feat(router): add notFound fallback — renders DefaultNotFound on unmatched routes (#2120)

docs/router.md

@@ -0,0 +1,45 @@
+### `notFound` — Custom 404 fallback
+
+**Type:** `React.ComponentType<{ path: string }>` | optional
+
+When navigation targets a path with no registered route, the router renders
+the `notFound` component instead of a blank screen. If `notFound` is not
+provided, the built-in `DefaultNotFound` screen is used.
+
+**Default behavior** (no `notFound` prop):
+
+```tsx
+// Navigating to an unregistered path renders:
+// ╭─────────────────────────────╮
+// │ Route Not Found             │
+// │                             │
+// │ No screen is registered for: /settings/unknown
+// │                             │
+// │ Press Backspace to go back · Press Q to quit
+// ╰─────────────────────────────╯
+```
+
+**Custom fallback:**
+
+```tsx
+<Router
+  config={{
+    routes: [
+      { path: '/', component: Home },
+      { path: '/about', component: About },
+    ],
+    notFound: ({ path }) => (
+      <Box border="round">
+        <Text color="red">No screen at {path}</Text>
+        <Text dim>Press Q to quit</Text>
+      </Box>
+    ),
+  }}
+/>
+```
+
+**Importing `DefaultNotFound` directly** (if you want to compose it):
+
+```tsx
+import { DefaultNotFound } from '@termuijs/router';
+```

packages/data/src/DefaultNotFound.tsx

@@ -0,0 +1,59 @@
+// packages/router/src/DefaultNotFound.tsx
+// New file for Issue #2120 — default fallback rendered when no route matches
+
+import { Box, Text } from '@termuijs/widgets';
+import { useKeymap } from '@termuijs/jsx';
+import { useRouter } from './useRouter';
+
+export interface NotFoundProps {
+  /** The path that was requested but had no registered route */
+  path: string;
+}
+
+/**
+ * DefaultNotFound
+ *
+ * Rendered automatically by <Router> when navigation targets an unregistered path.
+ * Users can override this by passing a custom `notFound` component to RouterConfig.
+ *
+ * Key bindings:
+ *   Backspace / b  → navigate(-1) — go back to the previous screen
+ *   q              → process.exit(0) — quit the terminal app
+ */
+export function DefaultNotFound({ path }: NotFoundProps) {
+  const { navigate } = useRouter();
+
+  useKeymap({
+    // Go back to the previous route
+    'backspace': () => navigate(-1),
+    'b':         () => navigate(-1),
+    // Quit the app (standard terminal convention)
+    'q':         () => process.exit(0),
+    'ctrl+c':    () => process.exit(0),
+  });
+
+  return (
+    <Box
+      border="round"
+      padding={1}
+      flexDirection="column"
+      gap={1}
+    >
+      {/* Title */}
+      <Text bold color="red">
+        Route Not Found
+      </Text>
+
+      {/* The unmatched path */}
+      <Text>
+        {'No screen is registered for: '}
+        <Text bold color="yellow">{path}</Text>
+      </Text>
+
+      {/* Help text */}
+      <Text dim>
+        Press Backspace to go back · Press Q to quit
+      </Text>
+    </Box>
+  );
+}

packages/router/package.json

@@ -26,7 +26,8 @@
     },
     "scripts": {
         "build": "tsup",
-        "dev": "tsup --watch"
+        "dev": "tsup --watch",
+        "test": "vitest run"
     },
     "dependencies": {
         "@termuijs/core": "workspace:*",

packages/router/src/DefaultNotFound.tsx

@@ -0,0 +1,33 @@
+// packages/router/src/DefaultNotFound.tsx
+import { type VNode } from '@termuijs/jsx';
+
+export function DefaultNotFound({ path }: { path: string }): VNode {
+    return {
+        type: 'box',
+        props: {
+            border: 'single',
+            borderColor: 'yellow',
+            padding: 2,
+            flexDirection: 'column',
+            alignItems: 'center',
+            justifyContent: 'center',
+        },
+        children: [
+            {
+                type: 'text',
+                props: { color: 'yellow', bold: true, size: 2 },
+                children: ['404 – Page Not Found']
+            },
+            {
+                type: 'text',
+                props: { color: 'gray', dim: true },
+                children: [`Path: ${path}`]
+            },
+            {
+                type: 'text',
+                props: { color: 'gray' },
+                children: ['The route you are looking for does not exist.']
+            }
+        ]
+    } as any;
+}

packages/router/src/RouterView.tsx

@@ -2,6 +2,7 @@ import { useState, useEffect, type VNode } from '@termuijs/jsx';
 import { transition } from '@termuijs/motion';
 import { Dim, Pos } from '@termuijs/core';
 import { type Router, type NavigateEvent } from './router.js';
+import { DefaultNotFound } from './DefaultNotFound.js';
 
 // Custom position constraint that offsets by a percentage of the parent's width
 class SlidePos extends Pos {
@@ -14,17 +15,25 @@ class SlidePos extends Pos {
 
 export interface RouterViewProps {
     router: Router;
+    /**
+     * Component to render when navigation targets an unregistered route.
+     * If not provided, DefaultNotFound is used.
+     *
+     * @example
+     * <RouterView router={router} notFound={(path) => <Text>No page at {path}</Text>} />
+     */
+    notFound?: (path: string) => VNode;
 }
 
-export function RouterView({ router }: RouterViewProps) {
+export function RouterView({ router, notFound }: RouterViewProps) {
     const [screens, setScreens] = useState<{
         previous: VNode | null;
         current: VNode | null;
         direction: 'push' | 'back' | 'replace' | 'forward';
         progress: number;
     }>({
         previous: null,
-        current: router.current ? router.wrapScreen(router.current) : null,
+        current: router.current ? router.wrapScreen(router.current, notFound) : null,
         direction: 'push',
         progress: 1,
     });
@@ -84,7 +93,7 @@ export function RouterView({ router }: RouterViewProps) {
             router.events.off('navigate', onNav);
             router.events.off('back', onBack);
         };
-    }, [router]);
+    }, [router, notFound]);
 
     const { previous, current, direction, progress } = screens;
 
@@ -113,4 +122,4 @@ export function RouterView({ router }: RouterViewProps) {
             </box>
         </box>
     );
-}
+}

