@scion/components 22.6.0 → 22.7.0

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

@@ -1,12 +1,243 @@
 import * as _angular_core from '@angular/core';
-import { Signal, Provider, WritableSignal, Injector, Type, EnvironmentProviders } from '@angular/core';
-import { Observable } from 'rxjs';
+import { WritableSignal, Signal, Provider, Injector } from '@angular/core';
+import { MaybeArray, MaybeAsync } from '@scion/toolkit/types';
 import { MaybeSignal, SciComponentDescriptor, SciTemplateDescriptor } from '@scion/components/common';
 import { SciToolbarFactory, SciToolbarComponent } from '@scion/components/menu';
 import { Translatable } from '@scion/components/text';
 
-type MaybeAsync<T> = T | Promise<T> | Observable<T>;
+/**
+ * @docs-private Not public API. For internal use only.
+ */
+declare class ɵSciTable<T = unknown, ID = T> implements SciTable<ID> {
+    private readonly _tableStorage;
+    private readonly _injector;
+    readonly name: WritableSignal<`table:${string}` | undefined>;
+    readonly columns: Signal<SciTableColumnLike<T>[]>;
+    readonly rowActions?: SciTableRowActionFactoryFn<T>;
+    private readonly _rowBindings;
+    private readonly _datasource;
+    private readonly _trackBy?;
+    readonly tableViewRef: WritableSignal<SciTableViewRef | undefined>;
+    readonly userSettings: WritableSignal<SciTableUserSettings>;
+    readonly type: 'table' | 'tree';
+    readonly bufferSize: number;
+    readonly pageSize: number;
+    readonly filterable: WritableSignal<boolean>;
+    readonly showHeader: WritableSignal<boolean>;
+    readonly wrapHeader: WritableSignal<boolean>;
+    readonly sortable: WritableSignal<boolean>;
+    readonly resizable: WritableSignal<boolean>;
+    readonly selectable: WritableSignal<'single' | 'multi' | false>;
+    readonly scrollRange: Signal<SciScrollRange | undefined>;
+    readonly scrollTop: Signal<number>;
+    readonly virtualScrollOffset: Signal<{
+        top: number;
+        bottom: number;
+    }>;
+    readonly viewportPageSize: Signal<number>;
+    readonly scrolling: Signal<boolean>;
+    readonly resizing: Signal<boolean>;
+    readonly sortCriteria: WritableSignal<SciTableSortCriterion[]>;
+    readonly columnFilters: WritableSignal<SciTableColumnFilter[]>;
+    private readonly _cache;
+    private readonly _tableCellValuePreloader;
+    private readonly _tableFilter;
+    private readonly _tableTree;
+    readonly hoveredIndex: WritableSignal<number>;
+    readonly criteria: Signal<{
+        sort: SciTableSortCriterion[];
+        filter: SciTableColumnFilter[];
+        tableFilter: string | null;
+    }>;
+    readonly loading: Signal<boolean>;
+    readonly error: Signal<boolean>;
+    readonly activeRow: Signal<SciTableRow<T, ID> | undefined>;
+    readonly selectedItems: Signal<ID[]>;
+    readonly rowsById: Signal<Map<ID, SciTableRow<T, ID>>>;
+    readonly rows: Signal<SciTableRow<T, ID>[]>;
+    readonly visibleRowCount: Signal<number>;
+    readonly visibleRows: Signal<SciTreeTableNode<ID>[] | undefined>;
+    readonly rowIndexById: Signal<Map<ID, number>>;
+    readonly activeItem: Signal<ID | undefined>;
+    readonly activeIndex: Signal<number>;
+    constructor(descriptor: SciTableDescriptor<T, ID> & {
+        type?: 'table' | 'tree';
+    });
+    /**
+     * Connects {@link SciTableComponent} to the model.
+     */
+    connect(name: `table:${string}`, viewRef: SciTableViewRef): void;
+    disconnect(): void;
+    private computeColumns;
+    /**
+     * Computes the rows currently visible in the viewport (+buffer).
+     */
+    private computeRows;
+    /**
+     * Computes the visible row count based on the viewport size.
+     */
+    private computeScrollRange;
+    private computeVirtualScrollOffset;
+    private computeViewportPageSize;
+    /**
+     * Tracks {@link HTMLElement.scrollTop} of the viewport.
+     */
+    private computeScrollTop;
+    /**
+     * Tracks whether currently scrolling the viewport.
+     */
+    private computeScrolling;
+    /**
+     * Loads the requested page from the cache or datasource and returns its loading state with a cancelation handler.
+     */
+    private loadPage;
+    /**
+     * Toggles sort on a column. ASC -> DESC -> No sort
+     *
+     * TODO [ego] Revisit API, do we really want a three-state and implicit toggling logic?
+     */
+    sort(columnName: `column:${string}`, multi: boolean): void;
+    /**
+     * Applies a filter, either via global filter or on a specific column.
+     */
+    filter(text: string | null): void;
+    filter(text: string | number | boolean | SciEnumValueLike | SciEnumValueLike[] | null, options: {
+        columnName: `column:${string}`;
+    }): void;
+    setActiveItem(id: ID | undefined): void;
+    updateSelectedItems(updateFn: (ids: Set<ID>) => Set<ID>): void;
+    /**
+     * Indicates whether the built-in in-memory datasource is used.
+     */
+    isInMemoryDatasource(): boolean;
+    reload(): void;
+    reloadFailed(): void;
+    dispose(): void;
+    /**
+     * Loads a set of pages on criteria or viewport changes.
+     */
+    private installPageLoader;
+    private mapItemsToRow;
+    /**
+     * Creates a signal to read and write table user settings.
+     */
+    private computeUserSettings;
+    /**
+     * Call trackBy function or fallback to track by object reference.
+     */
+    trackBy(item: T): ID;
+    private computeActiveRow;
+    select(ids: MaybeArray<ID>): void;
+    expand(ids: MaybeArray<ID>): void;
+    isExpanded(id: ID): boolean;
+    expandAll(): void;
+    collapse(ids: MaybeArray<ID>): void;
+    collapseAll(): void;
+    toggleRow(id: ID): void;
+}
+interface SciScrollRange {
+    /** inclusive */
+    start: number;
+    /** exclusive */
+    end: number;
+}
+interface SciTableUserSettings {
+    columns?: {
+        name: string;
+        width?: number;
+    }[];
+}
+interface SciTableViewRef {
+    viewport: HTMLElement;
+    viewportHeight: Signal<number>;
+    viewportWidth: Signal<number>;
+    viewportClientHeight: Signal<number>;
+    viewportClientWidth: Signal<number>;
+    headerHeight: Signal<number>;
+    cellPadding: Signal<number>;
+    itemHeight: Signal<number>;
+    scrollToTop: () => void;
+}
 
