components/tabs/tabs.ts

Functions

Imports

It imports no other module of this repo. Imported by components/tabs/tabs.react.tsx.

Source

1// The tabs' behaviour (WAI-ARIA Authoring Practices, Tabs): one tab stop on the chosen tab
2// (a roving tabindex), arrow keys, Home and End move between tabs, a tab chosen shows its
3// panel and hides the rest. The markup arrives complete (chosen tab, `tabindex`, `hidden`
4// panels), so this module only adds what changes after a person acts. No framework; the
5// React wrapper uses the same pure functions.
6
7const READY = "data-cap-ready";
8
9export type Orientation = "horizontal" | "vertical";
10export type Activation = "automatic" | "manual";
11
12// The tab to move to for a key, among the tabs that can be chosen. `enabled` holds the
13// positions of the tabs not disabled, in order; `current` is the position of the focused
14// tab. Left and Right move a horizontal list (swapped in a right-to-left page), Up and Down
15// a vertical one; Home and End go to the ends; the ends wrap. Returns the position to focus,
16// or null when the key is not one of these.
17export function nextTab(enabled: number[], current: number, key: string, orientation: Orientation = "horizontal", rtl = false): number | null {
18  if (enabled.length === 0) return null;
19  const forward = orientation === "vertical" ? "ArrowDown" : rtl ? "ArrowLeft" : "ArrowRight";
20  const back = orientation === "vertical" ? "ArrowUp" : rtl ? "ArrowRight" : "ArrowLeft";
21  if (key === "Home") return enabled[0] ?? null;
22  if (key === "End") return enabled[enabled.length - 1] ?? null;
23  if (key !== forward && key !== back) return null;
24  const at = enabled.indexOf(current);
25  // From a tab that cannot be chosen, forward starts at the next one after it, back at the one before.
26  const step = key === forward ? 1 : -1;
27  if (at === -1) {
28    const after = enabled.filter((i) => (step === 1 ? i > current : i < current));
29    return (step === 1 ? after[0] : after[after.length - 1]) ?? (step === 1 ? enabled[0] : enabled[enabled.length - 1]) ?? null;
30  }
31  return enabled[(at + step + enabled.length) % enabled.length] ?? null;
32}
33
34function listOf(root: HTMLElement): HTMLElement | null {
35  return root.querySelector<HTMLElement>(":scope > [role='tablist']");
36}
37
38// This tab set's own tabs and panels (not those of a tab set nested in a panel).
39export function tabsOf(root: HTMLElement): HTMLElement[] {
40  return [...(listOf(root)?.querySelectorAll<HTMLElement>(":scope > [role='tab']") ?? [])];
41}
42export function panelOf(root: HTMLElement, tab: HTMLElement): HTMLElement | null {
43  const id = tab.getAttribute("aria-controls");
44  if (!id) return null;
45  return [...root.querySelectorAll<HTMLElement>(":scope > [role='tabpanel']")].find((p) => p.id === id) ?? null;
46}
47
48function isDisabled(tab: HTMLElement): boolean {
49  return tab.getAttribute("aria-disabled") === "true" || (tab as HTMLButtonElement).disabled === true;
50}
51
52// Chooses a tab: it becomes the one tab stop, its panel shows, the others hide. A disabled
53// tab is not chosen. Tells the page with a `cap:tabs-change` event (bubbles) carrying the
54// tab and its panel. Returns whether the tab was chosen.
55export function select(root: HTMLElement, tab: HTMLElement, options: { focus?: boolean; silent?: boolean } = {}): boolean {
56  if (isDisabled(tab)) return false;
57  const tabs = tabsOf(root);
58  if (!tabs.includes(tab)) return false;
59  const changed = tab.getAttribute("aria-selected") !== "true";
60  for (const t of tabs) {
61    const on = t === tab;
62    t.setAttribute("aria-selected", String(on));
63    t.tabIndex = on ? 0 : -1;
64    const panel = panelOf(root, t);
65    if (panel) panel.hidden = !on;
66  }
67  if (options.focus) tab.focus();
68  // A long list scrolls the chosen tab into view, the least distance that shows it.
69  tab.scrollIntoView?.({ block: "nearest", inline: "nearest" });
70  if (changed && !options.silent) tab.dispatchEvent(new CustomEvent("cap:tabs-change", { bubbles: true, detail: { tab, panel: panelOf(root, tab) } }));
71  return true;
72}
73
74function attach(root: HTMLElement): () => void {
75  const list = listOf(root);
76  if (!list) return () => {};
77  const undo: Array<() => void> = [];
78  const on = <E extends Event>(type: string, fn: (e: E) => void) => {
79    list.addEventListener(type, fn as EventListener);
80    undo.push(() => list.removeEventListener(type, fn as EventListener));
81  };
82  const orientation = (): Orientation => (list.getAttribute("aria-orientation") === "vertical" || root.dataset.orientation === "vertical" ? "vertical" : "horizontal");
83  const manual = () => root.dataset.activation === "manual";
84  const hashed = () => root.dataset.sync === "hash";
85
86  // Keeps the address in step when asked (data-sync="hash"): the panel's id after the #,
87  // so a link opens the tab, and Back does not pile up one entry per click.
88  const writeHash = (tab: HTMLElement) => {
89    const id = tab.getAttribute("aria-controls");
90    if (!hashed() || !id) return;
91    try {
92      history.replaceState(history.state, "", `#${id}`);
93    } catch {
94      /* a sandboxed frame may refuse; the tab still changes */
95    }
96  };
97  const fromHash = () => {
98    if (!hashed() || !location.hash) return;
99    const id = decodeURIComponent(location.hash.slice(1));
100    const tab = tabsOf(root).find((t) => t.getAttribute("aria-controls") === id);
101    if (tab && tab.getAttribute("aria-selected") !== "true") select(root, tab);
102  };
103
104  on<MouseEvent>("click", (e) => {
105    const tab = (e.target as HTMLElement).closest<HTMLElement>("[role='tab']");
106    if (!tab || tab.parentElement !== list) return;
107    if (isDisabled(tab)) {
108      e.preventDefault();
109      return;
110    }
111    if (select(root, tab)) writeHash(tab);
112  });
113
114  on<KeyboardEvent>("keydown", (e) => {
115    if (e.ctrlKey || e.metaKey || e.altKey) return;
116    const tab = (e.target as HTMLElement).closest<HTMLElement>("[role='tab']");
117    if (!tab || tab.parentElement !== list) return;
118    const tabs = tabsOf(root);
119    const enabled = tabs.flatMap((t, i) => (isDisabled(t) ? [] : [i]));
120    const rtl = getComputedStyle(list).direction === "rtl";
121    const to = nextTab(enabled, tabs.indexOf(tab), e.key, orientation(), rtl);
122    if (to === null) {
123      // Manual activation: Enter and Space on a focused tab choose it (a button does this
124      // by itself; a tab that is not a button needs it).
125      if ((e.key === "Enter" || e.key === " ") && tab.tagName !== "BUTTON" && select(root, tab)) {
126        e.preventDefault();
127        writeHash(tab);
128      }
129      return;
130    }
131    e.preventDefault();
132    const target = tabs[to];
133    if (!target) return;
134    if (manual()) {
135      // Focus moves along the tabs; the chosen one stays the tab stop until Enter or Space.
136      for (const t of tabs) t.tabIndex = t === target ? 0 : -1;
137      target.focus();
138    } else if (select(root, target, { focus: true })) writeHash(target);
139  });
140
141  // In manual mode focus may leave a tab that was only focused: the chosen tab is the tab stop again.
142  on<FocusEvent>("focusout", (e) => {
143    if (!manual()) return;
144    const next = e.relatedTarget as Node | null;
145    if (next && list.contains(next)) return;
146    for (const t of tabsOf(root)) t.tabIndex = t.getAttribute("aria-selected") === "true" ? 0 : -1;
147  });
148
149  if (hashed()) {
150    window.addEventListener("hashchange", fromHash);
151    undo.push(() => window.removeEventListener("hashchange", fromHash));
152    fromHash();
153  }
154  return () => undo.forEach((f) => f());
155}
156
157// Attaches every [data-cap="tabs"] under root not yet attached. Returns a function that
158// detaches them.
159export function enhance(root: ParentNode = document): () => void {
160  const undo: Array<() => void> = [];
161  for (const el of root.querySelectorAll<HTMLElement>("[data-cap='tabs']")) {
162    if (el.hasAttribute(READY)) continue;
163    el.setAttribute(READY, "");
164    const detach = attach(el);
165    undo.push(() => {
166      detach();
167      el.removeAttribute(READY);
168    });
169  }
170  return () => undo.forEach((f) => f());
171}