@mikestools/usetable 0.0.1 → 0.0.3

package/dist/index.d.ts

@@ -1,173 +1,424 @@
 import { Ref } from 'vue';
 
-/** Cell change record for dirty tracking. @public */
+/**
+ * Configuration for custom aggregation.
+ */
+export declare interface AggregateConfig<T> {
+    /** Initial accumulator value */
+    readonly initial: T;
+    /** Reducer function */
+    readonly reducer: (accumulator: T, value: unknown, rowIndex: number) => T;
+}
+
+/**
+ * Base record interface - all records must have an id.
+ * This is the foundation for the shared reactive data schema.
+ */
+export declare interface BaseRecord {
+    /** Unique identifier - required on all records */
+    readonly id: string;
+}
+
+/**
+ * Cell change record for dirty tracking.
+ */
 export declare interface CellChange {
-    row: number;
-    column: number;
-    oldValue: unknown;
-    newValue: unknown;
+    /** Row index */
+    readonly row: number;
+    /** Column index */
+    readonly column: number;
+    /** Previous value */
+    readonly oldValue: unknown;
+    /** New value */
+    readonly newValue: unknown;
 }
 
-/** Configuration for a table cell with content and attributes. @public */
+/**
+ * Configuration for a table cell with content and attributes.
+ */
 export declare interface CellConfig {
-    value: unknown;
-    attributes?: ElementAttributes;
-    columnSpan?: number;
-    rowSpan?: number;
+    /** The cell value - can be any type including HTML elements */
+    readonly value: unknown;
+    /** Optional HTML attributes to apply to the cell */
+    readonly attributes?: ElementAttributes;
+    /** Column span (colspan attribute) */
+    readonly columnSpan?: number;
+    /** Row span (rowspan attribute) */
+    readonly rowSpan?: number;
 }
 
-/** Cell position for focus/navigation. @public */
+/**
+ * Cell position for focus/navigation.
+ */
 export declare interface CellPosition {
-    row: number;
-    column: number;
+    /** Row index */
+    readonly row: number;
+    /** Column index */
+    readonly column: number;
 }
 
+/**
+ * Validator function for a single cell.
+ * Returns true if valid, or a string error message if invalid.
+ */
 export declare type CellValidator = (value: unknown) => boolean | string;
 
-/** Configuration for a table column. @public */
+/**
+ * Configuration for a table column.
+ */
 export declare interface ColumnConfig {
-    header: string | CellConfig;
-    defaultValue?: unknown;
-    defaultAttributes?: ElementAttributes;
+    /** Header content - string or CellConfig */
+    readonly header: string | CellConfig;
+    /** Default value for new cells in this column */
+    readonly defaultValue?: unknown;
+    /** Default attributes for cells in this column */
+    readonly defaultAttributes?: ElementAttributes;
 }
 
-/** Column definition for type parsing/formatting. @public */
+/**
+ * Column definition for type parsing/formatting.
+ */
 export declare interface ColumnDefinition {
-    type: 'string' | 'number' | 'date' | 'boolean';
-    parser?: (value: unknown) => unknown;
-    formatter?: (value: unknown) => string;
-    defaultValue?: unknown;
-    nullable?: boolean;
+    /** Data type of the column */
+    readonly type: 'string' | 'number' | 'date' | 'boolean';
+    /** Custom parser function */
+    readonly parser?: (value: unknown) => unknown;
+    /** Custom formatter function */
+    readonly formatter?: (value: unknown) => string;
+    /** Default value when cell is empty */
+    readonly defaultValue?: unknown;
+    /** Whether null/undefined values are allowed */
+    readonly nullable?: boolean;
 }
 
-/** Computed column configuration. @public */
+/**
+ * Configuration for computed columns.
+ */
 export declare interface ComputedColumnConfig {
-    computeFunction: (row: unknown[]) => unknown;
-    label: string;
-    index?: number;
+    /** Function to compute the column value from row data */
+    readonly computeFunction: (row: unknown[]) => unknown;
+    /** Column header label */
+    readonly label: string;
+    /** Position to insert the column */
+    readonly index?: number;
 }
 
-/** Editable configuration. @public */
+/**
+ * Configuration for editable cells.
+ */
 export declare interface EditableConfig {
-    cells?: boolean;
-    headers?: boolean;
-    footers?: boolean;
-    editableColumns?: number[];
-    editableRows?: number[];
-    validator?: (value: string, row: number, col: number) => boolean | string;
-    parser?: (value: string, row: number, col: number) => unknown;
-    onEdit?: (value: unknown, row: number, col: number) => void;
+    /** Enable cell editing */
+    readonly cells?: boolean;
+    /** Enable header editing */
+    readonly headers?: boolean;
+    /** Enable footer editing */
+    readonly footers?: boolean;
+    /** Specific columns that are editable */
+    readonly editableColumns?: readonly number[];
+    /** Specific rows that are editable */
+    readonly editableRows?: readonly number[];
+    /** Validator function */
+    readonly validator?: (value: string, row: number, column: number) => boolean | string;
+    /** Parser function to convert string input to stored value */
+    readonly parser?: (value: string, row: number, column: number) => unknown;
+    /** Callback when a cell is edited */
+    readonly onEdit?: (value: unknown, row: number, column: number) => void;
 }
 
 /**
  * Comprehensive HTML element attributes for table elements.
- * @public
+ * Supports class, style, data attributes, ARIA attributes, and event handlers.
  */
 export declare interface ElementAttributes extends Partial<Omit<HTMLElement, 'style' | 'className' | 'classList' | 'children' | 'childNodes' | 'parentNode' | 'parentElement' | 'attributes' | 'tagName' | 'namespaceURI' | 'shadowRoot' | 'assignedSlot' | 'offsetParent' | 'offsetTop' | 'offsetLeft' | 'offsetWidth' | 'offsetHeight' | 'clientTop' | 'clientLeft' | 'clientWidth' | 'clientHeight' | 'scrollTop' | 'scrollLeft' | 'scrollWidth' | 'scrollHeight' | 'innerHTML' | 'outerHTML' | 'innerText' | 'outerText' | 'textContent' | 'addEventListener' | 'removeEventListener' | 'dispatchEvent' | 'getAttribute' | 'setAttribute' | 'removeAttribute' | 'hasAttribute' | 'appendChild' | 'removeChild' | 'replaceChild' | 'insertBefore' | 'querySelector' | 'querySelectorAll' | 'getElementsByTagName' | 'getElementsByClassName' | 'getElementById' | 'animate' | 'getAnimations' | 'attachShadow' | 'closest' | 'matches' | 'webkitMatchesSelector' | 'getBoundingClientRect' | 'getClientRects' | 'scrollIntoView' | 'scroll' | 'scrollBy' | 'scrollTo' | 'focus' | 'blur' | 'click'>>, Partial<GlobalEventHandlers>, Partial<ARIAMixin> {
+    /** CSS class - string, array of strings, or object with boolean values */
     class?: string | string[] | Record<string, boolean>;
+    /** Inline styles - string or object */
     style?: string | Partial<CSSStyleDeclaration> | Record<string, string | number>;
+    /** Data attributes as object */
     dataset?: Record<string, string>;
-    [key: `data-${string}`]: string;
-    [key: `aria-${string}`]: string;
+    /** Data attributes with prefix */
+    [key: `data-${string}`]: string | undefined;
+    /** ARIA attributes with prefix */
+    [key: `aria-${string}`]: string | undefined;
+    /** Allow any other attributes */
     [key: string]: unknown;
 }
 
