@davidsouther/jiffies 2026.4.0 → 2026.24.0

package/src/dom/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: using-jiffies-dom
+description: Use when building or updating UI in a project that depends on @davidsouther/jiffies and you are writing DOM code with its html/svg/fc modules — creating elements, updating a node in place via its .update() method, wiring event handlers, setting class/style, or building stateful FC components. Covers the reentrant create-or-update model and the correct .ts import paths.
+---
+
+# Using Jiffies DOM
+
+## Overview
+
+Jiffies DOM is a tiny functional library that implements **reentrant DOM**, where every
+node is a function that when called again updates its contents. There are exactly two
+operations:
+
+- **Create:** calling a tag function (`div(...)`, `button(...)`, `circle(...)`) makes a
+  **new** node every time.
+- **Update in place:** every node Jiffies creates carries an `.update(attrs?, ...children)`
+  method. Calling it mutates **that same node** — same identity, no replacement.
+
+To update a node later, you must **keep a reference to it** and call `.update()` on it.
+Calling the tag function again does not update the old node; it builds a new one. 
+
+> Ideally, the object returned from the tag function would itself be directly callable, so instead of `const el = div({'class': 'off'}); el.update({'class': 'on'});`, you could just do `const el = div({'class': 'off'}); el({'class': 'on})';`. This is possible by wrapping the returned `HTMLDivElement` in a `Proxy` that implements a call interceptor, but `Proxy` cannot be passed to DOM APIs like appendChildren or addEventListener.
+
+## Import paths (get this right first)
+
+The package is `@davidsouther/jiffies` and its export map is `"./*.ts": "./src/*.ts"`.
+Imports use the real subpath **with the `.ts` extension**:
+
+```ts
+import { div, button, span, ul, li, p } from "@davidsouther/jiffies/dom/html.ts";
+import { FC, State } from "@davidsouther/jiffies/dom/fc.ts";
+import { svg, circle } from "@davidsouther/jiffies/dom/svg.ts";
+```
+
+The package READMEs show `jiffies/dom/html` — that path is **wrong**. Only `html` and `fc`
+are re-exported from `dom/index.ts`; reach `svg`, `observable`, `router`, `provide`, and
+`xml` by their own deep paths.
+
+## Quick reference
+
+| You want to… | Do this |
+|---|---|
+| Create an element | `div(attrs?, ...children)` — first arg is attrs only if a plain object |
+| Update a node in place | hold a reference to the node, then call `node.update(attrs?, ...children)` |
+| Set children only | `node.update("new text")` or `node.update(child1, child2)` |
+| Empty children | `import { CLEAR } from ".../dom/dom.ts"; node.update(CLEAR)` |
+| Add an event | `button({ events: { click: (e) => {...} } })` |
+| Replace an event handler | `node.update({ events: { click: newHandler } })` — old listener is removed first |
+| Remove an event | `node.update({ events: { click: null } })` |
+| Set a class | `div({ class: "a b" })` or `{ class: ["a", "b"] }` |
+| Remove a class on update | `node.update({ class: "!hidden" })` (`!` prefix removes) |
+| Inline style | `{ style: { flexDirection: "column" } }` or `{ style: "color:red" }` |
+| Boolean attribute | `{ disabled: true }` (falsy removes the attribute) |
+
+## The argument rule (common error source)
+
+The first argument is treated as an **attributes object** only if it is a plain object with
+no `nodeType`. A string, a Node, or `CLEAR` is treated as the **first child**.
+
+```ts
+div({ class: "row" }, span("a"), span("b")); // attrs + 2 children
+div(span("a"), span("b"));                    // 0 attrs, 2 children
+div("hello");                                 // 0 attrs, 1 text child
+```
+
+## Example: in-place Counter
+
+The number node is created once and reused on every click. The tag function is the create;
+`display.update(...)` is the reentrant update.
+
+```ts
+import { div, span, button } from "@davidsouther/jiffies/dom/html.ts";
+
+export function Counter(start = 0) {
+  let count = start;
+  const display = span(`${count}`); // created ONCE — keep the reference
+
+  return div(
+    display,
+    button(
+      { events: { click: () => { count += 1; display.update(`${count}`); } } },
+      "+1",
+    ),
+  );
+}
+```
+
+## FC: stateful components
+
+Use `FC` when a component owns state and should re-render itself from props. `FC(name, render)`
+defines a custom element and returns a constructor. Calling it creates the element; calling
+`.update(props)` **merges** props, re-runs `render`, and reconciles the rendered output into the host.
+
+```ts
+import { FC } from "@davidsouther/jiffies/dom/fc.ts";
+import { section, h2, ul, li } from "@davidsouther/jiffies/dom/html.ts";
+
+export const TodoList = FC<{ title: string; items: string[] }>(
+  "todo-list",
+  (_el, { title, items }) =>
+    section(h2(title ?? "Todos"), ul(...items.map((i) => li(i)))),
+);
+
+const list = TodoList({ title: "Chores", items: ["wash", "fold"] });
+document.body.append(list);
+list.update({ items: ["wash", "fold", "iron"] }); // title is retained (props merge)
+```
+
+The render function is `(el, props, children) => Element | Element[]`. `el` is the host
+custom element (also typed to carry `.update()` and the `State` symbol). It may return a
+single node or an array. Persist component state on the host via the `State` symbol:
+
+```ts
+import { FC, State } from "@davidsouther/jiffies/dom/fc.ts";
+
+export const Toggle = FC<{ label: string }, { on: boolean }>(
+  "app-toggle",
+  (el, { label }) => {
+    el[State] ??= { on: false };          // initialise once; retained across updates
+    const s = el[State];
+    return button(
+      { events: { click: () => { s.on = !s.on; el.update(); } } }, // el.update() re-renders
+      `${label}: ${s.on ? "on" : "off"}`,
+    );
+  },
+);
+```
+
+## Typing nodes
+
+You do not need a Jiffies-specific type to hold a node. Jiffies augments the global DOM
+`Element` interface with `.update()`, so standard lib types already carry it:
+
+```ts
+const display: HTMLSpanElement = span("0");
+display.update("1"); // .update is in scope on every Element
+```
+
+`dom/dom.ts` also exports `DOMElement` (`Element & ElementCSSInlineStyle`) for the general case.
+
+## Updates reconcile children by identity
+
+`.update(...children)` reconciles the new child list against the mounted children **by node
+object identity**. A child you pass back by the **same reference** is left in place and never
+detached, so its focus, scroll position, text selection, event listeners, and any descendant
+state survive the update. A freshly built node (or a string) has no matching identity, so it
+is inserted; a mounted child you omit is removed; order follows the argument list.
+
+This means you can update a parent and keep a specific subtree alive by passing the same node
+reference back through it:
+
+```ts
+const panel = div(span("Title"), input({ name: "q" })); // keep this reference
+const root = div(panel, p("status"));
+// ...later: replace the status line but keep the panel (and its focused input):
+root.update(panel, p("ready")); // panel is reused in place; only the <p> is rebuilt
+```
+
+Strings always rebuild (they carry no identity). The same reference must not appear twice in
+one update — a DOM node can occupy only one position.
+
+For fine-grained leaf updates (e.g. a counter), you can still hold a reference to the specific
+child node and call `.update()` on **that** node directly. **FC is the exception:** its
+`render` builds fresh nodes each update, so identity is not preserved inside an FC's own
+output (see the common mistake below).
+
+## Testing
+
+Tests use the `scope` microframework and run under Node (jsdom loads automatically when
+`window` is undefined). Run with `npm test` (`node ./src/test.mjs`).
+
+```ts
+import { describe, it, expect } from "@davidsouther/jiffies/scope/index.ts";
+import { button } from "@davidsouther/jiffies/dom/html.ts";
+
+describe("counter", () => {
+  it("reuses the node on update", () => {
+    const b = button("0");
+    b.update("1");
+    expect(b.textContent).toBe("1");
+  });
+});
+```
+
+## Common mistakes
+
+- **Calling the tag function again to "update."** That creates a new node. Hold the
+  reference and call `.update()` on it.
+- **Expecting event handlers to stack.** Calling `node.update({ events: { click: newFn } })`
+  removes the old listener before adding the new one. Each event key tracks exactly one
+  listener; the last one set is the one that fires.
+- **Importing `jiffies/dom/html`.** Use `@davidsouther/jiffies/dom/html.ts` (full name, `.ts`).
+- **Passing a config object as the first child.** A plain object becomes attrs; wrap text/nodes
+  as children explicitly.
+- **Expecting FC `.update()` to preserve child DOM identity.** It re-renders and replaces
+  children. For stable child nodes, update them directly.
+- **Using namespace-qualified SVG attributes.** `update()` always calls `setAttribute`, not
+  `setAttributeNS`. Attributes on SVG elements are plain unqualified names; read them back with
+  `getAttribute`, not `getAttributeNS`.
+- **Copying README examples verbatim.** The package README snippets are illustrative and not
+  all valid TypeScript; rely on this skill and the `*.test.ts` files for working code.

