@spark-web/design-system 5.0.100 → 5.1.0

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

@@ -0,0 +1,558 @@
+# Internal admin — list page pattern
+
+## Before using this pattern
+
+Read node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md
+fully before implementing this pattern. The interaction rules, badge tone
+mapping, row clickability rules, and overflow menu rules defined there all apply
+to this pattern.
+
+## What this pattern is
+
+A full page layout for displaying a searchable, filterable, paginated list of
+records in an internal admin interface. This is the most common page type in
+admin surfaces.
+
+## When to use this pattern
+
+Use this pattern when the PRD describes any of the following:
+
+- A list of records that can be searched, filtered, or sorted
+- A management interface where records can be viewed or acted upon
+- The words "list", "manage", "view all", "records", or "results"
+
+---
+
+## Required imports
+
+```tsx
+import { Stack } from '@spark-web/stack';
+import { Box } from '@spark-web/box';
+import { Columns } from '@spark-web/columns';
+import { Field } from '@spark-web/field';
+import { PageHeader } from '@spark-web/page-header';
+import { Text } from '@spark-web/text';
+import { TextInput } from '@spark-web/text-input';
+import { createColumnHelper, DataTable } from '@spark-web/data-table';
+import { Badge } from '@spark-web/badge';
+import { MeatballMenu } from '@spark-web/meatball-menu';
+import {
+  MultiSelectField,
+  SelectField,
+  TextInputField,
+} from '@brighte/ui-components'; // portal-hub only — @spark-web/multi-select not available
+import { css } from '@emotion/css';
+import { css as reactCss } from '@emotion/react';
+import { useTheme } from '@spark-web/theme';
+```
+
+---
+
+## Component docs to read
+
+Read these files at Step 4 — no others:
+
+- packages/page-header/CLAUDE.md
+- packages/data-table/CLAUDE.md
+- packages/badge/CLAUDE.md
+- packages/meatball-menu/CLAUDE.md
+- packages/stack/CLAUDE.md
+- packages/box/CLAUDE.md
+- packages/columns/CLAUDE.md
+- packages/field/CLAUDE.md
+- packages/text/CLAUDE.md
+- packages/text-input/CLAUDE.md
+
+---
+
+## Page structure
+
+The page is composed in this exact order, top to bottom. Do not change the order
+or omit any required section.
+
+```
+Page
+  Outer wrapper Stack            — full height, no padding
+  PageHeader                     — label={pageTitle}, optional statusBadge/action/controls
+  Alert (conditional)            — page-level feedback only, omit if no page-level actions
+  Content area Stack             — padding="large" gap="large", neutral background
+    Filter container             — required if filtering or searching exists
+    Table scroll wrapper         — flex scroll container (REQUIRED — never omit)
+      DataTable                  — required — the data table
+    Pagination                   — required if record count exceeds pageSize (custom, no Spark component)
+```
+
+---
+
+## Section 1 — Page header
+
+Renders the page title as an H1 using `PageHeader` from
+`@spark-web/page-header`.
+
+```tsx
+<PageHeader label={pageTitle} />
+```
+
+Optional variants — see `@spark-web/page-header` CLAUDE.md for full prop docs:
+
+```tsx
+{/* With status badge */}
+<PageHeader label={pageTitle} statusBadge={{ children: 'Active', tone: 'positive' }} />
+
+{/* With a single action button */}
+<PageHeader label={pageTitle} action={{ type: 'button', label: 'Add', onClick: handleAdd }} />
+
+{/* With overflow menu (2+ actions) */}
+<PageHeader label={pageTitle} action={{ type: 'meatball', items: [...] }} />
+```
+
+Rules:
+
+- Always use `PageHeader` — never replace with a manual `Stack + Heading`
+- `PageHeader` always renders an H1 — do not pass a different heading level
+- Page-level actions (e.g. "Add new") belong in the `action` prop, not in the
+  content area
+- This section always renders — never omit it
+
+---
+
+## Section 1b — Page-level feedback (conditional)
+
+When a page-level action (e.g. CSV export, bulk mutation) can produce success or
+error feedback, render an `<Alert>` between `<PageHeader>` and the content area
+Stack. Only rendered when feedback state exists.
+
+```tsx
+import { Alert } from '@spark-web/alert';
+
+{
+  actionStatus && (
+    <Alert tone={actionStatus.isSuccessful ? 'positive' : 'critical'}>
+      <Text>{actionStatus.message}</Text>
+    </Alert>
+  );
+}
+```
+
+Rules:
+
+- Never render Alert inside the neutral-background content Stack
+- Never render Alert above PageHeader
+- Feedback state is local component state, reset on filter change or page
+  navigation
+- If the page has no page-level actions, omit this section entirely
+
+---
+
+## Section 2 — Outer wrapper
+
+The outermost container fills the full viewport height.
+
+```tsx
+<Stack
+  height="full"
+  className={css({ minHeight: '100vh' })}
+>
+```
+
+Documented exceptions — no Spark token equivalent:
+
+- `minHeight: '100vh'` — ensures page fills viewport on short content
+
+---
+
+## Section 3 — Content area
+
+Sits inside the outer wrapper. Owns all page padding and gap between sections.
+
+```tsx
+<Stack
+  padding="large"
+  gap="large"
+  className={css({
+    backgroundColor: theme.color.background.neutral,
+    flex: 1,
+    display: 'flex',
+    flexDirection: 'column',
+    overflow: 'hidden',
+  })}
+>
+```
+
+Token mappings:
+
+- `padding="large"` — all four sides, Spark token
+- `gap="large"` — between all sections, Spark token
+- `backgroundColor` — `theme.color.background.neutral` via `useTheme()`
+
+Documented exceptions:
+
+- `flex: 1` — makes content area fill remaining height, no Spark flex prop
+- `display: 'flex'` + `flexDirection: 'column'` — required to activate flex: 1
+- `overflow: 'hidden'` — scroll containment, no Spark overflow prop on Stack
+
+---
+
+## Section 4 — Filter container
+
+Renders filter dropdowns and a search input in a horizontal row.
+
+```tsx
+const FieldProps = { labelVisibility: 'hidden' as const };
+
+<Columns gap="large" collapseBelow="desktop">
+  <MultiSelectField
+    control={control}
+    name="fieldName"
+    label="Label"
+    options={options}
+    placeholder="Filter by..."
+    fieldProps={FieldProps}
+  />
+  <Field label="Search">
+    <TextInput
+      type="search"
+      value={search}
+      onChange={e => setSearch(e.target.value)}
+      placeholder="Search by..."
+    />
+  </Field>
+</Columns>;
+```
+
+Rules:
+
+- Use `Columns` from @spark-web/columns with `gap="large"`
+- `collapseBelow="desktop"` — stacks vertically on mobile and tablet
+- Multi-select filter dropdowns use `MultiSelectField` from
+  `@brighte/ui-components` (portal-hub only — `@spark-web/multi-select` is not
+  available in portal-hub).
+- Single-select filter dropdowns use `SelectField` from
+  `@brighte/ui-components`.
+- Always pass `fieldProps={{ labelVisibility: 'hidden' as const }}` on both
+  `MultiSelectField` and `SelectField` — define it as a constant outside the
+  component to avoid re-renders. Never wrap in a `Stack` + `Text` label — the
+  label is hidden, not replaced. This rule applies to both components equally.
+
+  ```tsx
+  const FieldProps = { labelVisibility: 'hidden' as const };
+
+  <SelectField
+    control={control}
+    name="vendor"
+    label="Vendor"
+    options={vendorOptions}
+    placeholder="Filter by vendor..."
+    fieldProps={FieldProps}
+  />;
+  ```
+
+- Search input uses `TextInputField` from `@brighte/ui-components` with
+  `FieldProps` (same hidden label constant), with `SearchIcon` adornment on
+  start and a clear button (`XIcon`) on end
+- Filter controls always appear left of the search input
+- Maximum 2 filter dropdowns before the search input
+- Search input always appears on the far right
+- If no filtering or searching is needed, omit this section entirely
+
+---
+
+## Section 5 — Table scroll wrapper
+
+Wraps the Table to enable vertical scrolling without the page scrolling.
+
+```tsx
+<Box display="flex" flexDirection="column">
+  <div
+    className={css({
+      position: 'relative',
+      flex: 1,
+      minHeight: 0,
+      overflowY: 'auto',
+    })}
+  >
+    <Table>...</Table>
+  </div>
+</Box>
+```
+
+Documented exceptions — all required for flex scroll behaviour:
+
+- `position: 'relative'` — scroll container positioning
+- `flex: 1` — fills available height
+- `minHeight: 0` — classic flex scroll fix, prevents overflow
+- `overflowY: 'auto'` — enables vertical scrolling
+
+---
+
+## Section 6 — Table
+
+The core data display. Always uses `@spark-web/data-table`.
+
+Define columns outside the component using `createColumnHelper`. Pass `items`
+and `columns` to `<DataTable>`.
+
+Always apply `className` and `headerClassName` for canonical list-page styling:
+
+```tsx
+<DataTable
+  className={reactCss({ width: '100%' })}
+  headerClassName={reactCss({
+    boxShadow: `inset 0 -2px 0 0 ${theme.color.background.primaryDark}`,
+    th: {
+      color: theme.color.background.primaryDark,
+      textTransform: 'capitalize',
+      svg: { stroke: theme.color.background.primaryDark },
+    },
+  })}
+  ...
+/>
+```
+
+Note: `className` and `headerClassName` accept a `SerializedStyles` object from
+`@emotion/react`'s `css` — not a string class from `@emotion/css`. Use the named
+import `import { css as reactCss } from '@emotion/react'` to distinguish them.
+
+Column rules:
+
+- Default column width: equal flex distribution (`size` unset)
+- Actions column: always last, `size: 80`, empty string `header`
+- Status column: always use `<Badge>` (dot + label) — never `<StatusBadge>`,
+  never plain text
+- Actions column: always uses `<MeatballMenu>` when 2 or more row-level actions
+  exist
+
+Row interaction rules — see
+node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md:
+
+- Pass `onRowClick` and `enableClickableRow` when the record has a detail view
+- Hover state is applied automatically when `enableClickableRow` is true
+
+Status tone mapping — authoritative rules are in
+node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md. Do not
+duplicate them here.
+
+Table states to always implement:
+
+- Default: `items={rows}` with data
+- Loading: `isLoading` prop — renders spinner overlay, replaces data rows
+- Empty: `emptyState={<Text tone="muted" size="small">…</Text>}` — shown when
+  `items` is an empty array
+
+---
+
+## Section 7 — Pagination
+
+No dedicated Spark pagination component exists. Implement using Spark primitives
+or flag as a component gap.
+
+- Pagination is rendered outside and below DataTable — never nested inside it
+- Pagination is always rendered regardless of loading or empty state — never
+  conditionally hidden.
+
+Rules:
+
+- Always implement when the data source is an API or database
+- Default pageSize: 20
+- No additional wrapper needed — content area `gap="large"` handles spacing
+
+---
+
+## Complete assembly
+
+```tsx
+const col = createColumnHelper<Row>();
+
+const columns = [
+  col.accessor('column1', {
+    header: 'Column 1',
+    cell: info => <Text size="small">{String(info.getValue())}</Text>,
+  }),
+  col.accessor('status', {
+    header: 'Status',
+    cell: info => (
+      <Badge tone={deriveTone(info.getValue())}>{info.getValue()}</Badge>
+    ),
+  }),
+  col.display({
+    id: 'actions',
+    header: '',
+    size: 80,
+    cell: ({ row }) => <MeatballMenu items={rowActions(row.original)} />,
+  }),
+];
+
+// ---
+
+const theme = useTheme()
+
+<Stack height="full" className={css({ minHeight: '100vh' })}>
+  {/* Section 1: Page header */}
+  <PageHeader label={pageTitle} />
+
+  {/* Sections 3–7: Content area — neutral background */}
+  <Stack
+    padding="large"
+    gap="large"
+    className={css({
+      backgroundColor: theme.color.background.neutral,
+      flex: 1,
+      display: 'flex',
+      flexDirection: 'column',
+      overflow: 'hidden',
+    })}
+  >
+    {/* Section 4: Filters */}
+    <Columns gap="large" collapseBelow="desktop">
+      <MultiSelectField
+        control={control}
+        name="status"
+        label="Status"
+        options={statusOptions}
+        placeholder="Filter by status"
+        fieldProps={FieldProps}
+      />
+      <Field label="Search">
+        <TextInput type="search" value={search} onChange={e => setSearch(e.target.value)} placeholder="Search by..." />
+      </Field>
+    </Columns>
+
+    {/* Section 5 + 6: Table */}
+    <Box display="flex" flexDirection="column">
+      <div className={css({
+        position: 'relative',
+        flex: 1,
+        minHeight: 0,
+        overflowY: 'auto',
+      })}>
+        <DataTable
+          className={reactCss({ width: '100%' })}
+          headerClassName={reactCss({
+            boxShadow: `inset 0 -2px 0 0 ${theme.color.background.primaryDark}`,
+            th: {
+              color: theme.color.background.primaryDark,
+              textTransform: 'capitalize',
+              svg: { stroke: theme.color.background.primaryDark },
+            },
+          })}
+          items={rows}
+          columns={columns}
+          isLoading={isLoading}
+          emptyState={
+            <Text tone="muted" size="small">No records found. Try adjusting your filters.</Text>
+          }
+        />
+      </div>
+
+      {/* Section 7: Pagination — implement with Spark primitives */}
+    </Box>
+  </Stack>
+</Stack>
+```
+
+---
+
+## 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 height="full" className={css({ minHeight: '100vh' })}>
+  <PageHeader label={pageTitle} />
+
+  <Stack
+    padding="large"
+    gap="large"
+    className={css({
+      backgroundColor: theme.color.background.neutral,
+      flex: 1,
+      display: 'flex',
+      flexDirection: 'column',
+      overflow: 'hidden',
+    })}
+  >
+    <Columns gap="large" collapseBelow="desktop">
+      {/* filters here */}
+      {/* search here */}
+    </Columns>
+
+    <Box display="flex" flexDirection="column">
+      <div
+        className={css({
+          position: 'relative',
+          flex: 1,
+          minHeight: 0,
+          overflowY: 'auto',
+        })}
+      >
+        <DataTable
+          items={items}
+          columns={columns}
+          isLoading={isLoading}
+          emptyState={emptyState}
+        />
+      </div>
+    </Box>
+
+    {/* pagination here */}
+  </Stack>
+</Stack>
+```
+
+---
+
+## Documented exceptions summary
+
+These raw CSS values are required and have no Spark token equivalent. Use them
+exactly as written. Do not substitute alternatives.
+
+| Value                                         | Property                     | Reason                                  |
+| --------------------------------------------- | ---------------------------- | --------------------------------------- |
+| `minHeight: '100vh'`                          | Outer Stack                  | No Spark minHeight prop                 |
+| `flex: 1`                                     | Content area, scroll wrapper | No Spark flex prop                      |
+| `display: 'flex'` + `flexDirection: 'column'` | Content area                 | Required for flex: 1                    |
+| `overflow: 'hidden'`                          | Content area                 | No Spark overflow on Stack              |
+| `position: 'relative'`                        | Scroll div                   | No Spark position prop                  |
+| `minHeight: 0`                                | Scroll div                   | Flex scroll fix                         |
+| `overflowY: 'auto'`                           | Scroll div                   | No Spark overflow prop                  |
+| `backgroundColor: background.neutral`         | Content area                 | Accessed via useTheme(), not a Box prop |
+
+---
+
+## Do NOTs
+
+- NEVER use `<Container>` as the outer page wrapper — always use
+  `<Stack height="full">`. Container constrains width and removes full-height
+  layout and scroll containment behaviour
+- NEVER place DataTable directly inside the content area Stack — always use the
+  `<Box display="flex" flexDirection="column"> <div className={...}>` scroll
+  wrapper from Section 5. Omitting it breaks page scroll containment
+- NEVER put pagination inside DataTable
+- NEVER use plain text for status values — always use Badge with `children`
+- NEVER import `MeatBall` from `@spark-web/meatball` — the component is
+  `MeatballMenu` from `@spark-web/meatball-menu`
+- NEVER use `tone="pending"` on Badge — it does not exist; use `tone="info"` for
+  pending/awaiting states
+- NEVER omit the page header — every list page has an H1 title via PageHeader
+- NEVER add padding to the outer Stack wrapper
+- NEVER omit the flex scroll wrapper around DataTable
+- NEVER omit the empty state and loading state
+- NEVER place filter controls inside DataTable
+- NEVER hardcode column widths except for the actions column (80px)
+- NEVER substitute the documented exception values with alternatives
+- NEVER replace PageHeader with a manual Stack + Heading + Text breadcrumb
+- NEVER apply detail page spacing (paddingX="xlarge" paddingY="xxlarge") to a
+  list page — those values belong in detail-page.md only
+- NEVER render an external loading spinner/text outside DataTable — always use
+  the `isLoading` prop on DataTable to show loading state
+- NEVER use `Stack + Text weight="semibold"` to label a MultiSelectField or
+  SelectField filter — always use
+  `fieldProps={{ labelVisibility: 'hidden' as const }}`
+- NEVER omit `fieldProps={{ labelVisibility: 'hidden' as const }}` on
+  SelectField filter dropdowns — the same hidden label rule that applies to
+  MultiSelectField applies to SelectField equally
+- NEVER use `@spark-web/multi-select` in portal-hub — it is not installed; use
+  `MultiSelectField` from `@brighte/ui-components`
+- NEVER use `className` with a string from `@emotion/css` on DataTable — use
+  `SerializedStyles` from `@emotion/react`'s `css` tagged template