@humanspeak/svelte-headless-table/dist/createViewModel.d.ts

A powerful, headless table library for Svelte that provides complete control over table UI while handling complex data operations like sorting, filtering, pagination, grouping, and row expansion. Build custom, accessible data tables with zero styling opin

import { BodyRow, DataBodyRow } from './bodyRows.js';
import { FlatColumn, type Column } from './columns.js';
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;
    };
    /**
     * Per-derivation cumulative wall-clock in milliseconds, accumulated
     * via `performance.now()` deltas inside each `derived(...)` body.
     * Mirrors `derivationCalls` so the perf bench can attribute a
     * scenario's render budget to a specific derivation rather than the
     * aggregated `firstPaintMs`. Reset by `resetCounters()`.
     */
    derivationTimings: {
        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 and timings to 0 */
    resetCounters: () => void;
    /** Get total derivation calls since last reset */
    getTotalCalls: () => number;
    /** Get total derivation wall-clock (ms) since last reset */
    getTotalMs: () => 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>>;
    tableHeadAttrs: Readable<TableHeadAttributes<Item, Plugins>>;
    tableBodyAttrs: Readable<TableBodyAttributes<Item, Plugins>>;
    visibleColumns: Readable<FlatColumn<Item, Plugins>[]>;
    headerRows: Readable<HeaderRow<Item, Plugins>[]>;
    originalRows: Readable<BodyRow<Item, Plugins>[]>;
    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>;
/**
 * 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>[];
}
/**
 * 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>;