@malva-ui/core 0.1.13 → 0.1.14

package/types/malva-ui-core-form-utils.d.ts

@@ -0,0 +1,579 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Signal, ElementRef, ModelSignal, WritableSignal } from '@angular/core';
+import { MlvStructural } from '@malva-ui/cdk/utils';
+import { BooleanInput } from '@angular/cdk/coercion';
+import { ValidationError, FormCheckboxControl, FormValueControl } from '@angular/forms/signals';
+import * as _malva_ui_i18n from '@malva-ui/i18n';
+import * as _malva_ui_core_form_utils from '@malva-ui/core/form-utils';
+import { Subject } from 'rxjs';
+import { FocusOrigin } from '@angular/cdk/a11y';
+
+type MlvFormState = 'default' | 'success' | 'info' | 'warning' | 'error';
+
+type MlvErrorDisplayStrategy = 'touched' | 'dirty' | 'submit' | 'immediate';
+
+declare class MlvFormControlPrepend extends MlvStructural {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvFormControlPrepend, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvFormControlPrepend, "[mlvFormControlPrepend]", never, {}, {}, never, never, true, never>;
+}
+declare class MlvFormControlAppend extends MlvStructural {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvFormControlAppend, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvFormControlAppend, "[mlvFormControlAppend]", never, {}, {}, never, never, true, never>;
+}
+/**
+ * Full-width content rendered inside the bordered control, after its main row.
+ *
+ * Use for secondary, non-interactive control presentation such as strength
+ * meters. Prefix and suffix actions remain in their dedicated slots.
+ */
+declare class MlvFormControlInset extends MlvStructural {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvFormControlInset, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvFormControlInset, "[mlvFormControlInset]", never, {}, {}, never, never, true, never>;
+}
+
+interface MlvFormControl {
+    readonly focused: Signal<boolean>;
+    readonly disabled: Signal<boolean>;
+    readonly readonly: Signal<boolean>;
+    readonly state: Signal<MlvFormState>;
+    /**
+     * Effective state after field-bound errors/touched state are considered.
+     * Signal-form controls provide this; legacy controls fall back to `state`.
+     */
+    readonly resolvedState?: Signal<MlvFormState>;
+    readonly loading: Signal<boolean>;
+    readonly clearable: Signal<boolean>;
+    /**
+     * Fully rounded (stadium) control container. Optional — absent means the
+     * regular radius.
+     */
+    readonly pill?: Signal<boolean>;
+    /**
+     * Whether the control currently holds a clearable (non-empty) value. The
+     * wrapper renders the clear button only while `clearable() && hasValue()` —
+     * an empty control never shows a dangling X.
+     */
+    readonly hasValue: Signal<boolean>;
+    /**
+     * When `true`, the control renders its own clear button inside its template
+     * (e.g. select/combobox place it before the chevron) and the wrapper must
+     * NOT render its default one. Optional — absent means wrapper-rendered.
+     */
+    readonly ownsClearButton?: Signal<boolean>;
+    readonly prepend: Signal<MlvFormControlPrepend | undefined>;
+    readonly append: Signal<MlvFormControlAppend | undefined>;
+    /** Optional full-width content rendered inside the control border. */
+    readonly inset: Signal<MlvFormControlInset | undefined>;
+}
+declare const MLV_FORM_CONTROL: InjectionToken<MlvFormControl>;
+
+declare class MlvLabel {
+    /** Id of the control this label names, rendered as the native `for` attribute. */
+    readonly for: _angular_core.InputSignal<string>;
+    /**
+     * Whether the labelled control is required. Renders a visual `*` marker plus
+     * a visually-hidden, translated "required" word so the requirement is
+     * announced even where `aria-required` is not surfaced. Controls extending
+     * `MlvSignalFormUiControlBase` forward their own `required` input here.
+     */
+    readonly required: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * @private The form-utils i18n strings. Optional so a bare `mlv-label` still
+     * renders in applications that never called `provideMlvI18n()`.
+     */
+    private readonly _i18n;
+    /** @protected Translated word announced after the label of a required control. */
+    protected readonly _requiredText: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvLabel, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvLabel, "mlv-label", never, { "for": { "alias": "for"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; }, {}, never, ["*", "mlv-hint"], true, never>;
+}
+
+/**
+ * Secondary hint for the control named by the enclosing `mlv-label`.
+ *
+ * The hint is authored as projected content — `<mlv-hint>Sent to your phone</mlv-hint>` —
+ * but it renders as a small `circle-question-mark` icon button that reveals the
+ * text in an `mlvTooltip` on hover and on keyboard focus. Rendering an icon
+ * rather than inline text keeps the label row on one line no matter how long
+ * the hint is, which inline text could not do inside the label's flex row.
+ *
+ * The projected content itself stays in the DOM (hidden) purely as the source
+ * the tooltip string is read from; it is `aria-hidden` so the hint no longer
+ * leaks into the accessible name of the labelled control. The same string is
+ * put on the trigger's `aria-label`, so assistive tech still reaches it.
+ *
+ * Use `mlv-description` instead for sentence-length help text that should stay
+ * permanently visible below the control.
+ *
+ * @example Inside a label
+ * ```html
+ * <mlv-label for="email">
+ *   Email
+ *   <mlv-hint>We only use this for receipts</mlv-hint>
+ * </mlv-label>
+ * ```
+ *
+ * @example Interpolated, as every `hint`-input control renders it
+ * ```html
+ * <mlv-hint>{{ hint() }}</mlv-hint>
+ * ```
+ */
+declare class MlvHint {
+    /**
+     * @protected Wrapper around the projected content. Kept in the DOM (only
+     * `display: none`, never `@if`-ed away) because it is the sole source the
+     * hint string can be read from, and `textContent` still resolves on a
+     * non-displayed element.
+     */
+    protected readonly _source: _angular_core.Signal<ElementRef<HTMLElement>>;
+    /**
+     * @protected Trimmed text of the projected content — used both as the tooltip
+     * body and as the trigger's accessible name. Empty until the first render has
+     * produced the projected DOM, and kept in sync afterwards by `_observer`.
+     * While it is empty no trigger is rendered at all, so an empty `mlv-hint`
+     * never leaves a nameless icon button behind.
+     */
+    protected readonly _text: _angular_core.WritableSignal<string>;
+    /**
+     * @private Watches the projected content for changes. Interpolated hints
+     * (`<mlv-hint>{{ hint() }}</mlv-hint>`) mutate a text node owned by the
+     * *parent* view, which no signal in this component can depend on — and
+     * `textContent` is not a reactive read, so an effect would evaluate once and
+     * never re-run. A MutationObserver is the only thing that sees the change.
+     */
+    private _observer;
+    /** @private Disconnects `_observer` when the component is destroyed. */
+    private readonly _destroyRef;
+    constructor();
+    /**
+     * @protected Swallows the trigger's click so it does not read as an
+     * activation of the enclosing `<label>`. `preventDefault()` stops the label's
+     * native "focus the labelled control" behaviour, and `stopPropagation()`
+     * stops click handlers bound on `mlv-label` itself — `mlv-select` binds one
+     * there to open its dropdown — from firing when the user only wanted the
+     * hint. Both are required; neither alone covers the other case.
+     */
+    protected _onClick(event: MouseEvent): void;
+    /**
+     * @private Reads the trimmed projected text into `_text`. Setting a signal to
+     * an identical string is a no-op, so re-reads triggered by unrelated DOM
+     * mutations cannot loop.
+     */
+    private _readText;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvHint, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvHint, "mlv-hint", never, {}, {}, never, ["*"], true, never>;
+}
+
+/**
+ * Persistent help text rendered below a form control, in front of the
+ * validation message. Projected into `mlv-form-control-wrapper` through its
+ * `mlv-description` slot and referenced by the control's `aria-describedby`,
+ * so it stays readable while a validation message is shown.
+ *
+ * @example
+ * <mlv-description [id]="descriptionId">
+ *   We only use this address for receipts.
+ * </mlv-description>
+ */
+declare class MlvDescription {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvDescription, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvDescription, "mlv-description", never, {}, {}, never, ["*"], true, never>;
+}
+
+declare class MlvMessage {
+    readonly state: _angular_core.InputSignal<MlvFormState>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvMessage, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvMessage, "mlv-message", never, { "state": { "alias": "state"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+}
+
+declare class MlvFormField {
+    /** Visual state of the field. Overridden to `'error'` when an auto error message is shown. */
+    readonly state: _angular_core.InputSignal<MlvFormState>;
+    /** Custom validator-key → message map (string or factory) overriding the built-in defaults. */
+    readonly errorMessages: _angular_core.InputSignal<Record<string, string | ((err: unknown) => string)>>;
+    /** Controls when validation errors become visible. */
+    readonly displayStrategy: _angular_core.InputSignal<MlvErrorDisplayStrategy>;
+    /**
+     * @private The form-utils i18n strings. Optional so `mlv-form-field` keeps
+     * rendering in applications that never called `provideMlvI18n()`.
+     */
+    private readonly _i18n;
+    /** @private The projected `NgControl` whose validation state this field reflects. */
+    private readonly _ngControl;
+    /**
+     * @private The projected signal-forms `[formField]` directive, when the
+     * child control is bound through `@angular/forms/signals` instead of an
+     * `NgControl`. Takes precedence over the NgControl path when present.
+     */
+    private readonly _signalField;
+    /**
+     * @private The bound signal-forms `FieldState`, or `null` while no
+     * `[formField]` child is projected. `field()` is the `FieldTree`; calling it
+     * yields the reactive `FieldState`.
+     */
+    private readonly _signalFieldState;
+    /** @private The ancestor form directive, used to observe submission state. */
+    private readonly _formDirective;
+    /** @private Current validation errors of the projected control. */
+    private readonly _controlErrors;
+    /** @private Whether the projected control has been touched. */
+    private readonly _controlTouched;
+    /** @private Whether the projected control is dirty. */
+    private readonly _controlDirty;
+    /** @private Whether the ancestor form has been submitted. */
+    private readonly _formSubmitted;
+    constructor();
+    /** @private Whether validation errors should currently be displayed, per {@link displayStrategy}. */
+    private readonly _shouldDisplay;
+    /**
+     * @private Unified error view: `[key, errorPayload]` pairs from whichever
+     * forms API the projected control is bound through. Signal-forms
+     * `ValidationError`s are keyed by their lower-cased `kind` (matching the
+     * legacy reactive keys: `minLength` → `minlength`); the payload is the
+     * error object itself (it carries `message` when a rule supplied one).
+     */
+    private readonly _errorEntries;
+    /** The resolved auto error message for the projected control, or `''` when none should show. */
+    readonly autoErrorMessage: _angular_core.Signal<string>;
+    /**
+     * @private Neutral, translated message shown when a validator key has no
+     * consumer-supplied, rule-supplied or built-in message.
+     */
+    private readonly _genericErrorMessage;
+    /**
+     * @private The currently displayed validator key that has no mapped message
+     * and therefore falls back to {@link _genericErrorMessage} — `null` when a
+     * specific message applies. Drives the dev-mode warning only.
+     */
+    private readonly _unmappedErrorKey;
+    /** The effective visual state: `'error'` when an auto error message is shown, otherwise {@link state}. */
+    readonly resolvedState: _angular_core.Signal<MlvFormState>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvFormField, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvFormField, "mlv-form-field", never, { "state": { "alias": "state"; "required": false; "isSignal": true; }; "errorMessages": { "alias": "errorMessages"; "required": false; "isSignal": true; }; "displayStrategy": { "alias": "displayStrategy"; "required": false; "isSignal": true; }; }, {}, ["_ngControl", "_signalField"], ["mlv-label", "*", "mlv-message"], true, never>;
+}
+
+/**
+ * Shared, forms-transport-agnostic surface for **signal-forms** Malva controls.
+ * Owns everything EXCEPT the value/checked model: the
+ * Malva field surface (`state`, `label`, `hint`, `message`, `clearable`,
+ * `id`, prepend/append slots), the wrapper connector contract
+ * ({@link MlvFormControl}), and the signal-forms field↔control bindings —
+ * `errors` / `disabled` / `readonly` / `touched` / `dirty` input signals the
+ * `[formField]` directive binds automatically, plus the `touch` output the
+ * control emits when the user leaves the field.
+ *
+ * Per the signal-forms contract a component must NOT implement both
+ * `ControlValueAccessor` and `FormValueControl`; controls therefore adopt
+ * either {@link MlvSignalFormControlBase} or {@link MlvSignalCheckboxControlBase}
+ * atomically. Reactive (`[formControl]`)
+ * and template-driven (`ngModel`) bindings keep working — Angular binds the
+ * signal contract from those directives without extra compatibility code.
+ */
+declare abstract class MlvSignalFormUiControlBase implements MlvFormControl {
+    /** @protected Backing signal for {@link focused}. */
+    protected readonly _focused: _angular_core.WritableSignal<boolean>;
+    /** Whether the control currently has focus (drives the wrapper's focus ring). */
+    readonly focused: Signal<boolean>;
+    /** Sets the control's focus state (wired to the focus target's focus/blur). */
+    setFocused(value: boolean): void;
+    /** Explicit consumer-authored visual validation state. */
+    readonly state: _angular_core.InputSignal<MlvFormState>;
+    /**
+     * Whether the control is read-only. Also a signal-forms field binding: when
+     * bound via `[formField]`, a `readonly` schema rule drives this input.
+     */
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Whether the control is disabled. Also a signal-forms field binding: when
+     * bound via `[formField]`, the field's disabled state drives this input.
+     */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Whether the control must be filled in. Renders the required marker in
+     * `mlv-label` and sets `aria-required` on the control's focus target. Also a
+     * signal-forms field binding: when bound via `[formField]`, a `required()`
+     * schema rule drives this input.
+     */
+    readonly required: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Whether the control shows its loading affordance. */
+    readonly loading: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Whether the control renders a clear (X) affordance while it has a value. */
+    readonly clearable: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Fully rounded (stadium) control container. Shared by every control that
+     * renders through `mlv-form-control-wrapper`, mirroring `shape="pill"` on
+     * buttons and the pill action bar.
+     */
+    readonly pill: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Signal-forms field binding: current validation errors of the bound field
+     * (`[formField]` binds them automatically). Empty when unbound.
+     */
+    readonly errors: _angular_core.InputSignal<readonly ValidationError.WithOptionalFieldTree[]>;
+    /** Signal-forms field binding: whether the bound field is touched. */
+    readonly touched: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Signal-forms field binding: whether the bound field is dirty. */
+    readonly dirty: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Effective visual state exposed through the Malva form-control connector.
+     * An explicit non-default state wins; otherwise a signal-form validation
+     * error becomes visible after the field is touched, matching the default
+     * `MlvFormField` error-display strategy.
+     */
+    readonly resolvedState: Signal<MlvFormState>;
+    /**
+     * Emits when the user finishes interacting with the field (blur) — the
+     * signal-forms replacement for the CVA `onTouched` callback; `[formField]`
+     * subscribes and marks the bound field touched.
+     */
+    readonly touch: _angular_core.OutputEmitterRef<void>;
+    /**
+     * Whether the control currently holds a clearable (non-empty) value.
+     */
+    abstract readonly hasValue: Signal<boolean>;
+    /** HTML id applied to the control's focus target. */
+    readonly id: _angular_core.InputSignal<string>;
+    /** Label text rendered above the control. */
+    readonly label: _angular_core.InputSignal<string>;
+    /** Hint text rendered inside the label. */
+    readonly hint: _angular_core.InputSignal<string>;
+    /**
+     * Persistent help text rendered **below** the control, in front of the
+     * validation message. Unlike {@link hint} (a short inline aside inside the
+     * label) this is meant for sentence-length descriptions, and it stays
+     * visible while {@link message} is shown. Referenced by `aria-describedby`.
+     */
+    readonly description: _angular_core.InputSignal<string>;
+    /** Validation/status message rendered below the control. */
+    readonly message: _angular_core.InputSignal<string>;
+    /**
+     * Accessible name applied to the control's focus target (`aria-label`).
+     * Use it when the control renders no visible `<mlv-label>`.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /** @protected Id of the rendered `<mlv-description>` element. */
+    protected readonly _descriptionId: Signal<string>;
+    /** @protected Id of the rendered `<mlv-message>` element. */
+    protected readonly _messageId: Signal<string>;
+    /**
+     * @protected Space-separated `aria-describedby` value covering the rendered
+     * description and message elements — `null` when neither is rendered, so no
+     * dangling IDREF is emitted.
+     */
+    protected readonly _describedBy: Signal<string | null>;
+    /** Projected prefix slot. */
+    readonly prepend: Signal<MlvFormControlPrepend | undefined>;
+    /** Projected suffix slot. */
+    readonly append: Signal<MlvFormControlAppend | undefined>;
+    /** Projected full-width content rendered inside the control border. */
+    readonly inset: Signal<MlvFormControlInset | undefined>;
+    /**
+     * Effective disabled state. In the signal base there is no CVA
+     * `setDisabledState` side channel — the `disabled` input is the single
+     * source (consumer-bound or field-bound), kept as a computed so existing
+     * control templates retain one consistent disabled-state signal.
+     */
+    readonly computedDisabled: Signal<boolean>;
+    /** @protected Notifies the field that the user left the control. */
+    protected _markTouched(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvSignalFormUiControlBase, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvSignalFormUiControlBase, never, never, { "state": { "alias": "state"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "clearable": { "alias": "clearable"; "required": false; "isSignal": true; }; "pill": { "alias": "pill"; "required": false; "isSignal": true; }; "errors": { "alias": "errors"; "required": false; "isSignal": true; }; "touched": { "alias": "touched"; "required": false; "isSignal": true; }; "dirty": { "alias": "dirty"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "message": { "alias": "message"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "touch": "touch"; }, ["prepend", "append", "inset"], never, true, never>;
+}
+/**
+ * Signal-forms base for **value** controls: adds the required
+ * `value: ModelSignal<T>` of the `FormValueControl` contract. Each control
+ * supplies the model itself (`readonly value = model<T>(initial)`), mirroring
+ * how `hasValue` is supplied.
+ */
+declare abstract class MlvSignalFormControlBase<T> extends MlvSignalFormUiControlBase implements FormValueControl<T> {
+    /** The control's value — kept in sync with the bound field by `[formField]`. */
+    abstract readonly value: ModelSignal<T>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvSignalFormControlBase<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvSignalFormControlBase<any>, never, never, {}, {}, never, never, true, never>;
+}
+/**
+ * Signal-forms base for **checkbox-shaped** controls (checkbox, switch): adds
+ * the required `checked: ModelSignal<boolean>` of the `FormCheckboxControl`
+ * contract. The contract forbids a `value` member on this variant.
+ */
+declare abstract class MlvSignalCheckboxControlBase extends MlvSignalFormUiControlBase implements FormCheckboxControl {
+    /** The control's checked state — kept in sync with the bound field by `[formField]`. */
+    abstract readonly checked: ModelSignal<boolean>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvSignalCheckboxControlBase, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvSignalCheckboxControlBase, never, never, {}, {}, never, never, true, never>;
+}
+
+declare class MlvFormControlWrapperControl extends MlvStructural {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvFormControlWrapperControl, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvFormControlWrapperControl, "[mlvFormControlWrapperControl]", never, {}, {}, never, never, true, never>;
+}
+
+declare class MlvFormControlWrapper {
+    /** @protected Optional injected form control connector for state/focus/disabled bindings. */
+    protected readonly formControl: _malva_ui_core_form_utils.MlvFormControl | null;
+    /** @protected Computed BEM state modifier class derived from the control's validation state. */
+    protected readonly _stateClass: _angular_core.Signal<string>;
+    /** @protected Required projected control-slot directive rendered inside the wrapper. */
+    protected readonly renderer: _angular_core.Signal<MlvFormControlWrapperControl>;
+    /** @protected The component's i18n strings signal. */
+    protected readonly _i18n: _angular_core.Signal<_malva_ui_i18n.MlvFormUtilsI18n>;
+    /**
+     * Clear event emitter. Emits when user clicks on clear button
+     */
+    readonly clear: _angular_core.OutputEmitterRef<void>;
+    /** @protected Handles the clear-button click by emitting the `clear` output. */
+    protected _onClearClick(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvFormControlWrapper, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvFormControlWrapper, "mlv-form-control-wrapper", never, {}, { "clear": "clear"; }, ["renderer"], ["mlv-label", "mlv-description", "mlv-message", "[mlvFormControlWrapperAside]"], true, never>;
+}
+
+declare class MlvSelectionService<T = unknown> {
+    readonly multiple: _angular_core.WritableSignal<boolean>;
+    readonly selectedValues: _angular_core.WritableSignal<T[]>;
+    readonly focusFirst$: Subject<void>;
+    /**
+     * Equality predicate used for all membership checks (`isSelected`,
+     * `deselect`, and the `select`/`toggle` de-dup path). Defaults to reference
+     * equality (`a === b`). Set a custom comparator (e.g. compare by id) so object
+     * values written via `writeValue` after deserialization match the option
+     * instances and check-marks / display value stay in agreement.
+     */
+    readonly compareWith: _angular_core.WritableSignal<(a: T, b: T) => boolean>;
+    readonly displayValue: _angular_core.Signal<string>;
+    /** @private Index of `value` within the current selection, or `-1`. */
+    private _indexOf;
+    select(value: T): void;
+    deselect(value: T): void;
+    isSelected(value: T): boolean;
+    clear(): void;
+    setValues(values: T[]): void;
+    toggle(value: T): void;
+    requestFocusFirst(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvSelectionService<any>, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<MlvSelectionService<any>>;
+}
+
+/**
+ * Forms ↔ `@angular/aria` value bridge.
+ *
+ * The headless `@angular/aria` selection patterns (`ngListbox`, `ngMenu`,
+ * `ngTree`, …) always model their selection as an **array** of values
+ * (`value: ModelSignal<V[]>`), even in single-select mode where the array holds
+ * at most one entry. Malva UI form controls expose the idiomatic public shape:
+ * a bare `T` for single-select and a `T[]` for multi-select, with `null` used
+ * to represent "no selection".
+ *
+ * These helpers translate between the two representations so a component can
+ * keep its public single/multi forms contract while driving an aria pattern
+ * underneath. They are pure and allocation-light, and are designed to
+ * round-trip: `fromAriaValues(toAriaValues(v, multi), multi)` yields the
+ * canonical form of `v`.
+ *
+ * @remarks
+ * `toAriaValues` treats an incoming array as an already-expanded multi-select
+ * value. If your single-select `T` is itself an array type, wrap it before
+ * bridging — this is the same ambiguity the aria patterns themselves carry.
+ */
+/**
+ * Normalises a control value (`T`, `T[]`, or `null`/`undefined`) into the flat
+ * `V[]` array that `@angular/aria` selection patterns expect.
+ *
+ * - `null` / `undefined` → `[]` (cleared selection)
+ * - an array → a shallow copy of that array (multi-select)
+ * - any other value → a single-element array (single-select)
+ *
+ * @param value The control-side value to convert.
+ * @returns A fresh array suitable for assigning to an aria `value` model.
+ */
+declare function toAriaValues<V>(value: V | readonly V[] | null | undefined): V[];
+/**
+ * Collapses the flat `V[]` array produced by an `@angular/aria` selection
+ * pattern back into the control-side value shape.
+ *
+ * - `multiple === true` → a shallow copy of the array (empty array stays `[]`)
+ * - `multiple === false` → the first entry, or `null` when the array is empty
+ *
+ * @param values The aria-side selection array.
+ * @param multiple Whether the control is in multi-select mode.
+ * @returns The control-side value: `V[]` for multi-select, `V | null` for single.
+ */
+declare function fromAriaValues<V>(values: readonly V[] | null | undefined, multiple: boolean): V | V[] | null;
+
+/**
+ * The per-item contract a roving-tabindex group needs from each child: a
+ * focusable element whose `tabIndex` is a writable signal the group flips
+ * between `0` (the single tab stop) and `-1` (the rest). Satisfied by
+ * `mlv-checkbox` and `mlv-switch`, whose native input binds `[attr.tabindex]`
+ * to this signal.
+ *
+ * Deliberately NOT `extends FocusableOption`: components type `disabled` as a
+ * coerced input signal (`InputSignalWithTransform<boolean, BooleanInput>`),
+ * which is incompatible with `FocusableOption`'s plain `disabled?: boolean`.
+ * Disabled-skipping is expressed through the group's
+ * {@link MlvFocusableGroupBase._isDisabled} predicate instead, and
+ * `FocusKeyManager<T>` needs no constraint (it intersects `FocusableOption & T`
+ * internally).
+ */
+interface MlvFocusableGroupItem {
+    /** Focuses the item's focus target (the visually-hidden native input). */
+    focus(origin?: FocusOrigin): void;
+    /** Roving tabindex applied to the item's focus target. */
+    readonly tabIndex: WritableSignal<number>;
+}
+/**
+ * Shared, selection-agnostic scaffold for composite groups that navigate their
+ * children with a vertical, wrapping {@link FocusKeyManager} and a roving
+ * tabindex that follows focus (only the active child is tabbable).
+ *
+ * Extracted from the duplicated lifecycle in `MlvCheckboxGroup` and
+ * `MlvSwitchGroup`. It owns **only** the focus / roving-tabindex concern:
+ * key-manager creation over the current children, the `change`→tabindex sync,
+ * keydown delegation, child-focus tracking, and teardown. Subclasses supply the
+ * live children signal ({@link _items}) and the skip predicate
+ * ({@link _isDisabled}); everything else (selection, CVA, templates) stays in
+ * the concrete component.
+ *
+ * NB: this is a *focus-roving* base — the tab stop follows the focused child.
+ * Groups whose tab stop must follow a *selected* child instead (e.g.
+ * `mlv-radio-group`, whose checked radio is the tab stop and whose arrow keys
+ * also move selection) do not fit this contract and keep their own manager.
+ *
+ * @typeParam T The concrete focusable child component type.
+ */
+declare abstract class MlvFocusableGroupBase<T extends MlvFocusableGroupItem> {
+    /** @private Normalizes the vertical arrow keys delegated to the key manager. */
+    private readonly _rtlService;
+    /**
+     * @protected The live children in DOM order — typically a `contentChildren`
+     * signal on the subclass. Read reactively inside the base effect so the key
+     * manager is rebuilt whenever the projected set changes.
+     */
+    protected abstract readonly _items: Signal<readonly T[]>;
+    /**
+     * @protected Predicate marking a child as skipped by arrow navigation. Groups
+     * bridge their own disabled model here (e.g. `computedDisabled()`).
+     */
+    protected abstract _isDisabled(item: T): boolean;
+    /** @private FocusKeyManager driving roving-tabindex arrow navigation between children. */
+    private _keyManager?;
+    /** @private Subscription to the key manager's active-item changes. */
+    private _changeSub?;
+    constructor();
+    /**
+     * Notifies the manager which child took focus so arrow navigation resumes from
+     * it. Wire to each child's focus notification (group accessor token).
+     */
+    onChildFocus(item: T): void;
+    /**
+     * Delegates ArrowUp/ArrowDown to the key manager (moving focus + the tab stop)
+     * and suppresses the default page scroll. Wire to the group's `(keydown)`.
+     */
+    onKeydown(event: KeyboardEvent): void;
+    /** @private Sets tabindex 0 on the active child and -1 on the rest. */
+    private _syncTabIndices;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvFocusableGroupBase<any>, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvFocusableGroupBase<any>, never, never, {}, {}, never, never, true, never>;
+}
+
+export { MLV_FORM_CONTROL, MlvDescription, MlvFocusableGroupBase, MlvFormControlAppend, MlvFormControlInset, MlvFormControlPrepend, MlvFormControlWrapper, MlvFormControlWrapperControl, MlvFormField, MlvHint, MlvLabel, MlvMessage, MlvSelectionService, MlvSignalCheckboxControlBase, MlvSignalFormControlBase, MlvSignalFormUiControlBase, fromAriaValues, toAriaValues };
+export type { MlvErrorDisplayStrategy, MlvFocusableGroupItem, MlvFormControl, MlvFormState };