@mindees/router 0.12.0 → 0.14.0

package/README.md

@@ -6,15 +6,17 @@ Zod / Valibot / ArkType schema), and **fine-grained reactive route state** with
 selector-based re-render isolation. A modern, type-safe alternative to Expo
 Router and React Router for TypeScript cross-platform apps.
 
-> **Status: 🧪 Experimental (Phase 6 — Router I + Phase 7 — Router II).** The
+> **Status: 🧪 Experimental (pre-1.0).** The
 > typed routing core (typed params, Standard Schema search validation, the
 > signals-native router, typed + relative navigation, dynamic reconfiguration,
 > memory + browser history), **render integration** (`createRouterView` —
-> fine-grained, layout-preserving nested rendering; typed `createLink`), and
-> **data/guards/transitions** (SWR loaders + `preload`/`invalidate`, navigation
-> guards, web view transitions) are implemented and tested. The global typed
-> route registry and file-based route scanning are a later phase — see
-> [ROADMAP](../../ROADMAP.md).
+> fine-grained, layout-preserving nested rendering; typed `createLink`; bound
+> `Link` + `useRouter`/`useParams`/`useSearch`/`usePathname` hooks),
+> **data/guards/transitions** (SWR loaders + `preload`/`invalidate`,
+> auto-prefetch links, navigation guards, web view transitions), and
+> **file-based routing** (`createFileRouter` / `routesFromModules` — Expo-style
+> conventions, no hand-written route config) are implemented and tested. The
+> global typed route registry is a later phase — see [ROADMAP](../../ROADMAP.md).
 
 ## Install
 
@@ -30,6 +32,8 @@ pnpm add @mindees/router
 | Typed **search** params | ✅ via Standard Schema | ❌ not typed | ❌ raw `URLSearchParams` |
 | Validation lock-in | ✅ none — any Standard Schema (Zod/Valibot/ArkType) | — | — |
 | Reactivity | ✅ fine-grained signals; select a slice, re-run on *that* change | ⚠️ global-vs-local re-render footgun | React renders |
+| File-based routing | ✅ `createFileRouter` (Expo-style conventions) **or** explicit config | ✅ filesystem-only | ⚠️ optional plugin |
+| Auto-prefetch links | ✅ `<Link>` warms loaders on intent (hover / press-in / focus) | ❌ manual `router.prefetch` only | ⚠️ manual |
 | Build/dev-server required for types | ❌ pure TypeScript inference | ✅ dev server | ✅ typegen step |
 
 Relative navigation (`navigate('./edit')`, `'../'`) and `#fragment` targets are
@@ -132,6 +136,45 @@ type D = PathParams<'/about'>                // {}
 
 No generated `.d.ts`, no dev server, no stale type files — just TypeScript.
 
