wcz-layout 7.6.1 → 7.6.2

package/skills/data-grid/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: data-grid
+description: >
+  MUI X DataGrid Premium with wcz-layout helpers. ChipInputCell for chip
+  rendering in cells (getLabel for complex objects). EditableColumnHeader
+  for pencil icon headers. RouterGridActionsCellItem for type-safe row
+  action navigation. Column definitions with renderCell/renderHeader.
+  Feed rows from useLiveQuery collection data. Activate when building
+  data tables or grids.
+type: composition
+library: wcz-layout
+library_version: "7.6.1"
+requires:
+  - tanstack-db-collections
+  - ui-pages
+sources:
+  - "wcz-layout:src/components/data-grid/ChipInputCell.tsx"
+  - "wcz-layout:src/components/data-grid/EditableColumnHeader.tsx"
+  - "wcz-layout:src/components/router/RouterGridActionsCellItem.tsx"
+---
+
+# Data Grid
+
+## Setup
+
+Install `@mui/x-data-grid-premium` (peer dependency). Use `DataGridPremium`, not the community `DataGrid`.
+
+## Core Patterns
+
+### Basic data grid with collection data
+
+```typescript
+import { DataGridPremium, type GridColDef } from "@mui/x-data-grid-premium";
+import { useLiveQuery } from "@tanstack/react-db";
+import { todoCollection } from "~/lib/db/collections/todoCollection";
+import type { Todo } from "~/schemas/todo";
+
+const columns: GridColDef<Todo>[] = [
+  { field: "name", headerName: "Name", flex: 1 },
+  { field: "isCompleted", headerName: "Completed", type: "boolean", width: 120 },
+  { field: "createdAt", headerName: "Created", type: "dateTime", width: 180 },
+];
+
+function TodoGrid() {
+  const { data: todos } = useLiveQuery((query) =>
+    query.from({ todos: todoCollection })
+  );
+
+  return (
+    <DataGridPremium
+      rows={todos}
+      columns={columns}
+      getRowId={(row) => row.id}
+      autoHeight
+    />
+  );
+}
+```
+
+### Row actions with RouterGridActionsCellItem
+
+```typescript
+import { RouterGridActionsCellItem } from "wcz-layout/components";
+import EditIcon from "@mui/icons-material/Edit";
+import DeleteIcon from "@mui/icons-material/Delete";
+import type { GridColDef } from "@mui/x-data-grid-premium";
+
+const columns: GridColDef<Todo>[] = [
+  { field: "name", headerName: "Name", flex: 1 },
+  {
+    field: "actions",
+    type: "actions",
+    width: 100,
+    getActions: (params) => [
+      <RouterGridActionsCellItem
+        key="edit"
+        icon={<EditIcon />}
+        label="Edit"
+        to="/todos/edit/$id"
+        params={{ id: params.row.id }}
+      />,
+      <RouterGridActionsCellItem
+        key="delete"
+        icon={<DeleteIcon />}
+        label="Delete"
+        onClick={() => handleDelete(params.row)}
+        showInMenu
+      />,
+    ],
+  },
+];
+```
+
+`RouterGridActionsCellItem` wraps MUI's `GridActionsCellItem` with TanStack Router's `createLink` for type-safe SPA navigation.
+
+### ChipInputCell for array/tag columns
+
+```typescript
+import { ChipInputCell } from "wcz-layout/components";
+import type { GridColDef } from "@mui/x-data-grid-premium";
+
+const columns: GridColDef<Todo>[] = [
+  {
+    field: "tags",
+    headerName: "Tags",
+    flex: 1,
+    renderCell: (params) => <ChipInputCell params={params} />,
+  },
+];
+```
+
+For complex objects (not plain strings), provide `getLabel`:
+
+```typescript
+renderCell: (params) => (
+  <ChipInputCell
+    params={params}
+    getLabel={(item) => item.displayName}
+    slotProps={{ size: "small", color: "primary" }}
+  />
+),
+```
+
+`ChipInputCell` renders a horizontal scrollable stack of `Chip` components. It handles both scalar and array values automatically.
+
+### EditableColumnHeader
+
+```typescript
+import { EditableColumnHeader } from "wcz-layout/components";
+
+const columns: GridColDef<Todo>[] = [
+  {
+    field: "name",
+    headerName: "Name",
+    flex: 1,
+    editable: true,
+    renderHeader: (params) => <EditableColumnHeader {...params} />,
+  },
+];
+```
+
+Renders the column header text with a trailing pencil (Edit) icon to visually indicate editable columns. Purely visual — no interaction.
+
+## Common Mistakes
+
+### HIGH Using DataGrid instead of DataGridPremium
+
+Wrong:
+
+```typescript
+import { DataGrid } from "@mui/x-data-grid";
+```
+
+Correct:
+
+```typescript
+import { DataGridPremium } from "@mui/x-data-grid-premium";
+```
+
+The library peer-depends on `@mui/x-data-grid-premium`. Using the community `DataGrid` loses Premium features like column grouping, row grouping, tree data, and aggregation.
+
+Source: package.json peerDependencies
+
+### HIGH Using GridActionsCellItem instead of RouterGridActionsCellItem
+
+Wrong:
+
+```typescript
+import { GridActionsCellItem } from "@mui/x-data-grid-premium";
+
+<GridActionsCellItem
+  icon={<EditIcon />}
+  label="Edit"
+  onClick={() => navigate({ to: `/todos/${id}` })}
+/>
+```
+
+Correct:
+
+```typescript
+import { RouterGridActionsCellItem } from "wcz-layout/components";
+
+<RouterGridActionsCellItem
+  icon={<EditIcon />}
+  label="Edit"
+  to="/todos/edit/$id"
+  params={{ id }}
+/>
+```
+
+Plain `GridActionsCellItem` doesn't support TanStack Router navigation. `RouterGridActionsCellItem` wraps it with `createLink` for type-safe routing without manual `onClick` + `navigate`.
+
+Source: wcz-layout:src/components/router/RouterGridActionsCellItem.tsx
+
+### MEDIUM Not passing getLabel to ChipInputCell for complex objects
+
+Wrong:
+
+```typescript
+// params.value is Array<{ id: string; name: string }>
+<ChipInputCell params={params} />
+// Renders [object Object] chips
+```
+
+Correct:
+
+```typescript
+<ChipInputCell
+  params={params}
+  getLabel={(item) => item.name}
+/>
+```
+
+`ChipInputCell` defaults `getLabel` to identity (value as-is). For objects, you must provide `getLabel` to extract the display string.
+
+Source: wcz-layout:src/components/data-grid/ChipInputCell.tsx
+
+### HIGH Tension: MUI component API vs. TanStack Router types
+
+`RouterGridActionsCellItem` merges MUI grid action props with TanStack Router `LinkProps`. Use `to` + `params` for internal navigation. Using `onClick` + `navigate` bypasses the type-safe link and router prefetching.
+
+See also: skills/ui-pages/SKILL.md § Common Mistakes
+
+---
+
+See also:
+
+- skills/tanstack-db-collections/SKILL.md — Grid rows come from useLiveQuery results.
+- skills/ui-pages/SKILL.md — Grid pages follow the same routing patterns.

