@ghxstship/xos-ui 0.0.0-stage → 4.16.0

package/src/lib/live.ts

@@ -0,0 +1,92 @@
+import { createContext, createElement, useContext, useEffect, useRef, type ReactNode } from "react";
+
+/**
+ * Live updates in React (Section 11.7, ADR 0044). Components say which tables they show with
+ * `useLive`; the app's `LiveProvider` supplies the source, a hub that keeps one Realtime channel per
+ * page (`@xos/data/live`). This module has no Realtime code of its own, so a page that never
+ * watches anything never loads it, and outside a provider (Storybook, tests) `useLive` does nothing.
+ */
+
+/** One watched table, optionally narrowed with a Realtime filter such as `org_id=eq.<uuid>`. */
+export interface LiveTopic {
+  readonly table: string;
+  readonly filter?: string;
+}
+
+/** A changed row, or `RESYNC` after a reconnect. */
+export interface LiveChange {
+  readonly table: string;
+  readonly type: "INSERT" | "UPDATE" | "DELETE" | "RESYNC";
+  readonly id: string | null;
+  /** The row after an INSERT or UPDATE, as row level security let Realtime send it; the reread confirms it. */
+  readonly row?: Readonly<Record<string, unknown>>;
+}
+
+/** How fast batches may arrive; show mode follows cues faster than a list follows rows. */
+export interface LivePacing {
+  readonly batchMs?: number;
+  readonly minIntervalMs?: number;
+  readonly maxIntervalMs?: number;
+}
+
+export interface LiveSource {
+  watch(
+    topics: readonly LiveTopic[],
+    listener: (changes: readonly LiveChange[]) => void,
+    pacing?: LivePacing,
+  ): () => void;
+}
+
+const LiveContext = createContext<LiveSource | null>(null);
+
+export function LiveProvider({
+  source,
+  children,
+}: {
+  source: LiveSource | null;
+  children?: ReactNode;
+}): ReactNode {
+  return createElement(LiveContext.Provider, { value: source }, children);
+}
+
+/**
+ * One string for a set of topics, so a re-render with equal topics keeps its subscription. Topics
+ * are joined by a line break, which no filter holds; an `in` filter's values are comma-separated.
+ */
+function topicsKey(topics: readonly LiveTopic[] | null): string {
+  if (!topics || topics.length === 0) return "";
+  return topics
+    .map((t) => `${t.table}|${t.filter ?? ""}`)
+    .sort()
+    .join("\n");
+}
+
+/**
+ * Calls `onChange` with each batch of changes to the topics while the component is mounted. Null or
+ * empty topics watch nothing. The latest `onChange` is always the one called.
+ */
+export function useLive(
+  topics: readonly LiveTopic[] | null,
+  onChange: (changes: readonly LiveChange[]) => void,
+  pacing?: LivePacing,
+): void {
+  const source = useContext(LiveContext);
+  const handler = useRef(onChange);
+  handler.current = onChange;
+  const key = topicsKey(topics);
+  const batchMs = pacing?.batchMs;
+  const minIntervalMs = pacing?.minIntervalMs;
+  const maxIntervalMs = pacing?.maxIntervalMs;
+  useEffect(() => {
+    if (!source || key === "") return undefined;
+    const watched = key.split("\n").map((k): LiveTopic => {
+      const [table = "", filter = ""] = k.split("|");
+      return filter ? { table, filter } : { table };
+    });
+    return source.watch(watched, (changes) => handler.current(changes), {
+      ...(batchMs !== undefined ? { batchMs } : {}),
+      ...(minIntervalMs !== undefined ? { minIntervalMs } : {}),
+      ...(maxIntervalMs !== undefined ? { maxIntervalMs } : {}),
+    });
+  }, [source, key, batchMs, minIntervalMs, maxIntervalMs]);
+}

package/src/lib/preferences.ts

