@nexterajs/ui 0.0.1 → 0.1.0

package/types/nexterajs-ui-dropdowns.d.ts

@@ -1,7 +1,90 @@
 import * as _angular_core from '@angular/core';
-import { OnDestroy, TemplateRef, InjectionToken, OnInit } from '@angular/core';
-import { NxeFormControlBase } from '@nexterajs/ui/core';
-import { Subject } from 'rxjs';
+import { Signal, OnDestroy, TemplateRef, InjectionToken, OnInit } from '@angular/core';
+import { NxeExpr, NxeFormControlBase } from '@nexterajs/ui/core';
+import { ObservableInput, Subject } from 'rxjs';
+
+/** Payload of the `(searchChange)` output of the pickers: the text the user has settled on. */
+interface NxeSearchChangedEvent {
+    searchValue: string;
+}
+/** What a picker hands to {@link NxePickerStore.load}; the names follow DevExtreme `LoadOptions`. */
+interface NxePickerLoadOptions {
+    searchValue: string;
+    searchExpr: NxeExpr;
+    searchOperation: 'contains';
+    skip: number;
+    take: number;
+}
+/** Second argument of the store callbacks: `signal` aborts when a newer query replaces this one. */
+interface NxePickerLoadContext {
+    signal: AbortSignal;
+}
+/** A page of rows; `totalCount` is optional and, when given, decides whether more pages exist. */
+interface NxePickerLoadResult<T = any> {
+    data: readonly T[];
+    totalCount?: number;
+}
+/**
+ * A lightweight server-backed source for `nxe-select-box` and `nxe-tag-box` (`[dataSource]`).
+ * Shaped like a DevExtreme `CustomStore`: `load` receives `{searchValue, skip, take}`, and `byKey`
+ * fetches one row so a selected value outside the loaded page keeps its label.
+ */
+interface NxePickerStore<T = any> {
+    load(options: NxePickerLoadOptions, context: NxePickerLoadContext): ObservableInput<readonly T[] | NxePickerLoadResult<T>>;
+    byKey?(key: unknown, context: NxePickerLoadContext): ObservableInput<T | null | undefined>;
+}
+/** True for a store object (anything with a `load` function that is not an array). */
+declare function nxeIsPickerStore(value: unknown): value is NxePickerStore;
+/** Reads the debounce, minimum length and remote settings of a picker; every member is a live signal. */
+interface NxePickerSearchConfig {
+    store: Signal<NxePickerStore | null>;
+    searchExpr: Signal<NxeExpr>;
+    searchTimeout: Signal<number>;
+    minSearchLength: Signal<number>;
+    showDataBeforeSearch: Signal<boolean>;
+    pageSize: Signal<number>;
+    /** Called with each debounced search that reaches `minSearchLength` (or is cleared). */
+    searchChange: (event: NxeSearchChangedEvent) => void;
+    /** Called after a page of rows has landed. */
+    loaded?: () => void;
+}
+/**
+ * The search plumbing shared by the pickers: debounces typing by `searchTimeout`, emits
+ * `searchChange` once the text reaches `minSearchLength` (or is cleared), and, when the
+ * `dataSource` is a {@link NxePickerStore}, queries it and keeps only the newest response.
+ * Must be created in an injection context. It uses no `effect()`: it reacts only to the explicit
+ * {@link typed}, {@link open} and {@link loadMore} calls.
+ */
+declare class NxePickerSearch {
+    private readonly cfg;
+    /** Rows of the store loaded so far (all pages of the current query). */
+    readonly items: _angular_core.WritableSignal<readonly unknown[]>;
+    readonly loading: _angular_core.WritableSignal<boolean>;
+    readonly error: _angular_core.WritableSignal<unknown>;
+    readonly hasMore: _angular_core.WritableSignal<boolean>;
+    private readonly typedText;
+    private loadedFor;
+    private seq;
+    private controller;
+    constructor(cfg: NxePickerSearchConfig);
+    get hasStore(): boolean;
+    /** True when `text` is long enough to be searched. */
+    reachesMinimum(text: string): boolean;
+    /** The user typed; the search settles after `searchTimeout`. */
+    typed(text: string): void;
+    /** The panel opened with `text` in the field: load the first page unless that query is current. */
+    open(text: string): void;
+    /** Loads the next page of the current query (a scroll-to-bottom handler calls this). */
+    loadMore(): void;
+    /** Fetches one row by key through `byKey`; `null` when the store cannot or does not know it. */
+    lookup(key: unknown): Promise<unknown>;
+    private settled;
+    /** The text actually sent to the store: below the minimum nothing is searched. */
+    private effective;
+    private query;
+    private cancel;
+    private run;
+}
 
 /** DevExtreme-shaped selection-changed payload (handlers read `selectedItem`). */
 interface NxeSelectionChangedEvent {
@@ -14,10 +97,11 @@ interface NxeSelectionChangedEvent {
  *
  * A signal-CVA single-select dropdown over a plain array (`[dataSource]`). It bakes in the app's
  * global `dxSelectBox.defaultOptions` (`displayExpr='lovName'`, `valueExpr='lovCode'`,
- * `searchEnabled`, `showClearButton`), so the bound control value is the `valueExpr` field
- * (a string code) and the field shows the `displayExpr` field. Dropdown is a CDK overlay with
- * an in-field search filter. Emits `(valueChange)` (the code) and `(onSelectionChanged)`
- * (`{selectedItem}`). Hosts a projected `nxe-validator` via {@link NXE_VALIDATION_TARGET}.
+ * `searchEnabled`), so the bound control value is the `valueExpr` field (a string code) and the
+ * field shows the `displayExpr` field. The clear button follows dx and is off unless asked for.
+ * Dropdown is a CDK overlay with an in-field search filter. Emits `(valueChange)` (the code) and
+ * `(onSelectionChanged)` (`{selectedItem}`). Hosts a projected `nxe-validator` via
+ * {@link NXE_VALIDATION_TARGET}.
  */
 declare class NxeSelectBoxComponent extends NxeFormControlBase<unknown> implements OnDestroy {
     private readonly overlay;
@@ -25,37 +109,70 @@ declare class NxeSelectBoxComponent extends NxeFormControlBase<unknown> implemen
     private readonly dropdownTemplate;
     private readonly inputEl;
     private readonly templates;
-    /** The source array (plain JS array of `Lov`-shaped objects, or primitives). */
-    readonly dataSource: _angular_core.InputSignal<readonly unknown[]>;
+    /**
+     * The source: a plain array of `Lov`-shaped objects (or primitives), or an {@link NxePickerStore}
+     * whose `load({searchValue, skip, take})` the box calls itself (server-side search).
+     */
+    readonly dataSource: _angular_core.InputSignal<NxePickerStore<any> | readonly unknown[] | null | undefined>;
     /** Field shown in the box/list (DevExtreme default `lovName`). Empty => the item itself. */
-    readonly displayExprInput: _angular_core.InputSignal<string>;
-    readonly displayExpr: _angular_core.Signal<string>;
+    readonly displayExprInput: _angular_core.InputSignal<NxeExpr>;
+    readonly displayExpr: _angular_core.Signal<string | ((item: unknown) => unknown)>;
     /** Field bound as the control value (DevExtreme default `lovCode`). Empty => the whole item. */
-    readonly valueExprInput: _angular_core.InputSignal<string>;
-    readonly valueExpr: _angular_core.Signal<string>;
+    readonly valueExprInput: _angular_core.InputSignal<NxeExpr>;
+    readonly valueExpr: _angular_core.Signal<string | ((item: unknown) => unknown)>;
     /** Field matched while searching (DevExtreme default `lovName`). */
-    readonly searchExprInput: _angular_core.InputSignal<string>;
-    readonly searchExpr: _angular_core.Signal<string>;
-    readonly searchEnabledInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly searchExprInput: _angular_core.InputSignal<NxeExpr>;
+    /**
+     * dx searches by `displayExpr` when `searchExpr` is not given. Defaulting to the literal
+     * 'lovName' instead meant that any picker with a custom displayExpr searched a field its
+     * items do not have, and found nothing - silently, because an empty result looks like no
+     * match. Where displayExpr is the default this resolves to 'lovName' exactly as before.
+     */
+    readonly searchExpr: _angular_core.Signal<string | ((item: unknown) => unknown)>;
+    readonly searchEnabledInput: _angular_core.InputSignalWithTransform<boolean | undefined, unknown>;
     readonly searchEnabled: _angular_core.Signal<boolean>;
-    readonly showClearButtonInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly showClearButtonInput: _angular_core.InputSignalWithTransform<boolean | undefined, unknown>;
+    /**
+     * dx defaults `showClearButton` to false (m_text_editor.base.js). The library used to default it
+     * on, which gave every host that never asked for one a clear button dx would not show. An app
+     * that wants it everywhere says so once through `NXE_DEFAULT_OPTIONS.selectBox.showClearButton`.
+     */
     readonly showClearButton: _angular_core.Signal<boolean>;
     /** dx parity: dx-select-box shows its drop-down arrow unless showDropDownButton=false. */
-    readonly showDropDownButtonInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly showDropDownButtonInput: _angular_core.InputSignalWithTransform<boolean | undefined, unknown>;
     readonly showDropDownButton: _angular_core.Signal<boolean>;
-    readonly placeholderInput: _angular_core.InputSignal<string>;
+    readonly placeholderInput: _angular_core.InputSignal<string | undefined>;
     readonly placeholder: _angular_core.Signal<string>;
     /** Named template ('displayItem') for dropdown rows; `$implicit` = the item. */
-    readonly itemTemplate: _angular_core.InputSignal<string>;
+    readonly itemTemplate: _angular_core.InputSignal<string | undefined>;
     /** Named template ('inputField') for the closed field; `$implicit` = the selected item. */
-    readonly fieldTemplate: _angular_core.InputSignal<string>;
+    readonly fieldTemplate: _angular_core.InputSignal<string | undefined>;
+    /** dx `searchTimeout`: ms of typing pause before `(searchChange)` fires or a store is queried. */
+    readonly searchTimeout: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** dx `minSearchLength`: characters needed before a search is emitted, applied or sent. */
+    readonly minSearchLength: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** dx `showDataBeforeSearch`: list rows while the text is shorter than `minSearchLength`. */
+    readonly showDataBeforeSearch: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Rows requested per page from a store `dataSource` (`take`); more load on scroll to the end. */
+    readonly pageSize: _angular_core.InputSignalWithTransform<number, unknown>;
+    /**
+     * dx `displayValue`: the text shown for the current value while its row is not among the loaded
+     * ones (a store `dataSource` with the selection outside the current page, and no `byKey`).
+     */
+    readonly displayValue: _angular_core.InputSignal<string | null | undefined>;
     /** DevExtreme parity, cosmetic. */
     readonly hoverStateEnabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly onSelectionChanged: _angular_core.OutputEmitterRef<NxeSelectionChangedEvent>;
+    /**
+     * The search text settled: fires `searchTimeout` ms after the last keystroke, once the text has
+     * `minSearchLength` characters (or was cleared). Use it to query a server and replace
+     * `[dataSource]`, or pass a {@link NxePickerStore} and let the box query for you.
+     */
+    readonly searchChange: _angular_core.OutputEmitterRef<NxeSearchChangedEvent>;
     readonly focused: _angular_core.WritableSignal<boolean>;
     readonly open: _angular_core.WritableSignal<boolean>;
     /** What the user has typed to filter (null = not actively searching → show display text). */
-    readonly searchText: _angular_core.WritableSignal<string>;
+    readonly searchText: _angular_core.WritableSignal<string | null>;
     readonly activeIndex: _angular_core.WritableSignal<number>;
     readonly panelWidth: _angular_core.WritableSignal<number>;
     /** DevExtreme `.instance` facade — only `focus()` is used (via the customAutofocus directive). */
@@ -63,23 +180,33 @@ declare class NxeSelectBoxComponent extends NxeFormControlBase<unknown> implemen
     private overlayRef?;
     private closeSub?;
     private flipSub?;
+    private readonly store;
+    private readonly search;
+    /** Rows picked or fetched by key from a store, so the label outlives the page that held them. */
+    private readonly resolved;
     private readonly items;
+    /** Fetches the row of an externally set value through `byKey` when no loaded row has it. */
+    private readonly keyLookup;
+    private findRow;
+    private remember;
     protected display(item: unknown): string;
     private extractValue;
-    readonly selectedItem: _angular_core.Signal<unknown>;
+    readonly selectedItem: _angular_core.Signal<{} | null>;
     readonly hasValue: _angular_core.Signal<boolean>;
     /** Display text when the field is not being searched. */
     protected readonly displayText: _angular_core.Signal<string>;
     /** Value bound to the input element. */
     protected readonly inputDisplay: _angular_core.Signal<string>;
     protected readonly filteredItems: _angular_core.Signal<readonly unknown[]>;
-    protected readonly itemTemplateRef: _angular_core.Signal<TemplateRef<unknown>>;
-    protected readonly fieldTemplateRef: _angular_core.Signal<TemplateRef<unknown>>;
+    protected readonly itemTemplateRef: _angular_core.Signal<TemplateRef<unknown> | null>;
+    protected readonly fieldTemplateRef: _angular_core.Signal<TemplateRef<unknown> | null>;
     protected isSelected(item: unknown): boolean;
     /** Imperative focus (DevExtreme `.instance.focus()` via customAutofocus). */
     focus(): void;
     protected onFieldMousedown(event: MouseEvent): void;
     protected onSearchInput(event: Event): void;
+    /** Loads the next page of a store `dataSource` when the list is scrolled to its end. */
+    protected onPanelScroll(event: Event): void;
     protected onBlur(): void;
     protected selectItem(item: unknown, event: Event): void;
     protected onClear(event: Event): void;
@@ -88,37 +215,71 @@ declare class NxeSelectBoxComponent extends NxeFormControlBase<unknown> implemen
     private close;
     ngOnDestroy(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeSelectBoxComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeSelectBoxComponent, "nxe-select-box", never, { "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; "displayExprInput": { "alias": "displayExpr"; "required": false; "isSignal": true; }; "valueExprInput": { "alias": "valueExpr"; "required": false; "isSignal": true; }; "searchExprInput": { "alias": "searchExpr"; "required": false; "isSignal": true; }; "searchEnabledInput": { "alias": "searchEnabled"; "required": false; "isSignal": true; }; "showClearButtonInput": { "alias": "showClearButton"; "required": false; "isSignal": true; }; "showDropDownButtonInput": { "alias": "showDropDownButton"; "required": false; "isSignal": true; }; "placeholderInput": { "alias": "placeholder"; "required": false; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; "isSignal": true; }; "fieldTemplate": { "alias": "fieldTemplate"; "required": false; "isSignal": true; }; "hoverStateEnabled": { "alias": "hoverStateEnabled"; "required": false; "isSignal": true; }; }, { "onSelectionChanged": "onSelectionChanged"; }, ["templates"], ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeSelectBoxComponent, "nxe-select-box", never, { "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; "displayExprInput": { "alias": "displayExpr"; "required": false; "isSignal": true; }; "valueExprInput": { "alias": "valueExpr"; "required": false; "isSignal": true; }; "searchExprInput": { "alias": "searchExpr"; "required": false; "isSignal": true; }; "searchEnabledInput": { "alias": "searchEnabled"; "required": false; "isSignal": true; }; "showClearButtonInput": { "alias": "showClearButton"; "required": false; "isSignal": true; }; "showDropDownButtonInput": { "alias": "showDropDownButton"; "required": false; "isSignal": true; }; "placeholderInput": { "alias": "placeholder"; "required": false; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; "isSignal": true; }; "fieldTemplate": { "alias": "fieldTemplate"; "required": false; "isSignal": true; }; "searchTimeout": { "alias": "searchTimeout"; "required": false; "isSignal": true; }; "minSearchLength": { "alias": "minSearchLength"; "required": false; "isSignal": true; }; "showDataBeforeSearch": { "alias": "showDataBeforeSearch"; "required": false; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; "displayValue": { "alias": "displayValue"; "required": false; "isSignal": true; }; "hoverStateEnabled": { "alias": "hoverStateEnabled"; "required": false; "isSignal": true; }; }, { "onSelectionChanged": "onSelectionChanged"; "searchChange": "searchChange"; }, ["templates"], ["*"], true, never>;
 }
 
 /**
  * `nxe-tag-box` — drop-in replacement for DevExtreme `dx-tag-box` (multi-select sibling of
  * `nxe-select-box`). The bound value is an **array of `valueExpr` keys** (`lovCode` strings).
  * Bakes in the app's global `dxTagBox.defaultOptions` (display/search `lovName`, value `lovCode`,
- * search + clear + selection-controls on). Selected items render as removable chips; the dropdown
- * shows a checkbox per row. Provides {@link NXE_VALIDATION_TARGET} for a projected `nxe-validator`.
+ * search + selection-controls on); the clear button follows dx and is off unless asked for.
+ * Selected items render as removable chips; with selection controls the dropdown shows a checkbox
+ * per row under a tri-state "Select All". Provides {@link NXE_VALIDATION_TARGET} for a projected
+ * `nxe-validator`.
  */
 declare class NxeTagBoxComponent extends NxeFormControlBase<unknown[]> implements OnDestroy {
     private readonly overlay;
     private readonly viewContainerRef;
     private readonly dropdownTemplate;
     private readonly inputEl;
-    readonly dataSource: _angular_core.InputSignal<readonly unknown[]>;
-    readonly displayExprInput: _angular_core.InputSignal<string>;
-    readonly displayExpr: _angular_core.Signal<string>;
-    readonly valueExprInput: _angular_core.InputSignal<string>;
-    readonly valueExpr: _angular_core.Signal<string>;
-    readonly searchExprInput: _angular_core.InputSignal<string>;
-    readonly searchExpr: _angular_core.Signal<string>;
-    readonly searchEnabledInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** A plain array, or an {@link NxePickerStore} the box queries itself (server-side search). */
+    readonly dataSource: _angular_core.InputSignal<NxePickerStore<any> | readonly unknown[] | null | undefined>;
+    readonly displayExprInput: _angular_core.InputSignal<NxeExpr>;
+    readonly displayExpr: _angular_core.Signal<string | ((item: unknown) => unknown)>;
+    readonly valueExprInput: _angular_core.InputSignal<NxeExpr>;
+    readonly valueExpr: _angular_core.Signal<string | ((item: unknown) => unknown)>;
+    readonly searchExprInput: _angular_core.InputSignal<NxeExpr>;
+    /**
+     * dx searches by `displayExpr` when `searchExpr` is not given. Defaulting to the literal
+     * 'lovName' instead meant that any picker with a custom displayExpr searched a field its
+     * items do not have, and found nothing - silently, because an empty result looks like no
+     * match. Where displayExpr is the default this resolves to 'lovName' exactly as before.
+     */
+    readonly searchExpr: _angular_core.Signal<string | ((item: unknown) => unknown)>;
+    readonly searchEnabledInput: _angular_core.InputSignalWithTransform<boolean | undefined, unknown>;
     readonly searchEnabled: _angular_core.Signal<boolean>;
-    readonly showClearButtonInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly showClearButtonInput: _angular_core.InputSignalWithTransform<boolean | undefined, unknown>;
+    /**
+     * dx defaults `showClearButton` to false (m_text_editor.base.js). The library used to default it
+     * on, which gave every host that never asked for one a clear button dx would not show. An app
+     * that wants it everywhere says so once through `NXE_DEFAULT_OPTIONS.tagBox.showClearButton`.
+     */
     readonly showClearButton: _angular_core.Signal<boolean>;
+    readonly showSelectionControlsInput: _angular_core.InputSignalWithTransform<boolean | undefined, unknown>;
+    /**
+     * dx `showSelectionControls`. On (the literal, and what every consumer site passes): a checkbox
+     * per row and a tri-state "Select All" row — dx switches its list to `selectionMode: 'all'`
+     * (m_tag_box.js `_listConfig`). Off: plain rows whose fill marks the selection
+     * (`selectionMode: 'multiple'`).
+     */
+    readonly showSelectionControls: _angular_core.Signal<boolean>;
+    /** dx `selectAllText` — the label of the "Select All" row (dx: `dxList-selectAll`). */
+    readonly selectAllText: _angular_core.InputSignal<string | undefined>;
     /** dx parity: dx-tag-box does NOT show a drop-down arrow unless showDropDownButton is set. */
-    readonly showDropDownButtonInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly showDropDownButtonInput: _angular_core.InputSignalWithTransform<boolean | undefined, unknown>;
     readonly showDropDownButton: _angular_core.Signal<boolean>;
-    readonly placeholderInput: _angular_core.InputSignal<string>;
+    readonly placeholderInput: _angular_core.InputSignal<string | undefined>;
     readonly placeholder: _angular_core.Signal<string>;
+    /** dx `searchTimeout`: ms of typing pause before `(searchChange)` fires or a store is queried. */
+    readonly searchTimeout: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** dx `minSearchLength`: characters needed before a search is emitted, applied or sent. */
+    readonly minSearchLength: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** dx `showDataBeforeSearch`: list rows while the text is shorter than `minSearchLength`. */
+    readonly showDataBeforeSearch: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /** Rows requested per page from a store `dataSource` (`take`); more load on scroll to the end. */
+    readonly pageSize: _angular_core.InputSignalWithTransform<number, unknown>;
+    /** The search text settled (after `searchTimeout`, once it has `minSearchLength` characters or was cleared). */
+    readonly searchChange: _angular_core.OutputEmitterRef<NxeSearchChangedEvent>;
     readonly focused: _angular_core.WritableSignal<boolean>;
     readonly open: _angular_core.WritableSignal<boolean>;
     readonly searchText: _angular_core.WritableSignal<string>;
@@ -126,7 +287,15 @@ declare class NxeTagBoxComponent extends NxeFormControlBase<unknown[]> implement
     private overlayRef?;
     private closeSub?;
     private flipSub?;
+    private readonly store;
+    private readonly search;
+    /** Rows picked or fetched by key from a store, so a chip keeps its label off the loaded page. */
+    private readonly resolved;
     private readonly items;
+    /** Fetches, through `byKey`, the rows of externally set keys that no loaded row has. */
+    private readonly keyLookup;
+    private findRow;
+    private remember;
     /** The selected keys (always an array). */
     private readonly selectedKeys;
     protected display(item: unknown): string;
@@ -136,10 +305,23 @@ declare class NxeTagBoxComponent extends NxeFormControlBase<unknown[]> implement
     protected readonly hasValue: _angular_core.Signal<boolean>;
     protected readonly filteredItems: _angular_core.Signal<readonly unknown[]>;
     protected isSelected(item: unknown): boolean;
+    /**
+     * The "Select All" checkbox value over the rows currently listed — dx `selectAllMode: 'page'`,
+     * so a search narrows what it counts: `true` when every listed row is selected, `false` when
+     * none is, and `undefined` (indeterminate) in between.
+     */
+    protected readonly selectAllState: _angular_core.Signal<boolean | undefined>;
     protected onFieldMousedown(event: MouseEvent): void;
     protected onSearchInput(event: Event): void;
+    /** Loads the next page of a store `dataSource` when the list is scrolled to its end. */
+    protected onPanelScroll(event: Event): void;
     protected onBlur(): void;
     protected toggle(item: unknown, event: Event): void;
+    /**
+     * dx `_selectAllHandler`: anything short of all-selected selects every listed row (keeping
+     * selections the search hides); all-selected deselects the listed rows only.
+     */
+    protected toggleAll(event: Event): void;
     protected removeTag(item: unknown, event: Event): void;
     protected onClear(event: Event): void;
     protected onKeydown(event: KeyboardEvent): void;
@@ -147,7 +329,7 @@ declare class NxeTagBoxComponent extends NxeFormControlBase<unknown[]> implement
     private close;
     ngOnDestroy(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeTagBoxComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeTagBoxComponent, "nxe-tag-box", never, { "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; "displayExprInput": { "alias": "displayExpr"; "required": false; "isSignal": true; }; "valueExprInput": { "alias": "valueExpr"; "required": false; "isSignal": true; }; "searchExprInput": { "alias": "searchExpr"; "required": false; "isSignal": true; }; "searchEnabledInput": { "alias": "searchEnabled"; "required": false; "isSignal": true; }; "showClearButtonInput": { "alias": "showClearButton"; "required": false; "isSignal": true; }; "showDropDownButtonInput": { "alias": "showDropDownButton"; "required": false; "isSignal": true; }; "placeholderInput": { "alias": "placeholder"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeTagBoxComponent, "nxe-tag-box", never, { "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; "displayExprInput": { "alias": "displayExpr"; "required": false; "isSignal": true; }; "valueExprInput": { "alias": "valueExpr"; "required": false; "isSignal": true; }; "searchExprInput": { "alias": "searchExpr"; "required": false; "isSignal": true; }; "searchEnabledInput": { "alias": "searchEnabled"; "required": false; "isSignal": true; }; "showClearButtonInput": { "alias": "showClearButton"; "required": false; "isSignal": true; }; "showSelectionControlsInput": { "alias": "showSelectionControls"; "required": false; "isSignal": true; }; "selectAllText": { "alias": "selectAllText"; "required": false; "isSignal": true; }; "showDropDownButtonInput": { "alias": "showDropDownButton"; "required": false; "isSignal": true; }; "placeholderInput": { "alias": "placeholder"; "required": false; "isSignal": true; }; "searchTimeout": { "alias": "searchTimeout"; "required": false; "isSignal": true; }; "minSearchLength": { "alias": "minSearchLength"; "required": false; "isSignal": true; }; "showDataBeforeSearch": { "alias": "showDataBeforeSearch"; "required": false; "isSignal": true; }; "pageSize": { "alias": "pageSize"; "required": false; "isSignal": true; }; }, { "searchChange": "searchChange"; }, never, ["*"], true, never>;
 }
 
 /**
@@ -159,8 +341,8 @@ declare class NxeDropDownOptionsComponent {
     readonly wrapperAttr: _angular_core.InputSignal<{
         class?: string;
         id?: string;
-    }>;
-    readonly width: _angular_core.InputSignal<string | number>;
+    } | undefined>;
+    readonly width: _angular_core.InputSignal<string | number | undefined>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeDropDownOptionsComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeDropDownOptionsComponent, "nxe-drop-down-options", never, { "wrapperAttr": { "alias": "wrapperAttr"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
@@ -181,13 +363,13 @@ declare class NxeDropDownBoxComponent extends NxeFormControlBase<unknown> implem
     private readonly panelTemplate;
     private readonly templates;
     private readonly options;
-    readonly dataSource: _angular_core.InputSignal<readonly unknown[]>;
+    readonly dataSource: _angular_core.InputSignal<readonly unknown[] | null | undefined>;
     /** Field name shown in the closed box; empty => the raw value string. */
-    readonly displayExprInput: _angular_core.InputSignal<string>;
-    readonly displayExpr: _angular_core.Signal<string>;
-    readonly valueExprInput: _angular_core.InputSignal<string>;
-    readonly valueExpr: _angular_core.Signal<string>;
-    readonly placeholderInput: _angular_core.InputSignal<string>;
+    readonly displayExprInput: _angular_core.InputSignal<NxeExpr>;
+    readonly displayExpr: _angular_core.Signal<string | ((item: unknown) => unknown)>;
+    readonly valueExprInput: _angular_core.InputSignal<NxeExpr>;
+    readonly valueExpr: _angular_core.Signal<string | ((item: unknown) => unknown)>;
+    readonly placeholderInput: _angular_core.InputSignal<string | undefined>;
     readonly placeholder: _angular_core.Signal<string>;
     /** DevExtreme `[dropDownOptions]` — accepted for parity (popup-class hook). */
     readonly dropDownOptions: _angular_core.InputSignal<unknown>;
@@ -199,7 +381,7 @@ declare class NxeDropDownBoxComponent extends NxeFormControlBase<unknown> implem
      * every existing call site picks from a grid where clearing was never offered. Opt in where null
      * is a value the field can legitimately hold.
      */
-    readonly showClearButtonInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    readonly showClearButtonInput: _angular_core.InputSignalWithTransform<boolean | undefined, unknown>;
     readonly showClearButton: _angular_core.Signal<boolean>;
     /**
      * DevExtreme `[opened]` (orbit addition): programmatic open/close. Reflects the panel state
@@ -216,7 +398,7 @@ declare class NxeDropDownBoxComponent extends NxeFormControlBase<unknown> implem
     private overlayRef?;
     private closeSub?;
     private flipSub?;
-    protected readonly contentTemplateRef: _angular_core.Signal<TemplateRef<unknown>>;
+    protected readonly contentTemplateRef: _angular_core.Signal<TemplateRef<unknown> | null>;
     /**
      * DevExtreme sizes the popup to the editor, and every call site that says anything says
      * `width="100%"` — which means that same thing. So the panel is fixed at the field's width and
@@ -252,23 +434,102 @@ interface NxeListItemClickEvent {
 declare class NxeListComponent {
     private readonly menu;
     private readonly templates;
-    readonly dataSource: _angular_core.InputSignal<readonly unknown[]>;
+    readonly dataSource: _angular_core.InputSignal<readonly unknown[] | null | undefined>;
     /** Named template ('listItem'/'actionButton') for each row; `$implicit` = the item. */
-    readonly itemTemplate: _angular_core.InputSignal<string>;
+    readonly itemTemplate: _angular_core.InputSignal<string | undefined>;
     /** DevExtreme `[elementAttr]` — `{ id, class }` applied to the host. */
     readonly elementAttr: _angular_core.InputSignal<{
         id?: string;
         class?: string;
-    }>;
+    } | undefined>;
+    /**
+     * dx `keyExpr` — the field identifying an item. Used for `@for` tracking, so a list whose
+     * items are replaced by equal-but-not-identical objects keeps its DOM instead of rebuilding
+     * every row. Falls back to the index when unset, which is the previous behaviour.
+     */
+    readonly keyExpr: _angular_core.InputSignal<string | undefined>;
+    protected trackItem(item: unknown, index: number): unknown;
     readonly onItemClick: _angular_core.OutputEmitterRef<NxeListItemClickEvent>;
     protected readonly items: _angular_core.Signal<readonly unknown[]>;
-    protected readonly itemTemplateRef: _angular_core.Signal<_angular_core.TemplateRef<unknown>>;
+    protected readonly itemTemplateRef: _angular_core.Signal<_angular_core.TemplateRef<unknown> | null>;
     protected text(item: unknown): string;
     /** dx parity: dx-list honors `item.disabled` (grayed, non-interactive). */
     protected isDisabled(item: unknown): boolean;
     protected select(item: unknown): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeListComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeListComponent, "nxe-list", never, { "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; "isSignal": true; }; "elementAttr": { "alias": "elementAttr"; "required": false; "isSignal": true; }; }, { "onItemClick": "onItemClick"; }, ["templates"], never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeListComponent, "nxe-list", never, { "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; "isSignal": true; }; "elementAttr": { "alias": "elementAttr"; "required": false; "isSignal": true; }; "keyExpr": { "alias": "keyExpr"; "required": false; "isSignal": true; }; }, { "onItemClick": "onItemClick"; }, ["templates"], never, true, never>;
+}
+
+/** What an `nxe-menu-item` needs from its parent menu: a way to request close. */
+interface NxeMenuCloseTarget {
+    closeMenu(): void;
+}
+/** DI token the menu provides so projected `nxe-menu-item`s can close it on click. */
+declare const NXE_MENU: InjectionToken<NxeMenuCloseTarget>;
+
+/** How a typed query is matched against `searchExpr` (dx `searchMode`). */
+type NxeAutoCompleteSearchMode = 'contains' | 'startswith' | 'equals';
+/** DevExtreme-shaped selection payload, emitted when a suggestion is picked. */
+interface NxeAutoCompleteSelectionChangedEvent {
+    selectedItem: unknown;
+    value: string | null;
+}
+/**
+ * `nxe-auto-complete` — drop-in replacement for DevExtreme `dx-autocomplete`.
+ *
+ * The distinction from `nxe-select-box` is the value contract, and it is the whole reason this
+ * is a separate component: here the control value is the TEXT the user typed. A suggestion is a
+ * shortcut for typing, not a constraint on what may be entered, so free text survives and
+ * `valueExpr` only says which field of a picked item becomes that text.
+ *
+ * Deliberately not merged into the existing Material-shaped `nxe-autocomplete`: that one takes
+ * projected `nxe-option` children rather than a `[dataSource]`, so the two have incompatible
+ * content models and merging them would make every future change to one a risk to the other.
+ */
+declare class NxeAutoCompleteComponent extends NxeFormControlBase<string> implements OnDestroy {
+    private readonly overlay;
+    private readonly viewContainerRef;
+    private readonly dropdownTemplate;
+    private readonly inputEl;
+    readonly dataSource: _angular_core.InputSignal<readonly unknown[] | null | undefined>;
+    /** Field of a picked item that becomes the value (dx default `lovName`). */
+    readonly valueExpr: _angular_core.InputSignal<NxeExpr>;
+    /** Field matched against the query; defaults to {@link valueExpr}, as dx does. */
+    readonly searchExprInput: _angular_core.InputSignal<NxeExpr>;
+    readonly searchExpr: _angular_core.Signal<NxeExpr>;
+    readonly searchMode: _angular_core.InputSignal<NxeAutoCompleteSearchMode>;
+    /** Characters required before suggestions appear. dx defaults to 1; 0 shows all on focus. */
+    readonly minSearchLength: _angular_core.InputSignal<number>;
+    /** dx caps the suggestion list; beyond this the user is expected to keep typing. */
+    readonly maxItemCount: _angular_core.InputSignal<number>;
+    readonly placeholder: _angular_core.InputSignal<string>;
+    readonly showClearButton: _angular_core.InputSignalWithTransform<boolean | undefined, unknown>;
+    readonly onSelectionChanged: _angular_core.OutputEmitterRef<NxeAutoCompleteSelectionChangedEvent>;
+    readonly focused: _angular_core.WritableSignal<boolean>;
+    readonly open: _angular_core.WritableSignal<boolean>;
+    readonly activeIndex: _angular_core.WritableSignal<number>;
+    readonly panelWidth: _angular_core.WritableSignal<number>;
+    /** dx `.instance` facade — `focus()` is what the autofocus directive calls. */
+    get instance(): this;
+    private overlayRef?;
+    private closeSub?;
+    private flipSub?;
+    protected readonly text: _angular_core.Signal<string>;
+    protected itemText(item: unknown): string;
+    private searchText;
+    protected readonly suggestions: _angular_core.Signal<unknown[]>;
+    protected onFieldInput(event: Event): void;
+    protected onFocus(): void;
+    protected onBlur(): void;
+    protected pick(item: unknown, event: Event): void;
+    protected onKeydown(event: KeyboardEvent): void;
+    protected onClear(event: Event): void;
+    focus(): void;
+    private openPanel;
+    private closePanel;
+    ngOnDestroy(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NxeAutoCompleteComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeAutoCompleteComponent, "nxe-auto-complete", never, { "dataSource": { "alias": "dataSource"; "required": false; "isSignal": true; }; "valueExpr": { "alias": "valueExpr"; "required": false; "isSignal": true; }; "searchExprInput": { "alias": "searchExpr"; "required": false; "isSignal": true; }; "searchMode": { "alias": "searchMode"; "required": false; "isSignal": true; }; "minSearchLength": { "alias": "minSearchLength"; "required": false; "isSignal": true; }; "maxItemCount": { "alias": "maxItemCount"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "showClearButton": { "alias": "showClearButton"; "required": false; "isSignal": true; }; }, { "onSelectionChanged": "onSelectionChanged"; }, never, ["*"], true, never>;
 }
 
 /** What an `nxe-option` needs from its parent autocomplete: a way to request close on select. */
@@ -330,5 +591,5 @@ declare class NxeOptionComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeOptionComponent, "nxe-option", ["nxeOption"], {}, {}, never, ["*"], true, never>;
 }
 
-export { NXE_AUTOCOMPLETE, NxeAutocompleteComponent, NxeAutocompleteTriggerDirective, NxeDropDownBoxComponent, NxeDropDownOptionsComponent, NxeListComponent, NxeOptionComponent, NxeSelectBoxComponent, NxeTagBoxComponent };
-export type { NxeAutocompletePanel, NxeListItemClickEvent, NxeSelectionChangedEvent };
+export { NXE_AUTOCOMPLETE, NXE_MENU, NxeAutoCompleteComponent, NxeAutocompleteComponent, NxeAutocompleteTriggerDirective, NxeDropDownBoxComponent, NxeDropDownOptionsComponent, NxeListComponent, NxeOptionComponent, NxePickerSearch, NxeSelectBoxComponent, NxeTagBoxComponent, nxeIsPickerStore };
+export type { NxeAutoCompleteSearchMode, NxeAutoCompleteSelectionChangedEvent, NxeAutocompletePanel, NxeListItemClickEvent, NxeMenuCloseTarget, NxePickerLoadContext, NxePickerLoadOptions, NxePickerLoadResult, NxePickerSearchConfig, NxePickerStore, NxeSearchChangedEvent, NxeSelectionChangedEvent };