@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.
Files changed (131) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +162 -0
  3. package/lib/cjs/config/resolve-config.d.ts +56 -0
  4. package/lib/cjs/config/resolve-config.d.ts.map +1 -0
  5. package/lib/cjs/config/resolve-config.js +114 -0
  6. package/lib/cjs/config/resolve-config.js.map +1 -0
  7. package/lib/cjs/engine.d.ts +54 -0
  8. package/lib/cjs/engine.d.ts.map +1 -0
  9. package/lib/cjs/engine.js +139 -0
  10. package/lib/cjs/engine.js.map +1 -0
  11. package/lib/cjs/fallback-css-path.d.ts +53 -0
  12. package/lib/cjs/fallback-css-path.d.ts.map +1 -0
  13. package/lib/cjs/fallback-css-path.js +124 -0
  14. package/lib/cjs/fallback-css-path.js.map +1 -0
  15. package/lib/cjs/generate-selector.d.ts +54 -0
  16. package/lib/cjs/generate-selector.d.ts.map +1 -0
  17. package/lib/cjs/generate-selector.js +76 -0
  18. package/lib/cjs/generate-selector.js.map +1 -0
  19. package/lib/cjs/helpers/describe-relative.d.ts +28 -0
  20. package/lib/cjs/helpers/describe-relative.d.ts.map +1 -0
  21. package/lib/cjs/helpers/describe-relative.js +60 -0
  22. package/lib/cjs/helpers/describe-relative.js.map +1 -0
  23. package/lib/cjs/helpers/escape-css-identifier.d.ts +8 -0
  24. package/lib/cjs/helpers/escape-css-identifier.d.ts.map +1 -0
  25. package/lib/cjs/helpers/escape-css-identifier.js +50 -0
  26. package/lib/cjs/helpers/escape-css-identifier.js.map +1 -0
  27. package/lib/cjs/helpers/escape-id.d.ts +3 -0
  28. package/lib/cjs/helpers/escape-id.d.ts.map +1 -0
  29. package/lib/cjs/helpers/escape-id.js +10 -0
  30. package/lib/cjs/helpers/escape-id.js.map +1 -0
  31. package/lib/cjs/helpers/get-stable-id.d.ts +23 -0
  32. package/lib/cjs/helpers/get-stable-id.d.ts.map +1 -0
  33. package/lib/cjs/helpers/get-stable-id.js +44 -0
  34. package/lib/cjs/helpers/get-stable-id.js.map +1 -0
  35. package/lib/cjs/index.d.ts +31 -0
  36. package/lib/cjs/index.d.ts.map +1 -0
  37. package/lib/cjs/index.js +71 -0
  38. package/lib/cjs/index.js.map +1 -0
  39. package/lib/cjs/legacy-css-path.d.ts +84 -0
  40. package/lib/cjs/legacy-css-path.d.ts.map +1 -0
  41. package/lib/cjs/legacy-css-path.js +230 -0
  42. package/lib/cjs/legacy-css-path.js.map +1 -0
  43. package/lib/cjs/orchestrator.d.ts +61 -0
  44. package/lib/cjs/orchestrator.d.ts.map +1 -0
  45. package/lib/cjs/orchestrator.js +140 -0
  46. package/lib/cjs/orchestrator.js.map +1 -0
  47. package/lib/cjs/patterns/autogenerated-ids.d.ts +37 -0
  48. package/lib/cjs/patterns/autogenerated-ids.d.ts.map +1 -0
  49. package/lib/cjs/patterns/autogenerated-ids.js +102 -0
  50. package/lib/cjs/patterns/autogenerated-ids.js.map +1 -0
  51. package/lib/cjs/patterns/unstable-classes.d.ts +48 -0
  52. package/lib/cjs/patterns/unstable-classes.d.ts.map +1 -0
  53. package/lib/cjs/patterns/unstable-classes.js +155 -0
  54. package/lib/cjs/patterns/unstable-classes.js.map +1 -0
  55. package/lib/cjs/strategies/explicit-tracking-attribute.d.ts +22 -0
  56. package/lib/cjs/strategies/explicit-tracking-attribute.d.ts.map +1 -0
  57. package/lib/cjs/strategies/explicit-tracking-attribute.js +36 -0
  58. package/lib/cjs/strategies/explicit-tracking-attribute.js.map +1 -0
  59. package/lib/cjs/strategies/stable-id.d.ts +14 -0
  60. package/lib/cjs/strategies/stable-id.d.ts.map +1 -0
  61. package/lib/cjs/strategies/stable-id.js +27 -0
  62. package/lib/cjs/strategies/stable-id.js.map +1 -0
  63. package/lib/cjs/types.d.ts +100 -0
  64. package/lib/cjs/types.d.ts.map +1 -0
  65. package/lib/cjs/types.js +13 -0
  66. package/lib/cjs/types.js.map +1 -0
  67. package/lib/esm/config/resolve-config.d.ts +56 -0
  68. package/lib/esm/config/resolve-config.d.ts.map +1 -0
  69. package/lib/esm/config/resolve-config.js +110 -0
  70. package/lib/esm/config/resolve-config.js.map +1 -0
  71. package/lib/esm/engine.d.ts +54 -0
  72. package/lib/esm/engine.d.ts.map +1 -0
  73. package/lib/esm/engine.js +135 -0
  74. package/lib/esm/engine.js.map +1 -0
  75. package/lib/esm/fallback-css-path.d.ts +53 -0
  76. package/lib/esm/fallback-css-path.d.ts.map +1 -0
  77. package/lib/esm/fallback-css-path.js +120 -0
  78. package/lib/esm/fallback-css-path.js.map +1 -0
  79. package/lib/esm/generate-selector.d.ts +54 -0
  80. package/lib/esm/generate-selector.d.ts.map +1 -0
  81. package/lib/esm/generate-selector.js +72 -0
  82. package/lib/esm/generate-selector.js.map +1 -0
  83. package/lib/esm/helpers/describe-relative.d.ts +28 -0
  84. package/lib/esm/helpers/describe-relative.d.ts.map +1 -0
  85. package/lib/esm/helpers/describe-relative.js +56 -0
  86. package/lib/esm/helpers/describe-relative.js.map +1 -0
  87. package/lib/esm/helpers/escape-css-identifier.d.ts +8 -0
  88. package/lib/esm/helpers/escape-css-identifier.d.ts.map +1 -0
  89. package/lib/esm/helpers/escape-css-identifier.js +46 -0
  90. package/lib/esm/helpers/escape-css-identifier.js.map +1 -0
  91. package/lib/esm/helpers/escape-id.d.ts +3 -0
  92. package/lib/esm/helpers/escape-id.d.ts.map +1 -0
  93. package/lib/esm/helpers/escape-id.js +6 -0
  94. package/lib/esm/helpers/escape-id.js.map +1 -0
  95. package/lib/esm/helpers/get-stable-id.d.ts +23 -0
  96. package/lib/esm/helpers/get-stable-id.d.ts.map +1 -0
  97. package/lib/esm/helpers/get-stable-id.js +40 -0
  98. package/lib/esm/helpers/get-stable-id.js.map +1 -0
  99. package/lib/esm/index.d.ts +31 -0
  100. package/lib/esm/index.d.ts.map +1 -0
  101. package/lib/esm/index.js +50 -0
  102. package/lib/esm/index.js.map +1 -0
  103. package/lib/esm/legacy-css-path.d.ts +84 -0
  104. package/lib/esm/legacy-css-path.d.ts.map +1 -0
  105. package/lib/esm/legacy-css-path.js +226 -0
  106. package/lib/esm/legacy-css-path.js.map +1 -0
  107. package/lib/esm/orchestrator.d.ts +61 -0
  108. package/lib/esm/orchestrator.d.ts.map +1 -0
  109. package/lib/esm/orchestrator.js +136 -0
  110. package/lib/esm/orchestrator.js.map +1 -0
  111. package/lib/esm/patterns/autogenerated-ids.d.ts +37 -0
  112. package/lib/esm/patterns/autogenerated-ids.d.ts.map +1 -0
  113. package/lib/esm/patterns/autogenerated-ids.js +97 -0
  114. package/lib/esm/patterns/autogenerated-ids.js.map +1 -0
  115. package/lib/esm/patterns/unstable-classes.d.ts +48 -0
  116. package/lib/esm/patterns/unstable-classes.d.ts.map +1 -0
  117. package/lib/esm/patterns/unstable-classes.js +150 -0
  118. package/lib/esm/patterns/unstable-classes.js.map +1 -0
  119. package/lib/esm/strategies/explicit-tracking-attribute.d.ts +22 -0
  120. package/lib/esm/strategies/explicit-tracking-attribute.d.ts.map +1 -0
  121. package/lib/esm/strategies/explicit-tracking-attribute.js +33 -0
  122. package/lib/esm/strategies/explicit-tracking-attribute.js.map +1 -0
  123. package/lib/esm/strategies/stable-id.d.ts +14 -0
  124. package/lib/esm/strategies/stable-id.d.ts.map +1 -0
  125. package/lib/esm/strategies/stable-id.js +24 -0
  126. package/lib/esm/strategies/stable-id.js.map +1 -0
  127. package/lib/esm/types.d.ts +100 -0
  128. package/lib/esm/types.d.ts.map +1 -0
  129. package/lib/esm/types.js +12 -0
  130. package/lib/esm/types.js.map +1 -0
  131. package/package.json +40 -5
