@nativele/ts-dom 0.0.0-stage → 0.2.1

package/dist/cli.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+import { d as listHtml, i as CodegenError, n as checkA11y, p as watchAll, r as CODEGEN_RULES, s as generateAll, t as A11Y_RULES } from "./a11y-DZvViTVA.mjs";
+import { c as lintUsage, n as UNUSED_MARKUP_RULES, o as formatIssue, s as lintDataFlow, t as DATA_FLOW_RULES } from "./lint-B7SIRo0c.mjs";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+// src/cli.ts
+const HELP = `ts-dom <command> [dirs...] [flags]
+
+Commands
+  gen   [dirs...]   Generate x.html.ts for every x.html, plus ts-dom-tags.ts (default dir: src)
+        --watch           keep watching and regenerate on change
+        --include=<glob>  only these templates (repeatable; relative to each dir, ** crosses folders)
+        --exclude=<glob>  leave these templates out (repeatable)
+        --whitespace=collapse   collapse whitespace in text and drop line-break-only text between tags
+  lint  [dirs...]   Check templates against the code that uses them (default dir: src)
+        --a11y            also check ARIA / accessibility (warnings)
+        --strict          exit with code 1 on warnings too (errors always do)
+        --json            print the issues as JSON instead of text
+  rules             List every rule id with its description
+
+Output format: file:line:col severity [rule-id] message. Each message says what is wrong and how to fix it.
+Exit code: 0 = clean, 1 = errors found (or warnings with --strict).
+`;
+function tsFiles(dir) {
+	return readdirSync(dir).flatMap((n) => {
+		if (n === "node_modules") return [];
+		const f = join(dir, n);
+		if (statSync(f).isDirectory()) return tsFiles(f);
+		return n.endsWith(".ts") && !n.endsWith(".d.ts") && !n.endsWith(".html.ts") && n !== "ts-dom-tags.ts" ? [f] : [];
+	});
+}
+function printRules() {
+	const groups = [
+		[
+			"gen",
+			"reported by `ts-dom gen` while analyzing a template (errors stop code generation)",
+			CODEGEN_RULES
+		],
+		[
+			"lint: unused-markup",
+			"errors from `ts-dom lint` / oxlint rule ts-dom/unused-markup",
+			UNUSED_MARKUP_RULES
+		],
+		[
+			"lint: data-flow",
+			"warnings from `ts-dom lint` / oxlint rule ts-dom/data-flow",
+			DATA_FLOW_RULES
+		],
+		[
+			"lint: a11y",
+			"warnings from `ts-dom lint --a11y` / oxlint rule ts-dom/a11y",
+			Object.fromEntries(Object.entries(A11Y_RULES).map(([k, v]) => [k, v.split(". Fix:")[0]]))
+		]
+	];
+	for (const [name, note, rules] of groups) {
+		console.log(`\n${name}: ${note}`);
+		for (const [id, desc] of Object.entries(rules)) console.log(`  ${id.padEnd(24)} ${desc}`);
+	}
+}
+const [cmd, ...args] = process.argv.slice(2);
+const flags = new Set(args.filter((a) => a.startsWith("--")));
+const globs = (name) => args.filter((a) => a.startsWith(`--${name}=`)).map((a) => a.slice(name.length + 3));
+const generate = {
+	include: globs("include"),
+	exclude: globs("exclude"),
+	whitespace: flags.has("--whitespace=collapse") ? "collapse" : "preserve"
+};
+const dirs = args.filter((a) => !a.startsWith("--"));
+if (!dirs.length) dirs.push("src");
+try {
+	if (cmd === "gen") {
+		let failed = false;
+		for (const d of dirs) try {
+			generateAll(d, generate);
+		} catch (e) {
+			if (!(e instanceof CodegenError) || !flags.has("--watch")) throw e;
+			console.error(e.message);
+			failed = true;
+		}
+		if (flags.has("--watch")) {
+			console.log(`[ts-dom] watching ${dirs.join(", ")}${failed ? " (the first generation had errors)" : ""}`);
+			watchAll(dirs, {
+				...generate,
+				onGenerate: (f) => console.log(`[ts-dom] generated ${f}`),
+				onError: (m) => console.error(m)
+			});
+			await new Promise(() => {});
+		}
+	} else if (cmd === "lint") {
+		const files = dirs.flatMap(tsFiles);
+		const issues = [...lintUsage(dirs, files), ...lintDataFlow(dirs, files)];
+		if (flags.has("--a11y")) for (const dir of dirs) for (const f of listHtml(dir)) for (const d of checkA11y(readFileSync(f, "utf8"))) issues.push({
+			file: relative(process.cwd(), f),
+			...d
+		});
+		issues.sort((x, y) => x.file.localeCompare(y.file) || x.line - y.line || x.col - y.col);
+		if (flags.has("--json")) console.log(JSON.stringify({ issues }, null, 2));
+		else for (const i of issues) (i.severity === "error" ? console.error : console.warn)(formatIssue(i));
+		if (issues.filter((i) => i.severity === "error").length || flags.has("--strict") && issues.length) process.exitCode = 1;
+		if (!flags.has("--json") && !issues.length) console.log("ts-dom lint: no issues");
+	} else if (cmd === "rules") printRules();
+	else {
+		console.log(HELP);
+		if (cmd && cmd !== "--help" && cmd !== "-h" && cmd !== "help") process.exitCode = 1;
+	}
+} catch (e) {
+	if (e instanceof CodegenError) {
+		console.error(e.message);
+		process.exitCode = 1;
+	} else throw e;
+}
+export {};

