@brandsync/wc 1.16.0 → 1.18.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @brandsync/wc
 
+## 1.18.0
+
+### Minor Changes
+
+- 30f2ede: New `bs-app-switcher`, `bs-app-tile` and `bs-app-recent-item` components from the Figma "App switcher", "App tile" and "Recent item" designs. The switcher is the 360px launcher panel ("EG apps"): header with Manage, search field, your apps as a grid (or Recent plus All apps), search results, and a Browse all footer link, with no-results, loading (`status="loading"`), error (`status="error"`) and empty states. Set `apps` and `recent` as JS properties (each app's `icon` is a monochrome SVG URL); listen to `bsAppSelect` (cancelable; apps are buttons and never navigate), `bsManage`, `bsBrowseAll`, `bsClearSearch`, `bsRetry`, `bsRequestAccess` and `bsQueryChange`. Built from `bs-card`, `bs-input`, `bs-app-tile`, `bs-app-recent-item`, `bs-empty-state`, `bs-skeleton`, `bs-button` and `bs-divider`; the tile and row are built from `bs-icon-tile`.
+- 30f2ede: New `bs-company-switcher` component from the Figma "Company Switcher" and "Triggers" designs. A trigger (avatar, company name, org. number, chevron) opens a panel to find and switch company: a search field, Current / Recent / All companies groups, a filtered matches view, a no-results state, a switching state (`switchingId`) and "Manage Companies" / "Add companies" footer actions. Set `companies` as a JS property; listen to `bsCompanySwitch`, `bsManageCompanies`, `bsAddCompanies` and `bsOpenChange`. Built from `bs-popover`, `bs-card`, `bs-input`, `bs-list-item`, `bs-avatar`, `bs-spinner`, `bs-empty-state`, `bs-divider` and `bs-button`.
+- 30f2ede: `bs-navigation-header` and the `bs-mega-menu` in its `menu` slot work on phones. At 768px and below the header's `left` region scrolls sideways inside itself (default alignment) so wide tabs no longer widen the page, and the `menu` slot is limited to the viewport and scrolls internally; the limit is the new `--bs-navigation-header-menu-max-height` (default `calc(100dvh - 100%)`). `bs-mega-menu` now responds to its own width: below 600px it is one column with wrapping text, 44px links, a stacked footer and no shortcut hint. `bs-menu-block` gets `--bs-menu-block-white-space` (default `nowrap`). New "In navigation header (mobile)" stories.
+- 30f2ede: New `bs-mega-menu`, `bs-menu-block` and `bs-compact-menu-block` components from the Figma "Mega menu", "Menu block" and "Compact menu block" designs. The mega menu is the dropdown panel under a navigation header tab: columns of links under group headings (`type="columns"` with icons and descriptions, or `type="compact"` with plain text links), an optional featured area (the `featured` prop or slot), and a footer with recently used items and a `bs-key-caps` shortcut hint. Set `columns`, `featured` and `recent` as JS properties (each item's `icon` is a monochrome SVG URL); listen to `bsMenuSelect` (cancelable; blocks are buttons and never navigate) and `bsClose` (Escape); toggle the host's `hidden` attribute from the tab that opens it. Built from `bs-card`, `bs-menu-block`, `bs-compact-menu-block`, `bs-divider` and `bs-key-caps`; the menu block uses `bs-icon-tile` and `bs-chip-informative`.
+- 30f2ede: `bs-navigation-header` gets a `menu` slot (and a `menu` part, plus `--bs-navigation-header-menu-z-index`, aliased to `--bs-z-index-dropdown`) that anchors a panel such as `bs-mega-menu` directly under the bar, at the header's full width, overlaying the page below. The slot only positions the panel and costs no layout when empty or hidden; open/close state, closing on `bsClose` or an outside click, and restoring focus to the trigger stay with the consumer. New "In navigation header" `bs-mega-menu` stories show the composition.
+- 30f2ede: New `bs-page-header` component from the Figma "Page header" design (types List page, Record, Record with tabs and Sticky compact): the header at the top of a page's content area, with a `breadcrumb` slot, the `heading` as a real heading (`headingLevel` 1-6, default 1), an optional `back` button (`bsBack`) and `favoritable` star toggle (`favorite`, `bsFavoriteChange`, cancelable), a `status` slot, a `meta` prop or slot, page-level `actions` and a `tabs` row. `compact` is the condensed sticky state (one row, level 2 shadow, no breadcrumb or tabs; `--bs-page-header-sticky-offset` sets its `top`). It reacts to its own width: below 640px the actions wrap under the title, slotted buttons grow to 44px and the tab row scrolls inside itself. Built from `bs-icon-button` (back, favourite), `bs-divider`, and the `bs-breadcrumbs`, `bs-chip-informative`, `bs-button` and `bs-tabs` you slot in. `bs-icon-button` gains a `pressed` prop that sets `aria-pressed` for toggle buttons.
+
+## 1.17.0
+
+### Minor Changes
+
+- bd9e559: New `bs-command-palette` component from the Figma "Command Palette" design: a Ctrl+K modal (native `dialog`) with a search field, slotted recent, suggested, commands, navigation and records sections made of `bs-search-item`s, a commands-only mode (value starting with `>`), no-results and loading views, an optional scope chip, an optional `hotkey`, and a keyboard-hint footer.
+- ccd592e: New `bs-empty-state`, `bs-search-item` and `bs-global-search` components from the Figma "Empty state", "Search results" and "Global Search" designs. `bs-empty-state` is a centered icon tile, heading, description and optional action. `bs-search-item` is a suggestion or result row. `bs-global-search` is a search combobox with a dropdown panel: slot-driven recent, jump-to, top-match and search-in sections, empty and error views, a keyboard-hint footer, full arrow-key navigation and combobox ARIA.
+- 10998b3: New `bs-key` and `bs-key-caps` components from the Figma "Base keys" and "Key caps" designs. `bs-key` is a single keyboard keycap (`<kbd>`) with a `label` (or default slot) or an `icon` slot. `bs-key-caps` is a one-to-four-key shortcut joined by "+" separators: pass `keys="Ctrl+K"` (or an array for a literal plus key) or slot your own `bs-key` elements, with a `disabled` state that dims the shortcut to 38%.
+- 30ab50a: New `bs-shortcut-row` and `bs-keyboard-shortcuts` components from the Figma "Shortcut row" and "Keyboard shortcuts" designs. `bs-shortcut-row` is an action label with its `bs-key-caps`. `bs-keyboard-shortcuts` is a searchable two-column shortcut reference panel with a single-key switch, filtering, a no-results state and a footer hint.
+
 ## 1.16.0
 
 ### Minor Changes

package/REFERENCE.md

@@ -87,6 +87,35 @@ Generated from component JSDoc by `scripts/generate-reference.mjs`. Do not edit
 - `--bs-ai-thinking-line-height` — Label line height. Aliased to `--bs-line-height-body-md`.
 - `--bs-ai-thinking-cycle-duration` — Duration of one shimmer sweep. Figma's own keyframe track for this label runs over exactly 2s, longer than any `--bs-duration-*` token (max `--bs-duration-slower` is 500ms), so this is aliased directly to the literal value.
 
+## `<bs-app-recent-item>`
+
+### Slots
+
+- `(default)` — The icon (16px, `currentColor`). Overrides the `icon` prop.
+
+### Parts (`::part()`)
+
+- `container` — The button.
+- `icon` — The icon tile (`bs-icon-tile`).
+- `name` — The app name.
+- `description` — The description line.
+
+### CSS custom properties
+
+- `--bs-app-recent-item-padding-x` — Aliased to `--bs-spacing-100`.
+- `--bs-app-recent-item-padding-y` — Aliased to `--bs-spacing-100`.
+- `--bs-app-recent-item-gap` — Gap between icon and text. Aliased to `--bs-spacing-150`.
+- `--bs-app-recent-item-radius` — Aliased to `--bs-border-radius-100`.
+- `--bs-app-recent-item-bg` — Resting background. `transparent`.
+- `--bs-app-recent-item-bg-hover` — Aliased to `--bs-surface-hover`.
+- `--bs-app-recent-item-bg-pressed` — Aliased to `--bs-surface-pressed`.
+- `--bs-app-recent-item-bg-current` — Aliased to `--bs-surface-selected`.
+- `--bs-app-recent-item-icon-bg` — Icon square background. Aliased to `--bs-color-neutral-container`; `--bs-surface-base` while hovered, pressed or current.
+- `--bs-app-recent-item-color` — Name colour. Aliased to `--bs-text-default`.
+- `--bs-app-recent-item-color-muted` — Description colour. Aliased to `--bs-text-secondary`.
+- `--bs-app-recent-item-color-disabled` — Name, description and icon colour when disabled. Aliased to `--bs-text-on-disabled`.
+- `--bs-app-recent-item-focus-ring` — Focus ring colour. Aliased to `--bs-border-neutral-focus`.
+
 ## `<bs-app-shell>`
 
 ### Slots
@@ -111,6 +140,65 @@ Generated from component JSDoc by `scripts/generate-reference.mjs`. Do not edit
 - `--bs-app-shell-main-padding` — Padding of the main area. Aliased to `--bs-spacing-400`.
 - `--bs-app-shell-aside-width` — Width of the aside column. Defaults to `auto` (zero when empty).
 
+## `<bs-app-switcher>`
+
+### Parts (`::part()`)
+
+- `panel` — The panel surface (`bs-card`).
+- `header` — The header row.
+- `heading` — The heading.
+- `manage` — The Manage link or button.
+- `search` — The search field wrapper.
+- `group` — One group (header and its apps).
+- `group-header` — A group header.
+- `grid` — A list of tiles.
+- `list` — A list of rows.
+- `tile` — An app tile (`bs-app-tile`).
+- `row` — A recent or result row (`bs-app-recent-item`).
+- `empty` — The no-results, error or empty state (`bs-empty-state`).
+- `footer` — The footer.
+- `browse` — The "Browse all" link or button.
+
+### CSS custom properties
+
+- `--bs-app-switcher-width` — Panel width. Defaults to `360px` (Figma); capped at the viewport.
+- `--bs-app-switcher-radius` — Panel corner radius. Aliased to `--bs-border-radius-150`.
+- `--bs-app-switcher-bg` — Panel background. Aliased to `--bs-surface-base`.
+- `--bs-app-switcher-border-color` — Panel border. Aliased to `--bs-border-default`.
+- `--bs-app-switcher-shadow` — Panel shadow (elevation level 4). Aliased to the `--bs-shadow-*` position and blur tokens and `--bs-elevation-higher`.
+- `--bs-app-switcher-padding` — Side padding of the content. Aliased to `--bs-spacing-150`.
+- `--bs-app-switcher-text-color` — Heading and links in the header. Aliased to `--bs-text-default`.
+- `--bs-app-switcher-header-color` — Group headers. Aliased to `--bs-text-secondary`.
+- `--bs-app-switcher-link-color` — Browse link. Aliased to `--bs-text-action`.
+- `--bs-app-switcher-focus-ring` — Link focus ring. Aliased to `--bs-border-neutral-focus`.
+
+## `<bs-app-tile>`
+
+### Slots
+
+- `(default)` — The icon (24px in `grid`, 16px in `compact`, `currentColor`). Overrides the `icon` prop.
+
+### Parts (`::part()`)
+
+- `container` — The button.
+- `icon` — The icon tile (`bs-icon-tile`).
+- `label` — The app name.
+
+### CSS custom properties
+
+- `--bs-app-tile-icon-size` — Size of the icon square. `44px` in `grid` (Figma) and `--bs-sizing-400` in `compact`.
+- `--bs-app-tile-padding` — Padding inside the tile. Aliased to `--bs-spacing-150` (`grid`) or `--bs-spacing-100` (`compact`).
+- `--bs-app-tile-gap` — Gap between icon and label. Aliased to `--bs-spacing-150` (`grid`) or `--bs-spacing-50` (`compact`).
+- `--bs-app-tile-radius` — Corner radius. Aliased to `--bs-border-radius-100`.
+- `--bs-app-tile-bg` — Resting background. `transparent`.
+- `--bs-app-tile-bg-hover` — Aliased to `--bs-surface-hover`.
+- `--bs-app-tile-bg-pressed` — Aliased to `--bs-surface-pressed`.
+- `--bs-app-tile-bg-current` — Aliased to `--bs-surface-selected`.
+- `--bs-app-tile-icon-bg` — Icon square background. Aliased to `--bs-color-neutral-container`; `--bs-surface-base` while hovered, pressed or current.
+- `--bs-app-tile-color` — Label colour. Aliased to `--bs-text-default`.
+- `--bs-app-tile-color-disabled` — Label and icon colour when disabled. Aliased to `--bs-text-on-disabled`.
+- `--bs-app-tile-focus-ring` — Focus ring colour. Aliased to `--bs-border-neutral-focus`.
+
 ## `<bs-attachment>`
 
 ### Parts (`::part()`)
@@ -540,6 +628,98 @@ Generated from component JSDoc by `scripts/generate-reference.mjs`. Do not edit
 - `--bs-citation-preview-snippet-radius` — Snippet corner radius. Aliased to `--bs-border-radius-100`.
 - `--bs-citation-preview-page-color` — Page label color. Aliased to `--bs-text-secondary`.
 
+## `<bs-command-palette>`
+
+### Slots
+
+- `recent` — `bs-search-item`s for the "Recent" section.
+- `suggested` — `bs-search-item`s for the "Suggested" section.
+- `commands` — `bs-search-item`s for the "Commands" section.
+- `navigation` — `bs-search-item`s for the "Navigation" section.
+- `records` — `bs-search-item`s for the "Records" section.
+- `try-instead` — `bs-search-item`s under "Try instead" in the no-results view (status `empty`).
+
+### Parts (`::part()`)
+
+- `dialog` — The native `<dialog>`.
+- `panel` — The palette surface.
+- `search` — The search bar row.
+- `input` — The `bs-input`.
+- `results` — The scrolling results area.
+- `section` — One section (header and items).
+- `section-header` — A section header.
+- `empty` — The no-results message block.
+- `footer` — The footer row.
+- `hint` — One keyboard hint (keycaps and text).
+
+### CSS custom properties
+
+- `--bs-command-palette-width` — Panel width. Defaults to `640px` (Figma); capped to the viewport.
+- `--bs-command-palette-top` — Distance from the top of the viewport. Defaults to `12vh`.
+- `--bs-command-palette-max-height` — Max height of the results area. Defaults to `60vh`.
+- `--bs-command-palette-radius` — Aliased to `--bs-border-radius-150`.
+- `--bs-command-palette-bg` — Panel background. Aliased to `--bs-surface-base`.
+- `--bs-command-palette-shadow` — Figma elevation level 4: `0 8px 16px` in `--bs-elevation-higher` (stronger in dark mode).
+- `--bs-command-palette-overlay` — Scrim colour. Aliased to `--bs-surface-overlay`.
+- `--bs-command-palette-footer-bg` — Aliased to `--bs-surface-container`.
+- `--bs-command-palette-divider-color` — Aliased to `--bs-border-default`.
+- `--bs-command-palette-header-border-color` — Aliased to `--bs-border-neutral-container`.
+- `--bs-command-palette-header-color` — Aliased to `--bs-text-muted`.
+- `--bs-command-palette-hint-color` — Aliased to `--bs-text-secondary`.
+- `--bs-command-palette-z-index` — Aliased to `--bs-z-index-modal`.
+
+## `<bs-compact-menu-block>`
+
+### Parts (`::part()`)
+
+- `container` — The button.
+
+### CSS custom properties
+
+- `--bs-compact-menu-block-padding` — Padding inside the block. Aliased to `--bs-spacing-100`.
+- `--bs-compact-menu-block-radius` — Corner radius. Aliased to `--bs-border-radius-100`.
+- `--bs-compact-menu-block-bg` — Resting background. `transparent`.
+- `--bs-compact-menu-block-bg-hover` — Aliased to `--bs-surface-hover`.
+- `--bs-compact-menu-block-bg-pressed` — Aliased to `--bs-surface-pressed`.
+- `--bs-compact-menu-block-color` — Text colour. Aliased to `--bs-text-default`.
+- `--bs-compact-menu-block-focus-ring` — Focus ring colour. Aliased to `--bs-border-info`.
+
+## `<bs-company-switcher>`
+
+### Parts (`::part()`)
+
+- `trigger` — The trigger button.
+- `avatar` — The trigger's `bs-avatar`.
+- `name` — The company name in the trigger.
+- `subtitle` — The org. number (or "Switching…") line in the trigger.
+- `panel` — The panel surface (`bs-card`).
+- `search` — The search field wrapper (combobox).
+- `list` — The listbox.
+- `group` — One group (header and rows).
+- `group-header` — A group header.
+- `row` — A company row (`bs-list-item`).
+- `empty` — The no-results state (`bs-empty-state`).
+- `footer` — The footer actions.
+
+### CSS custom properties
+
+- `--bs-company-switcher-width` — Trigger width. Defaults to `260px` (Figma); capped at 100%.
+- `--bs-company-switcher-panel-width` — Panel width. Defaults to `360px` (Figma); capped at the viewport.
+- `--bs-company-switcher-radius` — Trigger and panel corner radius. Aliased to `--bs-border-radius-100`.
+- `--bs-company-switcher-trigger-bg` — Trigger resting background. `transparent`.
+- `--bs-company-switcher-trigger-bg-hover` — Aliased to `--bs-surface-hover`.
+- `--bs-company-switcher-trigger-bg-pressed` — Aliased to `--bs-surface-pressed`.
+- `--bs-company-switcher-trigger-bg-open` — Aliased to `--bs-surface-selected`.
+- `--bs-company-switcher-focus-ring` — Trigger focus outline. Aliased to `--bs-border-neutral-focus`.
+- `--bs-company-switcher-panel-bg` — Panel background. Aliased to `--bs-surface-base`.
+- `--bs-company-switcher-panel-border-color` — Panel border. Aliased to `--bs-border-default`.
+- `--bs-company-switcher-shadow` — Panel shadow. Aliased to `--bs-shadow-md`.
+- `--bs-company-switcher-max-height` — Maximum height of the scrolling list. Defaults to `320px`.
+- `--bs-company-switcher-text-color` — Names. Aliased to `--bs-text-default`.
+- `--bs-company-switcher-muted-color` — Org. numbers. Aliased to `--bs-text-secondary`.
+- `--bs-company-switcher-header-color` — Group headers. Aliased to `--bs-text-muted`.
+- `--bs-company-switcher-z-index` — Panel stacking. Aliased to `--bs-z-index-popover`.
+
 ## `<bs-composer>`
 
 ### Slots
@@ -711,6 +891,30 @@ Generated from component JSDoc by `scripts/generate-reference.mjs`. Do not edit
 - `--bs-divider-color` — Line colour. Aliased to `--bs-border-neutral-container` (`default`) or `--bs-neutral-100` (`subtle`).
 - `--bs-divider-inset` — Indent applied by `inset`. Aliased to `--bs-spacing-300`.
 
+## `<bs-empty-state>`
+
+### Slots
+
+- `icon` — The glyph inside the icon tile (24px, `currentColor`). Falls back to the tile's intent glyph.
+- `(default)` — The description (overrides the `description` prop).
+- `action` — An optional action, e.g. `<bs-button variant="outlined">`.
+
+### Parts (`::part()`)
+
+- `container` — The centered column.
+- `icon` — The icon tile (`bs-icon-tile`).
+- `heading` — The heading element.
+- `description` — The description paragraph.
+- `action` — The action wrapper (only rendered while the `action` slot is filled).
+
+### CSS custom properties
+
+- `--bs-empty-state-padding-y` — Vertical padding. Aliased to `--bs-spacing-700` (56px).
+- `--bs-empty-state-padding-x` — Horizontal padding. Aliased to `--bs-spacing-300` (24px).
+- `--bs-empty-state-gap` — Gap between tile, heading, description and action. Aliased to `--bs-spacing-150`.
+- `--bs-empty-state-heading-color` — Aliased to `--bs-text-default`.
+- `--bs-empty-state-description-color` — Aliased to `--bs-text-secondary`.
+
 ## `<bs-error-page>`
 
 ### Slots
@@ -759,6 +963,43 @@ Generated from component JSDoc by `scripts/generate-reference.mjs`. Do not edit
 - `status` — The success / error message line.
 - `action` — The cancel / remove button. // Note: this component's CSS Custom Properties (--bs-file-upload-item-*) are documented via @prop // comments in bs-file-upload-item.css, not here (see bs-input.tsx's equivalent note).
 
+## `<bs-global-search>`
+
+### Slots
+
+- `recent` — `bs-search-item`s for the "Recent searches" section (status `default`).
+- `jump-to` — `bs-search-item`s for the "Jump to" section (status `default`).
+- `top-matches` — `bs-search-item`s for the "Top matches" section (status `results`).
+- `search-in` — `bs-search-item`s for the "Search in" section (status `results`).
+- `empty` — Replaces the whole empty-state block (status `empty`).
+- `error` — Replaces the whole error-state block (status `error`).
+
+### Parts (`::part()`)
+
+- `field` — The combobox wrapper around the search field.
+- `panel` — The dropdown panel.
+- `section` — One section (header and items).
+- `section-header` — A section header.
+- `empty` — The built-in empty or error state (`bs-empty-state`).
+- `footer` — The footer row.
+- `hint` — One keyboard hint (keycaps and text).
+- `clear-recent` — The "Clear recent" button wrapper.
+- `see-all` — The "See all results" button wrapper.
+
+### CSS custom properties
+
+- `--bs-global-search-width` — Field and panel width. Defaults to `480px` (Figma); capped at 100%.
+- `--bs-global-search-panel-radius` — Aliased to `--bs-border-radius-100`.
+- `--bs-global-search-panel-padding` — Aliased to `--bs-spacing-100`.
+- `--bs-global-search-gap` — Gap between sections, and between the field and the panel. Aliased to `--bs-spacing-100`.
+- `--bs-global-search-panel-bg` — Panel background. Aliased to `--bs-surface-base`.
+- `--bs-global-search-shadow` — Panel shadow: Figma elevation level 3 (`0 4px 8px` in `--bs-elevation-high`, 10% black in light mode and 30% in dark mode).
+- `--bs-global-search-z-index` — Panel stacking. Aliased to `--bs-z-index-dropdown`.
+- `--bs-global-search-divider-color` — Footer divider. Aliased to `--bs-border-default`.
+- `--bs-global-search-header-border-color` — Section header underline. Aliased to `--bs-border-neutral-container`.
+- `--bs-global-search-header-color` — Section header text. Aliased to `--bs-text-muted`.
+- `--bs-global-search-hint-color` — Footer hint text. Aliased to `--bs-text-secondary`.
+
 ## `<bs-grid>`
 
 ### Slots
@@ -810,6 +1051,81 @@ Generated from component JSDoc by `scripts/generate-reference.mjs`. Do not edit
 - `error` — The error message element.
 - `error-icon` — The warning icon shown before the error message. // Note: this component's CSS Custom Properties (--bs-input-*) are documented via @prop comments // in bs-input.css, not here -- Stencil's docs generator only parses @prop out of CSS file // comments (see stencil.js's parseStyleDocs/parseCssComment), not the class-level JSDoc.
 
+## `<bs-key>`
+
+### Slots
+
+- `(default)` — The key's label text (overrides the `label` prop), e.g. `Ctrl`.
+- `icon` — An icon shown instead of the label (16px), e.g. a return arrow.
+
+### Parts (`::part()`)
+
+- `container` — The `<kbd>` cap.
+- `label` — The label text wrapper (not rendered while the `icon` slot is filled).
+- `icon` — The icon wrapper (only rendered while the `icon` slot is filled).
+
+### CSS custom properties
+
+- `--bs-key-bg` — Cap background. Aliased to `--bs-surface-base`.
+- `--bs-key-border-color` — Cap border colour. Aliased to `--bs-border-default`.
+- `--bs-key-radius` — Cap corner radius. Aliased to `--bs-border-radius-50`.
+- `--bs-key-padding-x` — Horizontal padding. Aliased to `--bs-spacing-75`.
+- `--bs-key-padding-y` — Vertical padding. Aliased to `--bs-spacing-50`.
+- `--bs-key-min-width` — Smallest cap width, so single characters keep a keycap shape. Defaults to `25px` (Figma).
+- `--bs-key-color` — Label colour. Aliased to `--bs-text-secondary`.
+- `--bs-key-font-size` — Label size. Aliased to `--bs-font-size-xs` (12px).
+- `--bs-key-icon-size` — Icon size. Defaults to `16px` (Figma).
+
+## `<bs-key-caps>`
+
+### Slots
+
+- `(default)` — `bs-key` elements. A "+" separator is drawn before every key except the first.
+
+### Parts (`::part()`)
+
+- `container` — The group wrapper.
+
+### CSS custom properties
+
+- `--bs-key-caps-gap` — Gap between keys and separators. Aliased to `--bs-spacing-100`.
+- `--bs-key-caps-separator-color` — Colour of the "+" separators. Aliased to `--bs-text-muted`.
+- `--bs-key-caps-disabled-opacity` — Opacity of the whole shortcut while `disabled`. Defaults to `0.38` (Figma).
+
+## `<bs-keyboard-shortcuts>`
+
+### Slots
+
+- `heading` — Replaces the heading text.
+- `footer` — Replaces the footer hint.
+
+### Parts (`::part()`)
+
+- `container` — The panel surface (a `bs-card`).
+- `head` — The heading row.
+- `heading` — The heading element.
+- `close` — The close button.
+- `search` — The search field.
+- `switch` — The single-key switch row.
+- `groups` — The columns wrapper.
+- `group` — One group.
+- `group-title` — A group title.
+- `row` — A shortcut row (`bs-shortcut-row`).
+- `empty` — The "no results" line.
+- `footer` — The footer hint.
+
+### CSS custom properties
+
+- `--bs-keyboard-shortcuts-width` — Panel width and min-width. Defaults to `720px` (Figma).
+- `--bs-keyboard-shortcuts-bg` — Panel background. Aliased to `--bs-surface-base`.
+- `--bs-keyboard-shortcuts-radius` — Aliased to `--bs-border-radius-150`.
+- `--bs-keyboard-shortcuts-padding` — Aliased to `--bs-spacing-200`.
+- `--bs-keyboard-shortcuts-gap` — Gap between sections. Aliased to `--bs-spacing-200`.
+- `--bs-keyboard-shortcuts-shadow` — Figma elevation level 4 (`0 8px 8px` in `--bs-elevation-higher`, 12% black in light mode and 25% in dark mode).
+- `--bs-keyboard-shortcuts-column-gap` — Gap between the two columns. Aliased to `--bs-spacing-600`.
+- `--bs-keyboard-shortcuts-color` — Main text colour. Aliased to `--bs-text-default`.
+- `--bs-keyboard-shortcuts-color-secondary` — Titles, captions, footer. Aliased to `--bs-text-secondary`.
+
 ## `<bs-list>`
 
 ### Slots
@@ -872,6 +1188,41 @@ Generated from component JSDoc by `scripts/generate-reference.mjs`. Do not edit
 
 - `logo` — The rendered SVG/image's wrapper. // Note: this component's CSS Custom Properties are documented via @prop comments in bs-logo.css, // not here -- see bs-navigation-header.css's identical note.
 
+## `<bs-mega-menu>`
+
+### Slots
+
+- `featured` — The featured area on the right. Overrides the `featured` prop.
+- `footer-start` — Left side of the footer. Overrides the recently used line.
+- `footer-end` — Right side of the footer. Overrides the shortcut hint.
+
+### Parts (`::part()`)
+
+- `panel` — The panel surface (`bs-card`).
+- `columns` — The grid of columns and the featured area.
+- `column` — One column (group).
+- `heading` — A column heading.
+- `list` — A column's list of links.
+- `block` — A link (`bs-menu-block` or `bs-compact-menu-block`).
+- `featured` — The featured area.
+- `featured-title` — The featured title.
+- `featured-description` — The featured description.
+- `footer` — The footer.
+- `shortcut` — The shortcut hint's key caps (`bs-key-caps`).
+
+### CSS custom properties
+
+- `--bs-mega-menu-width` — Panel width. Defaults to `1100px` (Figma); capped at the viewport.
+- `--bs-mega-menu-radius` — Panel corner radius. Aliased to `--bs-border-radius-150`.
+- `--bs-mega-menu-bg` — Panel background. Aliased to `--bs-surface-base`.
+- `--bs-mega-menu-border-color` — Panel border. Aliased to `--bs-border-default`.
+- `--bs-mega-menu-shadow` — Panel shadow (elevation level 3). Aliased to the `--bs-shadow-*` position and blur tokens and `--bs-elevation-high`.
+- `--bs-mega-menu-padding` — Padding around the columns. Aliased to `--bs-spacing-300` and `--bs-spacing-350`.
+- `--bs-mega-menu-gap` — Gap between columns. Aliased to `--bs-spacing-300`.
+- `--bs-mega-menu-heading-color` — Column headings. Aliased to `--bs-text-muted`.
+- `--bs-mega-menu-text-color` — Featured title. Aliased to `--bs-text-default`.
+- `--bs-mega-menu-muted-color` — Featured description and footer text. Aliased to `--bs-text-secondary`.
+
 ## `<bs-menu>`
 
 ### Slots
@@ -890,6 +1241,34 @@ Generated from component JSDoc by `scripts/generate-reference.mjs`. Do not edit
 - `--bs-menu-gap` — Gap between slotted items. Aliased to `--bs-spacing-50`.
 - `--bs-menu-shadow` — Elevation shadow of the menu box. Aliased to `--bs-shadow-sm`.
 
+## `<bs-menu-block>`
+
+### Slots
+
+- `(default)` — The icon (16px, `currentColor`). Overrides the `icon` prop.
+
+### Parts (`::part()`)
+
+- `container` — The button.
+- `icon` — The icon tile (`bs-icon-tile`).
+- `name` — The title.
+- `badge` — The badge chip (`bs-chip-informative`).
+- `description` — The description.
+
+### CSS custom properties
+
+- `--bs-menu-block-padding` — Padding inside the block. Aliased to `--bs-spacing-150`.
+- `--bs-menu-block-gap` — Gap between icon and text. Aliased to `--bs-spacing-150`.
+- `--bs-menu-block-radius` — Corner radius. Aliased to `--bs-border-radius-100`.
+- `--bs-menu-block-bg` — Resting background. `transparent`.
+- `--bs-menu-block-bg-hover` — Aliased to `--bs-surface-hover`.
+- `--bs-menu-block-bg-pressed` — Aliased to `--bs-surface-pressed`.
+- `--bs-menu-block-icon-bg` — Icon square background. Aliased to `--bs-color-neutral-container`; `--bs-surface-base` while hovered or pressed.
+- `--bs-menu-block-color` — Title colour. Aliased to `--bs-text-default`.
+- `--bs-menu-block-color-muted` — Description colour. Aliased to `--bs-text-secondary`.
+- `--bs-menu-block-focus-ring` — Focus ring colour. Aliased to `--bs-border-info`.
+- `--bs-menu-block-white-space` — `white-space` of the title and description. `nowrap` (single line, ellipsis); set `normal` to let them wrap.
+
 ## `<bs-menu-item>`
 
 ### Slots
@@ -993,6 +1372,46 @@ Generated from component JSDoc by `scripts/generate-reference.mjs`. Do not edit
 - `primary` — The main button (`completion`).
 - `secondary` — The Hide checklist button (`completion`).
 
+## `<bs-page-header>`
+
+### Slots
+
+- `breadcrumb` — A `bs-breadcrumbs` trail, shown above the title. Not shown when `compact`.
+- `status` — A status chip next to the title, e.g. `<bs-chip-informative color="error" size="sm">Overdue</bs-chip-informative>`.
+- `meta` — The line under the title (inline after it when `compact`). Overrides the `meta` prop. Plain text.
+- `actions` — The page-level actions on the right, e.g. `bs-button`s and an icon-only "more" `bs-icon-button`.
+- `tabs` — A `bs-tabs` row under the meta line. Not shown when `compact`.
+
+### Parts (`::part()`)
+
+- `container` — The root element.
+- `breadcrumb` — The breadcrumb area.
+- `row` — The row holding the title block and the actions.
+- `main` — The title block (back button, title row and meta).
+- `back` — The back `bs-icon-button`.
+- `title` — The row holding the heading, status and favourite button.
+- `heading` — The heading element.
+- `status` — The status area.
+- `favorite` — The favourite `bs-icon-button`.
+- `meta` — The meta line.
+- `actions` — The actions area.
+- `tabs` — The tab row (scrolls sideways when narrow).
+- `divider` — The `bs-divider` under the tabs.
+
+### CSS custom properties
+
+- `--bs-page-header-bg` — Background. Aliased to `--bs-surface-base`.
+- `--bs-page-header-padding-x` — Left and right padding. Aliased to `--bs-spacing-200`.
+- `--bs-page-header-padding-y` — Top and bottom padding. Aliased to `--bs-spacing-300`.
+- `--bs-page-header-gap` — Gap between the breadcrumb, title block and tabs, and between the title block and the actions. Aliased to `--bs-spacing-150`.
+- `--bs-page-header-title-gap` — Gap between the heading, status and favourite button. Aliased to `--bs-spacing-150`.
+- `--bs-page-header-actions-gap` — Gap between the actions. Aliased to `--bs-spacing-100`.
+- `--bs-page-header-text-color` — Heading. Aliased to `--bs-text-default`.
+- `--bs-page-header-meta-color` — Meta line. Aliased to `--bs-text-secondary`.
+- `--bs-page-header-shadow` — Shadow of the compact header (elevation level 2). Aliased to the `--bs-shadow-*` position and blur tokens and `--bs-elevation-medium`.
+- `--bs-page-header-sticky-offset` — The `top` of the compact header. Defaults to `0px`; set it to the height of a sticky bar above (e.g. the navigation header).
+- `--bs-page-header-z-index` — Stacking order of the compact header. Aliased to `--bs-z-index-sticky`.
+
 ## `<bs-pagination>`
 
 ### Parts (`::part()`)
@@ -1105,6 +1524,39 @@ Generated from component JSDoc by `scripts/generate-reference.mjs`. Do not edit
 - `dot` — The center fill shown inside the ring when `checked`.
 - `label` — The label text wrapper. // Note: this component's CSS Custom Properties (--bs-radio-*) are documented via @prop comments // in bs-radio.css, not here -- Stencil's docs generator only parses @prop out of CSS file // comments, not the class-level JSDoc (see bs-checkbox.tsx's equivalent note).
 
+## `<bs-search-item>`
+
+### Slots
+
+- `icon` — A leading glyph (24px, `currentColor`).
+- `(default)` — The primary text. Wrap the matched part in `<strong>` or `<b>` to show it semibold.
+- `description` — An optional second line.
+- `trailing` — Trailing text (overrides the `trailing` prop).
+
+### Parts (`::part()`)
+
+- `container` — The row.
+- `icon` — The icon wrapper.
+- `content` — The text column.
+- `label` — The primary line.
+- `description` — The description line.
+- `trailing` — The trailing text wrapper.
+
+### CSS custom properties
+
+- `--bs-search-item-min-height` — Aliased to `--bs-spacing-600` (48px).
+- `--bs-search-item-padding-y` — Aliased to `--bs-spacing-100`.
+- `--bs-search-item-padding-x` — Aliased to `--bs-spacing-150`.
+- `--bs-search-item-gap` — Aliased to `--bs-spacing-100`.
+- `--bs-search-item-radius` — Aliased to `--bs-border-radius-100`.
+- `--bs-search-item-bg` — Resting background. `transparent`.
+- `--bs-search-item-bg-active` — Active (highlighted) and hover background. Aliased to `--bs-surface-hover`.
+- `--bs-search-item-bg-pressed` — Aliased to `--bs-surface-pressed`.
+- `--bs-search-item-color` — Primary text. Aliased to `--bs-text-default`.
+- `--bs-search-item-color-muted` — Description and trailing text. Aliased to `--bs-text-muted`.
+- `--bs-search-item-color-disabled` — Aliased to `--bs-text-on-disabled`.
+- `--bs-search-item-icon-color` — Aliased to `--bs-icon-default`.
+
 ## `<bs-session-timeout>`
 
 ### Slots
@@ -1129,6 +1581,28 @@ Generated from component JSDoc by `scripts/generate-reference.mjs`. Do not edit
 - `secondary` — The secondary button.
 - `cancel` — The Cancel button (`confirm-identity`).
 
+## `<bs-shortcut-row>`
+
+### Slots
+
+- `(default)` — The action label (overrides the `action` prop).
+- `keys` — Your own `bs-key-caps` (or custom keys), replacing the generated one.
+
+### Parts (`::part()`)
+
+- `container` — The row.
+- `action` — The action label wrapper.
+- `keys` — The wrapper around the key caps.
+
+### CSS custom properties
+
+- `--bs-shortcut-row-height` — Row height. Defaults to `36px` (Figma).
+- `--bs-shortcut-row-padding-x` — Horizontal padding. Aliased to `--bs-spacing-100`.
+- `--bs-shortcut-row-gap` — Gap between label and keys. Aliased to `--bs-spacing-100`.
+- `--bs-shortcut-row-radius` — Corner radius. Aliased to `--bs-border-radius-75`.
+- `--bs-shortcut-row-color` — Label colour. Aliased to `--bs-text-default`.
+- `--bs-shortcut-row-color-disabled` — Label colour while `disabled`. Aliased to `--bs-text-on-disabled`.
+
 ## `<bs-side-panel>`
 
 ### Slots
@@ -1538,10 +2012,12 @@ Generated from component JSDoc by `scripts/generate-reference.mjs`. Do not edit
 
 - `left` — Menu/action content immediately after the logo (or, in `with-navigation-drawer` mode, at the bar's left edge). Typically one or more `bs-button`/`bs-icon-button` elements.
 - `right` — Menu/action content pushed to the bar's far right.
+- `menu` — A panel anchored directly below the bar, spanning the header's full width and overlaying the page content under it (typically a `bs-mega-menu`). It takes no space while empty or hidden. The slot only positions the panel: it does not own open/close state -- the consumer's trigger toggles the panel's `hidden`, closes it on its `bsClose` event and on an outside click, and restores focus to the trigger.
 
 ### Parts (`::part()`)
 
 - `logo` — The BrandSync brand mark, rendered via a nested `bs-logo` element (`part="logo"` is set directly on that element -- the same pattern `bs-attachment` uses for its own nested `bs-icon-button`'s `remove` part -- so `bs-navigation-header::part(logo)` still targets it directly, no forwarding needed). Not rendered in `with-navigation-drawer` mode.
 - `left` — The wrapper around the `left` slot.
 - `right` — The wrapper around the `right` slot.
+- `menu` — The wrapper around the `menu` slot (absolutely positioned under the bar).
 - `skip-link` — The "Skip to main content" link (only rendered when `skipToContentHref` is set). // Note: this component's CSS Custom Properties are documented via @prop comments in // bs-navigation-header.css, not here.