@molecule/app-react-native 1.0.0

package/dist/hooks/useAppState.d.ts

@@ -0,0 +1,27 @@
+/**
+ * React Native hook for app foreground/background state.
+ *
+ * @module
+ */
+import type { UseAppStateResult } from '../types.js';
+/**
+ * Tracks whether the app is in the foreground, background, or inactive.
+ *
+ * Uses React Native's `AppState` API under the hood. Falls back to
+ * 'active' on platforms where AppState is unavailable.
+ *
+ * @returns Current app state and whether the app is active.
+ *
+ * @example
+ * ```tsx
+ * const { appState, isActive } = useAppState()
+ *
+ * useEffect(() => {
+ *   if (isActive) {
+ *     refreshData()
+ *   }
+ * }, [isActive])
+ * ```
+ */
+export declare function useAppState(): UseAppStateResult;
+//# sourceMappingURL=useAppState.d.ts.map

package/dist/hooks/useAppState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAppState.d.ts","sourceRoot":"","sources":["../../src/hooks/useAppState.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAIpD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAmC/C"}

package/dist/hooks/useAppState.js

@@ -0,0 +1,48 @@
+/**
+ * React Native hook for app foreground/background state.
+ *
+ * @module
+ */
+import { useEffect, useState } from 'react';
+/**
+ * Tracks whether the app is in the foreground, background, or inactive.
+ *
+ * Uses React Native's `AppState` API under the hood. Falls back to
+ * 'active' on platforms where AppState is unavailable.
+ *
+ * @returns Current app state and whether the app is active.
+ *
+ * @example
+ * ```tsx
+ * const { appState, isActive } = useAppState()
+ *
+ * useEffect(() => {
+ *   if (isActive) {
+ *     refreshData()
+ *   }
+ * }, [isActive])
+ * ```
+ */
+export function useAppState() {
+    const [appState, setAppState] = useState('active');
+    useEffect(() => {
+        let cleanup;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { AppState } = require('react-native');
+            setAppState(AppState.currentState || 'active');
+            const subscription = AppState.addEventListener('change', (nextState) => {
+                setAppState(nextState || 'active');
+            });
+            cleanup = () => subscription.remove();
+        }
+        catch (_error) {
+            // Not running in React Native — stay 'active'
+        }
+        return cleanup;
+    }, []);
+    return {
+        appState,
+        isActive: appState === 'active',
+    };
+}

package/dist/hooks/useBackHandler.d.ts

@@ -0,0 +1,28 @@
+/**
+ * React Native hook for Android hardware back button.
+ *
+ * @module
+ */
+import type { UseBackHandlerOptions } from '../types.js';
+/**
+ * Registers a handler for the Android hardware back button.
+ *
+ * Return `true` from the handler to prevent the default back behavior,
+ * or `false` to allow it.
+ *
+ * @param handler - Callback invoked when the hardware back button is pressed.
+ * @param options - Optional configuration.
+ *
+ * @example
+ * ```tsx
+ * useBackHandler(() => {
+ *   if (isModalOpen) {
+ *     closeModal()
+ *     return true // Prevent default back
+ *   }
+ *   return false // Allow default back
+ * })
+ * ```
+ */
+export declare function useBackHandler(handler: () => boolean, options?: UseBackHandlerOptions): void;
+//# sourceMappingURL=useBackHandler.d.ts.map

package/dist/hooks/useBackHandler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBackHandler.d.ts","sourceRoot":"","sources":["../../src/hooks/useBackHandler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAExD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,OAAO,EAAE,OAAO,GAAE,qBAA0B,GAAG,IAAI,CAyBhG"}

package/dist/hooks/useBackHandler.js

@@ -0,0 +1,46 @@
+/**
+ * React Native hook for Android hardware back button.
+ *
+ * @module
+ */
+import { useEffect } from 'react';
+/**
+ * Registers a handler for the Android hardware back button.
+ *
+ * Return `true` from the handler to prevent the default back behavior,
+ * or `false` to allow it.
+ *
+ * @param handler - Callback invoked when the hardware back button is pressed.
+ * @param options - Optional configuration.
+ *
+ * @example
+ * ```tsx
+ * useBackHandler(() => {
+ *   if (isModalOpen) {
+ *     closeModal()
+ *     return true // Prevent default back
+ *   }
+ *   return false // Allow default back
+ * })
+ * ```
+ */
+export function useBackHandler(handler, options = {}) {
+    const { enabled = true } = options;
+    useEffect(() => {
+        if (!enabled)
+            return;
+        // Dynamic import to avoid crashes on non-RN platforms
+        let cleanup;
+        try {
+            // BackHandler is available from react-native
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { BackHandler } = require('react-native');
+            const subscription = BackHandler.addEventListener('hardwareBackPress', handler);
+            cleanup = () => subscription.remove();
+        }
+        catch (_error) {
+            // Not running in React Native — no-op
+        }
+        return cleanup;
+    }, [handler, enabled]);
+}

