@scion/components 22.6.0 → 22.7.0

package/types/scion-components-tree.d.ts

@@ -0,0 +1,559 @@
+import { MaybeSignal, SciComponentDescriptor, SciTemplateDescriptor } from '@scion/components/common';
+import * as _angular_core from '@angular/core';
+import { Signal, WritableSignal, Injector } from '@angular/core';
+import { SciTableDatasourceProvider, SciTreeTableNode, SciTableCellContext, SciTableRowActionFactoryFn, SciTableEvent, ɵSciTable as _SciTable } from '@scion/components/table';
+import { MaybeAsync, MaybeArray } from '@scion/toolkit/types';
+import { Translatable } from '@scion/components/text';
+
+type SciTreeDatasourceProvider<T, ID = never> = SciTableDatasourceProvider<T, ID>;
+type SciTreeNode<T> = SciTreeTableNode<T>;
+/**
+ * Provides an in-memory datasource for {@link SciTree} with built-in filtering.
+ *
+ * A datasource provides data to {@link SciTree}, passing each item to {@link SciTreeDescriptor.label} for display.
+ *
+ * This datasource requires all data to be loaded upfront. It invokes the passed child selector function for each item
+ * to construct the tree. Data is filtered in memory.
+ *
+ * If using custom labels, a {@link SciTreeDescriptor.matcher} is required to support {@link SciTree.filter}.
+ *
+ * For large datasets requiring pagination or server-side filtering and sorting, prefer implementing a custom datasource using {@link ɵprovideTreeDatasource}.
+ *
+ * IMPORTANT: Custom datasource support is experimental and currently exposed only as `ɵprovideTableDatasource`. The API and behavior may change in any version without notice.
+ *
+ * @example - Usage
+ * ```ts
+ * import {tree, provideTreeDatasource} from '@scion/components/tree';
+ * import {httpResource} from '@angular/common/http';
+ *
+ * const files = httpResource<File[]>(() => '/api/files', {defaultValue: []});
+ *
+ * const fileTree = tree({
+ *   label: file => file.name,
+ *   datasource: provideTreeDatasource(files.value, file => file.children),
+ * });
+ * ```
+ *
+ * @param root - Provides the root items to display in the tree.
+ * @param children - Function returning an item's children, or an empty array if the item has no children or is a leaf.
+ *                   Called eagerly for each item when initializing the tree, inside a reactive context that re-evaluates when tracked signals change.
+ *
+ * @see SciTreeDescriptor.datasource
+ */
+declare function provideTreeDatasource<T>(root: Signal<T[]>, children: (item: T) => T[]): SciTreeDatasourceProvider<T>;
+/**
+ * Provides a datasource for {@link SciTree}.
+ *
+ * A datasource provides data to {@link SciTree}, passing each item to {@link SciTreeDescriptor.label} for display.
+ * Filtering and sorting must be implemented by the datasource based on the provided filter and sort criteria.
+ *
+ * A tree is a hierarchical structure of nodes, represented by the datasource as a flat list of tree nodes.
+ * Each node references an item and its parent by ID, without containing the item itself. The tree requests items on demand when scrolled into view,
+ * allowing large datasets to be displayed without loading all items upfront. If the entire dataset is available locally, use {@link provideTreeDatasource}.
+ *
+ * {@link SciTree} constructs the tree from the returned nodes, starting with root nodes (nodes without a parent) and appending child nodes in array order.
+ * Child nodes can appear anywhere in the nodes list; they do not need to follow their parent.
+ *
+ * @example - Usage
+ * ```ts
+ * import {tree, provideTreeDatasource} from '@scion/components/tree';
+ * import {SciTreeNode} from '@scion/components/table';
+ * import {httpResource} from '@angular/common/http';
+ * import {toObservable} from '@angular/core/rxjs-interop';
+ *
+ * const files = httpResource<File[]>(() => '/api/files', {defaultValue: []});
+ *
+ * const fileTree = tree<File, string>({
+ *   label: file => file.name,
+ *   datasource: provideTreeDatasource({
+ *     getTreeNodes: query => toObservable(httpResource<SciTreeNode<string>[]>(() => `/api/files?filter=${query.filter}`, {defaultValue: []}).value),
+ *     getItems: guids => toObservable(httpResource<File[]>(() => ({url: `/api/files`, params: {guids}}), {defaultValue: []}).value),
+ *   }),
+ *   trackBy: file => file.guid,
+ * });
+ * ```
+ *
+ * @param datasource - Specifies the datasource.
+ *
+ * @docs-private Not public API. For internal use only.
+ * @experimental since 22.7.0; API and behavior may change in any version without notice.
+ */
+declare function ɵprovideTreeDatasource<T, ID>(datasource: SciTreeDatasource<T, ID>): SciTableDatasourceProvider<T, ID>;
+interface SciTreeDatasourceQuery {
+    filter?: string;
+}
+/**
+ * Represents a datasource for {@link SciTree}.
+ *
+ * A datasource provides data to {@link SciTree}, passing each item to {@link SciTreeDescriptor.label} for display.
+ * Filtering and sorting must be implemented by the datasource based on the provided filter and sort criteria.
+ *
+ * A tree is a hierarchical structure of nodes, represented by the datasource as a flat list of tree nodes.
+ * Each node references an item and its parent by ID, without containing the item itself. The tree requests items on demand when scrolled into view,
+ * allowing large datasets to be displayed without loading all items upfront. If the entire dataset is available locally, use {@link provideTreeDatasource}.
+ *
+ * {@link SciTree} constructs the tree from the returned nodes, starting with root nodes (nodes without a parent) and appending child nodes in array order.
+ * Child nodes can appear anywhere in the nodes list; they do not need to follow their parent.
+ */
+interface SciTreeDatasource<T, ID> {
+    /**
+     * Returns a flat list of tree nodes matching the given filter and sort criteria.
+     *
+     * A tree node references an item and its parent by ID, without containing the item itself.
+     *
+     * Child nodes can appear anywhere in the list; they do not need to follow their parent. Siblings are added in the order they appear in the list.
+     *
+     * If a filter is set, return only the directly matching nodes (leaf or intermediate). Do not include their ancestors.
+     */
+    getTreeNodes(query: SciTreeDatasourceQuery): MaybeAsync<SciTreeNode<ID>[]>;
+    /**
+     * Resolves items for the specified IDs. Called as nodes scroll into view.
+     */
+    getItems(ids: ID[]): MaybeAsync<T[]>;
+}
+
+/**
+ * Represents a descriptor to configure {@link SciTreeComponent}.
+ *
+ * Defines the datasource, the display of node labels, and other display options. Requires a datasource and node label function.
+ */
+interface SciTreeDescriptor<T, ID = T> {
+    /**
+     * Specifies the datasource to provide data to {@link SciTree}.
+     *
+     * Create a datasource using the {@link provideTreeDatasource} function and pass a signal containing the root items
+     * and a function that returns the children of a given item.
+     *
+     * @example - Usage
+     * ```ts
+     * import {tree, provideTreeDatasource} from '@scion/components/tree';
+     * import {httpResource} from '@angular/common/http';
+     *
+     * const files = httpResource<File[]>(() => '/api/files', {defaultValue: []});
+     *
+     * const fileTree = tree({
+     *   label: file => file.name,
+     *   datasource: provideTreeDatasource(files.value, file => file.children),
+     * });
+     * ```
+     *
+     * @see provideTreeDatasource
+     */
+    datasource: SciTreeDatasourceProvider<T, ID>;
+    /**
+     * Specifies the text or custom content to display for a tree node.
+     *
+     * Can be text or a translation key, or a {@link SciTreeNodeComponentDescriptor} or {@link SciTreeNodeTemplateDescriptor}.
+     *
+     * A translation key starts with the percent symbol (`%`) and may include parameters in matrix notation for text interpolation.
+     * SCION uses text providers to resolve translation keys. A text provider can be registered using {@link provideTextProvider}.
+     *
+     * The function:
+     * - Can call `inject` to get required dependencies.
+     * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
+     */
+    label: ((item: T) => MaybeSignal<Translatable | undefined>) | SciTreeNodeComponentDescriptor<T> | SciTreeNodeTemplateDescriptor<T>;
+    /**
+     * Specifies a custom matcher for {@link SciTree.filter}.
+     *
+     * If using the built-in in-memory datasource, defaults to matching node labels. Component and template labels require a custom matcher.
+     * For all other datasources, filtering is delegated to the datasource and this matcher is not used.
+     */
+    matcher?: (text: string, context: SciTreeNodeContext<T>) => boolean;
+    /**
+     * Controls whether the user can select a single node (`single`), multiple nodes (`multi`), or no nodes (`false`). Defaults to `multi`.
+     *
+     * Does not affect selection via {@link SciTree.select}.
+     */
+    selectable?: 'single' | 'multi' | false;
+    /**
+     * Configures actions to show when hovering over a node.
+     *
+     * @example
+     * ```ts
+     * import {tree} from '@scion/components/tree';
+     *
+     * tree({
+     *   datasource: provideTreeDatasource(data, item => item.children),
+     *   label: item => item.name,
+     *   rowActions: (toolbar, item) => toolbar.addToolbarButton({
+     *     icon: 'delete',
+     *     onSelect: () => ...,
+     *   }),
+     * });
+     * ```
+     *
+     * The function:
+     * - Is called per item with a {@link SciToolbarFactory} to contribute actions.
+     * - Runs in a reactive context and re-evaluates when tracked signals change.
+     * - Can call `inject` to get required dependencies.
+     */
+    nodeActions?: SciTreeNodeActionFactoryFn<T>;
+    /**
+     * Configures node bindings for tree nodes.
+     *
+     * Node bindings enable associating metadata and icons with a node. Metadata includes CSS shadow parts, CSS classes, and HTML attributes.
+     *
+     * @example
+     * ```ts
+     * import {tree} from '@scion/components/tree';
+     *
+     * tree({
+     *   datasource: provideTreeDatasource(data, item => item.children),
+     *   label: item => item.name,
+     *   nodeBindings: (bindings, item, index) => bindings
+     *     .addIconBinding(item.type === 'file' ? 'format_align_left' : 'folder')
+     *     .addPartBinding(item.active ? 'node:active' : undefined),
+     *     .addAttributeBinding('data-id', item.id)
+     *     .addClassBinding(item.inactive ? 'inactive' : undefined),
+     * });
+     * ```
+     *
+     * Part attribute bindings make a node stylable by associating its cells with one or more HTML part attributes that can be referenced in CSS using the `::part()` CSS pseudo-element selector.
+     *
+     * ```scss
+     * sci-tree::part(node\:active node\:not\:selected) {
+     *   background-color: lightgray;
+     * }
+     * ```
+     *
+     * The function:
+     * - Is called per item with a {@link SciTreeNodeBindingFactory} to register bindings.
+     * - Runs in a reactive context and re-evaluates when tracked signals change.
+     * - Can call `inject` to get required dependencies.
+     *
+     * @param bindings - Factory providing methods to register node bindings.
+     * @param item - Item associated with the node.
+     * @param index - Index of the node, zero-based.
+     */
+    nodeBindings?: SciTreeNodeBindingFactoryFn<T>;
+    /**
+     * Specifies the number of items to render before and after the viewport. Defaults to 10.
+     */
+    bufferSize?: number;
+    /**
+     * Specifies the number of items to load per page. Defaults to 50.
+     */
+    pageSize?: number;
+    /**
+     * Computes a unique and stable identity for items in the tree.
+     *
+     * Defaults to the item object reference. Used to identify items when loading data from the datasource and when tracking tree selection.
+     */
+    trackBy?: (item: T) => ID;
+    /**
+     * Specifies an injector used to create the tree. Defaults to the current injection context.
+     * The tree is disposed when the passed injector is destroyed.
+     */
+    injector?: Injector;
+}
+/**
+ * Represents a table for {@link SciTreeComponent}.
+ *
+ * Can be constructed using the {@link tree} function.
+ * Use to bind to `<sci-tree>` and interact with the tree.
+ *
+ * @see tree
+ * @see SciTreeComponent
+ */
+interface SciTree<ID = unknown> {
+    /**
+     * Provides the active item, if any.
+     *
+     * The active item may differ from the selected items and is used as the target for keyboard navigation.
+     */
+    readonly activeItem: Signal<ID | undefined>;
+    /**
+     * Provides the selected items.
+     */
+    readonly selectedItems: Signal<Array<ID>>;
+    /**
+     * Controls whether the user can select a single node, multiple nodes, or nothing.
+     *
+     * Initialized from {@link SciTreeDescriptor.selectable}. Defaults to `multi`.
+     */
+    readonly selectable: WritableSignal<'single' | 'multi' | false>;
+    /**
+     * Filters nodes by the specified text.
+     *
+     * Can be used to connect an external filter field to the tree.
+     *
+     * If using the built-in in-memory datasource, matches node labels, or uses the custom matcher, if one is configured in {@link SciTreeDescriptor.matcher}. Component and template labels require a custom matcher.
+     * For all other datasources, filtering is delegated to the datasource.
+     *
+     * @param text - Text to filter by, or `null` to clear the filter.
+     */
+    filter(text: string | null): void;
+    /**
+     * Selects the specified nodes, replacing the current selection.
+     *
+     * Expands parent nodes of the selected nodes.
+     *
+     * @param id - ID or IDs of the nodes to select, or an empty array to clear the selection.
+     */
+    select(id: MaybeArray<ID>): void;
+    /**
+     * Expands all nodes in the tree.
+     */
+    expandAll(): void;
+    /**
+     * Collapses all nodes in the tree.
+     */
+    collapseAll(): void;
+}
+type SciTreeNodeContext<T> = SciTableCellContext<T, string | void>;
+type SciTreeEvent<ID> = SciTableEvent<ID>;
+type SciTreeNodeActionFactoryFn<T> = SciTableRowActionFactoryFn<T>;
+type SciTreeNodeBindingFactoryFn<T> = (node: SciTreeNodeBindingFactory, item: T, index: number) => void;
+interface SciTreeNodeBindingFactory {
+    /**
+     * Binds an icon to the node, displayed in the first column.
+     *
+     * ```ts
+     * import {tree} from '@scion/components/tree';
+     *
+     * tree({
+     *   datasource: data,
+     *   nodeBindings: node => node.addIconBinding('mail'),
+     * });
+     * ```
+     *
+     * SCION uses icon providers to render icons. An icon provider can be registered using {@link provideIconProvider}.
+     *
+     * Defaults to a Material icon provider if the application has not registered an icon provider, interpreting the icon as a Material Icon font ligature.
+     * Refer to https://fonts.google.com/icons for available Material icons and instructions on including the Material icon font.
+     */
+    addIconBinding(icon: string): this;
+    /**
+     * Adds the specified values as part attributes to the node, enabling for custom styling of the node, e.g., based on a condition.
+     *
+     * Example usage:
+     * ```ts
+     * tree({
+     *   datasource: data,
+     *   nodeBindings: (node, item, index) => node
+     *     .addPartBinding(item.active ? 'node:active' : undefined),
+     * });
+     * ```
+     *
+     * ```scss
+     * sci-tree::part(node\:active node\:not\:selected) {
+     *   background-color: green;
+     * }
+     * ```
+     */
+    addPartBinding(name: `node:${string}` | undefined): this;
+    /**
+     * Binds an HTML attribute to the node.
+     *
+     * Useful for end-to-end testing, such as associating a node with an item's primary key.
+     *
+     * ```ts
+     * import {tree} from '@scion/components/tree';
+     *
+     * tree({
+     *   datasource: data,
+     *   nodeBindings: (node, item) => node.addAttributeBinding('data-id', item.id),
+     * });
+     * ```
+     */
+    addAttributeBinding(name: string, value: unknown | undefined): this;
+    /**
+     * Binds a CSS class to the node.
+     */
+    addClassBinding(name: string | undefined): this;
+}
+interface SciTreeNodeComponentDescriptor<T> {
+    component: (item: T) => SciComponentDescriptor;
+    padding?: boolean;
+}
+interface SciTreeNodeTemplateDescriptor<T> {
+    template: (item: T) => SciTemplateDescriptor;
+    padding?: boolean;
+}
+
+/**
+ * Creates a tree for displaying a tree structure in {@link SciTreeComponent}.
+ *
+ * Pass a descriptor to configure the datasource and the display of node labels.
+ *
+ * Use the {@link provideTreeDatasource} function to create a datasource, passing a signal containing the root items and a
+ * function that returns the children of a given item.
+ *
+ * ```ts
+ * import {SciTreeComponent, tree, provideTreeDatasource} from '@scion/components/tree';
+ * import {httpResource} from '@angular/common/http';
+ *
+ * // Load data to display in the tree.
+ * const files = httpResource<File[]>(() => '/api/files', {defaultValue: []});
+ *
+ * // Create the tree and pass data.
+ * const fileTree = tree({
+ *   label: file => file.name,
+ *   datasource: provideTreeDatasource(files.value, file => file.children),
+ * });
+ * ```
+ *
+ * In the HTML, bind the created tree instance to `<sci-tree>`.
+ *
+ * ```html
+ * <sci-tree name="tree:files" [tree]="fileTree"/>
+ * ```
+ *
+ * Callback functions:
+ * - Run in a reactive context and re-evaluate when tracked signals change.
+ * - Can call `inject` to get required dependencies. The injection context is destroyed each time the function is called anew.
+ *
+ * This function:
+ * - Must be called within an injection context, or an explicit {@link Injector} passed.
+ * - Must be called in a non-reactive (non-tracking) context.
+ *
+ * @see SciTreeComponent
+ * @experimental since 22.7.0; API and behavior may change in any version without notice.
+ *
+ * @param descriptor - Configures the tree. Requires a datasource and node label function.
+ * @return Handle to bind to `<sci-tree>` and interact with the tree.
+ */
+declare function tree<T>(descriptor: SciTreeDescriptor<T>): SciTree<T>;
+/**
+ * Creates a tree for displaying a tree structure in {@link SciTreeComponent}.
+ *
+ * Pass a descriptor to configure the datasource and the display of node labels.
+ *
+ * Use the {@link provideTreeDatasource} function to create a datasource, passing a signal containing the root items and a
+ * function that returns the children of a given item.
+ *
+ * ```ts
+ * import {SciTreeComponent, tree, provideTreeDatasource} from '@scion/components/tree';
+ * import {httpResource} from '@angular/common/http';
+ *
+ * // Load data to display in the tree.
+ * const files = httpResource<File[]>(() => '/api/files', {defaultValue: []});
+ *
+ * // Create the tree and pass data.
+ * const fileTree = tree({
+ *   label: file => file.name,
+ *   datasource: provideTreeDatasource(files.value, file => file.children),
+ * });
+ * ```
+ *
+ * In the HTML, bind the created tree instance to `<sci-tree>`.
+ *
+ * ```html
+ * <sci-tree name="tree:files" [tree]="fileTree"/>
+ * ```
+ *
+ * Callback functions:
+ * - Run in a reactive context and re-evaluate when tracked signals change.
+ * - Can call `inject` to get required dependencies. The injection context is destroyed each time the function is called anew.
+ *
+ * This function:
+ * - Must be called within an injection context, or an explicit {@link Injector} passed.
+ * - Must be called in a non-reactive (non-tracking) context.
+ *
+ * @see SciTreeComponent
+ * @experimental since 22.7.0; API and behavior may change in any version without notice.
+ *
+ * @param descriptor - Configures the tree. Requires a datasource and node label function.
+ * @return Handle to bind to `<sci-tree>` and interact with the tree.
+ */
+declare function tree<T, ID = T>(descriptor: SciTreeDescriptor<T, ID> & {
+    trackBy: (item: T) => ID;
+}): SciTree<ID>;
+
+declare class ɵSciTree<T = unknown, ID = T> implements SciTree<ID> {
+    readonly activeItem: Signal<ID | undefined>;
+    readonly selectedItems: Signal<Array<ID>>;
+    readonly selectable: WritableSignal<'single' | 'multi' | false>;
+    private readonly _table;
+    constructor(descriptor: SciTreeDescriptor<T, ID>);
+    get table(): _SciTable<T, ID>;
+    filter(text: string | null): void;
+    select(ids: MaybeArray<ID>): void;
+    expandAll(): void;
+    collapseAll(): void;
+    dispose(): void;
+}
+
+/**
+ * Provides a tree to display a tree structure.
+ *
+ * ### Usage
+ *
+ * Create a tree using the `tree()` function, passing a descriptor to configure the datasource and the display of node labels.
+ *
+ * Use the {@link provideTreeDatasource} function to create a datasource, passing a signal containing the root items and a
+ * function that returns the children of a given item.
+ *
+ * ```ts
+ * import {SciTreeComponent, tree, provideTreeDatasource} from '@scion/components/tree';
+ * import {httpResource} from '@angular/common/http';
+ *
+ * // Load data to display in the tree.
+ * const files = httpResource<File[]>(() => '/api/files', {defaultValue: []});
+ *
+ * // Create the tree and pass data.
+ * const fileTree = tree({
+ *   label: file => file.name,
+ *   datasource: provideTreeDatasource(files.value, file => file.children),
+ * });
+ * ```
+ *
+ * In the HTML, bind the created tree instance to `<sci-tree>` and assign it a name.
+ * The name must start with the `tree:` prefix and is used to store user settings.
+ *
+ * ```html
+ * <sci-tree name="tree:files" [tree]="fileTree"/>
+ * ```
+ *
+ * ### Fixed Node Height
+ *
+ * All nodes in the tree must have equal height, which is `2em` by default. The height can be changed per tree using the CSS variable `--sci-tree-node-height`.
+ *
+ * ```scss
+ * sci-tree {
+ *   --sci-tree-node-height: 30px;
+ * }
+ * ```
+ *
+ * ### Styling
+ *
+ * The appearance of the tree can be customized using the following CSS variables, either globally in the `:root` or at the tree level.
+ *
+ * - `--sci-tree-node-height`
+ * - `--sci-tree-node-indent`
+ * - `--sci-tree-node-background-color-hover`
+ * - `--sci-tree-node-background-color-selected`
+ * - `--sci-tree-node-border-radius`
+ * - `--sci-tree-node-outline-color`
+ * - `--sci-tree-node-outline-width`
+ * - `--sci-tree-node-outline-style`
+ * - `--sci-tree-node-action-background-color`
+ * - `--sci-tree-node-action-background-color-selected`
+ *
+ * @experimental since 22.7.0; API and behavior may change in any version without notice.
+ */
+declare class SciTreeComponent<T = unknown, ID = T> {
+    /**
+     * Specifies a unique tree identifier, used as the key for storing user preferences.
+     */
+    readonly name: _angular_core.InputSignal<`tree:${string}`>;
+    /**
+     * Specifies the tree definition and datasource.
+     */
+    readonly tree: _angular_core.InputSignalWithTransform<ɵSciTree<T, ID>, SciTree<ID>>;
+    /**
+     * Emits when the user double-clicks a node or presses `Enter` on selected nodes.
+     */
+    readonly primaryAction: _angular_core.OutputEmitterRef<SciTreeEvent<ID>>;
+    constructor();
+    /**
+     * Creates and attaches a {@link SciTableComponent} using this component as host.
+     */
+    private attachVirtualTable;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SciTreeComponent<any, any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SciTreeComponent<any, any>, "sci-tree", never, { "name": { "alias": "name"; "required": true; "isSignal": true; }; "tree": { "alias": "tree"; "required": true; "isSignal": true; }; }, { "primaryAction": "primaryAction"; }, never, never, true, never>;
+}
+
+export { SciTreeComponent, provideTreeDatasource, tree, ɵprovideTreeDatasource };
+export type { SciTree, SciTreeDatasource, SciTreeDatasourceProvider, SciTreeDatasourceQuery, SciTreeDescriptor, SciTreeNode, SciTreeNodeContext };