@amplitude/element-selector 0.0.1 → 0.1.1-featelement-selector-v1.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 +139 -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/generate-selector.d.ts +54 -0
- package/lib/cjs/generate-selector.d.ts.map +1 -0
- package/lib/cjs/generate-selector.js +76 -0
- package/lib/cjs/generate-selector.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 +31 -0
- package/lib/cjs/index.d.ts.map +1 -0
- package/lib/cjs/index.js +71 -0
- package/lib/cjs/index.js.map +1 -0
- package/lib/cjs/legacy-css-path.d.ts +84 -0
- package/lib/cjs/legacy-css-path.d.ts.map +1 -0
- package/lib/cjs/legacy-css-path.js +230 -0
- package/lib/cjs/legacy-css-path.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 +135 -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/generate-selector.d.ts +54 -0
- package/lib/esm/generate-selector.d.ts.map +1 -0
- package/lib/esm/generate-selector.js +72 -0
- package/lib/esm/generate-selector.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 +31 -0
- package/lib/esm/index.d.ts.map +1 -0
- package/lib/esm/index.js +50 -0
- package/lib/esm/index.js.map +1 -0
- package/lib/esm/legacy-css-path.d.ts +84 -0
- package/lib/esm/legacy-css-path.d.ts.map +1 -0
- package/lib/esm/legacy-css-path.js +226 -0
- package/lib/esm/legacy-css-path.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,54 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Top-level chokepoint for "generate a selector for this element."
|
|
3
|
+
*
|
|
4
|
+
* Both the SDK plugin (`plugin-autocapture-browser`) and the dashboard
|
|
5
|
+
* (`session-replay-ui`) used to maintain their own copy of this routing logic:
|
|
6
|
+
*
|
|
7
|
+
* if (config.enabled && engine) return engine.generate(el);
|
|
8
|
+
* else return cssPath(el, false);
|
|
9
|
+
*
|
|
10
|
+
* Two consumers, two routers, two locally-bundled copies of `cssPath`. As soon
|
|
11
|
+
* as we considered a third consumer (Chrome extension visual tagger, future
|
|
12
|
+
* tagging surfaces) the duplication became untenable — bug fixes had to land
|
|
13
|
+
* three places and the kill-switch semantics could drift between them.
|
|
14
|
+
*
|
|
15
|
+
* Moving the kill switch inside `engine.generate` covered the "engine present"
|
|
16
|
+
* case. This helper covers the remaining "engine is null" case that some
|
|
17
|
+
* consumers genuinely have:
|
|
18
|
+
*
|
|
19
|
+
* - dashboard's `useElementSelectorEngineContext()` returns
|
|
20
|
+
* `{ engine: null }` when no provider is mounted (tests, content-renderer
|
|
21
|
+
* paths, future call sites outside the canonical mount tree).
|
|
22
|
+
* - Chrome extension boots before the customer's SDK has stood up an engine
|
|
23
|
+
* on the page; reads `null` from `window.amplitude.elementSelector` until
|
|
24
|
+
* the SDK init finishes.
|
|
25
|
+
*
|
|
26
|
+
* In those cases, callers want the legacy `cssPath` selector — same shape the
|
|
27
|
+
* SDK is emitting in production for orgs without the engine. This helper makes
|
|
28
|
+
* that explicit and centralizes the rule so future consumers don't reinvent
|
|
29
|
+
* it.
|
|
30
|
+
*/
|
|
31
|
+
import { ResolvedSelectorConfig, SelectorEngine } from './types';
|
|
32
|
+
/**
|
|
33
|
+
* Generate a selector for `el`, transparently routing to the legacy
|
|
34
|
+
* `cssPath` walker when no engine is available.
|
|
35
|
+
*
|
|
36
|
+
* Why this signature (engine + config separately, rather than just engine):
|
|
37
|
+
* the dashboard's inert context has `engine: null` but still carries a
|
|
38
|
+
* resolved config. Both `null`-engine and engine-with-`enabled: false`
|
|
39
|
+
* collapse to "legacy `cssPath`", and we want the same one-line call site
|
|
40
|
+
* to handle both. When the engine *is* present, this just delegates — the
|
|
41
|
+
* engine's own kill switch handles `enabled === false`.
|
|
42
|
+
*
|
|
43
|
+
* Never throws. Returns the empty string in the pathological case where the
|
|
44
|
+
* legacy walker itself can't produce one (non-element nodes; environments
|
|
45
|
+
* missing `CSS.escape`).
|
|
46
|
+
*
|
|
47
|
+
* @param el DOM element to identify.
|
|
48
|
+
* @param engine Live `SelectorEngine`, or `null` when no engine is mounted.
|
|
49
|
+
* @param config Resolved selector config. Only consulted in the null-engine
|
|
50
|
+
* branch; when `engine` is present, the engine consults its
|
|
51
|
+
* own internal config.
|
|
52
|
+
*/
|
|
53
|
+
export declare const generateSelector: (el: Element, engine: SelectorEngine | null, config: ResolvedSelectorConfig) => string;
|
|
54
|
+
//# sourceMappingURL=generate-selector.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"generate-selector.d.ts","sourceRoot":"","sources":["../../src/generate-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGjE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,gBAAgB,OACvB,OAAO,UACH,cAAc,GAAG,IAAI,UACrB,sBAAsB,KAC7B,MAiBF,CAAC"}
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Top-level chokepoint for "generate a selector for this element."
|
|
3
|
+
*
|
|
4
|
+
* Both the SDK plugin (`plugin-autocapture-browser`) and the dashboard
|
|
5
|
+
* (`session-replay-ui`) used to maintain their own copy of this routing logic:
|
|
6
|
+
*
|
|
7
|
+
* if (config.enabled && engine) return engine.generate(el);
|
|
8
|
+
* else return cssPath(el, false);
|
|
9
|
+
*
|
|
10
|
+
* Two consumers, two routers, two locally-bundled copies of `cssPath`. As soon
|
|
11
|
+
* as we considered a third consumer (Chrome extension visual tagger, future
|
|
12
|
+
* tagging surfaces) the duplication became untenable — bug fixes had to land
|
|
13
|
+
* three places and the kill-switch semantics could drift between them.
|
|
14
|
+
*
|
|
15
|
+
* Moving the kill switch inside `engine.generate` covered the "engine present"
|
|
16
|
+
* case. This helper covers the remaining "engine is null" case that some
|
|
17
|
+
* consumers genuinely have:
|
|
18
|
+
*
|
|
19
|
+
* - dashboard's `useElementSelectorEngineContext()` returns
|
|
20
|
+
* `{ engine: null }` when no provider is mounted (tests, content-renderer
|
|
21
|
+
* paths, future call sites outside the canonical mount tree).
|
|
22
|
+
* - Chrome extension boots before the customer's SDK has stood up an engine
|
|
23
|
+
* on the page; reads `null` from `window.amplitude.elementSelector` until
|
|
24
|
+
* the SDK init finishes.
|
|
25
|
+
*
|
|
26
|
+
* In those cases, callers want the legacy `cssPath` selector — same shape the
|
|
27
|
+
* SDK is emitting in production for orgs without the engine. This helper makes
|
|
28
|
+
* that explicit and centralizes the rule so future consumers don't reinvent
|
|
29
|
+
* it.
|
|
30
|
+
*/
|
|
31
|
+
import { legacyCssPath } from './legacy-css-path';
|
|
32
|
+
/**
|
|
33
|
+
* Generate a selector for `el`, transparently routing to the legacy
|
|
34
|
+
* `cssPath` walker when no engine is available.
|
|
35
|
+
*
|
|
36
|
+
* Why this signature (engine + config separately, rather than just engine):
|
|
37
|
+
* the dashboard's inert context has `engine: null` but still carries a
|
|
38
|
+
* resolved config. Both `null`-engine and engine-with-`enabled: false`
|
|
39
|
+
* collapse to "legacy `cssPath`", and we want the same one-line call site
|
|
40
|
+
* to handle both. When the engine *is* present, this just delegates — the
|
|
41
|
+
* engine's own kill switch handles `enabled === false`.
|
|
42
|
+
*
|
|
43
|
+
* Never throws. Returns the empty string in the pathological case where the
|
|
44
|
+
* legacy walker itself can't produce one (non-element nodes; environments
|
|
45
|
+
* missing `CSS.escape`).
|
|
46
|
+
*
|
|
47
|
+
* @param el DOM element to identify.
|
|
48
|
+
* @param engine Live `SelectorEngine`, or `null` when no engine is mounted.
|
|
49
|
+
* @param config Resolved selector config. Only consulted in the null-engine
|
|
50
|
+
* branch; when `engine` is present, the engine consults its
|
|
51
|
+
* own internal config.
|
|
52
|
+
*/
|
|
53
|
+
export var generateSelector = function (el, engine, config) {
|
|
54
|
+
if (engine) {
|
|
55
|
+
// The engine has its own kill switch (`config.enabled === false` →
|
|
56
|
+
// legacy cssPath) and its own try/catch safety net. Trust it.
|
|
57
|
+
return engine.generate(el);
|
|
58
|
+
}
|
|
59
|
+
// Engine-null branch. We don't have a live engine to consult, so we route
|
|
60
|
+
// straight to the legacy walker — the same selector the SDK would be
|
|
61
|
+
// emitting if `config.enabled === false`. `config` is accepted for symmetry
|
|
62
|
+
// with the engine signature and so future versions can extend behavior
|
|
63
|
+
// without a breaking change.
|
|
64
|
+
void config;
|
|
65
|
+
try {
|
|
66
|
+
return legacyCssPath(el);
|
|
67
|
+
}
|
|
68
|
+
catch (_a) {
|
|
69
|
+
return '';
|
|
70
|
+
}
|
|
71
|
+
};
|
|
72
|
+
//# sourceMappingURL=generate-selector.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"generate-selector.js","sourceRoot":"","sources":["../../src/generate-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,IAAM,gBAAgB,GAAG,UAC9B,EAAW,EACX,MAA6B,EAC7B,MAA8B;IAE9B,IAAI,MAAM,EAAE;QACV,mEAAmE;QACnE,8DAA8D;QAC9D,OAAO,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;KAC5B;IACD,0EAA0E;IAC1E,qEAAqE;IACrE,4EAA4E;IAC5E,uEAAuE;IACvE,6BAA6B;IAC7B,KAAK,MAAM,CAAC;IACZ,IAAI;QACF,OAAO,aAAa,CAAC,EAAE,CAAC,CAAC;KAC1B;IAAC,WAAM;QACN,OAAO,EAAE,CAAC;KACX;AACH,CAAC,CAAC","sourcesContent":["/**\n * Top-level chokepoint for \"generate a selector for this element.\"\n *\n * Both the SDK plugin (`plugin-autocapture-browser`) and the dashboard\n * (`session-replay-ui`) used to maintain their own copy of this routing logic:\n *\n * if (config.enabled && engine) return engine.generate(el);\n * else return cssPath(el, false);\n *\n * Two consumers, two routers, two locally-bundled copies of `cssPath`. As soon\n * as we considered a third consumer (Chrome extension visual tagger, future\n * tagging surfaces) the duplication became untenable — bug fixes had to land\n * three places and the kill-switch semantics could drift between them.\n *\n * Moving the kill switch inside `engine.generate` covered the \"engine present\"\n * case. This helper covers the remaining \"engine is null\" case that some\n * consumers genuinely have:\n *\n * - dashboard's `useElementSelectorEngineContext()` returns\n * `{ engine: null }` when no provider is mounted (tests, content-renderer\n * paths, future call sites outside the canonical mount tree).\n * - Chrome extension boots before the customer's SDK has stood up an engine\n * on the page; reads `null` from `window.amplitude.elementSelector` until\n * the SDK init finishes.\n *\n * In those cases, callers want the legacy `cssPath` selector — same shape the\n * SDK is emitting in production for orgs without the engine. This helper makes\n * that explicit and centralizes the rule so future consumers don't reinvent\n * it.\n */\n\nimport { ResolvedSelectorConfig, SelectorEngine } from './types';\nimport { legacyCssPath } from './legacy-css-path';\n\n/**\n * Generate a selector for `el`, transparently routing to the legacy\n * `cssPath` walker when no engine is available.\n *\n * Why this signature (engine + config separately, rather than just engine):\n * the dashboard's inert context has `engine: null` but still carries a\n * resolved config. Both `null`-engine and engine-with-`enabled: false`\n * collapse to \"legacy `cssPath`\", and we want the same one-line call site\n * to handle both. When the engine *is* present, this just delegates — the\n * engine's own kill switch handles `enabled === false`.\n *\n * Never throws. Returns the empty string in the pathological case where the\n * legacy walker itself can't produce one (non-element nodes; environments\n * missing `CSS.escape`).\n *\n * @param el DOM element to identify.\n * @param engine Live `SelectorEngine`, or `null` when no engine is mounted.\n * @param config Resolved selector config. Only consulted in the null-engine\n * branch; when `engine` is present, the engine consults its\n * own internal config.\n */\nexport const generateSelector = (\n el: Element,\n engine: SelectorEngine | null,\n config: ResolvedSelectorConfig,\n): string => {\n if (engine) {\n // The engine has its own kill switch (`config.enabled === false` →\n // legacy cssPath) and its own try/catch safety net. Trust it.\n return engine.generate(el);\n }\n // Engine-null branch. We don't have a live engine to consult, so we route\n // straight to the legacy walker — the same selector the SDK would be\n // emitting if `config.enabled === false`. `config` is accepted for symmetry\n // with the engine signature and so future versions can extend behavior\n // without a breaking change.\n void config;\n try {\n return legacyCssPath(el);\n } catch {\n return '';\n }\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,31 @@
|
|
|
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 { legacyCssPath } from './legacy-css-path';
|
|
27
|
+
export { resolveSelectorConfig, DEFAULT_RESOLVED_CONFIG } from './config/resolve-config';
|
|
28
|
+
export { createSelectorEngine } from './engine';
|
|
29
|
+
export type { CreateSelectorEngineOptions } from './engine';
|
|
30
|
+
export { generateSelector } from './generate-selector';
|
|
31
|
+
//# 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;AAWtD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlD,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;AAO5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC"}
|
package/lib/esm/index.js
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
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
|
+
// ===== Legacy walker =====
|
|
31
|
+
// Canonical home for the Chromium-DevTools-derived `cssPath` algorithm.
|
|
32
|
+
// Both `plugin-autocapture-browser` and `session-replay-ui` historically
|
|
33
|
+
// shipped their own copies kept in sync by comment; both will switch to
|
|
34
|
+
// re-exporting from here so the two can never drift again. End consumers
|
|
35
|
+
// rarely need to call this directly — `engine.generate` and
|
|
36
|
+
// `generateSelector` route through it automatically — but it's exported so
|
|
37
|
+
// the SDK and dashboard can drop their local copies without breaking
|
|
38
|
+
// downstream imports.
|
|
39
|
+
export { legacyCssPath } from './legacy-css-path';
|
|
40
|
+
// ===== Config resolver =====
|
|
41
|
+
export { resolveSelectorConfig, DEFAULT_RESOLVED_CONFIG } from './config/resolve-config';
|
|
42
|
+
// ===== Engine factory =====
|
|
43
|
+
export { createSelectorEngine } from './engine';
|
|
44
|
+
// ===== Top-level selector entry point =====
|
|
45
|
+
// Use this from React contexts / boot-time call sites where the engine may
|
|
46
|
+
// not yet be available. When the engine *is* present, just call
|
|
47
|
+
// `engine.generate(el)` directly — it has the same kill-switch semantics
|
|
48
|
+
// baked in.
|
|
49
|
+
export { generateSelector } from './generate-selector';
|
|
50
|
+
//# 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,4BAA4B;AAC5B,wEAAwE;AACxE,yEAAyE;AACzE,wEAAwE;AACxE,yEAAyE;AACzE,4DAA4D;AAC5D,2EAA2E;AAC3E,qEAAqE;AACrE,sBAAsB;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,8BAA8B;AAC9B,OAAO,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAEzF,6BAA6B;AAC7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAGhD,6CAA6C;AAC7C,2EAA2E;AAC3E,gEAAgE;AAChE,yEAAyE;AACzE,YAAY;AACZ,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,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// ===== Legacy walker =====\n// Canonical home for the Chromium-DevTools-derived `cssPath` algorithm.\n// Both `plugin-autocapture-browser` and `session-replay-ui` historically\n// shipped their own copies kept in sync by comment; both will switch to\n// re-exporting from here so the two can never drift again. End consumers\n// rarely need to call this directly — `engine.generate` and\n// `generateSelector` route through it automatically — but it's exported so\n// the SDK and dashboard can drop their local copies without breaking\n// downstream imports.\nexport { legacyCssPath } from './legacy-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\n// ===== Top-level selector entry point =====\n// Use this from React contexts / boot-time call sites where the engine may\n// not yet be available. When the engine *is* present, just call\n// `engine.generate(el)` directly — it has the same kill-switch semantics\n// baked in.\nexport { generateSelector } from './generate-selector';\n"]}
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Canonical legacy CSS-path walker.
|
|
3
|
+
*
|
|
4
|
+
* This is the Chromium-DevTools-derived `cssPath` algorithm that was the only
|
|
5
|
+
* selector source autocapture used before the strategy engine existed. It still
|
|
6
|
+
* matters in two situations:
|
|
7
|
+
*
|
|
8
|
+
* 1. The kill switch: when `ResolvedSelectorConfig.enabled === false`, the
|
|
9
|
+
* engine routes here so a customer who flips the engine off mid-session
|
|
10
|
+
* keeps emitting the same selectors their downstream zones and cohorts
|
|
11
|
+
* were built against.
|
|
12
|
+
* 2. The safety net: when the strategy chain or its internal walker throws
|
|
13
|
+
* anything unexpected, the engine catches and falls back here. The
|
|
14
|
+
* autocapture click handler must always produce *some* selector — a
|
|
15
|
+
* runtime exception in selector generation is a worse outcome than a
|
|
16
|
+
* slightly less stable selector.
|
|
17
|
+
*
|
|
18
|
+
* Until this file existed, the algorithm was duplicated in two places kept
|
|
19
|
+
* "in sync by comment":
|
|
20
|
+
*
|
|
21
|
+
* - `packages/plugin-autocapture-browser/src/libs/element-path.ts`
|
|
22
|
+
* - `javascript/packages/session-replay-ui/src/utils/element-path.ts`
|
|
23
|
+
*
|
|
24
|
+
* Both will eventually re-export from here so divergence becomes impossible.
|
|
25
|
+
*
|
|
26
|
+
* Behavior is byte-identical to those two copies — selectors emitted by this
|
|
27
|
+
* function for a given element MUST match what the SDK has been emitting in
|
|
28
|
+
* production. Do not "fix" the selector format without an explicit version
|
|
29
|
+
* bump and a coordinated dashboard rollout.
|
|
30
|
+
*
|
|
31
|
+
* **Why this lives in the package, not as an optional consumer concern:**
|
|
32
|
+
*
|
|
33
|
+
* Every consumer that uses `engine.generate(el)` benefits from the kill
|
|
34
|
+
* switch and the safety net automatically. Without this, each new consumer
|
|
35
|
+
* (Chrome extension visual tagger, future tagging surfaces) has to
|
|
36
|
+
* reimplement the same router and the same legacy walker. We learned that
|
|
37
|
+
* the hard way — by writing the same `if (config.enabled && engine) ...
|
|
38
|
+
* else cssPath()` block in two repositories with two copies of cssPath.
|
|
39
|
+
*
|
|
40
|
+
* Code is adapted from The Chromium Authors.
|
|
41
|
+
* Source: https://github.com/ChromeDevTools/devtools-frontend/blob/main/front_end/panels/elements/DOMPath.ts#L14
|
|
42
|
+
* License: BSD-style license
|
|
43
|
+
*
|
|
44
|
+
* Copyright 2014 The Chromium Authors
|
|
45
|
+
*
|
|
46
|
+
* Redistribution and use in source and binary forms, with or without
|
|
47
|
+
* modification, are permitted provided that the following conditions are
|
|
48
|
+
* met:
|
|
49
|
+
*
|
|
50
|
+
* * Redistributions of source code must retain the above copyright
|
|
51
|
+
* notice, this list of conditions and the following disclaimer.
|
|
52
|
+
* * Redistributions in binary form must reproduce the above
|
|
53
|
+
* copyright notice, this list of conditions and the following
|
|
54
|
+
* disclaimer in the documentation and/or other materials provided
|
|
55
|
+
* with the distribution.
|
|
56
|
+
* * Neither the name of Google Inc. nor the names of its
|
|
57
|
+
* contributors may be used to endorse or promote products derived
|
|
58
|
+
* from this software without specific prior written permission.
|
|
59
|
+
*
|
|
60
|
+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
61
|
+
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
62
|
+
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
|
|
63
|
+
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
64
|
+
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
65
|
+
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
|
|
66
|
+
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
67
|
+
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
68
|
+
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
69
|
+
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
70
|
+
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
71
|
+
*/
|
|
72
|
+
/**
|
|
73
|
+
* Produce a CSS selector string for `node` using the legacy positional walker.
|
|
74
|
+
*
|
|
75
|
+
* Returns the empty string for non-element nodes — same shape every existing
|
|
76
|
+
* caller depends on. Never throws for well-formed Element inputs.
|
|
77
|
+
*
|
|
78
|
+
* @param node Element to identify.
|
|
79
|
+
* @param optimized When `true`, short-circuits at the nearest unique-ish step
|
|
80
|
+
* (id or `<body>` / `<head>` / `<html>`). Default `false`,
|
|
81
|
+
* which matches what autocapture has always passed.
|
|
82
|
+
*/
|
|
83
|
+
export declare const legacyCssPath: (node: Element, optimized?: boolean) => string;
|
|
84
|
+
//# sourceMappingURL=legacy-css-path.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"legacy-css-path.d.ts","sourceRoot":"","sources":["../../src/legacy-css-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsEG;AAgBH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,SAAU,OAAO,cAAc,OAAO,KAAG,MAuBlE,CAAC"}
|