@rhi-zone/rainbow-router 0.0.1 → 0.2.0-alpha.1

package/README.md

@@ -0,0 +1,73 @@
+# @rhi-zone/rainbow-router
+
+A trie-based SPA router for TypeScript. Signal-native, no codegen, no file-system conventions.
+
+## What it is
+
+rainbow-router treats the URL as state and routing as a lens. There is no magic file discovery, no compiler plugin, no generated types. You define a plain route tree object, hand it to `createRouter`, and get back a `Router` with a `current` signal that updates on every navigation.
+
+Key properties:
+
+- **Trie matching** — `O(depth)` per navigation, exact segments take priority over dynamic ones.
+- **Dynamic segments** — keys starting with `_` (e.g. `_id`) capture URL segments; validated by `ParamParser` functions.
+- **Loaders** — async data fetching per route, with automatic `AbortSignal` cancellation on navigation.
+- **Scroll handlers** — composable, swappable: `scrollRestore`, `scrollTop`, `scrollNone`, `scrollToHash`.
+- **Mountable subtrees** — type-branded subtrees for composable sub-routers.
+- **No framework dependency** — works with any UI library or vanilla JS.
+
+## Install
+
+```sh
+npm install @rhi-zone/rainbow-router
+```
+
+## Quick example
+
+```ts
+import { createRouter } from '@rhi-zone/rainbow-router'
+import { scrollRestore } from '@rhi-zone/rainbow-router/scroll'
+
+const router = createRouter(
+  {
+    '': { component: HomePage },
+    about: { component: AboutPage },
+    posts: {
+      '': { component: PostListPage },
+      _id: {
+        '': {
+          component: PostPage,
+          loader: async ({ params, signal }) => {
+            const res = await fetch(`/api/posts/${params.id}`, { signal })
+            return res.json()
+          },
+        },
+      },
+    },
+  },
+  { scroll: scrollRestore },
+)
+
+// Navigate programmatically
+router.navigate('/posts/42')
+
+// Subscribe to route changes
+router.current.subscribe((route) => {
+  if (route) console.log('matched', route.leaf.component, route.params)
+})
+
+// Clean up
+router.destroy()
+```
+
+## Entry points
+
+| Import | Contents |
+|---|---|
+| `@rhi-zone/rainbow-router` | `createRouter`, types, `match`, `defineMountable` |
+| `@rhi-zone/rainbow-router/scroll` | `scrollRestore`, `scrollTop`, `scrollNone`, `scrollToHash` |
+| `@rhi-zone/rainbow-router/defaults` | `createRouter` pre-wired with `scrollRestore` |
+| `@rhi-zone/rainbow-router/adapters/standard-schema` | `fromSchema` — adapt Standard Schema validators to `ParamParser` |
+
+## Docs
+
+Full guide and API reference are at the [Rainbow VitePress site](https://rhi.zone/rainbow/).

package/dist/matcher.d.ts

@@ -1,13 +1,17 @@
 import type { RouteTree, MatchedRoute } from './types.ts';
 /**
- * Match a pathname against a route tree.
+ * Match a pathname against a route tree, returning a `MatchedRoute` or `null`.
  *
- * Algorithm (mirrors the Lua trie router):
- * 1. Split pathname into segments
- * 2. Walk the tree segment-by-segment
- * 3. At each node: try exact key first, then `_name` dynamic key
- * 4. Run ParamParser for dynamic segment — null return = no match → 404
- * 5. Collect `''` handlers at intermediate nodes as layout layers
- * 6. At final segment: `''` key is the leaf handler
+ * Algorithm:
+ * 1. Split pathname into segments.
+ * 2. Walk the tree segment-by-segment.
+ * 3. At each node: try the exact key first, then any `_name` dynamic key.
+ * 4. Run the `ParamParser` for dynamic segments — a `null` return means no match (→ 404).
+ * 5. Collect `''` handlers at intermediate nodes as layout layers.
+ * 6. At the final segment: the `''` key is the leaf handler.
+ *
+ * @param tree - The route tree to match against.
+ * @param pathname - The URL pathname to match (e.g. `/posts/42`).
+ * @returns The matched route with layouts, leaf config, and parsed params; or `null` if unmatched.
  */
 export declare function match(tree: RouteTree, pathname: string): MatchedRoute | null;

package/dist/mountable.d.ts

@@ -1,6 +1,41 @@
 import type { RouteTree } from './types.ts';
+/**
+ * A `RouteTree` branded with a `Context` type that describes the params
+ * guaranteed to be present in any route matched within this subtree.
+ *
+ * Used to build composable sub-routers that can be mounted at a dynamic
+ * path segment. The `~context` property is a phantom type marker; it is
+ * never present at runtime.
+ */
 export type Mountable<Context extends Record<string, string>> = RouteTree & {
     readonly '~context': Context;
 };
+/**
+ * A factory function that stamps a `RouteTree` as `Mountable<Context>`.
+ * Created by `defineMountable<Context>()`.
+ */
 export type MountableFactory<Context extends Record<string, string>> = <Tree extends RouteTree>(tree: Tree) => Tree & Mountable<Context>;
+/**
+ * Define a reusable subtree factory for routes that require a specific param context.
+ *
+ * The type parameter `Context` declares which params will be available to all
+ * routes mounted in this subtree (e.g. `{ teamId: string }`). The factory is a
+ * no-op at runtime — it only applies the type brand.
+ *
+ * @example
+ * ```ts
+ * const teamMountable = defineMountable<{ teamId: string }>()
+ *
+ * const teamRoutes = teamMountable({
+ *   '': { component: TeamPage },
+ *   settings: { component: TeamSettingsPage },
+ * })
+ *
+ * const routes: RouteTree = {
+ *   teams: {
+ *     _teamId: teamRoutes,
+ *   },
+ * }
+ * ```
+ */
 export declare const defineMountable: <Context extends Record<string, string>>() => MountableFactory<Context>;

package/dist/router.d.ts

@@ -1,15 +1,51 @@
 import type { ReadonlySignal, AsyncData } from '@rhi-zone/rainbow';
 import type { RouteTree, MatchedRoute, ScrollHandler } from './types.ts';
+/** Options passed to `createRouter`. */
 export type RouterOptions = {
+    /** Scroll behavior handler; defaults to `scrollRestore` when using the `defaults` entry point. */
     scroll?: ScrollHandler;
 };
+/** A running router instance. */
 export type Router = {
+    /** Read-only signal of the currently matched route, or `null` if no route matched. */
     readonly current: ReadonlySignal<MatchedRoute | null>;
+    /** Read-only signal of the active loader's `AsyncData` state. */
     readonly loaderState: ReadonlySignal<AsyncData<unknown>>;
+    /** Push a new history entry and navigate to `pathname`. */
     navigate(pathname: string): void;
+    /** Replace the current history entry and navigate to `pathname`. */
     replace(pathname: string): void;
+    /** Go back one entry in the browser history. */
     back(): void;
+    /** Go forward one entry in the browser history. */
     forward(): void;
+    /** Remove event listeners and abort any in-flight loader. Call when unmounting. */
     destroy(): void;
 };
+/**
+ * Create a router that binds to the browser's `window.location` and History API.
+ *
+ * The `current` signal updates synchronously on every navigation. If the matched
+ * route has a `loader`, the router automatically manages the `loaderState` signal
+ * through `notAsked → loading → success | failure`, aborting in-flight requests on
+ * subsequent navigations.
+ *
+ * @param tree - The route tree to match against.
+ * @param options - Optional scroll handler and other settings.
+ * @returns A `Router` instance.
+ *
+ * @example
+ * ```ts
+ * const router = createRouter({
+ *   '': { component: HomePage },
+ *   about: { component: AboutPage },
+ *   posts: {
+ *     _id: { '': { component: PostPage } },
+ *   },
+ * })
+ *
+ * router.navigate('/posts/42')
+ * router.current.get() // { leaf: { component: PostPage }, params: { id: '42' }, ... }
+ * ```
+ */
 export declare function createRouter(tree: RouteTree, options?: RouterOptions): Router;

package/dist/scroll.d.ts

@@ -1,5 +1,19 @@
 import type { ScrollHandler } from './types.ts';
+/** Scroll to the top of the page on every navigation. */
 export declare const scrollTop: ScrollHandler;
+/** No-op scroll handler — do not scroll on navigation. */
 export declare const scrollNone: ScrollHandler;
+/**
+ * Scroll to the element matching the URL hash on navigation.
+ * If the hash is absent or no element is found, no scroll occurs.
+ */
 export declare const scrollToHash: ScrollHandler;
+/**
+ * Save the current scroll position before navigating away and restore it on
+ * browser back/forward (pop). On push/replace, scrolls to the hash anchor if
+ * present, otherwise to the top of the page.
+ *
+ * Scroll coordinates are stored in `history.state` so they survive page refreshes.
+ * This is the default scroll handler used by the `defaults` entry point.
+ */
 export declare const scrollRestore: ScrollHandler;

package/dist/types.d.ts

@@ -1,36 +1,79 @@
 import type { AsyncData } from '@rhi-zone/rainbow';
-/** The router's only contract for param validation. null = no match → 404. */
+/**
+ * The router's only contract for param validation.
+ * Receive the raw URL segment string; return the parsed value or `null` to signal no match (→ 404).
+ */
 export type ParamParser<T> = (raw: string) => T | null;
+/** Navigation metadata passed to a `ScrollHandler`. */
 export type ScrollNav = {
+    /** Whether this navigation was a history push, pop (back/forward), or replace. */
     readonly type: 'push' | 'pop' | 'replace';
+    /** The hash fragment of the destination URL without the `#`, or `null` if absent. */
     readonly hash: string | null;
+    /** The pathname navigated from. */
     readonly from: string;
+    /** The pathname navigated to. */
     readonly to: string;
 };
+/**
+ * A function called after every navigation to control scroll behavior.
+ * @see scrollTop, scrollNone, scrollToHash, scrollRestore
+ */
 export type ScrollHandler = (nav: ScrollNav) => void;
+/** Context passed to a route loader function. */
 export type LoaderCtx<P extends Record<string, unknown> = Record<string, string>> = {
+    /** Validated and parsed route params for this route. */
     readonly params: P;
+    /** AbortSignal that is aborted if the user navigates away before the loader resolves. */
     readonly signal: AbortSignal;
 };
+/**
+ * An async function that fetches data for a route.
+ * Receives params and an AbortSignal; resolves to the loaded data.
+ */
 export type LoaderFn<P extends Record<string, unknown> = Record<string, string>, T = unknown> = (ctx: LoaderCtx<P>) => Promise<T>;
 /**
- * A route node config — metadata attached to a path depth.
+ * Metadata attached to a route at a given path depth.
  * Component type is `unknown` to stay framework-agnostic;
- * the Lit/React/etc. adapters provide typed wrappers.
+ * framework adapters provide typed wrappers.
  */
 export type RouteConfig = {
+    /** The component or view to render at this route. */
     readonly component?: unknown;
+    /** Optional data loader; called when the route is matched. */
     readonly loader?: LoaderFn;
+    /** ParamParser map for dynamic segments at this node. */
     readonly params?: Record<string, ParamParser<unknown>>;
+    /** Scroll behavior override for this route. */
     readonly scroll?: ScrollHandler;
 };
 /**
- * A route tree node — either a shorthand component, a config, or a subtree.
- * The `''` key at any subtree node is the handler at that exact depth.
+ * A trie node in the route tree.
+ *
+ * - String keys are static path segments (e.g. `admin`, `settings`).
+ * - Keys starting with `_` are dynamic segments (e.g. `_id`, `_slug`).
+ * - The `''` key is the handler at the exact depth of that node.
+ *
+ * @example
+ * ```ts
+ * const routes: RouteTree = {
+ *   '': { component: HomePage },
+ *   admin: {
+ *     '': { component: AdminLayout },
+ *     users: { component: UsersPage },
+ *   },
+ *   posts: {
+ *     _id: {
+ *       '': { component: PostPage, params: { id: Number } },
+ *     },
+ *   },
+ * }
+ * ```
  */
 export type RouteTree = {
     readonly [segment: string]: RouteTree | RouteConfig | unknown;
 };
+/** The result of a successful route match. */
 export type MatchedRoute = {
     /** Layout stack from outermost to innermost, excluding leaf. */
     readonly layouts: RouteConfig[];
@@ -41,4 +84,5 @@ export type MatchedRoute = {
     /** The full matched pathname. */
     readonly pathname: string;
 };
+/** The reactive state of the active route's loader. */
 export type LoaderState<T = unknown> = AsyncData<T, unknown>;

package/package.json

@@ -1,40 +1,40 @@
 {
   "name": "@rhi-zone/rainbow-router",
-  "version": "0.0.1",
+  "version": "0.2.0-alpha.1",
   "description": "Trie-based SPA router for rainbow",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types":  "./dist/index.d.ts"
     },
     "./scroll": {
       "import": "./dist/scroll.js",
-      "types": "./dist/scroll.d.ts"
+      "types":  "./dist/scroll.d.ts"
     },
     "./defaults": {
       "import": "./dist/defaults.js",
-      "types": "./dist/defaults.d.ts"
+      "types":  "./dist/defaults.d.ts"
     },
     "./adapters/standard-schema": {
       "import": "./dist/adapters/standard-schema.js",
-      "types": "./dist/adapters/standard-schema.d.ts"
+      "types":  "./dist/adapters/standard-schema.d.ts"
     }
   },
   "files": ["dist"],
   "scripts": {
-    "dev": "vite build --watch",
-    "build": "vite build && tsgo --emitDeclarationOnly",
+    "dev":       "vite build --watch",
+    "build":     "vite build && tsgo --emitDeclarationOnly",
     "typecheck": "tsgo --noEmit",
-    "test": "vitest run"
+    "test":      "vitest run"
   },
   "dependencies": {
-    "@rhi-zone/rainbow": "0.1.0"
+    "@rhi-zone/rainbow": "0.2.0-alpha.0"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.0.0",
-    "vite": "^6.0.0",
+    "vite":   "^6.0.0",
     "vitest": "^2.0.0"
   }
 }