pixelize-design-library 2.4.2-beta.59 → 2.4.2-beta.60

package/CHANGELOG.md

@@ -26,15 +26,21 @@ next major.
     screens, keyword-only hits get a `· keyword` hint) and `flattenScreens`. The pin control is a
     star, shown with the ↗ link on row hover/focus only (always on touch); pinned rail items are tiles. It binds no global chord. `LauncherTrigger`
     is the chip (10px radius, 36px, accent ink, one ⌘K hint) that opens an app-owned launcher (`aria-haspopup="dialog"`, `aria-expanded`,
-    `aria-keyshortcuts`). Types: `NavLauncherProps`, `LauncherScreen`, `LauncherModule`,
+    `aria-keyshortcuts`); `display="icon"` is a 36px icon-only variant for a nav bar's `moreIcon`
+    (label is the accessible name, tooltip "Menu (⌘K)"). Types: `NavLauncherProps`, `LauncherScreen`, `LauncherModule`,
     `LauncherSection`, `LauncherSearchItem`, `LauncherLabels` and friends, `LauncherTriggerProps`.
     `NavLauncher` follows canvas `Launcher.dc.html`: stacked sections with "(n)" counts and a 1/2/3-column
-    grid, a 300px "Quick access" rail (Pinned tiles, Frequently visited, Recent), "Pins follow your
-    account" footer. New optional props `frequentLimit`, `suggestions` (no-results chips), `searchHint`,
+    grid, a "Quick access" rail of `clamp(20rem, 30%, 26rem)` in a panel whose `maxWidth` defaults to
+    1080px (Pinned tiles, Frequently visited, Recent), "Pins follow your account" footer. The footer's
+    key hints are key caps (ENTER, ⌘ ENTER / CTRL ENTER, ESC, four arrows) and are hidden on touch devices. New optional props `frequentLimit`, `suggestions` (no-results chips), `searchHint`,
     `LauncherModule.isNew`, and labels `quickAccess`, `newBadge`, `screens`, `pinShort`, `footerNote`,
     `suggestionsHint`, `found`, `pinTip`, `unpinTip`. The rail landmark is named "Quick access".
     Keyboard: ←/→ and ↑/↓ are grid-aware (row-major, ↑/↓ cross sections), and `P` pins or unpins the
-    focused item (never while typing). New optional `openShortcutHint` (e.g. "⌘K or /", app-owned),
+    focused item (never while typing); ArrowUp from the first item returns to the search field and
+    pinned tiles are a 2-column grid. The keyboard-active row highlights as a whole (soft fill plus
+    one 1px inset ring, at least 3:1), the whole row is the link target (Cmd/middle-click opens a new
+    tab), and truncated titles, rail rows, pinned tiles, app names and search rows show a tooltip with
+    the full text. New optional `openShortcutHint` (e.g. "⌘K or /", app-owned),
     labels `hintOpenMenu` and `hintPin`; hint label defaults are lowercase and follow the canvas order.
   - `Kbd` / `KbdShortcut` — a key cap and a chord (`mod+k` renders ⌘ K or Ctrl K), in the
     `AppSwitcher` notation. `Search` and `AppSwitcher` render their shortcut hints with `Kbd`.
@@ -68,6 +74,48 @@ next major.
     `navigator.pdfViewerEnabled`. `PdfViewerProps` / `PdfViewerLabels` are now exported types.
   - Page examples: **App launcher** (`/examples/launcher`), **Wizard** (`/examples/wizard`),
     **Template editor** (`/examples/template-editor`).
