@granite-js/react-native 0.1.13 → 0.1.15

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @granite-js/react-native
 
+## 0.1.15
+
+### Patch Changes
+
+- d16ee87: Add useInitialProps, useInitialSearchParams hook.
+- Updated dependencies [d16ee87]
+  - @granite-js/plugin-core@0.1.15
+  - @granite-js/style-utils@0.1.15
+  - @granite-js/lottie@0.1.15
+  - @granite-js/native@0.1.15
+  - @granite-js/image@0.1.15
+  - @granite-js/mpack@0.1.15
+  - @granite-js/jest@0.1.15
+  - @granite-js/cli@0.1.15
+
+## 0.1.14
+
+### Patch Changes
+
+- 0520d19: Fix type error
+- a06bb7d: Remove useWaitForReturnNavigator
+- 6d38bc5: Clarify error message for missing \_404 Page
+  - @granite-js/cli@0.1.14
+  - @granite-js/image@0.1.14
+  - @granite-js/jest@0.1.14
+  - @granite-js/lottie@0.1.14
+  - @granite-js/mpack@0.1.14
+  - @granite-js/native@0.1.14
+  - @granite-js/plugin-core@0.1.14
+  - @granite-js/style-utils@0.1.14
+
 ## 0.1.13
 
 ### Patch Changes

package/dist/app/context/InitialPropsContext.d.ts

@@ -0,0 +1,28 @@
+import { type PropsWithChildren } from 'react';
+import { InitialProps } from '../../initial-props';
+export declare const InitialPropsContext: import("react").Context<InitialProps | null>;
+export declare function InitialPropsProvider({ children, initialProps }: PropsWithChildren<{
+    initialProps: InitialProps;
+}>): import("react/jsx-runtime").JSX.Element;
+/**
+ * @public
+ * @name useInitialProps
+ * @category Core
+ * @description Provides initial data passed from the native platform (Android or iOS) when entering a specific screen in React Native apps. This data can be used to immediately apply themes or user settings right after app launch. For example, you can receive dark mode settings from the native platform and apply dark mode immediately when the React Native app starts.
+ * @returns {InitialProps} Initial data for the app
+ * @example
+ *
+ * ### Checking dark mode status with initial data
+ *
+ * ```tsx
+ * import { useInitialProps } from '@granite-js/react-native';
+ *
+ * function Page() {
+ *   const initialProps = useInitialProps();
+ *   // 'light' or 'dark'
+ *   console.log(initialProps.initialColorPreference);
+ *   return <></>;
+ * }
+ * ```
+ */
+export declare function useInitialProps<T extends InitialProps>(): T;

package/dist/app/context/useInitialSearchParams.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @public
+ * @name useInitialSearchParams
+ * @category EnvironmentCheck
+ * @description A hook that returns the query parameters from the URL passed when the app is first launched, directly as an object. This allows immediate application of initial entry handling like login or theme settings, enabling quick customization of user experience. If an invalid URL is provided, it safely returns an empty object. When the native platform (Android or iOS) passes a URL with query parameters to the app on first launch, you can easily read each parameter value using this hook.
+ *
+ * @returns {Record<string, string>} An object containing key-value pairs of query parameters from the initial URL. Returns an empty object if there are no query parameters or if the URL is invalid.
+ * @example
+ * ```tsx
+ * import { useInitialSearchParams } from '@granite-js/react-native';
+ *
+ * function Page() {
+ *   const params = useInitialSearchParams();
+ *   // Example: if initial URL is myapp://home?userId=42&theme=dark
+ *   console.log(params.userId); // "42"
+ *   console.log(params.theme);  // "dark"
+ *   return <></>;
+ * }
+ * ```
+ */
+export declare function useInitialSearchParams(): {
+    [k: string]: string;
+};

package/dist/app/index.d.ts

