@funstack/router 0.0.6 → 0.0.7

package/dist/docs/GettingStartedPage.tsx

@@ -0,0 +1,201 @@
+import { CodeBlock } from "../components/CodeBlock.js";
+
+export function GettingStartedPage() {
+  return (
+    <div className="page docs-page">
+      <h1>Getting Started</h1>
+
+      <section>
+        <h2>Installation</h2>
+        <p>Install the package using your preferred package manager:</p>
+        <CodeBlock language="bash">{`npm install @funstack/router
+# or
+pnpm add @funstack/router
+# or
+yarn add @funstack/router`}</CodeBlock>
+      </section>
+
+      <section>
+        <h2>AI Coding Agent Support</h2>
+        <p>
+          <code>@funstack/router</code> ships with an Agent skill that gives
+          your coding assistant (Claude Code, Cursor, GitHub Copilot, etc.)
+          knowledge about the router's API and best practices. After installing
+          the package, run:
+        </p>
+        <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.
+        </p>
+      </section>
+
+      <section>
+        <h2>Browser Support</h2>
+        <p>
+          FUNSTACK Router uses the{" "}
+          <a
+            href="https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            Navigation API
+          </a>{" "}
+          which is supported in Chrome 102+, Edge 102+, Firefox 147+, Safari
+          26.2+.
+        </p>
+      </section>
+
+      <section>
+        <h2>Basic Setup</h2>
+        <p>
+          Create your routes using the <code>route</code> helper function and
+          render them with the <code>Router</code> component:
+        </p>
+        <CodeBlock language="tsx">{`import { Router, route, Outlet } from "@funstack/router";
+
+// Define your page components
+function Home() {
+  return <h1>Welcome Home</h1>;
+}
+
+function About() {
+  return <h1>About Us</h1>;
+}
+
+function Layout() {
+  return (
+    <div>
+      <nav>
+        <a href="/">Home</a>
+        <a href="/about">About</a>
+      </nav>
+      <Outlet />
+    </div>
+  );
+}
+
+// Define your routes
+const routes = [
+  route({
+    path: "/",
+    component: Layout,
+    children: [
+      route({ path: "/", component: Home }),
+      route({ path: "/about", component: About }),
+    ],
+  }),
+];
+
+// Render the router
+function App() {
+  return <Router routes={routes} />;
+}`}</CodeBlock>
+      </section>
+
+      <section>
+        <h2>Route Parameters</h2>
+        <p>
+          Define dynamic segments in your paths using the <code>:param</code>{" "}
+          syntax. Route components receive parameters via the{" "}
+          <code>params</code> prop, which is fully typed based on the path
+          pattern:
+        </p>
+        <CodeBlock language="tsx">{`import { route } from "@funstack/router";
+
+function UserProfile({ params }: { params: { userId: string } }) {
+  return <h1>User: {params.userId}</h1>;
+}
+
+const routes = [
+  route({
+    path: "/users/:userId",
+    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>
+        <h2>Data Loading</h2>
+        <p>
+          Use the <code>loader</code> option to fetch data before rendering a
+          route. The component receives both <code>data</code> (from the loader)
+          and <code>params</code> (from the URL) as props:
+        </p>
+        <CodeBlock language="tsx">{`import { route } from "@funstack/router";
+
+interface User {
+  id: string;
+  name: string;
+}
+
+function UserProfilePage({
+  data,
+  params,
+}: {
+  data: Promise<User>;
+  params: { userId: string };
+}) {
+  const user = use(data);
+  return (
+    <Suspense fallback={<div>Loading...</div>}>
+      <UserProfile user={user} params={params} />
+    </Suspense>
+  );
+}
+
+function UserProfile({
+  user,
+  params,
+}: {
+  user: User;
+  params: { userId: string };
+}) {
+  return (
+    <div>
+      <h1>{user.name}</h1>
+      <p>User ID: {params.userId}</p>
+    </div>
+  );
+}
+
+const userRoute = route({
+  path: "/users/:userId",
+  component: UserProfilePage,
+  loader: async ({ params }): Promise<User> => {
+    const response = await fetch(\`/api/users/\${params.userId}\`);
+    return response.json();
+  },
+});`}</CodeBlock>
+      </section>
+    </div>
+  );
+}

package/dist/docs/LearnNavigationApiPage.tsx

@@ -0,0 +1,255 @@
+import { CodeBlock } from "../components/CodeBlock.js";
+
+export function LearnNavigationApiPage() {
+  return (
+    <div className="learn-content">
+      <h2>Navigation API</h2>
+
+      <p className="page-intro">
+        FUNSTACK Router is built on the{" "}
+        <a
+          href="https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          Navigation API
+        </a>
+        , a modern browser API that provides a unified way to handle navigation.
+        This guide explains the key differences from the older History API and
+        the benefits this brings to your application.
+      </p>
+
+      <section>
+        <h3>History API Limitations</h3>
+        <p>
+          The History API has been the foundation of single-page application
+          routing for years, but it comes with significant limitations that make
+          building routers more complex than necessary.
+        </p>
+        <p>
+          <strong>Reactive, not proactive:</strong> The <code>popstate</code>{" "}
+          event fires <em>after</em> navigation has already occurred. This makes
+          it difficult to intercept navigation, perform async operations like
+          data fetching, or cancel navigation based on conditions.
+        </p>
+        <CodeBlock language="typescript">{`// History API: popstate fires AFTER navigation
+window.addEventListener("popstate", (event) => {
+  // Too late! The URL has already changed.
+  // We can only react to what happened.
+  console.log("Navigated to:", location.pathname);
+});
+
+// For programmatic navigation, we must manually call pushState
+// AND then update the UI ourselves
+history.pushState(null, "", "/new-page");
+updateUI(); // Manually trigger UI update`}</CodeBlock>
+        <p>
+          <strong>Fragmented event model:</strong> Different navigation types
+          require different handling. Browser back/forward triggers{" "}
+          <code>popstate</code>, but <code>pushState</code> and{" "}
+          <code>replaceState</code> don't trigger any events. This leads to
+          scattered navigation logic.
+        </p>
+        <p>
+          <strong>Custom Link components required:</strong> Since clicking an{" "}
+          <code>{"<a>"}</code> tag causes a full page reload, routers must
+          provide custom <code>{"<Link>"}</code> components that intercept
+          clicks and call <code>pushState</code> instead.
+        </p>
+      </section>
+
+      <section>
+        <h3>The Navigation API Paradigm</h3>
+        <p>
+          The Navigation API fundamentally changes how navigation works by
+          providing a single <code>navigate</code> event that fires{" "}
+          <em>before</em> navigation commits. This allows routers to intercept
+          and handle navigation declaratively.
+        </p>
+        <CodeBlock language="typescript">{`// Navigation API: navigate event fires BEFORE navigation
+navigation.addEventListener("navigate", (event) => {
+  // Navigation hasn't happened yet - we can intercept it!
+  const url = new URL(event.destination.url);
+
+  // Check the navigation type
+  console.log(event.navigationType); // "push", "replace", "reload", or "traverse"
+
+  // Intercept and handle with async operations
+  event.intercept({
+    async handler() {
+      // Fetch data, render components, etc.
+      const data = await fetchPageData(url.pathname);
+      renderPage(data);
+      // Navigation completes when handler resolves
+    }
+  });
+});`}</CodeBlock>
+        <p>Key benefits of this approach:</p>
+        <ul>
+          <li>
+            <strong>Single unified event</strong> &mdash; All navigation types
+            (link clicks, back/forward, programmatic) trigger the same{" "}
+            <code>navigate</code> event
+          </li>
+          <li>
+            <strong>Interception with async support</strong> &mdash; The{" "}
+            <code>intercept()</code> method lets you run async handlers before
+            navigation completes
+          </li>
+          <li>
+            <strong>Built-in navigation type detection</strong> &mdash;{" "}
+            <code>event.navigationType</code> tells you exactly what kind of
+            navigation occurred
+          </li>
+        </ul>
+      </section>
+
+      <section>
+        <h3>
+          Native <code>{"<a>"}</code> Elements for SPA Links
+        </h3>
+        <p>
+          One of the most practical benefits of the Navigation API is that
+          standard <code>{"<a>"}</code> elements work for SPA navigation without
+          any special handling. The router intercepts navigation events from
+          native links automatically.
+        </p>
+        <CodeBlock language="tsx">{`// With FUNSTACK Router, native <a> elements just work!
+function Navigation() {
+  return (
+    <nav>
+      {/* These are standard HTML anchor tags */}
+      <a href="/home">Home</a>
+      <a href="/about">About</a>
+      <a href="/users/123">User Profile</a>
+    </nav>
+  );
+}
+
+// No special <Link> component needed for basic navigation
+// The router intercepts the navigate event and handles it as SPA navigation`}</CodeBlock>
+        <p>
+          This means you can use standard HTML in your components, and
+          navigation "just works". The router intercepts same-origin navigation
+          events and handles them without a full page reload.
+        </p>
+        <p>This approach has several advantages over custom Link components:</p>
+        <ul>
+          <li>
+            <strong>Standard HTML</strong> &mdash; No need to import and use
+            special components for every link
+          </li>
+          <li>
+            <strong>Progressive enhancement</strong> &mdash; Links work even if
+            JavaScript fails to load
+          </li>
+          <li>
+            <strong>Familiar patterns</strong> &mdash; Developers can use the{" "}
+            <code>{"<a>"}</code> tag they already know
+          </li>
+        </ul>
+      </section>
+
+      <section>
+        <h3>Accessing Navigation API Events</h3>
+        <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.
+        </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
+    navigation.addEventListener(
+      "navigatesuccess",
+      () => {
+        // Track page view for analytics
+        analytics.trackPageView(location.pathname);
+      },
+      { signal: controller.signal }
+    );
+
+    return () => controller.abort();
+  }, []);
+
+  return <Router routes={routes} />;
+}`}</CodeBlock>
+        <p>
+          The <code>navigatesuccess</code> event fires after navigation
+          completes successfully, making it ideal for post-navigation actions.
+          You can also use <code>navigation.transition</code> to track in-flight
+          navigations or implement loading indicators.
+        </p>
+        <p>
+          <strong>Note:</strong> be careful when adding event listeners for{" "}
+          <code>navigate</code> events since it may interfere with the router's
+          own handling. Consider using <code>onNavigate</code> prop on the{" "}
+          <code>{"<Router>"}</code> component for most use cases.
+        </p>
+      </section>
+
+      <section>
+        <h3>Other Navigation API Features</h3>
+        <p>
+          The Navigation API provides several advanced features that you can
+          leverage directly when needed:
+        </p>
+        <ul>
+          <li>
+            <strong>NavigationHistoryEntry</strong> &mdash; Each history entry
+            has a unique <code>id</code> and <code>key</code>, plus a{" "}
+            <code>dispose</code> event that fires when the entry is removed from
+            history
+          </li>
+          <li>
+            <strong>
+              Ephemeral <code>info</code>
+            </strong>{" "}
+            &mdash; Pass non-persisted context data during navigation via{" "}
+            <code>navigation.navigate(url, {"{ info }"}))</code>
+          </li>
+          <li>
+            <strong>navigation.entries()</strong> &mdash; Access the full
+            navigation history stack programmatically
+          </li>
+        </ul>
+        <p>
+          For more details, see the{" "}
+          <a
+            href="https://developer.mozilla.org/en-US/docs/Web/API/Navigation_API"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            MDN Navigation API documentation
+          </a>
+          .
+        </p>
+      </section>
+
+      <section>
+        <h3>Key Takeaways</h3>
+        <ul>
+          <li>
+            <strong>
+              Native <code>{"<a>"}</code> elements work
+            </strong>{" "}
+            &mdash; No special Link component required for SPA navigation; the
+            router intercepts standard anchor tags automatically
+          </li>
+          <li>
+            <strong>Direct API access when needed</strong> &mdash; Use events
+            like <code>navigatesuccess</code> for scroll restoration, analytics,
+            or other post-navigation actions
+          </li>
+        </ul>
+      </section>
+    </div>
+  );
+}