@malva-ui/core 0.1.13 → 0.1.14

package/fesm2022/malva-ui-core-autocomplete.mjs

@@ -0,0 +1,775 @@
+import * as i0 from '@angular/core';
+import { input, model, output, inject, ElementRef, Renderer2, ViewContainerRef, Injector, DestroyRef, signal, computed, effect, afterNextRender, untracked, Directive } from '@angular/core';
+import { coerceBooleanProperty } from '@angular/cdk/coercion';
+import { Overlay } from '@angular/cdk/overlay';
+import { UP_ARROW, DOWN_ARROW } from '@angular/cdk/keycodes';
+import { ComponentPortal } from '@angular/cdk/portal';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import { Subject, timer } from 'rxjs';
+import { debounce } from 'rxjs/operators';
+import { defaultOptionTransform, defaultOptionMatcher, MlvOptionsAdapter, MlvActiveDescendant, filterOptions, resolveOptions, optionId, MlvDropdownPanel } from '@malva-ui/core/dropdown';
+import { MlvSelectionService } from '@malva-ui/core/form-utils';
+import { MlvRtlService, mlvNextId } from '@malva-ui/cdk/utils';
+import { MlvDensityService, MLV_DENSITY_CONTEXT } from '@malva-ui/cdk/density';
+
+/** Connected-overlay positions: below the input first, above as the fallback. */
+const AUTOCOMPLETE_POSITIONS = [
+    {
+        originX: 'start',
+        originY: 'bottom',
+        overlayX: 'start',
+        overlayY: 'top',
+        offsetY: 8,
+    },
+    {
+        originX: 'start',
+        originY: 'top',
+        overlayX: 'start',
+        overlayY: 'bottom',
+        offsetY: -8,
+    },
+];
+/**
+ * `[mlvAutocomplete]` — a reusable autocomplete/typeahead behaviour applicable
+ * to **any** text input: a native `<input>` or a `<mlv-input>`. It reuses the
+ * same building blocks as `mlv-combobox` — the shared
+ * {@link filterOptions matching utility} and the `mlv-dropdown-panel` list — to
+ * render a suggestion popup, without forcing the field into a full form
+ * control.
+ *
+ * Suggestions come from the {@link options} source — an array or
+ * `Observable<T[]>` (filtered locally with {@link matcher}), or a
+ * `MlvDataSource<T>` (which filters and pages itself) — or from an async
+ * {@link search} function. Every shape is normalised by the shared
+ * `MlvOptionsAdapter`. The directive owns
+ * the popup (a CDK overlay hosting `mlv-dropdown-panel`, the same primitive
+ * `mlv-popup` wraps — a headless attribute directive cannot host `mlv-popup`'s
+ * declarative content template), the WAI-ARIA combobox wiring on the input
+ * (`role="combobox"`, `aria-autocomplete="list"`, `aria-expanded`,
+ * `aria-controls`, `aria-activedescendant`), and the activedescendant keyboard
+ * model (DOM focus stays in the input; Arrow/Home/End move the highlighted
+ * option, Enter selects it, Escape closes then clears).
+ *
+ * @example
+ * ```html
+ * <!-- Static options on a plain mlv-input -->
+ * <mlv-input [mlvAutocomplete]="fruits" (optionSelected)="pick($event)" />
+ *
+ * <!-- Async search with loading + highlighting -->
+ * <mlv-input [mlvAutocompleteSearch]="searchUsers" [mlvAutocompleteMinLength]="2" />
+ *
+ * <!-- Data source: it filters (setSearch) and pages itself -->
+ * <mlv-input [mlvAutocomplete]="usersDataSource" [mlvAutocompleteMinLength]="2" />
+ *
+ * <!-- Custom matcher -->
+ * <mlv-input [mlvAutocomplete]="cities" [mlvAutocompleteMatcher]="startsWith" />
+ * ```
+ */
+class MlvAutocomplete {
+    /**
+     * Suggestion source: a static array or `Observable<T[]>` (filtered locally
+     * against the query with {@link matcher}), or a `MlvDataSource<T>` (which owns
+     * its own filtering — the directive forwards the query as
+     * `setSearch({ query, keys: [] })` and pages lazily). Ignored when a
+     * {@link search} function is provided. Bound through the directive's own
+     * selector: `[mlvAutocomplete]="options"`.
+     */
+    options = input([], { ...(ngDevMode ? { debugName: "options" } : /* istanbul ignore next */ {}), alias: 'mlvAutocomplete' });
+    /**
+     * Async suggestion source: `(query) => T[] | Promise<T[]> | Observable<T[]>`.
+     * When set, it supersedes {@link options}; results feed the panel and drive
+     * the loading affordance. A newer query supersedes an in-flight one (its
+     * result is discarded), while the previous results stay visible until the new
+     * ones land.
+     */
+    search = input(null, { ...(ngDevMode ? { debugName: "search" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteSearch' });
+    /**
+     * Maps a raw item to a `MlvSelectOption` (`{ label, value, group? }`). Same
+     * convention as `mlv-select` / `mlv-combobox`; defaults to
+     * {@link defaultOptionTransform} (uses `String(item)` as the label).
+     */
+    toOption = input(defaultOptionTransform, { ...(ngDevMode ? { debugName: "toOption" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteToOption' });
+    /**
+     * Predicate used to filter {@link options} against the query. Defaults to a
+     * case- and diacritic-insensitive substring match on the label. Ignored when
+     * {@link search} is provided (the async source owns its own matching).
+     */
+    matcher = input(defaultOptionMatcher, { ...(ngDevMode ? { debugName: "matcher" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteMatcher' });
+    /**
+     * Debounce (ms) applied to keystrokes before filtering / searching — avoids
+     * redundant work and API calls during rapid typing.
+     * @default 200
+     */
+    debounce = input(200, { ...(ngDevMode ? { debugName: "debounce" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteDebounce' });
+    /**
+     * Minimum query length before suggestions open. `0` (default) opens on focus
+     * showing the full list — appropriate for cheap local filtering. Raise it
+     * (2+ recommended) for async sources so a network call is not made on every
+     * keystroke.
+     * @default 0
+     */
+    minLength = input(0, { ...(ngDevMode ? { debugName: "minLength" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteMinLength' });
+    /**
+     * When `true`, the matched substring of the query is emphasised inside each
+     * suggestion label.
+     * @default true
+     */
+    highlight = input(true, { ...(ngDevMode ? { debugName: "highlight" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteHighlight',
+        transform: coerceBooleanProperty });
+    /**
+     * When `true` (default), an **inline completion** is offered as the user types:
+     * if the top visible suggestion's label starts with the typed text (a genuine
+     * prefix, case-insensitively) and the caret is at the end of the field, the
+     * remainder of that suggestion is inserted after the caret and left **selected**
+     * — so continuing to type replaces it, `Enter`/click commits the full value, and
+     * `Escape` reverts to just the typed text. The user's typed prefix keeps their
+     * casing; only the appended remainder uses the suggestion's casing. Non-prefix
+     * (fuzzy / substring-only) top matches are skipped silently (list-only). While
+     * enabled the input advertises `aria-autocomplete="both"`; set `false` for
+     * list-only behaviour (`aria-autocomplete="list"`).
+     * @default true
+     */
+    inline = input(true, { ...(ngDevMode ? { debugName: "inline" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteInline',
+        transform: coerceBooleanProperty });
+    /**
+     * When `true` (default), focusing the input opens the suggestion list
+     * (subject to {@link minLength}). Set `false` to only open on typing / arrow.
+     * @default true
+     */
+    openOnFocus = input(true, { ...(ngDevMode ? { debugName: "openOnFocus" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteOpenOnFocus',
+        transform: coerceBooleanProperty });
+    /** Disables the behaviour entirely (no popup, no aria wiring changes). */
+    disabled = input(false, { ...(ngDevMode ? { debugName: "disabled" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteDisabled',
+        transform: coerceBooleanProperty });
+    /**
+     * Text shown / announced inside the panel's loading affordances — the top row
+     * while a remote source (an async {@link search} or a `MlvDataSource`)
+     * resolves, and the bottom row while a further page loads. Localise by binding
+     * a translated string.
+     * @default 'Loading…'
+     */
+    loadingText = input('Loading…', { ...(ngDevMode ? { debugName: "loadingText" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteLoadingText' });
+    /**
+     * Distance (px) from the end of the suggestion list at which the next
+     * data-source page is requested. Only meaningful for a `MlvDataSource`
+     * {@link options} source, which is the only shape that pages.
+     * @default 150
+     */
+    infiniteScrollThreshold = input(150, { ...(ngDevMode ? { debugName: "infiniteScrollThreshold" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteInfiniteScrollThreshold' });
+    /**
+     * Density applied to the suggestion panel's option rows.
+     *
+     * The panel is hosted in a bare CDK overlay portaled to the overlay container,
+     * outside the input's DOM tree, so ancestor density classes cannot cascade
+     * into it. The resolved density is stamped as a `mlv--{density}` class on the
+     * panel host (the same mechanism `mlv-popup` uses for its detached panel).
+     * When omitted, the nearest ancestor `MLV_DENSITY_CONTEXT` (e.g. a
+     * `form[mlvForm]`) applies, then the global `MlvDensityService` density.
+     */
+    density = input(undefined, { ...(ngDevMode ? { debugName: "density" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteDensity' });
+    /**
+     * The raw value of the last selected suggestion, or `null`. Two-way bindable
+     * (`[(mlvAutocompleteValue)]`) so a parent can observe the committed pick.
+     */
+    selectedValue = model(null, { ...(ngDevMode ? { debugName: "selectedValue" } : /* istanbul ignore next */ {}), alias: 'mlvAutocompleteValue' });
+    /** Emits the full `MlvSelectOption` each time the user selects a suggestion. */
+    optionSelected = output();
+    /** Emits `true` when the suggestion list opens and `false` when it closes. */
+    openedChange = output();
+    // ─── DI ────────────────────────────────────────────────────────────────────
+    /** @private Host element the directive is applied to (native input or mlv-input). */
+    _hostEl = inject(ElementRef).nativeElement;
+    /** @private Renderer for DOM attribute/listener wiring on the resolved input. */
+    _renderer = inject(Renderer2);
+    /** @private CDK overlay factory used to host the suggestion panel. */
+    _overlay = inject(Overlay);
+    /** @private View container + injector for the `mlv-dropdown-panel` component portal. */
+    _vcr = inject(ViewContainerRef);
+    _injector = inject(Injector);
+    /** @private Directive lifetime, for imperative listener / subscription cleanup. */
+    _destroyRef = inject(DestroyRef);
+    /** @private Global density service — fallback when no explicit {@link density} is supplied. */
+    _densityService = inject(MlvDensityService);
+    _rtlService = inject(MlvRtlService);
+    /** @private Ancestor-projected density (`MLV_DENSITY_CONTEXT`); consulted before the service. */
+    _densityContext = inject(MLV_DENSITY_CONTEXT, {
+        optional: true,
+    });
+    // ─── State ───────────────────────────────────────────────────────────────
+    /** @private The resolved focusable `<input>` (host itself, or the inner input of a `mlv-input`). */
+    _inputEl = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_inputEl" }] : /* istanbul ignore next */ []));
+    /** @private Current (post-input) query text. */
+    _query = signal('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_query" }] : /* istanbul ignore next */ []));
+    /** @private The current suggestion options rendered in the panel. */
+    _results = signal([], /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_results" }] : /* istanbul ignore next */ []));
+    /**
+     * @private Shared source adapter: arrays / observables filter locally, a
+     * `MlvDataSource` or `search` fn run remotely. Debounce is 0 here because the
+     * directive already debounces keystrokes before `_runQuery`.
+     */
+    _adapter = new MlvOptionsAdapter({
+        source: this.options,
+        searchFn: this.search,
+        debounce: signal(0),
+        eager: signal(false),
+    });
+    /** @private Panel loading flag — only remote sources report loading. */
+    _panelLoading = computed(() => this._adapter.mode() === 'remote' && this._adapter.loading(), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_panelLoading" }] : /* istanbul ignore next */ []));
+    /**
+     * @private Shared activedescendant bookkeeping: tracks the highlighted option
+     * index over the current results with wrap-around navigation. The same engine
+     * backs `mlv-combobox`.
+     */
+    _activeDescendant = new MlvActiveDescendant(() => this._results().length);
+    /** @private Whether the suggestion popup is open. */
+    _open = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_open" }] : /* istanbul ignore next */ []));
+    /** @private The attached panel component ref (a signal so the sync effect re-runs on attach). */
+    _panelRef = signal(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_panelRef" }] : /* istanbul ignore next */ []));
+    /** Whether the suggestion popup is currently open (read-only view of internal state). */
+    isOpen = this._open.asReadonly();
+    /** @private Stable listbox id shared between the input's `aria-controls` and the panel's option ids. */
+    _listboxId = mlvNextId('mlv-autocomplete-listbox');
+    /**
+     * @private Debounced keystroke stream. Carries the query text plus whether the
+     * triggering edit was an insertion (text grew) so the debounced `_runQuery`
+     * knows whether an inline completion may be offered — only genuine insertions
+     * complete, never deletions (Backspace/Delete/cut), focus, or arrow-open.
+     */
+    _input$ = new Subject();
+    /** @private Skips the synthetic `input` event dispatched while committing / completing a value. */
+    _suppressNextInput = false;
+    /** @private Live overlay reference while the panel is open. */
+    _overlayRef = null;
+    /**
+     * @private `inputType` of the pending native edit, captured on `beforeinput`
+     * and consumed on `input`. Non-null in real browsers (drives precise
+     * insert-vs-delete detection); `null` in environments that don't fire
+     * `beforeinput` (jsdom / programmatic edits), where a length comparison is the
+     * fallback.
+     */
+    _pendingInputType = null;
+    /** @private Length of the input value at the previous `input` event — the length-comparison fallback for insertion detection. */
+    _previousValueLength = 0;
+    /** @private Whether the current query is allowed to offer an inline completion (set per `_runQuery`; only true for inline-enabled insertions). */
+    _completionArmed = false;
+    /** @private Whether an inline completion (typed prefix + selected remainder) is currently present in the input. */
+    _completionActive = false;
+    /** @private The `mlv--{density}` class currently applied to the panel host, for removal on change. */
+    _appliedDensityClass = null;
+    constructor() {
+        // Keep the detached panel host stamped with the resolved density cascade
+        // class. The overlay (and panel element) is recreated on every open, so the
+        // applied-class memo resets when the ref clears; while open, the effect also
+        // reacts to live density changes.
+        effect(() => {
+            const ref = this._panelRef();
+            if (!ref) {
+                this._appliedDensityClass = null;
+                return;
+            }
+            const el = ref.location.nativeElement;
+            const next = `mlv--${this.density() ?? this._densityContext?.() ?? this._densityService.density()}`;
+            if (this._appliedDensityClass === next)
+                return;
+            if (this._appliedDensityClass) {
+                this._renderer.removeClass(el, this._appliedDensityClass);
+            }
+            this._renderer.addClass(el, next);
+            this._appliedDensityClass = next;
+        });
+        // Debounce keystrokes before filtering / searching. The last event in the
+        // window wins (rxjs `debounce`), so its `insertion` flag is what gates the
+        // inline completion for the resolved query.
+        this._input$
+            .pipe(debounce(() => timer(Math.max(0, this.debounce()))), takeUntilDestroyed())
+            .subscribe(({ query, insertion }) => this._runQuery(query, insertion));
+        // Resolve the real <input> and wire native listeners. When the host itself
+        // is an <input> it is available immediately; when the host is a `mlv-input`
+        // (or any wrapper) the inner <input> only exists after the first render.
+        if (this._hostEl.tagName === 'INPUT') {
+            this._bindTo(this._hostEl);
+        }
+        else {
+            afterNextRender(() => {
+                const el = this._hostEl.querySelector('input');
+                if (el)
+                    this._bindTo(el);
+            });
+        }
+        // Keep the input's WAI-ARIA combobox attributes in sync with popup state.
+        effect(() => {
+            const el = this._inputEl();
+            if (!el)
+                return;
+            const open = this._open();
+            this._renderer.setAttribute(el, 'role', 'combobox');
+            // "both": inline text completion + a list of suggestions (WAI-ARIA
+            // list-with-inline-autocomplete). "list": suggestions only, no inline
+            // completion. Tracks the `inline` opt-out.
+            this._renderer.setAttribute(el, 'aria-autocomplete', this.inline() ? 'both' : 'list');
+            this._renderer.setAttribute(el, 'aria-expanded', String(open));
+            if (open) {
+                this._renderer.setAttribute(el, 'aria-controls', this._listboxId);
+                const activeId = this._activeOptionId();
+                if (activeId) {
+                    this._renderer.setAttribute(el, 'aria-activedescendant', activeId);
+                }
+                else {
+                    this._renderer.removeAttribute(el, 'aria-activedescendant');
+                }
+            }
+            else {
+                this._renderer.removeAttribute(el, 'aria-controls');
+                this._renderer.removeAttribute(el, 'aria-activedescendant');
+            }
+        });
+        // Push current state into the attached panel component.
+        effect(() => {
+            const ref = this._panelRef();
+            if (!ref)
+                return;
+            ref.setInput('options', this._results());
+            ref.setInput('multiple', false);
+            ref.setInput('selectedValues', []);
+            ref.setInput('focusMode', 'activedescendant');
+            ref.setInput('activeIndex', this._activeDescendant.index());
+            ref.setInput('listboxId', this._listboxId);
+            ref.setInput('loading', this._panelLoading());
+            ref.setInput('loadingText', this.loadingText());
+            ref.setInput('hasMore', this._adapter.hasMore());
+            ref.setInput('loadingMore', this._adapter.loadingMore());
+            ref.setInput('infiniteScrollThreshold', this.infiniteScrollThreshold());
+            ref.setInput('highlightQuery', this.highlight() ? this._query().trim() : '');
+        });
+        // Mirror the adapter's items into the rendered results whenever the source
+        // produces a new set: a remote result landing, or a local observable
+        // emitting after the panel is already open (nothing else would repaint it
+        // until the next keystroke). Remote items render as-is — the source owns
+        // filtering — while local ones are re-filtered against the current query.
+        // Running only on an item-set change is what keeps stale remote results
+        // visible while a newer query is in flight; the inline completion is offered
+        // once per armed query.
+        effect(() => {
+            const mode = this._adapter.mode();
+            const items = this._adapter.items();
+            untracked(() => {
+                if (mode === 'remote') {
+                    this._results.set(items.map((item) => this.toOption()(item)));
+                    if (this._completionArmed && !this._adapter.loading()) {
+                        this._applyCompletion();
+                        this._completionArmed = false;
+                    }
+                    return;
+                }
+                // Local: only an open panel needs repainting — a closed one is filled by
+                // `_runQuery` when it opens.
+                if (!this._open())
+                    return;
+                this._results.set(filterOptions(resolveOptions([...items], this.toOption()), this._query(), this.matcher()));
+                // The highlighted row may not exist in the new list.
+                if (this._activeDescendant.index() >= this._results().length) {
+                    this._activeDescendant.reset();
+                }
+            });
+        });
+        this._destroyRef.onDestroy(() => this._disposeOverlay());
+    }
+    /**
+     * @private Resolves the focusable `<input>` and attaches the native listeners
+     * (input / focus / blur / keydown) that drive the behaviour. Cleaned up on
+     * directive destroy.
+     */
+    _bindTo(el) {
+        this._inputEl.set(el);
+        this._previousValueLength = el.value.length;
+        // Capture the edit intent (insert vs delete) before the value changes, so
+        // `_onInput` can gate the inline completion precisely in real browsers. Not
+        // fired for programmatic value changes (jsdom / our own dispatches), where
+        // `_onInput` falls back to a length comparison.
+        this._destroyRef.onDestroy(this._renderer.listen(el, 'beforeinput', (event) => {
+            this._pendingInputType =
+                'inputType' in event ? event.inputType : null;
+        }));
+        this._destroyRef.onDestroy(this._renderer.listen(el, 'input', () => this._onInput()));
+        this._destroyRef.onDestroy(this._renderer.listen(el, 'focus', () => this._onFocus()));
+        this._destroyRef.onDestroy(this._renderer.listen(el, 'blur', () => this._onBlur()));
+        this._destroyRef.onDestroy(this._renderer.listen(el, 'keydown', (event) => this._onKeydown(event)));
+    }
+    /**
+     * @private `aria-activedescendant` target: the DOM id of the highlighted
+     * option row, or `null` when nothing is active. Matches the id the panel
+     * renders (`<listboxId>-option-<index>`).
+     */
+    _activeOptionId = () => {
+        const index = this._activeDescendant.index();
+        if (index < 0 || index >= this._results().length)
+            return null;
+        return optionId(this._listboxId, index);
+    };
+    // ─── Input / focus events ──────────────────────────────────────────────────
+    /** @private Handles a native `input` event: pushes the value (with insertion flag) into the debounced stream. */
+    _onInput() {
+        if (this._suppressNextInput) {
+            this._suppressNextInput = false;
+            // Discard any beforeinput type that paired with our own synthetic dispatch.
+            this._pendingInputType = null;
+            return;
+        }
+        // A genuine user edit invalidates any inline completion currently in the
+        // field (the edit has replaced or removed the selected remainder).
+        this._completionActive = false;
+        if (this._isInert())
+            return;
+        const query = this._inputEl()?.value ?? '';
+        this._input$.next({ query, insertion: this._consumeInsertion(query) });
+    }
+    /**
+     * @private Whether the just-observed `input` event grew the field's text (a
+     * genuine insertion) rather than deleting from it. Prefers the `beforeinput`
+     * `inputType` when available (real browsers), else compares the value length
+     * against the previous `input` event. Consumes the pending type and records
+     * the new length either way.
+     */
+    _consumeInsertion(value) {
+        const inputType = this._pendingInputType;
+        this._pendingInputType = null;
+        const insertion = inputType !== null
+            ? inputType.startsWith('insert')
+            : value.length > this._previousValueLength;
+        this._previousValueLength = value.length;
+        return insertion;
+    }
+    /** @private Opens suggestions on focus (immediate, bypassing debounce) when enabled. */
+    _onFocus() {
+        if (this._isInert() || !this.openOnFocus())
+            return;
+        this._runQuery(this._inputEl()?.value ?? '');
+    }
+    /** @private Closes the popup when focus genuinely leaves the field. */
+    _onBlur() {
+        this._closePopup();
+    }
+    // ─── Keyboard ──────────────────────────────────────────────────────────────
+    /** @private Activedescendant keyboard model — DOM focus stays in the input. */
+    _onKeydown(event) {
+        if (this._isInert())
+            return;
+        switch (this._rtlService.normalizeArrowKey(event) ?? event.key) {
+            case DOWN_ARROW:
+                event.preventDefault();
+                if (this._open())
+                    this._activeDescendant.move(1);
+                else
+                    this._runQuery(this._inputEl()?.value ?? '');
+                break;
+            case UP_ARROW:
+                event.preventDefault();
+                if (this._open())
+                    this._activeDescendant.move(-1);
+                else
+                    this._runQuery(this._inputEl()?.value ?? '');
+                break;
+            case 'Home':
+                if (this._open() && this._results().length) {
+                    event.preventDefault();
+                    this._activeDescendant.first();
+                }
+                break;
+            case 'End':
+                if (this._open() && this._results().length) {
+                    event.preventDefault();
+                    this._activeDescendant.last();
+                }
+                break;
+            case 'Enter': {
+                const index = this._activeDescendant.index();
+                const results = this._results();
+                if (this._open() && index >= 0 && index < results.length) {
+                    event.preventDefault();
+                    this._commit(results[index]);
+                }
+                break;
+            }
+            case 'Escape': {
+                // Revert any inline completion to just the typed text first, then apply
+                // the existing close-then-clear semantics.
+                const stripped = this._stripCompletion();
+                if (this._open()) {
+                    event.preventDefault();
+                    this._closePopup();
+                }
+                else if (stripped) {
+                    // The strip already reverted the completed text on this keypress; do
+                    // not also clear the field.
+                    event.preventDefault();
+                }
+                else if (this._inputEl()?.value) {
+                    event.preventDefault();
+                    this._clearInput();
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    // ─── Query resolution ───────────────────────────────────────────────────────
+    /**
+     * @private Resolves suggestions for `query` and opens / closes the popup.
+     * Local sources (arrays / observables) filter synchronously; a remote source
+     * (a `MlvDataSource` or an async {@link search}) shows the loading affordance
+     * while keeping the previous results visible, and a newer query supersedes it.
+     */
+    _runQuery(query, insertion = false) {
+        this._query.set(query);
+        this._activeDescendant.reset();
+        // Arm the inline completion only for inline-enabled insertions. Focus /
+        // arrow-open (`insertion` false) and deletions never complete.
+        this._completionArmed = insertion && this.inline();
+        if (this._isInert())
+            return;
+        if (query.length < this.minLength()) {
+            this._results.set([]);
+            this._closePopup();
+            return;
+        }
+        if (this._adapter.mode() === 'local') {
+            const options = resolveOptions([...this._adapter.items()], this.toOption());
+            this._results.set(filterOptions(options, query, this.matcher()));
+            this._openPopup();
+            if (this._completionArmed) {
+                this._applyCompletion();
+                this._completionArmed = false;
+            }
+            return;
+        }
+        // Remote: seed the panel from what the source already holds, open (the
+        // spinner row sits over those stale results), then search. Seeding is what
+        // makes a re-entry into an already-answered query repaint: the mirroring
+        // effect only fires on an item-set *change*, so a `search` fn that memoises
+        // and returns the identical array for a repeated query — or a data source
+        // whose slice reference is unchanged — would otherwise leave the panel
+        // empty after the min-length gate cleared `_results`. The adapter discards
+        // superseded results; the effect renders new ones.
+        this._results.set(this._adapter.items().map((item) => this.toOption()(item)));
+        this._openPopup();
+        this._adapter.search(query);
+    }
+    // ─── Inline completion ─────────────────────────────────────────────────────
+    /**
+     * @private Offers an inline completion for the current results: if the top
+     * suggestion's label is a genuine case-insensitive **prefix** of the typed
+     * text and the caret sits at the end of the field, append the suggestion's
+     * remainder (in its own casing) after the typed prefix (kept in the user's
+     * casing) and leave that remainder **selected**. The completed value is pushed
+     * through the same synthetic-`input` path a commit uses so `mlv-input` /
+     * `ngModel` / a form control observe it, and the top item (index 0) becomes the
+     * activedescendant-active row. No-op unless armed for an inline insertion with
+     * an open panel; non-prefix (fuzzy) top matches are skipped silently.
+     */
+    _applyCompletion() {
+        if (!this.inline() || !this._open())
+            return;
+        const el = this._inputEl();
+        if (!el)
+            return;
+        const typed = el.value;
+        const typedLength = typed.length;
+        if (typedLength === 0)
+            return;
+        // Only complete when the caret is a plain cursor at the very end.
+        if (el.selectionStart !== typedLength || el.selectionEnd !== typedLength) {
+            return;
+        }
+        const top = this._results()[0];
+        if (!top)
+            return;
+        const label = top.label;
+        if (label.length <= typedLength ||
+            !label.toLowerCase().startsWith(typed.toLowerCase())) {
+            return;
+        }
+        // Keep the user's typed casing; take the remainder from the suggestion.
+        const completed = typed + label.slice(typedLength);
+        el.value = completed;
+        el.setSelectionRange(typedLength, completed.length);
+        this._completionActive = true;
+        // Highlight the completed top item so keyboard nav / Enter stay coherent.
+        this._activeDescendant.first();
+        // Propagate the completed value the same way a commit does (suppressing our
+        // own re-filter of this synthetic event).
+        this._suppressNextInput = true;
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+    }
+    /**
+     * @private Strips an active inline completion back to the typed prefix (the
+     * text before the selected remainder), restoring the caret to the end and
+     * notifying value listeners. Returns whether a completion was stripped.
+     */
+    _stripCompletion() {
+        if (!this._completionActive)
+            return false;
+        const el = this._inputEl();
+        if (!el)
+            return false;
+        const start = el.selectionStart ?? 0;
+        const end = el.selectionEnd ?? 0;
+        // The completion is the trailing selection [start, value.length].
+        if (end !== el.value.length || start >= end) {
+            this._completionActive = false;
+            return false;
+        }
+        const typed = el.value.slice(0, start);
+        el.value = typed;
+        el.setSelectionRange(typed.length, typed.length);
+        this._completionActive = false;
+        this._query.set(typed);
+        this._suppressNextInput = true;
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+        return true;
+    }
+    // ─── Selection ───────────────────────────────────────────────────────────────
+    /**
+     * Panel (pointer) selection handler — subscribed to the `mlv-dropdown-panel`
+     * `valueChange`. The panel is never seeded with a committed selection
+     * (`selectedValues` is always `[]`), so any non-empty emit is a genuine pick —
+     * no aria reconciliation guard is needed. Public so the overlay subscription
+     * (and unit tests) can invoke it.
+     */
+    selectFromPanel(values) {
+        if (!values.length)
+            return;
+        const picked = values[values.length - 1];
+        const option = this._results().find((o) => o.value === picked);
+        if (option)
+            this._commit(option);
+    }
+    /** @private Commits a suggestion: writes its full label into the input (caret to end), emits, and closes. */
+    _commit(option) {
+        this._completionActive = false;
+        const el = this._inputEl();
+        if (el) {
+            el.value = option.label;
+            // Full value, caret at the end (clears any completion selection).
+            el.setSelectionRange(option.label.length, option.label.length);
+            // Notify mlv-input / ngModel listeners without re-triggering our own filter.
+            this._suppressNextInput = true;
+            el.dispatchEvent(new Event('input', { bubbles: true }));
+        }
+        this._query.set(option.label);
+        this.selectedValue.set(option.value);
+        this.optionSelected.emit(option);
+        this._closePopup();
+    }
+    /** @private Clears the input text (second Escape) and notifies listeners. */
+    _clearInput() {
+        const el = this._inputEl();
+        if (!el)
+            return;
+        el.value = '';
+        this._query.set('');
+        el.dispatchEvent(new Event('input', { bubbles: true }));
+    }
+    // ─── Overlay ─────────────────────────────────────────────────────────────────
+    /** @private Creates (if needed) and shows the suggestion overlay. */
+    _openPopup() {
+        if (this._isInert())
+            return;
+        const el = this._inputEl();
+        if (!el)
+            return;
+        if (!this._overlayRef) {
+            const positionStrategy = this._overlay
+                .position()
+                .flexibleConnectedTo(el)
+                .withFlexibleDimensions(true)
+                .withPush(false)
+                .withPositions(AUTOCOMPLETE_POSITIONS);
+            this._overlayRef = this._overlay.create({
+                positionStrategy,
+                direction: this._rtlService.resolveDirection(el),
+                scrollStrategy: this._overlay.scrollStrategies.reposition(),
+                width: el.getBoundingClientRect().width,
+                hasBackdrop: false,
+            });
+            const ref = this._overlayRef.attach(new ComponentPortal(MlvDropdownPanel, this._vcr, this._injector));
+            // Paint a floating surface on the bare panel. `mlv-combobox` / `mlv-select`
+            // nest the panel in a styled `mlv-popup`; the directive's overlay hosts it
+            // directly, so it would otherwise be transparent over the page. Applied on
+            // the panel's own host element (which already carries `mlv-dropdown-panel`)
+            // as the BEM modifier — dropdown-panel.scss owns the `--surface` styles.
+            this._renderer.addClass(ref.location.nativeElement, 'mlv-dropdown-panel--surface');
+            // `valueChange` is an `output()` (OutputRef) — subscribe directly; the
+            // subscription is torn down when the overlay (and panel) is disposed.
+            ref.instance.valueChange.subscribe((values) => this.selectFromPanel(values));
+            // Lazy paging: the panel's scroll sentinel asks for the next data-source
+            // page. The adapter is a no-op unless another page exists and the previous
+            // one has landed.
+            ref.instance.loadMore.subscribe(() => this._adapter.loadMore());
+            // Keep DOM focus in the input while pointing at options: a mousedown on the
+            // panel must not blur the field (which would close before the click lands).
+            this._renderer.listen(this._overlayRef.overlayElement, 'mousedown', (event) => event.preventDefault());
+            // Backdrop-less dismissal: close on a genuine outside click (the input /
+            // host is treated as "inside" so caret repositioning does not dismiss).
+            this._overlayRef
+                .outsidePointerEvents()
+                .pipe(takeUntilDestroyed(this._destroyRef))
+                .subscribe((event) => {
+                if (!this._hostEl.contains(event.target))
+                    this._closePopup();
+            });
+            this._panelRef.set(ref);
+        }
+        if (!this._open()) {
+            this._open.set(true);
+            this.openedChange.emit(true);
+        }
+    }
+    /** @private Hides and disposes the overlay, resetting popup state. */
+    _closePopup() {
+        const wasOpen = this._open();
+        this._activeDescendant.reset();
+        this._disposeOverlay();
+        this._open.set(false);
+        if (wasOpen)
+            this.openedChange.emit(false);
+    }
+    /** @private Tears down the overlay + panel ref. */
+    _disposeOverlay() {
+        this._panelRef.set(null);
+        if (this._overlayRef) {
+            this._overlayRef.dispose();
+            this._overlayRef = null;
+        }
+    }
+    /** @private Whether all interaction paths are suppressed. */
+    _isInert() {
+        return this.disabled();
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: MlvAutocomplete, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.7", type: MlvAutocomplete, isStandalone: true, selector: "[mlvAutocomplete],[mlvAutocompleteSearch]", inputs: { options: { classPropertyName: "options", publicName: "mlvAutocomplete", isSignal: true, isRequired: false, transformFunction: null }, search: { classPropertyName: "search", publicName: "mlvAutocompleteSearch", isSignal: true, isRequired: false, transformFunction: null }, toOption: { classPropertyName: "toOption", publicName: "mlvAutocompleteToOption", isSignal: true, isRequired: false, transformFunction: null }, matcher: { classPropertyName: "matcher", publicName: "mlvAutocompleteMatcher", isSignal: true, isRequired: false, transformFunction: null }, debounce: { classPropertyName: "debounce", publicName: "mlvAutocompleteDebounce", isSignal: true, isRequired: false, transformFunction: null }, minLength: { classPropertyName: "minLength", publicName: "mlvAutocompleteMinLength", isSignal: true, isRequired: false, transformFunction: null }, highlight: { classPropertyName: "highlight", publicName: "mlvAutocompleteHighlight", isSignal: true, isRequired: false, transformFunction: null }, inline: { classPropertyName: "inline", publicName: "mlvAutocompleteInline", isSignal: true, isRequired: false, transformFunction: null }, openOnFocus: { classPropertyName: "openOnFocus", publicName: "mlvAutocompleteOpenOnFocus", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "mlvAutocompleteDisabled", isSignal: true, isRequired: false, transformFunction: null }, loadingText: { classPropertyName: "loadingText", publicName: "mlvAutocompleteLoadingText", isSignal: true, isRequired: false, transformFunction: null }, infiniteScrollThreshold: { classPropertyName: "infiniteScrollThreshold", publicName: "mlvAutocompleteInfiniteScrollThreshold", isSignal: true, isRequired: false, transformFunction: null }, density: { classPropertyName: "density", publicName: "mlvAutocompleteDensity", isSignal: true, isRequired: false, transformFunction: null }, selectedValue: { classPropertyName: "selectedValue", publicName: "mlvAutocompleteValue", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { selectedValue: "mlvAutocompleteValueChange", optionSelected: "optionSelected", openedChange: "openedChange" }, providers: [MlvSelectionService], exportAs: ["mlvAutocomplete"], ngImport: i0 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: MlvAutocomplete, decorators: [{
+            type: Directive,
+            args: [{
+                    selector: '[mlvAutocomplete],[mlvAutocompleteSearch]',
+                    exportAs: 'mlvAutocomplete',
+                    // Provided per-directive so the `mlv-dropdown-panel` component portal (created
+                    // with this directive's element injector) can resolve the MlvSelectionService it
+                    // injects — matching how `mlv-combobox` / `mlv-select` scope it.
+                    providers: [MlvSelectionService],
+                }]
+        }], ctorParameters: () => [], propDecorators: { options: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocomplete", required: false }] }], search: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteSearch", required: false }] }], toOption: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteToOption", required: false }] }], matcher: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteMatcher", required: false }] }], debounce: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteDebounce", required: false }] }], minLength: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteMinLength", required: false }] }], highlight: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteHighlight", required: false }] }], inline: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteInline", required: false }] }], openOnFocus: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteOpenOnFocus", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteDisabled", required: false }] }], loadingText: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteLoadingText", required: false }] }], infiniteScrollThreshold: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteInfiniteScrollThreshold", required: false }] }], density: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteDensity", required: false }] }], selectedValue: [{ type: i0.Input, args: [{ isSignal: true, alias: "mlvAutocompleteValue", required: false }] }, { type: i0.Output, args: ["mlvAutocompleteValueChange"] }], optionSelected: [{ type: i0.Output, args: ["optionSelected"] }], openedChange: [{ type: i0.Output, args: ["openedChange"] }] } });
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { MlvAutocomplete };
+//# sourceMappingURL=malva-ui-core-autocomplete.mjs.map