@@ -1,2 +1,4 @@
+export { useInitialProps } from './context/InitialPropsContext';
+export { useInitialSearchParams } from './context/useInitialSearchParams';
 export { Granite } from './Granite';
 export type { GraniteProps } from './Granite';

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import './types/global';
-export { Granite } from './app';
+export { Granite, useInitialSearchParams, useInitialProps } from './app';
 export * from '@granite-js/style-utils';
 export * from '@granite-js/image';
 export * from '@granite-js/lottie';
@@ -11,7 +11,6 @@ export * from './keyboard';
 export * from './intersection-observer';
 export * from './impression-area';
 export * from './scroll-view-inertial-background';
-export * from './react';
 export * from './router/createRoute';
 export * from './event';
 export * from './video';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@granite-js/react-native",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "The Granite Framework",
   "bin": {
     "granite": "./bin/cli.js"
@@ -74,7 +74,7 @@
     "@babel/core": "^7.24.9",
     "@babel/preset-env": "^7.24.8",
     "@babel/preset-typescript": "^7.24.7",
-    "@granite-js/native": "0.1.13",
+    "@granite-js/native": "0.1.15",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/react": "^16.1.0",
     "@types/babel__core": "^7",
@@ -100,13 +100,13 @@
     "react-native": "*"
   },
   "dependencies": {
-    "@granite-js/cli": "0.1.13",
-    "@granite-js/image": "0.1.13",
-    "@granite-js/jest": "0.1.13",
-    "@granite-js/lottie": "0.1.13",
-    "@granite-js/mpack": "0.1.13",
-    "@granite-js/plugin-core": "0.1.13",
-    "@granite-js/style-utils": "0.1.13",
+    "@granite-js/cli": "0.1.15",
+    "@granite-js/image": "0.1.15",
+    "@granite-js/jest": "0.1.15",
+    "@granite-js/lottie": "0.1.15",
+    "@granite-js/mpack": "0.1.15",
+    "@granite-js/plugin-core": "0.1.15",
+    "@granite-js/style-utils": "0.1.15",
     "es-toolkit": "^1.39.8",
     "react-native-url-polyfill": "1.3.0"
   }

package/src/app/AppRoot.tsx

@@ -6,6 +6,7 @@ import { BackEventProvider } from '../use-back-event';
 import { App } from './App';
 import type { GraniteProps } from './Granite';
 import { getSchemePrefix } from '../utils/getSchemePrefix';
+import { InitialPropsProvider } from './context/InitialPropsContext';
 
 /**
  * @internal
@@ -24,19 +25,21 @@ export function AppRoot({ appName, context, container: Container, initialProps,
   });
 
   return (
-    <App {...initialProps}>
-      <SafeAreaProvider>
-        <BackEventProvider>
-          <Router
-            context={context}
-            initialProps={initialProps}
-            initialScheme={initialScheme}
-            container={Container}
-            prefix={prefix}
-            {...router}
-          />
-        </BackEventProvider>
-      </SafeAreaProvider>
-    </App>
+    <InitialPropsProvider initialProps={initialProps}>
+      <App {...initialProps}>
+        <SafeAreaProvider>
+          <BackEventProvider>
+            <Router
+              context={context}
+              initialProps={initialProps}
+              initialScheme={initialScheme}
+              container={Container}
+              prefix={prefix}
+              {...router}
+            />
+          </BackEventProvider>
+        </SafeAreaProvider>
+      </App>
+    </InitialPropsProvider>
   );
 }

package/src/app/context/InitialPropsContext.tsx

@@ -0,0 +1,39 @@
+import { createContext, useContext, type PropsWithChildren } from 'react';
+import { InitialProps } from '../../initial-props';
+
+export const InitialPropsContext = createContext<InitialProps | null>(null);
+
+export function InitialPropsProvider({ children, initialProps }: PropsWithChildren<{ initialProps: InitialProps }>) {
+  return <InitialPropsContext.Provider value={initialProps}>{children}</InitialPropsContext.Provider>;
+}
+
+/**
+ * @public
+ * @name useInitialProps
+ * @category Core
+ * @description Provides initial data passed from the native platform (Android or iOS) when entering a specific screen in React Native apps. This data can be used to immediately apply themes or user settings right after app launch. For example, you can receive dark mode settings from the native platform and apply dark mode immediately when the React Native app starts.
+ * @returns {InitialProps} Initial data for the app
+ * @example
+ *
+ * ### Checking dark mode status with initial data
+ *
+ * ```tsx
+ * import { useInitialProps } from '@granite-js/react-native';
+ *
+ * function Page() {
+ *   const initialProps = useInitialProps();
+ *   // 'light' or 'dark'
+ *   console.log(initialProps.initialColorPreference);
+ *   return <></>;
+ * }
+ * ```
+ */
+export function useInitialProps<T extends InitialProps>() {
+  const initialProps = useContext(InitialPropsContext);
+
+  if (!initialProps) {
+    throw new Error('InitialPropsContext not found');
+  }
+
+  return initialProps as T;
+}

