wcz-layout 8.1.0 → 8.2.0

package/skills/tables/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: tables
+description: MUI X DataGrid Premium patterns — typed GridColDef, custom cell renderers (ChipInputCell, EditableColumnHeader) and row selection with toolbar actions.
+---
+
+## Rules
+
+- Wrap DataGrid in `Fullscreen` when it is the only content on the page. Embedded grids use `autoHeight` instead.
+- Always type `GridColDef<RowType>` with the row interface.
+- Use `const { t } = useTranslation()` from `wcz-layout/hooks` for all `headerName` values.
+- For editable columns, pair `editable: true` with `renderHeader: EditableColumnHeader`.
+- For enums use `type: "singleSelect"` with `valueOptions` as `{ value, label }` objects
+- Use properties: `showToolbar`, `loading`, `ignoreDiacritics`, `cellSelection`, `disableRowSelectionOnClick`.
+- Use custom `slots={{ toolbar: DataGridToolbar }}` from `src/components` if available.
+
+## File Placement
+
+```
+src/server/db/migrations/       — migrations
+src/server/db/schemas/          — tables, enums, relations
+src/lib/schemas/                — Zod schemas
+wcz-layout/utils                — shared utils from npm package
+wcz-layout/components           — shared components from npm package
+@tanstack/react-db              — TanStack DB Collections
+```
+
+## Examples
+
+```ts
+// imports
+import { useLiveQuery } from "@tanstack/react-db";
+import { t } from "wcz-layout/utils";
+import { ChipInputCell, Fullscreen, EditableColumnHeader } from "wcz-layout/components";
+import { useTranslation } from "wcz-layout/hooks";
+import { featureCollection } from "~/db-collections/featureCollection";
+import { DataGridToolbar } from "~/components/DataGridToolbar";
+import { statusEnum } from "~/server/db/schemas/feature";
+
+// ChipInputCell (Renders array or single values as MUI Chips)
+// Simple array of strings
+{ renderCell: (params) => <ChipInputCell params={params} /> }
+
+// Complex objects with custom label extraction
+{
+  renderCell: (params) => (
+    <ChipInputCell
+      params={params}
+      getLabel={(item) => item.displayName}
+      slotProps={{ color: "primary", size: "small" }}
+    />
+  ),
+}
+
+// EditableColumnHeader (Shows an edit icon next to the column name for editable columns)
+{
+  field: "name",
+  headerName: t("Name"),
+  editable: true,
+  renderHeader: EditableColumnHeader,
+}
+
+// Enum column
+{
+  field: "status",
+  headerName: t("Status"),
+  width: 160,
+  type: "singleSelect",
+  valueOptions: statusEnum.enumValues.map((status) => ({
+    value: status,
+    label: t(`Status.${status}`),
+  })),
+},
+
+// Integration with TanStack DB Collections
+function ExampleGrid() {
+  const { data, isLoading } = useLiveQuery((q) =>
+    q
+      .from({ library: libraryCollection })
+      .orderBy(({ library }) => library.title, "desc"),
+  );
+
+  return (
+    <Fullscreen>
+      <DataGridPremium
+        rows={data}
+        columns={columns}
+        showToolbar
+        loading={isLoading}
+        ignoreDiacritics
+        cellSelection
+        disableRowSelectionOnClick
+        onRowDoubleClick={({ row }) => navigate({ to: "/feature/$id", params: { id: row.id } })}
+        slots={{ toolbar: DataGridToolbar }}
+        slotProps={{
+          toolbar: {
+            title: t("List"),
+          },
+        }}
+      />
+    </Fullscreen>
+  );
+}
+
+// CRUD operations
+const [rowSelectionModel, setRowSelectionModel] = useState<GridRowSelectionModel>({
+type: "include",
+ids: new Set(),
+});
+
+const handleOnDelete = createOptimisticAction<Array<string>>({
+  onMutate: (ids) => {
+    ids.forEach((id) => {
+      featureCollection.delete(id);
+    });
+  },
+  mutationFn: async (ids) => {
+    deleteFeatures({ data: ids });
+    await featureCollection.utils.refetch();
+  },
+});
+
+return (
+  <DataGridPremium
+    // other props
+    rowSelectionModel={rowSelectionModel}
+    onRowSelectionModelChange={(newRowSelectionModel) =>
+      setRowSelectionModel(newRowSelectionModel)
+    }
+    slots={{ toolbar: DataGridToolbar }}
+    slotProps={{
+      toolbar: {
+        title: t("Feature.List"),
+        actions: [
+          <Tooltip key="create" title={t("Create")}>
+            <RouterIconButton to="/features/create">
+              <Add fontSize="small" />
+            </RouterIconButton>
+          </Tooltip>,
+          rowSelectionModel.ids.size === 1 && (
+            <Tooltip key="edit" title={t("Edit")}>
+              <RouterIconButton
+                to="/features/edit/$id"
+                params={{ id: Array.from(rowSelectionModel.ids)[0].toString() }}
+              >
+                <Edit fontSize="small" />
+              </RouterIconButton>
+            </Tooltip>
+          ),
+          rowSelectionModel.ids.size > 0 && (
+            <Tooltip key="delete" title={t("Delete")}>
+              <IconButton
+                onClick={async () => {
+                  const confirmed = await confirm(
+                    t("DeleteConfirmation", { count: rowSelectionModel.ids.size }),
+                  );
+                  if (confirmed) {
+                    try {
+                      const transaction = handleOnDelete(
+                        Array.from(rowSelectionModel.ids).map((id) => id.toString()),
+                      );
+                      await transaction.isPersisted.promise;
+                      setRowSelectionModel({ type: "include", ids: new Set() });
+                    } catch (error) {
+                      if (error instanceof Error) alert(error.message);
+                    }
+                  }
+                }}
+              >
+                <Badge
+                  badgeContent={rowSelectionModel.ids.size}
+                  invisible={rowSelectionModel.ids.size <= 1}
+                  color="error"
+                >
+                  <Delete fontSize="small" />
+                </Badge>
+              </IconButton>
+            </Tooltip>
+          ),
+        ],
+      },
+    }}
+  />
+);
+```

