@worksheet-js/core 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,1961 @@
+import { SheetData as SheetData$1, CsvOptions, JsonOptions, HtmlOptions } from '@worksheet-js/excel';
+export { AnchorMarker, AutoFilterData, CellData, CellType, ConditionalFormattingData, CsvOptions, DataValidationData, HtmlOptions, HyperlinkData, ImageData, JsonOptions, MergeData, ParsedStyle, ParserError, ParserResult, SheetData, WorkbookData, excelDateToJSDate, isDateFormat, parseCsv, parseHtml, parseJson, parseTsv } from '@worksheet-js/excel';
+import { FormulaEngine } from '@worksheet-js/formula';
+
+type CellType = 'string' | 'number' | 'boolean' | 'date' | 'error';
+/** Visual style properties for a cell — mirrors Google Sheets toolbar options */
+interface CellStyle {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    fontFamily?: string;
+    fontSize?: number;
+    color?: string;
+    fillColor?: string;
+    align?: 'left' | 'center' | 'right';
+    valign?: 'top' | 'middle' | 'bottom';
+    wrap?: 'overflow' | 'wrap' | 'clip';
+    rotation?: number;
+    numberFormat?: 'auto' | 'text' | 'number' | 'currency' | 'currency_rounded' | 'percent' | 'scientific' | 'accounting' | 'financial' | 'date' | 'time' | 'datetime' | 'duration';
+    decimals?: number;
+    borderTop?: boolean;
+    borderBottom?: boolean;
+    borderLeft?: boolean;
+    borderRight?: boolean;
+    borderWeight?: number;
+    borderStyle?: string;
+    borderColor?: string;
+    link?: string;
+    currencyCode?: string;
+    direction?: 'ltr' | 'rtl';
+    borderTopColor?: string;
+    borderTopStyle?: string;
+    borderTopWeight?: number;
+    borderBottomColor?: string;
+    borderBottomStyle?: string;
+    borderBottomWeight?: number;
+    borderLeftColor?: string;
+    borderLeftStyle?: string;
+    borderLeftWeight?: number;
+    borderRightColor?: string;
+    borderRightStyle?: string;
+    borderRightWeight?: number;
+}
+interface CommentReply {
+    id: string;
+    author: string;
+    text: string;
+    timestamp: Date;
+}
+interface CommentThread {
+    id: string;
+    author: string;
+    text: string;
+    timestamp: Date;
+    resolved: boolean;
+    replies: CommentReply[];
+}
+interface CellData {
+    value: string;
+    parsedValue: unknown;
+    type: CellType;
+    format?: string;
+    style?: CellStyle;
+    note?: string;
+    comments?: CommentThread[];
+}
+
+declare class CellEditor {
+    private ws;
+    element: HTMLTextAreaElement;
+    isOpen: boolean;
+    isComposing: boolean;
+    private _x;
+    private _y;
+    private _isFormula;
+    private _originalValue;
+    private _ghost;
+    constructor(ws: WorksheetModel);
+    /**
+     * Open the editor on cell (x, y), optionally prefilling with a char.
+     */
+    open(x: number, y: number, initialChar?: string, options?: {
+        preventFocus?: boolean;
+    }): void;
+    /**
+     * Close the editor, optionally saving the value.
+     */
+    close(save: boolean): void;
+    /** Get current editor value */
+    getValue(): string;
+    /** Insert text at current cursor position */
+    insertAtCursor(text: string): void;
+    private _position;
+    private _resize;
+    private _syncFormulaBar;
+    private _cycleRefAtCursor;
+}
+
+/** Zero-based column (x) and row (y) coordinates */
+interface CellAddress {
+    x: number;
+    y: number;
+}
+/** Selection range using inclusive corner coordinates (matches jspreadsheet coords convention) */
+interface SelectionRange {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+/** Sheet tab metadata */
+interface SheetMeta {
+    worksheetName: string;
+    tabColor?: string;
+    hidden?: boolean;
+    minDimensions?: [number, number];
+    defaultColWidth?: number;
+    defaultRowHeight?: number;
+    minColWidth?: number;
+    minRowHeight?: number;
+    hiddenColumns?: number[];
+    hiddenRows?: number[];
+    frozenRows?: number;
+    frozenCols?: number;
+    direction?: 'ltr' | 'rtl';
+}
+/** Base type for extensible sheet overlays (images, charts, widgets) */
+interface OverlayItem {
+    id: string;
+    type: string;
+    x: number;
+    y: number;
+    w?: number;
+    h?: number;
+    data: any;
+}
+/** A single style snapshot for one cell in a batch */
+interface CellStyleSnapshot {
+    x: number;
+    y: number;
+    before: unknown;
+    after: unknown;
+}
+/**
+ * A single history entry — discriminated union so each type carries precise before/after types.
+ * This enables TypeScript to narrow types in _applyHistory without casts.
+ */
+type HistoryEntry = {
+    type: 'value';
+    x: number;
+    y: number;
+    before: string;
+    after: string;
+} | {
+    type: 'style';
+    x: number;
+    y: number;
+    before: unknown;
+    after: unknown;
+} | {
+    type: 'style-batch';
+    x?: never;
+    y?: never;
+    before: null;
+    after: null;
+    cells: CellStyleSnapshot[];
+} | {
+    type: 'width';
+    x: number;
+    y?: never;
+    before: number;
+    after: number;
+} | {
+    type: 'height';
+    x?: never;
+    y: number;
+    before: number;
+    after: number;
+} | {
+    type: 'insert-row';
+    x?: never;
+    y: number;
+    before: null;
+    after: number;
+} | {
+    type: 'delete-row';
+    x?: never;
+    y: number;
+    before: null;
+    after: number;
+} | {
+    type: 'insert-col';
+    x: number;
+    y?: never;
+    before: null;
+    after: number;
+} | {
+    type: 'delete-col';
+    x: number;
+    y?: never;
+    before: null;
+    after: number;
+} | {
+    type: 'merge';
+    x?: never;
+    y?: never;
+    before: null;
+    after: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    };
+} | {
+    /** Multiple value changes as a single undoable action (e.g. clear selection, fill down) */
+    type: 'value-batch';
+    x?: never;
+    y?: never;
+    before: null;
+    after: null;
+    cells: Array<{
+        x: number;
+        y: number;
+        before: string;
+        after: string;
+    }>;
+} | {
+    /**
+     * Copy/cut+paste — carries full cell state (value + style) before and after.
+     * Undo restores all destination cells to their pre-paste state.
+     * For cut, also restores source cells.
+     */
+    type: 'paste-batch';
+    x?: never;
+    y?: never;
+    before: null;
+    after: null;
+    cells: Array<{
+        x: number;
+        y: number;
+        beforeValue: string;
+        afterValue: string;
+        beforeStyle: CellStyle | undefined;
+        afterStyle: CellStyle | undefined;
+        beforeOverlay: any | undefined;
+        afterOverlay: any | undefined;
+    }>;
+} | {
+    type: 'overlay';
+    x: number;
+    y: number;
+    before: any | undefined;
+    after: any | undefined;
+};
+/** Custom color overrides */
+interface ThemeColors {
+    primary?: string;
+    accent?: string;
+    headerBg?: string;
+    headerText?: string;
+    cellBg?: string;
+    cellText?: string;
+    toolbarBg?: string;
+    gridBorder?: string;
+}
+/** Custom font overrides */
+interface ThemeFonts {
+    ui?: string;
+    cell?: string;
+}
+type OnLoadCallback = (spreadsheet: Spreadsheet) => void;
+type OnSelectionCallback = (worksheet: WorksheetModel, x1: number, y1: number, x2: number, y2: number) => void;
+type OnChangeCallback = (worksheet: WorksheetModel, cell: HTMLElement | null, x: number, y: number, value: string, oldValue: string) => void;
+type OnCreateWorksheetCallback = (worksheet: WorksheetModel, index: number) => void;
+type OnDestroyCallback = () => void;
+/** Main options passed to Worksheet.create() */
+interface WorksheetOptions {
+    /** Container element to mount the spreadsheet into */
+    container: HTMLElement;
+    /** One or more worksheet configs (default: one sheet named "Sheet1") */
+    worksheets?: SheetMeta[];
+    /** Global default column width in px (default: 100) */
+    defaultColWidth?: number;
+    /** Global default row height in px (default: 24) */
+    defaultRowHeight?: number;
+    /** Maximum number of worksheets allowed (default: 200) */
+    maxSheets?: number;
+    /** Show sheet tab bar (default: true) */
+    tabs?: boolean;
+    /** Show ribbon toolbar (default: true) */
+    toolbar?: boolean;
+    /** Show formula bar (default: true) */
+    formulaBar?: boolean;
+    /** Frozen rows count (default: 0) */
+    frozenRows?: number;
+    /** Frozen columns count (default: 0) */
+    frozenCols?: number;
+    /** Color theme (default: 'light') */
+    theme?: 'light' | 'dark';
+    /** Custom color overrides */
+    colors?: ThemeColors;
+    /** Custom font overrides */
+    fonts?: ThemeFonts;
+    /**
+     * Spreadsheet-wide default font name (display name from the font registry, e.g. "Roboto").
+     * Applies to UI labels (toolbar, tabs, formula bar) and blank cell rendering.
+     * Typing a font name here is equivalent to calling setDefaultFont() after creation.
+     */
+    defaultFont?: string;
+    /** Zoom level 10–400 (default: 100) */
+    zoom?: number;
+    /** Locale for number formatting (default: navigator.language) */
+    locale?: string;
+    /** Encoded and signed license key string */
+    licenseKey?: string;
+    /** Custom watermark text for Enterprise edition */
+    watermark?: string;
+    onload?: OnLoadCallback;
+    onselection?: OnSelectionCallback;
+    onchange?: OnChangeCallback;
+    oncreateworksheet?: OnCreateWorksheetCallback;
+    ondestroy?: OnDestroyCallback;
+}
+
+type SelectionMode = 'normal' | 'row' | 'col' | 'all';
+type EnterDirection = 'down' | 'up' | 'right' | 'left';
+/**
+ * SelectionModel — full selection state with anchor/focus distinction.
+ * The anchor is where dragging/shift-extending started.
+ * The focus is where the keyboard/mouse currently points.
+ * Derived x1,y1,x2,y2 = bounding box of anchor + focus.
+ */
+declare class SelectionModel {
+    anchorX: number;
+    anchorY: number;
+    focusX: number;
+    focusY: number;
+    mode: SelectionMode;
+    copyRange: SelectionRange | null;
+    isCut: boolean;
+    enterDirection: EnterDirection;
+    tabOriginX: number;
+    /**
+     * Set anchor = focus = (x, y). Used on plain click or single-cell move.
+     */
+    setAnchor(x: number, y: number): void;
+    /**
+     * Extend focus to (x, y) keeping anchor fixed.
+     * Used on shift+click, shift+arrow, mousemove during drag.
+     */
+    extendFocus(x: number, y: number): void;
+    /**
+     * Get the bounding SelectionRange (always normalized: x1 ≤ x2, y1 ≤ y2).
+     */
+    getRange(): SelectionRange;
+    /**
+     * The display cell — top-left of bounding box (matches what NameBox shows).
+     */
+    getDisplayCell(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Move anchor+focus by (dx, dy). Clamps to [0, maxCol/maxRow].
+     */
+    move(dx: number, dy: number, maxCol: number, maxRow: number): void;
+    /**
+     * Extend focus by (dx, dy) keeping anchor fixed.
+     */
+    extend(dx: number, dy: number, maxCol: number, maxRow: number): void;
+    /**
+     * Select full row y.
+     */
+    selectRow(y: number, maxCol: number): void;
+    /**
+     * Extend row selection to row y (keeping anchor row).
+     */
+    extendRowTo(y: number, maxCol: number): void;
+    /**
+     * Select full column x.
+     */
+    selectCol(x: number, maxRow: number): void;
+    /**
+     * Extend column selection to col x.
+     */
+    extendColTo(x: number, maxRow: number): void;
+    /**
+     * Select all cells.
+     */
+    selectAll(maxCol: number, maxRow: number): void;
+    /**
+     * Set the copy range and start "marching ants" mode.
+     */
+    setCopyRange(range: SelectionRange, isCut?: boolean): void;
+    /**
+     * Clear copy range (escape or after paste).
+     */
+    clearCopyRange(): void;
+    isSingleCell(): boolean;
+    contains(x: number, y: number): boolean;
+}
+
+/**
+ * SelectionPainter — applies/removes CSS classes to reflect the current selection.
+ * Manages the floating selection border overlay and fill handle (corner) position.
+ */
+declare class SelectionPainter {
+    private ws;
+    private borderEl;
+    private highlighted;
+    private selectedHeaders;
+    constructor(ws: WorksheetModel);
+    /** Apply selection classes and position the border + fill handle */
+    paint(x1: number, y1: number, x2: number, y2: number): void;
+    /** Remove all selection highlight classes */
+    clear(): void;
+}
+
+/**
+ * SelectionState — stores the current selection rectangle.
+ * Uses same {x1,y1,x2,y2} coords convention as jSpreadsheet CE.
+ */
+declare class SelectionState {
+    private x1;
+    private y1;
+    private x2;
+    private y2;
+    set(x1: number, y1: number, x2: number, y2: number): void;
+    getRange(): SelectionRange;
+    getAnchor(): {
+        x: number;
+        y: number;
+    };
+    contains(x: number, y: number): boolean;
+    isAnchor(x: number, y: number): boolean;
+    isSingleCell(): boolean;
+}
+
+/**
+ * OverlayRegistry — a thin container for sheet widgets (images, charts, etc.).
+ * Designed to be extensible: adding a new widget type doesn't require changing this class.
+ */
+declare class OverlayRegistry {
+    private items;
+    add(item: OverlayItem): void;
+    remove(id: string): void;
+    getAll(): OverlayItem[];
+    getAt(x: number, y: number): OverlayItem[];
+    clear(): void;
+    /** Deep-clone all items from another registry. */
+    copyFrom(source: OverlayRegistry): void;
+}
+
+type CFOperator = 'cell_empty' | 'cell_not_empty' | 'text_contains' | 'text_not_contains' | 'text_starts' | 'text_ends' | 'text_is' | 'date_is' | 'date_before' | 'date_after' | 'num_greater' | 'num_greater_equal' | 'num_less' | 'num_less_equal' | 'num_equal' | 'num_not_equal' | 'num_between' | 'num_not_between' | 'custom_formula';
+interface CFRule {
+    ranges: SelectionRange[];
+    operator: CFOperator;
+    value1?: string;
+    value2?: string;
+    style: Partial<CellStyle>;
+}
+/**
+ * ConditionalFormattingManager — Handles rule storage and evaluation.
+ */
+declare class ConditionalFormattingManager {
+    private rules;
+    constructor();
+    getRules(): CFRule[];
+    addRule(rule: CFRule): void;
+    updateRule(index: number, rule: CFRule): void;
+    removeRule(index: number): void;
+    moveRule(from: number, to: number): void;
+    evaluate(x: number, y: number, value: unknown): Partial<CellStyle>;
+    private _isCellInRange;
+    private _checkRule;
+    clearRules(): void;
+}
+
+type ConditionType = 'none' | 'is_empty' | 'is_not_empty' | 'text_contains' | 'text_not_contains' | 'text_starts_with' | 'text_ends_with' | 'text_exactly' | 'text_not_exactly' | 'text_is_email' | 'text_is_url' | 'eq' | 'not_eq' | 'greater_than' | 'less_than' | 'greater_equal' | 'less_equal' | 'between' | 'num_not_between' | 'date_is' | 'date_before' | 'date_after' | 'date_on_or_before' | 'date_on_or_after' | 'date_between' | 'date_not_between' | 'date_is_valid';
+interface ColumnFilter {
+    /** If defined: only show rows whose value is in this set. */
+    valueSet?: Set<string>;
+    /** If defined and type !== 'none': also apply this condition. */
+    condition?: {
+        type: ConditionType;
+        value: string;
+        value2?: string;
+    };
+}
+declare class FilterState {
+    /** Set of columns that have filtering UI enabled via icon. */
+    enabledColumns: Set<number>;
+    /** Per-column active filter rules (0-indexed column). */
+    filters: Map<number, ColumnFilter>;
+    /** True if column `col` has a non-trivial active filter. */
+    isColumnFiltered(col: number): boolean;
+    /** True if any column has an active filter. */
+    get anyFiltered(): boolean;
+    /**
+     * Returns true if the given row should be VISIBLE (passes all active filters).
+     * Row 0 (header) always returns true.
+     */
+    rowPassesFilters(ws: WorksheetModel, row: number): boolean;
+    /**
+     * Set the filter for a column. Pass `null` to clear that column's filter.
+     */
+    setColumnFilter(col: number, filter: ColumnFilter | null): void;
+    /** Remove all active filters (but keep `hasFilter = true` so buttons remain). */
+    clearFilters(): void;
+    /** fully disable filtering for a specific column or all columns. */
+    disable(col?: number): void;
+    enableFilters(col?: number): void;
+    /** Deep-clone another FilterState instance. */
+    copyFrom(source: FilterState): void;
+}
+
+/**
+ * Viewport — High-performance grid virtualization engine.
+ *
+ * Instead of creating 100,000 DOM nodes, it creates a small pool of `<div class="worksheet-cell">`
+ * and recycles them as the user scrolls. The cells are absolutely positioned.
+ */
+declare class Viewport {
+    private ws;
+    private container;
+    private ghost;
+    private viewLayer;
+    private selectAllBlock;
+    private colContainer;
+    private rowContainer;
+    private poolSize;
+    private cells;
+    private rowHeaders;
+    private colHeaders;
+    private contentWidth;
+    private overscan;
+    private startCol;
+    private endCol;
+    private startRow;
+    private endRow;
+    private _measurer;
+    constructor(ws: WorksheetModel, container: HTMLElement);
+    /** Returns the view layer element for external consumers (e.g., SelectionPainter). */
+    getViewLayer(): HTMLElement;
+    private _linkTooltip;
+    private _linkTooltipTimer;
+    private _bindLinkTooltip;
+    private _showLinkTooltip;
+    private _hideLinkTooltip;
+    private isResizing;
+    private resizeAxis;
+    private resizeIndex;
+    private resizeStartPos;
+    private resizeStartSize;
+    private resizeLine;
+    private _boundResizeMove;
+    private _boundResizeUp;
+    private _bindResizeHandlers;
+    private _startResize;
+    /**
+     * Called by TableBuilder after seeding the initial DOM pool.
+     */
+    initPool(cells: HTMLElement[], rowHeaders: HTMLElement[], colHeaders: HTMLElement[], colContainer: HTMLElement, rowContainer: HTMLElement): void;
+    /**
+     * Compute cumulative pixel offsets to find which rows/cols are visible based on scroll pos.
+     */
+    private _calculateVisibleRange;
+    /**
+     * Render loop: recycles DOM nodes to match current visible range.
+     */
+    render(): void;
+    private _activeFilterPanel;
+    private _openFilterPanel;
+    /** Apply stored cell style properties to a DOM element */
+    private _applyStyleToCell;
+    private _onScroll;
+    _isCellVisible(x: number, y: number): boolean;
+    _updateGhostSize(): void;
+    _getCumulativeWidth(col: number): number;
+    _getCumulativeHeight(row: number): number;
+    getCellRect(x: number, y: number): {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    scrollToCell(x: number, y: number): void;
+    measureRowHeight(y: number): number;
+    destroy(): void;
+}
+
+/**
+ * @worksheet/utils — shared types for cell overlay components
+ */
+type OverlayType = 'checkbox' | 'dropdown' | 'image';
+interface CheckboxConfig {
+    /** If true, the underlying cell text is hidden and only the checkbox shows */
+    hideText?: boolean;
+}
+type ValidationCriteria = 'dropdown' | 'dropdown_range' | 'text_contains' | 'text_not_contains' | 'text_is' | 'text_is_email' | 'text_is_url' | 'date_is' | 'date_before' | 'date_after' | 'date_on_or_before' | 'date_on_or_after' | 'date_between' | 'date_not_between' | 'date_is_valid' | 'num_greater' | 'num_greater_equal' | 'num_less' | 'num_less_equal' | 'num_equal' | 'num_not_equal' | 'num_between' | 'num_not_between' | 'custom_formula' | 'checkbox';
+interface DropdownOption {
+    text: string;
+    color?: string;
+}
+interface ValidationConfig {
+    criteria: ValidationCriteria;
+    options?: DropdownOption[];
+    value1?: string;
+    value2?: string;
+    displayStyle?: 'chip' | 'arrow' | 'text';
+    showWarning?: boolean;
+    rejectInput?: boolean;
+    helpText?: string;
+    showHelpText?: boolean;
+    allowMultiSelect?: boolean;
+    showInputMessage?: boolean;
+    showErrorMessage?: boolean;
+    checkedValue?: string;
+    uncheckedValue?: string;
+}
+interface ImageConfig {
+    /** URL or data-URL of the image */
+    url: string;
+    /** 'in-cell' fills the cell; 'over-cells' floats freely on top of the grid */
+    mode: 'in-cell' | 'over-cells';
+    /** Native pixel width of the source image (captured after load) */
+    originalWidth?: number;
+    /** Native pixel height of the source image (captured after load) */
+    originalHeight?: number;
+    /** Horizontal drag offset in pixels from the anchor cell's left edge */
+    dx?: number;
+    /** Vertical drag offset in pixels from the anchor cell's top edge */
+    dy?: number;
+    /** Custom rendered width in pixels (overrides grid-computed width when set) */
+    dw?: number;
+    /** Custom rendered height in pixels (overrides grid-computed height when set) */
+    dh?: number;
+    /** Number of grid columns spanned (default 1) */
+    colSpan?: number;
+    /** Number of grid rows spanned (default 1) */
+    rowSpan?: number;
+}
+interface OverlayConfigMap {
+    checkbox: CheckboxConfig;
+    dropdown: ValidationConfig;
+    image: ImageConfig;
+}
+/** Generic config for a specific overlay type */
+type OverlayConfig<T extends OverlayType> = OverlayConfigMap[T];
+interface OverlayEntry {
+    type: OverlayType;
+    config: OverlayConfigMap[OverlayType];
+    el: HTMLElement;
+    /** Extra span columns (for images / shapes that cover multiple cells) */
+    colSpan: number;
+    rowSpan: number;
+    /** Custom pixel offsets from the anchor cell's calculated position (for dragging) */
+    dx?: number;
+    dy?: number;
+    /** Custom pixel dimensions (for resizing images) */
+    dw?: number;
+    dh?: number;
+}
+type PivotAggregation = 'SUM' | 'COUNT' | 'COUNTA' | 'COUNTUNIQUE' | 'AVERAGE' | 'MAX' | 'MIN' | 'MEDIAN' | 'PRODUCT' | 'STDEV' | 'STDEVP' | 'VAR' | 'VARP';
+interface PivotField {
+    /** Index of the column in the source data (0-based) */
+    sourceColumn: number;
+    /** Custom name/label for the field */
+    name: string;
+    /** Sort order for the groups generated by this field */
+    sort?: 'ASC' | 'DESC';
+    /** Whether to show totals for this grouping level */
+    showTotals?: boolean;
+    /** Field name to sort by (for values) or 'source' for the field itself */
+    sortBy?: string;
+    /** Whether to repeat row labels for multi-level pivots */
+    repeatLabels?: boolean;
+}
+interface PivotValue {
+    /** Index of the column in the source data (0-based) */
+    sourceColumn: number;
+    /** Custom name/label for the aggregated value */
+    name: string;
+    /** Aggregation function to apply */
+    aggregation: PivotAggregation;
+    /** How to display the value (e.g., as a percentage of total) */
+    showAs?: 'default' | 'percent_of_row' | 'percent_of_column' | 'percent_of_grand_total';
+}
+interface PivotConfig {
+    /** Range of the source data (inclusive) using 0-based indices */
+    sourceRange: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    };
+    /** Fields to use as rows (grouping) */
+    rows: PivotField[];
+    /** Fields to use as columns (grouping) */
+    columns: PivotField[];
+    /** Fields to use as values (aggregation) */
+    values: PivotValue[];
+    /** Human-readable string representation of the source range (e.g. "Sheet1!A1:D100") */
+    sourceRangeString?: string;
+    /** Whether to show grand totals for rows/columns */
+    showGrandTotals?: boolean;
+    /** Name of the worksheet containing the source data */
+    sourceSheet?: string;
+    /** Anchor coordinate for the top-left of the pivot result (x: column, y: row) */
+    destAnchor?: {
+        x: number;
+        y: number;
+    };
+}
+
+/** Minimal interface the OverlayManager needs from Viewport for positioning. */
+interface ViewportPositionCtx {
+    getCumulativeWidth(col: number): number;
+    getCumulativeHeight(row: number): number;
+    getColWidth(col: number): number;
+    getRowHeight(row: number): number;
+    scrollLeft: number;
+    scrollTop: number;
+}
+/** Minimal Worksheet interface used to read/write cell values. */
+interface WorksheetLike {
+    data: {
+        getValue(x: number, y: number): string;
+    };
+    setValue(x: number, y: number, value: string): void;
+    setOverlay<T extends OverlayType>(x: number, y: number, type: T, config: OverlayConfig<T>): void;
+    removeOverlay(x: number, y: number): void;
+    colModel: {
+        getWidth(col: number): number;
+    };
+    rowModel: {
+        getHeight(row: number): number;
+    };
+    selectionModel?: {
+        anchorX: number;
+        anchorY: number;
+    };
+}
+/**
+ * OverlayManager
+ *
+ * Manages absolutely-positioned overlay elements that sit above the virtual grid.
+ * Mount via `ws.overlayManager = new OverlayManager(ws, viewLayer)`.
+ *
+ * Positioning is re-synced on every Viewport.render() call so overlays scroll
+ * and reposition correctly without any separate scroll listener.
+ */
+declare class OverlayManager {
+    private ws;
+    /** Map key: `"x,y"` */
+    private entries;
+    /** The overlay layer div — sits inside viewLayer, above cells */
+    private layer;
+    /** Last seen viewport context — used to immediately position new overlays */
+    private lastCtx;
+    constructor(ws: WorksheetLike, viewLayer: HTMLElement);
+    /**
+     * Add or replace an overlay at cell (x, y).
+     * @param x 0-based column
+     * @param y 0-based row
+     * @param type Overlay kind
+     * @param config Type-specific options
+     */
+    set<T extends OverlayType>(x: number, y: number, type: T, config: OverlayConfig<T>): void;
+    /**
+     * Get an overlay at cell (x, y).
+     */
+    get(x: number, y: number): OverlayEntry | undefined;
+    /**
+     * Remove an overlay at cell (x, y).
+     */
+    remove(x: number, y: number): void;
+    /**
+     * Iterate over all overlays.
+     */
+    forEach(callback: (entry: OverlayEntry, key: string) => void): void;
+    /**
+     * Remove all overlays.
+     */
+    clear(): void;
+    /**
+     * Re-position all overlays to match current scroll / cell sizes.
+     * Called by Viewport.render() via ws.overlayManager?.sync(ctx).
+     */
+    sync(ctx: ViewportPositionCtx): void;
+    private _makeCtx;
+    private _destroyEntry;
+}
+
+declare class PivotPanel {
+    element: HTMLElement;
+    private config;
+    private sourceColumns;
+    private sourceData;
+    private onUpdate;
+    constructor(parent: HTMLElement, config: PivotConfig, sourceColumns: string[], sourceData: any[][], onUpdate: (config: PivotConfig) => void);
+    open(): void;
+    close(): void;
+    private render;
+    private createSection;
+    private showAddFieldMenu;
+}
+
+declare class RowModel {
+    private defaultHeight;
+    private heights;
+    private hidden;
+    constructor(defaultHeight?: number);
+    getHeight(index: number): number;
+    setHeight(index: number, heightPx: number): void;
+    hide(index: number): void;
+    show(index: number): void;
+    splice(index: number, count: number, direction: 'insert' | 'delete'): void;
+    copyFrom(source: RowModel): void;
+}
+declare class ColModel {
+    private defaultWidth;
+    private widths;
+    private hidden;
+    constructor(defaultWidth?: number);
+    getWidth(index: number): number;
+    setWidth(index: number, widthPx: number): void;
+    hide(index: number): void;
+    show(index: number): void;
+    splice(index: number, count: number, direction: 'insert' | 'delete'): void;
+    copyFrom(source: ColModel): void;
+}
+
+type LicensePlan = 'starter' | 'pro' | 'enterprise';
+
+declare class SheetData {
+    /** Sparse cell storage keyed by "x,y" */
+    private cells;
+    /** Set by Worksheet after construction to enable formula evaluation */
+    formulaEngine?: FormulaEngine;
+    /** Set by Worksheet to enable license-based validation */
+    getEdition?: () => LicensePlan;
+    /** Read-only access to the internal cell map (used for cloning). */
+    protected getCells(): ReadonlyMap<string, CellData>;
+    /** Get the raw input string value (e.g. "1200" or "=A1") */
+    getValue(x: number, y: number): string;
+    /** Iterate over all populated cells (sparse scan) */
+    forEachCell(callback: (x: number, y: number, cell: CellData) => void): void;
+    /** Get all populated cells in a specific row (sparse scan) */
+    getCellsInRow(rowIdx: number): Array<[number, CellData]>;
+    /**
+     * Efficiently bulk-load parsed data from @worksheet/parser directly into the underlying maps.
+     * Bypasses the FormatEngine's slow parsing for string/number extraction, mapping cell types directly.
+     */
+    loadFromParser(parsedData: SheetData$1): Promise<void>;
+    /** Get the parsed typed data */
+    getCell(x: number, y: number): CellData | undefined;
+    /** Set a new raw input value, parsing it automatically */
+    setValue(x: number, y: number, rawInput: string): void;
+    /** Delete a cell entirely (including values, styles, formats, notes, comments) */
+    deleteCell(x: number, y: number): void;
+    /** Get note for a cell */
+    getNote(x: number, y: number): string | undefined;
+    /** Set note for a cell */
+    setNote(x: number, y: number, note: string | undefined): void;
+    /** Get comments for a cell */
+    getComments(x: number, y: number): any[] | undefined;
+    /** Set comments for a cell */
+    setComments(x: number, y: number, comments: any[] | undefined): void;
+    /** Set format mask explicitly (e.g "$#,##0.00") — legacy */
+    setFormat(x: number, y: number, formatString: string): void;
+    /** Get the full style object for a cell (returns empty object if none) */
+    getStyle(x: number, y: number): CellStyle;
+    /** Replace the full style object for a cell */
+    setStyle(x: number, y: number, style: CellStyle): void;
+    /** Deep-copy all cells and merges from another SheetData instance. */
+    copyFrom(source: SheetData): void;
+    /** Merge partial style properties into the existing cell style. */
+    mergeStyle(x: number, y: number, partial: Partial<CellStyle>): void;
+    /**
+     * Get the computed (evaluated) value of a cell.
+     * If the cell contains a formula, runs it through FormulaEngine.
+     * Otherwise returns parsedValue from FormatEngine.
+     */
+    getComputedValue(x: number, y: number): unknown;
+    /** Get display string formatted for the DOM */
+    getDisplayString(x: number, y: number): string;
+    /** Each merge range: { x1, y1, x2, y2 } (inclusive, 0-indexed) */
+    private merges;
+    /** Add a merge range */
+    addMerge(x1: number, y1: number, x2: number, y2: number): void;
+    /** Remove merges that overlap the given range */
+    removeMerge(x1: number, y1: number, x2: number, y2: number): void;
+    /** Get all merge ranges */
+    getMerges(): MergeRange[];
+    /** Find the merge range that contains cell (x, y), or null */
+    getMergeForCell(x: number, y: number): MergeRange | null;
+    /** Returns true if (x, y) is inside a merge but is NOT the top-left anchor cell */
+    isMergedHidden(x: number, y: number): boolean;
+    /**
+     * Shift cells and merges row-wise.
+     * If x1/x2 are provided, ONLY those columns are shifted.
+     */
+    spliceRows(y: number, count: number, direction: 'insert' | 'delete', x1?: number, x2?: number): void;
+    /**
+     * Shift cells and merges column-wise.
+     * If y1/y2 are provided, ONLY those rows are shifted.
+     */
+    spliceCols(x: number, count: number, direction: 'insert' | 'delete', y1?: number, y2?: number): void;
+    /** Clear all data */
+    clear(): void;
+}
+/** Merge range definition */
+interface MergeRange {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+
+/**
+ * data/utils.ts — pure coordinate & address utilities.
+ *
+ * No DOM dependencies — safe to use universally across the package.
+ */
+/**
+ * Convert a 0-based column index to an Excel letter label.
+ * 0 → "A", 25 → "Z", 26 → "AA", …
+ */
+declare function colIndexToLetter(n: number): string;
+/**
+ * Convert 0-based (x, y) coordinates to an Excel address string.
+ * (0, 0) → "A1", (1, 2) → "B3"
+ */
+declare function coordsToAddr(x: number, y: number): string;
+/**
+ * Parse an Excel address string into 0-based (x, y) coordinates.
+ * Returns `null` for invalid input.
+ * "A1" → { x: 0, y: 0 }, "B3" → { x: 1, y: 2 }
+ */
+declare function parseAddress(addr: string): {
+    x: number;
+    y: number;
+} | null;
+
+/**
+ * Worksheet — per-sheet object. Phase 2 enhanced.
+ * Integrates SelectionModel (anchor/focus), CellEditor, and ClipboardHandler.
+ * Mirrors jSpreadsheet CE's worksheet object pattern.
+ */
+declare class WorksheetModel {
+    parent: Spreadsheet;
+    options: SheetMeta;
+    element: HTMLElement;
+    content: HTMLElement;
+    table: HTMLTableElement;
+    thead: HTMLTableSectionElement;
+    tbody: HTMLTableSectionElement;
+    headerContainer: HTMLTableRowElement;
+    colgroupContainer: HTMLElement;
+    get root(): HTMLElement;
+    data: SheetData;
+    rowModel: RowModel;
+    colModel: ColModel;
+    filterState: FilterState;
+    overlays: OverlayRegistry;
+    cfManager: ConditionalFormattingManager;
+    viewport?: Viewport;
+    pivotTables: any[];
+    corner: HTMLElement;
+    textarea: HTMLTextAreaElement;
+    addRowsBar: HTMLElement;
+    selectionState: SelectionState;
+    selectionModel: SelectionModel;
+    selectionPainter: SelectionPainter;
+    cellEditor: CellEditor | null;
+    overlayManager?: OverlayManager;
+    history: HistoryEntry[];
+    historyIndex: number;
+    private readonly HISTORY_LIMIT;
+    /** When true, setValue/setWidth/setHeight skip pushing to history (used by _applyHistory) */
+    private _skipHistory;
+    /** When true, UI updates (viewport renders) are suppressed (used for batch loading) */
+    private _skipViewUpdate;
+    /** Lock for lazy overlay manager initialization */
+    private _ensuringOverlays;
+    resizing: {
+        column?: number;
+        row?: number;
+        width?: number;
+        height?: number;
+        element?: HTMLElement;
+    } | null;
+    editingCell: {
+        x: number;
+        y: number;
+    } | null;
+    _onViewChange?: (x: number, y: number) => void;
+    constructor(parent: Spreadsheet, options: SheetMeta);
+    /** Max column index (0-based) */
+    get maxCol(): number;
+    /** Max row index (0-based) */
+    get maxRow(): number;
+    applyParsedMeta(meta: SheetMeta): void;
+    /** Deep-clone state from another WorksheetModel instance. */
+    cloneFrom(source: WorksheetModel): void;
+    /** Efficiently injects structured parser outputs for fast layout building */
+    loadFromParser(parsedData: SheetData$1): Promise<void>;
+    /** Detect if a row should be auto-fitted based on parser data (e.g. no height, but has wrapping or dropdowns) */
+    private rowHeightsNeedAutoFit;
+    /**
+     * Auto-fit a row's height based on its current content and column widths.
+     */
+    autoFitRowHeight(rowIdx: number): void;
+    /** Get cell text value at (x, y) */
+    getValue(x: number, y: number): string;
+    /** Get the evaluated result of a cell (for formulas) or its literal value */
+    getEvaluatedValue(x: number, y: number): string;
+    private _invalidCells;
+    private _validationPopover;
+    /** Check if a cell has a validation warning */
+    isInvalid(x: number, y: number): boolean;
+    /**
+     * Evaluates if a given string passes the cell's validation rules (if any).
+     * @returns true if valid or if there are no strict rules.
+     */
+    checkValidationValue(x: number, y: number, testValue: string): boolean;
+    /** Run validation for a specific cell, updating UI state */
+    validateCell(x: number, y: number): void;
+    private _getOptionsFromRange;
+    private _refreshDependentDropdowns;
+    private _isCellInRange;
+    /** Set cell text value at (x, y) */
+    setValue(x: number, y: number, value: string): void;
+    /**
+     * Set the style of a cell.
+     *
+     * @param x - Column index (0-based).
+     * @param y - Row index (0-based).
+     * @param style - Partial style object.
+     */
+    setStyle(x: number, y: number, style: Partial<CellStyle>): void;
+    /**
+     * Set multiple cell values at once as a single undoable history entry.
+     */
+    setValueBatch(cells: Array<{
+        x: number;
+        y: number;
+        value: string;
+    }>): void;
+    /** Get current selection coords (normalized bounding box) */
+    getSelection(): SelectionRange;
+    /**
+     * Update selection from explicit coords (public API + legacy support).
+     * Sets anchor = x1,y1 and focus = x2,y2.
+     */
+    updateSelectionFromCoords(x1: number, y1: number, x2: number, y2: number): void;
+    /** Force repaint the selection (e.g. after resize) */
+    refreshSelection(): void;
+    /**
+     * Apply the current SelectionModel state:
+     * 1. Sync legacy SelectionState
+     * 2. Repaint via SelectionPainter
+     * 3. Update FormulaBar
+     * 4. Update StatusBar aggregates
+     * 5. Fire onselection callback
+     * 6. Scroll anchor into view
+     */
+    _applySelectionModel(): void;
+    /** Move anchor+focus by (dx, dy) — plain navigation */
+    moveSelection(dx: number, dy: number): void;
+    /** Extend focus by (dx, dy) — shift navigation */
+    extendSelection(dx: number, dy: number): void;
+    /** Select all cells */
+    selectAll(): void;
+    /** Select entire column x */
+    selectColumn(x: number): void;
+    /** Select entire row y */
+    selectRow(y: number): void;
+    /** Open inline cell editor at (x, y), optionally with an initial character */
+    openEditor(x: number, y: number, initialChar?: string, options?: {
+        preventFocus?: boolean;
+    }): void;
+    /** Close inline cell editor */
+    closeEditor(save: boolean): void;
+    /** Undo last action */
+    undo(): void;
+    /** Redo last undone action */
+    redo(): void;
+    /** Set column width in px */
+    setWidth(col: number, width: number, skipHistory?: boolean): void;
+    /** Set row height in px */
+    setHeight(row: number, height: number, skipHistory?: boolean): void;
+    /** Turn on filter buttons in all column headers. */
+    enableFilters(col?: number): void;
+    /**
+     * Remove all filters: un-hide all filter-hidden rows and hide funnel buttons.
+     * Rows hidden by other means (explicit hide) are NOT un-hidden.
+     */
+    disableFilters(col?: number): void;
+    /**
+     * Recompute row visibility based on the current FilterState.
+     * Hides rows that do not pass the active filters.
+     * Row 0 (header) is never hidden.
+     */
+    applyFilters(): void;
+    insertRow(y: number, count?: number): void;
+    deleteRow(y: number, count?: number): void;
+    insertColumn(x: number, count?: number): void;
+    deleteColumn(x: number, count?: number): void;
+    /** Called by ResizeObserver when container resizes */
+    onResize(): void;
+    /** Download current sheet as CSV */
+    download(): Promise<void>;
+    /** Get the style object for anchor cell (used by toolbar sync) */
+    getStyle(x: number, y: number): CellStyle;
+    /**
+     * Apply a partial style to all cells in the current selection.
+     * Records a SINGLE 'style-batch' history entry so undo/redo is atomic.
+     */
+    applyStyleToSelection(partial: Partial<CellStyle>): void;
+    /**
+     * Apply a number format style to all cells in the current selection.
+     */
+    setFormatToSelection(fmt: CellStyle['numberFormat'], decimals?: number): void;
+    /** Merge all cells in the current selection into one */
+    mergeSelection(): void;
+    /** Unmerge all merges within the current selection */
+    unmergeSelection(): void;
+    /** Merge each row in the selection horizontally */
+    mergeHorizontally(): void;
+    /** Merge each column in the selection vertically */
+    mergeVertically(): void;
+    /** Apply manual direction override to selection */
+    applyDirectionToSelection(dir: 'ltr' | 'rtl'): void;
+    /**
+     * Applies borders dynamically to avoid double borders between adjacent cells.
+     */
+    applyBordersToSelection(type: string, weight: number, style: string, borderColor: string): void;
+    /**
+     * Apply a paste snapshot (value + style per cell) atomically with one undo entry.
+     * Called by ClipboardHandler after building the before/after cell snapshots.
+     */
+    pasteRange(record: Array<{
+        x: number;
+        y: number;
+        beforeValue: string;
+        afterValue: string;
+        beforeStyle: CellStyle | undefined;
+        afterStyle: CellStyle | undefined;
+        beforeOverlay: any | undefined;
+        afterOverlay: any | undefined;
+        afterNote?: string;
+        afterComments?: any[];
+    }>): void;
+    /**
+     * Get all data (cells, styles, merges, overlays) for a range.
+     * Useful for advanced copy/paste.
+     */
+    getRangeData(range: SelectionRange): {
+        cells: Array<Array<{
+            value: string;
+            style?: CellStyle;
+            overlay?: any;
+            note?: string;
+            comments?: any[];
+        }>>;
+        merges: Array<{
+            x1: number;
+            y1: number;
+            x2: number;
+            y2: number;
+        }>;
+    };
+    /**
+     * Clear all cell values AND styles in a range as a single undoable action.
+     */
+    clearRange(x1: number, y1: number, x2: number, y2: number): void;
+    private _pushHistory;
+    private _applyHistory;
+    private _updateFormulaBar;
+    /** Scroll cell at (x,y) into view */
+    _scrollCellIntoView(x: number, y: number): void;
+    /**
+     * Get an overlay at the given cell position.
+     */
+    getOverlay(x: number, y: number): OverlayEntry | undefined;
+    /**
+     * Place a cell overlay (checkbox)
+     * at the given cell position. Lazy-loads @worksheet/utils on first call.
+     */
+    setOverlay<T extends OverlayType>(x: number, y: number, type: T, config: OverlayConfig<T>, 
+    /** @internal — pre-mutation before-snapshot injected by OverlayManager.updateConfig */
+    _beforeHint?: {
+        type: OverlayType;
+        config: any;
+    }): Promise<void>;
+    /** Remove the overlay at cell (x, y). */
+    removeOverlay(x: number, y: number): void;
+    private _parseSqref;
+    private _mapCFOperator;
+    private _mapParsedStyleToCellStyle;
+    /** Remove all overlays on this worksheet. */
+    clearOverlays(): void;
+    private _ensureOverlayManager;
+    private _updateValidationPopover;
+    private _showValidationPopover;
+    private _hideValidationPopover;
+}
+
+/**
+ * ClipboardHandler — manages copy/cut/paste with marching ants visual.
+ * Copies cell values, styles, merges, and overlays.
+ * Supports multiple MIME types for cross-app compatibility.
+ */
+declare class ClipboardHandler {
+    /** Internal snapshot for same-instance copy/paste */
+    private snapshot;
+    /** Source range for the snapshot */
+    private srcRange;
+    private isCutMode;
+    private ws;
+    /** The SVG marching-ants overlay element */
+    private copyBorderEl;
+    copy(ws: WorksheetModel): void;
+    cut(ws: WorksheetModel): void;
+    /**
+     * Paste at current selection anchor.
+     * Priority: application/x-worksheet > text/html > text/plain.
+     */
+    paste(ws: WorksheetModel, text?: string): Promise<void>;
+    clear(): void;
+    private _pasteRange;
+    private _pasteTSV;
+    private _clear;
+    private _startAnts;
+    private _positionBorder;
+    private _applyClass;
+    private _writeToClipboard;
+    private _toHTML;
+}
+
+/**
+ * CommentPanel — A floating panel to display and edit threaded comments.
+ * Matches Google Sheets exact styling (white box, shadows, threaded replies).
+ */
+declare class CommentPanel {
+    element: HTMLElement;
+    private ws;
+    private currentX;
+    private currentY;
+    private _visible;
+    constructor();
+    attach(container: HTMLElement): void;
+    get isVisible(): boolean;
+    private _boundClickOutside;
+    /** Open comments for a specific cell */
+    open(ws: WorksheetModel, x: number, y: number): void;
+    private _renderContent;
+    private _renderNewCommentInput;
+    private _createAvatar;
+    private _renderThread;
+    private _createMoreMenu;
+    private _renderEditMode;
+    private _formatTime;
+    close(): void;
+}
+
+/**
+ * NoteEditor — A floating textarea to edit cell notes.
+ * Matches Google Sheets exact styling (black border, yellow background tooltip).
+ */
+declare class NoteEditor {
+    element: HTMLElement;
+    private textarea;
+    private ws;
+    private currentX;
+    private currentY;
+    private _visible;
+    constructor();
+    attach(container: HTMLElement): void;
+    get isVisible(): boolean;
+    private _boundClickOutside;
+    /** Open editor for a specific cell in the given worksheet */
+    open(ws: WorksheetModel, x: number, y: number, editMode?: boolean): void;
+    /** Close and optionally save the note */
+    close(save?: boolean): void;
+}
+
+/**
+ * ConditionalFormattingPanel — Sidebar for managing conditional formatting rules.
+ * Redesigned to match Google Sheets UI/UX with premium aesthetics.
+ */
+declare class ConditionalFormattingPanel {
+    element: HTMLElement;
+    private parent;
+    private body;
+    private currentWs;
+    private editingRuleIndex;
+    private tempRule;
+    constructor(parent: Spreadsheet);
+    open(ws: WorksheetModel): void;
+    close(): void;
+    private _buildHeader;
+    private _render;
+    private _renderRuleList;
+    private _renderRuleEditor;
+    private _createSection;
+    private _getOperatorLabel;
+    private _hasValueInput;
+}
+
+/**
+ * FillHandler — handles fill-handle drag to auto-fill cells.
+ * Detects number patterns, dates, and falls back to copy.
+ */
+declare class FillHandler {
+    private ws;
+    private startRange;
+    private previewEl;
+    private isDragging;
+    private fillDir;
+    /**
+     * Called when pointerdown lands on the fill handle corner.
+     */
+    startDrag(e: PointerEvent, ws: WorksheetModel): void;
+    /**
+     * Called on pointermove while dragging fill handle.
+     */
+    onMove(e: PointerEvent): void;
+    /**
+     * Called on pointerup — execute the fill.
+     */
+    endDrag(e: PointerEvent): void;
+    private _executeFill;
+    /** Detect pattern and return a series function */
+    private _detectSeries;
+    private _colValues;
+    private _rowValues;
+    private _positionPreview;
+    private _cleanup;
+    private _getCell;
+}
+
+/**
+ * FindReplace — Google Sheets-style Find and Replace dialog.
+ * Matches the exact Google Sheets UI layout.
+ */
+declare class FindReplace {
+    element: HTMLElement;
+    private parent;
+    private findInput;
+    private replaceInput;
+    private searchDropdown;
+    private matchCaseCheckbox;
+    private entireCellCheckbox;
+    private useRegexCheckbox;
+    private formulaeCheckbox;
+    private linksCheckbox;
+    private statusLabel;
+    private matches;
+    private currentMatchIdx;
+    constructor(parent: Spreadsheet);
+    open(): void;
+    close(): void;
+    isOpen(): boolean;
+    private _createInputRow;
+    private _createCheckbox;
+    private _createActionButton;
+    private _getWorksheet;
+    private _search;
+    private _isMatch;
+    private _findNext;
+    private _findPrev;
+    private _goToMatch;
+    private _replaceCurrent;
+    private _replaceAll;
+    private _replaceValue;
+    private _updateStatus;
+}
+
+/**
+ * DataValidation — Google Sheets-style Data validation rules sidebar.
+ * Specifically handles Dropdown configuration.
+ */
+declare class DataValidation {
+    element: HTMLElement;
+    private parent;
+    private body;
+    private rangeContainer;
+    private rangeLabel;
+    private criteriaContainer;
+    private advancedContainer;
+    private optionsContainer;
+    private currentWs;
+    private currentX;
+    private currentY;
+    private options;
+    private displayStyle;
+    private showWarning;
+    private criteria;
+    private value1;
+    private value2;
+    private showHelpText;
+    private helpText;
+    private allowMultiSelect;
+    private advancedExpanded;
+    private activePicker;
+    private pickerHandler;
+    constructor(parent: Spreadsheet);
+    open(ws: WorksheetModel, x: number, y: number): void;
+    close(): void;
+    updateSelection(ws: WorksheetModel): void;
+    private _buildHeader;
+    private _errorMsg;
+    private _inputRefs;
+    private _buildFooter;
+    private _render;
+    private _renderRange;
+    private _renderCriteria;
+    private _renderAdvanced;
+    private _renderOptions;
+    private _openColorPicker;
+    private _closePicker;
+    private _updateCPPreview;
+    private _save;
+    private _getRangeRef;
+}
+
+type MenuType = 'cell' | 'row-header' | 'col-header' | 'tab' | 'image';
+interface MenuItem {
+    label: string;
+    shortcut?: string;
+    icon?: string;
+    disabled?: boolean;
+    separator?: false;
+    items?: MenuDef[];
+    action?: (ws: WorksheetModel | null, targetEl: HTMLElement | null) => void;
+}
+interface MenuSeparator {
+    separator: true;
+}
+type MenuDef = MenuItem | MenuSeparator;
+/**
+ * ContextMenu — Web-native popup menu supporting cascading submenus.
+ */
+declare class ContextMenu {
+    element: HTMLElement;
+    private spreadsheet;
+    private _visible;
+    private childMenu;
+    private activeItemEl;
+    private activeTarget;
+    private parentMenu;
+    constructor(spreadsheet: Spreadsheet, parentMenu?: ContextMenu | null);
+    private _contains;
+    openMenu(x: number, y: number, items: MenuDef[], ws: WorksheetModel | null, options?: {
+        isMenuList?: boolean;
+        targetEl?: HTMLElement | null;
+    }): void;
+    open(x: number, y: number, type: MenuType, ws: WorksheetModel | null, targetEl?: HTMLElement): void;
+    close(): void;
+    closeAll(): void;
+    private _render;
+    private _getItems;
+    /**
+     * Sort all rows by the values in `col`.
+     * Sorts ALL rows (no assumed header row).
+     * Numbers are compared numerically; strings use locale-aware natural sort.
+     * Empty cells always sort to the bottom regardless of direction.
+     */
+    private _sortRows;
+}
+declare module '../sheet-tabs/SheetTabs' {
+    interface SheetTabs {
+        startRename(): void;
+    }
+}
+
+/**
+ * FormulaBar — NameBox + ƒx button + formula input.
+ */
+declare class FormulaBar {
+    element: HTMLElement;
+    private nameBoxEl;
+    private formulaInputEl;
+    private confirmBtns;
+    private spreadsheet;
+    private _fnMenu?;
+    private _fxBtn;
+    constructor(spreadsheet: Spreadsheet);
+    private build;
+    update(address: string, value: string): void;
+    enterEditMode(value: string): void;
+    exitEditMode(): void;
+    private _navigateToAddress;
+}
+
+/**
+ * LoadingOverlay — A premium loading screen with the custom "W" Chart logo from test.svg.
+ */
+declare class LoadingOverlay {
+    element: HTMLElement;
+    private _visible;
+    constructor(parent: HTMLElement);
+    show(): void;
+    hide(): void;
+    private _injectStyles;
+}
+
+/**
+ * SheetTabs — horizontal tab strip replacing jSuites.tabs().
+ * Zero dependencies.
+ */
+declare class SheetTabs {
+    element: HTMLElement;
+    private spreadsheet;
+    private strip;
+    activeIndex: number;
+    private addBtn;
+    private navLeft;
+    private navRight;
+    private navContainer;
+    private resizeObserver;
+    constructor(spreadsheet: Spreadsheet);
+    private build;
+    private updateScrollState;
+    render(): void;
+    /** Update the visibility state of the add-sheet button based on maxSheets config and license limits */
+    updateAddButton(): void;
+    setActiveTab(index: number): void;
+    private _startRename;
+    private _attachDragReorder;
+    private navBtn;
+    private openAllSheetsMenu;
+    private getWatermark;
+}
+
+declare class KeyboardShortcuts {
+    element: HTMLElement;
+    private parent;
+    private searchInput;
+    private listContainer;
+    constructor(parent: Spreadsheet);
+    open(): void;
+    close(): void;
+    private _renderList;
+}
+
+declare class Toolbar {
+    element: HTMLElement;
+    private parent;
+    private _fnMenu?;
+    private btnBold;
+    private btnItalic;
+    private btnStrikethrough;
+    private spanFontFamily;
+    private spanFontSize;
+    private spanZoom;
+    private colorBarText;
+    private colorBarFill;
+    private colorBarBorder;
+    private _activeDropdowns;
+    private _activeAnchors;
+    private _zoom;
+    private _borderPenColor;
+    private _borderPenWeight;
+    private _borderPenStyle;
+    constructor(parent: Spreadsheet);
+    syncToWorksheet(ws: WorksheetModel): void;
+    /** Called by Viewport link tooltip to open the insert-link panel */
+    openLinkEditor(x: number, y: number): void;
+    private _build;
+    private _makeBtn;
+    private _setupResponsive;
+    private _onResize;
+    private _dispatch;
+    private _openFunctionMenu;
+    private _openImageDropdown;
+    openImageDialog(title: string, onApplyImg: (url: string) => void): void;
+    private _openOverflowMenu;
+    private _openDropdown;
+    private _closeDropdowns;
+    private _ddItem;
+    private _openFileMenu;
+    private _openZoomDropdown;
+    private _openFormatDropdown;
+    private _openFontFamilyDropdown;
+    private _openFontSizeDropdown;
+    private _openColorDropdown;
+    private _openBordersDropdown;
+    private _openBorderStyleDropdown;
+    private _openMergeDropdown;
+    private _openAlignDropdown;
+    private _openVAlignDropdown;
+    private _openWrapDropdown;
+    private _openRotationDropdown;
+    private _openLinkPanel;
+    /** Reusable dialog shell */
+    private _createCustomFmtDialog;
+    /** Custom Currency dialog — exact Google Sheets clone */
+    private _openCustomCurrencyDialog;
+    /** Custom Date and Time dialog — Google Sheets clone */
+    private _openCustomDateTimeDialog;
+    /** Custom Number Format dialog — Google Sheets clone */
+    private _openCustomNumberDialog;
+    private _insertCheckbox;
+    private _insertDropdown;
+    private _openDirectionDropdown;
+}
+
+/**
+ * Watermark — a repeating diagonal overlay for trial and expired licenses.
+ */
+declare class Watermark {
+    element: HTMLElement;
+    private spreadsheet;
+    constructor(spreadsheet: Spreadsheet);
+    update(): void;
+    destroy(): void;
+}
+
+/**
+ * ThemeManager — handles Built-in themes and Custom color overrides.
+ * Maps user-friendly color names to internal CSS Custom Properties.
+ */
+declare class ThemeManager {
+    private root;
+    /** The currently active default cell font display name */
+    defaultCellFont: string;
+    private static COLOR_MAP;
+    constructor(root: HTMLElement);
+    /** Set built-in theme (light/dark) */
+    setTheme(theme: 'light' | 'dark'): void;
+    /** Apply custom color overrides via inline styles on the root element */
+    setColors(colors: Partial<ThemeColors>): void;
+    /** Apply custom font overrides via CSS variables */
+    setFonts(fonts: ThemeFonts): void;
+    /**
+     * Set the UI-chrome font (toolbar labels, sheet tabs, formula bar, status bar etc.).
+     * This intentionally does NOT affect cell content — cells use per-cell fontFamily styles.
+     * @param displayName - Font display name (stored for reference)
+     * @param cssFamily   - Full CSS font-family string to apply to --worksheet-font
+     */
+    setDefaultFont(displayName: string, cssFamily: string): void;
+}
+
+/**
+ * Spreadsheet — top-level owner.
+ * Mirrors jSpreadsheet CE's spreadsheet plain-object, but as a class.
+ * Owns all WorksheetModel instances and UI chrome components.
+ */
+declare class Spreadsheet {
+    element: HTMLElement;
+    root: HTMLElement;
+    config: WorksheetOptions;
+    worksheets: WorksheetModel[];
+    current: WorksheetModel | null;
+    toolbarUI: Toolbar;
+    formulaBar: FormulaBar;
+    sheetTabs?: SheetTabs;
+    contextMenu: ContextMenu;
+    findReplace: FindReplace;
+    dataValidation: DataValidation;
+    keyboardShortcuts: KeyboardShortcuts;
+    noteEditor: NoteEditor;
+    commentPanel: CommentPanel;
+    conditionalFormatting: ConditionalFormattingPanel;
+    pivotPanel: PivotPanel;
+    watermarkUI: Watermark;
+    loadingOverlay: LoadingOverlay;
+    clipboardHandler: ClipboardHandler;
+    fillHandler: FillHandler;
+    themeManager: ThemeManager;
+    worksheetHost: HTMLElement;
+    private _events;
+    constructor(element: HTMLElement, root: HTMLElement, config: WorksheetOptions);
+    /**
+     * Mount all UI chrome into root after worksheets are built.
+     */
+    mount(): void;
+    /**
+     * Close all active sidebars and panels.
+     */
+    closeAllSidebars(): void;
+    /** Switch the active worksheet model by index */
+    setActiveWorksheet(index: number): void;
+    /** Change the current theme (light | dark) */
+    setTheme(theme: 'light' | 'dark'): void;
+    /** Apply custom color overrides */
+    setColors(colors: Partial<ThemeColors>): void;
+    /** Apply custom font overrides */
+    setFonts(fonts: ThemeFonts): void;
+    /**
+     * Set the UI chrome font (toolbar labels, tabs, formula bar, status bar).
+     * This does NOT affect cell content — cell fonts are set per-cell via the font picker.
+     * Default UI font is Poppins.
+     *
+     * @param displayName - Font display name, e.g. "Roboto"
+     * @param cssFamily   - Full CSS font-family string (e.g. "Roboto, sans-serif").
+     *                      If omitted, the display name is used as-is.
+     */
+    setDefaultFont(displayName: string, cssFamily?: string): void;
+    /** Return the currently active worksheet model */
+    getActiveWorksheet(): WorksheetModel | null;
+    /** Add a new worksheet model (async — DOM built after promise resolves) */
+    addWorksheet(options?: Partial<SheetMeta>): Promise<WorksheetModel | null>;
+    /** Delete a worksheet model by index */
+    deleteWorksheet(index: number): void;
+    /** Duplicate an existing worksheet model */
+    duplicateWorksheet(index: number): Promise<void>;
+    /** Move a worksheet model from one index to another */
+    moveWorksheet(fromIdx: number, toIdx: number): void;
+    /** Rename a worksheet model */
+    renameWorksheet(index: number, newName: string): void;
+    /** Destroy the spreadsheet and release all resources. */
+    destroy(): void;
+    /**
+     * Import a workbook from a File object (XLSX, CSV, etc.)
+     * Distributes sheets and applies metadata.
+     */
+    importFromFile(file: File): Promise<void>;
+    /**
+     * Opens the pivot dialog to start creating a pivot table.
+     */
+    openPivotEditor(): void;
+    private _pivotWorksheet;
+    private _activePivotConfig;
+    private _lastPivotSize;
+    refreshPivotTable(config: PivotConfig, explicitWs?: WorksheetModel): Promise<void>;
+    /**
+     * Subscribes to spreadsheet events.
+     */
+    on(event: string, callback: (...args: any[]) => void): void;
+    /**
+     * Unsubscribes from spreadsheet events.
+     */
+    off(event: string, callback: (...args: any[]) => void): void;
+    /**
+     * Internal emit method for dispatching events.
+     */
+    emit(event: string, ...args: any[]): void;
+}
+
+/**
+ * @worksheet-js/core - Industrial-grade spreadsheet UI engine
+ * (c) 2024-present Worksheet Systems <support@worksheet.js>
+ * All Rights Reserved.
+ *
+ * PROPRIETARY AND CONFIDENTIAL: Unauthorized copying of this file,
+ * via any medium is strictly prohibited.
+ */
+
+/**
+ * The Worksheet class is the primary entry point for consumers to interact with the spreadsheet.
+ * It provides static factory methods to create and load spreadsheets, and instance methods
+ * to manipulate data, manage sheets, and handle exports.
+ *
+ * @example
+ * ```ts
+ * import { Worksheet } from '@worksheet-js/core';
+ *
+ * const sheet = await Worksheet.create({
+ *   container: document.getElementById('app')!,
+ *   worksheets: [{ worksheetName: 'Sheet1' }],
+ * });
+ * ```
+ */
+declare class Worksheet {
+    private _spreadsheet;
+    private constructor();
+    /**
+     * Create and mount a new Worksheet instance (async factory method).
+     */
+    static create(options: WorksheetOptions): Promise<Worksheet>;
+    /**
+     * Explicitly set the license globally.
+     */
+    static setLicense(licenseKey: string): Promise<void>;
+    /**
+     * Parses an XLSX file from a buffer and initializes a Worksheet instance.
+     */
+    static loadXlsx(buffer: Uint8Array, options: Omit<WorksheetOptions, 'worksheets'>): Promise<Worksheet>;
+    /**
+     * Imports a CSV file into the spreadsheet.
+     */
+    static loadCsv(buffer: Uint8Array, options: Omit<WorksheetOptions, 'worksheets'>, csvOptions?: CsvOptions): Promise<Worksheet>;
+    /**
+     * Imports a JSON into the spreadsheet.
+     */
+    static loadJson(data: any[], options: Omit<WorksheetOptions, 'worksheets'>, jsonOptions?: JsonOptions): Promise<Worksheet>;
+    /**
+     * Imports a HTML into the spreadsheet.
+     */
+    static loadHtml(html: string, options: Omit<WorksheetOptions, 'worksheets'>, htmlOptions?: HtmlOptions): Promise<Worksheet>;
+    /**
+     * Imports a WorkbookData object into a new Worksheet instance.
+     */
+    static loadData(data: any, options: Omit<WorksheetOptions, 'worksheets'>): Promise<Worksheet>;
+    /**
+     * Returns the underlying Spreadsheet engine instance.
+     */
+    get spreadsheet(): Spreadsheet;
+    /**
+     * Returns the currently active worksheet model.
+     */
+    get activeWorksheet(): WorksheetModel | null;
+    /**
+     * Returns an array of all worksheet models in the workbook.
+     */
+    get worksheets(): WorksheetModel[];
+    /**
+     * Switches the active worksheet.
+     *
+     * @param index - The index of the worksheet to activate (0-based).
+     */
+    setActiveWorksheet(index: number): void;
+    /**
+     * Exports the entire workbook to an XLSX file.
+     *
+     * @param filename - The name of the file to save (default: "spreadsheet.xlsx").
+     */
+    exportXlsx(filename?: string): Promise<void>;
+    /**
+     * Exports the active sheet to a CSV file.
+     *
+     * @param filename - The name of the file to save (default: "spreadsheet.csv").
+     */
+    exportCsv(filename?: string): Promise<void>;
+    /**
+     * Exports the active sheet to a JSON object.
+     *
+     * @returns An array of objects representing the sheet data.
+     */
+    exportJson(): Promise<any[]>;
+    private _triggerDownload;
+    /**
+     * Adds a new worksheet to the workbook.
+     *
+     * @param options - Optional metadata for the new sheet (name, color, etc.).
+     */
+    addWorksheet(options?: Partial<SheetMeta>): Promise<WorksheetModel | null>;
+    /**
+     * Deletes a worksheet from the workbook.
+     *
+     * @param index - The index of the worksheet to delete (0-based).
+     */
+    deleteWorksheet(index: number): void;
+    /**
+     * Duplicates an existing worksheet.
+     *
+     * @param index - The index of the worksheet to duplicate (0-based).
+     */
+    duplicateWorksheet(index: number): Promise<void>;
+    /**
+     * Moves a worksheet from one index to another.
+     *
+     * @param fromIdx - Current index of the worksheet.
+     * @param toIdx   - New index for the worksheet.
+     */
+    moveWorksheet(fromIdx: number, toIdx: number): void;
+    /**
+     * Import a workbook from a File object (XLSX, CSV, etc.)
+     */
+    importFromFile(file: File): Promise<void>;
+    /**
+     * Retrieves the raw clinical value of a cell.
+     *
+     * @param address - The cell address string (e.g., "A1", "B2").
+     * @returns The raw string value of the cell.
+     */
+    getValue(address: string): string;
+    /**
+     * Retrieves the raw clinical value of a cell.
+     *
+     * @param x - Column index (0-based).
+     * @param y - Row index (0-based).
+     * @returns The raw string value of the cell.
+     */
+    getValue(x: number, y: number): string;
+    /**
+     * Sets the value of a cell.
+     *
+     * @param address - The cell address string (e.g., "A1").
+     * @param value - The new value to set.
+     */
+    setValue(address: string, value: string): void;
+    /**
+     * Sets the value of a cell.
+     *
+     * @param x - Column index (0-based).
+     * @param y - Row index (0-based).
+     * @param value - The new value to set.
+     */
+    setValue(x: number, y: number, value: string): void;
+    /**
+     * Sets the style of a cell.
+     *
+     * @param address - The cell address string (e.g., "A1").
+     * @param style - The style object.
+     */
+    setStyle(address: string, style: Partial<CellStyle>): void;
+    /**
+     * Sets the style of a cell.
+     *
+     * @param x - Column index (0-based).
+     * @param y - Row index (0-based).
+     * @param style - The style object.
+     */
+    setStyle(x: number, y: number, style: Partial<CellStyle>): void;
+    /**
+     * Retrieves the style of a cell.
+     *
+     * @param address - The cell address string (e.g., "A1").
+     * @returns The style object.
+     */
+    getStyle(address: string): Partial<CellStyle>;
+    /**
+     * Retrieves the style of a cell.
+     *
+     * @param x - Column index (0-based).
+     * @param y - Row index (0-based).
+     * @returns The style object.
+     */
+    getStyle(x: number, y: number): Partial<CellStyle>;
+    /**
+     * Renames a worksheet.
+     *
+     * @param index - Index of the worksheet.
+     * @param name - New name for the worksheet.
+     */
+    renameWorksheet(index: number, name: string): void;
+    /**
+     * Subscribes to spreadsheet events.
+     */
+    on(event: string, callback: (...args: any[]) => void): void;
+    /**
+     * Unsubscribes from spreadsheet events.
+     */
+    off(event: string, callback: (...args: any[]) => void): void;
+    /**
+     * Destroys the spreadsheet instance.
+     */
+    destroy(): void;
+}
+
+/**
+ * manager.ts — License lifecycle manager.
+ * Handles initialization, periodic re-validation, integrity checks,
+ * and runtime tamper detection.
+ */
+
+/**
+ * Initialize the license system using the provided license key.
+ *
+ * @param licenseKey - The signed license key string.
+ */
+declare function initializeLicense(licenseKey?: string): Promise<void>;
+
+export { type CellAddress, type CellStyle, type CellStyleSnapshot, type CheckboxConfig, type HistoryEntry, type ImageConfig, type OnChangeCallback, type OnCreateWorksheetCallback, type OnDestroyCallback, type OnLoadCallback, type OnSelectionCallback, type OverlayConfig, type OverlayItem, OverlayManager, type OverlayType, type SelectionRange, type SheetMeta, Spreadsheet, type ThemeColors, type ThemeFonts, Worksheet, WorksheetModel, type WorksheetOptions, colIndexToLetter, coordsToAddr, initializeLicense, parseAddress };