components/theme-switch/theme-switch.ts

Functions

Imports

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

Source

1// The theme switch: Light or Dark, as a two-choice segmented radio group, or (0.9.0) as one icon
2// button that switches to the other theme (data-variant="button", the site header's control). The first visit
3// follows the operating system's setting (data-theme is left off, so the system's choice
4// applies); the first time the person chooses, data-theme is set and the choice is remembered
5// in this browser from then on, as the Portal's top bar button does. applyStoredTheme() is
6// what an app runs before first paint; toggleTheme() is for a "t" shortcut. No framework;
7// the React wrapper uses the same functions.
8import { readPref, writePref } from "../shell/shell.ts";
9import { attach as attachTip } from "../tooltip/tooltip.ts";
10
11export type ThemeChoice = "light" | "dark";
12export const THEME_PREF = "cap-theme";
13
14const isChoice = (v: string | null | undefined): v is ThemeChoice => v === "light" || v === "dark";
15
16// What the person chose and the browser remembers, or null if they never did. A "system"
17// remembered by 0.1.0 reads as no choice: the system's setting applies, as it did.
18export function readTheme(key = THEME_PREF): ThemeChoice | null {
19  const v = readPref(key);
20  return isChoice(v) ? v : null;
21}
22
23// The choice a theme view transition is about to paint, so effectiveTheme() is right at once.
24let pending: ThemeChoice | null = null;
25
26// Sets data-theme, remembers the choice unless told not to, and tells every switch on the page.
27// A person's choice (one it remembers) crossfades the page in a view transition (css/base.css),
28// where the browser has one and motion is allowed; a restored or synced choice paints at once.
29export function applyTheme(choice: ThemeChoice, opts: { key?: string; remember?: boolean } = {}): void {
30  const paint = () => {
31    pending = null;
32    document.documentElement.setAttribute("data-theme", choice);
33  };
34  const reduce = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
35  if (opts.remember === false || reduce || !document.startViewTransition) paint();
36  else {
37    pending = choice;
38    document.startViewTransition(paint);
39  }
40  if (opts.remember !== false) writePref(opts.key ?? THEME_PREF, choice);
41  document.dispatchEvent(new CustomEvent("cap-theme", { detail: { choice } }));
42}
43
44// Applies the remembered choice, if there is one. Run it before first paint, or the page
45// flashes the other theme. Returns what it applied.
46export function applyStoredTheme(key = THEME_PREF): ThemeChoice | null {
47  const t = readTheme(key);
48  if (t) applyTheme(t, { key, remember: false });
49  return t;
50}
51
52// The theme the page is painting now: data-theme when set, else the operating system's. It
53// is right even when storage cannot be read or written, because the attribute is what
54// applyTheme sets first.
55export function effectiveTheme(): ThemeChoice {
56  if (pending) return pending;
57  const t = document.documentElement.getAttribute("data-theme");
58  if (isChoice(t)) return t;
59  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
60}
61
62// Switches between light and dark, from whatever is showing, and remembers it. For a "t" shortcut.
63export function toggleTheme(key = THEME_PREF): ThemeChoice {
64  const next = effectiveTheme() === "dark" ? "light" : "dark";
65  applyTheme(next, { key });
66  return next;
67}
68
69function check(el: HTMLElement, choice: ThemeChoice): void {
70  for (const r of el.querySelectorAll<HTMLInputElement>("input[type='radio']")) r.checked = r.value === choice;
71}
72
73// The button form says what it does, never what is showing: "Switch to dark theme" while the
74// page is light, "Switch to light theme" while it is dark.
75export function themeButtonLabel(showing: ThemeChoice): string {
76  return showing === "dark" ? "Switch to light theme" : "Switch to dark theme";
77}
78
79// Keeps a theme button's name and its tip's words in step with the theme that is showing.
80export function syncThemeButton(button: HTMLElement, showing: ThemeChoice = effectiveTheme()): void {
81  const label = themeButtonLabel(showing);
82  button.setAttribute("aria-label", label);
83  const text = button.querySelector(".cap-theme-tip-text");
84  if (text) text.textContent = label;
85}
86
87// One theme button: a press switches to the other theme and remembers it; its name follows the
88// theme from any source (a switch, the T key, another tab, the system). Its tip repeats its name,
89// so it adds no description.
90function wireButton(el: HTMLElement, key: string): () => void {
91  const start = readTheme(key);
92  if (start) applyTheme(start, { key, remember: false });
93  syncThemeButton(el);
94  const tip = el.querySelector<HTMLElement>(".cap-theme-tip");
95  const detachTip = tip ? attachTip(el, tip) : null;
96  el.removeAttribute("aria-describedby");
97  const onClick = () => toggleTheme(key);
98  const onTheme = (e: Event) => syncThemeButton(el, (e as CustomEvent<{ choice: ThemeChoice }>).detail?.choice ?? effectiveTheme());
99  const onStorage = (e: StorageEvent) => {
100    if (e.key === key && isChoice(e.newValue)) applyTheme(e.newValue, { key, remember: false });
101  };
102  const media = window.matchMedia("(prefers-color-scheme: dark)");
103  const onSystem = () => syncThemeButton(el);
104  el.addEventListener("click", onClick);
105  document.addEventListener("cap-theme", onTheme);
106  window.addEventListener("storage", onStorage);
107  media.addEventListener("change", onSystem);
108  return () => {
109    el.removeEventListener("click", onClick);
110    document.removeEventListener("cap-theme", onTheme);
111    window.removeEventListener("storage", onStorage);
112    media.removeEventListener("change", onSystem);
113    detachTip?.();
114  };
115}
116
117// Attaches to every [data-cap="theme-switch"] under root. With a remembered choice, that is
118// checked and applied. With none and a radio checked in the markup (a server that read a
119// cookie), that one is applied. With neither, the radio for the operating system's theme is
120// checked and nothing is applied or remembered until the person chooses, so the page keeps
121// following the system. A change applies and remembers; the radios follow toggleTheme(),
122// other tabs and the system.
123export function enhance(root: ParentNode = document): () => void {
124  const undo: Array<() => void> = [];
125  for (const el of root.querySelectorAll<HTMLElement>("[data-cap='theme-switch']:not([data-cap-ready])")) {
126    el.dataset.capReady = "";
127    const key = el.dataset.capPref ?? THEME_PREF;
128    if (el.dataset.variant === "button") {
129      const unwire = wireButton(el, key);
130      undo.push(() => {
131        unwire();
132        delete el.dataset.capReady;
133      });
134      continue;
135    }
136    const marked = el.querySelector<HTMLInputElement>("input[type='radio']:checked")?.value;
137    const start = readTheme(key) ?? (isChoice(marked) ? marked : null);
138    if (start) applyTheme(start, { key, remember: false });
139    check(el, start ?? effectiveTheme());
140
141    const onChange = (e: Event) => {
142      const r = e.target as HTMLInputElement;
143      if (r.type === "radio" && isChoice(r.value)) applyTheme(r.value, { key });
144    };
145    const onTheme = (e: Event) => {
146      const choice = (e as CustomEvent<{ choice: ThemeChoice }>).detail?.choice;
147      if (isChoice(choice)) check(el, choice);
148    };
149    const onStorage = (e: StorageEvent) => {
150      if (e.key === key && isChoice(e.newValue)) applyTheme(e.newValue, { key, remember: false });
151    };
152    // While the person has not chosen, the system's change shows in the control too.
153    const media = window.matchMedia("(prefers-color-scheme: dark)");
154    const onSystem = () => {
155      if (!document.documentElement.hasAttribute("data-theme")) check(el, effectiveTheme());
156    };
157    el.addEventListener("change", onChange);
158    document.addEventListener("cap-theme", onTheme);
159    window.addEventListener("storage", onStorage);
160    media.addEventListener("change", onSystem);
161    undo.push(() => {
162      el.removeEventListener("change", onChange);
163      document.removeEventListener("cap-theme", onTheme);
164      window.removeEventListener("storage", onStorage);
165      media.removeEventListener("change", onSystem);
166      delete el.dataset.capReady;
167    });
168  }
169  return () => undo.forEach((f) => f());
170}