@spark-web/design-system 5.1.6 → 5.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spark-web/design-system",
-  "version": "5.1.6",
+  "version": "5.1.8",
   "license": "MIT",
   "main": "dist/spark-web-design-system.cjs.js",
   "module": "dist/spark-web-design-system.esm.js",
@@ -20,7 +20,7 @@
     "@spark-web/button": "5.6.1",
     "@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",

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

@@ -163,3 +163,84 @@ Props used by the patterns:
 
 This is a confirmed COMPONENT GAP — no `@spark-web` pagination component exists
 yet. Until one ships, every consumer supplies its own pagination component.
+
+---
+
+## Multi-select with per-item toggle rows
+
+When a multi-select picks N items and each selected item also needs its own
+on/off flag, pair the selector with a list of **toggle rows generated from the
+current selection** — one bordered row per item, label on the left and an
+`@spark-web/switch` `Switch` on the right. The toggle list binds to a
+react-hook-form field whose value is a `string[]` of the IDs currently switched
+on.
+
+Use it when a per-item boolean accompanies a multi-select choice (e.g. flagging
+some of the selected vendors as Authority Contacts). For a single form-wide
+boolean use `ToggleField`; for choosing items with no per-item flag, the
+multi-select alone is enough.
+
+Two parts:
+
+- **Selector** — `ComboboxField isMulti` or `MultiSelectField` from
+  `@brighte/ui-components` (never `@spark-web/multi-select` directly — see
+  Filter fields above). Its value is the set of selected items.
+- **Toggle rows** — derive `{ id, name }[]` from the current selection and
+  render one row each, bound to a separate `string[]` field of the "on" IDs.
+  Render nothing when the selection is empty.
+
+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 })`):
+
+```tsx
+<Box border="field" borderRadius="medium" padding="medium">
+  <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>
+  </Box>
+</Box>
+```
+
+Keep the toggle field consistent with the selection:
+
+- **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
+  consumer (a small `useEffect`/watch) and keep the row list presentational.
+- **Shape the payload in one place** — map `(selectedIds, onIds)` →
+  `[{ 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:
+
+- `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` —
+  payload shaping.
+- `apps/admin-portal/src/hooks/useAuthorityContactSync` — prunes the field on
+  role/selection change.
+
+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 put visibility/eligibility logic inside the row list — the consumer
+  gates it and owns pruning the field.