@mrmeg/expo-ui 0.1.0

package/dist/hooks/useDimensions.js

@@ -0,0 +1,55 @@
+import { useState, useEffect } from "react";
+import { Dimensions, Platform } from "react-native";
+export const SCREEN_SIZES = {
+    SMALL: 768,
+    MEDIUM: 1000,
+    LARGE: 1200,
+};
+/**
+* Provides a consistent way to access window dimensions and screen size information across mobile and web.
+*
+*/
+export const useDimensions = () => {
+    const isWeb = Platform.OS === "web";
+    const [dimensions, setDimensions] = useState({
+        width: 0,
+        height: 0,
+        orientation: "portrait",
+        isSmallScreen: true,
+        isMediumScreen: false,
+        isLargeScreen: false,
+    });
+    useEffect(() => {
+        const initialDimensions = isWeb
+            ? { width: window.innerWidth, height: window.innerHeight }
+            : Dimensions.get("window");
+        const updateDimensions = (width, height) => {
+            const orientation = width > height ? "landscape" : "portrait";
+            setDimensions({
+                width,
+                height,
+                orientation,
+                isSmallScreen: width <= SCREEN_SIZES.SMALL,
+                isMediumScreen: width > SCREEN_SIZES.SMALL,
+                isLargeScreen: width > SCREEN_SIZES.MEDIUM,
+            });
+        };
+        updateDimensions(initialDimensions.width, initialDimensions.height);
+        if (isWeb) {
+            const handleResize = () => {
+                updateDimensions(window.innerWidth, window.innerHeight);
+            };
+            window.addEventListener("resize", handleResize);
+            return () => {
+                window.removeEventListener("resize", handleResize);
+            };
+        }
+        else {
+            const onChange = ({ window }) => {
+                updateDimensions(window.width, window.height);
+            };
+            Dimensions.addEventListener("change", onChange);
+        }
+    }, [isWeb]);
+    return dimensions;
+};

package/dist/hooks/useReduceMotion.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Hook that returns whether the user prefers reduced motion.
+ * Uses a shared singleton listener so multiple consumers don't create duplicate subscriptions.
+ */
+export declare function useReducedMotion(): boolean;

package/dist/hooks/useReduceMotion.js

@@ -0,0 +1,64 @@
+import { useEffect, useState } from "react";
+import { AccessibilityInfo, Platform } from "react-native";
+let sharedValue = false;
+let listenerCount = 0;
+let subscription = null;
+function startListening() {
+    if (Platform.OS === "web") {
+        // On web, use the media query
+        if (typeof window !== "undefined" && window.matchMedia) {
+            const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+            sharedValue = mq.matches;
+            const handler = (e) => { sharedValue = e.matches; };
+            mq.addEventListener("change", handler);
+            subscription = { remove: () => mq.removeEventListener("change", handler) };
+        }
+        return;
+    }
+    AccessibilityInfo.isReduceMotionEnabled().then((enabled) => {
+        sharedValue = enabled;
+    });
+    const sub = AccessibilityInfo.addEventListener("reduceMotionChanged", (enabled) => {
+        sharedValue = enabled;
+    });
+    subscription = sub;
+}
+function stopListening() {
+    subscription?.remove();
+    subscription = null;
+}
+/**
+ * Hook that returns whether the user prefers reduced motion.
+ * Uses a shared singleton listener so multiple consumers don't create duplicate subscriptions.
+ */
+export function useReducedMotion() {
+    const [reduceMotion, setReduceMotion] = useState(sharedValue);
+    useEffect(() => {
+        listenerCount++;
+        if (listenerCount === 1) {
+            startListening();
+        }
+        // Re-read current value on mount (may have changed since last render)
+        if (Platform.OS === "web") {
+            if (typeof window !== "undefined" && window.matchMedia) {
+                const current = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+                setReduceMotion(current);
+            }
+        }
+        else {
+            AccessibilityInfo.isReduceMotionEnabled().then(setReduceMotion);
+        }
+        // Poll the shared value to pick up changes (lightweight — only boolean comparison)
+        const interval = setInterval(() => {
+            setReduceMotion((prev) => (prev !== sharedValue ? sharedValue : prev));
+        }, 500);
+        return () => {
+            clearInterval(interval);
+            listenerCount--;
+            if (listenerCount === 0) {
+                stopListening();
+            }
+        };
+    }, []);
+    return reduceMotion;
+}

package/dist/hooks/useResources.d.ts

@@ -0,0 +1,12 @@
+interface LoadResourcesResult {
+    loaded: boolean;
+    error: Error | null;
+}
+/**
+ * Loads essential app resources on startup.
+ *
+ * The UI package does not bundle font files. Web loads Lato from Google Fonts;
+ * native platforms use their system sans-serif fallback.
+ */
+export declare const useResources: () => LoadResourcesResult;
+export {};

