@k8ordo/router 0.1.0 → 1.1.0

package/docs/llms.txt

@@ -17,17 +17,23 @@ When installed via npm, these docs live under `node_modules/@k8ordo/router/docs/
   wildcards, route groups, declaration order), mounting `<Router>` and
   `<Outlet>`, links without a `<Link>` component, `useMatch` for active
   sections, `Register` for checked patterns, what navigation guarantees
-  (`finished` after commit, scroll to top or fragment on a new page), and
-  how the framework reuses the navigation half.
+  (`finished` after commit, scroll to top or fragment on a new page), how
+  a `<ViewTransition>` animates page changes by the router's transition
+  types, and how the framework reuses the navigation half (an application on
+  `@k8ordo/framework` imports that half from `@k8ordo/framework`, which
+  re-exports it, with this package installed as its peer).
 
 ## Entry point
 
 - `@k8ordo/router` — `defineRoutes(record)` returns a table whose one operation
-  is `match(pathname)`; `<Router routes>` mounts it on the Navigation API and
+  is `match(pathname, accept?)` — a match `accept` declines is passed over and
+  the walk goes on to the next pattern, which is how the framework skips a
+  param a schema refused; `<Router routes>` mounts it on the Navigation API and
   `<Outlet />` renders the rest of the matched stack; a branch's `error`
-  component (`{ error, reset }` props, type `ErrorComponent`) renders in the
-  layout's hole when what is below throws, keyed by `NavigationGeneration`
-  so leaving the page clears it. `href(pattern, params?)`
+  component (props `ErrorProps`, `{ error, reset }`; type `ErrorComponent`)
+  renders in the layout's hole when what is below throws; the next
+  `NavigationGeneration` clears the failure without remounting what the
+  boundary wraps. `href(pattern, params?)`
   and `navigateTo(pattern, params?, options?)` build and perform navigations
   from the pattern **string** alone — no table import, so no cycle — with
   params inferred from the literal and the pattern itself checked once
@@ -35,20 +41,70 @@ When installed via npm, these docs live under `node_modules/@k8ordo/router/docs/
   typed params and throws if rendered under a different pattern; under the
   framework `Register` also carries `params` — the type each pattern's
   `paramsSchema` produces — so `href` takes a param as the page receives it
-  (`ParsedParams` / `ParsedParamsMap` / `ParamsSchemaFor` are the types the
-  generated code uses); `useRoute()`
-  is the untyped form. `RouteOf<typeof routes>` is the pathname union to feed
-  `@k8ordo/state`'s `Register`. `usePathname()` reads the platform's
+  (`ParsedParams` / `ParsedParamsMap` / `ParamsSchemaFor` / `ParamsOf` /
+  `ErrorComponent` are the types the generated code imports); `useRoute()`
+  is the untyped form.
+  `@k8ordo/state`'s `Register` takes the same `routes: typeof routes`;
+  `NavigablePath<typeof routes, Path>` is `Path` when a linkable pattern
+  matches it segment by segment (a `:param` takes one non-empty segment)
+  and `never` otherwise — a check of the path given, never a union of every
+  path, which a `/:locale` page would turn into `/${string}` — for any other
+  typed-path consumer. `usePathname()` reads the platform's
   pathname — never the search — so it works with or without a table, which
   makes it the location hook that also works under the framework;
-  `useMatch(pattern)` / `matchPath(pattern, pathname)` answer whether that
-  pattern — or, with a trailing `/*`, anything strictly below it — is the pathname
-  showing, with its params, table-free, so a sidebar can ask which section is
-  open under the framework too; `normalizePathname(pathname)` is the router's
-  own trailing-slash rule;
+  `useMatch(pattern, options?)` / `matchPath(pattern, pathname, options?)`
+  answer whether that pattern — or, with a trailing `/*`, anything strictly
+  below it — is the pathname showing, with its params, table-free, so a
+  sidebar can ask which section is open under the framework too, and
+  `{ inclusive: true }` on either counts a `/*` pattern's own index in;
+  `normalizePathname(pathname)` is the router's own trailing-slash rule;
+  under Vite's `base` (`import.meta.env.BASE_URL`, e.g. `/docs/`) `href` /
+  `navigateTo` put it in front of every link (so `href` returns a `string`
+  URL, not a table path) and `usePathname` / `<Router>` take it off, a URL
+  outside it being left to the browser — `withBase(pathname, base?)` /
+  `withoutBase(pathname, base?)` (`null` outside the base) are the two steps;
+  `usePendingPathname()` is where a page change in progress is going (`null`
+  when none is), for a pending indicator; a branch's `loading` component
+  shows while what is below it suspends (a `<Suspense>` inside its `error`
+  boundary); `bindParams(() => ({ locale }))` returns `{ href, navigateTo }` with those
+  params supplied by the source at each call (still overridable), for a
+  segment every link shares — a pattern that names a param still takes
+  `options` third, after an `undefined` params slot if the source supplies
+  them all. `PageProps<P>` / `LayoutProps<P>` type a framework route file's
+  props by its pattern (`PageProps`' `params` from the registered schemas,
+  `LayoutProps`' `params` always strings and its `P` only a pattern the table
+  has a page at; `request` when the generated `Register` says the mode has
+  one), and `RouteContext<P>` types a framework `route.ts` method export's
+  `{ request, params }`. `notFound()` says, from a framework page, that its pathname is not a
+  page after all — the framework answers with the nearest `not-found.tsx`
+  under a 404 — and `isNotFound(value)` recognises what it throws.
   `<PathnameProvider pathname>` seeds it for a server render and hydration,
