@funstack/router 0.0.5 → 0.0.7-alpha.0

package/dist/docs/LearnRscPage.tsx

@@ -0,0 +1,293 @@
+import { CodeBlock } from "../components/CodeBlock.js";
+
+export function LearnRscPage() {
+  return (
+    <div className="learn-content">
+      <h2>React Server Components</h2>
+
+      <p className="page-intro">
+        FUNSTACK Router is designed to work with React Server Components (RSC).
+        The package provides a dedicated server entry point so that route
+        definitions can live in server modules, keeping client bundle sizes
+        small.
+      </p>
+
+      <section>
+        <h3>Why RSC Compatibility Matters</h3>
+        <p>
+          In an RSC architecture, the module graph is split into{" "}
+          <strong>server modules</strong> and <strong>client modules</strong>.
+          Server modules run at build time (or on the server) and are never sent
+          to the browser. Client modules are marked with the{" "}
+          <code>"use client"</code> directive and are included in the browser
+          bundle.
+        </p>
+        <p>
+          The main <code>@funstack/router</code> entry point is marked{" "}
+          <code>"use client"</code> because it exports components and hooks that
+          depend on browser APIs (the Navigation API, React context, etc.). This
+          means importing from <code>@funstack/router</code> in a server module
+          would pull the entire router into the client bundle &mdash; defeating
+          the purpose of RSC.
+        </p>
+        <p>
+          To solve this, the package provides a separate entry point:{" "}
+          <code>@funstack/router/server</code>.
+        </p>
+      </section>
+
+      <section>
+        <h3>
+          The <code>@funstack/router/server</code> Entry Point
+        </h3>
+        <p>
+          The server entry point exports the <code>route()</code> and{" "}
+          <code>routeState()</code> helper functions <em>without</em> the{" "}
+          <code>"use client"</code> directive. This lets you define your route
+          tree in a server module:
+        </p>
+        <CodeBlock language="tsx">{`// App.tsx — a Server Component (no "use client" directive)
+import { Router } from "@funstack/router";
+import { route } from "@funstack/router/server";
+
+const routes = [
+  route({
+    path: "/",
+    component: Layout,
+    children: [
+      route({ path: "/", component: HomePage }),
+      route({ path: "/about", component: AboutPage }),
+    ],
+  }),
+];
+
+export default function App() {
+  return <Router routes={routes} />;
+}`}</CodeBlock>
+        <p>
+          In this example, <code>App</code> is a server component. It builds the
+          route array using <code>route()</code> from{" "}
+          <code>@funstack/router/server</code> and renders the{" "}
+          <code>Router</code> component from <code>@funstack/router</code>.
+          Since <code>Router</code> is a client component, the RSC bundler
+          handles the client boundary automatically.
+        </p>
+        <h4>What the server entry point exports</h4>
+        <ul>
+          <li>
+            <code>route</code> &mdash; Route definition helper (same API as the
+            main entry point)
+          </li>
+          <li>
+            <code>routeState</code> &mdash; Route definition helper with typed
+            navigation state
+          </li>
+          <li>
+            Types: <code>LoaderArgs</code>, <code>RouteDefinition</code>,{" "}
+            <code>PathParams</code>, <code>RouteComponentProps</code>,{" "}
+            <code>RouteComponentPropsWithData</code>
+          </li>
+        </ul>
+      </section>
+
+      <section>
+        <h3>The Client Boundary</h3>
+        <p>
+          The <code>Router</code> component subscribes to the Navigation API and
+          manages React state, so it is a client component. It serves as the
+          client boundary in your component tree &mdash; server components above
+          it construct the route definitions, while <code>Router</code> and its
+          runtime dependencies run in the browser.
+        </p>
+        <p>
+          Route definitions (paths, component references, children) are plain
+          serializable data, so they can be passed from a server component into{" "}
+          <code>Router</code> as props.
+        </p>
+      </section>
+
+      <section>
+        <h3>Defining Routes in the Server Context</h3>
+        <p>
+          Because route definitions are plain data (paths, component references,
+          and children), they can be constructed entirely on the server. The{" "}
+          <code>route()</code> helper from <code>@funstack/router/server</code>{" "}
+          produces the same <code>RouteDefinition</code> objects as the one from
+          the main entry point &mdash; the only difference is that it does not
+          pull in client-side code.
+        </p>
+        <CodeBlock language="tsx">{`// App.tsx — Server Component
+import { Router } from "@funstack/router";
+import { route } from "@funstack/router/server";
+import { lazy } from "react";
+
+// Lazy-load page components — these will be code-split
+const HomePage = lazy(() => import("./pages/HomePage.js"));
+const DashboardPage = lazy(() => import("./pages/DashboardPage.js"));
+const SettingsPage = lazy(() => import("./pages/SettingsPage.js"));
+
+const routes = [
+  route({
+    component: <Layout />,
+    children: [
+      route({ path: "/", component: HomePage }),
+      route({ path: "/dashboard", component: DashboardPage }),
+      route({ path: "/settings", component: SettingsPage }),
+    ],
+  }),
+];
+
+export default function App() {
+  return <Router routes={routes} />;
+}`}</CodeBlock>
+        <p>
+          Note that page components referenced in route definitions can be
+          either server components or client components. When a page component
+          uses hooks or browser APIs, it should have the{" "}
+          <code>"use client"</code> directive. Otherwise, it can remain a server
+          component for optimal performance.
+        </p>
+
+        <h4>Loaders in an RSC Context</h4>
+        <p>
+          Loaders run client-side &mdash; they execute in the browser when a
+          route is matched. This means a loader function cannot be defined
+          inline within a server module. Instead, define the loader in a client
+          module and import it:
+        </p>
+        <CodeBlock language="tsx">{`// loaders/dashboard.ts — a Client Module
+"use client";
+
+export async function dashboardLoader({ params }: LoaderArgs) {
+  const res = await fetch(\`/api/dashboard/\${params.id}\`);
+  return res.json();
+}`}</CodeBlock>
+        <CodeBlock language="tsx">{`// App.tsx — Server Component
+import { Router } from "@funstack/router";
+import { route } from "@funstack/router/server";
+import { dashboardLoader } from "./loaders/dashboard.js";
+
+const routes = [
+  route({
+    component: <Layout />,
+    children: [
+      route({ path: "/", component: HomePage }),
+      route({
+        path: "/dashboard/:id",
+        component: DashboardPage,
+        loader: dashboardLoader,
+      }),
+    ],
+  }),
+];
+
+export default function App() {
+  return <Router routes={routes} />;
+}`}</CodeBlock>
+        <p>
+          By placing the loader in a <code>"use client"</code> module, it is
+          included in the client bundle where it can access browser APIs. The
+          server component imports the reference and passes it as part of the
+          route definition.
+        </p>
+      </section>
+
+      <section>
+        <h3>A Complete Example</h3>
+        <p>
+          This documentation site itself uses this pattern. Here is a simplified
+          version of how it is structured:
+        </p>
+        <CodeBlock language="tsx">{`// vite.config.ts
+import funstackStatic from "@funstack/static";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [
+    funstackStatic({
+      root: "./src/Root.tsx",  // Server Component — HTML shell
+      app: "./src/App.tsx",    // Server Component — route definitions
+      ssr: true,
+    }),
+    react(),
+  ],
+});`}</CodeBlock>
+        <CodeBlock language="tsx">{`// Root.tsx — Server Component (HTML shell)
+import type { ReactNode } from "react";
+
+export default function Root({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="UTF-8" />
+        <title>My App</title>
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}`}</CodeBlock>
+        <CodeBlock language="tsx">{`// App.tsx — Server Component (route definitions)
+import { Router } from "@funstack/router";
+import { route } from "@funstack/router/server";
+import { Layout } from "./components/Layout.js";
+import { HomePage } from "./pages/HomePage.js";
+import { AboutPage } from "./pages/AboutPage.js";
+
+const routes = [
+  route({
+    component: <Layout />,
+    children: [
+      route({ path: "/", component: HomePage }),
+      route({ path: "/about", component: AboutPage }),
+    ],
+  }),
+];
+
+export default function App() {
+  return <Router routes={routes} fallback="static" />;
+}`}</CodeBlock>
+        <p>
+          In this setup, <code>Root</code> and <code>App</code> are server
+          components. The route definitions are constructed on the server and
+          passed into <code>Router</code>, which acts as the client boundary.
+        </p>
+      </section>
+
+      <section>
+        <h3>Key Takeaways</h3>
+        <ul>
+          <li>
+            Import <code>route</code> and <code>routeState</code> from{" "}
+            <code>@funstack/router/server</code> in server modules to avoid
+            pulling client code into the server module graph
+          </li>
+          <li>
+            <code>Router</code> is a client component and serves as the client
+            boundary &mdash; render it directly from your server component
+          </li>
+          <li>
+            Route definitions are plain data and can be constructed entirely on
+            the server
+          </li>
+          <li>
+            Loaders run client-side &mdash; define them in{" "}
+            <code>"use client"</code> modules and import them into your route
+            definitions
+          </li>
+          <li>
+            Page components can be either server components or client components
+            depending on whether they need browser APIs or hooks
+          </li>
+          <li>
+            See also the{" "}
+            <a href="/funstack-router/learn/server-side-rendering">
+              Server-Side Rendering
+            </a>{" "}
+            guide for how the router handles SSR and hydration
+          </li>
+        </ul>
+      </section>
+    </div>
+  );
+}

