@tailor-platform/app-shell 1.15.0 → 1.17.0

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?"

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

@@ -1,155 +1,145 @@
 ---
-slug: pattern/interaction/multi-select
-name: Multi Select
-category: pattern
-subcategory: interaction
-description: Floating bottom action bar for bulk operations on selected list rows
-requiredImports: [Table, Checkbox, Button, Menu]
-tags: [bulk, selection, toolbar, floating-bar, multi-select, batch]
-do:
-  - ANY list page where rows can be acted on in bulk (archive, assign, export, approve, delete)
-  - Selection is initiated by clicking a leading-column checkbox on rows
-  - Selection state needs to persist across pagination and filter changes
-dont:
-  - A list where bulk action is genuinely impossible (single-select only)
-  - A pure picker/selector inside a Dialog whose footer already gates the action
-  - Destructive bulk action triggered without confirmation — pair with interaction/confirm
+title: Multi Select
+description: Bulk operations on selected DataTable rows, from a bar that takes over the table footer
 ---
 
-# pattern/interaction/multi-select
+<!-- GENERATED by docs-kit from docs-src/patterns/interaction-multi-select.docs.outline.md — do not edit by hand. -->
+
+# Multi Select
 
 ## When to Use
 
 - ANY list page where rows can be acted on in bulk (archive, assign, export, approve, delete)
-- Selection is initiated by clicking a leading-column checkbox on rows
-- Selection state needs to persist across pagination and filter changes
+- The list is a `DataTable` — selection and the bulk-action bar are built in; you only declare the actions
+- Some actions apply to only part of a selection (approve only pending rows, delete only archived ones)
 
 ## Layout
 
-Floating action bar appears the moment selection count goes from 0 → 1, anchored to the bottom of the viewport, centered horizontally, with elevation. It disappears when selection returns to 0.
+Pass `rowSelection.actions` to `useDataTable`. The moment one row is selected, `DataTable.Footer` becomes the bulk-action bar: a tinted strip with the selection count, the actions, and Clear, with pagination kept on the right. It turns back into the normal footer when the selection empties. In `<Layout fill>` the footer is already pinned; on a page that scrolls, the bar sticks to the bottom of the viewport until the end of the table is reached.
 
 ```
-+---------------------------------------------------------+
-| Layout.Header   title              [Filter] [Create]    |
-+---------------------------------------------------------+
-| Layout.Column                                           |
-|  Table.Root                                             |
-|   [x] | Col   | Col   | Col   | Col                    |
-|   [x] | row   | row   | row   | row                    |
-|   [ ] | row   | row   | row   | row                    |
-|   [x] | row   | row   | row   | row                    |
-|                                                         |
-|        +--------------------------------------+         |
-|        | 3 selected  [Archive] [Export] [⋯] [Clear] |   |
-|        +--------------------------------------+         |
-+---------------------------------------------------------+
++--------------------------------------------------------------------+
+| Layout.Header   title                                  [Create]    |
++--------------------------------------------------------------------+
+| Layout.Column                                                      |
+|  DataTable.Root                                                    |
+|   Toolbar   [Filters]                                  [Columns]   |
+|   [x] | Col   | Col   | Col   | Col                                |
+|   [x] | row   | row   | row   | row                                |
+|   [ ] | row   | row   | row   | row                                |
+|   [x] | row   | row   | row   | row                                |
+|   DataTable.Footer, while rows are selected:                       |
+|   3 of 240 selected | [Confirm] [Export] [⋯] | Clear       ‹ 1/10 › |
++--------------------------------------------------------------------+
 ```
 
 ## Page Implementation
 