@@ -0,0 +1,242 @@
+/**
+ * Display preferences from the settings registry (Section 4.5.6 Preferences and Accessibility, A65-001): the
+ * person's text size, contrast, motion, density, single-key shortcuts, date format, units, first day of the
+ * week and the zone schedule times show in. Atlas and Gateway resolve them from the person's settings, keep
+ * them in one cookie so the server renders the document with them, and set them on the document root as data
+ * attributes the styles read.
+ */
+import type { TimeZoneDisplay } from "./format.ts";
+import type { UnitsPreference } from "@xos/i18n/units";
+
+export * from "@xos/i18n/units";
+export { displayTimeZone, formatZonedDateTime, type TimeZoneDisplay } from "./format.ts";
+
+export type TextSize = "default" | "large" | "larger";
+export type Contrast = "default" | "more";
+export type Motion = "system" | "reduce" | "full";
+export type Density = "comfortable" | "compact";
+export type DateFormat = "locale" | "iso";
+/**
+ * locale.units (Section 15): "jurisdiction" follows the project's jurisdiction (imperial for the United States,
+ * metric otherwise), or a fixed system; resolve it with `resolveUnitSystem` where a value is shown.
+ */
+export type Units = UnitsPreference;
+/**
+ * 0 for Sunday (payroll.week_start's default), 1 for Monday. The default is the registry's, so a person who
+ * never chose one keeps the cookie empty and nothing resyncs.
+ */
+export type WeekStart = 0 | 1;
+
+export interface DisplayPreferences {
+  readonly textSize: TextSize;
+  readonly contrast: Contrast;
+  readonly motion: Motion;
+  readonly density: Density;
+  readonly shortcuts: boolean;
+  readonly dateFormat: DateFormat;
+  readonly units: Units;
+  readonly weekStart: WeekStart;
+  /** me.time_zone_display: schedule times in the event's zone (default) or the viewer's own. */
+  readonly timeZoneDisplay: TimeZoneDisplay;
+}
+
+export const DEFAULT_PREFERENCES: DisplayPreferences = {
+  textSize: "default",
+  contrast: "default",
+  motion: "system",
+  density: "comfortable",
+  shortcuts: true,
+  dateFormat: "locale",
+  units: "jurisdiction",
+  weekStart: 0,
+  timeZoneDisplay: "event",
+};
+
+/** The cookie that carries the preferences for server rendering. */
+export const PREFERENCES_COOKIE = "xos-prefs";
+
+const YEAR_SECONDS = 60 * 60 * 24 * 365;
+
+/**
+ * The `document.cookie` assignment that keeps the preferences cookie in step with the person's settings. It is
+ * set in the browser, not by a server action, so keeping it current never re-renders or interrupts the page.
+ * The value holds only letters, digits, dots and bars; an empty value expires the cookie.
+ */
+export function preferencesCookie(encoded: string, secure: boolean): string {
+  const value = /^[a-z0-9.|]*$/.test(encoded) ? encoded : "";
+  const age = value === "" ? 0 : YEAR_SECONDS;
+  return `${PREFERENCES_COOKIE}=${value}; path=/; max-age=${age}; samesite=lax${secure ? "; secure" : ""}`;
+}
+
+/** The registry key each preference reads (packages/schemas/settings). */
+export const PREFERENCE_SETTINGS = {
+  textSize: "me.text_size",
+  contrast: "me.high_contrast",
+  motion: "me.reduced_motion",
+  density: "shell.density",
+  shortcuts: "me.shortcuts_enabled",
+  dateFormat: "locale.date_format",
+  units: "locale.units",
+  weekStart: "payroll.week_start",
+  timeZoneDisplay: "me.time_zone_display",
+} as const;
+
+const UNITS: readonly Units[] = ["jurisdiction", "imperial", "metric"];
+const ZONE_DISPLAYS: readonly TimeZoneDisplay[] = ["event", "viewer"];
+
+type SettingLookup = (key: string) => unknown;
+
+function pick<T extends string>(value: unknown, allowed: readonly T[], fallback: T): T {
+  return typeof value === "string" && (allowed as readonly string[]).includes(value)
+    ? (value as T)
+    : fallback;
+}
+
+/** Preferences from resolved setting values, falling back to the defaults for anything unset or unknown. */
+export function preferencesFromSettings(
+  values: ReadonlyMap<string, unknown> | SettingLookup,
+): DisplayPreferences {
+  const get: SettingLookup = typeof values === "function" ? values : (key) => values.get(key);
+  const week = get(PREFERENCE_SETTINGS.weekStart);
+  return {
+    textSize: pick(get(PREFERENCE_SETTINGS.textSize), ["default", "large", "larger"], "default"),
+    contrast: get(PREFERENCE_SETTINGS.contrast) === true ? "more" : "default",
+    motion: pick(get(PREFERENCE_SETTINGS.motion), ["system", "reduce", "full"], "system"),
+    density: pick(get(PREFERENCE_SETTINGS.density), ["comfortable", "compact"], "comfortable"),
+    shortcuts: get(PREFERENCE_SETTINGS.shortcuts) !== false,
+    dateFormat: pick(get(PREFERENCE_SETTINGS.dateFormat), ["locale", "iso"], "locale"),
+    units: pick(get(PREFERENCE_SETTINGS.units), UNITS, "jurisdiction"),
+    weekStart: week === "monday" ? 1 : 0,
+    timeZoneDisplay: pick(get(PREFERENCE_SETTINGS.timeZoneDisplay), ZONE_DISPLAYS, "event"),
+  };
+}
+
+const CODES: Record<keyof DisplayPreferences, string> = {
+  textSize: "t",
+  contrast: "c",
+  motion: "m",
+  density: "d",
+  shortcuts: "s",
+  dateFormat: "f",
+  units: "u",
+  weekStart: "w",
+  timeZoneDisplay: "z",
+};
+
+/** A short cookie value holding only what differs from the defaults, such as `t.large|d.compact`. */
+export function encodePreferences(prefs: DisplayPreferences): string {
+  const parts: string[] = [];
+  for (const key of Object.keys(CODES) as (keyof DisplayPreferences)[]) {
+    if (prefs[key] === DEFAULT_PREFERENCES[key]) continue;
+    const value = prefs[key];
+    const text = typeof value === "boolean" ? (value ? "1" : "0") : String(value);
+    parts.push(`${CODES[key]}.${text}`);
+  }
+  return parts.join("|");
+}
+
+/** Reads a cookie value written by encodePreferences; anything it does not recognize stays at its default. */
+export function decodePreferences(raw: string | undefined | null): DisplayPreferences {
+  if (!raw) return DEFAULT_PREFERENCES;
+  const found = new Map<string, string>();
+  for (const part of raw.split("|")) {
+    const [code, value] = part.split(".");
+    if (code && value !== undefined) found.set(code, value);
+  }
+  const week = found.get(CODES.weekStart);
+  return {
+    textSize: pick(found.get(CODES.textSize), ["default", "large", "larger"], "default"),
+    contrast: pick(found.get(CODES.contrast), ["default", "more"], "default"),
+    motion: pick(found.get(CODES.motion), ["system", "reduce", "full"], "system"),
+    density: pick(found.get(CODES.density), ["comfortable", "compact"], "comfortable"),
+    shortcuts: found.get(CODES.shortcuts) !== "0",
+    dateFormat: pick(found.get(CODES.dateFormat), ["locale", "iso"], "locale"),
+    units: pick(found.get(CODES.units), UNITS, "jurisdiction"),
+    weekStart: week === "1" ? 1 : 0,
+    timeZoneDisplay: pick(found.get(CODES.timeZoneDisplay), ZONE_DISPLAYS, "event"),
+  };
+}
+
+/**
+ * The document root's data attributes for the preferences the styles read: data-text-size, data-contrast,
+ * data-motion, data-density and data-shortcuts. Defaults add nothing.
+ */
+export function documentAttributes(prefs: DisplayPreferences): Record<string, string> {
+  const out: Record<string, string> = {};
+  if (prefs.textSize !== "default") out["data-text-size"] = prefs.textSize;
+  if (prefs.contrast === "more") out["data-contrast"] = "more";
+  if (prefs.motion !== "system") out["data-motion"] = prefs.motion;
+  if (prefs.density === "compact") out["data-density"] = "compact";
+  if (!prefs.shortcuts) out["data-shortcuts"] = "off";
+  return out;
+}
+
+const ATTRIBUTES = [
+  "data-text-size",
+  "data-contrast",
+  "data-motion",
+  "data-density",
+  "data-shortcuts",
+];
+
+/** Sets the preference attributes on an element (the document root), removing the ones back at default. */
+export function applyDocumentAttributes(element: HTMLElement, prefs: DisplayPreferences): void {
+  const next = documentAttributes(prefs);
+  for (const name of ATTRIBUTES) {
+    const value = next[name];
+    if (value === undefined) element.removeAttribute(name);
+    else element.setAttribute(name, value);
+  }
+}
+
+/**
+ * Whether single-key shortcuts (J, K, /, ?) are on: off while the document root carries
+ * data-shortcuts="off" (me.shortcuts_enabled). Shortcuts with Cmd or Ctrl always work.
+ */
+export function singleKeyShortcutsEnabled(
+  doc: Document | undefined = globalThis.document,
+): boolean {
+  return doc?.documentElement.dataset["shortcuts"] !== "off";
+}
+
+const SQUARE_METERS_PER_SQUARE_FOOT = 0.09290304;
+const METERS_PER_FOOT = 0.3048;
+const METERS_PER_MILE = 1609.344;
+
+/**
+ * An area stored in square feet in the person's units (locale.units): square feet, or square meters to one
+ * decimal. Callers label the unit from their message catalog, since Intl has no area units.
+ */
+export function convertArea(
+  squareFeet: number,
+  units: "imperial" | "metric",
+): { readonly value: number; readonly unit: "squareFoot" | "squareMeter" } {
+  return units === "metric"
+    ? {
+        value: Math.round(squareFeet * SQUARE_METERS_PER_SQUARE_FOOT * 10) / 10,
+        unit: "squareMeter",
+      }
+    : { value: squareFeet, unit: "squareFoot" };
+}
+
+/**
+ * A distance stored in meters in the person's units (locale.units): feet up to 1,000 ft and miles
+ * beyond, or meters up to 1 km and kilometers beyond, formatted by Intl for the locale.
+ */
+export function formatDistance(
+  locale: string,
+  meters: number,
+  units: "imperial" | "metric",
+): string {
+  const unit = (name: string, value: number, digits: number) =>
+    new Intl.NumberFormat(locale, {
+      style: "unit",
+      unit: name,
+      maximumFractionDigits: digits,
+    }).format(value);
+  if (units === "metric") {
+    return meters >= 1000 ? unit("kilometer", meters / 1000, 1) : unit("meter", meters, 0);
+  }
+  const feet = meters / METERS_PER_FOOT;
+  return feet >= 1000 ? unit("mile", meters / METERS_PER_MILE, 1) : unit("foot", feet, 0);
+}