package/src/app/context/useInitialSearchParams.ts

@@ -0,0 +1,32 @@
+import { useInitialProps } from './InitialPropsContext';
+import { getSchemeUri } from '../../native-modules';
+
+/**
+ * @public
+ * @name useInitialSearchParams
+ * @category EnvironmentCheck
+ * @description A hook that returns the query parameters from the URL passed when the app is first launched, directly as an object. This allows immediate application of initial entry handling like login or theme settings, enabling quick customization of user experience. If an invalid URL is provided, it safely returns an empty object. When the native platform (Android or iOS) passes a URL with query parameters to the app on first launch, you can easily read each parameter value using this hook.
+ *
+ * @returns {Record<string, string>} An object containing key-value pairs of query parameters from the initial URL. Returns an empty object if there are no query parameters or if the URL is invalid.
+ * @example
+ * ```tsx
+ * import { useInitialSearchParams } from '@granite-js/react-native';
+ *
+ * function Page() {
+ *   const params = useInitialSearchParams();
+ *   // Example: if initial URL is myapp://home?userId=42&theme=dark
+ *   console.log(params.userId); // "42"
+ *   console.log(params.theme);  // "dark"
+ *   return <></>;
+ * }
+ * ```
+ */
+export function useInitialSearchParams() {
+  const scheme = useInitialProps().scheme ?? getSchemeUri();
+
+  try {
+    return Object.fromEntries(new URL(scheme).searchParams);
+  } catch {
+    return {};
+  }
+}

package/src/app/index.ts

@@ -1,2 +1,4 @@
+export { useInitialProps } from './context/InitialPropsContext';
+export { useInitialSearchParams } from './context/useInitialSearchParams';
 export { Granite } from './Granite';
 export type { GraniteProps } from './Granite';

package/src/index.ts

@@ -1,6 +1,6 @@
 import './types/global';
 
-export { Granite } from './app';
+export { Granite, useInitialSearchParams, useInitialProps } from './app';
 export * from '@granite-js/style-utils';
 export * from '@granite-js/image';
 export * from '@granite-js/lottie';
@@ -13,7 +13,6 @@ export * from './keyboard';
 export * from './intersection-observer';
 export * from './impression-area';
 export * from './scroll-view-inertial-background';
-export * from './react';
 export * from './router/createRoute';
 export * from './event';
 export * from './video';

package/src/router/utils/screen.tsx

@@ -72,6 +72,12 @@ export function getScreenPathMapConfig(routeScreens: RouteScreen[]) {
     path: '',
   };
 
