@koobiq/components 20.4.2 → 21.0.1

package/{form-field/index.d.ts → types/koobiq-components-form-field.d.ts}

@@ -1,46 +1,44 @@
 import * as i0 from '@angular/core';
-import { Signal, InjectionToken, AfterContentInit, Provider, QueryList, AfterViewInit, OnDestroy, ChangeDetectorRef, TemplateRef, OutputEmitterRef, AfterContentChecked, ElementRef } from '@angular/core';
+import { Signal, InjectionToken, AfterContentInit, Provider, AfterViewInit, OnDestroy, InputSignal, TemplateRef, OutputEmitterRef, AfterContentChecked, ElementRef } from '@angular/core';
 import { KbqIconButton } from '@koobiq/components/icon';
 import { NgControl } from '@angular/forms';
-import { Observable, Subject } from 'rxjs';
-import { KbqColorDirective, KbqComponentColors } from '@koobiq/components/core';
+import * as i1 from '@koobiq/components/core';
+import { KbqColorDirective } from '@koobiq/components/core';
 import { FocusMonitor, FocusOrigin } from '@angular/cdk/a11y';
 import { KbqTooltipTrigger } from '@koobiq/components/tooltip';
+import { Subject } from 'rxjs';
 
-/** An interface which allows a control to work inside of a `KbqFormField`. */
+/**
+ * An interface which allows a control to work inside of a `KbqFormField`.
+ *
+ * Every state member is a signal: the form field derives its own state from them and runs `OnPush`, so a
+ * change of the control reaches it without any notification of the control's own.
+ */
 declare abstract class KbqFormFieldControl<T> {
     /** The value of the control. */
-    value: T | null;
-    /**
-     * Stream that emits whenever the state of the control changes such that the parent `KbqFormField`
-     * needs to run change detection.
-     */
-    readonly stateChanges: Observable<void>;
+    readonly value: Signal<T | null>;
     /** The element ID for this control. */
-    readonly id: string;
+    readonly id: Signal<string>;
     /** The placeholder for this control. */
-    readonly placeholder: string;
+    readonly placeholder: Signal<string | null | undefined>;
     /** Gets the NgControl for this control. */
     readonly ngControl: NgControl | null;
     /** Whether the control is focused. */
-    readonly focused: boolean;
+    readonly focused: Signal<boolean>;
     /** Whether the control is empty. */
-    readonly empty: boolean;
+    readonly empty: Signal<boolean>;
     /** Whether the control is required. */
-    readonly required: boolean;
+    readonly required: Signal<boolean>;
     /** Whether the control is disabled. */
-    readonly disabled: boolean;
+    readonly disabled: Signal<boolean>;
     /** Whether the control is in an error state. */
-    readonly errorState: boolean;
+    readonly errorState: Signal<boolean>;
     /**
      * Whether the control's value was filled in by the browser.
      *
      * Implement it only where autofill is reachable: on a control that is itself a text input or a
      * textarea, or — like `KbqTagList` — on a wrapper that forwards the state of the input it hosts.
      * Leave it out on controls the browser never fills.
-     *
-     * A signal rather than a plain property because the form field reads it from a host binding and
-     * runs `OnPush`: a signal read there marks the form field dirty on its own.
      */
     readonly autofilled?: Signal<boolean>;
     /**
@@ -49,31 +47,64 @@ declare abstract class KbqFormFieldControl<T> {
      * `kbq-form-field-type-{{controlType}}` to its root element.
      */
     readonly controlType?: string;
+    /**
+     * Whether the control is a native labelable element, so that the `<label for>` a wrapping
+     * `kbq-form-field` renders associates with it.
+     *
+     * Defaults to `true`. A control rendered as a custom element (`kbq-select`, for one) sets it to
+     * `false`: a `<label>` with neither a `for` matching a labelable element nor a nested one is
+     * invalid, so the form field renders the caption as a `<span>` instead and the control is named
+     * through `aria-labelledby`.
+     */
+    readonly isNativeLabelSupported?: boolean;
+    /**
+     * Sets the ids of the elements (hints, errors) that describe the control.
+     *
+     * Implement it only when `aria-describedby` has to be placed on an element other than the one
+     * the control is declared on: `KbqFormField` writes the attribute on the control's host element
+     * by default.
+     */
+    setDescribedByIds?: (ids: string[]) => void;
     /** Handles a click on the control's container. */
     abstract onContainerClick(event: MouseEvent): void;
     /** Focuses the control. */
     abstract focus(options?: FocusOptions): void;
     /** Opens control's overlay. */
-    abstract open?(): void;
+    open?: () => void;
 }
 
 /** @docs-private */
