@conducivemammal/element-refs 0.0.0-stage → 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 +65 -2
- package/package.json +41 -4
- package/src/index.js +78 -0
- package/types/index.d.ts +48 -0
package/README.md
CHANGED
|
@@ -1,3 +1,66 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @conducivemammal/element-refs
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Find named DOM elements inside a component or explicitly associated with it elsewhere on the page. A small ES module with TypeScript declarations and no runtime dependencies.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
npm install @conducivemammal/element-refs
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Usage
|
|
10
|
+
|
|
11
|
+
```html
|
|
12
|
+
<header>
|
|
13
|
+
<button type="button" data-ref="trigger" data-ref-for="size-guide">
|
|
14
|
+
Open size guide
|
|
15
|
+
</button>
|
|
16
|
+
</header>
|
|
17
|
+
|
|
18
|
+
<section id="size-guide">
|
|
19
|
+
<dialog data-ref="panel" aria-label="Size guide">
|
|
20
|
+
<p>Measurements are in centimetres.</p>
|
|
21
|
+
<form method="dialog"><button>Close</button></form>
|
|
22
|
+
</dialog>
|
|
23
|
+
</section>
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
```js
|
|
27
|
+
import { createRefs } from '@conducivemammal/element-refs'
|
|
28
|
+
|
|
29
|
+
const root = document.getElementById('size-guide')
|
|
30
|
+
|
|
31
|
+
if (root) {
|
|
32
|
+
const refs = createRefs(root)
|
|
33
|
+
|
|
34
|
+
for (const trigger of refs.external.all('trigger')) {
|
|
35
|
+
trigger.addEventListener('click', () => {
|
|
36
|
+
const panel = refs.one('panel')
|
|
37
|
+
if (panel instanceof HTMLDialogElement && !panel.open) {
|
|
38
|
+
panel.showModal()
|
|
39
|
+
}
|
|
40
|
+
})
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## API
|
|
46
|
+
|
|
47
|
+
`createRefs(root, options?)` accepts a DOM `Element` and returns two lookup scopes.
|
|
48
|
+
|
|
49
|
+
| Scope | Which elements match |
|
|
50
|
+
| --- | --- |
|
|
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
|
+
| `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
|
+
|
|
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
|
+
|
|
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
|
+
|
|
58
|
+
## Development
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
npm ci
|
|
62
|
+
npm test
|
|
63
|
+
npm run build
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Edit the JSDoc in `src/index.js` and regenerate `types/index.d.ts` when the public API changes.
|
package/package.json
CHANGED
|
@@ -1,6 +1,43 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@conducivemammal/element-refs",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.1",
|
|
4
|
+
"description": "Find named DOM elements inside or outside a component.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./src/index.js",
|
|
7
|
+
"types": "./types/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./types/index.d.ts",
|
|
11
|
+
"import": "./src/index.js"
|
|
12
|
+
}
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"src/index.js",
|
|
16
|
+
"types/index.d.ts"
|
|
17
|
+
],
|
|
18
|
+
"sideEffects": false,
|
|
19
|
+
"license": "UNLICENSED",
|
|
20
|
+
"repository": {
|
|
21
|
+
"type": "git",
|
|
22
|
+
"url": "git+https://github.com/ConduciveMammal/element-refs.git"
|
|
23
|
+
},
|
|
24
|
+
"keywords": [
|
|
25
|
+
"dom",
|
|
26
|
+
"refs",
|
|
27
|
+
"web-components",
|
|
28
|
+
"javascript"
|
|
29
|
+
],
|
|
30
|
+
"scripts": {
|
|
31
|
+
"build": "tsc -p tsconfig.json",
|
|
32
|
+
"test": "node --test",
|
|
33
|
+
"prepack": "npm run build"
|
|
34
|
+
},
|
|
35
|
+
"devDependencies": {
|
|
36
|
+
"linkedom": "0.18.15",
|
|
37
|
+
"typescript": "5.9.3"
|
|
38
|
+
},
|
|
39
|
+
"publishConfig": {
|
|
40
|
+
"access": "public",
|
|
41
|
+
"registry": "https://registry.npmjs.org/"
|
|
42
|
+
}
|
|
43
|
+
}
|
package/src/index.js
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Look up elements by their exact, case-sensitive `data-ref` value.
|
|
3
|
+
*
|
|
4
|
+
* @typedef {object} RefLookup
|
|
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
|
+
*/
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* @typedef {RefLookup & { external: RefLookup }} ElementRefs
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* @typedef {object} RefOptions
|
|
15
|
+
* @property {Document | DocumentFragment | Element} [externalRoot]
|
|
16
|
+
* Search boundary for external refs. Defaults to the host's current owner document.
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
/**
|
|
20
|
+
* Create fresh DOM lookups for local and explicitly associated elements.
|
|
21
|
+
*
|
|
22
|
+
* Local refs are descendants with `data-ref` and no `data-ref-for`.
|
|
23
|
+
* External refs have `data-ref-for` equal to the host's current, non-empty ID.
|
|
24
|
+
*
|
|
25
|
+
* @param {Element} root - The host element to scope local refs to.
|
|
26
|
+
* @param {RefOptions} [options]
|
|
27
|
+
* @returns {ElementRefs}
|
|
28
|
+
*/
|
|
29
|
+
export function createRefs(root, { externalRoot } = {}) {
|
|
30
|
+
return {
|
|
31
|
+
...createLookup(
|
|
32
|
+
() => root.querySelectorAll('[data-ref]:not([data-ref-for])'),
|
|
33
|
+
(element, name) => element.getAttribute('data-ref') === name,
|
|
34
|
+
),
|
|
35
|
+
external: createLookup(
|
|
36
|
+
() => (externalRoot ?? root.ownerDocument).querySelectorAll('[data-ref][data-ref-for]'),
|
|
37
|
+
(element, name) =>
|
|
38
|
+
root.id !== '' &&
|
|
39
|
+
element.getAttribute('data-ref-for') === root.id &&
|
|
40
|
+
element.getAttribute('data-ref') === name,
|
|
41
|
+
),
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* @param {() => NodeListOf<Element>} query
|
|
47
|
+
* @param {(element: Element, name: string) => boolean} matches
|
|
48
|
+
* @returns {RefLookup}
|
|
49
|
+
*/
|
|
50
|
+
function createLookup(query, matches) {
|
|
51
|
+
return {
|
|
52
|
+
one(dataRefName) {
|
|
53
|
+
validateRefName('one', dataRefName)
|
|
54
|
+
const elements = query()
|
|
55
|
+
for (let index = 0; index < elements.length; index += 1) {
|
|
56
|
+
const element = elements[index]
|
|
57
|
+
if (matches(element, dataRefName)) return element
|
|
58
|
+
}
|
|
59
|
+
return null
|
|
60
|
+
},
|
|
61
|
+
all(dataRefName) {
|
|
62
|
+
validateRefName('all', dataRefName)
|
|
63
|
+
return Array.from(query()).filter((element) => matches(element, dataRefName))
|
|
64
|
+
},
|
|
65
|
+
}
|
|
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
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Look up elements by their exact, case-sensitive `data-ref` value.
|
|
3
|
+
*
|
|
4
|
+
* @typedef {object} RefLookup
|
|
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
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* @typedef {RefLookup & { external: RefLookup }} ElementRefs
|
|
10
|
+
*/
|
|
11
|
+
/**
|
|
12
|
+
* @typedef {object} RefOptions
|
|
13
|
+
* @property {Document | DocumentFragment | Element} [externalRoot]
|
|
14
|
+
* Search boundary for external refs. Defaults to the host's current owner document.
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* Create fresh DOM lookups for local and explicitly associated elements.
|
|
18
|
+
*
|
|
19
|
+
* Local refs are descendants with `data-ref` and no `data-ref-for`.
|
|
20
|
+
* External refs have `data-ref-for` equal to the host's current, non-empty ID.
|
|
21
|
+
*
|
|
22
|
+
* @param {Element} root - The host element to scope local refs to.
|
|
23
|
+
* @param {RefOptions} [options]
|
|
24
|
+
* @returns {ElementRefs}
|
|
25
|
+
*/
|
|
26
|
+
export function createRefs(root: Element, { externalRoot }?: RefOptions): ElementRefs;
|
|
27
|
+
/**
|
|
28
|
+
* Look up elements by their exact, case-sensitive `data-ref` value.
|
|
29
|
+
*/
|
|
30
|
+
export type RefLookup = {
|
|
31
|
+
/**
|
|
32
|
+
* - Pass a `data-ref` value, for example `one('panel')`. Returns the first match in DOM order, or null.
|
|
33
|
+
*/
|
|
34
|
+
one: (dataRefName: string) => Element | null;
|
|
35
|
+
/**
|
|
36
|
+
* - Pass a `data-ref` value, for example `all('item')`. Returns a snapshot of all matches in DOM order.
|
|
37
|
+
*/
|
|
38
|
+
all: (dataRefName: string) => Element[];
|
|
39
|
+
};
|
|
40
|
+
export type ElementRefs = RefLookup & {
|
|
41
|
+
external: RefLookup;
|
|
42
|
+
};
|
|
43
|
+
export type RefOptions = {
|
|
44
|
+
/**
|
|
45
|
+
* Search boundary for external refs. Defaults to the host's current owner document.
|
|
46
|
+
*/
|
|
47
|
+
externalRoot?: DocumentFragment | Element | Document | undefined;
|
|
48
|
+
};
|