@cdevhub/ngx-tw 0.5.0 → 0.6.0

package/fesm2022/cdevhub-ngx-tw-date-range-picker.mjs

@@ -1,12 +1,10 @@
 import * as i0 from '@angular/core';
 import { inject, ElementRef, signal, Directive, viewChild, viewChildren, computed, afterRenderEffect, ChangeDetectionStrategy, Component, input, booleanAttribute, model, output, ViewContainerRef, Injector, DestroyRef, linkedSignal, effect, untracked, afterNextRender, isDevMode, forwardRef } from '@angular/core';
-import { NgForm, FormGroupDirective, Validators, NgControl, NG_VALIDATORS, NG_VALUE_ACCESSOR } from '@angular/forms';
+import { NgControl, NG_VALIDATORS, NG_VALUE_ACCESSOR } from '@angular/forms';
 import { Overlay } from '@angular/cdk/overlay';
 import { FocusMonitor, LiveAnnouncer } from '@angular/cdk/a11y';
-import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
-import { merge } from 'rxjs';
 import { tv } from 'tailwind-variants';
-import { PickerOverlayCoordinator, TW_ERROR_STATE_MATCHER, resolveSelectScrollStrategy, buildSelectLikePositions } from '@cdevhub/ngx-tw/core';
+import { PickerOverlayCoordinator, wireErrorState, resolveSelectScrollStrategy, buildSelectLikePositions } from '@cdevhub/ngx-tw/core';
 import { FormFieldControl, TW_FORM_FIELD, TW_FORM_FIELD_CONTROL } from '@cdevhub/ngx-tw/form-field';
 import { TwDateRange, CalendarComponent, provideRangeSelectionStrategy, DATE_ADAPTER, calendarValidator } from '@cdevhub/ngx-tw/calendar';
 import { ButtonDirective } from '@cdevhub/ngx-tw/button';
@@ -74,6 +72,9 @@ class DateRangePickerOverlayComponent {
     /** @internal */
     startView = signal('day', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "startView" }] : /* istanbul ignore next */ []));
+    /** @internal Mirrors the host's `startAt`. Anchors the calendar when no range is pending. */
+    startAt = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "startAt" }] : /* istanbul ignore next */ []));
     /** @internal */
     numberOfMonths = signal(2, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "numberOfMonths" }] : /* istanbul ignore next */ []));
@@ -213,10 +214,18 @@ class DateRangePickerOverlayComponent {
         return v ? { start: v.start, end: v.end } : { start: null, end: null };
     }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "pendingRangeAsRange" }] : /* istanbul ignore next */ []));
-    /** @internal Seeds the calendar's active month on first attach so it anchors to the current value rather than today. */
+    /**
+     * @internal Seeds the calendar's active month on first attach so it anchors to
+     * the current value rather than today.
+     *
+     * A pending range wins: once the user has a selection, the calendar should
+     * follow it. `startAt` is the fallback for an empty picker, which is the case
+     * the host input exists for — it was declared but never forwarded here, so a
+     * consumer setting it got silence and the calendar always opened on today.
+     */
     initialStartAt = computed(() => {
         const v = this.pendingRange();
-        return v?.start ?? null;
+        return v?.start ?? this.startAt();
     }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "initialStartAt" }] : /* istanbul ignore next */ []));
     // ── Template handlers ──
@@ -461,7 +470,7 @@ class DateRangePickerOverlayComponent {
         </div>
       }
     </div>
