`\r\n\r\nRenders the matched child route content. Use inside `layout` components to produce nested UI.\r\n\r\n```tsx\r\nfunction AppLayout() {\r\n return (\r\n \r\n \r\n \r\n \r\n {/* child route content renders here */}\r\n \r\n
\r\n )\r\n}\n```\n\n`useOutlet()` and `Outlet()` return `null` at a leaf with no further outlet.\nThey return an element when a child layout or page is available, so nullable\nhandling is required in strict TypeScript consumers.\n\n### Hooks\n\r\n#### `useRouter()`\r\n\r\nReturns the full router context object.\r\n\r\n```ts\r\nconst router = useRouter()\r\n// router.mode — Router mode\r\n// router.base — Base path\r\n// router.location — Current location object\r\n// router.pathname — Path used for route matching (base-truncated)\r\n// router.params — Current route parameters\r\n// router.state — Current history state\r\n// router.navigate() — Navigate function\r\n// router.replace() — Replace navigation\r\n// router.back() — Go back\r\n// router.forward() — Go forward\r\n```\r\n\r\n#### `useNavigate()`\r\n\r\nReturns the navigate function.\r\n\r\n```ts\r\nconst navigate = useNavigate()\r\nnavigate('/dashboard')\r\nnavigate('/profile', { state: { from: 'home' }, replace: true })\r\nnavigate(-1) // go back\n```\n\nA leading `/` denotes a route path and applies `base` once. For example, with `base=\"/app\"`, `/about` resolves to `/app/about`; a route named `/app/details` resolves to `/app/app/details`. Relative paths resolve against the complete current location, including its directory slash and query. From `/app/items/?q=keep`, `next` resolves to `/app/items/next`, `?q=new` replaces the query, and `#detail` preserves `?q=keep`. Parent segments may leave the base; an out-of-base location renders `notFound`.\n\nURL objects and strings starting with a `://` protocol are complete addresses and do not receive another base prefix. History and hash require the same browser origin. Hash uses the address's pathname/query/fragment as its internal address. Memory accepts any origin and uses only those route fields. `useResolvePath` and Link hrefs use these same rules; hash and memory hrefs start with `#`.\n\n`router.setState(valueOrUpdater)` also accepts a function of the current state. History computes the value once and writes it to native history before committing the local state. If serialization fails, the error is propagated and the current state remains unchanged. Hash and memory update the state belonging to their current local entry.\n\r\n#### `useParams()`\r\n\r\nReturns matched route parameters as `Params = Record`. Repeated names, including repeated `*`, accumulate values in order. Parameters retain their URL encoding. Replacing a route tree clears captures that no longer belong to the matching route.\n\r\n```tsx\r\n// Route: /user/:userId/post/:postId\r\n// URL: /user/42/post/101\r\nconst { userId, postId } = useParams()\r\n// userId = '42', postId = '101'\n```\n\n```ts\nconst id = useParams().id\nconst firstId = Array.isArray(id) ? id[0] : id\n// /one/two/three matched by /:id/:id/:id gives ['one', 'two', 'three']\n```\n\r\n#### `useSearchParams()` / `useQuery()`\r\n\r\nReturns the URL search params as a `URLSearchParams` instance.\r\n\r\n```tsx\r\n// URL: /search?q=react&page=1\r\nconst searchParams = useSearchParams()\r\nsearchParams.get('q') // 'react'\r\nsearchParams.get('page') // '1'\r\n```\r\n\r\n#### `useRouteStack()`\r\n\r\nReturns the full matched route chain (from root to leaf).\r\n\r\n```ts\r\nconst stack = useRouteStack()\r\n// [rootRoute, userRoute, userIdRoute]\r\n```\r\n\r\n#### `useRouteLayoutStack()`\r\n\r\nReturns routes from the stack that have a `layout` (or the last route). Useful for building breadcrumbs or nested layout metadata.\r\n\r\n```ts\r\nconst layouts = useRouteLayoutStack()\r\n```\r\n\r\n#### `useRouteLayoutStackIndex()`\r\n\r\nReturns the current layout depth index.\r\n\r\n#### `useCurrentRoute()`\r\n\r\nReturns the currently active route item from the layout stack.\r\n\r\n#### `useResolvePath(to)`\r\n\r\nResolves a relative path against the current router context (accounting for `base` and `mode`).\r\n\r\n```ts\r\nconst resolvedPath = useResolvePath('../settings')\r\n```\r\n\r\n## Advanced Usage\r\n\r\n### Nested Routers\n\r\nYou can nest `` components. A child `Router` can detect and call the parent's update method to keep nested routing in sync.\n\nWhen parent and child routers use the same browser mode, a parent location or\nhistory state update refreshes an already mounted child from that mode's native\nlocation. The child keeps its own base and context; synchronization does not\nwrite another history entry or recreate the child. Memory routers remain\nisolated from browser routers and from other memory instances.\n\nStatic route keys containing Unicode characters or spaces are matched against\ntheir URL encoded form (for example, `中文` matches `%E4%B8%AD%E6%96%87`). The\nsame encoding rule applies to a Unicode or space-containing `base`; the public\n`base` value remains the configured text while matching uses its URL form.\n\n`Routes`, `RouterContext`, `RouteStack`, `RouteLayoutStackIndex` and `isStartWithProtocol` are also available from the package entry with TypeScript declarations. `Routes` accepts `entry` and optional `notFound` inside an existing router context; the Context exports support ordinary React Provider and `useContext` usage.\n\r\n### Custom Route Metadata\r\n\r\nExtend `RouteItem` with your own metadata using the generic type parameter:\r\n\r\n```tsx\r\nimport type { RouteItem } from '@canlooks/react-router'\r\n\r\ntype AppRoute = RouteItem<{\r\n icon?: string\r\n label?: string\r\n roles?: string[]\r\n}>\r\n\r\nconst routes: AppRoute = {\r\n label: 'Root',\r\n children: {\r\n 'admin': {\r\n label: 'Admin',\r\n roles: ['admin'],\r\n page: \r\n }\r\n }\r\n}\r\n\r\nfunction Breadcrumbs() {\r\n const stack = useRouteStack()\r\n return (\r\n \r\n )\r\n}\r\n```\r\n\r\n### Scroll Restoration\r\n\r\nIn history mode, `scrollRestore` selects the browser's `history.scrollRestoration` policy:\n\r\n```tsx\r\n// Let the browser restore scroll during history traversal (default)\nnavigate('/page', { scrollRestore: true })\r\n\r\n// Disable automatic browser scroll restoration\nnavigate('/page', { scrollRestore: false })\n```\n\nThis option does not call `scrollTo`; applications that require scrolling to the top on navigation should implement it explicitly. Hash and memory leave the browser's scroll restoration policy unchanged.\n\r\n### Not Found Handling\r\n\r\nProvide a `notFound` prop to the `Router` to render custom content when no route matches:\r\n\r\n```tsx\r\n} />\r\n```\r\n\r\nOr define a catch-all route as the last child:\r\n\r\n```tsx\r\nconst routes: RouteItem = {\r\n page: ,\r\n children: {\r\n 'about': { page: },\r\n '**': { page: }\r\n }\r\n}\r\n```\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md"}