@bitforgehq/ui 0.3.0 → 0.3.1

package/ai/reference/bf-date-input-harness.md

@@ -0,0 +1,67 @@
+# BfDateInputHarness
+
+Test harness for the date input: types a date or picks one in its calendar
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for `bf-date-input`. It reads and types the field as a user sees it (in its locale's
+order) and picks a date through the calendar popover with `BfCalendarHarness`.
+
+```ts
+import { BfDateInputHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfDateInputHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The visible label without the required mark, else the field's `aria-label`.
+
+### `getValue(): Promise<string>`
+
+The field's text as the locale shows it ("14/10/2026"); the ISO value in native mode.
+
+### `setValue(text: string): Promise<void>`
+
+Types a date as a user would: clears the field, then types each run of digits (or letters)
+into the next part in the field's order, such as "14/10/2026" in an en-GB field. In native mode it sets the
+platform input to the ISO value.
+
+| Parameter | Type     | Description                     |
+| --------- | -------- | ------------------------------- |
+| `text`    | `string` | The date as the field shows it. |
+
+### `clear(): Promise<void>`
+
+Clears every part with `Backspace`, as a user would.
+
+### `isInvalid(): Promise<boolean>`
+
+Whether the field shows its error state (`aria-invalid` on its parts or native input).
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the field is disabled.
+
+### `openPicker(): Promise<void>`
+
+Opens the calendar popover with a click on its button; throws when the field has none or it is disabled.
+
+### `isPickerOpen(): Promise<boolean>`
+
+Whether the calendar popover is open (`aria-expanded` on its button).
+
+### `pickDate(iso: string): Promise<void>`
+
+Picks a date in the calendar as a user would: opens the popover (when closed), then picks the
+day through the calendar's harness, which closes it.
+
+| Parameter | Type     | Description                                 |
+| --------- | -------- | ------------------------------------------- |
+| `iso`     | `string` | The ISO date to pick, such as '2026-11-03'. |

package/ai/reference/bf-date-input-picker.md

@@ -0,0 +1,27 @@
+# BfDateInputPicker
+
+Whether a date input offers a calendar popover besides typing
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.1
+
+How `bf-date-input` picks a date besides typing: `calendar` adds a button that opens a
+`bf-calendar` in a popover, `none` keeps the field typed only.
+
+```ts
+import { type BfDateInputPicker } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfDateInputPicker = 'calendar' | 'none'
+```
+
+## Values
+
+- `calendar`
+- `none`
+
+## Used by
+
+- [bf-date-input](../components/date-input.md)

package/ai/reference/bf-date-time-input-harness.md

@@ -0,0 +1,76 @@
+# BfDateTimeInputHarness
+
+Test harness for the date and time input: types or picks a date and time
+
+Class from `@bitforgehq/ui/testing` · since 0.3.1
+
+Harness for `bf-datetime-input`. It reads and types the field as a user sees it and picks the
+date in the popover's calendar and the time in its list.
+
+```ts
+import { BfDateTimeInputHarness } from '@bitforgehq/ui/testing';
+```
+
+## Signature
+
+```ts
+class BfDateTimeInputHarness extends ComponentHarness
+```
+
+## Methods
+
+### `getLabel(): Promise<string>`
+
+The visible label without the required mark, else the field's `aria-label`.
+
+### `getValue(): Promise<string>`
+
+The field's text as the locale shows it ("14/10/2026, 09:30"); the ISO value in native mode.
+
+### `setValue(text: string): Promise<void>`
+
+Types a date and time as a user would: clears the field, then types each run of digits (or letters)
+into the next part in the field's order, such as "14/10/2026, 09:30" in an en-GB field. In native mode it sets the
+platform input to the ISO value.
+
+| Parameter | Type     | Description                              |
+| --------- | -------- | ---------------------------------------- |
+| `text`    | `string` | The date and time as the field shows it. |
+
+### `clear(): Promise<void>`
+
+Clears every part with `Backspace`, as a user would.
+
+### `isInvalid(): Promise<boolean>`
+
+Whether the field shows its error state (`aria-invalid` on its parts or native input).
+
+### `isDisabled(): Promise<boolean>`
+
+Whether the field is disabled.
+
+### `openPicker(): Promise<void>`
+
+Opens the popover with a click on its button; throws when the field has none or it is disabled.
+
+### `isPickerOpen(): Promise<boolean>`
+
+Whether the popover is open (`aria-expanded` on its button).
+
+### `pickDate(iso: string): Promise<void>`
+
+Picks a date in the calendar as a user would: opens the popover (when closed), then picks the
+day through the calendar's harness. The popover stays open, with focus on its time list.
+
+| Parameter | Type     | Description                                 |
+| --------- | -------- | ------------------------------------------- |
+| `iso`     | `string` | The ISO date to pick, such as '2026-11-03'. |
+
+### `pickTime(time: string): Promise<void>`
+
+Picks a time in the list as a user would: opens the popover (when closed), then clicks the
+time, which closes it. Throws for a time the list does not hold (off the `step`) or disables.
+
+| Parameter | Type     | Description                            |
+| --------- | -------- | -------------------------------------- |
+| `time`    | `string` | The ISO time to pick, such as '14:30'. |

package/ai/reference/bf-date-time-input-picker.md

@@ -0,0 +1,27 @@
+# BfDateTimeInputPicker
+
+Whether a date and time input offers a calendar and time list popover
+
+Type from `@bitforgehq/ui/overlay` · since 0.3.1
+
+How `bf-datetime-input` picks a date and time besides typing: `popover` adds a button that
+opens a calendar and a list of times side by side, `none` keeps the field typed only.
+
+```ts
+import { type BfDateTimeInputPicker } from '@bitforgehq/ui/overlay';
+```
+
+## Signature
+
+```ts
+type BfDateTimeInputPicker = 'popover' | 'none'
+```
+
+## Values
+
+- `popover`
+- `none`
+
+## Used by
+
+- [bf-datetime-input](../components/datetime-input.md)

package/ai/reference/bf-description-list-layout.md

@@ -0,0 +1,26 @@
+# BfDescriptionListLayout
+
+The two description list layouts, divided label-value rows or a grid of tiles
+
+Type from `@bitforgehq/ui` · since 0.3.1
+
+The layout of a `bf-description-list`: `rows` (label beside value, divided) or `grid` (tiles).
+
+```ts
+import { type BfDescriptionListLayout } from '@bitforgehq/ui';
+```
+
+## Signature
+
+```ts
+type BfDescriptionListLayout = 'rows' | 'grid'
+```
+
+## Values
+
+- `rows`
+- `grid`
+
+## Used by
+
+- [bf-description-list](../components/description-list.md)

package/ai/reference/bf-donut-slice.md

@@ -0,0 +1,22 @@
+# BfDonutSlice
+
+One labelled slice of a donut chart with its value
+
+Interface from `@bitforgehq/ui/charts` · since 0.3.1
+
+One slice of a `bf-donut-chart`.
+
+```ts
+import { type BfDonutSlice } from '@bitforgehq/ui/charts';
+```
+
+## Properties
+
+| Name    | Type     | Default  | Description                                                                                       |
+| ------- | -------- | -------- | ------------------------------------------------------------------------------------------------- |
+| `label` | `string` | required | The slice name, shown in the legend, the tooltip and the data table.                              |
+| `value` | `number` | required | The slice's value; its share of the total sets its angle. Zero and negative values draw no slice. |
+
+## Used by
+
+- [bf-donut-chart](../components/donut-chart.md)

package/ai/reference/bf-labels.md

@@ -12,26 +12,73 @@ 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.                                                 |
+| `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.                                                                |
+| `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)