@spark-web/design-system 5.1.4 → 5.1.5

package/patterns/vendor-admin/list-page.md

@@ -0,0 +1,709 @@
+# Vendor admin — list page pattern
+
+## Before using this pattern
+
+Read `node_modules/@spark-web/design-system/patterns/vendor-admin/CLAUDE.md`
+fully before implementing this pattern. The layout shell / content region, the
+`Heading level="2"` page-title rule, the side-panel-vs-full-page rule, the
+infinite-scroll-vs-pagination rule, the bulk-action toast rule, and the badge
+tone mapping defined there all apply to this pattern and take precedence over
+anything below.
+
+Working in vendor-portal? Apply the substitutions in
+`node_modules/@spark-web/design-system/patterns/vendor-admin/vendor-portal.md`.
+
+## What this pattern is
+
+A full page for displaying a searchable, filterable list of records on the
+vendor-admin surface — leads, applications, referrals, and similar — rendered
+inside the vendor-admin shell (fixed Header + left NavBar). It supports two
+record-detail interactions (a slide-in side panel or, where the surface rules
+permit, a full page) and two list-loading strategies (infinite scroll or
+pagination). This is the most common page type on the vendor-admin surface.
+
+## When to use this pattern
+
+Use this pattern when the PRD describes any of the following:
+
+- A list of records a vendor / installer / partner can search, filter, or sort
+- A management interface where records can be viewed, assigned, exported, or
+  bulk-acted upon
+- The words "list", "manage", "view all", "leads", "applications", "referrals",
+  "records", or "results"
+
+---
+
+## Component docs to read
+
+Read these before implementing — they own the component-level rules:
+
+- `node_modules/@spark-web/heading/CLAUDE.md` — Heading API, `level` values
+- `node_modules/@spark-web/badge/CLAUDE.md` — status / count tone mapping
+- `node_modules/@spark-web/button/CLAUDE.md` — action Button (Export) API,
+  `loading`, prominence/tone
+- `node_modules/@spark-web/icon/CLAUDE.md` — icon sizing and tones (SearchIcon,
+  action icons)
+- `node_modules/@spark-web/field/CLAUDE.md` — Field API, `labelVisibility`,
+  `disabled` context (DatePicker reads it)
+- `node_modules/@spark-web/date-picker/CLAUDE.md` — DatePicker API; **must be
+  wrapped in a Field** (it reads `disabled` from Field context)
+- `node_modules/@spark-web/multi-select/CLAUDE.md` — MultiSelect filter
+  dropdowns; grouped `options` shape
+- `node_modules/@spark-web/a11y/CLAUDE.md` — VisuallyHidden (accessible labels)
+- `node_modules/@spark-web/text-input/CLAUDE.md` — TextInput + InputAdornment
+  search field
+- `node_modules/@spark-web/data-table/CLAUDE.md` — DataTable API,
+  `createColumnHelper`, `isLoading`, `emptyState`, row click
+- `node_modules/@spark-web/stack/CLAUDE.md` — vertical stacking and gap
+- `node_modules/@spark-web/box/CLAUDE.md` — flex layout utilities
+- `node_modules/@spark-web/columns/CLAUDE.md` — responsive multi-column layout
+- `node_modules/@spark-web/text/CLAUDE.md` — Text API
+- `node_modules/@spark-web/alert/CLAUDE.md` — page-level feedback Alert
+- `node_modules/@spark-web/checkbox/CLAUDE.md` — row-select Checkbox
+  (multi-select lists only)
+- `node_modules/@spark-web/modal-dialog/CLAUDE.md` — export / assign modals
+
+---
+
+## Page structure
+
+```
+Page (renders into the vendor-admin shell content region — no Header/NavBar here)
+  Page Stack                     — gap="large", margin="xxlarge" marginBottom="none", height="full", overflow hidden
+    Alert (conditional)          — page-level success/error feedback; omit if no page-level actions
+    Title row (Box flex)         — Heading level="2" + optional count Badge (left); right-aligned action Button(s)
+    Filter bar (Columns)         — date-range (Field+DatePicker ×2), multi-select filter, search TextInput — REQUIRED if filtering exists
+    Scroll region (Stack)        — position relative, height full, overflow hidden — the side-panel/toast anchor
+      Scroll wrapper (Stack)     — overflowY scroll — scrolls the table, not the page
+        DataTable                — items/columns via createColumnHelper, isLoading, emptyState
+      SidePanel (conditional)    — slide-in detail (COMPONENT GAP — primitives placeholder) — single selected record only
+      BulkActionToast (cond.)    — bottom-anchored bulk actions (COMPONENT GAP — primitives placeholder) — multi-select, ≥1 row selected
+    Pagination (conditional)     — only when paginated (COMPONENT GAP — primitives placeholder); omit when infinite-scroll
+    Modals (export / assign)     — declared in JSX, open via state
+```
+
+---
+
+## Section 1 — Page Stack (outer wrapper)
+
+The page body is a single `Stack` that fills the shell content region and owns
+the page rhythm. Per the surface rules' spacing rule, list pages use
+`gap="large"` with `margin="xxlarge" marginBottom="none"` so the scroll region
+reaches the viewport edge, `height="full"`, and clip overflow so the inner
+scroll region — not the page — scrolls.
+
+```tsx
+<Stack
+  gap="large"
+  margin="xxlarge"
+  marginBottom="none"
+  height="full"
+  overflow="hidden"
+>
+```
+
+Rules:
+
+- This is a plain `Stack` — **never** `PageHeader` and **never** `Container`.
+  Container is reserved for centered form / settings pages (see form-page.md).
+- All spacing comes from tokens (`gap`, `margin`) — no raw pixel margins.
+
+---
+
+## Section 2 — Page-level feedback (conditional)
+
+When a page-level action (CSV export, bulk assign / close) can produce success
+or error feedback, render an `<Alert>` as the first child of the page Stack,
+above the title row. Only rendered when feedback state exists.
+
+```tsx
+import { Alert } from '@spark-web/alert';
+
+{
+  successMessage && (
+    <Alert tone="positive" closeLabel="Close" onClose={clearSuccess}>
+      {successMessage}
+    </Alert>
+  );
+}
+```
+
+Rules:
+
+- `tone="positive"` for success, `tone="critical"` for failure.
+- An `Alert` with `onClose` requires `closeLabel` (discriminated union — see the
+  Alert doc).
+- Feedback state is local component state, reset on filter change or navigation.
+- If the page has no page-level actions, omit this section entirely.
+
+---
+
+## Section 3 — Title row
+
+A flex row: the page title `Heading level="2"` (with an optional count / limit
+`Badge` beside it) on the left, and right-aligned page-level action Button(s).
+Per the surface rules, vendor-admin uses `Heading level="2"` for the page title
+— **never** `PageHeader` and **never** `level="1"`.
+
+```tsx
+<Box
+  display="flex"
+  justifyContent="spaceBetween"
+  alignItems="center"
+  flexDirection={{ mobile: 'column', tablet: 'row' }}
+>
+  <Box display="flex" alignItems="center" gap="medium">
+    <Heading level="2">{pageTitle}</Heading>
+    {countShown && <Badge tone="info">{`${count} results`}</Badge>}
+  </Box>
+
+  <Box
+    gap="medium"
+    display="flex"
+    marginTop={{ mobile: 'medium', tablet: 'none' }}
+  >
+    <Button
+      onClick={onExport}
+      loading={isExporting}
+      prominence="none"
+      tone="neutral"
+    >
+      Export all as CSV
+      <ArrowCircleRightIcon />
+    </Button>
+  </Box>
+</Box>
+```
+
+Rules:
+
+- The title is always `Heading level="2"`. Sub-section titles step to
+  `level="3"`.
+- Page-level actions (Export, etc.) are right-aligned in their own `Box` — never
+  in the content/scroll area. Use the Button `loading` prop for in-flight state;
+  do not hand-roll a "Exporting… %" label unless the consumer's export hook
+  exposes progress (overlay concern).
+- An optional count / limit indicator is a `Badge` on the left, beside the
+  title. Use a tone from the surface badge tone mapping (typically `info` for a
+  neutral count; `caution` when approaching a limit).
+- If the page has no page-level actions, render the title row with the heading
+  only.
+
+---
+
+## Section 4 — Filter bar
+
+Renders the date-range pickers, the multi-select filter, and the search input in
+a horizontal row that collapses on small screens. Per the surface rules, filter
+rows use `gap="medium"`.
+
+```tsx
+<Columns gap="medium" collapseBelow="tablet">
+  {/* Date range — always first: From then To */}
+  <Field label="From" labelVisibility="hidden">
+    <DatePicker value={startDate} onChange={setStartDate} />
+  </Field>
+  <Field label="To" labelVisibility="hidden">
+    <DatePicker value={endDate} onChange={setEndDate} />
+  </Field>
+
+  {/* Multi-select filter */}
+  <Box>
+    <VisuallyHidden as="span" id="list-filter-label">
+      Filters
+    </VisuallyHidden>
+    <MultiSelect
+      aria-labelledby="list-filter-label"
+      options={filterOptions}
+      placeholder="Filter by..."
+      onChange={setFilters}
+    />
+  </Box>
+
+  {/* Search — always last */}
+  <Field label="Search" labelVisibility="hidden">
+    <TextInput
+      type="search"
+      inputMode="search"
+      placeholder="Search"
+      value={search}
+      onChange={e => setSearch(e.target.value)}
+    >
+      <InputAdornment placement="start">
+        <SearchIcon size="xxsmall" tone="muted" />
+      </InputAdornment>
+    </TextInput>
+  </Field>
+</Columns>
+```
+
+Ordering (fixed): **date-range (From, then To) first → multi-select filter →
+search last.** This is the observed vendor-admin order (date range leads, search
+trails) and differs from internal-admin (where search is leftmost). Hold this
+order.
+
+Rules:
+
+- **Date range** is two `Field` + `DatePicker` pairs, labels `"From"` / `"To"`
+  with `labelVisibility="hidden"`. `DatePicker` **must** be wrapped in a `Field`
+  — it reads `disabled` from Field context and has no standalone label. See the
+  date-picker doc.
+- **Multi-select filter** uses `MultiSelect` from `@spark-web/multi-select`. Its
+  `options` are grouped — `Array<{ label, options }>` — which suits the
+  vendor-admin multi-facet filter (e.g. Assigned To / Intent / Status /
+  Financial Product groups in one control). For a single flat facet pass
+  `[{ label: '', options }]`. It renders no visible label, so label it for
+  assistive tech via `aria-labelledby` pointing at a `VisuallyHidden` element
+  from `@spark-web/a11y`. (vendor-portal substitutes a local
+  `MultiselectCheckbox` with the same grouped `options` / `onChange` shape —
+  COMPONENT GAP is not implied; the Spark component exists. See the overlay.)
+  Filter state is typed `SelectedOptions` — an object keyed by group label →
+  `string[]` — **not** `string[]`; do not declare `useState<string[]>` (see
+  `node_modules/@spark-web/multi-select/CLAUDE.md`).
+- **Search** is a `TextInput` (`type="search"`) wrapped in a `Field`
+  (`label="Search"`, hidden), with a leading `InputAdornment` holding a
+  `SearchIcon size="xxsmall" tone="muted"`.
+- Filter labels are never visible — wrap inputs in a `Field` with
+  `labelVisibility="hidden"`; the `label` is still required for accessibility,
+  and `aria-labelledby` + `VisuallyHidden` for `MultiSelect`.
+- If no filtering or searching is needed, omit this section entirely.
+
+---
+
+## Section 5 — Scroll region and table
+
+The scroll region is the **anchor** for the side panel and the bulk-action toast
+(both are `position: absolute` within it — see Sections 6 and 7). It is a
+`Stack` that is `position="relative"`, `height="full"`, and clips overflow; an
+inner `Stack` scrolls the table vertically.
+
+```tsx
+<Stack position="relative" height="full" overflow="hidden">
+  <Stack width="full" css={{ overflowY: 'scroll' }}>
+    <DataTable
+      items={rows}
+      columns={columns}
+      isLoading={isLoading}
+      emptyState={
+        <Text tone="muted" size="small">
+          No records found. Try adjusting your filters.
+        </Text>
+      }
+    />
+  </Stack>
+
+  {/* Section 6 — SidePanel (conditional) */}
+  {/* Section 7 — BulkActionToast (conditional) */}
+</Stack>
+```
+
+`position` / `height` / `overflow` here are **Spark Stack props** (Box props
+forwarded through Stack) — not raw CSS. Only `overflowY: 'scroll'` on the inner
+Stack is a documented exception (no Spark prop for axis-specific overflow).
+
+### Table (DataTable)
+
+Always uses `@spark-web/data-table`. The **current** API is a single `DataTable`
+that takes `items` + `columns` (built with `createColumnHelper`), `isLoading`,
+and `emptyState`. (vendor-portal pins an older `data-table` whose columns are a
+raw `ColumnDef[]` array; **document and build the current API**, not the pinned
+one.)
+
+```tsx
+import { createColumnHelper, DataTable } from '@spark-web/data-table';
+
+const columnHelper = createColumnHelper<RecordRow>();
+
+const columns = [
+  columnHelper.accessor('name', { header: 'Name' }),
+  columnHelper.accessor('received', { header: 'Received' }),
+  columnHelper.accessor('status', {
+    header: 'Status',
+    cell: ({ getValue }) => (
+      <Badge tone={toneFor(getValue())}>{labelFor(getValue())}</Badge>
+    ),
+  }),
+];
+```
+
+Column rules:
+
+- The **status column** is always a `<Badge>` (dot + label), tone mapped via the
+  surface badge tone mapping (read it in the vendor-admin / internal-admin rules
+  — do not re-derive; never `tone="pending"`, use `info`). Never plain text,
+  never `StatusBadge` in a table.
+- Default column width: equal flex distribution (`size` unset). Only hardcode a
+  width for a fixed-width utility column (e.g. a row-select checkbox or icon).
+- **Row-select checkbox column** (multi-select lists only): a leading column
+  whose cell renders `@spark-web/checkbox` `Checkbox` wired to the row's
+  selection handlers; stop click propagation so selecting a row does not also
+  open its detail panel.
+- **Loading / empty:** pass `isLoading` and `emptyState` to `DataTable` — never
+  render an external spinner or "no results" text outside the table.
+- **Row click → detail:** when a record has a detail view, open it via the side
+  panel (Section 6), wiring `onRowClick` (and `enableClickableRow`) per the
+  data-table doc and the surface row-interaction rules.
+
+---
+
+## Section 6 — Side-panel detail variant (conditional)
+
+Per the surface "Detail interaction rule", vendor-admin opens a record's detail
+in a **slide-in side panel** anchored to the scroll region — not a navigate-to
+detail page. Render the panel as a sibling of the scroll wrapper, inside the
+`position="relative"` scroll region.
+
+```tsx
+{
+  /* COMPONENT GAP: SidePanel/Drawer needed — not yet in Spark — see Section 6
+     rules for the protocol and prop contract. */
+}
+{
+  selectedRecordId && selectedRows.length <= 1 && (
+    <Box
+      position="absolute"
+      top={0}
+      bottom={0}
+      right={0}
+      background="surface"
+      shadow="large"
+      css={{
+        width: '90vw',
+        overflowY: 'auto',
+        ['@media (min-width: 768px)']: { maxWidth: '500px' },
+      }}
+    >
+      <Stack gap="large" padding="large">
+        <Box display="flex" justifyContent="spaceBetween" alignItems="center">
+          <Heading level="3">{panelHeading}</Heading>
+          <Button prominence="none" tone="neutral" onClick={closePanel}>
+            Close
+          </Button>
+        </Box>
+        {/* record detail body */}
+      </Stack>
+    </Box>
+  );
+}
+```
+
+Rules:
+
+- **Side panel is a COMPONENT GAP** — there is no `@spark-web` drawer / side
+  panel (verification note: see the overlay). **COMPONENT GAP protocol** (this
+  applies to every gap in this file): build the placeholder from primitives,
+  mark the first use with a `// COMPONENT GAP: <Name> needed — not yet in Spark`
+  comment, and flag it for **product design review before production — the
+  placeholder is a stop-gap; do not ship as-is**. Prop contract: `heading`
+  (string), `onHide` (`() => void`, wired to the close Button), record body as
+  children. (In vendor-portal, apply the overlay's `SidePanel` — see the overlay
+  for its props.)
+- **When to use a panel vs a full page** (surface rule): use the panel for
+  inspecting / lightly acting on a single record while staying in the list;
+  reserve a full page for heavyweight standalone flows (multi-step forms,
+  settings). Settings is a full page (`Container`-centered), not a panel.
+- Open the panel by setting the selected record — typically via a URL query
+  param so the panel is deep-linkable — and render it **only when a single
+  record is selected** (`selectedRows.length <= 1`). It overlays the list rather
+  than reflowing it.
+
+---
+
+## Section 7 — Bulk-action toast (conditional)
+
+Per the surface "Bulk actions rule", when the list is multi-select and at least
+one row is selected, a **bottom-anchored bulk-action toast** appears, pinned to
+the scroll region. It exposes the actions for the current selection (e.g.
+assign, close) and a way to clear the selection.
+
+```tsx
+{
+  /* COMPONENT GAP: BulkActionToast needed — not yet in Spark — protocol: see
+     Section 6. Prop contract: count (selected rows), disabled (in-flight),
+     onClose (clear selection), onActionSubmit (run the bulk action). */
+}
+{
+  isMultiSelect && selectedRows.length > 0 && (
+    <Box
+      position="absolute"
+      bottom={0}
+      left={0}
+      right={0}
+      background="surface"
+      shadow="large"
+      padding="medium"
+      display="flex"
+      alignItems="center"
+      justifyContent="spaceBetween"
+    >
+      <Text>{`${selectedRows.length} selected`}</Text>
+      <Box display="flex" gap="medium" alignItems="center">
+        <Button
+          prominence="high"
+          tone="primary"
+          disabled={isBulkMutationRunning}
+          onClick={runBulkAction}
+        >
+          Assign
+        </Button>
+        <Button prominence="none" tone="neutral" onClick={clearSelection}>
+          Clear
+        </Button>
+      </Box>
+    </Box>
+  );
+}
+```
+
+Rules:
+
+- Rendered **only when** the list is multi-select **and**
+  `selectedRows.length > 0`; hidden when the selection is empty.
+- Mutually exclusive with the side panel (Section 6) — show the panel only for a
+  single selected record, the toast only for a multi-row bulk selection.
+- Disable the toast's actions while a bulk mutation is in flight (`disabled`).
+- The toast container is a COMPONENT GAP — build the placeholder above from
+  primitives (`Box` anchored absolutely to the scroll region per the surface
+  rule, with a count `Text` + action/clear `Button`s) and mark the first use
+  with `// COMPONENT GAP: BulkActionToast needed — not yet in Spark` (protocol:
+  see Section 6). (In vendor-portal, apply the overlay's component.)
+
+---
+
+## Section 8 — Pagination (conditional, paginated lists only)
+
+Per the surface "List loading rule", choose **infinite scroll** for large /
+streamed / open-ended lists (fetch the next page when the scroll bottom is
+reached and append rows — no pagination control) and **pagination** for bounded,
+countable lists.
+
+For paginated lists, render `TablePagination` **outside and below the scroll
+region** — never nested inside DataTable.
+
+```tsx
+{
+  /* COMPONENT GAP: TablePagination needed — not yet in Spark — protocol: see
+     Section 6. Prop contract: total, pageSize, current (page), dataShowing
+     (rows on this page), onChange (next page). */
+}
+{
+  total > PAGE_SIZE && (
+    <Box
+      display="flex"
+      alignItems="center"
+      justifyContent="spaceBetween"
+      paddingY="medium"
+    >
+      <Text tone="muted" size="small">
+        {`Showing ${dataShowing} of ${total}`}
+      </Text>
+      <Box display="flex" gap="medium" alignItems="center">
+        <Button
+          prominence="low"
+          tone="neutral"
+          disabled={current <= 1}
+          onClick={() => onChange(current - 1)}
+        >
+          Previous
+        </Button>
+        <Button
+          prominence="low"
+          tone="neutral"
+          disabled={current * pageSize >= total}
+          onClick={() => onChange(current + 1)}
+        >
+          Next
+        </Button>
+      </Box>
+    </Box>
+  );
+}
+```
+
+Rules:
+
+- **Pagination is a COMPONENT GAP** — there is no `@spark-web` pagination
+  component. Build the placeholder above from primitives (Box/Text/Button) and
+  mark the first use with
+  `// COMPONENT GAP: TablePagination needed — not yet in Spark` (protocol: see
+  Section 6). (In vendor-portal, apply the overlay's pagination control — see
+  the overlay for its props.)
+- Render pagination **only when** `total > pageSize` and use the real total from
+  a dedicated count query — never derive total from `rows.length`.
+- **Omit pagination entirely for infinite-scroll lists.** Infinite scroll and
+  pagination are mutually exclusive — pick one per the surface rule.
+
+---
+
+## Section 9 — Modals (export / assign)
+
+Page-level modals (an export modal, a bulk-assign modal) are declared in the JSX
+and opened via local state. Build them on `@spark-web/modal-dialog`.
+
+```tsx
+<ExportModal isOpen={isExportOpen} onClose={closeExport} onExport={onExport} />
+<AssignModal isOpen={isAssignOpen} onClose={closeAssign} onAssign={onAssign} />
+```
+
+Rules:
+
+- Modals are always rendered in the tree (their open state is a prop), not
+  conditionally mounted, so close transitions work.
+- The export modal pairs with the title-row Export button; the assign modal
+  pairs with the bulk-action toast's assign action.
+- Use `@spark-web/modal-dialog` for the dialog chrome — never a custom overlay.
+
+---
+
+## Structural skeleton
+
+Use this skeleton as the starting point for new builds and uplifts. Do not use
+existing page implementations as a structural reference.
+
+```tsx
+<Stack
+  gap="large"
+  margin="xxlarge"
+  marginBottom="none"
+  height="full"
+  overflow="hidden"
+>
+  {/* Section 2 — page-level feedback Alert (conditional) — see above */}
+
+  {/* Section 3 — title row: Heading level="2" + count Badge (left),
+      right-aligned action Button(s) — see above */}
+
+  {/* Section 4 — filter bar Columns: date-range → multi-select → search — see above */}
+
+  <Stack position="relative" height="full" overflow="hidden">
+    <Stack width="full" css={{ overflowY: 'scroll' }}>
+      {/* Section 5 — DataTable (items/columns via createColumnHelper,
+          isLoading, emptyState) — see above */}
+    </Stack>
+
+    {/* Section 6 — SidePanel placeholder (conditional: single selected record;
+        COMPONENT GAP) — see above */}
+
+    {/* Section 7 — BulkActionToast placeholder (conditional: multi-select,
+        ≥1 row selected; COMPONENT GAP) — see above */}
+  </Stack>
+
+  {/* Section 8 — TablePagination placeholder (paginated lists only — omit
+      entirely for infinite scroll; COMPONENT GAP) — see above */}
+
+  {/* Section 9 — export / assign modals (declared in JSX, open via state) — see above */}
+</Stack>
+```
+
+---
+
+## Documented exceptions summary
+
+These raw CSS values are required and have no Spark token / prop equivalent. Use
+them exactly as written. Do not substitute alternatives. Everything else uses
+Spark props / tokens (the scroll region's `position`/`height`/`overflow` are
+Stack props, not raw CSS, and so are not listed here).
+
+| Value                        | Property             | Reason                                                      |
+| ---------------------------- | -------------------- | ----------------------------------------------------------- |
+| `overflowY: 'scroll'`        | inner scroll Stack   | No Spark prop for axis-specific overflow; scrolls the table |
+| `overflowY: 'auto'`          | side-panel `Box` css | No Spark prop for axis-specific overflow; scrolls the panel |
+| `width: '90vw'`              | side-panel `Box` css | Mobile panel width — no Spark token equivalent              |
+| `maxWidth: '500px'` (≥768px) | side-panel `Box` css | Tablet+ panel width cap per surface rule — no Spark token   |
+| `@media (min-width: 768px)`  | side-panel `Box` css | Breakpoint for panel width; placeholder is raw-CSS sized    |
+
+The `position="absolute"`, `top={0}`, `bottom={0}`, `right={0}`, `left={0}` on
+the side-panel / bulk-toast / pagination placeholder `Box`es are **Box props**,
+not raw CSS, so they are not exceptions.
+
+---
+
+## Do NOTs
+
+- NEVER use `PageHeader` for the page title — vendor-admin uses
+  `Heading level="2"`. Do not promote it to `level="1"`.
+- NEVER use `<Container>` as the list-page wrapper — the page body is a `Stack`
+  with `margin="xxlarge" marginBottom="none"`. Container is for centered
+  form/settings pages only.
+- NEVER reproduce the Header or NavBar inside the page — the shell wraps the
+  page (surface rule); the page starts at the title row.
+- NEVER place the search input first in the filter bar — vendor-admin order is
+  date-range → multi-select → search (search last). (This is the opposite of
+  internal-admin; do not "correct" it.)
+- NEVER use a bare `DatePicker` — it must be wrapped in a `Field` (it reads
+  `disabled` from Field context and carries the hidden label).
+- NEVER use plain text for status values — always `<Badge>` (dot + label) with a
+  tone from the surface tone mapping; never `tone="pending"` (use `info`), never
+  `StatusBadge` in a table.
+- NEVER render an external spinner / loading text outside DataTable — use the
+  `isLoading` prop; never omit `emptyState`.
+- NEVER render both the side panel and the bulk-action toast at once — they are
+  mutually exclusive (panel = single record; toast = multi-row selection).
+- NEVER render pagination for an infinite-scroll list — pick one loading
+  strategy per the surface rule; omit the pagination control entirely for
+  infinite scroll.
+- NEVER render pagination when all records fit on one page — only when
+  `total > pageSize`; never derive `total` from `rows.length`.
+- NEVER put pagination, the side panel, or the toast inside DataTable.
+- NEVER substitute the documented exception values with alternatives.
+- NEVER use the old `data-table` `ColumnDef[]` array API from vendor-portal's
+  pinned version — use the current `createColumnHelper` + `items`/`columns` API.
+- NEVER import a side panel, pagination, or bulk-action toast from `@spark-web`
+  — they are COMPONENT GAPs. Build each as a primitives placeholder
+  (Box/Stack/Heading/Text/Button), mark it with a `// COMPONENT GAP:` comment,
+  and flag it for product design review before production — do not ship the
+  placeholder as-is. (In vendor-portal, the overlay's local components remain
+  the canonical substitution.)
+- NEVER reach for vendor-portal's local `MultiselectCheckbox` in new code — the
+  canonical multi-select filter is `@spark-web/multi-select` `MultiSelect`; the
+  local wrapper is a retained overlay substitution only.
+
+---
+
+## Validation checklist
+
+Run this checklist before marking any vendor-admin list-page task complete. Fix
+every violation first. The uplift protocol in
+`node_modules/@spark-web/design-system/CLAUDE.md` also runs this checklist
+against existing pages and reports PASS/FAIL per item.
+
+1. Page title is `Heading level="2"` (not `PageHeader`, not `level="1"`), with
+   any count indicator as a `Badge` beside it; page-level actions (Export) are
+   right-aligned Buttons in the title row, not in the content area.
+2. Outer wrapper is a `Stack` with
+   `gap="large" margin="xxlarge" marginBottom="none" height="full" overflow="hidden"`
+   — not `Container`, not `PageHeader`; the page does not reproduce the shell
+   Header / NavBar.
+3. If search/filtering exists: filter bar order is date-range (`Field` +
+   `DatePicker`: From then To) → multi-select filter → search (search LAST),
+   with `gap="medium"`; all labels hidden but accessible
+   (`labelVisibility="hidden"` on each `Field`; `aria-labelledby` +
+   `VisuallyHidden` for `MultiSelect`).
+4. Every `DatePicker` is wrapped in a `Field`; the search `TextInput` has a
+   leading `InputAdornment` + `SearchIcon size="xxsmall" tone="muted"`.
+5. DataTable uses the current API — `items` + `columns` via
+   `createColumnHelper`, with `isLoading` and `emptyState` — never the old
+   `ColumnDef[]` array API, never an external spinner/empty text.
+6. Status columns use `<Badge>` (dot + label) with a tone from the surface tone
+   mapping — never plain text, never `StatusBadge`, never `tone="pending"`.
+7. DataTable sits inside the scroll region: an outer
+   `Stack position="relative" height="full" overflow="hidden"` wrapping an inner
+   `Stack css={{ overflowY: 'scroll' }}` — never directly in the page Stack.
+8. Side panel (if the record has detail) is rendered inside the scroll region,
+   only when a single record is selected (`selectedRows.length <= 1`), and is
+   flagged `// COMPONENT GAP: SidePanel/Drawer needed — not yet in Spark`.
+9. Bulk-action toast (multi-select lists) renders only when `selectedRows.length
+   > 0`, is mutually exclusive with the side panel, disables its actions during
+   > an in-flight mutation, and is flagged as a COMPONENT GAP where no Spark
+   > equivalent exists.
+10. List loading is exactly one of infinite scroll OR pagination (surface rule).
+    Pagination renders outside the scroll region, only when `total > pageSize`,
+    with `total` from a dedicated count query, flagged
+    `// COMPONENT GAP: TablePagination needed — not yet in Spark`; for
+    infinite-scroll lists no pagination control is rendered.
+11. Export / assign modals are built on `@spark-web/modal-dialog`, declared in
+    the JSX with open state — not custom overlays.
+12. No raw CSS values beyond the Documented exceptions table; every component is
+    `@spark-web/*` or an explicit consumer-overlay substitute, and anything
+    missing (side panel, pagination, bulk-action toast) is flagged with a
+    `// COMPONENT GAP:` comment.