@spark-web/design-system 5.1.4 → 5.1.5

package/patterns/internal-admin/{details-page.md → detail-page.md}

@@ -1,10 +1,10 @@
-# Internal admin — details page pattern
+# Internal admin — detail 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.
+Surface rules: read
+`node_modules/@spark-web/design-system/patterns/internal-admin/CLAUDE.md` in
+full first — its rules all apply here.
 
 ## What this pattern is
 
@@ -15,11 +15,9 @@ 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"
+Any single-record detail/profile view — the registry
+(`node_modules/@spark-web/design-system/patterns/CLAUDE.md`) owns surface and
+feature-type classification.
 
 ---
 
@@ -27,20 +25,23 @@ Use this pattern when the PRD describes any of the following:
 
 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
+- `node_modules/@spark-web/action-dropdown/CLAUDE.md` — dropdown construction,
+  ordering, hide vs. disable
+- `node_modules/@spark-web/modal-dialog/CLAUDE.md` — ContentDialog API, admin
+  modal sizing, destructive modal anatomy
+- `node_modules/@spark-web/data-table/CLAUDE.md` — DataTable API, loading/empty
+  states, expandable rows
+- `node_modules/@spark-web/tabs/CLAUDE.md` — Tabs API, internal-admin background
+  override, null guard
+- `node_modules/@spark-web/section-card/CLAUDE.md` — SectionCard API
+- `node_modules/@spark-web/section-header/CLAUDE.md` — SectionHeader API, for
+  SectionCard headers
+- `node_modules/@spark-web/badge/CLAUDE.md` — status tone mapping
+- `node_modules/@spark-web/columns/CLAUDE.md` — responsive two-column layout
+- `node_modules/@spark-web/box/CLAUDE.md` — flex layout utilities
+- `node_modules/@spark-web/stack/CLAUDE.md` — vertical stacking and gap
+- `node_modules/@spark-web/heading/CLAUDE.md` — detail-page H1
+- `node_modules/@spark-web/alert/CLAUDE.md` — page-level feedback Alert
 
 ---
 
@@ -55,8 +56,8 @@ Outer wrapper Stack              paddingX="xlarge" paddingY="xxlarge" gap="xlarg
     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
+        DataTable                PAGE_SIZE=5 items; see node_modules/@spark-web/data-table/CLAUDE.md
+        TablePagination          consumer-supplied — only when total > PAGE_SIZE
 ```
 
 ---
@@ -92,7 +93,7 @@ All spacing uses Spark tokens. This is distinct from list-page spacing
   </Box>
 
   {actions.length > 0 && (
-    <Box className={css({ minWidth: 130 })}>
+    <Box css={{ minWidth: 130 }}>
       <ActionDropdown label="Actions" actions={actions} />
     </Box>
   )}
@@ -109,7 +110,8 @@ Rules:
 
 ## Section 3 — Actions dropdown
 
-See `packages/action-dropdown/CLAUDE.md` for full API and ordering rules.
+See `node_modules/@spark-web/action-dropdown/CLAUDE.md` for full API and
+ordering rules.
 
 Page-level decisions:
 
@@ -141,14 +143,14 @@ 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`.
+`ContentDialog` — see `node_modules/@spark-web/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.
+See `node_modules/@spark-web/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:
@@ -190,38 +192,50 @@ 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:
+Each content section is wrapped in a `SectionCard` from
+`@spark-web/section-card`, composed with `SectionHeader` from
+`@spark-web/section-header` for the card header:
 
 ```tsx
-import { SectionCard } from '@components/PortalTable/SectionCard';
+import { SectionCard } from '@spark-web/section-card';
+import { SectionHeader } from '@spark-web/section-header';
 
-<SectionCard label="Section Title">{/* section content */}</SectionCard>;
+<SectionCard header={<SectionHeader 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 |
+| Prop       | Type        | Notes                                                   |
+| ---------- | ----------- | ------------------------------------------------------- |
+| `children` | `ReactNode` | Required — main content area                            |
+| `header`   | `ReactNode` | Optional — renders above the content; use SectionHeader |
+| `footer`   | `ReactNode` | Optional — rendered below a Divider                     |
+
+The header text (`label`), optional `action`, and optional `controls` belong to
+`SectionHeader` — see `node_modules/@spark-web/section-header/CLAUDE.md`.
 
 Return `null` for sections conditionally hidden — never render an empty card.
 
+Working in portal-hub? Apply the substitutions in
+`node_modules/@spark-web/design-system/patterns/internal-admin/portal-hub.md`.
+
 ---
 
 ## Section 8 — Section data tables
 
-See `packages/data-table/CLAUDE.md` for DataTable API, column definitions, and
-loading/empty state props.
+See `node_modules/@spark-web/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`
+  `total > PAGE_SIZE`. `TablePagination` is NOT a spark-web component (COMPONENT
+  GAP) — build a placeholder from `@spark-web/box` + `@spark-web/button`
+  (prev/next + "Show N of M") and flag it for product design review before
+  production. Props: `total`, `pageSize`, `current`, `dataShowing`,
+  `onChange(page)`
 - **Reset page**: reset to 1 when the record context changes (e.g. `userId`)
 
 ```tsx
