merging all conflicts

Author: iliakan

1-js/02-first-steps/09-comparison/article.md

@@ -9,7 +9,13 @@
 - يساوي: `a == b` ، يرجى ملاحظة أن علامة المساواة المزدوجة` = `تعني اختبار المساواة ، في حين أن كلمة واحدة` a = b` تعني  تعيين أو مساواة .
 - لا تساوي. في الرياضيات يكون الترميز <code>&ne;</code> ،لكن في JavaScript تكتب هكذا <code>a != b</code>.
 
+<<<<<<< HEAD
 في هذه المقالة سنتعلم المزيد عن الأنواع المختلفة من المقارنات ، وكيف تجعلها JavaScript ، بما في ذلك الخصائص المهمة.
+=======
+In this article we'll learn more about different types of comparisons, how JavaScript makes them, including important peculiarities. 
+
+At the end you'll find a good recipe to avoid "javascript quirks"-related issues.
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 ## Boolean هي النتيجة
 
@@ -197,13 +203,22 @@ alert( undefined == 0 ); // false (3)
 - المقارنات `(1)` و `(2)` إرجاع `false` لأنه يتم تحويل` undefined` إلى `NaN` و` NaN` هي قيمة رقمية خاصة تُرجع `false` لجميع المقارنات.
 - تحقق المساواة `((3)` تُرجع `false` لأن` undefined` تساوي فقط `null` و` undefined` ولا قيمة أخرى.
 
+<<<<<<< HEAD
 ### تجنب المشاكل
 
 لماذا راجعنا هذه الأمثلة؟ هل يجب أن نتذكر هذه الخصائص المميزة طوال الوقت؟ حسنًا ، ليس حقًا. في الواقع ، ستصبح هذه الأشياء الصعبة مألوفة تدريجيًا بمرور الوقت ، ولكن هناك طريقة صلبة للتهرب من المشاكل معها:
 
 فقط تعامل مع أي مقارنة بـ "undefined / null" باستثناء المساواة الصارمة `===` مع رعاية استثنائية.
 
 لا تستخدم المقارنات `> => <<=` مع متغير قد يكون `فارغًا / غير محدد` ، ما لم تكن متأكدًا حقًا مما تفعله. إذا كان المتغير يمكن أن يكون له هذه القيم ، تحقق منها بشكل منفصل.
+=======
+### Avoid problems
+
+Why did we go over these examples? Should we remember these peculiarities all the time? Well, not really. Actually, these tricky things will gradually become familiar over time, but there's a solid way to avoid problems with them:
+
+- Treat any comparison with `undefined/null` except the strict equality `===` with exceptional care.
+- Don't use comparisons `>= > < <=` with a variable which may be `null/undefined`, unless you're really sure of what you're doing. If a variable can have these values, check for them separately.
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 ## ملخص
 

1-js/05-data-types/02-number/article.md

@@ -114,12 +114,18 @@ alert( 123456..toString(36) ); // 2n9c
 
 يختصر الجدول في الأسفل الاختلافات بين هذه التوابع:
 
+<<<<<<< HEAD
 |      | `Math.floor` | `Math.ceil` | `Math.round` | `Math.trunc` |
 | ---- | ---------- | --------- | ---------- | ---------- |
 | 3.1  | 3          | 4         | 3          | 3          |
 | 3.6  | 3          | 4         | 4          | 3          |
 | -1.1 | -2         | -1        | -1         | -1         |
 | -1.6 | -2         | -1        | -2         | -1         |
+=======
+    For example, to round the number to the 2nd digit after the decimal, we can multiply the number by `100` (or a bigger power of 10), call the rounding function and then divide it back.
+    ```js run
+    let num = 1.23456;
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 
 

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

@@ -330,7 +330,11 @@ alert(user.name); // John
 alert(User.prototype.name); // undefined
 ```
 
+<<<<<<< HEAD
 من الناحية الفنية ، تتم معالجتها بعد أن يقوم المنشئ بعمله ، ويمكننا استخدامه بالنسبة لهم التعبيرات المعقدة واستدعاءات الوظائف:
+=======
+We can also assign values using more complex expressions and function calls:
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 ```js run
 class User {
@@ -343,9 +347,14 @@ let user = new User();
 alert(user.name); // John
 ```
 
+<<<<<<< HEAD
 ### عمل طرق مرتبطة بحقول class
 
 كما هو موضح في الفصل <info: bind> ، فإن وظائف JavaScript لها ديناميكية `this`. يعتمد ذلك على سياق المكالمة.
