@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/reference/bf-empty-state-heading.md

@@ -0,0 +1,33 @@
+# BfEmptyStateHeading
+
+The heading level of an empty state title, one for a whole page
+
+Type from `@bitforgehq/ui` · since 0.3.2
+
+The heading level a `bf-empty-state` title takes: a `BfEmptyStateHeadingLevel`, or `1` when the
+empty state is the page itself (a not-found or no-access page). A new type, so `Record`s over
+the released `BfEmptyStateHeadingLevel` keep compiling.
+
+```ts
+import { type BfEmptyStateHeading } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfEmptyStateHeading = BfEmptyStateHeadingLevel | 1
+```
+
+## Values
+
+- `2`
+- `3`
+- `1`
+
+## Uses
+
+- [BfEmptyStateHeadingLevel](bf-empty-state-heading-level.md)
+
+## Used by
+
+- [bf-empty-state](../components/empty-state.md)

package/ai/reference/bf-labels.md

@@ -12,26 +12,79 @@ import { type BfLabels } from '@bitforgehq/ui';
 
 ## Properties
 
-| Name            | Type                                          | Default                                                       | Description                                                                                                   |
-| --------------- | --------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| `loading`       | `string`                                      | `'Loading'`                                                   | bf-spinner's accessible name (a loading bf-button's spinner is decorative and has none).                      |
-| `dismiss`       | `string`                                      | `'Dismiss'`                                                   | bf-alert's dismiss button.                                                                                    |
-| `tabBar`        | `string`                                      | `'Main'`                                                      | bf-tab-bar's navigation name.                                                                                 |
-| `tabBadge`      | `(count: number) => string`                   | `` (count) => `${count} new` ``                               | bf-tab's announcement of a numeric badge.                                                                     |
-| `back`          | `string`                                      | `'Back'`                                                      | bf-back-button's label.                                                                                       |
-| `ok`            | `string`                                      | `'OK'`                                                        | BfAlertDialogService's default button.                                                                        |
-| `cancel`        | `string`                                      | `'Cancel'`                                                    | BfActionSheetService's cancel row.                                                                            |
-| `actions`       | `string`                                      | `'Actions'`                                                   | An action sheet's name when it has no title.                                                                  |
-| `sheet`         | `string`                                      | `'Sheet'`                                                     | bf-sheet's name without an ariaLabel or heading.                                                              |
-| `modal`         | `string`                                      | `'Modal'`                                                     | bf-modal's name without an ariaLabel or heading.                                                              |
-| `refreshing`    | `string`                                      | `'Refreshing'`                                                | bf-refresher's status while refreshing.                                                                       |
-| `close`         | `string`                                      | `'Close'`                                                     | bf-dialog's close button, and bf-sheet's screen-reader Close.                                                 |
-| `expand`        | `string`                                      | `'Expand'`                                                    | bf-sheet's grabber button below the top snap point: the next press expands the sheet.                         |
-| `collapse`      | `string`                                      | `'Collapse'`                                                  | bf-sheet's grabber button at the top snap point: the next press collapses the sheet.                          |
-| `sheetPosition` | `(position: number, count: number) => string` | `` (position, count) => `Sheet at ${position} of ${count}` `` | bf-sheet's snap position (1-based), announced politely when it changes and part of the grabber button's name. |
-| `dialog`        | `string`                                      | `'Dialog'`                                                    | A dialog's name without an ariaLabel, a bf-dialog title or a heading.                                         |
-| `notifications` | `string`                                      | `'Notifications'`                                             | The desktop toast stack's region name.                                                                        |
-| `validation`    | `BfValidationMessages`                        | required                                                      | Default error text per validator kind (see `BfValidationMessages`).                                           |
+| Name                    | Type                                          | Default                                                                          | Description                                                                                                    |
+| ----------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `loading`               | `string`                                      | `'Loading'`                                                                      | bf-spinner's accessible name (a loading bf-button's spinner is decorative and has none).                       |
+| `dismiss`               | `string`                                      | `'Dismiss'`                                                                      | bf-alert's dismiss button.                                                                                     |
+| `tabBar`                | `string`                                      | `'Main'`                                                                         | bf-tab-bar's navigation name.                                                                                  |
+| `tabBadge`              | `(count: number) => string`                   | `` (count) => `${count} new` ``                                                  | bf-tab's announcement of a numeric badge.                                                                      |
+| `back`                  | `string`                                      | `'Back'`                                                                         | bf-back-button's label.                                                                                        |
+| `ok`                    | `string`                                      | `'OK'`                                                                           | BfAlertDialogService's default button.                                                                         |
+| `cancel`                | `string`                                      | `'Cancel'`                                                                       | BfActionSheetService's cancel row.                                                                             |
+| `actions`               | `string`                                      | `'Actions'`                                                                      | An action sheet's name when it has no title.                                                                   |
+| `sheet`                 | `string`                                      | `'Sheet'`                                                                        | bf-sheet's name without an ariaLabel or heading.                                                               |
+| `modal`                 | `string`                                      | `'Modal'`                                                                        | bf-modal's name without an ariaLabel or heading.                                                               |
+| `refreshing`            | `string`                                      | `'Refreshing'`                                                                   | bf-refresher's status while refreshing.                                                                        |
+| `close`                 | `string`                                      | `'Close'`                                                                        | bf-dialog's and bf-side-panel's close button, and bf-sheet's screen-reader Close.                              |
+| `expand`                | `string`                                      | `'Expand'`                                                                       | bf-sheet's grabber button below the top snap point: the next press expands the sheet.                          |
+| `collapse`              | `string`                                      | `'Collapse'`                                                                     | bf-sheet's grabber button at the top snap point: the next press collapses the sheet.                           |
+| `sheetPosition`         | `(position: number, count: number) => string` | `` (position, count) => `Sheet at ${position} of ${count}` ``                    | bf-sheet's snap position (1-based), announced politely when it changes and part of the grabber button's name.  |
+| `dialog`                | `string`                                      | `'Dialog'`                                                                       | A dialog's or side panel's name without an ariaLabel, a title or a heading.                                    |
+| `notifications`         | `string`                                      | `'Notifications'`                                                                | The desktop toast stack's region name.                                                                         |
+| `tableSelectAll`        | `string`                                      | `'Select all rows'`                                                              | bf-table's header checkbox, which selects or clears every row.                                                 |
+| `tableSortBy`           | `string`                                      | `'Sort by'`                                                                      | The label of a stacked bf-table's sort select.                                                                 |
+| `tableSortAscending`    | `(column: string) => string`                  | `` (column) => `${column}, ascending` ``                                         | A stacked bf-table's sort option for a column in ascending order.                                              |
+| `tableSortDescending`   | `(column: string) => string`                  | `` (column) => `${column}, descending` ``                                        | A stacked bf-table's sort option for a column in descending order.                                             |
+| `theme`                 | `string`                                      | `'Theme'`                                                                        | bf-theme-switch's and bf-theme-menu-button's name without a label.                                             |
+| `themeSystem`           | `string`                                      | `'System'`                                                                       | The theme choice that follows the system's colour scheme.                                                      |
+| `themeLight`            | `string`                                      | `'Light'`                                                                        | The theme choice that forces the light colour scheme.                                                          |
+| `themeDark`             | `string`                                      | `'Dark'`                                                                         | The theme choice that forces the dark colour scheme.                                                           |
+| `breadcrumb`            | `string`                                      | `'Breadcrumb'`                                                                   | bf-breadcrumb's navigation name.                                                                               |
+| `breadcrumbExpand`      | `(count: number) => string`                   | ``(count) => (count === 1 ? 'Show 1 more level' : `Show ${count} more levels`)`` | bf-breadcrumb's ellipsis button, which shows the levels a `maxItems` trail hides.                              |
+| `navigation`            | `string`                                      | `'Main'`                                                                         | bf-sidebar's and bf-top-nav's navigation name.                                                                 |
+| `navBadge`              | `(count: number) => string`                   | `` (count) => `${count} new` ``                                                  | a[bfNavItem]'s announcement of its count badge.                                                                |
+| `sidebarCollapse`       | `string`                                      | `'Collapse sidebar'`                                                             | bf-sidebar-toggle's name and tooltip while the sidebar is expanded.                                            |
+| `sidebarExpand`         | `string`                                      | `'Expand sidebar'`                                                               | bf-sidebar-toggle's name and tooltip while the sidebar is an icon rail.                                        |
+| `skipToContent`         | `string`                                      | `'Skip to main content'`                                                         | bf-app-frame's skip link, the first stop of the tab order, which moves focus to the content.                   |
+| `pagination`            | `string`                                      | `'Pagination'`                                                                   | bf-pagination's navigation name.                                                                               |
+| `previousPage`          | `string`                                      | `'Previous page'`                                                                | bf-pagination's button to the previous page.                                                                   |
+| `nextPage`              | `string`                                      | `'Next page'`                                                                    | bf-pagination's button to the next page.                                                                       |
+| `pageOf`                | `(page: number, count: number) => string`     | `` (page, count) => `Page ${page} of ${count}` ``                                | bf-pagination's compact position text, such as "Page 3 of 12".                                                 |
+| `goToPage`              | `(page: number) => string`                    | `` (page) => `Page ${page}` ``                                                   | bf-pagination's name of one page button, such as "Page 3".                                                     |
+| `tabGroup`              | `string`                                      | `'Tabs'`                                                                         | bf-tab-group's tablist name.                                                                                   |
+| `calendarPreviousMonth` | `string`                                      | `'Previous month'`                                                               | bf-calendar's button that shows the previous month.                                                            |
+| `calendarNextMonth`     | `string`                                      | `'Next month'`                                                                   | bf-calendar's button that shows the next month.                                                                |
+| `calendarChooseMonth`   | `string`                                      | `'Choose month'`                                                                 | bf-calendar's title button in the day view, which opens the month view; read after the visible month and year. |
+| `calendarChooseYear`    | `string`                                      | `'Choose year'`                                                                  | bf-calendar's title button in the month view, which opens the year view; read after the visible year.          |
+| `statTrendUp`           | `string`                                      | `'Up'`                                                                           | bf-stat's hidden direction word before an upward delta, so colour is never the only signal.                    |
+| `statTrendDown`         | `string`                                      | `'Down'`                                                                         | bf-stat's hidden direction word before a downward delta.                                                       |
+| `statTrendFlat`         | `string`                                      | `'No change'`                                                                    | bf-stat's hidden direction word before an unchanged (flat) delta.                                              |
+| `comboboxEmpty`         | `string`                                      | `'No results'`                                                                   | bf-combobox's and bf-multi-combobox's list row when no option matches the typed text.                          |
+| `comboboxRemove`        | `(label: string) => string`                   | `` (label) => `Remove ${label}` ``                                               | bf-multi-combobox's remove button on a picked value's tag.                                                     |
+| `dateInputDay`          | `string`                                      | `'Day'`                                                                          | The day part of bf-date-input and bf-datetime-input; its first letter is the part's placeholder ("dd").        |
+| `dateInputMonth`        | `string`                                      | `'Month'`                                                                        | The month part of bf-date-input and bf-datetime-input; its first letter is the part's placeholder ("mm").      |
+| `dateInputYear`         | `string`                                      | `'Year'`                                                                         | The year part of bf-date-input and bf-datetime-input; its first letter is the part's placeholder ("yyyy").     |
+| `dateInputOpenCalendar` | `string`                                      | `'Choose date'`                                                                  | The button of bf-date-input and bf-datetime-input that opens the calendar, and the panel's name.               |
+| `dateInputInvalid`      | `string`                                      | `'Enter a valid date'`                                                           | The error of bf-date-input and bf-datetime-input while the date is incomplete or does not exist (31 February). |
+| `dateInputUnavailable`  | `string`                                      | `'This date is not available'`                                                   | The error of bf-date-input and bf-datetime-input for a typed date that `disabledDate` rules out.               |
+| `timeInputHour`         | `string`                                      | `'Hour'`                                                                         | The hour part of bf-time-input and bf-datetime-input; its first letter is the part's placeholder ("hh").       |
+| `timeInputMinute`       | `string`                                      | `'Minute'`                                                                       | The minute part of bf-time-input and bf-datetime-input; its first letter is the part's placeholder ("mm").     |
+| `timeInputSecond`       | `string`                                      | `'Second'`                                                                       | The second part of bf-time-input with `seconds`; its first letter is the part's placeholder ("ss").            |
+| `timeInputDayPeriod`    | `string`                                      | `'AM/PM'`                                                                        | The AM/PM part of bf-time-input and bf-datetime-input under a 12-hour clock.                                   |
+| `timeInputOpenList`     | `string`                                      | `'Choose time'`                                                                  | The button of bf-time-input that opens the list of times, and the list's name.                                 |
+| `timeInputInvalid`      | `string`                                      | `'Enter a valid time'`                                                           | The error of bf-time-input and bf-datetime-input while the time is incomplete.                                 |
+| `timeInputMin`          | `(time: string) => string`                    | `` (time) => `Pick ${time} or later` ``                                          | The error of bf-time-input and bf-datetime-input below `min`, given the limit as the locale writes it.         |
+| `timeInputMax`          | `(time: string) => string`                    | `` (time) => `Pick ${time} or earlier` ``                                        | The error of bf-time-input and bf-datetime-input above `max`, given the limit as the locale writes it.         |
+| `chart`                 | `string`                                      | `'Chart'`                                                                        | The name of a chart from `@bitforgehq/ui/charts` that has no `label` (and no `bf-chart-card` title).           |
+| `chartLegend`           | `string`                                      | `'Legend'`                                                                       | The name of a chart's legend, the group of buttons that show and hide its series.                              |
+| `chartValues`           | `string`                                      | `'Data points, arrow keys move between them'`                                    | The name of a chart's plot, the focusable area whose arrow keys move between the values.                       |
+| `chartShowData`         | `string`                                      | `'Show data'`                                                                    | A chart's button that shows its data as a table.                                                               |
+| `chartHideData`         | `string`                                      | `'Hide data'`                                                                    | A chart's button that hides its data table again.                                                              |
+| `chartCategory`         | `string`                                      | `'Category'`                                                                     | The first column header of a chart's data table.                                                               |
+| `chartValue`            | `string`                                      | `'Value'`                                                                        | The value column header of a bf-donut-chart's data table.                                                      |
+| `chartEmpty`            | `string`                                      | `'No data to show'`                                                              | bf-chart-card's text when it has no data and no `empty` slot.                                                  |
+| `chartError`            | `string`                                      | `'The data could not be loaded'`                                                 | bf-chart-card's text when its data failed to load and it has no `error` slot.                                  |
+| `validation`            | `BfValidationMessages`                        | required                                                                         | Default error text per validator kind (see `BfValidationMessages`).                                            |
 
 ## Uses
 

