@rangojs/router 0.0.0-experimental.f2d1a2f1 → 0.0.0-experimental.f4a8e8de

package/skills/hooks/data.md

@@ -0,0 +1,273 @@
+# Data Hooks
+
+### useLoader()
+
+Access loader data (strict - data guaranteed):
+
+```tsx
+"use client";
+import { useLoader } from "@rangojs/router/client";
+import { ProductLoader } from "../loaders/product";
+
+function ProductPrice() {
+  const { data, isLoading, error } = useLoader(ProductLoader);
+
+  // data: T (guaranteed - throws if not in context)
+  // isLoading: boolean
+  // error: Error | null
+
+  return <span>${data.price}</span>;
+}
+```
+
+**Precondition**: Loader must be registered on route via `loader()` helper.
+
+Loaders can also be passed as props from server to client components:
+
+```tsx
+"use client";
+import { useLoader } from "@rangojs/router/client";
+import type { ProductLoader } from "../loaders";
+
+// typeof infers the full data type from the loader definition
+function ProductCard({ loader }: { loader: typeof ProductLoader }) {
+  const { data } = useLoader(loader);
+  return <h2>{data.product.name}</h2>;
+}
+```
+
+### useFetchLoader()
+
+Access loader with on-demand fetching (flexible):
+
+```tsx
+"use client";
+import { useFetchLoader } from "@rangojs/router/client";
+import { SearchLoader } from "../loaders/search";
+
+function SearchResults() {
+  const { data, load, isLoading, error } = useFetchLoader(SearchLoader);
+
+  // data: T | undefined (may be undefined if not fetched)
+  // load: (options?) => Promise<T>
+  // refetch: alias for load
+
+  const handleSearch = async (query: string) => {
+    await load({ params: { query } });
+  };
+
+  return (
+    <div>
+      <input onChange={(e) => handleSearch(e.target.value)} />
+      {isLoading && <Spinner />}
+      {data?.results.map((r) => (
+        <Result key={r.id} {...r} />
+      ))}
+    </div>
+  );
+}
+```
+
+**Shared refetch behavior**:
+
+When the loader is registered on the route via `loader()`, a plain
+`load()` call (no options, or a trivially-defaulted GET with no
+`params` and no `body`) broadcasts its result to every component
+reading the same loader id. Layout, page, and parallel-slot reads
+all converge on the new value:
+
+```tsx
+// Layout button calls load() — the page read below sees the update too.
+function Layout() {
+  const { data, load } = useLoader(CartLoader);
+  return <button onClick={() => load()}>Refresh ({data.count})</button>;
+}
+function Page() {
+  const { data } = useLoader(CartLoader); // updates with the layout's load()
+  return <span>{data.count} items</span>;
+}
+```
+
+`isLoading` and `error` follow the same scope. `throwOnError: true`
+render-throws are scoped to the **originating** hook — sibling readers
+see the error in their `error` state but their boundaries are not
+triggered by someone else's failure. A successful follow-up `load()`
+clears the shared error.
+
+**`load()` calls that stay local** (no broadcast, per-hook state, same
+semantics as the old per-component `useState`):
+
+- `load({ params: { ... } })` — explicit params.
+- `load({ method: "POST", body })` — mutations.
+- Any `load()` on a `useFetchLoader(loader)` whose loader is **not**
+  registered on the current route. Two unrelated components calling
+  `load()` on the same fetchable-but-unregistered loader keep
+  independent results.
+
+So the search/list pattern still works — two components calling
+`load({ params: { q } })` with different `q` values each keep their
+own result; they do not collapse to last-write-wins through a shared
+store.
+
+**Scoping refetch with a `key`**:
+
+Pass a `key` to partition the shared refresh store. Only hooks using the
+**same** `key` refresh together when one of them calls `load()`. This is a
+client-side refresh identity only — it never changes the request sent to the
+server, and is unrelated to the server `cache({ key })` option and to
+`revalidate()`.
+
+```tsx
+// Two independent dashboards using the same loader. Without a key, one
+// dashboard's load() would flip the other's spinner and value. With a key,
+// they refresh independently.
+function Dashboard({ id }: { id: string }) {
+  const { data, load } = useLoader(StatsLoader, { key: `dashboard:${id}` });
+  return <button onClick={() => load()}>Refresh {data.total}</button>;
+}
+```
+
+The `key` widens sharing in two ways the default cannot:
+
+- **Parameterized GETs share.** `useFetchLoader(SearchLoader, { key: q })`
+  with the same `q` in two components share one result and refresh together —
+  a keyed `load({ params: { q } })` broadcasts to the group instead of staying
+  local. (Mutations — non-GET or `body` — stay local even with a key.)
+- **Unregistered loaders share.** A `key` makes `useFetchLoader` of a loader
+  that is **not** registered on the route share too, letting unrelated
+  components opt into a common refresh group.
+
+Lifecycle: a keyed read of an unregistered loader is reference-counted — its
+shared value lives as long as at least one component using that key is mounted.
+A persistent component (e.g. a header) keeps the value across navigations; a
+route-scoped component's value is reclaimed when it unmounts. Registered-loader
+reads (keyed or not) reset on navigation from fresh route data, as before.
+
+**Refreshing multiple loaders together (`refreshGroup` + `useRefreshLoaders`)**:
+
+`key` groups readers of one loader. To refresh **different** loaders together,
+tag them with a shared `refreshGroup` name and trigger them with
+`useRefreshLoaders()`. The hook takes no argument; you pass the group(s) to the
+function it returns, so one `useRefreshLoaders()` can refresh different groups
+depending on context. A read may carry **several** tags — pass an array — and is
+refreshed when **any** of its groups is refreshed:
+
+```tsx
+function Profile() {
+  const { data } = useLoader(ProfileLoader, {
+    key: userId,
+    refreshGroup: "account",
+  });
+  return <span>{data.name}</span>;
+}
+function Orders() {
+  // Tagged into two groups: refreshed by "account" (the whole set) or the
+  // finer "orders" tag.
+  const { data } = useLoader(OrdersLoader, {
+    key: userId,
+    refreshGroup: ["account", "orders"],
+  });
+  return <span>{data.count} orders</span>;
+}
+function RefreshButtons() {
+  const refresh = useRefreshLoaders();
+  return (
+    <>
+      <button onClick={() => refresh("account")}>Refresh account</button>
+      <button onClick={() => refresh("orders")}>Refresh orders only</button>
+      <button onClick={() => refresh(["account", "orders"])}>
+        Refresh both
+      </button>
+    </>
+  );
+}
+```
+
+`refresh(groups)` accepts one name or an array and re-runs every currently-mounted
+member tagged with **any** of them, with a **plain GET** against the current route
+URL — no params, no body, no mutation methods, because a group spans loaders with
+different shapes. A member that sits in two of the requested groups is fetched
+once (members are unioned and deduped by read). It returns a promise that resolves
+when all members settle and **rejects with an `AggregateError`** if any fail;
+group refresh never render-throws, so handle failures at the await site
+(`await refresh("account").catch(...)`). Each failing member also exposes its
+error via its own read's `error`.
+
+Multiple tags give you granular vs. whole-set refresh from one place: a coarse
+tag (`"account"`) covers everything, while a finer tag (`"orders"`) targets a
+subset. Sharing within a group is opt-in via `key`: members that share a `key`
+share one value (and one fetch); a grouped reader **without** a `key` gets its own
+private bucket, so a group refresh updates only that read and never leaks into
+unrelated unkeyed reads of the same loader. A bucket may belong to several groups
+at once (one read tagged with multiple names, or different reads tagging the same
+keyed bucket with different names). Keep parameterized loaders on the single-loader
+`key` — a plain-GET group refresh sends no params.
+
+**Load options**:
+
+```tsx
+// JSON body — sent as application/json, available as ctx.body on the server
+await load({
+  method: "POST",
+  params: { query: "test" },
+  body: { data: "value" },
+});
+
+// FormData body — sent as multipart/form-data, available as ctx.formData on the server.
+// Automatically detected: when body is a FormData instance, the request switches
+// to multipart/form-data to preserve File objects and binary data.
+const formData = new FormData();
+formData.append("file", fileInput.files[0]);
+await load({ method: "POST", body: formData });
+```
+
+**Body type auto-switching**: The `load()` function inspects the `body` value to
+choose the encoding. If `body instanceof FormData`, the request is sent as
+`multipart/form-data` (browser sets the boundary header automatically). Otherwise
+the body is JSON-serialized and sent with `Content-Type: application/json`. On the
+server, JSON bodies are available via `ctx.body` and FormData bodies via `ctx.formData`.
+
+**File upload example**:
+
+```tsx
+"use client";
+import { useFetchLoader } from "@rangojs/router/client";
+import { FileUploadLoader } from "../loaders/upload";
+
+function FileUploader() {
+  const { data, load, isLoading } = useFetchLoader(FileUploadLoader);
+  const formRef = useRef<HTMLFormElement>(null);
+
+  const handleSubmit = async (formData: FormData) => {
+    await load({ method: "POST", body: formData });
+    formRef.current?.reset();
+  };
+
+  return (
+    <form ref={formRef} action={handleSubmit}>
+      <input type="file" name="file" />
+      <button type="submit" disabled={isLoading}>
+        {isLoading ? "Uploading..." : "Upload"}
+      </button>
+      {data?.uploadedFile && <p>Uploaded: {data.uploadedFile.name}</p>}
+    </form>
+  );
+}
+```
+
+Server-side loader for the upload:
+
+```typescript
+import { createLoader } from "@rangojs/router";
+
+export const FileUploadLoader = createLoader(async (ctx) => {
+  "use server";
+
+  const file = ctx.formData?.get("file") as File | null;
+  if (file && file.size > 0) {
+    // Process file (save to R2, D1, etc.)
+    return { uploadedFile: { name: file.name, size: file.size } };
+  }
+  return { uploadedFile: null };
+}, true); // true = fetchable (can be called from the client via load())
+```

