@spark-web/design-system 5.1.7 → 5.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spark-web/design-system",
-  "version": "5.1.7",
+  "version": "5.1.9",
   "license": "MIT",
   "main": "dist/spark-web-design-system.cjs.js",
   "module": "dist/spark-web-design-system.esm.js",
@@ -17,10 +17,10 @@
     "@spark-web/analytics": "5.1.0",
     "@spark-web/badge": "^5.1.1",
     "@spark-web/box": "6.0.1",
-    "@spark-web/button": "5.6.1",
+    "@spark-web/button": "5.7.0",
     "@spark-web/checkbox": "5.1.2",
     "@spark-web/columns": "5.1.1",
-    "@spark-web/combobox": "6.1.0",
+    "@spark-web/combobox": "6.2.0",
     "@spark-web/container": "5.1.1",
     "@spark-web/control-label": "5.1.0",
     "@spark-web/core": "5.2.0",
@@ -44,9 +44,9 @@
     "@spark-web/multi-select": "6.0.2",
     "@spark-web/nav-link": "5.1.0",
     "@spark-web/next-utils": "5.1.0",
-    "@spark-web/page-header": "1.0.0",
+    "@spark-web/page-header": "2.0.0",
     "@spark-web/password-input": "6.0.0",
-    "@spark-web/portal-table": "^1.0.1",
+    "@spark-web/portal-table": "^2.0.0",
     "@spark-web/radio": "5.3.1",
     "@spark-web/row": "5.1.1",
     "@spark-web/section-card": "0.1.0",

package/patterns/internal-admin/CLAUDE.md

@@ -105,6 +105,35 @@ Spark Web theme.
 
 ---
 
+## Destructive-action caution alert
+
+When a form control triggers a destructive or irreversible side-effect (e.g.
+toggling off an authority contact, revoking access), show an
+`Alert tone="caution"` **below** the control that caused the change — not above
+it. The alert appears only while the destructive state is active, and disappears
+when the user reverses the action (e.g. re-toggles the item back on).
+
+Place the alert after the controls so the user sees the change they made before
+the warning. Showing it above shifts the layout downward and pushes the controls
+away from where the user just clicked.
+
+---
+
+## Button size
+
+Internal-admin surfaces are dense, so the compact `size="small"` button (32px
+tall) is permitted here — use it for inline row actions, table toolbars, and
+other tightly-packed action clusters where the default `medium` button would
+crowd the layout.
+
+Use `size="small"` only where density genuinely requires it. Page-level primary
+actions (page headers, form submit/cancel) stay at the default `medium`. Never
+mix `small` and `medium` buttons within the same action group — pick one size
+per cluster. The `small` size is scoped to internal-admin; do not use it on
+vendor-admin or public surfaces.
+
+---
+
 ## Rules that update as the system grows
 
 When a new pattern or component is added to the internal admin surface, update

package/patterns/internal-admin/portal-hub.md

@@ -191,29 +191,111 @@ Two parts:
 
 Each row is a bordered card wrapping a space-between flex row, with the Switch's
 accessible name supplied via `aria-label` (so the name isn't rendered twice;
-target a row with `getByRole('switch', { name })`):
+target a row with `getByRole('switch', { name })`).
+
+### Row content
+
+Each row's children follow a consistent layout: a label stack on the left and an
+optional `Switch` on the right. The label stack contains the item name and an
+optional description line (`Text size="small" tone="muted"`) providing context
+such as the item's current status or effective date:
+
+```tsx
+<ToggleRow variant="active">
+  <Stack gap="small">
+    <Text>{item.name}</Text>
+    <Text size="small" tone="muted">
+      Current authority contact
+    </Text>
+  </Stack>
+  <Switch
+    aria-label={item.name}
+    checked
+    onCheckedChange={() => toggle(item.id)}
+  >
+    {''}
+  </Switch>
+</ToggleRow>
+```
+
+The description is optional — when no secondary line is needed, drop the `Stack`
+wrapper and render a single `<Text>{item.name}</Text>` directly as the left-side
+child of `ToggleRow`.
+
+### Row variants
+
+A toggle row has three visual variants. Use a reusable `ToggleRow` component
+(see Reference implementation below) to encapsulate these — never hand-write the
+border/background per call site.
+
+**Default** — standard field border, surface background. Used when the switch is
+off (item not currently active):
 
 ```tsx
-<Box border="field" borderRadius="medium" padding="medium">
+<Box border="field" borderRadius="medium" padding="medium" background="surface">
   <Box
     display="flex"
     alignItems="center"
     justifyContent="spaceBetween"
     gap="medium"
   >
-    <Text>{item.name}</Text>
-    <Switch
-      aria-label={item.name}
-      checked={value.includes(item.id)}
-      onCheckedChange={() => toggle(item.id)}
-    >
-      {''}
-    </Switch>
+    {children}
   </Box>
 </Box>
 ```
 
