pixelize-design-library 2.3.22 → 2.4.1-beta.2

package/.cursor/modules/data-display/MODULE.md

@@ -0,0 +1,42 @@
+# Data Display
+
+## Purpose
+
+Tag, Timeline, Reorder, Divider, Trail.
+
+## Key paths
+
+- `src/Components/Tag/` — `Tag.tsx`, `TagProps.ts`, `Tag.styles.tsx` (registered in `Theme/componentStyles.ts`)
+- `Timeline/`, `Reorder/`, `Divider/`, `Trail/`
+- Demo: `src/Pages/tag.tsx`
+
+## Key rules
+
+- Timeline: each event card renders its manual notes from `event.notes` (`TimelineNote[]` — `log_note_id`, `title`, `note`, `attachments[]`, `created_by`, `created_at`). Adding a note is event-scoped via the per-card "Add note" button → `onAddNote(note, title, files, event, index)`; the consumer persists it against `event.logs_id` and re-supplies it back in `event.notes`. Attachments show as links opening `attachment.url`.
+- Timeline notes support edit + delete: hovering a note shows edit/delete icons → `onEditNote(logNoteId, note, title, files, event, index)` (inline `NoteTextArea`) and `onDeleteNote(logNoteId, event, index)` (consumer owns any confirm dialog). Loading props: `addNoteLoading`/`editNoteLoading` keep the editor open with a Save spinner until the request resolves (then auto-close); `deletingNoteId` shows a spinner on the note being deleted. With no loading props wired, the add editor closes immediately on submit (back-compat).
+- Trail includes editable cell demos
+- Tag styling lives in `Tag.styles.tsx` (Chakra component theme), not hardcoded in `Tag.tsx`
+- Tag sizes: `xs | sm | md | lg`; variants: `solid | outline | subtle`
+- Tag colors are token-driven from the active theme via `colorScheme` (brand `primary/secondary/tertiary` + global scales); palette resolution falls back to `gray` so a missing scale never throws
+- Tag `solid` variant label color is now `onFilled(fill, white, black)` (per state: base/hover/active), not a hardcoded `white` — picks whichever of white/black clears WCAG AA against that swatch, so it stays readable on light brand fills too
+
+## WCAG / dark-mode pass (this session)
+
+- **Tag.styles.tsx** — `solid` variant's foreground swapped from hardcoded `theme.colors?.white` to
+  `onFilled(fill, white, black)`, computed per bg (base `500`, hover `600`, active `700`); verified
+  against WCAG AA.
+- **Trail/EditableCell.tsx** — `priority` menu's `MenuButton` had a real hover-contrast fix: `bg`
+  `teal.500`/`color white` → `bg="teal.50"` / `color="teal.900"` (+ hover/active states). **Known
+  gap:** this uses raw Chakra `teal.*` literals, not `useCustomTheme()` tokens, so it won't track
+  brand hue or dark mode — needs a follow-up token pass.
+  - **Known gap (not fixed this pass):** the same `MenuList`/`MenuItem` still has no `bg=`/
+    `sx={{ "--menu-bg": ... }}` override, so Chakra's `--menu-bg` CSS var still resolves to its
+    hardcoded light-mode white regardless of this app's active dark mode — same root-cause bug
+    already fixed this session in `ButtonGroupIcon` (buttons module) and `NavigationBar`
+    (layout-navigation module). Deliberately deferred, not overlooked.
+
+## Dark mode
+
+- Timeline takes every color from `useCustomTheme()`, so it follows whichever palette the theme carries. Dark works by swapping the palette — there is no `_dark`/`semanticTokens` layer, so a hardcoded value would stay light forever.
+- White surfaces use `colors.background[50]`, **not** `colors.white` — `white` is a *foreground* token (label on a filled button) and stays white in dark. Covers Timeline's event card, date chip, and the node ring that punches each node out of the spine. (Timeline's inline `NoteTextArea` is owned by `inputs-basic`.)
+- Timeline's remaining `?? "#fff"` fallbacks are defensive only — every brand palette defines `background[50]` (dark included, derived by `buildDarkPalette`).