package/src/lib/route-transition.tsx

@@ -0,0 +1,22 @@
+import { ViewTransition, type ReactElement, type ReactNode } from "react";
+
+/** The view transition class the route transition's CSS (styles/components.css) animates. */
+export const ROUTE_TRANSITION_CLASS = "xos-route";
+
+/**
+ * The page region of a route, for an app's `template.tsx` (Section 11.7, ADR 0118). Next remounts a
+ * template when the route below it changes, and the navigation is a React transition, so the page
+ * that leaves fades out and the page that arrives fades in through the browser's View Transitions
+ * API. Nothing else animates it: refreshes, search parameters and live updates keep the same
+ * template, and `default="none"` keeps every other transition still. Under reduced motion the CSS
+ * runs no animation, so the page swaps at once.
+ *
+ * It holds no state and no hooks, so a server template renders it and no route JavaScript is added.
+ */
+export function RouteTransition({ children }: { children: ReactNode }): ReactElement {
+  return (
+    <ViewTransition enter={ROUTE_TRANSITION_CLASS} exit={ROUTE_TRANSITION_CLASS} default="none">
+      {children}
+    </ViewTransition>
+  );
+}

package/src/lib/selection.ts

@@ -0,0 +1,92 @@
+import { useRef, type KeyboardEvent, type MouseEvent } from "react";
+import { singleKeyShortcutsEnabled } from "./preferences.ts";
+
+/** Items selected by id (Section 11.7). The component only reports the selection; the page keeps it. */
+export interface ItemSelection {
+  /** Ids of the selected items. */
+  selected: ReadonlySet<string>;
+  onChange: (next: ReadonlySet<string>) => void;
+}
+
+/** What an item's own gestures can do to the selection; see useItemSelection. */
+export interface ItemSelect {
+  isSelected: (id: string) => boolean;
+  /** Toggles an item, or with `range` selects every item from the last toggled one to it. */
+  toggle: (id: string, range: boolean) => void;
+  /** X, Shift+X, Cmd or Ctrl+A and Esc on a focused item; true when the key was handled. */
+  onKey: (event: KeyboardEvent<HTMLElement>, id: string) => boolean;
+  /** Cmd or Ctrl+click and Shift+click on an item; true when the click was a selection. */
+  onClick: (event: MouseEvent<HTMLElement>, id: string) => boolean;
+}
+
+const NONE: ItemSelect = {
+  isSelected: () => false,
+  toggle: () => undefined,
+  onKey: () => false,
+  onClick: () => false,
+};
+
+/**
+ * Selection gestures for RecordList, Board and Calendar, the same as DataTable's: X toggles the
+ * focused item and Shift+X selects the range from the last toggled one; Cmd or Ctrl+click toggles and
+ * Shift+click selects a range; Cmd or Ctrl+A selects every item and Esc clears. X follows the
+ * single-key shortcuts setting. `order` lists the item ids in reading order when a gesture happens.
+ */
+export function useItemSelection(
+  selection: ItemSelection | undefined,
+  order: () => readonly string[],
+): ItemSelect {
+  const anchor = useRef<string | null>(null);
+  if (!selection) return NONE;
+  const toggle = (id: string, range: boolean) => {
+    const next = new Set(selection.selected);
+    const ids = order();
+    const from = anchor.current === null ? -1 : ids.indexOf(anchor.current);
+    const to = ids.indexOf(id);
+    if (range && from !== -1 && to !== -1 && from !== to) {
+      for (const each of ids.slice(Math.min(from, to), Math.max(from, to) + 1)) next.add(each);
+    } else {
+      if (!next.delete(id)) next.add(id);
+      anchor.current = id;
+    }
+    selection.onChange(next);
+  };
+  return {
+    isSelected: (id) => selection.selected.has(id),
+    toggle,
+    onKey: (event, id) => {
+      const ctrl = event.ctrlKey || event.metaKey;
+      const key = event.key.toLowerCase();
+      if (ctrl && !event.altKey && !event.shiftKey && key === "a") {
+        event.preventDefault();
+        selection.onChange(new Set([...selection.selected, ...order()]));
+        return true;
+      }
+      if (!ctrl && !event.altKey && key === "x" && singleKeyShortcutsEnabled()) {
+        event.preventDefault();
+        toggle(id, event.shiftKey);
+        return true;
+      }
+      if (event.key === "Escape" && selection.selected.size > 0) {
+        // Esc clears the selection first; a second Esc reaches the page (closing a peek).
+        event.preventDefault();
+        event.stopPropagation();
+        selection.onChange(new Set());
+        return true;
+      }
+      return false;
+    },
+    onClick: (event, id) => {
+      if (event.metaKey || event.ctrlKey) toggle(id, false);
+      else if (event.shiftKey) toggle(id, true);
+      else return false;
+      event.preventDefault();
+      return true;
+    },
+  };
+}
+
+/** Whether a key opens an item's context menu: Shift+F10 or the Context Menu key (Section 11.7). */
+export function isMenuKey(event: KeyboardEvent<HTMLElement>): boolean {
+  return (event.key === "F10" && event.shiftKey) || event.key === "ContextMenu";
+}

