@humanspeak/svelte-headless-table 6.0.2 → 6.0.3

package/dist/plugins/addGroupBy.js

@@ -4,6 +4,10 @@ import { BodyRow, DisplayBodyRow } from '../bodyRows.js';
 import { isShiftClick } from '../utils/event.js';
 import { nonUndefined } from '../utils/filter.js';
 import { arraySetStore } from '../utils/store.js';
+/**
+ * Extracts the ID prefix from a row ID.
+ * @internal
+ */
 const getIdPrefix = (id) => {
     const prefixTokens = id.split('>').slice(0, -1);
     if (prefixTokens.length === 0) {
@@ -11,16 +15,29 @@ const getIdPrefix = (id) => {
     }
     return `${prefixTokens.join('>')}>`;
 };
-const getIdLeaf = (id) => {
-    const tokens = id.split('>');
-    return tokens[tokens.length - 1] ?? '';
-};
+/**
+ * Recursively updates row IDs and depths for nested grouped rows.
+ * @internal
+ */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const deepenIdAndDepth = (row, parentId) => {
     row.id = `${parentId}>${row.id}`;
     row.depth = row.depth + 1;
     row.subRows?.forEach((subRow) => deepenIdAndDepth(subRow, parentId));
 };
+/**
+ * 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 const getGroupedRows = (rows, groupByIds, columnOptions, { repeatCellIds, aggregateCellIds, groupCellIds, allGroupByIds }) => {
     if (groupByIds.length === 0) {
         return rows;
@@ -119,6 +136,33 @@ export const getGroupedRows = (rows, groupByIds, columnOptions, { repeatCellIds,
     }
     return groupedRows;
 };
+/**
+ * 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 const addGroupBy = ({ initialGroupByIds = [], disableMultiGroup = false, isMultiGroupEvent = isShiftClick } = {}) => ({ columnOptions }) => {
     const disabledGroupIds = Object.entries(columnOptions)
         .filter(([, option]) => option.disable === true)

package/dist/plugins/addHiddenColumns.d.ts

@@ -1,9 +1,36 @@
 import { type Writable } from 'svelte/store';
 import type { NewTablePropSet, TablePlugin } from '../types/TablePlugin.js';
+/**
+ * Configuration options for the addHiddenColumns plugin.
+ */
 export interface HiddenColumnsConfig {
+    /** Initial list of column IDs to hide. */
     initialHiddenColumnIds?: string[];
 }
+/**
+ * State exposed by the addHiddenColumns plugin.
+ */
 export interface HiddenColumnsState {
+    /** Writable store containing the list of hidden column IDs. */
     hiddenColumnIds: Writable<string[]>;
 }
+/**
+ * Creates a hidden columns plugin that enables showing/hiding table columns.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides column visibility control.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   hide: addHiddenColumns({
+ *     initialHiddenColumnIds: ['internalId', 'createdAt']
+ *   })
+ * })
+ *
+ * // Hide/show columns dynamically
+ * const { hiddenColumnIds } = table.pluginStates.hide
+ * hiddenColumnIds.update(ids => [...ids, 'newColumn'])
+ * ```
+ */
 export declare const addHiddenColumns: <Item>({ initialHiddenColumnIds }?: HiddenColumnsConfig) => TablePlugin<Item, HiddenColumnsState, Record<string, never>, NewTablePropSet<never>>;

package/dist/plugins/addHiddenColumns.js

@@ -1,4 +1,23 @@
 import { derived, writable } from 'svelte/store';
+/**
+ * Creates a hidden columns plugin that enables showing/hiding table columns.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides column visibility control.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   hide: addHiddenColumns({
+ *     initialHiddenColumnIds: ['internalId', 'createdAt']
+ *   })
+ * })
+ *
+ * // Hide/show columns dynamically
+ * const { hiddenColumnIds } = table.pluginStates.hide
+ * hiddenColumnIds.update(ids => [...ids, 'newColumn'])
+ * ```
+ */
 export const addHiddenColumns = ({ initialHiddenColumnIds = [] } = {}) => () => {
     const hiddenColumnIds = writable(initialHiddenColumnIds);
     const pluginState = { hiddenColumnIds };

package/dist/plugins/addPagination.d.ts

@@ -1,22 +1,45 @@
 import { type Readable, type Updater, type Writable } from 'svelte/store';
 import type { NewTablePropSet, TablePlugin } from '../types/TablePlugin.js';
+/**
+ * Configuration options for the addPagination plugin.
+ * Supports both client-side and server-side pagination modes.
+ */
 export type PaginationConfig = {
+    /** Initial page index (0-based). Defaults to 0. */
     initialPageIndex?: number;
+    /** Initial page size. Defaults to 10. */
     initialPageSize?: number;
 } & ({
+    /** Client-side pagination mode. */
     serverSide?: false | undefined;
     serverItemCount?: undefined;
 } | {
+    /** Server-side pagination mode. */
     serverSide: true;
+    /** A readable store containing the total item count from the server. */
     serverItemCount: Readable<number>;
 });
+/**
+ * State exposed by the addPagination plugin.
+ */
 export interface PaginationState {
+    /** Writable store for the current page size. */
     pageSize: Writable<number>;
+    /** Writable store for the current page index (0-based). */
     pageIndex: Writable<number>;
+    /** Readable store for the total number of pages. */
     pageCount: Readable<number>;
+    /** Readable store indicating if there's a previous page. */
     hasPreviousPage: Readable<boolean>;
+    /** Readable store indicating if there's a next page. */
     hasNextPage: Readable<boolean>;
 }
+/**
+ * Creates a page store with pagination state and navigation helpers.
+ *
+ * @param config - Configuration for the page store.
+ * @returns An object containing pagination state stores.
+ */
 export declare const createPageStore: ({ items, initialPageSize, initialPageIndex, serverSide, serverItemCount }: PageStoreConfig) => {
     pageSize: {
         subscribe: (this: void, run: import("svelte/store").Subscriber<number>, invalidate?: () => void) => import("svelte/store").Unsubscriber;
@@ -29,11 +52,42 @@ export declare const createPageStore: ({ items, initialPageSize, initialPageInde
     hasPreviousPage: Readable<boolean>;
     hasNextPage: Readable<boolean>;
 };
+/**
+ * Configuration for createPageStore.
+ */
 export interface PageStoreConfig {
+    /** Readable store of items to paginate. */
     items: Readable<unknown[]>;
+    /** Initial page size. */
     initialPageSize?: number;
+    /** Initial page index (0-based). */
     initialPageIndex?: number;
+    /** Whether pagination is server-side. */
     serverSide?: boolean;
+    /** Total item count from server (for server-side pagination). */
     serverItemCount?: Readable<number>;
 }
+/**
+ * Creates a pagination plugin that enables paged navigation through table rows.
+ * Supports both client-side and server-side pagination.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options for pagination.
+ * @returns A TablePlugin that provides pagination functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   page: addPagination({
+ *     initialPageSize: 20,
+ *     initialPageIndex: 0
+ *   })
+ * })
+ *
+ * // Navigate pages
+ * const { pageIndex, pageCount, hasNextPage } = table.pluginStates.page
+ * if ($hasNextPage) {
+ *   pageIndex.update(n => n + 1)
+ * }
+ * ```
+ */
 export declare const addPagination: <Item>({ initialPageIndex, initialPageSize, serverSide, serverItemCount }?: PaginationConfig) => TablePlugin<Item, PaginationState, Record<string, never>, NewTablePropSet<never>>;

package/dist/plugins/addPagination.js

@@ -1,5 +1,11 @@
 import { derived, writable } from 'svelte/store';
 const MIN_PAGE_SIZE = 1;
+/**
+ * Creates a page store with pagination state and navigation helpers.
+ *
+ * @param config - Configuration for the page store.
+ * @returns An object containing pagination state stores.
+ */
 export const createPageStore = ({ items, initialPageSize, initialPageIndex, serverSide, serverItemCount }) => {
     const pageSize = writable(initialPageSize);
     const updatePageSize = (fn) => {
@@ -47,6 +53,29 @@ export const createPageStore = ({ items, initialPageSize, initialPageIndex, serv
         hasNextPage
     };
 };
+/**
+ * Creates a pagination plugin that enables paged navigation through table rows.
+ * Supports both client-side and server-side pagination.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options for pagination.
+ * @returns A TablePlugin that provides pagination functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   page: addPagination({
+ *     initialPageSize: 20,
+ *     initialPageIndex: 0
+ *   })
+ * })
+ *
+ * // Navigate pages
+ * const { pageIndex, pageCount, hasNextPage } = table.pluginStates.page
+ * if ($hasNextPage) {
+ *   pageIndex.update(n => n + 1)
+ * }
+ * ```
+ */
 export const addPagination = ({ initialPageIndex = 0, initialPageSize = 10, serverSide = false, serverItemCount } = {}) => () => {
     const prePaginatedRows = writable([]);
     const paginatedRows = writable([]);

package/dist/plugins/addResizedColumns.d.ts

@@ -1,25 +1,50 @@
 import { type Writable } from 'svelte/store';
 import type { NewTableAttributeSet, NewTablePropSet, TablePlugin } from '../types/TablePlugin.js';
+/**
+ * Configuration options for the addResizedColumns plugin.
+ */
 export interface AddResizedColumnsConfig {
-    onResizeEnd?: (ev: Event) => void;
+    /** Callback fired when a resize operation ends. */
+    onResizeEnd?: (_ev: Event) => void;
 }
+/**
+ * State exposed by the addResizedColumns plugin.
+ */
 export type ResizedColumnsState = {
+    /** Writable store mapping column IDs to their current widths in pixels. */
     columnWidths: Writable<Record<string, number>>;
 };
+/**
+ * Per-column configuration options for resizing.
+ */
 export type ResizedColumnsColumnOptions = {
+    /** Initial width in pixels. */
     initialWidth?: number;
+    /** Minimum width in pixels. */
     minWidth?: number;
+    /** Maximum width in pixels. */
     maxWidth?: number;
+    /** If true, resizing is disabled for this column. */
     disable?: boolean;
 };
+/**
+ * Props added to table elements by the resized columns plugin.
+ */
 export type ResizedColumnsPropSet = NewTablePropSet<{
     'thead.tr.th': {
-        (node: Element): void;
-        drag: (node: Element) => void;
-        reset: (node: Element) => void;
+        /** Action to register the header cell element. */
+        (_node: Element): void;
+        /** Action to enable drag-to-resize on an element. */
+        drag: (_node: Element) => void;
+        /** Action to enable double-click-to-reset on an element. */
+        reset: (_node: Element) => void;
+        /** Whether resizing is disabled for this column. */
         disabled: boolean;
     };
 }>;
+/**
+ * Attributes added to table elements by the resized columns plugin.
+ */
 export type ResizedColumnsAttributeSet = NewTableAttributeSet<{
     'thead.tr.th': {
         style?: {
@@ -38,4 +63,33 @@ export type ResizedColumnsAttributeSet = NewTableAttributeSet<{
         };
     };
 }>;
+/**
+ * Creates a resized columns plugin that enables drag-to-resize column widths.
+ * Supports both mouse and touch interactions.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides column resizing functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   resize: addResizedColumns({
+ *     onResizeEnd: (event) => console.log('Resize ended')
+ *   })
+ * })
+ *
+ * // Configure per-column options
+ * table.column({
+ *   accessor: 'name',
+ *   header: 'Name',
+ *   plugins: {
+ *     resize: {
+ *       initialWidth: 200,
+ *       minWidth: 100,
+ *       maxWidth: 400
+ *     }
+ *   }
+ * })
+ * ```
+ */
 export declare const addResizedColumns: <Item>({ onResizeEnd }?: AddResizedColumnsConfig) => TablePlugin<Item, ResizedColumnsState, ResizedColumnsColumnOptions, ResizedColumnsPropSet, ResizedColumnsAttributeSet>;

package/dist/plugins/addResizedColumns.js

@@ -1,6 +1,10 @@
 import { keyed } from '@humanspeak/svelte-keyed';
 import { derived, writable } from 'svelte/store';
 import { sum } from '../utils/math.js';
+/**
+ * Gets the X position from a mouse or touch event.
+ * @internal
+ */
 const getDragXPos = (event) => {
     if (event instanceof MouseEvent)
         return event.clientX;
@@ -17,6 +21,35 @@ const isCellDisabled = (cell, disabledIds) => {
     }
     return false;
 };
+/**
+ * Creates a resized columns plugin that enables drag-to-resize column widths.
+ * Supports both mouse and touch interactions.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides column resizing functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   resize: addResizedColumns({
+ *     onResizeEnd: (event) => console.log('Resize ended')
+ *   })
+ * })
+ *
+ * // Configure per-column options
+ * table.column({
+ *   accessor: 'name',
+ *   header: 'Name',
+ *   plugins: {
+ *     resize: {
+ *       initialWidth: 200,
+ *       minWidth: 100,
+ *       maxWidth: 400
+ *     }
+ *   }
+ * })
+ * ```
+ */
 export const addResizedColumns = ({ onResizeEnd } = {}) => ({ columnOptions }) => {
     const disabledResizeIds = Object.entries(columnOptions)
         .filter(([, option]) => option.disable === true)

package/dist/plugins/addSelectedRows.d.ts

@@ -2,30 +2,86 @@ 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 SelectedRowsConfig<Item> {
+/**
+ * Configuration options for the addSelectedRows plugin.
+ *
+ * @template _Item - The type of data items (unused but required for type inference).
+ */
+export interface SelectedRowsConfig<_Item> {
+    /** Initial selection state keyed by data ID. */
     initialSelectedDataIds?: Record<string, boolean>;
+    /** If true, selecting a parent row selects all its sub-rows. Defaults to true. */
     linkDataSubRows?: boolean;
 }
+/**
+ * State exposed by the addSelectedRows plugin.
+ *
+ * @template Item - The type of data items in the table.
+ */
 export interface SelectedRowsState<Item> {
+    /** Store containing selected data IDs. */
     selectedDataIds: RecordSetStore<string>;
+    /** Writable store for selecting/deselecting all rows. */
     allRowsSelected: Writable<boolean>;
+    /** Readable store indicating if any rows are selected. */
     someRowsSelected: Readable<boolean>;
+    /** Writable store for selecting/deselecting all rows on the current page. */
     allPageRowsSelected: Writable<boolean>;
+    /** Readable store indicating if any rows on the current page are selected. */
     somePageRowsSelected: Readable<boolean>;
-    getRowState: (row: BodyRow<Item>) => SelectedRowsRowState;
+    /** Gets the selection state stores for a specific row. */
+    getRowState: (_row: BodyRow<Item>) => SelectedRowsRowState;
     /** Cleans up internal subscriptions and clears the row state cache. Call when destroying the table. */
     invalidate: () => void;
 }
+/**
+ * Selection state for a single row.
+ */
 export interface SelectedRowsRowState {
+    /** Writable store for the row's selection state. */
     isSelected: Writable<boolean>;
+    /** Readable store indicating if some (but not all) sub-rows are selected. */
     isSomeSubRowsSelected: Readable<boolean>;
+    /** Readable store indicating if all sub-rows are selected. */
     isAllSubRowsSelected: Readable<boolean>;
 }
+/**
+ * Props added to table rows by the selected rows plugin.
+ */
 export type SelectedRowsPropSet = NewTablePropSet<{
     'tbody.tr': {
+        /** Whether this row is selected. */
         selected: boolean;
+        /** Whether some (but not all) sub-rows are selected. */
         someSubRowsSelected: boolean;
+        /** Whether all sub-rows are selected. */
         allSubRowsSelected: boolean;
     };
 }>;
+/**
+ * Creates a row selection plugin that enables selecting/deselecting table rows.
+ * Supports hierarchical selection with parent-child row linking.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides row selection functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   select: addSelectedRows({
+ *     linkDataSubRows: true // Selecting parent selects children
+ *   })
+ * })
+ *
+ * // Access selection state
+ * const { selectedDataIds, allRowsSelected } = table.pluginStates.select
+ *
+ * // Toggle all rows
+ * allRowsSelected.set(true)
+ *
+ * // Check if a specific row is selected
+ * const rowState = table.pluginStates.select.getRowState(row)
+ * $rowState.isSelected // true or false
+ * ```
+ */
 export declare const addSelectedRows: <Item>({ initialSelectedDataIds, linkDataSubRows }?: SelectedRowsConfig<Item>) => TablePlugin<Item, SelectedRowsState<Item>, Record<string, never>, SelectedRowsPropSet>;

package/dist/plugins/addSelectedRows.js

@@ -3,6 +3,10 @@ import { derived, get } from 'svelte/store';
 import { nonNull } from '../utils/filter.js';
 import { recordSetStore } from '../utils/store.js';
 import { DEFAULT_ROW_STATE_CACHE_CONFIG } from './cacheConfig.js';
+/**
+ * Recursively checks if all sub-rows of a row are selected.
+ * @internal
+ */
 const isAllSubRowsSelectedForRow = (row, $selectedDataIds, linkDataSubRows) => {
     if (row.isData()) {
         if (!linkDataSubRows || row.subRows === undefined) {
@@ -14,6 +18,10 @@ const isAllSubRowsSelectedForRow = (row, $selectedDataIds, linkDataSubRows) => {
     }
     return row.subRows.every((subRow) => isAllSubRowsSelectedForRow(subRow, $selectedDataIds, linkDataSubRows));
 };
+/**
+ * Recursively checks if any sub-rows of a row are selected.
+ * @internal
+ */
 const isSomeSubRowsSelectedForRow = (row, $selectedDataIds, linkDataSubRows) => {
     if (row.isData()) {
         if (!linkDataSubRows || row.subRows === undefined) {
@@ -25,6 +33,10 @@ const isSomeSubRowsSelectedForRow = (row, $selectedDataIds, linkDataSubRows) =>
     }
     return row.subRows.some((subRow) => isSomeSubRowsSelectedForRow(subRow, $selectedDataIds, linkDataSubRows));
 };
+/**
+ * Recursively writes selection state for a row and its sub-rows.
+ * @internal
+ */
 const writeSelectedDataIds = (row, value, $selectedDataIds, linkDataSubRows) => {
     if (row.isData()) {
         $selectedDataIds[row.dataId] = value;
@@ -39,6 +51,10 @@ const writeSelectedDataIds = (row, value, $selectedDataIds, linkDataSubRows) =>
         writeSelectedDataIds(subRow, value, $selectedDataIds, linkDataSubRows);
     });
 };
+/**
+ * Creates a writable store for a row's selection state.
+ * @internal
+ */
 const getRowIsSelectedStore = (row, selectedDataIds, linkDataSubRows) => {
     const { subscribe } = derived(selectedDataIds, ($selectedDataIds) => {
         if (row.isData()) {
@@ -69,6 +85,32 @@ const getRowIsSelectedStore = (row, selectedDataIds, linkDataSubRows) => {
         set
     };
 };
+/**
+ * Creates a row selection plugin that enables selecting/deselecting table rows.
+ * Supports hierarchical selection with parent-child row linking.
+ *
+ * @template Item - The type of data items in the table.
+ * @param config - Configuration options.
+ * @returns A TablePlugin that provides row selection functionality.
+ * @example
+ * ```typescript
+ * const table = createTable(data, {
+ *   select: addSelectedRows({
+ *     linkDataSubRows: true // Selecting parent selects children
+ *   })
+ * })
+ *
+ * // Access selection state
+ * const { selectedDataIds, allRowsSelected } = table.pluginStates.select
+ *
+ * // Toggle all rows
+ * allRowsSelected.set(true)
+ *
+ * // Check if a specific row is selected
+ * const rowState = table.pluginStates.select.getRowState(row)
+ * $rowState.isSelected // true or false
+ * ```
+ */
 export const addSelectedRows = ({ initialSelectedDataIds = {}, linkDataSubRows = true } = {}) => ({ tableState }) => {
     const selectedDataIds = recordSetStore(initialSelectedDataIds);
     // LRU cache for memoized row state with automatic eviction.