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

package/COMPONENT-GOTCHAS.md

@@ -127,7 +127,7 @@ also passed `native`.
 | 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`, `isSelectAll`, `rightIcon`, a field-level loading slot and the paginated `pagination.onScroll` shape (1-based `startIndex`/`limit`/`query`) have **no** equivalent in `Select` today. Keep using it until they do |
+| `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 |
 
@@ -158,7 +158,7 @@ visible at the call site, or declare the handler with both parameters. Grep for
 ### `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) — no numeric value, min/max, or step. The
+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.
@@ -203,13 +203,18 @@ and wires `aria-controls` to them. Pick by that, never by the picture. A screen
 | 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` / `Buttons`
+### Which "button" — `Button` / `ButtonGroupIcon`
 
-| Need | Component | Why not the others |
+| Need | Component | Why not the other |
 | --- | --- | --- |
-| A single themed, interactive button — any variant/size/colorScheme, dark-mode aware | `Button` | The only one of the three that reads design tokens at all |
-| A themed row of icon + text + icon, optionally a dropdown menu on the right | `ButtonGroupIcon` | The real "group" component despite `Buttons`' plural name suggesting otherwise |
-| *(avoid)* | `Buttons` (plural) | Legacy single-`Button` wrapper, not exported from the package root — see gotcha below |
+| 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`
 
@@ -241,11 +246,11 @@ and wires `aria-controls` to them. Pick by that, never by the picture. A screen
 | 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 |
+| 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` | Two-column popover grid of separate app origins — `SideBar`'s `otherApps` is the legacy predecessor; don't wire both into one shell |
+| 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`
@@ -255,7 +260,7 @@ and wires `aria-controls` to them. Pick by that, never by the picture. A screen
 | 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 export a type named `FileUploaderProps` — the one re-exported from the package root (`src/index.ts`) describes `FileUpload`, not `FileUploader`. Check which folder a type came from before trusting the name.
+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`
 
@@ -290,7 +295,7 @@ The value `HeaderActions` comes from `Components/Header/HeaderActions.tsx`, whic
 
 **`ConfirmDialog.onConfirm` does not close the dialog.** It fires and nothing else; you call `onClose` yourself. That is deliberate — it lets you keep the dialog open while an async delete is in flight — but a handler that only calls your delete function leaves the dialog on screen with no error.
 
-`iconBg` and `iconColor` are **required** and take raw colour strings, so the caller resolves the tone. Read them from `useCustomTheme()` — a hardcoded hex there is stuck in light mode.
+`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`
 
@@ -313,6 +318,7 @@ not enough when the overlay sits inside a transition wrapper — the wrapper kee
 | 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` |
 
