@scion/components 22.4.0 → 22.6.0

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

@@ -9,7 +9,7 @@ type MaybeAsync<T> = T | Promise<T> | Observable<T>;
 
 interface SciTableColumnFilter {
     columnName: `column:${string}`;
-    text: string | boolean | number;
+    text: string | number | boolean | SciEnumValueLike | SciEnumValueLike[];
 }
 interface SciTableSortCriterion {
     columnName: `column:${string}`;
@@ -47,61 +47,355 @@ type SciTableDataLoaderFn<T> = (request: SciTablePageRequest) => MaybeAsync<SciT
  */
 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;
+/**
+ * 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.
+ */
+declare function provideTableRowBinding<T = unknown>(bindings: SciTableRowBindingFactoryFn<T>): Provider[];
+/**
+ * Signature of a function to configure row bindings.
+ *
+ * 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.
+ */
 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 => ...,
      * });
      * ```
      *
      * ```scss
-     * sci-table::part(row\:even) {
+     * sci-table::part(row\:even row\:not\:selected) {
      *   background-color: lightgray;
      * }
      *
-     * sci-table::part(row\:active) {
+     * sci-table::part(row\:active row\:not\:selected) {
      *   background-color: green;
      * }
      * ```
      */
     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;
 }
 interface SciTableRowBindings {
-    cssClass: Signal<string[]>;
+    icons: Signal<string[]>;
+    parts: Signal<`row:${string}`[]>;
     attributes: Signal<{
         [name: string]: unknown;
     }>;
-    part: Signal<`row:${string}`[]>;
+    classes: Signal<string[]>;
 }
 
 interface SciTableColumnFactory<T> {
-    addStringColumn(header: Translatable, value: (item: T) => string): this;
-    addStringColumn(value: (item: T) => string): 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;
-    addBooleanColumn(header: Translatable, value: (item: T) => boolean): this;
-    addBooleanColumn(value: (item: T) => boolean): this;
-    addBooleanColumn(descriptor: SciBooleanColumnDescriptor<T>): this;
-    addNumberColumn(header: Translatable, value: (item: T) => number): this;
-    addNumberColumn(value: (item: T) => number): this;
+    /**
+     * 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.
+     *
+     * Tabular figures include digits (0-9), basic math symbols, and punctuations/spaces.
+     *
+     * To disable tabular figures using CSS:
+     *
+     * ```scss
+     * // Disable tabular figures for all number columns.
+     * sci-table::part(column\:number) {
+     *   font-variant-numeric: normal;
+     * }
+     *
+     * // Disable tabular figures for a specific column (replace `column-name` with the column's name).
+     * sci-table::part(column\:column-name) {
+     *   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: SciColumnHeaderLike, value: (item: T) => MaybeSignal<number | undefined>): this;
+    /**
+     * 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.
+     *
+     * Tabular figures include digits (0-9), basic math symbols, and punctuations/spaces.
+     *
+     * To disable tabular figures using CSS:
+     *
+     * ```scss
+     * // Disable tabular figures for all number columns.
+     * sci-table::part(column\:number) {
+     *   font-variant-numeric: normal;
+     * }
+     *
+     * // Disable tabular figures for a specific column (replace `column-name` with the column's name).
+     * sci-table::part(column\:column-name) {
+     *   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 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.
+     *
+     * Tabular figures include digits (0-9), basic math symbols, and punctuations/spaces.
+     *
+     * To disable tabular figures using CSS:
+     *
+     * ```scss
+     * // Disable tabular figures for all number columns.
+     * sci-table::part(column\:number) {
+     *   font-variant-numeric: normal;
+     * }
+     *
+     * // Disable tabular figures for a specific column (replace `column-name` with the column's name).
+     * sci-table::part(column\:column-name) {
+     *   font-variant-numeric: normal;
+     * }
+     * ```
+     */
     addNumberColumn(descriptor: SciNumberColumnDescriptor<T>): 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 column to the table for displaying dates, times, or both.
+     *
+     * Supports ISO 8601 date/time strings, milliseconds since the UTC epoch, and `Date` objects.
+     *
+     * Dates are formatted using `mediumDate`, or as specified in {@link DATE_PIPE_DEFAULT_OPTIONS}.
+     *
+     * ### Tabular Figures
+     * Dates are rendered using tabular (fixed-width) figures to align digits vertically in fonts with varying character widths. Has no effect on monospaced fonts.
+     *
+     * Tabular figures include digits (0-9), basic math symbols, and punctuations/spaces.
+     *
+     * To disable tabular figures using CSS:
+     *
+     * ```scss
+     * // Disable tabular figures for all date columns.
+     * sci-table::part(column\:date) {
+     *   font-variant-numeric: normal;
+     * }
+     *
+     * // Disable tabular figures for a specific column (replace `column-name` with the column's name).
+     * sci-table::part(column\:column-name) {
+     *   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: SciColumnHeaderLike, value: (item: T) => MaybeSignal<SciDateLike | undefined>): this;
+    /**
+     * 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.
+     *
+     * Dates are formatted using `mediumDate`, or as specified in {@link DATE_PIPE_DEFAULT_OPTIONS}.
+     *
+     * ### Tabular Figures
+     * Dates are rendered using tabular (fixed-width) figures to align digits vertically in fonts with varying character widths. Has no effect on monospaced fonts.
+     *
+     * Tabular figures include digits (0-9), basic math symbols, and punctuations/spaces.
+     *
+     * To disable tabular figures using CSS:
+     *
+     * ```scss
+     * // Disable tabular figures for all date columns.
+     * sci-table::part(column\:date) {
+     *   font-variant-numeric: normal;
+     * }
+     *
+     * // Disable tabular figures for a specific column (replace `column-name` with the column's name).
+     * sci-table::part(column\:column-name) {
+     *   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 column to the table for displaying dates, times, or both.
+     *
+     * Supports ISO 8601 date/time strings, milliseconds since the UTC epoch, and `Date` objects.
+     *
+     * Dates are formatted as specified in {@link SciDateColumnDescriptor.format}, {@link SciDateColumnDescriptor.locale}, and {@link SciDateColumnDescriptor.timezone}.
+     *
+     * ### Tabular Figures
+     * Dates are rendered using tabular (fixed-width) figures to align digits vertically in fonts with varying character widths. Has no effect on monospaced fonts.
+     *
+     * Tabular figures include digits (0-9), basic math symbols, and punctuations/spaces.
+     *
+     * To disable tabular figures using CSS:
+     *
+     * ```scss
+     * // Disable tabular figures for all date columns.
+     * sci-table::part(column\:date) {
+     *   font-variant-numeric: normal;
+     * }
+     *
+     * // Disable tabular figures for a specific column (replace `column-name` with the column's name).
+     * sci-table::part(column\:column-name) {
+     *   font-variant-numeric: normal;
+     * }
+     * ```
+     */
+    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.
@@ -114,8 +408,22 @@ interface SciTableColumnDescriptor {
      */
     minWidth?: number;
 }
+/**
+ * Configures a table column for displaying text.
+ */
 interface SciStringColumnDescriptor<T> extends SciTableColumnDescriptor {
-    value: (item: T) => MaybeSignal<string>;
+    /**
+     * 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>;
     };
@@ -123,15 +431,270 @@ interface SciStringColumnDescriptor<T> extends SciTableColumnDescriptor {
         matcher: SciTableColumnFilterMatcherFn<T, string>;
     };
 }
+/**
+ * Configures a table column for displaying numeric values.
+ */
 interface SciNumberColumnDescriptor<T> extends SciTableColumnDescriptor {
-    value: (item: T) => MaybeSignal<number>;
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * Specifies how to format numbers. Defaults to standard number formatting based on the active {@link locale}.
+     *
+     * ##### Grouping Separators
+     * Disable grouping separators (such as thousands separators) by setting {@link Intl.NumberFormatOptions.useGrouping} to `false`.
+     *
+     * ```ts
+     * import {table} from '@scion/components/table';
+     *
+     * table(data, table => table.addNumberColumn({
+     *   value: item => item.numericValue,
+     *   format: {useGrouping: false},
+     * }));
+     * ```
+     *
+     * ##### Fraction Digits
+     * Control the number of decimal places using the {@link Intl.NumberFormatOptions.minimumFractionDigits} and {@link Intl.NumberFormatOptions.maximumFractionDigits} properties.
+     *
+     * ```ts
+     * import {table} from '@scion/components/table';
+     *
+     * table(data, table => table.addNumberColumn({
+     *   value: item => item.numericValue,
+     *   format: {
+     *     minimumFractionDigits: 2,
+     *     maximumFractionDigits: 2,
+     *   },
+     * }));
+     * ```
+     *
+     * ##### Currency
+     * To render numbers as currency, set {@link Intl.NumberFormatOptions.style} to `currency` and specify the currency code.
+     *
+     * The currency code defaults to {@link DEFAULT_CURRENCY_CODE}, or `USD` if not provided.
+     * To change the currency, set the {@link Intl.NumberFormatOptions.currency} property to a different [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code (e.g., `EUR`, `CHF`, `GBP`).
+     *
+     * ```ts
+     * import {table} from '@scion/components/table';
+     *
+     * table(data, table => table.addNumberColumn({
+     *   value: item => item.numericValue,
+     *   format: {
+     *     style: 'currency',
+     *     currency: 'EUR',
+     *   },
+     * }));
+     * ```
+     *
+     * ##### Unit
+     * To render numbers with a specific unit (e.g., `kilogram`, `kilometer`, `kilometer-per-hour`, or `hour`), set {@link Intl.NumberFormatOptions.style} to `unit`
+     * and specify the unit from [Supported Unit Identifiers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf#supported_unit_identifiers).
+     *
+     * ```ts
+     * import {table} from '@scion/components/table';
+     *
+     * table(data, table => table.addNumberColumn({
+     *   value: item => item.numericValue,
+     *   format: {
+     *     style: 'unit',
+     *     unit: 'kilometer-per-hour',
+     *   },
+     * }));
+     * ```
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options
+     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/supportedValuesOf#supported_unit_identifiers
+     * @see https://en.wikipedia.org/wiki/ISO_4217
+     */
+    format?: Intl.NumberFormatOptions;
+    /**
+     * Specifies the locale used to localize numbers.
+     *
+     * The locale determines group sizing and separators, decimal point characters, and other locale-specific formatting rules.
+     *
+     * Defaults to {@link SCI_LOCALE}, which initializes from {@link LOCALE_ID} (defaulting to `en-US`).
+     *
+     * See {@link SCI_LOCALE} for details on how to change the locale at runtime.
+     */
+    locale?: MaybeSignal<string>;
 }
+/**
+ * Configures a table column for displaying boolean values.
+ */
 interface SciBooleanColumnDescriptor<T> extends SciTableColumnDescriptor {
-    value: (item: T) => MaybeSignal<boolean>;
+    /**
+     * 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;
+}
+/**
+ * Configures a table column for displaying dates.
+ */
+interface SciDateColumnDescriptor<T> extends SciTableColumnDescriptor {
+    /**
+     * 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>;
+    /**
+     * 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;
+    /**
+     * Specifies how to format dates. Defaults to the format configured in {@link DATE_PIPE_DEFAULT_OPTIONS}, or `mediumDate` if not provided.
+     *
+     * Accepts a predefined Angular date format (e.g., `mediumDate`, `mediumTime`) or a custom format (e.g., `dd.MM.yyyy`, `HH:mm`).
+     * Formatting may vary depending on the active {@link locale}.
+     *
+     * Use a time-only format to display only the time component.
+     *
+     * @see https://angular.dev/api/common/DatePipe#pre-defined-format-options
+     * @see https://angular.dev/api/common/DatePipe#custom-format-options
+     */
+    format?: 'shortDate' | 'mediumDate' | 'longDate' | 'fullDate' | 'shortTime' | 'mediumTime' | 'longTime' | 'fullTime' | 'short' | 'medium' | 'long' | 'full' | string;
+    /**
+     * Specifies the locale used to localize dates.
+     *
+     * The locale determines date/time patterns, month and weekday names, AM/PM indicators, and related formatting symbols.
+     *
+     * Defaults to {@link SCI_LOCALE}, which initializes from {@link LOCALE_ID} (defaulting to `en-US`).
+     *
+     * See {@link SCI_LOCALE} for details on how to change the locale at runtime.
+     */
+    locale?: MaybeSignal<string>;
+    /**
+     * Specifies the timezone in which to render dates.
+     *
+     * Must be a UTC/GMT offset (e.g., `+0430` or `-0500`).
+     *
+     * Defaults to the timezone configured in {@link DATE_PIPE_DEFAULT_OPTIONS}, or the user's system timezone if not provided.
+     */
+    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 when 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;
@@ -172,8 +735,40 @@ type SciTableColumnSortComparatorFn<T = unknown, VALUE = unknown> = (a: SciTable
  */
 type SciTableColumnFilterMatcherFn<T = unknown, VALUE = unknown, FILTER = VALUE> = (filter: FILTER, context: SciTableCellContext<T, VALUE>) => boolean;
 
-type SciTableColumnType = 'string' | 'number' | 'boolean' | 'component' | 'template';
-type SciTableRowActionFactoryFn<T> = (toolbar: SciToolbarFactory, item: T, index: number) => void;
+/**
+ * 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}.
+ */
+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';
 interface SciTableDescriptor<T> {
     datasource: Signal<T[]>;
     /**
@@ -185,7 +780,7 @@ interface SciTableDescriptor<T> {
     sortable?: boolean;
     resizable?: boolean;
     filterable?: boolean;
-    selectable?: false | 'single' | 'multi';
+    selectable?: 'single' | 'multi' | false;
     showHeader?: boolean;
     /**
      * Defaults to false.
@@ -194,39 +789,62 @@ interface SciTableDescriptor<T> {
     /**
      * 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) {
+     * 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>;
     /**
@@ -260,14 +878,14 @@ interface SciTable<T> {
      */
     filter(text: string | null): void;
 }
-interface SciTableCellContext<T = unknown, VALUE = unknown> {
-    item: T;
-    value: VALUE;
-}
 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>;
@@ -282,37 +900,42 @@ interface SciTableColumn<T = unknown, VALUE = unknown, FILTER = VALUE> {
     compare: SciTableColumnSortComparatorFn<T, VALUE>;
     matches: SciTableColumnFilterMatcherFn<T, VALUE, FILTER>;
 }
-interface SciStringColumn<T> extends SciTableColumn<T, string> {
+interface SciStringColumn<T = unknown> extends SciTableColumn<T, string> {
     type: 'string';
-    value: (item: T) => MaybeSignal<string>;
-    compare: SciTableColumnSortComparatorFn<T, string>;
-    matches: SciTableColumnFilterMatcherFn<T, string>;
+    value: (item: T) => Signal<string | undefined>;
 }
-interface SciNumberColumn<T> extends SciTableColumn<T, number> {
+interface SciNumberColumn<T = unknown> extends SciTableColumn<T, number> {
     type: 'number';
-    value: (item: T) => MaybeSignal<number>;
-    compare: SciTableColumnSortComparatorFn<T, number>;
-    matches: SciTableColumnFilterMatcherFn<T, number>;
+    value: (item: T) => Signal<number | undefined>;
+    format: Signal<Intl.NumberFormat>;
 }
-interface SciBooleanColumn<T> extends SciTableColumn<T, boolean> {
-    type: 'boolean';
-    value: (item: T) => MaybeSignal<boolean>;
-    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>;
 }
-interface SciComponentColumn<T> extends SciTableColumn<T, void, 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> extends SciTableColumn<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> | SciComponentColumn<T> | SciTemplateColumn<T>;
+type SciTableColumnLike<T = unknown> = SciStringColumn<T> | SciNumberColumn<T> | SciDateColumn<T> | SciEnumColumn<T> | SciComponentColumn<T> | SciTemplateColumn<T>;
 /**
  * Mapped row, used as display state.
  */
@@ -329,30 +952,49 @@ interface SciTableRow<T> {
 }
 interface SciStringCell {
     type: 'string';
-    column: SciTableColumnLike;
-    value: Signal<string>;
+    column: SciStringColumn;
+    value: Signal<string | undefined>;
 }
 interface SciNumberCell {
     type: 'number';
-    column: SciTableColumnLike;
-    value: Signal<number>;
+    column: SciNumberColumn;
+    value: Signal<number | undefined>;
+}
+interface SciDateCell {
+    type: 'date';
+    column: SciDateColumn;
+    value: Signal<SciDateValue | undefined>;
 }
-interface SciBooleanCell {
-    type: 'boolean';
-    column: SciTableColumnLike;
-    value: Signal<boolean>;
+interface SciEnumCell {
+    type: 'enum';
+    column: SciEnumColumn;
+    value: Signal<SciEnumValue | undefined>;
 }
 interface SciComponentCell {
     type: 'component';
-    column: SciTableColumnLike;
+    column: SciComponentColumn;
     component: SciComponentDescriptor;
 }
 interface SciTemplateCell {
     type: 'template';
-    column: SciTableColumnLike;
+    column: SciTemplateColumn;
     template: SciTemplateDescriptor;
 }
-type SciTableCellLike = SciStringCell | SciNumberCell | SciBooleanCell | 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}.
  */
@@ -366,6 +1008,66 @@ interface SciTableEvent<T> {
      */
     items: T[];
 }
+/**
+ * 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. */
@@ -406,6 +1108,7 @@ declare class ɵSciTable<T = unknown> implements SciTable<T> {
     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>;
@@ -467,7 +1170,7 @@ declare class ɵSciTable<T = unknown> implements SciTable<T> {
      * Applies a filter, either via global filter or on a specific column.
      */
     filter(text: string | null): void;
-    filter(text: string | number | boolean | null, options: {
+    filter(text: string | number | boolean | SciEnumValueLike | SciEnumValueLike[] | null, options: {
         columnName: `column:${string}`;
     }): void;
     updateSelectedItems(updateFn: (ids: Map<unknown, T>) => Map<unknown, T>): void;
@@ -592,4 +1295,4 @@ interface SciTableStorage {
 declare function provideTableStorage(storage: Type<SciTableStorage>): EnvironmentProviders;
 
 export { SciTableComponent, provideTableRowBinding, provideTableStorage, table, ɵillegaldatasource };
-export type { SciBooleanColumnDescriptor, SciComponentColumnDescriptor, SciNumberColumnDescriptor, SciStringColumnDescriptor, SciTable, SciTableCellContext, SciTableColumnDescriptor, SciTableColumnFactory, SciTableColumnFactoryFn, SciTableColumnFilter, SciTableColumnFilterMatcherFn, SciTableColumnSortComparatorFn, SciTableColumnType, SciTableDataLoaderFn, SciTableDescriptor, SciTableEvent, SciTablePageRequest, SciTablePageResponse, SciTableRowActionFactoryFn, SciTableRowBindingFactory, SciTableRowBindingFactoryFn, SciTableSortCriterion, SciTableStorage, SciTemplateColumnDescriptor };
+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 };