package/dist/hooks/useKeyboardHeight.d.ts

@@ -0,0 +1,27 @@
+/**
+ * React Native hook for keyboard visibility and height.
+ *
+ * @module
+ */
+import type { UseKeyboardHeightResult } from '../types.js';
+/**
+ * Tracks soft keyboard visibility and height.
+ *
+ * Uses React Native's `Keyboard` API. Falls back to hidden state
+ * on platforms where Keyboard is unavailable.
+ *
+ * @returns Current keyboard height and visibility state.
+ *
+ * @example
+ * ```tsx
+ * const { keyboardHeight, isKeyboardVisible } = useKeyboardHeight()
+ *
+ * return (
+ *   <View style={{ paddingBottom: keyboardHeight }}>
+ *     <TextInput />
+ *   </View>
+ * )
+ * ```
+ */
+export declare function useKeyboardHeight(): UseKeyboardHeightResult;
+//# sourceMappingURL=useKeyboardHeight.d.ts.map

package/dist/hooks/useKeyboardHeight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useKeyboardHeight.d.ts","sourceRoot":"","sources":["../../src/hooks/useKeyboardHeight.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,IAAI,uBAAuB,CA2C3D"}

package/dist/hooks/useKeyboardHeight.js

@@ -0,0 +1,55 @@
+/**
+ * React Native hook for keyboard visibility and height.
+ *
+ * @module
+ */
+import { useEffect, useState } from 'react';
+/**
+ * Tracks soft keyboard visibility and height.
+ *
+ * Uses React Native's `Keyboard` API. Falls back to hidden state
+ * on platforms where Keyboard is unavailable.
+ *
+ * @returns Current keyboard height and visibility state.
+ *
+ * @example
+ * ```tsx
+ * const { keyboardHeight, isKeyboardVisible } = useKeyboardHeight()
+ *
+ * return (
+ *   <View style={{ paddingBottom: keyboardHeight }}>
+ *     <TextInput />
+ *   </View>
+ * )
+ * ```
+ */
+export function useKeyboardHeight() {
+    const [keyboardHeight, setKeyboardHeight] = useState(0);
+    useEffect(() => {
+        const cleanups = [];
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { Keyboard, Platform } = require('react-native');
+            const showEvent = Platform.OS === 'ios' ? 'keyboardWillShow' : 'keyboardDidShow';
+            const hideEvent = Platform.OS === 'ios' ? 'keyboardWillHide' : 'keyboardDidHide';
+            const showSub = Keyboard.addListener(showEvent, (e) => {
+                setKeyboardHeight(e.endCoordinates.height);
+            });
+            cleanups.push(() => showSub.remove());
+            const hideSub = Keyboard.addListener(hideEvent, () => {
+                setKeyboardHeight(0);
+            });
+            cleanups.push(() => hideSub.remove());
+        }
+        catch (_error) {
+            // Not running in React Native (e.g. web/SSR); the Keyboard API is
+            // unavailable and the hook falls back to the hidden-state default.
+            // Ignoring is safe because no keyboard subscriptions were registered.
+        }
+        return () => cleanups.forEach((fn) => fn());
+    }, []);
+    return {
+        keyboardHeight,
+        isKeyboardVisible: keyboardHeight > 0,
+    };
+}

package/dist/hooks/useSafeArea.d.ts

@@ -0,0 +1,35 @@
+/**
+ * React Native hook for safe area insets.
+ *
+ * @module
+ */
+/**
+ * Safe area inset values in points.
+ */
+export interface SafeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Returns the current safe area insets from `react-native-safe-area-context`.
+ *
+ * Must be used within a `SafeAreaProvider`. Falls back to zero insets
+ * if the context is unavailable.
+ *
+ * @returns Safe area insets for the current device.
+ *
+ * @example
+ * ```tsx
+ * const insets = useSafeArea()
+ *
+ * return (
+ *   <View style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}>
+ *     <App />
+ *   </View>
+ * )
+ * ```
+ */
+export declare function useSafeArea(): SafeAreaInsets;
+//# sourceMappingURL=useSafeArea.d.ts.map