-  `, isInline: true, dependencies: [{ kind: "component", type: CalendarComponent, selector: "tw-calendar", inputs: ["mode", "value", "startAt", "minDate", "maxDate", "dateFilter", "disabledDates", "disabledDaysOfWeek", "constraints", "minRangeLength", "maxRangeLength", "maxSelections", "maxSelectionBehavior", "errorAriaDescribedBy", "rangeClickBehavior", "rangeBehavior", "dateClass", "bordered", "startView", "firstDayOfWeek", "monthColumns", "disabled", "readonly", "resetBehavior", "cellTemplate", "locale", "intl"], outputs: ["valueChange", "selectionStart", "rangePreview", "selectionComplete", "selectionRestart", "selectionCleared", "selectionLimitReached", "presetChange", "viewChange", "activeDateChange", "monthChange", "yearChange", "cellClick", "cellHover", "modeChange"] }, { kind: "component", type: TimePickerComponent, selector: "tw-time-picker", inputs: ["id", "disabled", "required", "readonly", "size", "color", "variant", "format", "showSeconds", "hourStep", "minuteStep", "secondStep", "minTime", "maxTime", "referenceDate", "placeholder", "showSteppers", "showClear", "clearLabel", "errorStateMatcher", "aria-label", "aria-labelledby", "aria-describedby", "value"], outputs: ["valueChange", "timeInput", "timeChange"] }, { kind: "directive", type: ButtonDirective, selector: "[twButton]", inputs: ["variant", "color", "size", "disabled", "loading"], exportAs: ["twButton"] }, { kind: "directive", type: DateRangePresetOptionDirective, selector: "button[twDateRangePresetOption]" }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+  `, isInline: true, dependencies: [{ kind: "component", type: CalendarComponent, selector: "tw-calendar", inputs: ["mode", "value", "startAt", "minDate", "maxDate", "dateFilter", "disabledDates", "disabledDaysOfWeek", "constraints", "minRangeLength", "maxRangeLength", "maxSelections", "maxSelectionBehavior", "errorAriaDescribedBy", "aria-describedby", "rangeClickBehavior", "rangeBehavior", "dateClass", "bordered", "startView", "firstDayOfWeek", "monthColumns", "disabled", "readonly", "resetBehavior", "cellTemplate", "locale", "intl"], outputs: ["valueChange", "selectionStart", "rangePreview", "selectionComplete", "selectionRestart", "selectionCleared", "selectionLimitReached", "presetChange", "viewChange", "activeDateChange", "monthChange", "yearChange", "cellClick", "cellHover", "modeChange"] }, { kind: "component", type: TimePickerComponent, selector: "tw-time-picker", inputs: ["id", "disabled", "required", "readonly", "size", "color", "variant", "format", "showSeconds", "hourStep", "minuteStep", "secondStep", "minTime", "maxTime", "referenceDate", "placeholder", "showSteppers", "showClear", "clearLabel", "errorStateMatcher", "aria-label", "aria-labelledby", "aria-describedby", "value"], outputs: ["valueChange", "timeInput", "timeChange"] }, { kind: "directive", type: ButtonDirective, selector: "[twButton]", inputs: ["variant", "color", "size", "disabled", "loading"], exportAs: ["twButton"] }, { kind: "directive", type: DateRangePresetOptionDirective, selector: "button[twDateRangePresetOption]" }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: DateRangePickerOverlayComponent, decorators: [{
             type: Component,
@@ -626,7 +635,11 @@ function rangesEqual(a, b, adapter) {
 const dateRangePickerVariants = tv({
     slots: {
         root: 'relative inline-flex items-center w-full text-fg transition-[color,border-color,box-shadow] duration-normal motion-reduce:transition-none',
-        trigger: 'flex-1 inline-flex items-center gap-2 min-w-0 bg-transparent text-left text-fg outline-none border-0 p-0 m-0 cursor-pointer focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500 disabled:cursor-not-allowed',
+        // `self-stretch` so the trigger — the component's only interactive surface —
+        // fills the pinned control height. Without it the button is exactly its line
+        // box tall and everything above/below it inside the shell is dead click area
+        // (up to 22px at xl).
+        trigger: 'flex-1 inline-flex items-center gap-2 min-w-0 self-stretch bg-transparent text-left text-fg outline-none border-0 p-0 m-0 cursor-pointer focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500 disabled:cursor-not-allowed',
         startText: 'truncate',
         separator: 'shrink-0 text-fg-subtle',
         endText: 'truncate',
@@ -634,6 +647,11 @@ const dateRangePickerVariants = tv({
         triggerIconWrapper: 'inline-flex items-center justify-center shrink-0 text-fg-muted',
         triggerIcon: 'shrink-0 text-fg-muted transition-colors duration-normal motion-reduce:transition-none',
         // size-6 (24×24 CSS px) is the WCAG AA minimum interactive target — bumping past size-5 keeps the affordance hittable without growing the inline row.
+        // Held flat across every size. It fits the 30/34/42/46px content boxes at sm..xl. At xs the
+        // pinned root is h-6 (24px border-box) so its content box is only 22px: the button is kept at
+        // 24×24 anyway — docs/vertical-rhythm.md calls 24px a hard floor — and therefore coincides with
+        // the root's *border*-box, overlapping the 1px border row top and bottom. The root's height is
+        // unaffected (h-6 is a definite height); only the hover fill meets the border at that density.
         clearButton: 'inline-flex items-center justify-center shrink-0 rounded-md text-fg-muted hover:text-fg hover:bg-surface-muted transition-colors duration-normal motion-reduce:transition-none size-6 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500',
     },
     variants: {
@@ -663,7 +681,10 @@ const dateRangePickerVariants = tv({
         },
         variant: {
             default: {
-                root: 'rounded-md border border-border bg-surface px-3 py-2 hover:border-border-strong',
+                // No `py-*`: the height is pinned per size in compoundVariants below.
+                // See docs/vertical-rhythm.md §3 — padding and a pinned height fight,
+                // and under border-box the taller one silently wins.
+                root: 'rounded-md border border-border bg-surface px-3 hover:border-border-strong',
             },
             naked: {
                 root: 'bg-transparent border-0 rounded-none p-0 focus-within:outline-none',
@@ -688,6 +709,16 @@ const dateRangePickerVariants = tv({
         },
     },
     compoundVariants: [
+        // ── Pinned control height (docs/vertical-rhythm.md §1) ──
+        // Only the `default` variant carries a height. `naked` means somebody else
+        // owns the box — `<tw-form-field>` auto-nakeds this picker and supplies its
+        // own bordered, padded controlWrapper, so pinning naked would stack 36px on
+        // top of the form-field's `py-2` and inflate a wrapped picker at every size.
+        { variant: 'default', size: 'xs', class: { root: 'h-6' } },
+        { variant: 'default', size: 'sm', class: { root: 'h-8' } },
+        { variant: 'default', size: 'md', class: { root: 'h-9' } },
+        { variant: 'default', size: 'lg', class: { root: 'h-11' } },
+        { variant: 'default', size: 'xl', class: { root: 'h-12' } },
         { variant: 'default', focused: true, color: 'primary', class: { root: 'border-primary-500' } },
         { variant: 'default', focused: true, color: 'secondary', class: { root: 'border-secondary-500' } },
         { variant: 'default', focused: true, color: 'accent', class: { root: 'border-accent-500' } },
@@ -732,13 +763,13 @@ class DateRangePickerComponent extends FormFieldControl {
     /** Latest selectable date for either endpoint. Presets and calendar cells later than this are rejected or disabled. Defaults to `null`. */
     maxDate = input(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "maxDate" }] : /* istanbul ignore next */ []));
-    /** Per-date predicate — return `false` to disable. Applied in both calendars. Presets that fall on a filtered date are skipped. */
+    /** Per-date predicate — return `false` to disable. Applied in both calendars. Presets that fall on a filtered date are skipped. Defaults to `null`. */
     dateFilter = input(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "dateFilter" }] : /* istanbul ignore next */ []));
     /** Which calendar view opens first — `'day'`, `'month'`, or `'year'`. Defaults to `'day'`. */
     startView = input('day', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "startView" }] : /* istanbul ignore next */ []));
-    /** Date the left calendar focuses on when opened with no value. Falls back to today. Ignored when a value is already set. */
+    /** Date the left calendar focuses on when opened with no value. Falls back to today. Ignored when a value is already set. Defaults to `null`. */
     startAt = input(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "startAt" }] : /* istanbul ignore next */ []));
     /** Display format for each endpoint, passed to `DateAdapter.format()`. When `showTime` is true and this is left at the default, hour/minute (and optional seconds) are folded in automatically. */
@@ -747,13 +778,13 @@ class DateRangePickerComponent extends FormFieldControl {
     /** Separator rendered between the two formatted endpoints in the trigger. Defaults to `" – "`. */
     rangeSeparator = input(' – ', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "rangeSeparator" }] : /* istanbul ignore next */ []));
