From a42763b290d618cd9186fdc988668939191de84f Mon Sep 17 00:00:00 2001 From: Marcello Lamonaca Date: Tue, 5 Dec 2023 10:52:09 +0100 Subject: [PATCH] add Shadow DOM notes --- docs/img/webcomponents_shadowdom.svg | 1 + docs/misc/web-components.md | 70 ++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 docs/img/webcomponents_shadowdom.svg diff --git a/docs/img/webcomponents_shadowdom.svg b/docs/img/webcomponents_shadowdom.svg new file mode 100644 index 0000000..421de73 --- /dev/null +++ b/docs/img/webcomponents_shadowdom.svg @@ -0,0 +1 @@ +shadowrootdocumentshadowhostDocument TreeShadow BoundaryShadow TreedocumentshadowhostFlattened Tree (for rendering)ShadowTree \ No newline at end of file diff --git a/docs/misc/web-components.md b/docs/misc/web-components.md index ef5e91b..16f1472 100644 --- a/docs/misc/web-components.md +++ b/docs/misc/web-components.md @@ -98,6 +98,76 @@ class CustomElement extends HTMLElement { } ``` +## [Shadow DOM][using-shadow-dom-mdn] + +THe **Shadow DOM** allows to attach a DOM tree to an element, and have the internals of this tree hidden from JavaScript and CSS running in the page. + +The shadow DOM tree starts with a shadow root, underneath which it's possible to attach any element, in the same way as the normal DOM. + +Terminology: + +- **Shadow host**: The regular DOM node that the shadow DOM is attached to. +- **Shadow tree**: The DOM tree inside the shadow DOM. +- **Shadow boundary**: the place where the shadow DOM ends, and the regular DOM begins. +- **Shadow root**: The root node of the shadow tree. + +![shadow-dom-schema] + +### Creating a Shadow DOM + +```html +
+I'm not in the shadow DOM +``` + +```js +const host = document.querySelector("#host"); +const shadow = host.attachShadow({ mode: "open" }); +const span = document.createElement("span"); +span.textContent = "I'm in the shadow DOM"; +shadow.appendChild(span); +``` + +> **Note**: `{mode: "open"}` allows accessing the shadow DOM from the _root node_ `shadowDom` property. The "close" mode does not expose this property. + +### JavaScript & CSS Encapsulation + +The JavaScript and CSS defined outside the shadow DOM do not have effect inside. To style a shadow dom there are two possibilities: + +- defining a `CSSStylesheet` and assigning it to the `ShadowRoot: adoptedStyleSheets` +- adding a ` + I'm in the shadow DOM + + +
+I'm not in the shadow DOM +``` + [web-components-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Components "Web Components Docs" [using-cusotom-elements-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements "Using Custom Elements" +[using-shadow-dom-mdn]: https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM "Using Shadow DOM" +[shadow-dom-schema]: ../img/webcomponents_shadowdom.svg