@scion/components 22.3.0 → 22.5.0

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

@@ -67,11 +67,11 @@ interface SciTableRowBindingFactory {
      * ```
      *
      * ```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;
      * }
      * ```
@@ -86,7 +86,398 @@ interface SciTableRowBindings {
     part: Signal<`row:${string}`[]>;
 }
 
-type SciTableColumnType = 'string' | 'number' | 'boolean' | 'component' | 'template';
+interface SciTableColumnFactory<T> {
+    addStringColumn(header: Translatable, value: (item: T) => MaybeSignal<string | undefined>): this;
+    addStringColumn(value: (item: T) => MaybeSignal<string | undefined>): this;
+    addStringColumn(descriptor: SciStringColumnDescriptor<T>): this;
+    /**
+     * Adds a number 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(header: Translatable, value: (item: T) => MaybeSignal<number | undefined>): this;
+    /**
+     * Adds a number 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(value: (item: T) => MaybeSignal<number | undefined>): this;
+    /**
+     * Adds a number 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;
+    addBooleanColumn(header: Translatable, value: (item: T) => MaybeSignal<boolean | undefined>): this;
+    addBooleanColumn(value: (item: T) => MaybeSignal<boolean | undefined>): this;
+    addBooleanColumn(descriptor: SciBooleanColumnDescriptor<T>): this;
+    /**
+     * Adds a temporal 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;
+     * }
+     * ```
+     */
+    addDateColumn(header: Translatable, value: (item: T) => MaybeSignal<SciDateLike | undefined>): this;
+    /**
+     * Adds a temporal 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;
+     * }
+     * ```
+     */
+    addDateColumn(value: (item: T) => MaybeSignal<SciDateLike | undefined>): this;
+    /**
+     * Adds a temporal 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;
+    addComponentColumn(descriptor: SciComponentColumnDescriptor<T>): this;
+    addTemplateColumn(descriptor: SciTemplateColumnDescriptor<T>): this;
+}
+interface SciTableColumnDescriptor {
+    name?: `column:${string}`;
+    header?: Translatable;
+    resizable?: boolean;
+    /**
+     * Preferred column size.
+     * Value which can be used inside `grid-template-columns` definition. Defaults to 1fr.
+     * Examples: `1fr`, `max-content`, `100px`.
+     */
+    width?: string;
+    /**
+     * Min column width in px. Defaults to 100.
+     */
+    minWidth?: number;
+}
+interface SciStringColumnDescriptor<T> extends SciTableColumnDescriptor {
+    value: (item: T) => MaybeSignal<string | undefined>;
+    sortable?: boolean | {
+        comparator: SciTableColumnSortComparatorFn<T, string>;
+    };
+    filterable?: boolean | {
+        matcher: SciTableColumnFilterMatcherFn<T, string>;
+    };
+}
+/**
+ * Configures a table column for displaying numeric values.
+ */
+interface SciNumberColumnDescriptor<T> extends SciTableColumnDescriptor {
+    /**
+     * Specifies the number to display in this column.
+     */
+    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>;
+}
+interface SciBooleanColumnDescriptor<T> extends SciTableColumnDescriptor {
+    value: (item: T) => MaybeSignal<boolean | undefined>;
+    sortable?: boolean;
+    filterable?: boolean;
+}
+/**
+ * Configures a table column for displaying dates.
+ */
+interface SciDateColumnDescriptor<T> extends SciTableColumnDescriptor {
+    /**
+     * Specifies the date value to display in this column.
+     *
+     * 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.
+     */
+    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;
+}
+interface SciComponentColumnDescriptor<T> extends SciTableColumnDescriptor {
+    component: (item: T) => SciComponentDescriptor;
+    sortable?: boolean | {
+        comparator: SciTableColumnSortComparatorFn<T, void>;
+    };
+    filterable?: boolean | {
+        matcher: SciTableColumnFilterMatcherFn<T, void, string>;
+    };
+    /**
+     * Controls whether cell padding is applied. Set to `false` to let content fill the entire cell (render to cell bounds).
+     *
+     * Defaults to `true`.
+     */
+    padding?: boolean;
+}
+interface SciTemplateColumnDescriptor<T> extends SciTableColumnDescriptor {
+    template: (item: T) => SciTemplateDescriptor;
+    sortable?: boolean | {
+        comparator: SciTableColumnSortComparatorFn<T, void>;
+    };
+    filterable?: boolean | {
+        matcher: SciTableColumnFilterMatcherFn<T, void, string>;
+    };
+    /**
+     * Controls whether cell padding is applied. Set to `false` to let content fill the entire cell (render to cell bounds).
+     *
+     * Defaults to `true`.
+     */
+    padding?: boolean;
+}
+/**
+ * Signature of a function used to configure a comparator for sorting a table column.
+ */
+type SciTableColumnSortComparatorFn<T = unknown, VALUE = unknown> = (a: SciTableCellContext<T, VALUE>, b: SciTableCellContext<T, VALUE>) => number;
+/**
+ * Signature of a function used to configure a matcher for filtering a table column.
+ */
+type SciTableColumnFilterMatcherFn<T = unknown, VALUE = unknown, FILTER = VALUE> = (filter: FILTER, context: SciTableCellContext<T, VALUE>) => boolean;
+
+/**
+ * Represents the internal value of {@link SciDateColumn}.
+ */
+interface SciDateValue {
+    /**
+     * Full ISO 8601 date/time string.
+     */
+    isoString: string;
+    /**
+     * Milliseconds since UTC epoch.
+     */
+    millis: number;
+    /**
+     * Human-readable formatted date and time string.
+     */
+    formatted: string;
+}
+
+type SciTableColumnType = 'string' | 'number' | 'boolean' | 'date' | 'component' | 'template';
 type SciTableRowActionFactoryFn<T> = (toolbar: SciToolbarFactory, item: T, index: number) => void;
 interface SciTableDescriptor<T> {
     datasource: Signal<T[]>;
@@ -137,7 +528,7 @@ interface SciTableDescriptor<T> {
      * ```
      *
      * ```scss
-     * sci-table::part(row\:even) {
+     * sci-table::part(row\:even row\:not\:selected) {
      *   background-color: lightgray;
      * }
      * ```
@@ -169,13 +560,12 @@ interface SciTable<T> {
     readonly sortable: WritableSignal<boolean>;
     readonly resizable: WritableSignal<boolean>;
     readonly selectable: WritableSignal<'single' | 'multi' | false>;
+    /**
+     * Filters items cross-column, ignoring {@link SciTableDescriptor.filterable} and {@link SciTableColumnDescriptor.filterable} settings.
+     */
     filter(text: string | null): void;
 }
-interface SciTableCellContext<T, VALUE> {
-    item: T;
-    value: VALUE;
-}
-interface SciTableColumn {
+interface SciTableColumn<T = unknown, VALUE = unknown, FILTER = VALUE> {
     type: SciTableColumnType;
     name: `column:${string}`;
     header: Signal<string>;
@@ -190,38 +580,47 @@ interface SciTableColumn {
         x: number;
         width: number;
     };
+    compare: SciTableColumnSortComparatorFn<T, VALUE>;
+    matches: SciTableColumnFilterMatcherFn<T, VALUE, FILTER>;
 }
-interface SciStringColumn<T> extends SciTableColumn {
+interface SciStringColumn<T = unknown> extends SciTableColumn<T, string> {
     type: 'string';
-    value: (item: T) => MaybeSignal<string>;
-    sort: (a: SciTableCellContext<T, string>, b: SciTableCellContext<T, string>) => number;
-    filter: (text: string, context: SciTableCellContext<T, string>) => boolean;
+    value: (item: T) => Signal<string | undefined>;
+    compare: SciTableColumnSortComparatorFn<T, string>;
+    matches: SciTableColumnFilterMatcherFn<T, string>;
 }
-interface SciNumberColumn<T> extends SciTableColumn {
+interface SciNumberColumn<T = unknown> extends SciTableColumn<T, number> {
     type: 'number';
-    value: (item: T) => MaybeSignal<number>;
-    sort: (a: SciTableCellContext<T, number>, b: SciTableCellContext<T, number>) => number;
-    filter: (text: number, context: SciTableCellContext<T, number>) => boolean;
+    value: (item: T) => Signal<number | undefined>;
+    compare: SciTableColumnSortComparatorFn<T, number>;
+    matches: SciTableColumnFilterMatcherFn<T, number>;
+    format: Signal<Intl.NumberFormat>;
 }
-interface SciBooleanColumn<T> extends SciTableColumn {
+interface SciBooleanColumn<T = unknown> extends SciTableColumn<T, boolean> {
     type: 'boolean';
-    value: (item: T) => MaybeSignal<boolean>;
-    sort: (a: SciTableCellContext<T, boolean>, b: SciTableCellContext<T, boolean>) => number;
-    filter: (text: boolean, context: SciTableCellContext<T, boolean>) => 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 SciComponentColumn<T> extends SciTableColumn {
+interface SciComponentColumn<T = unknown> extends SciTableColumn<T, void, string> {
     type: 'component';
     component: (item: T) => SciComponentDescriptor;
-    sort: (a: SciTableCellContext<T, void>, b: SciTableCellContext<T, void>) => number;
-    filter: (text: string, context: SciTableCellContext<T, void>) => boolean;
+    compare: SciTableColumnSortComparatorFn<T, void>;
+    matches: SciTableColumnFilterMatcherFn<T, void, string>;
 }
-interface SciTemplateColumn<T> extends SciTableColumn {
+interface SciTemplateColumn<T = unknown> extends SciTableColumn<T, void, string> {
     type: 'template';
     template: (item: T) => SciTemplateDescriptor;
-    sort: (a: SciTableCellContext<T, void>, b: SciTableCellContext<T, void>) => number;
-    filter: (text: string, context: SciTableCellContext<T, void>) => boolean;
+    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> | SciBooleanColumn<T> | SciDateColumn<T> | SciComponentColumn<T> | SciTemplateColumn<T>;
 /**
  * Mapped row, used as display state.
  */
@@ -238,30 +637,39 @@ 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 SciBooleanCell {
     type: 'boolean';
-    column: SciTableColumnLike;
-    value: Signal<boolean>;
+    column: SciBooleanColumn;
+    value: Signal<boolean | undefined>;
+}
+interface SciDateCell {
+    type: 'date';
+    column: SciDateColumn;
+    value: Signal<SciDateValue | 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 | SciBooleanCell | SciDateCell | SciComponentCell | SciTemplateCell;
+interface SciTableCellContext<T = unknown, VALUE = unknown> {
+    item: T;
+    value: VALUE;
+}
 /**
  * Represents an event emitted by {@link SciTableComponent}.
  */
@@ -275,84 +683,10 @@ interface SciTableEvent<T> {
      */
     items: T[];
 }
-
-interface SciTableColumnFactory<T> {
-    addStringColumn(header: Translatable, value: (item: T) => string): this;
-    addStringColumn(value: (item: T) => string): this;
-    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;
-    addNumberColumn(descriptor: SciNumberColumnDescriptor<T>): this;
-    addComponentColumn(descriptor: SciComponentColumnDescriptor<T>): this;
-    addTemplateColumn(descriptor: SciTemplateColumnDescriptor<T>): this;
-}
-interface SciTableColumnDescriptor {
-    name?: `column:${string}`;
-    header?: Translatable;
-    resizable?: boolean;
-    /**
-     * Preferred column size.
-     * Value which can be used inside `grid-template-columns` definition. Defaults to 1fr.
-     * Examples: `1fr`, `max-content`, `100px`.
-     */
-    width?: string;
-    /**
-     * Min column width in px. Defaults to 100.
-     */
-    minWidth?: number;
-}
-interface SciStringColumnDescriptor<T> extends SciTableColumnDescriptor {
-    value: (item: T) => MaybeSignal<string>;
-    sortable?: boolean | {
-        comparator: (a: SciTableCellContext<T, string>, b: SciTableCellContext<T, string>) => number;
-    };
-    filterable?: boolean | {
-        matcher: (text: string, context: SciTableCellContext<T, string>) => boolean;
-    };
-}
-interface SciNumberColumnDescriptor<T> extends SciTableColumnDescriptor {
-    value: (item: T) => MaybeSignal<number>;
-    sortable?: boolean;
-    filterable?: boolean;
-}
-interface SciBooleanColumnDescriptor<T> extends SciTableColumnDescriptor {
-    value: (item: T) => MaybeSignal<boolean>;
-    sortable?: boolean;
-    filterable?: boolean;
-}
-interface SciComponentColumnDescriptor<T> extends SciTableColumnDescriptor {
-    component: (item: T) => SciComponentDescriptor;
-    sortable?: boolean | {
-        comparator: (a: SciTableCellContext<T, void>, b: SciTableCellContext<T, void>) => number;
-    };
-    filterable?: boolean | {
-        matcher: (text: string, context: SciTableCellContext<T, void>) => boolean;
-    };
-    /**
-     * Controls whether cell padding is applied. Set to `false` to let content fill the entire cell (render to cell bounds).
-     *
-     * Defaults to `true`.
-     */
-    padding?: boolean;
-}
-interface SciTemplateColumnDescriptor<T> extends SciTableColumnDescriptor {
-    template: (item: T) => SciTemplateDescriptor;
-    sortable?: boolean | {
-        comparator: (a: SciTableCellContext<T, void>, b: SciTableCellContext<T, void>) => number;
-    };
-    filterable?: boolean | {
-        matcher: (text: string, context: SciTableCellContext<T, void>) => boolean;
-    };
-    /**
-     * Controls whether cell padding is applied. Set to `false` to let content fill the entire cell (render to cell bounds).
-     *
-     * Defaults to `true`.
-     */
-    padding?: boolean;
-}
+/**
+ * Represents an ISO 8601 date/time string, milliseconds since the UTC epoch, or a `Date` object.
+ */
+type SciDateLike = string | number | Date;
 
 type SciTableColumnFactoryFn<T> = (table: SciTableColumnFactory<T>) => void;
 /** @experimental since 22.3.0; API and behavior may change in any version without notice. */
@@ -393,6 +727,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>;
@@ -458,6 +793,12 @@ declare class ɵSciTable<T = unknown> implements SciTable<T> {
         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;
     /**
@@ -468,7 +809,6 @@ declare class ɵSciTable<T = unknown> implements SciTable<T> {
      * Resets cache on criteria changes.
      */
     private installCriteriaWatcher;
-    private initColumn;
     private mapItemsToRow;
     /**
      * Creates a signal to read and write table user settings.
@@ -574,4 +914,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, SciTableColumnType, SciTableDataLoaderFn, SciTableDescriptor, SciTableEvent, SciTablePageRequest, SciTablePageResponse, SciTableRowActionFactoryFn, SciTableRowBindingFactory, SciTableRowBindingFactoryFn, SciTableSortCriterion, SciTableStorage, SciTemplateColumnDescriptor };
+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 };