@davidsouther/jiffies 2026.24.0 → 2026.24.2

package/src/components/virtual_scroll.ts

@@ -1,199 +0,0 @@
-import { debounce } from "../debounce.ts";
-import { FC, State } from "../dom/fc.ts";
-import { div } from "../dom/html.ts";
-
-export interface VirtualScrollSettings {
-  minIndex: number;
-  maxIndex: number;
-  startIndex: number;
-  itemHeight: number; // In pixels
-  count: number;
-  tolerance: number;
-}
-
-export type VirtualScrollDataAdapter<T> = (
-  offset: number,
-  limit: number,
-) => Iterable<T>;
-
-export function arrayAdapter<T>(data: T[]): VirtualScrollDataAdapter<T> {
-  return (offset, limit) => data.slice(offset, offset + limit);
-}
-
-export interface VirtualScrollProps<T, U extends HTMLElement> {
-  settings: Partial<VirtualScrollSettings>;
-  get: VirtualScrollDataAdapter<T>;
-  row: (t: T) => U;
-}
-
-export function fillVirtualScrollSettings(
-  settings: Partial<VirtualScrollSettings>,
-): VirtualScrollSettings {
-  const {
-    minIndex = 0,
-    maxIndex = Number.MAX_SAFE_INTEGER,
-    startIndex = 0,
-    itemHeight = 20,
-    count = maxIndex - minIndex + 1,
-    tolerance = count,
-  } = settings;
-
-  return { minIndex, maxIndex, startIndex, itemHeight, count, tolerance };
-}
-
-export function initialState<T>(
-  settings: VirtualScrollSettings,
-): VirtualScrollState<T> {
-  // From Denis Hilt, https://blog.logrocket.com/virtual-scrolling-core-principles-and-basic-implementation-in-react/
-  const { minIndex, maxIndex, startIndex, itemHeight, count, tolerance } =
-    settings;
-  const bufferedItems = count + 2 * tolerance;
-  const itemsAbove = Math.max(0, startIndex - tolerance - minIndex);
-
-  const viewportHeight = count * itemHeight;
-  const totalHeight = (maxIndex - minIndex + 1) * itemHeight;
-  const toleranceHeight = tolerance * itemHeight;
-  const bufferHeight = viewportHeight + 2 * toleranceHeight;
-  const topPaddingHeight = itemsAbove * itemHeight;
-  const bottomPaddingHeight = totalHeight - (topPaddingHeight + bufferHeight);
-
-  return {
-    scrollTop: 0,
-    settings,
-    viewportHeight,
-    totalHeight,
-    toleranceHeight,
-    bufferedItems,
-    topPaddingHeight,
-    bottomPaddingHeight,
-    data: [],
-    rows: [],
-  };
-}
-
-export function getData<T>(
-  minIndex: number,
-  maxIndex: number,
-  offset: number,
-  limit: number,
-  get: VirtualScrollDataAdapter<T>,
-): T[] {
-  const start = Math.max(0, minIndex, offset);
-  const end = Math.min(maxIndex, offset + limit - 1);
-  const data = get(start, end - start);
-  return [...data];
-}
-
-export function doScroll<T>(
-  scrollTop: number,
-  state: VirtualScrollState<T>,
-  get: VirtualScrollDataAdapter<T>,
-): {
-  scrollTop: number;
-  topPaddingHeight: number;
-  bottomPaddingHeight: number;
-  data: T[];
-} {
-  const {
-    totalHeight,
-    toleranceHeight,
-    bufferedItems,
-    settings: { itemHeight, minIndex, maxIndex },
-  } = state;
-  const index =
-    minIndex + Math.floor((scrollTop - toleranceHeight) / itemHeight);
-  const data = getData(minIndex, maxIndex, index, bufferedItems, get);
-  const topPaddingHeight = Math.max((index - minIndex) * itemHeight, 0);
-  const bottomPaddingHeight = Math.max(
-    totalHeight - (topPaddingHeight + data.length * itemHeight),
-    0,
-  );
-
-  return { scrollTop, topPaddingHeight, bottomPaddingHeight, data };
-}
-
-interface VirtualScrollState<T, U extends HTMLElement = HTMLElement> {
-  settings: VirtualScrollSettings;
-  scrollTop: number; // px
-  bufferedItems: number; // count
-  totalHeight: number; // px
-  viewportHeight: number; // px
-  topPaddingHeight: number; // px
-  bottomPaddingHeight: number; // px
-  toleranceHeight: number; // px
-  data: T[];
-  rows: U[];
-}
-
-export interface VirtualScroll<T, U extends HTMLElement> {
-  state: VirtualScrollState<T>;
-  rows: U[];
-}
-
-export const VirtualScroll = FC<
-  VirtualScrollProps<unknown, HTMLElement>,
-  VirtualScrollState<unknown, HTMLElement>
->("virtual-scroll", (element, props) => {
-  const settings = fillVirtualScrollSettings(props.settings);
-  const state = {
-    ...initialState(settings),
-    ...element[State],
-  };
-  element[State] = state;
-
-  const scrollTo = (
-    { target }: { target?: { scrollTop: number } } = { target: state },
-  ) => {
-    const scrollTop = target?.scrollTop ?? state.topPaddingHeight;
-    const updatedSate = {
-      ...state,
-      ...doScroll(scrollTop, state, props.get),
-    };
-    setState(updatedSate);
-  };
-
-  const viewportElement = div({
-    style: { height: `${state.viewportHeight}px`, overflowY: "scroll" },
-    events: {
-      // @ts-expect-error
-      scroll: debounce(scrollTo, 0),
-    },
-  });
-  setTimeout(() => {
-    viewportElement.scroll?.({ top: state.scrollTop });
-  });
-
-  const setState = (newState: VirtualScrollState<unknown>) => {
-    state.scrollTop = newState.scrollTop;
-    state.topPaddingHeight = newState.topPaddingHeight;
-    state.bottomPaddingHeight = newState.bottomPaddingHeight;
-    state.data = newState.data;
-    state.rows = state.data.map(props.row);
-
-    viewportElement.update(
-      div({
-        class: "VirtualScroll__topPadding",
-        style: { height: `${state.topPaddingHeight}px` },
-      }),
-      ...(state.rows ?? []).map((row, i) =>
-        div(
-          {
-            class: `VirtualScroll__item_${i}`,
-            style: { height: `${settings.itemHeight}px` },
-          },
-          row,
-        ),
-      ),
-      div({
-        class: "VirtualScroll__bottomPadding",
-        style: { height: `${state.bottomPaddingHeight}px` },
-      }),
-    );
-  };
-
-  scrollTo();
-
-  return viewportElement;
-});
-
-export default VirtualScroll;

