pixelize-design-library 2.4.2-beta.43 → 2.4.2-beta.45

package/COMPONENT-GOTCHAS.md

@@ -6,7 +6,30 @@ cleanly, accepts what you pass, and produces the wrong result with no warning
 catch any of these, and a unit suite that mocks the library won't either.
 
 This file ships inside the published package (`node_modules/pixelize-design-library/COMPONENT-GOTCHAS.md`)
-so it's available without checking out the library's source repo.
+so it's available without checking out the library's source repo. Its companion
+[DESIGN-GUIDE.md](DESIGN-GUIDE.md) ships beside it and covers how to compose components into a page.
+
+---
+
+## A colour rung flips direction between light and dark
+
+`colors.primary[700]` is a deep purple in light mode and a **pale** lavender in dark. The scales are
+ordered so a high rung always contrasts with the page canvas, which means its lightness inverts
+with the mode. Using one as ink is what the ordering is for; using one as a **background fill**
+gives you a dark bar in light mode and a pale one in dark, with whatever you put on top now
+unreadable.
+
+```tsx
+// Wrong — pale lavender bar in dark mode, and the label on it is unreadable
+<Box bg={colors.primary[700]}>…</Box>
+
+// Right — a brand fill that stays a brand fill, with its own guaranteed-AA foreground
+const brand = resolveFilledSurface(colors.primary, colors);
+<Box bg={brand.activeFill} color={brand.activeColor}>…</Box>
+```
+
+`resolveFilledSurface` is exported from the package root. Use `.fill`/`.color` for a standard
+brand surface and `.activeFill`/`.activeColor` for a deeper one behind other content.
 
 ---
 
@@ -26,46 +49,100 @@ opt-in, never assume a non-default look).
 Pick by density and emphasis, not by taste. When unsure, or migrating an existing call site, leave
 it on `"default"` — it's the only variant guaranteed to match previously-shipped screenshots.
 
-### Which "select" component — seven components overlap in name, not purpose
+**On a coloured bar, pass `surface`.** `SegmentedControl` (and `Switch`, which renders it) cannot
+read the background its parent painted, so without `surface` it assumes the **page canvas**. Drop one
+into a brand-filled header and two things go wrong: `brandSlide`'s 8% tint composites into the bar,
+so the track stops reading as a control at all, and the inactive label — measured against the canvas
+— lands at **1.0–2.0:1**: technically rendered, effectively invisible.
 
-**Not picking a value from an options list at all:**
+Given `surface`, the `brandSlide` track becomes an **opaque plate** (`colors.surfaceRaised`) with a
+1px edge lifted to 3:1 against the bar, and every label's ink is re-aimed at that plate. The edge is
+what carries the boundary: in dark mode the plate and a brand bar can sit at almost the same
+lightness (as low as 1.56:1 on radiant), so hue alone would not separate them.
 
-| Doing | Component | Why not the others |
-| --- | --- | --- |
-| Triggering a labelled *action* (export, row menu, "...") | `Dropdown` | A menu-button, not a form field — nothing is "selected" and persisted |
-| Typing free-text tags (e.g. email addresses), no options list | `MultiSelect` | Despite the name, there is nothing to pick from — see gotcha below |
-| Choosing which *fields/columns* to include, in a modal, from a checkbox grid | `FieldSelectModal` | Multi-checkbox selection UI, not an inline field control |
+```tsx
+<Box bg={theme.colors.primary[700]}>
+  <Switch ... surface={theme.colors.primary[700]} />   // 1.24:1 -> 4.54:1
+</Box>
+```
 
-**Picking one or more values from an options list, inline in a form:**
+Pass the same value you gave the wrapper's `bg`. It re-aims the unselected, selected and hover inks
+together, and flips direction correctly in dark mode. `HeaderActions` takes `surface` for the same
+reason.
 
-| List length / need | Component | Why |
+### Which "select" component — `Select` is the only one to reach for now
+
+There is now **one** picker. `Select` does both modes off the `native` prop:
+`native` (default `true`) renders a real `<select>`; `native={false}` renders the themed,
+fully-React popup — searchable, `isMulti` with chips, grouped options, `isClearable`,
+`onCreate`, `renderOption`, `onLoadMore`, optional windowing via `virtualizeAfter`.
+
+`isMulti` always forces the popup — there is no native multi-select — and dev-warns if you
+also passed `native`.
+
+**Only `SelectV2` is `@deprecated`. None was deleted; every existing call site still works.**
+
+| Deprecated | Status | Migration |
 | --- | --- | --- |
