@acorex/components 22.0.0-next.9 → 22.0.0

package/lookup/README.md

@@ -0,0 +1,74 @@
+# @acorex/components/lookup
+
+An advanced drop-down (lookup) component with six modes, `AXDataSource` support, and virtual scrolling.
+
+## Modes
+
+| Mode                | Description                                                         |
+| ------------------- | ------------------------------------------------------------------- |
+| `drop-down-list`    | A predefined list of options for picking single values.             |
+| `multi-select`      | A predefined list of options for multiple item selection.           |
+| `drop-down-tree`    | A tree-like structure for single item selection.                    |
+| `multi-select-tree` | A tree-like structure for multiple item selection.                  |
+| `multi-column`      | An `ax-data-table` grid; further pages load on scroll.              |
+| `multi-column-tree` | A multi-column table with a drop-down tree inside it (expandable rows). |
+
+## Usage
+
+```ts
+import { AXLookupComponent } from '@acorex/components/lookup';
+import { AXDataSource } from '@acorex/cdk/common';
+```
+
+```html
+<!-- DropDownList -->
+<ax-lookup mode="drop-down-list" [dataSource]="items" [(ngModel)]="selected" placeholder="Select..."></ax-lookup>
+
+<!-- Skip byKey when the full item is already known (e.g. edit form) -->
+<ax-lookup
+  mode="drop-down-list"
+  [dataSource]="remoteUsers"
+  [valueItems]="[knownUser]"
+  valueField="id"
+  textField="name"
+  [(ngModel)]="userId"
+></ax-lookup>
+
+<!-- MultiSelect -->
+<ax-lookup mode="multi-select" [dataSource]="items" [(ngModel)]="selectedValues"></ax-lookup>
+
+<!-- DropDownTree / MultiSelectTree -->
+<ax-lookup mode="drop-down-tree" [treeDataSource]="nodes" textField="title" [(ngModel)]="selectedNode"></ax-lookup>
+<ax-lookup mode="multi-select-tree" [treeDataSource]="nodes" textField="title" [(ngModel)]="selectedNodes"></ax-lookup>
+
+<!-- MultiColumnComboBox -->
+<ax-lookup mode="multi-column" [dataSource]="items" [columns]="columns" [(ngModel)]="selected"></ax-lookup>
+
+<!-- MultiColumnTree (table + expandable tree) -->
+<ax-lookup
+  mode="multi-column-tree"
+  [treeDataSource]="nodes"
+  [columns]="columns"
+  textField="title"
+  [(ngModel)]="selectedNode"
+></ax-lookup>
+```
+
+Value binding uses the signal `value` model (`FormValueControl`) — prefer `[(ngModel)]` (or `[(value)]` / signal forms). No `ControlValueAccessor`.
+
+- `dataSource`: `AXDataSource` or a plain array (list and multi-column modes). Supports remote paging, `byKey` value resolution, and server-side filtering. Also used by `multi-column-tree` when `treeDataSource` is not set (hierarchical load via `treeParentField`).
+- `valueItems`: full items that resolve the current `value` key(s) without calling `byKey` (useful when the parent already loaded the selected entity). Missing keys still fall through to `find` / `byKey`. You can also call `seedItems(items)` imperatively.
+- `treeDataSource`: node array or lazy children callback (tree modes, including `multi-column-tree`).
+- `valueField` / `textField` / `disabledField`: field mappings. For tree modes these map to the tree `idField` / `titleField`.
+- `columns`: column definitions (`{ field, title, width?, expandHandler? }`) for `multi-column` and `multi-column-tree` (mapped to `ax-text-column`).
+- `treeParentField` / `hasChildrenField`: hierarchy fields for `multi-column-tree` (defaults `parentId` / `hasChild`).
+- `searchable`: when `true` (default), the trigger accepts typing and filters the list or tree in every mode. Nested array trees keep matching branches and expand ancestors of hits; lazy callback trees filter each loaded level (unloaded descendants are not searched). When `false`, the trigger is select-only.
+- `adaptivityEnabled`: when `true` (default), the list opens as a bottom actionsheet on small screens instead of a dropdown; set `false` to always use the anchored dropdown.
+- `caption`: title shown in the actionsheet header (falls back to `placeholder`).
+- `alternate`: when `true`, list rows use alternating background colors for easier scanning (all modes, including tree).
+- `searchPlaceholder`: placeholder for the multi-select / multi-select-tree trigger search input when chips are already selected.
+- `itemHeight` / `maxVisibleItems`: list virtual-scroll sizing, and multi-column table viewport height (multi-column loads more pages on scroll, not via a pager).
+- `look`: the same editor-container look schemes as other editors like `ax-text-box`.
+- `ax-prefix` / `ax-suffix`: project decorators into the editor container.
+
+Each mode is rendered by its own internal mini component (`ax-lookup-drop-down-list`, `ax-lookup-multi-select`, `ax-lookup-drop-down-tree`, `ax-lookup-multi-select-tree`, `ax-lookup-multi-column`, `ax-lookup-multi-column-tree`), all exported for direct use.

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@acorex/components",
-  "version": "22.0.0-next.9",
+  "version": "22.0.0",
   "peerDependencies": {
-    "@acorex/core": "22.0.0-next.9",
-    "@acorex/cdk": "22.0.0-next.9",
+    "@acorex/core": "22.0.0",
+    "@acorex/cdk": "22.0.0",
+    "@angular/aria": ">=22.1.0",
     "polytype": ">=0.17.0",
     "angular-imask": ">=7.6.1",
     "imask": ">=7.6.1",
@@ -134,6 +135,10 @@
       "types": "./types/acorex-components-color-palette.d.ts",
       "default": "./fesm2022/acorex-components-color-palette.mjs"
     },