-    /** Placeholder text shown in the trigger for an empty `start` endpoint. */
+    /** Placeholder text shown in the trigger for an empty `start` endpoint. Defaults to `'Start date'`. */
     emptyStartLabel = input('Start date', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "emptyStartLabel" }] : /* istanbul ignore next */ []));
-    /** Placeholder text shown in the trigger for an empty `end` endpoint. */
+    /** Placeholder text shown in the trigger for an empty `end` endpoint. Defaults to `'End date'`. */
     emptyEndLabel = input('End date', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "emptyEndLabel" }] : /* istanbul ignore next */ []));
-    /** When set, overrides the composed `${emptyStartLabel}${rangeSeparator}${emptyEndLabel}` placeholder with a single string. */
+    /** When set, overrides the composed `${emptyStartLabel}${rangeSeparator}${emptyEndLabel}` placeholder with a single string. Defaults to `undefined`. */
     placeholder = input(undefined, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "placeholder" }] : /* istanbul ignore next */ []));
     /** When true, the trigger cannot open the overlay and `aria-disabled="true"` is set. Defaults to `false`. */
@@ -774,11 +805,10 @@ class DateRangePickerComponent extends FormFieldControl {
     /** How many months the overlay shows side-by-side. `2` is the standard range-picker layout; use `1` for compact contexts. Defaults to `2`. */
     numberOfMonths = input(2, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "numberOfMonths" }] : /* istanbul ignore next */ []));
