forty-cdk 0.4.0 → 0.5.0

package/date-picker/README.md

@@ -286,6 +286,59 @@ readonly dateRange = signal<CalendarDateRange<CalendarDate> | null>(null);
 | `range`           | `model<CalendarDateRange<D> \| null>` | Two-way bindable committed range. `(rangeChange)` fires only on commit / clear. Default `null`. |
 | `rangeSeparator`  | `input<string>`                       | String placed between start and end in the formatted display. Default `' – '`.                  |
 
+## Range as a Signal Forms value — `ForDateRangePicker`
+
+`ForDatePicker[selectionMode="range"]` exposes the range through a plain two-way `[(range)]` model with **no** form contract — so a range inside a form has to be hand-wired. `ForDateRangePicker` (selector `[forDateRangePicker]`) is the form-capable sibling: it is the root **and** the form value, implementing `FormValueControl<CalendarDateRange<D> | null>`, so the committed range auto-wires with `[formField]` exactly like any other control.
+
+It reuses the same pieces — `[forDatePickerTrigger]`, `[forDatePickerContent]`, `[forDatePickerValue]`, `[forDatePickerAnchor]` — through a shared base, and provides `FOR_DATE_PICKER_CONTEXT` so they resolve under it. Project a `[forCalendar]` in `selectionMode="range"` and bind its range to the picker's `value`; the two-click anchor → commit flow keeps `value` `null` until both endpoints are chosen (the form never sees a half-entered range), and `start <= end` is an invariant. Range is day-granular in v1 (no time composition).
+
+```ts
+import { type CalendarDateRange } from 'forty-cdk/calendar';
+import { ForDateRangePicker } from 'forty-cdk/date-picker';
+import { form } from '@angular/forms/signals';
+
+interface Booking {
+  stay: CalendarDateRange<CalendarDate> | null;
+}
+readonly model = signal<Booking>({ stay: null });
+readonly booking = form(this.model, (p) => required(p.stay));
+```
+
+```html
+<div
+  forDateRangePicker
+  [formField]="booking.stay"
+  [(open)]="open"
+  [ariaLabel]="'Choose date range'"
+  #picker="forDateRangePicker"
+>
+  <button forDatePickerTrigger>
+    <span forDatePickerValue [placeholder]="'Pick a range'"></span>
+  </button>
+
+  @if (open()) {
+  <div forDatePickerContent>
+    <div
+      forCalendar
+      selectionMode="range"
+      [(range)]="picker.value"
+      [min]="picker.minDate()"
+      [max]="picker.maxDate()"
+    >
+      <!-- …header + grid… -->
+    </div>
+  </div>
+  }
+</div>
+```
+
+- **Form value.** The committed `CalendarDateRange<D> | null` is the `value` model. `null` is the empty state — pair it with `required(p.stay)` so `invalid()` flips when the form demands a range and none is committed. `touched` fires on commit and on close, exactly like the single-date picker.
+- **Validity.** `start <= end` is guaranteed by construction and is never an error. Forward `minDate` / `maxDate` to the calendar's `[min]` / `[max]`, and `minRangeLength` / `maxRangeLength` to the calendar's `[minRangeLength]` / `[maxRangeLength]` (a too-short / too-long range is rejected as a no-op by the calendar's two-click flow).
+- **Native submission.** When `name` is set, two hidden inputs `<name>-start` / `<name>-end` mirror the committed endpoints as ISO `YYYY-MM-DD` for native `<form>` posts.
+- **Bounds naming.** `minDate` / `maxDate` (not `min` / `max`) for the same reason as `ForDatePicker` — and additionally because `FormUiControl.min` / `max` are typed `NonNullable<TValue>` (the range object itself), which is meaningless as a bound.
+
+Defaults are configured with `provideForDateRangePickerDefaults` (`sideOffset` / `collisionPadding`), and both wrapper patterns work via the exported `FOR_DATE_RANGE_PICKER_HOST_DIRECTIVE_INPUTS` / `FOR_DATE_RANGE_PICKER_HOST_DIRECTIVE_OUTPUTS` tuples — see [Wrapping form primitives](../../../../../docs/wrapping-form-primitives.md).
+
 ## 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.

package/date-range-field/README.md

@@ -0,0 +1,173 @@
+# DateRangeField
+
+Headless, segmented, spin-editable date **range** input — the keyboard-first, form-capable counterpart to [DateRangePicker](../date-picker/README.md). There is **no single WAI-ARIA APG pattern** for a range field; it is a composition of two labelled `role="group"` endpoints (start / end), each holding a row of [Spinbuttons](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/) — the same machinery as [DateField](../date-field/README.md) — nested inside one outer `role="group"`. Segment **order** and separators follow the runtime locale (`MM/DD/YYYY` vs `DD.MM.YYYY` vs `YYYY/MM/DD`).
+
+`ForDateRangeField` implements `FormValueControl<CalendarDateRange<D> | null>` from `@angular/forms/signals` — the **same** contract as `ForDateRangePicker` — so the committed range auto-wires with `[formField]` and auto-associates inside a `[forField]` (label / description / error) with no extra markup. The value stays `null` until **both** endpoints are fully entered and ordered (`start <= end`); a half-entered or out-of-order range never reaches the form.
+
+## Date adapter — pick one (required)
+
+All date math goes through the same pluggable `DateAdapter<D>` as `ForCalendar`, so the library hard-depends on **no** date library. Provide exactly one adapter in your application (or component) providers:
+
+| Provider                                | Date type `D`                              | Dependency                                                                                                |
+| --------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `provideInternationalizedDateAdapter()` | `CalendarDate` (`@internationalized/date`) | **Recommended.** From `forty-cdk/internationalized-date`; needs `@internationalized/date` (optional peer) |
+| `provideNativeDateAdapter()`            | `Date`                                     | None (zero-dependency fallback)                                                                           |
+
+## Pieces
+
+| Class                      | Selector                     | Role                                                                                                         |
+| -------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `ForDateRangeField`        | `[forDateRangeField]`        | Root (`role="group"`). Owns both endpoint engines, composes the `CalendarDateRange`, the `FormValueControl`. |
+| `ForDateRangeFieldStart`   | `[forDateRangeFieldStart]`   | Start endpoint group (`role="group"`). Its own tab stop; exposes `segments()`.                               |
+| `ForDateRangeFieldEnd`     | `[forDateRangeFieldEnd]`     | End endpoint group (`role="group"`). Its own tab stop; exposes `segments()`.                                 |
+| `ForDateRangeFieldSegment` | `[forDateRangeFieldSegment]` | One editable part (`role="spinbutton"`). Roving tab stop, ARIA value reflection, keyboard editing.           |
+| `ForDateRangeFieldLiteral` | `[forDateRangeFieldLiteral]` | A decorative separator (`/`, `.`, `-`, `:`). `aria-hidden`, out of the tab order.                            |
+
+## Inputs / models — `ForDateRangeField`
+
+| API           | Type                                                  | Description                                                                                                                   |
+| ------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `value`       | `model<CalendarDateRange<D> \| null>`                 | Two-way bindable committed range, or `null` while incomplete or out of order. The `FormValueControl` backing. Default `null`. |
+| `minDate`     | `input<D \| null>`                                    | Minimum date (inclusive) for both endpoints. A composed endpoint below it is clamped up. Named `minDate` — see note below.    |
+| `maxDate`     | `input<D \| null>`                                    | Maximum date (inclusive) for both endpoints. A composed endpoint above it is clamped down. Default `null`.                    |
+| `granularity` | `input<'day' \| 'hour' \| 'minute' \| 'second'>`      | Date-time precision shared by both endpoints. `'day'` (default) is date-only; coarser-than-day off appends time segments.     |
+| `hourCycle`   | `input<12 \| 24 \| null>`                             | 12/24-hour cycle for the time segments. Default `null` → locale. 12-hour adds the AM/PM segment.                              |
+| `locale`      | `input<string \| null>`                               | BCP 47 locale driving segment order, separators, and month name. Default `null` → runtime locale.                             |
+| `placeholder` | `input<Partial<Record<DateTimeSegmentType, string>>>` | Per-segment placeholder while empty, applied to both endpoints. Default `{}`.                                                 |
+| `ariaLabel`   | `input<string \| null>`                               | Accessible name for the whole range field 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.          |
+
+The endpoint groups (`[forDateRangeFieldStart]` / `[forDateRangeFieldEnd]`) each accept an `ariaLabel` input for their own group label, falling back to the scope defaults (`'Start date'` / `'End date'`).
+
+Plus the shared `FormUiControl` members from `@angular/forms/signals`: `disabled`, `readonly`, `required`, `invalid`, `name`, `errors`, `touched` (bound automatically by `[formField]`).
+
+> **Why `minDate` / `maxDate`, not `min` / `max`?** `FormUiControl.min` / `max` are reserved members typed `number | undefined` for numeric validators, and additionally typed `NonNullable<TValue>` (the range object itself), which is meaningless as a bound — so the date bounds use distinct names.
+
+## Usage
+
+```ts
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { CalendarDate } from '@internationalized/date';
+import { CalendarDateRange } from 'forty-cdk/calendar';
+import {
+  ForDateRangeField,
+  ForDateRangeFieldEnd,
+  ForDateRangeFieldLiteral,
+  ForDateRangeFieldSegment,
+  ForDateRangeFieldStart,
+} from 'forty-cdk/date-range-field';
+
+@Component({
+  selector: 'app-stay',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    ForDateRangeField,
+    ForDateRangeFieldStart,
+    ForDateRangeFieldEnd,
+    ForDateRangeFieldSegment,
+    ForDateRangeFieldLiteral,
+  ],
+  template: `
+    <div forDateRangeField class="range-field" [(value)]="stay" [ariaLabel]="'Stay'">
+      <div forDateRangeFieldStart class="range-endpoint" #start="forDateRangeFieldStart">
+        @for (seg of start.segments(); track seg.id) {
+          @if (seg.isLiteral) {
+            <span forDateRangeFieldLiteral>{{ seg.text }}</span>
+          } @else {
+            <span forDateRangeFieldSegment class="range-segment" [segment]="seg.type!">{{
+              seg.text
+            }}</span>
+          }
+        }
+      </div>
+      <span aria-hidden="true">–</span>
+      <div forDateRangeFieldEnd class="range-endpoint" #end="forDateRangeFieldEnd">
+        @for (seg of end.segments(); track seg.id) {
+          @if (seg.isLiteral) {
+            <span forDateRangeFieldLiteral>{{ seg.text }}</span>
+          } @else {
+            <span forDateRangeFieldSegment class="range-segment" [segment]="seg.type!">{{
+              seg.text
+            }}</span>
+          }
+        }
+      </div>
+    </div>
+  `,
+})
+export class StayField {
+  readonly stay = signal<CalendarDateRange<CalendarDate> | null>(null);
+}
+```
+
+## Ordering
+
+The two endpoints are typed independently, so order is not guaranteed by construction the way the picker's two-click flow guarantees it. The field preserves the `CalendarDateRange` `end >= start` invariant by **never emitting an out-of-order range**: when both endpoints are complete but `start > end`, the typed segments are kept (not silently rewritten), `value` stays `null`, and the root reflects `aria-invalid="true"` + `data-range-error` so the disorder is perceivable and stylable. Editing either endpoint back into order emits the range.
+
+## Keyboard (per segment)
+
+Each endpoint is its own tab stop, so `Tab` moves from the start group to the end group to the next control; arrows move between segments **within** an endpoint. Horizontal arrows mirror under `dir="rtl"`.
+
+| Key                        | Behavior                                                                 |
+| -------------------------- | ------------------------------------------------------------------------ |
+| **0–9**                    | Type the value; auto-advances to the next segment when full.             |
+| **ArrowUp / ArrowDown**    | Step the value. Day and month wrap; year clamps. Empty seeds from today. |
+| **ArrowLeft / ArrowRight** | Move to the previous / next segment in the same endpoint (no wrap).      |
+| **Home / End**             | Jump to the segment minimum / maximum.                                   |
+| **Backspace / Delete**     | Clear the segment (the range becomes `null` until refilled).             |
+
+The day clamps to the current month's length (e.g. 31 → 28 in February), and each composed endpoint is clamped into `[minDate, maxDate]`.
+
+## Date-time range (`granularity > 'day'`)
+
+Set `granularity` to `'hour'`, `'minute'`, or `'second'` to append time segments to **each** endpoint — hour / minute / second and, in 12-hour mode, an AM·PM `dayPeriod`. This needs a **time-capable** adapter — `provideNativeDateAdapter()` (`Date`) or `provideInternationalizedDateTimeAdapter()` (`CalendarDateTime`); the day-only `provideInternationalizedDateAdapter()` (`CalendarDate`) throws.
+
+## Scope defaults
+
+```ts
+import { provideForDateRangeFieldDefaults } from 'forty-cdk/date-range-field';
+
+// app config or a component's providers — localize the endpoint group labels,
+// segment labels, and the empty-segment announcement for every nested field.
+providers: [
+  provideForDateRangeFieldDefaults({
+    emptySegmentText: 'Vacío',
+    startLabel: 'Desde',
+    endLabel: 'Hasta',
+    segmentLabels: { day: 'día', month: 'mes', year: 'año', dayPeriod: 'AM/PM' },
+  }),
+];
+```
+
+`startLabel` / `endLabel` supply each endpoint group's default `aria-label`; `segmentLabels` supplies each segment's default `aria-label`, keyed by part type. Unset keys keep the library default, so overriding a single key never wipes the rest. An endpoint's own `[ariaLabel]`, or 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            |
+| ---------------------------- | ------------------ | ----------------- |
+| `[forDateRangeField]`        | `data-disabled`    | present \| absent |
+| `[forDateRangeField]`        | `data-readonly`    | present \| absent |
+| `[forDateRangeField]`        | `data-empty`       | present \| absent |
+| `[forDateRangeField]`        | `data-range-error` | present \| absent |
+| `[forDateRangeFieldSegment]` | `data-highlighted` | present \| absent |
+| `[forDateRangeFieldSegment]` | `data-placeholder` | present \| absent |
+| `[forDateRangeFieldSegment]` | `data-disabled`    | present \| absent |
+| `[forDateRangeFieldSegment]` | `data-readonly`    | present \| absent |
+
+`data-empty` marks the whole field while the range is `null` (either endpoint unfilled, or the two out of order); `data-range-error` marks the specific case of two complete but out-of-order endpoints; `data-placeholder` marks each individual segment that is still empty. `data-highlighted` is the current roving-tabindex segment — the only focus hook the consumer gets, shared with the other roving primitives.
+
+## Accessibility notes
+
+- **`role="group"`** on the root carries the field's accessible name (`ariaLabel`, or point native `aria-labelledby` at a visible label); each endpoint is its own labelled `role="group"`.
+- **`role="spinbutton"`** per segment, with `aria-valuemin` / `aria-valuemax` / `aria-valuenow` reflected; the month segment also exposes a localized `aria-valuetext` ("March").
+- **Roving tabindex per endpoint**: exactly one segment per endpoint is tabbable, so `Tab` steps start group → end group; arrows move between segments within an endpoint.
+- **`aria-invalid="true"`** is reflected on the root when the form marks it invalid **or** when two complete endpoints are out of order.
+- **Literals are `aria-hidden`** and never focusable — assistive tech reads only the spinbutton segments.
+
+## Wrapping in a design system
+
+Both supported wrapper patterns — `hostDirectives` with the exported `FOR_DATE_RANGE_FIELD_HOST_DIRECTIVE_INPUTS` / `FOR_DATE_RANGE_FIELD_HOST_DIRECTIVE_OUTPUTS` name tuples, and subclassing — are documented in [Wrapping form primitives](../../../../../docs/wrapping-form-primitives.md).

package/fesm2022/forty-cdk-combobox.mjs

@@ -155,7 +155,13 @@ function findSelectedEnabled(items, values, equals) {
  *    The seed itself comes from the linkedSignal; this is its imperative tail.
  *    The activedescendant is read `untracked` so the scroll never re-triggers
  *    the effect, and pointer-move hover doesn't reach here (it changes none of
- *    the tracked reads), so hovering never scrolls.
+ *    the tracked reads), so hovering never scrolls. This handles a re-seed while
+ *    the listbox is already open (e.g. the consumer's filter dropped the active
+ *    option). The **initial open** scroll runs here too but is wiped a tick
+ *    later when `[forComboboxContent]` portals to `document.body` (which resets
+ *    `scrollTop`); `ForCombobox.scrollActiveOptionIntoView` re-applies it from
+ *    the positioner's first-resolved-position hook, after the portal move and
+ *    after the surface is sized (#1066).
  *
  * Internal — not re-exported from `combobox/index.ts` or `public-api.ts`.
  */
@@ -1023,6 +1029,37 @@ class ForCombobox extends FormUiControlBase {
         this.#pointerSuppression.suppress();
         host.scrollIntoView?.({ block: 'nearest' });
     }
+    /**
+     * Scroll the current activedescendant option into view. Driven from
+     * `[forComboboxContent]`'s positioner first-resolved-position hook
+     * (`onFirstPosition`) — the only moment both prerequisites hold: the content
+     * has been portaled to `document.body` (which resets the scroll container's
+     * `scrollTop` to 0, wiping the seed scroll the auto-highlight bridge applied
+     * during change detection) and `@floating-ui/dom`'s `size` middleware has
+     * constrained the surface to its `max-height` (so it is actually scrollable).
+     *
+     * Re-applies the scroll unconditionally — the bridge already recorded this id
+     * as positioned, but the portal move invalidated the real scroll position, so
+     * the usual "already positioned" guard must not short-circuit here. Fires once
+     * per open (the positioner hook is one-shot per run), so a later hover never
+     * scrolls. No-op while virtualizing: the navigator owns the virtualized scroll
+     * and the indexed seed is intentionally passive.
+     */
+    scrollActiveOptionIntoView() {
+        if (this.totalCount() !== undefined) {
+            return;
+        }
+        const id = this.#activeId();
+        if (id === null) {
+            return;
+        }
+        const active = this.#items.items().find((o) => o.id() === id);
+        if (!active) {
+            return;
+        }
+        active.host.scrollIntoView?.({ block: 'nearest' });
+        this.#lastPositionedId = id;
+    }
     #cachedOptionsMemo = computed(() => {
         if (this.totalCount() === undefined) {
             return this.#labelCache.entries();
@@ -1652,6 +1689,7 @@ class ForComboboxContent {
                 sticky: ctx.sticky,
                 hideWhenDetached: ctx.hideWhenDetached,
                 clipUntilPositioned: ctx.clipUntilPositioned,
+                onFirstPosition: () => ctx.scrollActiveOptionIntoView(),
             },
             dismiss: {
                 dismissible: ctx.dismissible,