@mrmeg/expo-ui 0.20.0 → 0.22.0

package/dist/state/SsrViewportContext.js

@@ -1,42 +1,13 @@
 import { createContext } from "react";
-/**
- * Default viewport used during SSR and the initial client render. Desktop is
- * chosen because:
- *   1. Most web traffic for app dashboards / marketing pages skews desktop.
- *   2. Desktop visitors see no layout reflow on hydration (SSR layout matches
- *      their actual viewport's breakpoint).
- *   3. Mobile visitors get one frame of desktop-styled content before
- *      `useDimensions`'s post-mount effect snaps to real dimensions — better
- *      than the inverse (every desktop visitor sees mobile-tiny then snap).
- *
- * Projects that skew mobile can override with their own Provider higher in
- * the tree, or per-page via a loader that detects from cookie / User-Agent.
- */
-export const SSR_VIEWPORT_DEFAULT_WIDTH = 1280;
-export const SSR_VIEWPORT_DEFAULT_HEIGHT = 800;
 /**
  * Per-request SSR viewport width. Consumed by `useDimensions` to seed the
- * initial responsive render so it matches what the user sees.
- *
- * Set the provider near the top of your tree (typically in a route component
- * whose loader detects the viewport from a cookie or User-Agent):
- *
- * ```tsx
- * import { SsrViewportContext } from "@mrmeg/expo-ui/state";
- * import { detectSsrViewportWidth } from "@/server/lib/ssrViewport";
- *
- * export const loader: LoaderFunction<{ ssrViewportWidth?: number }> = (request) => ({
- *   ssrViewportWidth: detectSsrViewportWidth(request),
- * });
- *
- * export default function Page() {
- *   const { ssrViewportWidth } = useLoaderData<typeof loader>();
- *   return (
- *     <SsrViewportContext.Provider value={ssrViewportWidth ?? SSR_VIEWPORT_DEFAULT_WIDTH}>
- *       ...
- *     </SsrViewportContext.Provider>
- *   );
- * }
- * ```
+ * server render and the browser's FIRST render, so a server that detected a
+ * phone lays the tree out at phone width and hydration matches byte-for-byte.
+ *
+ * `null` (the default, when no provider is mounted) means "no per-request
+ * signal" and `useDimensions` falls back to `DEFAULT_VIEWPORT_WIDTH`. The
+ * host app is expected to provide the same value on the server and on the
+ * client's first render — both derived from signals both sides can read
+ * (cookie / User-Agent), never from `window`.
  */
-export const SsrViewportContext = createContext(SSR_VIEWPORT_DEFAULT_WIDTH);
+export const SsrViewportContext = createContext(null);

package/dist/state/index.d.ts

@@ -1,6 +1,5 @@
 export * from "./globalUIStore";
 export * from "./notify";
+export * from "./SsrViewportContext";
 export * from "./themeStore";
 export * from "./themeColorScope";
-export * from "./ssrTheme";
-export * from "./SsrViewportContext";

package/dist/state/index.js

@@ -1,6 +1,5 @@
 export * from "./globalUIStore.js";
 export * from "./notify.js";
+export * from "./SsrViewportContext.js";
 export * from "./themeStore.js";
 export * from "./themeColorScope.js";
-export * from "./ssrTheme.js";
-export * from "./SsrViewportContext.js";

package/dist/state/themeStore.d.ts

@@ -3,15 +3,12 @@ import type { FontOverrides } from "../constants/fonts";
 export type ThemePreference = "system" | "light" | "dark";
 export type ResolvedTheme = "light" | "dark";
 /**
- * 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.
+ * Key the persisted preference lives under (`localStorage` on web,
+ * `AsyncStorage` on native). Exported so a host app's pre-boot script — e.g.
+ * the blocking color-scheme script in `app/+html.tsx` — can read the same
+ * value the store does.
  */
