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

package/src/primitives/focus-trap.ts

@@ -0,0 +1,157 @@
+/**
+ * focus-trap.ts — Keep Tab / Shift+Tab cycling within a container, per the
+ * WAI-ARIA dialog pattern. Headless: no DOM is created, only focus is managed.
+ *
+ * ```ts
+ * const release = trapFocus(dialogEl, { returnFocus: true });
+ * // ... interaction ...
+ * release(); // restores focus to the previously-focused element
+ * ```
+ *
+ * @module
+ */
+
+import { untracked } from "../signal/signal.js";
+
+import { createDriver, ownedBinding } from "./owner.js";
+
+/** The standard focusable-element selector. Elements are additionally filtered
+ *  to those that are rendered (see `isVisible`) at each Tab. */
+const FOCUSABLE =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+/** Is `el` laid out (and, where the engine supports it, actually visible)?
+ *  Uses `getClientRects().length` rather than `offsetParent !== null` so that
+ *  `position: fixed` elements — whose `offsetParent` is `null` — still count as
+ *  focusable. `checkVisibility` (when present) additionally rejects elements
+ *  hidden via `visibility`/`content-visibility`. */
+function isVisible(el: HTMLElement): boolean {
+  if (el.getClientRects().length === 0) {
+    return false;
+  }
+  return (
+    typeof el.checkVisibility !== "function" || el.checkVisibility({ visibilityProperty: true })
+  );
+}
+
+/** The two focus hand-offs a trap owns: which element takes focus on entry,
+ *  and where focus lands when the release function runs. Both optional — the
+ *  defaults focus the first focusable descendant and restore the element that
+ *  was focused when the trap was installed. */
+export interface FocusTrapOptions {
+  /** Element to focus on entry. Defaults to the first focusable descendant.
+   *  A `null` value is treated the same as omitting it. */
+  initialFocus?: HTMLElement | null;
+  /** Where focus goes on release. `true` (default) or omitted restores the
+   *  previously-focused element; an `HTMLElement` focuses that element; `false`
+   *  leaves focus untouched. */
+  returnFocus?: boolean | HTMLElement;
+}
+
+/** Trap Tab focus within `container`. Returns a release function. */
+export function trapFocus(container: HTMLElement, opts?: FocusTrapOptions): () => void {
+  const o = untracked(() => ({
+    initialFocus: opts?.initialFocus ?? null,
+    returnFocus: opts?.returnFocus ?? true,
+  }));
+
+  const getFocusable = (): HTMLElement[] =>
+    [...container.querySelectorAll<HTMLElement>(FOCUSABLE)].filter(isVisible);
+
+  return ownedBinding((binding) => {
+    const previousFocus =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    let listening = false;
+    let entered = false;
+
+    /** Where Tab must go instead of the browser's default, or null to leave it. */
+    const redirect = (e: KeyboardEvent): HTMLElement | null => {
+      const focusable = getFocusable();
+      const active = document.activeElement;
+      const inside = active instanceof Node && container.contains(active);
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (first === undefined || last === undefined) {
+        // No focusable targets: pin focus to the container, never let Tab out.
+        return container;
+      }
+      if (!inside) {
+        // Focus escaped, or was never inside: pull it back to the edge.
+        return e.shiftKey ? last : first;
+      }
+      if (e.shiftKey ? active === first : active === last) {
+        return e.shiftKey ? last : first;
+      }
+      return null;
+    };
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key !== "Tab") {
+        return;
+      }
+      driver.act((fx) => {
+        const target = redirect(e);
+        if (target !== null) {
+          e.preventDefault();
+          fx.focus(target);
+        }
+      });
+    };
+    // Capture phase on `document` (not `container`): focus that is currently
+    // outside the container still routes through here so it can be redirected in.
+    const listen = (on: boolean): void => {
+      if (listening !== on) {
+        listening = on;
+        if (on) {
+          document.addEventListener("keydown", onKey, true);
+        } else {
+          document.removeEventListener("keydown", onKey, true);
+        }
+      }
+    };
+
+    const driver = createDriver<null>({
+      initial: null,
+      realize(fx) {
+        listen(true);
+        if (entered) {
+          return;
+        }
+        entered = true;
+        const focusable = getFocusable();
+        if (focusable.length === 0) {
+          // Fail closed: with nothing focusable, the container itself holds
+          // focus so Tab can't escape to the page behind it.
+          // The attribute: a div's tabIndex property already reads -1 without it.
+          fx.setAttr(container, "tabindex", "-1");
+          fx.focus(container);
+          return;
+        }
+        // A detached initialFocus (an opener chained from a removed modal) is
+        // a safe no-op, not a throw.
+        const target = o.initialFocus ?? focusable[0];
+        if (target?.isConnected === true) {
+          fx.focus(target);
+        }
+      },
+      terminal(fx) {
+        listen(false);
+        const target =
+          o.returnFocus === true ? previousFocus : o.returnFocus === false ? null : o.returnFocus;
+        // Focusing a detached node throws in some engines and no-ops in others.
+        if (target?.isConnected === true) {
+          fx.focus(target);
+        }
+      },
+    });
+
+    return {
+      controller: binding.dispose,
+      start: () => {
+        driver.flush();
+      },
+      release: () => {
+        driver.release();
+      },
+    };
+  });
+}

