pixelize-design-library 2.4.2-beta.67 → 2.4.2-beta.68

package/CHANGELOG.md

@@ -13,11 +13,15 @@ line below names its issue number.
 
 ## [Unreleased] — 2.4.2-beta.x
 
-The theme-tokens/dark-mode line. Still in beta; the breaking items below land together in the
-next major.
+The theme-tokens/dark-mode line. Every entry below has shipped in a `2.4.2-beta.N` prerelease, the latest
+being `2.4.2-beta.67` (the `beta` dist-tag); betas carry no per-version headings, and "Unreleased" means not yet in
+a stable release. The breaking items below land together in the next major.
 
 ### Added
 
+- **`Select` Playground gains `native` and `variant` controls.** The `/select` demo page can now switch between native and popup
+  mode and between the four native variants, and its native examples keep the option you pick.
+
 - **Development warning for an unthemed `colorScheme`.** `Tag` (dot), `RadioButton` and every style that resolves a scale
   by name now log one `console.warn` per unknown name outside production, then fall back exactly as before (gray, or
   primary for `RadioButton`). Nothing throws and production is silent.
@@ -428,6 +432,12 @@ next major.
 - **Repo tooling, no package change.** `scripts/verify-consumers.sh` now covers `lfour/frontend`, finds consumers from a git
   worktree (`CONSUMERS_ROOT`), writes nothing in a consumer, and exits non-zero when nothing was compared or `tsc` rejected
   its own config, instead of printing a clean pass.
+- **`Select` popup rows: `renderOptionEnd`, `optionAction` and `checkPlacement`.** `renderOptionEnd(option, state)` puts
+  non-interactive content (a badge) between the row and its check. `optionAction={{ icon, label, onAction }}` adds one
+  pointer-only, `aria-hidden` row button whose click calls `onAction(option)` and never selects the row, which a button
+  placed inside `renderOption` could not do (it bubbled to the row and failed axe `nested-interactive`).
+  `checkPlacement="start"` moves the single-select check to the leading column the multi checkbox uses. Omitted, the
+  output is exactly as before.
 
 ### Changed
 
@@ -562,6 +572,46 @@ next major.
 
 ### Changed (visual)
 
+- **`OrgSwitcher` rows match the `Select` popup (screenshots pending).** Rows take the option radius and a 4px side inset, the
+  active org gets the selected fill (hover and focus on it the stacked rung), keyboard focus draws the neutral 1px inset ring
+  instead of the browser outline, the name weight is 500 for the active org and 400 otherwise (was 600/500), and names and roles
+  use `Select`'s ink ladder (dark unchanged). Props, ids and ARIA are unchanged.
+- **`SelectSearch` rows match the `Select` popup (screenshots pending).** The keyboard-focused row (real DOM focus, `:focus-visible`
+  only) draws the neutral 1px inset ring instead of the browser's outline; a reopened single selection gets the selected fill,
+  and hover or focus on it the stacked rung. Light labels and `email` lines use `Select`'s neutral ink ladder (dark unchanged).
+  Uncontrolled model, multi's removal of picked options, ids and ARIA are unchanged.
+- **`SearchSelect` rows match the `Select` popup (screenshots pending).** Checked or selected rows get the selected fill, the
+  cursor on a selected row the stacked rung, and Arrow/Home/End draw the same neutral 1px inset ring (also on Select All and
+  Add New); the mouse clears it. Labels use `Select`'s neutral ink ladder in light (dark unchanged). Selected-label weight,
+  radius, `activeIndex` sentinels, `insideSelect` and every prop, id and ARIA attribute are unchanged.
+- **`Select` popup, light: the selected row gets a fill (screenshots pending).** Hover stays today's faint brand tint
+  (lavender `#f1edf6`, emerald `#ebefef`). Selected is the next deeper step of the same tint (lavender `#e7e0f0`, emerald
+  `#dde4e4`, about 1.29:1 on the panel) and selected+hover one more (`#dfd6eb`, `#d2dbdb`), so hover, selected and both
+  read as one family and every adjacent pair is at least 1.10:1 (selected vs stacked 1.08:1). Arrow-key navigation now
+  also draws the neutral 1px inset ring in light (`#7b7b7b`, 3:1 on all four fills), because keyboard-on-selected is only
+  1.08:1 from a plain selected row; the mouse never draws it. Multi checked rows get the same fill (checkbox fill stays
+  at least 3.2:1). The text ladder holds on the new fills.
+- **Native `Select` `filled`, `flushed` and `unstyled` variants are themed.** They had no keyboard focus indicator, `filled` had
+  square corners at `xs`/`sm`, and `flushed` rested on a 1.2:1 hairline. Each now shows the brand border plus glow on `:focus-visible`
+  (`unstyled` gets the two-tone ring), `filled`/`unstyled` use the field radius, and `flushed` uses the outline border rung. `outline` is unchanged.
+
+- **`Select` popup layout polish, light and dark (screenshots pending).** Fills are unchanged. The single-select check sits
+  in a reserved 16px slot so long labels no longer shift by the check's width; Select All has a hairline rule under it; the
+  list is padded by the row inset (6px at `sm`, was 4px) so rows sit evenly from the panel edge; the scrolling list shows top
+  and bottom scroll shadows (`scrollShadowStylesVertical`, a vertical twin of the Table helper); and a disabled row no longer
+  dims as a whole (was opacity 0.4), so its cursor fill and the dark keyboard ring stay visible: light sets its content to a
+  solid `#868686` (3.6:1), dark dims the content to 0.55.
+- **`Select` popup, light: row text is one neutral grey ladder, identical on all nine brands (screenshots pending).** The
+  brand-derived `text[700]`/`text[900]`/`textMuted` read as soft purple, green or brown. Now (built with `neutralStep` from
+  the panel, no mode argument) the label is `#323232` (12.8:1), the selected label `#242424` at weight 500 beside its
+  check, the description `#595959` (7:1), and the filter input's placeholder `#757575` (4.6:1, filter only; every other
+  field keeps `placeholderInk`). Dark text is unchanged, and `Menu`, `DropDown`, `SearchSelect`, `SelectSearch`,
+  `OrgSwitcher` and `CompactSelect` keep reading `optionRowInk`, so their light rows stay brand-tinted.
+- **`Select` popup, dark: selected, hover, stacked and keyboard states are four neutral rungs (screenshots pending).** Hover
+  stays `#363636`; the selected row now fills `#3d3d3d`, hovering it `#424242`, and arrow-key navigation draws a 1px
+  `#8d8d8d` inset ring (never under the mouse), identical on all nine brands and derived from the panel,
+  not a mode. The description line is lifted against the busiest rung. Light follows in the entry below. `SelectPopup` only; `listRowBackgrounds`, `optionRowFill` and the
+  other readers of the shared helpers are untouched.
 - **`Table` rows with `onRowClick` show a keyboard focus ring.** A focused row draws the library's two-tone ring inset around its
   cells (sticky cells included), on `:focus-visible` only, so a mouse click draws nothing. It clears 3:1 on every row plane in light and dark.
 
