components/admin-shell/admin-shell.ts

Functions

Imports

It imports components/shell/shell.ts, components/site-header/site-header.ts, components/tooltip/tooltip.ts. Imported by components/admin-shell/admin-shell.react.tsx.

Source

1// The admin shell's behaviour: collapse the menu (the strip stays), remember the choice, attach
2// each control's name tip (Capsomer's tooltip: Esc hides it, WCAG 1.4.13) and jump between apps
3// with G and 1 to 9. The header above it (its panels, the account menu and the phone's sheet) is
4// the site header's own behaviour, which enhance() attaches too. No framework; the React wrapper
5// uses the same functions. The menu's links and the page are in the HTML without any of this.
6import { DEFAULT_PREF, readPref, writePref } from "../shell/shell.ts";
7import { enhance as enhanceHeader } from "../site-header/site-header.ts";
8import { attach as attachTip, hideTip } from "../tooltip/tooltip.ts";
9
10// A count is a glance, not a figure: past 99 it says 99+ (the site header's rule, one for the
11// family); the accessible name keeps the real count.
12export { badgeText } from "../site-header/site-header.ts";
13
14export const ADMIN_PREF = DEFAULT_PREF;
15
16// Page transitions (the View Transitions API), an option on the shell: `data-transition="page"`
17// names the content area, the strip and the menu for the browser, so the content cross-fades
18// between pages while the strip and menu stay put (admin-shell.css has the animation, from the
19// --dur-* tokens). An app calls this around the update that shows the next page (in React, wrap
20// the state change in flushSync). It runs `update` straight away, with no animation and no
21// error, when the browser has no document.startViewTransition, when a person asked for reduced
22// motion, or when the shell has not opted in. Resolves when the update has been shown.
23type Transitioner = { startViewTransition?: (update: () => void | Promise<void>) => { finished: Promise<void> } };
24
25export function pageTransitionsOn(shell: HTMLElement | null = document.querySelector("[data-cap='admin-shell']")): boolean {
26  if (!shell || shell.dataset.transition !== "page") return false;
27  if (typeof (document as unknown as Transitioner).startViewTransition !== "function") return false;
28  return !window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
29}
30
31export async function startPageTransition(update: () => void | Promise<void>, shell?: HTMLElement | null): Promise<void> {
32  if (!pageTransitionsOn(shell)) return void (await update());
33  try {
34    await (document as unknown as Required<Transitioner>).startViewTransition(update).finished;
35  } catch {
36    // A skipped or interrupted transition still showed the page; its animation is all that was lost.
37  }
38}
39
40export function setMenu(shell: HTMLElement, collapsed: boolean, remember = true): void {
41  if (collapsed) shell.dataset.menu = "collapsed";
42  else delete shell.dataset.menu;
43  const toggle = shell.querySelector<HTMLButtonElement>("[data-cap-part='menu-toggle']");
44  if (toggle) {
45    const name = collapsed ? "Expand menu" : "Collapse menu";
46    toggle.setAttribute("aria-expanded", String(!collapsed));
47    toggle.setAttribute("aria-label", name);
48    for (const text of toggle.querySelectorAll(":scope > .cap-admin-label, .cap-admin-tip .cap-admin-tip-text")) text.textContent = name;
49  }
50  if (remember) writePref(shell.dataset.capPref ?? ADMIN_PREF, collapsed ? "collapsed" : "expanded");
51}
52
53export function toggleMenu(shell: HTMLElement): void {
54  setMenu(shell, shell.dataset.menu !== "collapsed");
55}
56
57// G then a number jumps to the app in that place (the sequence GitHub and Linear use; Ctrl and a
58// digit belong to the browser's tabs). `armed` holds the time G was pressed. Returns the app's
59// address, or null: the key is not part of a jump, the number has no app, that app is already
60// open, or the person is typing in a field.
61export const JUMP_WINDOW_MS = 1200;
62export function jumpTarget(armed: { at: number }, e: Pick<KeyboardEvent, "key" | "ctrlKey" | "metaKey" | "altKey" | "target">, apps: ReadonlyArray<{ href: string; current?: boolean }>, now = Date.now()): string | null {
63  if (e.ctrlKey || e.metaKey || e.altKey) return null;
64  const t = e.target as Element | null;
65  if (t?.closest?.("input, textarea, select, [contenteditable='true']")) return null;
66  const live = armed.at > 0 && now - armed.at < JUMP_WINDOW_MS;
67  armed.at = e.key === "g" ? now : 0;
68  if (!live || !/^[1-9]$/.test(e.key)) return null;
69  const app = apps[Number(e.key) - 1];
70  return app && !app.current ? app.href : null;
71}
72
73// Attaches to every [data-cap="admin-shell"] under root that is not attached yet. Returns a
74// function that detaches them all.
75export function enhance(root: ParentNode = document): () => void {
76  const undo: Array<() => void> = [];
77  for (const shell of root.querySelectorAll<HTMLElement>("[data-cap='admin-shell']:not([data-cap-ready])")) {
78    shell.dataset.capReady = "";
79    const pref = readPref(shell.dataset.capPref ?? ADMIN_PREF);
80    if (pref) setMenu(shell, pref === "collapsed", false);
81
82    // Each control's name tip, a child of its control. A menu link's tip repeats its name, so it
83    // adds no description; it shows only while the menu is collapsed (admin-shell.css).
84    const detachTips = [...shell.querySelectorAll<HTMLElement>(".cap-admin-tip")].map((tip) => {
85      const trigger = tip.parentElement;
86      if (!trigger) return () => undefined;
87      const detach = attachTip(trigger, tip);
88      if (trigger.closest(".cap-admin-menu")) trigger.removeAttribute("aria-describedby");
89      const used = () => hideTip(trigger);
90      trigger.addEventListener("click", used);
91      return () => {
92        trigger.removeEventListener("click", used);
93        detach();
94      };
95    });
96    const detachHeader = enhanceHeader(shell);
97
98    const onClick = (e: MouseEvent) => {
99      if ((e.target as Element).closest("[data-cap-part='menu-toggle']")) toggleMenu(shell);
100    };
101    const armed = { at: 0 };
102    const onKey = (e: KeyboardEvent) => {
103      const apps = [...shell.querySelectorAll<HTMLAnchorElement>(".cap-admin-tile")].map((a) => ({ href: a.href, current: a.getAttribute("aria-current") === "true" }));
104      const to = jumpTarget(armed, e, apps);
105      if (to) {
106        e.preventDefault();
107        location.assign(to);
108      }
109    };
110    shell.addEventListener("click", onClick);
111    document.addEventListener("keydown", onKey);
112    undo.push(() => {
113      shell.removeEventListener("click", onClick);
114      detachTips.forEach((f) => f());
115      document.removeEventListener("keydown", onKey);
116      detachHeader();
117      delete shell.dataset.capReady;
118    });
119  }
120  return () => undo.forEach((f) => f());
121}