package/src/primitives/fx.ts

@@ -0,0 +1,204 @@
+// fx.ts — INTERNAL: the effect vocabulary a driver's realization uses. Every
+// call that can run code outside the library is one method here, which writes
+// only what differs and then checks the pass, so a pass made stale by that
+// code restarts before its next effect.
+
+/** The inline style properties realization writes. */
+export type StyleProp =
+  "height" | "position" | "left" | "right" | "top" | "minWidth" | "width" | "overflow";
+
+/** `showModal`'s outcome, read from the element after the call. */
+type ShowResult = { readonly open: true } | { readonly open: false; readonly error: unknown };
+
+type Reflected = "hidden" | "inert" | "id" | "tabIndex";
+
+/** The checked effects of one pass. */
+export interface Fx {
+  setAttr(el: Element, name: string, value: string): void;
+  removeAttr(el: Element, name: string): void;
+  /** Adds only the missing tokens, in one write. */
+  addClass(el: Element, ...tokens: string[]): void;
+  removeClass(el: Element, ...tokens: string[]): void;
+  toggleClass(el: Element, token: string, on: boolean): void;
+  setProp<E extends HTMLElement, K extends Reflected>(el: E, key: K, value: E[K]): void;
+  /** Compared with the value the browser would serialize, so `-0px` reaches a fixed point. */
+  setStyle(el: HTMLElement, prop: StyleProp, value: string): void;
+  /** Skipped when `child` is already a child of `parent`. */
+  append(parent: Node, child: Node): void;
+  /** Skipped when detached. */
+  remove(node: ChildNode): void;
+  /** Skipped when `el` is focused or detached. */
+  focus(el: HTMLElement): void;
+  /** Skipped unless `el` is focused. */
+  blur(el: HTMLElement): void;
+  click(el: HTMLElement): void;
+  select(input: HTMLInputElement): void;
+  /** Skipped when already open. Never throws: a platform throw comes back as `error`. */
+  showModal(dialog: HTMLDialogElement): ShowResult;
+  /** Skipped when not open. */
+  close(dialog: HTMLDialogElement): void;
+  /** A user hook or another driver's flush: a throw is collected and yields undefined. */
+  call<R>(fn: () => R): R | undefined;
+  /** `call` for reading the outside facts a kick reports. The pass marks the kick
+   *  count just before `fn` runs, so a kick from inside `fn` makes it stale. */
+  measure<R>(fn: () => R): R | undefined;
+  /** Collect an error for the drive's edge. */
+  report(error: unknown): void;
+}
+
+/** What a pass gives its `Fx`. */
+interface Pass {
+  /** After an external call: throw to restart when the pass went stale. */
+  check(): void;
+  /** Before a measurement's reads. */
+  measured(): void;
+  /** Keep a hook's error for the drive's edge, or rethrow it. */
+  collect(error: unknown): void;
+}
+
+/** Read through a call: TypeScript keeps `dialog.open` narrowed across the platform
+ *  call that changes it (microsoft/TypeScript#9998). */
+function isOpen(dialog: HTMLDialogElement): boolean {
+  return dialog.open;
+}
+
+let scratch: HTMLElement | null = null;
+
+/** `value` as the browser serializes it for `prop`. */
+function serialized(prop: StyleProp, value: string): string {
+  scratch ??= document.createElement("div");
+  scratch.style[prop] = value;
+  const out = scratch.style[prop];
+  scratch.style[prop] = "";
+  return out;
+}
+
+/** The `Fx` of one pass: every method diffs, performs, then checks `pass`. */
+export function fxAt(pass: Pass): Fx {
+  const fx: Fx = {
+    setAttr(el, name, value) {
+      if (el.getAttribute(name) !== value) {
+        el.setAttribute(name, value);
+        pass.check();
+      }
+    },
+    removeAttr(el, name) {
+      if (el.hasAttribute(name)) {
+        el.removeAttribute(name);
+        pass.check();
+      }
+    },
+    addClass(el, ...tokens) {
+      const missing = tokens.filter((t) => !el.classList.contains(t));
+      if (missing.length > 0) {
+        el.classList.add(...missing);
+        pass.check();
+      }
+    },
+    removeClass(el, ...tokens) {
+      const present = tokens.filter((t) => el.classList.contains(t));
+      if (present.length > 0) {
+        el.classList.remove(...present);
+        pass.check();
+      }
+    },
+    toggleClass(el, token, on) {
+      if (on) {
+        fx.addClass(el, token);
+      } else {
+        fx.removeClass(el, token);
+      }
+    },
+    setProp(el, key, value) {
+      if (el[key] !== value) {
+        el[key] = value;
+        pass.check();
+      }
+    },
+    setStyle(el, prop, value) {
+      if (el.style[prop] !== serialized(prop, value)) {
+        el.style[prop] = value;
+        pass.check();
+      }
+    },
+    append(parent, child) {
+      if (child.parentNode !== parent) {
+        parent.appendChild(child);
+        pass.check();
+      }
+    },
+    remove(node) {
+      if (node.parentNode !== null) {
+        node.remove();
+        pass.check();
+      }
+    },
+    focus(el) {
+      if (el.isConnected && document.activeElement !== el) {
+        el.focus();
+        pass.check();
+      }
+    },
+    blur(el) {
+      if (document.activeElement === el) {
+        el.blur();
+        pass.check();
+      }
+    },
+    click(el) {
+      el.click();
+      pass.check();
+    },
+    select(input) {
+      input.select();
+      pass.check();
+    },
+    showModal(dialog) {
+      if (dialog.open) {
+        return { open: true };
+      }
+      let error: unknown = undefined;
+      try {
+        dialog.showModal();
+      } catch (e) {
+        error = e;
+      }
+      pass.check();
+      return isOpen(dialog) ? { open: true } : { open: false, error };
+    },
+    close(dialog) {
+      if (dialog.open) {
+        dialog.close();
+        pass.check();
+      }
+    },
+    call(fn) {
+      let out: ReturnType<typeof fn> | undefined;
+      try {
+        out = fn();
+      } catch (error) {
+        pass.collect(error);
+      }
+      pass.check();
+      return out;
+    },
+    measure(fn) {
+      pass.measured();
+      return fx.call(fn);
+    },
+    report(error) {
+      pass.collect(error);
+    },
+  };
+  return fx;
+}
+
+/** The same diffs with no pass: nothing is checked and every throw propagates.
+ *  Only the public `placeAnchored` uses it. */
+export const directFx: Fx = fxAt({
+  check: () => undefined,
+  measured: () => undefined,
+  collect: (error) => {
+    throw error;
+  },
+});

