id-dom 0.0.4 → 0.0.6

package/dist/types/id-dom.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Typed lookup by ID.
+ *
+ * @template {Element} T
+ * @param {string} id
+ * @param {{ new (...args: any[]): T }} Type
+ * @param {DomConfig} [config]
+ * @returns {T | null}
+ */
+export function byId<T extends Element>(id: string, Type: {
+    new (...args: any[]): T;
+}, config?: DomConfig): T | null;
+export namespace byId {
+    /**
+     * Optional typed lookup: always returns T | null.
+     *
+     * @template {Element} T
+     * @param {string} id
+     * @param {{ new (...args: any[]): T }} Type
+     * @param {DomConfig} [config]
+     * @returns {T | null}
+     */
+    export function optional<T extends Element>(id: string, Type: {
+        new (...args: any[]): T;
+    }, config?: DomConfig): T | null;
+    import opt = optional;
+    export { opt };
+}
+/**
+ * Tag-name lookup by element tag.
+ * Useful when constructor checks are not the right fit.
+ *
+ * @param {string} id
+ * @param {string} tagName
+ * @param {DomConfig} [config]
+ * @returns {Element | null}
+ */
+export function tag(id: string, tagName: string, config?: DomConfig): Element | null;
+export namespace tag {
+    /**
+     * Optional tag lookup: always returns Element | null.
+     *
+     * @param {string} id
+     * @param {string} tagName
+     * @param {DomConfig} [config]
+     * @returns {Element | null}
+     */
+    export function optional(id: string, tagName: string, config?: DomConfig): Element | null;
+    import opt_1 = optional;
+    export { opt_1 as opt };
+}
+/**
+ * Factory: scope getters to a specific root + default policy.
+ *
+ * @param {any} root
+ * @param {Omit<DomConfig, 'root'>} [config]
+ * @returns {DomApi}
+ */
+export function createDom(root: any, config?: Omit<DomConfig, "root">): DomApi;
+/** @type {TypedHelper<HTMLElement>} */
+export const el: TypedHelper<HTMLElement>;
+/** @type {TypedHelper<HTMLInputElement>} */
+export const input: TypedHelper<HTMLInputElement>;
+/** @type {TypedHelper<HTMLButtonElement>} */
+export const button: TypedHelper<HTMLButtonElement>;
+/** @type {TypedHelper<HTMLTextAreaElement>} */
+export const textarea: TypedHelper<HTMLTextAreaElement>;
+/** @type {TypedHelper<HTMLSelectElement>} */
+export const select: TypedHelper<HTMLSelectElement>;
+/** @type {TypedHelper<HTMLFormElement>} */
+export const form: TypedHelper<HTMLFormElement>;
+/** @type {TypedHelper<HTMLDivElement>} */
+export const div: TypedHelper<HTMLDivElement>;
+/** @type {TypedHelper<HTMLSpanElement>} */
+export const span: TypedHelper<HTMLSpanElement>;
+/** @type {TypedHelper<HTMLLabelElement>} */
+export const label: TypedHelper<HTMLLabelElement>;
+/** @type {TypedHelper<HTMLCanvasElement>} */
+export const canvas: TypedHelper<HTMLCanvasElement>;
+/** @type {TypedHelper<HTMLTemplateElement>} */
+export const template: TypedHelper<HTMLTemplateElement>;
+/** @type {TypedHelper<SVGSVGElement>} */
+export const svg: TypedHelper<SVGSVGElement>;
+/** @type {TypedHelper<HTMLBodyElement>} */
+export const body: TypedHelper<HTMLBodyElement>;
+/** @type {TypedHelper<HTMLElement>} */
+export const main: TypedHelper<HTMLElement>;
+/** @type {TypedHelper<HTMLElement>} */
+export const section: TypedHelper<HTMLElement>;
+/** @type {TypedHelper<HTMLElement>} */
+export const small: TypedHelper<HTMLElement>;
+export default dom;
+export type DomMode = "throw" | "null";
+export type DomConfig = {
+    mode?: DomMode;
+    warn?: boolean;
+    onError?: (error: Error, ctx: any) => void;
+    root?: any;
+};
+/**
+ * The callable shape exposed by every typed helper (`input`, `button`, …)
+ * and tag helper (`main`, `section`, …). The base call follows the helper's
+ * default `mode` (typically `'throw'`); `.optional`/`.opt` always return `T | null`.
+ */
+export type TypedHelper<T> = ((id: string) => T) & {
+    optional: (id: string) => T | null;
+    opt: (id: string) => T | null;
+};
+/**
+ * Aggregate API returned by {@link createDom}. Mirrors the named exports
+ * but is scoped to the configured root.
+ *
+ * SSR behavior (0.0.6+): typed-element helpers are *always callable*.
+ * In a non-DOM environment where the corresponding global constructor
+ * is undefined (Node without jsdom, edge runtimes), the base call
+ * throws a clear "DOM required" error and `.optional` / `.opt` return
+ * `null`. This matches the throw / null semantics consumers already
+ * expect from the browser path.
+ */
+export type DomApi = {
+    byId: (<T extends Element>(id: string, Type: {
+        new (...args: any[]): T;
+    }) => T) & {
+        optional: <T extends Element>(id: string, Type: {
+            new (...args: any[]): T;
+        }) => T | null;
+        opt: <T extends Element>(id: string, Type: {
+            new (...args: any[]): T;
+        }) => T | null;
+    };
+    tag: ((id: string, tagName: string) => Element) & {
+        optional: (id: string, tagName: string) => Element | null;
+        opt: (id: string, tagName: string) => Element | null;
+    };
+    el: TypedHelper<HTMLElement>;
+    input: TypedHelper<HTMLInputElement>;
+    button: TypedHelper<HTMLButtonElement>;
+    textarea: TypedHelper<HTMLTextAreaElement>;
+    select: TypedHelper<HTMLSelectElement>;
+    form: TypedHelper<HTMLFormElement>;
+    div: TypedHelper<HTMLDivElement>;
+    span: TypedHelper<HTMLSpanElement>;
+    label: TypedHelper<HTMLLabelElement>;
+    canvas: TypedHelper<HTMLCanvasElement>;
+    template: TypedHelper<HTMLTemplateElement>;
+    svg: TypedHelper<SVGSVGElement>;
+    body: TypedHelper<HTMLBodyElement>;
+    main: TypedHelper<HTMLElement>;
+    section: TypedHelper<HTMLElement>;
+    small: TypedHelper<HTMLElement>;
+};
+declare const dom: DomApi;

