@cplieger/ui 0.0.0-stage → 1.0.0-dev.1

package/src/primitives/roving-focus.ts

@@ -0,0 +1,198 @@
+/**
+ * roving-focus.ts — WAI-ARIA roving-tabindex keyboard navigation for
+ * composite widgets (menus, listboxes, pickers, toolbars): one Tab stop,
+ * arrow keys move focus. Items are queried live each keystroke; call
+ * `refresh()` after a bulk re-render to restore the single-Tab-stop invariant.
+ *
+ * Pairs with popover for the WAI-ARIA menu pattern:
+ *
+ * ```ts
+ * const pop = createPopover(button, panel, { haspopup: "menu" });
+ * const nav = rovingFocus(panel, "[role=menuitem]");
+ * // on open: nav.focusFirst();
+ * ```
+ *
+ * @module
+ */
+
+import { untracked } from "../signal/signal.js";
+
+import { createDriver, ownedBinding } from "./owner.js";
+
+/** Keyboard behavior of a roving-tabindex container: which arrow pair moves
+ *  focus, whether the ends wrap, whether Home/End jump, and whether
+ *  Enter/Space activate the focused item. The defaults are the WAI-ARIA
+ *  vertical-menu shape. */
+export interface RovingFocusOptions {
+  /** Which arrow pair moves focus: `"vertical"` (Up/Down, default) or
+   *  `"horizontal"` (Left/Right). */
+  orientation?: "vertical" | "horizontal";
+  /** Wrap from the last item to the first and vice versa. Default `true`. */
+  wrap?: boolean;
+  /** Home/End jump to the first/last item. Default `true`. */
+  homeEnd?: boolean;
+  /** Enter and Space activate (click) the focused item. Default `true`.
+   *  Disable when items are inputs or handle their own keys. */
+  activate?: boolean;
+}
+
+/** Handle on a wired container. Items are re-queried on every keystroke, so
+ *  adding or removing one needs no call here; `refresh()` exists for a bulk
+ *  re-render, which discards the element carrying the single `tabindex=0` Tab
+ *  stop. */
+export interface RovingFocusController {
+  /** Focus the first item (e.g. when a menu opens). */
+  focusFirst(): void;
+  /** Re-apply the roving tabindex after a bulk re-render: the current item
+   *  (focused, or the previous Tab stop if still present) keeps `tabindex=0`,
+   *  everything else gets `-1`. */
+  refresh(): void;
+  /** Remove the listeners. Tabindex attributes are left as-is, and
+   *  `focusFirst()` and `refresh()` do nothing from then on. */
+  dispose(): void;
+}
+
+/** Wire roving-tabindex arrow-key navigation over `container`'s descendants
+ *  matching `selector`. Returns a controller with `focusFirst` / `refresh` /
+ *  `dispose`. */
+export function rovingFocus(
+  container: HTMLElement,
+  selector: string,
+  opts?: RovingFocusOptions,
+): RovingFocusController {
+  const o = untracked(() => ({
+    vertical: (opts?.orientation ?? "vertical") !== "horizontal",
+    wrap: opts?.wrap ?? true,
+    homeEnd: opts?.homeEnd ?? true,
+    activate: opts?.activate ?? true,
+  }));
+  const prevKey = o.vertical ? "ArrowUp" : "ArrowLeft";
+  const nextKey = o.vertical ? "ArrowDown" : "ArrowRight";
+
+  interface State {
+    /** The committed tab stop. */
+    readonly stop: HTMLElement | null;
+    /** Moves at every refresh(), whose job is to re-apply even an unchanged stop. */
+    readonly sync: number;
+  }
+
+  return ownedBinding((binding) => {
+    const items = (): HTMLElement[] => [...container.querySelectorAll<HTMLElement>(selector)];
+    let listening = false;
+
+    const onKeyDown = (e: KeyboardEvent): void => {
+      driver.act((fx) => {
+        const list = items();
+        if (list.length === 0) {
+          return;
+        }
+        const active = document.activeElement;
+        const current = active instanceof HTMLElement ? list.indexOf(active) : -1;
+        let next: number;
+        switch (e.key) {
+          case nextKey:
+            next = current < list.length - 1 ? current + 1 : o.wrap ? 0 : list.length - 1;
+            break;
+          case prevKey:
+            next = current > 0 ? current - 1 : o.wrap ? list.length - 1 : 0;
+            break;
+          case "Home":
+            if (!o.homeEnd) {
+              return;
+            }
+            next = 0;
+            break;
+          case "End":
+            if (!o.homeEnd) {
+              return;
+            }
+            next = list.length - 1;
+            break;
+          case "Enter":
+          case " ":
+          case "Spacebar": {
+            const item = list[current];
+            if (o.activate && item !== undefined) {
+              // Suppress the native Enter/Space activation and fire exactly one click.
+              e.preventDefault();
+              fx.click(item);
+            }
+            return;
+          }
+          default:
+            return;
+        }
+        e.preventDefault();
+        const target = list[next];
+        if (target !== undefined) {
+          fx.focus(target);
+        }
+      });
+    };
+    const onFocusIn = (e: FocusEvent): void => {
+      const target = e.target;
+      if (binding.ended || !(target instanceof HTMLElement) || !target.matches(selector)) {
+        return;
+      }
+      driver.commit(
+        driver.state.stop === target ? driver.state : { ...driver.state, stop: target },
+      );
+    };
+    const listen = (on: boolean): void => {
+      if (listening !== on) {
+        listening = on;
+        const method = on ? "addEventListener" : "removeEventListener";
+        container[method]("keydown", onKeyDown as EventListener);
+        container[method]("focusin", onFocusIn as EventListener);
+      }
+    };
+
+    const driver = createDriver<State>({
+      initial: { stop: null, sync: 0 },
+      realize(fx, d) {
+        listen(true);
+        const list = items();
+        const target = d.stop !== null && list.includes(d.stop) ? d.stop : (list[0] ?? null);
+        for (const item of list) {
+          fx.setAttr(item, "tabindex", item === target ? "0" : "-1");
+        }
+      },
+      terminal() {
+        listen(false);
+      },
+    });
+
+    return {
+      controller: {
+        focusFirst(): void {
+          driver.act((fx) => {
+            const first = items()[0];
+            if (first !== undefined) {
+              fx.focus(first);
+            }
+          });
+        },
+        refresh(): void {
+          if (binding.ended) {
+            return;
+          }
+          // Re-deriving the stop from the DOM is this method's contract.
+          const list = items();
+          const active = document.activeElement;
+          const stop =
+            active instanceof HTMLElement && list.includes(active)
+              ? active
+              : (list.find((i) => i.getAttribute("tabindex") === "0") ?? null);
+          driver.commit({ stop, sync: driver.state.sync + 1 });
+        },
+        dispose: binding.dispose,
+      },
+      start: () => {
+        driver.flush();
+      },
+      release: () => {
+        driver.release();
+      },
+    };
+  });
+}

