API Reference

const {
  table,
  columns,
  rows,
  total,
  hasMore,
  isLoading,
  isRowsLoading,
  selectOptions,
  filters,
  sorts,
  setFilters,
  setSorts,
  updateCell,
  updateColumn,
  addColumn,
  deleteColumn,
  addRow,
  deleteRow,
  loadMore,
  loadSelectOptions,
  createSelectOption,
  updateSelectOption,
  deleteSelectOption,
} = useTable({ tableId: string });

<DataTableProvider
  dbAdapter={adapter}
  workspaceId="my-workspace"
  fileAdapter={fileAdapter}  // Optional
>
  {children}
</DataTableProvider>

<TableView
  columns={columns}
  rows={rows}
  selectOptions={selectOptions}
  onCellChange={(rowId, columnId, value) => {}}
  onAddRow={() => {}}
  onDeleteRow={(rowId) => {}}
  onColumnResize={(columnId, width) => {}}
  onColumnAlignmentChange={(columnId, alignment) => {}}
  onAddProperty={(name, type) => {}}
  onCreateSelectOption={(columnId, name, color) => {}}
  onUpdateSelectOption={(optionId, updates) => {}}
  onDeleteSelectOption={(columnId, optionId) => {}}
  enableKeyboardNav={true}
  sorts={sorts}
  onSortChange={(sorts) => {}}
  selectedRows={selectedRows}
  onSelectionChange={(selection) => {}}
  isLoading={isLoading}
  hasMore={hasMore}
  onLoadMore={() => {}}
  className=""
  style={{}}
/>

<FilterBar
  columns={columns}
  filters={filters}
  selectOptions={selectOptions}
  onFiltersChange={(filters) => {}}
/>

interface Column {
  id: string;
  tableId: string;
  name: string;
  type: ColumnType;
  position: number;
  width: number;
  isPrimary: boolean;
  config?: Record<string, unknown>;
}

type ColumnType =
  | 'text'
  | 'number'
  | 'date'
  | 'boolean'
  | 'select'
  | 'multi_select'
  | 'url'
  | 'file'
  | 'formula'
  | 'relation'
  | 'rollup';

interface Row {
  id: string;
  tableId: string;
  cells: Record<string, CellValue>;
}

type CellValue =
  | string
  | number
  | boolean
  | string[]  // multi_select
  | null;

interface SelectOption {
  id: string;
  columnId: string;
  name: string;
  color?: string;
  position: number;
}

interface QueryFilter {
  columnId: string;
  operator: FilterOperator;
  value: CellValue;
}

type FilterOperator =
  | 'equals'
  | 'notEquals'
  | 'contains'
  | 'notContains'
  | 'greaterThan'
  | 'lessThan'
  | 'isEmpty'
  | 'isNotEmpty';

interface QuerySort {
  columnId: string;
  direction: 'asc' | 'desc';
}

const {
  views,
  currentView,
  isLoading,
  error,
  createView,
  updateView,
  deleteView,
  reorderViews,
  setCurrentView,
  refresh,
} = useViews({ tableId: string });

<ViewSwitcher
  views={views}
  currentViewId={currentViewId}
  onViewChange={(viewId) => {}}
  onCreateView={(type) => {}}
  onDeleteView={(viewId) => {}}
  onRenameView={(viewId, name) => {}}
/>

<BoardView
  columns={columns}
  rows={rows}
  selectOptions={selectOptions}
  config={boardConfig}
  onCellChange={(rowId, columnId, value) => {}}
  onAddRow={(initialCells) => {}}
  onDeleteRow={(rowId) => {}}
  onCardClick={(rowId) => {}}
  onCreateSelectOption={(columnId, name, color) => {}}
  onUpdateSelectOption={(optionId, updates) => {}}
  onDeleteSelectOption={(columnId, optionId) => {}}
  onUploadFile={(rowId, columnId, file) => {}}
  onDeleteFile={(rowId, columnId, fileId) => {}}
  readOnly={false}
  isLoading={false}
  className=""
  style={{}}
/>

