@wix/viewer-core-services-utils 0.0.0-stage → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,103 @@
1
- # Temporary Holding Version
1
+ # @wix/viewer-core-services-utils
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > ⚠️ **No API stability guarantee.** This package is published to support Wix products and is provided as-is. Its API may change or be removed at any time without notice, and it does not follow semver compatibility guarantees. Use at your own risk.
4
+
5
+ Shared utilities for viewer-core-services. This is a plain utility package, not a service: it has no definition or implementation, no service registration, and no runtime dependencies.
6
+
7
+ Each utility lives in its own subpath module. There is no root entry point, so always import from a subpath:
8
+
9
+ | Subpath | What it does |
10
+ | --- | --- |
11
+ | `@wix/viewer-core-services-utils/dom-utils` | Class-first component element lookup |
12
+
13
+ ## Install
14
+
15
+ ```sh
16
+ pnpm add @wix/viewer-core-services-utils
17
+ ```
18
+
19
+ ## `dom-utils`
20
+
21
+ Finds a component's DOM element by its component class first, falling back to its `id`. The class-first behavior is gated on a boolean the caller passes, `isClassLookupOpen`. While it is `false`, every function behaves exactly like the id-based lookup it replaces.
22
+
23
+ Its functions are pure, and the only DOM they read is the `Document` you pass. This package reads no experiments.
24
+
25
+ ### The gate
26
+
27
+ Pass `isClassLookupOpen: true` only when both of these experiments are open:
28
+
29
+ - `classLookupInViewerServices` (`CLASS_LOOKUP_EXPERIMENT`): the viewer-core-services toggle, so these services can roll out on their own schedule.
30
+ - `specs.thunderbolt.addIdAsClassName` (`ADD_ID_AS_CLASS_NAME_EXPERIMENT`): thunderbolt's experiment that adds each component's ID to its element as a class. Without it no element has the class, so the toggle alone must never open the gate.
31
+
32
+ Every function takes the boolean, not the experiments map. Compute it with your host's own experiment check, once, where the experiments are fixed for the page, and don't parse experiment values yourself. Whatever values that check treats as open are the ones that open the gate: both checks below treat `true`, `'true'` and `'B'` as open.
33
+
34
+ ```ts
35
+ import { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT } from '@wix/viewer-core-services-utils/dom-utils'
36
+
37
+ // In a site service
38
+ const experiments = getService(ExperimentsDefinition) // @wix/site-service-experiments/definition
39
+ const isClassLookupOpen = experiments.isOpen(CLASS_LOOKUP_EXPERIMENT) && experiments.isOpen(ADD_ID_AS_CLASS_NAME_EXPERIMENT)
40
+
41
+ // In a viewer service
42
+ const envService = getService(EnvironmentDefinition) // @wix/viewer-service-environment/definition
43
+ const isClassLookupOpen =
44
+ envService.isExperimentOpen(CLASS_LOOKUP_EXPERIMENT) && envService.isExperimentOpen(ADD_ID_AS_CLASS_NAME_EXPERIMENT)
45
+ ```
46
+
47
+ Only `isClassLookupOpen: true` opens the gate; `false`, or any other value a JavaScript caller passes by mistake, keeps the id-based lookup.
48
+
49
+ ### API
50
+
51
+ ```ts
52
+ import {
53
+ ADD_ID_AS_CLASS_NAME_EXPERIMENT,
54
+ CLASS_LOOKUP_EXPERIMENT,
55
+ getByCompId,
56
+ querySelectorAll,
57
+ } from '@wix/viewer-core-services-utils/dom-utils'
58
+ ```
59
+
60
+ #### `CLASS_LOOKUP_EXPERIMENT`, `ADD_ID_AS_CLASS_NAME_EXPERIMENT`
61
+
62
+ The names of the two experiments to check. Open lookup only when both are open.
63
+
64
+ #### `getByCompId(doc, compId, { isClassLookupOpen }): HTMLElement | null`
65
+
66
+ Finds one component's element.
67
+
68
+ - Closed (`false`): `doc.getElementById(compId)`, nothing else.
69
+ - Open (`true`): the first element with the class `compId`, else `doc.getElementById(compId)`.
70
+ - An empty or non-string `compId` returns `null` in both modes without querying the DOM, as `getByCompId` in `thunderbolt-dom-utils` does.
71
+
72
+ ```ts
73
+ const popupsRoot = getByCompId(document, 'POPUPS_ROOT', { isClassLookupOpen })
74
+ ```
75
+
76
+ #### `querySelectorAll(doc, selector, { isClassLookupOpen }): Array<Element>`
77
+
78
+ Finds every element matching an id-based selector, class-first. Mirrors `querySelectorAll` in `thunderbolt-dom-utils`, with an explicit `doc`, a boolean gate, no logger and no element scope.
79
+
80
+ - Closed (`false`): `Array.from(doc.querySelectorAll(selector))`, nothing else. The elements, their order and the errors are the native query's, including the `SyntaxError` for an invalid selector.
81
+ - Open (`true`): the selector is converted to its class form (`#a,#b` becomes `.a,.b`; `[id^="x"]`, `[id*="x"]`, `[id$="x"]` and `[id="x"]` are converted too) and queried. If any element matches the class form, those elements are returned and the id form is not queried. Only when nothing matches the class form is `Array.from(doc.querySelectorAll(selector))` returned.
82
+ - The fallback is all-or-nothing: in `#a,#b`, if an element has the class `a`, an element that has only the id `b` is not returned.
83
+ - Document order and deduplication come from the native query.
84
+ - An empty or non-string `selector` returns `[]` in both modes without querying the DOM, as `querySelectorAll` in `thunderbolt-dom-utils` does.
85
+ - An open lookup that falls back to the id selector is not metered yet; that is deferred.
86
+
87
+ ```ts
88
+ const elements = querySelectorAll(document, '#comp-1,#comp-2', { isClassLookupOpen })
89
+ ```
90
+
91
+ #### Types
92
+
93
+ - `CompLookupOptions`: `{ isClassLookupOpen: boolean }`. `isClassLookupOpen` is required and has no default, so it can't be left out by accident.
94
+
95
+ ### Testing a caller
96
+
97
+ Drive the gate through the experiments your test hands the host's experiments service, not by stubbing this package, so the test proves the caller computes the boolean:
98
+
99
+ ```ts
100
+ const experiments = { [CLASS_LOOKUP_EXPERIMENT]: 'true', [ADD_ID_AS_CLASS_NAME_EXPERIMENT]: 'true' }
101
+ ```
102
+
103
+ Also cover each experiment open on its own, which must keep the id-based lookup.
@@ -0,0 +1,73 @@
1
+ /**
2
+ * The viewer-core-services toggle for class-first component lookup. It lets these services roll out independently.
3
+ * This package does not read it: the caller checks it with its host's own experiment check and opens lookup
4
+ * (`isClassLookupOpen: true`) only when both it and `ADD_ID_AS_CLASS_NAME_EXPERIMENT` are open.
5
+ */
6
+ export declare const CLASS_LOOKUP_EXPERIMENT = "classLookupInViewerServices";
7
+ /**
8
+ * Thunderbolt's experiment that adds each component's ID to its element as a class. Without it no element has the
9
+ * class. This package does not read it: the caller opens lookup (`isClassLookupOpen: true`) only when both it and
10
+ * `CLASS_LOOKUP_EXPERIMENT` are open.
11
+ */
12
+ export declare const ADD_ID_AS_CLASS_NAME_EXPERIMENT = "specs.thunderbolt.addIdAsClassName";
13
+ /** Options for looking up component elements. */
14
+ export type CompLookupOptions = {
15
+ /**
16
+ * Whether class-first lookup is open. Pass `true` only when both `CLASS_LOOKUP_EXPERIMENT` and
17
+ * `ADD_ID_AS_CLASS_NAME_EXPERIMENT` are open, as your host's experiment check reports them. `false` keeps the
18
+ * id-based lookup this package replaces.
19
+ */
20
+ isClassLookupOpen: boolean;
21
+ };
22
+ /**
23
+ * Escapes a value for use as a CSS identifier, for example in a class selector.
24
+ *
25
+ * Uses `CSS.escape` when the environment has it. Otherwise follows the CSSOM identifier serialization rules for
26
+ * the characters a component ID can contain: a lone `-`, a leading digit, a digit after a leading `-`, and any
27
+ * character other than ASCII letters, digits, `_` and `-`.
28
+ */
29
+ export declare function escapeIdent(value: string): string;
30
+ /**
31
+ * Finds a component's element.
32
+ *
33
+ * Closed (`isClassLookupOpen: false`): `doc.getElementById(compId)`, nothing else.
34
+ *
35
+ * Open (`isClassLookupOpen: true`): the first element with the component's class, else `doc.getElementById(compId)`.
36
+ *
37
+ * An empty or non-string `compId` returns `null` in both modes without querying the DOM, as `getByCompId` in
38
+ * `thunderbolt-dom-utils` does.
39
+ */
40
+ export declare const getByCompId: (doc: Document, compId: string, options: CompLookupOptions) => HTMLElement | null;
41
+ /**
42
+ * Converts an ID-based selector to a class-based selector.
43
+ * Handles various selector patterns:
44
+ * - #id → .id
45
+ * - [id="value"] → [class~="value"]
46
+ * - [id^="value"] → :is([class^="value"],[class*=" value"]) — matches prefix as first or any subsequent class token
47
+ * - [id*="value"] → [class*="value"]
48
+ * - [id$="value"] → :is([class$="value"],[class*="value "]) — matches suffix as last or any earlier class token
49
+ *
50
+ * @param selector - The ID-based selector to convert
51
+ * @returns The class-based selector
52
+ */
53
+ export declare function convertIdSelectorToClassSelector(selector: string): string;
54
+ /**
55
+ * Finds every element matching an id-based selector, class-first. Mirrors `querySelectorAll` in
56
+ * `thunderbolt-dom-utils`, with an explicit `doc`, a boolean gate, no logger and no element scope.
57
+ *
58
+ * Closed (`isClassLookupOpen: false`): `Array.from(doc.querySelectorAll(selector))`, nothing else, so the elements,
59
+ * their order and the errors (such as the `SyntaxError` for an invalid selector) are the native query's.
60
+ *
61
+ * Open (`isClassLookupOpen: true`): the selector is converted with `convertIdSelectorToClassSelector` (for example
62
+ * `#a,#b` becomes `.a,.b`) and queried. If any element matches the class form, those elements are returned and the
63
+ * id form is not queried. Only when nothing matches the class form is `Array.from(doc.querySelectorAll(selector))`
64
+ * returned. The fallback is all-or-nothing: in `#a,#b`, if an element has the class `a`, an element that has only
65
+ * the id `b` is not returned. Document order and deduplication come from the native query.
66
+ *
67
+ * An empty or non-string `selector` returns `[]` in both modes without querying the DOM, as `querySelectorAll` in
68
+ * `thunderbolt-dom-utils` does.
69
+ *
70
+ * Unlike `thunderbolt-dom-utils`, an open lookup that falls back to the id selector is not metered yet; that is
71
+ * deferred.
72
+ */
73
+ export declare function querySelectorAll(doc: Document, selector: string, options: CompLookupOptions): Array<Element>;
@@ -0,0 +1,119 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.getByCompId = exports.ADD_ID_AS_CLASS_NAME_EXPERIMENT = exports.CLASS_LOOKUP_EXPERIMENT = void 0;
4
+ exports.escapeIdent = escapeIdent;
5
+ exports.convertIdSelectorToClassSelector = convertIdSelectorToClassSelector;
6
+ exports.querySelectorAll = querySelectorAll;
7
+ /**
8
+ * The viewer-core-services toggle for class-first component lookup. It lets these services roll out independently.
9
+ * This package does not read it: the caller checks it with its host's own experiment check and opens lookup
10
+ * (`isClassLookupOpen: true`) only when both it and `ADD_ID_AS_CLASS_NAME_EXPERIMENT` are open.
11
+ */
12
+ exports.CLASS_LOOKUP_EXPERIMENT = 'classLookupInViewerServices';
13
+ /**
14
+ * Thunderbolt's experiment that adds each component's ID to its element as a class. Without it no element has the
15
+ * class. This package does not read it: the caller opens lookup (`isClassLookupOpen: true`) only when both it and
16
+ * `CLASS_LOOKUP_EXPERIMENT` are open.
17
+ */
18
+ exports.ADD_ID_AS_CLASS_NAME_EXPERIMENT = 'specs.thunderbolt.addIdAsClassName';
19
+ /**
20
+ * Escapes a value for use as a CSS identifier, for example in a class selector.
21
+ *
22
+ * Uses `CSS.escape` when the environment has it. Otherwise follows the CSSOM identifier serialization rules for
23
+ * the characters a component ID can contain: a lone `-`, a leading digit, a digit after a leading `-`, and any
24
+ * character other than ASCII letters, digits, `_` and `-`.
25
+ */
26
+ function escapeIdent(value) {
27
+ if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
28
+ return CSS.escape(value);
29
+ }
30
+ if (value === '-') {
31
+ return '\\-';
32
+ }
33
+ // Escape the symbols first: an escaped symbol starts with `\`, so the leading-digit step below only sees a
34
+ // digit (or `-` then a digit) that really starts the identifier.
35
+ const withSymbolsEscaped = value.replace(/[^a-zA-Z0-9_-]/g, '\\$&');
36
+ return withSymbolsEscaped.replace(/^(-?)(\d)/, '$1\\3$2 ');
37
+ }
38
+ /** The class selector for a component, for example `.comp-abc`. */
39
+ const toClassSelector = (compId) => `.${escapeIdent(compId)}`;
40
+ /**
41
+ * Finds a component's element.
42
+ *
43
+ * Closed (`isClassLookupOpen: false`): `doc.getElementById(compId)`, nothing else.
44
+ *
45
+ * Open (`isClassLookupOpen: true`): the first element with the component's class, else `doc.getElementById(compId)`.
46
+ *
47
+ * An empty or non-string `compId` returns `null` in both modes without querying the DOM, as `getByCompId` in
48
+ * `thunderbolt-dom-utils` does.
49
+ */
50
+ const getByCompId = (doc, compId, options) => {
51
+ if (!compId || typeof compId !== 'string') {
52
+ return null;
53
+ }
54
+ if (options?.isClassLookupOpen !== true) {
55
+ return doc.getElementById(compId);
56
+ }
57
+ return doc.querySelector(toClassSelector(compId)) ?? doc.getElementById(compId);
58
+ };
59
+ exports.getByCompId = getByCompId;
60
+ /**
61
+ * Converts an ID-based selector to a class-based selector.
62
+ * Handles various selector patterns:
63
+ * - #id → .id
64
+ * - [id="value"] → [class~="value"]
65
+ * - [id^="value"] → :is([class^="value"],[class*=" value"]) — matches prefix as first or any subsequent class token
66
+ * - [id*="value"] → [class*="value"]
67
+ * - [id$="value"] → :is([class$="value"],[class*="value "]) — matches suffix as last or any earlier class token
68
+ *
69
+ * @param selector - The ID-based selector to convert
70
+ * @returns The class-based selector
71
+ */
72
+ function convertIdSelectorToClassSelector(selector) {
73
+ return (selector
74
+ // Replace #id with .id
75
+ .replace(/#([a-zA-Z0-9_-]+)/g, '.$1')
76
+ // Replace [id="value"] with [class~="value"] (exact match in space-separated list)
77
+ .replace(/\[id="([^"]+)"\]/g, '[class~="$1"]')
78
+ // Replace [id^="value"] with :is([class^="value"],[class*=" value"])
79
+ // [class^="value"] matches when the class is first; [class*=" value"] matches any subsequent token.
80
+ // Together they reliably match a prefix regardless of class order in the attribute.
81
+ .replace(/\[id\^="([^"]+)"\]/g, ':is([class^="$1"],[class*=" $1"])')
82
+ // Replace [id*="value"] with [class*="value"] (contains)
83
+ .replace(/\[id\*="([^"]+)"\]/g, '[class*="$1"]')
84
+ // Replace [id$="value"] with :is([class$="value"],[class*="value "])
85
+ // [class$="value"] matches when the class is last; [class*="value "] matches any earlier token.
86
+ // The identity class is rarely last: components append their own classes after it, and the
87
+ // editor appends wix-select.
88
+ .replace(/\[id\$="([^"]+)"\]/g, ':is([class$="$1"],[class*="$1 "])'));
89
+ }
90
+ /**
91
+ * Finds every element matching an id-based selector, class-first. Mirrors `querySelectorAll` in
92
+ * `thunderbolt-dom-utils`, with an explicit `doc`, a boolean gate, no logger and no element scope.
93
+ *
94
+ * Closed (`isClassLookupOpen: false`): `Array.from(doc.querySelectorAll(selector))`, nothing else, so the elements,
95
+ * their order and the errors (such as the `SyntaxError` for an invalid selector) are the native query's.
96
+ *
97
+ * Open (`isClassLookupOpen: true`): the selector is converted with `convertIdSelectorToClassSelector` (for example
98
+ * `#a,#b` becomes `.a,.b`) and queried. If any element matches the class form, those elements are returned and the
99
+ * id form is not queried. Only when nothing matches the class form is `Array.from(doc.querySelectorAll(selector))`
100
+ * returned. The fallback is all-or-nothing: in `#a,#b`, if an element has the class `a`, an element that has only
101
+ * the id `b` is not returned. Document order and deduplication come from the native query.
102
+ *
103
+ * An empty or non-string `selector` returns `[]` in both modes without querying the DOM, as `querySelectorAll` in
104
+ * `thunderbolt-dom-utils` does.
105
+ *
106
+ * Unlike `thunderbolt-dom-utils`, an open lookup that falls back to the id selector is not metered yet; that is
107
+ * deferred.
108
+ */
109
+ function querySelectorAll(doc, selector, options) {
110
+ if (!selector || typeof selector !== 'string') {
111
+ return [];
112
+ }
113
+ if (options?.isClassLookupOpen !== true) {
114
+ return Array.from(doc.querySelectorAll(selector));
115
+ }
116
+ const byClass = Array.from(doc.querySelectorAll(convertIdSelectorToClassSelector(selector)));
117
+ return byClass.length > 0 ? byClass : Array.from(doc.querySelectorAll(selector));
118
+ }
119
+ //# sourceMappingURL=domSelectors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"domSelectors.js","sourceRoot":"","sources":["../../../src/dom-utils/domSelectors.ts"],"names":[],"mappings":";;;;;;AAAA;;;;GAIG;AACU,QAAA,uBAAuB,GAAG,6BAA6B,CAAA;AAEpE;;;;GAIG;AACU,QAAA,+BAA+B,GAAG,oCAAoC,CAAA;AAYnF;;;;;;GAMG;AACH,qBAA4B,KAAa;IACxC,IAAI,OAAO,GAAG,KAAK,WAAW,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACpE,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACzB,CAAC;IACD,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,KAAK,CAAA;IACb,CAAC;IACD,2GAA2G;IAC3G,iEAAiE;IACjE,MAAM,kBAAkB,GAAG,KAAK,CAAC,OAAO,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAA;IACnE,OAAO,kBAAkB,CAAC,OAAO,CAAC,WAAW,EAAE,UAAU,CAAC,CAAA;AAC3D,CAAC;AAED,mEAAmE;AACnE,MAAM,eAAe,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAA;AAErE;;;;;;;;;GASG;AACI,MAAM,WAAW,GAAG,CAAC,GAAa,EAAE,MAAc,EAAE,OAA0B,EAAsB,EAAE;IAC5G,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAA;IACZ,CAAC;IACD,IAAI,OAAO,EAAE,iBAAiB,KAAK,IAAI,EAAE,CAAC;QACzC,OAAO,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;IAClC,CAAC;IACD,OAAO,GAAG,CAAC,aAAa,CAAc,eAAe,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;AAC7F,CAAC,CAAA;AARY,QAAA,WAAW,GAAX,WAAW,CAQvB;AAED;;;;;;;;;;;GAWG;AACH,0CAAiD,QAAgB;IAChE,OAAO,CACN,QAAQ;QACP,uBAAuB;SACtB,OAAO,CAAC,oBAAoB,EAAE,KAAK,CAAC;QACrC,mFAAmF;SAClF,OAAO,CAAC,mBAAmB,EAAE,eAAe,CAAC;QAC9C,qEAAqE;QACrE,oGAAoG;QACpG,oFAAoF;SACnF,OAAO,CAAC,qBAAqB,EAAE,mCAAmC,CAAC;QACpE,yDAAyD;SACxD,OAAO,CAAC,qBAAqB,EAAE,eAAe,CAAC;QAChD,qEAAqE;QACrE,gGAAgG;QAChG,2FAA2F;QAC3F,6BAA6B;SAC5B,OAAO,CAAC,qBAAqB,EAAE,mCAAmC,CAAC,CACrE,CAAA;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,0BAAiC,GAAa,EAAE,QAAgB,EAAE,OAA0B;IAC3F,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,EAAE,CAAA;IACV,CAAC;IACD,IAAI,OAAO,EAAE,iBAAiB,KAAK,IAAI,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAA;IAClD,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,gCAAgC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;IAC5F,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAA;AACjF,CAAC"}
@@ -0,0 +1,2 @@
1
+ export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, getByCompId, querySelectorAll } from './domSelectors';
2
+ export type { CompLookupOptions } from './domSelectors';
@@ -0,0 +1,9 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.querySelectorAll = exports.getByCompId = exports.CLASS_LOOKUP_EXPERIMENT = exports.ADD_ID_AS_CLASS_NAME_EXPERIMENT = void 0;
4
+ var domSelectors_1 = require("./domSelectors");
5
+ Object.defineProperty(exports, "ADD_ID_AS_CLASS_NAME_EXPERIMENT", { enumerable: true, get: function () { return domSelectors_1.ADD_ID_AS_CLASS_NAME_EXPERIMENT; } });
6
+ Object.defineProperty(exports, "CLASS_LOOKUP_EXPERIMENT", { enumerable: true, get: function () { return domSelectors_1.CLASS_LOOKUP_EXPERIMENT; } });
7
+ Object.defineProperty(exports, "getByCompId", { enumerable: true, get: function () { return domSelectors_1.getByCompId; } });
8
+ Object.defineProperty(exports, "querySelectorAll", { enumerable: true, get: function () { return domSelectors_1.querySelectorAll; } });
9
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/dom-utils/index.ts"],"names":[],"mappings":";;;AAAA,+CAAwH;AAA/G,+HAAA,+BAA+B,OAAA;AAAE,uHAAA,uBAAuB,OAAA;AAAE,2GAAA,WAAW,OAAA;AAAE,gHAAA,gBAAgB,OAAA"}
@@ -0,0 +1,73 @@
1
+ /**
2
+ * The viewer-core-services toggle for class-first component lookup. It lets these services roll out independently.
3
+ * This package does not read it: the caller checks it with its host's own experiment check and opens lookup
4
+ * (`isClassLookupOpen: true`) only when both it and `ADD_ID_AS_CLASS_NAME_EXPERIMENT` are open.
5
+ */
6
+ export declare const CLASS_LOOKUP_EXPERIMENT = "classLookupInViewerServices";
7
+ /**
8
+ * Thunderbolt's experiment that adds each component's ID to its element as a class. Without it no element has the
9
+ * class. This package does not read it: the caller opens lookup (`isClassLookupOpen: true`) only when both it and
10
+ * `CLASS_LOOKUP_EXPERIMENT` are open.
11
+ */
12
+ export declare const ADD_ID_AS_CLASS_NAME_EXPERIMENT = "specs.thunderbolt.addIdAsClassName";
13
+ /** Options for looking up component elements. */
14
+ export type CompLookupOptions = {
15
+ /**
16
+ * Whether class-first lookup is open. Pass `true` only when both `CLASS_LOOKUP_EXPERIMENT` and
17
+ * `ADD_ID_AS_CLASS_NAME_EXPERIMENT` are open, as your host's experiment check reports them. `false` keeps the
18
+ * id-based lookup this package replaces.
19
+ */
20
+ isClassLookupOpen: boolean;
21
+ };
22
+ /**
23
+ * Escapes a value for use as a CSS identifier, for example in a class selector.
24
+ *
25
+ * Uses `CSS.escape` when the environment has it. Otherwise follows the CSSOM identifier serialization rules for
26
+ * the characters a component ID can contain: a lone `-`, a leading digit, a digit after a leading `-`, and any
27
+ * character other than ASCII letters, digits, `_` and `-`.
28
+ */
29
+ export declare function escapeIdent(value: string): string;
30
+ /**
31
+ * Finds a component's element.
32
+ *
33
+ * Closed (`isClassLookupOpen: false`): `doc.getElementById(compId)`, nothing else.
34
+ *
35
+ * Open (`isClassLookupOpen: true`): the first element with the component's class, else `doc.getElementById(compId)`.
36
+ *
37
+ * An empty or non-string `compId` returns `null` in both modes without querying the DOM, as `getByCompId` in
38
+ * `thunderbolt-dom-utils` does.
39
+ */
40
+ export declare const getByCompId: (doc: Document, compId: string, options: CompLookupOptions) => HTMLElement | null;
41
+ /**
42
+ * Converts an ID-based selector to a class-based selector.
43
+ * Handles various selector patterns:
44
+ * - #id → .id
45
+ * - [id="value"] → [class~="value"]
46
+ * - [id^="value"] → :is([class^="value"],[class*=" value"]) — matches prefix as first or any subsequent class token
47
+ * - [id*="value"] → [class*="value"]
48
+ * - [id$="value"] → :is([class$="value"],[class*="value "]) — matches suffix as last or any earlier class token
49
+ *
50
+ * @param selector - The ID-based selector to convert
51
+ * @returns The class-based selector
52
+ */
53
+ export declare function convertIdSelectorToClassSelector(selector: string): string;
54
+ /**
55
+ * Finds every element matching an id-based selector, class-first. Mirrors `querySelectorAll` in
56
+ * `thunderbolt-dom-utils`, with an explicit `doc`, a boolean gate, no logger and no element scope.
57
+ *
58
+ * Closed (`isClassLookupOpen: false`): `Array.from(doc.querySelectorAll(selector))`, nothing else, so the elements,
59
+ * their order and the errors (such as the `SyntaxError` for an invalid selector) are the native query's.
60
+ *
61
+ * Open (`isClassLookupOpen: true`): the selector is converted with `convertIdSelectorToClassSelector` (for example
62
+ * `#a,#b` becomes `.a,.b`) and queried. If any element matches the class form, those elements are returned and the
63
+ * id form is not queried. Only when nothing matches the class form is `Array.from(doc.querySelectorAll(selector))`
64
+ * returned. The fallback is all-or-nothing: in `#a,#b`, if an element has the class `a`, an element that has only
65
+ * the id `b` is not returned. Document order and deduplication come from the native query.
66
+ *
67
+ * An empty or non-string `selector` returns `[]` in both modes without querying the DOM, as `querySelectorAll` in
68
+ * `thunderbolt-dom-utils` does.
69
+ *
70
+ * Unlike `thunderbolt-dom-utils`, an open lookup that falls back to the id selector is not metered yet; that is
71
+ * deferred.
72
+ */
73
+ export declare function querySelectorAll(doc: Document, selector: string, options: CompLookupOptions): Array<Element>;
@@ -0,0 +1,112 @@
1
+ /**
2
+ * The viewer-core-services toggle for class-first component lookup. It lets these services roll out independently.
3
+ * This package does not read it: the caller checks it with its host's own experiment check and opens lookup
4
+ * (`isClassLookupOpen: true`) only when both it and `ADD_ID_AS_CLASS_NAME_EXPERIMENT` are open.
5
+ */
6
+ export const CLASS_LOOKUP_EXPERIMENT = 'classLookupInViewerServices';
7
+ /**
8
+ * Thunderbolt's experiment that adds each component's ID to its element as a class. Without it no element has the
9
+ * class. This package does not read it: the caller opens lookup (`isClassLookupOpen: true`) only when both it and
10
+ * `CLASS_LOOKUP_EXPERIMENT` are open.
11
+ */
12
+ export const ADD_ID_AS_CLASS_NAME_EXPERIMENT = 'specs.thunderbolt.addIdAsClassName';
13
+ /**
14
+ * Escapes a value for use as a CSS identifier, for example in a class selector.
15
+ *
16
+ * Uses `CSS.escape` when the environment has it. Otherwise follows the CSSOM identifier serialization rules for
17
+ * the characters a component ID can contain: a lone `-`, a leading digit, a digit after a leading `-`, and any
18
+ * character other than ASCII letters, digits, `_` and `-`.
19
+ */
20
+ export function escapeIdent(value) {
21
+ if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
22
+ return CSS.escape(value);
23
+ }
24
+ if (value === '-') {
25
+ return '\\-';
26
+ }
27
+ // Escape the symbols first: an escaped symbol starts with `\`, so the leading-digit step below only sees a
28
+ // digit (or `-` then a digit) that really starts the identifier.
29
+ const withSymbolsEscaped = value.replace(/[^a-zA-Z0-9_-]/g, '\\$&');
30
+ return withSymbolsEscaped.replace(/^(-?)(\d)/, '$1\\3$2 ');
31
+ }
32
+ /** The class selector for a component, for example `.comp-abc`. */
33
+ const toClassSelector = (compId) => `.${escapeIdent(compId)}`;
34
+ /**
35
+ * Finds a component's element.
36
+ *
37
+ * Closed (`isClassLookupOpen: false`): `doc.getElementById(compId)`, nothing else.
38
+ *
39
+ * Open (`isClassLookupOpen: true`): the first element with the component's class, else `doc.getElementById(compId)`.
40
+ *
41
+ * An empty or non-string `compId` returns `null` in both modes without querying the DOM, as `getByCompId` in
42
+ * `thunderbolt-dom-utils` does.
43
+ */
44
+ export const getByCompId = (doc, compId, options) => {
45
+ if (!compId || typeof compId !== 'string') {
46
+ return null;
47
+ }
48
+ if (options?.isClassLookupOpen !== true) {
49
+ return doc.getElementById(compId);
50
+ }
51
+ return doc.querySelector(toClassSelector(compId)) ?? doc.getElementById(compId);
52
+ };
53
+ /**
54
+ * Converts an ID-based selector to a class-based selector.
55
+ * Handles various selector patterns:
56
+ * - #id → .id
57
+ * - [id="value"] → [class~="value"]
58
+ * - [id^="value"] → :is([class^="value"],[class*=" value"]) — matches prefix as first or any subsequent class token
59
+ * - [id*="value"] → [class*="value"]
60
+ * - [id$="value"] → :is([class$="value"],[class*="value "]) — matches suffix as last or any earlier class token
61
+ *
62
+ * @param selector - The ID-based selector to convert
63
+ * @returns The class-based selector
64
+ */
65
+ export function convertIdSelectorToClassSelector(selector) {
66
+ return (selector
67
+ // Replace #id with .id
68
+ .replace(/#([a-zA-Z0-9_-]+)/g, '.$1')
69
+ // Replace [id="value"] with [class~="value"] (exact match in space-separated list)
70
+ .replace(/\[id="([^"]+)"\]/g, '[class~="$1"]')
71
+ // Replace [id^="value"] with :is([class^="value"],[class*=" value"])
72
+ // [class^="value"] matches when the class is first; [class*=" value"] matches any subsequent token.
73
+ // Together they reliably match a prefix regardless of class order in the attribute.
74
+ .replace(/\[id\^="([^"]+)"\]/g, ':is([class^="$1"],[class*=" $1"])')
75
+ // Replace [id*="value"] with [class*="value"] (contains)
76
+ .replace(/\[id\*="([^"]+)"\]/g, '[class*="$1"]')
77
+ // Replace [id$="value"] with :is([class$="value"],[class*="value "])
78
+ // [class$="value"] matches when the class is last; [class*="value "] matches any earlier token.
79
+ // The identity class is rarely last: components append their own classes after it, and the
80
+ // editor appends wix-select.
81
+ .replace(/\[id\$="([^"]+)"\]/g, ':is([class$="$1"],[class*="$1 "])'));
82
+ }
83
+ /**
84
+ * Finds every element matching an id-based selector, class-first. Mirrors `querySelectorAll` in
85
+ * `thunderbolt-dom-utils`, with an explicit `doc`, a boolean gate, no logger and no element scope.
86
+ *
87
+ * Closed (`isClassLookupOpen: false`): `Array.from(doc.querySelectorAll(selector))`, nothing else, so the elements,
88
+ * their order and the errors (such as the `SyntaxError` for an invalid selector) are the native query's.
89
+ *
90
+ * Open (`isClassLookupOpen: true`): the selector is converted with `convertIdSelectorToClassSelector` (for example
91
+ * `#a,#b` becomes `.a,.b`) and queried. If any element matches the class form, those elements are returned and the
92
+ * id form is not queried. Only when nothing matches the class form is `Array.from(doc.querySelectorAll(selector))`
93
+ * returned. The fallback is all-or-nothing: in `#a,#b`, if an element has the class `a`, an element that has only
94
+ * the id `b` is not returned. Document order and deduplication come from the native query.
95
+ *
96
+ * An empty or non-string `selector` returns `[]` in both modes without querying the DOM, as `querySelectorAll` in
97
+ * `thunderbolt-dom-utils` does.
98
+ *
99
+ * Unlike `thunderbolt-dom-utils`, an open lookup that falls back to the id selector is not metered yet; that is
100
+ * deferred.
101
+ */
102
+ export function querySelectorAll(doc, selector, options) {
103
+ if (!selector || typeof selector !== 'string') {
104
+ return [];
105
+ }
106
+ if (options?.isClassLookupOpen !== true) {
107
+ return Array.from(doc.querySelectorAll(selector));
108
+ }
109
+ const byClass = Array.from(doc.querySelectorAll(convertIdSelectorToClassSelector(selector)));
110
+ return byClass.length > 0 ? byClass : Array.from(doc.querySelectorAll(selector));
111
+ }
112
+ //# sourceMappingURL=domSelectors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"domSelectors.js","sourceRoot":"","sources":["../../src/dom-utils/domSelectors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,6BAA6B,CAAA;AAEpE;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,oCAAoC,CAAA;AAYnF;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACxC,IAAI,OAAO,GAAG,KAAK,WAAW,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACpE,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACzB,CAAC;IACD,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,KAAK,CAAA;IACb,CAAC;IACD,2GAA2G;IAC3G,iEAAiE;IACjE,MAAM,kBAAkB,GAAG,KAAK,CAAC,OAAO,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAA;IACnE,OAAO,kBAAkB,CAAC,OAAO,CAAC,WAAW,EAAE,UAAU,CAAC,CAAA;AAC3D,CAAC;AAED,mEAAmE;AACnE,MAAM,eAAe,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAA;AAErE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAa,EAAE,MAAc,EAAE,OAA0B,EAAsB,EAAE;IAC5G,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAA;IACZ,CAAC;IACD,IAAI,OAAO,EAAE,iBAAiB,KAAK,IAAI,EAAE,CAAC;QACzC,OAAO,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;IAClC,CAAC;IACD,OAAO,GAAG,CAAC,aAAa,CAAc,eAAe,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;AAC7F,CAAC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gCAAgC,CAAC,QAAgB;IAChE,OAAO,CACN,QAAQ;QACP,uBAAuB;SACtB,OAAO,CAAC,oBAAoB,EAAE,KAAK,CAAC;QACrC,mFAAmF;SAClF,OAAO,CAAC,mBAAmB,EAAE,eAAe,CAAC;QAC9C,qEAAqE;QACrE,oGAAoG;QACpG,oFAAoF;SACnF,OAAO,CAAC,qBAAqB,EAAE,mCAAmC,CAAC;QACpE,yDAAyD;SACxD,OAAO,CAAC,qBAAqB,EAAE,eAAe,CAAC;QAChD,qEAAqE;QACrE,gGAAgG;QAChG,2FAA2F;QAC3F,6BAA6B;SAC5B,OAAO,CAAC,qBAAqB,EAAE,mCAAmC,CAAC,CACrE,CAAA;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAa,EAAE,QAAgB,EAAE,OAA0B;IAC3F,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,EAAE,CAAA;IACV,CAAC;IACD,IAAI,OAAO,EAAE,iBAAiB,KAAK,IAAI,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAA;IAClD,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,gCAAgC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;IAC5F,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAA;AACjF,CAAC"}
@@ -0,0 +1,2 @@
1
+ export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, getByCompId, querySelectorAll } from './domSelectors';
2
+ export type { CompLookupOptions } from './domSelectors';
@@ -0,0 +1,2 @@
1
+ export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, getByCompId, querySelectorAll } from './domSelectors';
2
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/dom-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,+BAA+B,EAAE,uBAAuB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA"}
@@ -0,0 +1,3 @@
1
+ {
2
+ "main": "../cjs/build/dom-utils/index.js"
3
+ }
package/package.json CHANGED
@@ -1,6 +1,56 @@
1
1
  {
2
2
  "name": "@wix/viewer-core-services-utils",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.0.1",
4
+ "description": "Shared viewer-core-services utilities; dom-utils: class-first component element lookup",
5
+ "license": "UNLICENSED",
6
+ "files": [
7
+ "dist",
8
+ "src",
9
+ "cjs",
10
+ "dom-utils",
11
+ "!**/*.tsbuildinfo"
12
+ ],
13
+ "sideEffects": false,
14
+ "main": "cjs/build/dom-utils/index.js",
15
+ "module": "dist/dom-utils/index.js",
16
+ "types": "dist/dom-utils/index.d.ts",
17
+ "exports": {
18
+ "./dom-utils": {
19
+ "types": "./dist/dom-utils/index.d.ts",
20
+ "import": "./dist/dom-utils/index.js",
21
+ "require": "./cjs/build/dom-utils/index.js"
22
+ }
23
+ },
24
+ "publishConfig": {
25
+ "registry": "https://registry.npmjs.org/",
26
+ "access": "public"
27
+ },
28
+ "scripts": {
29
+ "build": "tsc -b . && tsc --project tsconfig.cjs.json",
30
+ "lint": "pnpm --workspace-root run lint:package --package $npm_package_name",
31
+ "test": "vitest --run && pnpm run test-type-check",
32
+ "test-type-check": "echo 'validating typescript in test files' && tsc --project tsconfig.test.json && echo 'Finished validating typescript in test files successfully'"
33
+ },
34
+ "devDependencies": {
35
+ "typescript": "~7.0.2",
36
+ "vitest": "4.1.11"
37
+ },
38
+ "publishUnscoped": false,
39
+ "wix": {
40
+ "artifact": {
41
+ "groupId": "com.wixpress.npm",
42
+ "artifactId": "viewer-core-services-utils",
43
+ "targets": {
44
+ "static": false,
45
+ "docker": false
46
+ }
47
+ },
48
+ "validations": {
49
+ "postBuild": [
50
+ "test",
51
+ "lint"
52
+ ]
53
+ }
54
+ },
55
+ "falconPackageHash": "55e2e41273e42975b8e5eb98f249c413a8ae12fcdfaf298775b5513a"
6
56
  }
