@humanspeak/svelte-headless-table 6.0.2 → 6.0.3

package/dist/plugins/addColumnFilters.js

@@ -1,5 +1,9 @@
 import { keyed } from '@humanspeak/svelte-keyed';
 import { derived, writable } from 'svelte/store';
+/**
+ * Filters rows based on column filter values.
+ * @internal
+ */
 const getFilteredRows = (rows, filterValues, columnOptions) => {
     const $filteredRows = rows
         // Filter `subRows`
@@ -36,6 +40,31 @@ const getFilteredRows = (rows, filterValues, columnOptions) => {
     });
     return $filteredRows;
 };
+/**
+ * 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 const addColumnFilters = ({ serverSide = false } = {}) => ({ columnOptions, tableState }) => {
     const filterValues = writable({});
     const preFilteredRows = writable([]);
@@ -100,18 +129,44 @@ export const addColumnFilters = ({ serverSide = false } = {}) => ({ columnOption
         }
     };
 };
+/**
+ * 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 const matchFilter = ({ filterValue, value }) => {
     if (filterValue === undefined) {
         return true;
     }
     return filterValue === value;
 };
+/**
+ * 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 const textPrefixFilter = ({ filterValue, value }) => {
     if (filterValue === '') {
         return true;
     }
     return String(value).toLowerCase().startsWith(String(filterValue).toLowerCase());
 };
+/**
+ * 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 const numberRangeFilter = ({ filterValue: [min, max], value }) => {
     return (min ?? -Infinity) <= value && value <= (max ?? Infinity);
 };

package/dist/plugins/addColumnOrder.d.ts

@@ -1,10 +1,40 @@
 import { type Writable } from 'svelte/store';
 import type { NewTablePropSet, TablePlugin } from '../types/TablePlugin.js';
+/**
+ * Configuration options for the addColumnOrder plugin.
+ */
 export interface ColumnOrderConfig {
+    /** Initial order of column IDs. Columns are ordered in this sequence. */
     initialColumnIdOrder?: string[];
+    /** If true, columns not in the order list are hidden. Defaults to false. */
     hideUnspecifiedColumns?: boolean;
 }
+/**
+ * State exposed by the addColumnOrder plugin.
+ */
 export interface ColumnOrderState {
+    /** Writable store containing the ordered list of column IDs. */
     columnIdOrder: Writable<string[]>;
 }
+/**
+ * Creates a column order plugin that enables reordering table columns.
+ * Columns are displayed in the order specified by columnIdOrder.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides column ordering functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   order: addColumnOrder({
+ *     initialColumnIdOrder: ['name', 'age', 'email'],
+ *     hideUnspecifiedColumns: false
+ *   })
+ * })
+ *
+ * // Reorder columns dynamically
+ * const { columnIdOrder } = table.pluginStates.order
+ * columnIdOrder.set(['email', 'name', 'age'])
+ * ```
+ */
 export declare const addColumnOrder: <Item>({ initialColumnIdOrder, hideUnspecifiedColumns }?: ColumnOrderConfig) => TablePlugin<Item, ColumnOrderState, Record<string, never>, NewTablePropSet<never>>;

package/dist/plugins/addColumnOrder.js

@@ -1,4 +1,25 @@
 import { derived, writable } from 'svelte/store';
