kerfjs 0.5.1 → 0.7.0

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 import { ArraySignal } from './array-signal.js';
 import { SafeHtml } from './jsx-runtime.js';
 export { Fragment, isSafeHtml, raw } from './jsx-runtime.js';
-export { ReadonlySignal, Signal, batch, computed, effect, signal } from '@preact/signals-core';
+import { Signal } from '@preact/signals-core';
+export { ReadonlySignal, Signal, batch, computed, effect } from '@preact/signals-core';
 export { S as Store, d as defineStore, r as resetAllStores } from './testing-CdMgVVoI.js';
 
 /**
@@ -60,39 +61,104 @@ declare function delegate(rootEl: HTMLElement, type: string, selector: string, h
 declare function delegateCapture(rootEl: HTMLElement, type: string, selector: string, handler: Handler): () => void;
 
 /**
- * `each(items, render, key?)` — keyed list iteration with per-item memoisation.
+ * `each(items, render, cacheKey?)` — keyed list iteration with per-item memoization.
  *
  * Drops in as the body of a list-rendering JSX expression inside a `mount()`
  * render function. Returns a `SafeHtml` carrying a structured list segment,
  * so `mount()` can run a native keyed reconciler instead of the general-
  * purpose morph for these children.
  *
- * Two layers of optimisation:
+ * Two layers of optimization:
  *
- * 1. Per-item memoisation. `render(item)` is skipped for items whose object
- *    identity (and optional `key`) are unchanged since the previous call.
- *    Their HTML strings come from a `WeakMap` keyed by item reference. The
- *    immutable-update style ("replace the row object" instead of "mutate it")
- *    makes the cache work automatically.
+ * 1. Per-item memoization. `render(item)` is skipped for items whose object
+ *    identity (and optional `cacheKey`) are unchanged since the previous
+ *    call. Their HTML strings come from a `WeakMap` keyed by item reference.
+ *    The immutable-update style ("replace the row object" instead of "mutate
+ *    it") makes the cache work automatically.
  *
- * 2. Structural handoff. `mount()` recognises the list segment and bypasses
+ * 2. Structural handoff. `mount()` recognizes the list segment and bypasses
  *    the parse-the-whole-table round trip: only fresh items get parsed (one
  *    at a time, into the smallest detached element), and only changed rows
  *    get patched in the live DOM. Unchanged rows are physically the same
  *    nodes they were before — never visited.
  *
- * `key` covers the case where external state, not the item itself, drives
- * what the row should render (e.g. a "currently selected" id flips a CSS
- * class on one row). Same item identity but a different `key` value means
- * "re-render this item." If you don't pass `key`, only identity changes
- * invalidate.
+ * `cacheKey` is a passive comparator — it covers the case where external
+ * state, not the item itself, drives what the row should render (e.g. a
+ * "currently selected" id flips a CSS class on one row). Same item identity
+ * but a different `cacheKey` return value means "the cached HTML is stale —
+ * re-render this row." Not a reactive subscription: it's evaluated once per
+ * mount-effect run and compared against the previous run's return value. If
+ * you don't pass `cacheKey`, only object-identity changes invalidate the
+ * cache. (Renamed from `key` for clarity — it shared a name with React's
+ * `key` prop but has different semantics; the new name says what the
+ * parameter actually does. Positional callers — the canonical form — are
+ * unaffected.)
  *
  * Items must be objects (cache is a `WeakMap`); wrap primitives if you need
  * to iterate them. Each item's render output must produce exactly one
  * top-level element — the list reconciler binds one live DOM node per item.
  */
 
