@idealyst/navigation 1.0.99 → 1.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/navigation",
-  "version": "1.0.99",
+  "version": "1.1.1",
   "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.0.99",
-    "@idealyst/theme": "^1.0.99",
+    "@idealyst/components": "^1.1.1",
+    "@idealyst/theme": "^1.1.1",
     "@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.0.99",
+    "@idealyst/components": "^1.1.1",
     "@idealyst/datagrid": "^1.0.93",
     "@idealyst/datepicker": "^1.0.93",
-    "@idealyst/theme": "^1.0.99",
+    "@idealyst/theme": "^1.1.1",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "react": "^19.1.0",
@@ -86,4 +86,4 @@
     "cross-platform",
     "router"
   ]
-}
+}

package/src/context/NavigatorContext.native.tsx

@@ -217,10 +217,20 @@ const UnwrappedNavigatorProvider = ({ route }: NavigatorProviderProps) => {
         return memo(buildNavigator(route));
     }, [route]);
 
+    const canGoBack = () => navigation.canGoBack();
+
+    const goBack = () => {
+        if (navigation.canGoBack()) {
+            navigation.goBack();
+        }
+    };
+
     return (
         <NavigatorContext.Provider value={{
             route,
             navigate,
+            canGoBack,
+            goBack,
         }}>
             <RouteComponent />
         </NavigatorContext.Provider>
@@ -294,8 +304,16 @@ const DrawerNavigatorProvider = ({ navigation, route, children }: { navigation:
         }
     };
 
+    const canGoBack = () => navigation.canGoBack();
+
+    const goBack = () => {
+        if (navigation.canGoBack()) {
+            navigation.goBack();
+        }
+    };
+
     return (
-        <DrawerNavigatorContext.Provider value={{ navigate, route }}>
+        <DrawerNavigatorContext.Provider value={{ navigate, route, canGoBack, goBack }}>
             {children}
         </DrawerNavigatorContext.Provider>
     );

package/src/context/NavigatorContext.web.tsx

@@ -1,11 +1,13 @@
 import React, { createContext, memo, useContext, useMemo } from 'react';
-import { useNavigate, useParams } from '../router';
+import { useNavigate, useParams, useLocation } from '../router';
 import { NavigateParams, NavigatorProviderProps, NavigatorContextValue } from './types';
 import { buildNavigator, NavigatorParam } from '../routing';
 
 const NavigatorContext = createContext<NavigatorContextValue>({
     navigate: () => {},
     route: undefined,
+    canGoBack: () => false,
+    goBack: () => {},
 });
 
 /**
@@ -171,10 +173,37 @@ function findInvalidRouteHandler(
     return handlers.length > 0 ? handlers[handlers.length - 1] : undefined;
 }
 
+/**
+ * Get the parent path from a given path.
+ * e.g., "/users/123/edit" -> "/users/123"
+ *       "/users" -> "/"
+ *       "/" -> null (no parent)
+ */
+function getParentPath(path: string): string | null {
+    const normalizedPath = path === '' ? '/' : path;
+
+    if (normalizedPath === '/') {
+        return null;
+    }
+
+    const segments = normalizedPath.split('/').filter(Boolean);
+
+    if (segments.length === 0) {
+        return null;
+    }
+
+    if (segments.length === 1) {
+        return '/';
+    }
+
+    return '/' + segments.slice(0, -1).join('/');
+}
+
 export const NavigatorProvider = ({
     route,
 }: NavigatorProviderProps) => {
     const reactRouterNavigate = useNavigate();
+    const location = useLocation();
 
     // Memoize the list of valid route patterns
     const validPatterns = useMemo(() => buildValidPatterns(route), [route]);
@@ -219,10 +248,27 @@ export const NavigatorProvider = ({
         return memo(buildNavigator(route));
     }, [route]);
 
+    const canGoBack = () => {
+        const parentPath = getParentPath(location.pathname);
+        if (!parentPath) {
+            return false;
+        }
+        return isValidRoute(parentPath, validPatterns);
+    };
+
+    const goBack = () => {
+        const parentPath = getParentPath(location.pathname);
+        if (parentPath && isValidRoute(parentPath, validPatterns)) {
+            reactRouterNavigate(parentPath);
+        }
+    };
+
     return (
         <NavigatorContext.Provider value={{
             route,
             navigate: navigateFunction,
+            canGoBack,
+            goBack,
         }}>
             <RouteComponent />
         </NavigatorContext.Provider>

package/src/context/types.ts

@@ -24,4 +24,16 @@ export type NavigatorProviderProps = {
 export type NavigatorContextValue = {
     route: NavigatorParam | undefined;
     navigate: (params: NavigateParams) => void;
+    /**
+     * Returns true if there is a parent route in the route hierarchy to navigate back to.
+     * On web, this checks for parent routes (not browser history).
+     * On native, this uses react-navigation's canGoBack().
+     */
+    canGoBack: () => boolean;
+    /**
+     * Navigate back to the parent route in the route hierarchy.
+     * On web, this navigates to the parent path (e.g., /users/123 -> /users).
+     * On native, this uses react-navigation's goBack().
+     */
+    goBack: () => void;
 };

package/src/examples/ExampleNavigationRouter.tsx

@@ -84,6 +84,66 @@ const SettingsNotFoundScreen = ({ path, params }: NotFoundComponentProps) => {
     );
 };
 
+/**
+ * FullScreen Example - demonstrates a screen that renders without parent layout
+ * This screen will NOT have the sidebar, header, or any parent navigator chrome
+ */
+const FullScreenExample = () => {
+    const { navigate } = useNavigator();
+
+    return (
+        <Screen>
+            <View
+                spacing="lg"
+                padding={12}
+                style={{
+                    flex: 1,
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    backgroundColor: '#1a1a2e',
+                }}
+            >
+                <Icon name="fullscreen" size={80} color="white" />
+                <Text size="xxl" weight="bold" style={{ color: 'white', marginTop: 24 }}>
+                    Full Screen Mode
+                </Text>
+                <Text size="md" style={{ color: '#aaa', textAlign: 'center', maxWidth: 400, marginTop: 8 }}>
+                    This screen renders outside of the parent layout. Notice there's no sidebar,
+                    header, or any navigation chrome from the parent navigator.
+                </Text>
+                <Card style={{ marginTop: 32, padding: 24, maxWidth: 500 }}>
+                    <View spacing="md">
+                        <Text size="lg" weight="semibold">How it works</Text>
+                        <Text size="sm" color="secondary">
+                            Add <Text weight="semibold">fullScreen: true</Text> to the screen's options:
+                        </Text>
+                        <View style={{ backgroundColor: '#f5f5f5', padding: 12, borderRadius: 8, marginTop: 8 }}>
+                            <Text size="sm" style={{ fontFamily: 'monospace' }}>
+                                {`{
+  path: "fullscreen-demo",
+  type: 'screen',
+  component: FullScreenExample,
+  options: { fullScreen: true }
+}`}
+                            </Text>
+                        </View>
+                        <Text size="sm" color="secondary" style={{ marginTop: 8 }}>
+                            Use cases: Onboarding flows, media viewers, immersive experiences, modal-like screens.
+                        </Text>
+                    </View>
+                </Card>
+                <Button
+                    style={{ marginTop: 32 }}
+                    intent="primary"
+                    onPress={() => navigate({ path: '/', replace: false })}
+                >
+                    Back to Home
+                </Button>
+            </View>
+        </Screen>
+    );
+};
+
 // Settings section screens
 const SettingsHomeScreen = () => (
     <Screen>
@@ -149,6 +209,8 @@ const SettingsNavigator: NavigatorParam = {
 };
 
 const HomeScreen = () => {
+    const { navigate } = useNavigator();
+
     return (
         <Screen>
             <View spacing='lg' padding={12}>
@@ -194,6 +256,25 @@ const HomeScreen = () => {
                         </Text>
                     </View>
                 </Card>
+
+                <Card>
+                    <View spacing="md" style={{ padding: 16 }}>
+                        <Text size="lg" weight="semibold">
+                            Full Screen Mode
+                        </Text>
+                        <Text>
+                            Screens can opt-out of parent layout inheritance using the fullScreen option.
+                            This is useful for onboarding flows, media viewers, or immersive experiences.
+                        </Text>
+                        <Button
+                            style={{ marginTop: 12 }}
+                            type="outlined"
+                            onPress={() => navigate({ path: '/fullscreen-demo' })}
+                        >
+                            Try Full Screen Demo
+                        </Button>
+                    </View>
+                </Card>
             </View>
         </Screen>
     )
@@ -211,6 +292,8 @@ const ExampleNavigationRouter: NavigatorParam = {
     },
     routes: [
         { path: "/", type: 'screen', component: HomeScreen, options: { title: "Home" } },
+        // FullScreen demo - renders without parent layout (no sidebar/header)
+        { path: "fullscreen-demo", type: 'screen', component: FullScreenExample, options: { title: "Full Screen Demo", fullScreen: true } },
         // Nested settings navigator with its own 404 handling
         SettingsNavigator,
         { path: "avatar", type: 'screen', component: AvatarExamples, options: { title: "Avatar" } },

package/src/index.web.ts

@@ -3,3 +3,9 @@ export * from './index';
 
 // Direct export to fix module resolution
 export { NavigatorProvider, useNavigator } from './context/NavigatorContext.web';
+
+// [DEVCONTAINER FIX] Explicit hook exports to fix Vite re-export resolution
+// When Vite processes `export * from './index'` -> `export * from './hooks'`,
+// it doesn't apply .web extension priority for nested re-exports.
+// This explicit export ensures useParams is available from @idealyst/navigation.
+export { useParams } from './hooks/useParams.web';

package/src/routing/router.native.tsx

@@ -213,12 +213,24 @@ const buildScreen = (params: RouteParam, Navigator: TypedNavigator, parentPath =
         component = buildNavigator(params, fullPath);
     }
 
+    // Build screen options, adding fullScreen presentation if specified
+    let screenOptions = params.options;
+    if (params.type === 'screen' && params.options?.fullScreen) {
+        screenOptions = {
+            ...params.options,
+            // Use fullScreenModal presentation to bypass parent navigator chrome
+            presentation: 'fullScreenModal',
+            // Hide header for true fullScreen experience
+            headerShown: params.options.headerShown ?? false,
+        } as ScreenOptions;
+    }
+
     return (
         <Navigator.Screen
             key={`${fullPath}-${index}`}
             name={fullPath}
             component={component}
-            options={params.options}
+            options={screenOptions}
         />
     )
 }

package/src/routing/router.web.tsx

@@ -2,7 +2,7 @@ import React, { useEffect, useState, useRef } from 'react'
 import { Routes, Route, useLocation, useParams } from '../router'
 import { DefaultStackLayout } from '../layouts/DefaultStackLayout'
 import { DefaultTabLayout } from '../layouts/DefaultTabLayout'
-import { NavigatorParam, RouteParam, NotFoundComponentProps } from './types'
+import { NavigatorParam, RouteParam, ScreenParam, NotFoundComponentProps } from './types'
 import { NavigateParams } from '../context/types'
 
 /**
@@ -98,30 +98,55 @@ const NotFoundWrapper = ({
 export const buildNavigator = (params: NavigatorParam, parentPath = '') => {
     return () => (
         <Routes>
-            {buildRoute(params, 0, false)}
+            {buildRoute(params, 0, false, parentPath)}
         </Routes>
     )
 }
 
 
+/**
+ * Helper to compute full path by joining parent and child paths
+ */
+const joinPaths = (parentPath: string, childPath: string): string => {
+    // Remove trailing slash from parent
+    const normalizedParent = parentPath.endsWith('/') ? parentPath.slice(0, -1) : parentPath;
+    // Remove leading slash from child
+    const normalizedChild = childPath.startsWith('/') ? childPath.slice(1) : childPath;
+
+    if (!normalizedParent || normalizedParent === '') {
+        return normalizedChild ? `/${normalizedChild}` : '/';
+    }
+    if (!normalizedChild || normalizedChild === '') {
+        return normalizedParent;
+    }
+    return `${normalizedParent}/${normalizedChild}`;
+};
+
+/**
+ * Check if a screen has fullScreen option enabled
+ */
+const isFullScreenRoute = (route: RouteParam): route is ScreenParam => {
+    return route.type === 'screen' && route.options?.fullScreen === true;
+};
+
 /**
  * Build Route - handles both screens and nested navigators
  * @param params Route configuration
  * @param index Route index for key generation
  * @param isNested Whether this is a nested route (should strip leading slash)
- * @returns React Router Route element
+ * @param parentPath Full parent path for computing fullScreen route paths
+ * @returns React Router Route element or array of elements
  */
-const buildRoute = (params: RouteParam, index: number, isNested = false) => {
+const buildRoute = (params: RouteParam, index: number, isNested = false, parentPath = ''): React.ReactNode => {
     // For nested routes, strip leading slash to make path relative
-    const routePath = isNested && params.path.startsWith('/') 
-        ? params.path.slice(1) 
+    const routePath = isNested && params.path.startsWith('/')
+        ? params.path.slice(1)
         : params.path;
-    
+
     if (params.type === 'screen') {
-        
         // If the route path is empty (root route in navigator), make it an index route
         const routeProps = routePath === '' ? { index: true } : { path: routePath };
-        
+
         return (
             <Route
                 key={`${params.path}-${index}`}
@@ -134,19 +159,28 @@ const buildRoute = (params: RouteParam, index: number, isNested = false) => {
         const LayoutComponent = params.layoutComponent ||
             (params.layout === 'tab' ? DefaultTabLayout : DefaultStackLayout);
 
-        // Transform routes to include full paths for layout component
-        const routesWithFullPaths = params.routes.map(route => ({
+        // Compute the full path for this navigator
+        const navigatorFullPath = joinPaths(parentPath, params.path);
+
+        // Separate fullScreen routes from regular routes
+        const regularRoutes = params.routes.filter(route => !isFullScreenRoute(route));
+        const fullScreenRoutes = params.routes.filter(isFullScreenRoute);
+
+        // Transform routes to include full paths for layout component (only non-fullScreen)
+        const routesWithFullPaths = regularRoutes.map(route => ({
             ...route,
             fullPath: route.path
         }));
 
-        // Build child routes including catch-all for 404
-        const childRoutes = params.routes.map((child, childIndex) => buildRoute(child, childIndex, true));
+        // Build child routes for regular (non-fullScreen) screens
+        const childRoutes = regularRoutes.map((child, childIndex) =>
+            buildRoute(child, childIndex, true, navigatorFullPath)
+        );
 
         // Add catch-all and index routes if notFoundComponent or onInvalidRoute is configured
         if (params.notFoundComponent || params.onInvalidRoute) {
             // Check if any route handles the index (empty path or "/" for this navigator)
-            const hasIndexRoute = params.routes.some(route => {
+            const hasIndexRoute = regularRoutes.some(route => {
                 const childPath = route.path.startsWith('/') ? route.path.slice(1) : route.path;
                 return childPath === '' || childPath === '/';
             });
@@ -183,7 +217,8 @@ const buildRoute = (params: RouteParam, index: number, isNested = false) => {
             );
         }
 
-        return (
+        // Build the main navigator route with layout
+        const navigatorRoute = (
             <Route
                 key={`${params.path}-${index}`}
                 path={routePath}
@@ -198,8 +233,36 @@ const buildRoute = (params: RouteParam, index: number, isNested = false) => {
                 {childRoutes}
             </Route>
         );
+
+        // If there are fullScreen routes, return them as siblings to the navigator route
+        if (fullScreenRoutes.length > 0) {
+            const fullScreenElements = fullScreenRoutes.map((route, fsIndex) => {
+                // Compute full absolute path for the fullScreen route
+                const fullPath = joinPaths(navigatorFullPath, route.path);
+                // Remove leading slash for React Router path (it will be relative to root)
+                const routerPath = fullPath.startsWith('/') ? fullPath.slice(1) : fullPath;
+
+                return (
+                    <Route
+                        key={`fullscreen-${route.path}-${fsIndex}`}
+                        path={routerPath || '/'}
+                        element={React.createElement(route.component)}
+                    />
+                );
+            });
+
+            // Return array of routes: navigator + fullScreen siblings
+            return (
+                <React.Fragment key={`navigator-group-${index}`}>
+                    {navigatorRoute}
+                    {fullScreenElements}
+                </React.Fragment>
+            );
+        }
+
+        return navigatorRoute;
     }
-    
+
     return null;
 }
 

package/src/routing/types.ts

@@ -61,6 +61,15 @@ export type ScreenOptions = {
      */
     title?: string;
     headerShown?: boolean;
+    /**
+     * When true, renders the screen outside of parent layout wrappers.
+     * Useful for fullscreen modals, onboarding flows, or any screen that
+     * should not inherit the parent navigator's layout (header, sidebar, tabs, etc.)
+     *
+     * Web: Screen renders as a sibling route without the parent LayoutComponent
+     * Native: Screen uses fullScreenModal presentation
+     */
+    fullScreen?: boolean;
 
 } & NavigatorOptions;