kerfjs 4.1.1 → 4.2.0-beta.2

package/dist/imperative.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `kerfjs/imperative` — bind a non-kerf widget's lifecycle to a single DOM node.
+ *
+ * `data-morph-skip` lets a library own a subtree so kerf won't touch it — but
+ * nothing manages that widget's LIFECYCLE. You set it up imperatively after
+ * render and must remember to tear it down when the node is replaced/removed
+ * (dropping document-level listeners the widget added, etc.). `imperative` closes
+ * that seam: it's a `useEffect`-with-cleanup bound to one node.
+ *
+ *   import { imperative } from 'kerfjs/imperative';
+ *
+ *   imperative(canvasEl, (el) => {
+ *     const chart = D3.mount(el);
+ *     return () => chart.destroy();   // runs when el leaves the DOM (or on dispose)
+ *   });
+ *
+ * `setup(node)` runs immediately and may return a teardown function. The teardown
+ * runs once — whichever comes first — when the node leaves the document (detected
+ * by a `MutationObserver`, so a morph swap, a `remountOn` replacement, or any
+ * removal triggers it) or when the returned disposer is called. Re-creation is
+ * NOT handled here: a fresh node is a fresh `imperative()` call — pair it with
+ * `kerfjs/remount`, which replaces the node and re-runs your render (and thus
+ * this call) on the new one.
+ */
+/** The setup callback for {@link imperative}: run against `node`, optionally return a teardown. */
+type ImperativeSetup = (node: Element) => (() => void) | void;
+/**
+ * Run `setup(node)` now, and its returned teardown once — when `node` leaves the
+ * document, or when the returned disposer is called, whichever is first. Returns
+ * a disposer (idempotent) so a `mount()` / `Scope` can drive teardown explicitly.
+ */
+declare function imperative(node: Element, setup: ImperativeSetup): () => void;
+
+export { type ImperativeSetup, imperative };

package/dist/imperative.js

@@ -0,0 +1,20 @@
+// src/imperative.ts
+function imperative(node, setup) {
+  const teardown = setup(node);
+  let done = false;
+  const finish = () => {
+    if (done) return;
+    done = true;
+    observer.disconnect();
+    if (typeof teardown === "function") teardown();
+  };
+  const observer = new MutationObserver(() => {
+    if (!node.isConnected) finish();
+  });
+  observer.observe(node.getRootNode(), { childList: true, subtree: true });
+  return finish;
+}
+
+export { imperative };
+//# sourceMappingURL=imperative.js.map
+//# sourceMappingURL=imperative.js.map

