@cdevhub/ngx-tw 0.5.0 → 0.6.0

package/fesm2022/cdevhub-ngx-tw-time-picker.mjs

@@ -1,11 +1,9 @@
 import * as i0 from '@angular/core';
 import { Injectable, input, booleanAttribute, model, output, inject, ElementRef, DestroyRef, Injector, viewChild, signal, linkedSignal, computed, effect, untracked, afterNextRender, isDevMode, forwardRef, ChangeDetectionStrategy, Component } 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 { FocusMonitor, LiveAnnouncer } from '@angular/cdk/a11y';
-import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
-import { merge } from 'rxjs';
 import { tv } from 'tailwind-variants';
-import { TW_ERROR_STATE_MATCHER, fieldMin, fieldMax, parseField, padTwo, to12h, appendDigit, isTerminalDigit, stepWithWrap, from12h, timeOfDaySeconds, clamp } from '@cdevhub/ngx-tw/core';
+import { wireErrorState, fieldMin, fieldMax, parseField, padTwo, to12h, appendDigit, isTerminalDigit, stepWithWrap, from12h, timeOfDaySeconds, clamp } from '@cdevhub/ngx-tw/core';
 import { FormFieldControl, TW_FORM_FIELD, TW_FORM_FIELD_CONTROL } from '@cdevhub/ngx-tw/form-field';
 import { DATE_ADAPTER } from '@cdevhub/ngx-tw/calendar';
 
