@mrmeg/expo-ui 0.1.6 → 0.1.8

package/LLM_USAGE.md

@@ -119,10 +119,30 @@ Token intent:
 - `ring`: focus outline color
 - `popover`: elevated overlay surface
 
-Use `getShadowStyle()` for package surfaces that need elevation and
-`getFocusRingStyle()` for web focus styling. Keep web controls compact, but
-preserve mobile tap comfort with package controls that already provide native
-hit slop or 44px touch rows.
+Use `getShadowStyle()` for package surfaces that need elevation. It supports
+`base`, `soft`, `sharp`, `subtle`, `elevated`, `glow`, `glass`, `card`,
+`cardHover`, and `cardSubtle`, returning native shadow/elevation off web and
+CSS `boxShadow` on web. Use `getFocusRingStyle()` for web focus styling. Keep
+web controls compact, but preserve mobile tap comfort with package controls
+that already provide native hit slop or 44px touch rows.
+
+Use `useStyles()` for memoized theme-aware local styles. Its factory receives
+`{ theme, spacing, withAlpha }`, so components can derive alpha-adjusted
+semantic colors without destructuring `withAlpha` outside the factory:
+
+```tsx
+const { styles } = useStyles(({ theme, spacing, withAlpha }) => ({
+  card: {
+    backgroundColor: withAlpha(theme.colors.primary, 0.08),
+    padding: spacing.md,
+  },
+}));
+```
+
+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
 

package/README.md

