@cplieger/ui 0.0.0 → 1.0.0-dev.1

package/src/primitives/dialog.ts

@@ -0,0 +1,263 @@
+/**
+ * dialog.ts — Thin behavior layer over the native `<dialog>` element. The
+ * platform gives us focus containment, the top layer, and Escape-to-close for
+ * free; this module adds backdrop-click dismissal (drag-safe) and a fade-out
+ * lifecycle via a namespaced `is-leaving` class before the element is closed.
+ *
+ * @module
+ */
+
+import { untracked } from "../signal/signal.js";
+
+import {
+  dialogEngine,
+  existingEngine,
+  type DialogEngine,
+  type DialogFacet,
+} from "./dialog-engine.js";
+import { SUPERSEDED, createDriver, ownedBinding } from "./owner.js";
+
+/** Which user gestures dismiss a wrapped `<dialog>`, an optional veto over
+ *  them, and a hook that runs once the fade-out has finished. All optional; by
+ *  default both backdrop and Escape dismiss it. */
+export interface DialogOptions {
+  /** Close when the backdrop is clicked. Default `true`. */
+  closeOnBackdrop?: boolean;
+  /** Close on Escape. Default `true`. */
+  closeOnEscape?: boolean;
+  /** Dismiss guard, consulted on every USER dismissal attempt (backdrop click,
+   *  Escape): return `false` to refuse it and keep the dialog open. The wiring
+   *  stays armed, so later attempts re-consult the guard. Perform any "why
+   *  not" feedback (a toast, a shake) inside the guard before returning.
+   *  Programmatic `close()` is unaffected. Omitted = always dismissible. */
+  canDismiss?: () => boolean;
+  /** Invoked once each time the dialog goes from shown to closed, whoever
+   *  closed it: the fade, `closeDialog`, or the browser. */
+  onClose?: () => void;
+}
+
+/** Handle on a wrapped `<dialog>`. The element is the caller's throughout: this
+ *  controller adds wiring, classes and the dialog's live-region pair, and creates
+ *  or removes no other node. The pair is appended as the dialog's last two children
+ *  at the first helper or controller call on it and stays for the dialog's life,
+ *  through closes and `dispose()`: render content into a child element, never by
+ *  replacing the dialog's children, or announcements miss it until the next open. */
+export interface DialogController {
+  /** Open as a platform modal, cancelling a leave fade still in flight so a
+   *  reopen mid-fade is safe. A no-op while already open. Throws as
+   *  `openDialog` does, and an `InvalidStateError` once `dispose()` has begun,
+   *  also from a handler that `dispose()` reaches. */
+  open(): void;
+  /** Close through the fade-out lifecycle. Programmatic, so `canDismiss` does
+   *  not apply. Does nothing once `dispose()` has begun. */
+  close(): void;
+  /** The `<dialog>` handed to `createDialog`, never a node this controller
+   *  made. Only the caller may remove it, and removing it neither unwires the
+   *  controller nor clears this reference: it keeps reading back a detached
+   *  node, listeners and all, until `dispose()` runs. */
+  readonly el: HTMLDialogElement;
+  /** Close the dialog at once if it is open (no fade, no `onClose`) and remove
+   *  the dismissal wiring and the `uip-dialog` class. The live-region pair stays. */
+  dispose(): void;
+}
+
+/** Open a native <dialog> as a modal, first putting back its live-region pair if
+ *  the app's render removed it, so `announce` reaches it while the rest of the page
+ *  is inert. Toasts and popups go to the modal opened last; announcements are written
+ *  to every open modal these helpers drive and to the root. A reopen during the leave
+ *  fade cancels it. Throws `showModal()`'s `InvalidStateError` for a disconnected
+ *  dialog or one showing as a popover, keeping only the pair, and an
+ *  `InvalidStateError` for the dialog of a disposed modal. */
+export function openDialog(dialog: HTMLDialogElement): void {
+  const engine = dialogEngine(dialog);
+  engine.open();
+  engine.flush();
+}
+
+/** Close a native <dialog> after a fade-out: add `is-leaving`, wait for
+ *  `transitionend` (or the fallback), then close and invoke `onClosed`. A
+ *  reopen cancels a pending close and drops its `onClosed`. On a closed dialog
+ *  `onClosed` runs at once, or, when called from code a change of that dialog
+ *  is running, as soon as that change finishes. */
+export function closeDialog(dialog: HTMLDialogElement, onClosed?: () => void): void {
+  const engine = dialogEngine(dialog);
+  engine.close(onClosed);
+  engine.flush();
+}
+
+/** @internal Install drag-safe backdrop-press detection on `dialog`, with no
+ *  ownership: `onPress` fires only when a press both starts and ends on the
+ *  dialog element itself. Returns the remover. */
+export function listenBackdrop(dialog: HTMLDialogElement, onPress: () => void): () => void {
+  let downOnDialog = false;
+  const onMouseDown = (e: MouseEvent): void => {
+    // A backdrop press targets the dialog element itself (content presses
+    // target a descendant), so a drag-select ending on the backdrop is not one.
+    downOnDialog = e.target === dialog;
+  };
+  const onMouseUp = (e: MouseEvent): void => {
+    const onBackdrop = e.target === dialog && downOnDialog;
+    downOnDialog = false;
+    if (onBackdrop) {
+      onPress();
+    }
+  };
+  dialog.addEventListener("mousedown", onMouseDown);
+  dialog.addEventListener("mouseup", onMouseUp);
+  return () => {
+    dialog.removeEventListener("mousedown", onMouseDown);
+    dialog.removeEventListener("mouseup", onMouseUp);
+  };
+}
+
+/** Wire drag-safe backdrop dismissal on a native <dialog>: `onDismiss` fires
+ *  only when a press both starts and ends on the dialog element itself.
+ *  Returns a cleanup fn that removes both listeners. */
+export function wireBackdropDismiss(dialog: HTMLDialogElement, onDismiss: () => void): () => void {
+  return ownedBinding((binding) => {
+    let remove: (() => void) | null = null;
+    const driver = createDriver<null>({
+      initial: null,
+      realize() {
+        remove ??= listenBackdrop(dialog, () => {
+          driver.act((fx) => {
+            fx.call(onDismiss);
+          });
+        });
+      },
+      terminal() {
+        remove?.();
+        remove = null;
+      },
+    });
+    return {
+      controller: binding.dispose,
+      start: () => {
+        driver.flush();
+      },
+      release: () => {
+        driver.release();
+      },
+    };
+  });
+}
+
+/** Throw unless `dialog` can take a new controller. Creates nothing. */
+function assertNoController(dialog: HTMLDialogElement): void {
+  const engine = existingEngine(dialog);
+  if (engine !== undefined && (engine.state.retired || engine.state.facet !== null)) {
+    throw new DOMException("The dialog already has a controller", "InvalidStateError");
+  }
+}
+
+/** Wrap an existing native <dialog> with backdrop + Escape dismissal and the
+ *  fade-out close lifecycle. Adds the `uip-dialog` class for the base skin.
+ *  Throws `InvalidStateError`, acquiring nothing, on a dialog that already
+ *  has a controller (a live `createDialog`, or a modal's `el`). */
+export function createDialog(dialog: HTMLDialogElement, opts?: DialogOptions): DialogController {
+  const o = untracked(() => ({
+    closeOnBackdrop: opts?.closeOnBackdrop ?? true,
+    closeOnEscape: opts?.closeOnEscape ?? true,
+    canDismiss: opts?.canDismiss,
+    onClose: opts?.onClose,
+  }));
+  assertNoController(dialog);
+
+  return ownedBinding((binding) => {
+    let engine: DialogEngine | null = null;
+    let disarm: (() => void) | null = null;
+    let reported: "shown" | "closed" = "closed";
+
+    const dismiss = (): void => {
+      const e = engine;
+      if (binding.ended || e?.phase !== "open") {
+        return;
+      }
+      const guard = o.canDismiss;
+      if (guard !== undefined) {
+        const answer = e.consult(guard);
+        if (answer === SUPERSEDED || !answer) {
+          return;
+        }
+      }
+      e.close();
+      e.flush();
+    };
+    const onCancel = (e: Event): void => {
+      // A nested `<input type=file>` fires a bubbling `cancel` when its picker
+      // is dismissed (https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/cancel_event);
+      // only the dialog's own `cancel` is an Escape.
+      if (e.target !== dialog) {
+        return;
+      }
+      // The platform closes at once after `cancel`; prevented, the fade runs instead.
+      e.preventDefault();
+      if (o.closeOnEscape) {
+        dismiss();
+      }
+    };
+
+    const facet: DialogFacet = {
+      prepare(fx) {
+        if (disarm === null) {
+          dialog.addEventListener("cancel", onCancel);
+          const removeBackdrop = o.closeOnBackdrop ? listenBackdrop(dialog, dismiss) : null;
+          disarm = () => {
+            dialog.removeEventListener("cancel", onCancel);
+            removeBackdrop?.();
+          };
+        }
+        fx.addClass(dialog, "uip-dialog");
+      },
+      notify(fx, d) {
+        const shown = d.phase !== "closed";
+        if (reported === "shown" && !shown) {
+          reported = "closed";
+          if (o.onClose !== undefined) {
+            fx.call(o.onClose);
+          }
+        } else if (shown) {
+          reported = "shown";
+        }
+      },
+      cleanup(fx) {
+        disarm?.();
+        disarm = null;
+        fx.removeClass(dialog, "uip-dialog");
+      },
+    };
+
+    return {
+      controller: {
+        el: dialog,
+        open: () => {
+          if (binding.ended || engine === null) {
+            throw new DOMException("The dialog controller is disposed", "InvalidStateError");
+          }
+          engine.open();
+          engine.flush();
+        },
+        close: () => {
+          if (!binding.ended && engine !== null) {
+            engine.close();
+            engine.flush();
+          }
+        },
+        dispose: binding.dispose,
+      },
+      start: () => {
+        const e = dialogEngine(dialog);
+        engine = e;
+        reported = e.phase === "closed" ? "closed" : "shown";
+        e.attach(facet);
+        e.flush();
+      },
+      release: () => {
+        if (engine !== null) {
+          engine.detach(facet);
+          engine.flush();
+        }
+      },
+    };
+  });
+}

