@mikestools/usetable 0.0.5 → 0.0.6

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import { ComputedRef } from 'vue';
+import { ElementInstance } from '@mikestools/useelement';
+import { MaybeRef } from 'vue';
 import { Ref } from 'vue';
 
 /**
  * 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 */
@@ -11,71 +12,92 @@ export declare interface BaseRecord {
 }
 
 /**
- * Cell change record for tracking modifications.
+ * Cell change record for dirty tracking.
  */
 export declare interface CellChange {
+    /** Row index */
     readonly row: number;
+    /** Column index */
     readonly column: number;
-    readonly oldValue: CellValue;
-    readonly newValue: CellValue;
+    /** Previous value */
+    readonly oldValue: unknown;
+    /** New value */
+    readonly newValue: unknown;
 }
 
+/**
+ * Callback for cell change events
+ */
 export declare type CellChangeCallback = (row: number, column: number, oldValue: CellValue, newValue: CellValue) => void;
 
 /**
- * Cell position for navigation and selection.
+ * Cell position for focus/navigation.
  */
 export declare interface CellPosition {
+    /** Row index */
     readonly row: number;
+    /** Column index */
     readonly column: number;
 }
 
 /**
- * Cell value can be a string, number, or DOM element.
+ * Cell value types - can be primitive or DOM node
  */
-export declare type CellValue = string | number | boolean | null | undefined | HTMLElement | Node;
+export declare type CellValue = string | number | boolean | null | undefined | Node;
 
 /**
- * Create a table instance for manipulating an HTML table element.
+ * Create a table instance wrapping HTMLTableElement.
  *
- * Uses native table DOM APIs exclusively - no querySelector/querySelectorAll.
- * DOM-first architecture where the HTML table is the source of truth.
+ * Built on top of createElement, adds table-specific APIs using native methods:
+ * - element.caption, tHead, tFoot, tBodies (native properties)
+ * - element.insertRow(), deleteRow() (native methods)
+ * - element.rows (native HTMLCollection)
+ * - row.cells, row.insertCell(), row.deleteCell()
  *
  * @param element - The HTML table element
- * @param initialData - Optional initial body data
+ * @param initialData - Initial body data
  * @param options - Configuration options
- * @returns TableInstance for table manipulation
+ * @returns TableInstance with full table manipulation API
  *
  * @example
  * ```ts
  * const table = document.createElement('table')
- * const instance = createTable(table, [['Alice', 30], ['Bob', 25]], {
+ * const instance = createTable(table, [
+ *   ['Alice', 30],
+ *   ['Bob', 25]
+ * ], {
  *   headers: ['Name', 'Age'],
  *   caption: 'Users'
  * })
  *
+ * // Native table methods
+ * const row = instance.insertTableRow() // Uses native insertRow
+ *
+ * // High-level convenience
  * instance.addRow(['Carol', 35])
  * instance.setCell(0, 1, 31)
- * console.log(instance. getData())
  * ```
  */
 export declare function createTable(element: HTMLTableElement, initialData?: TableData, options?: CreateTableOptions): TableInstance;
 
 /**
- * Options for creating a table.
+ * Options for createTable
  */
 export declare interface CreateTableOptions {
     /** Initial headers */
     readonly headers?: readonly string[];
-    /** Initial footer data */
-    readonly footer?: RowData;
-    /** Caption text */
+    /** Table caption */
     readonly caption?: string;
-    /** ID generator for records */
+    /** Initial footer row */
+    readonly footer?: RowData;
+    /** ID generator for rows */
     readonly idGenerator?: IdGenerator;
 }
 