-Keep the toggle field consistent with the selection:
+**Active** — primary border with a green tint background. Used when the switch
+is on (item currently active):
+
+```tsx
+<Box
+  border="primary"
+  borderRadius="medium"
+  padding="medium"
+  background="primaryLow"
+>
+  <Box
+    display="flex"
+    alignItems="center"
+    justifyContent="spaceBetween"
+    gap="medium"
+  >
+    {children}
+  </Box>
+</Box>
+```
+
+**Ended** — field border, reduced opacity, no switch. Used for historical items
+that can no longer be changed (e.g. an authority contact whose term has ended).
+Show these as read-only rows alongside active toggles when the modal displays
+history for context:
+
+```tsx
+<Box
+  border="field"
+  borderRadius="medium"
+  padding="medium"
+  background="surface"
+  opacity={0.6}
+>
+  <Box
+    display="flex"
+    alignItems="center"
+    justifyContent="spaceBetween"
+    gap="medium"
+  >
+    {children}
+  </Box>
+</Box>
+```
+
+**Important:** always provide a `background` value (even `"surface"` for
+non-active variants) so the Box's internal `BackgroundProvider` stays mounted
+across variant changes — toggling between `background={undefined}` and a value
+unmounts the provider and recreates the subtree, which breaks Switch state in
+tests and can cause flicker.
+
+### Keeping the toggle field consistent
 
 - **Prune on change** — when an item is deselected (or an upstream condition
   turns the section off), drop its id from the toggle field. Do this in the
@@ -222,10 +304,25 @@ Keep the toggle field consistent with the selection:
   `[{ id, <flag>: onIds.includes(id) }]` in a single helper so the field's wire
   shape lives in one spot.
 
-Reference implementation — Authority Contacts on the Create/Edit vendor-user
-flows:
+### Reference implementation
+
+> **Note:** paths below are in the **portal-hub** consumer repo
+> (`brighte-labs/portal-hub`), not this repository.
+
+`ToggleRow` — a reusable row container at
+`apps/admin-portal/src/components/ToggleRow/ToggleRow.tsx` that accepts a
+`variant` prop (`'default' | 'active' | 'ended'`) and renders the correct
+border/background/opacity combination using only Spark Box tokens. Children are
+placed inside the inner flex Box.
 
-- `apps/admin-portal/src/components/AuthorityContactToggleList` — the row list
+Usage in Authority Contacts flows (portal-hub):
+
+- **Edit AC modal** (vendor Overview) —
+  `apps/admin-portal/src/pages/Vendors/VendorDetail/Overview/EditAuthorityContactsModal.tsx`
+  — active contacts get `variant="active"` with a Switch, ended contacts get
+  `variant="ended"` with no Switch.
+- **Create/Edit vendor-user** —
+  `apps/admin-portal/src/components/AuthorityContactToggleList` — the row list
   (props: `name`, `control`, `vendors: { id; name }[]`, optional
   `label`/`description`/`rules`).
 - `apps/admin-portal/src/utils/authorityContact` → `buildVendorAcPayload` —
@@ -233,14 +330,14 @@ flows:
 - `apps/admin-portal/src/hooks/useAuthorityContactSync` — prunes the field on
   role/selection change.
 
-Do NOTs (portal-hub):
+### Do NOTs (portal-hub)
 
 - NEVER pass raw CSS to Spark `Box` layout props — they take token KEYS:
   `justifyContent="spaceBetween"` (NOT `"space-between"`),
   `alignItems`=`start|center|end|stretch`. An unrecognised value is silently
   dropped and the row falls back to `flex-start` (the switch clumps next to the
   label instead of aligning right).
-- NEVER render a toggle row for an item that can't be changed in the current
-  flow — show those as read-only `Badge`s instead.
+- NEVER hand-write border/background per toggle row — use the `ToggleRow`
+  component with the appropriate `variant`.
 - NEVER put visibility/eligibility logic inside the row list — the consumer
   gates it and owns pruning the field.