package/dist/hooks/useResources.js

@@ -0,0 +1,56 @@
+import { useEffect, useState } from "react";
+import * as Font from "expo-font";
+import Feather from "@expo/vector-icons/Feather";
+import { Platform } from "react-native";
+const LATO_STYLESHEET_ID = "mrmeg-expo-ui-lato";
+const LATO_STYLESHEET_URL = "https://fonts.googleapis.com/css2?family=Lato:wght@400;700&display=swap";
+function ensureWebFontStylesheet() {
+    if (Platform.OS !== "web" || typeof document === "undefined") {
+        return Promise.resolve();
+    }
+    if (document.getElementById(LATO_STYLESHEET_ID)) {
+        return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+        const link = document.createElement("link");
+        link.id = LATO_STYLESHEET_ID;
+        link.rel = "stylesheet";
+        link.href = LATO_STYLESHEET_URL;
+        link.onload = () => resolve();
+        link.onerror = () => reject(new Error("Lato stylesheet failed to load"));
+        document.head.appendChild(link);
+    });
+}
+/**
+ * Loads essential app resources on startup.
+ *
+ * The UI package does not bundle font files. Web loads Lato from Google Fonts;
+ * native platforms use their system sans-serif fallback.
+ */
+export const useResources = () => {
+    const [loaded, setLoaded] = useState(false);
+    const [error, setError] = useState(null);
+    useEffect(() => {
+        async function loadResourcesAndDataAsync() {
+            try {
+                const fontPromise = Promise.all([
+                    Font.loadAsync(Feather.font),
+                    ensureWebFontStylesheet(),
+                ]);
+                // Timeout after 5 seconds — proceed with system fallback fonts
+                const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error("Font loading timed out after 5s")), 5000));
+                await Promise.race([fontPromise, timeoutPromise]);
+            }
+            catch (e) {
+                const error = e instanceof Error ? e : new Error(String(e));
+                console.warn("Font loading issue (proceeding with fallback):", error.message);
+                setError(error);
+            }
+            finally {
+                setLoaded(true);
+            }
+        }
+        loadResourcesAndDataAsync();
+    }, []);
+    return { loaded, error };
+};

package/dist/hooks/useScalePress.d.ts

@@ -0,0 +1,57 @@
+interface ScalePressOptions {
+    /**
+     * Scale value when pressed (1 = no change, 0.97 = subtle, 0.93 = more pronounced)
+     * @default 0.97
+     */
+    scaleTo?: number;
+    /**
+     * Whether to fire haptic feedback on press
+     * @default true
+     */
+    haptic?: boolean;
+    /**
+     * Spring damping for bounce-back
+     * @default 20
+     */
+    damping?: number;
+    /**
+     * Spring stiffness
+     * @default 300
+     */
+    stiffness?: number;
+    /**
+     * Whether the component is disabled (skips animation)
+     * @default false
+     */
+    disabled?: boolean;
+}
+/**
+ * Hook for press-feedback scale animation using Reanimated.
+ *
+ * Returns an animated style and onPressIn/onPressOut handlers to spread onto a Pressable.
+ * Respects reduced motion preferences.
+ *
+ * @example
+ * ```tsx
+ * const { animatedStyle, pressHandlers } = useScalePress();
+ *
+ * <Animated.View style={animatedStyle}>
+ *   <Pressable {...pressHandlers} onPress={handlePress}>
+ *     <Text>Press me</Text>
+ *   </Pressable>
+ * </Animated.View>
+ * ```
+ */
+export declare function useScalePress(options?: ScalePressOptions): {
+    animatedStyle: {
+        transform: {
+            scale: number;
+        }[];
+    };
+    pressHandlers: {
+        onPressIn: () => void;
+        onPressOut: () => void;
+    };
+    scale: import("react-native-reanimated").SharedValue<number>;
+};
+export {};

package/dist/hooks/useScalePress.js