@@ -95,7 +95,26 @@ 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`. 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.
+`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
+import { useStyles } from "@mrmeg/expo-ui/hooks";
+
+const { styles } = useStyles(({ theme, spacing, withAlpha }) => ({
+  card: {
+    backgroundColor: withAlpha(theme.colors.primary, 0.08),
+    borderRadius: spacing.radiusMd,
+    padding: spacing.md,
+  },
+}));
+```
 
 Use `StyledText` for theme-aware text:
 

package/dist/hooks/useTheme.d.ts

@@ -1,7 +1,7 @@
 import { Colors } from "../constants/colors";
 import { ViewStyle, StyleSheet } from "react-native";
 import { spacing as spacingConstants } from "../constants/spacing";
-type ShadowType = "base" | "soft" | "sharp" | "subtle";
+type ShadowType = "base" | "soft" | "sharp" | "subtle" | "elevated" | "glow" | "glass" | "card" | "cardHover" | "cardSubtle";
 interface ExtendedColorScheme {
     theme: Colors["light" | "dark"];
     scheme: "light" | "dark";
@@ -45,6 +45,7 @@ export declare function useTheme(): ExtendedColorScheme & {
 interface StyleContext {
     theme: Colors["light" | "dark"];
     spacing: typeof spacingConstants;
+    withAlpha: (color: string, alpha: number) => string;
 }
 /**
  * Return type for useStyles hook
@@ -58,17 +59,17 @@ type UseStylesReturn<T extends StyleSheet.NamedStyles<T>> = {
  * useStyles
  *
  * A hook that combines useTheme with StyleSheet.create for theme-aware styling.
- * Provides access to theme colors and spacing constants within the style factory.
+ * Provides access to theme colors, spacing constants, and color helpers within the style factory.
  *
- * @param factory - A function that receives { theme, spacing } and returns style definitions
+ * @param factory - A function that receives { theme, spacing, withAlpha } and returns style definitions
  * @returns { styles, theme, spacing, ...themeUtilities }
  *
  * @example
  * ```tsx
  * function MyComponent() {
- *   const { styles, theme } = useStyles(({ theme, spacing }) => ({
+ *   const { styles, theme } = useStyles(({ theme, spacing, withAlpha }) => ({
  *     container: {
- *       backgroundColor: theme.colors.background,
+ *       backgroundColor: withAlpha(theme.colors.primary, 0.08),
  *       padding: spacing.md,
  *       borderRadius: spacing.radiusMd,
  *     },

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(() => {
@@ -109,6 +105,48 @@ export function useTheme() {
                 shadowRadius: 2,
                 elevation: 1,
             },
+            elevated: {
+                shadowColor: theme.colors.overlay,
+                shadowOffset: { width: 0, height: 20 },
+                shadowOpacity: 0.15,
+                shadowRadius: 40,
+                elevation: 16,
+            },
+            glow: {
+                shadowColor: theme.colors.primary,
+                shadowOffset: { width: 0, height: 4 },
+                shadowOpacity: 0.4,
+                shadowRadius: 20,
+                elevation: 10,
+            },
+            glass: {
+                shadowColor: theme.colors.overlay,
+                shadowOffset: { width: 0, height: 4 },
+                shadowOpacity: 0.05,
+                shadowRadius: 30,
+                elevation: 4,
+            },
+            card: {
+                shadowColor: theme.colors.overlay,
+                shadowOffset: { width: 0, height: 2 },
+                shadowOpacity: 0.08,
+                shadowRadius: 8,
+                elevation: 4,
+            },
+            cardHover: {
+                shadowColor: theme.colors.overlay,
+                shadowOffset: { width: 0, height: 8 },
+                shadowOpacity: 0.12,
+                shadowRadius: 24,
+                elevation: 8,
+            },
+            cardSubtle: {
+                shadowColor: theme.colors.overlay,
+                shadowOffset: { width: 0, height: 1 },
+                shadowOpacity: 0.08,
+                shadowRadius: 3,
+                elevation: 2,
+            },
         };
         const config = shadowConfigs[type];
         if (Platform.OS === "web") {
@@ -117,6 +155,12 @@ export function useTheme() {
                 soft: { boxShadow: theme.dark ? "0 8px 24px rgba(0, 0, 0, 0.36)" : "0 8px 24px rgba(0, 0, 0, 0.10)" },
                 sharp: { boxShadow: theme.dark ? "0 1px 1px rgba(0, 0, 0, 0.55)" : "0 1px 1px rgba(0, 0, 0, 0.12)" },
                 subtle: { boxShadow: theme.dark ? "0 1px 2px rgba(0, 0, 0, 0.32)" : "0 1px 2px rgba(0, 0, 0, 0.05)" },
+                elevated: { boxShadow: theme.dark ? "0 20px 40px rgba(0, 0, 0, 0.38)" : "0 20px 40px rgba(0, 0, 0, 0.15)" },
+                glow: { boxShadow: `0 0 20px ${theme.colors.primary}` },
+                glass: { boxShadow: theme.dark ? "0 4px 30px rgba(0, 0, 0, 0.32)" : "0 4px 30px rgba(0, 0, 0, 0.05)" },
+                card: { boxShadow: theme.dark ? "0 1px 2px rgba(0, 0, 0, 0.32)" : "0 1px 3px rgba(0, 0, 0, 0.08)" },
+                cardHover: { boxShadow: theme.dark ? "0 8px 24px rgba(0, 0, 0, 0.36)" : "0 8px 24px rgba(0, 0, 0, 0.12)" },
+                cardSubtle: { boxShadow: theme.dark ? "0 1px 2px rgba(0, 0, 0, 0.32)" : "0 1px 3px rgba(0, 0, 0, 0.05)" },
             };
             return webShadows[type];
         }
@@ -304,17 +348,17 @@ function withAlpha(color, alpha) {
  * useStyles
  *
  * A hook that combines useTheme with StyleSheet.create for theme-aware styling.
- * Provides access to theme colors and spacing constants within the style factory.
+ * Provides access to theme colors, spacing constants, and color helpers within the style factory.
  *
- * @param factory - A function that receives { theme, spacing } and returns style definitions
+ * @param factory - A function that receives { theme, spacing, withAlpha } and returns style definitions
  * @returns { styles, theme, spacing, ...themeUtilities }
  *
  * @example
  * ```tsx
  * function MyComponent() {
- *   const { styles, theme } = useStyles(({ theme, spacing }) => ({
+ *   const { styles, theme } = useStyles(({ theme, spacing, withAlpha }) => ({
  *     container: {
- *       backgroundColor: theme.colors.background,
+ *       backgroundColor: withAlpha(theme.colors.primary, 0.08),
  *       padding: spacing.md,
  *       borderRadius: spacing.radiusMd,
  *     },
@@ -337,7 +381,8 @@ export function useStyles(factory) {
     const styles = useMemo(() => StyleSheet.create(factory({
         theme: themeContext.theme,
         spacing: spacingConstants,
-    })), [factory, themeContext.theme]);
+        withAlpha: themeContext.withAlpha,
+    })), [factory, themeContext.theme, themeContext.withAlpha]);
     return useMemo(() => ({
         styles,
         theme: themeContext.theme,

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