@hitch42/applet 0.1.0-beta.9 → 0.1.1-beta.10

package/scaffold/.agents/skills/tanstack-router/references/router-core/path-params.md

@@ -0,0 +1,383 @@
+---
+name: path-params
+description: >-
+  Dynamic path segments ($paramName), splat routes ($ / _splat),
+  optional params ({-$paramName}), prefix/suffix patterns ({$param}.ext),
+  useParams, params.parse/stringify, pathParamsAllowedCharacters,
+  i18n locale patterns.
+metadata:
+  type: sub-skill
+  library: tanstack-router
+  library_version: "1.171.15"
+requires:
+  - router-core
+sources:
+  - TanStack/router:docs/router/guide/path-params.md
+  - TanStack/router:docs/router/routing/routing-concepts.md
+  - TanStack/router:docs/router/guide/internationalization-i18n.md
+---
+
+# Path Params
+
+Path params capture dynamic URL segments into named variables. They are defined with a `$` prefix in the route path.
+
+> **CRITICAL**: Never interpolate params into the `to` string. Always use the `params` prop. This is the most common agent mistake for path params.
+
+> **CRITICAL**: Types are fully inferred. Never annotate the return of `useParams()`.
+
+## Dynamic Segments
+
+A segment prefixed with `$` captures text until the next `/`.
+
+```tsx
+// src/routes/posts.$postId.tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/posts/$postId")({
+  loader: async ({ params }) => {
+    // params.postId is string — fully inferred, do not annotate
+    return fetchPost(params.postId);
+  },
+  component: PostComponent,
+});
+
+function PostComponent() {
+  const { postId } = Route.useParams();
+  const data = Route.useLoaderData();
+  return (
+    <h1>
+      Post {postId}: {data.title}
+    </h1>
+  );
+}
+```
+
+Multiple dynamic segments work across path levels:
+
+```tsx
+// src/routes/teams.$teamId.members.$memberId.tsx
+export const Route = createFileRoute("/teams/$teamId/members/$memberId")({
+  component: MemberComponent,
+});
+
+function MemberComponent() {
+  const { teamId, memberId } = Route.useParams();
+  return (
+    <div>
+      Team {teamId}, Member {memberId}
+    </div>
+  );
+}
+```
+
+## Splat / Catch-All Routes
+
+A route with a path ending in `$` (bare dollar sign) captures everything after it. The value is available under the `_splat` key.
+
+```tsx
+// src/routes/files.$.tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/files/$")({
+  component: FileViewer,
+});
+
+function FileViewer() {
+  const { _splat } = Route.useParams();
+  // URL: /files/documents/report.pdf → _splat = "documents/report.pdf"
+  return <div>File path: {_splat}</div>;
+}
+```
+
+## Optional Params
+
+Optional params use `{-$paramName}` syntax. The segment may or may not be present. When absent, the value is `undefined`.
+
+```tsx
+// src/routes/posts.{-$category}.tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/posts/{-$category}")({
+  component: PostsComponent,
+});
+
+function PostsComponent() {
+  const { category } = Route.useParams();
+  // URL: /posts → category is undefined
+  // URL: /posts/tech → category is "tech"
+  return <div>{category ? `Posts in ${category}` : "All Posts"}</div>;
+}
+```
+
+Multiple optional params:
+
+```tsx
+// Matches: /posts, /posts/tech, /posts/tech/hello-world
+export const Route = createFileRoute("/posts/{-$category}/{-$slug}")({
+  component: PostComponent,
+});
+```
+
+### i18n with Optional Locale
+
+```tsx
+// src/routes/{-$locale}/about.tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/{-$locale}/about")({
+  component: AboutComponent,
+});
+
+function AboutComponent() {
+  const { locale } = Route.useParams();
+  const currentLocale = locale || "en";
+  return <h1>{currentLocale === "fr" ? "À Propos" : "About Us"}</h1>;
+}
+// Matches: /about, /en/about, /fr/about
+```
+
+## Prefix and Suffix Patterns
+
+Curly braces `{}` around `$paramName` allow text before or after the dynamic part within a single segment.
+
+### Prefix
+
+```tsx
+// src/routes/posts/post-{$postId}.tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/posts/post-{$postId}")({
+  component: PostComponent,
+});
+
+function PostComponent() {
+  const { postId } = Route.useParams();
+  // URL: /posts/post-123 → postId = "123"
+  return <div>Post ID: {postId}</div>;
+}
+```
+
+### Suffix
+
+```tsx
+// src/routes/files/{$fileName}[.]txt.tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/files/{$fileName}.txt")({
+  component: FileComponent,
+});
+
+function FileComponent() {
+  const { fileName } = Route.useParams();
+  // URL: /files/readme.txt → fileName = "readme"
+  return <div>File: {fileName}.txt</div>;
+}
+```
+
+### Combined Prefix + Suffix
+
+```tsx
+// URL: /users/user-456.json → userId = "456"
+export const Route = createFileRoute("/users/user-{$userId}.json")({
+  component: UserComponent,
+});
+
+function UserComponent() {
+  const { userId } = Route.useParams();
+  return <div>User: {userId}</div>;
+}
+```
+
+## Navigating with Path Params
+
+### Object Form
+
+```tsx
+import { Link } from "@tanstack/react-router";
+
+function PostLink({ postId }: { postId: string }) {
+  return (
+    <Link to="/posts/$postId" params={{ postId }}>
+      View Post
+    </Link>
+  );
+}
+```
+
+### Function Form (Preserves Other Params)
+
+```tsx
+function PostLink({ postId }: { postId: string }) {
+  return (
+    <Link to="/posts/$postId" params={(prev) => ({ ...prev, postId })}>
+      View Post
+    </Link>
+  );
+}
+```
+
+### Programmatic Navigation
+
+```tsx
+import { useNavigate } from "@tanstack/react-router";
+
+function GoToPost({ postId }: { postId: string }) {
+  const navigate = useNavigate();
+
+  return (
+    <button
+      onClick={() => {
+        navigate({ to: "/posts/$postId", params: { postId } });
+      }}
+    >
+      Go to Post
+    </button>
+  );
+}
+```
+
+### Navigating with Optional Params
+
+```tsx
+// Include the optional param
+<Link to="/posts/{-$category}" params={{ category: 'tech' }}>
+  Tech Posts
+</Link>
+
+// Omit the optional param (renders /posts)
+<Link to="/posts/{-$category}" params={{ category: undefined }}>
+  All Posts
+</Link>
+```
+
+## Reading Params Outside Route Components
+
+### `useParams` with `from`
+
+```tsx
+import { useParams } from "@tanstack/react-router";
+
+function PostHeader() {
+  const { postId } = useParams({ from: "/posts/$postId" });
+  return <h2>Post {postId}</h2>;
+}
+```
+
+### `useParams` with `strict: false`
+
+```tsx
+function GenericBreadcrumb() {
+  const params = useParams({ strict: false });
+  // params is a union of all possible route params
+  return <span>{params.postId ?? "Home"}</span>;
+}
+```
+
+## Params in Loaders and `beforeLoad`
+
+```tsx
+export const Route = createFileRoute("/posts/$postId")({
+  beforeLoad: async ({ params }) => {
+    // params.postId available here
+    const canView = await checkPermission(params.postId);
+    if (!canView) throw redirect({ to: "/unauthorized" });
+  },
+  loader: async ({ params }) => {
+    return fetchPost(params.postId);
+  },
+});
+```
+
+## Allowed Characters
+
+By default, params are encoded with `encodeURIComponent`. Allow extra characters via router config:
+
+```tsx
+import { createRouter } from "@tanstack/react-router";
+
+const router = createRouter({
+  routeTree,
+  pathParamsAllowedCharacters: ["@", "+"],
+});
+```
+
+Allowed characters: `;`, `:`, `@`, `&`, `=`, `+`, `$`, `,`.
+
+## Common Mistakes
+
+### 1. CRITICAL (cross-skill): Interpolating path params into `to` string
+
+```tsx
+// WRONG — breaks type safety and param encoding
+<Link to={`/posts/${postId}`}>Post</Link>
+
+// CORRECT — use params prop
+<Link to="/posts/$postId" params={{ postId }}>Post</Link>
+```
+
+### 2. MEDIUM: Using `*` for splat routes instead of `$`
+
+TanStack Router uses `$` for splat routes. The captured value is under `_splat`, not `*`.
+
+```tsx
+// WRONG (React Router / other frameworks)
+// <Route path="/files/*" />
+
+// CORRECT (TanStack Router)
+// File: src/routes/files.$.tsx
+export const Route = createFileRoute("/files/$")({
+  component: () => {
+    const { _splat } = Route.useParams();
+    return <div>{_splat}</div>;
+  },
+});
+```
+
+> Note: `*` works in v1 for backwards compatibility but will be removed in v2. Always use `_splat`.
+
+### 3. MEDIUM: Using curly braces for basic dynamic segments
+
+Curly braces are ONLY for prefix/suffix patterns and optional params. Basic dynamic segments use bare `$`.
+
+```tsx
+// WRONG — braces not needed for basic params
+createFileRoute("/posts/{$postId}");
+
+// CORRECT — bare $ for basic dynamic segments
+createFileRoute("/posts/$postId");
+
+// CORRECT — braces for prefix pattern
+createFileRoute("/posts/post-{$postId}");
+
+// CORRECT — braces for optional param
+createFileRoute("/posts/{-$category}");
+```
+
+### 4. Params are always strings
+
+Path params are always parsed as strings. If you need a number, parse in the loader or component:
+
+```tsx
+export const Route = createFileRoute("/posts/$postId")({
+  loader: async ({ params }) => {
+    const id = parseInt(params.postId, 10);
+    if (isNaN(id)) throw notFound();
+    return fetchPost(id);
+  },
+});
+```
+
+You can also use `params.parse` and `params.stringify` on the route for bidirectional transformation:
+
+```tsx
+export const Route = createFileRoute("/posts/$postId")({
+  params: {
+    parse: (raw) => ({ postId: parseInt(raw.postId, 10) }),
+    stringify: (parsed) => ({ postId: String(parsed.postId) }),
+  },
+  loader: async ({ params }) => {
+    // params.postId is now number
+    return fetchPost(params.postId);
+  },
+});
+```