-/** Filter state for tracking row filtering. @public */
+/**
+ * Ensure a record has an ID, generating one if missing.
+ */
+export declare function ensureId<T extends Record<string, unknown>>(record: T, generator?: IdGenerator): T & {
+    id: string;
+};
+
+/**
+ * Filter state for tracking row filtering.
+ */
 export declare interface FilterState {
+    /** Whether any filter is active */
     readonly isFiltered: Readonly<Ref<boolean>>;
+    /** Number of visible rows after filtering */
     readonly filteredRowCount: Readonly<Ref<number>>;
+    /** Indices of visible rows */
     readonly filteredIndices: Readonly<Ref<readonly number[]>>;
 }
 
-export declare type FullValidator = (value: unknown, row: number, col: number) => string | null;
+/**
+ * Find record by ID in array.
+ */
+export declare function findById<T extends BaseRecord>(records: readonly T[], id: string): T | undefined;
+
+/**
+ * Validator function for all cells.
+ * Returns null if valid, or a string error message if invalid.
+ */
+export declare type FullValidator = (value: unknown, row: number, column: number) => string | null;
+
+/**
+ * Default ID generator using crypto.randomUUID.
+ */
+export declare function generateId(): string;
 
+/**
+ * Symbol for tracking auto-generated IDs.
+ * Internal use only - invisible to JSON.stringify, Object.keys, for...in.
+ */
+export declare const ID_GENERATED: unique symbol;
+
+/**
+ * ID generator function type.
+ */
+export declare type IdGenerator = () => string;
+
+/**
+ * Find record index by ID.
+ */
+export declare function indexById<T extends BaseRecord>(records: readonly T[], id: string): number;
+
+/**
+ * Type guard for CellConfig.
+ */
 export declare function isCellConfig(value: unknown): value is CellConfig;
 
+/**
+ * Type guard for ValidationError.
+ */
 export declare function isValidationError(value: unknown): value is ValidationError;
 
+/**
+ * Type guard for ValidationError array.
+ */
 export declare function isValidationErrorArray(value: unknown): value is ValidationError[];
 
+/**
+ * Type guard for ValidationResult.
+ */
 export declare function isValidationResult(value: unknown): value is ValidationResult;
 
-/** Pagination configuration. @public */
+/**
+ * Check if a value is a valid ID.
+ */
+export declare function isValidId(value: unknown): value is string;
+
+/**
+ * Pagination configuration.
+ */
 export declare interface PaginationConfig {
-    pageSize: number;
-    currentPage?: number;
+    /** Number of rows per page */
+    readonly pageSize: number;
+    /** Initial page (1-based) */
+    readonly currentPage?: number;
 }
 
-/** Pagination state. @public */
+/**
+ * Pagination state.
+ */
 export declare interface PaginationState {
-    totalPages: Readonly<Ref<number>>;
-    currentPage: Ref<number>;
-    pageSize: Ref<number>;
-    visibleRows: Ref<number[]>;
+    /** Total number of pages */
+    readonly totalPages: Readonly<Ref<number>>;
+    /** Current page (1-based) */
+    readonly currentPage: Ref<number>;
+    /** Number of rows per page */
+    readonly pageSize: Ref<number>;
+    /** Indices of visible rows on current page */
+    readonly visibleRows: Ref<number[]>;
 }
 
-/** Reactive wrapper for table cells. @public */
+/**
+ * Reactive wrapper for table cells.
+ */
 export declare interface ReactiveCellCollection {
+    /** All cell elements */
     readonly cells: Readonly<Ref<readonly HTMLTableCellElement[]>>;
+    /** Number of cells */
     readonly cellCount: Readonly<Ref<number>>;
 }
 
-/** Reactive wrapper for table rows. @public */
+/**
+ * Reactive wrapper for table rows.
+ */
 export declare interface ReactiveRowCollection {
+    /** All row elements */
     readonly rows: Readonly<Ref<readonly HTMLTableRowElement[]>>;
+    /** Number of rows */
     readonly rowCount: Readonly<Ref<number>>;
 }
 
-/** Reactive wrapper for tbody elements. @public */
+/**
+ * Reactive wrapper for tbody elements.
+ */
 export declare interface ReactiveTBodyCollection {
+    /** All tbody elements */
     readonly tBodies: Readonly<Ref<readonly HTMLTableSectionElement[]>>;
+    /** Number of tbody elements */
     readonly tBodyCount: Readonly<Ref<number>>;
 }
 