-    /** Optional quick-select presets rendered as a vertical list before the calendars. Each preset provides a label and a factory returning a `TwDateRange<D>`. An empty array hides the preset panel. */
+    /** Optional quick-select presets rendered as a vertical list before the calendars. Each preset provides a label and a factory returning a `TwDateRange<D>`. An empty array hides the preset panel. Defaults to an empty array. */
     presets = input([], /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "presets" }] : /* istanbul ignore next */ []));
-    /** Whether to show a clear-button affordance inside the trigger when a value is set. Defaults to `true`. */
-    // TRUE-default: a picker without a clear affordance forces consumers to wire one — most form pickers expect the inline clear, matching `<tw-input>`'s clear button.
+    /** 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. */
     showClear = input(true, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "showClear" }] : /* istanbul ignore next */ []));
     /** Minimum range length in days, inclusive. Commits shorter than this are rejected and surface `calendarRangeTooShort` on the bound `NgControl`. `null` = no minimum. Defaults to `null`. */
@@ -800,13 +830,13 @@ class DateRangePickerComponent extends FormFieldControl {
     /** Override first day of week (0=Sun, 1=Mon) on the embedded calendar. Falls back to the adapter's default. */
     firstDayOfWeek = input(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "firstDayOfWeek" }] : /* istanbul ignore next */ []));
-    /** Per-instance locale override. Forwarded to the embedded calendar and the underlying `DateAdapter` so the trigger display tracks the picker's locale. Falls back to Angular `LOCALE_ID` when `null`. */
+    /** Per-instance locale override. Forwarded to the embedded calendar and the underlying `DateAdapter` so the trigger display tracks the picker's locale. Falls back to Angular `LOCALE_ID` when `null`. Defaults to `null`. */
     locale = input(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "locale" }] : /* istanbul ignore next */ []));
-    /** Function producing per-cell CSS classes on the embedded calendar. */
+    /** Function producing per-cell CSS classes on the embedded calendar. Defaults to `null`. */
     dateClass = input(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "dateClass" }] : /* istanbul ignore next */ []));
-    /** 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`. */
     cellTemplate = input(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "cellTemplate" }] : /* istanbul ignore next */ []));
     /** When true, renders a `Today / Clear / Cancel / Apply` action bar at the bottom of the overlay. The calendar commits on the second click by default — turn this on for touch-heavy contexts. Defaults to `false`. */
@@ -830,19 +860,19 @@ class DateRangePickerComponent extends FormFieldControl {
     /** Step for the embedded time-pickers' second fields. Defaults to `1`. */
     secondStep = input(1, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "secondStep" }] : /* istanbul ignore next */ []));
-    /** 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'`. */
     todayLabel = input('Today', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "todayLabel" }] : /* istanbul ignore next */ []));
-    /** 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'`. */
     clearLabel = input('Clear', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "clearLabel" }] : /* istanbul ignore next */ []));
-    /** 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'`. */
     cancelLabel = input('Cancel', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "cancelLabel" }] : /* istanbul ignore next */ []));
-    /** 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'`. */
     applyLabel = input('Apply', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "applyLabel" }] : /* istanbul ignore next */ []));
-    /** Extra class(es) applied to the overlay panel element. `twMerge` resolves conflicts with internal classes. */
+    /** Extra class(es) applied to the overlay panel element. `twMerge` resolves conflicts with internal classes. Defaults to an empty string. */
     panelClass = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "panelClass" }] : /* istanbul ignore next */ []));
     /** CDK scroll strategy for the overlay. Defaults to `'reposition'`. */
