draft

Author: iliakan

Diff for: 2-ui/1-document/11-coordinates/document-window-coordinates-scroll.png

@@ -67,7 +67,7 @@ For example, there already exists `<time>` element in HTML, for date/time. But i
 Let's create `<time-formatted>` element that does the formatting:
 
 
-```html run height=50 autorun
+```html run height=50 autorun="no-epub"
 <script>
 class TimeFormatted extends HTMLElement {
 
@@ -133,7 +133,7 @@ Please note that in the current implementation, after the element is rendered, f
 
 We can observe attributes by providing their list in `observedAttributes()` static getter, and then update the element in `attributeChangedCallback`. It's called for changes only in the listed attributes for performance reasons.
 
-```html run autorun height=50
+```html run autorun="no-epub" height=50
 <script>
 class TimeFormatted extends HTMLElement {
 
@@ -286,7 +286,7 @@ We could use special [ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessi
 
 Built-in elements can be customized by inheriting from their classes. HTML buttons are instances of `HTMLButtonElement`, so let's extend it:
 
-```html run autorun
+```html run autorun="no-epub"
 <script>
 // The button that says "hello" on click
 class HelloButton extends HTMLButtonElement {
@@ -324,4 +324,7 @@ customElements.define('hello-button', HelloButton, {extends: 'button'}); // 2
 
 Мы рассмотрели, как создавать свои DOM-элементы при помощи стандарта [Custom Elements](http://www.w3.org/TR/custom-elements/).
 
+POLYFILL
+Edge is a bit lagging behind, but there's a polyfill <https://github.com/webcomponents/webcomponentsjs> that covers
+
 Далее мы перейдём к изучению дополнительных возможностей по работе с DOM.

Diff for: 2-ui/1-document/11-coordinates/[email protected]

@@ -75,16 +75,15 @@ That's how it looks in Chrome dev tools:
 
 **Shadow DOM is strongly delimited from the main document:**
 
-1. Shadow tree has own stylesheets. Style rules from the outer DOM don't get applied.
-2. Shadow tree is not visible by `document.querySelector`.
-3. Shadow tree element ids may match those in the outer document. They be unique only within the shadow tree.
+1. Shadow DOM elements are not visible to `querySelector` from the light DOM. In particular,  Shadow DOM elements may have ids that conflict with those in the light DOM. They be unique only within the shadow tree.
+2. Shadow DOM has own stylesheets. Style rules from the outer DOM don't get applied.
 
 For example:
 
 ```html run untrusted height=40
 <style>
 *!*
-  /* document style not applied to shadow tree (2) */
+  /* document style doesn't apply to shadow tree (2) */
 */!*
   p { color: red; }
 </style>
@@ -94,15 +93,15 @@ For example:
 <script>
   elem.attachShadow({mode: 'open'});
 *!*
-    // inner style is applied to shadow tree (1)
+    // shadow tree has its own style (1)
 */!*
   elem.shadowRoot.innerHTML = `
     <style> p { font-weight: bold; } </style>
     <p>Hello, John!</p>
   `;
 
 *!*
-  // <p> is only visible from inside the shadow tree  (3)
+  // <p> is only visible from queries inside the shadow tree (3)
 */!*
   alert(document.querySelectorAll('p').length); // 0
   alert(elem.shadowRoot.querySelectorAll('p').length); // 1
@@ -120,9 +119,55 @@ The element with a shadow root is called a "shadow tree host", and is available
 alert(elem.shadowRoot.host === elem); // true
 ```
 
-## Composition
 
-We can create "slotted" components, e.g. articles, tabs, menus, that can be filled by
+## Slots, composition
+
+Quite often, our components should be generic. Like tabs, menus, etc -- we should be able to fill them with content.
+
+Something like this:
+
+<custom-menu>
+  <title>Please choose:</title>
+  <item>Candy</item>
+  <item>
+  <div slot="birthday">01.01.2001</div>
+  <p>I am John</p>
+</user-card>
+
+
+Let's say we need to create a `<user-card>` custom element, for showing user cards.
+
+```html run
+<user-card>
+  <p>Hello</p>
+  <div slot="username">John Smith</div>
+  <div slot="birthday">01.01.2001</div>
+  <p>I am John</p>
+</user-card>
+
+<script>
+customElements.define('user-card', class extends HTMLElement {
+  connectedCallback() {
+    this.attachShadow({mode: 'open'});
+    this.shadowRoot = `
+      <slot name="username"></slot>
+      <slot name="birthday"></slot>
+      <slot></slot>
+    `;
+  }
+});
+</script>
+```
+
+
+
+
+Let's say we'd like to create a generic `<user-card>` element for showing the information about the user. The element itself should be generic and contain "bio", "birthday" and "avatar" image.
+
+ Another developer should be able to add `<user-card>` on the page
+
+
+Shadow DOM with "slots",  e.g. articles, tabs, menus, that can be filled by
 
 polyfill https://github.com/webcomponents/webcomponentsjs
 

Diff for: 8-web-components/2-custom-elements/article.md

@@ -1,53 +1,92 @@
 
-# Шаблоны <template>
+# Template tags
 
-Элемент `<template>` предназначен для хранения "образца" разметки, невидимого и предназначенного для вставки куда-либо.
+A built-in `<template>` element serves as a storage for markup. The browser ignores it contents, only checks for syntax validity.
 
-Конечно, есть много способов записать произвольный невидимый текст в HTML. В чём же особенность `<template>`?
+Of course, there are many ways to create an invisible element somewhere in HTML for markup purposes. What's special about `<template>`?
 
-Его отличие от обычных тегов в том, что его содержимое обрабатывается особым образом. Оно не только скрыто, но и считается находящимся вообще "вне документа". А при вставке автоматически "оживает", выполняются из него скрипты, начинает проигрываться видео и т.п.
+First, as the content is ignored, it can be any valid HTML.
 
-Содержимое тега `<template>`, в отличие, к примеру, от шаблонов или `<script type="неизвестный тип">`, обрабатывается браузером.  А значит, должно быть корректным HTML.
+For example, we can put there a table row `<tr>`:
+```html
+<template>
+  <tr>
+    <td>Contents</td>
+  </tr>
+</template>
+```
+
+Usually, if we try to put `<tr>` inside, say, a `<div>`, the browser detects the invalid DOM structure and "fixes" it, adds `<table>` around. That's not what we want. On the other hand, `<template>` keeps exactly what we place there.
+
+We can put there styles:
+
+```html
+<template>
+  <style>
+    p { font-weight: bold; }
+  </style>
+</template>
+```
 
-Оно доступно как `DocumentFragment` в свойстве тега `content`. Предполагается, что мы, при необходимости, возьмём `content` и вставим, куда надо.
+The browser considers `<template>` content "out of the document", so the style is not applied.
 
-## Вставка шаблона
+More than that, we can also have `<video>`, `<audio>` and even `<script>` in the template. It becomes live (the script executes) when we insert it.
 
-Пример вставки шаблона `tmpl` в Shadow DOM элемента `elem`:
+## Inserting template
 
-```html run autorun="no-epub"
-<p id="elem">
-  Доброе утро, страна!</p>
+The template content is available in its `content` property as a `DocumentFragment` -- a special type of DOM node.
 
+We can treat it as any other DOM node, except one special property: when we insert it somewhere, its children are inserted instead.
+
+For example, let's rewrite a Shadow DOM example from the previous chapter using `<template>`:
+
+```html run untrusted autorun="no-epub" height=60
 <template id="tmpl">
-  <h3><content></content></h3>
-  <p>Привет из подполья!</p>
-  <script>
-    document.write('...document.write:Новость!');
-  </script>
+  <style> p { font-weight: bold; } </style>
+  <script> alert("I am alive!"); </script>
+  <p id="message"></p>
 </template>
 
+<div id="elem">Click me</div>
+
 <script>
-  var root = elem.createShadowRoot();
-  root.appendChild(tmpl.content.cloneNode(true));
+  elem.onclick = function() {
+    elem.attachShadow({mode: 'open'});
+
+*!*
+    elem.shadowRoot.append(tmpl.content.cloneNode(true)); // (*)
+*/!*
+
+    elem.shadowRoot.getElementById('message').innerHTML = "Hello from the shadows!";
+  };
 </script>
 ```
 
-У нас получилось, что:
+In the line `(*)` when we clone and insert `tmpl.content`, its children (`<style>`, `<p>`) are inserted instead, they form the shadow DOM:
 
-1. В элементе `#elem` содержатся данные в некоторой оговорённой разметке.
-2. Шаблон `#tmpl` указывает, как их отобразить, куда и в какие HTML-теги завернуть содержимое `#elem`.
-3. Здесь шаблон показывается в Shadow DOM тега. Технически, это не обязательно, шаблон можно использовать и без Shadow DOM, но тогда не сработает тег `<content>`.
+```html
+<div id="elem">
+  #shadow-root
+    <style> p { font-weight: bold; } </style>
+    <script> alert("I am alive!"); </script>
+    <p id="message"></p>
+</div>
+```
 
-Можно также заметить, что скрипт из шаблона выполнился. Это важнейшее отличие вставки шаблона от вставки HTML через `innerHTML` и от обычного `DocumentFragment`.
+Please note that the template `<script>` runs exactly when it's added into the document. If we clone `template.content` multiple times, it executes each time.
 
-Также мы вставили не сам `tmpl.content`, а его клон. Это обычная практика, чтобы можно было использовать один шаблон много раз.
+## Summary
 
-## Итого
+To summarize:
 
-Тег `<template>` не призван заменить системы шаблонизации. В нём нет хитрых операторов итерации, привязок к данным.
+- `<template>` content can be any syntactically correct HTML.
+- `<template>` content is considered "out of the document", so it doesn't affect anything.
+- We can access `template.content` from JavaScript, clone it to render new component or for other purposes.
 
-Его основная особенность -- это возможность вставки "живого" содержимого, вместе со скриптами.
+The `<template>` tag is quite unique, because:
 
-И, конечно, мелочь, но удобно, что он не требует никаких библиотек.
+- The browser checks the syntax inside it (as opposed to using a template string inside a script).
+- ...But still allows to use any top-level HTML tags, even those that don't make sense without proper wrappers (e.g. `<tr>`).
+- The content becomes interactive: scripts run, `<video autoplay>` plays etc, when the insert it into the document (as opposed to assigning it with `elem.innerHTML=` that doesn't do that).
 
+The `<template>` tag does not feature any sophisticated iteration mechanisms or variable substitutions, making it less powerful than frameworks. But it's built-in and ready to serve.