@cdevhub/ngx-tw 0.5.0 → 0.6.0

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

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
 import { InjectionToken, Signal, ElementRef, ViewContainerRef, Injector, ComponentRef, EventEmitter } from '@angular/core';
-import { AbstractControl } from '@angular/forms';
+import { AbstractControl, NgControl, ValidatorFn } from '@angular/forms';
 import { ConnectedPosition, Overlay, ScrollStrategy, OverlayRef } from '@angular/cdk/overlay';
 import { ComponentType } from '@angular/cdk/portal';
 import { Observable } from 'rxjs';
@@ -83,6 +83,131 @@ declare const defaultErrorStateMatcher: ErrorStateMatcher;
  */
 declare const TW_ERROR_STATE_MATCHER: InjectionToken<ErrorStateMatcher>;
 
+/**
+ * Configuration for {@link wireErrorState}. Every field is a callback rather
+ * than a `Signal`, so the options object may reference class members that are
+ * declared *below* the `wireErrorState()` call site — the callbacks are only
+ * invoked from inside the returned computeds, long after construction.
+ */
+interface ErrorStateWiringOptions {
+    /**
+     * Resolves the host's bound `NgControl`, or `null` when the host is not bound
+     * to a form control. Pass a getter rather than the instance so controls that
+     * resolve `NgControl` lazily (pickers that self-provide `NG_VALIDATORS` and
+     * must defer the lookup to `ngOnInit`) work unchanged. Deliberately *not*
+     * injected by this helper: the host owns the `NgControl` reference because it
+     * also owns `ControlValueAccessor` registration.
+     */
+    readonly ngControl: () => NgControl | null;
+    /**
+     * Reads the host's per-instance `errorStateMatcher` input. When it returns
+     * `undefined` the matcher provided under `TW_ERROR_STATE_MATCHER` is used.
+     */
+    readonly matcher?: () => ErrorStateMatcher | undefined;
+    /**
+     * Reads the host's `required` input. When it returns `true`,
+     * {@link ErrorStateWiring.required} is `true` without consulting validators —
+     * the arm that keeps signal forms working, since `cvaControlCreate` writes the
+     * `required` input directly and never inspects validators.
+     */
+    readonly required?: () => boolean;
+    /**
+     * Validators that mark the control required when present on the bound
+     * `NgControl`. Defaults to `[Validators.required]`; boolean controls
+     * (`tw-checkbox`, `tw-switch`) also pass `Validators.requiredTrue`.
+     */
+    readonly requiredValidators?: readonly ValidatorFn[];
+    /**
+     * Extra reactive sources {@link ErrorStateWiring.errorState} track-reads.
+     * Controls pass their focus signal here so a blur — which flips `touched` on
+     * the bound control without changing its status or value — repaints the error
+     * styling.
+     */
+    readonly track?: readonly (() => unknown)[];
+    /**
+     * Short-circuits {@link ErrorStateWiring.errorState}. Return a boolean to use
+     * it as the error state without consulting the matcher, or `undefined` to fall
+     * through to the matcher. Used by the pickers (a parse or range error is an
+     * error regardless of validator status) and by `tw-radio` (a radio inside a
+     * group inherits the group's error state). Called after the revision signals
+     * are read, so its own reads are tracked normally.
+     */
+    readonly errorStateOverride?: () => boolean | undefined;
+}
+/** Reactive error-state surface returned by {@link wireErrorState}. */
+interface ErrorStateWiring {
+    /**
+     * Whether the control should render as invalid, per the resolved
+     * {@link ErrorStateMatcher}. Satisfies `FormFieldControl.errorState`.
+     */
+    readonly errorState: Signal<boolean>;
+    /**
+     * Whether the control is required — the host's `required` input OR'd with the
+     * configured required validators on the bound `NgControl`. Satisfies
+     * `FormFieldControl.required`.
+     */
+    readonly required: Signal<boolean>;
+    /**
+     * Active validation errors on the bound `NgControl`, or `null` when it reports
+     * none or is unbound. Satisfies `FormFieldControl.errors`, which is what
+     * `[twError match="…"]` filters on inside a `<tw-form-field>`.
+     */
+    readonly errors: Signal<Record<string, unknown> | null>;
+    /**
+     * Revision counter bumped whenever the bound control may have changed. Read it
+     * from any other computed that dereferences `NgControl` — typically a
+     * `disabled` computed reading `ngControl.disabled` — so that computed
+     * invalidates on the same ticks the error state does.
+     */
+    readonly rev: Signal<number>;
+    /**
+     * Bumps {@link ErrorStateWiring.rev}. Call it from anywhere the bound control
+     * changed without emitting on `statusChanges`/`valueChanges` — a `FocusMonitor`
+     * blur that flipped `touched`, `setDisabledState`, or immediately after a
+     * deferred `NgControl` lookup.
+     */
+    bump(): void;
+    /**
+     * Subscribes to the bound control's `statusChanges`/`valueChanges` and to the
+     * parent form's `ngSubmit`. Call this from `ngOnInit`, never the constructor:
+     * `NgControl.control` is populated by the parent `FormControl*` directive's own
+     * `ngOnChanges`, which runs before children's `ngOnInit` but after their
+     * constructors. Teardown is wired to the host's `DestroyRef`.
+     */
+    connect(): void;
+}
+/**
+ * Builds the error-state, required and errors signals every ngx-tw form control
+ * exposes to `<tw-form-field>`, plus the revision plumbing that keeps them live.
+ *
+ * Call it from an injection context (a field initializer or the constructor).
+ * It injects `DestroyRef`, `NgForm`/`FormGroupDirective` (both optional) and
+ * `TW_ERROR_STATE_MATCHER` on the host's behalf; it does **not** inject
+ * `NgControl`, because the host must keep ownership of that reference for
+ * `ControlValueAccessor` registration.
+ *
+ * Wiring an error-state-aware control takes three steps:
+ *
+ * ```ts
+ * private readonly ngControl = inject(NgControl, { optional: true, self: true });
+ * private readonly errorWiring = wireErrorState({
+ *   ngControl: () => this.ngControl,
+ *   matcher: () => this.errorStateMatcher(),
+ *   required: () => this.requiredInput(),
+ *   track: [this._focused],
+ * });
+ *
+ * readonly errorState = this.errorWiring.errorState;
+ * readonly required = this.errorWiring.required;
+ * readonly errors = this.errorWiring.errors;
+ *
+ * ngOnInit(): void {
+ *   this.errorWiring.connect();
+ * }
+ * ```
+ */
+declare function wireErrorState(options: ErrorStateWiringOptions): ErrorStateWiring;
+
 /**
  * Read-only view of a sortable region's state.
  *
@@ -184,6 +309,15 @@ interface PickerOpenConfig<TOverlay> {
     readonly panelClass: string;
     /** Viewport margin forwarded to the CDK position-strategy. Defaults to `8`. */
     readonly viewportMargin?: number;
