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

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,130 @@
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 and selectors |
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
+ canSelectByClass,
56
+ getByCompId,
57
+ getCompAndCopiesSelector,
58
+ getCompSelector,
59
+ querySelectorAll,
60
+ } from '@wix/viewer-core-services-utils/dom-utils'
61
+ ```
62
+
63
+ #### `CLASS_LOOKUP_EXPERIMENT`, `ADD_ID_AS_CLASS_NAME_EXPERIMENT`
64
+
65
+ The names of the two experiments to check. Open lookup only when both are open.
66
+
67
+ #### `getByCompId(doc, compId, { isClassLookupOpen }): HTMLElement | null`
68
+
69
+ Finds one component's element.
70
+
71
+ - Closed (`false`): `doc.getElementById(compId)`, nothing else.
72
+ - Open (`true`): the first element with the class `compId`, else `doc.getElementById(compId)`.
73
+ - An empty or non-string `compId` returns `null` in both modes without querying the DOM, as `getByCompId` in `thunderbolt-dom-utils` does.
74
+
75
+ ```ts
76
+ const popupsRoot = getByCompId(document, 'POPUPS_ROOT', { isClassLookupOpen })
77
+ ```
78
+
79
+ #### `querySelectorAll(doc, selector, { isClassLookupOpen }): Array<Element>`
80
+
81
+ 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.
82
+
83
+ - 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.
84
+ - 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.
85
+ - 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.
86
+ - Document order and deduplication come from the native query.
87
+ - An empty or non-string `selector` returns `[]` in both modes without querying the DOM, as `querySelectorAll` in `thunderbolt-dom-utils` does.
88
+ - An open lookup that falls back to the id selector is not metered yet; that is deferred.
89
+
90
+ ```ts
91
+ const elements = querySelectorAll(document, '#comp-1,#comp-2', { isClassLookupOpen })
92
+ ```
93
+
94
+ #### `getCompSelector(compId, { isClassLookupOpen }): string`
95
+
96
+ A CSS selector for the element `#<compId>` selects, for stylesheets that target a component. It matches the component's own element and not the copies of a repeated or forwarded component, which Thunderbolt gives the ids `<compId>__<item>`.
97
+
98
+ - Closed (`false`), or a `compId` that isn't a plain ASCII CSS identifier: `#<compId>`, with `compId` inserted as is, matching the `#<compId>` selectors it replaces.
99
+ - Open (`true`): `.<compId>`, excluding elements that also carry a `<compId>__…` class (the copies carry the component's class beside their own, after any ASCII whitespace) and a `.<compId>` inside another `.<compId>`. The class form weighs less than `#<compId>`, so wrap it if specificity matters.
100
+ - Cost: the exclusions make the browser re-match the selector on every class change in the page. Prefer `getCompAndCopiesSelector` when the copies may match too.
101
+
102
+ #### `getCompAndCopiesSelector(compId, { isClassLookupOpen }): string`
103
+
104
+ A CSS selector for every element of a component: its own and each copy's (`<compId>__<item>`).
105
+
106
+ - Closed (`false`), or a `compId` that isn't a plain ASCII CSS identifier: `:is([id="<compId>"], [id^="<compId>__"])`.
107
+ - Open (`true`): `.<compId>`, which Thunderbolt puts on the component and on every copy, with the same specificity.
108
+
109
+ #### `canSelectByClass(compId, { isClassLookupOpen }): boolean`
110
+
111
+ Whether the two selector functions return the class form for `compId`: lookup is open and `compId` is a plain ASCII CSS identifier. Use it when you wrap the id and class forms differently.
112
+
113
+ ```ts
114
+ const section = getCompSelector(sectionId, { isClassLookupOpen })
115
+ const scope = canSelectByClass(sectionId, { isClassLookupOpen }) ? `#main_MF#main_MF :where(${section})` : `#main_MF ${section}`
116
+ ```
117
+
118
+ #### Types
119
+
120
+ - `CompLookupOptions`: `{ isClassLookupOpen: boolean }`. `isClassLookupOpen` is required and has no default, so it can't be left out by accident.
121
+
122
+ ### Testing a caller
123
+
124
+ 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:
125
+
126
+ ```ts
127
+ const experiments = { [CLASS_LOOKUP_EXPERIMENT]: 'true', [ADD_ID_AS_CLASS_NAME_EXPERIMENT]: 'true' }
128
+ ```
129
+
130
+ Also cover each experiment open on its own, which must keep the id-based lookup.
@@ -0,0 +1,103 @@
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
+ * Whether `getCompSelector` and `getCompAndCopiesSelector` return the class form for `compId`: lookup is open and
32
+ * `compId` is a plain ASCII CSS identifier. Otherwise they return the id form, so a caller that wraps the two forms
33
+ * differently (for example to keep an id selector's specificity) can tell which one it got.
34
+ */
35
+ export declare const canSelectByClass: (compId: string, options: CompLookupOptions) => boolean;
36
+ /**
37
+ * A CSS selector for the element `#<compId>` selects: the component's own element, and not the copies of a
38
+ * repeated or forwarded component, which Thunderbolt gives the ids `<compId>__<item>`.
39
+ *
40
+ * Closed, or a `compId` that isn't a plain ASCII CSS identifier: `#<compId>`, with `compId` inserted as is, matching
41
+ * the `#<compId>` selectors it replaces.
42
+ *
43
+ * Open: `.<compId>`, excluding the elements that also carry a `<compId>__…` class (the copies, which carry the
44
+ * component's class beside their own) and a `.<compId>` inside another `.<compId>` (a component that repeats its
45
+ * class on an inner element). The class form weighs less than `#<compId>`; wrap it if specificity matters. Its
46
+ * exclusions make the browser re-match the selector on every class change in the page, so prefer
47
+ * `getCompAndCopiesSelector` when the copies may match too.
48
+ */
49
+ export declare const getCompSelector: (compId: string, options: CompLookupOptions) => string;
50
+ /**
51
+ * A CSS selector for every element of a component: its own and, for a repeated or forwarded component, each
52
+ * copy's (`<compId>__<item>`).
53
+ *
54
+ * Closed, or a `compId` that isn't a plain ASCII CSS identifier: `:is([id="<compId>"], [id^="<compId>__"])`.
55
+ *
56
+ * Open: `.<compId>`. Thunderbolt puts the component's class on the copies too, beside their own
57
+ * `<compId>__<item>` class, so the one class matches what both id branches match, with the same specificity.
58
+ */
59
+ export declare const getCompAndCopiesSelector: (compId: string, options: CompLookupOptions) => string;
60
+ /**
61
+ * Finds a component's element.
62
+ *
63
+ * Closed (`isClassLookupOpen: false`): `doc.getElementById(compId)`, nothing else.
64
+ *
65
+ * Open (`isClassLookupOpen: true`): the first element with the component's class, else `doc.getElementById(compId)`.
66
+ *
67
+ * An empty or non-string `compId` returns `null` in both modes without querying the DOM, as `getByCompId` in
68
+ * `thunderbolt-dom-utils` does.
69
+ */
70
+ export declare const getByCompId: (doc: Document, compId: string, options: CompLookupOptions) => HTMLElement | null;
71
+ /**
72
+ * Converts an ID-based selector to a class-based selector.
73
+ * Handles various selector patterns:
74
+ * - #id → .id
75
+ * - [id="value"] → [class~="value"]
76
+ * - [id^="value"] → :is([class^="value"],[class*=" value"]) — matches prefix as first or any subsequent class token
77
+ * - [id*="value"] → [class*="value"]
78
+ * - [id$="value"] → :is([class$="value"],[class*="value "]) — matches suffix as last or any earlier class token
79
+ *
80
+ * @param selector - The ID-based selector to convert
81
+ * @returns The class-based selector
82
+ */
83
+ export declare function convertIdSelectorToClassSelector(selector: string): string;
84
+ /**
85
+ * Finds every element matching an id-based selector, class-first. Mirrors `querySelectorAll` in
86
+ * `thunderbolt-dom-utils`, with an explicit `doc`, a boolean gate, no logger and no element scope.
87
+ *
88
+ * Closed (`isClassLookupOpen: false`): `Array.from(doc.querySelectorAll(selector))`, nothing else, so the elements,
89
+ * their order and the errors (such as the `SyntaxError` for an invalid selector) are the native query's.
90
+ *
91
+ * Open (`isClassLookupOpen: true`): the selector is converted with `convertIdSelectorToClassSelector` (for example
92
+ * `#a,#b` becomes `.a,.b`) and queried. If any element matches the class form, those elements are returned and the
93
+ * id form is not queried. Only when nothing matches the class form is `Array.from(doc.querySelectorAll(selector))`
94
+ * returned. The fallback is all-or-nothing: in `#a,#b`, if an element has the class `a`, an element that has only
95
+ * the id `b` is not returned. Document order and deduplication come from the native query.
96
+ *
97
+ * An empty or non-string `selector` returns `[]` in both modes without querying the DOM, as `querySelectorAll` in
98
+ * `thunderbolt-dom-utils` does.
99
+ *
100
+ * Unlike `thunderbolt-dom-utils`, an open lookup that falls back to the id selector is not metered yet; that is
101
+ * deferred.
102
+ */
103
+ export declare function querySelectorAll(doc: Document, selector: string, options: CompLookupOptions): Array<Element>;
@@ -0,0 +1,171 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.getByCompId = exports.getCompAndCopiesSelector = exports.getCompSelector = exports.canSelectByClass = 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
+ const CSS_IDENT = /^-?[a-zA-Z_][a-zA-Z0-9_-]*$/;
41
+ // HTML separates class tokens with any ASCII whitespace; control characters are escaped in CSS strings.
42
+ const CLASS_SEPARATORS = [' ', '\\9 ', '\\a ', '\\c ', '\\d '];
43
+ const escapeCssString = (value) => value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
44
+ /**
45
+ * Whether `getCompSelector` and `getCompAndCopiesSelector` return the class form for `compId`: lookup is open and
46
+ * `compId` is a plain ASCII CSS identifier. Otherwise they return the id form, so a caller that wraps the two forms
47
+ * differently (for example to keep an id selector's specificity) can tell which one it got.
48
+ */
49
+ const canSelectByClass = (compId, options) => options?.isClassLookupOpen === true && CSS_IDENT.test(compId);
50
+ exports.canSelectByClass = canSelectByClass;
51
+ /**
52
+ * A CSS selector for the element `#<compId>` selects: the component's own element, and not the copies of a
53
+ * repeated or forwarded component, which Thunderbolt gives the ids `<compId>__<item>`.
54
+ *
55
+ * Closed, or a `compId` that isn't a plain ASCII CSS identifier: `#<compId>`, with `compId` inserted as is, matching
56
+ * the `#<compId>` selectors it replaces.
57
+ *
58
+ * Open: `.<compId>`, excluding the elements that also carry a `<compId>__…` class (the copies, which carry the
59
+ * component's class beside their own) and a `.<compId>` inside another `.<compId>` (a component that repeats its
60
+ * class on an inner element). The class form weighs less than `#<compId>`; wrap it if specificity matters. Its
61
+ * exclusions make the browser re-match the selector on every class change in the page, so prefer
62
+ * `getCompAndCopiesSelector` when the copies may match too.
63
+ */
64
+ const getCompSelector = (compId, options) => {
65
+ if (!(0, exports.canSelectByClass)(compId, options)) {
66
+ return `#${compId}`;
67
+ }
68
+ const copies = [
69
+ `[class^="${compId}__"]`,
70
+ ...CLASS_SEPARATORS.map((separator) => `[class*="${separator}${compId}__"]`),
71
+ ];
72
+ return `.${compId}:not(${copies.join(', ')}, .${compId} .${compId})`;
73
+ };
74
+ exports.getCompSelector = getCompSelector;
75
+ /**
76
+ * A CSS selector for every element of a component: its own and, for a repeated or forwarded component, each
77
+ * copy's (`<compId>__<item>`).
78
+ *
79
+ * Closed, or a `compId` that isn't a plain ASCII CSS identifier: `:is([id="<compId>"], [id^="<compId>__"])`.
80
+ *
81
+ * Open: `.<compId>`. Thunderbolt puts the component's class on the copies too, beside their own
82
+ * `<compId>__<item>` class, so the one class matches what both id branches match, with the same specificity.
83
+ */
84
+ const getCompAndCopiesSelector = (compId, options) => {
85
+ if ((0, exports.canSelectByClass)(compId, options)) {
86
+ return `.${compId}`;
87
+ }
88
+ const escaped = escapeCssString(compId);
89
+ return `:is([id="${escaped}"], [id^="${escaped}__"])`;
90
+ };
91
+ exports.getCompAndCopiesSelector = getCompAndCopiesSelector;
92
+ /**
93
+ * Finds a component's element.
94
+ *
95
+ * Closed (`isClassLookupOpen: false`): `doc.getElementById(compId)`, nothing else.
96
+ *
97
+ * Open (`isClassLookupOpen: true`): the first element with the component's class, else `doc.getElementById(compId)`.
98
+ *
99
+ * An empty or non-string `compId` returns `null` in both modes without querying the DOM, as `getByCompId` in
100
+ * `thunderbolt-dom-utils` does.
101
+ */
102
+ const getByCompId = (doc, compId, options) => {
103
+ if (!compId || typeof compId !== 'string') {
104
+ return null;
105
+ }
106
+ if (options?.isClassLookupOpen !== true) {
107
+ return doc.getElementById(compId);
108
+ }
109
+ return doc.querySelector(toClassSelector(compId)) ?? doc.getElementById(compId);
110
+ };
111
+ exports.getByCompId = getByCompId;
112
+ /**
113
+ * Converts an ID-based selector to a class-based selector.
114
+ * Handles various selector patterns:
115
+ * - #id → .id
116
+ * - [id="value"] → [class~="value"]
117
+ * - [id^="value"] → :is([class^="value"],[class*=" value"]) — matches prefix as first or any subsequent class token
118
+ * - [id*="value"] → [class*="value"]
119
+ * - [id$="value"] → :is([class$="value"],[class*="value "]) — matches suffix as last or any earlier class token
120
+ *
121
+ * @param selector - The ID-based selector to convert
122
+ * @returns The class-based selector
123
+ */
124
+ function convertIdSelectorToClassSelector(selector) {
125
+ return (selector
126
+ // Replace #id with .id
127
+ .replace(/#([a-zA-Z0-9_-]+)/g, '.$1')
128
+ // Replace [id="value"] with [class~="value"] (exact match in space-separated list)
129
+ .replace(/\[id="([^"]+)"\]/g, '[class~="$1"]')
130
+ // Replace [id^="value"] with :is([class^="value"],[class*=" value"])
131
+ // [class^="value"] matches when the class is first; [class*=" value"] matches any subsequent token.
132
+ // Together they reliably match a prefix regardless of class order in the attribute.
133
+ .replace(/\[id\^="([^"]+)"\]/g, ':is([class^="$1"],[class*=" $1"])')
134
+ // Replace [id*="value"] with [class*="value"] (contains)
135
+ .replace(/\[id\*="([^"]+)"\]/g, '[class*="$1"]')
136
+ // Replace [id$="value"] with :is([class$="value"],[class*="value "])
137
+ // [class$="value"] matches when the class is last; [class*="value "] matches any earlier token.
138
+ // The identity class is rarely last: components append their own classes after it, and the
139
+ // editor appends wix-select.
140
+ .replace(/\[id\$="([^"]+)"\]/g, ':is([class$="$1"],[class*="$1 "])'));
141
+ }
142
+ /**
143
+ * Finds every element matching an id-based selector, class-first. Mirrors `querySelectorAll` in
144
+ * `thunderbolt-dom-utils`, with an explicit `doc`, a boolean gate, no logger and no element scope.
145
+ *
146
+ * Closed (`isClassLookupOpen: false`): `Array.from(doc.querySelectorAll(selector))`, nothing else, so the elements,
147
+ * their order and the errors (such as the `SyntaxError` for an invalid selector) are the native query's.
148
+ *
149
+ * Open (`isClassLookupOpen: true`): the selector is converted with `convertIdSelectorToClassSelector` (for example
150
+ * `#a,#b` becomes `.a,.b`) and queried. If any element matches the class form, those elements are returned and the
151
+ * id form is not queried. Only when nothing matches the class form is `Array.from(doc.querySelectorAll(selector))`
152
+ * returned. The fallback is all-or-nothing: in `#a,#b`, if an element has the class `a`, an element that has only
153
+ * the id `b` is not returned. Document order and deduplication come from the native query.
154
+ *
155
+ * An empty or non-string `selector` returns `[]` in both modes without querying the DOM, as `querySelectorAll` in
156
+ * `thunderbolt-dom-utils` does.
157
+ *
158
+ * Unlike `thunderbolt-dom-utils`, an open lookup that falls back to the id selector is not metered yet; that is
159
+ * deferred.
160
+ */
161
+ function querySelectorAll(doc, selector, options) {
162
+ if (!selector || typeof selector !== 'string') {
163
+ return [];
164
+ }
165
+ if (options?.isClassLookupOpen !== true) {
166
+ return Array.from(doc.querySelectorAll(selector));
167
+ }
168
+ const byClass = Array.from(doc.querySelectorAll(convertIdSelectorToClassSelector(selector)));
169
+ return byClass.length > 0 ? byClass : Array.from(doc.querySelectorAll(selector));
170
+ }
171
+ //# sourceMappingURL=domSelectors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"domSelectors.js","sourceRoot":"","sources":["../../../src/dom-utils/domSelectors.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, canSelectByClass, getByCompId, getCompAndCopiesSelector, getCompSelector, querySelectorAll, } from './domSelectors';
2
+ export type { CompLookupOptions } from './domSelectors';
@@ -0,0 +1,12 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.querySelectorAll = exports.getCompSelector = exports.getCompAndCopiesSelector = exports.getByCompId = exports.canSelectByClass = 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, "canSelectByClass", { enumerable: true, get: function () { return domSelectors_1.canSelectByClass; } });
8
+ Object.defineProperty(exports, "getByCompId", { enumerable: true, get: function () { return domSelectors_1.getByCompId; } });
9
+ Object.defineProperty(exports, "getCompAndCopiesSelector", { enumerable: true, get: function () { return domSelectors_1.getCompAndCopiesSelector; } });
10
+ Object.defineProperty(exports, "getCompSelector", { enumerable: true, get: function () { return domSelectors_1.getCompSelector; } });
11
+ Object.defineProperty(exports, "querySelectorAll", { enumerable: true, get: function () { return domSelectors_1.querySelectorAll; } });
12
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/dom-utils/index.ts"],"names":[],"mappings":";;;AAAA,+CAQuB;AAPtB,+HAAA,+BAA+B,OAAA;AAC/B,uHAAA,uBAAuB,OAAA;AACvB,gHAAA,gBAAgB,OAAA;AAChB,2GAAA,WAAW,OAAA;AACX,wHAAA,wBAAwB,OAAA;AACxB,+GAAA,eAAe,OAAA;AACf,gHAAA,gBAAgB,OAAA"}
@@ -0,0 +1,103 @@
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
+ * Whether `getCompSelector` and `getCompAndCopiesSelector` return the class form for `compId`: lookup is open and
32
+ * `compId` is a plain ASCII CSS identifier. Otherwise they return the id form, so a caller that wraps the two forms
33
+ * differently (for example to keep an id selector's specificity) can tell which one it got.
34
+ */
35
+ export declare const canSelectByClass: (compId: string, options: CompLookupOptions) => boolean;
36
+ /**
37
+ * A CSS selector for the element `#<compId>` selects: the component's own element, and not the copies of a
38
+ * repeated or forwarded component, which Thunderbolt gives the ids `<compId>__<item>`.
39
+ *
40
+ * Closed, or a `compId` that isn't a plain ASCII CSS identifier: `#<compId>`, with `compId` inserted as is, matching
41
+ * the `#<compId>` selectors it replaces.
42
+ *
43
+ * Open: `.<compId>`, excluding the elements that also carry a `<compId>__…` class (the copies, which carry the
44
+ * component's class beside their own) and a `.<compId>` inside another `.<compId>` (a component that repeats its
45
+ * class on an inner element). The class form weighs less than `#<compId>`; wrap it if specificity matters. Its
46
+ * exclusions make the browser re-match the selector on every class change in the page, so prefer
47
+ * `getCompAndCopiesSelector` when the copies may match too.
48
+ */
49
+ export declare const getCompSelector: (compId: string, options: CompLookupOptions) => string;
50
+ /**
51
+ * A CSS selector for every element of a component: its own and, for a repeated or forwarded component, each
52
+ * copy's (`<compId>__<item>`).
53
+ *
54
+ * Closed, or a `compId` that isn't a plain ASCII CSS identifier: `:is([id="<compId>"], [id^="<compId>__"])`.
55
+ *
56
+ * Open: `.<compId>`. Thunderbolt puts the component's class on the copies too, beside their own
57
+ * `<compId>__<item>` class, so the one class matches what both id branches match, with the same specificity.
58
+ */
59
+ export declare const getCompAndCopiesSelector: (compId: string, options: CompLookupOptions) => string;
60
+ /**
61
+ * Finds a component's element.
62
+ *
63
+ * Closed (`isClassLookupOpen: false`): `doc.getElementById(compId)`, nothing else.
64
+ *
65
+ * Open (`isClassLookupOpen: true`): the first element with the component's class, else `doc.getElementById(compId)`.
66
+ *
67
+ * An empty or non-string `compId` returns `null` in both modes without querying the DOM, as `getByCompId` in
68
+ * `thunderbolt-dom-utils` does.
69
+ */
70
+ export declare const getByCompId: (doc: Document, compId: string, options: CompLookupOptions) => HTMLElement | null;
71
+ /**
72
+ * Converts an ID-based selector to a class-based selector.
73
+ * Handles various selector patterns:
74
+ * - #id → .id
75
+ * - [id="value"] → [class~="value"]
76
+ * - [id^="value"] → :is([class^="value"],[class*=" value"]) — matches prefix as first or any subsequent class token
77
+ * - [id*="value"] → [class*="value"]
78
+ * - [id$="value"] → :is([class$="value"],[class*="value "]) — matches suffix as last or any earlier class token
79
+ *
80
+ * @param selector - The ID-based selector to convert
81
+ * @returns The class-based selector
82
+ */
83
+ export declare function convertIdSelectorToClassSelector(selector: string): string;
84
+ /**
85
+ * Finds every element matching an id-based selector, class-first. Mirrors `querySelectorAll` in
86
+ * `thunderbolt-dom-utils`, with an explicit `doc`, a boolean gate, no logger and no element scope.
87
+ *
88
+ * Closed (`isClassLookupOpen: false`): `Array.from(doc.querySelectorAll(selector))`, nothing else, so the elements,
89
+ * their order and the errors (such as the `SyntaxError` for an invalid selector) are the native query's.
90
+ *
91
+ * Open (`isClassLookupOpen: true`): the selector is converted with `convertIdSelectorToClassSelector` (for example
92
+ * `#a,#b` becomes `.a,.b`) and queried. If any element matches the class form, those elements are returned and the
93
+ * id form is not queried. Only when nothing matches the class form is `Array.from(doc.querySelectorAll(selector))`
94
+ * returned. The fallback is all-or-nothing: in `#a,#b`, if an element has the class `a`, an element that has only
95
+ * the id `b` is not returned. Document order and deduplication come from the native query.
96
+ *
97
+ * An empty or non-string `selector` returns `[]` in both modes without querying the DOM, as `querySelectorAll` in
98
+ * `thunderbolt-dom-utils` does.
99
+ *
100
+ * Unlike `thunderbolt-dom-utils`, an open lookup that falls back to the id selector is not metered yet; that is
101
+ * deferred.
102
+ */
103
+ export declare function querySelectorAll(doc: Document, selector: string, options: CompLookupOptions): Array<Element>;
@@ -0,0 +1,161 @@
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
+ const CSS_IDENT = /^-?[a-zA-Z_][a-zA-Z0-9_-]*$/;
35
+ // HTML separates class tokens with any ASCII whitespace; control characters are escaped in CSS strings.
36
+ const CLASS_SEPARATORS = [' ', '\\9 ', '\\a ', '\\c ', '\\d '];
37
+ const escapeCssString = (value) => value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
38
+ /**
39
+ * Whether `getCompSelector` and `getCompAndCopiesSelector` return the class form for `compId`: lookup is open and
40
+ * `compId` is a plain ASCII CSS identifier. Otherwise they return the id form, so a caller that wraps the two forms
41
+ * differently (for example to keep an id selector's specificity) can tell which one it got.
42
+ */
43
+ export const canSelectByClass = (compId, options) => options?.isClassLookupOpen === true && CSS_IDENT.test(compId);
44
+ /**
45
+ * A CSS selector for the element `#<compId>` selects: the component's own element, and not the copies of a
46
+ * repeated or forwarded component, which Thunderbolt gives the ids `<compId>__<item>`.
47
+ *
48
+ * Closed, or a `compId` that isn't a plain ASCII CSS identifier: `#<compId>`, with `compId` inserted as is, matching
49
+ * the `#<compId>` selectors it replaces.
50
+ *
51
+ * Open: `.<compId>`, excluding the elements that also carry a `<compId>__…` class (the copies, which carry the
52
+ * component's class beside their own) and a `.<compId>` inside another `.<compId>` (a component that repeats its
53
+ * class on an inner element). The class form weighs less than `#<compId>`; wrap it if specificity matters. Its
54
+ * exclusions make the browser re-match the selector on every class change in the page, so prefer
55
+ * `getCompAndCopiesSelector` when the copies may match too.
56
+ */
57
+ export const getCompSelector = (compId, options) => {
58
+ if (!canSelectByClass(compId, options)) {
59
+ return `#${compId}`;
60
+ }
61
+ const copies = [
62
+ `[class^="${compId}__"]`,
63
+ ...CLASS_SEPARATORS.map((separator) => `[class*="${separator}${compId}__"]`),
64
+ ];
65
+ return `.${compId}:not(${copies.join(', ')}, .${compId} .${compId})`;
66
+ };
67
+ /**
68
+ * A CSS selector for every element of a component: its own and, for a repeated or forwarded component, each
69
+ * copy's (`<compId>__<item>`).
70
+ *
71
+ * Closed, or a `compId` that isn't a plain ASCII CSS identifier: `:is([id="<compId>"], [id^="<compId>__"])`.
72
+ *
73
+ * Open: `.<compId>`. Thunderbolt puts the component's class on the copies too, beside their own
74
+ * `<compId>__<item>` class, so the one class matches what both id branches match, with the same specificity.
75
+ */
76
+ export const getCompAndCopiesSelector = (compId, options) => {
77
+ if (canSelectByClass(compId, options)) {
78
+ return `.${compId}`;
79
+ }
80
+ const escaped = escapeCssString(compId);
81
+ return `:is([id="${escaped}"], [id^="${escaped}__"])`;
82
+ };
83
+ /**
84
+ * Finds a component's element.
85
+ *
86
+ * Closed (`isClassLookupOpen: false`): `doc.getElementById(compId)`, nothing else.
87
+ *
88
+ * Open (`isClassLookupOpen: true`): the first element with the component's class, else `doc.getElementById(compId)`.
89
+ *
90
+ * An empty or non-string `compId` returns `null` in both modes without querying the DOM, as `getByCompId` in
91
+ * `thunderbolt-dom-utils` does.
92
+ */
93
+ export const getByCompId = (doc, compId, options) => {
94
+ if (!compId || typeof compId !== 'string') {
95
+ return null;
96
+ }
97
+ if (options?.isClassLookupOpen !== true) {
98
+ return doc.getElementById(compId);
99
+ }
100
+ return doc.querySelector(toClassSelector(compId)) ?? doc.getElementById(compId);
101
+ };
102
+ /**
103
+ * Converts an ID-based selector to a class-based selector.
104
+ * Handles various selector patterns:
105
+ * - #id → .id
106
+ * - [id="value"] → [class~="value"]
107
+ * - [id^="value"] → :is([class^="value"],[class*=" value"]) — matches prefix as first or any subsequent class token
108
+ * - [id*="value"] → [class*="value"]
109
+ * - [id$="value"] → :is([class$="value"],[class*="value "]) — matches suffix as last or any earlier class token
110
+ *
111
+ * @param selector - The ID-based selector to convert
112
+ * @returns The class-based selector
113
+ */
114
+ export function convertIdSelectorToClassSelector(selector) {
115
+ return (selector
116
+ // Replace #id with .id
117
+ .replace(/#([a-zA-Z0-9_-]+)/g, '.$1')
118
+ // Replace [id="value"] with [class~="value"] (exact match in space-separated list)
119
+ .replace(/\[id="([^"]+)"\]/g, '[class~="$1"]')
120
+ // Replace [id^="value"] with :is([class^="value"],[class*=" value"])
121
+ // [class^="value"] matches when the class is first; [class*=" value"] matches any subsequent token.
122
+ // Together they reliably match a prefix regardless of class order in the attribute.
123
+ .replace(/\[id\^="([^"]+)"\]/g, ':is([class^="$1"],[class*=" $1"])')
124
+ // Replace [id*="value"] with [class*="value"] (contains)
125
+ .replace(/\[id\*="([^"]+)"\]/g, '[class*="$1"]')
126
+ // Replace [id$="value"] with :is([class$="value"],[class*="value "])
127
+ // [class$="value"] matches when the class is last; [class*="value "] matches any earlier token.
128
+ // The identity class is rarely last: components append their own classes after it, and the
129
+ // editor appends wix-select.
130
+ .replace(/\[id\$="([^"]+)"\]/g, ':is([class$="$1"],[class*="$1 "])'));
131
+ }
132
+ /**
133
+ * Finds every element matching an id-based selector, class-first. Mirrors `querySelectorAll` in
134
+ * `thunderbolt-dom-utils`, with an explicit `doc`, a boolean gate, no logger and no element scope.
135
+ *
136
+ * Closed (`isClassLookupOpen: false`): `Array.from(doc.querySelectorAll(selector))`, nothing else, so the elements,
137
+ * their order and the errors (such as the `SyntaxError` for an invalid selector) are the native query's.
138
+ *
139
+ * Open (`isClassLookupOpen: true`): the selector is converted with `convertIdSelectorToClassSelector` (for example
140
+ * `#a,#b` becomes `.a,.b`) and queried. If any element matches the class form, those elements are returned and the
141
+ * id form is not queried. Only when nothing matches the class form is `Array.from(doc.querySelectorAll(selector))`
142
+ * returned. The fallback is all-or-nothing: in `#a,#b`, if an element has the class `a`, an element that has only
143
+ * the id `b` is not returned. Document order and deduplication come from the native query.
144
+ *
145
+ * An empty or non-string `selector` returns `[]` in both modes without querying the DOM, as `querySelectorAll` in
146
+ * `thunderbolt-dom-utils` does.
147
+ *
148
+ * Unlike `thunderbolt-dom-utils`, an open lookup that falls back to the id selector is not metered yet; that is
149
+ * deferred.
150
+ */
151
+ export function querySelectorAll(doc, selector, options) {
152
+ if (!selector || typeof selector !== 'string') {
153
+ return [];
154
+ }
155
+ if (options?.isClassLookupOpen !== true) {
156
+ return Array.from(doc.querySelectorAll(selector));
157
+ }
158
+ const byClass = Array.from(doc.querySelectorAll(convertIdSelectorToClassSelector(selector)));
159
+ return byClass.length > 0 ? byClass : Array.from(doc.querySelectorAll(selector));
160
+ }
161
+ //# 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,MAAM,SAAS,GAAG,6BAA6B,CAAA;AAE/C,wGAAwG;AACxG,MAAM,gBAAgB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;AAE9D,MAAM,eAAe,GAAG,CAAC,KAAa,EAAU,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;AAEpG;;;;GAIG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,MAAc,EAAE,OAA0B,EAAW,EAAE,CACvF,OAAO,EAAE,iBAAiB,KAAK,IAAI,IAAI,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;AAE9D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,MAAc,EAAE,OAA0B,EAAU,EAAE;IACrF,IAAI,CAAC,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;QACxC,OAAO,IAAI,MAAM,EAAE,CAAA;IACpB,CAAC;IACD,MAAM,MAAM,GAAG;QACd,YAAY,MAAM,MAAM;QACxB,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,YAAY,SAAS,GAAG,MAAM,MAAM,CAAC;KAC5E,CAAA;IACD,OAAO,IAAI,MAAM,QAAQ,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,MAAM,KAAK,MAAM,GAAG,CAAA;AACrE,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,MAAc,EAAE,OAA0B,EAAU,EAAE;IAC9F,IAAI,gBAAgB,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;QACvC,OAAO,IAAI,MAAM,EAAE,CAAA;IACpB,CAAC;IACD,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;IACvC,OAAO,YAAY,OAAO,aAAa,OAAO,OAAO,CAAA;AACtD,CAAC,CAAA;AAED;;;;;;;;;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, canSelectByClass, getByCompId, getCompAndCopiesSelector, getCompSelector, querySelectorAll, } from './domSelectors';
2
+ export type { CompLookupOptions } from './domSelectors';
@@ -0,0 +1,2 @@
1
+ export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, canSelectByClass, getByCompId, getCompAndCopiesSelector, getCompSelector, 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,EACN,+BAA+B,EAC/B,uBAAuB,EACvB,gBAAgB,EAChB,WAAW,EACX,wBAAwB,EACxB,eAAe,EACf,gBAAgB,GAChB,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.2",
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": "567d1b3f7b709837623bb764991b32bb05b9885260efca0306f5c545"
6
56
  }
@@ -0,0 +1,185 @@
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
+ const CSS_IDENT = /^-?[a-zA-Z_][a-zA-Z0-9_-]*$/
49
+
50
+ // HTML separates class tokens with any ASCII whitespace; control characters are escaped in CSS strings.
51
+ const CLASS_SEPARATORS = [' ', '\\9 ', '\\a ', '\\c ', '\\d ']
52
+
53
+ const escapeCssString = (value: string): string => value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')
54
+
55
+ /**
56
+ * Whether `getCompSelector` and `getCompAndCopiesSelector` return the class form for `compId`: lookup is open and
57
+ * `compId` is a plain ASCII CSS identifier. Otherwise they return the id form, so a caller that wraps the two forms
58
+ * differently (for example to keep an id selector's specificity) can tell which one it got.
59
+ */
60
+ export const canSelectByClass = (compId: string, options: CompLookupOptions): boolean =>
61
+ options?.isClassLookupOpen === true && CSS_IDENT.test(compId)
62
+
63
+ /**
64
+ * A CSS selector for the element `#<compId>` selects: the component's own element, and not the copies of a
65
+ * repeated or forwarded component, which Thunderbolt gives the ids `<compId>__<item>`.
66
+ *
67
+ * Closed, or a `compId` that isn't a plain ASCII CSS identifier: `#<compId>`, with `compId` inserted as is, matching
68
+ * the `#<compId>` selectors it replaces.
69
+ *
70
+ * Open: `.<compId>`, excluding the elements that also carry a `<compId>__…` class (the copies, which carry the
71
+ * component's class beside their own) and a `.<compId>` inside another `.<compId>` (a component that repeats its
72
+ * class on an inner element). The class form weighs less than `#<compId>`; wrap it if specificity matters. Its
73
+ * exclusions make the browser re-match the selector on every class change in the page, so prefer
74
+ * `getCompAndCopiesSelector` when the copies may match too.
75
+ */
76
+ export const getCompSelector = (compId: string, options: CompLookupOptions): string => {
77
+ if (!canSelectByClass(compId, options)) {
78
+ return `#${compId}`
79
+ }
80
+ const copies = [
81
+ `[class^="${compId}__"]`,
82
+ ...CLASS_SEPARATORS.map((separator) => `[class*="${separator}${compId}__"]`),
83
+ ]
84
+ return `.${compId}:not(${copies.join(', ')}, .${compId} .${compId})`
85
+ }
86
+
87
+ /**
88
+ * A CSS selector for every element of a component: its own and, for a repeated or forwarded component, each
89
+ * copy's (`<compId>__<item>`).
90
+ *
91
+ * Closed, or a `compId` that isn't a plain ASCII CSS identifier: `:is([id="<compId>"], [id^="<compId>__"])`.
92
+ *
93
+ * Open: `.<compId>`. Thunderbolt puts the component's class on the copies too, beside their own
94
+ * `<compId>__<item>` class, so the one class matches what both id branches match, with the same specificity.
95
+ */
96
+ export const getCompAndCopiesSelector = (compId: string, options: CompLookupOptions): string => {
97
+ if (canSelectByClass(compId, options)) {
98
+ return `.${compId}`
99
+ }
100
+ const escaped = escapeCssString(compId)
101
+ return `:is([id="${escaped}"], [id^="${escaped}__"])`
102
+ }
103
+
104
+ /**
105
+ * Finds a component's element.
106
+ *
107
+ * Closed (`isClassLookupOpen: false`): `doc.getElementById(compId)`, nothing else.
108
+ *
109
+ * Open (`isClassLookupOpen: true`): the first element with the component's class, else `doc.getElementById(compId)`.
110
+ *
111
+ * An empty or non-string `compId` returns `null` in both modes without querying the DOM, as `getByCompId` in
112
+ * `thunderbolt-dom-utils` does.
113
+ */
114
+ export const getByCompId = (doc: Document, compId: string, options: CompLookupOptions): HTMLElement | null => {
115
+ if (!compId || typeof compId !== 'string') {
116
+ return null
117
+ }
118
+ if (options?.isClassLookupOpen !== true) {
119
+ return doc.getElementById(compId)
120
+ }
121
+ return doc.querySelector<HTMLElement>(toClassSelector(compId)) ?? doc.getElementById(compId)
122
+ }
123
+
124
+ /**
125
+ * Converts an ID-based selector to a class-based selector.
126
+ * Handles various selector patterns:
127
+ * - #id → .id
128
+ * - [id="value"] → [class~="value"]
129
+ * - [id^="value"] → :is([class^="value"],[class*=" value"]) — matches prefix as first or any subsequent class token
130
+ * - [id*="value"] → [class*="value"]
131
+ * - [id$="value"] → :is([class$="value"],[class*="value "]) — matches suffix as last or any earlier class token
132
+ *
133
+ * @param selector - The ID-based selector to convert
134
+ * @returns The class-based selector
135
+ */
136
+ export function convertIdSelectorToClassSelector(selector: string): string {
137
+ return (
138
+ selector
139
+ // Replace #id with .id
140
+ .replace(/#([a-zA-Z0-9_-]+)/g, '.$1')
141
+ // Replace [id="value"] with [class~="value"] (exact match in space-separated list)
142
+ .replace(/\[id="([^"]+)"\]/g, '[class~="$1"]')
143
+ // Replace [id^="value"] with :is([class^="value"],[class*=" value"])
144
+ // [class^="value"] matches when the class is first; [class*=" value"] matches any subsequent token.
145
+ // Together they reliably match a prefix regardless of class order in the attribute.
146
+ .replace(/\[id\^="([^"]+)"\]/g, ':is([class^="$1"],[class*=" $1"])')
147
+ // Replace [id*="value"] with [class*="value"] (contains)
148
+ .replace(/\[id\*="([^"]+)"\]/g, '[class*="$1"]')
149
+ // Replace [id$="value"] with :is([class$="value"],[class*="value "])
150
+ // [class$="value"] matches when the class is last; [class*="value "] matches any earlier token.
151
+ // The identity class is rarely last: components append their own classes after it, and the
152
+ // editor appends wix-select.
153
+ .replace(/\[id\$="([^"]+)"\]/g, ':is([class$="$1"],[class*="$1 "])')
154
+ )
155
+ }
156
+
157
+ /**
158
+ * Finds every element matching an id-based selector, class-first. Mirrors `querySelectorAll` in
159
+ * `thunderbolt-dom-utils`, with an explicit `doc`, a boolean gate, no logger and no element scope.
160
+ *
161
+ * Closed (`isClassLookupOpen: false`): `Array.from(doc.querySelectorAll(selector))`, nothing else, so the elements,
162
+ * their order and the errors (such as the `SyntaxError` for an invalid selector) are the native query's.
163
+ *
164
+ * Open (`isClassLookupOpen: true`): the selector is converted with `convertIdSelectorToClassSelector` (for example
165
+ * `#a,#b` becomes `.a,.b`) and queried. If any element matches the class form, those elements are returned and the
166
+ * id form is not queried. Only when nothing matches the class form is `Array.from(doc.querySelectorAll(selector))`
167
+ * returned. The fallback is all-or-nothing: in `#a,#b`, if an element has the class `a`, an element that has only
168
+ * the id `b` is not returned. Document order and deduplication come from the native query.
169
+ *
170
+ * An empty or non-string `selector` returns `[]` in both modes without querying the DOM, as `querySelectorAll` in
171
+ * `thunderbolt-dom-utils` does.
172
+ *
173
+ * Unlike `thunderbolt-dom-utils`, an open lookup that falls back to the id selector is not metered yet; that is
174
+ * deferred.
175
+ */
176
+ export function querySelectorAll(doc: Document, selector: string, options: CompLookupOptions): Array<Element> {
177
+ if (!selector || typeof selector !== 'string') {
178
+ return []
179
+ }
180
+ if (options?.isClassLookupOpen !== true) {
181
+ return Array.from(doc.querySelectorAll(selector))
182
+ }
183
+ const byClass = Array.from(doc.querySelectorAll(convertIdSelectorToClassSelector(selector)))
184
+ return byClass.length > 0 ? byClass : Array.from(doc.querySelectorAll(selector))
185
+ }
@@ -0,0 +1,10 @@
1
+ export {
2
+ ADD_ID_AS_CLASS_NAME_EXPERIMENT,
3
+ CLASS_LOOKUP_EXPERIMENT,
4
+ canSelectByClass,
5
+ getByCompId,
6
+ getCompAndCopiesSelector,
7
+ getCompSelector,
8
+ querySelectorAll,
9
+ } from './domSelectors'
10
+ export type { CompLookupOptions } from './domSelectors'