feat(decnet_web/Layout): topbar dark/light toggle with circular reveal

User-facing theme toggle ships now that the design system has been audited end-to-end. A Sun/Moon button lives between the threat indicator and the SYSTEM status pill in the topbar — same slim 28x28 voice as the rest of the topbar controls, no chrome shouting at the user. Click coords drive a View Transitions API circle clip-path that grows from the cursor to the farthest viewport corner over 520ms with the project's standard --ease curve. Browsers without startViewTransition (older Firefox, Safari < 18) fall through to an unanimated swap — the hook returns instantly in that case. Persistence is two-tier: - localStorage decnet_theme — the user's saved preference, the thing the topbar toggle writes. Survives reloads, applies everywhere. - sessionStorage decnet_theme_lab — dev-mode lab override (Task 3). Tab-scoped, wins on boot so devs can A/B without nuking the saved preference. App.tsx hydrates both on first mount in the right order so the correct theme is on <html> before the first paint. useThemeToggle is a small hook in lib/ rather than a Layout-only helper so the same toggle can be reused later from a settings page or hotkey.
2026-05-09 04:01:24 -04:00
parent 9cab37db3a
commit 438a6e3e45
7 changed files with 262 additions and 9 deletions
--- a/decnet_web/src/lib/tests/useThemeToggle.test.ts
+++ b/decnet_web/src/lib/tests/useThemeToggle.test.ts
@@ -0,0 +1,71 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import {
+  useThemeToggle,
+  readSavedTheme,
+  readEffectiveBootTheme,
+  THEME_STORAGE_KEY,
+  LAB_THEME_STORAGE_KEY,
+} from '../useThemeToggle';
+
+describe('useThemeToggle', () => {
+  beforeEach(() => {
+    localStorage.clear();
+    sessionStorage.clear();
+    delete document.documentElement.dataset.theme;
+  });
+
+  it('readSavedTheme defaults to dark', () => {
+    expect(readSavedTheme()).toBe('dark');
+  });
+
+  it('readSavedTheme returns light when saved', () => {
+    localStorage.setItem(THEME_STORAGE_KEY, 'light');
+    expect(readSavedTheme()).toBe('light');
+  });
+
+  it('readSavedTheme rejects junk values', () => {
+    localStorage.setItem(THEME_STORAGE_KEY, 'banana');
+    expect(readSavedTheme()).toBe('dark');
+  });
+
+  it('readEffectiveBootTheme prefers sessionStorage lab over localStorage', () => {
+    localStorage.setItem(THEME_STORAGE_KEY, 'dark');
+    sessionStorage.setItem(LAB_THEME_STORAGE_KEY, 'light');
+    expect(readEffectiveBootTheme()).toBe('light');
+  });
+
+  it('readEffectiveBootTheme falls back to localStorage when no lab override', () => {
+    localStorage.setItem(THEME_STORAGE_KEY, 'light');
+    expect(readEffectiveBootTheme()).toBe('light');
+  });
+
+  it('toggle flips theme, writes localStorage, sets data-theme', () => {
+    const { result } = renderHook(() => useThemeToggle());
+    expect(result.current.theme).toBe('dark');
+
+    act(() => result.current.toggle({ clientX: 100, clientY: 50 }));
+    expect(result.current.theme).toBe('light');
+    expect(localStorage.getItem(THEME_STORAGE_KEY)).toBe('light');
+    expect(document.documentElement.dataset.theme).toBe('light');
+
+    act(() => result.current.toggle({ clientX: 100, clientY: 50 }));
+    expect(result.current.theme).toBe('dark');
+    expect(localStorage.getItem(THEME_STORAGE_KEY)).toBe('dark');
+    expect(document.documentElement.dataset.theme).toBe('dark');
+  });
+
+  it('toggle without click coords still flips theme', () => {
+    const { result } = renderHook(() => useThemeToggle());
+    act(() => result.current.toggle());
+    expect(result.current.theme).toBe('light');
+    expect(document.documentElement.dataset.theme).toBe('light');
+  });
+
+  it('hydrates from data-theme attribute set pre-mount by App.tsx', () => {
+    document.documentElement.dataset.theme = 'light';
+    localStorage.setItem(THEME_STORAGE_KEY, 'light');
+    const { result } = renderHook(() => useThemeToggle());
+    expect(result.current.theme).toBe('light');
+  });
+});
--- a/decnet_web/src/lib/useThemeToggle.ts
+++ b/decnet_web/src/lib/useThemeToggle.ts
@@ -0,0 +1,112 @@
+import { useCallback, useEffect, useState } from 'react';
+
+/* User-facing dark/light theme management.
+ *
+ * Two persistence layers:
+ *   - localStorage `decnet_theme`  — the user's saved preference.
+ *     Survives reloads, applies to every tab.
+ *   - sessionStorage `decnet_theme_lab` — dev-mode lab override
+ *     (set from /theme-lab). Tab-scoped, wins over localStorage on
+ *     boot so devs can A/B without nuking their saved preference.
+ *
+ * Both write the same `data-theme` attribute on <html>. The toggle
+ * called from the topbar updates localStorage; the lab toggle
+ * (Task 3) updates sessionStorage. App.tsx hydrates on boot.
+ *
+ * Animation: when supported, the swap rides the View Transitions
+ * API with a circle clip-path that grows from the click point to
+ * cover the viewport diagonal. Browsers without the API still get
+ * the theme swap, just without the reveal. */
+
+export const THEME_STORAGE_KEY = 'decnet_theme';
+export const LAB_THEME_STORAGE_KEY = 'decnet_theme_lab';
+
+export type Theme = 'dark' | 'light';
+
+function isTheme(v: unknown): v is Theme {
+  return v === 'dark' || v === 'light';
+}
+
+export function readSavedTheme(): Theme {
+  try {
+    const v = localStorage.getItem(THEME_STORAGE_KEY);
+    return isTheme(v) ? v : 'dark';
+  } catch {
+    return 'dark';
+  }
+}
+
+export function readEffectiveBootTheme(): Theme {
+  // sessionStorage (lab) wins over localStorage on boot.
+  try {
+    const lab = sessionStorage.getItem(LAB_THEME_STORAGE_KEY);
+    if (isTheme(lab)) return lab;
+  } catch { /* ignore */ }
+  return readSavedTheme();
+}
+
+interface ViewTransitionDoc {
+  startViewTransition?: (cb: () => void | Promise<void>) => {
+    ready: Promise<void>;
+    finished: Promise<void>;
+  };
+}
+
+/* Animate the theme swap with a circle clip-path that grows from
+ * (x, y) to the farthest viewport corner. Falls back to an
+ * unanimated swap when View Transitions aren't available. */
+function animateSwap(next: Theme, x: number, y: number): void {
+  const docVT = document as unknown as ViewTransitionDoc;
+  const apply = () => { document.documentElement.dataset.theme = next; };
+
+  if (typeof docVT.startViewTransition !== 'function') {
+    apply();
+    return;
+  }
+
+  const transition = docVT.startViewTransition(apply)!;
+  transition.ready.then(() => {
+    const endRadius = Math.hypot(
+      Math.max(x, window.innerWidth - x),
+      Math.max(y, window.innerHeight - y),
+    );
+    document.documentElement.animate(
+      {
+        clipPath: [
+          `circle(0px at ${x}px ${y}px)`,
+          `circle(${endRadius}px at ${x}px ${y}px)`,
+        ],
+      },
+      {
+        duration: 520,
+        easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+        pseudoElement: '::view-transition-new(root)',
+      },
+    );
+  }).catch(() => { /* user-cancelled or unsupported pseudo, ignore */ });
+}
+
+export function useThemeToggle() {
+  const [theme, setTheme] = useState<Theme>(() => readSavedTheme());
+
+  /* Keep React state aligned with whatever boot-time hydration set
+   * on <html>, in case App.tsx already wrote the attribute. */
+  useEffect(() => {
+    const fromAttr = document.documentElement.dataset.theme;
+    if (isTheme(fromAttr) && fromAttr !== theme) {
+      setTheme(fromAttr);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const toggle = useCallback((e?: { clientX?: number; clientY?: number }) => {
+    const next: Theme = theme === 'dark' ? 'light' : 'dark';
+    const x = e?.clientX ?? window.innerWidth - 32;
+    const y = e?.clientY ?? 32;
+    try { localStorage.setItem(THEME_STORAGE_KEY, next); } catch { /* ignore */ }
+    animateSwap(next, x, y);
+    setTheme(next);
+  }, [theme]);
+
+  return { theme, toggle };
+}