@@ -0,0 +1,55 @@
+import { useCallback } from "react";
+import { useSharedValue, useAnimatedStyle, withSpring, withTiming, useReducedMotion, } from "react-native-reanimated";
+import { hapticLight } from "../lib/haptics";
+/**
+ * Hook for press-feedback scale animation using Reanimated.
+ *
+ * Returns an animated style and onPressIn/onPressOut handlers to spread onto a Pressable.
+ * Respects reduced motion preferences.
+ *
+ * @example
+ * ```tsx
+ * const { animatedStyle, pressHandlers } = useScalePress();
+ *
+ * <Animated.View style={animatedStyle}>
+ *   <Pressable {...pressHandlers} onPress={handlePress}>
+ *     <Text>Press me</Text>
+ *   </Pressable>
+ * </Animated.View>
+ * ```
+ */
+export function useScalePress(options = {}) {
+    const { scaleTo = 0.97, haptic = true, damping = 20, stiffness = 300, disabled = false, } = options;
+    const reduceMotion = useReducedMotion();
+    const scale = useSharedValue(1);
+    const onPressIn = useCallback(() => {
+        if (disabled)
+            return;
+        if (haptic)
+            hapticLight();
+        if (reduceMotion) {
+            scale.value = withTiming(scaleTo, { duration: 0 });
+        }
+        else {
+            scale.value = withSpring(scaleTo, { damping, stiffness });
+        }
+    }, [disabled, haptic, reduceMotion, scale, scaleTo, damping, stiffness]);
+    const onPressOut = useCallback(() => {
+        if (disabled)
+            return;
+        if (reduceMotion) {
+            scale.value = withTiming(1, { duration: 0 });
+        }
+        else {
+            scale.value = withSpring(1, { damping, stiffness });
+        }
+    }, [disabled, reduceMotion, scale, damping, stiffness]);
+    const animatedStyle = useAnimatedStyle(() => ({
+        transform: [{ scale: scale.value }],
+    }));
+    return {
+        animatedStyle,
+        pressHandlers: { onPressIn, onPressOut },
+        scale,
+    };
+}

package/dist/hooks/useStaggeredEntrance.d.ts

@@ -0,0 +1,67 @@
+type EntranceType = "fade" | "fadeSlideUp" | "fadeSlideDown" | "scale";
+interface StaggeredEntranceOptions {
+    /**
+     * Type of entrance animation
+     * @default "fadeSlideUp"
+     */
+    type?: EntranceType;
+    /**
+     * Delay before this item starts animating (ms).
+     * Use index * staggerMs for staggered lists.
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * Duration of the entrance animation (ms)
+     * @default 200
+     */
+    duration?: number;
+    /**
+     * Slide distance in pixels (for fadeSlideUp/fadeSlideDown)
+     * @default 8
+     */
+    slideDistance?: number;
+    /**
+     * Initial scale (for scale type)
+     * @default 0.95
+     */
+    initialScale?: number;
+}
+/**
+ * Hook for entrance animations with stagger support using Reanimated.
+ *
+ * Returns an animated style to apply to an Animated.View.
+ * Respects reduced motion preferences.
+ *
+ * @example
+ * ```tsx
+ * // Single entrance
+ * const entranceStyle = useStaggeredEntrance({ type: "fadeSlideUp" });
+ * <Animated.View style={entranceStyle}>...</Animated.View>
+ *
+ * // Staggered list
+ * {items.map((item, i) => {
+ *   const style = useStaggeredEntrance({ delay: i * 50 });
+ *   return <Animated.View key={item.id} style={style}>...</Animated.View>;
+ * })}
+ * ```
+ */
+export declare function useStaggeredEntrance(options?: StaggeredEntranceOptions): {
+    opacity: number;
+    transform?: undefined;
+} | {
+    opacity: number;
+    transform: {
+        translateY: number;
+    }[];
+} | {
+    opacity: number;
+    transform: {
+        scale: number;
+    }[];
+};
+/**
+ * Convenience constant: default stagger delay between items (ms)
+ */
+export declare const STAGGER_DELAY = 30;
+export {};

package/dist/hooks/useStaggeredEntrance.js

@@ -0,0 +1,74 @@
+import { useEffect } from "react";
+import { useSharedValue, useAnimatedStyle, withTiming, withSpring, withDelay, useReducedMotion, Easing, } from "react-native-reanimated";
+/**
+ * Hook for entrance animations with stagger support using Reanimated.
+ *
+ * Returns an animated style to apply to an Animated.View.
+ * Respects reduced motion preferences.
+ *
+ * @example
+ * ```tsx
+ * // Single entrance
+ * const entranceStyle = useStaggeredEntrance({ type: "fadeSlideUp" });
+ * <Animated.View style={entranceStyle}>...</Animated.View>
+ *
+ * // Staggered list
+ * {items.map((item, i) => {
+ *   const style = useStaggeredEntrance({ delay: i * 50 });
+ *   return <Animated.View key={item.id} style={style}>...</Animated.View>;
+ * })}
+ * ```
+ */
+export function useStaggeredEntrance(options = {}) {
+    const { type = "fadeSlideUp", delay = 0, duration = 200, slideDistance = 8, initialScale = 0.95, } = options;
+    const reduceMotion = useReducedMotion();
+    const opacity = useSharedValue(reduceMotion ? 1 : 0);
+    const translateY = useSharedValue(reduceMotion
+        ? 0
+        : type === "fadeSlideUp"
+            ? slideDistance
+            : type === "fadeSlideDown"
+                ? -slideDistance
+                : 0);
+    const scale = useSharedValue(reduceMotion ? 1 : type === "scale" ? initialScale : 1);
+    useEffect(() => {
+        if (reduceMotion) {
+            opacity.value = 1;
+            translateY.value = 0;
+            scale.value = 1;
+            return;
+        }
+        const timingConfig = {
+            duration,
+            easing: Easing.out(Easing.cubic),
+        };
+        opacity.value = withDelay(delay, withTiming(1, timingConfig));
+        if (type === "fadeSlideUp" || type === "fadeSlideDown") {
+            translateY.value = withDelay(delay, withTiming(0, timingConfig));
+        }
+        if (type === "scale") {
+            scale.value = withDelay(delay, withSpring(1, { damping: 14, stiffness: 250 }));
+        }
+    }, [reduceMotion]);
+    const animatedStyle = useAnimatedStyle(() => {
+        if (type === "fade") {
+            return { opacity: opacity.value };
+        }
+        if (type === "fadeSlideUp" || type === "fadeSlideDown") {
+            return {
+                opacity: opacity.value,
+                transform: [{ translateY: translateY.value }],
+            };
+        }
+        // scale
+        return {
+            opacity: opacity.value,
+            transform: [{ scale: scale.value }],
+        };
+    });
+    return animatedStyle;
+}
+/**
+ * Convenience constant: default stagger delay between items (ms)
+ */
+export const STAGGER_DELAY = 30;