-```tsx
-/* pattern: interaction/multi-select */
-import { useState } from "react";
-import { Button, Table, Menu } from "@tailor-platform/app-shell";
-import type { Order } from "./mock";
-
-type Props = {
-  orders: Order[];
-  onArchive: (ids: string[]) => void;
-  onExport: (ids: string[]) => void;
-};
-
-export default function MultiSelect({ orders, onArchive, onExport }: Props) {
-  const [selectedIds, setSelectedIds] = useState<Set<string>>(new Set());
-
-  const toggleRow = (id: string) => {
-    setSelectedIds((prev) => {
-      const next = new Set(prev);
-      if (next.has(id)) next.delete(id);
-      else next.add(id);
-      return next;
-    });
-  };
+<example-preview name="interaction-multi-select"></example-preview>
 
-  const toggleAll = () => {
-    if (selectedIds.size === orders.length) {
-      setSelectedIds(new Set());
-    } else {
-      setSelectedIds(new Set(orders.map((o) => o.id)));
-    }
+```tsx
+function InteractionMultiSelect() {
+  const [selectedIds, setSelectedIds] = useState<string[]>([]);
+  const [pendingCancel, setPendingCancel] = useState<PendingCancel | null>(null);
+  const [cancelling, setCancelling] = useState(false);
+  const [cancelError, setCancelError] = useState<string | null>(null);
+
+  const removeCompletedIds = (ids: string[]) => {
+    const completed = new Set(ids);
+    setSelectedIds((current) => current.filter((id) => !completed.has(id)));
   };
 
-  const clearSelection = () => setSelectedIds(new Set());
-  const selectedCount = selectedIds.size;
+  const actions: SelectionAction[] = [
+    {
+      id: "confirm",
+      label: "Confirm",
+      // The operation returns actual successes; never clear ineligible or newer selections.
+      onClick: async (ids) => removeCompletedIds(await confirmOrders(ids)),
+    },
+    {
+      id: "export",
+      label: "Export",
+      onClick: (ids) => exportOrders(ids),
+    },
+    {
+      id: "assign",
+      label: "Assign owner",
+      onClick: async (ids) => window.alert(`Assigning ${ids.length} order(s)`),
+    },
+    {
+      // 4th action: lands in the More actions menu.
+      id: "cancel",
+      label: "Cancel",
+      variant: "destructive",
+      onClick: (ids, { run }) => {
+        setCancelError(null);
+        setPendingCancel({ ids: [...ids], run });
+      },
+    },
+  ];
+
+  // In a real app, fetch eligibility for these snapshot ids before showing this explanation.
+  const cancellableCount = mockOrders.filter(
+    (order) => pendingCancel?.ids.includes(order.id) && order.status !== "Shipped",
+  ).length;
+
+  const table = useDataTable({
+    columns,
+    data: { rows: mockOrders, total: mockOrders.length },
+    rowSelection: { selectedIds, onChange: setSelectedIds, actions },
+  });
 
   return (
     <>
-      <Table.Root>
-        <Table.Header>
-          <Table.Row>
-            <Table.Head className="w-10">
-              <input
-                type="checkbox"
-                checked={selectedIds.size === orders.length && orders.length > 0}
-                onChange={toggleAll}
-                aria-label="Select all on page"
-              />
-            </Table.Head>
-            <Table.Head>Order #</Table.Head>
-            <Table.Head>Status</Table.Head>
-            <Table.Head>Total</Table.Head>
-          </Table.Row>
-        </Table.Header>
-        <Table.Body>
-          {orders.map((order) => (
-            <Table.Row key={order.id}>
-              <Table.Cell>
-                <input
-                  type="checkbox"
-                  checked={selectedIds.has(order.id)}
-                  onChange={() => toggleRow(order.id)}
-                  aria-label={`Select ${order.number}`}
-                />
-              </Table.Cell>
-              <Table.Cell>{order.number}</Table.Cell>
-              <Table.Cell>{order.status}</Table.Cell>
-              <Table.Cell>${order.total.toLocaleString()}</Table.Cell>
-            </Table.Row>
-          ))}
-        </Table.Body>
-      </Table.Root>
-
-      {selectedCount > 0 && (
-        <div
-          role="toolbar"
-          aria-label="Bulk actions"
-          className="fixed bottom-4 left-1/2 z-30 flex -translate-x-1/2 items-center gap-2 rounded-md border bg-popover px-3 py-2 shadow-lg"
-        >
-          <span className="text-sm font-medium">{selectedCount} selected</span>
-          <Button size="sm" onClick={() => onArchive([...selectedIds])}>
-            Archive
-          </Button>
-          <Button size="sm" variant="outline" onClick={() => onExport([...selectedIds])}>
-            Export
-          </Button>
-          <Menu.Root>
-            <Menu.Trigger>
-              <Button size="sm" variant="outline" aria-label="More actions">
-                ⋯
-              </Button>
-            </Menu.Trigger>
-            <Menu.Content>
-              <Menu.Item>Assign owner</Menu.Item>
-              <Menu.Item>Tag</Menu.Item>
-              <Menu.Separator />
-              <Menu.Item>Delete</Menu.Item>
-            </Menu.Content>
-          </Menu.Root>
-          <Button size="sm" variant="ghost" onClick={clearSelection}>
-            Clear
-          </Button>
-        </div>
-      )}
+      <DataTable.Root value={table}>
+        <DataTable.Table />
+        <DataTable.Footer>
+          <DataTable.Pagination />
+        </DataTable.Footer>
+      </DataTable.Root>
+
+      <Dialog.Root
+        open={pendingCancel !== null}
+        onOpenChange={(open) => {
+          if (!open && !cancelling) setPendingCancel(null);
+        }}
+      >
+        <Dialog.Content>
+          <Dialog.Header>
+            <Dialog.Title>Cancel selected orders?</Dialog.Title>
+            <Dialog.Description>
+              {cancellableCount} of {pendingCancel?.ids.length ?? 0} selected orders can be
+              cancelled; shipped orders are excluded. Cancelled orders can&apos;t be reopened.
+            </Dialog.Description>
+          </Dialog.Header>
+          {cancelError && <p role="alert">{cancelError}</p>}
+          <Dialog.Footer>
+            <Dialog.Close render={<Button variant="outline" disabled={cancelling} />}>
+              Keep orders
+            </Dialog.Close>
+            <Button
+              variant="destructive"
+              disabled={cancelling || cancellableCount === 0}
+              onClick={async () => {
+                if (!pendingCancel || cancelling) return;
+                setCancelling(true);
+                setCancelError(null);
+                try {
+                  const cancelledIds = await pendingCancel.run(cancelOrders(pendingCancel.ids));
+                  removeCompletedIds(cancelledIds);
+                  setPendingCancel(null);
+                } catch {
+                  setCancelError("Cancellation failed. Please try again.");
+                } finally {
+                  setCancelling(false);
+                }
+              }}
+            >
+              {cancelling ? "Cancelling…" : "Cancel orders"}
+            </Button>
+          </Dialog.Footer>
+        </Dialog.Content>
+      </Dialog.Root>
     </>
   );
 }
