feat(KAN-17): add Emerald design system and resilient themes

resources/js/composables/useAppearance.ts

@@ -1,124 +1,107 @@
-import type { ComputedRef, Ref } from 'vue';
-import { computed, onMounted, ref } from 'vue';
+import type { App, ComputedRef, InjectionKey, Ref } from 'vue';
+import { computed, inject, readonly, ref } from 'vue';
 import type { Appearance, ResolvedAppearance } from '@/types';
 
 export type { Appearance, ResolvedAppearance };
 
 export type UseAppearanceReturn = {
-    appearance: Ref<Appearance>;
+    appearance: Readonly<Ref<Appearance>>;
     resolvedAppearance: ComputedRef<ResolvedAppearance>;
     updateAppearance: (value: Appearance) => void;
 };
 
-export function updateTheme(value: Appearance): void {
-    if (typeof window === 'undefined') {
-        return;
-    }
+const appearanceKey: InjectionKey<UseAppearanceReturn> = Symbol('appearance');
 
-    if (value === 'system') {
-        const mediaQueryList = window.matchMedia(
-            '(prefers-color-scheme: dark)',
-        );
-        const systemTheme = mediaQueryList.matches ? 'dark' : 'light';
+export function normalizeAppearance(value: unknown): Appearance {
+    return value === 'light' || value === 'dark' ? value : 'system';
+}
 
+/** Each Vue app owns its state, including each server-rendered request. */
+export function createAppearance(initialAppearance: Appearance = 'system') {
+    const appearance = ref<Appearance>(normalizeAppearance(initialAppearance));
+    const systemDark = ref(false);
+    const resolvedAppearance = computed<ResolvedAppearance>(() =>
+        appearance.value === 'system'
+            ? systemDark.value
+                ? 'dark'
+                : 'light'
+            : appearance.value,
+    );
+
+    function applyTheme(): void {
         document.documentElement.classList.toggle(
             'dark',
-            systemTheme === 'dark',
+            resolvedAppearance.value === 'dark',
         );
-    } else {
-        document.documentElement.classList.toggle('dark', value === 'dark');
-    }
-}
-
-const setCookie = (name: string, value: string, days = 365) => {
-    if (typeof document === 'undefined') {
-        return;
+        document.documentElement.style.colorScheme = resolvedAppearance.value;
+        document.documentElement.dataset.appearance = appearance.value;
     }
 
-    const maxAge = days * 24 * 60 * 60;
-
-    document.cookie = `${name}=${value};path=/;max-age=${maxAge};SameSite=Lax`;
-};
-
-const mediaQuery = () => {
-    if (typeof window === 'undefined') {
-        return null;
-    }
-
-    return window.matchMedia('(prefers-color-scheme: dark)');
-};
-
-const getStoredAppearance = () => {
-    if (typeof window === 'undefined') {
-        return null;
-    }
-
-    return localStorage.getItem('appearance') as Appearance | null;
-};
-
-const prefersDark = (): boolean => {
-    if (typeof window === 'undefined') {
-        return false;
-    }
-
-    return window.matchMedia('(prefers-color-scheme: dark)').matches;
-};
-
-const handleSystemThemeChange = () => {
-    const currentAppearance = getStoredAppearance();
-
-    updateTheme(currentAppearance || 'system');
-};
-
-export function initializeTheme(): void {
-    if (typeof window === 'undefined') {
-        return;
-    }
-
-    // Initialize theme from saved preference or default to system...
-    const savedAppearance = getStoredAppearance();
-    updateTheme(savedAppearance || 'system');
-
-    // Set up system theme change listener...
-    mediaQuery()?.addEventListener('change', handleSystemThemeChange);
-}
-
-const appearance = ref<Appearance>('system');
-
-export function useAppearance(): UseAppearanceReturn {
-    onMounted(() => {
-        const savedAppearance = localStorage.getItem(
-            'appearance',
-        ) as Appearance | null;
-
-        if (savedAppearance) {
-            appearance.value = savedAppearance;
-        }
-    });
-
-    const resolvedAppearance = computed<ResolvedAppearance>(() => {
-        if (appearance.value === 'system') {
-            return prefersDark() ? 'dark' : 'light';
+    function updateAppearance(value: Appearance): void {
+        appearance.value = normalizeAppearance(value);
+        if (typeof window === 'undefined') {
+            return;
         }
 
-        return appearance.value;
-    });
+        applyTheme();
+        try {
+            window.localStorage.setItem('appearance', appearance.value);
+        } catch {
+            // Private or embedded browsers may deny storage; the current theme still works.
+        }
+        document.cookie = `appearance=${appearance.value};path=/;max-age=31536000;SameSite=Lax`;
+    }
 
-    function updateAppearance(value: Appearance) {
-        appearance.value = value;
+    function handleSystemChange(event: MediaQueryListEvent): void {
+        systemDark.value = event.matches;
+        applyTheme();
+    }
 
-        // Store in localStorage for client-side persistence...
-        localStorage.setItem('appearance', value);
-
-        // Store in cookie for SSR...
-        setCookie('appearance', value);
-
-        updateTheme(value);
+    function handleStorageChange(event: StorageEvent): void {
+        if (event.key === 'appearance' || event.key === null) {
+            updateAppearance(normalizeAppearance(event.newValue));
+        }
     }
 
     return {
-        appearance,
+        appearance: readonly(appearance),
         resolvedAppearance,
         updateAppearance,
+        install(app: App): void {
+            app.provide(appearanceKey, {
+                appearance: readonly(appearance),
+                resolvedAppearance,
+                updateAppearance,
+            });
+            if (typeof window === 'undefined') {
+                return;
+            }
+
+            // The blocking head script already reconciled local storage and the SSR cookie.
+            appearance.value = normalizeAppearance(
+                document.documentElement.dataset.appearance ??
+                    initialAppearance,
+            );
+            const media = window.matchMedia('(prefers-color-scheme: dark)');
+            systemDark.value = media.matches;
+            applyTheme();
+            media.addEventListener('change', handleSystemChange);
+            window.addEventListener('storage', handleStorageChange);
+
+            app.onUnmount(() => {
+                media.removeEventListener('change', handleSystemChange);
+                window.removeEventListener('storage', handleStorageChange);
+            });
+        },
     };
 }
+
+export function useAppearance(): UseAppearanceReturn {
+    const appearance = inject(appearanceKey);
+    if (!appearance) {
+        throw new Error(
+            'The appearance plugin must be installed before useAppearance().',
+        );
+    }
+    return appearance;
+}