-export declare type DataChangeCallback = (data: CellValue[][]) => void;
+/**
+ * Callback for data change events
+ */
+export declare type DataChangeCallback = (data: readonly (readonly CellValue[])[]) => void;
 
 /**
  * Ensure a record has an ID, generating one if missing.
@@ -90,7 +112,7 @@ export declare function ensureId<T extends Record<string, unknown>>(record: T, g
 export declare function findById<T extends BaseRecord>(records: readonly T[], id: string): T | undefined;
 
 /**
- * Focus state.
+ * Focus state for cells.
  */
 export declare interface FocusState {
     /** Currently focused cell position */
@@ -102,6 +124,9 @@ export declare interface FocusState {
  */
 export declare function generateId(): string;
 
+/**
+ * Callback for header change events
+ */
 export declare type HeaderChangeCallback = (headers: readonly string[]) => void;
 
 /**
@@ -126,21 +151,27 @@ export declare function indexById<T extends BaseRecord>(records: readonly T[], i
 export declare function isValidId(value: unknown): value is string;
 
 /**
- * Event callback types.
+ * Callback for row add events
  */
-export declare type RowAddCallback = (rowData: CellValue[], rowIndex: number, rowId: string | undefined) => void;
+export declare type RowAddCallback = (data: readonly CellValue[], index: number, id: string | null) => void;
 
 /**
- * Row data is an array of cell values.
+ * Row data is an array of cell values
  */
 export declare type RowData = readonly CellValue[];
 
-export declare type RowRemoveCallback = (rowData: CellValue[], rowIndex: number, rowId: string | undefined) => void;
+/**
+ * Callback for row remove events
+ */
+export declare type RowRemoveCallback = (data: readonly CellValue[], index: number, id: string | null) => void;
 
-export declare type RowUpdateCallback = (rowIndex: number, oldData: CellValue[], newData: CellValue[], rowId: string | undefined) => void;
+/**
+ * Callback for row update events
+ */
+export declare type RowUpdateCallback = (index: number, oldData: readonly CellValue[], newData: readonly CellValue[], id: string | null) => void;
 
 /**
- * Selection state.
+ * Selection state for rows.
  */
 export declare interface SelectionState {
     /** Selected row indices */
@@ -157,228 +188,149 @@ export declare function stripGeneratedId<T extends {
 }>(record: T): Omit<T, 'id'> | T;
 
 /**
- * Table data is a 2D array of cell values.
+ * Table data is a 2D array
  */
 export declare type TableData = readonly RowData[];
 
 /**
- * Return type for createTable.
+ * Table instance - extends ElementInstance with table-specific APIs
  */
-export declare interface TableInstance {
-    /** The table element */
-    readonly element: HTMLTableElement;
-    /** Get caption element */
-    getCaption(): HTMLTableCaptionElement | null;
-    /** Get thead element */
-    getTHead(): HTMLTableSectionElement | null;
-    /** Get tfoot element */
-    getTFoot(): HTMLTableSectionElement | null;
-    /** Get all tbody elements */
-    getTBodies(): HTMLCollectionOf<HTMLTableSectionElement>;
-    /** Get primary tbody (first one, created if needed) */
-    getPrimaryTBody(): HTMLTableSectionElement;
-    /** Get all rows in tbody sections */
-    getBodyRows(): readonly HTMLTableRowElement[];
-    /** Get row by index (body rows only) */
-    getRow(index: number): HTMLTableRowElement | undefined;
-    /** Get row by ID */
-    getRowById(id: string): HTMLTableRowElement | undefined;
-    /** Get cell at position */
-    getCell(row: number, column: number): HTMLTableCellElement | undefined;
-    /** Get cell by row ID and column index */
-    getCellByRowId(rowId: string, column: number): HTMLTableCellElement | undefined;
-    /** Get current headers */
-    getHeaders(): string[];
-    /** Get header at index */
-    getHeader(index: number): string | undefined;
-    /** Get body data as 2D array */
-    getData(): CellValue[][];
-    /** Get row data by index */
-    getRowData(index: number): CellValue[] | undefined;
-    /** Get row data by ID */
-    getRowDataById(id: string): CellValue[] | undefined;
-    /** Get cell value */
-    getCellValue(row: number, column: number): CellValue;
-    /** Get column data */
-    getColumnData(index: number): CellValue[];
-    /** Get footer data */
-    getFooterData(): CellValue[] | undefined;
-    /** Get row count (body rows only) */
-    getRowCount(): number;
-    /** Get column count (based on headers or first row) */
-    getColumnCount(): number;
-    /** Get row ID by index */
-    getRowId(index: number): string | undefined;
-    /** Get row index by ID */
-    getRowIndex(id: string): number;
-    /** Get all row IDs */
-    getAllRowIds(): string[];
-    /** Create or get caption */
+export declare interface TableInstance extends ElementInstance<HTMLTableElement> {
+    /** Get/set caption element */
+    getTableCaption(): HTMLTableCaptionElement | null;
+    setTableCaption(caption: HTMLTableCaptionElement | null): void;
+    /** Create and return caption (or return existing) */
     createCaption(): HTMLTableCaptionElement;
-    /** Delete caption */
+    /** Delete caption if exists */
     deleteCaption(): void;
-    /** Create or get thead */
+    /** Get/set thead element */
+    getTHead(): HTMLTableSectionElement | null;
+    setTHead(thead: HTMLTableSectionElement | null): void;
+    /** Create and return thead (or return existing) */
     createTHead(): HTMLTableSectionElement;
-    /** Delete thead */
+    /** Delete thead if exists */
     deleteTHead(): void;
-    /** Create or get tfoot */
+    /** Get/set tfoot element */
+    getTFoot(): HTMLTableSectionElement | null;
+    setTFoot(tfoot: HTMLTableSectionElement | null): void;
+    /** Create and return tfoot (or return existing) */
     createTFoot(): HTMLTableSectionElement;
-    /** Delete tfoot */
+    /** Delete tfoot if exists */
     deleteTFoot(): void;
-    /** Create a new tbody */
+    /** Get tBodies collection */
+    getTBodies(): HTMLCollectionOf<HTMLTableSectionElement>;
+    /** Create and insert new tbody */
     createTBody(): HTMLTableSectionElement;
-    /** Get rows from a specific section (thead, tbody, or tfoot) */
-    getSectionRows(section: HTMLTableSectionElement): HTMLCollectionOf<HTMLTableRowElement>;
-    /** Insert a row in a specific section at the given index */
-    insertSectionRow(section: HTMLTableSectionElement, data: RowData, index?: number, id?: string): HTMLTableRowElement;
-    /** Delete a row from a specific section at the given index */
-    deleteSectionRow(section: HTMLTableSectionElement, index: number): CellValue[] | undefined;
-    /** Get row count for a specific section */
-    getSectionRowCount(section: HTMLTableSectionElement): number;
-    /** Add row to thead */
-    addHeadRow(data: RowData, index?: number): HTMLTableRowElement;
-    /** Remove row from thead */
-    removeHeadRow(index: number): CellValue[] | undefined;
-    /** Get head row count */
-    getHeadRowCount(): number;
-    /** Add row to tfoot */
-    addFootRow(data: RowData, index?: number): HTMLTableRowElement;
-    /** Remove row from tfoot */
-    removeFootRow(index: number): CellValue[] | undefined;
-    /** Get foot row count */
-    getFootRowCount(): number;
-    /** Add row to specific tbody */
-    addBodyRow(data: RowData, tbodyIndex?: number, rowIndex?: number, id?: string): HTMLTableRowElement;
-    /** Remove row from specific tbody */
-    removeBodyRow(rowIndex: number, tbodyIndex?: number): CellValue[] | undefined;
-    /** Get body row count for a specific tbody */
-    getBodyRowCount(tbodyIndex?: number): number;
-    /** Set all headers */
+    /** Get rows collection (all rows in table) */
+    getTableRows(): HTMLCollectionOf<HTMLTableRowElement>;
+    /** Insert row at index (-1 = end) */
+    insertTableRow(index?: number): HTMLTableRowElement;
+    /** Delete row at index */
+    deleteTableRow(index: number): void;
+    /** Get header texts from thead */
+    getHeaders(): readonly string[];
+    /** Set headers (creates/updates thead) */
     setHeaders(headers: readonly string[]): void;
-    /** Set single header */
-    setHeader(index: number, text: string): void;
-    /** Add header column */
+    /** Add single header at index */
     addHeader(text: string, index?: number): void;
-    /** Remove header column */
+    /** Remove header at index */
     removeHeader(index: number): void;
-    /** Add a row with data */
-    addRow(data: RowData, index?: number, id?: string): HTMLTableRowElement;
-    /** Remove row by index */
-    removeRow(index: number): CellValue[] | undefined;
-    /** Remove row by ID */
-    removeRowById(id: string): CellValue[] | undefined;
-    /** Update entire row */
+    /** Clear all headers */
+    clearHeaders(): void;
+    /** Get count of body rows */
+    getRowCount(): number;
+    /** Get all body rows */
+    getBodyRows(): readonly HTMLTableRowElement[];
+    /** Get row at index */
+    getRow(index: number): HTMLTableRowElement | null;
+    /** Add row with data */
+    addRow(data: RowData, index?: number): HTMLTableRowElement;
+    /** Remove row at index, return data */
+    removeRow(index: number): RowData | null;
+    /** Update row data */
     updateRow(index: number, data: RowData): void;
-    /** Update row by ID */
-    updateRowById(id: string, data: RowData): void;
-    /** Move row from one index to another */
-    moveRow(fromIndex: number, toIndex: number): void;
-    /** Swap two rows */
-    swapRows(indexA: number, indexB: number): void;
     /** Clear all body rows */
     clearRows(): void;
-    /** Add a column */
-    addColumn(header: string, defaultValue?: CellValue, index?: number): void;
-    /** Remove a column */
+    /** Get row by data-id */
+    getRowById(id: string): HTMLTableRowElement | null;
+    /** Get ID of row at index */
+    getRowId(index: number): string | null;
+    /** Add row with specific ID */
+    addRowWithId(data: RowData, id: string, index?: number): HTMLTableRowElement;
+    /** Remove row by ID */
+    removeRowById(id: string): RowData | null;
+    /** Get cell at row, col */
+    getCell(row: number, col: number): HTMLTableCellElement | null;
+    /** Get cell value */
+    getCellValue(row: number, col: number): CellValue;
+    /** Set cell value */
+    setCell(row: number, col: number, value: CellValue): void;
+    /** Get column count */
+    getColumnCount(): number;
+    /** Add column (header + cells) */
+    addColumn(header?: string, index?: number): void;
+    /** Remove column */
     removeColumn(index: number): void;
-    /** Move column */
-    moveColumn(fromIndex: number, toIndex: number): void;
-    /** Swap two columns */
-    swapColumns(indexA: number, indexB: number): void;
+    /** Get column data */
+    getColumnData(index: number): readonly CellValue[];
     /** Set column data */
     setColumnData(index: number, data: readonly CellValue[]): void;
-    /** Set cell value */
-    setCell(row: number, column: number, value: CellValue): void;
-    /** Set cell by row ID */
-    setCellByRowId(rowId: string, column: number, value: CellValue): void;
-    /** Set cell range */
-    setCellRange(startRow: number, startColumn: number, data: TableData): void;
+    /** Get all body data */
+    getTableData(): TableData;
+    /** Set all body data */
+    setTableData(data: TableData): void;
+    /** Get footer row data */
+    getFooter(): RowData | null;
     /** Set footer row */
     setFooter(data: RowData): void;
-    /** Set footer cell */
-    setFooterCell(index: number, value: CellValue): void;
-    /** Get footer cell */
-    getFooterCell(index: number): CellValue;
     /** Clear footer */
     clearFooter(): void;
-    /** Set caption text */
-    setCaption(text: string): void;
     /** Get caption text */
-    getCaptionText(): string | undefined;
-    /** Set all data (replaces body rows) */
-    setData(data: TableData): void;
-    /** Reset table (clear all content) */
-    reset(): void;
-    /** Sync internal state with DOM (if external changes made) */
-    sync(): void;
-    /** Set records with column mapping */
-    setRecords<T extends BaseRecord>(records: readonly T[], fields: readonly (keyof T | ((record: T) => CellValue))[]): void;
-    /** Get record by ID */
-    getRecordData(id: string): CellValue[] | undefined;
-    /** Add a record */
-    addRecord<T extends BaseRecord>(record: T | Omit<T, 'id'>, fields: readonly (keyof T | ((record: T) => CellValue))[], index?: number): string;
-    /** Update a record by ID */
-    updateRecordRow(id: string, data: RowData): boolean;
-    /** Remove a record by ID */
-    removeRecord(id: string): boolean;
-    /** Check if record exists */
-    hasRecord(id: string): boolean;
-    /** Set the ID generator function */
-    setIdGenerator(generator: IdGenerator): void;
-    /** Generate a new ID */
-    generateId(): string;
-    /** Subscribe to row add events */
-    onRowAdd(callback: RowAddCallback): () => void;
-    /** Subscribe to row remove events */
-    onRowRemove(callback: RowRemoveCallback): () => void;
-    /** Subscribe to row update events */
-    onRowUpdate(callback: RowUpdateCallback): () => void;
-    /** Subscribe to cell change events */
-    onCellChange(callback: CellChangeCallback): () => void;
-    /** Subscribe to header change events */
-    onHeaderChange(callback: HeaderChangeCallback): () => void;
-    /** Subscribe to data change events */
-    onDataChange(callback: DataChangeCallback): () => void;
-    /** Destroy and clean up */
-    destroy(): void;
+    getCaptionText(): string | null;
+    /** Set caption text */
+    setCaptionText(text: string): void;
+    /** Move row from one index to another */
+    moveRow(fromIndex: number, toIndex: number): void;
+    /** Swap two rows */
+    swapRows(index1: number, index2: number): void;
+    /** Subscribe to row add */
+    onRowAdd(callback: (index: number, id: string | null) => void): () => void;
+    /** Subscribe to row remove */
+    onRowRemove(callback: (index: number, id: string | null) => void): () => void;
+    /** Subscribe to data change */
+    onDataChange(callback: () => void): () => void;
 }
 
 /**
  * Vue 3 composable for HTML table manipulation.
  *
- * Wraps createTable with Vue reactivity and state management.
- * Uses native table DOM APIs - no querySelector/querySelectorAll.
+ * Wraps createTable with reactive state and Vue-specific integration.
+ * Follows the DOM-first architecture where the HTML table element is the source of truth.
  *
  * @param elementRef - Ref to the HTML table element
- * @param initialData - Optional initial body data
+ * @param initialData - Initial body data
  * @param options - Configuration options
- * @returns UseTableReturn for reactive table manipulation
+ * @returns UseTableReturn with reactive state and methods
  *
  * @example
  * ```vue
- * <script setup lang="ts">
+ * <script setup>
  * import { ref, onMounted } from 'vue'
  * import { useTable } from '@mikestools/usetable'
  *
- * const tableRef = ref<HTMLTableElement>()
+ * const tableRef = ref<HTMLTableElement | null>(null)
  *
- * onMounted(() => {
- *   if (! tableRef.value) return
- *
- *   const table = useTable(ref(tableRef.value), [
- *     ['Alice', 30],
- *     ['Bob', 25]
- *   ], {
- *     headers: ['Name', 'Age']
- *   })
- *
- *   // Reactive access
- *   console. log(table.data. value)
- *   console.log(table.rowCount. value)
- *
- *   // Mutations
- *   table.addRow(['Carol', 35])
- *   table.setCell(0, 1, 31)
+ * const {
+ *   data,
+ *   headers,
+ *   rowCount,
+ *   addRow,
+ *   setCell
+ * } = useTable(tableRef, [
+ *   ['Alice', 30],
+ *   ['Bob', 25]
+ * ], {
+ *   headers: ['Name', 'Age']
  * })
  * </script>
  *
@@ -387,7 +339,7 @@ export declare interface TableInstance {
  * </template>
  * ```
  */
-export declare function useTable(elementRef: Ref<HTMLTableElement>, initialData?: TableData, options?: UseTableOptions): UseTableReturn;
+export declare function useTable(elementRef: MaybeRef<HTMLTableElement | null>, initialData?: TableData, options?: UseTableOptions): UseTableReturn;
 
 /**
  * Options for useTable composable.
@@ -398,10 +350,12 @@ export declare type UseTableOptions = CreateTableOptions;
  * Return type for useTable composable.
  */
 export declare interface UseTableReturn {
-    /** Underlying table instance */
-    readonly instance: TableInstance;
-    /** The table element */
-    readonly element: Readonly<Ref<HTMLTableElement>>;
+    /** Underlying table instance (for advanced usage) */
+    readonly instance: Readonly<Ref<TableInstance | null>>;
+    /** Whether the table is initialized */
+    readonly isInitialized: ComputedRef<boolean>;
+    /** The table element reference */
+    readonly element: Readonly<Ref<HTMLTableElement | null>>;
     /** Reactive headers */
     readonly headers: ComputedRef<readonly string[]>;
     /** Reactive body data */
@@ -413,9 +367,9 @@ export declare interface UseTableReturn {
     /** Reactive row IDs */
     readonly rowIds: ComputedRef<readonly string[]>;
     /** Reactive footer data */
-    readonly footerData: ComputedRef<readonly CellValue[] | undefined>;
+    readonly footerData: ComputedRef<readonly CellValue[] | null>;
     /** Reactive caption text */
-    readonly captionText: ComputedRef<string | undefined>;
+    readonly captionText: ComputedRef<string | null>;
     /** Version counter for reactivity (incremented on changes) */
     readonly version: Readonly<Ref<number>>;
     /** Selection state */
@@ -423,117 +377,77 @@ export declare interface UseTableReturn {
     /** Focus state */
     readonly focus: FocusState;
     /** Create or get caption */
-    createCaption(): HTMLTableCaptionElement;
+    createCaption(): HTMLTableCaptionElement | null;
     /** Delete caption */
     deleteCaption(): void;
     /** Create or get thead */
-    createTHead(): HTMLTableSectionElement;
+    createTHead(): HTMLTableSectionElement | null;
     /** Delete thead */
     deleteTHead(): void;
     /** Create or get tfoot */
-    createTFoot(): HTMLTableSectionElement;
+    createTFoot(): HTMLTableSectionElement | null;
     /** Delete tfoot */
     deleteTFoot(): void;
     /** Create a new tbody */
-    createTBody(): HTMLTableSectionElement;
-    /** Get rows from a specific section (thead, tbody, or tfoot) */
-    getSectionRows(section: HTMLTableSectionElement): HTMLCollectionOf<HTMLTableRowElement>;
-    /** Insert a row in a specific section at the given index */
-    insertSectionRow(section: HTMLTableSectionElement, data: RowData, index?: number, id?: string): HTMLTableRowElement;
-    /** Delete a row from a specific section at the given index */
-    deleteSectionRow(section: HTMLTableSectionElement, index: number): CellValue[] | undefined;
-    /** Get row count for a specific section */
-    getSectionRowCount(section: HTMLTableSectionElement): number;
-    /** Add row to thead */
-    addHeadRow(data: RowData, index?: number): HTMLTableRowElement;
-    /** Remove row from thead */
-    removeHeadRow(index: number): CellValue[] | undefined;
-    /** Get head row count */
-    getHeadRowCount(): number;
-    /** Add row to tfoot */
-    addFootRow(data: RowData, index?: number): HTMLTableRowElement;
-    /** Remove row from tfoot */
-    removeFootRow(index: number): CellValue[] | undefined;
-    /** Get foot row count */
-    getFootRowCount(): number;
-    /** Add row to specific tbody */
-    addBodyRow(data: RowData, tbodyIndex?: number, rowIndex?: number, id?: string): HTMLTableRowElement;
-    /** Remove row from specific tbody */
-    removeBodyRow(rowIndex: number, tbodyIndex?: number): CellValue[] | undefined;
-    /** Get body row count for a specific tbody */
-    getBodyRowCount(tbodyIndex?: number): number;
+    createTBody(): HTMLTableSectionElement | null;
     /** Set all headers */
     setHeaders(headers: readonly string[]): void;
-    /** Set single header */
-    setHeader(index: number, text: string): void;
     /** Add header column */
     addHeader(text: string, index?: number): void;
     /** Remove header column */
     removeHeader(index: number): void;
+    /** Clear all headers */
+    clearHeaders(): void;
     /** Add a row with data */
-    addRow(data: RowData, index?: number, id?: string): HTMLTableRowElement;
+    addRow(data: RowData, index?: number): HTMLTableRowElement | null;
+    /** Add a row with specific ID */
+    addRowWithId(data: RowData, id: string, index?: number): HTMLTableRowElement | null;
     /** Remove row by index */
-    removeRow(index: number): CellValue[] | undefined;
+    removeRow(index: number): RowData | null;
     /** Remove row by ID */
-    removeRowById(id: string): CellValue[] | undefined;
+    removeRowById(id: string): RowData | null;
     /** Update entire row */
     updateRow(index: number, data: RowData): void;
-    /** Update row by ID */
-    updateRowById(id: string, data: RowData): void;
+    /** Clear all body rows */
+    clearRows(): void;
+    /** Get row by index */
+    getRow(index: number): HTMLTableRowElement | null;
+    /** Get row by ID */
+    getRowById(id: string): HTMLTableRowElement | null;
+    /** Get row ID by index */
+    getRowId(index: number): string | null;
     /** Move row from one index to another */
     moveRow(fromIndex: number, toIndex: number): void;
     /** Swap two rows */
-    swapRows(indexA: number, indexB: number): void;
-    /** Clear all body rows */
-    clearRows(): void;
+    swapRows(index1: number, index2: number): void;
     /** Add a column */
-    addColumn(header: string, defaultValue?: CellValue, index?: number): void;
+    addColumn(header?: string, index?: number): void;
     /** Remove a column */
     removeColumn(index: number): void;
-    /** Move column */
-    moveColumn(fromIndex: number, toIndex: number): void;
-    /** Swap two columns */
-    swapColumns(indexA: number, indexB: number): void;
+    /** Get column data */
+    getColumnData(index: number): readonly CellValue[];
     /** Set column data */
     setColumnData(index: number, data: readonly CellValue[]): void;
+    /** Get cell element */
+    getCell(row: number, column: number): HTMLTableCellElement | null;
     /** Get cell value */
-    getCell(row: number, column: number): CellValue;
+    getCellValue(row: number, column: number): CellValue;
     /** Set cell value */
     setCell(row: number, column: number, value: CellValue): void;
-    /** Set cell by row ID */
-    setCellByRowId(rowId: string, column: number, value: CellValue): void;
-    /** Set cell range */
-    setCellRange(startRow: number, startColumn: number, data: TableData): void;
-    /** Get cell element */
-    getCellElement(row: number, column: number): HTMLTableCellElement | undefined;
-    /** Get row data by index */
-    getRowData(index: number): CellValue[] | undefined;
-    /** Get row data by ID */
-    getRowDataById(id: string): CellValue[] | undefined;
-    /** Get row element */
-    getRowElement(index: number): HTMLTableRowElement | undefined;
-    /** Get row by ID */
-    getRowById(id: string): HTMLTableRowElement | undefined;
-    /** Get row ID by index */
-    getRowId(index: number): string | undefined;
-    /** Get row index by ID */
-    getRowIndex(id: string): number;
-    /** Get column data */
-    getColumnData(index: number): CellValue[];
+    /** Get footer data */
+    getFooter(): RowData | null;
     /** Set footer row */
     setFooter(data: RowData): void;
-    /** Set footer cell */
-    setFooterCell(index: number, value: CellValue): void;
-    /** Get footer cell */
-    getFooterCell(index: number): CellValue;
     /** Clear footer */
     clearFooter(): void;
+    /** Get caption text */
+    getCaption(): string | null;
     /** Set caption text */
     setCaption(text: string): void;
+    /** Get all table data */
+    getData(): TableData;
     /** Set all data (replaces body rows) */
     setData(data: TableData): void;
-    /** Reset table (clear all content) */
-    reset(): void;
     /** Sync internal state with DOM */
     sync(): void;
     /** Select a row by index */
@@ -546,14 +460,16 @@ export declare interface UseTableReturn {
     selectAllRows(): void;
     /** Deselect all rows */
     deselectAllRows(): void;
-    /** Select row range */
-    selectRowRange(startIndex: number, endIndex: number): void;
     /** Check if row is selected */
     isRowSelected(index: number): boolean;
     /** Get selected row indices */
     getSelectedRowIndices(): readonly number[];
     /** Get selected row data */
     getSelectedRowData(): readonly (readonly CellValue[])[];
+    /** Select a range of rows (from anchor to target) */
+    selectRowRange(fromIndex: number, toIndex: number): void;
+    /** Select row with modifier key awareness (Ctrl/Cmd, Shift) */
+    selectRowWithModifiers(index: number, ctrlKey: boolean, shiftKey: boolean): void;
     /** Select a cell */
     selectCell(row: number, column: number): void;
     /** Deselect a cell */
@@ -580,51 +496,19 @@ export declare interface UseTableReturn {
     moveFocusLeft(): boolean;
     /** Move focus right */
     moveFocusRight(): boolean;
-    /** Move focus to first cell */
-    moveFocusToFirst(): void;
-    /** Move focus to last cell */
-    moveFocusToLast(): void;
     /** Enable keyboard navigation (returns cleanup function) */
     enableKeyboardNavigation(): () => void;
-    /** Set records with column mapping */
-    setRecords<T extends BaseRecord>(records: readonly T[], fields: readonly (keyof T | ((record: T) => CellValue))[]): void;
-    /** Get record data by ID */
-    getRecordData(id: string): CellValue[] | undefined;
-    /** Add a record */
-    addRecord<T extends BaseRecord>(record: T | Omit<T, 'id'>, fields: readonly (keyof T | ((record: T) => CellValue))[], index?: number): string;
-    /** Update a record row by ID */
-    updateRecordRow(id: string, data: RowData): boolean;
-    /** Remove a record by ID */
-    removeRecord(id: string): boolean;
-    /** Check if record exists */
-    hasRecord(id: string): boolean;
-    /** Get selected record IDs */
-    getSelectedRecordIds(): readonly string[];
-    /** Select records by IDs */
-    selectRecords(ids: readonly string[]): void;
-    /** Deselect records by IDs */
-    deselectRecords(ids: readonly string[]): void;
-    /** Set the ID generator function */
-    setIdGenerator(generator: IdGenerator): void;
-    /** Generate a new ID */
-    generateId(): string;
     /** Subscribe to row add events */
-    onRowAdd(callback: RowAddCallback): () => void;
+    onRowAdd(callback: (index: number, id: string | null) => void): () => void;
     /** Subscribe to row remove events */
-    onRowRemove(callback: RowRemoveCallback): () => void;
-    /** Subscribe to row update events */
-    onRowUpdate(callback: RowUpdateCallback): () => void;
-    /** Subscribe to cell change events */
-    onCellChange(callback: CellChangeCallback): () => void;
-    /** Subscribe to header change events */
-    onHeaderChange(callback: HeaderChangeCallback): () => void;
+    onRowRemove(callback: (index: number, id: string | null) => void): () => void;
     /** Subscribe to data change events */
-    onDataChange(callback: DataChangeCallback): () => void;
+    onDataChange(callback: () => void): () => void;
     /** Subscribe to selection change events */
-    onSelectionChange(callback: (selectedRows: ReadonlySet<number>, selectedCells: ReadonlySet<string>) => void): () => void;
+    onSelectionChange(callback: (rows: ReadonlySet<number>, cells: ReadonlySet<string>) => void): () => void;
     /** Subscribe to focus change events */
     onFocusChange(callback: (cell: CellPosition | null) => void): () => void;
-    /** Destroy and clean up */
+    /** Destroy and cleanup */
     destroy(): void;
 }