package/src/debounce.ts

@@ -1,14 +0,0 @@
-export function debounce<T extends unknown[]>(
-  fn: (...args: T) => void,
-  ms = 32,
-): (...args: T) => void {
-  let timer: ReturnType<typeof setTimeout>;
-  return (...args: T) => {
-    clearTimeout(timer);
-    timer = setTimeout(() => {
-      clearTimeout(timer);
-      return fn(...args);
-    }, ms);
-    return timer;
-  };
-}

package/src/diff.ts

@@ -1,82 +0,0 @@
-import { range } from "./range.ts";
-import { isSome, None, type Option, Some } from "./result.ts";
-
-export const DiffA = Symbol("A");
-export const DiffB = Symbol("B");
-
-export type DiffIndex = string | number;
-export type DiffPrimitive = string | number | boolean | null | undefined;
-
-interface DiffEntry {
-  key: DiffIndex;
-  left: DiffPrimitive;
-  right: DiffPrimitive;
-}
-
-interface DiffList {
-  key: DiffIndex;
-  children: (DiffEntry | DiffList)[];
-}
-
-function doDiff<T>(va: T, vb: T, k: DiffIndex): Option<DiffList | DiffEntry> {
-  if (Array.isArray(va)) {
-    // @ts-expect-error
-    return diffArray(va, vb, k);
-  }
-  if (typeof va === "object") {
-    const d = diffObject(va ?? {}, vb ?? {}, k);
-    if (d.children.length === 0) {
-      return None();
-    }
-    return Some(d);
-  }
-  if (Object.is(va, vb)) {
-    return None();
-  }
-  // @ts-expect-error
-  return { key: k, left: va, right: vb };
-}
-
-function diffArray<T>(
-  a: Partial<T>[],
-  b: Partial<T>[],
-  key: DiffIndex,
-): Option<DiffList> {
-  const indexes = Math.max(a.length, b.length);
-  const children = range(0, indexes)
-    .map((i) => doDiff(a[i], b[i], i))
-    .filter(isSome);
-  return children.length > 0 ? { key, children } : None();
-}
-
-function diffObject<T>(
-  a: Partial<T>,
-  b: Partial<T>,
-  key: DiffIndex = "",
-): DiffList {
-  const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
-  const children = [...keys]
-    // @ts-expect-error
-    .map((k) => doDiff(a[k], b[k], k))
-    .filter(isSome);
-  return {
-    key,
-    children,
-  };
-}
-
-export function diff<T>(
-  a: Partial<T>,
-  b: Partial<T>,
-): (DiffEntry | DiffList)[] {
-  if (typeof a !== "object" && !Object.is(a, b)) {
-    // @ts-expect-error
-    return [{ key: "", left: a, right: b }];
-  }
-  return (
-    Array.isArray(a)
-      ? // @ts-ignore
-        (diffArray(a, b, "") ?? { children: [] })
-      : diffObject(a, b, "")
-  ).children;
-}

package/src/display.ts

