@bitforgehq/ui 0.3.0 → 0.3.1

package/ai/components/theme-menu-button.md

@@ -0,0 +1,182 @@
+# bf-theme-menu-button
+
+Menu button with System, Light and Dark radio items bound to the colour scheme
+
+`BfThemeMenuButtonComponent` from `@bitforgehq/ui/overlay` · Overlays · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { type BfColorScheme } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfThemeMenuButtonComponent } from '@bitforgehq/ui/overlay';
+import { Moon, Sun, SunMoon } from 'lucide';
+
+/**
+ * The bf-theme-menu-button overview.
+ *
+ * Live demo of `bf-theme-menu-button`: an outline "Theme" button and an icon-only text button
+ * share one choice; the icon follows it (sun, moon, or both for System) and the status line
+ * reports it. The demo binds a local signal, so the docs site keeps its own theme; an app binds
+ * `BfColorSchemeService.scheme` instead.
+ */
+@Component({
+  selector: 'app-example-theme-menu-button-overview',
+  imports: [BfIconComponent, BfThemeMenuButtonComponent],
+  template: `
+    <div class="flex flex-col gap-4">
+      <div class="flex flex-wrap items-center gap-2">
+        <bf-theme-menu-button placement="below-start" [(value)]="scheme">
+          <bf-icon bfSlot="icon" [icon]="icon()" />
+        </bf-theme-menu-button>
+        <bf-theme-menu-button iconOnly variant="text" [(value)]="scheme">
+          <bf-icon bfSlot="icon" [icon]="icon()" />
+        </bf-theme-menu-button>
+      </div>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">
+        Theme: {{ scheme() }}
+      </p>
+    </div>
+  `,
+})
+export class ThemeMenuButtonOverviewExampleComponent {
+  /** Stands in for `BfColorSchemeService.scheme`. */
+  readonly scheme = signal<BfColorScheme>('system');
+  /** Sun for light, moon for dark, both while the choice follows the system. */
+  readonly icon = computed(() => ({ system: SunMoon, light: Sun, dark: Moon })[this.scheme()]);
+}
+```
+
+## Overview
+
+The colour scheme switch as a menu button, for a crowded top bar: a `bf-menu-button` whose menu
+holds System, Light and Dark as radio items, the current one marked with a dot. It holds a
+`BfColorScheme` and injects no service, so the app binds its own state, usually
+`BfColorSchemeService.scheme` (`BfPlatformService.theme` in a Capacitor app). The button shows
+`label` ("Theme") next to an optional icon, or only the icon with `iconOnly`.
+
+A theme menu button lets the user pick the app's colour scheme from a menu, from `@bitforgehq/ui/overlay` (needs `@angular/cdk`, no Capacitor). It is a `bf-menu-button` whose `bf-menu` holds System, Light and Dark as radio items, the current one marked with a dot. It holds a `BfColorScheme` and injects no service: the app binds its own state, normally `BfColorSchemeService.scheme`, with `[(value)]`. It works in both shells. Import `BfThemeMenuButtonComponent` from `@bitforgehq/ui/overlay`.
+
+## When to use
+
+Use `bf-theme-menu-button` in a crowded top bar or toolbar, where one button fits and three segments do not. Use [bf-theme-switch](https://bitforge-ui.web.app/components/theme-switch) instead on a settings page or in a header row with room, where the choice should stay visible. For a menu of other actions use [bf-menu-button](https://bitforge-ui.web.app/components/menu-button).
+
+## Icon only in a top bar
+
+`iconOnly` renders a round button holding only the icon, like `bf-icon-button`; `label` (else the `theme` label, "Theme") is then its accessible name. Project the icon in the `icon` slot: the component never picks one. Show the current look, a sun or a moon from `BfColorSchemeService.dark()`, so under System the icon says what the OS chose. Bind `[(value)]` to `BfColorSchemeService.scheme`: on desktop with `provideBfColorScheme()` in the app's providers, in a Capacitor app through `provideBfShell()` (where `BfPlatformService.theme` is the same signal). `changed` emits the new choice after a user pick; picking the current item again changes nothing.
+
+```ts
+import { Component, computed, inject } from '@angular/core';
+import { BfColorSchemeService } from '@bitforgehq/ui';
+import { BfIconComponent } from '@bitforgehq/ui/icons';
+import { BfThemeMenuButtonComponent } from '@bitforgehq/ui/overlay';
+import { Moon, Sun } from 'lucide';
+
+/**
+ * An icon-only theme menu in a top bar, bound to the app's colour scheme.
+ *
+ * `[(value)]` binds `BfColorSchemeService.scheme`: with `provideBfColorScheme()` in the app's
+ * providers (desktop) or `provideBfShell()` (Capacitor), a pick sets the `dark` class on `<html>`
+ * and is stored. The icon follows `dark()`, so under System it shows what the OS chose.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-theme-menu-button-top-bar',
+  imports: [BfIconComponent, BfThemeMenuButtonComponent],
+  template: `
+    <header class="border-border flex items-center gap-2 border-b px-4 py-2">
+      <span class="text-heading me-auto">Grove</span>
+      <bf-theme-menu-button iconOnly variant="text" [(value)]="colorScheme.scheme">
+        <bf-icon bfSlot="icon" [icon]="icon()" />
+      </bf-theme-menu-button>
+    </header>
+  `,
+})
+export class ThemeMenuButtonTopBarExampleComponent {
+  // app.config.ts: providers: [provideBfColorScheme()]
+  protected readonly colorScheme = inject(BfColorSchemeService);
+  protected readonly icon = computed(() => (this.colorScheme.dark() ? Moon : Sun));
+}
+```
+
+## Label and variants
+
+Without `iconOnly` the button shows `label` (else "Theme") after the optional icon, with the menu-button caret. It shows the name, not the current choice: the choice is the checked item in the menu (and the icon, when you project one), and a fixed text keeps the button's width and accessible name steady. `variant` is `outline` (default), `text` or `tonal`; `size` is `sm` 32, `md` 40 or `lg` 48 px, unset following `provideBfDefaults()`'s `controlSize`. `placement` defaults to `'below-end'`, since the button usually sits at the end of a bar.
+
+## Labels
+
+The items read `themeSystem`, `themeLight` and `themeDark`; the button reads `theme`. Translate them with `provideBfLabels()`.
+
+## Testing
+
+The component renders a `bf-menu-button`, so `BfMenuButtonHarness` from `@bitforgehq/ui/testing` drives it: filter it by `label: 'Theme'`, open it with `getMenu()`, then pick with `clickItem('Dark')`; `isChecked()` on a `BfMenuItemHarness` reads the dot.
+
+## Desktop
+
+The button hovers, presses and shows the focus ring like `bf-menu-button` (and `bf-icon-button` with `iconOnly`): a darker fill or text on hover with the pointer cursor, the ring on keyboard focus only. A click opens the menu; menu rows take the muted fill on hover. Under a fine pointer the visible box is the hit area. In a dense top bar set `size="sm"`, or `provideBfDefaults({ size: 'sm' })` in a component's `providers` ([density guide](https://bitforge-ui.web.app/density)). Add `provideBfColorScheme()` to the desktop app's providers; the Capacitor shell needs nothing more than `provideBfShell()`.
+
+## Theming
+
+The button consumes `bf-menu-button`'s tokens (`bf-button`'s, or `bf-icon-button`'s with `iconOnly`); the menu consumes `bf-menu`'s: `surface` with a `border` and `shadow-floating`, rows `text` with a `surface-muted` hover and focus, and the radio dot in the row's text colour.
+
+## Accessibility
+
+- The button is a native `<button type="button">` with `aria-haspopup="menu"` and `aria-expanded`; its name is the visible label, or `label` (`aria-label`) with `iconOnly`. The menu it opens is named by it.
+- The three items are `role="menuitemradio"` with `aria-checked`, so a screen reader announces the current choice. The dot is drawn in CSS and adds nothing to the name.
+- Choosing an item closes the menu and returns focus to the button.
+- Hit area: at least 32 px, 44 px under a coarse pointer, as `bf-menu-button`.
+
+### Keyboard
+
+The keys inside the open menu are on the [bf-menu](https://bitforge-ui.web.app/components/menu#keyboard) page.
+
+| Key                                                        | Action                                                         |
+| ---------------------------------------------------------- | -------------------------------------------------------------- |
+| <kbd>Enter</kbd> / <kbd>Space</kbd> / <kbd>ArrowDown</kbd> | Opens the menu and focuses System                              |
+| <kbd>ArrowUp</kbd>                                         | Opens the menu and focuses Dark                                |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>                        | In the open menu: picks the focused choice, closes the menu    |
+| <kbd>Escape</kbd>                                          | In the open menu: closes it without a change and returns focus |
+
+## Inputs
+
+| Name        | Type                                                                               | Default       | Description                                                                                                |
+| ----------- | ---------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------- |
+| `label`     | `string`                                                                           | `''`          | The button's text, and its accessible name with `iconOnly`; empty falls back to the `theme` label.         |
+| `iconOnly`  | `boolean`                                                                          | `false`       | Square button holding only the projected icon, like `bf-icon-button`.                                      |
+| `variant`   | `BfMenuButtonVariant` (`'outline' \| 'text' \| 'tonal'`)                           | `'outline'`   | Visual style: outline (default), text, tonal.                                                              |
+| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)                        | `undefined`   | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default). |
+| `placement` | `BfMenuPlacement` (`'below-start' \| 'below-end' \| 'above-start' \| 'above-end'`) | `'below-end'` | Where the menu opens against the button; it flips when it would overflow.                                  |
+| `value`     | `BfColorScheme` (`'system' \| 'light' \| 'dark'`)                                  | `'system'`    | The colour scheme choice; bind it two-way, usually to `BfColorSchemeService.scheme`. Two-way: `[(value)]`. |
+
+## Outputs
+
+| Name      | Payload                                           | Description                                                          |
+| --------- | ------------------------------------------------- | -------------------------------------------------------------------- |
+| `changed` | `BfColorScheme` (`'system' \| 'light' \| 'dark'`) | Emitted with the new choice right after the user picks another item. |
+
+## Slots
+
+- `icon`: The icon before the label, or the whole button with `iconOnly` (a sun or a moon).
+
+## Notes
+
+### Do
+
+- Project a sun or moon icon that follows `BfColorSchemeService.dark()`.
+- Bind `[(value)]` to `BfColorSchemeService.scheme` (or `BfPlatformService.theme` in the shell).
+
+### Don't
+
+- Don't use it where there is room for three segments; use `bf-theme-switch`, which shows the choice without a click.
+- Don't import it into a root-entry widget; it lives in `@bitforgehq/ui/overlay` because it opens a `bf-menu`.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-theme-menu-button` in `@bitforgehq/ui/overlay`: a `bf-menu-button` whose menu holds
+System, Light and Dark as radio items, for a crowded top bar. Same `value` / `changed` / `label`
+as `bf-theme-switch`, plus `iconOnly`, `variant`, `size`, `placement` (default `'below-end'`) and
+an `icon` slot for the consumer's sun or moon.

package/ai/components/theme-switch.md

@@ -0,0 +1,170 @@
+# bf-theme-switch
+
+Segmented System, Light and Dark switch bound two-way to the app colour scheme
+
+`BfThemeSwitchComponent` from `@bitforgehq/ui` · Forms · since 0.3.1
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfThemeSwitchComponent, type BfColorScheme } from '@bitforgehq/ui';
+
+/**
+ * The bf-theme-switch overview.
+ *
+ * Live demo of `bf-theme-switch`: the default switch and a `sm` one share one choice, and the
+ * status line reports it. The demo binds a local signal, so the docs site keeps its own theme; an
+ * app binds `BfColorSchemeService.scheme` instead.
+ */
+@Component({
+  selector: 'app-example-theme-switch-overview',
+  imports: [BfThemeSwitchComponent],
+  template: `
+    <div class="flex flex-col items-start gap-3">
+      <bf-theme-switch [(value)]="scheme" />
+      <bf-theme-switch size="sm" label="Theme (small)" [(value)]="scheme" />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">
+        Theme: {{ scheme() }}
+      </p>
+    </div>
+  `,
+})
+export class ThemeSwitchOverviewExampleComponent {
+  /** Stands in for `BfColorSchemeService.scheme`. */
+  readonly scheme = signal<BfColorScheme>('system');
+}
+```
+
+## Overview
+
+The colour scheme switch: System, Light and Dark as a three-option segmented control. It holds
+a `BfColorScheme` and injects no service, so the app binds its own state, usually
+`BfColorSchemeService.scheme` (`provideBfColorScheme()` on desktop, `provideBfShell()` in a
+Capacitor app, where `BfPlatformService.theme` is the same signal).
+
+A theme switch lets the user pick the app's colour scheme: System, Light or Dark, as a three-option `bf-segmented`. It holds a `BfColorScheme` and injects no service: the app binds its own state, normally `BfColorSchemeService.scheme`, with `[(value)]`. It works in both shells.
+
+## When to use
+
+Use `bf-theme-switch` on a settings page, or in a header row with room for three segments, so the choice stays visible. Use [bf-theme-menu-button](https://bitforge-ui.web.app/components/theme-menu-button) instead in a crowded top bar, where only one button fits. For a general view switch use [bf-segmented](https://bitforge-ui.web.app/components/segmented) itself.
+
+## Bind the colour scheme
+
+Bind `[(value)]` to `BfColorSchemeService.scheme` (from `@bitforgehq/ui`). On desktop, `provideBfColorScheme()` in the app's providers makes the service set the `dark` class on `<html>`, follow `prefers-color-scheme` under System and store the choice under `bf-theme`. In a Capacitor app `provideBfShell()` already does this, and `BfPlatformService.theme` (`@bitforgehq/ui/mobile`) is the same signal, so `[(value)]="platform.theme"` works too. `changed` emits the new choice after a user pick, never for a programmatic write.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { BfColorSchemeService, BfThemeSwitchComponent } from '@bitforgehq/ui';
+
+/**
+ * A theme switch bound to the app's colour scheme.
+ *
+ * `[(value)]` binds `BfColorSchemeService.scheme` itself: with `provideBfColorScheme()` in the
+ * app's providers (desktop) or `provideBfShell()` (Capacitor), a pick sets the `dark` class on
+ * `<html>` and is stored for the next visit.
+ *
+ * @preview none
+ */
+@Component({
+  selector: 'app-example-theme-switch-color-scheme',
+  imports: [BfThemeSwitchComponent],
+  template: `<bf-theme-switch [(value)]="colorScheme.scheme" />`,
+})
+export class ThemeSwitchColorSchemeExampleComponent {
+  // app.config.ts: providers: [provideBfColorScheme()]
+  protected readonly colorScheme = inject(BfColorSchemeService);
+}
+```
+
+## Full width
+
+`fullWidth` stretches the switch and shares the width between the segments, as on a phone settings screen. `size` sets the height step (`sm` 32, `md` 40, `lg` 48 px; unset follows `provideBfDefaults()`'s `controlSize`).
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfThemeSwitchComponent, type BfColorScheme } from '@bitforgehq/ui';
+
+/** A full-width theme switch under a visible caption, as on a phone settings screen. */
+@Component({
+  selector: 'app-example-theme-switch-full-width',
+  imports: [BfThemeSwitchComponent],
+  template: `
+    <div class="flex max-w-sm flex-col gap-2">
+      <!-- The group's own name repeats the caption, so the caption is hidden from readers. -->
+      <p aria-hidden="true" class="text-caption text-text-muted">Appearance</p>
+      <bf-theme-switch fullWidth label="Appearance" [(value)]="scheme" />
+    </div>
+  `,
+})
+export class ThemeSwitchFullWidthExampleComponent {
+  protected readonly scheme = signal<BfColorScheme>('light');
+}
+```
+
+## Labels
+
+The segments read `themeSystem`, `themeLight` and `themeDark`, and the group's accessible name is `label`, else `theme` ("Theme"); translate them with `provideBfLabels()`. The name is not shown: put a visible caption beside it when the page needs one.
+
+## Testing
+
+The switch renders a `bf-segmented`, so `BfSegmentedHarness` from `@bitforgehq/ui/testing` drives it: filter it by `label: 'Theme'`, pick with `select('Dark')` and read the choice with `getSelectedLabel()`.
+
+## Desktop
+
+The segments hover, press and show the focus ring like `bf-segmented`'s: a darker label on hover with the pointer cursor, the ring on keyboard focus only. Under a fine pointer each segment is its own hit area. In a dense header row set `size="sm"`, or `provideBfDefaults({ size: 'sm' })` in a component's `providers` ([density guide](https://bitforge-ui.web.app/density)). Add `provideBfColorScheme()` to the desktop app's providers; the Capacitor shell needs nothing more than `provideBfShell()`.
+
+## Theming
+
+The switch is a `bf-segmented` and consumes its tokens: track `surface-sunken`, active segment `surface` / `text` with `shadow-segment` and a 1.5 px inset `primary-strong` outline, inactive `text-muted`, focus `ring`, shape `rounded-control`.
+
+## Accessibility
+
+A `bf-segmented`: `role="radiogroup"` named by `label` (else the `theme` label), each choice a `<button role="radio">` with `aria-checked`, one tab stop on the selected segment. A visible caption next to it should repeat the name or carry `aria-hidden="true"`, so readers do not hear it twice. Under a coarse pointer each segment's hit area reaches 44 px.
+
+### Keyboard
+
+| Key                                              | Action                                                   |
+| ------------------------------------------------ | -------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Moves focus into and out of the switch (one tab stop)    |
+| <kbd>ArrowRight</kbd> / <kbd>ArrowDown</kbd>     | Selects and focuses the next choice, wrapping at the end |
+| <kbd>ArrowLeft</kbd> / <kbd>ArrowUp</kbd>        | Selects and focuses the previous choice, wrapping        |
+| <kbd>Home</kbd> / <kbd>End</kbd>                 | Selects System / Dark                                    |
+| <kbd>Space</kbd> / <kbd>Enter</kbd>              | Selects the focused choice                               |
+
+## Inputs
+
+| Name        | Type                                                        | Default     | Description                                                                                                                       |
+| ----------- | ----------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `label`     | `string`                                                    | `''`        | Accessible name of the switch (not shown); empty falls back to the `theme` label.                                                 |
+| `size`      | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined` | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`controlSize`, `md` by default).                        |
+| `fullWidth` | `boolean`                                                   | `false`     | Stretch the switch and share the width between the three segments.                                                                |
+| `value`     | `BfColorScheme` (`'system' \| 'light' \| 'dark'`)           | `'system'`  | The colour scheme choice; bind it two-way, usually to `BfColorSchemeService.scheme`, or with `[formField]`. Two-way: `[(value)]`. |
+
+## Outputs
+
+| Name      | Payload                                           | Description                                                             |
+| --------- | ------------------------------------------------- | ----------------------------------------------------------------------- |
+| `changed` | `BfColorScheme` (`'system' \| 'light' \| 'dark'`) | Emitted with the new choice right after the user picks another segment. |
+
+## Notes
+
+### Do
+
+- Bind `[(value)]` to `BfColorSchemeService.scheme` (or `BfPlatformService.theme` in the shell), so the switch and the page agree.
+- Keep System as an option: it follows the OS until the user decides.
+
+### Don't
+
+- Don't call `scheme.set()` from `(changed)` as well as binding `[(value)]`; the two-way binding already writes it.
+- Don't squeeze the switch into a crowded top bar; use `bf-theme-menu-button` there.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-theme-switch` in `@bitforgehq/ui`: System, Light and Dark as a three-option
+`bf-segmented`, holding a `BfColorScheme` in `value` (`[(value)]`, `changed`), with `label`,
+`size` and `fullWidth`. It injects no service; bind it to `BfColorSchemeService.scheme`
+(`BfPlatformService.theme` in the shell). New `BfLabels` keys `theme`, `themeSystem`, `themeLight`
+and `themeDark`.

