@idealyst/navigation 1.0.96 → 1.0.98

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/navigation",
-  "version": "1.0.96",
+  "version": "1.0.98",
   "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.96",
-    "@idealyst/theme": "^1.0.96",
+    "@idealyst/components": "^1.0.98",
+    "@idealyst/theme": "^1.0.98",
     "@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.96",
+    "@idealyst/components": "^1.0.98",
     "@idealyst/datagrid": "^1.0.93",
     "@idealyst/datepicker": "^1.0.93",
-    "@idealyst/theme": "^1.0.96",
+    "@idealyst/theme": "^1.0.98",
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "react": "^19.1.0",

package/src/context/NavigatorContext.native.tsx

@@ -1,18 +1,93 @@
-import React, { createContext, memo, use, useContext, useMemo } from 'react';
+import React, { createContext, memo, useContext, useMemo } from 'react';
 import { NavigateParams, NavigatorProviderProps, NavigatorContextValue } from './types';
-import { useNavigation, useNavigationState, DarkTheme, DefaultTheme, NavigationContainer, useRoute } from '@react-navigation/native';
-import { buildNavigator } from '../routing';
+import { useNavigation, DarkTheme, DefaultTheme, NavigationContainer, CommonActions } from '@react-navigation/native';
+import { buildNavigator, NavigatorParam, NOT_FOUND_SCREEN_NAME } from '../routing';
 import { useUnistyles } from 'react-native-unistyles';
 
-const NavigatorContext = createContext<NavigatorContextValue>({
-    route: undefined,
-    navigate: () => {},
-});
+const NavigatorContext = createContext<NavigatorContextValue>(null!);
 