package/skills/api-routes/SKILL.md

@@ -1,251 +0,0 @@
----
-name: api-routes
-description: >
-  Create TanStack Start file-based API routes with createFileRoute or
-  createServerFn. Wire authorizationMiddleware(permissionKey) and
-  validationMiddleware(schema) in server.middleware. Use createHandlers
-  for CRUD with Drizzle queries. Response.json patterns. Covers the
-  { middleware, handler } object shape for handlers needing validation.
-  Activate when creating or modifying API endpoints or server functions.
-type: core
-library: wcz-layout
-library_version: "7.6.1"
-requires:
-  - database-schema
-sources:
-  - "wcz-layout:src/middleware/authMiddleware.ts"
-  - "wcz-layout:src/middleware/validationMiddleware.ts"
-  - "wcz-layout:src/routes/api/"
----
-
-# API Routes & Server Functions
-
-## Setup
-
-API routes live under `src/routes/api/` and follow TanStack Router file-based conventions:
-
-```
-src/routes/api/
-├── health.ts           # GET /api/health
-└── todos/
-    ├── index.ts        # GET /api/todos, POST /api/todos
-    └── $id.ts          # GET /api/todos/:id, PUT /api/todos/:id, DELETE /api/todos/:id
-```
-
-## Core Patterns
-
-### Basic CRUD API route
-
-```typescript
-// src/routes/api/todos/index.ts
-import { createFileRoute } from "@tanstack/react-router";
-import { createHandlers } from "@tanstack/start/api";
-import { authorizationMiddleware, validationMiddleware } from "wcz-layout/middleware";
-import { todoTable } from "~/lib/db/schemas/todo";
-import { TodoInsertSchema } from "~/schemas/todo";
-
-export const Route = createFileRoute("/api/todos")({
-  server: {
-    middleware: [authorizationMiddleware("all")],
-    handlers: createHandlers({
-      GET: async ({ context }) => {
-        const items = await context.db.select().from(todoTable);
-        return Response.json(items);
-      },
-      POST: {
-        middleware: [validationMiddleware(TodoInsertSchema)],
-        handler: async ({ context }) => {
-          const [item] = await context.db.insert(todoTable).values(context.data).returning();
-          return Response.json(item, { status: 201 });
-        },
-      },
-    }),
-  },
-});
-```
-
-### Route with path parameters
-
-```typescript
-// src/routes/api/todos/$id.ts
-import { createFileRoute } from "@tanstack/react-router";
-import { createHandlers } from "@tanstack/start/api";
-import { eq } from "drizzle-orm";
-import { authorizationMiddleware, validationMiddleware } from "wcz-layout/middleware";
-import { todoTable } from "~/lib/db/schemas/todo";
-import { TodoSchema } from "~/schemas/todo";
-
-export const Route = createFileRoute("/api/todos/$id")({
-  server: {
-    middleware: [authorizationMiddleware("all")],
-    handlers: createHandlers({
-      GET: async ({ context, params }) => {
-        const [item] = await context.db.select().from(todoTable).where(eq(todoTable.id, params.id));
-        if (!item) return new Response(null, { status: 404 });
-        return Response.json(item);
-      },
-      PUT: {
-        middleware: [validationMiddleware(TodoSchema)],
-        handler: async ({ context, params }) => {
-          const [item] = await context.db
-            .update(todoTable)
-            .set(context.data)
-            .where(eq(todoTable.id, params.id))
-            .returning();
-          return Response.json(item);
-        },
-      },
-      DELETE: async ({ context, params }) => {
-        await context.db.delete(todoTable).where(eq(todoTable.id, params.id));
-        return new Response(null, { status: 204 });
-      },
-    }),
-  },
-});
-```
-
-### Server functions (RPC-style)
-
-```typescript
-import { createServerFn } from "@tanstack/start";
-
-const getTodos = createServerFn({ method: "GET" })
-  .middleware([authorizationMiddleware("all")])
-  .handler(async ({ context }) => {
-    return context.db.select().from(todoTable);
-  });
-```
-
-Server functions are typed end-to-end. Use them for operations that don't need REST semantics.
-
-### Middleware composition
-
-`authorizationMiddleware(permissionKey)` already includes `authenticationMiddleware` internally. It verifies the JWT token and injects `context.user` with a `User` object that has `hasPermission()`. If the user lacks the permission, it returns 403.
-
-`validationMiddleware(schema)` parses `request.json()` against the Zod schema and injects `context.data` with the typed result. On failure, returns 400 with the first field error.
-
-## Common Mistakes
-
-### HIGH Chaining authenticationMiddleware then authorizationMiddleware
-
-Wrong:
-
-```typescript
-middleware: [authenticationMiddleware(), authorizationMiddleware("admin")],
-```
-
-Correct:
-
-```typescript
-middleware: [authorizationMiddleware("admin")],
-```
-
-`authorizationMiddleware` already composes `authenticationMiddleware` internally. Chaining both duplicates JWT verification.
-
-Source: maintainer interview
-
-Cross-skill: See also skills/auth/SKILL.md § Common Mistakes
-
-### HIGH Forgetting validationMiddleware for mutations
-
-Wrong:
-
-```typescript
-POST: async ({ request, context }) => {
-  const data = await request.json();
-  await context.db.insert(todoTable).values(data).returning();
-},
-```
-
-Correct:
-
-```typescript
-POST: {
-  middleware: [validationMiddleware(TodoInsertSchema)],
-  handler: async ({ context }) => {
-    const [item] = await context.db
-      .insert(todoTable)
-      .values(context.data)
-      .returning();
-    return Response.json(item, { status: 201 });
-  },
-},
-```
-
-POST/PUT handlers without `validationMiddleware` accept unvalidated JSON. The middleware parses `request.json()` with Zod and injects typed `context.data`.
-
-Source: wcz-layout:src/middleware/validationMiddleware.ts
-
-### HIGH Returning data without Response.json wrapper
-
-Wrong:
-
-```typescript
-GET: async ({ context }) => {
-  return await context.db.select().from(todoTable);
-},
-```
-
-Correct:
-
-```typescript
-GET: async ({ context }) => {
-  const items = await context.db.select().from(todoTable);
-  return Response.json(items);
-},
-```
-
-TanStack Start API route handlers must return `Response` objects. Returning raw objects doesn't set content-type headers correctly.
-
-Source: consumer project example
-
-### MEDIUM Using plain function for POST instead of middleware object
-
-Wrong:
-
-```typescript
-POST: async ({ request, context }) => {
-  // no way to attach validationMiddleware
-},
-```
-
-Correct:
-
-```typescript
-POST: {
-  middleware: [validationMiddleware(TodoInsertSchema)],
-  handler: async ({ context }) => {
-    // context.data is typed from schema
-  },
-},
-```
-
-When a handler needs per-method middleware (like validation), it must use the `{ middleware, handler }` object shape, not a plain async function.
-
-Source: consumer project example
-
-### MEDIUM Using invalid permission key string
-
-`authorizationMiddleware(permissionKey)` is typed to `keyof typeof permissions` from your app's `permissions.ts`. Using a string not defined there causes a compile error.
-
-Source: wcz-layout:src/middleware/authMiddleware.ts
-
-### HIGH Tension: Simplicity vs. full-stack rigor
-
-Quick prototypes may skip middleware to move fast. Always include `authorizationMiddleware` and `validationMiddleware` from the start — retrofitting security later is error-prone.
-
-See also: skills/project-initialization/SKILL.md § Common Mistakes
-
-### HIGH Tension: Client-side first vs. server-side data
-
-`defaultSsr: false` means pages render on the client. Do not use SSR data fetching patterns (loader + dehydrate). API routes serve data to TanStack DB collections which manage client-side state.
-
-See also: skills/tanstack-db-collections/SKILL.md § Core Patterns
-
----
-
-See also:
-
-- skills/tanstack-db-collections/SKILL.md — Collections consume these API routes via axios.
-- skills/auth/SKILL.md — Every API route uses authorizationMiddleware.
-- skills/database-schema/SKILL.md — Schemas feed into validationMiddleware.