-declare function each<T extends object>(items: readonly T[] | ArraySignal<T>, render: (item: T, index: number) => SafeHtml | string, key?: (item: T, index: number) => unknown): SafeHtml;
+declare function each<T extends object>(items: readonly T[] | ArraySignal<T>, render: (item: T, index: number) => SafeHtml | string, cacheKey?: (item: T, index: number) => unknown): SafeHtml;
+
+/**
+ * `morph(liveRoot, template)` — minimum-mutation DOM reconciliation.
+ *
+ * Public primitive (KF-150): one-shot reconciliation against an
+ * already-populated element. `mount()` first paints by writing
+ * `innerHTML`; `morph()` is the "I have a live tree and a template,
+ * reconcile them in place" sibling. Use it for SSR hydration of static
+ * fragments, page-refresh diffs, third-party widget remounts, etc.
+ *
+ * Replaces our previous dependency on `morphdom`. The algorithm is the
+ * classic two-tree walk: match children by key (id, then data-key, then
+ * positional same-tag), morph matches in place, insert / remove / clone
+ * the rest. Specialized for what kerf needs:
+ *
+ * - `childrenOnly` is always true; the live root is never replaced.
+ * - Per-element short-circuits: `data-morph-skip` (library-owned, leave
+ *   element AND subtree verbatim), `data-morph-skip-children` (KF-152 —
+ *   morph attrs on the element, leave its subtree verbatim — for
+ *   client-hydrated slots whose loading/state classes still need to flow
+ *   through), and `isEqualNode` (byte-identical, no work needed).
+ * - **`data-morph-preserve`** (KF-151) is honored in the trailing-removal
+ *   pass: an unmatched live element with this attribute is skipped instead
+ *   of removed. Lets imperatively-injected nodes (autoplay `<video>`s,
+ *   tour-widget tooltips, analytics pixels) survive across renders without
+ *   having to `data-morph-skip` the entire parent.
+ * - **`ownedItems`** is the set of element nodes owned by an `each()`
+ *   list reconciler. The morph skips them in every children walk —
+ *   they're not added to the keyed-lookup map, the from-cursor advances
+ *   past them, and the trailing-removal pass leaves them in place. This
+ *   lets each() coexist with non-list siblings inside the same parent
+ *   (KF-102 round 2): the morph still walks the parent's children to
+ *   reconcile siblings, but never disturbs list rows. The parameter is an
+ *   internal coordination channel between `mount()` and the reconciler;
+ *   public callers should omit it (the default empty set is correct for
+ *   any tree that isn't being managed by an active `mount()`).
+ * - Focused text inputs (`<input>`/`<textarea>`) keep their value +
+ *   selection across the morph; focused `[contenteditable]` keeps its
+ *   entire subtree (typed content + caret + multi-range selection).
+ *
+ * Algorithm credit: based on the design of
+ * https://github.com/patrick-steele-idem/morphdom by Patrick Steele-Idem
+ * (MIT licensed). Reimplemented here so kerf can specialize the hot paths
+ * (segment-aware list dispatch, lighter callback surface) and drop the
+ * runtime dependency. Original copyright preserved in `LICENSE`.
+ */
+
+/**
+ * Reconcile the children of `liveRoot` to match `template`.
+ *
+ * `template` can be an `Element` (used directly), a `SafeHtml`, or a raw
+ * HTML string — the latter two are stringified and parsed into a transient
+ * element whose tag matches `liveRoot`. The active text-entry / focused-
+ * contenteditable preservation rules apply in all cases.
+ *
+ * `ownedItems` is an internal coordination channel for `mount()`'s list
+ * reconciler; public callers should omit it.
+ */
+declare function morph(liveRoot: Element, template: Element | SafeHtml | string, ownedItems?: ReadonlySet<Element>): void;
 
 /**
  * `mount(rootEl, render)` — kerf's render primitive.
@@ -106,7 +172,7 @@ declare function each<T extends object>(items: readonly T[] | ArraySignal<T>, re
  * Two phases per render:
  *
  *   - Static surrounds (everything outside `each()` lists): kerf's native
- *     `diff()` reconciler walks a freshly-built template against the live
+ *     `morph()` reconciler walks a freshly-built template against the live
  *     tree. Conventions: id/data-key matching, `data-morph-skip`, focus
  *     preservation.
  *
@@ -147,6 +213,20 @@ declare function each<T extends object>(items: readonly T[] | ArraySignal<T>, re
 type MountResult = SafeHtml | string | number | boolean | null | undefined;
 declare function mount(rootEl: HTMLElement, render: () => MountResult): () => void;
 
+/**
+ * Re-exports of `@preact/signals-core`. Lets the rest of the codebase depend
+ * on `'./reactive.js'` without naming the underlying lib, so swapping it out
+ * later (or fronting it with a hand-rolled implementation) is a one-file
+ * change.
+ *
+ * The `signal()` factory is dev-gated: when `NODE_ENV !== 'production'` and
+ * `KERF_DEV_WARN_UNTRACKED_SIGNALS === '1'`, it returns a `DevSignal` that
+ * warns on writes to signals with no subscribers (KF-176). Off by default;
+ * production always returns the bare `@preact/signals-core` signal.
+ */
+
+declare function signal<T>(value?: T): Signal<T>;
+
 /**
  * `toElement(jsx)` — JSX → DOM, with SVG-aware namespace handling.
  *
@@ -163,4 +243,4 @@ declare function mount(rootEl: HTMLElement, render: () => MountResult): () => vo
 
 declare function toElement(jsx: SafeHtml | string): Element;
 
-export { type MountResult, SafeHtml, delegate, delegateCapture, each, mount, toElement };
+export { type MountResult, SafeHtml, delegate, delegateCapture, each, morph, mount, signal, toElement };