pixelize-design-library 2.4.2-beta.5 → 2.4.2-beta.51

package/COMPONENT-GOTCHAS.md

@@ -0,0 +1,1460 @@
+# 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`.
+
+**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`, `isSelectAll`, `rightIcon`, a field-level loading slot and the paginated `pagination.onScroll` shape (1-based `startIndex`/`limit`/`query`) have **no** equivalent in `Select` today. Keep using it until they do |
+| `SelectSearch` | **Not deprecated** — implementation untouched | Hand-migrate. It is uncontrolled (`initialSelectedOption` seeds state once and never resyncs) and moves real DOM focus into rows; `Select` is controlled and uses `aria-activedescendant` |
+| `Dropdown` | **NOT deprecated** — the marker was wrong and was removed 2026-09-21 | Never "migrate" it to `Select`. It is a menu-button (`role="menu"`/`menuitem`, `aria-haspopup="menu"`), not a value picker (`role="combobox"`/`listbox`). Swapping it would be an accessibility regression, and nothing in this library replaces it |
+
+**Still genuinely different, not pickers at all:**
+
+| Doing | Component |
+| --- | --- |
+| Typing free-text tags (e.g. email addresses), no options list | `MultiSelect` — despite the name there is nothing to pick from; see gotcha below |
+| Choosing which fields/columns to include, in a modal, from a checkbox grid | `FieldSelectModal` |
+
+`onChange` is the change prop on `Select` and `SelectV2` (`SearchSelect.onSelect` is the one it
+actually uses; its `onChange` is passed almost nowhere). `Search` uses `onSearch`/`onClear`
+(`onclose` is `@deprecated`).
+
+### `Dropdown`'s `handleOptionSelect` takes TWO arguments and TypeScript will not tell you
+
+The prop is `(id, label) => void`. TypeScript accepts a one-argument function anywhere a
+two-argument one is expected, so `handleOptionSelect={handleSelect}` where `handleSelect`
+is `(id: string | number) => void` compiles cleanly and silently never receives `label`.
+
+This is live in **10 call sites today** across crm-frontend and commerce — every one of them
+a bare function reference rather than an inline arrow.
+
+**Apply:** pass an inline arrow (`(id, label) => handleSelect(id, label)`) so the arity is
+visible at the call site, or declare the handler with both parameters. Grep for
+`handleOptionSelect={` followed by a bare identifier.
+
+### `Slider` is an image carousel, not a numeric range input
+
+`Slider` auto-advances a set of images/content on a timer — no numeric value, min/max, or step. The
+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` 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` / `Buttons`
+
+| Need | Component | Why not the others |
+| --- | --- | --- |
+| 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 |
+
+### Which "card" — `Card` / `ProductCard` / `ProductDetails` / `PaymentCard`
+
+| Need | Component | Why not the others |
+| --- | --- | --- |
+| Generic bordered/padded container, no commerce semantics | `Card` | Layout wrapper with `header`/`footer` slots and a padded body — see gotcha below |
+| Compact product tile for a grid/listing page | `ProductCard` | Fixed size presets, single-image hover-swap, no gallery |
+| Full product detail page layout (gallery + description + variant picker) | `ProductDetails` | No card chrome of its own; same variant-list shape as `ProductCard` but named `price`, not `options` |
+| Subscription/pricing-tier card (plans, billing cycle, feature list) | `PaymentCard` | Takes a `Plan` object, unrelated to `options`/`productImage` |
+
+### 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 |
+| Collapsible/dockable left rail — primary in-app navigation + secondary panel | `SideBar` | The persistent nav shell, not for switching between whole apps |
+| 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 |
+| 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 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.
+
+### 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 |
+| Crop/preview a user avatar | `ProfilePhotoViewer` | Avatar-specific, not a general file viewer |
+
+`PdfViewer` and `FilePreview` both render a PDF through the identical unstyled `<embed type="application/pdf">` with no error handling if the browser can't render it inline — neither tells you when that happens. `MediaViewer` does handle it: formats a browser cannot decode (`.avi`, `.mkv`, `.m3u8`, `.heic`, `.tiff`) render an icon and a file-type chip with a download action instead of a blank frame.
+
+`MediaViewer.labels` takes a `Partial<MediaViewerLabels>` — that type and `defaultMediaViewerLabels` are both exported from the package root, so you can merge rather than restate every string.
+
+`MediaViewer`'s `index`/`onIndexChange` are now optional: omit both for uncontrolled (it owns the index, starting at `defaultIndex ?? 0`), or pass both to control it. Passing `index` without `onIndexChange` freezes the viewer — every nav path has nowhere to write the new index — and now warns loudly in dev.
+
+### `HeaderActionsProps` describes a different component than `HeaderActions`
+
+The value `HeaderActions` comes from `Components/Header/HeaderActions.tsx`, which declares its props inline. The type `HeaderActionsProps` re-exported from the package root comes from `Components/Table/TableProps.tsx` — the *table's* internal bulk-action bar. Typing a `HeaderActions` usage with `HeaderActionsProps` compiles into the wrong shape.
+
+**Apply:** don't annotate `HeaderActions` with `HeaderActionsProps`. Let the props infer from the component, or use `React.ComponentProps<typeof HeaderActions>`. Same trap as `FileUploaderProps` above — check which folder a type came from before trusting the name.
+
+### Confirm prompts — `ConfirmDialog` vs `AlertDialog` vs `Modal`
+
+| Need | Component | Why |
+| --- | --- | --- |
+| A delete/deactivate prompt with a header swatch and a red Confirm | `ConfirmDialog` | The shared shape behind the library's confirm modals; `tone="destructive"` (the default) fills Confirm red |
+| A simple two-button yes/no | `AlertDialog` | Lighter; `confirmButtonText`/`cancelButtonText`, `tone="danger"` for a red Confirm |
+| Anything else | `Modal` | Named slots only — see the slot gotcha below |
+
+**`ConfirmDialog.onConfirm` does not close the dialog.** It fires and nothing else; you call `onClose` yourself. That is deliberate — it lets you keep the dialog open while an async delete is in flight — but a handler that only calls your delete function leaves the dialog on screen with no error.
+
+`iconBg` and `iconColor` are **required** and take raw colour strings, so the caller resolves the tone. Read them from `useCustomTheme()` — a hardcoded hex there is stuck in light mode.
+
+### Busy indicators — `Spinner` vs `Backdrop` vs `Loading`
+
+| Need | Component | Why |
+| --- | --- | --- |
+| Inline busy mark in a row, cell or button area | `Spinner` | The package-root `Spinner` is the themed one (accent colour, own xs–xl `size` scale), not Chakra's raw spinner |
+| **Scrim over the page or one panel — the default for new work** | **`Backdrop`** | `variant="dim"` by default: black at 0.5, no blur, 225ms in / 195ms out, 40px spinner. `container` scopes it, `onClick` dismisses, `invisible` blocks without painting |
+| Let clicks reach the page while a scrim is showing | `Backdrop allowBackgroundInteraction` | Drops `pointer-events` on the scrim **and** its transition wrapper. `onClick` cannot fire while set — that is the trade |
+| Existing screens already using it | `Loading` | The older API. Its default `variant="frosted"` keeps the heavier house scrim (0.6 + 4px blur) so nothing shifts; `variant="dim"` routes it through `Backdrop` |
+
+**Never hand-roll a scrim.** A `position: fixed` `Box` with your own `rgba()` will not match the
+Modal/Drawer overlay, will not fade, and will not follow dark mode. `Backdrop` is the one owner.
+
+One trap if you build anything similar yourself: setting `pointer-events: none` on your overlay is
+not enough when the overlay sits inside a transition wrapper — the wrapper keeps capturing clicks.
+`Backdrop` sets it on both.
+
+### Data states — `EmptyState` / `ErrorState` / `QueryStateBoundary`
+
+| Need | Component | Why |
+| --- | --- | --- |
+| "Nothing here yet" with an optional action | `EmptyState` | Neutral placeholder |
+| A failed load with retry | `ErrorState` | `role="alert"`, `onRetry`/`isRetrying` built in |
+| One fetch that can be loading, failed, empty or ready | `QueryStateBoundary` | Picks for you: loading > error > empty > `children` |
+
+---
+
+## Known gotchas (silent failures)
+
+### Defaults changed in 2.4.2-beta.44 — read this first when upgrading from beta.43
+
+| Component | beta.43 → beta.44 | Restore the old look |
+| --- | --- | --- |
+| Fields, selects, buttons (`Button`, `TextInput`, `InputTextArea`, `NumberInput`, DatePicker family, `Select`, `SelectV2`, `SearchSelect`, `SelectSearch`, `Search`, `Dropdown`, `SegmentedControl`) | Default size `md` → `sm` (35px). One scale for all: xs 28 / sm 35 / md 40 / lg 48 — `md` is now 40px everywhere (`TextInput` was 44, selects 38, `SegmentedControl` ~36). `TimePicker` has no `size` (fixed `sm`); `SegmentedControl` has no `xs` | `size="md"` |
+| `Button` | Text one step smaller (sm 14→13px, md 16→14, lg 18→16). Busy = spinner only, width kept (was "Loading" + spinner). Outline: 1px border, hover is a tint, not a fill | `loadingText="Loading"` |
+| `Tag` | `solid`/`md` → `subtle`/`sm`. Hover + pointer only with `onTagClick`; `maxW` truncates with the full text as a title. Exact heights 20/24/28/32, weight 500, 1px inset ring (never adds height); subtle is a light tint with ink ≥ 6.5:1 | `variant="solid" size="md"` |
+| `resolveSoftTone` | `bg`/`border` are now translucent (alpha hex) — composite onto the surface before `contrastRatio`; optional 3rd `surface` arg; adds `hoverBg`/`activeBg`. Badge/Alert/Toaster/EmptyState follow | — |
+| `resolveFilledSurface` | Still white-first; when a white-labelled fill would vanish on the canvas (zinc dark primary) it falls back to a light fill with dark ink. Takes `background` in `colors` now | — |
+| `Checkbox` / `RadioButton` | Box 16/20/24 → 14/16/20; label 14px; 1px border; one fill rung for every `colorScheme`. **`RadioButton colorScheme` now applies** (was always primary) | — |
+| `ToggleSwitch` / `SegmentedControl` / `TableToggle` | Off track lifted to 3:1; thumb ink flips on light fills. Radius `lg`; `TableToggle` tooltips = button names, `aria-pressed` | — |
+| `MultiSelect` | Default `md` → `sm`; real `<label>`; shared two-tone focus ring | `size="md"` |
+| Selected rows (`Dropdown`, `SelectV2`, `SearchSelect`, `SelectSearch`, `MoreItems`, `Table` filters, menus) | Dark aliases `backgroundColor.tertiary` to the panel, so a selected row sat at 1.025:1 and was invisible. It is now lifted to a perceptible step. Light is byte-identical on eight brands; `zinc` moves slightly, having been below the step too | — |
+| `tertiary` | Was an exact copy of `secondary` on six brands and of `primary` on three, so `colorScheme="tertiary"` rendered as another scheme. Now a real third accent: `primary`'s hue turned 60° at `secondary`'s luminances, so contrast is unchanged | use `secondary` |
+| `SelectV2` | Trigger is now `div[role=combobox]`, not `<button>` — widen a `useRef<HTMLButtonElement>` to `HTMLDivElement`; assert `aria-disabled`, not `toBeDisabled()`. `isMulti` shows removable `Tag` chips (`maxVisibleChips`, default 6, then `+N`); Backspace removes the last; `maxLabelsBeforeSummary` now only shapes the `aria-label`. Read-only is `data-readonly`, not `aria-readonly` | custom `renderValue` for text |
+| `SearchSelect` / `SelectSearch` | Menu radius `lg` → `xl`, shadow `lg`. `SearchSelect`'s button triggers are now `role=button` named `"Label: value"`; only the text input is `role=combobox` — update `getByRole("combobox")` queries | — |
+| `TextInput` | **`type="password"` now auto-renders a show/hide toggle** — a plain password field gains a button it did not have in beta.43. Suppressed automatically when `inputRightIcon` is set, so a hand-rolled toggle never doubles up; `isPasswordToggleDisabled` opts out entirely. Also new: `variant` (`outline` default / `filled` / `flushed`), `isClearable`, `showCharacterCount` + `maxLength`, `inputLeftAddon`/`inputRightAddon`, `isLoading`. `inputStyle`/`leftElementStyle`/`rightElementStyle` are now `SystemProps` and `inputGroupStyle` is `CSSProperties` — all four were bare `object`, so a wrong key that used to compile now fails | `isPasswordToggleDisabled` |
+| Chakra passthroughs | 34 barrel value exports (and 12 type exports) that duplicated an owned component were removed: `Input`, `Textarea`, `Progress`, `Radio`, `RadioGroup`, `Skeleton`, `ModalOverlay`, `ModalContent`, `ModalCloseButton`, `CardBody`, `ChakraCard`, `ChakraSelect`, `ChakraModal`(+`Body`/`Header`/`Footer`) the `Tabs`/`Accordion` families, and the Chakra slider sub-parts. `Tabs`, `Accordion` and `RangeSlider` now resolve to the library's own themed components (`RangeSlider` gained a real dual-thumb mode and a `marks` prop). Each removal is a compile error, never a silent swap | use the owned component — `TextInput`, `InputTextArea`, `ProgressBar`, `RadioButton`, `Skeletons`, `Modal`, `Card`, `Select` |
+| `Avatar` / `AvatarGroup` | Now the library's own components, not Chakra passthroughs. `AvatarProps` is a closed list (`name`, `src`, `size` `2xs`–`xl`, `status`, `ariaLabel`, `getInitials`, `data-testid`) — Chakra style props and `2xl` no longer compile, and **`name` is now required `string`**, so a `user.name?: string` call site fails. The fill is derived from `name`, so stop passing `bg`/`color`; it follows brand and dark mode on its own. `AvatarGroup` takes `people=[{name, src}]`, not `<Avatar>` children, so it can build one accurate group label. Measured by typecheck: 13 of 18 consumer files break | wrap in a `Box` for placement/shadow; resolve `name` at the call site |
+| `SettingsSection` | New optional `action` slot, right of the title/description on the header row — additive, nothing changes without it | — |
+| `Button` / `Buttons` | Icon-only buttons are square. `Buttons` (plural) is themed instead of hardcoded purple | — |
+| `ProgressBar` | Fill lifted to ≥ 3:1 on its track — green/orange/blue/cyan are visibly darker in light mode | — |
+| `PhoneNumberInput` / `PinInput` / `NoteTextArea` | `ref` now attaches; labels bound; PIN digits grouped and named | — |
+| `RangeDatePicker` | Outside click keeps a fully picked range (was discarded) | — |
+| `FilePreview` / `ContactForm` | Radius `2xl` → `xl` | — |
+| `Avatar` / `Timeline` / `Table` | Generated avatar fills now guarantee ≥ 4.5:1 initials (a name may get a different shade); Timeline rail lifted to 3:1; Table status/filter chips use the soft recipe; stray radii → `lg`/`xl`/`full` | — |
+| `AlertDialog` | Yes/No → Confirm/Cancel; Cancel is a neutral gray outline (was red) | `confirmButtonText`/`cancelButtonText`; `tone="danger"` for a red Confirm |
+| `Modal` | Page scroll now locks (`blockScrollOnMount` was silently off); `motionPreset="scale"`; theme scrim (60% black + blur) — drop any `overlaybackdropFilter` hue-rotate workaround; `isLoading` keeps header + close button | `blockScrollOnMount={false}` |
+| `Toaster` | `showToast` returns an id; `update(id, patch)` / `close(id)`; `loading` toasts never auto-dismiss | pass `duration` |
+| `ToolTip` | `openDelay` 0 → 300ms; 13px themed look | `openDelay={0}` |
+| `InputTextArea` / `FileUpload` / `TextInput` | Width 500px → 100% / `maxSizeKB` 5 → 5120 / no default "Placeholder" text | `width="500px"` / — (5 KB was a bug) / — |
+| `DatePicker` (no `pickerType`) | Inference is case-sensitive: `MM` is month, `mm` minutes. `dd/MM/yyyy` was misread as date+time and showed time selects; it is now date-only | `pickerType="datetime"` |
+| `EmptyState` | Title is an `h3`; image is decorative (`alt=""`, was the title) | `titleAs`, `imageAlt` |
+| Theme `Badge` / `Card` / field labels | Badge: pill, no uppercase, default `sm`. Card: default variant `outline`. Label colour `text[700]`; helper/error row 12px | `size`/`variant` props |
+| `Header` | `position: sticky; top: 0`, z-index `sticky` (1100, was 1000); `rightSlot` mounts once, not per layout | — |
+| `Table` | Radius `xl`; row height 32/40/52 by density; filter button is named "Filter {label}" (tests querying "Search" break); client pagination resets to page 1 when `data.length` changes | — |
+| `KanbanBoard` | `height`/`maxH` props replace the clipping wrapper; `height="100%"` needs a parent with a definite height | — |
+| `ProfileCard` / `SideBar` | `variant="outlein"` now draws an outline; header divider 1px `boxborder[200]` / mobile backdrop uses the shared scrim | — |
+| `SideBar` | Scroll-container and submenu ids are generated (`useId`) — `#sidebar-scroll-container` / `#submenu-<label>` no longer exist; row heights fixed 20/32/48; count badges use soft tone | — |
+| `ToggleSwitch` | No `aria-required` on the switch (invalid for `role=switch`); `isRequired` still shows `*` | — |
+| `KanbanBoard` / `PdfViewer` / `UserDetails` | Cards, drag handles and toolbar links get accessible names; scroll panels are focusable regions; `UserDetails` badges 12px | — |
+| `NumberInput` / `FileUpload` | Steppers exactly half the field height; drop-zone border 1px (was 2px) | — |
+| `HeaderActions` | Edit/Create are real `<button>`s (keyboard reachable, focus ring); select named by `select.ariaLabel` or its placeholder | — |
+| `SearchSelect` | New `aria-label` prop for fields without a visible `label` | — |
+| New root exports | `mergeRefs`/`setRef`, `rafThrottle`, `toWords`, `useDebouncedCallback`/`useDebouncedValue`, and the chart theming kit (`getCategoricalSeriesColors`, `chartInk`, `labelOnSeries`, …) — previously internal-only | — |
+| `toWords` | Now splits camelCase (`nextFollowUp` → `Next Follow Up`), so `Timeline`/`KanbanBoard` auto-labels read correctly instead of `Nextfollowup` | pass an explicit label |
+| Focus rings (all controls) | `focusRing.ring` is now the brand accent itself (lavender `#8B3FC8`), not a near-black band — the white halo already separates it from a filled control | — |
+| `Tag` | Label line-height 1.45 so descenders (`p`, `g`, `y`) are no longer clipped by the ellipsis overflow | — |
+| `Toaster` | `error` toasts announce assertively (`role="alert"`); status icons have a text equivalent | — |
+| `FeedbackForm` | Built on `TextInput`/`InputTextArea`/`RadioButtonGroup`; required fields show `*` in the label | — |
+| `PinInput` | `size` now works (square cells 28/35/40/48, default `sm`) — it was silently ignored | `size="md"` |
+| `Tag` | New `leadingIcon` (decorative, before the label) and `isDisabled` (sets `aria-disabled` + native `disabled` on the clickable/remove buttons, so they leave the tab order — not just dimmed) | — |
+| `ToolTip` | Defaults a Popper `preventOverflow` padding of 8px, so a bubble near the right edge no longer overhangs by a subpixel and raises page scrollbars. A caller-supplied `preventOverflow` modifier still wins | pass your own `modifiers` |
+| `Table` / `KanbanBoard` | Column sort buttons and draggable cards now show the library focus ring on keyboard focus (was an opacity flicker / the browser default outline). Kanban card wrappers render as Chakra `Box`; keyboard drag (Space, arrows, Space) is unchanged | — |
+| `Search` / `FilterBar` / `SettingRow` / `NoteTextArea` | `Search` names itself from `placeholder` when there's no `label`/`aria-label`. `FilterBar` wraps `search` in a `role="search"` landmark named by `searchLabel` (default "Search"). `SettingRow` auto-wires an unnamed `control` to the row's title/description via `aria-labelledby`/`aria-describedby` unless it already has its own `aria-label`. `NoteTextArea` adds `titleAriaLabel`/`noteAriaLabel` (default "Note title" / `customPlaceholder`) | — |
+
+### Removed barrel exports → what to import instead (beta.44)
+
+Every name below stopped resolving from `pixelize-design-library` in beta.44. Each is a **compile
+error**, never a silent swap, and each has an owned replacement that is already exported. Props
+differ — this is a rewrite of the call site, not a rename.
+
+| No longer exported | Import instead | Note |
+| --- | --- | --- |
+| `Input` | `TextInput` | Owns its label, helper/error text and password toggle |
+| `Textarea` | `InputTextArea` | |
+| `ChakraModal`, `ModalContent`, `ModalOverlay`, `ModalCloseButton`, `ChakraModalHeader`, `ChakraModalBody`, `ChakraModalFooter` | `Modal` | `Modal` renders the overlay, content and close button itself — drop those three. **`ModalHeader`/`ModalBody`/`ModalFooter` are still exported** and are still how you fill it; only the `Chakra`-prefixed aliases went. Header text can come from `title`/`subtitle` instead |
+| `ChakraCard`, `CardBody` | `Card` | `header`/`footer` slots + `bodyProps` |
+| `ChakraSelect` | `Select` | |
+| `Radio`, `RadioGroup` | `RadioButton` / `RadioButtonGroup` | |
+| `Skeleton` | `Skeletons` | Takes `borderRadius` |
+| `Progress` | `ProgressBar` | |
+| `AccordionItem`, `AccordionButton`, `AccordionPanel`, `AccordionIcon` | `Accordion` | Takes an `items` array, not compound children |
+| `SliderTrack`, `SliderFilledTrack`, `SliderThumb`, `SliderMark` | `Slider` / `RangeSlider` | Owned components; the Chakra sub-parts are gone |
+
+**Ten names still resolve** and only narrowed their props — `Accordion`, `Avatar`, `AvatarGroup`,
+`RangeSlider`, `Spinner`, `Tab`, `TabList`, `TabPanel`, `TabPanels`, `Tabs`. They now point at the
+library's own themed component rather than the Chakra passthrough.
+
+### `Tag`'s `onIconClick` renders nothing without `icon` — the remove button silently never appears
+
+`onIconClick` only turns `icon` into a remove button; it has no effect on its own (`Tag.tsx`
+`{icon && (onIconClick ? … : …)}`). Passing `onIconClick` alone — expecting a default close
+affordance the way Chakra's own `TagCloseButton` or AntD's `closable` work — compiles fine and
+renders a plain tag with no way to remove it.
+
+**Apply:** always pass both `icon` (e.g. `lucide-react`'s `X`) and `onIconClick` together for a
+removable chip. `icon` alone (no `onIconClick`) is the decorative case — a plain right-side icon
+with no click affordance, aria-hidden.
+
+### A rounded box with `overflow: hidden` clips glyphs at the corners — never round the clipping element
+
+`border-radius` reshapes the overflow clip, so a pill-shaped element with `overflow: hidden`
+clips text along an **ellipse**, not a rectangle. A leading `p`, `j`, `g`, `q` or `y` loses part
+of its descender to the bottom-left curve. It looks like a font or line-height problem; it is not.
+This shipped in `Tag`, where the label carried both `borderRadius: "full"` (to round its focus
+ring) and `overflow: hidden` (for `text-overflow: ellipsis`).
+
+The two cannot live on the same element. `overflow-clip-margin` does not rescue it either:
+`text-overflow: ellipsis` needs a non-`clip` horizontal axis, and mixing `hidden`/`clip` across
+axes collapses both to `hidden`, which makes the margin inert.
+
+**Apply:** keep the radius on the outer element and put `overflow: hidden` +
+`text-overflow: ellipsis` on a square (`borderRadius: 0`) child. Chakra's `TagLabel` also forces
+`noOfLines={1}` as a style prop, which outranks the theme — pass `noOfLines={undefined}` to drop
+it. In your own components, the same rule holds for any rounded chip, avatar or badge that clips
+its own text. The `/tag` playground's "Glyph clipping" section renders every letter leading and
+trailing at all four sizes as the visual check.
+
+### `colorScheme="tertiary"` is a real third accent from beta.44 (it used to be a duplicate)
+
+Through beta.43 `tertiary` was an exact copy of `secondary` on six brands and of `primary` on three,
+so the two schemes were indistinguishable. It is now `primary`'s hue turned 60° re-solved to
+`secondary`'s luminances, so every contrast guarantee is unchanged.
+
+**Apply:** `secondary` vs `tertiary` is now a real visual distinction on every brand except `zinc`,
+which is near-grey and has almost no hue to turn — use a semantic scheme (`blue`, `teal`, `purple`)
+there if the two categories must read apart.
+
+### Your own overlay painted `background[50]` sinks into the dark canvas
+
+In dark mode `background[50]` equals the page canvas on 8 of 9 brands. Library dialogs, drawers,
+popovers and menus now paint `colors.surfaceRaised` — identical `#ffffff` in light, one elevation
+step up in dark. A custom panel, popover or `ModalContent bg=` in an app should read
+`surfaceRaised` too, and a divider inside it `raisedRule(colors)`.
+
+### `Drawer` / `Modal` / `ProfileCard` drop any child that isn't a named slot
+
+All three match children by exact type (`child.type === XHeader/XBody/XFooter`) and render only
+those matches — nothing else in `children` is ever read. A sibling among the slots (a nested
+`Modal`, `AlertDialog`, a confirm dialog, a portal after the footer) silently never mounts. All
+three now unwrap **one** `<>...</>` level around a slot (so `<>{cond && <DrawerFooter>...}</>`
+still renders) and spread styling props (`padding`, `borderBottom`, `sx`, …) from the matched slot
+onto the real header/body/footer — a second nested fragment, or any other wrapper element, still
+drops the slot silently.
+
+**Apply:** put a confirm dialog **outside** the `Drawer`/`Modal`/`ProfileCard`, as a sibling in a
+wrapping fragment — never among the header/body/footer slots. When a ternary picks between bodies,
+branch into a variable rendered inside one body slot, rather than returning fragment-wrapped slots
+per branch. `Drawer`'s misspelled `vaiant` is `@deprecated` — use `variant`.
+
+### `QueryStateBoundary` evaluates JSX `children` even while loading
+
+JSX children are built before the boundary decides what to show, so `data.items.map(...)` crashes
+while `data` is still `undefined`. **Apply:** pass `children` as a function — `{() => <List
+items={data.items} />}` — whenever it reads data that may not exist yet.
+
+### `StatCard`'s delta colour follows `trend` vs `goodDirection`, not `trend` alone
+
+Green when `trend === goodDirection`, red otherwise — a falling cost with `goodDirection="down"` is
+green. Pass `onClick` for a clickable card (it renders its own `<button>`); never wrap it in one.
+
+### A clickable `TextInput` icon is a real button — give it a name
+
+With `onRightIconclick`/`onLeftIconClick` the icon renders as a `<button>`. Without
+`rightIconAriaLabel`/`leftIconAriaLabel` it is announced as "{label}: right icon action".
+
+### `SelectSearch`'s `isRequired` shows the asterisk but never announces "required"
+
+`SelectSearch` sets `aria-required` by hand on its Chakra `Input`, but Chakra's `useFormControl`
+re-adds its own `"aria-required"` key *after* spreading your props, computed from the surrounding
+`FormControl`. That `FormControl` is never given `isRequired`, so the attribute is recomputed as
+undefined and stripped. Verified by DOM dump: the rendered `<input>` carries no `aria-required`
+even when `isRequired` is passed. The visible asterisk comes from a separate custom label, so the
+field *looks* required to sighted users and is silent to a screen reader.
+
+**Apply:** `SelectSearch` is `@deprecated` — use `Select` (`native={false}`), which marks required
+state on a plain `Box` combobox that Chakra does not rewrite. If you must stay on `SelectSearch`,
+set the required state on your own wrapping `FormControl`. Note the obvious one-line fix inside the
+component is not neutral: Chakra's `useFormControl` also emits native `required`, which would add
+browser validation to a *filter* input that was never submitted before.
+
+### `Select` 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.
+
+### `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.
+
+### `error` without `errorMessage` renders the literal word "Error" — and erases `helperText`
+
+Every field that shows validation errors (`TextInput`, `InputTextArea`, `Select`, `MultiSelect`,
+`SelectV2`, `SearchSelect`, `SelectSearch`, `Search`, `Checkbox`, the `DatePicker` variants,
+`PhoneNumberInput`) falls back to the literal word **"Error"** when `error` is `true` but
+`errorMessage` is empty. Worse, `helperText` only renders when `!error` — so the guidance
+disappears exactly when it's needed.
+
+**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="studio" {...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 = 'studio', ...props }: TableProps) => <Table variant={variant} {...props} />;
+```
+Applies to any library prop with a default value, not just `Table`'s `variant`.
+
+### `FormWrapper` has a closed prop list — no `...rest`
+
+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.
+
+**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.
+
+### `ContactForm`'s `apiKey` prop is a POST URL, not an auth token
+
+Despite the name, `apiKey` is passed straight into `fetch(apiKey, { method: "POST" })` as the submit
+endpoint — never sent as a header or credential. A real API key/secret fails silently as an invalid
+URL, surfaced only as a generic "Failed to send message" alert. There's no `headers` prop, so an
+authenticated endpoint can't be reached through this component at all.
+
+**Apply:** pass the full POST URL, never a token. If the endpoint needs auth headers, proxy through
+your own backend instead.
+
+### `ContactForm` can't tell its parent the submission result
+
+It does its own internal `fetch` and renders its own success/error alert from local state — there is
+no `onSuccess`, `onSubmit`, or `onError` prop (a dead `// onSubmit(formData)` line is the only trace
+one ever existed). A call site can't redirect, toast, or update its own state when the enquiry sends.
+Separately, the email field is validated for format but its "required" check is commented out, so a
+blank email submits successfully with no error shown.
+
+**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
+
+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.
+
+**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.
+
+### `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 is Chakra's raw `useToast`, not this library's
+`Toaster` — the same portal issue documented for `Toaster`/`Modal` can silently hide it when this
+form is embedded in a `Modal`.
+
+**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, 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."
+
+### `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
+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, and labels are the raw key
+
+A numeric field on an `Account` (allowed by its index signature) is never shown in the card's field
+list. The label is the key with only its first letter capitalised — `account_name` renders
+"Account_name", `nextFollowUp` renders "NextFollowUp"; nothing splits words.
+
+**Apply:** keep numeric display values as strings; use keys that read acceptably as-is.
+
+### `KanbanBoard`'s `onColumnDelete` receives the deleted column's **card** ids, not the column's id
+
+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` and the internal `Input.tsx` set native `required` (browser bubble, blocks submit).
+`TextInput` and `InputTextArea` set only `aria-required` — announced, but no native validation.
+`PhoneNumberInput` and `PinInput` pass it only to the label (draws a `*`); the field gets nothing.
+
+**Apply:** don't rely on `isRequired` for native form validation — validate required fields yourself
+regardless of which component you're using.
+
+### `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 })`.
+
+### 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
+`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.
+
+### `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.
+
+### `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`/
+`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 }}`.
+
+### `ProductCard`'s variant selection goes stale after an `options` update, and `options={[]}` crashes it
+
+Both `ProductCard` and its internal `ProductPrice` capture `options[0]` into state only once, at
+mount, with no resync effect — a later re-render with refreshed `options` (new stock/price) is
+silently ignored, so Add to Cart/Notify Me act on stale data. An empty array crashes on
+`selected.label`. Separately, `description` and `avalabilitys` are typed and accepted but never
+read by the component.
+
+**Apply:** treat `options` as effectively static per mount (remount via `key` if it changes), and
+never pass `[]`. Don't rely on `description`/`avalabilitys` — there's currently no way to show either.
+
+### `ProductTags` (shared by `ProductCard`/`ProductDetails`) silently renders zero tags past 4
+
+The row-layout helper only handles 1-4 entries — 5 or more tags renders nothing at all, no
+truncation or "+N more" affordance.
+
+**Apply:** cap `tags` at 4 entries at the call site until the component adds an overflow case.
+
+### `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.
+
+### `UpgradeButton`'s gold icon accent silently falls back to the label color on low contrast
+
+The gold accent is only used when it clears AA contrast against both gradient stops; a custom
+`gradient` prop can flip it to the label's own ink color with no signal.
+
+**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`.
+
+### `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`'s Jodit toolbar is fixed for screen readers and keyboard, from our wrapper only
+
+Jodit's own markup (`node_modules/jodit`) put `aria-label` on each button's `role="listitem"`
+wrapper instead of the real inner `<button>`, used the invalid ARIA role `"trigger"` for its
+dropdown-chevron spans, gave `listitem` no `role="list"` ancestor, and ships every toolbar button
+at `tabindex="-1"` unless `config.allowTabNavigation` is on — so by default the toolbar failed
+axe's `button-name`/`aria-roles`/`aria-required-parent` and was entirely unreachable by keyboard.
+`Editor` now sets `allowTabNavigation: true` by default (same override rule as `theme`/`popupRoot`
+above — a value you pass in `config` wins) and runs a `MutationObserver`-backed DOM pass
+(`joditAccessibility.ts`) that copies each button's real name onto it and fixes the two roles.
+
+**Apply:** nothing — this is automatic. Set `config.allowTabNavigation: false` only if you
+deliberately want the toolbar out of the tab order; you'll reintroduce the keyboard-reachability gap.
+
+### `SelectV2`, `SearchSelect`, and `SelectSearch` all search `option.label` only
+
+None of the three checks a rendered secondary field (`option.description`, a custom `view` node,
+`option.email` on a profile row) — typing text that's visibly on-screen in a secondary field returns
+no match.
+
+**Apply:** if a secondary field needs to be searchable, fold it into `option.label` yourself, or
+pre-filter `options` before passing them in.
+
+### `SearchSelect` never virtualizes
+
+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.
+
+### `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 accepted 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 —
+`FilterSection.checkboxes` doesn't exist either; 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` —
+none of them do anything.
+
+### `Breadcrumbs`' `isLastChild` prop is accepted but never read
+
+It's declared on the type but omitted from the component's destructure entirely.
+
+**Apply:** don't pass it expecting it to mark or style the final crumb — there's nothing it can do.
+
+### `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`'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 `photoUrl` is read once
+
+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, `photoUrl` only seeds state at mount — a later re-render with a new
+`photoUrl` (list virtualization, route change without remount) keeps showing the old photo.
+
+**Apply:** don't use the built-in edit flow for PDF documents; detect kind from `File.type` in your
+own handler instead. Use `key={photoUrl}` to force a remount when the photo identity changes.
+
+### `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.
+
+### `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.
+
+### `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
+these six. All six are now marked `@deprecated` in `TableProps.tsx` rather than removed outright, in
+case an app outside those five repos relies on one. None of these do anything in the current
+implementation, despite being typed on `TableProps` (and some documented on the demo page):
+
+- `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, despite `src/Pages/table.tsx` documenting them as if live.
+- `onColumnFilter` — commented out of `Table`'s own destructure (`// onColumnFilter`).
+- `headerBgColor` / `tableBorderColor` — also dead and `@deprecated`; the header paints the
+  variant's own background.
+
+**Apply:** don't reach for any of these expecting an effect. Column visibility is driven by
+`isTableSettings` (shows the Settings gear) + `preferences` (server persistence) + the Manage
+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.
+
+### `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`.
+
+### `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]` / `primary[500]`, hidden until hover.
+`FlexCss` is removed — `cssForScrollBar` is now the only scrollbar treatment the SideBar uses.
+
+**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.
+
+### `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.