-const DrawerNavigatorContext = createContext<NavigatorContextValue>({
-    route: undefined,
-    navigate: () => {},
-});
+const DrawerNavigatorContext = createContext<NavigatorContextValue>(null!);
+
+/**
+ * Find the nearest invalid route handler by matching path prefixes and bubbling up.
+ * Returns the handler from the deepest matching navigator, or undefined if none found.
+ */
+function findInvalidRouteHandler(
+    route: NavigatorParam,
+    invalidPath: string
+): ((path: string) => NavigateParams | undefined) | undefined {
+    const pathSegments = invalidPath.split('/').filter(Boolean);
+
+    // Recursively search for handlers, collecting them from root to deepest match
+    function collectHandlers(
+        currentRoute: NavigatorParam,
+        segmentIndex: number,
+        prefix: string
+    ): Array<(path: string) => NavigateParams | undefined> {
+        const handlers: Array<(path: string) => NavigateParams | undefined> = [];
+
+        // Add this navigator's handler if it exists
+        if (currentRoute.onInvalidRoute) {
+            handlers.push(currentRoute.onInvalidRoute);
+        }
+
+        // Check if any child route matches the next segments
+        if (currentRoute.routes && segmentIndex < pathSegments.length) {
+            for (const childRoute of currentRoute.routes) {
+                if (childRoute.type !== 'navigator') continue;
+
+                const childSegments = childRoute.path.split('/').filter(Boolean);
+
+                // Check if child path matches the next path segments
+                let matches = true;
+                for (let i = 0; i < childSegments.length && segmentIndex + i < pathSegments.length; i++) {
+                    const childSeg = childSegments[i];
+                    const pathSeg = pathSegments[segmentIndex + i];
+
+                    if (!childSeg.startsWith(':') && childSeg !== pathSeg) {
+                        matches = false;
+                        break;
+                    }
+                }
+
+                if (matches && childSegments.length > 0) {
+                    // Recurse into matching child navigator
+                    const childPrefix = `${prefix}/${childRoute.path}`.replace(/\/+/g, '/');
+                    const childHandlers = collectHandlers(
+                        childRoute as NavigatorParam,
+                        segmentIndex + childSegments.length,
+                        childPrefix
+                    );
+                    handlers.push(...childHandlers);
+                }
+            }
+        }
+
+        return handlers;
+    }
+
+    const handlers = collectHandlers(route, 0, '');
+
+    // Return the deepest handler (last in the array)
+    return handlers.length > 0 ? handlers[handlers.length - 1] : undefined;
+}
+
+/**
+ * Check if any navigator in the tree has a notFoundComponent configured
+ */
+function hasNotFoundComponent(route: NavigatorParam): boolean {
+    if (route.notFoundComponent) return true;
+
+    if (route.routes) {
+        for (const child of route.routes) {
+            if (child.type === 'navigator' && hasNotFoundComponent(child as NavigatorParam)) {
+                return true;
+            }
+        }
+    }
+
+    return false;
+}
 
 // Utility function to parse path with parameters and find matching route
 const parseParameterizedPath = (path: string, rootRoute: any): { routeName: string, params: Record<string, string> } | null => {
@@ -84,15 +159,56 @@ const UnwrappedNavigatorProvider = ({ route }: NavigatorProviderProps) => {
 
     const navigation = useNavigation();
 
-    const navigate = (params: NavigateParams) => {
+    const navigate = (params: NavigateParams, _redirectCount = 0) => {
+        // Prevent infinite redirect loops
+        if (_redirectCount > 10) {
+            console.error('Navigation: Maximum redirect count exceeded. Check onInvalidRoute handlers.');
+            return;
+        }
+
         // Parse parameterized path for mobile
         const parsed = parseParameterizedPath(params.path, route);
-        if (parsed) {
+
+        if (!parsed) {
+            // Invalid route - try to find a handler
+            const handler = findInvalidRouteHandler(route, params.path);
+            if (handler) {
+                const redirectParams = handler(params.path);
+                if (redirectParams) {
+                    // Handler returned NavigateParams - redirect
+                    return navigate(
+                        { ...redirectParams, replace: true },
+                        _redirectCount + 1
+                    );
+                }
+                // Handler returned undefined - fall through to 404 screen
+            }
+
+            // Navigate to 404 screen if configured
+            if (route.notFoundComponent) {
+                navigation.navigate(NOT_FOUND_SCREEN_NAME as never, {
+                    path: params.path,
+                    params: params.vars
+                } as never);
+                return;
+            }
+
+            // No handler and no 404 screen - log warning
+            console.warn(`Navigation: Invalid route "${params.path}" and no handler or notFoundComponent configured.`);
+            return;
+        }
+
+        if (params.replace) {
+            // Use CommonActions.reset to replace the current route
+            navigation.dispatch(
+                CommonActions.reset({
+                    index: 0,
+                    routes: [{ name: parsed.routeName, params: parsed.params }],
+                })
+            );
+        } else {
             // Navigate to the pattern route with extracted parameters
             navigation.navigate(parsed.routeName as never, parsed.params as never);
-        } else {
-            // Fallback to direct navigation
-            navigation.navigate(params.path as never, params.vars as never);
         }
     };
 
@@ -125,14 +241,56 @@ const NavigatorProvider = ({ route }: NavigatorProviderProps) => {
 
 const DrawerNavigatorProvider = ({ navigation, route, children }: { navigation: any, route: any, children: React.ReactNode }) => {
 
-    const navigate = (params: NavigateParams) => {
+    const navigate = (params: NavigateParams, _redirectCount = 0) => {
+        // Prevent infinite redirect loops
+        if (_redirectCount > 10) {
+            console.error('Navigation: Maximum redirect count exceeded. Check onInvalidRoute handlers.');
+            return;
+        }
+
         // Parse parameterized path for mobile
         const parsed = parseParameterizedPath(params.path, route);
-        if (parsed) {
+
+        if (!parsed) {
+            // Invalid route - try to find a handler
+            const handler = findInvalidRouteHandler(route, params.path);
+            if (handler) {
+                const redirectParams = handler(params.path);
+                if (redirectParams) {
+                    // Handler returned NavigateParams - redirect
+                    return navigate(
+                        { ...redirectParams, replace: true },
+                        _redirectCount + 1
+                    );
+                }
+                // Handler returned undefined - fall through to 404 screen
+            }
+
+            // Navigate to 404 screen if configured
+            if (route.notFoundComponent) {
+                navigation.navigate(NOT_FOUND_SCREEN_NAME as never, {
+                    path: params.path,
+                    params: params.vars
+                } as never);
+                return;
+            }
+
+            // No handler and no 404 screen - log warning
+            console.warn(`Navigation: Invalid route "${params.path}" and no handler or notFoundComponent configured.`);
+            return;
+        }
+
+        if (params.replace) {
+            // Use CommonActions.reset to replace the current route
+            navigation.dispatch(
+                CommonActions.reset({
+                    index: 0,
+                    routes: [{ name: parsed.routeName, params: parsed.params }],
+                })
+            );
+        } else {
             // Navigate to the pattern route with extracted parameters
             navigation.navigate(parsed.routeName as never, parsed.params as never);
-        } else {
-            // Fallback to direct navigation
         }
     };
 

package/src/context/NavigatorContext.web.tsx

@@ -1,45 +1,224 @@
 import React, { createContext, memo, useContext, useMemo } from 'react';
 import { useNavigate, useParams } from '../router';
 import { NavigateParams, NavigatorProviderProps, NavigatorContextValue } from './types';
-import { buildNavigator } from '../routing';
+import { buildNavigator, NavigatorParam } from '../routing';
 
 const NavigatorContext = createContext<NavigatorContextValue>({
     navigate: () => {},
     route: undefined,
 });
 
+/**
+ * Normalize a path and substitute variables
+ */
+function normalizePath(path: string, vars?: Record<string, string>): string {
+    let normalizedPath = path;
+
+    // Convert empty string to '/'
+    if (normalizedPath === '' || normalizedPath === '/') {
+        normalizedPath = '/';
+    } else if (!normalizedPath.startsWith('/')) {
+        normalizedPath = `/${normalizedPath}`;
+    }
+
+    // Substitute variables in the path if provided
+    if (vars) {
+        Object.entries(vars).forEach(([key, value]) => {
+            normalizedPath = normalizedPath.replace(`:${key}`, value);
+        });
+    }
+
+    return normalizedPath;
+}
+
+/**
+ * Build a list of valid route patterns from the route tree
+ */
+function buildValidPatterns(route: NavigatorParam, prefix = ''): string[] {
+    const patterns: string[] = [];
+
+    if (!route.routes) return patterns;
+
+    for (const childRoute of route.routes) {
+        const childPath = childRoute.path.startsWith('/')
+            ? childRoute.path
+            : `${prefix}/${childRoute.path}`.replace(/\/+/g, '/');
+
+        // Add the pattern (keeping :param placeholders)
+        if (childPath) {
+            patterns.push(childPath === '' ? '/' : childPath);
+        }
+
+        // Recursively add nested routes
+        if (childRoute.type === 'navigator') {
+            patterns.push(...buildValidPatterns(childRoute as NavigatorParam, childPath));
+        }
+    }
+
+    // Also add the root pattern
+    if (prefix === '' || prefix === '/') {
+        patterns.push('/');
+    }
+
+    return patterns;
+}
+
+/**
+ * Check if a path matches any of the valid route patterns
+ */
+function isValidRoute(path: string, patterns: string[]): boolean {
+    const pathSegments = path.split('/').filter(Boolean);
+
+    for (const pattern of patterns) {
+        const patternSegments = pattern.split('/').filter(Boolean);
+
+        // Check for root path match
+        if (path === '/' && (pattern === '/' || pattern === '')) {
+            return true;
+        }
+
+        // Length must match
+        if (pathSegments.length !== patternSegments.length) {
+            continue;
+        }
+
+        let isMatch = true;
+        for (let i = 0; i < patternSegments.length; i++) {
+            const patternSeg = patternSegments[i];
+            const pathSeg = pathSegments[i];
+
+            // Parameter segments match anything
+            if (patternSeg.startsWith(':')) {
+                continue;
+            }
+
+            // Literal segments must match exactly
+            if (patternSeg !== pathSeg) {
+                isMatch = false;
+                break;
+            }
+        }
+
+        if (isMatch) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Find the nearest invalid route handler by matching path prefixes and bubbling up.
+ * Returns the handler from the deepest matching navigator, or undefined if none found.
+ */
+function findInvalidRouteHandler(
+    route: NavigatorParam,
+    invalidPath: string
+): ((path: string) => NavigateParams | undefined) | undefined {
+    const pathSegments = invalidPath.split('/').filter(Boolean);
+
+    // Recursively search for handlers, collecting them from root to deepest match
+    function collectHandlers(
+        currentRoute: NavigatorParam,
+        segmentIndex: number,
+        prefix: string
+    ): Array<(path: string) => NavigateParams | undefined> {
+        const handlers: Array<(path: string) => NavigateParams | undefined> = [];
+
+        // Add this navigator's handler if it exists
+        if (currentRoute.onInvalidRoute) {
+            handlers.push(currentRoute.onInvalidRoute);
+        }
+
+        // Check if any child route matches the next segments
+        if (currentRoute.routes && segmentIndex < pathSegments.length) {
+            for (const childRoute of currentRoute.routes) {
+                if (childRoute.type !== 'navigator') continue;
+
+                const childSegments = childRoute.path.split('/').filter(Boolean);
+
+                // Check if child path matches the next path segments
+                let matches = true;
+                for (let i = 0; i < childSegments.length && segmentIndex + i < pathSegments.length; i++) {
+                    const childSeg = childSegments[i];
+                    const pathSeg = pathSegments[segmentIndex + i];
+
+                    if (!childSeg.startsWith(':') && childSeg !== pathSeg) {
+                        matches = false;
+                        break;
+                    }
+                }
+
+                if (matches && childSegments.length > 0) {
+                    // Recurse into matching child navigator
+                    const childPrefix = `${prefix}/${childRoute.path}`.replace(/\/+/g, '/');
+                    const childHandlers = collectHandlers(
+                        childRoute as NavigatorParam,
+                        segmentIndex + childSegments.length,
+                        childPrefix
+                    );
+                    handlers.push(...childHandlers);
+                }
+            }
+        }
+
+        return handlers;
+    }
+
+    const handlers = collectHandlers(route, 0, '');
+
+    // Return the deepest handler (last in the array)
+    return handlers.length > 0 ? handlers[handlers.length - 1] : undefined;
+}
+
 export const NavigatorProvider = ({
     route,
 }: NavigatorProviderProps) => {
-    const reactRouterNavigate = useNavigate()
-    
-    const navigateFunction = (params: NavigateParams) => {
+    const reactRouterNavigate = useNavigate();
+
+    // Memoize the list of valid route patterns
+    const validPatterns = useMemo(() => buildValidPatterns(route), [route]);
+
+    const navigateFunction = (params: NavigateParams, _redirectCount = 0) => {
+        // Prevent infinite redirect loops
+        if (_redirectCount > 10) {
+            console.error('Navigation: Maximum redirect count exceeded. Check onInvalidRoute handlers.');
+            return;
+        }
+
         if (params.path) {
-            // Normalize path - convert empty string to '/'
-            let path = params.path
-            if (path === '' || path === '/') {
-                path = '/'
-            } else if (!path.startsWith('/')) {
-                path = `/${path}`
-            }
-            
-            // Substitute variables in the path if provided
-            if (params.vars) {
-                Object.entries(params.vars).forEach(([key, value]) => {
-                    path = path.replace(`:${key}`, value);
-                });
+            const path = normalizePath(params.path, params.vars);
+
+            // Check if route is valid
+            if (!isValidRoute(path, validPatterns)) {
+                // Try to find a handler for the invalid route
+                const handler = findInvalidRouteHandler(route, path);
+                if (handler) {
+                    const redirectParams = handler(path);
+                    if (redirectParams) {
+                        // Handler returned NavigateParams - redirect
+                        return navigateFunction(
+                            { ...redirectParams, replace: true },
+                            _redirectCount + 1
+                        );
+                    }
+                    // Handler returned undefined - let React Router show 404 via catch-all
+                }
+                // No handler or handler returned undefined
+                // Navigate anyway - React Router's catch-all will show notFoundComponent
+                // If no notFoundComponent configured, React Router will render nothing
             }
-            
-            // Use React Router's navigate function
-            reactRouterNavigate(path);
+
+            // Use React Router's navigate function with replace option
+            reactRouterNavigate(path, { replace: params.replace });
         }
     };
-    
+
     const RouteComponent = useMemo(() => {
         // Memoize the router to prevent unnecessary re-renders
         return memo(buildNavigator(route));
     }, [route]);
-    
+
     return (
         <NavigatorContext.Provider value={{
             route,

package/src/context/types.ts

@@ -6,6 +6,11 @@ import { NavigatorParam } from "../routing";
 export type NavigateParams = {
     path: string;
     vars?: Record<string, string>;
+    /**
+     * If true, replaces the current history entry instead of pushing a new one.
+     * On web, this uses history.replace(). On native, this resets the navigation state.
+     */
+    replace?: boolean;
 };
 
 export type NavigatorProviderProps = {

package/src/examples/ExampleNavigationRouter.tsx

@@ -2,11 +2,151 @@ import React from 'react';
 import { AvatarExamples, BadgeExamples, ButtonExamples, CardExamples, CheckboxExamples, DialogExamples, DividerExamples, IconExamples, InputExamples, LinkExamples, PopoverExamples, ScreenExamples, SelectExamples, SliderExamples, SVGImageExamples, TextExamples, ViewExamples, ThemeExtensionExamples, SwitchExamples, RadioButtonExamples, ProgressExamples, TextAreaExamples, TabBarExamples, TooltipExamples, AccordionExamples, ListExamples, TableExamples, MenuExamples, ImageExamples, VideoExamples, AlertExamples, SkeletonExamples, ChipExamples, BreadcrumbExamples } from '@idealyst/components/examples';
 import { DataGridShowcase } from '@idealyst/datagrid/examples';
 import { DatePickerExamples } from '@idealyst/datepicker/examples';
-import { Text, View, Card, Screen } from '@idealyst/components';
-import { NavigatorParam, RouteParam } from '../routing';
+import { Text, View, Card, Screen, Icon, Button } from '@idealyst/components';
+import { NavigatorParam, RouteParam, NotFoundComponentProps } from '../routing';
 import { ExampleWebLayout } from './ExampleWebLayout';
 import ExampleSidebar from './ExampleSidebar';
 import HeaderRight from './HeaderRight';
+import { useNavigator } from '../context';
+
+/**
+ * Global 404 Not Found screen - shown for invalid routes at the root level
+ */
+const NotFoundScreen = ({ path, params }: NotFoundComponentProps) => {
+    const { navigate } = useNavigator();
+
+    return (
+        <Screen>
+            <View spacing='lg' padding={12} style={{ alignItems: 'center', justifyContent: 'center', flex: 1 }}>
+                <Icon name="alert-circle-outline" size={64} color="red" />
+                <Text size="xl" weight="bold">
+                    Page Not Found
+                </Text>
+                <Text size="md" color="secondary">
+                    The page you're looking for doesn't exist.
+                </Text>
+                <Card style={{ marginTop: 16, padding: 16 }}>
+                    <View spacing="sm">
+                        <Text size="sm" weight="semibold">Attempted path:</Text>
+                        <Text size="sm" color="secondary">{path}</Text>
+                        {params && Object.keys(params).length > 0 && (
+                            <>
+                                <Text size="sm" weight="semibold" style={{ marginTop: 8 }}>Params:</Text>
+                                <Text size="sm" color="secondary">{JSON.stringify(params, null, 2)}</Text>
+                            </>
+                        )}
+                    </View>
+                </Card>
+                <Button
+                    style={{ marginTop: 24 }}
+                    onPress={() => navigate({ path: '/', replace: true })}
+                >
+                    Go Home
+                </Button>
+            </View>
+        </Screen>
+    );
+};
+
+/**
+ * Settings-specific 404 screen - a simpler, more minimal style
+ */
+const SettingsNotFoundScreen = ({ path, params }: NotFoundComponentProps) => {
+    const { navigate } = useNavigator();
+
+    return (
+        <Screen>
+            <View spacing='md' padding={12} style={{ alignItems: 'center', justifyContent: 'center', flex: 1, backgroundColor: '#f5f5f5' }}>
+                <Icon name="cog-off-outline" size={48} color="orange" />
+                <Text size="lg" weight="semibold">
+                    Settings Page Not Found
+                </Text>
+                <Text size="sm" color="secondary" style={{ textAlign: 'center', maxWidth: 300 }}>
+                    The settings page "{path}" doesn't exist. You've been redirected here.
+                </Text>
+                <View direction="row" spacing="md" style={{ marginTop: 16 }}>
+                    <Button
+                        type="outlined"
+                        size="sm"
+                        onPress={() => navigate({ path: '/settings', replace: true })}
+                    >
+                        Settings Home
+                    </Button>
+                    <Button
+                        size="sm"
+                        onPress={() => navigate({ path: '/', replace: true })}
+                    >
+                        Go Home
+                    </Button>
+                </View>
+            </View>
+        </Screen>
+    );
+};
+
+// Settings section screens
+const SettingsHomeScreen = () => (
+    <Screen>
+        <View spacing='lg' padding={12}>
+            <Text size="xl" weight="bold">Settings</Text>
+            <Text size="md" color="secondary">Manage your application settings</Text>
+            <Card style={{ marginTop: 16, padding: 16 }}>
+                <View spacing="sm">
+                    <Text size="sm">Navigate to:</Text>
+                    <Text size="sm" color="secondary">• /settings/general - General settings</Text>
+                    <Text size="sm" color="secondary">• /settings/account - Account settings</Text>
+                    <Text size="sm" color="secondary">• /settings/invalid - Test 404 (will show SettingsNotFoundScreen)</Text>
+                    <Text size="sm" color="secondary">• /settings/redirect-me - Test redirect handler</Text>
+                </View>
+            </Card>
+        </View>
+    </Screen>
+);
+
+const GeneralSettingsScreen = () => (
+    <Screen>
+        <View spacing='lg' padding={12}>
+            <Text size="xl" weight="bold">General Settings</Text>
+            <Text size="md" color="secondary">Configure general app preferences</Text>
+        </View>
+    </Screen>
+);
+
+const AccountSettingsScreen = () => (
+    <Screen>
+        <View spacing='lg' padding={12}>
+            <Text size="xl" weight="bold">Account Settings</Text>
+            <Text size="md" color="secondary">Manage your account</Text>
+        </View>
+    </Screen>
+);
+
+/**
+ * Nested Settings Navigator with its own error handling:
+ * - onInvalidRoute: Redirects /settings/redirect-* to /settings/general
+ * - notFoundComponent: Shows SettingsNotFoundScreen for other invalid routes
+ */
+const SettingsNavigator: NavigatorParam = {
+    path: "settings",
+    type: 'navigator',
+    layout: 'stack',
+    notFoundComponent: SettingsNotFoundScreen,
+    onInvalidRoute: (invalidPath) => {
+        // Example: Redirect old/deprecated paths to the general settings
+        if (invalidPath.includes('redirect')) {
+            console.log(`[Settings] Redirecting "${invalidPath}" to /settings/general`);
+            return { path: '/settings/general', replace: true };
+        }
+        // Return undefined to show the notFoundComponent instead
+        console.log(`[Settings] Showing 404 for "${invalidPath}"`);
+        return undefined;
+    },
+    routes: [
+        { path: "", type: 'screen', component: SettingsHomeScreen, options: { title: "Settings" } },
+        { path: "general", type: 'screen', component: GeneralSettingsScreen, options: { title: "General" } },
+        { path: "account", type: 'screen', component: AccountSettingsScreen, options: { title: "Account" } },
+    ],
+};
 
 const HomeScreen = () => {
     return (
@@ -65,11 +205,14 @@ const ExampleNavigationRouter: NavigatorParam = {
     layout: 'drawer',
     sidebarComponent: ExampleSidebar,
     layoutComponent: ExampleWebLayout,
+    notFoundComponent: NotFoundScreen,
     options: {
         headerRight: HeaderRight,
     },
     routes: [
         { path: "/", type: 'screen', component: HomeScreen, options: { title: "Home" } },
+        // Nested settings navigator with its own 404 handling
+        SettingsNavigator,
         { path: "avatar", type: 'screen', component: AvatarExamples, options: { title: "Avatar" } },
         { path: "badge", type: 'screen', component: BadgeExamples, options: { title: "Badge" } },
         { path: "button", type: 'screen', component: ButtonExamples, options: { title: "Button" } },

package/src/routing/router.native.tsx

@@ -1,4 +1,4 @@
-import { NavigatorParam, RouteParam, ScreenOptions } from './types'
+import { NavigatorParam, RouteParam, ScreenOptions, NotFoundComponentProps } from './types'
 
 import { TypedNavigator } from "@react-navigation/native";
 import { createNativeStackNavigator } from "@react-navigation/native-stack";
@@ -75,6 +75,24 @@ const createThemeAwareComponent = (OriginalComponent: React.ComponentType<any>)
     return Wrapped;
 };
 
+/**
+ * Internal screen name for 404 pages
+ */
+export const NOT_FOUND_SCREEN_NAME = '__notFound__';
+
+/**
+ * Creates a NotFound screen component that receives path and params from route params
+ */
+const createNotFoundScreen = (NotFoundComponent: React.ComponentType<NotFoundComponentProps>) => {
+    return React.memo((props: any) => {
+        const { route } = props;
+        const path = route?.params?.path ?? '';
+        const params = route?.params?.params;
+
+        return <NotFoundComponent path={path} params={params} />;
+    });
+};
+
 /**
  * Build the Mobile navigator using React Navigation
  * @param params
@@ -104,6 +122,26 @@ export const buildNavigator = (params: NavigatorParam, parentPath = '') => {
         }
         : params.options;
 
+    // Build screens including optional 404 screen
+    const buildScreens = () => {
+        const screens = params.routes.map((child, index) => buildScreen(child, NavigatorType, parentPath, index));
+
+        // Add 404 screen if notFoundComponent is configured
+        if (params.notFoundComponent) {
+            const NotFoundScreen = createNotFoundScreen(params.notFoundComponent);
+            screens.push(
+                <NavigatorType.Screen
+                    key={NOT_FOUND_SCREEN_NAME}
+                    name={NOT_FOUND_SCREEN_NAME}
+                    component={NotFoundScreen}
+                    options={{ headerShown: false }}
+                />
+            );
+        }
+
+        return screens;
+    };
+
     // Special handling for drawer navigator with custom sidebar
     if (params.layout === 'drawer' && params.sidebarComponent) {
         return () => (
@@ -117,14 +155,14 @@ export const buildNavigator = (params: NavigatorParam, parentPath = '') => {
                     />
                 )}
             >
-                {params.routes.map((child, index) => buildScreen(child, NavigatorType, parentPath, index))}
+                {buildScreens()}
             </NavigatorType.Navigator>
         );
     }
 
     return () => (
         <NavigatorType.Navigator screenOptions={screenOptions}>
-            {params.routes.map((child, index) => buildScreen(child, NavigatorType, parentPath, index))}
+            {buildScreens()}
         </NavigatorType.Navigator>
     )
 }

package/src/routing/router.web.tsx

@@ -1,8 +1,93 @@
-import React from 'react'
-import { Routes, Route } from '../router'
+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 } from './types'
+import { NavigatorParam, RouteParam, NotFoundComponentProps } from './types'
+import { NavigateParams } from '../context/types'
+
+/**
+ * Wrapper component for catch-all routes that:
+ * 1. Checks onInvalidRoute handler first
+ * 2. If handler returns NavigateParams, redirects (using absolute path)
+ * 3. If handler returns undefined or no handler, renders notFoundComponent (if provided)
+ */
+const NotFoundWrapper = ({
+    component: Component,
+    onInvalidRoute
+}: {
+    component?: React.ComponentType<NotFoundComponentProps>
+    onInvalidRoute?: (path: string) => NavigateParams | undefined
+}) => {
+    const location = useLocation()
+    const params = useParams()
+    const [shouldRender, setShouldRender] = useState(false)
+    const redirectingRef = useRef(false)
+    const lastPathRef = useRef(location.pathname)
+
+    useEffect(() => {
+        // Reset state if path changed (navigated to a different invalid route)
+        if (lastPathRef.current !== location.pathname) {
+            lastPathRef.current = location.pathname
+            redirectingRef.current = false
+            setShouldRender(false)
+        }
+
+        // Prevent multiple redirects
+        if (redirectingRef.current) {
+            return
+        }
+
+        // Check if handler wants to redirect
+        if (onInvalidRoute) {
+            const redirectParams = onInvalidRoute(location.pathname)
+            if (redirectParams) {
+                // Mark as redirecting to prevent loops
+                redirectingRef.current = true
+
+                // Handler returned NavigateParams - redirect using absolute path
+                // Ensure path starts with / for absolute navigation
+                let targetPath = redirectParams.path
+                if (!targetPath.startsWith('/')) {
+                    targetPath = `/${targetPath}`
+                }
+
+                // Substitute any vars in the path
+                if (redirectParams.vars) {
+                    Object.entries(redirectParams.vars).forEach(([key, value]) => {
+                        targetPath = targetPath.replace(`:${key}`, value)
+                    })
+                }
+
+                // Use window.history for truly absolute navigation
+                // React Router's navigate can have issues in catch-all contexts
+                const replaceMode = redirectParams.replace ?? true
+                if (replaceMode) {
+                    window.history.replaceState(null, '', targetPath)
+                } else {
+                    window.history.pushState(null, '', targetPath)
+                }
+                // Trigger React Router to sync with the new URL
+                window.dispatchEvent(new PopStateEvent('popstate'))
+                return
+            }
+        }
+        // No redirect - show the 404 component (if provided)
+        setShouldRender(true)
+    }, [location.pathname, onInvalidRoute])
+
+    // Don't render until we've checked the handler
+    if (!shouldRender) {
+        return null
+    }
+
+    // If no component provided, render nothing (handler-only mode)
+    if (!Component) {
+        console.warn(`[Navigation] Invalid route "${location.pathname}" - no notFoundComponent configured and onInvalidRoute returned undefined`)
+        return null
+    }
+
+    return <Component path={location.pathname} params={params as Record<string, string>} />
+}
 
 /**
  * Build the Web navigator using React Router v7 nested routes
@@ -46,18 +131,37 @@ const buildRoute = (params: RouteParam, index: number, isNested = false) => {
         );
     } else if (params.type === 'navigator') {
         // Get the layout component directly
-        const LayoutComponent = params.layoutComponent || 
+        const LayoutComponent = params.layoutComponent ||
             (params.layout === 'tab' ? DefaultTabLayout : DefaultStackLayout);
-        
+
         // Transform routes to include full paths for layout component
         const routesWithFullPaths = params.routes.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));
+
+        // Add catch-all route if notFoundComponent or onInvalidRoute is configured
+        if (params.notFoundComponent || params.onInvalidRoute) {
+            childRoutes.push(
+                <Route
+                    key="__notFound__"
+                    path="*"
+                    element={
+                        <NotFoundWrapper
+                            component={params.notFoundComponent}
+                            onInvalidRoute={params.onInvalidRoute}
+                        />
+                    }
+                />
+            );
+        }
+
         return (
-            <Route 
-                key={`${params.path}-${index}`} 
+            <Route
+                key={`${params.path}-${index}`}
                 path={routePath}
                 element={
                     <LayoutComponent
@@ -67,7 +171,7 @@ const buildRoute = (params: RouteParam, index: number, isNested = false) => {
                     />
                 }
             >
-                {params.routes.map((child, childIndex) => buildRoute(child, childIndex, true))}
+                {childRoutes}
             </Route>
         );
     }

package/src/routing/types.ts

@@ -1,4 +1,5 @@
 import React from "react";
+import type { NavigateParams } from "../context/types";
 
 /**
  * Tab bar specific screen options
@@ -64,10 +65,37 @@ export type ScreenOptions = {
 } & NavigatorOptions;
 
 
+/**
+ * Props passed to the notFoundComponent when an invalid route is accessed
+ */
+export type NotFoundComponentProps = {
+    /** The full path that was attempted */
+    path: string
+    /** Any route parameters that were parsed from the path */
+    params?: Record<string, string>
+}
+
 export type BaseNavigatorParam = {
     path: string
     type: 'navigator'
     options?: NavigatorOptions
+    /**
+     * Handler called when an invalid route is accessed.
+     * - Return NavigateParams to redirect to a different route
+     * - Return undefined to show the notFoundComponent (if set)
+     * If not defined, bubbles up to parent navigator.
+     *
+     * @param invalidPath - The path that was attempted but not found
+     * @returns NavigateParams to redirect, or undefined to use notFoundComponent
+     */
+    onInvalidRoute?: (invalidPath: string) => NavigateParams | undefined
+    /**
+     * Component to render/navigate to when route is invalid and onInvalidRoute returns undefined.
+     * - Web: Renders at the current URL via catch-all route
+     * - Native: Navigated to as a screen
+     * - Optional: If not set and nothing handles the route, a warning is logged
+     */
+    notFoundComponent?: React.ComponentType<NotFoundComponentProps>
 }
 
 export type TabNavigatorParam = {