@@ -813,6 +863,13 @@ next major.
 
 ### Fixed
 
+- **`SearchSelect` Select All row now highlights under the mouse.** Only the keyboard reached it before; hover filled every other row.
+- **Native `Select` without a `value` snapped back to the placeholder, and `defaultValue` did nothing.** A native `Select` that never
+  received `value` was pinned to `""`, so picking an option reverted at once unless `onChange` stored it. It now keeps its own
+  selection, seeded by `defaultValue`, until a defined `value` is passed; after that `value` controls it as before.
+
+- **`OrgSwitcher`'s open popup now has an accessible name.** The dialog carried no name (axe `aria-dialog-name`, serious); it
+  now reads the existing `ariaLabel` prop ("Switch organization" by default). No new prop, no DOM id changes.
 - **`FileUploader` revokes its `blob:` preview URLs on unmount.** Images still listed when the component unmounted kept their
   object URLs alive for the life of the page; removal, `maxFiles` overflow and `maxTotalSize` rejection already revoked.
 - **`SearchSelect`'s "Clear all" button no longer opens the menu.** Its click bubbled to the control, so Enter, Space or a
@@ -1358,8 +1415,8 @@ than copied here where it can drift.
 
 Get the current number from `scripts/verify-consumers.sh check`, which typechecks every consumer
 against a real build — **do not estimate it by grep.** A grep conflates names that were removed
-outright (`ChakraModal*`, `CardBody`, `ModalContent`, the `Slider*` sub-parts, `TabList`/`TabPanel`)
-with names that still resolve but narrowed (`Avatar`, `AvatarGroup`, `Tabs`, `RangeSlider`), and
+outright (`ChakraModal*`, `CardBody`, `ModalContent`, the `Slider*` sub-parts)
+with names that still resolve but narrowed (`Avatar`, `AvatarGroup`, `Tabs`, `Tab`, `TabList`, `TabPanel`, `TabPanels`, `RangeSlider`), and
 overcounts badly — that mistake has already been made twice in this repo's own planning docs.
 
 Layout and composition primitives with no owned equivalent stay exported: `Box`, `Flex`, `Stack`,

package/COMPONENT-GOTCHAS.md