package/scaffold/.agents/skills/tanstack-router/references/router-core/search-params.md

@@ -0,0 +1,343 @@
+---
+name: search-params
+description: >-
+  validateSearch, search param validation with Zod/Valibot/ArkType adapters,
+  fallback(), search middlewares (retainSearchParams, stripSearchParams),
+  custom serialization (parseSearch, stringifySearch), search param
+  inheritance, loaderDeps for cache keys, reading and writing search params.
+metadata:
+  type: sub-skill
+  library: tanstack-router
+  library_version: "1.171.15"
+requires:
+  - router-core
+sources:
+  - TanStack/router:docs/router/guide/search-params.md
+  - TanStack/router:docs/router/how-to/setup-basic-search-params.md
+  - TanStack/router:docs/router/how-to/validate-search-params.md
+  - TanStack/router:docs/router/how-to/navigate-with-search-params.md
+  - TanStack/router:docs/router/how-to/share-search-params-across-routes.md
+  - TanStack/router:docs/router/guide/custom-search-param-serialization.md
+---
+
+# Search Params
+
+TanStack Router treats search params as JSON-first application state. They are automatically parsed from the URL into structured objects (numbers, booleans, arrays, nested objects) and validated via `validateSearch` on each route.
+
+> **CRITICAL**: When using `zodValidator()` and Zod v3, use `fallback()` from `@tanstack/zod-adapter`, NOT zod's `.catch()`. Using `.catch()` with the zod adapter makes the output type `unknown`, destroying type safety. This does not apply to Valibot or ArkType (which use their own fallback mechanisms). It also does not apply to Zod v4, which should use `.catch()` and not use the `zodValidator()`.
+> **CRITICAL**: Types are fully inferred. Never annotate the return of `useSearch()`.
+
+## Setup: Zod Adapter (Recommended)
+
+```bash
+npm install zod @tanstack/zod-adapter
+```
+
+```tsx
+// src/routes/products.tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { z } from "zod";
+
+const productSearchSchema = z.object({
+  page: z.number().default(1).catch(1),
+  filter: z.string().default(""),
+  sort: z.enum(["newest", "oldest", "price"]).default("newest").catch("newest"),
+});
+
+export const Route = createFileRoute("/products")({
+  validateSearch: productSearchSchema,
+  component: ProductsPage,
+});
+
+function ProductsPage() {
+  // page: number, filter: string, sort: 'newest' | 'oldest' | 'price'
+  // ALL INFERRED — do not annotate
+  const { page, filter, sort } = Route.useSearch();
+
+  return (
+    <div>
+      <p>
+        Page {page}, filter: {filter}, sort: {sort}
+      </p>
+    </div>
+  );
+}
+```
+
+## Reading Search Params
+
+### In Route Components: `Route.useSearch()`
+
+```tsx
+function ProductsPage() {
+  const { page, sort } = Route.useSearch();
+  return <div>Page {page}</div>;
+}
+```
+
+### In Code-Split Components: `getRouteApi()`
+
+```tsx
+import { getRouteApi } from "@tanstack/react-router";
+
+const routeApi = getRouteApi("/products");
+
+function ProductFilters() {
+  const { sort } = routeApi.useSearch();
+  return <select value={sort}>{/* options */}</select>;
+}
+```
+
+### From Any Component: `useSearch({ from })`
+
+```tsx
+import { useSearch } from "@tanstack/react-router";
+
+function SortIndicator() {
+  const { sort } = useSearch({ from: "/products" });
+  return <span>Sorted by: {sort}</span>;
+}
+```
+
+### Loose Access: `useSearch({ strict: false })`
+
+```tsx
+function GenericPaginator() {
+  const search = useSearch({ strict: false });
+  // search.page is number | undefined (union of all routes)
+  return <span>Page: {search.page ?? 1}</span>;
+}
+```
+
+## Writing Search Params
+
+### Link with Function Form (Preserves Existing Params)
+
+```tsx
+import { Link } from "@tanstack/react-router";
+
+function Pagination() {
+  return (
+    <Link from="/products" search={(prev) => ({ ...prev, page: prev.page + 1 })}>
+      Next Page
+    </Link>
+  );
+}
+```
+
+### Link with Object Form (Replaces All Params)
+
+```tsx
+<Link to="/products" search={{ page: 1, filter: "", sort: "newest" }}>
+  Reset
+</Link>
+```
+
+### Programmatic: `useNavigate()`
+
+```tsx
+import { useNavigate } from "@tanstack/react-router";
+
+function SortDropdown() {
+  const navigate = useNavigate({ from: "/products" });
+
+  return (
+    <select
+      onChange={(e) => {
+        navigate({
+          search: (prev) => ({ ...prev, sort: e.target.value, page: 1 }),
+        });
+      }}
+    >
+      <option value="newest">Newest</option>
+      <option value="price">Price</option>
+    </select>
+  );
+}
+```
+
+## Search Param Inheritance
+
+Parent route search params are automatically merged into child routes:
+
+```tsx
+// src/routes/shop.tsx — parent defines shared params
+import { createFileRoute } from "@tanstack/react-router";
+import { z } from "zod";
+
+const shopSearchSchema = z.object({
+  currency: z.enum(["USD", "EUR"]).default("USD").catch("USD"),
+});
+
+export const Route = createFileRoute("/shop")({
+  validateSearch: shopSearchSchema,
+});
+```
+
+```tsx
+// src/routes/shop/products.tsx — child inherits currency
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/shop/products")({
+  component: ShopProducts,
+});
+
+function ShopProducts() {
+  // currency is available here from parent — fully typed
+  const { currency } = Route.useSearch();
+  return <div>Currency: {currency}</div>;
+}
+```
+
+## Search Middlewares
+
+### `retainSearchParams` — Keep Params Across Navigation
+
+```tsx
+import { createRootRoute, retainSearchParams } from "@tanstack/react-router";
+import { z } from "zod";
+
+const rootSearchSchema = z.object({
+  debug: z.boolean().optional(),
+});
+
+export const Route = createRootRoute({
+  validateSearch: rootSearchSchema,
+  search: {
+    middlewares: [retainSearchParams(["debug"])],
+  },
+});
+```
+
+### `stripSearchParams` — Remove Default Values from URL
+
+```tsx
+import { createFileRoute, stripSearchParams } from "@tanstack/react-router";
+import { z } from "zod";
+
+const defaults = { sort: "newest", page: 1 };
+
+const searchSchema = z.object({
+  sort: z.string().default(defaults.sort),
+  page: z.number().default(defaults.page),
+});
+
+export const Route = createFileRoute("/items")({
+  validateSearch: searchSchema,
+  search: {
+    middlewares: [stripSearchParams(defaults)],
+  },
+});
+```
+
+### Chaining Middlewares
+
+```tsx
+export const Route = createFileRoute("/search")({
+  validateSearch: z.object({
+    retainMe: z.string().optional(),
+    arrayWithDefaults: z.string().array().default(["foo", "bar"]),
+    required: z.string(),
+  }),
+  search: {
+    middlewares: [
+      retainSearchParams(["retainMe"]),
+      stripSearchParams({ arrayWithDefaults: ["foo", "bar"] }),
+    ],
+  },
+});
+```
+
+## Custom Serialization
+
+Override the default JSON serialization at the router level:
+
+```tsx
+import { createRouter, parseSearchWith, stringifySearchWith } from "@tanstack/react-router";
+
+const router = createRouter({
+  routeTree,
+  // Example: use JSURL2 for compact, human-readable URLs
+  parseSearch: parseSearchWith(parse),
+  stringifySearch: stringifySearchWith(stringify),
+});
+```
+
+## Using Search Params in Loaders via `loaderDeps`
+
+```tsx
+export const Route = createFileRoute("/products")({
+  validateSearch: productSearchSchema,
+  // Pick ONLY the params the loader needs — not the entire search object
+  loaderDeps: ({ search }) => ({ page: search.page }),
+  loader: async ({ deps }) => {
+    return fetchProducts({ page: deps.page });
+  },
+});
+```
+
+## Common Mistakes
+
+### 1. HIGH: Using zod v3's `.catch()` with `zodValidator()` instead of adapter `fallback()`
+
+```tsx
+// WRONG — .catch() with zodValidator makes the type unknown
+const schema = z.object({ page: z.number().catch(1) });
+validateSearch: zodValidator(schema); // page is typed as unknown!
+
+// CORRECT — fallback() preserves the inferred type
+import { fallback } from "@tanstack/zod-adapter";
+const schema = z.object({ page: fallback(z.number(), 1) });
+```
+
+**Important:** This only applies when using Zod v3, not when using Zod v4. For v4, using `.catch()` is correct.
+
+### 2. HIGH: Returning entire search object from `loaderDeps`
+
+```tsx
+// WRONG — loader re-runs on ANY search param change
+loaderDeps: ({ search }) => search;
+
+// CORRECT — loader only re-runs when page changes
+loaderDeps: ({ search }) => ({ page: search.page });
+```
+
+### 3. HIGH: Passing Date objects in search params
+
+```tsx
+// WRONG — Date does not serialize correctly to JSON in URLs
+<Link search={{ startDate: new Date() }}>
+
+// CORRECT — convert to ISO string
+<Link search={{ startDate: new Date().toISOString() }}>
+```
+
+### 4. MEDIUM: Parent route missing `validateSearch` blocks inheritance
+
+```tsx
+// WRONG — child cannot access shared params
+export const Route = createRootRoute({
+  component: RootComponent,
+  // no validateSearch!
+});
+
+// CORRECT — parent must define validateSearch for children to inherit
+export const Route = createRootRoute({
+  validateSearch: globalSearchSchema,
+  component: RootComponent,
+});
+```
+
+### 5. HIGH (cross-skill): Using search as object instead of function loses params
+
+```tsx
+// WRONG — replaces ALL search params, losing any existing ones
+<Link to="." search={{ page: 2 }}>Page 2</Link>
+
+// CORRECT — preserves existing params, updates only page
+<Link to="." search={(prev) => ({ ...prev, page: 2 })}>Page 2</Link>
+```
+
+## References
+
+- [Validation Patterns Reference](https://tanstack.com/router/latest/docs/framework/react/guide/search-params) — comprehensive patterns for all validation libraries