<CalendarView
  rows={rows}
  columns={columns}
  config={calendarConfig}
  onRowClick={(row) => {}}
  onDayClick={(date, events) => {}}
  onDateChange={(date) => {}}
  isLoading={false}
  className=""
  style={{}}
/>

<RelationCell
  value={relationValues}
  onChange={(values) => {}}
  config={relationConfig}
  readOnly={false}
  onSearchRows={(tableId, query) => {}}
  onGetRowTitle={(tableId, rowId) => {}}
/>

<RelationPicker
  targetTableId={tableId}
  selectedRowIds={selectedIds}
  onSelect={(rowId, displayValue) => {}}
  onDeselect={(rowId) => {}}
  onClose={() => {}}
  limitType="multiple"
  position={{ top: 100, left: 200 }}
  onSearchRows={(query) => {}}
/>

interface View {
  id: string;
  tableId: string;
  name: string;
  type: ViewType;
  isDefault: boolean;
  position: number;
  config: ViewConfig;
  createdAt: Date;
  updatedAt: Date;
}

type ViewType = 'table' | 'board' | 'calendar' | 'gallery' | 'timeline' | 'list';

interface ViewConfig {
  filters?: QueryFilter[];
  sorts?: QuerySort[];
  groupBy?: string; // columnId for grouping
  boardConfig?: BoardViewConfig;
  calendarConfig?: CalendarViewConfig;
  galleryConfig?: GalleryViewConfig;
  timelineConfig?: TimelineViewConfig;
  listConfig?: ListViewConfig;
}

interface BoardViewConfig {
  groupByColumnId: string;      // must be select/multi_select
  showEmptyGroups?: boolean;
  cardProperties?: string[];    // columnIds to show on cards
}

interface CalendarViewConfig {
  dateColumnId: string;
  endDateColumnId?: string;     // for date ranges
}

interface GalleryViewConfig {
  coverColumnId?: string;       // file column for cover image
  cardSize?: 'small' | 'medium' | 'large';
  cardProperties?: string[];    // columnIds to show on cards
}

interface TimelineViewConfig {
  startDateColumnId: string;
  endDateColumnId?: string;
  groupByColumnId?: string;
}

interface ListViewConfig {
  showCheckboxes?: boolean;
  indentColumnId?: string;      // for nested lists
}

interface CreateViewInput {
  tableId: string;
  name: string;
  type: ViewType;
  isDefault?: boolean;
  position?: number;
  config?: ViewConfig;
}

interface UpdateViewInput {
  name?: string;
  type?: ViewType;
  isDefault?: boolean;
  config?: ViewConfig;
}

interface Column {
  id: string;
  tableId: string;
  name: string;
  type: ColumnType;
  position: number;
  width: number;
  isPrimary: boolean;
  config?: ColumnConfig;
  createdAt: Date;
}

type ColumnType =
  | 'text'
  | 'number'
  | 'date'
  | 'boolean'
  | 'select'
  | 'multi_select'
  | 'url'
  | 'file'
  | 'formula'
  | 'relation'
  | 'rollup';

interface FormulaColumnConfig {
  formula: string;              // The formula expression
  resultType: 'text' | 'number' | 'date' | 'boolean';
}

interface RollupColumnConfig {
  relationColumnId: string;     // ID of the relation column to traverse
  targetColumnId: string;       // ID of the column to aggregate from related rows
  aggregation: RollupAggregation;
}

type RollupAggregation =
  | 'count'           // Count of related rows
  | 'sum'             // Sum of numeric values
  | 'average'         // Average of numeric values
  | 'min'             // Minimum value
  | 'max'             // Maximum value
  | 'countValues'     // Count of non-empty values
  | 'countUnique'     // Count of unique values
  | 'countEmpty'      // Count of empty values
  | 'countNotEmpty'   // Count of non-empty values (alias)
  | 'percentEmpty'    // Percentage of empty values (0-100)
  | 'percentNotEmpty' // Percentage of non-empty values (0-100)
  | 'showOriginal'    // Array of all values
  | 'showUnique';     // Array of unique values