+/**
+ * Column definition for record-based tables.
+ * Maps record fields to table columns.
+ */
+export declare interface RecordColumnDef<T extends BaseRecord = BaseRecord> {
+    /** Field name (string) or accessor function */
+    readonly field: string | ((record: T) => unknown);
+    /** Column header text */
+    readonly header: string;
+    /** Format value for display */
+    readonly format?: (value: unknown, record: T) => string;
+    /** Parse display value back to data value */
+    readonly parse?: (value: string, record: T) => unknown;
+    /** Whether column is editable (default: true for fields, false for functions) */
+    readonly editable?: boolean;
+    /** Column width */
+    readonly width?: string | number;
+    /** Default value for new records */
+    readonly defaultValue?: unknown;
+}
+
+/**
+ * Options for record-based table configuration.
+ */
+export declare interface RecordTableOptions<T extends BaseRecord = BaseRecord> {
+    /** Column definitions mapping fields to columns */
+    readonly columns: readonly RecordColumnDef<T>[];
+    /** ID generator for new records */
+    readonly idGenerator?: IdGenerator;
+    /** Callback when a cell is edited */
+    readonly onCellEdit?: (recordId: string, field: keyof T | string, value: unknown) => void;
+    /** Callback when a row is inserted */
+    readonly onRowInsert?: (values: Omit<T, 'id'>) => void;
+    /** Callback when a row is deleted */
+    readonly onRowDelete?: (recordId: string) => void;
+    /** Callback when row selection changes */
+    readonly onRowSelect?: (recordId: string | null) => void;
+}
+
+/**
+ * Record-based table state.
+ */
+export declare interface RecordTableState<T extends BaseRecord = BaseRecord> {
+    /** All records in the table */
+    readonly records: readonly T[];
+    /** Currently selected record ID */
+    readonly selectedRecordId: string | null;
+    /** Record IDs in display order */
+    readonly displayOrder: readonly string[];
+}
+
+/**
+ * Validator function for a row.
+ * Returns true if valid, or a string error message if invalid.
+ */
 export declare type RowValidator = (rowData: unknown[]) => boolean | string;
 
-/** Search options. @public */
+/**
+ * Options for search operations.
+ */
 export declare interface SearchOptions {
-    caseSensitive?: boolean;
+    /** Whether search is case-sensitive */
+    readonly caseSensitive?: boolean;
 }
 
-/** Search result. @public */
+/**
+ * Search result for a found cell.
+ */
 export declare interface SearchResult {
-    row: number;
-    column: number;
-    value: unknown;
+    /** Row index */
+    readonly row: number;
+    /** Column index */
+    readonly column: number;
+    /** The found value */
+    readonly value: unknown;
 }
 
-/** Sort state for tracking column sorting. @public */
+/**
+ * Sort state for tracking column sorting.
+ */
 export declare interface SortState {
+    /** Currently sorted column index */
     readonly columnIndex: Readonly<Ref<number | null>>;
+    /** Whether sorted ascending */
     readonly ascending: Readonly<Ref<boolean>>;
+    /** Whether sorted descending */
     readonly descending: Readonly<Ref<boolean>>;
 }
 
-/** Table cell composable. @public */
+/**
+ * Strip generated ID from record (for export).
+ */
+export declare function stripGeneratedId<T extends {
+    id: string;
+}>(record: T): Omit<T, 'id'> | T;
+
+/**
+ * Table cell composable.
+ */
 export declare interface TableCell {
+    /** The cell element */
     readonly element: Readonly<Ref<HTMLTableCellElement>>;
+    /** Cell index within row */
     readonly cellIndex: Readonly<Ref<number>>;
+    /** Column span */
     readonly columnSpan: Ref<number>;
+    /** Row span */
     readonly rowSpan: Ref<number>;
+    /** Header IDs */
     readonly headers: Ref<string>;
+    /** Abbreviated text */
     readonly abbr: Ref<string>;
+    /** Scope (for th elements) */
     readonly scope: Ref<string>;
 }
 
-/** Table row composable. @public */
+/**
+ * Table row composable.
+ */
 export declare interface TableRow extends ReactiveCellCollection {
+    /** The row element */
     readonly element: Readonly<Ref<HTMLTableRowElement>>;
+    /** Row index in table */
     readonly rowIndex: Readonly<Ref<number>>;
+    /** Row index in parent section */
     readonly sectionRowIndex: Readonly<Ref<number>>;
+    /** Insert a cell at index */
     insertCell(index?: number): HTMLTableCellElement;
+    /** Delete a cell at index */
     deleteCell(index: number): void;
+    /** Get TableCell composable for cell at index */
     getCell(index: number): TableCell | undefined;
 }
 
-/** Table section composable. @public */
+/**
+ * Table section composable.
+ */
 export declare interface TableSection extends ReactiveRowCollection {
+    /** The section element */
     readonly element: Readonly<Ref<HTMLTableSectionElement>>;
+    /** Insert a row at index */
     insertRow(index?: number): HTMLTableRowElement;
+    /** Delete a row at index */
     deleteRow(index: number): void;
+    /** Get TableRow composable for row at index */
     getRow(index: number): TableRow | undefined;
 }
 