package/src/dom/dom.ts

@@ -1,14 +1,37 @@
-import { assertExists } from "../assert.ts";
+import { assert, assertExists } from "../assert.ts";
 import type { Properties as SVGProperties } from "./types/css.ts";
 
+if (typeof window === "undefined") {
+  const { JSDOM } = await import("jsdom");
+  // biome-ignore lint/suspicious/noGlobalAssign: Load JSDom globally
+  window = global.window = new JSDOM().window as unknown as Window &
+    typeof globalThis;
+  global.HTMLElement ??= window.HTMLElement;
+  global.customElements ??= window.customElements;
+  // Unconditional: jsdom's dispatchEvent instanceof-checks its own Event class, so Node's native Event must be replaced.
+  global.Event = window.Event as unknown as typeof Event;
+  global.MouseEvent ??= window.MouseEvent as unknown as typeof MouseEvent;
+  global.Element ??= window.Element as unknown as typeof Element;
+}
+
 export const XHTML_NAMESPACE_URI = "http://www.w3.org/1999/xhtml";
 export const SVG_NAMESPACE_URI = "http://www.w3.org/2000/svg";
 
 const Events = Symbol("events");
 export const CLEAR = Symbol("Clear children");
 
+// Node.ELEMENT_NODE; the Node global is not installed in the jsdom bootstrap
+// above, so the numeric constant is used directly (cf. nodeType 3 for text).
+const ELEMENT_NODE = 1;
+
 export type EventHandler = EventListenerOrEventListenerObject;