interface RelationColumnConfig {
  targetTableId: string;        // ID of the table to link to
  bidirectional?: boolean;      // Create reverse relation automatically
  reverseColumnId?: string;     // ID of the reverse relation column
  limitType?: 'single' | 'multiple';  // Single or multiple row links
}

interface RelationValue {
  rowId: string;                // ID of the linked row
  displayValue?: string;        // Cached title for display
}

interface Row {
  id: string;
  tableId: string;
  cells: Record<string, CellValue>;
  computed?: Record<string, CellValue>; // Cached formula/rollup values
  archived: boolean;
  createdAt: Date;
  updatedAt: Date;
}

type CellValue =
  | string
  | number
  | boolean
  | Date
  | null
  | string[]           // For multi_select
  | FileReference[]    // For file columns
  | RelationValue[];   // For relation columns

interface SelectOption {
  id: string;
  columnId: string;
  name: string;
  color?: string;
  position: number;
}

interface QueryFilter {
  columnId: string;
  operator: FilterOperator;
  value: CellValue;
}

type FilterOperator =
  | 'equals'
  | 'notEquals'
  | 'contains'
  | 'notContains'
  | 'startsWith'
  | 'endsWith'
  | 'greaterThan'
  | 'greaterThanOrEquals'
  | 'lessThan'
  | 'lessThanOrEquals'
  | 'isEmpty'
  | 'isNotEmpty'
  | 'isIn'
  | 'isNotIn';

interface QuerySort {
  columnId: string;
  direction: 'asc' | 'desc';
}

interface DatabaseAdapter {
  // Tables
  createTable(input: CreateTableInput): Promise<Table>;
  getTable(tableId: string): Promise<Table | null>;
  updateTable(tableId: string, updates: UpdateTableInput): Promise<Table>;
  deleteTable(tableId: string): Promise<void>;
  listTables(workspaceId: string): Promise<Table[]>;

  // Columns
  createColumn(input: CreateColumnInput): Promise<Column>;
  getColumns(tableId: string): Promise<Column[]>;
  getColumn(columnId: string): Promise<Column | null>;
  updateColumn(columnId: string, updates: UpdateColumnInput): Promise<Column>;
  deleteColumn(columnId: string): Promise<void>;
  reorderColumns(tableId: string, columnIds: string[]): Promise<void>;

  // Select Options
  createSelectOption(input: CreateSelectOptionInput): Promise<SelectOption>;
  getSelectOptions(columnId: string): Promise<SelectOption[]>;
  updateSelectOption(optionId: string, updates: UpdateSelectOptionInput): Promise<SelectOption>;
  deleteSelectOption(optionId: string): Promise<void>;
  reorderSelectOptions(columnId: string, optionIds: string[]): Promise<void>;

  // Rows
  createRow(input: CreateRowInput): Promise<Row>;
  getRow(rowId: string): Promise<Row | null>;
  getRows(tableId: string, query?: QueryOptions): Promise<QueryResult<Row>>;
  updateRow(rowId: string, cells: Record<string, CellValue>): Promise<Row>;
  deleteRow(rowId: string): Promise<void>;
  archiveRow(rowId: string): Promise<void>;
  unarchiveRow(rowId: string): Promise<void>;
  bulkCreateRows(inputs: CreateRowInput[]): Promise<Row[]>;
  bulkDeleteRows(rowIds: string[]): Promise<void>;
  bulkArchiveRows(rowIds: string[]): Promise<void>;

  // Relations
  createRelation(input: CreateRelationInput): Promise<void>;
  deleteRelation(sourceRowId: string, columnId: string, targetRowId: string): Promise<void>;
  getRelatedRows(rowId: string, columnId: string): Promise<Row[]>;
  getRelationsForRow(rowId: string): Promise<Array<{ columnId: string; targetRowId: string }>>;

  // File References
  addFileReference(input: CreateFileRefInput): Promise<FileReference>;
  removeFileReference(fileRefId: string): Promise<void>;
  getFileReferences(rowId: string, columnId: string): Promise<FileReference[]>;
  reorderFileReferences(rowId: string, columnId: string, fileRefIds: string[]): Promise<void>;