package/dist/docs/LearnSsrPage.tsx

@@ -0,0 +1,180 @@
+import { CodeBlock } from "../components/CodeBlock.js";
+
+export function LearnSsrPage() {
+  return (
+    <div className="learn-content">
+      <h2>Server-Side Rendering</h2>
+
+      <p className="page-intro">
+        FUNSTACK Router supports server-side rendering with a two-stage model.
+        During SSR, pathless (layout) routes without loaders render to produce
+        an app shell, while path-based routes and loaders activate only after
+        client hydration.
+      </p>
+
+      <section>
+        <h3>How SSR Works</h3>
+        <p>
+          FUNSTACK Router uses a two-stage rendering model that separates what
+          renders on the server from what renders on the client:
+        </p>
+        <p>
+          <strong>Stage 1 &mdash; Server:</strong> No URL is available on the
+          server. The router matches only pathless routes (routes without a{" "}
+          <code>path</code> property) that do not have a loader. Pathless routes
+          with loaders are skipped because there is no request context to run
+          them. This produces the app shell &mdash; layouts, headers, navigation
+          chrome, and other structural markup.
+        </p>
+        <p>
+          <strong>Stage 2 &mdash; Client hydration:</strong> Once the browser
+          hydrates the page, the actual URL becomes available via the Navigation
+          API. Path-based routes now match, loaders execute, and page-specific
+          content renders.
+        </p>
+        <CodeBlock language="tsx">{`// What renders at each stage:
+
+// Stage 1 (Server)         Stage 2 (Client)
+// ─────────────────        ─────────────────
+// App shell (pathless      App shell (pathless)
+//   without loader)
+// ✗ No path routes         ✓ Path routes match
+// ✗ No loaders             ✓ Loaders execute
+// ✗ No URL available       ✓ URL from Navigation API`}</CodeBlock>
+      </section>
+
+      <section>
+        <h3>Pathless Routes as the App Shell</h3>
+        <p>
+          Pathless routes (routes without a <code>path</code> property) always
+          match regardless of the current URL. This makes them ideal for
+          defining the SSR app shell &mdash; the parts of your UI that should be
+          visible immediately while the rest of the page loads.
+        </p>
+        <p>
+          Consider the following route tree. During SSR, only the pathless{" "}
+          <code>AppShell</code> route renders. The page routes require a URL to
+          match, so they are skipped:
+        </p>
+        <CodeBlock language="tsx">{`const routes = [
+  route({
+    component: AppShell, // Pathless — renders during SSR ✓
+    children: [
+      route({ path: "/", component: HomePage }),   // Has path — skipped during SSR
+      route({ path: "/about", component: AboutPage }), // Has path — skipped during SSR
+    ],
+  }),
+];`}</CodeBlock>
+        <p>
+          In this example, <code>AppShell</code> might render a header, sidebar,
+          and footer &mdash; the structural parts of your application. After
+          hydration, the router matches the actual URL and renders{" "}
+          <code>HomePage</code> or <code>AboutPage</code> inside the shell.
+        </p>
+      </section>
+
+      <section>
+        <h3>Hooks and SSR</h3>
+        <p>
+          Because no URL is available during SSR, hooks that depend on the
+          current URL will throw errors if called during server rendering. The
+          affected hooks are <code>useLocation</code> and{" "}
+          <code>useSearchParams</code>.
+        </p>
+        <CodeBlock language="tsx">{`// These hooks throw during SSR:
+useLocation();
+// Error: "useLocation: URL is not available during SSR."
+
+useSearchParams();
+// Error: "useSearchParams: URL is not available during SSR."`}</CodeBlock>
+        <p>
+          To avoid these errors, either use URL-dependent hooks only in
+          components rendered by path-based routes, or read the current path
+          inside a client-side effect (e.g., <code>useLayoutEffect</code> +{" "}
+          <code>navigation.currentEntry</code>) so the value is only accessed
+          after hydration:
+        </p>
+        <CodeBlock language="tsx">{`// ✗ Bad: AppShell renders during SSR, useLocation will throw
+function AppShell() {
+  const location = useLocation(); // Throws during SSR!
+  return <div>{/* ... */}</div>;
+}
+
+// ✓ Good: Read the path in a client-side effect
+function useCurrentPath() {
+  const [path, setPath] = useState<string | undefined>(undefined);
+  useLayoutEffect(() => {
+    setPath(navigation.currentEntry?.url
+      ? new URL(navigation.currentEntry.url).pathname
+      : undefined);
+  }, []);
+  return path;
+}
+
+function AppShell() {
+  const path = useCurrentPath(); // undefined during SSR, string after hydration
+  const isActive = (p: string) => path === p;
+  return <nav>{/* ... */}</nav>;
+}
+
+// ✓ Good: HomePage only renders after hydration (has a path)
+function HomePage() {
+  const location = useLocation(); // Safe — URL is available
+  return <div>Current path: {location.pathname}</div>;
+}`}</CodeBlock>
+      </section>
+
+      <section>
+        <h3>
+          The <code>fallback="static"</code> Mode
+        </h3>
+        <p>
+          When the Navigation API is unavailable (e.g., in older browsers), the
+          router's <code>fallback</code> prop controls what happens. With{" "}
+          <code>fallback="static"</code>, the router reads the current URL from{" "}
+          <code>window.location</code> and renders matched routes without
+          navigation interception. Links cause full page reloads (MPA behavior).
+        </p>
+        <p>
+          This is different from SSR: in static fallback mode, a URL <em>is</em>{" "}
+          available (from <code>window.location</code>), so path-based routes
+          match and loaders execute normally. During SSR, no URL is available at
+          all.
+        </p>
+        <CodeBlock language="tsx">{`import { Router } from "@funstack/router";
+
+// Static fallback: renders routes using window.location
+// when Navigation API is unavailable
+<Router routes={routes} fallback="static" />`}</CodeBlock>
+      </section>
+
+      <section>
+        <h3>Key Takeaways</h3>
+        <ul>
+          <li>
+            During SSR, only pathless routes without loaders render (no URL or
+            request context is available on the server)
+          </li>
+          <li>
+            Path-based routes, loaders, and pathless routes with loaders
+            activate after client hydration
+          </li>
+          <li>
+            Pathless routes are ideal for app shell markup (headers, footers,
+            layout structure)
+          </li>
+          <li>
+            Avoid <code>useLocation</code> and <code>useSearchParams</code> in
+            components that render during SSR; use a client-side effect (e.g.,{" "}
+            <code>useLayoutEffect</code>) to read location information in the
+            app shell
+          </li>
+          <li>
+            This two-stage model keeps SSR output lightweight while enabling
+            full interactivity on the client
+          </li>
+        </ul>
+      </section>
+    </div>
+  );
+}