@@ -178,327 +429,747 @@ export declare interface TableSection extends ReactiveRowCollection {
  */
 export declare function useTable(element: Ref<HTMLTableElement>): UseTableReturn;
 
-/** Main table composable return type. @public */
+/**
+ * Main table composable return type.
+ *
+ * Provides comprehensive table manipulation capabilities including:
+ * - DOM structure methods
+ * - Data layer methods
+ * - Sorting, filtering, and searching
+ * - Selection and focus management
+ * - Validation and transformation
+ * - Import/export functionality
+ * - Undo/redo support
+ * - Pagination and virtual scrolling
+ */
 export declare interface UseTableReturn extends ReactiveRowCollection, ReactiveTBodyCollection {
+    /** The table element */
     readonly element: Readonly<Ref<HTMLTableElement>>;
+    /** Caption element */
     readonly caption: Ref<HTMLTableCaptionElement | null>;
+    /** Thead element */
     readonly tHead: Ref<HTMLTableSectionElement | null>;
+    /** Tfoot element */
     readonly tFoot: Ref<HTMLTableSectionElement | null>;
+    /** Table body data as 2D array */
     readonly data: Ref<unknown[][]>;
+    /** Header texts */
     readonly headers: Ref<string[]>;
+    /** Number of columns */
     readonly columnCount: Readonly<Ref<number>>;
+    /** Create or get existing caption */
     createCaption(): HTMLTableCaptionElement;
+    /** Delete caption */
     deleteCaption(): void;
+    /** Create or get existing thead */
     createTHead(): HTMLTableSectionElement;
+    /** Delete thead */
     deleteTHead(): void;
+    /** Create or get existing tfoot */
     createTFoot(): HTMLTableSectionElement;
+    /** Delete tfoot */
     deleteTFoot(): void;
+    /** Create new tbody */
     createTBody(): HTMLTableSectionElement;
+    /** Insert row at index */
     insertRow(index?: number): HTMLTableRowElement;
+    /** Delete row at index */
     deleteRow(index: number): void;
+    /** Get thead as TableSection */
     getTHead(): TableSection | undefined;
+    /** Get tfoot as TableSection */
     getTFoot(): TableSection | undefined;
+    /** Get tbody at index as TableSection */
     getTBody(index: number): TableSection | undefined;
+    /** Get row at index as TableRow */
     getRow(index: number): TableRow | undefined;
+    /** Add a row with data */
     addRow(rowData: readonly unknown[], index?: number): HTMLTableRowElement;
+    /** Remove row at index */
     removeRow(index: number): void;
+    /** Add a column */
     addColumn(headerText?: string, defaultValue?: unknown, index?: number): void;
+    /** Remove column at index */
     removeColumn(index: number): void;
+    /** Set cell value */
     setCell(rowIndex: number, columnIndex: number, value: unknown): void;
+    /** Get cell value */
     getCell(rowIndex: number, columnIndex: number): unknown;
+    /** Set caption text */
     setCaption(text: string): void;
+    /** Set all headers */
     setHeaders(headerTexts: readonly string[]): void;
+    /** Set footer row */
     setFooter(footerData: readonly unknown[]): void;
+    /** Set all data */
     setData(newData: readonly (readonly unknown[])[]): void;
+    /** Clear body data (keep headers) */
     clearData(): void;
+    /** Reset entire table */
     reset(): void;
+    /** Sync reactive state with DOM */
     sync(): void;
+    /** Add row with cell configs */
     addRowWithAttributes(rowData: readonly (unknown | CellConfig)[], attributes?: ElementAttributes, index?: number): HTMLTableRowElement;
+    /** Add column with config */
     addColumnWithAttributes(config: ColumnConfig, index?: number): void;
+    /** Set headers with configs */
     setHeadersWithAttributes(headerConfigs: readonly (string | CellConfig)[]): void;
+    /** Set cell with attributes */
     setCellWithAttributes(rowIndex: number, columnIndex: number, value: unknown, attributes?: ElementAttributes): void;
+    /** Get row data copy */
     getRowData(index: number): unknown[] | undefined;
+    /** Set row data */
     setRowData(index: number, rowData: readonly unknown[]): void;
+    /** Get all row data as copy */
     getAllRowData(): unknown[][];
+    /** Get column data */
     getColumnData(index: number): unknown[];
+    /** Set column data */
     setColumnData(index: number, columnData: readonly unknown[]): void;
+    /** Get cell range */
     getCellRange(rowStart: number, rowEnd: number, columnStart: number, columnEnd: number): unknown[][];
+    /** Set cell range */
     setCellRange(rowStart: number, columnStart: number, rangeData: readonly (readonly unknown[])[]): void;
+    /** Get header data copy */
     getHeaderData(): string[];
+    /** Get footer data */
     getFooterData(): unknown[] | undefined;
+    /** Set footer cell */
     setFooterCell(columnIndex: number, value: unknown): void;
+    /** Get footer cell */
     getFooterCell(columnIndex: number): unknown;
+    /** Update cell with config */
     updateCell(rowIndex: number, columnIndex: number, config: CellConfig): void;
+    /** Update row data */
     updateRow(index: number, rowData: readonly (unknown | CellConfig)[]): void;
+    /** Get cell DOM element */
     getCellElement(rowIndex: number, columnIndex: number): HTMLTableCellElement | undefined;
+    /** Get row DOM element */
     getRowElement(index: number): HTMLTableRowElement | undefined;
+    /** Select multiple rows */
     selectRows(indices: readonly number[]): unknown[][];
+    /** Select multiple columns */
     selectColumns(indices: readonly number[]): unknown[][];
+    /** Update multiple rows */
     updateRows(updates: ReadonlyMap<number, readonly (unknown | CellConfig)[]>): void;
+    /** Update multiple cells */
     updateCells(updates: ReadonlyMap<readonly [number, number], unknown | CellConfig>): void;
+    /** Get all row elements */
     getRowElements(): readonly HTMLTableRowElement[];
+    /** Get cells for a row */
     getRowCellElements(rowIndex: number): readonly HTMLTableCellElement[];
+    /** Set multiple rows */
     setRows(startIndex: number, rows: readonly (readonly (unknown | CellConfig)[])[]): void;
+    /** Validate single cell */
     validateCell(rowIndex: number, columnIndex: number, validator: CellValidator): true | ValidationError;
+    /** Validate single row */
     validateRow(index: number, validator: RowValidator): true | ValidationError[];
+    /** Validate single column */
     validateColumn(index: number, validator: CellValidator): true | ValidationError[];
+    /** Validate all cells */
     validateAll(validator: FullValidator): ValidationResult;
+    /** Sum of column values */
     sum(columnIndex: number): number;
+    /** Average of column values */
     average(columnIndex: number): number;
+    /** Minimum value in column */
     min(columnIndex: number): unknown;
+    /** Maximum value in column */
     max(columnIndex: number): unknown;
+    /** Count values in column */
     count(columnIndex: number, predicate?: (value: unknown) => boolean): number;
-    aggregate<T>(columnIndex: number, options: {
-        initial: T;
-        reducer: (accumulator: T, value: unknown, rowIndex: number) => T;
-    }): T;
+    /** Custom aggregation */
+    aggregate<T>(columnIndex: number, options: AggregateConfig<T>): T;
+    /** Transform all cells in column */
     transformColumn(columnIndex: number, transformer: (value: unknown, rowIndex: number) => unknown): void;
+    /** Transform all cells in row */
     transformRow(rowIndex: number, transformer: (value: unknown, colIndex: number) => unknown): void;
+    /** Transform all cells */
     transformCells(transformer: (value: unknown, rowIndex: number, colIndex: number) => unknown): void;
+    /** Export to CSV string */
     exportToCSV(): string;
+    /** Export to JSON string */
     exportToJSON(): string;
+    /** Import from 2D array */
     importFromArray(data: readonly (readonly unknown[])[]): void;
+    /** Import from CSV string */
     importFromCSV(csv: string): void;
+    /** Import from JSON string */
     importFromJSON(json: string): void;
+    /** Search all cells */
     search(query: string, options?: SearchOptions): SearchResult[];
+    /** Search single column */
     searchColumn(columnIndex: number, query: string, options?: SearchOptions): SearchResult[];
+    /** Selected row indices */
     readonly selectedRows: Readonly<Ref<Set<number>>>;
+    /** Selected cell keys (row,column format) */
     readonly selectedCells: Readonly<Ref<Set<string>>>;
+    /** Select a row */
     selectRow(index: number): void;
+    /** Deselect a row */
     deselectRow(index: number): void;
+    /** Toggle row selection */
     toggleRowSelection(index: number): void;
+    /** Check if row is selected */
     isRowSelected(index: number): boolean;
+    /** Select a cell */
     selectCell(rowIndex: number, columnIndex: number): void;
+    /** Clear all selection */
     clearSelection(): void;
+    /** Enable cell editing */
     enableCellEditing(config?: EditableConfig): void;
+    /** Disable cell editing */
     disableCellEditing(): void;
+    /** Enable header editing */
     enableHeaderEditing(config?: Omit<EditableConfig, 'cells'>): void;
+    /** Disable header editing */
     disableHeaderEditing(): void;
+    /** Enable editing for specific column */
     enableColumnEditing(columnIndex: number, config?: EditableConfig): void;
+    /** Disable editing for specific column */
     disableColumnEditing(columnIndex: number): void;
+    /** Enable editing for specific row */
     enableRowEditing(rowIndex: number, config?: EditableConfig): void;
+    /** Disable editing for specific row */
     disableRowEditing(rowIndex: number): void;
+    /** Enable double-click to edit (returns cleanup) */
     enableEditing(): () => void;
+    /** Group rows by key function */
     groupBy(keyFunction: (row: unknown[]) => string | number): Map<string | number, number[]>;
+    /** Add computed column */
     addComputedColumn(config: ComputedColumnConfig): number;
+    /** Remove computed column */
     removeComputedColumn(index: number): void;
-    pagination: PaginationState | null;
+    /** Current pagination state */
+    readonly pagination: PaginationState | null;
+    /** Enable pagination */
     paginate(config: PaginationConfig): void;
+    /** Go to next page */
     nextPage(): void;
+    /** Go to previous page */
     previousPage(): void;
+    /** Go to specific page */
     goToPage(page: number): void;
-    virtualScroll: VirtualScrollState | null;
+    /** Current virtual scroll state */
+    readonly virtualScroll: VirtualScrollState | null;
+    /** Enable virtual scrolling */
     enableVirtualScrolling(config: VirtualScrollConfig): void;
+    /** Disable virtual scrolling */
     disableVirtualScrolling(): void;
+    /** Execute operations with rollback on error */
     transaction<T>(callback: () => T | Promise<T>): T | Promise<T>;
+    /** Subscribe to data changes (returns unsubscribe) */
     onDataChange(callback: (data: unknown[][]) => void): () => void;
+    /** Current sort state */
     readonly sortState: SortState;
+    /** Sort column ascending */
     sortColumnAscending(columnIndex: number): void;
+    /** Sort column descending */
     sortColumnDescending(columnIndex: number): void;
+    /** Sort column ascending with custom comparator */
     sortColumnAscendingWith(columnIndex: number, comparator: (a: unknown, b: unknown) => number): void;
+    /** Sort column descending with custom comparator */
     sortColumnDescendingWith(columnIndex: number, comparator: (a: unknown, b: unknown) => number): void;
+    /** Clear sorting */
     clearColumnSort(): void;
+    /** Get sorted column index */
     getSortedColumnIndex(): number | null;
+    /** Check if sorted ascending */
     isSortedAscending(): boolean;
+    /** Check if sorted descending */
     isSortedDescending(): boolean;
+    /** Check if any sort is active */
     isSorted(): boolean;
+    /** Current filter state */
     readonly filterState: FilterState;
+    /** Filter rows by predicate */
     filterRows(predicate: (rowData: unknown[], rowIndex: number) => boolean): void;
+    /** Filter by column predicate */
     filterColumn(columnIndex: number, predicate: (value: unknown) => boolean): void;
+    /** Filter by exact value */
     filterColumnByValue(columnIndex: number, value: unknown): void;
+    /** Filter by multiple values */
     filterColumnByValues(columnIndex: number, values: readonly unknown[]): void;
+    /** Clear all filters */
     clearFilters(): void;
+    /** Get visible row indices */
     getFilteredRowIndices(): readonly number[];
+    /** Set function to generate row keys */
     setRowKeyFunction(keyFunction: (rowData: unknown[], rowIndex: number) => string | number): void;
+    /** Clear row key function */
     clearRowKeyFunction(): void;
+    /** Check if row key function is set */
     hasRowKeyFunction(): boolean;
+    /** Get row data by key */
     getRowByKey(key: string | number): unknown[] | undefined;
+    /** Get row index by key */
     getRowIndexByKey(key: string | number): number | undefined;
+    /** Update row by key */
     updateRowByKey(key: string | number, rowData: readonly unknown[]): boolean;
+    /** Remove row by key */
     removeRowByKey(key: string | number): boolean;
+    /** Check if row with key exists */
     hasRowWithKey(key: string | number): boolean;
+    /** Get key for row */
     getRowKey(rowIndex: number): string | number | undefined;
+    /** Get all row keys */
     getAllRowKeys(): readonly (string | number)[];
+    /** Set column definition */
     setColumnDefinition(columnIndex: number, definition: ColumnDefinition): void;
+    /** Set all column definitions */
     setColumnDefinitions(definitions: readonly (ColumnDefinition | undefined)[]): void;
+    /** Clear column definition */
     clearColumnDefinition(columnIndex: number): void;
+    /** Clear all column definitions */
     clearColumnDefinitions(): void;
+    /** Get column definition */
     getColumnDefinition(columnIndex: number): ColumnDefinition | undefined;
+    /** Check if column has definition */
     hasColumnDefinition(columnIndex: number): boolean;
+    /** Get parsed cell value */
     getParsedCell(rowIndex: number, columnIndex: number): unknown;
+    /** Get parsed row data */
     getParsedRowData(rowIndex: number): unknown[];
+    /** Get parsed column data */
     getParsedColumnData(columnIndex: number): unknown[];
+    /** Get all parsed data */
     getParsedData(): unknown[][];
+    /** Whether table has unsaved changes */
     readonly dirtyState: Readonly<Ref<boolean>>;
+    /** Mark as clean (save point) */
     markClean(): void;
+    /** Mark as dirty */
     markDirty(): void;
+    /** Check if dirty */
     isDirty(): boolean;
+    /** Check if has changes */
     hasChanges(): boolean;
+    /** Get all cell changes */
     getChangedCells(): readonly CellChange[];
+    /** Get changed row indices */
     getChangedRowIndices(): readonly number[];
+    /** Get changed column indices */
     getChangedColumnIndices(): readonly number[];
+    /** Undo last change */
     undo(): boolean;
+    /** Redo last undone change */
     redo(): boolean;
+    /** Clear history */
     clearHistory(): void;
+    /** Check if can undo */
     canUndo(): boolean;
+    /** Check if can redo */
     canRedo(): boolean;
+    /** Get undo stack size */
     getUndoStackSize(): number;
+    /** Get redo stack size */
     getRedoStackSize(): number;
+    /** Set history limit */
     setHistoryLimit(limit: number): void;
+    /** Get history limit */
     getHistoryLimit(): number;
+    /** Select all rows */
     selectAllRows(): void;
+    /** Deselect all rows */
     deselectAllRows(): void;
+    /** Select range of rows */
     selectRowRange(startIndex: number, endIndex: number): void;
+    /** Invert row selection */
     invertRowSelection(): void;
+    /** Get data for selected rows */
     getSelectedRowData(): readonly unknown[][];
+    /** Get selected row indices */
     getSelectedRowIndices(): readonly number[];
+    /** Get selected cell positions */
     getSelectedCellIndices(): readonly CellPosition[];
+    /** Currently focused cell */
     readonly focusedCell: Readonly<Ref<CellPosition | null>>;
+    /** Focus a cell */
     focusCell(rowIndex: number, columnIndex: number): void;
+    /** Clear cell focus */
     clearCellFocus(): void;
+    /** Get focused cell position */
     getFocusedCell(): CellPosition | null;
+    /** Check if cell is focused */
     isCellFocused(rowIndex: number, columnIndex: number): boolean;
+    /** Move focus up */
     moveFocusUp(): boolean;
+    /** Move focus down */
     moveFocusDown(): boolean;
+    /** Move focus left */
     moveFocusLeft(): boolean;
+    /** Move focus right */
     moveFocusRight(): boolean;
+    /** Move focus to first cell */
     moveFocusToFirstCell(): void;
+    /** Move focus to last cell */
     moveFocusToLastCell(): void;
+    /** Move focus to row start */
     moveFocusToRowStart(): void;
+    /** Move focus to row end */
     moveFocusToRowEnd(): void;
+    /** Enable keyboard navigation (returns cleanup) */
     enableKeyboardNavigation(): () => void;
+    /** Count of visible columns */
     readonly visibleColumnCount: Readonly<Ref<number>>;
+    /** Hide a column */
     hideColumn(columnIndex: number): void;
+    /** Show a column */
     showColumn(columnIndex: number): void;
+    /** Toggle column visibility */
     toggleColumnVisibility(columnIndex: number): void;
+    /** Check if column is visible */
     isColumnVisible(columnIndex: number): boolean;
+    /** Get visible column indices */
     getVisibleColumnIndices(): readonly number[];
+    /** Get hidden column indices */
     getHiddenColumnIndices(): readonly number[];
+    /** Move row from one position to another */
     moveRow(fromIndex: number, toIndex: number): void;
+    /** Move row up */
     moveRowUp(rowIndex: number): boolean;
+    /** Move row down */
     moveRowDown(rowIndex: number): boolean;
+    /** Move row to top */
     moveRowToTop(rowIndex: number): void;
+    /** Move row to bottom */
     moveRowToBottom(rowIndex: number): void;
+    /** Swap two rows */
     swapRows(indexA: number, indexB: number): void;
+    /** Move column from one position to another */
     moveColumn(fromIndex: number, toIndex: number): void;
+    /** Move column left */
     moveColumnLeft(columnIndex: number): boolean;
+    /** Move column right */
     moveColumnRight(columnIndex: number): boolean;
+    /** Move column to start */
     moveColumnToStart(columnIndex: number): void;
+    /** Move column to end */
     moveColumnToEnd(columnIndex: number): void;
+    /** Swap two columns */
     swapColumns(indexA: number, indexB: number): void;
+    /** Copy selected cells to string */
     copySelectedCells(): string;
+    /** Copy selected rows to string */
     copySelectedRows(): string;
+    /** Copy row to string */
     copyRow(rowIndex: number): string;
+    /** Copy column to string */
     copyColumn(columnIndex: number): string;
+    /** Copy cell to string */
     copyCell(rowIndex: number, columnIndex: number): string;
+    /** Copy cell range to string */
     copyCellRange(rowStart: number, columnStart: number, rowEnd: number, columnEnd: number): string;
+    /** Paste data at cell */
     pasteAtCell(rowIndex: number, columnIndex: number, data: string): void;
+    /** Expanded row indices */
     readonly expandedRows: Readonly<Ref<ReadonlySet<number>>>;
+    /** Rows pinned to top */
     readonly pinnedTopRows: Readonly<Ref<readonly number[]>>;
+    /** Rows pinned to bottom */
     readonly pinnedBottomRows: Readonly<Ref<readonly number[]>>;
+    /** Expand a row */
     expandRow(rowIndex: number): void;
+    /** Collapse a row */
     collapseRow(rowIndex: number): void;
+    /** Toggle row expansion */
     toggleRowExpansion(rowIndex: number): void;
+    /** Expand all rows */
     expandAllRows(): void;
+    /** Collapse all rows */
     collapseAllRows(): void;
+    /** Check if row is expanded */
     isRowExpanded(rowIndex: number): boolean;
+    /** Get expanded row indices */
     getExpandedRowIndices(): readonly number[];
+    /** Pin row to top */
     pinRowTop(rowIndex: number): void;
+    /** Pin row to bottom */
     pinRowBottom(rowIndex: number): void;
+    /** Unpin a row */
     unpinRow(rowIndex: number): void;
+    /** Unpin all rows */
     unpinAllRows(): void;
+    /** Check if row is pinned to top */
     isRowPinnedTop(rowIndex: number): boolean;
+    /** Check if row is pinned to bottom */
     isRowPinnedBottom(rowIndex: number): boolean;
+    /** Get indices of rows pinned to top */
     getPinnedTopRowIndices(): readonly number[];
+    /** Get indices of rows pinned to bottom */
     getPinnedBottomRowIndices(): readonly number[];
+    /** Set cell metadata */
     setCellMeta<T>(rowIndex: number, columnIndex: number, key: string, value: T): void;
+    /** Get cell metadata */
     getCellMeta<T>(rowIndex: number, columnIndex: number, key: string): T | undefined;
+    /** Check if cell has metadata */
     hasCellMeta(rowIndex: number, columnIndex: number, key: string): boolean;
+    /** Clear all cell metadata */
     clearCellMeta(rowIndex: number, columnIndex: number): void;
+    /** Clear specific cell metadata key */
     clearCellMetaKey(rowIndex: number, columnIndex: number, key: string): void;
+    /** Set row metadata */
     setRowMeta<T>(rowIndex: number, key: string, value: T): void;
+    /** Get row metadata */
     getRowMeta<T>(rowIndex: number, key: string): T | undefined;
+    /** Check if row has metadata */
     hasRowMeta(rowIndex: number, key: string): boolean;
+    /** Clear all row metadata */
     clearRowMeta(rowIndex: number): void;
+    /** Clear specific row metadata key */
     clearRowMetaKey(rowIndex: number, key: string): void;
+    /** Set column metadata */
     setColumnMeta<T>(columnIndex: number, key: string, value: T): void;
+    /** Get column metadata */
     getColumnMeta<T>(columnIndex: number, key: string): T | undefined;
+    /** Check if column has metadata */
     hasColumnMeta(columnIndex: number, key: string): boolean;
+    /** Clear all column metadata */
     clearColumnMeta(columnIndex: number): void;
+    /** Clear specific column metadata key */
     clearColumnMetaKey(columnIndex: number, key: string): void;
+    /** Subscribe to row add events */
     onRowAdd(callback: (rowData: unknown[], rowIndex: number) => void): () => void;
+    /** Subscribe to row remove events */
     onRowRemove(callback: (rowData: unknown[], rowIndex: number) => void): () => void;
+    /** Subscribe to row update events */
     onRowUpdate(callback: (rowIndex: number, oldRowData: unknown[], newRowData: unknown[]) => void): () => void;
+    /** Subscribe to cell change events */
     onCellChange(callback: (rowIndex: number, columnIndex: number, oldValue: unknown, newValue: unknown) => void): () => void;
+    /** Subscribe to row selection change events */
     onRowSelectionChange(callback: (selectedIndices: ReadonlySet<number>) => void): () => void;
+    /** Subscribe to cell selection change events */
     onCellSelectionChange(callback: (selectedCells: ReadonlySet<string>) => void): () => void;
+    /** Subscribe to sort change events */
     onSortChange(callback: (columnIndex: number | null, ascending: boolean) => void): () => void;
+    /** Subscribe to filter change events */
     onFilterChange(callback: (filteredIndices: readonly number[]) => void): () => void;
+    /** Subscribe to cell focus change events */
     onCellFocusChange(callback: (cell: CellPosition | null) => void): () => void;
+    /** Subscribe to column visibility change events */
     onColumnVisibilityChange(callback: (columnIndex: number, visible: boolean) => void): () => void;
+    /** Begin batch update (defer reactivity) */
     beginBatchUpdate(): void;
+    /** End batch update (commit changes) */
     endBatchUpdate(): void;
+    /** Cancel batch update (rollback) */
     cancelBatchUpdate(): void;
+    /** Check if batch updating */
     isBatchUpdating(): boolean;
+    /** Execute callback as batch */
     batchUpdate(callback: () => void): void;
+    /** Whether table is loading */
     readonly tableLoading: Readonly<Ref<boolean>>;
+    /** Set table loading state */
     setTableLoading(loading: boolean): void;
+    /** Set cell loading state */
     setCellLoading(rowIndex: number, columnIndex: number, loading: boolean): void;
+    /** Set row loading state */
     setRowLoading(rowIndex: number, loading: boolean): void;
+    /** Set column loading state */
     setColumnLoading(columnIndex: number, loading: boolean): void;
+    /** Check if table is loading */
     isTableLoading(): boolean;
+    /** Check if cell is loading */
     isCellLoading(rowIndex: number, columnIndex: number): boolean;
+    /** Check if row is loading */
     isRowLoading(rowIndex: number): boolean;
+    /** Check if column is loading */
     isColumnLoading(columnIndex: number): boolean;
+    /** Load data with fetcher */
     loadData(fetcher: () => Promise<readonly (readonly unknown[])[]>): Promise<void>;
+    /** Append rows asynchronously */
     appendRowsAsync(fetcher: () => Promise<readonly (readonly unknown[])[]>): Promise<void>;
+    /** Prepend rows asynchronously */
     prependRowsAsync(fetcher: () => Promise<readonly (readonly unknown[])[]>): Promise<void>;
+    /** Number of columns frozen on left */
     readonly frozenLeftColumnCount: Readonly<Ref<number>>;
+    /** Number of columns frozen on right */
     readonly frozenRightColumnCount: Readonly<Ref<number>>;
+    /** Freeze columns on left */
     freezeColumnsLeft(count: number): void;
+    /** Freeze columns on right */
     freezeColumnsRight(count: number): void;
+    /** Unfreeze columns on left */
     unfreezeColumnsLeft(): void;
+    /** Unfreeze columns on right */
     unfreezeColumnsRight(): void;
+    /** Unfreeze all columns */
     unfreezeAllColumns(): void;
+    /** Get frozen left column count */
     getFrozenLeftColumnCount(): number;
+    /** Get frozen right column count */
     getFrozenRightColumnCount(): number;
+    /** Check if column is frozen on left */
     isColumnFrozenLeft(columnIndex: number): boolean;
+    /** Check if column is frozen on right */
     isColumnFrozenRight(columnIndex: number): boolean;
+    /** Check if any columns are frozen */
     hasFrozenColumns(): boolean;
+    /**
+     * Configure table for record-based data.
+     * This enables integration with useDatabase and other composables.
+     */
+    setRecordColumns<T extends BaseRecord>(columns: readonly RecordColumnDef<T>[]): void;
+    /**
+     * Clear record column configuration.
+     */
+    clearRecordColumns(): void;
+    /**
+     * Check if record columns are configured.
+     */
+    hasRecordColumns(): boolean;
+    /**
+     * Get the configured record columns.
+     */
+    getRecordColumns<T extends BaseRecord>(): readonly RecordColumnDef<T>[] | undefined;
+    /**
+     * Set table data from an array of records.
+     * Records must have an `id` field.
+     */
+    setRecords<T extends BaseRecord>(records: readonly T[]): void;
+    /**
+     * Get all records from the table.
+     * Returns records reconstructed from table data using column definitions.
+     */
+    getRecords<T extends BaseRecord>(): readonly T[];
+    /**
+     * Get a single record by ID.
+     */
+    getRecordById<T extends BaseRecord>(id: string): T | undefined;
+    /**
+     * Get record ID for a row index.
+     */
+    getRecordId(rowIndex: number): string | undefined;
+    /**
+     * Get row index for a record ID.
+     */
+    getRowIndexForRecord(recordId: string): number | undefined;
+    /**
+     * Update a record by ID.
+     * Only updates the specified fields.
+     */
+    updateRecord<T extends BaseRecord>(id: string, updates: Partial<Omit<T, 'id'>>): boolean;
+    /**
+     * Add a new record to the table.
+     * If no ID is provided, one will be generated.
+     */
+    addRecord<T extends BaseRecord>(record: T | Omit<T, 'id'>, index?: number): string;
+    /**
+     * Remove a record by ID.
+     */
+    removeRecord(id: string): boolean;
+    /**
+     * Check if a record with the given ID exists.
+     */
+    hasRecord(id: string): boolean;
+    /**
+     * Get record IDs for selected rows.
+     */
+    getSelectedRecordIds(): readonly string[];
+    /**
+     * Select rows by record IDs.
+     */
+    selectRecords(ids: readonly string[]): void;
+    /**
+     * Deselect rows by record IDs.
+     */
+    deselectRecords(ids: readonly string[]): void;
+    /**
+     * Get the selected records.
+     */
+    getSelectedRecords<T extends BaseRecord>(): readonly T[];
+    /**
+     * Subscribe to record changes.
+     * Callback receives the record ID and the updated record.
+     */
+    onRecordChange<T extends BaseRecord>(callback: (recordId: string, record: T, changeType: 'add' | 'update' | 'remove') => void): () => void;
+    /**
+     * Set the ID generator for new records.
+     */
+    setIdGenerator(generator: IdGenerator): void;
+    /**
+     * Convert array row data to a record object using column definitions.
+     */
+    rowToRecord<T extends BaseRecord>(rowIndex: number): T | undefined;
+    /**
+     * Convert a record to array row data using column definitions.
+     */
+    recordToRow<T extends BaseRecord>(record: T): unknown[];
+    /**
+     * Export records to JSON (uses column definitions).
+     */
+    exportRecordsToJSON(): string;
+    /**
+     * Import records from JSON.
+     */
+    importRecordsFromJSON(json: string): void;
 }
 
-/** Validation error. @public */
+/**
+ * Validation error for a specific cell.
+ */
 export declare interface ValidationError {
-    row: number;
-    column: number;
-    value: unknown;
-    message: string;
+    /** Row index */
+    readonly row: number;
+    /** Column index */
+    readonly column: number;
+    /** The invalid value */
+    readonly value: unknown;
+    /** Error message */
+    readonly message: string;
 }
 
-/** Validation result. @public */
+/**
+ * Result of validation operations.
+ */
 export declare interface ValidationResult {
-    valid: boolean;
-    errors: ValidationError[];
+    /** Whether validation passed */
+    readonly valid: boolean;
+    /** Array of validation errors */
+    readonly errors: readonly ValidationError[];
 }
 
-/** Virtual scrolling configuration. @public */
+/**
+ * Virtual scrolling configuration.
+ */
 export declare interface VirtualScrollConfig {
-    rowHeight: number;
-    overscan: number;
-    containerHeight: number;
+    /** Height of each row in pixels */
+    readonly rowHeight: number;
+    /** Number of extra rows to render above/below viewport */
+    readonly overscan: number;
+    /** Height of the scroll container in pixels */
+    readonly containerHeight: number;
 }
 
-/** Virtual scrolling state. @public */
+/**
+ * Virtual scrolling state.
+ */
 export declare interface VirtualScrollState {
-    scrollTop: Ref<number>;
-    rowHeight: number;
-    overscan: number;
-    containerHeight: number;
-    visibleRows: Ref<number[]>;
-    startIndex: Ref<number>;
-    endIndex: Ref<number>;
+    /** Current scroll position */
+    readonly scrollTop: Ref<number>;
+    /** Height of each row */
+    readonly rowHeight: number;
+    /** Overscan count */
+    readonly overscan: number;
+    /** Container height */
+    readonly containerHeight: number;
+    /** Indices of currently visible rows */
+    readonly visibleRows: Ref<number[]>;
+    /** Start index of visible range */
+    readonly startIndex: Ref<number>;
+    /** End index of visible range */
+    readonly endIndex: Ref<number>;
+    /** Scroll event handler (internal) */
     scrollHandler?: () => void;
+    /** Container element (internal) */
     container?: HTMLElement;
 }
 
+/**
+ * Check if a record's ID was auto-generated.
+ */
+export declare function wasIdGenerated(record: object): boolean;
+
 export { }