@humanspeak/svelte-headless-table 6.0.2 → 6.0.3

package/dist/columns.d.ts

@@ -2,74 +2,278 @@ import type { DisplayBodyCell } from './bodyCells.js';
 import type { TableState } from './createViewModel.js';
 import type { DataLabel, DisplayLabel, HeaderLabel } from './types/Label.js';
 import type { AnyPlugins, PluginColumnConfigs } from './types/TablePlugin.js';
+/**
+ * Initialization options for a Column.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ */
 export interface ColumnInit<Item, Plugins extends AnyPlugins = AnyPlugins> {
+    /** The header label or render function. */
     header: HeaderLabel<Item, Plugins>;
+    /** Optional footer label or render function. */
     footer?: HeaderLabel<Item, Plugins>;
+    /** The height of the column in header rows (for grouping). */
     height: number;
+    /** Plugin-specific column configuration. */
     plugins?: PluginColumnConfigs<Plugins>;
 }
+/**
+ * Base class for all column types in the table.
+ * Provides type guards for determining the specific column type.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ */
 export declare class Column<Item, Plugins extends AnyPlugins = AnyPlugins> {
+    /** The header label or render function. */
     header: HeaderLabel<Item, Plugins>;
+    /** Optional footer label or render function. */
     footer?: HeaderLabel<Item, Plugins>;
+    /** The height of the column in header rows. */
     height: number;
+    /** Plugin-specific column configuration. */
     plugins?: PluginColumnConfigs<Plugins>;
+    /**
+     * Creates a new Column instance.
+     *
+     * @param init - The column initialization options.
+     */
     constructor({ header, footer, height, plugins }: ColumnInit<Item, Plugins>);
+    /**
+     * Type guard to check if this column is a FlatColumn (DataColumn or DisplayColumn).
+     *
+     * @returns True if this is a FlatColumn.
+     */
     isFlat(): this is FlatColumn<Item, Plugins>;
+    /**
+     * Type guard to check if this column is a DataColumn.
+     *
+     * @returns True if this is a DataColumn.
+     */
     isData(): this is DataColumn<Item, Plugins>;
+    /**
+     * Type guard to check if this column is a DisplayColumn.
+     *
+     * @returns True if this is a DisplayColumn.
+     */
     isDisplay(): this is DisplayColumn<Item, Plugins>;
+    /**
+     * Type guard to check if this column is a GroupColumn.
+     *
+     * @returns True if this is a GroupColumn.
+     */
     isGroup(): this is GroupColumn<Item, Plugins>;
 }
+/**
+ * Initialization options for a FlatColumn.
+ * Height is always 1 for flat columns.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @template Id - The column ID type.
+ */
 export type FlatColumnInit<Item, Plugins extends AnyPlugins = AnyPlugins, Id extends string = any> = Omit<ColumnInit<Item, Plugins>, 'height'> & {
+    /** Optional unique identifier for the column. Defaults to the header string. */
     id?: Id;
 };
+/**
+ * A column that occupies a single row in the header (not a group).
+ * Base class for DataColumn and DisplayColumn.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @template Id - The column ID type.
+ */
 export declare class FlatColumn<Item, Plugins extends AnyPlugins = AnyPlugins, Id extends string = any> extends Column<Item, Plugins> {
     __flat: boolean;
+    /** The unique identifier for this column. */
     id: Id;
+    /**
+     * Creates a new FlatColumn instance.
+     *
+     * @param init - The column initialization options.
+     */
     constructor({ header, footer, plugins, id }: FlatColumnInit<Item, Plugins>);
 }
+/**
+ * Full initialization type for a DataColumn.
+ * Supports three accessor patterns: key only, key with ID, or function with ID.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @template Id - The column ID type.
+ * @template Value - The type of the cell value.
+ */
 export type DataColumnInit<Item, Plugins extends AnyPlugins = AnyPlugins, Id extends string = string, Value = unknown> = DataColumnInitBase<Item, Plugins, Value> & ((Id extends keyof Item ? DataColumnInitKey<Item, Id> : never) | DataColumnInitIdAndKey<Item, Id, keyof Item> | DataColumnInitFnAndId<Item, Id, Value>);
