Merge pull request #2 from javascript-tutorial/sync-2b5ac971

Sync with upstream @ 2b5ac97

Author: zaicevas

1-js/01-getting-started/1-intro/article.md

@@ -38,7 +38,11 @@ Varikliai yra sudėtingi daiktai, bet basic'ai yra paprasti.
 2. Konvertuoja ("kompiliuoja") skriptą į mašininį kodą.
 3. Vykdomas mašininis kodas.
 
+<<<<<<< HEAD
 Varikliai optimizuoja kodą kiekviename žingsnyje. Jie netgi stebi sukompiliuotą skriptą, kuomet jis vykdomas, bei analizuoja duomenis, kurie jame naudojami, ir pagal tai taiko papildomas optimizacijas. Po viso šio procesio, skriptai yra vykdomi gan greitai.
+=======
+The engine applies optimizations at each step of the process. It even watches the compiled script as it runs, analyzes the data that flows through it, and further optimizes the machine code based on that knowledge.
+>>>>>>> 2b5ac971c1bd8abe7b17cdcf724afd84799b6cbd
 ```
 
 ## Ką gali JavaScript'as padaryti naršyklėje?

1-js/02-first-steps/15-function-expressions-arrows/article.md renamed to 1-js/02-first-steps/15-function-expressions/article.md

@@ -1,4 +1,4 @@
-# Function expressions and arrows
+# Function expressions
 
 In JavaScript, a function is not a "magical language structure", but a special kind of value.
 
@@ -355,107 +355,6 @@ That's also better for readability, as it's easier to look up `function f(…) {
 ...But if a Function Declaration does not suit us for some reason, or we need a conditional declaration (we've just seen an example), then Function Expression should be used.
 ```
 
-
-## Arrow functions [#arrow-functions]
-
-There's one more very simple and concise syntax for creating functions, that's often better than Function Expressions. It's called "arrow functions", because it looks like this:
-
-
-```js
-let func = (arg1, arg2, ...argN) => expression
-```
-
-...This creates a function `func` that has arguments `arg1..argN`, evaluates the `expression` on the right side with their use and returns its result.
-
-In other words, it's roughly the same as:
-
-```js
-let func = function(arg1, arg2, ...argN) {
-  return expression;
-};
-```
-
-...But much more concise.
-
-Let's see an example:
-
-```js run
-let sum = (a, b) => a + b;
-
-/* The arrow function is a shorter form of:
-
-let sum = function(a, b) {
-  return a + b;
-};
-*/
-
-alert( sum(1, 2) ); // 3
-
-```
-
-If we have only one argument, then parentheses around parameters can be omitted, making that even shorter:
-
-```js run
-// same as
-// let double = function(n) { return n * 2 }
-*!*
-let double = n => n * 2;
-*/!*
-
-alert( double(3) ); // 6
-```
-
-If there are no arguments, parentheses should be empty (but they should be present):
-
-```js run
-let sayHi = () => alert("Hello!");
-
-sayHi();
-```
-
-Arrow functions can be used in the same way as Function Expressions.
-
-For instance, here's the rewritten example with `welcome()`:
-
-```js run
-let age = prompt("What is your age?", 18);
-
-let welcome = (age < 18) ?
-  () => alert('Hello') :
-  () => alert("Greetings!");
-
-welcome(); // ok now
-```
-
-Arrow functions may appear unfamiliar and not very readable at first, but that quickly changes as the eyes get used to the structure.
-
-They are very convenient for simple one-line actions, when we're just too lazy to write many words.
-
-```smart header="Multiline arrow functions"
-
-The examples above took arguments from the left of `=>` and evaluated the right-side expression with them.
-
-Sometimes we need something a little bit more complex, like multiple expressions or statements. It is also possible, but we should enclose them in curly braces. Then use a normal `return` within them.
-
-Like this:
-
-```js run
-let sum = (a, b) => {  // the curly brace opens a multiline function
-  let result = a + b;
-*!*
-  return result; // if we use curly braces, use return to get results
-*/!*
-};
-
-alert( sum(1, 2) ); // 3
-```
-
-```smart header="More to come"
-Here we praised arrow functions for brevity. But that's not all! Arrow functions have other interesting features. We'll return to them later in the chapter <info:arrow-functions>.
-
-For now, we can already use arrow functions for one-line actions and callbacks.
-```
-
 ## Summary
 
 - Functions are values. They can be assigned, copied or declared in any place of the code.
@@ -467,8 +366,3 @@ For now, we can already use arrow functions for one-line actions and callbacks.
 In most cases when we need to declare a function, a Function Declaration is preferable, because it is visible prior to the declaration itself. That gives us more flexibility in code organization, and is usually more readable.
 
 So we should use a Function Expression only when a Function Declaration is not fit for the task. We've seen a couple of examples of that in this chapter, and will see more in the future.
-
-Arrow functions are handy for one-liners. They come in two flavors:
-
-1. Without curly braces: `(...args) => expression` -- the right side is an expression: the function evaluates it and returns the result.
-2. With curly braces: `(...args) => { body }` -- brackets allow us to write multiple statements inside the function, but we need an explicit `return` to return something.

1-js/02-first-steps/15-function-expressions-arrows/1-rewrite-arrow/solution.md renamed to 1-js/02-first-steps/16-arrow-functions-basics/1-rewrite-arrow/solution.md

@@ -1,7 +1,7 @@
 
 # Rewrite with arrow functions
 
-Replace Function Expressions with arrow functions in the code:
+Replace Function Expressions with arrow functions in the code below:
 
 ```js run
 function ask(question, yes, no) {

1-js/02-first-steps/15-function-expressions-arrows/1-rewrite-arrow/task.md renamed to 1-js/02-first-steps/16-arrow-functions-basics/1-rewrite-arrow/task.md

@@ -0,0 +1,111 @@
+# Arrow functions, the basics
+
+There's another very simple and concise syntax for creating functions, that's often better than Function Expressions.
+
+It's called "arrow functions", because it looks like this:
+
+```js
+let func = (arg1, arg2, ...argN) => expression
+```
+
+...This creates a function `func` that accepts arguments `arg1..argN`, then evaluates the `expression` on the right side with their use and returns its result.
+
+In other words, it's the shorter version of:
+
+```js
+let func = function(arg1, arg2, ...argN) {
+  return expression;
+};
+```
+
+Let's see a concrete example:
+
+```js run
+let sum = (a, b) => a + b;
+
+/* This arrow function is a shorter form of:
+
+let sum = function(a, b) {
+  return a + b;
+};
+*/
+
+alert( sum(1, 2) ); // 3
+```
+
+As you can, see `(a, b) => a + b` means a function that accepts two arguments named `a` and `b`. Upon the execution, it evaluates the expression `a + b` and returns the result.
+
+- If we have only one argument, then parentheses around parameters can be omitted, making that even shorter.
+
+    For example:
+
+    ```js run
+    *!*
+    let double = n => n * 2;
+    // roughly the same as: let double = function(n) { return n * 2 }
+    */!*
+
+    alert( double(3) ); // 6
+    ```
+
+- If there are no arguments, parentheses will be empty (but they should be present):
+
+    ```js run
+    let sayHi = () => alert("Hello!");
+
+    sayHi();
+    ```
+
+Arrow functions can be used in the same way as Function Expressions.
+
+For instance, to dynamically create a function:
+
+```js run
+let age = prompt("What is your age?", 18);
+
+let welcome = (age < 18) ?
+  () => alert('Hello') :
+  () => alert("Greetings!");
+
+welcome(); // ok now
+```
+
+Arrow functions may appear unfamiliar and not very readable at first, but that quickly changes as the eyes get used to the structure.
+
+They are very convenient for simple one-line actions, when we're just too lazy to write many words.
+
+## Multiline arrow functions
+
+The examples above took arguments from the left of `=>` and evaluated the right-side expression with them.
+
+Sometimes we need something a little bit more complex, like multiple expressions or statements. It is also possible, but we should enclose them in curly braces. Then use a normal `return` within them.
+
+Like this:
+
+```js run
+let sum = (a, b) => {  // the curly brace opens a multiline function
+  let result = a + b;
+*!*
+  return result; // if we use curly braces, then we need an explicit "return" 
+*/!*
+};
+
+alert( sum(1, 2) ); // 3
+```
+
+```smart header="More to come"
+Here we praised arrow functions for brevity. But that's not all!
+
+Arrow functions have other interesting features.
+
+To study them in-depth, we first need to get to know some other aspects of JavaScript, so we'll return to arrow functions later in the chapter <info:arrow-functions>.
+
+For now, we can already use arrow functions for one-line actions and callbacks.
+```
+
+## Summary
+
+Arrow functions are handy for one-liners. They come in two flavors:
+
+1. Without curly braces: `(...args) => expression` -- the right side is an expression: the function evaluates it and returns the result.
+2. With curly braces: `(...args) => { body }` -- brackets allow us to write multiple statements inside the function, but we need an explicit `return` to return something.

1-js/02-first-steps/16-arrow-functions-basics/article.md

@@ -272,7 +272,7 @@ We covered three ways to create a function in JavaScript:
 - Parameters can have default values: `function sum(a = 1, b = 2) {...}`.
 - Functions always return something. If there's no `return` statement, then the result is `undefined`.
 
-Details: see <info:function-basics>, <info:function-expressions-arrows>.
+Details: see <info:function-basics>, <info:arrow-functions-basics>.
 
 ## More to come
 

1-js/02-first-steps/16-javascript-specials/article.md renamed to 1-js/02-first-steps/17-javascript-specials/article.md

@@ -123,7 +123,7 @@ These methods must return a primitive value. If `toString` or `valueOf` returns
 By default, a plain object has following `toString` and `valueOf` methods:
 
 - The `toString` method returns a string `"[object Object]"`.
-- The `valueOf` method returns an object itself.
+- The `valueOf` method returns the object itself.
 
 Here's the demo:
 
@@ -199,7 +199,7 @@ In contrast, `Symbol.toPrimitive` *must* return a primitive, otherwise there wil
 
 ## Further conversions
 
-As we know already, many operators and functions perform type conversions, e.g. multiplication `*` converts operatnds to numbers.
+As we know already, many operators and functions perform type conversions, e.g. multiplication `*` converts operands to numbers.
 
 If we pass an object as an argument, then there are two stages:
 1. The object is converted to a primitive (using the rules described above).

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

@@ -447,7 +447,7 @@ alert(arr);  // *!*1, 2, 15*/!*
 ````
 
 ````smart header="Arrow functions for the best"
-Remember [arrow functions](info:function-expressions-arrows#arrow-functions)? We can use them here for neater sorting:
+Remember [arrow functions](info:arrow-functions-basics)? We can use them here for neater sorting:
 
 ```js
 arr.sort( (a, b) => a - b );

1-js/05-data-types/05-array-methods/article.md

@@ -214,7 +214,7 @@ let arr = Array.from(arrayLike); // (*)
 alert(arr.pop()); // World (method works)
 ```
 
-`Array.from` at the line `(*)` takes the object, examines it for being an iterable or array-like, then makes a new array and copies there all items.
+`Array.from` at the line `(*)` takes the object, examines it for being an iterable or array-like, then makes a new array and copies all items to it.
 
 The same happens for an iterable:
 

1-js/05-data-types/06-iterable/article.md

@@ -33,6 +33,13 @@ To create a new `Date` object call `new Date()` with one of the following argume
 
     It's a lightweight numeric representation of a date. We can always create a date from a timestamp using `new Date(timestamp)` and convert the existing `Date` object to a timestamp using the `date.getTime()` method (see below).
 
+    Dates before 01.01.1970 have negative timestamps, e.g.:
+    ```js run
+    // 31 Dec 1969
+    let Dec31_1969 = new Date(-24 * 3600 * 1000);
+    alert( Dec31_1969 );
+    ```
+
 `new Date(datestring)`
 : If there is a single argument, and it's a string, then it is parsed automatically. The algorithm is the same as `Date.parse` uses, we'll cover it later.
 

1-js/05-data-types/11-date/article.md

@@ -116,9 +116,9 @@ alert(User.prototype.sayHi); // alert(this.name);
 alert(Object.getOwnPropertyNames(User.prototype)); // constructor, sayHi
 ```
 
-## Not just a syntax sugar
+## Not just a syntactic sugar
 
-Sometimes people say that `class` is a "syntax sugar" (syntax that is designed to make things easier to read, but doesn't introduce anything new), because we could actually declare the same without `class` keyword at all:
+Sometimes people say that `class` is a "syntactic sugar" (syntax that is designed to make things easier to read, but doesn't introduce anything new), because we could actually declare the same without `class` keyword at all:
 
 ```js run
 // rewriting class User in pure functions
@@ -140,7 +140,7 @@ let user = new User("John");
 user.sayHi();
 ```
 
-The result of this definition is about the same. So, there are indeed reasons why `class` can be considered a syntax sugar to define a constructor together with its prototype methods.
+The result of this definition is about the same. So, there are indeed reasons why `class` can be considered a syntactic sugar to define a constructor together with its prototype methods.
 
 Still, there are important differences.
 
@@ -282,7 +282,7 @@ Object.defineProperties(User.prototype, {
 });
 ```
 
-Here's an example with a computed property in brackets `[...]`:
+Here's an example with a computed property name in brackets `[...]`:
 
 ```js run
 class User {
@@ -318,6 +318,9 @@ class User {
 }
 
 new User().sayHi();
+
+alert(User.prototype.sayHi); // placed in User.prototype
+alert(User.prototype.name); // undefined, not placed in User.prototype
 ```
 
 The property `name` is not placed into `User.prototype`. Instead, it is created by `new` before calling the constructor, it's a property of the object itself.

1-js/09-classes/01-class/article.md

@@ -40,7 +40,7 @@ The syntax to extend another class is: `class Child extends Parent`.
 
 Let's create `class Rabbit` that inherits from `Animal`:
 
-```js run
+```js
 *!*
 class Rabbit extends Animal {
 */!*

1-js/09-classes/02-class-inheritance/article.md

@@ -19,12 +19,14 @@ User.staticMethod(); // true
 
 That actually does the same as assigning it as a property directly:
 
-```js
+```js run
 class User() { }
 
 User.staticMethod = function() {
   alert(this === User);
 };
+
+User.staticMethod(); // true
 ```
 
 The value of `this` in `User.staticMethod()` call is the class constructor `User` itself (the "object before dot" rule).
@@ -123,14 +125,15 @@ That is the same as a direct assignment to `Article`:
 Article.publisher = "Ilya Kantor";
 ```
 
-## Inheritance of static methods
+## Inheritance of static properties and methods
 
-Static methods are inherited.
+Static properties and methods are inherited.
 
-For instance, `Animal.compare` in the code below is inherited and accessible as `Rabbit.compare`:
+For instance, `Animal.compare` and `Animal.planet` in the code below are inherited and accessible as `Rabbit.compare` and `Rabbit.planet`:
 
 ```js run
 class Animal {
+  static planet = "Earth";
 
   constructor(name, speed) {
     this.speed = speed;
@@ -167,6 +170,8 @@ rabbits.sort(Rabbit.compare);
 */!*
 
 rabbits[0].run(); // Black Rabbit runs with speed 5.
+
+alert(Rabbit.planet); // Earth
 ```
 
 Now when we call `Rabbit.compare`, the inherited `Animal.compare` will be called.

1-js/09-classes/03-static-properties-methods/article.md

@@ -3,11 +3,11 @@
 
 There are many areas where we need random data.
 
-One of them is testing. We may need random data: text, numbers etc, to test things out well.
+One of them is testing. We may need random data: text, numbers, etc. to test things out well.
 
 In JavaScript, we could use `Math.random()`. But if something goes wrong, we'd like to be able to repeat the test, using exactly the same data.
 
-For that, so called "seeded pseudo-random generators" are used. They take a "seed", the first value, and then generate next ones using a formula. So that the same seed yields the same sequence, and hence the whole flow is easily reproducible. We only need to remember the seed to repeat it.
+For that, so called "seeded pseudo-random generators" are used. They take a "seed", the first value, and then generate the next ones using a formula so that the same seed yields the same sequence, and hence the whole flow is easily reproducible. We only need to remember the seed to repeat it.
 
 An example of such formula, that generates somewhat uniformly distributed values:
 

1-js/12-generators-iterators/1-generators/01-pseudo-random-generator/task.md

@@ -40,7 +40,7 @@ The function code execution hasn't started yet:
 
 ![](generateSequence-1.svg)
 
-The main method of a generator is `next()`. When called, it runs the execution till the nearest `yield <value>` statement (`value` can be omitted, then it's `undefined`). Then the function execution pauses, and the yielded `value` is returned to the outer code.
+The main method of a generator is `next()`. When called, it runs the execution until the nearest `yield <value>` statement (`value` can be omitted, then it's `undefined`). Then the function execution pauses, and the yielded `value` is returned to the outer code.
 
 The result of `next()` is always an object with two properties:
 - `value`: the yielded value.
@@ -78,7 +78,7 @@ alert(JSON.stringify(two)); // {value: 2, done: false}
 
 ![](generateSequence-3.svg)
 
-And, if we call it the third time, then the execution reaches `return` statement that finishes the function:
+And, if we call it a third time, the execution reaches the `return` statement that finishes the function:
 
 ```js
 let three = generator.next();
@@ -90,7 +90,7 @@ alert(JSON.stringify(three)); // {value: 3, *!*done: true*/!*}
 
 Now the generator is done. We should see it from `done:true` and process `value:3` as the final result.
 
-New calls `generator.next()` don't make sense any more. If we do them, they return the same object: `{done: true}`.
+New calls to `generator.next()` don't make sense any more. If we do them, they return the same object: `{done: true}`.
 
 ```smart header="`function* f(…)` or `function *f(…)`?"
 Both syntaxes are correct.
@@ -154,7 +154,7 @@ let sequence = [0, ...generateSequence()];
 alert(sequence); // 0, 1, 2, 3
 ```
 
-In the code above, `...generateSequence()` turns the iterable generator object into array of items (read more about the spread operator in the chapter [](info:rest-parameters-spread-operator#spread-operator))
+In the code above, `...generateSequence()` turns the iterable generator object into an array of items (read more about the spread operator in the chapter [](info:rest-parameters-spread-operator#spread-operator))
 
 ## Using generators for iterables
 
@@ -212,17 +212,17 @@ alert( [...range] ); // 1,2,3,4,5
 ```
 
 That works, because `range[Symbol.iterator]()` now returns a generator, and generator methods are exactly what `for..of` expects:
-- it has `.next()` method
+- it has a `.next()` method
 - that returns values in the form `{value: ..., done: true/false}`
 
-That's not a coincidence, of course. Generators were added to JavaScript language with iterators in mind, to implement them easier.
+That's not a coincidence, of course. Generators were added to JavaScript language with iterators in mind, to implement them easily.
 
 The variant with a generator is much more concise than the original iterable code of `range`, and keeps the same functionality.
 
 ```smart header="Generators may generate values forever"
 In the examples above we generated finite sequences, but we can also make a generator that yields values forever. For instance, an unending sequence of pseudo-random numbers.
 
-That surely would require a `break` (or `return`) in `for..of` over such generator, otherwise the loop would repeat forever and hang.
+That surely would require a `break` (or `return`) in `for..of` over such generator. Otherwise, the loop would repeat forever and hang.
 ```
 
 ## Generator composition
@@ -237,7 +237,7 @@ function* generateSequence(start, end) {
 }
 ```
 
-Now we'd like to reuse it for generation of a more complex sequence:
+Now we'd like to reuse it to generate a more complex sequence:
 - first, digits `0..9` (with character codes 48..57),
 - followed by uppercase alphabet letters `A..Z` (character codes 65..90)
 - followed by lowercase alphabet letters `a..z` (character codes 97..122)
@@ -316,7 +316,7 @@ A generator composition is a natural way to insert a flow of one generator into
 
 ## "yield" is a two-way road
 
-Till this moment, generators were similar to iterable objects, with a special syntax to generate values. But in fact they are much more powerful and flexible.
+Until this moment, generators were similar to iterable objects, with a special syntax to generate values. But in fact they are much more powerful and flexible.
 
 That's because `yield` is a two-way road: it not only returns the result outside, but also can pass the value inside the generator.
 
@@ -422,7 +422,7 @@ generator.throw(new Error("The answer is not found in my database")); // (2)
 */!*
 ```
 
-The error, thrown into the generator at the line `(2)` leads to an exception in the line `(1)` with `yield`. In the example above, `try..catch` catches it and shows.
+The error, thrown into the generator at line `(2)` leads to an exception in line `(1)` with `yield`. In the example above, `try..catch` catches it and shows it.
 
 If we don't catch it, then just like any exception, it "falls out" the generator into the calling code.
 
@@ -456,6 +456,6 @@ If we don't catch the error there, then, as usual, it falls through to the outer
 
 In modern JavaScript, generators are rarely used. But sometimes they come in handy, because the ability of a function to exchange data with the calling code during the execution is quite unique. And, surely, they are great for making iterable objects.
 
-Also, in the next chapter we'll learn async generators, which are used to read streams of asynchronously generated data (e.g paginated fetches over a network) in `for await ... of` loop.
+Also, in the next chapter we'll learn async generators, which are used to read streams of asynchronously generated data (e.g paginated fetches over a network) in `for await ... of` loops.
 
 In web-programming we often work with streamed data, so that's another very important use case.

1-js/12-generators-iterators/1-generators/article.md

@@ -9,7 +9,7 @@ Let's see a simple example first, to grasp the syntax, and then review a real-li
 
 Asynchronous iterators are similar to regular iterators, with a few syntactic differences.
 
-"Regular" iterable object, as described in the chapter <info:iterable>, look like this:
+A "regular" iterable object, as described in the chapter <info:iterable>, looks like this:
 
 ```js run
 let range = {
@@ -79,8 +79,10 @@ let range = {
         // (automatically wrapped into a promise by async)
 */!*
 
+*!*
         // can use await inside, do async stuff:
         await new Promise(resolve => setTimeout(resolve, 1000)); // (3)
+*/!*
 
         if (this.current <= this.last) {
           return { done: false, value: this.current++ };
@@ -267,7 +269,7 @@ So far we've seen simple examples, to gain basic understanding. Now let's review
 
 There are many online services that deliver paginated data. For instance, when we need a list of users, a request returns a pre-defined count (e.g. 100 users) - "one page", and provides a URL to the next page.
 
-The pattern is very common, it's not about users, but just about anything. For instance, GitHub allows to retrieve commits in the same, paginated fashion:
+This pattern is very common. It's not about users, but just about anything. For instance, GitHub allows to retrieve commits in the same, paginated fashion:
 
 - We should make a request to URL in the form `https://api.github.com/repos/<repo>/commits`.
 - It responds with a JSON of 30 commits, and also provides a link to the next page in the `Link` header.
@@ -283,7 +285,7 @@ for await (let commit of fetchCommits(repo)) {
 }
 ```
 
-We'd like to make a function `fetchCommits(repo)` that gets commits for us, making requests whenever needed. And let it care about all pagination stuff, for us it'll be a simple `for await..of`.
+We'd like to make a function `fetchCommits(repo)` that gets commits for us, making requests whenever needed. And let it care about all pagination stuff. For us it'll be a simple `for await..of`.
 
 With async generators that's pretty easy to implement:
 

1-js/12-generators-iterators/2-async-iterators-generators/article.md

@@ -49,7 +49,7 @@ The `import` directive loads the module by path `./sayHi.js` relative the curren
 
 Let's run the example in-browser.
 
-As modules support special keywords and features, we must tell the browser that a script should be treated as module, by using the attribute `<script type="module">`.
+As modules support special keywords and features, we must tell the browser that a script should be treated as a module, by using the attribute `<script type="module">`.
 
 Like this:
 
@@ -165,7 +165,7 @@ So, let's reiterate -- the module is executed only once. Exports are generated,
 
 Such behavior allows to *configure* modules on first import. We can setup its properties once, and then in further imports it's ready.
 
-For instance, `admin.js` module may provide certain functionality, but expect the credentials to come into the `admin` object from outside:
+For instance, the `admin.js` module may provide certain functionality, but expect the credentials to come into the `admin` object from outside:
 
 ```js
 // 📁 admin.js
@@ -236,7 +236,7 @@ You may want skip this section for now if you're reading for the first time, or
 Module scripts are *always* deferred, same effect as `defer` attribute (described in the chapter [](info:script-async-defer)), for both external and inline scripts.
 
 In other words:
-- downloading of external module scripts `<script type="module" src="...">` doesn't block HTML processing, they load in parallel with other resources.
+- downloading external module scripts `<script type="module" src="...">` doesn't block HTML processing, they load in parallel with other resources.
 - module scripts wait until the HTML document is fully ready (even if they are tiny and load faster than HTML), and then run.
 - relative order of scripts is maintained: scripts that go first in the document, execute first.
 
@@ -264,21 +264,21 @@ Compare to regular script below:
 <button id="button">Button</button>
 ```
 
-Please note: the second script actually works before the first! So we'll see `undefined` first, and then `object`.
+Please note: the second script actually runs before the first! So we'll see `undefined` first, and then `object`.
 
-That's because modules are deferred, so we wait for the document to be processed. The regular scripts runs immediately, so we saw its output first.
+That's because modules are deferred, so we wait for the document to be processed. The regular script runs immediately, so we see its output first.
 
 When using modules, we should be aware that HTML-page shows up as it loads, and JavaScript modules run after that, so the user may see the page before the JavaScript application is ready. Some functionality may not work yet. We should put "loading indicators", or otherwise ensure that the visitor won't be confused by that.
 
 ### Async works on inline scripts
 
 For non-module scripts, `async` attribute only works on external scripts. Async scripts run immediately when ready, independently of other scripts or the HTML document.
 
-For module scripts, it works on any scripts.
+For module scripts, it works on inline scripts as well.
 
-For example, the script below has `async`, so it doesn't wait for anyone.
+For example, the inline script below has `async`, so it doesn't wait for anything.
 
-It performs the import (fetches `./analytics.js`) and runs when ready, even if HTML document is not finished yet, or if other scripts are still pending.
+It performs the import (fetches `./analytics.js`) and runs when ready, even if the HTML document is not finished yet, or if other scripts are still pending.
 
 That's good for functionality that doesn't depend on anything, like counters, ads, document-level event listeners.
 
@@ -296,7 +296,7 @@ That's good for functionality that doesn't depend on anything, like counters, ad
 
 External scripts that have `type="module"` are different in two aspects:
 
-1. External scripts with same `src` run only once:
+1. External scripts with the same `src` run only once:
     ```html
     <!-- the script my.js is fetched and executed only once -->
     <script type="module" src="my.js"></script>
@@ -322,11 +322,11 @@ import {sayHi} from 'sayHi'; // Error, "bare" module
 // the module must have a path, e.g. './sayHi.js' or wherever the module is
 ```
 
-Certain environments, like Node.js or bundle tools allow bare modules, without any path, as they have own ways for finding modules and hooks to fine-tune them. But browsers do not support bare modules yet.
+Certain environments, like Node.js or bundle tools allow bare modules, without any path, as they have their own ways for finding modules and hooks to fine-tune them. But browsers do not support bare modules yet.
 
 ### Compatibility, "nomodule"
 
-Old browsers do not understand `type="module"`. Scripts of the unknown type are just ignored. For them, it's possible to provide a fallback using `nomodule` attribute:
+Old browsers do not understand `type="module"`. Scripts of an unknown type are just ignored. For them, it's possible to provide a fallback using the `nomodule` attribute:
 
 ```html run
 <script type="module">
@@ -350,7 +350,7 @@ Build tools do the following:
 1. Take a "main" module, the one intended to be put in `<script type="module">` in HTML.
 2. Analyze its dependencies: imports and then imports of imports etc.
 3. Build a single file with all modules (or multiple files, that's tunable), replacing native `import` calls with bundler functions, so that it works. "Special" module types like HTML/CSS modules are also supported.
-4. In the process, other transforms and optimizations may be applied:
+4. In the process, other transformations and optimizations may be applied:
     - Unreachable code removed.
     - Unused exports removed ("tree-shaking").
     - Development-specific statements like `console` and `debugger` removed.
@@ -379,7 +379,7 @@ To summarize, the core concepts are:
 3. Modules always `use strict`.
 4. Module code is executed only once. Exports are created once and shared between importers.
 
-When we use modules, each module implements the functionality and exports it. Then we use `import` to directly import it where it's needed. Browser loads and evaluates the scripts automatically.
+When we use modules, each module implements the functionality and exports it. Then we use `import` to directly import it where it's needed. The browser loads and evaluates the scripts automatically.
 
 In production, people often use bundlers such as [Webpack](https://webpack.js.org) to bundle modules together for performance and other reasons.
 

1-js/13-modules/01-modules-intro/article.md

@@ -155,14 +155,14 @@ say.*!*bye*/!*('John'); // Bye, John!
 
 In practice, there are mainly two kinds of modules.
 
-1. Module that contains a library, pack of functions, like `say.js` above.
-2. Module that declares a single entity, e.g. a module `user.js` exports only `class User`.
+1. Modules that contain a library, pack of functions, like `say.js` above.
+2. Modules that declare a single entity, e.g. a module `user.js` exports only `class User`.
 
 Mostly, the second approach is preferred, so that every "thing" resides in its own module.
 
-Naturally, that requires a lot of files, as everything wants its own module, but that's not a problem at all. Actually, code navigation becomes easier, if files are well-named and structured into folders.
+Naturally, that requires a lot of files, as everything wants its own module, but that's not a problem at all. Actually, code navigation becomes easier if files are well-named and structured into folders.
 
-Modules provide special `export default` ("the default export") syntax to make "one thing per module" way look better.
+Modules provide special `export default` ("the default export") syntax to make the "one thing per module" way look better.
 
 Put `export default` before the entity to export:
 
@@ -291,7 +291,7 @@ import {User} from './user.js';
 ```js
 import User from './user.js'; // works
 import MyUser from './user.js'; // works too
-// could be import Anything..., and it'll be work
+// could be import Anything... and it'll still work
 ```
 
 So team members may use different names to import the same thing, and that's not good.
@@ -319,7 +319,7 @@ export {sayHi} from './say.js'; // re-export sayHi
 export {default as User} from './user.js'; // re-export default
 ```
 
-Why that may be needed? Let's see a practical use case.
+Why would that be needed? Let's see a practical use case.
 
 Imagine, we're writing a "package": a folder with a lot of modules, with some of the functionality exported outside (tools like NPM allow to publish and distribute such packages), and many modules are just "helpers", for the internal use in other package modules.
 
@@ -389,17 +389,17 @@ export default class User {
 
 1. `export User from './user.js'` won't work. What can go wrong?... But that's a syntax error!
 
-    To re-export the default export, we should write `export {default as User}`, as in the example above.    
+    To re-export the default export, we have to write `export {default as User}`, as in the example above.    
 
-2. `export * from './user.js'` re-exports only named exports, ignores the default one.
+2. `export * from './user.js'` re-exports only named exports, but ignores the default one.
 
     If we'd like to re-export both named and the default export, then two statements are needed:
     ```js
     export * from './user.js'; // to re-export named exports
     export {default} from './user.js'; // to re-export the default export
     ```
 
-Such oddities of re-exporting the default export is one of the reasons, why some developers don't like them.
+Such oddities of re-exporting the default export are one of the reasons why some developers don't like them.
 
 ## Summary
 

1-js/13-modules/02-import-export/article.md

@@ -593,7 +593,7 @@ Other traps exist: the full list is in the beginning of this chapter. Their usag
 
 `Reflect` is a built-in object that simplifies creation of `Proxy`.
 
-It was said previously that internal methods, such as `[[Get]]`, `[[Set]]` and others are specifiction only, they can't be called directly.
+It was said previously that internal methods, such as `[[Get]]`, `[[Set]]` and others are specification-only, they can't be called directly.
 
 The `Reflect` object makes that somewhat possible. Its methods are minimal wrappers around the internal methods.
 

1-js/99-js-misc/01-proxy/article.md

@@ -280,12 +280,12 @@ Till now we described the basic navigation properties.
 
 Certain types of DOM elements may provide additional properties, specific to their type, for convenience.
 
-Tables are a great example of that, and a particularly important case.
+Tables are a great example of that, and represent a particularly important case:
 
 **The `<table>`** element supports (in addition to the given above) these properties:
 - `table.rows` -- the collection of `<tr>` elements of the table.
 - `table.caption/tHead/tFoot` -- references to elements `<caption>`, `<thead>`, `<tfoot>`.
-- `table.tBodies` -- the collection of `<tbody>` elements (can be many according to the standard).
+- `table.tBodies` -- the collection of `<tbody>` elements (can be many according to the standard, but there will always be at least one -- even if it is not in the source HTML, the browser will put it in the DOM).
 
 **`<thead>`, `<tfoot>`, `<tbody>`** elements provide the `rows` property:
 - `tbody.rows` -- the collection of `<tr>` inside.

2-ui/1-document/03-dom-navigation/article.md

@@ -14,6 +14,6 @@ table.tBodies[0].append(...sortedRows);
 3. Then sort them comparing by the content of the first `<td>` (the name field).
 4. Now insert nodes in the right order by `.append(...sortedRows)`.
 
-    Tables always have an implicit <tbody> element, so we need to take it and insert into it: a simple `table.append(...)` would fail.
+    Tables always have an implicit `<tbody>` element, so we need to take it and insert into it: a simple `table.append(...)` would fail.
 
     Please note: we don't have to remove them, just "re-insert", they leave the old place automatically.

2-ui/1-document/07-modifying-document/12-sort-table/solution.md

@@ -4,7 +4,11 @@ importance: 1
 
 # Why does "aaa" remain?
 
-Run the example. Why does `table.remove()` not delete the text `"aaa"`?
+In the example below, the call `table.remove()` removes the table from the document.
+
+But if you run it, you can see that the text `"aaa"` is still visible.
+
+Why does that happen?
 
 ```html height=100 run
 <table id="table">

2-ui/1-document/07-modifying-document/5-why-aaa/task.md

@@ -282,7 +282,7 @@ Visited links may be colored using `:visited` CSS pseudoclass.
 
 But `getComputedStyle` does not give access to that color, because otherwise an arbitrary page could find out whether the user visited a link by creating it on the page and checking the styles.
 
-JavaScript may not see the styles applied by `:visited`. And also, there's a limitation in CSS that forbids to apply geometry-changing styles in `:visited`. That's to guarantee that there's no sideway for an evil page to test if a link was visited and hence to break the privacy.
+JavaScript may not see the styles applied by `:visited`. And also, there's a limitation in CSS that forbids applying geometry-changing styles in `:visited`. That's to guarantee that there's no side way for an evil page to test if a link was visited and hence to break the privacy.
 ```
 
 ## Summary

2-ui/1-document/08-styles-and-classes/article.md

@@ -4,7 +4,7 @@ importance: 5
 
 # What's the scroll from the bottom?
 
-The `elem.scrollTop` property is the size of the scrolled out part from the top. How to get the size from the bottom scroll (let's call it `scrollBottom`)?
+The `elem.scrollTop` property is the size of the scrolled out part from the top. How to get the size of the bottom scroll (let's call it `scrollBottom`)?
 
 Write the code that works for an arbitrary `elem`.
 

2-ui/1-document/09-size-and-scroll/1-get-scroll-height-bottom/task.md

@@ -55,13 +55,13 @@ Let's start exploring the properties starting from the outside of the element.
 
 These properties are rarely needed, but still they are the "most outer" geometry properties, so we'll start with them.
 
-The `offsetParent` is the nearest ancestor, that browser uses for calculating coordinates during rendering.
+The `offsetParent` is the nearest ancestor that the browser uses for calculating coordinates during rendering.
 
-That's the nearest ancestor, that satisfies following conditions:
+That's the nearest ancestor that is one of the following:
 
-1. CSS-positioned (`position` is `absolute`, `relative`, `fixed` or `sticky`),
-2. or `<td>`, `<th>`, `<table>`,
-2. or `<body>`.
+1. CSS-positioned (`position` is `absolute`, `relative`, `fixed` or `sticky`),  or
+2. `<td>`, `<th>`, or `<table>`,  or
+3. `<body>`.
 
 Properties `offsetLeft/offsetTop` provide x/y coordinates relative to `offsetParent` upper-left corner.
 
@@ -104,7 +104,7 @@ For our sample element:
 ````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`).
+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` for `offsetParent`).
 
 For example, `offsetParent` is `null`, and `offsetWidth`, `offsetHeight` are `0` when we created an element, but haven't inserted it into the document yet, or it (or it's ancestor) has `display:none`.
 
@@ -243,9 +243,9 @@ Why should we use geometry properties instead? There are two reasons:
     </script>
     ```
 
-    From the CSS standpoint, `width:auto` is perfectly normal, but in JavaScript we need an exact size in `px` that we can use in calculations. So here CSS width is useless at all.
+    From the CSS standpoint, `width:auto` is perfectly normal, but in JavaScript we need an exact size in `px` that we can use in calculations. So here CSS width is useless.
 
-And there's one more reason: a scrollbar. Sometimes the code that works fine without a scrollbar starts to bug with it, because a scrollbar takes the space from the content in some browsers. So the real width available for the content is *less* than CSS width. And `clientWidth/clientHeight` take that into account.
+And there's one more reason: a scrollbar. Sometimes the code that works fine without a scrollbar becomes buggy with it, because a scrollbar takes the space from the content in some browsers. So the real width available for the content is *less* than CSS width. And `clientWidth/clientHeight` take that into account.
 
 ...But with `getComputedStyle(elem).width` the situation is different. Some browsers (e.g. Chrome) return the real inner width, minus the scrollbar, and some of them (e.g. Firefox) -- CSS width (ignore the scrollbar). Such cross-browser differences is the reason not to use `getComputedStyle`, but rather rely on geometry properties.
 

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

@@ -1,8 +1,8 @@
 # Window sizes and scrolling
 
-How to find out the width and height of the browser window? How to get the full width and height of the document, including the scrolled out part? How to scroll the page using JavaScript?
+How do we find the width and height of the browser window? How do we get the full width and height of the document, including the scrolled out part? How do we scroll the page using JavaScript?
 
-For most such requests, we can use the root document element `document.documentElement`, that corresponds to `<html>` tag. But there are additional methods and peculiarities important enough to consider.
+For most such requests, we can use the root document element `document.documentElement`, that corresponds to the `<html>` tag. But there are additional methods and peculiarities important enough to consider.
 
 ## Width/height of the window
 

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

@@ -250,4 +250,4 @@ Any point on the page has coordinates:
 
 Window coordinates are great to use with `position:fixed`, and document coordinates do well with `position:absolute`.
 
-Both coordinate systems have their "pro" and "contra", there are times we need one or the other one, just like CSS `position` `absolute` and `fixed`.
+Both coordinate systems have their pros and cons; there are times we need one or the other one, just like CSS `position` `absolute` and `fixed`.

2-ui/1-document/11-coordinates/article.md

@@ -148,7 +148,7 @@ In the code below `button` shows its contents using `this.innerHTML`:
 
 ## Possible mistakes
 
-If you're starting to work with event -- please note some subtleties.
+If you're starting to work with events -- please note some subtleties.
 
 **The function should be assigned as `sayThanks`, not `sayThanks()`.**
 
@@ -181,7 +181,7 @@ button.onclick = function() {
 
 **Use functions, not strings.**
 
-The assignment `elem.onclick = "alert(1)"` would work too. It works for compatibility reasons, but strongly not recommended.
+The assignment `elem.onclick = "alert(1)"` would work too. It works for compatibility reasons, but is strongly not recommended.
 
 **Don't use `setAttribute` for handlers.**
 

2-ui/2-events/01-introduction-browser-events/article.md

@@ -21,16 +21,16 @@ The most used simple events are:
 `mousemove`
 : Every mouse move over an element triggers that event.
 
+`contextmenu`
+: Triggers when opening a context menu is attempted. In the most common case, that happens when the right mouse button is pressed. Although, there are other ways to open a context menu, e.g. using a special keyboard key, so it's not exactly the mouse event.
+
 ...There are several other event types too, we'll cover them later.
 
 ### Complex events
 
 `click`
 : Triggers after `mousedown` and then `mouseup` over the same element if the left mouse button was used.
 
-`contextmenu`
-: Triggers after `mousedown` if the right mouse button was used.
-
 `dblclick`
 : Triggers after a double click over an element.
 

2-ui/3-event-details/1-mouse-events-basics/article.md

@@ -6,9 +6,9 @@ In the modern HTML standard there's a [section about Drag and Drop](https://html
 
 They are interesting because they allow to solve simple tasks easily, and also allow to handle drag'n'drop of "external" files into the browser. So we can take a file in the OS file-manager and drop it into the browser window. Then JavaScript gains access to its contents.
 
-But native Drag Events also have limitations. For instance, we can't limit dragging by a certain area. Also we can't make it "horizontal" or "vertical" only. There are other drag'n'drop tasks that can't be done using that API.
+But native Drag Events also have limitations. For instance, we can't limit dragging by a certain area. Also we can't make it "horizontal" or "vertical" only. There are other drag'n'drop tasks that can't be done using that API. Besides, mobile devices support for such events is almost non-existant.
 
-Here we'll see how to implement Drag'n'Drop using mouse events.
+So here we'll see how to implement Drag'n'Drop using mouse events.
 
 ## Drag'n'Drop algorithm
 

2-ui/3-event-details/4-mouse-drag-and-drop/article.md

@@ -1,22 +1,22 @@
 # Patterns and flags
 
-Regular expressions is a powerful way to search and replace in text.
+Regular expressions are patterns that provide a powerful way to search and replace in text.
 
-In JavaScript, they are available as [RegExp](mdn:js/RegExp) object, and also integrated in methods of strings.
+In JavaScript, they are available via the [RegExp](mdn:js/RegExp) object, as well as being integrated in methods of strings.
 
 ## Regular Expressions
 
 A regular expression (also "regexp", or just "reg") consists of a *pattern* and optional *flags*.
 
-There are two syntaxes to create a regular expression object.
+There are two syntaxes that can be used to create a regular expression object.
 
 The "long" syntax:
 
 ```js
 regexp = new RegExp("pattern", "flags");
 ```
 
-...And the short one, using slashes `"/"`:
+And the "short" one, using slashes `"/"`:
 
 ```js
 regexp = /pattern/; // no flags
@@ -25,11 +25,11 @@ regexp = /pattern/gmi; // with flags g,m and i (to be covered soon)
 
 Slashes `pattern:/.../` tell JavaScript that we are creating a regular expression. They play the same role as quotes for strings.
 
-In both cases `regexp` becomes an object of the built-in `RegExp` class.
+In both cases `regexp` becomes an instance of the built-in `RegExp` class.
 
-The main difference between these two syntaxes is that slashes `pattern:/.../` do not allow to insert expressions (like strings with `${...}`). They are fully static.
+The main difference between these two syntaxes is that pattern using slashes `/.../` does not allow for expressions to be inserted (like string template literals with `${...}`). They are fully static.
 
-Slashes are used when we know the regular expression at the code writing time -- and that's the most common situation. While `new RegExp` is used when we need to create a regexp "on the fly", from a dynamically generated string, for instance:
+Slashes are used when we know the regular expression at the code writing time -- and that's the most common situation. While `new RegExp`, is more often used when we need to create a regexp "on the fly" from a dynamically generated string. For instance:
 
 ```js
 let tag = prompt("What tag do you want to find?", "h2");
@@ -47,7 +47,7 @@ There are only 6 of them in JavaScript:
 : With this flag the search is case-insensitive: no difference between `A` and `a` (see the example below).
 
 `pattern:g`
-: With this flag the search looks for all matches, without it -- only the first one.
+: With this flag the search looks for all matches, without it -- only the first match is returned.
 
 `pattern:m`
 : Multiline mode (covered in the chapter <info:regexp-multiline-mode>).
@@ -71,7 +71,7 @@ From here on the color scheme is:
 
 ## Searching: str.match
 
-As it was said previously, regular expressions are integrated with string methods.
+As mentioned previously, regular expressions are integrated with string methods.
 
 The method `str.match(regexp)` finds all matches of `regexp` in the string `str`.
 
@@ -102,7 +102,7 @@ It has 3 working modes:
 
 3. And, finally, if there are no matches, `null` is returned (doesn't matter if there's flag `pattern:g` or not).
 
-    That's a very important nuance. If there are no matches, we get not an empty array, but `null`. Forgetting about that may lead to errors, e.g.:
+    This a very important nuance. If there are no matches, we don't receive an empty array, but instead receive `null`. Forgetting about that may lead to errors, e.g.:
 
     ```js run
     let matches = "JavaScript".match(/HTML/); // = null
@@ -112,7 +112,7 @@ It has 3 working modes:
     }
     ```
 
-    If we'd like the result to be always an array, we can write it this way:
+    If we'd like the result to always be an array, we can write it this way:
 
     ```js run
     let matches = "JavaScript".match(/HTML/)*!* || []*/!*;
@@ -124,7 +124,7 @@ It has 3 working modes:
 
 ## Replacing: str.replace
 
-The method `str.replace(regexp, replacement)` replaces matches with `regexp` in string `str` with `replacement` (all matches, if there's flag `pattern:g`, otherwise only the first one).
+The method `str.replace(regexp, replacement)` replaces matches found using `regexp` in string `str` with `replacement` (all matches if there's flag `pattern:g`, otherwise, only the first one).
 
 For instance:
 
@@ -164,14 +164,14 @@ let regexp = /LOVE/i;
 alert( regexp.test(str) ); // true
 ```
 
-Further in this chapter we'll study more regular expressions, come across many other examples and also meet other methods.
+Later in this chapter we'll study more regular expressions, walk through more examples, and also meet other methods.
 
 Full information about the methods is given in the article <info:regexp-methods>.
 
 ## Summary
 
 - A regular expression consists of a pattern and optional flags: `pattern:g`, `pattern:i`, `pattern:m`, `pattern:u`, `pattern:s`, `pattern:y`.
-- Without flags and special symbols that we'll study later, the search by a regexp is the same as a substring search.
-- The method `str.match(regexp)` looks for matches: all of them if there's `pattern:g` flag, otherwise only the first one.
-- The method `str.replace(regexp, replacement)` replaces matches with `regexp` by `replacement`: all of them if there's `pattern:g` flag, otherwise only the first one.
-- The method `regexp.test(str)` returns `true` if there's at least one match, otherwise `false`.
+- Without flags and special symbols  (that we'll study later), the search by a regexp is the same as a substring search.
+- The method `str.match(regexp)` looks for matches: all of them if there's `pattern:g` flag, otherwise, only the first one.
+- The method `str.replace(regexp, replacement)` replaces matches found using `regexp` with `replacement`: all of them if there's `pattern:g` flag, otherwise only the first one.
+- The method `regexp.test(str)` returns `true` if there's at least one match, otherwise, it returns `false`.