Repository navigation
Shadow DOM
A page can carry shadow trees in its HTML: a <template shadowrootmode="open"> inside an element becomes that element's shadow root as the page is parsed, the way every major browser now does. Parsec attaches them the same way, so a web component's markup, its slots and the styles scoped to it are in the tree you get back, not lost in an inert template.
use parsec::css::SelectorList;
let html = r#"<user-card><template shadowrootmode="open"><style>:host { display: block }</style><b><slot name="who"></slot></b></template><span slot="who">Ada</span></user-card>"#;
let doc = parsec::parse(html, false);
let host = SelectorList::parse("user-card").unwrap().select_first(&doc, doc.root()).unwrap();
let root = doc.shadow_root(host).unwrap();
// The document's own queries don't enter the shadow tree; the root's do.
assert!(SelectorList::parse("b").unwrap().select_first(&doc, doc.root()).is_none());
let slot = SelectorList::parse("slot").unwrap().select_first(&doc, root).unwrap();
// The light-DOM <span> is assigned to the slot by name.
let span = doc.assigned_nodes(slot)[0];
assert_eq!(doc.text(span), "Ada");It follows the HTML Standard's steps for a template start tag in the "in head" insertion mode. A <template> with a valid shadowrootmode (open or closed) becomes the parent element's shadow root, with shadowrootdelegatesfocus, shadowrootclonable, shadowrootserializable and shadowrootslotassignment read as the standard says. It stays an ordinary template when the parent can't be a shadow host (only certain elements and custom elements can), already has a shadow root, or is the <html> element, or when the mode isn't valid.
Options::declarative_shadow_roots controls it. Left as None it does what the standard does: on for a whole document, off for a fragment, the way innerHTML ignores them. Some(true) turns them on for a fragment too, as setHTMLUnsafe does. One difference for fragments: the context element is never made a host, since it isn't part of the result.
-
shadow_root(host)andshadow_host(root)go between a host and its root. A shadow root'sKindisShadowRoot, with its mode and flags. - The ordinary tree walks (
children,selectfrom the document,outer_html) stay out of shadow trees, as the DOM's do. Start from the root to go in. - Slots:
assigned_nodes(slot),flattened_assigned_nodes(slot)andassigned_slot(node), for named and default slots and formanualassignment withassign. - The flat tree, what a browser would render:
flat_children,flat_parentandflat_tree. -
attach_shadow(host, init)attaches one by hand, with the DOM's rules;EditError::NotAShadowHostsays the element can't take one.
:host, :host(<compound>), :host-context(<compound>) and ::slotted(<compound>) work, from CSS Scoping. They match only in a shadow tree's own scope: run select from a shadow root, or matches with the root as scope. There the host stands in for the root, with no features of its own. The arguments are compound selectors only, so :host(:not(.a .b)) is refused.
outer_html and inner_html leave shadow roots out, as innerHTML does. SerializeOptions { serializable_shadow_roots: true, .. } writes the ones marked serializable, and shadow_roots lists any others to include, which is getHTML(). See Serialization.
XPath leaves shadow trees out, like document.evaluate; index a shadow root as a root of its own to query inside it (XPath). A shadow root can't be inserted anywhere, a host can't be moved into its own shadow tree, and a host keeps its shadow root when it's moved or renamed.
The static cases of web-platform-tests' shadow-dom/declarative suite run in cargo test: 7,590 passed, 0 failed. They cover the tree cases, attaching to every element, getHTML with every combination of options, slot-assignment serialization and attribute order. WPT's :host selector cases now run too (Conformance). Lexbor has a shadow root node type, but its parser never attaches one.
Parsec is Apache-2.0 and not yet released; these pages describe main. Found something wrong here? Open an issue or ask in Discussions.
Repository · Issues · Discussions · Roadmap · Security policy · Licence