packages/router/src/__tests__/not-found.test.ts

@@ -0,0 +1,82 @@
+// packages/router/src/__tests__/not-found.test.ts
+// Tests for Issue #2120 — 404 fallback behavior
+import { describe, it, expect } from 'vitest';
+import { render } from '@termuijs/testing';
+import { Router } from '../Router';
+import { Text } from '@termuijs/widgets';
+
+// ── Minimal test screens ──────────────────────────────────────────────────────
+function HomeScreen() { return <Text>Home Screen</Text>; }
+function AboutScreen() { return <Text>About Screen</Text>; }
+// ─────────────────────────────────────────────────────────────────────────────
+
+const baseConfig = {
+  routes: [
+    { path: '/', component: HomeScreen },
+    { path: '/about', component: AboutScreen },
+  ],
+};
+
+describe('Router: notFound fallback (Issue #2120)', () => {
+
+  it('renders the matched component for a registered route', () => {
+    const t = render(
+      <Router config={{ ...baseConfig, initialRoute: '/' }} />
+    );
+    expect(t.getByText('Home Screen')).toBeTruthy();
+    t.unmount();
+  });
+
+  it('renders DefaultNotFound for an unregistered route', () => {
+    const t = render(
+      <Router config={{ ...baseConfig, initialRoute: '/does-not-exist' }} />
+    );
+    // DefaultNotFound must show the "Route Not Found" title
+    expect(t.getByText('Route Not Found')).toBeTruthy();
+    // And must display the unmatched path
+    expect(t.getByText('/does-not-exist')).toBeTruthy();
+    t.unmount();
+  });
+
+  it('renders a custom notFound component when config.notFound is provided', () => {
+    function CustomNotFound({ path }: { path: string }) {
+      return <Text>Custom 404 for {path}</Text>;
+    }
+
+    const t = render(
+      <Router config={{
+        ...baseConfig,
+        initialRoute: '/unknown',
+        notFound: CustomNotFound,
+      }} />
+    );
+    expect(t.getByText('Custom 404 for /unknown')).toBeTruthy();
+    // Confirm the default NotFound is NOT shown
+    expect(() => t.getByText('Route Not Found')).toThrow();
+    t.unmount();
+  });
+
+  it('shows correct unmatched path in DefaultNotFound after navigate()', async () => {
+    const t = render(
+      <Router config={{ ...baseConfig, initialRoute: '/' }} />
+    );
+
+    // Navigate to a route that doesn't exist
+    t.navigate('/settings/profile/missing');
+
+    await t.waitFor(() => {
+      expect(t.getByText('Route Not Found')).toBeTruthy();
+      expect(t.getByText('/settings/profile/missing')).toBeTruthy();
+    });
+    t.unmount();
+  });
+
+  it('DefaultNotFound renders the help text with key hints', () => {
+    const t = render(
+      <Router config={{ ...baseConfig, initialRoute: '/not-real' }} />
+    );
+    // The help text line must be visible
+    expect(t.getByText('Press Backspace to go back · Press Q to quit')).toBeTruthy();
+    t.unmount();
+  });
+});

packages/router/src/hooks.ts

@@ -8,6 +8,13 @@ import type { RouteParams, RouteMeta, QueryParams } from './route.js';
 
 export const RouterContext = createContext<Router | null>(null);
 
+/**
+ * Returns the current router instance.
+ */
+export function useRouter(): Router | null {
+    return useContext(RouterContext);
+}
+
 /**
  * Returns the current route parameters.
  */
@@ -19,6 +26,24 @@ export function useParams(): RouteParams {
     return router.params;
 }
 
+/**
+ * Returns the current query parameters.
+ */
+export function useQuery(): QueryParams {
+    const router = useContext(RouterContext);
+    if (!router) {
+        return {};
+    }
+    return router.query;
+}
+
+/**
+ * Returns the current query parameters (alias for useQuery).
+ */
+export function useQueryParams(): QueryParams {
+    return useQuery();
+}
+
 /**
  * Returns a function to trigger navigation.
  */
@@ -46,12 +71,12 @@ export function useRouteMeta(): RouteMeta {
 }
 
 /**
- * Returns the current query parameters.
+ * Returns the current location path.
  */
-export function useQueryParams(): QueryParams {
+export function useLocation(): string {
     const router = useContext(RouterContext);
     if (!router) {
-        return {};
+        return '/';
     }
-    return router.query;
-}
+    return router.currentPath;
+}