@pixerate/editor 0.24.0 → 0.26.0

package/dist/spreadsheet/index.d.cts

@@ -1,6 +1,64 @@
-import { A as ASTNode, r as FormulaErrorCode, v as FormulaRange, a as CellData, c as CellFormat, G as GroupAggregate, O as SortDirection, e as CellRange, d as CellPosition, p as FilterRule, S as SpreadsheetController } from '../controller-BhLLAoi8.cjs';
-export { B as BinaryOpNode, C as CellCoordinate, b as CellDep, 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, M as MAX_FORMULA_ARRAY_SIZE, N as NameNode, H as NewFilterRule, P as ParsedSpreadsheetClipboard, I as PropertyRefNode, R as RangeNode, J as RowType, K as SPREADSHEET_CLIPBOARD_MIME, Q as SortKey, T as SpillRefNode, U as SpreadsheetCellSpan, V as SpreadsheetClipboardCell, W as SpreadsheetClipboardData, X as SpreadsheetClipboardPayload, Y as SpreadsheetClipboardSource, Z as SpreadsheetColumn, _ as SpreadsheetControllerOptions, $ as SpreadsheetDataSource, a0 as SpreadsheetDataSourceField, a1 as SpreadsheetDocument, a2 as SpreadsheetFilterState, a3 as SpreadsheetGrouping, a4 as SpreadsheetRow, a5 as SpreadsheetRowGroup, a6 as SpreadsheetRowSection, a7 as SpreadsheetSpill, a8 as SpreadsheetTableSettings, a9 as SpreadsheetViewColumn, aa as SpreadsheetViewModel, ab as SpreadsheetViewRow, ac as StructuralChange, ad as UnaryOpNode, ae as WHOLE_COLUMN_END_ROW, af as buildSpreadsheetView, ag as colNameToIndex, ah as columnDependencyKey, ai as compareNumbers, aj as compareValues, ak as computeRowGroups, al as createSpreadsheetClipboardData, am as describeFormulaError, an as extractCellDependencies, ao as getRowSection, ap as getTableSections, aq as indexToColName, ar as isFormulaError, as as mapFormulaReferences, at as numberToText, au as offsetFormulaReferences, av as parseCellReference, aw as parseFormula, ax as parseHtmlTable, ay as parseRange, az as readSpreadsheetClipboard, aA as rebaseClipboardRows, aB as remapFormulaReferences, aC as rowPassesFilters, aD as serializeHtmlTable, aE as shiftFormulaReferences, aF as sortCompareValues, aG as tokenizeFormula } from '../controller-BhLLAoi8.cjs';
-import { I as ImportAdapterRegistry, c as ImportAdapter, h as ImportInput, a as ImportOutcome } from '../registry-GJI4gToU.cjs';
+import { A as ASTNode, P as FormulaErrorCode, V as FormulaRange, a as CellData, c as CellFormat, p as ConditionalFormatSheet, n as ConditionalFormatOverlay, o as ConditionalFormatRule, j as ConditionalCellFormat, t as ConditionalFormatValue, l as ConditionalFormatIconSet, F as DataValidationRule, q as ConditionalFormatStyle, r as ConditionalFormatTimePeriod, e as CellRange, y as DataValidationErrorStyle, z as DataValidationOperator, H as DataValidationType, a8 as NewConditionalFormatRule, G as DataValidationSheet, d as CellPosition, E as DataValidationResult, $ as GroupAggregate, aj as SortDirection, N as FilterRule, S as SpreadsheetController, aw as SpreadsheetDefinedName, aP as StructuralChange, aM as SpreadsheetViewModel } from '../controller-CxXGOEmy.cjs';
+export { B as BinaryOpNode, C as CellCoordinate, b as CellDep, f as CellRefNode, g as CellValueReader, h as ColumnBinding, i as ColumnType, k as ConditionalFormatCondition, m as ConditionalFormatOperator, s as ConditionalFormatType, u as CsvExportOptions, v as CsvImportOptions, D as DEFAULT_COLUMN_WIDTH, w as DEFAULT_ROW_HEIGHT, x as DataSourceBinder, I as DependencyGraph, J as DependencyIndexStats, K as EvaluationContext, L as FORMULA_ERRORS, M as FilterOperator, O as FormulaDiagnostic, Q as FormulaEvaluationResult, R as FormulaEvaluator, T as FormulaNameDefinition, U as FormulaParser, W as FormulaReferenceFilter, X as FormulaReferenceInfo, Y as FormulaToken, Z as FormulaTokenType, _ as FunctionCallNode, a0 as GroupSummary, a1 as IntervalIndex, a2 as InvokeNode, a3 as LiteralNode, a4 as MAX_FORMULA_ARRAY_SIZE, a5 as MissingNode, a6 as NameDep, a7 as NameNode, a9 as NewDataValidationRule, aa as NewFilterRule, ab as ParsedSpreadsheetClipboard, ac as PropertyRefNode, ad as RangeNode, ae as RangeResolveOptions, af as ReferenceDep, ag as RowType, ah as SPREADSHEET_CLIPBOARD_MIME, ai as SheetQualifier, ak as SortKey, al as SpillRefNode, am as SpreadsheetCellSpan, an as SpreadsheetClipboardCell, ao as SpreadsheetClipboardData, ap as SpreadsheetClipboardPayload, aq as SpreadsheetClipboardSource, ar as SpreadsheetColumn, as as SpreadsheetCommitResult, at as SpreadsheetControllerOptions, au as SpreadsheetDataSource, av as SpreadsheetDataSourceField, ax as SpreadsheetDocument, ay as SpreadsheetFilterState, az as SpreadsheetGrouping, aA as SpreadsheetNameInfo, aB as SpreadsheetNameScope, aC as SpreadsheetRecalculationStats, aD as SpreadsheetRow, aE as SpreadsheetRowGroup, aF as SpreadsheetRowSection, aG as SpreadsheetSheetInfo, aH as SpreadsheetSpill, aI as SpreadsheetTableSettings, aJ as SpreadsheetValidationAction, aK as SpreadsheetValidationPrompt, aL as SpreadsheetViewColumn, aN as SpreadsheetViewRow, aO as SpreadsheetWorkbook, aQ as UnaryOpNode, aR as WHOLE_COLUMN_END_ROW, aS as buildSpreadsheetView, aT as colNameToIndex, aU as columnDependencyKey, aV as compareNumbers, aW as compareValues, aX as computeRowGroups, aY as createSpreadsheetClipboardData, aZ as deleteSheetInFormula, a_ as describeFormulaError, a$ as extractCellDependencies, b0 as extractNameDependencies, b1 as extractReferenceDependencies, b2 as formatSheetPrefix, b3 as formulaIdentifiers, b4 as getRowSection, b5 as getTableSections, b6 as indexToColName, b7 as isFormulaError, b8 as mapFormulaReferences, b9 as numberToText, ba as offsetFormulaReferences, bb as parseCellReference, bc as parseFormula, bd as parseHtmlTable, be as parseRange, bf as quoteSheetName, bg as rangeDependencyKey, bh as readSpreadsheetClipboard, bi as rebaseClipboardRows, bj as remapFormulaReferences, bk as renameNameInFormula, bl as renameSheetInFormula, bm as rowPassesFilters, bn as serializeHtmlTable, bo as sheetNameNeedsQuotes, bp as shiftFormulaReferences, bq as sortCompareValues, br as tokenizeFormula } from '../controller-CxXGOEmy.cjs';
+import { I as ImportAdapterRegistry, b as ImportAdapter, h as ImportInput, a as ImportOutcome } from '../registry-CEgwXED1.cjs';
+
+/**
+ * LAMBDA values and the lexical environments of LET and LAMBDA variables.
+ */
+
+/**
+ * Variables of one LET or LAMBDA call. Environments form a chain: a lambda
+ * keeps the environment it was created in (a closure), so its body sees the
+ * LET variables around its definition, not those of its caller.
+ */
+interface FormulaEnvironment {
+    /** Upper-case variable name → value. */
+    readonly vars: Map<string, any>;
+    /** LAMBDA parameters whose argument was left out (for ISOMITTED). */
+    readonly omitted?: Set<string>;
+    readonly parent: FormulaEnvironment | null;
+}
+/**
+ * A function value created by `LAMBDA(params…, body)`, or a built-in function
+ * passed by name (`BYROW(A1:C3, SUM)`). Lambdas can be stored in LET
+ * variables and defined names and passed to MAP, REDUCE, SCAN, BYROW, BYCOL
+ * and MAKEARRAY; a cell whose result is an uncalled lambda shows `#CALC!`.
+ */
+declare class FormulaLambda {
+    /** Upper-case parameter names. */
+    readonly params: readonly string[];
+    /** The calculation; null for a native (built-in) function. */
+    readonly body: ASTNode | null;
+    /** The environment the lambda was created in. */
+    readonly env: FormulaEnvironment | null;
+    /** The sheet unqualified references in the body refer to (a sheet-scoped name's sheet). */
+    readonly sheet?: string | undefined;
+    /** Implementation of a built-in function passed by name. */
+    readonly native?: ((args: any[]) => any) | undefined;
+    /** Display name, e.g. `SUM` or `LAMBDA`. */
+    readonly label: string;
+    constructor(
+    /** Upper-case parameter names. */
+    params: readonly string[], 
+    /** The calculation; null for a native (built-in) function. */
+    body: ASTNode | null, 
+    /** The environment the lambda was created in. */
+    env: FormulaEnvironment | null, 
+    /** The sheet unqualified references in the body refer to (a sheet-scoped name's sheet). */
+    sheet?: string | undefined, 
+    /** Implementation of a built-in function passed by name. */
+    native?: ((args: any[]) => any) | undefined, 
+    /** Display name, e.g. `SUM` or `LAMBDA`. */
+    label?: string);
+    toString(): string;
+}
+declare const isFormulaLambda: (value: unknown) => value is FormulaLambda;
+/**
+ * Deepest nesting of LAMBDA calls (recursion through named lambdas). Deeper
+ * calls return `#NUM!`, as in Excel. The JavaScript stack may run out first
+ * on small stacks; that is reported as `#NUM!` too.
+ */
+declare const MAX_LAMBDA_DEPTH = 1000;
 
 type FormulaFunctionCategory = 'math' | 'statistical' | 'logical' | 'text' | 'lookup' | 'date' | 'information';
 /** What an argument expects. Used for documentation, hints and messages. */