package/skills/hooks/handle-and-actions.md

@@ -0,0 +1,103 @@
+# Handle and Action Hooks
+
+## Handle Hooks
+
+### useHandle()
+
+Access accumulated handle data from route segments:
+
+```tsx
+"use client";
+import { useHandle, Breadcrumbs } from "@rangojs/router/client";
+
+function BreadcrumbNav() {
+  const crumbs = useHandle(Breadcrumbs);
+  // Array of { label, href } accumulated from layouts/routes
+
+  return (
+    <nav>
+      {crumbs.map((c, i) => (
+        <span key={i}>
+          <a href={c.href}>{c.label}</a>
+          {i < crumbs.length - 1 && " > "}
+        </span>
+      ))}
+    </nav>
+  );
+}
+
+// With selector
+const lastCrumb = useHandle(Breadcrumbs, (data) => data.at(-1));
+```
+
+Handles can be passed as props from server to client components:
+
+```tsx
+// Server component
+path("/dashboard", (ctx) => {
+  const push = ctx.use(Breadcrumbs);
+  push({ label: "Dashboard", href: "/dashboard" });
+  return <DashboardNav handle={Breadcrumbs} />;
+});
+```
+
+```tsx
+// Client component — typeof infers the full Handle<T> type
+"use client";
+import { useHandle, type Breadcrumbs } from "@rangojs/router/client";
+
+function DashboardNav({ handle }: { handle: typeof Breadcrumbs }) {
+  const crumbs = useHandle(handle);
+  return (
+    <nav>
+      {crumbs.map((c) => (
+        <a href={c.href}>{c.label}</a>
+      ))}
+    </nav>
+  );
+}
+```
+
+RSC serialization strips the `collect` function via `toJSON()`. On the client,
+`useHandle()` recovers it from the module-level registry (populated when
+`createHandle()` runs during module initialization).
+
+## Action Hooks
+
+For the full server-action guide (defining actions, `useActionState`,
+`useOptimistic`, validation, revalidation, error handling, file uploads),
+see `/server-actions`. `useAction()` below is a Rango-specific hook for
+tracking actions called outside a `<form action={...}>` flow.
+
+### useAction()
+
+Track state of server action invocations:
+
+```tsx
+"use client";
+import { useAction } from "@rangojs/router/client";
+import { addToCart } from "../actions/cart";
+
+function AddToCartButton({ productId }: { productId: string }) {
+  const { state, error, result } = useAction(addToCart);
+
+  // state: 'idle' | 'loading' | 'streaming'
+  // actionId: string | null
+  // payload: unknown | null (input data)
+  // error: Error | null
+  // result: unknown | null (return value)
+
+  return (
+    <form action={addToCart}>
+      <input type="hidden" name="productId" value={productId} />
+      <button disabled={state === "loading"}>
+        {state === "loading" ? "Adding..." : "Add to Cart"}
+      </button>
+      {error && <p className="error">{error.message}</p>}
+    </form>
+  );
+}
+
+// Match by string suffix (convenient but may be ambiguous)
+const isLoading = useAction("addToCart", (s) => s.state === "loading");
+```