+## File-based routing (Expo-style conventions)
+
+Prefer filesystem conventions to an explicit config? `createFileRouter` turns a
+module map into a router using the same conventions Expo Router uses — feeding
+Quantum's better core (validated/typed params, loaders, re-render isolation):
+
+```ts
+import { createFileRouter, createBrowserHistory } from '@mindees/router'
+
+// web (Vite): a glob; native: a generated table — either way, no hand-written config
+const modules = import.meta.glob('./app/**/*.tsx', { eager: true })
+const router = createFileRouter(modules, { history: createBrowserHistory() })
+```
+
+Conventions (file path → route): `index` → the directory's path · `[param]` →
+`:param` · `[...rest]` → catch-all (`:rest*`) · `(group)` → a layout group that
+doesn't affect the URL · `_layout` → a layout that wraps the directory (renders
+its outlet) · `+not-found` → the fallback route. Each module's `default` export is
+the screen; named exports (`loader`, `loaderDeps`, `searchSchema`, `staleTime`,
+`meta`) configure the route. `routesFromModules` returns the route table directly
+if you'd rather build the router yourself.
+
+## Hooks + a bound `<Link>`
+
+Resolve the active router without prop-drilling — the familiar Expo Router surface
+on Quantum's fine-grained, validated core. The hooks return reactive **accessors**
+(call them inside JSX/effects), so reads stay fine-grained:
+
+```ts
+import { Link, useRouter, useParams, useSearch, usePathname } from '@mindees/router'
+
+const router = useRouter()        // throws if no router has been created
+const params = useParams()        // () => Record<string, string>
+const search = useSearch()        // () => validated search params
+const pathname = usePathname()    // () => string, re-render isolated
+
+Link({ to: '/posts/:id', params: { id: '42' }, children: 'Open' })
+```
+
 ## Data, guards & transitions
 
 ```ts
@@ -168,10 +211,12 @@ transparent no-op outside a DOM (SSR / native).
 ## API surface
 
 - **Render (Router II)** — `createRouterView`, `createLink`, `RouterViewOptions`,
-  `LinkProps`, `LinkComponent`, `LinkOptions`, `RouteComponentProps`.
+  `LinkProps`, `LinkComponent`, `LinkOptions`, `PrefetchMode`, `RouteComponentProps`.
+- **File-based routing** — `createFileRouter`, `routesFromModules`, `RouteModule`.
+- **Hooks** — `useRouter`, `useParams`, `useSearch`, `usePathname`, bound `Link`.
 - **Data / guards / transitions** — route `loader` / `loaderDeps` / `staleTime`,
   `router.loaderData` / `invalidate` / `preload`, `LoaderContext`, `LoaderData`,
-  `LoaderFn`, `LoaderStatus`; `BeforeNavigate`, `NavigateOptions` (`force`,
+  `LoaderDepsFn`, `LoaderFn`, `LoaderStatus`; `BeforeNavigate`, `NavigateOptions` (`force`,
   `viewTransition`), `CreateRouterOptions` (`beforeNavigate`, `viewTransitions`).
 - **Router** — `createRouter`, `Router`, `RouteRecord` (with `children` for
   nesting), `RouteMatch`, `RouterState` (with `matches` chain), `NavTarget`,

package/dist/index.d.ts

@@ -14,7 +14,7 @@ import { Maturity, NotImplementedError, PackageInfo, notImplemented } from "@min
 /** The npm package name. */
 declare const name = "@mindees/router";
 /** The package version. All `@mindees/*` packages share one locked version line. */
-declare const VERSION = "0.12.0";
+declare const VERSION = "0.14.0";
 /**
  * Current maturity. Router I (typed params, Standard-Schema search, history, the
  * signals-native router, selector-isolated state, typed + relative navigation)

package/dist/index.js

@@ -11,7 +11,7 @@ import { NotImplementedError, notImplemented } from "@mindees/core";
 /** The npm package name. */
 const name = "@mindees/router";
 /** The package version. All `@mindees/*` packages share one locked version line. */