@@ -854,20 +884,20 @@ class DateRangePickerComponent extends FormFieldControl {
     /** Accessible label for the clear button. Defaults to `'Clear date range'`. */
     clearAriaLabel = input('Clear date range', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "clearAriaLabel" }] : /* istanbul ignore next */ []));
-    /** Per-instance override of the `ErrorStateMatcher`. When omitted, uses the injected `TW_ERROR_STATE_MATCHER`. */
+    /** Per-instance override of the `ErrorStateMatcher`. When omitted, uses the injected `TW_ERROR_STATE_MATCHER`. Defaults to `undefined`. */
     errorStateMatcher = input(undefined, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "errorStateMatcher" }] : /* istanbul ignore next */ []));
-    /** Accessible name for the trigger. Required when no visible label is supplied via `tw-form-field` or an external `aria-labelledby`. Alias: `aria-label`. */
+    /** Accessible name for the trigger. Required when no visible label is supplied via `tw-form-field` or an external `aria-labelledby`. Alias: `aria-label`. Defaults to `undefined`. */
     ariaLabel = input(undefined, { ...(ngDevMode ? { debugName: "ariaLabel" } : /* istanbul ignore next */ {}), alias: 'aria-label' });
-    /** ID of an external element that labels the trigger. Alias: `aria-labelledby`. */
+    /** ID of an external element that labels the trigger. Alias: `aria-labelledby`. Defaults to `undefined`. */
     ariaLabelledby = input(undefined, { ...(ngDevMode ? { debugName: "ariaLabelledby" } : /* istanbul ignore next */ {}), alias: 'aria-labelledby' });
-    /** 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`. */
     userAriaDescribedByInput = input(undefined, { ...(ngDevMode ? { debugName: "userAriaDescribedByInput" } : /* istanbul ignore next */ {}), alias: 'aria-describedby' });
     // ── Models (two-way) ──
-    /** Two-way bound selected range. `null` when no selection. Setting programmatically updates the trigger display and the calendar selection; it does NOT trigger `onChange`. */
+    /** Two-way bound selected range. `null` when no selection. Setting programmatically updates the trigger display and the calendar selection; it does NOT trigger `onChange`. Defaults to `null`. */
     value = model(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "value" }] : /* istanbul ignore next */ []));
-    /** Two-way bound open state of the overlay. Setting to `true` opens; setting to `false` closes. */
+    /** Two-way bound open state of the overlay. Setting to `true` opens; setting to `false` closes. Defaults to `false`. */
     open = model(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "open" }] : /* istanbul ignore next */ []));
     // ── Outputs ──
@@ -895,9 +925,6 @@ class DateRangePickerComponent extends FormFieldControl {
     // constructor pulls the validator set — eager `inject(NgControl, {self})`
     // would resolve to this component while it is still being created).
     ngControl = null;
-    parentForm = inject(NgForm, { optional: true });
-    parentFormGroup = inject(FormGroupDirective, { optional: true });
-    defaultMatcher = inject(TW_ERROR_STATE_MATCHER);
     // ── View refs ──
     triggerRef = viewChild.required('trigger', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "triggerRef" }] : /* istanbul ignore next */ []));
@@ -924,29 +951,41 @@ class DateRangePickerComponent extends FormFieldControl {
     ...(ngDevMode ? [{ debugName: "cvaDisabled" }] : /* istanbul ignore next */ []));
     describedByIdsSignal = signal([], /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "describedByIdsSignal" }] : /* istanbul ignore next */ []));
-    closingSignal = signal(false, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "closingSignal" }] : /* istanbul ignore next */ []));
     lastValueBeforeOpen = signal(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "lastValueBeforeOpen" }] : /* istanbul ignore next */ []));
     pendingRange = signal(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "pendingRange" }] : /* istanbul ignore next */ []));
     currentView = signal('day', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "currentView" }] : /* istanbul ignore next */ []));
-    _ngControlRev = signal(0, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "_ngControlRev" }] : /* istanbul ignore next */ []));
-    _formSubmitRev = signal(0, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "_formSubmitRev" }] : /* istanbul ignore next */ []));
+    /** @internal Shared `errorState` / `required` / `errors` derivation — see `wireErrorState`. */
+    errorWiring = wireErrorState({
+        ngControl: () => this.ngControl,
+        matcher: () => this.errorStateMatcher(),
+        required: () => this.requiredInput(),
+        track: [() => this.focusedSignal()],
+        // An unparseable entry or an out-of-range date is an error regardless of validator status.
+        errorStateOverride: () => (this.parseError() || this.rangeError() ? true : undefined),
+    });
     onChange = () => { };
     onTouched = () => { };