-interface KbqCleanerContext {
+interface KbqCleanerContextBase {
     readonly control: KbqFormFieldControl<unknown>;
-    readonly keydownTarget: HTMLElement;
-    readonly clearByEscape: boolean;
     /** Overrides the default `cleanerControl.ngControl?.reset()` behavior when the cleaner is activated. */
     clear?(): void;
+    /**
+     * Whether the control still holds something the cleaner would remove — a host that keeps part of
+     * its value back reports `false` once only that part is left. Defaults to `true`.
+     */
+    canClear?(): boolean;
 }
+/**
+ * `keydownTarget` is where `Escape` presses are listened for, so it is required by `clearByEscape` and
+ * refused without it — a host that asks for `Escape` clearing but names no target would silently never clear.
+ *
+ * @docs-private
+ */
+type KbqCleanerContext = KbqCleanerContextBase & ({
+    readonly clearByEscape: true;
+    readonly keydownTarget: HTMLElement;
+} | {
+    readonly clearByEscape: false;
+    readonly keydownTarget?: never;
+});
 /** @docs-private */
 declare const KBQ_CLEANER_CONTEXT: InjectionToken<KbqCleanerContext | null>;
 /**
  * Utility provider for `KBQ_CLEANER_CONTEXT`, built from a factory that resolves the current host's `KbqCleanerContext`.
+ *
  * @docs-private
  */
 declare const kbqCleanerFactoryProvider: (factory: () => KbqCleanerContext) => Provider;
-/** @docs-private */
-declare function getKbqFormFieldYouCanNotUseCleanerInNumberInputError(): Error;
 /**
  * Element to be placed in end of the form field.
  * Resets form control by click.
@@ -82,6 +113,7 @@ declare class KbqCleaner extends KbqIconButton implements AfterContentInit {
     private readonly context;
     /**
      * Whether the cleaner can be displayed for the current control state.
+     *
      * @docs-private
      */
     get canShow(): boolean;
@@ -94,6 +126,7 @@ declare class KbqCleaner extends KbqIconButton implements AfterContentInit {
     ngAfterContentInit(): void;
     /**
      * Clears the owning control in response to pointer or keyboard activation.
+     *
      * @docs-private
      */
     clear(event: Event): void;
@@ -102,21 +135,19 @@ declare class KbqCleaner extends KbqIconButton implements AfterContentInit {
      */
     private onKeyDown;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqCleaner, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqCleaner, "kbq-cleaner", ["kbqCleaner"], { "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqCleaner, "kbq-cleaner", ["kbqCleaner"], { "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof i1.KbqLocaleOverridesDirective; inputs: { "kbqLocaleOverrides": "localeOverrides"; }; outputs: {}; }]>;
 }
 
 /** Hint text to be shown below the form field control. */
 declare class KbqHint extends KbqColorDirective {
-    /** Unique ID for the hint. */
+    /** Unique ID for the hint. Referenced by the `aria-describedby` of the form field control. */
     readonly id: i0.InputSignal<string>;
     /** Disables `color` for the hint text. */
-    fillTextOff: boolean;
+    readonly fillTextOff: i0.InputSignalWithTransform<boolean, unknown>;
     /** Makes the hint size smaller. */
-    compact: boolean;
+    readonly compact: i0.InputSignalWithTransform<boolean, unknown>;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqHint, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqHint, "kbq-hint", ["kbqHint"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "fillTextOff": { "alias": "fillTextOff"; "required": false; }; "compact": { "alias": "compact"; "required": false; }; }, {}, never, ["[kbq-icon]", "*"], true, never>;
-    static ngAcceptInputType_fillTextOff: unknown;
-    static ngAcceptInputType_compact: unknown;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqHint, "kbq-hint", ["kbqHint"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; "fillTextOff": { "alias": "fillTextOff"; "required": false; "isSignal": true; }; "compact": { "alias": "compact"; "required": false; "isSignal": true; }; }, {}, never, ["[kbq-icon]", "*"], true, never>;
 }
 
 /** Error text to be shown below the form field control. */
@@ -128,91 +159,43 @@ declare class KbqError extends KbqHint {
 
 /** Directive for marking an element as legend of `KbqFieldset` */
 declare class KbqLegend {
+    /** Unique ID for the legend, referenced by the `aria-labelledby` of the fieldset. */
+    readonly id: i0.InputSignal<string>;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqLegend, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqLegend, "[kbqLegend]", never, {}, {}, never, never, true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqLegend, "[kbqLegend]", ["kbqLegend"], { "id": { "alias": "id"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 /** Directive for marking elements as items inside `KbqFieldset` */
 declare class KbqFieldsetItem {
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqFieldsetItem, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqFieldsetItem, "[kbqFieldsetItem]", never, {}, {}, never, never, true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqFieldsetItem, "[kbqFieldsetItem]", ["kbqFieldsetItem"], {}, {}, never, never, true, never>;
 }
 /**
  * A group of form-fields and related controls.
  * Container component emulating the native `fieldset` element.
  */
 declare class KbqFieldset {
-    private readonly legend;
     /**
-     * Computes the aria-label from the inner text of the legend element.
-     * Used to enhance accessibility by labeling the group.
-     * @docs-private
+     * Labels the group with the projected legend. Referencing the element keeps the accessible name in sync
+     * with the visible text, including after a locale change.
      */
-    protected readonly ariaLabel: Signal<string | undefined>;
+    protected readonly legend: i0.Signal<KbqLegend | undefined>;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqFieldset, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqFieldset, "kbq-fieldset", never, {}, {}, ["legend"], ["[kbqLegend]", "*", "kbq-error", "kbq-hint, kbq-password-hint, kbq-reactive-password-hint"], true, never>;
-}
-
-declare enum PasswordRules {
-    Length = 0,
-    UpperLatin = 1,
-    LowerLatin = 2,
-    Digit = 3,
-    LatinAndSpecialSymbols = 4,
-    Custom = 5
-}
-declare const regExpPasswordValidator: {
-    2: RegExp;
-    1: RegExp;
-    3: RegExp;
-    4: RegExp;
-};
-declare const hasPasswordStrengthError: (passwordHints: QueryList<KbqPasswordHint> | readonly KbqPasswordHint[]) => boolean;
-declare class KbqPasswordHint extends KbqHint implements AfterContentInit {
-    private changeDetectorRef;
-    private formField;
-    readonly id: i0.InputSignal<string>;
-    readonly rule: i0.InputSignal<any>;
-    readonly min: i0.InputSignal<number>;
-    readonly max: i0.InputSignal<number>;
-    regex: RegExp | null;
-    readonly customCheckRule: i0.InputSignal<(value: string) => boolean>;
-    readonly viewFormField: i0.InputSignal<KbqFormField | undefined>;
-    fillTextOff: boolean;
-    hasError: boolean;
-    checked: boolean;
-    get icon(): string;
-    /**
-     * The form field hint icon color.
-     *
-     * @docs-private
-     */
-    protected get iconColor(): KbqComponentColors;
-    private checkRule;
-    private get control();
-    private lastControlValue;
-    constructor();
-    ngAfterContentInit(): void;
-    private checkValue;
-    private checkLengthRule;
-    private checkRegexRule;
-    private checkSpecialSymbolsRegexRule;
-    private isValueChanged;
-    static ɵfac: i0.ɵɵFactoryDeclaration<KbqPasswordHint, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqPasswordHint, "kbq-password-hint", never, { "id": { "alias": "id"; "required": false; "isSignal": true; }; "rule": { "alias": "rule"; "required": false; "isSignal": true; }; "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "regex": { "alias": "regex"; "required": false; }; "customCheckRule": { "alias": "checkRule"; "required": false; "isSignal": true; }; "viewFormField": { "alias": "viewFormField"; "required": false; "isSignal": true; }; "fillTextOff": { "alias": "fillTextOff"; "required": false; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqFieldset, "kbq-fieldset", ["kbqFieldset"], {}, {}, ["legend"], ["[kbqLegend]", "*", "kbq-error", "kbq-hint, kbq-reactive-password-hint"], true, never>;
 }
 
 /** Component which changes password visibility. */
-declare class KbqPasswordToggle extends KbqTooltipTrigger implements AfterViewInit, OnDestroy, AfterContentInit {
+declare class KbqPasswordToggle extends KbqTooltipTrigger implements AfterViewInit, OnDestroy {
     protected readonly nativeElement: HTMLElement;
     protected readonly focusMonitor: FocusMonitor;
-    protected readonly changeDetectorRef: ChangeDetectorRef;
     private readonly a11yLocaleConfiguration;
     private readonly formField;
     readonly tabindex: i0.InputSignalWithTransform<number, unknown>;
     /**
      * @docs-private
      */
-    readonly icon: i0.Signal<KbqIconButton>;
+    readonly icon: Signal<KbqIconButton>;
+    /** @docs-private */
+    readonly contentInput: InputSignal<KbqTooltipTrigger['content'] | undefined>;
     /**
      * Tooltip shown while the password is visible. Reading it resolves to the tooltip matching the current
      * visibility, so that the base trigger renders the right one.
@@ -220,8 +203,8 @@ declare class KbqPasswordToggle extends KbqTooltipTrigger implements AfterViewIn
     get content(): string | TemplateRef<any>;
     set content(content: string | TemplateRef<any>);
     /** Tooltip shown while the password is hidden. */
-    readonly kbqTooltipHidden: i0.InputSignal<string | TemplateRef<any>>;
-    protected hasError: boolean;
+    readonly kbqTooltipHidden: InputSignal<string | TemplateRef<any>>;
+    protected readonly hasError: Signal<boolean>;
     /** Form field password control. */
     private get control();
     /**
@@ -236,6 +219,7 @@ declare class KbqPasswordToggle extends KbqTooltipTrigger implements AfterViewIn
      * @docs-private
      */
     get visibility(): 'hidden' | 'visible';
+    private readonly visibilityState;
     /**
      * Accessible name of the icon-only toggle, describing the action it performs.
      *
@@ -243,7 +227,6 @@ declare class KbqPasswordToggle extends KbqTooltipTrigger implements AfterViewIn
      */
     protected get accessibleName(): string;
     constructor();
-    ngAfterContentInit(): void;
     ngAfterViewInit(): void;
     ngOnDestroy(): void;
     /**
@@ -254,9 +237,8 @@ declare class KbqPasswordToggle extends KbqTooltipTrigger implements AfterViewIn
      * Toggles password visibility for the Alt+F8 shortcut.
      */
     private onFormFieldKeyDown;
-    private updateState;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqPasswordToggle, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqPasswordToggle, "kbq-password-toggle", ["kbqPasswordToggle"], { "tabindex": { "alias": "tabindex"; "required": false; "isSignal": true; }; "content": { "alias": "kbqTooltipNotHidden"; "required": false; }; "kbqTooltipHidden": { "alias": "kbqTooltipHidden"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqPasswordToggle, "kbq-password-toggle", ["kbqPasswordToggle"], { "tabindex": { "alias": "tabindex"; "required": false; "isSignal": true; }; "contentInput": { "alias": "kbqTooltipNotHidden"; "required": false; "isSignal": true; }; "kbqTooltipHidden": { "alias": "kbqTooltipHidden"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof i1.KbqLocaleOverridesDirective; inputs: { "kbqLocaleOverrides": "localeOverrides"; }; outputs: {}; }]>;
 }
 
 /** Element to be placed in front of the form field. */
@@ -266,26 +248,20 @@ declare class KbqPrefix {
 }
 
 /**
- * Narrow structural contract for the control hosted by `kbqNumberInput`, duck-typed here to avoid
- * a circular dependency between `@koobiq/components/form-field` and `@koobiq/components/input`.
+ * Narrow structural contract for `KbqNumberInput`, duck-typed here to avoid a circular dependency between
+ * `@koobiq/components/form-field` and `@koobiq/components/input`. It is not the form field control: that is
+ * `KbqInput` on the same element.
  */
-type KbqStepperControl = KbqFormFieldControl<unknown> & {
+type KbqStepperControl = {
     readonly controlType: 'input-number';
-    readonly step: number;
+    /** Read by the template, so it has to be backed by a signal for the stepper to follow it. */
+    readonly disabled: boolean;
+    /** A signal since the input review: `step` is an `input()` on `KbqNumberInput`. */
+    readonly step: Signal<number>;
     stepUp: (step: number) => void;
     /** Decreases the value by `step`. */
     stepDown: (step: number) => void;
 };
-/**
- * Timeout duration when clicking the up/down arrow
- * @docs-private
- */
-declare const KBQ_STEPPER_INITIAL_TIMEOUT = 300;
-/**
- * Interval delay when clicking the up/down arrow
- * @docs-private
- */
-declare const KBQ_STEPPER_INTERVAL_DELAY = 75;
 /** Component which allow to increment or decrement number value. */
 declare class KbqStepper {
     private readonly formField;
@@ -300,12 +276,9 @@ declare class KbqStepper {
     /**
      * Timing observable simulating long press in native input-number.
      * - Value increases/decreases by step immediately.
-     * - Brief pause (`300ms`)
+     * - Brief pause (`300ms`, {@link KBQ_STEPPER_INITIAL_TIMEOUT})
      * - Numbers start running upward/downward with selected speed
-     * (controlled by interval period)
-     * @see KBQ_STEPPER_INTERVAL_DELAY
-     * @see KBQ_STEPPER_INITIAL_TIMEOUT
-     * @docs-private
+     * (controlled by interval period, {@link KBQ_STEPPER_INTERVAL_DELAY})
      */
     private readonly longPress;
     /**
@@ -313,13 +286,8 @@ declare class KbqStepper {
      *
      * @docs-private
      */
-    protected readonly control: i0.Signal<KbqStepperControl>;
+    protected readonly control: Signal<KbqStepperControl>;
     constructor();
-    /**
-     * @deprecated No longer required — `KbqStepper` resolves its control automatically via DI.
-     * @docs-private
-     */
-    connectTo(_: any): void;
     /** @docs-private */
     onStepUp(event: MouseEvent): void;
     /** @docs-private */
@@ -332,13 +300,12 @@ declare class KbqStepper {
 /** Element to be placed at the end of the form field. */
 declare class KbqSuffix {
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqSuffix, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqSuffix, "[kbqSuffix]", never, {}, {}, never, never, true, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<KbqSuffix, "[kbqSuffix]", ["kbqSuffix"], {}, {}, never, never, true, never>;
 }
 
-/** @docs-private */
-declare function getKbqFormFieldMissingControlError(): Error;
 /**
  * Injection token used to access the owning `KbqFormField`.
+ *
  * @docs-private
  */
 declare const KBQ_FORM_FIELD: InjectionToken<KbqFormField>;
@@ -360,6 +327,7 @@ type KbqFormFieldDefaultOptions = Partial<{
 }>;
 /**
  * Injection token that can be used to configure the default options for all kbq-form-field's.
+ *
  * @docs-private
  */
 declare const KBQ_FORM_FIELD_DEFAULT_OPTIONS: InjectionToken<Partial<{
@@ -402,53 +370,43 @@ declare class KbqFormField extends KbqColorDirective implements AfterContentInit
      *
      * @docs-private
      */
-    readonly control: i0.Signal<KbqFormFieldControl<any>>;
-    /**
-     * @docs-private
-     */
-    readonly stepper: i0.Signal<KbqStepper | undefined>;
+    readonly control: Signal<KbqFormFieldControl<any>>;
     /**
      * @docs-private
-     *
-     * @TODO Should be readonly (#DS-3883)
      */
-    cleaner: KbqCleaner | null;
+    readonly stepper: Signal<KbqStepper | undefined>;
     /**
      * @docs-private
      */
-    passwordToggle: KbqPasswordToggle | null;
+    readonly cleaner: Signal<KbqCleaner | undefined>;
     /**
      * @docs-private
      */
-    hint: QueryList<KbqHint>;
+    readonly passwordToggle: Signal<KbqPasswordToggle | undefined>;
     /**
      * @docs-private
      */
-    passwordHints: QueryList<KbqPasswordHint>;
+    readonly hint: Signal<readonly KbqHint[]>;
     /**
      * @docs-private
      */
-    suffix: QueryList<KbqSuffix>;
+    readonly suffix: Signal<readonly KbqSuffix[]>;
     /**
      * @docs-private
      */
-    prefix: QueryList<KbqPrefix>;
+    readonly prefix: Signal<readonly KbqPrefix[]>;
     /**
      * @docs-private
      */
-    readonly connectionContainerRef: i0.Signal<ElementRef<any>>;
+    readonly connectionContainerRef: Signal<ElementRef<any>>;
+    /** Host element of the control, used as the `aria-describedby` target. */
+    private readonly controlElementRef;
     private readonly reactivePasswordHint;
     private readonly error;
     private readonly label;
-    /**
-     * @docs-private
-     */
-    hovered: boolean;
-    /**
-     * @docs-private
-     * @deprecated Unused. This property is no longer used by the form field and will be removed in a future version.
-     */
-    canCleanerClearByEsc: boolean;
+    private readonly invalidState;
+    private readonly disabledState;
+    private readonly autofilledState;
     /** Whether the form field is invalid. */
     get invalid(): boolean;
     /**
@@ -456,73 +414,85 @@ declare class KbqFormField extends KbqColorDirective implements AfterContentInit
      *
      * @docs-private
      */
-    protected get hasReactivePasswordHint(): boolean;
+    protected readonly hasReactivePasswordHint: Signal<boolean>;
     /**
      * Whether the form-field contains kbq-error.
      *
      * @docs-private
      */
-    protected get hasError(): boolean;
+    protected readonly hasError: Signal<boolean>;
     /**
      * Whether the form-field contains kbq-label.
      *
      * @docs-private
      */
-    protected get hasLabel(): boolean;
+    protected readonly hasLabel: Signal<boolean>;
     /**
-     * Whether the form-field contains kbq-password-hint.
+     * Id of the rendered label, or `null` when the form field has no label.
      *
-     * @docs-private
+     * `for` only associates a label with a native form control, so a control that is a custom element
+     * (`kbq-select`, for one) has to point back at the label through `aria-labelledby` instead.
      */
-    get hasPasswordHint(): boolean;
+    readonly labelId: Signal<string | null>;
     /**
-     * Current focus origin state.
+     * Whether the control is a native labelable element, so that a `<label>` can associate with it.
      *
-     * @docs-private
-     */
-    get focusOrigin(): FocusOrigin;
-    private _focusOrigin;
-    /**
-     * @docs-private
+     * A custom control (`kbq-select`, for one) reports `isNativeLabelSupported: false`; the caption is then rendered
+     * as a `<span>` instead of a `<label>`, because a label that neither has a `for` matching a labelable
+     * element nor wraps one is invalid, and the control is named through `aria-labelledby` instead.
      */
-    get hasFocus(): boolean;
+    readonly isNativeLabelSupported: Signal<boolean>;
     /**
      * Whether the form-field contains kbq-hint.
      *
      * @docs-private
      */
-    get hasHint(): boolean;
+    readonly hasHint: Signal<boolean>;
     /**
      * Whether the form-field contains kbqSuffix.
      *
      * @docs-private
      */
-    get hasSuffix(): boolean;
+    readonly hasSuffix: Signal<boolean>;
     /**
      * Whether the form-field contains kbqPrefix.
      *
      * @docs-private
      */
-    get hasPrefix(): boolean;
+    readonly hasPrefix: Signal<boolean>;
     /**
      * Whether the form-field contains kbq-cleaner.
      *
      * @docs-private
      */
-    get hasCleaner(): boolean;
+    readonly hasCleaner: Signal<boolean>;
     /**
      * Whether the form-field contains kbq-stepper.
      *
      * @docs-private
      */
-    get hasStepper(): boolean;
+    readonly hasStepper: Signal<boolean>;
     /**
      * Whether the form-field contains kbq-password-toggle.
      *
      * @docs-private
      */
-    get hasPasswordToggle(): boolean;
+    readonly hasPasswordToggle: Signal<boolean>;
     /**
+     * Current focus origin state.
+     *
+     * @docs-private
+     */
+    get focusOrigin(): FocusOrigin;
+    private _focusOrigin;
+    /**
+     * @docs-private
+     */
+    get hasFocus(): boolean;
+    /**
+     * Whether the cleaner can be displayed: it requires a projected `kbq-cleaner`, an enabled control
+     * and a value that is not empty.
+     *
      * @docs-private
      */
     get canShowCleaner(): boolean;
@@ -539,6 +509,8 @@ declare class KbqFormField extends KbqColorDirective implements AfterContentInit
      * longer considers autofilled.
      */
     get autofilled(): boolean;
+    /** Ids last written to the control's `aria-describedby`, to skip redundant DOM writes. */
+    private appliedDescribedByIds;
     ngAfterContentInit(): void;
     ngAfterContentChecked(): void;
     ngAfterViewInit(): void;
@@ -555,16 +527,6 @@ declare class KbqFormField extends KbqColorDirective implements AfterContentInit
      * @docs-private
      */
     onContainerClick(event: MouseEvent): void;
-    /**
-     * Handles keydown events.
-     * @deprecated Unused. This method is no longer called by the form field and will be removed in a future version.
-     * @docs-private
-     */
-    onKeyDown(_event: KeyboardEvent): void;
-    /**
-     * @docs-private
-     */
-    onHoverChanged(isHovered: boolean): void;
     /**
      * Gets an ElementRef for the element that a overlay attached to the form-field should be positioned relative to.
      */
@@ -593,23 +555,35 @@ declare class KbqFormField extends KbqColorDirective implements AfterContentInit
      * @docs-private
      */
     protected validateControlChild(): void;
+    /**
+     * Links the hints and the error rendered by the form field to the control via `aria-describedby`,
+     * so assistive technology announces them when the control gets focused.
+     */
+    private updateDescribedByIds;
     /** Initializes the form field control. */
     private initializeControl;
-    /** Initializes the kbqPrefix and kbqSuffix containers. */
-    private initializePrefixAndSuffix;
-    /** Initializes the KbqHint, KbqPasswordHint, KbqReactivePasswordHint and KbqError containers. */
-    private initializeHint;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqFormField, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqFormField, "kbq-form-field", ["kbqFormField"], { "noBorders": { "alias": "noBorders"; "required": false; "isSignal": true; }; "inOverlay": { "alias": "inOverlay"; "required": false; "isSignal": true; }; "horizontal": { "alias": "horizontal"; "required": false; "isSignal": true; }; "labelClass": { "alias": "labelClass"; "required": false; "isSignal": true; }; "contentClass": { "alias": "contentClass"; "required": false; "isSignal": true; }; }, { "inOverlay": "inOverlayChange"; }, ["control", "stepper", "cleaner", "passwordToggle", "label", "hint", "passwordHints", "suffix", "prefix", "reactivePasswordHint", "error"], ["kbq-label", "[kbqPrefix]", "*", "kbq-cleaner", "kbq-password-toggle, kbq-stepper, [kbqSuffix]", "kbq-error", "kbq-hint, kbq-password-hint, kbq-reactive-password-hint"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqFormField, "kbq-form-field", ["kbqFormField"], { "noBorders": { "alias": "noBorders"; "required": false; "isSignal": true; }; "inOverlay": { "alias": "inOverlay"; "required": false; "isSignal": true; }; "horizontal": { "alias": "horizontal"; "required": false; "isSignal": true; }; "labelClass": { "alias": "labelClass"; "required": false; "isSignal": true; }; "contentClass": { "alias": "contentClass"; "required": false; "isSignal": true; }; }, { "inOverlay": "inOverlayChange"; }, ["control", "stepper", "cleaner", "passwordToggle", "hint", "suffix", "prefix", "controlElementRef", "reactivePasswordHint", "error", "label"], ["kbq-label", "[kbqPrefix]", "*", "kbq-cleaner", "kbq-password-toggle, kbq-stepper, [kbqSuffix]", "kbq-error", "kbq-hint, kbq-reactive-password-hint"], true, never>;
 }
 /**
+ * Trims the value of `kbqInput` and `kbqTextarea` before it reaches the model.
+ *
+ * The value displayed in the control is left untouched, so trimming never fights the user while they
+ * are typing. Add the `no-trim` attribute to the control to keep the value as is. `kbqInputPassword`
+ * is not matched by this directive, so passwords keep their leading and trailing whitespace.
+ *
  * @docs-private
  */
 declare class KbqTrim {
     private readonly noTrim;
     private readonly ngControl;
     constructor();
-    trim(value: any): any;
+    /**
+     * Trims the value when it is a string, other values are passed through as is.
+     *
+     * @docs-private
+     */
+    trim(value: unknown): unknown;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqTrim, never>;
     static ɵdir: i0.ɵɵDirectiveDeclaration<KbqTrim, "[kbqInput], [kbqTextarea]", ["KbqTrim"], {}, {}, never, never, true, never>;
 }
@@ -624,26 +598,28 @@ declare class KbqLabel {
 declare class KbqReactivePasswordHint extends KbqHint {
     private readonly formField;
     private readonly destroyRef;
-    private readonly changeDetectorRef;
     /** Whether the form field control has an error. */
     readonly hasError: i0.InputSignalWithTransform<boolean, unknown>;
+    /** Disables `color` for the hint text. */
+    readonly fillTextOff: i0.InputSignalWithTransform<boolean, unknown>;
     /**
      * The form field hint icon.
      *
      * @docs-private
      */
-    protected readonly icon: i0.Signal<"kbq-check-s_16" | "kbq-xmark-s_16">;
+    protected readonly icon: i0.Signal<"kbq-xmark-s_16" | "kbq-check-s_16">;
     constructor();
+    private updateColor;
     private makeColor;
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqReactivePasswordHint, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<KbqReactivePasswordHint, "kbq-reactive-password-hint", ["kbqReactivePasswordHint"], { "hasError": { "alias": "hasError"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<KbqReactivePasswordHint, "kbq-reactive-password-hint", ["kbqReactivePasswordHint"], { "hasError": { "alias": "hasError"; "required": false; "isSignal": true; }; "fillTextOff": { "alias": "fillTextOff"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
 declare class KbqFormFieldModule {
     static ɵfac: i0.ɵɵFactoryDeclaration<KbqFormFieldModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<KbqFormFieldModule, never, [typeof KbqCleaner, typeof KbqFormField, typeof KbqPrefix, typeof KbqSuffix, typeof KbqPasswordToggle, typeof KbqStepper, typeof KbqLabel, typeof KbqHint, typeof KbqError, typeof KbqReactivePasswordHint, typeof KbqLegend, typeof KbqFieldset, typeof KbqFieldsetItem, typeof KbqPasswordHint, typeof KbqTrim], [typeof KbqCleaner, typeof KbqFormField, typeof KbqPrefix, typeof KbqSuffix, typeof KbqPasswordToggle, typeof KbqStepper, typeof KbqLabel, typeof KbqHint, typeof KbqError, typeof KbqReactivePasswordHint, typeof KbqLegend, typeof KbqFieldset, typeof KbqFieldsetItem, typeof KbqPasswordHint, typeof KbqTrim]>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<KbqFormFieldModule, never, [typeof KbqCleaner, typeof KbqFormField, typeof KbqPrefix, typeof KbqSuffix, typeof KbqPasswordToggle, typeof KbqStepper, typeof KbqLabel, typeof KbqHint, typeof KbqError, typeof KbqReactivePasswordHint, typeof KbqLegend, typeof KbqFieldset, typeof KbqFieldsetItem, typeof KbqTrim], [typeof KbqCleaner, typeof KbqFormField, typeof KbqPrefix, typeof KbqSuffix, typeof KbqPasswordToggle, typeof KbqStepper, typeof KbqLabel, typeof KbqHint, typeof KbqError, typeof KbqReactivePasswordHint, typeof KbqLegend, typeof KbqFieldset, typeof KbqFieldsetItem, typeof KbqTrim]>;
     static ɵinj: i0.ɵɵInjectorDeclaration<KbqFormFieldModule>;
 }
 
-export { KBQ_CLEANER_CONTEXT, KBQ_FORM_FIELD, KBQ_FORM_FIELD_DEFAULT_OPTIONS, KBQ_STEPPER_INITIAL_TIMEOUT, KBQ_STEPPER_INTERVAL_DELAY, KbqCleaner, KbqError, KbqFieldset, KbqFieldsetItem, KbqFormField, KbqFormFieldControl, KbqFormFieldModule, KbqHint, KbqLabel, KbqLegend, KbqPasswordHint, KbqPasswordToggle, KbqPrefix, KbqReactivePasswordHint, KbqStepper, KbqSuffix, KbqTrim, PasswordRules, getKbqFormFieldMissingControlError, getKbqFormFieldYouCanNotUseCleanerInNumberInputError, hasPasswordStrengthError, kbqCleanerFactoryProvider, kbqFormFieldDefaultOptionsProvider, regExpPasswordValidator };
-export type { KbqCleanerContext, KbqFormFieldDefaultOptions };
+export { KBQ_CLEANER_CONTEXT, KBQ_FORM_FIELD, KBQ_FORM_FIELD_DEFAULT_OPTIONS, KbqCleaner, KbqError, KbqFieldset, KbqFieldsetItem, KbqFormField, KbqFormFieldControl, KbqFormFieldModule, KbqHint, KbqLabel, KbqLegend, KbqPasswordToggle, KbqPrefix, KbqReactivePasswordHint, KbqStepper, KbqSuffix, KbqTrim, kbqCleanerFactoryProvider, kbqFormFieldDefaultOptionsProvider };
+export type { KbqCleanerContext, KbqCleanerContextBase, KbqFormFieldDefaultOptions };