@tailor-platform/app-shell 1.15.0 → 1.17.0

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

@@ -1,35 +1,11 @@
 ---
-slug: pattern/list/dense-scan
-name: Dense Scan List
-category: pattern
-subcategory: list
+title: Dense Scan 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
+<!-- GENERATED by docs-kit from docs-src/patterns/list-dense-scan.docs.outline.md — do not edit by hand. -->
+
+# Dense Scan List
 
 ## When to Use
 
@@ -39,73 +15,22 @@ dont:
 
 ## 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;
-};
-
-// Primary status column — filled semantic variants (one per row).
-// Secondary status columns (e.g. delivery, billing) use outline-* instead.
-const statusVariant = {
-  draft: "neutral",
-  confirmed: "info",
-  shipped: "warning",
-  delivered: "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>,
-  },
-  {
-    // Numeric columns right-align so digits line up. `type: "money" | "number"`
-    // auto-right; with a custom `render` set `align` explicitly.
-    label: "Amount",
-    align: "right",
-    render: (row) => `${row.amount.toLocaleString()}`,
-  },
-  { label: "Created", accessor: (row) => row.createdAt },
-];
-```
+Columns are defined with `createColumnHelper` (see the example below) — each column has a `label` and an `accessor`, or a custom `render` for cells like status badges.
 
 ## Page Implementation
 
-```tsx
-/* pattern: list/dense-scan */
-import { DataTable, Layout, 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;
-};
+<example-preview name="dense-scan"></example-preview>
 
-export default function DenseScanList({ data, onCreateClick }: Props) {
-  const table = useDataTable({ data, columns });
+```tsx
+function DenseScan() {
+  const table = useDataTable({ data: { rows: orders, total: orders.length }, columns });
 
   return (
-    // `fill` pins the page chrome for table-first pages: the title, toolbar,
-    // column header row, and pagination footer stay visible at every viewport
-    // height — only the table's rows region scrolls. Omit `fill` on pages
-    // that should flow and scroll naturally (forms, dashboards, articles).
-    <Layout fill>
+    <Layout>
       <Layout.Header
         title="Orders"
         actions={[
-          <Button key="create" onClick={onCreateClick}>
+          <Button key="create" size="sm">
             Create Order
           </Button>,
         ]}
@@ -142,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
@@ -152,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