+/**
+ * Base initialization options for a DataColumn.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @template Value - The type of the cell value.
+ */
 export type DataColumnInitBase<Item, Plugins extends AnyPlugins = AnyPlugins, Value = unknown> = Omit<ColumnInit<Item, Plugins>, 'height'> & {
+    /** Optional custom cell renderer. */
     cell?: DataLabel<Item, Plugins, Value>;
 };
+/**
+ * DataColumn init when using an accessor key that matches Item property.
+ *
+ * @template Item - The type of data items.
+ * @template Id - The key of Item to access.
+ */
 export type DataColumnInitKey<Item, Id extends keyof Item> = {
+    /** The property key to access on each item. */
     accessor: Id;
+    /** Optional ID override. Defaults to accessor key. */
     id?: Id;
 };
+/**
+ * DataColumn init when using an accessor key with a custom ID.
+ *
+ * @template Item - The type of data items.
+ * @template Id - The column ID type.
+ * @template Key - The key of Item to access.
+ */
 export type DataColumnInitIdAndKey<Item, Id extends string, Key extends keyof Item> = {
+    /** The property key to access on each item. */
     accessor: Key;
+    /** Optional custom ID for the column. */
     id?: Id;
 };
+/**
+ * DataColumn init when using an accessor function.
+ *
+ * @template Item - The type of data items.
+ * @template Id - The column ID type.
+ * @template Value - The return type of the accessor function.
+ */
 export type DataColumnInitFnAndId<Item, Id extends string, Value> = {
+    /** Function to extract the value from each item, or a property key. */
     accessor: keyof Item | ((item: Item) => Value);
+    /** Optional custom ID for the column. */
     id?: Id;
 };
+/**
+ * A column that displays data from the table items.
+ * Uses an accessor (key or function) to extract values from each row.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @template Id - The column ID type.
+ * @template Value - The type of the cell value.
+ */
 export declare class DataColumn<Item, Plugins extends AnyPlugins = AnyPlugins, Id extends string = any, Value = any> extends FlatColumn<Item, Plugins, Id> {
     __data: boolean;
+    /** Optional custom cell renderer. */
     cell?: DataLabel<Item, Plugins, Value>;
+    /** The property key used to access values (if using key accessor). */
     accessorKey?: keyof Item;
+    /** The function used to extract values (if using function accessor). */
     accessorFn?: (item: Item) => Value;
+    /**
+     * Creates a new DataColumn instance.
+     *
+     * @param init - The column initialization options.
+     * @throws Error if no id, accessor key, or header is provided.
+     */
     constructor({ header, footer, plugins, cell, accessor, id }: DataColumnInit<Item, Plugins, Id, Value>);
+    /**
+     * Extracts the value from a data item using the configured accessor.
+     *
+     * @param item - The data item to extract the value from.
+     * @returns The extracted value, or undefined if no accessor is configured.
+     */
     getValue(item: Item): any;
 }
+/**
+ * Function type for getting custom data from a DisplayColumn cell.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ */
 export type DisplayColumnDataGetter<Item, Plugins extends AnyPlugins = AnyPlugins> = (cell: DisplayBodyCell<Item>, state?: TableState<Item, Plugins>) => unknown;
+/**
+ * Initialization options for a DisplayColumn.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @template Id - The column ID type.
+ */
 export type DisplayColumnInit<Item, Plugins extends AnyPlugins = AnyPlugins, Id extends string = any> = FlatColumnInit<Item, Plugins, Id> & {
+    /** The cell renderer function. */
     cell: DisplayLabel<Item, Plugins>;
+    /** Optional function to provide custom data to the cell. */
     data?: DisplayColumnDataGetter<Item, Plugins>;
 };
