@nexterajs/ui 0.0.2 → 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, NxeExpr } 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 {
@@ -26,14 +109,17 @@ 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<NxeExpr>;
-    readonly displayExpr: _angular_core.Signal<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<NxeExpr>;
-    readonly valueExpr: _angular_core.Signal<NxeExpr>;
+    readonly valueExpr: _angular_core.Signal<string | ((item: unknown) => unknown)>;
     /** Field matched while searching (DevExtreme default `lovName`). */
     readonly searchExprInput: _angular_core.InputSignal<NxeExpr>;
     /**
@@ -42,10 +128,10 @@ declare class NxeSelectBoxComponent extends NxeFormControlBase<unknown> implemen
      * 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<NxeExpr>;
-    readonly searchEnabledInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    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
@@ -53,21 +139,40 @@ declare class NxeSelectBoxComponent extends NxeFormControlBase<unknown> implemen
      */
     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). */
@@ -75,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;
@@ -100,7 +215,7 @@ 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>;
 }
 
 /**
@@ -117,11 +232,12 @@ declare class NxeTagBoxComponent extends NxeFormControlBase<unknown[]> implement
     private readonly viewContainerRef;
     private readonly dropdownTemplate;
     private readonly inputEl;
-    readonly dataSource: _angular_core.InputSignal<readonly 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<NxeExpr>;
+    readonly displayExpr: _angular_core.Signal<string | ((item: unknown) => unknown)>;
     readonly valueExprInput: _angular_core.InputSignal<NxeExpr>;
-    readonly valueExpr: _angular_core.Signal<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
@@ -129,17 +245,17 @@ declare class NxeTagBoxComponent extends NxeFormControlBase<unknown[]> implement
      * 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<NxeExpr>;
-    readonly searchEnabledInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    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, unknown>;
+    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'`
@@ -148,12 +264,22 @@ declare class NxeTagBoxComponent extends NxeFormControlBase<unknown[]> implement
      */
     readonly showSelectionControls: _angular_core.Signal<boolean>;
     /** dx `selectAllText` — the label of the "Select All" row (dx: `dxList-selectAll`). */
-    readonly selectAllText: _angular_core.InputSignal<string>;
+    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>;
@@ -161,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;
@@ -176,9 +310,11 @@ declare class NxeTagBoxComponent extends NxeFormControlBase<unknown[]> implement
      * 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>;
+    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;
     /**
@@ -193,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; }; "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; }; }, {}, 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>;
 }
 
 /**
@@ -205,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>;
 }
@@ -227,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<NxeExpr>;
-    readonly displayExpr: _angular_core.Signal<NxeExpr>;
+    readonly displayExpr: _angular_core.Signal<string | ((item: unknown) => unknown)>;
     readonly valueExprInput: _angular_core.InputSignal<NxeExpr>;
-    readonly valueExpr: _angular_core.Signal<NxeExpr>;
-    readonly placeholderInput: _angular_core.InputSignal<string>;
+    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>;
@@ -245,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
@@ -262,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
@@ -298,24 +434,24 @@ 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>;
+    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;
@@ -324,6 +460,13 @@ declare class NxeListComponent {
     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. */
@@ -348,7 +491,7 @@ declare class NxeAutoCompleteComponent extends NxeFormControlBase<string> implem
     private readonly viewContainerRef;
     private readonly dropdownTemplate;
     private readonly inputEl;
-    readonly dataSource: _angular_core.InputSignal<readonly unknown[]>;
+    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. */
@@ -360,7 +503,7 @@ declare class NxeAutoCompleteComponent extends NxeFormControlBase<string> implem
     /** 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, unknown>;
+    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>;
@@ -448,5 +591,5 @@ declare class NxeOptionComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NxeOptionComponent, "nxe-option", ["nxeOption"], {}, {}, never, ["*"], true, never>;
 }
 
-export { NXE_AUTOCOMPLETE, NxeAutoCompleteComponent, NxeAutocompleteComponent, NxeAutocompleteTriggerDirective, NxeDropDownBoxComponent, NxeDropDownOptionsComponent, NxeListComponent, NxeOptionComponent, NxeSelectBoxComponent, NxeTagBoxComponent };
-export type { NxeAutoCompleteSearchMode, NxeAutoCompleteSelectionChangedEvent, 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 };