@amplitude/element-selector 0.0.1 → 0.1.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/LICENSE +21 -0
- package/README.md +162 -0
- package/lib/cjs/config/resolve-config.d.ts +56 -0
- package/lib/cjs/config/resolve-config.d.ts.map +1 -0
- package/lib/cjs/config/resolve-config.js +114 -0
- package/lib/cjs/config/resolve-config.js.map +1 -0
- package/lib/cjs/engine.d.ts +54 -0
- package/lib/cjs/engine.d.ts.map +1 -0
- package/lib/cjs/engine.js +104 -0
- package/lib/cjs/engine.js.map +1 -0
- package/lib/cjs/fallback-css-path.d.ts +53 -0
- package/lib/cjs/fallback-css-path.d.ts.map +1 -0
- package/lib/cjs/fallback-css-path.js +124 -0
- package/lib/cjs/fallback-css-path.js.map +1 -0
- package/lib/cjs/helpers/describe-relative.d.ts +28 -0
- package/lib/cjs/helpers/describe-relative.d.ts.map +1 -0
- package/lib/cjs/helpers/describe-relative.js +60 -0
- package/lib/cjs/helpers/describe-relative.js.map +1 -0
- package/lib/cjs/helpers/escape-css-identifier.d.ts +8 -0
- package/lib/cjs/helpers/escape-css-identifier.d.ts.map +1 -0
- package/lib/cjs/helpers/escape-css-identifier.js +50 -0
- package/lib/cjs/helpers/escape-css-identifier.js.map +1 -0
- package/lib/cjs/helpers/escape-id.d.ts +3 -0
- package/lib/cjs/helpers/escape-id.d.ts.map +1 -0
- package/lib/cjs/helpers/escape-id.js +10 -0
- package/lib/cjs/helpers/escape-id.js.map +1 -0
- package/lib/cjs/helpers/get-stable-id.d.ts +23 -0
- package/lib/cjs/helpers/get-stable-id.d.ts.map +1 -0
- package/lib/cjs/helpers/get-stable-id.js +44 -0
- package/lib/cjs/helpers/get-stable-id.js.map +1 -0
- package/lib/cjs/index.d.ts +29 -0
- package/lib/cjs/index.d.ts.map +1 -0
- package/lib/cjs/index.js +53 -0
- package/lib/cjs/index.js.map +1 -0
- package/lib/cjs/orchestrator.d.ts +61 -0
- package/lib/cjs/orchestrator.d.ts.map +1 -0
- package/lib/cjs/orchestrator.js +140 -0
- package/lib/cjs/orchestrator.js.map +1 -0
- package/lib/cjs/patterns/autogenerated-ids.d.ts +37 -0
- package/lib/cjs/patterns/autogenerated-ids.d.ts.map +1 -0
- package/lib/cjs/patterns/autogenerated-ids.js +102 -0
- package/lib/cjs/patterns/autogenerated-ids.js.map +1 -0
- package/lib/cjs/patterns/unstable-classes.d.ts +48 -0
- package/lib/cjs/patterns/unstable-classes.d.ts.map +1 -0
- package/lib/cjs/patterns/unstable-classes.js +155 -0
- package/lib/cjs/patterns/unstable-classes.js.map +1 -0
- package/lib/cjs/strategies/explicit-tracking-attribute.d.ts +22 -0
- package/lib/cjs/strategies/explicit-tracking-attribute.d.ts.map +1 -0
- package/lib/cjs/strategies/explicit-tracking-attribute.js +36 -0
- package/lib/cjs/strategies/explicit-tracking-attribute.js.map +1 -0
- package/lib/cjs/strategies/stable-id.d.ts +14 -0
- package/lib/cjs/strategies/stable-id.d.ts.map +1 -0
- package/lib/cjs/strategies/stable-id.js +27 -0
- package/lib/cjs/strategies/stable-id.js.map +1 -0
- package/lib/cjs/types.d.ts +100 -0
- package/lib/cjs/types.d.ts.map +1 -0
- package/lib/cjs/types.js +13 -0
- package/lib/cjs/types.js.map +1 -0
- package/lib/esm/config/resolve-config.d.ts +56 -0
- package/lib/esm/config/resolve-config.d.ts.map +1 -0
- package/lib/esm/config/resolve-config.js +110 -0
- package/lib/esm/config/resolve-config.js.map +1 -0
- package/lib/esm/engine.d.ts +54 -0
- package/lib/esm/engine.d.ts.map +1 -0
- package/lib/esm/engine.js +100 -0
- package/lib/esm/engine.js.map +1 -0
- package/lib/esm/fallback-css-path.d.ts +53 -0
- package/lib/esm/fallback-css-path.d.ts.map +1 -0
- package/lib/esm/fallback-css-path.js +120 -0
- package/lib/esm/fallback-css-path.js.map +1 -0
- package/lib/esm/helpers/describe-relative.d.ts +28 -0
- package/lib/esm/helpers/describe-relative.d.ts.map +1 -0
- package/lib/esm/helpers/describe-relative.js +56 -0
- package/lib/esm/helpers/describe-relative.js.map +1 -0
- package/lib/esm/helpers/escape-css-identifier.d.ts +8 -0
- package/lib/esm/helpers/escape-css-identifier.d.ts.map +1 -0
- package/lib/esm/helpers/escape-css-identifier.js +46 -0
- package/lib/esm/helpers/escape-css-identifier.js.map +1 -0
- package/lib/esm/helpers/escape-id.d.ts +3 -0
- package/lib/esm/helpers/escape-id.d.ts.map +1 -0
- package/lib/esm/helpers/escape-id.js +6 -0
- package/lib/esm/helpers/escape-id.js.map +1 -0
- package/lib/esm/helpers/get-stable-id.d.ts +23 -0
- package/lib/esm/helpers/get-stable-id.d.ts.map +1 -0
- package/lib/esm/helpers/get-stable-id.js +40 -0
- package/lib/esm/helpers/get-stable-id.js.map +1 -0
- package/lib/esm/index.d.ts +29 -0
- package/lib/esm/index.d.ts.map +1 -0
- package/lib/esm/index.js +34 -0
- package/lib/esm/index.js.map +1 -0
- package/lib/esm/orchestrator.d.ts +61 -0
- package/lib/esm/orchestrator.d.ts.map +1 -0
- package/lib/esm/orchestrator.js +136 -0
- package/lib/esm/orchestrator.js.map +1 -0
- package/lib/esm/patterns/autogenerated-ids.d.ts +37 -0
- package/lib/esm/patterns/autogenerated-ids.d.ts.map +1 -0
- package/lib/esm/patterns/autogenerated-ids.js +97 -0
- package/lib/esm/patterns/autogenerated-ids.js.map +1 -0
- package/lib/esm/patterns/unstable-classes.d.ts +48 -0
- package/lib/esm/patterns/unstable-classes.d.ts.map +1 -0
- package/lib/esm/patterns/unstable-classes.js +150 -0
- package/lib/esm/patterns/unstable-classes.js.map +1 -0
- package/lib/esm/strategies/explicit-tracking-attribute.d.ts +22 -0
- package/lib/esm/strategies/explicit-tracking-attribute.d.ts.map +1 -0
- package/lib/esm/strategies/explicit-tracking-attribute.js +33 -0
- package/lib/esm/strategies/explicit-tracking-attribute.js.map +1 -0
- package/lib/esm/strategies/stable-id.d.ts +14 -0
- package/lib/esm/strategies/stable-id.d.ts.map +1 -0
- package/lib/esm/strategies/stable-id.js +24 -0
- package/lib/esm/strategies/stable-id.js.map +1 -0
- package/lib/esm/types.d.ts +100 -0
- package/lib/esm/types.d.ts.map +1 -0
- package/lib/esm/types.js +12 -0
- package/lib/esm/types.js.map +1 -0
- package/package.json +40 -5
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fallback CSS-path walker — the safety net for the v1 element-selector
|
|
3
|
+
* algorithm.
|
|
4
|
+
*
|
|
5
|
+
* When the orchestrator's strategy chain finds nothing usable across the full
|
|
6
|
+
* ancestor walk, the engine invokes this fallback. It produces a positional
|
|
7
|
+
* selector by walking up from the target to <html>, expressing each step as
|
|
8
|
+
* either an id anchor (when one survives the autogen filter) or a
|
|
9
|
+
* `tag:nth-of-type(n)` step.
|
|
10
|
+
*
|
|
11
|
+
* Key differences from the legacy autocapture `cssPath`:
|
|
12
|
+
*
|
|
13
|
+
* 1. Ids are filtered through `getStableId`, which honors the
|
|
14
|
+
* explicit-tracking-attribute suppression signal AND the autogenerated-id
|
|
15
|
+
* pattern pack. The legacy `cssPath` would happily anchor on `id=":r5:"`
|
|
16
|
+
* and produce selectors that never match across page loads.
|
|
17
|
+
*
|
|
18
|
+
* 2. Classes — when they're used at all for sibling disambiguation — are
|
|
19
|
+
* filtered through `filterClasses` against the unstable-class pattern
|
|
20
|
+
* pack. The current v1 implementation here doesn't emit classes (we lean
|
|
21
|
+
* entirely on `:nth-of-type` for sibling disambiguation), but the
|
|
22
|
+
* filtering helper is wired through so future iterations can opt back in
|
|
23
|
+
* surgically without re-deriving the policy.
|
|
24
|
+
*
|
|
25
|
+
* 3. A unique anchor id terminates the walk early — once we hit `body#main`,
|
|
26
|
+
* we don't need to keep walking up to `<html>`.
|
|
27
|
+
*
|
|
28
|
+
* 4. Ambiguous id anchors are skipped. Duplicate ids are invalid HTML but
|
|
29
|
+
* common enough in the wild that fallback must not emit selectors that
|
|
30
|
+
* resolve to the wrong target.
|
|
31
|
+
*
|
|
32
|
+
* Output format mirrors the orchestrator's output: `<anchor> > <descent>`.
|
|
33
|
+
* When no usable id is found anywhere on the walk, the fallback emits a
|
|
34
|
+
* pure-positional selector rooted at `html`.
|
|
35
|
+
*
|
|
36
|
+
* See the design doc:
|
|
37
|
+
* packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
|
|
38
|
+
*/
|
|
39
|
+
import { __read, __spreadArray } from "tslib";
|
|
40
|
+
import { getStableId } from './helpers/get-stable-id';
|
|
41
|
+
import { escapeIdForCss } from './helpers/escape-id';
|
|
42
|
+
/**
|
|
43
|
+
* Build a positional CSS selector for `el`, using stable ids as anchors when
|
|
44
|
+
* available and falling back to `tag:nth-of-type(n)` for disambiguation.
|
|
45
|
+
*
|
|
46
|
+
* Honors `config.maxAncestorWalkDepth` defensively — once the depth limit is
|
|
47
|
+
* reached, the walker stops and returns whatever it has built so far rooted at
|
|
48
|
+
* the deepest reached ancestor.
|
|
49
|
+
*/
|
|
50
|
+
export function fallbackCssPath(el, config, options) {
|
|
51
|
+
var _a, _b;
|
|
52
|
+
if (options === void 0) { options = {}; }
|
|
53
|
+
var scope = (_b = (_a = options.scope) !== null && _a !== void 0 ? _a : el.ownerDocument) !== null && _b !== void 0 ? _b : document;
|
|
54
|
+
var segments = [];
|
|
55
|
+
var cursor = el;
|
|
56
|
+
var depth = 0;
|
|
57
|
+
while (cursor !== null) {
|
|
58
|
+
if (config.maxAncestorWalkDepth !== undefined && depth > config.maxAncestorWalkDepth) {
|
|
59
|
+
break;
|
|
60
|
+
}
|
|
61
|
+
var id = getStableId(cursor, config);
|
|
62
|
+
if (id !== null) {
|
|
63
|
+
// Anchor format mirrors the stableId strategy: `tag#id` with the id
|
|
64
|
+
// CSS-escaped. Only terminate if the composed selector uniquely resolves
|
|
65
|
+
// to the target; duplicate ids should fall through to positional steps.
|
|
66
|
+
var anchorSegment = "".concat(cursor.tagName.toLowerCase(), "#").concat(escapeIdForCss(id));
|
|
67
|
+
var candidate = __spreadArray([anchorSegment], __read(segments), false).join(' > ');
|
|
68
|
+
if (isUniqueMatch(scope, candidate, el)) {
|
|
69
|
+
return candidate;
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
segments.unshift(stepFor(cursor));
|
|
73
|
+
cursor = cursor.parentElement;
|
|
74
|
+
depth += 1;
|
|
75
|
+
}
|
|
76
|
+
// Walked all the way to the document root without finding an id. The first
|
|
77
|
+
// segment is whatever `<html>` produced (which is just `html` since it has
|
|
78
|
+
// no parent and no same-tag siblings).
|
|
79
|
+
return segments.join(' > ');
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Build a single step. For an element with a parent: `tag:nth-of-type(n)`.
|
|
83
|
+
* For a root element (no parent — i.e. <html>): just `tag`.
|
|
84
|
+
*
|
|
85
|
+
* Class-based disambiguation is intentionally not emitted in v1 — see the
|
|
86
|
+
* design doc, "Why we don't use classes for sibling disambiguation". The
|
|
87
|
+
* `filterClasses` helper is imported in the package for future iterations.
|
|
88
|
+
*/
|
|
89
|
+
function stepFor(el) {
|
|
90
|
+
var tag = el.tagName.toLowerCase();
|
|
91
|
+
var parent = el.parentElement;
|
|
92
|
+
if (parent === null) {
|
|
93
|
+
return tag;
|
|
94
|
+
}
|
|
95
|
+
var index = sameTypeIndex(el, parent);
|
|
96
|
+
return "".concat(tag, ":nth-of-type(").concat(index, ")");
|
|
97
|
+
}
|
|
98
|
+
function sameTypeIndex(el, parent) {
|
|
99
|
+
var count = 0;
|
|
100
|
+
for (var i = 0; i < parent.children.length; i++) {
|
|
101
|
+
var sibling = parent.children[i];
|
|
102
|
+
if (sibling.tagName === el.tagName) {
|
|
103
|
+
count += 1;
|
|
104
|
+
if (sibling === el)
|
|
105
|
+
return count;
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
return 1;
|
|
109
|
+
}
|
|
110
|
+
function isUniqueMatch(scope, selector, el) {
|
|
111
|
+
var matches;
|
|
112
|
+
try {
|
|
113
|
+
matches = scope.querySelectorAll(selector);
|
|
114
|
+
}
|
|
115
|
+
catch (_e) {
|
|
116
|
+
return false;
|
|
117
|
+
}
|
|
118
|
+
return matches.length === 1 && matches[0] === el;
|
|
119
|
+
}
|
|
120
|
+
//# sourceMappingURL=fallback-css-path.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"fallback-css-path.js","sourceRoot":"","sources":["../../src/fallback-css-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAOrD;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,EAAW,EACX,MAA8B,EAC9B,OAAoC;;IAApC,wBAAA,EAAA,YAAoC;IAEpC,IAAM,KAAK,GAAe,MAAA,MAAA,OAAO,CAAC,KAAK,mCAAI,EAAE,CAAC,aAAa,mCAAI,QAAQ,CAAC;IACxE,IAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,MAAM,GAAmB,EAAE,CAAC;IAChC,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,OAAO,MAAM,KAAK,IAAI,EAAE;QACtB,IAAI,MAAM,CAAC,oBAAoB,KAAK,SAAS,IAAI,KAAK,GAAG,MAAM,CAAC,oBAAoB,EAAE;YACpF,MAAM;SACP;QAED,IAAM,EAAE,GAAG,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACvC,IAAI,EAAE,KAAK,IAAI,EAAE;YACf,oEAAoE;YACpE,yEAAyE;YACzE,wEAAwE;YACxE,IAAM,aAAa,GAAG,UAAG,MAAM,CAAC,OAAO,CAAC,WAAW,EAAE,cAAI,cAAc,CAAC,EAAE,CAAC,CAAE,CAAC;YAC9E,IAAM,SAAS,GAAG,eAAC,aAAa,UAAK,QAAQ,UAAE,IAAI,CAAC,KAAK,CAAC,CAAC;YAC3D,IAAI,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,EAAE;gBACvC,OAAO,SAAS,CAAC;aAClB;SACF;QAED,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAClC,MAAM,GAAG,MAAM,CAAC,aAAa,CAAC;QAC9B,KAAK,IAAI,CAAC,CAAC;KACZ;IAED,2EAA2E;IAC3E,2EAA2E;IAC3E,uCAAuC;IACvC,OAAO,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC9B,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,OAAO,CAAC,EAAW;IAC1B,IAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IACrC,IAAM,MAAM,GAAG,EAAE,CAAC,aAAa,CAAC;IAChC,IAAI,MAAM,KAAK,IAAI,EAAE;QACnB,OAAO,GAAG,CAAC;KACZ;IACD,IAAM,KAAK,GAAG,aAAa,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,UAAG,GAAG,0BAAgB,KAAK,MAAG,CAAC;AACxC,CAAC;AAED,SAAS,aAAa,CAAC,EAAW,EAAE,MAAe;IACjD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;QAC/C,IAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACnC,IAAI,OAAO,CAAC,OAAO,KAAK,EAAE,CAAC,OAAO,EAAE;YAClC,KAAK,IAAI,CAAC,CAAC;YACX,IAAI,OAAO,KAAK,EAAE;gBAAE,OAAO,KAAK,CAAC;SAClC;KACF;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,aAAa,CAAC,KAAiB,EAAE,QAAgB,EAAE,EAAW;IACrE,IAAI,OAA4B,CAAC;IACjC,IAAI;QACF,OAAO,GAAG,KAAK,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;KAC5C;IAAC,OAAO,EAAE,EAAE;QACX,OAAO,KAAK,CAAC;KACd;IACD,OAAO,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;AACnD,CAAC","sourcesContent":["/**\n * Fallback CSS-path walker — the safety net for the v1 element-selector\n * algorithm.\n *\n * When the orchestrator's strategy chain finds nothing usable across the full\n * ancestor walk, the engine invokes this fallback. It produces a positional\n * selector by walking up from the target to <html>, expressing each step as\n * either an id anchor (when one survives the autogen filter) or a\n * `tag:nth-of-type(n)` step.\n *\n * Key differences from the legacy autocapture `cssPath`:\n *\n * 1. Ids are filtered through `getStableId`, which honors the\n * explicit-tracking-attribute suppression signal AND the autogenerated-id\n * pattern pack. The legacy `cssPath` would happily anchor on `id=\":r5:\"`\n * and produce selectors that never match across page loads.\n *\n * 2. Classes — when they're used at all for sibling disambiguation — are\n * filtered through `filterClasses` against the unstable-class pattern\n * pack. The current v1 implementation here doesn't emit classes (we lean\n * entirely on `:nth-of-type` for sibling disambiguation), but the\n * filtering helper is wired through so future iterations can opt back in\n * surgically without re-deriving the policy.\n *\n * 3. A unique anchor id terminates the walk early — once we hit `body#main`,\n * we don't need to keep walking up to `<html>`.\n *\n * 4. Ambiguous id anchors are skipped. Duplicate ids are invalid HTML but\n * common enough in the wild that fallback must not emit selectors that\n * resolve to the wrong target.\n *\n * Output format mirrors the orchestrator's output: `<anchor> > <descent>`.\n * When no usable id is found anywhere on the walk, the fallback emits a\n * pure-positional selector rooted at `html`.\n *\n * See the design doc:\n * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md\n */\n\nimport { ResolvedSelectorConfig } from './types';\nimport { getStableId } from './helpers/get-stable-id';\nimport { escapeIdForCss } from './helpers/escape-id';\n\nexport interface FallbackCssPathOptions {\n /** Document or shadow root used for uniqueness checks. Defaults to the target's owner document. */\n scope?: ParentNode;\n}\n\n/**\n * Build a positional CSS selector for `el`, using stable ids as anchors when\n * available and falling back to `tag:nth-of-type(n)` for disambiguation.\n *\n * Honors `config.maxAncestorWalkDepth` defensively — once the depth limit is\n * reached, the walker stops and returns whatever it has built so far rooted at\n * the deepest reached ancestor.\n */\nexport function fallbackCssPath(\n el: Element,\n config: ResolvedSelectorConfig,\n options: FallbackCssPathOptions = {},\n): string {\n const scope: ParentNode = options.scope ?? el.ownerDocument ?? document;\n const segments: string[] = [];\n let cursor: Element | null = el;\n let depth = 0;\n\n while (cursor !== null) {\n if (config.maxAncestorWalkDepth !== undefined && depth > config.maxAncestorWalkDepth) {\n break;\n }\n\n const id = getStableId(cursor, config);\n if (id !== null) {\n // Anchor format mirrors the stableId strategy: `tag#id` with the id\n // CSS-escaped. Only terminate if the composed selector uniquely resolves\n // to the target; duplicate ids should fall through to positional steps.\n const anchorSegment = `${cursor.tagName.toLowerCase()}#${escapeIdForCss(id)}`;\n const candidate = [anchorSegment, ...segments].join(' > ');\n if (isUniqueMatch(scope, candidate, el)) {\n return candidate;\n }\n }\n\n segments.unshift(stepFor(cursor));\n cursor = cursor.parentElement;\n depth += 1;\n }\n\n // Walked all the way to the document root without finding an id. The first\n // segment is whatever `<html>` produced (which is just `html` since it has\n // no parent and no same-tag siblings).\n return segments.join(' > ');\n}\n\n/**\n * Build a single step. For an element with a parent: `tag:nth-of-type(n)`.\n * For a root element (no parent — i.e. <html>): just `tag`.\n *\n * Class-based disambiguation is intentionally not emitted in v1 — see the\n * design doc, \"Why we don't use classes for sibling disambiguation\". The\n * `filterClasses` helper is imported in the package for future iterations.\n */\nfunction stepFor(el: Element): string {\n const tag = el.tagName.toLowerCase();\n const parent = el.parentElement;\n if (parent === null) {\n return tag;\n }\n const index = sameTypeIndex(el, parent);\n return `${tag}:nth-of-type(${index})`;\n}\n\nfunction sameTypeIndex(el: Element, parent: Element): number {\n let count = 0;\n for (let i = 0; i < parent.children.length; i++) {\n const sibling = parent.children[i];\n if (sibling.tagName === el.tagName) {\n count += 1;\n if (sibling === el) return count;\n }\n }\n return 1;\n}\n\nfunction isUniqueMatch(scope: ParentNode, selector: string, el: Element): boolean {\n let matches: NodeListOf<Element>;\n try {\n matches = scope.querySelectorAll(selector);\n } catch (_e) {\n return false;\n }\n return matches.length === 1 && matches[0] === el;\n}\n"]}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Positional descent builder.
|
|
3
|
+
*
|
|
4
|
+
* Given an anchor element (the result of pass 2's walk in the orchestration PR)
|
|
5
|
+
* and the trail of intermediate elements between the anchor and the original
|
|
6
|
+
* click target, produce the CSS-selector descent string. Each step in the
|
|
7
|
+
* descent uses `tag:nth-of-type(n)` so the resulting selector resolves
|
|
8
|
+
* unambiguously to the original target regardless of class-state churn.
|
|
9
|
+
*
|
|
10
|
+
* Matches ContentSquare's "position within identical markers" convention.
|
|
11
|
+
*
|
|
12
|
+
* Example:
|
|
13
|
+
*
|
|
14
|
+
* describeRelative(anchor, [<section>, <ul>, <li>])
|
|
15
|
+
* → "section:nth-of-type(1) > ul:nth-of-type(1) > li:nth-of-type(3)"
|
|
16
|
+
*
|
|
17
|
+
* Combined with the anchor selector (`anchor#some-id`) by the orchestrator:
|
|
18
|
+
*
|
|
19
|
+
* "anchor#some-id > section:nth-of-type(1) > ul:nth-of-type(1) > li:nth-of-type(3)"
|
|
20
|
+
*
|
|
21
|
+
* The `anchor` parameter is accepted for symmetry with the orchestrator's call
|
|
22
|
+
* site but isn't currently used — the function only needs each trail element's
|
|
23
|
+
* own parent context. We keep the signature so subsequent work can reference
|
|
24
|
+
* the anchor when extending the descent format (e.g., to optimize bare
|
|
25
|
+
* `:nth-of-type(1)` away when there's only one of that type).
|
|
26
|
+
*/
|
|
27
|
+
export declare function describeRelative(_anchor: Element, trail: Element[]): string;
|
|
28
|
+
//# sourceMappingURL=describe-relative.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"describe-relative.d.ts","sourceRoot":"","sources":["../../../src/helpers/describe-relative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,CAE3E"}
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Positional descent builder.
|
|
3
|
+
*
|
|
4
|
+
* Given an anchor element (the result of pass 2's walk in the orchestration PR)
|
|
5
|
+
* and the trail of intermediate elements between the anchor and the original
|
|
6
|
+
* click target, produce the CSS-selector descent string. Each step in the
|
|
7
|
+
* descent uses `tag:nth-of-type(n)` so the resulting selector resolves
|
|
8
|
+
* unambiguously to the original target regardless of class-state churn.
|
|
9
|
+
*
|
|
10
|
+
* Matches ContentSquare's "position within identical markers" convention.
|
|
11
|
+
*
|
|
12
|
+
* Example:
|
|
13
|
+
*
|
|
14
|
+
* describeRelative(anchor, [<section>, <ul>, <li>])
|
|
15
|
+
* → "section:nth-of-type(1) > ul:nth-of-type(1) > li:nth-of-type(3)"
|
|
16
|
+
*
|
|
17
|
+
* Combined with the anchor selector (`anchor#some-id`) by the orchestrator:
|
|
18
|
+
*
|
|
19
|
+
* "anchor#some-id > section:nth-of-type(1) > ul:nth-of-type(1) > li:nth-of-type(3)"
|
|
20
|
+
*
|
|
21
|
+
* The `anchor` parameter is accepted for symmetry with the orchestrator's call
|
|
22
|
+
* site but isn't currently used — the function only needs each trail element's
|
|
23
|
+
* own parent context. We keep the signature so subsequent work can reference
|
|
24
|
+
* the anchor when extending the descent format (e.g., to optimize bare
|
|
25
|
+
* `:nth-of-type(1)` away when there's only one of that type).
|
|
26
|
+
*/
|
|
27
|
+
export function describeRelative(_anchor, trail) {
|
|
28
|
+
return trail.map(stepFor).join(' > ');
|
|
29
|
+
}
|
|
30
|
+
function stepFor(el) {
|
|
31
|
+
var tag = el.tagName.toLowerCase();
|
|
32
|
+
var parent = el.parentElement;
|
|
33
|
+
if (parent === null) {
|
|
34
|
+
// Detached element or root — emit just the tag. The orchestrator shouldn't
|
|
35
|
+
// call us with a detached trail, but we don't want to crash if it does.
|
|
36
|
+
return tag;
|
|
37
|
+
}
|
|
38
|
+
var index = sameTypeIndex(el, parent);
|
|
39
|
+
return "".concat(tag, ":nth-of-type(").concat(index, ")");
|
|
40
|
+
}
|
|
41
|
+
function sameTypeIndex(el, parent) {
|
|
42
|
+
// 1-based index among same-tag element siblings, mirroring :nth-of-type semantics.
|
|
43
|
+
var count = 0;
|
|
44
|
+
for (var i = 0; i < parent.children.length; i++) {
|
|
45
|
+
var sibling = parent.children[i];
|
|
46
|
+
if (sibling.tagName === el.tagName) {
|
|
47
|
+
count += 1;
|
|
48
|
+
if (sibling === el)
|
|
49
|
+
return count;
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
// Element wasn't found among its parent's children — shouldn't happen for a
|
|
53
|
+
// live element. Return 1 as a defensive fallback rather than throwing.
|
|
54
|
+
return 1;
|
|
55
|
+
}
|
|
56
|
+
//# sourceMappingURL=describe-relative.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"describe-relative.js","sourceRoot":"","sources":["../../../src/helpers/describe-relative.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB,EAAE,KAAgB;IACjE,OAAO,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AACxC,CAAC;AAED,SAAS,OAAO,CAAC,EAAW;IAC1B,IAAM,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;IACrC,IAAM,MAAM,GAAG,EAAE,CAAC,aAAa,CAAC;IAChC,IAAI,MAAM,KAAK,IAAI,EAAE;QACnB,2EAA2E;QAC3E,wEAAwE;QACxE,OAAO,GAAG,CAAC;KACZ;IACD,IAAM,KAAK,GAAG,aAAa,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IACxC,OAAO,UAAG,GAAG,0BAAgB,KAAK,MAAG,CAAC;AACxC,CAAC;AAED,SAAS,aAAa,CAAC,EAAW,EAAE,MAAe;IACjD,mFAAmF;IACnF,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE;QAC/C,IAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;QACnC,IAAI,OAAO,CAAC,OAAO,KAAK,EAAE,CAAC,OAAO,EAAE;YAClC,KAAK,IAAI,CAAC,CAAC;YACX,IAAI,OAAO,KAAK,EAAE;gBAAE,OAAO,KAAK,CAAC;SAClC;KACF;IACD,4EAA4E;IAC5E,uEAAuE;IACvE,OAAO,CAAC,CAAC;AACX,CAAC","sourcesContent":["/**\n * Positional descent builder.\n *\n * Given an anchor element (the result of pass 2's walk in the orchestration PR)\n * and the trail of intermediate elements between the anchor and the original\n * click target, produce the CSS-selector descent string. Each step in the\n * descent uses `tag:nth-of-type(n)` so the resulting selector resolves\n * unambiguously to the original target regardless of class-state churn.\n *\n * Matches ContentSquare's \"position within identical markers\" convention.\n *\n * Example:\n *\n * describeRelative(anchor, [<section>, <ul>, <li>])\n * → \"section:nth-of-type(1) > ul:nth-of-type(1) > li:nth-of-type(3)\"\n *\n * Combined with the anchor selector (`anchor#some-id`) by the orchestrator:\n *\n * \"anchor#some-id > section:nth-of-type(1) > ul:nth-of-type(1) > li:nth-of-type(3)\"\n *\n * The `anchor` parameter is accepted for symmetry with the orchestrator's call\n * site but isn't currently used — the function only needs each trail element's\n * own parent context. We keep the signature so subsequent work can reference\n * the anchor when extending the descent format (e.g., to optimize bare\n * `:nth-of-type(1)` away when there's only one of that type).\n */\nexport function describeRelative(_anchor: Element, trail: Element[]): string {\n return trail.map(stepFor).join(' > ');\n}\n\nfunction stepFor(el: Element): string {\n const tag = el.tagName.toLowerCase();\n const parent = el.parentElement;\n if (parent === null) {\n // Detached element or root — emit just the tag. The orchestrator shouldn't\n // call us with a detached trail, but we don't want to crash if it does.\n return tag;\n }\n const index = sameTypeIndex(el, parent);\n return `${tag}:nth-of-type(${index})`;\n}\n\nfunction sameTypeIndex(el: Element, parent: Element): number {\n // 1-based index among same-tag element siblings, mirroring :nth-of-type semantics.\n let count = 0;\n for (let i = 0; i < parent.children.length; i++) {\n const sibling = parent.children[i];\n if (sibling.tagName === el.tagName) {\n count += 1;\n if (sibling === el) return count;\n }\n }\n // Element wasn't found among its parent's children — shouldn't happen for a\n // live element. Return 1 as a defensive fallback rather than throwing.\n return 1;\n}\n"]}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Escape a string for use as a CSS identifier.
|
|
3
|
+
*
|
|
4
|
+
* Uses the native CSS.escape implementation when available, with the CSSOM
|
|
5
|
+
* algorithm inlined for runtimes that do not expose it (notably jsdom).
|
|
6
|
+
*/
|
|
7
|
+
export declare function escapeCssIdentifier(value: string): string;
|
|
8
|
+
//# sourceMappingURL=escape-css-identifier.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"escape-css-identifier.d.ts","sourceRoot":"","sources":["../../../src/helpers/escape-css-identifier.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiDzD"}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/* eslint-disable no-restricted-globals */
|
|
2
|
+
/**
|
|
3
|
+
* Escape a string for use as a CSS identifier.
|
|
4
|
+
*
|
|
5
|
+
* Uses the native CSS.escape implementation when available, with the CSSOM
|
|
6
|
+
* algorithm inlined for runtimes that do not expose it (notably jsdom).
|
|
7
|
+
*/
|
|
8
|
+
export function escapeCssIdentifier(value) {
|
|
9
|
+
var css = globalThis.CSS;
|
|
10
|
+
if (css && typeof css.escape === 'function') {
|
|
11
|
+
return css.escape(value);
|
|
12
|
+
}
|
|
13
|
+
var string = String(value);
|
|
14
|
+
var length = string.length;
|
|
15
|
+
var result = '';
|
|
16
|
+
for (var index = 0; index < length; index++) {
|
|
17
|
+
var codeUnit = string.charCodeAt(index);
|
|
18
|
+
if (codeUnit === 0x0000) {
|
|
19
|
+
result += '\uFFFD';
|
|
20
|
+
continue;
|
|
21
|
+
}
|
|
22
|
+
if ((codeUnit >= 0x0001 && codeUnit <= 0x001f) ||
|
|
23
|
+
codeUnit === 0x007f ||
|
|
24
|
+
(index === 0 && codeUnit >= 0x0030 && codeUnit <= 0x0039) ||
|
|
25
|
+
(index === 1 && codeUnit >= 0x0030 && codeUnit <= 0x0039 && string.charCodeAt(0) === 0x002d)) {
|
|
26
|
+
result += "\\".concat(codeUnit.toString(16), " ");
|
|
27
|
+
continue;
|
|
28
|
+
}
|
|
29
|
+
if (index === 0 && length === 1 && codeUnit === 0x002d) {
|
|
30
|
+
result += '\\-';
|
|
31
|
+
continue;
|
|
32
|
+
}
|
|
33
|
+
if (codeUnit >= 0x0080 ||
|
|
34
|
+
codeUnit === 0x002d ||
|
|
35
|
+
codeUnit === 0x005f ||
|
|
36
|
+
(codeUnit >= 0x0030 && codeUnit <= 0x0039) ||
|
|
37
|
+
(codeUnit >= 0x0041 && codeUnit <= 0x005a) ||
|
|
38
|
+
(codeUnit >= 0x0061 && codeUnit <= 0x007a)) {
|
|
39
|
+
result += string.charAt(index);
|
|
40
|
+
continue;
|
|
41
|
+
}
|
|
42
|
+
result += "\\".concat(string.charAt(index));
|
|
43
|
+
}
|
|
44
|
+
return result;
|
|
45
|
+
}
|
|
46
|
+
//# sourceMappingURL=escape-css-identifier.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"escape-css-identifier.js","sourceRoot":"","sources":["../../../src/helpers/escape-css-identifier.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAQ1C;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,IAAM,GAAG,GAAI,UAA8B,CAAC,GAAG,CAAC;IAChD,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE;QAC3C,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;KAC1B;IAED,IAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7B,IAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,IAAI,MAAM,GAAG,EAAE,CAAC;IAEhB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE;QAC3C,IAAM,QAAQ,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;QAE1C,IAAI,QAAQ,KAAK,MAAM,EAAE;YACvB,MAAM,IAAI,QAAQ,CAAC;YACnB,SAAS;SACV;QAED,IACE,CAAC,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,CAAC;YAC1C,QAAQ,KAAK,MAAM;YACnB,CAAC,KAAK,KAAK,CAAC,IAAI,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,CAAC;YACzD,CAAC,KAAK,KAAK,CAAC,IAAI,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,IAAI,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,EAC5F;YACA,MAAM,IAAI,YAAK,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAG,CAAC;YACxC,SAAS;SACV;QAED,IAAI,KAAK,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC,IAAI,QAAQ,KAAK,MAAM,EAAE;YACtD,MAAM,IAAI,KAAK,CAAC;YAChB,SAAS;SACV;QAED,IACE,QAAQ,IAAI,MAAM;YAClB,QAAQ,KAAK,MAAM;YACnB,QAAQ,KAAK,MAAM;YACnB,CAAC,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,CAAC;YAC1C,CAAC,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,CAAC;YAC1C,CAAC,QAAQ,IAAI,MAAM,IAAI,QAAQ,IAAI,MAAM,CAAC,EAC1C;YACA,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC/B,SAAS;SACV;QAED,MAAM,IAAI,YAAK,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAE,CAAC;KACvC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["/* eslint-disable no-restricted-globals */\n\ntype CssEscapeGlobal = {\n CSS?: {\n escape?: (value: string) => string;\n };\n};\n\n/**\n * Escape a string for use as a CSS identifier.\n *\n * Uses the native CSS.escape implementation when available, with the CSSOM\n * algorithm inlined for runtimes that do not expose it (notably jsdom).\n */\nexport function escapeCssIdentifier(value: string): string {\n const css = (globalThis as CssEscapeGlobal).CSS;\n if (css && typeof css.escape === 'function') {\n return css.escape(value);\n }\n\n const string = String(value);\n const length = string.length;\n let result = '';\n\n for (let index = 0; index < length; index++) {\n const codeUnit = string.charCodeAt(index);\n\n if (codeUnit === 0x0000) {\n result += '\\uFFFD';\n continue;\n }\n\n if (\n (codeUnit >= 0x0001 && codeUnit <= 0x001f) ||\n codeUnit === 0x007f ||\n (index === 0 && codeUnit >= 0x0030 && codeUnit <= 0x0039) ||\n (index === 1 && codeUnit >= 0x0030 && codeUnit <= 0x0039 && string.charCodeAt(0) === 0x002d)\n ) {\n result += `\\\\${codeUnit.toString(16)} `;\n continue;\n }\n\n if (index === 0 && length === 1 && codeUnit === 0x002d) {\n result += '\\\\-';\n continue;\n }\n\n if (\n codeUnit >= 0x0080 ||\n codeUnit === 0x002d ||\n codeUnit === 0x005f ||\n (codeUnit >= 0x0030 && codeUnit <= 0x0039) ||\n (codeUnit >= 0x0041 && codeUnit <= 0x005a) ||\n (codeUnit >= 0x0061 && codeUnit <= 0x007a)\n ) {\n result += string.charAt(index);\n continue;\n }\n\n result += `\\\\${string.charAt(index)}`;\n }\n\n return result;\n}\n"]}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"escape-id.d.ts","sourceRoot":"","sources":["../../../src/helpers/escape-id.ts"],"names":[],"mappings":"AAEA,+FAA+F;AAC/F,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAEjD"}
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import { escapeCssIdentifier } from './escape-css-identifier';
|
|
2
|
+
/** Escape an element id for the `tag#<id>` selector form shared by strategies and fallback. */
|
|
3
|
+
export function escapeIdForCss(id) {
|
|
4
|
+
return escapeCssIdentifier(id);
|
|
5
|
+
}
|
|
6
|
+
//# sourceMappingURL=escape-id.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"escape-id.js","sourceRoot":"","sources":["../../../src/helpers/escape-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,+FAA+F;AAC/F,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,OAAO,mBAAmB,CAAC,EAAE,CAAC,CAAC;AACjC,CAAC","sourcesContent":["import { escapeCssIdentifier } from './escape-css-identifier';\n\n/** Escape an element id for the `tag#<id>` selector form shared by strategies and fallback. */\nexport function escapeIdForCss(id: string): string {\n return escapeCssIdentifier(id);\n}\n"]}
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import { ResolvedSelectorConfig } from '../types';
|
|
2
|
+
/**
|
|
3
|
+
* Shared helper that the `stableId` strategy (in this PR) and the
|
|
4
|
+
* `fallback-css-path` walker (in the orchestration PR) both consult to decide
|
|
5
|
+
* whether an element's id is usable as a selector anchor.
|
|
6
|
+
*
|
|
7
|
+
* Resolution order:
|
|
8
|
+
*
|
|
9
|
+
* 1. Check the customer's explicit-tracking attribute. If set with an empty
|
|
10
|
+
* value (e.g. `data-amp-track-id=""`), that's an explicit suppression
|
|
11
|
+
* signal — the customer is telling us to ignore this element's id even
|
|
12
|
+
* if it would otherwise look stable. Return null.
|
|
13
|
+
* 2. Read the element's id. If absent or empty, return null.
|
|
14
|
+
* 3. Check the id against the autogenerated-id pattern pack. If matched,
|
|
15
|
+
* return null (the algorithm should walk past this element).
|
|
16
|
+
* 4. Otherwise return the id.
|
|
17
|
+
*
|
|
18
|
+
* The single point of consultation means the strategy and the fallback always
|
|
19
|
+
* agree on what's a usable id — no chance of one component filtering an id
|
|
20
|
+
* while another uses it anyway.
|
|
21
|
+
*/
|
|
22
|
+
export declare function getStableId(el: Element, cfg: ResolvedSelectorConfig): string | null;
|
|
23
|
+
//# sourceMappingURL=get-stable-id.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"get-stable-id.d.ts","sourceRoot":"","sources":["../../../src/helpers/get-stable-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGlD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,sBAAsB,GAAG,MAAM,GAAG,IAAI,CAoBnF"}
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { isStableId } from '../patterns/autogenerated-ids';
|
|
2
|
+
/**
|
|
3
|
+
* Shared helper that the `stableId` strategy (in this PR) and the
|
|
4
|
+
* `fallback-css-path` walker (in the orchestration PR) both consult to decide
|
|
5
|
+
* whether an element's id is usable as a selector anchor.
|
|
6
|
+
*
|
|
7
|
+
* Resolution order:
|
|
8
|
+
*
|
|
9
|
+
* 1. Check the customer's explicit-tracking attribute. If set with an empty
|
|
10
|
+
* value (e.g. `data-amp-track-id=""`), that's an explicit suppression
|
|
11
|
+
* signal — the customer is telling us to ignore this element's id even
|
|
12
|
+
* if it would otherwise look stable. Return null.
|
|
13
|
+
* 2. Read the element's id. If absent or empty, return null.
|
|
14
|
+
* 3. Check the id against the autogenerated-id pattern pack. If matched,
|
|
15
|
+
* return null (the algorithm should walk past this element).
|
|
16
|
+
* 4. Otherwise return the id.
|
|
17
|
+
*
|
|
18
|
+
* The single point of consultation means the strategy and the fallback always
|
|
19
|
+
* agree on what's a usable id — no chance of one component filtering an id
|
|
20
|
+
* while another uses it anyway.
|
|
21
|
+
*/
|
|
22
|
+
export function getStableId(el, cfg) {
|
|
23
|
+
// 1. Suppression signal: empty explicit-tracking attribute on this element.
|
|
24
|
+
var trackAttr = el.getAttribute(cfg.explicitTrackingAttribute);
|
|
25
|
+
if (trackAttr !== null && trackAttr === '') {
|
|
26
|
+
return null;
|
|
27
|
+
}
|
|
28
|
+
// 2. Id presence.
|
|
29
|
+
var id = el.getAttribute('id');
|
|
30
|
+
if (id === null || id === '') {
|
|
31
|
+
return null;
|
|
32
|
+
}
|
|
33
|
+
// 3. Autogenerated-pattern filter.
|
|
34
|
+
if (!isStableId(id, cfg.autogeneratedIdPatterns)) {
|
|
35
|
+
return null;
|
|
36
|
+
}
|
|
37
|
+
// 4. Stable.
|
|
38
|
+
return id;
|
|
39
|
+
}
|
|
40
|
+
//# sourceMappingURL=get-stable-id.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"get-stable-id.js","sourceRoot":"","sources":["../../../src/helpers/get-stable-id.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,WAAW,CAAC,EAAW,EAAE,GAA2B;IAClE,4EAA4E;IAC5E,IAAM,SAAS,GAAG,EAAE,CAAC,YAAY,CAAC,GAAG,CAAC,yBAAyB,CAAC,CAAC;IACjE,IAAI,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,EAAE,EAAE;QAC1C,OAAO,IAAI,CAAC;KACb;IAED,kBAAkB;IAClB,IAAM,EAAE,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,EAAE,EAAE;QAC5B,OAAO,IAAI,CAAC;KACb;IAED,mCAAmC;IACnC,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,GAAG,CAAC,uBAAuB,CAAC,EAAE;QAChD,OAAO,IAAI,CAAC;KACb;IAED,aAAa;IACb,OAAO,EAAE,CAAC;AACZ,CAAC","sourcesContent":["import { ResolvedSelectorConfig } from '../types';\nimport { isStableId } from '../patterns/autogenerated-ids';\n\n/**\n * Shared helper that the `stableId` strategy (in this PR) and the\n * `fallback-css-path` walker (in the orchestration PR) both consult to decide\n * whether an element's id is usable as a selector anchor.\n *\n * Resolution order:\n *\n * 1. Check the customer's explicit-tracking attribute. If set with an empty\n * value (e.g. `data-amp-track-id=\"\"`), that's an explicit suppression\n * signal — the customer is telling us to ignore this element's id even\n * if it would otherwise look stable. Return null.\n * 2. Read the element's id. If absent or empty, return null.\n * 3. Check the id against the autogenerated-id pattern pack. If matched,\n * return null (the algorithm should walk past this element).\n * 4. Otherwise return the id.\n *\n * The single point of consultation means the strategy and the fallback always\n * agree on what's a usable id — no chance of one component filtering an id\n * while another uses it anyway.\n */\nexport function getStableId(el: Element, cfg: ResolvedSelectorConfig): string | null {\n // 1. Suppression signal: empty explicit-tracking attribute on this element.\n const trackAttr = el.getAttribute(cfg.explicitTrackingAttribute);\n if (trackAttr !== null && trackAttr === '') {\n return null;\n }\n\n // 2. Id presence.\n const id = el.getAttribute('id');\n if (id === null || id === '') {\n return null;\n }\n\n // 3. Autogenerated-pattern filter.\n if (!isStableId(id, cfg.autogeneratedIdPatterns)) {\n return null;\n }\n\n // 4. Stable.\n return id;\n}\n"]}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @amplitude/element-selector
|
|
3
|
+
*
|
|
4
|
+
* Shared element-selector algorithm consumed by autocapture, the
|
|
5
|
+
* app.amplitude.com tagging UI, and the Chrome extension visual tagger.
|
|
6
|
+
*
|
|
7
|
+
* This file is the package's public API surface. The orchestrator, fallback,
|
|
8
|
+
* config resolver, and engine factory compose on top of the primitives
|
|
9
|
+
* (types, pattern packs, helpers, strategies) to produce the runtime engine
|
|
10
|
+
* consumers actually call.
|
|
11
|
+
*
|
|
12
|
+
* See the design doc:
|
|
13
|
+
* packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
|
|
14
|
+
*/
|
|
15
|
+
export declare const PACKAGE_NAME = "@amplitude/element-selector";
|
|
16
|
+
export type { Strategy, StrategyContext, ResolvedSelectorConfig, ElementSelectorRemoteConfig, ElementSelectorLogger, SelectorEngine, } from './types';
|
|
17
|
+
export { DEFAULT_AUTOGENERATED_ID_PATTERNS, compile as compileAutogeneratedIdPatterns, isStableId, } from './patterns/autogenerated-ids';
|
|
18
|
+
export { DEFAULT_UNSTABLE_CLASS_PATTERNS, compile as compileUnstableClassPatterns, filterClasses, } from './patterns/unstable-classes';
|
|
19
|
+
export { getStableId } from './helpers/get-stable-id';
|
|
20
|
+
export { describeRelative } from './helpers/describe-relative';
|
|
21
|
+
export { explicitTrackingAttribute } from './strategies/explicit-tracking-attribute';
|
|
22
|
+
export { stableId as stableIdStrategy } from './strategies/stable-id';
|
|
23
|
+
export { runOrchestrator, DEFAULT_STRATEGIES } from './orchestrator';
|
|
24
|
+
export type { OrchestratorOptions } from './orchestrator';
|
|
25
|
+
export { fallbackCssPath } from './fallback-css-path';
|
|
26
|
+
export { resolveSelectorConfig, DEFAULT_RESOLVED_CONFIG } from './config/resolve-config';
|
|
27
|
+
export { createSelectorEngine } from './engine';
|
|
28
|
+
export type { CreateSelectorEngineOptions } from './engine';
|
|
29
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,YAAY,gCAAgC,CAAC;AAG1D,YAAY,EACV,QAAQ,EACR,eAAe,EACf,sBAAsB,EACtB,2BAA2B,EAC3B,qBAAqB,EACrB,cAAc,GACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,iCAAiC,EACjC,OAAO,IAAI,8BAA8B,EACzC,UAAU,GACX,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,+BAA+B,EAC/B,OAAO,IAAI,4BAA4B,EACvC,aAAa,GACd,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAG/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AACrF,OAAO,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAKtE,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACrE,YAAY,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAGtD,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAGzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,YAAY,EAAE,2BAA2B,EAAE,MAAM,UAAU,CAAC"}
|
package/lib/esm/index.js
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @amplitude/element-selector
|
|
3
|
+
*
|
|
4
|
+
* Shared element-selector algorithm consumed by autocapture, the
|
|
5
|
+
* app.amplitude.com tagging UI, and the Chrome extension visual tagger.
|
|
6
|
+
*
|
|
7
|
+
* This file is the package's public API surface. The orchestrator, fallback,
|
|
8
|
+
* config resolver, and engine factory compose on top of the primitives
|
|
9
|
+
* (types, pattern packs, helpers, strategies) to produce the runtime engine
|
|
10
|
+
* consumers actually call.
|
|
11
|
+
*
|
|
12
|
+
* See the design doc:
|
|
13
|
+
* packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
|
|
14
|
+
*/
|
|
15
|
+
export var PACKAGE_NAME = '@amplitude/element-selector';
|
|
16
|
+
// ===== Pattern packs =====
|
|
17
|
+
export { DEFAULT_AUTOGENERATED_ID_PATTERNS, compile as compileAutogeneratedIdPatterns, isStableId, } from './patterns/autogenerated-ids';
|
|
18
|
+
export { DEFAULT_UNSTABLE_CLASS_PATTERNS, compile as compileUnstableClassPatterns, filterClasses, } from './patterns/unstable-classes';
|
|
19
|
+
// ===== Helpers =====
|
|
20
|
+
export { getStableId } from './helpers/get-stable-id';
|
|
21
|
+
export { describeRelative } from './helpers/describe-relative';
|
|
22
|
+
// ===== Strategies =====
|
|
23
|
+
export { explicitTrackingAttribute } from './strategies/explicit-tracking-attribute';
|
|
24
|
+
export { stableId as stableIdStrategy } from './strategies/stable-id';
|
|
25
|
+
// ===== Orchestrator + fallback =====
|
|
26
|
+
// Exposed publicly so the dashboard / Chrome extension can call them ad-hoc
|
|
27
|
+
// without instantiating a full engine — useful for preview / debugging flows.
|
|
28
|
+
export { runOrchestrator, DEFAULT_STRATEGIES } from './orchestrator';
|
|
29
|
+
export { fallbackCssPath } from './fallback-css-path';
|
|
30
|
+
// ===== Config resolver =====
|
|
31
|
+
export { resolveSelectorConfig, DEFAULT_RESOLVED_CONFIG } from './config/resolve-config';
|
|
32
|
+
// ===== Engine factory =====
|
|
33
|
+
export { createSelectorEngine } from './engine';
|
|
34
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,CAAC,IAAM,YAAY,GAAG,6BAA6B,CAAC;AAY1D,4BAA4B;AAC5B,OAAO,EACL,iCAAiC,EACjC,OAAO,IAAI,8BAA8B,EACzC,UAAU,GACX,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EACL,+BAA+B,EAC/B,OAAO,IAAI,4BAA4B,EACvC,aAAa,GACd,MAAM,6BAA6B,CAAC;AAErC,sBAAsB;AACtB,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAE/D,yBAAyB;AACzB,OAAO,EAAE,yBAAyB,EAAE,MAAM,0CAA0C,CAAC;AACrF,OAAO,EAAE,QAAQ,IAAI,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEtE,sCAAsC;AACtC,4EAA4E;AAC5E,8EAA8E;AAC9E,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAErE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,8BAA8B;AAC9B,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEzF,6BAA6B;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC","sourcesContent":["/**\n * @amplitude/element-selector\n *\n * Shared element-selector algorithm consumed by autocapture, the\n * app.amplitude.com tagging UI, and the Chrome extension visual tagger.\n *\n * This file is the package's public API surface. The orchestrator, fallback,\n * config resolver, and engine factory compose on top of the primitives\n * (types, pattern packs, helpers, strategies) to produce the runtime engine\n * consumers actually call.\n *\n * See the design doc:\n * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md\n */\n\nexport const PACKAGE_NAME = '@amplitude/element-selector';\n\n// ===== Types =====\nexport type {\n Strategy,\n StrategyContext,\n ResolvedSelectorConfig,\n ElementSelectorRemoteConfig,\n ElementSelectorLogger,\n SelectorEngine,\n} from './types';\n\n// ===== Pattern packs =====\nexport {\n DEFAULT_AUTOGENERATED_ID_PATTERNS,\n compile as compileAutogeneratedIdPatterns,\n isStableId,\n} from './patterns/autogenerated-ids';\n\nexport {\n DEFAULT_UNSTABLE_CLASS_PATTERNS,\n compile as compileUnstableClassPatterns,\n filterClasses,\n} from './patterns/unstable-classes';\n\n// ===== Helpers =====\nexport { getStableId } from './helpers/get-stable-id';\nexport { describeRelative } from './helpers/describe-relative';\n\n// ===== Strategies =====\nexport { explicitTrackingAttribute } from './strategies/explicit-tracking-attribute';\nexport { stableId as stableIdStrategy } from './strategies/stable-id';\n\n// ===== Orchestrator + fallback =====\n// Exposed publicly so the dashboard / Chrome extension can call them ad-hoc\n// without instantiating a full engine — useful for preview / debugging flows.\nexport { runOrchestrator, DEFAULT_STRATEGIES } from './orchestrator';\nexport type { OrchestratorOptions } from './orchestrator';\nexport { fallbackCssPath } from './fallback-css-path';\n\n// ===== Config resolver =====\nexport { resolveSelectorConfig, DEFAULT_RESOLVED_CONFIG } from './config/resolve-config';\n\n// ===== Engine factory =====\nexport { createSelectorEngine } from './engine';\nexport type { CreateSelectorEngineOptions } from './engine';\n"]}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Orchestrator — the entry point for the v1 element-selector algorithm.
|
|
3
|
+
*
|
|
4
|
+
* Given a click target, the orchestrator walks from the target up through its
|
|
5
|
+
* ancestors and tries each registered strategy at each level. The first
|
|
6
|
+
* strategy that returns a non-null candidate (and produces a selector that
|
|
7
|
+
* resolves uniquely under the scope) wins; the trail of intermediate elements
|
|
8
|
+
* between the anchor and the original target is then expressed as a positional
|
|
9
|
+
* descent via `describeRelative`.
|
|
10
|
+
*
|
|
11
|
+
* Two-pass design: every ancestor is tried under the `explicitTrackingAttribute`
|
|
12
|
+
* strategy first, then the entire walk repeats with `stableId`. This ordering
|
|
13
|
+
* means an explicit anchor anywhere up the tree always beats a stable id deeper
|
|
14
|
+
* down — the design doc describes this as the "customer intent overrides
|
|
15
|
+
* structural inference" rule.
|
|
16
|
+
*
|
|
17
|
+
* The orchestrator does not own the fallback. When no strategy + walk produces
|
|
18
|
+
* a unique selector, it returns `null` and the engine wires the
|
|
19
|
+
* `fallback-css-path` path in instead. Keeping the fallback outside the
|
|
20
|
+
* orchestrator keeps the strategy chain testable in isolation.
|
|
21
|
+
*
|
|
22
|
+
* See the design doc:
|
|
23
|
+
* packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
|
|
24
|
+
*/
|
|
25
|
+
import { ElementSelectorLogger, ResolvedSelectorConfig, Strategy } from './types';
|
|
26
|
+
/**
|
|
27
|
+
* Default strategy chain in priority order. Used by the engine factory when the
|
|
28
|
+
* caller doesn't provide an explicit list. Exported for diagnostics — tests
|
|
29
|
+
* import this so they don't have to duplicate the list.
|
|
30
|
+
*/
|
|
31
|
+
export declare const DEFAULT_STRATEGIES: ReadonlyArray<Strategy>;
|
|
32
|
+
export interface OrchestratorOptions {
|
|
33
|
+
/** Strategy chain. Defaults to `DEFAULT_STRATEGIES`. Order = priority. */
|
|
34
|
+
strategies?: ReadonlyArray<Strategy>;
|
|
35
|
+
/** Document or shadow root used for uniqueness checks. Defaults to the target's owner document. */
|
|
36
|
+
scope?: ParentNode;
|
|
37
|
+
/**
|
|
38
|
+
* Optional logger. When provided, the orchestrator emits a `debug` log if a
|
|
39
|
+
* strategy produces a malformed selector that throws during the uniqueness
|
|
40
|
+
* check — useful for diagnosing strategy bugs without crashing the engine.
|
|
41
|
+
*/
|
|
42
|
+
logger?: ElementSelectorLogger;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Try to produce a CSS selector for `el` using the strategy chain.
|
|
46
|
+
*
|
|
47
|
+
* Returns the composed selector string on success, or `null` if every strategy
|
|
48
|
+
* declined at every walked ancestor. Callers (the engine) treat `null` as the
|
|
49
|
+
* signal to invoke the fallback walker.
|
|
50
|
+
*
|
|
51
|
+
* Selector format on success:
|
|
52
|
+
*
|
|
53
|
+
* - Anchor only (target itself was an anchor): `<anchor-selector>`
|
|
54
|
+
* - Anchor + trail (anchor was an ancestor): `<anchor-selector> > <descent>`
|
|
55
|
+
*
|
|
56
|
+
* Where `<anchor-selector>` is whatever the winning strategy returned for the
|
|
57
|
+
* anchor element (e.g. `[data-amp-track-id="login-form"]` or `div#hero`), and
|
|
58
|
+
* `<descent>` is `describeRelative(anchor, trail)`.
|
|
59
|
+
*/
|
|
60
|
+
export declare function runOrchestrator(el: Element, config: ResolvedSelectorConfig, options?: OrchestratorOptions): string | null;
|
|
61
|
+
//# sourceMappingURL=orchestrator.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,QAAQ,EAAmB,MAAM,SAAS,CAAC;AAKnG;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,aAAa,CAAC,QAAQ,CAAiD,CAAC;AAEzG,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,UAAU,CAAC,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACrC,mGAAmG;IACnG,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAChC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,sBAAsB,EAC9B,OAAO,GAAE,mBAAwB,GAChC,MAAM,GAAG,IAAI,CAoCf"}
|