+=======
+
+### Making bound methods with class fields
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 لذلك إذا تم تمرير طريقة كائن واستدعاؤها في سياق آخر ، فلن يكون `هذا` مرجعاً إلى كائنه بعد الآن.
 
@@ -374,6 +383,7 @@ setTimeout(button.click, 1000); // undefined
 
 هناك طريقتان لإصلاحها ، كما هو موضح في الفصل <info: bind>:
 
+<<<<<<< HEAD
 1. قم بتمرير دالة مجمعة ، مثل `setTimeout (() => button.click ()، 1000)`.
 2. ربط طريقة الاعتراض ، على سبيل المثال في المنشئ:
 
@@ -399,6 +409,12 @@ setTimeout(button.click, 1000); // hello
 ```
 
 توفر حقول class بنية أكثر أناقة للحل الأخير:
+=======
+1. Pass a wrapper-function, such as `setTimeout(() => button.click(), 1000)`.
+2. Bind the method to object, e.g. in the constructor.
+
+Class fields provide another, quite elegant syntax:
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 ```js run
 class Button {
@@ -417,9 +433,15 @@ let button = new Button("hello");
 setTimeout(button.click, 1000); // hello
 ```
 
+<<<<<<< HEAD
 ينشئ حقل الفئة `click = () => {...}` وظيفة مستقلة على كل كائن `Button` ، مع` this` مرتبطًا بالكائن. ثم يمكننا تمرير "button.click" في أي مكان ، وسيتم استدعاؤها باستخدام `this` الصحيح.
 
 هذا مفيد بشكل خاص في بيئة المتصفح ، عندما نحتاج إلى إعداد طريقة كمستمع للأحداث.
+=======
+The class field `click = () => {...}` is created on a per-object basis, there's a separate function for each `Button` object, with `this` inside it referencing that object. We can pass `button.click` around anywhere, and the value of `this` will always be correct.
+
+That's especially useful in browser environment, for event listeners.
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 ## ملخص
 

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

@@ -232,7 +232,13 @@ let rabbit = new Rabbit("White Rabbit", 10); // Error: this is not defined.
 
 عفوًا! لدينا خطأ. الآن لا يمكننا إنشاء الأرانب. ماذا حصل؟
 
+<<<<<<< HEAD
 الإجابة المختصرة هي: يجب على منشئو الفصول الموروثة استدعاء `super (...)` و (!) قبل ذلك باستخدام `this`.
+=======
+The short answer is:
+
+- **Constructors in inheriting classes must call `super(...)`, and (!) do it before using `this`.**
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 ...لكن لماذا؟ ماذا يجري هنا؟ في الواقع ، يبدو الشرط غريبًا.
 
@@ -245,7 +251,11 @@ let rabbit = new Rabbit("White Rabbit", 10); // Error: this is not defined.
 - عندما يتم تنفيذ وظيفة عادية باستخدام `new` ، فإنها تنشئ كائنًا فارغًا وتعينه بـ` this`.
 - ولكن عندما يعمل منشئ مشتق ، فإنه لا يفعل ذلك. وتتوقع من المُنشئ الأصلي أن يقوم بهذه المهمة.
 
+<<<<<<< HEAD
 لذا يجب على المُنشئ المشتق استدعاء `super` من أجل تنفيذ مُنشئه الأصلي (غير المُشتق) ، وإلا فلن يتم إنشاء كائن` this`. وسنحصل على خطأ.
+=======
+So a derived constructor must call `super` in order to execute its parent (base) constructor, otherwise the object for `this` won't be created. And we'll get an error.
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 لكي يعمل مُنشئ "الأرنب" ، يجب الاتصال بـ "super ()` قبل استخدام `this` ، كما يلي:
 
@@ -281,7 +291,107 @@ alert(rabbit.earLength); // 10
 ```
 
 
+<<<<<<< HEAD
 ## Super: الأجزاء الداخلية ، [[HomeObject]]
+=======
+
+### Overriding class fields: a tricky note
+
+```warn header="Advanced note"
+This note assumes you have a certain experience with classes, maybe in other programming languages.
+
+It provides better insight into the language and also explains the behavior that might be a source of bugs (but not very often).
+
+If you find it difficult to understand, just go on, continue reading, then return to it some time later.
+```
+
+We can override not only methods, but also class fields.
+
+Although, there's a tricky behavior when we access an overridden field in parent constructor, quite different from most other programming languages.
+
+Consider this example:
+
+```js run
+class Animal {
+  name = 'animal'
+
+  constructor() {
+    alert(this.name); // (*)
+  }
+}
+
+class Rabbit extends Animal {
+  name = 'rabbit';
+}
+
+new Animal(); // animal
+*!*
+new Rabbit(); // animal
+*/!*
+```
+
+Here, class `Rabbit` extends `Animal` and overrides `name` field with its own value.
+
+There's no own constructor in `Rabbit`, so `Animal` constructor is called.
+
+What's interesting is that in both cases: `new Animal()` and `new Rabbit()`, the `alert` in the line `(*)` shows `animal`.
+
+**In other words, parent constructor always uses its own field value, not the overridden one.**
+
+What's odd about it?
+
+If it's not clear yet, please compare with methods.
+
+Here's the same code, but instead of `this.name` field we call `this.showName()` method:
+
+```js run
+class Animal {
+  showName() {  // instead of this.name = 'animal'
+    alert('animal');
+  }
+
+  constructor() {
+    this.showName(); // instead of alert(this.name);
+  }
+}
+
+class Rabbit extends Animal {
+  showName() {
+    alert('rabbit');
+  }
+}
+
+new Animal(); // animal
+*!*
+new Rabbit(); // rabbit
+*/!*
+```
+
+Please note: now the output is different.
+
+And that's what we naturally expect. When the parent constructor is called in the derived class, it uses the overridden method.
+
+...But for class fields it's not so. As said, the parent constructor always uses the parent field.
+
+Why is there the difference?
+
+Well, the reason is in the field initialization order. The class field is initialized:
+- Before constructor for the base class (that doesn't extend anything),
+- Imediately after `super()` for the derived class.
+
+In our case, `Rabbit` is the derived class. There's no `constructor()` in it. As said previously, that's the same as if there was an empty constructor with only `super(...args)`.
+
+So, `new Rabbit()` calls `super()`, thus executing the parent constructor, and (per the rule for derived classes) only after that its class fields are initialized. At the time of the parent constructor execution, there are no `Rabbit` class fields yet, that's why `Animal` fields are used.
+
+This subtle difference between fields and methods is specific to JavaScript
+
+Luckily, this behavior only reveals itself if an overridden field is used in the parent constructor. Then it may be difficult to understand what's going on, so we're explaining it here.
+
+If it becomes a problem, one can fix it by using methods or getters/setters instead of fields.
+
+
+## Super: internals, [[HomeObject]]
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 ```warn header="معلومات متقدمة"
 إذا كنت تقرأ البرنامج التعليمي لأول مرة - فقد يتم تخطي هذا القسم.

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

@@ -1,25 +1,41 @@
 
 # مقدّمة إلى الوِحدات
 
+<<<<<<< HEAD
 سنرى سريعًا بينما تطبيقنا يكبُر حجمًا وتعقيدًا بأنّ علينا تقسيمه إلى ملفات متعدّدة، أو ”وِحدات“ (module). عادةً ما تحتوي الوِحدة على صنف أو مكتبة فيها دوالّ.
+=======
+As our application grows bigger, we want to split it into multiple files, so called "modules". A module may contain a class or a library of functions for a specific purpose.
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 كانت محرّكات جافاسكربت تعمل لفترة طويلة جدًا دون أيّ صياغة وِحدات على مستوى اللغة، ولم تكن هذه بالمشكلة إذ أنّ السكربتات سابقًا كانت بسيطة وسهلة ولم يكن هناك داعٍ فعلي للوِحدات.
 
 ولكن كالعادة صارت السكربتات هذه أكثر تعقيدًا وأكبر، فكان على المجتمع اختراع طرائق مختلفة لتنظيم الشيفرات في وحدات (أو مكتبات خاصّة تُحمّل تلك الوِحدات حين الطلب).
 
+<<<<<<< HEAD
 مثال:
+=======
+To name some (for historical reasons):
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 - [AMD](https://en.wikipedia.org/wiki/Asynchronous_module_definition): هذه إحدى نُظم المكتبات القديمة جدًا والتي كتبت تنفيذها بدايةً المكتبة [require.js](http://requirejs.org/).
 - [CommonJS](http://wiki.commonjs.org/wiki/Modules/1.1): نظام الوِحدات الذي صُنِع لخوادم Node.js.
 - [UMD](https://github.com/umdjs/umd): نظام وِحدات آخر (اقتُرح ليكون للعموم أجمعين) وهو متوافق مع AMD وCommonJS.
 
 أمّا الآن فهذه المكتبات صارت (أو تصير، يومًا بعد آخر) جزءًا من التاريخ، ولكن مع ذلك سنراها في السكربتات القديمة.
 
+<<<<<<< HEAD
 ظهر نظام الوِحدات (على مستوى اللغة) في المعيار عام 2015، وتطوّر شيئًا فشيئًا منذئذ وصارت الآن أغلب المتصفّحات الرئيسة (كما و Node.js) تدعمه. لذا سيكون أفضل لو بدأنا دراسة عملها من الآن.
+=======
+The language-level module system appeared in the standard in 2015, gradually evolved since then, and is now supported by all major browsers and in Node.js. So we'll study the modern JavaScript modules from now on.
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 ## ما الوِحدة؟
 
+<<<<<<< HEAD
 الوِحدة هي ملف، فقط. كلّ نص برمجي يساوي وحدة واحدة.
+=======
+A module is just a file. One script is one module. As simple as that.
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 يمكن أن تُحمّل الوِحدات بعضها البعض وتستعمل توجيهات خاصة مثل التصدير `export` والاستيراد `import` لتتبادل الميزات فيما بينها وتستدعي الدوالّ الموجودة في وحدة ص، من وحدة س:
 
@@ -55,7 +71,15 @@ sayHi('John'); // Hello, John!
 
 [codetabs src="say" height="140" current="index.html"]
 
+<<<<<<< HEAD
 يجلب المتصفّح الوِحدة تلقائيًا ويقيم الشيفرة البرمجية بداخلها (ويستورد جميع الوحدات المتعلقة بها إن لزم الأمر)، وثمّ يشغلها.
+=======
+The browser automatically fetches and evaluates the imported module (and its imports if needed), and then runs the script.
+
+```warn header="Modules work only via HTTP(s), not in local files"
+If you try to open a web-page locally, via `file://` protocol, you'll find that `import/export` directives don't work. Use a local web-server, such as [static-server](https://www.npmjs.com/package/static-server#getting-started) or use the "live server" capability of your editor, such as VS Code [Live Server Extension](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer) to test modules.
+```
+>>>>>>> 445bda39806050acd96f87166a7c97533a0c67e9
 
 
 ## ميزات الوِحدات الأساسية

2-ui/1-document/01-browser-environment/article.md

@@ -2,11 +2,11 @@
 
 The JavaScript language was initially created for web browsers. Since then it has evolved and become a language with many uses and platforms.
 
-A platform may be a browser, or a web-server or another *host*, even a coffee machine. Each of them provides platform-specific functionality. The JavaScript specification calls that a *host environment*.
+A platform may be a browser, or a web-server or another *host*, even a "smart" coffee machine, if it can run JavaScript. Each of them provides platform-specific functionality. The JavaScript specification calls that a *host environment*.
 
 A host environment provides own objects and functions additional to the language core. Web browsers give a means to control web pages. Node.js provides server-side features, and so on.
 
-Here's a bird's-eye view of what we have when JavaScript runs in a web-browser:
+Here's a bird's-eye view of what we have when JavaScript runs in a web browser:
 
 ![](windowObjects.svg)
 
@@ -49,9 +49,7 @@ document.body.style.background = "red";
 setTimeout(() => document.body.style.background = "", 1000);
 ```
 
-Here we used `document.body.style`, but there's much, much more. Properties and methods are described in the specification:
-
-- **DOM Living Standard** at <https://dom.spec.whatwg.org>
+Here we used `document.body.style`, but there's much, much more. Properties and methods are described in the specification: [DOM Living Standard](https://dom.spec.whatwg.org).
 
 ```smart header="DOM is not only for browsers"
 The DOM specification explains the structure of a document and provides objects to manipulate it. There are non-browser instruments that use DOM too.
@@ -60,9 +58,9 @@ For instance, server-side scripts that download HTML pages and process them can
 ```
 
 ```smart header="CSSOM for styling"
-CSS rules and stylesheets are structured in a different way than HTML. There's a separate specification, [CSS Object Model (CSSOM)](https://www.w3.org/TR/cssom-1/), that explains how they are represented as objects, and how to read and write them.
+There's also a separate specification, [CSS Object Model (CSSOM)](https://www.w3.org/TR/cssom-1/) for CSS rules and stylesheets, that explains how they are represented as objects, and how to read and write them.
 
-CSSOM is used together with DOM when we modify style rules for the document. In practice though, CSSOM is rarely required, because usually CSS rules are static. We rarely need to add/remove CSS rules from JavaScript, but that's also possible.
+CSSOM is used together with DOM when we modify style rules for the document. In practice though, CSSOM is rarely required, because we rarely need to modify CSS rules from JavaScript (usually we just add/remove CSS classes, not modify their CSS rules), but that's also possible.
 ```
 
 ## BOM (Browser Object Model)