@idealyst/navigation 1.1.4 → 1.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/navigation",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Cross-platform navigation library for React and React Native",
   "readme": "README.md",
   "main": "src/index.ts",
@@ -43,8 +43,8 @@
     "publish:npm": "npm publish"
   },
   "peerDependencies": {
-    "@idealyst/components": "^1.1.4",
-    "@idealyst/theme": "^1.1.4",
+    "@idealyst/components": "^1.1.5",
+    "@idealyst/theme": "^1.1.5",
     "@react-navigation/bottom-tabs": ">=7.0.0",
     "@react-navigation/drawer": ">=7.0.0",
     "@react-navigation/native": ">=7.0.0",
@@ -60,10 +60,10 @@
     "react-router-dom": ">=6.0.0"
   },
   "devDependencies": {
-    "@idealyst/components": "^1.1.4",
+    "@idealyst/components": "^1.1.5",
     "@idealyst/datagrid": "^1.0.93",
     "@idealyst/datepicker": "^1.0.93",
-    "@idealyst/theme": "^1.1.4",
+    "@idealyst/theme": "^1.1.5",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "react": "^19.1.0",

package/src/context/NavigatorContext.native.tsx

@@ -198,17 +198,23 @@ const UnwrappedNavigatorProvider = ({ route }: NavigatorProviderProps) => {
             return;
         }
 
+        // Merge route params with navigation state (state values stored directly in params)
+        const navigationParams = {
+            ...parsed.params,
+            ...(params.state || {}),
+        };
+
         if (params.replace) {
             // Use CommonActions.reset to replace the current route
             navigation.dispatch(
                 CommonActions.reset({
                     index: 0,
-                    routes: [{ name: parsed.routeName, params: parsed.params }],
+                    routes: [{ name: parsed.routeName, params: navigationParams }],
                 })
             );
         } else {
             // Navigate to the pattern route with extracted parameters
-            navigation.navigate(parsed.routeName as never, parsed.params as never);
+            navigation.navigate(parsed.routeName as never, navigationParams as never);
         }
     };
 
@@ -290,17 +296,23 @@ const DrawerNavigatorProvider = ({ navigation, route, children }: { navigation:
             return;
         }
 
+        // Merge route params with navigation state (state values stored directly in params)
+        const navigationParams = {
+            ...parsed.params,
+            ...(params.state || {}),
+        };
+
         if (params.replace) {
             // Use CommonActions.reset to replace the current route
             navigation.dispatch(
                 CommonActions.reset({
                     index: 0,
-                    routes: [{ name: parsed.routeName, params: parsed.params }],
+                    routes: [{ name: parsed.routeName, params: navigationParams }],
                 })
             );
         } else {
             // Navigate to the pattern route with extracted parameters
-            navigation.navigate(parsed.routeName as never, parsed.params as never);
+            navigation.navigate(parsed.routeName as never, navigationParams as never);
         }
     };
 

package/src/context/NavigatorContext.web.tsx

@@ -238,8 +238,23 @@ export const NavigatorProvider = ({
                 // If no notFoundComponent configured, React Router will render nothing
             }
 
-            // Use React Router's navigate function with replace option
-            reactRouterNavigate(path, { replace: params.replace });
+            // Build URL with query params if state is provided
+            let finalPath = path;
+            if (params.state && Object.keys(params.state).length > 0) {
+                const searchParams = new URLSearchParams();
+                for (const [key, value] of Object.entries(params.state)) {
+                    if (value !== undefined && value !== null) {
+                        searchParams.set(key, String(value));
+                    }
+                }
+                const queryString = searchParams.toString();
+                if (queryString) {
+                    finalPath = `${path}?${queryString}`;
+                }
+            }
+
+            // Use React Router's navigate function
+            reactRouterNavigate(finalPath, { replace: params.replace });
         }
     };
 

package/src/context/types.ts