@@ -0,0 +1,129 @@
1
+ /**
2
+ * The viewer-core-services toggle for class-first component lookup. It lets these services roll out independently.
3
+ * This package does not read it: the caller checks it with its host's own experiment check and opens lookup
4
+ * (`isClassLookupOpen: true`) only when both it and `ADD_ID_AS_CLASS_NAME_EXPERIMENT` are open.
5
+ */
6
+ export const CLASS_LOOKUP_EXPERIMENT = 'classLookupInViewerServices'
7
+
8
+ /**
9
+ * Thunderbolt's experiment that adds each component's ID to its element as a class. Without it no element has the
10
+ * class. This package does not read it: the caller opens lookup (`isClassLookupOpen: true`) only when both it and
11
+ * `CLASS_LOOKUP_EXPERIMENT` are open.
12
+ */
13
+ export const ADD_ID_AS_CLASS_NAME_EXPERIMENT = 'specs.thunderbolt.addIdAsClassName'
14
+
15
+ /** Options for looking up component elements. */
16
+ export type CompLookupOptions = {
17
+ /**
18
+ * Whether class-first lookup is open. Pass `true` only when both `CLASS_LOOKUP_EXPERIMENT` and
19
+ * `ADD_ID_AS_CLASS_NAME_EXPERIMENT` are open, as your host's experiment check reports them. `false` keeps the
20
+ * id-based lookup this package replaces.
21
+ */
22
+ isClassLookupOpen: boolean
23
+ }
24
+
25
+ /**
26
+ * Escapes a value for use as a CSS identifier, for example in a class selector.
27
+ *
28
+ * Uses `CSS.escape` when the environment has it. Otherwise follows the CSSOM identifier serialization rules for
29
+ * the characters a component ID can contain: a lone `-`, a leading digit, a digit after a leading `-`, and any
30
+ * character other than ASCII letters, digits, `_` and `-`.
31
+ */
32
+ export function escapeIdent(value: string): string {
33
+ if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') {
34
+ return CSS.escape(value)
35
+ }
36
+ if (value === '-') {
37
+ return '\\-'
38
+ }
39
+ // Escape the symbols first: an escaped symbol starts with `\`, so the leading-digit step below only sees a
40
+ // digit (or `-` then a digit) that really starts the identifier.
41
+ const withSymbolsEscaped = value.replace(/[^a-zA-Z0-9_-]/g, '\\$&')
42
+ return withSymbolsEscaped.replace(/^(-?)(\d)/, '$1\\3$2 ')
43
+ }
44
+
45
+ /** The class selector for a component, for example `.comp-abc`. */
46
+ const toClassSelector = (compId: string) => `.${escapeIdent(compId)}`
47
+
48
+ /**
49
+ * Finds a component's element.
50
+ *
51
+ * Closed (`isClassLookupOpen: false`): `doc.getElementById(compId)`, nothing else.
52
+ *
53
+ * Open (`isClassLookupOpen: true`): the first element with the component's class, else `doc.getElementById(compId)`.
54
+ *
55
+ * An empty or non-string `compId` returns `null` in both modes without querying the DOM, as `getByCompId` in
56
+ * `thunderbolt-dom-utils` does.
57
+ */
58
+ export const getByCompId = (doc: Document, compId: string, options: CompLookupOptions): HTMLElement | null => {
59
+ if (!compId || typeof compId !== 'string') {
60
+ return null
61
+ }
62
+ if (options?.isClassLookupOpen !== true) {
63
+ return doc.getElementById(compId)
64
+ }
65
+ return doc.querySelector<HTMLElement>(toClassSelector(compId)) ?? doc.getElementById(compId)
66
+ }
67
+
68
+ /**
69
+ * Converts an ID-based selector to a class-based selector.
70
+ * Handles various selector patterns:
71
+ * - #id → .id
72
+ * - [id="value"] → [class~="value"]
73
+ * - [id^="value"] → :is([class^="value"],[class*=" value"]) — matches prefix as first or any subsequent class token
74
+ * - [id*="value"] → [class*="value"]
75
+ * - [id$="value"] → :is([class$="value"],[class*="value "]) — matches suffix as last or any earlier class token
76
+ *
77
+ * @param selector - The ID-based selector to convert
78
+ * @returns The class-based selector
79
+ */
80
+ export function convertIdSelectorToClassSelector(selector: string): string {
81
+ return (
82
+ selector
83
+ // Replace #id with .id
84
+ .replace(/#([a-zA-Z0-9_-]+)/g, '.$1')
85
+ // Replace [id="value"] with [class~="value"] (exact match in space-separated list)
86
+ .replace(/\[id="([^"]+)"\]/g, '[class~="$1"]')
87
+ // Replace [id^="value"] with :is([class^="value"],[class*=" value"])
88
+ // [class^="value"] matches when the class is first; [class*=" value"] matches any subsequent token.
89
+ // Together they reliably match a prefix regardless of class order in the attribute.
90
+ .replace(/\[id\^="([^"]+)"\]/g, ':is([class^="$1"],[class*=" $1"])')
91
+ // Replace [id*="value"] with [class*="value"] (contains)
92
+ .replace(/\[id\*="([^"]+)"\]/g, '[class*="$1"]')
93
+ // Replace [id$="value"] with :is([class$="value"],[class*="value "])
94
+ // [class$="value"] matches when the class is last; [class*="value "] matches any earlier token.
95
+ // The identity class is rarely last: components append their own classes after it, and the
96
+ // editor appends wix-select.
97
+ .replace(/\[id\$="([^"]+)"\]/g, ':is([class$="$1"],[class*="$1 "])')
98
+ )
99
+ }
100
+
101
+ /**
102
+ * Finds every element matching an id-based selector, class-first. Mirrors `querySelectorAll` in
103
+ * `thunderbolt-dom-utils`, with an explicit `doc`, a boolean gate, no logger and no element scope.
104
+ *
105
+ * Closed (`isClassLookupOpen: false`): `Array.from(doc.querySelectorAll(selector))`, nothing else, so the elements,
106
+ * their order and the errors (such as the `SyntaxError` for an invalid selector) are the native query's.
107
+ *
108
+ * Open (`isClassLookupOpen: true`): the selector is converted with `convertIdSelectorToClassSelector` (for example
109
+ * `#a,#b` becomes `.a,.b`) and queried. If any element matches the class form, those elements are returned and the
110
+ * id form is not queried. Only when nothing matches the class form is `Array.from(doc.querySelectorAll(selector))`
111
+ * returned. The fallback is all-or-nothing: in `#a,#b`, if an element has the class `a`, an element that has only
112
+ * the id `b` is not returned. Document order and deduplication come from the native query.
113
+ *
114
+ * An empty or non-string `selector` returns `[]` in both modes without querying the DOM, as `querySelectorAll` in
115
+ * `thunderbolt-dom-utils` does.
116
+ *
117
+ * Unlike `thunderbolt-dom-utils`, an open lookup that falls back to the id selector is not metered yet; that is
118
+ * deferred.
119
+ */
120
+ export function querySelectorAll(doc: Document, selector: string, options: CompLookupOptions): Array<Element> {
121
+ if (!selector || typeof selector !== 'string') {
122
+ return []
123
+ }
124
+ if (options?.isClassLookupOpen !== true) {
125
+ return Array.from(doc.querySelectorAll(selector))
126
+ }
127
+ const byClass = Array.from(doc.querySelectorAll(convertIdSelectorToClassSelector(selector)))
128
+ return byClass.length > 0 ? byClass : Array.from(doc.querySelectorAll(selector))
129
+ }
@@ -0,0 +1,2 @@
1
+ export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, getByCompId, querySelectorAll } from './domSelectors'
2
+ export type { CompLookupOptions } from './domSelectors'