-  and is mounted by `<Router>` and by both mode runtimes, never by an
-  application. `useInterceptedNavigation({claim, load, apply})` returns
+  and is mounted by `<Router>` and by the framework's runtime, never by an
+  application; `<BrowserPathname>` is the opposite seed — below it a server
+  render's `usePathname` (and `useMatch`) waits for the browser with
+  `use(browser())`, leaving the nearest `<Suspense>` to it — mounted by the
+  framework's runtime around a `fallback.tsx`, never by an application. Every page change renders in the background, outside any
+  pending async action (so awaiting `finished` inside one settles), tagged
+  `navigation` and `navigation-push` / `navigation-replace` /
+  `navigation-traverse` (`addTransitionType`), so a `<ViewTransition
+  update={{ navigation: 'auto', default: 'none' }}>` around the pages'
+  hole animates page changes and no other transition. `useInterceptedNavigation({claim, load, apply})` returns
   `{ generation }` and is the
   navigation primitive `<Router>` is built on, and the seam the framework
-  uses to render server-produced trees instead.
+  uses to render server-produced trees instead; its host renders what
+  `apply` set through `useDeferredValue`; its optional `refresh(url)` says
+  whether a same-pathname navigation still has to load (the page showing reads
+  the search), which then loads in place — no scroll, focus reset or
+  transition types.
+  Exported types, by group — the table: `Routes` (`{ kind, record, match }`),
+  `RoutesRecord`, `RouteNode`, `RouteComponent`, `Match`, `ErrorComponent`,
+  `ErrorProps`; patterns: `PatternOf`, `NavigablePatternOf`, `NavigablePath`,
+  `MatchablePattern`; registration: `Register`, `RegisteredPattern`,
+  `RegisteredNavigablePattern`, `RegisteredParams` (what a link takes),
+  `RegisteredPageParams` (what a page receives), `PageProps`, `LayoutProps`;
+  paths and schemas: `ParamsOf`, `PathFor`, `ParamValue`,
+  `StandardSchemaLike`, `SchemaOutput`, `ParamsSchemaFor`, `ParsedParams`,
+  `ParsedParamsMap`; options and handlers: `NavigateToOptions`
+  (`{ history? }`), `MatchOptions` (`{ inclusive? }`), `BoundParams` /
+  `BoundLinks` (what `bindParams`'s source returns / what it returns),
+  `NavigationHandler` (`{ claim, load, apply }`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k8ordo/router",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "The pathname axis of the URL, owned. One route table derives the types, the matching, the links, and the navigation, over the Navigation API and URLPattern.",
   "keywords": [
     "navigation-api",
@@ -40,22 +40,25 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "0.18.5",
-    "@types/react": "19.2.18",
-    "@vitejs/plugin-react": "6.0.5",
-    "@vitest/browser-playwright": "4.1.10",
-    "publint": "0.3.23",
-    "react": "19.2.8",
-    "react-dom": "19.2.8",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "@vitejs/plugin-react": "6.1.2",
+    "@vitest/browser-playwright": "5.0.5",
+    "playwright": "1.63.0",
+    "publint": "0.3.25",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
     "typescript": "7.0.2",
-    "vite": "8.2.1",
-    "vite-plus": "0.2.9",
-    "vitest": "4.1.10",
-    "vitest-browser-react": "2.2.0"
+    "vite": "npm:@voidzero-dev/vite-plus-core@1.3.0",
+    "vite-plus": "1.3.0",
+    "vitest": "5.0.5",
+    "vitest-browser-react": "2.3.0"
   },
   "peerDependencies": {
-    "@types/react": ">=19.2.18",
-    "react": ">=19.2.6",
-    "typescript": ">=7.0.2"
+    "@types/react": ">=19.3.0",
+    "react": ">=19.3.0",
+    "react-dom": ">=19.3.0",
+    "typescript": ">=7.0.0"
   },
   "peerDependenciesMeta": {
     "@types/react": {