@funstack/router 0.0.10 → 1.1.0

package/dist/docs/LearnActionsPage.tsx

@@ -0,0 +1,228 @@
+import { CodeBlock } from "../components/CodeBlock.js";
+
+export function LearnActionsPage() {
+  return (
+    <div className="learn-content">
+      <h2>Form Actions</h2>
+
+      <p className="page-intro">
+        FUNSTACK Router can intercept <code>{"<form>"}</code> submissions and
+        run an <strong>action</strong> function on the client before navigation
+        occurs. This guide explains how actions work, when to use them, and
+        important considerations for progressive enhancement.
+      </p>
+
+      <div className="callout warning">
+        <p className="callout-title">Important: Progressive Enhancement</p>
+        <p>
+          A <code>{'<form method="post">'}</code> should work even{" "}
+          <strong>before JavaScript has loaded</strong>. The browser natively
+          submits POST forms to the server, so your server must be prepared to
+          handle these requests. The router&rsquo;s <code>action</code> function
+          is a <strong>client-side shortcut</strong> that runs only after
+          hydration &mdash; it does not replace server-side form handling.
+        </p>
+        <p>
+          If your server cannot handle the POST request, users on slow
+          connections, users with JavaScript disabled, or users who submit the
+          form before hydration completes will experience a broken form. Always
+          ensure your server handles POST submissions for the same URL as a
+          baseline.
+        </p>
+      </div>
+
+      <section>
+        <h3>How It Works</h3>
+        <p>
+          When a <code>{'<form method="post">'}</code> is submitted, the router
+          matches the form&rsquo;s destination URL against the route
+          definitions. If a matched route defines an <code>action</code>, the
+          router intercepts the submission via the Navigation API instead of
+          letting the browser send it to the server. The flow is:
+        </p>
+        <ol>
+          <li>
+            User submits a form with <code>method="post"</code>
+          </li>
+          <li>
+            The Navigation API fires a <code>navigate</code> event with{" "}
+            <code>formData</code>
+          </li>
+          <li>
+            The router finds the deepest matched route that has an{" "}
+            <code>action</code>
+          </li>
+          <li>
+            The <code>action</code> function runs with the form data wrapped in
+            a <code>Request</code>
+          </li>
+          <li>
+            The action&rsquo;s return value is passed to the route&rsquo;s{" "}
+            <code>loader</code> as <code>actionResult</code>
+          </li>
+          <li>The loader runs and the UI updates with fresh data</li>
+        </ol>
+        <p>
+          If the matched route does <strong>not</strong> define an action, the
+          router does not intercept the submission and the browser sends it to
+          the server as a normal POST request.
+        </p>
+      </section>
+
+      <section>
+        <h3>Defining an Action</h3>
+        <p>
+          Add an <code>action</code> function to your route definition. It
+          receives an <code>ActionArgs</code> object with the route params, a{" "}
+          <code>Request</code>, and an <code>AbortSignal</code>:
+        </p>
+        <CodeBlock language="tsx">{`import { route } from "@funstack/router";
+
+const editRoute = route({
+  path: "/posts/:postId/edit",
+  action: async ({ params, request, signal }) => {
+    const formData = await request.formData();
+    const title = formData.get("title") as string;
+    const body = formData.get("body") as string;
+
+    const res = await fetch(\`/api/posts/\${params.postId}\`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ title, body }),
+      signal,
+    });
+    return res.json();
+  },
+  loader: async ({ params, actionResult, signal }) => {
+    // After a successful action, actionResult contains
+    // the return value. On normal navigations it is undefined.
+    const res = await fetch(\`/api/posts/\${params.postId}\`, { signal });
+    return res.json();
+  },
+  component: EditPostPage,
+});`}</CodeBlock>
+      </section>
+
+      <section>
+        <h3>The Form</h3>
+        <p>
+          Use a standard HTML <code>{"<form>"}</code> element with{" "}
+          <code>method="post"</code>. There is no special form component needed
+          &mdash; the router hooks into the Navigation API which intercepts
+          native form submissions:
+        </p>
+        <CodeBlock language="tsx">{`function EditPostPage({ data, params }: EditPostProps) {
+  return (
+    <form method="post" action={\`/posts/\${params.postId}/edit\`}>
+      <input name="title" defaultValue={data.title} />
+      <textarea name="body" defaultValue={data.body} />
+      <button type="submit">Save</button>
+    </form>
+  );
+}`}</CodeBlock>
+        <p>
+          Note that the form&rsquo;s <code>action</code> attribute points to the
+          same URL that the route matches. This is essential for progressive
+          enhancement: before hydration, the browser will POST to this URL on
+          the server.
+        </p>
+      </section>
+
+      <section>
+        <h3>Progressive Enhancement in Detail</h3>
+        <p>
+          The action feature is designed as an{" "}
+          <strong>enhancement layer</strong>. The baseline behavior of a POST
+          form is a server round-trip, and the router&rsquo;s action provides a
+          faster, client-side alternative once hydration is complete. This
+          means:
+        </p>
+        <ul>
+          <li>
+            <strong>Before hydration</strong> &mdash; The browser submits the
+            form to the server as a normal POST request. Your server must handle
+            it and return an appropriate response (typically a redirect or a
+            re-rendered page).
+          </li>
+          <li>
+            <strong>After hydration</strong> &mdash; The router intercepts the
+            submission, runs your <code>action</code> function on the client,
+            and updates the UI without a full page reload.
+          </li>
+        </ul>
+        <p>
+          Both paths should produce the same end result for the user. The client
+          action is a shortcut, not a replacement.
+        </p>
+
+        <div className="callout warning">
+          <p className="callout-title">
+            When your server cannot handle POST requests
+          </p>
+          <p>
+            If you are building a purely client-side application (e.g. a SPA
+            with no server-side form handling), consider using React 19&rsquo;s{" "}
+            <code>{"<form action={fn}>"}</code> pattern instead. When a form
+            action is a <strong>function</strong> rather than a URL, the browser
+            will not attempt a server round-trip on submission. Note that in a
+            client-only app the form will not work until React hydrates, since
+            the function only exists in the JavaScript bundle.
+          </p>
+          <p>
+            In contrast, FUNSTACK Router&rsquo;s <code>action</code> intercepts
+            URL-based form submissions. If the client has not hydrated yet, the
+            browser will POST to the URL, which will fail without server
+            handling.
+          </p>
+        </div>
+      </section>
+
+      <section>
+        <h3>Action Result and Loader</h3>
+        <p>
+          When a route defines both an <code>action</code> and a{" "}
+          <code>loader</code>, the loader runs after the action completes. The
+          action&rsquo;s return value is passed to the loader via the{" "}
+          <code>actionResult</code> parameter:
+        </p>
+        <CodeBlock language="typescript">{`action: async ({ request }) => {
+  const formData = await request.formData();
+  // ... process form
+  return { success: true, message: "Saved!" };
+},
+loader: async ({ params, actionResult, signal }) => {
+  // actionResult is { success: true, message: "Saved!" }
+  // after the action, or undefined on normal navigation
+  const data = await fetchData(params.id, signal);
+  return { ...data, actionResult };
+},`}</CodeBlock>
+        <p>
+          This lets your UI display feedback from the action (e.g. success
+          messages or validation errors) alongside the refreshed data.
+        </p>
+      </section>
+
+      <section>
+        <h3>Summary</h3>
+        <ul>
+          <li>
+            <code>action</code> intercepts POST form submissions on the client
+            after hydration
+          </li>
+          <li>
+            Your server must handle the same POST endpoint for progressive
+            enhancement
+          </li>
+          <li>
+            The action&rsquo;s return value flows to the loader as{" "}
+            <code>actionResult</code>
+          </li>
+          <li>
+            For SPAs without server-side form handling, prefer React 19&rsquo;s{" "}
+            <code>{"<form action={fn}>"}</code> pattern
+          </li>
+        </ul>
+      </section>
+    </div>
+  );
+}