@@ -122,6 +122,12 @@ fully-React popup — searchable, `isMulti` with chips, grouped options, `isClea
 `isMulti` always forces the popup — there is no native multi-select — and dev-warns if you
 also passed `native`.
 
+**Native `Select` is uncontrolled until you pass a `value`.** With no `value` it keeps its own selection
+(seeded by `defaultValue`), so `onChange={() => {}}` still lets the user pick. Once a defined `value` has been
+passed it is controlled: an `onChange` that does not store the value snaps the field back, and `value` going
+back to `undefined` shows the placeholder, not the earlier pick. `variant` (`outline`, `filled`, `flushed`,
+`unstyled`) is native-only and inert in popup mode.
+
 **Only `SelectV2` is `@deprecated`. None was deleted; every existing call site still works.**
 
 | Deprecated | Status | Migration |
@@ -135,11 +141,11 @@ also passed `native`.
 
 | Doing | Component |
 | --- | --- |
-| Typing free-text tags (e.g. email addresses), no options list | `MultiSelect` — despite the name there is nothing to pick from; see gotcha below |
+| Typing free-text tags, no options list | `TagInput` (any text, your own `validate`). `MultiSelect` is the email-only variant — despite the name there is nothing to pick from; see its gotcha below |
 | Choosing which fields/columns to include, in a modal, from a checkbox grid | `FieldSelectModal` |
 
-`onChange` is the change prop on `Select` and `SelectV2` (`SearchSelect.onSelect` is the one it
-actually uses; its `onChange` is passed almost nowhere). `Search` uses `onSearch`/`onClear`
+`onChange` is the change prop on `Select`, `SelectV2` and `SearchSelect` (`SearchSelect.onSelect` is
+`@deprecated`, same payload; `onChange` wins when both are set). `Search` uses `onSearch`/`onClear`
 (`onclose` is `@deprecated`).
 
 ### `Dropdown`'s `handleOptionSelect` takes TWO arguments and TypeScript will not tell you
@@ -148,8 +154,8 @@ The prop is `(id, label) => void`. TypeScript accepts a one-argument function an
 two-argument one is expected, so `handleOptionSelect={handleSelect}` where `handleSelect`
 is `(id: string | number) => void` compiles cleanly and silently never receives `label`.
 
-This is live in **10 call sites today** across crm-frontend and commerce — every one of them
-a bare function reference rather than an inline arrow.
+Call sites across crm-frontend and commerce hit this, every one a bare function reference rather
+than an inline arrow.
 
 **Apply:** pass an inline arrow (`(id, label) => handleSelect(id, label)`) so the arity is
 visible at the call site, or declare the handler with both parameters. Grep for
@@ -273,7 +279,7 @@ Four components open a file, and only one of them is the general answer.
 | Always-visible inline PDF panel in the page flow | `PdfViewer` | Non-modal, PDF-only, small open/download toolbar; `getBlob` for files behind auth |
 | Crop/preview a user avatar | `ProfilePhotoViewer` | Avatar-specific, not a general file viewer |
 
-`PdfViewer` shows a fallback when the browser cannot render a PDF inline (`navigator.pdfViewerEnabled === false`) or `getBlob` rejects; `FilePreview`'s `"pdf"` kind renders a bare `<embed type="application/pdf">` and tells you nothing. `MediaViewer` also handles it: formats a browser cannot decode (`.avi`, `.mkv`, `.m3u8`, `.heic`, `.tiff`) render an icon and a file-type chip with a download action instead of a blank frame.
+`PdfViewer` shows a fallback when the browser cannot render a PDF inline (`navigator.pdfViewerEnabled === false`) or `getBlob` rejects; `FilePreview`'s `"pdf"` kind renders a bare `<embed type="application/pdf">` and tells you nothing. `MediaViewer` also handles it: formats a browser cannot decode (`.avi`, `.mkv`, `.m3u8`, `.heic`, `.heif`) render an icon and a file-type chip with a download action instead of a blank frame.
 
 `MediaViewer.labels` takes a `Partial<MediaViewerLabels>` — that type and `defaultMediaViewerLabels` are both exported from the package root, so you can merge rather than restate every string.
 
@@ -374,9 +380,9 @@ The wrapper is deliberately not a button; make the custom component a button, or
 
 | Component | beta.43 → beta.44 | Restore the old look |
 | --- | --- | --- |
-| Fields, selects, buttons (`Button`, `TextInput`, `InputTextArea`, `NumberInput`, DatePicker family, `Select`, `SelectV2`, `SearchSelect`, `SelectSearch`, `Search`, `Dropdown`, `SegmentedControl`) | Default size `md` → `sm` (38px). One scale for all: xs 24 / sm 38 / md 40 / lg 48 — the same height in every field, select and button. `TimePicker` has no `size` (fixed `sm`); `SegmentedControl` has no `xs`. **Since decoupled** — fields/selects now read `CONTROL_SIZES` (xs 24 / sm 38 / md 40 / lg 48 at the time of the split; xs later raised to 32px), `Button`/`SegmentedControl`/`Tabs`/`TableToggle`/`Dropdown`'s trigger read the separate `BUTTON_SIZES` (xs 24 / sm 32 / md 40 / lg 48, back to pre-regression) — see the gotcha below | `size="md"` |
+| Fields, selects, buttons (`Button`, `TextInput`, `InputTextArea`, `NumberInput`, DatePicker family, `Select`, `SelectV2`, `SearchSelect`, `SelectSearch`, `Search`, `Dropdown`, `SegmentedControl`) | Default size `md` → `sm`. Fields/selects read `CONTROL_SIZES` (xs 32 / sm 38 / md 40 / lg 48); `Button`/`SegmentedControl`/`Tabs`/`TableToggle`/`Dropdown`'s trigger read the separate `BUTTON_SIZES` (xs 24 / sm 32 / md 40 / lg 48). `SegmentedControl` has no `xs` — see the gotcha below | `size="md"` |
 | `Button` | Text one step smaller (sm 14→13px, md 16→14, lg 18→16). Busy = spinner only, width kept (was "Loading" + spinner). Outline: 1px border, hover is a tint, not a fill | `loadingText="Loading"` |
-| `Tag` | `solid`/`md` → `subtle`/`sm`. Hover + pointer only with `onTagClick`; `maxW` truncates with the full text as a title. Exact heights 20/24/28/32, weight 500, 1px inset ring (never adds height); subtle is a light tint with ink ≥ 6.5:1 | `variant="solid" size="md"` |
+| `Tag` | `solid`/`md` → `subtle`/`sm`. Hover + pointer only with `onTagClick`; `maxW` truncates with the full text as a title. Exact heights 20/24/28/32, weight 500, 1px inset ring (never adds height); subtle is a light tint with ink ≥ 6:1 | `variant="solid" size="md"` |
 | `resolveSoftTone` | `bg`/`border` are now translucent (alpha hex) — composite onto the surface before `contrastRatio`; optional 3rd `surface` arg; adds `hoverBg`/`activeBg`. Badge/Alert/Toaster/EmptyState follow | — |
 | `resolveFilledSurface` | Still white-first; when a white-labelled fill would vanish on the canvas (zinc dark primary) it falls back to a light fill with dark ink. Takes `background` in `colors` now | — |
 | `Checkbox` / `RadioButton` | Box 16/20/24 → 14/16/20; label 14px; 1px border; one fill rung for every `colorScheme`. **`RadioButton colorScheme` now applies** (was always primary) | — |
@@ -393,7 +399,7 @@ The wrapper is deliberately not a button; make the custom component a button, or
 | `Button` | Icon-only buttons are square | — |
 | `ProgressBar` | Fill lifted to ≥ 3:1 on its track — green/orange/blue/cyan are visibly darker in light mode | — |
 | `PhoneNumberInput` | Default `size` `md` → `sm`, so it matches the `TextInput`s beside it | `size="md"` |
-| `PhoneNumberInput` / `PinInput` / `NoteTextArea` | `ref` now attaches; labels bound; PIN digits grouped and named | — |
+| `PhoneNumberInput` / `PinInput` / `NoteTextArea` | `ref` now attaches on `PhoneNumberInput` and `NoteTextArea` (`PinInput` takes none); labels bound; PIN digits grouped and named | — |
 | `RangeDatePicker` | Outside click keeps a fully picked range (was discarded) | — |
 | `FilePreview` / `ContactForm` | Radius `2xl` → `xl` | — |
 | `Avatar` / `Timeline` / `Table` | Generated avatar fills now guarantee ≥ 4.5:1 initials (a name may get a different shade); Timeline rail lifted to 3:1; Table status/filter chips use the soft recipe; stray radii → `lg`/`xl`/`full` | — |
@@ -405,11 +411,11 @@ The wrapper is deliberately not a button; make the custom component a button, or
 | `DatePicker` (no `pickerType`) | Inference is case-sensitive: `MM` is month, `mm` minutes. `dd/MM/yyyy` was misread as date+time and showed time selects; it is now date-only | `pickerType="datetime"` |
 | `EmptyState` | Title is an `h3`; image is decorative (`alt=""`, was the title) | `titleAs`, `imageAlt` |
 | Theme `Badge` / `Card` / field labels | Badge: pill, no uppercase, default `sm`. Card: default variant `elevated` (borderless, `shadows.card`). Label colour `text[700]`; helper/error row 12px | `size`/`variant` props |
-| `Header` | `position: sticky; top: 0`, z-index `sticky` (1100, was 1000); `rightSlot` mounts once, not per layout | — |
+| `Header` | `position: sticky; top: 0`, z-index `sticky` (1100); `rightSlot` mounts once, not per layout | — |
 | `Table` | Radius `xl`; row height 32/40/52 by density; filter button is named "Filter {label}" (tests querying "Search" break); client pagination resets to page 1 when `data.length` changes | — |
 | `KanbanBoard` | `height`/`maxH` props replace the clipping wrapper; `height="100%"` needs a parent with a definite height | — |
 | `ProfileCard` / `SideBar` | `variant="outlein"` now draws an outline; header divider 1px `boxborder[200]` / mobile backdrop uses the shared scrim | — |
-| `SideBar` | Scroll-container and submenu ids are generated (`useId`) — `#sidebar-scroll-container` / `#submenu-<label>` no longer exist; row heights fixed 20/32/48; count badges use soft tone | — |
+| `SideBar` | Scroll-container and submenu ids are generated (`useId`) — `#sidebar-scroll-container` / `#submenu-<label>` no longer exist; rail rows 32px (44px in the mobile overlay), submenu rows 28px; count badges use soft tone | — |
 | `ToggleSwitch` | No `aria-required` on the switch (invalid for `role=switch`); `isRequired` still shows `*` | — |
 | `KanbanBoard` / `PdfViewer` / `UserDetails` | Cards, drag handles and toolbar links get accessible names; scroll panels are focusable regions; `UserDetails` badges 12px | — |
 | `NumberInput` / `FileUpload` | Steppers exactly half the field height; drop-zone border 1px (was 2px) | — |