package/dist/holes-DTBtTZF_.mjs

@@ -0,0 +1,15 @@
+// src/lib/reserved.ts
+/** Names that would override built-in DOM members or ts-dom's own members. Shared by the runtime and codegen (must not depend on Node or the DOM). */
+const RESERVED_NAMES = new Set(`remove click focus blur append prepend before after replaceWith replaceChildren scroll scrollTo scrollBy scrollIntoView animate attachShadow closest matches contains normalize cloneNode dispatchEvent addEventListener removeEventListener getAttribute setAttribute hasAttribute removeAttribute toggleAttribute querySelector querySelectorAll insertBefore appendChild removeChild replaceChild requestFullscreen showPopover hidePopover togglePopover checkVisibility getBoundingClientRect attachInternals constructor
+   refs lists text root state props set batch render show bind on emit onCleanup connected disconnected slotchange assignedNodes connectedCallback disconnectedCallback attributeChangedCallback`.split(/\s+/));
+/** The HTML attribute name for a camelCase prop name: userName -> user-name */
+const attrNameOf = (prop) => prop.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+// src/lib/holes.ts
+/** The {{ hole }} syntax: only a single identifier is allowed, no expressions or paths. Shared by the runtime and codegen. */
+const HOLE_ANY = /\{\{([\s\S]*?)\}\}/g;
+const IDENT = /^[A-Za-z_$][\w$]*$/;
+function holeName(inner) {
+	const s = inner.trim();
+	return IDENT.test(s) ? s : null;
+}
+export { attrNameOf as a, RESERVED_NAMES as i, IDENT as n, holeName as r, HOLE_ANY as t };

package/dist/index.d.mts