package/src/primitives/scroll-lock.ts

@@ -0,0 +1,119 @@
+// scroll-lock.ts — INTERNAL: the body scroll lock nested modals share. iOS
+// Safari ignores `overflow: hidden` on the root for touch-scroll, so the body
+// is pinned with `position: fixed` at the negated scroll offset instead.
+//
+// The lock is held while any registered holder is live, and a holder's
+// liveness is read from its dialog at every check, so a close or open the
+// browser makes during a lock write stops the writes for the old target.
+
+import type { StyleProp } from "./fx.js";
+import { createDriver, type Driver } from "./owner.js";
+
+type LockProp = Extract<StyleProp, "position" | "top" | "left" | "right" | "width" | "overflow">;
+const PROPS: readonly LockProp[] = ["position", "top", "left", "right", "width", "overflow"];
+
+interface LockState {
+  readonly held: ReadonlySet<symbol>;
+}
+
+/** Each holder's live state, read at every check. */
+const holders = new Map<symbol, () => boolean>();
+/** The page's own body styles and scroll offset, kept across a restart. */
+let saved: { readonly y: number; readonly styles: Readonly<Record<LockProp, string>> } | null =
+  null;
+
+function liveHolders(): ReadonlySet<symbol> {
+  const held = new Set<symbol>();
+  for (const [holder, live] of holders) {
+    if (live()) {
+      held.add(holder);
+    }
+  }
+  return held;
+}
+
+function sameSet(a: ReadonlySet<symbol>, b: ReadonlySet<symbol>): boolean {
+  return a.size === b.size && [...a].every((h) => b.has(h));
+}
+
+function lockValue(prop: LockProp, y: number): string {
+  switch (prop) {
+    case "position":
+      return "fixed";
+    case "top":
+      return `-${y.toString()}px`;
+    case "left":
+    case "right":
+      return "0";
+    case "width":
+      return "100%";
+    case "overflow":
+      return "hidden";
+  }
+}
+
+function makeLock(): Driver<LockState> {
+  return createDriver<LockState>({
+    initial: { held: new Set() },
+    observe(s) {
+      const held = liveHolders();
+      return sameSet(held, s.held) ? s : { held };
+    },
+    realize(fx, s) {
+      const body = document.body;
+      if (s.held.size > 0) {
+        saved ??= {
+          y: window.scrollY,
+          styles: Object.fromEntries(PROPS.map((p) => [p, body.style[p]])) as Record<
+            LockProp,
+            string
+          >,
+        };
+        for (const prop of PROPS) {
+          fx.setStyle(body, prop, lockValue(prop, saved.y));
+        }
+        return;
+      }
+      if (saved === null) {
+        return;
+      }
+      for (const prop of PROPS) {
+        fx.setStyle(body, prop, saved.styles[prop]);
+      }
+      const y = saved.y;
+      saved = null;
+      window.scrollTo(0, y);
+    },
+  });
+}
+
+let lock = makeLock();
+
+/** Register `holder` with its live state, or withdraw it with `null`. Sets
+ *  the lock's state without driving it. */
+export function holdScrollLock(holder: symbol, live: (() => boolean) | null): void {
+  if (live === null) {
+    holders.delete(holder);
+  } else {
+    holders.set(holder, live);
+  }
+  lock.sync();
+}
+
+/** Realize the lock for its current holders. */
+export function flushScrollLock(): void {
+  lock.sync();
+  lock.flush();
+}
+
+/** Test-only: restore the page's body styles and forget every holder. */
+export function _resetScrollLockForTest(): void {
+  if (saved !== null) {
+    for (const prop of PROPS) {
+      document.body.style[prop] = saved.styles[prop];
+    }
+  }
+  saved = null;
+  holders.clear();
+  lock = makeLock();
+}

