@conducivemammal/element-refs 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -51,7 +51,7 @@ if (root) {
51
51
  | `refs` | Descendants with `data-ref` and no `data-ref-for`. Pass the element that bounds your component. The lookup includes ordinary nested markup without inferring component boundaries. |
52
52
  | `refs.external` | Elements with `data-ref` whose `data-ref-for` exactly matches the root's current ID. The search defaults to the root's owner document. Set `options.externalRoot` to a document, element or fragment (including a shadow root) to change the search boundary. |
53
53
 
54
- Both scopes have `one(name)`, which returns the first match in DOM order or `null`, and `all(name)`, which returns an array in DOM order or an empty array. Names and IDs are case-sensitive. Use unique IDs within the external search scope. A root without an ID has no external matches.
54
+ Both scopes have `one(dataRefName)`, which returns the first match in DOM order or `null`, and `all(dataRefName)`, which returns an array in DOM order or an empty array. Pass the exact `data-ref` value, such as `refs.all('item')` for `data-ref="item"`. Omitting the argument or passing a value other than a string throws a `TypeError`. Names and IDs are case-sensitive. Use unique IDs within the external search scope. A root without an ID has no external matches.
55
55
 
56
56
  Lookups use the current DOM on each call. An array returned earlier is a snapshot, and listeners added to an element stay on that element. For controls that are frequently replaced, use event delegation or bind again after replacement. DOM searches stay within their search tree. To search the contents of a shadow root for external refs, explicitly use it as `externalRoot`.
57
57
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@conducivemammal/element-refs",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Find named DOM elements inside or outside a component.",
5
5
  "type": "module",
6
6
  "main": "./src/index.js",
package/src/index.js CHANGED
@@ -2,8 +2,8 @@
2
2
  * Look up elements by their exact, case-sensitive `data-ref` value.
3
3
  *
4
4
  * @typedef {object} RefLookup
5
- * @property {(name: string) => Element | null} one - The first match in DOM order, or null.
6
- * @property {(name: string) => Element[]} all - All matches in DOM order, as a snapshot.
5
+ * @property {(dataRefName: string) => Element | null} one - Pass a `data-ref` value, for example `one('panel')`. Returns the first match in DOM order, or null.
6
+ * @property {(dataRefName: string) => Element[]} all - Pass a `data-ref` value, for example `all('item')`. Returns a snapshot of all matches in DOM order.
7
7
  */
8
8
 
9
9
  /**
@@ -49,16 +49,30 @@ export function createRefs(root, { externalRoot } = {}) {
49
49
  */
50
50
  function createLookup(query, matches) {
51
51
  return {
52
- one(name) {
52
+ one(dataRefName) {
53
+ validateRefName('one', dataRefName)
53
54
  const elements = query()
54
55
  for (let index = 0; index < elements.length; index += 1) {
55
56
  const element = elements[index]
56
- if (matches(element, name)) return element
57
+ if (matches(element, dataRefName)) return element
57
58
  }
58
59
  return null
59
60
  },
60
- all(name) {
61
- return Array.from(query()).filter((element) => matches(element, name))
61
+ all(dataRefName) {
62
+ validateRefName('all', dataRefName)
63
+ return Array.from(query()).filter((element) => matches(element, dataRefName))
62
64
  },
63
65
  }
64
66
  }
67
+
68
+ /**
69
+ * @param {'one' | 'all'} method
70
+ * @param {unknown} dataRefName
71
+ */
72
+ function validateRefName(method, dataRefName) {
73
+ if (typeof dataRefName !== 'string') {
74
+ throw new TypeError(
75
+ `element-refs: ${method}() requires a string argument. Pass the data-ref value, for example ${method}('item').`,
76
+ )
77
+ }
78
+ }
package/types/index.d.ts CHANGED
@@ -2,8 +2,8 @@
2
2
  * Look up elements by their exact, case-sensitive `data-ref` value.
3
3
  *
4
4
  * @typedef {object} RefLookup
5
- * @property {(name: string) => Element | null} one - The first match in DOM order, or null.
6
- * @property {(name: string) => Element[]} all - All matches in DOM order, as a snapshot.
5
+ * @property {(dataRefName: string) => Element | null} one - Pass a `data-ref` value, for example `one('panel')`. Returns the first match in DOM order, or null.
6
+ * @property {(dataRefName: string) => Element[]} all - Pass a `data-ref` value, for example `all('item')`. Returns a snapshot of all matches in DOM order.
7
7
  */
8
8
  /**
9
9
  * @typedef {RefLookup & { external: RefLookup }} ElementRefs
@@ -29,13 +29,13 @@ export function createRefs(root: Element, { externalRoot }?: RefOptions): Elemen
29
29
  */
30
30
  export type RefLookup = {
31
31
  /**
32
- * - The first match in DOM order, or null.
32
+ * - Pass a `data-ref` value, for example `one('panel')`. Returns the first match in DOM order, or null.
33
33
  */
34
- one: (name: string) => Element | null;
34
+ one: (dataRefName: string) => Element | null;
35
35
  /**
36
- * - All matches in DOM order, as a snapshot.
36
+ * - Pass a `data-ref` value, for example `all('item')`. Returns a snapshot of all matches in DOM order.
37
37
  */
38
- all: (name: string) => Element[];
38
+ all: (dataRefName: string) => Element[];
39
39
  };
40
40
  export type ElementRefs = RefLookup & {
41
41
  external: RefLookup;