+/**
+ * A column for displaying non-data content like actions, checkboxes, or custom UI.
+ * Unlike DataColumn, it doesn't extract values from the data items automatically.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @template Id - The column ID type.
+ */
 export declare class DisplayColumn<Item, Plugins extends AnyPlugins = AnyPlugins, Id extends string = any> extends FlatColumn<Item, Plugins, Id> {
     __display: boolean;
+    /** The cell renderer function. */
     cell: DisplayLabel<Item, Plugins>;
+    /** Optional function to provide custom data to the cell. */
     data?: DisplayColumnDataGetter<Item, Plugins>;
+    /**
+     * Creates a new DisplayColumn instance.
+     *
+     * @param init - The column initialization options.
+     */
     constructor({ header, footer, plugins, id, cell, data }: DisplayColumnInit<Item, Plugins, Id>);
 }
+/**
+ * Initialization options for a GroupColumn.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ */
 export type GroupColumnInit<Item, Plugins extends AnyPlugins = AnyPlugins> = Omit<ColumnInit<Item, Plugins>, 'height'> & {
+    /** The child columns contained within this group. */
     columns: Column<Item, Plugins>[];
 };
+/**
+ * A column that groups other columns under a shared header.
+ * Creates a hierarchical header structure.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ */
 export declare class GroupColumn<Item, Plugins extends AnyPlugins = AnyPlugins> extends Column<Item, Plugins> {
     __group: boolean;
+    /** The child columns contained within this group. */
     columns: Column<Item, Plugins>[];
+    /** The IDs of all flat columns within this group (recursively). */
     ids: string[];
+    /**
+     * Creates a new GroupColumn instance.
+     * Height is calculated as max child height + 1.
+     *
+     * @param init - The column initialization options.
+     */
     constructor({ header, footer, columns, plugins }: GroupColumnInit<Item, Plugins>);
 }
+/**
+ * Extracts all flat column IDs from an array of columns (including nested groups).
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @param columns - The array of columns to extract IDs from.
+ * @returns An array of column ID strings.
+ */
 export declare const getFlatColumnIds: <Item, Plugins extends AnyPlugins = AnyPlugins>(columns: Column<Item, Plugins>[]) => string[];
+/**
+ * Extracts all FlatColumns from an array of columns (including nested groups).
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @param columns - The array of columns to flatten.
+ * @returns An array of FlatColumn instances.
+ */
 export declare const getFlatColumns: <Item, Plugins extends AnyPlugins = AnyPlugins>(columns: Column<Item, Plugins>[]) => FlatColumn<Item, Plugins>[];

package/dist/columns.js

@@ -1,47 +1,115 @@
+/**
+ * Base class for all column types in the table.
+ * Provides type guards for determining the specific column type.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ */
 export class Column {
+    /** The header label or render function. */
     header;
+    /** Optional footer label or render function. */
     footer;
+    /** The height of the column in header rows. */
     height;
+    /** Plugin-specific column configuration. */
     plugins;
+    /**
+     * Creates a new Column instance.
+     *
+     * @param init - The column initialization options.
+     */
     constructor({ header, footer, height, plugins }) {
         this.header = header;
         this.footer = footer;
         this.height = height;
         this.plugins = plugins;
     }
+    /**
+     * Type guard to check if this column is a FlatColumn (DataColumn or DisplayColumn).
+     *
+     * @returns True if this is a FlatColumn.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isFlat() {
         return '__flat' in this;
     }
+    /**
+     * Type guard to check if this column is a DataColumn.
+     *
+     * @returns True if this is a DataColumn.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isData() {
         return '__data' in this;
     }
+    /**
+     * Type guard to check if this column is a DisplayColumn.
+     *
+     * @returns True if this is a DisplayColumn.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isDisplay() {
         return '__display' in this;
     }
+    /**
+     * Type guard to check if this column is a GroupColumn.
+     *
+     * @returns True if this is a GroupColumn.
+     */
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     isGroup() {
         return '__group' in this;
     }
 }
