@solidrt/router 0.0.64 → 0.0.66

package/AGENTS.md

@@ -57,11 +57,75 @@ let item = createRoute({                                    // a value: typed pa
   route, or with children a pathless layout. Children match in
   declaration order.
 
+## App structure
+
+Split a routed app by role, so the entry reads as a map of the app:
+
+```
+src/
+  index.tsx          the entry: render(), the window and the route tree
+  app.tsx            App, the root layout: what stays around every screen
+                     (background, safe area, nav bar), renders <Outlet />
+  state.ts           module-scope signals the screens share
+  routes/
+    home.tsx         /                one file per screen
+    settings.tsx     /settings        a layout: renders <Outlet />
+    settings/
+      theme.tsx      /settings/theme  its children, in a folder of its name
+    item.tsx         /item/$id        exports its route value (typed params)
+    not-found.tsx    /$
+```
+
+```tsx
+// src/index.tsx
+render(() => (
+  <window title="My app">
+    <Router initial="/">
+      <Route path="/" component={App}>
+        <Route path="/" component={Home} />
+        <SettingsRoutes />
+        <Route route={item} />
+        <Route path="/$" component={NotFound} />
+      </Route>
+    </Router>
+  </window>
+))
+
+// src/routes/settings.tsx: a section that owns its subtree
+export function SettingsRoutes() {
+  return (
+    <Route path="/settings" component={Settings}>
+      <Route path="/" component={Overview} />
+      <Route path="/theme" component={Theme} />
+    </Route>
+  )
+}
+```
+
+- Prefer the JSX tree. The tree as values (`createRouter` at module scope)
+  is for code outside the component tree that must reach the router.
+- The file layout is a convention, not a mechanism: a path comes from the
+  `path` of its `<Route>` and nothing reads the file system. Name a file
+  after the path so a screen is found by its link.
+- index.tsx holds the window and the tree, nothing else. App-wide effects
+  (theme, focus navigation) go in `App`; a window prop that changes reads
+  state.ts.
+- A screen is one file until it has children; then its children go in a
+  folder of its name. While the tree is small, write it whole in index.tsx.
+  When a section grows, its file exports a component returning its
+  `<Route>` subtree (`SettingsRoutes` above, a fragment for several
+  siblings), placed in the tree like a `<Route>`.
+- A screen with typed params defines its `createRoute` value in its own
+  file, next to the `useParams(item)` that reads it; index.tsx places it.
+- routes/ holds screens only. Pieces several screens share live beside it.
+- With tabs, the tabs route goes under `App` and its component draws the
+  bar.
+
 ## 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.
+  `<Route>` elements, or components returning them, 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
@@ -71,7 +135,7 @@ let item = createRoute({                                    // a value: typed pa
   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.
+  module-scope signal (state.ts above), 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
@@ -93,4 +157,4 @@ let item = createRoute({                                    // a value: typed pa
   `/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.
+  publishes, `sol render --link <path>` renders that screen.

package/README.md

@@ -2,7 +2,7 @@
 
 `@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
+path is what a link from the OS, an MCP tool, `sol 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.
@@ -50,6 +50,62 @@ 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`).
 
+## App structure
+
+A routed app splits by role, so the entry reads as a map of the app:
+
+```
+src/
+  index.tsx          the entry: render(), the window and the route tree
+  app.tsx            App, the root layout: what stays around every screen
+  state.ts           module-scope signals the screens share
+  routes/
+    home.tsx         /
+    settings.tsx     /settings        a layout: renders <Outlet />
+    settings/
+      theme.tsx      /settings/theme
+    item.tsx         /item/$id
+    not-found.tsx    /$
+```
+
+The entry holds the window and the tree and nothing else. `App` is the
+outermost layout route (the `Shell` above): the background, the safe area,
+a nav bar, the app-wide effects, around an `<Outlet />`. State that screens
+share is module-scope signals in `state.ts`, since route components take no
+props. Each screen is a file under `routes/`, named after its path; a
+screen with children keeps its file as the layout and gets a folder of the
+same name for them.
+
+This is a convention, not a mechanism: a path comes from the `path` of its
+`<Route>`, and nothing reads the file system. Naming the file after the
+path is what lets a screen be found by its link.
+
+While the tree is small it is written whole in the entry. When a section
+grows, it can own its subtree: a component that returns `<Route>` elements
+is placed in the tree like a `<Route>` (a fragment returns several
+siblings), so the entry keeps one line per section.
+
+```tsx
+// src/routes/settings.tsx
+export function SettingsRoutes() {
+  return (
+    <Route path="/settings" component={Settings}>
+      <Route path="/" component={Overview} />
+      <Route path="/theme" component={Theme} />
+    </Route>
+  )
+}
+
+// src/index.tsx
+<Route path="/" component={App}>
+  <Route path="/" component={Home} />
+  <SettingsRoutes />
+  <Route path="/$" component={NotFound} />
+</Route>
+```
+
+`sol init` with the router selected starts a project in this shape.
+
 ## Params are validated
 
 A path arrives as strings, and from outside the app they are untrusted. A
@@ -230,9 +286,9 @@ 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
+`sol: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
+screen directly. `sol 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`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/router",
-  "version": "0.0.64",
+  "version": "0.0.66",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -15,7 +15,7 @@
     "AGENTS.md"
   ],
   "peerDependencies": {
-    "@solidjs/signals": "2.0.0-rc.9",
-    "@solidrt/core": "0.0.64"
+    "@solidjs/signals": "2.0.0-rc.13",
+    "@solidrt/core": "0.0.66"
   }
 }

package/src/router.tsx

@@ -2,10 +2,10 @@
 // navigation, the back step, blocking, links in and the location out, the
 // JSX tree (`<Route>`) and the components that render the matched routes.
 // Everything here is built on what core offers every app (onBack, onLink,
-// env.launchLink, reportLocation from srt:dev); core knows nothing of routes.
+// env.launchLink, reportLocation from sol:dev); core knows nothing of routes.
 import { createSignal, createMemo, createContext, createEffect, useContext, untrack, onCleanup, children, Show, For } from "@solidrt/core"
 import { env, onBack, onLink } from "@solidrt/core"
-import { reportLocation } from "srt:dev"
+import { reportLocation } from "sol:dev"
 import { createRootRoute, createRoute, formatPath, linkToPath, matchPath, place } from "./route"
 import type { AnyRoute, Match, ParamsOf, RawParams, Route as RouteValue } from "./route"
 import { back as stepBack, changed, currentPath, findTabs, initialState, push, replace, reset, resolve } from "./stack"