@malva-ui/core 0.1.13 → 0.1.14

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

@@ -0,0 +1,592 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef, Signal, PipeTransform } from '@angular/core';
+import { BooleanInput } from '@angular/cdk/coercion';
+import { MlvArrayDataSource, MlvDataSource } from '@malva-ui/cdk/data-source';
+import { Observable } from 'rxjs';
+export { normalizeForMatch } from '@malva-ui/cdk/utils';
+
+interface MlvSelectOption<T = unknown> {
+    label: string;
+    value: T;
+    /**
+     * Optional group label. When one or more options in an array carry a
+     * (non-empty) `group`, the dropdown panel clusters consecutive options that
+     * share the same `group` value under a sticky, **non-selectable** section
+     * header bearing this text (APG listbox grouping: `role="group"` +
+     * `aria-labelledby`).
+     *
+     * Group headers are purely presentational. They are:
+     * - skipped by keyboard navigation and type-ahead (they are not aria options);
+     * - excluded from a combobox's filtered result set — a header shows only when
+     *   at least one of its options matches the current filter;
+     * - never part of the control's value (a header is not a `MlvSelectOption`).
+     *
+     * Only honoured for `MlvSelectOption`-shaped options. Plain primitive arrays go
+     * through {@link defaultOptionTransform}, never carry a `group`, and therefore
+     * render exactly as an ungrouped list. Options without a `group` (or with an
+     * empty string) render ungrouped.
+     */
+    group?: string;
+    /**
+     * Whether the option is unavailable for selection. Rendered as
+     * `aria-disabled` on the option row and skipped by keyboard navigation
+     * (the dropdown panel pins `[softDisabled]="false"`). Clicking a disabled
+     * row does not change the selection.
+     */
+    disabled?: boolean;
+}
+type MlvSelectOptionTransform<T> = (item: T) => MlvSelectOption<T>;
+declare function defaultOptionTransform<T>(item: T): MlvSelectOption<T>;
+declare function isSelectOption<T>(value: unknown): value is MlvSelectOption<T>;
+/**
+ * Type-guard predicate: whether an array of resolved options is "grouped",
+ * i.e. at least one option carries a non-empty {@link MlvSelectOption.group} label.
+ *
+ * The dropdown panel uses this to decide whether to render sticky group headers.
+ * Returns `false` for empty arrays and for arrays where no option declares a
+ * group, so ungrouped `MlvSelectOption` arrays (and plain primitive arrays) render
+ * exactly as before.
+ */
+declare function hasOptionGroups<T>(options: readonly MlvSelectOption<T>[]): boolean;
+declare function resolveOptions<T>(items: T[], transform: MlvSelectOptionTransform<T>): MlvSelectOption<T>[];
+
+/**
+ * One option within a rendered group, paired with its flat index into the
+ * panel's `options()` array. The flat index (not a group-local index) is what
+ * the panel forwards to {@link MlvDropdownPanel.optionId} and matches
+ * against `activeIndex`, so an owning combobox's activedescendant model stays
+ * aligned regardless of grouping.
+ */
+interface DropdownOptionEntry<T> {
+    readonly option: MlvSelectOption<T>;
+    readonly index: number;
+}
+/**
+ * A rendered cluster of consecutive options that share the same group label.
+ * `label`/`headerId` are `null` for an ungrouped (headerless) run.
+ */
+interface DropdownOptionGroup<T> {
+    readonly label: string | null;
+    readonly headerId: string | null;
+    readonly entries: DropdownOptionEntry<T>[];
+}
+declare class MlvDropdownPanel<T> {
+    /**
+     * Chooses the single scroll owner for this panel.
+     *
+     * Standalone panels scroll themselves. Panels composed inside `mlv-popup`
+     * delegate to the popup so the DOM never contains nested scroll regions.
+     */
+    readonly scrollMode: _angular_core.InputSignal<"self" | "parent">;
+    readonly minHeight: _angular_core.InputSignal<number>;
+    readonly maxHeight: _angular_core.InputSignal<number>;
+    readonly options: _angular_core.InputSignal<MlvSelectOption<T>[]>;
+    /** Whether multiple options can be selected. */
+    readonly multiple: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    readonly selectedValues: _angular_core.InputSignal<T[]>;
+    readonly itemTemplate: _angular_core.InputSignal<TemplateRef<{
+        $implicit: MlvSelectOption<T>;
+    }> | null>;
+    /**
+     * Focus strategy forwarded to the inner aria listbox.
+     *
+     * - `'roving'` (default) — DOM focus moves onto the active option (`tabindex`).
+     *   Used by `mlv-select`.
+     * - `'activedescendant'` — DOM focus stays on the owning trigger/input; the
+     *   active option is tracked via `aria-activedescendant`. Used by
+     *   `mlv-combobox`, whose text input must retain focus so typing keeps
+     *   working while navigating options.
+     */
+    readonly focusMode: _angular_core.InputSignal<"roving" | "activedescendant">;
+    /**
+     * Index of the option that is visually "active" (highlighted) under the
+     * activedescendant model. `-1` (default) means no active option. The panel
+     * renders a deterministic `[id]` on each option (`<listboxId>-option-<index>`)
+     * so an owning combobox can point its input's `aria-activedescendant` at the
+     * active row and keep the highlight in sync.
+     */
+    readonly activeIndex: _angular_core.InputSignal<number>;
+    /**
+     * Optional HTML `id` to assign to the inner `<mlv-list>` listbox element.
+     * Allows a parent combobox or select to reference this listbox via `aria-controls`.
+     */
+    readonly listboxId: _angular_core.InputSignal<string | null>;
+    /**
+     * Accessible name rendered as `aria-label` on the inner listbox. `role="listbox"`
+     * is an ARIA input field, so a panel that is not already named through an owning
+     * control (`mlv-filter`'s popover, for instance) needs one to satisfy WCAG 4.1.2.
+     * `null` (default) renders no attribute.
+     */
+    readonly ariaLabel: _angular_core.InputSignal<string | null>;
+    /**
+     * When non-empty, the default option row emphasises the matched substring of
+     * this query inside each suggestion label (case- and diacritic-insensitive;
+     * see {@link MlvHighlightMatchPipe}). Ignored for rows rendered by a custom
+     * {@link itemTemplate}. Empty (default) renders the label as plain text —
+     * ungrouped, un-highlighted lists are byte-for-byte unchanged.
+     */
+    readonly highlightQuery: _angular_core.InputSignal<string>;
+    /**
+     * When `true`, the panel renders a loading affordance instead of the option
+     * list / empty state — used by `[mlvAutocomplete]` while an async `search`
+     * resolves. The {@link loadingText} is announced politely.
+     */
+    readonly loading: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Text shown (and announced) inside the loading affordance while
+     * {@link loading} is `true`. Localise by binding a translated string.
+     * @default 'Loading…'
+     */
+    readonly loadingText: _angular_core.InputSignal<string>;
+    /**
+     * When `true`, a page beyond the first is being fetched: renders a polite
+     * bottom status row (`loadingText`) after the last option. The listbox and
+     * existing options stay interactive.
+     * @default false
+     */
+    readonly loadingMore: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /**
+     * Whether more pages exist. When `true` the panel observes its scroll owner
+     * and emits {@link loadMore} as the user nears the end of the list.
+     * @default false
+     */
+    readonly hasMore: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Distance (px) from the end of the scroll owner at which {@link loadMore} fires. */
+    readonly infiniteScrollThreshold: _angular_core.InputSignal<number>;
+    /** Emits when the user scrolls within `infiniteScrollThreshold` of the end while `hasMore`. */
+    readonly loadMore: _angular_core.OutputEmitterRef<void>;
+    /**
+     * @protected Effective listbox id forwarded to the aria `Listbox.id` input on
+     * the inner `<mlv-list>`. Uses the consumer-provided {@link listboxId} when
+     * set, otherwise a stable generated fallback so the rendered listbox always
+     * carries a valid unique DOM id (aria would otherwise mint its own, breaking
+     * a parent trigger's `aria-controls` linkage).
+     */
+    protected readonly _resolvedListboxId: _angular_core.Signal<string>;
+    /** @private Stable generated id used when no `listboxId` is supplied. */
+    private readonly _fallbackListboxId;
+    /**
+     * @protected Whether the current options declare groups (at least one option
+     * carries a non-empty `group`). When `false` the template renders the exact
+     * flat option list as before — plain / ungrouped arrays are unaffected.
+     */
+    protected readonly _isGrouped: _angular_core.Signal<boolean>;
+    /**
+     * @protected The options clustered into consecutive same-group runs for
+     * rendering under sticky headers. Consecutive-run grouping (no reordering)
+     * keeps DOM order identical to the flat `options()` order, so option indices,
+     * `optionId`, `activeIndex`, and aria's DOM-order navigation all stay aligned.
+     * Each entry retains its flat index into `options()`. A run of options without
+     * a group (empty/undefined) becomes a headerless cluster (`label: null`).
+     */
+    protected readonly _groups: _angular_core.Signal<DropdownOptionGroup<T>[]>;
+    /** @protected Effective max panel height in px — the `maxHeight` input when set, else the viewport-derived default. */
+    protected readonly _calculatedMaxHeight: _angular_core.Signal<number>;
+    readonly valueChange: _angular_core.OutputEmitterRef<readonly T[]>;
+    /** @private Selection service coordinating focus-first requests from a parent select/combobox. */
+    private readonly _selectionService;
+    /** @private Set of currently selected values for O(1) membership checks. */
+    private readonly _selectedSet;
+    /** @private Default max panel height (px) derived from the viewport height. */
+    private readonly _defaultMaxHeight;
+    /** @private The inner selectable list directive, used to move focus to the first option. */
+    private readonly _listSelectable;
+    /** @private The panel's own scrollbar (`scrollMode="self"` only). */
+    private readonly _scrollbar;
+    /** @private The sentinel-hosted infinite-scroll directive, re-checked after each option append. */
+    private readonly _infiniteScroll;
+    /**
+     * @protected The element that actually scrolls: the panel's own scrollbar
+     * viewport (`scrollMode="self"`) or the nearest ancestor `mlv-scrollbar`
+     * viewport — the owning `mlv-popup`'s — in parent mode. Resolved after the
+     * first render; the sentinel directive stays disabled until then.
+     */
+    protected readonly _scrollContainer: _angular_core.WritableSignal<HTMLElement | null>;
+    /**
+     * @private Whether the scroll-owner lookup has already run. It needs the first
+     * render, so a `null` {@link _scrollContainer} before that means "not resolved
+     * yet", not "no owner" — the dev warning must not fire on it.
+     */
+    private readonly _scrollOwnerResolved;
+    /** @private Latches the dev-mode "no scroll owner" warning to once per panel. */
+    private _warnedNoScrollOwner;
+    /** @private Host element, used to scroll the active option into view (activedescendant model). */
+    private readonly _host;
+    /** @private Angular-provided document used to access the browser viewport safely. */
+    private readonly _document;
+    constructor();
+    isValueSelected(value: T): boolean;
+    /**
+     * Deterministic DOM `id` for the option at `index`, forwarded to aria's
+     * `ngOption` id. An owning combobox computes the same id (via the shared
+     * {@link optionId} helper) to wire its input's `aria-activedescendant`.
+     */
+    optionId(index: number): string;
+    /**
+     * Re-emits the aria listbox selection. `@angular/aria`'s `ngListbox` emits the
+     * selected values array directly (unlike CdkListbox's `ListboxValueChangeEvent`).
+     */
+    onValueChange(values: readonly T[]): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvDropdownPanel<any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MlvDropdownPanel<any>, "mlv-dropdown-panel", never, { "scrollMode": { "alias": "scrollMode"; "required": false; "isSignal": true; }; "minHeight": { "alias": "minHeight"; "required": false; "isSignal": true; }; "maxHeight": { "alias": "maxHeight"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "selectedValues": { "alias": "selectedValues"; "required": false; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; "isSignal": true; }; "focusMode": { "alias": "focusMode"; "required": false; "isSignal": true; }; "activeIndex": { "alias": "activeIndex"; "required": false; "isSignal": true; }; "listboxId": { "alias": "listboxId"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "highlightQuery": { "alias": "highlightQuery"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "loadingText": { "alias": "loadingText"; "required": false; "isSignal": true; }; "loadingMore": { "alias": "loadingMore"; "required": false; "isSignal": true; }; "hasMore": { "alias": "hasMore"; "required": false; "isSignal": true; }; "infiniteScrollThreshold": { "alias": "infiniteScrollThreshold"; "required": false; "isSignal": true; }; }, { "loadMore": "loadMore"; "valueChange": "valueChange"; }, never, ["*"], true, never>;
+}
+
+/**
+ * A contiguous slice of a label produced by {@link matchSegments}, tagged with
+ * whether it is part of the query match. Rendered by consumers (e.g. the
+ * dropdown panel's suggestion highlighting) as `<mark>` for matched slices and
+ * plain text otherwise.
+ */
+interface MlvMatchSegment {
+    /** The original (non-folded) label text for this slice. */
+    readonly text: string;
+    /** Whether this slice is part of the matched query substring. */
+    readonly matched: boolean;
+}
+/**
+ * Predicate deciding whether an option satisfies the current query. The default
+ * ({@link defaultOptionMatcher}) is a case- and diacritic-insensitive substring
+ * match on the option label. Provide a custom matcher to a combobox / the
+ * `[mlvAutocomplete]` directive to change how suggestions are filtered (e.g.
+ * fuzzy, token-prefix, or matching against a secondary field).
+ *
+ * A matcher receives the already-trimmed, non-empty query — an empty query is
+ * short-circuited by {@link filterOptions} to return every option.
+ */
+type MlvOptionMatcher<T> = (option: MlvSelectOption<T>, query: string) => boolean;
+/**
+ * The default option matcher: a case- and diacritic-insensitive substring match
+ * on {@link MlvSelectOption.label}. An empty (or whitespace-only) query matches
+ * every option.
+ *
+ * @param option - The option to test.
+ * @param query - The current search query (already trimmed by callers).
+ * @returns Whether the option label contains the query.
+ */
+declare function defaultOptionMatcher<T>(option: MlvSelectOption<T>, query: string): boolean;
+/**
+ * Filters a list of resolved options against a query using `matcher`
+ * ({@link defaultOptionMatcher} by default), then ranks **prefix matches
+ * first** ({@link rankPrefixMatchesFirst}) so the top suggestion is the one an
+ * inline completion can extend (`"Pe"` ranks `"Pear"` above `"Grape"`). A blank
+ * query returns a shallow copy of every option — the "show everything" state a
+ * combobox / autocomplete shows on focus. This is the single shared
+ * implementation of the substring filter that previously lived inline in
+ * `mlv-combobox`.
+ *
+ * @param options - The resolved options to filter.
+ * @param query - The raw search query (trimmed internally).
+ * @param matcher - Optional custom predicate; defaults to substring matching.
+ * @returns The matcher-satisfying options, prefix matches ranked first (all
+ *   options, unranked, for a blank query).
+ */
+declare function filterOptions<T>(options: readonly MlvSelectOption<T>[], query: string, matcher?: MlvOptionMatcher<T>): MlvSelectOption<T>[];
+/**
+ * Stable-partitions filtered options so labels that **start with** the query
+ * (case- and diacritic-insensitive) come before the remaining matches, keeping
+ * the original relative order inside each partition.
+ *
+ * Grouped options ({@link MlvSelectOption.group}) are ranked **within each
+ * consecutive same-group run** only — runs themselves never move or merge, so
+ * the panel's consecutive-run group rendering (sticky headers, flat-index
+ * alignment) is preserved. An ungrouped list is a single run and gets the full
+ * prefix-first ordering.
+ *
+ * @param options - The already-filtered options.
+ * @param query - The trimmed, non-empty query.
+ * @returns The options with prefix matches ranked first per group run.
+ */
+declare function rankPrefixMatchesFirst<T>(options: readonly MlvSelectOption<T>[], query: string): MlvSelectOption<T>[];
+/**
+ * Splits `label` into matched / unmatched {@link MlvMatchSegment}s for the first
+ * occurrence of `query`, so consumers can emphasise the matched substring in a
+ * suggestion (e.g. wrapping matched slices in `<mark>`).
+ *
+ * Matching is case- and diacritic-insensitive ({@link normalizeForMatch}); the
+ * returned segment `text` preserves the **original** label casing/diacritics.
+ * Because NFD folding can change string length (e.g. `"é"` → `"e"` + combining
+ * mark), the search runs over a per-code-point folded projection with an index
+ * map back to the original code points, keeping the highlighted slice aligned
+ * with the source label. Only the first match is highlighted.
+ *
+ * @param label - The option label to segment.
+ * @param query - The query to highlight within the label.
+ * @returns Ordered segments covering the whole label; a single unmatched
+ *   segment when the query is empty or not found.
+ */
+declare function matchSegments(label: string, query: string): MlvMatchSegment[];
+
+/**
+ * Builds the deterministic DOM `id` for the option row at `index` within a
+ * listbox, matching the id `mlv-dropdown-panel` stamps on each option. An
+ * owning combobox / autocomplete computes the same id to point its input's
+ * `aria-activedescendant` at the active row.
+ *
+ * This is the single source of truth for the activedescendant option-id format
+ * (`<listboxId>-option-<index>`), shared by `mlv-dropdown-panel`,
+ * `mlv-combobox`, and `[mlvAutocomplete]` so the id the panel renders and the
+ * id the trigger references can never drift.
+ *
+ * @param listboxId - The id of the listbox that owns the option.
+ * @param index - The option's flat index within the listbox.
+ * @returns The option's DOM id, e.g. `"my-listbox-option-3"`.
+ */
+declare function optionId(listboxId: string, index: number): string;
+/**
+ * Signal-backed bookkeeping for the "active option" index of a WAI-ARIA
+ * activedescendant keyboard model — the shared engine behind `mlv-combobox`
+ * and `[mlvAutocomplete]`, where DOM focus stays on the text input and the
+ * highlighted option is tracked purely by index (mirrored into the input's
+ * `aria-activedescendant`).
+ *
+ * The active index is `-1` when no option is active. {@link move} advances it
+ * with wrap-around, treating a first move from `-1` as landing on the first
+ * (forward) or last (backward) option; {@link first} / {@link last} jump to the
+ * ends; {@link reset} clears it back to `-1`. The current option count is read
+ * lazily through the accessor supplied at construction, so the owner can back it
+ * with any signal / computed (e.g. a filtered-options length) without pushing
+ * the count on every keystroke.
+ */
+declare class MlvActiveDescendant {
+    private readonly _count;
+    /** @private The active option index; `-1` = no active option. */
+    private readonly _index;
+    /**
+     * The active option index as a read-only signal; `-1` when no option is
+     * active. Read it reactively (template / effect) or imperatively (call it in
+     * an event handler) — both track the same underlying state.
+     */
+    readonly index: Signal<number>;
+    /**
+     * @param _count Accessor returning the current number of navigable options.
+     * Read lazily on each {@link move} / {@link first} / {@link last} call, so it
+     * always reflects the live count (e.g. after the options are filtered).
+     */
+    constructor(_count: () => number);
+    /**
+     * Advances the active option by `delta` with wrap-around. With no option
+     * active (`-1`), a forward move (`delta > 0`) lands on the first option and a
+     * backward move (`delta < 0`) on the last; otherwise the index wraps modulo
+     * the option count. Resets to `-1` when there are no options.
+     *
+     * @param delta Step to move by (`+1` next, `-1` previous).
+     */
+    move(delta: number): void;
+    /** Activates the first option. No-op when there are no options. */
+    first(): void;
+    /** Activates the last option. No-op when there are no options. */
+    last(): void;
+    /** Clears the active option back to `-1` (nothing active). */
+    reset(): void;
+}
+
+/**
+ * Splits a label into matched / unmatched {@link MlvMatchSegment}s for the given
+ * query so a template can emphasise the matched substring (case- and
+ * diacritic-insensitive; see {@link matchSegments}). Used by
+ * `mlv-dropdown-panel` to highlight the query inside each suggestion.
+ *
+ * @example
+ * ```html
+ * @for (seg of option.label | mlvHighlightMatch:query; track $index) {
+ *   @if (seg.matched) { <mark>{{ seg.text }}</mark> }
+ *   @else { {{ seg.text }} }
+ * }
+ * ```
+ */
+declare class MlvHighlightMatchPipe implements PipeTransform {
+    /**
+     * @param label - The label to segment. Nullish input yields an empty result.
+     * @param query - The query to highlight; empty query returns one unmatched
+     *   segment containing the whole label.
+     */
+    transform(label: string | null | undefined, query: string): MlvMatchSegment[];
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<MlvHighlightMatchPipe, never>;
+    static ɵpipe: _angular_core.ɵɵPipeDeclaration<MlvHighlightMatchPipe, "mlvHighlightMatch", true>;
+}
+
+/**
+ * In-memory data source for option controls (`mlv-select`, `mlv-combobox`,
+ * `[mlvAutocomplete]`). Identical to `MlvArrayDataSource` except that it is
+ * **unpaged** (`perPage = Infinity`) so the whole list renders; the shared
+ * natural-field search (`setSearch({ query, keys: [] })`) and sorting are
+ * inherited. Reach for it when you want a data-source-shaped API over an
+ * in-memory array (e.g. to swap for a remote subclass later); a plain `T[]`
+ * remains the simplest input.
+ */
+declare class MlvSelectDataSource<T> extends MlvArrayDataSource<T> {
+    /**
+     * @param data A plain array (wrapped in a signal automatically) or a
+     * `Signal<T[]>` to track reactively.
+     */
+    constructor(data: Signal<T[]> | T[]);
+}
+
+/**
+ * Normalises every supported search result into a one-shot observable. Shared
+ * by `MlvOptionsAdapter` and `[mlvAutocomplete]`.
+ */
+declare function toOptionsResult<T>(result: T[] | Promise<T[]> | Observable<T[]>): Observable<T[]>;
+
+/**
+ * A function producing option items for a query. May return a synchronous
+ * array, a `Promise`, or an `Observable`. Async results drive the loading
+ * affordance; a newer query supersedes an in-flight one.
+ */
+type MlvOptionsSearchFn<T> = (query: string) => T[] | Promise<T[]> | Observable<T[]>;
+/** Everything an option control accepts as its `options` input. */
+type MlvOptionsInput<T> = readonly T[] | Observable<readonly T[]> | MlvDataSource<T> | null | undefined;
+/**
+ * `'local'` — the consumer filters `items` itself (arrays / observables).
+ * `'remote'` — the source owns filtering; the consumer calls `search()` and
+ * renders `items` as-is (`MlvDataSource` / `searchFn`).
+ */
+type MlvOptionsMode = 'local' | 'remote';
+/**
+ * Everything `MlvOptionsAdapter` reads from its owner. Every field is a
+ * `Signal`, so an option control passes its own `input()`s straight through and
+ * the adapter reacts to each of them — a swapped `source` reconnects, a swapped
+ * `searchFn` re-arms the lazy gate, and `debounce` / `eager` are read at the
+ * moment they matter rather than captured at construction.
+ */
+interface MlvOptionsAdapterConfig<T> {
+    /** The control's `options` input. */
+    source: Signal<MlvOptionsInput<T>>;
+    /** Optional remote search function; when set it supersedes `source`. */
+    searchFn: Signal<MlvOptionsSearchFn<T> | null | undefined>;
+    /** Debounce (ms) applied to remote searches only. */
+    debounce: Signal<number>;
+    /** When `true`, a `searchFn` runs `searchFn('')` on construction instead of lazily. */
+    eager: Signal<boolean>;
+}
+/**
+ * Normalises `T[] | Observable<T[]> | MlvDataSource<T>` (+ optional
+ * `searchFn`) into one reactive shape shared by `mlv-select`, `mlv-combobox`
+ * and `[mlvAutocomplete]`. Construct it inside an injection context (a
+ * component field initialiser or constructor) — it uses `effect()` and
+ * `DestroyRef`.
+ *
+ * Paging (`MlvDataSource` only): `connect()` emits the current page's slice and
+ * the adapter accumulates, tracking the **applied page** — the page whose slice
+ * is currently in `items` — alongside the items accumulated before it:
+ *
+ * - `page <= 1` → the slice replaces `items` and accumulation restarts.
+ * - `page === appliedPage` → the source re-emitted the page already shown (a
+ *   backing array changed, a refetch landed): its **tail is replaced**, never
+ *   appended, so rows are not duplicated.
+ * - `page > appliedPage` → the slice is appended.
+ * - A run where the slice reference has not changed (a `page` bump whose data
+ *   has not arrived yet) applies nothing.
+ *
+ * `loadMore()` is therefore a no-op while a page is pending — a scroll sentinel
+ * firing repeatedly cannot skip a page.
+ *
+ * Swapping the `searchFn` **only re-arms the lazy gate** (the next
+ * `ensureLoaded()` calls the new function): the in-flight call is left running
+ * and `items` / `ready` / `loading` are untouched, so results stay on screen
+ * until the new function answers and a control bound to an inline arrow — a
+ * fresh reference on every change detection run — is not reset on every pass.
+ */
+declare class MlvOptionsAdapter<T> {
+    private readonly _config;
+    /** @private Lifetime for the in-flight `searchFn` subscription / debounce timer. */
+    private readonly _destroyRef;
+    /** @private Which branch the current inputs select. `searchFn` wins over the source. */
+    private readonly _kind;
+    /** @private Latest emission of the observable source. */
+    private readonly _obsItems;
+    /** @private Whether the observable source has emitted at least once. */
+    private readonly _obsReady;
+    /** @private The connected source and its (memoised) `connect()` signal. */
+    private readonly _connected;
+    /** @private Accumulated pages. */
+    private readonly _dsItems;
+    /** @private Whether the source has been observed not-loading at least once since connect. */
+    private readonly _dsReady;
+    /** @private Last slice reference applied — a `page` bump whose slice has not arrived yet must not append. */
+    private _dsLastSlice;
+    /** @private The page whose slice is currently applied (`0` = none yet). Distinguishes an append from a re-emit of the page already shown. */
+    private _dsAppliedPage;
+    /** @private Items accumulated *before* the applied page — the prefix a re-emit of that page is re-appended to. */
+    private _dsBase;
+    /** @private Last `searchFn` result. */
+    private readonly _fnItems;
+    /** @private Whether a `searchFn` call is in flight. */
+    private readonly _fnLoading;
+    /** @private Whether `searchFn` has produced (or failed) at least once. */
+    private readonly _fnReady;
+    /** @private Whether `searchFn` has been invoked at least once (lazy-load gate). */
+    private _fnStarted;
+    /**
+     * @private The `searchFn` reference the swap effect last observed, normalised
+     * to `null` when unset. Stays `undefined` until that effect's first run, which
+     * is how `undefined → fn` at construction is told apart from a genuine swap.
+     */
+    private _fnSeen;
+    /** @private In-flight `searchFn` subscription (superseded by a newer query). */
+    private _fnSub;
+    /** @private Monotonic token discarding stale `searchFn` results. */
+    private _fnToken;
+    /** @private Pending debounce timer for remote searches. */
+    private _debounceTimer;
+    /** @private Last query handed to `search()`; replayed by `ensureLoaded()`. */
+    private _lastQuery;
+    /** `'local'` for arrays / observables (consumer filters); `'remote'` for a data source or `searchFn`. */
+    readonly mode: Signal<MlvOptionsMode>;
+    /** The current raw items (accumulated pages for a data source). */
+    readonly items: Signal<readonly T[]>;
+    /** Source-owned "first page / search in flight" flag (drives the top spinner row). */
+    readonly loading: Signal<boolean>;
+    /** A page beyond the first is in flight (drives the bottom spinner row). Data source only. */
+    readonly loadingMore: Signal<boolean>;
+    /** The first payload has arrived — arrays immediately, observables on first emit, data sources once observed not-loading, `searchFn` after its first result. */
+    readonly ready: Signal<boolean>;
+    /** More pages exist (`items.length < totalItems`). Data source only. */
+    readonly hasMore: Signal<boolean>;
+    constructor(_config: MlvOptionsAdapterConfig<T>);
+    /**
+     * Remote-mode search entry point (debounced). Data source → `setSearch({ query, keys: [] })`
+     * (or `null` for a blank query); `searchFn` → invoked with the query. No-op in local mode.
+     */
+    search(query: string): void;
+    /** Runs the initial `searchFn` load if it has not run yet (data sources connect eagerly; local modes need nothing). */
+    ensureLoaded(): void;
+    /**
+     * Requests the next data-source page. No-op unless `hasMore()`, nothing is in
+     * flight, and the source's current page is the one already applied — a page
+     * requested but not yet accumulated (or a search that reset the source to page
+     * one) blocks the next bump, so a scroll sentinel cannot skip a page.
+     */
+    loadMore(): void;
+    /** @private Clears every accumulation bookkeeping field — on connect, and when a source is disconnected. */
+    private _resetDataSource;
+    /** @private Schedules `run` after `debounce` ms (immediately when 0), cancelling a pending one. */
+    private _debounced;
+    /** @private Forwards a query to the connected data source using the option-control contract (`keys: []`). */
+    private _searchDataSource;
+    /** @private Invokes `searchFn`, superseding any in-flight call; keeps stale items until the result. */
+    private _runSearchFn;
+}
+
+/**
+ * `@angular/aria`'s `ngListbox` reconciles its `value` model against the
+ * currently **rendered** options and re-emits `valueChange` whenever the
+ * rendered set changes — not only on user interaction. These helpers let an
+ * owning control tell that noise apart from a genuine selection.
+ */
+/**
+ * Whether an incoming listbox `valueChange` is pure aria reconciliation: it
+ * (a) adds no value that is not already committed and (b) only removes values
+ * whose option is currently not rendered (`visible`). An emit that exactly
+ * restates the committed selection is reconciliation too.
+ */
+declare function isReconciliationEmit<T>(incoming: readonly T[], committed: readonly T[], visible: readonly T[], compare: (a: T, b: T) => boolean): boolean;
+/**
+ * Committed values that aria dropped only because their option is not
+ * rendered (not in `visible`) and that are not in `incoming`. Re-add them to
+ * a genuine multi-select pick so earlier selections survive filtering.
+ */
+declare function filteredOutCommitted<T>(incoming: readonly T[], committed: readonly T[], visible: readonly T[], compare: (a: T, b: T) => boolean): T[];
+
+export { MlvActiveDescendant, MlvDropdownPanel, MlvHighlightMatchPipe, MlvOptionsAdapter, MlvSelectDataSource, defaultOptionMatcher, defaultOptionTransform, filterOptions, filteredOutCommitted, hasOptionGroups, isReconciliationEmit, isSelectOption, matchSegments, optionId, rankPrefixMatchesFirst, resolveOptions, toOptionsResult };
+export type { MlvMatchSegment, MlvOptionMatcher, MlvOptionsAdapterConfig, MlvOptionsInput, MlvOptionsMode, MlvOptionsSearchFn, MlvSelectOption, MlvSelectOptionTransform };

package/types/malva-ui-core-empty-state.d.ts

@@ -0,0 +1,37 @@
+import * as i0 from '@angular/core';
+
+/**
+ * Empty state component for displaying a placeholder when there is no content
+ * to show. Provides content projection slots for an icon or illustration,
+ * a title, a description, and one or more action buttons.
+ *
+ * All slots are optional — compose only the ones your use-case requires.
+ *
+ * @example Basic
+ * ```html
+ * <mlv-empty-state>
+ *   <ng-container mlvEmptyStateIcon>
+ *     <svg lucideInbox [size]="48" />
+ *   </ng-container>
+ *   <span mlvEmptyStateTitle>No items found</span>
+ * </mlv-empty-state>
+ * ```
+ *
+ * @example With action
+ * ```html
+ * <mlv-empty-state>
+ *   <ng-container mlvEmptyStateIcon><svg lucideFolder [size]="48" /></ng-container>
+ *   <span mlvEmptyStateTitle>No projects</span>
+ *   <span mlvEmptyStateDescription>Create your first project to get started.</span>
+ *   <ng-container mlvEmptyStateActions>
+ *     <button mlvButton>Create project</button>
+ *   </ng-container>
+ * </mlv-empty-state>
+ * ```
+ */
+declare class MlvEmptyState {
+    static ɵfac: i0.ɵɵFactoryDeclaration<MlvEmptyState, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<MlvEmptyState, "mlv-empty-state", never, {}, {}, never, ["[mlvEmptyStateIcon]", "[mlvEmptyStateTitle]", "[mlvEmptyStateDescription]", "[mlvEmptyStateActions]"], true, never>;
+}
+
+export { MlvEmptyState };