package/skills/hooks/navigation.md

@@ -0,0 +1,110 @@
+# Navigation Hooks
+
+### useNavigation()
+
+Track reactive navigation state (state-only, no actions):
+
+```tsx
+"use client";
+import { useNavigation } from "@rangojs/router/client";
+
+function NavIndicator() {
+  const nav = useNavigation();
+
+  // State properties
+  nav.state; // 'idle' | 'loading'
+  nav.isStreaming; // boolean
+  nav.location; // Current URL
+  nav.pendingUrl; // Target URL during navigation (or null)
+
+  return nav.state === "loading" ? <Spinner /> : null;
+}
+
+// With selector for performance (re-renders only when selected value changes)
+function IsLoading() {
+  const isLoading = useNavigation((nav) => nav.state === "loading");
+  return isLoading ? <Spinner /> : null;
+}
+```
+
+### useRouter()
+
+Access stable router actions (never causes re-renders):
+
+```tsx
+"use client";
+import { useRouter } from "@rangojs/router/client";
+
+function NavigationControls() {
+  const router = useRouter();
+
+  router.push("/products"); // Navigate (adds history entry)
+  router.replace("/login"); // Navigate (replaces history entry)
+  router.refresh(); // Re-fetch current route data
+  router.prefetch("/dashboard"); // Prefetch for faster navigation
+  router.back(); // Go back in history
+  router.forward(); // Go forward in history
+}
+```
+
+#### Skipping revalidation
+
+Pass `revalidate: false` to skip the RSC server fetch for same-pathname navigations (search param or hash changes). The URL updates and all hooks re-render, but server components stay as-is.
+
+```tsx
+// Update search params without server round-trip
+router.push("/products?color=blue", { revalidate: false });
+router.replace("/products?page=3", { revalidate: false });
+```
+
+If the pathname changes, `revalidate: false` is silently ignored and a full navigation occurs. This also works on `<Link>`:
+
+```tsx
+<Link to="/products?color=blue" revalidate={false}>
+  Blue
+</Link>
+```
+
+Plain `<a>` tags can opt in via `data-revalidate="false"`.
+
+### useSegments()
+
+Access current URL path and matched route segments:
+
+```tsx
+"use client";
+import { useSegments } from "@rangojs/router/client";
+
+function Breadcrumbs() {
+  const { path, segmentIds, location } = useSegments();
+
+  // path: ["shop", "products", "123"] (split on "/", no leading slash on any element)
+  // segmentIds: ["L0", "L0L1", "L0L1R0"] (opaque internal short-codes, not route names)
+  // location: URL object
+
+  return <nav>{path.join(" > ")}</nav>;
+}
+
+// With selector
+const isShopRoute = useSegments((s) => s.path[0] === "shop");
+```
+
+### useLinkStatus()
+
+Track pending state inside a Link component:
+
+```tsx
+"use client";
+import { Link, useLinkStatus } from "@rangojs/router/client";
+
+function LoadingIndicator() {
+  const { pending } = useLinkStatus();
+  return pending ? <Spinner /> : null;
+}
+
+// Must be inside Link
+<Link to="/dashboard">
+  Dashboard
+  <LoadingIndicator />
+</Link>;
+```