package/src/primitives/skeleton.ts

@@ -0,0 +1,142 @@
+/**
+ * skeleton.ts — anti-flicker timing for a "show a skeleton, then replace it
+ * with content" load. Pure timing, no DOM: the caller paints the skeleton and
+ * the content; this owns WHEN.
+ *
+ * Two consumption styles, unified:
+ *
+ * ```ts
+ * // commit-style: the content render replaces the skeleton in place
+ * const t = skeletonTiming(() => paint(out, skeleton), { minVisibleMs: 300, signal });
+ * const data = await load(signal);
+ * t.commit(() => paint(out, content(data)));
+ *
+ * // teardown-style: the skeleton is its own element, removed on settle
+ * const t = skeletonTiming(() => {
+ *   const node = makeSkeleton();
+ *   list.append(node);
+ *   return () => node.remove();
+ * });
+ * await load();
+ * t.cancel(); // removes the skeleton if it was painted
+ * ```
+ *
+ * @module
+ */
+
+/** The three windows that decide whether a skeleton is painted at all and how
+ *  long it stays: the delay before it appears, the floor on how long it stays
+ *  once it has, and the load's abort signal. */
+export interface SkeletonTimingOptions {
+  /** Delay before the skeleton is painted (default 150ms). A load that settles
+   *  within this window never paints the skeleton at all. */
+  showDelayMs?: number;
+  /** Minimum time the skeleton stays up once painted (default 0 = none), so it
+   *  never appears then instantly vanishes. Leave at 0 when the skeleton
+   *  shares its container with the real content and must clear the instant the
+   *  load completes. */
+  minVisibleMs?: number;
+  /** Abort signal for the underlying load. If it fires before the skeleton is
+   *  painted, the skeleton is suppressed — no orphaned skeleton for a
+   *  cancelled or superseded load. It does NOT retract an already-painted
+   *  skeleton (settle with `commit` or `cancel` for that). */
+  signal?: AbortSignal;
+}
+
+/** The settle handle for one load. Call exactly one of `commit` (the content
+ *  arrived) or `cancel` (the load was abandoned); whichever runs first wins,
+ *  and a later call to either is a no-op. Leaving both uncalled leaves a
+ *  painted skeleton up forever. */
+export interface SkeletonTimingController {
+  /** Paint the content. Call once, after the awaited work settles. Honors
+   *  show-delay (renders immediately when the skeleton was never painted) and
+   *  min-visible (defers until the skeleton has been up long enough); any
+   *  teardown returned by `show` runs immediately before the render.
+   *
+   *  The render always runs (unless `cancel()` won first) — a caller whose
+   *  content is a captured, stale-sensitive result should guard its own render
+   *  closure (e.g. `if (signal.aborted) return;`). */
+  commit(render: () => void): void;
+  /** Abandon the load: clears a pending skeleton (so it never paints), runs
+   *  the `show` teardown if it was painted, and drops any pending deferred
+   *  `commit` render. Idempotent; the teardown runs at most once. */
+  cancel(): void;
+}
+
+/**
+ * Build an anti-flicker controller. `show` paints the skeleton (deferred by
+ * show-delay) and may return a teardown that removes it again; the returned
+ * controller settles the load with `commit(render)` (paint content) or
+ * `cancel()` (abandon).
+ */
+export function skeletonTiming(
+  show: (() => () => void) | (() => void),
+  opts?: SkeletonTimingOptions,
+): SkeletonTimingController {
+  const showDelayMs = opts?.showDelayMs ?? 150;
+  const minVisibleMs = opts?.minVisibleMs ?? 0;
+
+  let shownAt: number | null = null;
+  let teardown: (() => void) | undefined;
+  let committed = false;
+  let cancelled = false;
+  let commitTimer: ReturnType<typeof setTimeout> | null = null;
+
+  const showTimer = setTimeout(() => {
+    if (opts?.signal?.aborted === true) {
+      return;
+    }
+    shownAt = Date.now();
+    const result = show();
+    teardown = typeof result === "function" ? result : undefined;
+  }, showDelayMs);
+
+  const runTeardown = (): void => {
+    if (teardown !== undefined) {
+      const t = teardown;
+      teardown = undefined;
+      t();
+    }
+  };
+
+  return {
+    commit(render: () => void): void {
+      if (committed || cancelled) {
+        return;
+      }
+      committed = true;
+      clearTimeout(showTimer);
+      if (shownAt === null) {
+        // Skeleton never painted (fast load, or suppressed by abort) — paint
+        // the content straight away.
+        render();
+        return;
+      }
+      const paint = (): void => {
+        commitTimer = null;
+        runTeardown();
+        render();
+      };
+      const remaining = minVisibleMs - (Date.now() - shownAt);
+      if (remaining <= 0) {
+        paint();
+      } else {
+        commitTimer = setTimeout(paint, remaining);
+      }
+    },
+    cancel(): void {
+      if (cancelled) {
+        return;
+      }
+      cancelled = true;
+      clearTimeout(showTimer);
+      if (commitTimer !== null) {
+        // A commit deferred by min-visible loses to a later cancel: the render
+        // must not fire into a view the caller is abandoning.
+        clearTimeout(commitTimer);
+        commitTimer = null;
+      }
+      runTeardown();
+    },
+  };
+}