-const VERSION = "0.12.0";
+const VERSION = "0.14.0";
 /**
 * Current maturity. Router I (typed params, Standard-Schema search, history, the
 * signals-native router, selector-isolated state, typed + relative navigation)

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@mindees/router` — **Quantum**, the typed router for MindeesNative.\n *\n * Router I (Phase 6): codegen-free typed path params ({@link PathParams}),\n * Standard-Schema validated search params, a signals-native router with typed +\n * relative navigation and selector-isolated state, and an injectable history\n * (memory + browser). See ADR-0003.\n *\n * Router II (Phase 7): render integration — {@link createRouterView} (nested,\n * fine-grained, layout-preserving) and typed {@link createLink} — plus SWR data\n * loaders (with `AbortSignal`, {@link Router.invalidate}/{@link Router.preload}),\n * navigation guards ({@link BeforeNavigate} cancel/redirect + idempotent\n * navigation), and web view transitions. See ADR-0004 and ADR-0005.\n *\n * Still a later phase (not exported): the global typed route registry and\n * file-based route scanning + bundler plugin. See `STATUS.md`.\n *\n * @module\n */\n\nimport type { Maturity, PackageInfo } from '@mindees/core'\nimport { NotImplementedError, notImplemented } from '@mindees/core'\n\n/** Render integration: nested view + typed links (Router II). */\nexport {\n  createLink,\n  createRouterView,\n  type LinkComponent,\n  type LinkOptions,\n  type LinkProps,\n  type PrefetchMode,\n  type RouterViewOptions,\n} from './components'\n/** Loaders + data (SWR). */\nexport type {\n  LoaderContext,\n  LoaderData,\n  LoaderDepsFn,\n  LoaderFn,\n  LoaderStatus,\n} from './data'\n/** Errors. */\nexport { RouterError, type RouterErrorCode } from './errors'\n/** File-based routing: a module map → a router (Expo-style conventions). */\nexport { createFileRouter, type RouteModule, routesFromModules } from './file-routes'\n/** History capability. */\nexport {\n  createBrowserHistory,\n  createHref,\n  createMemoryHistory,\n  type HistoryListener,\n  type MemoryHistoryOptions,\n  parseHref,\n  type RouterHistory,\n  type RouterLocation,\n} from './history'\n/** Ergonomic hooks + a bound Link that resolve the active router. */\nexport { Link, useParams, usePathname, useRouter, useSearch } from './hooks'\n/** Route patterns + codegen-free typed params. */\nexport {\n  buildPath,\n  compareSpecificity,\n  type HasPathParams,\n  matchPattern,\n  type PathParams,\n  parsePattern,\n} from './pattern'\n/** Router. */\nexport {\n  type BeforeNavigate,\n  type CreateRouterOptions,\n  createRouter,\n  type NavigateOptions,\n  type NavTarget,\n  type RouteComponentProps,\n  type RouteMatch,\n  type RouteRecord,\n  type Router,\n  type RouterState,\n  resolvePath,\n} from './router'\n/** Search (query) params. */\nexport {\n  parseQuery,\n  type QueryValue,\n  safeValidateSearch,\n  stringifyQuery,\n  type ValidationResult,\n  validateSearch,\n} from './search'\n/** Standard Schema — the validator-agnostic interface (vendored, types only). */\nexport type { StandardSchemaV1 } from './standard-schema'\n\n/** The npm package name. */\nexport const name = '@mindees/router'\n\n/** The package version. All `@mindees/*` packages share one locked version line. */\nexport const VERSION = '0.12.0'\n\n/**\n * Current maturity. Router I (typed params, Standard-Schema search, history, the\n * signals-native router, selector-isolated state, typed + relative navigation)\n * and Router II (nested rendering, typed links, SWR loaders, navigation guards,\n * view transitions) are implemented and tested. The global typed route registry\n * and file-based route scanning are a later phase — see `STATUS.md`.\n */\nexport const maturity: Maturity = 'experimental'\n\n/** Static identity + maturity metadata for this package. */\nexport const info: PackageInfo = { name, version: VERSION, maturity }\n\nexport type { Maturity, PackageInfo }\nexport { NotImplementedError, notImplemented }\n"],"mappings":";;;;;;;;;;;AA8FA,MAAa,OAAO;;AAGpB,MAAa,UAAU;;;;;;;;AASvB,MAAa,WAAqB;;AAGlC,MAAa,OAAoB;CAAE;CAAM,SAAS;CAAS;AAAS"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["/**\n * `@mindees/router` — **Quantum**, the typed router for MindeesNative.\n *\n * Router I (Phase 6): codegen-free typed path params ({@link PathParams}),\n * Standard-Schema validated search params, a signals-native router with typed +\n * relative navigation and selector-isolated state, and an injectable history\n * (memory + browser). See ADR-0003.\n *\n * Router II (Phase 7): render integration — {@link createRouterView} (nested,\n * fine-grained, layout-preserving) and typed {@link createLink} — plus SWR data\n * loaders (with `AbortSignal`, {@link Router.invalidate}/{@link Router.preload}),\n * navigation guards ({@link BeforeNavigate} cancel/redirect + idempotent\n * navigation), and web view transitions. See ADR-0004 and ADR-0005.\n *\n * Still a later phase (not exported): the global typed route registry and\n * file-based route scanning + bundler plugin. See `STATUS.md`.\n *\n * @module\n */\n\nimport type { Maturity, PackageInfo } from '@mindees/core'\nimport { NotImplementedError, notImplemented } from '@mindees/core'\n\n/** Render integration: nested view + typed links (Router II). */\nexport {\n  createLink,\n  createRouterView,\n  type LinkComponent,\n  type LinkOptions,\n  type LinkProps,\n  type PrefetchMode,\n  type RouterViewOptions,\n} from './components'\n/** Loaders + data (SWR). */\nexport type {\n  LoaderContext,\n  LoaderData,\n  LoaderDepsFn,\n  LoaderFn,\n  LoaderStatus,\n} from './data'\n/** Errors. */\nexport { RouterError, type RouterErrorCode } from './errors'\n/** File-based routing: a module map → a router (Expo-style conventions). */\nexport { createFileRouter, type RouteModule, routesFromModules } from './file-routes'\n/** History capability. */\nexport {\n  createBrowserHistory,\n  createHref,\n  createMemoryHistory,\n  type HistoryListener,\n  type MemoryHistoryOptions,\n  parseHref,\n  type RouterHistory,\n  type RouterLocation,\n} from './history'\n/** Ergonomic hooks + a bound Link that resolve the active router. */\nexport { Link, useParams, usePathname, useRouter, useSearch } from './hooks'\n/** Route patterns + codegen-free typed params. */\nexport {\n  buildPath,\n  compareSpecificity,\n  type HasPathParams,\n  matchPattern,\n  type PathParams,\n  parsePattern,\n} from './pattern'\n/** Router. */\nexport {\n  type BeforeNavigate,\n  type CreateRouterOptions,\n  createRouter,\n  type NavigateOptions,\n  type NavTarget,\n  type RouteComponentProps,\n  type RouteMatch,\n  type RouteRecord,\n  type Router,\n  type RouterState,\n  resolvePath,\n} from './router'\n/** Search (query) params. */\nexport {\n  parseQuery,\n  type QueryValue,\n  safeValidateSearch,\n  stringifyQuery,\n  type ValidationResult,\n  validateSearch,\n} from './search'\n/** Standard Schema — the validator-agnostic interface (vendored, types only). */\nexport type { StandardSchemaV1 } from './standard-schema'\n\n/** The npm package name. */\nexport const name = '@mindees/router'\n\n/** The package version. All `@mindees/*` packages share one locked version line. */\nexport const VERSION = '0.14.0'\n\n/**\n * Current maturity. Router I (typed params, Standard-Schema search, history, the\n * signals-native router, selector-isolated state, typed + relative navigation)\n * and Router II (nested rendering, typed links, SWR loaders, navigation guards,\n * view transitions) are implemented and tested. The global typed route registry\n * and file-based route scanning are a later phase — see `STATUS.md`.\n */\nexport const maturity: Maturity = 'experimental'\n\n/** Static identity + maturity metadata for this package. */\nexport const info: PackageInfo = { name, version: VERSION, maturity }\n\nexport type { Maturity, PackageInfo }\nexport { NotImplementedError, notImplemented }\n"],"mappings":";;;;;;;;;;;AA8FA,MAAa,OAAO;;AAGpB,MAAa,UAAU;;;;;;;;AASvB,MAAa,WAAqB;;AAGlC,MAAa,OAAoB;CAAE;CAAM,SAAS;CAAS;AAAS"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindees/router",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Quantum — the typed, signals-native router for MindeesNative: codegen-free typed path params, Standard Schema validated search params, and selector-isolated reactive route state.",
   "keywords": [
     "router",
@@ -35,13 +35,13 @@
     "directory": "packages/router"
   },
   "dependencies": {
-    "@mindees/core": "0.12.0"
+    "@mindees/core": "0.14.0"
   },
   "devDependencies": {
     "happy-dom": "20.9.0",
     "valibot": "1.4.1",
     "zod": "4.4.3",
-    "@mindees/renderer": "0.12.0"
+    "@mindees/renderer": "0.14.0"
   },
   "scripts": {
     "build": "tsdown",