+/**
+ * Creates a column order plugin that enables reordering table columns.
+ * Columns are displayed in the order specified by columnIdOrder.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides column ordering functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   order: addColumnOrder({
+ *     initialColumnIdOrder: ['name', 'age', 'email'],
+ *     hideUnspecifiedColumns: false
+ *   })
+ * })
+ *
+ * // Reorder columns dynamically
+ * const { columnIdOrder } = table.pluginStates.order
+ * columnIdOrder.set(['email', 'name', 'age'])
+ * ```
+ */
 export const addColumnOrder = ({ initialColumnIdOrder = [], hideUnspecifiedColumns = false } = {}) => () => {
     const columnIdOrder = writable(initialColumnIdOrder);
     const pluginState = { columnIdOrder };

package/dist/plugins/addDataExport.d.ts

@@ -1,21 +1,72 @@
 import { type Readable } from 'svelte/store';
 import type { TablePlugin } from '../types/TablePlugin.js';
+/**
+ * Supported export formats for the data export plugin.
+ */
 export type DataExportFormat = 'object' | 'json' | 'csv';
+/**
+ * Maps export formats to their output types.
+ * @internal
+ */
 type ExportForFormat = {
     object: Record<string, unknown>[];
     json: string;
     csv: string;
 };
+/**
+ * The export output type based on the format.
+ *
+ * @template F - The export format.
+ */
 export type DataExport<F extends DataExportFormat> = ExportForFormat[F];
+/**
+ * Configuration options for the addDataExport plugin.
+ *
+ * @template F - The export format type.
+ */
 export interface DataExportConfig<F extends DataExportFormat> {
+    /** Key used for nested children in hierarchical exports. Defaults to 'children'. */
     childrenKey?: string;
+    /** Export format: 'object', 'json', or 'csv'. Defaults to 'object'. */
     format?: F;
 }
+/**
+ * State exposed by the addDataExport plugin.
+ *
+ * @template F - The export format type.
+ */
 export interface DataExportState<F extends DataExportFormat> {
+    /** Readable store containing the exported data in the specified format. */
     exportedData: Readable<DataExport<F>>;
 }
+/**
+ * Per-column configuration options for data export.
+ */
 export interface DataExportColumnOptions {
+    /** If true, this column is excluded from exports. */
     exclude?: boolean;
 }
+/**
+ * Creates a data export plugin that provides reactive exports of table data.
+ * Supports exporting to objects, JSON, or CSV formats.
+ *
+ * @template Item - The type of data items in the table.
+ * @template F - The export format type.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides data export functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   export: addDataExport({
+ *     format: 'csv',
+ *     childrenKey: 'subItems'
+ *   })
+ * })
+ *
+ * // Access exported data
+ * const { exportedData } = table.pluginStates.export
+ * $: csvData = $exportedData
+ * ```
+ */
 export declare const addDataExport: <Item, F extends DataExportFormat = "object">({ format, childrenKey }?: DataExportConfig<F>) => TablePlugin<Item, DataExportState<F>, DataExportColumnOptions>;
 export {};

package/dist/plugins/addDataExport.js

@@ -1,5 +1,9 @@
 import { derived, get } from 'svelte/store';
 import { isReadable } from '../utils/store.js';
+/**
+ * Converts rows to an array of plain objects.
+ * @internal
+ */
 const getObjectsFromRows = (rows, ids, childrenKey) => {
     return rows.map((row) => {
         const dataObject = Object.fromEntries(ids.map((id) => {
@@ -22,6 +26,10 @@ const getObjectsFromRows = (rows, ids, childrenKey) => {
         return dataObject;
     });
 };
+/**
+ * Converts rows to CSV format.
+ * @internal
+ */
 const getCsvFromRows = (rows, ids) => {
     const dataLines = rows.map((row) => {
         const line = ids.map((id) => {
@@ -43,6 +51,28 @@ const getCsvFromRows = (rows, ids) => {
     const headerLine = ids.join(',');
     return headerLine + '\n' + dataLines.join('\n');
 };
+/**
+ * Creates a data export plugin that provides reactive exports of table data.
+ * Supports exporting to objects, JSON, or CSV formats.
+ *
+ * @template Item - The type of data items in the table.
+ * @template F - The export format type.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides data export functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   export: addDataExport({
+ *     format: 'csv',
+ *     childrenKey: 'subItems'
+ *   })
+ * })
+ *
+ * // Access exported data
+ * const { exportedData } = table.pluginStates.export
+ * $: csvData = $exportedData
+ * ```
+ */
 export const addDataExport = ({ format = 'object', childrenKey = 'children' } = {}) => ({ tableState, columnOptions }) => {
     const excludedIds = Object.entries(columnOptions)
         .filter(([, option]) => option.exclude === true)

package/dist/plugins/addExpandedRows.d.ts

@@ -2,18 +2,57 @@ import { type Readable, type Writable } from 'svelte/store';
 import type { BodyRow } from '../bodyRows.js';
 import type { NewTablePropSet, TablePlugin } from '../types/TablePlugin.js';
 import { type RecordSetStore } from '../utils/store.js';
-export interface ExpandedRowsConfig<Item> {
+/**
+ * Configuration options for the addExpandedRows plugin.
+ *
+ * @template _Item - The type of data items (unused but required for type inference).
+ */
+export interface ExpandedRowsConfig<_Item> {
+    /** Initial expanded state keyed by row ID. */
     initialExpandedIds?: Record<string, boolean>;
 }
+/**
+ * State exposed by the addExpandedRows plugin.
+ *
+ * @template Item - The type of data items in the table.
+ */
 export interface ExpandedRowsState<Item> {
+    /** Store containing expanded row IDs. */
     expandedIds: RecordSetStore<string>;
-    getRowState: (row: BodyRow<Item>) => ExpandedRowsRowState;
+    /** Gets the expansion state stores for a specific row. */
+    getRowState: (_row: BodyRow<Item>) => ExpandedRowsRowState;
     /** Cleans up internal subscriptions and clears the row state cache. Call when destroying the table. */
     invalidate: () => void;
 }
+/**
+ * Expansion state for a single row.
+ */
 export interface ExpandedRowsRowState {
+    /** Writable store for the row's expanded state. */
     isExpanded: Writable<boolean>;
+    /** Readable store indicating if this row can be expanded (has sub-rows). */
     canExpand: Readable<boolean>;
+    /** Readable store indicating if all expandable sub-rows are expanded. */
     isAllSubRowsExpanded: Readable<boolean>;
 }
+/**
+ * Creates an expanded rows plugin that enables expanding/collapsing rows with sub-rows.
+ * When a row is expanded, its sub-rows are included in the flattened row list.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides row expansion functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   expand: addExpandedRows({
+ *     initialExpandedIds: { '0': true } // Row 0 starts expanded
+ *   })
+ * })
+ *
+ * // Toggle expansion
+ * const rowState = table.pluginStates.expand.getRowState(row)
+ * rowState.isExpanded.update(v => !v)
+ * ```
+ */
 export declare const addExpandedRows: <Item>({ initialExpandedIds }?: ExpandedRowsConfig<Item>) => TablePlugin<Item, ExpandedRowsState<Item>, Record<string, never>, NewTablePropSet<never>>;

package/dist/plugins/addExpandedRows.js

@@ -3,6 +3,10 @@ import { keyed } from '@humanspeak/svelte-keyed';
 import { derived, readable } from 'svelte/store';
 import { recordSetStore } from '../utils/store.js';
 import { DEFAULT_ROW_STATE_CACHE_CONFIG } from './cacheConfig.js';
+/**
+ * Recursively expands rows based on the expanded IDs map.
+ * @internal
+ */
 const withExpandedRows = (row, expandedIds) => {
     if (row.subRows === undefined) {
         return [row];
@@ -13,6 +17,26 @@ const withExpandedRows = (row, expandedIds) => {
     const expandedSubRows = row.subRows.flatMap((subRow) => withExpandedRows(subRow, expandedIds));
     return [row, ...expandedSubRows];
 };
+/**
+ * Creates an expanded rows plugin that enables expanding/collapsing rows with sub-rows.
+ * When a row is expanded, its sub-rows are included in the flattened row list.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides row expansion functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   expand: addExpandedRows({
+ *     initialExpandedIds: { '0': true } // Row 0 starts expanded
+ *   })
+ * })
+ *
+ * // Toggle expansion
+ * const rowState = table.pluginStates.expand.getRowState(row)
+ * rowState.isExpanded.update(v => !v)
+ * ```
+ */
 export const addExpandedRows = ({ initialExpandedIds = {} } = {}) => () => {
     const expandedIds = recordSetStore(initialExpandedIds);
     // LRU cache for memoized row state with automatic eviction.

package/dist/plugins/addFlatten.d.ts

@@ -1,19 +1,64 @@
 import { type Writable } from 'svelte/store';
 import type { BodyRow } from '../bodyRows.js';
 import type { NewTablePropSet, TablePlugin } from '../types/TablePlugin.js';
+/**
+ * Configuration options for the addFlatten plugin.
+ */
 export interface FlattenConfig {
+    /** Initial depth to flatten. 0 means no flattening. Defaults to 0. */
     initialDepth?: number;
 }
+/**
+ * State exposed by the addFlatten plugin.
+ */
 export interface FlattenState {
+    /** Writable store for the current flatten depth. */
     depth: Writable<number>;
 }
-export interface FlattenColumnOptions<Item> extends Record<string, never> {
-}
+/**
+ * Column options for the flatten plugin (currently empty).
+ *
+ * @template _Item - The type of data items (unused).
+ */
+export type FlattenColumnOptions<_Item> = Record<string, never>;
+/**
+ * Props added to table cells by the flatten plugin.
+ */
 export type FlattenPropSet = NewTablePropSet<{
     'tbody.tr.td': {
-        flatten: (depth: number) => void;
+        /** Function to set the flatten depth. */
+        flatten: (_depth: number) => void;
+        /** Function to reset flattening (set depth to 0). */
         unflatten: () => void;
     };
 }>;
+/**
+ * Recursively extracts rows at a specific depth from the hierarchy.
+ *
+ * @template Item - The type of data items.
+ * @template Row - The row type.
+ * @param rows - The rows to flatten.
+ * @param depth - The depth to extract (0 returns current level).
+ * @returns The flattened rows array.
+ */
 export declare const getFlattenedRows: <Item, Row extends BodyRow<Item>>(rows: Row[], depth: number) => Row[];
+/**
+ * Creates a flatten plugin that enables displaying rows at a specific depth level.
+ * Useful for showing only leaf nodes or a specific level of hierarchical data.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides flattening functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   flatten: addFlatten({
+ *     initialDepth: 0 // Start with no flattening
+ *   })
+ * })
+ *
+ * // Flatten to show only first-level children
+ * table.pluginStates.flatten.depth.set(1)
+ * ```
+ */
 export declare const addFlatten: <Item>({ initialDepth }?: FlattenConfig) => TablePlugin<Item, FlattenState, FlattenColumnOptions<Item>, FlattenPropSet>;

package/dist/plugins/addFlatten.js

@@ -1,4 +1,13 @@
 import { derived, writable } from 'svelte/store';
+/**
+ * Recursively extracts rows at a specific depth from the hierarchy.
+ *
+ * @template Item - The type of data items.
+ * @template Row - The row type.
+ * @param rows - The rows to flatten.
+ * @param depth - The depth to extract (0 returns current level).
+ * @returns The flattened rows array.
+ */
 export const getFlattenedRows = (rows, depth) => {
     if (depth === 0)
         return rows;
@@ -11,6 +20,25 @@ export const getFlattenedRows = (rows, depth) => {
     }
     return flattenedRows;
 };
+/**
+ * Creates a flatten plugin that enables displaying rows at a specific depth level.
+ * Useful for showing only leaf nodes or a specific level of hierarchical data.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides flattening functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   flatten: addFlatten({
+ *     initialDepth: 0 // Start with no flattening
+ *   })
+ * })
+ *
+ * // Flatten to show only first-level children
+ * table.pluginStates.flatten.depth.set(1)
+ * ```
+ */
 export const addFlatten = ({ initialDepth = 0 } = {}) => () => {
     const depth = writable(initialDepth);
     const pluginState = { depth };

package/dist/plugins/addGridLayout.d.ts

@@ -1,2 +1,15 @@
 import type { NewTablePropSet, TablePlugin } from '../types/TablePlugin.js';
+/**
+ * Creates a grid layout plugin that renders the table using CSS Grid.
+ * This allows for more flexible layouts and better handling of complex headers.
+ *
+ * @template Item - The type of data items in the table.
+ * @returns A TablePlugin that applies CSS Grid layout to the table.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   grid: addGridLayout()
+ * })
+ * ```
+ */
 export declare const addGridLayout: <Item>() => TablePlugin<Item, Record<string, never>, Record<string, never>, NewTablePropSet<never>>;

package/dist/plugins/addGridLayout.js

@@ -1,4 +1,17 @@
 import { derived } from 'svelte/store';
+/**
+ * Creates a grid layout plugin that renders the table using CSS Grid.
+ * This allows for more flexible layouts and better handling of complex headers.
+ *
+ * @template Item - The type of data items in the table.
+ * @returns A TablePlugin that applies CSS Grid layout to the table.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   grid: addGridLayout()
+ * })
+ * ```
+ */
 export const addGridLayout = () => ({ tableState }) => {
     const pluginState = {};
     const deriveTableAttrs = (attrs) => {

package/dist/plugins/addGroupBy.d.ts

@@ -2,39 +2,115 @@ import { BodyRow } from '../bodyRows.js';
 import type { DataLabel } from '../types/Label.js';
 import type { NewTablePropSet, TablePlugin } from '../types/TablePlugin.js';
 import { type ArraySetStore } from '../utils/store.js';
+/**
+ * Configuration options for the addGroupBy plugin.
+ */
 export interface GroupByConfig {
+    /** Initial list of column IDs to group by. */
     initialGroupByIds?: string[];
+    /** If true, prevents grouping by multiple columns. Defaults to false. */
     disableMultiGroup?: boolean;
-    isMultiGroupEvent?: (event: Event) => boolean;
+    /** Function to detect multi-group events (e.g., shift+click). Defaults to isShiftClick. */
+    isMultiGroupEvent?: (_event: Event) => boolean;
 }
+/**
+ * State exposed by the addGroupBy plugin.
+ */
 export interface GroupByState {
+    /** Store containing the list of column IDs to group by. */
     groupByIds: ArraySetStore<string>;
 }
+/**
+ * Per-column configuration options for grouping.
+ *
+ * @template Item - The type of data items.
+ * @template Value - The type of the cell value.
+ * @template GroupOn - The type to group on (must be string or number).
+ * @template Aggregate - The type of the aggregated value.
+ */
 export interface GroupByColumnOptions<Item, Value = any, GroupOn extends string | number = any, Aggregate = any> {
+    /** If true, grouping is disabled for this column. */
     disable?: boolean;
-    getAggregateValue?: (values: GroupOn[]) => Aggregate;
-    getGroupOn?: (value: Value) => GroupOn;
+    /** Function to compute an aggregate value from grouped values. */
+    getAggregateValue?: (_values: GroupOn[]) => Aggregate;
+    /** Function to extract the grouping key from a cell value. */
+    getGroupOn?: (_value: Value) => GroupOn;
+    /** Custom cell renderer for grouped rows. */
     cell?: DataLabel<Item>;
 }
+/**
+ * Props added to table elements by the group by plugin.
+ */
 export type GroupByPropSet = NewTablePropSet<{
     'thead.tr.th': {
+        /** Whether this column is currently grouped. */
         grouped: boolean;
-        toggle: (event: Event) => void;
+        /** Function to toggle grouping on this column. */
+        toggle: (_event: Event) => void;
+        /** Function to clear grouping on this column. */
         clear: () => void;
+        /** Whether grouping is disabled for this column. */
         disabled: boolean;
     };
     'tbody.tr.td': {
+        /** Whether this cell is a repeated group value (not the first in group). */
         repeated: boolean;
+        /** Whether this cell displays an aggregated value. */
         aggregated: boolean;
+        /** Whether this cell is the primary grouped column. */
         grouped: boolean;
     };
 }>;
+/**
+ * Internal options for getGroupedRows.
+ * @internal
+ */
 interface GetGroupedRowsProps {
     repeatCellIds: Record<string, boolean>;
     aggregateCellIds: Record<string, boolean>;
     groupCellIds: Record<string, boolean>;
     allGroupByIds: string[];
 }
+/**
+ * Groups rows by the specified column IDs, creating hierarchical grouped rows.
+ * Computes aggregate values for non-grouped columns.
+ *
+ * @template Item - The type of data items.
+ * @template Row - The row type.
+ * @template GroupOn - The grouping key type.
+ * @param rows - The rows to group.
+ * @param groupByIds - Column IDs to group by, in order.
+ * @param columnOptions - Per-column grouping configuration.
+ * @param props - Internal state tracking objects.
+ * @returns The grouped rows array.
+ */
 export declare const getGroupedRows: <Item, Row extends BodyRow<Item>, GroupOn extends string | number = any>(rows: Row[], groupByIds: string[], columnOptions: Record<string, GroupByColumnOptions<Item>>, { repeatCellIds, aggregateCellIds, groupCellIds, allGroupByIds }: GetGroupedRowsProps) => Row[];
+/**
+ * Creates a group by plugin that enables grouping rows by column values.
+ * Groups are hierarchical - grouping by multiple columns creates nested groups.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides grouping functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   group: addGroupBy({
+ *     initialGroupByIds: ['department']
+ *   })
+ * })
+ *
+ * // Configure aggregation for columns
+ * table.column({
+ *   accessor: 'salary',
+ *   header: 'Salary',
+ *   plugins: {
+ *     group: {
+ *       getAggregateValue: (values) => values.reduce((a, b) => a + b, 0)
+ *     }
+ *   }
+ * })
+ * ```
+ */
 export declare const addGroupBy: <Item>({ initialGroupByIds, disableMultiGroup, isMultiGroupEvent }?: GroupByConfig) => TablePlugin<Item, GroupByState, GroupByColumnOptions<Item>, GroupByPropSet>;
 export {};