@scion/components 22.3.0 → 22.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scion/components",
-  "version": "22.3.0",
+  "version": "22.4.0",
   "description": "Provides a collection of Angular components and directives primarily for use in SCION libraries such as `@scion/workbench` and `@scion/microfrontend-platform`. This library is not a comprehensive component library as its focus is on SCION requirements.",
   "license": "EPL-2.0",
   "private": false,
@@ -83,7 +83,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/SchweizerischeBundesbahnen/scion-toolkit.git"
+    "url": "git+https://github.com/SchweizerischeBundesbahnen/scion-toolkit.git"
   },
   "sideEffects": false,
   "module": "fesm2022/scion-components.mjs",

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

@@ -60,61 +60,8 @@ declare class SciIconComponent {
  * @import url('https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL@20..24,400,0&display=block');
  * ```
  *
- * SCION uses the following built-in icons:
- * - scion.add               : Add an item
- * - scion.add_large         : Add an item (large)
- * - scion.bin               : Bin symbol
- * - scion.checkmark         : Indicates a selected option
- * - scion.chevron_down      : Chevron down symbol
- * - scion.chevron_left      : Chevron left symbol
- * - scion.chevron_right     : Chevron right symbol
- * - scion.chevron_up        : Chevron up symbol
- * - scion.clear             : Clear items
- * - scion.close             : Close a popover
- * - scion.collapse_all      : Collapse all items
- * - scion.copy              : Copy an item
- * - scion.delete            : Delete an item
- * - scion.dirty             : Indicates unsaved data
- * - scion.drag_handle       : Drag or move an item
- * - scion.duplicate         : Duplicate an item
- * - scion.edit              : Edit an item
- * - scion.emdash            : Em dash symbol
- * - scion.envelope          : Envelope symbol
- * - scion.envelope_closed   : Indicates a closed envelope
- * - scion.envelope_opened   : Indicates an opened envelope
- * - scion.expand_all        : Expand an item
- * - scion.external_link     : Open link in a new tab
- * - scion.filter            : Set or change a filter
- * - scion.find              : Find an item
- * - scion.folder            : Directory symbol
- * - scion.help              : Indicates help, support, or documentation
- * - scion.hide              : Hide a panel
- * - scion.magnifier         : Magnifier symbol
- * - scion.minimize          : Minimize a panel
- * - scion.minus             : Minus sign
- * - scion.modified          : Indicates modified data
- * - scion.more_horizontal   : Show a popover to the left or right
- * - scion.more_vertical     : Show a popover above or below
- * - scion.new               : Create an item
- * - scion.new_large         : Create an item (large)
- * - scion.paste             : Paste from clipboard
- * - scion.pen               : Pen symbol
- * - scion.pin               : Pin an item
- * - scion.pinned            : Indicates a pinned item
- * - scion.placeholder_frame : Placeholder symbol
- * - scion.placeholder_image : Placeholder symbol for an image
- * - scion.plus              : Plus sign
- * - scion.plus_large        : Plus sign (large)
- * - scion.remove            : Remove an item (x)
- * - scion.remove_minus      : Remove an item (-)
- * - scion.reset             : Reset a form
- * - scion.search            : Search for an item
- * - scion.sort_ascending    : Sort items in ascending order (A-Z, 0-9)
- * - scion.sort_by           : Change sort order
- * - scion.sort_descending   : Sort items in descending order (Z-A, 9-0)
- * - scion.user              : User symbol
- *
- * To not replace built-in icons, the icon provider can return `undefined` for icons starting with the `scion.` prefix.
+ * Built-in SCION icons start with the `scion.` prefix. To not replace SCION icons, the icon provider can return `undefined` for icons starting with the `scion.` prefix.
+ * Refer to https://icons.scion.vercel.app for available SCION icons.
  *
  * The function can call `inject` to get any required dependencies.
  *
@@ -130,7 +77,7 @@ declare function provideIconProvider(iconProviderFn: SciIconProviderFn | undefin
  * Alternatively, the icon provider can return a descriptor, allowing for additional configuration such as inputs.
  * Inputs are available as input properties in the component. The component can use the inputs to render the icon.
  *
- * Icon keys used by SCION start with the `scion.` prefix. To not replace built-in icons, the icon provider can
+ * Icon keys used by SCION start with the `scion.` prefix. To not replace SCION icons, the icon provider can
  * return `undefined` for icons starting with the `scion.` prefix.
  *
  * An icon provider can be registered via {@link provideIconProvider} function.

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

@@ -86,6 +86,92 @@ interface SciTableRowBindings {
     part: Signal<`row:${string}`[]>;
 }
 
+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: SciTableColumnSortComparatorFn<T, string>;
+    };
+    filterable?: boolean | {
+        matcher: SciTableColumnFilterMatcherFn<T, string>;
+    };
+}
+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: 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;
+
 type SciTableColumnType = 'string' | 'number' | 'boolean' | 'component' | 'template';
 type SciTableRowActionFactoryFn<T> = (toolbar: SciToolbarFactory, item: T, index: number) => void;
 interface SciTableDescriptor<T> {
@@ -169,13 +255,16 @@ 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> {
+interface SciTableCellContext<T = unknown, VALUE = unknown> {
     item: T;
     value: VALUE;
 }
-interface SciTableColumn {
+interface SciTableColumn<T = unknown, VALUE = unknown, FILTER = VALUE> {
     type: SciTableColumnType;
     name: `column:${string}`;
     header: Signal<string>;
@@ -190,36 +279,38 @@ interface SciTableColumn {
         x: number;
         width: number;
     };
+    compare: SciTableColumnSortComparatorFn<T, VALUE>;
+    matches: SciTableColumnFilterMatcherFn<T, VALUE, FILTER>;
 }
-interface SciStringColumn<T> extends SciTableColumn {
+interface SciStringColumn<T> 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;
+    compare: SciTableColumnSortComparatorFn<T, string>;
+    matches: SciTableColumnFilterMatcherFn<T, string>;
 }
-interface SciNumberColumn<T> extends SciTableColumn {
+interface SciNumberColumn<T> 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;
+    compare: SciTableColumnSortComparatorFn<T, number>;
+    matches: SciTableColumnFilterMatcherFn<T, number>;
 }
-interface SciBooleanColumn<T> extends SciTableColumn {
+interface SciBooleanColumn<T> 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;
+    compare: SciTableColumnSortComparatorFn<T, boolean>;
+    matches: SciTableColumnFilterMatcherFn<T, boolean>;
 }
-interface SciComponentColumn<T> extends SciTableColumn {
+interface SciComponentColumn<T> 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> 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>;
 /**
@@ -276,84 +367,6 @@ 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;
-}
-
 type SciTableColumnFactoryFn<T> = (table: SciTableColumnFactory<T>) => void;
 /** @experimental since 22.3.0; API and behavior may change in any version without notice. */
 declare function table<T>(descriptor: SciTableDescriptor<T>): SciTable<T>;
@@ -458,6 +471,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 +487,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 +592,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, SciNumberColumnDescriptor, SciStringColumnDescriptor, SciTable, SciTableCellContext, SciTableColumnDescriptor, SciTableColumnFactory, SciTableColumnFactoryFn, SciTableColumnFilter, SciTableColumnFilterMatcherFn, SciTableColumnSortComparatorFn, SciTableColumnType, SciTableDataLoaderFn, SciTableDescriptor, SciTableEvent, SciTablePageRequest, SciTablePageResponse, SciTableRowActionFactoryFn, SciTableRowBindingFactory, SciTableRowBindingFactoryFn, SciTableSortCriterion, SciTableStorage, SciTemplateColumnDescriptor };