@spark-web/design-system 5.0.100 → 5.1.1

package/patterns/CLAUDE.md

@@ -0,0 +1,67 @@
+# Pattern library — surface classifier
+
+When an agent receives a PRD or feature brief, it must read this file first
+before reading any component or pattern documentation.
+
+---
+
+## Step 1 — Identify the surface
+
+Determine which surface is being built by reading the PRD for these signals:
+
+| Signal in PRD                                                    | Surface                           |
+| ---------------------------------------------------------------- | --------------------------------- |
+| "admin", "internal", "back office", "ops", "manage", "dashboard" | Internal admin                    |
+| "customer", "portal", "my account", "self-service"               | Customer portal (not yet defined) |
+| "website", "marketing", "landing page", "public"                 | Website (not yet defined)         |
+| "mobile", "app", "iOS", "Android"                                | Mobile app (not yet defined)      |
+
+If the surface cannot be determined from the PRD, ask for clarification before
+proceeding. Do not assume.
+
+---
+
+## Step 2 — Read the rules for that surface
+
+| Surface         | Rules location                                                            |
+| --------------- | ------------------------------------------------------------------------- |
+| Internal admin  | `node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md` |
+| Customer portal | Not yet defined — flag to the team                                        |
+| Website         | Not yet defined — flag to the team                                        |
+| Mobile app      | Not yet defined — flag to the team                                        |
+
+Read the surface rules file in full before reading any component documentation.
+Surface rules take precedence over component rules.
+
+---
+
+## Step 3 — Read the pattern for the feature type
+
+After reading surface rules, identify the feature type and read the
+corresponding pattern file:
+
+| Feature type                 | Pattern file                                                                                 |
+| ---------------------------- | -------------------------------------------------------------------------------------------- |
+| List of records with actions | `node_modules/@spark-web/design-system/patterns/internal-admin/list-page.md`                 |
+| Create or edit a record      | `node_modules/@spark-web/design-system/patterns/internal-admin/form-page.md` (coming soon)   |
+| Record detail view           | `node_modules/@spark-web/design-system/patterns/internal-admin/detail-page.md` (coming soon) |
+
+If no pattern file exists yet for the feature type, use the surface rules and
+component documentation to make the best decision, and flag that a pattern file
+should be created for this feature type.
+
+---
+
+## Reading order for any build task
+
+1. `node_modules/@spark-web/design-system/patterns/CLAUDE.md` ← this file
+   (surface classifier)
+2. `node_modules/@spark-web/design-system/patterns/[surface]/CLAUDE.md` ←
+   surface interaction rules
+3. `node_modules/@spark-web/design-system/patterns/[surface]/[pattern].md` ←
+   feature pattern (if exists)
+4. `node_modules/@spark-web/[component]/CLAUDE.md` ← component rules
+5. `node_modules/@spark-web/[component]/src/[component].stories.tsx` ← usage
+   examples
+
+Never skip steps. Never read component documentation before surface rules.

package/patterns/internal-admin/CLAUDE.md