+  const notFoundPage = routeScreens.find((screen) => screen.path === '/_404');
+
+  if (notFoundPage == null) {
+    throw new Error('404 page not found. Please create a `_404.ts` or `_404.tsx` file in the `pages/*` folder.');
+  }
+
   // https://reactnavigation.org/docs/configuring-links/#handling-unmatched-routes-or-404
   screensConfig['/_404'] = {
     path: '*',

package/dist/react/index.d.ts

@@ -1 +0,0 @@
-export { useWaitForReturnNavigator } from './useWaitForReturnNavigator';

package/dist/react/useWaitForReturnNavigator.d.ts

@@ -1,39 +0,0 @@
-/**
- * @public
- * @category Screen Control
- * @name useWaitForReturnNavigator
- * @description
- * A Hook that helps execute the next code synchronously when returning from a screen transition.
- * Screen navigation uses [@react-navigation/native `useNavigation`'s `navigate`](https://reactnavigation.org/docs/6.x/navigation-prop#navigate).
- *
- * For example, it can be used when you want to log that a user has navigated to another screen and returned.
- *
- * @example
- * ### Example of code execution when returning from screen navigation
- *
- * When the **"Navigate"** button is pressed, it navigates to another screen, and logs are created when returning.
- *
- * ```tsx
- * import { Button } from 'react-native';
- * import { useWaitForReturnNavigator } from '@granite-js/react-native';
- *
- * export function UseWaitForReturnNavigator() {
- *   const navigate = useWaitForReturnNavigator();
- *
- *   return (
- *     <>
- *       <Button
- *         title="Navigate"
- *         onPress={async () => {
- *           console.log(1);
- *           await navigate('/examples/use-visibility');
- *           // This code executes when returning to the screen
- *           console.log(2);
- *         }}
- *       />
- *     </>
- *   );
- * }
- * ```
- */
-export declare function useWaitForReturnNavigator<T extends Record<string, object | undefined>>(): <RouteName extends keyof T>(route: RouteName, params?: T[RouteName]) => Promise<void>;

package/src/react/index.ts

@@ -1 +0,0 @@
-export { useWaitForReturnNavigator } from './useWaitForReturnNavigator';

package/src/react/useWaitForReturnNavigator.ts

@@ -1,75 +0,0 @@
-import { useNavigation } from '@granite-js/native/@react-navigation/native';
-import { NativeStackNavigationProp } from '@granite-js/native/@react-navigation/native-stack';
-import { useCallback, useRef } from 'react';
-import { useVisibilityChange, type VisibilityState } from '../visibility';
-
-/**
- * @public
- * @category Screen Control
- * @name useWaitForReturnNavigator
- * @description
- * A Hook that helps execute the next code synchronously when returning from a screen transition.
- * Screen navigation uses [@react-navigation/native `useNavigation`'s `navigate`](https://reactnavigation.org/docs/6.x/navigation-prop#navigate).
- *
- * For example, it can be used when you want to log that a user has navigated to another screen and returned.
- *
- * @example
- * ### Example of code execution when returning from screen navigation
- *
- * When the **"Navigate"** button is pressed, it navigates to another screen, and logs are created when returning.
- *
- * ```tsx
- * import { Button } from 'react-native';
- * import { useWaitForReturnNavigator } from '@granite-js/react-native';
- *
- * export function UseWaitForReturnNavigator() {
- *   const navigate = useWaitForReturnNavigator();
- *
- *   return (
- *     <>
- *       <Button
- *         title="Navigate"
- *         onPress={async () => {
- *           console.log(1);
- *           await navigate('/examples/use-visibility');
- *           // This code executes when returning to the screen
- *           console.log(2);
- *         }}
- *       />
- *     </>
- *   );
- * }
- * ```
- */
-
-export function useWaitForReturnNavigator<T extends Record<string, object | undefined>>() {
-  const callbacks = useRef<Array<() => void>>([]).current;
-  const navigation = useNavigation<NativeStackNavigationProp<T>>();
-
-  const startNavigating = useCallback(
-    <RouteName extends keyof T>(route: RouteName, params?: T[RouteName]): Promise<void> => {
-      return new Promise<void>((resolve) => {
-        callbacks.push(resolve);
-        navigation.navigate(route as any, params as any);
-      });
-    },
-    [callbacks, navigation]
-  );
-
-  const handleVisibilityChange = useCallback(
-    (state: VisibilityState) => {
-      if (state === 'visible' && callbacks.length > 0) {
-        for (const callback of callbacks) {
-          callback();
-        }
-
-        callbacks.splice(0, callbacks.length);
-      }
-    },
-    [callbacks]
-  );
-
-  useVisibilityChange(handleVisibilityChange);
-
-  return startNavigating;
-}