правки iliakan

Author: xcurveballx

8-web-components/7-shadow-dom-events/article.md

@@ -1,12 +1,12 @@
 # Теневой DOM и события
 
-Идея, стоящая за теневым DOM-деревом -- это инкапсуляция реализации внутренних деталей компонента.
+Смысл создания теневого DOM-дерева - это инкапсуляция внутренних деталей компонента.
 
-Допустим, клик произошёл внутри теневого DOM на компоненте `<user-card>`. Но скрипты основного документа ничего не знают о внутреннем устройстве теневой DOM-структуры, в особенности, если компонент из кода сторонней библиотеки или вроде того.
+Допустим, клик произошёл внутри теневого DOM на компоненте `<user-card>`. Но скрипты основного документа ничего не знают о внутреннем устройстве теневой DOM-структуры, в особенности, если компонент создан сторонней библиотекой.
 
-Таким образом, чтобы не усложнять, браузер *меняет у этого события целевой элемент*.
+Поэтому, чтобы не нарушать инкапсуляцию, браузер *меняет у этого события целевой элемент*.
 
-**События, которые пойманы в теневом DOM, но вне компонента, имеют в качестве целевого элемента -- элемент-хозяин.**
+**События, которые произошли в теневом DOM, но пойманы снаружи этого DOM, имеют элемент-хозяин в качестве целевого элемента `event.target`.**
 
 Рассмотрим простой пример:
 
@@ -37,9 +37,9 @@ document.onclick =
 
 Хорошо, что браузер подменяет целевые элементы событий. Потому что внешний документ ничего не знает о внутреннем устройстве компонента. С его (внешнего документа) точки зрения, событие происходит на `<user-card>`.
 
-**Подмена целевого элемента не происходит, если событие берёт начало на "слотовом" элементе, который фактически находится в обычном, "светлом" DOM.**
+**Подмена целевого элемента не происходит, если событие берёт начало на элементе из слота, который фактически находится в обычном, светлом DOM.**
 
