@solidrt/router 0.0.62

package/AGENTS.md

@@ -0,0 +1,96 @@
+# @solidrt/router - agent notes
+
+Routing for SolidRT apps: a typed route tree, a stack, one back step, links
+in and the location out. Optional: an app with one screen, or one that
+routes by hand over core's `onBack`/`onLink`, needs none of it. Prose is in
+README.md; the typed API is src/route.ts (the headless tree and matching)
+and src/router.tsx (the Solid binding).
+
+## Install
+
+```sh
+bun add @solidrt/router   # peers: @solidrt/core, @solidjs/signals
+```
+
+## Shape
+
+```tsx
+let item = createRoute({                                    // a value: typed params
+  path: "/item/$id",
+  params: { parse: (raw) => ({ id: Number(raw.id) }) },   // throw = no match
+  component: Item,
+})
+
+<Router initial="/">                                        // once, inside <Window>
+  <Route path="/" component={Shell}>                        // Shell renders <Outlet />
+    <Route path="/" component={Home} />
+    <Route path="/settings" component={Settings} />
+    <Route route={item} />                                  // the value, placed
+    <Route path="/$" component={NotFound} />
+  </Route>
+</Router>
+```
+
+- JSX for the tree; a route value (`createRoute`) where a param needs a
+  type or validation, placed with `<Route route={...}>`. A JSX `<Route>`
+  takes `path` and `component` only. Values can also form the whole tree
+  (`createRootRoute({ children: [...] })`, `createRoute({ ..., children })`)
+  with `createRouter({ tree })` at module scope and `<Router router={...}>`;
+  the player does this.
+- Targets: `useNavigate()("/item/42")` by path (matched at run time, refused
+  with a warning when nothing matches), or by value, checked at compile
+  time: `navigate(home)`, `navigate({ route: item, params: { id: 42 } })`.
+- `useParams()()` is the screen's raw strings; `useParams(item)()` is typed
+  by the value. Both reactive. `useLocation()`, `useNavigate()`,
+  `useRouter()`, `createLink(target)`, `useBlocker(fn)`.
+- `router.entries()` is the stack as paths; pass a saved one as `initial`.
+- Tabs: `<Route path="/" tabs component={Main}>` makes each child a tab
+  with a stack of its own, kept mounted and hidden while another shows;
+  full-window screens are siblings of the tabs route, above the bar. `Main`
+  renders `<Outlet />` and draws the bar from `useTabs()` (`{ paths,
+  active(), select(path) }`, e.g. wired to components' `NavShell`). A tab
+  is named by its literal root path. Select = show as left, re-select =
+  back to root; back pops above the bar, then the tab, then goes to the
+  first tab, then the platform. With tabs `entries()` is `{ stack, tabs }`.
+- Path syntax: literal, `$name`, `$name?` (last), `$` for the rest (a `$`
+  route last under the root is the not-found screen). `/` is an index
+  route, or with children a pathless layout. Children match in
+  declaration order.
+
+## Traps
+
+- A `<Route>` is not an element: it evaluates to a route value. Only
+  `<Route>` elements go under `<Router>` or another `<Route>`; anything
+  else there throws at mount.
+- A route value has one place in one tree: placing it twice (two `<Route
+  route={x}>`, or a `children:` list and a `<Route route={x}>`) throws.
+- With a JSX tree the router exists only inside `<Router>`: screens reach
+  it through `useNavigate()` / `useRouter()`, not a module-scope import.
+  With a value tree at module scope, screens that import route values from
+  the module that imports them form a cycle ESM handles as long as a
+  screen reads a route only inside a handler or a hook call, never at
+  module scope.
+- Route components take no props. State a screen shares with others is a
+  module-scope signal (see the player's parts/app-state.ts), not a prop.
+- A layout route's component must render `<Outlet />` or its child never
+  appears; a route without a component is an outlet alone.
+- `<Router>` registers its `onBack` before anything it renders. A dialog
+  that registers its own `onBack` inside a screen still runs first, as
+  before; only use `useBlocker` for guards that must hold a navigation
+  (unsaved changes), not for closing overlays.
+- `navigate(..., { reset: true })` for "flow finished, this is home"; a
+  plain push there leaves the flow's screens under home for back to revisit.
+- A hidden tab is laid out to nothing: its reactive code keeps running,
+  but `getBoundingBox` and friends return null there and nothing in it is
+  painted, hit or focusable. A screen that measures itself checks
+  `useTabs().active()` against its tab's path, or tolerates null.
+- The tabs route and each tab render in a full-size `<view>` (flex 1,
+  column): put the tabs route under laid-out parents only.
+- Nothing above a tabs route takes a param, a tab's path is literal, one
+  tabs route per tree and never inside a tab: all thrown at tree build.
+- Links are untrusted: put validation in `params.parse`, never in the
+  screen. `linkToPath` strips a custom scheme whole (`myapp://a/b` is
+  `/a/b`) and an http(s) host.
+- Tooling: `open_link` / `POST /__control__/link` opens a screen,
+  `get_location` / `GET /__control__/link` reads the path the router
+  publishes, `srt render --link <path>` renders that screen.

package/README.md

@@ -0,0 +1,257 @@
+# Router
+
+`@solidrt/router` makes screens addressable. A route tree maps a path like
+`/settings/theme` to a screen, a stack holds where the app is, and the same
+path is what a link from the OS, an MCP tool, `srt render --link` or a saved
+session carries. It is a layer over core: core reports links (`onLink`,
+`env.launchLink`) and the back intent (`onBack`), the router decides what
+they mean. An app can route by hand without it.
+
+Not a web router. There is no address bar, no forward, no history API, no
+code splitting, no data loading. What is left is small, and typed.
+
+## Routes
+
+The tree is JSX, one `<Route>` per screen, nested for layouts:
+
+```tsx
+import { Router, Route, Outlet, useParams, useNavigate } from "@solidrt/router"
+
+render(() => (
+  <Window>
+    <Router initial="/">
+      <Route path="/" component={Shell}>
+        <Route path="/" component={Home} />
+        <Route path="/settings" component={SettingsLayout}>
+          <Route path="/$section" component={Section} />
+        </Route>
+        <Route path="/$" component={NotFound} />
+      </Route>
+    </Router>
+  </Window>
+))
+
+function Section() {
+  let params = useParams()              // () => { section: string }
+  return <text>{params().section}</text>
+}
+```
+
+A route's `path` is its own piece below the parent: literal segments,
+`$name` for a param, `$name?` for an optional one at the end, `$` for the
+rest of the path (captured as `rest`; a `$` route last under the root is
+the not-found screen). `/` adds nothing: an index route under a layout, or
+with children a pathless layout (the `Shell` above). A layout route's
+component renders its child with `<Outlet />`; a route without a component
+is an `<Outlet />` alone. Children match in declaration order, first match
+wins, so a catch-all goes last.
+
+A `<Route>` is not an element: it evaluates to a route value that its
+parent places in the tree, once, when `<Router>` mounts. The router made
+this way is reached through the hooks (`useNavigate`, `useRouter`).
+
+## Params are validated
+
+A path arrives as strings, and from outside the app they are untrusted. A
+JSX route hands them to its screen as they came (`useParams()` above). When
+a param has a shape, a route is a value with a `parse`, placed in the JSX
+tree where it belongs:
+
+```tsx
+import { createRoute } from "@solidrt/router"
+
+let item = createRoute({
+  path: "/item/$id",
+  params: { parse: (raw) => ({ id: parseId(raw.id) }) },
+  component: Item,
+})
+
+<Route route={item} />                  // in the tree, next to the JSX routes
+
+function Item() {
+  let params = useParams(item)          // () => { id: number }
+  return <text>{params().id}</text>
+}
+```
+
+`params.parse` is the one place strings become typed values: return them,
+or throw, and the route does not match (the next sibling is tried, then
+the catch-all). `useParams(route)` is typed by the route it names, so there
+is no way to read a value that did not pass. That is the rule: JSX for the
+tree, a route value where a param needs a type. A JSX `<Route>` takes no
+`params`.
+
+Params are reactive: navigating to the same route with other params updates
+`params()` without remounting the screen. An ancestor's params are in the
+match too; read them through the ancestor, `useParams(settings)`.
+
+### The tree as values
+
+The whole tree can be values instead, with the router made at module scope
+so screens import it directly; the player app does this. Children are a
+list, in matching order, and a route has one place in one tree:
+
+```tsx
+let root = createRootRoute({
+  component: Shell,
+  children: [home, settings, item, notFound],
+})
+let router = createRouter({ tree: root, initial: "/" })
+
+<Router router={router} />
+```
+
+`<Route route={x}>` and a `children:` list are the same placement; a JSX
+`<Route route={settings}>` can nest more `<Route>` elements under a value
+that already has children of its own.
+
+## Navigation
+
+```tsx
+let navigate = useNavigate()
+navigate(home)                                        // a route without params
+navigate({ route: section, params: { section: "theme" } })  // one with params, checked
+navigate("/settings/theme")                           // a path, as a link would carry it
+navigate(home, { replace: true })                     // swap the top instead of pushing
+navigate(home, { reset: true })                       // start the stack over here (a flow finished)
+router.back()                                         // pop
+```
+
+The route forms are checked at compile time: a removed screen or a missing
+param is a build error. The path form is matched at run time and refused,
+with a warning, when nothing matches.
+
+Every navigation is a signal write, so Solid's transition semantics apply:
+a new screen whose async reads are still pending keeps the previous one on
+screen, and `isPending(() => router.location())` says so. Data lives in
+the screen (`createMemo(() => db.query(...))` under `<Loading>`, failures
+in `<Errored>`); the router has no data layer.
+
+`createLink(target)` gives `{ href, go }` for a pressable; styling is the
+caller's.
+
+## Tabs
+
+A `tabs` route makes each of its children a tab: a screen with a stack of
+its own, kept mounted while another tab shows. Full-window screens (a
+viewer, a login) go above the tab bar, as siblings of the tabs route.
+
+```tsx
+import { useTabs } from "@solidrt/router"
+
+<Router>
+  <Route path="/" tabs component={Main}>
+    <Route path="/feed">
+      <Route path="/" component={Feed} />
+      <Route path="/post/$id" component={Post} />
+    </Route>
+    <Route path="/search" component={Search} />
+    <Route path="/profile" component={Profile} />
+  </Route>
+  <Route path="/viewer/$id" component={Viewer} />
+  <Route path="/$" component={NotFound} />
+</Router>
+
+function Main() {
+  let tabs = useTabs()                  // { paths, active(), select(path) }
+  return (
+    <NavShell items={items} value={tabs.active()} onChange={(v) => tabs.select(v as string)}>
+      <Outlet />
+    </NavShell>
+  )
+}
+```
+
+A tab is named by its root path (`/feed`), the router's usual unit: what a
+link carries, what a `NavShell` item holds. A tab's path is literal and
+nothing above the tabs route takes a param; a tree holds one tabs route,
+not inside another. `createRoute({ tabs: true, children })` is the value
+form. The router draws no bar: `NavShell` from components does, wired in
+app code as above, or any component of the app's own.
+
+The tabs behave as native tab bars do:
+
+- Selecting another tab shows it as it was left. Selecting the tab that
+  shows takes it back to its root. `navigate` to a tab's root path is the
+  same as selecting it.
+- Navigating to a screen in a tab shows that tab and pushes the screen on
+  its stack. Navigating to a screen outside the tabs pushes it above the
+  tab bar, full window; back returns to the tabs, active tab intact.
+- Back pops the screen above the tab bar if there is one, else the active
+  tab's stack while it is deeper than its root, else switches a non-first
+  tab to the first tab, and on the first tab's root leaves the event to
+  the platform.
+- `replace` swaps the top of the stack that holds the target (the tab bar
+  itself, when a full-window screen replaces it); `reset` clears every
+  stack and lands the target with its tab's root beneath it.
+- A link arriving while the app runs is a navigation. A launch link into a
+  tab lands with the tab's root beneath it, the other tabs on their roots.
+- `useBlocker` in a tab holds the moves that change that tab's stack; in a
+  component outside the tabs, those that change the parent stack. Showing
+  another tab changes no stack and asks no blocker.
+
+A tab mounts the first time it shows and stays mounted, hidden while
+another shows: never painted, hit or focused, its reactive code still
+running. Inside a tab `useLocation` and `useParams` read the tab's own
+stack whether or not it shows, and `useTabs().active()` compared with the
+tab's path says whether it does, for a screen to pause video or per-frame
+work. The tabs route and each tab render in a full-size `<view>` (flex 1,
+column) of their own. The tabs stay mounted under a full-window screen as
+long as the routes above the tabs route stay matched, which they do when
+that screen is a sibling of the tabs route.
+
+With tabs, `entries()` is `{ stack, tabs: { active, stacks } }`: the parent
+stack, in which the tabs route's own path stands for the tab bar, and a
+stack per tab. `initial` takes that back; a path or a list of paths still
+works too.
+
+## Back
+
+`<Router>` registers one `onBack` step: it pops while the stack is deeper
+than one entry, and at the root leaves the event to the platform default
+(background on Android, exit elsewhere). With tabs the step is the one
+described above. It registers before anything it
+renders, so a dialog or a screen that registers its own `onBack` gets the
+event first, as before.
+
+`useBlocker(fn)` guards leaving the current entry while the component is
+mounted: back, navigate and replace ask it first. Return `false` to stay,
+`true` to go, or a promise that decides later (a confirm dialog). A
+blocked back is prevented and never falls through to the platform.
+
+## Links in, location out
+
+`createRouter` reads `env.launchLink`: a link the app was started with wins
+over `initial` and lands as a stack of one. `<Router>` subscribes to
+`onLink`: a link arriving while the app runs pushes onto the stack. A
+custom-scheme link keeps everything after the scheme (`myapp://settings/theme`
+is `/settings/theme`); an http(s) link drops its host; a query or fragment
+is dropped. A link that matches nothing lands on the catch-all route, or is
+ignored with a warning.
+
+`<Router>` reports the current path through `reportLocation` from
+`srt:dev`, so `GET /__control__/link` and the `get_location` MCP tool read
+where the app is, and `POST /__control__/link` or `open_link` opens a
+screen directly. `srt render --link /settings` renders that screen. A hot
+reload starts the rebuilt app at the path it was on: the runtime hands the
+last reported path to the new run as `env.launchLink`.
+
+## Restore
+
+The stack is plain data:
+
+```tsx
+onSuspend(() => file("nav.json").write(JSON.stringify(router.entries())))
+```
+
+To resume, read it back before creating the router and pass it as
+`initial` (an array is a saved stack). Whether to resume is the app's call
+(`env.launch === "restored"`); a launch link still wins.
+
+## Reference
+
+- `<Router initial?>` with `<Route path? component? tabs?>` / `<Route route>` children, or `<Router router />`; `<Outlet />`
+- `createRoute({ path, params?, component?, children?, tabs? })`, `createRootRoute({ component?, children? })`
+- `createRouter({ tree, initial? })` returns `{ entries, location, navigate, back, href }`
+- `useRouter()`, `useLocation()`, `useParams()` / `useParams(route)`, `useNavigate()`, `createLink(target, options?)`, `useBlocker(fn)`, `useTabs()`
+- `matchPath(root, path)`, `formatPath(route, params)`, `linkToPath(link)` for tooling and tests

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@solidrt/router",
+  "version": "0.0.62",
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/wellawaretech",
+  "author": "Antoine van Wel",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "peerDependencies": {
+    "@solidjs/signals": "2.0.0-rc.9",
+    "@solidrt/core": "0.0.62"
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { createRootRoute, createRoute, matchPath, formatPath, formatPattern, linkToPath } from "./route.ts"
+export type { AnyRoute, ParamsOf, RouteOptions, RawParams, Match } from "./route.ts"
+export {
+  createRouter,
+  Router,
+  Route,
+  Outlet,
+  useRouter,
+  useLocation,
+  useParams,
+  useNavigate,
+  createLink,
+  useBlocker,
+  useTabs,
+} from "./router.tsx"
+export type { Router as RouterInstance, RouterProps, RouteProps, Location, NavTarget, NavigateOptions, Blocker, RouterOptions, Tabs } from "./router.tsx"
+export type { Entries, TabsState } from "./stack.ts"