-    overlayInstanceSignal = signal(null, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "overlayInstanceSignal" }] : /* istanbul ignore next */ []));
-    get overlayInstance() {
-        return this.overlayInstanceSignal();
-    }
+    // Overlay lifecycle bookkeeping. Both are PLAIN FIELDS, not signals, and that
+    // is load-bearing: the lifecycle effect in the constructor both reads and
+    // writes them, so as signals they would form a read → write → re-trigger
+    // cycle of exactly the shape CLAUDE.md forbids. Demoting them is the fix
+    // `popover.ts` and `command-palette.ts` already use — see the comment on that
+    // effect. Do not promote either back to `signal()`.
+    overlayInstance = null;
+    closing = false;
+    // The one piece of overlay state that must stay a signal: it is the *only*
+    // dependency that re-runs the overlay state-push effect when the panel
+    // attaches. Written in openOverlay / closeOverlay, never read by the
+    // lifecycle effect, so it cannot cycle. Mirrors `command-palette.ts`.
+    isAttached = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "isAttached" }] : /* istanbul ignore next */ []));
     // ── Derived state ──
     /** @internal */
     isDisabled = computed(() => {
-        this._ngControlRev();
+        this.errorWiring.rev();
         return this.disabledInput() || this.cvaDisabled() || !!this.ngControl?.disabled;
     }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "isDisabled" }] : /* istanbul ignore next */ []));
@@ -1106,26 +1145,19 @@ class DateRangePickerComponent extends FormFieldControl {
     /** @internal */
     disabled = this.isDisabled;
     /** @internal */
-    required = computed(() => {
-        this._ngControlRev();
-        if (this.requiredInput())
-            return true;
-        return !!this.ngControl?.control?.hasValidator(Validators.required);
-    }, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "required" }] : /* istanbul ignore next */ []));
-    /** @internal */
-    errorState = computed(() => {
-        this._ngControlRev();
-        this._formSubmitRev();
-        this.focusedSignal();
-        if (this.parseError() || this.rangeError())
-            return true;
-        const matcher = this.errorStateMatcher() ?? this.defaultMatcher;
-        const form = this.parentFormGroup ??
-            this.parentForm;
-        return matcher.isErrorState(this.ngControl?.control ?? null, form);
-    }, /* @ts-ignore */
-    ...(ngDevMode ? [{ debugName: "errorState" }] : /* istanbul ignore next */ []));
+    required = this.errorWiring.required;
+    /** @internal */
+    errorState = this.errorWiring.errorState;
+    /**
+     * @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` / `calendarInvalidRange` / `calendarRangeTooShort` /
+     * `calendarRangeTooLong` codes this component's `NG_VALIDATORS` apparatus exists to produce —
+     * stays permanently hidden. (Authoritative key list: `CalendarValidationErrors` in
+     * `calendar.types.ts`.)
+     */
+    errors = this.errorWiring.errors;
     /** @internal */
     controlType = 'date-range-picker';
     /** @internal */
