@tailor-platform/app-shell 1.14.0 → 1.16.0

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

@@ -1,20 +1,11 @@
 ---
-slug: pattern/form/composer
-name: Composer
-category: pattern
-subcategory: form
+title: Composer
 description: Free-text composer — a multi-line input above a trailing action row, for notes, replies, and comments submitted in place
-requiredImports: [Card, Textarea, Button, Checkbox]
-tags: [composer, textarea, note, reply, comment, actions, discard, send]
-do:
-  - A free-text box the user fills and submits in place — add a note, reply on a thread, leave a comment, give a rejection reason
-  - The prose IS the interaction; any other controls only qualify how the text is submitted
-dont:
-  - The text is one field among many on a record form — use form/modal, form/single-page or form/sectioned with a Textarea field
-  - A chat input where Enter sends and there is no Discard — that is a different layout
 ---
 
-# pattern/form/composer
+<!-- GENERATED by docs-kit from docs-src/patterns/form-composer.docs.outline.md — do not edit by hand. -->
+
+# Composer
 
 ## When to Use
 
@@ -60,35 +51,36 @@ Leave it empty and the buttons still sit correctly at the right; `justify-betwee
 
 ## Page Implementation
 
-```tsx
-/* pattern: form/composer */
-import { useState } from "react";
-import { Button, Card, Checkbox, Textarea } from "@tailor-platform/app-shell";
-
-type Props = {
-  onSubmit: (body: string, internal: boolean) => void;
-  submitting?: boolean;
-};
+<example-preview name="form-composer"></example-preview>
 
