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

package/CHANGELOG.md

@@ -18,6 +18,57 @@ 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`). 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`,
+    `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.
+  - `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`).
+
 - **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 +137,22 @@ 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).
+
 - **`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 +192,10 @@ next major.
 
 ### Fixed
 
+- **`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
@@ -379,6 +450,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

@@ -233,6 +233,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 +255,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.
 
@@ -948,6 +950,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 +1121,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 +1222,34 @@ 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.
+- **`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).
+
 ### `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 +1285,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
@@ -1378,6 +1449,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

package/DESIGN-GUIDE.md

@@ -29,7 +29,7 @@ Calm, dense, professional SaaS admin — Linear/Stripe-dashboard, not a landing
 | Page padding | `px={{ base: 4, md: 6 }} py={{ base: 4, md: 5 }}` |
 | Between page sections | `gap={5}` (a `Flex direction="column"`) |
 | Between cards in a grid | `gap={4}` |
-| Inside a card | `Card`'s own padding — don't add more; `bodyProps={{ p: 0 }}` for edge-to-edge content |
+| Inside a card | `Card`'s own padding — don't add more; `padding="none"` (or `"2xs"`/`"xs"` for dense) instead of `sx={{ p }}`, `bodyProps={{ p: 0 }}` for edge-to-edge content |
 | Between form fields | `gap={4}` vertical, `gap={3}` side by side |
 | Inline clusters (tags, meta, icon + text) | `gap={1.5}`–`gap={2}` |
 | Page header → content | the section gap (`gap={5}`) — no extra margin |
@@ -41,7 +41,7 @@ Borders are the one px value: `borderWidth="1px"`. Fixed widths (side panel, lis
 
 | Role | Props |
 | --- | --- |
-| Page title + subtitle | `PageHeader` (`lg`/600 h1, `sm` muted subtitle) — don't hand-build it |
+| Page title + subtitle | `PageHeader` (18px/600 h1 by default, `sm` muted subtitle; `titleSize="xl"` for a top-level page) — don't hand-build it |
 | 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}` |
@@ -139,11 +139,15 @@ the row title is the label: `<Text as="label" htmlFor={id}>` pointing at the fie
 ```
 
 `PageHeader` also takes `breadcrumbs`, `leading` (avatar), `titleAddon` (status `Tag`), `meta` (icon
-row) and `tabs` — a record page's whole header. KPI rows are a `SimpleGrid` of `StatCard`s; card
+row) and `tabs` — a record page's whole header. Actions wrap under the title on their own when they do
+not fit (`actionsLayout="auto"`), so don't hand-build a stacked variant. KPI rows are a `SimpleGrid` of `StatCard`s; card
 sections are `Card` with the title in `header`.
 
 | Pattern | Component — don't hand-build it |
 | --- | --- |
+| Multi-step flow (send, import, onboard) with validated Continue and a review step | `WizardDialog` (`Wizard` inline) — don't hand-roll Back / Continue / Finish around `StageProgress`; each step's `validate` returns its error messages, future steps stay locked until valid, each step's `summary` drives the review |
+| Rich-text template with `${field}` placeholders | `Editor mergeFields={…}` — not a `Select` + caret tracking + dialog beside it; use its `label` / `helperText` / `errorMessage` |
+| A PDF behind auth, shown inline | `PdfViewer getBlob={…}` — the toolbar's Open / Download then work with the token, so don't add your own buttons |
 | Toolbar: search · filters · active-filter chips · count · actions | `FilterBar` (`search`, children, `activeFilters` + `onRemoveFilter`/`onClearAll`, `summary`, `actions`) |
 | Read-only label/value grid (record details, key facts) | `DescriptionList` (`items`, `columns`, `layout="inline"` for a side panel, `copyable`, `isLoading`) |
 | Settings row (title + description left, control right) | `SettingRow` inside a `SettingsSection` (`isDanger` for the danger zone, `action` for a header-right button) |