@@ -157,17 +147,24 @@ export default function MultiSelect({ orders, onArchive, onExport }: Props) {
 
 ## Constraints
 
-- Count label + Clear button are always present in the bar
-- Max 3 inline action buttons — 4th onward collapse behind an overflow `Menu`
-- Destructive bulk actions MUST open an `interaction/confirm` dialog
-- Filter or sort change must NOT silently clear the selection
-- Pagination MUST preserve selection across pages
+- Declare bulk actions as the non-generic `SelectionAction[]` in `useDataTable`'s `rowSelection.actions` — do NOT hand-build the bar, a floating panel, or checkboxes; the footer renders the selection count, actions, overflow menu, and Clear. Providing `rowSelection` enables checkboxes even when `actions` is omitted or empty; the bar requires non-empty actions and selected ids
+- Keep `DataTable.Footer` in the tree — it is where the bar renders
+- Selection stores IDs only, not row objects. `onClick` receives a click-time copy of all selected ids (`string[]`), including unloaded ids; fetch any records required for the operation in the consumer's ID-based workflow
+- The consumer owns eligibility checks, required fetching, confirmation UI, and execution; backend validation remains authoritative. Selection actions have no row-based `canApply`, automatic eligible count, or eligibility-based disabled state
+- Return the promise from `onClick` for async work: the bar disables its actions and shows a spinner while it runs. Success and rejection both leave selection unchanged; there is no `keepSelection` option. Rejections are logged; show errors in the consumer UI
+- Use controlled `rowSelection: { selectedIds, onChange }` to remove only ids actually changed, with a functional update against the current selection. Preserve ineligible ids and ids selected after the operation started; cancellation or failure does not clear selection
+- At most 3 actions render inline, in array order; the 4th onward move to the More actions menu — order by frequency and put a destructive action last
+- Destructive bulk actions MUST open an `interaction/confirm` dialog from `onClick`. Optionally keep the `run` helper and pass it the later request (`await run(deleteRows(ids))`) for pending tracking only. `clearSelection` explicitly clears every page when that is intentional
+- Share only presentation fields (`id`, `label`, `icon`, `variant`) as a non-generic `DataTableAction`. `RowAction<TRow>` retains `canApply` for its concrete row; bulk eligibility belongs in the ID-based consumer workflow
+- Selection persists across pagination, filter, and sort changes — do NOT clear it on those
 
 ## Anti-patterns
 
-- Placing bulk-action buttons in the page header — bulk actions belong only in the floating bar
-- Hiding the bar behind row hover or right-click — bar must be visible when selection > 0
-- Omitting the count or the Clear affordance — both are mandatory
-- Letting filter/sort changes silently drop selection
+- Hand-rolled selection (`useState<Set>`, raw `<input type="checkbox">`, `Table.Root`) when the list is a DataTable
+- A floating or fixed-position action bar over the table instead of the footer bar
+- Placing bulk-action buttons in the page header or the table toolbar
+- Treating the currently loaded rows as the full selection or deriving bulk eligibility from incomplete row data
+- Clearing the whole selection after partial success, or overwriting it with the click-time snapshot and losing newer selections
+- Fire-and-forget async `onClick` that doesn't return its promise or use `run` — users can fire it twice
 - Firing destructive bulk actions without an interaction/confirm step
 - Per-row `Menu` actions as a substitute for bulk actions when selection > 0

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

@@ -1,21 +1,11 @@
 ---
-slug: pattern/interaction/toast
-name: Toast
-category: pattern
-subcategory: interaction
+title: Toast
 description: Lightweight feedback after mutations — success or error notifications
-requiredImports: [Button]
-tags: [toast, feedback, notification, mutation, success, error]
-do:
-  - Feedback after a mutation (create, update, delete) — success or error
-  - Lightweight async signal that doesn't need to block the UI
-  - Confirming work the user just initiated
-dont:
-  - Destructive action that has not yet executed — use interaction/confirm
-  - Long-running blocking operation — use an inline progress UI, not a toast
 ---
 
-# pattern/interaction/toast
+<!-- GENERATED by docs-kit from docs-src/patterns/interaction-toast.docs.outline.md — do not edit by hand. -->
+
+# Toast
 
 ## When to Use
 
@@ -25,31 +15,17 @@ dont:
 
 ## Page Implementation
 
-```tsx
-/* pattern: interaction/toast */
-import { Button, useToast } from "@tailor-platform/app-shell";
-
-type Props = {
-  orderId: string;
-  onApprove: () => Promise<void>;
-};
+<example-preview name="interaction-toast"></example-preview>
 
-export default function ToastExample({ orderId, onApprove }: Props) {
+```tsx
+function InteractionToast() {
   const toast = useToast();
-
-  const handleApprove = async () => {
-    try {
-      await onApprove();
-      toast.success(`Order ${orderId} approved`);
-    } catch {
-      toast.error("Failed to approve order. Try again.");
-    }
-  };
-
-  return <Button onClick={handleApprove}>Approve</Button>;
+  return <Button onClick={() => toast.success("Order ORD-1024 approved")}>Approve</Button>;
 }
 ```
 
+<!-- source: toast-example.tsx -->
+
 ## Copy Rules
 
 - Success: name what happened, including the object identifier. "Order #1234 created", "Product archived".