npm - @kode4/react-foundation - Versions diffs - 0.1.0 - Mend

@kode4/react-foundation 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (126) hide show

package/DESIGN-SYSTEM.md +190 -0
package/INSTRUCTIONS.md +694 -0
package/LICENSE +21 -0
package/README.md +53 -0
package/errors.d.ts +24 -0
package/forms/Form/Form.d.ts +30 -0
package/forms/Form/index.d.ts +1 -0
package/forms/index.d.ts +1 -0
package/hooks/index.d.ts +1 -0
package/hooks/useMediaQuery.d.ts +8 -0
package/index.d.ts +24 -0
package/index.js +1679 -0
package/index.js.map +1 -0
package/internal/env.d.ts +1 -0
package/internal/registry.d.ts +3 -0
package/internal/type-utils.d.ts +6 -0
package/layout/AppLayout/AppLayout.d.ts +18 -0
package/layout/AppLayout/index.d.ts +1 -0
package/layout/CenteredLayout/CenteredLayout.d.ts +12 -0
package/layout/CenteredLayout/index.d.ts +1 -0
package/layout/Columns/Columns.d.ts +35 -0
package/layout/Columns/index.d.ts +1 -0
package/layout/Container/Container.d.ts +5 -0
package/layout/Container/index.d.ts +1 -0
package/layout/DashboardGrid/DashboardGrid.d.ts +37 -0
package/layout/DashboardGrid/index.d.ts +1 -0
package/layout/FillHeight/FillHeight.d.ts +16 -0
package/layout/FillHeight/index.d.ts +1 -0
package/layout/Footer/Footer.d.ts +5 -0
package/layout/Footer/index.d.ts +1 -0
package/layout/Header/Header.d.ts +13 -0
package/layout/Header/index.d.ts +1 -0
package/layout/SideBar/SideBar.d.ts +6 -0
package/layout/SideBar/index.d.ts +1 -0
package/layout/SiteLayout/SiteLayout.d.ts +27 -0
package/layout/SiteLayout/index.d.ts +1 -0
package/layout/SkipLink/SkipLink.d.ts +9 -0
package/layout/SkipLink/index.d.ts +1 -0
package/layout/TopBar/TopBar.d.ts +32 -0
package/layout/TopBar/index.d.ts +1 -0
package/layout/index.d.ts +12 -0
package/package.json +52 -0
package/query/index.d.ts +1 -0
package/query/sort.d.ts +19 -0
package/router/DefaultErrorBoundary.d.ts +5 -0
package/router/TypedLink/TypedLink.d.ts +22 -0
package/router/TypedLink/index.d.ts +1 -0
package/router/adapter.d.ts +27 -0
package/router/chain.d.ts +17 -0
package/router/context.d.ts +24 -0
package/router/createAppRouter.d.ts +15 -0
package/router/defineRoute.d.ts +11 -0
package/router/index.d.ts +11 -0
package/router/menu.d.ts +51 -0
package/router/pathTo.d.ts +21 -0
package/router/types.d.ts +72 -0
package/router/useRoute.d.ts +22 -0
package/style.css +3 -0
package/theme/ModeToggle/ModeToggle.d.ts +6 -0
package/theme/ModeToggle/index.d.ts +1 -0
package/theme/ThemeProvider/ThemeProvider.d.ts +25 -0
package/theme/ThemeProvider/index.d.ts +1 -0
package/theme/Toaster/Toaster.d.ts +9 -0
package/theme/Toaster/index.d.ts +2 -0
package/theme/Toaster/toast.d.ts +38 -0
package/theme/index.d.ts +3 -0
package/ui/Accordion/Accordion.d.ts +7 -0
package/ui/Accordion/index.d.ts +1 -0
package/ui/Alert/Alert.d.ts +11 -0
package/ui/Alert/index.d.ts +1 -0
package/ui/AlertDialog/AlertDialog.d.ts +19 -0
package/ui/AlertDialog/index.d.ts +1 -0
package/ui/Avatar/Avatar.d.ts +7 -0
package/ui/Avatar/index.d.ts +1 -0
package/ui/AwaitErrorBlock/AwaitErrorBlock.d.ts +11 -0
package/ui/AwaitErrorBlock/index.d.ts +1 -0
package/ui/Badge/Badge.d.ts +10 -0
package/ui/Badge/index.d.ts +1 -0
package/ui/Button/Button.d.ts +13 -0
package/ui/Button/index.d.ts +1 -0
package/ui/Card/Card.d.ts +11 -0
package/ui/Card/index.d.ts +1 -0
package/ui/Checkbox/Checkbox.d.ts +5 -0
package/ui/Checkbox/index.d.ts +1 -0
package/ui/Command/Command.d.ts +19 -0
package/ui/Command/index.d.ts +1 -0
package/ui/Dialog/Dialog.d.ts +17 -0
package/ui/Dialog/index.d.ts +1 -0
package/ui/DropdownMenu/DropdownMenu.d.ts +28 -0
package/ui/DropdownMenu/index.d.ts +1 -0
package/ui/ErrorBlock/ErrorBlock.d.ts +21 -0
package/ui/ErrorBlock/index.d.ts +1 -0
package/ui/Input/Input.d.ts +4 -0
package/ui/Input/index.d.ts +1 -0
package/ui/Label/Label.d.ts +5 -0
package/ui/Label/index.d.ts +1 -0
package/ui/Pagination/Pagination.d.ts +17 -0
package/ui/Pagination/index.d.ts +1 -0
package/ui/Popover/Popover.d.ts +7 -0
package/ui/Popover/index.d.ts +1 -0
package/ui/Progress/Progress.d.ts +16 -0
package/ui/Progress/index.d.ts +1 -0
package/ui/RadioGroup/RadioGroup.d.ts +7 -0
package/ui/RadioGroup/index.d.ts +1 -0
package/ui/Select/Select.d.ts +16 -0
package/ui/Select/index.d.ts +1 -0
package/ui/Separator/Separator.d.ts +5 -0
package/ui/Separator/index.d.ts +1 -0
package/ui/Sheet/Sheet.d.ts +17 -0
package/ui/Sheet/index.d.ts +1 -0
package/ui/Skeleton/Skeleton.d.ts +4 -0
package/ui/Skeleton/index.d.ts +1 -0
package/ui/Spinner/Spinner.d.ts +35 -0
package/ui/Spinner/index.d.ts +1 -0
package/ui/Switch/Switch.d.ts +5 -0
package/ui/Switch/index.d.ts +1 -0
package/ui/Table/Table.d.ts +11 -0
package/ui/Table/index.d.ts +1 -0
package/ui/Tabs/Tabs.d.ts +8 -0
package/ui/Tabs/index.d.ts +1 -0
package/ui/Textarea/Textarea.d.ts +4 -0
package/ui/Textarea/index.d.ts +1 -0
package/ui/Tooltip/Tooltip.d.ts +7 -0
package/ui/Tooltip/index.d.ts +1 -0
package/ui/index.d.ts +29 -0
package/utils.d.ts +8 -0

