@wix/viewer-core-services-utils 1.0.1 → 1.0.3

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
@@ -8,7 +8,7 @@ Each utility lives in its own subpath module. There is no root entry point, so a
8
8
 
9
9
  | Subpath | What it does |
10
10
  | --- | --- |
11
- | `@wix/viewer-core-services-utils/dom-utils` | Class-first component element lookup |
11
+ | `@wix/viewer-core-services-utils/dom-utils` | Class-first component element lookup and selectors |
12
12
 
13
13
  ## Install
14
14
 
@@ -52,7 +52,10 @@ Only `isClassLookupOpen: true` opens the gate; `false`, or any other value a Jav
52
52
  import {
53
53
  ADD_ID_AS_CLASS_NAME_EXPERIMENT,
54
54
  CLASS_LOOKUP_EXPERIMENT,
55
+ canSelectByClass,
55
56
  getByCompId,
57
+ getCompAndCopiesSelector,
58
+ getCompSelector,
56
59
  querySelectorAll,
57
60
  } from '@wix/viewer-core-services-utils/dom-utils'
58
61
  ```
@@ -88,6 +91,30 @@ Finds every element matching an id-based selector, class-first. Mirrors `querySe
88
91
  const elements = querySelectorAll(document, '#comp-1,#comp-2', { isClassLookupOpen })
