pixelize-design-library 2.3.22 → 2.4.1

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,32 @@
+# 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
+
+- **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,56 @@
+# 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. The one remaining `colors.white` (day label on the filled `primary[500]` circle — selected / range start / range end) is a *foreground* and correctly stays white. Don't "fix" it.
+- **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`.
+- 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,27 @@
+# Select & Search
+
+## Purpose
+
+Select, SearchSelect, SelectSearch, MultiSelect, Dropdown, Search.
+
+## Key paths
+
+- `src/Components/Select/`, `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`

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

@@ -0,0 +1,18 @@
+# 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.

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.

package/.cursor/modules/layout-navigation/MODULE.md

@@ -0,0 +1,269 @@
+# Layout & Navigation
+
+## Purpose
+
+Accordion, Breadcrumbs, NavigationBar, SideBar, Header, Drawer, FilterSidebar,
+WorkspaceWindow.
+
+## Key paths
+
+- `src/Components/Accordion/`, `Breadcrumbs/`, `NavigationBar/`, `SideBar/`, `Header/`, `Drawer/`, `FilterSidebar/`, `WorkspaceWindow/`
+
+## Key rules
+
+- SideBar/Header have sub-`components/` folders
+- Used by crm-frontend, account-frontend sidebars
+
+## Dark mode
+
+FilterSidebar, WorkspaceWindow and WorkspaceTrayPreview read surfaces from
+`useCustomTheme()` and follow the active palette. Chakra string tokens (`gray.50`) already
+resolve through the swapped palette — only `white` had to change, because `colors.white` is
+a **foreground** token that stays white in dark. White surfaces are now
+`colors.background[50]` (FilterSidebar thumbs / value bubbles / min-max rows / panel,
+WorkspaceWindow shell, WorkspaceTrayPreview popover).
+
+`WorkspaceWindow` calls `useCustomTheme()` **before** its `state === "minimized"` early
+return — after it, hook order would change when the window reopens.
+
+### Header, NavigationBar, FilterSidebar — WCAG/dark pass
+
+- **Header.tsx** — default (no explicit `colors` prop) styling changed: `bg` now
+  `themeColor.sidebar.background[500]` (was `gray[700]`), `color`/`hoverText` now
+  `themeColor.white` (was `background[100]`/`text[600]`), `activeBg` now computed via
+  `accentTextOnCanvas(themeColor.primary, bg)` (was fixed `primary[400]`), `hoverBg` now
+  `sidebar.background[400]` (was `gray[500]`). **Visible behavior change** for any consumer
+  not passing an explicit `colors` prop — not just an internal refactor.
+- **Header/HeaderActions.tsx** (the Header's own action bar — distinct from
+  `Table/components/HeaderActions.tsx`) — "Edit Layout"/"Create New" label ink now
+  `accentTextOnCanvas(colors?.secondary, colors?.backgroundColor?.main)` (was fixed
+  `secondary[500]`); its test mock theme expanded with a full `secondary` ramp +
+  `backgroundColor.main` to match.
+- **NavigationBar.tsx** — brand text label (`navigationBarText`) ink now
+  `accentTextOnCanvas(theme.colors.secondary, theme.colors.backgroundColor.light)` (was fixed
+  `secondary[500]`). Its profile/account `MenuList` also sets
+  `sx={{ "--menu-bg": theme.colors.backgroundColor.light }}` — same Chakra CSS-var fix as
+  `ButtonGroupIcon` (buttons module): Chakra's `MenuItem` baseStyle hardcodes `--menu-bg` to
+  white, gated behind `_dark`, which this app's theme-swap dark mode never triggers.
+- **FilterSidebar.tsx** — section-label tooltip swapped from raw Chakra `Tooltip` (hardcoded
+  `bg={gray[600]}`/`color={white}`) to the library's `ToolTip` (token-driven); search-input
+  `borderColor` now `theme.colors.boxborder?.[800] ?? gray[200]` — plain `gray[200]` fails
+  WCAG 1.4.11 (≥3.0 non-text contrast) as a control boundary in dark mode.
+- **desktopMenu.tsx / Header.tsx `activeBg` (QA-caught, blocking)** — `activeBg` was computed via
+  `accentTextOnCanvas(themeColor.primary, bg)`, which picks its search direction from the canvas's
+  darkness and assumes that always means a dark-mode-shaped scale (50 darkest -> 900 lightest).
+  Header's sidebar canvas is always dark regardless of app mode (`buildDarkPalette` leaves `sidebar`
+  unchanged), but `primary` still follows the active app mode — in light mode it's light-mode-shaped
+  (50 lightest -> 900 darkest), so walking toward 900 walked toward darker, not lighter, landing
+  near-black (lavender measured ~1.09 contrast, well under WCAG 1.4.11's 3:1 non-text bar). Since
+  this same value drove both the active-tab underline (`borderBottom`) and the submenu row highlight
+  (`bg`), and a separate fix removed `activeBg` from *text* color for the identical reason, the
+  underline became the only remaining active-state signal — and it was invisible. Fixed with a new
+  local `pickActiveAccent` (exported from `Header.tsx`, not added to the shared `accentText.ts` — this
+  need is specific to a canvas that never inverts with app mode) that detects the scale's own
+  direction from its own data (`primary[50]` vs `primary[900]` luminance) instead of the canvas,
+  walking toward whichever end is actually lighter and preferring the rung closest to `[500]` that
+  clears 3:1. Verified computationally correct across all 7 brands x both app modes (`Header.test.tsx`).
+  The submenu row's label ink also switched from static `text[800]` (tuned for the `background[50]`
+  canvas, not the `activeBg` fill the active row switches to) to `onFilled(activeBg, white, black)`,
+  which is provably >=4.5 against any fill regardless of which rung `pickActiveAccent` picks.
+- **Drawer.tsx (QA-caught, blocking)** — same `ModalContent` surface bug as `Modal`/`AlertDialog`
+  (overlays module): `DrawerContent` had no explicit `bg=`, so it fell through to Chakra's
+  hardcoded `colors.white` baseStyle, gated behind a `_dark` this app's theme-swap dark mode
+  never triggers. Fixed with `bg={colors?.background?.[50]}`.
+- **FilterSidebar.tsx WCAG pass (Wave D, QA-driven)** — two real AA/graphical-object failures
+  found beyond the surface bug above: the min/max price selected-row checkmark icon (`red[600]`
+  on its own `red[100]` fill, ≈2.89:1, fails the 3:1 non-text bar) now uses
+  `onFilled(theme.colors.red[100], theme.colors.white, theme.colors.black)` (resolves to black,
+  ≈13.96:1); the star-rating icon's `color`/`fill` (`orange[500]` on `background[50]`, ≈2.22:1)
+  now both use `accentTextOnCanvas(theme.colors.orange, <row's actual canvas>)` (resolves to
+  `orange[800]`, ≈6.33:1) — the canvas mirrors the row's own `bg` ternary (`red[50]` when that
+  rating is the active filter, `background[50]` otherwise; a code-review catch — the first pass
+  always computed against `background[50]` even on the selected row). All other `red`/`orange`
+  usages in this file (row backgrounds, `borderLeftColor`, focus border) are decorative/border
+  roles and were left unchanged.
+- **Two `PopoverContent`s missed by the same QA pass (code-review catch, same file):** the
+  min/max price value-list popovers had no `bg=`, hitting the identical
+  Chakra-hardcoded-`colors.white`-behind-`_dark` bug as `Modal`/`AlertDialog`/`Drawer` — just on
+  `PopoverContent`'s baseStyle (`var(--popper-bg)`) instead of Modal's. Fixed with
+  `bg={theme.colors.background[50]}` on both, same pattern already used for `MoreItems`/
+  `OrgSwitcher`/`NavigationBar` popovers elsewhere in the library.
+- **Checkbox/option/popover-row hover invisible in dark mode (QA follow-up round, fixed):** all 5
+  `_hover={{ bg: theme.colors.gray[50] }}` spots in this file (min/max price rows, rating rows, the
+  filter-option checkbox row, the accordion trigger) used `gray[50]`, a pale near-white tint in
+  light mode that — once the whole `gray` scale flips for dark — lands within ~1 lightness point of
+  the dark canvas (~1.08:1 contrast, computed), reading as no hover at all. As a side effect this
+  also silently fixed the `cards`-variant tautology where the accordion button's own resting
+  background (`customStyles.buttonStyle.background`, line ~680) equaled its hover token exactly —
+  hovering a `cards`-variant button visibly did nothing. Fixed via a new pure helper,
+  `getFilterHoverBg(colors, isDark)` (`filterHoverStyle.ts`, mirrors `Editor/joditThemeVars.ts`'s
+  pattern) — dark mode now uses `gray[300]` (~2.3:1 against the canvas, clearly visible) which still
+  keeps the existing `gray[700]`/`gray[800]` row text at/above AA (~4.9:1+) on top of it, so — unlike
+  the Table row-hover fix — no text-color flip was needed here. Light mode is untouched (`gray[50]`).
+  Regression tests: `filterHoverStyle.test.ts` (lavender + rosewood).
+- **Accordion section-header hover still invisible after the fix above (QA retest follow-up):**
+  the 5th spot (the accordion trigger row itself) kept showing no hover change even after
+  `getFilterHoverBg` fixed the other 4. Traced two real, distinct issues in `Accordion.tsx` (not
+  FilterSidebar): (1) its own `expandedBg`/`softHover` defaults — `primary.opacity[8]` composited
+  over the dark canvas, and `table.hover[100]`/`gray[50]` — both collapse to ~1.07-1.09:1
+  (verified numerically), so any Accordion consumer relying on these un-overridden defaults gets an
+  invisible expanded-state tint and hover in dark mode; (2) FilterSidebar's own header override
+  (`buttonProps._hover: { bg: hoverBg }`) was verified via direct CSSOM inspection to compile into a
+  correct `:hover` rule with the right color even with FilterSidebar's exact `customStyles`
+  shape — the mechanism itself checked out. Fixed (1) with a new pure helper,
+  `getAccordionHoverColors(colors, isDark)` (`Accordion/accordionColors.ts`, same pattern as
+  `Editor/joditThemeVars.ts` / `FilterSidebar/filterHoverStyle.ts`): dark mode now uses `gray[200]`
+  for both (opaque, ~1.6:1 against canvas — visibly present but a step below the `gray[300]`
+  active-hover fill FilterSidebar/Table already use), light mode unchanged. Reinforced (2) as
+  belt-and-suspenders: FilterSidebar's `customStyles.hoverbuttonStyle` now also sets
+  `{ background: hoverBg }`, reasserting the same fill via the `sx` path so the header hover
+  doesn't depend on a single prop-merge route. Regression tests: `accordionColors.test.ts`
+  (lavender + rosewood). Note: jsdom cannot simulate real `:hover` rendering, so this was verified
+  via computed contrast + direct CSSOM rule inspection, not a live click-test; a real-browser
+  Playwright re-check afterward confirmed the fix applies correctly (`rgba(0,0,0,0)` →
+  `gray[300]` on hover, both brands, reverting on mouse-away).
+- **`Accordion.tsx`/`FilterSidebar.tsx` perf pass:** the new `getAccordionHoverColors`/
+  `getFilterHoverBg` calls above are now wrapped in `useMemo` (keyed on `theme.colors`/`isDark`),
+  matching the existing memoization pattern in `Table/components/TableBody.tsx` — avoids
+  recomputing the color object on every render.
+
+### SideBar — active-icon/label dark-mode fix (user-reported via screenshot, blocking)
+
+`MenuItemBox.tsx`, `MenuPopoverContent.tsx`, `SecondaryBar.tsx`, and `SideBar.tsx` all read the
+active/accent icon and label color from `theme.colors.primary[300]`/`[100]` directly. That's
+correct in light mode, but breaks in dark mode: `sidebar.background` **never inverts** across
+modes (`buildDarkPalette.ts` keeps `sidebar: light.sidebar` — it's already near-black in light
+mode), while `primary`'s every rung **does** invert (`toDarkRamp`/`liftAccent`, correct for
+badge/tag consumers whose surface inverts alongside them). Pairing an inverted `primary[300]`/
+`[100]` with a canvas that stayed put produces near-black text/icons on an already-dark rail —
+only the checked/lavender-selected item stayed legible, everything else read as invisible
+(exactly the user's report: "only selected lavender is visible to my eyes").
+
+Presented 3 fix options via an artifact (pinned-light accent / Header's `pickActiveAccent`
+pattern / a dedicated non-inverting SideBar accent scale) — user chose **pinned-light accent**.
+Fixed with a new pure helper + hook, `src/Components/SideBar/sidebarAccentColors.ts`
+(`getSidebarActiveAccent` / `useSidebarActiveAccent`, same pure-function + `useMemo` pattern as
+`accordionColors.ts`/`filterHoverStyle.ts`): in dark mode it reuses each rung's own **light-mode**
+value (`lightPalettes[brand].primary[300]`/`[100]`) instead of the dark-inverted one — provably
+correct because the canvas behind it is identical in both modes, so whatever already clears
+contrast in light mode still clears it in dark mode with the same foreground value. Falls back to
+the current (still-broken) rung if `brand` is unavailable (a consumer on a plain `ChakraProvider`,
+where dark mode never activates anyway) rather than crashing — `brand` is read via
+`useContext(ThemeModeContext)` directly, not the throwing `useThemeMode()`, since this hook must
+degrade gracefully outside `PixelizeThemeProvider`.
+
+Wired at every active/accent-icon usage: `MenuItemBox.tsx` (main + submenu icon/label/dot),
+`MenuPopoverContent.tsx` (header + submenu icon/label), `SecondaryBar.tsx` (collapsed/expanded
+item icon+label, header icon), `SideBar.tsx` (Add-New icon, avatar-initials fallback, footer
+control accent icon+label, mobile-nav "Show" `PanelLeft` icon) — every one was reading `[300]`
+(icon role) or `[100]` (label role) directly. `borderLeftColor`/`bg` usages of `primary[500]`/
+`.opacity[16]`/`.opacity[32]` were left untouched — confirmed not broken (the audit found `[500]`
+correctly lifts lighter in dark mode; `.opacity[N]` tints are self-scaling, not absolute rungs).
+Regression tests: `sidebarAccentColors.test.ts` (lavender + rosewood) — light mode unchanged,
+dark mode pins the light-mode rung (not the dark-inverted one), contrast ≥3:1 (icon) / ≥4.5:1
+(label) against the sidebar canvas, graceful fallback when `brand` is unknown.
+
+### Known gap — Header "Login" demo button (raw Chakra, wrong-canvas ghost ink)
+
+`Layout.tsx`'s `/header` playground route renders its `rightSlot` demo content with a **raw**
+Chakra `Button` (`import { Button } from "@chakra-ui/react"`, not the library's own `Button`),
+`variant="ghost" colorScheme="purple"`. Because Chakra's theme registration is global once
+`extendTheme` runs, this raw Button still picks up the library's `Button.styles.ts` ghost-variant
+logic (`accentTextOnCanvas(scale, colors.backgroundColor.main)`, buttons module) — but that logic
+assumes the **page** canvas. Header's own bar is an always-dark surface
+(`sidebar.background[500]`), not the page canvas, so the computed ink is tuned for the wrong
+background and can read too dark/low-contrast against Header's actual bar. Not a new bug — it's
+the same "wrong canvas" gap as the already-documented Button ghost-variant limitation, now
+independently confirmed by the QA pass. Deferred: fixing it correctly needs a `canvasBg` prop
+threaded through `Button.styles.ts` so a caller can tell the ghost/outline/link ink helper which
+surface it's actually rendering on, rather than always assuming the page canvas — a bigger,
+cross-component change out of scope for this pass.
+
+## SideBar — responsive overlay (< lg / 992px)
+
+At/above `lg` the SideBar is unchanged: inline, sticky, with the collapse/mini-rail
+(`toggle`). Below `lg` it becomes a slide-in **overlay** above the content (it leaves
+layout flow, so content stays full-width — not shrunk):
+
+- `mobileOpen?: boolean` + `onMobileClose?: () => void` props drive the overlay. Wire
+  `mobileOpen` to the NavigationBar hamburger (`sideBarToggole` / `onSideBarToggole`).
+- Overlay is always expanded (collapse/mini-rail is desktop-only and hidden < lg). The
+  header's trailing control becomes a Close (X) instead of the collapse chevron.
+- Dismiss: backdrop scrim click, **Esc**, the Close button, or **swipe-left** on the
+  panel. Body scroll is locked while open; panel exposes `role="dialog"`/`aria-modal`.
+- NavigationBar hamburger now shows below `lg` (was `< md`); its panel icon is
+  state-aware (`PanelLeftClose` open / `PanelRightClose` closed).
+- The overlay panel has **square edges** (no border radius).
+- Overlay panel width = `OVERLAY_WIDTH` (**14.7rem** / 235px — a touch wider than the
+  inline expanded 13rem for touch), capped by `maxW: 88vw` on very small screens.
+
+Breakpoint, scrim/slide, and z-index are Chakra responsive props (no JS flash) when
+`mobileNav` is off; the breakpoint is read once via `useBreakpointValue({ base: true, lg: false })`.
+
+## SideBar — Hide/Show (mobile navbar on big screens)
+
+A footer **Hide/Show** toggle (next to Collapse) switches the navbar *presentation*
+between the docked desktop sidebar and the mobile-style overlay — at **any** width, so
+desktop users can get the full-screen content experience. It is a layout switch, **not**
+a close: toggling never hides the navigation.
+
+- `mobileNav?: boolean` forces overlay presentation regardless of breakpoint:
+  `overlay = (below lg) || mobileNav`. `onToggleMobileNav?: () => void` backs the
+  footer control (render the control only when provided).
+- Footer control: docked → segmented **Collapse | Hide**; desktop mobile-nav overlay →
+  **Show** (return to docked). Pure below-`lg` overlay shows no navbar-mode control.
+- Wire so entering mobile-nav also opens the overlay (sidebar stays visible) and leaving
+  docks it — see `App.tsx`. NavigationBar `forceSideBarToggle` shows the hamburger at all
+  widths while `mobileNav` is on.
+- Selecting a **leaf** menu item in overlay mode auto-closes the overlay (content returns
+  to full-screen); submenu **parents** only expand and do not close it.
+
+## Persisting sidebar choices — `useSidebarPrefs`
+
+Opt-in hook (`src/Hooks/useSidebarPrefs.ts`, exported from `index.ts`) that persists the
+user's **explicit** layout choices to `localStorage` so they survive reload/restart —
+without it, `mobileNav`/collapse reset to desktop default on every mount.
+
+- Persists `{ mobileNav, collapsed, mobileOpen }` so the sidebar restores to **exactly** the
+  same state (mode, mini-rail, drawer). It deliberately does **not** persist the `lg`
+  breakpoint (viewport-driven, must stay live).
+- SSR-safe (`typeof window` guards); corrupt/invalid stored values fall back to defaults
+  per field; `setItem` failures (private mode / quota) no-op without throwing.
+- API: state `{ mobileNav, collapsed, mobileOpen }`; setters `setMobileNav / setCollapsed
+  / setMobileOpen`; toggles `toggleMobileNav / toggleCollapsed / toggleMobileOpen`; plus
+  **composed handlers** `onToggleMobileNav` (flips navbar mode **and** syncs the drawer)
+  and `closeMobile`. Options: `storageKey` (default `pixelize:sidebar-prefs:v1`, versioned)
+  and `defaults`.
+- **Consumer adoption** — map the returned values onto `SideBar` + `NavBar`; the composed
+  handlers mean apps don't re-implement the navbar-mode/drawer behavior:
+
+  ```tsx
+  const sb = useSidebarPrefs();
+  <SideBar
+    toggle={sb.collapsed} changeToggle={sb.toggleCollapsed}
+    mobileNav={sb.mobileNav} onToggleMobileNav={sb.onToggleMobileNav}
+    mobileOpen={sb.mobileOpen} onMobileClose={sb.closeMobile} /* ...menus, user */ />
+  <NavBar sideBarToggole={sb.mobileOpen} onSideBarToggole={sb.toggleMobileOpen}
+    forceSideBarToggle={sb.mobileNav} /* ...nav props */ />
+  ```
+
+  See `App.tsx` for the live reference wiring.
+
+### Known gaps
+
+- `SecondaryBar` keeps its current side-by-side stacking inside the overlay — revisit if
+  it feels cramped on very narrow screens.
+- Consumer apps (crm/account/…) must pass `mobileOpen`/`onMobileClose` to adopt overlay
+  mode, and adopt `useSidebarPrefs` to get persistence; until then they get the unchanged
+  inline sidebar with non-persisted state.
+- Persisted `collapsed` can be transiently overridden by SideBar's existing "auto-collapse
+  when a secondary panel is active" effect — pre-existing, not regressed.
+- Persisting `mobileOpen` means a phone (`belowLg`) left with the drawer open reloads with
+  it open (until a leaf tap auto-closes it). Accepted to honor "restore exactly the same
+  state"; revisit with a `belowLg` gate if it proves annoying.
+- Dark-mode migration covered FilterSidebar/WorkspaceWindow (surfaces) plus, this pass,
+  Header (default bg/color/active/hover tokens), NavigationBar (label ink + Menu
+  `--menu-bg` fix), and Accordion (item surface + expanded/hover tint — see above) — see
+  "Header, NavigationBar, FilterSidebar — WCAG/dark pass" above. **SideBar's active-icon/
+  label accent is now fixed** (see "SideBar — active-icon/label dark-mode fix" above); its
+  notification-count badge contrast gap is still open — see `theme/MODULE.md` Known gaps.

package/.cursor/modules/overlays/MODULE.md

@@ -0,0 +1,69 @@
+# Overlays
+
+## Purpose
+
+Modal, AlertDialog, ToolTip / OverflowToolTip, Toaster (+ `useToaster` hook).
+
+## Key paths
+
+- `src/Components/Modal/`, `AlertDialog/`, `ToolTip/`, `Toaster/`
+
+## Key rules
+
+- **Toaster `showToast({ actions })`:** optional `actions?: (onClose) => ReactNode`
+  renders action buttons under the message (e.g. Jira-style "View" / "Copy link").
+  The render-prop receives the toast's own `onClose` so an action can dismiss it;
+  callers style the buttons with their app theme. Prefer this over a bespoke Chakra
+  `useToast` in a consumer app — a second `useToast` renders into a *different* toast
+  portal that a `Modal`'s overlay/focus-trap can hide, so the toast silently never
+  appears. The toast card slides in (framer tween), pulses the status icon once on
+  mount, and **pauses the auto-dismiss countdown on hover** so the user can read and
+  click an action before it dismisses.
+- Modal exports ModalHeader, ModalBody, ModalFooter subcomponents
+- **ToolTip `overflowOnly`:** pass `overflowOnly` to show the tooltip **only**
+  when the child text is actually truncated (ellipsis active) — no tooltip when
+  it fits. The child must be the single clamping element (e.g. `Text` with
+  `noOfLines`); its ref is managed internally. Works for single- and multi-line
+  clamps and combines with `isDisabled`. **`OverflowToolTip`** is sugar for
+  `<ToolTip overflowOnly>`. Powered by the `useIsTruncated` hook (see
+  `utils-hooks`). Inert unless `overflowOnly` is set — no measurement/observer
+  for ordinary tooltips, and it never measures on hover/scroll.
+
+## Dark mode
+
+Toaster and ToolTip take all color from the theme (`useTheme()` / `useCustomTheme()`),
+so they follow the active light/dark palette; remaining hex literals are only `??`
+fallbacks for when no Pixelize palette is in context.
+
+- **Modal/AlertDialog surface bug (QA-caught, blocking):** `ModalContent`/`AlertDialogContent`
+  had no explicit `bg=`, so both fell through to Chakra's own `baseStyle`, which hardcodes
+  `[$bg.variable]: "colors.white"` gated behind `_dark` — this app's theme-swap dark mode
+  (palette swapped, Chakra `colorMode` stays `"light"`) never triggers that `_dark` block, so
+  every Modal/AlertDialog rendered a white panel with near-invisible text on the dark canvas.
+  Same bug class as the `ButtonGroupIcon` menu-bg bug (buttons) and the `OrgSwitcher` popover
+  bug (account-management) — Chakra part-styles that hardcode a literal instead of reading a
+  semantic token. `Card` was unaffected because it already used the patched
+  `chakra-body-bg`/`chakra-body-text` semantic tokens (see theme module); Modal/AlertDialog
+  bypass that layer entirely. Fixed with an explicit `bg={colors?.background?.[50]}` on both.
+  `AlertDialog` has no separate Chakra theme key (it reuses Chakra's `Modal` style config
+  internally), but still needed its own prop-level fix since this app's fix is component-level,
+  not a Chakra `components.Modal` theme-config override.
+
+## Dark mode — Modal/AlertDialog consumers
+
+`Drawer` (layout-navigation module) has the identical fix. Every other file in the library that
+renders a raw Chakra `ModalContent` needed the same explicit `bg=` — see the account-management,
+table, and cards MODULE.md sections for the specific consumer components fixed in this pass.
+`WorkspaceWindow` (layout-navigation) was checked and is **not** affected: its `ModalContent` is
+deliberately `bg="transparent"` with an inner `Box bg={theme.colors.background[50]}` as the real
+surface.
+
+- **Toast card surface is `background[50]`, not `colors.white`** — `white` is a
+  *foreground* token (a label on a filled button) and stays white in dark mode.
+  Status tints read `colors.semantic[status]`, falling back to the plain ramp
+  (`green` / `red` / …).
+- **ToolTip is an inverted surface** — near-black under a light canvas, carrying a
+  white label. It uses `sidebar.background[500]`, the one ramp `buildDarkPalette`
+  passes through un-inverted (`sidebar: light.sidebar`), so it stays near-black in
+  dark and the label stays legible; any other surface ramp would flip light and
+  render the white label invisible. Callers overriding `bg` own that contrast.