+  - `Tag` `display="dot"` — an 8px tone dot plus plain label for quiet rows (`variant` and icons
+    are ignored; the dot ink is lifted to 3:1 on both canvases). `StatusTag` (+ `StatusTagProps`,
+    `StatusAppearance`) maps an app's status union to a `Tag` tone once; an unknown status renders
+    neutral and warns once in development. (HRMS #13)
+  - `Drawer` / `Modal` `portalChildren` — rendered **inside** the dialog content after the slots (not
+    a sibling in the portal, which Chakra would `aria-hide`), for nested dialogs and live regions;
+    a nested `AlertDialog` still portals out, stacks above and returns focus. (HRMS #20)
+  - `FormDrawer` (+ `FormDrawerProps`, `FormDrawerSection`, `FormDrawerLabels`) — a sectioned
+    create/edit form in a `Drawer`: `role="alert"` error summary focused after a failed submit,
+    sticky footer with a real `<form>` submit, discard-changes confirm on every close path while
+    `isDirty`, all close paths blocked while `isSubmitting`. (HRMS #14)
+  - `Table` row detail expander — `renderRowDetail(row)` (null = no chevron), `expandedRows` /
+    `onExpandedRowsChange` (uncontrolled when `expandedRows` is omitted). Chevron column after the
+    checkbox, full-width detail row; works with pagination, virtualisation, frozen columns and
+    grouped mode. The chevron is a button with `aria-expanded` / `aria-controls`. (HRMS #17)
+  - `EmptyState` `description` accepts a `ReactNode` — a string keeps today's styling, a node sits in
+    the same muted block above `action`. (HRMS #18)
+  - `QueryStateBoundary` `isForbidden` (boolean or `(error) => boolean`), `forbidden`
+    (`{ title, description, icon, action }`) and `hasData`; type `QueryStateForbiddenProps`. Order is
+    now loading (only when `!hasData`) → forbidden → error → empty → children; forbidden is a lock
+    `EmptyState` with `role="status"`. Defaults unchanged. (HRMS #21)
+  - `Tabs` link mode — `TabItem.href` and `TabsProps.linkAs`: when every item has an `href`, `Tabs`
+    renders a `<nav aria-label>` of links (same variants and sizes, no panels, not a tablist) with
+    `aria-current="page"` on `value`; modifier and middle clicks are never intercepted. (HRMS #19)
+  - `BulkSelectionBar` (+ `BulkAction`, `BulkActionTone`, `BulkSelectionBarProps`) — selection bar for
+    beside a `Table`: "{n} selected", facts about the whole selection, tone-ranked actions, clear,
+    `inline` or `sticky`, polite count announcement; renders nothing at 0. (HRMS #15)
+  - `SectionRail` (+ `RailSection`, `SectionRailProps`) — section navigation for long settings
+    screens: a vertical `nav` with `aria-current` and a dirty dot per section, collapsing to a
+    `Select` below `collapseBelow` (default `md`). (HRMS #16)
+  - `StatCard` `iconTone` (neutral / info / success / warning / error) paints the icon chip with the
+    soft tone; unset keeps today's brand-primary chip. (HRMS #23)
+  - `CircularProgress` (+ `CircularProgressProps`, `CircularProgressSize`) — SVG ring, sm/md/lg =
+    32/48/72px, `thickness`, `tone`, centred `label`, `role="progressbar"`. (HRMS #24)
+  - `CalendarGrid` (+ `CalendarEvent`, `CalendarGridProps`, `CalendarGridView`, `CalendarGridLabels`) —
+    a controlled month/week/day grid of date-granularity events: multi-day spans, "+N more" opens the
+    day, `role="grid"` with arrow/Home/End/Page keys, link or button chips in `Tag` tones, `locale`,
+    `weekStartsOn`, `isLoading`. (HRMS #25)
+  - `AudioRecorder` (+ `AudioRecorderProps`, `AudioRecorderLabels`) — microphone recorder: asks for
+    the mic on Start, mm:ss timer, `maxDurationSec` auto-stop, hands a `File` named for the recorded
+    mime to `onRecorded`, permission-denied and unsupported states, releases the mic on unmount.
+    (HRMS #26)
 
 - **Commerce kit** — the components for a shop front, designed mobile-first (Pebble principles:
   chromeless tonal cards, one loud action per view, selection never by colour alone). Product:
@@ -152,6 +200,16 @@ next major.
 - `Editor` binds Jodit's `change` / `blur` itself on every Jodit instance and renders Jodit only once
   its popup root exists (no throwaway first instance). Behaviour for existing props is unchanged.
 - `BreadcrumbItem.path` is optional (type widening).
+- **`Drawer` / `Modal` warn when they drop a child.** A child that is not a Header/Body/Footer slot
+  still renders nothing, but now logs a dev-only `console.warn` (once per child type) pointing at
+  `portalChildren`. (HRMS #20)
+- **`Table` `studio` variant on touch devices:** under `@media (pointer: coarse)` the row checkbox is
+  always visible and the row number is hidden, instead of a hover-only reveal. (HRMS #17)
+- **`ProfilePhotoViewer` re-syncs when `photoUrl` changes** (it used to seed on mount only), so
+  consumers can drop `key={photoUrl}`. A locally picked preview is replaced by the new URL — update
+  `photoUrl` only once an upload has finished. (HRMS #22)
+- **Page examples:** `records.tsx` uses `BulkSelectionBar` instead of the `Table`'s `headerActions`;
+  `settings.tsx` uses `SectionRail` instead of a hand-built section nav.
 
 - **`ProductCard` and `ProductDetails` are rewritten** — see Breaking below. `ProductCard` is a
   chromeless 4:5 card (grid / list / rail, swatch dots that swap the photo, quick-add sheet or
@@ -192,6 +250,15 @@ next major.
 
 ### Fixed
 
+- **`NavLauncher` keyboard and link fixes.** Arrow keys, typing and Backspace were dead on rail and
+  apps rows while a search was active; Enter could throw when results shrank; Enter during IME
+  composition opened a result; removing the focused row (e.g. an app dropped from `apps`) dropped
+  focus to the page body (it now moves to the neighbouring row, or the field).
+- **`Search` / `TextInput` / `Select` / `Textarea` / `NumberInput` / `FileUpload` / `PincodeChecker`
+  focus glow was transitioned in**, so a screenshot or accessibility check taken the instant a field
+  gained focus saw no ring. `FIELD_TRANSITION` no longer animates `box-shadow`; border-colour and
+  background transitions are unchanged and still honour reduced motion.
+
 - **`SideBar` rail controls now show a `:focus-visible` ring** (rows, submenu and flyout rows,
   `SecondaryBar`, collapse toggle, Add New, user footer, Collapse/Hide/Show, switch-app cells,
   overlay close) — WCAG 2.4.7 / 2.4.11.
@@ -370,8 +437,8 @@ next major.
   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
+  were only ever true in light mode. `segmentedTrackSurface` and `segmentedRestInk`
+  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
@@ -387,9 +454,11 @@ next major.
   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.
+  indicator: Button's own two-tone ring (halo plus brand band, at least 3:1 on any fill, light and
+  dark) on the track while a segment has keyboard focus (never after a mouse click).
+  `underlineSlide` has no track chrome, so there the
+  segment wears `focusVisibleStyles`. `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.

package/COMPONENT-GOTCHAS.md

@@ -177,6 +177,15 @@ is now the library's own themed component, with a real dual-thumb mode and a `ma
 
 **Apply:** "on vs off" is always `ToggleSwitch`; 2+ named options is always `SegmentedControl`.
 
+**`SegmentedControl`'s focus ring sits on the track, not the segment** (Button's two-tone ring). It is
+driven by a `:focus-visible` check in `onFocus`, so a mouse click stays ringless. `underlineSlide` has no
+track chrome, so its focused segment wears the ring instead.
+
+**A focus indicator must never be in a `transition` list.** The 0ms computed style is the transparent
+start value, so a screenshot or axe check taken on focus misses it. Field styles go through
+`FIELD_TRANSITION` (`Common/fieldStyles.ts`), which animates `border-color` and `background-color`
+only; keep `box-shadow` out of any transition you add around a field.
+
 **`SegmentedControl` and `Tabs` look near-identical and are not interchangeable.** They share the
 size scale and tokens, so `SegmentedControl variant="underlineSlide"` and `Tabs variant="line"`
 render almost the same picture, as do `variant="default"` and `Tabs variant="subtle"`. The
@@ -304,7 +313,7 @@ not enough when the overlay sits inside a transition wrapper — the wrapper kee
 | --- | --- | --- |
 | "Nothing here yet" with an optional action | `EmptyState` | Neutral placeholder |
 | A failed load with retry | `ErrorState` | `role="alert"`, `onRetry`/`isRetrying` built in |
-| One fetch that can be loading, failed, empty or ready | `QueryStateBoundary` | Picks for you: loading > error > empty > `children` |
+| One fetch that can be loading, forbidden, failed, empty or ready | `QueryStateBoundary` | Picks for you: loading > forbidden > error > empty > `children` |
 
 ---
 
@@ -421,6 +430,12 @@ renders a plain tag with no way to remove it.
 removable chip. `icon` alone (no `onIconClick`) is the decorative case — a plain right-side icon
 with no click affordance, aria-hidden.
 
+### `Tag display="dot"` ignores `variant` and icons; `StatusTag` renders an unknown status neutral
+
+`display="dot"` ignores `variant`, `icon`, `leadingIcon` and `onIconClick`. `StatusTag`'s `map` is
+keyed by your status union, but a runtime value outside it (API drift) renders a neutral chip and
+only warns in development — guard upstream if a silent neutral would mislead.
+
 ### A rounded box with `overflow: hidden` clips glyphs at the corners — never round the clipping element
 
 `border-radius` reshapes the overflow clip, so a pill-shaped element with `overflow: hidden`
@@ -457,20 +472,33 @@ popovers and menus now paint `colors.surfaceRaised` — identical `#ffffff` in l
 step up in dark. A custom panel, popover or `ModalContent bg=` in an app should read
 `surfaceRaised` too, and a divider inside it `raisedRule(colors)`.
 
-### `Drawer` / `Modal` / `ProfileCard` drop any child that isn't a named slot
+### `Drawer` / `Modal` / `ProfileCard` drop any child that isn't a named slot — use `portalChildren`
 
 All three match children by exact type (`child.type === XHeader/XBody/XFooter`) and render only
 those matches — nothing else in `children` is ever read. A sibling among the slots (a nested
-`Modal`, `AlertDialog`, a confirm dialog, a portal after the footer) silently never mounts. All
-three now unwrap **one** `<>...</>` level around a slot (so `<>{cond && <DrawerFooter>...}</>`
-still renders) and spread styling props (`padding`, `borderBottom`, `sx`, …) from the matched slot
-onto the real header/body/footer — a second nested fragment, or any other wrapper element, still
-drops the slot silently.
-
-**Apply:** put a confirm dialog **outside** the `Drawer`/`Modal`/`ProfileCard`, as a sibling in a
-wrapping fragment — never among the header/body/footer slots. When a ternary picks between bodies,
-branch into a variable rendered inside one body slot, rather than returning fragment-wrapped slots
-per branch. `Drawer`'s misspelled `vaiant` is `@deprecated` — use `variant`.
+`Modal`, `AlertDialog`, a confirm dialog, a live region) silently never mounts; `Drawer` and `Modal`
+now warn once per dropped child type in development, `ProfileCard` still says nothing. All three
+unwrap **one** `<>...</>` level around a slot (so `<>{cond && <DrawerFooter>...}</>` still renders)
+and spread styling props (`padding`, `borderBottom`, `sx`, …) from the matched slot onto the real
+header/body/footer — a second nested fragment, or any other wrapper element, still drops the slot
+silently.
+
+**Apply:** pass a nested confirm dialog, toast host or live region to `Drawer` / `Modal` as
+`portalChildren`. It renders **inside** the dialog content after the slots (a sibling in the portal
+would be `aria-hidden` by Chakra, so a live region there is never announced); a nested `AlertDialog`
+portals out on its own, stacks above and returns focus. It unmounts with the dialog, so reset its
+open state when the parent closes. `ProfileCard` has no such prop — keep its confirm dialog outside,
+as a sibling in a wrapping fragment. When a ternary picks between bodies, branch into a variable
+rendered inside one body slot, rather than returning fragment-wrapped slots per branch. `Drawer`'s
+misspelled `vaiant` is `@deprecated` — use `variant`.
+
+### `FormDrawer` has no browser validation, and its submit button sits outside the `<form>`
+
+It sets `noValidate`: validate in `onSubmit` and pass messages via `errors`. Error-summary focus
+fires only after a submit; if validation is async, set `isSubmitting` synchronously in `onSubmit` so
+focus waits for the result, otherwise errors that arrive later are not focused. The footer submit
+button is tied to the form with the `form` attribute — Enter-to-submit works in browsers, but
+jsdom / user-event does not simulate it, so use `fireEvent.submit(form)` in tests.
 
 ### `QueryStateBoundary` evaluates JSX `children` even while loading
 
@@ -478,11 +506,23 @@ JSX children are built before the boundary decides what to show, so `data.items.
 while `data` is still `undefined`. **Apply:** pass `children` as a function — `{() => <List
 items={data.items} />}` — whenever it reads data that may not exist yet.
 
+### `QueryStateBoundary` `isForbidden` and `hasData`
+
+An `isForbidden` function is only called when `error` is set (never with `undefined`); `isForbidden:
+true` shows the panel even with no error. `isLoading` + `hasData` keeps `children` visible during a
+refetch, so pass `hasData` only when data is genuinely loaded — otherwise a first load shows a blank
+region.
+
 ### `StatCard`'s delta colour follows `trend` vs `goodDirection`, not `trend` alone
 
 Green when `trend === goodDirection`, red otherwise — a falling cost with `goodDirection="down"` is
 green. Pass `onClick` for a clickable card (it renders its own `<button>`); never wrap it in one.
 
+### `CircularProgress` `tone="info"` is the brand primary, not blue
+
+Unlike `Tag` and `StatCard`, where `info` is blue, the default `tone="info"` here paints the brand
+primary scale. `aria-label` is required — the ring has no visible caption.
+
 ### A clickable `TextInput` icon is a real button — give it a name
 
 With `onRightIconclick`/`onLeftIconClick` the icon renders as a `<button>`. Without
@@ -562,6 +602,14 @@ accepted, typed, never called.
 **Apply:** leave at least one column without a `node`, or put an explicit control inside a `node`
 renderer instead of relying on row click.
 
+### `Table.renderRowDetail` runs for every row on every render, and `expandedRows` ids match strictly
+
+It decides whether each row gets a chevron, so an inline function re-renders every row (defeating
+`TableRow`'s memo) — wrap it in `useCallback` / `useMemo`. `expandedRows` ids compare with `===`, so
+`1` and `"1"` are different: keep the id type the same as `row.id`. It is not the older
+`row.content` + `isContent` expander (chevron before the checkbox, index-based); both can coexist,
+but only `row.content` still disables grouped virtualisation.
+
 ### `error` without `errorMessage` renders the literal word "Error" — and erases `helperText`
 
 Every field that shows validation errors (`TextInput`, `InputTextArea`, `Select`, `MultiSelect`,
@@ -1246,9 +1294,22 @@ the `Search` listeners see it — otherwise the first mounted `Search` takes Ctr
 - **`NavLauncher` `suggestions` empty falls back to `noResultsHint`** instead of showing chips.
 - **`PinToggle` / `NewTabLink` are opacity 0 until row hover or focus-within**, so a consumer's own row must carry `data-group` (or `role="group"`) to reveal them.
 - **`LauncherLabels.screensGroup` is unused** by search now (sections replaced the flat group); kept so label objects still type-check.
+- **`apps` is data-driven.** Gate by plan by changing the array or setting `locked` / `lockedReason`;
+  keep `id`s stable (hues and `key` derive from them), and pass `color` on an app whose mark must not
+  shift when siblings are added or removed. Locked rows are not links, not focusable, `aria-disabled`,
+  tooltip = `lockedReason`. Pass `appsVisibility="always"` to show them above `md`.
+- **Never use `:has()` in an emotion style.** jsdom's (nwsapi) `getComputedStyle` can throw ("not a valid selector") and takes every consumer test that opens a
+  Drawer down with it. The launcher marks row focus with a `data-row-focus` attribute instead. If you
+  hit that error in your own tests on a newer jsdom, report it with the selector.
+- **Launcher rows are CSS containers** (`container-type: inline-size`, name `launcher-row`); jsdom
+  drops `@container` rules, so tests assert the style objects (`titleInset`, `WIDE_ROW`), not the
+  stylesheet.
+- **A search row without `href` (an action with `run`) cannot open in a new tab:** any click, with or
+  without Cmd/Ctrl, runs it and closes the launcher, same as Enter.
 - **`LauncherTrigger` does not bind its shortcut**; `shortcut={null}` removes the hint and
   `aria-keyshortcuts`. An explicit `aria-label` hides the visible label from assistive tech, so keep
-  the visible text inside the label (WCAG 2.5.3).
+  the visible text inside the label (WCAG 2.5.3). `display="icon"` has no visible text: the label is
+  its accessible name and tooltip.
 
 ### `Header`'s desktop submenus open on hover only — no keyboard or click trigger
 
@@ -1316,16 +1377,56 @@ error, no warning, `scrollTop` on a non-scrolling parent just stays `0` forever.
 **Apply:** `ScrollToTop`'s JSX parent must be the actual scroll container, or pass `useWindow` when
 the page itself scrolls.
 
-### `ProfilePhotoViewer`'s PDF detection breaks the moment a file is picked, and `photoUrl` is read once
+### `ProfilePhotoViewer`'s PDF detection breaks the moment a file is picked, and a new `photoUrl` discards the preview
 
 PDF detection is a literal `.endsWith(".pdf")` check — picking a file through the built-in editor
 replaces the value with a base64 data URI that never ends in `.pdf`, so a freshly-picked PDF renders
 as a broken image instead of the intended file badge (only the original URL prop is detected
-correctly). Separately, `photoUrl` only seeds state at mount — a later re-render with a new
-`photoUrl` (list virtualization, route change without remount) keeps showing the old photo.
+correctly). Separately, a changed `photoUrl` re-syncs the component and replaces any locally picked
+preview (a same-URL re-render keeps it), so a parent that updates `photoUrl` before the upload has
+finished makes the preview vanish mid-upload.
 
 **Apply:** don't use the built-in edit flow for PDF documents; detect kind from `File.type` in your
-own handler instead. Use `key={photoUrl}` to force a remount when the photo identity changes.
+own handler instead. Update `photoUrl` only once the upload has finished. `key={photoUrl}` is no
+longer needed.
+
+### `Tabs` link mode needs `href` on every item, and has no default current item
+
+One item without `href` makes the whole thing a normal tablist and `href` is ignored everywhere (a
+dev-only `console.warn` is the only signal). Button tabs select the first enabled item when `value`
+is missing; link tabs mark nothing `aria-current` until you pass `value`. A plain left-click calls
+`onChange` but never `preventDefault`s; modifier and middle clicks only open the link. `isDisabled`
+link items render as a non-link `span`.
+
+**Apply:** `Tabs items=[{ id, label, href }] linkAs={RouterLink} value={currentId}` with `value`
+derived from the route, and never hand-build `Box as={Link}` tabs.
+
+### `BulkSelectionBar` renders nothing at `selectedCount` 0, and `sticky` needs a scroll ancestor
+
+With no persistent live region it announces count changes itself (the node mounts empty and fills in
+an effect), so don't also announce from your own region. `placement="sticky"` pins only inside an
+ancestor scroll container — an ancestor with `overflow: hidden` silently disables it. Combining it
+with `Table`'s `headerActions` gives two action sets for one selection.
+
+### `SectionRail` chooses rail vs `Select` with `matchMedia` at render time
+
+It renders the rail when `matchMedia` is missing (SSR). In the `Select` branch a dirty section's
+option reads `"Label (dirtyHint)"` — a native `<option>` cannot hold a dot.
+
+### `CalendarGrid` is fully controlled, ignores time of day, and `renderDayCell` turns multi-day bars off
+
+Without `onDateChange` / `onViewChange` the toolbar's Today/Prev/Next and the view switcher are
+hidden and arrow keys stop at the edge of the visible range, so the grid looks static — wire both.
+`start` / `end` are read as local calendar dates (`end` inclusive): a UTC-midnight `Date` shows the
+previous day in a negative-offset zone, so build date-only values with `new Date(y, m, d)`.
+`renderDayCell` replaces each cell's chips wholesale: a 3-day event is passed to it for all 3 days
+but is no longer drawn as one bar, and `onEventClick` never fires from your own content.
+
+### `AudioRecorder` needs a secure context, and `onRecorded` is not called after unmount
+
+`getUserMedia` is undefined on plain http (except localhost), so the component shows its
+"unsupported" state there, not "permission denied". A parent that navigates away mid-recording gets
+no `onRecorded` call (the mic is released instead), and an empty recording never calls it either.
 
 ### `FilePreview` infers file kind from `fileName`, not `fileUrl`, and never resets zoom/rotation on its own
 

package/DESIGN-GUIDE.md

@@ -45,7 +45,7 @@ Borders are the one px value: `borderWidth="1px"`. Fixed widths (side panel, lis
 | Section / card title | `Heading as="h2" fontSize="md" fontWeight={600} color={colors.header[900]}`, in `Card`'s `header` prop |
 | Body | `Text fontSize="sm" color={colors.text[800]}` |
 | Label / meta / helper | `Text fontSize="xs" color={colors.textMuted}` |
-| KPI tile | `StatCard` — pass `trend` and `goodDirection`; the delta is green when the change is *good* (a shorter sales cycle is green) |
+| KPI tile | `StatCard` — pass `trend` and `goodDirection`; the delta is green when the change is *good* (a shorter sales cycle is green); `iconTone` tints the icon chip (unset = brand primary) |
 | Numbers in tables/columns | `sx={{ fontVariantNumeric: "tabular-nums" }}` so digits align; `Table` columns take `align: "end"` |
 | Overline (rare) | `fontSize="xs" fontWeight={600} textTransform="uppercase" letterSpacing="0.06em"` |
 
@@ -69,7 +69,7 @@ stay light in dark mode.
 | Secondary text, icons | `colors.textMuted` |
 | Brand-colored text/link | `colors.accentText` — never `primary[500]` |
 | Status text/icon | `colors.semanticText.success \| error \| warning \| info` |
-| Status chip | `<Tag label="Won" colorScheme="green" />` (subtle, `sm` by default) — never a painted `Box`. Tone → `colorScheme`: success `green`, warning `orange`, error `red`, info `blue`, neutral `gray` |
+| Status chip | `<Tag label="Won" colorScheme="green" />` (subtle, `sm` by default) — never a painted `Box`. Tone → `colorScheme`: success `green`, warning `orange`, error `red`, info `blue`, neutral `gray`. Quiet rows: `<Tag tone="success" display="dot" label=… />`; map an app's status vocabulary once with `<StatusTag status map label display />` |
 | Selectable list row (inbox, picker) | `listRowBackgrounds(colors)` for hover/selected + `sx={focusVisibleStyles(colors)}`; pad the list `p={2}` so the ring isn't clipped |
 | Any filled surface you paint | `resolveFilledSurface(colors.<scale>, colors)` → `{ fill, color }` |
 | Icon tint chip, avatar tint | `bg={colors.primary.opacity[8]}` + `color={colors.accentText}` (`opacity` exists on `primary`/`secondary`/`tertiary` only) |
@@ -154,6 +154,12 @@ sections are `Card` with the title in `header`.
 | A person: avatar + name (+ role/email, presence, remove) | `PersonChip` (`orientation="vertical"` for a stacked profile block) |
 | An avatar on its own, or a stack of them | `Avatar` / `AvatarGroup` — never pick the fill, it is derived from `name` |
 | Unsaved-changes bar | `SaveBar isOpen={isDirty} onSave onDiscard isSaving` |
+| Create / edit a record in a side panel | `FormDrawer` (`sections`, `errors`, `isDirty`, `isSubmitting`) — don't hand-assemble Drawer + footer + discard confirm. A nested confirm dialog in any `Drawer` / `Modal` goes in `portalChildren` |
+| Detail or sub-table under a table row | `Table renderRowDetail` (+ optional `expandedRows`) — don't put an Accordion outside the Table |
+| Tabs that navigate between routes | `Tabs items=[{ id, label, href }] linkAs={RouterLink} value={currentId}` — never hand-build `Box as={Link}` tabs |
+| Completion / capacity ring | `CircularProgress` (`ProgressBar` stays for linear) |
+| Per-day activity (leave, tasks, shifts) | `CalendarGrid` with `events` mapped from your data — don't hand-roll a month grid |
+| Voice note capture | `AudioRecorder`; `MediaAudioPlayer` for playback |
 | Previewing an attachment (image, video, audio, PDF, Office, text, archive) | `MediaViewer` (`items`, `isOpen`, `onClose`) — omit `index` and it owns navigation itself |
 | Notification tray | `NotificationBell` (badge, needs `aria-label`) opening a `NotificationPanel` (zones, filters, all four states) |
 | Confirm that needs the name typed to arm it | `ConfirmDialog confirmationText="delete-me"` — `onConfirm` does **not** close; call `onClose` yourself |
@@ -178,14 +184,19 @@ scrim `Box`. `Loading` is the older API and stays on the heavier house scrim by
 - Pins live in the app (server or local). Pass them to `NavLauncher` (`pinnedIds`, `onTogglePin`) *and*
   to `SideBar pinnedItems` + `onUnpin` so the rail shows what the launcher pinned. Persist collapse with
   `useSidebarPrefs`, and pass `autoCollapse={false}` if the app, not the rail, decides.
+- Replacing a 9-dot app switcher in a nav bar: `<LauncherTrigger display="icon" />` (36px) in `moreIcon`;
+  keep the chip variant (`leading`) where there is room.
+- Show the suite's apps with `appsVisibility="always"` and drive plan gating by editing `apps` /
+  `locked`.
 - Show shortcut hints with `KbdShortcut`, never a hand-styled `<kbd>`.
 
 ## 7. Every page has four states
 
 Design all four, not just the happy path.
 
-`QueryStateBoundary` picks one per content region (loading > error > empty > data). Pass `children`
-as a function when it reads data that may still be undefined.
+`QueryStateBoundary` picks one per content region (loading > no access > error > empty > data). Pass
+`children` as a function when it reads data that may still be undefined. `isForbidden` shows the
+no-access panel between loading and error; `hasData` keeps content on screen during a refetch.
 
 | State | Render |
 | --- | --- |
@@ -228,9 +239,9 @@ not shipped in this package). Start from the closest one:
 | Screen you're building | Reference | Shows |
 | --- | --- | --- |
 | Dashboard / overview | `dashboard.tsx` | `StatCard` row, chart `Card`, stage list with `ProgressBar`, task list, `QueryStateBoundary` |
-| List of records | `records.tsx` | saved views, `FilterBar`, `Table` (`isGlobalSearch={false}`, `Tag` cells), bulk actions, `AlertDialog tone="danger"`, create `Drawer` |
+| List of records | `records.tsx` | saved views, `FilterBar`, `Table` (`isGlobalSearch={false}`, `Tag` cells, row selection), `BulkSelectionBar` (count, facts, ranked actions, clear), `AlertDialog tone="danger"`, create `Drawer` |
 | One record | `recordDetail.tsx` | `PageHeader` with breadcrumbs/avatar/meta, `Tabs` (declarative `items` with `count` badges), `DescriptionList` (grid + inline side panel), `Timeline` (per-event `icon`/`description`), `ErrorState` + back |
-| Settings / long form | `settings.tsx` | section nav, `SettingsSection` + `SettingRow`, `SaveBar`, danger zone |
+| Settings / long form | `settings.tsx` | `SectionRail` (rail from `lg`, `Select` below, dirty dots), `SettingsSection` + `SettingRow`, `SaveBar`, danger zone |
 | Board | `pipeline.tsx` | `KanbanBoard` with custom cards and column totals (`height`/`maxH` to size it) |
 | Inbox / master–detail | `inbox.tsx` | selectable list rows, conversation pane, composer, mobile list↔detail |
 | App launcher (browse, pins, recents, search with actions) | `launcher.tsx` (`/examples/launcher`) | `NavLauncher` + `LauncherTrigger` in `NavigationBar leading`, app-owned registry and permission filter, pinned / frequent / recent ids, `linkAs`, remote results via `extraResults`, `isLoading`, `SideBar pinnedItems` |

package/dist/Components/AudioRecorder/AudioRecorder.d.ts

@@ -0,0 +1,8 @@
+import type { AudioRecorderProps } from "./AudioRecorderProps";
+export declare const formatElapsed: (ms: number) => string;
+export declare const recordingFileName: (mime: string, now: number) => {
+    type: string;
+    name: string;
+};
+declare const AudioRecorder: ({ onRecorded, maxDurationSec, isDisabled, labels }: AudioRecorderProps) => import("react/jsx-runtime").JSX.Element;
+export default AudioRecorder;

package/dist/Components/AudioRecorder/AudioRecorder.js

@@ -0,0 +1,169 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recordingFileName = exports.formatElapsed = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const react_2 = require("@chakra-ui/react");
+const Button_1 = __importDefault(require("../Button/Button"));
+const useCustomTheme_1 = require("../../Theme/useCustomTheme");
+const DEFAULT_LABELS = {
+    start: "Start recording",
+    stop: "Stop recording",
+    recording: "Recording",
+    recorded: "Recorded",
+    permissionDenied: "Microphone access was denied. Allow it in your browser settings and try again.",
+    unsupported: "Audio recording is not supported in this browser.",
+};
+const PREFERRED_MIME = "audio/webm";
+const TICK_MS = 250;
+const EXTENSIONS = {
+    "audio/webm": "webm",
+    "audio/wav": "wav",
+    "audio/wave": "wav",
+    "audio/x-wav": "wav",
+    "audio/ogg": "ogg",
+    "audio/mp4": "m4a",
+    "audio/mpeg": "mp3",
+};
+const formatElapsed = (ms) => {
+    const total = Math.floor(ms / 1000);
+    return `${String(Math.floor(total / 60)).padStart(2, "0")}:${String(total % 60).padStart(2, "0")}`;
+};
+exports.formatElapsed = formatElapsed;
+const recordingFileName = (mime, now) => {
+    var _a, _b;
+    const type = mime.split(";")[0].trim().toLowerCase() || PREFERRED_MIME;
+    return { type, name: `recording-${now}.${(_a = EXTENSIONS[type]) !== null && _a !== void 0 ? _a : (((_b = type.split("/")[1]) === null || _b === void 0 ? void 0 : _b.replace(/^x-/, "")) || "webm")}` };
+};
+exports.recordingFileName = recordingFileName;
+const isSupported = () => { var _a; return typeof navigator !== "undefined" && !!((_a = navigator.mediaDevices) === null || _a === void 0 ? void 0 : _a.getUserMedia) && typeof MediaRecorder !== "undefined"; };
+const AudioRecorder = ({ onRecorded, maxDurationSec, isDisabled = false, labels }) => {
+    const { colors } = (0, useCustomTheme_1.useCustomTheme)();
+    const text = { ...DEFAULT_LABELS, ...labels };
+    const [status, setStatus] = (0, react_1.useState)("idle");
+    const [elapsedMs, setElapsedMs] = (0, react_1.useState)(0);
+    const [announcement, setAnnouncement] = (0, react_1.useState)("");
+    const recorderRef = (0, react_1.useRef)(null);
+    const streamRef = (0, react_1.useRef)(null);
+    const chunksRef = (0, react_1.useRef)([]);
+    const timerRef = (0, react_1.useRef)(null);
+    const startedAtRef = (0, react_1.useRef)(0);
+    const mountedRef = (0, react_1.useRef)(true);
+    const startingRef = (0, react_1.useRef)(false);
+    const onRecordedRef = (0, react_1.useRef)(onRecorded);
+    const textRef = (0, react_1.useRef)(text);
+    onRecordedRef.current = onRecorded;
+    textRef.current = text;
+    const release = (0, react_1.useCallback)(() => {
+        var _a;
+        if (timerRef.current !== null)
+            clearInterval(timerRef.current);
+        timerRef.current = null;
+        (_a = streamRef.current) === null || _a === void 0 ? void 0 : _a.getTracks().forEach((track) => track.stop());
+        streamRef.current = null;
+        recorderRef.current = null;
+    }, []);
+    (0, react_1.useEffect)(() => {
+        mountedRef.current = true;
+        if (!isSupported())
+            setStatus("unsupported");
+        return () => {
+            mountedRef.current = false;
+            const recorder = recorderRef.current;
+            if (recorder) {
+                recorder.ondataavailable = null;
+                recorder.onstop = null;
+                recorder.onerror = null;
+                if (recorder.state !== "inactive") {
+                    try {
+                        recorder.stop();
+                    }
+                    catch {
+                        // NOTE: a recorder the browser already tore down throws on stop.
+                    }
+                }
+            }
+            release();
+        };
+    }, [release]);
+    const stop = (0, react_1.useCallback)(() => {
+        const recorder = recorderRef.current;
+        if (recorder && recorder.state !== "inactive")
+            recorder.stop();
+    }, []);
+    const start = (0, react_1.useCallback)(async () => {
+        var _a, _b;
+        if (startingRef.current)
+            return;
+        if (!isSupported()) {
+            setStatus("unsupported");
+            return;
+        }
+        startingRef.current = true;
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+            if (!mountedRef.current) {
+                stream.getTracks().forEach((track) => track.stop());
+                return;
+            }
+            streamRef.current = stream;
+            chunksRef.current = [];
+            const useWebm = (_b = (_a = MediaRecorder.isTypeSupported) === null || _a === void 0 ? void 0 : _a.call(MediaRecorder, PREFERRED_MIME)) !== null && _b !== void 0 ? _b : false;
+            const recorder = new MediaRecorder(stream, useWebm ? { mimeType: PREFERRED_MIME } : undefined);
+            recorderRef.current = recorder;
+            recorder.ondataavailable = (event) => {
+                if (event.data.size > 0)
+                    chunksRef.current.push(event.data);
+            };
+            recorder.onerror = () => {
+                release();
+                setStatus("idle");
+            };
+            recorder.onstop = () => {
+                const duration = Date.now() - startedAtRef.current;
+                const { type, name } = (0, exports.recordingFileName)(recorder.mimeType || PREFERRED_MIME, Date.now());
+                const file = new File(chunksRef.current, name, { type });
+                release();
+                setStatus("idle");
+                setElapsedMs(duration);
+                setAnnouncement(`${textRef.current.recorded} ${(0, exports.formatElapsed)(duration)}`);
+                if (file.size > 0)
+                    onRecordedRef.current(file);
+            };
+            recorder.start();
+            startedAtRef.current = Date.now();
+            setElapsedMs(0);
+            setStatus("recording");
+            setAnnouncement(textRef.current.recording);
+            timerRef.current = setInterval(() => {
+                const elapsed = Date.now() - startedAtRef.current;
+                if (maxDurationSec !== undefined && elapsed >= maxDurationSec * 1000) {
+                    setElapsedMs(maxDurationSec * 1000);
+                    stop();
+                    return;
+                }
+                setElapsedMs(elapsed);
+            }, TICK_MS);
+        }
+        catch (error) {
+            release();
+            if (!mountedRef.current)
+                return;
+            const name = error === null || error === void 0 ? void 0 : error.name;
+            setStatus(name === "NotFoundError" ? "unsupported" : "denied");
+        }
+        finally {
+            startingRef.current = false;
+        }
+    }, [maxDurationSec, release, stop]);
+    const isRecording = status === "recording";
+    const blocked = status === "unsupported";
+    return ((0, jsx_runtime_1.jsxs)(react_2.Box, { children: [(0, jsx_runtime_1.jsxs)(react_2.Flex, { align: "center", gap: 3, children: [(0, jsx_runtime_1.jsx)(Button_1.default, { label: isRecording ? text.stop : text.start, size: "sm", colorScheme: isRecording ? "red" : undefined, variant: isRecording ? "solid" : "outline", "aria-pressed": isRecording, isDisabled: isRecording ? false : isDisabled || blocked, onClick: isRecording ? stop : () => void start() }), isRecording ? ((0, jsx_runtime_1.jsxs)(react_2.Flex, { align: "center", gap: 2, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { "data-testid": "audio-recorder-dot", boxSize: "0.5rem", borderRadius: "full", bg: colors.semanticText.error, "aria-hidden": true, sx: {
+                                    "@media (prefers-reduced-motion: no-preference)": { animation: "audio-recorder-pulse 1.2s ease-in-out infinite" },
+                                    "@keyframes audio-recorder-pulse": { "0%, 100%": { opacity: 1 }, "50%": { opacity: 0.35 } },
+                                } }), (0, jsx_runtime_1.jsx)(react_2.Text, { as: "span", role: "timer", fontSize: "0.875rem", color: colors.header[900], sx: { fontVariantNumeric: "tabular-nums" }, children: (0, exports.formatElapsed)(elapsedMs) })] })) : null] }), (0, jsx_runtime_1.jsx)(react_2.VisuallyHidden, { role: "status", "aria-live": "polite", children: announcement }), status === "denied" || status === "unsupported" ? ((0, jsx_runtime_1.jsx)(react_2.Text, { role: "alert", mt: 1, fontSize: "0.75rem", color: colors.semanticText.error, children: status === "denied" ? text.permissionDenied : text.unsupported })) : null] }));
+};
+exports.default = AudioRecorder;

package/dist/Components/AudioRecorder/AudioRecorderProps.d.ts

@@ -0,0 +1,20 @@
+/** Visible text and announcements; every key falls back to English. */
+export type AudioRecorderLabels = {
+    start: string;
+    stop: string;
+    recording: string;
+    /** Announced when a recording finishes, followed by its duration. */
+    recorded: string;
+    permissionDenied: string;
+    unsupported: string;
+};
+/** Props for the microphone recorder: one toggle button, a timer, and a `File` on stop. */
+export interface AudioRecorderProps {
+    /** Receives the finished recording; never called for an empty one or after unmount. */
+    onRecorded: (file: File) => void;
+    /** Stops the recording by itself after this many seconds. No limit when omitted. */
+    maxDurationSec?: number;
+    /** Blocks Start only; a recording already in progress can always be stopped. */
+    isDisabled?: boolean;
+    labels?: Partial<AudioRecorderLabels>;
+}

package/dist/Components/AudioRecorder/AudioRecorderProps.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/Components/BulkSelectionBar/BulkSelectionBar.d.ts

@@ -0,0 +1,3 @@
+import type { BulkSelectionBarProps } from "./BulkSelectionBarProps";
+declare const BulkSelectionBar: ({ selectedCount, facts, actions, onClearSelection, clearLabel, countLabel, placement, "aria-label": ariaLabel, "data-testid": testId, }: BulkSelectionBarProps) => import("react/jsx-runtime").JSX.Element | null;
+export default BulkSelectionBar;