@rangojs/router 0.0.0-experimental.b02a2fec → 0.0.0-experimental.b30bbf02

package/README.md

@@ -10,6 +10,7 @@ Named-route RSC router with structural composability and type-safe partial rende
 - **Structural composability** — Attach routes, loaders, middleware, handles, caching, prerendering, and static generation without hiding the route tree
 - **Composable URL patterns** — Django-style `urls()` DSL with `path`, `layout`, `include`
 - **Data loaders** — `createLoader()` with automatic streaming and Suspense integration
+- **Server actions** — `"use server"` mutations with `useActionState`, `useOptimistic`, and per-segment + per-loader `revalidate()` rules
 - **Live data layer** — Pre-render or cache the UI shell while loaders stay live by default at request time
 - **Layouts & nesting** — Nested layouts with `<Outlet />` and parallel routes
 - **Segment-level caching** — `cache()` DSL with TTL/SWR and pluggable cache stores
@@ -161,13 +162,18 @@ const urlpatterns = urls(({ path }) => [
 ]);
 ```
 
-Use `reverse()` as the default way to link to routes:
+Use `ctx.reverse()` from handler context as the default way to link to routes from server code:
 
 ```tsx
-router.reverse("product", { slug: "widget" }); // "/product/widget"
-router.reverse("search", undefined, { q: "rsc" }); // "/search?q=rsc"
+const ProductPage: Handler<"product"> = (ctx) => {
+  const url = ctx.reverse("product", { slug: "widget" }); // "/product/widget"
+  const searchUrl = ctx.reverse("search", undefined, { q: "rsc" }); // "/search?q=rsc"
+  return <Link to={url}>Widget</Link>;
+};
 ```
 
+`router.reverse()` (exported from the router module) is the same function without a handler context, useful in scripts or tests. In request code, prefer `ctx.reverse()` — it auto-fills mount params from the current match.
+
 ### Composable URL Modules
 
 Local route names compose cleanly with `include(..., { name })`:
@@ -477,41 +483,130 @@ const urlpatterns = urls(({ path, loader }) => [
 ]);
 ```
 
-## Navigation & Links
+## Server Actions
 
-### Named Routes with `reverse()` (Server Components)
+Server actions are React's RSC mutation primitive. Define them with the
+`"use server"` directive — Rango uses standard React 19 hooks
+(`useActionState`, `useFormStatus`, `useOptimistic`) with no framework wrapper.
 
-In server components, use `reverse()` to generate URLs by route name:
+```tsx
+// app/actions/cart.ts
+"use server";
+
+import { getRequestContext } from "@rangojs/router";
+
+export async function addToCart(productId: string): Promise<void> {
+  const ctx = getRequestContext();
+  const userId = ctx.get("user").id;
+  await db.cart.insert({ userId, productId });
+}
+```
 
 ```tsx
-import { Link } from "@rangojs/router/client";
-import { reverse } from "./router";
+// Client form with progressive enhancement + pending state
+"use client";
+import { useActionState } from "react";
+import { saveProfile } from "../actions/profile";
 
-function BlogIndex() {
+export function ProfileForm() {
+  const [state, action, pending] = useActionState(saveProfile, null);
   return (
-    <nav>
-      <Link to={reverse("home")}>Home</Link>
-      <Link to={reverse("blogPost", { slug: "my-post" })}>My Post</Link>
-      <Link to={reverse("about")}>About</Link>
-    </nav>
+    <form action={action}>
+      <input name="name" defaultValue={state?.values?.name} />
+      {state?.errors?.name && <p role="alert">{state.errors.name}</p>}
+      <button disabled={pending}>{pending ? "Saving…" : "Save"}</button>
+    </form>
   );
 }
 ```
 
-`reverse()` is type-safe — route names and required params are checked at compile time. Included routes use dotted names: `reverse("api.health")`.
+After an action runs, matched route segments (path/layout/parallel/intercept)
+and loaders can re-render/re-resolve so the UI reflects the new state.
+Attach a `revalidate(({ actionId }) => ...)` rule on any segment or loader
+that owns data the action touched:
 
-Handlers also have `ctx.reverse()` directly on the context:
+```tsx
+urls(({ path, loader, revalidate }) => [
+  // Segment-level: re-render the cart page handler after cart actions.
+  // Nest loaders that belong to this route inside the same path() so the
+  // segment owns its data dependencies.
+  path("/cart", CartPage, { name: "cart" }, () => [
+    revalidate(
+      ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
+    ),
+    loader(CartLoader, () => [
+      revalidate(
+        ({ actionId }) => actionId?.startsWith("src/actions/cart.ts#") ?? false,
+      ),
+    ]),
+  ]),
+]);
+```
+
+For the full guide — validation with Zod, error handling, file uploads,
+`useOptimistic`, redirects, and progressive enhancement — see the
+`/server-actions` skill.
+
+## Navigation & Links
+
+### Named Routes with `ctx.reverse()` (Server)
+
+In server components and handlers, use `ctx.reverse()` to generate URLs by route name. This is the default — it is typed, auto-fills mount params from the current match, and resolves both local (`.name`) and absolute (`name.sub`) names:
 
 ```tsx
+import { Link } from "@rangojs/router/client";
+import type { Handler } from "@rangojs/router";
+
 const BlogPostPage: Handler<"blogPost"> = (ctx) => {
   const backUrl = ctx.reverse("blog");
   return <Link to={backUrl}>Back to blog</Link>;
 };
 ```
 
+`reverse()` is type-safe — route names and required params are checked at compile time. Included routes use dotted names: `ctx.reverse("api.health")`.
+
+For scripts, tests, or other code without a handler context, import the router-level `reverse`:
+
+```tsx
+import { reverse } from "./router";
+reverse("blogPost", { slug: "my-post" });
+```
+
+### Client Components
+
+**`reverse()` is server-only.** It depends on the route manifest and handler context — neither is available in the browser bundle. Client components receive URLs as props, loader data, or server-action return values:
+
+```tsx
+// server
+function BlogIndex(ctx: HandlerContext) {
+  return (
+    <Nav
+      home={ctx.reverse("home")}
+      post={ctx.reverse("blogPost", { slug: "my-post" })}
+    />
+  );
+}
+```
+
+```tsx
+"use client";
+import { Link } from "@rangojs/router/client";
+
+export function Nav({ home, post }: { home: string; post: string }) {
+  return (
+    <nav>
+      <Link to={home}>Home</Link>
+      <Link to={post}>My Post</Link>
+    </nav>
+  );
+}
+```
+
+For client-side navigation to static paths (no named-route lookup), use `href()` — see below. For URLs tied to named routes, always generate on the server and pass the string in.
+
 ### `href()` for Path Validation (Client Components)
 
-In client components, use `href()` for compile-time path validation:
+In client components, use `href()` for compile-time path validation on static path strings:
 
 ```tsx
 "use client";