package/INSTRUCTIONS.md ADDED Viewed

@@ -0,0 +1,694 @@
+# Instructions — building apps with `@kode4/react-foundation`
+This guide is written for someone (human or AI agent) **consuming** the library
+to build an application. It captures the patterns, mental model, and idioms the
+library expects, with copy-pasteable examples. If you follow these patterns the
+app will be idiomatic, type-safe, and themeable.
+> **Companion docs.** `DESIGN-SYSTEM.md` is the theming/token contract.
+> `roadmap.md` lists planned components. `CLAUDE.md` is the primer for working
+> *inside* the library repo (different audience — internal conventions). This
+> file is the *consumer* contract and must be kept in sync as the library grows.
+> **Import paths.** A published consumer imports from the package name and loads
+> the stylesheet once:
+>
+> ```ts
+> import { Button, defineRoute, useRoute, ThemeProvider } from '@kode4/react-foundation';
+> import '@kode4/react-foundation/styles.css'; // once, near the app root
+> ```
+>
+> Inside *this* repo the demo consumes the same barrel via the local alias
+> `@/lib` (and the barrel side-effect-imports the CSS, so no separate style
+> import is needed locally). Every example below uses `@kode4/react-foundation`;
+> substitute `@/lib` when working in-repo.
+---
+## 1. Mental model (read this first)
+The library is three things behind one barrel:
+1. **A typed router** — a thin layer over React Router DOM v7's data router. You
+   declare each route once with `defineRoute` (path, Zod schemas for
+   params/search, a loader, the component, menu/tabs metadata). From those
+   declarations the library derives the router config and a registry that powers
+   typed links and menus. **Routes are the single source of truth.**
+2. **A themed UI component library** — 30+ components (shadcn/ui as the design
+   blueprint) built on Radix primitives, styled entirely through CSS variables.
+3. **A design system** — semantic design tokens with light/dark mode; everything
+   themeable by re-declaring CSS variables, no rebuild.
+Two rules that drive everything:
+- **Read route state only through `useRoute(routeDef)`** — never reach into React
+  Router hooks for params/search you've declared. `useRoute` returns them parsed
+  and typed.
+- **Never hand-write URLs** — use `TypedLink` / `pathTo`, which enforce params
+  and search against the route's schemas.
+---
+## 2. App bootstrap
+Compose the providers in this order (outermost → innermost). `ThemeProvider`
+must wrap everything so the mode class is on `<html>` before anything paints;
+`Toaster` is a sibling of the router.
+```tsx
+import { QueryClientProvider } from '@tanstack/react-query';
+import { Suspense } from 'react';
+import { RouterProvider } from 'react-router-dom';
+import { SpinnerBlock, ThemeProvider, Toaster } from '@kode4/react-foundation';
+import '@kode4/react-foundation/styles.css';
+import { router } from './app/router';
+import { queryClient } from './query/client';
+export function App() {
+  return (
+    <ThemeProvider>
+      <QueryClientProvider client={queryClient}>
+        <Suspense fallback={<SpinnerBlock label="Loading…" />}>
+          <RouterProvider router={router} />
+        </Suspense>
+        <Toaster />
+      </QueryClientProvider>
+    </ThemeProvider>
+  );
+}
+```
+**Fonts.** The design system's `--font-sans` token points at `'Open Sans
+Variable'` first, then system fallbacks. Load the font (self-hosted via
+`@fontsource-variable/open-sans` keeps it GDPR-clean and offline) or override
+`--font-sans` in your app CSS. See `DESIGN-SYSTEM.md` → Typography.
+---
+## 3. The typed router
+### 3.1 Declaring a route
+`defineRoute` is the unit of declaration. Co-locate it with its page component.
+```tsx
+import { z } from 'zod';
+import { defineRoute, useRoute } from '@kode4/react-foundation';
+import { fetchUser } from './api';
+const userParamsSchema = z.object({
+  id: z.coerce.number().int().positive(), // URL params are STRINGS — coerce!
+});
+export const userDetailRoute = defineRoute({
+  path: 'users/:id',
+  component: UserDetailPage,
+  params: userParamsSchema,
+  loader: async ({ params }) => ({ user: await fetchUser(params.id) }),
+});
+export function UserDetailPage() {
+  const { params, data } = useRoute(userDetailRoute); // params.id is `number`
+  return <h1>{data.user.name} (#{params.id})</h1>;
+}
+```
+`defineRoute` accepts: `path`, `component`, `params` (Zod), `search` (Zod),
+`loader`, `menu` (`{ label, icon }`), `tabs`, and `children` (nested routes).
+Everything is inferred from the schemas + loader — no manual generics.
+### 3.2 Params vs. search
+- **Path params** (`:id`) are always strings in the URL — wrap numeric ones in
+  `z.coerce.number()`. Validation runs once at the loader boundary; invalid input
+  yields a `400 Response`.
+- **Search params** are typically `optional()` or `.default(...)`:
+  ```ts
+  const search = z.object({ q: z.string().optional(), tab: z.enum(TABS).default('overview') });
+  // route: defineRoute({ ..., search })
+  // read:  const { search } = useRoute(route);  // search.tab is the enum
+  ```
+- **Writing search state**: use React Router's `useSearchParams` setter with
+  `{ replace: true }` — never `window.history`.
+  ```tsx
+  const [, setSearchParams] = useSearchParams();
+  setSearchParams((prev) => { prev.set('q', value); return prev; }, { replace: true });
+  ```
+### 3.3 Loaders, guards, and middleware chains
+A loader is `({ params, search, context, request }) => data`. `context` carries
+`queryClient` plus whatever your app augments in (e.g. `auth` — see 3.6).
+Simple loader: a plain async function (see 3.1). For cross-cutting concerns
+(auth, roles) compose typed middleware with `chain()`; each step's return value
+**merges** into the accumulated, inferred `data`:
+```tsx
+import { chain, defineRoute, useRoute } from '@kode4/react-foundation';
+import { requireAuth, requireRole } from './auth/guards';
+export const adminRoute = defineRoute({
+  path: 'admin',
+  component: AdminPage,
+  loader: chain()
+    .use(requireAuth)             // contributes { user }
+    .use(requireRole('admin'))    // requires { user }, contributes nothing
+    .use(() => ({ metrics: getMetrics() }))
+    .build(),
+});
+function AdminPage() {
+  const { data } = useRoute(adminRoute); // data: { user, metrics } — fully typed
+}
+```
+Write guards as `LoaderMiddleware<Contributes, Requires>`:
+```ts
+import { redirect } from 'react-router-dom';
+import type { LoaderMiddleware } from '@kode4/react-foundation';
+export const requireAuth: LoaderMiddleware<{ user: User }> = ({ context, request }) => {
+  const user = context.auth.current;
+  if (!user) {
+    const url = new URL(request.url);
+    throw redirect(`/login?next=${encodeURIComponent(url.pathname + url.search)}`);
+  }
+  return { user };
+};
+// Factory that REQUIRES a prior step's { user }:
+export function requireRole(role: Role): LoaderMiddleware<void, { user: User }> {
+  return ({ data }) => {
+    if (data.user.role !== role) throw new Response('Forbidden', { status: 403 });
+  };
+}
+```
+### 3.4 Linking — never hand-write URLs
+```tsx
+import { TypedLink, pathTo } from '@kode4/react-foundation';
+<TypedLink route={userDetailRoute} params={{ id: 7 }}>Open user 7</TypedLink>
+<TypedLink route={projectDetailRoute} params={{ id }} search={{ tab: 'tasks' }}>Tasks</TypedLink>
+const href = pathTo(userDetailRoute, { params: { id: 7 } }); // for non-link uses
+```
+`params`/`search` are checked against the route's schemas at the type level.
+`pathTo` drops search args that fail their schema (with a dev-mode warning).
+### 3.5 Tabs
+Tabs are just a search param plus `tabs` metadata on the route. The metadata
+drives rendering; the search param holds the active tab:
+```tsx
+const TABS = ['overview', 'tasks', 'team'] as const;
+export const projectDetailRoute = defineRoute({
+  path: 'projects/:id',
+  params: z.object({ id: z.coerce.number() }),
+  search: z.object({ tab: z.enum(TABS).default('overview') }),
+  tabs: TABS.map((id) => ({ id, label: id[0].toUpperCase() + id.slice(1) })),
+  component: ProjectDetailPage,
+});
+// In the page: const { search } = useRoute(route); link tabs with <TypedLink ... search={{ tab }} />
+```
+### 3.6 Assembling the router + injecting app services
+Build the router from your top-level routes. Pass `queryClient` and any app
+services (here `auth`) as context; you can also override `hydrateFallback` /
+`errorBoundary` here.
+```ts
+import { createAppRouter } from '@kode4/react-foundation';
+export const router = createAppRouter([shellRoute, loginRoute], {
+  queryClient,
+  auth: authState,
+});
+```
+Tell the library's typed `context` about your services by **augmenting the
+declaring module** (not the barrel):
+```ts
+// app/context.ts — import this once at startup (e.g. from main.tsx)
+import type { AuthState } from './auth';
+declare module '@kode4/react-foundation/router/context' {
+  interface AppContext {
+    auth: AuthState; // now context.auth is typed in every loader
+  }
+}
+```
+> Pitfalls: a route not included in the array passed to `createAppRouter` makes
+> `pathTo()` throw. Don't call `pathTo()`/`resolveMenu()` at module load — the
+> registry fills when the router config is built.
+---
+## 4. Menus
+The menu is a hand-authored `MenuNode[]` tree — the single source of truth for
+navigation. Top-level nodes render in the `TopBar`; their `children` render in
+the `SideBar` when that top-level item is active.
+```tsx
+import type { MenuNode } from '@kode4/react-foundation';
+export const menuTree: MenuNode[] = [
+  { route: homeRoute },
+  { route: usersRoute, label: 'Manage', children: [
+    { route: usersRoute },
+    { route: settingsRoute, children: [{ route: profileRoute }, { route: securityRoute }] },
+  ]},
+  { group: 'Reports', children: [
+    { content: <small>Section note (arbitrary node)</small> },
+    'separator',
+    { route: reportRoute },
+  ]},
+];
+```
+Node kinds: `{ route, label?, icon?, children? }`, `{ group, children }`,
+`'separator'`, and `{ content }` (arbitrary JSX). Labels default to the route's
+`menu.label`. Resolve a tree to renderable items with `resolveMenu(menuTree)`.
+---
+## 5. App chrome & layout
+There is no monolithic `<Shell>` — you **compose** the chrome from primitives, so
+you control the structure. The canonical pattern:
+```tsx
+import {
+  AppLayout, TopBar, SideBar, SkipLink, ModeToggle,
+  resolveMenu, findActiveTopItem,
+} from '@kode4/react-foundation';
+function Shell() {
+  const { pathname } = useLocation();
+  const topMenu = useMemo(() => resolveMenu(menuTree), []);
+  const sideItems = useMemo(
+    () => findActiveTopItem(topMenu, pathname)?.children ?? [],
+    [topMenu, pathname],
+  );
+  return (
+    <>
+      <SkipLink />
+      <AppLayout
+        header={
+          <TopBar
+            items={topMenu}
+            brand={<Link to="/">My App</Link>}
+            mobileMenu={topMenu}              // full tree shown in the mobile drawer
+            end={<ModeToggle />}
+          />
+        }>
+        <div className="app-body">
+          <SideBar items={sideItems} />
+          <main><Outlet /></main>
+        </div>
+      </AppLayout>
+    </>
+  );
+}
+// Use this component as the `component` of a parent route whose `children` are
+// the in-shell pages.
+```
+### Responsive navigation is automatic (mobile is a first-class requirement)
+`TopBar` is **content-aware**: it measures whether its inline nav fits and
+collapses into a hamburger + left-side drawer when it doesn't — so phones and
+iPads in portrait get a usable drawer out of the box, with no per-app work.
+- `mobileMenu` — the menu shown in the drawer; pass the full nested tree so
+  mobile users reach every page (the drawer renders a `SideBar` internally).
+- `mobileQuery` — a *hard floor* (default `'(max-width: 768px)'`): at/below it the
+  nav always collapses; above it, collapse happens automatically on overflow.
+  Pass `null` to rely purely on overflow detection.
+- On mobile, hide your in-content `SideBar` (the drawer already carries the full
+  nav) — e.g. `@media (max-width: 768px) { .app-body > .k4-sidebar { display: none } }`.
+**Every component is expected to work on touch.** Avoid hover-only affordances as
+the sole interaction.
+### Layout frames & primitives
+- **Frames**: `AppLayout` (full-height app shell with a sticky `header` slot),
+  `SiteLayout` (constrained marketing-style column), `CenteredLayout` (centered
+  card, e.g. login).
+- **Primitives**: `Container`, `Columns` (left/right asides + content; supports
+  independent scroll regions via a `scroll` mode), `FillHeight`, `Header`,
+  `Footer`, `TopBar`, `SideBar`, `SkipLink`.
+- **DashboardGrid** — an equal-column grid with a base row height, for dashboards.
+  Drop blocks (typically `Card`s) in via `DashboardGridItem`; each defaults to one
+  cell and can span columns/rows. Spans are clamped to the column count (never
+  overflow), and the grid collapses to a single column on phones.
+  ```tsx
+  <DashboardGrid columns={4}>          {/* columns + rowHeight have sensible defaults */}
+    <DashboardGridItem colSpan={2}><Card>…</Card></DashboardGridItem>   {/* wide */}
+    <DashboardGridItem><Card>…</Card></DashboardGridItem>              {/* 1×1 default */}
+    <DashboardGridItem colSpan={2} rowSpan={2}><Card>…</Card></DashboardGridItem> {/* big */}
+  </DashboardGrid>
+  ```
+---
+## 6. UI components
+All components follow the shadcn/ui blueprint, are built on Radix primitives, and
+expose their props type. Two conventions matter:
+### 6.1 `asChild`
+Trigger-style components accept Radix's `asChild` to merge their behavior onto
+your own element (commonly a `Button`):
+```tsx
+<DialogTrigger asChild><Button appearance="outline">Open</Button></DialogTrigger>
+```
+### 6.2 The two-axis variant model (Button, Alert, Toast, Badge)
+Color and fill are **orthogonal**:
+- **`variant`** = color: `default` (neutral), `primary`, `secondary`,
+  `destructive`, `success` — plus `ghost` and `link` on `Button`.
+- **`appearance`** = `filled` (default) or `outline`. `outline` is an
+  *appearance*, not a variant, and composes with every color.
+- **`size`** (Button): `default`, `sm`, `lg`, `icon`.
+```tsx
+<Button>Save</Button>                                  {/* neutral, filled */}
+<Button variant="primary">Save</Button>
+<Button variant="destructive" appearance="outline">Delete</Button>
+<Button variant="ghost" size="icon" aria-label="More"><MoreHorizontalIcon /></Button>
+```
+### 6.3 Confirm dialogs — `AlertDialog`
+`AlertDialogAction` / `AlertDialogCancel` accept the same `variant` / `appearance`
+/ `size` props as `Button`, so no `asChild` plumbing is needed. They auto-close.
+```tsx
+<AlertDialog>
+  <AlertDialogTrigger asChild><Button variant="destructive" appearance="outline">Delete</Button></AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Are you sure?</AlertDialogTitle>
+      <AlertDialogDescription>This cannot be undone.</AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction variant="destructive">Delete</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+### 6.4 Pagination
+Links styled like buttons; drive them with `href` (URL-based) or `onClick`
+(client state). Mark the current page with `isActive`.
+```tsx
+<Pagination>
+  <PaginationContent>
+    <PaginationItem><PaginationPrevious href="#" onClick={…} /></PaginationItem>
+    <PaginationItem><PaginationLink href="#" isActive>1</PaginationLink></PaginationItem>
+    <PaginationItem><PaginationEllipsis /></PaginationItem>
+    <PaginationItem><PaginationNext href="#" onClick={…} /></PaginationItem>
+  </PaginationContent>
+</Pagination>
+```
+### 6.5 Component catalog
+- **Inputs & forms**: `Input`, `Textarea`, `Label`, `Checkbox`, `Switch`,
+  `RadioGroup`, `Select`, `Form` (+ `FormField`/`FormItem`/`FormLabel`/
+  `FormControl`/`FormDescription`/`FormMessage`).
+- **Actions & disclosure**: `Button`, `DropdownMenu`, `Dialog`, `AlertDialog`,
+  `Sheet`, `Popover`, `Tooltip`, `Command` (palette), `Accordion`, `Tabs`.
+- **Display**: `Card`, `Table`, `Badge`, `Avatar`, `Separator`, `Skeleton`,
+  `Progress`, `Pagination`, `Alert`.
+- **Feedback / async**: `Spinner` (+ `SpinnerBlock`, `DefaultHydrateFallback`),
+  `ErrorBlock`, `AwaitErrorBlock`, toasts (`Toaster` + `toast`).
+- **Hooks**: `useMediaQuery('(max-width: 768px)')` for responsive logic that
+  can't be pure CSS.
+---
+## 7. Theming
+Everything is themed through CSS variables — no rebuild. You re-declare tokens in
+a stylesheet loaded **after** the library's.
+- **Colors** use the unprefixed shadcn names (`--primary`, `--secondary`,
+  `--background`, `--foreground`, `--border`, `--destructive`, `--success`, …),
+  each often with a `-foreground` partner. Light values in `:root`, dark
+  overrides in `.dark`.
+- **Dimensions** use the `--k4-` prefix where lib-specific. `--spacing` is the
+  global density lever (scales all padding/margin/gap/control sizes);
+  `--radius` controls corner rounding.
+- **Mode toggle**: drop `<ModeToggle />` (typically in `TopBar`'s `end` slot);
+  read/set the mode with `useTheme()`. `ThemeProvider` manages the `.dark` class.
+```css
+/* your app theme, loaded after the library */
+:root { --primary: oklch(0.45 0.16 258); --radius: 0.4rem; --spacing: 0.25rem; }
+.dark { --primary: oklch(0.68 0.14 258); }
+```
+> **Don't reuse a system token name for an app-specific meaning.** Declaring e.g.
+> `--accent` for your own purpose silently re-themes every component consuming
+> that token. Name app variables distinctly (e.g. `--brand`).
+The full contract — every token, the `-foreground` convention, custom fonts — is
+in **`DESIGN-SYSTEM.md`**. A live token board ships in the demo at `/ui/tokens`.
+---
+## 8. Data fetching (TanStack Query)
+The library doesn't impose a data layer, but it has a **standard blueprint** for
+TanStack Query (v5). Follow it for every server resource — it gives one
+definition per query that's reusable across components, route loaders, and the
+query client, plus reliable cache invalidation.
+Per entity (e.g. `article`), create four pieces, conventionally in the feature's
+`<entity>-service.ts` (the fetchers themselves live in an `api.ts`):
+### 8.1 A hierarchical query-key factory
+One source of truth for keys. The hierarchy is what makes **targeted
+invalidation** possible: invalidating `lists()` refreshes every list variant at
+once.
+```ts
+import type { SortOrderInput } from '@kode4/react-foundation';
+export const articleKeys = {
+  all: ['articles'] as const,
+  lists: () => [...articleKeys.all, 'list'] as const,
+  list: (sort?: SortOrderInput) => [...articleKeys.lists(), sort] as const,
+  items: () => [...articleKeys.all, 'item'] as const,
+  item: (id?: number) => [...articleKeys.items(), id] as const,
+};
+```
+### 8.2 Query definitions with `queryOptions`
+`queryOptions` colocates key + fn + options into a reusable object. The same
+definition feeds `useQuery`, `useSuspenseQuery`, `ensureQueryData`,
+`getQueryData`, etc. — never re-spell the key at each call site.
+```ts
+import { queryOptions, skipToken } from '@tanstack/react-query';
+import { fetchArticle, fetchArticleList } from './api';
+export const articleQueries = {
+  list: (sort?: SortOrderInput) =>
+    queryOptions({ queryKey: articleKeys.list(sort), queryFn: () => fetchArticleList(sort) }),
+  // skipToken disables the query while keeping the data type non-undefined —
+  // prefer it over `enabled: false` for conditional fetches.
+  item: (id?: number) =>
+    queryOptions({
+      queryKey: articleKeys.item(id),
+      queryFn: id == null ? skipToken : () => fetchArticle(id),
+      retry: false, // a 404 on a detail fetch shouldn't be retried
+    }),
+};
+```
+Read them in components:
+```tsx
+const { data } = useQuery(articleQueries.list(sort));     // or useSuspenseQuery(...)
+const { data } = useQuery(articleQueries.item(selectedId)); // pauses until id is set
+```
+### 8.3 Mutations + colocated invalidation
+Define mutations with `mutationOptions`, then a `use<Entity>Mutations()` hook
+that wires `onSuccess` invalidation **through the key factory** (never hardcode a
+key — that silently drifts when the shape changes):
+```ts
+import { mutationOptions, useMutation, useQueryClient } from '@tanstack/react-query';
+export const articleMutations = {
+  save: () => mutationOptions({ mutationKey: [...articleKeys.all, 'save'], mutationFn: saveArticle }),
+  remove: () => mutationOptions({ mutationKey: [...articleKeys.all, 'remove'], mutationFn: deleteArticle }),
+};
+export function useArticleMutations() {
+  const qc = useQueryClient();
+  const saveMutation = useMutation({
+    ...articleMutations.save(),
+    onSuccess: async (savedId) => {
+      await Promise.all([
+        qc.invalidateQueries({ queryKey: articleKeys.lists() }),
+        savedId != null ? qc.invalidateQueries({ queryKey: articleKeys.item(savedId) }) : undefined,
+      ]);
+    },
+  });
+  const deleteMutation = useMutation({
+    ...articleMutations.remove(),
+    onSuccess: async (_data, id) => {
+      await Promise.all([
+        qc.invalidateQueries({ queryKey: articleKeys.lists() }),
+        qc.invalidateQueries({ queryKey: articleKeys.item(id) }),
+      ]);
+    },
+  });
+  return { saveMutation, deleteMutation };
+}
+```
+### 8.4 The loader integration (this library's payoff)
+Because query definitions are reusable, a route loader can **prefetch** the exact
+same definition the component reads — so the page renders synchronously, with no
+loading flash, and stays in the shared cache:
+```tsx
+export const articlesRoute = defineRoute({
+  path: 'articles',
+  component: ArticlesPage,
+  loader: ({ context }) => context.queryClient.ensureQueryData(articleQueries.list()),
+});
+function ArticlesPage() {
+  const { data } = useSuspenseQuery(articleQueries.list()); // already warmed by the loader
+}
+```
+### 8.5 Rules
+- **One key, one factory.** Every key — in queries, mutations, and invalidations —
+  comes from the `<entity>Keys` factory. A query that spells its own key lands in
+  a different cache bucket and **won't be invalidated** by the mutations.
+- **Reuse, don't re-spell.** Pass `articleQueries.x()` to `useQuery`,
+  `useSuspenseQuery`, `ensureQueryData`, etc. Don't inline `{ queryKey, queryFn }`.
+- **`skipToken`** for conditional fetches; **`retry: false`** for detail fetches
+  that 404 meaningfully.
+- **Sorting**: reuse `SortOrder` / `SortDirection` / `SortOrderInput` from
+  `@kode4/react-foundation` for any sortable list, and include the sort in the
+  list key (`articleKeys.list(sort)`) so each sort variant caches independently.
+---
+## 9. Forms
+`Form` wraps react-hook-form; pair it with a Zod resolver. `FormField` wires ids
+and ARIA automatically.
+```tsx
+const schema = z.object({ username: z.string().min(3, 'At least 3 characters.') });
+const form = useForm<z.infer<typeof schema>>({ resolver: zodResolver(schema), defaultValues: { username: '' } });
+<Form {...form}>
+  <form onSubmit={form.handleSubmit((v) => toast.success(`Hi ${v.username}`))}>
+    <FormField control={form.control} name="username" render={({ field }) => (
+      <FormItem>
+        <FormLabel>Username</FormLabel>
+        <FormControl><Input placeholder="ada" {...field} /></FormControl>
+        <FormDescription>Your public name.</FormDescription>
+        <FormMessage />
+      </FormItem>
+    )} />
+    <Button type="submit">Submit</Button>
+  </form>
+</Form>
+```
+---
+## 10. Toasts
+Render `<Toaster />` once near the root, then call `toast` anywhere. Toast styling
+mirrors the Alert variant system (including `primary`/`secondary`).
+```tsx
+import { toast } from '@kode4/react-foundation';
+toast.success('Saved');
+toast.error('Something went wrong');
+toast.primary('Heads up');
+```
+---
+## 11. Errors & async boundaries
+- Every route gets `DefaultErrorBoundary` unless it declares its own — thrown
+  `Response`s (e.g. a guard's `403`) and Zod `400`s render sensibly.
+- `ErrorBlock` is the standalone error display; `AwaitErrorBlock` is for
+  `<Await>`/deferred boundaries.
+- `SpinnerBlock` / `DefaultHydrateFallback` are the standard loading fallbacks.
+---
+## 12. Styling your own app
+The library's internal rule "no Tailwind utility classes in markup" applies to
+the *library source only*. **In your consuming app you may style however you
+like** — Tailwind, CSS modules, plain CSS. Two guidelines:
+1. **Theme through tokens**, not by overriding internal `k4-*` classes (those are
+   implementation detail and may change).
+2. To make your own elements follow light/dark mode, style them against the same
+   semantic tokens (`var(--background)`, `var(--foreground)`, `var(--border)`, …).
+---
+## 13. Quick pitfall checklist
+1. Forgot `z.coerce` on a numeric path param → it's a string.
+2. Route missing from the `createAppRouter` array → `pathTo()` throws.
+3. Called `pathTo()`/`resolveMenu()` at module load → registry not filled yet.
+4. Augmented the barrel instead of `@kode4/react-foundation/router/context`.
+5. Hand-wrote a URL instead of `TypedLink`/`pathTo`.
+6. Reused a system token name (`--accent`, `--primary`) for an app-specific
+   value → re-themed every component. Use a distinct name.
+7. Wrote search state via `window.history` instead of `useSearchParams`'s setter
+   with `{ replace: true }`.
+8. Read params/search from React Router hooks instead of `useRoute(routeDef)`.