`,
changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeStateSavingExample {
protected readonly tree = viewChild.required(KbqTreeSelection);
treeControl: FlatTreeControl;
treeFlattener: KbqTreeFlattener;
dataSource: KbqTreeFlatDataSource;
constructor() {
this.treeFlattener = new KbqTreeFlattener(this.transformer, this.getLevel, this.isExpandable, this.getChildren);
this.treeControl = new FlatTreeControl(
this.getLevel,
this.isExpandable,
this.getValue,
this.getViewValue
);
this.dataSource = new KbqTreeFlatDataSource(this.treeControl, this.treeFlattener);
this.dataSource.data = buildFileTree(DATA_OBJECT, 0);
}
hasChild(_: number, nodeData: FileFlatNode) {
return nodeData.expandable;
}
private transformer = (node: FileNode, level: number, parent: any) => {
const flatNode = new FileFlatNode();
flatNode.name = node.name;
flatNode.parent = parent;
flatNode.type = node.type;
flatNode.level = level;
flatNode.expandable = !!node.children;
return flatNode;
};
private getLevel = (node: FileFlatNode) => {
return node.level;
};
private isExpandable = (node: FileFlatNode) => {
return node.expandable;
};
private getChildren = (node: FileNode): FileNode[] => {
return node.children;
};
// The value expansion is persisted under. It must be stable across reloads, and unique within the
// tree — a node object is re-created whenever the data is replaced, so it cannot serve as the key.
private getValue = (node: FileFlatNode): string => {
return node.name;
};
private getViewValue = (node: FileFlatNode): string => {
const nodeType = node.type ? `.${node.type}` : '';
return `${node.name}${nodeType}`;
};
}
```
Selection is not persisted: it belongs to the form control the tree is bound to.
Expansion is persisted by the value `getValue` returns for a node, so that value has to be a string, stable across reloads and unique within the tree. A tree on a `NestedTreeControl` has no `getValue` and persists nothing, and neither does one rendered into an overlay — `kbq-tree-select` among them.
Expansion the application performs itself — `treeControl.expandAll()`, or writing to `expansionModel` directly — is not persisted until `saveState()` is called. `clearSavedState()` removes what is stored.
Keys, storage and expiry work the same for every component that persists — see [Saving component state](https://koobiq.io/en/components/core.md#saving-component-state).
### Focus and keyboard navigation
| Key | Action |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tab | If focus is on the component preceding the tree in tab order → Move to the first tree row or the selected row If focus is on any tree item and it has no additional actions → Move to the next component in tab order after the tree If focus is on any tree item and it has additional actions → Move to the first additional action If focus is on an item's additional action → Move to the next additional action (if one exists), otherwise move to the next component in tab order after the tree |
| Shift + Tab | If focus is on any tree item → Move to the previous component in tab order before the tree If focus is on the component following the tree in tab order → Move to the first tree row or the selected row |
| → | If focus is on a collapsed non-leaf item → Expand the nested items of that item If focus is on an expanded non-leaf item → Move to its first nested item If focus is on a leaf item → Nothing happens |
| ← | If focus is on an expanded non-leaf item → Collapse the nested items of that item If focus is on a collapsed non-leaf item → Move to its parent item If focus is on a leaf item → Move to its parent item If focus is on a top-level item → Nothing happens |
| ↵ | If focus is on a tree item → Trigger the primary action of that item If focus is on a tree item with a checkbox → Nothing happens If focus is on an additional action → Apply that additional action |
| Space | If focus is on a tree item with a checkbox → Select that tree item (and all nested items, if any) If focus is on a tree item → Nothing happens If focus is on an additional action → Apply that additional action |
| ↑ ↓ | If focus is on a tree item → Move to the next (if it is the last item — nothing happens) / previous tree item (if it is the first item — nothing happens) |
| PgUp | Move focus to the lowest visible item If the current item is the lowest visible → Scroll the tree down If the current item is the last in the tree → Nothing happens |
| PgDn | Move focus to the topmost visible item If the current item is the topmost visible → Scroll the tree up If the current item is the topmost in the tree → Nothing happens |
| Home | Move focus to the first tree item |
| End | Move focus to the last loaded tree item |
| Ctrl + click | Clicking tree items — multiple row selection Clicking a selected item — the item is deselected |
| Shift + ↓ Shift + ↑ | If focus is on a tree item → Multiple selection of the next / previous tree items (if the row is the first or last — nothing happens) |
| Ctrl + C | If focus is on tree items → Copy the content of the items By default, item names are copied. The separator between items is a line break |
| Ctrl + A | If focus is on any tree item → Select all tree items (including unloaded ones) |
| Printable characters | Move focus to the next item whose name starts with the typed characters. Typing several characters in quick succession matches them as one word |
### Accessibility
The tree exposes the structure it renders to assistive technology, so a screen reader announces an
item's nesting depth and whether it is expanded, selected or checked.
- The tree is a `role="tree"`, each row a `role="treeitem"`.
- The tab stop stays on the tree itself and the rows stay at `tabindex="-1"`, but the row the arrow
keys land on does take real focus, and is advertised through `aria-activedescendant` on top of that.
- Branch rows carry `aria-expanded` — including while a filter is active, which disables the chevrons
without turning the branches into leaves — and every row carries `aria-level`.
- Rows with a checkbox report `aria-checked`, including `mixed` for a partially selected branch; rows
without one report `aria-selected`.
- Expand/collapse chevrons are hidden from assistive technology: their state is already on the row, and
the ← and → keys drive them.
- The tree has no visible label of its own, so give it an accessible name with `aria-label`, or point
`aria-labelledby` at the element that labels it. A tree inside a `kbq-tree-select` is labelled by the
select and needs neither.
### Rendering
Every expanded item is rendered, with no windowing — a collapsed branch costs nothing, an expanded one
costs a DOM row per item. A tree that shows thousands of rows at once should keep its branches
collapsed or narrow the data with the search field.
Nodes are tracked by identity by default, so a data source that rebuilds its node objects on every
emission — a flattener among them — rebuilds every row, and a rebuilt node comes back collapsed.
Give the tree control a `trackBy` that returns a stable key of a node: the node is then expanded by that
key, and the tree re-uses the row of the same key across data updates. Set it before anything is
expanded, as a property or in the options, the last argument of `FlatTreeControl` and
`NestedTreeControl`:
**Example: Tree track by** (`tree-track-by`)
```ts tree-track-by-example.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { KbqButtonModule } from '@koobiq/components/button';
import { FlatTreeControl, KbqTreeFlatDataSource, KbqTreeFlattener, KbqTreeModule } from '@koobiq/components/tree';
type FileTree = { [name: string]: FileTree | string };
class FileNode {
name: string;
type?: string;
children?: FileNode[];
}
class FileFlatNode {
id: string;
name: string;
type?: string;
level: number;
expandable: boolean;
}
function buildFileTree(value: FileTree): FileNode[] {
return Object.keys(value).map((name) => {
const node = new FileNode();
const content = value[name];
node.name = name;
if (typeof content === 'object') {
node.children = buildFileTree(content);
} else {
node.type = content;
}
return node;
});
}
const DOCUMENTS: FileTree = {
'Delivery terms': 'pdf',
'Payment terms': 'pdf'
};
const DATA_OBJECT: FileTree = {
Documents: DOCUMENTS,
Pictures: {
Sun: 'png',
Woods: 'jpg'
},
Downloads: {
November: 'pdf',
October: 'pdf'
}
};
@Component({
selector: 'tree-track-by-example',
imports: [
KbqTreeModule,
KbqButtonModule
],
template: `
`,
changeDetection: ChangeDetectionStrategy.OnPush
})
export class TreeTrackByExample {
protected readonly treeControl = new FlatTreeControl(
(node) => node.level,
(node) => node.expandable,
(node) => node.id,
(node) => (node.type ? `${node.name}.${node.type}` : node.name)
);
// Every update flattens the data into new node objects: the expanded ones are found by their key.
protected readonly dataSource = new KbqTreeFlatDataSource(
this.treeControl,
new KbqTreeFlattener(
this.transformer,
(node) => node.level,
(node) => node.expandable,
(node) => node.children
),
buildFileTree(DATA_OBJECT)
);
private readonly drafts: FileTree = {};
constructor() {
// Before anything is expanded: a key is matched only under the function that stored it.
this.treeControl.trackBy = (node) => node.id;
}
protected hasChild(_: number, node: FileFlatNode): boolean {
return node.expandable;
}
protected addDraft(): void {
this.drafts[`Draft ${Object.keys(this.drafts).length + 1}`] = 'docx';
this.dataSource.data = buildFileTree({ ...DATA_OBJECT, Documents: { ...DOCUMENTS, ...this.drafts } });
}
private transformer(node: FileNode, level: number, parent: FileFlatNode | null): FileFlatNode {
const flatNode = new FileFlatNode();
flatNode.id = parent ? `${parent.id}/${node.name}` : node.name;
flatNode.name = node.name;
flatNode.type = node.type;
flatNode.level = level;
flatNode.expandable = !!node.children;
return flatNode;
}
}
```
`expansionModel` then holds the keys rather than the nodes, and the types of the tree, its events and
its data source take the key type as one more parameter: `KbqTreeSelection`,
`KbqTreeFlatDataSource`.
The tree's own `trackBy` input, a `TrackByFunction` of the index and the node, overrides the key the rows
are re-used by; it does not change the expansion. Without a control `trackBy` it is the only way to
re-use the rows.
## API
### Components
#### KbqTree (component)
```ts
@Component({ selector: 'kbq-tree', exportAs: 'kbqTree' })
class KbqTree extends KbqTreeBase {
treeControl = input();
readonly trackBy = input>();
dataSource = input | Observable | T[] | null | undefined>();
get nodeOutlet(): KbqTreeNodeOutlet;
readonly nodeDefs: Signal[]>;
viewChange: BehaviorSubject<{ start: number; end: number }>;
get hasSavedState(): boolean;
saveState(): void;
clearSavedState(): void;
renderNodeChanges(
data: T[] | ReadonlyArray,
dataDiffer?: IterableDiffer,
viewContainer?: ViewContainerRef,
parentData?: T
): void;
getNodeDef(data: T, i: number): KbqTreeNodeDef;
insertNode(
nodeData: T,
index: number,
viewContainer?: ViewContainerRef,
parentData?: T
): void;
}
```
- `[useStateSaving]`: `boolean` — Whether the component remembers its state across reloads and restores it on the next render.
Defaults to `true`, or to whatever `KBQ_STATE_SAVING_ENABLED` is provided as.
- `[stateSavingKey]`: `string` — The key the state is persisted under. While it is empty the key is derived from where the
component sits in the document, which moves when the surrounding markup is restructured — an `id`
on the component or any ancestor pins it just as well as this input does.
- `[treeControl]`: `C` — Controls the expanded state and holds the data nodes of the tree.
- `[trackBy]`: `TrackByFunction` — Tracking function that will be used to check the differences in data changes. Used similarly
to `ngFor` `trackBy` function. Optimize node operations by identifying a node based on its data
relative to the function to know if a node should be added/removed/moved.
Accepts a function that takes two parameters, `index` and `item`.
Views are reused for nodes the function reports as unchanged, which a data source that rebuilds
its node objects on every emission — a flattener among them — otherwise cannot get.
Defaults to the `trackBy` of the tree control, read when the tree initializes and when the data source changes.
- `[dataSource]`: `DataSource | Observable | T[] | null | undefined` — Provides a stream containing the latest data array to render. Influenced by the tree's
stream of view window (what dataNodes are currently on screen).
Data source can be an observable of data array, or a data array to render.
- `nodeOutlet`: `KbqTreeNodeOutlet` — Outlet within the tree's template where the data nodes are inserted.
- `nodeDefs`: `Signal[]>` — The tree node template for the tree
- `viewChange`: `BehaviorSubject<{ start: number; end: number }>` — Stream containing the latest information on what rows are being displayed on screen.
Can be used by the data source to as a heuristic of what data should be provided.
The tree renders every expanded node eagerly, so the window is the whole data set; a data source
cannot use it to page or virtualize. Windowing would have to emit a real range from a scroll
listener here first.
- `hasSavedState`: `boolean` — Whether state is currently persisted for this tree — restored on init, or written since.
Always `false` while `useStateSaving` is unset, and `false` again after `clearSavedState()`.
- `saveState()`: `void` — Persists the values of the currently expanded nodes.
Called for every expansion and collapse a user performs. Expansion driven by the application —
`treeControl.expandAll()`, or writing to `expansionModel` — is not persisted; call this to record it.
A no-op while a filter is active: what is expanded then is the result set, not a chosen state.
- `clearSavedState()`: `void` — Removes the state persisted for this tree.
Persistence itself stays on — the next expansion is written again.
- `renderNodeChanges()`: `void` — Check for changes made in the data and render each change (node added/removed/moved).
- `getNodeDef()`: `KbqTreeNodeDef` — Finds the matching node definition that should be used for this node data. If there is only
one node definition, it is returned. Otherwise, find the node definition that has a when
predicate that returns true with the data. If none return true, return the default node
definition.
- `insertNode()`: `void` — Create the embedded view for the data node template and place it in the correct index location
within the data node view container.
#### KbqTreeNodeToggleComponent (component)
```ts
@Component({ selector: 'kbq-tree-node-toggle', exportAs: 'kbqTreeNodeToggle' })
class KbqTreeNodeToggleComponent extends KbqTreeNodeToggleBaseDirective {
readonly node = input();
readonly recursive = input(false, {
alias: 'kbqTreeNodeToggleRecursive'
});
disabled = input(false);
get iconState(): boolean;
toggle(event: Event): void;
}
```
- `[kbqTreeNodeToggleRecursive]`: `boolean` — Whether toggling expands or collapses the whole subtree instead of the node alone.
#### KbqTreeOption (component)
```ts
@Component({ selector: 'kbq-tree-option', exportAs: 'kbqTreeOption' })
class KbqTreeOption extends KbqTreeNode implements KbqTitleTextRef {
readonly checkboxThirdState = input(false);
disabled = input(false);
readonly selectable = input(true);
showCheckbox = input();
readonly selectionChange = output();
/** @deprecated */
readonly onSelectionChange = output();
tree: KbqTreeOptionParent & KbqTreeBase;
readonly onFocus: Observable;
readonly onBlur: Observable;
preventBlur: boolean;
get parentTextElement(): ElementRef | undefined;
get textElement(): ElementRef | undefined;
readonly toggleElementDirective: Signal | undefined>;
readonly toggleElementComponent: Signal | undefined>;
readonly pseudoCheckbox: Signal;
readonly actionButton: Signal;
get tooltipTrigger(): KbqTooltipTrigger | undefined;
get dropdownTrigger(): KbqDropdownTrigger | undefined;
get externalPseudoCheckbox(): boolean;
value: any;
readonly userInteraction: EventEmitter;
selected: boolean;
get id(): string;
get viewValue(): string;
hasFocus: boolean;
get isExpandable(): boolean;
get level(): number;
get toggleElement(): KbqTreeNodeToggleBaseDirective | undefined;
get isToggleInDefaultPlace(): boolean;
checkboxState: KbqPseudoCheckboxState;
updateCheckboxState: () => void;
data: T;
get isExpanded(): boolean;
/** @deprecated */
static mostRecentTreeNode: KbqTreeNode | null;
descendantsAllSelected(): boolean;
descendantsPartiallySelected(): boolean;
updateParentsCheckboxState(node: T): void;
toggle(): void;
setSelected(selected: boolean): void;
focus(focusOrigin?: FocusOrigin): void;
blur(): void;
select(setFocus?: boolean): void;
deselect(): void;
onKeydown($event: any): void;
selectViaInteraction($event?: KeyboardEvent | MouseEvent): void;
emitSelectionChangeEvent(): void;
getHostElement(): HTMLElement;
markForCheck(): void;
}
```
- `[disabled]`: `boolean` — Whether the option is disabled: through its own input, the tree, or the tree control's `isDisabled`.
- `[selectable]`: `boolean` — Whether the option can be selected by user interaction (click, keyboard, select all).
A non-selectable option remains focusable, navigable and expandable.
Programmatic selection (`setSelected`, `select`, value accessor) is not affected.
Options that are not rendered (e.g. collapsed) are not checked by "select all".
- `[showCheckbox]`: `boolean | undefined` — Whether the option renders a pseudo-checkbox. Falls back to the tree's own mode until bound.
- `(selectionChange)`: `KbqTreeOptionChange` — Emits whenever the selected state of the option changes.
- `(onSelectionChange)`: `KbqTreeOptionChange` — Deprecated: Use `selectionChange` instead. Will be removed in 22.0.0.
- `onFocus`: `Observable` — Emits when the option takes focus.
- `onBlur`: `Observable` — Emits when the option loses focus.
- `parentTextElement`: `ElementRef | undefined` — Container of the option text, measured by `kbq-title`.
- `tooltipTrigger`: `KbqTooltipTrigger | undefined` — Tooltip trigger projected into the option.
- `dropdownTrigger`: `KbqDropdownTrigger | undefined` — Dropdown trigger projected into the option.
- `level`: `number` — The "select all" row sits above the tree at root depth; `getLevel` has no node to resolve for it.
- `mostRecentTreeNode`: `KbqTreeNode | null` — The most recently created `KbqTreeNode`, across every tree on the page.
Deprecated: Kept for backwards compatibility only — the tree hands a node its data through
`KbqTreeBase.registerNode`, which is scoped to the tree that owns the node. Will be removed in 22.0.0.
#### KbqTreeSelection (component)
```ts
@Component({ selector: 'kbq-tree-selection', exportAs: 'kbqTreeSelection' })
class KbqTreeSelection extends KbqTreeBase> implements ControlValueAccessor {
readonly ariaLabel = input(undefined, {
alias: 'aria-label'
});
readonly ariaLabelledby = input(undefined, {
alias: 'aria-labelledby'
});
autoSelect = input();
multiple = input();
noUnselectLast = input();
typeAhead = input(true);
readonly selectAllToggle = input(false);
selectAll = model(false);
disabled = input();
selectAllHandler = input<((event: KeyboardEvent, tree: KbqTreeSelection) => void) | undefined>();
treeControl = input();
readonly trackBy = input>();
dataSource = input | Observable | T[] | null | undefined>();
readonly navigationChange = output, T, K>>();
/** @deprecated */
readonly onSelectAll = output, T, K>>();
inSelect: boolean;
renderedOptions: QueryList>;
keyManager: FocusKeyManager>;
selectionModel: SelectionModel;
resetFocusedItemOnBlur: boolean;
userTabIndex: number | null;
optionShouldHoldFocusOnBlur: boolean;
ownsKeyboard: boolean;
readonly selectAllOption: Signal | undefined>;
get unorderedOptions(): QueryList>;
readonly selectionChange: EventEmitter, T, K>>;
readonly copyChange: EventEmitter, T, K>>;
/** @deprecated */
readonly onCopy: EventEmitter, T, K>>;
get optionFocusChanges(): Observable;
get optionBlurChanges(): Observable;
multipleMode: MultipleMode | null;
get allOptionsSelected(): boolean;
get selectAllState(): KbqPseudoCheckboxState;
get showCheckbox(): boolean;
get isEmpty(): boolean;
get nodesCount(): number;
get nodeOutlet(): KbqTreeNodeOutlet;
readonly nodeDefs: Signal[]>;
viewChange: BehaviorSubject<{ start: number; end: number }>;
get hasSavedState(): boolean;
initializeForEmbedding(selectionModel: SelectionModel): void;
focus($event: any): void;
blur(): void;
onKeyDown(event: KeyboardEvent): void;
handleKeydown(event: KeyboardEvent): void;
selectAllOptions(allowDeselect?: boolean): void;
copyActiveOption(event: KeyboardEvent): void;
setStateChildren(option: KbqTreeOption, state: boolean): void;
saveState(): void;
clearSavedState(): void;
getNodeDef(data: T, i: number): KbqTreeNodeDef;
insertNode(
nodeData: T,
index: number,
viewContainer?: ViewContainerRef,
parentData?: T
): void;
}
```
- `[aria-label]`: `string` — Accessible name of the tree. Set it whenever the tree has no visible label of its own; a tree
embedded in a `kbq-tree-select` is labelled by the select instead.
- `[aria-labelledby]`: `string` — Id of the element that labels the tree, for when the label is rendered next to it.
- `[autoSelect]`: `boolean | undefined` — Whether clicking a node clears the rest of the selection. Defaults to `true`, and to `false` for
`multiple="checkbox"`.
Assigning it — from a template binding or imperatively, as `KbqTreeSelect` does — replaces the
derived default, so a later `multiple` change leaves the value alone.
- `[multiple]`: `KbqMultipleInput | undefined` — Selection mode of the tree.
`checkbox` renders a checkbox in every node, `keyboard` selects without one. A bare `multiple` and
`true` both mean `checkbox`; `single`, `false` and an absent attribute mean single selection. The mode
can be changed at any time — narrowing it to single selection keeps the first selected node and
reports the shortened value through the `ControlValueAccessor`.
A tree rendered inside a `kbq-tree-select` shares its `SelectionModel` with the select, so the
select decides how many nodes may be selected: switching this input between single and multiple
selection there throws. Switching between `checkbox` and `keyboard` only changes the presentation
and is allowed.
The getter reports whether more than one node can be selected; read `multipleMode` for the mode
itself.
- `[noUnselectLast]`: `boolean | undefined` — Whether the last selected node can be deselected.
Derived from the mode until assigned, like `autoSelect`.
- `[typeAhead]`: `boolean` — Whether typing printable characters moves the focus to the next option whose label starts with
them. On by default.
Turn it off wherever the tree shares its keystrokes with a text field: an embedder such as
`KbqTreeSelect` routes everything the user types — the search query included — into this key
manager, and type-ahead would move the active option out from under the query.
- `[selectAllToggle]`: `boolean` — When `true`, a repeated Ctrl/Cmd+A deselects all options. Off by default (Ctrl+A only selects).
- `[(selectAll)]`: `boolean` — Whether to render the "select all" master checkbox above the nodes. Multiple selection only.
Enabling it also makes Ctrl/Cmd + A a two-way toggle, so the shortcut and the checkbox never
disagree (`selectAllToggle` is implied).
- `[disabled]`: `boolean | undefined` — Whether the tree is disabled, bound with `[disabled]` or set by a form control.
- `[selectAllHandler]`: `((event: KeyboardEvent, tree: KbqTreeSelection) => void) | undefined` — Function for handling the combination Ctrl + A (select all). By default, the internal handler is used,
which toggles the selection of all non-disabled, selectable options.
- `[useStateSaving]`: `boolean` — Whether the component remembers its state across reloads and restores it on the next render.
Defaults to `true`, or to whatever `KBQ_STATE_SAVING_ENABLED` is provided as.
- `[stateSavingKey]`: `string` — The key the state is persisted under. While it is empty the key is derived from where the
component sits in the document, which moves when the surrounding markup is restructured — an `id`
on the component or any ancestor pins it just as well as this input does.
- `[localeOverrides]`: `KbqPartialLocaleData | undefined` — Localized strings for this element and its subtree, keyed by locale section. Every key is optional at
every depth.
- `[treeControl]`: `C` — Controls the expanded state and holds the data nodes of the tree.
- `[trackBy]`: `TrackByFunction` — Tracking function that will be used to check the differences in data changes. Used similarly
to `ngFor` `trackBy` function. Optimize node operations by identifying a node based on its data
relative to the function to know if a node should be added/removed/moved.
Accepts a function that takes two parameters, `index` and `item`.
Views are reused for nodes the function reports as unchanged, which a data source that rebuilds
its node objects on every emission — a flattener among them — otherwise cannot get.
Defaults to the `trackBy` of the tree control, read when the tree initializes and when the data source changes.
- `[dataSource]`: `DataSource | Observable | T[] | null | undefined` — Provides a stream containing the latest data array to render. Influenced by the tree's
stream of view window (what dataNodes are currently on screen).
Data source can be an observable of data array, or a data array to render.
- `(onSelectAll)`: `KbqTreeSelectAllEvent, T, K>` — Deprecated: Use `selectAllChange` instead. Will be removed in 22.0.0.
- `inSelect`: `boolean` — Whether this tree-selection is rendered inside a select panel (enables option
hover-to-focus). Defaults to detecting a wrapping `KbqFormField`, and is forced to `true`
by the host `KbqTreeSelect` so hover works even when the tree-select has no form-field
wrapper (e.g. the filter-bar pipes render the tree-select bare).
- `selectionModel`: `SelectionModel` — Model backing the selection.
The instance is replaced whenever `multiple` changes the multiplicity, because CDK freezes that
flag at construction. Subscribe to `selectionChange` rather than to `selectionModel.changed`:
a subscription taken on the model directly is left behind on the discarded instance.
`T` is the type of the data nodes, inferred from `[treeControl]` in a template. A query names it:
`viewChild.required>(KbqTreeSelection)`, and a tree whose control has a `trackBy`
names the key type too: `KbqTreeSelection`.
- `ownsKeyboard`: `boolean` — Whether the tree acts on keyboard input itself. Turned off by an embedding host that owns the
keyboard, such as `KbqTreeSelect`.
- `selectAllOption`: `Signal | undefined>` — Reference to the built-in "select all" row, rendered only while `selectAll` is on.
- `selectionChange`: `EventEmitter, T, K>>` — Emits when the selection changes. A stream rather than an `output()`: `KbqTreeSelect` pipes it with rxjs.
- `copyChange`: `EventEmitter, T, K>>` — Emits when the active option is copied with Ctrl/Cmd + C. Subscribing replaces the built-in
clipboard handler, so the event has to stay an `EventEmitter`: the decision is made by reading
`observed`, which `OutputEmitterRef` does not have. A template listener subscribes to it through
the output below.
- `onCopy`: `EventEmitter, T, K>>` — Deprecated: Use `copyChange` instead. Will be removed in 22.0.0.
- `optionFocusChanges`: `Observable` — Emits when an option of the tree takes focus.
- `optionBlurChanges`: `Observable` — Emits when an option of the tree loses focus.
- `multipleMode`: `MultipleMode | null` — Resolved selection mode, or `null` when only one node can be selected.
- `allOptionsSelected`: `boolean` — Whether every node "select all" can act on is selected.
- `selectAllState`: `KbqPseudoCheckboxState` — State of the "select all" master checkbox.
- `nodesCount`: `number` — Number of real, data-backed nodes currently rendered — unlike `renderedOptions.length`, never
includes the "select all" row, which is appended to `renderedOptions` on its own, later-processed
reactive pass and would otherwise make a consumer's own node count race against that pass.
- `nodeOutlet`: `KbqTreeNodeOutlet` — Outlet within the tree's template where the data nodes are inserted.
- `nodeDefs`: `Signal[]>` — The tree node template for the tree
- `viewChange`: `BehaviorSubject<{ start: number; end: number }>` — Stream containing the latest information on what rows are being displayed on screen.
Can be used by the data source to as a heuristic of what data should be provided.
The tree renders every expanded node eagerly, so the window is the whole data set; a data source
cannot use it to page or virtualize. Windowing would have to emit a real range from a scroll
listener here first.
- `hasSavedState`: `boolean` — Whether state is currently persisted for this tree — restored on init, or written since.
Always `false` while `useStateSaving` is unset, and `false` again after `clearSavedState()`.
- `initializeForEmbedding()`: `void` — Rebuilds the tree around a selection model owned by an embedding host, such as `KbqTreeSelect`.
The host has to take the model over before the tree starts reacting to it, and re-running
`ngAfterContentInit()` is not a way to do that: neither `unorderedOptions` nor `renderedOptions` is
ever re-created, so a second run would only leave a second set of subscribers on both — every options
change handled twice, and the whole option sweep run twice per emission. Only the subscription that
depends on the model has to move, which is exactly what `bindSelectionModel` does.
- `onKeyDown()`: `void` — Host listener for keyboard input.
Does nothing while an embedding host owns the keyboard — `KbqTreeSelect` routes every key through
its own panel handler and calls back into `handleKeydown` for the parts it delegates, so without
this guard the same event would be acted on twice.
- `handleKeydown()`: `void` — Runs the tree's own keyboard handling, whether or not it owns the keyboard.
- `saveState()`: `void` — Persists the values of the currently expanded nodes.
Called for every expansion and collapse a user performs. Expansion driven by the application —
`treeControl.expandAll()`, or writing to `expansionModel` — is not persisted; call this to record it.
A no-op while a filter is active: what is expanded then is the result set, not a chosen state.
- `clearSavedState()`: `void` — Removes the state persisted for this tree.
Persistence itself stays on — the next expansion is written again.
- `getNodeDef()`: `KbqTreeNodeDef` — Finds the matching node definition that should be used for this node data. If there is only
one node definition, it is returned. Otherwise, find the node definition that has a when
predicate that returns true with the data. If none return true, return the default node
definition.
- `insertNode()`: `void` — Create the embedded view for the data node template and place it in the correct index location
within the data node view container.
### Directives
#### KbqTreeBase (directive)
Rendering core of the tree.
Originally forked from `@angular/cdk/tree` and maintained independently since: the node/outlet
contract, the option-based selection model and the filtering pipeline have all diverged, so
`@angular/cdk/tree` is deliberately not a dependency of this package and upstream fixes have to be
ported by hand.
`C` narrows the tree control a concrete tree accepts, and so the type its `treeControl` binding is checked against.
The bound leaves out `expansionModel` and `trackBy`, the members typed by the control's key, so that it admits
a control of any key type: the model makes a control invariant in that type.
```ts
@Directive()
class KbqTreeBase, 'expansionModel' | 'trackBy'> = TreeControl> implements CollectionViewer {
treeControl = input();
readonly trackBy = input>();
dataSource = input | Observable | T[] | null | undefined>();
get nodeOutlet(): KbqTreeNodeOutlet;
readonly nodeDefs: Signal[]>;
viewChange: BehaviorSubject<{ start: number; end: number }>;
get hasSavedState(): boolean;
saveState(): void;
clearSavedState(): void;
renderNodeChanges(
data: T[] | ReadonlyArray,
dataDiffer?: IterableDiffer,
viewContainer?: ViewContainerRef,
parentData?: T
): void;
getNodeDef(data: T, i: number): KbqTreeNodeDef;
insertNode(
nodeData: T,
index: number,
viewContainer?: ViewContainerRef,
parentData?: T
): void;
}
```
- `[treeControl]`: `C` — Controls the expanded state and holds the data nodes of the tree.
- `[trackBy]`: `TrackByFunction` — Tracking function that will be used to check the differences in data changes. Used similarly
to `ngFor` `trackBy` function. Optimize node operations by identifying a node based on its data
relative to the function to know if a node should be added/removed/moved.
Accepts a function that takes two parameters, `index` and `item`.
Views are reused for nodes the function reports as unchanged, which a data source that rebuilds
its node objects on every emission — a flattener among them — otherwise cannot get.
Defaults to the `trackBy` of the tree control, read when the tree initializes and when the data source changes.
- `[dataSource]`: `DataSource | Observable | T[] | null | undefined` — Provides a stream containing the latest data array to render. Influenced by the tree's
stream of view window (what dataNodes are currently on screen).
Data source can be an observable of data array, or a data array to render.
- `nodeOutlet`: `KbqTreeNodeOutlet` — Outlet within the tree's template where the data nodes are inserted.
- `nodeDefs`: `Signal[]>` — The tree node template for the tree
- `viewChange`: `BehaviorSubject<{ start: number; end: number }>` — Stream containing the latest information on what rows are being displayed on screen.
Can be used by the data source to as a heuristic of what data should be provided.
The tree renders every expanded node eagerly, so the window is the whole data set; a data source
cannot use it to page or virtualize. Windowing would have to emit a real range from a scroll
listener here first.
- `hasSavedState`: `boolean` — Whether state is currently persisted for this tree — restored on init, or written since.
Always `false` while `useStateSaving` is unset, and `false` again after `clearSavedState()`.
- `saveState()`: `void` — Persists the values of the currently expanded nodes.
Called for every expansion and collapse a user performs. Expansion driven by the application —
`treeControl.expandAll()`, or writing to `expansionModel` — is not persisted; call this to record it.
A no-op while a filter is active: what is expanded then is the result set, not a chosen state.
- `clearSavedState()`: `void` — Removes the state persisted for this tree.
Persistence itself stays on — the next expansion is written again.
- `renderNodeChanges()`: `void` — Check for changes made in the data and render each change (node added/removed/moved).
- `getNodeDef()`: `KbqTreeNodeDef` — Finds the matching node definition that should be used for this node data. If there is only
one node definition, it is returned. Otherwise, find the node definition that has a when
predicate that returns true with the data. If none return true, return the default node
definition.
- `insertNode()`: `void` — Create the embedded view for the data node template and place it in the correct index location
within the data node view container.
#### KbqTreeNode (directive)
```ts
@Directive({ selector: 'kbq-tree-node', exportAs: 'kbqTreeNode' })
class KbqTreeNode implements IFocusableOption {
tree: KbqTreeBase>;
data: T;
get isExpanded(): boolean;
get level(): number;
/** @deprecated */
static mostRecentTreeNode: KbqTreeNode | null;
focus(): void;
}
```
- `mostRecentTreeNode`: `KbqTreeNode | null` — The most recently created `KbqTreeNode`, across every tree on the page.
Deprecated: Kept for backwards compatibility only — the tree hands a node its data through
`KbqTreeBase.registerNode`, which is scoped to the tree that owns the node. Will be removed in 22.0.0.
#### KbqTreeNodeDef (directive)
Data node definition for the KbqTree.
Captures the node's template and a when predicate that describes when this node should be used.
```ts
@Directive({ selector: '[kbqTreeNodeDef]' })
class KbqTreeNodeDef {
readonly data = input(undefined, { alias: 'kbqTreeNode' });
@Input('kbqTreeNodeDefWhen') when: (index: number, nodeData: T) => boolean;
template: TemplateRef;
}
```
- `[kbqTreeNodeDefWhen]`: `(index: number, nodeData: T) => boolean` — Function that should return true if this node template should be used for the provided node
data and index. If left undefined, this node will be considered the default node template to
use when no other when functions return true for the data.
For every node, there must be at least one when function that passes or an undefined to
default.
#### KbqTreeNodeOutlet (directive)
```ts
@Directive({ selector: '[kbqTreeNodeOutlet]' })
class KbqTreeNodeOutlet {
viewContainer: ViewContainerRef;
}
```
#### KbqTreeNodePadding (directive)
```ts
@Directive({ selector: '[kbqTreeNodePadding]', exportAs: 'kbqTreeNodePadding' })
class KbqTreeNodePadding {
readonly indent = input(12, {
alias: 'kbqTreeNodePaddingIndent'
});
level: number;
get leftPadding(): number;
get leftPaddingForFirstLevel(): number;
get indentUnits(): string;
withIcon: boolean;
iconWidth: number;
paddingIndent(): string | null;
}
```
- `[kbqTreeNodePaddingIndent]`: `number | string` — Indentation added per nesting level. Accepts a bare number (px) or a value with CSS units.
- `indentUnits`: `string` — CSS units used for the indentation value.
- `iconWidth`: `number` — Horizontal room a toggle takes up in a row: its own 16px box plus the option's 8px `gap`. A node
without a toggle reserves the same amount so its content lines up with a sibling that has one —
which is why widening the toggle itself pushes every branch row out of line.
#### KbqTreeNodeToggleDirective (directive)
```ts
@Directive({
selector: '[kbq-tree-node-toggle], [kbqTreeNodeToggle]',
exportAs: 'kbqTreeNodeToggle'
})
class KbqTreeNodeToggleDirective extends KbqTreeNodeToggleBaseDirective {
readonly node = input();
readonly recursive = input(false, {
alias: 'kbqTreeNodeToggleRecursive'
});
disabled = input(false);
get iconState(): boolean;
toggle(event: Event): void;
}
```
- `[kbqTreeNodeToggleRecursive]`: `boolean` — Whether toggling expands or collapses the whole subtree instead of the node alone.
### Classes
#### BaseTreeControl (abstract class)
Base tree control. It has basic toggle/expand/collapse operations on a single data node.
```ts
abstract class BaseTreeControl implements TreeControl {
dataNodes: T[];
expansionModel: SelectionModel;
trackBy?: (dataNode: T) => K;
filterModel: SelectionModel;
filterValue: BehaviorSubject;
getLevel: (dataNode: T) => number;
isExpandable: (dataNode: T) => boolean;
getChildren: (dataNode: T) => Observable;
abstract getDescendants(dataNode: T): T[];
abstract expandAll(): void;
toggle(dataNode: T): void;
expand(dataNode: T): void;
collapse(dataNode: T): void;
isExpanded(dataNode: T): boolean;
toggleDescendants(dataNode: T): void;
collapseAll(): void;
expandDescendants(dataNode: T): void;
collapseDescendants(dataNode: T): void;
protected expansionKey(dataNode: T): K;
}
```
- `expansionModel`: `SelectionModel` — A selection model with multi-selection to track expansion status: it holds the key of every expanded node.
- `trackBy?`: `(dataNode: T) => K` — Gives the key a data node is expanded by. Without it the node object is its own key, so a node
rebuilt as a new object — as a flattener does whenever its data changes — comes back collapsed.
Set it before anything is expanded: keys stored under another function no longer match.
- `getLevel`: `(dataNode: T) => number` — Get depth of a given data node, return the level number. This is for flat tree node.
- `isExpandable`: `(dataNode: T) => boolean` — Whether the data node is expandable. Returns true if expandable.
This is for flat tree node.
- `getChildren`: `(dataNode: T) => Observable` — Gets a stream that emits whenever the given data node's children change.
- `getDescendants()`: `T[]` — Gets a list of descendent data nodes of a subtree rooted at given data node recursively.
- `expandAll()`: `void` — Expands all data nodes in the tree.
- `toggle()`: `void` — Toggles one single data node's expanded/collapsed state.
- `expand()`: `void` — Expands one single data node.
- `collapse()`: `void` — Collapses one single data node.
- `isExpanded()`: `boolean` — Whether a given data node is expanded or not. Returns true if the data node is expanded.
- `toggleDescendants()`: `void` — Toggles a subtree rooted at `node` recursively.
- `collapseAll()`: `void` — Collapse all dataNodes in the tree.
- `expandDescendants()`: `void` — Expands a subtree rooted at given data node recursively.
- `collapseDescendants()`: `void` — Collapses a subtree rooted at given data node recursively.
- `expansionKey()`: `K` — The key `expansionModel` holds for a data node.
#### FilterByValues (class)
```ts
class FilterByValues implements FlatTreeControlFilter {
result: T[];
setValues: (values: string[]) => void;
constructor(control: FlatTreeControl);
handle(_: any, prevFilter?: FlatTreeControlFilter): T[];
getValues(): string[];
}
```
#### FlatTreeControl (class)
Flat tree control. Able to expand/collapse a subtree recursively for flattened tree.
```ts
class FlatTreeControl extends BaseTreeControl {
expandedItemsBeforeFiltration: K[];
getLevel: (dataNode: T) => number;
isExpandable: (dataNode: T) => boolean;
getValue: (dataNode: T) => any;
getViewValue: (dataNode: T) => string;
compareValues: (firstValue: any, secondValue: any) => boolean;
compareViewValues: (firstViewValue: any, secondViewValue: any) => boolean;
isDisabled: (dataNode: T) => boolean;
dataNodes: T[];
expansionModel: SelectionModel;
trackBy?: (dataNode: T) => K;
filterModel: SelectionModel;
filterValue: BehaviorSubject;
getChildren: (dataNode: T) => Observable;
constructor(
getLevel: (dataNode: T) => number,
isExpandable: (dataNode: T) => boolean,
getValue: (dataNode: T) => any,
getViewValue: (dataNode: T) => string,
compareValues?: (firstValue: any, secondValue: any) => boolean,
compareViewValues?: (firstViewValue: any, secondViewValue: any) => boolean,
isDisabled?: (dataNode: T) => boolean,
options?: KbqTreeControlOptions
);
getFilters(): FlatTreeControlFilter[];
setFilters(...filters: FlatTreeControlFilter[]): void;
getDescendants(dataNode: T): T[];
expandAll(): void;
getParents(node: T, result?: T[]): T[];
hasValue(value: string): T | undefined;
filterNodes(value?: string | null): void;
toggle(dataNode: T): void;
expand(dataNode: T): void;
collapse(dataNode: T): void;
isExpanded(dataNode: T): boolean;
toggleDescendants(dataNode: T): void;
collapseAll(): void;
expandDescendants(dataNode: T): void;
collapseDescendants(dataNode: T): void;
protected expansionKey(dataNode: T): K;
}
```
- `getValue`: `(dataNode: T) => any` — getValue will be used to determine if the tree contains value or not. Used in method hasValue
- `getViewValue`: `(dataNode: T) => string` — getViewValue will be used for filter nodes. Returned value will be first argument in filterNodesFunction
- `compareValues`: `(firstValue: any, secondValue: any) => boolean` — compareValues will be used to comparing values.
- `compareViewValues`: `(firstViewValue: any, secondViewValue: any) => boolean` — compareValues will be used to comparing values.
- `isDisabled`: `(dataNode: T) => boolean` — isDisabled will be used to determine if the node is disabled.
- `expansionModel`: `SelectionModel` — A selection model with multi-selection to track expansion status: it holds the key of every expanded node.
- `trackBy?`: `(dataNode: T) => K` — Gives the key a data node is expanded by. Without it the node object is its own key, so a node
rebuilt as a new object — as a flattener does whenever its data changes — comes back collapsed.
Set it before anything is expanded: keys stored under another function no longer match.
- `getChildren`: `(dataNode: T) => Observable` — Gets a stream that emits whenever the given data node's children change.
- `constructor()` — Construct with flat tree data node functions getLevel, isExpandable, getValue and getViewValue.
- `getValue`: `(dataNode: T) => any` — getValue will be used to determine if the tree contains value or not. Used in method hasValue
- `getViewValue`: `(dataNode: T) => string` — getViewValue will be used for filter nodes. Returned value will be first argument in filterNodesFunction
- `compareValues`: `(firstValue: any, secondValue: any) => boolean` — compareValues will be used to comparing values.
- `compareViewValues`: `(firstViewValue: any, secondViewValue: any) => boolean` — compareValues will be used to comparing values.
- `isDisabled`: `(dataNode: T) => boolean` — isDisabled will be used to determine if the node is disabled.
- `options`: `KbqTreeControlOptions | undefined` — Further options: the `trackBy` the nodes are expanded by.
- `getDescendants()`: `T[]` — Gets a list of the data node's subtree of descendent data nodes.
To make this working, the `dataNodes` of the TreeControl must be flattened tree nodes
with correct levels.
- `expandAll()`: `void` — Expands all data nodes in the tree.
To make this working, the `dataNodes` variable of the TreeControl must be set to all flattened
data nodes of the tree.
- `getParents()`: `T[]` — Ancestors of a data node, outermost first.
Derived from `dataNodes` rather than from a `parent` back-reference: the flattened nodes are in
depth-first order, so scanning backwards from the node, the first node of a smaller level is its
parent, and repeating with that level yields the whole chain. A data node whose shape carries no
`parent` therefore resolves just as well as one that does.
- `result`: `T[]` — Collector the ancestors are prepended to. Provided so callers can accumulate into
an existing array; a fresh one is used when omitted.
- `toggle()`: `void` — Toggles one single data node's expanded/collapsed state.
- `expand()`: `void` — Expands one single data node.
- `collapse()`: `void` — Collapses one single data node.
- `isExpanded()`: `boolean` — Whether a given data node is expanded or not. Returns true if the data node is expanded.
- `toggleDescendants()`: `void` — Toggles a subtree rooted at `node` recursively.
- `collapseAll()`: `void` — Collapse all dataNodes in the tree.
- `expandDescendants()`: `void` — Expands a subtree rooted at given data node recursively.
- `collapseDescendants()`: `void` — Collapses a subtree rooted at given data node recursively.
- `expansionKey()`: `K` — The key `expansionModel` holds for a data node.
#### KbqTreeCopyEvent (class)
Event class that occurs when copying an item from the KbqTreeSelection.
Used to pass data about the copied item and copy context.
```ts
class KbqTreeCopyEvent {
source: KbqTreeSelection;
option: T;
event?: KeyboardEvent;
constructor(
source: KbqTreeSelection,
option: T,
event?: KeyboardEvent
);
}
```
#### KbqTreeFlatDataSource (class)
Data source for flat tree.
The data source need to handle expansion/collapsion of the tree node and change the data feed
to `KbqTree`.
The nested tree nodes of type `T` are flattened through `KbqTreeFlattener`, and converted
to type `F` for `KbqTree` to consume.
```ts
class KbqTreeFlatDataSource extends DataSource {
flattenedData: BehaviorSubject;
expandedData: BehaviorSubject;
filteredData: BehaviorSubject;
data: T[];
constructor(
treeControl: FlatTreeControl,
treeFlattener: KbqTreeFlattener,
initialData?: T[]
);
connect(collectionViewer: CollectionViewer): Observable;
filterHandler(): F[];
expansionHandler(_change: SelectionChange): F[];
disconnect(): void;
}
```
#### KbqTreeFlattener (class)
Tree flattener to convert a normal type of node to node with children & level information.
Transform nested nodes of type `T` to flattened nodes of type `F`.
For example, the input data of type `T` is nested, and contains its children data:
```ts
SomeNode: {
key: 'Fruits',
children: [
NodeOne: {
key: 'Apple'
},
NodeTwo: {
key: 'Pear'
}
]
}
```
After flattener flatten the tree, the structure will become
```ts
SomeNode: {
key: 'Fruits',
expandable: true,
level: 1
},
NodeOne: {
key: 'Apple',
expandable: false,
level: 2
},
NodeTwo: {
key: 'Pear',
expandable: false,
level: 2
}
```
and the output flattened type is `F` with additional information.
```ts
class KbqTreeFlattener {
transformFunction: (node: T, level: number, parent: F | null) => F;
getLevel: (node: F) => number;
isExpandable: (node: F) => boolean;
getChildren: (node: T) => T[] | Observable | null | undefined;
constructor(
transformFunction: (node: T, level: number, parent: F | null) => F,
getLevel: (node: F) => number,
isExpandable: (node: F) => boolean,
getChildren: (node: T) => T[] | Observable | null | undefined
);
flattenNodes(structuredData: T[]): F[];
expandFlattenedNodes(
nodes: F[],
treeControl: Pick, 'isExpanded'>
): F[];
}
```
- `flattenNodes()`: `F[]` — Flatten a list of node type T to flattened version of node F.
Please note that type T may be nested, and the length of `structuredData` may be different
from that of returned list `F[]`.
- `expandFlattenedNodes()`: `F[]` — Expand flattened node with current expansion status.
The returned list may have different length.
Reads only `isExpanded` of the tree control, so it takes a control of any key type.
#### KbqTreeNavigationChange (class)
```ts
class KbqTreeNavigationChange {
source: KbqTreeSelection;
option: T;
constructor(source: KbqTreeSelection, option: T);
}
```
#### KbqTreeNestedDataSource (class)
Data source for nested tree.
The data source for nested tree doesn't have to consider node flattener, or the way to expand
or collapse. The expansion/collapsion will be handled by TreeControl and each non-leaf node.
```ts
class KbqTreeNestedDataSource extends DataSource {
data: T[];
connect(collectionViewer: CollectionViewer): Observable;
disconnect(): void;
}
```
#### KbqTreeNodeOutletContext (class)
Context provided to the tree node component.
```ts
class KbqTreeNodeOutletContext {
$implicit: T;
level: number;
index?: number;
count?: number;
constructor(data: T);
}
```
- `$implicit`: `T` — Data for the node.
- `level`: `number` — Depth of the node.
- `index?`: `number` — Index location of the node.
- `count?`: `number` — Length of the number of total dataNodes.
#### KbqTreeOptionChange (class)
Represents a change event for a tree option.
```ts
class KbqTreeOptionChange {
source: KbqTreeOption;
constructor(source: KbqTreeOption);
}
```
- `source`: `KbqTreeOption` — The tree option that has been modified or selected.
- `constructor()`
- `source`: `KbqTreeOption` — The tree option that has been modified or selected.
#### KbqTreeSelectAllEvent (class)
```ts
class KbqTreeSelectAllEvent {
source: KbqTreeSelection;
options: T[];
constructor(source: KbqTreeSelection, options: T[]);
}
```
#### KbqTreeSelectionChange (class)
```ts
class KbqTreeSelectionChange {
source: KbqTreeSelection;
option: T;
options?: T[];
constructor(
source: KbqTreeSelection,
option: T,
options?: T[]
);
}
```
#### NestedTreeControl (class)
Nested tree control. Able to expand/collapse a subtree recursively for NestedNode type.
```ts
class NestedTreeControl extends BaseTreeControl {
getChildren: (dataNode: T) => Observable;
dataNodes: T[];
expansionModel: SelectionModel;
trackBy?: (dataNode: T) => K;
filterModel: SelectionModel;
filterValue: BehaviorSubject;
getLevel: (dataNode: T) => number;
isExpandable: (dataNode: T) => boolean;
constructor(
getChildren: (dataNode: T) => Observable,
options?: KbqTreeControlOptions
);
expandAll(): void;
getDescendants(dataNode: T): T[];
toggle(dataNode: T): void;
expand(dataNode: T): void;
collapse(dataNode: T): void;
isExpanded(dataNode: T): boolean;
toggleDescendants(dataNode: T): void;
collapseAll(): void;
expandDescendants(dataNode: T): void;
collapseDescendants(dataNode: T): void;
protected expansionKey(dataNode: T): K;
}
```
- `getChildren`: `(dataNode: T) => Observable` — Must emit **synchronously** (e.g. `of(children)` or a `BehaviorSubject`).
`getDescendants` walks the tree with `take(1)` and returns as soon as the recursion unwinds, so
an asynchronous source yields an incomplete — usually empty — descendant list.
- `expansionModel`: `SelectionModel` — A selection model with multi-selection to track expansion status: it holds the key of every expanded node.
- `trackBy?`: `(dataNode: T) => K` — Gives the key a data node is expanded by. Without it the node object is its own key, so a node
rebuilt as a new object — as a flattener does whenever its data changes — comes back collapsed.
Set it before anything is expanded: keys stored under another function no longer match.
- `getLevel`: `(dataNode: T) => number` — Get depth of a given data node, return the level number. This is for flat tree node.
- `isExpandable`: `(dataNode: T) => boolean` — Whether the data node is expandable. Returns true if expandable.
This is for flat tree node.
- `constructor()` — Construct with nested tree function getChildren.
- `getChildren`: `(dataNode: T) => Observable` — Must emit **synchronously** (e.g. `of(children)` or a `BehaviorSubject`).
`getDescendants` walks the tree with `take(1)` and returns as soon as the recursion unwinds, so
an asynchronous source yields an incomplete — usually empty — descendant list.
- `expandAll()`: `void` — Expands all dataNodes in the tree.
To make this working, the `dataNodes` variable of the TreeControl must be set to all root level
data nodes of the tree.
- `getDescendants()`: `T[]` — Gets a list of descendant dataNodes of a subtree rooted at given data node recursively.
- `toggle()`: `void` — Toggles one single data node's expanded/collapsed state.
- `expand()`: `void` — Expands one single data node.
- `collapse()`: `void` — Collapses one single data node.
- `isExpanded()`: `boolean` — Whether a given data node is expanded or not. Returns true if the data node is expanded.
- `toggleDescendants()`: `void` — Toggles a subtree rooted at `node` recursively.
- `collapseAll()`: `void` — Collapse all dataNodes in the tree.
- `expandDescendants()`: `void` — Expands a subtree rooted at given data node recursively.
- `collapseDescendants()`: `void` — Collapses a subtree rooted at given data node recursively.
- `expansionKey()`: `K` — The key `expansionModel` holds for a data node.
### Functions
#### defaultCompareValues (function)
```ts
function defaultCompareValues(
firstValue: string,
secondValue: string
): boolean;
```
#### defaultCompareViewValues (function)
```ts
function defaultCompareViewValues(
firstViewValue: string,
secondViewValue: string
): boolean;
```
### Types
#### FlatTreeControlFilter (interface)
```ts
interface FlatTreeControlFilter {
result: T[];
handle(
value: string | null,
prevFilter?: FlatTreeControlFilter | null
): T[];
}
```
#### KbqTreeControlOptions (interface)
Options of `FlatTreeControl` and `NestedTreeControl`.
```ts
interface KbqTreeControlOptions {
trackBy?: (dataNode: T) => K;
}
```
- `trackBy?`: `(dataNode: T) => K` — Initial value of the control's `trackBy`.
#### KbqTreeOptionEvent (interface)
```ts
interface KbqTreeOptionEvent {
option: KbqTreeOption;
}
```
#### KbqTreeOptionParent (interface)
The part of the tree an option talks to.
Declared as an interface rather than as `KbqTreeSelection` so the token stays free of a circular
import, and so anything embedding options only has to provide these members.
```ts
interface KbqTreeOptionParent {
disabled: boolean;
multiple: boolean;
showCheckbox: boolean;
inSelect: boolean;
optionShouldHoldFocusOnBlur: boolean;
selectAllState: KbqPseudoCheckboxState;
treeControl: FlatTreeControl;
selectionModel: SelectionModel;
unorderedOptions: QueryList>;
setSelectedOptionsByClick(
option: KbqTreeOption,
shiftKey: boolean,
ctrlKey: boolean
): void;
reportOptionFocus?(event: KbqTreeOptionEvent): void;
reportOptionBlur?(event: KbqTreeOptionEvent): void;
}
```
- `disabled`: `boolean` — Whether the whole tree is disabled.
- `multiple`: `boolean` — Whether more than one option can be selected at a time.
- `showCheckbox`: `boolean` — Whether the options render a checkbox.
- `inSelect`: `boolean` — Whether the tree is rendered inside a select panel, which makes hovering an option focus it.
- `optionShouldHoldFocusOnBlur`: `boolean` — Whether an option keeps focus while the tree loses it, as a select with a search field needs.
- `selectAllState`: `KbqPseudoCheckboxState` — State of the tree-level "select all" checkbox.
- `reportOptionFocus?()`: `void` — Called when an option takes focus.
- `reportOptionBlur?()`: `void` — Called when an option loses focus.
#### KbqTreeState (type)
The persisted state of a tree — the values of the nodes that were expanded.
```ts
type KbqTreeState = string[];
```
#### TreeControl (interface)
Tree control interface. User can implement TreeControl to expand/collapse dataNodes in the tree.
The Tree will use this TreeControl to expand/collapse a node.
User can also use it outside the `` to control the expansion status of the tree.
```ts
interface TreeControl {
dataNodes: T[];
expansionModel: SelectionModel;
filterModel: SelectionModel;
trackBy?: (dataNode: T) => K;
filterValue: BehaviorSubject;
getLevel(dataNode: T): number;
isExpandable(dataNode: T): boolean;
getChildren(dataNode: T): Observable;
isExpanded(dataNode: T): boolean;
getDescendants(dataNode: T): any[];
toggle(dataNode: T): void;
expand(dataNode: T): void;
collapse(dataNode: T): void;
expandAll(): void;
collapseAll(): void;
toggleDescendants(dataNode: T): void;
expandDescendants(dataNode: T): void;
collapseDescendants(dataNode: T): void;
}
```
- `dataNodes`: `T[]` — The saved tree nodes data for `expandAll` action.
- `expansionModel`: `SelectionModel` — The expansion model: the keys of the expanded data nodes, which are the nodes themselves by default.
- `trackBy?`: `(dataNode: T) => K` — Gives the key a data node is expanded by. Without it the node object is its own key.
- `getLevel()`: `number` — Get depth of a given data node, return the level number. This is for flat tree node.
- `isExpandable()`: `boolean` — Whether the data node is expandable. Returns true if expandable.
This is for flat tree node.
- `getChildren()`: `Observable` — Gets a stream that emits whenever the given data node's children change.
- `isExpanded()`: `boolean` — Whether the data node is expanded or collapsed. Return true if it's expanded.
- `getDescendants()`: `any[]` — Get all descendants of a data node
- `toggle()`: `void` — Expand or collapse data node
- `expand()`: `void` — Expand one data node
- `collapse()`: `void` — Collapse one data node
- `expandAll()`: `void` — Expand all the dataNodes in the tree
- `collapseAll()`: `void` — Collapse all the dataNodes in the tree
- `toggleDescendants()`: `void` — Toggle a data node by expand/collapse it and all its descendants
- `expandDescendants()`: `void` — Expand a data node and all its descendants
- `collapseDescendants()`: `void` — Collapse a data node and all its descendants
### Constants
#### KBQ_SELECTION_TREE_VALUE_ACCESSOR (const)
```ts
const KBQ_SELECTION_TREE_VALUE_ACCESSOR: Provider;
```
#### KBQ_TREE_OPTION_PARENT_COMPONENT (const)
Injection token used to provide the parent component to options.
```ts
const KBQ_TREE_OPTION_PARENT_COMPONENT: InjectionToken;
```
#### kbqTreeSelectAllValue (const)
```ts
const kbqTreeSelectAllValue: string;
```
## Examples
### Search
The search results include matches and all of their parents:
- the tree collapses down to the matches and the path to them: the found items and the chain of their parents are visible
- the path to a match is expanded, while the items nested inside it are hidden;
- matched branches can be expanded and collapsed to view their contents;
- the matched fragment is highlighted.
**Example: Tree custom filtering** (`tree-custom-filtering`)
```ts tree-custom-filtering-example.ts
import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { FormsModule } from '@angular/forms';
import { KbqHighlightModule } from '@koobiq/components/core';
import { KbqInputModule } from '@koobiq/components/input';
import {
FlatTreeControl,
FlatTreeControlFilter,
KbqTreeFlatDataSource,
KbqTreeFlattener,
KbqTreeModule
} from '@koobiq/components/tree';
export class FileNode {
children: FileNode[];
name: string;
type: any;
}
/** Flat node with expandable and level information */
export class FileFlatNode {
name: string;
type: any;
level: number;
expandable: boolean;
parent: any;
}
/**
* Build the file structure tree. The `value` is the Json object, or a sub-tree of a Json object.
* The return value is the list of `FileNode`.
*/
export function buildFileTree(value: any, level: number): FileNode[] {
const data: any[] = [];
for (const k of Object.keys(value)) {
const v = value[k];
const node = new FileNode();
node.name = `${k}`;
if (v === null || v === undefined) {
// no action
} else if (typeof v === 'object') {
node.children = buildFileTree(v, level + 1);
} else {
node.type = v;
}
data.push(node);
}
return data;
}
export const DATA_OBJECT = {
docs: 'app',
src: {
cdk: {
a11ly: {
'aria describer': {
'aria-describer': 'ts',
'aria-describer.spec': 'ts',
'aria-reference': 'ts',
'aria-reference.spec': 'ts'
},
'focus monitor': {
'focus-monitor': 'ts',
'focus-monitor.spec': 'ts'
}
}
},
documentation: {
source: '',
tools: ''
},
mosaic: {
autocomplete: '',
button: '',
'button-toggle': '',
index: 'ts',
package: 'json',
version: 'ts'
},
'mosaic-dev': {
alert: '',
badge: ''
},
'mosaic-examples': '',
'mosaic-moment-adapter': '',
README: 'md',
'tsconfig.build': 'json'
},
scripts: {
deploy: {
'cleanup-preview': 'ts',
'publish-artifacts': 'sh',
'publish-docs': 'sh',
'publish-docs-preview': 'ts'
},
'tsconfig.deploy': 'json'
},
tests: ''
};
export class CustomTreeControlFilter implements FlatTreeControlFilter {
result: T[];
constructor(private control: FlatTreeControl) {}
handle(value: string | null): T[] {
if (!value) {
this.result = [];
return this.result;
}
const result: Set = new Set();
const foundedNodes = this.control.dataNodes.filter((node: any) => {
return this.control.compareViewValues(this.control.getViewValue(node), value);
});
foundedNodes.forEach((filteredNode) => {
this.control.getParents(filteredNode, []).forEach((node) => result.add(node));
result.add(filteredNode);
});
this.result = Array.from(result);
return this.result;
}
}
@Component({
selector: 'tree-custom-filtering-example',
imports: [KbqInputModule, FormsModule, KbqTreeModule, KbqHighlightModule],
template: `