@@ -421,7 +427,7 @@ The wrapper is deliberately not a button; make the custom component a button, or
 | `Tag` | Label line-height 1.45 so descenders (`p`, `g`, `y`) are no longer clipped by the ellipsis overflow | — |
 | `Toaster` | `error` toasts announce assertively (`role="alert"`); status icons have a text equivalent | — |
 | `FeedbackForm` | Built on `TextInput`/`InputTextArea`/`RadioButtonGroup`; required fields show `*` in the label | — |
-| `PinInput` | `size` now works (square cells 24 / 38 / 40 / 48, default `sm`) — it was silently ignored | `size="md"` |
+| `PinInput` | `size` now works (square cells 32 / 38 / 40 / 48 today, default `sm`) — it was silently ignored | `size="md"` |
 | `Tag` | New `leadingIcon` (decorative, before the label) and `isDisabled` (sets `aria-disabled` + native `disabled` on the clickable/remove buttons, so they leave the tab order — not just dimmed) | — |
 | `ToolTip` | Defaults a Popper `preventOverflow` padding of 8px, so a bubble near the right edge no longer overhangs by a subpixel and raises page scrollbars. A caller-supplied `preventOverflow` modifier still wins | pass your own `modifiers` |
 | `Table` / `KanbanBoard` | Column sort buttons and draggable cards now show the library focus ring on keyboard focus (was an opacity flicker / the browser default outline). Kanban card wrappers render as Chakra `Box`; keyboard drag (Space, arrows, Space) is unchanged | — |
@@ -527,7 +533,7 @@ never mutate what they return.
 ### Reduced motion is per component unless the app passes `reducedMotion="global"`
 
 The library's own animations honour `prefers-reduced-motion` one component at a time. For one
-document-wide rule, pass `reducedMotion="global"` to `PixelizeThemeProvider` (or `createBrandTheme`);
+document-wide rule, pass `reducedMotion="global"` to `PixelizeThemeProvider`;
 transitions and animations then collapse to one near-instant pass. Add `pz-motion-keep`
 (`MOTION_KEEP_CLASS`) to any loop that is essential feedback; Chakra spinners and progress bars are
 kept automatically.
@@ -568,8 +574,8 @@ For an accent icon on the gradient, use `resolved.ink` unless the accent clears
 
 All three match children by exact type (`child.type === XHeader/XBody/XFooter`) and render only
 those matches — nothing else in `children` is ever read. A sibling among the slots (a nested
-`Modal`, `AlertDialog`, a confirm dialog, a live region) silently never mounts; `Drawer` and `Modal`
-`ProfileCard` now warn once per dropped child type in development. All three
+`Modal`, `AlertDialog`, a confirm dialog, a live region) silently never mounts; dev builds of all three
+warn once per dropped child type. All three
 look through `<>...</>` Fragments around a slot, at any depth (so `<>{cond && <DrawerFooter>...}</>` still renders)
 and spread styling props (`padding`, `borderBottom`, `sx`, …) from the matched slot onto the real
 header/body/footer — any other wrapper element still drops the slot.
@@ -616,14 +622,14 @@ green. Pass `onClick` for a clickable card (it renders its own `<button>`); neve
 
 ### `CircularProgress` `tone="info"` is the brand primary, not blue
 
-Unlike `Tag` and `StatCard`, where `info` is blue, the default `tone="info"` here paints the brand
+Unlike `Tag` (`tone`) and `StatCard` (`iconTone`), where `info` is blue, the default `tone="info"` here paints the brand
 primary scale. `aria-label` is required — the ring has no visible caption.
 
 ### `TextInput variant="filled"` has no border, only a fill that barely separates it
 
 `filled` draws no resting border (`borderColor: "transparent"`), so the field's edge is the fill
-alone. That fill measures 1.01-1.06:1 against a card in light mode on the nine brands, well under
-the 3:1 that WCAG 1.4.11 asks of a control boundary, and about 1.19:1 in dark mode. The focus ring
+alone. That fill sits well under
+the 3:1 that WCAG 1.4.11 asks of a control boundary, in light and dark. The focus ring
 and the invalid border still show, but a resting empty field can be hard to find.
 
 **Apply:** use the default `variant="outline"` for any form a person must find and fill in. Keep
@@ -680,6 +686,13 @@ server there.
 
 **Apply:** a client-side table that looked like it had "no matches" past page 1 now finds them.
 
