@amplitude/element-selector 0.2.1 → 0.3.1-video-analytics-2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +22 -0
- package/lib/cjs/config/resolve-config.d.ts +21 -3
- package/lib/cjs/config/resolve-config.d.ts.map +1 -1
- package/lib/cjs/config/resolve-config.js +47 -2
- package/lib/cjs/config/resolve-config.js.map +1 -1
- package/lib/cjs/engine.d.ts.map +1 -1
- package/lib/cjs/engine.js +61 -27
- package/lib/cjs/engine.js.map +1 -1
- package/lib/cjs/fallback-css-path.d.ts +6 -1
- package/lib/cjs/fallback-css-path.d.ts.map +1 -1
- package/lib/cjs/fallback-css-path.js +38 -37
- package/lib/cjs/fallback-css-path.js.map +1 -1
- package/lib/cjs/helpers/shadow.d.ts +196 -0
- package/lib/cjs/helpers/shadow.d.ts.map +1 -0
- package/lib/cjs/helpers/shadow.js +415 -0
- package/lib/cjs/helpers/shadow.js.map +1 -0
- package/lib/cjs/index.d.ts +4 -2
- package/lib/cjs/index.d.ts.map +1 -1
- package/lib/cjs/index.js +19 -1
- package/lib/cjs/index.js.map +1 -1
- package/lib/cjs/orchestrator.d.ts.map +1 -1
- package/lib/cjs/orchestrator.js +4 -2
- package/lib/cjs/orchestrator.js.map +1 -1
- package/lib/cjs/types.d.ts +36 -1
- package/lib/cjs/types.d.ts.map +1 -1
- package/lib/cjs/types.js.map +1 -1
- package/lib/esm/config/resolve-config.d.ts +21 -3
- package/lib/esm/config/resolve-config.d.ts.map +1 -1
- package/lib/esm/config/resolve-config.js +46 -2
- package/lib/esm/config/resolve-config.js.map +1 -1
- package/lib/esm/engine.d.ts.map +1 -1
- package/lib/esm/engine.js +61 -27
- package/lib/esm/engine.js.map +1 -1
- package/lib/esm/fallback-css-path.d.ts +6 -1
- package/lib/esm/fallback-css-path.d.ts.map +1 -1
- package/lib/esm/fallback-css-path.js +37 -36
- package/lib/esm/fallback-css-path.js.map +1 -1
- package/lib/esm/helpers/shadow.d.ts +196 -0
- package/lib/esm/helpers/shadow.d.ts.map +1 -0
- package/lib/esm/helpers/shadow.js +402 -0
- package/lib/esm/helpers/shadow.js.map +1 -0
- package/lib/esm/index.d.ts +4 -2
- package/lib/esm/index.d.ts.map +1 -1
- package/lib/esm/index.js +9 -1
- package/lib/esm/index.js.map +1 -1
- package/lib/esm/orchestrator.d.ts.map +1 -1
- package/lib/esm/orchestrator.js +4 -2
- package/lib/esm/orchestrator.js.map +1 -1
- package/lib/esm/types.d.ts +36 -1
- package/lib/esm/types.d.ts.map +1 -1
- package/lib/esm/types.js.map +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shadow-DOM traversal + re-resolution helpers.
|
|
3
|
+
*
|
|
4
|
+
* CSS selectors cannot pierce shadow boundaries: `document.querySelector` never
|
|
5
|
+
* matches an element that lives inside a shadow root. So a selector that needs
|
|
6
|
+
* to reach into shadow DOM can't be a single flat string — it has to be a
|
|
7
|
+
* sequence of per-tree selectors, one per shadow tree, each resolvable within
|
|
8
|
+
* its own root. We join those segments with `SHADOW_BOUNDARY_DELIMITER` and
|
|
9
|
+
* re-resolve them with `resolveSelector`, descending one `shadowRoot` per
|
|
10
|
+
* boundary.
|
|
11
|
+
*
|
|
12
|
+
* This module owns the primitives that knowledge lives in:
|
|
13
|
+
*
|
|
14
|
+
* - `composedParent` / `rootOf` — walk *out* of a shadow tree (the light-DOM
|
|
15
|
+
* `parentElement` chain dead-ends at a shadow root; `getRootNode().host`
|
|
16
|
+
* crosses the boundary).
|
|
17
|
+
* - `segmentWalk` — split the outward walk into per-tree segments, honoring
|
|
18
|
+
* the configured max shadow depth.
|
|
19
|
+
* - `resolveSelector` — the symmetric inverse of the engine's output: split
|
|
20
|
+
* on the delimiter and pierce open shadow roots to re-find the element.
|
|
21
|
+
* - `walkComposedAncestors` — yield ancestors up the composed tree, honoring a
|
|
22
|
+
* shadow-boundary crossing budget (shared by capture and selector layers).
|
|
23
|
+
* - `collectOpenShadowRoots` — DFS collection of open shadow roots for
|
|
24
|
+
* observer fan-out and deep `querySelectorAll`.
|
|
25
|
+
* - `positionalStep` — a shadow-aware `tag:nth-of-type(n)` builder shared by
|
|
26
|
+
* the orchestrator's descent and the fallback walker, so a shadow-root-top
|
|
27
|
+
* element is still disambiguated against its `ShadowRoot` siblings.
|
|
28
|
+
*
|
|
29
|
+
* See the design doc:
|
|
30
|
+
* packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
|
|
31
|
+
*/
|
|
32
|
+
/**
|
|
33
|
+
* Delimiter that separates per-shadow-tree segments in a generated selector.
|
|
34
|
+
*
|
|
35
|
+
* Chosen to be visually distinct and trivially splittable, and to be invalid as
|
|
36
|
+
* a real CSS combinator so it can never be confused with a `>` child combinator
|
|
37
|
+
* the engine emits inside a single tree. Example output:
|
|
38
|
+
*
|
|
39
|
+
* `div#host >>> button:nth-of-type(1)`
|
|
40
|
+
*
|
|
41
|
+
* which `resolveSelector` re-resolves as
|
|
42
|
+
* `document.querySelector('div#host').shadowRoot.querySelector('button:nth-of-type(1)')`.
|
|
43
|
+
*/
|
|
44
|
+
export declare const SHADOW_BOUNDARY_DELIMITER = " >>> ";
|
|
45
|
+
/**
|
|
46
|
+
* Marker prefix for a "direct child from the root" chain inside a shadow tree.
|
|
47
|
+
*
|
|
48
|
+
* A positional chain scoped to a `ShadowRoot` (e.g. `div:nth-of-type(2)`) is not
|
|
49
|
+
* anchored: `querySelector` matches it tree-wide, and `:scope` matches nothing
|
|
50
|
+
* on a `ShadowRoot` (it isn't an element), so there is no CSS way to express
|
|
51
|
+
* "direct child of the root." The generator therefore prefixes such chains with
|
|
52
|
+
* this marker and `resolveSelector` resolves them by strict direct-child descent
|
|
53
|
+
* instead of `querySelector`. Keying off this explicit marker — rather than
|
|
54
|
+
* sniffing a segment for the absence of `#`/`[` — keeps the round-trip correct
|
|
55
|
+
* no matter what the steps contain (tag, `:nth-of-type`, classes, …).
|
|
56
|
+
*
|
|
57
|
+
* `:scope > ` is deliberately valid CSS syntax so a generated selector stays a
|
|
58
|
+
* syntactically legal string; its meaning here is purely the descent signal.
|
|
59
|
+
*/
|
|
60
|
+
export declare const SHADOW_CHILD_CHAIN_PREFIX = ":scope > ";
|
|
61
|
+
/** Narrowing guard that tolerates environments without a `ShadowRoot` global. */
|
|
62
|
+
export declare function isShadowRoot(node: Node): node is ShadowRoot;
|
|
63
|
+
/**
|
|
64
|
+
* Anchor a per-tree segment so it re-resolves within a `ShadowRoot`.
|
|
65
|
+
*
|
|
66
|
+
* Both selector algorithms (the strategy-chain fallback and the legacy Chromium
|
|
67
|
+
* `cssPath`) can emit a segment that is only *positionally* specified — a chain
|
|
68
|
+
* of `tag:nth-*` / class steps with no id or attribute to pin it. In the light
|
|
69
|
+
* DOM the chain is implicitly anchored by the unique `<html>` root; inside a
|
|
70
|
+
* shadow root there is no such root element, so `querySelector` matches the
|
|
71
|
+
* chain tree-wide and can resolve to the wrong element (or none).
|
|
72
|
+
*
|
|
73
|
+
* When `segment` is such a root-anchored positional chain inside a shadow root,
|
|
74
|
+
* we prefix it with {@link SHADOW_CHILD_CHAIN_PREFIX} so `resolveSelector`
|
|
75
|
+
* descends by strict direct-child matching instead of `querySelector`. An
|
|
76
|
+
* id/attribute-anchored segment is already resolvable tree-wide and is returned
|
|
77
|
+
* untouched. `isRootAnchored` is the caller's decision (each generator knows
|
|
78
|
+
* whether its own output reached the tree top vs. short-circuited on an id), so
|
|
79
|
+
* this stays correct regardless of what the steps contain.
|
|
80
|
+
*/
|
|
81
|
+
export declare function anchorSegmentToShadowScope(segment: string, scope: ParentNode, isRootAnchored: boolean): string;
|
|
82
|
+
/**
|
|
83
|
+
* Whether the legacy `cssPath` output for `el` is a root-anchored positional
|
|
84
|
+
* chain rather than one anchored by an id.
|
|
85
|
+
*
|
|
86
|
+
* `legacyCssPath` short-circuits at the first element — inclusive of `el` —
|
|
87
|
+
* that carries an `id`, emitting `tag#id > …` from there. If some element in
|
|
88
|
+
* `el`'s ancestor chain has an id the emitted selector is id-anchored (a plain,
|
|
89
|
+
* tree-wide-resolvable `querySelector`); if none does, the chain spans the tree
|
|
90
|
+
* top down to `el` via positional steps and must be marked for direct-child
|
|
91
|
+
* descent inside a shadow root. This walks the same `parentElement` chain the
|
|
92
|
+
* legacy walker does, so the two stay in lockstep.
|
|
93
|
+
*/
|
|
94
|
+
export declare function legacyPathIsRootAnchored(el: Element): boolean;
|
|
95
|
+
/**
|
|
96
|
+
* The queryable root for `el`'s own tree: the enclosing `ShadowRoot` when `el`
|
|
97
|
+
* lives inside shadow DOM, otherwise the owner document. Both support
|
|
98
|
+
* `querySelectorAll`, so uniqueness checks can be scoped to the correct tree.
|
|
99
|
+
*
|
|
100
|
+
* Preserves the legacy default for non-shadow elements (`ownerDocument`), so
|
|
101
|
+
* nothing changes for the common flat-document case.
|
|
102
|
+
*/
|
|
103
|
+
export declare function rootOf(el: Element): ParentNode;
|
|
104
|
+
/**
|
|
105
|
+
* The next element up, crossing shadow boundaries: `parentElement` within a
|
|
106
|
+
* tree, or the shadow host when `el` is at the top of a shadow tree. Returns
|
|
107
|
+
* `null` only at the document root (or a detached non-shadow root).
|
|
108
|
+
*/
|
|
109
|
+
export declare function composedParent(el: Element): Element | null;
|
|
110
|
+
/** One tree's contribution to a piercing selector. */
|
|
111
|
+
export interface TreeSegment {
|
|
112
|
+
/** Queryable root for this tree — a `Document` or `ShadowRoot`. */
|
|
113
|
+
root: ParentNode;
|
|
114
|
+
/** Element to locate within `root`: the host of the next inner tree, or the original target. */
|
|
115
|
+
target: Element;
|
|
116
|
+
}
|
|
117
|
+
export interface SegmentWalkResult {
|
|
118
|
+
/** Tree segments, outermost (document) first — the order they're joined for output. */
|
|
119
|
+
segments: TreeSegment[];
|
|
120
|
+
/**
|
|
121
|
+
* True when the target sat deeper than `maxShadowDepth` allowed, so inner
|
|
122
|
+
* trees were dropped and the innermost emitted segment targets the shadow
|
|
123
|
+
* host at the depth limit rather than the original target.
|
|
124
|
+
*/
|
|
125
|
+
truncated: boolean;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Defensive bound on composed-ancestor walks (host-chain iteration in
|
|
129
|
+
* `walkComposedAncestors` and `segmentWalk`). Far above any real shadow nesting
|
|
130
|
+
* (the resolver caps effective depth at `MAX_SHADOW_DOM_DEPTH`). See also
|
|
131
|
+
* {@link MAX_SHADOW_DOM_TRAVERSAL_NODES} for the DFS collection cap.
|
|
132
|
+
*/
|
|
133
|
+
export declare const MAX_SHADOW_COMPOSED_WALK_ITERATIONS = 1024;
|
|
134
|
+
/**
|
|
135
|
+
* Defensive bound on node visits when collecting open shadow roots via DFS.
|
|
136
|
+
* Caps synchronous work inside MutationObserver callbacks on pathologically
|
|
137
|
+
* large trees. See also {@link MAX_SHADOW_COMPOSED_WALK_ITERATIONS} for the
|
|
138
|
+
* ancestor-walk cap.
|
|
139
|
+
*/
|
|
140
|
+
export declare const MAX_SHADOW_DOM_TRAVERSAL_NODES = 50000;
|
|
141
|
+
export interface OpenShadowRootEntry {
|
|
142
|
+
root: ShadowRoot;
|
|
143
|
+
/** 1-based shadow-boundary depth relative to the collection `root`. */
|
|
144
|
+
depth: number;
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
147
|
+
* Yield `start` and each ancestor up the composed tree. Within a tree the walk
|
|
148
|
+
* follows `parentElement`; at the top of a shadow tree it crosses to the host
|
|
149
|
+
* when `crossings < maxShadowDepth`. Yields every element including detached
|
|
150
|
+
* nodes at the top of their tree (where `parentElement` is null).
|
|
151
|
+
*/
|
|
152
|
+
export declare function walkComposedAncestors(start: Element, maxShadowDepth: number): Generator<Element>;
|
|
153
|
+
/**
|
|
154
|
+
* Collect the OPEN shadow roots within `root`'s composed subtree (its own light
|
|
155
|
+
* children and any nested shadow trees), each paired with how many shadow
|
|
156
|
+
* boundary crossings deep it sits relative to `root` (1-based). Bounded by
|
|
157
|
+
* `maxShadowDepth` crossings and by {@link MAX_SHADOW_DOM_TRAVERSAL_NODES}
|
|
158
|
+
* total nodes. Closed roots are invisible (`el.shadowRoot` is null) and skipped.
|
|
159
|
+
*/
|
|
160
|
+
export declare function collectOpenShadowRoots(root: Element, maxShadowDepth: number): OpenShadowRootEntry[];
|
|
161
|
+
/**
|
|
162
|
+
* Split the outward composed walk from `el` into per-tree segments.
|
|
163
|
+
*
|
|
164
|
+
* Always walks fully out to the document so the outermost segment is
|
|
165
|
+
* document-rooted and therefore re-resolvable. `maxShadowDepth` caps how many
|
|
166
|
+
* shadow boundaries the *emitted* selector descends through: when the target is
|
|
167
|
+
* nested deeper than the budget, the innermost (over-budget) trees are dropped
|
|
168
|
+
* and the result is flagged `truncated` — the innermost kept segment then
|
|
169
|
+
* targets the shadow host at the depth limit (a best-effort, still-resolvable
|
|
170
|
+
* selector for an ancestor of the true target).
|
|
171
|
+
*/
|
|
172
|
+
export declare function segmentWalk(el: Element, maxShadowDepth: number): SegmentWalkResult;
|
|
173
|
+
/**
|
|
174
|
+
* Re-resolve a generated selector back to its element, piercing open shadow
|
|
175
|
+
* roots at each boundary. The symmetric inverse of `engine.generate`.
|
|
176
|
+
*
|
|
177
|
+
* Returns `null` when any segment fails to match, or when a boundary crossing
|
|
178
|
+
* hits a *closed* shadow root (`host.shadowRoot === null`) — closed roots are
|
|
179
|
+
* opaque from outside, so such selectors cannot round-trip (a documented
|
|
180
|
+
* limitation). Never throws on a malformed segment.
|
|
181
|
+
*
|
|
182
|
+
* @param root Root to resolve against — almost always `document`.
|
|
183
|
+
* @param selector A selector produced by the engine (may contain boundary delimiters).
|
|
184
|
+
*/
|
|
185
|
+
export declare function resolveSelector(root: ParentNode, selector: string): Element | null;
|
|
186
|
+
/**
|
|
187
|
+
* Build a single positional step for `el`: `tag:nth-of-type(n)`, indexed among
|
|
188
|
+
* its same-tag siblings. A parentless element emits the bare tag.
|
|
189
|
+
*
|
|
190
|
+
* `shadowAware` extends the parentless case: an element at the top of a shadow
|
|
191
|
+
* tree has a null `parentElement` but can still have same-tag peers among the
|
|
192
|
+
* `ShadowRoot`'s children, so it is indexed against those instead. When
|
|
193
|
+
* `shadowAware` is false every parentless element emits the bare tag.
|
|
194
|
+
*/
|
|
195
|
+
export declare function positionalStep(el: Element, shadowAware: boolean): string;
|
|
196
|
+
//# sourceMappingURL=shadow.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"shadow.d.ts","sourceRoot":"","sources":["../../../src/helpers/shadow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,UAAU,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,yBAAyB,cAAc,CAAC;AAErD,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,IAAI,UAAU,CAE3D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,OAAO,GAAG,MAAM,CAK9G;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAO7D;AAED;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,OAAO,GAAG,UAAU,CAM9C;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,GAAG,IAAI,CAS1D;AAED,sDAAsD;AACtD,MAAM,WAAW,WAAW;IAC1B,mEAAmE;IACnE,IAAI,EAAE,UAAU,CAAC;IACjB,gGAAgG;IAChG,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,eAAO,MAAM,mCAAmC,OAAO,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,QAAQ,CAAC;AAEpD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,UAAU,CAAC;IACjB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAiB,qBAAqB,CAAC,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,CAuBjG;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAwBnG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,GAAG,iBAAiB,CAgClF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,IAAI,CA0BlF;AAyCD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,CAgBxE"}
|
|
@@ -0,0 +1,415 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
/**
|
|
3
|
+
* Shadow-DOM traversal + re-resolution helpers.
|
|
4
|
+
*
|
|
5
|
+
* CSS selectors cannot pierce shadow boundaries: `document.querySelector` never
|
|
6
|
+
* matches an element that lives inside a shadow root. So a selector that needs
|
|
7
|
+
* to reach into shadow DOM can't be a single flat string — it has to be a
|
|
8
|
+
* sequence of per-tree selectors, one per shadow tree, each resolvable within
|
|
9
|
+
* its own root. We join those segments with `SHADOW_BOUNDARY_DELIMITER` and
|
|
10
|
+
* re-resolve them with `resolveSelector`, descending one `shadowRoot` per
|
|
11
|
+
* boundary.
|
|
12
|
+
*
|
|
13
|
+
* This module owns the primitives that knowledge lives in:
|
|
14
|
+
*
|
|
15
|
+
* - `composedParent` / `rootOf` — walk *out* of a shadow tree (the light-DOM
|
|
16
|
+
* `parentElement` chain dead-ends at a shadow root; `getRootNode().host`
|
|
17
|
+
* crosses the boundary).
|
|
18
|
+
* - `segmentWalk` — split the outward walk into per-tree segments, honoring
|
|
19
|
+
* the configured max shadow depth.
|
|
20
|
+
* - `resolveSelector` — the symmetric inverse of the engine's output: split
|
|
21
|
+
* on the delimiter and pierce open shadow roots to re-find the element.
|
|
22
|
+
* - `walkComposedAncestors` — yield ancestors up the composed tree, honoring a
|
|
23
|
+
* shadow-boundary crossing budget (shared by capture and selector layers).
|
|
24
|
+
* - `collectOpenShadowRoots` — DFS collection of open shadow roots for
|
|
25
|
+
* observer fan-out and deep `querySelectorAll`.
|
|
26
|
+
* - `positionalStep` — a shadow-aware `tag:nth-of-type(n)` builder shared by
|
|
27
|
+
* the orchestrator's descent and the fallback walker, so a shadow-root-top
|
|
28
|
+
* element is still disambiguated against its `ShadowRoot` siblings.
|
|
29
|
+
*
|
|
30
|
+
* See the design doc:
|
|
31
|
+
* packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
|
|
32
|
+
*/
|
|
33
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
34
|
+
exports.positionalStep = exports.resolveSelector = exports.segmentWalk = exports.collectOpenShadowRoots = exports.walkComposedAncestors = exports.MAX_SHADOW_DOM_TRAVERSAL_NODES = exports.MAX_SHADOW_COMPOSED_WALK_ITERATIONS = exports.composedParent = exports.rootOf = exports.legacyPathIsRootAnchored = exports.anchorSegmentToShadowScope = exports.isShadowRoot = exports.SHADOW_CHILD_CHAIN_PREFIX = exports.SHADOW_BOUNDARY_DELIMITER = void 0;
|
|
35
|
+
var tslib_1 = require("tslib");
|
|
36
|
+
/**
|
|
37
|
+
* Delimiter that separates per-shadow-tree segments in a generated selector.
|
|
38
|
+
*
|
|
39
|
+
* Chosen to be visually distinct and trivially splittable, and to be invalid as
|
|
40
|
+
* a real CSS combinator so it can never be confused with a `>` child combinator
|
|
41
|
+
* the engine emits inside a single tree. Example output:
|
|
42
|
+
*
|
|
43
|
+
* `div#host >>> button:nth-of-type(1)`
|
|
44
|
+
*
|
|
45
|
+
* which `resolveSelector` re-resolves as
|
|
46
|
+
* `document.querySelector('div#host').shadowRoot.querySelector('button:nth-of-type(1)')`.
|
|
47
|
+
*/
|
|
48
|
+
exports.SHADOW_BOUNDARY_DELIMITER = ' >>> ';
|
|
49
|
+
/**
|
|
50
|
+
* Marker prefix for a "direct child from the root" chain inside a shadow tree.
|
|
51
|
+
*
|
|
52
|
+
* A positional chain scoped to a `ShadowRoot` (e.g. `div:nth-of-type(2)`) is not
|
|
53
|
+
* anchored: `querySelector` matches it tree-wide, and `:scope` matches nothing
|
|
54
|
+
* on a `ShadowRoot` (it isn't an element), so there is no CSS way to express
|
|
55
|
+
* "direct child of the root." The generator therefore prefixes such chains with
|
|
56
|
+
* this marker and `resolveSelector` resolves them by strict direct-child descent
|
|
57
|
+
* instead of `querySelector`. Keying off this explicit marker — rather than
|
|
58
|
+
* sniffing a segment for the absence of `#`/`[` — keeps the round-trip correct
|
|
59
|
+
* no matter what the steps contain (tag, `:nth-of-type`, classes, …).
|
|
60
|
+
*
|
|
61
|
+
* `:scope > ` is deliberately valid CSS syntax so a generated selector stays a
|
|
62
|
+
* syntactically legal string; its meaning here is purely the descent signal.
|
|
63
|
+
*/
|
|
64
|
+
exports.SHADOW_CHILD_CHAIN_PREFIX = ':scope > ';
|
|
65
|
+
/** Narrowing guard that tolerates environments without a `ShadowRoot` global. */
|
|
66
|
+
function isShadowRoot(node) {
|
|
67
|
+
return typeof ShadowRoot !== 'undefined' && node instanceof ShadowRoot;
|
|
68
|
+
}
|
|
69
|
+
exports.isShadowRoot = isShadowRoot;
|
|
70
|
+
/**
|
|
71
|
+
* Anchor a per-tree segment so it re-resolves within a `ShadowRoot`.
|
|
72
|
+
*
|
|
73
|
+
* Both selector algorithms (the strategy-chain fallback and the legacy Chromium
|
|
74
|
+
* `cssPath`) can emit a segment that is only *positionally* specified — a chain
|
|
75
|
+
* of `tag:nth-*` / class steps with no id or attribute to pin it. In the light
|
|
76
|
+
* DOM the chain is implicitly anchored by the unique `<html>` root; inside a
|
|
77
|
+
* shadow root there is no such root element, so `querySelector` matches the
|
|
78
|
+
* chain tree-wide and can resolve to the wrong element (or none).
|
|
79
|
+
*
|
|
80
|
+
* When `segment` is such a root-anchored positional chain inside a shadow root,
|
|
81
|
+
* we prefix it with {@link SHADOW_CHILD_CHAIN_PREFIX} so `resolveSelector`
|
|
82
|
+
* descends by strict direct-child matching instead of `querySelector`. An
|
|
83
|
+
* id/attribute-anchored segment is already resolvable tree-wide and is returned
|
|
84
|
+
* untouched. `isRootAnchored` is the caller's decision (each generator knows
|
|
85
|
+
* whether its own output reached the tree top vs. short-circuited on an id), so
|
|
86
|
+
* this stays correct regardless of what the steps contain.
|
|
87
|
+
*/
|
|
88
|
+
function anchorSegmentToShadowScope(segment, scope, isRootAnchored) {
|
|
89
|
+
if (segment && isRootAnchored && isShadowRoot(scope)) {
|
|
90
|
+
return "".concat(exports.SHADOW_CHILD_CHAIN_PREFIX).concat(segment);
|
|
91
|
+
}
|
|
92
|
+
return segment;
|
|
93
|
+
}
|
|
94
|
+
exports.anchorSegmentToShadowScope = anchorSegmentToShadowScope;
|
|
95
|
+
/**
|
|
96
|
+
* Whether the legacy `cssPath` output for `el` is a root-anchored positional
|
|
97
|
+
* chain rather than one anchored by an id.
|
|
98
|
+
*
|
|
99
|
+
* `legacyCssPath` short-circuits at the first element — inclusive of `el` —
|
|
100
|
+
* that carries an `id`, emitting `tag#id > …` from there. If some element in
|
|
101
|
+
* `el`'s ancestor chain has an id the emitted selector is id-anchored (a plain,
|
|
102
|
+
* tree-wide-resolvable `querySelector`); if none does, the chain spans the tree
|
|
103
|
+
* top down to `el` via positional steps and must be marked for direct-child
|
|
104
|
+
* descent inside a shadow root. This walks the same `parentElement` chain the
|
|
105
|
+
* legacy walker does, so the two stay in lockstep.
|
|
106
|
+
*/
|
|
107
|
+
function legacyPathIsRootAnchored(el) {
|
|
108
|
+
for (var node = el; node !== null; node = node.parentElement) {
|
|
109
|
+
if (node.getAttribute('id')) {
|
|
110
|
+
return false;
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
return true;
|
|
114
|
+
}
|
|
115
|
+
exports.legacyPathIsRootAnchored = legacyPathIsRootAnchored;
|
|
116
|
+
/**
|
|
117
|
+
* The queryable root for `el`'s own tree: the enclosing `ShadowRoot` when `el`
|
|
118
|
+
* lives inside shadow DOM, otherwise the owner document. Both support
|
|
119
|
+
* `querySelectorAll`, so uniqueness checks can be scoped to the correct tree.
|
|
120
|
+
*
|
|
121
|
+
* Preserves the legacy default for non-shadow elements (`ownerDocument`), so
|
|
122
|
+
* nothing changes for the common flat-document case.
|
|
123
|
+
*/
|
|
124
|
+
function rootOf(el) {
|
|
125
|
+
var _a;
|
|
126
|
+
var root = el.getRootNode();
|
|
127
|
+
if (isShadowRoot(root)) {
|
|
128
|
+
return root;
|
|
129
|
+
}
|
|
130
|
+
return (_a = el.ownerDocument) !== null && _a !== void 0 ? _a : document;
|
|
131
|
+
}
|
|
132
|
+
exports.rootOf = rootOf;
|
|
133
|
+
/**
|
|
134
|
+
* The next element up, crossing shadow boundaries: `parentElement` within a
|
|
135
|
+
* tree, or the shadow host when `el` is at the top of a shadow tree. Returns
|
|
136
|
+
* `null` only at the document root (or a detached non-shadow root).
|
|
137
|
+
*/
|
|
138
|
+
function composedParent(el) {
|
|
139
|
+
if (el.parentElement) {
|
|
140
|
+
return el.parentElement;
|
|
141
|
+
}
|
|
142
|
+
var root = el.getRootNode();
|
|
143
|
+
if (isShadowRoot(root)) {
|
|
144
|
+
return root.host;
|
|
145
|
+
}
|
|
146
|
+
return null;
|
|
147
|
+
}
|
|
148
|
+
exports.composedParent = composedParent;
|
|
149
|
+
/**
|
|
150
|
+
* Defensive bound on composed-ancestor walks (host-chain iteration in
|
|
151
|
+
* `walkComposedAncestors` and `segmentWalk`). Far above any real shadow nesting
|
|
152
|
+
* (the resolver caps effective depth at `MAX_SHADOW_DOM_DEPTH`). See also
|
|
153
|
+
* {@link MAX_SHADOW_DOM_TRAVERSAL_NODES} for the DFS collection cap.
|
|
154
|
+
*/
|
|
155
|
+
exports.MAX_SHADOW_COMPOSED_WALK_ITERATIONS = 1024;
|
|
156
|
+
/**
|
|
157
|
+
* Defensive bound on node visits when collecting open shadow roots via DFS.
|
|
158
|
+
* Caps synchronous work inside MutationObserver callbacks on pathologically
|
|
159
|
+
* large trees. See also {@link MAX_SHADOW_COMPOSED_WALK_ITERATIONS} for the
|
|
160
|
+
* ancestor-walk cap.
|
|
161
|
+
*/
|
|
162
|
+
exports.MAX_SHADOW_DOM_TRAVERSAL_NODES = 50000;
|
|
163
|
+
/**
|
|
164
|
+
* Yield `start` and each ancestor up the composed tree. Within a tree the walk
|
|
165
|
+
* follows `parentElement`; at the top of a shadow tree it crosses to the host
|
|
166
|
+
* when `crossings < maxShadowDepth`. Yields every element including detached
|
|
167
|
+
* nodes at the top of their tree (where `parentElement` is null).
|
|
168
|
+
*/
|
|
169
|
+
function walkComposedAncestors(start, maxShadowDepth) {
|
|
170
|
+
var node, crossings, iterations, host;
|
|
171
|
+
return tslib_1.__generator(this, function (_a) {
|
|
172
|
+
switch (_a.label) {
|
|
173
|
+
case 0:
|
|
174
|
+
node = start;
|
|
175
|
+
crossings = 0;
|
|
176
|
+
iterations = 0;
|
|
177
|
+
_a.label = 1;
|
|
178
|
+
case 1:
|
|
179
|
+
if (!(node !== null && iterations < exports.MAX_SHADOW_COMPOSED_WALK_ITERATIONS)) return [3 /*break*/, 3];
|
|
180
|
+
iterations += 1;
|
|
181
|
+
return [4 /*yield*/, node];
|
|
182
|
+
case 2:
|
|
183
|
+
_a.sent();
|
|
184
|
+
if (node.parentElement) {
|
|
185
|
+
node = node.parentElement;
|
|
186
|
+
return [3 /*break*/, 1];
|
|
187
|
+
}
|
|
188
|
+
if (crossings < maxShadowDepth && typeof node.getRootNode === 'function') {
|
|
189
|
+
host = composedParent(node);
|
|
190
|
+
if (host && host !== node) {
|
|
191
|
+
crossings += 1;
|
|
192
|
+
node = host;
|
|
193
|
+
return [3 /*break*/, 1];
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
return [3 /*break*/, 3];
|
|
197
|
+
case 3: return [2 /*return*/];
|
|
198
|
+
}
|
|
199
|
+
});
|
|
200
|
+
}
|
|
201
|
+
exports.walkComposedAncestors = walkComposedAncestors;
|
|
202
|
+
/**
|
|
203
|
+
* Collect the OPEN shadow roots within `root`'s composed subtree (its own light
|
|
204
|
+
* children and any nested shadow trees), each paired with how many shadow
|
|
205
|
+
* boundary crossings deep it sits relative to `root` (1-based). Bounded by
|
|
206
|
+
* `maxShadowDepth` crossings and by {@link MAX_SHADOW_DOM_TRAVERSAL_NODES}
|
|
207
|
+
* total nodes. Closed roots are invisible (`el.shadowRoot` is null) and skipped.
|
|
208
|
+
*/
|
|
209
|
+
function collectOpenShadowRoots(root, maxShadowDepth) {
|
|
210
|
+
var found = [];
|
|
211
|
+
if (maxShadowDepth <= 0) {
|
|
212
|
+
return found;
|
|
213
|
+
}
|
|
214
|
+
var stack = [[root, 0]];
|
|
215
|
+
var visited = 0;
|
|
216
|
+
while (stack.length && visited < exports.MAX_SHADOW_DOM_TRAVERSAL_NODES) {
|
|
217
|
+
visited += 1;
|
|
218
|
+
var _a = tslib_1.__read(stack.pop(), 2), el = _a[0], depth = _a[1];
|
|
219
|
+
var shadowRoot = el.shadowRoot;
|
|
220
|
+
if (shadowRoot && depth + 1 <= maxShadowDepth) {
|
|
221
|
+
found.push({ root: shadowRoot, depth: depth + 1 });
|
|
222
|
+
var shadowChildren = shadowRoot.children;
|
|
223
|
+
for (var i = 0; i < shadowChildren.length; i++) {
|
|
224
|
+
stack.push([shadowChildren[i], depth + 1]);
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
var children = el.children;
|
|
228
|
+
for (var i = 0; i < children.length; i++) {
|
|
229
|
+
stack.push([children[i], depth]);
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
return found;
|
|
233
|
+
}
|
|
234
|
+
exports.collectOpenShadowRoots = collectOpenShadowRoots;
|
|
235
|
+
/**
|
|
236
|
+
* Split the outward composed walk from `el` into per-tree segments.
|
|
237
|
+
*
|
|
238
|
+
* Always walks fully out to the document so the outermost segment is
|
|
239
|
+
* document-rooted and therefore re-resolvable. `maxShadowDepth` caps how many
|
|
240
|
+
* shadow boundaries the *emitted* selector descends through: when the target is
|
|
241
|
+
* nested deeper than the budget, the innermost (over-budget) trees are dropped
|
|
242
|
+
* and the result is flagged `truncated` — the innermost kept segment then
|
|
243
|
+
* targets the shadow host at the depth limit (a best-effort, still-resolvable
|
|
244
|
+
* selector for an ancestor of the true target).
|
|
245
|
+
*/
|
|
246
|
+
function segmentWalk(el, maxShadowDepth) {
|
|
247
|
+
// Build innermost-first: one segment per tree, each `target` being the
|
|
248
|
+
// element to locate within that tree (the inner tree's host, or `el`).
|
|
249
|
+
var innermostFirst = [];
|
|
250
|
+
var node = el;
|
|
251
|
+
var iterations = 0;
|
|
252
|
+
while (node !== null && iterations < exports.MAX_SHADOW_COMPOSED_WALK_ITERATIONS) {
|
|
253
|
+
iterations += 1;
|
|
254
|
+
var root = rootOf(node);
|
|
255
|
+
innermostFirst.push({ root: root, target: node });
|
|
256
|
+
var actualRoot = node.getRootNode();
|
|
257
|
+
if (!isShadowRoot(actualRoot)) {
|
|
258
|
+
break; // reached the document (or a detached non-shadow root)
|
|
259
|
+
}
|
|
260
|
+
node = actualRoot.host; // cross the boundary outward
|
|
261
|
+
}
|
|
262
|
+
var totalCrossings = innermostFirst.length - 1;
|
|
263
|
+
var truncated = false;
|
|
264
|
+
var kept = innermostFirst;
|
|
265
|
+
if (totalCrossings > maxShadowDepth) {
|
|
266
|
+
// Drop the innermost over-budget trees, keeping the outermost
|
|
267
|
+
// (maxShadowDepth + 1) trees. The new innermost kept segment's `target` is
|
|
268
|
+
// already the shadow host of the first dropped tree.
|
|
269
|
+
kept = innermostFirst.slice(totalCrossings - maxShadowDepth);
|
|
270
|
+
truncated = true;
|
|
271
|
+
}
|
|
272
|
+
// Reverse to outermost-first so the engine joins document → target order.
|
|
273
|
+
return { segments: kept.reverse(), truncated: truncated };
|
|
274
|
+
}
|
|
275
|
+
exports.segmentWalk = segmentWalk;
|
|
276
|
+
/**
|
|
277
|
+
* Re-resolve a generated selector back to its element, piercing open shadow
|
|
278
|
+
* roots at each boundary. The symmetric inverse of `engine.generate`.
|
|
279
|
+
*
|
|
280
|
+
* Returns `null` when any segment fails to match, or when a boundary crossing
|
|
281
|
+
* hits a *closed* shadow root (`host.shadowRoot === null`) — closed roots are
|
|
282
|
+
* opaque from outside, so such selectors cannot round-trip (a documented
|
|
283
|
+
* limitation). Never throws on a malformed segment.
|
|
284
|
+
*
|
|
285
|
+
* @param root Root to resolve against — almost always `document`.
|
|
286
|
+
* @param selector A selector produced by the engine (may contain boundary delimiters).
|
|
287
|
+
*/
|
|
288
|
+
function resolveSelector(root, selector) {
|
|
289
|
+
var segments = selector.split(exports.SHADOW_BOUNDARY_DELIMITER);
|
|
290
|
+
var scope = root;
|
|
291
|
+
var found = null;
|
|
292
|
+
for (var i = 0; i < segments.length; i++) {
|
|
293
|
+
if (scope === null) {
|
|
294
|
+
return null; // previous segment's host had no (open) shadow root
|
|
295
|
+
}
|
|
296
|
+
var segment = segments[i].trim();
|
|
297
|
+
try {
|
|
298
|
+
found = resolveSegment(scope, segment);
|
|
299
|
+
}
|
|
300
|
+
catch (_a) {
|
|
301
|
+
return null; // malformed segment — never throw out of the resolver
|
|
302
|
+
}
|
|
303
|
+
if (found === null) {
|
|
304
|
+
return null;
|
|
305
|
+
}
|
|
306
|
+
if (i < segments.length - 1) {
|
|
307
|
+
// Descend into this host's shadow root for the next segment. `null` for a
|
|
308
|
+
// closed root ends resolution gracefully on the next iteration.
|
|
309
|
+
scope = found.shadowRoot;
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
return found;
|
|
313
|
+
}
|
|
314
|
+
exports.resolveSelector = resolveSelector;
|
|
315
|
+
/**
|
|
316
|
+
* Resolve a single (non-delimited) segment within `scope`.
|
|
317
|
+
*
|
|
318
|
+
* A segment marked with {@link SHADOW_CHILD_CHAIN_PREFIX} is a root-anchored
|
|
319
|
+
* "direct child from the root" chain (emitted by the fallback for a shadow-root
|
|
320
|
+
* scope, where `querySelector` can't express that anchoring). We strip the
|
|
321
|
+
* marker and resolve by strict direct-child descent. The marker is set
|
|
322
|
+
* explicitly by the generator, so this stays correct regardless of what the
|
|
323
|
+
* steps contain (tag, `:nth-of-type`, classes, …). Every other segment —
|
|
324
|
+
* id/attribute-anchored, or any document-scope segment — resolves via a plain
|
|
325
|
+
* `querySelector`.
|
|
326
|
+
*/
|
|
327
|
+
function resolveSegment(scope, segment) {
|
|
328
|
+
if (segment.startsWith(exports.SHADOW_CHILD_CHAIN_PREFIX)) {
|
|
329
|
+
return resolveChildChain(scope, segment.slice(exports.SHADOW_CHILD_CHAIN_PREFIX.length));
|
|
330
|
+
}
|
|
331
|
+
return scope.querySelector(segment);
|
|
332
|
+
}
|
|
333
|
+
/**
|
|
334
|
+
* Resolve a `>`-joined chain as a strict direct-child descent from `scope`. At
|
|
335
|
+
* each level exactly one child matches the step (positional or otherwise via
|
|
336
|
+
* `matches()`), so the walk is deterministic. Returns `null` if any step matches
|
|
337
|
+
* no child.
|
|
338
|
+
*/
|
|
339
|
+
function resolveChildChain(scope, chain) {
|
|
340
|
+
var e_1, _a;
|
|
341
|
+
var _b;
|
|
342
|
+
var steps = chain.split('>').map(function (s) { return s.trim(); });
|
|
343
|
+
var children = Array.from(scope.children);
|
|
344
|
+
var el = null;
|
|
345
|
+
var _loop_1 = function (step) {
|
|
346
|
+
el = (_b = children.find(function (child) { return child.matches(step); })) !== null && _b !== void 0 ? _b : null;
|
|
347
|
+
if (el === null) {
|
|
348
|
+
return { value: null };
|
|
349
|
+
}
|
|
350
|
+
children = Array.from(el.children);
|
|
351
|
+
};
|
|
352
|
+
try {
|
|
353
|
+
for (var steps_1 = tslib_1.__values(steps), steps_1_1 = steps_1.next(); !steps_1_1.done; steps_1_1 = steps_1.next()) {
|
|
354
|
+
var step = steps_1_1.value;
|
|
355
|
+
var state_1 = _loop_1(step);
|
|
356
|
+
if (typeof state_1 === "object")
|
|
357
|
+
return state_1.value;
|
|
358
|
+
}
|
|
359
|
+
}
|
|
360
|
+
catch (e_1_1) { e_1 = { error: e_1_1 }; }
|
|
361
|
+
finally {
|
|
362
|
+
try {
|
|
363
|
+
if (steps_1_1 && !steps_1_1.done && (_a = steps_1.return)) _a.call(steps_1);
|
|
364
|
+
}
|
|
365
|
+
finally { if (e_1) throw e_1.error; }
|
|
366
|
+
}
|
|
367
|
+
return el;
|
|
368
|
+
}
|
|
369
|
+
/**
|
|
370
|
+
* Build a single positional step for `el`: `tag:nth-of-type(n)`, indexed among
|
|
371
|
+
* its same-tag siblings. A parentless element emits the bare tag.
|
|
372
|
+
*
|
|
373
|
+
* `shadowAware` extends the parentless case: an element at the top of a shadow
|
|
374
|
+
* tree has a null `parentElement` but can still have same-tag peers among the
|
|
375
|
+
* `ShadowRoot`'s children, so it is indexed against those instead. When
|
|
376
|
+
* `shadowAware` is false every parentless element emits the bare tag.
|
|
377
|
+
*/
|
|
378
|
+
function positionalStep(el, shadowAware) {
|
|
379
|
+
var tag = el.tagName.toLowerCase();
|
|
380
|
+
var parent = el.parentElement;
|
|
381
|
+
if (parent === null) {
|
|
382
|
+
// Parentless means the document root (`<html>`), a detached element, or the
|
|
383
|
+
// top of a shadow tree. Only the last has siblings worth indexing, and only
|
|
384
|
+
// when the caller asks for shadow-aware stepping.
|
|
385
|
+
var root = el.getRootNode();
|
|
386
|
+
if (shadowAware && isShadowRoot(root)) {
|
|
387
|
+
return "".concat(tag, ":nth-of-type(").concat(sameTypeIndexAmong(el, root.children), ")");
|
|
388
|
+
}
|
|
389
|
+
return tag;
|
|
390
|
+
}
|
|
391
|
+
return "".concat(tag, ":nth-of-type(").concat(sameTypeIndexAmong(el, parent.children), ")");
|
|
392
|
+
}
|
|
393
|
+
exports.positionalStep = positionalStep;
|
|
394
|
+
/**
|
|
395
|
+
* 1-based index of `el` among same-tag siblings in `siblings`, mirroring
|
|
396
|
+
* `:nth-of-type`. Takes an `HTMLCollection` rather than a parent `Element` so a
|
|
397
|
+
* `ShadowRoot`'s children can be counted too — a `ShadowRoot` is not an
|
|
398
|
+
* `Element` but does expose `children`.
|
|
399
|
+
*/
|
|
400
|
+
function sameTypeIndexAmong(el, siblings) {
|
|
401
|
+
var count = 0;
|
|
402
|
+
for (var i = 0; i < siblings.length; i++) {
|
|
403
|
+
var sibling = siblings[i];
|
|
404
|
+
if (sibling.tagName === el.tagName) {
|
|
405
|
+
count += 1;
|
|
406
|
+
if (sibling === el) {
|
|
407
|
+
return count;
|
|
408
|
+
}
|
|
409
|
+
}
|
|
410
|
+
}
|
|
411
|
+
// Defensive: element not found among its parent's children (shouldn't happen
|
|
412
|
+
// for a live element). Return 1 rather than throwing.
|
|
413
|
+
return 1;
|
|
414
|
+
}
|
|
415
|
+
//# sourceMappingURL=shadow.js.map
|