package/dist/hooks/useTheme.d.ts

@@ -0,0 +1,88 @@
+import { Colors } from "../constants/colors";
+import { ViewStyle, StyleSheet } from "react-native";
+import { spacing as spacingConstants } from "../constants/spacing";
+type ShadowType = "base" | "soft" | "sharp" | "subtle";
+interface ExtendedColorScheme {
+    theme: Colors["light" | "dark"];
+    scheme: "light" | "dark";
+    getShadowStyle: (type: ShadowType) => ViewStyle;
+    getContrastingColor: (backgroundColor: string, color1?: string, color2?: string) => string;
+    getTextColorForBackground: (backgroundColor: string) => "light" | "dark";
+    withAlpha: (color: string, alpha: number) => string;
+    getContrastRatio: (color1: string, color2: string) => number;
+}
+/**
+ * useTheme
+ *
+ * Provides access to app colors, theme styles, and utilities for color contrast.
+ * Includes helpers to determine readable text color for any background.
+ *
+ * Returns:
+ * - theme: active theme colors (light or dark)
+ * - scheme: "light" | "dark"
+ * - getShadowStyle(type): returns cross-platform shadow style object
+ * - getContrastingColor(bg, color1?, color2?): pick best contrast of two options
+ * - getTextColorForBackground(bg): returns "light" or "dark"
+ * - withAlpha(color, alpha): adds transparency
+ * - getContrastRatio(color1, color2): returns numeric WCAG contrast ratio
+ *
+ * Examples:
+ * - getTextColorForBackground("#000") → "light"
+ * - getContrastingColor("#f4f4f4", "#222", "#fff") → "#222"
+ * - withAlpha("#336699", 0.6) → "rgba(51,102,153,0.6)"
+ * - getShadowStyle('base') → { shadowColor, shadowOffset, ... }
+ */
+export declare function useTheme(): ExtendedColorScheme & {
+    toggleTheme: () => void;
+    setTheme: (theme: "system" | "light" | "dark") => void;
+    currentTheme: "system" | "light" | "dark";
+};
+/**
+ * Style factory context passed to the createStyles callback
+ */
+interface StyleContext {
+    theme: Colors["light" | "dark"];
+    spacing: typeof spacingConstants;
+}
+/**
+ * Return type for useStyles hook
+ */
+type UseStylesReturn<T extends StyleSheet.NamedStyles<T>> = {
+    styles: T;
+    theme: Colors["light" | "dark"];
+    spacing: typeof spacingConstants;
+} & Omit<ReturnType<typeof useTheme>, "theme">;
+/**
+ * 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.
+ *
+ * @param factory - A function that receives { theme, spacing } and returns style definitions
+ * @returns { styles, theme, spacing, ...themeUtilities }
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { styles, theme } = useStyles(({ theme, spacing }) => ({
+ *     container: {
+ *       backgroundColor: theme.colors.background,
+ *       padding: spacing.md,
+ *       borderRadius: spacing.radiusMd,
+ *     },
+ *     text: {
+ *       color: theme.colors.textPrimary,
+ *       fontSize: 16,
+ *     },
+ *   }));
+ *
+ *   return (
+ *     <View style={styles.container}>
+ *       <Text style={styles.text}>Hello</Text>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export declare function useStyles<T extends StyleSheet.NamedStyles<T>>(factory: (context: StyleContext) => T): UseStylesReturn<T>;
+export {};