@funstack/router 0.0.6 → 0.0.7-alpha.0

package/dist/docs/ApiTypesPage.tsx

@@ -0,0 +1,310 @@
+import { CodeBlock } from "../components/CodeBlock.js";
+
+export function ApiTypesPage() {
+  return (
+    <div className="page docs-page api-page">
+      <h1>Types</h1>
+      <p className="page-intro">
+        TypeScript types and interfaces exported by the router.
+      </p>
+
+      <article className="api-item">
+        <h3>
+          <code>RouteComponentProps&lt;TParams, TState&gt;</code>
+        </h3>
+        <p>
+          Props type for route components without a loader. Includes navigation
+          state management props.
+        </p>
+        <CodeBlock language="typescript">{`import type { RouteComponentProps } from "@funstack/router";
+
+type Props = RouteComponentProps<
+  { userId: string },      // TParams - path parameters
+  { scrollPosition: number } // TState - navigation state type
+>;
+
+// Equivalent to:
+type Props = {
+  params: { userId: string };
+  state: { scrollPosition: number } | undefined;
+  // Async state update via replace navigation
+  setState: (
+    state: { scrollPosition: number } |
+           ((prev: { scrollPosition: number } | undefined) => { scrollPosition: number })
+  ) => Promise<void>;
+  // Sync state update via updateCurrentEntry
+  setStateSync: (
+    state: { scrollPosition: number } |
+           ((prev: { scrollPosition: number } | undefined) => { scrollPosition: number })
+  ) => void;
+  resetState: () => void;
+  info: unknown; // Ephemeral navigation info
+  isPending: boolean; // Whether a navigation transition is pending
+};`}</CodeBlock>
+        <p>
+          <strong>setState vs setStateSync:</strong>
+        </p>
+        <ul>
+          <li>
+            <code>setState</code> - Async method that returns a Promise. Uses
+            replace navigation internally, ensuring the state update goes
+            through the full navigation cycle.
+          </li>
+          <li>
+            <code>setStateSync</code> - Synchronous method that updates state
+            immediately using <code>navigation.updateCurrentEntry()</code>.
+          </li>
+        </ul>
+      </article>
+
+      <article className="api-item">
+        <h3>
+          <code>RouteComponentPropsWithData&lt;TParams, TData, TState&gt;</code>
+        </h3>
+        <p>
+          Props type for route components with a loader. Extends{" "}
+          <code>RouteComponentProps</code> with a <code>data</code> prop.
+        </p>
+        <CodeBlock language="typescript">{`import type { RouteComponentPropsWithData } from "@funstack/router";
+
+type Props = RouteComponentPropsWithData<
+  { userId: string },        // TParams - path parameters
+  User,                      // TData - loader return type
+  { selectedTab: string }    // TState - navigation state type
+>;
+
+// Equivalent to:
+type Props = {
+  params: { userId: string };
+  data: User;
+  state: { selectedTab: string } | undefined;
+  setState: (state: ...) => Promise<void>;  // async
+  setStateSync: (state: ...) => void;       // sync
+  resetState: () => void;
+  info: unknown; // Ephemeral navigation info
+  isPending: boolean; // Whether a navigation transition is pending
+};`}</CodeBlock>
+      </article>
+
+      <article className="api-item">
+        <h3>
+          <code>PathParams&lt;T&gt;</code>
+        </h3>
+        <p>
+          Utility type that extracts parameter types from a path pattern string.
+        </p>
+        <CodeBlock language="tsx">{`import type { PathParams } from "@funstack/router";
+
+// PathParams<"/users/:userId"> = { userId: string }
+// PathParams<"/users/:userId/posts/:postId"> = { userId: string; postId: string }
+// PathParams<"/about"> = Record<string, never>
+
+type MyParams = PathParams<"/users/:userId">;
+// { userId: string }`}</CodeBlock>
+      </article>
+
+      <article className="api-item">
+        <h3>
+          <code>
+            TypefulOpaqueRouteDefinition&lt;Id, Params, State, Data&gt;
+          </code>
+        </h3>
+        <p>
+          A route definition that carries type information. Created when using{" "}
+          <code>route()</code> or <code>routeState()</code> with an{" "}
+          <code>id</code> property. This enables type-safe access to route
+          params, state, and data via hooks.
+        </p>
+        <CodeBlock language="tsx">{`import { route, routeState } from "@funstack/router";
+import type { TypefulOpaqueRouteDefinition } from "@funstack/router";
+
+// Route with id gets TypefulOpaqueRouteDefinition type
+const userRoute = route({
+  id: "user",
+  path: "/users/:userId",
+  loader: () => ({ name: "John" }),
+  component: UserPage,
+});
+// Type: TypefulOpaqueRouteDefinition<"user", { userId: string }, undefined, { name: string }>
+
+// Route without id gets OpaqueRouteDefinition (no type info)
+const aboutRoute = route({
+  path: "/about",
+  component: AboutPage,
+});
+// Type: OpaqueRouteDefinition`}</CodeBlock>
+      </article>
+
+      <article className="api-item">
+        <h3>Type Extraction Utilities</h3>
+        <p>
+          Helper types to extract type information from{" "}
+          <code>TypefulOpaqueRouteDefinition</code>. Useful for advanced type
+          manipulation.
+        </p>
+        <CodeBlock language="tsx">{`import type {
+  ExtractRouteId,
+  ExtractRouteParams,
+  ExtractRouteState,
+  ExtractRouteData,
+} from "@funstack/router";
+
+const userRoute = route({
+  id: "user",
+  path: "/users/:userId",
+  loader: () => ({ name: "John", age: 30 }),
+  component: UserPage,
+});
+
+type Id = ExtractRouteId<typeof userRoute>;
+// "user"
+
+type Params = ExtractRouteParams<typeof userRoute>;
+// { userId: string }
+
+type State = ExtractRouteState<typeof userRoute>;
+// undefined
+
+type Data = ExtractRouteData<typeof userRoute>;
+// { name: string; age: number }`}</CodeBlock>
+      </article>
+
+      <article className="api-item">
+        <h3>
+          <code>RouteComponentPropsOf&lt;T&gt;</code>
+        </h3>
+        <p>
+          Utility type that extracts the component props type from a route
+          definition. Returns <code>RouteComponentProps</code> for routes
+          without a loader, or <code>RouteComponentPropsWithData</code> for
+          routes with a loader. This is useful for typing route components
+          separately from the route definition.
+        </p>
+        <CodeBlock language="tsx">{`import { route, routeState } from "@funstack/router";
+import type { RouteComponentPropsOf } from "@funstack/router";
+
+// Route without loader
+const userRoute = route({
+  id: "user",
+  path: "/users/:userId",
+  component: UserPage,
+});
+
+type UserPageProps = RouteComponentPropsOf<typeof userRoute>;
+// RouteComponentProps<{ userId: string }, undefined>
+
+function UserPage({ params }: UserPageProps) {
+  return <h1>User: {params.userId}</h1>;
+}
+
+// Route with loader
+const profileRoute = route({
+  id: "profile",
+  path: "/profile/:userId",
+  loader: () => ({ name: "John", age: 30 }),
+  component: ProfilePage,
+});
+
+type ProfilePageProps = RouteComponentPropsOf<typeof profileRoute>;
+// RouteComponentPropsWithData<{ userId: string }, { name: string; age: number }, undefined>
+
+// Route with state
+type MyState = { tab: string };
+const settingsRoute = routeState<MyState>()({
+  id: "settings",
+  path: "/settings",
+  component: SettingsPage,
+});
+
+type SettingsPageProps = RouteComponentPropsOf<typeof settingsRoute>;
+// RouteComponentProps<Record<string, never>, MyState>`}</CodeBlock>
+        <p>
+          <strong>Note:</strong> This utility requires a route with an{" "}
+          <code>id</code> property. Using it with a route without{" "}
+          <code>id</code> will result in a type error.
+        </p>
+      </article>
+
+      <article className="api-item">
+        <h3>
+          <code>RouteDefinition</code>
+        </h3>
+        <p>
+          The <code>component</code> field accepts two forms:
+        </p>
+        <ul>
+          <li>
+            <strong>Component reference</strong> (e.g.,{" "}
+            <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).
+          </li>
+          <li>
+            <strong>JSX element</strong> (e.g.,{" "}
+            <code>component: &lt;UserPage /&gt;</code>): Rendered as-is without
+            router props injection. Useful for static components or when you
+            want to pass custom props.
+          </li>
+        </ul>
+        <CodeBlock language="tsx">{`// Component reference: router injects props automatically
+route({
+  path: "/users/:userId",
+  component: UserPage,  // receives { params, state, setState, ... }
+});
+
+// JSX element: rendered as-is, no props injection
+route({
+  path: "/about",
+  component: <AboutPage title="About Us" />,  // custom props only
+});
+
+// With loader and state:
+routeState<{ tab: string }>()({
+  path: "/users/:userId",
+  component: UserPage,  // receives { data, params, state, ... }
+  loader: () => fetchUser(),
+});`}</CodeBlock>
+      </article>
+
+      <article className="api-item">
+        <h3>
+          <code>LoaderArgs</code>
+        </h3>
+        <CodeBlock language="typescript">{`interface LoaderArgs {
+  params: Record<string, string>;
+  request: Request;
+  signal: AbortSignal;
+}`}</CodeBlock>
+      </article>
+
+      <article className="api-item">
+        <h3>
+          <code>Location</code>
+        </h3>
+        <CodeBlock language="typescript">{`interface Location {
+  pathname: string;
+  search: string;
+  hash: string;
+}`}</CodeBlock>
+      </article>
+
+      <article className="api-item">
+        <h3>
+          <code>NavigateOptions</code>
+        </h3>
+        <CodeBlock language="typescript">{`interface NavigateOptions {
+  replace?: boolean;
+  state?: unknown;
+  info?: unknown;  // Ephemeral, not persisted in history
+}`}</CodeBlock>
+        <p>
+          <strong>Note:</strong> <code>state</code> is persisted in history and
+          available across back/forward navigation. <code>info</code> is
+          ephemeral and only available during the navigation that triggered it.
+        </p>
+      </article>
+    </div>
+  );
+}

