@funstack/router 0.0.8 → 0.0.9

package/dist/docs/ApiComponentsPage.tsx

@@ -72,19 +72,20 @@ export function ApiComponentsPage() {
             </tr>
             <tr>
               <td>
-                <code>ssrPathname</code>
+                <code>ssr</code>
               </td>
               <td>
-                <code>string</code>
+                <code>SSRConfig</code>
               </td>
               <td>
-                Pathname to use for route matching during SSR. When provided,
-                path-based routes match against this pathname on the server.
-                Routes with loaders are always skipped during SSR. Once the
-                client hydrates, the real URL from the Navigation API takes
-                over. See the{" "}
-                <a href="/learn/server-side-rendering">SSR guide</a> for
-                details.
+                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>

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>
+  );
+}

package/dist/docs/GettingStartedPage.tsx

@@ -26,8 +26,13 @@ yarn add @funstack/router`}</CodeBlock>
         <CodeBlock language="bash">{`npx funstack-router-skill-installer`}</CodeBlock>
         <p>
           The installer will guide you through setting up the skill for your
-          preferred AI agent.
+          preferred AI agent. Alternatively, if you prefer{" "}
+          <a href="https://skills.sh/" target="_blank">
+            npx skills
+          </a>
+          , you can install it with:
         </p>
+        <CodeBlock language="bash">{`npx skills add uhyo/funstack-router`}</CodeBlock>
       </section>
 
       <section>
@@ -113,34 +118,6 @@ const routes = [
     component: UserProfile,
   }),
 ];`}</CodeBlock>
-        <p>
-          Alternatively, you can use the <code>useParams</code> hook to access
-          parameters:
-        </p>
-        <CodeBlock language="tsx">{`import { useParams } from "@funstack/router";
-
-function UserProfile() {
-  const params = useParams<{ userId: string }>();
-  return <h1>User: {params.userId}</h1>;
-}`}</CodeBlock>
-      </section>
-
-      <section>
-        <h2>Programmatic Navigation</h2>
-        <p>
-          Use the <code>useNavigate</code> hook for programmatic navigation:
-        </p>
-        <CodeBlock language="tsx">{`import { useNavigate } from "@funstack/router";
-
-function MyComponent() {
-  const navigate = useNavigate();
-
-  const handleClick = () => {
-    navigate("/about");
-  };
-
-  return <button onClick={handleClick}>Go to About</button>;
-}`}</CodeBlock>
       </section>
 
       <section>
@@ -164,21 +141,21 @@ function UserProfilePage({
   data: Promise<User>;
   params: { userId: string };
 }) {
-  const user = use(data);
   return (
     <Suspense fallback={<div>Loading...</div>}>
-      <UserProfile user={user} params={params} />
+      <UserProfile data={data} params={params} />
     </Suspense>
   );
 }
 
 function UserProfile({
-  user,
+  data,
   params,
 }: {
-  user: User;
+  data: Promise<User>;
   params: { userId: string };
 }) {
+  const user = use(data);
   return (
     <div>
       <h1>{user.name}</h1>

package/dist/docs/LearnNavigationApiPage.tsx

@@ -155,15 +155,12 @@ function Navigation() {
         <p>
           While FUNSTACK Router handles navigation for you, you can interact
           directly with the Navigation API when needed. This is useful for
-          features like scroll-to-top behavior or analytics tracking.
+          features like analytics tracking.
         </p>
         <CodeBlock language="tsx">{`import { useEffect } from "react";
 
 function App() {
   useEffect(() => {
-    const navigation = window.navigation;
-    if (!navigation) return;
-
     const controller = new AbortController();
 
     // Listen for successful navigation completion

package/dist/docs/LearnNestedRoutesPage.tsx

@@ -338,7 +338,7 @@ const routes = [
         <CodeBlock language="tsx">{`import { use, Suspense } from "react";
 import { route, Outlet, useRouteData } from "@funstack/router";
 
-// Define the parent route with a loader
+// Define the parent route with a loader and child routes
 const teamRoute = route({
   id: "team",
   path: "/teams/:teamId",
@@ -347,9 +347,14 @@ const teamRoute = route({
     const response = await fetch(\`/api/teams/\${params.teamId}\`);
     return response.json();
   },
+  children: [
+    route({ path: "/", component: TeamOverview }),
+    route({ path: "/members", component: TeamMembers }),
+    route({ path: "/settings", component: TeamSettings }),
+  ],
 });
 
-// Parent layout loads team data once
+// Parent layout loads team data once, child routes render in <Outlet />
 function TeamLayoutContent({
   data,
 }: {
@@ -439,8 +444,7 @@ function TeamLayout(props: {
           Pathless routes also play a key role in server-side rendering. During
           SSR, only pathless routes render (since no URL is available on the
           server), making them ideal for defining the app shell. See the{" "}
-          <a href="/learn/server-side-rendering">Server-Side Rendering</a> page
-          for details.
+          <a href="/learn/ssr">Server-Side Rendering</a> page for details.
         </p>
       </section>