@@ -81,11 +79,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
  *   }),
  * ]
  * ```
+ *
+ * Keys explicitly set to `undefined` are dropped before merging. Root
+ * `tsconfig.json` does not set `exactOptionalPropertyTypes`, so
+ * `provideTimePickerIntl({ hoursLabel: bundle['time.hours'] })` type-checks
+ * even when the lookup misses — and a plain `Object.assign` would then copy
+ * that `undefined` over a field `TimePickerIntl` types as `string`. Because
+ * this is a bootstrap-level provider, one missing key broke *every*
+ * time-picker in the app: `focusedFieldLabel()` calls `.toLowerCase()` on the
+ * field labels to build the stepper aria-labels, so the picker threw on first
+ * render. Filtering here makes a missing key fall back to the English default.
  */
 function provideTimePickerIntl(custom) {
     return {
         provide: TimePickerIntl,
-        useFactory: () => Object.assign(new TimePickerIntl(), custom),
+        useFactory: () => {
+            const overrides = Object.fromEntries(Object.entries(custom ?? {}).filter(([, value]) => value !== undefined));
+            return Object.assign(new TimePickerIntl(), overrides);
+        },
     };
 }
 
@@ -109,11 +120,21 @@ const timePickerVariants = tv({
         // as the equivalent-control exception applies — the time is fully editable
         // by typing into the spinbutton fields (and via ↑/↓), so the spinner is a
         // pointer enhancement, never the only path.
+        //
+        // That min-content floor is also why the column is suppressed at
+        // `size="xs"` + `variant="default"`: a pinned h-6 root leaves a 22px content
+        // box, below the stacked pair's 24px floor. See `steppersVisible` below.
         stepperGroup: 'flex flex-col self-stretch ml-0.5',
         stepper: 'flex-1 inline-flex items-center justify-center text-fg-muted hover:text-fg hover:bg-surface-muted rounded-md transition-colors duration-normal motion-reduce:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500 disabled:opacity-40 disabled:pointer-events-none',
         stepperIcon: '',
         meridiem: 'inline-flex items-center rounded-md border border-border overflow-hidden ml-2 shrink-0',
         meridiemButton: 'font-medium text-fg-muted hover:bg-surface-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500 transition-colors duration-normal motion-reduce:transition-none disabled:opacity-40 disabled:pointer-events-none',
+        // size-6 (24×24 CSS px) is the WCAG 2.2 SC 2.5.8 minimum interactive target, 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 stays 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 ml-1 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500',
     },
     variants: {
@@ -126,6 +147,13 @@ const timePickerVariants = tv({
                 field: 'w-5 text-xs',
                 stepper: 'w-6',
                 stepperIcon: 'size-3',
+                // `border-0` on the AM/PM shell only at xs. With its 1px border the pair
+                // measures 26px, which cannot sit inside the 22px content box of a pinned
+                // h-6 root. Dropping the shell border lets each radio keep the full 24px
+                // WCAG 2.2 SC 2.5.8 target height and makes the pair coincide with the
+                // root's border-box. The pair stays legible without the shell because the
+                // selected half always carries a solid `bg-{color}-500` fill.
+                meridiem: 'border-0',
                 meridiemButton: 'px-1.5 py-1 text-2xs',
             },
             sm: {
@@ -163,7 +191,10 @@ const timePickerVariants = 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',
@@ -187,6 +218,17 @@ const timePickerVariants = 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, and both `<tw-date-picker>` and
+        // `<tw-date-range-picker>` embed a naked time-picker in their overlay footer.
+        // Pinning naked would stack 36px on top of those hosts' own padding.
+        { 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' } },
@@ -209,20 +251,30 @@ const timePickerVariants = tv({
 // ── Static active-state color lookup for the AM/PM meridiem button ─────────────
 // Each entry is written out so Tailwind v4's static scanner picks the classes up.
 // Mirrors the lookup-table pattern used by `checkbox.ts` and `radio.ts`.
+//
+// Every entry uses the `{role}-solid` / `-solid-fg` / `-solid-hover` slot trio,
+// which the theme layer picks specifically so the label reaches AA on the fill
+// (see the light-mode contrast table in `theme/_semantic.css`). The previous
+// `bg-{role}-500 text-on-{role}` pairing was off that contract: `primary-500`
+// is blue-500, and white on blue-500 measures 3.76:1 in light / 3.92:1 in dark
+// against a 4.5:1 bar for this 12px label. `primary-solid` is blue-600 in light
+// (≈6:1 on white) and blue-400 in dark (≈5.6:1 on blue-950). `--color-on-{role}`
+// is additionally a legacy alias the theme marks for removal — new code takes
+// the slot token directly.
 const MERIDIEM_ACTIVE_COLOR = {
-    primary: 'bg-primary-500 text-on-primary hover:bg-primary-600',
-    secondary: 'bg-secondary-500 text-on-secondary hover:bg-secondary-600',
-    accent: 'bg-accent-500 text-on-accent hover:bg-accent-600',
-    neutral: 'bg-fg text-on-neutral hover:bg-fg/90',
-    info: 'bg-info-500 text-on-info hover:bg-info-600',
-    success: 'bg-success-500 text-on-success hover:bg-success-600',
-    warning: 'bg-warning-500 text-on-warning hover:bg-warning-600',
-    error: 'bg-error-500 text-on-error hover:bg-error-600',
+    primary: 'bg-primary-solid text-primary-solid-fg hover:bg-primary-solid-hover',
+    secondary: 'bg-secondary-solid text-secondary-solid-fg hover:bg-secondary-solid-hover',
+    accent: 'bg-accent-solid text-accent-solid-fg hover:bg-accent-solid-hover',
+    neutral: 'bg-neutral-solid text-neutral-solid-fg hover:bg-neutral-solid-hover',
+    info: 'bg-info-solid text-info-solid-fg hover:bg-info-solid-hover',
+    success: 'bg-success-solid text-success-solid-fg hover:bg-success-solid-hover',
+    warning: 'bg-warning-solid text-warning-solid-fg hover:bg-warning-solid-hover',
+    error: 'bg-error-solid text-error-solid-fg hover:bg-error-solid-hover',
 };
 let nextTimePickerId = 0;
 class TimePickerComponent extends FormFieldControl {
     // ── Inputs ──
-    /** Id on the time-picker's host element. Auto-generated when not provided. Used by the form-field's `<label for>` attribute. */
+    /** Id on the time-picker's host element. Auto-generated when not provided. The accessible name inside a `<tw-form-field>` comes from `aria-labelledby` on the inner `role="group"` wrapper, not from the field's `<label for>` — the host is a custom element, which `for` cannot target. */
     idInput = input(undefined, { ...(ngDevMode ? { debugName: "idInput" } : /* istanbul ignore next */ {}), alias: 'id' });
     /** When true, the whole component is disabled and every field sets `aria-disabled="true"`. Defaults to `false`. */
     disabledInput = input(false, { ...(ngDevMode ? { debugName: "disabledInput" } : /* istanbul ignore next */ {}), alias: 'disabled',
@@ -230,7 +282,7 @@ class TimePickerComponent extends FormFieldControl {
     /** When true, exposes `aria-required="true"`. Validators.required on a bound NgControl is also honoured. Defaults to `false`. */
     requiredInput = input(false, { ...(ngDevMode ? { debugName: "requiredInput" } : /* istanbul ignore next */ {}), alias: 'required',
         transform: booleanAttribute });
-    /** When true, blocks typing, stepping, and the AM/PM toggle — the value is still read-only visible. Defaults to `false`. */
+    /** When true, blocks typing, stepping, and the AM/PM toggle — the value is still read-only visible. Defaults to `false`. Alias: `readonly`. */
     readonlyInput = input(false, { ...(ngDevMode ? { debugName: "readonlyInput" } : /* istanbul ignore next */ {}), alias: 'readonly',
         transform: booleanAttribute });
     /** Controls field height, font size, and stepper density. Defaults to `'md'`. */
@@ -242,7 +294,7 @@ class TimePickerComponent extends FormFieldControl {
     /** Visual style of the chrome. `'default'` draws its own border; `'naked'` strips chrome. Auto-resolves to `'naked'` inside `<tw-form-field>`. */
     variant = input(undefined, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "variant" }] : /* istanbul ignore next */ []));
-    /** `'12h'` renders 1–12 hours with an AM/PM toggle; `'24h'` renders 00–23. Defaults to `'24h'`. */
+    /** `'12h'` renders 1–12 hours with an AM/PM toggle; `'24h'` renders 00–23. The same axis is spelled `timeFormat` on `tw-date-range-picker` and lives under `timeConfig.format` on `tw-date-picker`, where `format` instead means the display-format descriptor. Defaults to `'24h'`. */
     format = input('24h', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "format" }] : /* istanbul ignore next */ []));
     /** When true, renders a seconds field after minutes. Defaults to `false`. */
@@ -269,28 +321,26 @@ class TimePickerComponent extends FormFieldControl {
     /** Placeholder shown in each field when empty. Defaults to `'--'`. */
     placeholder = input(undefined, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "placeholder" }] : /* istanbul ignore next */ []));
-    /** Whether to render the up/down stepper column. Defaults to `true`. */
-    // TRUE-default: pointer users expect inline up/down chevrons next to a numeric editor — without them the picker reads as a static display, and consumers must rebuild stepping for every instance.
+    /** Whether to render the up/down stepper column. Defaults to `true`. Pointer users expect inline up/down chevrons next to a numeric editor; without them the picker reads as a static display and consumers must rebuild stepping for every instance. Ignored at `size="xs"` on the bordered `default` variant, where the 24px control leaves no room for a stacked pair — use ↑/↓ on a field instead. */
     showSteppers = input(true, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "showSteppers" }] : /* istanbul ignore next */ []));
-    /** Whether to render the clear affordance when a value is set. Defaults to `true`. */
-    // TRUE-default: matches `<tw-date-picker>` and `<tw-input>` clear behaviour; without the inline clear, every form has to wire its own reset surface for an obvious affordance.
+    /** Whether to render the clear affordance when a value is set. Defaults to `true` — it matches `<tw-date-picker>` and `<tw-input>` clear behaviour; without the inline clear every form has to wire its own reset surface for an obvious affordance. */
     showClear = input(true, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "showClear" }] : /* istanbul ignore next */ []));
-    /** Accessible label for the clear button. Defaults to `'Clear time'`. */
+    /** Accessible label for the clear button. Note the name differs in meaning from the date pickers, which spell this `clearAriaLabel` and reserve `clearLabel` for the overlay action bar's visible button text. Defaults to `'Clear time'`. */
     clearLabel = input('Clear time', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "clearLabel" }] : /* istanbul ignore next */ []));
-    /** Per-instance override of the `ErrorStateMatcher`. */
+    /** Per-instance override of the `ErrorStateMatcher`. Defaults to `undefined`. */
     errorStateMatcher = input(undefined, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "errorStateMatcher" }] : /* istanbul ignore next */ []));
-    /** Accessible name for the fields group. Required when no visible label is supplied. Alias: `aria-label`. */
+    /** Accessible name for the fields group. Required when no visible label is supplied. 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 group. Alias: `aria-labelledby`. */
+    /** ID of an external element that labels the group. 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 bound current time. `null` when empty. Setting programmatically updates the fields without firing `onChange`. */
+    /** Two-way bound current time. `null` when empty. Setting programmatically updates the fields without firing `onChange`. Defaults to `null`. */
     value = model(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "value" }] : /* istanbul ignore next */ []));
     // ── Outputs ──
@@ -311,9 +361,6 @@ class TimePickerComponent extends FormFieldControl {
     // against its own validator during construction. Mirrors `date-picker.ts`,
     // `date-range-picker.ts` and `calendar.ts`.
     ngControl = null;
-    parentForm = inject(NgForm, { optional: true });
-    parentFormGroup = inject(FormGroupDirective, { optional: true });
-    defaultMatcher = inject(TW_ERROR_STATE_MATCHER);
     /** @internal — exposed for the template; consumers configure via `provideTimePickerIntl()`. */
     intl = inject(TimePickerIntl, { optional: true }) ?? new TimePickerIntl();
     // ── View refs ──
@@ -350,12 +397,19 @@ class TimePickerComponent extends FormFieldControl {
     ...(ngDevMode ? [{ debugName: "cvaDisabled" }] : /* istanbul ignore next */ []));
     describedByIdsSignal = signal([], /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "describedByIdsSignal" }] : /* istanbul ignore next */ []));
+    labelledByIdsSignal = signal([], /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "labelledByIdsSignal" }] : /* istanbul ignore next */ []));
     focusedSignal = signal(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "focusedSignal" }] : /* 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 out-of-range time is an error regardless of validator status.
+        errorStateOverride: () => (this.rangeError() ? true : undefined),
+    });
     /** When true, an effect should not rewrite field text from the external value. */
     editing = false;
     onChange = () => { };
@@ -363,7 +417,7 @@ class TimePickerComponent extends FormFieldControl {
     // ── 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 */ []));
@@ -373,6 +427,28 @@ class TimePickerComponent extends FormFieldControl {
     /** @internal Effective variant — auto-naked when wrapped in tw-form-field. */
     resolvedVariant = computed(() => this.variant() ?? (this.formField ? 'naked' : 'default'), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "resolvedVariant" }] : /* istanbul ignore next */ []));
+    /**
+     * @internal Whether the stepper column actually renders.
+     *
+     * `showSteppers` stays the consumer's switch, but the column is geometrically
+     * impossible at `size="xs"` on the bordered `default` variant: the pinned h-6
+     * root is 24px border-box, leaving a 22px content box, while a stacked pair of
+     * chevron buttons has a 24px min-content height (2 × size-3). Rendering it
+     * anyway would either overflow the shell or squeeze each button to 11px — far
+     * under any usable pointer target. The `naked` variant keeps its steppers: it
+     * draws no border, so in the date-picker / date-range-picker overlay footers a
+     * 24px row leaves a full 24px content box and the pair fits exactly. (Inside
+     * `<tw-form-field>` the row is governed by the field's own padding and its
+     * `min-h-*` floor, which is a minimum — the row grows rather than clipping.)
+     * Stepping stays available everywhere via ↑/↓ on a focused field, so nothing
+     * becomes unreachable.
+     */
+    steppersVisible = computed(() => {
+        if (!this.showSteppers())
+            return false;
+        return !(this.size() === 'xs' && this.resolvedVariant() === 'default');
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "steppersVisible" }] : /* istanbul ignore next */ []));
     /** @internal */
     hourMin = computed(() => fieldMin('hour', this.format()), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "hourMin" }] : /* istanbul ignore next */ []));
@@ -416,8 +492,34 @@ class TimePickerComponent extends FormFieldControl {
         return n === null ? this.intl.emptyValueText : padTwo(n);
     }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "secondValueText" }] : /* istanbul ignore next */ []));
-    /** @internal */
-    groupAriaLabel = computed(() => this.ariaLabel() ?? this.intl.groupLabel, /* @ts-ignore */
+    /**
+     * @internal Merged `aria-labelledby` for the `role="group"` wrapper: the ids a
+     * wrapping `<tw-form-field>` pushes down (its projected `<label twLabel>` plus
+     * anything the consumer supplied) or, standalone, the consumer's own
+     * `aria-labelledby`. The host is `<tw-time-picker>`, a custom element the
+     * field's `<label for>` cannot target, so this attribute is the only route
+     * from the visible label to the composite. Returns `null` when nothing labels
+     * the group by reference.
+     */
+    groupLabelledBy = computed(() => {
+        const pushed = this.labelledByIdsSignal();
+        if (pushed.length)
+            return pushed.join(' ');
+        return this.ariaLabelledby() ?? null;
+    }, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "groupLabelledBy" }] : /* istanbul ignore next */ []));
+    /**
+     * @internal `aria-label` for the group. An explicit `aria-label` always wins;
+     * otherwise the generic intl fallback is suppressed whenever `groupLabelledBy`
+     * already names the group, so a real label is not shadowed by "Time" in the
+     * accessibility tree inspector.
+     */
+    groupAriaLabel = computed(() => {
+        const explicit = this.ariaLabel();
+        if (explicit)
+            return explicit;
+        return this.groupLabelledBy() ? null : this.intl.groupLabel;
+    }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "groupAriaLabel" }] : /* istanbul ignore next */ []));
     /** @internal Label of the currently focused field, used by stepper aria-labels. */
     focusedFieldLabel = computed(() => {
@@ -485,30 +587,29 @@ class TimePickerComponent extends FormFieldControl {
     /** @internal */ focused = this.focusedSignal.asReadonly();
     /** @internal */ empty = this.isEmpty;
     /** @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 */ []));
+    /**
+     * Whether the control is required — the `required` input OR `Validators.required`
+     * on a bound `NgControl`. Bound to `aria-required` on each spinbutton field, not on
+     * the `role="group"` wrapper, which does not permit the attribute.
+     */
+    required = this.errorWiring.required;
     /** @internal */
-    errorState = computed(() => {
-        this._ngControlRev();
-        this._formSubmitRev();
-        this.focusedSignal();
-        if (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 */ []));
+    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
+     * `timePickerMin` / `timePickerMax` codes this component's `NG_VALIDATORS` apparatus exists
+     * to produce — stays permanently hidden.
+     */
+    errors = this.errorWiring.errors;
     /** @internal */ controlType = 'time-picker';
     /** @internal */
     userAriaDescribedBy = computed(() => this.userAriaDescribedByInput(), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "userAriaDescribedBy" }] : /* istanbul ignore next */ []));
+    /** @internal Consumer-supplied `aria-labelledby`, surfaced so the wrapping form-field merges it into the ids it pushes back rather than replacing it. */
+    userAriaLabelledby = computed(() => this.ariaLabelledby(), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "userAriaLabelledby" }] : /* istanbul ignore next */ []));
     // ── Constructor ──
     constructor() {
         super();
@@ -608,7 +709,7 @@ class TimePickerComponent extends FormFieldControl {
                 this.editing = false;
                 this.normalizeEmptyFields();
                 this.onTouched();
-                this._ngControlRev.update((n) => n + 1);
+                this.errorWiring.bump();
             }
         });
         this.destroyRef.onDestroy(() => {
@@ -622,22 +723,8 @@ class TimePickerComponent extends FormFieldControl {
         this.ngControl = this.injector.get(NgControl, null, { self: true, optional: true });
         // `isDisabled` / `required` / `errorState` read `ngControl` and saw `null`
         // until now; bump the revision so they recompute.
-        this._ngControlRev.update((n) => n + 1);
-        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));
-        }
+        this.errorWiring.bump();
+        this.errorWiring.connect();
     }
     // ── Public imperative API ──
     /** Moves focus to the hours field. */
@@ -1078,6 +1165,10 @@ class TimePickerComponent extends FormFieldControl {
     setDescribedByIds(ids) {
         this.describedByIdsSignal.set([...ids]);
     }
+    /** @internal Receives the merged `aria-labelledby` ids from the wrapping form-field and applies them to the `role="group"` wrapper. Required because the host is a custom element rather than a labelable control, so the field's `<label for>` never reaches it. */
+    setLabelledByIds(ids) {
+        this.labelledByIdsSignal.set([...ids]);
+    }
     /** @internal */
     onContainerClick(event) {
         if (this.isDisabled())
@@ -1114,7 +1205,12 @@ class TimePickerComponent extends FormFieldControl {
                 multi: true,
             },
         ], viewQueries: [{ propertyName: "hourInputRef", first: true, predicate: ["hourInput"], descendants: true, isSignal: true }, { propertyName: "minuteInputRef", first: true, predicate: ["minuteInput"], descendants: true, isSignal: true }, { propertyName: "secondInputRef", first: true, predicate: ["secondInput"], descendants: true, isSignal: true }], usesInheritance: true, ngImport: i0, template: `