package/skills/auth/SKILL.md

@@ -1,268 +0,0 @@
----
-name: auth
-description: >
-  MSAL/Entra ID authentication and AD-group authorization. Use
-  authorizationMiddleware(permissionKey) which includes authentication.
-  Configure permissions.ts and scopes.ts for type-safe keys via
-  virtual:wcz-layout. Client: getAccessToken(scopeKey). Server:
-  getAppToken(scopeKey), getTokenOnBehalfOf(userToken, scopeKey).
-  Route guards with requirePermission. Public routes via LayoutOptions.
-  serverFnAccessTokenMiddleware in start.ts. Activate when configuring
-  authentication, authorization, or token acquisition.
-type: core
-library: wcz-layout
-library_version: "7.6.1"
-sources:
-  - "wcz-layout:src/middleware/authMiddleware.ts"
-  - "wcz-layout:src/lib/auth/msalClient.ts"
-  - "wcz-layout:src/lib/auth/msalServer.ts"
-  - "wcz-layout:src/lib/auth/permissions.ts"
-  - "wcz-layout:src/lib/auth/scopes.ts"
----
-
-# Authentication & Authorization
-
-## Setup
-
-Two configuration files define the app's security surface. Both are consumed by the `viteWczLayout()` plugin via `virtual:wcz-layout` to generate TypeScript types:
-
-```typescript
-// src/lib/auth/permissions.ts
-export const permissions = {
-  admin: ["wcz-developers"],
-  all: ["wcz-all-employees", "wscz-all-employees"],
-} as const;
-// keyof typeof permissions → "admin" | "all"
-```
-
-```typescript
-// src/lib/auth/scopes.ts
-export const scopes = {
-  graph: ["User.Read"],
-  api: ["api://wistron.com/your-app/access_as_user"],
-} as const;
-// keyof typeof scopes → "graph" | "api"
-```
-
-Permission keys map to AD group names. A user has a permission if their JWT `groups` claim contains at least one group from the array.
-
-## Core Patterns
-
-### API route authorization
-
-```typescript
-import { authorizationMiddleware } from "wcz-layout/middleware";
-
-export const Route = createFileRoute("/api/todos")({
-  server: {
-    middleware: [authorizationMiddleware("all")],
-    handlers: createHandlers({
-      GET: async ({ context }) => {
-        // context.user is typed as User with hasPermission()
-        return Response.json(await context.db.select().from(todoTable));
-      },
-    }),
-  },
-});
-```
-
-`authorizationMiddleware(permissionKey)`:
-
-1. Verifies the JWT Bearer token (includes `authenticationMiddleware` internally)
-2. Builds a `User` object with `hasPermission(key)` method
-3. Returns 401 if token is invalid, 403 if user lacks the specified permission
-4. Injects `context.user: User`
-
-### Public (authentication-only) route
-
-For routes that need authentication but no specific permission:
-
-```typescript
-import { authenticationMiddleware } from "wcz-layout/middleware";
-
-export const Route = createFileRoute("/api/profile")({
-  server: {
-    middleware: [authenticationMiddleware()],
-    handlers: createHandlers({
-      GET: async ({ context }) => {
-        // context.user — any authenticated user
-        return Response.json(context.user);
-      },
-    }),
-  },
-});
-```
-
-For optional authentication (public endpoints that may have user context):
-
-```typescript
-middleware: [authenticationMiddleware({ optional: true })],
-// context.user is User | null
-```
-
-### Route-level permission guard
-
-```typescript
-import { requirePermission } from "wcz-layout/utils";
-
-export const Route = createFileRoute("/admin/")({
-  beforeLoad: requirePermission("admin"),
-  component: AdminPage,
-});
-```
-
-`requirePermission` runs in `beforeLoad` and redirects unauthorized users.
-
-### Client-side token acquisition
-
-```typescript
-import { getAccessToken } from "wcz-layout/utils";
-
-// In an axios interceptor or client-side code
-const token = await getAccessToken("api");
-```
-
-`getAccessToken` is a client-only function (uses MSAL `PublicClientApplication`). It acquires tokens silently and triggers interaction listeners on `InteractionRequiredAuthError`.
-
-### Server-side token acquisition
-
-```typescript
-import { getAppToken, getTokenOnBehalfOf } from "wcz-layout/utils";
-
-// App-only token (client credentials flow — no user context)
-const appToken = await getAppToken("graph");
-
-// On-behalf-of flow (exchange user token for downstream API token)
-const oboToken = await getTokenOnBehalfOf(userBearerToken, "graph");
-```
-
-Both are server-only functions using MSAL `ConfidentialClientApplication`.
-
-### Global server function middleware
-
-```typescript
-// src/start.ts
-import { serverFnAccessTokenMiddleware } from "wcz-layout/middleware";
-
-export const startInstance = createStart(() => ({
-  defaultSsr: false,
-  functionMiddleware: [serverFnAccessTokenMiddleware("api")],
-}));
-```
-
-`serverFnAccessTokenMiddleware` attaches the Bearer token to all server function calls globally. Without it, server functions won't include authorization headers.
-
-### Getting the current user
-
-```typescript
-import { getUser } from "wcz-layout/utils";
-
-// Isomorphic — works on client (returns User | null) and server (returns null)
-const user = getUser();
-```
-
-On the client, `getUser` reads the active MSAL account's ID token claims.
-
-## Common Mistakes
-
-### HIGH Chaining authenticationMiddleware before authorizationMiddleware
-
-Wrong:
-
-```typescript
-middleware: [authenticationMiddleware(), authorizationMiddleware("admin")],
-```
-
-Correct:
-
-```typescript
-middleware: [authorizationMiddleware("admin")],
-```
-
-`authorizationMiddleware` already composes `authenticationMiddleware` internally. Chaining both duplicates JWT verification.
-
-Source: maintainer interview
-
-Cross-skill: See also skills/api-routes/SKILL.md § Common Mistakes
-
-### CRITICAL Calling getAccessToken on the server
-
-Wrong:
-
-```typescript
-// In a server handler or serverFn
-const token = await getAccessToken("api");
-```
-
-Correct:
-
-```typescript
-// Server-side — use app token or OBO
-const token = await getAppToken("api");
-// or
-const token = await getTokenOnBehalfOf(userToken, "api");
-```
-
-`getAccessToken` is `createClientOnlyFn` — it uses MSAL `PublicClientApplication` which only exists in the browser. Calling it on the server throws.
-
-Source: wcz-layout:src/lib/auth/msalClient.ts
-
-### HIGH Forgetting serverFnAccessTokenMiddleware in start.ts
-
-Wrong:
-
-```typescript
-// src/start.ts
-export const startInstance = createStart(() => ({
-  defaultSsr: false,
-  // Missing functionMiddleware
-}));
-```
-
-Correct:
-
-```typescript
-// src/start.ts
-export const startInstance = createStart(() => ({
-  defaultSsr: false,
-  functionMiddleware: [serverFnAccessTokenMiddleware("api")],
-}));
-```
-
-Without `serverFnAccessTokenMiddleware`, server function calls won't include the Authorization header, causing 401 errors.
-
-Source: wcz-layout:src/start.ts
-
-### MEDIUM Using string literals for permission/scope keys
-
-Wrong:
-
-```typescript
-authorizationMiddleware("superadmin"); // not in permissions.ts → compile error
-getAccessToken("custom-api"); // not in scopes.ts → compile error
-```
-
-Correct:
-
-```typescript
-// First add to permissions.ts / scopes.ts, then use the typed key
-authorizationMiddleware("admin");
-getAccessToken("api");
-```
-
-Permission and scope keys are typed from the `as const` exports via `virtual:wcz-layout`. Using arbitrary strings causes TypeScript compile errors.
-
-Source: wcz-layout:src/types/wcz-layout.d.ts
-
-### HIGH Missing Entra redirect URI configuration
-
-The MSAL `redirectUri` defaults to `"/"`. The Entra app registration must include this exact redirect URI, or the authentication flow fails silently with a redirect error.
-
-Source: wcz-layout:src/routes/runbook/entra-id.tsx
-
----
-
-See also:
-
-- skills/api-routes/SKILL.md — Every API route uses authorizationMiddleware.
-- skills/layout-navigation/SKILL.md — publicRoutes bypass auth; permission guards need auth context.