package/src/primitives/live-regions.ts

@@ -0,0 +1,83 @@
+import { el } from "../dom/el.js";
+
+export type Politeness = "polite" | "assertive";
+
+type RegionPair = Readonly<Record<Politeness, HTMLElement>>;
+
+interface Mount {
+  pair: RegionPair;
+  readonly owners: Set<symbol>;
+}
+
+const mounts = new WeakMap<HTMLElement, Mount>();
+
+function buildRegion(politeness: Politeness): HTMLElement {
+  return el("div", {
+    className: "uip-visually-hidden",
+    role: politeness === "assertive" ? "alert" : "status",
+    "aria-live": politeness,
+    "aria-atomic": "true",
+  });
+}
+
+function appendPair(host: HTMLElement): RegionPair {
+  const pair: RegionPair = { polite: buildRegion("polite"), assertive: buildRegion("assertive") };
+  host.append(pair.polite, pair.assertive);
+  return pair;
+}
+
+function removePair(pair: RegionPair): void {
+  pair.polite.remove();
+  pair.assertive.remove();
+}
+
+function isInside(pair: RegionPair, host: HTMLElement): boolean {
+  return pair.polite.parentElement === host && pair.assertive.parentElement === host;
+}
+
+/** The pair mounted in `host`, or `undefined` once its last owner released it
+ *  or either region has left it (an app clearing the host's children takes the
+ *  pair with them). */
+export function regionsOf(host: HTMLElement): RegionPair | undefined {
+  const mount = mounts.get(host);
+  return mount !== undefined && isInside(mount.pair, host) ? mount.pair : undefined;
+}
+
+/** `host`'s mount, with a pair appended as its last two children unless one is
+ *  still inside it. */
+function mount(host: HTMLElement): Mount {
+  let mount = mounts.get(host);
+  if (mount === undefined) {
+    mount = { pair: appendPair(host), owners: new Set() };
+    mounts.set(host, mount);
+  } else if (!isInside(mount.pair, host)) {
+    removePair(mount.pair);
+    mount.pair = appendPair(host);
+  }
+  return mount;
+}
+
+/** The owner that never releases. */
+const forLife = Symbol("live-region owner for the host's life");
+
+/** Give `host` a pair for the rest of its life, appending one as its last two
+ *  children unless one is still inside it. */
+export function keepRegions(host: HTMLElement): void {
+  mount(host).owners.add(forLife);
+}
+
+/** Hold `host`'s polite and assertive pair as a new owner, appending a pair
+ *  as its last two children unless one is still inside it. Returns this
+ *  owner's release: idempotent, it drops only this owner, and the pair leaves
+ *  `host` when its last owner releases. */
+export function acquireRegions(host: HTMLElement): () => void {
+  const held = mount(host);
+  const owner = Symbol("live-region owner");
+  held.owners.add(owner);
+  return () => {
+    held.owners.delete(owner);
+    if (held.owners.size === 0) {
+      removePair(held.pair);
+    }
+  };
+}

