@0001-labs/design-system-1 0.3.0-alpha.13 → 0.3.0-alpha.15

package/DS1/0-face/copy-text.ts

@@ -0,0 +1,96 @@
+/**
+ * Copy text to the clipboard and say so in a toast, for pages with or
+ * without a framework.
+ *
+ * It writes with the Clipboard API, and where that is missing or refused (a
+ * page served over plain HTTP, an older browser) it copies from a hidden field
+ * instead. The toast is the shared word "Copied" in the page's language,
+ * shown by `<ds-toast>` where the page has one and by the page toaster
+ * otherwise; a failure says "Could not copy".
+ *
+ * It is small on its own: the page toaster (`./toaster.ts`) loads only when a
+ * toast is shown and nothing in the page draws toasts yet, so a page that
+ * copies with `toast: false`, or has `<ds-toast>`, never loads it. Import it
+ * from here, not from `./feedback.ts`, where the page needs nothing else.
+ */
+import { feedbackWord } from "./feedback-words";
+import { toast, toasterListening } from "./toast-queue";
+
+export interface CopyTextOptions {
+  /** The toast's words when it is copied; `false` shows no toast at all. "Copied" by default. */
+  toast?: string | false;
+}
+
+/** The open modal dialog, if any: the rest of the page is inert, so the hidden field goes in it. */
+function modalDialog(): HTMLDialogElement | null {
+  try {
+    return document.querySelector<HTMLDialogElement>("dialog:modal");
+  } catch {
+    return null;
+  }
+}
+
+/** The fallback: select the text in a hidden field and copy the selection. */
+function copyFromField(text: string): boolean {
+  if (typeof document === "undefined" || !document.body) return false;
+  const active = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+  const selection = document.getSelection();
+  const ranges = selection ? Array.from({ length: selection.rangeCount }, (_, index) => selection.getRangeAt(index)) : [];
+  const field = document.createElement("textarea");
+  field.value = text;
+  field.setAttribute("readonly", "");
+  field.setAttribute("aria-hidden", "true");
+  field.tabIndex = -1;
+  field.style.cssText = "position:fixed;top:0;left:0;width:1px;height:1px;margin:0;padding:0;border:0;opacity:0;pointer-events:none";
+  (modalDialog() ?? document.body).appendChild(field);
+  field.focus({ preventScroll: true });
+  field.select();
+  field.setSelectionRange(0, text.length);
+  let copied = false;
+  try {
+    copied = document.execCommand("copy");
+  } catch {
+    copied = false;
+  }
+  field.remove();
+  active?.focus({ preventScroll: true });
+  if (selection) {
+    selection.removeAllRanges();
+    for (const range of ranges) selection.addRange(range);
+  }
+  return copied;
+}
+
+/**
+ * Copy `text` and confirm it with a toast. Resolves to whether it was copied.
+ * Call it from the click or key press that asks for it: browsers allow writing
+ * to the clipboard only then.
+ */
+export async function copyText(text: string, options: CopyTextOptions = {}): Promise<boolean> {
+  let copied = false;
+  const clipboard = typeof navigator === "undefined" ? undefined : navigator.clipboard;
+  if (clipboard?.writeText) {
+    try {
+      await clipboard.writeText(text);
+      copied = true;
+    } catch {
+      copied = false;
+    }
+  }
+  if (!copied) copied = copyFromField(text);
+  if (options.toast !== false) await say(copied, copied ? options.toast ?? feedbackWord("Copied") : feedbackWord("Could not copy"));
+  return copied;
+}
+
+/** The toast, with the page toaster loaded first where nothing in the page draws toasts yet. */
+async function say(copied: boolean, words: string): Promise<void> {
+  if (!toasterListening()) {
+    try {
+      (await import("./load-toaster")).pageToaster();
+    } catch {
+      // No toaster could load: the copy itself still answers.
+    }
+  }
+  if (copied) toast.success(words);
+  else toast.error(words);
+}

package/DS1/0-face/device.ts

@@ -2,8 +2,10 @@
 // Device detection, context utilities, and responsive scaling
 
 import { signal } from "@lit-labs/signals";
