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

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

@@ -0,0 +1,319 @@
+# 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.
+
+**First real consumer: tickets (user-reported dark-mode gaps + first adoption).** `WorkspaceWindow`/
+`WorkspaceTray`/`WorkspaceTrayPreview` existed but had no consumer yet; tickets' own hand-rolled
+floating-ticket-window/tray/hover-preview (`core/workspace/`) was migrated onto these, and the
+migration surfaced real gaps the "dark-mode checked" note above didn't cover — the control-bar
+`bg="gray.50"`/`borderColor="gray.100"`/title `color="gray.700"` and the tray pill's
+`bg/color/borderColor="blue.100/700/200"` were still **hardcoded literals**, not
+`useCustomTheme()` tokens, so they didn't actually follow brand/dark-mode. Fixed to
+`theme.colors.background?.[100]`/`boxborder?.[200]`/`text?.[700]` (window chrome, same pattern as
+`AiLauncher`) and `theme.colors.primary?.[100/700/200]` (tray pill, matching tickets' own prior
+token usage). `WorkspaceTrayPreview`'s card wrapper had the same gap (`borderColor="gray.200"`,
+`color="gray.800"`) — same fix.
+- **`onOverlayClick?: () => void`** added to `WorkspaceWindowProps` — with `size="full"` the
+  transparent `ModalContent` covers the viewport so Chakra's own `closeOnOverlayClick` never fires;
+  the parent needs its own "clicked the blurred backdrop" signal (tickets uses it to minimize
+  rather than close, preserving unsaved edits). `WorkspaceWindow` detects this itself
+  (`onMouseDown` + `e.target === e.currentTarget` on `ModalContent`) and also exposes
+  `${testId}-backdrop`.
+- **`renderItem?: (item, {restore, close}) => ReactNode`** added to `WorkspaceTrayProps` — full
+  override for one tray item's pill markup, for a consumer that needs to wrap the pill in its own
+  logic (tickets wraps it in a ticket-fetching hover preview, `TrayTabPreview`) while still reusing
+  the tray's positioned/wrap-reverse container. Omit it for the plain built-in pill.
+- Tickets' `TrayTabPreview` now delegates the hover-bridge timer/positioning entirely to
+  `WorkspaceTrayPreview` (`onOpenChange` gates the ticket fetch) and only supplies the ticket-specific
+  `preview` content — the timer/placement logic that used to be duplicated in the app is gone from
+  there now.
+
+### 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. Now also
+  covered app-wide by the theme-level `Menu` style override (`Theme/chakra/Menu.styles.ts`, theme
+  module Wave G) — this per-call-site `sx` is redundant but harmless alongside it.
+- **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 surface bug — now fixed at the theme level.** Same bug class as `Modal`/
+  `AlertDialog` (overlays module): Chakra's own `Drawer` baseStyle hardcodes `--drawer-bg` to
+  `colors.white` on the `dialog` part, gated behind a `_dark` this app's theme-swap dark mode
+  never triggers. Fixed centrally in `Theme/chakra/Drawer.styles.ts` (registered as `Drawer` in
+  `componentStyles.ts`), mirroring `Modal.styles.ts` — covers every `DrawerContent` app-wide. An
+  earlier pass's per-call-site `bg={colors?.background?.[50]}` fix is now redundant but harmless.
+- **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.
+
+### SideBar default logo — hardcoded black fill invisible on dark-`primary[500]` brands (user-reported, fixed)
+
+`SidebarHeader`'s fallback mark (no `logo` prop passed) wraps `Assets/defaultLogo.tsx` in a `Box`
+with `bg={theme.colors.primary[500]}` + `color={theme.colors.white}` — but the SVG paths inside
+`DefaultLogo` hardcoded `fill={theme.colors.black}` instead of inheriting that `color`. Most brands'
+`primary[500]` is a mid-tone hue, so a black mark still read against it by accident; **zinc**'s
+`primary[500]` is `#18181b` (near-black by design — see zinc's palette comment), so the black-on-
+near-black logo was effectively invisible. Fixed by switching all three paths to `fill="currentColor"`
+so the mark always matches whatever `color` its wrapper sets, regardless of brand — `DefaultLogo` no
+longer needs `useCustomTheme()` at all.
+
+That alone wasn't sufficient: the wrapper `Box` itself hardcoded `color={theme.colors.white}`
+regardless of mode. Zinc **inverts** its dark palette — `primary[500]` is `#18181b` in light but
+`#e4e4e7` (near-white) in dark — so a hardcoded-white icon on a hardcoded-white-in-dark-mode fill
+went invisible again, this time in dark mode. Fixed with the same `onFilled(fill, white, black)`
+WCAG-pick helper already used for the calendar's selected-day circle and `Button.styles.ts`'s solid
+variant: `color={onFilled(theme.colors.primary[500], theme.colors.white, theme.colors.black)}`. Any
+future "icon on a `primary[500]` fill" spot should use this same helper rather than assuming white
+always clears — zinc dark is the proof case that it doesn't.
+
+### 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,82 @@
+# 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 — now fixed at the theme level, not per-component.**
+  Chakra's own `Modal` baseStyle hardcodes `[$bg.variable]: "colors.white"` on the `dialog`
+  part, gated behind `_dark` — this app's theme-swap dark mode (palette swapped, Chakra
+  `colorMode` stays `"light"`) never triggers that block, so every `ModalContent` rendered a
+  white panel with near-invisible text on the dark canvas. `AlertDialog` reuses Chakra's
+  `Modal` style config internally, so it inherits the same fix with no separate theme key.
+  Fixed centrally in `Theme/chakra/Modal.styles.ts` (`definePartsStyle` on the `dialog` part,
+  registered as `Modal` in `componentStyles.ts`) — mirrors `Menu.styles.ts`/`Drawer.styles.ts`.
+  A prior pass fixed this per-call-site with an explicit `bg=` prop; that approach is
+  superseded by this theme-level override, which covers every `ModalContent`/`AlertDialogContent`
+  app-wide with zero per-call-site changes (an explicit `bg=` still wins if a caller sets one).
+- **Popover surface bug** — same bug class, fixed in `Theme/chakra/Popover.styles.ts`
+  (`--popper-bg` + `--popper-arrow-shadow-color`, registered as `Popover` in
+  `componentStyles.ts`) — see theme module Wave H. Every bare `<PopoverContent>` in the
+  library (this module doesn't own a dedicated Popover component folder — Popover is used
+  directly from Chakra by many components, e.g. `OrgSwitcher`, `MoreItems`, `SideBar`,
+  `DatePicker`) now gets a dark-aware surface for free.
+
+## Dark mode — Modal/AlertDialog consumers
+
+`Drawer` (layout-navigation module) has the identical theme-level fix (`Drawer.styles.ts`). Many
+consumer components (see account-management, table, cards MODULE.md) additionally carry an
+explicit per-call-site `bg=` from an earlier pass, predating the theme-level `Modal`/`Drawer`
+style overrides above — now redundant but harmless (an explicit prop still wins, same value).
+`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.
+- **Chakra's raw `Tooltip` baseStyle** hardcodes `--tooltip-bg`/`--tooltip-fg` to
+  `gray.700`/`whiteAlpha.900` behind `_dark`, same never-triggered gate — our reversed dark
+  gray ramp makes `gray.700` LIGHT, so a bare (non-`ToolTip`) Chakra `<Tooltip>` renders
+  near-white-on-near-white. Fixed with a `Tooltip` entry in `componentStyles.ts` pinning both
+  vars to `black`/`white` — the two tokens `buildDarkPalette` never remaps, so the chip stays a
+  stable dark-bg/white-text pair in both modes. This library's own `ToolTip` above already sets
+  its own `bg`/`color` explicitly and is unaffected; the fix targets consumer apps that render a
+  raw Chakra `Tooltip` directly instead of this component.

package/.cursor/modules/playground/MODULE.md

@@ -0,0 +1,28 @@
+# Playground
+
+## Purpose
+
+Vite dev playground — demo pages not published to npm.
+
+## Key paths
+
+- `src/Pages/` (49 demo files), `src/App.tsx`, `src/Layout.tsx`
+- `npm start` launches playground
+
+## Key rules
+
+- Demo API calls to dev.pixelizetech.com are playground-only
+- Not included in `dist/` publish output
+
+## Recent changes (WCAG contrast + dark-mode pass)
+
+- `stageProgress.tsx`, `tier1.tsx`, `upgradeButton.tsx`, `orgSwitcher.tsx`: local `Section` demo
+  wrapper switched from hardcoded `bg="white"` / `border="1px solid #E2E8F0"` / `color="gray.700"`
+  to `useCustomTheme()` tokens (`background[50]` / `boxborder[300]` / `text[900]`) — previously
+  stayed white regardless of the active theme.
+- `stageProgress.tsx` (4 captions) and `tier1.tsx` (1 caption): `color="gray.400"` →
+  `theme.colors.gray[500]`, the library's verified muted-text token (`gray.400` fails contrast in
+  dark mode).
+- `card.tsx`: swapped the raw Chakra `Button` (`color="blue"`) for the library's own `Button`
+  (`colorScheme="primary"`) — a component-choice fix, not a Section/caption token pass.
+- Demo-only — no `src/index.ts` export or library API changed.

package/.cursor/modules/table/MODULE.md

@@ -0,0 +1,84 @@
+# Table
+
+## Purpose
+
+Data table with virtualization, filters, pagination, column management.
+
+## Key paths
+
+- `src/Components/Table/`, `Table/components/`, `Table/settings/`, `Table/filters/`, `Table/hooks/`
+- Tests: `components/TableBody.virtualize.test.tsx`, `settings/ManageColumns.test.tsx`
+
+## Key rules
+
+- Core CRM list UI — high change frequency
+- `src/Utils/table.ts` helpers
+
+## Dark mode
+
+Surfaces read `theme.colors.background[50]` via `useCustomTheme()`, so the table follows the
+active palette: `Table` (pagination popover), `TableBody` (expanded-row panel), `CompactSelect`
+(trigger), `LeftFilterPane` (pane + apply/clear footer).
+
+- **`white` is a foreground token, not a surface.** It stays `#fff` in dark, so `bg="white"` /
+  `bg={theme.colors.white}` renders a white slab on the dark canvas — that was the defect this
+  migration fixed. Use `background[50]` (`#ffffff` light, dark-aware) for any surface.
+  `color="white"` on the filter-count badge is correct — it is a label on `primary[500]`.
+- Chakra scale literals (`borderColor="gray.200"`, `_hover={{ bg: "gray.50" }}`) are **already
+  dark-aware** — `createBrandTheme` passes `colors: palette`, so they resolve against the
+  swapped palette. Only for scales the palette defines: `whiteAlpha`/`blackAlpha` are not in it,
+  so they keep Chakra's fixed rgba — `TableGroupRow`'s `_hover={{ bg: "whiteAlpha.500" }}` is
+  still a white wash in dark.
+- `LeftFilterPane` takes `theme` as a **prop** (from `Table`), not from the hook — pass it down.
+
+## WCAG contrast pass (this session)
+
+- `HeaderActions` action-list ink and `TableHeader`'s sort-chevron hover ink + column-header ink
+  now use `accentTextOnCanvas(secondary, canvas)` (from `Theme/tokens/builders/accentText`)
+  instead of a bare `colors.secondary?.[500]` — picks a text color that clears AA against the
+  actual canvas instead of assuming secondary-on-white always passes. Relies on the shared
+  `accentText.ts` guard (theme module) to stay crash-safe when `secondary`/canvas are undefined.
+- `TableBody`'s `StatusCell` ink is no longer hardcoded `white` — it resolves
+  `statusColor.onSolid ?? onFilled(statusColor.solid, white, black)` so the label clears AA
+  against light and dark status fills alike; falls back for callers whose `statusColor` predates
+  `onSolid`.
+- `TableRenderGroup.color` gained an optional `onSolid?: string` (additive, non-breaking).
+- `LeftFilterPane`'s `SectionLabel` tooltip swapped Chakra `Tooltip` → design-library `ToolTip`
+  (drops the manual `bg`/`color`/`theme`-prop overrides — `ToolTip` themes itself).
+- **Filter-sidebar `ModalContent` surface bug (QA-caught, blocking):** `Table.tsx`'s mobile
+  filter-sidebar modal had no explicit `bg=` on `ModalContent`, hitting the same
+  Chakra-hardcoded-`colors.white`-behind-`_dark` bug as `Modal`/`AlertDialog`/`Drawer` (overlays,
+  layout-navigation modules). Fixed with `bg={theme.colors?.background?.[50]}`.
+  `TableSettings.tsx`'s `MotionModalContent` already had this fix from an earlier pass.
+- **`LeftFilterPane`'s date filter (user-reported, blocking):** `LeftFilterPane.tsx` imports the
+  legacy `DatePicker/DatePicker.tsx` directly (not the public `ThemeDatePicker` export) — its
+  `PopoverContent` had the identical missing-`bg=` bug, fixed alongside the other three date/time
+  pickers (see `inputs-date-file` MODULE.md). It's easy to assume this file is dead because the
+  playground's `datePick.tsx` import of it is commented out — it isn't; `LeftFilterPane` is a real
+  consumer.
+- **Row hover invisible in dark mode (QA-reported, fixed):** `TableBody`'s per-cell `_hover`
+  painted `table.hover[300]`, a token built for a light-mode white canvas — in dark mode that rung
+  sits within ~10 lightness points of the near-black canvas (both compressed near L7-15), computing
+  to ~1.2:1 contrast (verified numerically), i.e. no visible hover at all. Fixed via a new pure
+  helper, `getTableRowHoverStyle(colors, isDark)` (`components/tableRowHoverStyle.ts`, same pattern
+  as `Editor/joditThemeVars.ts`): dark mode now fills with `background[900]` (this palette's dark-
+  mode "bright highlight" rung, ~9.7-10.7:1 against the canvas across brands) **and** flips `color`
+  to `backgroundColor.main`, since the row's resting ink (`text[500]`) is tuned for a near-black
+  backdrop and would go illegible against a bright fill — mirrors how Jodit's own dark-mode hover
+  rule flips text to its canvas color alongside a brighter fill. Light mode is untouched
+  (`table.hover[300]`, same as before). Regression tests: `tableRowHoverStyle.test.ts` (lavender +
+  rosewood). Scoped to the per-cell hover mechanism already in place — not restructured to a
+  `<Tr>`-level highlight, since that wasn't the reported defect.
+- **`TableSettings.tsx` enclosed-tab "cutout" bug (theme-level fix):** Chakra's own `Tabs`
+  baseStyle hardcodes the selected tab's cutout color to `colors.white` for the `enclosed`
+  (selected border) and `enclosed-colored` (selected background) variants, both behind `_dark`,
+  same never-triggered gate. `TableSettings.tsx` is this library's only consumer of Chakra's raw
+  `TabList`/`TabPanels`. Fixed centrally in `Theme/chakra/Tabs.styles.ts` (registered in
+  `componentStyles.ts`), overriding both variants' selected-tab cutout token.
+- **Known gap (found by code review, not fixed this pass):** `Table/filters/CompactSelect.tsx`,
+  `Table/filters/TableFilters.tsx`, and `Table/components/TableActions.tsx` each render a raw
+  Chakra `PopoverContent` with no `bg=` — the identical bug class just fixed in `Table.tsx`'s
+  filter-sidebar modal, `FilterSidebar.tsx`'s two price popovers (layout-navigation module), and
+  `Modal`/`AlertDialog`/`Drawer` (overlays module). Not in this session's diff and not covered by
+  any test, so deliberately deferred rather than expanding this pass's scope — worth a follow-up
+  ticket to make the `ModalContent`/`PopoverContent`/`MenuList` sweep exhaustive across the repo.