components/shell/shell.ts

Functions

Imports

It imports components/dialog/dialog.ts. Imported by components/admin-shell/admin-shell.react.tsx, components/admin-shell/admin-shell.ts, components/shell/shell.react.tsx, components/shortcuts/shortcuts.ts, components/theme-switch/theme-switch.ts.

Source

1// The shell's behaviour: the rail's collapse button, the remembered choice, the More sheet,
2// the density choice, and Esc to dismiss a collapsed rail's label (WCAG 1.4.13). No framework;
3// the React wrapper uses the same functions. readPref and writePref are shared with the theme
4// switch and the shortcuts, so they stay exported.
5import { closeDialog, openDialog, wireDialog } from "../dialog/dialog.ts";
6
7export const DEFAULT_PREF = "cap-rail";
8
9export function readPref(key: string): string | null {
10  try {
11    return localStorage.getItem(key);
12  } catch {
13    return null;
14  }
15}
16
17export function writePref(key: string, value: string): void {
18  try {
19    localStorage.setItem(key, value);
20  } catch {
21    // Private windows and blocked storage: the choice lasts for this page only.
22  }
23}
24
25// Collapses or expands the rail of one shell, and keeps its toggle's state and name true.
26export function setRail(shell: HTMLElement, collapsed: boolean, remember = true): void {
27  if (collapsed) shell.dataset.rail = "collapsed";
28  else delete shell.dataset.rail;
29  const toggle = shell.querySelector<HTMLButtonElement>("[data-cap-part='rail-toggle']");
30  if (toggle) {
31    toggle.setAttribute("aria-expanded", String(!collapsed));
32    const label = toggle.querySelector(".cap-shell-label");
33    if (label) label.textContent = collapsed ? "Expand menu" : "Collapse menu";
34  }
35  if (remember) writePref(shell.dataset.capPref ?? DEFAULT_PREF, collapsed ? "collapsed" : "expanded");
36}
37
38export function toggleRail(shell: HTMLElement): void {
39  setRail(shell, shell.dataset.rail !== "collapsed");
40}
41
42// The phone tab bar's More sheet: the shared dialog (components/dialog) as a bottom sheet,
43// which the More button opens. The dialog gives Esc, the inert page, the backdrop click, the
44// focus trap and the hand-back of focus to More; this adds aria-expanded on the button.
45export function openMore(shell: HTMLElement): void {
46  const button = shell.querySelector<HTMLButtonElement>("[data-cap-part='more']");
47  const dialog = shell.querySelector<HTMLDialogElement>("dialog.cap-shell-more");
48  if (!dialog || dialog.open) return;
49  openDialog(dialog, button);
50  button?.setAttribute("aria-expanded", "true");
51}
52
53export function closeMore(shell: HTMLElement): void {
54  const dialog = shell.querySelector<HTMLDialogElement>("dialog.cap-shell-more");
55  if (dialog?.open) closeDialog(dialog);
56}
57
58// Density: the choice of how roomy the app is, on the root as data-density, remembered in
59// this browser like the theme. With no choice made the attribute is left off and the default
60// (compact) applies. An app puts the choice on its Settings page, and runs applyStoredDensity()
61// before first paint beside applyStoredTheme().
62export type Density = "compact" | "comfortable";
63export const DENSITY_PREF = "cap-density";
64const isDensity = (v: string | null | undefined): v is Density => v === "compact" || v === "comfortable";
65
66export function readDensity(key = DENSITY_PREF): Density | null {
67  const v = readPref(key);
68  return isDensity(v) ? v : null;
69}
70
71export function applyDensity(choice: Density, opts: { key?: string; remember?: boolean } = {}): void {
72  document.documentElement.setAttribute("data-density", choice);
73  if (opts.remember !== false) writePref(opts.key ?? DENSITY_PREF, choice);
74  document.dispatchEvent(new CustomEvent("cap-density", { detail: { choice } }));
75}
76
77export function applyStoredDensity(key = DENSITY_PREF): Density | null {
78  const d = readDensity(key);
79  if (d) applyDensity(d, { key, remember: false });
80  return d;
81}
82
83// Attaches to every [data-cap="shell"] under root that is not attached yet. Returns a
84// function that detaches them all.
85export function enhance(root: ParentNode = document): () => void {
86  const undo: Array<() => void> = [];
87  for (const shell of root.querySelectorAll<HTMLElement>("[data-cap='shell']:not([data-cap-ready])")) {
88    shell.dataset.capReady = "";
89    const pref = readPref(shell.dataset.capPref ?? DEFAULT_PREF);
90    if (pref) setRail(shell, pref === "collapsed", false);
91
92    const more = shell.querySelector<HTMLDialogElement>("dialog.cap-shell-more");
93    const moreButton = shell.querySelector<HTMLButtonElement>("[data-cap-part='more']");
94    const onClick = (e: MouseEvent) => {
95      const target = e.target as Element;
96      if (target.closest("[data-cap-part='rail-toggle']")) toggleRail(shell);
97      if (target.closest("[data-cap-part='more']")) openMore(shell);
98      // The dialog closes itself on Close and the backdrop; a link inside closes it too.
99      if (more?.open && target.closest("a") && more.contains(target)) closeDialog(more);
100    };
101    // Closed by Esc, Close, a link or the backdrop: More says so, and the dialog hands focus back to it.
102    const onMoreClose = () => moreButton?.setAttribute("aria-expanded", "false");
103    const unwireMore = more ? wireDialog(more) : null;
104    more?.addEventListener("close", onMoreClose);
105    // Esc hides the label a collapsed rail is showing, until the pointer or focus moves on.
106    const onKey = (e: KeyboardEvent) => {
107      if (e.key !== "Escape" || shell.dataset.rail !== "collapsed") return;
108      const entry = (document.activeElement as Element | null)?.closest<HTMLElement>(".cap-shell-rail a, .cap-shell-toggle, .cap-shell-railbtn");
109      const hovered = shell.querySelector<HTMLElement>(".cap-shell-rail a:hover, .cap-shell-toggle:hover, .cap-shell-railbtn:hover");
110      for (const el of [entry, hovered]) if (el && shell.contains(el)) el.dataset.tip = "hidden";
111    };
112    const reset = (e: Event) => {
113      const el = (e.target as Element).closest<HTMLElement>("[data-tip='hidden']");
114      if (el) delete el.dataset.tip;
115    };
116    shell.addEventListener("click", onClick);
117    document.addEventListener("keydown", onKey);
118    shell.addEventListener("mouseout", reset);
119    shell.addEventListener("focusout", reset);
120    undo.push(() => {
121      shell.removeEventListener("click", onClick);
122      more?.removeEventListener("close", onMoreClose);
123      unwireMore?.();
124      document.removeEventListener("keydown", onKey);
125      shell.removeEventListener("mouseout", reset);
126      shell.removeEventListener("focusout", reset);
127      delete shell.dataset.capReady;
128    });
129  }
130  return () => undo.forEach((f) => f());
131}