@funstack/router 0.0.7 → 0.0.9

package/dist/docs/ApiComponentsPage.tsx

@@ -55,6 +55,39 @@ export function ApiComponentsPage() {
                 the router will intercept the navigation.
               </td>
             </tr>
+            <tr>
+              <td>
+                <code>fallback</code>
+              </td>
+              <td>
+                <code>{'"none" | "static"'}</code>
+              </td>
+              <td>
+                Fallback mode when Navigation API is unavailable.{" "}
+                <code>"none"</code> (default) renders nothing;{" "}
+                <code>"static"</code> renders matched routes using{" "}
+                <code>window.location</code> without navigation interception
+                (MPA behavior).
+              </td>
+            </tr>
+            <tr>
+              <td>
+                <code>ssr</code>
+              </td>
+              <td>
+                <code>SSRConfig</code>
+              </td>
+              <td>
+                SSR configuration for route matching during server-side
+                rendering. Accepts an object with <code>path</code> (the
+                pathname to match against) and an optional{" "}
+                <code>runLoaders</code> boolean (defaults to <code>false</code>
+                ). When <code>runLoaders</code> is <code>false</code>, routes
+                with loaders are skipped during SSR. Once the client hydrates,
+                the real URL from the Navigation API takes over. See the{" "}
+                <a href="/learn/ssr">SSR guide</a> for details.
+              </td>
+            </tr>
           </tbody>
         </table>
       </article>

package/dist/docs/ApiHooksPage.tsx

@@ -163,9 +163,14 @@ function MyComponent() {
         <ul>
           <li>
             This hook is powered by React's <code>useTransition</code>. The
-            router wraps navigation state updates in{" "}
-            <code>startTransition</code>, so React defers rendering suspended
-            routes and keeps the current UI visible.
+            router wraps navigations in <code>startTransition</code>, so React
+            defers rendering suspended routes and keeps the current UI visible.
+          </li>
+          <li>
+            Sync state updates via <code>setStateSync</code> and{" "}
+            <code>resetStateSync</code> bypass transitions entirely, so{" "}
+            <code>isPending</code> will <strong>not</strong> become{" "}
+            <code>true</code> for those updates.
           </li>
           <li>
             The same <code>isPending</code> value is also available as a prop on

package/dist/docs/ApiTypesPage.tsx

@@ -37,7 +37,10 @@ type Props = {
     state: { scrollPosition: number } |
            ((prev: { scrollPosition: number } | undefined) => { scrollPosition: number })
   ) => void;
-  resetState: () => void;
+  // Async reset via replace navigation
+  resetState: () => Promise<void>;
+  // Sync reset via updateCurrentEntry
+  resetStateSync: () => void;
   info: unknown; // Ephemeral navigation info
   isPending: boolean; // Whether a navigation transition is pending
 };`}</CodeBlock>
@@ -48,11 +51,27 @@ type Props = {
           <li>
             <code>setState</code> - Async method that returns a Promise. Uses
             replace navigation internally, ensuring the state update goes
-            through the full navigation cycle.
+            through the full navigation cycle. Because it performs a navigation,
+            it is wrapped in a React transition and may set{" "}
+            <code>isPending</code> to <code>true</code>.
           </li>
           <li>
             <code>setStateSync</code> - Synchronous method that updates state
-            immediately using <code>navigation.updateCurrentEntry()</code>.
+            immediately using <code>navigation.updateCurrentEntry()</code>. This
+            is <strong>not</strong> a navigation, so it bypasses React
+            transitions and will never set <code>isPending</code> to{" "}
+            <code>true</code>.
+          </li>
+          <li>
+            <code>resetState</code> - Async method that clears navigation state
+            via replace navigation. Like <code>setState</code>, it goes through
+            a React transition and may set <code>isPending</code> to{" "}
+            <code>true</code>.
+          </li>
+          <li>
+            <code>resetStateSync</code> - Clears navigation state synchronously.
+            Like <code>setStateSync</code>, this bypasses React transitions and
+            will never set <code>isPending</code> to <code>true</code>.
           </li>
         </ul>
       </article>
@@ -80,7 +99,8 @@ type Props = {
   state: { selectedTab: string } | undefined;
   setState: (state: ...) => Promise<void>;  // async
   setStateSync: (state: ...) => void;       // sync
-  resetState: () => void;
+  resetState: () => Promise<void>;          // async
+  resetStateSync: () => void;               // sync
   info: unknown; // Ephemeral navigation info
   isPending: boolean; // Whether a navigation transition is pending
 };`}</CodeBlock>
