@tailor-platform/app-shell 1.2.0 → 1.3.0

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

@@ -0,0 +1,75 @@
+---
+slug: pattern/interaction/confirm
+name: Confirm
+category: pattern
+subcategory: interaction
+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
+
+## When to Use
+
+- 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
+
+## Page Implementation
+
+```tsx
+/* pattern: interaction/confirm */
+import { Button, Dialog } from "@tailor-platform/app-shell";
+
+type Props = {
+  orderId: string;
+  onDelete: () => void;
+};
+
+export default function ConfirmDialog({ orderId, onDelete }: Props) {
+  return (
+    <Dialog.Root>
+      <Dialog.Trigger render={<Button variant="destructive" />}>Delete</Dialog.Trigger>
+      <Dialog.Content>
+        <Dialog.Header>
+          <Dialog.Title>Delete order {orderId}?</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.Footer>
+      </Dialog.Content>
+    </Dialog.Root>
+  );
+}
+```
+
+## Copy Rules
+
+- Title is a question, names the object: "Delete order ORD-1234?", "Cancel invoice INV-001?"
+- Body names the object and the consequence: what will change, what will be lost, whether it's reversible
+- Confirm button verb matches the title: "Delete", "Cancel invoice" — never "OK" or "Yes"
+
+## Constraints
+
+- Dialog renders as bottom sheet below 1024px; centered max-w-sm at 1024+
+- Confirm button must use `variant="destructive"` for destructive actions
+
+## Anti-patterns
+
+- Vague titles like "Are you sure?" — gives users nothing to evaluate
+- Cancel rendered as the primary visual treatment — promotes the wrong default
+- Confirm button without `variant="destructive"` for destructive actions — no visual signal

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