package/ai/components/time-input.md

@@ -0,0 +1,240 @@
+# bf-time-input
+
+Typed time-of-day field with a popover list of times, valued as an ISO string
+
+`BfTimeInputComponent` from `@bitforgehq/ui/overlay` · Forms · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfTimeInputComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * The bf-time-input overview.
+ *
+ * Live demo of `bf-time-input`: a start time typed as hour and minute (24-hour in British
+ * English) or picked from the list of times every 30 minutes, which opens scrolled to the value.
+ * The value is an ISO time string; the status line shows it.
+ */
+@Component({
+  selector: 'app-example-time-input-overview',
+  imports: [BfTimeInputComponent],
+  template: `
+    <div class="flex max-w-xs flex-col gap-3">
+      <bf-time-input label="Start" locale="en-GB" [(value)]="start" />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class TimeInputOverviewExampleComponent {
+  /** The start time, 'HH:mm'; null while empty or incomplete. */
+  readonly start = signal<string | null>('09:30');
+
+  readonly status = computed(() => `Start: ${this.start() ?? 'none'}`);
+}
+```
+
+## Overview
+
+Time field typed part by part (hour, minute, optional seconds, AM/PM under a 12-hour clock)
+with a popover list of times, valued as an ISO time string.
+
+A time-of-day field typed part by part: the hour and the minute (and the seconds with `seconds`) in the locale's order and clock, with an AM/PM part under a 12-hour clock. A clock button opens a list of times every `step` minutes in a popover, scrolled to the value. The value is an ISO time string (`'14:30'`, `'14:30:05'` with seconds) on a 24-hour clock whatever the field shows, with no date and no time zone.
+
+Import `BfTimeInputComponent` from `@bitforgehq/ui/overlay` (it needs `@angular/cdk` for the popover). The parts work as in [bf-date-input](https://bitforge-ui.web.app/components/date-input); for a date and a time in one field use [bf-datetime-input](https://bitforge-ui.web.app/components/datetime-input).
+
+## When to use
+
+Use `bf-time-input` for a time of day in a form: a start time, an alarm, opening hours. Use [bf-select](https://bitforge-ui.web.app/components/select) or [bf-segmented](https://bitforge-ui.web.app/components/segmented) instead for a handful of fixed slots (morning, afternoon), and [bf-number-input](https://bitforge-ui.web.app/components/number-input) for a duration ("90 minutes"), which is not a time of day. It works in both shells; in a Capacitor app set `native`, so a phone shows its own time picker (see Native picker).
+
+## Typing a time
+
+Each part takes digits and moves on once it is complete ("7" in the hour of a 24-hour clock waits for a second digit, "3" moves on), and a part takes its value only then or when you leave it, so typing "30" minutes never passes through 03. <kbd>ArrowUp</kbd> and <kbd>ArrowDown</kbd> step a part and wrap (59 to 00), <kbd>Backspace</kbd> clears it, <kbd>ArrowLeft</kbd> and <kbd>ArrowRight</kbd> move between parts and <kbd>:</kbd> moves on. `value` is `null` while any part is empty, and `(changed)` emits the new value right after a user change.
+
+## 12-hour clock
+
+The clock follows the locale (`Intl.DateTimeFormat`'s `hourCycle`): American English counts 1 to 12 with an AM/PM part, British English and German count 0 to 23. `hourCycle` forces `h12` or `h23`. The AM/PM part takes the first letter of the locale's AM or PM name, or the arrows; the names come from `Intl`, its spinbutton name from the `timeInputDayPeriod` label. The value stays a 24-hour time: 2:30 PM is `'14:30'`, 12:05 AM is `'00:05'`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTimeInputComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * A 12-hour clock.
+ *
+ * American English counts hours 1 to 12 with an AM/PM part (type A or P, or press the arrows);
+ * `hourCycle="h12"` forces it in any locale. The value stays a 24-hour ISO time: 2:30 PM is
+ * '14:30'.
+ */
+@Component({
+  selector: 'app-example-time-input-twelve-hour',
+  imports: [BfTimeInputComponent],
+  template: `<bf-time-input class="max-w-xs" label="Alarm" locale="en-US" [(value)]="alarm" />`,
+})
+export class TimeInputTwelveHourExampleComponent {
+  readonly alarm = signal<string | null>('14:30');
+}
+```
+
+## List of times
+
+The clock button opens a list of times every `step` minutes from midnight (30 by default, any number from 1 to 720), written in the locale's clock. It opens scrolled to the value (else to the next time from now) with keyboard focus on it; <kbd>ArrowUp</kbd> and <kbd>ArrowDown</kbd> move, <kbd>Enter</kbd> or a click picks a time, closes the list and returns focus to the button. `min` and `max` disable the times outside them, and a typed time outside them shows `timeInputMin` / `timeInputMax` once focus leaves the field; an incomplete time shows `timeInputInvalid`. `picker="none"` leaves the field typed only.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfTimeInputComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * Step, min and max.
+ *
+ * `step="15"` lists a time every 15 minutes, and `min` and `max` disable the times outside
+ * opening hours; a typed time outside them shows an error once focus leaves the field.
+ */
+@Component({
+  selector: 'app-example-time-input-step',
+  imports: [BfTimeInputComponent],
+  template: `
+    <bf-time-input
+      class="max-w-xs"
+      label="Pickup"
+      locale="en-GB"
+      helpText="Between 08:00 and 18:00."
+      step="15"
+      min="08:00"
+      max="18:00"
+      [(value)]="pickup"
+    />
+  `,
+})
+export class TimeInputStepExampleComponent {
+  readonly pickup = signal<string | null>(null);
+}
+```
+
+## Seconds
+
+`seconds` adds a seconds part, and the value becomes `'HH:mm:ss'`; the list's times then end in `:00`. Leave it off unless the seconds matter (a log filter, a timer).
+
+## Native picker
+
+`native` renders an `input type="time"` with the same label, help and error text when the primary pointer is coarse (`matchMedia('(pointer: coarse)')`), and the segmented field under a mouse. `min`, `max` and `seconds` go to the native input. Recommended in the Capacitor shell: phones show their own time wheel, and typing into the parts needs a hardware keyboard.
+
+## With Signal Forms
+
+Bind the field with `[formField]`: required, touched, errors, disabled and readonly flow in, the first error shows once focus has left the field, and `focus()` focuses the first empty part. The [bf-date-input](https://bitforge-ui.web.app/components/date-input) page shows a booking form with both fields. Under `[formField]` the form owns `min` and `max`: give them through the schema with a metadata key (`metadata(path.time, OPENS, () => '09:00')` and `metadata(path.time, MIN, () => OPENS)`, with `OPENS = createMetadataKey<string | undefined>()`). In specs, `BfTimeInputHarness` from `@bitforgehq/ui/testing` types a time (`setValue('2:30 PM')`) or picks one from the list (`pickTime('14:30')`).
+
+## Desktop
+
+The field shows the `primary` border and focus ring while any part has focus, the focused part tinted `primary-soft`. The list's times tint `surface-muted` on hover; the keyboard's active time carries the focus ring while the list has keyboard focus. Fields default to `md` (40 px); `size` and `provideBfDefaults({ fieldSize })` set the step as on `bf-input` ([density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+- Field, parts and button: as `bf-date-input` (`surface`, `border-strong`, `primary` focus, `primary-soft` focused part, `text-muted` placeholders).
+- List: times `text` with `rounded-control` pills, hover `surface-muted`; the selected time `primary` with `on-primary`, bold; disabled times `text-disabled`; the active time `ring`.
+- Popover: `surface`, `border`, `rounded-card`, `shadow-floating`.
+
+## Accessibility
+
+The parts are a `role="group"` named by `label` (else `ariaLabel` or `ariaLabelledby`); each part is a `role="spinbutton"` named from the `timeInputHour`, `timeInputMinute`, `timeInputSecond` and `timeInputDayPeriod` labels, with `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and `aria-valuetext` (the AM or PM name), and the field's `aria-invalid`, `aria-errormessage`, `aria-required`, `aria-readonly` and `aria-disabled`. The clock button is named by `timeInputOpenList`, with `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`. The list is a `role="listbox"` named by the same label, its times `role="option"` with `aria-selected` and `aria-disabled`; focus stays on the list and `aria-activedescendant` names the active time.
+
+### Keyboard
+
+| Key                                              | Where | Action                                                   |
+| ------------------------------------------------ | ----- | -------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Field | Moves through the parts, then to the clock button        |
+| <kbd>0</kbd>–<kbd>9</kbd>                        | Part  | Types into the part; moves on once no further digit fits |
+| <kbd>A</kbd> / <kbd>P</kbd>                      | AM/PM | Sets the day period (the first letter of its name)       |
+| <kbd>ArrowUp</kbd> / <kbd>ArrowDown</kbd>        | Part  | Next / previous value, wrapping                          |
+| <kbd>ArrowRight</kbd> / <kbd>ArrowLeft</kbd>     | Part  | Next / previous part (swapped under `dir="rtl"`)         |
+| <kbd>Backspace</kbd> / <kbd>Delete</kbd>         | Part  | Clears the part                                          |
+| <kbd>:</kbd>                                     | Part  | Moves on to the next part                                |
+| <kbd>Alt</kbd>+<kbd>ArrowDown</kbd>              | Part  | Opens the list                                           |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>        | List  | Next / previous time (skipping disabled ones)            |
+| <kbd>Home</kbd> / <kbd>End</kbd>                 | List  | First / last time                                        |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | List  | Picks the active time and closes the list                |
+| <kbd>Escape</kbd>                                | List  | Closes the list, focus back on the button                |
+| <kbd>Tab</kbd>                                   | List  | Closes the list and moves on                             |
+
+## Inputs
+
+| Name             | Type                                                                | Default     | Description                                                                                                                                                          |
+| ---------------- | ------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `min`            | `string \| undefined`                                               | `undefined` | The earliest valid time ('HH:mm'): earlier times show an error and are disabled in the list. Set by `[formField]`; do not bind it yourself.                          |
+| `max`            | `string \| undefined`                                               | `undefined` | The latest valid time ('HH:mm'): later times show an error and are disabled in the list. Set by `[formField]`; do not bind it yourself.                              |
+| `step`           | `number`                                                            | `30`        | Minutes between the times of the list, from midnight (1–720).                                                                                                        |
+| `seconds`        | `boolean`                                                           | `false`     | Adds a seconds part; the value becomes 'HH:mm:ss'.                                                                                                                   |
+| `hourCycle`      | `BfTimeInputHourCycle \| undefined` (`'h12' \| 'h23' \| undefined`) | `undefined` | Forces a 12-hour (`h12`, with AM/PM) or 24-hour (`h23`) clock; unset follows the locale.                                                                             |
+| `picker`         | `BfTimeInputPicker` (`'list' \| 'none'`)                            | `'list'`    | `list` adds the button that opens the list of times; `none` keeps the field typed only.                                                                              |
+| `native`         | `boolean`                                                           | `false`     | Renders the platform's time picker (`input type="time"`) under a coarse pointer (touch).                                                                             |
+| `locale`         | `string`                                                            | `''`        | BCP 47 locale of the part order, the separators, the clock and the AM/PM names; empty follows the document's `lang`, else English.                                   |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`)         | `undefined` | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`fieldSize`, `md` by default).                                                             |
+| `label`          | `string`                                                            | `''`        | Visible label above the field.                                                                                                                                       |
+| `ariaLabel`      | `string`                                                            | `''`        | Accessible name when no visible label is rendered. Ignored when `label` is set.                                                                                      |
+| `ariaLabelledby` | `string`                                                            | `''`        | Id(s) of the element(s) that name the field when no visible label is rendered. Ignored when `label` is set.                                                          |
+| `helpText`       | `string`                                                            | `''`        | Helper text under the field.                                                                                                                                         |
+| `errorMessage`   | `string`                                                            | `''`        | Explicit error text; takes precedence over the field's own errors and Signal Forms errors.                                                                           |
+| `disabled`       | `boolean`                                                           | `false`     | Disables the field and its list button. Set by `[formField]`; do not bind it yourself.                                                                               |
+| `readonly`       | `boolean`                                                           | `false`     | Shows the time but blocks changes; the parts stay focusable and expose `aria-readonly`. Set by `[formField]`; do not bind it yourself.                               |
+| `required`       | `boolean`                                                           | `false`     | Marks the field required. Set by `[formField]`; do not bind it yourself.                                                                                             |
+| `invalid`        | `boolean`                                                           | `false`     | Field validity from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                     |
+| `touched`        | `boolean`                                                           | `false`     | Whether the user has left the field. Set by `[formField]`; do not bind it yourself.                                                                                  |
+| `errors`         | `readonly ValidationError.WithOptionalFieldTree[]`                  | `[]`        | Validation errors from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                  |
+| `name`           | `string`                                                            | `''`        | Native name attribute of the platform input (`native` under a coarse pointer). Set by `[formField]`; do not bind it yourself.                                        |
+| `id`             | `string`                                                            | `generated` | Field id; generated when not set.                                                                                                                                    |
+| `value`          | `string \| null`                                                    | `null`      | The time as an ISO string ('HH:mm', 'HH:mm:ss' with `seconds`), `null` while empty or incomplete; two-way bindable and bound by `[formField]`. Two-way: `[(value)]`. |
+
+## Outputs
+
+| Name      | Payload          | Description                                                                                                                               |
+| --------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| `changed` | `string \| null` | Emitted with the new time right after a user change: `null` once it is cleared or incomplete.                                             |
+| `touch`   | `void`           | Emitted when focus leaves the field (not into its list), so Signal Forms marks it touched. Set by `[formField]`; do not bind it yourself. |
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the first empty part (else the first part); Signal Forms calls it from
+`focusBoundControl()`.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+### `openPicker(): void`
+
+Opens the list of times; does nothing without a picker, or while disabled or read-only.
+
+### `closePicker(): void`
+
+Closes the list of times, focus back on its button; does nothing while it is closed.
+
+## Notes
+
+### Do
+
+- Give the field a `label`.
+- Store the value as the ISO time it is, and combine it with a date only where you know the time zone.
+- Pick a `step` that matches the slots you accept (15 for appointments).
+
+### Don't
+
+- Don't use it for a duration; a time input is a time of day.
+- Don't add `seconds` for times people pick by the quarter hour.
+- Don't format the value yourself for display in the field; it follows the locale's clock.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-time-input` in `@bitforgehq/ui/overlay`: a time-of-day field typed as hour and minute
+(and second with `seconds`), with an AM/PM part under a 12-hour clock. The clock follows the
+locale; `hourCycle` (`BfTimeInputHourCycle`: `'h12'` or `'h23'`) forces one. The value is an ISO
+time on a 24-hour clock (`'HH:mm'`, `'HH:mm:ss'` with seconds). `picker` (`BfTimeInputPicker`:
+`'list'`, the default, or `'none'`) adds a button that opens a listbox of times every `step`
+minutes (30 by default), scrolled to the value; `min` and `max` disable the times outside them
+and show an error for a typed one. `native` renders `input type="time"` under a coarse pointer.
+New label keys `timeInputHour`, `timeInputMinute`, `timeInputSecond`, `timeInputDayPeriod`,
+`timeInputOpenList`, `timeInputInvalid`, `timeInputMin` and `timeInputMax`, and a
+`BfTimeInputHarness` in `@bitforgehq/ui/testing` (`setValue(text)`, `pickTime(time)`).