Core Types

Core Types

All types are exported from @witqq/spreadsheet.

import type { CellValue, CellData, CellStyle, ColumnDef, CellRange } from '@witqq/spreadsheet';

Cell Types

CellValue

type CellValue = string | number | boolean | Date | null;

CellData

interface CellData {
  readonly value: CellValue;
  readonly displayValue?: string;    // Override default formatting
  readonly formula?: string;         // Formula expression (e.g. "=SUM(A1:A10)")
  readonly style?: CellStyleRef;     // Reference to shared style
  readonly type?: CellType;          // Cell type for rendering
  readonly metadata?: CellMetadata;  // Status, links, comments
}

CellMetadata

interface CellMetadata {
  readonly status?: 'changed' | 'error' | 'saving' | 'saved';
  readonly errorMessage?: string;
  readonly link?: { url: string; label?: string };
  readonly comment?: string;
}

CellType

type CellType =
  | 'string' | 'number' | 'boolean' | 'date'
  | 'select' | 'dynamicSelect' | 'formula'
  | 'link' | 'image' | 'progressBar' | 'rating' | 'badge'
  | 'custom';

Style Types

CellStyle

interface CellStyle {
  readonly bgColor?: string;
  readonly textColor?: string;
  readonly fontFamily?: string;
  readonly fontSize?: number;
  readonly fontWeight?: 'normal' | 'bold';
  readonly fontStyle?: 'normal' | 'italic';
  readonly textAlign?: 'left' | 'center' | 'right';
  readonly verticalAlign?: 'top' | 'middle' | 'bottom';
  readonly borderTop?: BorderStyle;
  readonly borderRight?: BorderStyle;
  readonly borderBottom?: BorderStyle;
  readonly borderLeft?: BorderStyle;
  readonly numberFormat?: string;
  readonly textWrap?: boolean;
  readonly indent?: number;
}

BorderStyle

interface BorderStyle {
  readonly width: number;
  readonly color: string;
  readonly style: 'solid' | 'dashed' | 'dotted';
}

CellStyleRef

interface CellStyleRef {
  readonly ref: string;       // Unique key in StylePool
  readonly style: CellStyle;  // Resolved style object
}

Geometry Types

CellAddress

interface CellAddress {
  readonly row: number;
  readonly col: number;
}

CellRange

interface CellRange {
  readonly startRow: number;
  readonly startCol: number;
  readonly endRow: number;
  readonly endCol: number;
}

CellRect

Pixel-space rectangle for a cell on canvas:

interface CellRect {
  readonly x: number;
  readonly y: number;
  readonly width: number;
  readonly height: number;
}

Column Types

ColumnDef

interface ColumnDef {
  readonly key: string;          // Data binding key
  readonly title: string;        // Header display text
  readonly width: number;        // Width in pixels
  readonly minWidth?: number;    // Minimum resize width
  readonly maxWidth?: number;    // Maximum resize width
  readonly type?: CellType;      // Cell type for rendering
  readonly frozen?: boolean;     // Pin to frozen pane
  readonly sortable?: boolean;   // Enable header click sorting
  readonly filterable?: boolean; // Enable filter panel
  readonly editable?: boolean;   // Allow inline editing
  readonly resizable?: boolean;  // Allow drag-to-resize
  readonly hidden?: boolean;     // Hide from display and print
}

Selection Types

Selection

interface Selection {
  readonly type: SelectionType;
  readonly ranges: readonly CellRange[];
  readonly activeCell: CellAddress;
  readonly anchorCell: CellAddress;
}

type SelectionType = 'cell' | 'range' | 'row' | 'column' | 'all';

Merge Types

MergedRegion

interface MergedRegion {
  readonly startRow: number;
  readonly startCol: number;
  readonly endRow: number;    // inclusive
  readonly endCol: number;    // inclusive
}

Validation Types

ValidationRule

interface ValidationRule {
  readonly type: string;
  readonly message?: string;
  readonly severity?: 'error' | 'warning' | 'info';
}

ValidationResult

interface ValidationResult {
  readonly valid: boolean;
  readonly message?: string;
  readonly severity?: 'error' | 'warning' | 'info';
}

Theme Types

WitTheme

Theme controls all visual dimensions and colors. See Themes & Styling for details.

interface WitTheme {
  rowHeight: number;
  headerHeight: number;
  cellPadding: number;
  rowNumberWidth: number;
  colors: {
    background: string;
    cellText: string;
    cellBorder: string;
    headerBg: string;
    headerText: string;
    selectionBg: string;
    selectionBorder: string;
    // ... additional color tokens
  };
  fonts: {
    cell: string;
    header: string;
  };
}

Built-in themes: lightTheme, darkTheme.