package/.cursor/modules/feedback/MODULE.md

@@ -0,0 +1,38 @@
+# Feedback
+
+## Purpose
+
+Loading, Skeletons, ProgressBar, Notification, FeedbackForm.
+
+## Key paths
+
+- `src/Components/Loading/`, `Skeletons/`, `ProgressBar/`, `Notification/`, `FeedbackForm/`
+- `src/services/feedback.ts`
+
+## Key rules
+
+- FeedbackForm may POST to account API in consumer apps — keep props generic
+
+## Dark mode
+
+- **Skeleton** (`Components/Skeletons/`) — Chakra's own baseStyle hardcodes
+  `--skeleton-start-color`/`--skeleton-end-color` to `gray.100`/`gray.400` behind `_dark`, same
+  never-triggered gate as Modal/Menu (theme module). Fixed centrally in `componentStyles.ts`
+  (`Skeleton` entry, rungs `gray[100]`/`gray[300]`) rather than in `Skeletons.tsx` — a
+  caller-supplied `startColor`/`endColor` prop still wins exactly as before; this only supplies
+  the default the base style already owns.
+- **Notification**: default `bgColor` switched `theme.colors.white` → `theme.colors.background[50]`
+  — `white` is a foreground token (label ink, stays white in dark) and was being used as the card
+  surface; `background[50]` is the correct dark-mode-aware white-surface token. Real bug fix (was
+  forcing a white card in dark mode), not a plain refactor. Consumers passing `colors.bgColor`
+  explicitly are unaffected.
+- **`warningColor`/`errorColor`/`successColor` object-vs-string bug (QA-adjacent, real correctness
+  bug, not WCAG):** `NotificationProps` types these as hex strings, but the defaults were an
+  un-indexed whole `ColorScale` object (`theme.colors.semantic.warning` instead of
+  `theme.colors.semantic.warning[500]`) — Chakra silently can't render an object as a `bg=` color,
+  so the default (no-override) case was broken. Fixed by indexing `[500]` on all three defaults.
+- **Time-elapsed icon/label AA gap:** the "time ago" `Icon`/`Text` defaulted to `orange.400`/
+  `orange.500`, which fail AA (~1.9–2.2:1) against `bgColor` in every brand — same class of bug as
+  the `error`/`red[500]` gap (theme module). Fixed by routing both through
+  `accentTextOnCanvas(theme.colors.orange, bgColor)` (`Theme/tokens/builders/accentText`) instead
+  of a fixed rung.

package/.cursor/modules/form/MODULE.md

@@ -0,0 +1,13 @@
+# Form
+
+## Purpose
+
+FormWrapper — shared form layout wrapper for entity forms in CRM apps.
+
+## Key paths
+
+- `src/Components/Form/FormWrapper`
+
+## Key rules
+
+- Used with smart forms in crm-frontend; keep generic props

package/.cursor/modules/inputs-basic/MODULE.md

