@granite-js/react-native 0.1.14 → 0.1.15

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # @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

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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@granite-js/react-native",
-  "version": "0.1.14",
+  "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.14",
+    "@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.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/plugin-core": "0.1.14",
-    "@granite-js/style-utils": "0.1.14",
+    "@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';