@eifi1/ui-kit 0.4.1 → 0.5.0

package/src/theme/palette-store.ts

@@ -0,0 +1,94 @@
+import { useEffect } from "react";
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import type { StoreApi, UseBoundStore } from "zustand";
+import { logger } from "../lib/logger";
+import type { HeatStops } from "./chart-palette";
+import { applyTokenSet, DEFAULT_PRESET, presetById, type TokenSet } from "./palette-presets";
+import type { ThemeState, ThemeMode } from "./theme-store";
+
+/**
+ * Pre-hydration counterpart to `applyPersistedTheme`: read the palette id
+ * persisted under `storageKey` straight from localStorage and apply that preset's
+ * tokens for the given resolved `mode` to <html>, BEFORE React mounts (no flash of
+ * the default palette). Falls back to the default preset for missing/malformed
+ * state, so an app entrypoint never re-types the persist envelope.
+ */
+export function applyPersistedPalette(storageKey: string, mode: ThemeMode): void {
+  let id = DEFAULT_PRESET.id;
+  try {
+    const blob = JSON.parse(localStorage.getItem(storageKey) ?? "{}") as {
+      state?: { id?: string };
+    };
+    if (blob.state?.id) id = blob.state.id;
+  } catch {
+    /* malformed storage → default preset */
+  }
+  applyTokenSet(document.documentElement, presetById(id)[mode]);
+}
+
+// The palette layer flips the whole app between candidate appearance presets at
+// runtime (feedback #307), re-skinning every token-driven surface and chart.
+// Persisted like the theme so a reload keeps the selection.
+interface PaletteState {
+  id: string;
+  setId: (id: string) => void;
+}
+
+/**
+ * Build a palette store bound to a consumer-supplied localStorage key, wired to
+ * that app's theme store (for the active light/dark mode). Returns the palette
+ * hook plus the effect + selector hooks that read the active preset's tokens.
+ */
+export function createPaletteStore(
+  storageKey: string,
+  useTheme: UseBoundStore<StoreApi<ThemeState>>,
+) {
+  const usePalette = create<PaletteState>()(
+    logger(
+      persist(
+        (set) => ({
+          id: DEFAULT_PRESET.id,
+          setId: (id) => set({ id }),
+        }),
+        { name: storageKey, version: 1 },
+      ),
+      "palette",
+    ),
+  );
+
+  /** Apply the active preset's tokens to <html> as inline CSS custom properties,
+   *  re-applying when the preset or the light/dark theme changes. Tailwind v4
+   *  strips a bare root token block from the bundle, so this inline write from
+   *  the TS source of truth is what actually drives the colours. */
+  function useApplyPalette(): void {
+    const id = usePalette((s) => s.id);
+    const mode = useTheme((s) => s.mode);
+    useEffect(() => {
+      applyTokenSet(document.documentElement, presetById(id)[mode]);
+    }, [id, mode]);
+  }
+
+  /** The active preset's token set for the current theme — the source for the
+   *  JS-interpolated charts (treemap fills, heatmap stops) that can't read CSS
+   *  vars. */
+  function useActiveTokenSet(): TokenSet {
+    const id = usePalette((s) => s.id);
+    const mode = useTheme((s) => s.mode);
+    return presetById(id)[mode];
+  }
+
+  /** The 9 categorical chart hues for the active preset/theme (treemap cells). */
+  function useChartHex(): string[] {
+    return useActiveTokenSet().chart;
+  }
+
+  /** The active preset/theme heatmap interpolation stops. */
+  function useHeatStops(): HeatStops {
+    return useActiveTokenSet().heat;
+  }
+
+  return { usePalette, useApplyPalette, useActiveTokenSet, useChartHex, useHeatStops };
+}
+
+export type PaletteStore = ReturnType<typeof createPaletteStore>;

package/src/theme/theme-store.ts

