pixelize-design-library 2.4.2-beta.4 → 2.4.2-beta.40

package/COMPONENT-GOTCHAS.md

@@ -0,0 +1,1087 @@
+# 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.
+
+---
+
+## 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.
+
+### Which "select" component — seven components overlap in name, not purpose
+
+**Not picking a value from an options list at all:**
+
+| Doing | Component | Why not the others |
+| --- | --- | --- |
+| Triggering a labelled *action* (export, row menu, "...") | `Dropdown` | A menu-button, not a form field — nothing is "selected" and persisted |
+| Typing free-text tags (e.g. email addresses), no options list | `MultiSelect` | Despite the name, there is nothing to pick from — see gotcha below |
+| Choosing which *fields/columns* to include, in a modal, from a checkbox grid | `FieldSelectModal` | Multi-checkbox selection UI, not an inline field control |
+
+**Picking one or more values from an options list, inline in a form:**
+
+| List length / need | Component | Why |
+| --- | --- | --- |
+| Short, always-visible list, no search needed | `Select` | Native `<select>` wrapper — lightest option, but the popup is OS-painted and can't be themed |
+| New build, want themed/custom-rendered rows (icons, descriptions), no huge list | `SelectV2` | Fully React-rendered popup — **prefer this for new work** over `Select` |
+| Long list needing search + chips + select-all + infinite scroll | `SearchSelect` | The full-featured picker; scales via consumer-driven `pagination`, not DOM virtualization — see gotcha below |
+| Search-as-you-type with avatars/colour swatches/a pinned "add new" row | `SelectSearch` | Lighter than `SearchSelect`; reach for it for that specific row-content need |
+
+Default when unsure: `SelectV2` for a themed field, `Select` if the native popup is genuinely fine.
+
+### `Slider` is an image carousel, not a numeric range input
+
+`Slider` auto-advances a set of images/content on a timer — no numeric value, min/max, or step. The
+actual range-input slider is Chakra's own, re-exported from the `Primitives` barrel as `RangeSlider`
+specifically because this library's `Slider` already owns the name.
+
+**Apply:** for a numeric/range form control, import `RangeSlider` from the `Primitives` barrel —
+never `Slider`.
+
+### Which "switch" — `ToggleSwitch` / `SegmentedControl` / `Switch`
+
+| Choosing | Component | Why |
+| --- | --- | --- |
+| A real on/off toggle | `ToggleSwitch` | `role="switch"` + `aria-checked`, full keyboard support |
+| One of 2-5 named options | `SegmentedControl` | `role="radiogroup"`, keyboard-navigable, supports per-option disabling |
+| — | `Switch` | Despite the name, a two-label segmented control (`leftText`/`rightText`) — no role, no keyboard handling at all (mouse-only). Kept only for backward compatibility; don't reach for it in new code |
+
+**Apply:** if the choice is "on vs off," it's never `Switch` — use `ToggleSwitch`. For 2+ named
+options, prefer `SegmentedControl` even over `Switch`.
+
+### 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>` hardcoded to Tailwind `bg-purple-600`, not theme-aware, not exported from the package root — see gotcha below |
+
+### Which "card" — `Card` / `ProductCard` / `ProductDetails` / `PaymentCard`
+
+| Need | Component | Why not the others |
+| --- | --- | --- |
+| Generic bordered/padded container, no commerce semantics | `Card` | Plain layout wrapper — its `header`/`footer`/divider props are dead, compose your own layout in `children` |
+| 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.
+
+### Inline file preview — `PdfViewer` vs `FilePreview`
+
+| Need | Component | Why |
+| --- | --- | --- |
+| Always-visible inline PDF panel in the page flow | `PdfViewer` | Non-modal, PDF-only, small open/download toolbar |
+| Click-to-open lightbox over mixed/unknown file types | `FilePreview` | Controlled modal; auto-detects image/pdf/video/other, adds zoom/rotate for images, graceful fallback for unsupported types |
+
+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.
+
+---
+
+## Known gotchas (silent failures)
+
+### `Drawer` / `Modal` / `ProfileCard` drop any child that isn't a named slot
+
+All three match children by exact type (`child.type === XHeader/XBody/XFooter`) and render only
+those matches — nothing else in `children` is ever read. Two consequences: a sibling among the
+slots (a nested `Modal`, `AlertDialog`, a confirm dialog, a portal after the footer) silently never
+mounts; and a slot wrapped in a `<>...</>` fragment is dropped too, because the matching doesn't
+unwrap fragments — a fragment's `.type` is `Fragment`, never the slot component.
+
+**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.
+
+### `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.
+
+### `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 `SearchSelect` with `isMultiple` to pick multiple values from an options list.
+
+### `RadioButton` has a closed prop list — no `...rest`, no `name`
+
+It forwards only a fixed set of props (`label`, `colorScheme`, `isChecked`, `onChange`,
+`isDisabled`, `size`, `value`, `defaultChecked`, plus label/tooltip props) to the underlying radio
+— a `data-*` hook, `aria-describedby`, or a `ref` cannot reach it.
+
+**Apply:** it still joins an external `RadioGroup` correctly (grouping comes from context, no
+`name` prop needed) — don't avoid it just for grouping. Reach for the library's Chakra escape
+hatch only when you need something outside that closed list.
+
+### `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.
+
+### `InputTextArea`'s `width` defaults to the number `500`, and no `id` means no label
+
+`width` defaults to `500`, forwarded straight through — `500` isn't a sizing-scale key, so it
+renders a literal `500px`, not a max and not responsive. It only shows up on a narrow screen.
+Separately, `id` feeds both the visible label and the field itself with no fallback — omit it and
+the label is associated with nothing; the field has no accessible name.
+
+**Apply:** pass `width="100%"` **and** `id` at every call site.
+
+### `error` without `errorMessage` renders the literal word "Error" — and erases `helperText`
+
+Every field that shows validation errors (`TextInput`, `InputTextArea`, `Select`, `MultiSelect`,
+`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`/`PinInputs` 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` / `ProgressBar` have closed prop lists — no `borderRadius`, no margin, no `...rest`
+
+Both `Pick<>` a fixed key set from their Chakra equivalents and forward nothing else — there is no
+way to round a skeleton's corners, add margin, or attach a ref/`data-*` through either component.
+
+**Apply:** for rounding, spacing, or a ref, use the Primitives barrel's raw Chakra `Skeleton`/
+`Progress` instead.
+
+### `Skeletons`' `isLoaded` only works for `type="skeleton"`
+
+`type="circle"`/`"text"` never receive `isLoaded` (or `children`/`bg`/`color`/`fadeDuration`) —
+passing them compiles and is silently dropped; the shimmer never stops no matter what `isLoaded` is
+set to.
+
+**Apply:** for `circle`/`text`, control visibility by conditionally rendering the `Skeletons` element
+itself, not via `isLoaded`.
+
+### `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 `error` never sets `isInvalid`, and `variant` is a no-op
+
+`error` doesn't set `isInvalid`/`aria-invalid`, and `errorMessage`/`helperText` aren't linked via
+`aria-describedby` — confirmed by three `it.failing` cases in `Checkbox.a11y.test.tsx`. Separately,
+`variant` is typed and accepted but never destructured or read; `Checkbox.styles.ts` defines no
+`variants` key, so no value changes anything.
+
+**Apply:** pass `isInvalid` explicitly alongside `error` — `error` alone never registers as invalid.
+Don't expect `variant` to change a `Checkbox`'s look.
+
+### `Toggle`/`TableToggle` has no `aria-pressed`, and its tooltip text can silently mismatch its `aria-label`
+
+Confirmed by three `it.failing` cases in `TableToggle.a11y.test.tsx` — a tooltip reading "Table View"
+on a button whose `aria-label` is "Grid View" is a real, reachable state, not a hypothetical.
+
+**Apply:** keep each button's tooltip text and `aria-label` in sync yourself; the component doesn't
+enforce or derive one from the other.
+
+### `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."
+
+### Any field's label silently renders as an unassociated `<span>` if you omit `id`
+
+`TextLabel` (the shared label engine behind nearly every field, see above) only renders a real
+`<label htmlFor>` when given an `id` — omit it and the visible label text renders but is never
+programmatically associated with its control, on any of the ~17 components that use it.
+
+**Apply:** always pass `id` when you want a real, accessible `<label>`. (`MultiSelect` omits it on
+purpose and wires `aria-label` instead — that's the pattern to copy if you skip `id` deliberately.)
+
+### `ErrorComponent`'s `error` prop is the message text itself — the opposite of `error`+`errorMessage`
+
+Every other field in the library pairs a boolean `error` with a string `errorMessage`.
+`ErrorComponent` (used internally by `Input`/`PinInputs`) instead takes `error: string` directly as
+the message, with no internal truthy-check — passing `error=""` still draws the full icon next to
+blank text. It also has no `id`, so unlike `ErrorMessage` it can't be wired to `aria-describedby`.
+
+**Apply:** treat `ErrorComponent` as `Input`/`PinInputs`-specific, not a general error row; guard it
+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 dead — only `timelineEvents` renders
+
+`events` is typed and accepted, reads as a plausible prop name, and is never used by the component.
+
+**Apply:** always use `timelineEvents`; treat `events`/the exported `TimelineEvent` type as vestigial.
+
+### `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, and its real props aren't in its exported type
+
+A drag that ends back at its starting index still has a drop target and still calls `onReorder` with
+a new array reference in the same order. Separately, the component supports `showRemoveIcon`/
+`onRemove` in practice, but the exported `ReorderListProps` type declares only
+`label`/`items`/`onReorder` — neither `ReorderListProps` nor `ReorderItem` is exported from
+`src/index.ts` at all, so there's no public named type to check either way.
+
+**Apply:** compare source/destination index (or diff the array) before persisting a reorder, if a
+no-op write matters. `showRemoveIcon`/`onRemove` do work — pass them despite the type gap.
+
+### `Divider` and `Trail`'s pieces aren't exported from the package at all
+
+Neither `src/Components/Divider/` nor `src/Components/Trail/` appears in `src/index.ts`, though both
+still compile into `dist/` and are deep-import-reachable. The library's own `Divider` is always
+vertical, fixed size/color, zero props — a different thing from the general-purpose (horizontal,
+styleable) `Divider` re-exported from the `Primitives` barrel. `Trail/TrailWorks` is a hardcoded
+2-row demo table, not a reusable grid.
+
+**Apply:** for a divider in a consuming app, use the `Divider` from `Primitives`, not this library's
+own. For a real data grid, use `Table` — nothing under `Trail/` is meant for reuse.
+
+### `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 mangles camelCase labels
+
+A numeric field on an `Account` (explicitly allowed by its index signature) is silently never shown
+in the card's field list. The auto-generated label only splits on `_` — a snake_case key
+(`account_name`) renders as "Account Name," but an idiomatic camelCase key (`nextFollowUp`)
+collapses into one mashed word ("Nextfollowup").
+
+**Apply:** use snake_case keys on `Account` objects, and keep numeric display values as strings.
+
+### `KanbanBoard`'s `onColumnDelete` receives the deleted column's **card** ids, not the column's id
+
+Despite the callback parameter being named `colId`-adjacent, what's actually passed is
+`columns[colId].items.map(item => item.id)` — the cards that were in the column, never the column's
+own id.
+
+**Apply:** track which column was being deleted another way (e.g. hover/selection state captured
+before the click) if you need the column id itself.
+
+### `isRequired` is decorative on some fields, native on others — same prop name, different behavior
+
+`TextInput`, `PhoneNumberInput`, and the exported `PinInput` pass `isRequired` only to the label
+(draws a `*`) — the field itself never gets `required`/`aria-required` (confirmed by an `it.failing`
+case in `TextInput.a11y.test.tsx`). `NumberInput` and the internal `Input.tsx` do propagate it
+natively. A form relying on `isRequired` for native HTML5/AT validation works on some fields and
+silently doesn't on others.
+
+**Apply:** don't rely on `isRequired` for native form validation — validate required fields yourself
+regardless of which component you're using.
+
+### `PhoneNumberInput` and `NoteTextArea` type a `ref` prop that never attaches
+
+Both are plain function components, not `forwardRef` — a `ref` passed to a plain function component
+is stripped before the body runs, so the destructured ref param is always `undefined`.
+`NoteTextArea` compounds this: even where it does forward a ref, it only reaches the secondary title
+input, never the primary `Textarea`.
+
+**Apply:** don't rely on a `ref` into either component; `NumberInput`/`InputTextArea` forward refs
+correctly if you need that pattern.
+
+### `NoteTextArea`'s `saveButtonLoading` going `true → false` clears the draft even on a failed save
+
+The effect that resets note/title/files fires whenever `saveButtonLoading` goes falsy — there's no
+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).
+
+### `PinInput` and `PinInputs` are two unrelated implementations — only one is real
+
+The component published as `PinInput` from `index.ts` is Chakra-native, themed, supports OTP paste
+and `type: "alphanumeric" | "number"`. `PinInputs` (plural) is a separate, hand-rolled,
+always-numeric implementation that is **not exported** and not referenced anywhere else in the repo
+— a dead-code candidate, not an alternate API. It still compiles into `dist/`, so the deep-import
+pattern this repo otherwise supports would silently pull in the unmaintained one.
+
+**Apply:** always use `PinInput` (singular); never deep-import `PinInputs`.
+
+### `InputSwitch`'s checked/unchecked track color is silently replaced by a caller-supplied `sx`
+
+The component's own `sx` (sets track background from `isChecked`) is spread over first, then
+`{...props}` — any `sx` a caller passes wins outright, so the switch stops changing color on toggle.
+
+**Apply:** don't pass `sx` to override styling on `InputSwitch`; if you must, re-include the
+checked/unchecked background logic yourself.
+
+### `TextInput`'s `placeholder` defaults to the literal word `"Placeholder"`, not empty
+
+Omit the prop and real users see the actual text "Placeholder" in the field.
+
+**Apply:** always pass an explicit `placeholder` (or an empty string) at every `TextInput` call site.
+
+### 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 (`Pick`ed from Chakra's `AlertProps`) but never destructured — Cancel/Confirm are hardcoded
+red/primary at `size="sm"` regardless of what you pass.
+
+**Apply:** style Cancel/Confirm via `button1Style`/`button2Style`, not `colorScheme`/`size`/`status`/
+`variant`.
+
+### `AlertDialog` can always be dismissed via Escape or an overlay click, not just its buttons
+
+`closeOnOverlayClick`/`closeOnEsc` aren't exposed as props, so Chakra's `true`/`true` defaults apply
+unconditionally — `onClose` fires the same way for Escape/overlay-click as for the Cancel button.
+
+**Apply:** don't treat `onClose` as "the user explicitly chose Cancel" — that distinction isn't
+available through this component.
+
+### `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` type-checks (Picked from Chakra's `ToastProps`) but is never read — only `title`/
+`description`/`actions` render. Separately, the `onClose` you pass to `showToast` is wired to
+Chakra's `onCloseComplete` (fires after the exit animation, on any dismiss path); the `onClose` your
+`actions` render-prop receives is a different, immediate per-toast dismiss function.
+
+**Apply:** pass `description`, not `children`. Don't assume your `onClose` fires the instant the
+user clicks close — it fires after the exit transition completes.
+
+### Every `Toaster` status announces at `aria-live="polite"`, including `error`
+
+No urgency bump for errors, and status is conveyed by icon + colour alone with no text equivalent —
+confirmed by two intentionally-`it.failing` tests in `Toaster.a11y.test.tsx`.
+
+**Apply:** don't rely on an error toast interrupting a screen reader; pair a critical failure with
+another signal (e.g. an inline field error).
+
+### `Button`'s `loadingText` defaults to `"Loading"`, not Chakra's spinner-only style
+
+`loadingText` defaults to the literal string `"Loading"`, so every `isLoading` button shows that
+text next to the spinner instead of Chakra's native behavior (hide content, spinner only) — even
+icon-only buttons, where it can break the expected square aspect ratio. Passing
+`loadingText={undefined}` does not restore the native look; the default parameter still applies.
+
+**Apply:** pass `loadingText=""` explicitly to get a spinner-only loading state.
+
+### `ButtonGroupIcon`'s dropdown needs `rightIcon` **and** `rightIconDropdown` both set
+
+The `Menu`/`dropdownOptions` branch only renders inside `rightIcon && rightIconDropdown`. Supplying
+`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, and not theme-aware
+
+Despite the plural name suggesting a group, `Buttons` renders one plain `<button>` hardcoded to
+Tailwind's `bg-purple-600` — it ignores brand/dark-mode entirely and isn't exported from the package
+root.
+
+**Apply:** use `Button` for a single themed button or `ButtonGroupIcon` for a themed group; there is
+no good reason to reach for `Buttons`.
+
+### `Card` silently drops `header`, `footer`, and all three divider props
+
+`CardProps` declares `header`, `footer`, `dividercolor`, `dividersize`, `dividervariant`, but none
+are destructured by `Card` — passing them compiles cleanly and renders nothing. Padding is also
+hardcoded (`p={4}`), so it can't be tuned via props either.
+
+**Apply:** put header/footer content inside `children`; use `sx` for padding overrides.
+
+### `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`.
+
+### `FileUpload`'s default `maxSizeKB` is 5 — that's 5 **kilobytes**, not megabytes
+
+Left at its default, `FileUpload` rejects virtually every real file, and the auto-generated
+hint/error text literally reads "0.00 MB" because the KB→MB conversion divides an already-tiny value.
+
+**Apply:** always pass an explicit `maxSizeKB` in KB (e.g. `5000` for ~5MB).
+
+### `DatePicker`'s `pickerType` does nothing when `isRange` is set, and no variant has a seconds control
+
+`RangeDatePicker` never reads `pickerType` — whether time inputs show is controlled entirely by
+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.
+
+### `RangeDatePicker` loses a picked range if you click outside instead of Apply
+
+Unlike `SingleDatePicker`, its outside-click handler doesn't call `finalize()` — only the Apply
+button or Escape commits a completed range via `onChange`. Clicking anywhere else outside the
+popover after picking both ends discards the selection silently.
+
+**Apply:** don't assume outside-click commits a range the way it does for `SingleDatePicker`.
+
+### `TimeOnlyPicker`'s label is never associated with its field, and `name` is a no-op
+
+Passing `id`/`label` does not produce an accessible `<label for>` — the internal label call omits
+`id`, so it always renders as an unassociated `<span>`. `name` (and `minDate`/`maxDate`/
+`disableFutureDates`/`disablePastDates`/`autoComplete`) are also silently dropped — the rendered
+`<input>` never gets a `name` attribute, breaking plain `<form>`/`FormData` submission.
+
+**Apply:** don't rely on `TimeOnlyPicker` for native form submission or label accessibility; read its
+value via `onChange` rather than form `name`.
+
+### `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.
+
+### `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, and `chip.maxChips={0}` is swallowed by a falsy fallback
+
+Despite the prop name, `virtualization` does nothing — every filtered option renders as a real DOM
+node; the list scales only via consumer-driven `pagination`. Separately,
+`selectedValues.slice(0, chip?.maxChips || selectedValues.length)` treats a literal `0` as "no limit
+set" (falsy), so every chip renders anyway instead of zero.
+
+**Apply:** for a dataset large enough to need real virtualization, page it in via `pagination` rather
+than setting `virtualization={true}`. Pass `1` or higher to `chip.maxChips`; there's no supported way
+to hide all chips via this prop.
+
+### `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`.
+
+### `Search`'s default `shortcut` grabs a page-global Ctrl+K with no way to opt out
+
+Every mounted `Search` registers its own `window` Ctrl+K listener by default — the type only permits
+the literal `"Ctrl+K"` or `undefined`, and `undefined` still resolves to the same default via JS
+parameter defaulting. Two instances on one visible view race for the keypress.
+
+**Apply:** avoid mounting more than one `Search` per visible view/route — there's currently no way to
+scope or disable the hotkey per-instance.
+
+### `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`/`itemProps` replace, not merge, the expanded/hover highlight
+
+Both spread after the built-in `bg`/`_hover` that encode `isExpanded` state — passing `bg` or
+`_hover` there to tweak one item's style silently kills that item's expanded/active indication.
+
+**Apply:** style around the defaults via `customStyles` (merged through `sx`) rather than
+`buttonProps`/`itemProps` 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
+
+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`).
+
+**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.limit` also drives a "has more" guess, not just page size
+
+`hasMore` is computed as `options.length % pagination.limit === 0` — there is no real end-of-data
+signal from the consumer. A total result count that happens to be an exact multiple of `limit`
+looks indistinguishable from "more pages exist," firing one extra, empty `onScroll` call.
+
+**Apply:** if exact pagination boundaries matter, pad or report a real "no more results" state some
+other way; don't rely on `hasMore` being accurate at a page boundary.
+
+### `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
+
+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.
+
+**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
+
+`SidebarProps.selectedSubMenu` is threaded through `SideBar` → `MenuItems` → `MenuItemBox`, but the
+component's destructure never includes it — passing it has no effect of any kind.
+
+**Apply:** don't pass `selectedSubMenu` expecting it to highlight a submenu row.
+
+### `SideBar`'s `locked` menu-item flag doesn't lock anything
+
+`MenuProps.locked` only swaps the trailing badge/chevron for a lock icon. The click handler checks
+only `disabled` — a `locked: true, disabled: false` item still fully navigates/expands.
+
+**Apply:** set `disabled: true` alongside `locked: true` to actually prevent interaction.
+
+### `KanbanBoard`'s `kanbanSelect` ignores `permissions`, unlike `kanbanEdit`/`kanbanCreate`
+
+`kanbanEdit`/`kanbanCreate` are only forwarded when `permissions.isEditable`/`isCreatable` allow it;
+`kanbanSelect` is passed through unconditionally regardless of `permissions`. `onOpen` similarly has
+no permission gate at all, asymmetric with the gated `onDelete`.
+
+**Apply:** gate `kanbanSelect.isSelect` (and any `onOpen` affordance) yourself if they should also be
+permission-locked.
+
+### `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.