package/skills/database-schema/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: database-schema
+description: >
+  Design PostgreSQL tables with Drizzle ORM pgTable and derive Zod validation
+  schemas via createSelectSchema from drizzle-orm/zod. Covers uuid primary keys,
+  column types, Zod refinements (trim, min, max), and type inference. Drizzle
+  tables live in src/lib/db/schemas/, Zod schemas in src/schemas/. Activate
+  when creating or modifying database tables or validation schemas.
+type: core
+library: wcz-layout
+library_version: "7.6.1"
+sources:
+  - "wcz-layout:src/lib/db/schemas/"
+  - "wcz-layout:src/schemas/"
+  - "drizzle-orm:docs/zod.md"
+---
+
+# Database Schema Design
+
+## Setup
+
+Database schema files live in two directories:
+
+```
+src/lib/db/schemas/todo.ts       # Drizzle pgTable definition
+src/schemas/todo.ts              # Zod schema derived from the table
+```
+
+## Core Patterns
+
+### Drizzle table definition
+
+```typescript
+// src/lib/db/schemas/todo.ts
+import { boolean, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+
+export const todoTable = pgTable("todos", {
+  id: uuid().primaryKey(),
+  name: text().notNull(),
+  description: text(),
+  isCompleted: boolean().notNull().default(false),
+  createdBy: text().notNull(),
+  createdAt: timestamp().notNull().defaultNow(),
+  updatedAt: timestamp().notNull().defaultNow(),
+});
+```
+
+All tables use `uuid().primaryKey()`. IDs are generated client-side with `uuidv7()`.
+
+### Deriving Zod schema from Drizzle
+
+```typescript
+// src/schemas/todo.ts
+import { createSelectSchema } from "drizzle-orm/zod";
+import { todoTable } from "~/lib/db/schemas/todo";
+
+export const TodoSchema = createSelectSchema(todoTable, {
+  name: (schema) => schema.trim().min(1),
+  description: (schema) => schema.trim().nullish(),
+});
+
+export type Todo = typeof TodoSchema._type;
+```
+
+`createSelectSchema` generates a Zod schema matching the table columns. The second argument lets you refine individual fields — add `.trim()`, `.min()`, `.max()`, or replace the schema entirely.
+
+### Insert schema for mutations
+
+```typescript
+// src/schemas/todo.ts
+import { createInsertSchema } from "drizzle-orm/zod";
+
+export const TodoInsertSchema = createInsertSchema(todoTable, {
+  name: (schema) => schema.trim().min(1),
+});
+```
+
+Use `createInsertSchema` when you need a schema for insert operations that omits fields with defaults (like `id`, `createdAt`).
+
+### Type inference
+
+```typescript
+import type { InferSelectModel, InferInsertModel } from "drizzle-orm";
+import { todoTable } from "~/lib/db/schemas/todo";
+
+type Todo = InferSelectModel<typeof todoTable>;
+type NewTodo = InferInsertModel<typeof todoTable>;
+```
+
+Prefer the Zod `_type` for runtime-validated types. Use Drizzle inference types when you need the raw DB shape without validation.
+
+## Common Mistakes
+
+### CRITICAL Writing Zod schemas manually instead of deriving from Drizzle
+
+Wrong:
+
+```typescript
+import { z } from "zod";
+
+export const TodoSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string().trim().min(1),
+  isCompleted: z.boolean(),
+});
+```
+
+Correct:
+
+```typescript
+import { createSelectSchema } from "drizzle-orm/zod";
+import { todoTable } from "~/lib/db/schemas/todo";
+
+export const TodoSchema = createSelectSchema(todoTable, {
+  name: (schema) => schema.trim().min(1),
+});
+```
+
+Manual Zod schemas drift from the database when columns are added or renamed. `createSelectSchema` keeps them in sync automatically.
+
+Source: maintainer interview
+
+### HIGH Placing schema files in wrong directory
+
+Wrong:
+
+```
+src/lib/db/schemas/todo.ts      # Contains both pgTable AND Zod schema
+```
+
+Correct:
+
+```
+src/lib/db/schemas/todo.ts      # Only pgTable definition
+src/schemas/todo.ts             # Zod schema derived from the table
+```
+
+Drizzle table definitions and Zod validation schemas live in separate directories. Mixing them in one file violates the project structure convention.
+
+Source: consumer project structure
+
+### HIGH Forgetting uuid primary key convention
+
+Wrong:
+
+```typescript
+import { serial, pgTable, text } from "drizzle-orm/pg-core";
+
+export const todoTable = pgTable("todos", {
+  id: serial().primaryKey(),
+  name: text().notNull(),
+});
+```
+
+Correct:
+
+```typescript
+import { uuid, pgTable, text } from "drizzle-orm/pg-core";
+
+export const todoTable = pgTable("todos", {
+  id: uuid().primaryKey(),
+  name: text().notNull(),
+});
+```
+
+All tables use `uuid().primaryKey()`. IDs are generated client-side with `uuidv7()` for optimistic inserts through TanStack DB collections.
+
+Source: consumer project example
+
+### HIGH Tension: Type safety vs. rapid prototyping
+
+Deriving Zod schemas from Drizzle tables and wiring them through forms requires more setup than quick `useState` + manual validation. Always use the enforced pattern — `createSelectSchema` + `useLayoutForm` — even for simple forms.
+
+See also: skills/forms-validation/SKILL.md § Core Patterns
+
+---
+
+See also:
+
+- skills/api-routes/SKILL.md — Schemas feed into validationMiddleware(Schema).
+- skills/tanstack-db-collections/SKILL.md — Same Zod schema used as collection schema option.
+- skills/forms-validation/SKILL.md — Zod schemas used as form validators.

