@tailor-platform/app-shell 1.13.0 → 1.14.0

package/skills/app-shell-patterns/references/patterns/form-single-page.md

@@ -4,7 +4,7 @@ name: Single Page Form
 category: pattern
 subcategory: form
 description: Routed full-page form for moderate field count (6-15) without natural sectioning
-requiredImports: [Layout, Form, Field, Fieldset, Input, Textarea, Select, Button]
+requiredImports: [Layout, Form, Field, Textarea, Select, Button]
 tags: [form, page, create, edit, routed]
 do:
   - A routed Create or Edit page that the design has explicitly called out (e.g. /orders/create)
@@ -26,65 +26,81 @@ dont:
 
 ```tsx
 /* pattern: form/single-page */
-import { Button, Layout, Input, Textarea, Select, Field } from "@tailor-platform/app-shell";
+import { Button, Field, Form, Textarea, Layout, Select } from "@tailor-platform/app-shell";
+
+const CATEGORIES = ["Electronics", "Furniture", "Clothing", "Food"];
+
+type ProductDraft = {
+  name: string;
+  sku: string;
+  category: string;
+  price: string;
+  description: string;
+};
 
 type Props = {
-  onSave: (data: Record<string, string>) => void;
+  onSave: (data: ProductDraft) => void;
   onCancel: () => void;
 };
 
 export default function SinglePageForm({ onSave, onCancel }: Props) {
   return (
     <Layout>
+      {/*
+       * Save/Cancel live in the page header and reach the form through the
+       * native `form` attribute, matching `Form`'s `id`. No state plumbing.
+       */}
       <Layout.Header
-        title="Create Product"
+        title="Create product"
         actions={[
           <Button key="cancel" variant="outline" onClick={onCancel}>
             Cancel
           </Button>,
-          <Button key="save" type="submit" form="single-page-form">
+          <Button key="save" type="submit" form="product-form">
             Save
           </Button>,
         ]}
       />
       <Layout.Column>
-        <form
-          id="single-page-form"
-          onSubmit={(e) => {
-            e.preventDefault();
-            const formData = new FormData(e.currentTarget);
-            const entries: Record<string, string> = {};
-            formData.forEach((value, key) => {
-              entries[key] = value as string;
-            });
-            onSave(entries);
-          }}
-          className="space-y-4 max-w-2xl"
+        <Form<ProductDraft>
+          id="product-form"
+          noValidate
+          className="max-w-2xl space-y-4"
+          onFormSubmit={(values) => onSave(values)}
         >
           <Field.Root name="name">
             <Field.Label>Name</Field.Label>
-            <Field.Control render={<Input />} />
+            <Field.Control required />
+            <Field.Error match="valueMissing">Name is required.</Field.Error>
           </Field.Root>
           <Field.Root name="sku">
             <Field.Label>SKU</Field.Label>
-            <Field.Control render={<Input />} />
+            <Field.Control required pattern="[A-Z]{3}-[0-9]{4}" />
+            <Field.Description>Format: ABC-1234</Field.Description>
+            <Field.Error match="patternMismatch">Use the format ABC-1234.</Field.Error>
+            <Field.Error match="valueMissing">SKU is required.</Field.Error>
           </Field.Root>
+          {/*
+           * Dropdowns need no `name` and no React state: `Field.Root` registers
+           * the control, so its value arrives in `onFormSubmit` under the
+           * field's name like any other input.
+           */}
           <Field.Root name="category">
             <Field.Label>Category</Field.Label>
-            <Select
-              items={["Electronics", "Furniture", "Clothing", "Food"]}
-              placeholder="Select category"
-            />
+            <Select items={CATEGORIES} placeholder="Select category" />
+            <Field.Error />
           </Field.Root>
           <Field.Root name="price">
             <Field.Label>Price</Field.Label>
-            <Field.Control render={<Input type="number" />} />
+            <Field.Control type="number" required min={0} step="0.01" />
+            <Field.Error match="rangeUnderflow">Price cannot be negative.</Field.Error>
+            <Field.Error match="valueMissing">Price is required.</Field.Error>
           </Field.Root>
           <Field.Root name="description">
             <Field.Label>Description</Field.Label>
             <Textarea rows={4} />
           </Field.Root>
-        </form>
+        </Form>
       </Layout.Column>
     </Layout>
   );
@@ -96,6 +112,20 @@ export default function SinglePageForm({ onSave, onCancel }: Props) {
 - Single column full width below 1024px; single column max-w constrained at 1024–1280px
 - Without an explicit routed-page requirement, the answer is `form/modal`
 - A `/create` or `/edit` route in the screen spec does NOT require a full-page replacement
+- Save/Cancel belong in `Layout.Header`, wired with `<Button type="submit" form="…">` matching the
+  `Form`'s `id` (requires 1.13.0+)
+- Validation lives on the fields (`required`, `pattern`, `min`, `type`) with a matching
+  `Field.Error match="…"`; `Form` gates submit on it
+
+## 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.
+
+This pattern is the reference for the simple case: every field, dropdowns included, is
+uncontrolled and arrives through `onFormSubmit`. No component state at all.
 
 ## Anti-patterns
 
@@ -103,3 +133,5 @@ export default function SinglePageForm({ onSave, onCancel }: Props) {
 - No required-field markers — users can't predict which fields will error
 - Errors shown above the form rather than below the offending field
 - Choosing this pattern for a Create flow because it's a Create flow — without explicit need, use `form/modal`
+- Making fields controlled "for consistency" — nothing on this page needs React state
+- Giving `Select` a `name` to make it submit — inside a `Field.Root` that is already handled

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`