package/package.json

@@ -1,19 +1,22 @@
 {
   "name": "id-dom",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "Deterministic DOM element getters by ID (typed, tiny, modern).",
-  "author": "DR.WATT",
+  "author": "WATT3D <WATT3D@protonmail.com>",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
+  "types": "./dist/types/id-dom.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/types/id-dom.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs",
       "default": "./dist/index.js"
     },
     "./min": {
+      "types": "./dist/types/id-dom.d.ts",
       "import": "./dist/index.min.js",
       "default": "./dist/index.min.js"
     }
@@ -22,7 +25,9 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "ADDITIONAL_TERMS.md",
+    "robots.txt"
   ],
   "repository": {
     "type": "git",
@@ -44,13 +49,15 @@
   ],
   "scripts": {
     "build": "node build.js",
-    "prepublishOnly": "npm run build",
+    "build:types": "tsc -p tsconfig.types.json",
+    "prepublishOnly": "npm run build && npm run build:types",
     "test": "vitest run --environment jsdom",
     "test:watch": "vitest --environment jsdom"
   },
   "devDependencies": {
     "esbuild": "^0.27.3",
     "jsdom": "^24.0.0",
+    "typescript": "^5.9.3",
     "vitest": "^3.1.2"
   },
   "engines": {

package/robots.txt

@@ -0,0 +1,79 @@
+# WATT3D — AI scraping policy
+#
+# This file enumerates known AI / LLM training and inference crawlers
+# that the WATT3D AI Training Rider does not consent to. See
+# ./ADDITIONAL_TERMS.md for the legal scope and definitions.
+#
+# Honoring robots.txt is voluntary. The rider applies whether or not
+# a bot respects this file. The enumeration is non-exhaustive — bots
+# not listed here are still bound by the rider if they perform
+# Training Use as defined in ADDITIONAL_TERMS.md §1.
+
+User-agent: GPTBot
+Disallow: /
+
+User-agent: ChatGPT-User
+Disallow: /
+
+User-agent: OAI-SearchBot
+Disallow: /
+
+User-agent: anthropic-ai
+Disallow: /
+
+User-agent: ClaudeBot
+Disallow: /
+
+User-agent: Claude-Web
+Disallow: /
+
+User-agent: Claude-SearchBot
+Disallow: /
+
+User-agent: Google-Extended
+Disallow: /
+
+User-agent: Applebot-Extended
+Disallow: /
+
+User-agent: Meta-ExternalAgent
+Disallow: /
+
+User-agent: Meta-ExternalFetcher
+Disallow: /
+
+User-agent: FacebookBot
+Disallow: /
+
+User-agent: CCBot
+Disallow: /
+
+User-agent: PerplexityBot
+Disallow: /
+
+User-agent: Perplexity-User
+Disallow: /
+
+User-agent: cohere-ai
+Disallow: /
+
+User-agent: Bytespider
+Disallow: /
+
+User-agent: Amazonbot
+Disallow: /
+
+User-agent: Omgilibot
+Disallow: /
+
+User-agent: AI2Bot
+Disallow: /
+
+User-agent: Diffbot
+Disallow: /
+
+# Everyone else: full access. Search engines and human-driven crawlers
+# remain welcome.
+
+User-agent: *
+Allow: /