components/dialog/dialog.ts

Functions

Imports

It imports no other module of this repo. Imported by components/approval-sheet/approval-sheet.ts, components/command-menu/command-menu.ts, components/confirm-dialog/confirm-dialog.ts, components/detail-panel/detail-panel.ts, components/dialog/dialog.react.tsx, components/media/media.react.tsx, components/media/media.ts, components/shell/shell.ts, components/shortcuts/shortcuts.ts, components/site-header/site-header.ts.

Source

1// The dialog: one native <dialog> opened with showModal(), shared by every Capsomer overlay
2// (confirm dialog, detail panel, command menu, shortcut sheet, the phone's More sheet). The
3// platform gives the top layer, the inert page behind it, the focus trap and Esc; this module
4// adds what it does not: focus placed on open and handed back on close, a click on the
5// backdrop that closes (unless the dialog is locked or busy), Esc held while a request runs,
6// an address entry that Back takes away, and a keyboard stop on a body that scrolls.
7// No framework; the React wrapper and the other overlays call the same functions.
8
9// ---------------------------------------------------------------------------------------
10// Helpers every overlay shares (confirm-dialog.ts re-exports the first six for 0.1 imports).
11
12const openers = new WeakMap<HTMLDialogElement, Element | null>();
13
14// Remembers what had focus before the dialog opened, to hand focus back on close.
15export function rememberOpener(dialog: HTMLDialogElement, opener: Element | null = document.activeElement): void {
16  openers.set(dialog, opener);
17}
18
19// Where focus goes when the opener has gone (a revoked agent loses its Revoke button): the
20// dialog's data-cap-return selector, the given fallback, the Close button of another dialog
21// that is still open behind this one (a detail panel), then the page's main region.
22function fallbackFor(dialog: HTMLDialogElement, fallback?: HTMLElement | null): HTMLElement[] {
23  const sel = dialog.dataset.capReturn;
24  const named = sel ? document.querySelector<HTMLElement>(sel) : null;
25  let behind: HTMLElement | null = null;
26  for (const d of document.querySelectorAll<HTMLDialogElement>("dialog[open]")) {
27    if (d !== dialog) behind = d.querySelector<HTMLElement>("[data-cap-part='close']") ?? behind;
28  }
29  return [named, fallback ?? null, behind, document.querySelector<HTMLElement>("main")].filter((x): x is HTMLElement => !!x);
30}
31
32// Hands focus back after a dialog closes. After the next frame, so whatever the action
33// changed has rendered first (a revoked agent's row, and its button, may be gone). Only when
34// focus is lost: if the browser already restored it, or a command opened another dialog,
35// that focus stands.
36export function returnFocus(dialog: HTMLDialogElement, fallback?: HTMLElement | null): void {
37  const from = openers.get(dialog);
38  openers.delete(dialog);
39  requestAnimationFrame(() => {
40    const now = document.activeElement;
41    const lost = !now || now === document.body || !now.isConnected || dialog.contains(now);
42    if (!lost) return;
43    const candidates: HTMLElement[] = [];
44    if (from instanceof HTMLElement && from.isConnected && from !== document.body) candidates.push(from);
45    candidates.push(...fallbackFor(dialog, fallback));
46    for (const el of candidates) {
47      el.focus();
48      if (document.activeElement === el) return;
49    }
50  });
51}
52
53// True when a mouse event landed on the dialog's backdrop rather than its content.
54export function isBackdropClick(dialog: HTMLDialogElement, e: MouseEvent): boolean {
55  if (e.target !== dialog) return false;
56  const r = dialog.getBoundingClientRect();
57  return e.clientX < r.left || e.clientX > r.right || e.clientY < r.top || e.clientY > r.bottom;
58}
59
60// The text of a thrown value, for the error shown inside a dialog.
61export function errorText(e: unknown): string {
62  if (e instanceof Error && e.message) return e.message;
63  if (typeof e === "string" && e) return e;
64  return "Something went wrong and nothing says what.";
65}
66
67let seq = 0;
68export function uid(prefix: string): string {
69  seq += 1;
70  return `${prefix}-${seq}`;
71}
72
73// A dialog is busy while its action runs: aria-busy on the dialog. Esc, Close, Cancel and the
74// backdrop all refuse until it is cleared.
75export function isBusy(dialog: HTMLDialogElement): boolean {
76  return dialog.getAttribute("aria-busy") === "true";
77}
78
79// Sets or clears busy. The Close and Cancel parts say so with aria-disabled (not disabled, so
80// focus stays where it was).
81export function setDialogBusy(dialog: HTMLDialogElement, on: boolean): void {
82  for (const el of dialog.querySelectorAll<HTMLElement>("[data-cap-part='close'], [data-cap-part='cancel']")) {
83    if (on) el.setAttribute("aria-disabled", "true");
84    else el.removeAttribute("aria-disabled");
85  }
86  if (on) dialog.setAttribute("aria-busy", "true");
87  else dialog.removeAttribute("aria-busy");
88}
89
90// True when a click outside the dialog must not close it: it is locked, it is an alert
91// dialog (one that asks a question the person must answer), or it is busy.
92export function isLocked(dialog: HTMLDialogElement): boolean {
93  return dialog.hasAttribute("data-cap-modal-lock") || dialog.getAttribute("role") === "alertdialog" || isBusy(dialog);
94}
95
96// ---------------------------------------------------------------------------------------
97// Drag to dismiss a sheet (Vaul). The header of a bottom, right or left sheet is its handle:
98// it follows the pointer toward the sheet's edge, and on release the sheet closes, as Close
99// would, when it went past a third of its size or was flung (faster than 0.5 px a ms);
100// otherwise it springs back. Not while the dialog is locked or busy, nor under reduced motion;
101// Esc, Close and focus return are unchanged.
102
103// Whether a released drag dismisses: past a third of the sheet, or flung toward its edge.
104function dragDismisses(moved: number, size: number, velocity: number): boolean {
105  return moved > size / 3 || (moved > 16 && velocity > 0.5);
106}
107
108function wireDrag(dialog: HTMLDialogElement): () => void {
109  let drag: { id: number; head: HTMLElement; x: number; y: number; dir: [number, number]; size: number; moved: number; t: number; v: number; on: boolean } | null = null;
110  const place = (px: number, dir: [number, number]) => {
111    dialog.style.translate = `${px * dir[0]}px ${px * dir[1]}px`;
112    dialog.style.setProperty("--cap-drag", String(drag ? Math.min(1, px / drag.size) : 0));
113  };
114  const onDown = (e: PointerEvent) => {
115    const placement = dialog.dataset.placement;
116    const head = (e.target as Element).closest?.<HTMLElement>(".cap-dialog-header");
117    if (e.button !== 0 || !head || head.closest("dialog") !== dialog || !dialog.open) return;
118    if (!["bottom", "right", "left"].includes(placement ?? "") || isLocked(dialog) || matchMedia("(prefers-reduced-motion: reduce)").matches) return;
119    if ((e.target as Element).closest("a, button, input, select, textarea, [contenteditable]")) return;
120    const r = dialog.getBoundingClientRect();
121    // Toward the edge it sits on, whatever the writing direction.
122    const dir: [number, number] = placement === "bottom" ? [0, 1] : r.left < innerWidth - r.right ? [-1, 0] : [1, 0];
123    drag = { id: e.pointerId, head, x: e.clientX, y: e.clientY, dir, size: placement === "bottom" ? r.height : r.width, moved: 0, t: e.timeStamp, v: 0, on: false };
124    head.setPointerCapture(e.pointerId);
125  };
126  const onMove = (e: PointerEvent) => {
127    if (!drag || e.pointerId !== drag.id) return;
128    const along = (e.clientX - drag.x) * drag.dir[0] + (e.clientY - drag.y) * drag.dir[1];
129    // A press that has not moved 4 px is still a click.
130    if (!drag.on && Math.abs(along) < 4) return;
131    drag.on = true;
132    dialog.dataset.capDragging = "";
133    const moved = Math.max(0, along);
134    const dt = e.timeStamp - drag.t;
135    if (dt > 0) drag.v = (moved - drag.moved) / dt;
136    drag.moved = moved;
137    drag.t = e.timeStamp;
138    place(moved, drag.dir);
139  };
140  const onUp = (e: PointerEvent) => {
141    if (!drag || e.pointerId !== drag.id) return;
142    const d = drag;
143    drag = null;
144    if (d.head.hasPointerCapture(e.pointerId)) d.head.releasePointerCapture(e.pointerId);
145    if (!d.on) return;
146    delete dialog.dataset.capDragging;
147    const css = getComputedStyle(dialog);
148    const ease = (name: string) => css.getPropertyValue(name).trim() || "ease-out";
149    const from = `${d.moved * d.dir[0]}px ${d.moved * d.dir[1]}px`;
150    dialog.style.removeProperty("translate");
151    dialog.style.removeProperty("--cap-drag");
152    // A pointer that stopped before letting go was not flung.
153    const v = e.timeStamp - d.t > 100 ? 0 : d.v;
154    if (e.type === "pointerup" && dragDismisses(d.moved, d.size, v)) {
155      // On out of the edge while it fades, then gone; the close is Close's, so focus returns.
156      const off = dialog.animate({ translate: [from, `${d.size * d.dir[0]}px ${d.size * d.dir[1]}px`] }, { duration: parseFloat(css.getPropertyValue("--dur-fast")) || 100, easing: ease("--ease-out"), fill: "forwards" });
157      off.onfinish = () => off.cancel();
158      dialog.close("drag");
159    } else {
160      dialog.animate({ translate: [from, "0px 0px"] }, { duration: parseFloat(css.getPropertyValue("--dur-slow")) || 400, easing: ease("--ease-spring") });
161    }
162  };
163  dialog.addEventListener("pointerdown", onDown);
164  dialog.addEventListener("pointermove", onMove);
165  dialog.addEventListener("pointerup", onUp);
166  dialog.addEventListener("pointercancel", onUp);
167  return () => {
168    dialog.removeEventListener("pointerdown", onDown);
169    dialog.removeEventListener("pointermove", onMove);
170    dialog.removeEventListener("pointerup", onUp);
171    dialog.removeEventListener("pointercancel", onUp);
172  };
173}
174
175// ---------------------------------------------------------------------------------------
176// Opening and closing.
177
178export interface DialogOptions {
179  // Pushes "#<prefix>-<id>" so Back closes the dialog. Default: the dialog's data-cap-history.
180  history?: boolean;
181  // Where focus goes on open. Default: the [autofocus] element; for an alert or destructive
182  // dialog, Cancel; otherwise the first control.
183  focus?: HTMLElement | null;
184  // Where focus goes on close when the opener has gone.
185  returnTo?: HTMLElement | null;
186}
187
188interface State {
189  opts: DialogOptions;
190  pushed: boolean;
191  onPop: (() => void) | null;
192  observer: ResizeObserver | null;
193  down: boolean;
194}
195const states = new WeakMap<HTMLDialogElement, State>();
196
197function stateOf(dialog: HTMLDialogElement): State {
198  let s = states.get(dialog);
199  if (!s) {
200    s = { opts: {}, pushed: false, onPop: null, observer: null, down: false };
201    states.set(dialog, s);
202  }
203  return s;
204}
205
206// The address a history-entry dialog pushes: data-cap-history may name the prefix
207// ("detail" gives #detail-<id>); the id is data-cap-history-id, data-cap-detail-id or the
208// dialog's id.
209export function historyHash(dialog: HTMLDialogElement): string {
210  const prefix = dialog.dataset.capHistory || "dialog";
211  return `#${prefix}-${dialog.dataset.capHistoryId ?? dialog.dataset.capDetailId ?? dialog.id}`;
212}
213
214const FOCUSABLE = "a[href], button, input:not([type='hidden']), select, textarea, summary, [tabindex]";
215
216function canFocus(el: HTMLElement): boolean {
217  if (el.matches(":disabled") || el.closest("[hidden], [inert]")) return false;
218  if (el.getAttribute("tabindex") === "-1") return false;
219  return el.getClientRects().length > 0;
220}
221
222// Puts focus where a person starts: the given element, the [autofocus] one, Cancel when the
223// dialog is an alert or marked destructive (Enter on arrival must not do the damage), else
224// the first control that is not the Close button or the scrolling body, else Close, the body,
225// the dialog itself.
226export function focusInitial(dialog: HTMLDialogElement, target?: HTMLElement | null): void {
227  const cancel = dialog.querySelector<HTMLElement>("[data-cap-part='cancel']");
228  const destructive = dialog.getAttribute("role") === "alertdialog" || dialog.hasAttribute("data-cap-destructive");
229  const all = [...dialog.querySelectorAll<HTMLElement>(FOCUSABLE)].filter(canFocus);
230  const plain = all.filter((el) => el.dataset.capPart !== "close" && !el.hasAttribute("data-cap-scroll"));
231  const choice =
232    target ??
233    dialog.querySelector<HTMLElement>("[autofocus]") ??
234    (destructive && cancel && canFocus(cancel) ? cancel : null) ??
235    plain[0] ??
236    dialog.querySelector<HTMLElement>("[data-cap-part='close']") ??
237    all[0] ??
238    dialog;
239  choice.focus();
240  if (document.activeElement !== choice) dialog.focus();
241}
242
243// A body that scrolls must be reachable by keyboard: it takes tabindex="0" while it overflows
244// (and gives it back when it does not), so arrow keys scroll it.
245export function syncScroll(dialog: HTMLDialogElement): void {
246  const body = dialog.querySelector<HTMLElement>(".cap-dialog-body");
247  if (!body) return;
248  const over = body.scrollHeight > body.clientHeight + 1;
249  if (over && !body.hasAttribute("tabindex")) {
250    body.tabIndex = 0;
251    body.dataset.capScroll = "";
252  } else if (!over && body.hasAttribute("data-cap-scroll")) {
253    body.removeAttribute("tabindex");
254    delete body.dataset.capScroll;
255  }
256}
257
258// Wires one dialog: a click on a Close or Cancel part, a click on the backdrop, Esc held
259// while busy, and what happens on close (the address entry, focus back to the opener).
260// Returns a function that unwires it. Idempotent for a dialog that is already wired.
261export function wireDialog(dialog: HTMLDialogElement, opts: DialogOptions = {}): () => void {
262  const s = stateOf(dialog);
263  s.opts = { ...s.opts, ...opts };
264  if (dialog.dataset.capReady !== undefined && dialog.dataset.capWired !== undefined) return () => undefined;
265  dialog.dataset.capReady = "";
266  dialog.dataset.capWired = "";
267  if (dialog.hasAttribute("data-cap-alert") && !dialog.hasAttribute("role")) dialog.setAttribute("role", "alertdialog");
268
269  // A press that starts inside the dialog and ends on the backdrop (selecting text) is not a
270  // click on the backdrop.
271  const onDown = (e: MouseEvent) => {
272    s.down = isBackdropClick(dialog, e);
273    // A locked dialog keeps focus where it was: the browser would move it to the dialog.
274    if (s.down && isLocked(dialog)) e.preventDefault();
275  };
276  const onClick = (e: MouseEvent) => {
277    const t = e.target;
278    const closer = t instanceof Element ? t.closest<HTMLElement>("[data-cap-part='close'], [data-cap-part='cancel']") : null;
279    if (closer && dialog.contains(closer)) {
280      if (isBusy(dialog)) return;
281      // A Cancel that is a link (so it works with no script) closes the modal instead of leaving.
282      if (closer instanceof HTMLAnchorElement) e.preventDefault();
283      return dialog.close(closer.dataset.capPart);
284    }
285    const wasDown = s.down;
286    s.down = false;
287    if (wasDown && isBackdropClick(dialog, e) && !isLocked(dialog)) dialog.close("backdrop");
288  };
289  // Esc while a request is in flight would hide its answer. The keydown is held as well as the
290  // cancel event, because a browser may skip a cancel event that the page refused once.
291  const onCancel = (e: Event) => {
292    if (isBusy(dialog)) e.preventDefault();
293  };
294  const onKey = (e: KeyboardEvent) => {
295    if (e.key === "Escape" && isBusy(dialog)) e.preventDefault();
296    if (e.key !== "Tab" || e.altKey || e.ctrlKey || e.metaKey) return;
297    // Tab past the last control comes back to the first (and the reverse), so focus never
298    // leaves for the browser's own controls: the page behind is inert.
299    const stops = [...dialog.querySelectorAll<HTMLElement>(FOCUSABLE)].filter(canFocus);
300    const first = stops[0];
301    const last = stops[stops.length - 1];
302    if (!first || !last) return;
303    const at = document.activeElement;
304    if (e.shiftKey && (at === first || at === dialog)) {
305      e.preventDefault();
306      last.focus();
307    } else if (!e.shiftKey && at === last) {
308      e.preventDefault();
309      first.focus();
310    }
311  };
312  // A <form method="dialog"> closes natively; while busy it must not.
313  const onSubmit = (e: SubmitEvent) => {
314    if (isBusy(dialog) && (e.target as HTMLFormElement | null)?.method === "dialog") e.preventDefault();
315  };
316  const onClose = () => {
317    // A close event queued before the dialog was opened again is stale.
318    if (dialog.open) return;
319    s.observer?.disconnect();
320    s.observer = null;
321    if (s.onPop) window.removeEventListener("popstate", s.onPop);
322    s.onPop = null;
323    // Closed by Esc or Close: take back the entry the dialog pushed, so Back goes where it
324    // went before.
325    if (s.pushed) {
326      s.pushed = false;
327      history.back();
328    }
329    returnFocus(dialog, s.opts.returnTo);
330  };
331
332  dialog.addEventListener("mousedown", onDown);
333  dialog.addEventListener("click", onClick);
334  dialog.addEventListener("cancel", onCancel);
335  dialog.addEventListener("keydown", onKey);
336  dialog.addEventListener("submit", onSubmit);
337  dialog.addEventListener("close", onClose);
338  const unDrag = wireDrag(dialog);
339  return () => {
340    unDrag();
341    dialog.removeEventListener("mousedown", onDown);
342    dialog.removeEventListener("click", onClick);
343    dialog.removeEventListener("cancel", onCancel);
344    dialog.removeEventListener("keydown", onKey);
345    dialog.removeEventListener("submit", onSubmit);
346    dialog.removeEventListener("close", onClose);
347    s.observer?.disconnect();
348    s.observer = null;
349    delete dialog.dataset.capReady;
350    delete dialog.dataset.capWired;
351  };
352}
353
354// Opens a dialog from the control that asked for it, remembering that control. Focus is
355// placed (see focusInitial); with history, "#<prefix>-<id>" is pushed so Back closes it.
356export function openDialog(dialog: HTMLDialogElement, opener: Element | null = document.activeElement, opts: DialogOptions = {}): void {
357  if (dialog.open && dialog.matches(":modal")) return;
358  wireDialog(dialog, opts);
359  const s = stateOf(dialog);
360  rememberOpener(dialog, opener);
361  // A dialog left open without showModal() (written with the open attribute) is not modal:
362  // drop the attribute so showModal() can run.
363  if (dialog.open) dialog.removeAttribute("open");
364  dialog.showModal();
365  focusInitial(dialog, s.opts.focus);
366  syncScroll(dialog);
367  s.observer?.disconnect();
368  if (typeof ResizeObserver !== "undefined") {
369    s.observer = new ResizeObserver(() => syncScroll(dialog));
370    s.observer.observe(dialog);
371    const body = dialog.querySelector(".cap-dialog-body");
372    if (body) s.observer.observe(body);
373  }
374  const useHistory = s.opts.history ?? dialog.hasAttribute("data-cap-history");
375  if (!useHistory) return;
376  history.pushState({ capDialog: dialog.dataset.capHistoryId ?? dialog.dataset.capDetailId ?? dialog.id }, "", historyHash(dialog));
377  s.pushed = true;
378  s.onPop = () => {
379    // Back: the entry is already gone, so closing must not go back again.
380    s.pushed = false;
381    if (dialog.open) dialog.close();
382  };
383  window.addEventListener("popstate", s.onPop);
384}
385
386export function closeDialog(dialog: HTMLDialogElement, returnValue?: string): void {
387  if (dialog.open) dialog.close(returnValue);
388}
389
390// Wires every dialog under root ([data-cap="dialog"]) and every trigger
391// [data-cap-dialog-open="<dialog id>"]. A dialog with data-cap-open (or the specimens'
392// data-specimen-open) opens now. A dialog with data-cap-inline and `open` is in the page until
393// this runs, then closed (see the markup on the doc page). A trigger that is a link keeps its href for a new tab; a plain
394// click opens the dialog. Returns a function that detaches them all.
395export function enhance(root: ParentNode = document): () => void {
396  const undo: Array<() => void> = [];
397  for (const dialog of root.querySelectorAll<HTMLDialogElement>("dialog[data-cap='dialog']:not([data-cap-ready])")) {
398    // Shown in the page with no script (`open`, `data-cap-inline`): script takes it over, so it
399    // is closed until a trigger opens it as the modal.
400    if (dialog.hasAttribute("data-cap-inline") && dialog.open && !dialog.matches(":modal")) dialog.removeAttribute("open");
401    undo.push(wireDialog(dialog));
402    if (dialog.hasAttribute("data-cap-open") || dialog.hasAttribute("data-specimen-open")) openDialog(dialog, null);
403  }
404  for (const trigger of root.querySelectorAll<HTMLElement>("[data-cap-dialog-open]:not([data-cap-ready])")) {
405    trigger.dataset.capReady = "";
406    if (!trigger.hasAttribute("aria-haspopup")) trigger.setAttribute("aria-haspopup", "dialog");
407    const onClick = (e: MouseEvent) => {
408      if (e.ctrlKey || e.metaKey || e.shiftKey || e.button !== 0) return;
409      const dialog = document.getElementById(trigger.dataset.capDialogOpen ?? "");
410      if (!(dialog instanceof HTMLDialogElement)) return;
411      e.preventDefault();
412      openDialog(dialog, trigger);
413    };
414    trigger.addEventListener("click", onClick);
415    undo.push(() => {
416      trigger.removeEventListener("click", onClick);
417      delete trigger.dataset.capReady;
418    });
419  }
420  return () => undo.forEach((f) => f());
421}