Merge branch 'master' of github.com:javascript-tutorial/en.javascript.info into sync-5e9eca37

Author: iliakan

1-js/04-object-basics/04-object-methods/article.md

@@ -257,9 +257,9 @@ user.hi(); // John (the simple call works)
 */!*
 ```
 
-On the last line there is a conditinal operator that chooses either `user.hi` or `user.bye`. In this case the result is `user.hi`.
+On the last line there is a conditional operator that chooses either `user.hi` or `user.bye`. In this case the result is `user.hi`.
 
-Then the method is immediately called with parentheses `()`. But it doesn't work right!
+Then the method is immediately called with parentheses `()`. But it doesn't work correctly!
 
 As you can see, the call results in an error, because the value of `"this"` inside the call becomes `undefined`.
 

1-js/04-object-basics/05-object-toprimitive/article.md

@@ -3,7 +3,7 @@
 
 What happens when objects are added `obj1 + obj2`, subtracted `obj1 - obj2` or printed using `alert(obj)`?
 
-In that case objects are auto-converted to primitives, and then the operation is carried out.
+In that case, objects are auto-converted to primitives, and then the operation is carried out.
 
 In the chapter <info:type-conversions> we've seen the rules for numeric, string and boolean conversions of primitives. But we left a gap for objects. Now, as we know about methods and symbols it becomes possible to fill it.
 
@@ -138,7 +138,7 @@ alert(+user); // valueOf -> 1000
 alert(user + 500); // valueOf -> 1500
 ```
 
-Often we want a single "catch-all" place to handle all primitive conversions. In this case we can implement `toString` only, like this:
+Often we want a single "catch-all" place to handle all primitive conversions. In this case, we can implement `toString` only, like this:
 
 ```js run
 let user = {

1-js/06-advanced-functions/03-closure/article.md

@@ -599,7 +599,7 @@ function f() {
 }
 
 let g = f(); // while g is alive
-// there corresponding Lexical Environment lives
+// their corresponding Lexical Environment lives
 
 g = null; // ...and now the memory is cleaned up
 ```

1-js/06-advanced-functions/04-var/article.md

@@ -31,7 +31,7 @@ alert(phrase); // Error, phrase is not defined
 
 ## "var" has no block scope
 
-`var` variables are either function-wide or global, they are visible through blocks.
+Variables, declared with `var`, are either function-wide or global. They are visible through blocks.
 
 For instance:
 
@@ -45,7 +45,7 @@ alert(test); // true, the variable lives after if
 */!*
 ```
 
-`var` ignores code blocks, so we've got a global variable `test`.
+As `var` ignores code blocks, we've got a global variable `test`.
 
 If we used `let test` instead of `var test`, then the variable would only be visible inside `if`:
 

1-js/06-advanced-functions/08-settimeout-setinterval/article.md

@@ -9,7 +9,6 @@ There are two methods for it:
 
 These methods are not a part of JavaScript specification. But most environments have the internal scheduler and provide these methods. In particular, they are supported in all browsers and Node.js.
 
-
 ## setTimeout
 
 The syntax:
@@ -291,9 +290,9 @@ For server-side JavaScript, that limitation does not exist, and there exist othe
 - To cancel the execution, we should call `clearInterval/clearTimeout` with the value returned by `setInterval/setTimeout`.
 - Nested `setTimeout` calls is a more flexible alternative to `setInterval`. Also they can guarantee the minimal time *between* the executions.
 - Zero delay scheduling with `setTimeout(func, 0)` (the same as `setTimeout(func)`) is used to schedule the call "as soon as possible, but after the current code is complete".
-- The browsere ensures that for five or more nested call of `setTimeout`, or for zero-delay `setInterval`, the real delay between calls is at least 4ms. That's for historical reasons.
+- The browser limits the minimal delay for five or more nested call of `setTimeout` or for `setInterval` (after 5th call) to 4ms. That's for historical reasons.
 
-Please note that all scheduling methods do not *guarantee* the exact delay. We should not rely on that in the scheduled code.
+Please note that all scheduling methods do not *guarantee* the exact delay. 
 
 For example, the in-browser timer may slow down for a lot of reasons:
 - The CPU is overloaded.

1-js/07-object-properties/01-property-descriptors/article.md

@@ -122,7 +122,7 @@ user.name = "Pete"; // Error: Cannot assign to read only property 'name'...
 
 Now no one can change the name of our user, unless they apply their own `defineProperty` to override ours.
 
-```smart header="Errors appear only in use strict"
+```smart header="Errors appear only in strict mode"
 In the non-strict mode, no errors occur when writing to read-only properties and such. But the operation still won't succeed. Flag-violating actions are just silently ignored in non-strict.
 ```
 