package/ai/reference/bf-menu-button-variant.md

@@ -25,3 +25,4 @@ type BfMenuButtonVariant = 'outline' | 'text' | 'tonal'
 ## Used by
 
 - [bf-menu-button](../components/menu-button.md)
+- [bf-theme-menu-button](../components/theme-menu-button.md)

package/ai/reference/bf-menu-placement.md

@@ -27,3 +27,4 @@ type BfMenuPlacement = 'below-start' | 'below-end' | 'above-start' | 'above-end'
 
 - [bf-menu-button](../components/menu-button.md)
 - [BfMenuTriggerDirective](bf-menu-trigger-directive.md)
+- [bf-theme-menu-button](../components/theme-menu-button.md)

package/ai/reference/bf-overlay-options.md

@@ -14,37 +14,38 @@ import { type BfOverlayOptions } from '@bitforgehq/ui/overlay';
 
 ## Properties
 
-| Name                | Type                                                                  | Default                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| ------------------- | --------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `data`              | `unknown`                                                             |                         | Injected into the content as `BF_OVERLAY_DATA`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `panelClass`        | `string[]`                                                            |                         | Extra classes on the panel (it always carries `bf-overlay-panel`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| `backdrop`          | `boolean`                                                             | `true`                  | Renders a backdrop behind the panel (default true; never for passive overlays).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `backdropClass`     | `string`                                                              | `'bf-overlay-backdrop'` | Class of the backdrop (default `bf-overlay-backdrop`: a black scrim, 40 % light / 60 % dark).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `dismissOnBackdrop` | `boolean`                                                             | `true`                  | A backdrop click closes the overlay (default true).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `dismissOnEscape`   | `boolean`                                                             | `true`                  | `Escape` closes the overlay (default true).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
-| `onEscape`          | `() => void`                                                          |                         | Runs instead of closing when the overlay is on top and `Escape` is pressed (e.g. an alert resolving with its cancel button). The key is always claimed by the topmost non-passive overlay, so it never reaches an overlay underneath.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `role`              | `BfOverlayRole` (`'dialog' \| 'alertdialog' \| 'status'`)             | `'dialog'`              | Role of the panel (default `dialog`; passive overlays get none unless one is given — a toast is announced through `LiveAnnouncer`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `ariaLabel`         | `string`                                                              |                         | Accessible name of the panel.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `ariaLabelledBy`    | `string`                                                              |                         | Id of the element naming the panel. Dropped after the content renders when no element inside the panel carries it and `ariaLabel` is unset, so the panel never points at nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
-| `ariaDescribedBy`   | `string`                                                              |                         | Id of the element describing the panel (an alert's message).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `trapFocus`         | `boolean`                                                             | `true`                  | Traps Tab focus inside the panel (default true).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| `autoFocus`         | `BfOverlayAutoFocus` (`'first-tabbable' \| 'panel'`)                  | `'first-tabbable'`      | Where focus goes on open (non-passive overlays): `first-tabbable` (default) — the element marked `[autofocus]`/`[cdkFocusInitial]` when it is focusable (a control, or any element with a `tabindex`, also `-1`), else the first tabbable element inside it, else (all its controls disabled) the first tabbable element of the panel, else the panel; `panel` — the panel itself, so a long text is read from its start (APG dialog pattern). `first-tabbable` skips the library's own container controls (`bf-sheet`'s hidden Close and grabber button, marked with the internal `data-bf-overlay-chrome`): they stay in the Tab order but never take the initial focus, so it lands on your content. |
-| `restoreFocus`      | `boolean`                                                             | `true`                  | Returns focus to the previously focused element on close (default true); when that element is gone, to the topmost overlay still open, else focus stays on the body (move it yourself, e.g. to the next row after a delete).                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `position`          | `BfOverlayPosition` (`'bottom' \| 'center' \| 'top' \| 'fullscreen'`) | `'center'`              | Placement of the panel (default `center`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `closeOnNavigation` | `boolean`                                                             | `true`                  | Closes the overlay when the URL path changes (default true; false for passive overlays): a router navigation, a link, the browser's back and forward buttons. Query- or fragment-only changes never close; a matrix-parameter change (`/a;x=1`) is a path change and closes. Read from `Location.onUrlChange()`, so no router is needed, and a `history.pushState()` made outside Angular's `Location` is not seen. An overlay opened before the first navigation ends (root component, `APP_INITIALIZER`) closes when the start URL redirects: open it after the first `NavigationEnd`, or pass false.                                                                                                 |
-| `onNavigation`      | `() => void`                                                          |                         | Runs instead of `close()` when a navigation closes the overlay (e.g. an alert answering with its cancel id); it should close the overlay.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `backPriority`      | `number`                                                              | `100`                   | Priority of the hardware back handler that closes the overlay (default 100).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `countsAsModal`     | `boolean`                                                             | `false`                 | Counts towards `BfOverlayStack.depth()` / `--bf-modal-depth` (default false).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| `passive`           | `boolean`                                                             | `false`                 | A passive overlay (a toast) has no backdrop, no focus trap, does not move focus, does not count in `BfOverlayStack.count()`, registers no back handler and leaves the page interactive.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `enter`             | `(el: HTMLElement) => Animation \| null`                              | `fadeIn`                | Enter animation of the panel (default `fadeIn`); return null for none.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
-| `exit`              | `(el: HTMLElement) => Animation \| null`                              | `fadeOut`               | Exit animation of the panel (default `fadeOut`), awaited before detaching.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `injector`          | `Injector`                                                            |                         | Parent of the content's injector (default the root injector), so the content resolves the opener's providers, e.g. a feature-level `provideBfLabels()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `providers`         | `(ref: BfOverlayRef<unknown>) => StaticProvider[]`                    |                         | Extra providers of the content's injector, next to `BF_OVERLAY_DATA` and `BfOverlayRef`, built with the new overlay's ref (e.g. a typed ref of a service built on the core).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Name                | Type                                                                            | Default                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------- | ------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data`              | `unknown`                                                                       |                         | Injected into the content as `BF_OVERLAY_DATA`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `panelClass`        | `string[]`                                                                      |                         | Extra classes on the panel (it always carries `bf-overlay-panel`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `backdrop`          | `boolean`                                                                       | `true`                  | Renders a backdrop behind the panel (default true; never for passive overlays).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `backdropClass`     | `string`                                                                        | `'bf-overlay-backdrop'` | Class of the backdrop (default `bf-overlay-backdrop`: a black scrim, 40 % light / 60 % dark).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `dismissOnBackdrop` | `boolean`                                                                       | `true`                  | A backdrop click closes the overlay (default true).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `dismissOnEscape`   | `boolean`                                                                       | `true`                  | `Escape` closes the overlay (default true).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `onEscape`          | `() => void`                                                                    |                         | Runs instead of closing when the overlay is on top and `Escape` is pressed (e.g. an alert resolving with its cancel button). The key is always claimed by the topmost non-passive overlay, so it never reaches an overlay underneath.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `role`              | `BfOverlayRole` (`'dialog' \| 'alertdialog' \| 'status'`)                       | `'dialog'`              | Role of the panel (default `dialog`; passive overlays get none unless one is given — a toast is announced through `LiveAnnouncer`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `ariaLabel`         | `string`                                                                        |                         | Accessible name of the panel.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `ariaLabelledBy`    | `string`                                                                        |                         | Id of the element naming the panel. Dropped after the content renders when no element inside the panel carries it and `ariaLabel` is unset, so the panel never points at nothing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `ariaDescribedBy`   | `string`                                                                        |                         | Id of the element describing the panel (an alert's message).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `trapFocus`         | `boolean`                                                                       | `true`                  | Traps Tab focus inside the panel (default true).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `autoFocus`         | `BfOverlayAutoFocus` (`'first-tabbable' \| 'panel'`)                            | `'first-tabbable'`      | Where focus goes on open (non-passive overlays): `first-tabbable` (default) — the element marked `[autofocus]`/`[cdkFocusInitial]` when it is focusable (a control, or any element with a `tabindex`, also `-1`), else the first tabbable element inside it, else (all its controls disabled) the first tabbable element of the panel, else the panel; `panel` — the panel itself, so a long text is read from its start (APG dialog pattern). `first-tabbable` skips the library's own container controls (`bf-sheet`'s hidden Close and grabber button, marked with the internal `data-bf-overlay-chrome`): they stay in the Tab order but never take the initial focus, so it lands on your content. |
+| `restoreFocus`      | `boolean`                                                                       | `true`                  | Returns focus to the previously focused element on close (default true); when that element is gone, to the topmost overlay still open, else focus stays on the body (move it yourself, e.g. to the next row after a delete).                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `position`          | `BfOverlayPlacement` (`'bottom' \| 'center' \| 'top' \| 'fullscreen' \| 'end'`) | `'center'`              | Placement of the panel (default `center`); `end` is full height at the inline end edge.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `closeOnNavigation` | `boolean`                                                                       | `true`                  | Closes the overlay when the URL path changes (default true; false for passive overlays): a router navigation, a link, the browser's back and forward buttons. Query- or fragment-only changes never close; a matrix-parameter change (`/a;x=1`) is a path change and closes. Read from `Location.onUrlChange()`, so no router is needed, and a `history.pushState()` made outside Angular's `Location` is not seen. An overlay opened before the first navigation ends (root component, `APP_INITIALIZER`) closes when the start URL redirects: open it after the first `NavigationEnd`, or pass false.                                                                                                 |
+| `onNavigation`      | `() => void`                                                                    |                         | Runs instead of `close()` when a navigation closes the overlay (e.g. an alert answering with its cancel id); it should close the overlay.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `backPriority`      | `number`                                                                        | `100`                   | Priority of the hardware back handler that closes the overlay (default 100).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `countsAsModal`     | `boolean`                                                                       | `false`                 | Counts towards `BfOverlayStack.depth()` / `--bf-modal-depth` (default false).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `passive`           | `boolean`                                                                       | `false`                 | A passive overlay (a toast) has no backdrop, no focus trap, does not move focus, does not count in `BfOverlayStack.count()`, registers no back handler and leaves the page interactive.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `modal`             | `boolean`                                                                       | `true`                  | A modal overlay (default true) has a backdrop, traps focus, is `aria-modal`, blocks document scroll and makes the page behind it `inert`. A non-modal one (a side panel beside the page) has none of these and is not in `BfOverlayStack`: focus moves in, the page stays usable, `Escape` closes it only while focus is inside it, and on close focus returns to the opener only from inside it. Ignored for passive overlays.                                                                                                                                                                                                                                                                         |
+| `enter`             | `(el: HTMLElement) => Animation \| null`                                        | `fadeIn`                | Enter animation of the panel (default `fadeIn`); return null for none.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `exit`              | `(el: HTMLElement) => Animation \| null`                                        | `fadeOut`               | Exit animation of the panel (default `fadeOut`), awaited before detaching.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `injector`          | `Injector`                                                                      |                         | Parent of the content's injector (default the root injector), so the content resolves the opener's providers, e.g. a feature-level `provideBfLabels()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `providers`         | `(ref: BfOverlayRef<unknown>) => StaticProvider[]`                              |                         | Extra providers of the content's injector, next to `BF_OVERLAY_DATA` and `BfOverlayRef`, built with the new overlay's ref (e.g. a typed ref of a service built on the core).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 
 ## Uses
 
 - [BfOverlayAutoFocus](bf-overlay-auto-focus.md)
-- [BfOverlayPosition](bf-overlay-position.md)
+- [BfOverlayPlacement](bf-overlay-placement.md)
 - [BfOverlayRef](bf-overlay-ref.md)
 - [BfOverlayRole](bf-overlay-role.md)
 

package/ai/reference/bf-overlay-placement.md

@@ -0,0 +1,34 @@
+# BfOverlayPlacement
+
+Where an overlay panel sits: a viewport position or full height at the end
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.1
+
+Where an overlay panel sits: a `BfOverlayPosition`, or `end`, full height against the inline
+end edge of the viewport (the right in a left-to-right page, the left under `dir="rtl"`).
+
+```ts
+import { type BfOverlayPlacement } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfOverlayPlacement = BfOverlayPosition | 'end'
+```
+
+## Values
+
+- `bottom`
+- `center`
+- `top`
+- `fullscreen`
+- `end`
+
+## Uses
+
+- [BfOverlayPosition](bf-overlay-position.md)
+
+## Used by
+
+- [BfOverlayOptions](bf-overlay-options.md)

package/ai/reference/bf-overlay-position.md

@@ -27,4 +27,4 @@ type BfOverlayPosition = 'bottom' | 'center' | 'top' | 'fullscreen'
 
 ## Used by
 
-- [BfOverlayOptions](bf-overlay-options.md)
+- [BfOverlayPlacement](bf-overlay-placement.md)

package/ai/reference/bf-overlay-service.md

@@ -18,9 +18,11 @@ unless the host handles the system back itself (`handlesSystemBack`). An overlay
 close on it (`dismissOnEscape: false` without `onEscape`, or an `onEscape` that keeps it open)
 swallows Android web back for as long as it is open, as a non-dismissible sheet swallows the
 hardware back button. A navigation to another URL path closes every non-passive
-overlay (`closeOnNavigation`, read from `Location`, so no router is needed). The content
-injects `BF_OVERLAY_DATA` and `BfOverlayRef` (plus any `providers`). `BfDialogService` and the
-`/mobile` sheet, modal, toast, action sheet and alert services build on it.
+overlay (`closeOnNavigation`, read from `Location`, so no router is needed). `modal: false`
+(a side panel beside the page) drops the backdrop, the trap, `aria-modal`, the scroll lock and
+the `inert` page. The content injects `BF_OVERLAY_DATA` and `BfOverlayRef` (plus any
+`providers`). `BfDialogService`, `BfSidePanelService` and the `/mobile` sheet, modal, toast,
+action sheet and alert services build on it.
 
 ```ts
 import { BfOverlayService } from '@bitforgehq/ui/overlay';

package/ai/reference/bf-page-header-heading-level.md

@@ -0,0 +1,26 @@
+# BfPageHeaderHeadingLevel
+
+The heading level of a page header title, one for a page or two
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+The heading level of a `bf-page-header` title: `1` for the page, `2` for a section header.
+
+```ts
+import { type BfPageHeaderHeadingLevel } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfPageHeaderHeadingLevel = 1 | 2
+```
+
+## Values
+
+- `1`
+- `2`
+
+## Used by
+
+- [bf-page-header](../components/page-header.md)

package/ai/reference/bf-pagination-harness.md

@@ -0,0 +1,61 @@
+# BfPaginationHarness
+
+Test harness for pagination: reads the current page and moves between pages
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for `bf-pagination`. It reads the current page and the page count as numbers, so a test
+never parses the "Page 3 of 12" text, and clicks the buttons as a user would.
+
+```ts
+import { BfPaginationHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfPaginationHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The navigation's accessible name (`label`, else "Pagination").
+
+### `getCurrentPage(): Promise<number>`
+
+The page shown as current, 1-based.
+
+### `getPageCount(): Promise<number>`
+
+The number of pages in effect (`pageCount`, else `total` over `pageSize`, at least 1).
+
+### `getVisiblePages(): Promise<number[]>`
+
+The page numbers the row shows right now, in order, without the gaps; empty when compact.
+
+### `goTo(page: number): Promise<void>`
+
+Clicks the button of this page, as a user would. Throws when the row does not show it (behind
+a gap, or in a compact pagination).
+
+| Parameter | Type     | Description                |
+| --------- | -------- | -------------------------- |
+| `page`    | `number` | The 1-based page to go to. |
+
+### `next(): Promise<void>`
+
+Clicks Next. Throws on the last page, where the button is disabled.
+
+### `previous(): Promise<void>`
+
+Clicks Previous. Throws on the first page, where the button is disabled.
+
+### `isPreviousDisabled(): Promise<boolean>`
+
+Whether Previous is disabled (on the first page).
+
+### `isNextDisabled(): Promise<boolean>`
+
+Whether Next is disabled (on the last page).

package/ai/reference/bf-platform-service.md

@@ -6,15 +6,17 @@ Service from `@bitforgehq/ui/mobile` · since 0.2.0
 
 Platform facts and the app theme: native or web, iOS or Android, the shell mode that follows
 from it, and the user's theme choice (system, light, dark) reflected as the `dark` class on
-`<html>`. `matchMedia('(prefers-color-scheme: dark)')` is the single source for the system
-theme on every platform.
+`<html>`. The theme is `BfColorSchemeService` from `@bitforgehq/ui` (the Capacitor-free colour
+scheme a desktop app uses through `provideBfColorScheme()`): `theme` and `dark` are its
+`scheme` and `dark` signals, and `matchMedia('(prefers-color-scheme: dark)')` is the single
+source for the system theme on every platform.
 
 The `theme`/`dark` signals always compute, but the `<html>` class and storage writes
-only run when `provideBfShell()` provided `BF_SHELL_CONFIG` — i.e. this service is the app's
-own shell, not merely injected by something that wants `platform`/`mode`. Without it (e.g. a
-docs demo that instantiates `BfPlatformService` directly to preview `bf-tabs`), this service
-would otherwise fight the host page's own theme: its `effect` runs on construction and would
-immediately overwrite `<html class="dark">` with whatever `prefers-color-scheme` says.
+only run when `provideBfShell()` provided `BF_SHELL_CONFIG` (or the app provided
+`provideBfColorScheme()`) — i.e. this service is the app's own shell, not merely injected by
+something that wants `platform`/`mode`. Without it (e.g. a docs demo that instantiates
+`BfPlatformService` directly to preview `bf-tabs`), this service would otherwise fight the host
+page's own theme, overwriting `<html class="dark">` with whatever `prefers-color-scheme` says.
 
 With `provideBfShell()` on a native platform it also makes the viewport meta forbid zoom
 (`maximum-scale=1, user-scalable=no`, other directives kept; the meta is created if missing):
@@ -34,19 +36,19 @@ import { BfPlatformService } from '@bitforgehq/ui/mobile';
 
 ## Properties
 
-| Name       | Type                                         | Default | Description                                                                                         |
-| ---------- | -------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
-| `isNative` | `boolean`                                    |         | True inside the native iOS or Android app, false in a browser.                                      |
-| `platform` | `BfPlatform` (`'ios' \| 'android' \| 'web'`) |         | The platform the app runs on.                                                                       |
-| `mode`     | `Signal<BfShellMode>`                        |         | The platform's shell mode: `ios` on iOS, else `md`; `resolveShellMode()` applies the config.        |
-| `theme`    | `WritableSignal<BfTheme>`                    |         | The user's theme choice, stored in `BF_THEME_STORAGE` (`localStorage`); set it with `theme.set(…)`. |
-| `dark`     | `Signal<boolean>`                            |         | Whether the app is dark now: the theme choice, or the system's under `system`.                      |
+| Name       | Type                                         | Default | Description                                                                                                                                           |
+| ---------- | -------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `isNative` | `boolean`                                    |         | True inside the native iOS or Android app, false in a browser.                                                                                        |
+| `platform` | `BfPlatform` (`'ios' \| 'android' \| 'web'`) |         | The platform the app runs on.                                                                                                                         |
+| `mode`     | `Signal<BfShellMode>`                        |         | The platform's shell mode: `ios` on iOS, else `md`; `resolveShellMode()` applies the config.                                                          |
+| `theme`    | `WritableSignal<BfColorScheme>`              |         | The user's theme choice, stored in `BF_THEME_STORAGE` (`localStorage`); set it with `theme.set(…)`. The same signal as `BfColorSchemeService.scheme`. |
+| `dark`     | `Signal<boolean>`                            |         | Whether the app is dark now: the theme choice, or the system's under `system`. The same signal as `BfColorSchemeService.dark`.                        |
 
 ## Uses
 
+- [BfColorScheme](bf-color-scheme.md)
 - [BfPlatform](bf-platform.md)
 - [BfShellMode](bf-shell-mode.md)
-- [BfTheme](bf-theme.md)
 
 ## Used by
 

package/ai/reference/bf-popover-harness.md

@@ -0,0 +1,42 @@
+# BfPopoverHarness
+
+Test harness for a popover: opens and closes it and reads its panel
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for an element with a `[bfPopoverTriggerFor]` and the `bf-popover` it opens, which
+renders in the CDK overlay container while open (found through the trigger's
+`aria-controls`). Its `label` filter matches the trigger's accessible name (`aria-label`, else
+its text).
+
+```ts
+import { BfPopoverHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfPopoverHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The trigger's accessible name: its control's `aria-label`, else its text.
+
+### `open(): Promise<void>`
+
+Opens the popover with a click; does nothing while it is open.
+
+### `close(): Promise<void>`
+
+Closes the popover with `Escape`, as a user would; does nothing while it is closed.
+
+### `isOpen(): Promise<boolean>`
+
+Whether the popover is open (`aria-expanded`).
+
+### `getPanelText(): Promise<string>`
+
+The open panel's text, opening it first when it is closed.

package/ai/reference/bf-popover-placement.md

@@ -0,0 +1,28 @@
+# BfPopoverPlacement
+
+Where a popover opens against its trigger, above or below, at either end
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.1
+
+Where a popover opens against its trigger; `start`/`end` follow the text direction.
+
+```ts
+import { type BfPopoverPlacement } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfPopoverPlacement = 'below-start' | 'below-end' | 'above-start' | 'above-end'
+```
+
+## Values
+
+- `below-start`
+- `below-end`
+- `above-start`
+- `above-end`
+
+## Used by
+
+- [BfPopoverTriggerDirective](bf-popover-trigger-directive.md)