@@ -328,23 +334,21 @@ Each wrapped component gets its own `ChakraProvider` (CSS reset, global styles,
 
 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, and the prop is `disabled`
+### `ChoiceCardGroup`'s children must be `ChoiceCard` elements
 
-A wrapper component hides each card's `value` and `disabled` from the roving tab stop, so with nothing
-selected the group has no Tab stop at all (same rule as `PaymentOptionGroup` / `AddressCardGroup`). The
-card's prop is `disabled`, not `isDisabled`: the shared machinery reads `disabled` off the child element.
-The group is a column only.
+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.
 
-### Four components with a behaviour their props do not hint at
+### A component with a behaviour its props do not hint at
 
-- `Notification`'s countdown is computed when its dates change and never ticks; remount or change a date to refresh it. Overdue labels read "overdue by N hours ago".
-- `NoteTextArea` checks `maxNoteWordCount` against the title only until the note is next edited, so a long title can be saved; `handleCancel` always receives `false`.
-- `VerifyEmailOtp` fields set `autocomplete="off"`, so browser or OS one-time-code autofill never offers the code.
+- `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
 
@@ -359,7 +363,7 @@ itself takes no ref); `Avatar` to the outer box; `Tag` to its root, which is a `
 `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` in its type but never
+`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
@@ -386,7 +390,7 @@ The wrapper is deliberately not a button; make the custom component a button, or
 | Chakra passthroughs | 34 barrel value exports (and 12 type exports) that duplicated an owned component were removed: `Input`, `Textarea`, `Progress`, `Radio`, `RadioGroup`, `Skeleton`, `ModalOverlay`, `ModalContent`, `ModalCloseButton`, `CardBody`, `ChakraCard`, `ChakraSelect`, `ChakraModal`(+`Body`/`Header`/`Footer`) the `Tabs`/`Accordion` families, and the Chakra slider sub-parts. `Tabs`, `Accordion` and `RangeSlider` now resolve to the library's own themed components (`RangeSlider` gained a real dual-thumb mode and a `marks` prop). Each removal is a compile error, never a silent swap | use the owned component — `TextInput`, `InputTextArea`, `ProgressBar`, `RadioButton`, `Skeletons`, `Modal`, `Card`, `Select` |
 | `Avatar` / `AvatarGroup` | Now the library's own components, not Chakra passthroughs. `AvatarProps` is a closed list (`name`, `src`, `size` `2xs`–`xl`, `status`, `ariaLabel`, `getInitials`, `data-testid`) — Chakra style props and `2xl` no longer compile, and **`name` is now required `string`**, so a `user.name?: string` call site fails. The fill is derived from `name`, so stop passing `bg`/`color`; it follows brand and dark mode on its own. `AvatarGroup` takes `people=[{name, src}]`, not `<Avatar>` children, so it can build one accurate group label. Measured by typecheck: 13 of 18 consumer files break | wrap in a `Box` for placement/shadow; resolve `name` at the call site |
 | `SettingsSection` | New optional `action` slot, right of the title/description on the header row — additive, nothing changes without it | — |
-| `Button` / `Buttons` | Icon-only buttons are square. `Buttons` (plural) is themed instead of hardcoded purple | — |
+| `Button` | Icon-only buttons are square | — |
 | `ProgressBar` | Fill lifted to ≥ 3:1 on its track — green/orange/blue/cyan are visibly darker in light mode | — |
 | `PhoneNumberInput` | Default `size` `md` → `sm`, so it matches the `TextInput`s beside it | `size="md"` |
 | `PhoneNumberInput` / `PinInput` / `NoteTextArea` | `ref` now attaches; labels bound; PIN digits grouped and named | — |
@@ -565,11 +569,10 @@ For an accent icon on the gradient, use `resolved.ink` unless the accent clears
 All three match children by exact type (`child.type === XHeader/XBody/XFooter`) and render only
 those matches — nothing else in `children` is ever read. A sibling among the slots (a nested
 `Modal`, `AlertDialog`, a confirm dialog, a live region) silently never mounts; `Drawer` and `Modal`
-now warn once per dropped child type in development, `ProfileCard` still says nothing. All three
-unwrap **one** `<>...</>` level around a slot (so `<>{cond && <DrawerFooter>...}</>` still renders)
+`ProfileCard` now warn once per dropped child type in development. 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 — a second nested fragment, or any other wrapper element, still drops the slot
-silently.
+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
@@ -580,6 +583,10 @@ as a sibling in a wrapping fragment. When a ternary picks between bodies, branch
 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
@@ -612,9 +619,19 @@ green. Pass `onClick` for a clickable card (it renders its own `<button>`); neve
 Unlike `Tag` and `StatCard`, where `info` is blue, the default `tone="info"` here paints the brand
 primary scale. `aria-label` is required — the ring has no visible caption.
 
+### `TextInput variant="filled"` has no border, only a fill that barely separates it
+
+`filled` draws no resting border (`borderColor: "transparent"`), so the field's edge is the fill
+alone. That fill measures 1.01-1.06:1 against a card in light mode on the nine brands, well under
+the 3:1 that WCAG 1.4.11 asks of a control boundary, and about 1.19:1 in dark mode. The focus ring
+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
+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"
@@ -626,7 +643,7 @@ undefined and stripped. Verified by DOM dump: the rendered `<input>` carries no
 even when `isRequired` is passed. The visible asterisk comes from a separate custom label, so the
 field *looks* required to sighted users and is silent to a screen reader.
 
-**Apply:** `SelectSearch` is `@deprecated` — use `Select` (`native={false}`), which marks required
+**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
@@ -691,6 +708,15 @@ 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
@@ -723,15 +749,12 @@ const AppTable = ({ variant = 'classic', ...props }: TableProps) => <Table varia
 ```
 Applies to any library prop with a default value, not just `Table`'s `variant`.
 
-### `FormWrapper` has a closed prop list — no `...rest`
+### `FormWrapper` forwards extra props to the outer wrapper only
 
-It destructures exactly `{ icon, text, children }` and forwards nothing else to either the outer
-wrapper or the bordered content `Box` — a `data-testid`, `id`, a margin override, or an `onClick` on
-the wrapper all silently disappear, and TypeScript won't catch it since excess-property checks don't
-apply to spreads.
+`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:** wrap `FormWrapper` in your own `Box` when you need margin, a test hook, or an id on the
-section — don't expect anything but `icon`/`text`/`children` to reach the DOM.
+**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
 
@@ -754,15 +777,15 @@ blank email submits successfully with no error shown.
 **Apply:** if the parent needs to react to success, this component can't provide it. Don't rely on
 `email` being enforced as required — validate it yourself first if that matters.
 
-### `VerifyEmailOtp` can't accept alphanumeric codes
+### `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` text also
-always gets a hardcoded second line appended — "your new Pixel Account" — with no prop to remove it.
+`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 with product copy that matches that exact
-trailing phrase. Otherwise build the card from `PinInput` plus your own text.
+**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
 
@@ -873,23 +896,6 @@ the library (`TextInput`, `NumberInput`, `PhoneNumberInput`, `RadioButton`, `Pin
 **Apply:** always pass `isInformation` and `informationMessage` together; never treat
 `isInformation` alone as "use a default message."
 
-### `ErrorComponent`'s `error` prop is the message text itself — the opposite of `error`+`errorMessage`
-
-Every other field in the library pairs a boolean `error` with a string `errorMessage`.
-`ErrorComponent` (used internally by `Input`) instead takes `error: string` directly as
-the message, with no internal truthy-check — passing `error=""` still draws the full icon next to
-blank text. It also has no `id`, so unlike `ErrorMessage` it can't be wired to `aria-describedby`.
-
-**Apply:** treat `ErrorComponent` as `Input`-specific, not a general error row; guard it
-with a truthy-message check yourself, and use `ErrorMessage` for any other field.
-
-### `FormattedDescription`'s single-`*italic*` marker strips the asterisks but applies no italic style
-
-`**bold**` works; a lone `*word*` silently renders as plain text with the markers removed, reading
-as though the formatting was simply ignored.
-
-**Apply:** don't rely on single-asterisk emphasis in `content` strings — use `**bold**` or plain text.
-
 ### `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
@@ -970,13 +976,13 @@ props. Mixing plain and `customNode` items in one column produces inconsistent p
 **Apply:** don't expect board-wide card actions to reach a `customNode` card; wire them inside your
 custom render instead.
 
-### `KanbanBoard`'s `AccountCard` only renders string-typed fields, and labels are the raw key
+### `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 with only its first letter capitalised — `account_name` renders
-"Account_name", `nextFollowUp` renders "NextFollowUp"; nothing splits words.
+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; use keys that read acceptably as-is.
+**Apply:** keep numeric display values as strings.
 
 ### `KanbanBoard`'s `onColumnDelete` receives the deleted column's **card** ids, not the column's id
 
@@ -989,7 +995,7 @@ 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` and the internal `Input.tsx` set native `required` (browser bubble, blocks submit).
+`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.
 
@@ -1021,15 +1027,6 @@ 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 })`.
 
-### The internal `Input.tsx` silently ignores six declared props
-
-`disabled`, `autoComplete`, `autoFocus`, `inputClassName`, `labelClassName`, and `errorClassName`
-are all typed on `InputProps` but never read — passing them, `disabled` especially, compiles cleanly
-and does nothing. It also has no `id` field, so its label always renders as an unassociated `<span>`.
-
-**Apply:** this is an internal component (not exported) reachable only via deep import — prefer
-`TextInput` for anything public-facing, which doesn't have this gap.
-
 ### `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
