@pixerate/editor 0.19.0 → 0.20.0

package/dist/spreadsheet/index.d.ts

@@ -1,343 +1,401 @@
-type CellFormat = 'text' | 'number' | 'currency' | 'percentage' | 'date' | 'badge' | 'status' | 'assignee';
-type ColumnType = 'bound' | 'freeform' | 'formula';
-interface ColumnBinding {
-    dataSource: string;
-    field: string;
-}
-interface SpreadsheetColumn {
-    id: string;
-    key: string;
-    title: string;
-    width?: number;
-    type: ColumnType;
-    binding?: ColumnBinding;
-    formula?: string;
-    format?: CellFormat;
-    readOnly?: boolean;
-}
-type RowType = 'record' | 'freeform';
-interface SpreadsheetRow {
-    id: string;
-    index: number;
-    height?: number;
-    recordId?: string;
-    type: RowType;
-}
-interface CellCoordinate {
-    row: number;
-    col: number;
-    rowId?: string;
-    colId?: string;
-}
-interface CellRange {
-    startRow: number;
-    startCol: number;
-    endRow: number;
-    endCol: number;
-}
-interface CellData {
-    raw: string;
-    value: any;
-    error?: string;
-    format?: CellFormat;
-    readOnly?: boolean;
-}
-interface SpreadsheetDocument {
-    id: string;
+import { A as ASTNode, r as FormulaErrorCode, v as FormulaRange, G as GroupAggregate, J as SortDirection, e as CellRange, d as CellPosition, p as FilterRule, W as SpreadsheetController } from '../controller-OUdxPY-X.js';
+export { B as BinaryOpNode, C as CellCoordinate, a as CellData, b as CellDep, c as CellFormat, f as CellRefNode, g as CellValueReader, h as ColumnBinding, i as ColumnType, j as CsvExportOptions, k as CsvImportOptions, D as DEFAULT_COLUMN_WIDTH, l as DEFAULT_ROW_HEIGHT, m as DataSourceBinder, n as DependencyGraph, E as EvaluationContext, F as FORMULA_ERRORS, o as FilterOperator, q as FormulaDiagnostic, s as FormulaEvaluationResult, t as FormulaEvaluator, u as FormulaParser, w as FormulaToken, x as FormulaTokenType, y as FunctionCallNode, z as GroupSummary, L as LiteralNode, N as NewFilterRule, P as ParsedSpreadsheetClipboard, H as PropertyRefNode, R as RangeNode, I as RowType, S as SPREADSHEET_CLIPBOARD_MIME, K as SortKey, M as SpreadsheetCellSpan, O as SpreadsheetClipboardCell, Q as SpreadsheetClipboardData, T as SpreadsheetClipboardPayload, U as SpreadsheetClipboardSource, V as SpreadsheetColumn, X as SpreadsheetControllerOptions, Y as SpreadsheetDataSource, Z as SpreadsheetDataSourceField, _ as SpreadsheetDocument, $ as SpreadsheetFilterState, a0 as SpreadsheetGrouping, a1 as SpreadsheetRow, a2 as SpreadsheetRowGroup, a3 as SpreadsheetRowSection, a4 as SpreadsheetTableSettings, a5 as SpreadsheetViewColumn, a6 as SpreadsheetViewModel, a7 as SpreadsheetViewRow, a8 as StructuralChange, a9 as UnaryOpNode, aa as WHOLE_COLUMN_END_ROW, ab as buildSpreadsheetView, ac as colNameToIndex, ad as columnDependencyKey, ae as computeRowGroups, af as createSpreadsheetClipboardData, ag as describeFormulaError, ah as extractCellDependencies, ai as getRowSection, aj as getTableSections, ak as indexToColName, al as isFormulaError, am as mapFormulaReferences, an as offsetFormulaReferences, ao as parseCellReference, ap as parseFormula, aq as parseHtmlTable, ar as parseRange, as as readSpreadsheetClipboard, at as rebaseClipboardRows, au as remapFormulaReferences, av as rowPassesFilters, aw as serializeHtmlTable, ax as shiftFormulaReferences, ay as tokenizeFormula } from '../controller-OUdxPY-X.js';
+import { I as ImportAdapterRegistry, c as ImportAdapter, h as ImportInput, a as ImportOutcome } from '../registry-iAHbqkYt.js';
+
+type FormulaFunctionCategory = 'math' | 'statistical' | 'logical' | 'text' | 'lookup' | 'date' | 'information';
+/** What an argument expects. Used for documentation, hints and messages. */
+type FormulaArgumentType = 'any' | 'number' | 'text' | 'logical' | 'date' | 'range' | 'criteria';
+interface FormulaArgumentSpec {
+    /** Argument name shown in signatures, e.g. `sum_range`. */
     name: string;
-    columns: SpreadsheetColumn[];
-    rows: SpreadsheetRow[];
-    cells: Record<string, Record<string, CellData>>;
-    createdAt?: number;
-    updatedAt?: number;
+    description: string;
+    type?: FormulaArgumentType;
+    /** The argument may be left out. */
+    optional?: boolean;
+    /**
+     * The argument repeats. Consecutive repeating arguments form a group that
+     * repeats together (`criteria_range, criteria` in SUMIFS). The group must be
+     * the last arguments, and is required once unless its first spec is optional.
+     */
+    repeating?: boolean;
 }
-interface SpreadsheetDataSourceField {
-    key: string;
-    label: string;
-    type: 'string' | 'number' | 'date' | 'boolean' | 'enum';
-    options?: Array<{
-        key: string;
-        label: string;
-        color?: string;
-    }>;
+/** One argument of a call, evaluated lazily so functions like IF can short-circuit. */
+interface FormulaArgument {
+    /** 0-based position in the call. */
+    readonly index: number;
+    readonly node: ASTNode;
+    /** Evaluates the argument (once; later calls return the cached value). Ranges evaluate to arrays. */
+    value(): any;
 }
-interface SpreadsheetDataSource {
-    id: string;
+/** What a function implementation receives. Coercion helpers report argument-indexed diagnostics. */
+interface FormulaFunctionContext {
+    /** Upper-case function name. */
+    readonly name: string;
+    readonly args: readonly FormulaArgument[];
+    /** Returns `code` and records `message` as the reason (shown to the user if the cell ends up with that error). */
+    error(code: FormulaErrorCode, message?: string): string;
+    /** Like `error`, phrased as `Argument N of NAME <reason>`. */
+    argError(index: number, code: FormulaErrorCode, reason: string): string;
+    /** Whether argument `index` was supplied. */
+    has(index: number): boolean;
+    /** Raw (lazily evaluated) value of an argument; ranges are arrays. */
+    value(index: number): any;
+    /** Single value of an argument: a one-cell range is unwrapped, larger ranges are #VALUE!. */
+    scalar(index: number): any;
+    /** Argument as a number (or an error string). Text that isn't numeric is #VALUE!. */
+    number(index: number, fallback?: number): number | string;
+    /** Argument as an integer (truncated toward zero). */
+    integer(index: number, fallback?: number): number | string;
+    /** Argument as text (or an error string). */
+    text(index: number, fallback?: string): string;
+    /** Argument as a boolean (or an error string). */
+    boolean(index: number, fallback?: boolean): boolean | string;
+    /** Argument as a date (or an error string). */
+    date(index: number): Date | string;
+    /** Argument as a 2D range (or an error string if it is not a range). */
+    range(index: number): FormulaRange | string;
+    /** Every value of the arguments `from` (default 0) up to `to` (exclusive, default all), ranges flattened. */
+    flatValues(from?: number, to?: number): any[];
+    /**
+     * Numbers among the arguments `from`..`to` (exclusive), as SUM reads them:
+     * text, booleans and blanks are skipped; the first error is returned instead.
+     */
+    numbers(from?: number, to?: number): number[] | string;
+}
+interface FormulaFunctionDefinition {
+    /** Function name; matched case-insensitively. */
     name: string;
-    getRecords(): Array<{
-        id: string;
-        [key: string]: any;
-    }>;
-    getFields(): SpreadsheetDataSourceField[];
-    updateRecord(recordId: string, field: string, value: any): Promise<void> | void;
+    category: FormulaFunctionCategory;
+    description: string;
+    args: FormulaArgumentSpec[];
+    /** Result changes on every recalculation (RAND, NOW, TODAY). */
+    volatile?: boolean;
+    /**
+     * A repeating group may end with one extra argument (SWITCH's `default`).
+     * Otherwise a group must be complete.
+     */
+    allowTrailingArgument?: boolean;
+    evaluate(ctx: FormulaFunctionContext): any;
 }
-
-type FormulaTokenType = 'NUMBER' | 'STRING' | 'BOOLEAN' | 'ERROR' | 'CELL_REF' | 'RANGE' | 'PROPERTY_REF' | 'IDENTIFIER' | 'OPERATOR' | 'LPAREN' | 'RPAREN' | 'COMMA' | 'EOF';
-interface FormulaToken {
-    type: FormulaTokenType;
-    value: string;
-    position: number;
+/**
+ * Adds (or replaces) a formula function. Replacing a built-in is allowed, so
+ * apps can customise behaviour; the change is global.
+ */
+declare function registerFormulaFunction(definition: FormulaFunctionDefinition): void;
+/** Removes a formula function. Returns false if it was not registered. */
+declare function unregisterFormulaFunction(name: string): boolean;
+declare function getFormulaFunction(name: string): FormulaFunctionDefinition | undefined;
+/** All registered functions sorted by name, optionally limited to one category. */
+declare function listFormulaFunctions(category?: FormulaFunctionCategory): FormulaFunctionDefinition[];
+/**
+ * Functions matching `query`, for autocomplete: names starting with the query
+ * first, then names containing it. An empty query lists every function.
+ */
+declare function searchFormulaFunctions(query: string, options?: {
+    limit?: number;
+    category?: FormulaFunctionCategory;
+}): FormulaFunctionDefinition[];
+/**
+ * Index into `def.args` of the spec describing the call argument at
+ * `argIndex`, or -1 if the function takes no argument there.
+ */
+declare function getFormulaArgumentSpecIndex(def: FormulaFunctionDefinition, argIndex: number): number;
+/**
+ * Checks the number of arguments of a call. Returns a message such as
+ * `SUMIF needs at least 2 arguments, but 1 was given.`, or null when valid.
+ */
+declare function checkFormulaArgumentCount(def: FormulaFunctionDefinition, count: number): string | null;
+/** A piece of a rendered signature; `specIndex` is set on argument names. */
+interface FormulaSignaturePart {
+    text: string;
+    specIndex: number | null;
+    active: boolean;
 }
-declare function tokenizeFormula(formula: string): FormulaToken[];
+/**
+ * Renders a signature as parts, e.g. `SUMIFS(` `sum_range` `, ` ... `)`, with
+ * the argument at call position `activeArgIndex` (if any) marked active. A
+ * repeating group is shown twice (`value1, [value2, ...]`); arguments past
+ * the first repetition highlight the second one.
+ */
+declare function getFormulaSignatureParts(nameOrDef: string | FormulaFunctionDefinition, activeArgIndex?: number | null): FormulaSignaturePart[];
+/** Signature string such as `SUMIF(range, criteria, [sum_range])`. */
+declare function getFormulaSignature(nameOrDef: string | FormulaFunctionDefinition): string;
 
-/** Row number used for the open end of whole-column ranges such as `A:A`. */
-declare const WHOLE_COLUMN_END_ROW = 1048576;
-type ASTNode = LiteralNode | CellRefNode | RangeNode | PropertyRefNode | BinaryOpNode | UnaryOpNode | FunctionCallNode;
-interface LiteralNode {
-    type: 'Literal';
-    value: number | string | boolean;
-}
-interface CellRefNode {
-    type: 'CellRef';
-    ref: string;
-    col: string;
-    row: number;
-}
-interface RangeNode {
-    type: 'Range';
-    raw: string;
-    startCol: string;
-    startRow: number;
-    endCol: string;
-    endRow: number;
-}
-interface PropertyRefNode {
-    type: 'PropertyRef';
-    property: string;
-}
-interface BinaryOpNode {
-    type: 'BinaryOp';
-    op: string;
-    left: ASTNode;
-    right: ASTNode;
+/**
+ * Caret analysis for formula autocomplete. The input is scanned tolerantly
+ * (unterminated strings and unbalanced parentheses are expected while typing),
+ * so this never throws.
+ */
+interface FormulaCaretContext {
+    /** The function-name prefix being typed right before the caret, if any. */
+    prefix: {
+        text: string;
+        start: number;
+        end: number;
+    } | null;
+    /** The innermost function call containing the caret, if any. */
+    call: {
+        name: string;
+        /** 0-based index of the argument the caret is in. */
+        argIndex: number;
+        /** Offset of the call's opening parenthesis. */
+        openParen: number;
+    } | null;
 }
-interface UnaryOpNode {
-    type: 'UnaryOp';
-    op: string;
-    argument: ASTNode;
+/** Determines what is being typed at `caret` in `input` (a formula starting with `=`). */
+declare function getFormulaCaretContext(input: string, caret?: number): FormulaCaretContext;
+/** A function suggestion for autocomplete. */
+interface FormulaFunctionSuggestion {
+    name: string;
+    signature: string;
+    description: string;
+    category: FormulaFunctionDefinition['category'];
 }
-interface FunctionCallNode {
-    type: 'FunctionCall';
+interface FormulaActiveCall {
     name: string;
-    args: ASTNode[];
+    signature: string;
+    description: string;
+    /** Signature split into parts, with the active argument marked. */
+    parts: FormulaSignaturePart[];
+    /** 0-based argument index at the caret. */
+    argIndex: number;
+    /** Spec of the active argument, if the function takes an argument there. */
+    argument: FormulaArgumentSpec | null;
 }
-declare function parseCellReference(ref: string): {
-    col: string;
-    row: number;
-};
-declare function parseRange(rangeStr: string): RangeNode;
-declare class FormulaParser {
-    private tokens;
-    private current;
-    constructor(tokens: FormulaToken[]);
-    parse(): ASTNode;
-    private expression;
-    private comparison;
-    private concatenation;
-    private addition;
-    private multiplication;
-    private exponentiation;
-    private unary;
-    private primary;
-    private match;
-    private matchOperator;
-    private check;
-    private advance;
-    private isAtEnd;
-    private peek;
-    private previous;
-    private consume;
+interface FormulaHints {
+    context: FormulaCaretContext;
+    /** Functions matching the name prefix at the caret (empty when not typing a name). */
+    suggestions: FormulaFunctionSuggestion[];
+    /** The known function whose arguments the caret is in. */
+    activeCall: FormulaActiveCall | null;
 }
-declare function parseFormula(formula: string): ASTNode;
+/** Everything formula autocomplete UIs need for `input` with the caret at `caret`. */
+declare function getFormulaHints(input: string, caret?: number, options?: {
+    limit?: number;
+}): FormulaHints;
+/**
+ * Replaces the name prefix at the caret with `NAME(`, returning the new input
+ * and caret position (just inside the parenthesis).
+ */
+declare function applyFormulaSuggestion(input: string, caret: number, name: string): {
+    value: string;
+    caret: number;
+};
 
-interface EvaluationContext {
-    resolveCell?: (col: string, row: number) => any;
-    resolveRange?: (startCol: string, startRow: number, endCol: string, endRow: number) => any[];
-    resolveProperty?: (property: string) => any;
-}
-/** Spreadsheet error values. They propagate through operators and functions. */
-declare const FORMULA_ERRORS: Set<string>;
-declare function isFormulaError(value: unknown): value is string;
-declare function colNameToIndex(col: string): number;
-declare function indexToColName(index: number): string;
-declare class FormulaEvaluator {
-    private context;
-    constructor(context?: EvaluationContext);
-    evaluate(astOrFormula: ASTNode | string): any;
-    private evaluateNode;
-    private callFunction;
-}
+/** Tests one value against a criterion. */
+type FormulaCriteriaPredicate = (value: unknown) => boolean;
+/**
+ * Builds a regular expression from a spreadsheet wildcard pattern: `*` is any
+ * run of characters, `?` any single character, and `~` escapes the next
+ * character (`~*` is a literal asterisk). Matching is case-insensitive.
+ */
+declare function wildcardToRegExp(pattern: string): RegExp;
+/**
+ * Parses a criterion as used by SUMIF, COUNTIFS etc.:
+ * - a number or boolean matches equal values (`5` matches 5 and the text "5");
+ * - text may start with `=`, `<>`, `<`, `<=`, `>` or `>=`. Numeric operands
+ *   compare numbers; text operands compare text case-insensitively;
+ * - `=`/`<>` text operands and plain text support `*` and `?` wildcards;
+ * - `""` and `"="` match blank cells, `"<>"` matches non-blank cells.
+ * Error values in the data never match.
+ */
+declare function parseCriteria(criterion: unknown): FormulaCriteriaPredicate;
 
-interface CellDep {
-    col: string;
-    row: number;
-}
 /**
- * Dependency key for "every cell in column `col`", used by whole-column ranges
- * (`A:A`) instead of expanding a million cell keys.
+ * A subset of spreadsheet number format codes, as used by TEXT():
+ * - numbers: `0`, `#`, `0.00`, `#,##0`, `#,##0.00`, `0%`, `0.0%`, `0.00E+00`,
+ *   literal prefixes/suffixes (`$#,##0.00`, `0.0 "kg"`), and
+ *   `positive;negative;zero` sections;
+ * - dates and times: `yyyy yy mmmm mmm mm m dddd ddd dd d hh h mm ss AM/PM`
+ *   (`m`/`mm` after an hour or before seconds means minutes).
+ * Text values are returned unchanged; unsupported codes are best effort.
  */
-declare const columnDependencyKey: (col: string) => string;
-declare function extractCellDependencies(node: ASTNode): CellDep[];
-declare class DependencyGraph {
-    private dependencies;
-    private dependents;
-    setCellFormula(cellKey: string, formulaStr: string | null): void;
-    /** Removes every registered formula and dependency. */
-    clear(): void;
-    getDependencies(cellKey: string): string[];
-    getDependents(cellKey: string): string[];
-    /**
-     * Detects if there is a cycle containing cellKey.
-     */
-    hasCycle(cellKey: string): boolean;
-    /**
-     * Returns cells affected by updating cellKey in topological order.
-     */
-    getEvaluationOrder(startCellKey: string): {
-        order: string[];
-        hasCycle: boolean;
-    };
+declare function formatValueWithCode(value: unknown, format: string): string | null;
+
+/**
+ * RFC 4180 CSV (and other delimiter-separated values) parsing and
+ * serialization.
+ *
+ * - Fields may be quoted with `"`; a quote inside a quoted field is written
+ *   as `""`. Quoted fields may contain delimiters and line breaks.
+ * - Records end at CRLF, LF or CR. A final line break does not add an empty
+ *   record.
+ * - A leading UTF-8 byte order mark is ignored.
+ * - The parser is lenient like spreadsheet apps: a quote inside an unquoted
+ *   field is kept as text, text after a closing quote is appended, and an
+ *   unterminated quoted field runs to the end of the input.
+ */
+interface CsvParseOptions {
+    /** Field separator. Default `,`. */
+    delimiter?: string;
     /**
-     * Plans a recalculation over `cellKeys` (and, with `includeDependents`, every
-     * cell that transitively depends on them). Returns the keys in evaluation
-     * order (dependencies first) and the set of keys that are part of a cycle,
-     * which must be marked `#CYCLE!` instead of evaluated. Every member of a
-     * cycle is reported, not just the cell that closed it.
+     * Only treat a leading `"` as a quote when the quoted field is closed and
+     * followed by a delimiter or line break; otherwise keep it as text. Used for
+     * clipboard TSV, where plain text may legitimately start with a quote.
      */
-    getEvaluationPlan(cellKeys: Iterable<string>, options?: {
-        includeDependents?: boolean;
-    }): {
-        order: string[];
-        cyclic: Set<string>;
-    };
+    requireWellFormedQuotes?: boolean;
+}
+interface CsvSerializeOptions {
+    /** Field separator. Default `,`. */
+    delimiter?: string;
+    /** Record separator. Default `\r\n` (RFC 4180). */
+    lineEnding?: string;
+    /** Prefix the output with a UTF-8 byte order mark (helps Excel detect UTF-8). */
+    bom?: boolean;
+    /** Quote every field, not only those that need it. */
+    quoteAll?: boolean;
 }
+declare function parseCsv(text: string, options?: CsvParseOptions): string[][];
+/** Quotes `value` when it contains the delimiter, a quote or a line break. */
+declare function escapeCsvField(value: string, delimiter?: string, quoteAll?: boolean): string;
+declare function serializeCsv(rows: ReadonlyArray<ReadonlyArray<unknown>>, options?: CsvSerializeOptions): string;
+/**
+ * Parses tab-separated clipboard text as spreadsheet apps write it: cells
+ * containing line breaks or tabs are quoted CSV-style. A field is only
+ * treated as quoted when it starts with `"` *and* its closing quote ends the
+ * field, so plain text that happens to start with a quote is kept as is.
+ */
+declare function parseTsv(text: string): string[][];
+/**
+ * Serializes values as TSV for the clipboard. Fields containing a tab, line
+ * break or a leading quote are quoted so `parseTsv` (and spreadsheet apps)
+ * read them back as one cell.
+ */
+declare function serializeTsv(rows: ReadonlyArray<ReadonlyArray<unknown>>): string;
 
 /**
- * A row or column insertion/deletion. `index` is the 0-based position of the
- * inserted or deleted row/column.
+ * Pure helpers behind the controller's table operations: value comparison
+ * for sorting, filter matching, group aggregates, autofill series and range
+ * arithmetic. Framework packages use these through `SpreadsheetController`.
  */
-interface StructuralChange {
-    axis: 'row' | 'col';
-    index: number;
-    type: 'insert' | 'delete';
-}
+
+/** Returns `range` with start <= end on both axes. */
+declare function normalizeRange(range: CellRange): CellRange;
+declare function rangeContains(range: CellRange, row: number, col: number): boolean;
+declare function rangesIntersect(a: CellRange, b: CellRange): boolean;
+/** True when `inner` lies entirely inside `outer`. */
+declare function rangeContainsRange(outer: CellRange, inner: CellRange): boolean;
+declare function isSingleCellRange(range: CellRange): boolean;
+declare function isBlankValue(value: unknown): boolean;
+/** The numeric value of a number or numeric string, or null. */
+declare function toNumber(value: unknown): number | null;
+/**
+ * Sort order for cell values: numbers (ascending) before text (natural,
+ * case-insensitive). `desc` reverses that order. Blanks always sort last,
+ * whatever the direction.
+ */
+declare function compareCellValues(a: unknown, b: unknown, direction?: SortDirection): number;
+/** Whether a cell value passes one filter rule. */
+declare function matchesFilterRule(value: unknown, rule: FilterRule): boolean;
+/**
+ * Aggregates values the way category summaries do: `count` counts non-blank
+ * values; the other aggregates use numeric values only and return null when
+ * there are none.
+ */
+declare function aggregateValues(values: unknown[], aggregate: GroupAggregate): number | null;
+/** Removes binary floating point noise (0.1 + 0.2 -> 0.3). */
+declare function roundFloat(value: number): number;
+/**
+ * Extends `source` (raw values in fill order: for an upward or leftward fill,
+ * nearest-first) by `count` values, the way a fill handle does:
+ *
+ * - numbers: one value repeats; two or more continue their linear trend
+ * - ISO dates (`YYYY-MM-DD`): one date counts up by a day; two or more
+ *   continue their day or month step
+ * - text ending in a number ("Item 1"): the number counts up (or continues
+ *   the step of several values with the same prefix/suffix)
+ * - anything else (or a mix) repeats the source cyclically
+ *
+ * Formulas are not handled here; the controller shifts their references.
+ */
+declare function fillSeries(source: string[], count: number): string[];
+type FillDirection = 'down' | 'up' | 'right' | 'left';
+/**
+ * Works out where a fill handle drag ends. Dragging further vertically than
+ * horizontally fills down/up the source's columns; otherwise right/left
+ * across its rows. Returns the full target range (source included), or null
+ * while the pointer is still inside the source.
+ */
+declare function computeFillTarget(source: CellRange, pointer: CellPosition): CellRange | null;
 /**
- * Rewrites the cell and range references in `formula` after a row or column
- * is inserted or deleted, the way spreadsheet apps do: references after the
- * change shift, ranges grow or shrink, and references to a deleted row/column
- * become `#REF!`. Absolute (`$`) markers are kept. String literals, property
- * references and function names are left untouched.
+ * The direction of a fill from `source` into `target` (the extended range),
+ * or null when `target` does not extend `source` along exactly one edge.
  */
-declare function shiftFormulaReferences(formula: string, change: StructuralChange): string;
+declare function getFillDirection(source: CellRange, target: CellRange): FillDirection | null;
 
-declare class DataSourceBinder {
-    private dataSources;
-    register(dataSource: SpreadsheetDataSource): void;
-    unregister(dataSourceId: string): void;
-    getDataSource(id: string): SpreadsheetDataSource | undefined;
-    /**
-     * Generates or reconciles spreadsheet rows from a primary data source.
-     */
-    syncRows(currentRows: SpreadsheetRow[], dataSourceId: string): SpreadsheetRow[];
-    /**
-     * Resolves a record's bound field value.
-     */
-    resolveBoundValue(dataSourceId: string, recordId: string, field: string): any;
-    /**
-     * Dispatches an update to the underlying data source.
-     */
-    commitBoundValue(dataSourceId: string, recordId: string, field: string, value: any): Promise<void>;
+/**
+ * The spreadsheet's table context menu, defined once so the React and Svelte
+ * editors show the same actions. Frameworks render the items and call
+ * `run()`; the controller's change listeners refresh their state.
+ */
+
+interface SpreadsheetMenuItem {
+    id: string;
+    label: string;
+    disabled?: boolean;
+    /** Draw a divider before this item. */
+    separatorBefore?: boolean;
+    run: () => void;
 }
+/**
+ * Menu items for a right-click on `cell`. When the cell is inside the
+ * selection, range actions (hide, merge, transpose) apply to the selection;
+ * otherwise to the clicked cell.
+ */
+declare function getSpreadsheetMenuItems(controller: SpreadsheetController, cell: CellPosition): SpreadsheetMenuItem[];
+
+/**
+ * Controller methods the React and Svelte spreadsheet bindings expose as-is,
+ * so both frameworks offer the same table operations. They need no extra
+ * state syncing: the controller reports changes through `onDocumentChange`
+ * and `onSelectionChange`.
+ */
+declare const SPREADSHEET_TABLE_ACTIONS: readonly ["sortRows", "getFilterState", "setFilterRules", "addFilterRule", "updateFilterRule", "removeFilterRule", "clearFilters", "setFiltersEnabled", "toggleFilters", "setHeaderRowCount", "setFooterRowCount", "setHeaderColumnCount", "setFrozenRowCount", "setFrozenColumnCount", "hideRows", "unhideRows", "hideColumns", "unhideColumns", "unhideAll", "getMerges", "getMergeAt", "mergeCells", "unmergeCells", "autofill", "groupRowsBy", "ungroupRows", "setGroupSummary", "setGroupCollapsed", "toggleGroupCollapsed", "getGroups", "transposeRange", "exportToCsv", "importFromCsv", "copyToClipboardData", "pasteClipboardData"];
+type SpreadsheetTableActionName = (typeof SPREADSHEET_TABLE_ACTIONS)[number];
+type SpreadsheetTableActions = Pick<SpreadsheetController, SpreadsheetTableActionName>;
+/** The table operations of `controller`, bound so they can be passed around. */
+declare function bindSpreadsheetTableActions(controller: SpreadsheetController): SpreadsheetTableActions;
+
+/**
+ * `spreadsheet` import adapters for the import registry: CSV and TSV files
+ * parsed with the RFC 4180 parser in `csv.ts`.
+ *
+ * They are not registered by default (the default registry only knows
+ * `document` adapters). Registries are passed in explicitly so this entry
+ * point does not pull in the document adapters (markdown, TipTap):
+ *
+ *   registerSpreadsheetImportAdapters(defaultImportRegistry);
+ *   await importFileIntoSpreadsheet(controller, file, { registry: defaultImportRegistry });
+ */
 
-interface SpreadsheetControllerOptions {
-    document?: Partial<SpreadsheetDocument>;
-    dataSources?: SpreadsheetDataSource[];
-    primaryDataSourceId?: string;
-    onDocumentChange?: (doc: SpreadsheetDocument) => void;
-    onSelectionChange?: (activeCell: CellCoordinate | null, range: CellRange | null) => void;
-    onCellCommit?: (rowId: string, colId: string, raw: string, value: any) => void;
+/** Result of every `spreadsheet` adapter. */
+interface SpreadsheetImport {
+    /** Parsed records, one array of raw cell inputs per row. */
+    rows: string[][];
+    /** Field separator the file was parsed with. */
+    delimiter: string;
 }
-declare class SpreadsheetController {
-    document: SpreadsheetDocument;
-    activeCell: CellCoordinate | null;
-    selectedRange: CellRange | null;
-    editingCell: CellCoordinate | null;
-    draftValue: string;
-    readonly binder: DataSourceBinder;
-    readonly depGraph: DependencyGraph;
-    readonly evaluator: FormulaEvaluator;
-    private primaryDataSourceId?;
-    private onDocumentChange?;
-    private onSelectionChange?;
-    private onCellCommit?;
-    private undoStack;
-    private redoStack;
-    private isApplyingHistory;
-    private batching;
-    private pendingCommits;
-    private evaluatingRowIndex;
-    constructor(options?: SpreadsheetControllerOptions);
-    loadDocument(document: SpreadsheetDocument): void;
-    registerDataSource(ds: SpreadsheetDataSource): void;
-    setPrimaryDataSource(dataSourceId: string | undefined): void;
-    syncWithDataSource(): void;
-    private recomputeRowIndices;
-    getColumn(colIdOrKey: string): SpreadsheetColumn | undefined;
-    getRow(rowIdOrIndex: string | number): SpreadsheetRow | undefined;
-    getCell(rowId: string, colId: string): CellData;
-    /** Value of a cell with no stored data: bound record value, column formula, or blank. */
-    private getDerivedCell;
-    setCellValue(rowId: string, colId: string, raw: string): void;
-    private getCellKey;
-    /**
-     * Recalculates a cell and everything that depends on it, in dependency
-     * order. Every cell in a reference cycle is marked `#CYCLE!`.
-     */
-    recalculateCell(rowId: string, colId: string): void;
-    /**
-     * Rebuilds the dependency graph from scratch and recalculates every formula
-     * in dependency order.
-     */
-    recalculateAll(): void;
-    private runEvaluationPlan;
-    private locateCellKey;
-    private markCycle;
-    private evalSingleCellByKey;
-    private resolveCellByCoord;
-    private resolveRangeByCoords;
-    private resolveCurrentRowProperty;
-    selectCell(row: number, col: number, extendSelection?: boolean): void;
-    selectRange(range: CellRange): void;
-    startEditing(row?: number, col?: number, initialValue?: string): void;
-    commitEditing(valueToCommit?: string): void;
-    cancelEditing(): void;
-    moveCursor(direction: 'up' | 'down' | 'left' | 'right', extendSelection?: boolean): void;
-    insertColumn(index: number, config?: Partial<SpreadsheetColumn>): void;
-    deleteColumn(colId: string): void;
-    insertRow(index: number, config?: Partial<SpreadsheetRow>): void;
-    deleteRow(rowId: string): void;
-    private generateId;
-    /**
-     * Rewrites references in every cell formula (and, for column changes, every
-     * column formula) so they keep pointing at the same cells.
-     */
-    private shiftReferences;
-    setColumnWidth(colId: string, width: number): void;
-    autoFitColumnWidth(colId: string, customWidth?: number): void;
-    /**
-     * Exports cell values as TSV: the whole sheet, or only `range` (e.g. the
-     * current selection) when given.
-     */
-    exportToTsv(range?: CellRange | null): string;
-    /**
-     * Pastes tab-separated values starting at (startRow, startCol), adding rows
-     * and columns as needed. The whole paste is a single undo step.
-     */
-    importFromTsv(tsvData: string, startRow?: number, startCol?: number): void;
-    private recordSnapshot;
-    undo(): void;
-    redo(): void;
-    private notifyChange;
+type SpreadsheetImportAdapter = ImportAdapter<SpreadsheetImport>;
+declare const csvImportAdapter: SpreadsheetImportAdapter;
+declare const tsvImportAdapter: SpreadsheetImportAdapter;
+declare const SPREADSHEET_IMPORT_ADAPTERS: readonly SpreadsheetImportAdapter[];
+/** Registers the CSV and TSV adapters; returns a function that unregisters them. */
+declare function registerSpreadsheetImportAdapters(registry: ImportAdapterRegistry): () => void;
+interface ImportFileIntoSpreadsheetOptions {
+    /** Registry to resolve the adapter from (e.g. `defaultImportRegistry`). */
+    registry: ImportAdapterRegistry;
+    /** Force an adapter instead of matching by file name / MIME type. */
+    adapterId?: string;
+    fileName?: string;
+    mimeType?: string;
+    /** Top-left cell to write to (0-based). Default A1. */
+    startRow?: number;
+    startCol?: number;
 }
+/**
+ * Imports a CSV/TSV file (or any registered `spreadsheet` adapter that
+ * returns `SpreadsheetImport`) into the controller as one undoable change.
+ */
+declare function importFileIntoSpreadsheet(controller: SpreadsheetController, input: ImportInput, options: ImportFileIntoSpreadsheetOptions): Promise<ImportOutcome<SpreadsheetImport>>;
 
-export { type ASTNode, type BinaryOpNode, type CellCoordinate, type CellData, type CellDep, type CellFormat, type CellRange, type CellRefNode, type ColumnBinding, type ColumnType, DataSourceBinder, DependencyGraph, type EvaluationContext, FORMULA_ERRORS, FormulaEvaluator, FormulaParser, type FormulaToken, type FormulaTokenType, type FunctionCallNode, type LiteralNode, type PropertyRefNode, type RangeNode, type RowType, type SpreadsheetColumn, SpreadsheetController, type SpreadsheetControllerOptions, type SpreadsheetDataSource, type SpreadsheetDataSourceField, type SpreadsheetDocument, type SpreadsheetRow, type StructuralChange, type UnaryOpNode, WHOLE_COLUMN_END_ROW, colNameToIndex, columnDependencyKey, extractCellDependencies, indexToColName, isFormulaError, parseCellReference, parseFormula, parseRange, shiftFormulaReferences, tokenizeFormula };
+export { ASTNode, CellPosition, CellRange, type CsvParseOptions, type CsvSerializeOptions, type FillDirection, FilterRule, type FormulaActiveCall, type FormulaArgument, type FormulaArgumentSpec, type FormulaArgumentType, type FormulaCaretContext, type FormulaCriteriaPredicate, FormulaErrorCode, type FormulaFunctionCategory, type FormulaFunctionContext, type FormulaFunctionDefinition, type FormulaFunctionSuggestion, type FormulaHints, FormulaRange, type FormulaSignaturePart, GroupAggregate, type ImportFileIntoSpreadsheetOptions, SPREADSHEET_IMPORT_ADAPTERS, SPREADSHEET_TABLE_ACTIONS, SortDirection, SpreadsheetController, type SpreadsheetImport, type SpreadsheetImportAdapter, type SpreadsheetMenuItem, type SpreadsheetTableActionName, type SpreadsheetTableActions, aggregateValues, applyFormulaSuggestion, bindSpreadsheetTableActions, checkFormulaArgumentCount, compareCellValues, computeFillTarget, csvImportAdapter, escapeCsvField, fillSeries, formatValueWithCode, getFillDirection, getFormulaArgumentSpecIndex, getFormulaCaretContext, getFormulaFunction, getFormulaHints, getFormulaSignature, getFormulaSignatureParts, getSpreadsheetMenuItems, importFileIntoSpreadsheet, isBlankValue, isSingleCellRange, listFormulaFunctions, matchesFilterRule, normalizeRange, parseCriteria, parseCsv, parseTsv, rangeContains, rangeContainsRange, rangesIntersect, registerFormulaFunction, registerSpreadsheetImportAdapters, roundFloat, searchFormulaFunctions, serializeCsv, serializeTsv, toNumber, tsvImportAdapter, unregisterFormulaFunction, wildcardToRegExp };