@@ -0,0 +1,145 @@
+import { useEffect } from "react";
+import { create } from "zustand";
+import { persist } from "zustand/middleware";
+import { logger } from "../lib/logger";
+
+export type ThemeMode = "light" | "dark";
+/** What the user chose; "system" tracks the OS `prefers-color-scheme`. */
+export type ThemePreference = "light" | "dark" | "system";
+
+export interface ThemeState {
+  /** The user's choice (persisted). */
+  preference: ThemePreference;
+  /** The RESOLVED light/dark actually in effect (system → OS). Read this for
+   *  anything that needs the concrete theme (e.g. token selection, toasts). */
+  mode: ThemeMode;
+  setPreference: (preference: ThemePreference) => void;
+  /** Set an explicit light/dark choice (preference follows). */
+  setMode: (mode: ThemeMode) => void;
+  /** Flip the effective theme to the opposite explicit choice. */
+  toggle: () => void;
+}
+
+function systemPreference(): ThemeMode {
+  try {
+    return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  } catch {
+    return "light";
+  }
+}
+
+function resolve(preference: ThemePreference): ThemeMode {
+  return preference === "system" ? systemPreference() : preference;
+}
+
+/** Normalize a persisted theme-state blob to a valid preference. Older blobs
+ *  persisted the concrete `mode` (light/dark); carry that over as an explicit
+ *  preference so the choice survives. Shared by the store's `migrate` and the
+ *  pre-hydration {@link applyPersistedTheme}. */
+function preferenceFromState(
+  s: { mode?: string; preference?: string } | null | undefined,
+): ThemePreference {
+  if (s?.preference === "light" || s?.preference === "dark" || s?.preference === "system") {
+    return s.preference;
+  }
+  if (s?.mode === "light" || s?.mode === "dark") return s.mode;
+  return "system";
+}
+
+/** Toggle the `.dark` class on <html> for a resolved light/dark mode. */
+function applyThemeClass(mode: ThemeMode): void {
+  const root = document.documentElement;
+  if (mode === "dark") root.classList.add("dark");
+  else root.classList.remove("dark");
+}
+
+/**
+ * Pre-hydration: read the theme PREFERENCE persisted under `storageKey` straight
+ * from localStorage, resolve it to a concrete light/dark mode, and toggle the
+ * `.dark` class on <html> — BEFORE React and the store mount, so the first paint
+ * already has the right theme (no flash). Returns the resolved mode so the caller
+ * can chain {@link applyPersistedPalette}. Encapsulates the zustand-persist
+ * envelope + the legacy `mode`→`preference` fallback so apps never re-type the
+ * storage shape in their entrypoint.
+ */
+export function applyPersistedTheme(storageKey: string): ThemeMode {
+  let preference: ThemePreference = "system";
+  try {
+    const blob = JSON.parse(localStorage.getItem(storageKey) ?? "{}") as {
+      state?: { mode?: string; preference?: string };
+    };
+    preference = preferenceFromState(blob.state);
+  } catch {
+    /* malformed storage → system */
+  }
+  const mode = resolve(preference);
+  applyThemeClass(mode);
+  return mode;
+}
+
+/**
+ * Build a theme store bound to a consumer-supplied localStorage key. Tracks a
+ * light/dark/system PREFERENCE (feedback #330) and exposes the resolved `mode`.
+ * Returns the `useTheme` hook plus a `useApplyTheme` effect that toggles the
+ * `.dark` class on <html> and, while on "system", follows OS theme changes live.
+ */
+export function createThemeStore(storageKey: string) {
+  const useTheme = create<ThemeState>()(
+    logger(
+      persist(
+        (set, get) => ({
+          preference: "system" as ThemePreference,
+          mode: systemPreference(),
+          setPreference: (preference) => set({ preference, mode: resolve(preference) }),
+          setMode: (mode) => set({ preference: mode, mode }),
+          toggle: () => {
+            const next: ThemeMode = get().mode === "dark" ? "light" : "dark";
+            set({ preference: next, mode: next });
+          },
+        }),
+        {
+          name: storageKey,
+          version: 2,
+          // Only the preference is persisted; `mode` is derived on load.
+          partialize: (s) => ({ preference: s.preference }),
+          migrate: (persistedState): { preference: ThemePreference } => ({
+            preference: preferenceFromState(
+              persistedState as { mode?: string; preference?: string } | null,
+            ),
+          }),
+          onRehydrateStorage: () => (state) => {
+            // The persisted preference decides the concrete mode at load.
+            if (state) state.mode = resolve(state.preference);
+          },
+        },
+      ),
+      "theme",
+    ),
+  );
+
+  function useApplyTheme(): void {
+    const mode = useTheme((s) => s.mode);
+    const preference = useTheme((s) => s.preference);
+    useEffect(() => {
+      applyThemeClass(mode);
+    }, [mode]);
+    // While tracking the system, follow OS theme changes live.
+    useEffect(() => {
+      if (preference !== "system") return;
+      let mq: MediaQueryList;
+      try {
+        mq = window.matchMedia("(prefers-color-scheme: dark)");
+      } catch {
+        return;
+      }
+      const onChange = () => useTheme.setState({ mode: mq.matches ? "dark" : "light" });
+      onChange();
+      mq.addEventListener?.("change", onChange);
+      return () => mq.removeEventListener?.("change", onChange);
+    }, [preference]);
+  }
+
+  return { useTheme, useApplyTheme };
+}
+
+export type ThemeStore = ReturnType<typeof createThemeStore>;