@@ -1057,6 +1054,17 @@ child, with no tooltip element and no document listeners. A test that mocks Chak
 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
@@ -1077,14 +1085,6 @@ button, right icon/dropdown), not just a "clicked outside the buttons" signal.
 **Apply:** always set `rightIcon` + `rightIconDropdown={true}` together for the dropdown. Don't use
 `onButtongroupClick` to detect background clicks — inspect `event.target` if you need to distinguish.
 
-### `Buttons` (plural) is not a group wrapper
-
-Despite the plural name suggesting a group, `Buttons` is now a thin wrapper over one themed
-`Button` (its `className` is `@deprecated`), and it isn't exported from the package root.
-
-**Apply:** use `Button` for a single themed button or `ButtonGroupIcon` for a themed group; there is
-no good reason to reach for `Buttons`.
-
 ### `Card` 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`/
@@ -1163,9 +1163,9 @@ Inside a `NavigationBar` `moreIcon` cluster, a full trigger needs about 88px (av
 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"`. In avatar mode
-the accessible name is `${ariaLabel}, ${org name}` and 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
+**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.
 
@@ -1242,8 +1242,10 @@ 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 that `FileUploader` never revokes. Call
-`URL.revokeObjectURL` when you drop the entry or unmount. (`FileUpload` revokes its own thumbnail URLs.)
+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
 
@@ -1280,6 +1282,15 @@ is also `null` until Jodit's lazy-loaded chunk resolves — a mount-time effect
 **Apply:** never set `theme`/`popupRoot` inside the `config` you pass to `Editor`. To force a
 remount, wrap `<Editor>` itself in a keyed parent, not via `Editor`'s own `key` prop.
 
+`Editor` 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,
@@ -1315,6 +1326,15 @@ test asserting the old single-row layout needs `actionsLayout="inline"`.
   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"`
@@ -1329,6 +1349,17 @@ above — a value you pass in `config` wins) and runs a `MutationObserver`-backe
 **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.