@@ -0,0 +1,173 @@
+---
+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
+---
+
+# pattern/interaction/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
+
+## 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.
+
+```
++---------------------------------------------------------+
+| 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] |   |
+|        +--------------------------------------+         |
++---------------------------------------------------------+
+```
+
+## 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;
+    });
+  };
+
+  const toggleAll = () => {
+    if (selectedIds.size === orders.length) {
+      setSelectedIds(new Set());
+    } else {
+      setSelectedIds(new Set(orders.map((o) => o.id)));
+    }
+  };
+
+  const clearSelection = () => setSelectedIds(new Set());
+  const selectedCount = selectedIds.size;
+
+  return (
+    <>
+      <Table.Root>
+        <Table.Header>
+          <Table.Row>
+            <Table.Head className="astw: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-surface-2 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>
+      )}
+    </>
+  );
+}
+```
+
+## 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
+
+## 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
+- 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

@@ -0,0 +1,69 @@
+---
+slug: pattern/interaction/toast
+name: Toast
+category: pattern
+subcategory: interaction
+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
+
+## When to Use
+
+- 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
+
+## Page Implementation
+
+```tsx
+/* pattern: interaction/toast */
+import { Button, useToast } from "@tailor-platform/app-shell";
+
+type Props = {
+  orderId: string;
+  onApprove: () => Promise<void>;
+};
+
+export default function ToastExample({ orderId, onApprove }: Props) {
+  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>;
+}
+```
+
+## Copy Rules
+
+- Success: name what happened, including the object identifier. "Order #1234 created", "Product archived".
+- Error: state what failed and why. "Failed to save: SKU already exists", "Couldn't archive product: network error".
+- Avoid generic messages like "Success" or "Something went wrong".
+
+## Constraints
+
+- Toast renders as a top-right overlay; mobile (<1024) anchors to bottom-center
+- Stack max one visible at a time; replace prior toast on new emission
+- Success auto-dismisses after 3s; Error is sticky (no auto-dismiss)
+
+## Anti-patterns
+
+- Toast on every navigation — creates noise; reserve for mutation feedback
+- More than one toast stacking — replace, don't accumulate
+- Blocking the UI on a toast — toasts are non-modal by definition

package/skills/app-shell-patterns/references/patterns/list-dense-scan.md

@@ -0,0 +1,132 @@
+---
+slug: pattern/list/dense-scan
+name: Dense Scan List
+category: pattern
+subcategory: list
+description: High-density scannable list backed by GraphQL connections with DataTable, sort, filters, and pagination
+requiredImports:
+  [
+    DataTable,
+    useDataTable,
+    useCollectionVariables,
+    createColumnHelper,
+    Layout,
+    Card,
+    Button,
+    Badge,
+    Link,
+    Menu,
+    Tabs,
+  ]
+tags: [table, bulk-action, filter, pagination, datatable, connection]
+do:
+  - Browsing many records of one entity type (orders, POs, products) with GraphQL pagination
+  - Operators sort, filter, and select rows; row click navigates to detail
+  - Optionally a bucket control (Tabs) aligned to one categorical dimension (status, type)
+dont:
+  - Side-by-side match/reconcile views comparing two grids
+  - A tiny/static list where DataTable would be heavyweight — use Table.Root manually
+  - Inline editable cells — use pattern/detail or pattern/form/modal instead
+---
+
+# pattern/list/dense-scan
+
+## When to Use
+
+- Browsing many records of one entity type (orders, POs, products, invoices) with GraphQL pagination
+- Operators sort, filter, and select rows; row click navigates to detail
+- Optionally: a bucket control (`Tabs`, segmented buttons) aligned to one categorical dimension the business cares about (status, fulfillment stage, type)
+
+## Column Definition
+
+```tsx
+import type { Column } from "@tailor-platform/app-shell";
+import { Badge } from "@tailor-platform/app-shell";
+
+export type Order = {
+  id: string;
+  orderNumber: string;
+  customer: string;
+  status: "draft" | "confirmed" | "shipped" | "delivered";
+  amount: number;
+  createdAt: string;
+};
+
+const statusVariant = {
+  draft: "neutral",
+  confirmed: "outline-info",
+  shipped: "outline-warning",
+  delivered: "outline-success",
+} as const;
+
+export const columns: Column<Order>[] = [
+  { label: "Order #", accessor: (row) => row.orderNumber },
+  { label: "Customer", accessor: (row) => row.customer },
+  {
+    label: "Status",
+    render: (row) => <Badge variant={statusVariant[row.status]}>{row.status}</Badge>,
+  },
+  {
+    label: "Amount",
+    render: (row) => `${row.amount.toLocaleString()}`,
+  },
+  { label: "Created", accessor: (row) => row.createdAt },
+];
+```
+
+## Page Implementation
+
+```tsx
+/* pattern: list/dense-scan */
+import { DataTable, useDataTable, Button, Input } from "@tailor-platform/app-shell";
+import type { Order } from "./columns";
+import { columns } from "./columns";
+import type { DataTableData } from "@tailor-platform/app-shell";
+
+type Props = {
+  data: DataTableData<Order>;
+  onCreateClick: () => void;
+};
+
+export default function DenseScanList({ data, onCreateClick }: Props) {
+  const table = useDataTable({ data, columns });
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between">
+        <Input placeholder="Search orders..." className="max-w-sm" />
+        <Button onClick={onCreateClick}>Create Order</Button>
+      </div>
+      <DataTable.Root value={table}>
+        <DataTable.Table />
+      </DataTable.Root>
+    </div>
+  );
+}
+```
+
+## Variants
+
+- **Toolbar chips only (`DataTable.Filters`)** — best when filters map cleanly to typed column metadata / enum facets
+- **Tabs only above `DataTable`** — best when workflows are organized as obvious buckets
+- **Tabs + chips** — when buckets are primary and finer filters help
+- **Bulk selection** — `onSelectionChange` hook on `useDataTable`; combine with `interaction/multi-select`
+- **`Table` primitives** — small static lists without collection hooks
+
+## Constraints
+
+- Column count: 4-8 recommended
+- Must include pagination — never render unbounded lists
+- Status Badge colors must use design system tokens (variant prop)
+- Bulk actions toolbar appears only when ≥1 row is selected
+- Whole row is clickable via `onClickRow`; no per-row "View" / "Open" buttons
+- Per-row `Menu` (overflow `…`) is reserved for non-navigation actions (Archive, Duplicate, Delete)
+
+## Anti-patterns
+
+- Building a bespoke table + custom pagination instead of `DataTable` + `useCollectionVariables`
+- Tabs that mutate only local UI state while pagination/filters assume the full server set
+- Using `<table>` directly instead of `<DataTable>` for live collections
+- Client-side filtering on 1000+ records without server-side support
+- Inline editable cells — use `pattern/detail/*` or `pattern/form/modal` instead
+- Per-row "View" / "Open" buttons duplicating the row-click navigation