wcz-layout 7.6.1 → 7.6.2

package/skills/forms-validation/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: forms-validation
+description: >
+  Build forms with useLayoutForm hook (primary) and withLayoutForm for
+  composable sub-forms. 13 pre-registered MUI field components via
+  form.AppField: TextField, NumberField, Autocomplete, Checkbox, Switch,
+  RadioGroup, Slider, DatePicker, DateRangePicker, TimePicker,
+  TimeRangePicker, DateTimePicker, DateTimeRangePicker. SubmitButton in
+  form.AppForm. Zod onChange validators. FormOmittedProps type. Activate
+  when creating or modifying forms with validation.
+type: core
+library: wcz-layout
+library_version: "7.6.1"
+sources:
+  - "wcz-layout:src/hooks/FormHooks.ts"
+  - "wcz-layout:src/components/form/"
+  - "wcz-layout:src/lib/utils.ts"
+references:
+  - "references/field-components.md"
+---
+
+# Forms & Validation
+
+## Setup
+
+Import the form hook and Zod schema:
+
+```typescript
+import { useLayoutForm } from "wcz-layout/hooks";
+import { TodoSchema } from "~/schemas/todo";
+```
+
+## Core Patterns
+
+### Basic form with useLayoutForm
+
+```typescript
+import { useLayoutForm } from "wcz-layout/hooks";
+import { TodoSchema } from "~/schemas/todo";
+import type { Todo } from "~/schemas/todo";
+import { todoCollection } from "~/lib/db/collections/todoCollection";
+import { uuidv7 } from "uuidv7";
+
+function TodoForm() {
+  const form = useLayoutForm({
+    defaultValues: {
+      id: uuidv7(),
+      name: "",
+      description: "",
+      isCompleted: false,
+    } as Todo,
+    validators: {
+      onChange: TodoSchema,
+    },
+    onSubmit: ({ value }) => {
+      todoCollection.insert(value);
+    },
+  });
+
+  return (
+    <form.AppForm>
+      <form.AppField
+        name="name"
+        children={(field) => <field.TextField label="Name" required />}
+      />
+      <form.AppField
+        name="description"
+        children={(field) => <field.TextField label="Description" multiline rows={3} />}
+      />
+      <form.AppField
+        name="isCompleted"
+        children={(field) => <field.Checkbox label="Completed" />}
+      />
+      <form.SubmitButton />
+    </form.AppForm>
+  );
+}
+```
+
+### Available field components
+
+All 13 field components are accessed through `field.*` inside `form.AppField`:
+
+| Component                   | MUI base                    | Use case                      |
+| --------------------------- | --------------------------- | ----------------------------- |
+| `field.TextField`           | TextField                   | Text input, multiline         |
+| `field.NumberField`         | TextField (number)          | Numeric input                 |
+| `field.Autocomplete`        | Autocomplete                | Search/select with options    |
+| `field.Checkbox`            | FormControlLabel + Checkbox | Boolean toggle                |
+| `field.Switch`              | FormControlLabel + Switch   | Boolean toggle (switch)       |
+| `field.RadioGroup`          | RadioGroup                  | Single selection from options |
+| `field.Slider`              | Slider                      | Range/value slider            |
+| `field.DatePicker`          | DatePicker                  | Date only                     |
+| `field.DateRangePicker`     | DateRangePicker             | Date range                    |
+| `field.TimePicker`          | TimePicker                  | Time only                     |
+| `field.TimeRangePicker`     | TimeRangePicker             | Time range                    |
+| `field.DateTimePicker`      | DateTimePicker              | Date + time                   |
+| `field.DateTimeRangePicker` | DateTimeRangePicker         | Date + time range             |
+
+See references/field-components.md for detailed prop surfaces.
+
+### Edit form with existing data
+
+```typescript
+function TodoEditForm({ todo }: { todo: Todo }) {
+  const form = useLayoutForm({
+    defaultValues: todo,
+    validators: {
+      onChange: TodoSchema,
+    },
+    onSubmit: ({ value }) => {
+      todoCollection.update(value);
+    },
+  });
+
+  return (
+    <form.AppForm>
+      <form.AppField
+        name="name"
+        children={(field) => <field.TextField label="Name" required />}
+      />
+      <form.SubmitButton />
+    </form.AppForm>
+  );
+}
+```
+
+### Sub-form composition with withLayoutForm
+
+Use `withLayoutForm` when splitting a large form into reusable sub-form components:
+
+```typescript
+import { withLayoutForm } from "wcz-layout/hooks";
+import { TodoSchema } from "~/schemas/todo";
+
+const TodoDetailsSubForm = withLayoutForm({
+  defaultValues: { name: "", description: "" },
+  render: ({ form }) => (
+    <>
+      <form.AppField
+        name="name"
+        children={(field) => <field.TextField label="Name" required />}
+      />
+      <form.AppField
+        name="description"
+        children={(field) => <field.TextField label="Description" multiline />}
+      />
+    </>
+  ),
+});
+```
+
+### Autocomplete with API data
+
+```typescript
+<form.AppField
+  name="assigneeId"
+  children={(field) => (
+    <field.Autocomplete
+      label="Assignee"
+      options={users}
+      getOptionLabel={(user) => user.displayName}
+      isOptionEqualToValue={(option, value) => option.id === value.id}
+    />
+  )}
+/>
+```
+
+### Date pickers
+
+```typescript
+<form.AppField
+  name="dueDate"
+  children={(field) => <field.DatePicker label="Due Date" />}
+/>
+
+<form.AppField
+  name="dateRange"
+  children={(field) => (
+    <field.DateRangePicker
+      localeText={{ start: "Start Date", end: "End Date" }}
+    />
+  )}
+/>
+```
+
+## Common Mistakes
+
+### CRITICAL Using raw MUI TextField instead of form.AppField
+
+Wrong:
+
+```typescript
+<TextField
+  name="title"
+  value={title}
+  onChange={(e) => setTitle(e.target.value)}
+/>
+```
+
+Correct:
+
+```typescript
+<form.AppField
+  name="title"
+  children={(field) => <field.TextField label="Title" />}
+/>
+```
+
+`useLayoutForm` pre-registers all field components. Using raw MUI inputs bypasses TanStack Form state management, validation, and error display.
+
+Source: wcz-layout:src/hooks/FormHooks.ts
+
+### HIGH Passing name/value/onChange to AppField components
+
+Wrong:
+
+```typescript
+<form.AppField
+  name="title"
+  children={(field) => (
+    <field.TextField
+      label="Title"
+      name="title"
+      value={field.state.value}
+      onChange={(e) => field.handleChange(e.target.value)}
+    />
+  )}
+/>
+```
+
+Correct:
+
+```typescript
+<form.AppField
+  name="title"
+  children={(field) => <field.TextField label="Title" />}
+/>
+```
+
+`FormOmittedProps` explicitly strips `name`, `value`, `onChange`, `onBlur`, `error`, `helperText`, `renderInput`, `type`, and `aria-label`. These are managed internally by `useFieldContext`. Passing them causes conflicts or is silently ignored.
+
+Source: wcz-layout:src/lib/utils.ts
+
+### HIGH Not wrapping SubmitButton in form.AppForm
+
+Wrong:
+
+```typescript
+<div>
+  <form.AppField name="name" children={(field) => <field.TextField label="Name" />} />
+  <form.SubmitButton /> {/* Outside AppForm — crashes */}
+</div>
+```
+
+Correct:
+
+```typescript
+<form.AppForm>
+  <form.AppField name="name" children={(field) => <field.TextField label="Name" />} />
+  <form.SubmitButton />
+</form.AppForm>
+```
+
+`SubmitButton` uses `useFormContext()` to read `canSubmit` and `isSubmitting` state. It must be rendered inside `form.AppForm`.
+
+Source: wcz-layout:src/components/form/FormSubmitButton.tsx
+
+### HIGH Using useMemo or useCallback in form components
+
+Wrong:
+
+```typescript
+const handleSubmit = useCallback(() => form.handleSubmit(), [form]);
+```
+
+Correct:
+
+```typescript
+const handleSubmit = () => form.handleSubmit();
+```
+
+React Compiler handles memoization. Manual `useMemo` / `useCallback` is forbidden per project conventions.
+
+Source: copilot-instructions.md
+
+Cross-skill: See also skills/ui-pages/SKILL.md § Common Mistakes
+
+### MEDIUM FormRadioGroup numeric values become strings
+
+Wrong:
+
+```typescript
+<field.RadioGroup
+  options={[
+    { label: "Low", value: 1 },
+    { label: "High", value: 2 },
+  ]}
+/>
+// field.state.value is "1" not 1
+```
+
+Correct:
+
+```typescript
+<field.RadioGroup
+  options={[
+    { label: "Low", value: "1" },
+    { label: "High", value: "2" },
+  ]}
+/>
+// Use string values consistently, or convert in onSubmit
+```
+
+Radio group `onChange` always returns `event.target.value` as a string. Numeric option values round-trip as strings unless explicitly converted.
+
+Source: wcz-layout:src/components/form/FormRadioGroup.tsx
+
+### HIGH Tension: Type safety vs. rapid prototyping
+
+Quick forms using `useState` + manual validation bypass the enforced pattern. Always use `useLayoutForm` + Zod schema derived from Drizzle — even for simple forms. The boilerplate pays off in type safety and consistency.
+
+See also: skills/database-schema/SKILL.md § Common Mistakes
+
+---
+
+See also:
+
+- skills/database-schema/SKILL.md — Zod schemas used as form validators.
+- skills/dialogs-notifications/SKILL.md — Form submissions typically show notifications.
+- skills/ui-pages/SKILL.md — Create/edit pages embed forms.