-Например, если пользователь кликнет на `<span slot="username">` из кода ниже -- целевой элемент события будет именно этим элементом для обоих обработчиков -- теневого и обычного ("светлого"):
+Например, если пользователь кликнет на `<span slot="username">` в примере ниже -- целевой элемент события будет именно этот `span` для обоих обработчиков -- теневого и обычного (светлого):
 
 ```html run autorun="no-epub" untrusted height=60
 <user-card id="userCard">
@@ -65,17 +65,17 @@ userCard.onclick = e => alert(`Внешний целевой элемент: ${e
 </script>
 ```
 
-Если клик произойдёт на `"John Smith"`, то для обоих обработчиков -- внутреннего и внешнего -- целевым элементом будет `<span slot="username">`. Это элемент обычного ("светлого") DOM, так что подмены не происходит.
+Если клик произойдёт на `"John Smith"`, то для обоих обработчиков -- внутреннего и внешнего -- целевым элементом будет `<span slot="username">`. Это элемент обычного (светлого) DOM, так что подмены не происходит.
 
-С другой стороны, если клик произойдёт на элементе, происходящем из теневого DOM, например, на `<b>Имя</b>`, то как только всплытие выйдет за пределы теневой DOM-структуры, его `event.target` станет `<user-card>`.
+С другой стороны, если клик произойдёт на элементе, который находится в теневом DOM, например, на `<b>Имя</b>`, то как только всплытие выйдет за пределы теневой DOM-структуры, его `event.target` станет `<user-card>`.
 
 ## Всплытие и метод event.composedPath()
 
-Для обеспечения всплытия событий используются развёрнутые DOM-структуры (Flattened DOM).
+Для обеспечения всплытия событий используется развёрнутый DOM.
 
-Таким образом, если мы имеем "слотовый" (slotted) элемент и событие происходит где-то внутри него, то оно всплывает до `<slot>` и выше.
+Таким образом, если у нас есть элемент в слоте, и событие происходит где-то внутри него, то оно всплывает до `<slot>` и выше.
 
-Полный путь изначального целевого элемента, со всеми корневыми элементами теневого DOM-дерева, можно получить, воспользовавшись методом `event.composedPath()`. Как видно из названия -- это метод, возвращающий путь, полученный после задания композиции.
+Полный путь к изначальному целевому элементу, со всеми теневыми элементами, можно получить, воспользовавшись методом `event.composedPath()`. Как видно из названия, этот метод возвращает путь после композиции.
 
 В примере выше развёрнутое DOM-дерево будет таким:
 
@@ -92,18 +92,18 @@ userCard.onclick = e => alert(`Внешний целевой элемент: ${e
 ```
 
 
-Так что, при клике по `<span slot="username">` вызов метода `event.composedPath()` вернёт массив: [`span`, `slot`, `div`, `shadow-root`, `user-card`, `body`, `html`, `document`, `window`]. Что в точности отражает цепочку родителей от целевого элемента в развёрнутой DOM-структуре после задания композиции.
+Так что, при клике по `<span slot="username">` вызов метода `event.composedPath()` вернёт массив: [`span`, `slot`, `div`, `shadow-root`, `user-card`, `body`, `html`, `document`, `window`]. Что в точности отражает цепочку родителей от целевого элемента в развёрнутой DOM-структуре после композиции.
 
 ```warn header="Детали теневого DOM-дерева доступны только для деревьев с `{mode:'open'}`"
-Если теневое DOM-дерево было создано с `{mode: 'closed'}`, то после задания композиции путь будет начинаться с элемента-хозяина: `user-card` и дальше вверх по дереву.
+Если теневое DOM-дерево было создано с `{mode: 'closed'}`, то после композиции путь будет начинаться с элемента-хозяина: `user-card` и дальше вверх по дереву.
 
-Этот метод работает по тем же принципам, что и остальные методы теневого DOM. Внутреннее устройство свёрнутых DOM-деревьев совершенно скрыто.
+Этот метод следует тем же принципам, что и остальные. Внутреннее устройство закрытых DOM-деревьев совершенно скрыто.
 ```
 
 
 ## Свойство: event.composed
 
-Большинство событий успешно всплывают, выходя за границы теневого DOM. Но есть некоторые события, которые ведут себя иначе.
+Большинство событий успешно всплывают сквозь границу теневого DOM. Но не все.
 
 Это поведение регулируется с помощью свойства `composed` объекта события. Если оно `true`, то событие пересекает границу. Иначе, оно может быть поймано лишь внутри теневого DOM.
 
@@ -119,7 +119,7 @@ userCard.onclick = e => alert(`Внешний целевой элемент: ${e
 
 Хотя есть и события, имеющие `composed: false`:
 
-- `mouseenter`, `mouseleave` (также не всплывают),
+- `mouseenter`, `mouseleave` (они вообще не всплывают),
 - `load`, `unload`, `abort`, `error`,
 - `select`,
 - `slotchange`.
@@ -128,9 +128,9 @@ userCard.onclick = e => alert(`Внешний целевой элемент: ${e
 
 ## Генерация событий
 
-Когда мы инициируем сгенерированное событие, чтобы оно всплывало за пределы компонента, нужно установить оба свойства: `bubbles` и `composed` -- со значением `true`.
+Когда мы генерируем своё событие, то, чтобы оно всплывало за пределы компонента, нужно установить оба свойства: `bubbles` и `composed` - в значение `true`.
 
-Например, здесь мы создаём элемент `div#inner` в теневом DOM-дереве элемента `div#outer` и генерируем на нём два события. Только одно с флагом `composed: true` выйдет за пределы документа:
+Например, здесь мы создаём элемент `div#inner` в теневом DOM-дереве элемента `div#outer` и генерируем на нём два события. Только одно с флагом `composed: true` выйдет наружу, в документ:
 
 ```html run untrusted height=0
 <div id="outer"></div>
@@ -169,9 +169,9 @@ inner.dispatchEvent(new CustomEvent('test', {
 
 ## Итого
 
-Только те события пересекают границы теневого DOM, чей флаг `composed` установлен в значение `true`.
+Только те события пересекают границы теневого DOM, у которых флаг `composed` установлен в значение `true`.
 
-У большинства встроенных событий стоит `composed: true`, как и описано в соответствующих спецификациях:
+У большинства встроенных событий стоит `composed: true`, это описано в соответствующих спецификациях:
 
 - UI Events <https://www.w3.org/TR/uievents>.
 - Touch Events <https://w3c.github.io/touch-events>.
@@ -180,13 +180,13 @@ inner.dispatchEvent(new CustomEvent('test', {
 
 У некоторых встроенных событий всё же стоит `composed: false`:
 
-- `mouseenter`, `mouseleave` (также не всплывают),
+- `mouseenter`, `mouseleave` (вообще не всплывают),
 - `load`, `unload`, `abort`, `error`,
 - `select`,
 - `slotchange`.
 
 Эти события могут быть пойманы только на элементах, принадлежащих тому же DOM-дереву.
 
-Если мы инициируем `CustomEvent`, то должны явно поставить флаг `composed: true`.
+Если мы генерируем своё событие `CustomEvent`, то должны явно поставить флаг `composed: true`.
 
-Обратите внимание, что в случае вложенных компонентов, события с заданной композицией всплывают через границы всего теневого DOM. Поэтому, если событие предназначено только для непосредственного ближайшего компонента, то мы также должны инициировать это событие на элементе-хозяине. Иначе оно выйдет за пределы своего теневого DOM.
+Обратите внимание, что в случае вложенных компонентов теневые DOM могут быть вложены друг в друга. События с флагом `composed` всплывают через границы всех теневых DOM. Поэтому, если событие предназначено только для ближайшего внешнего компонента-родителя, мы можем инициировать его на элементе-хозяине. Тогда оно будет уже вне теневого DOM компонента, но не выплывает наружу в "ещё более внешний" DOM.