package/dist/imperative.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/imperative.ts"],"names":[],"mappings":";AAiCO,SAAS,UAAA,CAAW,MAAe,KAAA,EAAoC;AAC5E,EAAA,MAAM,QAAA,GAAW,MAAM,IAAI,CAAA;AAC3B,EAAA,IAAI,IAAA,GAAO,KAAA;AAEX,EAAA,MAAM,SAAS,MAAY;AACzB,IAAA,IAAI,IAAA,EAAM;AACV,IAAA,IAAA,GAAO,IAAA;AACP,IAAA,QAAA,CAAS,UAAA,EAAW;AACpB,IAAA,IAAI,OAAO,QAAA,KAAa,UAAA,EAAY,QAAA,EAAS;AAAA,EAC/C,CAAA;AAMA,EAAA,MAAM,QAAA,GAAW,IAAI,gBAAA,CAAiB,MAAM;AAC1C,IAAA,IAAI,CAAC,IAAA,CAAK,WAAA,EAAa,MAAA,EAAO;AAAA,EAChC,CAAC,CAAA;AACD,EAAA,QAAA,CAAS,OAAA,CAAQ,KAAK,WAAA,EAAY,EAAG,EAAE,SAAA,EAAW,IAAA,EAAM,OAAA,EAAS,IAAA,EAAM,CAAA;AAEvE,EAAA,OAAO,MAAA;AACT","file":"imperative.js","sourcesContent":["/**\n * `kerfjs/imperative` — bind a non-kerf widget's lifecycle to a single DOM node.\n *\n * `data-morph-skip` lets a library own a subtree so kerf won't touch it — but\n * nothing manages that widget's LIFECYCLE. You set it up imperatively after\n * render and must remember to tear it down when the node is replaced/removed\n * (dropping document-level listeners the widget added, etc.). `imperative` closes\n * that seam: it's a `useEffect`-with-cleanup bound to one node.\n *\n *   import { imperative } from 'kerfjs/imperative';\n *\n *   imperative(canvasEl, (el) => {\n *     const chart = D3.mount(el);\n *     return () => chart.destroy();   // runs when el leaves the DOM (or on dispose)\n *   });\n *\n * `setup(node)` runs immediately and may return a teardown function. The teardown\n * runs once — whichever comes first — when the node leaves the document (detected\n * by a `MutationObserver`, so a morph swap, a `remountOn` replacement, or any\n * removal triggers it) or when the returned disposer is called. Re-creation is\n * NOT handled here: a fresh node is a fresh `imperative()` call — pair it with\n * `kerfjs/remount`, which replaces the node and re-runs your render (and thus\n * this call) on the new one.\n */\n\n/** The setup callback for {@link imperative}: run against `node`, optionally return a teardown. */\nexport type ImperativeSetup = (node: Element) => (() => void) | void;\n\n/**\n * Run `setup(node)` now, and its returned teardown once — when `node` leaves the\n * document, or when the returned disposer is called, whichever is first. Returns\n * a disposer (idempotent) so a `mount()` / `Scope` can drive teardown explicitly.\n */\nexport function imperative(node: Element, setup: ImperativeSetup): () => void {\n  const teardown = setup(node);\n  let done = false;\n\n  const finish = (): void => {\n    if (done) return;\n    done = true;\n    observer.disconnect();\n    if (typeof teardown === 'function') teardown();\n  };\n\n  // Observe the node's live tree (the document when connected) with subtree, so\n  // an ANCESTOR removal — not just a direct one — is caught. Each mutation just\n  // re-checks `node.isConnected`, which is true until the node (or an ancestor)\n  // is removed, so a morph swap / remountOn replacement / manual removal all fire.\n  const observer = new MutationObserver(() => {\n    if (!node.isConnected) finish();\n  });\n  observer.observe(node.getRootNode(), { childList: true, subtree: true });\n\n  return finish;\n}\n"]}

package/dist/index.d.ts

@@ -1,6 +1,9 @@
+export { A as AttrSpec, a as attr } from './attrSelector-Cmu2ZoGO.js';
+export { D as DelegateOptions, d as delegate, a as delegateCapture } from './delegate-CL9VTZFb.js';
 import { ArraySignal } from './array-signal.js';
 import { SafeHtml } from './jsx-runtime.js';
-export { Fragment, isSafeHtml, raw } from './jsx-runtime.js';
+export { Fragment, isSafeHtml, raw, trustedRaw } from './jsx-runtime.js';
+export { M as MountResult, m as mount } from './mount-Bo2qOx25.js';
 import { Signal } from '@preact/signals-core';
 export { ReadonlySignal, Signal, batch, computed } from '@preact/signals-core';
 export { S as Store, d as defineStore, r as resetAllStores } from './testing-DNEY7wi3.js';
@@ -33,176 +36,6 @@ import './bindings-CYwoJpQb.js';
 declare function signal<T>(value?: T): Signal<T>;
 declare function effect(fn: () => void | (() => void)): () => void;
 
-/**
- * `attr(name, value)` — create a pre-computed attribute descriptor (static form).
- * `attr(name)` — create a per-render factory for dynamic attribute values (dynamic form).
- *
- * **Static form** — best for fixed action names, filter keys, role values, etc.
- * Escapes once at module-load time; produces a full {@link AttrSpec} with
- * `.name`, `.value`, `.selector`, and `.attrs`.
- *
- *   const ACTIONS = {
- *     toggle: attr('data-action', 'toggle'),
- *     remove: attr('data-action', 'remove'),
- *   } as const satisfies Record<string, AttrSpec<'data-action'>>;
- *
- *   // In JSX — spread .attrs (rename-safe; no hardcoded attribute name):
- *   <button {...ACTIONS.toggle.attrs}>Toggle</button>
- *
- *   // In delegate — use the pre-computed selector:
- *   delegate(root, 'click', ACTIONS.toggle.selector, handler);
- *
- * **Dynamic form** — best for per-row data like `data-id`, where the value
- * changes per item but the attribute name is constant.
- * The name is validated and pre-escaped at definition time; calling the
- * returned factory is cheap (it just freezes a one-key object — the value is
- * escaped later by the JSX attribute renderer when the result is spread).
- *
- *   const ITEM = { id: attr('data-id') } as const;
- *
- *   // In JSX — call the factory inline:
- *   <li {...ITEM.id(String(item.id))}>…</li>
- *
- * For ad-hoc compound selectors, concatenate `.selector` strings:
- *
- *   delegate(root, 'click',
- *     ACTIONS.toggle.selector + attr('data-id', id).selector,
- *     handler);
- *
- * Escaping:
- * - Attribute name: escaped as a CSS identifier via `cssEscapeIdent`, which is
- *   an SSR-safe (no `CSS.escape`) adaptation of the Mathias Bynens polyfill
- *   (https://github.com/mathiasbynens/CSS.escape, MIT licensed — see the
- *   Acknowledgements section of LICENSE). Handles
- *   control chars, leading digits, non-ASCII, and CSS metacharacters.
- * - Attribute value: embedded in double quotes as a CSS string. Backslashes and
- *   double-quote characters are backslash-escaped; control characters are
- *   hex-escaped per CSS Syntax Level 3 §3.4.
- *
- * Throws on an empty attribute name (not a valid CSS identifier).
- */
-/** Descriptor created by the static {@link attr} overload. */
-interface AttrSpec<N extends string = string, V extends string = string> {
-    /** The raw attribute name passed to `attr()`. */
-    readonly name: N;
-    /** The raw attribute value passed to `attr()`. */
-    readonly value: V;
-    /** Pre-computed `[name="value"]` CSS selector string, safe to pass to `delegate()`. */
-    readonly selector: string;
-    /** Spreadable JSX object — `{ [name]: value }` — keeps the attribute name out of JSX literals. */
-    readonly attrs: {
-        readonly [K in N]: V;
-    };
-}
-/**
- * Static overload — pre-computes the full descriptor at definition time.
- * Returns an {@link AttrSpec} with `.name`, `.value`, `.selector`, and `.attrs`.
- */
-declare function attr<N extends string, V extends string>(name: N, value: V): AttrSpec<N, V>;
-/**
- * Dynamic overload — pre-validates and pre-escapes the attribute name, returns a
- * factory that accepts a per-render value and produces a frozen spreadable object.
- * Use for per-row attributes like `data-id` where the value changes per item.
- * The optional `V` generic constrains which values the factory accepts:
- * `attr<'data-id', 'a'|'b'>('data-id')` → `(value: 'a'|'b') => { 'data-id': 'a'|'b' }`.
- * Leaving both generics off infers `N` from the argument and defaults `V` to `string`.
- */
-declare function attr<N extends string, V extends string = string>(name: N): (value: V) => {
-    readonly [K in N]: V;
-};
-
-/**
- * Tiny event-delegation helpers. Replace per-element `addEventListener` calls
- * (which don't survive morph re-renders for nodes the diff creates) with one
- * listener at the morph-root that dispatches via `closest()`.
- *
- * Three-tier listener model:
- *
- *   - Tier 1 (bubbling events) — use `delegate()`.
- *     click, input, change, submit, mousedown/up, keydown/up, pointerdown/up/move,
- *     drag*, drop, contextmenu, wheel, copy/paste/cut, focusin/focusout.
- *
- *     `delegate()` also auto-promotes the well-known non-bubbling event
- *     types (`focus`, `blur`, `scroll`, `load`, `error`, `mouseenter`,
- *     `mouseleave`) to the capture phase under the hood, so the call site
- *     looks identical for "interactive thing happens on a descendant"
- *     regardless of whether that event bubbles. Selector matching stays
- *     `closest()`-style — the same as for bubbling events — so a wrapper
- *     selector like `'.field-row'` still matches when the event fires on
- *     a descendant `<input>`.
- *
- *   - Tier 2 (explicit capture) — use `delegateCapture()`.
- *     The escape hatch for cases the auto-promotion list doesn't cover
- *     (custom non-bubbling events) or when you want capture-phase
- *     interception. Selector matching is `closest()`-style by default —
- *     the same walk-up as `delegate()`, and it passes the matched ancestor
- *     (not the raw target) to the handler — so a click on any descendant of
- *     the selected element climbs to it. Pass `{ match: 'direct' }` to opt
- *     into strict `matches()`-style matching (fire only when the event lands
- *     on the exact element the selector identifies).
- *
- *   - Tier 3 (per-element instances / library-owned subtrees) — mark the
- *     host element with `data-morph-skip` and manage the library's
- *     lifecycle directly. No delegation helper applies.
- */
-/**
- * How the selector is matched against the event's target:
- *
- *   - `'closest'` (the default for both helpers) — walk UP from `event.target`
- *     via `closest(selector)`, firing for the nearest matching ancestor inside
- *     `rootEl`. This is the delegation behavior you almost always want: a click
- *     on an icon inside a button fires the button's handler.
- *   - `'direct'` — strict `matches()` match: fire only when `event.target`
- *     itself matches the selector, with no walk-up.
- */
-interface DelegateOptions {
-    match?: 'closest' | 'direct';
-}
-/**
- * Delegation that "just works" for both bubbling and the common non-bubbling
- * events. Installs ONE listener on `rootEl`; for known non-bubblers (see
- * `NON_BUBBLING` above) the listener is registered on the capture phase so
- * it actually reaches the target, otherwise on the bubble phase. Either way,
- * matching walks up from `event.target` via `closest(selector)` and fires
- * `handler(event, matched)` if the match is inside `rootEl`.
- *
- * Pass `{ match: 'direct' }` to fire only when `event.target` itself matches
- * the selector (no walk-up); the default is `'closest'`.
- *
- * The generic `T` narrows the second handler argument to the expected element
- * type — `delegate<HTMLButtonElement>(root, 'click', 'button', (e, btn) => btn.value)`
- * — so consumers can avoid casts. Defaults to `Element` for untyped calls.
- *
- * Returns a disposer that removes the listener.
- *
- * Usage (pseudo-code — see examples for live ones):
- *   delegate(rootEl, 'click', '[data-action="add"]', handlerFn);
- *   delegate(rootEl, 'focus', 'input',                handlerFn); // auto-capture
- */
-declare function delegate<T extends Element = Element>(rootEl: HTMLElement, type: string, selector: string, handler: (event: Event, target: T) => void, options?: DelegateOptions): () => void;
-/**
- * Capture-phase delegation — the escape hatch for custom non-bubbling events
- * (ones `delegate()`'s auto-promotion list doesn't know about) and for
- * capture-phase interception (run before any descendant's bubble-phase
- * handler). Reaches descendants of `rootEl` that match `selector` regardless
- * of how many times the diff has rebuilt them.
- *
- * Selector matching is `closest()`-style by default — the same walk-up as
- * `delegate()`, and it passes the matched ancestor (not the raw target) to
- * the handler — so a click on any descendant of the selected element climbs
- * to it. Pass `{ match: 'direct' }` to opt into strict `matches()`-style
- * matching (fire only when the event lands on the exact element the selector
- * identifies, with no walk-up).
- *
- * The generic `T` narrows the second handler argument to the expected element
- * type, mirroring `delegate<T>()`. Defaults to `Element` for untyped calls.
- *
- * Usage (pseudo-code — see examples for live ones):
- *   delegateCapture(rootEl, 'focus', 'input, textarea', handlerFn);
- *   delegateCapture(rootEl, 'click', '.exact', handlerFn, { match: 'direct' });
- */
-declare function delegateCapture<T extends Element = Element>(rootEl: HTMLElement, type: string, selector: string, handler: (event: Event, target: T) => void, options?: DelegateOptions): () => void;
-
 /**
  * `each(items, render, cacheKey?)` — keyed list iteration with per-item memoization.
  *
@@ -338,58 +171,27 @@ declare function each<T extends object>(items: readonly T[] | ArraySignal<T>, re
 declare function morph(liveRoot: Element, template: Element | SafeHtml | string, ownedItems?: ReadonlySet<Element>): void;
 
 /**
- * `mount(rootEl, render)` — kerf's render primitive.
- *
- * Wraps `effect()` so that whenever any signal read inside `render()`
- * changes, we re-run `render()` and apply the minimum DOM mutations against
- * the live tree. Element identity (and thus focus, selection, in-flight
- * pointer interactions, and event listeners on preserved nodes) is preserved
- * wherever the keyed/positional diff matches.
+ * `renderDocument(node)` — prepend the doctype to a rendered document.
  *
- * Two phases per render:
+ * Every kerf SSR app ends its routes with the identical concat
+ * `"<!DOCTYPE html>" + page.toString()`. This is that one line, blessed, so the
+ * doctype isn't reinvented (or forgotten) per route.
  *
- *   - Static surrounds (everything outside `each()` lists): kerf's native
- *     `morph()` reconciler walks a freshly-built template against the live
- *     tree. Conventions: id/data-key matching, `data-morph-skip`, focus
- *     preservation.
+ *   import { renderDocument } from 'kerfjs';
+ *   return c.html(renderDocument(<Page />));   // "<!DOCTYPE html><html>…"
  *
- *   - List interiors (children of every `each()` parent): native keyed
- *     reconciler operates directly on the live parent's children. No
- *     re-parse, no morph walk for cache-hit rows. Cost is O(changes), not
- *     O(rows).
- *
- * Compared to a `replaceChildren(...rows.map(toElement))` rebuild pattern,
- * the user-visible win is that an `<input>` the user is typing into
- * survives an unrelated re-render — its DOM node, focus state, and cursor
- * position are not destroyed and recreated on each tick.
+ * `node` is a `SafeHtml` (from JSX / the `html` tagged template) or a raw string
+ * — both are stringified via `.toString()`. The optional `doctype` overrides the
+ * default `'html'`.
  */
 
-/** What `mount()`'s render function may return; non-SafeHtml values coerce (nullish/boolean → render nothing). */
-type MountResult = SafeHtml | string | number | boolean | null | undefined;
-/**
- * Bind `render()` to the children of `rootEl`. Re-runs whenever any signal
- * read inside `render()` changes. Returns a disposer that tears down the
- * effect; call it when the host element is removed from the DOM.
- *
- * Conventions:
- *
- * - Diff keys: `id` and `data-key` are matched across the morph by key
- *   rather than positionally, so list reorders move existing nodes instead
- *   of churning unrelated siblings.
- * - `data-morph-skip`: any element with this attribute is left untouched
- *   inside on subsequent renders. Used for library-owned subtrees (xterm-
- *   style widgets, charts, third-party editors) where the library's own
- *   lifecycle manages the children.
- * - Focused text-entry inputs (`<input>` of typing kinds, `<textarea>`)
- *   keep their current value + selection range across morphs while focused.
- *   The user never sees their cursor jump mid-keystroke.
- * - Focused `[contenteditable]` elements have their entire subtree
- *   skipped (same mechanism as `data-morph-skip`). The user's in-progress
- *   edit — typed content, caret position, multi-range selections, anything
- *   else they did to the DOM — survives verbatim. The next render after
- *   blur catches up.
- */
-declare function mount(rootEl: HTMLElement, render: () => MountResult): () => void;
+/** Options for {@link renderDocument}. */
+interface RenderDocumentOptions {
+    /** The doctype name. Default `'html'` → `<!DOCTYPE html>`. */
+    doctype?: string;
+}
+/** Prepend `<!DOCTYPE …>` to a rendered `SafeHtml` (or string) document and return the full HTML string. */
+declare function renderDocument(node: SafeHtml | string, options?: RenderDocumentOptions): string;
 
 /**
  * `toElement(jsx)` — JSX → DOM, with SVG-aware namespace handling.
@@ -417,4 +219,4 @@ declare function mount(rootEl: HTMLElement, render: () => MountResult): () => vo
 
 declare function toElement(jsx: SafeHtml | string): Element | DocumentFragment;
 
-export { type AttrSpec, type DelegateOptions, type MountResult, SafeHtml, attr, delegate, delegateCapture, each, effect, morph, mount, signal, toElement };
+export { type RenderDocumentOptions, SafeHtml, each, effect, morph, renderDocument, signal, toElement };