@@ -0,0 +1,42 @@
+# Basic Inputs
+
+## Purpose
+
+TextInput, PhoneNumberInput, InputTextArea, NoteTextArea, NumberInput, PinInput, PinInputs.
+
+## Key paths
+
+- `src/Components/Input/`, `InputTextArea/`, `NoteTextArea/`, `NumberInput/`, `PinInput/`, `PinInputs/`
+
+## Key rules
+
+- InputSwitch in `Input/Switch/`
+
+## Dark mode
+
+- No hex literals remain — every field follows the active palette, but by three paths, not one:
+  `useCustomTheme()` (TextInput, PhoneNumberInput, NoteTextArea, PinInput, InputSwitch), Chakra
+  `useTheme()` (Input/Input, PinInputs), and `componentStyles` `({ theme })` fns (InputTextArea,
+  NumberInput — no theme hook at all). The `?? "gray.300"` fallbacks in `*.styles.ts` are token
+  refs, not literals: `createBrandTheme` sets `colors: palette`, so they resolve against the
+  swapped palette.
+- `NoteTextArea` was the only migration here: its 4 white surfaces moved `colors.white` →
+  `colors.background[50]`. `colors.white` is a **foreground** token (a label on a filled button)
+  and stays white in dark; a white *surface* needs `background[50]` (identical `#ffffff` in light).
+- `InputSwitch` layers `useColorModeValue` over the palette swap — it picks a different *rung*
+  (`primary[500]`→`[300]`, `gray[300]`→`[600]`) of the already-dark palette, not a second palette.
+
+## Border contrast bump ([500]/[700] → [800])
+
+- Follow-up fix: `boxborder` at `[500]`/`[700]` only cleared canvas-level surfaces (main/base)
+  and failed WCAG 1.4.11 (control boundary, >=3.0) against `muted`, the lightest named surface
+  (2.41-2.72). All seven fields — `Input/Input.tsx`, `TextInput.styles.ts`,
+  `InputTextArea.style.tsx`, `NumberInput.styles.ts`, `PinInput.tsx`, `PinInputs.tsx`,
+  `NoteTextArea.tsx` — now use `boxborder?.[800]` for the resting/default border, clearing all
+  12 named surfaces (3.44-3.90) in both modes.
+- `Input/Input.tsx` also swapped its label/accent color from `colors.secondary?.[500]` to
+  `accentTextOnCanvas(colors.secondary, colors.backgroundColor?.main)` — relies on the shared
+  `accentText.ts` guard (Theme module) for safety when rendered without a full Pixelize theme;
+  no separate fix was needed in this file.
+- `Input/Input.tsx` is **not** exported from `src/index.ts` (internal, used only by
+  `src/Pages/TInput.tsx`) — low external impact.

package/.cursor/modules/inputs-date-file/MODULE.md

