id-dom 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,296 @@
+# id-dom
+
+[![npm version](https://img.shields.io/npm/v/id-dom.svg)](https://www.npmjs.com/package/id-dom)
+[![npm downloads](https://img.shields.io/npm/dm/id-dom.svg)](https://www.npmjs.com/package/id-dom)
+[![GitHub stars](https://img.shields.io/github/stars/iWhatty/id-dom.svg?style=social)](https://github.com/iWhatty/id-dom)
+[![License](https://img.shields.io/github/license/iWhatty/id-dom.svg)](https://github.com/iWhatty/id-dom/blob/main/LICENSE)
+
+**Deterministic DOM element getters by ID — typed, tiny, modern.**
+
+`id-dom` is a small utility for grabbing DOM references safely **by `id`**, with predictable behavior:
+
+* **Typed getters** like `button('saveBtn')`, `input('nameInput')`, `svg('icon')`
+* **Strict or optional** mode (`throw` vs `null`)
+* **Short optional alias** via `.opt`
+* **Scoped lookups** for `document`, `ShadowRoot`, `DocumentFragment`, or an `Element`
+* **Centralized error handling** with `onError` and optional `warn`
+* **Zero deps**
+
+This is deliberately **not** a selector framework. It is a tiny, ID-first primitive for safe DOM wiring.
+
+---
+
+## Install
+
+```bash
+npm install id-dom
+```
+
+---
+
+## Quick Start
+
+```js
+import dom from 'id-dom'
+
+const saveBtn = dom.button('saveBtn')
+saveBtn.addEventListener('click', save)
+```
+
+Optional access never throws for missing or wrong-type elements:
+
+```js
+const debug = dom.div.optional('debugPanel')
+debug?.append('hello')
+
+const maybeCanvas = dom.canvas.opt('game')
+```
+
+---
+
+## Why ID-first?
+
+Using `getElementById` is:
+
+* fast
+* unambiguous
+* easy to reason about
+
+And with typed getters, you immediately know whether you got a `HTMLButtonElement`, `HTMLInputElement`, `SVGSVGElement`, and so on.
+
+When scoped roots do not support `getElementById`, `id-dom` falls back to `querySelector(#id)` and safely escapes edge-case IDs.
+
+---
+
+## API
+
+### Default export: `dom`
+
+The default export is a scoped instance using `document` (when available) with **strict** behavior:
+
+* missing element → **throws**
+* wrong type or wrong tag → **throws**
+* invalid input → **throws**
+
+```js
+import dom from 'id-dom'
+
+const name = dom.input('nameInput')
+const submit = dom.button('submitBtn')
+```
+
+---
+
+### `createDom(root, config?)`
+
+Create a scoped instance that searches within a specific root:
+
+* `document` → uses `getElementById`
+* `ShadowRoot`, `DocumentFragment`, or `Element` → uses `querySelector(#id)` fallback
+
+```js
+import { createDom } from 'id-dom'
+
+const d = createDom(document, { mode: 'null', warn: true })
+const sidebar = d.div('sidebar')
+```
+
+#### Config
+
+```ts
+type DomMode = 'throw' | 'null'
+
+{
+  mode?: DomMode
+  warn?: boolean
+  onError?: (err: Error, ctx: any) => void
+}
+```
+
+---
+
+### `byId(id, Type, config?)`
+
+Generic typed lookup:
+
+```js
+import { byId } from 'id-dom'
+
+const btn = byId('saveBtn', HTMLButtonElement)
+```
+
+Optional variants:
+
+```js
+const maybeBtn = byId.optional('saveBtn', HTMLButtonElement)
+const maybeBtn2 = byId.opt('saveBtn', HTMLButtonElement)
+```
+
+#### Behavior
+
+* valid match → returns the element
+* missing element → throws or returns `null`
+* wrong type → throws or returns `null`
+* invalid `id` → throws or returns `null`
+* invalid `Type` → throws or returns `null`
+
+---
+
+### `tag(id, tagName, config?)`
+
+Tag-based validation when constructor checks are not the right fit:
+
+```js
+import { tag } from 'id-dom'
+
+const main = tag('appMain', 'main')
+const icon = tag('icon', 'svg', { root: container })
+```
+
+Optional variants:
+
+```js
+const maybeMain = tag.optional('appMain', 'main')
+const maybeMain2 = tag.opt('appMain', 'main')
+```
+
+#### Behavior
+
+* valid tag match → returns the element
+* missing element → throws or returns `null`
+* wrong tag → throws or returns `null`
+* invalid `id` → throws or returns `null`
+* invalid `tagName` → throws or returns `null`
+
+---
+
+## Built-in Getters
+
+### Typed getters
+
+Available on `dom` and on any `createDom()` instance:
+
+* `el(id)` → `HTMLElement`
+* `input(id)` → `HTMLInputElement`
+* `button(id)` → `HTMLButtonElement`
+* `textarea(id)` → `HTMLTextAreaElement`
+* `select(id)` → `HTMLSelectElement`
+* `form(id)` → `HTMLFormElement`
+* `div(id)` → `HTMLDivElement`
+* `span(id)` → `HTMLSpanElement`
+* `label(id)` → `HTMLLabelElement`
+* `canvas(id)` → `HTMLCanvasElement`
+* `template(id)` → `HTMLTemplateElement`
+* `svg(id)` → `SVGSVGElement`
+* `body(id)` → `HTMLBodyElement`
+
+Each getter also has:
+
+```js
+dom.canvas.optional('game')
+dom.canvas.opt('game')
+```
+
+### Common tag helpers
+
+* `main(id)` → validates `<main>`
+* `section(id)` → validates `<section>`
+* `small(id)` → validates `<small>`
+
+Each also supports `.optional` and `.opt`.
+
+---
+
+## Error Handling
+
+### Throwing mode
+
+```js
+import dom from 'id-dom'
+
+dom.button('missing') // throws
+```
+
+### Null-returning mode
+
+```js
+import { createDom } from 'id-dom'
+
+const d = createDom(document, { mode: 'null' })
+d.button('missing') // null
+```
+
+### Central reporting
+
+```js
+const d = createDom(document, {
+  mode: 'null',
+  onError: (err, ctx) => {
+    // sendToSentry({ err, ctx })
+  },
+})
+```
+
+Enable console warnings too:
+
+```js
+createDom(document, { mode: 'null', warn: true })
+```
+
+---
+
+## Scoped Roots
+
+### Shadow DOM
+
+```js
+import { createDom } from 'id-dom'
+
+const host = document.querySelector('#widget')
+const shadow = host.attachShadow({ mode: 'open' })
+shadow.innerHTML = `<button id="shadowBtn">Click</button>`
+
+const d = createDom(shadow)
+const btn = d.button('shadowBtn')
+```
+
+### Element root
+
+```js
+const container = document.querySelector('#settings-panel')
+const d = createDom(container)
+const input = d.input('emailInput')
+```
+
+### SVG in scoped roots
+
+```js
+const container = document.querySelector('#icons')
+const d = createDom(container)
+const icon = d.svg('logoMark')
+```
+
+---
+
+## Notes
+
+* `el(id)` is specifically for `HTMLElement`, not every possible DOM `Element`.
+* `body(id)` looks up a `<body>` **by ID**. This library stays ID-first on purpose.
+* `tag()` can validate non-HTML tags too, such as `svg`, when used against supported scoped roots.
+
+---
+
+## Browser Support
+
+Modern browsers supporting:
+
+* `getElementById`
+* `querySelector`
+
+`CSS.escape` is used when available. A safe internal fallback is included for environments such as some jsdom builds where it may be missing.
+
+---
+
+## License
+
+See `LICENSE`.

package/dist/index.cjs

@@ -27,10 +27,22 @@ const DEFAULT_ROOT = typeof document !== "undefined" && document ? document : (
   /** @type {any} */
   null
 );
+const REASON = (
+  /** @type {const} */
+  {
+    INVALID_ID: "invalid-id",
+    INVALID_TYPE: "invalid-type",
+    INVALID_TAG: "invalid-tag",
+    MISSING: "missing",
+    WRONG_TYPE: "wrong-type",
+    WRONG_TAG: "wrong-tag"
+  }
+);
+const SAFE_ID_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+const NEEDS_START_ESCAPE_RE = /^(?:\d|-\d)/;
 function normalizeConfig(cfg) {
   return {
     mode: cfg?.mode ?? "throw",
-    // default strict
     warn: cfg?.warn ?? false,
     onError: typeof cfg?.onError === "function" ? cfg.onError : null,
     root: cfg?.root ?? DEFAULT_ROOT
@@ -42,8 +54,6 @@ function hasGetElementById(v) {
 function hasQuerySelector(v) {
   return !!v && typeof v === "object" && typeof v.querySelector === "function";
 }
-const SAFE_ID_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
-const NEEDS_START_ESCAPE_RE = /^(?:\d|-\d)/;
 function cssEscape(id) {
   const s = String(id);
   if (typeof CSS !== "undefined" && typeof CSS.escape === "function") {
@@ -59,10 +69,13 @@ function cssEscape(id) {
     cp >= 97 && cp <= 122 || // a-z
     cp === 95 || // _
     cp === 45;
-    const needsStartEscape = i === 0 && (cp >= 48 && cp <= 57 || cp === 45 && s.length > 1 && s.codePointAt(1) >= 48 && s.codePointAt(1) <= 57);
+    const next = s.codePointAt(i + 1);
+    const startsWithDigit = cp >= 48 && cp <= 57;
+    const startsWithDashDigit = cp === 45 && s.length > 1 && next >= 48 && next <= 57;
+    const needsStartEscape = i === 0 && (startsWithDigit || startsWithDashDigit);
     if (!needsStartEscape && (isAsciiSafe || cp >= 160)) {
       out += ch;
-    } else if (cp === 45 && i === 0 && s.length > 1 && s.codePointAt(1) >= 48 && s.codePointAt(1) <= 57) {
+    } else if (i === 0 && startsWithDashDigit) {
       out += "\\-";
     } else {
       out += `\\${cp.toString(16).toUpperCase()} `;
@@ -71,16 +84,32 @@ function cssEscape(id) {
   }
   return out;
 }
+function isElementNode(v) {
+  if (!v || typeof v !== "object") return false;
+  if (typeof Element !== "undefined") return v instanceof Element;
+  return (
+    /** @type {any} */
+    v.nodeType === 1
+  );
+}
 function getById(root, id) {
   if (!root) return null;
   if (hasGetElementById(root)) return root.getElementById(id);
   if (hasQuerySelector(root)) {
-    const sel = `#${cssEscape(id)}`;
-    const el = root.querySelector(sel);
-    return el instanceof HTMLElement ? el : null;
+    const el = root.querySelector(`#${cssEscape(id)}`);
+    return isElementNode(el) ? el : null;
   }
   return null;
 }
+function isValidId(v) {
+  return typeof v === "string" && v.length > 0;
+}
+function isValidTagName(v) {
+  return typeof v === "string" && v.trim().length > 0;
+}
+function isConstructor(v) {
+  return typeof v === "function";
+}
 function fmtId(id) {
   return id.startsWith("#") ? id : `#${id}`;
 }
@@ -95,54 +124,114 @@ function handleLookupError(err, ctx, cfg) {
     cfg.onError?.(err, ctx);
   } catch {
   }
-  if (cfg.warn) console.warn(err);
+  if (cfg.warn) console.warn(err, ctx);
   if (cfg.mode === "throw") throw err;
   return null;
 }
-function byId(id, Type, config) {
+function createCtx(id, root, reason, extra) {
+  return {
+    id,
+    root,
+    reason,
+    ...extra || {}
+  };
+}
+function resolveLookup(config, spec) {
   const cfg = normalizeConfig(config);
-  const el = getById(cfg.root, id);
+  const inputFailure = spec.validateInput(cfg);
+  if (inputFailure) {
+    return handleLookupError(inputFailure.err, inputFailure.ctx, cfg);
+  }
+  const el = getById(cfg.root, spec.id);
   if (!el) {
-    return handleLookupError(
-      missingElError(id, Type.name),
-      { id, Type, root: cfg.root, reason: "missing" },
-      cfg
-    );
-  }
-  if (!(el instanceof Type)) {
-    const got = el?.constructor?.name || typeof el;
-    return handleLookupError(
-      wrongTypeError(id, Type.name, got),
-      { id, Type, root: cfg.root, reason: "wrong-type", got },
-      cfg
-    );
-  }
-  return el;
+    const failure = spec.onMissing(cfg);
+    return handleLookupError(failure.err, failure.ctx, cfg);
+  }
+  if (!spec.matches(el, cfg)) {
+    const failure = spec.onMismatch(el, cfg);
+    return handleLookupError(failure.err, failure.ctx, cfg);
+  }
+  return (
+    /** @type {T} */
+    el
+  );
+}
+function byId(id, Type, config) {
+  return resolveLookup(config, {
+    id,
+    validateInput(cfg) {
+      if (!isValidId(id)) {
+        return {
+          err: new Error("id-dom: invalid id (expected non-empty string)"),
+          ctx: createCtx(String(id), cfg.root, REASON.INVALID_ID, { Type })
+        };
+      }
+      if (!isConstructor(Type)) {
+        return {
+          err: new Error(`id-dom: invalid Type for ${fmtId(id)}`),
+          ctx: createCtx(id, cfg.root, REASON.INVALID_TYPE, { Type })
+        };
+      }
+      return null;
+    },
+    onMissing(cfg) {
+      return {
+        err: missingElError(id, Type.name),
+        ctx: createCtx(id, cfg.root, REASON.MISSING, { Type })
+      };
+    },
+    matches(el) {
+      return el instanceof Type;
+    },
+    onMismatch(el, cfg) {
+      const got = el?.constructor?.name || typeof el;
+      return {
+        err: wrongTypeError(id, Type.name, got),
+        ctx: createCtx(id, cfg.root, REASON.WRONG_TYPE, { Type, got })
+      };
+    }
+  });
 }
 byId.optional = function byIdOptional(id, Type, config) {
   return byId(id, Type, { ...config, mode: "null" });
 };
 byId.opt = byId.optional;
 function tag(id, tagName, config) {
-  const cfg = normalizeConfig(config);
-  const el = getById(cfg.root, id);
-  if (!el) {
-    return handleLookupError(
-      missingElError(id, `<${tagName}>`),
-      { id, tagName, root: cfg.root, reason: "missing" },
-      cfg
-    );
-  }
-  const expected = String(tagName).toUpperCase();
-  const got = String(el.tagName || "").toUpperCase();
-  if (got !== expected) {
-    return handleLookupError(
-      wrongTypeError(id, `<${expected.toLowerCase()}>`, `<${got.toLowerCase()}>`),
-      { id, tagName, root: cfg.root, reason: "wrong-tag", got },
-      cfg
-    );
-  }
-  return el;
+  return resolveLookup(config, {
+    id,
+    validateInput(cfg) {
+      if (!isValidId(id)) {
+        return {
+          err: new Error("id-dom: invalid id (expected non-empty string)"),
+          ctx: createCtx(String(id), cfg.root, REASON.INVALID_ID, { tagName })
+        };
+      }
+      if (!isValidTagName(tagName)) {
+        return {
+          err: new Error(`id-dom: invalid tagName for ${fmtId(id)}`),
+          ctx: createCtx(id, cfg.root, REASON.INVALID_TAG, { tagName })
+        };
+      }
+      return null;
+    },
+    onMissing(cfg) {
+      return {
+        err: missingElError(id, `<${tagName}>`),
+        ctx: createCtx(id, cfg.root, REASON.MISSING, { tagName })
+      };
+    },
+    matches(el) {
+      return String(el.tagName || "").toUpperCase() === String(tagName).toUpperCase();
+    },
+    onMismatch(el, cfg) {
+      const expected = String(tagName).toUpperCase();
+      const got = String(el.tagName || "").toUpperCase();
+      return {
+        err: wrongTypeError(id, `<${expected.toLowerCase()}>`, `<${got.toLowerCase()}>`),
+        ctx: createCtx(id, cfg.root, REASON.WRONG_TAG, { tagName, got })
+      };
+    }
+  });
 }
 tag.optional = function tagOptional(id, tagName, config) {
   return tag(id, tagName, { ...config, mode: "null" });
@@ -162,7 +251,8 @@ const TYPE_HELPERS = (
     label: typeof HTMLLabelElement !== "undefined" ? HTMLLabelElement : null,
     canvas: typeof HTMLCanvasElement !== "undefined" ? HTMLCanvasElement : null,
     template: typeof HTMLTemplateElement !== "undefined" ? HTMLTemplateElement : null,
-    svg: typeof SVGSVGElement !== "undefined" ? SVGSVGElement : null
+    svg: typeof SVGSVGElement !== "undefined" ? SVGSVGElement : null,
+    body: typeof HTMLBodyElement !== "undefined" ? HTMLBodyElement : null
   }
 );
 const TAG_HELPERS = (
@@ -173,42 +263,53 @@ const TAG_HELPERS = (
     small: "small"
   }
 );
+function attachOptional(fn, optionalFn) {
+  if (typeof fn !== "function") {
+    throw new TypeError("id-dom: attachOptional expected fn to be a function");
+  }
+  if (typeof optionalFn !== "function") {
+    throw new TypeError("id-dom: attachOptional expected optionalFn to be a function");
+  }
+  fn.optional = optionalFn;
+  fn.opt = optionalFn;
+  return fn;
+}
+function makeTypedHelper(Type, base, baseNull) {
+  if (!Type) {
+    throw new TypeError("id-dom: makeTypedHelper received an invalid Type");
+  }
+  return attachOptional(
+    (id) => byId(id, Type, base),
+    (id) => byId(id, Type, baseNull)
+  );
+}
+function makeTagHelper(tagName, base, baseNull) {
+  if (!tagName) {
+    throw new TypeError("id-dom: makeTagHelper received an invalid tagName");
+  }
+  return attachOptional(
+    (id) => tag(id, tagName, base),
+    (id) => tag(id, tagName, baseNull)
+  );
+}
 function createDom(root, config) {
   const base = normalizeConfig({ ...config, root });
   const baseNull = { ...base, mode: "null" };
-  const api = {
-    // generic
-    byId: (id, Type) => byId(id, Type, base),
-    tag: (id, name) => tag(id, name, base)
-  };
+  const api = {};
+  api.byId = attachOptional(
+    (id, Type) => byId(id, Type, base),
+    (id, Type) => byId(id, Type, baseNull)
+  );
+  api.tag = attachOptional(
+    (id, name) => tag(id, name, base),
+    (id, name) => tag(id, name, baseNull)
+  );
   for (const [name, Type] of Object.entries(TYPE_HELPERS)) {
     if (!Type) continue;
-    api[name] = (id) => byId(id, Type, base);
+    api[name] = makeTypedHelper(Type, base, baseNull);
   }
   for (const [name, tagName] of Object.entries(TAG_HELPERS)) {
-    api[name] = (id) => tag(id, tagName, base);
-  }
-  api.byId.optional = (id, Type) => byId(id, Type, baseNull);
-  api.byId.opt = api.byId.optional;
-  api.tag.optional = (id, name) => tag(id, name, baseNull);
-  api.tag.opt = api.tag.optional;
-  for (const k of Object.keys(api)) {
-    const fn = api[k];
-    if (typeof fn !== "function") continue;
-    if (fn.optional) continue;
-    if (k in TAG_HELPERS) {
-      const tagName = TAG_HELPERS[k];
-      fn.optional = (id) => tag(id, tagName, baseNull);
-      fn.opt = fn.optional;
-      continue;
-    }
-    if (k in TYPE_HELPERS) {
-      const Type = TYPE_HELPERS[k];
-      if (Type) {
-        fn.optional = (id) => byId(id, Type, baseNull);
-        fn.opt = fn.optional;
-      }
-    }
+    api[name] = makeTagHelper(tagName, base, baseNull);
   }
   return api;
 }