theme.ts · Source

theme.tspackages/ui/src/theme.tsraw ← src3,767 B← Back to the app
1/**
2 * @factory/ui — theme resolution + application (PURE, DOM-duck-typed, testable).
3 *
4 * `Theme` = explicit "light" | "dark" or "system" (follow OS). `applyThemeTo`
5 * accepts a minimal duck-typed document so the whole flow is unit-testable
6 * without a real DOM; `matchMedia` absence is guarded (SSR / older runtimes).
7 */
8 
9export type Theme = "light" | "dark" | "system";
10export type ResolvedTheme = "light" | "dark";
11 
12/** localStorage key for the persisted user preference. */
13export function themeLocalStorageKey(): string {
14  return "factory.theme";
15}
16 
17/** Media query describing the OS "dark" preference. */
18export function systemDarkQuery(): string {
19  return "(prefers-color-scheme: dark)";
20}
21 
22/** Resolve a stored preference against the current OS setting. */
23export function resolveTheme(pref: Theme, systemDark: boolean): ResolvedTheme {
24  if (pref === "light") return "light";
25  if (pref === "dark") return "dark";
26  return systemDark ? "dark" : "light";
27}
28 
29/** Minimal DOM document surface needed by {@link applyThemeTo}. */
30export interface ThemeDocument {
31  dataset: Record<string, string | undefined>;
32  addEventListener?: (type: string, handler: (e: unknown) => void) => void;
33  removeEventListener?: (type: string, handler: (e: unknown) => void) => void;
34}
35 
36interface MediaQueryLike {
37  matches: boolean;
38  addEventListener?: (type: string, handler: () => void) => void;
39  removeEventListener?: (type: string, handler: () => void) => void;
40  /** Safari <14 style. */
41  addListener?: (handler: () => void) => void;
42  removeListener?: (handler: () => void) => void;
43}
44 
45/**
46 * Active system-preference listener per media object. A module-level WeakMap
47 * makes `applyThemeTo` idempotent: re-applying "system" replaces (never
48 * stacks) the previous listener, and explicit prefs detach it.
49 */
50const SYSTEM_LISTENERS = new WeakMap<MediaQueryLike, () => void>();
51 
52function detachSystemListener(media: MediaQueryLike | null): void {
53  if (!media) return;
54  const handler = SYSTEM_LISTENERS.get(media);
55  if (!handler) return;
56  media.removeEventListener?.("change", handler);
57  media.removeListener?.(handler);
58  SYSTEM_LISTENERS.delete(media);
59}
60 
61/**
62 * Apply a theme preference to the document root.
63 *
64 *  1. Sets `data-theme="light|dark"` on `document.dataset` (i.e. `<html>`).
65 *  2. If pref is "system", (re)binds a `change` listener on
66 *     `matchMedia("(prefers-color-scheme: dark)")` so OS switches are live;
67 *     any previously bound listener is unregistered first (idempotent).
68 *  3. Non-system prefs remove any system listener.
69 *
70 * Returns the resolved theme actually applied.
71 */
72export function applyThemeTo(
73  document: ThemeDocument,
74  pref: Theme,
75  windowLike?: unknown,
76): ResolvedTheme {
77  const media =
78    typeof (windowLike as { matchMedia?: (q: string) => MediaQueryLike } | undefined)
79      ?.matchMedia === "function"
80      ? (windowLike as { matchMedia: (q: string) => MediaQueryLike }).matchMedia(systemDarkQuery())
81      : null; // guard: no matchMedia (SSR / older runtimes)
82 
83  const resolved = resolveTheme(pref, media ? media.matches : false);
84  document.dataset.theme = resolved;
85 
86  if (pref === "system" && media) {
87    detachSystemListener(media); // idempotent: replace any previous system listener
88    const handler = (): void => {
89      document.dataset.theme = resolveTheme(pref, media.matches);
90    };
91    // Register on exactly ONE API (modern first, legacy Safari fallback) so the
92    // listener is counted once per media object.
93    if (media.addEventListener) {
94      media.addEventListener("change", handler);
95    } else if (media.addListener) {
96      media.addListener(handler);
97    }
98    SYSTEM_LISTENERS.set(media, handler);
99  } else {
100    detachSystemListener(media);
101  }
102  return resolved;
103}
104