@tailor-platform/app-shell 1.16.0 → 1.17.0

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

@@ -1,6 +1,6 @@
 ---
 title: Multi Select
-description: Floating bottom action bar for bulk operations on selected list rows
+description: Bulk operations on selected DataTable rows, from a bar that takes over the table footer
 ---
 
 <!-- GENERATED by docs-kit from docs-src/patterns/interaction-multi-select.docs.outline.md — do not edit by hand. -->
@@ -10,28 +10,27 @@ description: Floating bottom action bar for bulk operations on selected list row
 ## 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
@@ -40,120 +39,132 @@ Floating action bar appears the moment selection count goes from 0 → 1, anchor
 
 ```tsx
 function InteractionMultiSelect() {
-  const orders = mockOrders;
-  const onArchive = (ids: string[]) => window.alert(`Archiving ${ids.length}`);
-  const onExport = (ids: string[]) => window.alert(`Exporting ${ids.length}`);
-
-  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 [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 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;
+  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>
     </>
   );
 }
 ```
 
-<!-- source: multi-select.tsx -->
-
 ## 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/list-dense-scan.md

@@ -67,7 +67,7 @@ Omit `fill` on pages that should flow and scroll naturally (forms, dashboards, a
 - **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`
+- **Bulk actions** — `rowSelection.actions` on `useDataTable` turns `DataTable.Footer` into a bulk-action bar while rows are selected; see `interaction/multi-select`
 - **`Table` primitives** — small static lists without collection hooks
 
 ## Constraints
@@ -77,7 +77,7 @@ Omit `fill` on pages that should flow and scroll naturally (forms, dashboards, a
 - Table-first pages use `<Layout fill>` so title/toolbar/header/footer stay pinned and only rows scroll
 - Handle every state: `DataTable` renders the loading skeleton and error row; always provide a **labelled empty state** (what the list is + how to add the first record) rather than a bare empty table
 - Status Badge colors must use design system tokens (variant prop): the **primary** status column uses **filled** semantic variants; **secondary** status columns (delivery, billing) use **`outline-*`** (see `design-system.md` → Composition & emphasis rules)
-- Bulk actions toolbar appears only when ≥1 row is selected
+- Bulk actions go in the footer bar from `rowSelection.actions`, which appears only while ≥1 row is selected — never a separate toolbar or floating bar
 - Whole row is clickable via `onClickRow`; wrap the primary identifier cell in `<Link>` for keyboard/SR access. No per-row "View" / "Open" buttons
 - Per-row `Menu` (overflow `…`) is reserved for non-navigation actions (Archive, Duplicate, Delete)
 - Wide lists (many columns / horizontal scroll): pin the column users scan by to the **left** — the record's identifier (invoice / order **reference**) or its **name** (customer, product) — so it stays anchored while the rest scrolls; optionally pin a single high-signal **status** or **total** to the **right**. Keep the pinned set small (≈1 left, at most 1 right) — over-pinning eats the scroll area. Let users override via `<DataTable.Toolbar columnSettings>` (show/hide + reorder + re-pin) with a stable `tableId` so each user's layout persists