forty-cdk 0.2.0 → 0.3.0

package/tabs/README.md

@@ -0,0 +1,130 @@
+# Tabs
+
+Headless implementation of the [WAI-ARIA Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) with selectable activation mode (automatic vs manual) and roving tabindex.
+
+## Pieces
+
+| Class            | Selector           | Role                                                                                          |
+| ---------------- | ------------------ | --------------------------------------------------------------------------------------------- |
+| `ForTabs`        | `[forTabs]`        | Root. Owns `value` (selected tab), activation mode, orientation. Provides the shared context. |
+| `ForTabsList`    | `[forTabsList]`    | `role="tablist"` container that wraps the tab buttons.                                        |
+| `ForTabsTrigger` | `[forTabsTrigger]` | One tab button. Apply on a `<button type="button">`.                                          |
+| `ForTabsContent` | `[forTabsContent]` | Panel revealed by the tab with the matching `value`.                                          |
+
+## Inputs / models
+
+### `ForTabs`
+
+| API              | Type                                | Description                                                                                                                                            |
+| ---------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `value`          | `model<string \| null>`             | Two-way bindable. The selected tab's value, or `null` when nothing is selected. `null` is the unset state — distinct from a tab whose `value` is `''`. |
+| `activationMode` | `input<'automatic' \| 'manual'>`    | Default `'automatic'` (selection follows arrow focus). Use `'manual'` when panel content is expensive — user must press Space / Enter.                 |
+| `orientation`    | `input<'horizontal' \| 'vertical'>` | Default `'horizontal'`. Drives keyboard navigation and `aria-orientation`.                                                                             |
+| `dir`            | `input<'ltr' \| 'rtl'>`             | Default `'ltr'`. Swaps ArrowLeft / ArrowRight.                                                                                                         |
+| `disabled`       | `input<boolean>`                    | When true, blocks all selection and keyboard nav.                                                                                                      |
+| `loop`           | `input<boolean>`                    | When true (default), arrow nav wraps around past the first / last enabled trigger. Set to `false` for a non-wrapping tablist.                          |
+
+### `ForTabsTrigger`
+
+| API        | Type                     | Description                                                           |
+| ---------- | ------------------------ | --------------------------------------------------------------------- |
+| `value`    | `input.required<string>` | The tab's identifier. Must match the `value` of its `ForTabsContent`. |
+| `disabled` | `input<boolean>`         | Disables this trigger; arrow nav skips it.                            |
+
+Reflects on its host: `id`, `aria-selected`, `aria-controls` (looked up from the matching content), `aria-disabled`, `tabindex`, `data-state="active" \| "inactive"`, `data-disabled`. A disabled trigger keeps `aria-disabled="true"` + `data-disabled=""` (no native `disabled`, per APG) — announced but non-activatable, with arrow nav skipping it.
+
+### `ForTabsContent`
+
+| API                  | Type                     | Description                                                                                                                                                                                                                   |
+| -------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `value`              | `input.required<string>` | Pairs the panel with the trigger of the same value.                                                                                                                                                                           |
+| `interactiveContent` | `input<boolean \| null>` | Overrides the automatic focusable-content detection that drives `tabindex`. Default `null` (auto-detect). `true` forces no tab stop (the panel always holds its own focusable content); `false` forces a tab stop regardless. |
+
+Reflects: `id`, `role="tabpanel"`, `aria-labelledby` (the matching trigger's id), `tabindex="0"` **only when the panel has no focusable descendants** (APG), `aria-hidden` (when inactive), `inert` (when inactive), `data-state="active" \| "inactive"`.
+
+The directive does **not** apply `[hidden]`. Two patterns work:
+
+- **Leave all panels mounted** (idiomatic) — preserves scroll/input state across activations. While inactive, the directive sets `aria-hidden="true"` and `inert` so each non-selected panel is out of the accessibility tree and focus order. Hide the inactive ones visually with CSS keyed on `[data-state="inactive"]` (e.g. `display: none`).
+- **Mount/unmount with `@if (active() === 'tab')`** — the panel is absent while inactive; useful for heavy panels or when you want `animate.enter` / `animate.leave`.
+
+## Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { ForTabs, ForTabsContent, ForTabsList, ForTabsTrigger } from 'forty-cdk/tabs';
+
+@Component({
+  selector: 'demo-settings',
+  imports: [ForTabs, ForTabsList, ForTabsTrigger, ForTabsContent],
+  template: `
+    <div forTabs [(value)]="active">
+      <div forTabsList aria-label="Settings sections">
+        <button type="button" forTabsTrigger class="tabs-trigger" value="profile">Profile</button>
+        <button type="button" forTabsTrigger class="tabs-trigger" value="security">Security</button>
+        <button type="button" forTabsTrigger class="tabs-trigger" value="billing">Billing</button>
+      </div>
+      <div forTabsContent class="tabs-content" value="profile">…profile…</div>
+      <div forTabsContent class="tabs-content" value="security">…security…</div>
+      <div forTabsContent class="tabs-content" value="billing">…billing…</div>
+    </div>
+  `,
+})
+export class DemoSettings {
+  readonly active = signal('profile');
+}
+```
+
+## Manual activation
+
+```html
+<div forTabs activationMode="manual" [(value)]="active">
+  <!-- Arrow keys move focus only. Space / Enter activates. -->
+</div>
+```
+
+## Styling
+
+forty-cdk ships no styles. Add your own class to each piece — the for\* selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../../../docs/styling.md)). Key your CSS off the reflected data-\* attributes below.
+
+### Data attributes
+
+| Piece              | Attribute          | Values                     |
+| ------------------ | ------------------ | -------------------------- |
+| `[forTabs]`        | `data-orientation` | `horizontal` \| `vertical` |
+| `[forTabs]`        | `data-disabled`    | present \| absent          |
+| `[forTabsList]`    | `data-orientation` | `horizontal` \| `vertical` |
+| `[forTabsTrigger]` | `data-state`       | `active` \| `inactive`     |
+| `[forTabsTrigger]` | `data-disabled`    | present \| absent          |
+| `[forTabsTrigger]` | `data-orientation` | `horizontal` \| `vertical` |
+| `[forTabsContent]` | `data-state`       | `active` \| `inactive`     |
+| `[forTabsContent]` | `data-orientation` | `horizontal` \| `vertical` |
+
+```css
+.tabs-trigger[data-state='active'] {
+  border-bottom: 2px solid currentColor;
+}
+
+.tabs-trigger[data-disabled] {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.tabs-content[data-state='inactive'] {
+  display: none;
+}
+```
+
+## Keyboard
+
+- **Tab** moves focus into / out of the tablist; lands on the user-focused trigger (or the selected one, if none focused yet).
+- **ArrowRight / ArrowLeft** in horizontal, **ArrowDown / ArrowUp** in vertical: move focus between triggers, wrap-around. RTL swaps Left/Right.
+- **Home / End** jump to first / last enabled trigger.
+- **Space / Enter** activate the focused trigger (no-op in automatic mode since arrow nav already activated it).
+- Disabled triggers are skipped.
+
+## Accessibility notes
+
+- **Label the tablist** via `aria-label` on `ForTabsList`, or `aria-labelledby` pointing to a heading.
+- **Choose `activationMode='automatic'`** when panels render quickly; `'manual'` when activation has noticeable cost (network, heavy computation).
+- **Panel `tabindex`** follows APG: a panel with **no** focusable descendants is itself a tab stop (`tabindex="0"`) so screen-reader users can focus and read it, while a panel that already contains focusable content (a form, links, buttons) is **not** a tab stop — the directive detects this automatically and reacts to subtree changes. Use `[interactiveContent]` to override the detection in either direction.
+- **`aria-controls` and `aria-labelledby`** are wired automatically when triggers and contents share the same `value`. `aria-controls` is emitted only on the selected trigger — mirroring the overlay triggers' open-only gating — so the reference never dangles at an unmounted panel under the `@if (selected())` mount pattern.

package/time-field/README.md

@@ -0,0 +1,157 @@
+# TimeField
+
+Headless, segmented, spin-editable **time-of-day** input — the time counterpart to [DateField](../date-field/README.md). There is **no single WAI-ARIA APG pattern** for a time field; it is a composition of [Spinbuttons](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/) inside a labelled `role="group"`. Each hour / minute / second / AM·PM part is an independent `role="spinbutton"` segment, so entry is unambiguous and locale-correct. Segment **order**, the separators between them, and whether an AM/PM segment is shown follow the runtime locale and the resolved hour cycle.
+
+`ForTimeField` implements `FormValueControl<D | null>` from `@angular/forms/signals`, so it auto-wires with `[formField]` and auto-associates inside a `[forField]` (label / description / error) with no extra markup. The value stays `null` until every visible segment is filled.
+
+## Date adapter — pick a time-capable one (required)
+
+All time math goes through the same pluggable `DateAdapter<D>` as `ForCalendar`, so the library hard-depends on **no** date library. The time field needs the adapter's optional time accessors, so provide a **time-capable** adapter:
+
+| Provider                                    | Date-time type `D`                             | Dependency                                                                                                |
+| ------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `provideInternationalizedDateTimeAdapter()` | `CalendarDateTime` (`@internationalized/date`) | **Recommended.** From `forty-cdk/internationalized-date`; needs `@internationalized/date` (optional peer) |
+| `provideNativeDateAdapter()`                | `Date`                                         | None (zero-dependency fallback)                                                                           |
+
+> The day-only `provideInternationalizedDateAdapter()` (`CalendarDate`) cannot carry a time — `ForTimeField` throws a descriptive error if it is the active adapter.
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideInternationalizedDateTimeAdapter } from 'forty-cdk/internationalized-date';
+
+bootstrapApplication(App, {
+  providers: [provideInternationalizedDateTimeAdapter()],
+});
+```
+
+When no value is bound yet, a composed value is anchored on the adapter's `today()` and carries the entered time. Bind an existing date-time as `value` to edit its time in place (the calendar day is preserved).
+
+## Pieces
+
+| Class                 | Selector                | Role                                                                                               |
+| --------------------- | ----------------------- | -------------------------------------------------------------------------------------------------- |
+| `ForTimeField`        | `[forTimeField]`        | Root (`role="group"`). Owns the entered parts, composes the value, and exposes `segments()`.       |
+| `ForTimeFieldSegment` | `[forTimeFieldSegment]` | One editable part (`role="spinbutton"`). Roving tab stop, ARIA value reflection, keyboard editing. |
+| `ForTimeFieldLiteral` | `[forTimeFieldLiteral]` | A decorative separator (`:`, a space). `aria-hidden`, out of the tab order.                        |
+
+## Inputs / models — `ForTimeField`
+
+| API           | Type                                              | Description                                                                                                                      |
+| ------------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `value`       | `model<D \| null>`                                | Two-way bindable entered time, or `null` while any visible segment is empty. The `FormValueControl` backing. Default `null`.     |
+| `minTime`     | `input<D \| null>`                                | Earliest time-of-day (inclusive). A composed value earlier in the day is clamped up. Named `minTime` — see note. Default `null`. |
+| `maxTime`     | `input<D \| null>`                                | Latest time-of-day (inclusive). A composed value later in the day is clamped down. Default `null`.                               |
+| `hourCycle`   | `input<12 \| 24 \| null>`                         | 12- or 24-hour cycle. Default `null` → derived from the locale. 12-hour adds the AM/PM segment.                                  |
+| `granularity` | `input<'hour' \| 'minute' \| 'second'>`           | Smallest editable unit. Default `'minute'`.                                                                                      |
+| `locale`      | `input<string \| null>`                           | BCP 47 locale driving segment order, separators, and AM/PM names. Default `null` → runtime locale.                               |
+| `placeholder` | `input<Partial<Record<TimeSegmentType, string>>>` | Per-segment placeholder while empty. Unspecified parts fall back to `hh` / `mm` / `ss` / `--`. Default `{}`.                     |
+| `ariaLabel`   | `input<string \| null>`                           | Accessible name for the group. Emits no `aria-label` while `null`. Default `null`.                                               |
+| `dir`         | `input<'ltr' \| 'rtl' \| null>`                   | Writing direction. Default `null` resolves the ambient direction; mirrors ArrowLeft / ArrowRight segment navigation.             |
+
+Plus the shared `FormUiControl` members from `@angular/forms/signals`: `disabled`, `readonly`, `required`, `invalid`, `name`, `errors`, `touched` (bound automatically by `[formField]`).
+
+> **Why `minTime` / `maxTime`, not `min` / `max`?** `FormUiControl.min` / `max` are reserved members typed `number | undefined` for numeric validators bound by `[formField]`. A date-time-typed `min` / `max` would break the `FormValueControl` contract, so the time bounds use distinct names. Only the time-of-day component of the bounds is considered.
+
+## Usage
+
+```ts
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { CalendarDateTime } from '@internationalized/date';
+import { ForTimeField, ForTimeFieldLiteral, ForTimeFieldSegment } from 'forty-cdk/time-field';
+
+@Component({
+  selector: 'app-appt-time',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [ForTimeField, ForTimeFieldSegment, ForTimeFieldLiteral],
+  template: `
+    <div forTimeField [(value)]="time" [ariaLabel]="'Appointment time'" #field="forTimeField">
+      @for (seg of field.segments(); track seg.id) {
+        @if (seg.isLiteral) {
+          <span forTimeFieldLiteral>{{ seg.text }}</span>
+        } @else {
+          <span forTimeFieldSegment class="time-field-segment" [segment]="seg.type!">{{
+            seg.text
+          }}</span>
+        }
+      }
+    </div>
+  `,
+})
+export class ApptTime {
+  readonly time = signal<CalendarDateTime | null>(null);
+}
+```
+
+The library is styleless: style the boolean `data-*` hooks on the segments yourself — `[data-highlighted]` (the focused/roving segment), `[data-placeholder]` (empty), `[data-disabled]`, `[data-readonly]` — and `[data-empty]` / `[data-disabled]` / `[data-readonly]` on the root group.
+
+## Keyboard (per segment)
+
+Horizontal arrows mirror under `dir="rtl"`.
+
+| Key                        | Behavior                                                                                           |
+| -------------------------- | -------------------------------------------------------------------------------------------------- |
+| **0–9**                    | Type the value; auto-advances to the next segment when full.                                       |
+| **a / p**                  | On the AM/PM segment, set the period of the entered hour.                                          |
+| **ArrowUp / ArrowDown**    | Step the value. Hour / minute / second wrap; the AM/PM segment toggles. Empty seeds from midnight. |
+| **ArrowLeft / ArrowRight** | Move to the previous / next segment (no wrap).                                                     |
+| **Home / End**             | Jump to the segment minimum / maximum (the AM/PM segment → AM / PM).                               |
+| **Backspace / Delete**     | Clear a numeric segment (the value becomes `null` until refilled).                                 |
+
+The hour, minute, and second clamp to their valid ranges (hour to the cycle, minute / second to 0–59), and a composed value is clamped into `[minTime, maxTime]` by time-of-day. The AM/PM period is derived from the entered hour; clearing it is a no-op (clear or step the hour instead).
+
+## Scope defaults
+
+```ts
+import { provideForTimeFieldDefaults } from 'forty-cdk/time-field';
+
+// app config or a component's providers — localize segment labels and the
+// empty-segment announcement for every nested [forTimeField].
+providers: [
+  provideForTimeFieldDefaults({
+    emptySegmentText: 'Vacío',
+    segmentLabels: { hour: 'hora', minute: 'minuto', second: 'segundo', dayPeriod: 'AM/PM' },
+  }),
+];
+```
+
+`segmentLabels` supplies each segment's default `aria-label`, keyed by part type. Unset keys keep the library default (the part name, and `'AM/PM'` for the `dayPeriod` segment), so overriding a single key never wipes the rest. A segment's own `[ariaLabel]` still wins over the scope default.
+
+## Styling
+
+forty-cdk ships no styles. Add your own class to each piece — the `for*` selectors are the behavior API, not a styling contract (see [Styling forty-cdk](../../../../../docs/styling.md)). Key your CSS off the reflected `data-*` attributes below.
+
+### Data attributes
+
+| Piece                   | Attribute          | Values            |
+| ----------------------- | ------------------ | ----------------- |
+| `[forTimeField]`        | `data-disabled`    | present \| absent |
+| `[forTimeField]`        | `data-readonly`    | present \| absent |
+| `[forTimeField]`        | `data-empty`       | present \| absent |
+| `[forTimeFieldSegment]` | `data-highlighted` | present \| absent |
+| `[forTimeFieldSegment]` | `data-placeholder` | present \| absent |
+| `[forTimeFieldSegment]` | `data-disabled`    | present \| absent |
+| `[forTimeFieldSegment]` | `data-readonly`    | present \| absent |
+
+`[forTimeFieldLiteral]` carries no `data-*` hooks — it is `aria-hidden` and purely decorative; style it directly via your own class.
+
+```css
+.time-field-segment[data-placeholder] {
+  color: gray;
+}
+
+.time-field-segment[data-highlighted] {
+  background: highlight;
+}
+```
+
+## Accessibility notes
+
+- **`role="group"`** on the root carries the field's accessible name (`ariaLabel`, or point native `aria-labelledby` at a visible label).
+- **`role="spinbutton"`** per segment, with `aria-valuemin` / `aria-valuemax` / `aria-valuenow` reflected; the AM/PM segment also exposes a localized `aria-valuetext` ("AM" / "PM"), so screen readers read the period rather than `0` / `1`.
+- **Roving tabindex**: exactly one segment is tabbable, so `Tab` enters and leaves the whole field in one stop; arrows move between segments.
+- **Literals are `aria-hidden`** and never focusable — assistive tech reads only the spinbutton segments.
+- **Boolean `data-*`** on each segment — `data-highlighted` (focused/roving), `data-placeholder` (empty), `data-disabled`, `data-readonly` — present when true, absent when false.
+
+## Wrapping in a design system
+
+Both supported wrapper patterns — `hostDirectives` with the exported `FOR_TIME_FIELD_HOST_DIRECTIVE_INPUTS` / `FOR_TIME_FIELD_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing — are documented in [Wrapping form primitives](../../../../../docs/wrapping-form-primitives.md).

package/time-picker/README.md

@@ -0,0 +1,172 @@
+# ForTimePicker
+
+Headless, styleless slot-based time picker. Implements the
+[WAI-ARIA Listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/) — a
+combobox trigger opens a floating listbox of generated time slots. Value is typed as
+your adapter's date-time type `D`.
+
+Requires a time-capable adapter:
+[`provideNativeDateAdapter()`](../calendar/native-date-adapter.ts) or the
+`@internationalized/date` adapter from `forty-cdk/internationalized-date`.
+
+## Usage
+
+```html
+<div
+  forTimePicker
+  [(value)]="value"
+  [(open)]="open"
+  [step]="30"
+  [hourCycle]="24"
+  #picker="forTimePicker"
+>
+  <button forTimePickerTrigger>
+    <span forTimePickerValue placeholder="Pick a time"></span>
+  </button>
+
+  @if (open()) {
+  <div forTimePickerContent>
+    @for (slot of picker.slots(); track slot.id) {
+    <div forTimePickerOption [value]="slot.value" [disabled]="slot.disabled">{{ slot.label }}</div>
+    }
+  </div>
+  }
+</div>
+```
+
+## Pieces
+
+| Piece                  | Selector                 | Role                                                                                                                       |
+| ---------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `ForTimePicker`        | `[forTimePicker]`        | Root — state, slots, context                                                                                               |
+| `ForTimePickerTrigger` | `[forTimePickerTrigger]` | Combobox button                                                                                                            |
+| `ForTimePickerValue`   | `[forTimePickerValue]`   | Display element                                                                                                            |
+| `ForTimePickerContent` | `[forTimePickerContent]` | Portaled listbox                                                                                                           |
+| `ForTimePickerOption`  | `[forTimePickerOption]`  | Option (non-button `<div>`)                                                                                                |
+| `ForTimePickerAnchor`  | `[forTimePickerAnchor]`  | Optional positioning anchor — wrap a decorated field box so the listbox aligns to the visible field instead of the trigger |
+
+## Inputs (root)
+
+| Input           | Type                             | Default    | Description                      |
+| --------------- | -------------------------------- | ---------- | -------------------------------- |
+| `value`         | `D \| null`                      | `null`     | Selected time (two-way)          |
+| `open`          | `boolean`                        | `false`    | Open state (two-way)             |
+| `step`          | `number`                         | `30`       | Slot interval in minutes         |
+| `granularity`   | `'hour' \| 'minute' \| 'second'` | `'minute'` | Selection precision              |
+| `hourCycle`     | `12 \| 24 \| null`               | `null`     | Hour cycle for labels            |
+| `locale`        | `string \| null`                 | `null`     | BCP 47 locale for labels         |
+| `minTime`       | `D \| null`                      | `null`     | Earliest selectable time         |
+| `maxTime`       | `D \| null`                      | `null`     | Latest selectable time           |
+| `closeOnSelect` | `boolean`                        | `true`     | Close on slot selection          |
+| `modal`         | `boolean`                        | `false`    | Modal (focus-trapped) mode       |
+| `dismissible`   | `boolean`                        | `true`     | Escape / outside close           |
+| `returnFocus`   | `boolean`                        | `true`     | Return focus to trigger on close |
+| `placeholder`   | `string`                         | `''`       | Value display placeholder        |
+| `formatOptions` | `Intl.DateTimeFormatOptions`     | `{}`       | Override slot label format       |
+
+Inherits all `FormUiControl` inputs (`disabled`, `readonly`, `required`, `invalid`,
+`errors`, `touched`, `name`, `pending`) for `[formField]` auto-wiring.
+
+## Signal Forms
+
+```html
+<div forTimePicker [formField]="profile.meetingTime" [(open)]="open" #picker="forTimePicker">
+  <button forTimePickerTrigger>
+    <span forTimePickerValue placeholder="Pick a time"></span>
+  </button>
+  @if (open()) {
+  <div forTimePickerContent>
+    @for (slot of picker.slots(); track slot.id) {
+    <div forTimePickerOption [value]="slot.value" [disabled]="slot.disabled">{{ slot.label }}</div>
+    }
+  </div>
+  }
+</div>
+```
+
+## Anchoring to a field box
+
+By default the listbox is positioned against `[forTimePickerTrigger]`. When the trigger lives inside a decorated field box — padding, a prefix icon, a clear / chevron button — anchoring to the inner button makes the panel offset from the visible field's edge. Wrap the field box in `[forTimePickerAnchor]` so floating-ui positions (and sizes, via `--for-anchor-width`) the listbox against the box instead:
+
+```html
+<div forTimePicker #picker="forTimePicker" [(value)]="value" [(open)]="open">
+  <div forTimePickerAnchor class="field-box">
+    <icon name="clock" />
+    <button forTimePickerTrigger>
+      <span forTimePickerValue placeholder="Pick a time"></span>
+    </button>
+    <button class="clear" (click)="value.set(null)">×</button>
+  </div>
+  @if (open()) {
+  <div forTimePickerContent style="width: var(--for-anchor-width)">
+    @for (slot of picker.slots(); track slot.id) {
+    <div forTimePickerOption [value]="slot.value" [disabled]="slot.disabled">{{ slot.label }}</div>
+    }
+  </div>
+  }
+</div>
+```
+
+`[forTimePickerAnchor]` changes **only** positioning. The trigger keeps `aria-haspopup` / `aria-expanded` / `aria-controls`, the click toggle, focus return on close, and its exemption from outside-pointer dismissal. Without an anchor the listbox falls back to the trigger, so existing markup is unaffected. At most one `[forTimePickerAnchor]` per `[forTimePicker]` — a second one throws `[forty-cdk/time-picker]`.
+
+## Date-time composition
+
+Place `[forTimePicker]` inside `[forDatePickerContent]` alongside a `[forCalendar]`. The
+`FOR_TIME_VALUE_SOURCE` token is provided by `[forTimePicker]`, and `[forDatePicker]`
+resolves it automatically via `contentChild` to graft time changes onto the committed date.
+
+```html
+<div forDatePicker granularity="minute" [(value)]="value" [(open)]="open" #dp="forDatePicker">
+  <button forDatePickerTrigger>...</button>
+  @if (open()) {
+  <div forDatePickerContent>
+    <div forCalendar [value]="dp.value()">...</div>
+    <div forTimePicker [value]="dp.value()" [step]="60" #tp="forTimePicker">
+      <button forTimePickerTrigger>...</button>
+      @if (tp.open()) {
+      <div forTimePickerContent>
+        @for (slot of tp.slots(); track slot.id) {
+        <div forTimePickerOption [value]="slot.value" [disabled]="slot.disabled">
+          {{ slot.label }}
+        </div>
+        }
+      </div>
+      }
+    </div>
+  </div>
+  }
+</div>
+```
+
+## Wrapping with `hostDirectives`
+
+```typescript
+import {
+  FOR_TIME_PICKER_HOST_DIRECTIVE_INPUTS,
+  FOR_TIME_PICKER_HOST_DIRECTIVE_OUTPUTS,
+  ForTimePicker,
+} from 'forty-cdk/time-picker';
+
+@Component({
+  selector: '[myTimePicker]',
+  hostDirectives: [
+    {
+      directive: ForTimePicker,
+      inputs: [...FOR_TIME_PICKER_HOST_DIRECTIVE_INPUTS],
+      outputs: [...FOR_TIME_PICKER_HOST_DIRECTIVE_OUTPUTS],
+    },
+  ],
+})
+export class MyTimePicker {}
+```
+
+## Keyboard interaction
+
+| Key                     | Behavior                                  |
+| ----------------------- | ----------------------------------------- |
+| `Enter` / `Space`       | Select the focused slot                   |
+| `ArrowDown` / `ArrowUp` | Move focus between slots                  |
+| `Home`                  | Focus the first enabled slot              |
+| `End`                   | Focus the last enabled slot               |
+| `Tab`                   | Commit the focused slot and advance focus |
+| `Escape`                | Close without committing                  |