+### A button inside a `Select` `renderOption` row selects the row — use `optionAction`
+
+`renderOption` output sits inside `role="option"`, whose click selects. A `<button>` you place in it bubbles to the row
+(and fails axe `nested-interactive`, since options are presentational children). Pass `optionAction={{ icon, label, onAction }}`
+instead: it renders a pointer-only, `aria-hidden` control that calls `onAction(option)` and stops the click. It is not
+focusable, so give keyboard users the same action elsewhere.
+
 ### `Select`'s `onChange` never fires for the built-in placeholder
 
 `Select` resolves the changed value against its `options` list and calls `onChange` only on a hit.
@@ -725,13 +738,13 @@ It decides whether each row gets a chevron, so an inline function re-renders eve
 `row.content` + `isContent` expander (chevron before the checkbox, index-based); both can coexist,
 but only `row.content` still disables grouped virtualisation.
 
-### `error` without `errorMessage` renders the literal word "Error" — and erases `helperText`
+### `error` without `errorMessage` shows no message — and erases `helperText`
 
 Every field that shows validation errors (`TextInput`, `InputTextArea`, `Select`, `MultiSelect`,
 `SelectV2`, `SearchSelect`, `SelectSearch`, `Search`, `Checkbox`, the `DatePicker` variants,
-`PhoneNumberInput`) falls back to the literal word **"Error"** when `error` is `true` but
-`errorMessage` is empty. Worse, `helperText` only renders when `!error` — so the guidance
-disappears exactly when it's needed.
+`PhoneNumberInput`) turns the border red and sets `aria-invalid` when `error` is `true` but renders
+no message when `errorMessage` is empty. Worse, `helperText` only renders when `!error` — so the
+guidance disappears exactly when it's needed, leaving a red field with no text.
 
 **Apply:** never pass `error` without `errorMessage`. Gate `error` on a `touched` flag so a field
 whose defaults arrive asynchronously doesn't open already red.
@@ -758,24 +771,26 @@ receives nothing, and `children` is not type-matched.
 
 ### `ContactForm`'s `apiKey` prop is a POST URL, not an auth token
 
-Despite the name, `apiKey` is passed straight into `fetch(apiKey, { method: "POST" })` as the submit
-endpoint — never sent as a header or credential. A real API key/secret fails silently as an invalid
-URL, surfaced only as a generic "Failed to send message" alert. There's no `headers` prop, so an
-authenticated endpoint can't be reached through this component at all.
+Despite the name, `apiKey` is the fallback submit endpoint: only when no `onSubmit` is given, the form
+does `fetch(apiKey, { method: "POST", headers: { "Content-Type": "application/json" }, body })` — never a
+credential header. With both set, `onSubmit` wins and `apiKey` is never fetched. With neither, submit
+shows an inline "API key missing" alert. A real API key/secret fails as an invalid URL or a non-OK
+response, surfaced only as a generic "Failed to send message" alert, and there is no `headers` prop.
 
-**Apply:** pass the full POST URL, never a token. If the endpoint needs auth headers, proxy through
-your own backend instead.
+**Apply:** pass the full POST URL, never a token. If the endpoint needs auth headers, pass `onSubmit`
+and make the request yourself.
 
 ### `ContactForm` can't tell its parent the submission result
 
-It does its own internal `fetch` and renders its own success/error alert from local state — there is
-no `onSuccess`, `onSubmit`, or `onError` prop (a dead `// onSubmit(formData)` line is the only trace
-one ever existed). A call site can't redirect, toast, or update its own state when the enquiry sends.
-Separately, the email field is validated for format but its "required" check is commented out, so a
-blank email submits successfully with no error shown.
+It renders its own success/error alert from local state and has no `onSuccess` or `onError` prop. The
+only hook is `onSubmit(payload)`, which replaces the `apiKey` fetch: it is awaited, a resolve shows the
+success alert and clears the form, a throw shows "Failed to send message". The `apiKey` path tells the
+parent nothing. Separately, the email field is validated for format but its "required" check is
+commented out, so a blank email submits successfully with no error shown.
 
-**Apply:** if the parent needs to react to success, this component can't provide it. Don't rely on
-`email` being enforced as required — validate it yourself first if that matters.
+**Apply:** to redirect, toast or update state when the enquiry sends, pass `onSubmit` and do it there
+(rethrow to show the failure alert). Don't rely on `email` being enforced as required — validate it
+yourself first if that matters.
 
 ### `VerifyEmailOtp` can't accept alphanumeric codes, and appends "your new Pixel Account"
 
@@ -865,9 +880,9 @@ three color overrides with `showStatus`; don't use `status` to drive dot color.
 Both props are optional, and when neither is provided, submit still falls through to the success
 toast and form reset — validation, spinner, and reset all work end-to-end while the payload is never
 sent or captured anywhere. Separately, `defaultValues` only seeds state at mount (no resync if it
-arrives later from an async fetch), and its toast is Chakra's raw `useToast`, not this library's
-`Toaster` — the same portal issue documented for `Toaster`/`Modal` can silently hide it when this
-form is embedded in a `Modal`.
+arrives later from an async fetch), and its toast comes from `useToaster`, so it throws outside a
+`ToasterProvider` (`PixelizeThemeProvider` and `withTheme` mount one) — the same portal issue
+documented for `Toaster`/`Modal` can still hide the toast when this form is embedded in a `Modal`.
 
 **Apply:** always pass `onSubmit` or `submitUrl` — treat a bare `<FeedbackForm />` as a bug, not a
 minimal valid usage. Key the element to force a remount if `defaultValues` arrives late. Verify the
@@ -875,7 +890,7 @@ toast actually appears if embedding inside a `Modal`.
 
 ### `Checkbox`'s `variant` is a no-op
 
-Typed and accepted, but `Checkbox.styles.ts` defines no `variants` key, so no value changes the
+Typed and accepted (`@deprecated`), but `Checkbox.styles.ts` defines no `variants` key, so no value changes the
 look. (`error` now sets `isInvalid` and links its message — no need to pass both.)
 
 ### `Slider`'s pagination dots can desync from the visible slide
