@cdevhub/ngx-tw 0.2.0

package/types/cdevhub-ngx-tw-calendar.d.ts

@@ -0,0 +1,1704 @@
+import * as i0 from '@angular/core';
+import { Provider, InjectionToken, Type, OnInit, ModelSignal, InputSignal, TemplateRef, OutputEmitterRef, Signal, WritableSignal, EnvironmentProviders } from '@angular/core';
+import { ControlValueAccessor, Validator, AbstractControl, ValidationErrors, ValidatorFn } from '@angular/forms';
+import { RangeBehaviorConfig } from '@cdevhub/ngx-tw/core';
+import { FormValueControl, ValidationError, WithOptionalFieldTree, DisabledReason } from '@angular/forms/signals';
+
+/**
+ * Context payload passed to `cellAccessibleName` so consumers can produce a
+ * locale-appropriate accessible name for any cell in any view (§15.6, §19.4).
+ */
+interface CalendarCellAccessibleNameContext {
+    /** The date the cell represents. */
+    readonly date: Date;
+    /** Which view the cell lives in. */
+    readonly mode: 'day' | 'month' | 'year';
+    /** True when the cell is part of the committed selection. */
+    readonly selected?: boolean;
+    /** True when the cell is today. */
+    readonly today?: boolean;
+    /** True when the cell is non-interactive (constraint or filter). */
+    readonly disabled?: boolean;
+    /** Optional pre-formatted display string the consumer may incorporate. */
+    readonly display?: string;
+}
+/**
+ * Localized strings + ARIA announcements consumed by the calendar (§19.4).
+ *
+ * Override per-field via Angular DI — provide a custom instance, or pass a
+ * `Partial<CalendarIntl>` into the calendar component's `intl` input. Unset
+ * fields fall through to the English defaults shipped here.
+ *
+ * All members take primitives so consumers can write straight string
+ * literals or template helpers without depending on internal types.
+ */
+declare class CalendarIntl {
+    /**
+     * Plural rules used for the four plural-marked keys in §19.4: range length,
+     * "X dates selected", "Skipped {N} periods", and the year-range button label.
+     * Resolved lazily so SSR / non-`Intl` environments don't crash at construction.
+     */
+    private _plural;
+    private getPlural;
+    /** Aria label for the "previous month" navigation button (day view). */
+    previousMonthLabel: string;
+    /** Aria label for the "next month" navigation button (day view). */
+    nextMonthLabel: string;
+    /** Aria label for the "previous year" navigation button (month view). */
+    previousYearLabel: string;
+    /** Aria label for the "next year" navigation button (month view). */
+    nextYearLabel: string;
+    /** Aria label for the "previous N years" navigation button (year view). */
+    previousYearsLabel(yearsPerPage: number): string;
+    /** Aria label for the "next N years" navigation button (year view). */
+    nextYearsLabel(yearsPerPage: number): string;
+    /** Aria label for the "today" shortcut button (footer). */
+    todayLabel: string;
+    /** Aria label for the "clear" button (footer). */
+    clearLabel: string;
+    /** Aria label for the "apply" button (footer). */
+    applyLabel: string;
+    /** Aria label for the trigger/open-calendar button. */
+    openCalendarLabel: string;
+    /** Aria label for the "choose date" trigger. */
+    chooseDateLabel: string;
+    /** Aria label applied to the calendar root element. */
+    calendarLabel: string;
+    /** Aria label appended to the period button while in the day view. */
+    monthViewLabel: string;
+    /** Aria label appended to the period button while in the month view. */
+    yearViewLabel: string;
+    /** Aria label for the year (decade) view. */
+    decadeViewLabel: string;
+    /** Tooltip / aria text for the "switch to month view" affordance. */
+    switchToMonthViewLabel(period: string): string;
+    /** Tooltip / aria text for the "switch to year view" affordance. */
+    switchToYearViewLabel(period: string): string;
+    /**
+     * Returns the accessible name a screen reader announces for any cell.
+     * Default implementation appends "today" / "selected" / "disabled" suffixes
+     * to the supplied `display` string.
+     */
+    cellAccessibleName(ctx: CalendarCellAccessibleNameContext): string;
+    /** Live-region message after navigating the displayed period. */
+    navigatedTo(direction: 'previous' | 'next', period: string): string;
+    /** Live-region message after a single-mode selection commits. */
+    selectedAnnouncement(value: string): string;
+    /** Live-region message after the start of a range is picked. */
+    rangeStartAnnouncement(start: string): string;
+    /** Live-region message after a range commits. Plural-marked on `lengthDays`. */
+    rangeUpdateAnnouncement(start: string, end: string, lengthDays: number): string;
+    /** Live-region message after a `mode: 'multiple'` selection commits. Plural-marked. */
+    multipleSelectionAnnouncement(count: number): string;
+    /** Live-region message after the active view changes. */
+    viewSwitched(view: 'day' | 'month' | 'year', period: string): string;
+    /** Live-region template used while a range pick is in progress. */
+    inProgressTemplate(state: string): string;
+    /** Live-region message announcing how many empty periods auto-skip jumped over. Plural-marked. */
+    skippedPeriods(count: number, destination: string): string;
+    /** Live-region message announced when a click is rejected and the cell flashes (e.g. `'require-clear'` rejection, disabled-cross range commit). */
+    selectionRejectedAnnouncement: string;
+    /**
+     * When `true`, the calendar suppresses live-region announcements for the
+     * affected user actions. Override in tests or low-noise environments.
+     */
+    skipAnnouncement: boolean;
+    /** Message for the `calendarRequired` validation error. */
+    requiredError: string;
+    /** Message for the `calendarMinDate` validation error. */
+    minDateError(date: string): string;
+    /** Message for the `calendarMaxDate` validation error. */
+    maxDateError(date: string): string;
+    /** Message for the `calendarInvalidValue` validation error. */
+    invalidValueError: string;
+    /** Message for the `calendarRangeTooShort` validation error. Plural-marked on `min`. */
+    rangeTooShortError(min: number): string;
+    /** Message for the `calendarRangeTooLong` validation error. Plural-marked on `max`. */
+    rangeTooLongError(max: number): string;
+    /** Message for the `calendarInvalidRange` validation error. */
+    invalidRangeError: string;
+    /** Message for the `calendarDisabledDate` validation error. */
+    dateFilterError: string;
+    /** Message for the `calendarMaxSelections` validation error. */
+    maxSelectionsError(limit: number): string;
+    /** Label announced when a typed date fails to parse. */
+    parseErrorLabel: string;
+    /** Multi-line description of the keyboard contract for screen readers / help dialogs. */
+    keyboardHelpText: string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CalendarIntl, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<CalendarIntl>;
+}
+/**
+ * Provides a custom `CalendarIntl` instance. Place at any injector level —
+ * the calendar resolves the closest one and merges any per-instance `intl`
+ * input on top of it (§19.4 per-field merge semantics).
+ */
+declare function provideCalendarIntl(custom: Partial<CalendarIntl>): Provider;
+
+/**
+ * Calendar shared types. Aligned with `docs/requirements/calendar-component-requirements.md` v2.6
+ * (§7.1, §7.4, §8, §10.2, §22.5, §33).
+ */
+/** Selection mode exposed via the `mode` input. `'week'` is `[WONT] v1` — week-as-unit selection remains available via the DI-only `WeekSelectionStrategy`. */
+type CalendarMode = 'single' | 'multiple' | 'range';
+/** Value shape for `mode: 'single'`. */
+type CalendarSingleValue<D> = D | null;
+/** Value shape for `mode: 'multiple'`. */
+type CalendarMultipleValue<D> = D[];
+/** Value shape for `mode: 'range'`. Endpoints are independent — either can be `null`. */
+interface CalendarRangeValue<D> {
+    readonly start: D | null;
+    readonly end: D | null;
+}
+/** Mode-parameterized value. `mode: 'single' → D | null`, `'multiple' → D[]`, `'range' → { start; end }`. */
+type CalendarValue<M extends CalendarMode, D> = M extends 'single' ? CalendarSingleValue<D> : M extends 'multiple' ? CalendarMultipleValue<D> : M extends 'range' ? CalendarRangeValue<D> : never;
+/** Mode-agnostic empty value — `null` for single, `[]` for multiple, `{ start: null, end: null }` for range. */
+declare function emptyCalendarValue<M extends CalendarMode, D>(mode: M): CalendarValue<M, D>;
+/** Selection lifecycle. */
+type CalendarSelectionState = 'EMPTY' | 'SELECTING' | 'COMPLETE';
+/** Which grid the user is looking at. `'day'` = 7×6 day grid, `'month'` = 4×3 months in a year, `'year'` = a page of years. */
+type CalendarViewState = 'day' | 'month' | 'year';
+/** Overlay presentation lifecycle (Phase 10 wires the transitions). In inline mode this signal resolves to `null`. */
+type CalendarOverlayState = 'closed' | 'opening' | 'open' | 'closing';
+/** How `mode: 'range'` handles the third click after a complete range. */
+type RangeClickBehavior = 'restart' | 'nearest-edge' | 'require-clear';
+/** Granularity at which `mode: 'range'` commits (day-of-month, month-of-year, year). */
+type RangeGranularity = 'day' | 'month' | 'year';
+/** What happens when the user tries to select past `maxSelections` in `mode: 'multiple'`. */
+type MaxSelectionBehavior = 'emit-limit-reached' | 'replace-oldest' | 'ignore';
+/** How a form reset restores the calendar's internal state. `'full'` also resets view / active-date; `'value-only'` leaves navigation in place. */
+type ResetBehavior = 'full' | 'value-only';
+/** Presentation on small viewports. `'auto'` = native overlay on ≥ 600 px, fullscreen otherwise. */
+type MobileMode = 'overlay' | 'fullscreen' | 'bottom-sheet' | 'auto';
+/** Union of validation error keys emitted by the built-in validator. Stable across versions. */
+type CalendarErrorCode = 'calendarRequired' | 'calendarMinDate' | 'calendarMaxDate' | 'calendarDisabledDate' | 'calendarRangeTooShort' | 'calendarRangeTooLong' | 'calendarMaxSelections' | 'calendarInvalidRange' | 'calendarParseError' | 'calendarInvalidValue';
+/** Shape returned by the built-in validator. Each code carries the context payload described in §10.2. */
+type CalendarValidationErrors = Partial<{
+    calendarRequired: true;
+    calendarMinDate: {
+        min: unknown;
+        actual: unknown;
+    };
+    calendarMaxDate: {
+        max: unknown;
+        actual: unknown;
+    };
+    calendarDisabledDate: {
+        actual: unknown;
+    };
+    calendarRangeTooShort: {
+        length: number;
+        min: number;
+    };
+    calendarRangeTooLong: {
+        length: number;
+        max: number;
+    };
+    calendarMaxSelections: {
+        limit: number;
+        actual: number;
+    };
+    calendarInvalidRange: {
+        start: unknown;
+        end: unknown;
+    };
+    calendarParseError: {
+        raw: string;
+    };
+    calendarInvalidValue: {
+        expected: 'single' | 'multiple' | 'range';
+        actual: unknown;
+        reason: 'shape' | 'transformer';
+    };
+}>;
+/** Payload of `selectionComplete`. `reason` flags the commit path. */
+interface SelectionCompleteEvent<M extends CalendarMode, D> {
+    readonly value: CalendarValue<M, D>;
+    readonly reason: 'commit' | 'auto-swap' | 'nearest-edge' | 'preset';
+}
+/** Payload of `selectionCleared`. `reason` disambiguates user action from programmatic / mode-change / reset / disabled. */
+interface SelectionClearedEvent {
+    readonly reason: 'user' | 'programmatic' | 'mode-change' | 'reset' | 'disabled';
+}
+/** Payload of `rangePreview`. `invalidPreview` is set when the hover crosses a disabled date and `disableRangesCrossingDisabledDates` is true, or the range length violates `min`/`maxRangeLength` (Phase 4 / 6 set this). */
+interface RangePreviewEvent<D> {
+    readonly tentativeRange: {
+        readonly start: D;
+        readonly end: D;
+    };
+    readonly invalidPreview: boolean;
+}
+/** Payload of `viewChange`. Distinguishes drill-down (day→month→year) from drill-up and from programmatic changes. */
+interface ViewChangeEvent {
+    readonly from: CalendarViewState;
+    readonly to: CalendarViewState;
+    readonly reason: 'user' | 'programmatic' | 'drill-down' | 'drill-up';
+}
+/** Payload of `modeChange`. */
+interface ModeChangeEvent {
+    readonly from: CalendarMode;
+    readonly to: CalendarMode;
+}
+/**
+ * A date range with optional endpoints.
+ * Kept as a structural type for backward-compat with the existing view implementation;
+ * `CalendarRangeValue<D>` is the spec-canonical alias.
+ */
+interface DateRange<D> {
+    readonly start: D | null;
+    readonly end: D | null;
+}
+/** Factory for a plain `DateRange<D>`. */
+declare function createDateRange<D>(start: D | null, end: D | null): DateRange<D>;
+/**
+ * Visual state of a single cell in any view.
+ * Phase 4 replaces this with the `data-state-*` attribute surface (§34.5).
+ */
+type CalendarCellState = 'default' | 'today' | 'selected' | 'range-start' | 'range-middle' | 'range-end' | 'disabled' | 'preview-start' | 'preview-middle' | 'preview-end';
+/**
+ * Data describing one renderable cell.
+ * Phase 13 replaces this with `DayCellContext<D, T>` (§24.1) — kept in place through
+ * Phases 1–12 so the existing month/year/years views compile without a wholesale view rewrite.
+ */
+interface CalendarCell<D> {
+    /** The date value this cell represents. */
+    value: D;
+    /** Display text inside the cell (day number, short month name, year). */
+    displayValue: string;
+    /** Accessible label announced to screen readers. */
+    ariaLabel: string;
+    /** Whether the cell is interactive. Disabled cells still render. */
+    enabled: boolean;
+    /** Consumer-provided CSS classes (via `dateClass`). */
+    cssClasses: string;
+    /** True when this cell is today's date. */
+    isToday: boolean;
+    /** True when this cell is the committed selection (or part of a range). */
+    isSelected: boolean;
+    /** True when this cell starts a committed range. */
+    isRangeStart: boolean;
+    /** True when this cell is strictly inside a committed range. */
+    isRangeMiddle: boolean;
+    /** True when this cell ends a committed range. */
+    isRangeEnd: boolean;
+    /** True when this cell starts the hover-preview range. */
+    isPreviewStart: boolean;
+    /** True when this cell is inside the hover-preview range. */
+    isPreviewMiddle: boolean;
+    /** True when this cell ends the hover-preview range. */
+    isPreviewEnd: boolean;
+    /** True when this cell falls outside the currently displayed month (day view only). */
+    isOutOfMonth: boolean;
+    /** True when this cell is a weekend day (Sat/Sun by default; locale-aware override planned). */
+    isWeekend: boolean;
+    /** True when this cell is part of a tentative range that violates a constraint (e.g., crosses a disabled date or exceeds `maxRangeLength`). */
+    isInvalidPreview: boolean;
+    /** True when the cell briefly flashes to indicate a rejected click (e.g., disabled commit, `rangeClickBehavior: 'require-clear'`). Auto-cleared by the orchestrator. */
+    isInvalidFlash: boolean;
+    /** Numeric comparison key used for focus tracking. */
+    compareValue: number;
+}
+/** Configuration accepted by `createCalendarCell`. */
+interface CalendarCellConfig<D> {
+    value: D;
+    displayValue: string;
+    ariaLabel: string;
+    enabled?: boolean;
+    cssClasses?: string;
+    compareValue: number;
+}
+/** Factory for a `CalendarCell` with boolean state fields zeroed out. */
+declare function createCalendarCell<D>(config: CalendarCellConfig<D>): CalendarCell<D>;
+/** Style for month and weekday names. */
+type NameStyle = 'long' | 'short' | 'narrow';
+/** Days in a week. */
+declare const DAYS_PER_WEEK = 7;
+/** Rows in a month grid. */
+declare const WEEKS_PER_MONTH = 6;
+/** Default years shown per page in the year view. Phase 7 replaces this constant with the `yearsPerPage` input (default 20 per §33.1). */
+declare const YEARS_PER_PAGE = 24;
+/** Years per row in the year view. */
+declare const YEARS_PER_ROW = 4;
+/** Months per row in the month (of year) view. */
+declare const MONTHS_PER_ROW = 4;
+/** Predicate for per-date disabling — return `false` to disable. */
+type DateFilterFn<D> = (date: D) => boolean;
+/**
+ * Source for `disabledDates` (§10.1) — accepts either an explicit array of disabled dates
+ * (compared via `adapter.sameDate`) or a predicate returning `true` for disabled dates.
+ *
+ * Note: this is the inverse of `dateFilter` (which returns `true` for ENABLED dates).
+ * Both inputs are honored — a date is disabled if either source flags it.
+ */
+type DisabledDates<D> = readonly D[] | ((date: D) => boolean);
+/**
+ * Aggregated constraint inputs (§10.1). Doubles as the shorthand object accepted by
+ * `CalendarComponent`'s `constraints` input — every field is optional so consumers can
+ * supply only what they need (e.g. `{ minDate, maxDate }` or `{ dateFilter }`). The
+ * orchestrator's resolver normalizes missing fields to neutral values (`null` /
+ * empty array) before evaluating cell state.
+ *
+ * Resolution rule on the `constraints` input: the individual `minDate` / `maxDate` /
+ * `disabledDates` / `disabledDaysOfWeek` / `dateFilter` inputs win when both are set
+ * non-null. This lets a consumer pass `[constraints]="defaults"` for a base set and
+ * still override one field via the dedicated input.
+ */
+interface CalendarConstraints<D> {
+    readonly minDate?: D | null;
+    readonly maxDate?: D | null;
+    readonly disabledDates?: DisabledDates<D> | null;
+    readonly disabledDaysOfWeek?: readonly number[] | null;
+    readonly dateFilter?: DateFilterFn<D> | null;
+}
+/** Function producing extra per-cell CSS classes. */
+type DateClassFn<D> = (date: D, view: CalendarViewState) => string;
+
+/** Outcome returned by a selection strategy's `select` call. */
+interface SelectionResult<D, S> {
+    /** The new selection value after applying the click. */
+    readonly selection: S;
+    /** Whether the selection is committed. */
+    readonly isComplete: boolean;
+    /** Optional range used by the preview layer while the selection is in progress. */
+    readonly preview?: DateRange<D> | null;
+}
+/**
+ * Pluggable selection behaviour. Provide via `CALENDAR_SELECTION_STRATEGY` to
+ * customise how clicks mutate the calendar's `selected` value.
+ *
+ * `D` is the date type understood by the active `DateAdapter`.
+ * `S` is the shape of the `selected` value — `D | null` for single,
+ * `DateRange<D> | null` for range / week, `readonly D[]` for multi.
+ */
+declare abstract class CalendarSelectionStrategy<D, S = unknown> {
+    /** Produces the new selection after a click on `date`. */
+    abstract select(date: D, current: S): SelectionResult<D, S>;
+    /** Returns the range to highlight while the pointer hovers `active`. */
+    abstract createPreview(active: D | null, current: S): DateRange<D> | null;
+    /** Whether `date` should render as selected. */
+    abstract isSelected(date: D, current: S): boolean;
+    /** Whether `date` is the start of a committed range. */
+    abstract isRangeStart(date: D, current: S): boolean;
+    /** Whether `date` is the end of a committed range. */
+    abstract isRangeEnd(date: D, current: S): boolean;
+    /** Whether `date` sits strictly between the endpoints of a committed range. */
+    abstract isRangeMiddle(date: D, current: S): boolean;
+}
+/** Injection token for the active selection strategy. */
+declare const CALENDAR_SELECTION_STRATEGY: InjectionToken<CalendarSelectionStrategy<unknown, unknown>>;
+
+/**
+ * Single-date selection. Every click commits a new selection immediately.
+ * No preview range. `selected` has shape `D | null`.
+ */
+declare class SingleSelectionStrategy<D> extends CalendarSelectionStrategy<D, D | null> {
+    private readonly dateAdapter;
+    select(date: D, _current: D | null): SelectionResult<D, D | null>;
+    createPreview(_active: D | null, _current: D | null): DateRange<D> | null;
+    isSelected(date: D, current: D | null): boolean;
+    isRangeStart(_date: D, _current: D | null): boolean;
+    isRangeEnd(_date: D, _current: D | null): boolean;
+    isRangeMiddle(_date: D, _current: D | null): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SingleSelectionStrategy<any>, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SingleSelectionStrategy<any>>;
+}
+
+/**
+ * Date-range selection.
+ *
+ * - First click sets the start (selection incomplete).
+ * - Second click sets the end (selection complete).
+ * - If the second date is before the first, endpoints are swapped.
+ * - Hovering after the first click produces a preview range.
+ *
+ * `selected` has shape `DateRange<D> | null`.
+ */
+declare class RangeSelectionStrategy<D> extends CalendarSelectionStrategy<D, DateRange<D> | null> {
+    private readonly dateAdapter;
+    select(date: D, current: DateRange<D> | null): SelectionResult<D, DateRange<D> | null>;
+    createPreview(active: D | null, current: DateRange<D> | null): DateRange<D> | null;
+    isSelected(date: D, current: DateRange<D> | null): boolean;
+    isRangeStart(date: D, current: DateRange<D> | null): boolean;
+    isRangeEnd(date: D, current: DateRange<D> | null): boolean;
+    isRangeMiddle(date: D, current: DateRange<D> | null): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RangeSelectionStrategy<any>, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<RangeSelectionStrategy<any>>;
+}
+
+/**
+ * Multi-date selection.
+ *
+ * - Each click toggles the date in/out of the selection array.
+ * - Each click commits immediately (no intermediate preview).
+ * - `selected` has shape `D[]`.
+ */
+declare class MultiSelectionStrategy<D> extends CalendarSelectionStrategy<D, D[]> {
+    private readonly dateAdapter;
+    select(date: D, current: D[]): SelectionResult<D, D[]>;
+    createPreview(_active: D | null, _current: D[]): DateRange<D> | null;
+    isSelected(date: D, current: D[]): boolean;
+    isRangeStart(_date: D, _current: D[]): boolean;
+    isRangeEnd(_date: D, _current: D[]): boolean;
+    isRangeMiddle(_date: D, _current: D[]): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MultiSelectionStrategy<any>, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<MultiSelectionStrategy<any>>;
+}
+
+/**
+ * Week selection.
+ *
+ * - Any click selects the entire week containing that day.
+ * - Week bounds use `DateAdapter.getFirstDayOfWeek()`.
+ * - Each click commits immediately.
+ * - Hovering previews the week the cursor is in.
+ *
+ * `selected` has shape `DateRange<D> | null`.
+ */
+declare class WeekSelectionStrategy<D> extends CalendarSelectionStrategy<D, DateRange<D> | null> {
+    private readonly dateAdapter;
+    select(date: D, _current: DateRange<D> | null): SelectionResult<D, DateRange<D> | null>;
+    createPreview(active: D | null, _current: DateRange<D> | null): DateRange<D> | null;
+    isSelected(date: D, current: DateRange<D> | null): boolean;
+    isRangeStart(date: D, current: DateRange<D> | null): boolean;
+    isRangeEnd(date: D, current: DateRange<D> | null): boolean;
+    isRangeMiddle(date: D, current: DateRange<D> | null): boolean;
+    private weekRange;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WeekSelectionStrategy<any>, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WeekSelectionStrategy<any>>;
+}
+
+/** Provides single-date selection (default behaviour). */
+declare function provideSingleSelectionStrategy(): Provider;
+/** Provides two-click date-range selection. */
+declare function provideRangeSelectionStrategy(): Provider;
+/** Provides toggle-based multi-date selection. */
+declare function provideMultiSelectionStrategy(): Provider;
+/** Provides week-at-a-time selection. */
+declare function provideWeekSelectionStrategy(): Provider;
+/** Provides an arbitrary custom selection strategy. */
+declare function provideCalendarSelectionStrategy<D, S>(strategy: Type<CalendarSelectionStrategy<D, S>>): Provider;
+
+/**
+ * Main calendar orchestrator. Composes the header and view components
+ * (day, month, year) with view switching, navigation, focus management,
+ * and the §8 internal state model. Every date operation is delegated to
+ * an injected `DateAdapter` — call `provideNativeDateAdapter()` in your
+ * app to bootstrap the default one.
+ *
+ * Generic parameters (§7.3):
+ * - `M` — selection mode. Narrows `value` to the mode-specific shape.
+ * - `D` — adapter date type.
+ * - `TOut` — post-transformer form value type (Phase 14 wires it; until then
+ *   it defaults to `CalendarValue<M, D>` so forms see raw adapter values).
+ */
+declare class CalendarComponent<M extends CalendarMode = 'single', D = Date, TOut = CalendarValue<M, D>> implements ControlValueAccessor, Validator, OnInit {
+    private readonly dateAdapter;
+    private readonly elementRef;
+    private readonly injector;
+    private readonly destroyRef;
+    private readonly liveAnnouncer;
+    /**
+     * Resolved lazily in `ngOnInit` — eager construction-time injection creates a
+     * circular dependency (NG0200): the component registers itself as both
+     * `NG_VALUE_ACCESSOR` and `NG_VALIDATORS`, and `FormControlName` resolves
+     * those eagerly while constructing on the same element. Looking up
+     * `NgControl` after construction breaks the cycle.
+     */
+    private ngControl;
+    /** Angular's `LOCALE_ID` — used as the fallback when no `locale` input is supplied (§19.1). */
+    private readonly platformLocale;
+    /**
+     * DI-provided default `CalendarIntl`. New'd up locally when the consumer hasn't
+     * supplied one — DI defaults are merged with the per-instance `intl` input
+     * via `effectiveIntl()` (§19.4 per-field merge).
+     */
+    private readonly injectedIntl;
+    private readonly injectedStrategy;
+    private readonly monthViews;
+    /**
+     * Built-in strategies instantiated lazily in the host's injection context so
+     * `inject(DATE_ADAPTER)` calls inside each strategy resolve. Range state will
+     * migrate into the orchestrator in Phase 6; single / multiple stay here as
+     * internals (not exported) via the spec's mode union.
+     */
+    private readonly localStrategies;
+    /** Selection mode (§5). Changing this at runtime clears the value and emits `modeChange`. */
+    readonly mode: ModelSignal<CalendarMode>;
+    /**
+     * Consumer-bound value. Shape narrows by `M`: `D | null` for single,
+     * `D[]` for multiple, `{ start; end }` for range.
+     */
+    readonly value: ModelSignal<CalendarValue<M, D>>;
+    /** Anchor date for the displayed view. Defaults to today on mount. */
+    readonly startAt: InputSignal<D | null>;
+    /** Minimum selectable date. */
+    readonly minDate: InputSignal<D | null>;
+    /** Maximum selectable date. */
+    readonly maxDate: InputSignal<D | null>;
+    /** Per-date predicate — return `false` to disable. */
+    readonly dateFilter: InputSignal<DateFilterFn<D> | null>;
+    /**
+     * Explicitly disabled dates (§10.1). Either an array (each entry compared via
+     * `adapter.sameDate`) or a predicate returning `true` for disabled dates.
+     * OR-combined with `dateFilter`, `disabledDaysOfWeek`, and `[minDate, maxDate]`.
+     */
+    readonly disabledDates: InputSignal<DisabledDates<D> | null>;
+    /** Days of the week to disable (0=Sun … 6=Sat). Empty array = no day-of-week disabling. */
+    readonly disabledDaysOfWeek: InputSignal<readonly number[]>;
+    /**
+     * Bundle of date constraints (§10.1). Lets a consumer pass `minDate`, `maxDate`,
+     * `disabledDates`, `disabledDaysOfWeek`, and `dateFilter` as a single object —
+     * useful for sharing a constraint preset across multiple calendars. Each field is
+     * optional. Individual inputs (`minDate`, `maxDate`, `disabledDates`,
+     * `disabledDaysOfWeek`, `dateFilter`) take precedence over fields here when both
+     * are set non-null.
+     */
+    readonly constraints: InputSignal<CalendarConstraints<D> | null>;
+    /** Minimum range length in days, inclusive (`mode: 'range'` only). `null` = no minimum. */
+    readonly minRangeLength: InputSignal<number | null>;
+    /** Maximum range length in days, inclusive (`mode: 'range'` only). `null` = no maximum. */
+    readonly maxRangeLength: InputSignal<number | null>;
+    /** Maximum number of selections in `mode: 'multiple'`. `null` = unlimited. */
+    readonly maxSelections: InputSignal<number | null>;
+    /**
+     * What happens when the user tries to select past `maxSelections` (§10.1).
+     * `'emit-limit-reached'` (default) emits `selectionLimitReached` and ignores
+     * the click; `'replace-oldest'` drops the first entry; `'ignore'` is silent.
+     */
+    readonly maxSelectionBehavior: InputSignal<MaxSelectionBehavior>;
+    /**
+     * IDREF list for the form-error live region (§28.3). When set, the calendar
+     * root carries `aria-describedby="<value>"` so screen readers read consumer-
+     * rendered error messages alongside the focused cell announcement.
+     */
+    readonly errorAriaDescribedBy: InputSignal<string | null>;
+    /**
+     * How `mode: 'range'` reacts to a click after a complete range (§21.2):
+     * - `'restart'` (default): start a new range with the clicked cell, emit `selectionRestart`.
+     * - `'nearest-edge'`: move the closer endpoint (start vs end) to the clicked date and re-commit (§21.3); emits `selectionComplete({reason: 'nearest-edge'})`.
+     * - `'require-clear'`: ignore the click + flash the cell as invalid (`data-state-invalid-flash`); user must call `clear()` first.
+     */
+    readonly rangeClickBehavior: InputSignal<RangeClickBehavior>;
+    /**
+     * Range-mode behavior knobs. Accepts a partial object — unset fields use the
+     * defaults documented on each property of `RangeBehaviorConfig`. Defaults:
+     * `{ allowSingleDayRange: true, persistPartialRange: true, allowBackwardRange: false, disableRangesCrossingDisabledDates: false }`.
+     */
+    readonly rangeBehavior: InputSignal<Partial<RangeBehaviorConfig>>;
+    /** Function producing per-cell CSS classes. */
+    readonly dateClass: InputSignal<DateClassFn<D> | null>;
+    /** When `true`, the calendar renders with a border and a soft shadow. */
+    readonly bordered: InputSignal<boolean>;
+    /** Which view opens first. Defaults to `'day'`. Phase 8 will derive the default from `rangeGranularity`. */
+    readonly startView: InputSignal<CalendarViewState>;
+    /** Override first day of week (0=Sun, 1=Mon). Falls back to the adapter's default. */
+    readonly firstDayOfWeek: InputSignal<number | null>;
+    /**
+     * Number of months to display side-by-side (1 or 2). Phase 9 replaces this with a
+     * full `numberOfMonths: 1..12+` surface (§23).
+     */
+    readonly monthColumns: InputSignal<number>;
+    /** Disabled state. Merged with any `setDisabledState` call from a bound form control via `effectiveDisabled`. */
+    readonly disabled: InputSignal<boolean>;
+    /** Read-only state (§33.1). When `true`, focus and keyboard navigation still work but selections cannot be committed. */
+    readonly readonly: InputSignal<boolean>;
+    /** How a form reset restores internal state (§6.5). `'full'` (default) also restores view + active-date; `'value-only'` clears the draft but leaves navigation where the user left it. */
+    readonly resetBehavior: InputSignal<ResetBehavior>;
+    /** Optional cell-content template. */
+    readonly cellTemplate: InputSignal<TemplateRef<{
+        $implicit: CalendarCell<D>;
+    }> | null>;
+    /** Per-instance locale override. Falls back to Angular `LOCALE_ID` when `null` (§19.1). */
+    readonly locale: InputSignal<string | null>;
+    /**
+     * Per-instance `CalendarIntl` override (§19.4). Per-field merge — unspecified
+     * fields inherit the DI-provided default. Pass a partial bag (e.g. one of the
+     * shipped locale packs `de`, `fr`, `es`, `pt`, `ja`) or a full custom instance.
+     */
+    readonly intl: InputSignal<Partial<CalendarIntl> | null>;
+    /** Fires whenever the committed value changes (cell click, keyboard select, preset, mode change, programmatic clear). Payload is the untransformed mode-shaped `CalendarValue<M, D>` — `D | null` for single, `D[]` for multiple, `{ start, end }` for range (§7.6). */
+    readonly valueChange: OutputEmitterRef<CalendarValue<M, D>>;
+    /** Fires on the first click of a range selection (transitions selection state to SELECTING). Payload carries the chosen `start` date. */
+    readonly selectionStart: OutputEmitterRef<{
+        start: D;
+    }>;
+    /** Fires as the hover / keyboard cursor moves during range SELECTING. Payload carries the `tentativeRange` and an `invalidPreview` flag set when the range crosses a disabled date or violates `min`/`maxRangeLength`. */
+    readonly rangePreview: OutputEmitterRef<RangePreviewEvent<D>>;
+    /** Fires after `valueChange` once the selection commits. Payload carries the committed `value` and a `reason` flagging the commit path (`'commit' | 'auto-swap' | 'nearest-edge' | 'preset'`). */
+    readonly selectionComplete: OutputEmitterRef<SelectionCompleteEvent<M, D>>;
+    /** Fires when a range selection restarts after a complete range (e.g. third click with `rangeClickBehavior='restart'`). Payload carries the new draft `start` date. */
+    readonly selectionRestart: OutputEmitterRef<{
+        start: D;
+    }>;
+    /** Fires whenever the value clears. Payload carries a `reason` distinguishing user clear, programmatic, mode change, form reset, or a disabled flip. */
+    readonly selectionCleared: OutputEmitterRef<SelectionClearedEvent>;
+    /** Fires in `mode: 'multiple'` when the user attempts to select past `maxSelections` (only with `maxSelectionBehavior: 'emit-limit-reached'`). Payload carries the configured `limit` and the rejected `attempted` date. */
+    readonly selectionLimitReached: OutputEmitterRef<{
+        limit: number;
+        attempted: D;
+    }>;
+    /** Fires when the selected preset changes (user click on a preset chip, or programmatic clear). Payload is the new preset id, or `null` when no preset is active. Phase 12 wires it. */
+    readonly presetChange: OutputEmitterRef<string | null>;
+    /** Fires on every view transition (day ↔ month ↔ year). Payload carries `from`, `to`, and a `reason` distinguishing drill-down, drill-up, user header click, and programmatic changes. */
+    readonly viewChange: OutputEmitterRef<ViewChangeEvent>;
+    /** Fires when keyboard navigation, mouse hover, or programmatic action moves the focused (active) cell. Payload is the new active date. */
+    readonly activeDateChange: OutputEmitterRef<D>;
+    /** Fires when the displayed primary month changes (page-nav, drill-up, or programmatic). Payload carries the new `year` and zero-based `month`. */
+    readonly monthChange: OutputEmitterRef<{
+        year: number;
+        month: number;
+    }>;
+    /** Fires when the displayed year changes (month/year-view nav or year-page scroll). Payload carries the new `year`. */
+    readonly yearChange: OutputEmitterRef<{
+        year: number;
+    }>;
+    /** Fires on every pointer click of any cell, including disabled ones — analytics only. Payload carries the clicked `date` and the underlying `PointerEvent`. Does NOT indicate a selection; subscribe to `valueChange` for that. */
+    readonly cellClick: OutputEmitterRef<{
+        date: D;
+        event: PointerEvent;
+    }>;
+    /** Fires on every pointer hover of any cell — analytics only. Payload carries the hovered `date`. Does NOT indicate a preview; subscribe to `rangePreview` for range-mode hover state. */
+    readonly cellHover: OutputEmitterRef<{
+        date: D;
+    }>;
+    /** Fires when `mode` changes at runtime, in canonical order `selectionCleared` → `modeChange` → `valueChange` (§11.2). Payload carries `{ from, to }` modes. */
+    readonly modeChange: OutputEmitterRef<ModeChangeEvent>;
+    /** In-flight draft during range SELECTING. `null` in other states (§8.1). */
+    private readonly internalDraftValue;
+    /** Current selection lifecycle state. */
+    private readonly _selectionState;
+    /** Current view (writable for drill). Tracks `startView` until the user drills. */
+    private readonly _viewState;
+    /**
+     * Active (focused) date. `linkedSignal` so changes to `startAt` at runtime update
+     * the anchor, but internal navigation can still write it independently.
+     */
+    private readonly _activeDate;
+    /** Pointer-hover date (desktop only). */
+    private readonly _hoveredDate;
+    /** Overlay state. Always `'closed'` in inline mode until Phase 10 wires the lifecycle. */
+    private readonly _overlayState;
+    /** Preset selection id. Phase 12 writes this. */
+    private readonly _selectedPresetId;
+    /** Raw `TOut` retained when `fromForm` throws (§7.6, Phase 14). `null` otherwise. */
+    private readonly _lastInvalidFormValue;
+    /** Overlay lifecycle. `null` until `interaction: 'overlay'` lands in Phase 10; until then the implementation signal is exposed as `'closed'`. */
+    readonly overlayState: Signal<CalendarOverlayState | null>;
+    /** Selection lifecycle per §8. */
+    readonly selectionState: Signal<CalendarSelectionState>;
+    /** Active (focused) cell. `null` when the overlay is closed and no inline focus is established; in inline mode this is always the current anchor. */
+    readonly activeDate: Signal<D | null>;
+    /** Currently selected preset id. */
+    readonly selectedPresetId: Signal<string | null>;
+    /** Current view state (day / month / year). */
+    readonly viewState: Signal<CalendarViewState>;
+    /** Months currently rendered. Phase 9 extends this to the full responsive count. */
+    readonly displayedMonths: Signal<{
+        year: number;
+        month: number;
+    }[]>;
+    /** Raw form value rejected by the transformer's `fromForm` (§7.6, §33.3). */
+    readonly lastInvalidFormValue: Signal<unknown>;
+    private cvaOnChange;
+    private cvaOnTouched;
+    private validatorOnChange;
+    /**
+     * @internal Disabled state set by `ControlValueAccessor.setDisabledState` and
+     * by the Signal Forms mode directives. OR-merged with the public `disabled`
+     * input into `effectiveDisabled`.
+     */
+    readonly cvaDisabled: WritableSignal<boolean>;
+    /**
+     * @internal Read-only state set by the Signal Forms mode directives. OR-merged
+     * with the public `readonly` input into `effectiveReadonly`.
+     */
+    readonly cvaReadonly: WritableSignal<boolean>;
+    /** Effective disabled state — public `disabled` input OR any form-bound disabled flip. Drives `aria-disabled`. */
+    readonly effectiveDisabled: Signal<boolean>;
+    /** Effective read-only state — public `readonly` input OR any form-bound readonly flip. Drives `aria-readonly`. */
+    readonly effectiveReadonly: Signal<boolean>;
+    /**
+     * @internal Resolved range-behavior config. Merges the consumer-supplied
+     * `Partial<RangeBehaviorConfig>` over the documented defaults so internal
+     * call sites read each field directly without re-applying fallbacks.
+     */
+    private readonly _resolvedRangeBehavior;
+    /** @internal Dev-mode warning guard so each mismatched write warns only once per instance. */
+    private _warnedShapeMismatch;
+    /** @internal Set by `writeValue`; read by the `FormResetEvent` handler so it can emit `selectionCleared({reason: 'reset'})` only when a non-empty value was on the control before the reset cleared it. */
+    private _hadValueBeforeLastWrite;
+    constructor();
+    ngOnInit(): void;
+    /** @internal `ControlValueAccessor` — writes a value from a reactive / template-driven form. Wrong-shape writes preserve the prior value per §7.2. Programmatic writes during SELECTING discard the draft per §11.1. */
+    writeValue(incoming: unknown): void;
+    /** @internal `ControlValueAccessor` — registers the on-change callback. */
+    registerOnChange(fn: (value: unknown) => void): void;
+    /** @internal `ControlValueAccessor` — registers the touched callback. */
+    registerOnTouched(fn: () => void): void;
+    /** @internal `ControlValueAccessor` — reflects the form control's disabled state through `effectiveDisabled` / `aria-disabled`. */
+    setDisabledState(isDisabled: boolean): void;
+    /** @internal `Validator` — runs the §10.2 validator. Phase 3 codes (`calendarRequired`, `calendarInvalidValue`) plus Phase 4 constraint codes (`calendarMinDate`, `calendarMaxDate`, `calendarDisabledDate`, `calendarRangeTooShort`, `calendarRangeTooLong`, `calendarMaxSelections`, `calendarInvalidRange`). */
+    validate(control: AbstractControl): ValidationErrors | null;
+    /** @internal `Validator` — registers the change callback so the form re-runs validation when internal state changes. */
+    registerOnValidatorChange(fn: () => void): void;
+    /** @internal Host `(focusout)` handler — fires `onTouched` when focus leaves the component (§13.6 inline path). Overlay-mode wiring is Phase 10. */
+    onBlur(event: FocusEvent): void;
+    /**
+     * Effective `CalendarIntl` resolved per-field over the DI default (§19.4).
+     * The injected default is the base; the `intl` input overrides individual
+     * fields. Unspecified fields fall through to English defaults.
+     */
+    readonly effectiveIntl: Signal<CalendarIntl>;
+    /** Effective locale — `locale` input wins, otherwise Angular `LOCALE_ID`. */
+    readonly effectiveLocale: Signal<string>;
+    /**
+     * Active strategy for single/multiple/range. Injected strategies (custom) win.
+     * Range state will migrate into this component in Phase 6; for now we reuse
+     * the strategy for its `select` / `createPreview` / `isSelected` helpers.
+     */
+    readonly selectionStrategy: Signal<CalendarSelectionStrategy<D, unknown>>;
+    /** Computed first-day-of-week (input override wins over adapter default). */
+    readonly computedFirstDayOfWeek: Signal<number>;
+    /** Resolves the configured `monthColumns` value. Range-mode consumers pass `2` explicitly. */
+    readonly effectiveMonthColumns: Signal<number>;
+    /**
+     * @internal Drives `aria-multiselectable` on every view grid. `true` when the
+     * current `mode` allows more than one cell to be selected at a time
+     * (`'multiple'` or `'range'`); `false` for `'single'`.
+     */
+    readonly multiSelectable: Signal<boolean>;
+    /** Secondary anchor for the right-hand grid in multi-column mode. */
+    readonly secondaryActiveDate: Signal<D | null>;
+    /**
+     * Phase 6 — preview cursor. Pointer hover wins; falls back to `activeDate`
+     * when SELECTING so keyboard arrow-key moves drive the same preview path
+     * (§21.1, §16.1). `null` when no SELECTING draft is in-flight and pointer
+     * is off-grid.
+     */
+    private readonly previewCursor;
+    /**
+     * Preview range. Driven by the strategy and the `previewCursor` (hover or
+     * keyboard active-date during SELECTING).
+     */
+    readonly previewRange: Signal<DateRange<D> | null>;
+    /**
+     * Adapter-compatible view of the current selection.
+     * For range: a `{ start, end }` view of either the committed value or the in-flight draft.
+     * For single: the raw `D | null`.
+     * For multiple: the raw `D[]`.
+     *
+     * Used internally to feed the legacy strategy surface while Phase 6 migrates range state.
+     */
+    private readonly strategySelection;
+    /** Adapter-compatible view exposed to the view components. */
+    readonly legacySelected: Signal<D | D[] | DateRange<D> | null>;
+    private readonly variantResult;
+    /** @internal */
+    readonly rootClasses: Signal<string>;
+    /** @internal */
+    readonly monthsClasses: Signal<string>;
+    private readonly monthNames;
+    /** @internal */
+    readonly periodLabel: Signal<string>;
+    /** @internal */
+    readonly periodAriaLabel: Signal<string>;
+    /** @internal */
+    readonly prevAriaLabel: Signal<string>;
+    /** @internal */
+    readonly nextAriaLabel: Signal<string>;
+    /** @internal */
+    readonly prevDisabled: Signal<boolean>;
+    /** @internal */
+    readonly nextDisabled: Signal<boolean>;
+    /** Focuses `date` and optionally navigates the view to render it. */
+    focusDate(date: D, opts?: {
+        navigate?: boolean;
+    }): void;
+    /** Sets the current view state and emits a `viewChange` event. */
+    setView(view: CalendarViewState): void;
+    /** Navigates to a specific date (anchor). Does not emit a selection event. */
+    goToDate(date: D): void;
+    /** Navigates to today. */
+    goToToday(): void;
+    /** Clears the current selection. Alias: `clearSelection`. */
+    clear(): void;
+    /** Alias of `clear()` exported per §33.4 for discoverability. */
+    clearSelection(): void;
+    /** Resets to initial state — value + view + active date per `resetBehavior`. Phase 3 extends this with form-reset integration. */
+    reset(): void;
+    /** Revalidates constraints + cell filters (Phase 4 wires it). */
+    revalidate(): void;
+    /** Opens the overlay. Phase 10 wires the CDK overlay; inline mode is a no-op. */
+    open(): void;
+    /** Closes the overlay. */
+    close(): void;
+    /** Toggles the overlay. */
+    toggle(): void;
+    /** Imperatively focuses the currently active cell. */
+    focusActiveCell(): void;
+    /** @internal */
+    onPrevClicked(): void;
+    /** @internal */
+    onNextClicked(): void;
+    /** @internal — period-button click: drill up (day → month → year). */
+    onPeriodClicked(): void;
+    /** @internal — day-grid cell activation. */
+    onDateSelected(date: D): void;
+    /** @internal — preview sync from pointer hover. */
+    onPreviewChange(date: D | null): void;
+    /**
+     * Phase 4 — `true` when a tentative range hover would commit an invalid value.
+     * Reasons: crosses a disabled date, or length violates `min`/`maxRangeLength`.
+     * The flag is informational — does NOT block the commit on its own (§4 default
+     * is permissive). Subscribe to `rangePreview.invalidPreview` together with the
+     * `calendarRangeTooShort` / `calendarRangeTooLong` validator codes to react.
+     */
+    private isPreviewInvalid;
+    /**
+     * Resolved `minDate` — individual `minDate` input wins, then `constraints.minDate`,
+     * else `null`. Used by every internal min-date reader so the shorthand input is
+     * transparent to the rest of the component.
+     */
+    readonly resolvedMinDate: Signal<D | null>;
+    /** Resolved `maxDate` — individual input wins, then `constraints.maxDate`, else `null`. */
+    readonly resolvedMaxDate: Signal<D | null>;
+    /** Resolved `disabledDates` — individual input wins, then `constraints.disabledDates`, else `null`. */
+    readonly resolvedDisabledDates: Signal<DisabledDates<D> | null>;
+    /** Resolved `disabledDaysOfWeek` — individual input wins (when non-empty), then `constraints.disabledDaysOfWeek`, else `[]`. */
+    readonly resolvedDisabledDaysOfWeek: Signal<readonly number[]>;
+    /** Resolved `dateFilter` — individual input wins, then `constraints.dateFilter`, else `null`. */
+    readonly resolvedDateFilter: Signal<DateFilterFn<D> | null>;
+    /** Aggregated, resolved constraint inputs — passed to the resolver and validator. */
+    private readonly resolvedConstraints;
+    /** @internal — month-view cell activation (drill-down to day). */
+    onMonthSelected(date: D): void;
+    /** @internal — years-view cell activation (drill-down to month). */
+    onYearSelected(date: D): void;
+    /** @internal — keyboard / programmatic active-date change from a view. */
+    onActiveDateChange(date: D, gridIndex?: number): void;
+    /** @internal Last invalidly-clicked date, cleared after ~200ms — drives `data-state-invalid-flash`. */
+    private readonly _invalidFlashDate;
+    /** Public read of the transient invalid-flash anchor. Views consume this and tag the matching cell. */
+    readonly invalidFlashDate: Signal<D | null>;
+    private commitRangeClick;
+    /** Enters SELECTING with `date` as draft.start. Emits selectionStart or selectionRestart. */
+    private enterSelecting;
+    /**
+     * `'nearest-edge'` move (§21.3) — drag the closer endpoint of the committed
+     * range to `date`. Emits `selectionComplete({reason: 'nearest-edge'})`.
+     */
+    private commitNearestEdge;
+    /** Pending invalid-flash clear timer; tracked so we can cancel on destroy. */
+    private _invalidFlashTimer;
+    /** Sets the invalid-flash anchor and schedules a clear after 200ms. */
+    private flashInvalid;
+    /** Commits a value into the form + outputs with spec-ordered event emission. */
+    private commitValue;
+    /**
+     * Handles a form-owned reset. Triggered when the bound `NgControl` flips
+     * `pristine` back to `true` (via `FormControl.reset()` / `FormGroup.reset()`).
+     * Per §6.5 the form owns the value write, so this path does NOT emit
+     * `valueChange` and does NOT call `onTouched`. It emits `selectionCleared`
+     * when a value was previously committed and restores UI state per
+     * `resetBehavior`.
+     */
+    private handleFormReset;
+    private onModeChanged;
+    private computeCompareValue;
+    private emitPeriodChange;
+    private announceViewChange;
+    private announceNavigation;
+    /** Announces a committed selection for AT users. Branches on mode so the message matches the §19.4 intl strings. */
+    private announceSelectionComplete;
+    /** Announces the start of a range pick for AT users. */
+    private announceRangeStart;
+    /** Announces that a click was rejected (require-clear, disable-cross commit, single-day disallowed). */
+    private announceRejection;
+    /** Locale-aware long-form date format used in announcements (e.g. "Wednesday, April 15, 2026"). */
+    private formatDate;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CalendarComponent<any, any, any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CalendarComponent<any, any, any>, "tw-calendar", never, { "mode": { "alias": "mode"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "startAt": { "alias": "startAt"; "required": false; "isSignal": true; }; "minDate": { "alias": "minDate"; "required": false; "isSignal": true; }; "maxDate": { "alias": "maxDate"; "required": false; "isSignal": true; }; "dateFilter": { "alias": "dateFilter"; "required": false; "isSignal": true; }; "disabledDates": { "alias": "disabledDates"; "required": false; "isSignal": true; }; "disabledDaysOfWeek": { "alias": "disabledDaysOfWeek"; "required": false; "isSignal": true; }; "constraints": { "alias": "constraints"; "required": false; "isSignal": true; }; "minRangeLength": { "alias": "minRangeLength"; "required": false; "isSignal": true; }; "maxRangeLength": { "alias": "maxRangeLength"; "required": false; "isSignal": true; }; "maxSelections": { "alias": "maxSelections"; "required": false; "isSignal": true; }; "maxSelectionBehavior": { "alias": "maxSelectionBehavior"; "required": false; "isSignal": true; }; "errorAriaDescribedBy": { "alias": "errorAriaDescribedBy"; "required": false; "isSignal": true; }; "rangeClickBehavior": { "alias": "rangeClickBehavior"; "required": false; "isSignal": true; }; "rangeBehavior": { "alias": "rangeBehavior"; "required": false; "isSignal": true; }; "dateClass": { "alias": "dateClass"; "required": false; "isSignal": true; }; "bordered": { "alias": "bordered"; "required": false; "isSignal": true; }; "startView": { "alias": "startView"; "required": false; "isSignal": true; }; "firstDayOfWeek": { "alias": "firstDayOfWeek"; "required": false; "isSignal": true; }; "monthColumns": { "alias": "monthColumns"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "resetBehavior": { "alias": "resetBehavior"; "required": false; "isSignal": true; }; "cellTemplate": { "alias": "cellTemplate"; "required": false; "isSignal": true; }; "locale": { "alias": "locale"; "required": false; "isSignal": true; }; "intl": { "alias": "intl"; "required": false; "isSignal": true; }; }, { "mode": "modeChange"; "value": "valueChange"; "valueChange": "valueChange"; "selectionStart": "selectionStart"; "rangePreview": "rangePreview"; "selectionComplete": "selectionComplete"; "selectionRestart": "selectionRestart"; "selectionCleared": "selectionCleared"; "selectionLimitReached": "selectionLimitReached"; "presetChange": "presetChange"; "viewChange": "viewChange"; "activeDateChange": "activeDateChange"; "monthChange": "monthChange"; "yearChange": "yearChange"; "cellClick": "cellClick"; "cellHover": "cellHover"; "modeChange": "modeChange"; }, never, ["[twCalendarPresets]"], true, never>;
+}
+
+/**
+ * Common signal-input surface declared by the three mode-specific directives
+ * per spec §6.3 / §7.3. Each directive maps the Signal Forms contract onto
+ * the hosting `CalendarComponent`, so `[field]="form.someDate"` drives the
+ * calendar without any extra wiring.
+ */
+interface CalendarFormControlCommon {
+    /** Disabled flag forwarded from the bound field. OR-merged with `disabled` on the component. */
+    readonly disabled: InputSignal<boolean>;
+    /** Read-only flag forwarded from the bound field. OR-merged with `readonly` on the component. */
+    readonly readonly: InputSignal<boolean>;
+    /** Required flag forwarded from the bound field. Surfaces `calendarRequired` when empty (§10.2). */
+    readonly required: InputSignal<boolean>;
+    /** Mirrors the bound field's `invalid` flag. Reserved for visual treatment (Phase 4 wires styling). */
+    readonly invalid: InputSignal<boolean>;
+    /** Mirrors the bound field's `hidden` flag. Consumers should guard the component with `@if` when true. */
+    readonly hidden: InputSignal<boolean>;
+    /** Field errors forwarded from Signal Forms for consumer-side styling. */
+    readonly errors: InputSignal<readonly ValidationError.WithOptionalFieldTree[]>;
+    /** Forwarded disablement reasons; surfaced for consumer-side UX (tooltips, etc.). */
+    readonly disabledReasons: InputSignal<readonly WithOptionalFieldTree<DisabledReason>[]>;
+    /** Two-way `touched` flag — the directive writes `true` on blur; the `Field` directive reads/writes it. */
+    readonly touched: ModelSignal<boolean>;
+}
+/**
+ * Signal Forms strict binding for `CalendarComponent` in `single` mode.
+ * Implements `FormValueControl<D | null>` so `[field]="form.someDate"`
+ * infers `FieldTree<D | null>` with no casts.
+ *
+ * Applies automatically when `<tw-calendar mode="single">` appears in the
+ * template. When the mode attribute is omitted, consumers bind the component
+ * directly — the CVA path handles reactive / template-driven forms.
+ */
+declare class CalendarSingleDirective<D = Date, TOut = D | null> implements FormValueControl<TOut>, CalendarFormControlCommon {
+    private readonly host;
+    /** Two-way value, forwarded to the hosting `CalendarComponent`. Signal Forms `Field` binds against this. */
+    readonly value: ModelSignal<TOut>;
+    /** Mirrors the bound field's disabled flag. */
+    readonly disabled: InputSignal<boolean>;
+    /** Mirrors the bound field's readonly flag. */
+    readonly readonly: InputSignal<boolean>;
+    /** Mirrors the bound field's required flag. */
+    readonly required: InputSignal<boolean>;
+    /** Mirrors the bound field's invalid flag. */
+    readonly invalid: InputSignal<boolean>;
+    /** Mirrors the bound field's hidden flag. */
+    readonly hidden: InputSignal<boolean>;
+    /** Mirrors the bound field's errors. */
+    readonly errors: InputSignal<readonly ValidationError.WithOptionalFieldTree[]>;
+    /** Mirrors the bound field's disablement reasons. */
+    readonly disabledReasons: InputSignal<readonly WithOptionalFieldTree<DisabledReason>[]>;
+    /** Two-way `touched` flag — drives and reflects the field's touched state. */
+    readonly touched: ModelSignal<boolean>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<CalendarSingleDirective<any, any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CalendarSingleDirective<any, any>, "tw-calendar[mode=\"single\"]", ["twCalendarSingle"], { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; "errors": { "alias": "errors"; "required": false; "isSignal": true; }; "disabledReasons": { "alias": "disabledReasons"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; }, { "touched": "touchedChange"; }, never, never, true, never>;
+}
+/**
+ * Signal Forms strict binding for `CalendarComponent` in `multiple` mode.
+ * Implements `FormValueControl<D[]>`.
+ */
+declare class CalendarMultipleDirective<D = Date, TOut = D[]> implements FormValueControl<TOut>, CalendarFormControlCommon {
+    private readonly host;
+    /** Two-way value, forwarded to the hosting `CalendarComponent`. Signal Forms `Field` binds against this. */
+    readonly value: ModelSignal<TOut>;
+    /** Mirrors the bound field's disabled flag. */
+    readonly disabled: InputSignal<boolean>;
+    /** Mirrors the bound field's readonly flag. */
+    readonly readonly: InputSignal<boolean>;
+    /** Mirrors the bound field's required flag. */
+    readonly required: InputSignal<boolean>;
+    /** Mirrors the bound field's invalid flag. */
+    readonly invalid: InputSignal<boolean>;
+    /** Mirrors the bound field's hidden flag. */
+    readonly hidden: InputSignal<boolean>;
+    /** Mirrors the bound field's errors. */
+    readonly errors: InputSignal<readonly ValidationError.WithOptionalFieldTree[]>;
+    /** Mirrors the bound field's disablement reasons. */
+    readonly disabledReasons: InputSignal<readonly WithOptionalFieldTree<DisabledReason>[]>;
+    /** Two-way `touched` flag — drives and reflects the field's touched state. */
+    readonly touched: ModelSignal<boolean>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<CalendarMultipleDirective<any, any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CalendarMultipleDirective<any, any>, "tw-calendar[mode=\"multiple\"]", ["twCalendarMultiple"], { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; "errors": { "alias": "errors"; "required": false; "isSignal": true; }; "disabledReasons": { "alias": "disabledReasons"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; }, { "touched": "touchedChange"; }, never, never, true, never>;
+}
+/**
+ * Signal Forms strict binding for `CalendarComponent` in `range` mode.
+ * Implements `FormValueControl<{ start: D | null; end: D | null }>`.
+ */
+declare class CalendarRangeDirective<D = Date, TOut = CalendarRangeValue<D>> implements FormValueControl<TOut>, CalendarFormControlCommon {
+    private readonly host;
+    /** Two-way value, forwarded to the hosting `CalendarComponent`. Signal Forms `Field` binds against this. */
+    readonly value: ModelSignal<TOut>;
+    /** Mirrors the bound field's disabled flag. */
+    readonly disabled: InputSignal<boolean>;
+    /** Mirrors the bound field's readonly flag. */
+    readonly readonly: InputSignal<boolean>;
+    /** Mirrors the bound field's required flag. */
+    readonly required: InputSignal<boolean>;
+    /** Mirrors the bound field's invalid flag. */
+    readonly invalid: InputSignal<boolean>;
+    /** Mirrors the bound field's hidden flag. */
+    readonly hidden: InputSignal<boolean>;
+    /** Mirrors the bound field's errors. */
+    readonly errors: InputSignal<readonly ValidationError.WithOptionalFieldTree[]>;
+    /** Mirrors the bound field's disablement reasons. */
+    readonly disabledReasons: InputSignal<readonly WithOptionalFieldTree<DisabledReason>[]>;
+    /** Two-way `touched` flag — drives and reflects the field's touched state. */
+    readonly touched: ModelSignal<boolean>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<CalendarRangeDirective<any, any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CalendarRangeDirective<any, any>, "tw-calendar[mode=\"range\"]", ["twCalendarRange"], { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; "errors": { "alias": "errors"; "required": false; "isSignal": true; }; "disabledReasons": { "alias": "disabledReasons"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; }, { "touched": "touchedChange"; }, never, never, true, never>;
+}
+
+/** Names of month / day-of-week labels, in three densities. */
+type TwDateNameStyle = 'long' | 'short' | 'narrow';
+/**
+ * Injection token for a per-instance timezone override (§7.4, §4.3).
+ * When set, TZ-aware adapters resolve `today()` and date-range math against
+ * the supplied IANA timezone. Floating (naive) adapters ignore the token.
+ */
+declare const TZ_OVERRIDE: InjectionToken<string>;
+/**
+ * Injection token for the default value transformer (§7.4, §7.6). Phase 14 wires
+ * the component-level `valueTransformer` input to override this DI default.
+ * Shipped as a token shell now so later phases can bind against it without a
+ * breaking change.
+ */
+declare const DATE_SERIALIZATION: InjectionToken<unknown>;
+/**
+ * Format definitions consumed by the calendar header, views, and text-input
+ * directive. Each field accepts an adapter-specific format token — the default
+ * {@link NativeDateAdapter} interprets them as `Intl.DateTimeFormatOptions`
+ * bags wrapped in a {@link NativeDateFormat}.
+ *
+ * Phases 2+ only require the `input`, `display`, `monthLabel`, and `yearLabel`
+ * members; the rest ship as slots now so later phases (5 — CalendarIntl, 9 —
+ * multi-month, 11 — text input) can populate them without an API break.
+ */
+interface DateFormats {
+    /** Format used when parsing user-typed input. */
+    readonly input?: unknown;
+    /** Format used when rendering a date into a text input's display value. */
+    readonly display?: unknown;
+    /** Format used for the header's month label (e.g., `"January 2026"`). */
+    readonly monthLabel?: unknown;
+    /** Format used for the header's year label in month view (e.g., `"2026"`). */
+    readonly yearLabel?: unknown;
+    /** Format used for the years-view header (e.g., `"2020 – 2039"`). */
+    readonly decadeLabel?: unknown;
+    /** Format used for a day-cell's accessible label. */
+    readonly a11yLabel?: unknown;
+    /** Format used for a month-cell's accessible label. */
+    readonly monthA11yLabel?: unknown;
+    /** Format used for a day-of-week column header's accessible label. */
+    readonly dayA11yLabel?: unknown;
+    /** Format used for a month name inside the year view's accessible label. */
+    readonly yearViewMonthA11yLabel?: unknown;
+}
+/** DI token carrying the default `DateFormats`. The calendar's `dateFormats` input overrides. */
+declare const DATE_FORMATS: InjectionToken<DateFormats>;
+/**
+ * Abstract date adapter. Ship a subclass to swap the underlying date library
+ * (Luxon, date-fns, Temporal). The calendar consumes only the methods defined
+ * here — nothing else.
+ *
+ * `D` is the native date type understood by the underlying library.
+ *
+ * Method contract aligned with spec §20.1 / §20.2: `addYears`/`addMonths`/
+ * `addDays`, `compare`, 1-based-month `create`, `toIso`/`fromIso`, and
+ * optional TZ virtuals.
+ */
+declare abstract class DateAdapter<D> {
+    /** Returns today at midnight, local time (or in the adapter's configured TZ). */
+    abstract today(): D;
+    /**
+     * Constructs a date.
+     *
+     * **`month` is 1-based** — pass `1` for January, `12` for December.
+     * Callers migrating from the pre-v1 `createDate(year, zeroBasedMonth, day)`
+     * must bump the month argument by one.
+     *
+     * `day` is 1-based.
+     */
+    abstract create(year: number, month: number, day: number): D;
+    /** Returns a defensive copy. */
+    abstract clone(date: D): D;
+    /** Locale for label formatting. Subclasses may honour this or ignore. */
+    abstract setLocale(locale: string): void;
+    abstract getLocale(): string;
+    /** Field getters. `month` is zero-based. */
+    abstract getYear(date: D): number;
+    abstract getMonth(date: D): number;
+    abstract getDate(date: D): number;
+    /** 0 = Sunday, 6 = Saturday. */
+    abstract getDayOfWeek(date: D): number;
+    abstract getNumDaysInMonth(date: D): number;
+    /** Time getters — hours are 0–23, minutes and seconds are 0–59. */
+    abstract getHours(date: D): number;
+    abstract getMinutes(date: D): number;
+    abstract getSeconds(date: D): number;
+    /**
+     * Returns a new date with the same year/month/day as `date` but the supplied
+     * time-of-day. Adapters must not mutate `date`. `hours` is 0–23.
+     *
+     * **Not part of the calendar's v1 spec surface** — the calendar does not
+     * consume time-of-day. Retained for the companion time-picker component.
+     */
+    abstract withTime(date: D, hours: number, minutes: number, seconds: number): D;
+    /** 0 = Sunday, 1 = Monday, etc. */
+    abstract getFirstDayOfWeek(): number;
+    /** Days per week. Override only for non-Gregorian adapters (WONT v1). */
+    getDaysInWeek(): number;
+    /** Returns month names for the current locale. */
+    abstract getMonthNames(style: TwDateNameStyle): string[];
+    /** Returns day-of-week names for the current locale, starting at Sunday. */
+    abstract getDayOfWeekNames(style: TwDateNameStyle): string[];
+    /** Returns 1-based day-of-month names (`["1", "2", ..., "31"]`) for locales that localize numerals. Default implementation returns Latin digits. */
+    getDateNames(_style?: TwDateNameStyle): string[];
+    /** Returns the localised year label (e.g. `"2026"`). */
+    abstract getYearName(date: D): string;
+    /** Formats a date for display. Subclasses pick their own format tokens. */
+    abstract format(date: D, displayFormat: unknown): string;
+    /** Date arithmetic — preserve original in immutable adapters. */
+    abstract addYears(date: D, years: number): D;
+    abstract addMonths(date: D, months: number): D;
+    abstract addDays(date: D, days: number): D;
+    /** Time arithmetic. Default implementation derives hours/minutes from day arithmetic via `addDays` — adapters with better precision should override. */
+    addHours(date: D, hours: number): D;
+    abstract addMinutes(date: D, minutes: number): D;
+    /** Returns negative when `first` is earlier, 0 when equal, positive when later. */
+    abstract compare(first: D, second: D): number;
+    abstract sameDate(first: D | null | undefined, second: D | null | undefined): boolean;
+    /** Whether a raw value can be turned into a valid date. */
+    abstract isValid(date: D): boolean;
+    /** Returns an invalid sentinel of type `D` (NaN-date for native). */
+    abstract invalid(): D;
+    /** Attempt to parse an ISO or free-form string. Return `null` on failure. */
+    abstract parse(value: unknown, parseFormat?: unknown): D | null;
+    /** Coerce an incoming value from form writes. */
+    abstract deserialize(value: unknown): D | null;
+    /** ISO 8601 (`YYYY-MM-DD`) serialization. Phases using serialized forms call this. */
+    abstract toIso(date: D): string;
+    /** ISO 8601 (`YYYY-MM-DD`) deserialization counterpart to `toIso`. */
+    fromIso(iso: string): D | null;
+    /**
+     * Start-of-day normalization. Default implementation rebuilds the date at
+     * `00:00:00.000` local time; DST-skipped hours (e.g., 02:00 on DST start) are
+     * resolved to the wall-clock midnight the adapter considers valid.
+     *
+     * TZ-aware adapters MUST override to normalize in the adapter's TZ.
+     */
+    abstract startOfDay(date: D): D;
+    /** First day of the week containing `date`. `firstDayOfWeek` defaults to `getFirstDayOfWeek()`. */
+    startOfWeek(date: D, firstDayOfWeek?: number): D;
+    /** Last day of the week containing `date`. */
+    endOfWeek(date: D, firstDayOfWeek?: number): D;
+    /** Equality on year + month. */
+    sameMonth(first: D, second: D): boolean;
+    /** Equality on year only. */
+    sameYear(first: D, second: D): boolean;
+    /** Clamp a date into the [min, max] window. */
+    clampDate(date: D, min?: D | null, max?: D | null): D;
+    /** Returns the adapter's configured timezone, or `null` for floating adapters. */
+    getTimezone(): string | null;
+    /** Returns a copy of `date` reinterpreted in `tz`. Floating adapters pass through. */
+    withTimezone(date: D, _tz: string): D;
+    /** Returns `true` when `date` sits inside a DST-transition. Floating adapters return `false`. */
+    isDST(_date: D): boolean;
+    /** Resolves an ambiguous wall-clock time (DST fall-back) to one of the two candidates. Floating adapters pass through. */
+    resolveAmbiguous(date: D, _prefer: 'earlier' | 'later'): D;
+}
+/**
+ * Injection token for the calendar's `DateAdapter`. Prefer `provideNativeDateAdapter()`
+ * or `provideTwCalendar({ adapter })` over binding this token directly.
+ */
+declare const DATE_ADAPTER: InjectionToken<DateAdapter<unknown>>;
+
+/**
+ * Shape of the read-only context the calendar validator needs from the
+ * hosting component. Kept as a structural type so tests and custom consumers
+ * can synthesize one without subclassing `CalendarComponent`.
+ */
+interface CalendarValidatorContext<M extends CalendarMode = CalendarMode, D = unknown> {
+    /** Current mode — used to decide which shape counts as "empty". */
+    readonly mode: M;
+    /** The raw form value whose last write was rejected as wrong-shape (§7.2). `null` when no rejected write is outstanding. */
+    readonly lastInvalidFormValue: unknown;
+    /** Aggregated constraint inputs (§10.1). Optional — when omitted, only `calendarRequired` / `calendarInvalidValue` codes are produced. */
+    readonly constraints?: CalendarConstraints<D>;
+    /** Adapter used to evaluate constraint codes. Required when `constraints` is set. */
+    readonly adapter?: DateAdapter<D>;
+    /** Minimum range length, days. `mode: 'range'` only. */
+    readonly minRangeLength?: number | null;
+    /** Maximum range length, days. `mode: 'range'` only. */
+    readonly maxRangeLength?: number | null;
+    /** Maximum number of selections. `mode: 'multiple'` only. */
+    readonly maxSelections?: number | null;
+}
+/** `true` when `value` matches the mode-specific empty state (§7.1, §6.4). */
+declare function isCalendarValueEmpty<M extends CalendarMode, D>(mode: M, value: CalendarValue<M, D> | null | undefined): boolean;
+/**
+ * Built-in synchronous validator (§6.1, §10.2). Emits the full v1 error code set:
+ *
+ * Phase 3 codes:
+ * - `calendarRequired` when the hosting control carries `Validators.required`
+ *   and the calendar value is mode-specific empty.
+ * - `calendarInvalidValue` when the most recent `writeValue` was rejected as
+ *   wrong-shape (§7.2) — the raw value is held on the component's
+ *   `lastInvalidFormValue` until a valid write clears it.
+ *
+ * Phase 4 codes (active when `ctx.constraints` + `ctx.adapter` are supplied):
+ * - `calendarMinDate` / `calendarMaxDate` — value (or any range endpoint /
+ *   array entry) falls outside `[minDate, maxDate]`.
+ * - `calendarDisabledDate` — value matches `dateFilter` / `disabledDates` /
+ *   `disabledDaysOfWeek` (constraint resolver).
+ * - `calendarRangeTooShort` / `calendarRangeTooLong` — `mode: 'range'` length
+ *   violates `minRangeLength` / `maxRangeLength`.
+ * - `calendarMaxSelections` — `mode: 'multiple'` array exceeds `maxSelections`.
+ * - `calendarInvalidRange` — committed range has `start > end` (the orchestrator
+ *   normalizes via auto-swap; this only triggers on programmatic writeValue).
+ *
+ * Each code's payload mirrors §10.2 — `{ min, actual }`, `{ max, actual }`,
+ * `{ length, min }`, etc.
+ */
+declare function calendarValidator<M extends CalendarMode, D>(ctx: CalendarValidatorContext<M, D>): ValidatorFn;
+/**
+ * Standalone required-validator helper for consumers who want to compose
+ * calendar-required on a control that is **not** bound directly to a
+ * `CalendarComponent`. The rule is identical: mode-specific empty ⇒ error.
+ */
+declare function calendarRequiredValidator<M extends CalendarMode, D>(mode: M): ValidatorFn;
+
+/**
+ * Marker directive for a slot positioned above the calendar grid. Used to
+ * style an external preset rail; the calendar renders projected content
+ * with `<ng-content select="[twCalendarPresets]">`.
+ */
+declare class CalendarPresetsDirective {
+    static ɵfac: i0.ɵɵFactoryDeclaration<CalendarPresetsDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CalendarPresetsDirective, "[twCalendarPresets]", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Calendar navigation header — previous / period / next button row.
+ * The period label button toggles between views (month → year → multi-year).
+ */
+declare class CalendarHeaderComponent {
+    /** Display text for the period button (e.g. "January 2026"). */
+    readonly periodLabel: InputSignal<string>;
+    /** Accessible label for the period button. */
+    readonly periodAriaLabel: InputSignal<string>;
+    /** Accessible label for the previous button. */
+    readonly prevAriaLabel: InputSignal<string>;
+    /** Accessible label for the next button. */
+    readonly nextAriaLabel: InputSignal<string>;
+    /** Disables the previous button. */
+    readonly prevDisabled: InputSignal<boolean>;
+    /** Disables the next button. */
+    readonly nextDisabled: InputSignal<boolean>;
+    /** When false, the period button is disabled (e.g. when already at the top view). */
+    readonly canSwitchView: InputSignal<boolean>;
+    /** Fires on previous button click. */
+    readonly prevClicked: OutputEmitterRef<void>;
+    /** Fires on next button click. */
+    readonly nextClicked: OutputEmitterRef<void>;
+    /** Fires on period button click (switch to the next higher view). */
+    readonly periodClicked: OutputEmitterRef<void>;
+    protected readonly classes: Signal<{
+        root: string;
+        navButton: string;
+        periodButton: string;
+    }>;
+    protected onPeriodClick(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CalendarHeaderComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CalendarHeaderComponent, "tw-calendar-header", never, { "periodLabel": { "alias": "periodLabel"; "required": true; "isSignal": true; }; "periodAriaLabel": { "alias": "periodAriaLabel"; "required": true; "isSignal": true; }; "prevAriaLabel": { "alias": "prevAriaLabel"; "required": true; "isSignal": true; }; "nextAriaLabel": { "alias": "nextAriaLabel"; "required": true; "isSignal": true; }; "prevDisabled": { "alias": "prevDisabled"; "required": false; "isSignal": true; }; "nextDisabled": { "alias": "nextDisabled"; "required": false; "isSignal": true; }; "canSwitchView": { "alias": "canSwitchView"; "required": false; "isSignal": true; }; }, { "prevClicked": "prevClicked"; "nextClicked": "nextClicked"; "periodClicked": "periodClicked"; }, never, never, true, never>;
+}
+
+/**
+ * German (de) locale pack for the calendar's user-visible strings.
+ * Pass into the `intl` input or via {@link provideCalendarIntl}. Per-field
+ * merge semantics (§19.4) — unspecified fields fall back to English defaults.
+ */
+declare const de: Partial<CalendarIntl>;
+
+/**
+ * French (fr) locale pack for the calendar's user-visible strings.
+ * Pass into the `intl` input or via {@link provideCalendarIntl}. Per-field
+ * merge semantics (§19.4) — unspecified fields fall back to English defaults.
+ */
+declare const fr: Partial<CalendarIntl>;
+
+/**
+ * Spanish (es) locale pack for the calendar's user-visible strings.
+ * Pass into the `intl` input or via {@link provideCalendarIntl}. Per-field
+ * merge semantics (§19.4) — unspecified fields fall back to English defaults.
+ */
+declare const es: Partial<CalendarIntl>;
+
+/**
+ * Portuguese (pt) locale pack for the calendar's user-visible strings.
+ * Pass into the `intl` input or via {@link provideCalendarIntl}. Per-field
+ * merge semantics (§19.4) — unspecified fields fall back to English defaults.
+ */
+declare const pt: Partial<CalendarIntl>;
+
+/**
+ * Japanese (ja) locale pack for the calendar's user-visible strings.
+ * Pass into the `intl` input or via {@link provideCalendarIntl}. Per-field
+ * merge semantics (§19.4) — unspecified fields fall back to English defaults.
+ *
+ * Note: Japanese has no grammatical plural form, so plural-marked methods
+ * collapse to a single form.
+ */
+declare const ja: Partial<CalendarIntl>;
+
+/** Emitted on keyboard navigation keys (arrows, Home/End, PageUp/PageDown). */
+interface CalendarCellKeyNavEvent<D> {
+    readonly direction: 'left' | 'right' | 'up' | 'down' | 'home' | 'end' | 'pageUp' | 'pageDown';
+    /** True when the originating KeyboardEvent had Shift held — drives year-jump variants of Page navigation. */
+    readonly shiftKey: boolean;
+    readonly cell: CalendarCell<D>;
+}
+/**
+ * Renders a single cell in any calendar view.
+ *
+ * The cell is a stateless presentation component — selection / preview /
+ * today state is all derived from the `CalendarCell<D>` data object. It
+ * emits events for clicks, keyboard navigation, mouse hover, and focus.
+ */
+declare class CalendarCellComponent<D> {
+    private readonly buttonRef;
+    /** The cell data object to render. */
+    readonly cell: InputSignal<CalendarCell<D>>;
+    /** The active calendar view — drives cell dimensions and radius. */
+    readonly view: InputSignal<CalendarViewState>;
+    /** `true` when the cell's date is outside the currently displayed month. */
+    readonly outside: InputSignal<boolean>;
+    /** Tab index for roving focus (`0` for the active cell, `-1` otherwise). */
+    readonly tabindex: InputSignal<number>;
+    /** Optional template rendered inside the button — receives `{ $implicit: CalendarCell<D> }`. */
+    readonly cellTemplate: InputSignal<TemplateRef<{
+        $implicit: CalendarCell<D>;
+    }> | null>;
+    /** Emitted when the user activates the cell (click, Enter, or Space). */
+    readonly selected: OutputEmitterRef<CalendarCell<D>>;
+    /** Emitted when the cell gains focus. */
+    readonly focused: OutputEmitterRef<CalendarCell<D>>;
+    /** Emitted on pointer hover — parent uses this to drive range preview. */
+    readonly previewed: OutputEmitterRef<CalendarCell<D>>;
+    /** Emitted on navigation keys (arrows, Home/End, PageUp/PageDown). */
+    readonly keyNav: OutputEmitterRef<CalendarCellKeyNavEvent<D>>;
+    protected readonly cellState: Signal<CalendarCellState>;
+    protected readonly wrapperRange: Signal<'none' | 'start' | 'middle' | 'end' | 'single'>;
+    private readonly variantResult;
+    protected readonly wrapperClasses: Signal<string>;
+    protected readonly buttonClasses: Signal<string>;
+    protected onClick(): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    protected onMouseEnter(): void;
+    protected onFocus(): void;
+    /** Imperatively focuses this cell's button. */
+    focusButton(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CalendarCellComponent<any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<CalendarCellComponent<any>, "tw-calendar-cell", never, { "cell": { "alias": "cell"; "required": true; "isSignal": true; }; "view": { "alias": "view"; "required": false; "isSignal": true; }; "outside": { "alias": "outside"; "required": false; "isSignal": true; }; "tabindex": { "alias": "tabindex"; "required": false; "isSignal": true; }; "cellTemplate": { "alias": "cellTemplate"; "required": false; "isSignal": true; }; }, { "selected": "selected"; "focused": "focused"; "previewed": "previewed"; "keyNav": "keyNav"; }, never, never, true, never>;
+}
+
+/**
+ * Abstract base for the three calendar views. Holds shared inputs/outputs
+ * (selection, preview, min/max, filters), cell-hit helpers, and roving-focus
+ * machinery. Subclasses implement `cells`, `gridLabel`, `onKeyNav`, and
+ * `getActiveCompareValue`.
+ */
+declare abstract class CalendarViewBase<D> {
+    protected readonly dateAdapter: DateAdapter<D>;
+    /** The date that anchors the grid being rendered. */
+    readonly activeDate: InputSignal<D>;
+    /** Current selection — scalar, array (multi), or range. */
+    readonly selected: InputSignal<D | D[] | DateRange<D> | null>;
+    /** Minimum selectable date. */
+    readonly minDate: InputSignal<D | null>;
+    /** Maximum selectable date. */
+    readonly maxDate: InputSignal<D | null>;
+    /** Per-date predicate — return `false` to disable. */
+    readonly dateFilter: InputSignal<DateFilterFn<D> | null>;
+    /** Explicitly disabled dates — array (compared via `adapter.sameDate`) or predicate (returns `true` for disabled). */
+    readonly disabledDates: InputSignal<DisabledDates<D> | null>;
+    /** Days of the week to disable (0=Sun … 6=Sat). Empty array = no day-of-week disabling. */
+    readonly disabledDaysOfWeek: InputSignal<readonly number[]>;
+    /** Per-cell class override. */
+    readonly dateClass: InputSignal<DateClassFn<D> | null>;
+    /** Hover-preview start (set while user is mid-range pick). */
+    readonly previewStart: InputSignal<D | null>;
+    /** Hover-preview end. */
+    readonly previewEnd: InputSignal<D | null>;
+    /** Phase 6 — date that briefly flashes as invalid (rejected commit). Cleared by the orchestrator. */
+    readonly invalidFlashDate: InputSignal<D | null>;
+    /** `true` when the parent calendar allows more than one cell to be selected at once. Drives `aria-multiselectable` on the grid host. */
+    readonly multiSelectable: InputSignal<boolean>;
+    /** `true` when the parent calendar is in read-only mode. Drives `aria-readonly` on the grid host. */
+    readonly readonlyGrid: InputSignal<boolean>;
+    /** Optional cell-content override. */
+    readonly cellTemplate: InputSignal<TemplateRef<{
+        $implicit: CalendarCell<D>;
+    }> | null>;
+    /** Fires when the user activates an enabled cell (click, Enter, or Space). Payload is the activated cell's date. */
+    readonly selectedChange: OutputEmitterRef<D>;
+    /** Fires when keyboard navigation or programmatic focus moves the roving cursor to a new cell. Payload is the new active date. */
+    readonly activeDateChange: OutputEmitterRef<D>;
+    /** Fires on pointer hover with the hovered date, and again with `null` when the pointer leaves the grid. The parent orchestrator drives any range-preview state from this stream. */
+    readonly previewChange: OutputEmitterRef<D | null>;
+    /** Subclass declares which view it represents. */
+    protected abstract readonly view: CalendarViewState;
+    /** Subclass exposes its cell components for focus management. */
+    protected abstract readonly cellComponents: Signal<readonly CalendarCellComponent<D>[]>;
+    /** Cell that should own the roving-tabindex cursor. `null` means "use `activeDate`". */
+    protected readonly focusedCellValue: WritableSignal<number | null>;
+    /** Pending focus target — drained after the next render. */
+    protected readonly focusPending: WritableSignal<number | null>;
+    constructor();
+    /** 2D grid of cells rendered by the subclass. */
+    abstract readonly cells: Signal<CalendarCell<D>[][]>;
+    /** Accessible label for the grid (e.g. "January 2026"). */
+    abstract readonly gridLabel: Signal<string>;
+    /** Today's date — memoized per view instance. */
+    protected readonly today: Signal<D>;
+    /** True when `date` is part of the committed selection. */
+    protected isSelected(date: D): boolean;
+    protected isRangeStart(date: D): boolean;
+    protected isRangeEnd(date: D): boolean;
+    protected isRangeMiddle(date: D): boolean;
+    protected isPreviewStart(date: D): boolean;
+    protected isPreviewEnd(date: D): boolean;
+    protected isPreviewMiddle(date: D): boolean;
+    protected isDateRange(value: D | D[] | DateRange<D>): value is DateRange<D>;
+    /** Routes a cell activation up to the parent. */
+    onCellSelected(cell: CalendarCell<D>): void;
+    /** Routes hover events up to the parent (parent drives preview state). */
+    onCellPreviewed(cell: CalendarCell<D>): void;
+    /** Clears the preview when the pointer leaves the grid. */
+    onGridMouseLeave(): void;
+    /** Subclass implements view-specific keyboard navigation. */
+    abstract onKeyNav(event: {
+        direction: string;
+        cell: CalendarCell<D>;
+    }): void;
+    /** Returns `true` when the cell owns the roving cursor. */
+    isActiveCell(cell: CalendarCell<D>): boolean;
+    /** Compare value of the currently active date (subclass-specific). */
+    protected abstract getActiveCompareValue(): number;
+    /** Imperatively focuses the cell matching `compareValue` after the next render. */
+    focusCell(compareValue: number): void;
+    /** Focuses the cell that currently owns the roving cursor. */
+    focusActiveCell(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<CalendarViewBase<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<CalendarViewBase<any>, never, never, { "activeDate": { "alias": "activeDate"; "required": true; "isSignal": true; }; "selected": { "alias": "selected"; "required": false; "isSignal": true; }; "minDate": { "alias": "minDate"; "required": false; "isSignal": true; }; "maxDate": { "alias": "maxDate"; "required": false; "isSignal": true; }; "dateFilter": { "alias": "dateFilter"; "required": false; "isSignal": true; }; "disabledDates": { "alias": "disabledDates"; "required": false; "isSignal": true; }; "disabledDaysOfWeek": { "alias": "disabledDaysOfWeek"; "required": false; "isSignal": true; }; "dateClass": { "alias": "dateClass"; "required": false; "isSignal": true; }; "previewStart": { "alias": "previewStart"; "required": false; "isSignal": true; }; "previewEnd": { "alias": "previewEnd"; "required": false; "isSignal": true; }; "invalidFlashDate": { "alias": "invalidFlashDate"; "required": false; "isSignal": true; }; "multiSelectable": { "alias": "multiSelectable"; "required": false; "isSignal": true; }; "readonlyGrid": { "alias": "readonlyGrid"; "required": false; "isSignal": true; }; "cellTemplate": { "alias": "cellTemplate"; "required": false; "isSignal": true; }; }, { "selectedChange": "selectedChange"; "activeDateChange": "activeDateChange"; "previewChange": "previewChange"; }, never, never, true, never>;
+}
+
+/** Arranges a flat array of items into a 2D grid with `columns` items per row. */
+declare function createGrid<T>(items: readonly T[], columns: number): T[][];
+/** Returns the new flat index after an arrow-key navigation step, or `null` on out of bounds. */
+declare function navigateGrid(currentIndex: number, direction: 'left' | 'right' | 'up' | 'down', totalItems: number, columns: number): number | null;
+/** Label pair for a weekday header cell. */
+interface WeekdayHeader {
+    readonly label: string;
+    readonly narrow: string;
+}
+/** Builds seven weekday headers rotated to start at `firstDayOfWeek` (or adapter default). */
+declare function getWeekdayHeaders<D>(adapter: DateAdapter<D>, style?: NameStyle, firstDayOfWeek?: number): WeekdayHeader[];
+/**
+ * True when `date` falls outside `[minDate, maxDate]` or fails the filter.
+ *
+ * Phase 4 superset: also OR-checks `disabledDates` (array OR predicate) and
+ * `disabledDaysOfWeek`. Legacy callers passing only the first four arguments
+ * keep working — the new sources default to neutral values.
+ */
+declare function isDateDisabled<D>(date: D, minDate: D | null, maxDate: D | null, dateFilter: DateFilterFn<D> | null, adapter: DateAdapter<D>, disabledDates?: DisabledDates<D> | null, disabledDaysOfWeek?: readonly number[]): boolean;
+/** True when the whole month falls outside `[minDate, maxDate]`. `month` is 0-based (matches `adapter.getMonth`). */
+declare function isMonthDisabled<D>(year: number, month: number, minDate: D | null, maxDate: D | null, adapter: DateAdapter<D>): boolean;
+/** True when the whole year falls outside `[minDate, maxDate]`. */
+declare function isYearDisabled<D>(year: number, minDate: D | null, maxDate: D | null, adapter: DateAdapter<D>): boolean;
+/** Aligns `activeYear` to the start of its `yearsPerPage`-block. */
+declare function getMultiYearStartingYear(activeYear: number, yearsPerPage?: number): number;
+/** True when `date` sits inside `[start, end]` (inclusive). */
+declare function isDateInRange<D>(date: D, start: D | null, end: D | null, adapter: DateAdapter<D>): boolean;
+/** Returns the first day of the month for `date`. */
+declare function getFirstDayOfMonth<D>(date: D, adapter: DateAdapter<D>): D;
+
+/**
+ * Month view — renders a 7×6 grid of day cells, with leading/trailing days
+ * from adjacent months marked as "outside".
+ */
+declare class MonthViewComponent<D> extends CalendarViewBase<D> {
+    protected readonly view: CalendarViewState;
+    protected readonly cellComponents: Signal<readonly CalendarCellComponent<D>[]>;
+    /** Override first day of week (0=Sun, 1=Mon). */
+    readonly firstDayOfWeek: InputSignal<number>;
+    /** Index within a multi-month row (0=left, 1+=right) — used by the orchestrator to disambiguate focus. */
+    readonly gridIndex: InputSignal<number>;
+    readonly weekdayHeaders: Signal<WeekdayHeader[]>;
+    readonly displayMonth: Signal<number>;
+    readonly displayYear: Signal<number>;
+    readonly cells: Signal<CalendarCell<D>[][]>;
+    readonly gridLabel: Signal<string>;
+    protected getActiveCompareValue(): number;
+    /** True when the cell's date sits in a neighbouring month (leading/trailing). */
+    isOutsideMonth(cell: CalendarCell<D>): boolean;
+    onKeyNav(event: CalendarCellKeyNavEvent<D>): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MonthViewComponent<any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MonthViewComponent<any>, "tw-calendar-month-view", never, { "firstDayOfWeek": { "alias": "firstDayOfWeek"; "required": false; "isSignal": true; }; "gridIndex": { "alias": "gridIndex"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Year view — 4×3 grid of month cells inside the active year.
+ */
+declare class YearViewComponent<D> extends CalendarViewBase<D> {
+    protected readonly view: CalendarViewState;
+    protected readonly cellComponents: Signal<readonly CalendarCellComponent<D>[]>;
+    readonly displayYear: Signal<number>;
+    readonly cells: Signal<CalendarCell<D>[][]>;
+    readonly gridLabel: Signal<string>;
+    protected getActiveCompareValue(): number;
+    onKeyNav(event: CalendarCellKeyNavEvent<D>): void;
+    private isMonthSelected;
+    private isMonthRangeStart;
+    private isMonthRangeEnd;
+    private isMonthRangeMiddle;
+    private isMonthPreviewStart;
+    private isMonthPreviewEnd;
+    private isMonthPreviewMiddle;
+    static ɵfac: i0.ɵɵFactoryDeclaration<YearViewComponent<any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<YearViewComponent<any>, "tw-calendar-year-view", never, {}, {}, never, never, true, never>;
+}
+
+/** Default years per page — kept until Phase 7 introduces the `yearsPerPage` input. */
+declare const yearsPerPage = 24;
+/**
+ * Year view — 4×6 grid (24 years by default). A user clicks a year to drill
+ * down to the month-of-year view. In the spec vocabulary this is the
+ * `'year'` view state (§7.4, §22).
+ */
+declare class YearsViewComponent<D> extends CalendarViewBase<D> {
+    protected readonly view: CalendarViewState;
+    protected readonly cellComponents: Signal<readonly CalendarCellComponent<D>[]>;
+    readonly startYear: Signal<number>;
+    readonly endYear: Signal<number>;
+    readonly cells: Signal<CalendarCell<D>[][]>;
+    readonly gridLabel: Signal<string>;
+    protected getActiveCompareValue(): number;
+    onKeyNav(event: CalendarCellKeyNavEvent<D>): void;
+    private isYearSelected;
+    private isYearRangeStart;
+    private isYearRangeEnd;
+    private isYearRangeMiddle;
+    private isYearPreviewStart;
+    private isYearPreviewEnd;
+    private isYearPreviewMiddle;
+    static ɵfac: i0.ɵɵFactoryDeclaration<YearsViewComponent<any>, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<YearsViewComponent<any>, "tw-calendar-years-view", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Serializes a `CalendarValue<M, D>` to a JSON-friendly shape (spec §7.5, §33.4).
+ * The output mirrors the mode: a scalar ISO string for single, an array for
+ * multiple, and an endpoint-preserving object for range. `null` endpoints
+ * round-trip unchanged.
+ *
+ * This is a consumer-facing helper — the component itself does NOT auto-
+ * serialize. Apps emitting ISO strings at the form-submit boundary call
+ * `serializeCalendarValue(control.value, adapter)` and assign the result to
+ * their backend payload.
+ *
+ * Typing: TypeScript cannot narrow the return type by the mode-generic without
+ * the caller passing `M` explicitly; the helper is declared with overloads that
+ * cover all three modes plus a broad union fallback.
+ */
+declare function serializeCalendarValue<D>(value: CalendarValue<'single', D>, adapter: DateAdapter<D>): string | null;
+declare function serializeCalendarValue<D>(value: CalendarValue<'multiple', D>, adapter: DateAdapter<D>): string[];
+declare function serializeCalendarValue<D>(value: CalendarValue<'range', D>, adapter: DateAdapter<D>): {
+    start: string | null;
+    end: string | null;
+};
+declare function serializeCalendarValue<M extends CalendarMode, D>(value: CalendarValue<M, D>, adapter: DateAdapter<D>): string | null | string[] | {
+    start: string | null;
+    end: string | null;
+};
+
+/** Display-format descriptor used by `NativeDateAdapter.format()`. */
+interface TwNativeDateFormat {
+    /** Any option bag accepted by `Intl.DateTimeFormat`. */
+    readonly dateTimeFormat?: Intl.DateTimeFormatOptions;
+}
+/** `Intl`-driven `Date` adapter. Zero runtime dependencies. */
+declare class NativeDateAdapter extends DateAdapter<Date> {
+    /**
+     * Locale is resolved lazily on first read so the constructor stays
+     * SSR-safe (no `navigator` access at class-construction time — §31.1).
+     */
+    private _locale;
+    private get locale();
+    today(): Date;
+    /**
+     * Constructs a `Date`. **`month` is 1-based** — `create(2026, 1, 1)` yields
+     * January 1, 2026.
+     */
+    create(year: number, month: number, day: number): Date;
+    clone(date: Date): Date;
+    setLocale(locale: string): void;
+    getLocale(): string;
+    getYear(date: Date): number;
+    getMonth(date: Date): number;
+    getDate(date: Date): number;
+    getDayOfWeek(date: Date): number;
+    getNumDaysInMonth(date: Date): number;
+    getHours(date: Date): number;
+    getMinutes(date: Date): number;
+    getSeconds(date: Date): number;
+    withTime(date: Date, hours: number, minutes: number, seconds: number): Date;
+    getFirstDayOfWeek(): number;
+    getMonthNames(style: TwDateNameStyle): string[];
+    getDayOfWeekNames(style: TwDateNameStyle): string[];
+    getDateNames(style?: TwDateNameStyle): string[];
+    getYearName(date: Date): string;
+    format(date: Date, displayFormat: unknown): string;
+    addYears(date: Date, years: number): Date;
+    addMonths(date: Date, months: number): Date;
+    addDays(date: Date, days: number): Date;
+    addMinutes(date: Date, minutes: number): Date;
+    addHours(date: Date, hours: number): Date;
+    compare(first: Date, second: Date): number;
+    sameDate(first: Date | null | undefined, second: Date | null | undefined): boolean;
+    /**
+     * Start-of-day normalization. Rebuilds the date at `00:00:00.000` local time.
+     * On DST spring-forward days where midnight is valid, this is a no-op beyond
+     * zeroing h/m/s/ms. On DST fall-back days the repeated-01:00 hour does not
+     * affect `00:00`, so this is also safe.
+     *
+     * The edge case of an entire DST-skipped midnight (rare — exists in some
+     * historical zones) is resolved by `new Date(year, month, day)` selecting the
+     * next valid instant forward.
+     */
+    startOfDay(date: Date): Date;
+    isValid(date: Date): boolean;
+    invalid(): Date;
+    parse(value: unknown): Date | null;
+    deserialize(value: unknown): Date | null;
+    toIso(date: Date): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NativeDateAdapter, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<NativeDateAdapter>;
+}
+/** Provides the default `Date`-based adapter. */
+declare function provideNativeDateAdapter(): EnvironmentProviders;
+/** Provides a custom `DateAdapter` implementation. */
+declare function provideTwCalendar<D>(config: {
+    adapter: new (...args: never[]) => DateAdapter<D>;
+    extraProviders?: Provider[];
+}): EnvironmentProviders;
+
+/**
+ * Convenience class that satisfies the `DateRange<D>` interface and carries
+ * `complete` / `empty` getters. Interchangeable with a plain
+ * `{ start, end }` object anywhere a `DateRange<D>` is expected.
+ */
+declare class TwDateRange<D> implements DateRange<D> {
+    readonly start: D | null;
+    readonly end: D | null;
+    constructor(start: D | null, end: D | null);
+    /** True when both endpoints are set. */
+    get complete(): boolean;
+    /** True when neither endpoint is set. */
+    get empty(): boolean;
+}
+/** Shape accepted when writing a range value — either a `TwDateRange` or a plain object. */
+type TwDateRangeInput<D> = TwDateRange<D> | {
+    readonly start: D | null;
+    readonly end: D | null;
+} | null;
+/** @internal Normalises any range-shaped value into a `TwDateRange` instance. */
+declare function toTwDateRange<D>(value: TwDateRangeInput<D>): TwDateRange<D> | null;
+
+export { CALENDAR_SELECTION_STRATEGY, CalendarCellComponent, CalendarComponent, CalendarHeaderComponent, CalendarIntl, CalendarMultipleDirective, CalendarPresetsDirective, CalendarRangeDirective, CalendarSelectionStrategy, CalendarSingleDirective, CalendarViewBase, DATE_ADAPTER, DATE_FORMATS, DATE_SERIALIZATION, DAYS_PER_WEEK, DateAdapter, MONTHS_PER_ROW, MonthViewComponent, MultiSelectionStrategy, NativeDateAdapter, RangeSelectionStrategy, SingleSelectionStrategy, TZ_OVERRIDE, TwDateRange, WEEKS_PER_MONTH, WeekSelectionStrategy, YEARS_PER_PAGE, YEARS_PER_ROW, YearViewComponent, YearsViewComponent, calendarRequiredValidator, calendarValidator, createCalendarCell, createDateRange, createGrid, de, emptyCalendarValue, es, fr, getFirstDayOfMonth, getMultiYearStartingYear, getWeekdayHeaders, isCalendarValueEmpty, isDateDisabled, isDateInRange, isMonthDisabled, isYearDisabled, ja, navigateGrid, provideCalendarIntl, provideCalendarSelectionStrategy, provideMultiSelectionStrategy, provideNativeDateAdapter, provideRangeSelectionStrategy, provideSingleSelectionStrategy, provideTwCalendar, provideWeekSelectionStrategy, pt, serializeCalendarValue, toTwDateRange, yearsPerPage };
+export type { CalendarCell, CalendarCellAccessibleNameContext, CalendarCellConfig, CalendarCellKeyNavEvent, CalendarCellState, CalendarConstraints, CalendarErrorCode, CalendarMode, CalendarMultipleValue, CalendarOverlayState, CalendarRangeValue, CalendarSelectionState, CalendarSingleValue, CalendarValidationErrors, CalendarValidatorContext, CalendarValue, CalendarViewState, DateClassFn, DateFilterFn, DateFormats, DateRange, DisabledDates, MaxSelectionBehavior, MobileMode, ModeChangeEvent, NameStyle, RangeClickBehavior, RangeGranularity, RangePreviewEvent, ResetBehavior, SelectionClearedEvent, SelectionCompleteEvent, SelectionResult, TwDateNameStyle, TwDateRangeInput, TwNativeDateFormat, ViewChangeEvent, WeekdayHeader };