@conducivemammal/element-refs 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,66 @@
1
- # Temporary Holding Version
1
+ # @conducivemammal/element-refs
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 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(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.
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.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
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,64 @@
1
+ /**
2
+ * Look up elements by their exact, case-sensitive `data-ref` value.
3
+ *
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.
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(name) {
53
+ const elements = query()
54
+ for (let index = 0; index < elements.length; index += 1) {
55
+ const element = elements[index]
56
+ if (matches(element, name)) return element
57
+ }
58
+ return null
59
+ },
60
+ all(name) {
61
+ return Array.from(query()).filter((element) => matches(element, name))
62
+ },
63
+ }
64
+ }
@@ -0,0 +1,48 @@
1
+ /**
2
+ * Look up elements by their exact, case-sensitive `data-ref` value.
3
+ *
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.
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
+ * - The first match in DOM order, or null.
33
+ */
34
+ one: (name: string) => Element | null;
35
+ /**
36
+ * - All matches in DOM order, as a snapshot.
37
+ */
38
+ all: (name: 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
+ };