@mikestools/usetable 0.0.4 → 0.0.6

package/README.md

@@ -13,20 +13,19 @@ A Vue 3 composable for HTML table manipulation with native DOM APIs. Two-layer a
 
 ### Core Features
 
-| Feature          | Description                               |
-|------------------|-------------------------------------------|
-| 📋 **Headers**   | Set, update, add, remove header cells     |
-| ➕ **Rows**       | Add, remove, update, move, swap rows      |
-| 📊 **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         |
+| Feature          | Description                                   |
+|------------------|-----------------------------------------------|
+| 📋 **Headers**   | Set, update, add, remove header cells         |
+| ➕ **Rows**       | Add, remove, update rows                      |
+| 📊 **Columns**   | Add, remove columns                           |
+| 🔲 **Cells**     | Get, set individual cell values               |
+| ☑️ **Selection** | Row and cell selection                        |
+| 🎯 **Focus**     | Cell focus with keyboard navigation           |
+| 📝 **Footer**    | Footer row for totals/summaries               |
+| 🔔 **Events**    | Data change callbacks                         |
+| ⌨️ **Keyboard**  | Arrow key cell navigation                     |
+| ⚡ **Reactive**   | Vue computed properties                       |
+| 🔄 **Sync**      | Sync with pre-existing DOM tables             |
 
 ## Installation
 
@@ -121,8 +120,8 @@ function addEmployee() {
 
 ```typescript
 function useTable(
-  elementRef: Ref<HTMLTableElement | null>,
-  initialData?: readonly (readonly CellValue[])[],
+  elementRef: MaybeRef<HTMLTableElement | null>,
+  initialData?: TableData,
   options?: UseTableOptions
 ): UseTableReturn
 ```
@@ -131,84 +130,90 @@ function useTable(
 
 | Option         | Type                    | Description                    |
 |----------------|-------------------------|--------------------------------|
-| `headers`      | `readonly CellValue[]`  | Initial header values          |
+| `headers`      | `readonly string[]`     | Initial header values          |
 | `caption`      | `string`                | Table caption text             |
-| `footer`       | `readonly CellValue[]`  | Initial footer values          |
+| `footer`       | `RowData`               | 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 |
+| Property      | Type                                        | Description                    |
+|---------------|---------------------------------------------|--------------------------------|
+| `element`     | `Readonly<Ref<HTMLTableElement \| null>>`   | 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<readonly CellValue[] \| null>` | Footer row values              |
+| `captionText` | `ComputedRef<string \| null>`               | Caption text                   |
+| `version`     | `Readonly<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) |
+| Property          | Type                                 | Description          |
+|-------------------|--------------------------------------|----------------------|
+| `selection.rows`  | `Readonly<Ref<ReadonlySet<number>>>` | Selected row indices |
+| `selection.cells` | `Readonly<Ref<ReadonlySet<string>>>` | Selected cell keys   |
 
 #### Focus State
 
-| Property     | Type                                         | Description           |
-|--------------|----------------------------------------------|-----------------------|
-| `focus.cell` | `Ref<{row: number, column: number} \| null>` | Focused cell position |
+| Property     | Type                                    | Description           |
+|--------------|-----------------------------------------|-----------------------|
+| `focus.cell` | `Readonly<Ref<CellPosition \| null>>`   | Focused cell position |
 
 ### Methods
 
+#### Structure Methods
+
+```typescript
+createCaption(): HTMLTableCaptionElement | null
+deleteCaption(): void
+createTHead(): HTMLTableSectionElement | null
+deleteTHead(): void
+createTFoot(): HTMLTableSectionElement | null
+deleteTFoot(): void
+createTBody(): HTMLTableSectionElement | null
+```
+
 #### 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
+setHeaders(headers: readonly string[]): void
+addHeader(text: string, index?: number): void
+removeHeader(index: number): void
+clearHeaders(): void
 ```
 
 #### 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
+addRow(data: RowData, index?: number): HTMLTableRowElement | null
+addRowWithId(data: RowData, id: string, index?: number): HTMLTableRowElement | null
+removeRow(index: number): RowData | null
+removeRowById(id: string): RowData | null
+updateRow(index: number, data: RowData): void
 clearRows(): void
-getRowData(index: number): readonly CellValue[] | undefined
-getRowId(index: number): string | undefined
-getRowIndex(id: string): number
+getRow(index: number): HTMLTableRowElement | null
+getRowById(id: string): HTMLTableRowElement | null
+getRowId(index: number): string | null
 ```
 
 #### Column Methods
 
 ```typescript
-addColumn(header: CellValue, defaultValue?: CellValue, index?: number): void
+addColumn(header?: string, 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
+getColumnData(index: number): readonly CellValue[]
+setColumnData(index: 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
+getCell(row: number, column: number): HTMLTableCellElement | null
+getCellValue(row: number, column: number): CellValue
+setCell(row: number, column: number, value: CellValue): void
 ```
 
 #### Selection Methods
@@ -219,84 +224,66 @@ 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[][]
+getSelectedRowIndices(): readonly number[]
+getSelectedRowData(): readonly (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
+selectCell(row: number, column: number): void
+deselectCell(row: number, column: number): void
+toggleCellSelection(row: number, column: number): void
+isCellSelected(row: number, column: number): boolean
 clearSelection(): void
 ```
 
 #### Focus Methods
 
 ```typescript
-focusCell(rowIndex: number, columnIndex: number): void
+focusCell(row: number, column: number): void
 clearFocus(): void
-getFocusedCell(): { row: number; column: number } | null
-isCellFocused(rowIndex: number, columnIndex: number): boolean
+getFocusedCell(): CellPosition | null
+isCellFocused(row: number, column: number): boolean
 moveFocusUp(): boolean
 moveFocusDown(): boolean
 moveFocusLeft(): boolean
 moveFocusRight(): boolean
-moveFocusToFirst(): void
-moveFocusToLast(): void
+enableKeyboardNavigation(): () => void  // Returns cleanup function
 ```
 
 #### Footer Methods
 
 ```typescript
-setFooter(data: readonly CellValue[]): void
-setFooterCell(index: number, value: CellValue): void
-getFooterCell(index: number): string | undefined
+getFooter(): RowData | null
+setFooter(data: RowData): void
 clearFooter(): void
 ```
 
-#### Record Methods
+#### Caption Methods
+
+```typescript
+getCaption(): string | null
+setCaption(text: string): void
+```
+
+#### Bulk Operations
 
 ```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[]
+getData(): TableData
+setData(data: TableData): void
+sync(): void  // Trigger reactive update
 ```
 
 #### 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
+onRowAdd(callback: (index: number, id: string | null) => void): () => void
+onRowRemove(callback: (index: number, id: string | null) => void): () => void
+onDataChange(callback: () => void): () => 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
+destroy(): void  // Cleanup all resources
 ```
 
 ### createTable
@@ -325,21 +312,22 @@ console.log(table.getRowCount())  // 3
 // 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
+// Row data is an array of cell values
+type RowData = readonly CellValue[]
+
+// Table data is a 2D array
+type TableData = readonly RowData[]
+
+// Cell position for focus/navigation
+interface CellPosition {
+  readonly row: number
+  readonly column: number
 }
 
 // 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 RowAddCallback = (data: readonly CellValue[], index: number, id: string | null) => void
+type RowRemoveCallback = (data: readonly CellValue[], index: number, id: string | null) => 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