@@ -238,8 +258,9 @@ type SettingsPageProps = RouteComponentPropsOf<typeof settingsRoute>;
             <code>component: UserPage</code>): Router automatically injects
             props (<code>params</code>, <code>state</code>,{" "}
             <code>setState</code>, <code>setStateSync</code>,{" "}
-            <code>resetState</code>, <code>info</code>, <code>isPending</code>,
-            and <code>data</code> when a loader is defined).
+            <code>resetState</code>, <code>resetStateSync</code>,{" "}
+            <code>info</code>, <code>isPending</code>, and <code>data</code>{" "}
+            when a loader is defined).
           </li>
           <li>
             <strong>JSX element</strong> (e.g.,{" "}
@@ -268,15 +289,42 @@ routeState<{ tab: string }>()({
 });`}</CodeBlock>
       </article>
 
+      <article className="api-item">
+        <h3>
+          <code>ActionArgs</code>
+        </h3>
+        <p>
+          Arguments passed to route action functions. The <code>request</code>{" "}
+          carries the POST method and <code>FormData</code> body from the form
+          submission.
+        </p>
+        <CodeBlock language="typescript">{`interface ActionArgs<Params> {
+  params: Params;
+  request: Request;  // method: "POST", body: FormData
+  signal: AbortSignal;
+}`}</CodeBlock>
+      </article>
+
       <article className="api-item">
         <h3>
           <code>LoaderArgs</code>
         </h3>
-        <CodeBlock language="typescript">{`interface LoaderArgs {
-  params: Record<string, string>;
+        <p>
+          Arguments passed to route loader functions. The optional{" "}
+          <code>actionResult</code> parameter contains the return value of the
+          route's action when the loader runs after a form submission.
+        </p>
+        <CodeBlock language="typescript">{`interface LoaderArgs<Params, ActionResult = undefined> {
+  params: Params;
   request: Request;
   signal: AbortSignal;
+  actionResult: ActionResult | undefined;
 }`}</CodeBlock>
+        <p>
+          On normal navigations, <code>actionResult</code> is{" "}
+          <code>undefined</code>. After a form submission, it contains the
+          action's return value (awaited if the action is async).
+        </p>
       </article>
 
       <article className="api-item">

package/dist/docs/ApiUtilitiesPage.tsx

@@ -17,8 +17,9 @@ export function ApiUtilitiesPage() {
           always receives a <code>params</code> prop with types inferred from
           the path pattern. When a <code>loader</code> is defined, the component
           also receives a <code>data</code> prop. Components also receive{" "}
-          <code>state</code>, <code>setState</code>, <code>setStateSync</code>,
-          and <code>resetState</code> props for navigation state management.
+          <code>state</code>, <code>setState</code>, <code>setStateSync</code>,{" "}
+          <code>resetState</code>, and <code>resetStateSync</code> props for
+          navigation state management.
         </p>
         <CodeBlock language="tsx">{`import { route } from "@funstack/router";
 
@@ -84,6 +85,20 @@ const myRoute = route({
                 (and <code>data</code> prop if loader is defined)
               </td>
             </tr>
+            <tr>
+              <td>
+                <code>action</code>
+              </td>
+              <td>
+                <code>(args: ActionArgs) =&gt; T</code>
+              </td>
+              <td>
+                Function to handle form submissions (POST navigations). Receives
+                a <code>Request</code> with <code>FormData</code> body. The
+                return value is passed to the loader as{" "}
+                <code>actionResult</code>.
+              </td>
+            </tr>
             <tr>
               <td>
                 <code>loader</code>
@@ -204,11 +219,15 @@ const productRoute = routeState<{ filter: string }>()({
           <li>
             <code>setState</code> - Async method that uses replace navigation.
             Returns a Promise that resolves when the navigation completes.
+            Because it performs a navigation, the update is wrapped in a React
+            transition (may set <code>isPending</code> to <code>true</code>).
           </li>
           <li>
             <code>setStateSync</code> - Sync method that uses{" "}
             <code>navigation.updateCurrentEntry()</code>. Updates state
-            immediately without waiting.
+            immediately without waiting. This is not a navigation, so it
+            bypasses React transitions entirely (<code>isPending</code> stays{" "}
+            <code>false</code>).
           </li>
         </ul>
         <p>Navigation state characteristics:</p>
@@ -276,8 +295,9 @@ const routes = [
             <code>routeState</code> - Route definition helper with typed state
           </li>
           <li>
-            Types: <code>LoaderArgs</code>, <code>RouteDefinition</code>,{" "}
-            <code>PathParams</code>, <code>RouteComponentProps</code>,{" "}
+            Types: <code>ActionArgs</code>, <code>LoaderArgs</code>,{" "}
+            <code>RouteDefinition</code>, <code>PathParams</code>,{" "}
+            <code>RouteComponentProps</code>,{" "}
             <code>RouteComponentPropsWithData</code>
           </li>
         </ul>
@@ -287,9 +307,7 @@ const routes = [
         </p>
         <p>
           See the{" "}
-          <a href="/funstack-router/learn/react-server-components">
-            React Server Components
-          </a>{" "}
+          <a href="/learn/react-server-components">React Server Components</a>{" "}
           guide for a full walkthrough of using the server entry point.
         </p>
       </article>

package/dist/docs/ExamplesPage.tsx

@@ -0,0 +1,445 @@
+import { CodeBlock } from "../components/CodeBlock.js";
+
+export function ExamplesPage() {
+  return (
+    <div className="page docs-page">
+      <h1>Examples</h1>
+
+      <section>
+        <h2>Basic Routing</h2>
+        <p>A simple example with home and about pages:</p>
+        <CodeBlock language="tsx">{`import { Router, route, Outlet, useNavigate } from "@funstack/router";
+
+function Home() {
+  return <h1>Home Page</h1>;
+}
+
+function About() {
+  return <h1>About Page</h1>;
+}
+
+function Layout() {
+  const navigate = useNavigate();
+
+  return (
+    <div>
+      <nav>
+        <button onClick={() => navigate("/")}>Home</button>
+        <button onClick={() => navigate("/about")}>About</button>
+      </nav>
+      <Outlet />
+    </div>
+  );
+}
+
+const routes = [
+  route({
+    path: "/",
+    component: Layout,
+    children: [
+      route({ path: "/", component: Home }),
+      route({ path: "/about", component: About }),
+    ],
+  }),
+];
+
+function App() {
+  return <Router routes={routes} />;
+}`}</CodeBlock>
+      </section>
+
+      <section>
+        <h2>Dynamic Routes with Params</h2>
+        <p>
+          Handle dynamic URL segments with parameters. Components receive params
+          via props:
+        </p>
+        <CodeBlock language="tsx">{`import { route } from "@funstack/router";
+
+function UserProfile({ params }: { params: { userId: string } }) {
+  return <h1>Viewing user: {params.userId}</h1>;
+}
+
+function PostDetail({
+  params,
+}: {
+  params: { userId: string; postId: string };
+}) {
+  return (
+    <div>
+      <h1>Post {params.postId}</h1>
+      <p>By user {params.userId}</p>
+    </div>
+  );
+}
+
+const routes = [
+  route({
+    path: "/users/:userId",
+    component: UserProfile,
+  }),
+  route({
+    path: "/users/:userId/posts/:postId",
+    component: PostDetail,
+  }),
+];`}</CodeBlock>
+      </section>
+
+      <section>
+        <h2>Nested Routes</h2>
+        <p>Create complex layouts with nested routing:</p>
+        <CodeBlock language="tsx">{`import { route, Outlet } from "@funstack/router";
+
+function Dashboard() {
+  return (
+    <div className="dashboard">
+      <aside>
+        <nav>Dashboard Menu</nav>
+      </aside>
+      <main>
+        <Outlet />
+      </main>
+    </div>
+  );
+}
+
+function DashboardHome() {
+  return <h2>Dashboard Overview</h2>;
+}
+
+function DashboardSettings() {
+  return <h2>Settings</h2>;
+}
+
+function DashboardProfile() {
+  return <h2>Your Profile</h2>;
+}
+
+const dashboardRoutes = route({
+  path: "/dashboard",
+  component: Dashboard,
+  children: [
+    route({ path: "/", component: DashboardHome }),
+    route({ path: "/settings", component: DashboardSettings }),
+    route({ path: "/profile", component: DashboardProfile }),
+  ],
+});`}</CodeBlock>
+      </section>
+
+      <section>
+        <h2>Data Loading</h2>
+        <p>
+          Load data with loaders. When a loader returns a Promise, the component
+          receives that Promise and uses React's <code>use</code> hook to unwrap
+          it. Use <code>&lt;Suspense&gt;</code> within your pages or layouts to
+          handle loading states.
+        </p>
+        <CodeBlock language="tsx">{`import { use, Suspense } from "react";
+import { route } from "@funstack/router";
+
+interface Post {
+  id: number;
+  title: string;
+  body: string;
+  userId: number;
+}
+
+// When the loader returns a Promise, the component receives that Promise.
+// Use React's \`use\` hook to unwrap the Promise.
+function UserPostsContent({
+  data,
+  params,
+}: {
+  data: Promise<Post[]>;
+  params: { userId: string };
+}) {
+  const posts = use(data);
+  return (
+    <div>
+      <h2>Posts by user {params.userId}</h2>
+      <ul>
+        {posts.map((post) => (
+          <li key={post.id}>{post.title}</li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+// Wrap the content with Suspense at the page level
+function UserPosts(props: {
+  data: Promise<Post[]>;
+  params: { userId: string };
+}) {
+  return (
+    <Suspense fallback={<div>Loading posts...</div>}>
+      <UserPostsContent {...props} />
+    </Suspense>
+  );
+}
+
+const userPostsRoute = route({
+  path: "/users/:userId/posts",
+  component: UserPosts,
+  loader: async ({ params }): Promise<Post[]> => {
+    const response = await fetch(
+      \`https://jsonplaceholder.typicode.com/posts?userId=\${params.userId}\`
+    );
+    return response.json();
+  },
+});`}</CodeBlock>
+      </section>
+
+      <section>
+        <h2>Form Submissions</h2>
+        <p>
+          Handle form POST submissions with route actions. The action receives
+          the form data, and its return value flows to the loader via{" "}
+          <code>actionResult</code>. Native <code>&lt;form&gt;</code> elements
+          work out of the box — no wrapper component needed.
+        </p>
+        <CodeBlock language="tsx">{`import { route, type RouteComponentPropsOf } from "@funstack/router";
+
+// Define a route with both action and loader
+const editUserRoute = route({
+  id: "editUser",
+  path: "/users/:userId/edit",
+  action: async ({ request, params, signal }) => {
+    const formData = await request.formData();
+    const response = await fetch(\`/api/users/\${params.userId}\`, {
+      method: "PUT",
+      body: formData,
+      signal,
+    });
+    return response.json() as Promise<{ success: boolean; error?: string }>;
+  },
+  loader: async ({ params, signal, actionResult }) => {
+    const user = await fetchUser(params.userId, signal);
+    return {
+      user,
+      // actionResult is undefined on normal navigation,
+      // contains the action's return value after form submission
+      updateResult: actionResult ?? null,
+    };
+  },
+  component: EditUserPage,
+});
+
+// Component receives data from the loader (which includes the action result)
+function EditUserPage({ data, isPending }: RouteComponentPropsOf<typeof editUserRoute>) {
+  return (
+    <form method="post">
+      {data.updateResult?.error && (
+        <p className="error">{data.updateResult.error}</p>
+      )}
+      {data.updateResult?.success && (
+        <p className="success">User updated successfully!</p>
+      )}
+      <input name="name" defaultValue={data.user.name} />
+      <input name="email" defaultValue={data.user.email} />
+      <button type="submit" disabled={isPending}>
+        {isPending ? "Saving..." : "Save"}
+      </button>
+    </form>
+  );
+}
+
+// Route with action only (pure side effect, no data for component)
+const deleteRoute = route({
+  path: "/users/:userId/delete",
+  action: async ({ params, signal }) => {
+    await fetch(\`/api/users/\${params.userId}\`, {
+      method: "DELETE",
+      signal,
+    });
+  },
+  component: DeleteConfirmation,
+});`}</CodeBlock>
+        <p>Key behaviors:</p>
+        <ul>
+          <li>
+            Actions handle POST form submissions; loaders handle GET navigations
+          </li>
+          <li>Action results are never cached — each submission runs fresh</li>
+          <li>
+            After an action completes, all matched loaders are revalidated
+          </li>
+          <li>
+            POST submissions to routes without an action are not intercepted
+            (browser handles normally)
+          </li>
+          <li>
+            The deepest matched route with an action handles the submission
+          </li>
+        </ul>
+      </section>
+
+      <section>
+        <h2>Search Parameters</h2>
+        <p>Work with URL query parameters:</p>
+        <CodeBlock language="tsx">{`import { useSearchParams } from "@funstack/router";
+
+function ProductList() {
+  const [searchParams, setSearchParams] = useSearchParams();
+
+  const category = searchParams.get("category") || "all";
+  const sortBy = searchParams.get("sort") || "name";
+
+  const handleCategoryChange = (newCategory: string) => {
+    setSearchParams({
+      category: newCategory,
+      sort: sortBy,
+    });
+  };
+
+  const handleSortChange = (newSort: string) => {
+    setSearchParams({
+      category,
+      sort: newSort,
+    });
+  };
+
+  return (
+    <div>
+      <select value={category} onChange={(e) => handleCategoryChange(e.target.value)}>
+        <option value="all">All Categories</option>
+        <option value="electronics">Electronics</option>
+        <option value="clothing">Clothing</option>
+      </select>
+
+      <select value={sortBy} onChange={(e) => handleSortChange(e.target.value)}>
+        <option value="name">Sort by Name</option>
+        <option value="price">Sort by Price</option>
+      </select>
+
+      <p>Showing {category} products, sorted by {sortBy}</p>
+    </div>
+  );
+}`}</CodeBlock>
+      </section>
+
+      <section>
+        <h2>Pathless Routes</h2>
+        <p>
+          Routes without a <code>path</code> are called "pathless routes". They
+          always match and don't consume any pathname, making them ideal for
+          layout wrappers that don't affect the URL structure.
+        </p>
+        <CodeBlock language="tsx">{`import { route, Outlet } from "@funstack/router";
+
+// A layout wrapper that provides authentication context
+function AuthLayout() {
+  return (
+    <AuthProvider>
+      <Outlet />
+    </AuthProvider>
+  );
+}
+
+// A layout wrapper that provides a sidebar
+function DashboardLayout() {
+  return (
+    <div className="dashboard">
+      <Sidebar />
+      <main>
+        <Outlet />
+      </main>
+    </div>
+  );
+}
+
+const routes = [
+  route({
+    path: "/",
+    component: RootLayout,
+    children: [
+      route({ path: "/", component: HomePage }),
+      route({ path: "/about", component: AboutPage }),
+      // Pathless route wraps authenticated pages
+      route({
+        component: AuthLayout,
+        children: [
+          // Another pathless route for dashboard layout
+          route({
+            component: DashboardLayout,
+            children: [
+              route({ path: "/dashboard", component: DashboardHome }),
+              route({ path: "/dashboard/settings", component: Settings }),
+              route({ path: "/dashboard/profile", component: Profile }),
+            ],
+          }),
+        ],
+      }),
+    ],
+  }),
+];`}</CodeBlock>
+        <p>Key behaviors of pathless routes:</p>
+        <ul>
+          <li>
+            <strong>Always match</strong> - They don't participate in path
+            matching
+          </li>
+          <li>
+            <strong>Consume no pathname</strong> - Children receive the full
+            remaining pathname
+          </li>
+          <li>
+            <strong>No params</strong> - The <code>params</code> prop is always
+            an empty object
+          </li>
+          <li>
+            <strong>Can have loaders</strong> - Pathless routes can still load
+            data
+          </li>
+        </ul>
+        <h3>Catch-All Routes</h3>
+        <p>
+          Use <code>path: "/*"</code> at the end of a route list to catch any
+          unmatched paths:
+        </p>
+        <CodeBlock language="tsx">{`const routes = [
+  route({ path: "/", component: HomePage }),
+  route({ path: "/about", component: AboutPage }),
+  // Catch-all: matches any unmatched path
+  route({ path: "/*", component: NotFoundPage }),
+];`}</CodeBlock>
+      </section>
+
+      <section>
+        <h2>Navigation Callback</h2>
+        <p>
+          React to navigation events. The callback receives the{" "}
+          <code>NavigateEvent</code> from the Navigation API and an info object
+          containing matched routes and whether the navigation will be
+          intercepted:
+        </p>
+        <CodeBlock language="tsx">{`import { Router, route, type OnNavigateCallback } from "@funstack/router";
+
+function App() {
+  const handleNavigate: OnNavigateCallback = (event, info) => {
+    // Track page views
+    const url = new URL(event.destination.url);
+    analytics.track("page_view", {
+      path: url.pathname,
+      search: url.search,
+    });
+
+    // info.matches contains the matched routes (or null if no match)
+    // info.intercepting indicates if the router will handle this navigation
+    console.log("Matched routes:", info.matches);
+    console.log("Intercepting:", info.intercepting);
+
+    // You can call event.preventDefault() to cancel the navigation
+  };
+
+  return (
+    <Router
+      routes={routes}
+      onNavigate={handleNavigate}
+    />
+  );
+}`}</CodeBlock>
+      </section>
+    </div>
+  );
+}