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

package/CHANGELOG.md

@@ -24,18 +24,44 @@ next major.
     with actions and remote groups, optional suite-apps section below `md`), with `PinToggle`,
     `NewTabLink`, `searchLauncher`, `searchLauncherSections` (sectioned search: modules, then their
     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`
+    star, shown with the ↗ link on row hover/focus only (always on touch); pinned rail items are tiles. It never opens itself or binds a global chord (Cmd/Ctrl+K and `/` only refocus its field while it is open). `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`,
+    `NavLauncher` follows canvas `Launcher.dc.html`: from `lg` up, stacked sections with "(n)" counts and a
+    1/2/3-column grid beside a "Quick access" rail of `clamp(20rem, 30%, 26rem)` in a panel whose `maxWidth`
+    defaults to 1080px (Pinned tiles, Frequently visited, Recent). Below `lg` (phone and tablet) the body is a
+    Menu / Quick access / Apps tab bar (labels `tabsLabel`, `tabMenu`, `tabQuickAccess`, `tabApps`; Apps follows
+    `appsVisibility`) above one scrolling panel with only the selected panel mounted, rows are 44px, and search
+    keeps the stacked results plus rail with no tab bar. The header is the search field (fills the row; 44px at
+    `md`+, 40px below, 16px type), a muted live result count (`labels.resultsCount`, with a separate polite
+    announcement), optional `headerActions` (an app's own icon button) and close; there is no "Menu" pill and
+    `labels.title` names the dialog and the results list. "Pins follow your account" footer; its key hints
+    are key caps (arrows, ENTER, ⌘ ENTER / CTRL ENTER, ⌘ + click, P, ESC) and are hidden on touch devices
+    (`labels.hintClickNewTab`; the ↗ link's tooltip is `labels.newTabTip`, `NewTabLink` takes `tip`). 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),
-    labels `hintOpenMenu` and `hintPin`; hint label defaults are lowercase and follow the canvas order.
+    Keyboard: in the field, the first result is active as soon as there is a query, ↑/↓ follow the
+    visual rows of the result grid, → at the end of the text enters the grid and ←/→/Home/End then move
+    through results until the query changes, and PageUp/PageDown page; Esc clears the query first and
+    closes only when it is empty; Cmd/Ctrl+K and `/` focus the field. In lists ←/→ and ↑/↓ are grid-aware
+    (row-major, ↑/↓ cross sections), Home/End/PageUp/PageDown work, `P` pins or unpins the focused item
+    (never while typing) and typing anywhere else in the launcher refocuses the field; ArrowUp from the
+    first item returns to the search field (or the selected tab) and pinned tiles are a 2-column grid
+    (3 in the tablet Quick access tab). 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 label `hintPin`; hint label defaults are lowercase and follow the canvas order.
+    `LauncherLabels` gained required keys (`hintClickNewTab`, `newTabTip`, `resultsCount`, `tabsLabel`,
+    `tabMenu`, `tabQuickAccess`, `tabApps`): a consumer that types a full `LauncherLabels` object needs
+    them, while the `labels` prop (`Partial<LauncherLabels>`) is unaffected. Consumer tests: below `lg`
+    the Quick access and Apps sections are behind their tabs, and the dialog's accessible name now comes
+    from a visually hidden "Menu" heading.
+  - `OrgSwitcher` `display` (`"full"` default | `"avatar"` | `"auto"`) — `"avatar"` is a 36px avatar plus
+    chevron trigger whose accessible name is `Switch organization, <name>` with the name in a tooltip;
+    `"auto"` is avatar below `md` and full from `md` up. Types `OrgSwitcherProps`, `OrgSwitcherSize` and
+    `OrgSwitcherDisplay` are now exported from the package root.
   - `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`.
   - `NavigationBar` `leading` — a slot between the sidebar toggle/back button and the title, outside
@@ -68,6 +94,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 +220,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 +270,21 @@ next major.
 
 ### Fixed
 
+- **`NavigationBar` right cluster no longer overflows onto the avatar at phone widths.** The title
+  truncates first (overflow-only tooltip when it is a string); the `moreIcon` cluster can shrink, while
+  the sidebar toggle, back button and avatar menu never do. (HRMS, beta.60 launcher trigger overflow)
+- **`OrgSwitcher` trigger shrinks and its menu fits the screen.** The full trigger truncates its label
+  (avatar and chevron are kept) when its container is short, and the menu panel is capped at
+  `100vw - 32px`, so a long org name no longer causes horizontal page scroll on phones.
+- **`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 +463,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 +480,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.
@@ -422,6 +517,8 @@ next major.
 
 Nothing is removed yet — each of these still ships its full implementation.
 
+- `NavLauncher` `openShortcutHint` and `LauncherLabels.hintOpenMenu` — no longer rendered (the launcher
+  is already open when its footer shows); bind the open chord in the app only.
 - `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

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`,
@@ -1013,6 +1061,18 @@ reach it.
 **Apply:** don't depend on `onChange` firing for a repeat pick. There's no supported way to attach
 test hooks or a ref to the trigger.
 
+### `OrgSwitcher display="full"` still squeezes the navbar title on phones — use `display="auto"`
+
+Inside a `NavigationBar` `moreIcon` cluster, a full trigger needs about 88px (avatar + chevron) even
+when its label truncates to nothing, and the title is the first thing to give way. With a long org name
+the title is invisible on 320-375px bars, and a smaller `maxWidth` does not change that.
+
+**Apply:** `display="auto"` (avatar + chevron below `md`, full from `md`) or `"avatar"`. In avatar mode
+the accessible name is `${ariaLabel}, ${org name}` and the name appears in a tooltip that wraps a
+`span` around the trigger, so don't pass the trigger a ref. `auto` falls back to `"full"` where
+`matchMedia` is missing (SSR, jsdom). `NavigationBar`'s `moreIcon` root is `min-width: 0`: give your
+own icon buttons `flexShrink={0}` and let any label truncate.
+
 ### `UpgradeButton`'s gold icon accent silently falls back to the label color on low contrast
 
 The gold accent is only used when it clears AA contrast against both gradient stops; a custom
@@ -1222,7 +1282,8 @@ Each mounted `Search` registers its own `window` Ctrl+K listener, so two on one
 keypress. **Apply:** pass `shortcut={false}` on all but one. `showShortcutHint={false}` only hides
 the hint; the listener stays.
 
-The same applies to a launcher: `NavLauncher` and `LauncherTrigger` bind no chord, and the library
+The same applies to a launcher: `NavLauncher` and `LauncherTrigger` bind no chord to *open* (once open,
+the launcher uses Cmd/Ctrl+K and `/` only to refocus its own field), and the library
 reserves `mod+k` for the app's own palette. The app must pass `shortcut={false}` on every page
 `Search`, or claim the chord in capture phase (`keydown` on `window` with `capture: true`) before
 the `Search` listeners see it — otherwise the first mounted `Search` takes Ctrl+K.
@@ -1240,15 +1301,52 @@ the `Search` listeners see it — otherwise the first mounted `Search` takes Ctr
   anchor is an `aria-hidden`, `tabIndex={-1}` overlay (so copy-link and mod-click work) and pin / ↗
   are `aria-hidden` siblings. Screen readers use Enter / mod+Enter. Do not nest links inside the
   option — axe `nested-interactive` fails.
-- **The apps section decides "compact" with `matchMedia("(min-width: 48em)")`** and falls back to
-  desktop (hidden) where `matchMedia` is missing (SSR, jsdom). Tests must stub it to see the section.
-- **`P` on a focused NavLauncher row pins it** instead of starting type-ahead; in the search field it types the letter. Rows without a star (Recent, key screens, apps) keep type-ahead.
+- **The apps section decides "compact" with `matchMedia("(min-width: 48em)")`, the layout with
+  `(min-width: 62em)`** (`lg`). Both fall back to desktop (apps hidden, two panes) where `matchMedia`
+  is missing (SSR, jsdom), so tests must stub both to see the apps section or the tab bar.
+- **Below `lg` only the selected tab's panel is mounted.** Pinned / Frequently visited / Recent
+  (Quick access tab) and the apps list (Apps tab) are not in the DOM until their tab is clicked; the
+  Quick access tab is omitted when it would be empty, and a single remaining tab hides the bar. The
+  search view is different: no tab bar, stacked results plus the Quick access rail. A phone or tablet
+  consumer test that looks for an app or a pin must click the tab first.
+- **`P` on a focused NavLauncher row pins it.** Any other printable key pressed on a row, tab or
+  button (not Space, no modifier) is appended to the query and focuses the field; in the field `P`
+  types the letter.
+- **Esc is handled by the launcher, not the Drawer** (`closeOnEsc` is off): it clears a non-empty
+  query and keeps focus in the field, and closes only when the query is empty. The keydown is stopped inside
+  the launcher, so a consumer `Escape` listener on `document` never sees it.
+- **`headerActions` text joins the dialog's accessible name** (header content becomes part of it,
+  as the search value already does: "Menu leave"). Use icon-only buttons with an `aria-label`.
+- **The result count is `aria-hidden`; the announcement is a separate visually hidden `aria-live="polite"`
+  node, deliberately not `role="status"`**, so `getByRole("status")` still matches only the no-results
+  message and the loading skeleton.
+- **Left/Right/Home/End in the search field edit the caret** until a result has been navigated by
+  arrow/Page keys (→ at the end of the text enters the grid); any change to the query hands them back
+  to the caret. Do not "fix" this by binding them to results.
 - **`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.
+- **`LauncherLabels` gained required keys** (`hintClickNewTab`, `newTabTip`, `resultsCount`, `tabsLabel`,
+  `tabMenu`, `tabQuickAccess`, `tabApps`). The `labels` prop is `Partial<LauncherLabels>` and is fine;
+  a consumer that annotates a *full* `LauncherLabels` object fails to compile.
+- **`openShortcutHint` and `labels.hintOpenMenu` are deprecated no-ops:** the open chord is no longer
+  shown in the footer. Drop them; the footer's hints are arrows, ENTER, ⌘ ENTER, ⌘ + click, P, ESC.
+- **`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 +1414,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 |
@@ -174,18 +180,31 @@ scrim `Box`. `Loading` is the older API and stays on the heavier house scrim by
   unknown, `linkAs` for the router link, and `extraResults` + `isSearching` for remote (entity) results.
 - Open the launcher with `<NavigationBar leading={<LauncherTrigger onClick isOpen />} />` — never inside
   `navigationBarText.text`. Neither component binds the chord: the app owns the `mod+k` listener
-  (capture phase) and passes `shortcut={false}` to any page `Search`.
+  (capture phase) and passes `shortcut={false}` to any page `Search`. Bind it to *open* the launcher only:
+  once open, the launcher refocuses its own field on Cmd/Ctrl+K and `/`, and shows no open-chord hint
+  (`openShortcutHint` is deprecated).
 - 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.
+- In a phone-width app bar use `<OrgSwitcher display="auto" />` (avatar below `md`) next to the bell,
+  `LauncherTrigger display="icon"` and the avatar menu; keep every icon control 36px or less and
+  `flexShrink={0}`. The title truncates first.
+- Below `lg` the launcher is a Menu / Quick access / Apps tab bar over one panel (search stays a single
+  stacked list), so design for phone and tablet with that structure, not a long scroll. Pass
+  `headerActions` for the app's own icon button (help, customise) with an `aria-label`.
+- 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 +247,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;