@@ -0,0 +1,67 @@
+# Date & Files
+
+## Purpose
+
+ThemeDatePicker (Single/Range/Time variants), FileUpload, FileUploader, Editor (jodit-react).
+
+## Key paths
+
+- `src/Components/DatePicker/` — `ThemeDatePicker.tsx` (public entry), `SingleDatePicker.tsx`, `RangeDatePicker.tsx`, `TimePicker.tsx`, `TimeOnlyPicker.tsx`, `CalendarPanel.tsx`
+- `src/Components/FileUpload/`, `FileUploader/`, `Editor/`
+
+## Key rules
+
+- DatePicker themed for brand tokens — `CalendarPanel` reads every color from `useCustomTheme()` (no hex literals), so it follows the active light/dark palette automatically.
+- The month/year `<select>` uses `colors.background[50]`, not `colors.white`: it is a white *surface* and must darken in dark mode.
+- **Selected-day circle WCAG contrast (user-reported, fixed) — supersedes prior guidance below.** The filled day circle (selected / range start / range end) hardcoded `colors.white` text on `primary[500]`/`[600]` regardless of brand — the same class of gap `Button.styles.ts`'s solid variant already accounts for (white doesn't reliably clear AA against every brand's `[500]`, e.g. emerald/rosewood in dark, ~3.38/3.46). A previous pass here called this hardcoded white "correctly a foreground token, don't fix it" — that was wrong for the fill-contrast case specifically; foreground-vs-surface only tells you whether a token *inverts with mode*, not whether it *clears contrast against the fill it sits on*. Fixed via `onFilled(fill, theme.colors.white, theme.colors.black)` (`Theme/tokens/builders/accentText`) for both resting (`primary[500]`) and hover (`primary[600]`) fills.
+- **Calendar/time popover surface bug (user-reported, blocking):** `SingleDatePicker.tsx`, `RangeDatePicker.tsx`, `TimeOnlyPicker.tsx`, and the legacy `DatePicker.tsx` (still reachable — consumed directly by `Table/filters/LeftFilterPane.tsx`, not just via the unused commented-out playground import) each rendered a `PopoverContent` with no explicit `bg=` — the same Chakra-hardcoded-`colors.white`-behind-`_dark` bug as `Modal`/`AlertDialog`/`Drawer` (overlays module). Because `CalendarPanel`'s day/weekday text (`text[700]`/`gray[400]`/`gray[500]`) is computed against the *intended* dark canvas, the panel rendered on Chakra's un-migrated white default while its text was tuned for a dark background — producing exactly the washed-out, near-invisible day numbers reported. Fixed with `bg={theme.colors.background[50]}` on all four `PopoverContent`s (`TimeOnlyPicker.tsx` didn't previously call `useCustomTheme()` at all — added the hook). Verified live via Playwright across all four variants (date-only, date+time, range, time-only).
+- **FileUploader (QA-caught)** — its file-count and "Click here" text hardcoded `color="blue.500"`/
+  `"blue.400"`, which fail AA against the component's canvas (same class as the Notification
+  orange gap). Fixed via `accentTextOnCanvas(colors.blue, colors.backgroundColor?.main ?? "#ffffff")`
+  (`Theme/tokens/builders/accentText`), reused for both spots. Rest of the component (drag/drop
+  chrome, file-row chips) is still Chakra scale literals (`gray.*`), not migrated to
+  `useCustomTheme()` — out of scope for this pass since those are already dark-aware Chakra
+  literals (see table/account-management MODULE.md for why plain `gray.*` literals already track
+  the swapped palette).
+- Editor is now theme-aware: it reads `theme.colors.backgroundColor?.main` (with a `"#ffffff"` fallback added after a code-review-caught crash risk) via `isDarkCanvas()` to switch Jodit's own internal `dark`/`default` editor theme — it does not restyle Jodit itself, just picks which built-in Jodit theme renders. FileUpload does use theme (`useCustomTheme()`: `gray`, `red`, `blue`, `background`, `secondary.opacity`) but was not migrated — **known gap**: `FileUpload.tsx:153` paints the uploaded-file row `bg={colors?.white}`, a *surface* on the foreground token, so it stays white in dark mode; should be `background[50]`.
+- **Editor dark-mode "not black" bug (user-reported, fixed):** toggling Jodit's `config.theme` between `"dark"`/`"default"` only switches which of Jodit's OWN CSS selectors apply (`.jodit_theme_dark`, 180+ occurrences in `jodit.css`) — those selectors are still driven by Jodit's own hardcoded CSS custom properties (`--jd-dark-background-color: #575757`, a mid-gray, not black; `--jd-color-border-selected: #1e88e5`, generic blue), never fed this library's palette. Fixed in `Editor.tsx` by wrapping `<JoditEditor>` in a `<Box sx={...}>` carrying `getJoditThemeVars(theme.colors, isDark)` (`joditThemeVars.ts`) — inline CSS custom properties, scoped to this instance only (no `:root` leak onto other Jodit instances). Mapping: canvas/toolbar → `backgroundColor.main`/`.secondary`, ink → `text[900]`, icons → `text[700]`, hover/select-bg → `backgroundColor.muted`, border → `boxborder[500]`, accent → `primary[500]` — reusing the SAME role-stable tokens in both modes (`background[50]`/`text[900]` etc. already flip lightness internally per `buildDarkPalette.ts`, so no per-mode branching on VALUES, only on the `--jd-color-*` vs `--jd-dark-*` variable NAMES Jodit's default vs dark theme actually reads). Verified via Playwright: before showed `rgb(87,87,87)` (`#575757`, Jodit's default) on the canvas/toolbar in dark mode; after shows the brand's real near-black surface. Regression tests: `joditThemeVars.test.ts` (contrast + non-default-value assertions, lavender + rosewood).
+- **Editor popup/dialog portal gap (user-reported follow-up on the fix above, fixed):** the "Known gap" this section used to note — Jodit appends dialogs and toolbar-dropdown popups (search & replace, image/link properties, font-size list, paragraph format, …) directly to `document.body` (`Dialog.destination` / `getPopupViewRoot` in jodit core), outside the CSS-variable wrapper's DOM subtree, so they kept rendering in Jodit's default (light, unthemed) styling even in dark mode — was reported again as "hovering [in the] editor is not following WCAG standards." Traced via `node_modules/jodit/es2021/jodit.css`: the main toolbar's own `:hover` rule (`.jodit_theme_dark .jodit-toolbar-button:hover`) already clears AA/AA-non-text comfortably once `--jd-dark-background-color`/`--jd-dark-icon-color` are mapped (verified numerically — computed contrast ~10:1+ across all 8 brands, not touched), so the actual gap was specifically the portalled popups never inheriting `themeVars` at all. Fixed by wiring Jodit's own `config.popupRoot` (a supported, documented option — `node_modules/jodit/esm/config.d.ts`: `popupRoot: Nullable<HTMLElement>`) to the wrapper `<Box>`'s own DOM node via a callback ref (`useState<HTMLElement | null>` + `ref={setPopupRoot}` on the `Box`), so `Dialog.destination` resolves to the themed wrapper instead of `document.body` and every popup/dialog now inherits the same CSS custom properties as the toolbar/canvas. Regression test: `Editor.test.tsx` (mocks `jodit-react` to assert `config.popupRoot` is a real DOM node, not `null`/`document.body`). One TS gotcha hit while wiring this: adding a literal `popupRoot` key alongside `...config` (typed `DeepPartial<Config>`, Jodit's huge recursive config type) triggered `TS2589: Type instantiation is excessively deep` — worked around by spreading `config` as `Record<string, unknown>` before the final `as EditorProps["config"]` assertion, since the plain literal-plus-spread pattern is otherwise unaffected (see comment in `Editor.tsx`).
+- **Editor dialog inputs/search-panel/button-hover still unthemed (QA follow-up round, fixed):** the
+  `popupRoot` fix above got popups into the themed DOM subtree, but 3 more Jodit CSS variables were
+  still unmapped: `--jd-color-panel` (search & replace box background — only set in the light
+  branch, so dark mode fell to Jodit's own `#f9f9f9`, a near-white panel), `--jd-color-white` /
+  `--jd-color-gray` (`.jodit-ui-input__input` / `.jodit-ui-select__input` background — Jodit's own
+  raw white default, unmapped in either mode; `-gray` is what the `_theme_dark`-suffixed variant
+  reads instead of `-white`, and dialogs don't reliably get that modifier class). Traced each via
+  `node_modules/jodit/es2021/jodit.css` line-by-line before touching anything. Also found (via a
+  throwaway jest contrast computation, not assumed): the toolbar/dialog-button hover fill and the
+  `.jodit-select`/`.jodit-input` background both already mapped to `--jd-dark-background-ligher:
+  colors.backgroundColor.muted` — computed at ~1.3:1 against the canvas, a near-miss that had
+  actually shipped (both values sit within ~11 lightness points of each other down near L7-18, where
+  WCAG contrast collapses non-linearly) — this was the QA-reported "Insert button illegible on
+  hover." Fixed in `joditThemeVars.ts`: `--jd-color-panel` moved into `shared` (role-stable, same
+  `backgroundColor.secondary` expression already correct for light); `--jd-color-white:
+  background[50]` added to `shared`; `--jd-color-gray: background[50]` added to the dark branch;
+  `--jd-dark-background-ligher` changed to `background[900]` (this palette's dark-mode "bright
+  highlight" rung, ~9.7-10.7:1 against the canvas across brands — verified before applying, not
+  guessed). Confirmed via `node_modules/jodit/es2021/jodit.css` that `.jodit_theme_dark` /
+  `.jodit-dialog_theme_dark` already hardcode `--jd-color-border: #6b6b6b` themselves (a Jodit-owned
+  override we can't/don't need to touch), so this fix only had to cover panel/input backgrounds and
+  the hover fill. Regression tests added to `joditThemeVars.test.ts`.
+- **Date/time input control-boundary + surface pass (this session):** `SingleDatePicker`'s text
+  input, `TimePicker`'s hour/minute/AM-PM `<Select>`s, and `TimePickerInput`'s input all gained an
+  explicit `bg={theme.colors.gray?.[50]}` (was inheriting the ambient/transparent default) and
+  `borderColor={theme.colors.boxborder?.[800]}` (was `undefined`/unset outside the error state) —
+  same WCAG 1.4.11 control-boundary standard already applied to `MultiSelect`/`Select.styles`/
+  `SelectSearch` (see `inputs-select` MODULE.md). Hover now also resolves to
+  `theme.colors.primary[500]` (was `undefined`, i.e. no hover feedback at all) to match the
+  existing `_focus` treatment. `TimeOnlyPicker`'s footer divider `borderColor` switched from the
+  raw Chakra literal `gray.200` to the token `theme.colors.boxborder?.[300]`. `TimePicker` didn't
+  previously call `useCustomTheme()` — added the hook.
+- Masked-input blur must not discard a valid value. `isMaskComplete()` only recognises numeric/`a` tokens, so text month formats (e.g. `MMM d, yyyy`) never look "complete" — `handleInputBlur`/`handleInputFocus` therefore keep any value that `parseValidatedValue()` can parse to a valid date, and only `requestClose(null)` (clear) on empty/unparseable input. The Clear button and emptied-mask paths remain the explicit ways to clear. Regression: `SingleDatePicker.blur.test.tsx`.
+
+## Migration notes
+
+- DatePicker public export moved: `DatePicker/DatePicker` → `DatePicker/ThemeDatePicker` (exported as `DatePicker` from `src/index.ts`)
+- Split into Single/Range/Time picker variants under the same folder
+- Picker tests build their Chakra theme from `Theme/tokens/brands/lavender/palette.light` (was `Theme/Default/palette`)

package/.cursor/modules/inputs-select/MODULE.md

@@ -0,0 +1,89 @@
+# Select & Search
+
+## Purpose
+
+Select, SelectV2, SearchSelect, SelectSearch, MultiSelect, Dropdown, Search.
+
+## Key paths
+
+- `src/Components/Select/`, `SelectV2/`, `SearchSelect/`, `SelectSearch/`, `MultiSelect/`, `Dropdown/`, `Search/`
+
+## Key rules
+
+- SearchSelect has performance tests; virtualize for large lists
+- Dropdown and SearchSelect main options menu are portaled to `<body>` (`position: fixed`) and clamp to the viewport — right-align/flip above when near edges
+- `insideSelect` prefix: mutually exclusive with main dropdown; menu uses `position: fixed`, flips above/below based on viewport space, and re-anchors on scroll/resize; supports `placeholder` when no value
+
+## Dark mode
+
+SearchSelect and SelectSearch source every color from `useCustomTheme()` or a palette-backed Chakra scale literal — no hex in source — so they follow the active light/dark palette.
+
+- Menu/panel surfaces use `colors.background[50]`, never `colors.white` — `white` is a foreground token (label on a filled button) and stays white in dark. The portaled menus are no exception: a portal escapes the DOM, not the theme
+- Chakra scale literals (`gray.300`) are palette-backed — the Chakra theme's `colors` *is* the palette — but the literal `bg="white"` hits the same foreground-token trap as `colors.white`
+- Lucide icons default to `currentColor` (a bare `<ChevronDown />` inherits the wrapper's `color`), but an explicit `color` prop is a raw CSS string — a scale name like `"gray.500"` won't resolve there; pass a token value
+- Known gap: SearchSelect's "Remove All" X passes `colors.black`, which is untouched in dark, on a `gray[50]` control (L10 in dark) — near-invisible; needs a text token
+- Control borders (`MultiSelect`, `Select.styles`, `SelectSearch`) bumped `boxborder` step [500]/[700] to **[800]**: WCAG 1.4.11 needs a 3:1 contrast ratio against any named surface up to `muted` (lightest) — [500]/[700] failed there, [800] clears all with margin (see inline comments at each call site)
+- Known behavior change: SearchSelect's inside-select placeholder text dropped the `theme.colors.placeholder?.[500] ?? theme.colors.gray[500]` fallback for a flat `theme.colors.gray[500]` — still a valid token, but only the lavender brand defines a distinct `placeholder` scale (other brands inherit it via spread), so lavender's placeholder text loses its tint and now renders plain gray
+- SearchSelect's "Remove All" tooltip dropped its explicit `bg`/`color` overrides, now rendering with ToolTip's own default styling instead of a forced `gray[600]`/`white`
+
+## SelectV2 — custom-popup dropdown (additive, new)
+
+**Why it exists:** the existing `Select` (`src/Components/Select/`) wraps Chakra's `<Select>`, which
+renders a **real native `<select>`/`<option>`** — the closed field is themeable, but the open dropdown
+popup is painted by the browser's own UA stylesheet, not React. That means it can never get custom
+option rendering, hover states beyond OS defaults, or type-ahead filtering — the popup is architecturally
+outside Chakra/React's control (same class of gap as the native `color-scheme` bug documented in the
+theme MODULE.md, Wave H). `SelectV2` is a MUI-style alternative: a fully React-rendered popup, so every
+visual state (hover, selected, focus, disabled) is themeable via `useCustomTheme()`.
+
+**This is purely additive.** `Select.tsx`/`SelectProps.ts`/`Select.styles.ts` were not touched — existing
+consumer apps see **zero behavior change** on upgrading `pixelize-design-library`, whether or not they
+ever adopt `SelectV2`. New work should prefer `SelectV2`; old call sites can keep using `Select`
+indefinitely, with no forced migration.
+
+- **Path:** `src/Components/SelectV2/` — `SelectV2.tsx`, `SelectV2Props.ts`, `SelectV2.test.tsx`.
+- **Built from existing primitives only** — Chakra `Popover`/`PopoverTrigger`/`PopoverContent` (already
+  globally dark-mode-patched via `Theme/chakra/Popover.styles.ts`, Wave H) plus plain React state. No new
+  dependency added (no react-select/downshift/MUI) — bundle size and dependency surface are unchanged for
+  every consumer.
+- **Prop shape mirrors `Select`** for easy future migration: `options: {id, label}[]`, `value`,
+  `onChange(option | undefined)`, `placeholder`, `label`, `error`, `errorMessage`, `helperText`,
+  `isDisabled`, `isRequired`, `size` (`sm`/`md`/`lg`, same px/height scale as `Select.styles.ts`). Not
+  identical — e.g. no `variant`/`colorScheme` passthrough — since it isn't a drop-in wrapper.
+- **`data-testid`** is forwarded to the trigger button (same element as `role="combobox"`), so a
+  `Select` call site's existing `getByTestId(...)` query keeps working after switching to `SelectV2`.
+- **Multi-select** via `isMulti` (discriminated union in `SelectV2Props`): `value` becomes
+  `(string|number)[]`, `onChange` receives the full `OptionProp[]` selection, each row renders a checkbox,
+  and the popup stays open across picks (`resetAndClose` skips closing on `isMulti`). Trigger shows the
+  joined labels, or `"N selected"` past `maxLabelsBeforeSummary` (default 2).
+- **Custom option/row/trigger content**: `option.icon` + `option.description` give a built-in
+  icon+label+description row layout with no extra work; `renderOption(option, {isSelected, isActive})`
+  takes full control of a row (badges, avatars, arbitrary JSX) when that's not enough; `renderValue(selected)`
+  does the same for the trigger's content. All optional — omit for the original plain-text behavior.
+- **`defaultOpen`**: opens the popover immediately on mount instead of waiting for a click — for
+  inline-edit patterns (a table cell that swaps to a select the instant it becomes editable, replacing a
+  native `<select autoFocus>`). Click-away still closes it via `Popover`'s own close-on-blur, firing `onBlur`.
+- **Type-ahead filtering** built in (`isSearchable`, defaults `true`): a text input at the top of the
+  popup filters `options` client-side by substring match on `label`. Set `isSearchable={false}` to hide
+  it (still fully keyboard-navigable without it).
+- **Keyboard/ARIA:** trigger is `role="combobox"` with `aria-haspopup="listbox"`/`aria-expanded`/
+  `aria-controls`; popup list is `role="listbox"` with `role="option"`/`aria-selected` items. ArrowDown/
+  ArrowUp move the active option (wraps at both ends), Enter selects, Escape closes without selecting,
+  Tab closes and lets focus move on. Reuses Chakra's `Popover` focus/outside-click handling rather than
+  reimplementing it.
+- **Styling:** trigger box uses `Components/Common/fieldStyles.ts`'s `getFieldStateStyles()` — the same
+  shared border/focus/error visual standard as `Select`, `SearchSelect`, `MultiSelect` — so a `SelectV2`
+  sits visually consistent next to any of them. Popup surface/list follow the same token conventions as
+  `Dropdown`'s portaled menu (`background[50]`, `boxborder[200]`, `primary.opacity[8]` hover).
+- **Known gap / fast-follow:** no virtualization — fine for typical option-list sizes (tens to low
+  hundreds); for very large lists prefer `SearchSelect`, which already has performance tests and
+  virtualizes.
+- **Popup clipped inside `overflow:hidden` ancestors (user-reported, fixed).** `PopoverContent` wasn't
+  wrapped in Chakra's `<Portal>`, so it rendered inline in the DOM — any ancestor with
+  `overflow: hidden` (e.g. the library's own `Card variant="elevated"`, used throughout consumer
+  apps' settings/detail pages) visually clipped the open popup to whatever space was left below the
+  trigger. Symptom looked like a filtering bug (a 3-option list showing only the first option by
+  default, but showing correctly once typed down to 1 match) when it was actually the same content
+  height fitting inside the clipped region either way — the filter never changed. `Dropdown` and
+  `SearchSelect` already portal their menus for exactly this reason (see "Key rules" above); `SelectV2`
+  now does too.

package/.cursor/modules/inputs-toggle/MODULE.md

@@ -0,0 +1,24 @@
+# Toggles
+
+## Purpose
+
+Checkbox, RadioButton, Switch, Slider, Toggle/TableToggle.
+
+## Key paths
+
+- `src/Components/Checkbox/`, `RadioButton/`, `Switch/`, `Slider/`, `Toggle/`
+
+## Key rules
+
+- RadioButtonGroup for grouped radios
+
+## Dark-mode / contrast fixes
+
+- `Checkbox`: label tooltip now uses the shared `ToolTip` component instead of raw Chakra `Tooltip` with hardcoded `gray[600]`/`white` — `ToolTip` resolves a dark-mode-aware surface itself.
+- `Toggle/TableToggle`: selected-tab label color changed from `theme.colors.black` (mode-invariant) to `theme.colors.text[900]` (mode-adaptive). Real bug fix: `black` was rendered on `background[50]`, which is near-black in dark mode — black-on-near-black was invisible; `text[900]` flips to near-white in dark mode.
+- **`Slider`/`Switch` thumb bug (theme-level fix):** Chakra's own thumb baseStyle for both
+  hardcodes `bg: "white"` with **no** `_dark` gate at all (unlike most other components in this
+  sweep), so every bare `<SliderThumb>`/`<Switch>` rendered a literal white circle/knob on the
+  dark canvas regardless of mode. Fixed centrally in `Theme/chakra/Slider.styles.ts` and
+  `Switch.styles.ts` (registered in `componentStyles.ts`), each overriding the thumb part's `bg`
+  to `theme.colors.backgroundColor?.light ?? theme.colors.background?.[50]`.

package/.cursor/modules/kanban/MODULE.md

@@ -0,0 +1,22 @@
+# Kanban
+
+## Purpose
+
+KanbanBoard with drag-and-drop columns and KanbanActions.
+
+## Key paths
+
+- `src/Components/KanbanBoard/`, `KanbanActions/`
+- Tests: `KanbanBoard.test.tsx`, `AccountCard.test.tsx`
+
+## Key rules
+
+- Uses @hello-pangea/dnd; MeasuredItem for layout
+
+## Dark mode
+
+- **KanbanBoard.test.tsx** mocked theme extended with a full `secondary` ramp (`600`-`900`) and
+  `backgroundColor.main`, for parity with other components' test mocks in this refactor pass.
+  **Known gap:** neither field is actually read by `KanbanBoard.tsx` or its subcomponents today —
+  this is inert test-fixture parity, not new dark-mode test coverage. KanbanBoard itself was not
+  touched in this pass.