+/**
+ * A column that occupies a single row in the header (not a group).
+ * Base class for DataColumn and DisplayColumn.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @template Id - The column ID type.
+ */
 export class FlatColumn extends Column {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __flat = true;
+    /** The unique identifier for this column. */
     id;
+    /**
+     * Creates a new FlatColumn instance.
+     *
+     * @param init - The column initialization options.
+     */
     constructor({ header, footer, plugins, id }) {
         super({ header, footer, plugins, height: 1 });
         this.id = id ?? String(header);
     }
 }
+/**
+ * A column that displays data from the table items.
+ * Uses an accessor (key or function) to extract values from each row.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @template Id - The column ID type.
+ * @template Value - The type of the cell value.
+ */
 export class DataColumn extends FlatColumn {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __data = true;
+    /** Optional custom cell renderer. */
     cell;
+    /** The property key used to access values (if using key accessor). */
     accessorKey;
+    /** The function used to extract values (if using function accessor). */
     /* trunk-ignore(eslint/no-unused-vars) */
     accessorFn;
+    /**
+     * Creates a new DataColumn instance.
+     *
+     * @param init - The column initialization options.
+     * @throws Error if no id, accessor key, or header is provided.
+     */
     constructor({ header, footer, plugins, cell, accessor, id }) {
         super({ header, footer, plugins, id: 'Initialization not complete' });
         this.cell = cell;
@@ -57,6 +125,12 @@ export class DataColumn extends FlatColumn {
         const accessorKeyId = typeof this.accessorKey === 'string' ? this.accessorKey : null;
         this.id = (id ?? accessorKeyId ?? String(header));
     }
+    /**
+     * Extracts the value from a data item using the configured accessor.
+     *
+     * @param item - The data item to extract the value from.
+     * @returns The extracted value, or undefined if no accessor is configured.
+     */
     /* trunk-ignore(eslint/@typescript-eslint/no-explicit-any) */
     getValue(item) {
         if (this.accessorFn !== undefined) {
@@ -68,22 +142,52 @@ export class DataColumn extends FlatColumn {
         return undefined;
     }
 }
+/**
+ * A column for displaying non-data content like actions, checkboxes, or custom UI.
+ * Unlike DataColumn, it doesn't extract values from the data items automatically.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @template Id - The column ID type.
+ */
 export class DisplayColumn extends FlatColumn {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __display = true;
+    /** The cell renderer function. */
     cell;
+    /** Optional function to provide custom data to the cell. */
     data;
+    /**
+     * Creates a new DisplayColumn instance.
+     *
+     * @param init - The column initialization options.
+     */
     constructor({ header, footer, plugins, id, cell, data }) {
         super({ header, footer, plugins, id });
         this.cell = cell;
         this.data = data;
     }
 }
+/**
+ * A column that groups other columns under a shared header.
+ * Creates a hierarchical header structure.
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ */
 export class GroupColumn extends Column {
     // TODO Workaround for https://github.com/vitejs/vite/issues/9528
     __group = true;
+    /** The child columns contained within this group. */
     columns;
+    /** The IDs of all flat columns within this group (recursively). */
     ids;
+    /**
+     * Creates a new GroupColumn instance.
+     * Height is calculated as max child height + 1.
+     *
+     * @param init - The column initialization options.
+     */
     constructor({ header, footer, columns, plugins }) {
         const height = Math.max(...columns.map((c) => c.height)) + 1;
         super({ header, footer, height, plugins });
@@ -91,7 +195,23 @@ export class GroupColumn extends Column {
         this.ids = getFlatColumnIds(columns);
     }
 }
+/**
+ * Extracts all flat column IDs from an array of columns (including nested groups).
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @param columns - The array of columns to extract IDs from.
+ * @returns An array of column ID strings.
+ */
 export const getFlatColumnIds = (columns) => columns.flatMap((c) => (c.isFlat() ? [c.id] : c.isGroup() ? c.ids : []));
+/**
+ * Extracts all FlatColumns from an array of columns (including nested groups).
+ *
+ * @template Item - The type of data items in the table.
+ * @template Plugins - The plugins configuration type.
+ * @param columns - The array of columns to flatten.
+ * @returns An array of FlatColumn instances.
+ */
 export const getFlatColumns = (columns) => {
     return columns.flatMap((c) => (c.isFlat() ? [c] : c.isGroup() ? getFlatColumns(c.columns) : []));
 };

package/dist/constants.d.ts

@@ -1 +1,5 @@
+/**
+ * Non-breaking space character (U+00A0).
+ * Used as a placeholder in empty header cells to maintain proper rendering.
+ */
 export declare const NBSP = " ";

package/dist/constants.js

@@ -1 +1,5 @@
+/**
+ * Non-breaking space character (U+00A0).
+ * Used as a placeholder in empty header cells to maintain proper rendering.
+ */
 export const NBSP = ' ';

package/dist/createTable.d.ts

@@ -2,16 +2,123 @@ import { DataColumn, DisplayColumn, GroupColumn, type Column, type DataColumnIni
 import { type CreateViewModelOptions, type TableViewModel } from './createViewModel.js';
 import type { AnyPlugins } from './types/TablePlugin.js';
 import type { ReadOrWritable } from './utils/store.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 declare class Table<Item, Plugins extends AnyPlugins = AnyPlugins> {
+    /** The data source, either a Readable or Writable Svelte store. */
     data: ReadOrWritable<Item[]>;
+    /** The plugins configuration object. */
     plugins: 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: ReadOrWritable<Item[]>, 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: Column<Item, Plugins>[]): Column<Item, Plugins>[];
+    /**
+     * Creates a data column that displays values from the data items.
+     * Supports three initialization patterns:
+     * - `accessorKey` only: Uses a property key from Item
+     * - `accessorKey` and `id`: Uses a property key with a custom ID
+     * - `accessorFn` and `id`: Uses a function to extract values
+     *
+     * @param def - The column definition object.
+     * @returns A new DataColumn instance.
+     * @example
+     * ```typescript
+     * table.column({ accessor: 'name', header: 'Name' })
+     * table.column({ accessor: (item) => item.firstName + ' ' + item.lastName, header: 'Full Name', id: 'fullName' })
+     * ```
+     */
     column<Id extends Exclude<keyof Item, symbol>>(def: DataColumnInitBase<Item, Plugins, Item[Id]> & DataColumnInitKey<Item, Id>): DataColumn<Item, Plugins, `${Id}`, Item[Id]>;
     column<Id extends string, Key extends keyof Item>(def: DataColumnInitBase<Item, Plugins, Item[Key]> & DataColumnInitIdAndKey<Item, Id, Key>): DataColumn<Item, Plugins, Id, Item[Key]>;
     column<Id extends string, Value>(def: DataColumnInitBase<Item, Plugins, Value> & DataColumnInitFnAndId<Item, Id, Value>): DataColumn<Item, Plugins, Id, Value>;
+    /**
+     * 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: GroupColumnInit<Item, Plugins>): GroupColumn<Item, Plugins>;
+    /**
+     * 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: DisplayColumnInit<Item, Plugins>): DisplayColumn<Item, Plugins>;
+    /**
+     * 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: Column<Item, Plugins>[], options?: CreateViewModelOptions<Item>): TableViewModel<Item, Plugins>;
 }
+/**
+ * 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 declare const createTable: <Item, Plugins extends AnyPlugins = AnyPlugins>(data: ReadOrWritable<Item[]>, plugins?: Plugins) => Table<Item, Plugins>;