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

package/CHANGELOG.md

@@ -0,0 +1,300 @@
+# Changelog
+
+All notable changes to `pixelize-design-library`.
+
+Versions follow semver. The `beta` dist-tag is released manually from the active feature branch;
+`latest` is published by CI from `develop`. **Pin a prerelease exactly** (`2.4.2-beta.43`, never
+`^2.4.2-beta.43`) — a caret range on a prerelease is satisfied by the next stable publish, which
+silently downgrades you.
+
+Found a bug or a gap? Report it as a GitHub issue and track it to closure — see
+[COMPONENT-GOTCHAS.md](COMPONENT-GOTCHAS.md#found-a-gap-or-a-bug-report-it-then-track-it). A fix's
+line below names its issue number.
+
+## [Unreleased] — 2.4.2-beta.x
+
+The theme-tokens/dark-mode line. Still in beta; the breaking items below land together in the
+next major.
+
+### Added
+
+- **`SegmentedControl` / `Switch` — `surface`.** The background the control is drawn on. Optional:
+  the track is an opaque plate on any backdrop, so the labels read without it. Pass it to aim the
+  plate's hairline edge at the real backdrop rather than at the page canvas.
+- **`MultiSelect` — `addOnBlur`.** Commits the typed address on focus-out as well as on Enter.
+  Defaults to `false`, so existing call sites keep Enter-only behaviour.
+
+- **Dark mode.** `PixelizeThemeProvider` (defaults to `system`), `useThemeMode`, `ThemeSwitcher`.
+  Dark palettes are derived per brand from that brand's own light palette, so brand hue carries
+  through. `withTheme` stays light-only, so existing apps are visually unchanged — dark is opt-in.
+- **`MediaViewer`** — a full-screen viewer for images, video, audio, PDF, Office documents, text
+  and archives, with a filmstrip, keyboard navigation and per-kind fallbacks. `index` is optional:
+  omit it and the viewer owns navigation itself.
+- **`NotificationBell` / `NotificationPanel` / `NotificationList` / `NotificationItem`** — a
+  notification tray with zones, filters, day bucketing and all four load states.
+- **`Backdrop`** — a fading scrim matching MUI's Backdrop exactly (black at 0.5, no blur, 225ms in /
+  195ms out, 40px spinner), with `container` scoping, `invisible`, `onClick` dismissal and
+  `allowBackgroundInteraction` to let clicks reach the page behind. Prefer it over any hand-rolled
+  overlay. `Loading` gains `variant="dim"` to route through it; its default stays `"frosted"`, so
+  existing screens are visually unchanged.
+- **`ConfirmDialog`** — the shared Cancel/Confirm shape, including typed confirmation
+  (`confirmationText`).
+- **`Avatar` / `AvatarGroup`** as owned components. The fill is derived from `name` through the
+  theme's colour scales, so it follows brand and dark mode on its own.
+- **`RangeSlider`** as an owned dual/single-thumb component with a `marks` prop.
+- `resolveFilledSurface(scale, colors)` — picks readable ink for any filled surface.
+- `size="2xs"` (16px) on `Avatar`, and `getInitials` to override the built-in derivation.
+
+### Changed
+
+- **Control heights: `xs` 24px → 28px, `sm` 32px → 35px.** `md` (40px) and `lg` (48px) are
+  unchanged. `CONTROL_SIZES` is the one scale behind every field, select and button, so `Button`,
+  `TextInput`, `InputTextArea`, `NumberInput`, `PinInput`, `Select`, `SelectV2`, `SearchSelect`,
+  `SelectSearch`, `Search`, `Dropdown`, `SegmentedControl` and the `DatePicker` family all grow
+  together and still line up side by side. `sm` is the default size, so most call sites gain 3px of
+  height without passing anything.
+
+- **`SideBar` sizing is one scale.** Rail, submenu, collapsed flyout and `SecondaryBar` rows now all
+  read `SIDEBAR_ROW`, so every nav label is 13px at every level. Visible changes: submenu and flyout
+  rows grow 20px → 28px with their labels 12/12.5px → 13px, the "Add New" label 12.5px → 13px, and
+  `SecondaryBar`'s `headerFontSize`/`itemFontSize` defaults 0.75rem → 13px. Child rows previously
+  rendered a step smaller than their parent; pass the `SecondaryBar` font props to keep the old size.
+- **Charts are lazy.** `react-apexcharts` now loads behind a dynamic `import()`. The main chart
+  entry dropped from 227,454 B to 2,448 B gzip, and an app that never renders a chart no longer
+  pays for one. Verified against real ESM build output.
+- `src/index.publicApi.test.ts` is now **bidirectional** — removing a public export fails the
+  build instead of passing unnoticed (249 → 387 guarded names).
+- `Accordian` still resolves, now as a `@deprecated` alias for the owned `Accordion`.
+- **`ToggleSwitch` absorbs every `InputSwitch` capability**, so `InputSwitch`'s deprecation is now
+  true: `isChecked` is optional (uncontrolled via `defaultChecked`), `fieldLabel` (+ `isInformation`/
+  `informationMessage`) for a label above the track distinct from the inline `label` beside it,
+  `colorScheme` (any brand/global scale, via `resolveFilledSurface`), `isReadOnly` with real
+  `aria-readonly`, and `m`/`mt`/`mb`/`ml`/`mr`/`mx`/`my` on the wrapper. `InputSwitch` is now a
+  genuine thin wrapper — no prop it previously accepted is silently dropped.
+
+### Fixed
+
+- **Icons beside a field are centred at every size and height.** A lone right-hand icon in
+  `TextInput` (an `inputRightIcon`, the clear button or the password toggle) sat flush against the
+  border while the left one was inset; both now mirror at 6/9/12/15px. `SelectSearch`'s `rightIcon`
+  was centred on a 40px box whatever the field size (up to 8px high at `lg`). `Tabs` drew a
+  caller's icon at the caller's size inside a token-sized box, leaving it 3–6px off; it is now
+  pinned to the size token. `TableSearch`'s clear icon and `TableToggle` had a literal `2rem`
+  height and now follow the `sm` control height. `TextInput`'s `height` prop now wins over the
+  size token's `minH`, so an explicit height below the token no longer leaves a taller input in a
+  shorter group.
+- **`*Props` JSDoc quoted the old control scale.** Eleven components documented "xs 24 · sm 32";
+  they now say 28 / 35, and `Common/controlSizeDocs.test.ts` fails if they drift again.
+- **`Table` — a column search only ever matched the page you were looking at.** The per-column
+  search ran on `filteredData`, which `useTable` had already sliced to the current page, so a match
+  on page 3 was invisible from page 1 and the pager still counted every row. The search now runs
+  before the slice: page count, the `1 - 20 of N` readout and the rendered rows all come from the
+  matched set, and typing a new search returns to page 1. Grouped mode already searched the whole
+  source and is unchanged; server pagination still searches only the loaded page, since the client
+  cannot see the rest.
+- **`Table` — an empty page was a dead end, and a page-size change left the body scrolled.** The
+  pager's step controls were hidden whenever the loaded rows were empty, so a server page that came
+  back with nothing stranded the user with no way back; stepping back now survives an empty result
+  and only stepping forward is disabled. A narrowing client-side result also clamps the current page
+  instead of leaving it past the end. Changing the page size at page 0 swaps the rows without moving
+  `startRow`, which used to leave the virtualized body scrolled into the old page — the scroll reset
+  now keys on the page size too.
+- **`Table` — a full-bleed status cell ignored `columns[].align`.** `align` is documented as aligning
+  the header label and the cells together, but a bleed status cell hardcoded centre. It now follows
+  `align` when the column sets one, and still centres when it does not, so existing tables look the
+  same.
+- **`Select` — the popup's filter field did not line up with the options under it.** Its wrapper
+  used a hardcoded `p={2}` while option rows inset by the size spec's `mx` (6px at `sm`, 4px at
+  `xs`), so the field's edges sat 2-4px inside the list's, and its text origin 2px further in. The
+  field was also fixed at `size="sm"` whatever the `Select`'s own size, so a `lg` picker got a small
+  search box. Both now follow the active size spec; measured edge- and text-aligned at every size.
+- **`Select` — a multi-select with chips rendered 2px taller than every other field.** The chip row's
+  vertical padding was computed against the control height without allowing for the trigger's own
+  1px rule top and bottom, which a border-box trigger adds on top. The sizing now lives in one
+  shared helper (`Common/chipTriggerSize`) that `Select` and the deprecated `SelectV2` both read.
+- **`SearchSelect` — infinite-scroll paging could duplicate a page, loop forever on an
+  exact-multiple total, leak a pending fetch into a closed/unmounted menu, and never scrolled the
+  keyboard-highlighted row into view.** `handleScroll` now reads the live option count at fire
+  time instead of the value captured when its 200ms debounce was scheduled, and won't re-request a
+  `startIndex` it already asked for. `hasMore` takes new optional `pagination.hasMore` /
+  `pagination.totalRecords` overrides, defaults `limit` to 10 (it used to never update when `limit`
+  was omitted), and stops after one page that doesn't grow `options`. The pending page timer is
+  cleared on close/unmount, and the active row now scrolls into view with `block: "nearest"`.
+- **`Table` — frozen columns sat at the wrong offset, and the pagination bar was misaligned.** The
+  sticky `left` was passed as a bare number, which Chakra reads off the space scale: a 48px offset
+  rendered as `12rem` (192px), and any cumulative frozen-column width landing on the scale jumped
+  4x. It stayed hidden because the old `CHECKBOX_SLOT_OFFSET = 50` is not a scale value — but 50
+  also missed the real 48px select-all cell by 2px, leaving a slit that scrolled content bled
+  through, and was wrong outright for `variant="studio"`'s 56px slot. The slot is now measured with
+  a `ResizeObserver`, and both offsets interpolate explicit pixels. The pager is one 24px row: the
+  `mt={3}` that faked centring is gone, the steps are `size="xs"` with 16px icons instead of
+  Chakra's 40px default, and the page-size select no longer fights `justify="flex-end"` with
+  `w="100%"`.
+- **`Table` — virtualized body jumped to the top on an appended page, and never scrolled on a real
+  page change below the virtualize threshold.** The scroll-reset effect now keys on `startRow`
+  actually changing instead of on the 30-row virtualize threshold flipping, so infinite-scroll and
+  grouped `groupLoadMore` appends no longer yank the user to the top, while a real page change
+  resets correctly at any size. A shrinking `data` set no longer strands the window past the end,
+  the offset-lookup binary-searches instead of scanning from 0, and measured row heights are
+  pruned per page instead of growing forever.
+
+- **`SegmentedControl` / `Switch` guessed the backdrop it was drawn on.** `brandSlide` painted an
+  8% brand tint composited over `backgroundColor.main` and lifted its unselected-label ink against
+  that same assumed canvas, so on a brand-filled bar the tint sank into the bar and the label
+  measured **1.03–2.03:1 across all 9 brands x 2 modes** — crm's `Overview / Timeline` view switcher
+  on a `primary[700]` bar was unreadable. The track is now an opaque plate on every backdrop: rest
+  ink 7.58–18.39:1, plate-vs-bar 6.31–19.0:1, with no change required at the call site. `surface`
+  is now only a refinement for the plate's hairline edge, and a test gates the invariant.
+- **A selected `Select`/`SearchSelect`/`SelectSearch`/`CompactSelect` option stacked brand ink on a
+  brand-tinted row** — `CompactSelect` had no selected styling at all. The label is now `text[900]`
+  at weight 500 with the brand carried by a trailing check, matching `OrgSwitcher`. The row tint
+  itself is also settled to one perceptible step off the panel instead of taking the raw token
+  (`selected` 1.16–1.29:1 → 1.151–1.191:1; the pressed-and-selected state above it 1.34–1.52:1 →
+  1.259–1.340:1), so a too-saturated tint is pulled down as reliably as a too-faint one is lifted.
+- **Every dropdown row is now one size.** `Select`, `SearchSelect`, `SelectSearch`,
+  `CompactSelect`'s filter, `DropDown`'s menu items and every themed `Menu` item shared six
+  different paddings for the same row; `sm` is now 30px tall everywhere (`padding: 4px 10px`,
+  `font-size: 13px`) instead of `SearchSelect` alone rendering ~34px with a 16px font. Row
+  content — including a `SearchSelect` `option.view` or `Select` `renderOption` node — now inherits
+  its font size from the row, so consumer-rendered row content is no longer stuck at the page's
+  16px body font.
+- **A dropdown row's description sub-line fell under AA in dark mode.** Settling the selected rung
+  left `textMuted` at **4.00–4.22:1** on the hovered-selected row across 6 of 9 brands (dark
+  `surfaceRaised` carries only ~0.86 of headroom, so any lighter rung eats it). The sub-line ink is
+  now derived once per palette against that busiest rung, clearing 4.5:1 everywhere; light mode is
+  unchanged because it already cleared.
+- **`Switch` no longer forces a 200px-wide track when it has no labels.** The width floor now only
+  applies once a label is set, so an unlabelled instance — the wrong component for a boolean field,
+  but one that shipped live in a 120px table cell — shrinks to fit instead of overflowing by 80px.
+  Use `ToggleSwitch` for an on/off field; swapping it in trades `role="radiogroup"` for
+  `role="switch"`, the same `getByRole` break the `InputSwitch` → `ToggleSwitch` migration caused.
+
+- **`SegmentedControl`'s pill bulged past the plate's corners.** The pill and the segments carried
+  the track's own `lg` radius while sitting 2px inside it, so the plate's band stayed even along the
+  straight edges but pinched to nothing at the corners. They now round concentrically at
+  `calc(radii.lg - TRACK_PADDING)`, and a test gates the relationship.
+- **Every field's focus ring was too heavy.** Fields reused the button ring — a 2px surface halo
+  plus a 2px brand band — outside a 1px border that also turns brand on focus, so a focused field
+  was ringed by 5px of chrome reading as one fat stroke. Narrowing and fading that band did not fix
+  it: a `0 0 0 Npx` shadow has a hard outer edge at every opacity, and beside a same-hue border it
+  always merges into one thick stroke. Fields now draw `focusGlowShadow` as a **blurred bloom** —
+  `0 0 6px -1px primary.opacity[32]` — with the border still turning `primary[500]` as the
+  accessible 3:1 indicator. Buttons, chips, checkboxes and every borderless control keep the
+  two-tone ring unchanged.
+- **The Switch demo's "brand-filled bar" was pale in dark mode.** It hardcoded `primary[700]`,
+  which is deep in light and pale in dark, so the bar inverted and the whole comparison was
+  unreadable. It now derives the bar from `resolveFilledSurface(...).activeFill` and **measures**
+  both contrast ratios live against the active brand and mode, instead of printing two numbers that
+  were only ever true in light mode. `segmentedTrackSurface`, `segmentedRestInk` and
+  `segmentedFocusShadow` are now one shared module, so the demo, the component and the contrast
+  gate cannot drift apart.
+- **`SegmentedControl` on a brand-filled bar was unreadable mud.** `brandSlide`'s track is an 8%
+  brand tint, which on a brand bar composites straight back into the bar — the control lost its
+  own surface and the labels had nothing to sit on. With `surface` the track is now an opaque
+  plate (`surfaceRaised`) carrying a 1px inset edge lifted to 3:1 against the bar, because in dark mode
+  the plate and the bar can sit at nearly the same lightness (1.56:1 on radiant) and hue alone
+  would not separate them. The `/switch` demo shows the control instead of a pass/fail ratio pair.
+- **`Tabs` drew a focus ring that was clipped into two arcs.** `TabList` scrolls, so the outer
+  two-tone ring was cut off on all four sides and rendered as two disconnected side edges rather
+  than a ring. The tab now draws it inside itself (`outline-offset: -2px`), clear of the `outline`
+  variant's own border, in an ink lifted to 3:1 against that tab's own surface.
+- **`SegmentedControl` / `Switch` drew the button's focus ring.** A segment sits inside a track, so
+  the ring's surface-toned halo painted a white band and both bands landed outside the pill — a
+  thick double border that overflowed the track. A radiogroup is also a single tab stop, so ringing
+  one segment says nothing the selection does not already say. The **group** now carries the
+  indicator, in the same language as a focused field: a 1px brand hairline inset on the track plus
+  `focusGlowShadow`. `underlineSlide` has no track chrome, so there the segment wears it.
+  `ThemeSwitcher`'s mode segments follow the same rule through their own border.
+- **`Switch` clipped long labels.** Its 12.5rem width was fixed, so labels wider than the track
+  overflowed the background; it is now a minimum. `SegmentedControl`'s track carries
+  `minW="max-content"` for the same reason.
+- **`ThemeSwitcher` had no visible focus indicator.** All four controls used Chakra's `boxShadow:
+  "outline"` token, which resolves to a fully transparent shadow under these brand themes — keyboard
+  focus was invisible. They now use the library's own rings.
+- **Four fields never used the shared focus style.** `PinInput`, `VerifyEmailOtp`, the
+  `CalendarPanel` month/year selects and the `FilterSidebar` search box each hand-rolled a focus
+  shadow (the last one suppressed it entirely with `boxShadow: "none"`). All four now read
+  `fieldFocusVisible`, so the library has one field focus treatment rather than five.
+- `SearchSelect` drew its placeholder over the selected chips. The search input is `flex: 1`
+  with `minW: 0`, so a field holding chips shrinks it to near-zero and the placeholder text
+  overflowed across them. The placeholder is now the empty-state hint only — it is dropped as
+  soon as anything is selected, open or closed.
+- `Select`'s popup panel truncated long option labels. It no longer inherits the trigger width
+  (`matchWidth`); it grows to `max-content` above a measured trigger-width floor, capped at
+  `min(24rem, 100vw - 2rem)`.
+- `usePrefersReducedMotion` crashed during SSR — it now guards `window.matchMedia`. Affected
+  `Tabs`, `Toaster` and `SideBar`.
+- `MediaViewer` coalesced several navigation calls landing in the same tick, so six rapid arrow
+  presses advanced one item. Relative moves now compose.
+- `SideBar` menu labels clipped descenders (g/y/p/q/j), and its nav list showed a bare, unthemed
+  scrollbar when items overflowed.
+- `SideBar`'s `locked` menu-item flag now actually blocks interaction.
+- `sidebar.hoverBg` no longer shares `sidebar.divider`'s value.
+- `InputSwitch`'s `colorScheme` was destructured and discarded — every switch rendered `primary`
+  regardless of the prop. Now forwarded to `ToggleSwitch` and actually applied.
+
+### Deprecated
+
+Nothing is removed yet — each of these still ships its full implementation.
+
+- `SelectV2` — use `Select` with `native={false}`; it is already a thin wrapper over it.
+- `SearchSelect`, `SelectSearch` are **no longer `@deprecated`.** Both now say "prefer `Select`
+  for new work" instead: `@deprecated` claimed a migration that loses real capabilities
+  (`insideSelect`, `isSelectAll`, `addNew`, field-level loading; and `SelectSearch`'s combobox is
+  the text input itself, a different ARIA pattern). The marker returns once `Select` absorbs them.
+- `Dropdown` is **no longer deprecated.** The marker was an artifact of the Select-consolidation
+  pass; `Dropdown` is a `role="menu"` action menu, never a value picker, and nothing replaces it.
+- `Notification` is **no longer deprecated.** `NotificationItem` cannot replace it —
+  `formatRelativeTime` clamps every future date to "Just now", so a countdown card silently
+  renders wrong text through it.
+- Dead props now marked rather than silently ignored: `Checkbox.variant`, `ProgressBar.variant`,
+  `Table.isVisiblity` and its export props, `SideBar.selectedSubMenu`, `InputSwitch.variant`/
+  `.spacing`/`.isFocusable`, and nine native-only `Select` props that are inert under
+  `native={false}` (these now warn in dev).
+- `disabled` → `isDisabled` on `SideBar`, `Buttons`, `StageProgress`, `Input`, `DatePicker`. Both
+  are accepted; `isDisabled` wins.
+- `MultiSelctOPtions` → `MultiSelectOption` (two typos in a shipped public type name).
+
+### Breaking — staged for the next major, not yet released
+
+**34 Chakra value passthroughs (and 12 type passthroughs) are removed from the Primitives barrel**,
+because each duplicated a component this library already owns. The point of the library is one
+place to change the UI; a Chakra twin beside an owned component means half the call sites bypass
+the theme.
+
+Every removal is a **compile error, never a silent behaviour change** — the owned components' props
+differ, so `tsc` names each site and nothing must be found by hand.
+
+- `Tabs` takes `value: string` where Chakra's took `index: number`.
+- `RangeSlider`'s old sub-parts (`SliderTrack`, `SliderFilledTrack`, `SliderThumb`, `SliderMark`)
+  are gone; the owned component renders its own internals.
+- `Avatar`/`AvatarGroup` keep their names but narrow their props: `name` is required, Chakra style
+  props are rejected, and `AvatarGroup` takes a `people` array instead of `Avatar` children.
+
+**Blast radius concentrates in `hrms`, with a long tail in `social-frontend`, `tickets`,
+`account-frontend`, `spare-cart` and `lfour`.** `crm-frontend` and `commerce/frontend` import no
+affected name at all.
+
+Get the current number from `scripts/verify-consumers.sh check`, which typechecks every consumer
+against a real build — **do not estimate it by grep.** A grep conflates names that were removed
+outright (`ChakraModal*`, `CardBody`, `ModalContent`, the `Slider*` sub-parts, `TabList`/`TabPanel`)
+with names that still resolve but narrowed (`Avatar`, `AvatarGroup`, `Tabs`, `RangeSlider`), and
+overcounts badly — that mistake has already been made twice in this repo's own planning docs.
+
+Layout and composition primitives with no owned equivalent stay exported: `Box`, `Flex`, `Stack`,
+`Grid`, `Text`, `Heading`, `Divider`, `Badge`, `Alert*`, `Menu*`, `Popover*`, `FormControl*`,
+`List*`, `Portal`, `TableRoot` and the Chakra hooks.
+
+Consumers pin published versions, so none of this bites until a repo upgrades.
+
+### Known gaps
+
+Tracked in `.cursor/plans/deferred-breaking-changes.md` (repo-only). The ones a consumer can hit:
+
+- `Select`'s search matches `label` only — no `searchFields` / `filterOption`.
+- `Select`'s `virtualizeAfter` silently disables itself when any option has a `group`.
+- `Select`'s `onLoadMore` is zero-arg with no `hasMore` gate, unlike `SearchSelect.pagination`.
+- Migrating `SearchSelect` → `Select` by hand: `SearchSelect.onSearch` debounces **1000 ms**;
+  `Select.searchDebounceMs` defaults to **0**. A mechanical rename starts firing the consumer's
+  API on every keystroke.
+- React 19 is not supported — `peerDependencies` pins React `^18.3.1`, in step with Chakra 2.8.