package/skills/forms-validation/references/field-components.md

@@ -0,0 +1,212 @@
+# Field Components Reference
+
+All field components are accessed via `field.*` inside a `form.AppField` children render prop. Props listed below are the MUI props you can pass — `FormOmittedProps` (`name`, `value`, `onChange`, `onBlur`, `error`, `helperText`, `renderInput`, `type`, `aria-label`) are automatically stripped and managed by TanStack Form.
+
+## TextField
+
+```typescript
+<form.AppField
+  name="title"
+  children={(field) => (
+    <field.TextField
+      label="Title"
+      required
+      multiline          // optional: enables textarea
+      rows={3}           // optional: fixed row count for multiline
+      placeholder="..."  // optional
+      disabled           // optional
+      slotProps={{        // optional: MUI slot props
+        input: { startAdornment: <InputAdornment position="start">$</InputAdornment> }
+      }}
+    />
+  )}
+/>
+```
+
+## NumberField
+
+```typescript
+<form.AppField
+  name="quantity"
+  children={(field) => (
+    <field.NumberField
+      label="Quantity"
+      required
+      slotProps={{
+        input: { inputProps: { min: 0, max: 100, step: 1 } }
+      }}
+    />
+  )}
+/>
+```
+
+## Autocomplete
+
+```typescript
+<form.AppField
+  name="assignee"
+  children={(field) => (
+    <field.Autocomplete
+      label="Assignee"
+      options={users}
+      getOptionLabel={(user) => user.displayName}
+      isOptionEqualToValue={(option, value) => option.id === value.id}
+      multiple               // optional: multi-select
+      freeSolo               // optional: allow custom input
+      loading={isLoading}    // optional: show loading indicator
+    />
+  )}
+/>
+```
+
+## Checkbox
+
+```typescript
+<form.AppField
+  name="isActive"
+  children={(field) => (
+    <field.Checkbox
+      label="Active"
+      disabled  // optional
+    />
+  )}
+/>
+```
+
+Renders `FormControlLabel` wrapping MUI `Checkbox`.
+
+## Switch
+
+```typescript
+<form.AppField
+  name="notifications"
+  children={(field) => (
+    <field.Switch
+      label="Enable Notifications"
+      disabled  // optional
+    />
+  )}
+/>
+```
+
+Renders `FormControlLabel` wrapping MUI `Switch`.
+
+## RadioGroup
+
+```typescript
+<form.AppField
+  name="priority"
+  children={(field) => (
+    <field.RadioGroup
+      label="Priority"
+      options={[
+        { label: "Low", value: "low" },
+        { label: "Medium", value: "medium" },
+        { label: "High", value: "high" },
+      ]}
+      row  // optional: horizontal layout
+    />
+  )}
+/>
+```
+
+**Warning:** `onChange` returns `event.target.value` as a string. Use string values.
+
+## Slider
+
+```typescript
+<form.AppField
+  name="rating"
+  children={(field) => (
+    <field.Slider
+      min={0}
+      max={10}
+      step={1}
+      marks
+      valueLabelDisplay="auto"
+    />
+  )}
+/>
+```
+
+## DatePicker
+
+```typescript
+<form.AppField
+  name="dueDate"
+  children={(field) => (
+    <field.DatePicker
+      label="Due Date"
+      minDate={dayjs()}       // optional
+      maxDate={dayjs().add(1, "year")}  // optional
+    />
+  )}
+/>
+```
+
+## DateRangePicker
+
+```typescript
+<form.AppField
+  name="dateRange"
+  children={(field) => (
+    <field.DateRangePicker
+      localeText={{ start: "Start", end: "End" }}
+    />
+  )}
+/>
+```
+
+## TimePicker
+
+```typescript
+<form.AppField
+  name="startTime"
+  children={(field) => (
+    <field.TimePicker
+      label="Start Time"
+      ampm={false}  // optional: 24-hour format
+    />
+  )}
+/>
+```
+
+## TimeRangePicker
+
+```typescript
+<form.AppField
+  name="timeRange"
+  children={(field) => (
+    <field.TimeRangePicker
+      localeText={{ start: "From", end: "To" }}
+    />
+  )}
+/>
+```
+
+## DateTimePicker
+
+```typescript
+<form.AppField
+  name="scheduledAt"
+  children={(field) => (
+    <field.DateTimePicker
+      label="Scheduled At"
+      ampm={false}
+    />
+  )}
+/>
+```
+
+## DateTimeRangePicker
+
+```typescript
+<form.AppField
+  name="availability"
+  children={(field) => (
+    <field.DateTimeRangePicker
+      localeText={{ start: "From", end: "Until" }}
+    />
+  )}
+/>
+```