@mrmeg/expo-ui 0.17.0 → 0.20.0

package/dist/state/themeStore.js

@@ -2,6 +2,26 @@ import { Appearance, Platform } from "react-native";
 import { create } from "zustand";
 import AsyncStorage from "@react-native-async-storage/async-storage";
 const THEME_KEY = "user-theme-preference";
+/**
+ * Cookie name the web build mirrors the persisted preference into, so a
+ * server-rendered host can seed its first render with the visitor's real
+ * theme instead of shipping a light tree that recolors after hydration.
+ *
+ * Same name as the `localStorage` key on purpose: one string to grep, and the
+ * blocking color-scheme script in a host's `+html.tsx` already reads it.
+ * `localStorage` stays the source of truth; the cookie is a render hint only.
+ */
+export const THEME_COOKIE_NAME = THEME_KEY;
+const THEME_COOKIE_MAX_AGE = 60 * 60 * 24 * 365; // 1 year
+function isThemePreference(value) {
+    return value === "system" || value === "light" || value === "dark";
+}
+function writeThemeCookie(theme) {
+    if (Platform.OS !== "web" || typeof document === "undefined")
+        return;
+    document.cookie =
+        `${THEME_COOKIE_NAME}=${theme}; path=/; max-age=${THEME_COOKIE_MAX_AGE}; SameSite=Lax`;
+}
 export function resolveThemePreference(userTheme, systemTheme) {
     return userTheme === "system" ? systemTheme : userTheme;
 }
@@ -14,8 +34,13 @@ function getSystemTheme() {
 export const useThemeStore = create((set) => ({
     userTheme: "system",
     // Always start with "light" so SSR and the first client render agree.
-    // Real values are populated by `syncThemeFromEnvironment()` after mount.
+    // Real values are populated by `syncThemeFromEnvironment()` after mount;
+    // until then a web render reads `SsrThemeSeedContext` (cookie-derived) so
+    // the server and the browser paint the visitor's actual theme.
     systemTheme: "light",
+    // False until persistence has been read. `useTheme` uses this to decide
+    // whether to trust store state or the per-request SSR seed.
+    hasLoadedTheme: false,
     // No overrides by default: the package renders with its built-in palette
     // until a host app calls `setColors`.
     colorOverrides: {},
@@ -36,6 +61,7 @@ export const useThemeStore = create((set) => ({
     setTheme: (theme) => {
         set({
             userTheme: theme,
+            hasLoadedTheme: true,
             ...(theme === "system" ? { systemTheme: getSystemTheme() } : {}),
         });
         // Save directly when setting theme
@@ -43,10 +69,14 @@ export const useThemeStore = create((set) => ({
             AsyncStorage.setItem(THEME_KEY, theme).catch(() => {
                 // Silently fail if storage is not available
             });
+            return;
         }
-        else if (typeof window !== "undefined" && window.localStorage) {
+        if (typeof window !== "undefined" && window.localStorage) {
             localStorage.setItem(THEME_KEY, theme);
         }
+        // Dual-write: localStorage for the client, cookie for the next SSR render
+        // (so the server paints the right theme on the visitor's next request).
+        writeThemeCookie(theme);
     },
     setSystemTheme: (theme) => {
         set({ systemTheme: theme });
@@ -54,19 +84,32 @@ export const useThemeStore = create((set) => ({
     loadTheme: () => {
         if (Platform.OS !== "web") {
             AsyncStorage.getItem(THEME_KEY).then((saved) => {
-                if (saved && (saved === "system" || saved === "light" || saved === "dark")) {
+                if (saved && isThemePreference(saved)) {
                     set({ userTheme: saved });
                 }
             }).catch(() => {
                 // Use default if loading fails
+            }).finally(() => {
+                set({ hasLoadedTheme: true });
             });
+            return;
         }
-        else if (typeof window !== "undefined" && window.localStorage) {
+        if (typeof window !== "undefined" && window.localStorage) {
             const saved = localStorage.getItem(THEME_KEY);
-            if (saved && (saved === "system" || saved === "light" || saved === "dark")) {
+            if (saved && isThemePreference(saved)) {
                 set({ userTheme: saved });
+                // Backfill / repair the cookie so a visitor who set their preference
+                // before this mechanism existed (or who cleared cookies) gets a
+                // correctly themed server render on their very next request.
+                writeThemeCookie(saved);
+            }
+            else {
+                // Nothing persisted: mirror the implicit "system" default so the
+                // server stops guessing from a stale cookie.
+                writeThemeCookie("system");
             }
         }
+        set({ hasLoadedTheme: true });
     }
 }));
 let stopSystemThemeListener = null;
@@ -112,9 +155,15 @@ export function startSystemThemeListener() {
 // environment (persisted preference + OS color scheme listener). Safe to
 // call multiple times — `startSystemThemeListener` is idempotent — and
 // returns the unsubscribe so it can be used directly inside `useEffect`.
+//
+// The listener starts BEFORE `loadTheme()` on purpose: `loadTheme` is what
+// flips `hasLoadedTheme`, which is the moment web renders stop trusting the
+// SSR seed and start trusting store state. Reading the real OS scheme first
+// means a `system` user never sees a frame of the boot-default "light".
 export function syncThemeFromEnvironment() {
+    const stop = startSystemThemeListener();
     useThemeStore.getState().loadTheme();
-    return startSystemThemeListener();
+    return stop;
 }
 // Native has no SSR mismatch concern, so keep the historical auto-init
 // behavior there. On web the host app must call `syncThemeFromEnvironment()`

package/llms-full.md

@@ -51,9 +51,14 @@ package `tx` props translated by its app-owned i18n instance.
 ## Theme Rules
 
 Use `useTheme()` and `useStyles()` from `@mrmeg/expo-ui/hooks`. Use semantic
-tokens such as `background`, `foreground`, `card`, `popover`, `border`,
-`input`, `ring`, `primary`, `secondary`, `accent`, `mutedForeground`,
-`destructive`, `success`, and `warning`.
+tokens such as `surfaceSunken`, `background`, `foreground`, `card`, `popover`,
+`border`, `borderStrong`, `input`, `ring`, `primary`, `secondary`, `accent`,
+`mutedForeground`, `destructive`, `success`, and `warning`.
+
+Surfaces form a tier ladder rather than a shadow scale: `surfaceSunken` (app
+chrome such as the Drawer rail) < `background` (content) < `card`/`popover`
+(raised) < `muted` (chips, insets). Use `borderStrong` for hairlines on filled
+or raised elements, where `border` would blend into the fill.
 
 Use `StyledText` and semantic text aliases instead of raw `Text` for app UI.
 Use package controls instead of hardcoded Pressable/View/Text combinations.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrmeg/expo-ui",
-  "version": "0.17.0",
+  "version": "0.20.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [