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

package/CHANGELOG.md

@@ -18,6 +18,105 @@ next major.
 
 ### Added
 
+- **HRMS library requests** — a navigation launcher, key caps, a merge-field `Editor`, a wizard and
+  smaller gaps found by the HRMS migration:
+  - `NavLauncher` — full-height navigation launcher (browse modules, pins, Frequent, Recent, search
+    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`
+    is the chip (10px radius, 36px, accent ink, one ⌘K hint) that opens an app-owned launcher (`aria-haspopup="dialog"`, `aria-expanded`,
+    `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 "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); 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`.
+  - `NavigationBar` `leading` — a slot between the sidebar toggle/back button and the title, outside
+    the title `<p>`.
+  - `SideBar` pinned section: `pinnedItems`, `pinnedLabel`, `onUnpin`, `activePinnedId`,
+    `pinnedLimit`, `pinnedLabels`; `collapseTransition` (`"none"` or `{ speed, animateShadow }`);
+    `autoCollapse` (default `true`; `false` stops the rail calling `changeToggle` itself, which also
+    silences the `open` prop). Types `SidebarPinnedItem`, `SidebarPinnedLabels`,
+    `SidebarCollapseTransition`.
+  - `Breadcrumbs` `overflow` (`"nowrap"` | `"wrap"` | `"truncate"`), `maxItems` (default 3) and
+    `labels.showMore`; `"truncate"` folds middle crumbs into a "…" menu. A `BreadcrumbItem` without
+    `path` renders as plain text.
+  - `PageHeader` `titleSize` (`"md"` | `"lg"` | `"xl"`) and `actionsLayout`
+    (`"auto"` | `"stacked"` | `"inline"`).
+  - `Card` `padding` (`"none"` | `"2xs"` | `"xs"` | `"sm"` | `"md"` | `"lg"`) — one padding for
+    header, body and footer.
+  - `Editor` merge fields: `mergeFields` adds an Insert field menu (grouped, searchable),
+    non-editable token chips (stored HTML keeps the raw `${path}`), unknown-field error chips with
+    `onUnknownTokens`, and a Make dynamic dialog; plus `tokenSyntax`, `showMakeDynamic`,
+    `toolbarButtons`, `apiRef` / `onReady` (`EditorApi`) and `labels` (incl. `dynamicFieldPlaceholder`, default "Choose a field"). `Editor` also takes `label`,
+    `isRequired`, `helperText`, `error`, `errorMessage` and `data-testid`; the editable area gets
+    `role="textbox"` with `aria-labelledby` / `aria-invalid` / `aria-describedby` / `aria-required`.
+    Types `EditorProps`, `EditorApi`, `EditorMergeField`, `EditorTokenSyntax`, `EditorToolbarButton`,
+    `EditorLabels`.
+  - `WizardDialog` and inline `Wizard` — a multi-step flow that owns step state (validated
+    Continue, locked future steps, error summary, review on the last step); `wizardTransition` and
+    `firstInvalidStep` are exported.
+  - `PdfViewer` `getBlob` (authed files: the viewer makes and revokes the object URL, skeleton while
+    loading), `fallback`, `onLoad`, `onError`, `labels`; inline support is detected with
+    `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:
   `Rating`, `PriceBlock`, `StockStatus`, `ProductBadges`, `WishlistToggle`, `OptionChip`,
@@ -86,6 +185,32 @@ next major.
 
 ### Changed
 
+- **`PageHeader` `actionsLayout` defaults to `"auto"`**: at `md` and up the actions wrap below the
+  title when they do not fit (before, they squeezed the title). Identical whenever title and
+  actions fit on one row; pass `actionsLayout="inline"` for the old behaviour.
+- **`Card` `padding` is no longer Chakra's style prop** — it is omitted from the type and now takes
+  the `CardPadding` steps. A consumer passing `padding={4}` gets a compile error; use `p` or `sx`.
+  Staged for the next major (see Breaking); consumer blast radius not measured.
+- **`SideBar` default box-shadow transition is 260ms** (was 200ms) so it follows `collapseTransition`
+  `speed="slow"`. The width transition is unchanged.
+- **`StageProgress variant="stepper"` renders an `ol` of `li`** (`StepperStageProps.asListItem`).
+  Visual layout is unchanged; selectors that expected a `div` list no longer match.
+- **`PdfViewer` `pdfUrl` is optional** — pass exactly one of `pdfUrl` / `getBlob`. In `getBlob` mode
+  the toolbar Open and Download are real buttons that fetch through it.
+- `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
   direct add that morphs into a stepper, sold-out "Notify me", slots). `ProductDetails` is a
@@ -125,6 +250,19 @@ 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.
+
 - **Commerce performance (consumer report on 2.4.2-beta.57).** `ProductCard` no longer loads the
   hover image on devices that cannot hover; `QuickAddSheet` mounts on first open, not on first
   paint; `formatPrice` caches its `Intl.NumberFormat`; every `matchMedia` consumer
@@ -299,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
@@ -316,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.
@@ -379,6 +519,10 @@ known consumers in the Pixelize repos. `ProductCard` drops `id`, `label`, `descr
 option and cart-callback props (it takes `product`, `selection`, `onAddToBag` and slots). Video
 and YouTube/Vimeo frames are now `ProductMedia` items in `MediaGallery`.
 
+**`Card` `padding` narrows from Chakra's style prop to `CardPadding`.** `padding={4}` stops
+compiling; use `p` / `sx` for arbitrary values. No use inside this repo; consumers not measured, so
+run `tsc --noEmit` in each before upgrading.
+
 **`star` is a required `PaletteProps` token.** A hand-written palette without it throws in
 `assertPixelizePalette` naming `star`; palettes built from the library's builders get it for free.
 

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
@@ -233,6 +242,8 @@ and wires `aria-controls` to them. Pick by that, never by the picture. A screen
 | Top bar: back control + user-avatar profile/logout dropdown | `NavigationBar` | No page-nav links at all — `navMenu` is only the avatar dropdown's own items |
 | Top bar: horizontal page links with active-state highlighting + submenus | `Header` | Desktop submenus are hover-only, see gotcha below |
 | Collapsible/dockable left rail — primary in-app navigation + secondary panel | `SideBar` | The persistent nav shell, not for switching between whole apps |
+| In-app launcher: browse modules, pins, recents, search | `NavLauncher` opened by a `LauncherTrigger` in `NavigationBar`'s `leading` | An app-owned screen registry, not a cross-app switcher; pins can also surface in `SideBar` `pinnedItems` |
+| Key cap or chord hint (`mod+k`) | `Kbd` / `KbdShortcut` | Never hand-style a `<kbd>`; `Search` and `AppSwitcher` already use it |
 | Cross-app launcher (CRM/HRMS/Tickets/Billing/...) | `AppSwitcher` | Two-column popover grid of separate app origins — `SideBar`'s `otherApps` is the legacy predecessor; don't wire both into one shell |
 | Floating Jira-style dialog to view/edit one record without leaving the page | `WorkspaceWindow` | Modal-based floating panel, not page navigation; pairs with `WorkspaceTray` |
 
@@ -253,10 +264,10 @@ Four components open a file, and only one of them is the general answer.
 | --- | --- | --- |
 | A gallery of mixed media with next/prev, a filmstrip and per-type stages | `MediaViewer` | The full lightbox: image/video/audio/pdf/doc stages, keyboard nav, fullscreen, download. Collapses the filmstrip and stepper automatically for a single item |
 | One file, click-to-open, no gallery | `FilePreview` | Lighter controlled modal; auto-detects type, zoom/rotate for images |
-| Always-visible inline PDF panel in the page flow | `PdfViewer` | Non-modal, PDF-only, small open/download toolbar |
+| Always-visible inline PDF panel in the page flow | `PdfViewer` | Non-modal, PDF-only, small open/download toolbar; `getBlob` for files behind auth |
 | Crop/preview a user avatar | `ProfilePhotoViewer` | Avatar-specific, not a general file viewer |
 
-`PdfViewer` and `FilePreview` both render a PDF through the identical unstyled `<embed type="application/pdf">` with no error handling if the browser can't render it inline — neither tells you when that happens. `MediaViewer` does handle it: formats a browser cannot decode (`.avi`, `.mkv`, `.m3u8`, `.heic`, `.tiff`) render an icon and a file-type chip with a download action instead of a blank frame.
+`PdfViewer` shows a fallback when the browser cannot render a PDF inline (`navigator.pdfViewerEnabled === false`) or `getBlob` rejects; `FilePreview`'s `"pdf"` kind renders a bare `<embed type="application/pdf">` and tells you nothing. `MediaViewer` also handles it: formats a browser cannot decode (`.avi`, `.mkv`, `.m3u8`, `.heic`, `.tiff`) render an icon and a file-type chip with a download action instead of a blank frame.
 
 `MediaViewer.labels` takes a `Partial<MediaViewerLabels>` — that type and `defaultMediaViewerLabels` are both exported from the package root, so you can merge rather than restate every string.
 
@@ -302,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` |
 
 ---
 
@@ -419,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`
@@ -455,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
 
@@ -476,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
@@ -560,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`,
@@ -948,6 +998,11 @@ draw nothing.
 
 **Apply:** drop the nested `CardBody`, or pass `bodyProps={{ p: 0 }}`.
 
+To change the padding, use `padding="none" | "2xs" | "xs" | "sm" | "md" | "lg"`. `sx={{ p: ... }}` on
+the container *adds* to the body padding (double inset) and `sx={{ p: 0 }}` does nothing. `padding`
+is no longer Chakra's style prop (omitted from the type) — use `p` for a raw value. With
+`padding="none"` the header keeps `xs` padding.
+
 ### Commerce kit — read before building a shop screen
 
 `ProductCard`, `ProductDetails`, `VariantSelector` and the bag pieces share one contract: pass
@@ -1114,6 +1169,39 @@ is also `null` until Jodit's lazy-loaded chunk resolves — a mount-time effect
 **Apply:** never set `theme`/`popupRoot` inside the `config` you pass to `Editor`. To force a
 remount, wrap `<Editor>` itself in a keyed parent, not via `Editor`'s own `key` prop.
 
+### `PdfViewer` `getBlob` — fetched on mount only; the toolbar already has Open and Download
+
+- **Swapping the file needs a new React `key`.** `getBlob` is read through a ref and fetched on mount,
+  so an inline arrow is safe, but changing it never refetches — the old document silently stays.
+- **The default fallback shows only a message while the toolbar is visible**; with
+  `showToolbar={false}` it adds its own Open and Download buttons. `getBlob` mode makes the toolbar's
+  actions work for authed files, so an app need not render its own — or pass `showToolbar={false}`.
+- Pass exactly one of `pdfUrl` / `getBlob`.
+
+### `WizardDialog` — `validate` must be pure; controlled `stepId` does not unlock steps
+
+`validate` runs on Continue, on Finish, and again for every step on Finish. Passing `stepId` controls
+the visible step only: stages past the furthest valid step stay disabled. Esc, close, Back and Cancel
+are disabled while `isFinishing`.
+
+### `PageHeader` actions wrap by default
+
+`actionsLayout` defaults to `"auto"`, so actions that do not fit drop below the title at `md`+. A
+test asserting the old single-row layout needs `actionsLayout="inline"`.
+
+### `Editor` merge fields — chips, raw values and stale closures
+
+- **Chips are `<span data-field contenteditable="false">`.** Do not style or strip `[data-field]` in
+  consumer CSS or sanitisers, and sanitise the raw `${path}` value `onChange` reports, not Jodit's HTML.
+- **A hand-typed `${path}` stays plain text** until `value` is next applied from outside; only tokens
+  inserted through the menu / `apiRef` or already present in `value` become chips. Unknown-token
+  detection still runs on the raw value.
+- **`config.extraButtons[].exec` goes stale** (the memo key is `JSON.stringify`, which drops functions).
+  Use `toolbarButtons` — React buttons, always current.
+- **`jodit-react` binds `onChange` / `onBlur` once, keyed on handler identity, not `config`.** After
+  Jodit is re-created (readonly or height change) a stable handler stops receiving events. `Editor`
+  binds them itself per instance; don't copy the pattern when wrapping Jodit directly.
+
 ### `Editor`'s Jodit toolbar is fixed for screen readers and keyboard, from our wrapper only
 
 Jodit's own markup (`node_modules/jodit`) put `aria-label` on each button's `role="listitem"`