@@ -0,0 +1,48 @@
1
+ import { ElementSelectorLogger } from '../types';
2
+ /**
3
+ * Unstable-class pattern pack.
4
+ *
5
+ * The fallback walker filters classes through these regexes before adding them
6
+ * to a selector. Classes that match are dropped — they don't participate in
7
+ * sibling disambiguation and never appear in the emitted output. Defends
8
+ * against three failure modes:
9
+ *
10
+ * 1. Build-tool / framework utilities (Tailwind, etc.) — class names that
11
+ * look stable but change with every design tweak.
12
+ * 2. CSS-in-JS / build-hash classes (Emotion, CSS modules, styled-components,
13
+ * styled-jsx) — change on every build.
14
+ * 3. Library runtime state classes (Swiper, MUI, Radix, Headless UI,
15
+ * BEM-style is-active/is-open) — class is stable in name but its presence
16
+ * on a given element moves as the user interacts.
17
+ *
18
+ * Defaults are surfaced to customers in remote config so they can audit what's
19
+ * being filtered and add or remove patterns to match their stack.
20
+ */
21
+ /**
22
+ * Built-in defaults grouped by category for readability. The runtime treats
23
+ * the whole list uniformly via `Array.prototype.some(pattern.test)`.
24
+ */
25
+ export declare const DEFAULT_UNSTABLE_CLASS_PATTERNS: ReadonlyArray<RegExp>;
26
+ /**
27
+ * Compile a list of regex pattern strings (e.g. from a remote-config payload)
28
+ * into RegExp objects. Invalid patterns are skipped (not thrown) so a single
29
+ * bad regex in remote config can't crash the engine.
30
+ *
31
+ * Pass `logger` to surface invalid patterns at `warn` level — useful for
32
+ * diagnosing why a customer's override isn't taking effect.
33
+ *
34
+ * Callers decide whether to merge the result with `DEFAULT_UNSTABLE_CLASS_PATTERNS`
35
+ * or use it as a full replacement. That policy lives in the config resolver,
36
+ * not here.
37
+ */
38
+ export declare function compile(patterns: string[], logger?: ElementSelectorLogger): RegExp[];
39
+ /**
40
+ * Filter a list of class names, dropping any that match a pattern. Returns a
41
+ * new array containing only the survivors, preserving original order.
42
+ *
43
+ * Used by the fallback walker (in the next PR) before adding classes to a
44
+ * selector for sibling disambiguation. Also returns sensibly on null /
45
+ * undefined / empty inputs.
46
+ */
47
+ export declare function filterClasses(classes: string[], patterns: ReadonlyArray<RegExp>): string[];
48
+ //# sourceMappingURL=unstable-classes.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"unstable-classes.d.ts","sourceRoot":"","sources":["../../../src/patterns/unstable-classes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAEjD;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,eAAO,MAAM,+BAA+B,EAAE,aAAa,CAAC,MAAM,CA6CjE,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,MAAM,CAAC,EAAE,qBAAqB,GAAG,MAAM,EAAE,CAWpF;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CAe1F"}
@@ -0,0 +1,150 @@
1
+ import { __values } from "tslib";
2
+ /**
3
+ * Unstable-class pattern pack.
4
+ *
5
+ * The fallback walker filters classes through these regexes before adding them
6
+ * to a selector. Classes that match are dropped — they don't participate in
7
+ * sibling disambiguation and never appear in the emitted output. Defends
8
+ * against three failure modes:
9
+ *
10
+ * 1. Build-tool / framework utilities (Tailwind, etc.) — class names that
11
+ * look stable but change with every design tweak.
12
+ * 2. CSS-in-JS / build-hash classes (Emotion, CSS modules, styled-components,
13
+ * styled-jsx) — change on every build.
14
+ * 3. Library runtime state classes (Swiper, MUI, Radix, Headless UI,
15
+ * BEM-style is-active/is-open) — class is stable in name but its presence
16
+ * on a given element moves as the user interacts.
17
+ *
18
+ * Defaults are surfaced to customers in remote config so they can audit what's
19
+ * being filtered and add or remove patterns to match their stack.
20
+ */
21
+ /**
22
+ * Built-in defaults grouped by category for readability. The runtime treats
23
+ * the whole list uniformly via `Array.prototype.some(pattern.test)`.
24
+ */
25
+ export var DEFAULT_UNSTABLE_CLASS_PATTERNS = [
26
+ // ===== Tailwind / build-tool utilities =====
27
+ // Tailwind spacing: p-4, px-2, py-8, pt-1, mt-4, etc.
28
+ /^(p|m|px|py|mx|my|pt|pb|pl|pr|mt|mb|ml|mr)-\d+$/,
29
+ // Tailwind sizing: w-full, h-screen, max-w-[1440px], etc.
30
+ /^(w|h|min-w|max-w|min-h|max-h)-/,
31
+ // Tailwind color / visual: bg-blue-500, text-white, border-gray-200, ring-2, etc.
32
+ /^(text|bg|border|ring|fill|stroke)-/,
33
+ // Tailwind state variants: hover:underline, focus:ring-2, active:bg-transparent.
34
+ /^(hover|focus|active|disabled|group-hover):/,
35
+ // Tailwind breakpoint variants: md:flex, lg:grid-cols-3.
36
+ /^(sm|md|lg|xl|2xl):/,
37
+ // Tailwind z-index utility: z-10, z-50.
38
+ /^z-\d+$/,
39
+ // Tailwind arbitrary data-attribute variants: data-[state=open]:bg-white.
40
+ /^data-\[/,
41
+ // Tailwind arbitrary selector variants: [&_.swiper-slide]:h-auto, [&>div]:p-4.
42
+ /^\[/,
43
+ // ===== CSS-in-JS / build hashes =====
44
+ // Emotion: css-1abcd23, css-9xyzkw0.
45
+ /^css-[a-z0-9]{6,}$/,
46
+ // CSS modules: Button_root__abc123, Card_container__xyz789. The middle
47
+ // segment can be as short as `root` (4 chars) in practice; the trailing
48
+ // hash is the load-bearing part.
49
+ /^[a-zA-Z]+_[a-zA-Z0-9]{3,}__[a-zA-Z0-9]{5,}$/,
50
+ // styled-components: sc-bdVaJa, sc-1jjuPXC0.
51
+ /^sc-[a-zA-Z0-9]{6,}$/,
52
+ // styled-jsx (Next.js): jsx-1234567.
53
+ /^jsx-\d+$/,
54
+ // ===== Library runtime state classes =====
55
+ // Swiper carousel slide states. Move between elements as carousel advances.
56
+ /^swiper-slide-(visible|fully-visible|active|prev|next|duplicate)$/,
57
+ // BEM-style interaction state: is-active, is-open, is-selected, etc.
58
+ /^is-(active|open|selected|hovered|focused|expanded)$/,
59
+ // MUI per-component state: MuiButton-focusVisible, MuiSwitch-checked, etc.
60
+ /^Mui[A-Z][a-zA-Z]+-(focused|selected|disabled|expanded|focusVisible|active|checked)$/,
61
+ // MUI bare state classes: Mui-selected, Mui-disabled.
62
+ /^Mui-(selected|focused|disabled|expanded|focusVisible|active|checked)$/,
63
+ // Radix-style state class mirrors: data-state-open, data-state-checked.
64
+ /^data-state-/,
65
+ ];
66
+ /**
67
+ * Compile a list of regex pattern strings (e.g. from a remote-config payload)
68
+ * into RegExp objects. Invalid patterns are skipped (not thrown) so a single
69
+ * bad regex in remote config can't crash the engine.
70
+ *
71
+ * Pass `logger` to surface invalid patterns at `warn` level — useful for
72
+ * diagnosing why a customer's override isn't taking effect.
73
+ *
74
+ * Callers decide whether to merge the result with `DEFAULT_UNSTABLE_CLASS_PATTERNS`
75
+ * or use it as a full replacement. That policy lives in the config resolver,
76
+ * not here.
77
+ */
78
+ export function compile(patterns, logger) {
79
+ var e_1, _a;
80
+ var compiled = [];
81
+ try {
82
+ for (var patterns_1 = __values(patterns), patterns_1_1 = patterns_1.next(); !patterns_1_1.done; patterns_1_1 = patterns_1.next()) {
83
+ var pattern = patterns_1_1.value;
84
+ try {
85
+ compiled.push(new RegExp(pattern));
86
+ }
87
+ catch (e) {
88
+ var message = e instanceof Error ? e.message : String(e);
89
+ logger === null || logger === void 0 ? void 0 : logger.warn("@amplitude/element-selector: ignoring invalid unstable-class pattern \"".concat(pattern, "\" (").concat(message, ")"));
90
+ }
91
+ }
92
+ }
93
+ catch (e_1_1) { e_1 = { error: e_1_1 }; }
94
+ finally {
95
+ try {
96
+ if (patterns_1_1 && !patterns_1_1.done && (_a = patterns_1.return)) _a.call(patterns_1);
97
+ }
98
+ finally { if (e_1) throw e_1.error; }
99
+ }
100
+ return compiled;
101
+ }
102
+ /**
103
+ * Filter a list of class names, dropping any that match a pattern. Returns a
104
+ * new array containing only the survivors, preserving original order.
105
+ *
106
+ * Used by the fallback walker (in the next PR) before adding classes to a
107
+ * selector for sibling disambiguation. Also returns sensibly on null /
108
+ * undefined / empty inputs.
109
+ */
110
+ export function filterClasses(classes, patterns) {
111
+ var e_2, _a, e_3, _b;
112
+ if (!classes || classes.length === 0)
113
+ return [];
114
+ var survivors = [];
115
+ try {
116
+ for (var classes_1 = __values(classes), classes_1_1 = classes_1.next(); !classes_1_1.done; classes_1_1 = classes_1.next()) {
117
+ var cls = classes_1_1.value;
118
+ if (!cls)
119
+ continue;
120
+ var matched = false;
121
+ try {
122
+ for (var patterns_2 = (e_3 = void 0, __values(patterns)), patterns_2_1 = patterns_2.next(); !patterns_2_1.done; patterns_2_1 = patterns_2.next()) {
123
+ var pattern = patterns_2_1.value;
124
+ if (pattern.test(cls)) {
125
+ matched = true;
126
+ break;
127
+ }
128
+ }
129
+ }
130
+ catch (e_3_1) { e_3 = { error: e_3_1 }; }
131
+ finally {
132
+ try {
133
+ if (patterns_2_1 && !patterns_2_1.done && (_b = patterns_2.return)) _b.call(patterns_2);
134
+ }
135
+ finally { if (e_3) throw e_3.error; }
136
+ }
137
+ if (!matched)
138
+ survivors.push(cls);
139
+ }
140
+ }
141
+ catch (e_2_1) { e_2 = { error: e_2_1 }; }
142
+ finally {
143
+ try {
144
+ if (classes_1_1 && !classes_1_1.done && (_a = classes_1.return)) _a.call(classes_1);
145
+ }
146
+ finally { if (e_2) throw e_2.error; }
147
+ }
148
+ return survivors;
149
+ }
150
+ //# sourceMappingURL=unstable-classes.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"unstable-classes.js","sourceRoot":"","sources":["../../../src/patterns/unstable-classes.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;GAGG;AACH,MAAM,CAAC,IAAM,+BAA+B,GAA0B;IACpE,8CAA8C;IAE9C,sDAAsD;IACtD,iDAAiD;IACjD,0DAA0D;IAC1D,iCAAiC;IACjC,kFAAkF;IAClF,qCAAqC;IACrC,iFAAiF;IACjF,6CAA6C;IAC7C,yDAAyD;IACzD,qBAAqB;IACrB,wCAAwC;IACxC,SAAS;IACT,0EAA0E;IAC1E,UAAU;IACV,+EAA+E;IAC/E,KAAK;IAEL,uCAAuC;IAEvC,qCAAqC;IACrC,oBAAoB;IACpB,uEAAuE;IACvE,wEAAwE;IACxE,iCAAiC;IACjC,8CAA8C;IAC9C,6CAA6C;IAC7C,sBAAsB;IACtB,qCAAqC;IACrC,WAAW;IAEX,4CAA4C;IAE5C,4EAA4E;IAC5E,mEAAmE;IACnE,qEAAqE;IACrE,sDAAsD;IACtD,2EAA2E;IAC3E,sFAAsF;IACtF,sDAAsD;IACtD,wEAAwE;IACxE,wEAAwE;IACxE,cAAc;CACf,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO,CAAC,QAAkB,EAAE,MAA8B;;IACxE,IAAM,QAAQ,GAAa,EAAE,CAAC;;QAC9B,KAAsB,IAAA,aAAA,SAAA,QAAQ,CAAA,kCAAA,wDAAE;YAA3B,IAAM,OAAO,qBAAA;YAChB,IAAI;gBACF,QAAQ,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC;aACpC;YAAC,OAAO,CAAC,EAAE;gBACV,IAAM,OAAO,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;gBAC3D,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,IAAI,CAAC,iFAAyE,OAAO,iBAAM,OAAO,MAAG,CAAC,CAAC;aAChH;SACF;;;;;;;;;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,OAAiB,EAAE,QAA+B;;IAC9E,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAChD,IAAM,SAAS,GAAa,EAAE,CAAC;;QAC/B,KAAkB,IAAA,YAAA,SAAA,OAAO,CAAA,gCAAA,qDAAE;YAAtB,IAAM,GAAG,oBAAA;YACZ,IAAI,CAAC,GAAG;gBAAE,SAAS;YACnB,IAAI,OAAO,GAAG,KAAK,CAAC;;gBACpB,KAAsB,IAAA,4BAAA,SAAA,QAAQ,CAAA,CAAA,kCAAA,wDAAE;oBAA3B,IAAM,OAAO,qBAAA;oBAChB,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;wBACrB,OAAO,GAAG,IAAI,CAAC;wBACf,MAAM;qBACP;iBACF;;;;;;;;;YACD,IAAI,CAAC,OAAO;gBAAE,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;SACnC;;;;;;;;;IACD,OAAO,SAAS,CAAC;AACnB,CAAC","sourcesContent":["import { ElementSelectorLogger } from '../types';\n\n/**\n * Unstable-class pattern pack.\n *\n * The fallback walker filters classes through these regexes before adding them\n * to a selector. Classes that match are dropped — they don't participate in\n * sibling disambiguation and never appear in the emitted output. Defends\n * against three failure modes:\n *\n * 1. Build-tool / framework utilities (Tailwind, etc.) — class names that\n * look stable but change with every design tweak.\n * 2. CSS-in-JS / build-hash classes (Emotion, CSS modules, styled-components,\n * styled-jsx) — change on every build.\n * 3. Library runtime state classes (Swiper, MUI, Radix, Headless UI,\n * BEM-style is-active/is-open) — class is stable in name but its presence\n * on a given element moves as the user interacts.\n *\n * Defaults are surfaced to customers in remote config so they can audit what's\n * being filtered and add or remove patterns to match their stack.\n */\n\n/**\n * Built-in defaults grouped by category for readability. The runtime treats\n * the whole list uniformly via `Array.prototype.some(pattern.test)`.\n */\nexport const DEFAULT_UNSTABLE_CLASS_PATTERNS: ReadonlyArray<RegExp> = [\n // ===== Tailwind / build-tool utilities =====\n\n // Tailwind spacing: p-4, px-2, py-8, pt-1, mt-4, etc.\n /^(p|m|px|py|mx|my|pt|pb|pl|pr|mt|mb|ml|mr)-\\d+$/,\n // Tailwind sizing: w-full, h-screen, max-w-[1440px], etc.\n /^(w|h|min-w|max-w|min-h|max-h)-/,\n // Tailwind color / visual: bg-blue-500, text-white, border-gray-200, ring-2, etc.\n /^(text|bg|border|ring|fill|stroke)-/,\n // Tailwind state variants: hover:underline, focus:ring-2, active:bg-transparent.\n /^(hover|focus|active|disabled|group-hover):/,\n // Tailwind breakpoint variants: md:flex, lg:grid-cols-3.\n /^(sm|md|lg|xl|2xl):/,\n // Tailwind z-index utility: z-10, z-50.\n /^z-\\d+$/,\n // Tailwind arbitrary data-attribute variants: data-[state=open]:bg-white.\n /^data-\\[/,\n // Tailwind arbitrary selector variants: [&_.swiper-slide]:h-auto, [&>div]:p-4.\n /^\\[/,\n\n // ===== CSS-in-JS / build hashes =====\n\n // Emotion: css-1abcd23, css-9xyzkw0.\n /^css-[a-z0-9]{6,}$/,\n // CSS modules: Button_root__abc123, Card_container__xyz789. The middle\n // segment can be as short as `root` (4 chars) in practice; the trailing\n // hash is the load-bearing part.\n /^[a-zA-Z]+_[a-zA-Z0-9]{3,}__[a-zA-Z0-9]{5,}$/,\n // styled-components: sc-bdVaJa, sc-1jjuPXC0.\n /^sc-[a-zA-Z0-9]{6,}$/,\n // styled-jsx (Next.js): jsx-1234567.\n /^jsx-\\d+$/,\n\n // ===== Library runtime state classes =====\n\n // Swiper carousel slide states. Move between elements as carousel advances.\n /^swiper-slide-(visible|fully-visible|active|prev|next|duplicate)$/,\n // BEM-style interaction state: is-active, is-open, is-selected, etc.\n /^is-(active|open|selected|hovered|focused|expanded)$/,\n // MUI per-component state: MuiButton-focusVisible, MuiSwitch-checked, etc.\n /^Mui[A-Z][a-zA-Z]+-(focused|selected|disabled|expanded|focusVisible|active|checked)$/,\n // MUI bare state classes: Mui-selected, Mui-disabled.\n /^Mui-(selected|focused|disabled|expanded|focusVisible|active|checked)$/,\n // Radix-style state class mirrors: data-state-open, data-state-checked.\n /^data-state-/,\n];\n\n/**\n * Compile a list of regex pattern strings (e.g. from a remote-config payload)\n * into RegExp objects. Invalid patterns are skipped (not thrown) so a single\n * bad regex in remote config can't crash the engine.\n *\n * Pass `logger` to surface invalid patterns at `warn` level — useful for\n * diagnosing why a customer's override isn't taking effect.\n *\n * Callers decide whether to merge the result with `DEFAULT_UNSTABLE_CLASS_PATTERNS`\n * or use it as a full replacement. That policy lives in the config resolver,\n * not here.\n */\nexport function compile(patterns: string[], logger?: ElementSelectorLogger): RegExp[] {\n const compiled: RegExp[] = [];\n for (const pattern of patterns) {\n try {\n compiled.push(new RegExp(pattern));\n } catch (e) {\n const message = e instanceof Error ? e.message : String(e);\n logger?.warn(`@amplitude/element-selector: ignoring invalid unstable-class pattern \"${pattern}\" (${message})`);\n }\n }\n return compiled;\n}\n\n/**\n * Filter a list of class names, dropping any that match a pattern. Returns a\n * new array containing only the survivors, preserving original order.\n *\n * Used by the fallback walker (in the next PR) before adding classes to a\n * selector for sibling disambiguation. Also returns sensibly on null /\n * undefined / empty inputs.\n */\nexport function filterClasses(classes: string[], patterns: ReadonlyArray<RegExp>): string[] {\n if (!classes || classes.length === 0) return [];\n const survivors: string[] = [];\n for (const cls of classes) {\n if (!cls) continue;\n let matched = false;\n for (const pattern of patterns) {\n if (pattern.test(cls)) {\n matched = true;\n break;\n }\n }\n if (!matched) survivors.push(cls);\n }\n return survivors;\n}\n"]}
@@ -0,0 +1,22 @@
1
+ import { Strategy } from '../types';
2
+ /**
3
+ * First strategy in the chain. Customer-controlled anchor selector via the
4
+ * configured tracking attribute (default: `data-amp-track-id`).
5
+ *
6
+ * Semantics:
7
+ *
8
+ * - Attribute set with a non-empty value:
9
+ * returns `[<attr>="<value>"]` — uses this element as an explicit anchor.
10
+ * - Attribute set with an empty value:
11
+ * returns null. The empty value is a suppression signal for downstream
12
+ * components (the `stableId` strategy and the fallback both consult
13
+ * `getStableId` which honors the empty-value semantic). This strategy
14
+ * doesn't anchor on the element either.
15
+ * - Attribute absent:
16
+ * returns null.
17
+ *
18
+ * The selector wraps the value in JSON-encoded quotes so any special CSS
19
+ * characters in the value are escaped uniformly.
20
+ */
21
+ export declare const explicitTrackingAttribute: Strategy;
22
+ //# sourceMappingURL=explicit-tracking-attribute.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"explicit-tracking-attribute.d.ts","sourceRoot":"","sources":["../../../src/strategies/explicit-tracking-attribute.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAavC,CAAC"}
@@ -0,0 +1,33 @@
1
+ /**
2
+ * First strategy in the chain. Customer-controlled anchor selector via the
3
+ * configured tracking attribute (default: `data-amp-track-id`).
4
+ *
5
+ * Semantics:
6
+ *
7
+ * - Attribute set with a non-empty value:
8
+ * returns `[<attr>="<value>"]` — uses this element as an explicit anchor.
9
+ * - Attribute set with an empty value:
10
+ * returns null. The empty value is a suppression signal for downstream
11
+ * components (the `stableId` strategy and the fallback both consult
12
+ * `getStableId` which honors the empty-value semantic). This strategy
13
+ * doesn't anchor on the element either.
14
+ * - Attribute absent:
15
+ * returns null.
16
+ *
17
+ * The selector wraps the value in JSON-encoded quotes so any special CSS
18
+ * characters in the value are escaped uniformly.
19
+ */
20
+ export var explicitTrackingAttribute = {
21
+ name: 'explicitTrackingAttribute',
22
+ try: function (el, ctx) {
23
+ var attrName = ctx.config.explicitTrackingAttribute;
24
+ var value = el.getAttribute(attrName);
25
+ if (value === null || value === '') {
26
+ return null;
27
+ }
28
+ // JSON.stringify wraps in double quotes and escapes embedded quotes /
29
+ // backslashes — the resulting attribute selector is valid CSS.
30
+ return "[".concat(attrName, "=").concat(JSON.stringify(value), "]");
31
+ },
32
+ };
33
+ //# sourceMappingURL=explicit-tracking-attribute.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"explicit-tracking-attribute.js","sourceRoot":"","sources":["../../../src/strategies/explicit-tracking-attribute.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,IAAM,yBAAyB,GAAa;IACjD,IAAI,EAAE,2BAA2B;IAEjC,GAAG,YAAC,EAAE,EAAE,GAAG;QACT,IAAM,QAAQ,GAAG,GAAG,CAAC,MAAM,CAAC,yBAAyB,CAAC;QACtD,IAAM,KAAK,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE;YAClC,OAAO,IAAI,CAAC;SACb;QACD,sEAAsE;QACtE,+DAA+D;QAC/D,OAAO,WAAI,QAAQ,cAAI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAG,CAAC;IAClD,CAAC;CACF,CAAC","sourcesContent":["import { Strategy } from '../types';\n\n/**\n * First strategy in the chain. Customer-controlled anchor selector via the\n * configured tracking attribute (default: `data-amp-track-id`).\n *\n * Semantics:\n *\n * - Attribute set with a non-empty value:\n * returns `[<attr>=\"<value>\"]` — uses this element as an explicit anchor.\n * - Attribute set with an empty value:\n * returns null. The empty value is a suppression signal for downstream\n * components (the `stableId` strategy and the fallback both consult\n * `getStableId` which honors the empty-value semantic). This strategy\n * doesn't anchor on the element either.\n * - Attribute absent:\n * returns null.\n *\n * The selector wraps the value in JSON-encoded quotes so any special CSS\n * characters in the value are escaped uniformly.\n */\nexport const explicitTrackingAttribute: Strategy = {\n name: 'explicitTrackingAttribute',\n\n try(el, ctx) {\n const attrName = ctx.config.explicitTrackingAttribute;\n const value = el.getAttribute(attrName);\n if (value === null || value === '') {\n return null;\n }\n // JSON.stringify wraps in double quotes and escapes embedded quotes /\n // backslashes — the resulting attribute selector is valid CSS.\n return `[${attrName}=${JSON.stringify(value)}]`;\n },\n};\n"]}
@@ -0,0 +1,14 @@
1
+ import { Strategy } from '../types';
2
+ /**
3
+ * Second strategy in the chain. Anchors on the element's `id` when the id is
4
+ * "stable" — i.e., present, not suppressed via the explicit-tracking-attribute
5
+ * empty-value mechanism, and not matching any autogenerated-id pattern.
6
+ *
7
+ * Returns `tag#id` (CSS-escaped) when the id is usable; null otherwise.
8
+ *
9
+ * Filtering is delegated to `getStableId` so this strategy and the
10
+ * `fallback-css-path` walker (in the orchestration PR) share a single source
11
+ * of truth for "is this id usable?"
12
+ */
13
+ export declare const stableId: Strategy;
14
+ //# sourceMappingURL=stable-id.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"stable-id.d.ts","sourceRoot":"","sources":["../../../src/strategies/stable-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAIpC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,EAAE,QAUtB,CAAC"}
@@ -0,0 +1,24 @@
1
+ import { getStableId } from '../helpers/get-stable-id';
2
+ import { escapeIdForCss } from '../helpers/escape-id';
3
+ /**
4
+ * Second strategy in the chain. Anchors on the element's `id` when the id is
5
+ * "stable" — i.e., present, not suppressed via the explicit-tracking-attribute
6
+ * empty-value mechanism, and not matching any autogenerated-id pattern.
7
+ *
8
+ * Returns `tag#id` (CSS-escaped) when the id is usable; null otherwise.
9
+ *
10
+ * Filtering is delegated to `getStableId` so this strategy and the
11
+ * `fallback-css-path` walker (in the orchestration PR) share a single source
12
+ * of truth for "is this id usable?"
13
+ */
14
+ export var stableId = {
15
+ name: 'stableId',
16
+ try: function (el, ctx) {
17
+ var id = getStableId(el, ctx.config);
18
+ if (id === null) {
19
+ return null;
20
+ }
21
+ return "".concat(el.tagName.toLowerCase(), "#").concat(escapeIdForCss(id));
22
+ },
23
+ };
24
+ //# sourceMappingURL=stable-id.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"stable-id.js","sourceRoot":"","sources":["../../../src/strategies/stable-id.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,IAAM,QAAQ,GAAa;IAChC,IAAI,EAAE,UAAU;IAEhB,GAAG,YAAC,EAAE,EAAE,GAAG;QACT,IAAM,EAAE,GAAG,WAAW,CAAC,EAAE,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,EAAE,KAAK,IAAI,EAAE;YACf,OAAO,IAAI,CAAC;SACb;QACD,OAAO,UAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,cAAI,cAAc,CAAC,EAAE,CAAC,CAAE,CAAC;IAC7D,CAAC;CACF,CAAC","sourcesContent":["import { Strategy } from '../types';\nimport { getStableId } from '../helpers/get-stable-id';\nimport { escapeIdForCss } from '../helpers/escape-id';\n\n/**\n * Second strategy in the chain. Anchors on the element's `id` when the id is\n * \"stable\" — i.e., present, not suppressed via the explicit-tracking-attribute\n * empty-value mechanism, and not matching any autogenerated-id pattern.\n *\n * Returns `tag#id` (CSS-escaped) when the id is usable; null otherwise.\n *\n * Filtering is delegated to `getStableId` so this strategy and the\n * `fallback-css-path` walker (in the orchestration PR) share a single source\n * of truth for \"is this id usable?\"\n */\nexport const stableId: Strategy = {\n name: 'stableId',\n\n try(el, ctx) {\n const id = getStableId(el, ctx.config);\n if (id === null) {\n return null;\n }\n return `${el.tagName.toLowerCase()}#${escapeIdForCss(id)}`;\n },\n};\n"]}
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Core type definitions for the v1 element-selector algorithm.
3
+ *
4
+ * These are the public-API contract that consumers (autocapture SDK, dashboard
5
+ * tagging UI, Chrome extension visual tagger) design against. They land before
6
+ * any implementation so the contract is stable for cross-team review.
7
+ *
8
+ * See the design doc:
9
+ * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
10
+ */
11
+ /**
12
+ * A pluggable selector strategy. Given an element + context, returns a CSS
13
+ * selector string candidate (which the orchestrator will then uniqueness-check)
14
+ * or `null` when the strategy doesn't apply to this element.
15
+ */
16
+ export interface Strategy {
17
+ /** Stable identifier for the strategy. Used for diagnostics and remote-config references. */
18
+ readonly name: string;
19
+ /**
20
+ * Produce a candidate selector for `el`, or `null` if this strategy has
21
+ * nothing to contribute for this element. Strategies are pure transforms —
22
+ * they never call `querySelectorAll` themselves; uniqueness is checked by
23
+ * the orchestrator in the next layer up.
24
+ */
25
+ try(el: Element, ctx: StrategyContext): string | null;
26
+ }
27
+ /**
28
+ * Context passed to every strategy invocation. `scope` is the document or
29
+ * shadow root the orchestrator will use for uniqueness checks; `config` is the
30
+ * resolved configuration (defaults + remote + local options merged).
31
+ */
32
+ export interface StrategyContext {
33
+ scope: ParentNode;
34
+ config: ResolvedSelectorConfig;
35
+ }
36
+ /**
37
+ * Logger shape accepted by element-selector diagnostics.
38
+ *
39
+ * This is intentionally structural so callers can pass the SDK's
40
+ * `@amplitude/analytics-core` ILogger without this package needing to import
41
+ * analytics-core types during standalone tests/builds.
42
+ */
43
+ export interface ElementSelectorLogger {
44
+ warn(...args: unknown[]): void;
45
+ debug(...args: unknown[]): void;
46
+ }
47
+ /**
48
+ * Fully-resolved configuration consumed at runtime. Produced by
49
+ * `resolveSelectorConfig` (lands in the orchestration PR) from the
50
+ * `ElementSelectorRemoteConfig` payload plus built-in defaults.
51
+ */
52
+ export interface ResolvedSelectorConfig {
53
+ /** Master kill switch. When false, autocapture reverts to legacy cssPath. */
54
+ enabled: boolean;
55
+ /** Attribute name customers can use to set or suppress anchors. Default: 'data-amp-track-id'. */
56
+ explicitTrackingAttribute: string;
57
+ /** Compiled regex patterns matching ids the algorithm should treat as autogenerated. */
58
+ autogeneratedIdPatterns: RegExp[];
59
+ /** Compiled regex patterns matching classes the fallback should filter from sibling disambiguation. */
60
+ unstableClassPatterns: RegExp[];
61
+ /** Optional throttle on the ancestor walk. When undefined, the walk runs to <html>. */
62
+ maxAncestorWalkDepth?: number;
63
+ }
64
+ /**
65
+ * Remote-config payload shape. Each field is optional; absent fields fall back
66
+ * to built-in defaults. Customers see the defaults in the remote-config UI and
67
+ * may add or remove patterns as needed.
68
+ */
69
+ export interface ElementSelectorRemoteConfig {
70
+ /** Kill switch. When set, overrides the default at resolve time. */
71
+ enabled?: boolean;
72
+ /** Override the attribute name used for explicit tracking. */
73
+ explicitTrackingAttribute?: string;
74
+ /** Full replacement for the autogenerated-id pattern list. When omitted, defaults apply. */
75
+ autogeneratedIdPatterns?: string[];
76
+ /** Full replacement for the unstable-class pattern list. When omitted, defaults apply. */
77
+ unstableClassPatterns?: string[];
78
+ /** Defensive throttle on the ancestor walk. Omit for unbounded walking to <html>. */
79
+ maxAncestorWalkDepth?: number;
80
+ }
81
+ /**
82
+ * Public interface of the runtime engine. Implementation lands in the
83
+ * orchestration PR; the interface is declared here so consumers can write
84
+ * against the contract before the class exists.
85
+ */
86
+ export interface SelectorEngine {
87
+ /** Produce a CSS selector string identifying `el` using the engine's current config. */
88
+ generate(el: Element): string;
89
+ /** Read-only access to the current resolved config — for diagnostics and consumer hydration. */
90
+ getConfig(): Readonly<ResolvedSelectorConfig>;
91
+ /** Replace the current config. Notifies any onConfigChange subscribers. */
92
+ updateConfig(next: ResolvedSelectorConfig): void;
93
+ /**
94
+ * Subscribe to config-change notifications. Returns an unsubscribe function.
95
+ * Used by the Chrome extension to keep its locally-hydrated engine in sync
96
+ * with the customer's SDK as remote config updates flow in.
97
+ */
98
+ onConfigChange(cb: (config: ResolvedSelectorConfig) => void): () => void;
99
+ }
100
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,6FAA6F;IAC7F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAAC;CACvD;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,sBAAsB,CAAC;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAC/B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,6EAA6E;IAC7E,OAAO,EAAE,OAAO,CAAC;IACjB,iGAAiG;IACjG,yBAAyB,EAAE,MAAM,CAAC;IAClC,wFAAwF;IACxF,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAClC,uGAAuG;IACvG,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,uFAAuF;IACvF,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8DAA8D;IAC9D,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,4FAA4F;IAC5F,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC;IACnC,0FAA0F;IAC1F,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC,qFAAqF;IACrF,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,MAAM,CAAC;IAE9B,gGAAgG;IAChG,SAAS,IAAI,QAAQ,CAAC,sBAAsB,CAAC,CAAC;IAE9C,2EAA2E;IAC3E,YAAY,CAAC,IAAI,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAEjD;;;;OAIG;IACH,cAAc,CAAC,EAAE,EAAE,CAAC,MAAM,EAAE,sBAAsB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC1E"}
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Core type definitions for the v1 element-selector algorithm.
3
+ *
4
+ * These are the public-API contract that consumers (autocapture SDK, dashboard
5
+ * tagging UI, Chrome extension visual tagger) design against. They land before
6
+ * any implementation so the contract is stable for cross-team review.
7
+ *
8
+ * See the design doc:
9
+ * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md
10
+ */
11
+ export {};
12
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG","sourcesContent":["/**\n * Core type definitions for the v1 element-selector algorithm.\n *\n * These are the public-API contract that consumers (autocapture SDK, dashboard\n * tagging UI, Chrome extension visual tagger) design against. They land before\n * any implementation so the contract is stable for cross-team review.\n *\n * See the design doc:\n * packages/plugin-autocapture-browser/element-selector-strategy-v1-no-classes.md\n */\n\n/**\n * A pluggable selector strategy. Given an element + context, returns a CSS\n * selector string candidate (which the orchestrator will then uniqueness-check)\n * or `null` when the strategy doesn't apply to this element.\n */\nexport interface Strategy {\n /** Stable identifier for the strategy. Used for diagnostics and remote-config references. */\n readonly name: string;\n\n /**\n * Produce a candidate selector for `el`, or `null` if this strategy has\n * nothing to contribute for this element. Strategies are pure transforms —\n * they never call `querySelectorAll` themselves; uniqueness is checked by\n * the orchestrator in the next layer up.\n */\n try(el: Element, ctx: StrategyContext): string | null;\n}\n\n/**\n * Context passed to every strategy invocation. `scope` is the document or\n * shadow root the orchestrator will use for uniqueness checks; `config` is the\n * resolved configuration (defaults + remote + local options merged).\n */\nexport interface StrategyContext {\n scope: ParentNode;\n config: ResolvedSelectorConfig;\n}\n\n/**\n * Logger shape accepted by element-selector diagnostics.\n *\n * This is intentionally structural so callers can pass the SDK's\n * `@amplitude/analytics-core` ILogger without this package needing to import\n * analytics-core types during standalone tests/builds.\n */\nexport interface ElementSelectorLogger {\n warn(...args: unknown[]): void;\n debug(...args: unknown[]): void;\n}\n\n/**\n * Fully-resolved configuration consumed at runtime. Produced by\n * `resolveSelectorConfig` (lands in the orchestration PR) from the\n * `ElementSelectorRemoteConfig` payload plus built-in defaults.\n */\nexport interface ResolvedSelectorConfig {\n /** Master kill switch. When false, autocapture reverts to legacy cssPath. */\n enabled: boolean;\n /** Attribute name customers can use to set or suppress anchors. Default: 'data-amp-track-id'. */\n explicitTrackingAttribute: string;\n /** Compiled regex patterns matching ids the algorithm should treat as autogenerated. */\n autogeneratedIdPatterns: RegExp[];\n /** Compiled regex patterns matching classes the fallback should filter from sibling disambiguation. */\n unstableClassPatterns: RegExp[];\n /** Optional throttle on the ancestor walk. When undefined, the walk runs to <html>. */\n maxAncestorWalkDepth?: number;\n}\n\n/**\n * Remote-config payload shape. Each field is optional; absent fields fall back\n * to built-in defaults. Customers see the defaults in the remote-config UI and\n * may add or remove patterns as needed.\n */\nexport interface ElementSelectorRemoteConfig {\n /** Kill switch. When set, overrides the default at resolve time. */\n enabled?: boolean;\n /** Override the attribute name used for explicit tracking. */\n explicitTrackingAttribute?: string;\n /** Full replacement for the autogenerated-id pattern list. When omitted, defaults apply. */\n autogeneratedIdPatterns?: string[];\n /** Full replacement for the unstable-class pattern list. When omitted, defaults apply. */\n unstableClassPatterns?: string[];\n /** Defensive throttle on the ancestor walk. Omit for unbounded walking to <html>. */\n maxAncestorWalkDepth?: number;\n}\n\n/**\n * Public interface of the runtime engine. Implementation lands in the\n * orchestration PR; the interface is declared here so consumers can write\n * against the contract before the class exists.\n */\nexport interface SelectorEngine {\n /** Produce a CSS selector string identifying `el` using the engine's current config. */\n generate(el: Element): string;\n\n /** Read-only access to the current resolved config — for diagnostics and consumer hydration. */\n getConfig(): Readonly<ResolvedSelectorConfig>;\n\n /** Replace the current config. Notifies any onConfigChange subscribers. */\n updateConfig(next: ResolvedSelectorConfig): void;\n\n /**\n * Subscribe to config-change notifications. Returns an unsubscribe function.\n * Used by the Chrome extension to keep its locally-hydrated engine in sync\n * with the customer's SDK as remote config updates flow in.\n */\n onConfigChange(cb: (config: ResolvedSelectorConfig) => void): () => void;\n}\n"]}
package/package.json CHANGED
@@ -1,9 +1,44 @@
1
1
  {
2
2
  "name": "@amplitude/element-selector",
3
- "version": "0.0.1",
4
- "description": "Bootstrap placeholder for Trusted Publishing setup. Do not use.",
5
- "private": false,
3
+ "version": "0.1.1-featelement-selector-v1.0",
4
+ "description": "Shared element-selector algorithm consumed by autocapture, the Amplitude dashboard, and the Chrome extension visual tagger.",
5
+ "author": "Amplitude Inc",
6
+ "homepage": "https://github.com/amplitude/Amplitude-TypeScript",
7
+ "license": "MIT",
8
+ "main": "lib/cjs/index.js",
9
+ "module": "lib/esm/index.js",
10
+ "types": "lib/esm/index.d.ts",
11
+ "sideEffects": false,
6
12
  "publishConfig": {
7
- "access": "public"
13
+ "access": "public",
14
+ "tag": "latest"
15
+ },
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "git+https://github.com/amplitude/Amplitude-TypeScript.git"
19
+ },
20
+ "bugs": {
21
+ "url": "https://github.com/amplitude/Amplitude-TypeScript/issues"
22
+ },
23
+ "dependencies": {
24
+ "tslib": "^2.4.1"
25
+ },
26
+ "files": [
27
+ "lib"
28
+ ],
29
+ "scripts": {
30
+ "build": "pnpm build:es5 & pnpm build:esm",
31
+ "build:es5": "tsc -p ./tsconfig.es5.json",
32
+ "build:esm": "tsc -p ./tsconfig.esm.json",
33
+ "watch": "tsc -p ./tsconfig.esm.json --watch",
34
+ "clean": "rimraf node_modules lib coverage",
35
+ "fix": "pnpm fix:eslint & pnpm fix:prettier",
36
+ "fix:eslint": "eslint '{src,test}/**/*.ts' --fix",
37
+ "fix:prettier": "prettier --write \"{src,test}/**/*.ts\"",
38
+ "lint": "pnpm lint:eslint & pnpm lint:prettier",
39
+ "lint:eslint": "eslint '{src,test}/**/*.ts'",
40
+ "lint:prettier": "prettier --check \"{src,test}/**/*.ts\"",
41
+ "test": "jest",
42
+ "typecheck": "tsc -p ./tsconfig.json"
8
43
  }
9
- }
44
+ }