@@ -11,6 +11,16 @@ export type NavigateParams = {
      * On web, this uses history.replace(). On native, this resets the navigation state.
      */
     replace?: boolean;
+    /**
+     * Optional state data to pass to the destination screen.
+     * On web, this is passed as URL query parameters (e.g., ?autostart=true).
+     * On native, this is passed via route params.
+     * Use useNavigationState() hook to access this data in the destination screen.
+     *
+     * Note: Values are serialized to strings. Booleans and numbers are automatically
+     * parsed back when using useNavigationState().
+     */
+    state?: Record<string, string | number | boolean>;
 };
 
 export type NavigatorProviderProps = {

package/src/hooks/index.native.ts

@@ -1,2 +1,3 @@
 // Native-specific hook exports
-export * from './useParams.native';
+export * from './useParams.native';
+export * from './useNavigationState.native';

package/src/hooks/index.ts

@@ -1,2 +1,3 @@
 // Cross-platform hook exports
-export * from './useParams.web'; // This will be overridden by platform-specific exports
+export * from './useParams.web'; // This will be overridden by platform-specific exports
+export * from './useNavigationState.web'; // This will be overridden by platform-specific exports

package/src/hooks/index.web.ts

@@ -1,2 +1,3 @@
 // Web-specific hook exports
-export * from './useParams.web';
+export * from './useParams.web';
+export * from './useNavigationState.web';

package/src/hooks/useNavigationState.native.ts

@@ -0,0 +1,34 @@
+import { useRoute } from '@react-navigation/native';
+
+export interface UseNavigationStateOptions {
+    /**
+     * Keys to remove from the URL query parameters after reading.
+     * This option only affects web - it has no effect on native.
+     * Included here for API consistency across platforms.
+     */
+    consume?: string[];
+}
+
+/**
+ * Hook to access navigation state passed via the navigate() function.
+ * On native, state is passed via route params (merged with path params).
+ * Returns the state object passed during navigation, or an empty object if no state was passed.
+ *
+ * @example
+ * // Navigate with state
+ * navigate({ path: '/recording', state: { autostart: true } });
+ *
+ * // Access state in destination screen
+ * const { autostart } = useNavigationState<{ autostart?: boolean }>();
+ *
+ * @example
+ * // The consume option is accepted but has no effect on native
+ * const { autostart } = useNavigationState<{ autostart?: boolean }>({ consume: ['autostart'] });
+ */
+export function useNavigationState<T extends Record<string, unknown> = Record<string, unknown>>(
+    _options?: UseNavigationStateOptions
+): T {
+    const route = useRoute();
+    const params = route.params as Record<string, unknown> | undefined;
+    return (params as T) || ({} as T);
+}

package/src/hooks/useNavigationState.web.ts

@@ -0,0 +1,87 @@
+import { useEffect, useRef } from 'react';
+import { useSearchParams } from '../router';
+
+export interface UseNavigationStateOptions {
+    /**
+     * Keys to remove from the URL query parameters after reading.
+     * This is useful for one-time state like 'autostart' that shouldn't persist in the URL.
+     * Only affects web - has no effect on native.
+     *
+     * @example
+     * // URL: /recording?autostart=true
+     * const { autostart } = useNavigationState<{ autostart?: boolean }>({ consume: ['autostart'] });
+     * // autostart = true, URL becomes: /recording
+     */
+    consume?: string[];
+}
+
+/**
+ * Hook to access navigation state passed via the navigate() function.
+ * On web, state is passed as URL query parameters.
+ * Returns the state object passed during navigation, or an empty object if no state was passed.
+ *
+ * @example
+ * // Navigate with state
+ * navigate({ path: '/recording', state: { autostart: true } });
+ *
+ * // Access state in destination screen
+ * const { autostart } = useNavigationState<{ autostart?: boolean }>();
+ * // URL will be: /recording?autostart=true
+ *
+ * @example
+ * // Consume (remove) the parameter after reading
+ * const { autostart } = useNavigationState<{ autostart?: boolean }>({ consume: ['autostart'] });
+ * // autostart = true, URL becomes: /recording (param removed)
+ */
+function parseSearchParams(searchParams: URLSearchParams): Record<string, unknown> {
+    const state: Record<string, unknown> = {};
+    searchParams.forEach((value, key) => {
+        if (value === 'true') {
+            state[key] = true;
+        } else if (value === 'false') {
+            state[key] = false;
+        } else if (!isNaN(Number(value)) && value !== '') {
+            state[key] = Number(value);
+        } else {
+            state[key] = value;
+        }
+    });
+    return state;
+}
+
+export function useNavigationState<T extends Record<string, unknown> = Record<string, unknown>>(
+    options?: UseNavigationStateOptions
+): T {
+    const [searchParams, setSearchParams] = useSearchParams();
+    const consumedStateRef = useRef<Record<string, unknown> | null>(null);
+    const hasConsumed = useRef(false);
+
+    // Capture consumed values before they're removed from URL
+    if (options?.consume && options.consume.length > 0 && !hasConsumed.current) {
+        const keysToConsume = options.consume.filter(key => searchParams.has(key));
+        if (keysToConsume.length > 0 && consumedStateRef.current === null) {
+            // Capture the full state including values we're about to consume
+            consumedStateRef.current = parseSearchParams(searchParams);
+        }
+    }
+
+    // Remove consumed keys from URL after initial read
+    useEffect(() => {
+        if (options?.consume && options.consume.length > 0 && !hasConsumed.current) {
+            const keysToRemove = options.consume.filter(key => searchParams.has(key));
+            if (keysToRemove.length > 0) {
+                hasConsumed.current = true;
+                const newParams = new URLSearchParams(searchParams);
+                keysToRemove.forEach(key => newParams.delete(key));
+                setSearchParams(newParams, { replace: true });
+            }
+        }
+    }, [options?.consume, searchParams, setSearchParams]);
+
+    // Return captured state if we consumed params, otherwise parse current URL
+    if (consumedStateRef.current !== null) {
+        return consumedStateRef.current as T;
+    }
+
+    return parseSearchParams(searchParams) as T;
+}