-import { calculateScalingFactor as calculateScale, defaultScalingConfig, type ScalingConfig } from "./scaling";
-export type { ScalingConfig, ScalingMode } from "./scaling";
+import { applyScaling, calculateScalingFactor as calculateScale, defaultScalingConfig, detectMobileDevice, type ScalingConfig } from "./scaling";
+export type { ScalingConfig, ScalingMode, ScalingOptions, ScalingSnap } from "./scaling";
+// One rule for which screens scale, shared with pages that copy scaling.ts alone.
+export { applyScaling, detectMobileDevice, startScaling, toDevicePixel, toLayoutStep } from "./scaling";
 
 // ============================================================================
 // Types
@@ -32,38 +34,6 @@ export const scalingConfig = signal<ScalingConfig>(defaultScalingConfig);
 // Device Detection
 // ============================================================================
 
-/**
- * Comprehensive mobile device detection
- * Combines user agent detection, touch capability, and viewport size
- */
-export function detectMobileDevice(): boolean {
-  if (typeof navigator === "undefined" || typeof window === "undefined") {
-    return false;
-  }
-
-  const nav = navigator as any;
-  const win = window as any;
-  const ua: string =
-    (nav && (nav.userAgent || nav.vendor)) || (win && win.opera) || "";
-
-  // User agent based detection
-  const uaMatchesMobile =
-    /Mobile|Android|iP(ad|hone|od)|IEMobile|BlackBerry|Kindle|Silk-Accelerated|(hpw|web)OS|Opera M(obi|ini)|Windows Phone|Phone|Tablet/i.test(
-      ua
-    );
-
-  // Touch capability detection
-  const touchPoints = (nav && nav.maxTouchPoints) || 0;
-  const isTouchCapable = touchPoints > 1;
-
-  // Viewport detection
-  const narrowViewport = win
-    ? Math.min(win.innerWidth || 0, win.innerHeight || 0) <= 820
-    : false;
-
-  return uaMatchesMobile || (isTouchCapable && narrowViewport);
-}
-
 /**
  * Get detailed device information
  */
