@zvndev/yable-core

Headless, framework-agnostic data table engine. Zero dependencies.

@zvndev/yable-core is the foundation of the Yable table library. It handles all table logic -- sorting, filtering, pagination, editing, grouping, aggregation, pivot tables, tree data, formulas, clipboard, fill handle, undo/redo, and more -- without touching the DOM. Framework adapters like @zvndev/yable-react and @zvndev/yable-vanilla consume the core to produce UI.

Installation

npm install @zvndev/yable-core

Core Concepts

Table

The central object. Created via createTable(options), it holds all state and exposes methods for sorting, filtering, pagination, editing, selection, and more.

Column

Defined using createColumnHelper<T>() and its .accessor(), .display(), and .group() methods. Columns describe how data maps to cells, how to sort/filter, and how to render headers and footers.

Row

Represents a single data record. Rows provide access to cell values, selection state, expansion state, and pinning. Rows can have sub-rows for tree data.

Cell

The intersection of a row and a column. Cells provide typed value access, editing state, and render context.

Key Exports

Factory Functions

| Export | Description | |---|---| | createTable(options) | Create a table instance from data + column definitions | | createColumnHelper<T>() | Type-safe column definition builder | | createColumn(table, def, depth) | Create a column instance (internal) | | createRow(table, id, original, index, depth) | Create a row instance (internal) | | createHeader(table, column, options) | Create a header instance (internal) |

Built-in Functions

| Export | Description | |---|---| | sortingFns | 6 sorting comparators: alphanumeric, alphanumericCaseSensitive, text, textCaseSensitive, datetime, basic | | filterFns | 11 filter predicates: includesString, equalsString, arrIncludes, arrIncludesAll, arrIncludesSome, equals, weakEquals, inNumberRange, inDateRange, and case-sensitive variants | | aggregationFns | 9 aggregation functions: sum, min, max, extent, mean, median, unique, uniqueCount, count |

Utilities

| Export | Description | |---|---| | functionalUpdate(updater, old) | Apply an Updater<T> (value or function) to a previous value | | memo(deps, fn, opts) | Memoization helper with dependency tracking | | makeStateUpdater(key, table) | Create a state slice updater function |

Event System

| Export | Description | |---|---| | EventEmitterImpl | Typed event emitter with on, off, emit, removeAllListeners |

Basic Usage

import { createTable, createColumnHelper } from '@zvndev/yable-core'

interface Person {
  name: string
  age: number
  email: string
}

// Define columns
const columnHelper = createColumnHelper<Person>()
const columns = [
  columnHelper.accessor('name', { header: 'Name', enableSorting: true }),
  columnHelper.accessor('age', { header: 'Age', enableSorting: true }),
  columnHelper.accessor('email', { header: 'Email' }),
]

// Create data
const data: Person[] = [
  { name: 'Alice', age: 32, email: '[email protected]' },
  { name: 'Bob', age: 27, email: '[email protected]' },
]

// Create table
const table = createTable({
  data,
  columns,
  state: {
    sorting: [{ id: 'name', desc: false }],
  },
  onStateChange: (updater) => {
    // Handle state changes (wire to your framework's state management)
    console.log('State changed')
  },
})

// Read the row model
const rows = table.getRowModel().rows
rows.forEach((row) => {
  const cells = row.getVisibleCells()
  cells.forEach((cell) => {
    console.log(cell.column.id, cell.getValue())
  })
})

Row Model Pipeline

The core processes data through a pipeline of row models:

1. Core Row Model -- raw data[] converted to Row[]
2. Filtered Row Model -- column filters and global filter applied
3. Sorted Row Model -- sorting applied to filtered rows
4. Paginated Row Model -- page slice of sorted rows

Each stage is memoized. The final table.getRowModel() returns the paginated result.

Feature Overview

| Feature | Table Option | Column Option | |---|---|---| | Sorting | enableSorting, onSortingChange | enableSorting, sortingFn | | Filtering | enableFilters, onColumnFiltersChange, onGlobalFilterChange | enableColumnFilter, filterFn | | Pagination | manualPagination, onPaginationChange | -- | | Cell Editing | enableCellEditing, onEditCommit | editable, editConfig | | Column Pinning | enableColumnPinning | enablePinning | | Column Resizing | enableColumnResizing, columnResizeMode | enableResizing | | Row Selection | enableRowSelection, onRowSelectionChange | -- | | Row Expanding | enableExpanding, getSubRows | -- | | Grouping | enableGrouping, onGroupingChange | enableGrouping, aggregationFn | | Visibility | enableHiding | enableHiding | | Export | enableExport | -- |

See the full API Reference and Feature Documentation for details.

Types

All types are exported from the package entry point:

import type {
  Table,
  TableOptions,
  TableState,
  ColumnDef,
  Column,
  Row,
  Cell,
  Header,
  HeaderGroup,
  SortingState,
  ColumnFiltersState,
  PaginationState,
  RowSelectionState,
  EditingState,
  // ... and many more
} from '@zvndev/yable-core'

License

MIT