@mrmeg/expo-ui 0.1.7 → 0.1.8

package/LLM_USAGE.md

@@ -139,6 +139,11 @@ const { styles } = useStyles(({ theme, spacing, withAlpha }) => ({
 }));
 ```
 
+When the saved theme preference is `system`, the package theme store owns the
+OS color-scheme subscription, including web `prefers-color-scheme`. Do not add
+app-local Appearance or `matchMedia` listeners for package components; import
+`useTheme()`, `useStyles()`, and `useThemeStore` from `@mrmeg/expo-ui`.
+
 ## Component Use-Case Index
 
 Use this table before creating a new app-local primitive.

package/README.md

@@ -97,6 +97,11 @@ const styles = StyleSheet.create({
 
 `useTheme()` returns the active `theme`, resolved `scheme`, persisted `currentTheme`, `setTheme`, `toggleTheme`, cross-platform shadow helpers, a web focus-ring helper, contrast helpers, and `withAlpha`. `getShadowStyle(type)` supports `base`, `soft`, `sharp`, `subtle`, `elevated`, `glow`, `glass`, `card`, `cardHover`, and `cardSubtle`. Use semantic tokens such as `theme.colors.background`, `foreground`, `card`, `popover`, `border`, `input`, `ring`, `primary`, `secondary`, `accent`, `mutedForeground`, `destructive`, `success`, and `warning`. `primary` is the neutral action color, `secondary` is a neutral secondary surface, `accent` is the teal highlight color, `input` is the default form-control border, and `ring` is the focus outline color.
 
+When `currentTheme` is `"system"`, the package tracks the OS color scheme and
+updates all `useTheme()` and `useStyles()` consumers through the package theme
+store. Apps should not add their own Appearance or `matchMedia` listeners just
+to make package components follow system light/dark changes.
+
 Use `useStyles()` when a component needs memoized theme-aware styles. The style factory receives `{ theme, spacing, withAlpha }`, and the returned hook value also includes the normal `useTheme()` helpers.
 
 ```tsx

package/dist/hooks/useTheme.js

@@ -1,7 +1,7 @@
 import { useCallback, useEffect, useMemo } from "react";
 import { colors } from "../constants/colors.js";
-import { useColorScheme as useColorSchemeDefault, Platform, StyleSheet } from "react-native";
-import { useThemeStore } from "../state/themeStore.js";
+import { Platform, StyleSheet } from "react-native";
+import { resolveThemePreference, useThemeStore } from "../state/themeStore.js";
 import { spacing as spacingConstants } from "../constants/spacing.js";
 // Module-level cache for contrast calculations to avoid memory leak
 // and share across components
@@ -45,14 +45,10 @@ function getCachedOrCompute(key, compute) {
  */
 export function useTheme() {
     const userTheme = useThemeStore((s) => s.userTheme);
+    const systemTheme = useThemeStore((s) => s.systemTheme);
     const setTheme = useThemeStore((s) => s.setTheme);
-    let defaultScheme = useColorSchemeDefault();
-    // Ensure a scheme is selected, even if we fail to get one
-    if (!defaultScheme) {
-        defaultScheme = "light";
-    }
     // Determine which theme to use (user preference or system)
-    const effectiveScheme = userTheme === "system" ? defaultScheme : userTheme;
+    const effectiveScheme = resolveThemePreference(userTheme, systemTheme);
     const theme = colors[effectiveScheme];
     // Sync theme to DOM so CSS in +html.tsx follows the app's runtime theme
     useEffect(() => {

package/dist/state/themeStore.d.ts

@@ -1,6 +1,13 @@
+export type ThemePreference = "system" | "light" | "dark";
+export type ResolvedTheme = "light" | "dark";
 export type ThemeStore = {
-    userTheme: "system" | "light" | "dark";
-    setTheme: (theme: "system" | "light" | "dark") => void;
+    userTheme: ThemePreference;
+    systemTheme: ResolvedTheme;
+    setTheme: (theme: ThemePreference) => void;
+    setSystemTheme: (theme: ResolvedTheme) => void;
     loadTheme: () => void;
 };
+export declare function resolveThemePreference(userTheme: ThemePreference, systemTheme: ResolvedTheme): ResolvedTheme;
 export declare const useThemeStore: import("zustand").UseBoundStore<import("zustand").StoreApi<ThemeStore>>;
+export declare function syncSystemTheme(): void;
+export declare function startSystemThemeListener(): () => void;

package/dist/state/themeStore.js

@@ -1,11 +1,24 @@
-import { Platform } from "react-native";
+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";
+export function resolveThemePreference(userTheme, systemTheme) {
+    return userTheme === "system" ? systemTheme : userTheme;
+}
+function getSystemTheme() {
+    if (Platform.OS === "web" && typeof window !== "undefined" && typeof window.matchMedia === "function") {
+        return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+    }
+    return Appearance.getColorScheme() === "dark" ? "dark" : "light";
+}
 export const useThemeStore = create((set) => ({
     userTheme: "system",
+    systemTheme: getSystemTheme(),
     setTheme: (theme) => {
-        set({ userTheme: theme });
+        set({
+            userTheme: theme,
+            ...(theme === "system" ? { systemTheme: getSystemTheme() } : {}),
+        });
         // Save directly when setting theme
         if (Platform.OS !== "web") {
             AsyncStorage.setItem(THEME_KEY, theme).catch(() => {
@@ -16,6 +29,9 @@ export const useThemeStore = create((set) => ({
             localStorage.setItem(THEME_KEY, theme);
         }
     },
+    setSystemTheme: (theme) => {
+        set({ systemTheme: theme });
+    },
     loadTheme: () => {
         if (Platform.OS !== "web") {
             AsyncStorage.getItem(THEME_KEY).then((saved) => {
@@ -34,5 +50,45 @@ export const useThemeStore = create((set) => ({
         }
     }
 }));
+let stopSystemThemeListener = null;
+export function syncSystemTheme() {
+    useThemeStore.getState().setSystemTheme(getSystemTheme());
+}
+export function startSystemThemeListener() {
+    if (stopSystemThemeListener) {
+        return stopSystemThemeListener;
+    }
+    syncSystemTheme();
+    if (Platform.OS === "web" && typeof window !== "undefined" && typeof window.matchMedia === "function") {
+        const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+        const onChange = () => {
+            useThemeStore.getState().setSystemTheme(mediaQuery.matches ? "dark" : "light");
+        };
+        if (typeof mediaQuery.addEventListener === "function") {
+            mediaQuery.addEventListener("change", onChange);
+            stopSystemThemeListener = () => {
+                mediaQuery.removeEventListener("change", onChange);
+                stopSystemThemeListener = null;
+            };
+        }
+        else {
+            mediaQuery.addListener(onChange);
+            stopSystemThemeListener = () => {
+                mediaQuery.removeListener(onChange);
+                stopSystemThemeListener = null;
+            };
+        }
+        return stopSystemThemeListener;
+    }
+    const subscription = Appearance.addChangeListener(({ colorScheme }) => {
+        useThemeStore.getState().setSystemTheme(colorScheme === "dark" ? "dark" : "light");
+    });
+    stopSystemThemeListener = () => {
+        subscription.remove();
+        stopSystemThemeListener = null;
+    };
+    return stopSystemThemeListener;
+}
 // Load saved theme on store creation
 useThemeStore.getState().loadTheme();
+startSystemThemeListener();

package/package.json

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