package/dist/docs/LearnLoadersPage.tsx

@@ -0,0 +1,320 @@
+import { CodeBlock } from "../components/CodeBlock.js";
+
+export function LearnLoadersPage() {
+  return (
+    <div className="learn-content">
+      <h2>How Loaders Run</h2>
+
+      <p className="page-intro">
+        Loaders fetch data for a route before the UI renders. This page explains
+        when loaders execute, how results are cached, and how different types of
+        navigation affect loader behavior.
+      </p>
+
+      <section>
+        <h3>Defining a Loader</h3>
+        <p>
+          A loader is a function on a route definition that receives the route
+          params, a <code>Request</code>, and an <code>AbortSignal</code>. It
+          can return any value &mdash; typically a Promise from a fetch call:
+        </p>
+        <CodeBlock language="tsx">{`import { route } from "@funstack/router";
+
+const userRoute = route({
+  path: "/users/:id",
+  loader: async ({ params, request, signal }) => {
+    const res = await fetch(\`/api/users/\${params.id}\`, { signal });
+    return res.json();
+  },
+  component: UserPage,
+});`}</CodeBlock>
+        <p>
+          The component receives the loader&rsquo;s return value as the{" "}
+          <code>data</code> prop. For async loaders this is a{" "}
+          <code>Promise</code>, which you unwrap with React&rsquo;s{" "}
+          <code>use()</code> hook inside a <code>Suspense</code> boundary:
+        </p>
+        <CodeBlock language="tsx">{`import { use, Suspense } from "react";
+
+function UserPage({ data }: { data: Promise<User> }) {
+  return (
+    <Suspense fallback={<p>Loading...</p>}>
+      <UserDetail data={data} />
+    </Suspense>
+  );
+}
+
+function UserDetail({ data }: { data: Promise<User> }) {
+  const user = use(data);
+  return <h1>{user.name}</h1>;
+}`}</CodeBlock>
+      </section>
+
+      <section>
+        <h3>When Loaders Execute</h3>
+        <p>Loaders run at two points in the lifecycle:</p>
+        <ol>
+          <li>
+            <strong>Initial page load</strong> &mdash; When the Router first
+            renders, it matches the current URL against the route definitions
+            and executes all matching loaders immediately.
+          </li>
+          <li>
+            <strong>Navigation events</strong> &mdash; When the user navigates
+            (by clicking a link, submitting a form, or calling{" "}
+            <code>navigate()</code>), the Router matches the destination URL and
+            executes loaders for the matched routes.
+          </li>
+        </ol>
+        <p>
+          In both cases, all loaders in the matched route stack (parent and
+          child) run <strong>in parallel</strong>. The navigation completes once
+          every loader&rsquo;s Promise has resolved.
+        </p>
+      </section>
+
+      <section>
+        <h3>Caching by Navigation Entry</h3>
+        <p>
+          Loader results are cached using the{" "}
+          <strong>navigation entry ID</strong> from the Navigation API. Each
+          time you navigate to a new URL, the browser creates a new navigation
+          entry with a unique ID. The Router uses this ID as the cache key, so:
+        </p>
+        <ul>
+          <li>
+            Re-renders of the same page <strong>do not</strong> re-execute
+            loaders &mdash; the cached result is returned.
+          </li>
+          <li>
+            Navigating to a new URL always creates a new entry and{" "}
+            <strong>always</strong> executes loaders, even if the URL is the
+            same as a previous navigation.
+          </li>
+        </ul>
+        <p>
+          This design ensures that loaders run exactly once per navigation while
+          preventing unnecessary re-fetches during React re-renders.
+        </p>
+      </section>
+
+      <section>
+        <h3>Navigation Types and Loader Behavior</h3>
+        <p>
+          Different types of navigation have different effects on whether
+          loaders run:
+        </p>
+
+        <h4>Push and Replace</h4>
+        <p>
+          A <strong>push</strong> navigation (the default when clicking a link
+          or calling <code>navigate()</code>) creates a new navigation entry.
+          Since the entry is new, loaders always execute. A{" "}
+          <strong>replace</strong> navigation behaves the same way &mdash; it
+          creates a new entry that replaces the current one, so loaders execute
+          fresh.
+        </p>
+
+        <h4>Traverse (Back / Forward)</h4>
+        <p>
+          When the user goes back or forward in history, the browser revisits an{" "}
+          <strong>existing</strong> navigation entry. Because the entry ID is
+          the same as when the page was originally visited, the cached loader
+          results are returned <strong>without re-executing</strong> the
+          loaders. This makes back/forward navigation instant.
+        </p>
+
+        <h4>Reload</h4>
+        <p>
+          A reload navigation stays on the same navigation entry, but the Router
+          generates a <strong>fresh cache key</strong> so that all loaders{" "}
+          <strong>re-execute</strong>. This is useful when you want to refresh
+          data without navigating away from the current page.
+        </p>
+        <p>
+          You can trigger a reload programmatically using the Navigation
+          API&rsquo;s <code>navigation.reload()</code> method:
+        </p>
+        <CodeBlock language="tsx">{`function RefreshButton() {
+  return (
+    <button onClick={() => navigation.reload()}>
+      Refresh Data
+    </button>
+  );
+}`}</CodeBlock>
+        <p>
+          During a reload, the old cached data remains available for the{" "}
+          <strong>pending UI</strong>. Because the Router wraps navigations in a
+          React transition, the previous UI stays on screen while the new data
+          loads. Once the new loaders resolve, the UI updates. This means users
+          see the existing content while the refresh is in progress, rather than
+          a blank screen or loading spinner.
+        </p>
+        <p>
+          Consecutive reloads work correctly &mdash; each reload increments an
+          internal counter to produce a unique cache key, and stale caches are
+          pruned automatically.
+        </p>
+
+        <h4>Form Submissions</h4>
+        <p>
+          When a <code>{'<form method="post">'}</code> is submitted, the Router
+          runs the matched route&rsquo;s <code>action</code> first, then clears
+          the loader cache for the current entry and re-executes all loaders.
+          The action&rsquo;s return value is passed to each loader as{" "}
+          <code>actionResult</code>. See the{" "}
+          <a href="/learn/actions">Form Actions</a> page for details.
+        </p>
+      </section>
+
+      <section>
+        <h3>Nested Route Loaders</h3>
+        <p>
+          When routes are nested, each route in the matched stack can define its
+          own loader. All loaders in the stack execute in parallel, and each
+          component receives its own loader&rsquo;s result:
+        </p>
+        <CodeBlock language="tsx">{`const routes = [
+  route({
+    path: "/dashboard",
+    loader: () => fetchDashboardLayout(),
+    component: DashboardLayout,
+    children: [
+      route({
+        path: "/stats",
+        loader: () => fetchStats(),
+        component: StatsPage,
+      }),
+    ],
+  }),
+];
+
+// When navigating to /dashboard/stats:
+// → fetchDashboardLayout() and fetchStats() run in parallel
+// → DashboardLayout receives the layout data
+// → StatsPage receives the stats data`}</CodeBlock>
+        <p>
+          On reload, <strong>all</strong> loaders in the matched stack
+          re-execute, not just the deepest one.
+        </p>
+      </section>
+
+      <section>
+        <h3>Cache Cleanup</h3>
+        <p>
+          Cached loader results are automatically cleaned up when a navigation
+          entry is <strong>disposed</strong>. The browser disposes entries when
+          they are removed from the history stack (for example, when the user
+          navigates forward from a point in the middle of the history stack, the
+          entries ahead are discarded). The Router listens for these dispose
+          events and removes the corresponding cached data.
+        </p>
+      </section>
+
+      <section>
+        <h3>Error Handling</h3>
+        <p>
+          When a loader throws an error, the router catches it and re-throws it
+          during rendering of that route&rsquo;s component. This means the error
+          can be caught by a React{" "}
+          <a href="https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary">
+            Error Boundary
+          </a>{" "}
+          placed above the route in the component tree. For async loaders that
+          return a rejected promise, the error is surfaced when{" "}
+          <code>use(data)</code> is called, which is also caught by Error
+          Boundaries.
+        </p>
+        <p>
+          The recommended pattern is to place an error boundary in your{" "}
+          <strong>root layout route</strong>, wrapping the{" "}
+          <code>{"<Outlet />"}</code>. This catches errors from any loader in
+          the route tree while keeping the root layout (header, navigation,
+          etc.) intact:
+        </p>
+        <CodeBlock language="tsx">{`import { Router, route, Outlet } from "@funstack/router";
+import { ErrorBoundary } from "./ErrorBoundary";
+
+function RootLayout() {
+  return (
+    <div>
+      <header>My App</header>
+      <ErrorBoundary fallback={<div>Something went wrong.</div>}>
+        <Outlet />
+      </ErrorBoundary>
+    </div>
+  );
+}
+
+const routes = [
+  route({
+    path: "/",
+    component: RootLayout,
+    children: [
+      route({
+        path: "/",
+        component: HomePage,
+      }),
+      route({
+        path: "/users/:id",
+        component: UserPage,
+        loader: async ({ params }) => {
+          const res = await fetch(\`/api/users/\${params.id}\`);
+          if (!res.ok) throw new Error("Failed to load user");
+          return res.json();
+        },
+      }),
+    ],
+  }),
+];`}</CodeBlock>
+        <p>
+          This works for both synchronous and asynchronous loaders. For sync
+          loaders, the router catches the error and re-throws it during route
+          rendering. For async loaders, the rejected promise naturally surfaces
+          through <code>use()</code>. Either way, Error Boundaries catch the
+          error.
+        </p>
+        <p>
+          You can also place error boundaries at more granular levels (e.g.,
+          wrapping a specific route&rsquo;s <code>{"<Outlet />"}</code> or{" "}
+          <code>{"<Suspense>"}</code> boundary) for fine-grained error handling.
+        </p>
+      </section>
+
+      <section>
+        <h3>Summary</h3>
+        <table className="summary-table">
+          <thead>
+            <tr>
+              <th>Navigation type</th>
+              <th>Loaders run?</th>
+              <th>Why</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>Push / Replace</td>
+              <td>Yes</td>
+              <td>New navigation entry, no cache</td>
+            </tr>
+            <tr>
+              <td>Traverse (Back / Forward)</td>
+              <td>No</td>
+              <td>Existing entry, cached results returned</td>
+            </tr>
+            <tr>
+              <td>Reload</td>
+              <td>Yes</td>
+              <td>Fresh cache key generated</td>
+            </tr>
+            <tr>
+              <td>Form submission (POST)</td>
+              <td>Yes</td>
+              <td>Cache cleared after action runs</td>
+            </tr>
+          </tbody>
+        </table>
+      </section>
+    </div>
+  );
+}

package/dist/docs/LearnNavigationApiPage.tsx

@@ -210,7 +210,7 @@ function App() {
               Ephemeral <code>info</code>
             </strong>{" "}
             &mdash; Pass non-persisted context data during navigation via{" "}
-            <code>navigation.navigate(url, {"{ info }"}))</code>
+            <code>navigation.navigate(url, {"{ info }"})</code>
           </li>
           <li>
             <strong>navigation.entries()</strong> &mdash; Access the full