@tailor-platform/app-shell 1.2.0 → 1.3.0

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

@@ -0,0 +1,157 @@
+---
+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]
+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.
+
+## 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>Qty</Table.Head>
+                  <Table.Head>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>{item.qty}</Table.Cell>
+                    <Table.Cell>${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
+
+- More than 2 primary actions in the header → move overflow into a `Menu`.
+- 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.
+- `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.

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

@@ -0,0 +1,169 @@
+---
+slug: pattern/form/modal
+name: Modal Form
+category: pattern
+subcategory: form
+description: Default form pattern for Create/Edit — keeps user in context on the parent screen
+requiredImports: [Dialog, Button, Form, Field, Input]
+tags: [form, modal, dialog, create, edit, inline-add]
+do:
+  - Default for most Create and Edit forms — keeps user in context on parent screen
+  - Inline add of a related entity from another screen (add address from order detail)
+  - Quick configuration changes and single-purpose forms (rename, change status)
+  - Any form the design hasn't explicitly called out as a full-page routed screen
+dont:
+  - Design explicitly calls for a full-page (non-overlay) routed Create or Edit
+  - Form is complex with 15+ fields or multiple grouped sections — use form/sectioned
+  - Multi-stage flow with per-step validation — use form/wizard
+---
+
+# pattern/form/modal
+
+## When to Use
+
+- Default for most Create and Edit forms — keeps user in context on parent screen
+- Inline add of a related entity from another screen (add address from order detail)
+- Quick configuration changes and single-purpose forms (rename, change status)
+- Any form the design hasn't explicitly called out as a full-page routed screen
+
+## Page Implementation
+
+```tsx
+/* pattern: form/modal */
+import { Button, Dialog, Input, Field } from "@tailor-platform/app-shell";
+
+type Props = {
+  onSave: (data: { label: string; street: string; city: string }) => void;
+};
+
+export default function ModalForm({ onSave }: Props) {
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger render={<Button />}>Add address</Dialog.Trigger>
+      <Dialog.Content>
+        <Dialog.Header>
+          <Dialog.Title>Add address</Dialog.Title>
+          <Dialog.Description>Add a shipping address to this order.</Dialog.Description>
+        </Dialog.Header>
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            const formData = new FormData(e.currentTarget);
+            onSave({
+              label: formData.get("label") as string,
+              street: formData.get("street") as string,
+              city: formData.get("city") as string,
+            });
+          }}
+        >
+          <div className="space-y-4 py-4">
+            <Field.Root name="label">
+              <Field.Label>Label</Field.Label>
+              <Field.Control render={<Input />} />
+            </Field.Root>
+            <Field.Root name="street">
+              <Field.Label>Street</Field.Label>
+              <Field.Control render={<Input />} />
+            </Field.Root>
+            <Field.Root name="city">
+              <Field.Label>City</Field.Label>
+              <Field.Control render={<Input />} />
+            </Field.Root>
+          </div>
+          <Dialog.Footer>
+            <Dialog.Close render={<Button variant="ghost" />}>Cancel</Dialog.Close>
+            <Button type="submit">Save</Button>
+          </Dialog.Footer>
+        </form>
+      </Dialog.Content>
+    </Dialog.Root>
+  );
+}
+```
+
+## Route-driven Variant
+
+```tsx
+/* pattern: form/modal (route-driven variant) */
+import { Button, Dialog, Input, Layout, Field } from "@tailor-platform/app-shell";
+
+type Props = {
+  isCreateOpen: boolean;
+  onNavigateToCreate: () => void;
+  onNavigateToList: () => void;
+  onSave: (data: { name: string }) => void;
+};
+
+/**
+ * Route-driven modal: the form has its own URL but renders as a popup
+ * over the list. Both `/products` and `/products/create` render this
+ * same component — the parent list stays visible underneath.
+ */
+export default function ModalFormRouted({
+  isCreateOpen,
+  onNavigateToCreate,
+  onNavigateToList,
+  onSave,
+}: Props) {
+  return (
+    <Layout>
+      <Layout.Header
+        title="Products"
+        actions={[
+          <Button key="create" onClick={onNavigateToCreate}>
+            Create
+          </Button>,
+        ]}
+      />
+      <Layout.Column>{/* products list — see list/dense-scan */}</Layout.Column>
+
+      <Dialog.Root
+        open={isCreateOpen}
+        onOpenChange={(open) => {
+          if (!open) onNavigateToList();
+        }}
+      >
+        <Dialog.Content>
+          <Dialog.Header>
+            <Dialog.Title>Create product</Dialog.Title>
+          </Dialog.Header>
+          <form
+            onSubmit={(e) => {
+              e.preventDefault();
+              const formData = new FormData(e.currentTarget);
+              onSave({ name: formData.get("name") as string });
+            }}
+          >
+            <div className="space-y-4 py-4">
+              <Field.Root name="name">
+                <Field.Label>Name</Field.Label>
+                <Field.Control render={<Input />} />
+              </Field.Root>
+            </div>
+            <Dialog.Footer>
+              <Button variant="ghost" onClick={onNavigateToList}>
+                Cancel
+              </Button>
+              <Button type="submit">Save</Button>
+            </Dialog.Footer>
+          </form>
+        </Dialog.Content>
+      </Dialog.Root>
+    </Layout>
+  );
+}
+```
+
+## Constraints
+
+- Dialog renders full-screen sheet below 1024px; centered max-w-md at 1024–1280px
+- Route-driven variant requires both parent path and create/edit path to render the same component
+- `onOpenChange` must navigate back — just calling `setOpen(false)` leaves the URL broken
+
+## Anti-patterns
+
+- Nesting modals — opening a Dialog from inside another Dialog
+- Modal containing a wizard — promote to a routed `form/wizard`
+- Save closes the dialog but parent state is stale — wire refetch or optimistic update
+- Building a routed Create/Edit page when the design didn't explicitly call for one — modal is the default
+- Registering the create path as a separate top-level route — that unmounts the parent list

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

@@ -0,0 +1,126 @@
+---
+slug: pattern/form/sectioned
+name: Sectioned Form
+category: pattern
+subcategory: form
+description: Complex form with 15+ fields organized into named fieldset sections
+requiredImports: [Layout, Form, Fieldset, Field, Input, Select, Combobox, Button]
+tags: [form, sections, fieldset, settings, complex]
+do:
+  - Form is complex with 15+ fields or multiple grouped sections (Identity, Pricing, Inventory)
+  - Configure-style settings pages with named boundaries
+dont:
+  - Simple Create/Edit — use form/modal (the default)
+  - Routed Create/Edit at moderate size with no grouping — use form/single-page
+  - Step-gated validation across stages — use form/wizard
+---
+
+# pattern/form/sectioned
+
+## When to Use
+
+- Form is complex with 15+ fields or multiple grouped sections (Identity, Pricing, Inventory)
+- Configure-style settings pages with named boundaries
+
+## Page Implementation
+
+```tsx
+/* pattern: form/sectioned */
+import { Button, Layout, Input, Select, Field, Fieldset } from "@tailor-platform/app-shell";
+
+type Props = {
+  onSave: (data: Record<string, string>) => void;
+  onCancel: () => void;
+};
+
+export default function SectionedForm({ onSave, onCancel }: Props) {
+  return (
+    <Layout>
+      <Layout.Header
+        title="Product settings"
+        actions={[
+          <Button key="cancel" variant="outline" onClick={onCancel}>
+            Cancel
+          </Button>,
+          <Button key="save" type="submit" form="sectioned-form">
+            Save
+          </Button>,
+        ]}
+      />
+      <Layout.Column>
+        <form
+          id="sectioned-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-8"
+        >
+          <Fieldset.Root>
+            <Fieldset.Legend>Identity</Fieldset.Legend>
+            <div className="space-y-4">
+              <Field.Root name="name">
+                <Field.Label>Name</Field.Label>
+                <Field.Control render={<Input />} />
+              </Field.Root>
+              <Field.Root name="sku">
+                <Field.Label>SKU</Field.Label>
+                <Field.Control render={<Input />} />
+              </Field.Root>
+              <Field.Root name="description">
+                <Field.Label>Description</Field.Label>
+                <Field.Control render={<Input />} />
+              </Field.Root>
+            </div>
+          </Fieldset.Root>
+
+          <Fieldset.Root>
+            <Fieldset.Legend>Pricing</Fieldset.Legend>
+            <div className="space-y-4">
+              <Field.Root name="price">
+                <Field.Label>Price</Field.Label>
+                <Field.Control render={<Input type="number" />} />
+              </Field.Root>
+              <Field.Root name="currency">
+                <Field.Label>Currency</Field.Label>
+                <Select items={["USD", "EUR", "GBP", "JPY"]} placeholder="Select currency" />
+              </Field.Root>
+            </div>
+          </Fieldset.Root>
+
+          <Fieldset.Root>
+            <Fieldset.Legend>Inventory</Fieldset.Legend>
+            <div className="space-y-4">
+              <Field.Root name="quantity">
+                <Field.Label>Initial quantity</Field.Label>
+                <Field.Control render={<Input type="number" />} />
+              </Field.Root>
+              <Field.Root name="reorderPoint">
+                <Field.Label>Reorder point</Field.Label>
+                <Field.Control render={<Input type="number" />} />
+              </Field.Root>
+            </div>
+          </Fieldset.Root>
+        </form>
+      </Layout.Column>
+    </Layout>
+  );
+}
+```
+
+## Constraints
+
+- Max ~6 sections — more than that is too hard to scan; promote to `form/wizard`
+- Required-marker convention must be consistent across all sections
+- Section legends must match anchor-nav labels
+
+## Anti-patterns
+
+- More than ~6 sections — hard to scan; promote to `form/wizard`
+- Required-marker convention varies between sections — pick one rule and apply everywhere
+- Section legends that don't match anchor-nav labels

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

@@ -0,0 +1,105 @@
+---
+slug: pattern/form/single-page
+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, 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)
+  - Moderate field count (roughly 6-15) without natural sectioning, completed in one pass
+dont:
+  - Default Create/Edit with no explicit routing requirement — use form/modal (the default)
+  - 15+ fields or grouped concerns — use form/sectioned
+  - Multi-stage flow — use form/wizard
+---
+
+# pattern/form/single-page
+
+## When to Use
+
+- A routed Create or Edit page that the design has explicitly called out
+- Moderate field count (roughly 6–15) without natural sectioning, completed in one pass
+
+## Page Implementation
+
+```tsx
+/* pattern: form/single-page */
+import { Button, Layout, Input, Select, Field } from "@tailor-platform/app-shell";
+
+type Props = {
+  onSave: (data: Record<string, string>) => void;
+  onCancel: () => void;
+};
+
+export default function SinglePageForm({ onSave, onCancel }: Props) {
+  return (
+    <Layout>
+      <Layout.Header
+        title="Create Product"
+        actions={[
+          <Button key="cancel" variant="outline" onClick={onCancel}>
+            Cancel
+          </Button>,
+          <Button key="save" type="submit" form="single-page-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"
+        >
+          <Field.Root name="name">
+            <Field.Label>Name</Field.Label>
+            <Field.Control render={<Input />} />
+          </Field.Root>
+          <Field.Root name="sku">
+            <Field.Label>SKU</Field.Label>
+            <Field.Control render={<Input />} />
+          </Field.Root>
+          <Field.Root name="category">
+            <Field.Label>Category</Field.Label>
+            <Select
+              items={["Electronics", "Furniture", "Clothing", "Food"]}
+              placeholder="Select category"
+            />
+          </Field.Root>
+          <Field.Root name="price">
+            <Field.Label>Price</Field.Label>
+            <Field.Control render={<Input type="number" />} />
+          </Field.Root>
+          <Field.Root name="description">
+            <Field.Label>Description</Field.Label>
+            <Field.Control render={<Input />} />
+          </Field.Root>
+        </form>
+      </Layout.Column>
+    </Layout>
+  );
+}
+```
+
+## Constraints
+
+- 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
+
+## Anti-patterns
+
+- Two-column layout for unrelated fields — breaks the linear reading order
+- 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`

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

@@ -0,0 +1,134 @@
+---
+slug: pattern/form/wizard
+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]
+do:
+  - Multi-stage Create with 3-7 steps
+  - Import flows (upload → map → validate → confirm)
+  - 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
+---
+
+# pattern/form/wizard
+
+## When to Use
+
+- Multi-stage Create with 3–7 steps
+- Import flows (upload → map → validate → confirm)
+- Per-step validation gates progression
+
+## Page Implementation
+
+```tsx
+/* pattern: form/wizard */
+import { useState } from "react";
+import { Button, Card, Layout, Badge, Input, Field } from "@tailor-platform/app-shell";
+
+const STEPS = ["Upload", "Map", "Review", "Done"] as const;
+
+type Props = {
+  onComplete: () => 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);
+    }
+  };
+
+  return (
+    <Layout>
+      <Layout.Header title="Import products" />
+      <Layout.Column>
+        <Card.Root>
+          <Card.Content>
+            <div className="flex items-center gap-2">
+              {STEPS.map((step, i) => (
+                <Badge
+                  key={step}
+                  variant={i === currentStep ? "default" : i < currentStep ? "success" : "neutral"}
+                >
+                  {i + 1}. {step}
+                </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" />} />
+                </Field.Root>
+              </div>
+            )}
+            {currentStep === 1 && (
+              <div className="space-y-4">
+                <p className="text-fg-muted">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-fg-muted">Review your import — 42 products will be created.</p>
+              </div>
+            )}
+            {currentStep === 3 && (
+              <div className="space-y-4">
+                <p className="text-fg-default">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>
+      </Layout.Column>
+    </Layout>
+  );
+}
+```
+
+## Constraints
+
+- Max 7 steps — more than that causes user abandonment
+- 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
+
+## 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