+/**
+ * Provides an in-memory datasource for {@link SciTable} with built-in filtering and sorting.
+ *
+ * A datasource provides data to {@link SciTable}, passing each item to columns for display. For a tree structure, additionally pass a child selector to the datasource.
+ *
+ * This datasource requires all data to be loaded upfront. The datasource filters and sorts data in memory.
+ *
+ * Custom columns must configure a filter matcher and sort comparator to be filterable and sortable.
+ *
+ * For large datasets requiring pagination or server-side filtering and sorting, prefer implementing a custom datasource using {@link ɵprovideTableDatasource}.
+ *
+ * @example - Usage
+ * ```ts
+ * import {table, provideTableDatasource} from '@scion/components/table';
+ * import {httpResource} from '@angular/common/http';
+ *
+ * const users = httpResource<User[]>(() => '/api/users', {defaultValue: []});
+ *
+ * table({
+ *   datasource: provideTableDatasource(users.value),
+ *   columns: table => table.addStringColumn('Name', user => user.name),
+ * });
+ * ```
+ *
+ * @example - Displaying hierarchical data
+ * ```ts
+ * import {table, provideTableDatasource} from '@scion/components/table';
+ * import {httpResource} from '@angular/common/http';
+ *
+ * const users = httpResource<User[]>(() => '/api/users', {defaultValue: []});
+ *
+ * table({
+ *   datasource: provideTableDatasource(users.value, user => user.children),
+ *   columns: table => table.addStringColumn('Name', user => user.name),
+ * });
+ * ```
+ *
+ * @param data - Provides items to display in the table, or root items if displaying a tree structure.
+ * @param children - Function required to display a tree structure, 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 table, inside a reactive context that re-evaluates when tracked signals change.
+ *
+ * @see SciTableDescriptor.datasource
+ */
+declare function provideTableDatasource<T>(data: Signal<T[]>, children?: (item: T) => T[]): SciTableDatasourceProvider<T>;
+/**
+ * @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 ɵprovideTableDatasource<T, ID = T>(tableDatasource: SciTableDatasource<T, ID>): SciTableDatasourceProvider<T, ID>;
+declare function ɵprovideTableDatasource<T, ID = T>(treeTableDatasource: SciTreeTableDatasource<T, ID>): SciTableDatasourceProvider<T, ID>;
+interface SciTableDatasource<T, ID> {
+    getIds: (query: SciTableDatasourceQuery) => MaybeAsync<ID[]>;
+    getItems: (ids: ID[]) => MaybeAsync<T[]>;
+}
+/**
+ * @experimental since 22.7.0; API and behavior may change in any version without notice.
+ */
+interface SciTreeTableDatasource<T, ID> {
+    getTreeTableNodes(query: SciTableDatasourceQuery): MaybeAsync<SciTreeTableNode<ID>[]>;
+    getItems(ids: ID[]): MaybeAsync<T[]>;
+}
+/**
+ * Symbol for providing a {@link SciTreeTableDatasource}.
+ */
+declare const eSCI_TABLE_DATASOURCE_PROVIDER: unique symbol;
+/**
+ * Symbol for providing type inference for the ID type.
+ */
+declare const eSCI_TABLE_DATASOURCE_ID_TYPE: unique symbol;
+/**
+ * Provides a datasource to {@link SciTable}.
+ */
+type SciTableDatasourceProvider<T, ID = never> = {
+    readonly [eSCI_TABLE_DATASOURCE_ID_TYPE]?: ID;
+} & ([ID] extends [never] ? {
+    readonly [eSCI_TABLE_DATASOURCE_PROVIDER]: <ID>(table: ɵSciTable<T, ID>) => SciTreeTableDatasource<T, ID>;
+} : {
+    readonly [eSCI_TABLE_DATASOURCE_PROVIDER]: (table: ɵSciTable<T, ID>) => SciTreeTableDatasource<T, ID>;
+});
 interface SciTableColumnFilter {
     columnName: `column:${string}`;
     text: string | number | boolean | SciEnumValueLike | SciEnumValueLike[];
@@ -15,37 +246,15 @@ interface SciTableSortCriterion {
     columnName: `column:${string}`;
     direction: 'asc' | 'desc';
 }
-interface SciTablePageRequest {
-    page: number;
-    pageSize: number;
-    start: number;
-    end: number;
+interface SciTableDatasourceQuery {
     sortCriteria: SciTableSortCriterion[];
     columnFilters: SciTableColumnFilter[];
     tableFilter?: string;
 }
-interface SciTablePageResponse<T> {
-    /**
-     * Items of the requested page.
-     */
-    items: T[];
-    /**
-     * Total count of the source data, used to calculate the scroll size.
-     */
-    totalCount: number;
+interface SciTreeTableNode<ID> {
+    id: ID;
+    parentId?: ID;
 }
-/**
- * @docs-private Not public API. For internal use only.
- * @experimental since 22.3.0; API and behavior may change in any version without notice.
- */
-type SciTableDataLoaderFn<T> = (request: SciTablePageRequest) => MaybeAsync<SciTablePageResponse<T>>;
-/**
- * TODO [table] Remove after datasource is final.
- *
- * @docs-private Not public API. For internal use only.
- * @experimental since 22.3.0; API and behavior may change in any version without notice.
- */
-declare function ɵillegaldatasource<T>(): Signal<T[]>;
 
 /**
  * Provides row bindings to tables in the scope of the injector providing the bindings.
@@ -136,15 +345,43 @@ interface SciTableRowBindingFactory {
      */
     addClassBinding(name: string | undefined): this;
 }
+declare class ɵSciTableRowBindingFactory implements SciTableRowBindingFactory {
+    readonly icons: string[];
+    readonly parts: string[];
+    readonly attributes: [string, unknown][];
+    readonly classes: string[];
+    addIconBinding(icon: string | undefined): this;
+    addPartBinding(name: string | undefined): this;
+    addAttributeBinding(name: string, value: unknown | undefined): this;
+    addClassBinding(name: string | undefined): this;
+}
 interface SciTableRowBindings {
     icons: Signal<string[]>;
-    parts: Signal<`row:${string}`[]>;
+    parts: Signal<string[]>;
     attributes: Signal<{
         [name: string]: unknown;
     }>;
     classes: Signal<string[]>;
 }
 
+/**
+ * Represents the internal value of {@link SciDateColumn}.
+ */
+interface SciDateValue {
+    /**
+     * Full ISO 8601 date/time string.
+     */
+    isoString: string;
+    /**
+     * Milliseconds since UTC epoch.
+     */
+    millis: number;
+    /**
+     * Human-readable formatted date and time string.
+     */
+    formatted: string;
+}
+
 interface SciTableColumnFactory<T> {
     /**
      * Adds a column to the table for displaying text.
@@ -631,7 +868,7 @@ interface SciEnumColumnDescriptor<T = unknown> extends SciTableColumnDescriptor
     /**
      * Configures the display of enumeration values.
      *
-     * Defaults to displaying the label in cells, and both icon and label in the column filter menu. Defaults are unset when using a custom format.
+     * Defaults to displaying the label in cells, and both icon and label in the column filter menu. Defaults are unset if using a custom format.
      */
     format?: {
         /**
@@ -735,24 +972,6 @@ type SciTableColumnSortComparatorFn<T = unknown, VALUE = unknown> = (a: SciTable
  */
 type SciTableColumnFilterMatcherFn<T = unknown, VALUE = unknown, FILTER = VALUE> = (filter: FILTER, context: SciTableCellContext<T, VALUE>) => boolean;
 
-/**
- * Represents the internal value of {@link SciDateColumn}.
- */
-interface SciDateValue {
-    /**
-     * Full ISO 8601 date/time string.
-     */
-    isoString: string;
-    /**
-     * Milliseconds since UTC epoch.
-     */
-    millis: number;
-    /**
-     * Human-readable formatted date and time string.
-     */
-    formatted: string;
-}
-
 /**
  * Represents the internal value of {@link SciEnumColumn}.
  */
@@ -769,21 +988,97 @@ interface SciEnumValue {
  * Represents supported column types of {@link SciTableComponent}.
  */
 type SciTableColumnType = 'string' | 'number' | 'boolean' | 'date' | 'icon' | 'enum' | 'component' | 'template';
-interface SciTableDescriptor<T> {
-    datasource: Signal<T[]>;
+/**
+ * Represents a descriptor to configure {@link SciTableComponent}.
+ *
+ * Defines the columns, datasource, and display options. Requires at minimum a datasource and columns.
+ */
+interface SciTableDescriptor<T, ID = T> {
+    /**
+     * Specifies the datasource to provide data to {@link SciTable}.
+     *
+     * Create a datasource using the {@link provideTableDatasource} function and pass a signal containing the items.
+     * For a tree structure, additionally pass a child selector to the datasource.
+     *
+     * As a convenience for non-hierarchical tables, an array signal can be used directly as the datasource.
+     *
+     * @example - Usage
+     * ```ts
+     * import {table} from '@scion/components/table';
+     * import {httpResource} from '@angular/common/http';
+     *
+     * const users = httpResource<User[]>(() => '/api/users', {defaultValue: []});
+     *
+     * table({
+     *   datasource: users.value,
+     *   columns: table => table.addStringColumn('Name', user => user.name),
+     * });
+     * ```
+     *
+     * @example - Displaying hierarchical data
+     * ```ts
+     * import {table, provideTableDatasource} from '@scion/components/table';
+     * import {httpResource} from '@angular/common/http';
+     *
+     * const users = httpResource<User[]>(() => '/api/users', {defaultValue: []});
+     *
+     * table({
+     *   datasource: provideTableDatasource(users.value, user => user.children),
+     *   columns: table => table.addStringColumn('Name', user => user.name),
+     * });
+     * ```
+     *
+     * @see provideTableDatasource
+     */
+    datasource: Signal<T[]> | SciTableDatasourceProvider<T, ID>;
     /**
-     * @docs-private Not public API. For internal use only.
-     * @experimental since 22.3.0; API and behavior may change in any version without notice.
+     * Configures the table columns.
+     *
+     * @example
+     * ```ts
+     * import {table} from '@scion/components/table';
+     *
+     * table({
+     *   datasource: data,
+     *   columns: table => table
+     *     .addStringColumn('Name', item => item.name)
+     *     .addNumberColumn('Age', item => item.age),
+     * });
+     * ```
+     *
+     * The function:
+     * - Runs in a reactive context and re-evaluates when tracked signals change.
+     * - Can call `inject` to get required dependencies.
      */
-    ɵdatasource?: Signal<T[]> | SciTableDataLoaderFn<T>;
     columns: SciTableColumnFactoryFn<T>;
+    /**
+     * Controls whether the user can sort rows by clicking column headers. Defaults to `true`.
+     */
     sortable?: boolean;
+    /**
+     * Controls whether the user can resize columns. Defaults to `true`.
+     */
     resizable?: boolean;
+    /**
+     * Controls whether the column filters are displayed. Defaults to `false`.
+     *
+     * Does not affect filtering via {@link SciTable.filter}.
+     */
     filterable?: boolean;
+    /**
+     * Controls whether the user can select a single row (`single`), multiple rows (`multi`), or no rows (`false`). Defaults to `multi`.
+     *
+     * Does not affect selection via {@link SciTable.select}.
+     */
     selectable?: 'single' | 'multi' | false;
+    /**
+     * Controls whether column headers are displayed. Defaults to `true`.
+     */
     showHeader?: boolean;
     /**
-     * Defaults to false.
+     * Controls whether column headers are wrapped if they overflow. Defaults to `false`.
+     *
+     * If not wrapped, the headers are truncated and ellipsis are shown on overflow.
      */
     wrapHeader?: boolean;
     /**
@@ -855,28 +1150,97 @@ interface SciTableDescriptor<T> {
      * Specifies the number of items to load per page. Defaults to 50.
      */
     pageSize?: number;
-    trackBy?: (item: T) => unknown;
+    /**
+     * Computes a unique and stable identity for items in the table.
+     *
+     * Defaults to the item object reference. Used to identify items when loading data from the datasource and when tracking table selection.
+     */
+    trackBy?: (item: T) => ID;
+    /**
+     * Specifies an injector used to create the table. Defaults to the current injection context.
+     * The table is disposed when the passed injector is destroyed.
+     */
     injector?: Injector;
 }
-interface SciTable<T> {
+/**
+ * Represents a table for {@link SciTableComponent}.
+ *
+ * Can be constructed using the {@link table} function.
+ * Use to bind to `<sci-table>` and interact with the table.
+ *
+ * @see table
+ * @see SciTableComponent
+ */
+interface SciTable<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>;
     /**
-     * Currently active item.
+     * Provides the selected items.
      */
-    readonly activeItem: Signal<T | undefined>;
+    readonly selectedItems: Signal<Array<ID>>;
     /**
-     * Selected items.
+     * Controls whether the column filters are displayed.
+     *
+     * Initialized from {@link SciTableDescriptor.filterable}. Defaults to `false`.
+     * Does not affect filtering via {@link SciTable.filter}.
      */
-    readonly selectedItems: Signal<Array<T>>;
     readonly filterable: WritableSignal<boolean>;
+    /**
+     * Controls whether column headers are displayed.
+     *
+     * Initialized from {@link SciTableDescriptor.showHeader}. Defaults to `true`.
+     */
     readonly showHeader: WritableSignal<boolean>;
+    /**
+     * Controls whether column headers are wrapped if they overflow.
+     *
+     * If not wrapped, the headers are truncated with an ellipsis on overflow.
+     * Initialized from {@link SciTableDescriptor.wrapHeader}. Defaults to `false`.
+     */
     readonly wrapHeader: WritableSignal<boolean>;
+    /**
+     * Controls whether the user can sort rows by clicking column headers.
+     *
+     * Initialized from {@link SciTableDescriptor.sortable}. Defaults to `true`.
+     */
     readonly sortable: WritableSignal<boolean>;
+    /**
+     * Controls whether the user can resize columns.
+     *
+     * Initialized from {@link SciTableDescriptor.resizable}. Defaults to `true`.
+     */
     readonly resizable: WritableSignal<boolean>;
+    /**
+     * Controls whether the user can select a single row (`single`), multiple rows (`multi`), or no rows (`false`).
+     *
+     * Initialized from {@link SciTableDescriptor.selectable}. Defaults to `multi`.
+     * Does not affect selection via {@link SciTable.select}.
+     */
     readonly selectable: WritableSignal<'single' | 'multi' | false>;
     /**
      * Filters items cross-column, ignoring {@link SciTableDescriptor.filterable} and {@link SciTableColumnDescriptor.filterable} settings.
      */
     filter(text: string | null): void;
+    /**
+     * Selects the specified rows, replacing the current selection.
+     *
+     * Expands parent rows for table tree (hierarchical) datasource.
+     *
+     * @param id - ID or IDs of the rows to select, or an empty array to clear the selection.
+     */
+    select(id: MaybeArray<ID>): void;
+    /**
+     * Expands all rows in the tree. Only for table tree (hierarchical) datasource.
+     */
+    expandAll(): void;
+    /**
+     * Collapses all rows in the tree. Only for table tree (hierarchical) datasource.
+     */
+    collapseAll(): void;
 }
 interface SciTableColumn<T = unknown, VALUE = unknown, FILTER = VALUE> {
     type: SciTableColumnType;
@@ -936,19 +1300,23 @@ interface SciTemplateColumn<T = unknown> extends SciTableColumn<T, void, string>
     template: (item: T) => SciTemplateDescriptor;
 }
 type SciTableColumnLike<T = unknown> = SciStringColumn<T> | SciNumberColumn<T> | SciDateColumn<T> | SciEnumColumn<T> | SciComponentColumn<T> | SciTemplateColumn<T>;
+declare const skeletonRowId: unique symbol;
 /**
  * Mapped row, used as display state.
  */
-interface SciTableRow<T> {
+interface SciTableRow<T, ID> {
     index: number;
-    item?: T;
-    id?: unknown;
-    cells?: SciTableCellLike[];
-    bindings?: SciTableRowBindings;
-    loading: boolean;
+    item: T;
+    id: ID | typeof skeletonRowId;
+    level?: number;
+    parentId?: ID;
+    cells: SciTableCellLike[];
+    bindings: SciTableRowBindings;
     active: Signal<boolean>;
     selected: Signal<boolean>;
     hovered: Signal<boolean>;
+    expanded: Signal<boolean>;
+    hasChildren: Signal<boolean>;
 }
 interface SciStringCell {
     type: 'string';
@@ -998,7 +1366,7 @@ type SciTableRowActionFactoryFn<T> = (toolbar: SciToolbarFactory, item: T, index
 /**
  * Represents an event emitted by {@link SciTableComponent}.
  */
-interface SciTableEvent<T> {
+interface SciTableEvent<ID> {
     /**
      * The native browser event (`MouseEvent` or `KeyboardEvent`) that triggered the action.
      */
@@ -1006,7 +1374,7 @@ interface SciTableEvent<T> {
     /**
      * The items associated with the action.
      */
-    items: T[];
+    items: ID[];
 }
 /**
  * Represents the header of a table column, defined as a {@link Translatable} or an object with an optional icon, label, and tooltip.
@@ -1070,183 +1438,265 @@ type SciIconColumnValues = {
 }[];
 
 type SciTableColumnFactoryFn<T> = (table: SciTableColumnFactory<T>) => void;
-/** @experimental since 22.3.0; API and behavior may change in any version without notice. */
+/**
+ * Creates a table for displaying tabular or hierarchical data in {@link SciTableComponent}.
+ *
+ * Pass a descriptor to define the columns, datasource, and display options. Requires at minimum a datasource and columns.
+ *
+ * ```ts
+ * import {table} from '@scion/components/table';
+ * import {httpResource} from '@angular/common/http';
+ *
+ * const users = httpResource<User[]>(() => '/api/users', {defaultValue: []});
+ *
+ * const userTable = table({
+ *   datasource: users.value,
+ *   columns: table => table
+ *     .addStringColumn('Name', user => user.name)
+ *     .addBooleanColumn('Inactive', user => user.inactive)
+ *     .addDateColumn('Expiration', user => user.expiration),
+ * });
+ * ```
+ *
+ * In the HTML, bind the created table instance to `<sci-table>`.
+ *
+ * ```html
+ * <sci-table name="table:users" [table]="userTable"/>
+ * ```
+ *
+ * To display a tree structure, provide a hierarchical datasource via {@link provideTableDatasource}, passing a signal
+ * containing the root items and a function that returns the children of a given item.
+ *
+ * ```ts
+ * import {table, provideTableDatasource} from '@scion/components/table';
+ * import {httpResource} from '@angular/common/http';
+ *
+ * const users = httpResource<User[]>(() => '/api/users', {defaultValue: []});
+ *
+ * const userTable = table({
+ *   datasource: provideTableDatasource(users.value, user => user.children),
+ *   columns: table => table
+ *     .addStringColumn('Name', user => user.name)
+ *     .addBooleanColumn('Inactive', user => user.inactive)
+ *     .addDateColumn('Expiration', user => user.expiration),
+ * });
+ * ```
+ *
+ * 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 SciTableComponent
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ *
+ * @param descriptor - Configures the table. Requires a datasource and columns.
+ * @return Handle to bind to `<sci-table>` and interact with the table.
+ */
 declare function table<T>(descriptor: SciTableDescriptor<T>): SciTable<T>;
-/** @experimental since 22.3.0; API and behavior may change in any version without notice. */
+/**
+ * Creates a table for displaying tabular or hierarchical data in {@link SciTableComponent}.
+ *
+ * Pass a descriptor to define the columns, datasource, and display options. Requires at minimum a datasource and columns.
+ *
+ * ```ts
+ * import {table} from '@scion/components/table';
+ * import {httpResource} from '@angular/common/http';
+ *
+ * const users = httpResource<User[]>(() => '/api/users', {defaultValue: []});
+ *
+ * const userTable = table({
+ *   datasource: users.value,
+ *   columns: table => table
+ *     .addStringColumn('Name', user => user.name)
+ *     .addBooleanColumn('Inactive', user => user.inactive)
+ *     .addDateColumn('Expiration', user => user.expiration),
+ * });
+ * ```
+ *
+ * In the HTML, bind the created table instance to `<sci-table>`.
+ *
+ * ```html
+ * <sci-table name="table:users" [table]="userTable"/>
+ * ```
+ *
+ * To display a tree structure, provide a hierarchical datasource via {@link provideTableDatasource}, passing a signal
+ * containing the root items and a function that returns the children of a given item.
+ *
+ * ```ts
+ * import {table, provideTableDatasource} from '@scion/components/table';
+ * import {httpResource} from '@angular/common/http';
+ *
+ * const users = httpResource<User[]>(() => '/api/users', {defaultValue: []});
+ *
+ * const userTable = table({
+ *   datasource: provideTableDatasource(users.value, user => user.children),
+ *   columns: table => table
+ *     .addStringColumn('Name', user => user.name)
+ *     .addBooleanColumn('Inactive', user => user.inactive)
+ *     .addDateColumn('Expiration', user => user.expiration),
+ * });
+ * ```
+ *
+ * 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 SciTableComponent
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ *
+ * @param descriptor - Configures the table. Requires a datasource and columns.
+ * @return Handle to bind to `<sci-table>` and interact with the table.
+ */
+declare function table<T, ID>(descriptor: SciTableDescriptor<T, ID> & {
+    trackBy: (item: T) => ID;
+}): SciTable<ID>;
+/**
+ * Creates a table for displaying tabular data in {@link SciTableComponent}.
+ *
+ * Pass a signal containing the items to display in the table and a factory function to define the columns.
+ * The table calls the passed function with a factory that has methods for adding columns to the table.
+ *
+ * NOTE: This function is a shorthand for creating a table directly from data and columns; pass a descriptor instead to display a tree structure, configure a custom datasource, or set additional options.
+ *
+ * ```ts
+ * import {SciTableComponent, table} from '@scion/components/table';
+ * import {httpResource} from '@angular/common/http';
+ *
+ * // Load data to display in the table.
+ * const users = httpResource<User[]>(() => '/api/users', {defaultValue: []});
+ *
+ * // Create the table and pass data.
+ * const userTable = table(users.value, table => table
+ *   .addStringColumn('Name', user => user.name)
+ *   .addBooleanColumn('Inactive', user => user.inactive)
+ *   .addDateColumn('Expiration', user => user.expiration),
+ * );
+ * ```
+ *
+ * In the HTML, bind the created table instance to `<sci-table>`.
+ *
+ * ```html
+ * <sci-table name="table:users" [table]="userTable"/>
+ * ```
+ *
+ * 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 SciTableComponent
+ * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ *
+ * @param data - Specifies items to display in the table.
+ * @param columnFactoryFn - Specifies a factory function to add columns to the table.
+ * @param options - Controls table creation.
+ * @param options.injector - Injector used to create the table. Defaults to the current injection context. The table is disposed when the passed injector is destroyed.
+ * @return Handle to bind to `<sci-table>` and interact with the table.
+ */
 declare function table<T>(data: Signal<T[]>, columnFactoryFn: SciTableColumnFactoryFn<T>, options?: {
     injector?: Injector;
 }): SciTable<T>;
 
-declare class ɵSciTable<T = unknown> implements SciTable<T> {
-    private readonly _tableStorage;
-    private readonly _injector;
-    readonly name: WritableSignal<`table:${string}` | undefined>;
-    readonly columns: Signal<SciTableColumnLike<T>[]>;
-    readonly rowActions?: SciTableRowActionFactoryFn<T>;
-    private readonly _rowBindings;
-    private readonly _dataLoaderFn;
-    private readonly _trackBy?;
-    readonly tableViewRef: WritableSignal<SciTableViewRef | undefined>;
-    readonly userSettings: WritableSignal<SciTableUserSettings>;
-    readonly bufferSize: number;
-    readonly pageSize: number;
-    readonly filterable: WritableSignal<boolean>;
-    readonly showHeader: WritableSignal<boolean>;
-    readonly wrapHeader: WritableSignal<boolean>;
-    readonly sortable: WritableSignal<boolean>;
-    readonly resizable: WritableSignal<boolean>;
-    readonly selectable: WritableSignal<'single' | 'multi' | false>;
-    readonly scrollRange: Signal<SciScrollRange | undefined>;
-    readonly scrollTop: Signal<number>;
-    readonly virtualScrollOffset: Signal<{
-        top: number;
-        bottom: number;
-    }>;
-    readonly viewportPageSize: Signal<number>;
-    readonly scrolling: Signal<boolean>;
-    readonly resizing: Signal<boolean>;
-    readonly sortCriteria: WritableSignal<SciTableSortCriterion[]>;
-    readonly filterCriteria: WritableSignal<SciTableColumnFilter[]>;
-    private readonly _cache;
-    private readonly _tableCellValuePreloader;
-    private readonly _tableFilter;
-    private readonly _selectedItems;
-    readonly totalCount: WritableSignal<number | undefined>;
-    readonly activeItem: WritableSignal<T | undefined>;
-    readonly hoveredIndex: WritableSignal<number>;
-    readonly criteria: Signal<{
-        sort: SciTableSortCriterion[];
-        filter: SciTableColumnFilter[];
-        tableFilter: string | null;
-    }>;
-    readonly loading: Signal<boolean>;
-    readonly error: Signal<Error | undefined>;
-    readonly activeRow: Signal<SciTableRow<T> | undefined>;
-    readonly hoveredRow: Signal<SciTableRow<T> | undefined>;
-    readonly selectedItems: Signal<T[]>;
-    readonly selectedIds: Signal<Set<unknown>>;
-    readonly rowsByIndex: Signal<Map<number, SciTableRow<T>>>;
-    readonly rows: Signal<SciTableRow<T>[]>;
-    constructor(descriptor: SciTableDescriptor<T>);
-    /**
-     * Connects {@link SciTableComponent} to the model.
-     */
-    connect(name: `table:${string}`, viewRef: SciTableViewRef): void;
-    disconnect(): void;
-    private computeColumns;
-    /**
-     * Computes the rows currently visible in the viewport (+buffer).
-     */
-    private computeRows;
-    /**
-     * Computes the visible row count based on the viewport size.
-     */
-    private computeScrollRange;
-    private computeVirtualScrollOffset;
-    private computeViewportPageSize;
-    /**
-     * Tracks {@link HTMLElement.scrollTop} of the viewport.
-     */
-    private computeScrollTop;
-    /**
-     * Tracks whether currently scrolling the viewport.
-     */
-    private computeScrolling;
-    /**
-     * Loads a range of rows, based on the current sort and filter criteria, into the cache.
-     */
-    loadRange(start: number, end: number): Promise<void>;
-    /**
-     * Loads the requested page from the cache or datasource and returns its loading state with a cancelation handler.
-     */
-    private loadPage;
-    /**
-     * Toggles sort on a column. ASC -> DESC -> No sort
-     *
-     * TODO [ego] Revisit API, do we really want a three-state and implicit toggling logic?
-     */
-    sort(columnName: `column:${string}`, multi: boolean): void;
-    /**
-     * Applies a filter, either via global filter or on a specific column.
-     */
-    filter(text: string | null): void;
-    filter(text: string | number | boolean | SciEnumValueLike | SciEnumValueLike[] | null, options: {
-        columnName: `column:${string}`;
-    }): void;
-    updateSelectedItems(updateFn: (ids: Map<unknown, T>) => Map<unknown, T>): void;
-    /**
-     * Indicates whether the built-in array datasource is used.
-     *
-     * Supports out-of-the-box filtering and sorting for built-in table columns.
-     */
-    isArrayDatasource(): boolean;
-    reset(): void;
-    dispose(): void;
-    /**
-     * Loads a set of pages on criteria or viewport changes.
-     */
-    private installPageLoader;
-    /**
-     * Resets cache on criteria changes.
-     */
-    private installCriteriaWatcher;
-    private mapItemsToRow;
-    /**
-     * Creates a signal to read and write table user settings.
-     */
-    private computeUserSettings;
-    /**
-     * Call trackBy function or fallback to track by object reference.
-     */
-    trackBy(item: T): unknown;
-    private computeActiveRow;
-}
-interface SciScrollRange {
-    /** incluse */
-    start: number;
-    /** exclusive */
-    end: number;
-}
-interface SciTableUserSettings {
-    columns?: {
-        name: string;
-        width?: number;
-    }[];
-}
-interface SciTableViewRef {
-    viewport: HTMLElement;
-    viewportHeight: Signal<number>;
-    viewportWidth: Signal<number>;
-    viewportClientHeight: Signal<number>;
-    viewportClientWidth: Signal<number>;
-    headerHeight: Signal<number>;
-    cellPadding: Signal<number>;
-    itemHeight: Signal<number>;
-    scrollToTop: () => void;
-}
-
-declare class SciTableRowComponent<T> {
-    readonly row: _angular_core.InputSignal<SciTableRow<T>>;
-    readonly primaryAction: _angular_core.OutputEmitterRef<SciTableEvent<T>>;
-    protected readonly table: _angular_core.Signal<ɵSciTable<unknown>>;
-    protected readonly rowActionToolbar: _angular_core.Signal<SciToolbarComponent | undefined>;
-    protected readonly rowActionsToolbarName: `toolbar:${string}`;
+declare class SciTableRowComponent<T, ID> {
+    readonly row: _angular_core.InputSignal<SciTableRow<T, ID>>;
+    readonly primaryAction: _angular_core.OutputEmitterRef<SciTableEvent<ID>>;
+    protected readonly table: Signal<ɵSciTable<T, ID>>;
     private readonly _selectionService;
+    protected readonly rowActionToolbar: Signal<SciToolbarComponent | undefined>;
+    protected readonly rowActionsToolbarName: `toolbar:${string}`;
     constructor();
     protected onRowClick(event: PointerEvent): void;
     protected onRowDblClick(event: MouseEvent): void;
     protected onRowMouseEnter(): void;
     protected onRowMouseLeave(event: MouseEvent): void;
     protected onActionToolbarClick(event: PointerEvent): void;
+    protected onTreeNodeHandle(event: PointerEvent): void;
     private contributeRowActions;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SciTableRowComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SciTableRowComponent<any>, "sci-table-row", never, { "row": { "alias": "row"; "required": true; "isSignal": true; }; }, { "primaryAction": "primaryAction"; }, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SciTableRowComponent<any, any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SciTableRowComponent<any, any>, "sci-table-row", never, { "row": { "alias": "row"; "required": true; "isSignal": true; }; }, { "primaryAction": "primaryAction"; }, never, never, true, never>;
 }
 
 /**
+ * Provides a table to display tabular or hierarchical data.
+ *
+ * ### Usage
+ *
+ * Create a table using the `table()` function, passing a signal containing the items to display in the table and a factory function to define the columns.
+ * Alternatively, pass a descriptor to display a tree structure, configure a custom datasource, or set additional options.
+ *
+ * ```ts
+ * import {SciTableComponent, table} from '@scion/components/table';
+ * import {httpResource} from '@angular/common/http';
+ *
+ * // Load data to display in the table.
+ * const users = httpResource<User[]>(() => '/api/users', {defaultValue: []});
+ *
+ * // Create the table and pass data.
+ * const userTable = table(users.value, table => table
+ *   .addNumberColumn('ID', user => user.id)
+ *   .addStringColumn('Name', user => user.name)
+ *   .addBooleanColumn('Inactive', user => user.inactive)
+ *   .addDateColumn('Expiration', user => user.expiration),
+ * );
+ * ```
+ *
+ * In the HTML, bind the created table instance to `<sci-table>` and assign it a name.
+ * The name must start with the `table:` prefix and is used to store user settings.
+ *
+ * ```html
+ * <sci-table name="table:users" [table]="userTable"/>
+ * ```
+ *
+ * ### Fixed Row Height
+ *
+ * All rows in the table must have equal height, which is `2em` by default. The height can be changed per table using the CSS variable `--sci-table-row-height`.
+ *
+ * ```scss
+ * sci-table {
+ *   --sci-table-row-height: 30px;
+ * }
+ * ```
+ *
+ * ### Styling
+ *
+ * The appearance of the table can be customized using the following CSS variables, either globally in the `:root` or at the table level.
+ *
+ * - `--sci-table-gridline-color`
+ * - `--sci-table-header-height`
+ * - `--sci-table-header-cursor`
+ * - `--sci-table-header-background-color`
+ * - `--sci-table-header-background-color-hover`
+ * - `--sci-table-header-font-family`
+ * - `--sci-table-header-font-size`
+ * - `--sci-table-header-font-weight`
+ * - `--sci-table-header-text-color`
+ * - `--sci-table-header-column-divider`
+ * - `--sci-table-row-height`
+ * - `--sci-table-row-indent`
+ * - `--sci-table-row-background-color-hover`
+ * - `--sci-table-row-background-color-selected`
+ * - `--sci-table-row-border-radius`
+ * - `--sci-table-row-outline-color`
+ * - `--sci-table-row-outline-width`
+ * - `--sci-table-row-outline-style`
+ * - `--sci-table-row-action-background-color`
+ * - `--sci-table-row-action-background-color-selected`
+ * - `--sci-table-cell-padding-inline`
+ *
  * @experimental since 22.3.0; API and behavior may change in any version without notice.
  */
-declare class SciTableComponent<T = unknown> {
+declare class SciTableComponent<T = unknown, ID = T> {
     /**
      * Specifies a unique table identifier, used as the key for storing user preferences.
      */
@@ -1254,45 +1704,26 @@ declare class SciTableComponent<T = unknown> {
     /**
      * Specifies the table definition and datasource.
      */
-    readonly table: _angular_core.InputSignalWithTransform<ɵSciTable<T>, SciTable<T>>;
+    readonly table: _angular_core.InputSignalWithTransform<ɵSciTable<T, ID>, SciTable<ID>>;
     /**
      * Emits when the user double-clicks a row or presses `Enter` on selected rows.
      */
-    readonly primaryAction: _angular_core.OutputEmitterRef<SciTableEvent<T>>;
+    readonly primaryAction: _angular_core.OutputEmitterRef<SciTableEvent<ID>>;
     private readonly _viewport;
     private readonly _viewportClient;
     private readonly _tableHeader;
     private readonly _tableBody;
     private readonly _itemSizeSyntheticElement;
     private readonly _cellPaddingSyntheticElement;
-    protected readonly rows: _angular_core.Signal<readonly SciTableRowComponent<any>[]>;
+    protected readonly rows: _angular_core.Signal<readonly SciTableRowComponent<any, any>[]>;
     constructor();
-    protected onRowPrimaryAction(event: SciTableEvent<T>): void;
+    protected onRowPrimaryAction(event: SciTableEvent<ID>): void;
     protected onRetry(): void;
     private connectToModel;
     private scrollActiveRowIntoViewport;
-    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SciTableComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SciTableComponent<any>, "sci-table", never, { "name": { "alias": "name"; "required": true; "isSignal": true; }; "table": { "alias": "table"; "required": true; "isSignal": true; }; }, { "primaryAction": "primaryAction"; }, never, never, true, never>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<SciTableComponent<any, any>, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SciTableComponent<any, any>, "sci-table", never, { "name": { "alias": "name"; "required": true; "isSignal": true; }; "table": { "alias": "table"; "required": true; "isSignal": true; }; }, { "primaryAction": "primaryAction"; }, never, never, true, never>;
 }
 
-/**
- * Provides persistent storage for the sci-table.
- */
-interface SciTableStorage {
-    /**
-     * Method invoked to load a value from persisted storage.
-     */
-    load(name: `scion.components.table:${string}`): Promise<string | null> | string | null;
-    /**
-     * Method invoked to write a value to persisted storage.
-     */
-    store(name: `scion.components.table:${string}`, value: string): Promise<void> | void;
-}
-/**
- * Defaults to localStorage persistence.
- * @param storage
- */
-declare function provideTableStorage(storage: Type<SciTableStorage>): EnvironmentProviders;
-
-export { SciTableComponent, provideTableRowBinding, provideTableStorage, table, ɵillegaldatasource };
-export type { SciBooleanColumnDescriptor, SciColumnHeaderLike, SciComponentColumnDescriptor, SciDateColumnDescriptor, SciDateLike, SciEnumColumnDescriptor, SciEnumColumnValues, SciEnumValueLike, SciIconColumnDescriptor, SciIconColumnValues, SciNumberColumnDescriptor, SciStringColumnDescriptor, SciTable, SciTableCellContext, SciTableColumnDescriptor, SciTableColumnFactory, SciTableColumnFactoryFn, SciTableColumnFilter, SciTableColumnFilterMatcherFn, SciTableColumnSortComparatorFn, SciTableColumnType, SciTableDataLoaderFn, SciTableDescriptor, SciTableEvent, SciTablePageRequest, SciTablePageResponse, SciTableRowActionFactoryFn, SciTableRowBindingFactory, SciTableRowBindingFactoryFn, SciTableSortCriterion, SciTableStorage, SciTemplateColumnDescriptor };
+export { SciTableComponent, provideTableDatasource, provideTableRowBinding, table, ɵSciTable, ɵSciTableRowBindingFactory, ɵprovideTableDatasource };
+export type { SciBooleanColumnDescriptor, SciColumnHeaderLike, SciComponentColumnDescriptor, SciDateColumnDescriptor, SciDateLike, SciEnumColumnValues, SciEnumValueLike, SciIconColumnValues, SciNumberColumnDescriptor, SciStringColumnDescriptor, SciTable, SciTableCellContext, SciTableColumnDescriptor, SciTableColumnFactory, SciTableColumnFactoryFn, SciTableColumnFilter, SciTableColumnFilterMatcherFn, SciTableColumnSortComparatorFn, SciTableColumnType, SciTableDatasource, SciTableDatasourceProvider, SciTableDatasourceQuery, SciTableDescriptor, SciTableEvent, SciTableRowActionFactoryFn, SciTableRowBindingFactory, SciTableSortCriterion, SciTemplateColumnDescriptor, SciTreeTableDatasource, SciTreeTableNode };