-| Short, always-visible list, no search needed | `Select` | Native `<select>` wrapper — lightest option, but the popup is OS-painted and can't be themed |
-| New build, want themed/custom-rendered rows (icons, descriptions), no huge list | `SelectV2` | Fully React-rendered popup — **prefer this for new work** over `Select` |
-| Long list needing search + chips + select-all + infinite scroll | `SearchSelect` | The full-featured picker; scales via consumer-driven `pagination`, not DOM virtualization — see gotcha below |
-| Search-as-you-type with avatars/colour swatches/a pinned "add new" row | `SelectSearch` | Lighter than `SearchSelect`; reach for it for that specific row-content need |
+| `SelectV2` | Now a thin wrapper — literally `<Select {...props} native={false} />` | Drop-in. DOM, ARIA roles, keyboard and the `${listboxId}-option-${id}` id scheme are unchanged, so E2E selectors keyed to it still pass |
+| `SearchSelect` | **Not deprecated** — implementation untouched, not 1:1 replaceable yet | Hand-migrate. `insideSelect`, `isSelectAll`, `rightIcon`, a field-level loading slot and the paginated `pagination.onScroll` shape (1-based `startIndex`/`limit`/`query`) have **no** equivalent in `Select` today. Keep using it until they do |
+| `SelectSearch` | **Not deprecated** — implementation untouched | Hand-migrate. It is uncontrolled (`initialSelectedOption` seeds state once and never resyncs) and moves real DOM focus into rows; `Select` is controlled and uses `aria-activedescendant` |
+| `Dropdown` | **NOT deprecated** — the marker was wrong and was removed 2026-09-21 | Never "migrate" it to `Select`. It is a menu-button (`role="menu"`/`menuitem`, `aria-haspopup="menu"`), not a value picker (`role="combobox"`/`listbox`). Swapping it would be an accessibility regression, and nothing in this library replaces it |
+
+**Still genuinely different, not pickers at all:**
+
+| 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 |
+| 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`
+(`onclose` is `@deprecated`).
 
-Default when unsure: `SelectV2` for a themed field, `Select` if the native popup is genuinely fine.
+### `Dropdown`'s `handleOptionSelect` takes TWO arguments and TypeScript will not tell you
+
+The prop is `(id, label) => void`. TypeScript accepts a one-argument function anywhere a
+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.
+
+**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
+`handleOptionSelect={` followed by a bare identifier.
 
 ### `Slider` is an image carousel, not a numeric range input
 
 `Slider` auto-advances a set of images/content on a timer — no numeric value, min/max, or step. The
-actual range-input slider is Chakra's own, re-exported from the `Primitives` barrel as `RangeSlider`
-specifically because this library's `Slider` already owns the name.
+range-input slider is a separate component named `RangeSlider`, because this library's `Slider`
+already owns the name. `RangeSlider` used to be a Chakra passthrough on the `Primitives` barrel; it
+is now the library's own themed component, with a real dual-thumb mode and a `marks` prop.
 
-**Apply:** for a numeric/range form control, import `RangeSlider` from the `Primitives` barrel —
-never `Slider`.
+**Apply:** for a numeric/range form control import `RangeSlider` from the package root — never
+`Slider`, and no longer from the `Primitives` barrel, which no longer carries it.
 
-### Which "switch" — `ToggleSwitch` / `SegmentedControl` / `Switch`
+### Which "switch" — `ToggleSwitch` / `SegmentedControl` / `Tabs` / `InputSwitch` / `Switch`
 
 | Choosing | Component | Why |
 | --- | --- | --- |
 | A real on/off toggle | `ToggleSwitch` | `role="switch"` + `aria-checked`, full keyboard support |
 | One of 2-5 named options | `SegmentedControl` | `role="radiogroup"`, keyboard-navigable, supports per-option disabling |
-| — | `Switch` | Despite the name, a two-label segmented control (`leftText`/`rightText`) — no role, no keyboard handling at all (mouse-only). Kept only for backward compatibility; don't reach for it in new code |
+| Switching between views or panels | `Tabs` | `role="tablist"` + `aria-controls`, count badges, lazy panels, vertical orientation |
+| *(avoid)* | `InputSwitch` | `@deprecated` — now a thin wrapper that renders `ToggleSwitch` |
+| *(avoid)* | `Switch` | `@deprecated` — a mouse-only two-label segmented control (`leftText`/`rightText`); use `SegmentedControl` |
 
-**Apply:** if the choice is "on vs off," it's never `Switch` — use `ToggleSwitch`. For 2+ named
-options, prefer `SegmentedControl` even over `Switch`.
+**Apply:** "on vs off" is always `ToggleSwitch`; 2+ named options is always `SegmentedControl`.
+
+**`SegmentedControl` and `Tabs` look near-identical and are not interchangeable.** They share the
+size scale and tokens, so `SegmentedControl variant="underlineSlide"` and `Tabs variant="line"`
+render almost the same picture, as do `variant="default"` and `Tabs variant="subtle"`. The
+difference is what the control *is*: `SegmentedControl` is a **radiogroup** — it filters or sets a
+value and owns nothing else on the page; `Tabs` is a **tablist** — it shows one of several panels
+and wires `aria-controls` to them. Pick by that, never by the picture. A screen reader announces
+"radio 1 of 3" versus "tab 1 of 3, selected", and only `Tabs` gives you panels, count badges,
+`isLazy` and `orientation="vertical"`.
 
 ### Circular charts — `ApexPieChart` vs `ApexPolarCharts`
 
@@ -80,13 +157,13 @@ options, prefer `SegmentedControl` even over `Switch`.
 | --- | --- | --- |
 | A single themed, interactive button — any variant/size/colorScheme, dark-mode aware | `Button` | The only one of the three that reads design tokens at all |
 | A themed row of icon + text + icon, optionally a dropdown menu on the right | `ButtonGroupIcon` | The real "group" component despite `Buttons`' plural name suggesting otherwise |
-| *(avoid)* | `Buttons` (plural) | Legacy single `<button>` hardcoded to Tailwind `bg-purple-600`, not theme-aware, not exported from the package root — see gotcha below |
+| *(avoid)* | `Buttons` (plural) | Legacy single-`Button` wrapper, not exported from the package root — see gotcha below |
 
 ### Which "card" — `Card` / `ProductCard` / `ProductDetails` / `PaymentCard`
 
 | Need | Component | Why not the others |
 | --- | --- | --- |
-| Generic bordered/padded container, no commerce semantics | `Card` | Plain layout wrapper — its `header`/`footer`/divider props are dead, compose your own layout in `children` |
+| Generic bordered/padded container, no commerce semantics | `Card` | Layout wrapper with `header`/`footer` slots and a padded body — see gotcha below |
 | Compact product tile for a grid/listing page | `ProductCard` | Fixed size presets, single-image hover-swap, no gallery |
 | Full product detail page layout (gallery + description + variant picker) | `ProductDetails` | No card chrome of its own; same variant-list shape as `ProductCard` but named `price`, not `options` |
 | Subscription/pricing-tier card (plans, billing cycle, feature list) | `PaymentCard` | Takes a `Plan` object, unrelated to `options`/`productImage` |
@@ -126,31 +203,240 @@ options, prefer `SegmentedControl` even over `Switch`.
 
 Both export a type named `FileUploaderProps` — the one re-exported from the package root (`src/index.ts`) describes `FileUpload`, not `FileUploader`. Check which folder a type came from before trusting the name.
 
-### Inline file preview — `PdfViewer` vs `FilePreview`
+### Viewing files — `MediaViewer` / `FilePreview` / `PdfViewer` / `ProfilePhotoViewer`
+
+Four components open a file, and only one of them is the general answer.
 
 | Need | Component | Why |
 | --- | --- | --- |
+| A gallery of mixed media with next/prev, a filmstrip and per-type stages | `MediaViewer` | The full lightbox: image/video/audio/pdf/doc stages, keyboard nav, fullscreen, download. Collapses the filmstrip and stepper automatically for a single item |
+| One file, click-to-open, no gallery | `FilePreview` | Lighter controlled modal; auto-detects type, zoom/rotate for images |
 | Always-visible inline PDF panel in the page flow | `PdfViewer` | Non-modal, PDF-only, small open/download toolbar |
-| Click-to-open lightbox over mixed/unknown file types | `FilePreview` | Controlled modal; auto-detects image/pdf/video/other, adds zoom/rotate for images, graceful fallback for unsupported types |
+| Crop/preview a user avatar | `ProfilePhotoViewer` | Avatar-specific, not a general file viewer |
+
+`PdfViewer` and `FilePreview` both render a PDF through the identical unstyled `<embed type="application/pdf">` with no error handling if the browser can't render it inline — neither tells you when that happens. `MediaViewer` does handle 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.
 
-Both render a PDF through the identical unstyled `<embed type="application/pdf">` with no error handling if the browser can't render it inline — neither tells you when that happens.
+`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.
+
+`MediaViewer`'s `index`/`onIndexChange` are now optional: omit both for uncontrolled (it owns the index, starting at `defaultIndex ?? 0`), or pass both to control it. Passing `index` without `onIndexChange` freezes the viewer — every nav path has nowhere to write the new index — and now warns loudly in dev.
+
+### `HeaderActionsProps` describes a different component than `HeaderActions`
+
+The value `HeaderActions` comes from `Components/Header/HeaderActions.tsx`, which declares its props inline. The type `HeaderActionsProps` re-exported from the package root comes from `Components/Table/TableProps.tsx` — the *table's* internal bulk-action bar. Typing a `HeaderActions` usage with `HeaderActionsProps` compiles into the wrong shape.
+
+**Apply:** don't annotate `HeaderActions` with `HeaderActionsProps`. Let the props infer from the component, or use `React.ComponentProps<typeof HeaderActions>`. Same trap as `FileUploaderProps` above — check which folder a type came from before trusting the name.
+
+### Confirm prompts — `ConfirmDialog` vs `AlertDialog` vs `Modal`
+
+| Need | Component | Why |
+| --- | --- | --- |
+| A delete/deactivate prompt with a header swatch and a red Confirm | `ConfirmDialog` | The shared shape behind the library's confirm modals; `tone="destructive"` (the default) fills Confirm red |
+| A simple two-button yes/no | `AlertDialog` | Lighter; `confirmButtonText`/`cancelButtonText`, `tone="danger"` for a red Confirm |
+| Anything else | `Modal` | Named slots only — see the slot gotcha below |
+
+**`ConfirmDialog.onConfirm` does not close the dialog.** It fires and nothing else; you call `onClose` yourself. That is deliberate — it lets you keep the dialog open while an async delete is in flight — but a handler that only calls your delete function leaves the dialog on screen with no error.
+
+`iconBg` and `iconColor` are **required** and take raw colour strings, so the caller resolves the tone. Read them from `useCustomTheme()` — a hardcoded hex there is stuck in light mode.
+
+### Busy indicators — `Spinner` vs `Backdrop` vs `Loading`
+
+| Need | Component | Why |
+| --- | --- | --- |
+| Inline busy mark in a row, cell or button area | `Spinner` | The package-root `Spinner` is the themed one (accent colour, own xs–xl `size` scale), not Chakra's raw spinner |
+| **Scrim over the page or one panel — the default for new work** | **`Backdrop`** | `variant="dim"` by default: black at 0.5, no blur, 225ms in / 195ms out, 40px spinner. `container` scopes it, `onClick` dismisses, `invisible` blocks without painting |
+| Let clicks reach the page while a scrim is showing | `Backdrop allowBackgroundInteraction` | Drops `pointer-events` on the scrim **and** its transition wrapper. `onClick` cannot fire while set — that is the trade |
+| Existing screens already using it | `Loading` | The older API. Its default `variant="frosted"` keeps the heavier house scrim (0.6 + 4px blur) so nothing shifts; `variant="dim"` routes it through `Backdrop` |
+
+**Never hand-roll a scrim.** A `position: fixed` `Box` with your own `rgba()` will not match the
+Modal/Drawer overlay, will not fade, and will not follow dark mode. `Backdrop` is the one owner.
+
+One trap if you build anything similar yourself: setting `pointer-events: none` on your overlay is
+not enough when the overlay sits inside a transition wrapper — the wrapper keeps capturing clicks.
+`Backdrop` sets it on both.
+
+### Data states — `EmptyState` / `ErrorState` / `QueryStateBoundary`
+
+| Need | Component | Why |
+| --- | --- | --- |
+| "Nothing here yet" with an optional action | `EmptyState` | Neutral placeholder |
+| A failed load with retry | `ErrorState` | `role="alert"`, `onRetry`/`isRetrying` built in |
+| One fetch that can be loading, failed, empty or ready | `QueryStateBoundary` | Picks for you: loading > error > empty > `children` |
 
 ---
 
 ## Known gotchas (silent failures)
 
+### Defaults changed in 2.4.2-beta.44 — read this first when upgrading from beta.43
+
+| 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` (32px). One scale for all: xs 24 / sm 32 / md 40 / lg 48 — `md` is now 40px everywhere (`TextInput` was 44, selects 38, `SegmentedControl` ~36). `TimePicker` has no `size` (fixed `sm`); `SegmentedControl` has no `xs` | `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"` |
+| `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) | — |
+| `ToggleSwitch` / `SegmentedControl` / `TableToggle` | Off track lifted to 3:1; thumb ink flips on light fills. Radius `lg`; `TableToggle` tooltips = button names, `aria-pressed` | — |
+| `MultiSelect` | Default `md` → `sm`; real `<label>`; shared two-tone focus ring | `size="md"` |
+| Selected rows (`Dropdown`, `SelectV2`, `SearchSelect`, `SelectSearch`, `MoreItems`, `Table` filters, menus) | Dark aliases `backgroundColor.tertiary` to the panel, so a selected row sat at 1.025:1 and was invisible. It is now lifted to a perceptible step. Light is byte-identical on eight brands; `zinc` moves slightly, having been below the step too | — |
+| `tertiary` | Was an exact copy of `secondary` on six brands and of `primary` on three, so `colorScheme="tertiary"` rendered as another scheme. Now a real third accent: `primary`'s hue turned 60° at `secondary`'s luminances, so contrast is unchanged | use `secondary` |
+| `SelectV2` | Trigger is now `div[role=combobox]`, not `<button>` — widen a `useRef<HTMLButtonElement>` to `HTMLDivElement`; assert `aria-disabled`, not `toBeDisabled()`. `isMulti` shows removable `Tag` chips (`maxVisibleChips`, default 6, then `+N`); Backspace removes the last; `maxLabelsBeforeSummary` now only shapes the `aria-label`. Read-only is `data-readonly`, not `aria-readonly` | custom `renderValue` for text |
+| `SearchSelect` / `SelectSearch` | Menu radius `lg` → `xl`, shadow `lg`. `SearchSelect`'s button triggers are now `role=button` named `"Label: value"`; only the text input is `role=combobox` — update `getByRole("combobox")` queries | — |
+| `TextInput` | **`type="password"` now auto-renders a show/hide toggle** — a plain password field gains a button it did not have in beta.43. Suppressed automatically when `inputRightIcon` is set, so a hand-rolled toggle never doubles up; `isPasswordToggleDisabled` opts out entirely. Also new: `variant` (`outline` default / `filled` / `flushed`), `isClearable`, `showCharacterCount` + `maxLength`, `inputLeftAddon`/`inputRightAddon`, `isLoading`. `inputStyle`/`leftElementStyle`/`rightElementStyle` are now `SystemProps` and `inputGroupStyle` is `CSSProperties` — all four were bare `object`, so a wrong key that used to compile now fails | `isPasswordToggleDisabled` |
+| Chakra passthroughs | 34 barrel value exports (and 12 type exports) that duplicated an owned component were removed: `Input`, `Textarea`, `Progress`, `Radio`, `RadioGroup`, `Skeleton`, `ModalOverlay`, `ModalContent`, `ModalCloseButton`, `CardBody`, `ChakraCard`, `ChakraSelect`, `ChakraModal`(+`Body`/`Header`/`Footer`) the `Tabs`/`Accordion` families, and the Chakra slider sub-parts. `Tabs`, `Accordion` and `RangeSlider` now resolve to the library's own themed components (`RangeSlider` gained a real dual-thumb mode and a `marks` prop). Each removal is a compile error, never a silent swap | use the owned component — `TextInput`, `InputTextArea`, `ProgressBar`, `RadioButton`, `Skeletons`, `Modal`, `Card`, `Select` |
+| `Avatar` / `AvatarGroup` | Now the library's own components, not Chakra passthroughs. `AvatarProps` is a closed list (`name`, `src`, `size` `2xs`–`xl`, `status`, `ariaLabel`, `getInitials`, `data-testid`) — Chakra style props and `2xl` no longer compile, and **`name` is now required `string`**, so a `user.name?: string` call site fails. The fill is derived from `name`, so stop passing `bg`/`color`; it follows brand and dark mode on its own. `AvatarGroup` takes `people=[{name, src}]`, not `<Avatar>` children, so it can build one accurate group label. Measured by typecheck: 13 of 18 consumer files break | wrap in a `Box` for placement/shadow; resolve `name` at the call site |
+| `SettingsSection` | New optional `action` slot, right of the title/description on the header row — additive, nothing changes without it | — |
+| `Button` / `Buttons` | Icon-only buttons are square. `Buttons` (plural) is themed instead of hardcoded purple | — |
+| `ProgressBar` | Fill lifted to ≥ 3:1 on its track — green/orange/blue/cyan are visibly darker in light mode | — |
+| `PhoneNumberInput` / `PinInput` / `NoteTextArea` | `ref` now attaches; 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` | — |
+| `AlertDialog` | Yes/No → Confirm/Cancel; Cancel is a neutral gray outline (was red) | `confirmButtonText`/`cancelButtonText`; `tone="danger"` for a red Confirm |
+| `Modal` | Page scroll now locks (`blockScrollOnMount` was silently off); `motionPreset="scale"`; theme scrim (60% black + blur) — drop any `overlaybackdropFilter` hue-rotate workaround; `isLoading` keeps header + close button | `blockScrollOnMount={false}` |
+| `Toaster` | `showToast` returns an id; `update(id, patch)` / `close(id)`; `loading` toasts never auto-dismiss | pass `duration` |
+| `ToolTip` | `openDelay` 0 → 300ms; 13px themed look | `openDelay={0}` |
+| `InputTextArea` / `FileUpload` / `TextInput` | Width 500px → 100% / `maxSizeKB` 5 → 5120 / no default "Placeholder" text | `width="500px"` / — (5 KB was a bug) / — |
+| `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 `outline`. 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 | — |
+| `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 | — |
+| `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) | — |
+| `HeaderActions` | Edit/Create are real `<button>`s (keyboard reachable, focus ring); select named by `select.ariaLabel` or its placeholder | — |
+| `SearchSelect` | New `aria-label` prop for fields without a visible `label` | — |
+| New root exports | `mergeRefs`/`setRef`, `rafThrottle`, `toWords`, `useDebouncedCallback`/`useDebouncedValue`, and the chart theming kit (`getCategoricalSeriesColors`, `chartInk`, `labelOnSeries`, …) — previously internal-only | — |
+| `toWords` | Now splits camelCase (`nextFollowUp` → `Next Follow Up`), so `Timeline`/`KanbanBoard` auto-labels read correctly instead of `Nextfollowup` | pass an explicit label |
+| Focus rings (all controls) | `focusRing.ring` is now the brand accent itself (lavender `#8B3FC8`), not a near-black band — the white halo already separates it from a filled control | — |
+| `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/32/40/48, 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 | — |
+| `Search` / `FilterBar` / `SettingRow` / `NoteTextArea` | `Search` names itself from `placeholder` when there's no `label`/`aria-label`. `FilterBar` wraps `search` in a `role="search"` landmark named by `searchLabel` (default "Search"). `SettingRow` auto-wires an unnamed `control` to the row's title/description via `aria-labelledby`/`aria-describedby` unless it already has its own `aria-label`. `NoteTextArea` adds `titleAriaLabel`/`noteAriaLabel` (default "Note title" / `customPlaceholder`) | — |
+
+### Removed barrel exports → what to import instead (beta.44)
+
+Every name below stopped resolving from `pixelize-design-library` in beta.44. Each is a **compile
+error**, never a silent swap, and each has an owned replacement that is already exported. Props
+differ — this is a rewrite of the call site, not a rename.
+
+| No longer exported | Import instead | Note |
+| --- | --- | --- |
+| `Input` | `TextInput` | Owns its label, helper/error text and password toggle |
+| `Textarea` | `InputTextArea` | |
+| `ChakraModal`, `ModalContent`, `ModalOverlay`, `ModalCloseButton`, `ChakraModalHeader`, `ChakraModalBody`, `ChakraModalFooter` | `Modal` | `Modal` renders the overlay, content and close button itself — drop those three. **`ModalHeader`/`ModalBody`/`ModalFooter` are still exported** and are still how you fill it; only the `Chakra`-prefixed aliases went. Header text can come from `title`/`subtitle` instead |
+| `ChakraCard`, `CardBody` | `Card` | `header`/`footer` slots + `bodyProps` |
+| `ChakraSelect` | `Select` | |
+| `Radio`, `RadioGroup` | `RadioButton` / `RadioButtonGroup` | |
+| `Skeleton` | `Skeletons` | Takes `borderRadius` |
+| `Progress` | `ProgressBar` | |
+| `AccordionItem`, `AccordionButton`, `AccordionPanel`, `AccordionIcon` | `Accordion` | Takes an `items` array, not compound children |
+| `SliderTrack`, `SliderFilledTrack`, `SliderThumb`, `SliderMark` | `Slider` / `RangeSlider` | Owned components; the Chakra sub-parts are gone |
+
+**Ten names still resolve** and only narrowed their props — `Accordion`, `Avatar`, `AvatarGroup`,
+`RangeSlider`, `Spinner`, `Tab`, `TabList`, `TabPanel`, `TabPanels`, `Tabs`. They now point at the
+library's own themed component rather than the Chakra passthrough.
+
+### `Tag`'s `onIconClick` renders nothing without `icon` — the remove button silently never appears
+
+`onIconClick` only turns `icon` into a remove button; it has no effect on its own (`Tag.tsx`
+`{icon && (onIconClick ? … : …)}`). Passing `onIconClick` alone — expecting a default close
+affordance the way Chakra's own `TagCloseButton` or AntD's `closable` work — compiles fine and
+renders a plain tag with no way to remove it.
+
+**Apply:** always pass both `icon` (e.g. `lucide-react`'s `X`) and `onIconClick` together for a
+removable chip. `icon` alone (no `onIconClick`) is the decorative case — a plain right-side icon
+with no click affordance, aria-hidden.
+
+### A rounded box with `overflow: hidden` clips glyphs at the corners — never round the clipping element
+
+`border-radius` reshapes the overflow clip, so a pill-shaped element with `overflow: hidden`
+clips text along an **ellipse**, not a rectangle. A leading `p`, `j`, `g`, `q` or `y` loses part
+of its descender to the bottom-left curve. It looks like a font or line-height problem; it is not.
+This shipped in `Tag`, where the label carried both `borderRadius: "full"` (to round its focus
+ring) and `overflow: hidden` (for `text-overflow: ellipsis`).
+
+The two cannot live on the same element. `overflow-clip-margin` does not rescue it either:
+`text-overflow: ellipsis` needs a non-`clip` horizontal axis, and mixing `hidden`/`clip` across
+axes collapses both to `hidden`, which makes the margin inert.
+
+**Apply:** keep the radius on the outer element and put `overflow: hidden` +
+`text-overflow: ellipsis` on a square (`borderRadius: 0`) child. Chakra's `TagLabel` also forces
+`noOfLines={1}` as a style prop, which outranks the theme — pass `noOfLines={undefined}` to drop
+it. In your own components, the same rule holds for any rounded chip, avatar or badge that clips
+its own text. The `/tag` playground's "Glyph clipping" section renders every letter leading and
+trailing at all four sizes as the visual check.
+
+### `colorScheme="tertiary"` is a real third accent from beta.44 (it used to be a duplicate)
+
+Through beta.43 `tertiary` was an exact copy of `secondary` on six brands and of `primary` on three,
+so the two schemes were indistinguishable. It is now `primary`'s hue turned 60° re-solved to
+`secondary`'s luminances, so every contrast guarantee is unchanged.
+
+**Apply:** `secondary` vs `tertiary` is now a real visual distinction on every brand except `zinc`,
+which is near-grey and has almost no hue to turn — use a semantic scheme (`blue`, `teal`, `purple`)
+there if the two categories must read apart.
+
+### Your own overlay painted `background[50]` sinks into the dark canvas
+
+In dark mode `background[50]` equals the page canvas on 8 of 9 brands. Library dialogs, drawers,
+popovers and menus now paint `colors.surfaceRaised` — identical `#ffffff` in light, one elevation
+step up in dark. A custom panel, popover or `ModalContent bg=` in an app should read
+`surfaceRaised` too, and a divider inside it `raisedRule(colors)`.
+
 ### `Drawer` / `Modal` / `ProfileCard` drop any child that isn't a named slot
 
 All three match children by exact type (`child.type === XHeader/XBody/XFooter`) and render only
-those matches — nothing else in `children` is ever read. Two consequences: a sibling among the
-slots (a nested `Modal`, `AlertDialog`, a confirm dialog, a portal after the footer) silently never
-mounts; and a slot wrapped in a `<>...</>` fragment is dropped too, because the matching doesn't
-unwrap fragments — a fragment's `.type` is `Fragment`, never the slot component.
+those matches — nothing else in `children` is ever read. A sibling among the slots (a nested
+`Modal`, `AlertDialog`, a confirm dialog, a portal after the footer) silently never mounts. All
+three now unwrap **one** `<>...</>` level around a slot (so `<>{cond && <DrawerFooter>...}</>`
+still renders) and spread styling props (`padding`, `borderBottom`, `sx`, …) from the matched slot
+onto the real header/body/footer — a second nested fragment, or any other wrapper element, still
+drops the slot silently.
 
 **Apply:** put a confirm dialog **outside** the `Drawer`/`Modal`/`ProfileCard`, as a sibling in a
 wrapping fragment — never among the header/body/footer slots. When a ternary picks between bodies,
 branch into a variable rendered inside one body slot, rather than returning fragment-wrapped slots
-per branch.
+per branch. `Drawer`'s misspelled `vaiant` is `@deprecated` — use `variant`.
+
+### `QueryStateBoundary` evaluates JSX `children` even while loading
+
+JSX children are built before the boundary decides what to show, so `data.items.map(...)` crashes
+while `data` is still `undefined`. **Apply:** pass `children` as a function — `{() => <List
+items={data.items} />}` — whenever it reads data that may not exist yet.
+
+### `StatCard`'s delta colour follows `trend` vs `goodDirection`, not `trend` alone
+
+Green when `trend === goodDirection`, red otherwise — a falling cost with `goodDirection="down"` is
+green. Pass `onClick` for a clickable card (it renders its own `<button>`); never wrap it in one.
+
+### A clickable `TextInput` icon is a real button — give it a name
+
+With `onRightIconclick`/`onLeftIconClick` the icon renders as a `<button>`. Without
+`rightIconAriaLabel`/`leftIconAriaLabel` it is announced as "{label}: right icon action".
+
+### `SelectSearch`'s `isRequired` shows the asterisk but never announces "required"
+
+`SelectSearch` sets `aria-required` by hand on its Chakra `Input`, but Chakra's `useFormControl`
+re-adds its own `"aria-required"` key *after* spreading your props, computed from the surrounding
+`FormControl`. That `FormControl` is never given `isRequired`, so the attribute is recomputed as
+undefined and stripped. Verified by DOM dump: the rendered `<input>` carries no `aria-required`
+even when `isRequired` is passed. The visible asterisk comes from a separate custom label, so the
+field *looks* required to sighted users and is silent to a screen reader.
+
+**Apply:** `SelectSearch` is `@deprecated` — use `Select` (`native={false}`), which marks required
+state on a plain `Box` combobox that Chakra does not rewrite. If you must stay on `SelectSearch`,
+set the required state on your own wrapping `FormControl`. Note the obvious one-line fix inside the
+component is not neutral: Chakra's `useFormControl` also emits native `required`, which would add
+browser validation to a *filter* input that was never submitted before.
 
 ### `Select`'s `onChange` never fires for the built-in placeholder
 
@@ -160,7 +446,8 @@ picking it resolves to no match and nothing fires. An "Any / All / None" reset b
 placeholder alone is a dead control; the value snaps back and no filter clears.
 
 **Apply:** fine for a plain pick-one-of-N. For a clearable filter, add an explicit
-`{ id: "", label: "Any" }` entry to `options` instead of relying on the placeholder.
+`{ id: "", label: "Any" }` entry to `options` instead of relying on the placeholder. With
+`isReadOnly`, `onChange` never fires at all.
 
 ### `MultiSelect` is an email-chip input, not a picker
 
@@ -168,17 +455,7 @@ Despite the name, `MultiSelect` takes **no `options` prop at all**. Typed text i
 email address and rejected if it doesn't match — there is no way to choose from a product/entity
 list.
 
-**Apply:** use `SearchSelect` with `isMultiple` to pick multiple values from an options list.
-
-### `RadioButton` has a closed prop list — no `...rest`, no `name`
-
-It forwards only a fixed set of props (`label`, `colorScheme`, `isChecked`, `onChange`,
-`isDisabled`, `size`, `value`, `defaultChecked`, plus label/tooltip props) to the underlying radio
-— a `data-*` hook, `aria-describedby`, or a `ref` cannot reach it.
-
-**Apply:** it still joins an external `RadioGroup` correctly (grouping comes from context, no
-`name` prop needed) — don't avoid it just for grouping. Reach for the library's Chakra escape
-hatch only when you need something outside that closed list.
+**Apply:** use `Select` with `isMulti` to pick multiple values from an options list.
 
 ### `Table`'s `onRowClick` is dead if every column has a `node` renderer
 
@@ -189,15 +466,6 @@ accepted, typed, never called.
 **Apply:** leave at least one column without a `node`, or put an explicit control inside a `node`
 renderer instead of relying on row click.
 
-### `InputTextArea`'s `width` defaults to the number `500`, and no `id` means no label
-
-`width` defaults to `500`, forwarded straight through — `500` isn't a sizing-scale key, so it
-renders a literal `500px`, not a max and not responsive. It only shows up on a narrow screen.
-Separately, `id` feeds both the visible label and the field itself with no fallback — omit it and
-the label is associated with nothing; the field has no accessible name.
-
-**Apply:** pass `width="100%"` **and** `id` at every call site.
-
 ### `error` without `errorMessage` renders the literal word "Error" — and erases `helperText`
 
 Every field that shows validation errors (`TextInput`, `InputTextArea`, `Select`, `MultiSelect`,
@@ -261,7 +529,7 @@ applies — any letter typed is silently rejected (the character never appears,
 always gets a hardcoded second line appended — "your new Pixel Account" — with no prop to remove it.
 
 **Apply:** only use this component for numeric-only OTPs with product copy that matches that exact
-trailing phrase. Otherwise build the card from `PinInput`/`PinInputs` plus your own text.
+trailing phrase. Otherwise build the card from `PinInput` plus your own text.
 
 ### `ApexLineChart` only ever renders one line, frozen at mount
 
@@ -295,22 +563,36 @@ the rest of the array is silently unused. `ApexRadialChart`'s `hollowSize` has i
 `distributed` whenever `ApexBarChart`'s `barColor` has more than one color. Don't expect
 `ApexRadialChart`'s `hollowSize` to apply under `variant="multi"`.
 
-### `Skeletons` / `ProgressBar` have closed prop lists — no `borderRadius`, no margin, no `...rest`
+### `Skeletons`' `isLoaded` and `borderRadius` only work for `type="skeleton"`
 
-Both `Pick<>` a fixed key set from their Chakra equivalents and forward nothing else — there is no
-way to round a skeleton's corners, add margin, or attach a ref/`data-*` through either component.
+`type="circle"`/`"text"` never receive `isLoaded`, `borderRadius` (or `children`/`bg`/`color`/
+`fadeDuration`) — passing them compiles and is silently dropped; the shimmer never stops no matter
+what `isLoaded` is set to. Neither `Skeletons` nor `ProgressBar` forwards a `ref`; `ProgressBar`'s
+`color` is `@deprecated` (use `colorScheme`).
 
-**Apply:** for rounding, spacing, or a ref, use the Primitives barrel's raw Chakra `Skeleton`/
-`Progress` instead.
+**Apply:** for `circle`/`text`, control visibility by conditionally rendering the `Skeletons` element
+itself, not via `isLoaded`.
 
-### `Skeletons`' `isLoaded` only works for `type="skeleton"`
+### Five exports start with `Notification` and only one of them is a notification tray
 
-`type="circle"`/`"text"` never receive `isLoaded` (or `children`/`bg`/`color`/`fadeDuration`) —
-passing them compiles and is silently dropped; the shimmer never stops no matter what `isLoaded` is
-set to.
+Autocomplete offers `Notification`, `NotificationBell`, `NotificationPanel`, `NotificationList` and
+`NotificationItem`. They are not a family — `Notification` is a standalone countdown card from a
+different era, and picking it for an inbox row is the common mistake.
 
-**Apply:** for `circle`/`text`, control visibility by conditionally rendering the `Skeletons` element
-itself, not via `isLoaded`.
+| Export | What it actually is |
+| --- | --- |
+| `NotificationBell` | The badge/bell button only. Requires `aria-label`; it renders no list |
+| `NotificationPanel` | The tray the bell opens — zones, filters, loading/error/empty/data |
+| `NotificationList` | The panel's scrolling body without the panel chrome — owns the day bucketing and `groupKey` collapsing |
+| `NotificationItem` | One inbox row: the tone-driven chassis the list paints for each item |
+| `Notification` | **Not deprecated.** A dated countdown card — its dot colour comes from `dueDate`/`endDate` math, not from a tone. `NotificationItem` cannot replace it: `formatRelativeTime` clamps every future date to "Just now" |
+
+`Notification` is kept only because nothing else does that date-driven countdown; it is not a thin
+alias, so it has not been removed.
+
+**Apply:** for a notification tray use `NotificationBell` + `NotificationPanel`. For rows inside your
+own layout use `NotificationList` or `NotificationItem`. Reach for `Notification` only when you
+specifically want the deadline-countdown card, and read the gotcha below before you do.
 
 ### `Notification`'s `onClick` only reaches the title text, and its status dot has two gates
 
@@ -335,23 +617,10 @@ form is embedded in a `Modal`.
 minimal valid usage. Key the element to force a remount if `defaultValues` arrives late. Verify the
 toast actually appears if embedding inside a `Modal`.
 
-### `Checkbox`'s `error` never sets `isInvalid`, and `variant` is a no-op
-
-`error` doesn't set `isInvalid`/`aria-invalid`, and `errorMessage`/`helperText` aren't linked via
-`aria-describedby` — confirmed by three `it.failing` cases in `Checkbox.a11y.test.tsx`. Separately,
-`variant` is typed and accepted but never destructured or read; `Checkbox.styles.ts` defines no
-`variants` key, so no value changes anything.
+### `Checkbox`'s `variant` is a no-op
 
-**Apply:** pass `isInvalid` explicitly alongside `error` — `error` alone never registers as invalid.
-Don't expect `variant` to change a `Checkbox`'s look.
-
-### `Toggle`/`TableToggle` has no `aria-pressed`, and its tooltip text can silently mismatch its `aria-label`
-
-Confirmed by three `it.failing` cases in `TableToggle.a11y.test.tsx` — a tooltip reading "Table View"
-on a button whose `aria-label` is "Grid View" is a real, reachable state, not a hypothetical.
-
-**Apply:** keep each button's tooltip text and `aria-label` in sync yourself; the component doesn't
-enforce or derive one from the other.
+Typed and accepted, 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
 
@@ -371,23 +640,14 @@ the library (`TextInput`, `NumberInput`, `PhoneNumberInput`, `RadioButton`, `Pin
 **Apply:** always pass `isInformation` and `informationMessage` together; never treat
 `isInformation` alone as "use a default message."
 
-### Any field's label silently renders as an unassociated `<span>` if you omit `id`
-
-`TextLabel` (the shared label engine behind nearly every field, see above) only renders a real
-`<label htmlFor>` when given an `id` — omit it and the visible label text renders but is never
-programmatically associated with its control, on any of the ~17 components that use it.
-
-**Apply:** always pass `id` when you want a real, accessible `<label>`. (`MultiSelect` omits it on
-purpose and wires `aria-label` instead — that's the pattern to copy if you skip `id` deliberately.)
-
 ### `ErrorComponent`'s `error` prop is the message text itself — the opposite of `error`+`errorMessage`
 
 Every other field in the library pairs a boolean `error` with a string `errorMessage`.
-`ErrorComponent` (used internally by `Input`/`PinInputs`) instead takes `error: string` directly as
+`ErrorComponent` (used internally by `Input`) instead takes `error: string` directly as
 the message, with no internal truthy-check — passing `error=""` still draws the full icon next to
 blank text. It also has no `id`, so unlike `ErrorMessage` it can't be wired to `aria-describedby`.
 
-**Apply:** treat `ErrorComponent` as `Input`/`PinInputs`-specific, not a general error row; guard it
+**Apply:** treat `ErrorComponent` as `Input`-specific, not a general error row; guard it
 with a truthy-message check yourself, and use `ErrorMessage` for any other field.
 
 ### `FormattedDescription`'s single-`*italic*` marker strips the asterisks but applies no italic style
@@ -407,11 +667,10 @@ looks like it does nothing: the form stays open with no error or feedback.
 **Apply:** always pass `editNoteLoading` alongside `onEditNote`, even a client-only flag flipped
 right after the call resolves.
 
-### `Timeline`'s `events` prop is dead — only `timelineEvents` renders
+### `Timeline`'s `events` prop is `@deprecated` and still renders nothing
 
-`events` is typed and accepted, reads as a plausible prop name, and is never used by the component.
-
-**Apply:** always use `timelineEvents`; treat `events`/the exported `TimelineEvent` type as vestigial.
+Pass `timelineEvents`; `events` (and the `TimelineEvent` type) is never read, not even as a fallback.
+Rows are now static unless you pass `onEventClick`.
 
 ### `Timeline` drops events with an unparseable `created_at`, with no visible trace
 
@@ -421,27 +680,24 @@ shown in a fallback bucket, just gone. The only signal is a `console.warn` insid
 **Apply:** validate/normalize `created_at` before handing events to `Timeline` — a bad timestamp is
 silent, total content loss for that row.
 
-### `Reorder`'s `onReorder` fires even when nothing moved, and its real props aren't in its exported type
+### `Reorder`'s `onReorder` fires even when nothing moved
 
 A drag that ends back at its starting index still has a drop target and still calls `onReorder` with
-a new array reference in the same order. Separately, the component supports `showRemoveIcon`/
-`onRemove` in practice, but the exported `ReorderListProps` type declares only
-`label`/`items`/`onReorder` — neither `ReorderListProps` nor `ReorderItem` is exported from
-`src/index.ts` at all, so there's no public named type to check either way.
+a new array reference in the same order.
 
 **Apply:** compare source/destination index (or diff the array) before persisting a reorder, if a
-no-op write matters. `showRemoveIcon`/`onRemove` do work — pass them despite the type gap.
+no-op write matters. `showRemoveIcon`/`onRemove` are declared on `ReorderListProps` and work as
+expected; a missing-name item's image alt falls back to `item-<1-based position>`.
 
-### `Divider` and `Trail`'s pieces aren't exported from the package at all
+### `Divider` isn't exported from the package at all
 
-Neither `src/Components/Divider/` nor `src/Components/Trail/` appears in `src/index.ts`, though both
-still compile into `dist/` and are deep-import-reachable. The library's own `Divider` is always
-vertical, fixed size/color, zero props — a different thing from the general-purpose (horizontal,
-styleable) `Divider` re-exported from the `Primitives` barrel. `Trail/TrailWorks` is a hardcoded
-2-row demo table, not a reusable grid.
+`src/Components/Divider/` doesn't appear in `src/index.ts`, though it still compiles into `dist/`
+and is deep-import-reachable. The library's own `Divider` is always vertical, fixed size/color,
+zero props — a different thing from the general-purpose (horizontal, styleable) `Divider`
+re-exported from the `Primitives` barrel.
 
 **Apply:** for a divider in a consuming app, use the `Divider` from `Primitives`, not this library's
-own. For a real data grid, use `Table` — nothing under `Trail/` is meant for reuse.
+own.
 
 ### `KanbanActions` is exported but still not wired into `KanbanBoard`
 
@@ -481,14 +737,13 @@ props. Mixing plain and `customNode` items in one column produces inconsistent p
 **Apply:** don't expect board-wide card actions to reach a `customNode` card; wire them inside your
 custom render instead.
 
-### `KanbanBoard`'s `AccountCard` only renders string-typed fields, and mangles camelCase labels
+### `KanbanBoard`'s `AccountCard` only renders string-typed fields, and labels are the raw key
 
-A numeric field on an `Account` (explicitly allowed by its index signature) is silently never shown
-in the card's field list. The auto-generated label only splits on `_` — a snake_case key
-(`account_name`) renders as "Account Name," but an idiomatic camelCase key (`nextFollowUp`)
-collapses into one mashed word ("Nextfollowup").
+A numeric field on an `Account` (allowed by its index signature) is never shown in the card's field
+list. The label is the key with only its first letter capitalised — `account_name` renders
+"Account_name", `nextFollowUp` renders "NextFollowUp"; nothing splits words.
 
-**Apply:** use snake_case keys on `Account` objects, and keep numeric display values as strings.
+**Apply:** keep numeric display values as strings; use keys that read acceptably as-is.
 
 ### `KanbanBoard`'s `onColumnDelete` receives the deleted column's **card** ids, not the column's id
 
@@ -501,25 +756,13 @@ before the click) if you need the column id itself.
 
 ### `isRequired` is decorative on some fields, native on others — same prop name, different behavior
 
-`TextInput`, `PhoneNumberInput`, and the exported `PinInput` pass `isRequired` only to the label
-(draws a `*`) — the field itself never gets `required`/`aria-required` (confirmed by an `it.failing`
-case in `TextInput.a11y.test.tsx`). `NumberInput` and the internal `Input.tsx` do propagate it
-natively. A form relying on `isRequired` for native HTML5/AT validation works on some fields and
-silently doesn't on others.
+`NumberInput` and the internal `Input.tsx` set native `required` (browser bubble, blocks submit).
+`TextInput` and `InputTextArea` set only `aria-required` — announced, but no native validation.
+`PhoneNumberInput` and `PinInput` pass it only to the label (draws a `*`); the field gets nothing.
 
 **Apply:** don't rely on `isRequired` for native form validation — validate required fields yourself
 regardless of which component you're using.
 
-### `PhoneNumberInput` and `NoteTextArea` type a `ref` prop that never attaches
-
-Both are plain function components, not `forwardRef` — a `ref` passed to a plain function component
-is stripped before the body runs, so the destructured ref param is always `undefined`.
-`NoteTextArea` compounds this: even where it does forward a ref, it only reaches the secondary title
-input, never the primary `Textarea`.
-
-**Apply:** don't rely on a `ref` into either component; `NumberInput`/`InputTextArea` forward refs
-correctly if you need that pattern.
-
 ### `NoteTextArea`'s `saveButtonLoading` going `true → false` clears the draft even on a failed save
 
 The effect that resets note/title/files fires whenever `saveButtonLoading` goes falsy — there's no
@@ -529,29 +772,21 @@ silently discards everything the user typed.
 **Apply:** don't flip `saveButtonLoading` back to `false` on failure without your own recovery path
 (e.g. keep the draft in your own state and re-seed it).
 
-### `PinInput` and `PinInputs` are two unrelated implementations — only one is real
-
-The component published as `PinInput` from `index.ts` is Chakra-native, themed, supports OTP paste
-and `type: "alphanumeric" | "number"`. `PinInputs` (plural) is a separate, hand-rolled,
-always-numeric implementation that is **not exported** and not referenced anywhere else in the repo
-— a dead-code candidate, not an alternate API. It still compiles into `dist/`, so the deep-import
-pattern this repo otherwise supports would silently pull in the unmaintained one.
-
-**Apply:** always use `PinInput` (singular); never deep-import `PinInputs`.
-
-### `InputSwitch`'s checked/unchecked track color is silently replaced by a caller-supplied `sx`
+### `InputSwitch` now renders `ToggleSwitch` — `.chakra-switch__*` selectors match nothing
 
-The component's own `sx` (sets track background from `isChecked`) is spread over first, then
-`{...props}` — any `sx` a caller passes wins outright, so the switch stops changing color on toggle.
+`InputSwitch` is `@deprecated` and wraps `ToggleSwitch`, which is not a Chakra `Switch`. An `sx`
+targeting `.chakra-switch__track`/`__thumb` still compiles and lands on the wrapper, but styles
+nothing. `colorScheme` and `isReadOnly` are real now (colorScheme used to be silently discarded);
+`variant`/`spacing`/`isFocusable` stay typed `@deprecated` no-ops. **Apply:** migrate to
+`ToggleSwitch` (`fieldLabel` for the label InputSwitch drew above the track) and drop those selectors.
 
-**Apply:** don't pass `sx` to override styling on `InputSwitch`; if you must, re-include the
-checked/unchecked background logic yourself.
+**This breaks tests, not types.** Chakra's `Switch` rendered `role="checkbox"`; `ToggleSwitch`
+renders the correct `role="switch"`, so `getByRole("checkbox", { name })` silently stops matching
+while everything still compiles. Two consumer repos hit this on the beta.44 upgrade. **Apply:**
+change those queries to `getByRole("switch", …)`.
 
-### `TextInput`'s `placeholder` defaults to the literal word `"Placeholder"`, not empty
-
-Omit the prop and real users see the actual text "Placeholder" in the field.
-
-**Apply:** always pass an explicit `placeholder` (or an empty string) at every `TextInput` call site.
+Same shape of trap on `Tabs`: the owned `Tab` forwards no `data-testid`, so `getByTestId("…-tab-…")`
+queries must become `getByRole("tab", { name })`.
 
 ### The internal `Input.tsx` silently ignores six declared props
 
@@ -564,19 +799,14 @@ and does nothing. It also has no `id` field, so its label always renders as an u
 
 ### `AlertDialog`'s `colorScheme`/`size`/`status`/`variant`/`addRole` are dead props
 
-Typed (`Pick`ed from Chakra's `AlertProps`) but never destructured — Cancel/Confirm are hardcoded
-red/primary at `size="sm"` regardless of what you pass.
-
-**Apply:** style Cancel/Confirm via `button1Style`/`button2Style`, not `colorScheme`/`size`/`status`/
-`variant`.
+Typed but never read, and `@deprecated` as a group (editors may not strike each one through). Use
+`tone="danger"` for a red Confirm, or `button1Style`/`button2Style`.
 
-### `AlertDialog` can always be dismissed via Escape or an overlay click, not just its buttons
+### `AlertDialog`'s `onClose` also fires on Escape and overlay click
 
-`closeOnOverlayClick`/`closeOnEsc` aren't exposed as props, so Chakra's `true`/`true` defaults apply
-unconditionally — `onClose` fires the same way for Escape/overlay-click as for the Cancel button.
-
-**Apply:** don't treat `onClose` as "the user explicitly chose Cancel" — that distinction isn't
-available through this component.
+`closeOnEsc`/`closeOnOverlayClick` default to `true`, and every dismiss path calls the same
+`onClose`. **Apply:** don't read `onClose` as "the user chose Cancel"; pass both as `false` when
+only the buttons may close it.
 
 ### `ToolTip`'s `overflowOnly` silently no-ops on non-single-element children
 
@@ -589,31 +819,13 @@ single `Text noOfLines`), never a Fragment or bare text.
 
 ### `Toaster`'s `showToast({ children })` is a dead prop, and its two `onClose`s are different functions
 
-`children` type-checks (Picked from Chakra's `ToastProps`) but is never read — only `title`/
-`description`/`actions` render. Separately, the `onClose` you pass to `showToast` is wired to
+`children` is `@deprecated` and never read — only `title`/`description`/`actions` render. The `onClose` you pass to `showToast` is wired to
 Chakra's `onCloseComplete` (fires after the exit animation, on any dismiss path); the `onClose` your
 `actions` render-prop receives is a different, immediate per-toast dismiss function.
 
 **Apply:** pass `description`, not `children`. Don't assume your `onClose` fires the instant the
 user clicks close — it fires after the exit transition completes.
 
-### Every `Toaster` status announces at `aria-live="polite"`, including `error`
-
-No urgency bump for errors, and status is conveyed by icon + colour alone with no text equivalent —
-confirmed by two intentionally-`it.failing` tests in `Toaster.a11y.test.tsx`.
-
-**Apply:** don't rely on an error toast interrupting a screen reader; pair a critical failure with
-another signal (e.g. an inline field error).
-
-### `Button`'s `loadingText` defaults to `"Loading"`, not Chakra's spinner-only style
-
-`loadingText` defaults to the literal string `"Loading"`, so every `isLoading` button shows that
-text next to the spinner instead of Chakra's native behavior (hide content, spinner only) — even
-icon-only buttons, where it can break the expected square aspect ratio. Passing
-`loadingText={undefined}` does not restore the native look; the default parameter still applies.
-
-**Apply:** pass `loadingText=""` explicitly to get a spinner-only loading state.
-
 ### `ButtonGroupIcon`'s dropdown needs `rightIcon` **and** `rightIconDropdown` both set
 
 The `Menu`/`dropdownOptions` branch only renders inside `rightIcon && rightIconDropdown`. Supplying
@@ -625,22 +837,22 @@ button, right icon/dropdown), not just a "clicked outside the buttons" signal.
 **Apply:** always set `rightIcon` + `rightIconDropdown={true}` together for the dropdown. Don't use
 `onButtongroupClick` to detect background clicks — inspect `event.target` if you need to distinguish.
 
-### `Buttons` (plural) is not a group wrapper, and not theme-aware
+### `Buttons` (plural) is not a group wrapper
 
-Despite the plural name suggesting a group, `Buttons` renders one plain `<button>` hardcoded to
-Tailwind's `bg-purple-600` — it ignores brand/dark-mode entirely and isn't exported from the package
-root.
+Despite the plural name suggesting a group, `Buttons` is now a thin wrapper over one themed
+`Button` (its `className` is `@deprecated`), and it isn't exported from the package root.
 
 **Apply:** use `Button` for a single themed button or `ButtonGroupIcon` for a themed group; there is
 no good reason to reach for `Buttons`.
 
-### `Card` silently drops `header`, `footer`, and all three divider props
+### `Card` already wraps `children` in a padded `CardBody` — a nested one doubles the padding
 
-`CardProps` declares `header`, `footer`, `dividercolor`, `dividersize`, `dividervariant`, but none
-are destructured by `Card` — passing them compiles cleanly and renders nothing. Padding is also
-hardcoded (`p={4}`), so it can't be tuned via props either.
+`header`/`footer` now render, and `children` sit in a flex `CardBody` laid out by `direction`/
+`align`/`justify`. Code written for the old Card that nested its own `CardBody` now gets padding
+twice. `colorScheme` does nothing (the Card theme never reads it) and `color` is its `@deprecated` alias; the three divider props are `@deprecated` and
+draw nothing.
 
-**Apply:** put header/footer content inside `children`; use `sx` for padding overrides.
+**Apply:** drop the nested `CardBody`, or pass `bodyProps={{ p: 0 }}`.
 
 ### `ProductCard`'s variant selection goes stale after an `options` update, and `options={[]}` crashes it
 
@@ -769,13 +981,6 @@ wrong-type file. Exceeding `maxFiles` silently truncates the list with no error.
 
 **Apply:** need real file bytes or enforced validation → use `FileUpload`, not `FileUploader`.
 
-### `FileUpload`'s default `maxSizeKB` is 5 — that's 5 **kilobytes**, not megabytes
-
-Left at its default, `FileUpload` rejects virtually every real file, and the auto-generated
-hint/error text literally reads "0.00 MB" because the KB→MB conversion divides an already-tiny value.
-
-**Apply:** always pass an explicit `maxSizeKB` in KB (e.g. `5000` for ~5MB).
-
 ### `DatePicker`'s `pickerType` does nothing when `isRange` is set, and no variant has a seconds control
 
 `RangeDatePicker` never reads `pickerType` — whether time inputs show is controlled entirely by
@@ -786,23 +991,19 @@ are never user-editable.
 **Apply:** for a range picker, control the time row via `dateFormat`, never `pickerType`. Don't
 request second-precision input from any DatePicker variant.
 
-### `RangeDatePicker` loses a picked range if you click outside instead of Apply
+### `SingleDatePicker`/`TimeOnlyPicker` default to `Date` objects — opt into strings with `valueFormat="iso"`
 
-Unlike `SingleDatePicker`, its outside-click handler doesn't call `finalize()` — only the Apply
-button or Escape commits a completed range via `onChange`. Clicking anywhere else outside the
-popover after picking both ends discards the selection silently.
+By default `selectedDate`/`value`/`onChange` speak `Date`. `valueFormat="iso"` switches one instance
+to strings: `yyyy-MM-dd` (date), `HH:mm` (time, 24h), local `yyyy-MM-dd'T'HH:mm:ss` (datetime, no
+offset). An unparsable string reads as `null`. `RangeDatePicker` and legacy `DatePicker` stay Date-only.
 
-**Apply:** don't assume outside-click commits a range the way it does for `SingleDatePicker`.
+**Apply:** use this instead of `TextInput type="date"/"time"` plus hand-rolled ISO parsing.
 
-### `TimeOnlyPicker`'s label is never associated with its field, and `name` is a no-op
+### `TimeOnlyPicker` ignores the date-range props and `autoComplete`
 
-Passing `id`/`label` does not produce an accessible `<label for>` — the internal label call omits
-`id`, so it always renders as an unassociated `<span>`. `name` (and `minDate`/`maxDate`/
-`disableFutureDates`/`disablePastDates`/`autoComplete`) are also silently dropped — the rendered
-`<input>` never gets a `name` attribute, breaking plain `<form>`/`FormData` submission.
-
-**Apply:** don't rely on `TimeOnlyPicker` for native form submission or label accessibility; read its
-value via `onChange` rather than form `name`.
+Label and `name` now work. `minDate`/`maxDate`/`disableFutureDates`/`disablePastDates` are still
+dropped, and `autoComplete` is forced to `"off"`. `DatePicker`'s `disabled`/`placeholderText` are
+`@deprecated` — use `isDisabled`/`placeholder` (the new name wins when both are set).
 
 ### `Editor`'s `config` prop can silently break dark mode, and its `key` prop can never reach Jodit
 
@@ -815,6 +1016,20 @@ is also `null` until Jodit's lazy-loaded chunk resolves — a mount-time effect
 **Apply:** never set `theme`/`popupRoot` inside the `config` you pass to `Editor`. To force a
 remount, wrap `<Editor>` itself in a keyed parent, not via `Editor`'s own `key` prop.
 
+### `Editor`'s Jodit toolbar is fixed for screen readers and keyboard, from our wrapper only
+
+Jodit's own markup (`node_modules/jodit`) put `aria-label` on each button's `role="listitem"`
+wrapper instead of the real inner `<button>`, used the invalid ARIA role `"trigger"` for its
+dropdown-chevron spans, gave `listitem` no `role="list"` ancestor, and ships every toolbar button
+at `tabindex="-1"` unless `config.allowTabNavigation` is on — so by default the toolbar failed
+axe's `button-name`/`aria-roles`/`aria-required-parent` and was entirely unreachable by keyboard.
+`Editor` now sets `allowTabNavigation: true` by default (same override rule as `theme`/`popupRoot`
+above — a value you pass in `config` wins) and runs a `MutationObserver`-backed DOM pass
+(`joditAccessibility.ts`) that copies each button's real name onto it and fixes the two roles.
+
+**Apply:** nothing — this is automatic. Set `config.allowTabNavigation: false` only if you
+deliberately want the toolbar out of the tab order; you'll reintroduce the keyboard-reachability gap.
+
 ### `SelectV2`, `SearchSelect`, and `SelectSearch` all search `option.label` only
 
 None of the three checks a rendered secondary field (`option.description`, a custom `view` node,
@@ -824,16 +1039,11 @@ no match.
 **Apply:** if a secondary field needs to be searchable, fold it into `option.label` yourself, or
 pre-filter `options` before passing them in.
 
-### `SearchSelect` never virtualizes, and `chip.maxChips={0}` is swallowed by a falsy fallback
+### `SearchSelect` never virtualizes
 
 Despite the prop name, `virtualization` does nothing — every filtered option renders as a real DOM
-node; the list scales only via consumer-driven `pagination`. Separately,
-`selectedValues.slice(0, chip?.maxChips || selectedValues.length)` treats a literal `0` as "no limit
-set" (falsy), so every chip renders anyway instead of zero.
-
-**Apply:** for a dataset large enough to need real virtualization, page it in via `pagination` rather
-than setting `virtualization={true}`. Pass `1` or higher to `chip.maxChips`; there's no supported way
-to hide all chips via this prop.
+node. Page a large dataset in via `pagination` instead. (`chip.maxChips={0}` now works: no chips,
+just "+N".)
 
 ### `SelectSearch`'s Enter key requires an exact full-label match, not the keyboard-highlighted option
 
@@ -868,14 +1078,11 @@ dropping the hover transition.
 **Apply:** pair `ButtonText` with the default/`"button"` type and `text` with `dropdownType="text"`.
 Fold custom styling into `dropDownButtonStyle`, not `buttonProps.sx`.
 
-### `Search`'s default `shortcut` grabs a page-global Ctrl+K with no way to opt out
-
-Every mounted `Search` registers its own `window` Ctrl+K listener by default — the type only permits
-the literal `"Ctrl+K"` or `undefined`, and `undefined` still resolves to the same default via JS
-parameter defaulting. Two instances on one visible view race for the keypress.
+### Every `Search` grabs a page-wide Ctrl+K by default
 
-**Apply:** avoid mounting more than one `Search` per visible view/route — there's currently no way to
-scope or disable the hotkey per-instance.
+Each mounted `Search` registers its own `window` Ctrl+K listener, so two on one view race for the
+keypress. **Apply:** pass `shortcut={false}` on all but one. `showShortcutHint={false}` only hides
+the hint; the listener stays.
 
 ### `Header`'s desktop submenus open on hover only — no keyboard or click trigger
 
@@ -912,13 +1119,14 @@ It's declared on the type 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.
 
-### `Accordion`'s `items[].buttonProps`/`itemProps` replace, not merge, the expanded/hover highlight
+### `Accordion`'s `items[].buttonProps` replaces, not merges, the expanded/hover highlight
 
-Both spread after the built-in `bg`/`_hover` that encode `isExpanded` state — passing `bg` or
-`_hover` there to tweak one item's style silently kills that item's expanded/active indication.
+It spreads after the built-in `bg`/`_hover` that encode `isExpanded` state — passing `bg` or
+`_hover` there silently kills that item's expanded indication. An `sx` inside `buttonProps` or
+`itemProps` is always overwritten by `customStyles`.
 
-**Apply:** style around the defaults via `customStyles` (merged through `sx`) rather than
-`buttonProps`/`itemProps` when the highlight must survive.
+**Apply:** style around the defaults via `customStyles` (merged through `sx`) when the highlight
+must survive.
 
 ### `Table`'s `LeftFilterPane` Clear All only re-applies filters in `"sidebar"` mode
 
@@ -988,6 +1196,8 @@ implementation, despite being typed on `TableProps` (and some documented on the
 - `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.
 
 **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
@@ -1098,17 +1308,23 @@ and submenu items. `disabled` is unchanged and still works independently.
 
 `TextTruncation.tsx`'s label used `overflow="hidden"` (both axes) with `lineHeight="1"`, so the line
 box was exactly font-size tall and any glyph descender got clipped flat — reported live on
-lfour.pixelizetech.com ("Legal Requests"). Fixed with `overflowX="hidden"` (kept, needed for the
-ellipsis) plus `overflowY="clip"` and `sx={{ overflowClipMargin: "3px" }}` — `clip` (unlike `hidden`
-paired with `visible`) never promotes the axis to `auto`, so the label does not become its own
-scroll container; the margin just lets the descender's ink bleed 3px past the box without changing
-its layout height. If you rolled your own workaround (extra line-height, padding-bottom) for this on
-a consumer's own nav text, it's no longer needed upstream.
-
-**Apply:** nothing to do — this was a rendering bug, not a prop. If you build another
-truncated-single-line label elsewhere in this library, use `overflow: clip` + `overflow-clip-margin`
-for the non-ellipsis axis — never pair `hidden` with a plain `visible` axis (CSS computes that to
-`auto`, turning every label into its own 1px-overflowing scroll container).
+lfour.pixelizetech.com ("Legal Requests").
+
+**An earlier fix here did not work and shipped looking correct.** It paired `overflowX="hidden"`
+(needed for the ellipsis) with `overflowY="clip"` + `sx={{ overflowClipMargin: "3px" }}`. CSS
+discards that: when one axis is `clip` and the other is a non-`clip`, non-`visible` value, `clip`
+computes to `hidden` — the mirror of the `visible`→`auto` rule. Measured in Chrome 152,
+`overflow-x: hidden; overflow-y: clip` computes to `hidden`/`hidden`, so `overflow-clip-margin` was
+inert on all 177 elements carrying it.
+
+The working fix is vertical padding to grow the clip box, cancelled by an equal negative margin so
+the label's layout height is unchanged: `py="0.35em" my="-0.35em"`. The padding must suit the
+line-height — `0.35em` clears `lineHeight: 1`, while `Tag`'s label needs only `0.2em` at
+`lineHeight: 1.45` (a bigger box there would push its focus ring outside the pill).
+
+**Apply:** nothing to do — this was a rendering bug, not a prop. Building another truncated
+single-line label? Use the `py`/negative-`my` pair. `overflow-clip-margin` only works when **both**
+axes are `clip`, which `text-overflow: ellipsis` rules out.
 
 ### `SideBar` nav list showed a bare, unthemed scrollbar when items overflowed — fixed