wcz-layout 7.6.0 → 7.6.2

package/skills/project-structure/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: project-structure
+description: >
+  Domain-scoped co-location rules for TanStack Router file-based routing.
+  Dash-prefix convention (-components/, -hooks/) excludes folders from
+  route generation. Domain-specific code lives in route folders; shared
+  code in src/components/, src/hooks/. Drizzle schemas in src/lib/db/schemas/,
+  Zod schemas in src/schemas/, collections in src/lib/db/collections/.
+  Activate when deciding where to place a new file or organizing a feature.
+type: lifecycle
+library: wcz-layout
+library_version: "7.6.1"
+requires:
+  - project-initialization
+sources:
+  - "wcz-layout:src/routeTree.gen.ts"
+  - "TanStack/router:docs/router/api/file-based-routing.md"
+---
+
+This skill builds on project-initialization. Read it first for env and plugin setup.
+
+# Project Structure Conventions
+
+## Setup
+
+A typical project follows this structure:
+
+```
+src/
+├── components/              # SHARED components (used across multiple domains)
+│   ├── StyledCard.tsx
+│   └── DataGridToolbar.tsx
+├── hooks/                   # SHARED hooks
+├── lib/
+│   ├── auth/
+│   │   ├── permissions.ts   # AD group → permission key mapping
+│   │   └── scopes.ts        # OAuth scope definitions
+│   ├── db/
+│   │   ├── schemas/          # Drizzle pgTable definitions
+│   │   │   └── todo.ts
+│   │   ├── collections/      # TanStack DB collections
+│   │   │   └── todoCollection.ts
+│   │   └── migrations/       # Drizzle migrations
+│   └── theme.ts
+├── middleware/               # Custom middleware (e.g. databaseMiddleware)
+├── schemas/                  # Zod validation schemas (derived from Drizzle)
+│   └── todo.ts
+├── locales/                  # i18n translation files
+│   ├── en.json
+│   └── cs.json
+├── routes/
+│   ├── __root.tsx            # Root layout with LayoutProvider
+│   ├── index.tsx             # Home page
+│   ├── api/
+│   │   ├── health.ts         # Health check endpoint
+│   │   └── todos/
+│   │       ├── index.ts      # GET / POST handlers
+│   │       └── $id.ts        # GET / PUT / DELETE by id
+│   └── todos/
+│       ├── -components/      # Domain-specific components (dash prefix!)
+│       │   └── Form.tsx
+│       ├── index.tsx          # List page
+│       ├── create.tsx         # Create page
+│       ├── $id.tsx            # Detail page
+│       └── edit.$id.tsx       # Edit page
+├── env.ts                    # Environment variable validation
+├── router.tsx                # Router configuration
+├── start.ts                  # TanStack Start configuration
+└── routeTree.gen.ts          # AUTO-GENERATED — never edit
+```
+
+## Core Patterns
+
+### Domain-scoped co-location
+
+When a component, hook, or utility is used only within one route domain, place it inside that route folder with a dash-prefix directory:
+
+```
+src/routes/todos/-components/Form.tsx     # Only used in /todos routes
+src/routes/todos/-hooks/useTodoFilters.ts # Only used in /todos routes
+src/routes/orders/-components/OrderCard.tsx
+```
+
+When the same component is reused across multiple domains, move it to the top-level shared directory:
+
+```
+src/components/StyledCard.tsx    # Used by both /todos and /orders
+src/hooks/useDebounce.ts         # Used everywhere
+```
+
+### Data layer file placement
+
+```
+src/lib/db/schemas/todo.ts           # Drizzle table: pgTable("todos", { ... })
+src/schemas/todo.ts                  # Zod schema: createSelectSchema(todoTable, { ... })
+src/lib/db/collections/todoCollection.ts  # TanStack DB collection
+```
+
+## Common Mistakes
+
+### CRITICAL Missing dash prefix on route-scoped folders
+
+Wrong:
+
+```
+src/routes/todos/components/Form.tsx
+```
+
+Correct:
+
+```
+src/routes/todos/-components/Form.tsx
+```
+
+TanStack Router treats folders without a dash prefix as route segments. `components/Form.tsx` becomes a `/todos/components/Form` route. The dash prefix (`-components/`) tells the router to ignore this directory.
+
+Source: TanStack/router:docs/router/api/file-based-routing.md
+
+### CRITICAL Editing routeTree.gen.ts
+
+Wrong:
+
+```typescript
+// src/routeTree.gen.ts — manually adding a route
+```
+
+Correct:
+
+Create a new file in `src/routes/` and let TanStack Router auto-generate the route tree.
+
+This file is auto-generated and overwritten on every route change. Manual edits are silently lost.
+
+Source: wcz-layout:src/routeTree.gen.ts header comment
+
+### HIGH Placing domain-specific component in src/components/
+
+Wrong:
+
+```typescript
+// src/components/TodoForm.tsx — only used in /todos routes
+export function TodoForm() {
+  return <form>...</form>;
+}
+```
+
+Correct:
+
+```typescript
+// src/routes/todos/-components/TodoForm.tsx
+export function TodoForm() {
+  return <form>...</form>;
+}
+```
+
+Components used only within one route domain should live in that domain's `-components/` folder. `src/components/` is reserved for components shared across multiple domains.
+
+Source: maintainer interview

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.