+
 ### `SelectV2`, `SearchSelect`, and `SelectSearch` all search `option.label` only
 
 None of the three checks a rendered secondary field (`option.description`, a custom `view` node,
@@ -1500,12 +1531,15 @@ control expecting `onMaximize` to fire.
 
 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 —
-`FilterSection.checkboxes` doesn't exist either; radio-vs-checkbox mode is actually decided by
+`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. Don't reach for `onApply`/`headerPadding`/`sliderMode`/`FilterSection.checkboxes` —
+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
@@ -1595,7 +1629,8 @@ hidden and arrow keys stop at the edge of the visible range, so the grid looks s
 `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.
+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
 
@@ -1613,6 +1648,17 @@ 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,
@@ -1625,6 +1671,16 @@ matches either, even when the "same" stage is clearly intended.
 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`, and `onColumnFilter` are dead props — now `@deprecated`
 
 Grepped account-frontend, tickets, crm-frontend, hrms and social-frontend: zero consumers set any of
@@ -1912,7 +1968,8 @@ A wide node header is also **clipped, not ellipsized** — the header's ellipsis
 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.
+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
 
@@ -1935,9 +1992,11 @@ can outgrow the column.
 - `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`, so put a Clear action beside it if one is needed.
+  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`.
+  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

package/DESIGN-GUIDE.md

@@ -52,11 +52,31 @@ Borders are the one px value: `borderWidth="1px"`. Fixed widths (side panel, lis
 | Body | `Text fontSize="sm" color={colors.text[800]}` |
 | Label / meta / helper | `Text fontSize="xs" color={colors.textMuted}` |
 | KPI tile | `StatCard` — pass `trend` and `goodDirection`; the delta is green when the change is *good* (a shorter sales cycle is green); `iconTone` tints the icon chip (unset = brand primary) |
-| Numbers in tables/columns | `sx={{ fontVariantNumeric: "tabular-nums" }}` so digits align; `Table` columns take `align: "end"` |
-| Overline (rare) | `fontSize="xs" fontWeight={600} textTransform="uppercase" letterSpacing="0.06em"` |
+| Numbers in tables/columns | `sx={NUMERIC_TEXT}` (root export, tabular figures) so digits align; `Table` columns take `align: "end"` |
+| Code, ids, shortcuts | `fontFamily="mono"` (a real monospace stack); shortcut hints are `KbdShortcut`, never a hand-styled `<kbd>` |
+| Overline (rare) | `textStyle="overline"` |
 
-Chakra size keys only (`xs sm md lg xl 2xl`) — never `fontSize="14px"`, never below `xs`.
-Weights: 400 body, 500 labels, 600 titles, 700 KPI numbers only.
+**`textStyle` sets size, line height, weight and tracking in one prop.** Prefer it to hand-picking
+the four: `<Text textStyle="label">`. The ramp (`TEXT_STYLES`, also a root export):
+
+| `textStyle` | Use |
+| --- | --- |
+| `title` · `heading` · `subheading` | page / section / card titles (24 · 20 · 16px) |
+| `body` | running text (14px) |
+| `ui` · `label` | control and form text (13px, weight 500 · 600) |
+| `caption` | helper and meta text (12px) |
+| `overline` | small-caps eyebrow (11px, uppercase) |
+
+Chakra size keys only (`xs-minus xs xs-plus sm md lg xl 2xl`) — never `fontSize="14px"`.
+`xs-plus` (13px) is the control size; `xs-minus` (11px) is for chips, counts, keyboard hints and
+overlines only; nothing is smaller. Weights: 400 body, 500 labels, 600 titles, 700 KPI numbers only.
+
+**Radius and elevation come from the role, not the scale step.** `RADIUS_ROLE` (root export) names
+the radius a surface plays: `control`, `field`, `tooltip` and `media` 8px · `option` 6px · `card`,
+`float`, `dialog` and `sheet` 12px · `chip` full. Anchored popups (`Menu`, `Popover`, `Select`,
+`Dropdown`) all take the 12px radius, and `Menu` and `Popover` the `md` (float) shadow, so a panel
+you build yourself takes `borderRadius={RADIUS_ROLE.float}` and `boxShadow="md"`. A resting card is
+`shadows.card`; heavier shadows belong to floating things only.
 
 ## 4. Color — pick by role
 
@@ -91,8 +111,9 @@ stay light in dark mode.
 | Must stand out (a status that needs attention) | `variant="solid"` |
 | Dense list, table cell, or an already-colored surface | `variant="outline"` — no fill to compete with the surface |
 
-`secondary` and `tertiary` render as the same hex on most brands (see `COMPONENT-GOTCHAS.md`) —
-don't lean on that pair to distinguish two categories; reach for a utility scheme instead.
+`secondary` and `tertiary` are two distinct accents on every brand except `zinc`, which is
+near-grey and has almost no hue to turn (see `COMPONENT-GOTCHAS.md`) — on `zinc`, reach for a
+utility scheme to tell two categories apart.
 
 ## 5. Controls — two scales, `sm` by default
 
@@ -155,6 +176,7 @@ sections are `Card` with the title in `header`.
 | Multi-step flow (send, import, onboard) with validated Continue and a review step | `WizardDialog` (`Wizard` inline; `chrome="inline"` inside a `WorkspaceWindow` or other host that is already the dialog) — don't hand-roll Back / Continue / Finish around `StageProgress`; each step's `validate` returns its error messages, future steps stay locked until valid, each step's `summary` drives the review |
 | Rich-text template with `${field}` placeholders | `Editor mergeFields={…}` — not a `Select` + caret tracking + dialog beside it; use its `label` / `helperText` / `errorMessage` |
 | A PDF behind auth, shown inline | `PdfViewer getBlob={…}` — the toolbar's Open / Download then work with the token, so don't add your own buttons |
+| Data grid | `Table` — defaults to `variant="studio"` (flat small-caps header, one row rule, the select slot resting on the row number, status as a pill). Pass `variant="classic"` for the banded header and per-column rules; don't restyle the header or rows by hand |
 | Toolbar: search · filters · active-filter chips · count · actions | `FilterBar` (`search`, children, `activeFilters` + `onRemoveFilter`/`onClearAll`, `summary`, `actions`) |
 | Read-only label/value grid (record details, key facts) | `DescriptionList` (`items`, `columns`, `layout="inline"` for a side panel, `copyable`, `isLoading`) |
 | Settings row (title + description left, control right) | `SettingRow` inside a `SettingsSection` (`isDanger` for the danger zone, `action` for a header-right button) |
@@ -177,6 +199,23 @@ sections are `Card` with the title in `header`.
 scrim `Box`. `Loading` is the older API and stays on the heavier house scrim by default; pass
 `variant="dim"` to route it through `Backdrop`, or just use `Backdrop` directly.
 
+### Parts you reach for through their parent
+
+These are root exports, but each belongs to a parent component; start from the parent unless a row
+here says otherwise.
+
+| Part | Belongs to | Use it for |
+| --- | --- | --- |
+| `DrawerHeader` · `DrawerBody` · `DrawerFooter` | `Drawer` | the only children a `Drawer` renders; style props go straight on each slot. For a create / edit form use `FormDrawer` instead |
+| `ProfileCardHeader` · `ProfileCardBody` · `ProfileCardFooter` | `ProfileCard` | the only children a `ProfileCard` renders; any other sibling is dropped |
+| `StageItem` | `StageProgress` | one chevron, bar or pill stage; `StageProgress` renders it, so don't lay stages out by hand |
+| `FilePreviewTrigger` | `FilePreview` | a thumbnail button that opens one file in a modal; for several attachments use `MediaViewer` |
+| `MediaScrubber` · `MediaStatusPanel` · `MediaDocumentStage` | `MediaViewer` | building a custom media UI: a `role="slider"` seek bar (`onSeek`), the no-preview / error panel (`tone="warning"` for errors), and the document stage driven by a `resolveDocument` you supply |
+| `LazyWrapper` | `React.lazy` | a `Suspense` boundary with the themed spinner; pass `fallback` to replace it |
+| `ScrollbarBox` | any scrolling region | a themed scroll container; give it an `aria-label`, because it is a keyboard stop while it scrolls |
+| `AppearanceSettings` | a settings page | the theme, colour-mode and font-size controls in one panel; brand and font size are controlled, the colour-mode switch reads the theme context |
+| `ApexPolarChart` | `ApexPieChart` | independent magnitudes as wedges of equal angle and varying radius; values that add to a whole belong in `ApexPieChart` |
+
 ### Navigation shell
 
 `SideBar` is the rail, `NavigationBar` the top bar, `NavLauncher` the full-height "go anywhere" panel.
@@ -236,7 +275,8 @@ hides its primary; when only one section is empty on a populated page, that sect
   `Menu`…) come from `pixelize-design-library` too. Anything the library owns a component for
   (`Tabs`, `Accordion`, `Modal`, `Card`, `Select`, `TextInput`, `Skeletons`…) has no Chakra
   passthrough at all — the owned component is the only one.
-- Reaching for `SelectV2`, `SearchSelect`, `SelectSearch` in new work — all `@deprecated`.
+- Reaching for `SelectV2` (`@deprecated`), `SearchSelect` or `SelectSearch` (not deprecated, but not the
+  preferred picker) in new work.
   One picker now: `Select` (`native={false}` for the themed, searchable, multi popup).
   `Dropdown` is the exception — it is an action menu, not a picker, and is not replaced.
 - A card inside a card; a border on a content `Card` (it is borderless by default), or any resting