package/skills/hooks/outlets.md

@@ -0,0 +1,62 @@
+# Outlet Components
+
+### Outlet / ParallelOutlet
+
+Render child content in layouts:
+
+```tsx
+import { Outlet, ParallelOutlet } from "@rangojs/router/client";
+
+function DashboardLayout({ children }: { children?: React.ReactNode }) {
+  return (
+    <div className="dashboard">
+      <aside>
+        <ParallelOutlet name="@sidebar" />
+      </aside>
+      <main>{children ?? <Outlet />}</main>
+      <ParallelOutlet name="@notifications" />
+    </div>
+  );
+}
+```
+
+### useOutlet()
+
+Access outlet content and its client-route presentation state programmatically:
+
+```ts
+interface OutletState {
+  readonly content: ReactNode;
+  readonly pending: boolean;
+}
+```
+
+```tsx
+"use client";
+import { useOutlet } from "@rangojs/router/client";
+
+function ConditionalLayout() {
+  const { content, pending } = useOutlet();
+
+  return content ? (
+    <div className="with-content" aria-busy={pending}>
+      {content}
+    </div>
+  ) : (
+    <div className="empty">No content</div>
+  );
+}
+```
+
+Migration from the old bare-node return is `const { content, pending } =
+useOutlet()`, then render `content` where you previously rendered the hook result.
+`<Outlet />` itself is unchanged.
+
+`pending` is narrow. After hydration, a `clientUrls()` layout receives `true`
+while a browser-local match to a different client route beneath it is presenting
+optimistic loading or retaining the current branch until canonical partial Flight
+settles. It clears on commit, error, redirect, cancellation, or supersession. It
+is `false` during SSR and does not describe ordinary server-route navigation,
+prefetch, generic Suspense, unrelated actions, or a params/search change that
+keeps the same client route record. Use `useNavigation()`, `useLinkStatus()`, or
+loader state for those scopes.