@scion/components 22.5.0 → 22.7.0

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

@@ -1,68 +1,315 @@
 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 | boolean | number;
+    text: string | number | boolean | SciEnumValueLike | SciEnumValueLike[];
 }
 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.
+ * Provides row bindings to tables in the scope of the injector providing the bindings.
+ *
+ * Multiple providers can be registered. Providers at different injector tree levels form a hierarchy.
  */
-type SciTableDataLoaderFn<T> = (request: SciTablePageRequest) => MaybeAsync<SciTablePageResponse<T>>;
+declare function provideTableRowBinding<T = unknown>(bindings: SciTableRowBindingFactoryFn<T>): Provider[];
 /**
- * TODO [table] Remove after datasource is final.
+ * Signature of a function to configure row bindings.
  *
- * @docs-private Not public API. For internal use only.
- * @experimental since 22.3.0; API and behavior may change in any version without notice.
+ * Called per item with a {@link SciTableRowBindingFactory} to register bindings.
+ *
+ * The function:
+ * - Runs in a reactive context and re-evaluates when tracked signals change.
+ * - Can call `inject` to get required dependencies.
+ */
+type SciTableRowBindingFactoryFn<T> = (row: SciTableRowBindingFactory, item: T, index: number) => void;
+/**
+ * Factory for configuring row bindings.
+ *
+ * Row bindings enable associating metadata and icons with a row. Metadata includes CSS shadow parts, CSS classes, and HTML attributes.
  */