+    /**
+     * Whether keyboard focus is trapped inside the overlay while it is open.
+     * Defaults to `true`, which suits modal picker panels that move DOM focus
+     * into the overlay. Pass `false` for `aria-activedescendant` surfaces
+     * (`tw-select`, `tw-combobox`) where DOM focus deliberately stays on the
+     * trigger: the trap's capturing anchor elements would otherwise sit in the
+     * tab order around a panel that holds no focusable content.
+     */
+    readonly focusTrap?: boolean;
 }
 /** Synchronous return shape of {@link PickerOverlayCoordinator.open}. */
 interface PickerOpenResult<TOverlay> {
@@ -199,18 +333,23 @@ interface PickerOpenResult<TOverlay> {
 /**
  * Coordinator that owns the CDK `OverlayRef`, focus trap, panel-id, and
  * animation timing for an overlay-bearing form control. Consumed by
- * `DatePickerComponent` and `DateRangePickerComponent`; both pickers register
- * the coordinator at the component level (`providers: [PickerOverlayCoordinator]`)
- * so each picker instance owns its own coordinator state.
+ * `DatePickerComponent`, `DateRangePickerComponent`, `SelectComponent` and
+ * `ComboboxComponent`; every consumer registers the coordinator at the
+ * component level (`providers: [PickerOverlayCoordinator]`) so each instance
+ * owns its own coordinator state.
  *
  * Per the library "no `providedIn: 'root'` for services" rule (see
  * `.claude/CLAUDE.md` → "What NOT To Do"): the coordinator holds per-overlay
  * `OverlayRef` / `FocusTrap` state and MUST be component-scoped.
  *
  * Scope of responsibility:
- * - Create / dispose the CDK `OverlayRef`.
+ * - Create / dispose the CDK `OverlayRef`. The ref is **disposed** on close and
+ *   rebuilt on the next open, so every creation-time value (`positions`,
+ *   `scrollStrategy`, `panelClass`, and the position strategy's origin) is
+ *   re-read on every open. Nothing here is frozen at first open.
  * - Attach a `ComponentPortal` and return the instance.
- * - Set up / tear down a `FocusTrap` around the overlay element.
+ * - Set up / tear down a `FocusTrap` around the overlay element, unless the
+ *   consumer opts out via `focusTrap: false`.
  * - Emit `opened$` after the enter animation completes (closes the
  *   synchronous-emit bug previously present in both pickers).
  * - Expose `backdropClick$` / `overlayKeydown$` / `escape$` streams scoped
@@ -219,7 +358,11 @@ interface PickerOpenResult<TOverlay> {
  *   never touch a detached `OverlayRef` (mirrors the S14 command-palette
  *   pattern).
  *
- * Out of scope (stays in the consuming picker):
+ * Out of scope (stays in the consuming component):
+ * - Panel width. `select` / `combobox` size their panel from a trigger
+ *   measurement that only they can make (which of several host children is the
+ *   measurable trigger differs per component), so they call
+ *   `ref()?.updateSize(...)` themselves and own their `ResizeObserver`.
  * - "Restore previous value on close" — semantics differ per picker.
  * - Per-picker portal callbacks (calendar selection, action-bar buttons).
  * - View-mode change-detection nudges (the range-picker calls
@@ -648,18 +791,6 @@ declare const tabTriggerVariants: tailwind_variants.TVReturnType<{
 }, undefined, {
     twMerge: true;
 }, unknown, unknown, undefined>>;
-/** @internal Active trigger classes for horizontal underline variants, keyed by color. */
-declare const UNDERLINE_ACTIVE_HORIZONTAL: Record<TwColor, string>;
-/** @internal Active trigger classes for vertical underline variants, keyed by color. */
-declare const UNDERLINE_ACTIVE_VERTICAL: Record<TwColor, string>;
-/** @internal Active trigger classes for horizontal enclosed variants, keyed by color. */
-declare const ENCLOSED_ACTIVE_HORIZONTAL: Record<TwColor, string>;
-/** @internal Active trigger classes for vertical enclosed variants, keyed by color. */
-declare const ENCLOSED_ACTIVE_VERTICAL: Record<TwColor, string>;
-/** @internal Active trigger classes for pill variants, keyed by color. */
-declare const PILL_ACTIVE: Record<TwColor, string>;
-/** @internal Inactive trigger classes keyed by variant. */
-declare const INACTIVE_TRIGGER_CLASSES: Record<TabTriggerVariant, string>;
 /**
  * Returns the active-state trigger class string for the given variant, color,
  * and orientation. Tab-nav callers pass `'horizontal'` since it is horizontal-only.
@@ -715,5 +846,5 @@ declare function parseField(text: string): number | null;
 /** Total seconds since midnight for a (h, m, s) tuple — useful for min/max compare. */
 declare function timeOfDaySeconds(hour: number, minute: number, second: number): number;
 
-export { AriaIdQueue, ENCLOSED_ACTIVE_HORIZONTAL, ENCLOSED_ACTIVE_VERTICAL, INACTIVE_TRIGGER_CLASSES, OVERLAY_ANIMATION_FALLBACK_PADDING, OverlayContainerCoordinator, PICKER_ENTER_DURATION, PICKER_LEAVE_DURATION, PILL_ACTIVE, PickerOverlayCoordinator, TW_ERROR_STATE_MATCHER, TW_SORT_HANDLE, UNDERLINE_ACTIVE_HORIZONTAL, UNDERLINE_ACTIVE_VERTICAL, appendDigit, buildSelectLikePositions, clamp, coerceOverlayDuration, consumeOverlayEscape, defaultErrorStateMatcher, fieldMax, fieldMin, from12h, getActiveTriggerClasses, getInactiveTriggerClasses, isTerminalDigit, mergeOverlayPanelClass, padTwo, parseField, resolveSelectScrollStrategy, stepWithWrap, tabTriggerVariants, timeOfDaySeconds, to12h };
-export type { ErrorStateMatcher, OverlayContainerAnimationEvent, OverlayContainerState, PickerOpenConfig, PickerOpenResult, RangeBehaviorConfig, SelectScrollStrategyName, TabTriggerVariant, TimePickerFormat, TimePickerMeridiem, TwBreakpoint, TwColor, TwFormSubmitted, TwOrientation, TwSize, TwSortHandle };
+export { AriaIdQueue, OVERLAY_ANIMATION_FALLBACK_PADDING, OverlayContainerCoordinator, PICKER_ENTER_DURATION, PICKER_LEAVE_DURATION, PickerOverlayCoordinator, TW_ERROR_STATE_MATCHER, TW_SORT_HANDLE, appendDigit, buildSelectLikePositions, clamp, coerceOverlayDuration, consumeOverlayEscape, defaultErrorStateMatcher, fieldMax, fieldMin, from12h, getActiveTriggerClasses, getInactiveTriggerClasses, isTerminalDigit, mergeOverlayPanelClass, padTwo, parseField, resolveSelectScrollStrategy, stepWithWrap, tabTriggerVariants, timeOfDaySeconds, to12h, wireErrorState };
+export type { ErrorStateMatcher, ErrorStateWiring, ErrorStateWiringOptions, OverlayContainerAnimationEvent, OverlayContainerState, PickerOpenConfig, PickerOpenResult, RangeBehaviorConfig, SelectScrollStrategyName, TabTriggerVariant, TimePickerFormat, TimePickerMeridiem, TwBreakpoint, TwColor, TwFormSubmitted, TwOrientation, TwSize, TwSortHandle };

package/types/cdevhub-ngx-tw-date-picker-testing.d.ts

@@ -0,0 +1,141 @@
+import { ComponentHarness, BaseHarnessFilters, HarnessPredicate } from '@angular/cdk/testing';
+import { CalendarHarness } from '@cdevhub/ngx-tw/calendar/testing';
+
+/** Filters accepted by `DatePickerHarness.with`. */
+interface DatePickerHarnessFilters extends BaseHarnessFilters {
+    /** Match by the text input's accessible name. */
+    label?: string | RegExp;
+    /** Match by the text currently displayed in the input. */
+    value?: string | RegExp;
+    /** Match disabled / enabled pickers. */
+    disabled?: boolean;
+}
+/**
+ * Harness for `tw-date-picker`.
+ *
+ * `tw-date-picker` splits its trigger across **two** elements and the
+ * distinction matters for every method here:
+ *
+ * - `input[role="combobox"]` carries the displayed text, `aria-required`,
+ *   `aria-invalid` and `aria-disabled`. `getValue`, `setValue`, `getLabel`,
+ *   `isRequired`, `isInvalid` and `isDisabled` all read it.
+ * - a sibling `button[aria-haspopup="dialog"]` opens the calendar. `open`,
+ *   `close` and `isOpen` go through it.
+ *
+ * The calendar renders into the CDK overlay, outside the `tw-date-picker`
+ * host, so it is resolved through `documentRootLocatorFactory()`. A consumer
+ * loads this harness from the ordinary fixture loader — no
+ * `documentRootLoader` ceremony required.
+ *
+ * Day-grid navigation is not reimplemented here: `getCalendar()` returns the
+ * `CalendarHarness` from `@cdevhub/ngx-tw/calendar/testing`, which already
+ * owns cells, view switching and header paging.
+ *
+ * **Not usable with a projected `[slot=trigger]`.** That opts the component out
+ * of its default chrome, so neither the text input nor the trigger button is
+ * rendered and every method here fails to resolve its element. A custom trigger
+ * is whatever the consumer projected; drive it with their own harness or a
+ * plain DOM query.
+ */
+declare class DatePickerHarness extends ComponentHarness {
+    static hostSelector: string;
+    private readonly input;
+    private readonly trigger;
+    /**
+     * The inline clear control — the only button in the default trigger chrome
+     * that is not the calendar trigger. A consumer projecting `[slot=trigger]`
+     * replaces that chrome entirely, so neither this nor `trigger` resolves then.
+     */
+    private readonly clearButton;
+    /** Resolves the overlay's calendar, which lives outside this harness's host. */
+    private readonly calendar;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: DatePickerHarnessFilters): HarnessPredicate<DatePickerHarness>;
+    /** The text input's accessible name, from `aria-label` when one is set. */
+    getLabel(): Promise<string | null>;
+    /**
+     * The formatted date currently shown in the text input. Empty string when no
+     * date is selected — the placeholder is not part of the value.
+     */
+    getValue(): Promise<string>;
+    /** The text input's `placeholder`, or `null` when none is set. */
+    getPlaceholder(): Promise<string | null>;
+    /**
+     * Types `value` into the text input and blurs, which is what commits it —
+     * `tw-date-picker` parses on blur (and on Enter), never on keystroke. An
+     * unparseable string commits `null` and puts the control in its parse-error
+     * state, exactly as it would for a user.
+     */
+    setValue(value: string): Promise<void>;
+    /** Whether the calendar overlay is open, read from the trigger's `aria-expanded`. */
+    isOpen(): Promise<boolean>;
+    /** Whether the text input reports `aria-disabled="true"`. */
+    isDisabled(): Promise<boolean>;
+    /** Whether the text input reports `aria-invalid="true"`. */
+    isInvalid(): Promise<boolean>;
+    /**
+     * Whether the text input reports `aria-required="true"`. Reflects the
+     * `required` input *and* a `Validators.required` on a bound control.
+     */
+    isRequired(): Promise<boolean>;
+    /**
+     * Opens the calendar overlay by clicking the trigger button. No-op when
+     * already open; a disabled picker ignores it, as it does in the browser.
+     */
+    open(): Promise<void>;
+    /**
+     * Closes the calendar overlay by clicking the trigger button again. No-op
+     * when already closed.
+     *
+     * Deliberately not Escape: `tw-date-picker` treats Escape as *cancel* and
+     * restores the value the overlay opened with, which would make `close()`
+     * silently undo a selection. The trigger toggles without that side effect.
+     *
+     * The overlay runs a leave animation before it detaches, so `isOpen()` flips
+     * to `false` immediately while the panel element lingers for a few more
+     * frames. Two consequences worth knowing:
+     *
+     * - Do not assert `getCalendar()` is `null` on the tick after a close; the
+     *   old panel is still mounted.
+     * - An `open()` inside that window does **not** attach a fresh panel — the
+     *   component sees an overlay ref it has not disposed yet and silently
+     *   keeps the outgoing one. Let the animation finish before reopening.
+     */
+    close(): Promise<void>;
+    /**
+     * The `CalendarHarness` for the open overlay, or `null` when no overlay is
+     * attached. Use it for anything grid-shaped — paging months, switching to the
+     * year view, reading disabled cells.
+     */
+    getCalendar(): Promise<CalendarHarness | null>;
+    /**
+     * Opens the overlay if needed and clicks the calendar cell whose text matches
+     * `day` exactly (`'15'`, not `'April 15'`). Throws when no such cell is
+     * visible in the current view.
+     *
+     * With `showActions` off this commits and closes; with it on the pick stays
+     * pending until {@link clickAction} confirms it.
+     */
+    selectDay(day: string): Promise<void>;
+    /**
+     * Clicks a button in the overlay's action bar (`Today`, `Clear`, `Cancel`,
+     * `Apply`) by its visible text. Matching on text rather than position is what
+     * keeps this usable when a consumer relabels the actions via `todayLabel` and
+     * friends — pass whatever label you configured.
+     *
+     * Preset entries are excluded: they are `role="option"`, not action buttons.
+     * Throws when the overlay is closed or nothing matches.
+     */
+    clickAction(label: string | RegExp): Promise<void>;
+    /**
+     * Whether the inline clear control is rendered. It appears only while
+     * `showClear` is on, the picker is enabled and not readonly, and a value is
+     * set.
+     */
+    hasClearButton(): Promise<boolean>;
+    /** Clicks the inline clear control. Throws when none is rendered. */
+    clear(): Promise<void>;
+}
+
+export { DatePickerHarness };
+export type { DatePickerHarnessFilters };

package/types/cdevhub-ngx-tw-date-picker.d.ts

@@ -79,23 +79,23 @@ declare class DatePickerComponent<D = Date> extends FormFieldControl<D> implemen
     readonly minDate: _angular_core.InputSignal<D | null>;
     /** Maximum selectable date. Typed input later than this commits the value and marks the bound control invalid with `calendarMaxDate`; the calendar disables the cell. Defaults to `null`. */
     readonly maxDate: _angular_core.InputSignal<D | null>;
-    /** Per-date predicate — return `false` to disable. Applied in the calendar, the text-parse path, and the `calendarDisabledDate` validation error. */
+    /** Per-date predicate — return `false` to disable. Applied in the calendar, the text-parse path, and the `calendarDisabledDate` validation error. Defaults to `null`. */
     readonly dateFilter: _angular_core.InputSignal<DateFilterFn<D> | null>;
     /** Which calendar view opens first — `'day'`, `'month'`, or `'year'`. Defaults to `'day'`. */
     readonly startView: _angular_core.InputSignal<CalendarViewState>;
-    /** Date to focus when the calendar opens with no selection. Falls back to today. */
+    /** Date to focus when the calendar opens with no selection. Falls back to today. Defaults to `null`. */
     readonly startAt: _angular_core.InputSignal<D | null>;
     /** Display format passed to `DateAdapter.format()`. With the default adapter, accepts `{ dateTimeFormat: Intl.DateTimeFormatOptions }`. When `withTime` is true and this is left at the default, hour/minute (and optional seconds) are folded in automatically. */
     readonly format: _angular_core.InputSignal<unknown>;
     /** Optional format hint passed to `DateAdapter.parse()`. Ignored by the native adapter. */
     readonly parseFormat: _angular_core.InputSignal<unknown>;
-    /** Placeholder text shown in the input when no value is entered. */
+    /** Placeholder text shown in the input when no value is entered. Defaults to `undefined`. */
     readonly placeholder: _angular_core.InputSignal<string | undefined>;
     /** When true, the input is disabled, the trigger cannot open the calendar, and `aria-disabled="true"` is set. Defaults to `false`. */
     readonly disabledInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** When true, exposes `aria-required="true"`. Validators.required on a bound NgControl is also honoured. Defaults to `false`. */
     readonly requiredInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
-    /** When true, blocks typing but still allows picking via the calendar trigger. Defaults to `false`. */
+    /** When true, blocks typing but still allows picking via the calendar trigger. Defaults to `false`. Alias: `readonly`. */
     readonly readonlyInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Trigger padding, font size, and calendar cell density. Defaults to `'md'`. */
     readonly size: _angular_core.InputSignal<TwSize>;
@@ -103,21 +103,21 @@ declare class DatePickerComponent<D = Date> extends FormFieldControl<D> implemen
     readonly color: _angular_core.InputSignal<TwColor>;
     /** Visual style of the trigger. `'default'` draws its own border; `'naked'` strips chrome. Auto-resolves to `'naked'` when inside `<tw-form-field>`. */
     readonly variant: _angular_core.InputSignal<DatePickerVariant | undefined>;
-    /** Whether to show a clear-button affordance inside the trigger when a value is set. Defaults to `true`. */
+    /** Whether to show a clear-button affordance inside the trigger when a value is set. Defaults to `true` — most form pickers expect the inline clear, matching `<tw-input>`'s clear button; without it consumers must wire one themselves. */
     readonly showClear: _angular_core.InputSignal<boolean>;
     /** When true, renders a `Today / Clear / Cancel / Apply` action bar at the bottom of the overlay. Defaults to `false`. */
     readonly showActions: _angular_core.InputSignal<boolean>;
-    /** Label for the `Today` action in the overlay's action bar. */
+    /** Label for the `Today` action in the overlay's action bar. Defaults to `'Today'`. */
     readonly todayLabel: _angular_core.InputSignal<string>;
-    /** Label for the `Clear` action in the overlay's action bar. */
+    /** Label for the `Clear` action in the overlay's action bar. Defaults to `'Clear'`. */
     readonly clearLabel: _angular_core.InputSignal<string>;
-    /** Label for the `Cancel` action in the overlay's action bar. */
+    /** Label for the `Cancel` action in the overlay's action bar. Defaults to `'Cancel'`. */
     readonly cancelLabel: _angular_core.InputSignal<string>;
-    /** Label for the `Apply` action in the overlay's action bar. */
+    /** Label for the `Apply` action in the overlay's action bar. Defaults to `'Apply'`. */
     readonly applyLabel: _angular_core.InputSignal<string>;
     /** When true, focusing the text input opens the overlay. Defaults to `false`. */
     readonly openOnFocus: _angular_core.InputSignal<boolean>;
-    /** Extra class(es) applied to the overlay panel element. */
+    /** Extra class(es) applied to the overlay panel element. Defaults to an empty string. */
     readonly panelClass: _angular_core.InputSignal<string | readonly string[]>;
     /** CDK scroll strategy for the overlay. Defaults to `'reposition'`. */
     readonly scrollStrategy: _angular_core.InputSignal<"reposition" | "close" | "block">;
@@ -125,33 +125,35 @@ declare class DatePickerComponent<D = Date> extends FormFieldControl<D> implemen
     readonly offset: _angular_core.InputSignal<number>;
     /** Accessible name for the calendar trigger button. Defaults to `'Open calendar'`. */
     readonly triggerAriaLabel: _angular_core.InputSignal<string>;
+    /** Accessible name for the inline clear button shown when a value is set. Mirrors `tw-date-range-picker`'s input of the same name; distinct from `clearLabel`, which is the overlay action bar's visible button text. Defaults to `'Clear date'`. */
+    readonly clearAriaLabel: _angular_core.InputSignal<string>;
     /**
      * Bundles the time-of-day configuration. Passing a non-null object turns on the embedded `<tw-time-picker>` and forwards each field.
      *
      * Defaults to `null` (no time field). Pass an empty object `{}` to enable the time picker with all defaults.
      */
     readonly timeConfig: _angular_core.InputSignal<DatePickerTimeConfig<D> | null>;
-    /** Per-instance locale override. Forwarded to the embedded calendar and the underlying `DateAdapter` for parse/format. Falls back to Angular `LOCALE_ID` when `null`. */
+    /** Per-instance locale override. Forwarded to the embedded calendar and the underlying `DateAdapter` for parse/format. Falls back to Angular `LOCALE_ID` when `null`. Defaults to `null`. */
     readonly locale: _angular_core.InputSignal<string | null>;
-    /** Function producing per-cell CSS classes, forwarded to the embedded calendar. Useful for visually marking special dates (holidays, billing cycles). */
+    /** Function producing per-cell CSS classes, forwarded to the embedded calendar. Useful for visually marking special dates (holidays, billing cycles). Defaults to `null`. */
     readonly dateClass: _angular_core.InputSignal<DateClassFn<D> | null>;
-    /** Optional cell-content template, forwarded to the embedded calendar. Use to customize cell visuals beyond `dateClass`. */
+    /** Optional cell-content template, forwarded to the embedded calendar. Use to customize cell visuals beyond `dateClass`. Defaults to `null`. */
     readonly cellTemplate: _angular_core.InputSignal<TemplateRef<{
         $implicit: CalendarCell<D>;
     }> | null>;
-    /** Optional quick-select presets rendered as a vertical list before the calendar. Each preset provides a `label` and a `date` factory. An empty array hides the preset panel. */
+    /** Optional quick-select presets rendered as a vertical list before the calendar. Each preset provides a `label` and a `date` factory. An empty array hides the preset panel. Defaults to an empty array. */
     readonly presets: _angular_core.InputSignal<readonly DatePickerPreset<D>[]>;
-    /** Per-instance override of the `ErrorStateMatcher`. */
+    /** Per-instance override of the `ErrorStateMatcher`. Defaults to `undefined`. */
     readonly errorStateMatcher: _angular_core.InputSignal<ErrorStateMatcher | undefined>;
-    /** Accessible name for the input. Required when no visible label is supplied. Alias: `aria-label`. */
+    /** Accessible name for the input. Required when no visible label is supplied. Alias: `aria-label`. Defaults to `undefined`. */
     readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element that labels the input. Alias: `aria-labelledby`. */
+    /** ID of an external element that labels the input. Alias: `aria-labelledby`. Defaults to `undefined`. */
     readonly ariaLabelledby: _angular_core.InputSignal<string | undefined>;
-    /** Consumer-supplied `aria-describedby` ids. The form-field preserves these when merging hint/error ids. Alias: `aria-describedby`. */
+    /** Consumer-supplied `aria-describedby` ids. The form-field preserves these when merging hint/error ids. Alias: `aria-describedby`. Defaults to `undefined`. */
     readonly userAriaDescribedByInput: _angular_core.InputSignal<string | undefined>;
-    /** Two-way bound selected date. `null` when no selection. Setting programmatically updates the display; does NOT trigger `onChange`. */
+    /** Two-way bound selected date. `null` when no selection. Setting programmatically updates the display; does NOT trigger `onChange`. Defaults to `null`. */
     readonly value: _angular_core.ModelSignal<D | null>;
-    /** Two-way bound open state of the calendar overlay. */
+    /** Two-way bound open state of the calendar overlay. Defaults to `false`. */
     readonly open: _angular_core.ModelSignal<boolean>;
     /** Fires after the overlay's enter animation completes. Payload is the trigger element. */
     readonly opened: _angular_core.OutputEmitterRef<DatePickerOpenedEvent>;
@@ -174,9 +176,6 @@ declare class DatePickerComponent<D = Date> extends FormFieldControl<D> implemen
     private readonly destroyRef;
     private readonly formField;
     private ngControl;
-    private readonly parentForm;
-    private readonly parentFormGroup;
-    private readonly defaultMatcher;
     private readonly inputRef;
     private readonly triggerRef;
     /** @internal Whether a `[slot=trigger]` is projected. Detected post-mount via DOM query so we can drop the default chrome. */
@@ -219,17 +218,17 @@ declare class DatePickerComponent<D = Date> extends FormFieldControl<D> implemen
     readonly focusedSignal: _angular_core.WritableSignal<boolean>;
     private readonly cvaDisabled;
     private readonly describedByIdsSignal;
-    private readonly closingSignal;
     private readonly lastValueBeforeOpen;
     private readonly pendingCalendarValue;
     private readonly activePresetIdSignal;
-    private readonly _ngControlRev;
-    private readonly _formSubmitRev;
+    /** @internal Shared `errorState` / `required` / `errors` derivation — see `wireErrorState`. */
+    private readonly errorWiring;
     private onChange;
     private onTouched;
-    private readonly overlayInstanceSignal;
+    private overlayInstance;
+    private closing;
     private returnFocusTo;
-    private get overlayInstance();
+    private readonly isAttached;
     /** @internal */
     readonly isDisabled: Signal<boolean>;
     /** @internal Effective variant — auto-naked when wrapped in tw-form-field. */
@@ -270,6 +269,15 @@ declare class DatePickerComponent<D = Date> extends FormFieldControl<D> implemen
     readonly required: Signal<boolean>;
     /** @internal */
     readonly errorState: Signal<boolean>;
+    /**
+     * @internal Active validation errors map from the bound `NgControl` (or `null` when the
+     * control reports none / is unbound). This is what `[twError match="…"]` filters on inside a
+     * `<tw-form-field>`; without it every `match`-targeted message — including the
+     * `calendarMinDate` / `calendarMaxDate` / `calendarDisabledDate` / `calendarInvalidValue`
+     * codes this component's `NG_VALIDATORS` apparatus exists to produce — stays permanently
+     * hidden. (Authoritative key list: `CalendarValidationErrors` in `calendar.types.ts`.)
+     */
+    readonly errors: Signal<Record<string, unknown> | null>;
     /** @internal */
     readonly controlType = "date-picker";
     /** @internal */
@@ -336,7 +344,7 @@ declare class DatePickerComponent<D = Date> extends FormFieldControl<D> implemen
     /** @internal */
     onContainerClick(event: MouseEvent): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DatePickerComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DatePickerComponent<any>, "tw-date-picker", never, { "idInput": { "alias": "id"; "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; }; "startView": { "alias": "startView"; "required": false; "isSignal": true; }; "startAt": { "alias": "startAt"; "required": false; "isSignal": true; }; "format": { "alias": "format"; "required": false; "isSignal": true; }; "parseFormat": { "alias": "parseFormat"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabledInput": { "alias": "disabled"; "required": false; "isSignal": true; }; "requiredInput": { "alias": "required"; "required": false; "isSignal": true; }; "readonlyInput": { "alias": "readonly"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "showClear": { "alias": "showClear"; "required": false; "isSignal": true; }; "showActions": { "alias": "showActions"; "required": false; "isSignal": true; }; "todayLabel": { "alias": "todayLabel"; "required": false; "isSignal": true; }; "clearLabel": { "alias": "clearLabel"; "required": false; "isSignal": true; }; "cancelLabel": { "alias": "cancelLabel"; "required": false; "isSignal": true; }; "applyLabel": { "alias": "applyLabel"; "required": false; "isSignal": true; }; "openOnFocus": { "alias": "openOnFocus"; "required": false; "isSignal": true; }; "panelClass": { "alias": "panelClass"; "required": false; "isSignal": true; }; "scrollStrategy": { "alias": "scrollStrategy"; "required": false; "isSignal": true; }; "offset": { "alias": "offset"; "required": false; "isSignal": true; }; "triggerAriaLabel": { "alias": "triggerAriaLabel"; "required": false; "isSignal": true; }; "timeConfig": { "alias": "timeConfig"; "required": false; "isSignal": true; }; "locale": { "alias": "locale"; "required": false; "isSignal": true; }; "dateClass": { "alias": "dateClass"; "required": false; "isSignal": true; }; "cellTemplate": { "alias": "cellTemplate"; "required": false; "isSignal": true; }; "presets": { "alias": "presets"; "required": false; "isSignal": true; }; "errorStateMatcher": { "alias": "errorStateMatcher"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; "ariaLabelledby": { "alias": "aria-labelledby"; "required": false; "isSignal": true; }; "userAriaDescribedByInput": { "alias": "aria-describedby"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "open": { "alias": "open"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "open": "openChange"; "opened": "opened"; "closed": "closed"; "dateInput": "dateInput"; "dateChange": "dateChange"; "presetSelected": "presetSelected"; }, never, ["[slot=trigger]", "[slot=trigger-icon]"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DatePickerComponent<any>, "tw-date-picker", never, { "idInput": { "alias": "id"; "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; }; "startView": { "alias": "startView"; "required": false; "isSignal": true; }; "startAt": { "alias": "startAt"; "required": false; "isSignal": true; }; "format": { "alias": "format"; "required": false; "isSignal": true; }; "parseFormat": { "alias": "parseFormat"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabledInput": { "alias": "disabled"; "required": false; "isSignal": true; }; "requiredInput": { "alias": "required"; "required": false; "isSignal": true; }; "readonlyInput": { "alias": "readonly"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "showClear": { "alias": "showClear"; "required": false; "isSignal": true; }; "showActions": { "alias": "showActions"; "required": false; "isSignal": true; }; "todayLabel": { "alias": "todayLabel"; "required": false; "isSignal": true; }; "clearLabel": { "alias": "clearLabel"; "required": false; "isSignal": true; }; "cancelLabel": { "alias": "cancelLabel"; "required": false; "isSignal": true; }; "applyLabel": { "alias": "applyLabel"; "required": false; "isSignal": true; }; "openOnFocus": { "alias": "openOnFocus"; "required": false; "isSignal": true; }; "panelClass": { "alias": "panelClass"; "required": false; "isSignal": true; }; "scrollStrategy": { "alias": "scrollStrategy"; "required": false; "isSignal": true; }; "offset": { "alias": "offset"; "required": false; "isSignal": true; }; "triggerAriaLabel": { "alias": "triggerAriaLabel"; "required": false; "isSignal": true; }; "clearAriaLabel": { "alias": "clearAriaLabel"; "required": false; "isSignal": true; }; "timeConfig": { "alias": "timeConfig"; "required": false; "isSignal": true; }; "locale": { "alias": "locale"; "required": false; "isSignal": true; }; "dateClass": { "alias": "dateClass"; "required": false; "isSignal": true; }; "cellTemplate": { "alias": "cellTemplate"; "required": false; "isSignal": true; }; "presets": { "alias": "presets"; "required": false; "isSignal": true; }; "errorStateMatcher": { "alias": "errorStateMatcher"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; "ariaLabelledby": { "alias": "aria-labelledby"; "required": false; "isSignal": true; }; "userAriaDescribedByInput": { "alias": "aria-describedby"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "open": { "alias": "open"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "open": "openChange"; "opened": "opened"; "closed": "closed"; "dateInput": "dateInput"; "dateChange": "dateChange"; "presetSelected": "presetSelected"; }, never, ["[slot=trigger]", "[slot=trigger-icon]"], true, never>;
 }
 
 export { DatePickerComponent };