@@ -158,6 +216,20 @@ interface FormulaFunctionSuggestion {
     signature: string;
     description: string;
     category: FormulaFunctionDefinition['category'];
+    /**
+     * `name` for a defined name (accepting it inserts the name as defined,
+     * followed by `(` only for a LAMBDA name); unset for functions.
+     */
+    kind?: 'name';
+    /** For a defined name: it holds a LAMBDA, so it is called like a function. */
+    isLambda?: boolean;
+}
+/** A defined name offered by autocomplete (see `SpreadsheetController.getNameSuggestions`). */
+interface FormulaNameSuggestionSource {
+    name: string;
+    description?: string;
+    /** A LAMBDA name is called like a function. */
+    isLambda?: boolean;
 }
 interface FormulaActiveCall {
     name: string;
@@ -180,12 +252,17 @@ interface FormulaHints {
 /** Everything formula autocomplete UIs need for `input` with the caret at `caret`. */
 declare function getFormulaHints(input: string, caret?: number, options?: {
     limit?: number;
+    names?: readonly FormulaNameSuggestionSource[];
 }): FormulaHints;
 /**
  * Replaces the name prefix at the caret with `NAME(`, returning the new input
- * and caret position (just inside the parenthesis).
+ * and caret position (just inside the parenthesis). Given a defined-name
+ * suggestion (`kind: 'name'`), the name keeps its case and gets a `(` only
+ * when it holds a LAMBDA; `call: false` inserts any name without `(`.
  */
-declare function applyFormulaSuggestion(input: string, caret: number, name: string): {
+declare function applyFormulaSuggestion(input: string, caret: number, suggestion: string | Pick<FormulaFunctionSuggestion, 'name' | 'kind' | 'isLambda'>, options?: {
+    call?: boolean;
+}): {
     value: string;
     caret: number;
 };
@@ -402,6 +479,214 @@ declare function parseCellInput(input: string): ParsedCellInput;
  */
 declare function parseNumberText(text: string): number | null;
 
+/**
+ * The number a value counts as for scales, bars, icons, top/bottom and
+ * averages: numbers, and dates (ISO text) as their serial number. Text,
+ * booleans, blanks and errors are not numbers.
+ */
+declare function conditionalFormatNumber(value: unknown): number | null;
+/** Blends two colours: `t` 0 is `a`, 1 is `b`. */
+declare function blendConditionalFormatColors(a: string, b: string, t: number): string;
+/** Excel's default icon thresholds: percent 0, 33, 67 for three icons. */
+declare function defaultIconThresholds(set: string): ConditionalFormatValue[];
+/** An overlay with no formatted cells. */
+declare const EMPTY_CONDITIONAL_FORMAT_OVERLAY: ConditionalFormatOverlay;
+/**
+ * Evaluates conditional formats and keeps what it needs to re-evaluate only
+ * the affected cells after an edit (`update`). Rules are applied in order
+ * (the first has the highest priority): every matching rule adds the parts
+ * of its style that higher-priority rules left unset, and a matching rule
+ * with `stopIfTrue` hides lower-priority rules. Colour scales, data bars and
+ * icon sets apply to numbers only and never stop other rules.
+ */
+declare class ConditionalFormatEngine {
+    private sheet;
+    private cells;
+    private stats;
+    private rulesKey;
+    private current;
+    constructor(sheet: ConditionalFormatSheet);
+    /** Replaces the sheet accessor (e.g. after rows or columns were added). */
+    setSheet(sheet: ConditionalFormatSheet): void;
+    /** The last evaluated overlay. */
+    get overlay(): ConditionalFormatOverlay;
+    /** Evaluates every rule over every cell it applies to. */
+    evaluate(rules: ConditionalFormatRule[]): ConditionalFormatOverlay;
+    /**
+     * Re-evaluates after the values of `changed` cells changed (the edited
+     * cells and the formulas that depend on them). Rules that look at the whole
+     * range (scales, bars, icons, top/bottom, average, duplicates) are
+     * re-evaluated over their range when a changed cell is inside it; formula
+     * rules always are, since their formulas may read any cell; other rules
+     * only at the changed cells. Falls back to `evaluate` when the rules
+     * changed.
+     */
+    update(rules: ConditionalFormatRule[], changed: Iterable<{
+        row: number;
+        col: number;
+    }>): ConditionalFormatOverlay;
+    private statsFor;
+    private evalFormula;
+    private threshold;
+    /** The operand of a `cellIs` rule: a formula result, or typed input. */
+    private operand;
+    /** Combines every rule that applies to (row, col). */
+    computeLook(rules: ConditionalFormatRule[], row: number, col: number): ConditionalCellFormat | undefined;
+    /**
+     * Checks one rule: returns its style when it matches, 'look' when it set a
+     * scale fill, bar or icon on `out`, or null.
+     */
+    private matchRule;
+}
+/** Whether serial day `d` falls in `period` relative to `today`. */
+declare function matchesTimePeriod(period: string, d: number, today: Date): boolean;
+/** Evaluates `rules` over a sheet: the conditional look of every formatted cell. */
+declare function evaluateConditionalFormats(sheet: ConditionalFormatSheet, rules: ConditionalFormatRule[]): ConditionalFormatOverlay;
+
+/**
+ * Glyphs for conditional-format icon sets, so React and Svelte draw the same
+ * icons without image assets. Index 0 is the lowest icon.
+ */
+
+interface ConditionalFormatIconGlyph {
+    /** Text glyph to draw. */
+    glyph: string;
+    /** CSS colour of the glyph. */
+    color: string;
+    /** Accessible name, e.g. "Up arrow". */
+    label: string;
+}
+/** Names of the built-in icon sets. */
+declare const CONDITIONAL_FORMAT_ICON_SETS: ConditionalFormatIconSet[];
+/** Number of icons in a set (`3Arrows` → 3), always 3 to 5. */
+declare function conditionalFormatIconCount(set: string): number;
+/** The glyph of icon `index` of `set` (unknown sets use traffic lights). */
+declare function getConditionalFormatIcon(set: string, index: number): ConditionalFormatIconGlyph;
+
+/**
+ * One-line descriptions of rules for the conditional formatting and data
+ * validation managers, shared by React and Svelte.
+ */
+
+/** E.g. `Cell value > 100`, `Color scale (min → P50 → max)`, `Formula: =$B2>10`. */
+declare function describeConditionalFormat(rule: ConditionalFormatRule): string;
+/** E.g. `Whole number between 1 and 10`, `List: Low,Medium,High`, `Custom: =A1>0`. */
+declare function describeDataValidation(rule: DataValidationRule): string;
+
+/**
+ * Ready-made rules for the conditional formatting and data validation
+ * managers and the context menu, so React and Svelte offer the same choices.
+ */
+
+/** Excel's highlight styles. */
+declare const CONDITIONAL_FORMAT_STYLE_PRESETS: Array<{
+    id: string;
+    label: string;
+    style: ConditionalFormatStyle;
+}>;
+declare const DEFAULT_CONDITIONAL_FORMAT_STYLE: ConditionalFormatStyle;
+type ConditionalFormatPresetKind = 'greaterThan' | 'lessThan' | 'between' | 'equal' | 'textContains' | 'dateOccurring' | 'duplicate' | 'unique' | 'top10' | 'bottom10' | 'aboveAverage' | 'belowAverage' | 'blanks' | 'errors' | 'formula' | 'colorScale2' | 'colorScale3' | 'dataBar' | 'iconSet';
+/** Inputs a preset needs, besides the ranges. */
+type ConditionalFormatPresetField = 'value' | 'value2' | 'text' | 'formula' | 'rank' | 'period' | 'iconSet' | 'color';
+interface ConditionalFormatPresetInfo {
+    kind: ConditionalFormatPresetKind;
+    label: string;
+    fields: ConditionalFormatPresetField[];
+    /** Whether the rule takes a highlight style (scales, bars and icons don't). */
+    usesStyle: boolean;
+}
+declare const CONDITIONAL_FORMAT_PRESETS: ConditionalFormatPresetInfo[];
+declare const CONDITIONAL_FORMAT_TIME_PERIODS: Array<{
+    period: ConditionalFormatTimePeriod;
+    label: string;
+}>;
+interface ConditionalFormatPresetInput {
+    kind: ConditionalFormatPresetKind;
+    ranges: CellRange[];
+    value?: string;
+    value2?: string;
+    text?: string;
+    formula?: string;
+    rank?: number;
+    period?: ConditionalFormatTimePeriod;
+    iconSet?: ConditionalFormatIconSet;
+    /** Data bar colour. */
+    color?: string;
+    /** Highlight style (default light red fill, dark red text). */
+    style?: ConditionalFormatStyle;
+    stopIfTrue?: boolean;
+}
+/** Builds a rule from a preset and its inputs. */
+declare function createConditionalFormatRule(input: ConditionalFormatPresetInput): NewConditionalFormatRule;
+declare const DATA_VALIDATION_TYPE_OPTIONS: Array<{
+    type: DataValidationType;
+    label: string;
+}>;
+declare const DATA_VALIDATION_OPERATOR_OPTIONS: Array<{
+    operator: DataValidationOperator;
+    label: string;
+}>;
+declare const DATA_VALIDATION_ERROR_STYLE_OPTIONS: Array<{
+    style: DataValidationErrorStyle;
+    label: string;
+}>;
+
+/**
+ * CSS for the conditional look of a cell, shared by the React and Svelte
+ * grids (React uses the objects, Svelte the `style` strings).
+ */
+
+interface ConditionalFormatCss {
+    background?: string;
+    color?: string;
+    fontWeight?: string;
+    fontStyle?: string;
+    textDecoration?: string;
+}
+/**
+ * Black or white, whichever reads better on `fill` (`#rgb` / `#rrggbb`), or
+ * undefined for other colour syntaxes.
+ */
+declare function conditionalFormatContrastColor(fill: string): string | undefined;
+/**
+ * Fill, font colour and emphasis of a cell (no data bar or icon). A fill
+ * without a font colour of its own gets black or white text, so the value
+ * stays readable whatever the theme's text colour (Excel's fills assume
+ * dark text).
+ */
+declare function getConditionalFormatCss(format: ConditionalCellFormat | undefined): ConditionalFormatCss;
+/** The bar element of a data bar: absolutely placed from the cell's left edge. */
+declare function getDataBarCss(bar: NonNullable<ConditionalCellFormat['dataBar']>): Record<string, string>;
+/** `{ fontWeight: '700' }` → `font-weight: 700;` for `style` attributes. */
+declare function conditionalFormatStyleString(css: Record<string, string | undefined> | ConditionalFormatCss): string;
+
+/** Excel's message when a rule has no error message of its own. */
+declare const DEFAULT_DATA_VALIDATION_MESSAGE = "This value doesn't match the data validation restrictions defined for this cell.";
+declare const DEFAULT_DATA_VALIDATION_TITLE = "Invalid value";
+/** The rule that applies to (row, col): the first one containing it. */
+declare function findDataValidation(rules: DataValidationRule[] | undefined, row: number, col: number): DataValidationRule | undefined;
+/**
+ * The items of a list rule: literal (`Low, Medium, High`, optionally in
+ * quotes) or read from a range or formula (`=$H$1:$H$5`), blanks skipped.
+ * Formulas are evaluated at the range's top-left cell.
+ */
+declare function getValidationListValues(sheet: DataValidationSheet, rule: DataValidationRule): string[];
+/**
+ * Checks `input` typed into (row, col) against the cell's rule. Typed input
+ * is parsed like a cell commit (`10%` is 0.1, `3/4/2026` a date); a formula
+ * is checked through its result. Custom and bound formulas are relative to
+ * the range's top-left cell and see the value being entered. Blank input is
+ * valid unless `ignoreBlank` is false; rules with `showErrorAlert: false`
+ * accept anything.
+ */
+declare function validateCellInput(sheet: DataValidationSheet, rules: DataValidationRule[] | undefined, row: number, col: number, input: string): DataValidationResult;
+/**
+ * Cells whose current value breaks their rule ("circle invalid data").
+ * Blank cells are skipped, as are `any` rules. Alerts being off does not
+ * matter here. Each cell is listed once, rule by rule, in row-major order.
+ */
+declare function findInvalidCells(sheet: DataValidationSheet, rules: DataValidationRule[] | undefined): CellPosition[];
+
 /**
  * Common number formats offered by the "Format cells" menu, and the mapping
  * between format codes and the coarser `CellFormat` kinds.
@@ -566,14 +851,24 @@ interface SpreadsheetMenuItem {
         label: string;
         defaultValue?: string;
     };
+    /** Ask the user to confirm before running (e.g. deleting a sheet); the message to show. */
+    confirm?: string;
+    /**
+     * Opens one of the editor's panels instead of running an action: the
+     * editors open it (`run` does nothing).
+     */
+    panel?: SpreadsheetPanelId;
     run: (input?: string) => void;
 }
+/** Panels the spreadsheet editors can open from the context menu. */
+type SpreadsheetPanelId = 'conditionalFormatting' | 'dataValidation';
 /**
- * Runs a menu item the way the editors do: an item with `input` first asks
- * for text with `ask` (default `window.prompt`) and is skipped when that is
- * cancelled. Returns whether `run` was called.
+ * Runs a menu item the way the editors do: an item with `confirm` first asks
+ * for confirmation with `confirm` (default `window.confirm`), an item with
+ * `input` asks for text with `ask` (default `window.prompt`); either is
+ * skipped when cancelled. Returns whether `run` was called.
  */
-declare function runSpreadsheetMenuItem(item: SpreadsheetMenuItem, ask?: (label: string, defaultValue: string) => string | null | undefined): boolean;
+declare function runSpreadsheetMenuItem(item: SpreadsheetMenuItem, ask?: (label: string, defaultValue: string) => string | null | undefined, confirm?: (message: string) => boolean): boolean;
 /**
  * Where to place a `position: fixed` menu opened at `point` so it stays inside
  * the viewport: it flips to the left of / above the pointer when it would
@@ -608,7 +903,7 @@ declare function getSpreadsheetMenuItems(controller: SpreadsheetController, cell
  * 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", "setCellNumberFormat", "setColumnNumberFormat", "exportToCsv", "importFromCsv", "copyToClipboardData", "pasteClipboardData"];
+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", "setCellNumberFormat", "setColumnNumberFormat", "exportToCsv", "importFromCsv", "copyToClipboardData", "pasteClipboardData", "getConditionalFormats", "addConditionalFormat", "updateConditionalFormat", "deleteConditionalFormat", "moveConditionalFormat", "clearConditionalFormats", "getConditionalFormatOverlay", "getConditionalFormat", "getDataValidations", "getDataValidationAt", "addDataValidation", "updateDataValidation", "deleteDataValidation", "clearDataValidation", "validateCellInput", "getValidationListValues", "findInvalidCells", "setInvalidDataCircles", "getInvalidDataCircles", "isInvalidDataCircled"];
 type SpreadsheetTableActionName = (typeof SPREADSHEET_TABLE_ACTIONS)[number];
 type SpreadsheetTableActions = Pick<SpreadsheetController, SpreadsheetTableActionName>;
 /** The table operations of `controller`, bound so they can be passed around. */
@@ -649,6 +944,8 @@ interface ImportFileIntoSpreadsheetOptions {
     /** Top-left cell to write to (0-based). Default A1. */
     startRow?: number;
     startCol?: number;
+    /** Sheet (id or name) to import into; default the active sheet. */
+    sheet?: string;
 }
 /**
  * Imports a CSV/TSV file (or any registered `spreadsheet` adapter that
@@ -656,4 +953,230 @@ interface ImportFileIntoSpreadsheetOptions {
  */
 declare function importFileIntoSpreadsheet(controller: SpreadsheetController, input: ImportInput, options: ImportFileIntoSpreadsheetOptions): Promise<ImportOutcome<SpreadsheetImport>>;
 
-export { ASTNode, CellData, CellFormat, type CellInputFormatKind, CellPosition, CellRange, type CsvParseOptions, type CsvSerializeOptions, type FillDirection, FilterRule, type FormattedNumberValue, 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, MAX_NUMBER_FORMAT_CODE_CHARS, NUMBER_FORMAT_PRESETS, NumberFormat, type NumberFormatColor, type NumberFormatKind, type NumberFormatPreset, type ParsedCellInput, SPREADSHEET_IMPORT_ADAPTERS, SPREADSHEET_TABLE_ACTIONS, SortDirection, SpreadsheetController, type SpreadsheetImport, type SpreadsheetImportAdapter, type SpreadsheetMenuItem, type SpreadsheetTableActionName, type SpreadsheetTableActions, aggregateValues, applyFormulaSuggestion, bindSpreadsheetTableActions, builtinNumberFormat, builtinNumberFormatId, cellFormatForNumberFormat, checkFormulaArgumentCount, clampMenuPosition, clearNumberFormatCache, compareCellValues, computeFillTarget, csvImportAdapter, dateValueToSerial, escapeCsvField, fillSeries, formatCellDisplay, formatCellForDisplay, formatGeneralFit, formatNumberFormatValue, formatTextFunction, formatValueWithCode, getFillDirection, getFormulaArgumentSpecIndex, getFormulaCaretContext, getFormulaFunction, getFormulaHints, getFormulaSignature, getFormulaSignatureParts, getSpreadsheetMenuItems, importFileIntoSpreadsheet, isBlankValue, isGeneralNumberFormat, isSingleCellRange, listFormulaFunctions, matchesFilterRule, normalizeRange, numberFormatColorToCss, numberFormatForCellFormat, parseCellInput, parseCriteria, parseCsv, parseNumberText, parseTsv, rangeContains, rangeContainsRange, rangesIntersect, registerFormulaFunction, registerSpreadsheetImportAdapters, roundFloat, runSpreadsheetMenuItem, searchFormulaFunctions, serialFromYmd, serializeCsv, serializeTsv, toNumber, tsvImportAdapter, unregisterFormulaFunction, wildcardToRegExp };
+/**
+ * Workbook rules shared by the controller and the framework bindings: sheet
+ * and defined-name validation, and default sheet names.
+ */
+
+/** Longest sheet name Excel accepts. */
+declare const MAX_SHEET_NAME_LENGTH = 31;
+/** Longest defined name Excel accepts. */
+declare const MAX_DEFINED_NAME_LENGTH = 255;
+/**
+ * Checks a sheet name like Excel: 1–31 characters, none of `: \ / ? * [ ]`,
+ * not starting or ending with `'`, not the reserved `History`, and not used
+ * by another sheet (case-insensitively). Returns why it is invalid, or null.
+ */
+declare function validateSheetName(name: string, existingNames?: readonly string[]): string | null;
+/** The first `Sheet N` not used by `existingNames`. */
+declare function nextSheetName(existingNames: readonly string[], base?: string): string;
+/**
+ * A name for a copy of the sheet `name`: `Name (2)`, `Name (3)`, …, shortened
+ * so the suffix fits in 31 characters.
+ */
+declare function copySheetName(name: string, existingNames: readonly string[]): string;
+/**
+ * Checks a defined name like Excel: starts with a letter, `_` or `\`;
+ * continues with letters, digits, `_`, `.`, `\` or `?`; at most 255
+ * characters; and must not look like a cell reference (`A1`, `TAX2024`), an
+ * R1C1 reference (`R1C1`, `R`, `C3`) or a boolean. Returns why it is invalid,
+ * or null.
+ */
+declare function validateDefinedName(name: string): string | null;
+/** Whether a defined name holds a LAMBDA (and so is called like a function). */
+declare function isLambdaDefinition(definition: Pick<SpreadsheetDefinedName, 'refersTo'>): boolean;
+
+/**
+ * Sheet-tab and Name Manager behaviour shared by the React and Svelte
+ * bindings: the tab context menu, drag-to-reorder targets and the rows a
+ * Name Manager panel lists.
+ */
+
+/**
+ * Context-menu items for a sheet tab: insert, rename (asks for the name),
+ * duplicate, move left/right and delete (asks to confirm; disabled for the
+ * last sheet). Run them with `runSpreadsheetMenuItem`. A rename to an
+ * invalid name throws; pass `onError` to report it instead.
+ */
+declare function getSheetTabMenuItems(controller: SpreadsheetController, sheetId: string, options?: {
+    onError?: (message: string) => void;
+}): SpreadsheetMenuItem[];
+/**
+ * The tab index a dragged tab should move to when dropped on the tab at
+ * `targetIndex`: dropping on the left half of a tab places it before that
+ * tab, on the right half after it.
+ */
+declare function sheetDropIndex(fromIndex: number, targetIndex: number, dropAfter: boolean): number;
+/** A row of a Name Manager panel. */
+interface SpreadsheetNameRow {
+    name: string;
+    refersTo: string;
+    /** `Workbook` or the sheet's name. */
+    scopeLabel: string;
+    /** Sheet id for a sheet-scoped name. */
+    sheetId?: string;
+    /** The name's current value, as displayed (`#REF!`, `[LAMBDA]`, `{3×1 array}`). */
+    value: string;
+    comment?: string;
+    isLambda: boolean;
+}
+/** Every defined name with its scope and current value, sorted by name then scope. */
+declare function getNameManagerRows(controller: SpreadsheetController): SpreadsheetNameRow[];
+
+/**
+ * Range helpers shared by conditional formatting and data validation: rules
+ * apply to a list of rectangular ranges ("applies to") that follow row and
+ * column insertions/deletions, and can be cut out of a selection.
+ *
+ * Portions ported from gridcraft/crates/engine/src/cmd/sheet.rs and
+ * gridcraft/crates/engine/src/cmd/data.rs (MIT OR Apache-2.0, © ArtCraft Team
+ * and contributors). See THIRD_PARTY_NOTICES.md.
+ */
+
+/**
+ * Adjusts one range for an inserted or deleted row/column, the way merges
+ * and formula ranges move: ranges after the change shift, ranges across it
+ * grow or shrink, and a range whose rows (or columns) are all deleted is
+ * gone (null).
+ */
+declare function adjustRangeForStructuralChange(range: CellRange, change: StructuralChange): CellRange | null;
+/** `adjustRangeForStructuralChange` over a list, dropping ranges that are gone. */
+declare function adjustRangesForStructuralChange(ranges: CellRange[], change: StructuralChange): CellRange[];
+/** The parts of `range` outside `cut` (up to four rectangles). */
+declare function subtractRange(range: CellRange, cut: CellRange): CellRange[];
+/** Removes the cells of `cut` from every range of the list. */
+declare function subtractRangeFromRanges(ranges: CellRange[], cut: CellRange): CellRange[];
+/** Whether any range of the list contains (row, col). */
+declare function rangesContain(ranges: CellRange[], row: number, col: number): boolean;
+/** The top-left cell of the first range: rule formulas are written for it. */
+declare function ruleAnchor(ranges: CellRange[]): {
+    row: number;
+    col: number;
+};
+/**
+ * A rule formula written for `anchor`, as seen from (row, col): relative
+ * references shift by the distance, `$` parts stay (Excel's conditional
+ * formatting and validation formulas work this way). Returned with a
+ * leading `=`.
+ */
+declare function ruleFormulaAt(formula: string, anchor: {
+    row: number;
+    col: number;
+}, row: number, col: number): string;
+/**
+ * Rewrites a rule formula after a row/column insertion or deletion so it
+ * keeps pointing at the same cells. Keeps the caller's leading `=` (or its
+ * absence).
+ */
+declare function shiftRuleFormula(formula: string, change: StructuralChange): string;
+/** Every cell of a list of ranges, clamped to the sheet, each once, in row-major order per range. */
+declare function forEachRangeCell(ranges: CellRange[], rowCount: number, colCount: number, fn: (row: number, col: number) => void): void;
+/** A1 text of a list of ranges: `A1:B5, D2`. */
+declare function formatRuleRanges(ranges: CellRange[]): string;
+/** Parses `A1:B5, D2` (commas, semicolons or spaces between ranges; `$` ignored). Null when any part is not a cell or range. */
+declare function parseRuleRanges(text: string): CellRange[] | null;
+
+/**
+ * Virtualised rendering of large sheets: which displayed rows and columns
+ * are inside (or near) the scrolled viewport, the space taken by the ones
+ * left out, and how far to scroll to bring a cell into view. Framework
+ * bindings render the frozen rows/columns, a spacer, the window and another
+ * spacer; small sheets render everything (`shouldVirtualizeSpreadsheet`).
+ */
+
+/** Height of the sticky column-header row, in pixels. */
+declare const SPREADSHEET_COLUMN_HEADER_HEIGHT = 28;
+/** Width of the sticky row-number column, in pixels. */
+declare const SPREADSHEET_ROW_HEADER_WIDTH = 48;
+/** Height of a category (group) header row, in pixels. */
+declare const SPREADSHEET_GROUP_ROW_HEIGHT = 28;
+/** Displayed rows above which `shouldVirtualizeSpreadsheet` turns virtualisation on. */
+declare const SPREADSHEET_VIRTUAL_ROW_THRESHOLD = 200;
+/** Displayed columns above which `shouldVirtualizeSpreadsheet` turns virtualisation on. */
+declare const SPREADSHEET_VIRTUAL_COLUMN_THRESHOLD = 60;
+/** Viewport assumed before the grid has been measured (server rendering, jsdom). */
+declare const SPREADSHEET_DEFAULT_VIEWPORT: {
+    width: number;
+    height: number;
+};
+/** Pixel positions of a view model's rows and columns (see `measureSpreadsheetView`). */
+interface SpreadsheetViewMetrics {
+    /** Top of each entry of `view.rows`, below the column header; the last entry is the total height. */
+    rowTops: Float64Array;
+    /** Left of each entry of `view.columns`, after the row header; the last entry is the total width. */
+    columnLefts: Float64Array;
+    /** Leading frozen entries of `view.rows` (always rendered, sticky). */
+    frozenRows: number;
+    /** Leading frozen entries of `view.columns`. */
+    frozenColumns: number;
+    /** Position in `view.rows` of each displayed document row. */
+    rowPosition: Map<number, number>;
+    /** Position in `view.columns` of each displayed document column. */
+    columnPosition: Map<number, number>;
+}
+/** The scroll container: its scroll offsets and client size, in pixels. */
+interface SpreadsheetViewport {
+    scrollTop: number;
+    scrollLeft: number;
+    width: number;
+    height: number;
+}
+/**
+ * The part of a view model to render: frozen rows `[0, frozenRows)`, then
+ * `topSpace` pixels of rows left out, then rows `[rowStart, rowEnd)`, then
+ * `bottomSpace`; columns likewise (indices into `view.rows` / `view.columns`).
+ */
+interface SpreadsheetViewWindow {
+    virtual: boolean;
+    frozenRows: number;
+    rowStart: number;
+    rowEnd: number;
+    topSpace: number;
+    bottomSpace: number;
+    frozenColumns: number;
+    colStart: number;
+    colEnd: number;
+    leftSpace: number;
+    rightSpace: number;
+}
+interface SpreadsheetViewWindowOptions {
+    /** Extra rows rendered above and below the viewport. Default 8. */
+    overscanRows?: number;
+    /** Extra columns rendered left and right of the viewport. Default 2. */
+    overscanColumns?: number;
+    /** Merged ranges (document indices): a merge crossing the window's edge is rendered whole. */
+    merges?: readonly CellRange[];
+}
+/** Measures the rows (row height, or the group row height) and columns (width) of a view model. */
+declare function measureSpreadsheetView(view: SpreadsheetViewModel): SpreadsheetViewMetrics;
+/**
+ * Whether to virtualise: `true` / `false` force it; `'auto'` (the default)
+ * virtualises views with more than `SPREADSHEET_VIRTUAL_ROW_THRESHOLD` rows
+ * or `SPREADSHEET_VIRTUAL_COLUMN_THRESHOLD` columns, so small sheets render
+ * every cell exactly as before.
+ */
+declare function shouldVirtualizeSpreadsheet(view: SpreadsheetViewModel, mode?: boolean | 'auto'): boolean;
+/** A window holding every row and column (no spacers). */
+declare function fullSpreadsheetViewWindow(metrics: SpreadsheetViewMetrics): SpreadsheetViewWindow;
+/**
+ * The rows and columns to render for a viewport. Frozen rows and columns are
+ * always rendered; the rest are limited to the viewport plus overscan, and
+ * widened so no merge is cut by the window's edge.
+ */
+declare function getSpreadsheetViewWindow(metrics: SpreadsheetViewMetrics, viewport: SpreadsheetViewport, options?: SpreadsheetViewWindowOptions): SpreadsheetViewWindow;
+/**
+ * Scroll offsets that bring the cell at document (row, col) fully into view
+ * (below the frozen rows, right of the frozen columns), or null when it
+ * already is (or isn't displayed). Only the axes that must move are set.
+ */
+declare function getSpreadsheetScrollToCell(metrics: SpreadsheetViewMetrics, viewport: SpreadsheetViewport, cell: {
+    row: number;
+    col: number;
+}): {
+    scrollTop?: number;
+    scrollLeft?: number;
+} | null;
+/** Whether two windows render the same rows and columns. */
+declare function sameSpreadsheetViewWindow(a: SpreadsheetViewWindow, b: SpreadsheetViewWindow): boolean;
+
+export { ASTNode, CONDITIONAL_FORMAT_ICON_SETS, CONDITIONAL_FORMAT_PRESETS, CONDITIONAL_FORMAT_STYLE_PRESETS, CONDITIONAL_FORMAT_TIME_PERIODS, CellData, CellFormat, type CellInputFormatKind, CellPosition, CellRange, ConditionalCellFormat, type ConditionalFormatCss, ConditionalFormatEngine, type ConditionalFormatIconGlyph, ConditionalFormatIconSet, ConditionalFormatOverlay, type ConditionalFormatPresetField, type ConditionalFormatPresetInfo, type ConditionalFormatPresetInput, type ConditionalFormatPresetKind, ConditionalFormatRule, ConditionalFormatSheet, ConditionalFormatStyle, ConditionalFormatTimePeriod, ConditionalFormatValue, type CsvParseOptions, type CsvSerializeOptions, DATA_VALIDATION_ERROR_STYLE_OPTIONS, DATA_VALIDATION_OPERATOR_OPTIONS, DATA_VALIDATION_TYPE_OPTIONS, DEFAULT_CONDITIONAL_FORMAT_STYLE, DEFAULT_DATA_VALIDATION_MESSAGE, DEFAULT_DATA_VALIDATION_TITLE, DataValidationErrorStyle, DataValidationOperator, DataValidationResult, DataValidationRule, DataValidationSheet, DataValidationType, EMPTY_CONDITIONAL_FORMAT_OVERLAY, type FillDirection, FilterRule, type FormattedNumberValue, type FormulaActiveCall, type FormulaArgument, type FormulaArgumentSpec, type FormulaArgumentType, type FormulaCaretContext, type FormulaCriteriaPredicate, type FormulaEnvironment, FormulaErrorCode, type FormulaFunctionCategory, type FormulaFunctionContext, type FormulaFunctionDefinition, type FormulaFunctionSuggestion, type FormulaHints, FormulaLambda, type FormulaNameSuggestionSource, FormulaRange, type FormulaSignaturePart, GroupAggregate, type ImportFileIntoSpreadsheetOptions, MAX_DEFINED_NAME_LENGTH, MAX_LAMBDA_DEPTH, MAX_NUMBER_FORMAT_CODE_CHARS, MAX_SHEET_NAME_LENGTH, NUMBER_FORMAT_PRESETS, NewConditionalFormatRule, NumberFormat, type NumberFormatColor, type NumberFormatKind, type NumberFormatPreset, type ParsedCellInput, SPREADSHEET_COLUMN_HEADER_HEIGHT, SPREADSHEET_DEFAULT_VIEWPORT, SPREADSHEET_GROUP_ROW_HEIGHT, SPREADSHEET_IMPORT_ADAPTERS, SPREADSHEET_ROW_HEADER_WIDTH, SPREADSHEET_TABLE_ACTIONS, SPREADSHEET_VIRTUAL_COLUMN_THRESHOLD, SPREADSHEET_VIRTUAL_ROW_THRESHOLD, SortDirection, SpreadsheetController, SpreadsheetDefinedName, type SpreadsheetImport, type SpreadsheetImportAdapter, type SpreadsheetMenuItem, type SpreadsheetNameRow, type SpreadsheetPanelId, type SpreadsheetTableActionName, type SpreadsheetTableActions, type SpreadsheetViewMetrics, SpreadsheetViewModel, type SpreadsheetViewWindow, type SpreadsheetViewWindowOptions, type SpreadsheetViewport, StructuralChange, adjustRangeForStructuralChange, adjustRangesForStructuralChange, aggregateValues, applyFormulaSuggestion, bindSpreadsheetTableActions, blendConditionalFormatColors, builtinNumberFormat, builtinNumberFormatId, cellFormatForNumberFormat, checkFormulaArgumentCount, clampMenuPosition, clearNumberFormatCache, compareCellValues, computeFillTarget, conditionalFormatContrastColor, conditionalFormatIconCount, conditionalFormatNumber, conditionalFormatStyleString, copySheetName, createConditionalFormatRule, csvImportAdapter, dateValueToSerial, defaultIconThresholds, describeConditionalFormat, describeDataValidation, escapeCsvField, evaluateConditionalFormats, fillSeries, findDataValidation, findInvalidCells, forEachRangeCell, formatCellDisplay, formatCellForDisplay, formatGeneralFit, formatNumberFormatValue, formatRuleRanges, formatTextFunction, formatValueWithCode, fullSpreadsheetViewWindow, getConditionalFormatCss, getConditionalFormatIcon, getDataBarCss, getFillDirection, getFormulaArgumentSpecIndex, getFormulaCaretContext, getFormulaFunction, getFormulaHints, getFormulaSignature, getFormulaSignatureParts, getNameManagerRows, getSheetTabMenuItems, getSpreadsheetMenuItems, getSpreadsheetScrollToCell, getSpreadsheetViewWindow, getValidationListValues, importFileIntoSpreadsheet, isBlankValue, isFormulaLambda, isGeneralNumberFormat, isLambdaDefinition, isSingleCellRange, listFormulaFunctions, matchesFilterRule, matchesTimePeriod, measureSpreadsheetView, nextSheetName, normalizeRange, numberFormatColorToCss, numberFormatForCellFormat, parseCellInput, parseCriteria, parseCsv, parseNumberText, parseRuleRanges, parseTsv, rangeContains, rangeContainsRange, rangesContain, rangesIntersect, registerFormulaFunction, registerSpreadsheetImportAdapters, roundFloat, ruleAnchor, ruleFormulaAt, runSpreadsheetMenuItem, sameSpreadsheetViewWindow, searchFormulaFunctions, serialFromYmd, serializeCsv, serializeTsv, sheetDropIndex, shiftRuleFormula, shouldVirtualizeSpreadsheet, subtractRange, subtractRangeFromRanges, toNumber, tsvImportAdapter, unregisterFormulaFunction, validateCellInput, validateDefinedName, validateSheetName, wildcardToRegExp };