@@ -1106,8 +1121,9 @@ is no longer Chakra's style prop (omitted from the type) — use `p` for a raw v
 `options` must set every axis, or `findVariant` returns `undefined`.
 
 - **`layout="auto"` on `MediaGallery` and `ProductDetails` follows the container, not the window**
-  (560px / 960px). `ProductCard` and `QuickAddSheet` `auto` still read the window; pass `layout` /
-  `quickAddPresentation` explicitly inside a phone-width frame.
+  (560px / 960px of their own width), falling back to the window query only until the first measure.
+  `ProductCard`'s `layout` (`grid`/`list`/`rail`) has no `auto`. `QuickAddSheet`'s `presentation="auto"`
+  (`ProductCard`'s `quickAddPresentation`) reads the window (modal from `48em`); pass it explicitly inside a phone-width frame.
 - **Drawers and modals portal to the window, never into your phone frame.** `ProductCard`'s quick-add
   sheet needs `quickAddPresentation="drawer"` and `quickAddDrawerProps={{ maxW: "390px !important", mx: "auto" }}`
   there; the `!important` is needed because Chakra's slide sets an inline `max-width: 100vw`.
@@ -1157,6 +1173,12 @@ reach it.
 **Apply:** don't depend on `onChange` firing for a repeat pick. There's no supported way to attach
 test hooks or a ref to the trigger.
 
+### `OrgSwitcher`'s popup dialog is named by `ariaLabel`, and its rows follow `Select`'s state ladder
+
+The open `role="dialog"` now has `aria-label={ariaLabel}` (it had none), so a translated app should pass `ariaLabel` in its own
+language; the trigger name still reads `${ariaLabel}, ${org name}`. Rows are 4px inset with the option radius, fill the active org,
+and ring on `:focus-visible` only.
+
 ### `OrgSwitcher display="full"` still squeezes the navbar title on phones — use `display="auto"`
 
 Inside a `NavigationBar` `moreIcon` cluster, a full trigger needs about 88px (avatar + chevron) even
@@ -1171,8 +1193,11 @@ own icon buttons `flexShrink={0}` and let any label truncate.
 
 ### `UpgradeButton`'s gold icon accent silently falls back to the label color on low contrast
 
-The gold accent is only used when it clears AA contrast against both gradient stops; a custom
-`gradient` prop can flip it to the label's own ink color with no signal.
+Two different ratios apply. The label and subtitle ink clears **4.5:1** (AA text) on both gradient stops:
+`resolveGradient` darkens the stops until it does, so a custom `gradient` may paint darker than the
+colors you passed (the built-in variants are pinned per brand and mode in `upgradeButtonInk.test.ts`).
+The gold icon accent only needs **3:1** (non-text) against both of those painted stops; when it misses
+either, the icon silently switches to the label ink. An explicit `iconColor` is used as given, unchecked.
 
 **Apply:** don't assume the icon stays gold with a custom `gradient` — check contrast yourself if the
 gold accent is load-bearing for your design.
@@ -1360,15 +1385,27 @@ lights the Jodit frame while focus is inside it. Tab then walks toolbar, editing
 buttons (`config.statusbar: false` drops those). Inside a table cell Tab and Shift+Tab stay with Jodit (next
 cell, a new row after the last, a new row above the first): arrow out of the table before tabbing away.
 
-### `SelectV2`, `SearchSelect`, and `SelectSearch` all search `option.label` only
+### `SearchSelect` and `SelectSearch` search `option.label` only (so does `Select` unless you widen it)
 
-None of the three checks a rendered secondary field (`option.description`, a custom `view` node,
-`option.email` on a profile row) — typing text that's visibly on-screen in a secondary field returns
-no match.
+Neither checks a rendered secondary field (`option.description`, a custom `view` node, `option.email`
+on a profile row) — typing text that's visibly on-screen in a secondary field returns no match. `Select`
+and `SelectV2` (popup mode) match the label too, until you pass `searchFields={["label","description"]}`
+or a `filterOption(option, query)`.
 
-**Apply:** if a secondary field needs to be searchable, fold it into `option.label` yourself, or
+**Apply:** on `SearchSelect`/`SelectSearch`, fold a secondary field into `option.label` yourself, or
 pre-filter `options` before passing them in.
 
+### `SearchSelect` selected rows are filled now, and the ring is keyboard-only
+
+Checked or selected option rows paint the `Select` selected fill; hover and keyboard cursor step it deeper, and
+Arrow/Home/End add a 1px neutral inset ring (the mouse clears it). A test or screenshot that expects an unfilled selected
+row, or reads the label colour from `text[700]`, now sees the neutral ink ladder in light. Behaviour, ids and ARIA are unchanged.
+
+### `SelectSearch` keyboard focus draws a neutral ring, not the browser outline
+
+Rows are real focus targets; `:focus-visible` now paints the `Select` 1px inset ring (and `outline` stays transparent for forced-colors),
+and a reopened single selection is filled. A visual or E2E test that expects the UA outline on a focused row no longer sees it.
+
 ### `SearchSelect` never virtualizes
 
 Despite the prop name, `virtualization` does nothing — every filtered option renders as a real DOM
@@ -1522,7 +1559,7 @@ identical data renders as a click-toggled accordion on mobile.
 ### `WorkspaceWindow`'s `state="maximized"` is indistinguishable from `"medium"`
 
 The component only branches on `state === "minimized"` — size is always the same fixed constant, and
-`onMedium`/`onMaximize` are accepted callbacks that are never invoked anywhere in the component.
+`onMedium`/`onMaximize` are `@deprecated` callbacks that are never invoked anywhere in the component.
 
 **Apply:** treat `state` as effectively two-valued (open vs. `"minimized"`); don't wire a maximize
 control expecting `onMaximize` to fire.
@@ -1544,7 +1581,7 @@ none of them do anything.
 
 ### `Breadcrumbs`' `isLastChild` prop is accepted but never read
 
-It's declared on the type but omitted from the component's destructure entirely.
+It's declared on the type (`@deprecated`) but omitted from the component's destructure entirely.
 
 **Apply:** don't pass it expecting it to mark or style the final crumb — there's nothing it can do.
 
@@ -1681,12 +1718,13 @@ keeps its `ol` role, so its `aria-label` names the list rather than a region.
 
 **Apply:** pass `aria-label` ("Deal stages") on every read-only `StageProgress` that can overflow.
 
-### `Table`'s `isVisiblity`, `tableSettings`, `handleExportChange`/`exportOptions`/`exportLabel`, and `onColumnFilter` are dead props — now `@deprecated`
+### `Table`'s `isVisiblity`, `tableSettings`, `handleExportChange`/`exportOptions`/`exportLabel`, `onColumnFilter`, `headerBgColor`/`tableBorderColor`, and a column's `isSearch` are dead props — all `@deprecated`
 
 Grepped account-frontend, tickets, crm-frontend, hrms and social-frontend: zero consumers set any of
-these six. All six are now marked `@deprecated` in `TableProps.tsx` rather than removed outright, in
-case an app outside those five repos relies on one. None of these do anything in the current
-implementation, despite being typed on `TableProps` (and some documented on the demo page):
+the `TableProps` ones. Every prop below carries `@deprecated` in `TableProps.tsx` (eight on `TableProps`,
+plus `isSearch` on the column definition `TableHeaderProps`) rather than being removed outright, in case
+an app outside those five repos relies on one. None of them does anything in the current implementation,
+despite being typed (and some documented on the demo page):
 
 - `isVisiblity` — `Table`'s own destructure never lists it, so a consumer's value is dropped. It's
   hardcoded `true` into both `Pagination` call sites regardless, and `Pagination` doesn't read it
@@ -1695,10 +1733,10 @@ implementation, despite being typed on `TableProps` (and some documented on the
 - `tableSettings` (`{filters, filterSelected, onFilterSelection}`) — `Table` passes it to
   `TableSettings`, but `TableSettings`'s function signature never destructures it.
 - `handleExportChange` / `exportOptions` / `exportLabel` — `Table` renders no export UI at all; none
-  of the three are read anywhere, despite `src/Pages/table.tsx` documenting them as if live.
-- `onColumnFilter` — commented out of `Table`'s own destructure (`// onColumnFilter`).
-- `headerBgColor` / `tableBorderColor` — also dead and `@deprecated`; the header paints the
-  variant's own background.
+  of the three are read anywhere.
+- `onColumnFilter` — `Table.tsx` never references it.
+- `headerBgColor` / `tableBorderColor` — the header paints the variant's own background; neither is read.
+- column `isSearch` (on `TableHeaderProps`) — every column gets the filter popover regardless.
 
 **Apply:** don't reach for any of these expecting an effect. Column visibility is driven by
 `isTableSettings` (shows the Settings gear) + `preferences` (server persistence) + the Manage
@@ -1949,7 +1987,8 @@ from `optionRowDescriptionInk(theme.colors)` (exported from the package root) ra
 `listRowBackgrounds(colors).selected` and `.active` sit within 1.02:1 of each other on every brand
 and mode, so a list that fills both the selected row and the hovered row shows two identical fills
 and the user cannot tell which one is chosen. Library option lists paint one fill — the cursor's —
-and mark selection with `optionRowWeight` plus a trailing `Check` in `colors.accentText`.
+and mark selection with `optionRowWeight` plus a trailing `Check` in `colors.accentText`. (`Select`'s own popup
+additionally fills the selected row (a deeper step of the hover tint in light, a neutral rung in dark; not exported); a custom list keeps one fill.)
 
 **Apply:** `bg={optionRowFill(listRowBackgrounds(colors), isActive)}` for an index-driven list, or
 `{...optionRowCursorSx(listRowBackgrounds(colors))}` for rows that take DOM focus; both are exported

package/DESIGN-GUIDE.md

@@ -69,7 +69,7 @@ the four: `<Text textStyle="label">`. The ramp (`TEXT_STYLES`, also a root expor
 
 Chakra size keys only (`xs-minus xs xs-plus sm md lg xl 2xl`) — never `fontSize="14px"`.
 `xs-plus` (13px) is the control size; `xs-minus` (11px) is for chips, counts, keyboard hints and
-overlines only; nothing is smaller. Weights: 400 body, 500 labels, 600 titles, 700 KPI numbers only.
+overlines only; nothing is smaller. Weights: 400 body, 500 labels, 600 titles, 700 KPI numbers and the `title` step only.
 
 **Radius and elevation come from the role, not the scale step.** `RADIUS_ROLE` (root export) names
 the radius a surface plays: `control`, `field`, `tooltip` and `media` 8px · `option` 6px · `card`,
@@ -117,11 +117,12 @@ utility scheme to tell two categories apart.
 
 ## 5. Controls — two scales, `sm` by default
 
-Fields (`TextInput`, `InputTextArea`, `NumberInput`, `Select`, `Search`, `RangeSlider`, the
+Fields (`TextInput`, `InputTextArea`, `NumberInput`, `Select`, `Search`, the
 `DatePicker` family) sit on `CONTROL_SIZES` — `xs` 32px · `sm` 38px · `md` 40px · `lg` 48px.
 `Button` and every button-like trigger (`SegmentedControl`, `Tabs`, `TableToggle`, `Dropdown`)
 sit on the separate `BUTTON_SIZES` scale — `xs` 24px · `sm` 32px · `md` 40px · `lg` 48px. Both
-**default to `sm`**, so on a desktop page **don't pass `size`**. They line up at `md`/`lg`; at
+**default to `sm`**, so on a desktop page **don't pass `size`**. `RangeSlider` takes the same
+size names but keeps its own track and thumb values. They line up at `md`/`lg`; at
 `sm` a button reads 6px shorter than the field beside it.
 
 | Button role | Props |
@@ -193,6 +194,17 @@ sections are `Card` with the title in `header`.
 | Notification tray | `NotificationBell` (badge, needs `aria-label`) opening a `NotificationPanel` (zones, filters, all four states) |
 | Confirm that needs the name typed to arm it | `ConfirmDialog confirmationText="delete-me"` — `onConfirm` does **not** close; call `onClose` yourself |
 | Scrim over the page or one panel while something runs | `Backdrop open loader` — `variant="dim"` by default. Add `container` to scope it to the nearest positioned ancestor, `allowBackgroundInteraction` to let clicks through, `onClick` to dismiss |
+| A short "saved" / "copied" / "failed" notice | `useToaster().showToast({ title, status })` (`PixelizeThemeProvider` and `withTheme` mount the provider) — not a `ToolTip`, not an `AlertDialog` |
+| Page through a list that is not a `Table` | `Pagination` (controlled: numbered pages, previous / next, optional rows-per-page picker) |
+| Faceted filter column (checkboxes, radios, ranges) | `FilterSidebar` (`sidebarOptions`; controlled only when both `selected` and `onChange` are set) |
+| Pick one of a few options as cards | `ChoiceCardGroup` of `ChoiceCard`; payment methods are `PaymentOptionGroup` of `PaymentOption` |
+| On / off setting | `ToggleSwitch` — `Switch` is deprecated, a two-option pill is `SegmentedControl` |
+| One-time code | `PinInput` · free-text chips: `TagInput` · email chips: `MultiSelect` (it has no options list) |
+| Copy a value to the clipboard | `CopyButton` (icon, button or menu-item layout) — not a hand-built `navigator.clipboard` button |
+| Plan state and upsell | `PlanBadge` (resolves org plan data into a `PlanPill`), `UpgradeButton` for the CTA, `LimitReachedModal` when a limit is hit |
+| Charts | `ApexBarChart` · `ApexLineChart` · `ApexAreaChart` · `ApexPieChart` · `ApexRadialChart` · `ApexPolarChart`, inside a `Card`; default series colours follow the theme, so don't pass hexes |
+| Whole admin screens (roles matrix, user directory, org list, sign-in history) | `RolesPermission` · `UserDetails` · `OrganizationDetails` · `SignInActivityTable` — don't rebuild them |
+| "+N more" on an overflowed list | `MoreItems` |
 
 **Reach for `Backdrop` in new work** — the `dim` scrim (black at 0.5, no blur, 225ms in /
 195ms out) replaces every hand-rolled `position: fixed` overlay. Never build your own
@@ -260,7 +272,7 @@ no-access panel between loading and error; `hasData` keeps content on screen dur
 | --- | --- |
 | Loading | `loadingFallback` of `Skeletons` shaped like the content (rows, cards, `StatCard isLoading`) — never a lone centered `Spinner` for a page |
 | Empty (first run) | `empty={{ icon, title, description, action }}` — the primary action as `action` |
-| Empty (filtered) | `EmptyState size="sm"` "No results for these filters" + a ghost "Clear filters" button |
+| Empty (filtered) | `FilteredEmptyState` (`filterCount`, `onClearFilters`, `onRemoveLastFilter`; `scale="card"` inside a panel) — in the boundary pass `isEmpty` + `isFiltered` |
 | Error | `ErrorState` (the boundary's `errorTitle`/`errorDescription`/`onRetry`): what failed + an outline "Retry" (+ `action` "Back to …" on a detail page) |
 
 Page header stays visible in every state; only the content region swaps. Keep **one solid button
@@ -304,7 +316,7 @@ not shipped in this package). Start from the closest one:
 | Settings / long form | `settings.tsx` | `SectionRail` (rail from `lg`, `Select` below, dirty dots), `SettingsSection` + `SettingRow`, `SaveBar`, danger zone |
 | Board | `pipeline.tsx` | `KanbanBoard` with custom cards and column totals (`height`/`maxH` to size it) |
 | Inbox / master–detail | `inbox.tsx` | selectable list rows, conversation pane, composer, mobile list↔detail |
-| App launcher (browse, pins, recents, search with actions) | `launcher.tsx` (`/examples/launcher`) | `NavLauncher` + `LauncherTrigger` in `NavigationBar leading`, app-owned registry and permission filter, pinned / frequent / recent ids, `linkAs`, remote results via `extraResults`, `isLoading`, `SideBar pinnedItems`, Classic / Spotlight toggle, synonyms, scopes, quick actions, company facts with Copy, answers |
+| App launcher (browse, pins, recents, search with actions) | `launcher.tsx` (`/examples/launcher`) | `NavLauncher` with an app-owned registry and role-based permission filter, pinned / frequent / recent ids, `linkAs`, remote results via `extraResults`, `isLoading`, Classic / Spotlight toggle, synonyms, scopes, quick actions, company facts with Copy, answers |
 | Wizard / multi-step dialog | `wizard.tsx` (`/examples/wizard`) | `WizardDialog`, inline `Wizard` and `WizardDialog chrome="inline"` in a `WorkspaceWindow`: per-step `validate` messages, locked future steps, error summary, `summary`-driven review, `isFinishing` |
 | Template editor with merge fields | `templateEditor.tsx` (`/examples/template-editor`) | `Editor mergeFields`: grouped Insert field, chips, unknown-field error chips and `onUnknownTokens`, Make dynamic, side preview, label / helper / error |
 | Shop front (home → listing → product → bag → checkout → order) | `storefront/` | `ProductCard` grid / rail / quick-add, `ProductDetails` + `StickyBuyBar`, `CartItem`, `OrderSummary`, `CouponField`, address/payment groups, `OrderStatusTimeline`, `BagBar`; mobile frame + desktop |
@@ -317,7 +329,7 @@ and rules: [COMPONENT-GOTCHAS.md](COMPONENT-GOTCHAS.md) "Commerce kit".
 - **Model the product once** as `axes` + `variants` (`OptionAxis[]`, `ProductVariant[]`) and hand the
   same objects to `ProductCard`, `QuickAddSheet`, `VariantSelector` and `ProductDetails`. Any vertical
   works — colour/size, pack size, storage, finish, shade — because the components only see axis ids.
-- **Mobile first.** Cards in a 2-up `ProductCardGrid` (`density="compact"`), a swipe `MediaGallery`,
+- **Mobile first.** `ProductCard density="compact"` in a 2-up `ProductCardGrid`, a swipe `MediaGallery`,
   `StickyBuyBar` and `BagBar` pinned at the bottom, sheets (`QuickAddSheet`, filters) instead of popovers.
 - **One loud action per view:** the single brand-filled button is Add to bag / Place order. Wishlist,
   Buy now, Remove and Move-to-wishlist are soft or ghost.