package/src/primitives/theme.ts

@@ -0,0 +1,202 @@
+/**
+ * theme.ts — Persisted tri-state theme controller (light / dark / system).
+ * While the choice is "system" it follows the OS preference live via
+ * matchMedia; concrete choices are pinned. The resolved concrete value is
+ * written to a document-element attribute (default `data-theme`) so CSS can
+ * key off it. `themeInitSnippet` produces an inline blocking-script string for
+ * paint-time application (a real import can't run before first paint).
+ *
+ * @module
+ */
+
+/** The persisted preference: a pinned concrete theme, or `"system"` to follow
+ *  the OS preference live. Distinct from the resolved value written to the
+ *  document element, which is always concrete. */
+export type ThemeChoice = "light" | "dark" | "system";
+type Resolved = "light" | "dark";
+
+/** Persistence adapter for the theme preference. Encapsulates WHERE and HOW the
+ *  value is stored, so an app can keep the theme inside its own structure (for
+ *  example a field of a larger JSON blob) rather than a bare localStorage key. */
+export interface ThemeStorage {
+  /** Read the persisted preference, or `null` when nothing is stored yet. */
+  get(): string | null;
+  /** Persist the preference value. */
+  set(value: string): void;
+}
+
+/** Where the preference is persisted, which attribute carries the resolved
+ *  theme, and a hook for each application. `storageKey` is the only required
+ *  field; supply `storage` when the value must live somewhere other than a
+ *  bare localStorage key. */
+export interface ThemeOptions {
+  /** localStorage key the default adapter persists under. Unused when a custom
+   *  `storage` adapter is supplied (the adapter owns where the value lives). */
+  storageKey: string;
+  /** Persistence adapter. Defaults to bare `localStorage[storageKey]`. Supply a
+   *  custom adapter to read/write the theme inside your own structure — e.g. a
+   *  `theme` field of a JSON blob: `get` parses the blob and returns the field,
+   *  `set` does a read-modify-write of that field. Everything else (tri-state
+   *  resolution, following the OS while `system`, the applied attribute) is
+   *  unchanged; a 2-state app simply never calls `set("system")`. */
+  storage?: ThemeStorage;
+  /** Attribute set on `<html>` with the resolved value. Default `data-theme`. */
+  attribute?: string;
+  /** Called with the resolved concrete theme whenever it changes/applies. */
+  onChange?: (resolved: Resolved) => void;
+}
+
+/** A live theme controller. The preference (`get`) and the theme actually
+ *  applied (`resolved`) are separate values and differ whenever the preference
+ *  is `"system"`. A controller keeps a matchMedia listener until `dispose`. */
+export interface ThemeController {
+  /** The stored preference (may be `"system"`). */
+  get(): ThemeChoice;
+  /** Persist + apply a preference. */
+  set(choice: ThemeChoice): void;
+  /** The concrete resolved theme (`"system"` → OS value via matchMedia). */
+  resolved(): Resolved;
+  /** Cycle light → dark → system → light. */
+  cycle(): void;
+  /** The current OS preference. */
+  getSystem(): Resolved;
+  /** Remove the matchMedia listener. */
+  dispose(): void;
+}
+
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+const DEFAULT_ATTRIBUTE = "data-theme";
+
+function isChoice(value: string | null): value is ThemeChoice {
+  return value === "light" || value === "dark" || value === "system";
+}
+
+/** Create a theme controller bound to the given storage key. Applies the
+ *  resolved theme immediately and starts following the OS while in "system". */
+export function createTheme(opts: ThemeOptions): ThemeController {
+  const attribute = opts.attribute ?? DEFAULT_ATTRIBUTE;
+  // Lazy + try/catch-wrapped below, so blocked/absent storage degrades to
+  // in-memory rather than throwing at construction.
+  const storage: ThemeStorage = opts.storage ?? {
+    get: () => window.localStorage.getItem(opts.storageKey),
+    set: (value) => {
+      window.localStorage.setItem(opts.storageKey, value);
+    },
+  };
+  const mql = typeof window.matchMedia === "function" ? window.matchMedia(DARK_QUERY) : null;
+
+  const readChoice = (): ThemeChoice => {
+    let stored: string | null;
+    try {
+      stored = storage.get();
+    } catch {
+      stored = null;
+    }
+    return isChoice(stored) ? stored : "system";
+  };
+
+  let choice: ThemeChoice = readChoice();
+
+  const getSystem = (): Resolved => (mql?.matches === true ? "dark" : "light");
+  const resolved = (): Resolved => (choice === "system" ? getSystem() : choice);
+
+  const apply = (): void => {
+    const value = resolved();
+    document.documentElement.setAttribute(attribute, value);
+    opts.onChange?.(value);
+  };
+
+  const set = (next: ThemeChoice): void => {
+    choice = next;
+    try {
+      storage.set(next);
+    } catch {
+      // Storage denied, or a custom adapter threw — apply in memory only.
+    }
+    apply();
+  };
+
+  const cycle = (): void => {
+    set(choice === "light" ? "dark" : choice === "dark" ? "system" : "light");
+  };
+
+  const onSystemChange = (): void => {
+    if (choice === "system") {
+      apply();
+    }
+  };
+  mql?.addEventListener("change", onSystemChange);
+
+  apply();
+
+  return {
+    get: () => choice,
+    set,
+    resolved,
+    cycle,
+    getSystem,
+    dispose: () => {
+      mql?.removeEventListener("change", onSystemChange);
+    },
+  };
+}
+
+/** Build a self-contained IIFE string that reads the stored preference and sets
+ *  the resolved theme attribute synchronously. Inline it in a blocking `<head>`
+ *  script so the correct theme is painted before stylesheets parse:
+ *
+ *      <script>{themeInitSnippet("app-theme")}</script>
+ */
+export function themeInitSnippet(storageKey: string, attribute = DEFAULT_ATTRIBUTE): string {
+  const key = jsonForScript(storageKey);
+  const attr = jsonForScript(attribute);
+  const system = `window.matchMedia("${DARK_QUERY}").matches?"dark":"light"`;
+  return (
+    `(function(){try{` +
+    `var c=localStorage.getItem(${key});` +
+    `if(c!=="light"&&c!=="dark"&&c!=="system"){c="system";}` +
+    `var r=c==="system"?(${system}):c;` +
+    `document.documentElement.setAttribute(${attr},r);` +
+    // Falls back to the system preference, matching createTheme's runtime
+    // default, rather than a hardcoded "light".
+    `}catch(e){document.documentElement.setAttribute(${attr},${system});}})();`
+  );
+}
+
+/** Like {@link themeInitSnippet}, but the preference is the `field` of a JSON
+ *  object stored under `storageKey`, for a custom `storage` adapter that keeps
+ *  the theme in a JSON blob. A missing, blank or non-object blob, or a
+ *  `"system"` or unrecognized field, resolves to the OS preference. All three
+ *  arguments are escaped for the inline-`<script>` context. */
+export function themeInitSnippetFromJSON(
+  storageKey: string,
+  field: string,
+  attribute = DEFAULT_ATTRIBUTE,
+): string {
+  const key = jsonForScript(storageKey);
+  const fld = jsonForScript(field);
+  const attr = jsonForScript(attribute);
+  const system = `window.matchMedia("${DARK_QUERY}").matches?"dark":"light"`;
+  return (
+    `(function(){try{` +
+    `var raw=localStorage.getItem(${key});` +
+    `var o=raw?JSON.parse(raw):null;` +
+    `var c=o&&typeof o==="object"?o[${fld}]:null;` +
+    `if(c!=="light"&&c!=="dark"&&c!=="system"){c="system";}` +
+    `var r=c==="system"?(${system}):c;` +
+    `document.documentElement.setAttribute(${attr},r);` +
+    // Same system-preference fallback as themeInitSnippet.
+    `}catch(e){document.documentElement.setAttribute(${attr},${system});}})();`
+  );
+}
+
+/** `JSON.stringify` a value, then neutralize the characters that could break
+ *  out of an inline `<script>` context: `<` (so `</script>` can't close the
+ *  tag) and the raw line separators U+2028 / U+2029 (invalid in JS strings in
+ *  older engines, and stray line breaks in HTML). */
+function jsonForScript(value: string): string {
+  return JSON.stringify(value)
+    .replace(/</g, "\\x3C")
+    .replace(/\u2028/g, "\\u2028")
+    .replace(/\u2029/g, "\\u2029");
+}