@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 +129 -2
- package/cjs/build/dom-utils/domSelectors.d.ts +103 -0
- package/cjs/build/dom-utils/domSelectors.js +171 -0
- package/cjs/build/dom-utils/domSelectors.js.map +1 -0
- package/cjs/build/dom-utils/index.d.ts +2 -0
- package/cjs/build/dom-utils/index.js +12 -0
- package/cjs/build/dom-utils/index.js.map +1 -0
- package/dist/dom-utils/domSelectors.d.ts +103 -0
- package/dist/dom-utils/domSelectors.js +161 -0
- package/dist/dom-utils/domSelectors.js.map +1 -0
- package/dist/dom-utils/index.d.ts +2 -0
- package/dist/dom-utils/index.js +2 -0
- package/dist/dom-utils/index.js.map +1 -0
- package/dom-utils/package.json +3 -0
- package/package.json +53 -3
- package/src/dom-utils/domSelectors.ts +185 -0
- package/src/dom-utils/index.ts +10 -0
package/README.md
CHANGED
|
@@ -1,3 +1,130 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @wix/viewer-core-services-utils
|
|
2
2
|
|
|
3
|
-
This
|
|
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,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":"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"}
|
|
@@ -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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,56 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@wix/viewer-core-services-utils",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|