package/skills/dialogs-notifications/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: dialogs-notifications
+description: >
+  Use useDialogs for alert/confirm/custom dialogs and useNotification for
+  snackbar messages. Promise-based dialog API with DialogProps type for
+  custom dialogs. Notification severity (success, error, warning, info)
+  with configurable autoHideDuration. Activate when showing confirmations,
+  alerts, custom dialogs, or toast notifications.
+type: core
+library: wcz-layout
+library_version: "7.6.1"
+sources:
+  - "wcz-layout:src/hooks/DialogsHooks.tsx"
+  - "wcz-layout:src/providers/DialogsProvider.tsx"
+  - "wcz-layout:src/contexts/NotificationContext.tsx"
+---
+
+# Dialogs & Notifications
+
+## Setup
+
+Both hooks are available inside the `LayoutProvider` tree (which includes `DialogsProvider` and `NotificationProvider`):
+
+```typescript
+import { useDialogs, useNotification } from "wcz-layout/hooks";
+```
+
+## Core Patterns
+
+### Confirmation dialog before deletion
+
+```typescript
+import { useDialogs, useNotification } from "wcz-layout/hooks";
+import { todoCollection } from "~/lib/db/collections/todoCollection";
+import type { Todo } from "~/schemas/todo";
+
+function DeleteButton({ todo }: { todo: Todo }) {
+  const { confirm } = useDialogs();
+  const { notify } = useNotification();
+
+  const handleDelete = async () => {
+    const confirmed = await confirm("Delete this item?");
+    if (confirmed) {
+      todoCollection.delete(todo);
+      notify("Item deleted", { severity: "success" });
+    }
+  };
+
+  return <Button onClick={handleDelete}>Delete</Button>;
+}
+```
+
+### Alert dialog
+
+```typescript
+const { alert } = useDialogs();
+
+await alert("Operation completed successfully", { title: "Success" });
+// Resolves when user clicks OK
+```
+
+### Custom dialog
+
+Define the dialog component with `DialogProps`:
+
+```typescript
+import type { DialogProps } from "wcz-layout/hooks";
+import {
+  Dialog,
+  DialogTitle,
+  DialogContent,
+  DialogActions,
+  Button,
+  TextField,
+} from "@mui/material";
+import { useState } from "react";
+
+interface NotePayload {
+  title: string;
+}
+
+function NoteDialog({ payload, open, onClose }: DialogProps<NotePayload, string>) {
+  const [note, setNote] = useState("");
+
+  return (
+    <Dialog open={open} onClose={() => onClose("")} maxWidth="sm" fullWidth>
+      <DialogTitle>{payload.title}</DialogTitle>
+      <DialogContent>
+        <TextField
+          autoFocus
+          fullWidth
+          label="Note"
+          value={note}
+          onChange={(e) => setNote(e.target.value)}
+        />
+      </DialogContent>
+      <DialogActions>
+        <Button onClick={() => onClose("")}>Cancel</Button>
+        <Button onClick={() => onClose(note)} variant="contained">
+          Save
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+}
+```
+
+Open the custom dialog and await its result:
+
+```typescript
+const { open } = useDialogs();
+
+const note = await open(NoteDialog, { title: "Add a note" });
+if (note) {
+  // user entered a note
+}
+```
+
+### Dialog API reference
+
+```typescript
+interface DialogHook {
+  alert(message: string, options?: { title?: string }): Promise<void>;
+  confirm(message: string, options?: { title?: string; cancelText?: string }): Promise<boolean>;
+  open<TPayload, TResult>(
+    Component: ComponentType<DialogProps<TPayload, TResult>>,
+    payload?: TPayload,
+    options?: DialogOptions,
+  ): Promise<TResult>;
+  close<TResult>(dialogPromise: Promise<TResult>, result: TResult): Promise<TResult>;
+}
+```
+
+### Notifications
+
+```typescript
+const { notify } = useNotification();
+
+notify("Changes saved", { severity: "success" });
+notify("Something went wrong", { severity: "error" });
+notify("Check your input", { severity: "warning" });
+notify("New version available", { severity: "info" });
+
+// Custom auto-hide duration (default: 5000ms)
+notify("Processing...", { severity: "info", autoHideDuration: 10000 });
+```
+
+### After form submission
+
+```typescript
+const form = useLayoutForm({
+  defaultValues: { name: "" } as Todo,
+  validators: { onChange: TodoSchema },
+  onSubmit: ({ value }) => {
+    todoCollection.insert(value);
+    notify("Todo created", { severity: "success" });
+  },
+});
+```
+
+## Common Mistakes
+
+### HIGH Using window.confirm instead of useDialogs
+
+Wrong:
+
+```typescript
+if (window.confirm("Delete this item?")) {
+  todoCollection.delete(todo);
+}
+```
+
+Correct:
+
+```typescript
+const { confirm } = useDialogs();
+
+const confirmed = await confirm("Delete this item?");
+if (confirmed) {
+  todoCollection.delete(todo);
+}
+```
+
+`window.confirm` is a blocking browser dialog that ignores MUI theming and i18n. `useDialogs().confirm` provides themed, async/await MUI dialogs.
+
+Source: wcz-layout:src/hooks/DialogsHooks.tsx
+
+### CRITICAL Custom dialog not calling onClose
+
+Wrong:
+
+```typescript
+function MyDialog({ payload, open }: DialogProps<string>) {
+  return (
+    <Dialog open={open}>
+      <Button onClick={() => {}}>Done</Button>
+    </Dialog>
+  );
+}
+```
+
+Correct:
+
+```typescript
+function MyDialog({ payload, open, onClose }: DialogProps<string>) {
+  return (
+    <Dialog open={open} onClose={() => onClose()}>
+      <Button onClick={() => onClose()}>Done</Button>
+    </Dialog>
+  );
+}
+```
+
+`open()` returns a `Promise` that resolves when `onClose(result)` is called. Forgetting `onClose` leaves the promise hanging permanently and the dialog stuck open. Always wire both the `Dialog` `onClose` prop and button click handlers.
+
+Source: wcz-layout:src/providers/DialogsProvider.tsx
+
+### HIGH Using useDialogs outside LayoutProvider tree
+
+Wrong:
+
+```typescript
+// Component rendered outside LayoutProvider
+function StandaloneComponent() {
+  const { alert } = useDialogs(); // context has unsafe default — crashes on call
+}
+```
+
+Correct:
+
+Ensure all components using `useDialogs` or `useNotification` are rendered inside the `LayoutProvider` component tree (which wraps `DialogsProvider` and `NotificationProvider`).
+
+`DialogsContext` uses an unsafe cast default value. Accessing the context outside the provider doesn't throw on `useContext`, but crashes when `alert`, `confirm`, or `open` are invoked.
+
+Source: wcz-layout:src/contexts/DialogsContext.ts
+
+---
+
+See also:
+
+- skills/forms-validation/SKILL.md — Form submissions typically show notifications or confirmations.