@mrmeg/expo-ui 0.1.6 → 0.1.7

package/LLM_USAGE.md

@@ -119,10 +119,25 @@ 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,
+  },
+}));
+```
 
 ## Component Use-Case Index
 

package/README.md

@@ -95,7 +95,21 @@ 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.
+
+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

@@ -109,6 +109,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 +159,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 +352,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 +385,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/package.json

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