package/dist/docs/LearnTransitionsPage.tsx

@@ -0,0 +1,146 @@
+import { CodeBlock } from "../components/CodeBlock.js";
+
+export function LearnTransitionsPage() {
+  return (
+    <div className="learn-content">
+      <h2>Controlling Transitions</h2>
+
+      <p className="page-intro">
+        FUNSTACK Router wraps every navigation in React's{" "}
+        <code>startTransition</code>, which means the old UI may stay visible
+        while the new route loads. This page explains how this works and how to
+        control it.
+      </p>
+
+      <section>
+        <h3>Navigations as Transitions</h3>
+        <p>
+          When the user navigates, the Router updates its location state inside{" "}
+          <code>startTransition()</code>. This means React treats every
+          navigation as a transition: if an existing Suspense boundary suspends
+          (e.g., a component loading data with <code>use()</code>), React keeps
+          the old UI visible instead of immediately showing the fallback. This
+          behavior is{" "}
+          <a href="https://react.dev/reference/react/useTransition#building-a-suspense-enabled-router">
+            what React recommends for Suspense-enabled routers
+          </a>
+          .
+        </p>
+        <p>
+          Consider a route with a loader that fetches data. The component uses{" "}
+          <code>use()</code> to read the promise. Because the navigation happens
+          inside a transition, the previous page remains on screen until the
+          data is ready:
+        </p>
+        <CodeBlock language="tsx">{`const routes = [
+  route({
+    path: "/user/:id",
+    loader: ({ params }) => fetchUser(params.id),
+    component: UserDetailPage,
+  }),
+];
+
+// The route component receives the Promise and provides a Suspense boundary
+function UserDetailPage({ data }: { data: Promise<User> }) {
+  return (
+    <Suspense fallback={<p>Loading...</p>}>
+      <UserDetail data={data} />
+    </Suspense>
+  );
+}
+
+// A child component uses use() to read the data
+function UserDetail({ data }: { data: Promise<User> }) {
+  const user = use(data);
+  return <div>{user.name}</div>;
+}
+
+// When navigating from /user/1 to /user/2:
+// → The /user/1 page stays visible while /user/2 data loads
+// → Once loaded, the UI swaps to /user/2 instantly`}</CodeBlock>
+      </section>
+
+      <section>
+        <h3>
+          Showing Pending UI with <code>useIsPending</code>
+        </h3>
+        <p>
+          While a transition is in progress, the <code>useIsPending()</code>{" "}
+          hook returns <code>true</code>. Use it to give users visual feedback
+          that something is loading &mdash; for example, dimming the current
+          page or showing a loading bar.
+        </p>
+        <CodeBlock language="tsx">{`import { useIsPending, Outlet } from "@funstack/router";
+
+function Layout() {
+  const isPending = useIsPending();
+  return (
+    <div>
+      {isPending && <div className="loading-bar" />}
+      <div style={{ opacity: isPending ? 0.6 : 1 }}>
+        <Outlet />
+      </div>
+    </div>
+  );
+}`}</CodeBlock>
+        <p>
+          The <code>isPending</code> flag is also available as a prop on route
+          components, so you can use it without calling the hook:
+        </p>
+        <CodeBlock language="tsx">{`function Layout({ isPending }: { isPending: boolean }) {
+  return (
+    <div style={{ opacity: isPending ? 0.6 : 1 }}>
+      <Outlet />
+    </div>
+  );
+}`}</CodeBlock>
+      </section>
+
+      <section>
+        <h3>Opting Out of Transitions</h3>
+        <p>
+          Sometimes you want to show a loading fallback immediately instead of
+          keeping the old UI visible. This is especially useful when navigating
+          between pages that share the same route but with different params
+          &mdash; for example, going from <code>/users/1</code> to{" "}
+          <code>/users/2</code>, where showing stale data from user 1 while user
+          2 loads would be confusing.
+        </p>
+        <p>
+          The technique is to add a <code>key</code> prop to a{" "}
+          <code>{"<Suspense>"}</code> boundary that changes with the route
+          params. When the key changes, React unmounts the old Suspense boundary
+          and mounts a new one, immediately showing the fallback:
+        </p>
+        <CodeBlock language="tsx">{`import { Suspense } from "react";
+
+function UserDetailPage({
+  params,
+  data,
+}: {
+  params: { id: string };
+  data: Promise<User>;
+}) {
+  return (
+    <Suspense key={params.id} fallback={<LoadingSpinner />}>
+      <UserDetail data={data} />
+    </Suspense>
+  );
+}`}</CodeBlock>
+        <p>
+          Because the <code>key</code> changes from <code>"1"</code> to{" "}
+          <code>"2"</code> when navigating between users, React discards the old
+          Suspense boundary entirely. The new boundary has no resolved content
+          yet, so it shows the fallback right away &mdash; bypassing the
+          transition behavior.
+        </p>
+        <p>
+          Use this pattern when stale content would be misleading. For
+          navigations where the old page is still a reasonable placeholder
+          (e.g., navigating between completely different pages), the default
+          transition behavior is usually the better experience.
+        </p>
+      </section>
+    </div>
+  );
+}