forty-cdk 0.2.0 → 0.3.0

package/types/forty-cdk-date-field.d.ts

@@ -0,0 +1,307 @@
+import * as forty_cdk_core from 'forty-cdk/core';
+import { FieldSegment, SegmentEditorContext, SegmentHandle, FormUiControlBase, DateAdapter, SegmentType, WritingDirection, RovingTabindex, ForDateTimeSegmentBase, ForDateTimeLiteralBase } from 'forty-cdk/core';
+export { DateSegmentType, SegmentType as DateTimeSegmentType } from 'forty-cdk/core';
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Provider } from '@angular/core';
+import { FormValueControl } from '@angular/forms/signals';
+
+/** Date-time precision of a date field; `'day'` keeps it date-only. */
+type FieldGranularity = 'day' | 'hour' | 'minute' | 'second';
+
+/**
+ * A rendered segment descriptor exposed by `ForDateField.segments()` for the
+ * consumer's `@for`. Covers both editable spinbutton segments and the
+ * decorative literal separators between them.
+ */
+type DateFieldSegment = FieldSegment;
+/** Handle a `[forDateFieldSegment]` registers with the root for focus moves. */
+type ForDateFieldSegmentHandle = SegmentHandle;
+/**
+ * The coordination surface `ForDateField` exposes to its segment / literal
+ * children. Segments read the reactive per-part accessors for their ARIA and
+ * display bindings, and call the behavior methods to type, step, clear, and
+ * move focus — all canonical state lives on the root, never on the segment.
+ *
+ * It is the shared {@link SegmentEditorContext} backing both date and time
+ * fields; `ForDateField` satisfies it by forwarding to its `SegmentEditor`.
+ */
+type ForDateFieldContext = SegmentEditorContext;
+/**
+ * Injection token for the {@link ForDateFieldContext} provided by
+ * `[forDateField]`. Segment and literal children inject it to coordinate with
+ * the root.
+ */
+declare const FOR_DATE_FIELD_CONTEXT: InjectionToken<SegmentEditorContext>;
+
+/**
+ * Headless, segmented, spin-editable date input — the keyboard-first
+ * counterpart to `ForCalendar`. There is no single WAI-ARIA APG pattern for a
+ * date field; it is a composition of
+ * [Spinbuttons](https://www.w3.org/WAI/ARIA/apg/patterns/spinbutton/) inside a
+ * labelled `role="group"`.
+ * Each day / month / year part is an independent `role="spinbutton"` segment
+ * (`[forDateFieldSegment]`) so entry is unambiguous and locale-correct — no
+ * free-text parsing, no `03/04`-is-it-March-4th guesswork.
+ *
+ * `ForDateField` is the root: it owns the entered parts, composes them into the
+ * adapter's date type, resolves the locale-ordered segment list, and exposes
+ * everything to the segment / literal children through
+ * {@link FOR_DATE_FIELD_CONTEXT}. The spin-button engine (digit typing, stepping,
+ * Home/End, RTL focus moves, the segment registry) lives in the shared
+ * `_internal/datetime` {@link SegmentEditor}; the root supplies only the
+ * date-specific bits (segment bounds, the today-seed, the month-name
+ * `aria-valuetext`, and the create/clamp compose). All date math goes through
+ * the pluggable {@link DateAdapter} shared with `ForCalendar`
+ * (`provideInternationalizedDateAdapter()` / `provideNativeDateAdapter()`), so
+ * the field hard-depends on no date library.
+ *
+ * Set `granularity` coarser-than-a-day off (`'hour'` / `'minute'` / `'second'`)
+ * to make it a **date-time field**: time segments (hour / minute / second and,
+ * in 12-hour mode, an AM·PM `dayPeriod`) are appended after the date segments in
+ * the same `role="group"`, sharing the one roving tab stop. This needs a
+ * time-capable adapter (`provideNativeDateAdapter()` /
+ * `provideInternationalizedDateTimeAdapter()`); `granularity = 'day'` (default)
+ * is unchanged and works with any adapter.
+ *
+ * It implements `FormValueControl<D | null>` from `@angular/forms/signals`, so
+ * it auto-wires with `[formField]` and auto-associates inside a `[forField]`.
+ * The value stays `null` until every visible segment is filled.
+ *
+ * @typeParam D The adapter's immutable date (or, with `granularity > 'day'`,
+ *   date-time) type.
+ *
+ * Note: the date bounds are named `minDate` / `maxDate`, not `min` / `max` —
+ * the latter are reserved `FormUiControl` members typed `number | undefined`
+ * for numeric validators, so a date-typed `min` / `max` would break the
+ * `FormValueControl` contract.
+ *
+ * @example
+ * ```html
+ * <div forDateField [(value)]="date" [minDate]="min" [maxDate]="max" name="dob"
+ *      [ariaLabel]="'Date of birth'" #field="forDateField">
+ *   @for (seg of field.segments(); track seg.id) {
+ *     @if (seg.isLiteral) {
+ *       <span forDateFieldLiteral>{{ seg.text }}</span>
+ *     } @else {
+ *       <span forDateFieldSegment [segment]="seg.type!">{{ seg.text }}</span>
+ *     }
+ *   }
+ * </div>
+ * ```
+ */
+declare class ForDateField<D> extends FormUiControlBase implements FormValueControl<D | null>, ForDateFieldContext {
+    #private;
+    /** The active date adapter, resolved from `FOR_DATE_ADAPTER` (shared with `ForCalendar`). */
+    readonly adapter: DateAdapter<D>;
+    /**
+     * Two-way bindable entered date, or `null` while any segment is empty.
+     * Required by `FormValueControl<D | null>`. The `model()` change emitter
+     * (`(valueChange)`) fires only when the field itself composes a new value,
+     * never on consumer writes via `[(value)]`.
+     */
+    readonly value: _angular_core.ModelSignal<D | null>;
+    /**
+     * Minimum selectable date (inclusive). A composed value below it is clamped
+     * up. The comparison is by the **full instant** (`DateAdapter.compare`), so at
+     * `granularity > 'day'` a non-midnight `minDate` clamps the time too, and the
+     * result is identical across time-capable adapters. Named `minDate` (not
+     * `min`) because `FormUiControl.min` is reserved for a numeric validator bound
+     * by `[formField]`.
+     */
+    readonly minDate: _angular_core.InputSignal<D | null>;
+    /**
+     * Maximum selectable date (inclusive). A composed value above it is clamped
+     * down. Compared by the **full instant** like {@link minDate}. Named `maxDate`
+     * (not `max`) for the same reason as {@link minDate}.
+     */
+    readonly maxDate: _angular_core.InputSignal<D | null>;
+    /**
+     * Date-time precision. `'day'` (default, **non-breaking**) is a pure date
+     * field. `'hour'` / `'minute'` / `'second'` append the matching time segments
+     * and the value carries a time component — which requires a time-capable
+     * adapter (`provideNativeDateAdapter()` /
+     * `provideInternationalizedDateTimeAdapter()`).
+     */
+    readonly granularity: _angular_core.InputSignal<FieldGranularity>;
+    /**
+     * 12- or 24-hour cycle for the time segments. When `null` (default) it is
+     * derived from the locale. A 12-hour cycle adds the AM/PM `dayPeriod` segment.
+     * Only meaningful when `granularity > 'day'`.
+     */
+    readonly hourCycle: _angular_core.InputSignal<12 | 24 | null>;
+    /** BCP 47 locale driving segment order and separators. Defaults to the runtime locale. */
+    readonly locale: _angular_core.InputSignal<string | null>;
+    /**
+     * Per-segment placeholder shown while empty. Unspecified parts fall back to a
+     * letter-repeat default (`dd` / `mm` / `yyyy` / `hh` / `mm` / `ss` / `--`).
+     */
+    readonly placeholder: _angular_core.InputSignal<Partial<Record<SegmentType, string>>>;
+    /** Accessible name for the field group. Emits no `aria-label` while `null`. */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * Writing direction. When unset (default `null`), the inherited ambient
+     * direction is resolved from the nearest ancestor carrying a `dir` attribute
+     * (or `<html dir>`), defaulting to `'ltr'`. An explicit `[dir]` always wins.
+     * The resolved value is reflected to the host `dir` attribute and mirrors the
+     * ArrowLeft / ArrowRight segment navigation in RTL.
+     */
+    readonly _dirInput: _angular_core.InputSignal<WritingDirection | null>;
+    readonly dir: _angular_core.Signal<WritingDirection>;
+    /** Shared roving-tabindex tracker: exactly one segment owns `tabindex=0`. */
+    readonly roving: RovingTabindex;
+    /**
+     * The ordered, locale-derived segments (editable + literals) to render. Each
+     * entry carries the text to display: the formatted value when filled, the
+     * placeholder while empty, or the literal separator.
+     */
+    readonly segments: _angular_core.Signal<readonly forty_cdk_core.FieldSegment<SegmentType>[]>;
+    constructor();
+    segmentValue(type: SegmentType): number | null;
+    segmentMin(type: SegmentType): number;
+    segmentMax(type: SegmentType): number;
+    segmentValueText(type: SegmentType): string | null;
+    segmentDisplayText(type: SegmentType): string;
+    isSegmentEmpty(type: SegmentType): boolean;
+    isFirstSegmentType(type: SegmentType): boolean;
+    registerSegment(handle: SegmentHandle): void;
+    unregisterSegment(handle: SegmentHandle): void;
+    focusSegment(type: SegmentType): void;
+    typeDigit(type: SegmentType, digit: number): void;
+    step(type: SegmentType, delta: number): void;
+    goToBound(type: SegmentType, bound: 'min' | 'max'): void;
+    setDayPeriod(period: 'am' | 'pm'): void;
+    clear(type: SegmentType): void;
+    focusSibling(type: SegmentType, step: -1 | 1): void;
+    protected onFocusOut(event: FocusEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDateField<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDateField<any>, "[forDateField]", ["forDateField"], { "value": { "alias": "value"; "required": false; "isSignal": true; }; "minDate": { "alias": "minDate"; "required": false; "isSignal": true; }; "maxDate": { "alias": "maxDate"; "required": false; "isSignal": true; }; "granularity": { "alias": "granularity"; "required": false; "isSignal": true; }; "hourCycle": { "alias": "hourCycle"; "required": false; "isSignal": true; }; "locale": { "alias": "locale"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "_dirInput": { "alias": "dir"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, never, never, true, never>;
+}
+
+/**
+ * One editable spinbutton segment of a `[forDateField]` — the day, month, or
+ * year part (and, at `granularity > 'day'`, hour / minute / second / the AM·PM
+ * `dayPeriod`). Apply on a focusable element (typically a `<span>`); the shared
+ * {@link ForDateTimeSegmentBase} adds `role="spinbutton"`, the `aria-valuemin` /
+ * `aria-valuemax` / `aria-valuenow` / `aria-valuetext` reflection, the roving
+ * tabindex, and the full keyboard map:
+ *
+ * - **digits** fill a numeric segment and auto-advance to the next when full;
+ * - **a / p** set the period on the AM/PM (`dayPeriod`) segment;
+ * - **ArrowUp / ArrowDown** step the value (day / month / hour / minute / second
+ *   wrap, year clamps, dayPeriod toggles);
+ * - **ArrowLeft / ArrowRight** move between segments (mirrored under RTL, no wrap);
+ * - **Home / End** jump to the segment minimum / maximum (dayPeriod → AM / PM);
+ * - **Backspace / Delete** clear a numeric segment.
+ *
+ * All state lives on the root `ForDateField`; the segment only reads it and
+ * forwards intents. The rendered text comes from the root's `segments()` list
+ * (`{{ seg.text }}`), so this element carries behavior and ARIA, not content.
+ */
+declare class ForDateFieldSegment extends ForDateTimeSegmentBase {
+    #private;
+    protected readonly ctx: forty_cdk_core.SegmentEditorContext;
+    /** Which date or time part this segment edits. */
+    readonly segment: _angular_core.InputSignal<SegmentType>;
+    /**
+     * Accessible name for this segment. Falls back to the scope's localized
+     * default label for the part (via `provideForDateFieldDefaults`), which in
+     * turn defaults to the part name — and `'AM/PM'` for the `dayPeriod` segment.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    protected readonly resolvedAriaLabel: _angular_core.Signal<string>;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDateFieldSegment, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDateFieldSegment, "[forDateFieldSegment]", ["forDateFieldSegment"], { "segment": { "alias": "segment"; "required": true; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * A decorative separator (`/`, `.`, `-`) between the editable segments of a
+ * `[forDateField]`. Apply on the element rendering the literal text; it is
+ * marked `aria-hidden` and stays out of the tab order, so assistive tech reads
+ * only the spinbutton segments. The separator characters come from the root's
+ * locale-ordered `segments()` list (`{{ seg.text }}`).
+ */
+declare class ForDateFieldLiteral extends ForDateTimeLiteralBase {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ForDateFieldLiteral, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<ForDateFieldLiteral, "[forDateFieldLiteral]", ["forDateFieldLiteral"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Accessible name announced for each editable segment, keyed by its part type.
+ * Override individually (or wholesale) for localization; any key left unset
+ * falls back to the library default for that part — so overriding just
+ * `dayPeriod` keeps the English labels for the rest.
+ */
+type ForDateFieldSegmentLabels = Partial<Record<SegmentType, string>>;
+/**
+ * Defaults inherited by descendant `[forDateField]` controls in the
+ * surrounding injector scope. Configure with `provideForDateFieldDefaults` at
+ * the application root or in any component's `providers`; partial overrides
+ * merge with the parent scope.
+ */
+interface ForDateFieldDefaults {
+    /**
+     * Accessible value announced (via `aria-valuetext`) for an empty editable
+     * segment, so screen readers report the segment's empty state instead of
+     * silence. Override for localization.
+     */
+    emptySegmentText: string;
+    /**
+     * Accessible names announced for each editable segment (via `aria-label`),
+     * keyed by part type, used when a segment has no explicit `ariaLabel`. The
+     * AM/PM `dayPeriod` defaults to `'AM/PM'` instead of leaking the raw token.
+     * Override for localization; unset keys keep the library default.
+     */
+    segmentLabels: ForDateFieldSegmentLabels;
+}
+/**
+ * Library default accessible name for each editable segment. Used when neither
+ * the segment's explicit `ariaLabel` nor a `provideForDateFieldDefaults`
+ * override supplies one for that part.
+ */
+declare const DEFAULT_DATE_FIELD_SEGMENT_LABELS: Readonly<Record<SegmentType, string>>;
+/** Token holding the resolved date-field defaults for the current scope. */
+declare const FOR_DATE_FIELD_DEFAULTS: _angular_core.InjectionToken<ForDateFieldDefaults>;
+/**
+ * Configures forty-cdk date-field defaults for this injector scope. Partial
+ * overrides inherit unspecified keys from the parent scope (or library
+ * defaults at the root).
+ */
+declare function provideForDateFieldDefaults(defaults?: Partial<ForDateFieldDefaults>): Provider[];
+
+/**
+ * Exact public names of every `ForDateField` input, its models included. Spread it into the
+ * `inputs` array of a `hostDirectives` entry so a wrapper component re-exposes the
+ * primitive's full surface — the Signal Forms members `[formField]` binds among them —
+ * without hand-maintaining the list. Always spread into an inline object literal as shown
+ * below: the literal is what keeps the entry statically analyzable for consumers compiling
+ * against the published package. An anti-drift spec fails when this list no longer matches
+ * the directive's actual API. See `docs/wrapping-form-primitives.md` for both supported
+ * wrapping patterns.
+ *
+ * @example
+ * ```ts
+ * @Component({
+ *   selector: 'div[myDateField]',
+ *   template: '',
+ *   hostDirectives: [
+ *     {
+ *       directive: ForDateField,
+ *       inputs: [...FOR_DATE_FIELD_HOST_DIRECTIVE_INPUTS],
+ *       outputs: [...FOR_DATE_FIELD_HOST_DIRECTIVE_OUTPUTS],
+ *     },
+ *   ],
+ * })
+ * export class MyDateField {}
+ * ```
+ */
+declare const FOR_DATE_FIELD_HOST_DIRECTIVE_INPUTS: readonly ["value", "ariaLabel", "dir", "dirty", "disabled", "errors", "granularity", "hourCycle", "invalid", "locale", "maxDate", "minDate", "name", "pending", "placeholder", "readonly", "required", "touched"];
+/**
+ * Exact public names of every `ForDateField` output, the Signal Forms `touch` output
+ * included. Spread it into the `outputs` array of the same `hostDirectives` entry as
+ * {@link FOR_DATE_FIELD_HOST_DIRECTIVE_INPUTS}.
+ */
+declare const FOR_DATE_FIELD_HOST_DIRECTIVE_OUTPUTS: readonly ["valueChange", "touchedChange", "touch"];
+
+export { DEFAULT_DATE_FIELD_SEGMENT_LABELS, FOR_DATE_FIELD_CONTEXT, FOR_DATE_FIELD_DEFAULTS, FOR_DATE_FIELD_HOST_DIRECTIVE_INPUTS, FOR_DATE_FIELD_HOST_DIRECTIVE_OUTPUTS, ForDateField, ForDateFieldLiteral, ForDateFieldSegment, provideForDateFieldDefaults };
+export type { DateFieldSegment, FieldGranularity, ForDateFieldContext, ForDateFieldDefaults, ForDateFieldSegmentHandle, ForDateFieldSegmentLabels };