@tailor-platform/app-shell 1.12.0 → 1.14.0

package/skills/app-shell-patterns/references/patterns/form-wizard.md

@@ -4,15 +4,16 @@ name: Wizard Form
 category: pattern
 subcategory: form
 description: Multi-stage create flow with 3-7 steps and per-step validation gates
-requiredImports: [Layout, Card, Form, Fieldset, Field, Input, Select, Badge, Button]
-tags: [form, wizard, multi-step, import, stepper]
+requiredImports: [Layout, Card, Badge, Form, Fieldset, Field, Select, Button]
+tags: [form, wizard, multi-step, stepper, onboarding]
 do:
   - Multi-stage Create with 3-7 steps
-  - Import flows (upload → map → validate → confirm)
+  - Onboarding and request flows where users should focus on one step at a time
   - Per-step validation gates progression
 dont:
   - Single screen of fields — use form/modal or form/single-page
   - More than 7 steps — split into separate routed pages or reduce scope
+  - CSV/spreadsheet import — use the CsvImporter component, not a hand-built wizard
 ---
 
 # pattern/form/wizard
@@ -20,102 +21,166 @@ dont:
 ## When to Use
 
 - Multi-stage Create with 3–7 steps
-- Import flows (upload → map → validate → confirm)
+- Onboarding and request flows where users should focus on one step at a time
 - Per-step validation gates progression
 