@@ -0,0 +1,126 @@
+# Internal admin — interaction and pattern rules
+
+These rules apply to all components and patterns built for internal admin
+surfaces. They sit above individual component rules. When a conflict exists
+between these rules and a component-level CLAUDE.md, these rules take precedence
+for admin surfaces.
+
+---
+
+## Row interaction rules
+
+### Clickable rows
+
+A row is clickable when the data model has a record-level detail view or
+destination page. The agent must determine this from the PRD:
+
+- If the PRD describes a detail page, record view, or drill-down → row is
+  clickable
+- If the PRD describes a read-only data display with no record destination → row
+  is not clickable
+- If unsure, default to clickable
+
+### Hover state
+
+Hover state is determined entirely by whether the row is clickable:
+
+- Row is clickable → hover state is applied when the cursor is over the row,
+  **except** when hovering a button within the row (e.g. the MeatballMenu
+  trigger)
+- Row is not clickable → hover state is never applied, no exceptions
+
+Never apply a hover state to a non-clickable row. It implies interactivity that
+does not exist and misleads the user.
+
+When a clickable row contains a MeatballMenu, the row hover must be suppressed
+while the cursor is over the meatball button. Two competing hover targets (row
+and menu trigger) confuse the user about what will happen on click. Implement
+using CSS `:has()` on the `<tr>` — see `@spark-web/data-table` CLAUDE.md for the
+exact pattern.
+
+---
+
+## Overflow menu rules
+
+An overflow menu on a row is used only when ALL of the following are true:
+
+- There are 2 or more actions that apply to the row record
+- The actions relate only to that specific record, not to the page or table
+
+Use this decision tree:
+
+```
+Does the row have actions?
+  No  → no overflow menu, no action column
+  Yes → how many actions?
+          1 action + row is NOT clickable → inline button or icon
+          1 action + row IS clickable     → overflow menu
+          2+ actions                      → always overflow menu
+```
+
+Never place inline action buttons alongside a clickable row. A clickable row and
+inline buttons create two competing interaction targets and confuse the user
+about what clicking does.
+
+---
+
+## Badge and pill rules
+
+A badge or pill is used only when:
+
+- The field represents a status with 2 or more distinct values
+- The status values have meaningful visual distinction (e.g. active vs inactive,
+  pending vs approved vs rejected)
+
+Do not use a badge when:
+
+- The field is free-form text
+- The field is a boolean with no meaningful status distinction
+- There is only one possible value
+
+### Badge tone mapping
+
+This mapping is authoritative for the internal-admin surface. If a component
+CLAUDE.md defines tone guidance, the mapping below takes precedence.
+
+Map status values to tones using this logic derived from the PRD:
+
+- Positive / active / approved / complete → `positive` tone
+- Warning / approaching limit / expiring → `caution` tone
+- Critical / rejected / failed / overdue / suspended → `critical` tone
+- Neutral / inactive / archived / unknown → `neutral` tone
+- Pending / in review / awaiting approval → `info` tone
+
+**Caution vs info (pending):** Use `caution` for warnings that are
+time-sensitive or approaching a limit. Use `info` for states where a record is
+waiting on a human decision or review (e.g. "Pending approval", "Under review").
+
+Component choice:
+
+- Always use `<Badge>` (dot + label) for status columns in list-page tables —
+  never `<StatusBadge>`
+- Use `<StatusBadge>` (colored pill, no dot) only in page headers and section
+  headers via their `statusBadge` prop — never in table status columns
+
+Available tones for both components:
+`accent | caution | critical | info | neutral | positive`. There is no `pending`
+tone — always use `info` for pending/awaiting states.
+
+When in doubt, use `neutral`. Never invent a tone that does not exist in the
+Spark Web theme.
+
+---
+
+## Rules that update as the system grows
+
+When a new pattern or component is added to the internal admin surface, update
+this file with any new interaction rules that apply globally. Do not duplicate
+rules that already exist here in component-level CLAUDE.md files.
+
+Then open the root CLAUDE.md and append this line to the Architecture section:
+
+## Pattern library
+
+Agent pattern and surface rules live in
+node_modules/@spark-web/design-system/patterns/. Always read
+node_modules/@spark-web/design-system/patterns/CLAUDE.md before any build task.

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