89
92
  ```
90
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
+
91
118
  #### Types
92
119
 
93
120
  - `CompLookupOptions`: `{ isClassLookupOpen: boolean }`. `isClassLookupOpen` is required and has no default, so it can't be left out by accident.
@@ -27,6 +27,36 @@ export type CompLookupOptions = {
27
27
  * character other than ASCII letters, digits, `_` and `-`.
28
28
  */
29
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;
30
60
  /**
31
61
  * Finds a component's element.
32
62
  *
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.getByCompId = exports.ADD_ID_AS_CLASS_NAME_EXPERIMENT = exports.CLASS_LOOKUP_EXPERIMENT = void 0;
3
+ exports.getByCompId = exports.getCompAndCopiesSelector = exports.getCompSelector = exports.canSelectByClass = exports.ADD_ID_AS_CLASS_NAME_EXPERIMENT = exports.CLASS_LOOKUP_EXPERIMENT = void 0;
4
4
  exports.escapeIdent = escapeIdent;
5
5
  exports.convertIdSelectorToClassSelector = convertIdSelectorToClassSelector;
6
6
  exports.querySelectorAll = querySelectorAll;
@@ -37,6 +37,58 @@ function escapeIdent(value) {
37
37
  }
38
38
  /** The class selector for a component, for example `.comp-abc`. */
39
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;
40
92
  /**
41
93
  * Finds a component's element.
42
94
  *
@@ -52,8 +104,10 @@ const getByCompId = (doc, compId, options) => {
52
104
  return null;
53
105
  }
54
106
  if (options?.isClassLookupOpen !== true) {
107
+ // dom-id-usage-check-ignore-next-line -- this compatibility helper owns the legacy component-ID fallback
55
108
  return doc.getElementById(compId);
56
109
  }
110
+ // dom-id-usage-check-ignore-next-line -- this compatibility helper owns the legacy component-ID fallback
57
111
  return doc.querySelector(toClassSelector(compId)) ?? doc.getElementById(compId);
58
112
  };
59
113
  exports.getByCompId = getByCompId;
@@ -1 +1 @@
1
- {"version":3,"file":"domSelectors.js","sourceRoot":"","sources":["../../../src/dom-utils/domSelectors.ts"],"names":[],"mappings":";;;;;;AAAA;;;;GAIG;AACU,QAAA,uBAAuB,GAAG,6BAA6B,CAAA;AAEpE;;;;GAIG;AACU,QAAA,+BAA+B,GAAG,oCAAoC,CAAA;AAYnF;;;;;;GAMG;AACH,qBAA4B,KAAa;IACxC,IAAI,OAAO,GAAG,KAAK,WAAW,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACpE,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACzB,CAAC;IACD,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,KAAK,CAAA;IACb,CAAC;IACD,2GAA2G;IAC3G,iEAAiE;IACjE,MAAM,kBAAkB,GAAG,KAAK,CAAC,OAAO,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAA;IACnE,OAAO,kBAAkB,CAAC,OAAO,CAAC,WAAW,EAAE,UAAU,CAAC,CAAA;AAC3D,CAAC;AAED,mEAAmE;AACnE,MAAM,eAAe,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAA;AAErE;;;;;;;;;GASG;AACI,MAAM,WAAW,GAAG,CAAC,GAAa,EAAE,MAAc,EAAE,OAA0B,EAAsB,EAAE;IAC5G,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAA;IACZ,CAAC;IACD,IAAI,OAAO,EAAE,iBAAiB,KAAK,IAAI,EAAE,CAAC;QACzC,OAAO,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;IAClC,CAAC;IACD,OAAO,GAAG,CAAC,aAAa,CAAc,eAAe,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;AAC7F,CAAC,CAAA;AARY,QAAA,WAAW,GAAX,WAAW,CAQvB;AAED;;;;;;;;;;;GAWG;AACH,0CAAiD,QAAgB;IAChE,OAAO,CACN,QAAQ;QACP,uBAAuB;SACtB,OAAO,CAAC,oBAAoB,EAAE,KAAK,CAAC;QACrC,mFAAmF;SAClF,OAAO,CAAC,mBAAmB,EAAE,eAAe,CAAC;QAC9C,qEAAqE;QACrE,oGAAoG;QACpG,oFAAoF;SACnF,OAAO,CAAC,qBAAqB,EAAE,mCAAmC,CAAC;QACpE,yDAAyD;SACxD,OAAO,CAAC,qBAAqB,EAAE,eAAe,CAAC;QAChD,qEAAqE;QACrE,gGAAgG;QAChG,2FAA2F;QAC3F,6BAA6B;SAC5B,OAAO,CAAC,qBAAqB,EAAE,mCAAmC,CAAC,CACrE,CAAA;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,0BAAiC,GAAa,EAAE,QAAgB,EAAE,OAA0B;IAC3F,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,EAAE,CAAA;IACV,CAAC;IACD,IAAI,OAAO,EAAE,iBAAiB,KAAK,IAAI,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAA;IAClD,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,gCAAgC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;IAC5F,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAA;AACjF,CAAC"}
1
+ {"version":3,"file":"domSelectors.js","sourceRoot":"","sources":["../../../src/dom-utils/domSelectors.ts"],"names":[],"mappings":"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"}
@@ -1,2 +1,2 @@
1
- export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, getByCompId, querySelectorAll } from './domSelectors';
1
+ export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, canSelectByClass, getByCompId, getCompAndCopiesSelector, getCompSelector, querySelectorAll, } from './domSelectors';
2
2
  export type { CompLookupOptions } from './domSelectors';
@@ -1,9 +1,12 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.querySelectorAll = exports.getByCompId = exports.CLASS_LOOKUP_EXPERIMENT = exports.ADD_ID_AS_CLASS_NAME_EXPERIMENT = void 0;
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
4
  var domSelectors_1 = require("./domSelectors");
5
5
  Object.defineProperty(exports, "ADD_ID_AS_CLASS_NAME_EXPERIMENT", { enumerable: true, get: function () { return domSelectors_1.ADD_ID_AS_CLASS_NAME_EXPERIMENT; } });
6
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; } });
7
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; } });
8
11
  Object.defineProperty(exports, "querySelectorAll", { enumerable: true, get: function () { return domSelectors_1.querySelectorAll; } });
9
12
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/dom-utils/index.ts"],"names":[],"mappings":";;;AAAA,+CAAwH;AAA/G,+HAAA,+BAA+B,OAAA;AAAE,uHAAA,uBAAuB,OAAA;AAAE,2GAAA,WAAW,OAAA;AAAE,gHAAA,gBAAgB,OAAA"}
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"}
@@ -27,6 +27,36 @@ export type CompLookupOptions = {
27
27
  * character other than ASCII letters, digits, `_` and `-`.
28
28
  */
29
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;
30
60
  /**
31
61
  * Finds a component's element.
32
62
  *
@@ -31,6 +31,55 @@ export function escapeIdent(value) {
31
31
  }
32
32
  /** The class selector for a component, for example `.comp-abc`. */
33
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
+ };
34
83
  /**
35
84
  * Finds a component's element.
36
85
  *
@@ -46,8 +95,10 @@ export const getByCompId = (doc, compId, options) => {
46
95
  return null;
47
96
  }
48
97
  if (options?.isClassLookupOpen !== true) {
98
+ // dom-id-usage-check-ignore-next-line -- this compatibility helper owns the legacy component-ID fallback
49
99
  return doc.getElementById(compId);
50
100
  }
101
+ // dom-id-usage-check-ignore-next-line -- this compatibility helper owns the legacy component-ID fallback
51
102
  return doc.querySelector(toClassSelector(compId)) ?? doc.getElementById(compId);
52
103
  };
53
104
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"domSelectors.js","sourceRoot":"","sources":["../../src/dom-utils/domSelectors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,6BAA6B,CAAA;AAEpE;;;;GAIG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,oCAAoC,CAAA;AAYnF;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACxC,IAAI,OAAO,GAAG,KAAK,WAAW,IAAI,OAAO,GAAG,CAAC,MAAM,KAAK,UAAU,EAAE,CAAC;QACpE,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACzB,CAAC;IACD,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;QACnB,OAAO,KAAK,CAAA;IACb,CAAC;IACD,2GAA2G;IAC3G,iEAAiE;IACjE,MAAM,kBAAkB,GAAG,KAAK,CAAC,OAAO,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAA;IACnE,OAAO,kBAAkB,CAAC,OAAO,CAAC,WAAW,EAAE,UAAU,CAAC,CAAA;AAC3D,CAAC;AAED,mEAAmE;AACnE,MAAM,eAAe,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,IAAI,WAAW,CAAC,MAAM,CAAC,EAAE,CAAA;AAErE;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAa,EAAE,MAAc,EAAE,OAA0B,EAAsB,EAAE;IAC5G,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC3C,OAAO,IAAI,CAAA;IACZ,CAAC;IACD,IAAI,OAAO,EAAE,iBAAiB,KAAK,IAAI,EAAE,CAAC;QACzC,OAAO,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;IAClC,CAAC;IACD,OAAO,GAAG,CAAC,aAAa,CAAc,eAAe,CAAC,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,cAAc,CAAC,MAAM,CAAC,CAAA;AAC7F,CAAC,CAAA;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,gCAAgC,CAAC,QAAgB;IAChE,OAAO,CACN,QAAQ;QACP,uBAAuB;SACtB,OAAO,CAAC,oBAAoB,EAAE,KAAK,CAAC;QACrC,mFAAmF;SAClF,OAAO,CAAC,mBAAmB,EAAE,eAAe,CAAC;QAC9C,qEAAqE;QACrE,oGAAoG;QACpG,oFAAoF;SACnF,OAAO,CAAC,qBAAqB,EAAE,mCAAmC,CAAC;QACpE,yDAAyD;SACxD,OAAO,CAAC,qBAAqB,EAAE,eAAe,CAAC;QAChD,qEAAqE;QACrE,gGAAgG;QAChG,2FAA2F;QAC3F,6BAA6B;SAC5B,OAAO,CAAC,qBAAqB,EAAE,mCAAmC,CAAC,CACrE,CAAA;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAa,EAAE,QAAgB,EAAE,OAA0B;IAC3F,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC/C,OAAO,EAAE,CAAA;IACV,CAAC;IACD,IAAI,OAAO,EAAE,iBAAiB,KAAK,IAAI,EAAE,CAAC;QACzC,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAA;IAClD,CAAC;IACD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,gCAAgC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;IAC5F,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC,CAAA;AACjF,CAAC"}
1
+ {"version":3,"file":"domSelectors.js","sourceRoot":"","sources":["../../src/dom-utils/domSelectors.ts"],"names":[],"mappings":"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"}
@@ -1,2 +1,2 @@
1
- export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, getByCompId, querySelectorAll } from './domSelectors';
1
+ export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, canSelectByClass, getByCompId, getCompAndCopiesSelector, getCompSelector, querySelectorAll, } from './domSelectors';
2
2
  export type { CompLookupOptions } from './domSelectors';
@@ -1,2 +1,2 @@
1
- export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, getByCompId, querySelectorAll } from './domSelectors';
1
+ export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, canSelectByClass, getByCompId, getCompAndCopiesSelector, getCompSelector, querySelectorAll, } from './domSelectors';
2
2
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/dom-utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,+BAA+B,EAAE,uBAAuB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA"}
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,6 @@
1
1
  {
2
2
  "name": "@wix/viewer-core-services-utils",
3
- "version": "1.0.1",
3
+ "version": "1.0.3",
4
4
  "description": "Shared viewer-core-services utilities; dom-utils: class-first component element lookup",
5
5
  "license": "UNLICENSED",
6
6
  "files": [
@@ -27,14 +27,28 @@
27
27
  },
28
28
  "scripts": {
29
29
  "build": "tsc -b . && tsc --project tsconfig.cjs.json",
30
- "lint": "pnpm --workspace-root run lint:package --package $npm_package_name",
31
30
  "test": "vitest --run && pnpm run test-type-check",
32
31
  "test-type-check": "echo 'validating typescript in test files' && tsc --project tsconfig.test.json && echo 'Finished validating typescript in test files successfully'"
33
32
  },
33
+ "dependencies": {
34
+ "tslib": "^2.8.1"
35
+ },
34
36
  "devDependencies": {
37
+ "jsdom": "^23.0.1",
35
38
  "typescript": "~7.0.2",
36
39
  "vitest": "4.1.11"
37
40
  },
41
+ "nx": {
42
+ "targets": {
43
+ "build": {
44
+ "outputs": [
45
+ "{projectRoot}/dist/**/*",
46
+ "{projectRoot}/cjs/build/**/*",
47
+ "{projectRoot}/*.tsbuildinfo"
48
+ ]
49
+ }
50
+ }
51
+ },
38
52
  "publishUnscoped": false,
39
53
  "wix": {
40
54
  "artifact": {
@@ -47,10 +61,9 @@
47
61
  },
48
62
  "validations": {
49
63
  "postBuild": [
50
- "test",
51
- "lint"
64
+ "test"
52
65
  ]
53
66
  }
54
67
  },
55
- "falconPackageHash": "55e2e41273e42975b8e5eb98f249c413a8ae12fcdfaf298775b5513a"
68
+ "falconPackageHash": "39154aa9901e021f5cc271f95818207685c704e609b649ca77e7df70"
56
69
  }
@@ -45,6 +45,62 @@ export function escapeIdent(value: string): string {
45
45
  /** The class selector for a component, for example `.comp-abc`. */
46
46
  const toClassSelector = (compId: string) => `.${escapeIdent(compId)}`
47
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
+
48
104
  /**
49
105
  * Finds a component's element.
50
106
  *
@@ -60,8 +116,10 @@ export const getByCompId = (doc: Document, compId: string, options: CompLookupOp
60
116
  return null
61
117
  }
62
118
  if (options?.isClassLookupOpen !== true) {
119
+ // dom-id-usage-check-ignore-next-line -- this compatibility helper owns the legacy component-ID fallback
63
120
  return doc.getElementById(compId)
64
121
  }
122
+ // dom-id-usage-check-ignore-next-line -- this compatibility helper owns the legacy component-ID fallback
65
123
  return doc.querySelector<HTMLElement>(toClassSelector(compId)) ?? doc.getElementById(compId)
66
124
  }
67
125
 
@@ -1,2 +1,10 @@
1
- export { ADD_ID_AS_CLASS_NAME_EXPERIMENT, CLASS_LOOKUP_EXPERIMENT, getByCompId, querySelectorAll } from './domSelectors'
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'
2
10
  export type { CompLookupOptions } from './domSelectors'