-    <div [class]="fieldGroupClasses()" role="group" [attr.aria-label]="groupAriaLabel()">
+    <div
+      [class]="fieldGroupClasses()"
+      role="group"
+      [attr.aria-label]="groupAriaLabel()"
+      [attr.aria-labelledby]="groupLabelledBy()"
+    >
       <input
         #hourInput
         type="text"
@@ -1133,6 +1229,7 @@ class TimePickerComponent extends FormFieldControl {
         [attr.aria-valuenow]="hourValueNow()"
         [attr.aria-valuetext]="hourValueText()"
         [attr.aria-invalid]="errorState() || null"
+        [attr.aria-required]="required() || null"
         [attr.aria-disabled]="isDisabled() || null"
         (keydown)="onFieldKeydown($event, 'hour')"
         (beforeinput)="onBeforeInput($event, 'hour')"
@@ -1161,6 +1258,7 @@ class TimePickerComponent extends FormFieldControl {
         [attr.aria-valuenow]="minuteValueNow()"
         [attr.aria-valuetext]="minuteValueText()"
         [attr.aria-invalid]="errorState() || null"
+        [attr.aria-required]="required() || null"
         [attr.aria-disabled]="isDisabled() || null"
         (keydown)="onFieldKeydown($event, 'minute')"
         (beforeinput)="onBeforeInput($event, 'minute')"
@@ -1190,6 +1288,7 @@ class TimePickerComponent extends FormFieldControl {
           [attr.aria-valuenow]="secondValueNow()"
           [attr.aria-valuetext]="secondValueText()"
           [attr.aria-invalid]="errorState() || null"
+          [attr.aria-required]="required() || null"
           [attr.aria-disabled]="isDisabled() || null"
           (keydown)="onFieldKeydown($event, 'second')"
           (beforeinput)="onBeforeInput($event, 'second')"
@@ -1200,7 +1299,7 @@ class TimePickerComponent extends FormFieldControl {
       }
     </div>
 
-    @if (showSteppers()) {
+    @if (steppersVisible()) {
       <div [class]="stepperGroupClasses()">
         <button
           type="button"
@@ -1310,7 +1409,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
                         },
                     ],
                     template: `
-    <div [class]="fieldGroupClasses()" role="group" [attr.aria-label]="groupAriaLabel()">
+    <div
+      [class]="fieldGroupClasses()"
+      role="group"
+      [attr.aria-label]="groupAriaLabel()"
+      [attr.aria-labelledby]="groupLabelledBy()"
+    >
       <input
         #hourInput
         type="text"
@@ -1329,6 +1433,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
         [attr.aria-valuenow]="hourValueNow()"
         [attr.aria-valuetext]="hourValueText()"
         [attr.aria-invalid]="errorState() || null"
+        [attr.aria-required]="required() || null"
         [attr.aria-disabled]="isDisabled() || null"
         (keydown)="onFieldKeydown($event, 'hour')"
         (beforeinput)="onBeforeInput($event, 'hour')"
@@ -1357,6 +1462,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
         [attr.aria-valuenow]="minuteValueNow()"
         [attr.aria-valuetext]="minuteValueText()"
         [attr.aria-invalid]="errorState() || null"
+        [attr.aria-required]="required() || null"
         [attr.aria-disabled]="isDisabled() || null"
         (keydown)="onFieldKeydown($event, 'minute')"
         (beforeinput)="onBeforeInput($event, 'minute')"
@@ -1386,6 +1492,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
           [attr.aria-valuenow]="secondValueNow()"
           [attr.aria-valuetext]="secondValueText()"
           [attr.aria-invalid]="errorState() || null"
+          [attr.aria-required]="required() || null"
           [attr.aria-disabled]="isDisabled() || null"
           (keydown)="onFieldKeydown($event, 'second')"
           (beforeinput)="onBeforeInput($event, 'second')"
@@ -1396,7 +1503,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
       }
     </div>
 
-    @if (showSteppers()) {
+    @if (steppersVisible()) {
       <div [class]="stepperGroupClasses()">
         <button
           type="button"