@@ -0,0 +1,358 @@
+# Internal admin — details 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, and action dropdown rules defined there all apply to this pattern.
+
+## What this pattern is
+
+A full page layout for displaying the detail view of a single record in an
+internal admin interface. The page shows structured data and contextual
+sub-tables in a two-column layout, with record-level actions surfaced through a
+header dropdown.
+
+## When to use this pattern
+
+Use this pattern when the PRD describes any of the following:
+
+- A single-record view reachable by clicking a row on a list page
+- A page showing a record's fields, history, or associated sub-records
+- The words "detail", "profile", "view", "record page", or "user/vendor page"
+
+---
+
+## Component docs to read
+
+Read these before implementing — they own the component-level rules:
+
+- `packages/action-dropdown/CLAUDE.md` — dropdown construction, ordering, hide
+  vs. disable
+- `packages/modal-dialog/CLAUDE.md` — ContentDialog API,
+  ACCREDITATION_MODAL_CSS, destructive modal anatomy
+- `packages/data-table/CLAUDE.md` — DataTable API, loading/empty states,
+  expandable rows
+- `packages/tabs/CLAUDE.md` — Tabs API, internal-admin background override, null
+  guard
+- `packages/section-card/CLAUDE.md` — SectionCard API (note: portal-hub uses a
+  custom wrapper; see Section 6 below)
+- `packages/badge/CLAUDE.md` — status tone mapping
+- `packages/columns/CLAUDE.md` — responsive two-column layout
+- `packages/box/CLAUDE.md` — flex layout utilities
+- `packages/stack/CLAUDE.md` — vertical stacking and gap
+
+---
+
+## Page structure
+
+```
+Outer wrapper Stack              paddingX="xlarge" paddingY="xxlarge" gap="xlarge"
+  Header Box                     spaceBetween row: [Heading level="1" + Badge] | [ActionDropdown]
+  Page-level feedback Alert      conditional — only for inline (non-modal) action feedback
+  Modals                         all ContentDialog modals declared here, controlled by openModal state
+  Content Columns                template=[1,1] gap="xlarge" collapseBelow="desktop"
+    Left column Stack            gap="xlarge" — primary record fields + primary sub-tables
+    Right column Stack           gap="xlarge" — secondary/contextual sections
+      SectionCard (per section)
+        DataTable                PAGE_SIZE=5 items; see data-table/CLAUDE.md
+        TablePagination          only when total > PAGE_SIZE
+```
+
+---
+
+## Section 1 — Outer wrapper
+
+```tsx
+<Stack height="full" paddingX="xlarge" paddingY="xxlarge" gap="xlarge">
+```
+
+All spacing uses Spark tokens. This is distinct from list-page spacing
+(`padding="large"` on a neutral-background Stack) — do not mix the two.
+
+---
+
+## Section 2 — Page header
+
+```tsx
+<Box
+  display="flex"
+  flexDirection={{ mobile: 'column', tablet: 'row' }}
+  justifyContent={{ tablet: 'spaceBetween' }}
+  gap="medium"
+>
+  <Box
+    display="flex"
+    flexDirection={{ mobile: 'columnReverse', tablet: 'row' }}
+    alignItems={{ mobile: 'start', tablet: 'center' }}
+    gap={{ mobile: 'medium', tablet: 'small' }}
+  >
+    <Heading level="1">{recordTitle}</Heading>
+    <Badge tone={statusTone}>{statusLabel}</Badge>
+  </Box>
+
+  {actions.length > 0 && (
+    <Box className={css({ minWidth: 130 })}>
+      <ActionDropdown label="Actions" actions={actions} />
+    </Box>
+  )}
+</Box>
+```
+
+Rules:
+
+- Status badge follows the heading — never precedes it
+- Only render `ActionDropdown` when `actions.length > 0`
+- No action buttons directly in the header — always use `ActionDropdown`
+
+---
+
+## Section 3 — Actions dropdown
+
+See `packages/action-dropdown/CLAUDE.md` for full API and ordering rules.
+
+Page-level decisions:
+
+- **Order**: non-destructive actions first, restore-type actions second,
+  `tone: 'critical'` destructive actions always last
+- **Hide vs. disable**: hide actions permanently unavailable for the current
+  record state (conditional spread); disable actions temporarily unavailable
+  (e.g. mutation in-flight)
+- **Direct vs. modal**: direct actions (password reset, restore, activate) call
+  the mutation inline and surface feedback via page-level `actionStatus` Alert;
+  destructive actions (delete, suspend) always open a `ContentDialog` modal
+  first
+
+---
+
+## Section 4 — Page-level feedback
+
+```tsx
+{
+  actionStatus && (
+    <Alert tone={actionStatus.isSuccessful ? 'positive' : 'critical'}>
+      <Text>{actionStatus.message}</Text>
+    </Alert>
+  );
+}
+```
+
+State shape: `{ isSuccessful: boolean; message: string } | undefined`
+
+Rendered between the header and content columns. Only used for direct inline
+mutations. Modal confirmations own their own error Alert inside the
+`ContentDialog` — see `packages/modal-dialog/CLAUDE.md`.
+
+---
+
+## Section 5 — Confirmation modals
+
+See `packages/modal-dialog/CLAUDE.md` for ContentDialog API, sizing,
+form-in-modal anatomy, and the full destructive modal pattern.
+
+Declare all modals in the component JSX, controlled by a single `openModal`
+state union:
+
+```ts
+const [openModal, setOpenModal] = useState<'delete' | 'suspend' | null>(null);
+```
+
+```tsx
+{
+  openModal === 'delete' && recordId && (
+    <DeleteModal
+      isOpen
+      onToggle={() => setOpenModal(null)}
+      recordId={recordId}
+      onSuccess={() => {
+        refetch();
+        setOpenModal(null);
+      }}
+    />
+  );
+}
+```
+
+---
+
+## Section 6 — Content columns
+
+```tsx
+<Columns gap="xlarge" template={[1, 1]} collapseBelow="desktop">
+  <Stack gap="xlarge">{/* left column */}</Stack>
+  <Stack gap="xlarge">{/* right column */}</Stack>
+</Columns>
+```
+
+Always equal columns (`template={[1, 1]}`), always collapse below desktop.
+
+---
+
+## Section 7 — Section cards
+
+Each content section is wrapped in a `SectionCard`.
+
+**Portal-hub uses a custom wrapper** at `@components/PortalTable/SectionCard`
+(not `@spark-web/section-card`). The API differs:
+
+```tsx
+import { SectionCard } from '@components/PortalTable/SectionCard';
+
+<SectionCard label="Section Title">{/* section content */}</SectionCard>;
+```
+
+| Prop       | Type        | Notes                                 |
+| ---------- | ----------- | ------------------------------------- |
+| `label`    | `string`    | Required — card header text           |
+| `action`   | `ReactNode` | Optional — right-side header control  |
+| `controls` | `ReactNode` | Optional — additional header controls |
+
+Return `null` for sections conditionally hidden — never render an empty card.
+
+---
+
+## Section 8 — Section data tables
+
+See `packages/data-table/CLAUDE.md` for DataTable API, column definitions, and
+loading/empty state props.
+
+Detail-page-specific rules (differ from list pages):
+
+- **`PAGE_SIZE = 5`** — always 5 items per section table (not 20 like list
+  pages)
+- **Pagination threshold**: render `TablePagination` only when
+  `total > PAGE_SIZE`
+- **Reset page**: reset to 1 when the record context changes (e.g. `userId`)
+
+```tsx
+const PAGE_SIZE = 5;
+const [page, setPage] = useState(1);
+
+useEffect(() => {
+  setPage(1);
+}, [recordId]);
+
+// Client-side pagination — fetch all, slice
+const allItems = data?.items ?? [];
+const total = allItems.length;
+const pageItems = allItems.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE);
+
+// Server-side pagination — skip/take API
+const { data } = useQuery({ skip: (page - 1) * PAGE_SIZE, take: PAGE_SIZE });
+const total = countData?.count ?? 0;
+const pageItems = data?.items ?? [];
+```
+
+```tsx
+<Stack gap="large">
+  <DataTable
+    items={pageItems}
+    columns={columns}
+    isLoading={isLoading}
+    emptyState={
+      <Text tone="muted" size="small" align="center">
+        No items.
+      </Text>
+    }
+  />
+  {total > PAGE_SIZE && (
+    <TablePagination
+      total={total}
+      pageSize={PAGE_SIZE}
+      dataShowing={pageItems.length}
+      onChange={setPage}
+      current={page}
+    />
+  )}
+</Stack>
+```
+
+---
+
+## Section 9 — Tabbed sections
+
+See `packages/tabs/CLAUDE.md` for the Tabs API, dynamic tab construction, the
+required internal-admin background override, and the null guard pattern.
+
+Use tabs when a section has multiple sub-views (e.g. Email / SMS history). Each
+tab panel follows the same PAGE_SIZE=5 and pagination rules as Section 8.
+
+---
+
+## Structural skeleton
+
+```tsx
+<Stack height="full" paddingX="xlarge" paddingY="xxlarge" gap="xlarge">
+  {/* Header */}
+  <Box
+    display="flex"
+    flexDirection={{ mobile: 'column', tablet: 'row' }}
+    justifyContent={{ tablet: 'spaceBetween' }}
+    gap="medium"
+  >
+    <Box
+      display="flex"
+      flexDirection={{ mobile: 'columnReverse', tablet: 'row' }}
+      alignItems={{ mobile: 'start', tablet: 'center' }}
+      gap={{ mobile: 'medium', tablet: 'small' }}
+    >
+      <Heading level="1">{recordTitle}</Heading>
+      <Badge tone={statusTone}>{statusLabel}</Badge>
+    </Box>
+    {actions.length > 0 && (
+      <Box className={css({ minWidth: 130 })}>
+        <ActionDropdown label="Actions" actions={actions} />
+      </Box>
+    )}
+  </Box>
+
+  {/* Page-level feedback — direct actions only */}
+  {actionStatus && (
+    <Alert tone={actionStatus.isSuccessful ? 'positive' : 'critical'}>
+      <Text>{actionStatus.message}</Text>
+    </Alert>
+  )}
+
+  {/* Modals */}
+  {openModal === 'delete' && recordId && (
+    <DeleteModal
+      isOpen
+      onToggle={() => setOpenModal(null)}
+      recordId={recordId}
+      onSuccess={() => {
+        refetch();
+        setOpenModal(null);
+      }}
+    />
+  )}
+
+  {/* Content */}
+  <Columns gap="xlarge" template={[1, 1]} collapseBelow="desktop">
+    <Stack gap="xlarge">
+      <SectionCard label="Details">{/* fields */}</SectionCard>
+    </Stack>
+    <Stack gap="xlarge">
+      <SectionCard label="History">{/* table + pagination */}</SectionCard>
+    </Stack>
+  </Columns>
+</Stack>
+```
+
+---
+
+## Do NOTs
+
+- NEVER apply list-page spacing to a detail page — outer wrapper uses
+  `paddingX="xlarge" paddingY="xxlarge"`, not `padding="large"`
+- NEVER place a destructive action before non-destructive actions in the
+  dropdown
+- NEVER call a destructive mutation directly from a dropdown item — open a modal
+- NEVER surface modal errors as page-level Alerts — see `modal-dialog/CLAUDE.md`
+- NEVER use `PAGE_SIZE = 20` on section tables — always 5 on detail pages
+- NEVER render `TablePagination` when `total <= PAGE_SIZE`
+- NEVER render an empty `SectionCard` for hidden sections — return `null`
+- NEVER render `ActionDropdown` when `actions` is empty — gate with
+  `actions.length > 0`
+- NEVER render `Tabs` inside `SectionCard` without the background override — see
+  `tabs/CLAUDE.md`
+- NEVER use `Container` as the outer page wrapper