1-js/08-prototypes/04-prototype-methods/article.md

@@ -194,7 +194,7 @@ let clone = Object.create(Object.getPrototypeOf(obj), Object.getOwnPropertyDescr
 - [Object.getOwnPropertySymbols(obj)](mdn:js/Object/getOwnPropertySymbols) -- returns an array of all own symbolic keys.
 - [Object.getOwnPropertyNames(obj)](mdn:js/Object/getOwnPropertyNames) -- returns an array of all own string keys.
 - [Reflect.ownKeys(obj)](mdn:js/Reflect/ownKeys) -- returns an array of all own keys.
-- [obj.hasOwnProperty(key)](mdn:js/Object/hasOwnProperty): it returns `true` if `obj` has its own (not inherited) keytt named `key`.
+- [obj.hasOwnProperty(key)](mdn:js/Object/hasOwnProperty): it returns `true` if `obj` has its own (not inherited) key named `key`.
 
 We also made it clear that `__proto__` is a getter/setter for `[[Prototype]]` and resides in `Object.prototype`, just as other methods.
 

1-js/09-classes/05-extend-natives/article.md

@@ -34,7 +34,7 @@ Even more, we can customize that behavior.
 
 We can add a special static getter `Symbol.species` to the class. If exists, it should return the constructor that JavaScript will use internally to create new entities in `map`, `filter` and so on.
 
-If we'd like built-in methods like `map`, `filter` will return regular arrays, we can return `Array` in `Symbol.species`, like here:
+If we'd like built-in methods like `map` or `filter` to return regular arrays, we can return `Array` in `Symbol.species`, like here:
 
 ```js run
 class PowerArray extends Array {
@@ -79,7 +79,7 @@ So, if `Rabbit extends Animal`, then:
 
 That's thoroughly explained in the chapter [](info:static-properties-methods#statics-and-inheritance).
 
-But built-in classes are an exception. They don't inherit statics `(1)` from each other.
+But built-in classes are an exception. They don't inherit statics from each other.
 
 For example, both `Array` and `Date` inherit from `Object`, so their instances have methods from `Object.prototype`. But  `Array.[[Prototype]]` does not point to `Object`. So there's `Object.keys()`, but not `Array.keys()` and `Date.keys()`.
 

1-js/09-classes/06-instanceof/article.md

@@ -46,7 +46,7 @@ alert( arr instanceof Object ); // true
 
 Please note that `arr` also belongs to the `Object` class. That's because `Array` prototypally inherits from `Object`.
 
-The `instanceof` operator examines the prototype chain for the check, but we can set a custom logic the static method `Symbol.hasInstance`.
+The `instanceof` operator examines the prototype chain for the check, but we can set a custom logic in the static method `Symbol.hasInstance`.
 
 The algorithm of `obj instanceof Class` works roughly as follows:
 

1-js/11-async/05-promise-api/article.md

@@ -112,7 +112,7 @@ Promise.all(requests)
   ));
 ```
 
-A bigger example with fetching user information for an array of github users by their names (or we could fetch an array of goods by their ids, the logic is same):
+A bigger example with fetching user information for an array of GitHub users by their names (we could fetch an array of goods by their ids, the logic is same):
 
 ```js run
 let names = ['iliakan', 'remy', 'jeresig'];
@@ -134,7 +134,7 @@ Promise.all(requests)
   .then(users => users.forEach(user => alert(user.name)));
 ```
 
-**If any of the promises is rejected, `Promise.all` immediately rejects with that error.**
+**If any of the promises is rejected, the promise returned by `Promise.all` immediately rejects with that error.**
 
 For instance:
 
@@ -155,10 +155,10 @@ If one promise rejects, `Promise.all` immediately rejects, completely forgetting
 
 For example, if there are multiple `fetch` calls, like in the example above, and one fails, other ones will still continue to execute, but `Promise.all` don't watch them any more. They will probably settle, but the result will be ignored.
 
-`Promise.all` does nothing to cancel them, as there's no concept of "cancellation" in promises. In [another chapter](fetch-abort) we'll cover `AbortController` that aims to help with that, but it's not a part of the Promise API.
+`Promise.all` does nothing to cancel them, as there's no concept of "cancellation" in promises. In [another chapter](info:fetch-abort) we'll cover `AbortController` that can help with that, but it's not a part of the Promise API.
 ```
 
-````smart header="`Promise.all(...)` allows non-promise items in `iterable`"
+````smart header="`Promise.all(iterable)` allows non-promise \"regular\" values in `iterable`"
 Normally, `Promise.all(...)` accepts an iterable (in most cases an array) of promises. But if any of those objects is not a promise, it's wrapped in `Promise.resolve`.
 
 For instance, here the results are `[1, 2, 3]`:
@@ -173,8 +173,7 @@ Promise.all([
 ]).then(alert); // 1, 2, 3
 ```
 
-So we are able to pass non-promise values to `Promise.all` where convenient.
-
+So we are able to pass ready values to `Promise.all` where convenient.
 ````
 
 ## Promise.allSettled
@@ -289,4 +288,4 @@ There are 5 static methods of `Promise` class:
     - `value` (if fulfilled) or `reason` (if rejected).
 5. `Promise.race(promises)` -- waits for the first promise to settle, and its result/error becomes the outcome.
 
-Of these five, `Promise.all/allSettled` are the most common in practice.
+Of these five, `Promise.all` is probably the most common in practice.

1-js/11-async/07-microtask-queue/article.md

@@ -21,7 +21,7 @@ That's strange, because the promise is definitely done from the beginning.
 
 Why did the `.then` trigger afterwards? What's going on?
 
-## Microtasks
+## Microtasks queue
 
 Asynchronous tasks need proper management. For that, the standard specifies an internal queue `PromiseJobs`, more often referred to as "microtask queue" (v8 term).
 
@@ -68,7 +68,7 @@ let promise = Promise.reject(new Error("Promise Failed!"));
 promise.catch(err => alert('caught'));
 */!*
 
-// no error, all quiet
+// doesn't run: error handled
 window.addEventListener('unhandledrejection', event => alert(event.reason));
 ```
 
@@ -93,13 +93,13 @@ setTimeout(() => promise.catch(err => alert('caught')), 1000);
 window.addEventListener('unhandledrejection', event => alert(event.reason));
 ```
 
-Now, if you run it, we'll see `Promise Failed!` message first, and then `caught`.
+Now, if you run it, we'll see `Promise Failed!` message first, and then `caught`. 
 
-If we didn't know about microtasks, we could wonder: "Why did `unhandledrejection` happen? We did catch the error!".
+If we didn't know about microtasks queue, we could wonder: "Why did `unhandledrejection` handler run? We did catch the error!".
 
-But now we do know that `unhandledrejection` is generated when the microtask queue is complete: the engine examines promises and, if any of them is in "rejected" state, then the event triggers.
+But now we understand that `unhandledrejection` is generated when the microtask queue is complete: the engine examines promises and, if any of them is in "rejected" state, then the event triggers.
 
-...By the way, the `.catch` added by `setTimeout` also triggers, of course it does, but later, after `unhandledrejection` has already occurred.
+In the example above, `.catch` added by `setTimeout` also triggers, but later, after `unhandledrejection` has already occurred, so that doesn't change anything.
 
 ## Summary
 

2-ui/1-document/09-size-and-scroll/article.md

@@ -39,7 +39,9 @@ So, without scrollbar the content width would be `300px`, but if the scrollbar i
 ```
 
 ```smart header="The `padding-bottom` area may be filled with text"
-Usually paddings are shown empty on illustrations, but if there's a lot of text in the element and it overflows, then browsers show the "overflowing" text at `padding-bottom`, so you can see that in examples. Still, the padding is set in further examples, unless explicitly specified otherwise.
+Usually paddings are shown empty on illustrations, but if there's a lot of text in the element and it overflows, then browsers show the "overflowing" text at `padding-bottom`.
+
+That's a note to avoid confusion, as `padding-bottom` is set in further examples, unless explicitly specified otherwise.
 ```
 
 ## Geometry
@@ -66,7 +68,7 @@ That's the nearest ancestor, that satisfies following conditions:
 2. or `<td>`, `<th>`, `<table>`,
 2. or `<body>`.
 
-In most practical cases `offsetParent` is exactly the nearest ancestor, that is CSS-positioned. And `offsetLeft/offsetTop` provide x/y coordinates relative to its upper-left corner.
+Properties `offsetLeft/offsetTop` provide x/y coordinates relative to its upper-left corner.
 
 In the example below the inner `<div>` has `<main>` as `offsetParent` and `offsetLeft/offsetTop` shifts from its upper-left corner (`180`):
 
@@ -105,7 +107,7 @@ For our sample element:
 - `offsetWidth = 390` -- the outer width, can be calculated as inner CSS-width (`300px`) plus paddings (`2 * 20px`) and borders (`2 * 25px`).
 - `offsetHeight = 290` -- the outer height.
 
-````smart header="Geometry properties for not displayed elements are zero/null"
+````smart header="Geometry properties are zero/null for elements that are not displayed"
 Geometry properties are calculated only for displayed elements.
 
 If an element (or any of its ancestors) has `display:none` or is not in the document, then all geometry properties are zero (or `null` if that's `offsetParent`).

2-ui/2-events/02-bubbling-and-capturing/article.md

@@ -130,7 +130,7 @@ Here's the picture of a click on `<td>` inside a table, taken from the specifica
 
 ![](eventflow.png)
 
-That is: for a click on `<td>` the event first goes through the ancestors chain down to the element (capturing), then it reaches the target, and then it goes up (bubbles), calling handlers on its way.
+That is: for a click on `<td>` the event first goes through the ancestors chain down to the element (capturing phase), then it reaches the target and triggers there (target phase), and then it goes up (bubbling phase), calling handlers on its way.
 
 **Before we only talked about bubbling, because the capturing phase is rarely used. Normally it is invisible to us.**
 
@@ -149,6 +149,7 @@ There are two possible values of the `capture` option:
 - If it's `false` (default), then the handler is set on the bubbling phase.
 - If it's `true`, then the handler is set on the capturing phase.
 
+
 Note that while formally there are 3 phases, the 2nd phase ("target phase": the event reached the element) is not handled separately: handlers on both capturing and bubbling phases trigger at that phase.
 
 Let's see both capturing and bubbling in action:
@@ -179,30 +180,39 @@ The code sets click handlers on *every* element in the document to see which one
 
 If you click on `<p>`, then the sequence is:
 
-1. `HTML` -> `BODY` -> `FORM` -> `DIV` -> `P` (capturing phase, the first listener), and then:
-2. `P` -> `DIV` -> `FORM` -> `BODY` -> `HTML` (bubbling phase, the second listener).
-
-Please note that `P` shows up two times: at the end of capturing and at the start of bubbling.
+1. `HTML` -> `BODY` -> `FORM` -> `DIV` (capturing phase, the first listener):
+2. `P` (target phrase, triggers two times, as we've set two listeners: capturing and bubbling)
+3. `DIV` -> `FORM` -> `BODY` -> `HTML` (bubbling phase, the second listener).
 
 There's a property `event.eventPhase` that tells us the number of the phase on which the event was caught. But it's rarely used, because we usually know it in the handler.
 
 ```smart header="To remove the handler, `removeEventListener` needs the same phase"
 If we `addEventListener(..., true)`, then we should mention the same phase in `removeEventListener(..., true)` to correctly remove the handler.
 ```
 
+````smart header="Listeners on same element and same phase run in their set order"
+If we have multiple event handlers on the same phase, assigned to the same element with `addEventListener`, they run in the same order as they are created:
+
+```js
+elem.addEventListener("click", e => alert(1)); // guaranteed to trigger first
+elem.addEventListener("click", e => alert(2));
+```
+````
+
+
 ## Summary
 
-The event handling process:
+When an event happens -- the most nested element where it happens gets labeled as the "target element" (`event.target`).
 
-- When an event happens -- the most nested element where it happens gets labeled as the "target element" (`event.target`).
-- Then the event first moves from the document root down to the `event.target`, calling handlers assigned with `addEventListener(...., true)` on the way (`true` is a shorthand for `{capture: true}`).
-- Then the event moves from `event.target` up to the root, calling handlers assigned using  `on<event>` and `addEventListener` without the 3rd argument or with the 3rd argument `false`.
+- Then the event moves down from the document root to `event.target`, calling handlers assigned with `addEventListener(...., true)` on the way (`true` is a shorthand for `{capture: true}`).
+- Then handlers are called on the target element itself.
+- Then the event bubbles up from `event.target` up to the root, calling handlers assigned using `on<event>` and `addEventListener` without the 3rd argument or with the 3rd argument `false/{capture:false}`.
 
 Each handler can access `event` object properties:
 
 - `event.target` -- the deepest element that originated the event.
 - `event.currentTarget` (=`this`) -- the current element that handles the event (the one that has the handler on it)
-- `event.eventPhase` -- the current phase (capturing=1, bubbling=3).
+- `event.eventPhase` -- the current phase (capturing=1, target=2, bubbling=3).
 
 Any event handler can stop the event by calling `event.stopPropagation()`, but that's not recommended, because we can't really be sure we won't need it above, maybe for completely different things.
 

2-ui/4-forms-controls/3-events-change-input/article.md

@@ -29,7 +29,7 @@ For other elements: `select`, `input type=checkbox/radio` it triggers right afte
 
 ## Event: input
 
-The `input` event triggers every time after a value is modified.
+The `input` event triggers every time after a value is modified by the user.
 
 Unlike keyboard events, it triggers on any value change, even those that does not involve keyboard actions: pasting with a mouse or using speech recognition to dictate the text.
 

2-ui/5-loading/01-onload-ondomcontentloaded/article.md

@@ -150,12 +150,12 @@ window.addEventListener("unload", function() {
 ```
 
 - The request is sent as POST.
-- We can send not only a string, but also forms and other formats, as described in the chapter <info:fetch-basics>, but usually it's a stringified object.
+- We can send not only a string, but also forms and other formats, as described in the chapter <info:fetch>, but usually it's a stringified object.
 - The data is limited by 64kb.
 
 When the `sendBeacon` request is finished, the browser probably has already left the document, so there's no way to get server response (which is usually empty for analytics).
 
-There's also a `keepalive` flag for doing such "after-page-left" requests in  [fetch](info:fetch-basics) method for generic network requests. You can find more information in the chapter <info:fetch-api>.
+There's also a `keepalive` flag for doing such "after-page-left" requests in  [fetch](info:fetch) method for generic network requests. You can find more information in the chapter <info:fetch-api>.
 
 
 If we want to cancel the transition to another page, we can't do it here. But we can use  another event -- `onbeforeunload`.

2-ui/99-ui-misc/01-mutation-observer/article.md

@@ -130,7 +130,7 @@ let hello = "world";
 
 Everything's simple so far, right? There are `<pre>` code snippets in HTML, we highlight them.
 
-Now let's go on. Let's say we're going to dynamically fetch materials from a server. We'll study methods for that [later in the tutorial](info:fetch-basics). For now it only matters that we fetch an HTML article from a webserver and display it on demand:
+Now let's go on. Let's say we're going to dynamically fetch materials from a server. We'll study methods for that [later in the tutorial](info:fetch). For now it only matters that we fetch an HTML article from a webserver and display it on demand:
 
 ```js
 let article = /* fetch new content from server */