@malva-ui/core 0.1.12 → 0.1.14

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

@@ -0,0 +1,552 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef } from '@angular/core';
+import * as _malva_ui_i18n from '@malva-ui/i18n';
+import { BooleanInput } from '@angular/cdk/coercion';
+import { MlvSelectOption } from '@malva-ui/core/dropdown';
+import { MlvSelectOptionTransform } from '@malva-ui/core/select';
+import { MlvPopupTrigger } from '@malva-ui/core/popup';
+import { MlvSearchFieldTrigger } from '@malva-ui/core/search-field';
+
+/** Operators supported by Malva's neutral filter condition model. */
+type MlvFilterOperator = 'contains' | 'not-contains' | 'starts-with' | 'ends-with' | 'equals' | 'not-equals' | 'greater-than' | 'greater-than-or-equal' | 'less-than' | 'less-than-or-equal' | 'between' | 'in' | 'not-in' | 'empty' | 'not-empty';
+/** Determines how two or more conditions for the same field are combined. */
+type MlvFilterConditionStrategy = 'and' | 'or';
+/** Controls when edits made inside a filter popover become public state. */
+type MlvFilterApplyMode = 'live' | 'explicit';
+/** Visual presentation used by the smart filter bar. */
+type MlvSmartFilterBarAppearance = 'classic' | 'query';
+/** Selectable value presented by a bounded filter. */
+interface MlvFilterOption<T = unknown> {
+    /** Visible option label. */
+    readonly label: string;
+    /** Domain value represented by the option. */
+    readonly value: T;
+    /** Whether the option is unavailable for selection. */
+    readonly disabled?: boolean;
+}
+/** One comparison applied to a field. */
+interface MlvFilterCondition<T = unknown> {
+    /** Optional stable identifier used when editing multiple conditions. */
+    readonly id?: string;
+    /** Comparison performed by this condition. */
+    readonly operator: MlvFilterOperator;
+    /** Scalar, range, or multi-value operand. */
+    readonly value: T | readonly T[] | null;
+}
+/**
+ * A recursive, backend-neutral filter tree. Groups use the same conjunction
+ * vocabulary as multi-condition field state; conditions remain keyed so a
+ * consumer can read values from any domain model.
+ */
+type MlvFilterExpression = {
+    /** Leaf comparison applied to one field. */
+    readonly kind: 'condition';
+    /** Domain key supplied to an expression value reader. */
+    readonly key: string;
+    /** Comparison performed against the value read for {@link key}. */
+    readonly condition: MlvFilterCondition;
+} | {
+    /** Recursive boolean group. */
+    readonly kind: 'group';
+    /** Combination rule applied to this group's children. */
+    readonly combinator: MlvFilterConditionStrategy;
+    /** Ordered expression children. Empty AND is true; empty OR is false. */
+    readonly children: readonly MlvFilterExpression[];
+};
+/** Editor rendered for a filter definition. */
+type MlvFilterEditor = 'options' | 'text' | 'number';
+/** Metadata describing one field in a smart filter bar. */
+interface MlvFilterDefinition<T = unknown> {
+    /** Stable field key included in execution payloads. */
+    readonly key: string;
+    /** Human-readable field label. */
+    readonly label: string;
+    /** Editor type. Defaults to `options` when options exist, otherwise `text`. */
+    readonly editor?: MlvFilterEditor;
+    /** Bounded choices for an options editor. */
+    readonly options?: readonly MlvFilterOption<T>[];
+    /** Operators available to free-text and number conditions. */
+    readonly operators?: readonly MlvFilterOperator[];
+    /** Optional user-facing labels for domain-specific operators. */
+    readonly operatorLabels?: Readonly<Partial<Record<MlvFilterOperator, string>>>;
+    /** Initial operator for a new condition. */
+    readonly defaultOperator?: MlvFilterOperator;
+    /** Whether an options editor accepts more than one value. */
+    readonly multiple?: boolean;
+    /** Whether a free-form editor can add multiple conditions. */
+    readonly allowMultipleConditions?: boolean;
+    /** Initial condition-combination strategy. Defaults to `or`. */
+    readonly conditionStrategy?: MlvFilterConditionStrategy;
+    /** Whether the field appears before users adapt the filter set. */
+    readonly defaultVisible?: boolean;
+    /** Required fields stay visible and block query execution while empty. */
+    readonly required?: boolean;
+    /** Prevents users from editing this field. */
+    readonly disabled?: boolean;
+    /** Optional editor placeholder. */
+    readonly placeholder?: string;
+}
+/** Applied conditions for one field in a smart filter bar. */
+interface MlvFilterFieldState {
+    /** Filter definition key. */
+    readonly key: string;
+    /** Conditions applied to the field. */
+    readonly conditions: readonly MlvFilterCondition[];
+    /** How multiple conditions are combined. */
+    readonly strategy: MlvFilterConditionStrategy;
+}
+/** Deeply cloned snapshot emitted when a smart filter bar executes or refreshes. */
+interface MlvFilterExecutionPayload {
+    /** Search term submitted alongside structured filters. */
+    readonly search: string;
+    /** Applied structured filters. */
+    readonly filters: readonly MlvFilterFieldState[];
+    /** Definition keys currently exposed in the bar. */
+    readonly visibleKeys: readonly string[];
+    /** Grouped expression equivalent to the flat structured filter snapshot. */
+    readonly expression: MlvFilterExpression;
+}
+
+/**
+ * Converts the flat Smart Filter Bar model to its equivalent expression tree.
+ * Empty field states are omitted because they do not constrain a flat query.
+ */
+declare function mlvFilterFieldsToExpression(fields: readonly MlvFilterFieldState[]): MlvFilterExpression;
+/**
+ * Converts an expression to flat field state only when no grouping information
+ * would be lost. Direct leaves and singleton groups are canonicalized to the
+ * semantically-neutral `and` strategy. Returns `null` for cross-field ORs,
+ * contradictory field compositions, and false (empty OR) groups.
+ */
+declare function mlvFilterExpressionToFields(expression: MlvFilterExpression): MlvFilterFieldState[] | null;
+/**
+ * Evaluates an expression using a domain-owned value reader. String predicates
+ * are case- and diacritic-insensitive; equality and membership remain strict.
+ */
+declare function mlvMatchesFilterExpression<T>(value: T, expression: MlvFilterExpression, readValue: (value: T, key: string) => unknown): boolean;
+
+/** Template context available to a custom condition value editor. */
+interface MlvFilterValueEditorContext {
+    /** Current condition value (scalar, or the range array for `between`). */
+    $implicit: unknown;
+    /** Full condition being edited. */
+    condition: MlvFilterCondition;
+    /** Condition index within the editor. */
+    index: number;
+    /** Current operator of the condition. */
+    operator: MlvFilterOperator;
+    /** Whether the editor must reject changes (filter disabled or loading). */
+    disabled: boolean;
+    /** Resolved value placeholder. */
+    placeholder: string;
+    /** Writes the draft value; commits immediately in live apply mode. */
+    setValue: (value: unknown) => void;
+    /** Applies the draft in explicit mode (Enter-equivalent). No-op in live mode. */
+    commit: () => void;
+}
+/**
+ * Marks an `ng-template` as the value editor for free-form filter conditions.
+ * Standalone `mlv-filter`: project the template as content. Inside
+ * `mlv-smart-filter-bar`: set the input to a definition key to target one
+ * field; an empty key is the fallback for every free-form field.
+ *
+ * ```html
+ * <mlv-filter label="Renewal" editor="text">
+ *   <ng-template mlvFilterValueEditor let-value let-set="setValue">
+ *     <mlv-day-picker [value]="$any(value)" (valueChange)="set($event)" />
+ *   </ng-template>
+ * </mlv-filter>
+ * ```
+ */
+declare class MlvFilterValueEditorDef {
+    /** Definition key this editor targets; empty targets all free-form fields. */
+    readonly mlvFilterValueEditor: _angular_core.InputSignal<string>;
+    /** The template rendered in place of the built-in value input. */
+    readonly templateRef: TemplateRef<any>;
+    /**
+     * Type guard for template context inference.
+     * @internal
+     */
+    static ngTemplateContextGuard(_dir: MlvFilterValueEditorDef, _ctx: unknown): _ctx is MlvFilterValueEditorContext;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvFilterValueEditorDef, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<MlvFilterValueEditorDef, "[mlvFilterValueEditor]", never, { "mlvFilterValueEditor": { "alias": "mlvFilterValueEditor"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** Visual presentation of one field filter. */
+type MlvFilterAppearance = 'field' | 'query';
+/** Compact filter trigger and in-place condition editor. */
+declare class MlvFilter {
+    /** @private Document used for conservative focus restoration. */
+    private readonly _document;
+    /** @protected Reactive translated strings for filters. */
+    protected readonly _i18n: _angular_core.Signal<_malva_ui_i18n.MlvFilterI18n>;
+    /** @private ICU resolver for parameterized translated strings. */
+    private readonly _resolver;
+    /** @private Tabbable-element lookup for focusing custom editors. */
+    private readonly _tabbable;
+    /** Visible filter name. */
+    readonly label: _angular_core.InputSignal<string>;
+    /** Optional domain key for consumers coordinating multiple filter instances. */
+    readonly key: _angular_core.InputSignal<string>;
+    /** Whether this field renders as a classic control or a natural-language chip. */
+    readonly appearance: _angular_core.InputSignal<MlvFilterAppearance>;
+    /** Whether an empty query field exposes removal instead of becoming sticky. */
+    readonly queryRemovable: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Bounded values shown as a listbox. */
+    readonly options: _angular_core.InputSignal<readonly MlvFilterOption<unknown>[]>;
+    /** Explicit editor override. Options are inferred when choices are provided. */
+    readonly editor: _angular_core.InputSignal<MlvFilterEditor | undefined>;
+    /** Whether a bounded editor accepts multiple values. */
+    readonly multiple: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Whether a free-form editor may add multiple conditions. */
+    readonly allowMultipleConditions: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Operators available to a free-form editor. */
+    readonly operators: _angular_core.InputSignal<readonly MlvFilterOperator[]>;
+    /** Optional user-facing labels for domain-specific operator vocabulary. */
+    readonly operatorLabels: _angular_core.InputSignal<Readonly<Partial<Record<MlvFilterOperator, string>>>>;
+    /** Operator assigned to a newly-created free-form condition. */
+    readonly defaultOperator: _angular_core.InputSignal<MlvFilterOperator>;
+    /** Optional placeholder for free-form values. */
+    readonly placeholder: _angular_core.InputSignal<string | undefined>;
+    /** Whether edits publish immediately or wait for the Apply action. */
+    readonly applyMode: _angular_core.InputSignal<MlvFilterApplyMode>;
+    /** Prevents opening and editing the filter. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Shows progress and prevents editing while filter metadata is loading. */
+    readonly loading: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Whether the filter trigger represents an invalid field value. */
+    readonly invalid: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Id reference describing the filter trigger's validation state. */
+    readonly ariaDescribedBy: _angular_core.InputSignal<string | undefined>;
+    /**
+     * Custom value-editor template forwarded by a smart filter bar. Wins over a
+     * projected `[mlvFilterValueEditor]` content child.
+     */
+    readonly valueEditor: _angular_core.InputSignal<TemplateRef<MlvFilterValueEditorContext> | null>;
+    /** Applied conditions. */
+    readonly conditions: _angular_core.ModelSignal<readonly MlvFilterCondition<unknown>[]>;
+    /** Combination rule used when more than one condition is present. */
+    readonly conditionStrategy: _angular_core.ModelSignal<MlvFilterConditionStrategy>;
+    /** Whether the condition editor is open. */
+    readonly opened: _angular_core.ModelSignal<boolean>;
+    /** Emitted whenever live editing or Apply commits conditions. */
+    readonly applied: _angular_core.OutputEmitterRef<readonly MlvFilterCondition<unknown>[]>;
+    /** Emitted when the clear action removes every condition. */
+    readonly cleared: _angular_core.OutputEmitterRef<void>;
+    /** @protected Unique id linking the trigger to its popup content. */
+    protected readonly _panelId: string;
+    /** @protected Height budget handed to the bounded options panel. */
+    protected readonly _optionsMaxHeight = 320;
+    /** @private Working conditions kept separate for explicit-apply mode. */
+    private readonly _draftConditions;
+    /** @private Working condition strategy kept separate until Apply. */
+    private readonly _draftStrategy;
+    /** @private Trigger element used for focus restoration. */
+    private readonly _trigger;
+    /** @private Rendered value fields used to focus the free-form editor. */
+    private readonly _conditionInputs;
+    /** @private Rendered value cells used to focus custom editors. */
+    private readonly _valueCells;
+    /** @private Projected value-editor template for standalone usage. */
+    private readonly _contentValueEditor;
+    /**
+     * @protected Resolved custom value-editor template; `null` renders the
+     * built-in input.
+     */
+    protected readonly _valueEditorTemplate: _angular_core.Signal<TemplateRef<any> | null>;
+    /** @protected Resolved editor based on the explicit input and available options. */
+    protected readonly _resolvedEditor: _angular_core.Signal<MlvFilterEditor>;
+    /** @protected Whether the current editor is a bounded options list. */
+    protected readonly _usesOptions: _angular_core.Signal<boolean>;
+    /** @protected Whether an open editor must reject every state-changing action. */
+    protected readonly _editorDisabled: _angular_core.Signal<boolean>;
+    /**
+     * @protected Bounded options mapped to the dropdown panel's option shape. A
+     * locked editor (disabled or loading) marks every row disabled, so a panel
+     * that is already open when loading starts stops offering picks it would
+     * silently reject.
+     */
+    protected readonly _panelOptions: _angular_core.Signal<MlvSelectOption<unknown>[]>;
+    /** @protected Values currently selected in the draft, for the dropdown panel. */
+    protected readonly _selectedValues: _angular_core.Signal<unknown[]>;
+    /** @protected Valid new-condition operator, constrained to the allowed list. */
+    protected readonly _resolvedDefaultOperator: _angular_core.Signal<MlvFilterOperator>;
+    /** @protected Snapshot used by the editor template. */
+    protected readonly _draft: _angular_core.Signal<MlvFilterCondition<unknown>[]>;
+    /** @protected Draft strategy used by the editor template. */
+    protected readonly _strategy: _angular_core.Signal<MlvFilterConditionStrategy>;
+    /** @protected Resolved value placeholder with an i18n fallback. */
+    protected readonly _resolvedPlaceholder: _angular_core.Signal<string>;
+    /** @protected Operator-to-select-option adapter. */
+    protected readonly _operatorTransform: MlvSelectOptionTransform<MlvFilterOperator>;
+    /** @protected Strategy-to-select-option adapter. */
+    protected readonly _strategyTransform: MlvSelectOptionTransform<MlvFilterConditionStrategy>;
+    /** @protected Strategies available when multiple conditions exist. */
+    protected readonly _strategies: readonly MlvFilterConditionStrategy[];
+    /** @protected Number of selected scalar values represented by the conditions. */
+    protected readonly valueCount: _angular_core.Signal<number>;
+    /** @protected Whether at least one meaningful condition is applied. */
+    protected readonly hasValue: _angular_core.Signal<boolean>;
+    /** @protected First applied value rendered in the compact trigger. */
+    protected readonly primaryValue: _angular_core.Signal<string>;
+    /** @protected Number of values hidden behind the `+ n more` summary. */
+    protected readonly additionalValueCount: _angular_core.Signal<number>;
+    /** @protected Accessible description of the current applied state. */
+    protected readonly _triggerAriaLabel: _angular_core.Signal<string>;
+    /** @protected Translated accessible label for the clear action. */
+    protected readonly _clearAriaLabel: _angular_core.Signal<string>;
+    /** @protected Whether the compact clear/remove action should be shown. */
+    protected readonly _showsClearAction: _angular_core.Signal<boolean>;
+    /** @protected Full natural-language summary used by a query chip. */
+    protected readonly _querySentence: _angular_core.Signal<string>;
+    /** @protected Translated compact summary for values beyond the first. */
+    protected readonly _moreValuesLabel: _angular_core.Signal<string>;
+    constructor();
+    /** @protected Prepares and focuses the editor after the overlay attaches. */
+    protected _onOpened(): void;
+    /** @protected Resynchronises drafts and restores focus after a keyboard/action close. */
+    protected _onClosed(): void;
+    /** @protected Removes all applied and in-progress values. */
+    protected _clear(event?: Event): void;
+    /** @protected Clears the editor draft while preserving explicit-mode rollback. */
+    protected _clearDraft(): void;
+    /** @protected Discards uncommitted edits and closes the editor. */
+    protected _cancel(): void;
+    /** @protected Commits meaningful draft conditions and closes the editor. */
+    protected _apply(): void;
+    /**
+     * @protected Applies a dropdown-panel selection to the draft.
+     *
+     * `@angular/aria`'s listbox owns a `value` model that it reconciles against
+     * the options actually *registered* in the DOM, and it re-emits `valueChange`
+     * from that reconciliation — not only when a user picks. Two kinds of noise
+     * therefore have to be filtered out before anything may rewrite the draft:
+     *
+     * 1. An emit that restates the selection unchanged.
+     * 2. An emit that drops committed values whose option is not rendered — async
+     *    options that have not arrived, a saved view restored ahead of its
+     *    choices, a value whose option was removed. Left unguarded this silently
+     *    wipes committed conditions the moment the popover opens.
+     */
+    protected _onOptionValuesChange(values: readonly unknown[]): void;
+    /** @protected Updates one condition's operator. */
+    protected _setOperator(index: number, operator: MlvFilterOperator): void;
+    /** @protected Updates one condition's operand. */
+    protected _setConditionValue(index: number, value: unknown): void;
+    /** @protected Builds the template context for one condition's custom editor. */
+    protected _valueEditorContext(condition: MlvFilterCondition, index: number): MlvFilterValueEditorContext;
+    /** @protected Returns one side of a between-condition range. */
+    protected _conditionRangeValue(condition: MlvFilterCondition, rangeIndex: number): unknown;
+    /** @protected Updates one side of a between-condition range. */
+    protected _setConditionRangeValue(conditionIndex: number, rangeIndex: number, value: unknown): void;
+    /** @protected Updates the combination rule for working conditions. */
+    protected _setStrategy(strategy: MlvFilterConditionStrategy): void;
+    /** @protected Adds another free-form condition and focuses it. */
+    protected _addCondition(): void;
+    /** @protected Removes one working condition. */
+    protected _removeCondition(index: number): void;
+    /**
+     * @private First focusable control rendered inside a value cell. The CDK
+     * interactivity checker requires layout geometry, so a plain selector query
+     * takes over whenever it reports nothing focusable.
+     */
+    private _firstFocusableIn;
+    /** @private Creates an empty free-form condition. */
+    private _newCondition;
+    /** @private Publishes draft state immediately when live mode is active. */
+    private _commitLive;
+    /** @private Normalizes number-editor input while preserving empty/invalid drafts. */
+    private _normalizeValue;
+    /** @private Converts applied operands into compact, human-readable labels. */
+    private _displayValues;
+    /** @private Whether a condition has an operator-complete operand. */
+    private _isConditionMeaningful;
+    /** @private Resolves translated labels for built-in operators. */
+    private _operatorLabel;
+    /** @private Resolves one ICU message from the filter translation slice. */
+    private _resolveMessage;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvFilter, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvFilter, "mlv-filter", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": false; "isSignal": true; }; "appearance": { "alias": "appearance"; "required": false; "isSignal": true; }; "queryRemovable": { "alias": "queryRemovable"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "editor": { "alias": "editor"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "allowMultipleConditions": { "alias": "allowMultipleConditions"; "required": false; "isSignal": true; }; "operators": { "alias": "operators"; "required": false; "isSignal": true; }; "operatorLabels": { "alias": "operatorLabels"; "required": false; "isSignal": true; }; "defaultOperator": { "alias": "defaultOperator"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "applyMode": { "alias": "applyMode"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "ariaDescribedBy": { "alias": "ariaDescribedBy"; "required": false; "isSignal": true; }; "valueEditor": { "alias": "valueEditor"; "required": false; "isSignal": true; }; "conditions": { "alias": "conditions"; "required": false; "isSignal": true; }; "conditionStrategy": { "alias": "conditionStrategy"; "required": false; "isSignal": true; }; "opened": { "alias": "opened"; "required": false; "isSignal": true; }; }, { "conditions": "conditionsChange"; "conditionStrategy": "conditionStrategyChange"; "opened": "openedChange"; "applied": "applied"; "cleared": "cleared"; }, ["_contentValueEditor"], never, true, never>;
+}
+
+/** Metadata-driven query header for search, field filters, and execution. */
+declare class MlvSmartFilterBar {
+    /** @protected Reactive translated strings for filters. */
+    protected readonly _i18n: _angular_core.Signal<_malva_ui_i18n.MlvFilterI18n>;
+    /** @private ICU resolver for parameterized translated strings. */
+    private readonly _resolver;
+    /** @private Injector required by post-overlay render focus restoration. */
+    private readonly _injector;
+    /** Metadata for every available filter field. */
+    readonly definitions: _angular_core.InputSignal<readonly MlvFilterDefinition<unknown>[]>;
+    /** Structured filter state. */
+    readonly filters: _angular_core.ModelSignal<readonly MlvFilterFieldState[]>;
+    /** Whether the bar renders its established toolbar or natural-language query row. */
+    readonly appearance: _angular_core.InputSignal<MlvSmartFilterBarAppearance>;
+    /** Keys currently shown in the filter row. */
+    readonly visibleKeys: _angular_core.ModelSignal<readonly string[]>;
+    /** Global search query submitted with structured filters. */
+    readonly searchValue: _angular_core.ModelSignal<string>;
+    /** Commit behavior for the global search field. */
+    readonly searchTrigger: _angular_core.InputSignal<MlvSearchFieldTrigger>;
+    /** Debounce passed to the global live-search field. */
+    readonly searchDebounce: _angular_core.InputSignalWithTransform<number, string | number>;
+    /** Apply behavior used by each field filter editor. */
+    readonly filterApplyMode: _angular_core.InputSignal<MlvFilterApplyMode>;
+    /** Whether live search/filter commits should execute immediately. */
+    readonly autoExecute: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Whether structured fields are expanded beneath the query actions. */
+    readonly filtersVisible: _angular_core.ModelSignal<boolean>;
+    /** Whether the global search field is rendered. */
+    readonly showSearch: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Whether query execution is in progress. */
+    readonly loading: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Whether every control in the bar is unavailable. */
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Emitted with an immutable snapshot when the query executes. */
+    readonly execute: _angular_core.OutputEmitterRef<MlvFilterExecutionPayload>;
+    /** Emitted when consumers should refresh using the current query snapshot. */
+    readonly refresh: _angular_core.OutputEmitterRef<MlvFilterExecutionPayload>;
+    /** Emitted after search, filter values, and visibility return to defaults. */
+    readonly resetCompleted: _angular_core.OutputEmitterRef<void>;
+    /** @protected Search term used only inside the available-filters manager. */
+    protected readonly _availableSearch: _angular_core.WritableSignal<string>;
+    /** @private Optional blank fields deliberately selected through query Add filter. */
+    private readonly _queryAddedKeys;
+    /** @private Added key awaiting focus after its popup has detached. */
+    private readonly _pendingAddedKey;
+    /** @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 Query Add filter popup panel focused after it opens. */
+    private readonly _addPanel;
+    /** @private Query Add filter trigger used when the pending field disappears. */
+    private readonly _addButton;
+    /** @private Rendered filter hosts used to focus the first invalid field. */
+    private readonly _filterHosts;
+    /** @private Projected custom value-editor templates, matched to definitions by key. */
+    private readonly _valueEditors;
+    /** Visible definitions in stable metadata order. */
+    readonly visibleDefinitions: _angular_core.Signal<MlvFilterDefinition<unknown>[]>;
+    /** @protected Query chips represent required, meaningful, or deliberately added blank fields. */
+    protected readonly _queryDefinitions: _angular_core.Signal<MlvFilterDefinition<unknown>[]>;
+    /** @protected Definitions that may be added without creating duplicate or disabled fields. */
+    protected readonly _addableDefinitions: _angular_core.Signal<MlvFilterDefinition<unknown>[]>;
+    /** Number of filter fields currently visible. */
+    readonly visibleFilterCount: _angular_core.Signal<number>;
+    /** Number of fields with at least one applied condition. */
+    readonly appliedFilterCount: _angular_core.Signal<number>;
+    /** @protected Required definitions without an applied, meaningful condition. */
+    protected readonly _missingRequiredDefinitions: _angular_core.Signal<MlvFilterDefinition<unknown>[]>;
+    /** @protected Whether required-field errors should currently be rendered. */
+    protected readonly _showRequiredErrors: _angular_core.Signal<boolean>;
+    /** @protected Whether search or any structured condition is active. */
+    protected readonly _hasState: _angular_core.Signal<boolean>;
+    /** @protected Definitions matching the available-filter search. */
+    protected readonly _filteredDefinitions: _angular_core.Signal<readonly MlvFilterDefinition<unknown>[]>;
+    /** @protected Parameterized label for the filter-management action. */
+    protected readonly _filtersLabel: _angular_core.Signal<string>;
+    /** @protected Parameterized status for fields with applied values. */
+    protected readonly _appliedFiltersLabel: _angular_core.Signal<string>;
+    /** @protected Parameterized heading for the available-filter list. */
+    protected readonly _availableFiltersLabel: _angular_core.Signal<string>;
+    /** @protected Localized validation summary for all missing required fields. */
+    protected readonly _requiredFiltersMessage: _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 Focuses the searchable Add filter menu after its popup attaches. */
+    protected _onAddOpened(): void;
+    /** @protected Clears transient Add filter search after its popup closes. */
+    protected _onAddClosed(): void;
+    /** @protected Adds visibility only, then sends focus to the newly rendered field trigger. */
+    protected _addQueryFilter(definition: MlvFilterDefinition, trigger: MlvPopupTrigger): void;
+    /** @protected Removes an optional query field's state and visibility. */
+    protected _removeQueryFilter(definition: MlvFilterDefinition): void;
+    /** @protected Clears search and all optional query fields while retaining required visibility. */
+    protected _clearQuery(): void;
+    /** @protected Returns applied conditions for a definition key. */
+    protected _conditionsFor(key: string): readonly MlvFilterCondition[];
+    /** @protected Resolves the value-editor template for one definition (exact key > key-less fallback > null). */
+    protected _valueEditorFor(definition: MlvFilterDefinition): TemplateRef<MlvFilterValueEditorContext> | null;
+    /** @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: _angular_core.ɵɵFactoryDeclaration<MlvSmartFilterBar, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvSmartFilterBar, "mlv-smart-filter-bar", never, { "definitions": { "alias": "definitions"; "required": true; "isSignal": true; }; "filters": { "alias": "filters"; "required": false; "isSignal": true; }; "appearance": { "alias": "appearance"; "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"; }, ["_valueEditors"], never, true, never>;
+}
+
+export { MlvFilter, MlvFilterValueEditorDef, MlvSmartFilterBar, mlvFilterExpressionToFields, mlvFilterFieldsToExpression, mlvMatchesFilterExpression };
+export type { MlvFilterApplyMode, MlvFilterCondition, MlvFilterConditionStrategy, MlvFilterDefinition, MlvFilterEditor, MlvFilterExecutionPayload, MlvFilterExpression, MlvFilterFieldState, MlvFilterOperator, MlvFilterOption, MlvFilterValueEditorContext, MlvSmartFilterBarAppearance };

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

@@ -0,0 +1,50 @@
+/**
+ * One binding mode's view of the form side while running the bindings matrix.
+ * Concrete adapters are built by the control's spec for each of the three
+ * binding modes (reactive `[formControl]`, template-driven `ngModel`, signal
+ * forms `[formField]`), so the shared {@link verifyFormsBinding} assertions
+ * stay identical across modes and across controls.
+ */
+interface MlvFormsBindingAdapter<T> {
+    /** Mode label used in assertion messages. */
+    readonly mode: 'reactive' | 'template-driven' | 'signal-forms';
+    /** Writes a value from the FORM side into the control. */
+    setValue(value: T): void | Promise<void>;
+    /** Reads the form side's current value. */
+    getValue(): T;
+    /** Whether the form side considers the control touched. */
+    isTouched(): boolean;
+    /** Disables from the form side. Omit when the mode cannot express it. */
+    setDisabled?(disabled: boolean): void | Promise<void>;
+    /** Whether the COMPONENT reports disabled (e.g. `computedDisabled()`). */
+    isDisabled?(): boolean;
+}
+/**
+ * Options for one {@link verifyFormsBinding} run.
+ */
+interface MlvFormsBindingMatrixOptions<T> {
+    /** The mode adapter under test. */
+    adapter: MlvFormsBindingAdapter<T>;
+    /** Value written from the form side; must round-trip unchanged. */
+    sample: T;
+    /**
+     * Simulates a USER interaction on the rendered control that must surface on
+     * the form side as {@link expectedAfterInteraction}.
+     */
+    interact: () => void | Promise<void>;
+    /** Form-side value expected after {@link interact}. */
+    expectedAfterInteraction: T;
+    /** Simulates the user leaving the field; drives the touched assertion. */
+    blur?: () => void | Promise<void>;
+}
+/**
+ * Shared assertion driver for the forms bindings matrix: form→control value
+ * write, control→form user interaction, touched propagation on blur, and
+ * disabled propagation — identical expectations for every binding mode. A
+ * control's spec calls this once per mode; a migrated control (CVA →
+ * FormValueControl) must keep all three runs green.
+ */
+declare function verifyFormsBinding<T>(options: MlvFormsBindingMatrixOptions<T>): Promise<void>;
+
+export { verifyFormsBinding };
+export type { MlvFormsBindingAdapter, MlvFormsBindingMatrixOptions };