# @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.