package/src/primitives/modal-host.ts

@@ -0,0 +1,214 @@
+// showModal() makes everything outside the topmost modal dialog's SUBTREE
+// inert regardless of stacking order, so chrome painted above it (the toast
+// stack, a popup panel) is still dead to clicks and hover unless re-hosted inside it.
+
+/** When `open` was last added to each dialog the observer saw. The platform exposes
+ *  no top-layer order, and document order is not it (a dialog built early and
+ *  opened last is on top), but showModal() adds `open` as the dialog enters the top
+ *  layer, and one observer delivers its records in the order they were made. A
+ *  dialog with no entry is one whose opening no observer saw: it ranks below every
+ *  stamped one. */
+const openedAt = new WeakMap<HTMLDialogElement, number>();
+let clock = 0;
+
+function rank(records: readonly MutationRecord[]): void {
+  let reopened = false;
+  for (const r of records) {
+    if (r.oldValue === null && r.target instanceof HTMLDialogElement) {
+      openedAt.set(r.target, ++clock);
+      observeRoot(r.target);
+      // A close and showModal() in one record batch leave the dialog :modal, so
+      // leftCovering() cannot see the close.
+      reopened ||= covering.has(r.target);
+      if (pendingClear !== null && isModal(r.target)) {
+        cover(r.target);
+      }
+    }
+  }
+  if (reopened || leftCovering()) {
+    uncover();
+  }
+}
+
+// Observing a node again replaces its options, so OPEN_RECORDS must cover OWN_OPEN:
+// a tracked dialog can also be the root of its tree.
+const OWN_OPEN: MutationObserverInit = {
+  attributes: true,
+  attributeFilter: ["open"],
+  attributeOldValue: true,
+};
+const OPEN_RECORDS: MutationObserverInit = { ...OWN_OPEN, subtree: true };
+
+// Started at load, an import-time effect by design: an opening made before it
+// is lost, since no platform API reports it later. package.json `sideEffects` lists
+// every module whose evaluation reaches this one, so an effect-only import keeps it.
+const additions = new MutationObserver(rank);
+additions.observe(document, OPEN_RECORDS);
+
+/** The open modals whose closing, reopening or removal uncovers what they hide, while
+ *  `pendingClear` waits for that. */
+const covering = new Set<HTMLDialogElement>();
+let pendingClear: (() => void) | null = null;
+// A modal removed from its tree leaves the top layer with no `open` record (HTML, the
+// dialog removing steps), so the parent of each node on its path up to the document is
+// watched. moveBefore() changes that path and keeps the modal in the top layer (DOM, the
+// move algorithm), and its record lands on the old path, so each record walks it again.
+const removals = new MutationObserver(() => {
+  if (leftCovering()) {
+    uncover();
+    return;
+  }
+  for (const dialog of covering) {
+    cover(dialog);
+  }
+});
+
+function cover(dialog: HTMLDialogElement): void {
+  covering.add(dialog);
+  let node: Node = dialog;
+  for (let parent = node.parentNode; parent !== null; parent = node.parentNode) {
+    removals.observe(parent, { childList: true });
+    node = parent instanceof ShadowRoot ? parent.host : parent;
+  }
+}
+
+function leftCovering(): boolean {
+  for (const dialog of covering) {
+    if (!isModal(dialog)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function uncover(): void {
+  const clear = pendingClear;
+  pendingClear = null;
+  covering.clear();
+  removals.disconnect();
+  clear?.();
+}
+
+/** The observed shadow roots, whose open dialogs `document` queries miss. */
+const shadowRoots = new Set<WeakRef<ShadowRoot>>();
+const observed = new WeakSet<Node>();
+/** The dialogs trackOpens tracks, wherever they are now. */
+const tracked = new Set<WeakRef<HTMLDialogElement>>();
+const isTracked = new WeakSet<HTMLDialogElement>();
+
+/** Each target still alive, dropping the collected ones. */
+function* alive<T extends object>(refs: Set<WeakRef<T>>): Generator<T> {
+  for (const ref of refs) {
+    const target = ref.deref();
+    if (target === undefined) {
+      refs.delete(ref);
+    } else {
+      yield target;
+    }
+  }
+}
+
+/** Observe the tree `dialog` is in now when that is not the document (a shadow root,
+ *  or a detached subtree), which the document's registration does not reach. */
+function observeRoot(dialog: HTMLDialogElement): void {
+  const root = dialog.getRootNode();
+  if (root === document || observed.has(root)) {
+    return;
+  }
+  observed.add(root);
+  additions.observe(root, OPEN_RECORDS);
+  if (root instanceof ShadowRoot) {
+    shadowRoots.add(new WeakRef(root));
+  }
+}
+
+/** Rank every opening of `dialog` from now on, wherever it moves, count it among the
+ *  open dialogs chrome can host into, and rank the later openings of any dialog in
+ *  the tree it is in now. Idempotent. */
+export function trackOpens(dialog: HTMLDialogElement): void {
+  if (!isTracked.has(dialog)) {
+    isTracked.add(dialog);
+    tracked.add(new WeakRef(dialog));
+    // An element's own registration follows it into any tree. A dialog observed as a
+    // root already has the options that cover it.
+    if (!observed.has(dialog)) {
+      additions.observe(dialog, OWN_OPEN);
+    }
+  }
+  observeRoot(dialog);
+}
+
+function isModal(dialog: HTMLDialogElement): boolean {
+  return dialog.matches(":modal");
+}
+
+/** Whether `x` opened after `y`; of two whose openings no observer saw, the later in
+ *  tree order (a fixed, arbitrary order across trees). */
+function openedAfter(x: HTMLDialogElement, y: HTMLDialogElement): boolean {
+  const ax = openedAt.get(x) ?? 0;
+  const ay = openedAt.get(y) ?? 0;
+  return ax !== ay
+    ? ax > ay
+    : (y.compareDocumentPosition(x) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0;
+}
+
+/** The newest-opened of `dialogs`, or `null` for none. */
+function newest(dialogs: readonly HTMLDialogElement[]): HTMLDialogElement | null {
+  let top: HTMLDialogElement | null = null;
+  for (const dialog of dialogs) {
+    if (top === null || openedAfter(dialog, top)) {
+      top = dialog;
+    }
+  }
+  return top;
+}
+
+/** Every open, connected dialog the library knows of: the document's, those of the
+ *  observed shadow roots, and the tracked ones wherever they are. */
+function knownOpen(): HTMLDialogElement[] {
+  const open = new Set(document.querySelectorAll<HTMLDialogElement>("dialog[open]"));
+  for (const root of alive(shadowRoots)) {
+    if (root.host.isConnected) {
+      for (const dialog of root.querySelectorAll<HTMLDialogElement>("dialog[open]")) {
+        open.add(dialog);
+      }
+    }
+  }
+  for (const dialog of alive(tracked)) {
+    if (dialog.open && dialog.isConnected) {
+      open.add(dialog);
+    }
+  }
+  return [...open];
+}
+
+/** The open `<dialog>` chrome should host into, or `null` when none is open: of
+ *  every open dialog the library knows of, the `:modal` one that opened last, the
+ *  one subtree showModal() leaves live; else, when none is `:modal`, the open one
+ *  that opened last. */
+export function topmostOpenDialog(): HTMLDialogElement | null {
+  rank(additions.takeRecords());
+  const open = knownOpen();
+  return newest(open.filter(isModal)) ?? newest(open);
+}
+
+/** Every dialog trackOpens tracks that is showing as a modal now. */
+export function trackedModals(): HTMLDialogElement[] {
+  return [...alive(tracked)].filter(isModal);
+}
+
+/** Call `clear` once when a modal open now, or opened later, closes, opens again or leaves
+ *  its tree, before the browser exposes what that modal hid; a later call replaces `clear`.
+ *  A modal no observer sees, one the helpers do not drive in a shadow root they never
+ *  reached, is not watched. */
+export function whenUncovered(clear: () => void): void {
+  // Called in the change's own task (as under fake timers), records not yet delivered
+  // belong to the callback this one replaces.
+  rank(additions.takeRecords());
+  pendingClear = clear;
+  for (const dialog of knownOpen()) {
+    if (isModal(dialog)) {
+      cover(dialog);
+    }
+  }
+}