  // Views
  createView(input: CreateViewInput): Promise<View>;
  getViews(tableId: string): Promise<View[]>;
  getView(viewId: string): Promise<View | null>;
  updateView(viewId: string, updates: UpdateViewInput): Promise<View>;
  deleteView(viewId: string): Promise<void>;
  reorderViews(tableId: string, viewIds: string[]): Promise<void>;

  // Transactions
  transaction<T>(fn: (tx: DatabaseAdapter) => Promise<T>): Promise<T>;
}

createView(input: CreateViewInput): Promise<View>

getViews(tableId: string): Promise<View[]>

getView(viewId: string): Promise<View | null>

updateView(viewId: string, updates: UpdateViewInput): Promise<View>

deleteView(viewId: string): Promise<void>

reorderViews(tableId: string, viewIds: string[]): Promise<void>

import { FormulaEngine } from '@marlinjai/data-table-core';

const engine = new FormulaEngine(options?: FormulaEngineOptions);

interface FormulaEngineOptions {
  throwOnError?: boolean;       // Throw errors instead of returning null
  maxDepth?: number;            // Maximum recursion depth (default: 100)
  customFunctions?: Record<string, (...args: FormulaValue[]) => FormulaValue>;
}

engine.evaluate(formula: string, row: Row, columns: Column[]): CellValue

// Simple arithmetic with property references
engine.evaluate('prop("Price") * prop("Quantity")', row, columns);
// Returns: 150 (if Price=10, Quantity=15)

// String concatenation
engine.evaluate('concat(prop("First Name"), " ", prop("Last Name"))', row, columns);
// Returns: "John Doe"

// Conditional logic
engine.evaluate('if(prop("Status") == "Complete", "Done", "In Progress")', row, columns);
// Returns: "Done" or "In Progress"

// Math functions
engine.evaluate('round(prop("Price") * 1.08, 2)', row, columns);
// Returns: 10.80

engine.evaluateWithResult(formula: string, row: Row, columns: Column[]): FormulaResult

interface FormulaResult {
  value: CellValue;
  error?: string;
}

engine.validate(formula: string): { isValid: boolean; error?: string }

engine.getAST(formula: string): ASTNode

engine.addFunctions(functions: Record<string, (...args: FormulaValue[]) => FormulaValue>): void

engine.clearCache(): void

import { FormulaParser } from '@marlinjai/data-table-core';

const parser = new FormulaParser();
const ast = parser.parse(formula: string): ASTNode;

type ASTNode =
  | NumberLiteral       // e.g., 42, 3.14
  | StringLiteral       // e.g., "hello"
  | BooleanLiteral      // true, false
  | PropertyReference   // prop("Column Name")
  | BinaryExpression    // a + b, x == y
  | UnaryExpression     // not x, -5
  | FunctionCall        // concat("a", "b")
  | ConditionalExpression;  // condition ? true : false

class FormulaParseError extends Error {
  position: number;  // Position in the formula where error occurred
}

import { RollupEngine } from '@marlinjai/data-table-core';

const engine = new RollupEngine();

engine.calculate(
  config: RollupColumnConfig,
  relatedRows: Row[],
  targetColumn: Column
): RollupResult

type RollupResult = number | CellValue[] | null;

const engine = new RollupEngine();

// Sum prices from related line items
const total = engine.calculate(
  { relationColumnId: 'items', targetColumnId: 'price', aggregation: 'sum' },
  lineItemRows,
  priceColumn
);
// Returns: 250.00

// Count related tasks
const taskCount = engine.calculate(
  { relationColumnId: 'tasks', targetColumnId: 'id', aggregation: 'count' },
  taskRows,
  idColumn
);
// Returns: 5

// Get unique categories
const categories = engine.calculate(
  { relationColumnId: 'products', targetColumnId: 'category', aggregation: 'showUnique' },
  productRows,
  categoryColumn
);
// Returns: ['Electronics', 'Books', 'Clothing']

// Calculate completion percentage
const percentComplete = engine.calculate(
  { relationColumnId: 'tasks', targetColumnId: 'completed', aggregation: 'percentNotEmpty' },
  taskRows,
  completedColumn
);
// Returns: 80 (80% of tasks are completed)