-export default function Composer({ onSubmit, submitting = false }: Props) {
+```tsx
+function FormComposer() {
   const [body, setBody] = useState("");
   const [internal, setInternal] = useState(false);
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  const handleSubmit = () => {
+    window.alert(`Sending ${internal ? "internal note" : "reply"}: ${body}`);
+    setErrors({});
+    setBody("");
+  };
 
   return (
     <Card.Root>
       <Card.Content>
-        <div className="space-y-3">
-          <Textarea
-            aria-label="Reply"
-            value={body}
-            onChange={(e) => setBody(e.target.value)}
-            placeholder={internal ? "Internal context for teammates…" : "Reply to customer…"}
-            rows={4}
-          />
+        <Form noValidate errors={errors} onFormSubmit={handleSubmit} className="space-y-3">
+          <Field.Root name="body">
+            <Field.Label className="sr-only">Reply</Field.Label>
+            <Textarea
+              required
+              rows={4}
+              value={body}
+              onChange={(event) => setBody(event.target.value)}
+              placeholder={internal ? "Internal context for teammates…" : "Reply to customer…"}
+            />
+            <Field.Error />
+          </Field.Root>
           <div className="flex items-center justify-between gap-2">
-            {/* Options slot — 0..N controls that qualify the submission. An
-                internal-note toggle here; swap for an attachment button, a
-                visibility Select, a template picker, or drop it entirely. */}
             <div className="flex min-w-0 items-center gap-2">
               <Checkbox
                 label="Internal note (not sent to customer)"
@@ -96,39 +88,43 @@ export default function Composer({ onSubmit, submitting = false }: Props) {
                 onCheckedChange={setInternal}
               />
             </div>
-            {/* Action slot — fixed shape: optional ghost Discard, then exactly
-                one primary submit. Never more than one primary. */}
             <div className="flex shrink-0 gap-2">
               <Button
+                type="button"
                 variant="ghost"
-                onClick={() => setBody("")}
-                disabled={body.length === 0 || submitting}
+                onClick={() => {
+                  setBody("");
+                  setErrors({});
+                }}
+                disabled={body.length === 0}
               >
                 Discard
               </Button>
-              <Button
-                onClick={() => onSubmit(body, internal)}
-                disabled={body.trim().length === 0 || submitting}
-              >
-                {submitting ? "Sending…" : "Send"}
+              <Button type="submit" disabled={body.trim().length === 0}>
+                Send
               </Button>
             </div>
           </div>
-        </div>
+        </Form>
       </Card.Content>
     </Card.Root>
   );
 }
 ```
 
+<!-- source: composer.tsx -->
+
 ## Constraints
 
 - The body control is `Textarea`, never `Input` — `Input` is locked to `h-9` and clips prose to one 36px line.
-- Size the body with `rows` (3–5 is the usual range). Don't reach for an `astw:h-*` / `astw:min-h-*` override: `astw:` utilities only resolve if that exact class was compiled into the AppShell package CSS, so an arbitrary one written in a consuming app silently does nothing.
-- The `Textarea` needs an accessible name. There is usually no visible label in a composer, so pass `aria-label`; a placeholder is not a label.
+- Size the body with `rows` (3–5 is the usual range). Do not override its height with classes: `astw:` is internal to AppShell, and `Textarea`'s supported sizing API is `rows`.
+- The `Textarea` needs an accessible name. There is usually no visible label in a composer, so use a `sr-only` `Field.Label`; a placeholder is not a label. Prefer this over `aria-label` — the `Field.Root` is already there, and a real label keeps the error and description wiring available.
 - One primary `Button` in the action row. Discard is `ghost`, and any left-side action is `ghost` too.
 - The action row is one row at every width — the left side shrinks, the buttons do not wrap under the body.
 - Disable the submit on empty or whitespace-only input, and disable both buttons while `submitting`.
+- The composer is a `Form`, not a bare widget. The body sits in a `Field.Root name="…"`, Send is `type="submit"`, and Discard is `type="button"` — inside a `<Form>` an untyped `<button>` defaults to `submit`.
+- Keep the body **controlled**. It is read during render to gate Send and to swap the placeholder, which a submit-time handler cannot do. This is the one `form/*` pattern where field state is load-bearing rather than redundant.
+- Route server rejections (moderation, rate limit, thread closed) through `Form`'s `errors` prop into `Field.Error`, not a toast. A composer that can be rejected needs somewhere for the reason to land next to the text the user still has.
 - Wrap the composer in `Card.Root` when it sits among other cards (a detail page, the end of a thread). A composer that is already inside a `Sheet` or `Dialog` body does not need its own card.
 
 ## Anti-patterns
@@ -139,4 +135,6 @@ export default function Composer({ onSubmit, submitting = false }: Props) {
 - The action row stacked above the `Textarea`, or the buttons wrapped onto their own line — the composer stops reading as one unit.
 - A left-side toggle that silently changes what the submit does without changing the submit's own affordance — if "internal note" changes the destination, the placeholder (or the label) should say so.
 - Submit enabled on an empty body, so the user can post nothing.
+- A bare `<div>` of controls with an `onClick` submit — no `Form`, so a server rejection has nowhere to go and the body has no field identity.
+- Clearing the body on a _failed_ submit — the user loses what they wrote. Clear only after the submit succeeds.
 - A body so tall (`rows={12}`) that the action row falls below the fold — the composer stops reading as one unit.

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

@@ -1,23 +1,11 @@
 ---
-slug: pattern/form/modal
-name: Modal Form
-category: pattern
-subcategory: form
+title: Modal Form
 description: Default form pattern for Create/Edit — keeps user in context on the parent screen
-requiredImports: [Dialog, Button, Form, Field, Layout]
-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
+<!-- GENERATED by docs-kit from docs-src/patterns/form-modal.docs.outline.md — do not edit by hand. -->
+
+# Modal Form
 
 ## When to Use
 
@@ -28,21 +16,10 @@ dont:
 
 ## Page Implementation
 
-```tsx
-/* pattern: form/modal */
-import { Button, Dialog, Field, Form } from "@tailor-platform/app-shell";
-
-type Address = {
-  label: string;
-  street: string;
-  city: string;
-};
-
-type Props = {
-  onSave: (data: Address) => void;
-};
+<example-preview name="modal-form"></example-preview>
 
-export default function ModalForm({ onSave }: Props) {
+```tsx
+function ModalForm() {
   return (
     <Dialog.Root>
       <Dialog.Trigger render={<Button />}>Add address</Dialog.Trigger>
@@ -51,34 +28,32 @@ export default function ModalForm({ onSave }: Props) {
           <Dialog.Title>Add address</Dialog.Title>
           <Dialog.Description>Add a shipping address to this order.</Dialog.Description>
         </Dialog.Header>
-        {/*
-         * `Form` + `onFormSubmit` replaces a hand-rolled `<form onSubmit>` +
-         * `FormData`: values arrive parsed, and validation runs before the
-         * handler fires. Every text field is uncontrolled — no state needed.
-         */}
-        <Form<Address> noValidate onFormSubmit={(values) => onSave(values)}>
-          <div className="space-y-4 py-4">
+        <form
+          onSubmit={(event) => {
+            event.preventDefault();
+            const data = new FormData(event.currentTarget);
+            window.alert(`Saving ${data.get("label") ?? ""}`);
+          }}
+        >
+          <div className="flex flex-col gap-4 py-4">
             <Field.Root name="label">
               <Field.Label>Label</Field.Label>
-              <Field.Control required placeholder="Head office" />
-              <Field.Error match="valueMissing">Label is required.</Field.Error>
+              <Field.Control render={<Input />} />
             </Field.Root>
             <Field.Root name="street">
               <Field.Label>Street</Field.Label>
-              <Field.Control required />
-              <Field.Error match="valueMissing">Street is required.</Field.Error>
+              <Field.Control render={<Input />} />
             </Field.Root>
             <Field.Root name="city">
               <Field.Label>City</Field.Label>
-              <Field.Control required />
-              <Field.Error match="valueMissing">City is required.</Field.Error>
+              <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>
+        </form>
       </Dialog.Content>
     </Dialog.Root>
   );
@@ -87,87 +62,51 @@ export default function ModalForm({ onSave }: Props) {
 
 ## Route-driven Variant
 
-```tsx
-/* pattern: form/modal (route-driven variant) */
-import { useState } from "react";
-import { Button, Dialog, Field, Form, Layout } from "@tailor-platform/app-shell";
-
-type ProductDraft = {
-  name: string;
-};
-
-type Props = {
-  isCreateOpen: boolean;
-  onNavigateToCreate: () => void;
-  onNavigateToList: () => void;
-  onSave: (data: ProductDraft) => Promise<{ errors?: Record<string, string> }>;
-};
-
-/**
- * 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) {
-  // Server-side validation errors, keyed by field `name`. `Form` routes each
-  // one to the matching `Field.Error` and clears it when the user edits that
-  // field — so failures never need their own alert banner.
-  const [errors, setErrors] = useState<Record<string, string>>({});
-
-  const handleSubmit = async (values: ProductDraft) => {
-    const result = await onSave(values);
-    if (result.errors) {
-      setErrors(result.errors);
-      return;
-    }
-    setErrors({});
-    onNavigateToList();
-  };
+The route-driven variant renders the same component at both the parent path and the `create` / `edit` path, with `onOpenChange` navigating back so the URL stays in sync.
 
+<example-preview name="modal-form-routed"></example-preview>
+
+```tsx
+function ModalFormRouted() {
+  const [isCreateOpen, setCreateOpen] = useState(false);
   return (
     <Layout>
       <Layout.Header
         title="Products"
         actions={[
-          <Button key="create" onClick={onNavigateToCreate}>
+          <Button key="create" onClick={() => setCreateOpen(true)}>
             Create
           </Button>,
         ]}
       />
       <Layout.Column>{/* products list — see list/dense-scan */}</Layout.Column>
 
-      <Dialog.Root
-        open={isCreateOpen}
-        onOpenChange={(open) => {
-          if (!open) onNavigateToList();
-        }}
-      >
+      <Dialog.Root open={isCreateOpen} onOpenChange={setCreateOpen}>
         <Dialog.Content>
           <Dialog.Header>
             <Dialog.Title>Create product</Dialog.Title>
           </Dialog.Header>
-          <Form<ProductDraft> noValidate errors={errors} onFormSubmit={handleSubmit}>
-            <div className="space-y-4 py-4">
+          <form
+            onSubmit={(event) => {
+              event.preventDefault();
+              const data = new FormData(event.currentTarget);
+              window.alert(`Saving ${data.get("name") ?? ""}`);
+              setCreateOpen(false);
+            }}
+          >
+            <div className="flex flex-col gap-4 py-4">
               <Field.Root name="name">
                 <Field.Label>Name</Field.Label>
-                <Field.Control required />
-                {/* Catch-all: renders the native message, a `match` message, or
-                    the server error routed in via the `errors` prop above. */}
-                <Field.Error />
+                <Field.Control render={<Input />} />
               </Field.Root>
             </div>
             <Dialog.Footer>
-              <Button type="button" variant="ghost" onClick={onNavigateToList}>
+              <Button variant="ghost" onClick={() => setCreateOpen(false)}>
                 Cancel
               </Button>
               <Button type="submit">Save</Button>
             </Dialog.Footer>
-          </Form>
+          </form>
         </Dialog.Content>
       </Dialog.Root>
     </Layout>

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

@@ -1,21 +1,11 @@
 ---
-slug: pattern/form/sectioned
-name: Sectioned Form
-category: pattern
-subcategory: form
+title: Sectioned Form
 description: Complex form with 15+ fields organized into named fieldset sections
-requiredImports: [Layout, Card, Form, Fieldset, Field, 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
+<!-- GENERATED by docs-kit from docs-src/patterns/form-sectioned.docs.outline.md — do not edit by hand. -->
+
+# Sectioned Form
 
 ## When to Use
 
@@ -24,32 +14,14 @@ dont:
 
 ## Page Implementation
 
-```tsx
-/* pattern: form/sectioned */
-import { Button, Card, Combobox, Field, Fieldset, Form, Layout } from "@tailor-platform/app-shell";
-
-const CURRENCIES = ["USD", "EUR", "GBP", "JPY"];
-
-const WAREHOUSES = [
-  { id: 1, name: "Tokyo DC" },
-  { id: 2, name: "Osaka DC" },
-  { id: 3, name: "Nagoya DC" },
-];
+<example-preview name="form-sectioned"></example-preview>
 
-const SECTIONS = [
-  { id: "identity", title: "Identity", description: "How the product is named and referenced." },
-  { id: "pricing", title: "Pricing", description: "List price and the currency it is quoted in." },
-  { id: "inventory", title: "Inventory", description: "Opening stock and replenishment trigger." },
-];
-
-const anchorIdFor = (id: string) => `section-${id}`;
-
-type Props = {
-  onSave: (data: Record<string, unknown>) => void;
-  onCancel: () => void;
-};
+```tsx
+function FormSectioned() {
+  const onSave = (values: Record<string, unknown>) =>
+    window.alert(`Saving ${Object.keys(values).length} fields`);
+  const onCancel = () => {};
 
-export default function SectionedForm({ onSave, onCancel }: Props) {
   return (
     <Layout>
       <Layout.Header
@@ -163,6 +135,8 @@ export default function SectionedForm({ onSave, onCancel }: Props) {
 }
 ```
 
+<!-- source: sectioned-form.tsx -->
+
 ## Constraints
 
 - Max ~6 sections — more than that is too hard to scan; promote to `form/wizard`

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

@@ -1,21 +1,11 @@
 ---
-slug: pattern/form/single-page
-name: Single Page Form
-category: pattern
-subcategory: form
+title: Single Page Form
 description: Routed full-page form for moderate field count (6-15) without natural sectioning
-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)
-  - 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
+<!-- GENERATED by docs-kit from docs-src/patterns/form-single-page.docs.outline.md — do not edit by hand. -->
+
+# Single Page Form
 
 ## When to Use
 
@@ -24,26 +14,13 @@ dont:
 
 ## Page Implementation
 
-```tsx
-/* pattern: form/single-page */
-import { Button, Field, Form, Textarea, Layout, Select } from "@tailor-platform/app-shell";
-
-const CATEGORIES = ["Electronics", "Furniture", "Clothing", "Food"];
+<example-preview name="form-single-page"></example-preview>
 
-type ProductDraft = {
-  name: string;
-  sku: string;
-  category: string;
-  price: string;
-  description: string;
-};
-
-type Props = {
-  onSave: (data: ProductDraft) => void;
-  onCancel: () => void;
-};
+```tsx
+function FormSinglePage() {
+  const onSave = (values: ProductDraft) => window.alert(`Saving ${values.name}`);
+  const onCancel = () => {};
 
-export default function SinglePageForm({ onSave, onCancel }: Props) {
   return (
     <Layout>
       {/*
@@ -107,6 +84,8 @@ export default function SinglePageForm({ onSave, onCancel }: Props) {
 }
 ```
 
+<!-- source: single-page-form.tsx -->
+
 ## Constraints
 
 - Single column full width below 1024px; single column max-w constrained at 1024–1280px

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

@@ -1,22 +1,11 @@
 ---
-slug: pattern/form/wizard
-name: Wizard Form
-category: pattern
-subcategory: form
+title: Wizard Form
 description: Multi-stage create flow with 3-7 steps and per-step validation gates
-requiredImports: [Layout, Card, Badge, Form, Fieldset, Field, Select, Button]
-tags: [form, wizard, multi-step, stepper, onboarding]
-do:
-  - Multi-stage Create with 3-7 steps
-  - 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
+<!-- GENERATED by docs-kit from docs-src/patterns/form-wizard.docs.outline.md — do not edit by hand. -->
+
+# Wizard Form
 
 ## When to Use
 
@@ -29,45 +18,13 @@ the upload → map → validate → confirm flow. Don't rebuild it here.
 
 ## Page Implementation
 
+<example-preview name="form-wizard"></example-preview>
+
 ```tsx
-/* pattern: form/wizard */
-import { useState } from "react";
-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 INITIAL: Draft = {
-  title: "",
-  description: "",
-  owner: "",
-  startDate: "",
-  estimate: "",
-};
-
-type Props = {
-  onComplete: (draft: Draft) => void;
-  onCancel: () => void;
-};
-
-export default function WizardForm({ onComplete, onCancel }: Props) {
+function FormWizard() {
+  const onComplete = (finalDraft: Draft) => window.alert(`Creating ${finalDraft.title}`);
+  const onCancel = () => {};
+
   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`.
@@ -187,6 +144,8 @@ export default function WizardForm({ onComplete, onCancel }: Props) {
 }
 ```
 
+<!-- source: wizard-form.tsx -->
+
 ## Constraints
 
 - Max 7 steps — more than that causes user abandonment

package/skills/app-shell-patterns/references/patterns/interaction-confirm.md

@@ -1,21 +1,11 @@
 ---
-slug: pattern/interaction/confirm
-name: Confirm
-category: pattern
-subcategory: interaction
+title: Confirm
 description: Confirmation dialog before destructive or irreversible actions
-requiredImports: [Dialog, Button, Input]
-tags: [dialog, confirm, destructive, delete, irreversible]
-do:
-  - Before a destructive or irreversible action (delete, cancel, void, archive)
-  - Before bulk actions that affect many records
-  - When the action's consequence isn't obvious from the trigger
-dont:
-  - Routine reversible actions — use interaction/toast with optional Undo instead
-  - Form submission for non-destructive create/edit — submit handlers don't need a confirm
 ---
 
-# pattern/interaction/confirm
+<!-- GENERATED by docs-kit from docs-src/patterns/interaction-confirm.docs.outline.md — do not edit by hand. -->
+
+# Confirm
 
 ## When to Use
 
@@ -25,31 +15,23 @@ dont:
 
 ## Page Implementation
 
-```tsx
-/* pattern: interaction/confirm */
-import { Button, Dialog } from "@tailor-platform/app-shell";
-
-type Props = {
-  orderId: string;
-  onDelete: () => void;
-};
+<example-preview name="interaction-confirm"></example-preview>
 
-export default function ConfirmDialog({ orderId, onDelete }: Props) {
+```tsx
+function InteractionConfirm() {
   return (
     <Dialog.Root>
       <Dialog.Trigger render={<Button variant="destructive" />}>Delete</Dialog.Trigger>
       <Dialog.Content>
         <Dialog.Header>
-          <Dialog.Title>Delete order {orderId}?</Dialog.Title>
+          <Dialog.Title>Delete order ORD-1024?</Dialog.Title>
           <Dialog.Description>
             This will remove the order and all its line items. This action cannot be undone.
           </Dialog.Description>
         </Dialog.Header>
         <Dialog.Footer>
           <Dialog.Close render={<Button variant="outline" />}>Cancel</Dialog.Close>
-          <Button variant="destructive" onClick={onDelete}>
-            Delete
-          </Button>
+          <Dialog.Close render={<Button variant="destructive" />}>Delete</Dialog.Close>
         </Dialog.Footer>
       </Dialog.Content>
     </Dialog.Root>
@@ -57,6 +39,8 @@ export default function ConfirmDialog({ orderId, onDelete }: Props) {
 }
 ```
 
+<!-- source: confirm.tsx -->
+
 ## Copy Rules
 
 - Title is a question, names the object: "Delete order ORD-1234?", "Cancel invoice INV-001?"