package/src/lib/shortcut-targets.ts

@@ -0,0 +1,125 @@
+/**
+ * Shortcut targets (Section 11.2 principle 1): how a shell's key handler finds what a record or view
+ * shortcut acts on. A region of the page answers for a scope: the record full page and the side peek
+ * for `record`, a collection for `view`. The record and collection templates are regions by their
+ * template root (data-template), so no page carries anything more for them; any other region carries
+ * data-shortcut-scope, as the side peek does. The control that does an action carries
+ * data-shortcut="<registry id>". The handler clicks that control, or focuses it when it is a field,
+ * an option of a radio group or tab list, or carries data-shortcut-focus, so a feature binds its
+ * control to a shortcut by carrying the attribute.
+ *
+ * - The attribute may sit on the control itself or on a wrapper around it; in a wrapper, the selected
+ *   option of a radio group or tab list wins, else the first control.
+ * - A control belongs to the nearest region around it, so a peek or a nested collection keeps its own.
+ * - Disabled and hidden controls are skipped, except a `hidden` button that carries the attribute
+ *   itself: a page keeps such a button for an action that has no control of its own on screen.
+ */
+
+export const SHORTCUT_REGION =
+  '[data-shortcut-scope], [data-template="record"], [data-template="collection"]';
+
+/** The scope of each template root that is a region. */
+const TEMPLATE_SCOPE: Readonly<Record<string, string>> = { record: "record", collection: "view" };
+
+const CONTROL =
+  'button, a[href], input, select, textarea, summary, [contenteditable="true"], [role="button"], [role="radio"], [role="tab"], [role="combobox"], [role="menuitem"]';
+const SELECTED = '[aria-checked="true"], [aria-selected="true"], [aria-pressed="true"]';
+/** Menu and list triggers open on a key or pointer press, not on a click. */
+const POPUP = '[aria-haspopup="menu"], [aria-haspopup="true"], [aria-haspopup="listbox"]';
+/** Options are focused, not clicked: the selected one is already on, and the arrow keys move on. */
+const OPTION = '[role="radio"], [role="tab"]';
+const FIELD =
+  'input:not([type="button"]):not([type="submit"]):not([type="reset"]):not([type="checkbox"]):not([type="radio"]), select, textarea, [contenteditable="true"]';
+
+/**
+ * The region a key press acts in: the nearest marked region around the focused element or, while
+ * focus rests on the page or a container around the regions (the main content), the first region
+ * inside it.
+ */
+export function shortcutRegion(target: EventTarget | null): Element | null {
+  if (!(target instanceof Element)) return null;
+  return target.closest(SHORTCUT_REGION) ?? target.querySelector(SHORTCUT_REGION);
+}
+
+/** The scope a region answers for, such as `record` or `view`. */
+export function regionScope(region: Element | null): string | null {
+  if (!region) return null;
+  return (
+    region.getAttribute("data-shortcut-scope") ||
+    TEMPLATE_SCOPE[region.getAttribute("data-template") ?? ""] ||
+    null
+  );
+}
+
+function usable(control: HTMLElement): boolean {
+  if (control.matches(':disabled, [aria-disabled="true"]') || control.closest("[inert]")) {
+    return false;
+  }
+  return control.getClientRects().length > 0;
+}
+
+interface Target {
+  readonly control: HTMLElement;
+  readonly focus: boolean;
+}
+
+function targetIn(region: Element, id: string): Target | null {
+  for (const marked of region.querySelectorAll<HTMLElement>(`[data-shortcut="${id}"]`)) {
+    if (marked.closest(SHORTCUT_REGION) !== region) continue;
+    const focus = marked.hasAttribute("data-shortcut-focus");
+    if (marked.matches(CONTROL)) {
+      const kept = marked.hidden && marked.tagName === "BUTTON";
+      if (kept || usable(marked)) return { control: marked, focus };
+      continue;
+    }
+    const candidates = [
+      ...marked.querySelectorAll<HTMLElement>(SELECTED),
+      ...marked.querySelectorAll<HTMLElement>(CONTROL),
+    ];
+    const control = candidates.find((c) => c.matches(CONTROL) && usable(c));
+    if (control) return { control, focus };
+  }
+  return null;
+}
+
+/**
+ * The control in a region that does the shortcut's action, or null when the region has none. Ids
+ * are registry ids (letters, digits, dots and hyphens), so they quote safely in the selector.
+ */
+export function shortcutControl(region: Element, id: string): HTMLElement | null {
+  return targetIn(region, id)?.control ?? null;
+}
+
+function openPicker(select: HTMLSelectElement): void {
+  try {
+    select.showPicker();
+  } catch {
+    // Not every browser opens a select's picker from script; the select keeps focus.
+  }
+}
+
+/**
+ * Does the shortcut's action in a region: clicks its control, or focuses it (selecting a text
+ * input's text, such as a title). A menu trigger opens as the arrow key opens it, with focus on its
+ * first item, since menus open on a press rather than a click. Returns false when nothing in the
+ * region does the action, so the key goes on.
+ */
+export function runShortcut(region: Element, id: string): boolean {
+  const target = targetIn(region, id);
+  if (!target) return false;
+  const { control } = target;
+  if (target.focus || control.matches(FIELD) || control.matches(OPTION)) {
+    control.focus();
+    if (control instanceof HTMLInputElement) control.select();
+    // A list to pick from opens where the browser allows it, as assigning an owner expects.
+    if (control instanceof HTMLSelectElement && !target.focus) openPicker(control);
+  } else if (control.matches(POPUP)) {
+    control.focus();
+    control.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "ArrowDown", bubbles: true, cancelable: true }),
+    );
+  } else {
+    control.click();
+  }
+  return true;
+}

