@danielgindi/dgtable.js 2.0.7 → 2.0.8

package/README.md

@@ -1,288 +1,553 @@
-DGTable.js
-==========
-
-This is a table View for vanilla JS, which is meant to be high-performance, and allow simple user interactions with the UI, such as:
-* Sorting
-* Sorting by more than one column
-* Moving columns
-* Resizing columns
-* Full cell preview when hovering
-* Native RTL support
-* Variable row height
-
-Other features implemented are:
-* Mix absolute column widths with relative column widths
-* Virtual table mode (to supply high performance with hundreds of thousands of rows). This is the default.
-* Non-virtual table mode is fully supported, but for giant amounts of data it is not recommended.
-* Option to set a fixed width for the table so resizing (relative) columns will still make sure the table will not be less (and/or more) than the specified width.
-* Option to have both scrollbars inside the table. (set `width: DGTable.Width.SCROLL`)
-
-`jquery.dgtable` users:
-* Older `jquery.dgtable` can either keep using `jquery.dgtable`, or migrate to this new version which is more lightweight. 
-* The new version's API is the same as the old one, except that:
-  * No `$el` property
-  * No auto-clear of jQuery data.
-  * There is now an `emit` method instead of `trigger`.
-  * Event arguments are now always a single value/object.
-  * Props on DOM elements are now: `'columnName'` on a cell, `'index'/'vIndex'` on a row, `'columnName'/rowIndex'/'rowVIndex'` on a cellPreview
-
-My TODO list:
-* TODO: Have a simple and accurate API documentation here in the readme
-
-## Dev environment
-
-* Using grunt over Node.js to automate validating and building.
-* After installing Node.js, use `npm install`, and `npm install -g grunt-cli` to prepare building environment.
-* Use `grunt style` to just test for correct styling.
-* Use `grunt build` or just `grunt` to compile for release.
-* I am using Google Closure Compiler, because UglifyJS does not work with the JSDoc, and there's a major difference in size & performance of the output code.
-* Some features of jshint are disabled because it does not work well with JSDoc which is used for Google Closue Compiler.
-* Indentations in my editor are set to 4 spaces, and jshint validates that.
-
-## Me
-* Hi! I am Daniel Cohen Gindi. Or in short- Daniel.
-* danielgindi@gmail.com is my email address.
-* That's all you need to know.
-
-## Help
-
-I have invested, and investing, a lot of time in this project.
-If you want to help, you could:
-* Actually code, and issue pull requests
-* Test the library under different conditions and browsers
-* Create more demo pages
-* Spread the word
-* 
-[![Donate](https://www.paypalobjects.com/en_US/i/btn/btn_donate_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=G22LPLJ79NBYQ)
-
-## API
-
-To create a new table, just use `var myTable = new DGTable(INIT_OPTIONS)`.
-
-#### `INIT_OPTIONS`
-
-* **columns**: `COLUMN_OPTIONS[]` (Array of COLUMN_OPTIONS objects)
-  * **name**: `string` Name of the column
-  * **label**: `string=name` Used for the header of this column
-  * **dataPath**: `string=name` Path to the data to show (Defaults to `name`)
-  * **comparePath**: `string=name` Path to the data to use for comparison (Defaults to `dataPath`)
-  * **width**: `number|string`
-    * A simple number (i.e `10`, `30`, `50`) will set an absolute width for the column.
-    * A percentage (i.e `'30%'`) or a 0-1 decimal value (i.e `0.2`, `0.7`) will set a relative width for the column, out of the full table's width.
-    * Any other value, like `0`, `null` etc. will set an automatic width mode, base of the header's content length.
-  * **resizable**: `boolean=true` Is this column resizable?
-  * **sortable**: `boolean=true` Is this column sortable?
-  * **movable**: `boolean=true` Is this column movable?
-  * **visible**: `boolean=true` Is this column visible?
-  * **cellClasses**: `string` Classes to add to the DOM element of this cell
-  * **ignoreMin**: `boolean=false` Should this column ignore the minimum width specified for the table columns?
-* **height**: `number` Suggested height for the table
-* **width**: `DGTable.Width=DGTable.Width.NONE` The way that the width of the table will be handled
-  * `DGTable.Width.NONE`: No special handling
-  * `DGTable.Width.AUTO`: Sets the width automatically
-  * `DGTable.Width.SCROLL`: Creates a horizontal scroll when required
-* **virtualTable**: `boolean=true` When set, the table will work in virtual mode, which means only the visible rows are rendered. Rows must have fixed height in this mode.
-* **estimatedRowHeight**: `number?` Sets the estimated row height for the table. This is used for virtual table mode, to calculate the estimated scroll size. Will be auto calculated by default.
-* **resizableColumns**: `boolean=true` Turns on or off the resizable columns globally.
-* **movableColumns**: `boolean=true` Turns on or off the movable columns globally.
-* **sortableColumns**: `number=1` How many columns can you sort by, one after another?
-* **adjustColumnWidthForSortArrow**: `boolean=true` When set, the columns will automatically grow to accommodate for the sort arrow.
-* **relativeWidthGrowsToFillWidth**: `boolean=true` When set, relative width columns automatically grow to fill the table's width.
-* **relativeWidthShrinksToFillWidth**: `boolean=false` When set, relative width columns automatically shrink to fill the table's width.
-* **convertColumnWidthsToRelative**: `boolean=false` When set, auto-width columns are automatically converted to relatives.
-* **autoFillTableWidth**: `boolean=false` When set, columns are stretched proportionally to fill the table width (only if there is space left). Will supersede `relativeWidthGrowsToFillWidth` in the future.
-* **allowCancelSort**: `boolean=true` When set, the sorting arrows will have 3 modes - asc, desc, and cancelled.
-* **cellClasses**: `string` Classes to add to the DOM element of all cells
-* **sortColumn**: `string|string[]|COLUMN_SORT_OPTIONS|COLUMN_SORT_OPTIONS[]` Columns to sort by
-  * Can be a column or an array of columns.
-  * Each column is a `string` or a `COLUMN_SORT_OPTIONS`:
-  * **column**: `string` Column name
-  * **descending**: `boolean=false` Is this column sorted in descending order?
-* **cellFormatter**: `Function(string value, string columnName, Object rowData)string` *(optional)* A formatter function which will return the HTML for the cell. By default the formatter is a plain HTML formatter.
-* **headerCellFormatter**: `Function(string value, string columnName)string` *(optional)* A formatter function which will return the HTML for the cell's header. By default the formatter is a plain HTML formatter.
-* **rowsBufferSize**: `number=10` The size of the rows buffer, for virtual table
-* **minColumnWidth**: `number=35` In pixels, the minimum width for a column
-* **resizeAreaWidth**: `number=8` The size of the area where you can drag to resize.
-* **onComparatorRequired**: `function(columnName: string, descending: boolean, defaultComparator: function(a,b):number):{function(a,b):number}` A callback that can pass a comparator function for each column and mode as required.
-* **resizerClassName**: `string='dgtable-resize'` Class name for the dragged resizing element (showing when resizing a column)
-* **tableClassName**: `string='dgtable'` Class name for the table
-* **allowCellPreview**: `boolean=true` When set, hovering on truncated cells will show a preview of the full content.
-* **allowHeaderCellPreview**: `boolean=true` Allow for toggling off **allowCellPreview** for headers specifically.
-* **cellPreviewAutoBackground**: `boolean=true` When set, the preview cell will receive its background automatically from the cell.
-* **cellPreviewClassName**: `string='dgtable-cell-preview'` Class name for the cell preview element
-* **className**: `string='dgtable-wrapper'` Element class name.
-* **el**: `Element?` Optional element to take over
-* **filter**: `Function(row: Object, args: Object): boolean` *(optional)* A filter function for using with the `filter` method
-
-#### Events triggered by DGTable:
-
-* `renderskeleton`: The table is re-drawing it's base elements, including headers. Will always be followed by a `render` event.
-* `render`: The table has finished rendering (after adding rows etc.).
-* `cellpreview`: We are about to show a cell preview - `{ el: Element, rowIndex: number|null, name: string, rowData: Object|null, cell: Element, cellEl: Element }`
-  * At this stage you can prevent showing the preview, by calling `table.hideCellPreview`
-* `cellpreviewdestroy`: Cell preview element is about to be destroyed after hiding - `{ el: Element, name: string, filteredRowIndex: number|null, rowIndex: Object|null, cell: Element, cellEl: Element }`
-  * You can use this event to release any resources that you may have used in `cellPreview` event.
-* `headerrowcreate`: The header row has just been created - `Element`
-* `headerrowdestroy`: Called just before removing the header row DOM element from the table - `Element`
-* `rowcreate`: A row has just been created - `{ filteredRowIndex: number, rowIndex: number, rowEl: Element, rowData: Object }`
-* `rowclick`: A row has just been created - `{ event: MouseEvent, rowIndex: number, rowIndex: number, rowEl: Element, rowData: Object }`
-* `rowdestroy`: Called just before removing a row DOM element from the table - `Element`
-* `addrows`: Data rows have been added to the table - `({ count: number, clear: boolean })`
-* `addcolumn`: A column was added - `string` (the column's name)
-* `removecolumn`: A column was removed - `string` (the column's name)
-* `movecolumn`: A column was moved - `({ name: string, src: number, dest: number })`
-* `showcolumn`: A column was shown - `string` (the column's name)
-* `hidecolumn`: A column was hidden - `string` (the column's name)
-* `columnwidth`: A column was resized - `({ name: string, width: number|string, oldWidth: number|string })`
-* `filter`: A filter was applied - `any` - the arguments passed to the filter method
-* `filterclear`: A filter was cleared
-* `sort`: The data was sorted - `{ sorts: { "column": "column's name", "descending": true|false }[], resort: true|undefined, comparator: Function }`
-* `headercontextmenu`: A context menu should be shown for a header cell - `({ columnName: string, pageX: number, pageY: number, bounds: { left: number, top: number, width: number, height: number } })`
-
-- Member functions:
-* `on(eventName, {Function?} callback)`: Adds an event listener
-* `once(eventName, {Function?} callback)`: Adds a one-shot event listener
-* `off(eventName, {Function?} callback)`: Removes an event listener
-* `render()`: Renders the view. Should be called after adding to the DOM, and when the viewport has changed and the table has no knowledge of it.
-* `clearAndRender({boolean} render = true)`: Forces a full render of the table
-* `setColumns({COLUMN_OPTIONS[]} columns, {boolean} render = true) {DGTable}`: Sets the table columns
-* `addColumn({COLUMN_OPTIONS} columnData, {string|number} before = -1, {boolean} render = true) {DGTable}`: Add a column to the table
-  * **columnData**: Column properties. Same manner as in the **columns** options when initializing the DGTable
-  * **before**: Column name or order to be inserted before.
-  * *returns* Self, to allow for call chaining.
-* `removeColumn({string} column, {boolean} render = true) {DGTable}`: Remove a column from the table
-  * **column**: Column name
-  * *returns* Self, to allow for call chaining.
-* `setFilter({Function(row: Object, args: Object): boolean} filterFunc) {DGTable}`: Sets a new filtering function, set null for default.
-  * **filterFunc**: The filtering function receives a row and an options object, and returns true for any row that passes the filter.
-  * *returns* Self, to allow for call chaining.
-* `setCellFormatter({Function(value: *, columnName: string, row: Object):string|null} formatter) {DGTable}`: Sets a new cell formatter.
-  * **formatter**: The cell formatter. Should return an HTML.
-  * *returns* Self, to allow for call chaining.
-* `setHeaderCellFormatter({Function(label: string, columnName: string):string|null} formatter) {DGTable}`: Sets a new header cell formatter.
-  * **formatter**: The cell formatter. Should return an HTML.
-  * *returns* Self, to allow for call chaining.
-* `filter({Object} args) {DGTable}`: Filter the visible rows in the table
-  * **args**: Options to pass to the filtering function
-  * *returns* Self, to allow for call chaining.
-* `filter({{column: string, keyword: string, caseSensitive: boolean}} args) {DGTable}`: Syntax for default filtering function.
-  * **args.column**: Name of the column to filter on
-  * **args.keyword**: Tests the specified column if contains this keyword
-  * **args.caseSensitive**: Use caseSensitive filtering
-  * *returns* Self, to allow for call chaining.
-* `clearFilter() {DGTable}`: Clears the current filter
-  * *returns* Self, to allow for call chaining.
-* `setColumnLabel({string} column, {string} label) {DGTable}`: Set a new label to a column
-  * **column**: Name of the column
-  * **label**: New label for the column
-  * *returns* Self, to allow for call chaining.
-* `moveColumn({string|number} src, {string|number} dest, visibleOnly = true) {DGTable}`: Move a column to a new position
-  * **src**: Name or position of the column to be moved
-  * **dest**: Name of the column currently in the desired position, or the position itself
-  * **visibleOnly**: Should consider only visible columns and visible-relative indexes
-  * *returns* Self, to allow for call chaining.
-* `sort({string?} column, {boolean?} descending, {boolean=false} add) {DGTable}`: Sort the table. This does not render automatically, so you may need to call render() too.
-  * **src**: Name of the column to sort on
-  * **descending**: Sort in descending order (if not specified, defaults to false or reverses current descending mode if sorting by same column)
-  * **add**: Should this sort be on top of the existing sort? (For multiple column sort)
-  * *returns* Self, to allow for call chaining.
-* `resort() {DGTable}`: Re-sort the table using current sort specifiers. This does not render automatically, so you may need to call render() too.
-  * *returns* Self, to allow for call chaining.
-* `setColumnVisible({string} column, {boolean} visible) {DGTable}`: Show or hide a column
-  * **column**: Unique column name
-  * **visible**: New visibility mode for the column
-  * *returns* Self, to allow for call chaining.
-* `isColumnVisible({string} column, {boolean} visible) {boolean}`: Get the visibility mode of a column
-  * *returns* True if visible
-* `setMinColumnWidth({number} minColumnWidth) {DGTable}`: Globally set the minimum column width
-  * **minColumnWidth**: Minimum column width
-  * *returns* Self, to allow for call chaining.
-* `getMinColumnWidth() {number}`: Get the current minimum column width
-  * *returns* Minimum column width
-* `setSortableColumns({number} sortableColumns) {DGTable}`: Set the limit on concurrent columns sortedh
-  * **sortableColumns**: Minimum column width
-  * *returns* Self, to allow for call chaining.
-* `getSortableColumns() {number}`: Get the limit on concurrent columns sorted
-  * *returns* How many sortable columns are allowed?
-* `getHeaderRowElement() {Element}`: Get the DOM element of the header row
-  * *returns* a DOM element
-* `setMovableColumns({boolean} movableColumns) {DGTable}`: *Undocumented yet*
-* `getMovableColumns() {boolean}`: *Undocumented yet*
-* `setResizableColumns({boolean} resizableColumns) {DGTable}`: *Undocumented yet*
-* `getResizableColumns() {boolean}`: *Undocumented yet*
-* `setOnComparatorRequired({function(columnName: string, descending: boolean, defaultComparator: function(a,b):number):{function(a,b):number}}|null comparatorCallback) {DGTable}`: Sets a functions that supplies comparators dynamically
-  * **comparatorCallback**: a function that returns the comparator for a specific column
-* `setCustomSortingProvider({{function(data: any[], sort: function(any[]):any[]):any[]}|null} customSortingProvider) {DGTable}`: sets custom sorting function for a data set
-  * **customSortingProvider**: provides a custom sorting function (not the comparator, but a sort() alternative) for a data set
-* `setColumnWidth({string} column, {number|string} width) {DGTable}`: *Undocumented yet*
-* `getColumnWidth({string} column) {string|null}`: *Undocumented yet*
-* `getColumnConfig({string} column name) {SERIALIZED_COLUMN}`: *Undocumented yet*
-* `getColumnsConfig() {Object}`: *Undocumented yet*
-* `getSortedColumns() {Array.<SERIALIZED_COLUMN_SORT>}`: *Undocumented yet*
-* `getHtmlForRowCell(row: number, columnName: string) {string}`: Returns the HTML for specified cell in a row.
-  * **row**: Index of row
-  * **columnName**: Name of cell
-  * *returns* HTML for cell. By default cell content is *not* HTML encoded, you should encode appropriately in your `cellFormatter`.
-* `getHtmlForRowDataCell(rowData: Object, columnName: string) {string|null}`: Returns the HTML string for a specific cell. Can be used externally for special cases (i.e. when setting a fresh HTML in the cell preview through the callback).
-  * **rowData**: Actual row data
-  * **columnName**: Name of column
-  * *returns*  string for the specified cell
-* `getDataForRow(rowIndex: number): Object`: Gets the row data for a specific row
-  * *returns* row data at the specified index, out of all rows (not filtered)
-* `getRowCount(): number`: Gets the number of rows
-  * *returns* the number of rows
-* `getIndexForRow(row: Object): number`: Finds the index of the specified row
-  * *returns* the index of the specified row
-* `getFilteredRowCount(): number`: Gets the number of filtered rows
-  * *returns* the number of rows in the filtered set (defaults to full row count if no filtering is active)
-* `getIndexForFilteredRow(row: Object): number`: Finds the index of the specified row within the filtered results
-  * *returns* the index of the specified row
-* `getDataForFilteredRow(row: number): Object`: *Undocumented yet*
-* `getRowElement(rowIndex: number): Element`: Returns the element of the specified row (unfiltered index)
-* `getRowYPos(rowIndex: number): number?`: Returns the Y pos of the specified row (unfiltered index)
-* `tableWidthChanged() {DGTable}`: *Undocumented yet*
-* `tableHeightChanged() {DGTable}`: *Undocumented yet*
-* `addRows({Object[]} data, {number} at = -1, {boolean} resort = false, {boolean} render = true) {DGTable}`: Adds the specified rows at the specified position, and optionally resorts the data
-* `removeRow({number} rowIndex, {boolean} render = true) {DGTable}`: Removes one row at the specified position
-* `removeRows({number} rowIndex, {number} count, {boolean} render = true) {DGTable}`: Removes rows at the specified position
-* `refreshRow({number} rowIndex) {DGTable}`: Refreshes the row specified
-  * *returns* Self
-* `refreshAllVirtualRows() {DGTable}`: Refreshes all virtual rows
-  * *returns* Self
-* `setRows(data: Object[], resort: boolean=false) {DGTable}`: Rests the table rows to the provided array of rows.
-  * **data**: New rows for the table
-  * **resort**: Should re-sort the table?
-  * *returns* Self, to allow for call chaining.
-* `getUrlForElementContent({string} id) {string?}`: *Undocumented yet*
-* `isWorkerSupported() {boolean}`: *Undocumented yet*
-* `createWebWorker({string} url) {Worker?}`: *Undocumented yet*
-* `unbindWebWorker({Worker} worker) {DGTable}`: *Undocumented yet*
-* `hideCellPreview() {DGTable}`: Hide any cell preview showing currently, or prevent showing a cell preview from within the `cellpreview` event.
-* `destroy()`: Destroy the table and free all of its memory.
+# DGTable.js
 
-## License
+A high-performance virtual table component for vanilla JavaScript.
 
-All the code here is under MIT license. Which means you could do virtually anything with the code.
-I will appreciate it very much if you keep an attribution where appropriate.
+[![npm version](https://badge.fury.io/js/@danielgindi%2Fdgtable.svg)](https://www.npmjs.com/package/@danielgindi/dgtable)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-    The MIT License (MIT)
-    
-    Copyright (c) 2013 Daniel Cohen Gindi (danielgindi@gmail.com)
+## Features
+
+- **High Performance** - Virtual scrolling renders only visible rows, handling hundreds of thousands of rows smoothly
+- **Column Management** - Sort, resize, reorder, and hide/show columns
+- **Multi-column Sorting** - Sort by multiple columns simultaneously
+- **Flexible Column Widths** - Mix absolute, relative, and auto-calculated widths
+- **Cell Preview** - Hover tooltips for truncated cell content
+- **Sticky Columns** - Pin columns to the start or end of the table
+- **RTL Support** - Native right-to-left language support
+- **Variable Row Height** - Support for rows with different heights
+- **Filtering** - Built-in filtering with custom filter function support
+- **Web Worker Support** - Load data asynchronously via Web Workers
+
+## Installation
+
+```bash
+npm install @danielgindi/dgtable
+```
+
+## Quick Start
+
+```javascript
+import DGTable from '@danielgindi/dgtable';
+
+const table = new DGTable({
+    columns: [
+        { name: 'id', label: 'ID', width: 80 },
+        { name: 'name', label: 'Name', width: '30%' },
+        { name: 'email', label: 'Email' },
+    ],
+    height: 400,
+    virtualTable: true,
+});
+
+document.getElementById('container').appendChild(table.el);
+
+table.setRows([
+    { id: 1, name: 'John Doe', email: 'john@example.com' },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com' },
+]);
+
+table.render();
+```
+
+## Migration from jquery.dgtable
+
+If you're migrating from the older jQuery version:
+
+- No `$el` property - use `table.el` instead
+- No auto-clear of jQuery data
+- Use `emit()` instead of `trigger()` for events
+- Event arguments are now always a single value/object
+- DOM element properties: `'columnName'` on cells, `'index'/'vIndex'` on rows
+
+---
+
+## API Reference
+
+### Constructor Options
+
+```typescript
+new DGTable(options?: DGTableOptions)
+```
+
+#### Table Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `el` | `Element` | - | Optional existing element to use as container |
+| `className` | `string` | `'dgtable-wrapper'` | CSS class for the wrapper element |
+| `height` | `number` | - | Table height in pixels |
+| `width` | `DGTable.Width` | `NONE` | Width handling mode: `NONE`, `AUTO`, or `SCROLL` |
+| `virtualTable` | `boolean` | `true` | Enable virtual scrolling (recommended for large datasets) |
+| `estimatedRowHeight` | `number` | `40` | Estimated row height for virtual scrolling calculations |
+| `rowsBufferSize` | `number` | `3` | Number of rows to render outside visible area |
+
+#### Column Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `columns` | `ColumnOptions[]` | `[]` | Array of column definitions |
+| `minColumnWidth` | `number` | `35` | Minimum column width in pixels |
+| `resizableColumns` | `boolean` | `true` | Allow column resizing |
+| `movableColumns` | `boolean` | `true` | Allow column reordering |
+| `sortableColumns` | `number` | `1` | Maximum number of columns to sort by |
+| `allowCancelSort` | `boolean` | `true` | Allow cycling through asc → desc → none |
+| `adjustColumnWidthForSortArrow` | `boolean` | `true` | Auto-expand columns for sort indicator |
+| `relativeWidthGrowsToFillWidth` | `boolean` | `true` | Expand relative columns to fill space |
+| `relativeWidthShrinksToFillWidth` | `boolean` | `false` | Shrink relative columns to fit |
+| `convertColumnWidthsToRelative` | `boolean` | `false` | Convert auto widths to relative |
+| `autoFillTableWidth` | `boolean` | `false` | Stretch columns to fill table width |
+| `resizeAreaWidth` | `number` | `8` | Width of resize drag area in pixels |
+
+#### Column Definition
+
+```typescript
+{
+    name: string;                  // Required: unique identifier
+    label?: string;                // Header text (defaults to name)
+    width?: number | string;       // number (px), '30%', or 0.3 (relative)
+    dataPath?: string | string[];  // Path to data (defaults to [name])
+    comparePath?: string | string[]; // Path for sorting (defaults to dataPath)
+    resizable?: boolean;           // Allow resizing this column (default: true)
+    sortable?: boolean;            // Allow sorting by this column (default: true)
+    movable?: boolean;             // Allow moving this column (default: true)
+    visible?: boolean;             // Column visibility (default: true)
+    sticky?: 'start' | 'end' | false | null; // Pin to start or end
+    cellClasses?: string;          // Additional CSS classes for cells
+    ignoreMin?: boolean;           // Ignore minColumnWidth for this column
+    order?: number;                // Column order
+}
+```
+
+#### Formatting & Filtering
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `cellFormatter` | `(value: unknown, columnName: string, rowData: RowData) => string` | Custom cell HTML renderer |
+| `headerCellFormatter` | `(label: string, columnName: string) => string` | Custom header cell renderer |
+| `filter` | `(row: RowData, args: unknown) => boolean` | Custom filter function |
+| `sortColumn` | `string \| string[] \| ColumnSortOptions \| ColumnSortOptions[]` | Initial sort configuration |
+| `onComparatorRequired` | `(columnName: string, descending: boolean, defaultComparator: ComparatorFunction) => ComparatorFunction` | Custom comparator provider |
+| `customSortingProvider` | `(data: RowData[], sort: (data: RowData[]) => RowData[]) => RowData[]` | Custom sorting implementation |
+
+#### Styling
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `tableClassName` | `string` | `'dgtable'` | Base CSS class for the table |
+| `cellClasses` | `string` | `''` | Additional classes for all cells |
+| `resizerClassName` | `string` | `'dgtable-resize'` | Class for resize handle |
+| `cellPreviewClassName` | `string` | `'dgtable-cell-preview'` | Class for cell preview |
+| `allowCellPreview` | `boolean` | `true` | Show preview on hover |
+| `allowHeaderCellPreview` | `boolean` | `true` | Show preview for headers |
+| `cellPreviewAutoBackground` | `boolean` | `true` | Match preview background to cell |
+| `resizeAreaWidth` | `number` | `8` | Width of resize drag area |
+
+---
+
+### Methods
+
+#### Rendering
+
+```javascript
+table.render()                    // Render the table
+table.clearAndRender(render=true) // Force full re-render
+```
+
+#### Column Management
+
+```javascript
+table.setColumns(columns, render=true)           // Replace all columns
+table.addColumn(columnData, before=-1, render)   // Add a column
+table.removeColumn(columnName, render=true)      // Remove a column
+table.setColumnLabel(column, label)              // Update column label
+table.moveColumn(src, dest, visibleOnly=true)    // Reorder columns
+table.setColumnVisible(column, visible)          // Show/hide column
+table.isColumnVisible(column)                    // Check visibility
+table.setColumnWidth(column, width)              // Set column width
+table.getColumnWidth(column)                     // Get column width
+table.getColumnConfig(column)                    // Get column config
+table.getColumnsConfig()                         // Get all columns config
+```
+
+#### Sorting
+
+```javascript
+table.sort(column, descending, add=false)  // Sort by column
+table.resort()                             // Re-apply current sort
+table.getSortedColumns()                   // Get current sort state
+table.setSortableColumns(count)            // Set max sortable columns
+table.getSortableColumns()                 // Get max sortable columns
+```
+
+#### Data Management
+
+```javascript
+table.setRows(data, resort=false)                      // Replace all rows
+table.addRows(data, at=-1, resort=false, render=true)  // Add rows
+table.removeRow(rowIndex, render=true)                 // Remove one row
+table.removeRows(rowIndex, count, render=true)         // Remove multiple rows
+table.refreshRow(rowIndex, render=true)                // Refresh a row
+table.refreshAllVirtualRows()                          // Refresh all visible rows
+
+table.getRowCount()                        // Total row count
+table.getFilteredRowCount()                // Filtered row count
+table.getDataForRow(rowIndex)              // Get row data by index
+table.getDataForFilteredRow(filteredIndex) // Get filtered row data
+table.getIndexForRow(rowData)              // Find row index
+table.getIndexForFilteredRow(rowData)      // Find filtered row index
+table.getRowElement(rowIndex)              // Get row DOM element
+table.getRowYPos(rowIndex)                 // Get row Y position
+```
+
+#### Filtering
+
+```javascript
+table.setFilter(filterFn)     // Set custom filter function
+table.filter(args)            // Apply filter with arguments
+table.clearFilter()           // Clear active filter
+
+// Built-in filter example:
+table.filter({ column: 'name', keyword: 'john', caseSensitive: false });
+```
+
+#### Formatters
+
+```javascript
+table.setCellFormatter(fn)        // Set cell formatter
+table.setHeaderCellFormatter(fn)  // Set header formatter
+table.getHtmlForRowCell(rowIndex, columnName)      // Get cell HTML
+table.getHtmlForRowDataCell(rowData, columnName)   // Get cell HTML from data
+```
+
+#### Layout
+
+```javascript
+table.tableWidthChanged(forceUpdate=false, renderColumns=true)  // Notify width change
+table.tableHeightChanged()                                      // Notify height change
+table.setMinColumnWidth(width)                                  // Set global min width
+table.getMinColumnWidth()                                       // Get global min width
+```
+
+#### Cell Preview
+
+```javascript
+table.hideCellPreview()   // Hide or prevent cell preview
+table.abortCellPreview()  // Alias for hideCellPreview()
+```
+
+#### Column Features
+
+```javascript
+table.setMovableColumns(movable)     // Enable/disable column moving
+table.getMovableColumns()            // Get movable state
+table.setResizableColumns(resizable) // Enable/disable column resizing
+table.getResizableColumns()          // Get resizable state
+```
+
+#### Sorting Customization
+
+```javascript
+table.setOnComparatorRequired(callback)   // Set comparator provider
+table.setCustomSortingProvider(provider)  // Set custom sort provider
+```
+
+#### Web Workers
+
+```javascript
+table.isWorkerSupported()                     // Check Web Worker support
+table.createWebWorker(url, start=true, resort=false)  // Create worker
+table.unbindWebWorker(worker)                 // Unbind worker
+table.getUrlForElementContent(elementId)      // Create blob URL from element
+```
+
+#### DOM Access
+
+```javascript
+table.el                      // The table wrapper element
+table.getHeaderRowElement()   // Get header row element
+```
+
+#### Events
+
+```typescript
+// TypeScript users get full autocompletion and type checking!
+table.on('rowclick', (data) => {
+    // data is typed as RowClickEvent
+    console.log(data.rowIndex, data.rowData);
+});
+
+// Custom events are also supported (for using table as event bus)
+table.on('my-custom-event', (data) => {
+    // data is typed as `unknown` by default
+    console.log(data);
+});
+
+// You can specify the type for custom events
+table.on<{ customField: string }>('my-typed-event', (data) => {
+    console.log(data.customField); // TypeScript knows the type
+});
+
+table.on(event, handler)      // Add event listener (typed for built-in events)
+table.once(event, handler)    // Add one-time listener (typed)
+table.off(event, handler)     // Remove listener
+table.emit(event, data)       // Emit event (typed for built-in events)
+```
+
+#### Lifecycle
+
+```javascript
+table.destroy()  // Destroy table and free memory
+table.close()    // Alias for destroy()
+table.remove()   // Alias for destroy()
+```
+
+---
+
+### Events
+
+Subscribe to events using `table.on(eventName, handler)`. 
+
+Built-in events have fully typed handlers with autocompletion. You can also use the table's event system as an event bus for your own custom events.
+
+#### Rendering Events
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `render` | `undefined` | Table finished rendering |
+| `renderskeleton` | `undefined` | Table structure rebuilt |
+
+#### Row Events
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `rowcreate` | `RowCreateEvent` | Row element created |
+| `rowclick` | `RowClickEvent` | Row clicked |
+| `rowdestroy` | `HTMLElement` | Row element about to be removed |
+
+```typescript
+interface RowCreateEvent {
+    filteredRowIndex: number;  // Index in filtered data
+    rowIndex: number;          // Index in original data
+    rowEl: HTMLElement;        // The row DOM element
+    rowData: RowData;          // The row data object
+}
+
+interface RowClickEvent {
+    event: MouseEvent;         // The original mouse event
+    filteredRowIndex: number;  // Index in filtered data
+    rowIndex: number;          // Index in original data
+    rowEl: HTMLElement;        // The row DOM element
+    rowData: RowData;          // The row data object
+}
+```
+
+#### Cell Preview Events
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `cellpreview` | `CellPreviewEvent` | Cell preview showing |
+| `cellpreviewdestroy` | `CellPreviewDestroyEvent` | Cell preview hiding |
+
+```typescript
+interface CellPreviewEvent {
+    el: Element | null;        // Preview element's first child
+    name: string;              // Column name
+    rowIndex: number | null;   // Row index (null for header)
+    rowData: RowData | null;   // Row data (null for header)
+    cell: HTMLElement;         // Original cell element
+    cellEl: HTMLElement;       // Cell's inner element
+}
+
+interface CellPreviewDestroyEvent {
+    el: ChildNode | null;      // Preview element's first child
+    name: string;              // Column name
+    rowIndex: number | null;   // Row index (null for header)
+    rowData: RowData | null;   // Row data (null for header)
+    cell: HTMLElement | null;  // Original cell element
+    cellEl: ChildNode | null;  // Cell's inner element
+}
+```
+
+#### Header Events
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `headerrowcreate` | `HTMLElement` | Header row created |
+| `headercontextmenu` | `HeaderContextMenuEvent` | Header right-click |
+
+```typescript
+interface HeaderContextMenuEvent {
+    columnName: string;        // Column that was right-clicked
+    pageX: number;             // Mouse X position
+    pageY: number;             // Mouse Y position
+    bounds: {                  // Cell bounds
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+}
+```
+
+#### Column Events
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `addcolumn` | `string` | Column name added |
+| `removecolumn` | `string` | Column name removed |
+| `movecolumn` | `MoveColumnEvent` | Column moved |
+| `showcolumn` | `string` | Column name shown |
+| `hidecolumn` | `string` | Column name hidden |
+| `columnwidth` | `ColumnWidthEvent` | Column resized |
+
+```typescript
+interface MoveColumnEvent {
+    name: string;              // Column name
+    src: number;               // Original order position
+    dest: number;              // New order position
+}
+
+interface ColumnWidthEvent {
+    name: string;              // Column name
+    width: number;             // New width
+    oldWidth: number;          // Previous width
+}
+```
+
+#### Data Events
+
+| Event | Data Type | Description |
+|-------|-----------|-------------|
+| `addrows` | `AddRowsEvent` | Rows added |
+| `sort` | `SortEvent` | Data sorted |
+| `filter` | `unknown` | Filter applied (filter args) |
+| `filterclear` | `{}` | Filter cleared |
+
+```typescript
+interface AddRowsEvent {
+    count: number;             // Number of rows added
+    clear: boolean;            // Whether table was cleared first
+}
+
+interface SortEvent {
+    sorts: SerializedColumnSort[];  // Current sort state
+    resort?: boolean;          // True if re-sorting existing data
+}
+```
+
+#### Example Usage
+
+```typescript
+// Row click handler
+table.on('rowclick', (data) => {
+    console.log('Clicked row:', data.rowIndex, data.rowData);
+});
+
+// Column resize handler
+table.on('columnwidth', (data) => {
+    console.log(`Column ${data.name} resized from ${data.oldWidth} to ${data.width}`);
+});
+
+// Sort handler
+table.on('sort', (data) => {
+    console.log('Sorted by:', data.sorts);
+});
+
+// Cell preview handler
+table.on('cellpreview', (data) => {
+    // Customize preview content
+    if (data.el) {
+        data.el.innerHTML += '<span class="custom-badge">Preview</span>';
+    }
+});
+```
+
+---
+
+## TypeScript Types
+
+The library exports the following types for TypeScript users:
+
+```typescript
+import type {
+    // Configuration types
+    DGTableOptions,        // Constructor options
+    ColumnOptions,         // Column definition
+    ColumnSortOptions,     // Sort specification { column, descending? }
+    SerializedColumn,      // Saved column config
+    SerializedColumnSort,  // Saved sort config
+    RowData,               // Row data (Record<string, unknown>)
     
-    Permission is hereby granted, free of charge, to any person obtaining a copy
-    of this software and associated documentation files (the "Software"), to deal
-    in the Software without restriction, including without limitation the rights
-    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-    copies of the Software, and to permit persons to whom the Software is
-    furnished to do so, subject to the following conditions:
+    // Function types
+    CellFormatter,         // Cell formatter function
+    HeaderCellFormatter,   // Header cell formatter function
+    FilterFunction,        // Filter function
+    ComparatorFunction,    // Row comparator function
+    OnComparatorRequired,  // Comparator provider callback
+    CustomSortingProvider, // Custom sorting function
     
-    The above copyright notice and this permission notice shall be included in all
-    copies or substantial portions of the Software.
+    // Event types
+    RowCreateEvent,        // 'rowcreate' event data
+    RowClickEvent,         // 'rowclick' event data
+    CellPreviewEvent,      // 'cellpreview' event data
+    CellPreviewDestroyEvent, // 'cellpreviewdestroy' event data
+    HeaderContextMenuEvent, // 'headercontextmenu' event data
+    MoveColumnEvent,       // 'movecolumn' event data
+    ColumnWidthEvent,      // 'columnwidth' event data
+    AddRowsEvent,          // 'addrows' event data
+    SortEvent,             // 'sort' event data
     
-    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-    SOFTWARE.
+    // Event map (for advanced typing)
+    DGTableEventMap,       // Maps event names to their data types
+} from '@danielgindi/dgtable';
+```
+
+The `DGTableEventMap` interface provides full autocompletion when using `.on()`, `.once()`, `.off()`, and `.emit()`:
+
+```typescript
+// Event names autocomplete, and handler receives correctly typed data
+table.on('rowclick', (data) => {
+    // TypeScript knows: data.event, data.rowIndex, data.rowData, etc.
+    console.log(`Clicked row ${data.rowIndex}`);
+});
+
+table.on('columnwidth', (data) => {
+    // TypeScript knows: data.name, data.width, data.oldWidth
+    console.log(`Column ${data.name} resized to ${data.width}px`);
+});
+```
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Lint
+npm run lint
+```
+
+## Author
+
+**Daniel Cohen Gindi** - danielgindi@gmail.com
+
+## Contributing
+
+Contributions are welcome! Please feel free to:
+
+- Report bugs and issues
+- Submit pull requests
+- Improve documentation
+- Share your use cases
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+Copyright (c) 2013-present Daniel Cohen Gindi
+