-export declare const THEME_COOKIE_NAME = "user-theme-preference";
+export declare const THEME_STORAGE_KEY = "user-theme-preference";
 /**
  * Per-scheme color overrides a host app can inject to brand the package.
  *
@@ -56,11 +53,10 @@ export type ThemeStore = {
     systemTheme: ResolvedTheme;
     /**
      * True once the persisted preference has actually been read (or explicitly
-     * set by the user). Until then, a web render must not trust `userTheme` /
-     * `systemTheme` — they still hold the SSR-safe boot defaults, and `useTheme`
-     * uses `SsrThemeSeedContext` (cookie-derived, identical on server and
-     * client) instead. Mirrors `hasLoadedOnboarding` in the host app's
-     * onboarding store.
+     * set by the user). Until then `userTheme` / `systemTheme` still hold the
+     * boot defaults ("system" / light), so a host app that needs to hold a
+     * paint until the real preference is known can wait on this. Mirrors
+     * `hasLoadedOnboarding` in the host app's onboarding store.
      */
     hasLoadedTheme: boolean;
     /**

package/dist/state/themeStore.js

@@ -3,25 +3,15 @@ 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.
+ * Key the persisted preference lives under (`localStorage` on web,
+ * `AsyncStorage` on native). Exported so a host app's pre-boot script — e.g.
+ * the blocking color-scheme script in `app/+html.tsx` — can read the same
+ * value the store does.
  */
-export const THEME_COOKIE_NAME = THEME_KEY;
-const THEME_COOKIE_MAX_AGE = 60 * 60 * 24 * 365; // 1 year
+export const THEME_STORAGE_KEY = THEME_KEY;
 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;
 }
@@ -33,13 +23,12 @@ 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;
-    // until then a web render reads `SsrThemeSeedContext` (cookie-derived) so
-    // the server and the browser paint the visitor's actual theme.
+    // Always start with "light" so a web app's first render matches the HTML
+    // shell that was rendered in Node at export time (no `window`, no storage).
+    // Real values arrive from `syncThemeFromEnvironment()` after mount; a host
+    // app's pre-boot script paints the correct background in the meantime.
     systemTheme: "light",
-    // False until persistence has been read. `useTheme` uses this to decide
-    // whether to trust store state or the per-request SSR seed.
+    // False until persistence has been read.
     hasLoadedTheme: false,
     // No overrides by default: the package renders with its built-in palette
     // until a host app calls `setColors`.
