@humanspeak/svelte-headless-table 6.0.2 → 6.0.4

package/README.md

@@ -22,7 +22,7 @@
 
 </div>
 
-**Unopinionated and extensible data tables for Svelte**
+## Unopinionated and extensible data tables for Svelte
 
 > Build and design powerful datagrid experiences while retaining 100% control over styles and markup.
 
@@ -40,7 +40,7 @@ Svelte Headless Table is designed to work **seamlessly** with Svelte. If you lov
 - Highly performant
 - Feature-rich
 
-## All the features you could ever need!
+## All the features you could ever need
 
 Svelte Headless Table comes with an extensive suite of plugins.
 
@@ -60,6 +60,7 @@ Easily extend Svelte Headless Table with complex **sorting**, **filtering**, **g
 - [x] [addSelectedRows](https://table.svelte.page/docs/plugins/add-selected-rows)
 - [x] [addResizedColumns](https://table.svelte.page/docs/plugins/add-resized-columns)
 - [x] [addGridLayout](https://table.svelte.page/docs/plugins/add-grid-layout)
+- [x] [addVirtualScroll](https://table.svelte.page/docs/plugins/add-virtual-scroll)
 
 ## Examples
 

package/dist/bodyCells.d.ts

@@ -5,13 +5,32 @@ import type { DataLabel, DisplayLabel } from './types/Label.js';
 import type { AnyPlugins } from './types/TablePlugin.js';
 import type { RenderConfig } from '@humanspeak/svelte-render';
 import { type Readable } from 'svelte/store';
+/**
+ * Initialization options for creating a BodyCell.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type BodyCellInit<Item, Plugins extends AnyPlugins = AnyPlugins> = {
     id: string;
     row: BodyRow<Item, Plugins>;
 };
+/**
+ * HTML attributes for a body cell element.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type BodyCellAttributes<Item, Plugins extends AnyPlugins = AnyPlugins> = {
     role: 'cell';
 };
+/**
+ * Abstract base class representing a cell in the table body.
+ * Extended by DataBodyCell for data cells and DisplayBodyCell for display-only cells.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export declare abstract class BodyCell<Item, Plugins extends AnyPlugins = AnyPlugins> extends TableComponent<Item, Plugins, 'tbody.tr.td'> {
     abstract column: FlatColumn<Item, Plugins>;
     row: BodyRow<Item, Plugins>;
@@ -19,35 +38,132 @@ export declare abstract class BodyCell<Item, Plugins extends AnyPlugins = AnyPlu
     abstract render(): RenderConfig;
     attrs(): Readable<BodyCellAttributes<Item, Plugins>>;
     abstract clone(): BodyCell<Item, Plugins>;
+    /**
+     * Gets a unique identifier combining the row ID and column ID.
+     *
+     * @returns A string in the format "rowId:columnId".
+     */
     rowColId(): string;
+    /**
+     * Gets a unique identifier combining the data row ID and column ID.
+     * Only available for cells in data rows.
+     *
+     * @returns A string in the format "dataId:columnId", or undefined if not a data row.
+     */
     dataRowColId(): string | undefined;
+    /**
+     * Type guard to check if this cell is a data cell.
+     *
+     * @returns True if this is a DataBodyCell.
+     */
     isData(): this is DataBodyCell<Item, Plugins>;
+    /**
+     * Type guard to check if this cell is a display cell.
+     *
+     * @returns True if this is a DisplayBodyCell.
+     */
     isDisplay(): this is DisplayBodyCell<Item, Plugins>;
 }
+/**
+ * Initialization options for creating a DataBodyCell.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @template Value - The type of the cell value.
+ */
 export type DataBodyCellInit<Item, Plugins extends AnyPlugins = AnyPlugins, Value = unknown> = Omit<BodyCellInit<Item, Plugins>, 'id'> & {
+    /** The data column this cell belongs to. */
     column: DataColumn<Item, Plugins>;
+    /** Optional custom label renderer for the cell. */
     label?: DataLabel<Item, Plugins, Value>;
+    /** The cell's value. */
     value: Value;
 };
+/**
+ * HTML attributes for a data body cell element.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type DataBodyCellAttributes<Item, Plugins extends AnyPlugins = AnyPlugins> = BodyCellAttributes<Item, Plugins>;
+/**
+ * A body cell that contains actual data from the data source.
+ * Provides access to the cell value and custom rendering.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @template Value - The type of the cell value.
+ */
 export declare class DataBodyCell<Item, Plugins extends AnyPlugins = AnyPlugins, Value = unknown> extends BodyCell<Item, Plugins> {
     __data: boolean;
+    /** The data column this cell belongs to. */
     column: DataColumn<Item, Plugins>;
+    /** Optional custom label renderer for the cell. */
     label?: DataLabel<Item, Plugins, Value>;
+    /** The cell's value. */
     value: Value;
+    /**
+     * Creates a new DataBodyCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ row, column, label, value }: DataBodyCellInit<Item, Plugins, Value>);
+    /**
+     * Renders the cell content using the label function or the raw value.
+     *
+     * @returns The render configuration for displaying this cell.
+     * @throws Error if state reference is missing when using a custom label.
+     */
     render(): RenderConfig;
+    /**
+     * Creates a copy of this cell.
+     *
+     * @returns A cloned DataBodyCell.
+     */
     clone(): DataBodyCell<Item, Plugins>;
 }
+/**
+ * Initialization options for creating a DisplayBodyCell.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type DisplayBodyCellInit<Item, Plugins extends AnyPlugins = AnyPlugins> = Omit<BodyCellInit<Item, Plugins>, 'id'> & {
+    /** The display column this cell belongs to. */
     column: DisplayColumn<Item, Plugins>;
+    /** The label renderer for the cell. */
     label: DisplayLabel<Item, Plugins>;
 };
+/**
+ * A body cell used for display purposes only (e.g., action buttons, checkboxes).
+ * Does not contain direct data from the data source.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export declare class DisplayBodyCell<Item, Plugins extends AnyPlugins = AnyPlugins> extends BodyCell<Item, Plugins> {
     __display: boolean;
+    /** The display column this cell belongs to. */
     column: DisplayColumn<Item, Plugins>;
+    /** The label renderer for the cell. */
     label: DisplayLabel<Item, Plugins>;
+    /**
+     * Creates a new DisplayBodyCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ row, column, label }: DisplayBodyCellInit<Item, Plugins>);
+    /**
+     * Renders the cell content using the label function.
+     *
+     * @returns The render configuration for displaying this cell.
+     * @throws Error if state reference is missing.
+     */
     render(): RenderConfig;
+    /**
+     * Creates a copy of this cell.
+     *
+     * @returns A cloned DisplayBodyCell.
+     */
     clone(): DisplayBodyCell<Item, Plugins>;
 }

package/dist/bodyCells.js

@@ -1,5 +1,12 @@
 import { TableComponent } from './tableComponent.js';
 import { derived } from 'svelte/store';
+/**
+ * Abstract base class representing a cell in the table body.
+ * Extended by DataBodyCell for data cells and DisplayBodyCell for display-only cells.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export class BodyCell extends TableComponent {
     row;
     constructor({ id, row }) {
@@ -14,36 +21,79 @@ export class BodyCell extends TableComponent {
             };
         });
     }
+    /**
+     * Gets a unique identifier combining the row ID and column ID.
+     *
+     * @returns A string in the format "rowId:columnId".
+     */
     rowColId() {
         return `${this.row.id}:${this.column.id}`;
     }
+    /**
+     * Gets a unique identifier combining the data row ID and column ID.
+     * Only available for cells in data rows.
+     *
+     * @returns A string in the format "dataId:columnId", or undefined if not a data row.
+     */
     dataRowColId() {
         if (!this.row.isData()) {
             return undefined;
         }
         return `${this.row.dataId}:${this.column.id}`;
     }
+    /**
+     * Type guard to check if this cell is a data cell.
+     *
+     * @returns True if this is a DataBodyCell.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isData() {
         return '__data' in this;
     }
+    /**
+     * Type guard to check if this cell is a display cell.
+     *
+     * @returns True if this is a DisplayBodyCell.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isDisplay() {
         return '__display' in this;
     }
 }
+/**
+ * A body cell that contains actual data from the data source.
+ * Provides access to the cell value and custom rendering.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @template Value - The type of the cell value.
+ */
 export class DataBodyCell extends BodyCell {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __data = true;
+    /** The data column this cell belongs to. */
     column;
+    /** Optional custom label renderer for the cell. */
     label;
+    /** The cell's value. */
     value;
+    /**
+     * Creates a new DataBodyCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ row, column, label, value }) {
         super({ id: column.id, row });
         this.column = column;
         this.label = label;
         this.value = value;
     }
+    /**
+     * Renders the cell content using the label function or the raw value.
+     *
+     * @returns The render configuration for displaying this cell.
+     * @throws Error if state reference is missing when using a custom label.
+     */
     render() {
         if (this.label === undefined) {
             return `${this.value}`;
@@ -53,6 +103,11 @@ export class DataBodyCell extends BodyCell {
         }
         return this.label(this, this.state);
     }
+    /**
+     * Creates a copy of this cell.
+     *
+     * @returns A cloned DataBodyCell.
+     */
     clone() {
         const clonedCell = new DataBodyCell({
             row: this.row,
@@ -63,22 +118,47 @@ export class DataBodyCell extends BodyCell {
         return clonedCell;
     }
 }
+/**
+ * A body cell used for display purposes only (e.g., action buttons, checkboxes).
+ * Does not contain direct data from the data source.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export class DisplayBodyCell extends BodyCell {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __display = true;
+    /** The display column this cell belongs to. */
     column;
+    /** The label renderer for the cell. */
     label;
+    /**
+     * Creates a new DisplayBodyCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ row, column, label }) {
         super({ id: column.id, row });
         this.column = column;
         this.label = label;
     }
+    /**
+     * Renders the cell content using the label function.
+     *
+     * @returns The render configuration for displaying this cell.
+     * @throws Error if state reference is missing.
+     */
     render() {
         if (this.state === undefined) {
             throw new Error('Missing `state` reference');
         }
         return this.label(this, this.state);
     }
+    /**
+     * Creates a copy of this cell.
+     *
+     * @returns A cloned DisplayBodyCell.
+     */
     clone() {
         const clonedCell = new DisplayBodyCell({
             row: this.row,

package/dist/bodyRows.d.ts

@@ -3,6 +3,12 @@ import type { FlatColumn } from './columns.js';
 import { TableComponent } from './tableComponent.js';
 import type { AnyPlugins } from './types/TablePlugin.js';
 import { type Readable } from 'svelte/store';
+/**
+ * Initialization options for creating a BodyRow.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type BodyRowInit<Item, Plugins extends AnyPlugins = AnyPlugins> = {
     id: string;
     cells: BodyCell<Item, Plugins>[];
@@ -10,9 +16,22 @@ export type BodyRowInit<Item, Plugins extends AnyPlugins = AnyPlugins> = {
     depth?: number;
     parentRow?: BodyRow<Item, Plugins>;
 };
+/**
+ * HTML attributes for a body row element.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type BodyRowAttributes<Item, Plugins extends AnyPlugins = AnyPlugins> = {
     role: 'row';
 };
+/**
+ * Abstract base class representing a row in the table body.
+ * Extended by DataBodyRow for data rows and DisplayBodyRow for display-only rows.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export declare abstract class BodyRow<Item, Plugins extends AnyPlugins = AnyPlugins> extends TableComponent<Item, Plugins, 'tbody.tr'> {
     cells: BodyCell<Item, Plugins>[];
     /**
@@ -27,31 +46,104 @@ export declare abstract class BodyRow<Item, Plugins extends AnyPlugins = AnyPlug
     constructor({ id, cells, cellForId, depth, parentRow }: BodyRowInit<Item, Plugins>);
     attrs(): Readable<BodyRowAttributes<Item, Plugins>>;
     abstract clone(props?: BodyRowCloneProps): BodyRow<Item, Plugins>;
+    /**
+     * Type guard to check if this row is a data row.
+     *
+     * @returns True if this is a DataBodyRow.
+     */
     isData(): this is DataBodyRow<Item, Plugins>;
+    /**
+     * Type guard to check if this row is a display row.
+     *
+     * @returns True if this is a DisplayBodyRow.
+     */
     isDisplay(): this is DisplayBodyRow<Item, Plugins>;
 }
+/**
+ * Options for cloning a BodyRow.
+ */
 type BodyRowCloneProps = {
+    /** Whether to clone the cells as well. */
     includeCells?: boolean;
+    /** Whether to recursively clone sub-rows. */
     includeSubRows?: boolean;
 };
+/**
+ * Initialization options for creating a DataBodyRow.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type DataBodyRowInit<Item, Plugins extends AnyPlugins = AnyPlugins> = BodyRowInit<Item, Plugins> & {
+    /** Unique identifier for the data item. */
     dataId: string;
+    /** The original data item. */
     original: Item;
 };
+/**
+ * A body row that contains actual data from the data source.
+ * Provides access to the original data item and a unique data ID.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export declare class DataBodyRow<Item, Plugins extends AnyPlugins = AnyPlugins> extends BodyRow<Item, Plugins> {
     __data: boolean;
+    /** Unique identifier for the data item. */
     dataId: string;
+    /** The original data item from the data source. */
     original: Item;
+    /**
+     * Creates a new DataBodyRow.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, dataId, original, cells, cellForId, depth, parentRow }: DataBodyRowInit<Item, Plugins>);
+    /**
+     * Creates a copy of this row with optional deep cloning of cells and sub-rows.
+     *
+     * @param props - Cloning options.
+     * @returns A cloned DataBodyRow.
+     */
     clone({ includeCells, includeSubRows }?: BodyRowCloneProps): DataBodyRow<Item, Plugins>;
 }
+/**
+ * Initialization options for creating a DisplayBodyRow.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type DisplayBodyRowInit<Item, Plugins extends AnyPlugins = AnyPlugins> = BodyRowInit<Item, Plugins>;
+/**
+ * A body row used for display purposes only (e.g., grouped rows, aggregate rows).
+ * Does not contain direct data from the data source.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export declare class DisplayBodyRow<Item, Plugins extends AnyPlugins = AnyPlugins> extends BodyRow<Item, Plugins> {
     __display: boolean;
+    /**
+     * Creates a new DisplayBodyRow.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, cells, cellForId, depth, parentRow }: DisplayBodyRowInit<Item, Plugins>);
+    /**
+     * Creates a copy of this row with optional deep cloning of cells and sub-rows.
+     *
+     * @param props - Cloning options.
+     * @returns A cloned DisplayBodyRow.
+     */
     clone({ includeCells, includeSubRows }?: BodyRowCloneProps): DisplayBodyRow<Item, Plugins>;
 }
+/**
+ * Options for creating body rows from data.
+ *
+ * @template Item - The type of data items.
+ */
 export interface BodyRowsOptions<Item> {
+    /** Optional function to generate a unique ID for each data item. */
     rowDataId?: (item: Item, index: number) => string;
 }
 /**

package/dist/bodyRows.js

@@ -2,6 +2,13 @@ import { BodyCell, DataBodyCell, DisplayBodyCell } from './bodyCells.js';
 import { TableComponent } from './tableComponent.js';
 import { nonUndefined } from './utils/filter.js';
 import { derived } from 'svelte/store';
+/**
+ * Abstract base class representing a row in the table body.
+ * Extended by DataBodyRow for data rows and DisplayBodyRow for display-only rows.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export class BodyRow extends TableComponent {
     cells;
     /**
@@ -28,25 +35,55 @@ export class BodyRow extends TableComponent {
             };
         });
     }
+    /**
+     * Type guard to check if this row is a data row.
+     *
+     * @returns True if this is a DataBodyRow.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isData() {
         return '__data' in this;
     }
+    /**
+     * Type guard to check if this row is a display row.
+     *
+     * @returns True if this is a DisplayBodyRow.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isDisplay() {
         return '__display' in this;
     }
 }
+/**
+ * A body row that contains actual data from the data source.
+ * Provides access to the original data item and a unique data ID.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export class DataBodyRow extends BodyRow {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __data = true;
+    /** Unique identifier for the data item. */
     dataId;
+    /** The original data item from the data source. */
     original;
+    /**
+     * Creates a new DataBodyRow.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, dataId, original, cells, cellForId, depth = 0, parentRow }) {
         super({ id, cells, cellForId, depth, parentRow });
         this.dataId = dataId;
         this.original = original;
     }
+    /**
+     * Creates a copy of this row with optional deep cloning of cells and sub-rows.
+     *
+     * @param props - Cloning options.
+     * @returns A cloned DataBodyRow.
+     */
     clone({ includeCells = false, includeSubRows = false } = {}) {
         const clonedRow = new DataBodyRow({
             id: this.id,
@@ -76,12 +113,30 @@ export class DataBodyRow extends BodyRow {
         return clonedRow;
     }
 }
+/**
+ * A body row used for display purposes only (e.g., grouped rows, aggregate rows).
+ * Does not contain direct data from the data source.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export class DisplayBodyRow extends BodyRow {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __display = true;
+    /**
+     * Creates a new DisplayBodyRow.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, cells, cellForId, depth = 0, parentRow }) {
         super({ id, cells, cellForId, depth, parentRow });
     }
+    /**
+     * Creates a copy of this row with optional deep cloning of cells and sub-rows.
+     *
+     * @param props - Cloning options.
+     * @returns A cloned DisplayBodyRow.
+     */
     clone({ includeCells = false, includeSubRows = false } = {}) {
         const clonedRow = new DisplayBodyRow({
             id: this.id,