package/src/lib/theme.ts

@@ -0,0 +1,50 @@
+/**
+ * Theme switching by `data-theme` (ADR 0009): Dark is the default, Light is complete, Sunlight is the
+ * Compass maximum-contrast theme, and System follows the operating system between Dark and Light.
+ * The token build scopes every color variable to `[data-theme]`, so a switch needs no rebuild.
+ */
+
+export const themes = ["dark", "light", "sunlight"] as const;
+export type Theme = (typeof themes)[number];
+export type ThemePreference = Theme | "system";
+
+export const themePreferences: readonly ThemePreference[] = [...themes, "system"];
+
+export function isThemePreference(value: string): value is ThemePreference {
+  return (themePreferences as readonly string[]).includes(value);
+}
+
+const DARK_QUERY = "(prefers-color-scheme: dark)";
+
+function systemPrefersDark(): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return true;
+  return window.matchMedia(DARK_QUERY).matches;
+}
+
+/** The theme a preference renders: System resolves to Dark or Light from the operating system. */
+export function resolveTheme(
+  preference: ThemePreference,
+  prefersDark = systemPrefersDark(),
+): Theme {
+  if (preference === "system") return prefersDark ? "dark" : "light";
+  return preference;
+}
+
+/**
+ * Applies a preference to an element (the document root by default) and, for System, follows
+ * operating system changes until the returned cleanup runs.
+ */
+export function applyTheme(
+  preference: ThemePreference,
+  root: HTMLElement = document.documentElement,
+): () => void {
+  root.dataset["theme"] = resolveTheme(preference);
+  root.dataset["themePreference"] = preference;
+  if (preference !== "system" || typeof window.matchMedia !== "function") return () => undefined;
+  const query = window.matchMedia(DARK_QUERY);
+  const follow = (event: MediaQueryListEvent) => {
+    root.dataset["theme"] = event.matches ? "dark" : "light";
+  };
+  query.addEventListener("change", follow);
+  return () => query.removeEventListener("change", follow);
+}