package/src/primitives/disclosure.ts

@@ -0,0 +1,287 @@
+/**
+ * disclosure.ts — Animated collapsible (show/hide) region wired to a trigger,
+ * per the WAI-ARIA disclosure pattern. Headless: it wires two elements you
+ * supply — no DOM is created. The trigger gets button semantics
+ * (`aria-expanded`, Enter/Space when it isn't a native `<button>`) and is linked
+ * to the region via `aria-controls`; the region toggles `aria-hidden`.
+ *
+ * Height animates 0 <-> auto. Modern engines interpolate the `auto` keyword
+ * directly (`interpolate-size: allow-keywords`, set on the region in the base
+ * stylesheet); engines without it fall back to a measured `scrollHeight` px
+ * target. Both honor `prefers-reduced-motion` by skipping the tween.
+ *
+ * @module
+ */
+
+import { untracked } from "../signal/signal.js";
+
+import type { Fx } from "./fx.js";
+import { createDriver, ownedBinding } from "./owner.js";
+import { watchSettle } from "./transition.js";
+
+/** The initial open state, whether height changes tween, and the toggle hook.
+ *  All optional: a disclosure with no options starts collapsed, animates, and
+ *  reports nothing. */
+export interface DisclosureOptions {
+  /** Initial open state. Default `false`. */
+  open?: boolean;
+  /** Animate height changes. Default `true`. Ignored under reduced motion. */
+  animate?: boolean;
+  /** Invoked whenever the open state changes. `source` distinguishes a
+   *  user-initiated toggle (trigger click / Enter / Space) from a programmatic
+   *  one (`open()` / `close()` / `toggle()` on the controller) — the seam an
+   *  auto-collapse state machine needs to latch "the user took over". */
+  onToggle?: (open: boolean, source: DisclosureToggleSource) => void;
+}
+
+/** How a disclosure toggle was initiated: `"user"` = the wired trigger
+ *  (click / Enter / Space); `"api"` = a controller method. */
+export type DisclosureToggleSource = "user" | "api";
+
+/** Handle on a wired disclosure. Every method here reports as the `"api"`
+ *  toggle source, so an `onToggle` consumer can tell a controller call from a
+ *  trigger press. The only state driver in region-only mode (`trigger: null`). */
+export interface DisclosureController {
+  /** Expand the region. Does nothing once `dispose()` has begun, as do
+   *  `close()` and `toggle()`. */
+  open(): void;
+  close(): void;
+  toggle(): void;
+  readonly isOpen: boolean;
+  /** Unwire the trigger. An in-flight tween is cancelled and the height
+   *  settled (`auto` when open, `0` when collapsed) so no inline px height is
+   *  left frozen; the region keeps its current state, `aria-hidden` and
+   *  `inert` included. */
+  dispose(): void;
+}
+
+let idSeq = 0;
+
+function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  );
+}
+
+/** Whether the engine can transition `height` to/from the `auto` keyword. */
+function supportsInterpolateSize(): boolean {
+  return (
+    typeof CSS !== "undefined" &&
+    typeof CSS.supports === "function" &&
+    CSS.supports("interpolate-size", "allow-keywords")
+  );
+}
+
+/** Whether the page is rendering `el` at all. Measuring a region it does not
+ *  render to animate it is a forced render for a transition that cannot run.
+ *  No options object: `contentVisibilityAuto` would also catch a SKIPPED
+ *  `content-visibility: auto` region, which the next scroll makes relevant again. */
+function isRendered(el: HTMLElement): boolean {
+  return typeof el.checkVisibility !== "function" || el.checkVisibility();
+}
+
+/** Wire `trigger` (a button, or any element given button semantics) to `region`
+ *  as an animated disclosure. With `trigger: null` nothing is wired (no
+ *  aria-expanded, no click or keyboard handling) and only the controller
+ *  changes the open state; the region still animates and gets `aria-hidden`
+ *  plus `inert`. */
+export function createDisclosure(
+  trigger: HTMLElement | null,
+  region: HTMLElement,
+  opts?: DisclosureOptions,
+): DisclosureController {
+  const o = untracked(() => ({
+    animate: opts?.animate ?? true,
+    onToggle: opts?.onToggle,
+    open: opts?.open ?? false,
+  }));
+
+  interface State {
+    readonly open: boolean;
+    readonly source: DisclosureToggleSource;
+    /** The id of the open tween whose settle has fired. */
+    readonly settled: number;
+  }
+
+  return ownedBinding((binding) => {
+    const regionId = region.id === "" ? `uip-disclosure-${(++idSeq).toString()}` : region.id;
+    const isNativeButton = trigger instanceof HTMLButtonElement;
+    let listening = false;
+    let reported = o.open;
+    let tweenSeq = 0;
+    // The height is a sequence: `shown` is the state it was last driven
+    // toward, and `tween.step` advances after each write, so a restart resumes
+    // the step that did not finish.
+    const height: {
+      shown: boolean;
+      tween: {
+        readonly id: number;
+        readonly toOpen: boolean;
+        step: "from" | "to" | "armed";
+      } | null;
+      watch: (() => void) | null;
+    } = { shown: o.open, tween: null, watch: null };
+
+    const toggleTo = (next: boolean, source: DisclosureToggleSource): void => {
+      if (binding.ended) {
+        return;
+      }
+      driver.commit(
+        driver.state.open === next ? driver.state : { ...driver.state, open: next, source },
+      );
+    };
+    const onClick = (): void => {
+      toggleTo(!driver.state.open, "user");
+    };
+    const onKeyDown = (e: KeyboardEvent): void => {
+      if (e.key === "Enter" || e.key === " " || e.key === "Spacebar") {
+        // Space would scroll the page; Enter/Space both activate a button.
+        e.preventDefault();
+        toggleTo(!driver.state.open, "user");
+      }
+    };
+    const listen = (on: boolean): void => {
+      if (trigger === null || listening === on) {
+        return;
+      }
+      listening = on;
+      const method = on ? "addEventListener" : "removeEventListener";
+      trigger[method]("click", onClick);
+      if (!isNativeButton) {
+        trigger[method]("keydown", onKeyDown as EventListener);
+      }
+    };
+    const cancelWatch = (): void => {
+      height.watch?.();
+      height.watch = null;
+    };
+    const settle = (id: number): void => {
+      driver.commit({ ...driver.state, settled: id });
+    };
+
+    const driver = createDriver<State>({
+      initial: { open: o.open, source: "api", settled: 0 },
+      realize(fx, d) {
+        listen(true);
+        fx.addClass(region, "uip-disclosure-region");
+        if (region.id === "") {
+          fx.setProp(region, "id", regionId);
+        }
+        if (trigger !== null) {
+          fx.setAttr(trigger, "aria-controls", region.id);
+          if (!isNativeButton) {
+            if (!trigger.hasAttribute("role")) {
+              fx.setAttr(trigger, "role", "button");
+            }
+            if (!trigger.hasAttribute("tabindex")) {
+              fx.setAttr(trigger, "tabindex", "0");
+            }
+          }
+        }
+        reflect(fx, d.open);
+        if (height.shown !== d.open) {
+          cancelWatch();
+          height.shown = d.open;
+          const animated = o.animate && !prefersReducedMotion() && isRendered(region);
+          height.tween = animated ? { id: ++tweenSeq, toOpen: d.open, step: "from" } : null;
+        }
+        const tween = height.tween;
+        if (tween?.step === "from") {
+          // auto is not an animatable start on the fallback path, so measure first.
+          fx.setStyle(
+            region,
+            "height",
+            tween.toOpen ? "0px" : `${region.scrollHeight.toString()}px`,
+          );
+          tween.step = "to";
+        }
+        if (tween?.step === "to") {
+          // The start height is committed before the target, or both land in one frame.
+          region.getBoundingClientRect();
+          fx.setStyle(
+            region,
+            "height",
+            tween.toOpen
+              ? supportsInterpolateSize()
+                ? "auto"
+                : `${region.scrollHeight.toString()}px`
+              : "0px",
+          );
+          if (tween.toOpen) {
+            tween.step = "armed";
+          } else {
+            height.tween = null;
+          }
+        }
+        if (height.tween?.step === "armed") {
+          const armed = height.tween;
+          if (d.settled === armed.id) {
+            cancelWatch();
+            height.tween = null;
+          } else {
+            height.watch ??= watchSettle(region, () => {
+              settle(armed.id);
+            });
+          }
+        }
+        if (height.tween === null) {
+          fx.setStyle(region, "height", d.open ? "" : "0px");
+        }
+      },
+      notify(fx, d) {
+        if (reported !== d.open) {
+          reported = d.open;
+          const onToggle = o.onToggle;
+          if (onToggle !== undefined) {
+            fx.call(() => {
+              onToggle(d.open, d.source);
+            });
+          }
+        }
+      },
+      terminal(fx, d) {
+        listen(false);
+        cancelWatch();
+        height.tween = null;
+        reflect(fx, d.open);
+        fx.setStyle(region, "height", d.open ? "" : "0px");
+      },
+    });
+
+    const reflect = (fx: Fx, open: boolean): void => {
+      if (trigger !== null) {
+        fx.setAttr(trigger, "aria-expanded", open ? "true" : "false");
+      }
+      fx.setAttr(region, "aria-hidden", open ? "false" : "true");
+      // height:0 clips paint but keeps descendants keyboard-focusable, and
+      // aria-hidden on focusable content is invalid; `inert` removes both.
+      fx.setProp(region, "inert", !open);
+    };
+
+    return {
+      controller: {
+        get isOpen(): boolean {
+          return driver.state.open;
+        },
+        open(): void {
+          toggleTo(true, "api");
+        },
+        close(): void {
+          toggleTo(false, "api");
+        },
+        toggle(): void {
+          toggleTo(!driver.state.open, "api");
+        },
+        dispose: binding.dispose,
+      },
+      start: () => {
+        driver.flush();
+      },
+      release: () => {
+        driver.release();
+      },
+    };
+  });
+}