@tailor-platform/app-shell 1.13.0 → 1.15.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`

package/skills/app-shell-patterns/references/patterns/interaction-multi-select.md

@@ -87,7 +87,7 @@ export default function MultiSelect({ orders, onArchive, onExport }: Props) {
       <Table.Root>
         <Table.Header>
           <Table.Row>
-            <Table.Head className="astw:w-10">
+            <Table.Head className="w-10">
               <input
                 type="checkbox"
                 checked={selectedIds.size === orders.length && orders.length > 0}

package/skills/app-shell-patterns/references/patterns/detail-hero-with-actions.md

@@ -1,201 +0,0 @@
----
-slug: pattern/detail/hero-with-actions
-name: Hero With Actions Detail
-category: pattern
-subcategory: detail
-description: Single-record detail view with workflow actions and activity timeline
-requiredImports:
-  [
-    Layout,
-    Badge,
-    Button,
-    Menu,
-    DescriptionCard,
-    Card,
-    Table,
-    ActionPanel,
-    ActivityCard,
-    Grid,
-    MetricCard,
-    DocumentProgressCard,
-    Alert,
-  ]
-tags: [detail, actions, timeline, workflow, two-column]
-do:
-  - Single-record detail view (Order #1234, Supplier ABC, Product SKU-42)
-  - Record has a workflow with named actions (Approve, Cancel, Ship)
-  - An activity/audit history is meaningful to surface
-dont:
-  - The page primarily compares two grids or record sets (match/reconcile)
-  - The record is purely informational with no actions and no history — use list/dense-scan row click into a sheet instead
----
-
-# pattern/detail/hero-with-actions
-
-## When to Use
-
-- Single-record detail view (Order #1234, Supplier ABC, Product SKU-42)
-- Record has a workflow with named actions (Approve, Cancel, Ship)
-- An activity/audit history is meaningful to surface
-
-## Layout
-
-```
-+---------------------------------------------------------+
-| Layout.Header  title  [Badge]            [Primary CTA]  |
-+----------------------------------+----------------------+
-| Layout.Column (main)             | Layout.Column right  |
-|  DescriptionCard  Summary        |  ActionPanel         |
-|   - field : value                |   - Approve          |
-|   - field : value                |   - Cancel           |
-|  Card  Attachments               |                      |
-|   - file rows                    |  ActivityCard        |
-|  Card  Line items                |   - history entry    |
-|   inline Table.Root              |   - history entry    |
-|                                  |  (…N more side cards |
-|                                  |   per use case)      |
-+----------------------------------+----------------------+
-```
-
-Composition rules:
-
-- Both columns accept N cards based on the use case — add as many sections as the record requires.
-- Each main-column section sits in a `Card` container — except `DescriptionCard`, which already provides its own container and must not be double-wrapped in a `Card`.
-- Right-column cards (`ActionPanel`, `ActivityCard`, related summaries, etc.) are composed the same way. `ActionPanel` and `ActivityCard` are the most common; neither is mandatory.
-
-Responsive: <1024 collapses to single column with right column rendered below main; 1024–1280 two columns with narrow side; >1280 two columns at full width.
-
-## Layout variants
-
-Choose the column structure from the **record** — the pattern is "hero + workflow + (optional) history," and the layout flexes. The skill never mandates a fixed column count.
-
-- **Main + right rail** (most common) — the record has workflow actions and/or activity/related summaries → right `Layout.Column area="right"` holds `ActionPanel`, `ActivityCard`, integration cards.
-- **Single main column** — the record is mostly descriptive with few/no workflow actions and no meaningful history → one `Layout.Column`. Don't invent a rail just to fill space.
-- **Main + left rail** (`area="left"`, wider 320px) — when a persistent section index / summary should lead the reading order.
-- Either column holds **N cards** as the record requires.
-
-## Optional cards
-
-Add these only when the record calls for them — none is mandatory. Each is a card like any other in the columns above.
-
-- **Metric strip** — when the record has headline KPIs (totals, counts), lead the main column with `MetricCard`s wrapped in a `Grid` (never one per row). See the `Grid` and `MetricCard` entries in `components.md`.
-
-  ```tsx
-  <Grid columns={{ initial: 1, md: 2, xl: 4 }} gap={4}>
-    <MetricCard title="Net total" value="$12,480" trend={{ direction: "up", value: "+4%" }} />
-    <MetricCard title="Lines" value="18" />
-    <MetricCard title="Received" value="11" />
-    <MetricCard title="Outstanding" value="7" />
-  </Grid>
-  ```
-
-- **`DocumentProgressCard`** — when the record has a fulfilment / lifecycle breakdown (received vs returned vs pending, shipment status). Sits in the main column or the right rail; derive `percent` and `segments` in the consumer.
-- **`Alert`** — a record-level inline banner (blocking error, on-hold warning) above the columns; use the **error** variant for the pattern's required error state. Transient feedback uses `useToast`, not `Alert`.
-
-## Page Implementation
-
-```tsx
-/* pattern: detail/hero-with-actions */
-import {
-  Layout,
-  Badge,
-  Button,
-  Card,
-  DescriptionCard,
-  Table,
-  ActionPanel,
-  ActivityCard,
-} from "@tailor-platform/app-shell";
-import type { Order } from "./mock";
-
-type Props = {
-  order: Order;
-  onApprove: () => void;
-  onCancel: () => void;
-};
-
-export default function HeroWithActionsDetail({ order, onApprove, onCancel }: Props) {
-  return (
-    <Layout>
-      <Layout.Header
-        title={`Order ${order.number}`}
-        actions={[
-          <Badge key="status" variant="success">
-            {order.status}
-          </Badge>,
-          <Button key="edit">Edit</Button>,
-        ]}
-      />
-      <Layout.Column>
-        <DescriptionCard
-          title="Summary"
-          data={order}
-          columns={3}
-          fields={[
-            { key: "number", label: "Order number" },
-            {
-              key: "status",
-              label: "Status",
-              type: "badge",
-              meta: { badgeVariantMap: { Confirmed: "success", Draft: "neutral" } },
-            },
-            { key: "customer", label: "Customer" },
-            { key: "total", label: "Total" },
-          ]}
-        />
-        <Card.Root>
-          <Card.Header title="Line items" />
-          <Card.Content className="astw:px-0">
-            <Table.Root containerClassName="astw:px-6">
-              <Table.Header>
-                <Table.Row>
-                  <Table.Head>SKU</Table.Head>
-                  <Table.Head align="right">Qty</Table.Head>
-                  <Table.Head align="right">Total</Table.Head>
-                </Table.Row>
-              </Table.Header>
-              <Table.Body>
-                {order.lineItems.map((item) => (
-                  <Table.Row key={item.id}>
-                    <Table.Cell>{item.sku}</Table.Cell>
-                    <Table.Cell align="right">{item.qty}</Table.Cell>
-                    <Table.Cell align="right">${item.total.toLocaleString()}</Table.Cell>
-                  </Table.Row>
-                ))}
-              </Table.Body>
-            </Table.Root>
-          </Card.Content>
-        </Card.Root>
-      </Layout.Column>
-      <Layout.Column area="right">
-        <ActionPanel
-          title="Actions"
-          actions={[
-            { key: "approve", label: "Approve", icon: <span>✓</span>, onClick: onApprove },
-            { key: "cancel", label: "Cancel", icon: <span>✕</span>, onClick: onCancel },
-          ]}
-        />
-        <ActivityCard title="Activity" items={order.activities} />
-      </Layout.Column>
-    </Layout>
-  );
-}
-```
-
-## Constraints
-
-- **Header carries the single primary CTA + the status `Badge`** — not workflow actions. Workflow actions (Approve, Reject, Archive, …) live in the `ActionPanel`. If the header needs more than ~2 actions, move the overflow into a `Menu`.
-- **Never duplicate an action** across `Layout.Header` and `ActionPanel` — each action has exactly one home.
-- Every content section MUST sit inside `Card.Root` (or `DescriptionCard`, which already self-contains). Raw divs are not allowed.
-- `ActionPanel` is workflow-only — never back-navigation (that lives in the breadcrumb).
-- `Table.Root` inside a Card requires `containerClassName="astw:px-6"`.
-
-## Anti-patterns
-
-- No status `Badge` on stateful entities — users can't tell where the record is in its lifecycle.
-- `ActionPanel` mixed with metadata in the same card — keep workflow separate from descriptive fields.
-- Bare `<div>` sections in the main column — every content section MUST sit inside `Card.Root`.
-- `ActionPanel` containing back-navigation (e.g. "Back to Product List") — back navigation lives in `Layout.Header`'s breadcrumb.
-- A `Table.Root` inside a Card without `containerClassName="astw:px-6"` — the first column lands flush against the card edge.
-- The same action in both `Layout.Header` and the `ActionPanel` — duplicating it makes neither read as canonical. Pick one home.
-- Giving every status the same loud weight — the record's primary/lifecycle status is a **filled** semantic badge; secondary statuses (fulfilment, billing) use **`outline-*`** (see `design-system.md` → Composition & emphasis rules).