@@ -1,18 +0,0 @@
-export type Display =
-  | string
-  | {
-      toString(): string;
-    };
-
-export const isDisplay = (a: unknown): a is Display =>
-  typeof (a as Display)?.toString === "function" ||
-  typeof (a as Display) === "string";
-
-export const display = (a: unknown | Display): string => {
-  if (isDisplay(a)) {
-    const str = a.toString();
-    if (str === "[object Object]") return JSON.stringify(a);
-    return str;
-  }
-  return JSON.stringify(a);
-};

package/src/dom/README.md

@@ -1,107 +0,0 @@
-# Jiffies DOM
-
-Jiffies DOM is an HTML microframework, exposing access to the DOM in a functional-first way.
-
-```js
-import {form, input, label} from 'jiffies/dom/html';
-
-export const Form({
-        title,
-        action="#",
-        onSubmit = (event) => {},
-    },
-    ...children
-) =>
-    form({
-            action,
-            events: {
-              submit: (event) => {
-                event.preventDefault();
-                onSubmit(event);
-              }
-            }
-        },
-        h3(title),
-        ...children,
-        button({type: "submit"}, "Submit")
-    );
-
-export const Input(name, type="string") => {
-    let id = name.replace(/\s+/g, '_').toLowerCase();
-    return label(
-        {for: id},
-        name,
-        input({name, id, type})
-    )
-}
-
-window.document.body.append(
-    Form(
-        {
-            title: "Details",
-            onSubmit: (event) => {
-                console.log(event.target);
-            }
-        },
-        Input({name: "First Name"}),
-        Input({name: "Last Name"}),
-        Input({name: "Number of cats", type: "number"})
-    )
-);
-```
-
-Exposing HTML as a tree of function calls makes it very easy to compose units of HTML.
-Creating new functions which pass HTML fragments is natural and intuitive, and creating reusable chunks of common HTML patterns is easy.
-
-## Functional Components
-
-Exposing HTML as functions makes it easy on the programmer to create and compose HTML, but those functions lose context when they return.
-To capture HTML chunks and update them, use the `FC` function.
-The `FC` function creates new WebComponent elements in the DOM, and exposes an interface that matches native HTML elements.
-
-```js
-export const GameSquare = FC<{piece: Piece}>('game-square', (el, {piece}) => {
-    el.textContent = piece;
-    // `el` is retained between updates
-    return el;
-});
-
-export const GameBoard = FC<{pieces: Piece[]}>('game-board', (el, {pieces} => {
-    return el;
-}));
-```
-
-## Style Blocks
-
-The `compileFstyle` function streamlines creating nested style rules.
-When used with the `style` HTML tag, this can create complex layouts inline with components.
-
-```js
-const MyPage = () => [
-  style(
-    compileFstyle({
-      main: {
-        display: "flex",
-        flexDirection: "row",
-      },
-      "@media max-width(768px)": {
-        main: {
-          flexDirection: "column",
-        },
-      },
-    })
-  ),
-  section("..."),
-  section("..."),
-  section("..."),
-];
-```
-
-## jiffies-css
-
-Including [jiffies-css](https://www.npmjs.com/package/@davidsouther/jiffies-css)
-provides a semantic HTML base that styles by element type and ARIA role rather
-than class names. Load it with `jiffiesCssLink()` and build pages from the typed
-component functions in [`dom/components`](./components/index.ts) (`Card`, `Alert`,
-`Nav`, ...), which emit the exact structures jiffies-css targets — no manual class
-annotation.

package/src/dom/SKILL.md

@@ -1,201 +0,0 @@
----
-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/css/border.ts

@@ -1,47 +0,0 @@
-import type { Properties } from "../types/css.ts";
-import type { Side, Size } from "./constants.ts";
-import { getSide, getSize, isSide } from "./core.ts";
-
-export function rounded(size: Size = "", side: Side = "") {
-  if (isSide(size)) {
-    side = size;
-    size = "";
-  }
-  const sized = getSize(size);
-  return getSide(side).reduce((prev, curr) => {
-    if (curr === "") {
-      prev.borderRadius = sized;
-    } else {
-      // @ts-expect-error
-      prev[`border${curr}Radius`] = sized;
-    }
-    return prev;
-  }, {} as Properties);
-}
-
-export function border({
-  side: _side = "",
-  style: _style = "solid",
-  radius: _radius = "",
-  width: _width = 1,
-  color: _color = "black",
-}: {
-  side?: Side;
-  style?: "solid" | "dotted" | "dashed" | "double" | "none";
-  radius?: Size;
-  width?: 0 | 1 | 2 | 4 | 8;
-  color?: string;
-}) {
-  return {};
-}
-
-export function inset(
-  width: 0 | 1 | 2 | 4 | 8,
-  color1 = "gray",
-  color2 = "lightgray",
-) {
-  return {
-    ...border({ side: "tl", width, color: color1, radius: "none" }),
-    ...border({ side: "br", width, color: color2, radius: "none" }),
-  };
-}