@@ -132,39 +102,19 @@ export function setScalingConfig(config: Partial<ScalingConfig>): void {
 
 /**
  * Update the scaling factor based on current viewport
- * Desktop always uses factor 1; mobile uses computed factor
+ * Desktop always uses factor 1; mobile uses computed factor (see scaling.ts)
  */
 export function updateScalingFactor(): void {
   if (typeof window === "undefined" || typeof document === "undefined") {
     return;
   }
 
-  const isMobile = detectMobileDevice();
-
-  // Desktop: always use factor 1
-  if (!isMobile) {
-    const factor = 1;
-    scalingFactor.set(factor);
-    document.documentElement.style.setProperty("--sf", factor.toString());
-    window.dispatchEvent(
-      new CustomEvent("scaling-changed", {
-        detail: { scalingFactor: factor, config: scalingConfig.get() },
-      })
-    );
-    return;
-  }
-
-  // Mobile: compute scaling based on viewport
-  const viewportWidth = document.documentElement.clientWidth;
   const config = scalingConfig.get();
-  const newFactor = calculateScalingFactor(viewportWidth, config);
-
-  scalingFactor.set(newFactor);
-  document.documentElement.style.setProperty("--sf", newFactor.toString());
-
+  const factor = applyScaling(config);
+  scalingFactor.set(factor);
   window.dispatchEvent(
     new CustomEvent("scaling-changed", {
-      detail: { scalingFactor: newFactor, config },
+      detail: { scalingFactor: factor, config },
     })
   );
 }

package/DS1/0-face/dialog-swipe.ts

@@ -0,0 +1,249 @@
+/**
+ * Swipe a sheet or a drawer away: a finger that drags a dialog towards the
+ * edge it came from moves it, and letting go far or fast enough dismisses it.
+ * `ds-dialog` binds it for `placement="sheet"`, `"end"` and `"start"`; a page
+ * without Lit binds its own `dialog.ds-dialog--sheet` (or `--end`, `--start`)
+ * with `bindDialogSwipe(dialog)`. Plain TypeScript with no framework.
+ *
+ * It follows the finger as touch does on Apple's platforms:
+ *
+ * - Touch alone; a mouse or a trackpad closes with Escape or the close button.
+ * - Ten pixels of movement before it decides, then it tracks the finger one
+ *   to one from where it was grabbed, a moving dialog included (it starts
+ *   from the dialog's place on screen, not from where it was going).
+ * - A drag along the content's own scroll is the content's: a sheet scrolled
+ *   down scrolls back up first, a horizontal strip in a drawer scrolls, and a
+ *   slider, a range input or anything marked `data-ds-dialog-no-swipe` keeps
+ *   its touches.
+ * - Dragged the other way, it gives a little and pulls back (rubber-banding).
+ * - On release it projects where the throw would come to rest (the
+ *   deceleration of a scroll, rate 0.998) and dismisses when that is past half
+ *   its size and the finger is not moving back; otherwise it settles home.
+ * - The backdrop fades as the dialog goes (`--ds-dialog-progress`).
+ *
+ * Dismissing asks first, as a close button does: the element sends
+ * `ds-close-request` with the reason `"swipe"`, the native frame a cancelable
+ * `ds-close-request` on the dialog, and closes it when no listener prevents
+ * that. Declined (a form with unsaved changes asking first), it settles home.
+ * The motion itself is dialog-placement.css's, in transform alone.
+ */
+
+export type DialogPlacement = "center" | "sheet" | "end" | "start";
+
+export interface DialogSwipeOptions {
+  /** Where the dialog stands, read at each touch; from its class or `data-ds-placement` by default. */
+  placement?: DialogPlacement | (() => DialogPlacement);
+  /**
+   * Called when a swipe would dismiss it. By default a cancelable
+   * `ds-close-request` (`detail.reason` `"swipe"`) on the dialog, then
+   * `dialog.close()` unless a listener prevented it. Still open two frames
+   * later, the dialog settles home.
+   */
+  onDismiss?: (dialog: HTMLDialogElement) => void;
+}
+
+/** Ten pixels before a touch is a drag, as the platforms wait. */
+const SLOP = 10;
+/** A scroll's deceleration: where a throw at this speed comes to rest. */
+const DECELERATION = 0.998;
+const project = (velocity: number) => ((velocity / 1000) * DECELERATION) / (1 - DECELERATION);
+/** Past its edge the dialog follows less the further it goes. */
+const rubberband = (overshoot: number, dimension: number, constant = 0.55) =>
+  (overshoot * dimension * constant) / (dimension + constant * Math.abs(overshoot));
+
+const PLACEMENTS = new Set<DialogPlacement>(["center", "sheet", "end", "start"]);
+
+/** A dialog's placement, from `data-ds-placement` or its `ds-dialog--` class. */
+export function dialogPlacement(dialog: HTMLDialogElement): DialogPlacement {
+  const marked = dialog.getAttribute("data-ds-placement") as DialogPlacement | null;
+  if (marked && PLACEMENTS.has(marked)) return marked;
+  for (const placement of ["sheet", "end", "start"] as const) if (dialog.classList.contains(`ds-dialog--${placement}`)) return placement;
+  return "center";
+}
+
+type Gesture = {
+  id: number;
+  x: number;
+  y: number;
+  /** Where the dialog stood when the finger came down, towards its edge. */
+  base: number;
+  /** How far the finger had moved when the drag began. */
+  start: number;
+  mode: "pending" | "drag" | "ignore";
+  offset: number;
+  samples: { time: number; offset: number }[];
+  target: EventTarget | null;
+  path: EventTarget[];
+};
+
+/** The axis the dialog leaves along, and the sign of the way out on it. */
+function direction(dialog: HTMLDialogElement, placement: DialogPlacement): { axis: "x" | "y"; sign: 1 | -1 } {
+  if (placement === "sheet") return { axis: "y", sign: 1 };
+  const rtl = dialog.ownerDocument.defaultView?.getComputedStyle(dialog).direction === "rtl";
+  const right = (placement === "end") !== rtl;
+  return { axis: "x", sign: right ? 1 : -1 };
+}
+
+/**
+ * True when the content under the finger would scroll for this drag, so it
+ * keeps the touch: a finger moving down on content scrolled down scrolls it
+ * back up first, and one moving up scrolls it on while there is more.
+ */
+function contentScrolls(path: EventTarget[], dialog: HTMLDialogElement, axis: "x" | "y", along: number): boolean {
+  const view = dialog.ownerDocument.defaultView;
+  for (const node of path) {
+    if (!(node instanceof Element)) continue;
+    const style = view?.getComputedStyle(node);
+    if (axis === "y") {
+      const scrolls = /auto|scroll/.test(style?.overflowY ?? "") && node.scrollHeight > node.clientHeight;
+      if (scrolls && (along > 0 ? node.scrollTop > 0 : node.scrollTop + node.clientHeight < node.scrollHeight - 1)) return true;
+    } else {
+      const scrolls = /auto|scroll/.test(style?.overflowX ?? "") && node.scrollWidth > node.clientWidth;
+      if (scrolls) return true;
+    }
+    if (node === dialog) break;
+  }
+  return false;
+}
+
+/** The dialog's place on screen along its axis, towards its edge, from its live transform. */
+function presented(dialog: HTMLDialogElement, axis: "x" | "y", sign: 1 | -1): number {
+  const view = dialog.ownerDocument.defaultView;
+  const transform = view?.getComputedStyle(dialog).transform;
+  if (!transform || transform === "none" || typeof DOMMatrixReadOnly === "undefined") return 0;
+  try {
+    const matrix = new DOMMatrixReadOnly(transform);
+    return sign * (axis === "y" ? matrix.m42 : matrix.m41);
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Let a finger swipe a sheet or drawer away. Returns the function that
+ * unbinds it and clears what it set on the dialog.
+ */
+export function bindDialogSwipe(dialog: HTMLDialogElement, options: DialogSwipeOptions = {}): () => void {
+  const placementNow = (): DialogPlacement => {
+    const given = typeof options.placement === "function" ? options.placement() : options.placement;
+    return given ?? dialogPlacement(dialog);
+  };
+  let gesture: Gesture | null = null;
+  let settleTimer = 0;
+  const view = dialog.ownerDocument.defaultView;
+  const frame = (callback: () => void) => (view?.requestAnimationFrame ? view.requestAnimationFrame(callback) : view?.setTimeout(callback, 16) ?? 0);
+
+  const write = (offset: number, size: number, sign: 1 | -1) => {
+    dialog.style.setProperty("--ds-dialog-drag", `${sign * offset}px`);
+    dialog.style.setProperty("--ds-dialog-progress", String(size > 0 ? Math.min(1, Math.max(0, offset / size)) : 0));
+  };
+  const clear = () => {
+    dialog.style.removeProperty("--ds-dialog-drag");
+    dialog.style.removeProperty("--ds-dialog-progress");
+    dialog.removeAttribute("data-ds-dialog-dragging");
+  };
+  /** Home: the stylesheet's transition takes it back from where it is. */
+  const settle = () => {
+    dialog.removeAttribute("data-ds-dialog-dragging");
+    dialog.style.setProperty("--ds-dialog-drag", "0px");
+    dialog.style.setProperty("--ds-dialog-progress", "0");
+  };
+
+  const dismiss = () => {
+    dialog.removeAttribute("data-ds-dialog-dragging");
+    if (options.onDismiss) options.onDismiss(dialog);
+    else {
+      const request = new CustomEvent("ds-close-request", { detail: { reason: "swipe" }, bubbles: true, composed: true, cancelable: true });
+      if (dialog.dispatchEvent(request)) dialog.close();
+    }
+    // A product may close it a moment later (a framework's state); declined, it goes home.
+    const token = ++settleTimer;
+    frame(() => frame(() => { if (token === settleTimer && dialog.open) settle(); }));
+  };
+
+  const onStart = (event: TouchEvent) => {
+    const placement = placementNow();
+    if (!dialog.open || placement === "center") return;
+    if (event.touches.length !== 1) {
+      if (gesture?.mode === "drag") settle();
+      gesture = null;
+      return;
+    }
+    const path = event.composedPath();
+    if (path.some(node => node instanceof Element && node.matches('[data-ds-dialog-no-swipe], input[type="range"], [role="slider"]'))) return;
+    const touch = event.touches[0]!;
+    const { axis, sign } = direction(dialog, placement);
+    gesture = { id: touch.identifier, x: touch.clientX, y: touch.clientY, base: Math.max(0, presented(dialog, axis, sign)), start: 0, mode: "pending", offset: 0, samples: [], target: event.target, path };
+  };
+
+  const onMove = (event: TouchEvent) => {
+    if (!gesture || gesture.mode === "ignore") return;
+    const touch = [...event.touches].find(each => each.identifier === gesture!.id);
+    if (!touch) return;
+    const placement = placementNow();
+    if (placement === "center") { gesture = null; return; }
+    const { axis, sign } = direction(dialog, placement);
+    const dx = touch.clientX - gesture.x, dy = touch.clientY - gesture.y;
+    const along = axis === "y" ? dy * sign : dx * sign;
+    const across = axis === "y" ? dx : dy;
+    if (gesture.mode === "pending") {
+      if (Math.hypot(dx, dy) < SLOP) return;
+      if (Math.abs(along) <= Math.abs(across) || contentScrolls(gesture.path, dialog, axis, along)) {
+        gesture.mode = "ignore";
+        return;
+      }
+      gesture.mode = "drag";
+      gesture.start = along;
+      settleTimer++;
+      dialog.setAttribute("data-ds-dialog-dragging", "");
+    }
+    event.preventDefault();
+    const rect = dialog.getBoundingClientRect();
+    const size = axis === "y" ? rect.height : rect.width;
+    const raw = gesture.base + along - gesture.start;
+    gesture.offset = raw < 0 ? rubberband(raw, size || 1) : raw;
+    write(gesture.offset, size, sign);
+    const time = event.timeStamp || (view?.performance?.now() ?? Date.now());
+    gesture.samples.push({ time, offset: gesture.offset });
+    while (gesture.samples.length > 2 && time - gesture.samples[0]!.time > 150) gesture.samples.shift();
+  };
+
+  const onEnd = (event: TouchEvent) => {
+    if (!gesture) return;
+    if ([...event.touches].some(each => each.identifier === gesture!.id)) return;
+    const ended = gesture;
+    gesture = null;
+    if (ended.mode !== "drag") return;
+    const placement = placementNow();
+    const { axis } = direction(dialog, placement === "center" ? "sheet" : placement);
+    const rect = dialog.getBoundingClientRect();
+    const size = axis === "y" ? rect.height : rect.width;
+    // The speed of the last tenth of a second: a finger held still before letting go throws nothing.
+    const now = event.timeStamp || (view?.performance?.now() ?? Date.now());
+    const recent = ended.samples.filter(sample => now - sample.time <= 100);
+    const first = recent[0], last = recent[recent.length - 1];
+    const elapsed = first && last ? last.time - first.time : 0;
+    const velocity = first && last && elapsed > 0 ? ((last.offset - first.offset) / elapsed) * 1000 : 0;
+    const resting = ended.offset + project(velocity);
+    if (event.type !== "touchcancel" && placement !== "center" && ended.offset > 0 && resting > size / 2 && velocity > -100) dismiss();
+    else settle();
+  };
+
+  // Open again: it starts from its edge, with nothing left of the last drag.
+  const observer = new MutationObserver(() => { if (dialog.open) { settleTimer++; gesture = null; clear(); } });
+  observer.observe(dialog, { attributes: true, attributeFilter: ["open"] });
+  dialog.addEventListener("touchstart", onStart, { passive: true });
+  dialog.addEventListener("touchmove", onMove, { passive: false });
+  dialog.addEventListener("touchend", onEnd, { passive: true });
+  dialog.addEventListener("touchcancel", onEnd, { passive: true });
+  return () => {
+    observer.disconnect();
+    dialog.removeEventListener("touchstart", onStart);
+    dialog.removeEventListener("touchmove", onMove);
+    dialog.removeEventListener("touchend", onEnd);
+    dialog.removeEventListener("touchcancel", onEnd);
+    settleTimer++;
+    gesture = null;
+    clear();
+  };
+}

package/DS1/0-face/dialogs.ts

@@ -0,0 +1,208 @@
+/**
+ * Dialogs that answer with a promise, in place of the browser's `alert()`,
+ * `confirm()` and `prompt()`, for pages without Lit or any other framework.
+ *
+ * Each is drawn on the native `dialog.ds-dialog` frame from `1-root/controls.css`
+ * (which the page loads) with its native buttons, `.ds-button--primary`,
+ * `--secondary` and `--danger`, and opened with `showModal()`, so the browser
+ * keeps the rest of the page inert behind it. Their words default to the
+ * shared words (OK, Cancel) in the page's language where the page loads the
+ * language module, and English otherwise (`./feedback-words.ts`).
+ *
+ * - Focus moves into the dialog when it opens, and back to what had it when it
+ *   closes.
+ * - Escape cancels; Enter in a prompt's field confirms it.
+ * - A click on the backdrop cancels, except on a destructive confirmation
+ *   (`danger`), which takes an answer.
+ * - Two never open at once: a dialog asked for while another is open waits
+ *   for it to close.
+ * - A dialog asked for in a click opens within that click, so a phone shows
+ *   its keyboard for a prompt's field.
+ */
+import { feedbackWord } from "./feedback-words";
+
+export interface AlertOptions {
+  title: string;
+  text?: string;
+  /** The button's words; the shared word "OK" by default. */
+  confirm?: string;
+}
+
+export interface ConfirmOptions {
+  title: string;
+  text?: string;
+  /** The confirming button's words; the shared word "OK" by default. Name the action when it has one ("Delete"). */
+  confirm?: string;
+  /** The cancelling button's words; the shared word "Cancel" by default. */
+  cancel?: string;
+  /** A destructive action: the confirming button in the danger colour, Cancel focused, and no backdrop dismissal. */
+  danger?: boolean;
+}
+
+export interface PromptOptions {
+  title: string;
+  text?: string;
+  /** The field's label, shown above it; without one, the title names the field. */
+  label?: string;
+  value?: string;
+  placeholder?: string;
+  confirm?: string;
+  cancel?: string;
+}
+
+type Kind = "alert" | "confirm" | "prompt";
+interface Spec {
+  kind: Kind;
+  title: string;
+  text?: string;
+  confirm: string;
+  cancel?: string;
+  danger?: boolean;
+  field?: { label?: string; value: string; placeholder?: string };
+}
+
+/* One dialog at a time; the next waits in line. */
+const waiting: Array<() => void> = [];
+let open = false;
+let count = 0;
+
+function inLine<T>(show: () => Promise<T>): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const start = () => {
+      open = true;
+      show().then(resolve, reject).finally(() => {
+        open = false;
+        waiting.shift()?.();
+      });
+    };
+    if (open) waiting.push(start);
+    else start();
+  });
+}
+
+/** The element with focus, inside open shadow roots too. */
+function focused(): HTMLElement | null {
+  let active = document.activeElement;
+  while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement;
+  return active instanceof HTMLElement ? active : null;
+}
+
+function element<K extends keyof HTMLElementTagNameMap>(name: K, attributes: Record<string, string> = {}, text?: string): HTMLElementTagNameMap[K] {
+  const node = document.createElement(name);
+  for (const [key, value] of Object.entries(attributes)) node.setAttribute(key, value);
+  if (text !== undefined) node.textContent = text;
+  return node;
+}
+
+/** Answers `true` for the confirming button, `false` for Cancel, Escape and the backdrop; a prompt answers its text. */
+function show(spec: Spec): Promise<boolean | string | null> {
+  return new Promise(resolve => {
+    const id = `ds-feedback-${++count}`;
+    const opener = focused();
+    const dialog = element("dialog", {
+      class: "ds-dialog",
+      role: spec.kind === "prompt" ? "dialog" : "alertdialog",
+      "aria-labelledby": `${id}-title`,
+      "data-ds-feedback": spec.kind,
+    });
+    const header = element("div", { "data-ds-dialog": "header" });
+    header.appendChild(element("h2", { id: `${id}-title`, "data-ds-dialog": "title" }, spec.title));
+    if (spec.text) {
+      header.appendChild(element("p", { id: `${id}-text`, "data-ds-dialog": "description" }, spec.text));
+      dialog.setAttribute("aria-describedby", `${id}-text`);
+    }
+    dialog.appendChild(header);
+
+    let input: HTMLInputElement | undefined;
+    if (spec.field) {
+      const field = element("div", { "data-ds-dialog": "field" });
+      input = element("input", { id: `${id}-field`, class: "ds-input", type: "text", autocomplete: "off" });
+      input.value = spec.field.value;
+      if (spec.field.placeholder) input.placeholder = spec.field.placeholder;
+      if (spec.field.label) field.appendChild(element("label", { for: input.id, "data-ds-dialog": "label" }, spec.field.label));
+      else input.setAttribute("aria-labelledby", `${id}-title`);
+      field.appendChild(input);
+      dialog.appendChild(field);
+    }
+
+    const footer = element("div", { "data-ds-dialog": "footer" });
+    const cancel = spec.cancel === undefined ? undefined : element("button", { type: "button", class: "ds-button ds-button--secondary", value: "cancel" }, spec.cancel);
+    const confirm = element("button", { type: "button", class: spec.danger ? "ds-button ds-button--secondary ds-button--danger" : "ds-button ds-button--primary", value: "confirm" }, spec.confirm);
+    if (cancel) footer.appendChild(cancel);
+    footer.appendChild(confirm);
+    dialog.appendChild(footer);
+
+    const declined = spec.kind === "prompt" ? null : false;
+    let settled = false;
+    const finish = (confirmed: boolean) => {
+      if (settled) return;
+      settled = true;
+      if (dialog.open) dialog.close();
+      dialog.remove();
+      if (opener?.isConnected) opener.focus({ preventScroll: true });
+      resolve(spec.kind === "alert" ? true : confirmed ? (input ? input.value : true) : declined);
+    };
+
+    confirm.addEventListener("click", () => finish(true));
+    cancel?.addEventListener("click", () => finish(false));
+    input?.addEventListener("keydown", event => {
+      if (event.key !== "Enter" || event.isComposing || event.shiftKey || event.altKey || event.metaKey || event.ctrlKey) return;
+      event.preventDefault();
+      finish(true);
+    });
+    dialog.addEventListener("cancel", event => { event.preventDefault(); finish(false); });
+    // The browser can still close it (a second Escape): that is a cancel too.
+    dialog.addEventListener("close", () => finish(false));
+
+    // The backdrop is the dialog itself, outside its box; a press must start and end there.
+    const outside = (event: MouseEvent) => {
+      if (event.target !== dialog) return false;
+      const box = dialog.getBoundingClientRect();
+      return event.clientX < box.left || event.clientX > box.right || event.clientY < box.top || event.clientY > box.bottom;
+    };
+    let pressedOutside = false;
+    if (!spec.danger) {
+      dialog.addEventListener("pointerdown", event => { pressedOutside = event.button === 0 && outside(event); });
+      dialog.addEventListener("click", event => {
+        if (pressedOutside && outside(event)) finish(false);
+        pressedOutside = false;
+      });
+    }
+
+    const first = input ?? (spec.danger ? cancel : undefined) ?? confirm;
+    first.setAttribute("autofocus", "");
+    document.body.appendChild(dialog);
+    try {
+      dialog.showModal();
+    } catch {
+      dialog.setAttribute("open", "");
+    }
+    first.focus();
+    input?.select();
+  });
+}
+
+/** In place of `alert()`: a message with one button. Resolves when it is dismissed. */
+export function alert(options: AlertOptions | string): Promise<void> {
+  const { title, text, confirm } = typeof options === "string" ? { title: options } as AlertOptions : options;
+  if (typeof document === "undefined") return Promise.resolve();
+  return inLine(() => show({ kind: "alert", title, text, confirm: confirm ?? feedbackWord("OK") })).then(() => undefined);
+}
+
+/** In place of `confirm()`: resolves to `true` when confirmed, `false` otherwise. */
+export function confirm(options: ConfirmOptions | string): Promise<boolean> {
+  const { title, text, confirm: yes, cancel, danger } = typeof options === "string" ? { title: options } as ConfirmOptions : options;
+  if (typeof document === "undefined") return Promise.resolve(false);
+  return inLine(() => show({ kind: "confirm", title, text, confirm: yes ?? feedbackWord("OK"), cancel: cancel ?? feedbackWord("Cancel"), danger })).then(answer => answer === true);
+}
+
+/** In place of `prompt()`: resolves to the text written, or `null` when cancelled. */
+export function prompt(options: PromptOptions | string): Promise<string | null> {
+  const { title, text, label, value = "", placeholder, confirm: yes, cancel } = typeof options === "string" ? { title: options } as PromptOptions : options;
+  if (typeof document === "undefined") return Promise.resolve(null);
+  return inLine(() => show({
+    kind: "prompt", title, text,
+    confirm: yes ?? feedbackWord("OK"), cancel: cancel ?? feedbackWord("Cancel"),
+    field: { label, value, placeholder },
+  })).then(answer => typeof answer === "string" ? answer : null);
+}