-declare function ɵillegaldatasource<T>(): Signal<T[]>;
-
-declare function provideTableRowBinding<T = unknown>(bindings: SciTableRowBindingFactoryFn<T>): Provider;
-type SciTableRowBindingFactoryFn<T> = (bindings: SciTableRowBindingFactory, item: T, index: number) => void;
 interface SciTableRowBindingFactory {
-    addAttributeBinding(name: string, value: unknown | undefined): this;
-    addClassBinding(name: string | undefined): this;
     /**
-     * Adds the specified values as part attributes to the row, enabling for custom styling of the row, e.g., based on a condition.
+     * Binds an icon to the row, displayed in the first column.
+     *
+     * ```ts
+     * import {table} from '@scion/components/table';
+     *
+     * table({
+     *   datasource: data,
+     *   columns: table => ...,
+     *   rowBindings: bindings => bindings.addIconBinding('account_circle'),
+     * });
+     * ```
+     *
+     * 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;
+    /**
+     * Binds a CSS shadow part to the row for custom row/cell styling using the `::part()` CSS pseudo-element selector.
      *
      * Example usage:
      * ```ts
+     * import {table} from '@scion/components/table';
+     *
      * table({
      *   datasource: data,
+     *   columns: table => ...,
      *   rowBindings: (bindings, item, index) => bindings
      *     .addPartBinding(index % 2 === 0 ? 'row:even' : 'row:odd')
      *     .addPartBinding(item.active ? 'row:active' : undefined),
-     *   columns: table => ...,
      * });
      * ```
      *
@@ -77,21 +324,97 @@ interface SciTableRowBindingFactory {
      * ```
      */
     addPartBinding(name: `row:${string}` | undefined): this;
+    /**
+     * Binds an HTML attribute to the row.
+     *
+     * Useful for end-to-end testing, such as associating a row with an item's primary key.
+     *
+     * ```ts
+     * import {table} from '@scion/components/table';
+     *
+     * table({
+     *   datasource: data,
+     *   columns: table => ...,
+     *   rowBindings: (bindings, item) => bindings.addAttributeBinding('data-id', item.id),
+     * });
+     * ```
+     */
+    addAttributeBinding(name: string, value: unknown | undefined): this;
+    /**
+     * Binds a CSS class to the row.
+     */
+    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 {
-    cssClass: Signal<string[]>;
+    icons: Signal<string[]>;
+    parts: Signal<string[]>;
     attributes: Signal<{
         [name: string]: unknown;
     }>;
-    part: Signal<`row:${string}`[]>;
+    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> {
-    addStringColumn(header: Translatable, value: (item: T) => MaybeSignal<string | undefined>): this;
-    addStringColumn(value: (item: T) => MaybeSignal<string | undefined>): this;
+    /**
+     * Adds a column to the table for displaying text.
+     *
+     * The value can be plain text or a translation key. 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}.
+     */
+    addStringColumn(header: SciColumnHeaderLike, value: (item: T) => MaybeSignal<Translatable | undefined>): this;
+    /**
+     * Adds a column to the table for displaying text.
+     *
+     * The value can be plain text or a translation key. 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}.
+     */
+    addStringColumn(value: (item: T) => MaybeSignal<Translatable | undefined>): this;
+    /**
+     * Adds a column to the table for displaying text.
+     */
     addStringColumn(descriptor: SciStringColumnDescriptor<T>): this;
     /**
-     * Adds a number column to the table for displaying numeric values.
+     * Adds a column to the table for displaying numeric values.
      *
      * ### Tabular Figures
      * Numbers are rendered using tabular (fixed-width) figures to align digits vertically in fonts with varying character widths. Has no effect on monospaced fonts.
@@ -111,10 +434,14 @@ interface SciTableColumnFactory<T> {
      *   font-variant-numeric: normal;
      * }
      * ```
+     *
+     * The function:
+     * - Can call `inject` to get required dependencies.
+     * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
      */
-    addNumberColumn(header: Translatable, value: (item: T) => MaybeSignal<number | undefined>): this;
+    addNumberColumn(header: SciColumnHeaderLike, value: (item: T) => MaybeSignal<number | undefined>): this;
     /**
-     * Adds a number column to the table for displaying numeric values.
+     * Adds a column to the table for displaying numeric values.
      *
      * ### Tabular Figures
      * Numbers are rendered using tabular (fixed-width) figures to align digits vertically in fonts with varying character widths. Has no effect on monospaced fonts.
@@ -134,10 +461,14 @@ interface SciTableColumnFactory<T> {
      *   font-variant-numeric: normal;
      * }
      * ```
+     *
+     * The function:
+     * - Can call `inject` to get required dependencies.
+     * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
      */
     addNumberColumn(value: (item: T) => MaybeSignal<number | undefined>): this;
     /**
-     * Adds a number column to the table for displaying numeric values.
+     * Adds a column to the table for displaying numeric values.
      *
      * ### Tabular Figures
      * Numbers are rendered using tabular (fixed-width) figures to align digits vertically in fonts with varying character widths. Has no effect on monospaced fonts.
@@ -159,11 +490,37 @@ interface SciTableColumnFactory<T> {
      * ```
      */
     addNumberColumn(descriptor: SciNumberColumnDescriptor<T>): this;
-    addBooleanColumn(header: Translatable, value: (item: T) => MaybeSignal<boolean | undefined>): this;
+    /**
+     * Adds a column to the table for displaying boolean values.
+     *
+     * Cells display `true` as a checkmark and `false` as an 'X'. Filter options are labeled as 'Yes'/'No'.
+     * For custom display or filter options, use {@link addEnumColumn} instead.
+     *
+     * The function:
+     * - Can call `inject` to get required dependencies.
+     * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
+     */
+    addBooleanColumn(header: SciColumnHeaderLike, value: (item: T) => MaybeSignal<boolean | undefined>): this;
+    /**
+     * Adds a column to the table for displaying boolean values.
+     *
+     * Cells display `true` as a checkmark and `false` as an 'X'. Filter options are labeled as 'Yes'/'No'.
+     * For custom display or filter options, use {@link addEnumColumn} instead.
+     *
+     * The function:
+     * - Can call `inject` to get required dependencies.
+     * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
+     */
     addBooleanColumn(value: (item: T) => MaybeSignal<boolean | undefined>): this;
+    /**
+     * Adds a column to the table for displaying boolean values.
+     *
+     * Cells display `true` as a checkmark and `false` as an 'X'. Filter options are labeled as 'Yes'/'No'.
+     * For custom display or filter options, use {@link addEnumColumn} instead.
+     */
     addBooleanColumn(descriptor: SciBooleanColumnDescriptor<T>): this;
     /**
-     * Adds a temporal column to the table for displaying dates, times, or both.
+     * Adds a column to the table for displaying dates, times, or both.
      *
      * Supports ISO 8601 date/time strings, milliseconds since the UTC epoch, and `Date` objects.
      *
@@ -187,10 +544,14 @@ interface SciTableColumnFactory<T> {
      *   font-variant-numeric: normal;
      * }
      * ```
+     *
+     * The function:
+     * - Can call `inject` to get required dependencies.
+     * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
      */
-    addDateColumn(header: Translatable, value: (item: T) => MaybeSignal<SciDateLike | undefined>): this;
+    addDateColumn(header: SciColumnHeaderLike, value: (item: T) => MaybeSignal<SciDateLike | undefined>): this;
     /**
-     * Adds a temporal column to the table for displaying dates, times, or both.
+     * Adds a column to the table for displaying dates, times, or both.
      *
      * Supports ISO 8601 date/time strings, milliseconds since the UTC epoch, and `Date` objects.
      *
@@ -214,10 +575,14 @@ interface SciTableColumnFactory<T> {
      *   font-variant-numeric: normal;
      * }
      * ```
+     *
+     * The function:
+     * - Can call `inject` to get required dependencies.
+     * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
      */
     addDateColumn(value: (item: T) => MaybeSignal<SciDateLike | undefined>): this;
     /**
-     * Adds a temporal column to the table for displaying dates, times, or both.
+     * Adds a column to the table for displaying dates, times, or both.
      *
      * Supports ISO 8601 date/time strings, milliseconds since the UTC epoch, and `Date` objects.
      *
@@ -243,12 +608,31 @@ interface SciTableColumnFactory<T> {
      * ```
      */
     addDateColumn(descriptor: SciDateColumnDescriptor<T>): this;
+    /**
+     * Adds a column to the table for displaying values of an enumeration.
+     *
+     * An enumeration defines a fixed set of values, each with a label and an optional icon and tooltip.
+     */
+    addEnumColumn(descriptor: SciEnumColumnDescriptor<T>): this;
+    /**
+     * Adds a column to the table for displaying icons.
+     *
+     * An icon column is a standardized enum column for displaying icons. If configured with only a header icon and no label,
+     * it defaults to non-resizable and sizes to fit the icon.
+     */
+    addIconColumn(descriptor: SciIconColumnDescriptor<T>): this;
+    /**
+     * Adds a column to the table for displaying custom content using a component.
+     */
     addComponentColumn(descriptor: SciComponentColumnDescriptor<T>): this;
+    /**
+     * Adds a column to the table for displaying custom content using a template.
+     */
     addTemplateColumn(descriptor: SciTemplateColumnDescriptor<T>): this;
 }
 interface SciTableColumnDescriptor {
     name?: `column:${string}`;
-    header?: Translatable;
+    header?: SciColumnHeaderLike;
     resizable?: boolean;
     /**
      * Preferred column size.
@@ -261,8 +645,22 @@ interface SciTableColumnDescriptor {
      */
     minWidth?: number;
 }
+/**
+ * Configures a table column for displaying text.
+ */
 interface SciStringColumnDescriptor<T> extends SciTableColumnDescriptor {
-    value: (item: T) => MaybeSignal<string | undefined>;
+    /**
+     * Specifies the text to display for an item.
+     *
+     * Can be text or a translation key. 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}.
+     */
+    value: (item: T) => MaybeSignal<Translatable | undefined>;
     sortable?: boolean | {
         comparator: SciTableColumnSortComparatorFn<T, string>;
     };
@@ -275,7 +673,11 @@ interface SciStringColumnDescriptor<T> extends SciTableColumnDescriptor {
  */
 interface SciNumberColumnDescriptor<T> extends SciTableColumnDescriptor {
     /**
-     * Specifies the number to display in this column.
+     * Specifies the number to display for an item.
+     *
+     * The function:
+     * - Can call `inject` to get required dependencies.
+     * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
      */
     value: (item: T) => MaybeSignal<number | undefined>;
     /**
@@ -366,9 +768,28 @@ interface SciNumberColumnDescriptor<T> extends SciTableColumnDescriptor {
      */
     locale?: MaybeSignal<string>;
 }
+/**
+ * Configures a table column for displaying boolean values.
+ */
 interface SciBooleanColumnDescriptor<T> extends SciTableColumnDescriptor {
+    /**
+     * Specifies the boolean value to display for an item.
+     *
+     * Cells display `true` as a checkmark and `false` as an 'X'. Filter options are labeled as 'Yes'/'No'.
+     * For custom display or filter options, use {@link addEnumColumn} instead.
+     *
+     * The function:
+     * - Can call `inject` to get required dependencies.
+     * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
+     */
     value: (item: T) => MaybeSignal<boolean | undefined>;
+    /**
+     * Controls whether the user can sort this column. Defaults to `true`.
+     */
     sortable?: boolean;
+    /**
+     * Controls whether the user can filter this column. Defaults to `true`.
+     */
     filterable?: boolean;
 }
 /**
@@ -376,9 +797,13 @@ interface SciBooleanColumnDescriptor<T> extends SciTableColumnDescriptor {
  */
 interface SciDateColumnDescriptor<T> extends SciTableColumnDescriptor {
     /**
-     * Specifies the date value to display in this column.
+     * Specifies the date value to display for an item.
      *
      * Can be an ISO 8601 date/time string (e.g., `2026-10-06`, `2026-10-06T14:30:15Z`, `T14:30:15`), milliseconds since the UTC epoch, or a `Date` object.
+     *
+     * The function:
+     * - Can call `inject` to get required dependencies.
+     * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
      */
     value: (item: T) => MaybeSignal<SciDateLike | undefined>;
     /**
@@ -420,6 +845,94 @@ interface SciDateColumnDescriptor<T> extends SciTableColumnDescriptor {
      */
     timezone?: string;
 }
+/**
+ * Configures a table column for displaying values of an enumeration.
+ *
+ * An enumeration defines a fixed set of values, each with a label and an optional icon and tooltip.
+ */
+interface SciEnumColumnDescriptor<T = unknown> extends SciTableColumnDescriptor {
+    /**
+     * Specifies the enumeration value to display for an item. Must be a value of an entry defined in {@link values}.
+     *
+     * The function:
+     * - Can call `inject` to get required dependencies.
+     * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
+     */
+    value: (item: T) => MaybeSignal<SciEnumValueLike | undefined>;
+    /**
+     * Specifies the enumeration entries.
+     *
+     * The array order determines the sort order of the enumeration.
+     */
+    values: MaybeSignal<SciEnumColumnValues>;
+    /**
+     * 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 if using a custom format.
+     */
+    format?: {
+        /**
+         * Controls whether to display the icon in cells.
+         */
+        icon?: true;
+        /**
+         * Controls whether to display the label in cells.
+         */
+        label?: true;
+        /**
+         * Configures the display of entries in the column filter menu.
+         */
+        filter?: {
+            /**
+             * Controls whether to display the icon in the column filter menu.
+             */
+            icon?: true;
+        };
+    };
+    /**
+     * Controls whether the user can sort this column. Defaults to `true`.
+     */
+    sortable?: boolean;
+    /**
+     * Controls whether the user can filter this column. Defaults to `multi`.
+     */
+    filterable?: 'single' | 'multi' | false;
+}
+/**
+ * Configures a table column for displaying icons.
+ *
+ * An icon column is a standardized enum column for displaying icons. If configured with only a header icon and no label,
+ * it defaults to non-resizable and sizes to fit the icon.
+ */
+interface SciIconColumnDescriptor<T = unknown> extends SciTableColumnDescriptor {
+    /**
+     * Specifies the icon to display for an item.
+     *
+     * 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.
+     *
+     * The function:
+     * - Can call `inject` to get required dependencies.
+     * - Can call `toSignal` to convert an {@link Observable} to a {@link Signal}.
+     */
+    value: (item: T) => MaybeSignal<string | number | boolean | undefined>;
+    /**
+     * Specifies the icons displayed in this column.
+     *
+     * The array order determines the sort order.
+     */
+    values: MaybeSignal<SciIconColumnValues>;
+    /**
+     * Controls whether the user can sort this column. Defaults to `true`.
+     */
+    sortable?: boolean;
+    /**
+     * Controls whether the user can filter this column. Defaults to `multi`.
+     */
+    filterable?: 'single' | 'multi' | false;
+}
 interface SciComponentColumnDescriptor<T> extends SciTableColumnDescriptor {
     component: (item: T) => SciComponentDescriptor;
     sortable?: boolean | {
@@ -460,78 +973,173 @@ 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}.
+ * Represents the internal value of {@link SciEnumColumn}.
  */
-interface SciDateValue {
+interface SciEnumValue {
+    value: SciEnumValueLike;
+    /** localized text */
+    label: string;
+    /** localized tooltip */
+    tooltip?: string;
+    icon?: string;
+}
+
+/**
+ * Represents supported column types of {@link SciTableComponent}.
+ */
+type SciTableColumnType = 'string' | 'number' | 'boolean' | 'date' | 'icon' | 'enum' | 'component' | 'template';
+/**
+ * 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> {
     /**
-     * Full ISO 8601 date/time string.
+     * 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
      */
-    isoString: string;
+    datasource: Signal<T[]> | SciTableDatasourceProvider<T, ID>;
     /**
-     * Milliseconds since UTC epoch.
+     * 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.
      */
-    millis: number;
+    columns: SciTableColumnFactoryFn<T>;
     /**
-     * Human-readable formatted date and time string.
+     * Controls whether the user can sort rows by clicking column headers. Defaults to `true`.
      */
-    formatted: string;
-}
-
-type SciTableColumnType = 'string' | 'number' | 'boolean' | 'date' | 'component' | 'template';
-type SciTableRowActionFactoryFn<T> = (toolbar: SciToolbarFactory, item: T, index: number) => void;
-interface SciTableDescriptor<T> {
-    datasource: Signal<T[]>;
+    sortable?: boolean;
     /**
-     * @docs-private Not public API. For internal use only.
-     * @experimental since 22.3.0; API and behavior may change in any version without notice.
+     * Controls whether the user can resize columns. Defaults to `true`.
      */
-    ɵdatasource?: Signal<T[]> | SciTableDataLoaderFn<T>;
-    columns: SciTableColumnFactoryFn<T>;
-    sortable?: boolean;
     resizable?: boolean;
+    /**
+     * Controls whether the column filters are displayed. Defaults to `false`.
+     *
+     * Does not affect filtering via {@link SciTable.filter}.
+     */
     filterable?: boolean;
-    selectable?: false | 'single' | 'multi';
+    /**
+     * 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;
     /**
      * Configures actions to show when hovering over a row.
      *
-     * Example usage:
+     * @example
      * ```ts
+     * import {table} from '@scion/components/table';
+     *
      * table({
      *   datasource: data,
+     *   columns: table => ...,
      *   rowActions: (toolbar, item) => toolbar.addToolbarButton({
      *     icon: 'delete',
      *     onSelect: () => ...,
      *   }),
-     *   columns: table => ...,
      * });
      * ```
+     *
+     * 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.
      */
     rowActions?: SciTableRowActionFactoryFn<T>;
     /**
-     * Adds bindings to a table row, enabling custom styling, HTML attributes, and CSS classes.
+     * Configures row bindings for table rows.
      *
-     * Example usage:
+     * Row bindings enable associating metadata and icons with a row. Metadata includes CSS shadow parts, CSS classes, and HTML attributes.
+     *
+     * @example
      * ```ts
+     * import {table} from '@scion/components/table';
+     *
      * table({
      *   datasource: data,
+     *   columns: table => ...,
      *   rowBindings: (bindings, item, index) => bindings
+     *     .addIconBinding('account_circle')
      *     .addPartBinding(index % 2 === 0 ? 'row:even' : 'row:odd')
      *     .addAttributeBinding('data-id', item.id)
      *     .addClassBinding(item.inactive ? 'inactive' : undefined),
-     *   columns: table => ...,
      * });
      * ```
      *
+     * Part attribute bindings make a row 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-table::part(row\:even row\:not\:selected) {
      *   background-color: lightgray;
      * }
      * ```
+     *
+     * The function:
+     * - Is called per item with a {@link SciTableRowBindingFactory} 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 row bindings.
+     * @param item - Item associated with the row.
+     * @param index - Index of the row, zero-based.
      */
     rowBindings?: SciTableRowBindingFactoryFn<T>;
     /**
@@ -542,33 +1150,106 @@ 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;
     name: `column:${string}`;
-    header: Signal<string>;
+    header: {
+        icon: string | undefined;
+        label: Signal<string> | undefined;
+        tooltip: Signal<string> | undefined;
+    };
     sortable: Signal<boolean>;
     filterable: Signal<boolean>;
     resizable: Signal<boolean>;
@@ -586,54 +1267,56 @@ interface SciTableColumn<T = unknown, VALUE = unknown, FILTER = VALUE> {
 interface SciStringColumn<T = unknown> extends SciTableColumn<T, string> {
     type: 'string';
     value: (item: T) => Signal<string | undefined>;
-    compare: SciTableColumnSortComparatorFn<T, string>;
-    matches: SciTableColumnFilterMatcherFn<T, string>;
 }
 interface SciNumberColumn<T = unknown> extends SciTableColumn<T, number> {
     type: 'number';
     value: (item: T) => Signal<number | undefined>;
-    compare: SciTableColumnSortComparatorFn<T, number>;
-    matches: SciTableColumnFilterMatcherFn<T, number>;
     format: Signal<Intl.NumberFormat>;
 }
-interface SciBooleanColumn<T = unknown> extends SciTableColumn<T, boolean> {
-    type: 'boolean';
-    value: (item: T) => Signal<boolean | undefined>;
-    compare: SciTableColumnSortComparatorFn<T, boolean>;
-    matches: SciTableColumnFilterMatcherFn<T, boolean>;
-}
 interface SciDateColumn<T = unknown> extends SciTableColumn<T, SciDateValue, string> {
     type: 'date';
     value: (item: T) => Signal<SciDateValue | undefined>;
-    compare: SciTableColumnSortComparatorFn<T, SciDateValue>;
-    matches: SciTableColumnFilterMatcherFn<T, SciDateValue, string>;
+}
+interface SciEnumColumn<T = unknown> extends Omit<SciTableColumn<T, SciEnumValue, SciEnumValueLike[] | string>, 'filterable'> {
+    type: 'enum';
+    value: (item: T) => Signal<SciEnumValue | undefined>;
+    filterable: Signal<'single' | 'multi' | false>;
+    enumeration: Signal<SciEnumColumnValues>;
+    format: {
+        icon: boolean;
+        label: boolean;
+        filter: {
+            icon: boolean;
+        };
+    };
+    referenceType: SciTableColumnType | undefined;
 }
 interface SciComponentColumn<T = unknown> extends SciTableColumn<T, void, string> {
     type: 'component';
     component: (item: T) => SciComponentDescriptor;
-    compare: SciTableColumnSortComparatorFn<T, void>;
-    matches: SciTableColumnFilterMatcherFn<T, void, string>;
 }
 interface SciTemplateColumn<T = unknown> extends SciTableColumn<T, void, string> {
     type: 'template';
     template: (item: T) => SciTemplateDescriptor;
-    compare: SciTableColumnSortComparatorFn<T, void>;
-    matches: SciTableColumnFilterMatcherFn<T, void, string>;
 }
-type SciTableColumnLike<T = unknown> = SciStringColumn<T> | SciNumberColumn<T> | SciBooleanColumn<T> | SciDateColumn<T> | SciComponentColumn<T> | SciTemplateColumn<T>;
+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';
@@ -645,16 +1328,16 @@ interface SciNumberCell {
     column: SciNumberColumn;
     value: Signal<number | undefined>;
 }
-interface SciBooleanCell {
-    type: 'boolean';
-    column: SciBooleanColumn;
-    value: Signal<boolean | undefined>;
-}
 interface SciDateCell {
     type: 'date';
     column: SciDateColumn;
     value: Signal<SciDateValue | undefined>;
 }
+interface SciEnumCell {
+    type: 'enum';
+    column: SciEnumColumn;
+    value: Signal<SciEnumValue | undefined>;
+}
 interface SciComponentCell {
     type: 'component';
     column: SciComponentColumn;
@@ -665,15 +1348,25 @@ interface SciTemplateCell {
     column: SciTemplateColumn;
     template: SciTemplateDescriptor;
 }
-type SciTableCellLike = SciStringCell | SciNumberCell | SciBooleanCell | SciDateCell | SciComponentCell | SciTemplateCell;
+type SciTableCellLike = SciStringCell | SciNumberCell | SciDateCell | SciEnumCell | SciComponentCell | SciTemplateCell;
 interface SciTableCellContext<T = unknown, VALUE = unknown> {
     item: T;
     value: VALUE;
 }
+/**
+ * Signature of a function to contribute row actions.
+ *
+ * Called per item with a {@link SciToolbarFactory} to contribute actions.
+ *
+ * The function:
+ * - Runs in a reactive context and re-evaluates when tracked signals change.
+ * - Can call `inject` to get required dependencies.
+ */
+type SciTableRowActionFactoryFn<T> = (toolbar: SciToolbarFactory, item: T, index: number) => void;
 /**
  * Represents an event emitted by {@link SciTableComponent}.
  */
-interface SciTableEvent<T> {
+interface SciTableEvent<ID> {
     /**
      * The native browser event (`MouseEvent` or `KeyboardEvent`) that triggered the action.
      */
@@ -681,191 +1374,329 @@ interface SciTableEvent<T> {
     /**
      * The items associated with the action.
      */
-    items: T[];
+    items: ID[];
 }
 /**
- * Represents an ISO 8601 date/time string, milliseconds since the UTC epoch, or a `Date` object.
+ * Represents the header of a table column, defined as a {@link Translatable} or an object with an optional icon, label, and tooltip.
+ *
+ * The label can be text or a translation key. 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}.
+ *
+ * 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.
+ */
+type SciColumnHeaderLike = Translatable | {
+    icon?: string;
+    label?: Translatable;
+    tooltip?: Translatable;
+};
+/**
+ * An ISO 8601 date/time string, milliseconds since the UTC epoch, or a {@link Date} object.
  */
 type SciDateLike = string | number | Date;
+/**
+ * Supported data types for enumeration values used in an enum column.
+ */
+type SciEnumValueLike = string | number | boolean;
+/**
+ * Defines the enumeration entries of an enum column.
+ *
+ * The array order determines the sort order of the enumeration.
+ *
+ * A label can be text or a translation key. 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}.
+ *
+ * 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.
+ */
+type SciEnumColumnValues = {
+    value: SciEnumValueLike;
+    label: Translatable;
+    icon?: string;
+    tooltip?: Translatable | null;
+}[];
+/**
+ * Defines icons of an icon column.
+ *
+ * The array order determines the sort order.
+ *
+ * A label can be text or a translation key. 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}.
+ *
+ * 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.
+ */
+type SciIconColumnValues = {
+    value: string | number | boolean;
+    label: Translatable;
+    icon: string;
+    tooltip?: Translatable | null;
+}[];
 
 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 | 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.
      */
@@ -873,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>;
-}
-
-/**
- * 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;
+    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>;
 }
-/**
- * Defaults to localStorage persistence.
- * @param storage
- */
-declare function provideTableStorage(storage: Type<SciTableStorage>): EnvironmentProviders;
 
-export { SciTableComponent, provideTableRowBinding, provideTableStorage, table, ɵillegaldatasource };
-export type { SciBooleanColumnDescriptor, SciComponentColumnDescriptor, SciDateColumnDescriptor, SciDateLike, 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 };