@@ -74,9 +63,6 @@ export const useThemeStore = create((set) => ({
         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 });
@@ -98,15 +84,6 @@ export const useThemeStore = create((set) => ({
             const saved = localStorage.getItem(THEME_KEY);
             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 });
@@ -156,18 +133,20 @@ export function startSystemThemeListener() {
 // 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".
+// The listener starts BEFORE `loadTheme()` on purpose: reading the real OS
+// scheme first means a `system` user resolves straight from the boot-default
+// "light" to their actual scheme in one commit.
 export function syncThemeFromEnvironment() {
     const stop = startSystemThemeListener();
     useThemeStore.getState().loadTheme();
     return stop;
 }
-// Native has no SSR mismatch concern, so keep the historical auto-init
-// behavior there. On web the host app must call `syncThemeFromEnvironment()`
-// from a top-level `useEffect` to avoid hydration mismatches.
+// Native can read persistence at module load, so keep the historical
+// auto-init behavior there. On web the host app must call
+// `syncThemeFromEnvironment()` from a top-level `useEffect`: web bundles are
+// also evaluated in Node when `expo export` renders the HTML shell, where
+// `window`/`localStorage` don't exist, and reading them during the browser's
+// first render would disagree with the markup being hydrated.
 if (Platform.OS !== "web") {
     useThemeStore.getState().loadTheme();
     startSystemThemeListener();

package/llms-full.md

@@ -109,7 +109,7 @@ Use this catalog before creating a new app-local primitive.
 | `Icon` | `@mrmeg/expo-ui/components` | Feather or custom icons with theme tokens | Avoid raw vector icons with hardcoded colors. |
 | `InputOTP` | `@mrmeg/expo-ui/components` | Verification code entry | Prefer over manually managed text input groups. |
 | `KeyboardAvoidingView` | `@mrmeg/expo-ui/components` | Native keyboard-aware layout roots, composer footers, and form-heavy subtrees | `UIProvider` already mounts one root by default; use this directly only for custom subtrees. |
-| `Label` | `@mrmeg/expo-ui/components` | Accessible form labels | Use with package form controls. |
+| `Label` | `@mrmeg/expo-ui/components` | Accessible form labels | Pair with two distinct ids: `nativeID` is the label's id, `htmlFor` is the input's `nativeID`. Never reuse one id for both. |
 | `MaxWidthContainer` | `@mrmeg/expo-ui/components` | Centered responsive width | Use for web and tablet constrained layouts. |
 | `Notification` | `@mrmeg/expo-ui/components` | Global toast surface | Trigger through `notify` (or `globalUIStore` for subscriptions/tests) with root `UIProvider`; optional actions dismiss after press. |
 | `Popover` | `@mrmeg/expo-ui/components` | Anchored contextual content | Requires root `UIProvider` portal setup. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrmeg/expo-ui",
-  "version": "0.20.0",
+  "version": "0.22.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [
@@ -125,7 +125,7 @@
     "zustand": ">=5.0.0 <6.0.0"
   },
   "devDependencies": {
-    "@types/react": "~19.2.17",
+    "@types/react": "~19.2.18",
     "typescript": "~6.0.3"
   }
 }

package/dist/state/ssrTheme.d.ts

@@ -1,41 +0,0 @@
-import type { ResolvedTheme, ThemePreference } from "./themeStore";
-/**
- * The theme values the FIRST render must use on web — server and client alike.
- *
- * `useThemeStore` is a module singleton shared by every concurrent SSR request,
- * so a per-request theme can never be written into it. This context is the
- * per-request channel instead: the host app resolves it from the request (a
- * cookie the client mirrors) and provides it above the tree, and `useTheme`
- * reads it until the store has loaded real persistence after mount.
- */
-export type SsrThemeSeed = {
-    userTheme: ThemePreference;
-    systemTheme: ResolvedTheme;
-};
-/**
- * What a first-time visitor gets: no persisted preference, light scheme. Same
- * values the store boots with, so a host app that never provides the context
- * behaves exactly as it did before the seed existed.
- */
-export declare const SSR_THEME_SEED_DEFAULT: SsrThemeSeed;
-/**
- * Per-request theme seed consumed by `useTheme`/`useStyles` while
- * `hasLoadedTheme` is false (i.e. on the server render and the client's first
- * render, before `syncThemeFromEnvironment()` reads real persistence).
- *
- * Provide it near the top of the tree from a value BOTH the server and the
- * browser can derive from the same bytes — a cookie. Reading `localStorage`
- * for this would reintroduce the hydration mismatch it exists to remove,
- * because the server cannot see `localStorage`.
- *
- * ```tsx
- * import { SsrThemeSeedContext } from "@mrmeg/expo-ui/state";
- *
- * <SsrThemeSeedContext.Provider value={seedFromCookie}>
- *   <App />
- * </SsrThemeSeedContext.Provider>
- * ```
- */
-export declare const SsrThemeSeedContext: import("react").Context<SsrThemeSeed>;
-/** Read the active SSR theme seed (the default when no provider is mounted). */
-export declare function useSsrThemeSeed(): SsrThemeSeed;

package/dist/state/ssrTheme.js

@@ -1,33 +0,0 @@
-import { createContext, use } from "react";
-/**
- * What a first-time visitor gets: no persisted preference, light scheme. Same
- * values the store boots with, so a host app that never provides the context
- * behaves exactly as it did before the seed existed.
- */
-export const SSR_THEME_SEED_DEFAULT = {
-    userTheme: "system",
-    systemTheme: "light",
-};
-/**
- * Per-request theme seed consumed by `useTheme`/`useStyles` while
- * `hasLoadedTheme` is false (i.e. on the server render and the client's first
- * render, before `syncThemeFromEnvironment()` reads real persistence).
- *
- * Provide it near the top of the tree from a value BOTH the server and the
- * browser can derive from the same bytes — a cookie. Reading `localStorage`
- * for this would reintroduce the hydration mismatch it exists to remove,
- * because the server cannot see `localStorage`.
- *
- * ```tsx
- * import { SsrThemeSeedContext } from "@mrmeg/expo-ui/state";
- *
- * <SsrThemeSeedContext.Provider value={seedFromCookie}>
- *   <App />
- * </SsrThemeSeedContext.Provider>
- * ```
- */
-export const SsrThemeSeedContext = createContext(SSR_THEME_SEED_DEFAULT);
-/** Read the active SSR theme seed (the default when no provider is mounted). */
-export function useSsrThemeSeed() {
-    return use(SsrThemeSeedContext);
-}