pixelize-design-library 2.4.2-beta.9 → 3.0.0

package/COMPONENT-GOTCHAS.md

@@ -0,0 +1,2057 @@
+# Component Gotchas & Decision Guide
+
+For anyone — human or AI — consuming `pixelize-design-library` in an app. Read this **before**
+choosing a component or a prop value, not after something looks wrong. Every entry below compiles
+cleanly, accepts what you pass, and produces the wrong result with no warning — TypeScript cannot
+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. Its companion
+[DESIGN-GUIDE.md](DESIGN-GUIDE.md) ships beside it and covers how to compose components into a page.
+
+---
+
+## Found a gap or a bug? Report it, then track it
+
+The library exists so a UI change is made **once, here** — not patched per app. So when a component
+is wrong, missing a prop, or can't express what a screen needs, **don't work around it in your app
+and move on.** Report it upstream; a workaround nobody knows about is a bug that gets rediscovered
+in every other app.
+
+**What counts:** a component that renders wrong (misaligned, clipped, wrong size or colour, off the
+control scale), a prop you need that doesn't exist, a silent-failure trap that isn't listed below, or
+a doc that contradicts what you measured.
+
+**How to report** — one GitHub issue on `pixelize-tech/Micro-Components`, with the label `bug` or
+`enhancement`. From a terminal (AI agents included) this is one command:
+
+```bash
+gh issue create --repo pixelize-tech/Micro-Components --label bug \
+  --title "[consumer] <Component>: <what is wrong>" \
+  --body "Version: <output of: npm ls pixelize-design-library>
+App / screen: <where you saw it>
+Expected: <what should happen>
+Actual: <what happens, with measured numbers if it is visual>
+Repro: <props / minimal snippet>
+Workaround in the app: <none, or what you did and where, so it can be removed>"
+```
+
+Measure, don't eyeball: for a visual bug give the rendered size and offset (`getBoundingClientRect`)
+and the `size` prop — "icon 1.5px above centre at `sm`" gets fixed; "looks off" doesn't.
+
+**How it is tracked** — the issue is the record; there is no second list.
+
+| State | What it means | What you do |
+| --- | --- | --- |
+| Open | Reported, not yet fixed | Keep any workaround, and comment its file path on the issue |
+| Closed with a version | Fixed in the named beta/release, and the fix is under `### Fixed` in [CHANGELOG.md](CHANGELOG.md) citing the issue | Bump the pin to that version (exact, never a caret on a prerelease), **delete the workaround**, close your own follow-up |
+| Closed as `wontfix` / `invalid` / `duplicate` | Not changing, or already covered | Read the reason; the workaround stays, or use the issue it points to |
+
+Before reporting, search first — `gh issue list --repo pixelize-tech/Micro-Components --search "<component>" --state all`
+— and check the [CHANGELOG.md](CHANGELOG.md) shipped with your installed version; the gap may already
+be fixed in a newer beta.
+
+**Maintainers:** a fix closes its issue in the same change that lands it, and its CHANGELOG line
+names the issue number and the version that ships it. A workaround someone left in an app is only
+removable if the issue says which version fixes it, so never close without naming one.
+
+---
+
+## 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.
+
+---
+
+## Choosing between components
+
+### Segmented control look — `SegmentedControl` / `Toggle/TableToggle`
+
+Both take `variant?: "default" | "brandSlide" | "underlineSlide"` (default `"default"` — always
+opt-in, never assume a non-default look).
+
+| Context | `variant` | Look |
+| --- | --- | --- |
+| Most call sites — settings rows, filters, table view switches | `"default"` | Neutral chip |
+| The primary, hard-to-miss view switcher on a page (not a dense toolbar) | `"brandSlide"` | Solid brand-filled pill slides behind the active segment |
+| A dense toolbar, table header, or anywhere a boxed control feels heavy | `"underlineSlide"` | Thin brand-colored bar glides under the active label, no fill/chip |
+
+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.
+
+**`brandSlide` no longer guesses its backdrop — and `surface` is now optional.** Until
+2.4.2-beta.46 the track was an 8% brand tint composited over the **page canvas**, and the inactive
+label's ink was lifted against that same assumed canvas. Dropped into a brand-filled header both
+went wrong at once: the tint sank into the bar, and the label landed at **1.03–2.03:1** — rendered,
+effectively invisible. The track is now an opaque plate (`colors.surfaceRaised`) whatever it sits
+on, so a control on a coloured bar is readable with no prop passed (rest ink 7.58–18.39:1).
+
+Pass `surface` only to aim the plate's 1px edge at the real backdrop instead of the page canvas.
+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.
+
+```tsx
+<Box bg={theme.colors.primary[700]}>
+  <Switch ... surface={theme.colors.primary[700]} />   // optional: sharpens the plate's edge
+</Box>
+```
+
+### 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`.
+
+**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 |
+| --- | --- | --- |
+| `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` and the paginated `pagination.onScroll` shape (1-based `startIndex`/`limit`/`query`) have **no** equivalent in `Select` today; `isSelectAll`, `rightIcon`, `isFieldLoading`, `chipMaxLength`, `isChipRemovable` and `footerAction` (closes the popup, unlike `addNew`) now do. 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, 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`, `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
+
+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`.
+
+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
+`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 (paused while hovered or focused, never
+under reduced motion; `showPauseControl` adds a visible play/pause button) — no numeric value, min/max, or step. The
+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 package root — never
+`Slider`, and no longer from the `Primitives` barrel, which no longer carries it.
+
+### 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 |
+| 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 two-label segmented control (`leftText`/`rightText`), not a boolean; for a single on/off field use `ToggleSwitch` instead |
+
+**Apply:** "on vs off" is always `ToggleSwitch`; 2+ named options is always `SegmentedControl`.
+
+**`SegmentedControl`'s focus ring sits on the track, not the segment** (Button's two-tone ring). It is
+driven by a `:focus-visible` check in `onFocus`, so a mouse click stays ringless. `underlineSlide` has no
+track chrome, so its focused segment wears the ring instead.
+
+**A focus indicator must never be in a `transition` list.** The 0ms computed style is the transparent
+start value, so a screenshot or axe check taken on focus misses it. Field styles go through
+`FIELD_TRANSITION` (`Common/fieldStyles.ts`), which animates `border-color` and `background-color`
+only; keep `box-shadow` out of any transition you add around a field.
+
+**`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`
+
+| Need | Component | Why not the other |
+| --- | --- | --- |
+| Proportional share of a whole — slices sum to 100% | `ApexPieChart` | The default "part of a whole" chart; donut variants support a center total label |
+| Compare independent magnitudes on a shared radial grid — values need not sum to anything | `ApexPolarCharts` | Reads like a circular bar chart, not a pie; picking Pie here makes unrelated values look like they must add to 100% |
+
+### Which "button" — `Button` / `ButtonGroupIcon`
+
+| Need | Component | Why not the other |
+| --- | --- | --- |
+| A single themed, interactive button — any variant/size/colorScheme, dark-mode aware | `Button` | `ButtonGroupIcon` is a fixed icon + text + icon row, not a general button |
+| A themed row of icon + text + icon, optionally a dropdown menu on the right | `ButtonGroupIcon` | `Button` is one control; this row wires the left, center and right slots and the dropdown for you |
+
+A gray `ghost` or `outline` `Button` is built for a card, a toolbar or a panel, where its hover step
+reads. On the bare page canvas in light mode the hover fill measures only 1.076-1.124:1 against
+the canvas across the nine brands (above 1.15:1 on a card), so the hover is faint there. A gray
+ghost button that sits directly on `backgroundColor.base` should sit on a `Card` or panel surface
+instead.
+
+### Which "card" — `Card` / `ProductCard` / `StatCard` / `PaymentCard`
+
+| Need | Component | Why not the others |
+| --- | --- | --- |
+| Generic padded container (borderless by default; `variant="outline"` for a ruled one), no commerce semantics | `Card` | Layout wrapper with `header`/`footer` slots and a padded body — see gotcha below |
+| Product tile for a grid, list or rail (photo, price, rating, swatches, quick add) | `ProductCard` | Takes the same `axes` / `variants` as `ProductDetails`; for a whole page use `ProductDetails` |
+| A KPI figure with delta and sparkline | `StatCard` | Not a product or a container |
+| Subscription/pricing-tier card (plans, billing cycle, feature list) | `PaymentCard` | Takes a `Plan` object, unrelated to `options`/`productImage` |
+
+### Managing organizations — `OrganizationDetails` vs `OrgSwitcher`
+
+| Doing | Component | Why not the other |
+| --- | --- | --- |
+| Quickly changing which org is active for the current session (navbar/header) | `OrgSwitcher` | Compact trigger + searchable popover; no create/rename/delete — session-scoped |
+| Managing the org list — rename, delete, accept/decline invites, create new, set a persisted default | `OrganizationDetails` | Full admin panel with bundled CRUD modals; `default`/`onSetDefault` is a persisted preference, not OrgSwitcher's session-scoped `value`/`onChange` |
+
+### Plan/upgrade cluster — `UpgradeButton` / `PlanPill` / `PlanBadge` / `LimitReachedModal`
+
+| Doing | Component | Why not the others |
+| --- | --- | --- |
+| A prominent, animated "upgrade now" CTA button | `UpgradeButton` | Shimmer/hover-lift button with size variants |
+| Showing a plan-state badge and you already have label/tone/copy decided | `PlanPill` | Presentational only — no resolution logic |
+| Showing the top-bar plan-name/"upgrade" badge from raw org plan data | `PlanBadge` | Wraps `PlanPill` with `resolvePlanBadge()`; renders nothing if `canManageBilling` is falsy |
+| Blocking a user who hit a plan limit, with an explanation and upgrade path | `LimitReachedModal` | Full modal, fully controlled, reuses `UpgradeButton` as its own CTA |
+
+### Top-of-app navigation — `NavigationBar` / `Header` / `SideBar` / `AppSwitcher` / `WorkspaceWindow`
+
+| Need | Component | Why not the others |
+| --- | --- | --- |
+| Top bar: back control + user-avatar profile/logout dropdown | `NavigationBar` | No page-nav links at all — `navMenu` is only the avatar dropdown's own items |
+| Top bar: horizontal page links with active-state highlighting + submenus | `Header` | Desktop submenus are hover-only, see gotcha below; the bar is `min-height: 4.3rem` and grows when the nav wraps |
+| Collapsible/dockable left rail — primary in-app navigation + secondary panel | `SideBar` | The persistent nav shell, not for switching between whole apps |
+| In-app launcher: browse modules, pins, recents, search | `NavLauncher` opened by a `LauncherTrigger` in `NavigationBar`'s `leading` | An app-owned screen registry, not a cross-app switcher; pins can also surface in `SideBar` `pinnedItems` |
+| Key cap or chord hint (`mod+k`) | `Kbd` / `KbdShortcut` | Never hand-style a `<kbd>`; `Search` and `AppSwitcher` already use it |
+| Cross-app launcher (CRM/HRMS/Tickets/Billing/...) | `AppSwitcher` (list from `resolveSuiteApps`; `buildSuiteApps` throws on plain `localhost` unless `devFallbackBaseUrl` is set) | Two-column popover grid of separate app origins — `SideBar`'s `otherApps` is the legacy predecessor; don't wire both into one shell |
+| Floating Jira-style dialog to view/edit one record without leaving the page | `WorkspaceWindow` | Modal-based floating panel, not page navigation; pairs with `WorkspaceTray` |
+
+### File pickers — `FileUpload` vs `FileUploader`
+
+| Need | Component | Why |
+| --- | --- | --- |
+| Real `File`/Blob objects to actually upload (FormData/API) | `FileUpload` | Controlled; `onFilesUploaded` carries real `File[]` and validates accept/size with rejection messages |
+| Self-contained "add photos, see thumbnails, remove" list with no server upload | `FileUploader` | Manages its own state; its `onFilesChange` metadata discards the real `File` — see gotcha below |
+
+Both files declare a type named `FileUploaderProps`. The one at the package root describes `FileUpload` (`FileUpload/FileUploadProps.tsx`); `FileUploader`'s own props type (`FileUploader/FileUploaderProps.tsx`) is not exported, only its `UploadedFile`. Check which folder a type came from before trusting the name.
+
+### 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; `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`, `.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.
+
+`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 optional and derive a soft tint from `tone`; if you pass them, read them from `useCustomTheme()` — a hardcoded hex is stuck in light mode. For a delete that names the record, pass `entityName` (+ `entityKind`, `dependents`, `consequence`, `alternative`) instead of hand-building the body; focus opens on Cancel, never the destructive button, and `focusCancelOnOpen={false}` moves it to the close button, not Confirm.
+
+### 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 |
+| "Nothing matches your filters" | `FilteredEmptyState` | Names the filters, offers Clear and Remove-last; in a boundary use `isEmpty` + `isFiltered` |
+| A failed load with retry | `ErrorState` | `role="alert"`, `onRetry`/`isRetrying` built in |
+| One fetch that can be loading, forbidden, failed, empty or ready | `QueryStateBoundary` | Picks for you: loading > forbidden > error > empty > `children` |
+
+---
+
+## Known gotchas (silent failures)
+
+### `withTheme` mounts a full provider stack per wrapped instance
+
+Each wrapped component gets its own `ChakraProvider` (CSS reset, global styles, CSS variables), `ToasterProvider` and `ColorModeScript`. Wrap the app root once with `PixelizeThemeProvider`; never wrap list items or repeated rows.
+
+### `SearchSelect` with `insideSelect` shows a second `role="listbox"` while open
+
+A test that finds the main dropdown with `getByRole("listbox")` must now pick it by id (`<id>-listbox`).
+
+### `ChoiceCardGroup`'s children must be `ChoiceCard` elements
+
+A wrapper component hides each card's `value` and `disabled` / `isDisabled` from the roving tab stop, so with
+nothing selected the group has no Tab stop at all (same rule as `PaymentOptionGroup` / `AddressCardGroup`).
+`ChoiceCard` takes `disabled` or its `isDisabled` alias; `AddressCard` and `PaymentOption` still take
+`disabled` only. The group is a column; `columns={n}` (n above 1) lays it out as an n-column grid.
+
+### `Pagination` never resets `page` for you
+
+An out-of-range `page` (a filter shrank the result) is displayed clamped but never reported, and changing
+rows per page does not reset `page` either. Reset it yourself, in `onPageSizeChange` and when the filters change.
+
+### A component with a behaviour its props do not hint at
+
+- `NoteTextArea`'s `handleCancel` always receives `false`, and `handleSubmit` is called with three arguments although its type declares a fourth (both tagged `@deprecated`).
+
+### Where `ref` lands, and what does not take one
+
+`Checkbox`, `RadioButton`, `ToggleSwitch` and `DatePicker` (every mode) forward to the native `<input>`.
+`SegmentedControl` forwards to the radiogroup `<div>`, not a segment; `Tab` to its tab `<button>` (`Tabs`
+itself takes no ref); `Avatar` to the outer box; `Tag` to its root, which is a `<button>` only for
+`display="dot"` with `onTagClick`, so type that ref as `HTMLElement`. `PinInput`, `FileUpload`,
+`SettingRow` and `Tabs` do not forward a ref.
+
+### Root attributes on the page primitives, and `Skeletons` props that are ignored
+
+`PageHeader`, `StatCard`, `SaveBar`, `EmptyState`, `DescriptionList`, `FilterBar` and `Skeletons` put
+`className`, `style`, `id`, `data-*` and `aria-*` on their outermost element. `StatCard` applies
+`aria-label` only when `onClick` makes it a button; `DescriptionList`'s loading grid keeps its own
+`aria-label="Loading"`. `Skeletons` still accepts `alignSelf` and `flexShrink`, now `@deprecated`, but never
+applies them; wrap it in a `Box` to position it.
+
+### `Table` `HeaderActions` item with `customComponent` and `onClick` is mouse-only unless the custom component is focusable
+
+The wrapper is deliberately not a button; make the custom component a button, or the action cannot be reached from the keyboard.
+
+### 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`. 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: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` | 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 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` | — |
+| `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 `elevated` (borderless, `shadows.card`). Label colour `text[700]`; helper/error row 12px | `size`/`variant` props |
+| `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; 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) | — |
+| `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 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 | — |
+| `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.
+
+### `CONTROL_SIZES` (fields) and `BUTTON_SIZES` (buttons) are separate scales — changing one never changes the other
+
+Fields/selects (`TextInput`, `Select`, `MultiSelect`, `SearchSelect`, `NumberInput`, `PinInput`, the
+`DatePicker` family, …) read `CONTROL_SIZES` — xs 32 · sm 38 · md 40 · lg 48. `Button` and every
+button-like trigger (`SegmentedControl`, `Tabs`, `TableToggle`, `Dropdown`'s trigger) read the
+separate `BUTTON_SIZES` — xs 24 · sm 32 · md 40 · lg 48. They used to share one token, which is what
+let a field-only size bump leak into buttons — the split is now gate-tested
+(`Common/sizeScaleOwnership.test.ts`).
+
+**Apply:** a PR that "just" bumps a form-field size should never touch `Button.styles.ts`,
+`SegmentedControl`, `Tab`, `TableToggle` or `Dropdown` — if it does, it's reading the wrong token.
+
+### `controlSizeStyles()`'s `minH` silently overrides a smaller `h` override
+
+`fieldStyles.ts`'s `controlSizeStyles()` sets both `h` and `minH` to the same token value. A caller
+overriding only `h` with a smaller literal compiles and renders, but the inherited `minH` still
+wins, so the field stays at the token height.
+
+**Apply:** override both `h` and `minH` together, or don't override either.
+
+### `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.
+
+### `Tag display="dot"` ignores `variant` and icons; `StatusTag` renders an unknown status neutral
+
+`display="dot"` ignores `variant`, `icon`, `leadingIcon` and `onIconClick`. `StatusTag`'s `map` is
+keyed by your status union, but a runtime value outside it (API drift) renders a neutral chip and
+only warns in development — guard upstream if a silent neutral would mislead.
+
+### 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.
+
+### Brand palettes and non-default themes are lazy; library style functions may return cached objects
+
+Before its first read, a brand palette or a non-default light theme is an object of getters. Reading
+any key turns it into plain data; spread, `Object.keys`, JSON and assignment behave as before, but
+`Object.getOwnPropertyDescriptor` reports an accessor until then. Style functions in a library
+theme's `theme.components` receive props through a tracking Proxy and may return a cached object, so
+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`;
+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.
+
+A popup opened inside another popup takes `zIndex="popoverNested"` (1510), never `skipLink` (1600).
+`fontSize="xs-plus"` is 13px, the control size; use it instead of a `13px` literal.
+
+### Your own overlay painted `background[50]` sinks into the dark canvas
+
+In dark mode `background[50]` is the card plane, one step above the canvas; an overlay painted with it
+merges into the cards under it. Library dialogs, drawers, popovers and menus paint `colors.surfaceRaised`,
+one step above the card in dark and identical `#ffffff` in light. A custom panel, popover or
+`ModalContent bg=` should read `surfaceRaised` too, and a divider inside it `raisedRule(colors)`.
+
+### Named fills nearly vanish on a dark card
+
+In dark mode `backgroundColor.light`, `tertiary`, `medium` and `tableHeader` sit only 1.01-1.05:1 off
+`background[50]`, `muted` 1.00-1.06:1 off `surfaceRaised`, and `boxborder[200]` 1.10-1.16:1 off a card and
+1.00-1.06:1 off `surfaceRaised`. Never paint a named canvas fill or raw `boxborder[200]` on a card or overlay:
+use `bandOn(fill, surface)` for a header strip, hover or selection tint, `recessOn(fill, surface)` for a shaded
+or off cell, `cardRule(colors)` for a rule inside a card and `raisedRule(colors)` for a rule inside an overlay.
+All four return the old value unchanged in light mode.
+
+### A Chakra `ModalHeader` inside a coloured box keeps its own ink
+
+The theme gives `ModalHeader` `color: colors.header[900]` and a bottom rule. Wrapping it in a
+`Box bgGradient=… color={ink}` does not recolour it: the header paints `header[900]` itself, so the
+title is dark navy on a blue/purple gradient (3.11–4.11:1 in light across the 9 brands, against
+4.62:1 for the gradient's own ink). Icons and badges inside it that read `currentColor` follow the
+header, not the box.
+
+**Apply:** put the ink on the header itself — `<ModalHeader color={resolved.ink} borderBottomWidth={0}>`
+with `resolved = resolveGradient(stops, colors.white, colors.black)` — or use `LimitReachedModal`.
+For an accent icon on the gradient, use `resolved.ink` unless the accent clears 3:1 on both
+`resolved.from` and `resolved.to`; a theme `yellow[300]` drops to 2.61:1 in dark.
+
+### `Drawer` / `Modal` / `ProfileCard` drop any child that isn't a named slot — use `portalChildren`
+
+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; 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.
+
+**Apply:** pass a nested confirm dialog, toast host or live region to `Drawer` / `Modal` as
+`portalChildren`. It renders **inside** the dialog content after the slots (a sibling in the portal
+would be `aria-hidden` by Chakra, so a live region there is never announced); a nested `AlertDialog`
+portals out on its own, stacks above and returns focus. It unmounts with the dialog, so reset its
+open state when the parent closes. `ProfileCard` has no such prop — keep its confirm dialog outside,
+as a sibling in a wrapping fragment. When a ternary picks between bodies, branch into a variable
+rendered inside one body slot, rather than returning fragment-wrapped slots per branch. `Drawer`'s
+misspelled `vaiant` is `@deprecated` — use `variant`.
+
+A `Drawer` with no `DrawerHeader` is an unnamed dialog (axe `aria-dialog-name`) unless you pass its own
+`aria-label` or `aria-labelledby`; dev builds warn once when it opens. `contentProps["aria-labelledby"]` is
+overwritten, so it never names the drawer (`contentProps["aria-label"]` is kept).
+
+### `FormDrawer` has no browser validation, and its submit button sits outside the `<form>`
+
+It sets `noValidate`: validate in `onSubmit` and pass messages via `errors`. Error-summary focus
+fires only after a submit; if validation is async, set `isSubmitting` synchronously in `onSubmit` so
+focus waits for the result, otherwise errors that arrive later are not focused. The footer submit
+button is tied to the form with the `form` attribute — Enter-to-submit works in browsers, but
+jsdom / user-event only simulates it for a form with exactly one text field, so use
+`fireEvent.submit(form)` in tests. `isSubmitDisabled` swallows both: `onSubmit` is not called while it is true.
+
+### `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.
+
+### `QueryStateBoundary` `isForbidden` and `hasData`
+
+An `isForbidden` function is only called when `error` is set (never with `undefined`); `isForbidden:
+true` shows the panel even with no error. `isLoading` + `hasData` keeps `children` visible during a
+refetch, so pass `hasData` only when data is genuinely loaded — otherwise a first load shows a blank
+region.
+
+### `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.
+
+### `CircularProgress` `tone="info"` is the brand primary, not blue
+
+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 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
+`filled` for fields whose position is already obvious from the layout.
+
+### 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:** prefer `Select` (`native={false}`) for new work — `SelectSearch` is not deprecated, but `Select` 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` with `onSearchChange` no longer filters locally (beta.48)
+
+Passing `onSearchChange` means the server owns matching, so `Select` stops applying its own
+substring filter to `options`. Before this, a fuzzy or ranked server result whose label did not
+literally contain the typed text was fetched and then hidden. Pass `filterOptions={true}` to keep
+the local pass on top, or `filterOptions={false}` to drop it even without `onSearchChange`.
+
+**Apply:** if a server-backed `Select` suddenly shows more rows than it used to, that is this fix,
+not a regression. Paged `Select`s should also pass `hasMore={false}` once the last page lands —
+without it, `onLoadMore` fires again every time the user reaches the bottom.
+
+### `Select` with `isMulti` keeps picks that leave `options` (beta.48)
+
+`onChange` used to be built from the options currently in the list, so replacing `options` with a
+server-search result silently dropped every earlier pick the new page did not contain — the chips
+vanished and the next selection emitted a truncated array. Selected options are now remembered
+independently of `options`.
+
+**Apply:** nothing to change. If you worked around this by merging the old selection back in
+yourself, that workaround is now redundant.
+
+### `Table`'s column search covers every page (beta.48)
+
+The per-column search box used to run after the page slice, so it matched only the rows on screen
+while the pager still counted the whole data set. It now runs first: the page count, the
+`1 - 20 of N` readout and the rows all come from the matched set, and a new search returns to page
+1. Under `paginationMode="server"` the client still only sees the loaded page — filter on the
+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.
+The built-in `placeholder` renders as its own empty-value option, which isn't in `options` — so
+picking it resolves to no match and nothing fires. An "Any / All / None" reset built on the
+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. With
+`isReadOnly`, `onChange` never fires at all.
+
+### `MultiSelect` is an email-chip input, not a picker
+
+Despite the name, `MultiSelect` takes **no `options` prop at all**. Typed text is validated as an
+email address and rejected if it doesn't match — there is no way to choose from a product/entity
+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
+
+Row-click is gated **per column**, not per row: a column supplying a custom `node` renderer
+swallows the click on that cell. Give every column a `node` and `onRowClick` becomes dead code —
+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.
+
+Setting `onRowClick` makes every row a tab stop: Enter or Space on the focused row (not on a checkbox,
+button or link inside it) fires `onRowClick` with the first visible column that has no `node`. A table
+without `onRowClick`, one whose every column has a `node`, and a table that is `isLoading` get no tab
+stop. The column resize handle is a bare `div` with a `mousedown` handler and is unreachable by keyboard.
+
+**Apply:** expect one extra Tab stop per row once you pass `onRowClick`, and update any tab-order test.
+Controls inside a row keep their own keys; give a `node` column a real `Button` or link for the actions
+that must not depend on the row.
+
+### `Table.renderRowDetail` runs for every row on every render, and `expandedRows` ids match strictly
+
+It decides whether each row gets a chevron, so an inline function re-renders every row (defeating
+`TableRow`'s memo) — wrap it in `useCallback` / `useMemo`. `expandedRows` ids compare with `===`, so
+`1` and `"1"` are different: keep the id type the same as `row.id`. It is not the older
+`row.content` + `isContent` expander (chevron before the checkbox, index-based); both can coexist,
+but only `row.content` still disables grouped virtualisation.
+
+### `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`) 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.
+
+### A wrapper presetting a prop must destructure with a default, not rely on JSX prop order
+
+Wrapping a library component to preset a prop (e.g. `Table`'s `variant`) as
+`<Table variant="classic" {...props} />` silently reverts to the library's own default the moment a
+caller passes `variant={undefined}` — a later spread always wins in JSX, even with `undefined`,
+and the library component resolves that `undefined` via its own default parameter.
+
+**Apply:**
+```tsx
+const AppTable = ({ variant = 'classic', ...props }: TableProps) => <Table variant={variant} {...props} />;
+```
+Applies to any library prop with a default value, not just `Table`'s `variant`.
+
+### `FormWrapper` forwards extra props to the outer wrapper only
+
+`id`, `data-*`, `aria-*`, `className`, `style` and handlers land on the outermost `Box`; the bordered content `Box`
+receives nothing, and `children` is not type-matched.
+
+**Apply:** put a margin override on `FormWrapper` itself (`className`/`style`); there is no prop for the content box's padding or border.
+
+### `ContactForm`'s `apiKey` prop is a POST URL, not an auth token
+
+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, pass `onSubmit`
+and make the request yourself.
+
+### `ContactForm` can't tell its parent the submission result
+
+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:** 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"
+
+It wraps Chakra's `PinInput` without forwarding a `type`, so Chakra's `type="number"` default
+applies — any letter typed is silently rejected (the character never appears, no error shown).
+`VerifyEmailOtpProps` has no `type` field and no `...rest` escape hatch. Its `description` also gets
+a second line, "your new Pixel Account", unless you pass `subtitle` (`""` drops it).
+
+**Apply:** only use this component for numeric-only OTPs. Always pass `subtitle` outside the Pixel Account
+product; for a non-English UI pass `labels`. For an alphanumeric code build the card from `PinInput`.
+
+### `ApexLineChart` only ever renders one line, frozen at mount
+
+`data`/`series` changes after the first render are silently ignored unless the component remounts
+(no effect syncs later prop changes into state); `series` only reads index 0 for the line's name
+despite the plural name; `variant="realtime"` replaces your data with random numbers on an interval
+rather than animating it. Its `legendStyle` prop also type-checks but has no effect, unlike the
+identical prop on `ApexPieChart`/`ApexPolarCharts`.
+
+**Apply:** remount (`key`) `ApexLineChart` when the underlying data changes. Don't use
+`variant="realtime"` expecting it to reflect a live feed.
+
+### `ApexPieChart`'s `showDataLabels` can be silently overridden by chart height
+
+With the default `labelPlacement="auto"`, a **numeric** `height` under 240 forces labels off even
+with `showDataLabels={true}` — no warning. Slices under `minLabelPercent` (default 8%) render blank
+label text rather than being hidden as a unit.
+
+**Apply:** pass `labelPlacement="inside"`/`"outside"` explicitly for small numeric-height charts;
+lower `minLabelPercent` when every slice needs a visible value.
+
+### `ApexBarChart` and `ApexAreaChart` silently drop `data` when `series` is also passed
+
+`series` always wins over `data` with no warning, on both components — a natural mistake when
+migrating from single- to multi-series. Separately, `ApexBarChart`'s `barColor` array only paints one
+color per bar when `distributed={true}`; with the default `false`, every bar takes `barColor[0]` and
+the rest of the array is silently unused. `ApexRadialChart`'s `hollowSize` has its own unrelated trap
+— it's silently overridden to a fixed `"52%"` whenever `variant="multi"`.
+
+**Apply:** never pass `data` and `series` together on `ApexBarChart`/`ApexAreaChart`. Set
+`distributed` whenever `ApexBarChart`'s `barColor` has more than one color. Don't expect
+`ApexRadialChart`'s `hollowSize` to apply under `variant="multi"`.
+
+### `Skeletons`' `isLoaded` and `borderRadius` only work for `type="skeleton"`
+
+`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 `circle`/`text`, control visibility by conditionally rendering the `Skeletons` element
+itself, not via `isLoaded`.
+
+### Five exports start with `Notification` and only one of them is a notification tray
+
+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.
+
+| 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
+
+`onClick` is wired solely to the title text — the card, avatar, and description are not clickable
+despite the generic prop name. Separately, `warningColor`/`errorColor`/`successColor` only take
+effect when `showStatus` is also `true`, and populating `notification.status` (e.g. `"blocked"`) has
+no effect at all — the dot's color comes purely from `dueDate`/`endDate` math.
+
+**Apply:** for a fully clickable card, wrap it yourself with your own `onClick`. Always pair the
+three color overrides with `showStatus`; don't use `status` to drive dot color.
+
+### `FeedbackForm` shows a success toast and resets even with no `onSubmit`/`submitUrl`
+
+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 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
+toast actually appears if embedding inside a `Modal`.
+
+### `Checkbox`'s `variant` is a no-op
+
+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
+
+The main track sorts `images` by `order`; the pagination dots map over the unsorted array. Passing
+`images` out of `order` sequence makes the active dot point at the wrong slide.
+
+**Apply:** pre-sort `images` by `order` before passing them in.
+
+### `TextLabel`'s `isInformation` alone renders no icon — it also needs `informationMessage`
+
+The info-tooltip icon is gated on `isInformation && informationMessage` — both must be truthy or
+nothing renders, not even a bare icon. `TextLabel` is the shared label engine behind most fields in
+the library (`TextInput`, `NumberInput`, `PhoneNumberInput`, `RadioButton`, `PinInput`,
+`InputSwitch`, `SelectV2`, the `DatePicker` family, `InputTextArea`, `SelectSearch`, `Search`,
+`SearchSelect`, `MultiSelect`, `Select`), so the same silent no-op repeats at every one of them.
+
+**Apply:** always pass `isInformation` and `informationMessage` together; never treat
+`isInformation` alone as "use a default message."
+
+### `Timeline`'s `onEditNote` editor doesn't auto-close without `editNoteLoading` — unlike add-note
+
+Add-note has a back-compat fallback that closes its editor immediately if `addNoteLoading` is never
+wired. Edit-note has no equivalent fallback — its only close path is an effect watching
+`editNoteLoading` transition `true → false`. Wire `onEditNote` without `editNoteLoading` and Save
+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 `@deprecated` and still renders nothing
+
+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
+
+An event whose formatted date resolves to `"Invalid Date"` is excluded from every date group — not
+shown in a fallback bucket, just gone. The only signal is a `console.warn` inside the formatter.
+
+**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
+
+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.
+
+**Apply:** compare source/destination index (or diff the array) before persisting a reorder, if a
+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` isn't exported from the package at all
+
+`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.
+
+### `KanbanActions` is exported but still not wired into `KanbanBoard`
+
+`KanbanBoard`'s header select/edit/create bar is driven by its own `kanbanSelect`/`kanbanEdit`/
+`kanbanCreate` props, via a different internal component. `KanbanActions` is a separate, standalone
+component (exported from the package root as of 2.4.2-beta.39) that a consumer must render and wire
+up itself — its `options`-driven buttons always render with no permission gating, unlike
+`KanbanBoard`'s own header actions, which respect `permissions.isEditable`/`isCreatable`.
+
+**Apply:** use `KanbanBoard`'s own `kanbanSelect`/`kanbanEdit`/`kanbanCreate` props for the board's
+built-in header actions. Reach for `KanbanActions` only when building a custom toolbar outside
+`KanbanBoard`, and gate it yourself — it has no permissions awareness of its own.
+
+### `KanbanBoard`'s `permissions.isEditable: false` disables card drag but not column-reorder drag
+
+Card `Draggable`s get `isDragDisabled={!canDrag}`; the column-reorder `Draggable` (active when
+`enableColumnReorder` is true) never checks it — a "read-only" board still lets users reorder whole
+columns.
+
+**Apply:** also set `enableColumnReorder={false}` to fully lock a read-only board.
+
+### `KanbanBoard`'s `collapsedColumns` only seeds initial state — not a live controlled prop
+
+It seeds a `useState` lazy initializer once, on mount. Without the `preferences` feature wired, a
+later render passing a different `collapsedColumns` value does nothing, despite the name implying a
+controlled value.
+
+**Apply:** to force a column open/closed post-mount without `preferences`, remount the board (change
+its `key`) rather than re-passing the prop.
+
+### `KanbanBoard`'s `account.customNode` silently drops delete/open/expand for that one card
+
+An item with `customNode` set renders that function instead of `AccountCard`, so `onDelete`,
+`onOpen`, `isDeletable`, and expand/collapse never apply — even though they read as board-wide
+props. Mixing plain and `customNode` items in one column produces inconsistent per-card behavior.
+
+**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
+
+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 run through `toWords`, which splits snake_case, kebab-case and camelCase:
+`account_name` renders "Account Name" and `nextFollowUp` renders "Next Follow Up".
+
+**Apply:** keep numeric display values as strings.
+
+### `KanbanBoard`'s `onColumnDelete` receives the deleted column's **card** ids, not the column's id
+
+Despite the callback parameter being named `colId`-adjacent, what's actually passed is
+`columns[colId].items.map(item => item.id)` — the cards that were in the column, never the column's
+own id.
+
+**Apply:** track which column was being deleted another way (e.g. hover/selection state captured
+before the click) if you need the column id itself.
+
+### `isRequired` is decorative on some fields, native on others — same prop name, different behavior
+
+`NumberInput` sets 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.
+
+### `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
+separate success/failure signal, so a parent that turns off the loading flag after a failed save
+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).
+
+### `InputSwitch` now renders `ToggleSwitch` — `.chakra-switch__*` selectors match nothing
+
+`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.
+
+**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", …)`.
+
+Same shape of trap on `Tabs`: the owned `Tab` forwards no `data-testid`, so `getByTestId("…-tab-…")`
+queries must become `getByRole("tab", { name })`.
+
+### `AlertDialog`'s `colorScheme`/`size`/`status`/`variant`/`addRole` are dead props
+
+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`'s `onClose` also fires on Escape and overlay click
+
+`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
+
+The truncation ref only attaches when `children` passes `React.isValidElement` — a bare string, a
+Fragment, or multiple children skip that branch, so the tooltip always shows instead of
+only-when-truncated (the opposite of the prop's contract).
+
+**Apply:** give `overflowOnly`/`OverflowToolTip` exactly one real element as `children` (e.g. a
+single `Text noOfLines`), never a Fragment or bare text.
+
+### `ToolTip` mounts Chakra's tooltip only after the first hover or focus
+
+Until the trigger is hovered or focused (or `isOpen`/`defaultIsOpen` is set), `ToolTip` renders just the
+child, with no tooltip element and no document listeners. A test that mocks Chakra's `Tooltip` and
+expects it mounted at render time must hover or focus the trigger first
+(`fireEvent.pointerEnter(trigger)` or `userEvent.hover`).
+
+### A keyboard-focusable `ToolTip` trigger must be a native control — never a `span` with `aria-label`
+
+`ToolTip` adds `aria-describedby` to its trigger but no role and no name. An icon-only trigger written
+`<Box as="span" tabIndex={0} aria-label={hint}>` (a column-header hint, an info icon) fails axe
+`aria-prohibited-attr`: `aria-label` is not allowed on a role-less span, so a conforming screen reader may drop
+it and announce a nameless generic element (Chrome's tree still shows the name).
+
+**Apply:** use `<Box as="button" type="button" aria-label={hint} bg="transparent" border="0" p={0}
+cursor="default">`. It is still a Tab stop and the tooltip still opens on focus; measured pixel-identical to
+the span, closed and focused. `role="img"` on the span also passes axe but changes the focused state.
+
+### `Toaster`'s `showToast({ children })` is a dead prop, and its two `onClose`s are different functions
+
+`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.
+
+### `ButtonGroupIcon`'s dropdown needs `rightIcon` **and** `rightIconDropdown` both set
+
+The `Menu`/`dropdownOptions` branch only renders inside `rightIcon && rightIconDropdown`. Supplying
+`dropdownOptions` alone, or `rightIconDropdown` without `rightIcon`, silently renders nothing on the
+right side. Separately, `onButtongroupClick` is wired to Chakra `ButtonGroup`'s own `onClick` on the
+wrapping div — native DOM bubbling means it fires on every click inside the group (left icon, center
+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.
+
+### `Card` already wraps `children` in a padded `CardBody` — a nested one doubles the padding
+
+`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:** drop the nested `CardBody`, or pass `bodyProps={{ p: 0 }}`.
+
+To change the padding, use `padding="none" | "2xs" | "xs" | "sm" | "md" | "lg"`. `sx={{ p: ... }}` on
+the container *adds* to the body padding (double inset) and `sx={{ p: 0 }}` does nothing. `padding`
+is no longer Chakra's style prop (omitted from the type) — use `p` for a raw value. With
+`padding="none"` the header keeps `xs` padding.
+
+### Commerce kit — read before building a shop screen
+
+`ProductCard`, `ProductDetails`, `VariantSelector` and the bag pieces share one contract: pass
+`axes: OptionAxis[]` + `variants: ProductVariant[]`, never per-vertical props. A variant's
+`options` must set every axis, or `findVariant` returns `undefined`.
+
+- **`layout="auto"` on `MediaGallery` and `ProductDetails` follows the container, not the window**
+  (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`.
+- **`OptionChip` `unavailable` is visual and announced only** — `onSelect` still fires so a parent
+  can re-derive the other axes. Guard it yourself if the pick must be refused.
+- **`WishlistToggle` flips its default name and `aria-pressed` together** — on cards pass a fixed
+  `label` (`Save ${title}`).
+- **Group children must be direct children.** `AddressCardGroup` / `PaymentOptionGroup` read the
+  roving tab stop from their children's `value`; a wrapper component hides it.
+- **`BagBar` and `StickyBuyBar` are CSS-sticky, not fixed.** Make them the last child of the
+  scrolling container; `StickyBuyBar` also needs a parent taller than the viewport.
+- **"N left" appears only from a real `stock` count** at or below `LOW_STOCK_THRESHOLD` (5).
+
+### `PaymentCard`'s `onHover` never fires its `"card"` variant, and the CTA hides unless `isRenewal`
+
+`onHover`'s type promises `"card" | "button"`, but no hover handler exists on the outer plan card —
+only the CTA button wires hover. Separately, the CTA (and its callbacks) disappears whenever
+`isActive` is true unless `isRenewal` is also set, regardless of `plan.buttonText`.
+
+**Apply:** don't build "card" hover analytics on this prop. Pass `isRenewal` to show a CTA on the
+current/active plan.
+
+### `OrganizationDetails`' `defaultOrg === 1` silently overrides an explicit `canDelete: true`
+
+`isProtected` is computed as `item.defaultOrg === 1 || canProtect` — `defaultOrg` short-circuits the
+`canDelete`/role check unconditionally. An org that is both the user's default and marked
+`canDelete: true` still renders a disabled delete button, with only a tooltip explaining why.
+
+**Apply:** don't rely on `canDelete` alone to guarantee delete is enabled — check `defaultOrg` too.
+
+### `OrganizationDetails`, `CustomModulesTable`'s create/edit/delete modals show no error UI on rejection
+
+`onCreateOrganization`/`onDeleteOrganization`/`onEditOrganization` (and `CustomModulesTable`'s
+`onUpdateModule`/`onDeleteModule`) are `await`ed and the modal only resets on success — a rejection
+is an unhandled promise rejection with zero visible feedback.
+
+**Apply:** wrap your own handler in try/catch and show your own error toast; the library never does
+it for you.
+
+### `OrgSwitcher`'s `onChange` doesn't fire on re-selecting the already-active org, and has a closed prop list
+
+Re-clicking the current org closes the popover but skips `onChange` entirely (`org.id !== value` gate)
+— don't rely on it for a side effect that must run on every click (analytics, refetch). Separately,
+the trigger has no `...rest`/`ref` escape hatch: a `data-testid`, `id`, or positioning `ref` can't
+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
+when its label truncates to nothing, and the title is the first thing to give way. With a long org name
+the title is invisible on 320-375px bars, and a smaller `maxWidth` does not change that.
+
+**Apply:** `display="auto"` (avatar + chevron below `md`, full from `md`) or `"avatar"`. Both layouts
+name the trigger `${ariaLabel}, ${org name}` (the placeholder when no org is active), and in avatar mode
+the name appears in a tooltip that wraps a `span` around the trigger, so don't pass the trigger a ref. `auto` falls back to `"full"` where
+`matchMedia` is missing (SSR, jsdom). `NavigationBar`'s `moreIcon` root is `min-width: 0`: give your
+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
+
+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.
+
+### `PlanPill`/`PlanBadge` always render as a real, focusable `<button>` — even with no `onClick`
+
+`as="button"`, `cursor="pointer"`, and the hover-lift are unconditional. Omitting the optional
+`onClick` does not get you a static/informational pill — it stays tabbable and screen-reader
+-announced as a button regardless.
+
+**Apply:** there is currently no way to get a non-interactive plan badge from this component.
+
+### `LimitReachedModal`'s `onUpgrade` never triggers `onClose`, and needs both `limit` and `used` to show usage
+
+Clicking the CTA calls only `onUpgrade` — confirmed by the component's own test. Separately, the
+inline usage line renders only when **both** `limit` and `used` are non-nullish; passing just one
+silently omits the whole line.
+
+**Apply:** close the modal yourself inside your `onUpgrade` handler if upgrading should dismiss it.
+Always pass `limit`/`used` together, or neither.
+
+### `CustomModulesTable`'s `ModuleItem.module_id` is the one snake_case field on an otherwise camelCase type
+
+A loosely-typed API response cast straight to `ModuleItem[]` can leave `module_id: undefined` with
+no compile error, colliding React `key`s.
+
+**Apply:** map the API field explicitly to `module_id` — don't assume this type is uniformly
+camelCase like its sibling payload type (`UpdateModulePayload.moduleId`).
+
+### `RolesPermission`'s permission matrix silently reroutes every column for an "Automation" row
+
+Any `permissions[]` row whose `module` case-insensitively equals `"automation"` collapses every
+column onto a single `automation` boolean — only the Read cell renders/toggles, and clicking it
+calls `onPermissionChange(module, "automation")`, not `"read"`. Separately, `roles_id` (typed
+`string`) is coerced via `Number()` before `onDeleteRole` fires — a UUID or ObjectId silently
+becomes `NaN`.
+
+**Apply:** if a row's `module` can be `"automation"`, expect only its Read checkbox to work, toggling
+`automation` — create/edit/delete/import/export are unreachable for that row. Only pass
+numeric-string `roles_id` values.
+
+### Several delete/deactivate modals close before their async handler can be awaited
+
+`RolesPermission`'s `DeleteRoleModal` and `UserDetails`' `DeactivateConfirmModal` call their
+handlers fire-and-forget (typed plain `() => void`) and close synchronously in the same tick — the
+opposite failure mode from the create/edit modals above, whose handlers are genuinely awaited.
+
+**Apply:** any `isLoading`/spinner wiring for delete/deactivate can never be seen — handle
+loading/error UI outside these two modals (e.g. a toast).
+
+### `UserDetails`' Change Role and Resend Invitation buttons silently no-op when `userId` is null
+
+Only Deactivate actually disables itself when `selectedUser.userId` is null — the other two stay
+visually enabled and do nothing on click. Separately, `ChangeRoleModal` pre-selects the current role
+by case-insensitive **label text** match, not an id — any mismatch (whitespace, a renamed role)
+silently opens the modal with nothing pre-selected, no error shown.
+
+**Apply:** always populate `selectedUser.userId` when those two actions should be usable. Keep
+`currentRole` as the exact display label kept in sync with `roleOptions[].label`.
+
+### `FileUploader`'s `onFilesChange` discards the real `File`, and its `acceptTypes`/`maxFiles` enforce nothing
+
+`FileUploader` hands back lightweight `{id, name, size, previewUrl}` metadata — the original `File`
+is discarded in `handleFiles`, so it can never back an actual upload. `acceptTypes` only sets the
+native picker's `accept` attribute; drag-and-drop ignores it completely and no code path rejects a
+wrong-type file. Exceeding `maxFiles` silently truncates the list with no error.
+
+**Apply:** need real file bytes or enforced validation → use `FileUpload`, not `FileUploader`.
+
+Each image's `previewUrl` is a `blob:` URL. `FileUploader` revokes it when the image is removed,
+truncated by `maxFiles`, rejected by `maxTotalSize` or still listed when it unmounts. Do not
+reuse a `previewUrl` from `onFilesChange` after the component is gone. (`FileUpload` revokes its own
+thumbnail URLs.)
+
+### `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
+whether `dateFormat` contains time tokens. Separately, every time-capable picker caps at minute
+granularity regardless of `dateFormat` — a format containing `ss` compiles and parses but seconds
+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.
+
+### `SingleDatePicker`/`TimeOnlyPicker` default to `Date` objects — opt into strings with `valueFormat="iso"`
+
+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:** use this instead of `TextInput type="date"/"time"` plus hand-rolled ISO parsing.
+
+### `TimeOnlyPicker` ignores the date-range props and `autoComplete`
+
+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
+
+`Editor` computes `config.theme`/`config.popupRoot` itself to fix Jodit's dark-mode/popup theming,
+then spreads your `config` on top — any `theme`/`popupRoot` key you pass wins and silently disables
+the fix. Separately, `key` is typed as if readable, but React reserves and strips it before the
+component sees `props`, so it's always `undefined` internally and can't force a remount. `editorRef`
+is also `null` until Jodit's lazy-loaded chunk resolves — a mount-time effect reading it gets nothing.
+
+**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` keeps Jodit's defaults for the source view, and those defaults (`sourceEditor: "ace"`,
+`beautifyHTML: true`) load Ace and js-beautify from `cdnjs.cloudflare.com` when the editor mounts.
+Under a strict Content-Security-Policy, offline, or in a privacy review, those requests are blocked
+or are an outbound call you did not ask for.
+
+**Apply:** pass `config={{ sourceEditor: "area", beautifyHTML: false }}` to drop both calls (source
+mode becomes a plain textarea), or point Jodit's `sourceEditorCDNUrlsJS` and `beautifyHTMLCDNUrlsJS`
+at copies you host.
+
+### `PdfViewer` `getBlob` — fetched on mount only; the toolbar already has Open and Download
+
+- **Swapping the file needs a new React `key`.** `getBlob` is read through a ref and fetched on mount,
+  so an inline arrow is safe, but changing it never refetches — the old document silently stays.
+- **The default fallback shows only a message while the toolbar is visible**; with
+  `showToolbar={false}` it adds its own Open and Download buttons. `getBlob` mode makes the toolbar's
+  actions work for authed files, so an app need not render its own — or pass `showToolbar={false}`.
+- Pass exactly one of `pdfUrl` / `getBlob`.
+
+### `WizardDialog` — `validate` must be pure; controlled `stepId` does not unlock steps
+
+`validate` runs on Continue, on Finish, and again for every step on Finish. Passing `stepId` controls
+the visible step only: stages past the furthest valid step stay disabled. Esc, close, Back and Cancel
+are disabled while `isFinishing`. With `chrome="inline"` there is no Modal at all: no focus trap, no Esc,
+no close X and no `role="dialog"` (the host window supplies them), `size` is ignored, and nothing renders
+while `isOpen` is false; Cancel still calls `onClose`, so the host must close itself there.
+
+### `PageHeader` actions wrap by default
+
+`actionsLayout` defaults to `"auto"`, so actions that do not fit drop below the title at `md`+. A
+test asserting the old single-row layout needs `actionsLayout="inline"`.
+
+### `Editor` merge fields — chips, raw values and stale closures
+
+- **Chips are `<span data-field contenteditable="false">`.** Do not style or strip `[data-field]` in
+  consumer CSS or sanitisers, and sanitise the raw `${path}` value `onChange` reports, not Jodit's HTML.
+- **A hand-typed `${path}` stays plain text** until `value` is next applied from outside; only tokens
+  inserted through the menu / `apiRef` or already present in `value` become chips. Unknown-token
+  detection still runs on the raw value.
+- **`config.extraButtons[].exec` goes stale** (the memo key is `JSON.stringify`, which drops functions).
+  Use `toolbarButtons` — React buttons, always current.
+- **`jodit-react` binds `onChange` / `onBlur` once, keyed on handler identity, not `config`.** After
+  Jodit is re-created (readonly or height change) a stable handler stops receiving events. `Editor`
+  binds them itself per instance; don't copy the pattern when wrapping Jodit directly.
+
+- **`EditorMergeField` `object`, `objectDescription`, `description`, `example`, `source` and `image` do nothing inside
+  `Editor`.** They are metadata for a field browser you build; only `path`, `label`, `group` and `sample` are read.
+
+### `toCsv` — no BOM by default, and formula-like text gains a `'`
+
+Excel reads a BOM-less CSV as ANSI and garbles non-ASCII text: pass `{ bom: true }` when the file is for Excel. A cell
+starting with `=`, `+`, `-` or `@` (a signed plain number excepted) is written with a leading `'`; set
+`escapeFormulas: false` on a column such as phone numbers (`+91 ...`) only when you control every value in it.
+
+### `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.
+
+The editing area is a `role="textbox"` that Jodit leaves nameless. `Editor` names it from `label` when
+there is one, else from `labels.editor` (default `Rich text editor`), and sets `aria-readonly` while
+`config.readonly` is on. Two unlabelled editors on one page announce identically unless each gets its own
+`labels.editor`.
+
+Jodit also ships the editing area at `tabindex="-1"`, so no keyboard could reach the text and a scrollable
+read-only editor could not be scrolled. `Editor` sets `tabIndex: 0` (a `config.tabIndex` you pass wins) and
+lights the Jodit frame while focus is inside it. Tab then walks toolbar, editing area, Jodit's status-bar
+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.
+
+### `SearchSelect` and `SelectSearch` search `option.label` only (so does `Select` unless you widen it)
+
+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:** 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
+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
+
+Typing a partial query and pressing Enter without arrowing down first does not pick the
+visually-highlighted top option — it only fires if the typed text exactly equals an option's full
+label. `SelectV2`/`SearchSelect` both correctly select the highlighted option on Enter; `SelectSearch`
+doesn't. Two more props (`isSearchEnabled`, `BottomIconStyle`) are typed but never read, and
+`initialSelectedOption` only seeds selection at mount with no resync if the real value arrives later.
+
+**Apply:** tell users to arrow down before Enter with this component specifically. Don't pass
+`initialSelectedOption` before the real value is known (or key the component to force a remount).
+
+### `FieldSelectModal`'s "Select all" ignores the active search filter, and resets on any parent re-render
+
+The header checkbox (and its indeterminate state) always operates on the complete `fields` list, not
+the search-filtered subset — clicking it while filtered silently selects/clears fields the user can't
+see. Separately, an effect re-seeds selection whenever `fields`/`defaultSelected` changes
+**reference**, so an inline array literal for either prop silently wipes in-progress picks on the
+next parent re-render.
+
+**Apply:** clear the search before using "Select all." Memoize `fields`/`defaultSelected` in the
+parent before passing them down.
+
+### `Dropdown`'s `ButtonText`/`text` are mutually exclusive per `dropdownType`, silently
+
+The `"button"` trigger renders `ButtonText` only; the `"text"` trigger renders `text` only — pairing
+the wrong prop with the active `dropdownType` renders an icon-only or bare-chevron trigger with no
+visible label, and the `aria-label` fallback then substitutes "Open menu" as the accessible name too.
+Separately, `buttonProps.sx` fully replaces the built-in trigger style rather than merging, silently
+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`.
+
+### Every `Search` grabs a page-wide Ctrl+K by default
+
+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.
+
+The same applies to a launcher: `NavLauncher` and `LauncherTrigger` bind no chord to *open* (once open,
+the launcher uses Cmd/Ctrl+K and `/` only to refocus its own field), and the library
+reserves `mod+k` for the app's own palette. The app must pass `shortcut={false}` on every page
+`Search`, or claim the chord in capture phase (`keydown` on `window` with `capture: true`) before
+the `Search` listeners see it — otherwise the first mounted `Search` takes Ctrl+K.
+
+### `NavLauncher` — the app owns routing, registry, query and chord
+
+- **`linkAs` must forward `className`, `ref`, `onClick`, `href`, `target`, `rel`, `tabIndex` and
+  `aria-hidden`** to its anchor. Dropping `className` loses all row styling; dropping `onClick` means
+  a click never closes the launcher.
+- **`onNavigate` fires for keyboard opens only** (Enter, mod+Enter). Pointer clicks follow the
+  rendered links, so a router `linkAs` must do the navigation.
+- **Controlled `query`:** the launcher still calls `onQueryChange("")` when it closes; the app must
+  apply it or the stale query reopens.
+- **Search rows are not nested links.** The visible label is a text-only `role="option"`; the real
+  anchor is an `aria-hidden`, `tabIndex={-1}` overlay (so copy-link and mod-click work) and pin / ↗
+  are `aria-hidden` siblings. Screen readers use Enter / mod+Enter. Do not nest links inside the
+  option — axe `nested-interactive` fails.
+- **The apps section decides "compact" with `matchMedia("(min-width: 48em)")`, the layout with
+  `(min-width: 62em)`** (`lg`). Both fall back to desktop (apps hidden, two panes) where `matchMedia`
+  is missing (SSR, jsdom), so tests must stub both to see the apps section or the tab bar.
+- **Below `lg` only the selected tab's panel is mounted.** Pinned / Frequently visited / Recent
+  (Quick access tab) and the apps list (Apps tab) are not in the DOM until their tab is clicked; the
+  Quick access tab is omitted when it would be empty, and a single remaining tab hides the bar. The
+  search view is different: no tab bar, stacked results plus the Quick access rail. A phone or tablet
+  consumer test that looks for an app or a pin must click the tab first.
+- **`P` on a focused NavLauncher row pins it.** Any other printable key pressed on a row, tab or
+  button (not Space, no modifier) is appended to the query and focuses the field; in the field `P`
+  types the letter.
+- **Esc is handled by the launcher, not the Drawer** (`closeOnEsc` is off): it clears a non-empty
+  query and keeps focus in the field, and closes only when the query is empty. The keydown is stopped inside
+  the launcher, so a consumer `Escape` listener on `document` never sees it.
+- **The dialog's accessible name is always `labels.title`** (a hidden heading, through `Drawer`'s
+  `aria-labelledby`); the search value, scope chips and `headerActions` no longer join it. A consumer
+  test asserting the old "Menu leave" style name must assert `labels.title` instead.
+- **The result count is `aria-hidden`; the announcement is a separate visually hidden `aria-live="polite"`
+  node, deliberately not `role="status"`**, so `getByRole("status")` still matches only the no-results
+  message and the loading skeleton.
+- **Left/Right/Home/End in the search field edit the caret** until a result has been navigated by
+  arrow/Page keys (→ at the end of the text enters the grid); any change to the query hands them back
+  to the caret. Do not "fix" this by binding them to results.
+- **`NavLauncher` `suggestions` empty falls back to `noResultsHint`** instead of showing chips.
+- **`PinToggle` / `NewTabLink` are opacity 0 until row hover or focus-within**, so a consumer's own row must carry `data-group` (or `role="group"`) to reveal them.
+- **`LauncherLabels.screensGroup` is unused** by search now (sections replaced the flat group); kept so label objects still type-check.
+- **`LauncherLabels` gained required keys** (`hintClickNewTab`, `newTabTip`, `resultsCount`, `tabsLabel`,
+  `tabMenu`, `tabQuickAccess`, `tabApps`). The `labels` prop is `Partial<LauncherLabels>` and is fine;
+  a consumer that annotates a *full* `LauncherLabels` object fails to compile.
+- **`openShortcutHint` and `labels.hintOpenMenu` are deprecated no-ops:** the open chord is no longer
+  shown in the footer. Drop them; the footer's hints are arrows, ENTER, ⌘ ENTER, ⌘ + click, P, ESC.
+  Both are optional, so a full `LauncherLabels` object needs no `Omit<LauncherLabels, "hintOpenMenu">`.
+- **`apps` is data-driven.** Gate by plan by changing the array or setting `locked` / `lockedReason`;
+  keep `id`s stable (hues and `key` derive from them), and pass `color` on an app whose mark must not
+  shift when siblings are added or removed. Locked rows are not links, not focusable, `aria-disabled`,
+  tooltip = `lockedReason`. Pass `appsVisibility="always"` to show them above `md`.
+- **Never use `:has()` in an emotion style.** jsdom's (nwsapi) `getComputedStyle` can throw ("not a valid selector") and takes every consumer test that opens a
+  Drawer down with it. The launcher marks row focus with a `data-row-focus` attribute instead. If you
+  hit that error in your own tests on a newer jsdom, report it with the selector.
+- **Launcher rows are CSS containers** (`container-type: inline-size`, name `launcher-row`); jsdom
+  drops `@container` rules, so tests assert the style objects (`titleInset`, `WIDE_ROW`), not the
+  stylesheet.
+- **A search row without `href` (an action with `run`) cannot open in a new tab:** any click, with or
+  without Cmd/Ctrl, runs it and closes the launcher, same as Enter.
+- **Spotlight search is opt-in (`searchMode="spotlight"`).** Without it matching, ranking and row
+  order are exactly as before; `scopes`, `quickActions`, `answers`, `facts` and `groupLimit` work in
+  both modes. Facts are searchable in spotlight only.
+- **Two search models, and classic never matches a screen on its module.** Classic (the default) runs
+  `searchLauncherSections`: registry order, no ranking, and every query word must appear in one row's
+  own label or keywords. "leave balance" therefore finds nothing unless one screen's keywords carry
+  both words. Spotlight ranks and also matches a screen on its module and section labels, so the same
+  query finds Leave › Balances. The exported `searchLauncher` (one flat Screens group) is legacy and
+  `@deprecated`; the component never calls it.
+- **Scope chips live in the header row and are always shown** (their own header row below `md`);
+  while a query is active each chip's name carries its count ("People, 3 results"), so a test that
+  types first must match `getByRole("radio", { name: /^People/ })`, not the bare label.
+- **Picking a chip other than All or Screens with an empty field lists that scope** exactly as
+  passed: its `actions` or `extraResults` groups, so a remote group with nothing loaded yet shows
+  `labels.scopeEmpty`. Load the scope's items when `onScopeChange` fires if it should list them.
+- **Quick actions show only under All with an empty query, as the first block of the menu** (not
+  while `isLoading`); only the first 5 render.
+- **Closing resets the scope to "all"** and calls `onScopeChange("all")`; a controlled `activeScope`
+  must apply it, like `onQueryChange("")`.
+- **`facts` swap the Quick access rail for a Preview pane at `lg`** whenever any visible result has
+  facts; below `lg` the active result's facts dock under the list. Copy buttons are never inside an
+  `option` or the listbox (axe `nested-interactive`, `aria-required-children`).
+- **An answer without `run` or `href` copies `answer.value` on Enter/click**; answers show in the
+  All scope only.
+- **`extraResults` groups are not filtered** unless `matchLocally: true`; remote rows the query does not
+  match stay listed (score 0) and can never be the Top hit.
+- **`LauncherSearchEngine` searches what it is given.** It has no React, DOM or network; build the
+  index with `createIndex` once per data change, not per keystroke.
+- **`LauncherTrigger` does not bind its shortcut**; `shortcut={null}` removes the hint and
+  `aria-keyshortcuts`. An explicit `aria-label` hides the visible label from assistive tech, so keep
+  the visible text inside the label (WCAG 2.5.3). `display="icon"` has no visible text: the label is
+  its accessible name and tooltip.
+
+### `Header`'s desktop submenus open on hover only — no keyboard or click trigger
+
+Dropdown children are gated on local hover state (`onMouseEnter`/`onMouseLeave`), with no `onFocus`.
+A keyboard user tabbing to a parent item can never open its children on the desktop layout — the
+identical data renders as a click-toggled accordion on mobile.
+
+**Apply:** don't put anything a keyboard user must reach behind `children` on desktop; use `rightSlot`
+(real focusable buttons) for critical actions until this gets a keyboard path.
+
+### `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 `@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.
+
+### `FilterSidebar`'s `selected` without `onChange` makes every filter silently inert
+
+Passing `selected` alone (uncontrolled companion `onChange` omitted) computes the next filter state
+on every click and discards it — checkboxes visibly never check, forever, with no error. Separately,
+`onApply`, `headerPadding`, and `sliderMode` are all typed and accepted but have zero effect, as is
+`FilterSection.checkboxes` (all four are `@deprecated`); radio-vs-checkbox mode is actually decided by
+`type === "radio" || section.radio`.
+
+**Apply:** always pass `selected` and `onChange` together, or omit `selected` and let `FilterSidebar`
+own its state.
+
+Separately, `FilterSidebar` skips re-rendering sections whose `section` object is unchanged, so build `sidebarOptions`
+once (module constant or `useMemo`); fresh section objects every render re-render every section on each range drag. Don't reach for `onApply`/`headerPadding`/`sliderMode`/`FilterSection.checkboxes` —
+none of them do anything.
+
+### `Breadcrumbs`' `isLastChild` prop is accepted but never read
+
+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.
+
+With `overflow="wrap" | "truncate"` each crumb is `noOfLines={1}` with a `title`, so one very long
+label ellipsizes; the default `"nowrap"` is unchanged.
+
+### `Accordion`'s `items[].buttonProps` replaces, not merges, the expanded/hover highlight
+
+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`) when the highlight
+must survive.
+
+### `Table`: memoise `columns` if users can hide or reorder columns without `savePreferences`
+
+A new `columns` identity re-applies the column defaults and discards those local changes. Passing an
+equal array again no longer costs a re-render, but the reset still happens.
+
+**Apply:** define `columns` at module level or in `useMemo`.
+
+### `Table`'s `LeftFilterPane` Clear All only re-applies filters in `"sidebar"` mode
+
+`handleClear` calls `onClear` unconditionally, but only calls `onApply(cleared)` when
+`filterMode === "sidebar"` — in `"modal"` mode, Clear All visually unchecks every filter but never
+tells the parent the selection changed, so a consumer whose `onClear` doesn't itself reset
+applied/query state keeps serving pre-clear filtered data.
+
+**Apply:** when using `filterMode="modal"`, drive your data refetch from `onClear`, not `onApply` —
+don't assume `onApply` fires on every Clear All.
+
+### `ScrollToTop` watches one `parentElement` hop, not "the nearest scrollable ancestor"
+
+It reads `scrollTop` off its immediate DOM parent only, with no upward search for an `overflow:
+auto/scroll` element. Wrap it in one extra layout `<div>` and the button silently never appears — no
+error, no warning, `scrollTop` on a non-scrolling parent just stays `0` forever.
+
+**Apply:** `ScrollToTop`'s JSX parent must be the actual scroll container, or pass `useWindow` when
+the page itself scrolls.
+
+### `ProfilePhotoViewer`'s PDF detection breaks the moment a file is picked, and a new `photoUrl` discards the preview
+
+PDF detection is a literal `.endsWith(".pdf")` check — picking a file through the built-in editor
+replaces the value with a base64 data URI that never ends in `.pdf`, so a freshly-picked PDF renders
+as a broken image instead of the intended file badge (only the original URL prop is detected
+correctly). Separately, a changed `photoUrl` re-syncs the component and replaces any locally picked
+preview (a same-URL re-render keeps it), so a parent that updates `photoUrl` before the upload has
+finished makes the preview vanish mid-upload.
+
+**Apply:** don't use the built-in edit flow for PDF documents; detect kind from `File.type` in your
+own handler instead. Update `photoUrl` only once the upload has finished. `key={photoUrl}` is no
+longer needed.
+
+### `Tabs` link mode needs `href` on every item, and has no default current item
+
+One item without `href` makes the whole thing a normal tablist and `href` is ignored everywhere (a
+dev-only `console.warn` is the only signal). Button tabs select the first enabled item when `value`
+is missing; link tabs mark nothing `aria-current` until you pass `value`. A plain left-click calls
+`onChange` but never `preventDefault`s; modifier and middle clicks only open the link. `isDisabled`
+link items render as a non-link `span`.
+
+**Apply:** `Tabs items=[{ id, label, href }] linkAs={RouterLink} value={currentId}` with `value`
+derived from the route, and never hand-build `Box as={Link}` tabs.
+
+### `BulkSelectionBar` renders nothing at `selectedCount` 0, and `sticky` needs a scroll ancestor
+
+With no persistent live region it announces count changes itself (the node mounts empty and fills in
+an effect), so don't also announce from your own region. `placement="sticky"` pins only inside an
+ancestor scroll container — an ancestor with `overflow: hidden` silently disables it. Combining it
+with `Table`'s `headerActions` gives two action sets for one selection.
+
+### `SectionRail` chooses rail vs `Select` with `matchMedia` at render time
+
+It renders the rail when `matchMedia` is missing (SSR). In the `Select` branch a dirty section's
+option reads `"Label (dirtyHint)"` — a native `<option>` cannot hold a dot.
+
+### `CalendarGrid` is fully controlled, ignores time of day, and `renderDayCell` turns multi-day bars off
+
+Without `onDateChange` / `onViewChange` the toolbar's Today/Prev/Next and the view switcher are
+hidden and arrow keys stop at the edge of the visible range, so the grid looks static — wire both.
+`start` / `end` are read as local calendar dates (`end` inclusive): a UTC-midnight `Date` shows the
+previous day in a negative-offset zone, so build date-only values with `new Date(y, m, d)`.
+`renderDayCell` replaces each cell's chips wholesale: a 3-day event is passed to it for all 3 days
+but is no longer drawn as one bar, and `onEventClick` never fires from your own content. A cell is named by
+its date and count followed by everything inside it, your content included, so keep that content short.
+
+### `AudioRecorder` needs a secure context, and `onRecorded` is not called after unmount
+
+`getUserMedia` is undefined on plain http (except localhost), so the component shows its
+"unsupported" state there, not "permission denied". A parent that navigates away mid-recording gets
+no `onRecorded` call (the mic is released instead), and an empty recording never calls it either.
+
+### `FilePreview` infers file kind from `fileName`, not `fileUrl`, and never resets zoom/rotation on its own
+
+Once `fileName` is set, `fileUrl`'s own extension is never consulted — a friendly display name with
+no extension forces the "preview unavailable" fallback even when `fileUrl` points at a perfectly
+renderable file. Separately, cycling `fileUrl` while the modal stays open (a gallery next/prev)
+carries the previous image's zoom/rotation into the new one.
+
+**Apply:** keep the real extension on `fileName`, or pass `fileType` explicitly to skip inference.
+Remount via `key={fileUrl}` when swapping the file in place instead of just changing the prop.
+
+### An overflowing `ScrollbarBox` is a tab stop — give it an `aria-label`
+
+While its content overflows a scrollable axis (more than 1px) and holds no button, link or field, the
+box takes `tabIndex={0}` so a keyboard user can scroll it, and rings on `:focus-visible` only. A box that
+fits, scrolls `hidden`, or already holds something focusable gets no stop, and a mouse click shows no ring.
+Without `aria-label` the stop is unnamed (no `role="region"` either), so a screen reader announces nothing
+useful at it.
+
+**Apply:** pass `aria-label` ("Recent deals") on every `ScrollbarBox` that can overflow, and don't wrap one
+around a list of controls just to get a stop.
+
+### `StageProgress`'s `tooltipThreshold`/`minStageWidth` no-op under `variant="stepper"`, and a stale `value` blanks the tracker
+
+Both props stop having any effect the moment a tracker switches to the stepper variant. Separately,
+if `value` matches no `stage.id` (e.g. `stages` was filtered/re-derived and went stale), every stage
+silently renders as `"upcoming"` — no stage is ever active or completed, with no error. The match is
+also a strict `===`: a numeric `stage.id` compared against a string `value` (or vice versa) never
+matches either, even when the "same" stage is clearly intended.
+
+**Apply:** don't rely on either prop once on the stepper variant. Re-validate `value` against the
+current `stages` list whenever it's filtered, and keep `id`/`value` the same primitive type at every
+call site.
+
+### A `StageProgress` strip is a tab stop only when no stage is a button — name it with `aria-label`
+
+At a narrow width the strip scrolls sideways. Stage buttons already let a keyboard user reach every stage,
+so an interactive strip gets no extra stop. A strip with nothing focusable (`isReadOnly`, or every stage
+disabled) takes `tabIndex={0}` while it overflows and rings on `:focus-visible` only; nothing changes at
+rest, on a mouse click, or while the stages fit. Without `aria-label` the stop is unnamed. A `stepper`
+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`, `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
+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
+  either. It is a misspelling of `isVisibility`, but do not rename it (breaking change) — and do not
+  expect it to do anything if you do.
+- `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.
+- `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
+Columns tab — not by `isVisiblity`/`tableSettings`.
+
+### `Table`'s `preferences` prop is silent-by-default, not required
+
+Omitting `preferences` (or leaving `preferences.url` empty, the default) does not throw or disable
+the table — the persistence hooks both early-return when the base URL is falsy. The table works
+fully in memory; it just never persists column order/visibility, density, or grouping across
+reloads. When you do wire a `url`, `token` is sent as a **raw** `Authorization` header value — do
+not prefix it with `"Bearer "` yourself expecting the hook to strip it.
+
+**Apply:** treat `preferences` as opt-in persistence, not a required config block. If settings
+aren't surviving a refresh, check `preferences.url` is actually set before assuming a bug.
+
+### `SearchSelect`'s `height` prop only resizes the `insideSelect` segment, not the field
+
+Despite the name, `height` is read only to size the nested `insideSelect` trigger. The main
+control's height always comes from `size`'s token set — passing `height` with no `insideSelect`
+configured has no visible effect at all.
+
+**Apply:** to change the main field's height, change `size`; `height` only matters when
+`insideSelect` is also passed.
+
+### `SearchSelect`'s `pagination` now takes an explicit "has more" signal — prefer it at an exact-multiple total
+
+Without `pagination.hasMore`/`pagination.totalRecords`, `hasMore` still falls back to guessing from
+`options.length % (pagination.limit ?? 10) === 0`. A total that's an exact multiple of `limit`
+(30 items, limit 10) still looks like "more pages exist" for the *first* extra scroll, firing one
+empty `onScroll` call — after that empty response, `SearchSelect` stops asking (it no longer loops
+forever the way earlier versions did).
+
+**Apply:** pass `pagination.hasMore` (a boolean) or `pagination.totalRecords` (a count) so the field
+never fires that one avoidable empty request; both take precedence over the `limit` guess.
+
+### `RolesPermission`'s `RoleData.permission`/`designation`/`makeSuperAdmin`/`automation`/`trackLocation`/`show_records` are dead weight in this component
+
+None of these fields are read by `RolesPermission` — the roles list only renders
+`roleName`/`createdBy`/`created_at`/`roles_id`. They exist solely to be round-tripped unchanged
+through `onViewRole`/`onEditRole` so the consumer can prefill its own edit form. Setting them has no
+visible effect inside this component.
+
+**Apply:** treat these fields as pass-through-only storage — populate them for your own edit form,
+not to change anything `RolesPermission` itself renders.
+
+### `OrganizationDetails`' `OrganizationItem.uiInvite` is never read
+
+Active vs. invited organizations are decided purely by which array (`activeOrganizations` vs
+`invitedOrganizations`) an item is placed in — `uiInvite` is carried on the type but
+`OrganizationDetails` never inspects it.
+
+**Apply:** don't rely on `uiInvite` to control which section an item renders in — move the item
+between the two arrays instead.
+
+### `OrganizationDetails`' `onSetDefault`/`onAcceptInvite`/`onDeclineInvite` are fire-and-forget despite their `Promise<void>` signature
+
+Unlike `onCreateOrganization`/`onEditOrganization`/`onDeleteOrganization` (all awaited), these three
+are called without `await` — the `switchingOrgIds`/`respondingOrgIds` spinner arrays are entirely
+consumer-managed state, not driven by this component resolving the promise.
+
+**Apply:** don't assume symmetry with the awaited callbacks in the same props interface; manage your
+own loading state for these three around the promise you return.
+
+### `OrganizationDetails`' `CreateOrgFormValues.default`/`defaultOrg` are dead fields — now `@deprecated`
+
+The built-in `CreateOrgModal`'s internal state and submit handler never set or forward them, and the
+public `onCreateOrganization` callback's parameter type doesn't declare them at all — populating
+them in a custom create form has no effect on the built-in flow. account-frontend, the only real
+consumer of `OrganizationDetails`, never reads either field. Both are now `@deprecated` in
+`OrganizationDetailsProps.tsx`.
+
+**Apply:** don't rely on these two fields to pre-mark a newly created org as default.
+
+### `SideBar`'s `selectedSubMenu` prop is accepted but never read — now `@deprecated`
+
+`SidebarProps.selectedSubMenu` is threaded through `SideBar` → `MenuItems` → `MenuItemBox`, but the
+component's destructure never includes it — passing it has no effect of any kind. Zero consumers set
+it; now `@deprecated` in `SideBarProps.tsx`.
+
+**Apply:** don't pass `selectedSubMenu` expecting it to highlight a submenu row.
+
+### `SideBar` pinned rows, `autoCollapse` and `collapseTransition`
+
+- **`autoCollapse={false}` also silences the `open` prop** (`open` works by calling `changeToggle`).
+  Drive collapse with `toggle` only.
+- **A pinned id highlights only in the pinned block** while `activePinnedId` matches, and the parent
+  submenu of a pinned child does not auto-open. An `activePinnedId` past `pinnedLimit` expands the
+  list so the active state never disappears.
+- **Pinned rows are anchors with `href={url}`**: a plain click calls `handleMenuClick` (and closes the
+  overlay), modified clicks fall through to the browser. Unpin is a sibling button, never nested.
+- **`collapseTransition` affects the `lg`+ inline rail only** — overlay slide, drag and `mobileNav`
+  are untouched.
+- **The rail focus ring is lifted per surface** (`sidebarFocus.ts`) because `colors.focusRing.ring` is
+  derived for the page canvas and fails 3:1 on the rail for five light brands. The lasting fix is a
+  `sidebar.focusRing` theme token.
+
+### `KanbanBoard`'s `kanbanSelect`/`onOpen` don't check `permissions` — decision: accepted as-is
+
+Looked like an asymmetry with the gated `kanbanEdit`/`kanbanCreate`/`onDelete`, but on inspection
+`kanbanSelect` is a header filter dropdown (`options`/`onSelectChange`/`value`) — a view-level
+affordance, not a mutation trigger — and `onOpen` (opening a card) is a view action too. Both are
+already covered by the existing `permissions.isViewable` gate: the whole board (including the
+header) returns `null` before rendering when `isViewable` is `false`, so a viewer who can't see the
+board can't reach either. Gating them a second time against `isEditable`/`isCreatable`/`isDeletable`
+would be wrong — filtering/opening isn't an edit, create, or delete. No code change made.
+
+**Apply:** if you need `kanbanSelect` or `onOpen` gated on something narrower than view access, gate
+it yourself (e.g. `isSelect: canEdit`); the component won't do it for you.
+
+### `SideBar`'s `locked` menu-item flag — decision: fixed to actually block interaction
+
+Previously `locked` only swapped in a padlock icon; the click handler checked `disabled`, not
+`locked`, so a `locked: true` item still fully navigated. Zero consumers set `locked: true` in
+account-frontend, tickets, crm-frontend, hrms, social-frontend or crm-mobile, so there was no
+working behavior to preserve — the misleading name was a trap waiting for the first adopter. As of
+this release, `locked` blocks clicks/expansion the same way `disabled` does, in both the expanded
+sidebar (`MenuItemBox`) and the collapsed-sidebar flyout (`MenuPopoverContent`), for both top-level
+and submenu items. `disabled` is unchanged and still works independently.
+
+**Apply:** `locked: true` alone now prevents interaction; you no longer need to also set
+`disabled: true`.
+
+**Follow-up (same trap, missed spot): `SecondaryBar` still ignored `locked`.** `SecondaryBar.tsx`'s
+`CollapsedItem`/`ExpandedItem` render the same `MenuProps` shape via a top-level item's
+`secondaryItems`, but their click guards checked only `menuDisabled(item)` — never `item.locked` —
+and neither rendered the lock icon, so a locked secondary item stayed fully clickable and looked
+identical to an unlocked one. Fixed the same way as `MenuItemBox`/`MenuPopoverContent`. Also added
+`lockedReason?: string` (`MenuProps`) — an optional per-item tooltip, shown on hover/focus of a
+locked row anywhere in `SideBar` (rail row, submenu row, both collapsed-rail flyouts, and
+`SecondaryBar`), via the library's own `ToolTip`.
+
+### `SideBar` menu-item labels clipped the bottom of descenders (g/y/p/q/j) — fixed
+
+`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").
+
+**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
+
+`SideBar.tsx`'s `#sidebar-scroll-container` used `Constants/Sidebar.ts`'s `FlexCss`, which only set
+the `::-webkit-scrollbar-*` pseudo-elements — never the standard `scrollbar-width`/`scrollbar-color`
+properties. Chromium honors the webkit pseudo-elements, but any engine that reads the standard
+properties first, or doesn't support the pseudo-elements at all, fell back to the browser's default
+scrollbar: a plain bar with no relation to the dark sidebar theme, showing up the moment a nav list
+(enough sections/items) overflowed the viewport. Fixed by switching to the already-written
+`cssForScrollBar(theme)` (same file), which sets `scrollbarWidth`/`scrollbarColor` **and** the
+webkit pseudo-elements, themed to `sidebar.background[500]` / `sidebar.mutedIcon`/`mutedLabel`,
+hidden until hover. `FlexCss` is removed — `cssForScrollBar` is now the only scrollbar treatment
+the SideBar uses. (2026-09-29: the thumb was briefly brand `primary[500]`/`[700]` — since fixed to
+the neutral tokens shown above; `SecondaryBar`'s own scroll panel got the same styling and a
+duplicate-id fix in the same pass.)
+
+**Apply:** nothing to do. If a nav list is long enough to scroll, the bar now stays invisible until
+hovered, in the sidebar's own colors, on every engine — not just Chromium.
+
+### `SideBar` contrast pass — badge dot, hover fills, missing-icon fallback, default avatar/logo (2026-09-29) — fixed
+
+A themed-UI audit found six real defects, none of them behavior changes: the collapsed-rail
+notification dot (`red[400]`) is now `sidebar.semanticText.error`, which stays legible against the
+rail in both modes instead of drifting; six `whiteAlpha.100` hover/rest fills that sat below the
+sidebar's own perceptible-step floor are now `whiteAlpha.200`, matching every other row's hover;
+the collapsed-flyout submenu (`MenuPopoverContent`) no longer shows Chakra's built-in "?" glyph for
+a sub-item with no `icon` — it draws the same small dot the always-visible inline submenu already
+used; hovering an *active* flyout row no longer gets visibly lighter-then-darker (it now steps
+`.300` -> `.400`, like every other active row); and the default (no `logo`/`avatarUrl`) header logo
+tile and footer avatar initials no longer paint a raw `primary` fill, which was within ~1:1 of the
+rail — invisible — on zinc, skyline and storefront.
+
+**Apply:** nothing to do — same props, same markup, visuals only. If you rendered a `SideBar` or
+`SecondaryBar` with a screenshot baseline captured before 2026-09-29, expect the badge dot color,
+some hover states, and the default logo/avatar tile to look different.
+
+### `SideBar` contrast pass round 2 — muted icon/label under a hover fill, inline-submenu state (2026-09-29) — fixed
+
+A follow-up audit found `sidebar.mutedIcon`/`mutedLabel` could dip under WCAG AA when sitting on
+top of an active or hovered row (the whiteAlpha overlay steps), even though the same token cleared
+AA against the bare rail — the token was never resolved against that combined surface. Also, the
+expanded rail's always-visible inline submenu only swapped an active row's label to white with no
+fill or accent bar, unlike every other active row in the family (top-level rows, the
+collapsed-flyout submenu). Both fixed with no prop or markup changes.
+
+**Apply:** nothing to do — same props, visuals only. Expect a muted icon/label under a hover/active
+row to read slightly lighter than before on some brands, and an active inline-submenu item to now
+show a fill and left accent bar matching the rest of the sidebar's active-row styling.
+
+### `KanbanBoard`'s `permissions.isViewable: false` hides everything, including header actions
+
+Not just the columns — the select/edit/create header bar disappears too, since the whole component
+returns `null` before rendering anything.
+
+**Apply:** there's no prop for hiding only the board body while keeping header actions visible.
+
+### `Switch` was forced to 200px even with no labels — it overflowed a narrow cell
+
+`Switch` (`leftText`/`rightText`) kept a 12.5rem minimum width regardless of whether any label was
+set. Used as a boolean toggle — the wrong component for that, but the mistake shipped live in
+tickets' project custom-fields page — an unlabelled instance rendered as two unlabelled brand-filled
+pills at 200px inside a 120px table cell, overflowing by 80px. The width floor now only applies once
+`leftText`/`rightText` is actually set; an unlabelled instance shrinks to fit (~58px measured).
+
+**Apply:** for a single on/off field use `ToggleSwitch`, not `Switch`, even now that it no longer
+overflows — a two-option segmented control still announces as `role="radiogroup"`, not
+`role="switch"`. Swapping `Switch` for `ToggleSwitch` changes `getByRole("radio", …)` queries to
+`getByRole("switch", …)` — the same test break the `InputSwitch` → `ToggleSwitch` migration caused.
+
+### A `SearchSelect`/`Select` custom row node inherits the row's font size and padding — don't restate them
+
+`SearchSelect`'s `option.view` and `Select`'s `renderOption` render straight inside the option row,
+which now carries its own `fontSize`/`px`/`py` so a plain-text row is legible with no extra markup.
+A custom node that also sets its own `px`/`py`/`fontSize` stacks on top of the row's rather than
+replacing it — this is what made rows in crm-frontend render 57–75px tall instead of the ~30px every
+other row uses.
+
+**Apply:** size a custom `option.view`/`renderOption` node yourself only when it needs something
+*different* from the row default — inherit by default, don't restate it.
+
+### A custom option row's sub-line must not use `colors.textMuted` directly
+
+A selected row sits on a tinted fill, and the hovered-selected rung is the busiest one in the
+ladder. In dark mode `surfaceRaised` carries only ~0.86 of contrast headroom above AA, so raw
+`textMuted` on that rung measures **4.00–4.22:1** in 6 of 9 brands — under the 4.5:1 a 12px
+sub-line needs. The library's own rows no longer use it.
+
+**Apply:** in a `SearchSelect` `option.view` or `Select` `renderOption` node, read the sub-line ink
+from `optionRowDescriptionInk(theme.colors)` (exported from the package root) rather than
+`theme.colors.textMuted`. It is a no-op in light mode. The row's main label is
+`optionRowInk(theme.colors, isSelected)` with `optionRowWeight(isSelected)` — never brand ink.
+
+### A custom option list must not fill the selected row
+
+`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`. (`Select`'s own popup
+additionally fills the selected row (neutral grey rungs in both modes, identical on every brand; 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
+from the package root. Text is `optionRowInk(colors, isSelected)`, unchanged on hover.
+
+### `Table`'s node column `label` needs `labelText` unless its text is plain children
+
+`columns[].label` accepts a node (an icon, a tooltip trigger) as well as a string or number. Every
+place that cannot render a node — the sort and filter button names, Manage Columns, the Group
+picker, filter chips, saved preferences and `onRowClick`'s `header.label` — uses a plain-text name
+instead: `labelText` if set, else the node's literal text children, else the column `id`. A node
+whose text comes from inside a component (`<MyHeader title="Revenue" />`, a `t()` call inside a
+child) has no literal children, so those places silently read the raw `id`.
+
+A wide node header is also **clipped, not ellipsized** — the header's ellipsis only works on bare
+text. Column widths come from the rendered DOM, never from label length, so sizing is unaffected.
+
+**Apply:** set `labelText` on every node label; put an `isTruncated` `Text` inside the node if it
+can outgrow the column. An icon-only tooltip trigger inside the node is a native `button`, not a `span`
+with `aria-label` (see the `ToolTip` gotcha above).
+
+### `FormField`, `IconButton`, `SkipLink`: what their props do not hint at
+
+- **`FormField` + library fields:** `TextInput` inherits FormField's `error` and `isRequired` because it checks
+  for a parent `FormControl`. `InputTextArea`, `NumberInput`, `Select`, the date pickers and `PhoneNumberInput`
+  wrap themselves in their own and do **not**: pass `error`/`isRequired` to those directly, and never give a
+  wrapped field its own `label` as well, or it renders two.
+- **`FormField isRequired` sets native `required` on Chakra-based controls** (as Chakra's `FormControl` does), so
+  the browser blocks an empty submit. Add `noValidate` to the `<form>` if you validate yourself. Native children
+  get `aria-required` only.
+- **`FormField` children:** pass one element or a function. A Fragment is rendered untouched and gets no wiring.
+  `id` is the control's id (the root takes none); a child's own `id` is adopted when FormField has none.
+- **`IconButton` warns once per mount in development without `aria-label`/`aria-labelledby`.** `title` does not
+  count. Size the icon yourself (xs 12 · sm 14 · md 16 · lg 18): the button does not resize it.
+- **`SkipLink`** must be the first focusable element on the page. Its target gains `tabindex="-1"` if it is not
+  focusable, and keeps it. A missing target falls back to the browser's hash jump (and warns in development).
+
+### `formatDate`, `TimePicker`, `TagInput`: what their props do not hint at
+
+- `formatDate` reads a bare `YYYY-MM-DD` as that calendar day, not UTC midnight. Pass a `Date` only when you mean
+  an instant. Epoch *seconds* are not detected: multiply by 1000 first.
+- `TimePicker` fires `onChange` with a `Date` on the day of `value` (else `baseDate`, else today). It never clears
+  to `null` on its own: pass `onClear` to make "--" pickable once a time is set (it then fires instead of `onChange`).
+- For free-text chips that are not email addresses use `TagInput`: same look as `MultiSelect`, any text, with
+  your own `validate`. Its rejection messages and add/remove announcements are English by default; translate them
+  with `labels` (functions, e.g. `duplicate: (entry) => ...`), including `labels.remove` for each chip's remove button
+  (default `Remove <tag>`).
+- **Button press scale matches a real `:active` only.** A `MenuButton as={Button}` held open by Chakra's
+  `data-active` keeps the darker pressed fill but does not stay at 0.98. A consumer `_active={{ transform }}`
+  loses to the press rule while the pointer is down; use `variant="unstyled"` or an `sx` `&:active` with
+  `!important`.
+
+### `Card` is borderless by default (`elevated`)
+
+A Card that frames a table or a list of rows needs `variant="outline"`. `borderColor` alone shows nothing, because
+the default border width is 0, and the outline rule is Chakra `gray[200]`, not `boxborder[200]`. Paint the page with
+`backgroundColor.base`: on `backgroundColor.main` a borderless card can be white on white.
+
+### `Select` / `SearchSelect` multi rows have no checkbox role
+
+Query rows with `getAllByRole("option")` and check `aria-selected`. The row's checkbox is decorative and no longer
+exposes `role="checkbox"`, so `getByRole("checkbox")` finds nothing inside the popup.
+
+### Page behind an open `WorkspaceWindow` is `aria-hidden`
+
+While a window is open (not minimized) role queries for background elements need `{ hidden: true }` or a test id.