package/dist/docs/ApiUtilitiesPage.tsx

@@ -0,0 +1,298 @@
+import { CodeBlock } from "../components/CodeBlock.js";
+
+export function ApiUtilitiesPage() {
+  return (
+    <div className="page docs-page api-page">
+      <h1>Utilities</h1>
+      <p className="page-intro">
+        Helper functions for defining routes and managing state.
+      </p>
+
+      <article className="api-item">
+        <h3>
+          <code>route()</code>
+        </h3>
+        <p>
+          Helper function to define routes with proper typing. The component
+          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.
+        </p>
+        <CodeBlock language="tsx">{`import { route } from "@funstack/router";
+
+// Route without loader - component receives params prop
+function ProfileTab({ params }: { params: { userId: string } }) {
+  return <div>Profile for user {params.userId}</div>;
+}
+
+// Route with loader - component receives both data and params props
+function UserPage({
+  data,
+  params,
+}: {
+  data: User;
+  params: { userId: string };
+}) {
+  return <h1>{data.name} (ID: {params.userId})</h1>;
+}
+
+const myRoute = route({
+  path: "/users/:userId",
+  component: UserPage,
+  loader: async ({ params }) => {
+    return fetchUser(params.userId);
+  },
+  children: [
+    route({ path: "/profile", component: ProfileTab }),
+    route({ path: "/settings", component: SettingsTab }),
+  ],
+});`}</CodeBlock>
+        <h4>Options</h4>
+        <table className="props-table">
+          <thead>
+            <tr>
+              <th>Option</th>
+              <th>Type</th>
+              <th>Description</th>
+            </tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td>
+                <code>path</code>
+              </td>
+              <td>
+                <code>string</code> (optional)
+              </td>
+              <td>
+                URL path pattern (supports <code>:param</code> syntax). If
+                omitted, creates a pathless route that always matches and
+                consumes no pathname. Useful for layout wrappers.
+              </td>
+            </tr>
+            <tr>
+              <td>
+                <code>component</code>
+              </td>
+              <td>
+                <code>ComponentType</code>
+              </td>
+              <td>
+                React component to render. Receives <code>params</code> prop
+                (and <code>data</code> prop if loader is defined)
+              </td>
+            </tr>
+            <tr>
+              <td>
+                <code>loader</code>
+              </td>
+              <td>
+                <code>(args: LoaderArgs) =&gt; T</code>
+              </td>
+              <td>Function to load data. May be synchronous or asynchronous</td>
+            </tr>
+            <tr>
+              <td>
+                <code>children</code>
+              </td>
+              <td>
+                <code>RouteDefinition[]</code>
+              </td>
+              <td>Nested child routes</td>
+            </tr>
+            <tr>
+              <td>
+                <code>exact</code>
+              </td>
+              <td>
+                <code>boolean</code>
+              </td>
+              <td>
+                Override default matching. <code>true</code> = exact match only,{" "}
+                <code>false</code> = prefix match. Defaults to <code>true</code>{" "}
+                for leaf routes, <code>false</code> for parent routes.
+              </td>
+            </tr>
+            <tr>
+              <td>
+                <code>requireChildren</code>
+              </td>
+              <td>
+                <code>boolean</code>
+              </td>
+              <td>
+                Whether a parent route requires a child to match.{" "}
+                <code>true</code> (default) = parent only matches if a child
+                matches, <code>false</code> = parent can match alone with{" "}
+                <code>outlet</code> as <code>null</code>. Enables catch-all
+                routes to work intuitively.
+              </td>
+            </tr>
+          </tbody>
+        </table>
+      </article>
+
+      <article className="api-item">
+        <h3>
+          <code>routeState&lt;TState&gt;()</code>
+        </h3>
+        <p>
+          Curried helper function for defining routes with typed navigation
+          state. Use this when your route component needs to manage state that
+          persists across browser back/forward navigation.
+        </p>
+        <CodeBlock language="tsx">{`import { routeState, type RouteComponentProps } from "@funstack/router";
+
+type PageState = { scrollPosition: number; selectedTab: string };
+
+function UserPage({
+  params,
+  state,
+  setState,
+  setStateSync,
+  resetState,
+}: RouteComponentProps<{ userId: string }, PageState>) {
+  // state is PageState | undefined (undefined on first visit)
+  const scrollPosition = state?.scrollPosition ?? 0;
+  const selectedTab = state?.selectedTab ?? "posts";
+
+  // Async state update (recommended for most cases)
+  const handleTabChange = async (tab: string) => {
+    await setState({ scrollPosition, selectedTab: tab });
+  };
+
+  // Sync state update (for immediate updates like scroll position)
+  const handleScroll = (position: number) => {
+    setStateSync({ scrollPosition: position, selectedTab });
+  };
+
+  return (
+    <div>
+      <h1>User {params.userId}</h1>
+      <button onClick={() => resetState()}>Clear State</button>
+    </div>
+  );
+}
+
+// Use routeState<TState>() for typed state management
+const userRoute = routeState<PageState>()({
+  path: "/users/:userId",
+  component: UserPage,
+});
+
+// With loader
+const productRoute = routeState<{ filter: string }>()({
+  path: "/products",
+  component: ProductList,
+  loader: async () => fetchProducts(),
+});`}</CodeBlock>
+        <h4>How It Works</h4>
+        <p>
+          Navigation state is stored in the browser's{" "}
+          <a
+            href="https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Navigation API
+          </a>
+          . The router provides two methods to update state:
+        </p>
+        <ul>
+          <li>
+            <code>setState</code> - Async method that uses replace navigation.
+            Returns a Promise that resolves when the navigation completes.
+          </li>
+          <li>
+            <code>setStateSync</code> - Sync method that uses{" "}
+            <code>navigation.updateCurrentEntry()</code>. Updates state
+            immediately without waiting.
+          </li>
+        </ul>
+        <p>Navigation state characteristics:</p>
+        <ul>
+          <li>State persists when navigating back/forward in history</li>
+          <li>Each history entry has its own independent state</li>
+          <li>
+            State must be serializable (no functions, Symbols, or DOM nodes)
+          </li>
+        </ul>
+        <h4>Internal Storage</h4>
+        <p>
+          The router stores state internally using a <code>__routeStates</code>{" "}
+          array indexed by route match position. This enables each nested route
+          to maintain independent state:
+        </p>
+        <CodeBlock language="typescript">{`// Internal structure stored in NavigationHistoryEntry
+{
+  __routeStates: [
+    { sidebarOpen: true },    // Layout (index 0)
+    { selectedTab: "posts" }, // UserPage (index 1)
+    { scrollY: 500 },         // PostsPage (index 2)
+  ]
+}`}</CodeBlock>
+      </article>
+
+      <article className="api-item">
+        <h3>Server Entry Point</h3>
+        <p>
+          The <code>route()</code> and <code>routeState()</code> helpers are
+          also available from a server-compatible entry point. Use this when
+          defining routes in React Server Components or other server-side code.
+        </p>
+        <CodeBlock language="tsx">{`// In Server Components or server-side route definitions
+import { route, routeState } from "@funstack/router/server";
+
+// Define routes without the "use client" directive
+const routes = [
+  route({
+    path: "/",
+    component: HomePage,
+  }),
+  routeState<{ tab: string }>()({
+    path: "/dashboard",
+    component: DashboardPage,
+  }),
+];`}</CodeBlock>
+        <h4>When to Use</h4>
+        <ul>
+          <li>Defining routes in React Server Components</li>
+          <li>Server-side route configuration files</li>
+          <li>
+            Any context where <code>"use client"</code> would cause issues
+          </li>
+        </ul>
+        <h4>Available Exports</h4>
+        <p>
+          The <code>@funstack/router/server</code> entry point exports:
+        </p>
+        <ul>
+          <li>
+            <code>route</code> - Route definition helper
+          </li>
+          <li>
+            <code>routeState</code> - Route definition helper with typed state
+          </li>
+          <li>
+            Types: <code>LoaderArgs</code>, <code>RouteDefinition</code>,{" "}
+            <code>PathParams</code>, <code>RouteComponentProps</code>,{" "}
+            <code>RouteComponentPropsWithData</code>
+          </li>
+        </ul>
+        <p>
+          For client-side features like <code>Router</code>, <code>Outlet</code>
+          , and hooks, use the main <code>@funstack/router</code> entry point.
+        </p>
+        <p>
+          See the{" "}
+          <a href="/funstack-router/learn/react-server-components">
+            React Server Components
+          </a>{" "}
+          guide for a full walkthrough of using the server entry point.
+        </p>
+      </article>
+    </div>
+  );
+}