@@ -160,6 +164,22 @@ sections are `Card` with the title in `header`.
 scrim `Box`. `Loading` is the older API and stays on the heavier house scrim by default; pass
 `variant="dim"` to route it through `Backdrop`, or just use `Backdrop` directly.
 
+### Navigation shell
+
+`SideBar` is the rail, `NavigationBar` the top bar, `NavLauncher` the full-height "go anywhere" panel.
+**The app owns the registry, permissions and persistence**; the library owns the look and the keyboard.
+
+- Keep one registry (modules → screens) and derive the rail, the launcher and route guards from it.
+  Filter by permission *before* passing `sections` to `NavLauncher`; use `isLoading` while access is
+  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`.
+- 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.
+- Show shortcut hints with `KbdShortcut`, never a hand-styled `<kbd>`.
+
 ## 7. Every page has four states
 
 Design all four, not just the happy path.
@@ -213,6 +233,9 @@ not shipped in this package). Start from the closest one:
 | Settings / long form | `settings.tsx` | section nav, `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` |
+| Wizard / multi-step dialog | `wizard.tsx` (`/examples/wizard`) | `WizardDialog` and inline `Wizard`: per-step `validate` messages, locked future steps, error summary, `summary`-driven review, `isFinishing` |
+| Template editor with merge fields | `templateEditor.tsx` (`/examples/template-editor`) | `Editor mergeFields`: grouped Insert field, chips, unknown-field error chips and `onUnknownTokens`, Make dynamic, side preview, label / helper / error |
 | Shop front (home → listing → product → bag → checkout → order) | `storefront/` | `ProductCard` grid / rail / quick-add, `ProductDetails` + `StickyBuyBar`, `CartItem`, `OrderSummary`, `CouponField`, address/payment groups, `OrderStatusTimeline`, `BagBar`; mobile frame + desktop |
 
 ## 10. Shop screens (e-commerce)

package/dist/Components/AppSwitcher/AppSwitcher.js

@@ -32,6 +32,9 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
@@ -43,6 +46,7 @@ const accentText_1 = require("../../Theme/tokens/builders/accentText");
 const outlineRung_1 = require("../../Theme/tokens/builders/outlineRung");
 const rowStates_1 = require("../../Theme/tokens/builders/rowStates");
 const useExclusiveOverlay_1 = require("../../Hooks/useExclusiveOverlay");
+const Kbd_1 = __importDefault(require("../Kbd/Kbd"));
 const AppMark_1 = __importStar(require("./AppMark"));
 const AppSwitcherProps_1 = require("./AppSwitcherProps");
 const useAppSwitcherShortcut_1 = require("./useAppSwitcherShortcut");
@@ -225,7 +229,7 @@ const AppSwitcher = ({ apps, currentAppId, onSelect, onOpenChange, isSearchable,
                             return;
                         }
                         handlePanelKeyDown(e);
-                    }, children: (0, jsx_runtime_1.jsx)(lucide_react_1.Grip, { size: s.icon + 1 }) }) }), (0, jsx_runtime_1.jsx)(react_2.PopoverContent, { w: width, maxW: "calc(100vw - 1.5rem)", textAlign: "start", onKeyDown: handlePanelKeyDown, bg: theme.colors.surfaceRaised, borderRadius: "xl", overflow: "hidden", boxShadow: `0 10px 30px ${theme.colors.boxShadow.default}`, _focus: { outline: "none", boxShadow: `0 10px 30px ${theme.colors.boxShadow.default}` }, children: (0, jsx_runtime_1.jsxs)(react_2.PopoverBody, { p: 0, children: [(0, jsx_runtime_1.jsxs)(react_2.Flex, { align: "center", gap: 2, px: 3, pt: 3, pb: showSearch ? 2 : 1, children: [(0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: "0.6875rem", fontWeight: 600, letterSpacing: "0.08em", textTransform: "uppercase", color: theme.colors.textMuted, children: HEADING }), (0, jsx_runtime_1.jsx)(react_2.Box, { flex: "1" }), hint && ((0, jsx_runtime_1.jsx)(react_2.Text, { as: "kbd", fontSize: "0.6875rem", fontFamily: "inherit", color: theme.colors.textMuted, border: "1px solid", borderRadius: "full", px: 1.5, py: 0.5, children: hint }))] }), showSearch && ((0, jsx_runtime_1.jsx)(react_2.Box, { px: 3, pb: 2, children: (0, jsx_runtime_1.jsxs)(react_2.InputGroup, { size: "sm", children: [(0, jsx_runtime_1.jsx)(react_2.InputLeftElement, { pointerEvents: "none", children: (0, jsx_runtime_1.jsx)(lucide_react_1.Search, { size: 15, color: theme.colors.textMuted }) }), (0, jsx_runtime_1.jsx)(react_2.Input, { ref: searchRef, value: query, onChange: (e) => setQuery(e.target.value), placeholder: "Search apps", borderRadius: "lg", "aria-label": "Search apps", onKeyDown: (e) => {
+                    }, children: (0, jsx_runtime_1.jsx)(lucide_react_1.Grip, { size: s.icon + 1 }) }) }), (0, jsx_runtime_1.jsx)(react_2.PopoverContent, { w: width, maxW: "calc(100vw - 1.5rem)", textAlign: "start", onKeyDown: handlePanelKeyDown, bg: theme.colors.surfaceRaised, borderRadius: "xl", overflow: "hidden", boxShadow: `0 10px 30px ${theme.colors.boxShadow.default}`, _focus: { outline: "none", boxShadow: `0 10px 30px ${theme.colors.boxShadow.default}` }, children: (0, jsx_runtime_1.jsxs)(react_2.PopoverBody, { p: 0, children: [(0, jsx_runtime_1.jsxs)(react_2.Flex, { align: "center", gap: 2, px: 3, pt: 3, pb: showSearch ? 2 : 1, children: [(0, jsx_runtime_1.jsx)(react_2.Text, { fontSize: "0.6875rem", fontWeight: 600, letterSpacing: "0.08em", textTransform: "uppercase", color: theme.colors.textMuted, children: HEADING }), (0, jsx_runtime_1.jsx)(react_2.Box, { flex: "1" }), hint && (0, jsx_runtime_1.jsx)(Kbd_1.default, { size: "xs", children: hint })] }), showSearch && ((0, jsx_runtime_1.jsx)(react_2.Box, { px: 3, pb: 2, children: (0, jsx_runtime_1.jsxs)(react_2.InputGroup, { size: "sm", children: [(0, jsx_runtime_1.jsx)(react_2.InputLeftElement, { pointerEvents: "none", children: (0, jsx_runtime_1.jsx)(lucide_react_1.Search, { size: 15, color: theme.colors.textMuted }) }), (0, jsx_runtime_1.jsx)(react_2.Input, { ref: searchRef, value: query, onChange: (e) => setQuery(e.target.value), placeholder: "Search apps", borderRadius: "lg", "aria-label": "Search apps", onKeyDown: (e) => {
                                             if (e.key === "ArrowDown" && visible.length > 0) {
                                                 e.preventDefault();
                                                 focusItem(0);

package/dist/Components/AppSwitcher/AppSwitcherProps.d.ts

@@ -52,6 +52,8 @@ export declare const filterApps: (apps: AppOption[], query: string) => AppOption
 export type ShortcutEvent = Pick<KeyboardEvent, "key" | "altKey" | "ctrlKey" | "metaKey" | "shiftKey">;
 /** "mod" is Cmd on Apple platforms and Ctrl everywhere else. */
 export declare const matchesShortcut: (event: ShortcutEvent, shortcut: string, isApple?: boolean) => boolean;
+/** One label per key in a chord, so a named key such as `enter` stays a single cap. */
+export declare const shortcutKeys: (shortcut: string, isApple?: boolean) => string[];
 export declare const formatShortcut: (shortcut: string, isApple?: boolean) => string;
 /** Input to `buildSuiteApps`: an `AppOption` keyed by its subdomain label, with `url` optional since it can be derived. */
 export interface SuiteAppSource extends Omit<AppOption, "url"> {

package/dist/Components/AppSwitcher/AppSwitcherProps.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildSuiteApps = exports.formatShortcut = exports.matchesShortcut = exports.filterApps = exports.appInitials = void 0;
+exports.buildSuiteApps = exports.formatShortcut = exports.shortcutKeys = exports.matchesShortcut = exports.filterApps = exports.appInitials = void 0;
 const NON_WORD = /[^\p{L}\p{N}]+/u;
 /** Up to two initials, so a mark stays legible without an icon. */
 const appInitials = (name) => {
@@ -48,12 +48,15 @@ const matchesShortcut = (event, shortcut, isApple = typeof navigator !== "undefi
 exports.matchesShortcut = matchesShortcut;
 const APPLE_SYMBOLS = { mod: "⌘", cmd: "⌘", meta: "⌘", ctrl: "⌃", shift: "⇧", alt: "⌥" };
 const OTHER_LABELS = { mod: "Ctrl", cmd: "Win", meta: "Win", ctrl: "Ctrl", shift: "Shift", alt: "Alt" };
-const formatShortcut = (shortcut, isApple = typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform)) => {
+const isAppleNow = () => typeof navigator !== "undefined" && /Mac|iPhone|iPad/.test(navigator.platform);
+/** One label per key in a chord, so a named key such as `enter` stays a single cap. */
+const shortcutKeys = (shortcut, isApple = isAppleNow()) => {
     const parts = shortcut.toLowerCase().split("+").map((p) => p.trim()).filter(Boolean);
     const table = isApple ? APPLE_SYMBOLS : OTHER_LABELS;
-    const rendered = parts.map((p, i) => { var _a; return i === parts.length - 1 ? p.toUpperCase() : ((_a = table[p]) !== null && _a !== void 0 ? _a : p.toUpperCase()); });
-    return isApple ? rendered.join("") : rendered.join("+");
+    return parts.map((p, i) => { var _a; return (i === parts.length - 1 ? p.toUpperCase() : ((_a = table[p]) !== null && _a !== void 0 ? _a : p.toUpperCase())); });
 };
+exports.shortcutKeys = shortcutKeys;
+const formatShortcut = (shortcut, isApple = isAppleNow()) => (0, exports.shortcutKeys)(shortcut, isApple).join(isApple ? "" : "+");
 exports.formatShortcut = formatShortcut;
 /**
  * Derives every app's origin from the host the consumer is already served on, so one deployment

package/dist/Components/Breadcrumbs/Breadcrumbs.d.ts

@@ -1,2 +1,2 @@
 import { BreadcrumbsProps } from "./BreadcrumbsProps";
-export default function Breadcrumbs({ spacing, separator, fontWeight, fontSize, isCurrentPage, handleClick, items, }: BreadcrumbsProps): import("react/jsx-runtime").JSX.Element;
+export default function Breadcrumbs({ spacing, separator, fontWeight, fontSize, isCurrentPage, handleClick, items, overflow, maxItems, labels, "data-testid": testId, }: BreadcrumbsProps): import("react/jsx-runtime").JSX.Element;

package/dist/Components/Breadcrumbs/Breadcrumbs.js

@@ -4,19 +4,42 @@ exports.default = Breadcrumbs;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("@chakra-ui/react");
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
+const focusRing_styles_1 = require("../../Theme/chakra/focusRing.styles");
 const breadcrumbInk_1 = require("./breadcrumbInk");
-function Breadcrumbs({ spacing, separator, fontWeight, fontSize, isCurrentPage, handleClick, items, }) {
+const DEFAULT_MAX_ITEMS = 3;
+const MIN_MAX_ITEMS = 2;
+const OVERFLOW_SX = {
+    nowrap: undefined,
+    wrap: { "& ol": { flexWrap: "wrap", rowGap: "4px" }, "& li": { maxWidth: "100%" } },
+    truncate: { "& ol": { flexWrap: "nowrap" }, "& li": { minWidth: 0 } },
+};
+const collapse = (entries, maxItems) => {
+    const keep = Math.max(MIN_MAX_ITEMS, Math.floor(maxItems));
+    if (entries.length <= keep)
+        return { head: entries, hidden: [], tail: [] };
+    return { head: entries.slice(0, 1), hidden: entries.slice(1, entries.length - (keep - 1)), tail: entries.slice(entries.length - (keep - 1)) };
+};
+function Breadcrumbs({ spacing, separator, fontWeight, fontSize, isCurrentPage, handleClick, items, overflow = "nowrap", maxItems = DEFAULT_MAX_ITEMS, labels, "data-testid": testId, }) {
     const theme = (0, react_1.useTheme)();
     const { colors } = (0, useCustomTheme_1.useCustomTheme)();
     const ink = (0, breadcrumbInk_1.breadcrumbInk)(colors);
     const effectiveSeparator = separator !== null && separator !== void 0 ? separator : ((0, jsx_runtime_1.jsx)(react_1.Box, { as: "span", color: ink.separator, children: "/" }));
-    return ((0, jsx_runtime_1.jsx)(react_1.Breadcrumb, { spacing: spacing, separator: effectiveSeparator, fontWeight: fontWeight, fontSize: fontSize, fontFamily: theme.fonts.body, children: items.map((item, index) => {
-            const isLast = isCurrentPage && index === items.length - 1;
-            return ((0, jsx_runtime_1.jsx)(react_1.BreadcrumbItem, { isCurrentPage: isLast, children: (0, jsx_runtime_1.jsx)(react_1.BreadcrumbLink, { href: item.path, color: isLast ? ink.current : ink.link, fontWeight: isLast ? 600 : fontWeight, sx: {
-                        "&:hover, &:active": { textDecoration: "none", color: isLast ? ink.current : ink.linkHover },
-                    }, onClick: (event) => {
-                        event.preventDefault();
-                        handleClick(item.path);
-                    }, children: item.label }) }, index));
-        }) }));
+    const clip = overflow !== "nowrap";
+    const clipProps = clip ? { noOfLines: 1 } : {};
+    const renderCrumb = ({ crumb, index }) => {
+        const isLast = Boolean(isCurrentPage) && index === items.length - 1;
+        const color = isLast ? ink.current : ink.link;
+        const common = { ...clipProps, title: clip ? crumb.label : undefined, color, fontWeight: isLast ? 600 : fontWeight };
+        return ((0, jsx_runtime_1.jsx)(react_1.BreadcrumbItem, { isCurrentPage: isLast, children: crumb.path === undefined ? ((0, jsx_runtime_1.jsx)(react_1.Box, { as: "span", "aria-current": isLast ? "page" : undefined, ...common, children: crumb.label })) : ((0, jsx_runtime_1.jsx)(react_1.BreadcrumbLink, { href: crumb.path, ...common, sx: { "&:hover, &:active": { textDecoration: "none", color: isLast ? ink.current : ink.linkHover } }, onClick: (event) => {
+                    event.preventDefault();
+                    handleClick(crumb.path);
+                }, children: crumb.label })) }, index));
+    };
+    const renderMenu = (hidden) => {
+        var _a;
+        return ((0, jsx_runtime_1.jsx)(react_1.BreadcrumbItem, { sx: { flexShrink: 0 }, children: (0, jsx_runtime_1.jsxs)(react_1.Menu, { isLazy: true, placement: "bottom-start", children: [(0, jsx_runtime_1.jsx)(react_1.MenuButton, { type: "button", "aria-label": ((_a = labels === null || labels === void 0 ? void 0 : labels.showMore) !== null && _a !== void 0 ? _a : ((n) => `Show ${n} more`))(hidden.length), color: ink.link, borderRadius: "md", px: 1, _hover: { color: ink.linkHover }, sx: (0, focusRing_styles_1.focusVisibleStyles)(colors), children: "\u2026" }), (0, jsx_runtime_1.jsx)(react_1.MenuList, { children: hidden.map(({ crumb, index }) => ((0, jsx_runtime_1.jsx)(react_1.MenuItem, { isDisabled: crumb.path === undefined, onClick: () => crumb.path !== undefined && handleClick(crumb.path), children: crumb.label }, index))) })] }) }, "overflow"));
+    };
+    const entries = items.map((crumb, index) => ({ crumb, index }));
+    const { head, hidden, tail } = overflow === "truncate" ? collapse(entries, maxItems) : { head: entries, hidden: [], tail: [] };
+    return ((0, jsx_runtime_1.jsxs)(react_1.Breadcrumb, { spacing: spacing, separator: effectiveSeparator, fontWeight: fontWeight, fontSize: fontSize, fontFamily: theme.fonts.body, sx: OVERFLOW_SX[overflow], "data-testid": testId, children: [head.map(renderCrumb), hidden.length > 0 && renderMenu(hidden), tail.map(renderCrumb)] }));
 }

package/dist/Components/Breadcrumbs/BreadcrumbsProps.d.ts

@@ -4,11 +4,25 @@ export type BreadcrumbsProps = Pick<BreadcrumbProps, "spacing" | "separator" | "
     isCurrentPage?: boolean;
     /** Accepted but never read by Breadcrumbs — has no effect at all. */
     isLastChild?: boolean;
+    /** Called with a crumb's path; never called for a label-only crumb (no `path`). */
     handleClick: (path: string) => void;
     items: BreadcrumbItem[];
+    /** "wrap" flows crumbs onto new lines; "truncate" keeps one line and folds middle crumbs into a "…" menu. Default "nowrap". */
+    overflow?: "nowrap" | "wrap" | "truncate";
+    /** With overflow "truncate": most crumbs shown (first plus the last `maxItems - 1`); the rest go in the menu. Default 3, minimum 2. */
+    maxItems?: number;
+    /** Visible-string overrides; `showMore` is the collapsed menu button's aria-label. */
+    labels?: BreadcrumbsLabels;
+    "data-testid"?: string;
 };
-/** One crumb: `label` is the visible text, `path` is passed to both the link's href and `handleClick`. */
+/** Visible strings, each with an English default. */
+export type BreadcrumbsLabels = {
+    /** Default: `Show ${count} more`. */
+    showMore?: (count: number) => string;
+};
+/** One crumb: `label` is the visible text; `path` goes to the link's href and `handleClick`. */
 export type BreadcrumbItem = {
-    path: string;
+    /** Omit for a label-only crumb: rendered as text, not a link, never passed to `handleClick`. */
+    path?: string;
     label: string;
 };

package/dist/Components/Card/Card.d.ts

@@ -1,4 +1,5 @@
-declare const Card: import("react").ForwardRefExoticComponent<Omit<import("@chakra-ui/react").CardProps, "color" | "colorScheme" | "direction" | "size" | "justify" | "children" | "variant" | "align"> & {
+import { CardPadding } from "./CardProps";
+declare const Card: import("react").ForwardRefExoticComponent<Omit<import("@chakra-ui/react").CardProps, "color" | "colorScheme" | "direction" | "padding" | "size" | "justify" | "children" | "variant" | "align"> & {
     dividercolor?: "gray" | "red" | "orange" | "yellow" | "green" | "teal" | "blue" | "cyan" | "purple" | "pink" | "whiteAlpha" | "blackAlpha";
     dividersize?: string;
     dividervariant?: "solid" | "dashed";
@@ -13,6 +14,7 @@ declare const Card: import("react").ForwardRefExoticComponent<Omit<import("@chak
     direction?: import("@chakra-ui/react").ResponsiveValue<"row" | "column" | "row-reverse" | "column-reverse">;
     align?: import("@chakra-ui/react").CardBodyProps["alignItems"];
     justify?: import("@chakra-ui/react").CardBodyProps["justifyContent"];
+    padding?: CardPadding;
     bodyProps?: import("@chakra-ui/react").CardBodyProps;
 } & import("react").RefAttributes<HTMLDivElement>>;
 export default Card;

package/dist/Components/Card/Card.js

@@ -3,11 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const react_2 = require("@chakra-ui/react");
-const Card = (0, react_1.forwardRef)(function Card({ header, footer, children, color, colorScheme, direction = "column", align, justify, bodyProps, ...rest }, ref) {
+const HEADER_PADDING_WHEN_FLUSH = "0.75rem";
+const PADDING_VALUES = {
+    none: "0",
+    "2xs": "0.375rem",
+    xs: "0.75rem",
+    sm: "0.75rem 1rem",
+    md: "1rem 1.25rem",
+    lg: "1.25rem 1.5rem",
+};
+const Card = (0, react_1.forwardRef)(function Card({ header, footer, children, color, colorScheme, direction = "column", align, justify, bodyProps, padding, ...rest }, ref) {
     const cardProps = { ...rest };
     delete cardProps.dividercolor;
     delete cardProps.dividersize;
     delete cardProps.dividervariant;
-    return ((0, jsx_runtime_1.jsxs)(react_2.Card, { ref: ref, colorScheme: colorScheme !== null && colorScheme !== void 0 ? colorScheme : color, ...cardProps, children: [header && (0, jsx_runtime_1.jsx)(react_2.CardHeader, { children: header }), (0, jsx_runtime_1.jsx)(react_2.CardBody, { display: "flex", flexDirection: direction, alignItems: align, justifyContent: justify, ...bodyProps, children: children }), footer && (0, jsx_runtime_1.jsx)(react_2.CardFooter, { children: footer })] }));
+    const sx = padding ? { "--card-padding": PADDING_VALUES[padding], ...cardProps.sx } : cardProps.sx;
+    return ((0, jsx_runtime_1.jsxs)(react_2.Card, { ref: ref, colorScheme: colorScheme !== null && colorScheme !== void 0 ? colorScheme : color, ...cardProps, sx: sx, children: [header && ((0, jsx_runtime_1.jsx)(react_2.CardHeader, { sx: padding === "none" ? { "--card-padding": HEADER_PADDING_WHEN_FLUSH } : undefined, children: header })), (0, jsx_runtime_1.jsx)(react_2.CardBody, { display: "flex", flexDirection: direction, alignItems: align, justifyContent: justify, ...bodyProps, children: children }), footer && (0, jsx_runtime_1.jsx)(react_2.CardFooter, { children: footer })] }));
 });
 exports.default = Card;

package/dist/Components/Card/CardProps.d.ts

@@ -6,8 +6,10 @@ type DeadDividerProps = {
     dividersize?: string;
     dividervariant?: "solid" | "dashed";
 };
+/** Padding steps: "none" flush, "2xs" 0.375rem, "xs" 0.75rem all round, "sm" / "md" / "lg" match `size`. */
+export type CardPadding = "none" | "2xs" | "xs" | "sm" | "md" | "lg";
 /** Themed outline surface with optional header/footer slots; children and direction/align/justify apply to the body. */
-export type CardProps = Omit<ChakraCardProps, "children" | "variant" | "size" | "color" | "colorScheme" | "direction" | "align" | "justify"> & DeadDividerProps & {
+export type CardProps = Omit<ChakraCardProps, "children" | "variant" | "size" | "color" | "colorScheme" | "direction" | "align" | "justify" | "padding"> & DeadDividerProps & {
     /** Rendered in CardHeader (semibold header ink) only when truthy. */
     header?: React.ReactNode;
     /** Rendered in CardFooter only when truthy. */
@@ -27,6 +29,8 @@ export type CardProps = Omit<ChakraCardProps, "children" | "variant" | "size" |
     align?: CardBodyProps["alignItems"];
     /** Body justifyContent; `bodyProps` wins if it sets the same thing. */
     justify?: CardBodyProps["justifyContent"];
+    /** Overrides `size`'s padding for header, body and footer; "none" is flush (a header keeps "xs"), "2xs" is 6px. */
+    padding?: CardPadding;
     /** Props for the body wrapper, e.g. `p={0}` for edge-to-edge media. */
     bodyProps?: CardBodyProps;
 };