@@ -255,6 +269,7 @@ const pageItems = data?.items ?? [];
       </Text>
     }
   />
+  {/* COMPONENT GAP: TablePagination — see the pagination rules above */}
   {total > PAGE_SIZE && (
     <TablePagination
       total={total}
@@ -271,8 +286,9 @@ const pageItems = data?.items ?? [];
 
 ## 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.
+See `node_modules/@spark-web/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.
@@ -300,7 +316,7 @@ tab panel follows the same PAGE_SIZE=5 and pagination rules as Section 8.
       <Badge tone={statusTone}>{statusLabel}</Badge>
     </Box>
     {actions.length > 0 && (
-      <Box className={css({ minWidth: 130 })}>
+      <Box css={{ minWidth: 130 }}>
         <ActionDropdown label="Actions" actions={actions} />
       </Box>
     )}
@@ -329,10 +345,14 @@ tab panel follows the same PAGE_SIZE=5 and pagination rules as Section 8.
   {/* Content */}
   <Columns gap="xlarge" template={[1, 1]} collapseBelow="desktop">
     <Stack gap="xlarge">
-      <SectionCard label="Details">{/* fields */}</SectionCard>
+      <SectionCard header={<SectionHeader label="Details" />}>
+        {/* fields */}
+      </SectionCard>
     </Stack>
     <Stack gap="xlarge">
-      <SectionCard label="History">{/* table + pagination */}</SectionCard>
+      <SectionCard header={<SectionHeader label="History" />}>
+        {/* table + pagination */}
+      </SectionCard>
     </Stack>
   </Columns>
 </Stack>
@@ -340,6 +360,17 @@ tab panel follows the same PAGE_SIZE=5 and pagination rules as Section 8.
 
 ---
 
+## Documented exceptions summary
+
+These raw CSS values are required and have no Spark token equivalent. Use them
+exactly as written.
+
+| Value           | Property                     | Reason                                                               |
+| --------------- | ---------------------------- | -------------------------------------------------------------------- |
+| `minWidth: 130` | ActionDropdown container Box | Prevents dropdown collapse on narrow content; no Spark minWidth prop |
+
+---
+
 ## Do NOTs
 
 - NEVER apply list-page spacing to a detail page — outer wrapper uses
@@ -347,12 +378,44 @@ tab panel follows the same PAGE_SIZE=5 and pagination rules as Section 8.
 - 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 surface modal errors as page-level Alerts — see
+  `node_modules/@spark-web/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`
+  `node_modules/@spark-web/tabs/CLAUDE.md`
 - NEVER use `Container` as the outer page wrapper
+
+---
+
+## Validation checklist
+
+Run before marking any detail-page task complete and fix every violation; the
+uplift protocol in `node_modules/@spark-web/design-system/CLAUDE.md` runs this
+list PASS/FAIL against existing pages.
+
+1. Outer wrapper is
+   `Stack height="full" paddingX="xlarge" paddingY="xxlarge" gap="xlarge"` — not
+   list-page spacing, not Container.
+2. Header: `Heading level="1"` first, `Badge` after it; ActionDropdown only when
+   `actions.length > 0`; no inline action buttons in the header.
+3. Dropdown action order: non-destructive → restore-type → critical destructive
+   last; permanently unavailable actions hidden, temporarily unavailable actions
+   disabled.
+4. Destructive actions open a ContentDialog modal; direct actions surface
+   feedback via the page-level Alert between header and content — modal errors
+   render inside the modal, never as page-level Alerts.
+5. All modals declared in JSX, controlled by a single `openModal` union state.
+6. Content is `Columns template={[1, 1]} gap="xlarge" collapseBelow="desktop"`.
+7. Every content section is wrapped in a SectionCard (or the documented
+   consumer-overlay equivalent); conditionally hidden sections return `null`.
+8. Section tables use `PAGE_SIZE = 5`; pagination only when `total > PAGE_SIZE`;
+   page resets when the record context changes.
+9. Tabs inside SectionCard use the internal-admin background override per
+   `node_modules/@spark-web/tabs/CLAUDE.md`.
+10. No raw CSS beyond the Documented exceptions table; every component is
+    `@spark-web/*` or an explicit consumer-overlay substitute; gaps flagged with
+    `// COMPONENT GAP:`.