@mikestools/usetable 0.0.1 → 0.0.2

package/README.md

@@ -1,519 +1,586 @@
-# @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                               |
-|---------------------------|-------------------------------------------|
-| 🔀 **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[]>>
-}
-```
-
-### 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 21 interactive examples:
-
-1. **Basic Setup** - Headers, data, caption, row manipulation
-2. **Inline Editing** - Double-click to edit with data sync
-3. **Sorting** - Column sorting with state tracking
-4. **Search & Filter** - Search and filter with predicates
-5. **Selection** - Row/cell selection with range support
-6. **Cell Navigation** - Keyboard navigation between cells
-7. **Column Visibility** - Show/hide columns
-8. **Reordering** - Move rows and columns
-9. **Undo/Redo** - History tracking with rollback
-10. **Clipboard** - Copy/paste operations
-11. **Row State** - Expand/collapse and pin rows
-12. **Aggregation** - Sum, average, computed columns
-13. **Validation** - Per-cell validation rules
-14. **Pagination** - Page through large datasets
-15. **Import/Export** - CSV and JSON support
-16. **Styling** - Dynamic classes and attributes
-17. **Transactions** - Batch operations with rollback
-18. **Grouping** - Group rows by values
-19. **Footer & Totals** - Summary rows
-20. **HTML Elements** - Rich content in cells
-21. **Pre-existing Sync** - Connect to existing tables
-
-## Browser Support
-
-Works in all modern browsers that support ES2020+.
-
-## License
-
-MIT © Mike Garcia
+# @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