@malva-ui/core 0.1.12

package/filter/lib/smart-filter-bar/smart-filter-bar.d.ts

@@ -0,0 +1,153 @@
+import type { BooleanInput } from '@angular/cdk/coercion';
+import { MlvPopupTrigger } from '@malva-ui/core/popup';
+import type { MlvSearchFieldTrigger } from '@malva-ui/core/search-field';
+import type { MlvFilterApplyMode, MlvFilterCondition, MlvFilterConditionStrategy, MlvFilterDefinition, MlvFilterExecutionPayload, MlvFilterFieldState, MlvFilterOperator } from '../filter.types';
+import * as i0 from "@angular/core";
+/** Metadata-driven query header for search, field filters, and execution. */
+export declare class MlvSmartFilterBar {
+    /** @protected Reactive translated strings for filters. */
+    protected readonly _i18n: import("@angular/core").Signal<import("@malva-ui/i18n").MlvFilterI18n>;
+    /** @private ICU resolver for parameterized translated strings. */
+    private readonly _resolver;
+    /** Metadata for every available filter field. */
+    readonly definitions: import("@angular/core").InputSignal<readonly MlvFilterDefinition<unknown>[]>;
+    /** Structured filter state. */
+    readonly filters: import("@angular/core").ModelSignal<readonly MlvFilterFieldState[]>;
+    /** Keys currently shown in the filter row. */
+    readonly visibleKeys: import("@angular/core").ModelSignal<readonly string[]>;
+    /** Global search query submitted with structured filters. */
+    readonly searchValue: import("@angular/core").ModelSignal<string>;
+    /** Commit behavior for the global search field. */
+    readonly searchTrigger: import("@angular/core").InputSignal<MlvSearchFieldTrigger>;
+    /** Debounce passed to the global live-search field. */
+    readonly searchDebounce: import("@angular/core").InputSignalWithTransform<number, string | number>;
+    /** Apply behavior used by each field filter editor. */
+    readonly filterApplyMode: import("@angular/core").InputSignal<MlvFilterApplyMode>;
+    /** Whether live search/filter commits should execute immediately. */
+    readonly autoExecute: import("@angular/core").InputSignalWithTransform<boolean, BooleanInput>;
+    /** Whether structured fields are expanded beneath the query actions. */
+    readonly filtersVisible: import("@angular/core").ModelSignal<boolean>;
+    /** Whether the global search field is rendered. */
+    readonly showSearch: import("@angular/core").InputSignalWithTransform<boolean, BooleanInput>;
+    /** Whether query execution is in progress. */
+    readonly loading: import("@angular/core").InputSignalWithTransform<boolean, BooleanInput>;
+    /** Whether every control in the bar is unavailable. */
+    readonly disabled: import("@angular/core").InputSignalWithTransform<boolean, BooleanInput>;
+    /** Emitted with an immutable snapshot when the query executes. */
+    readonly execute: import("@angular/core").OutputEmitterRef<MlvFilterExecutionPayload>;
+    /** Emitted when consumers should refresh using the current query snapshot. */
+    readonly refresh: import("@angular/core").OutputEmitterRef<MlvFilterExecutionPayload>;
+    /** Emitted after search, filter values, and visibility return to defaults. */
+    readonly resetCompleted: import("@angular/core").OutputEmitterRef<void>;
+    /** @protected Search term used only inside the available-filters manager. */
+    protected readonly _availableSearch: import("@angular/core").WritableSignal<string>;
+    /** @private Staged field visibility while the manager dialog is open. */
+    private readonly _draftVisibleKeys;
+    /** @protected Id linking the filter visibility trigger to its region. */
+    protected readonly _filtersId: string;
+    /** @protected Id linking the manager trigger to its dialog content. */
+    protected readonly _managerId: string;
+    /** @protected Id for the validation summary announced after a blocked query. */
+    protected readonly _validationSummaryId: string;
+    /** @private Whether metadata defaults have been applied to a usable definition set. */
+    private _definitionsInitialized;
+    /** @private Previous metadata keys used to distinguish new defaults from hidden fields. */
+    private _knownDefinitionKeys;
+    /** @private Whether a query attempt should expose required-field errors. */
+    private readonly _validationAttempted;
+    /** @private Coalesces paired condition/strategy model changes into one execution. */
+    private _autoExecuteQueued;
+    /** @private Manager panel used to focus its search field after opening. */
+    private readonly _managerPanel;
+    /** @private Manager trigger restored after keyboard and action closes. */
+    private readonly _managerButton;
+    /** @private Rendered filter hosts used to focus the first invalid field. */
+    private readonly _filterHosts;
+    /** Visible definitions in stable metadata order. */
+    readonly visibleDefinitions: import("@angular/core").Signal<MlvFilterDefinition<unknown>[]>;
+    /** Number of filter fields currently visible. */
+    readonly visibleFilterCount: import("@angular/core").Signal<number>;
+    /** Number of fields with at least one applied condition. */
+    readonly appliedFilterCount: import("@angular/core").Signal<number>;
+    /** @protected Required definitions without an applied, meaningful condition. */
+    protected readonly _missingRequiredDefinitions: import("@angular/core").Signal<MlvFilterDefinition<unknown>[]>;
+    /** @protected Whether required-field errors should currently be rendered. */
+    protected readonly _showRequiredErrors: import("@angular/core").Signal<boolean>;
+    /** @protected Whether search or any structured condition is active. */
+    protected readonly _hasState: import("@angular/core").Signal<boolean>;
+    /** @protected Definitions matching the available-filter search. */
+    protected readonly _filteredDefinitions: import("@angular/core").Signal<readonly MlvFilterDefinition<unknown>[]>;
+    /** @protected Parameterized label for the filter-management action. */
+    protected readonly _filtersLabel: import("@angular/core").Signal<string>;
+    /** @protected Parameterized status for fields with applied values. */
+    protected readonly _appliedFiltersLabel: import("@angular/core").Signal<string>;
+    /** @protected Parameterized heading for the available-filter list. */
+    protected readonly _availableFiltersLabel: import("@angular/core").Signal<string>;
+    /** @protected Localized validation summary for all missing required fields. */
+    protected readonly _requiredFiltersMessage: import("@angular/core").Signal<string>;
+    constructor();
+    /** Executes the current search and structured-filter snapshot. */
+    executeQuery(): void;
+    /** Requests fresh results using the current query snapshot. */
+    refreshQuery(): void;
+    /** Clears search and conditions while retaining the user's visible fields. */
+    clear(): void;
+    /** Restores search, conditions, and visible fields to metadata defaults. */
+    resetToDefaults(): void;
+    /** @protected Updates search state and executes for submit or auto mode. */
+    protected _onSearch(query: string): void;
+    /** @protected Executes a staged live-search value immediately from Enter. */
+    protected _onSearchEnter(event: Event): void;
+    /** @protected Updates the available-filter manager search. */
+    protected _onAvailableSearch(query: string): void;
+    /** @protected Returns applied conditions for a definition key. */
+    protected _conditionsFor(key: string): readonly MlvFilterCondition[];
+    /** @protected Returns the applied strategy for a definition key. */
+    protected _strategyFor(key: string): MlvFilterConditionStrategy;
+    /** @protected Whether a definition permits more than one free-form condition. */
+    protected _allowsMultipleConditions(definition: MlvFilterDefinition): boolean;
+    /** @protected Operators for a definition with the neutral default fallback. */
+    protected _operatorsFor(definition: MlvFilterDefinition): readonly MlvFilterOperator[];
+    /** @protected Updates one field's conditions without disturbing other fields. */
+    protected _setConditions(definition: MlvFilterDefinition, conditions: readonly MlvFilterCondition[]): void;
+    /** @protected Updates one field's condition-combination strategy. */
+    protected _setStrategy(definition: MlvFilterDefinition, strategy: MlvFilterConditionStrategy): void;
+    /** @protected Whether a field key is currently visible. */
+    protected _isVisible(key: string): boolean;
+    /** @protected Whether a field currently has an applied, meaningful condition. */
+    protected _isActive(key: string): boolean;
+    /** @protected Stages a field for addition or removal from the filter row. */
+    protected _setVisible(definition: MlvFilterDefinition, visible: boolean): void;
+    /** @protected Toggles the structured filter row. */
+    protected _toggleFilters(): void;
+    /** @protected Focuses the manager's search input after the popup attaches. */
+    protected _onManagerOpened(): void;
+    /** @protected Restores manager-trigger focus after an overlay action closes. */
+    protected _onManagerClosed(): void;
+    /** @protected Stages the metadata default field selection in the manager. */
+    protected _resetManagerSelection(): void;
+    /** @protected Discards manager edits and closes its popup. */
+    protected _cancelManager(trigger: MlvPopupTrigger): void;
+    /** @protected Commits staged manager edits and closes its popup. */
+    protected _applyManager(trigger: MlvPopupTrigger): void;
+    /** @private Replaces or removes one field state and optionally auto-executes. */
+    private _replaceFieldState;
+    /** @private Schedules one auto execution for the current microtask. */
+    private _queueAutoExecute;
+    /** @private Default-visible keys, always including required definitions. */
+    private _defaultVisibleKeys;
+    /** @protected Whether a required field should currently expose an error. */
+    protected _isRequiredMissing(definition: MlvFilterDefinition): boolean;
+    /** @protected Stable id for one field-level validation message. */
+    protected _requiredErrorId(definition: MlvFilterDefinition): string;
+    /** @protected Localized field-level validation message. */
+    protected _requiredFilterMessage(definition: MlvFilterDefinition): string;
+    /** @private Blocks execution and focuses the first incomplete required field. */
+    private _validateRequiredFilters;
+    /** @private Builds a defensive execution snapshot. */
+    private _payload;
+    /** @private Resolves one ICU message from the filter translation slice. */
+    private _resolveMessage;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvSmartFilterBar, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MlvSmartFilterBar, "mlv-smart-filter-bar", never, { "definitions": { "alias": "definitions"; "required": true; "isSignal": true; }; "filters": { "alias": "filters"; "required": false; "isSignal": true; }; "visibleKeys": { "alias": "visibleKeys"; "required": false; "isSignal": true; }; "searchValue": { "alias": "searchValue"; "required": false; "isSignal": true; }; "searchTrigger": { "alias": "searchTrigger"; "required": false; "isSignal": true; }; "searchDebounce": { "alias": "searchDebounce"; "required": false; "isSignal": true; }; "filterApplyMode": { "alias": "filterApplyMode"; "required": false; "isSignal": true; }; "autoExecute": { "alias": "autoExecute"; "required": false; "isSignal": true; }; "filtersVisible": { "alias": "filtersVisible"; "required": false; "isSignal": true; }; "showSearch": { "alias": "showSearch"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "filters": "filtersChange"; "visibleKeys": "visibleKeysChange"; "searchValue": "searchValueChange"; "filtersVisible": "filtersVisibleChange"; "execute": "execute"; "refresh": "refresh"; "resetCompleted": "resetCompleted"; }, never, never, true, never>;
+}

package/filter/malva-ui-core-filter.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generated bundle index. Do not edit.
+ */
+/// <amd-module name="@malva-ui/core/filter" />
+export * from './index';

package/form/index.d.ts

@@ -0,0 +1,6 @@
+export * from './lib/form.types';
+export * from './lib/form/form';
+export * from './lib/fieldset/fieldset';
+export * from './lib/form-header';
+export * from './lib/form-actions';
+export * from './lib/fieldset-span';

package/form/lib/fieldset/fieldset.d.ts

@@ -0,0 +1,58 @@
+import type { MlvFieldsetColumns, MlvFormGap } from '../form.types';
+import * as i0 from "@angular/core";
+/**
+ * Group of related controls on a native `<fieldset>`: styled legend, optional
+ * description (wired to `aria-describedby`), and a responsive grid body.
+ *
+ * - `columns='auto'` (default): auto-fit columns of at least `minColumnWidth`.
+ * - `columns=n`: **at most** `n` columns; still collapses when the container is
+ *   narrower than `n × minColumnWidth`.
+ * - Gap inherits the surrounding `form[mlvForm]` rhythm (`--mlv-form-gap`);
+ *   `gap` overrides it for this fieldset and nested ones.
+ * - Rich headings: project a native `<legend>` instead of the `legend` input
+ *   (the input wins when both are present).
+ *
+ * @example
+ * ```html
+ * <fieldset mlvFieldset legend="Address" description="Where we ship." [columns]="2">
+ *   <mlv-input label="Street" mlvFieldsetSpan="full" />
+ *   <mlv-input label="City" />
+ *   <mlv-input label="Postal code" />
+ * </fieldset>
+ * ```
+ */
+export declare class MlvFieldset {
+    /** Element id; auto-generated (`mlv-fieldset-<n>`) unless bound. Seeds the description id. */
+    readonly id: import("@angular/core").InputSignal<string>;
+    /** Group heading rendered as `<legend class="mlv-fieldset__legend">`. Omit and project a native `<legend>` for rich content. */
+    readonly legend: import("@angular/core").InputSignal<string | undefined>;
+    /** Help text rendered under the legend and announced via `aria-describedby`. */
+    readonly description: import("@angular/core").InputSignal<string | undefined>;
+    /** `'auto'` (responsive auto-fit) or a maximum column count. Numeric strings are accepted. */
+    readonly columns: import("@angular/core").InputSignalWithTransform<MlvFieldsetColumns, string | number>;
+    /** Smallest inline size a column may shrink to before the grid drops a column. */
+    readonly minColumnWidth: import("@angular/core").InputSignal<string>;
+    /** Explicit gap for this fieldset (and nested ones); unset = inherited form rhythm / density default. */
+    readonly gap: import("@angular/core").InputSignal<MlvFormGap | undefined>;
+    /** @internal Whether `columns` is a number (capped grid). */
+    protected readonly _capped: import("@angular/core").Signal<boolean>;
+    /** @internal Id of the description paragraph, `<id>-description`. */
+    protected readonly _descriptionId: import("@angular/core").Signal<string>;
+    /**
+     * @private A static `aria-describedby` authored by the consumer, read once at
+     * construction (before the host binding takes the attribute over). `null` when
+     * absent or blank. A *bound* `[attr.aria-describedby]` is not supported — the
+     * host binding owns the attribute from the first change detection run.
+     */
+    private readonly _authoredDescribedBy;
+    /**
+     * @internal Host `aria-describedby`: the rendered description id (when
+     * `description` is set) merged with any consumer-authored value, `null` when
+     * neither is present.
+     */
+    protected readonly _describedBy: import("@angular/core").Signal<string | null>;
+    /** @internal Inline `--mlv-form-gap` value, `null` when unset. */
+    protected readonly _gapValue: import("@angular/core").Signal<string | null>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvFieldset, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MlvFieldset, "fieldset[mlvFieldset]", never, { "id": { "alias": "id"; "required": false; "isSignal": true; }; "legend": { "alias": "legend"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "columns": { "alias": "columns"; "required": false; "isSignal": true; }; "minColumnWidth": { "alias": "minColumnWidth"; "required": false; "isSignal": true; }; "gap": { "alias": "gap"; "required": false; "isSignal": true; }; }, {}, never, ["legend", "*"], true, never>;
+}

package/form/lib/fieldset-span.d.ts

@@ -0,0 +1,28 @@
+import * as i0 from "@angular/core";
+/** Column span of a fieldset grid child: a column count or the whole row. */
+export type MlvFieldsetSpanValue = number | 'full';
+/**
+ * Makes a direct child of a `fieldset[mlvFieldset]` grid span several columns.
+ *
+ * `'full'` (`grid-column: 1 / -1`) is safe in every grid. A numeric span is
+ * `grid-column: span n` — in an auto-fit grid that collapsed to fewer than `n`
+ * columns it creates implicit columns and overflows, so prefer `'full'` there
+ * and reserve numbers for `[columns]="n"` grids wide enough to hold them.
+ *
+ * @example
+ * ```html
+ * <fieldset mlvFieldset [columns]="2">
+ *   <mlv-input label="Street" mlvFieldsetSpan="full" />
+ *   <mlv-input label="City" />
+ *   <mlv-input label="Postal code" />
+ * </fieldset>
+ * ```
+ */
+export declare class MlvFieldsetSpan {
+    /** Column span: a positive integer (also as a string) or `'full'` for the whole row. */
+    readonly mlvFieldsetSpan: import("@angular/core").InputSignalWithTransform<MlvFieldsetSpanValue, string | number>;
+    /** @internal Resolved `grid-column` value. */
+    protected readonly _gridColumn: import("@angular/core").Signal<string>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvFieldsetSpan, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvFieldsetSpan, "[mlvFieldsetSpan]", never, { "mlvFieldsetSpan": { "alias": "mlvFieldsetSpan"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}

package/form/lib/form/form.d.ts

@@ -0,0 +1,37 @@
+import type { MlvFormGap } from '../form.types';
+import * as i0 from "@angular/core";
+import * as i1 from "@malva-ui/cdk/density";
+/**
+ * Layout shell for a native `<form>`: vertical stack with a density-scaled gap,
+ * and the density source for everything inside it.
+ *
+ * - `mlvDensity` (host directive) stamps `mlv-form--<density>` for cascade-only
+ *   controls **and** provides `MLV_DENSITY_CONTEXT` for directive-bearing ones
+ *   (buttons, selects, chips…), so one attribute sizes the whole form.
+ * - `gap` overrides the rhythm explicitly; `--mlv-form-gap` is the CSS hook.
+ *
+ * @example
+ * ```html
+ * <form mlvForm mlvDensity="compact" maxWidth="32rem" [formGroup]="form">
+ *   <mlv-input formControlName="name" label="Name" />
+ *   <footer mlvFormActions align="end"><button mlvButton type="submit">Save</button></footer>
+ * </form>
+ * ```
+ */
+export declare class MlvForm {
+    /**
+     * Explicit rhythm between the form's direct children (and, by inheritance,
+     * inside every `mlvFieldset`). Unset = density-scaled default
+     * (tight 0.5rem → airy 1.5rem).
+     */
+    readonly gap: import("@angular/core").InputSignal<MlvFormGap | undefined>;
+    /** Caps the form's inline size (`max-inline-size`), e.g. `'32rem'`. */
+    readonly maxWidth: import("@angular/core").InputSignal<string | undefined>;
+    /**
+     * @internal Inline `--mlv-form-gap` value; `null` removes the override so the
+     * stylesheet's density-scaled default applies.
+     */
+    protected readonly _gapValue: import("@angular/core").Signal<string | null>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvForm, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MlvForm, "form[mlvForm]", never, { "gap": { "alias": "gap"; "required": false; "isSignal": true; }; "maxWidth": { "alias": "maxWidth"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof i1.MlvDensityDirective; inputs: { "mlvDensity": "mlvDensity"; }; outputs: {}; }]>;
+}

package/form/lib/form-actions.d.ts

@@ -0,0 +1,20 @@
+import type { MlvFormActionsAlign } from './form.types';
+import * as i0 from "@angular/core";
+/**
+ * Marks the actions row of a `form[mlvForm]` (submit / cancel buttons): a
+ * wrapping flex row with the standard button gap.
+ *
+ * @example
+ * ```html
+ * <footer mlvFormActions align="end">
+ *   <button mlvButton variant="secondary" type="button">Cancel</button>
+ *   <button mlvButton type="submit">Save</button>
+ * </footer>
+ * ```
+ */
+export declare class MlvFormActions {
+    /** Horizontal distribution of the actions. `'start'` (default) hugs the start edge. */
+    readonly align: import("@angular/core").InputSignal<MlvFormActionsAlign>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvFormActions, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvFormActions, "[mlvFormActions]", never, { "align": { "alias": "align"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}

package/form/lib/form-gap.d.ts

@@ -0,0 +1,5 @@
+import type { MlvFormGap } from './form.types';
+/**
+ * @internal Resolves a gap step to the CSS value written into `--mlv-form-gap`.
+ */
+export declare function mlvFormGapValue(gap: MlvFormGap): string;

package/form/lib/form-header.d.ts

@@ -0,0 +1,18 @@
+import * as i0 from "@angular/core";
+/**
+ * Marks the title row of a `form[mlvForm]`: a wrapping flex row that keeps a
+ * heading (`h*[mlvTitle]`) on the start side and accessories (badges,
+ * segmented controls) on the end side.
+ *
+ * @example
+ * ```html
+ * <header mlvFormHeader>
+ *   <h2 mlvTitle>Registration</h2>
+ *   <mlv-badge tone="info" muted>Step 1 of 3</mlv-badge>
+ * </header>
+ * ```
+ */
+export declare class MlvFormHeader {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvFormHeader, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvFormHeader, "[mlvFormHeader]", never, {}, {}, never, never, true, never>;
+}

package/form/lib/form.types.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Explicit rhythm override for `form[mlvForm]` / `fieldset[mlvFieldset]`.
+ * Maps onto the spacing scale: `xs` 0.5rem, `s` 0.75rem, `m` 1rem, `l` 1.25rem,
+ * `xl` 1.5rem. Unset = density-scaled default.
+ */
+export type MlvFormGap = 'xs' | 's' | 'm' | 'l' | 'xl';
+/**
+ * Column mode of `fieldset[mlvFieldset]`: `'auto'` = responsive auto-fit,
+ * a number = maximum column count (still collapses when narrow).
+ */
+export type MlvFieldsetColumns = 'auto' | number;
+/** Horizontal distribution of `[mlvFormActions]` children. */
+export type MlvFormActionsAlign = 'start' | 'end' | 'center' | 'between';

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

@@ -0,0 +1,5 @@
+/**
+ * Generated bundle index. Do not edit.
+ */
+/// <amd-module name="@malva-ui/core/form" />
+export * from './index';

package/form-utils/index.d.ts

@@ -0,0 +1,15 @@
+export * from './lib/models/form-state';
+export * from './lib/models/error-display-strategy';
+export * from './lib/models/form-control-connector';
+export * from './lib/label/label';
+export * from './lib/hint/hint';
+export * from './lib/description/description';
+export * from './lib/message/message';
+export * from './lib/form-field/form-field';
+export * from './lib/form-control-base/signal-form-control-base';
+export * from './lib/form-control-wrapper/form-control-wrapper';
+export * from './lib/form-control-wrapper/form-control-wrapper-control';
+export * from './lib/form-control-sides';
+export * from './lib/selection.service';
+export * from './lib/aria-value-bridge';
+export * from './lib/focusable-group-base';

package/form-utils/lib/aria-value-bridge.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function fromAriaValues<V>(values: readonly V[] | null | undefined, multiple: boolean): V | V[] | null;

package/form-utils/lib/description/description.d.ts

@@ -0,0 +1,16 @@
+import * as i0 from "@angular/core";
+/**
+ * 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>
+ */
+export declare class MlvDescription {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvDescription, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MlvDescription, "mlv-description", never, {}, {}, never, ["*"], true, never>;
+}

package/form-utils/lib/focusable-group-base.d.ts

@@ -0,0 +1,76 @@
+import type { Signal, WritableSignal } from '@angular/core';
+import type { FocusOrigin } from '@angular/cdk/a11y';
+import * as i0 from "@angular/core";
+/**
+ * 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).
+ */
+export 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.
+ */
+export declare abstract class MlvFocusableGroupBase<T extends MlvFocusableGroupItem> {
+    /**
+     * @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: i0.ɵɵFactoryDeclaration<MlvFocusableGroupBase<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<MlvFocusableGroupBase<any>, never, never, {}, {}, never, never, true, never>;
+}