@humanspeak/svelte-headless-table 6.0.1 → 6.0.3

package/dist/headerCells.js

@@ -1,16 +1,37 @@
 import { NBSP } from './constants.js';
 import { TableComponent } from './tableComponent.js';
 import { derived } from 'svelte/store';
+/**
+ * Abstract base class representing a cell in the table header.
+ * Extended by FlatHeaderCell, DataHeaderCell, GroupHeaderCell, etc.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export class HeaderCell extends TableComponent {
+    /** Label content or render function for the header. */
     label;
+    /** Number of columns this cell spans. */
     colspan;
+    /** Starting column index. */
     colstart;
+    /**
+     * Creates a new HeaderCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, label, colspan, colstart }) {
         super({ id });
         this.label = label;
         this.colspan = colspan;
         this.colstart = colstart;
     }
+    /**
+     * Renders the header cell content.
+     *
+     * @returns The render configuration for displaying this cell.
+     * @throws Error if state reference is missing when using a function label.
+     */
     render() {
         if (this.label instanceof Function) {
             if (this.state === undefined) {
@@ -20,6 +41,11 @@ export class HeaderCell extends TableComponent {
         }
         return this.label;
     }
+    /**
+     * Gets the HTML attributes for this header cell.
+     *
+     * @returns A readable store of cell attributes.
+     */
     attrs() {
         return derived(super.attrs(), ($baseAttrs) => {
             return {
@@ -29,33 +55,75 @@ export class HeaderCell extends TableComponent {
             };
         });
     }
+    /**
+     * Type guard to check if this is a flat header cell.
+     *
+     * @returns True if this is a FlatHeaderCell.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isFlat() {
         return '__flat' in this;
     }
+    /**
+     * Type guard to check if this is a data header cell.
+     *
+     * @returns True if this is a DataHeaderCell.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isData() {
         return '__data' in this;
     }
+    /**
+     * Type guard to check if this is a flat display header cell.
+     *
+     * @returns True if this is a FlatDisplayHeaderCell.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isFlatDisplay() {
         return '__flat' in this && '__display' in this;
     }
+    /**
+     * Type guard to check if this is a group header cell.
+     *
+     * @returns True if this is a GroupHeaderCell.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isGroup() {
         return '__group' in this;
     }
+    /**
+     * Type guard to check if this is a group display header cell.
+     *
+     * @returns True if this is a GroupDisplayHeaderCell.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isGroupDisplay() {
         return '__group' in this && '__display' in this;
     }
 }
+/**
+ * A flat (non-grouped) header cell that spans a single column.
+ * Base class for DataHeaderCell and FlatDisplayHeaderCell.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export class FlatHeaderCell extends HeaderCell {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __flat = true;
+    /**
+     * Creates a new FlatHeaderCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, label, colstart }) {
         super({ id, label, colspan: 1, colstart });
     }
+    /**
+     * Creates a copy of this header cell.
+     *
+     * @returns A cloned FlatHeaderCell.
+     */
     clone() {
         return new FlatHeaderCell({
             id: this.id,
@@ -64,17 +132,36 @@ export class FlatHeaderCell extends HeaderCell {
         });
     }
 }
+/**
+ * A header cell for a data column that displays values from the data source.
+ * Contains accessor information for retrieving cell values.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export class DataHeaderCell extends FlatHeaderCell {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __data = true;
+    /** The key used to access data from the item. */
     accessorKey;
+    /** Function to extract data from the item. */
     /* trunk-ignore(eslint/no-unused-vars) */
     accessorFn;
+    /**
+     * Creates a new DataHeaderCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, label, accessorKey, accessorFn, colstart }) {
         super({ id, label, colstart });
         this.accessorKey = accessorKey;
         this.accessorFn = accessorFn;
     }
+    /**
+     * Creates a copy of this header cell.
+     *
+     * @returns A cloned DataHeaderCell.
+     */
     clone() {
         return new DataHeaderCell({
             id: this.id,
@@ -85,12 +172,29 @@ export class DataHeaderCell extends FlatHeaderCell {
         });
     }
 }
+/**
+ * A flat header cell for display-only columns (e.g., action columns).
+ * Does not contain data accessor information.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export class FlatDisplayHeaderCell extends FlatHeaderCell {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __display = true;
+    /**
+     * Creates a new FlatDisplayHeaderCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, label = NBSP, colstart }) {
         super({ id, label, colstart });
     }
+    /**
+     * Creates a copy of this header cell.
+     *
+     * @returns A cloned FlatDisplayHeaderCell.
+     */
     clone() {
         return new FlatDisplayHeaderCell({
             id: this.id,
@@ -99,26 +203,56 @@ export class FlatDisplayHeaderCell extends FlatHeaderCell {
         });
     }
 }
+/**
+ * A header cell that spans multiple columns, used for column grouping.
+ * Contains information about which columns are part of the group.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export class GroupHeaderCell extends HeaderCell {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __group = true;
+    /** Current column IDs covered by this group. */
     ids;
+    /** Combined ID string for all columns in the original group. */
     allId;
+    /** All column IDs in the original group definition. */
     allIds;
+    /**
+     * Creates a new GroupHeaderCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ label, ids, allIds, colspan, colstart }) {
         super({ id: `[${ids.join(',')}]`, label, colspan, colstart });
         this.ids = ids;
         this.allId = `[${allIds.join(',')}]`;
         this.allIds = allIds;
     }
+    /**
+     * Sets the column IDs covered by this group and updates the cell ID.
+     *
+     * @param ids - The new array of column IDs.
+     */
     setIds(ids) {
         this.ids = ids;
         this.id = `[${this.ids.join(',')}]`;
     }
+    /**
+     * Adds a column ID to this group and updates the cell ID.
+     *
+     * @param id - The column ID to add.
+     */
     pushId(id) {
         this.ids = [...this.ids, id];
         this.id = `[${this.ids.join(',')}]`;
     }
+    /**
+     * Creates a copy of this header cell.
+     *
+     * @returns A cloned GroupHeaderCell.
+     */
     clone() {
         return new GroupHeaderCell({
             label: this.label,
@@ -129,12 +263,29 @@ export class GroupHeaderCell extends HeaderCell {
         });
     }
 }
+/**
+ * A group header cell for display purposes (e.g., empty group headers).
+ * Used to fill gaps in the header row matrix.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export class GroupDisplayHeaderCell extends GroupHeaderCell {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __display = true;
+    /**
+     * Creates a new GroupDisplayHeaderCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ label = NBSP, ids, allIds, colspan = 1, colstart }) {
         super({ label, ids, allIds, colspan, colstart });
     }
+    /**
+     * Creates a copy of this header cell.
+     *
+     * @returns A cloned GroupDisplayHeaderCell.
+     */
     clone() {
         return new GroupDisplayHeaderCell({
             label: this.label,

package/dist/headerRows.d.ts

@@ -3,24 +3,96 @@ import { type HeaderCell } from './headerCells.js';
 import { TableComponent } from './tableComponent.js';
 import type { Matrix } from './types/Matrix.js';
 import type { AnyPlugins } from './types/TablePlugin.js';
+/**
+ * HTML attributes for a header row element.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type HeaderRowAttributes<Item, Plugins extends AnyPlugins = AnyPlugins> = {
     role: 'row';
 };
+/**
+ * Initialization options for creating a HeaderRow.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export interface HeaderRowInit<Item, Plugins extends AnyPlugins = AnyPlugins> {
     id: string;
     cells: HeaderCell<Item, Plugins>[];
 }
+/**
+ * Represents a row in the table header.
+ * Contains header cells for column labels and group headers.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export declare class HeaderRow<Item, Plugins extends AnyPlugins = AnyPlugins> extends TableComponent<Item, Plugins, 'thead.tr'> {
+    /** The header cells in this row. */
     cells: HeaderCell<Item, Plugins>[];
+    /**
+     * Creates a new HeaderRow.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, cells }: HeaderRowInit<Item, Plugins>);
+    /**
+     * Gets the HTML attributes for this header row.
+     *
+     * @returns A readable store of row attributes.
+     */
     attrs(): import("svelte/store").Readable<{
         role: "row";
     }>;
+    /**
+     * Creates a copy of this header row.
+     *
+     * @returns A cloned HeaderRow.
+     */
     clone(): HeaderRow<Item, Plugins>;
 }
+/**
+ * Converts an array of columns into header rows for rendering.
+ * Handles nested column groups by creating multiple header rows.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @param columns - The column definitions.
+ * @param flatColumnIds - Optional array of column IDs for ordering.
+ * @returns An array of HeaderRow objects.
+ */
 export declare const getHeaderRows: <Item, Plugins extends AnyPlugins = AnyPlugins>(columns: Column<Item, Plugins>[], flatColumnIds?: string[]) => HeaderRow<Item, Plugins>[];
+/**
+ * Creates a matrix of header cells from column definitions.
+ * Each row in the matrix represents a header row, with cells positioned
+ * according to their column spans.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @param columns - The column definitions.
+ * @returns A matrix of HeaderCell objects.
+ */
 export declare const getHeaderRowMatrix: <Item, Plugins extends AnyPlugins = AnyPlugins>(columns: Column<Item, Plugins>[]) => Matrix<HeaderCell<Item, Plugins>>;
+/**
+ * Reorders a column matrix according to the specified column ID order.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @param columnMatrix - The original column matrix.
+ * @param flatColumnIds - The desired order of column IDs.
+ * @returns A reordered column matrix.
+ */
 export declare const getOrderedColumnMatrix: <Item, Plugins extends AnyPlugins = AnyPlugins>(columnMatrix: Matrix<HeaderCell<Item, Plugins>>, flatColumnIds: string[]) => Matrix<HeaderCell<Item, Plugins>>;
+/**
+ * Converts a row matrix into an array of HeaderRow objects.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @param rowMatrix - The matrix of header cells organized by rows.
+ * @returns An array of HeaderRow objects.
+ */
 export declare const headerRowsForRowMatrix: <Item, Plugins extends AnyPlugins = AnyPlugins>(rowMatrix: Matrix<HeaderCell<Item, Plugins>>) => HeaderRow<Item, Plugins>[];
 /**
  * Multi-colspan cells will appear as multiple adjacent cells on the same row.

package/dist/headerRows.js

@@ -3,12 +3,30 @@ import { TableComponent } from './tableComponent.js';
 import { sum } from './utils/math.js';
 import { getNullMatrix, getTransposed } from './utils/matrix.js';
 import { derived } from 'svelte/store';
+/**
+ * Represents a row in the table header.
+ * Contains header cells for column labels and group headers.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export class HeaderRow extends TableComponent {
+    /** The header cells in this row. */
     cells;
+    /**
+     * Creates a new HeaderRow.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, cells }) {
         super({ id });
         this.cells = cells;
     }
+    /**
+     * Gets the HTML attributes for this header row.
+     *
+     * @returns A readable store of row attributes.
+     */
     attrs() {
         return derived(super.attrs(), ($baseAttrs) => {
             return {
@@ -17,6 +35,11 @@ export class HeaderRow extends TableComponent {
             };
         });
     }
+    /**
+     * Creates a copy of this header row.
+     *
+     * @returns A cloned HeaderRow.
+     */
     clone() {
         return new HeaderRow({
             id: this.id,
@@ -24,6 +47,16 @@ export class HeaderRow extends TableComponent {
         });
     }
 }
+/**
+ * Converts an array of columns into header rows for rendering.
+ * Handles nested column groups by creating multiple header rows.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @param columns - The column definitions.
+ * @param flatColumnIds - Optional array of column IDs for ordering.
+ * @returns An array of HeaderRow objects.
+ */
 export const getHeaderRows = (columns, flatColumnIds = []) => {
     const rowMatrix = getHeaderRowMatrix(columns);
     // Perform all column operations on the transposed columnMatrix. This helps
@@ -34,6 +67,16 @@ export const getHeaderRows = (columns, flatColumnIds = []) => {
     populateGroupHeaderCellIds(columnMatrix);
     return headerRowsForRowMatrix(getTransposed(columnMatrix));
 };
+/**
+ * Creates a matrix of header cells from column definitions.
+ * Each row in the matrix represents a header row, with cells positioned
+ * according to their column spans.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @param columns - The column definitions.
+ * @returns A matrix of HeaderCell objects.
+ */
 export const getHeaderRowMatrix = (columns) => {
     const maxColspan = sum(columns.map((c) => (c.isGroup() ? c.ids.length : 1)));
     const maxHeight = Math.max(...columns.map((c) => c.height));
@@ -96,6 +139,15 @@ const loadHeaderRowMatrix = (rowMatrix, column, rowOffset, cellOffset) => {
         return;
     }
 };
+/**
+ * Reorders a column matrix according to the specified column ID order.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @param columnMatrix - The original column matrix.
+ * @param flatColumnIds - The desired order of column IDs.
+ * @returns A reordered column matrix.
+ */
 export const getOrderedColumnMatrix = (columnMatrix, flatColumnIds) => {
     if (flatColumnIds.length === 0) {
         return columnMatrix;
@@ -134,6 +186,14 @@ const populateGroupHeaderCellIds = (columnMatrix) => {
         });
     });
 };
+/**
+ * Converts a row matrix into an array of HeaderRow objects.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @param rowMatrix - The matrix of header cells organized by rows.
+ * @returns An array of HeaderRow objects.
+ */
 export const headerRowsForRowMatrix = (rowMatrix) => {
     return rowMatrix.map((rowCells, rowIdx) => {
         return new HeaderRow({ id: rowIdx.toString(), cells: getMergedRow(rowCells) });

package/dist/plugins/addColumnFilters.d.ts

@@ -3,37 +3,138 @@ import { type Readable, type Writable } from 'svelte/store';
 import type { BodyRow } from '../bodyRows.js';
 import type { PluginInitTableState } from '../createViewModel.js';
 import type { NewTablePropSet, TablePlugin } from '../types/TablePlugin.js';
+/**
+ * Configuration options for the addColumnFilters plugin.
+ */
 export interface ColumnFiltersConfig {
+    /** If true, filtering is handled server-side and all rows are returned. */
     serverSide?: boolean;
 }
+/**
+ * State exposed by the addColumnFilters plugin.
+ *
+ * @template Item - The type of data items in the table.
+ */
 export interface ColumnFiltersState<Item> {
+    /** Writable store containing filter values keyed by column ID. */
     filterValues: Writable<Record<string, unknown>>;
+    /** Readable store containing rows before filtering was applied. */
     preFilteredRows: Readable<BodyRow<Item>[]>;
 }
+/**
+ * Per-column configuration options for column filters.
+ *
+ * @template Item - The type of data items in the table.
+ * @template FilterValue - The type of the filter value.
+ */
 export interface ColumnFiltersColumnOptions<Item, FilterValue = any> {
+    /** The filter function to use for this column. */
     fn: ColumnFilterFn<FilterValue>;
+    /** Initial filter value for this column. */
     initialFilterValue?: FilterValue;
+    /** Optional render function for custom filter UI. */
     render?: (props: ColumnRenderConfigPropArgs<Item, FilterValue>) => RenderConfig;
 }
+/**
+ * Props passed to the column filter render function.
+ *
+ * @template Item - The type of data items.
+ * @template FilterValue - The type of the filter value.
+ * @template Value - The type of cell values.
+ */
 interface ColumnRenderConfigPropArgs<Item, FilterValue = any, Value = any> extends PluginInitTableState<Item> {
+    /** The column ID. */
     id: string;
+    /** Writable store for the filter value. */
     filterValue: Writable<FilterValue>;
+    /** Readable store of all current column values (after filtering). */
     values: Readable<Value[]>;
+    /** Readable store of rows before filtering. */
     preFilteredRows: Readable<BodyRow<Item>[]>;
+    /** Readable store of all column values before filtering. */
     preFilteredValues: Readable<Value[]>;
 }
+/**
+ * Function type for column filter implementations.
+ *
+ * @template FilterValue - The type of the filter value.
+ * @template Value - The type of cell values.
+ */
 export type ColumnFilterFn<FilterValue = any, Value = any> = (props: ColumnFilterFnProps<FilterValue, Value>) => boolean;
+/**
+ * Props passed to a ColumnFilterFn.
+ *
+ * @template FilterValue - The type of the filter value.
+ * @template Value - The type of cell values.
+ */
 export type ColumnFilterFnProps<FilterValue = any, Value = any> = {
+    /** The current filter value for this column. */
     filterValue: FilterValue;
+    /** The cell value being tested. */
     value: Value;
 };
+/**
+ * Props added to header cells by the column filters plugin.
+ */
 export type ColumnFiltersPropSet = NewTablePropSet<{
     'thead.tr.th': {
+        /** The rendered filter component. */
         render?: RenderConfig;
     } | undefined;
 }>;
+/**
+ * Creates a column filters plugin that enables per-column filtering with custom filter functions.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides column filtering functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   colFilter: addColumnFilters()
+ * })
+ *
+ * // Configure per-column in column definitions:
+ * table.column({
+ *   accessor: 'status',
+ *   header: 'Status',
+ *   plugins: {
+ *     colFilter: {
+ *       fn: matchFilter,
+ *       initialFilterValue: undefined
+ *     }
+ *   }
+ * })
+ * ```
+ */
 export declare const addColumnFilters: <Item>({ serverSide }?: ColumnFiltersConfig) => TablePlugin<Item, ColumnFiltersState<Item>, ColumnFiltersColumnOptions<Item>, ColumnFiltersPropSet>;
+/**
+ * A filter function that matches exact values.
+ * Returns true if filterValue is undefined or equals the cell value.
+ *
+ * @param props - The filter props containing filterValue and value.
+ * @returns True if the value matches the filter.
+ */
 export declare const matchFilter: ColumnFilterFn<unknown, unknown>;
+/**
+ * A filter function that matches text by prefix (case-insensitive).
+ * Returns true if filterValue is empty or value starts with filterValue.
+ *
+ * @param props - The filter props containing filterValue and value.
+ * @returns True if the value starts with the filter text.
+ */
 export declare const textPrefixFilter: ColumnFilterFn<string, string>;
+/**
+ * A filter function that matches numbers within a range.
+ * The range is [min, max] inclusive. Use null for unbounded.
+ *
+ * @param props - The filter props with a [min, max] filterValue and numeric value.
+ * @returns True if the value is within the specified range.
+ * @example
+ * ```typescript
+ * numberRangeFilter({ filterValue: [10, 50], value: 25 }) // true
+ * numberRangeFilter({ filterValue: [null, 100], value: 50 }) // true (no min)
+ * ```
+ */
 export declare const numberRangeFilter: ColumnFilterFn<[number | null, number | null], number>;
 export {};