components/site-header/site-header.ts

Functions

Imports

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

Source

1// The site header's behaviour: the panels (the switcher, a section with children, the account),
2// the phone's sheet, and each icon control's name tip. No framework; the React wrapper uses the
3// same functions. Every link, the logo, Sign in and the controls are in the HTML without any of
4// this; a panel's contents are too, so a page with no script still reads and reaches them.
5//
6// A panel is a list of links under a disclosure button (aria-expanded, aria-controls), not an
7// ARIA menu: every item goes somewhere. It is a manual popover in the top layer, so it is above
8// the page and every rail, and this module gives it light dismiss and Esc. On a mouse it opens at
9// once on hover, with no delay, and on click; on touch, on tap. Opened from the keyboard, focus
10// moves to its first item; Up and Down move between items, Home and End go to the ends, Esc closes
11// it and focus goes back to its button.
12import { closeDialog, openDialog, wireDialog } from "../dialog/dialog.ts";
13import { place } from "../popover/popover.ts";
14import { attach as attachTip, hideTip } from "../tooltip/tooltip.ts";
15
16// A count is a glance, not a figure: past 99 it says 99+, in the header, the sheet, the bottom bar
17// and the admin shell alike; the accessible name keeps the real count.
18export const badgeText = (count: number): string => (count > 99 ? "99+" : String(count));
19
20// How long a panel opened by hover stays after the pointer leaves both it and its button, so the
21// pointer can cross the gap between them.
22export const HOVER_GRACE_MS = 150;
23
24// The phone layout's width (docs/design/design-site-header.md, section 5): under 768px.
25export const PHONE_QUERY = "(max-width: 767.98px)";
26
27// The next item for a key in a panel of `count` items with `at` focused (-1: none yet). Returns
28// null for a key that does not move. Up and Down wrap; Home and End go to the ends.
29export function stepIndex(count: number, at: number, key: string): number | null {
30  if (count === 0) return null;
31  if (key === "Home") return 0;
32  if (key === "End") return count - 1;
33  if (key === "ArrowDown") return at < 0 ? 0 : (at + 1) % count;
34  if (key === "ArrowUp") return at < 0 ? count - 1 : (at - 1 + count) % count;
35  return null;
36}
37
38// The items a panel holds that a person can reach: links and enabled buttons that are drawn.
39export function panelItems(panel: HTMLElement): HTMLElement[] {
40  return [...panel.querySelectorAll<HTMLElement>("a[href], button:not(:disabled)")].filter((el) => el.getClientRects().length > 0);
41}
42
43const isOpen = (panel: HTMLElement): boolean => {
44  try {
45    return panel.matches(":popover-open");
46  } catch {
47    return false;
48  }
49};
50
51// Every panel this module has wired, so opening one closes the others in the same header.
52const panels = new Map<HTMLElement, { trigger: HTMLElement; close: () => void }>();
53
54export function closePanels(except?: HTMLElement): void {
55  for (const [panel, p] of panels) if (panel !== except && isOpen(panel)) p.close();
56}
57
58// Puts a panel under its button, lined up with the button's edge (start, or end with
59// data-align="end"), its top just under the header's bottom edge so it never covers the header.
60export function placePanel(trigger: HTMLElement, panel: HTMLElement): void {
61  const bar = trigger.closest(".cap-site-header")?.getBoundingClientRect();
62  const t = trigger.getBoundingClientRect();
63  const offset = bar ? Math.max(4, Math.round(bar.bottom - t.bottom) + 4) : 4;
64  place(trigger, panel, { side: "bottom", align: panel.dataset.align === "end" ? "end" : "start", offset });
65}
66
67let escBound = false;
68function onEsc(e: KeyboardEvent): void {
69  if (e.key !== "Escape") return;
70  for (const [panel, p] of panels) {
71    if (!isOpen(panel)) continue;
72    e.preventDefault();
73    const inside = panel.contains(document.activeElement) || p.trigger === document.activeElement;
74    p.close();
75    if (inside) p.trigger.focus({ preventScroll: true });
76  }
77}
78
79// Wires one disclosure button to its panel. Returns a function that unwires it.
80export function wirePanel(trigger: HTMLElement, panel: HTMLElement): () => void {
81  if (!panel.hasAttribute("popover")) panel.setAttribute("popover", "manual");
82  trigger.setAttribute("aria-expanded", String(isOpen(panel)));
83  if (panel.id) trigger.setAttribute("aria-controls", panel.id);
84  // How it was opened: by hover it closes when the pointer leaves; by a click or a key it stays.
85  let mode: "hover" | "held" = "held";
86  let timer: number | undefined;
87  const undo: Array<() => void> = [];
88  const on = <E extends Event>(target: EventTarget, type: string, fn: (e: E) => void, opts?: boolean | AddEventListenerOptions) => {
89    target.addEventListener(type, fn as EventListener, opts);
90    undo.push(() => target.removeEventListener(type, fn as EventListener, opts));
91  };
92  const follow = () => {
93    if (isOpen(panel)) placePanel(trigger, panel);
94  };
95  const close = () => {
96    window.clearTimeout(timer);
97    if (isOpen(panel)) panel.hidePopover();
98  };
99  const open = (how: "hover" | "held", focusFirst = false) => {
100    window.clearTimeout(timer);
101    closePanels(panel);
102    mode = how;
103    if (!isOpen(panel)) panel.showPopover();
104    placePanel(trigger, panel);
105    if (focusFirst) panelItems(panel)[0]?.focus({ preventScroll: true });
106  };
107  panels.set(panel, { trigger, close });
108  if (!escBound) {
109    escBound = true;
110    document.addEventListener("keydown", onEsc);
111  }
112
113  on(panel, "toggle", (e: ToggleEvent) => {
114    const opened = e.newState === "open";
115    trigger.setAttribute("aria-expanded", String(opened));
116    window[opened ? "addEventListener" : "removeEventListener"]("scroll", follow, true);
117    window[opened ? "addEventListener" : "removeEventListener"]("resize", follow);
118    if (!opened) {
119      // Focus left inside a closed panel (or lost to the page) goes back to its button.
120      const active = document.activeElement;
121      if (!active || active === document.body || panel.contains(active)) trigger.focus({ preventScroll: true });
122    }
123  });
124  // A click, Enter or Space toggles. A panel opened by hover is held open by a click rather than
125  // closed by it, since the click is what the person meant. From the keyboard (no pointer, so
126  // detail 0) focus moves to the first item.
127  on(trigger, "click", (e: MouseEvent) => {
128    e.preventDefault();
129    hideTip(trigger);
130    const byKey = e.detail === 0;
131    if (isOpen(panel) && (mode === "held" || byKey)) close();
132    else open("held", byKey);
133  });
134  const hovered = () => trigger.matches(":hover") || panel.matches(":hover");
135  const leave = () => {
136    if (mode !== "hover") return;
137    window.clearTimeout(timer);
138    timer = window.setTimeout(() => {
139      if (!hovered()) close();
140    }, HOVER_GRACE_MS);
141  };
142  on(trigger, "pointerenter", (e: PointerEvent) => {
143    if (e.pointerType !== "mouse") return;
144    window.clearTimeout(timer);
145    if (!isOpen(panel)) open("hover");
146  });
147  on(trigger, "pointerleave", leave);
148  on(panel, "pointerenter", () => window.clearTimeout(timer));
149  on(panel, "pointerleave", leave);
150  on(panel, "keydown", (e: KeyboardEvent) => {
151    const items = panelItems(panel);
152    const next = stepIndex(items.length, items.indexOf(document.activeElement as HTMLElement), e.key);
153    if (next === null) return;
154    e.preventDefault();
155    items[next]?.focus();
156  });
157  // Tab past the panel's last item closes it without taking focus back.
158  on(panel, "focusout", (e: FocusEvent) => {
159    const to = e.relatedTarget as Node | null;
160    if (to && !panel.contains(to) && to !== trigger) close();
161  });
162  // A press outside the panel and its button closes it (light dismiss), as does following a link.
163  on(document, "pointerdown", (e: PointerEvent) => {
164    const t = e.target as Node;
165    if (isOpen(panel) && !panel.contains(t) && !trigger.contains(t)) close();
166  });
167  on(panel, "click", (e: MouseEvent) => {
168    if ((e.target as Element).closest("a[href], [data-panel-close]")) close();
169  });
170  return () => {
171    close();
172    window.removeEventListener("scroll", follow, true);
173    window.removeEventListener("resize", follow);
174    undo.forEach((f) => f());
175    panels.delete(panel);
176  };
177}
178
179// Opens the phone's sheet (the shared dialog, from the bottom) from the menu button.
180export function openSheet(header: HTMLElement): void {
181  const button = header.querySelector<HTMLButtonElement>(".cap-site-header-menu");
182  const sheet = header.querySelector<HTMLDialogElement>("dialog.cap-site-header-sheet");
183  if (!sheet || sheet.open) return;
184  openDialog(sheet, button, { focus: sheet.querySelector<HTMLElement>(".cap-site-header-sheet-title") });
185  button?.setAttribute("aria-expanded", "true");
186}
187
188export function closeSheet(header: HTMLElement): void {
189  const sheet = header.querySelector<HTMLDialogElement>("dialog.cap-site-header-sheet");
190  if (sheet?.open) closeDialog(sheet);
191}
192
193// Attaches to every [data-cap="site-header"] under root not yet attached: each panel, each
194// icon control's tip, the menu button and its sheet. Returns a function that detaches them all.
195export function enhance(root: ParentNode = document): () => void {
196  const undo: Array<() => void> = [];
197  for (const header of root.querySelectorAll<HTMLElement>("[data-cap='site-header']:not([data-cap-ready])")) {
198    header.dataset.capReady = "";
199    const parts: Array<() => void> = [];
200    for (const trigger of header.querySelectorAll<HTMLElement>("[data-cap-part='panel-trigger']")) {
201      const panel = document.getElementById(trigger.getAttribute("aria-controls") ?? "");
202      if (panel) parts.push(wirePanel(trigger, panel));
203    }
204    // An icon control's tip names it, so it adds no description; a press hides it.
205    for (const tip of header.querySelectorAll<HTMLElement>(".cap-site-header-tip")) {
206      const trigger = tip.parentElement;
207      if (!trigger) continue;
208      parts.push(attachTip(trigger, tip));
209      trigger.removeAttribute("aria-describedby");
210    }
211    const sheet = header.querySelector<HTMLDialogElement>("dialog.cap-site-header-sheet");
212    const menu = header.querySelector<HTMLButtonElement>(".cap-site-header-menu");
213    if (sheet) parts.push(wireDialog(sheet));
214    const onClose = () => menu?.setAttribute("aria-expanded", "false");
215    sheet?.addEventListener("close", onClose);
216    const onClick = (e: MouseEvent) => {
217      const t = e.target as Element;
218      if (menu && t.closest(".cap-site-header-menu") === menu) openSheet(header);
219      if (sheet?.open && sheet.contains(t) && t.closest("a[href]")) closeDialog(sheet);
220    };
221    header.addEventListener("click", onClick);
222    undo.push(() => {
223      header.removeEventListener("click", onClick);
224      sheet?.removeEventListener("close", onClose);
225      parts.forEach((f) => f());
226      delete header.dataset.capReady;
227    });
228  }
229  return () => undo.forEach((f) => f());
230}