@@ -1135,24 +1167,54 @@ class DateRangePickerComponent extends FormFieldControl {
     constructor() {
         super();
         // Mirror the `open` model into the overlay lifecycle.
+        //
+        // The only tracked reads here are `open()` and `isDisabled()`. Everything
+        // this effect *writes* — `overlayInstance`, `closing` — is a plain field,
+        // never a signal, so opening or closing cannot re-trigger the effect that
+        // ordered it. That is the whole reason those two are declared as fields
+        // (see their declaration); promoting either back to `signal()` recreates
+        // the read → write → re-trigger cycle CLAUDE.md forbids.
+        //
+        // `openOverlay()` / `closeOverlay()` do write `isAttached`, but this effect
+        // never reads it, so that write is a one-way hand-off to the state-push
+        // effect below and terminates there.
+        //
+        // The body is wrapped in `untracked()` because demoting the two fields is
+        // NOT sufficient on its own. `openOverlay()` reads roughly twenty-five
+        // inputs while pushing them into the freshly attached panel, and it writes
+        // two signals it then reads straight back. Called from the tracked phase,
+        // every one of those reads becomes a dependency of THIS effect, which both
+        // recreates the forbidden write-then-read-back shape and re-runs the whole
+        // lifecycle on any of those twenty-five inputs changing. Tracked reads are
+        // now exactly `open()` and `isDisabled()`, which is what the paragraph
+        // above claims — and only now true.
         effect(() => {
             const shouldOpen = this.open();
             const disabled = this.isDisabled();
-            if (disabled && this.overlayInstance) {
-                this.closeOverlay('programmatic');
-                return;
-            }
-            if (shouldOpen && !this.overlayInstance && !disabled && !this.closingSignal()) {
-                this.openOverlay();
-            }
-            else if (!shouldOpen && this.overlayInstance && !this.closingSignal()) {
-                this.closeOverlay('programmatic');
-            }
+            untracked(() => {
+                if (disabled && this.overlayInstance) {
+                    this.closeOverlay('programmatic');
+                    return;
+                }
+                if (shouldOpen && !this.overlayInstance && !disabled && !this.closing) {
+                    this.openOverlay();
+                }
+                else if (!shouldOpen && this.overlayInstance && !this.closing) {
+                    this.closeOverlay('programmatic');
+                }
+            });
         });
         // Push config into the overlay whenever anything relevant changes.
         // Reads happen in the tracked phase; writes to the overlay instance are
         // wrapped in `untracked()` so they never feed back into this effect.
+        //
+        // `isAttached()` MUST be read first and unconditionally: it is this
+        // effect's only dependency on the overlay's existence, so it is what makes
+        // the initial push happen when the panel attaches (`overlayInstance` is a
+        // plain field and is invisible to the signal graph). Do not reorder it
+        // behind the null check — the effect would then never re-run on open.
         effect(() => {
+            this.isAttached();
             const instance = this.overlayInstance;
             if (!instance)
                 return;
@@ -1162,6 +1224,7 @@ class DateRangePickerComponent extends FormFieldControl {
             const maxDate = this.maxDate();
             const dateFilter = this.dateFilter();
             const startView = this.startView();
+            const startAt = this.startAt();
             const numberOfMonths = this.numberOfMonths();
             const pendingRange = this.pendingRange();
             const currentView = this.currentView();
@@ -1196,6 +1259,7 @@ class DateRangePickerComponent extends FormFieldControl {
                 instance.maxDate.set(maxDate);
                 instance.dateFilter.set(dateFilter);
                 instance.startView.set(startView);
+                instance.startAt.set(startAt);
                 instance.numberOfMonths.set(numberOfMonths);
                 instance.pendingRange.set(pendingRange);
                 instance.currentView.set(currentView);
@@ -1263,15 +1327,16 @@ class DateRangePickerComponent extends FormFieldControl {
             this.focusedSignal.set(!!origin);
             if (wasFocused && !origin) {
                 this.onTouched();
-                this._ngControlRev.update((n) => n + 1);
+                this.errorWiring.bump();
             }
         });
         this.destroyRef.onDestroy(() => {
             monitorSub.unsubscribe();
             this.focusMonitor.stopMonitoring(this.elementRef);
             // The coordinator's own DestroyRef.onDestroy disposes the overlay and
-            // clears its timers; we only need to drop the local instance signal.
-            this.overlayInstanceSignal.set(null);
+            // clears its timers; we only need to drop the local instance reference.
+            this.overlayInstance = null;
+            this.isAttached.set(false);
         });
     }
     ngOnInit() {
@@ -1281,27 +1346,33 @@ class DateRangePickerComponent extends FormFieldControl {
             self: true,
             optional: true,
         });
-        // Wire this component as the NgControl's value accessor. NG_VALUE_ACCESSOR
-        // is not registered as a provider to keep `inject(NgControl, { self })`
-        // possible — we assign it here instead.
-        if (this.ngControl) {
-            this.ngControl.valueAccessor = this;
-        }
-        const ctrl = this.ngControl?.control;
-        if (ctrl) {
-            const streams = [ctrl.statusChanges, ctrl.valueChanges].filter((s) => !!s);
-            if (streams.length) {
-                merge(...streams)
-                    .pipe(takeUntilDestroyed(this.destroyRef))
-                    .subscribe(() => this._ngControlRev.update((n) => n + 1));
-            }
-        }
-        const submit = this.parentFormGroup?.ngSubmit ?? this.parentForm?.ngSubmit;
-        if (submit) {
-            submit
-                .pipe(takeUntilDestroyed(this.destroyRef))
-                .subscribe(() => this._formSubmitRev.update((n) => n + 1));
-        }
+        // There is deliberately NO `ngControl.valueAccessor = this` here, and none is needed:
+        // registration happens through the static NG_VALUE_ACCESSOR provider on this component,
+        // which `FormControlName` / `NgModel` resolve while constructing on the same element —
+        // long before ngOnInit. An assignment at this point would be a pure no-op on both the
+        // classic and the signal-forms path.
+        //
+        // Do NOT read the absence of a runtime assignment as evidence the static provider is
+        // optional. It is the only registration this component has: delete it and `validate()`
+        // is never invoked, so every calendar error code silently disappears with no test failure
+        // outside the guard spec. See the provider's own comment above.
+        //
+        // Bump the revision so any control-derived signal that was already read while
+        // `ngControl` was still `null` recomputes. `date-picker` and `time-picker` have
+        // always done this; this component's omission was an asymmetry preserved
+        // verbatim through the `wireErrorState` extraction.
+        //
+        // Honest scope, measured rather than assumed: **no test distinguishes this
+        // line.** Removing it leaves the whole suite green, including the
+        // `aria-required from the bound control` guard below. `required` and its
+        // siblings are `computed()`, and a `computed()` is lazy — nothing reads them
+        // before `ngOnInit` runs, so in every path exercised today there is no stale
+        // cache to invalidate and the bump is a no-op. It is kept for symmetry with
+        // the two sibling pickers, and as a guard against a future eager read (a
+        // parent querying `required` during its own first pass would cache the
+        // `null`-era answer permanently). Do not cite it as a bug fix.
+        this.errorWiring.bump();
+        this.errorWiring.connect();
     }
     // ── Public imperative API ──
     /** Opens the overlay. No-op when disabled or already open. */
@@ -1524,7 +1595,10 @@ class DateRangePickerComponent extends FormFieldControl {
         instance.locale.set(this.locale());
         instance.dateClass.set(this.dateClass());
         instance.cellTemplate.set(this.cellTemplate());
-        this.overlayInstanceSignal.set(instance);
+        this.overlayInstance = instance;
+        // Must follow the assignment above: this is what wakes the state-push
+        // effect, and it reads `overlayInstance` as a plain field.
+        this.isAttached.set(true);
         // Flush the initial config into the overlay's first render so view children
         // (calendar, time pickers, action bar) observe the picker's current inputs.
         result.componentRef.changeDetectorRef.detectChanges();
@@ -1553,9 +1627,9 @@ class DateRangePickerComponent extends FormFieldControl {
         });
     }
     closeOverlay(reason, restore = false) {
-        if (this.closingSignal() || !this.overlayInstance)
+        if (this.closing || !this.overlayInstance)
             return;
-        this.closingSignal.set(true);
+        this.closing = true;
         this.overlayInstance.leaving.set(true);
         if (restore) {
             const previous = this.lastValueBeforeOpen();
@@ -1569,10 +1643,11 @@ class DateRangePickerComponent extends FormFieldControl {
         }
         this.triggerRef().nativeElement.focus();
         this.coordinator.close(() => {
-            this.overlayInstanceSignal.set(null);
+            this.overlayInstance = null;
+            this.isAttached.set(false);
             this.pendingRange.set(null);
             untracked(() => this.open.set(false));
-            this.closingSignal.set(false);
+            this.closing = false;
             this.closed.emit(reason);
         });
     }
@@ -1818,7 +1893,7 @@ class DateRangePickerComponent extends FormFieldControl {
       [attr.aria-label]="triggerAccessibleName() || null"
       [attr.aria-labelledby]="ariaLabelledby() || null"
       [attr.aria-describedby]="describedBy() || null"
-      [attr.aria-required]="requiredInput() || null"
+      [attr.aria-required]="required() || null"
       [attr.aria-invalid]="errorState() || null"
       [attr.aria-disabled]="isDisabled() || null"
       [attr.data-variant]="resolvedVariant()"
@@ -1917,7 +1992,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
       [attr.aria-label]="triggerAccessibleName() || null"
       [attr.aria-labelledby]="ariaLabelledby() || null"
       [attr.aria-describedby]="describedBy() || null"
-      [attr.aria-required]="requiredInput() || null"
+      [attr.aria-required]="required() || null"
       [attr.aria-invalid]="errorState() || null"
       [attr.aria-disabled]="isDisabled() || null"
       [attr.data-variant]="resolvedVariant()"