+    "./combo-box": {
+      "types": "./types/acorex-components-combo-box.d.ts",
+      "default": "./fesm2022/acorex-components-combo-box.mjs"
+    },
     "./command": {
       "types": "./types/acorex-components-command.d.ts",
       "default": "./fesm2022/acorex-components-command.mjs"
@@ -254,6 +259,10 @@
       "types": "./types/acorex-components-loading-dialog.d.ts",
       "default": "./fesm2022/acorex-components-loading-dialog.mjs"
     },
+    "./lookup": {
+      "types": "./types/acorex-components-lookup.d.ts",
+      "default": "./fesm2022/acorex-components-lookup.mjs"
+    },
     "./map": {
       "types": "./types/acorex-components-map.d.ts",
       "default": "./fesm2022/acorex-components-map.mjs"
@@ -378,10 +387,6 @@
       "types": "./types/acorex-components-selection-list.d.ts",
       "default": "./fesm2022/acorex-components-selection-list.mjs"
     },
-    "./selection-list-2": {
-      "types": "./types/acorex-components-selection-list-2.d.ts",
-      "default": "./fesm2022/acorex-components-selection-list-2.mjs"
-    },
     "./side-menu": {
       "types": "./types/acorex-components-side-menu.d.ts",
       "default": "./fesm2022/acorex-components-side-menu.mjs"

package/select-box/README.md

@@ -1,3 +1,8 @@
 # @acorex/components/select-box
 
+> **Deprecated.** This component is no longer supported.
+>
+> - Use [`combo-box`](../combo-box) when your data is a simple array.
+> - Use [`lookup`](../lookup) when you need advanced features and `AXDataSource` support.
+
 Secondary entry point of `@acorex/components`. It can be used by importing from `@acorex/components/select-box`.

package/types/acorex-components-action-sheet.d.ts

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { TemplateRef, Type, OnInit, AfterViewInit, OnDestroy } from '@angular/core';
+import { TemplateRef, Type, ElementRef, OnInit, AfterViewInit, OnDestroy } from '@angular/core';
 import { AXStyleColorType, AXComponentCloseEvent, MXBaseComponent } from '@acorex/cdk/common';
 import { AXOverlayRef } from '@acorex/cdk/overlay';
 import { AXComponentInputs, AXComponentType } from '@acorex/core/components';
@@ -37,6 +37,14 @@ interface AXActionSheetConfig {
     content?: AXActionSheetContentType;
     draggable?: boolean;
     dragUp?: boolean;
+    /**
+     * Element used to resolve inherited visual context for overlays rendered
+     * outside the originating DOM subtree.
+     *
+     * This affects Appearance, Light/Dark theme, Contrast, Size, and supported
+     * Density context. It does not affect overlay positioning.
+     */
+    contextElement?: HTMLElement | ElementRef<HTMLElement>;
 }
 /**
  * Reference to an open action sheet, providing methods to interact with it.

package/types/acorex-components-combo-box.d.ts

@@ -0,0 +1,280 @@
+import * as _angular_core from '@angular/core';
+import { TemplateRef, ElementRef } from '@angular/core';
+import { NXValueComponent, AXStyleLookType, AXValueChangedEvent, AXFocusEvent, AXItemClickEvent, AXItemSelectedEvent, AXEvent, AXHtmlEvent } from '@acorex/cdk/common';
+import { AXPopoverComponent } from '@acorex/components/popover';
+import { AXSearchBoxComponent } from '@acorex/components/search-box';
+import { Combobox } from '@angular/aria/combobox';
+import { Listbox } from '@angular/aria/listbox';
+import { FormValueControl } from '@angular/forms/signals';
+
+/**
+ * An item in the combo box list.
+ *
+ * - `id` — unique key used for filtering/search and list identity
+ * - `text` — label shown in the list and in the trigger/input
+ * - `value` — value written to the component model when the item is selected
+ */
+interface AXComboBoxItem {
+    id: string;
+    text: string;
+    value: string | number;
+}
+/**
+ * The combo box model value: a scalar (or `null`) in single-select mode,
+ * or an array of scalars in multi-select mode.
+ */
+type AXComboBoxValue = string | number | (string | number)[] | null;
+
+/**
+ * A minimal combo box for selecting one or more values from a list of items.
+ *
+ * Built on top of the `@angular/aria/combobox` directives, it supports two behaviors:
+ * - `searchable="true"` (default): an input with typeahead filtering (matches `id`). On small
+ *   screens with `adaptivityEnabled`, the trigger is select-like and search moves into the actionsheet.
+ * - `searchable="false"`: a select-like, non-editable trigger (same input; typing blocked without
+ *   Combobox `readonly`, so Tab focus and keyboard open/select keep working).
+ *
+ * With `multiple="true"`, selected values are shown as chips in the trigger and the popup stays
+ * open while toggling items (same interaction model as `ax-lookup` multi-select).
+ *
+ * With `adaptivityEnabled` (default `true`), the list opens as a bottom actionsheet on small
+ * screens instead of an anchored dropdown — the same alternate presentation as `ax-select-box`.
+ *
+ * Items use `text` for display, `id` for search/identity, and `value` as the submitted model value.
+ * Implements {@link FormValueControl} so `[(ngModel)]` / signal forms work via the `value` model
+ * (no `ControlValueAccessor`).
+ *
+ * @category Components
+ */
+declare class AXComboBoxComponent extends NXValueComponent implements FormValueControl<AXComboBoxValue> {
+    #private;
+    /**
+     * The name of the form field, used by validation rules and `ax-form.validate(names)`.
+     */
+    name: _angular_core.InputSignal<string>;
+    /**
+     * The list of items the user can select from.
+     * Each item has `id` (search/identity), `text` (display), and `value` (submitted).
+     */
+    items: _angular_core.InputSignal<AXComboBoxItem[]>;
+    /**
+     * Whether the combo box accepts typing and filters the list (`true`),
+     * or is a select-like, non-editable trigger (`false`).
+     * On small screens with `adaptivityEnabled`, search is typed in the actionsheet instead of the trigger.
+     */
+    searchable: _angular_core.InputSignal<boolean>;
+    /**
+     * When `true`, multiple items can be selected. Selected values are shown as chips and the
+     * popup stays open while toggling. The model value is an array (`[]` when empty).
+     */
+    multiple: _angular_core.InputSignal<boolean>;
+    /**
+     * When `true` (default), the popup list uses the alternate actionsheet presentation on small
+     * screens (`SM`). Searchable mode then shows a search field inside the sheet. When `false`,
+     * the list always opens as an anchored dropdown.
+     */
+    adaptivityEnabled: _angular_core.InputSignal<boolean>;
+    /**
+     * Title shown in the actionsheet header on small screens. Falls back to `placeholder`.
+     */
+    caption: _angular_core.InputSignal<string>;
+    /**
+     * When `true`, list rows use alternating background colors for easier scanning.
+     */
+    alternate: _angular_core.InputSignal<boolean>;
+    /**
+     * The placeholder text shown when no value is selected.
+     */
+    placeholder: _angular_core.InputSignal<string>;
+    /**
+     * Placeholder for the trigger search input when items are already selected (multi-select),
+     * and for the in-sheet search field on small screens. Falls back to `placeholder` when the
+     * selection is empty on desktop.
+     */
+    searchPlaceholder: _angular_core.InputSignal<string>;
+    /**
+     * Custom template rendered when the filtered list has no items.
+     * When omitted, a default "no result found" message is shown.
+     */
+    emptyTemplate: _angular_core.InputSignal<TemplateRef<unknown>>;
+    /**
+     * Custom template rendered for each item in the popup list.
+     * Context: `{ $implicit: AXComboBoxItem }`.
+     */
+    itemTemplate: _angular_core.InputSignal<TemplateRef<unknown>>;
+    /**
+     * Custom template rendered for the selected value in the trigger.
+     * Context: `{ $implicit: AXComboBoxItem }`.
+     * When `searchable` is true, the template is shown while the popup is closed and the input
+     * still reflects the selected text; typing/opening falls back to the plain input.
+     * In multi-select mode, the template replaces the chip text for each selected item.
+     */
+    selectedTemplate: _angular_core.InputSignal<TemplateRef<unknown>>;
+    /**
+     * Whether the combo box is disabled.
+     */
+    readonly disabled: _angular_core.InputSignal<boolean>;
+    /**
+     * Whether the combo box is readonly.
+     */
+    readonly readonly: _angular_core.InputSignal<boolean>;
+    /**
+     * Predefined look scheme of the editor container. Same looks as other editor components like ax-text-box.
+     */
+    look: _angular_core.ModelSignal<AXStyleLookType>;
+    /**
+     * The selected item `value`(s). Scalar (or `null`) in single mode; an array in multi mode.
+     * Supports `[(value)]`, `[(ngModel)]`, and signal forms via {@link FormValueControl}.
+     */
+    readonly value: _angular_core.ModelSignal<AXComboBoxValue>;
+    /**
+     * Emitted when the selected value changes.
+     */
+    onValueChanged: _angular_core.OutputEmitterRef<AXValueChangedEvent<AXComboBoxValue>>;
+    /**
+     * Emitted when the trigger receives focus.
+     */
+    onFocus: _angular_core.OutputEmitterRef<AXFocusEvent>;
+    /**
+     * Emitted when the trigger loses focus.
+     */
+    onBlur: _angular_core.OutputEmitterRef<AXFocusEvent>;
+    /**
+     * Emitted when a list item is clicked.
+     */
+    onItemClick: _angular_core.OutputEmitterRef<AXItemClickEvent<AXComboBoxItem>>;
+    /**
+     * Emitted when a list item is selected (click or keyboard).
+     */
+    onItemSelected: _angular_core.OutputEmitterRef<AXItemSelectedEvent<AXComboBoxItem>>;
+    /**
+     * Emitted when the popup list opens.
+     */
+    onOpened: _angular_core.OutputEmitterRef<AXEvent>;
+    /**
+     * Emitted when the popup list closes.
+     */
+    onClosed: _angular_core.OutputEmitterRef<AXEvent>;
+    /** Whether the popup is expanded. */
+    protected expanded: _angular_core.WritableSignal<boolean>;
+    /** Whether the list is currently shown as a bottom actionsheet (small screens + adaptivity). */
+    protected isActionsheetStyle: _angular_core.WritableSignal<boolean>;
+    /** Whether the trigger input is writable and filters as you type (desktop searchable only). */
+    protected isEditableTrigger: _angular_core.Signal<boolean>;
+    /** Whether search is typed in the actionsheet instead of the trigger. */
+    protected isSheetSearchEnabled: _angular_core.Signal<boolean>;
+    /** Query typed in the actionsheet search field (independent of the trigger display text). */
+    protected sheetSearchText: _angular_core.WritableSignal<string>;
+    /** The current selection normalized to an array of submitted values. */
+    protected selectedValues: _angular_core.Signal<(string | number)[]>;
+    /** Whether there is at least one selected value. */
+    protected hasSelection: _angular_core.Signal<boolean>;
+    /** Resolved selected items for the current model value(s). */
+    protected selectedItems: _angular_core.Signal<AXComboBoxItem[]>;
+    /** The item whose `value` matches the current model value (single-select). */
+    protected selectedItem: _angular_core.Signal<AXComboBoxItem>;
+    /** Display text shown in the trigger / used as the searchable input baseline (single-select). */
+    protected displayText: _angular_core.Signal<string>;
+    /**
+     * The text typed in the searchable input.
+     * Multi-select starts empty; single mode syncs from the selected display text.
+     */
+    protected searchText: _angular_core.WritableSignal<string>;
+    /** Whether the trigger should render `selectedTemplate` instead of the plain input text. */
+    protected showSelectedTemplate: _angular_core.Signal<boolean>;
+    /** Placeholder for the editable trigger search input in multi-select. */
+    protected triggerSearchPlaceholder: _angular_core.Signal<string>;
+    /** The listbox selection (item ids), kept in sync with the selected value(s). */
+    protected selection: _angular_core.WritableSignal<string[]>;
+    /** Items filtered by typed query against `id` when the combo box is searchable. */
+    protected filteredItems: _angular_core.Signal<AXComboBoxItem[]>;
+    /** Whether the filtered list is empty (empty-state vs hidden listbox). */
+    protected hasNoMatches: _angular_core.Signal<boolean>;
+    protected comboboxRef: _angular_core.Signal<Combobox>;
+    protected listboxRef: _angular_core.Signal<Listbox<any>>;
+    protected popoverRef: _angular_core.Signal<AXPopoverComponent>;
+    protected originRef: _angular_core.Signal<ElementRef<HTMLElement>>;
+    protected popupRef: _angular_core.Signal<ElementRef<HTMLElement>>;
+    protected sheetSearchRef: _angular_core.Signal<AXSearchBoxComponent>;
+    constructor();
+    /** Stable unique key for `@for` — avoids NG0955 when `id` is missing or duplicated. */
+    protected trackItemKey(index: number, item: AXComboBoxItem): string;
+    /** Whether the given item is currently selected. */
+    protected isItemSelected(item: AXComboBoxItem): boolean;
+    /**
+     * Opens (searchable) or toggles (non-searchable) the popup on trigger click.
+     */
+    protected onTriggerClick(): void;
+    /**
+     * Keyboard handling on the trigger:
+     * - Searchable: Enter never submits the form; with no matches the value is cleared (`null`).
+     * - Non-searchable: open with Enter/Space when collapsed; commit with Space when expanded.
+     * - Multi-select: Backspace removes the last chip when the search input is empty.
+     */
+    protected onTriggerKeydown(event: KeyboardEvent): void;
+    /** Handles Enter in the actionsheet search field (no form submit; clear on no matches). */
+    protected onSheetSearchKeydown(e: AXHtmlEvent<KeyboardEvent>): void;
+    /** Blocks typing when the trigger is not editable (keeps Tab / keyboard open working). */
+    protected onBeforeInput(event: Event): void;
+    /**
+     * Combobox `expanded` two-way binding. On actionsheet with in-sheet search, ignore collapse
+     * so focusing the search field (Aria combobox blur) does not close the popup. Dismiss is owned
+     * by the header Apply/close button, `commit()`, and Escape. On desktop, outside click also closes.
+     */
+    protected onExpandedChange(open: boolean): void;
+    /** Filters the list from the actionsheet search field (reads the input so delayed ngModel cannot block typing). */
+    protected onSheetSearchInput(): void;
+    /**
+     * Keeps the combobox expanded state in sync when the popover closes (e.g. click outside).
+     */
+    protected onPopoverClosed(): void;
+    /**
+     * Removes a single chip from the multi selection.
+     */
+    protected removeChip(event: Event, item: AXComboBoxItem): void;
+    /**
+     * Clears the selected value(s) and closes the popup.
+     * Sets `null` in single mode and `[]` in multi mode. Used by projected `ax-clear-button`.
+     *
+     * @param isUserInteraction - Whether the clear was triggered by the user.
+     */
+    reset(isUserInteraction?: boolean): void;
+    /**
+     * Closes the popup list.
+     */
+    close(): void;
+    /**
+     * Closes the popup list (alias for {@link close}, required by `AXClosableComponent`).
+     */
+    closeAll(): void;
+    /**
+     * Commits the highlighted (active) or clicked list item as the component value.
+     *
+     * With `selectionMode="explicit"`, arrow keys only move the active item; Enter/Space must resolve
+     * that option. Clicks resolve from the event target so we do not depend on listener order vs ngListbox.
+     *
+     * In multi-select mode the item is toggled and the popup stays open.
+     * When the user typed a query with no matches, Enter clears single-select to `null`.
+     */
+    protected onListEnter(event: Event): void;
+    protected commit(event?: Event): void;
+    /**
+     * Focuses the combo box trigger input.
+     */
+    focus(options?: FocusOptions): void;
+    /** Forwards native focus from the trigger input. */
+    protected emitOnFocus(e: FocusEvent): void;
+    /** Forwards native blur from the trigger input. */
+    protected emitOnBlur(e: FocusEvent): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AXComboBoxComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<AXComboBoxComponent, "ax-combo-box", never, { "name": { "alias": "name"; "required": false; "isSignal": true; }; "items": { "alias": "items"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; "multiple": { "alias": "multiple"; "required": false; "isSignal": true; }; "adaptivityEnabled": { "alias": "adaptivityEnabled"; "required": false; "isSignal": true; }; "caption": { "alias": "caption"; "required": false; "isSignal": true; }; "alternate": { "alias": "alternate"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "searchPlaceholder": { "alias": "searchPlaceholder"; "required": false; "isSignal": true; }; "emptyTemplate": { "alias": "emptyTemplate"; "required": false; "isSignal": true; }; "itemTemplate": { "alias": "itemTemplate"; "required": false; "isSignal": true; }; "selectedTemplate": { "alias": "selectedTemplate"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "look": { "alias": "look"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "look": "lookChange"; "value": "valueChange"; "onValueChanged": "onValueChanged"; "onFocus": "onFocus"; "onBlur": "onBlur"; "onItemClick": "onItemClick"; "onItemSelected": "onItemSelected"; "onOpened": "onOpened"; "onClosed": "onClosed"; }, never, ["ax-prefix", "ax-clear-button", "ax-suffix", "ax-header", "ax-footer", "ax-validation-rule"], true, never>;
+}
+
+declare class AXComboBoxModule {
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<AXComboBoxModule, never>;
+    static ɵmod: _angular_core.ɵɵNgModuleDeclaration<AXComboBoxModule, never, [typeof AXComboBoxComponent], [typeof AXComboBoxComponent]>;
+    static ɵinj: _angular_core.ɵɵInjectorDeclaration<AXComboBoxModule>;
+}
+
+export { AXComboBoxComponent, AXComboBoxModule };
+export type { AXComboBoxItem, AXComboBoxValue };