@mikestools/usetable 0.0.3 → 0.0.5

package/README.md

@@ -1,586 +1,380 @@
-# @mikestools/usetable
-
-The most comprehensive Vue 3 table composable with 20+ advanced features. Pure DOM wrapper with reactive data layer for complete table manipulation.
-
-## Features
-
-- 🎯 **Composable-First** - Pure Vue 3 Composition API, no components
-- 📦 **TypeScript First** - Full type safety with IntelliSense
-- 🔗 **DOM-First Architecture** - HTML table is source of truth
-- ✨ **20+ Advanced Features** - All-in-one solution
-
-> **Note:** Data is read from DOM `textContent`, so values are strings. Use `Number()` when working with numeric data.
-
-### Complete Feature Set
-
-| Feature                   | Description                               |
-|---------------------------|-------------------------------------------|
-| 🗄️ **Record-Based Data** | Work with typed records by ID             |
-| 🔀 **Sorting**            | Column sorting with state tracking        |
-| 🔍 **Filtering**          | Row filtering with predicates             |
-| ↩️ **Undo/Redo**          | Full history tracking with rollback       |
-| 🎯 **Cell Focus**         | Keyboard navigation between cells         |
-| 👁️ **Column Visibility** | Show/hide columns dynamically             |
-| ↕️ **Reordering**         | Move rows and columns programmatically    |
-| 📋 **Clipboard**          | Copy/paste with Excel-compatible format   |
-| 📌 **Row State**          | Expand/collapse and pin rows              |
-| 🏷️ **Metadata**          | Custom data on cells, rows, columns       |
-| ☑️ **Selection**          | Row and cell selection with range support |
-| 🔔 **Events**             | Granular change callbacks                 |
-| ⚡ **Batch Updates**       | Efficient bulk operations                 |
-| ⏳ **Async Data**          | Loading states and async fetching         |
-| 🧊 **Frozen Columns**     | Pin columns to left/right                 |
-| 🔄 **Transactions**       | Batch operations with automatic rollback  |
-| ✅ **Validation**          | Cell, row, column validation              |
-| 📊 **Aggregation**        | Sum, average, min, max, count             |
-| 📄 **Pagination**         | Client-side pagination                    |
-| 📥 **Import/Export**      | CSV and JSON format support               |
-| 🧩 **HTML Elements**      | Rich cell content support                 |
-
-## Installation
-
-```bash
-npm install @mikestools/usetable vue
-```
-
-## Quick Start
-
-```typescript
-import { ref, onMounted } from 'vue'
-import { useTable } from '@mikestools/usetable'
-
-const tableRef = ref<HTMLTableElement>()
-
-onMounted(() => {
-  const element = tableRef.value
-  if (!element) return
-
-  const table = useTable(ref(element))
-
-  // Set up table structure
-  table.setHeaders(['Name', 'Department', 'Salary'])
-  table.setData([
-    ['Alice Johnson', 'Engineering', 85000],
-    ['Bob Smith', 'Marketing', 72000],
-    ['Carol Williams', 'Sales', 68000]
-  ])
-
-  // Add a row
-  table.addRow(['David Brown', 'Engineering', 92000])
-
-  // Update a cell
-  table.setCell(0, 2, 90000)
-
-  // Use aggregation
-  const totalSalary = table.sum(2)
-  console.log('Total:', totalSalary)
-
-  // Enable inline editing
-  const cleanup = table.enableEditing()
-})
-```
-
-```vue
-<template>
-  <table ref="tableRef" class="table"></table>
-</template>
-```
-
-## API Reference
-
-### Core Properties
-
-| Property             | Type                              | Description                       |
-|----------------------|-----------------------------------|-----------------------------------|
-| `element`            | `Readonly<Ref<HTMLTableElement>>` | The underlying table element      |
-| `data`               | `Ref<unknown[][]>`                | Reactive 2D array of body data    |
-| `headers`            | `Ref<string[]>`                   | Reactive array of headers         |
-| `rowCount`           | `Readonly<Ref<number>>`           | Number of data rows               |
-| `columnCount`        | `Readonly<Ref<number>>`           | Number of columns                 |
-| `selectedRows`       | `Ref<Set<number>>`                | Selected row indices              |
-| `selectedCells`      | `Ref<Set<string>>`                | Selected cell keys                |
-| `sortState`          | `SortState`                       | Current sort column and direction |
-| `filterState`        | `FilterState`                     | Current filter state              |
-| `focusedCell`        | `Ref<{row, column} \| null>`      | Currently focused cell            |
-| `visibleColumnCount` | `Readonly<Ref<number>>`           | Count of visible columns          |
-| `dirtyState`         | `Ref<boolean>`                    | Whether table has unsaved changes |
-| `expandedRows`       | `Ref<Set<number>>`                | Expanded row indices              |
-| `pinnedTopRows`      | `Ref<Set<number>>`                | Rows pinned to top                |
-| `pinnedBottomRows`   | `Ref<Set<number>>`                | Rows pinned to bottom             |
-| `tableLoading`       | `Ref<boolean>`                    | Loading state                     |
-
-### Data Methods
-
-#### Setup
-```typescript
-table.setHeaders(['Name', 'Age', 'Email'])
-table.setData([['Alice', 30, 'alice@email.com'], ...])
-table.setFooter(['Total', '', count])
-table.setCaption('User List')
-```
-
-#### Row Operations
-```typescript
-table.addRow(['value1', 'value2', ...], index?)
-table.addRowWithAttributes(['value1', ...], { class: 'highlight' })
-table.removeRow(index)  // -1 for last row
-table.updateRow(index, ['newValue1', ...])
-table.getRowData(index)  // Returns copy
-table.setRowData(index, ['value1', ...])
-```
-
-#### Cell Operations
-```typescript
-table.getCell(rowIndex, columnIndex)
-table.setCell(rowIndex, columnIndex, value)
-table.setCellWithAttributes(rowIndex, columnIndex, value, { class: 'active' })
-table.updateCell(rowIndex, columnIndex, { value, attributes })
-table.getCellRange(rowStart, rowEnd, columnStart, columnEnd)
-table.setCellRange(rowStart, columnStart, [[data]])
-```
-
-#### Column Operations
-```typescript
-table.addColumn('Header', ['data1', 'data2', ...], index?)
-table.removeColumn(index)
-table.getColumnData(index)
-table.setColumnData(index, ['value1', 'value2', ...])
-```
-
-### Advanced Features
-
-#### Transactions
-```typescript
-// Batch operations with automatic rollback on error
-table.transaction(() => {
-  table.addRow(['New', 'Row', 'Data'])
-  table.setCell(0, 0, 'Updated')
-  // If any operation fails, all changes are reverted
-})
-
-// Async transactions
-await table.transaction(async () => {
-  const data = await fetchData()
-  table.setData(data)
-})
-```
-
-#### Validation
-```typescript
-const result = table.validateAll((value, rowIndex, columnIndex) => {
-  if (columnIndex === 0 && !value) return 'Name required'
-  if (columnIndex === 2 && isNaN(Number(value))) return 'Must be number'
-  return null  // Valid
-})
-
-if (!result.valid) {
-  result.errors.forEach(error => {
-    console.log(`Row ${error.row}, Column ${error.column}: ${error.message}`)
-  })
-}
-```
-
-#### Aggregation
-```typescript
-const total = table.sum(colIndex)     // Returns number (auto-converts)
-const avg = table.average(colIndex)   // Returns number
-const min = table.min(colIndex)       // Returns string from DOM
-const max = table.max(colIndex)       // Returns string from DOM
-const count = table.count(colIndex, predicate?)
-const custom = table.aggregate(colIndex, { initial, reducer })
-
-// Convert min/max when needed
-const maxSalary = Number(table.max(2))
-```
-
-#### Transformation
-```typescript
-table.transformColumn(columnIndex, (value, rowIndex) => {
-  return Number(value) * 1.1  // 10% increase
-})
-
-table.transformRow(rowIndex, (value, columnIndex) => {
-  return String(value).toUpperCase()
-})
-
-table.transformCells((value, rowIndex, columnIndex) => {
-  return columnIndex === 2 ? Number(value).toFixed(2) : value
-})
-```
-
-#### Computed Columns
-```typescript
-table.addComputedColumn({
-  label: 'Total',
-  computeFunction: (row) => Number(row[1]) * Number(row[2]),
-  index: 3  // Optional, defaults to end
-})
-
-table.removeComputedColumn(3)
-```
-
-#### Grouping
-```typescript
-const grouped = table.groupBy(row => row[1])  // Group by column 1
-// Returns: Map<string, number[]> - key to row indices
-```
-
-#### Pagination
-```typescript
-table.paginate({ pageSize: 10, currentPage: 1 })
-
-// Navigation
-table.nextPage()
-table.previousPage()
-table.goToPage(5)
-```
-
-#### Virtual Scrolling
-```typescript
-table.enableVirtualScrolling({
-  rowHeight: 40,
-  containerHeight: 400
-})
-
-table.disableVirtualScrolling()
-```
-
-#### Import/Export
-```typescript
-// Export
-const csv = table.exportToCSV()
-const json = table.exportToJSON()
-
-// Import
-table.importFromCSV(csvString)
-table.importFromJSON(jsonString)
-table.importFromArray([['row1col1', ...], ['row2col1', ...]])
-```
-
-#### Search
-```typescript
-const results = table.search('query', { caseSensitive: false })
-// Returns: [{ row, column, value }, ...]
-
-const columnResults = table.searchColumn(0, 'query')
-```
-
-#### Selection
-```typescript
-table.selectRow(rowIndex)
-table.deselectRow(rowIndex)
-table.toggleRowSelection(rowIndex)
-table.selectCell(rowIndex, columnIndex)
-table.clearSelection()
-
-// Check state
-table.isRowSelected(rowIndex)
-table.selectedRows.value  // Set<number>
-table.selectedCells.value  // Set<string>
-```
-
-#### Inline Editing
-```typescript
-const cleanup = table.enableEditing()
-// Double-click to edit, Enter to save, Escape to cancel
-
-// Disable when done
-cleanup()
-```
-
-#### DOM Sync
-```typescript
-// Sync pre-existing HTML table to data layer
-table.sync()
-
-// Now table.headers and table.data contain DOM content
-```
-
-#### Data Change Subscription
-```typescript
-const unsubscribe = table.onDataChange((newData) => {
-  console.log('Data changed:', newData)
-  // Save to server, localStorage, etc.
-})
-
-// Stop watching
-unsubscribe()
-```
-
-### Types
-
-```typescript
-// Cell configuration
-interface CellConfig {
-  value: unknown
-  attributes?: ElementAttributes
-  columnSpan?: number
-  rowSpan?: number
-}
-
-// Element attributes
-interface ElementAttributes {
-  class?: string | string[] | Record<string, boolean>
-  style?: string | Record<string, string | number>
-  id?: string
-  title?: string
-  // ... all HTML attributes, ARIA, data-*, events
-}
-
-// Computed column configuration
-interface ComputedColumnConfig {
-  computeFunction: (row: unknown[]) => unknown
-  label: string
-  index?: number
-}
-
-// Validation
-interface ValidationResult {
-  valid: boolean
-  errors: ValidationError[]
-}
-
-interface ValidationError {
-  row: number
-  column: number
-  message: string
-}
-
-// Search
-interface SearchResult {
-  row: number
-  column: number
-  value: unknown
-}
-
-// Sort state
-interface SortState {
-  columnIndex: Readonly<Ref<number | null>>
-  ascending: Readonly<Ref<boolean>>
-  descending: Readonly<Ref<boolean>>
-}
-
-// Filter state
-interface FilterState {
-  isFiltered: Readonly<Ref<boolean>>
-  filteredRowCount: Readonly<Ref<number>>
-  filteredIndices: Readonly<Ref<number[]>>
-}
-
-// Base record type
-interface BaseRecord {
-  readonly id: string
-}
-
-// Column definition for records
-interface RecordColumnDef<T extends BaseRecord> {
-  field: string | ((record: T) => unknown)
-  header: string
-  format?: (value: unknown, record: T) => string
-  parse?: (value: string, record: T) => unknown
-  editable?: boolean
-  width?: string | number
-  defaultValue?: unknown
-}
-```
-
-### Record-Based Data API
-
-Work with typed records instead of raw arrays:
-
-```typescript
-import type { RecordColumnDef } from '@mikestools/usetable'
-
-interface User {
-  id: string
-  name: string
-  email: string
-  age: number
-}
-
-const columns: RecordColumnDef<User>[] = [
-  { field: 'id', header: 'ID' },
-  { field: 'name', header: 'Name' },
-  { field: 'email', header: 'Email' },
-  { field: 'age', header: 'Age' },
-]
-
-// Configure table for records
-table.setRecordColumns(columns)
-table.setRecords([
-  { id: 'user-1', name: 'Alice', email: 'alice@example.com', age: 30 },
-  { id: 'user-2', name: 'Bob', email: 'bob@example.com', age: 25 },
-])
-
-// CRUD operations
-const newId = table.addRecord({ name: 'Carol', email: 'carol@example.com', age: 28 })
-table.updateRecord<User>('user-1', { age: 31 })
-table.removeRecord('user-2')
-const user = table.getRecordById<User>('user-1')
-
-// Selection by ID
-table.selectRecords(['user-1', 'user-3'])
-const selectedIds = table.getSelectedRecordIds()
-const selectedRecords = table.getSelectedRecords<User>()
-
-// Change notifications
-table.onRecordChange<User>((id, record, type) => {
-  console.log(`${type}: ${id}`)  // 'add' | 'update' | 'remove'
-})
-
-// Export/Import
-const json = table.exportRecordsToJSON()
-table.importRecordsFromJSON(json)
-```
-
-### Sorting API
-
-```typescript
-table.sortColumnAscending(columnIndex)
-table.sortColumnDescending(columnIndex)
-table.sortColumnAscendingWith(columnIndex, comparator)
-table.sortColumnDescendingWith(columnIndex, comparator)
-table.clearColumnSort()
-
-// Check state
-table.isSorted()
-table.isSortedAscending()
-table.isSortedDescending()
-table.getSortedColumnIndex()
-
-// Reactive state
-table.sortState.columnIndex.value
-table.sortState.ascending.value
-```
-
-### Filtering API
-
-```typescript
-table.filterRows(predicate)
-table.filterColumn(columnIndex, predicate)
-table.filterColumnByValue(columnIndex, value)
-table.filterColumnByValues(columnIndex, values)
-table.clearFilters()
-
-// Check state
-table.getFilteredRowIndices()
-table.filterState.isFiltered.value
-```
-
-### Undo/Redo API
-
-```typescript
-table.undo()
-table.redo()
-table.canUndo()
-table.canRedo()
-table.clearHistory()
-table.setHistoryLimit(100)
-```
-
-### Cell Focus API
-
-```typescript
-table.focusCell(rowIndex, columnIndex)
-table.clearCellFocus()
-table.getFocusedCell()
-table.moveFocusUp()
-table.moveFocusDown()
-table.moveFocusLeft()
-table.moveFocusRight()
-table.enableKeyboardNavigation()
-```
-
-### Column Visibility API
-
-```typescript
-table.hideColumn(columnIndex)
-table.showColumn(columnIndex)
-table.toggleColumnVisibility(columnIndex)
-table.isColumnVisible(columnIndex)
-table.getVisibleColumnIndices()
-table.getHiddenColumnIndices()
-```
-
-### Reordering API
-
-```typescript
-table.moveRow(fromIndex, toIndex)
-table.moveRowUp(index)
-table.moveRowDown(index)
-table.moveRowToTop(index)
-table.moveRowToBottom(index)
-table.swapRows(index1, index2)
-table.moveColumn(fromIndex, toIndex)
-table.swapColumns(index1, index2)
-```
-
-### Clipboard API
-
-```typescript
-table.copyCell(rowIndex, columnIndex)
-table.copyRow(rowIndex)
-table.copyColumn(columnIndex)
-table.copyCellRange(startRow, startCol, endRow, endCol)
-table.copySelectedCells()
-table.copySelectedRows()
-table.pasteAtCell(rowIndex, columnIndex, data)
-```
-
-### Row State API
-
-```typescript
-table.expandRow(index)
-table.collapseRow(index)
-table.toggleRowExpansion(index)
-table.pinRowTop(index)
-table.pinRowBottom(index)
-table.unpinRow(index)
-table.unpinAllRows()
-```
-
-### Metadata API
-
-```typescript
-table.setCellMeta(row, col, key, value)
-table.getCellMeta(row, col, key)
-table.setRowMeta(index, key, value)
-table.getRowMeta(index, key)
-table.setColumnMeta(index, key, value)
-table.getColumnMeta(index, key)
-```
-
-## Examples
-
-The showcase includes 22 interactive examples:
-
-1. **Basic Setup** - Headers, data, caption, row manipulation
-2. **Record-Based Data** - Work with typed records by ID
-3. **Inline Editing** - Double-click to edit with data sync
-4. **Sorting** - Column sorting with state tracking
-5. **Search & Filter** - Search and filter with predicates
-6. **Selection** - Row/cell selection with range support
-7. **Cell Navigation** - Keyboard navigation between cells
-8. **Column Visibility** - Show/hide columns
-9. **Reordering** - Move rows and columns
-10. **Undo/Redo** - History tracking with rollback
-11. **Clipboard** - Copy/paste operations
-12. **Row State** - Expand/collapse and pin rows
-13. **Aggregation** - Sum, average, computed columns
-14. **Validation** - Per-cell validation rules
-15. **Pagination** - Page through large datasets
-16. **Import/Export** - CSV and JSON support
-17. **Styling** - Dynamic classes and attributes
-18. **Transactions** - Batch operations with rollback
-19. **Grouping** - Group rows by values
-20. **Footer & Totals** - Summary rows
-21. **HTML Elements** - Rich content in cells
-22. **Pre-existing Sync** - Connect to existing tables
-
-## Browser Support
-
-Works in all modern browsers that support ES2020+.
-
-## License
-
-MIT © Mike Garcia
+# @mikestools/usetable
+
+A Vue 3 composable for HTML table manipulation with native DOM APIs. Two-layer architecture with `createTable` (vanilla JS) and `useTable` (Vue composable).
+
+## Features
+
+- 🎯 **DOM-First Architecture** - HTML table element is source of truth
+- 📦 **TypeScript First** - Full type safety with IntelliSense
+- 🔗 **Two-Layer Design** - `createTable` (vanilla) + `useTable` (Vue)
+- ✨ **Vue Reactivity** - Computed state that reacts to DOM changes
+
+> **Note:** Data is read from DOM `textContent`, so values are strings. Use `Number()` when working with numeric data.
+
+### Core Features
+
+| Feature          | Description                                   |
+|------------------|-----------------------------------------------|
+| 📋 **Headers**   | Set, update, add, remove header cells         |
+| ➕ **Rows**       | Add, remove, update, move, swap rows          |
+| 📐 **Sections**  | Section-specific row ops (thead/tfoot/tbody)  |
+| 📊 **Columns**   | Add, remove, move, swap columns               |
+| 🔲 **Cells**     | Get, set individual cell values               |
+| ☑️ **Selection** | Row and cell selection with range support     |
+| 🎯 **Focus**     | Cell focus with keyboard navigation           |
+| 📝 **Footer**    | Footer row for totals/summaries               |
+| 🗄️ **Records**  | Work with typed records by ID                 |
+| 🔔 **Events**    | Granular change callbacks                     |
+| ⌨️ **Keyboard**  | Arrow key cell navigation                     |
+| ⚡ **Reactive**   | Vue computed properties                       |
+| 🔄 **Sync**      | Sync with pre-existing DOM tables             |
+
+## Installation
+
+```bash
+npm install @mikestools/usetable vue
+```
+
+## Quick Start
+
+```typescript
+import { ref, onMounted } from 'vue'
+import { useTable, type UseTableReturn } from '@mikestools/usetable'
+
+const tableRef = ref<HTMLTableElement>()
+
+// Template-bound state (updated via callbacks)
+const rowCount = ref(0)
+const totalSalary = ref(0)
+
+// Table instance
+let table: UseTableReturn | undefined
+
+// Update tracked stats from table
+function updateStats() {
+  if (!table) return
+  rowCount.value = table.rowCount.value
+  totalSalary.value = table.data.value.reduce((sum, row) => {
+    return sum + (Number(row[2]) || 0)
+  }, 0)
+}
+
+onMounted(() => {
+  // Create table with initial data
+  table = useTable(ref(tableRef.value!), [
+    ['Alice Johnson', 'Engineering', 85000],
+    ['Bob Smith', 'Marketing', 72000],
+  ], {
+    headers: ['Name', 'Department', 'Salary'],
+    caption: 'Employee Directory'
+  })
+
+  // Initial calculation
+  updateStats()
+
+  // Subscribe to data changes
+  table.onDataChange(() => updateStats())
+})
+
+// Functions can access table directly
+function addEmployee() {
+  table?.addRow(['Carol Williams', 'Sales', 68000])
+}
+```
+
+```vue
+<template>
+  <table ref="tableRef" class="table"></table>
+  <p>Employees: {{ rowCount }}</p>
+  <p>Total Salary: ${{ totalSalary }}</p>
+  <button @click="addEmployee">Add</button>
+</template>
+```
+
+## Architecture
+
+### Two-Layer Design
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        useTable (Vue)                        │
+│  Adds Vue reactivity: ref(), computed(), onUnmounted()       │
+├─────────────────────────────────────────────────────────────┤
+│                    createTable (Vanilla)                     │
+│  Pure DOM manipulation using native table APIs               │
+│  element.tHead, element.tBodies, row.cells, etc.            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Use `createTable`** when:
+- Building non-Vue applications
+- Need vanilla JavaScript table manipulation
+- Want smallest possible bundle size
+
+**Use `useTable`** when:
+- Building Vue 3 applications
+- Need reactive state (computed refs)
+- Want automatic cleanup on component unmount
+
+## API Reference
+
+### useTable
+
+```typescript
+function useTable(
+  elementRef: Ref<HTMLTableElement | null>,
+  initialData?: readonly (readonly CellValue[])[],
+  options?: UseTableOptions
+): UseTableReturn
+```
+
+#### Options
+
+| Option         | Type                    | Description                    |
+|----------------|-------------------------|--------------------------------|
+| `headers`      | `readonly CellValue[]`  | Initial header values          |
+| `caption`      | `string`                | Table caption text             |
+| `footer`       | `readonly CellValue[]`  | Initial footer values          |
+| `idGenerator`  | `() => string`          | Custom row ID generator        |
+
+#### Reactive State
+
+| Property      | Type                                    | Description                    |
+|---------------|-----------------------------------------|--------------------------------|
+| `element`     | `Readonly<Ref<HTMLTableElement>>`       | The table element              |
+| `headers`     | `ComputedRef<readonly string[]>`        | Header values                  |
+| `data`        | `ComputedRef<readonly CellValue[][]>`   | Body data as 2D array          |
+| `rowCount`    | `ComputedRef<number>`                   | Number of body rows            |
+| `columnCount` | `ComputedRef<number>`                   | Number of columns              |
+| `rowIds`      | `ComputedRef<readonly string[]>`        | Array of row IDs               |
+| `footerData`  | `ComputedRef<CellValue[] \| undefined>` | Footer row values              |
+| `captionText` | `ComputedRef<string \| undefined>`      | Caption text                   |
+| `version`     | `Ref<number>`                           | Version counter for reactivity |
+
+#### Selection State
+
+| Property          | Type               | Description                  |
+|-------------------|--------------------|------------------------------|
+| `selection.rows`  | `Ref<Set<number>>` | Selected row indices         |
+| `selection.cells` | `Ref<Set<string>>` | Selected cell keys (row,col) |
+
+#### Focus State
+
+| Property     | Type                                         | Description           |
+|--------------|----------------------------------------------|-----------------------|
+| `focus.cell` | `Ref<{row: number, column: number} \| null>` | Focused cell position |
+
+### Methods
+
+#### Header Methods
+
+```typescript
+setHeaders(headers: readonly CellValue[]): void
+setHeader(index: number, value: CellValue): void
+addHeader(value: CellValue, index?: number): void
+removeHeader(index: number): CellValue | undefined
+```
+
+#### Row Methods
+
+```typescript
+addRow(data: readonly CellValue[], index?: number, id?: string): HTMLTableRowElement
+removeRow(index: number): CellValue[] | undefined
+removeRowById(id: string): CellValue[] | undefined
+updateRow(index: number, data: readonly CellValue[]): void
+updateRowById(id: string, data: readonly CellValue[]): boolean
+moveRow(fromIndex: number, toIndex: number): void
+swapRows(index1: number, index2: number): void
+clearRows(): void
+getRowData(index: number): readonly CellValue[] | undefined
+getRowId(index: number): string | undefined
+getRowIndex(id: string): number
+```
+
+#### Section-Specific Row Methods
+
+Methods using native `HTMLTableSectionElement` APIs for direct section manipulation:
+
+```typescript
+// Generic section methods
+getSectionRows(section: HTMLTableSectionElement): HTMLCollectionOf<HTMLTableRowElement>
+insertSectionRow(section: HTMLTableSectionElement, data: RowData, index?: number, id?: string): HTMLTableRowElement
+deleteSectionRow(section: HTMLTableSectionElement, index: number): CellValue[] | undefined
+getSectionRowCount(section: HTMLTableSectionElement): number
+
+// thead-specific
+addHeadRow(data: RowData, index?: number): HTMLTableRowElement
+removeHeadRow(index: number): CellValue[] | undefined
+getHeadRowCount(): number
+
+// tfoot-specific
+addFootRow(data: RowData, index?: number): HTMLTableRowElement
+removeFootRow(index: number): CellValue[] | undefined
+getFootRowCount(): number
+
+// tbody-specific (supports multiple tbodies)
+addBodyRow(data: RowData, tbodyIndex?: number, rowIndex?: number, id?: string): HTMLTableRowElement
+removeBodyRow(rowIndex: number, tbodyIndex?: number): CellValue[] | undefined
+getBodyRowCount(tbodyIndex?: number): number
+```
+
+#### Column Methods
+
+```typescript
+addColumn(header: CellValue, defaultValue?: CellValue, index?: number): void
+removeColumn(index: number): void
+moveColumn(fromIndex: number, toIndex: number): void
+swapColumns(index1: number, index2: number): void
+getColumnData(columnIndex: number): readonly CellValue[]
+setColumnData(columnIndex: number, data: readonly CellValue[]): void
+```
+
+#### Cell Methods
+
+```typescript
+getCell(rowIndex: number, columnIndex: number): CellValue | undefined
+setCell(rowIndex: number, columnIndex: number, value: CellValue): void
+setCellByRowId(rowId: string, columnIndex: number, value: CellValue): boolean
+setCellRange(startRow: number, startCol: number, data: readonly (readonly CellValue[])[]): void
+getCellElement(rowIndex: number, columnIndex: number): HTMLTableCellElement | null
+```
+
+#### Selection Methods
+
+```typescript
+selectRow(index: number): void
+deselectRow(index: number): void
+toggleRowSelection(index: number): void
+selectAllRows(): void
+deselectAllRows(): void
+selectRowRange(startIndex: number, endIndex: number): void
+isRowSelected(index: number): boolean
+getSelectedRowIndices(): number[]
+getSelectedRowData(): readonly CellValue[][]
+
+selectCell(rowIndex: number, columnIndex: number): void
+deselectCell(rowIndex: number, columnIndex: number): void
+toggleCellSelection(rowIndex: number, columnIndex: number): void
+isCellSelected(rowIndex: number, columnIndex: number): boolean
+clearSelection(): void
+```
+
+#### Focus Methods
+
+```typescript
+focusCell(rowIndex: number, columnIndex: number): void
+clearFocus(): void
+getFocusedCell(): { row: number; column: number } | null
+isCellFocused(rowIndex: number, columnIndex: number): boolean
+moveFocusUp(): boolean
+moveFocusDown(): boolean
+moveFocusLeft(): boolean
+moveFocusRight(): boolean
+moveFocusToFirst(): void
+moveFocusToLast(): void
+```
+
+#### Footer Methods
+
+```typescript
+setFooter(data: readonly CellValue[]): void
+setFooterCell(index: number, value: CellValue): void
+getFooterCell(index: number): string | undefined
+clearFooter(): void
+```
+
+#### Record Methods
+
+```typescript
+setRecords<T extends BaseRecord>(
+  records: readonly T[],
+  fields: readonly (keyof T | ((record: T) => CellValue))[]
+): void
+
+addRecord<T extends BaseRecord>(
+  record: T,
+  fields: readonly (keyof T | ((record: T) => CellValue))[],
+  index?: number
+): string
+
+getRecordData(id: string): readonly CellValue[] | undefined
+updateRecordRow(id: string, data: readonly CellValue[]): boolean
+removeRecord(id: string): boolean
+hasRecord(id: string): boolean
+selectRecords(ids: readonly string[]): void
+getSelectedRecordIds(): string[]
+```
+
+#### Event Subscriptions
+
+```typescript
+onRowAdd(callback: RowAddCallback): () => void
+onRowRemove(callback: RowRemoveCallback): () => void
+onRowUpdate(callback: RowUpdateCallback): () => void
+onCellChange(callback: CellChangeCallback): () => void
+onHeaderChange(callback: HeaderChangeCallback): () => void
+onDataChange(callback: DataChangeCallback): () => void
+onSelectionChange(callback: SelectionChangeCallback): () => void
+onFocusChange(callback: FocusChangeCallback): () => void
+```
+
+#### Lifecycle Methods
+
+```typescript
+enableKeyboardNavigation(): () => void  // Returns cleanup function
+sync(): void                             // Re-sync state from DOM
+destroy(): void                          // Cleanup all resources
+reset(): void                            // Clear all table content
+```
+
+### createTable
+
+For vanilla JavaScript usage without Vue:
+
+```typescript
+import { createTable } from '@mikestools/usetable'
+
+const tableElement = document.querySelector('table')
+const table = createTable(tableElement, [
+  ['Alice', 'Engineering', 85000],
+  ['Bob', 'Marketing', 72000],
+], {
+  headers: ['Name', 'Department', 'Salary']
+})
+
+// Same API as useTable, but without Vue reactivity
+table.addRow(['Carol', 'Sales', 68000])
+console.log(table.getRowCount())  // 3
+```
+
+## Types
+
+```typescript
+// Cell value can be string, number, boolean, null, or DOM element
+type CellValue = string | number | boolean | null | undefined | Node
+
+// Base record interface for record-based operations
+interface BaseRecord {
+  id: string
+  [key: string]: unknown
+}
+
+// Callback types
+type RowAddCallback = (data: readonly CellValue[], index: number, id: string | undefined) => void
+type RowRemoveCallback = (data: readonly CellValue[], index: number, id: string | undefined) => void
+type RowUpdateCallback = (data: readonly CellValue[], index: number) => void
+type CellChangeCallback = (rowIndex: number, columnIndex: number, oldValue: CellValue, newValue: CellValue) => void
+type HeaderChangeCallback = (headers: readonly string[]) => void
+type DataChangeCallback = (data: readonly (readonly CellValue[])[]) => void
+type SelectionChangeCallback = (rows: ReadonlySet<number>, cells: ReadonlySet<string>) => void
+type FocusChangeCallback = (cell: { row: number; column: number } | null) => void
+```
+
+## Examples
+
+See the [showcase](./showcase.html) for interactive examples.
+
+## License
+
+MIT
+