HighTable

!HighTable

!coverage

HighTable is a virtualized table component for React, designed to efficiently display large datasets in the browser. It loads and renders only the rows necessary for the current viewport, enabling smooth scrolling and performance even with millions of rows. HighTable supports asynchronous data fetching, dynamic loading, and optional column sorting.

Features

- Virtualized Scrolling: Efficiently renders only the visible rows, optimizing performance for large datasets.
- Asynchronous Data Loading: Fetches data on-demand as the user scrolls, supporting datasets of any size.
- Column Sorting: Optional support for sorting data by columns.
- Column Resizing: Allows for resizing columns to fit the available space and auto-sizing.
- Row Selection: Supports selecting multiple rows using shift+click.
- Event Handling: Supports double-click events on cells.
- Loading Placeholder: Displays animated loading indicator per-cell.

Demo

Live table demo: https://hyparam.github.io/demos/hightable/. See the source code.

Installation

Ensure you have React set up in your project. Install the HighTable package via npm:

``sh
npm i hightable
`

Data Model

HighTable uses a data model called DataFrame, which defines how data is fetched and structured. The DataFrame object should have the following properties:

- columnDescriptors: An array of objects representing the column name, if it is sortable, and any metadata.
- numRows: The total number of rows in the dataset. It can be implemented as a getter and a setter that triggers a numrowschange event when it changes.
- getRowNumber: A function that returns the row number for a given row index. If not resolved yet, it returns undefined.
- getCell: A function that returns the value of a cell at a specific row and column. If not resolved yet, it returns undefined.
- eventTarget: An optional event target which must dispatch the event resolve when a cell or row number is resolved, numrowschange when the number of rows changes, and update when the content changes. This can be used to trigger re-renders or other side effects.
- fetch: An optional asynchronous function that fetches cells and row numbers, for a range of rows and columns. It should only fetch the missing data, and once the data is fetched, getRowNumber and getCell should return the resolved values (or the updated values, if applicable). It is responsible for dispatching the resolve event (once or multiple times) on the eventTarget when the data is ready.

Usage

Here's a basic example of how to use HighTable in your React application:

`jsx
import HighTable from 'hightable'

const eventTarget = new EventTarget()
const cache = new Map()
const store = (cells) => {
for (const [col, values] of Object.entries(cells)) {
if (!cache.has(col)) cache.set(col, new Map())
for (const [row, value] of Object.entries(values)) {
cache.get(col).set(Number(row), ({value}))
}
}
}
const dataframe = {
columnDescriptors: [{name: 'ID'}, {name: 'Name'}, {name: 'Email'}],
numRows: 1000000,
getRowNumber: ({ row }) => ({ value: rowIndex }),
getCell: ({ row, col }) => cache.get(col).get(row),
eventTarget,
async fetch({row, column}) {
// fetch cell data from your data source here
const cells = await fetchCellData(row, col)
// store the fetched data in the cache
store(cells)
// dispatch the resolve event to notify the table that the data is ready
eventTarget.dispatchEvent(new CustomEvent('resolve'))
}
}

