@humanspeak/svelte-headless-table 6.0.1 → 6.0.3

package/dist/createTable.js

@@ -1,13 +1,45 @@
 import { DataColumn, DisplayColumn, getFlatColumnIds, GroupColumn } from './columns.js';
 import { createViewModel } from './createViewModel.js';
 import { getDuplicates } from './utils/array.js';
+/**
+ * Core table class that provides methods for defining columns and creating view models.
+ * Use the `createTable` factory function to instantiate.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @example
+ * ```typescript
+ * const table = createTable(data, { sort: addSortBy(), filter: addTableFilter() })
+ * const columns = table.createColumns([
+ *   table.column({ accessor: 'name', header: 'Name' }),
+ *   table.column({ accessor: 'age', header: 'Age' })
+ * ])
+ * const viewModel = table.createViewModel(columns)
+ * ```
+ */
 export class Table {
+    /** The data source, either a Readable or Writable Svelte store. */
     data;
+    /** The plugins configuration object. */
     plugins;
+    /**
+     * Creates a new Table instance.
+     *
+     * @param data - A Svelte store containing the table data.
+     * @param plugins - The plugins to use with this table.
+     */
     constructor(data, plugins) {
         this.data = data;
         this.plugins = plugins;
     }
+    /**
+     * Validates and returns the column definitions.
+     * Throws an error if duplicate column IDs are detected.
+     *
+     * @param columns - Array of column definitions.
+     * @returns The same columns array if validation passes.
+     * @throws Error if duplicate column IDs are found.
+     */
     createColumns(columns) {
         const ids = getFlatColumnIds(columns);
         const duplicateIds = getDuplicates(ids);
@@ -19,16 +51,76 @@ export class Table {
     column(def) {
         return new DataColumn(def);
     }
+    /**
+     * Creates a group column that contains other columns.
+     * Used for creating hierarchical column headers.
+     *
+     * @param def - The group column definition.
+     * @returns A new GroupColumn instance.
+     * @example
+     * ```typescript
+     * table.group({
+     *   header: 'Personal Info',
+     *   columns: [
+     *     table.column({ accessor: 'firstName', header: 'First Name' }),
+     *     table.column({ accessor: 'lastName', header: 'Last Name' })
+     *   ]
+     * })
+     * ```
+     */
     group(def) {
         return new GroupColumn(def);
     }
+    /**
+     * Creates a display column for non-data content like actions or selection checkboxes.
+     *
+     * @param def - The display column definition.
+     * @returns A new DisplayColumn instance.
+     * @example
+     * ```typescript
+     * table.display({
+     *   id: 'actions',
+     *   header: '',
+     *   cell: ({ row }) => createRender(ActionButtons, { row })
+     * })
+     * ```
+     */
     display(def) {
         return new DisplayColumn(def);
     }
+    /**
+     * Creates a reactive view model from the table and columns.
+     * The view model provides all the data needed to render the table.
+     *
+     * @param columns - The column definitions.
+     * @param options - Optional configuration for the view model.
+     * @returns A TableViewModel with reactive stores for rendering.
+     */
     createViewModel(columns, options) {
         return createViewModel(this, columns, options);
     }
 }
+/**
+ * Factory function to create a new Table instance.
+ * This is the main entry point for using svelte-headless-table.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @param data - A Svelte store containing the table data.
+ * @param plugins - Optional plugins configuration object.
+ * @returns A new Table instance.
+ * @example
+ * ```typescript
+ * import { createTable } from 'svelte-headless-table'
+ * import { addSortBy, addPagination } from 'svelte-headless-table/plugins'
+ *
+ * const data = writable([{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }])
+ * const table = createTable(data, {
+ *   sort: addSortBy(),
+ *   page: addPagination({ initialPageSize: 10 })
+ * })
+ * ```
+ */
 export const createTable = (data, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 plugins = {}) => {

package/dist/createViewModel.d.ts

@@ -4,13 +4,74 @@ import type { Table } from './createTable.js';
 import { HeaderRow } from './headerRows.js';
 import type { AnyPlugins, PluginStates } from './types/TablePlugin.js';
 import { type Readable, type Writable } from 'svelte/store';
+/**
+ * HTML attributes for the table element.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type TableAttributes<Item, Plugins extends AnyPlugins = AnyPlugins> = Record<string, unknown> & {
     role: 'table';
 };
+/**
+ * HTML attributes for the table head element.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type TableHeadAttributes<Item, Plugins extends AnyPlugins = AnyPlugins> = Record<string, unknown>;
+/**
+ * HTML attributes for the table body element.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type TableBodyAttributes<Item, Plugins extends AnyPlugins = AnyPlugins> = Record<string, unknown> & {
     role: 'rowgroup';
 };
+/**
+ * Debug information for performance analysis of the table view model.
+ * Provides metrics about derivation chains and call counts.
+ */
+export interface ViewModelDebug {
+    /** Number of plugins active */
+    pluginCount: number;
+    /** Names of active plugins */
+    pluginNames: string[];
+    /** Number of derived stores in each chain */
+    derivedStoreCount: {
+        tableAttrs: number;
+        tableHeadAttrs: number;
+        tableBodyAttrs: number;
+        visibleColumns: number;
+        rows: number;
+        pageRows: number;
+    };
+    /** Counters that increment on each derivation execution */
+    derivationCalls: {
+        tableAttrs: number;
+        tableHeadAttrs: number;
+        tableBodyAttrs: number;
+        visibleColumns: number;
+        columnedRows: number;
+        rows: number;
+        injectedRows: number;
+        pageRows: number;
+        injectedPageRows: number;
+        headerRows: number;
+    };
+    /** Reset all derivation call counters to 0 */
+    resetCounters: () => void;
+    /** Get total derivation calls since last reset */
+    getTotalCalls: () => number;
+}
+/**
+ * The view model for a table, containing all reactive stores and state.
+ * Created by `createViewModel` and used to render the table.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export interface TableViewModel<Item, Plugins extends AnyPlugins = AnyPlugins> {
     flatColumns: FlatColumn<Item, Plugins>[];
     tableAttrs: Readable<TableAttributes<Item, Plugins>>;
@@ -22,17 +83,59 @@ export interface TableViewModel<Item, Plugins extends AnyPlugins = AnyPlugins> {
     rows: Readable<DataBodyRow<Item, Plugins>[]>;
     pageRows: Readable<DataBodyRow<Item, Plugins>[]>;
     pluginStates: PluginStates<Plugins>;
+    /** Debug information for performance analysis (always available) */
+    _debug: ViewModelDebug;
 }
+/**
+ * A type that can be either Readable or Writable.
+ *
+ * @template T - The type of the store value.
+ */
 export type ReadOrWritable<T> = Readable<T> | Writable<T>;
-export interface PluginInitTableState<Item, Plugins extends AnyPlugins = AnyPlugins> extends Omit<TableViewModel<Item, Plugins>, 'pluginStates'> {
+/**
+ * The table state passed to plugins during initialization.
+ * Contains references to all table stores before plugin states are available.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
+export interface PluginInitTableState<Item, Plugins extends AnyPlugins = AnyPlugins> extends Omit<TableViewModel<Item, Plugins>, 'pluginStates' | '_debug'> {
+    /** The data source for the table. */
     data: ReadOrWritable<Item[]>;
+    /** The column definitions. */
     columns: Column<Item, Plugins>[];
 }
-export interface TableState<Item, Plugins extends AnyPlugins = AnyPlugins> extends TableViewModel<Item, Plugins> {
+/**
+ * The complete table state including plugin states.
+ * Available to plugins and components after initialization.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
+export interface TableState<Item, Plugins extends AnyPlugins = AnyPlugins> extends Omit<TableViewModel<Item, Plugins>, '_debug'> {
+    /** The data source for the table. */
     data: ReadOrWritable<Item[]>;
+    /** The column definitions. */
     columns: Column<Item, Plugins>[];
 }
+/**
+ * Options for creating a table view model.
+ *
+ * @template Item - The type of data items in the table.
+ */
 export interface CreateViewModelOptions<Item> {
+    /** Optional function to generate a unique ID for each data item. */
     rowDataId?: (item: Item, index: number) => string;
 }
+/**
+ * Creates a view model for rendering a table.
+ * The view model contains all reactive stores for the table, headers, and rows.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @param table - The table instance created by `createTable`.
+ * @param columns - The column definitions.
+ * @param options - Optional configuration options.
+ * @returns A TableViewModel containing all reactive stores for rendering.
+ */
 export declare const createViewModel: <Item, Plugins extends AnyPlugins = AnyPlugins>(table: Table<Item, Plugins>, columns: Column<Item, Plugins>[], { rowDataId }?: CreateViewModelOptions<Item>) => TableViewModel<Item, Plugins>;

package/dist/createViewModel.js

@@ -4,8 +4,32 @@ import { getHeaderRows, HeaderRow } from './headerRows.js';
 import { finalizeAttributes } from './utils/attributes.js';
 import { nonUndefined } from './utils/filter.js';
 import { derived, readable, writable } from 'svelte/store';
+/**
+ * Creates a view model for rendering a table.
+ * The view model contains all reactive stores for the table, headers, and rows.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ * @param table - The table instance created by `createTable`.
+ * @param columns - The column definitions.
+ * @param options - Optional configuration options.
+ * @returns A TableViewModel containing all reactive stores for rendering.
+ */
 export const createViewModel = (table, columns, { rowDataId } = {}) => {
     const { data, plugins } = table;
+    // Initialize derivation call counters for debug instrumentation
+    const derivationCalls = {
+        tableAttrs: 0,
+        tableHeadAttrs: 0,
+        tableBodyAttrs: 0,
+        visibleColumns: 0,
+        columnedRows: 0,
+        rows: 0,
+        injectedRows: 0,
+        pageRows: 0,
+        injectedPageRows: 0,
+        headerRows: 0
+    };
     const $flatColumns = getFlatColumns(columns);
     const flatColumns = readable($flatColumns);
     const originalRows = derived([data, flatColumns], ([$data, $flatColumns]) => {
@@ -79,6 +103,7 @@ export const createViewModel = (table, columns, { rowDataId } = {}) => {
         tableAttrs = fn(tableAttrs);
     });
     const finalizedTableAttrs = derived(tableAttrs, ($tableAttrs) => {
+        derivationCalls.tableAttrs++;
         const $finalizedAttrs = finalizeAttributes($tableAttrs);
         _tableAttrs.set($finalizedAttrs);
         return $finalizedAttrs;
@@ -91,6 +116,7 @@ export const createViewModel = (table, columns, { rowDataId } = {}) => {
         tableHeadAttrs = fn(tableHeadAttrs);
     });
     const finalizedTableHeadAttrs = derived(tableHeadAttrs, ($tableHeadAttrs) => {
+        derivationCalls.tableHeadAttrs++;
         const $finalizedAttrs = finalizeAttributes($tableHeadAttrs);
         _tableHeadAttrs.set($finalizedAttrs);
         return $finalizedAttrs;
@@ -105,6 +131,7 @@ export const createViewModel = (table, columns, { rowDataId } = {}) => {
         tableBodyAttrs = fn(tableBodyAttrs);
     });
     const finalizedTableBodyAttrs = derived(tableBodyAttrs, ($tableBodyAttrs) => {
+        derivationCalls.tableBodyAttrs++;
         const $finalizedAttrs = finalizeAttributes($tableBodyAttrs);
         _tableBodyAttrs.set($finalizedAttrs);
         return $finalizedAttrs;
@@ -119,10 +146,12 @@ export const createViewModel = (table, columns, { rowDataId } = {}) => {
         visibleColumns = fn(visibleColumns);
     });
     const injectedColumns = derived(visibleColumns, ($visibleColumns) => {
+        derivationCalls.visibleColumns++;
         _visibleColumns.set($visibleColumns);
         return $visibleColumns;
     });
     const columnedRows = derived([originalRows, injectedColumns], ([$originalRows, $injectedColumns]) => {
+        derivationCalls.columnedRows++;
         return getColumnedBodyRows($originalRows, $injectedColumns.map((c) => c.id));
     });
     const deriveRowsFns = Object.values(pluginInstances)
@@ -134,6 +163,7 @@ export const createViewModel = (table, columns, { rowDataId } = {}) => {
         rows = fn(rows);
     });
     const injectedRows = derived(rows, ($rows) => {
+        derivationCalls.injectedRows++;
         // Inject state.
         $rows.forEach((row) => {
             row.injectState(tableState);
@@ -167,6 +197,7 @@ export const createViewModel = (table, columns, { rowDataId } = {}) => {
         pageRows = fn(pageRows);
     });
     const injectedPageRows = derived(pageRows, ($pageRows) => {
+        derivationCalls.injectedPageRows++;
         // Inject state.
         $pageRows.forEach((row) => {
             row.injectState(tableState);
@@ -191,6 +222,7 @@ export const createViewModel = (table, columns, { rowDataId } = {}) => {
         return $pageRows;
     });
     const headerRows = derived(injectedColumns, ($injectedColumns) => {
+        derivationCalls.headerRows++;
         const $headerRows = getHeaderRows(columns, $injectedColumns.map((c) => c.id));
         // Inject state.
         $headerRows.forEach((row) => {
@@ -215,6 +247,27 @@ export const createViewModel = (table, columns, { rowDataId } = {}) => {
         _headerRows.set($headerRows);
         return $headerRows;
     });
+    const _debug = {
+        pluginCount: Object.keys(plugins).length,
+        pluginNames: Object.keys(plugins),
+        derivedStoreCount: {
+            tableAttrs: deriveTableAttrsFns.length + 1, // +1 for finalized
+            tableHeadAttrs: deriveTableHeadAttrsFns.length + 1,
+            tableBodyAttrs: deriveTableBodyAttrsFns.length + 1,
+            visibleColumns: deriveFlatColumnsFns.length + 1, // +1 for injected
+            rows: deriveRowsFns.length + 2, // +2 for columned + injected
+            pageRows: derivePageRowsFns.length + 1 // +1 for injected
+        },
+        derivationCalls,
+        resetCounters: () => {
+            Object.keys(derivationCalls).forEach((key) => {
+                derivationCalls[key] = 0;
+            });
+        },
+        getTotalCalls: () => {
+            return Object.values(derivationCalls).reduce((sum, count) => sum + count, 0);
+        }
+    };
     return {
         tableAttrs: finalizedTableAttrs,
         tableHeadAttrs: finalizedTableHeadAttrs,
@@ -225,6 +278,7 @@ export const createViewModel = (table, columns, { rowDataId } = {}) => {
         originalRows,
         rows: injectedRows,
         pageRows: injectedPageRows,
-        pluginStates
+        pluginStates,
+        _debug
     };
 };

package/dist/headerCells.d.ts

@@ -2,79 +2,289 @@ import { TableComponent } from './tableComponent.js';
 import type { HeaderLabel } from './types/Label.js';
 import type { AnyPlugins } from './types/TablePlugin.js';
 import type { RenderConfig } from '@humanspeak/svelte-render';
+/**
+ * Initialization options for creating a HeaderCell.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type HeaderCellInit<Item, Plugins extends AnyPlugins = AnyPlugins> = {
+    /** Unique identifier for the cell. */
     id: string;
+    /** Label content or render function for the header. */
     label: HeaderLabel<Item, Plugins>;
+    /** Number of columns this cell spans. */
     colspan: number;
+    /** Starting column index. */
     colstart: number;
 };
+/**
+ * HTML attributes for a header cell element.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type HeaderCellAttributes<Item, Plugins extends AnyPlugins = AnyPlugins> = {
     role: 'columnheader';
     colspan: number;
 };
+/**
+ * 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 declare abstract class HeaderCell<Item, Plugins extends AnyPlugins = AnyPlugins> extends TableComponent<Item, Plugins, 'thead.tr.th'> {
+    /** Label content or render function for the header. */
     label: HeaderLabel<Item, Plugins>;
+    /** Number of columns this cell spans. */
     colspan: number;
+    /** Starting column index. */
     colstart: number;
+    /**
+     * Creates a new HeaderCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, label, colspan, colstart }: HeaderCellInit<Item, Plugins>);
+    /**
+     * 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(): RenderConfig;
+    /**
+     * Gets the HTML attributes for this header cell.
+     *
+     * @returns A readable store of cell attributes.
+     */
     attrs(): import("svelte/store").Readable<{
         role: "columnheader";
         colspan: number;
     }>;
     abstract clone(): HeaderCell<Item, Plugins>;
+    /**
+     * Type guard to check if this is a flat header cell.
+     *
+     * @returns True if this is a FlatHeaderCell.
+     */
     isFlat(): this is FlatHeaderCell<Item, Plugins>;
+    /**
+     * Type guard to check if this is a data header cell.
+     *
+     * @returns True if this is a DataHeaderCell.
+     */
     isData(): this is DataHeaderCell<Item, Plugins>;
+    /**
+     * Type guard to check if this is a flat display header cell.
+     *
+     * @returns True if this is a FlatDisplayHeaderCell.
+     */
     isFlatDisplay(): this is FlatDisplayHeaderCell<Item, Plugins>;
+    /**
+     * Type guard to check if this is a group header cell.
+     *
+     * @returns True if this is a GroupHeaderCell.
+     */
     isGroup(): this is GroupHeaderCell<Item, Plugins>;
+    /**
+     * Type guard to check if this is a group display header cell.
+     *
+     * @returns True if this is a GroupDisplayHeaderCell.
+     */
     isGroupDisplay(): this is GroupDisplayHeaderCell<Item, Plugins>;
 }
+/**
+ * Initialization options for a flat (non-grouped) header cell.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type FlatHeaderCellInit<Item, Plugins extends AnyPlugins = AnyPlugins> = Omit<HeaderCellInit<Item, Plugins>, 'colspan'>;
+/**
+ * HTML attributes for a flat header cell element.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type FlatHeaderCellAttributes<Item, Plugins extends AnyPlugins = AnyPlugins> = HeaderCellAttributes<Item, Plugins>;
+/**
+ * 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 declare class FlatHeaderCell<Item, Plugins extends AnyPlugins = AnyPlugins> extends HeaderCell<Item, Plugins> {
     __flat: boolean;
+    /**
+     * Creates a new FlatHeaderCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, label, colstart }: FlatHeaderCellInit<Item, Plugins>);
+    /**
+     * Creates a copy of this header cell.
+     *
+     * @returns A cloned FlatHeaderCell.
+     */
     clone(): FlatHeaderCell<Item, Plugins>;
 }
+/**
+ * Initialization options for a data header cell.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type DataHeaderCellInit<Item, Plugins extends AnyPlugins = AnyPlugins> = FlatHeaderCellInit<Item, Plugins> & {
+    /** The key used to access data from the item. */
     accessorKey?: keyof Item;
+    /** Function to extract data from the item. */
     accessorFn?: (item: Item) => unknown;
 };
+/**
+ * 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 declare class DataHeaderCell<Item, Plugins extends AnyPlugins = AnyPlugins> extends FlatHeaderCell<Item, Plugins> {
     __data: boolean;
+    /** The key used to access data from the item. */
     accessorKey?: keyof Item;
+    /** Function to extract data from the item. */
     accessorFn?: (item: Item) => unknown;
+    /**
+     * Creates a new DataHeaderCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, label, accessorKey, accessorFn, colstart }: DataHeaderCellInit<Item, Plugins>);
+    /**
+     * Creates a copy of this header cell.
+     *
+     * @returns A cloned DataHeaderCell.
+     */
     clone(): DataHeaderCell<Item, Plugins>;
 }
+/**
+ * Initialization options for a flat display header cell.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type FlatDisplayHeaderCellInit<Item, Plugins extends AnyPlugins = AnyPlugins> = Omit<FlatHeaderCellInit<Item, Plugins>, 'label'> & {
+    /** Optional label content (defaults to non-breaking space). */
     label?: HeaderLabel<Item, Plugins>;
 };
+/**
+ * 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 declare class FlatDisplayHeaderCell<Item, Plugins extends AnyPlugins = AnyPlugins> extends FlatHeaderCell<Item, Plugins> {
     __display: boolean;
+    /**
+     * Creates a new FlatDisplayHeaderCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ id, label, colstart }: FlatDisplayHeaderCellInit<Item, Plugins>);
+    /**
+     * Creates a copy of this header cell.
+     *
+     * @returns A cloned FlatDisplayHeaderCell.
+     */
     clone(): FlatDisplayHeaderCell<Item, Plugins>;
 }
+/**
+ * Initialization options for a group header cell.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type GroupHeaderCellInit<Item, Plugins extends AnyPlugins = AnyPlugins> = Omit<HeaderCellInit<Item, Plugins>, 'id'> & {
+    /** Current column IDs covered by this group. */
     ids: string[];
+    /** All column IDs in the original group definition. */
     allIds: string[];
 };
+/**
+ * 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 declare class GroupHeaderCell<Item, Plugins extends AnyPlugins = AnyPlugins> extends HeaderCell<Item, Plugins> {
     __group: boolean;
+    /** Current column IDs covered by this group. */
     ids: string[];
+    /** Combined ID string for all columns in the original group. */
     allId: string;
+    /** All column IDs in the original group definition. */
     allIds: string[];
+    /**
+     * Creates a new GroupHeaderCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ label, ids, allIds, colspan, colstart }: GroupHeaderCellInit<Item, Plugins>);
+    /**
+     * Sets the column IDs covered by this group and updates the cell ID.
+     *
+     * @param ids - The new array of column IDs.
+     */
     setIds(ids: string[]): void;
+    /**
+     * Adds a column ID to this group and updates the cell ID.
+     *
+     * @param id - The column ID to add.
+     */
     pushId(id: string): void;
+    /**
+     * Creates a copy of this header cell.
+     *
+     * @returns A cloned GroupHeaderCell.
+     */
     clone(): GroupHeaderCell<Item, Plugins>;
 }
+/**
+ * Initialization options for a group display header cell.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins used by the table.
+ */
 export type GroupDisplayHeaderCellInit<Item, Plugins extends AnyPlugins = AnyPlugins> = Omit<GroupHeaderCellInit<Item, Plugins>, 'label' | 'colspan'> & {
+    /** Optional label content (defaults to non-breaking space). */
     label?: HeaderLabel<Item, Plugins>;
+    /** Optional colspan (defaults to 1). */
     colspan?: number;
 };
+/**
+ * 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 declare class GroupDisplayHeaderCell<Item, Plugins extends AnyPlugins = AnyPlugins> extends GroupHeaderCell<Item, Plugins> {
     __display: boolean;
+    /**
+     * Creates a new GroupDisplayHeaderCell.
+     *
+     * @param init - Initialization options.
+     */
     constructor({ label, ids, allIds, colspan, colstart }: GroupDisplayHeaderCellInit<Item, Plugins>);
+    /**
+     * Creates a copy of this header cell.
+     *
+     * @returns A cloned GroupDisplayHeaderCell.
+     */
     clone(): GroupDisplayHeaderCell<Item, Plugins>;
 }