@@ -0,0 +1,242 @@
+type TextValue = string | number | boolean | null | undefined;
+interface ListSchema {
+  refs: Record<string, Element>;
+  text: string;
+  ifs: string;
+}
+type TextOf<N extends string> = { [K in N]: TextValue; };
+/** The per-item context passed to update(). */
+interface ItemContext<L extends ListSchema> {
+  readonly el: Element;
+  readonly refs: L["refs"];
+  readonly text: TextOf<L["text"]>;
+  /** Maps to a data-if inside the item */
+  show(name: L["ifs"], on: boolean): void;
+}
+type Update<L extends ListSchema, T> = (item: T, ctx: ItemContext<L>) => void;
+interface ReplaceOptions {
+  /**
+   * Skip update() when the item is the same reference as last time. Default: false.
+   * Only safe when you use immutable updates (a new object for every change); if you mutate objects in place the view keeps showing the old values.
+   */
+  skipUnchanged?: boolean;
+}
+/**
+ * A one-dimensional keyed list. Reordering uses `moveBefore` where the browser has it, so a moved item (a component, a playing video, a focused input) is not disconnected. It only compares keys, never subtrees;
+ * the content of an item is written explicitly by the user's update callback.
+ */
+export declare class List<L extends ListSchema = ListSchema> {
+  #private;
+  private readonly anchor;
+  private readonly proto;
+  /** Called when a new item is created (the component uses it to register data-on-* inside the item) */
+  private readonly onCreate?;
+  constructor(anchor: Comment, proto: Element,
+  /** Called when a new item is created (the component uses it to register data-on-* inside the item) */
+  onCreate?: ((el: Element) => void) | undefined);
+  /** From any node inside an item, find the key and data of the item it belongs to (used by event handlers). */
+  itemOf(node: Node | null): {
+    key: PropertyKey;
+    item: unknown;
+  } | undefined;
+  get size(): number;
+  has(key: PropertyKey): boolean;
+  get(key: PropertyKey): ItemContext<L> | undefined;
+  /** Add or update a single item; a new item is appended at the end. */
+  upsert<T>(key: PropertyKey, item: T, update: Update<L, T>): void;
+  remove(key: PropertyKey): boolean;
+  clear(): void;
+  /** Keyed reconciliation: remove extra items, create missing ones, reorder, and call update() for every item. */
+  replace<T>(items: readonly T[], key: (item: T) => PropertyKey, update: Update<L, T>, opts?: ReplaceOptions): void;
+}
+/** What `bind` needs from a store: the current value and a subscription. A read-only source can be bound too. */
+type ReadableStore<T> = Pick<Store<T>, "get" | "subscribe">;
+interface Store<T> {
+  get(): T;
+  set(next: T | ((prev: T) => T)): void;
+  subscribe(fn: (value: T) => void): () => void;
+}
+/** A tiny store: no dependency tracking, only get / set / subscribe. */
+export declare function createStore<T>(initial: T): Store<T>;
+/** The description of a template's structure, produced by codegen. */
+interface Schema {
+  refs: Record<string, Element>;
+  lists: Record<string, ListSchema>;
+  /** Names of the {{ hole }}s */
+  text: string;
+  /** Method names referenced by data-on-* */
+  events: string;
+  ifs: string;
+  slots: string;
+}
+/**
+ * A template's parsed markup, written by codegen: a string is a text node, `["#comment", text]` a comment,
+ * and `[tag, attributes, children, namespace?]` an element (a `<template>` element's children become its content).
+ */
+type TemplateNode = string | readonly [tag: string, attrs: Readonly<Record<string, string>>, children: readonly TemplateNode[], ns?: string] | readonly ["#comment", string];
+/** A template built without a component: the nodes, and the typed handles to the places the template names. */
+interface TemplateInstance<S extends Schema> {
+  /** The built nodes; insert it (or its children) where it should show. */
+  readonly root: DocumentFragment;
+  /** The elements marked with `data-ref`. */
+  readonly refs: S["refs"];
+  /** The `data-each` lists. */
+  readonly lists: { [K in keyof S["lists"]]: List<S["lists"][K]>; };
+  /** The `{{ name }}` holes: assigning a value updates every place the hole appears. */
+  readonly text: TextOf<S["text"]>;
+  /** Shows or hides the `data-if` elements of that name; hidden until shown. */
+  show(name: S["ifs"], on: boolean): void;
+}
+interface Template<S extends Schema = Schema> {
+  /** Builds a fresh copy of the markup with DOM calls only, so no HTML string is parsed and Trusted Types has nothing to block. */
+  build(): DocumentFragment;
+  /**
+   * Builds the template and wires up `refs`, `lists`, `text` and `show` without a component or custom element, e.g. for a menu item created in code.
+   * There is no host element, so `data-on-*` attributes do nothing here (listen on `refs`), and `<slot>` is not projected.
+   */
+  instantiate(): TemplateInstance<S>;
+  /** Type inference only; does not exist at runtime. */
+  readonly __schema?: S;
+}
+type El<K extends string> = K extends keyof HTMLElementTagNameMap ? HTMLElementTagNameMap[K] : HTMLElement;
+export declare function template<S extends Schema = Schema>(nodes: readonly TemplateNode[]): Template<S>;
+interface ComponentOptions {
+  /**
+   * Default false: render into the element itself (Light DOM); <slot> content is moved by the library at creation time.
+   * true: use Shadow DOM: styles are isolated and <slot> is the browser's native behavior.
+   */
+  shadow?: boolean;
+}
+/** Event declaration: put `event<DetailType>()` in the `emits` option; the type is only used to check emit() and receivers. */
+interface EventDecl<T = void> {
+  /** Default false: the event only reaches the child's own tag, so the handler is always written on `<child data-on-xxx>` in the parent's HTML. */
+  readonly bubbles?: boolean;
+  /** Type inference only; does not exist at runtime. */
+  readonly "~detail"?: T;
+}
+export declare function event<T = void>(opts?: {
+  bubbles?: boolean;
+}): EventDecl<T>;
+type DetailOf<D> = D extends EventDecl<infer T> ? T : never;
+type EmitArgs<D> = [DetailOf<D>] extends [void] ? [detail?: undefined] : [detail: DetailOf<D>];
+/** The data passed to render(): state, props and derived values merged. */
+type View<D, R> = Readonly<D> & Readonly<R>;
+interface DataOptions<St extends object, P extends object, R, E extends Record<string, EventDecl<unknown>>> extends ComponentOptions {
+  /** Data owned by the component and changed only through set(). Fields named like a {{ hole }} or data-if in the HTML bind automatically. */
+  state?: St;
+  /**
+   * Data provided by the parent (read-only): the parent sets it with an HTML attribute (`user-name="Ada"`) or a JS property (`el.userName = "Ada"`).
+   * The default value decides the type and how attributes are converted (string / number / boolean); arrays and objects can only be passed as JS properties.
+   * A component must not modify its props; use emit() to notify the parent.
+   */
+  props?: P;
+  /**
+   * Derived values: computed from state and props, usable directly by {{ holes }}, data-if and render().
+   * Recomputed after every data change (there is no dependency tracking).
+   */
+  derive?: { [K in keyof R]: (s: Readonly<St & P>) => R[K]; };
+  /** The events this component emits. */
+  emits?: E;
+}
+type Keys<St, P, R> = (keyof St | keyof P | keyof R) & string;
+type MissingBindings<S extends Schema, St, P, R> = Exclude<S["text"] | S["ifs"], Keys<St, P, R>>;
+type Conflicts<St, P, R> = (keyof St & keyof P) | (keyof St & keyof R) | (keyof P & keyof R);
+type ReservedProps<P> = Extract<keyof P, keyof HTMLElement | "refs" | "lists" | "text" | "root" | "state" | "props" | "set" | "batch" | "render" | "show" | "bind" | "on" | "emit">;
+type NativeEmits<E> = Extract<keyof E, keyof HTMLElementEventMap>;
+type Problems<S extends Schema, St, P, R, E> = ([keyof St | keyof P | keyof R] extends [never] ? unknown : [MissingBindings<S, St, P, R>] extends [never] ? unknown : {
+  missingStateKeys: MissingBindings<S, St, P, R>;
+}) & ([Conflicts<St, P, R>] extends [never] ? unknown : {
+  conflictingKeys: Conflicts<St, P, R>;
+}) & ([ReservedProps<P>] extends [never] ? unknown : {
+  reservedPropNames: ReservedProps<P>;
+}) & ([NativeEmits<E>] extends [never] ? unknown : {
+  nativeEventNames: NativeEmits<E>;
+});
+type IsClean<T> = unknown extends T ? true : false;
+type Lists<S extends Schema> = { [K in keyof S["lists"]]: List<S["lists"][K]>; };
+/** The second argument received by a data-on-* handler method. */
+interface EventHit<Item = unknown> {
+  /** The element that carries the data-on-* attribute */
+  readonly el: Element;
+  /** When the event happened inside a list item: the key of that item */
+  readonly key?: PropertyKey;
+  /** When the event happened inside a list item: the data last passed to update() for that item. Annotate the handler, e.g. `hit: EventHit<Todo>`, to type it. */
+  readonly item?: Item;
+}
+interface ComponentInstance<S extends Schema> extends HTMLElement {
+  /** Type inference only (define() uses it to check that data-on-* methods exist); does not exist at runtime. */
+  readonly "~events"?: S["events"];
+  readonly refs: S["refs"];
+  readonly lists: Lists<S>;
+  /** Maps to {{ name }}: assigning a value updates every place the hole appears. */
+  readonly text: TextOf<S["text"]>;
+  readonly root: ShadowRoot | HTMLElement;
+  /** Maps to data-if: hidden by default (removed from the DOM and replaced by a comment); shown when true. */
+  show(name: S["ifs"], on: boolean): void;
+  /** Subscribe to a store: calls fn immediately once, and unsubscribes automatically when the element is removed. */
+  bind<T>(store: ReadableStore<T>, fn: (value: T) => void): void;
+  /** Add an event listener that is removed automatically when the element is removed. Returns a function to remove it manually. */
+  on<K extends keyof HTMLElementEventMap>(target: HTMLElement, type: K, fn: (e: HTMLElementEventMap[K]) => void, opts?: AddEventListenerOptions): () => void;
+  on(target: EventTarget, type: string, fn: (e: Event) => void, opts?: AddEventListenerOptions): () => void;
+  /** Register a cleanup function that runs when the element is removed. */
+  onCleanup(fn: () => void): void;
+  /** The nodes currently assigned to the slot (fallback content excluded). In Shadow mode this is the native `slot.assignedNodes()`. */
+  assignedNodes(name: S["slots"]): Node[];
+  connected(): void;
+  disconnected(): void;
+  /** Light mode: called when slot content changes after creation (the initial assignment does not trigger it). */
+  slotchange(name: S["slots"]): void;
+}
+/** Members added when the `state` / `props` / `derive` / `emits` options are used. */
+interface StatefulInstance<S extends Schema, St extends object, P extends object, R, E extends Record<string, EventDecl<unknown>>> extends ComponentInstance<S> {
+  /** The component's own data (read-only). Use set() to change it. */
+  readonly state: Readonly<St>;
+  /** Data provided by the parent (read-only). Do not assign it inside the component; use emit() to notify the parent. */
+  readonly props: Readonly<P>;
+  /**
+   * The only way to change state: shallow-merges the patch, and does nothing when no field actually changed.
+   * When something changed it synchronously updates the same-named {{ holes }} and data-if, then calls render(). It cannot change props.
+   */
+  set(patch: Partial<St> | ((s: Readonly<St>) => Partial<St>)): void;
+  /** Coalesce several set() calls and prop changes: the view is updated and render() is called once, after fn returns. */
+  batch(fn: () => void): void;
+  /**
+   * Override it to handle updates that automatic binding cannot do (lists, attributes, focus, ...).
+   * `view` is state, props and derived values merged; `changed` holds the fields that changed (all of them on the first render).
+   */
+  render(view: View<St & P, R>, changed: ReadonlySet<keyof St | keyof P>): void;
+  /** Emit an event declared in `emits` (it does not bubble by default and only reaches this element itself). */
+  emit<K extends keyof E & string>(name: K, ...detail: EmitArgs<E[K]>): void;
+  /** Type inference only (EmitEvent uses it to get the detail type of an event); does not exist at runtime. */
+  readonly "~emits"?: { [K in keyof E]: DetailOf<E[K]>; };
+}
+/** The type of an event emitted by a component: `EmitEvent<FormField, "change-value">` is `CustomEvent<{ value: string }>`. */
+type EmitEvent<I, N extends string> = I extends {
+  readonly "~emits"?: infer M;
+} ? N extends keyof NonNullable<M> ? CustomEvent<NonNullable<M>[N]> : never : never;
+export declare function Component<S extends Schema>(tpl: Template<S>, opts?: ComponentOptions & {
+  state?: never;
+  props?: never;
+  derive?: never;
+  emits?: never;
+}): new () => ComponentInstance<S>;
+/**
+ * With the `state` / `props` / `derive` / `emits` options, {{ holes }} and data-if in the HTML bind to same-named data.
+ * When something is wrong the return type becomes an object type describing the problem, so
+ * `class X extends Component(...)` fails in tsc and lists the names:
+ * `missingStateKeys` (the HTML uses a name that does not exist), `conflictingKeys` (state / props / derive share a name),
+ * `reservedPropNames` (a prop shares a name with HTMLElement or a ts-dom member), `nativeEventNames` (emits shares a name with a native event).
+ * (The check lives in the return type, not in the parameter: in the parameter it prevents TypeScript from inferring the type of derive.)
+ */
+export declare function Component<S extends Schema, St extends object = Record<never, never>, P extends object = Record<never, never>, R = Record<never, never>, E extends Record<string, EventDecl<unknown>> = Record<never, never>>(tpl: Template<S>, opts: DataOptions<St, P, R, E>): IsClean<Problems<S, St, P, R, E>> extends true ? new () => StatefulInstance<S, St, P, R, E> & P : Problems<S, St, P, R, E>;
+type CheckHandlers<I> = I extends {
+  readonly "~events"?: infer E;
+} ? [Exclude<NonNullable<E>, keyof I>] extends [never] ? unknown : {
+  missingHandlers: Exclude<NonNullable<E>, keyof I>;
+} : unknown;
+/**
+ * Register a custom element. Also checks types: every method name referenced by data-on-* in the HTML must exist on the
+ * component as a public method, otherwise tsc reports an error that lists the missing names (`missingHandlers`).
+ */
+export declare function define<C extends abstract new (...args: never[]) => HTMLElement>(name: string, ctor: C & CheckHandlers<InstanceType<C>>): void;
+export type { ComponentInstance, ComponentOptions, DataOptions, El, EmitEvent, EventDecl, EventHit, ItemContext, ListSchema, ReadableStore, ReplaceOptions, Schema, StatefulInstance, Store, Template, TemplateInstance, TextOf, TextValue, Update, View };