function App() {
return (
data={dataframe}
onError={console.error}
/>
)
}
`

Props

HighTable accepts the following props:

`typescript
interface TableProps {
data: DataFrame // data provider for the table
cacheKey?: string // used to persist column widths. If undefined, the column widths are not persisted. It is expected to be unique for each table.
className?: string // additional class name for the table container
columnConfiguration?: Record // allows for additional configuration of columns
focus?: boolean // focus table on mount? (default true)
maxRowNumber?: number // maximum row number to display (for row headers). Useful for filtered data. If undefined, the number of rows in the data frame is applied.
orderBy?: OrderBy // order by column (if defined, the component order is controlled by the parent)
overscan?: number // number of rows to fetch beyond the visible table cells (default 20)
padding?: number // number of rows to render beyond the visible table cells (default 20)
numRowsPerPage?: number // number of rows per page for keyboard navigation (default 20)
selection?: Selection // selection state (if defined, the component selection is controlled by the parent)
styled?: boolean // use styled component? (default true)
onColumnsVisibilityChange?: (columnVisibilityStates: Record) => void // columns visibility change handler
onDoubleClickCell?: (event: MouseEvent, col: number, row: number) => void // double-click handler
onError?: (error: Error) => void // error handler
onKeyDownCell?: (event: KeyboardEvent, col: number, row: number) => void // key down handler. For accessibility, it should be passed if onDoubleClickCell is passed.
onMouseDownCell?: (event: MouseEvent, col: number, row: number) => void // mouse down handler
onOrderByChange?: (orderBy: OrderBy) => void // orderBy change handler
onSelectionChange?: (selection: Selection) => void // selection change handler
renderCellContent?: (props: CellContentProps) => ReactNode // custom cell content component, if not provided, the default CellContent will be used
stringify?: (value: unknown) => string | undefined // function to convert cell values to strings for display
}
`

DataFrame is defined as:

`typescript
interface DataFrame, C extends Record> {
columnDescriptors: ColumnDescriptor[]
numRows: number
metadata?: M // optional metadata for the DataFrame - use the generic type for increased type safety
// rows are 0-indexed, excludes the header, end is exclusive
// if orderBy is defined, start and end are applied on the sorted rows
getRowNumber({ row, orderBy }: { row: number, orderBy?: OrderBy }): ResolvedValue | undefined
getCell({ row, column, orderBy }: {row: number, column: string, orderBy?: OrderBy}): ResolvedValue | undefined
fetch?: ({ rowStart, rowEnd, columns, orderBy, signal }: { rowStart: number, rowEnd: number, columns?: string[], orderBy?: OrderBy, signal?: AbortSignal }) => Promise
eventTarget?: EventTarget
}
`

ColumnDescriptor is defined as:

`typescript
interface ColumnDescriptor> {
name: string // column name
sortable?: boolean // is the column sortable? Defaults to false
metadata?: C // custom metadata extendable by the user
}
`

ResolvedValue is defined as:

`typescript
type ResolvedValue = {
value: T // resolved value
}
`

OrderBy is defined as:

`typescript
interface OrderBy {
column: string // column name
direction?: "ascending" // sort direction - only ascending is supported
}
`

Selection is defined as:

`typescript
interface Selection {
ranges: Array<{
start: number // inclusive lower limit, positive integer
end: number // exclusive upper limit, positive integer, strictly greater than start (no zero-length ranges).
}> // the rows selection is an array of row index ranges (0-based). The values are indexes of the virtual table (sorted rows), and thus depend on the order.
anchor?: number // anchor row used as a reference for shift+click selection. It's a virtual table index (sorted), and thus depends on the order.
}
`

ColumnConfig is defined as:

`typescript
interface ColumnConfig {
headerComponent?: React.ReactNode // allows overriding column header cell with custom component
minWidth?: number // overrides the global column min width, useful for components with ui elements
initiallyHidden?: boolean // whether the column should be initially hidden
className?: string // additional CSS class name for the header and cells of this column
}
`

Array to DataFrame

HighTable includes a helper function to convert an array of objects to a DataFrame object. The function accepts an array of objects and assume that all the objects share the same keys. The dataframe is not sortable, see sortableDataFrame for that.

`javascript
import { arrayDataFrame } from 'hightable'
const data = [
{ id: 1, name: 'Alice' },
{ id: 2, name: 'Bob' },
]
const dataframe = arrayDataFrame(data)
`

Dataframe Utilities (Node.js)

For using dataframe utilities in Node.js or environments without React, import from the hightable/dataframe subpath:

`javascript
import {
arrayDataFrame,
sortableDataFrame,
createEventTarget,
computeRanks,
stringify,
// ... other utilities
} from 'hightable/dataframe'
`

Available exports include:
- arrayDataFrame, sortableDataFrame - DataFrame implementations
- createEventTarget, TypedCustomEvent - Event handling utilities
- computeRanks, serializeOrderBy, deserializeOrderBy - Sort utilities
- stringify - Value stringification
- Validation helpers: checkSignal, validateColumn, validateRow, etc.
- Legacy utilities: resolvablePromise, wrapPromise, asyncRows, etc.

Sortable DataFrame

If your data source supports sorting, set the sortable property to true in your DataFrame object. When sorting is enabled, the rows function will receive an additional orderBy parameter, which represents the column name to sort by.

Ensure your rows function handles the orderBy parameter appropriately to return sorted data.

HighTable includes a helper function to transform a dataframe to a sorted dataframe:

`javascript
import { sortedDataFrame } from 'hightable'
const sortableDf = sortableDataFrame(df)
`

Styling

HighTable includes basic CSS styling to make the table functional. You can customize the appearance of the table using CSS.

Structure of the code

The code is structured as follows:

- src/: Source code
- components/: React components
- helpers/: Helper functions, specific for HighTable
- hooks/: Custom hooks
- utils/: Generic utility functions
- test/: Unit tests (follows the same structure as src/`)