@bitforgehq/ui 0.3.0 → 0.3.1

package/ai/components/date-input.md

@@ -0,0 +1,396 @@
+# bf-date-input
+
+Typed date field with a calendar popover, valued as an ISO date string
+
+`BfDateInputComponent` from `@bitforgehq/ui/overlay` · Forms · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfDateInputComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * The bf-date-input overview.
+ *
+ * Live demo of `bf-date-input`: a due date typed part by part (day, month and year in the
+ * British order, each moving on by itself) or picked in the calendar popover. The value is a
+ * plain ISO date string; the status line shows it.
+ */
+@Component({
+  selector: 'app-example-date-input-overview',
+  imports: [BfDateInputComponent],
+  template: `
+    <div class="flex max-w-xs flex-col gap-3">
+      <bf-date-input
+        label="Due date"
+        locale="en-GB"
+        helpText="Type it, or pick it in the calendar."
+        [(value)]="due"
+      />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class DateInputOverviewExampleComponent {
+  /** The due date, 'YYYY-MM-DD'; null while empty or incomplete. */
+  readonly due = signal<string | null>('2026-10-14');
+
+  readonly status = computed(() => `Due: ${this.due() ?? 'none'}`);
+}
+```
+
+## Overview
+
+Date field typed part by part (day, month and year in the locale's order) with a calendar
+popover, valued as an ISO date string and bound like any other field.
+
+A date field typed part by part: the day, the month and the year sit in the order the locale writes them (14/10/2026 in British English, 10/14/2026 in American English, 14.10.2026 in German), each a spinbutton that takes digits and moves on by itself. A calendar button opens a `bf-calendar` in a popover anchored to the field. The value is a plain ISO date string (`'2026-10-14'`), never a `Date`, so no time zone can shift the day, and the field binds to Signal Forms like `bf-input`.
+
+Import `BfDateInputComponent` from `@bitforgehq/ui/overlay` (it needs `@angular/cdk` for the popover). For a time of day use [bf-time-input](https://bitforge-ui.web.app/components/time-input), for both in one field [bf-datetime-input](https://bitforge-ui.web.app/components/datetime-input).
+
+## When to use
+
+Use `bf-date-input` for a date in a form: a due date, a delivery day, a date of birth. Use [bf-calendar](https://bitforge-ui.web.app/components/calendar) instead when the month should stay in view on the page (a booking page, a dashboard filter), and [bf-select](https://bitforge-ui.web.app/components/select) or [bf-segmented](https://bitforge-ui.web.app/components/segmented) when the choice is a few fixed dates (today, tomorrow, next week). It works in both shells; in a Capacitor app set `native`, so a phone shows its own date picker (see Choosing a picker).
+
+## Choosing a picker
+
+| Style                    | How                                                                        | Best for                                                                                     |
+| ------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| Inline calendar          | [bf-calendar](https://bitforge-ui.web.app/components/calendar) on the page | A date the page is about, with the month always in view                                      |
+| Field + calendar popover | `bf-date-input` (the default)                                              | A date in a form: type it when you know it, browse the month when you do not                 |
+| Typed only               | `picker="none"`                                                            | Dates people know by heart (a date of birth) or far from today, where a calendar is a detour |
+| Native on touch          | `native`                                                                   | Capacitor apps and phone browsers: the platform's date wheel or sheet under a coarse pointer |
+
+`native` renders an `input type="date"` with the same label, help and error text when the primary pointer is coarse (`matchMedia('(pointer: coarse)')`), and the segmented field under a mouse. Its `min` and `max` go to the native input, `disabledDate` and the calendar do not (the platform picker has no such rule; the error still shows). Recommended in the Capacitor shell, where typing into the parts needs a hardware keyboard.
+
+## Typing a date
+
+Each part takes digits and moves on once it has all of them or no further digit could fit: "4" in the month moves on at once, "1" waits for a possible "0" to "2". A separator key (`/`, `.`, `-`, a space) moves on early. A year of one or two digits becomes one of the 2000s when you leave it ("26" is 2026). <kbd>ArrowUp</kbd> and <kbd>ArrowDown</kbd> step a part and wrap around (an empty year starts at this year), <kbd>Backspace</kbd> clears it (and on an empty part moves back), <kbd>ArrowLeft</kbd> and <kbd>ArrowRight</kbd> move between the parts. An empty part shows a muted placeholder: the first letter of its name once per digit (dd/mm/yyyy), so translating the part names translates the placeholder.
+
+`value` is `null` while the date is empty or incomplete, and `(changed)` emits the new value (also `null` when a part is cleared) right after a user change, never for a value you set. A part takes its value once it is complete or when you leave it, so typing "14" never passes through the 1st.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfDateInputComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * Typed only.
+ *
+ * `picker="none"` drops the calendar button: a date of birth is quicker to type than to find
+ * decades back in a calendar.
+ */
+@Component({
+  selector: 'app-example-date-input-typed-only',
+  imports: [BfDateInputComponent],
+  template: `
+    <bf-date-input
+      class="max-w-xs"
+      label="Date of birth"
+      locale="en-GB"
+      picker="none"
+      max="2026-10-28"
+      [(value)]="birthday"
+    />
+  `,
+})
+export class DateInputTypedOnlyExampleComponent {
+  readonly birthday = signal<string | null>(null);
+}
+```
+
+## Calendar popover
+
+The calendar button (a CSS mark, no icon import) opens a `bf-calendar` in a popover below the field, flipping above it when there is no room; focus moves to the selected day (else today). Picking a day writes the date, closes the popover and returns focus to the button. <kbd>Escape</kbd>, a click outside, <kbd>Tab</kbd> past the calendar or a navigation close it; <kbd>Alt</kbd>+<kbd>ArrowDown</kbd> on a part opens it from the keyboard. `openPicker()` and `closePicker()` do the same from code.
+
+## Min, max and disabled dates
+
+`min` and `max` (ISO dates) bound the calendar, and a typed date outside them shows an error (`validation.minDate` / `maxDate` of the labels) once focus leaves the field. `disabledDate` rules out more dates: they show disabled in the calendar, and a typed one shows `dateInputUnavailable`. An incomplete or impossible date (31/02) shows `dateInputInvalid`. These errors are the field's own; add the same rule to your Signal Forms schema when the form must not submit with them.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { type BfCalendarDisabledDate } from '@bitforgehq/ui';
+import { BfDateInputComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * Min, max and disabled dates.
+ *
+ * A delivery date in November 2026 on working days: `min` and `max` bound the calendar and show
+ * an error for a typed date outside them, and `disabledDate` rules out weekends in the calendar
+ * and for typed dates.
+ */
+@Component({
+  selector: 'app-example-date-input-min-max',
+  imports: [BfDateInputComponent],
+  template: `
+    <bf-date-input
+      class="max-w-xs"
+      label="Delivery"
+      locale="en-GB"
+      helpText="A working day in November 2026."
+      min="2026-11-02"
+      max="2026-11-30"
+      [disabledDate]="weekends"
+      [(value)]="delivery"
+    />
+  `,
+})
+export class DateInputMinMaxExampleComponent {
+  readonly delivery = signal<string | null>('2026-11-16');
+
+  /** Saturdays and Sundays; an ISO date parses as UTC midnight, so getUTCDay is its weekday. */
+  readonly weekends: BfCalendarDisabledDate = (iso) => [0, 6].includes(new Date(iso).getUTCDay());
+}
+```
+
+## Locale
+
+`locale` (a BCP 47 tag) sets the order of the parts and their separators (from `Intl.DateTimeFormat`'s `formatToParts`) and the calendar's names and week. Empty, it follows the document's `lang`, else English. The part names, the button's name and the error texts are labels: translate them with `provideBfLabels()`, and put a `lang` around the field so a screen reader reads them in that language.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { provideBfLabels } from '@bitforgehq/ui';
+import { BfDateInputComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * A German date input.
+ *
+ * `locale="de"` puts the day first with dots between the parts and gives the calendar German
+ * names; the part names come from `provideBfLabels()`, and their first letters make the
+ * placeholder (tt.mm.jjjj).
+ */
+@Component({
+  selector: 'app-example-date-input-locale',
+  imports: [BfDateInputComponent],
+  providers: [
+    provideBfLabels({
+      dateInputDay: 'Tag',
+      dateInputMonth: 'Monat',
+      dateInputYear: 'Jahr',
+      dateInputOpenCalendar: 'Datum wählen',
+      dateInputInvalid: 'Gib ein gültiges Datum ein',
+      calendarPreviousMonth: 'Vorheriger Monat',
+      calendarNextMonth: 'Nächster Monat',
+      calendarChooseMonth: 'Monat wählen',
+      calendarChooseYear: 'Jahr wählen',
+    }),
+  ],
+  template: `
+    <div lang="de" class="max-w-xs">
+      <bf-date-input label="Liefertermin" locale="de" [(value)]="delivery" />
+    </div>
+  `,
+})
+export class DateInputLocaleExampleComponent {
+  readonly delivery = signal<string | null>(null);
+}
+```
+
+## With Signal Forms
+
+Bind the field with `[formField]`. Required, touched, errors, disabled and readonly flow in; the first error shows under the field once focus has left it, and `errorMessage` shows at once. The field's own errors (incomplete, outside `min`/`max`, a disabled date) come before the form's; they do not block a submit, so put a rule the form must enforce in its schema too (here a `validate()` rule for Sundays). `focus()` focuses the first empty part, so `focusBoundControl()` lands where the user has to type.
+
+Under `[formField]` the form owns `min` and `max`, as it owns `disabled` and `required`: Angular refuses a `min` attribute beside `[formField]`. Signal Forms' `minDate()` works on `Date` fields, so give an ISO string field its limit through a metadata key of your own: `const FIRST_DAY = createMetadataKey<string | undefined>()`, then `metadata(path.day, FIRST_DAY, () => '2026-11-02')` and `metadata(path.day, MIN, () => FIRST_DAY)` in the schema (`MAX` alike). The form then binds it to the field's `min`. Here a booking form, next to a `bf-time-input` limited to opening hours the same way. In specs, `BfDateInputHarness` from `@bitforgehq/ui/testing` types a date (`setValue('14/10/2026')`) or picks one in the calendar (`pickDate('2026-11-03')`).
+
+```ts
+import { Component, signal } from '@angular/core';
+import {
+  FormField,
+  FormRoot,
+  MAX,
+  MIN,
+  createMetadataKey,
+  form,
+  metadata,
+  required,
+  validate,
+} from '@angular/forms/signals';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfDateInputComponent, BfTimeInputComponent } from '@bitforgehq/ui/overlay';
+
+interface Visit {
+  day: string | null;
+  time: string | null;
+}
+
+/* Limits for ISO string fields: the form binds them to the field's `min` and `max`. */
+const FIRST_DAY = createMetadataKey<string | undefined>();
+const OPENS = createMetadataKey<string | undefined>();
+const CLOSES = createMetadataKey<string | undefined>();
+
+/**
+ * A booking form with Signal Forms.
+ *
+ * The day and the time are required, the day may not be a Sunday (a `validate()` rule with its
+ * own message), and the limits come from the schema: under `[formField]` the form binds `min` and
+ * `max`, here through `metadata()` keys of its own. Book shows the errors of an empty form.
+ */
+@Component({
+  selector: 'app-example-date-input-signal-forms',
+  imports: [FormField, FormRoot, BfButtonComponent, BfDateInputComponent, BfTimeInputComponent],
+  template: `
+    <form [formRoot]="visit" class="flex max-w-xs flex-col items-start gap-3">
+      <bf-date-input label="Day" locale="en-GB" class="self-stretch" [formField]="visit.day" />
+      <bf-time-input label="Time" locale="en-GB" class="self-stretch" [formField]="visit.time" />
+      <bf-button type="submit">Book</bf-button>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ booked() }}</p>
+    </form>
+  `,
+})
+export class DateInputSignalFormsExampleComponent {
+  private readonly model = signal<Visit>({ day: null, time: null });
+  protected readonly booked = signal('Nothing booked yet.');
+  protected readonly visit = form(
+    this.model,
+    (path) => {
+      required(path.day);
+      required(path.time);
+      metadata(path.day, FIRST_DAY, () => '2026-11-02');
+      metadata(path.day, MIN, () => FIRST_DAY);
+      metadata(path.time, OPENS, () => '09:00');
+      metadata(path.time, MIN, () => OPENS);
+      metadata(path.time, CLOSES, () => '17:00');
+      metadata(path.time, MAX, () => CLOSES);
+      validate(path.day, ({ value }) => {
+        const day = value();
+        // An ISO date parses as UTC midnight, so getUTCDay is its weekday.
+        return day && new Date(day).getUTCDay() === 0
+          ? { kind: 'sunday', message: 'We are closed on Sundays' }
+          : undefined;
+      });
+    },
+    {
+      submission: {
+        action: () => {
+          const { day, time } = this.model();
+          this.booked.set(`Booked ${day ?? ''} at ${time ?? ''}.`);
+          return Promise.resolve(undefined);
+        },
+      },
+    },
+  );
+}
+```
+
+## Sizes and states
+
+`size` sets the field height like `bf-input`: `sm` 32 px, `md` 40 px (default), `lg` 48 px; unset it follows `provideBfDefaults()`'s `fieldSize`. The calendar button sits 3 px inside the border at every step and grows to a 44 px hit area under a coarse pointer. `disabled` greys the field and takes it out of the tab order; `readonly` shows the date, keeps the parts focusable and disables the calendar button.
+
+## Desktop
+
+The field box shows the `primary` border and focus ring while any part has focus; the focused part is tinted `primary-soft`. Hovering the box darkens its border, hovering the calendar button tints it `surface-muted`. A click on the label or the box focuses the first empty part. Under a fine pointer each part is at least 24 × 24 px. Desktop density is `md`; `provideBfDefaults({ fieldSize: 'sm' })` gives 32 px fields for a filter bar ([density guide](https://bitforge-ui.web.app/density)).
+
+## Theming
+
+- Field: `surface`, a 1 px `border-strong` border (hover `text-muted`, focus `primary` with the `ring` focus ring), `rounded-field`; disabled `surface-muted` with `surface-sunken` and `text-disabled`; read-only `surface-muted`; error `danger-border`.
+- Parts: `text`, placeholders and separators `text-muted`; the focused part `primary-soft` with `primary-text`, `rounded-checkbox`.
+- Calendar button: `text-muted`, hover `surface-muted` with `text`, pressed `surface-pressed`, `rounded-control`.
+- Popover: `surface`, `border`, `rounded-card`, `shadow-floating`; the calendar inside uses its own tokens.
+
+## Accessibility
+
+The parts are a `role="group"` named by `label` (else `ariaLabel` or `ariaLabelledby`) and described by the help and error text. Each part is a `role="spinbutton"` named from the `dateInputDay`, `dateInputMonth` and `dateInputYear` labels, with `aria-valuemin`, `aria-valuemax`, `aria-valuenow` (absent while empty) and `aria-valuetext` (the month's name); `aria-invalid`, `aria-errormessage`, `aria-required`, `aria-readonly` and `aria-disabled` reflect the field. The separators are `aria-hidden`. The calendar button is named by `dateInputOpenCalendar` and carries `aria-haspopup="dialog"`, `aria-expanded` and, while open, `aria-controls`; the popover is a non-modal `dialog` named by the button, holding a `bf-calendar` with its own grid semantics. Focus moves into the calendar on open and back to the button on a pick or <kbd>Escape</kbd>. In native mode the platform input carries the label, `aria-invalid` and `aria-describedby`.
+
+### Keyboard
+
+| Key                                              | Where    | Action                                                            |
+| ------------------------------------------------ | -------- | ----------------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Field    | Moves through the parts, then to the calendar button              |
+| <kbd>0</kbd>–<kbd>9</kbd>                        | Part     | Types into the part; moves on once no further digit fits          |
+| <kbd>ArrowUp</kbd> / <kbd>ArrowDown</kbd>        | Part     | Next / previous value, wrapping (an empty year starts at today)   |
+| <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>Backspace</kbd> on an empty part moves back |
+| <kbd>/</kbd>, <kbd>.</kbd>, <kbd>-</kbd>         | Part     | Moves on to the next part                                         |
+| <kbd>Alt</kbd>+<kbd>ArrowDown</kbd>              | Part     | Opens the calendar                                                |
+| <kbd>Enter</kbd> / <kbd>Space</kbd>              | Button   | Opens the calendar (closes it when open)                          |
+| <kbd>Escape</kbd>                                | Calendar | Closes the popover, focus back on the button                      |
+| <kbd>Tab</kbd>                                   | Calendar | Past the last control closes the popover and moves on             |
+
+The calendar's own keys (arrows, Page Up/Down, Home, End, Enter) work as on [bf-calendar](https://bitforge-ui.web.app/components/calendar).
+
+## Inputs
+
+| Name             | Type                                                        | Default      | Description                                                                                                                                    |
+| ---------------- | ----------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| `min`            | `string \| undefined`                                       | `undefined`  | The earliest valid date (ISO): earlier dates show an error, and the calendar stops there. Set by `[formField]`; do not bind it yourself.       |
+| `max`            | `string \| undefined`                                       | `undefined`  | The latest valid date (ISO): later dates show an error, and the calendar stops there. Set by `[formField]`; do not bind it yourself.           |
+| `disabledDate`   | `BfCalendarDisabledDate \| null`                            | `null`       | Rules out more dates (weekends, booked days): disabled in the calendar, an error when typed.                                                   |
+| `picker`         | `BfDateInputPicker` (`'calendar' \| 'none'`)                | `'calendar'` | `calendar` adds the button that opens a calendar popover; `none` keeps the field typed only.                                                   |
+| `native`         | `boolean`                                                   | `false`      | Renders the platform's date picker (`input type="date"`) under a coarse pointer (touch).                                                       |
+| `locale`         | `string`                                                    | `''`         | BCP 47 locale of the part order, the separators and the calendar; 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 calendar button. Set by `[formField]`; do not bind it yourself.                                                     |
+| `readonly`       | `boolean`                                                   | `false`      | Shows the date 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 date as an ISO string ('YYYY-MM-DD'), `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 date right after a user change: `null` once it is cleared or incomplete.                                                 |
+| `touch`   | `void`           | Emitted when focus leaves the field (not into its calendar), 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 calendar popover; does nothing without a picker, or while disabled or read-only.
+
+### `closePicker(): void`
+
+Closes the calendar popover, focus back on its button; does nothing while it is closed.
+
+## Notes
+
+### Do
+
+- Give the field a `label`; it names the group and the popover's calendar.
+- Store and send the value as the ISO string it is; turn it into a `Date` only to display or compute, at UTC midnight.
+- Set `native` in a Capacitor app, so phones get their own picker.
+- Add `min`, `max` and a `disabledDate` rule to your form schema too when the form must not submit an out-of-range date.
+
+### Don't
+
+- Don't parse what users type with `new Date()`; read the ISO value.
+- Don't use it for a range of two dates as one field; use two date inputs.
+- Don't drop the calendar for a date near today (an appointment); `picker="none"` suits dates people know by heart.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-date-input` in `@bitforgehq/ui/overlay`: a date field typed part by part, the day, month
+and year as spinbuttons in the locale's order and separators (`Intl.DateTimeFormat`
+`formatToParts`), with muted placeholders (dd/mm/yyyy). Digits type in and move on by themselves,
+Arrow Up/Down step with wrapping, Backspace clears, Arrow Left/Right move between the parts. The
+value is an ISO date string (`'YYYY-MM-DD'`), `null` while empty or incomplete, and `(changed)`
+emits each user change. `picker` (`BfDateInputPicker`: `'calendar'`, the default, or `'none'`)
+adds a button that opens a `bf-calendar` in an anchored popover; a pick closes it and returns
+focus. `min`, `max` and `disabledDate` bound the calendar and show the field's own error for a
+typed date outside them (as for an incomplete or impossible one). `native` renders
+`input type="date"` under a coarse pointer, for the Capacitor shell. `locale`, `size`
+(`fieldSize`), `openPicker()`, `closePicker()`, `focus()`, and the Signal Forms value contract
+like `bf-input`. New label keys `dateInputDay`, `dateInputMonth`, `dateInputYear`,
+`dateInputOpenCalendar`, `dateInputInvalid` and `dateInputUnavailable`, and a
+`BfDateInputHarness` in `@bitforgehq/ui/testing` (`getValue()`, `setValue(text)`, `clear()`,
+`openPicker()`, `pickDate(iso)`).

package/ai/components/datetime-input.md

@@ -0,0 +1,215 @@
+# bf-datetime-input
+
+Typed date and time field with a calendar and time list in one popover
+
+`BfDateTimeInputComponent` from `@bitforgehq/ui/overlay` · Forms · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfDateTimeInputComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * The bf-datetime-input overview.
+ *
+ * Live demo of `bf-datetime-input`: a meeting's date and time typed in one field, or picked in
+ * the popover, which holds the calendar and a list of times every 15 minutes side by side. The
+ * value is a local ISO date and time without a zone; the status line shows it.
+ */
+@Component({
+  selector: 'app-example-datetime-input-overview',
+  imports: [BfDateTimeInputComponent],
+  template: `
+    <div class="flex max-w-xs flex-col gap-3">
+      <bf-datetime-input label="Meeting" locale="en-GB" step="15" [(value)]="meeting" />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class DatetimeInputOverviewExampleComponent {
+  /** The meeting, 'YYYY-MM-DDTHH:mm'; null while empty or incomplete. */
+  readonly meeting = signal<string | null>('2026-10-14T09:30');
+
+  readonly status = computed(() => `Meeting: ${this.meeting() ?? 'none'}`);
+}
+```
+
+## Overview
+
+Date and time field typed part by part, with a popover holding a calendar and a list of
+times, valued as a local ISO date and time without a zone.
+
+A date and a time in one field: the date parts and the time parts in the locale's order ("14/10/2026, 09:30" in British English), typed like [bf-date-input](https://bitforge-ui.web.app/components/date-input) and [bf-time-input](https://bitforge-ui.web.app/components/time-input). Its button opens one popover holding the calendar and a list of times side by side. The value is a local ISO date and time without a zone (`'2026-10-14T09:30'`), the format of `input type="datetime-local"`.
+
+Import `BfDateTimeInputComponent` from `@bitforgehq/ui/overlay` (it needs `@angular/cdk` for the popover).
+
+## When to use
+
+Use `bf-datetime-input` for one moment a person picks as a date and a time: a meeting, a publish time, a reminder. Use [bf-date-input](https://bitforge-ui.web.app/components/date-input) and [bf-time-input](https://bitforge-ui.web.app/components/time-input) side by side instead when the two are edited apart (an all-day toggle, a time that may stay empty), and a [bf-calendar](https://bitforge-ui.web.app/components/calendar) on the page when the month should stay in view. It works in both shells; in a Capacitor app set `native`, so a phone shows its own picker.
+
+## Typing and picking
+
+The parts work as in the date and the time inputs: digits move on by themselves, the arrows step, <kbd>Backspace</kbd> clears, and the clock follows the locale (`hourCycle` forces `h12` or `h23`). `value` is `null` until every part is set, and `(changed)` emits the new value right after a user change.
+
+The button opens the popover with focus on the calendar's selected day. Picking a day writes the date and moves focus to the list of times beside it (every `step` minutes, 30 by default); picking a time writes it, closes the popover and returns focus to the button. <kbd>Escape</kbd>, a click outside or <kbd>Tab</kbd> past the list close it.
+
+## Min, max and disabled dates
+
+`min` and `max` are values like the field's (`'2026-10-14T09:00'`). Their dates bound the calendar; on the day of a limit the list disables the times past it. A typed value outside them shows an error once focus leaves the field: the date limit (`validation.minDate` / `maxDate`) when the day is out of range, the time limit (`timeInputMin` / `timeInputMax`) on the limit's own day. `disabledDate` rules out dates in the calendar and for typed dates (`dateInputUnavailable`). An incomplete date or time shows `dateInputInvalid` or `timeInputInvalid`.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfDateTimeInputComponent } from '@bitforgehq/ui/overlay';
+
+/**
+ * Min and max.
+ *
+ * A delivery slot from 14 October 2026, 09:00 to 30 October 2026, 17:00: the calendar stops at
+ * both days, and on 14 October the list disables the times before 09:00 (on 30 October those
+ * after 17:00). A typed value outside them shows the date or the time limit.
+ */
+@Component({
+  selector: 'app-example-datetime-input-min-max',
+  imports: [BfDateTimeInputComponent],
+  template: `
+    <bf-datetime-input
+      class="max-w-xs"
+      label="Delivery slot"
+      locale="en-GB"
+      step="60"
+      min="2026-10-14T09:00"
+      max="2026-10-30T17:00"
+      [(value)]="slot"
+    />
+  `,
+})
+export class DatetimeInputMinMaxExampleComponent {
+  readonly slot = signal<string | null>('2026-10-14T08:00');
+}
+```
+
+## Time zones
+
+The value has no zone: it is the wall-clock time the user picked, in no particular place. Keep it that way for local events (a shop's opening, a meeting in a known office), or turn it into an instant where you know the zone (the user's, or an event's), on the server or with `Intl`. Never parse what users type with `new Date()`; the field never does.
+
+## Native picker
+
+`native` renders an `input type="datetime-local"` 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` and `max` go to it. Recommended in the Capacitor shell.
+
+## With Signal Forms
+
+Bind the field with `[formField]`: required, touched, errors, disabled and readonly flow in, and `focus()` focuses the first empty part. Under `[formField]` the form owns `min` and `max`: give them through the schema with a metadata key and `metadata(path, MIN, () => KEY)`, as the [bf-date-input](https://bitforge-ui.web.app/components/date-input) page shows. In specs, `BfDateTimeInputHarness` from `@bitforgehq/ui/testing` types a value (`setValue('14/10/2026, 09:30')`) or picks it (`pickDate('2026-10-14')`, then `pickTime('09:30')`).
+
+## Desktop
+
+As the date and the time inputs: the focus ring on the field while a part has focus, a tinted focused part, hover tints on the button and the list's times. The popover is about 29 rem wide at `md`; on a narrow screen the list of times wraps below the calendar. Fields default to `md` (40 px); `size` and `provideBfDefaults({ fieldSize })` set the step ([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).
+- Popover: `surface`, `border`, `rounded-card`, `shadow-floating`.
+- Calendar and list: their own tokens, as on [bf-calendar](https://bitforge-ui.web.app/components/calendar) and `bf-time-input`.
+
+## Accessibility
+
+The parts are a `role="group"` named by `label` (else `ariaLabel` or `ariaLabelledby`), each a named `role="spinbutton"` with its range, value and value text, and the field's invalid, required, read-only and disabled state. The button is named by `dateInputOpenCalendar`, with `aria-haspopup="dialog"`, `aria-expanded` and `aria-controls`; the popover is a non-modal `dialog` named by the button, holding a `bf-calendar` grid and a `role="listbox"` of times named by `timeInputOpenList` (`aria-activedescendant`, `aria-selected`, `aria-disabled`). Focus moves into the calendar on open, to the list after a day is picked, and back to the button after a time is picked or on <kbd>Escape</kbd>.
+
+### Keyboard
+
+| Key                                              | Where   | Action                                                   |
+| ------------------------------------------------ | ------- | -------------------------------------------------------- |
+| <kbd>Tab</kbd> / <kbd>Shift</kbd>+<kbd>Tab</kbd> | Field   | Moves through the parts, then to the button              |
+| <kbd>0</kbd>–<kbd>9</kbd>                        | Part    | Types into the part; moves on once no further digit fits |
+| <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>Alt</kbd>+<kbd>ArrowDown</kbd>              | Part    | Opens the popover                                        |
+| <kbd>Tab</kbd>                                   | Popover | From the calendar to the list; past the list closes it   |
+| <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 popover             |
+| <kbd>Escape</kbd>                                | Popover | Closes the popover, focus back on the button             |
+
+The calendar's own keys work as on [bf-calendar](https://bitforge-ui.web.app/components/calendar).
+
+## Inputs
+
+| Name             | Type                                                                | Default     | Description                                                                                                                                                                        |
+| ---------------- | ------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `min`            | `string \| undefined`                                               | `undefined` | The earliest valid date and time ('YYYY-MM-DDTHH:mm'): earlier values show an error, and the calendar and the list stop there. Set by `[formField]`; do not bind it yourself.      |
+| `max`            | `string \| undefined`                                               | `undefined` | The latest valid date and time ('YYYY-MM-DDTHH:mm'): later values show an error, and the calendar and the list stop there. Set by `[formField]`; do not bind it yourself.          |
+| `disabledDate`   | `BfCalendarDisabledDate \| null`                                    | `null`      | Rules out more dates (weekends, booked days): disabled in the calendar, an error when typed.                                                                                       |
+| `step`           | `number`                                                            | `30`        | Minutes between the times of the list, from midnight (1–720).                                                                                                                      |
+| `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`         | `BfDateTimeInputPicker` (`'popover' \| 'none'`)                     | `'popover'` | `popover` adds the button that opens the calendar and the time list; `none` keeps the field typed only.                                                                            |
+| `native`         | `boolean`                                                           | `false`     | Renders the platform's picker (`input type="datetime-local"`) under a coarse pointer (touch).                                                                                      |
+| `locale`         | `string`                                                            | `''`        | BCP 47 locale of the part order, the separators, the clock and the calendar; 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 picker button. Set by `[formField]`; do not bind it yourself.                                                                                           |
+| `readonly`       | `boolean`                                                           | `false`     | Shows the value 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 local date and time as an ISO string without a zone ('YYYY-MM-DDTHH:mm'), `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 value right after a user change: `null` once it is cleared or incomplete.                                               |
+| `touch`   | `void`           | Emitted when focus leaves the field (not into its popover), 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 calendar and time popover; does nothing without a picker, or while disabled or
+read-only.
+
+### `closePicker(): void`
+
+Closes the popover, focus back on its button; does nothing while it is closed.
+
+## Notes
+
+### Do
+
+- Give the field a `label`.
+- Decide where the time zone comes from before you store the value as an instant.
+- Set `step` to the slots you accept.
+
+### Don't
+
+- Don't append a zone or a `Z` to the value as if it were UTC; it is a local wall-clock time.
+- Don't use it for an all-day event; use a date input.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-datetime-input` in `@bitforgehq/ui/overlay`: the date and the time parts in one field,
+valued as a local ISO date and time without a zone (`'YYYY-MM-DDTHH:mm'`). `picker`
+(`BfDateTimeInputPicker`: `'popover'`, the default, or `'none'`) opens one popover with the
+calendar and a list of times side by side: a day moves focus to the list, a time closes it.
+`min` and `max` bound the calendar and, on their own day, the list. `step`, `hourCycle`,
+`disabledDate`, `native` (`input type="datetime-local"`) and the field contract as on the date
+and time inputs. New `BfDateTimeInputHarness` in `@bitforgehq/ui/testing` (`pickDate(iso)`,
+`pickTime(time)`, `setValue(text)`).