wcz-layout 7.6.1 → 7.6.2

package/skills/tanstack-db-collections/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: tanstack-db-collections
+description: >
+  Wire TanStack DB createCollection with queryCollectionOptions for optimistic
+  client-side data. Set up axios instance with MSAL token interceptor using
+  getAccessToken(scopeKey). CRUD mutation handlers (onInsert, onUpdate, onDelete).
+  Use shared queryClient from wcz-layout/query. Consume with useLiveQuery /
+  useLiveSuspenseQuery. Activate when creating or modifying data collections.
+type: core
+library: wcz-layout
+library_version: "7.6.1"
+requires:
+  - database-schema
+  - api-routes
+sources:
+  - "wcz-layout:src/lib/db/collections/"
+  - "wcz-layout:src/exports/query.ts"
+  - "wcz-layout:src/lib/queryClient.ts"
+---
+
+# TanStack DB Collections
+
+## Setup
+
+Collection files live in `src/lib/db/collections/`:
+
+```
+src/lib/db/collections/todoCollection.ts
+```
+
+## Core Patterns
+
+### Creating a collection
+
+```typescript
+// src/lib/db/collections/todoCollection.ts
+import { createCollection } from "@tanstack/react-db";
+import { queryCollectionOptions } from "@tanstack/query-db-collection";
+import axios from "axios";
+import { getAccessToken, queryClient } from "wcz-layout";
+import { TodoSchema } from "~/schemas/todo";
+import type { Todo } from "~/schemas/todo";
+
+const api = axios.create({ baseURL: "/api/todos" });
+
+api.interceptors.request.use(async (config) => {
+  const accessToken = await getAccessToken("api");
+  config.headers.set("Authorization", `Bearer ${accessToken}`);
+  return config;
+});
+
+export const todoCollection = createCollection<Todo>({
+  id: "todos",
+  getKey: (item) => item.id,
+  ...queryCollectionOptions({
+    queryClient,
+    queryKey: ["todos"],
+    queryFn: async () => {
+      const response = await api.get<Todo[]>("");
+      return response.data;
+    },
+    schema: TodoSchema,
+    onInsert: async (item) => {
+      await api.post("", item);
+    },
+    onUpdate: async (item) => {
+      await api.put(`/${item.id}`, item);
+    },
+    onDelete: async (item) => {
+      await api.delete(`/${item.id}`);
+    },
+  }),
+});
+```
+
+### Choosing the scope key
+
+The `getAccessToken(scopeKey)` argument depends on the target service:
+
+| Target              | Scope key | When                              |
+| ------------------- | --------- | --------------------------------- |
+| Your own API routes | `"api"`   | Default — calls to `/api/*`       |
+| Microsoft Graph     | `"graph"` | Calls to `graph.microsoft.com`    |
+| File microservice   | `"file"`  | Calls to the file storage service |
+
+Scope keys are defined in your app's `src/lib/auth/scopes.ts`.
+
+### Consuming collection data in components
+
+```typescript
+import { useLiveQuery } from "@tanstack/react-db";
+import { todoCollection } from "~/lib/db/collections/todoCollection";
+
+function TodoList() {
+  const { data: todos } = useLiveQuery((query) =>
+    query.from({ todos: todoCollection })
+  );
+
+  return (
+    <ul>
+      {todos.map((todo) => (
+        <li key={todo.id}>{todo.name}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+For Suspense boundaries, use `useLiveSuspenseQuery` instead.
+
+### Optimistic mutations
+
+Collections handle mutations optimistically. Insert, update, and delete operations update the local collection immediately and sync to the server via `onInsert`, `onUpdate`, `onDelete`:
+
+```typescript
+import { todoCollection } from "~/lib/db/collections/todoCollection";
+import { uuidv7 } from "uuidv7";
+
+// Insert — collection updates instantly, API call runs in background
+todoCollection.insert({
+  id: uuidv7(),
+  name: "New task",
+  isCompleted: false,
+  createdBy: user.email,
+  createdAt: new Date(),
+  updatedAt: new Date(),
+});
+
+// Update
+todoCollection.update({ ...existingTodo, name: "Updated name" });
+
+// Delete
+todoCollection.delete(existingTodo);
+```
+
+## Common Mistakes
+
+### CRITICAL Using useQuery / useSuspenseQuery instead of TanStack DB
+
+Wrong:
+
+```typescript
+import { useQuery } from "@tanstack/react-query";
+
+const { data } = useQuery({
+  queryKey: ["todos"],
+  queryFn: fetchTodos,
+});
+```
+
+Correct:
+
+```typescript
+import { useLiveQuery } from "@tanstack/react-db";
+import { todoCollection } from "~/lib/db/collections/todoCollection";
+
+const { data } = useLiveQuery((query) => query.from({ todos: todoCollection }));
+```
+
+The enforced pattern is TanStack DB collections with `useLiveQuery` / `useLiveSuspenseQuery` for all API data. Plain TanStack Query bypasses the optimistic update layer.
+
+Source: maintainer interview
+
+### CRITICAL Creating a new QueryClient instead of using shared one
+
+Wrong:
+
+```typescript
+import { QueryClient } from "@tanstack/react-query";
+const queryClient = new QueryClient();
+```
+
+Correct:
+
+```typescript
+import { queryClient } from "wcz-layout/query";
+```
+
+wcz-layout exports a singleton `queryClient`. Creating a new one breaks cache sharing and SSR query integration.
+
+Source: wcz-layout:src/lib/queryClient.ts
+
+### HIGH Forgetting token interceptor on axios instance
+
+Wrong:
+
+```typescript
+const api = axios.create({ baseURL: "/api/todos" });
+// No interceptor — requests will return 401
+```
+
+Correct:
+
+```typescript
+import { getAccessToken } from "wcz-layout/utils";
+
+const api = axios.create({ baseURL: "/api/todos" });
+api.interceptors.request.use(async (config) => {
+  const accessToken = await getAccessToken("api");
+  config.headers.set("Authorization", `Bearer ${accessToken}`);
+  return config;
+});
+```
+
+API endpoints require Bearer token authentication. Without the interceptor, all requests return 401.
+
+Source: consumer project example
+
+### HIGH Using getKey that returns non-unique values
+
+Wrong:
+
+```typescript
+export const todoCollection = createCollection<Todo>({
+  id: "todos",
+  getKey: (item) => item.name, // names can be duplicated!
+  ...queryCollectionOptions({ ... }),
+});
+```
+
+Correct:
+
+```typescript
+export const todoCollection = createCollection<Todo>({
+  id: "todos",
+  getKey: (item) => item.id, // uuid — always unique
+  ...queryCollectionOptions({ ... }),
+});
+```
+
+`getKey` must return a unique identifier for each item. Using a non-unique field causes silent collection corruption — items overwrite each other.
+
+Source: TanStack DB documentation
+
+### MEDIUM Forgetting schema option in queryCollectionOptions
+
+Wrong:
+
+```typescript
+...queryCollectionOptions({
+  queryClient,
+  queryKey: ["todos"],
+  queryFn: async () => (await api.get("")).data,
+  // no schema — API responses are not validated
+}),
+```
+
+Correct:
+
+```typescript
+...queryCollectionOptions({
+  queryClient,
+  queryKey: ["todos"],
+  queryFn: async () => (await api.get("")).data,
+  schema: TodoSchema,
+}),
+```
+
+The `schema` option enables runtime validation of API responses. Omitting it removes type safety on incoming data — malformed payloads pass silently.
+
+Source: consumer project example
+
+---
+
+See also:
+
+- skills/ui-pages/SKILL.md — Pages consume collections via useLiveQuery.
+- skills/database-schema/SKILL.md — Same Zod schema used as collection schema.
+- skills/api-routes/SKILL.md — Collections consume API routes via axios baseURL.
+- skills/data-grid/SKILL.md — Grid rows come from useLiveQuery results.

package/skills/ui-pages/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: ui-pages
+description: >
+  Build route pages (index, detail, create, edit) with TanStack Router
+  createFileRoute. Use Router-bridged MUI components: RouterButton,
+  RouterLink, RouterIconButton, RouterFab, RouterTab, RouterListItemButton,
+  RouterGridActionsCellItem. Type-safe navigation with to prop. Route params,
+  search params, beforeLoad with requirePermission. Client-first rendering
+  (defaultSsr: false). Activate when creating or modifying page routes.
+type: core
+library: wcz-layout
+library_version: "7.6.1"
+requires:
+  - tanstack-db-collections
+sources:
+  - "wcz-layout:src/components/router/"
+  - "wcz-layout:src/routes/"
+  - "wcz-layout:src/start.ts"
+---
+
+# UI Pages & Routing
+
+## Setup
+
+Page routes live under `src/routes/` following TanStack Router file-based conventions:
+
+```
+src/routes/
+├── __root.tsx              # Root layout (LayoutProvider)
+├── index.tsx               # Home page (/)
+└── todos/
+    ├── -components/        # Domain-scoped components (dash prefix!)
+    │   └── TodoForm.tsx
+    ├── index.tsx            # /todos — list page
+    ├── create.tsx           # /todos/create — create page
+    ├── $id.tsx              # /todos/$id — detail page
+    └── edit.$id.tsx         # /todos/edit/$id — edit page
+```
+
+## Core Patterns
+
+### List page
+
+```typescript
+// src/routes/todos/index.tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { useLiveQuery } from "@tanstack/react-db";
+import { RouterButton } from "wcz-layout/components";
+import { todoCollection } from "~/lib/db/collections/todoCollection";
+
+export const Route = createFileRoute("/todos/")({
+  component: TodosPage,
+});
+
+function TodosPage() {
+  const { data: todos } = useLiveQuery((query) =>
+    query.from({ todos: todoCollection })
+  );
+
+  return (
+    <div>
+      <RouterButton to="/todos/create" variant="contained">
+        Create Todo
+      </RouterButton>
+      {todos.map((todo) => (
+        <RouterLink key={todo.id} to="/todos/$id" params={{ id: todo.id }}>
+          {todo.name}
+        </RouterLink>
+      ))}
+    </div>
+  );
+}
+```
+
+### Detail page with route params
+
+```typescript
+// src/routes/todos/$id.tsx
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/todos/$id")({
+  component: TodoDetailPage,
+});
+
+function TodoDetailPage() {
+  const { id } = Route.useParams();
+  // use id to filter collection data or fetch detail
+}
+```
+
+### Permission-guarded page
+
+```typescript
+import { createFileRoute } from "@tanstack/react-router";
+import { requirePermission } from "wcz-layout/utils";
+
+export const Route = createFileRoute("/admin/")({
+  beforeLoad: requirePermission("admin"),
+  component: AdminPage,
+});
+```
+
+`requirePermission` is a route `beforeLoad` guard that checks if the current user has the specified permission. Redirects to unauthorized if not.
+
+### Router-bridged MUI components
+
+These components merge MUI props with TanStack Router `LinkProps`. Use `to` for internal navigation (type-safe), `href` only for external URLs:
+
+| Component                   | MUI base            | Use case                |
+| --------------------------- | ------------------- | ----------------------- |
+| `RouterButton`              | Button              | Navigation buttons      |
+| `RouterLink`                | Link (Typography)   | Inline text links       |
+| `RouterIconButton`          | IconButton          | Icon-only navigation    |
+| `RouterFab`                 | Fab                 | Floating action buttons |
+| `RouterTab`                 | Tab                 | Tab-based navigation    |
+| `RouterListItemButton`      | ListItemButton      | Sidebar/list navigation |
+| `RouterGridActionsCellItem` | GridActionsCellItem | DataGrid row actions    |
+
+All accept the same TanStack Router link props: `to`, `params`, `search`, `hash`.
+
+### Root route structure
+
+```typescript
+// src/routes/__root.tsx
+import { createRootRouteWithContext, Outlet } from "@tanstack/react-router";
+import { LayoutProvider, rootRouteHead } from "wcz-layout";
+import type { ProvidersProps } from "wcz-layout";
+
+export const Route = createRootRouteWithContext()({
+  head: rootRouteHead,
+  component: RootComponent,
+  notFoundComponent: RouterNotFound,
+  errorComponent: RouterError,
+});
+
+function RootComponent() {
+  return (
+    <LayoutProvider theme={theme} navigation={navigation} options={options}>
+      <Outlet />
+    </LayoutProvider>
+  );
+}
+```
+
+## Common Mistakes
+
+### CRITICAL Using React Router or window.location for navigation
+
+Wrong:
+
+```typescript
+import { useNavigate } from "react-router-dom";
+// or
+window.location.href = "/todos";
+```
+
+Correct:
+
+```typescript
+import { useNavigate } from "@tanstack/react-router";
+const navigate = useNavigate();
+navigate({ to: "/todos" });
+```
+
+This stack uses TanStack Router exclusively. React Router does not exist in the dependency tree. `window.location` causes a full page reload, bypassing the SPA router.
+
+Source: copilot-instructions.md
+
+### HIGH Using MUI Button with href instead of RouterButton
+
+Wrong:
+
+```typescript
+<Button href="/todos/create">Create</Button>
+```
+
+Correct:
+
+```typescript
+import { RouterButton } from "wcz-layout/components";
+
+<RouterButton to="/todos/create" variant="contained">
+  Create
+</RouterButton>
+```
+
+Plain MUI `Button` with `href` causes a full page reload. `RouterButton` uses TanStack Router's `createLink` for SPA navigation with type-safe routes.
+
+Source: wcz-layout:src/components/router/RouterButton.tsx
+
+### HIGH Assuming SSR is enabled
+
+Wrong:
+
+```typescript
+// Expecting server-side data in a route loader
+export const Route = createFileRoute("/todos/")({
+  loader: async () => {
+    return { todos: await fetchTodos() }; // runs on server — but SSR is off
+  },
+});
+```
+
+Correct:
+
+```typescript
+// Use TanStack DB collections for client-side data
+function TodosPage() {
+  const { data } = useLiveQuery((q) => q.from({ todos: todoCollection }));
+}
+```
+
+`start.ts` sets `defaultSsr: false`. Pages render client-side first. Do not rely on SSR data fetching patterns — use TanStack DB collections instead.
+
+Source: wcz-layout:src/start.ts
+
+### MEDIUM Omitting suppressHydrationWarning on html element
+
+The root route's `<html>` element must include `suppressHydrationWarning` because i18n language detection and color scheme can differ between server and client initial renders.
+
+Source: wcz-layout:src/routes/\_\_root.tsx
+
+### HIGH Using useMemo or useCallback
+
+Wrong:
+
+```typescript
+const filteredTodos = useMemo(() => todos.filter((t) => t.isCompleted), [todos]);
+```
+
+Correct:
+
+```typescript
+const filteredTodos = todos.filter((t) => t.isCompleted);
+```
+
+React Compiler handles memoization automatically. Manual `useMemo` / `useCallback` is forbidden per project conventions.
+
+Source: copilot-instructions.md
+
+Cross-skill: See also skills/forms-validation/SKILL.md § Common Mistakes
+
+### HIGH Tension: MUI component API vs. TanStack Router types
+
+Router-bridged components merge MUI props with TanStack Router `LinkProps`. Use `to` for internal routes and `href` only for external URLs. Passing `href` for an internal route causes a full page reload.
+
+See also: skills/data-grid/SKILL.md § Common Mistakes
+
+### HIGH Using theme.palette for dark mode instead of theme.applyStyles
+
+Wrong:
+
+```typescript
+sx={{ color: mode === "dark" ? "white" : "black" }}
+```
+
+Correct:
+
+```typescript
+sx={(theme) => ({
+  color: "black",
+  ...theme.applyStyles("dark", { color: "white" }),
+})}
+```
+
+The app uses `colorSchemeSelector: "data-mui-color-scheme"`. Always use `theme.applyStyles("dark", ...)` for mode-specific styling.
+
+Source: copilot-instructions.md
+
+Cross-skill: See also skills/layout-navigation/SKILL.md § Common Mistakes
+
+---
+
+See also:
+
+- skills/forms-validation/SKILL.md — Create/edit pages embed forms.
+- skills/layout-navigation/SKILL.md — Pages render inside the layout shell.
+- skills/tanstack-db-collections/SKILL.md — Pages consume collections via useLiveQuery.