@@ -1182,6 +1270,47 @@ 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
+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.
+
+### `NavLauncher` — the app owns routing, registry, query and chord
+
+- **`linkAs` must forward `className`, `ref`, `onClick`, `href`, `target`, `rel`, `tabIndex` and
+  `aria-hidden`** to its anchor. Dropping `className` loses all row styling; dropping `onClick` means
+  a click never closes the launcher.
+- **`onNavigate` fires for keyboard opens only** (Enter, mod+Enter). Pointer clicks follow the
+  rendered links, so a router `linkAs` must do the navigation.
+- **Controlled `query`:** the launcher still calls `onQueryChange("")` when it closes; the app must
+  apply it or the stale query reopens.
+- **Search rows are not nested links.** The visible label is a text-only `role="option"`; the real
+  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.
+- **`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). `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
 
 Dropdown children are gated on local hover state (`onMouseEnter`/`onMouseLeave`), with no `onFocus`.
@@ -1217,6 +1346,9 @@ It's declared on the type but omitted from the component's destructure entirely.
 
 **Apply:** don't pass it expecting it to mark or style the final crumb — there's nothing it can do.
 
+With `overflow="wrap" | "truncate"` each crumb is `noOfLines={1}` with a `title`, so one very long
+label ellipsizes; the default `"nowrap"` is unchanged.
+
 ### `Accordion`'s `items[].buttonProps` replaces, not merges, the expanded/hover highlight
 
 It spreads after the built-in `bg`/`_hover` that encode `isExpanded` state — passing `bg` or
@@ -1245,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
 
@@ -1378,6 +1550,21 @@ it; now `@deprecated` in `SideBarProps.tsx`.
 
 **Apply:** don't pass `selectedSubMenu` expecting it to highlight a submenu row.
 
+### `SideBar` pinned rows, `autoCollapse` and `collapseTransition`
+
+- **`autoCollapse={false}` also silences the `open` prop** (`open` works by calling `changeToggle`).
+  Drive collapse with `toggle` only.
+- **A pinned id highlights only in the pinned block** while `activePinnedId` matches, and the parent
+  submenu of a pinned child does not auto-open. An `activePinnedId` past `pinnedLimit` expands the
+  list so the active state never disappears.
+- **Pinned rows are anchors with `href={url}`**: a plain click calls `handleMenuClick` (and closes the
+  overlay), modified clicks fall through to the browser. Unpin is a sibling button, never nested.
+- **`collapseTransition` affects the `lg`+ inline rail only** — overlay slide, drag and `mobileNav`
+  are untouched.
+- **The rail focus ring is lifted per surface** (`sidebarFocus.ts`) because `colors.focusRing.ring` is
+  derived for the page canvas and fails 3:1 on the rail for five light brands. The lasting fix is a
+  `sidebar.focusRing` theme token.
+
 ### `KanbanBoard`'s `kanbanSelect`/`onOpen` don't check `permissions` — decision: accepted as-is
 
 Looked like an asymmetry with the gated `kanbanEdit`/`kanbanCreate`/`onDelete`, but on inspection