+For CSV/spreadsheet import specifically, use the `CsvImporter` component — it already implements
+the upload → map → validate → confirm flow. Don't rebuild it here.
+
 ## Page Implementation
 
 ```tsx
 /* pattern: form/wizard */
 import { useState } from "react";
-import { Button, Card, Layout, Badge, Input, Field } from "@tailor-platform/app-shell";
+import {
+  Badge,
+  Button,
+  Card,
+  Field,
+  Fieldset,
+  Form,
+  Layout,
+  Select,
+} from "@tailor-platform/app-shell";
+
+const OWNERS = ["Tanaka", "Sato", "Suzuki", "Yamada"];
+const STEPS = ["Basic info", "Assignment", "Schedule", "Review"] as const;
+
+type Draft = {
+  title: string;
+  description: string;
+  owner: string;
+  startDate: string;
+  estimate: string;
+};
 
-const STEPS = ["Upload", "Map", "Review", "Done"] as const;
+const INITIAL: Draft = {
+  title: "",
+  description: "",
+  owner: "",
+  startDate: "",
+  estimate: "",
+};
 
 type Props = {
-  onComplete: () => void;
+  onComplete: (draft: Draft) => void;
+  onCancel: () => void;
 };
 
-export default function WizardForm({ onComplete }: Props) {
-  const [currentStep, setCurrentStep] = useState(0);
-
-  const handleNext = () => {
-    if (currentStep < STEPS.length - 1) {
-      setCurrentStep(currentStep + 1);
-    } else {
-      onComplete();
-    }
-  };
-
-  const handleBack = () => {
-    if (currentStep > 0) {
-      setCurrentStep(currentStep - 1);
+export default function WizardForm({ onComplete, onCancel }: Props) {
+  const [step, setStep] = useState(0);
+  // Accumulated values. Each step's Form unmounts on navigation, so the draft
+  // is what makes Back non-destructive — fields re-read it via `defaultValue`.
+  const [draft, setDraft] = useState<Draft>(INITIAL);
+
+  const isLastStep = step === STEPS.length - 1;
+
+  /**
+   * Each step is its own `Form`, and "Next" is a `type="submit"` button.
+   * `onFormSubmit` fires only after that step's fields pass validation, so
+   * progression is gated natively — no manual per-step validity check, and
+   * no deferring every error to the final submit.
+   */
+  const handleStepSubmit = (values: Record<string, unknown>) => {
+    const merged = { ...draft, ...(values as Partial<Draft>) };
+    setDraft(merged);
+    if (isLastStep) {
+      onComplete(merged);
+      return;
     }
+    setStep(step + 1);
   };
 
   return (
     <Layout>
-      <Layout.Header title="Import products" />
+      <Layout.Header title="Create task" />
       <Layout.Column>
         <Card.Root>
           <Card.Content>
             <div className="flex items-center gap-2">
-              {STEPS.map((step, i) => (
+              {STEPS.map((label, i) => (
                 <Badge
-                  key={step}
-                  variant={i === currentStep ? "default" : i < currentStep ? "success" : "neutral"}
+                  key={label}
+                  variant={i === step ? "default" : i < step ? "success" : "neutral"}
                 >
-                  {i + 1}. {step}
+                  {i + 1}. {label}
                 </Badge>
               ))}
             </div>
           </Card.Content>
         </Card.Root>
 
-        <Card.Root>
-          <Card.Content>
-            {currentStep === 0 && (
-              <div className="space-y-4">
-                <Field.Root name="file">
-                  <Field.Label>CSV file</Field.Label>
-                  <Field.Control render={<Input type="file" accept=".csv" />} />
+        <Form key={step} noValidate onFormSubmit={handleStepSubmit}>
+          <Card.Root>
+            <Card.Header title={STEPS[step]} />
+            <Card.Content>
+              {step === 0 && (
+                <Fieldset.Root className="space-y-4">
+                  <Field.Root name="title">
+                    <Field.Label>Title</Field.Label>
+                    <Field.Control required defaultValue={draft.title} />
+                    <Field.Error match="valueMissing">Title is required.</Field.Error>
+                  </Field.Root>
+                  <Field.Root name="description">
+                    <Field.Label>Description</Field.Label>
+                    <Field.Control defaultValue={draft.description} />
+                  </Field.Root>
+                </Fieldset.Root>
+              )}
+
+              {step === 1 && (
+                <Field.Root name="owner">
+                  <Field.Label>Owner</Field.Label>
+                  {/* Uncontrolled like every other field — `defaultValue`
+                      restores the prior choice when the user steps Back. */}
+                  <Select
+                    items={OWNERS}
+                    defaultValue={draft.owner || null}
+                    placeholder="Assign owner"
+                  />
                 </Field.Root>
-              </div>
-            )}
-            {currentStep === 1 && (
-              <div className="space-y-4">
-                <p className="text-sm text-muted-foreground">Map CSV columns to product fields</p>
-                <Field.Root name="nameColumn">
-                  <Field.Label>Name column</Field.Label>
-                  <Field.Control render={<Input placeholder="e.g. Column A" />} />
-                </Field.Root>
-                <Field.Root name="skuColumn">
-                  <Field.Label>SKU column</Field.Label>
-                  <Field.Control render={<Input placeholder="e.g. Column B" />} />
-                </Field.Root>
-              </div>
-            )}
-            {currentStep === 2 && (
-              <div className="space-y-4">
-                <p className="text-sm text-muted-foreground">
-                  Review your import — 42 products will be created.
-                </p>
-              </div>
-            )}
-            {currentStep === 3 && (
-              <div className="space-y-4">
-                <p className="text-sm text-foreground">Import complete! 42 products created.</p>
-              </div>
-            )}
-          </Card.Content>
-        </Card.Root>
-
-        <div className="flex justify-between">
-          <Button variant="ghost" onClick={handleBack} disabled={currentStep === 0}>
-            Back
-          </Button>
-          <Button onClick={handleNext}>{currentStep === STEPS.length - 1 ? "Done" : "Next"}</Button>
-        </div>
+              )}
+
+              {step === 2 && (
+                <Fieldset.Root className="grid gap-4 md:grid-cols-2">
+                  <Field.Root name="startDate">
+                    <Field.Label>Start date</Field.Label>
+                    <Field.Control type="date" required defaultValue={draft.startDate} />
+                    <Field.Error match="valueMissing">Start date is required.</Field.Error>
+                  </Field.Root>
+                  <Field.Root name="estimate">
+                    <Field.Label>Estimate (hours)</Field.Label>
+                    <Field.Control type="number" min={0} defaultValue={draft.estimate} />
+                  </Field.Root>
+                </Fieldset.Root>
+              )}
+
+              {step === 3 && (
+                <dl className="grid grid-cols-2 gap-2 text-sm">
+                  <dt className="text-muted-foreground">Title</dt>
+                  <dd>{draft.title}</dd>
+                  <dt className="text-muted-foreground">Owner</dt>
+                  <dd>{draft.owner || "—"}</dd>
+                  <dt className="text-muted-foreground">Start date</dt>
+                  <dd>{draft.startDate || "—"}</dd>
+                  <dt className="text-muted-foreground">Estimate</dt>
+                  <dd>{draft.estimate ? `${draft.estimate}h` : "—"}</dd>
+                </dl>
+              )}
+            </Card.Content>
+          </Card.Root>
+
+          <div className="flex justify-between pt-4">
+            <Button
+              type="button"
+              variant="ghost"
+              onClick={() => (step === 0 ? onCancel() : setStep(step - 1))}
+            >
+              {step === 0 ? "Cancel" : "Back"}
+            </Button>
+            <Button type="submit">{isLastStep ? "Create" : "Next"}</Button>
+          </div>
+        </Form>
       </Layout.Column>
     </Layout>
   );
@@ -128,9 +193,32 @@ export default function WizardForm({ onComplete }: Props) {
 - Back-navigation must preserve prior step's input
 - Validation must be per-step — don't defer until final submit
 - Step indicator collapses to "Step 2 of 4" label below 1024px
+- One `<Form>` rendered per step, keyed by step index so it remounts cleanly
+- Accumulated values live in a `draft` state object above the `Form`; each step's fields read
+  their initial value from it via `defaultValue`
+
+## Form state
+
+Rules that apply to every `form/*` pattern are in **`components.md`** → Forms, with a worked example
+in **`form/modal`** → Form state: `Form` + `Field` is the default stack, submit via `onFormSubmit`,
+dropdowns need only a wrapping `Field.Root` (no `name`, no state), server errors route through
+`errors`, and React Hook Form is an optional escape hatch.
+
+The wizard's specific mechanic: **make "Next" a `type="submit"` button.** `onFormSubmit` fires only
+after the current step's fields pass validation, so progression is gated natively — no manual
+validity check, and no deferring errors to the final submit. The handler merges that step's values
+into `draft` and advances; on the last step it calls the completion callback instead.
+
+Because each step's `Form` unmounts on navigation, values must be lifted into `draft` — that is
+what makes Back non-destructive. Every field, dropdowns included, is uncontrolled and re-reads its
+prior value from `draft` via `defaultValue`; nothing needs an `onChange`.
 
 ## Anti-patterns
 
 - More than 7 steps — users lose context and abandon
 - No back-navigation preservation — pressing Back loses prior step's input
 - Validation deferred until final submit — failures force full re-traversal
+- A plain `onClick` "Next" that advances without validating — use `type="submit"` and let
+  `onFormSubmit` gate it
+- Wrapping all steps in one `<Form>` and hiding inactive ones — hidden required fields block submit
+- Hand-building a CSV import wizard — use `CsvImporter`