id-dom 0.0.3 → 0.0.5

package/README.md

@@ -0,0 +1,295 @@
+# id-dom
+
+[![npm](https://img.shields.io/npm/v/id-dom)](https://www.npmjs.com/package/id-dom)
+[![downloads](https://img.shields.io/npm/dm/id-dom)](https://www.npmjs.com/package/id-dom)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/id-dom)](https://bundlephobia.com/package/id-dom)
+[![license](https://img.shields.io/npm/l/id-dom)](https://github.com/iWhatty/id-dom/blob/main/LICENSE)
+[![stars](https://img.shields.io/github/stars/iWhatty/id-dom?style=social)](https://github.com/iWhatty/id-dom)
+
+Deterministic DOM element getters by ID. Typed, tiny, modern. A small utility for grabbing DOM references safely by `id`, with predictable behavior.
+
+## Features
+
+- 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 dependencies
+
+This is deliberately **not** a selector framework. It is a tiny, ID-first primitive for safe DOM wiring.
+
+---
+
+## Install
+
+```sh
+pnpm add id-dom
+```
+
+---
+
+## Quick start
+
+Two import styles, same root, same behavior. Pick by preference:
+
+```js
+// Default-object style. Every typed helper lives under one namespace.
+import dom from 'id-dom'
+
+const saveBtn = dom.button('saveBtn')
+saveBtn.addEventListener('click', save)
+```
+
+```js
+// Named-import style, added in 0.0.5. Makes the dependency surface explicit
+// in the import declaration. Tree-shaken identically by modern bundlers
+// (esbuild, vite, rollup, webpack 5) since the package ships
+// `sideEffects: false`.
+import { button, input, div } from 'id-dom'
+
+const saveBtn = button('saveBtn')
+const email   = input('email')
+const panel   = div('mainPanel')
+```
+
+Optional access never throws for missing or wrong-type elements:
+
+```js
+const debug = dom.div.optional('debugPanel')   // default-object style
+debug?.append('hello')
+
+import { canvas } from 'id-dom'
+const maybeCanvas = canvas.opt('game')          // named style
+```
+
+---
+
+## 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 `.optional` and `.opt` variants:
+
+```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 })
+```
+
+---
+
+## Notes
+
+### Why id-first?
+
+Using `getElementById` is fast, unambiguous, and easy to reason about. 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.
+
+### Bundle-size note
+
+The shared lookup machinery (validation, CSS-escape fallback, error policy, root resolution) is the bulk of the package, roughly 1.9 KB gzipped in a modern bundler. Importing 4 helpers vs 1 vs the full default object lands in the same ballpark. The named-import style is recommended for readability and explicit-surface clarity, not for size.
+
+### 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')
+```
+
+### Misc
+
+- `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
+
+Licensed under AGPL-3.0 with WATT3D Additional Terms. See [LICENSE](./LICENSE) and [ADDITIONAL_TERMS.md](./ADDITIONAL_TERMS.md). Commercial AI/model-training use requires compliance with those terms or a separate WATT3D license. © WATT3D.

package/dist/index.cjs

@@ -17,20 +17,48 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var id_dom_exports = {};
 __export(id_dom_exports, {
+  body: () => body,
+  button: () => button,
   byId: () => byId,
+  canvas: () => canvas,
   createDom: () => createDom,
   default: () => id_dom_default,
-  tag: () => tag
+  div: () => div,
+  el: () => el,
+  form: () => form,
+  input: () => input,
+  label: () => label,
+  main: () => main,
+  section: () => section,
+  select: () => select,
+  small: () => small,
+  span: () => span,
+  svg: () => svg,
+  tag: () => tag,
+  template: () => template,
+  textarea: () => textarea
 });
 module.exports = __toCommonJS(id_dom_exports);
 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 +70,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 +85,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 +100,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 el2 = root.querySelector(`#${cssEscape(id)}`);
+    return isElementNode(el2) ? el2 : 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 +140,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);
-  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 inputFailure = spec.validateInput(cfg);
+  if (inputFailure) {
+    return handleLookupError(inputFailure.err, inputFailure.ctx, cfg);
+  }
+  const el2 = getById(cfg.root, spec.id);
+  if (!el2) {
+    const failure = spec.onMissing(cfg);
+    return handleLookupError(failure.err, failure.ctx, cfg);
+  }
+  if (!spec.matches(el2, cfg)) {
+    const failure = spec.onMismatch(el2, cfg);
+    return handleLookupError(failure.err, failure.ctx, cfg);
+  }
+  return (
+    /** @type {T} */
+    el2
+  );
+}
+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(el2) {
+      return el2 instanceof Type;
+    },
+    onMismatch(el2, cfg) {
+      const got = el2?.constructor?.name || typeof el2;
+      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(el2) {
+      return String(el2.tagName || "").toUpperCase() === String(tagName).toUpperCase();
+    },
+    onMismatch(el2, cfg) {
+      const expected = String(tagName).toUpperCase();
+      const got = String(el2.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 +267,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,45 +279,80 @@ 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;
 }
+const DEFAULT_BASE = normalizeConfig({ mode: "throw", root: DEFAULT_ROOT });
+const DEFAULT_BASE_NULL = { ...DEFAULT_BASE, mode: "null" };
+function defaultTypedHelper(Type) {
+  return Type ? makeTypedHelper(Type, DEFAULT_BASE, DEFAULT_BASE_NULL) : null;
+}
+function defaultTagHelper(tagName) {
+  return makeTagHelper(tagName, DEFAULT_BASE, DEFAULT_BASE_NULL);
+}
+const el = defaultTypedHelper(typeof HTMLElement !== "undefined" ? HTMLElement : null);
+const input = defaultTypedHelper(typeof HTMLInputElement !== "undefined" ? HTMLInputElement : null);
+const button = defaultTypedHelper(typeof HTMLButtonElement !== "undefined" ? HTMLButtonElement : null);
+const textarea = defaultTypedHelper(typeof HTMLTextAreaElement !== "undefined" ? HTMLTextAreaElement : null);
+const select = defaultTypedHelper(typeof HTMLSelectElement !== "undefined" ? HTMLSelectElement : null);
+const form = defaultTypedHelper(typeof HTMLFormElement !== "undefined" ? HTMLFormElement : null);
+const div = defaultTypedHelper(typeof HTMLDivElement !== "undefined" ? HTMLDivElement : null);
+const span = defaultTypedHelper(typeof HTMLSpanElement !== "undefined" ? HTMLSpanElement : null);
+const label = defaultTypedHelper(typeof HTMLLabelElement !== "undefined" ? HTMLLabelElement : null);
+const canvas = defaultTypedHelper(typeof HTMLCanvasElement !== "undefined" ? HTMLCanvasElement : null);
+const template = defaultTypedHelper(typeof HTMLTemplateElement !== "undefined" ? HTMLTemplateElement : null);
+const svg = defaultTypedHelper(typeof SVGSVGElement !== "undefined" ? SVGSVGElement : null);
+const body = defaultTypedHelper(typeof HTMLBodyElement !== "undefined" ? HTMLBodyElement : null);
+const main = defaultTagHelper("main");
+const section = defaultTagHelper("section");
+const small = defaultTagHelper("small");
 const dom = createDom(DEFAULT_ROOT, { mode: "throw" });
 var id_dom_default = dom;
 //# sourceMappingURL=index.cjs.map