-export type DenormChildren = Node | string | typeof CLEAR;
+export type DenormChildren =
+  | Node
+  | string
+  | typeof CLEAR
+  | null
+  | undefined
+  | false;
 
 export type DOMElement = Element & ElementCSSInlineStyle;
 
@@ -43,7 +66,7 @@ export type DOMUpdates<E extends Element = Element> =
   | DenormChildren[];
 
 function isAttrs<E extends Element>(
-  attrs: DenormAttrs<E> | undefined
+  attrs: DenormAttrs<E> | undefined,
 ): attrs is Attrs<E> {
   if (!attrs) {
     return false;
@@ -57,7 +80,7 @@ function isAttrs<E extends Element>(
 export function normalizeArguments<E extends Element>(
   attrs?: DenormAttrs<E>,
   children: DenormChildren[] = [],
-  defaultAttrs: Attrs<E> = {}
+  defaultAttrs: Attrs<E> = {},
 ): [Attrs<E>, DenormChildren[]] {
   let attributes: Attrs<E>;
   if (isAttrs(attrs)) {
@@ -68,7 +91,10 @@ export function normalizeArguments<E extends Element>(
     }
     attributes = defaultAttrs;
   }
-  return [attributes, children.flat()];
+  // Drop conditional/absent children (React's `{cond && <X/>}` idiom): null,
+  // undefined, and false. `0` and `""` are kept — they are legitimate text
+  // nodes, and dropping them would reintroduce the React `0`-renders-nothing bug.
+  return [attributes, children.flat().filter((c) => c != null && c !== false)];
 }
 
 export function up<E extends Element>(
@@ -79,29 +105,53 @@ export function up<E extends Element>(
   return update(element, ...normalizeArguments(attrs, children)) as E;
 }
 
+/**
+ * (Re)attach a single listener for `type`, replacing any handler `events`
+ * already tracks for it, so each event has exactly one live handler — no
+ * stacking, no orphans. `events` is the element's own `[Events]` map; it
+ * stays the single source of truth.
+ */
+function setListener(
+  target: EventTarget,
+  events: Map<string, EventHandler>,
+  type: string,
+  handler: EventHandler,
+): void {
+  if (events.has(type)) {
+    target.removeEventListener(type, assertExists(events.get(type)));
+  }
+  target.addEventListener(type, handler);
+  events.set(type, handler);
+}
+
+/** Detach the listener `events` tracks for `type`, if any, and forget it. */
+function clearListener(
+  target: EventTarget,
+  events: Map<string, EventHandler>,
+  type: string,
+): void {
+  if (events.has(type)) {
+    target.removeEventListener(type, assertExists(events.get(type)));
+    events.delete(type);
+  }
+}
+
 export function update(
   element: Omit<Element, "update">,
   attrs: Attrs<Element>,
-  children: DenormChildren[]
+  children: DenormChildren[],
 ): Element {
-  // Track events, to remove later
   element[Events] ??= new Map<string, EventHandler>();
   const $events = element[Events];
-  // const { style = {}, events = {}, ...rest } = attrs;
 
-  for (const [k, v] of Object.entries(
-    (attrs.events as NonNullable<typeof attrs.events>) ?? {}
-  )) {
+  for (const [k, v] of Object.entries(attrs.events ?? {})) {
     if (v === null) {
-      if ($events.has(k)) {
-        const listener = assertExists($events.get(k));
-        element.removeEventListener(k, listener);
-      }
+      clearListener(element, $events, k);
     } else if (v !== undefined) {
-      element.addEventListener(k as keyof ElementEventMap, v);
-      $events.set(k, v);
+      setListener(element, $events, k, v);
     }
   }
+  element.toggleAttribute("data-hydrate", $events.size > 0);
 
   const _style = (element as { style?: Partial<CSSStyleDeclaration> }).style;
   if (_style) {
@@ -109,7 +159,7 @@ export function update(
       _style.cssText = attrs.style;
     } else {
       for (const [k, v] of Object.entries(
-        (attrs.style as Partial<CSSStyleDeclaration>) ?? {}
+        (attrs.style as Partial<CSSStyleDeclaration>) ?? {},
       )) {
         // @ts-expect-error Object.entries is unable to statically look into args
         _style[k] = v;
@@ -138,34 +188,19 @@ export function update(
       continue;
     }
 
-    const useNamespace = false;
-    element.namespaceURI &&
-      element.namespaceURI !== XHTML_NAMESPACE_URI &&
-      element.namespaceURI !== SVG_NAMESPACE_URI;
-    const remove = !v;
-
-    if (useNamespace) {
-      if (remove) {
-        element.removeAttributeNS(element.namespaceURI, k);
-      } else if (v === true) {
-        element.setAttributeNS(element.namespaceURI, k, k);
-      } else {
-        element.setAttributeNS(element.namespaceURI, k, String(v));
-      }
+    if (!v) {
+      element.removeAttribute(k);
+    } else if (v === true) {
+      element.setAttribute(k, k);
     } else {
-      if (remove) {
-        element.removeAttribute(k);
-      } else if (v === true) {
-        element.setAttribute(k, k);
-      } else {
-        element.setAttribute(k, String(v));
-      }
+      element.setAttribute(k, String(v));
     }
   }
 
   if (children?.length > 0) {
-    element.replaceChildren(
-      ...(children[0] === CLEAR ? [] : (children as (string | Node)[]))
+    reconcileChildren(
+      element,
+      children[0] === CLEAR ? [] : (children as (string | Node)[]),
     );
   }
 
@@ -174,3 +209,119 @@ export function update(
 
   return element as Element;
 }
+
+/**
+ * Reconcile `element`'s mounted children against expected `children`, mutating the live DOM in place.
+ */
+export function reconcileChildren(
+  element: Node,
+  children: (string | Node)[],
+): void {
+  const desired = findDesiredNodes(element, children);
+
+  const { mountedSet, unclaimed } = findUnclaimedNodes(desired, element);
+
+  patchUnclaimedNodes(desired, mountedSet, unclaimed);
+
+  clearUnwantedNodes(desired, element);
+
+  insertDesiredNodes(element, desired);
+}
+
+function findDesiredNodes(element: Node, children: (string | Node)[]): Node[] {
+  const doc = element.ownerDocument ?? window.document;
+  const desired: Node[] = children.map((child) =>
+    typeof child === "string" ? doc.createTextNode(child) : child,
+  );
+  return desired;
+}
+
+function insertDesiredNodes(element: Node, desired: Node[]) {
+  let cursor: ChildNode | null = element.firstChild;
+  for (const node of desired) {
+    if (node === cursor) {
+      cursor = cursor.nextSibling;
+    } else {
+      element.insertBefore(node, cursor);
+    }
+  }
+}
+
+function clearUnwantedNodes(desired: Node[], element: Node) {
+  const keep = new Set(desired);
+  for (const mounted of Array.from(element.childNodes)) {
+    if (!keep.has(mounted)) {
+      element.removeChild(mounted);
+    }
+  }
+}
+
+function patchUnclaimedNodes(
+  desired: Node[],
+  mountedSet: Set<Node>,
+  unclaimed: Node[],
+) {
+  let claim = 0;
+  for (let i = 0; i < desired.length; i++) {
+    const node = desired[i];
+    if (node.nodeType !== ELEMENT_NODE || mountedSet.has(node)) {
+      continue;
+    }
+    if (claim < unclaimed.length) {
+      if (unclaimed[claim].nodeName === node.nodeName) {
+        patchNode(unclaimed[claim] as Element, node as Element);
+        desired[i] = unclaimed[claim];
+      }
+      claim++;
+    }
+  }
+}
+
+function findUnclaimedNodes(
+  desired: Node[],
+  element: Node,
+): { mountedSet: Set<Node>; unclaimed: Node[] } {
+  const unclaimed: Node[] = [];
+  const desiredSet = new Set<Node>(desired);
+  const mountedSet = new Set<Node>(element.childNodes);
+  for (const mounted of Array.from(element.childNodes)) {
+    if (mounted.nodeType === ELEMENT_NODE && !desiredSet.has(mounted)) {
+      unclaimed.push(mounted);
+    }
+  }
+  return { mountedSet, unclaimed };
+}
+
+export function patchNode(kept: Element, fresh: Element): void {
+  assert(kept.nodeName === fresh.nodeName, "patching nodes of different types");
+
+  // Remove `kept` attributes that aren't on `fresh`, then add `fresh` attributes not on `kept`.
+  for (const { name } of Array.from(kept.attributes)) {
+    if (!fresh.hasAttribute(name)) {
+      kept.removeAttribute(name);
+    }
+  }
+  for (const { name, value } of Array.from(fresh.attributes)) {
+    if (kept.getAttribute(name) !== value) {
+      kept.setAttribute(name, value);
+    }
+  }
+
+  // Similar to attributes, but operating in a map on the side rather than the node itself.
+  kept[Events] ??= new Map<string, EventHandler>();
+  const keptEvents = kept[Events];
+  const freshEvents = fresh[Events] ?? new Map<string, EventHandler>();
+  for (const [type] of keptEvents) {
+    if (!freshEvents.has(type)) {
+      clearListener(kept, keptEvents, type);
+    }
+  }
+  for (const [type, handler] of freshEvents) {
+    setListener(kept, keptEvents, type, handler);
+  }
+
+  // Custom elements rebuild their own subtrees
+  if (customElements.get(kept.localName)) return;
+
+  reconcileChildren(kept, Array.from(fresh.childNodes));
+}

package/src/dom/fc.ts

@@ -3,6 +3,7 @@ import {
   type DenormChildren,
   type DomAttrs,
   normalizeArguments,
+  reconcileChildren,
   update,
 } from "./dom.ts";
 
@@ -56,8 +57,8 @@ export function FC<Props extends object, State extends object = object>(
       update(this, this.#attrs, []);
 
       // Re-run the component function using new element, attrs, and children.
-      const replace = [component(this, this.#attrs, this.#children)];
-      this.replaceChildren(...replace.flat());
+      const rendered = [component(this, this.#attrs, this.#children)];
+      reconcileChildren(this, rendered.flat());
       return this;
     }
   }
@@ -68,7 +69,10 @@ export function FC<Props extends object, State extends object = object>(
     attrs?: Attrs<Props> | DenormChildren,
     ...children: DenormChildren[]
   ): FCComponent<Props, State> => {
-    const element = document.createElement(name) as FCComponent<Props, State>;
+    const element = window.document.createElement(name) as FCComponent<
+      Props,
+      State
+    >;
     element.update(attrs, ...children);
     return element;
   };

package/src/dom/form/form.app.ts

@@ -1,50 +1,44 @@
-import { article, button, div, main, small } from "../html.ts";
+import { button, div, main, small } from "../html.ts";
 import { Form, Input } from "./form.ts";
 
 export const App = () =>
   main(
-    { class: "container" },
-    article(
-      Form(
-        {
-          events: {
-            submit(event) {
-              console.log(
-                "Should see fields for firstname, lastname, email, etc",
-              );
-              console.log(event);
-            },
+    Form(
+      {
+        events: {
+          submit(event) {
+            console.log(
+              "Should see fields for firstname, lastname, email, etc",
+            );
+            console.log(event);
           },
         },
-        div(
-          { class: "grid" },
-          Input({ id: "firstname", placeholder: "First name" }),
-          Input({ id: "lastname", placeholder: "Last name" }),
-        ),
-        Input(
-          {
-            id: "email",
-            type: "email",
-            placeholder: "Email address",
-            required: true,
-          },
-          small("We will never share your email with anyone."),
-        ),
-        button({ type: "submit" }, "Submit"),
-        div(
-          { class: "grid" },
-          Input({ id: "valid", placeholder: "Valid", "aria-invalid": "false" }),
-          Input({
-            id: "invalid",
-            placeholder: "Invalid",
-            "aria-invalid": "true",
-          }),
-          Input({ id: "disabled", placeholder: "Disabled", disabled: true }),
-          Input({ id: "readonly", value: "Readonly", readOnly: true }),
-        ),
-        // Dropdown({id: 'fruit', label: "Fruit", placeholder: "Select a fruit...", options: ['Banana', 'Watermelon', 'Apple', 'Orange', 'Mango']}),
-        // Radios({legend: 'Size', options: {small: 'Small', medium: 'Medium', large: 'Large', extralarge: "Extra Large"}, checked: 'small'}),
-        // Checkboxes({options: {terms: 'I agree to the Terms and Conditions', termsSharing: {label: 'I agree to share my information with partners', disabled: true, checked: true}}),
+      },
+      div(
+        { class: "grid" },
+        Input({ id: "firstname", placeholder: "First name" }),
+        Input({ id: "lastname", placeholder: "Last name" }),
+      ),
+      Input(
+        {
+          id: "email",
+          type: "email",
+          placeholder: "Email address",
+          required: true,
+        },
+        small("We will never share your email with anyone."),
+      ),
+      button({ type: "submit" }, "Submit"),
+      div(
+        { class: "grid" },
+        Input({ id: "valid", placeholder: "Valid", "aria-invalid": "false" }),
+        Input({
+          id: "invalid",
+          placeholder: "Invalid",
+          "aria-invalid": "true",
+        }),
+        Input({ id: "disabled", placeholder: "Disabled", disabled: true }),
+        Input({ id: "readonly", value: "Readonly", readOnly: true }),
       ),
     ),
   );