package/dist/hooks/useSafeArea.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSafeArea.d.ts","sourceRoot":"","sources":["../../src/hooks/useSafeArea.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,IAAI,cAAc,CAY5C"}

package/dist/hooks/useSafeArea.js

@@ -0,0 +1,36 @@
+/**
+ * React Native hook for safe area insets.
+ *
+ * @module
+ */
+/**
+ * Returns the current safe area insets from `react-native-safe-area-context`.
+ *
+ * Must be used within a `SafeAreaProvider`. Falls back to zero insets
+ * if the context is unavailable.
+ *
+ * @returns Safe area insets for the current device.
+ *
+ * @example
+ * ```tsx
+ * const insets = useSafeArea()
+ *
+ * return (
+ *   <View style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}>
+ *     <App />
+ *   </View>
+ * )
+ * ```
+ */
+export function useSafeArea() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { useSafeAreaInsets } = require('react-native-safe-area-context');
+        return useSafeAreaInsets();
+    }
+    catch (_error) {
+        // Safe to ignore: react-native-safe-area-context is an optional peer dep;
+        // if it is absent or the provider is not mounted, zero insets are the documented fallback.
+        return { top: 0, right: 0, bottom: 0, left: 0 };
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * React Native framework bindings for molecule.dev.
+ *
+ * Re-exports every hook and provider from `@molecule/app-react` (they are pure
+ * React — no DOM dependency) and adds RN-specific hooks: `useAppState`
+ * (foreground/background), `useBackHandler` (Android back button),
+ * `useKeyboardHeight`, and `useSafeArea`.
+ *
+ * @example
+ * ```tsx
+ * import { MoleculeProvider, useAuth, useAppState, useSafeArea } from '@molecule/app-react-native'
+ * import { SafeAreaProvider } from 'react-native-safe-area-context'
+ * import { View } from 'react-native'
+ * import { provider as stateProvider } from '@molecule/app-state-zustand'
+ * import { createJWTAuthClient } from '@molecule/app-auth'
+ *
+ * const authClient = createJWTAuthClient({ baseURL: 'https://api.example.com' })
+ *
+ * function Shell() {
+ *   const { isAuthenticated } = useAuth()
+ *   const { isActive } = useAppState()
+ *   const insets = useSafeArea()
+ *   return (
+ *     <View style={{ paddingTop: insets.top }}>
+ *       {isAuthenticated && isActive ? <View /> : null}
+ *     </View>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <SafeAreaProvider>
+ *       <MoleculeProvider state={stateProvider} auth={authClient}>
+ *         <Shell />
+ *       </MoleculeProvider>
+ *     </SafeAreaProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @remarks
+ * - **The re-exported hooks keep `@molecule/app-react`'s contract**: each one throws unless its
+ *   provider was passed to `MoleculeProvider` (or mounted individually). See the
+ *   `@molecule/app-react` docs for the hook→provider map.
+ * - **`useSafeArea` needs `SafeAreaProvider`** (from `react-native-safe-area-context`) mounted at
+ *   the root; without it — or without the library installed — it silently returns zero insets
+ *   rather than throwing, so a notch-overlapped header means missing provider, not a bug in the hook.
+ * - `useBackHandler` only fires on Android; iOS has no hardware back button.
+ * - For components/styling pair this with `@molecule/app-ui-react-native`, whose ClassMap
+ *   styling requires the NativeWind setup (`@molecule/app-ui-nativewind`) — see that package's docs.
+ *
+ * @module
+ */
+export * from '@molecule/app-react';
+export { useAppState } from './hooks/useAppState.js';
+export { useBackHandler } from './hooks/useBackHandler.js';
+export { useKeyboardHeight } from './hooks/useKeyboardHeight.js';
+export { useSafeArea } from './hooks/useSafeArea.js';
+export type { UseAppStateResult, UseBackHandlerOptions, UseKeyboardHeightResult } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAGH,cAAc,qBAAqB,CAAA;AAGnC,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAGpD,YAAY,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,60 @@
+/**
+ * React Native framework bindings for molecule.dev.
+ *
+ * Re-exports every hook and provider from `@molecule/app-react` (they are pure
+ * React — no DOM dependency) and adds RN-specific hooks: `useAppState`
+ * (foreground/background), `useBackHandler` (Android back button),
+ * `useKeyboardHeight`, and `useSafeArea`.
+ *
+ * @example
+ * ```tsx
+ * import { MoleculeProvider, useAuth, useAppState, useSafeArea } from '@molecule/app-react-native'
+ * import { SafeAreaProvider } from 'react-native-safe-area-context'
+ * import { View } from 'react-native'
+ * import { provider as stateProvider } from '@molecule/app-state-zustand'
+ * import { createJWTAuthClient } from '@molecule/app-auth'
+ *
+ * const authClient = createJWTAuthClient({ baseURL: 'https://api.example.com' })
+ *
+ * function Shell() {
+ *   const { isAuthenticated } = useAuth()
+ *   const { isActive } = useAppState()
+ *   const insets = useSafeArea()
+ *   return (
+ *     <View style={{ paddingTop: insets.top }}>
+ *       {isAuthenticated && isActive ? <View /> : null}
+ *     </View>
+ *   )
+ * }
+ *
+ * function App() {
+ *   return (
+ *     <SafeAreaProvider>
+ *       <MoleculeProvider state={stateProvider} auth={authClient}>
+ *         <Shell />
+ *       </MoleculeProvider>
+ *     </SafeAreaProvider>
+ *   )
+ * }
+ * ```
+ *
+ * @remarks
+ * - **The re-exported hooks keep `@molecule/app-react`'s contract**: each one throws unless its
+ *   provider was passed to `MoleculeProvider` (or mounted individually). See the
+ *   `@molecule/app-react` docs for the hook→provider map.
+ * - **`useSafeArea` needs `SafeAreaProvider`** (from `react-native-safe-area-context`) mounted at
+ *   the root; without it — or without the library installed — it silently returns zero insets
+ *   rather than throwing, so a notch-overlapped header means missing provider, not a bug in the hook.
+ * - `useBackHandler` only fires on Android; iOS has no hardware back button.
+ * - For components/styling pair this with `@molecule/app-ui-react-native`, whose ClassMap
+ *   styling requires the NativeWind setup (`@molecule/app-ui-nativewind`) — see that package's docs.
+ *
+ * @module
+ */
+// Re-export everything from @molecule/app-react — all hooks are RN-compatible
+export * from '@molecule/app-react';
+// RN-specific hooks
+export { useAppState } from './hooks/useAppState.js';
+export { useBackHandler } from './hooks/useBackHandler.js';
+export { useKeyboardHeight } from './hooks/useKeyboardHeight.js';
+export { useSafeArea } from './hooks/useSafeArea.js';

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * React Native specific types for molecule.dev.
+ *
+ * @module
+ */
+/**
+ * Options for the useBackHandler hook.
+ */
+export interface UseBackHandlerOptions {
+    /** Whether the handler is enabled. Defaults to true. */
+    enabled?: boolean;
+}
+/**
+ * Result from the useAppState hook.
+ */
+export interface UseAppStateResult {
+    /** Current app state: 'active' | 'background' | 'inactive' */
+    appState: string;
+    /** Whether the app is in the foreground */
+    isActive: boolean;
+}
+/**
+ * Result from the useKeyboardHeight hook.
+ */
+export interface UseKeyboardHeightResult {
+    /** Current keyboard height in points (0 when hidden) */
+    keyboardHeight: number;
+    /** Whether the keyboard is currently visible */
+    isKeyboardVisible: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,8DAA8D;IAC9D,QAAQ,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,wDAAwD;IACxD,cAAc,EAAE,MAAM,CAAA;IACtB,gDAAgD;IAChD,iBAAiB,EAAE,OAAO,CAAA;CAC3B"}

package/dist/types.js

@@ -0,0 +1,6 @@
+/**
+ * React Native specific types for molecule.dev.
+ *
+ * @module
+ */
+export {};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@molecule/app-react-native",
+  "version": "1.0.0",
+  "description": "React Native framework bindings for molecule.dev",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "molecule",
+    "react-native",
+    "framework"
+  ],
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@molecule/app-react": "1.0.0",
+    "@types/node": "26.1.2",
+    "react": "19.2.8",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "peerDependencies": {
+    "@molecule/app-keyboard": "^1.0.0",
+    "@molecule/app-lifecycle": "^1.0.0",
+    "@molecule/app-react": "^1.0.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "react-native": ">=0.72.0",
+    "react-native-safe-area-context": ">=4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@molecule/app-react": {
+      "optional": true
+    },
+    "@molecule/app-lifecycle": {
+      "optional": true
+    },
+    "@molecule/app-keyboard": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    },
+    "react-native-safe-area-context": {
+      "optional": true
+    }
+  }
+}