@mrmeg/expo-ui 0.18.0 → 0.21.0

package/dist/state/themeStore.js

@@ -2,6 +2,16 @@ 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";
+/**
+ * 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_STORAGE_KEY = THEME_KEY;
+function isThemePreference(value) {
+    return value === "system" || value === "light" || value === "dark";
+}
 export function resolveThemePreference(userTheme, systemTheme) {
     return userTheme === "system" ? systemTheme : userTheme;
 }
@@ -13,9 +23,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.
+    // 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.
+    hasLoadedTheme: false,
     // No overrides by default: the package renders with its built-in palette
     // until a host app calls `setColors`.
     colorOverrides: {},
@@ -36,6 +50,7 @@ export const useThemeStore = create((set) => ({
     setTheme: (theme) => {
         set({
             userTheme: theme,
+            hasLoadedTheme: true,
             ...(theme === "system" ? { systemTheme: getSystemTheme() } : {}),
         });
         // Save directly when setting theme
@@ -43,8 +58,9 @@ 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);
         }
     },
@@ -54,19 +70,23 @@ 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 });
             }
         }
+        set({ hasLoadedTheme: true });
     }
 }));
 let stopSystemThemeListener = null;
@@ -112,13 +132,21 @@ 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: 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 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()`
-// 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

@@ -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.
@@ -104,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.18.0",
+  "version": "0.21.0",
   "private": false,
   "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
   "keywords": [

package/dist/state/SsrViewportContext.d.ts

@@ -1,41 +0,0 @@
-/**
- * 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 declare const SSR_VIEWPORT_DEFAULT_WIDTH = 1280;
-export declare 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>
- *   );
- * }
- * ```
- */
-export declare const SsrViewportContext: import("react").Context<number>;

package/dist/state/SsrViewportContext.js

@@ -1,42 +0,0 @@
-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>
- *   );
- * }
- * ```
- */
-export const SsrViewportContext = createContext(SSR_VIEWPORT_DEFAULT_WIDTH);