@mrmeg/expo-ui 0.1.0

package/dist/hooks/useTheme.js

@@ -0,0 +1,328 @@
+import { useEffect } from "react";
+import { colors } from "../constants/colors";
+import { useColorScheme as useColorSchemeDefault, Platform, StyleSheet } from "react-native";
+import { useThemeStore } from "../state/themeStore";
+import { spacing as spacingConstants } from "../constants/spacing";
+// Module-level cache for contrast calculations to avoid memory leak
+// and share across components
+const contrastCache = new Map();
+const MAX_CACHE_SIZE = 500;
+function getCachedOrCompute(key, compute) {
+    if (contrastCache.has(key)) {
+        return contrastCache.get(key);
+    }
+    // Prevent unbounded growth
+    if (contrastCache.size >= MAX_CACHE_SIZE) {
+        const firstKey = contrastCache.keys().next().value;
+        if (firstKey)
+            contrastCache.delete(firstKey);
+    }
+    const result = compute();
+    contrastCache.set(key, result);
+    return result;
+}
+/**
+ * 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 function useTheme() {
+    const userTheme = useThemeStore((s) => s.userTheme);
+    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 theme = colors[effectiveScheme];
+    // Sync theme to DOM so CSS in +html.tsx follows the app's runtime theme
+    useEffect(() => {
+        if (Platform.OS === "web" && typeof document !== "undefined") {
+            document.documentElement.dataset.theme = effectiveScheme;
+            document.documentElement.style.colorScheme = effectiveScheme;
+        }
+    }, [effectiveScheme]);
+    // Toggle between light, dark, and system themes
+    const toggleTheme = () => {
+        if (userTheme === "light") {
+            setTheme("dark");
+        }
+        else if (userTheme === "dark") {
+            setTheme("system");
+        }
+        else {
+            setTheme("light");
+        }
+    };
+    /**
+     * getShadowStyle
+     * Returns platform-appropriate shadow styles
+     * - Web: returns empty object (boxShadow not supported by RN Web)
+     * - Native: uses shadowColor, shadowOffset, shadowOpacity, shadowRadius, elevation
+     */
+    const getShadowStyle = (type) => {
+        const shadowConfigs = {
+            base: {
+                shadowColor: theme.colors.overlay,
+                shadowOffset: { width: 0, height: 1 },
+                shadowOpacity: 0.1,
+                shadowRadius: 3,
+                elevation: 3,
+            },
+            soft: {
+                shadowColor: theme.colors.overlay,
+                shadowOffset: { width: 0, height: 4 },
+                shadowOpacity: 0.1,
+                shadowRadius: 6,
+                elevation: 4,
+            },
+            sharp: {
+                shadowColor: theme.colors.overlay,
+                shadowOffset: { width: 0, height: 1 },
+                shadowOpacity: 0.15,
+                shadowRadius: 1,
+                elevation: 2,
+            },
+            subtle: {
+                shadowColor: theme.colors.overlay,
+                shadowOffset: { width: 0, height: 1 },
+                shadowOpacity: 0.05,
+                shadowRadius: 2,
+                elevation: 1,
+            },
+        };
+        const config = shadowConfigs[type];
+        return Platform.select({
+            web: {}, // Empty on web - boxShadow causes crashes
+            default: config,
+        });
+    };
+    // Helper to calculate contrast ratio between two colors
+    const getContrastRatio = (color1, color2) => {
+        const rgb1 = parseColor(color1);
+        const rgb2 = parseColor(color2);
+        if (!rgb1 || !rgb2) {
+            console.error("Invalid colors for contrast ratio:", color1, color2);
+            return 1; // Default to minimum contrast
+        }
+        const lum1 = calculateLuminance(rgb1[0], rgb1[1], rgb1[2]);
+        const lum2 = calculateLuminance(rgb2[0], rgb2[1], rgb2[2]);
+        return calculateContrastRatio(lum1, lum2);
+    };
+    // Cached version of getContrastingColor for performance
+    // Uses module-level cache to prevent memory leak
+    const getCachedContrastingColor = (backgroundColor, color1, color2) => {
+        const cacheKey = `${backgroundColor}-${color1}-${color2}`;
+        return getCachedOrCompute(cacheKey, () => getBetterContrast(backgroundColor, color1, color2));
+    };
+    return {
+        theme,
+        scheme: theme.dark ? "dark" : "light",
+        getShadowStyle,
+        toggleTheme,
+        setTheme,
+        currentTheme: userTheme,
+        getContrastingColor: getCachedContrastingColor,
+        getTextColorForBackground,
+        withAlpha,
+        getContrastRatio,
+    };
+}
+/**
+ * Parses a color string (hex or rgba) and returns RGB values.
+ * @param color - The color string (hex or rgba format)
+ * @returns An array of [red, green, blue, alpha] values (RGB 0-255, alpha 0-1) or null if invalid.
+ */
+function parseColor(color) {
+    // Check if it's an rgba string
+    const rgbaMatch = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)(?:,\s*([0-9.]+))?\)/);
+    if (rgbaMatch) {
+        return [
+            parseInt(rgbaMatch[1], 10),
+            parseInt(rgbaMatch[2], 10),
+            parseInt(rgbaMatch[3], 10),
+            rgbaMatch[4] ? parseFloat(rgbaMatch[4]) : 1
+        ];
+    }
+    // Otherwise, try to parse as hex
+    const rgb = hexToRgb(color);
+    return rgb ? [...rgb, 1] : null; // Add alpha=1 for hex colors
+}
+/**
+ * Converts a hexadecimal color code to RGB values.
+ * @param hex - The hexadecimal color code (e.g., "#RRGGBB" or "#RGB").
+ * @returns An array of [red, green, blue] values (0-255) or null if invalid.
+ */
+function hexToRgb(hex) {
+    // Check if already in rgba format
+    if (hex.startsWith("rgba") || hex.startsWith("rgb")) {
+        const rgbValues = parseColor(hex);
+        return rgbValues ? [rgbValues[0], rgbValues[1], rgbValues[2]] : null;
+    }
+    // Remove the hash if it exists
+    hex = hex.replace(/^#/, "");
+    // Handle shorthand hex (#RGB)
+    if (hex.length === 3) {
+        hex = hex[0] + hex[0] + hex[1] + hex[1] + hex[2] + hex[2];
+    }
+    // Handle standard hex (#RRGGBB)
+    const result = /^([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+    return result
+        ? [
+            parseInt(result[1], 16),
+            parseInt(result[2], 16),
+            parseInt(result[3], 16)
+        ]
+        : null;
+}
+/**
+ * Calculates the relative luminance of a color according to WCAG guidelines.
+ * @param r - Red component (0-255).
+ * @param g - Green component (0-255).
+ * @param b - Blue component (0-255).
+ * @returns The relative luminance value (0-1).
+ */
+function calculateLuminance(r, g, b) {
+    // Convert RGB to sRGB
+    const sRGB = [r, g, b].map(v => {
+        v /= 255;
+        return v <= 0.03928
+            ? v / 12.92
+            : Math.pow((v + 0.055) / 1.055, 2.4);
+    });
+    // Calculate luminance using WCAG formula
+    return sRGB[0] * 0.2126 + sRGB[1] * 0.7152 + sRGB[2] * 0.0722;
+}
+/**
+ * Calculates the contrast ratio between two colors according to WCAG guidelines.
+ * @param lum1 - First color's luminance.
+ * @param lum2 - Second color's luminance.
+ * @returns The contrast ratio (1-21).
+ */
+function calculateContrastRatio(lum1, lum2) {
+    const lighterLum = Math.max(lum1, lum2);
+    const darkerLum = Math.min(lum1, lum2);
+    return (lighterLum + 0.05) / (darkerLum + 0.05);
+}
+/**
+ * Determines the color with better contrast against the background.
+ * @param backgroundColor - The background color in hex or rgba format.
+ * @param color1 - First color option in hex format (default: "#FFFFFF").
+ * @param color2 - Second color option in hex format (default: "#000000").
+ * @returns The hex color code of the color with better contrast.
+ */
+function getBetterContrast(backgroundColor, color1 = "#FFFFFF", color2 = "#000000") {
+    const bgColor = parseColor(backgroundColor);
+    const color1Rgb = parseColor(color1);
+    const color2Rgb = parseColor(color2);
+    if (!bgColor || !color1Rgb || !color2Rgb) {
+        return "#000000"; // Default to black if any color is invalid
+    }
+    // For semi-transparent backgrounds, we'll consider their luminance directly
+    const bgLuminance = calculateLuminance(bgColor[0], bgColor[1], bgColor[2]);
+    const color1Luminance = calculateLuminance(color1Rgb[0], color1Rgb[1], color1Rgb[2]);
+    const color2Luminance = calculateLuminance(color2Rgb[0], color2Rgb[1], color2Rgb[2]);
+    const contrast1 = calculateContrastRatio(bgLuminance, color1Luminance);
+    const contrast2 = calculateContrastRatio(bgLuminance, color2Luminance);
+    return contrast1 > contrast2 ? color1 : color2;
+}
+/**
+ * Determines whether to use light or dark text based on background color.
+ * @param backgroundColor - The background color in hex or rgba format.
+ * @returns "light" or "dark" indicating the recommended text color.
+ */
+function getTextColorForBackground(backgroundColor) {
+    const rgb = parseColor(backgroundColor);
+    if (!rgb) {
+        console.error("Invalid color:", backgroundColor);
+        return "light"; // default to light if invalid color
+    }
+    // Using threshold of 0.5 for better light/dark text discrimination
+    const luminance = calculateLuminance(rgb[0], rgb[1], rgb[2]);
+    return luminance > 0.5 ? "dark" : "light";
+}
+/**
+ * Generates an alpha-modified version of a color
+ * @param color - The color to modify (hex or rgba)
+ * @param alpha - Alpha value between 0 and 1
+ * @returns rgba color string with the specified alpha
+ */
+function withAlpha(color, alpha) {
+    const rgb = parseColor(color);
+    if (!rgb) {
+        console.error("Invalid color for alpha:", color);
+        return `rgba(0, 0, 0, ${alpha})`;
+    }
+    return `rgba(${rgb[0]}, ${rgb[1]}, ${rgb[2]}, ${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.
+ *
+ * @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 function useStyles(factory) {
+    const themeContext = useTheme();
+    const styles = StyleSheet.create(factory({
+        theme: themeContext.theme,
+        spacing: spacingConstants,
+    }));
+    return {
+        styles,
+        theme: themeContext.theme,
+        spacing: spacingConstants,
+        scheme: themeContext.scheme,
+        getShadowStyle: themeContext.getShadowStyle,
+        getContrastingColor: themeContext.getContrastingColor,
+        getTextColorForBackground: themeContext.getTextColorForBackground,
+        withAlpha: themeContext.withAlpha,
+        getContrastRatio: themeContext.getContrastRatio,
+        toggleTheme: themeContext.toggleTheme,
+        setTheme: themeContext.setTheme,
+        currentTheme: themeContext.currentTheme,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./components";
+export * from "./constants";
+export * from "./hooks";
+export * from "./state";
+export * from "./lib";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./components";
+export * from "./constants";
+export * from "./hooks";
+export * from "./state";
+export * from "./lib";

package/dist/lib/animations.d.ts

@@ -0,0 +1 @@
+export declare const shouldUseNativeDriver: boolean;

package/dist/lib/animations.js

@@ -0,0 +1,3 @@
+import { Platform } from "react-native";
+// RN core Animated's native driver is not available on web.
+export const shouldUseNativeDriver = Platform.OS !== "web";

package/dist/lib/haptics.d.ts

@@ -0,0 +1,3 @@
+export declare function hapticLight(): void;
+export declare function hapticMedium(): void;
+export declare function hapticSuccess(): void;

package/dist/lib/haptics.js

@@ -0,0 +1,29 @@
+import { Platform } from "react-native";
+function runHaptic(fn) {
+    if (Platform.OS === "web")
+        return;
+    try {
+        fn();
+    }
+    catch {
+        // Haptics not available
+    }
+}
+export function hapticLight() {
+    runHaptic(() => {
+        const H = require("expo-haptics");
+        H.impactAsync(H.ImpactFeedbackStyle.Light);
+    });
+}
+export function hapticMedium() {
+    runHaptic(() => {
+        const H = require("expo-haptics");
+        H.impactAsync(H.ImpactFeedbackStyle.Medium);
+    });
+}
+export function hapticSuccess() {
+    runHaptic(() => {
+        const H = require("expo-haptics");
+        H.notificationAsync(H.NotificationFeedbackType.Success);
+    });
+}

package/dist/lib/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./animations";
+export * from "./haptics";
+export * from "./sentry";

package/dist/lib/index.js

@@ -0,0 +1,3 @@
+export * from "./animations";
+export * from "./haptics";
+export * from "./sentry";

package/dist/lib/sentry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Sentry error tracking wrapper.
+ *
+ * Zero-impact when EXPO_PUBLIC_SENTRY_DSN is not set — no network requests,
+ * no global handlers, and no Sentry code in the entry bundle.
+ */
+/**
+ * Initialize Sentry. Call once at app startup (module scope in _layout.tsx).
+ * No-op if sentryDsn is empty.
+ */
+export declare function setupSentry(): void;
+/**
+ * Capture an exception after the optional Sentry bundle has loaded.
+ * No-op when Sentry is disabled or failed to initialize.
+ */
+export declare function captureException(error: unknown, context?: Parameters<typeof import("@sentry/react-native")["captureException"]>[1]): void;

package/dist/lib/sentry.js

@@ -0,0 +1,55 @@
+/**
+ * Sentry error tracking wrapper.
+ *
+ * Zero-impact when EXPO_PUBLIC_SENTRY_DSN is not set — no network requests,
+ * no global handlers, and no Sentry code in the entry bundle.
+ */
+let initialized = false;
+let sentryModulePromise = null;
+function loadSentry() {
+    const dsn = process.env.EXPO_PUBLIC_SENTRY_DSN;
+    if (!dsn) {
+        if (__DEV__) {
+            console.log("Sentry disabled — no EXPO_PUBLIC_SENTRY_DSN set");
+        }
+        return Promise.resolve(null);
+    }
+    sentryModulePromise ??= import("@sentry/react-native").then((Sentry) => {
+        Sentry.init({
+            dsn,
+            debug: __DEV__,
+            enabled: true,
+            environment: __DEV__ ? "development" : "production",
+            tracesSampleRate: __DEV__ ? 1.0 : 0.2,
+        });
+        return Sentry;
+    });
+    return sentryModulePromise;
+}
+/**
+ * Initialize Sentry. Call once at app startup (module scope in _layout.tsx).
+ * No-op if sentryDsn is empty.
+ */
+export function setupSentry() {
+    if (initialized)
+        return;
+    initialized = true;
+    loadSentry().catch((error) => {
+        if (__DEV__) {
+            console.warn("Sentry failed to initialize:", error);
+        }
+    });
+}
+/**
+ * Capture an exception after the optional Sentry bundle has loaded.
+ * No-op when Sentry is disabled or failed to initialize.
+ */
+export function captureException(error, context) {
+    loadSentry().then((Sentry) => {
+        Sentry?.captureException(error, context);
+    }).catch((loadError) => {
+        if (__DEV__) {
+            console.warn("Sentry capture skipped:", loadError);
+        }
+    });
+}

package/dist/state/globalUIStore.d.ts

@@ -0,0 +1,30 @@
+/**
+ * globalUIStore
+ *
+ * Global UI state store for alerts, modals, and transient UI elements.
+ * Primarily used to trigger and dismiss the `Notification` component globally.
+ *
+ * Methods:
+ * - show({ type, title, messages, duration, loading }): displays a notification
+ * - hide(): hides the current notification
+ *
+ * Recommended: wrap in hooks or utility functions for cleaner usage across components.
+ */
+type State = {
+    alert: {
+        show: boolean;
+        type: "error" | "success" | "info" | "warning";
+        messages?: string[];
+        title?: string;
+        duration?: number;
+        loading?: boolean;
+        /** Where to display the notification */
+        position?: "top" | "bottom";
+    } | null;
+};
+type Actions = {
+    show: (alert: Omit<NonNullable<State["alert"]>, "show">) => void;
+    hide: () => void;
+};
+export declare const globalUIStore: import("zustand").UseBoundStore<import("zustand").StoreApi<State & Actions>>;
+export {};

package/dist/state/globalUIStore.js

@@ -0,0 +1,8 @@
+import { create } from "zustand";
+export const globalUIStore = create((set) => ({
+    alert: null,
+    show: (alert) => set({
+        alert: { ...alert, show: true }
+    }),
+    hide: () => set({ alert: null }),
+}));

package/dist/state/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./globalUIStore";
+export * from "./themeStore";

package/dist/state/index.js

@@ -0,0 +1,2 @@
+export * from "./globalUIStore";
+export * from "./themeStore";

package/dist/state/themeStore.d.ts

@@ -0,0 +1,6 @@
+export type ThemeStore = {
+    userTheme: "system" | "light" | "dark";
+    setTheme: (theme: "system" | "light" | "dark") => void;
+    loadTheme: () => void;
+};
+export declare const useThemeStore: import("zustand").UseBoundStore<import("zustand").StoreApi<ThemeStore>>;

package/dist/state/themeStore.js

@@ -0,0 +1,38 @@
+import { Platform } from "react-native";
+import { create } from "zustand";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+const THEME_KEY = "user-theme-preference";
+export const useThemeStore = create((set) => ({
+    userTheme: "system",
+    setTheme: (theme) => {
+        set({ userTheme: theme });
+        // Save directly when setting theme
+        if (Platform.OS !== "web") {
+            AsyncStorage.setItem(THEME_KEY, theme).catch(() => {
+                // Silently fail if storage is not available
+            });
+        }
+        else if (typeof window !== "undefined" && window.localStorage) {
+            localStorage.setItem(THEME_KEY, theme);
+        }
+    },
+    loadTheme: () => {
+        if (Platform.OS !== "web") {
+            AsyncStorage.getItem(THEME_KEY).then((saved) => {
+                if (saved && (saved === "system" || saved === "light" || saved === "dark")) {
+                    set({ userTheme: saved });
+                }
+            }).catch(() => {
+                // Use default if loading fails
+            });
+        }
+        else if (typeof window !== "undefined" && window.localStorage) {
+            const saved = localStorage.getItem(THEME_KEY);
+            if (saved && (saved === "system" || saved === "light" || saved === "dark")) {
+                set({ userTheme: saved });
+            }
+        }
+    }
+}));
+// Load saved theme on store creation
+useThemeStore.getState().loadTheme();

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@mrmeg/expo-ui",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Reusable Expo and React Native UI primitives for MrMeg projects.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "default": "./dist/components/index.js"
+    },
+    "./components/*": {
+      "types": "./dist/components/*.d.ts",
+      "default": "./dist/components/*.js"
+    },
+    "./constants": {
+      "types": "./dist/constants/index.d.ts",
+      "default": "./dist/constants/index.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "default": "./dist/hooks/index.js"
+    },
+    "./state": {
+      "types": "./dist/state/index.d.ts",
+      "default": "./dist/state/index.js"
+    },
+    "./lib": {
+      "types": "./dist/lib/index.d.ts",
+      "default": "./dist/lib/index.js"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "jest --config ../../jest.config.js packages/ui/src --runInBand --watchman=false",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "publish:dry-run": "bun pm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@expo/vector-icons": "*",
+    "@react-native-async-storage/async-storage": "*",
+    "@rn-primitives/accordion": "*",
+    "@rn-primitives/alert-dialog": "*",
+    "@rn-primitives/checkbox": "*",
+    "@rn-primitives/collapsible": "*",
+    "@rn-primitives/dialog": "*",
+    "@rn-primitives/dropdown-menu": "*",
+    "@rn-primitives/label": "*",
+    "@rn-primitives/popover": "*",
+    "@rn-primitives/portal": "*",
+    "@rn-primitives/radio-group": "*",
+    "@rn-primitives/select": "*",
+    "@rn-primitives/separator": "*",
+    "@rn-primitives/slot": "*",
+    "@rn-primitives/switch": "*",
+    "@rn-primitives/tabs": "*",
+    "@rn-primitives/toggle": "*",
+    "@rn-primitives/toggle-group": "*",
+    "@rn-primitives/tooltip": "*",
+    "@rn-primitives/types": "*",
+    "@sentry/react-native": "*",
+    "expo": "*",
+    "expo-font": "*",
+    "expo-haptics": "*",
+    "react": "*",
+    "react-native": "*",
+    "react-native-gesture-handler": "*",
+    "react-native-reanimated": "*",
+    "react-native-safe-area-context": "*",
+    "react-native-web": "*",
+    "zustand": "*"
+  },
+  "devDependencies": {
+    "@types/react": "~19.2.14",
+    "typescript": "~5.9.2"
+  }
+}