# Mog API — Complete Reference > Auto-generated from Mog TypeScript contracts. > Machine-readable spec: https://sheetmog.ai/api-spec.json ## Workbook ### Sub-APIs - `wb.sheets` → WorkbookSheets - `wb.slicers` → WorkbookSlicers - `wb.slicerStyles` → WorkbookSlicerStyles - `wb.pivotTableStyles` → WorkbookPivotTableStyles - `wb.functions` → WorkbookFunctions - `wb.names` → WorkbookNames - `wb.scenarios` → WorkbookScenarios - `wb.history` → WorkbookHistory - `wb.styles` → WorkbookStyles - `wb.properties` → WorkbookProperties - `wb.protection` → WorkbookProtection - `wb.notifications` → WorkbookNotifications - `wb.theme` → WorkbookTheme - `wb.viewport` → WorkbookViewport - `wb.changes` → WorkbookChanges ### Methods #### markClean ```typescript markClean(): void; ``` Reset the dirty flag (call after a successful save). #### getSheet ```typescript getSheet(sheetId: SheetId): Worksheet; ``` Get a sheet by internal SheetId. SYNC — no IPC needed. Throws KernelError if not found. #### getSheetByName ```typescript getSheetByName(name: string): Promise; ``` Get a sheet by name (case-insensitive). ASYNC — resolves name via Rust. #### getSheetByIndex ```typescript getSheetByIndex(index: number): Promise; ``` Get a sheet by 0-based index. ASYNC — resolves index via Rust. #### getActiveSheet ```typescript getActiveSheet(): Worksheet; ``` Get the currently active sheet. SYNC — uses known activeSheetId. #### getOrCreateSheet ```typescript getOrCreateSheet(name: string): Promise<{ sheet: Worksheet; created: boolean }>; ``` Get a sheet by name, creating it if it doesn't exist. @param name - Sheet name (case-insensitive lookup) @returns The sheet and whether it was newly created #### getSheetCount ```typescript getSheetCount(): Promise; ``` Get the number of sheets in the workbook. ASYNC — reads from Rust. #### getSheetNames ```typescript getSheetNames(): Promise; ``` Get the names of all sheets in order. ASYNC — reads from Rust. #### batch ```typescript batch(fn: (wb: Workbook) => Promise): Promise; ``` Execute a batch of operations as a single undo step. All operations inside the callback are grouped into one undo step. If an operation throws, the undo group is closed and all prior writes in the batch remain committed (Excel-style best-effort, not transactional). Note: Each mutation within the batch still triggers its own recalc pass. True deferred recalculation (single recalc at batch end) is not yet implemented. #### createCheckpoint ```typescript createCheckpoint(label?: string): string; ``` Create a named checkpoint (version snapshot). Returns the checkpoint ID. #### restoreCheckpoint ```typescript restoreCheckpoint(id: string): Promise; ``` Restore the workbook to a previously saved checkpoint. #### listCheckpoints ```typescript listCheckpoints(): CheckpointInfo[]; ``` List all saved checkpoints. #### calculate ```typescript calculate(options?: CalculateOptions | CalculationType): Promise; ``` Trigger recalculation of formulas. For circular references (common in financial models — debt schedules, tax shields), enable iterative calculation: await wb.calculate({ iterative: { maxIterations: 100, maxChange: 0.001 } }); Returns convergence metadata (hasCircularRefs, converged, iterations, maxDelta). @param options - Calculation options, or a CalculationType string for backward compatibility #### getCalculationMode ```typescript getCalculationMode(): Promise<'auto' | 'autoNoTable' | 'manual'>; ``` Get the current calculation mode (auto/manual/autoNoTable). Convenience accessor — equivalent to `(await getSettings()).calculationSettings.calcMode`. #### setCalculationMode ```typescript setCalculationMode(mode: 'auto' | 'autoNoTable' | 'manual'): Promise; ``` Set the calculation mode. Convenience mutator — patches `calculationSettings.calcMode`. #### getIterativeCalculation ```typescript getIterativeCalculation(): Promise; ``` Get whether iterative calculation is enabled for circular references. Convenience accessor — equivalent to `(await getSettings()).calculationSettings.enableIterativeCalculation`. #### setIterativeCalculation ```typescript setIterativeCalculation(enabled: boolean): Promise; ``` Set whether iterative calculation is enabled for circular references. Convenience mutator — patches `calculationSettings.enableIterativeCalculation`. @deprecated Use calculate({ iterative: ... }) instead. #### setMaxIterations ```typescript setMaxIterations(n: number): Promise; ``` Set the maximum number of iterations for iterative calculation. Convenience mutator — patches `calculationSettings.maxIterations`. @deprecated Use calculate({ iterative: { maxIterations: n } }) instead. #### setConvergenceThreshold ```typescript setConvergenceThreshold(threshold: number): Promise; ``` Set the convergence threshold (maximum change) for iterative calculation. Convenience mutator — patches `calculationSettings.maxChange`. @deprecated Use calculate({ iterative: { maxChange: threshold } }) instead. #### getUsePrecisionAsDisplayed ```typescript getUsePrecisionAsDisplayed(): Promise; ``` Whether to use displayed precision instead of full (15-digit) precision. Convenience accessor — inverted from `calculationSettings.fullPrecision`. #### setUsePrecisionAsDisplayed ```typescript setUsePrecisionAsDisplayed(value: boolean): Promise; ``` Set whether to use displayed precision. Convenience mutator — inverts and patches `calculationSettings.fullPrecision`. #### getCalculationEngineVersion ```typescript getCalculationEngineVersion(): string; ``` Get the calculation engine version string. #### on ```typescript on(event: WorkbookEvent | string, handler: (event: any) => void): () => void; ``` Subscribe to a coarse WorkbookEvent or arbitrary event string. Handler receives the internal event directly. #### executeCode ```typescript executeCode(code: string, options?: ExecuteOptions): Promise; ``` Execute TypeScript/JavaScript code in the spreadsheet sandbox. #### getWorkbookSnapshot ```typescript getWorkbookSnapshot(): Promise; ``` Get a summary snapshot of the entire workbook. #### getFunctionCatalog ```typescript getFunctionCatalog(): FunctionInfo[]; ``` Get the catalog of all available spreadsheet functions. #### getFunctionInfo ```typescript getFunctionInfo(name: string): FunctionInfo | null; ``` Get detailed info about a specific function. #### describeRanges ```typescript describeRanges( requests: SheetRangeRequest[], includeStyle?: boolean, ): Promise; ``` Describe multiple ranges across multiple sheets in a single IPC call. Each entry returns the same LLM-formatted output as ws.describeRange(). #### exportSnapshot ```typescript exportSnapshot(): Promise; ``` Export the workbook as a snapshot. #### toBuffer ```typescript toBuffer(): Promise; ``` Export the workbook as an XLSX binary buffer. #### insertWorksheetsFromBase64 ```typescript insertWorksheetsFromBase64(base64: string, options?: InsertWorksheetOptions): Promise; ``` Import sheets from an XLSX file (base64-encoded). Returns the names of the inserted sheets (may be deduped if names collide). #### save ```typescript save(): Promise; ``` Save the workbook. Exports to XLSX, calls platform save handler if provided, marks clean. Returns the XLSX buffer. #### copyRangeFrom ```typescript copyRangeFrom(source: Workbook, fromRange: string, toRange: string): Promise; ``` Copy a range from another workbook into this workbook. #### indexToAddress ```typescript indexToAddress(row: number, col: number): string; ``` Convert row/col to A1 address: (0, 0) -> "A1" #### addressToIndex ```typescript addressToIndex(address: string): { row: number; col: number }; ``` Convert A1 address to row/col: "A1" -> { row: 0, col: 0 } #### union ```typescript union(...ranges: string[]): string; ``` Combine multiple range addresses into a single comma-separated address. Equivalent to OfficeJS Application.union(). #### getCultureInfo ```typescript getCultureInfo(): Promise; ``` Get full CultureInfo for the workbook's current culture setting. Resolves the `culture` IETF tag (e.g. 'de-DE') into a complete CultureInfo with number/date/currency formatting details. #### getDecimalSeparator ```typescript getDecimalSeparator(): Promise; ``` Get the decimal separator for the current culture (e.g. '.' or ','). #### getThousandsSeparator ```typescript getThousandsSeparator(): Promise; ``` Get the thousands separator for the current culture (e.g. ',' or '.'). #### getAllTables ```typescript getAllTables(): Promise; ``` Get all tables across all sheets. #### getAllPivotTables ```typescript getAllPivotTables(): Promise; ``` Get all pivot tables across all sheets. #### getAllSlicers ```typescript getAllSlicers(): Promise; ``` Get all slicers across all sheets. #### getAllComments ```typescript getAllComments(): Promise; ``` Get all comments across all sheets. #### getAllNotes ```typescript getAllNotes(): Promise; ``` Get all notes across all sheets. #### searchAllSheets ```typescript searchAllSheets( patterns: string[], options?: SearchOptions, ): Promise>; ``` Search all sheets for cells matching regex patterns (single IPC call). #### getChartDataPointTrack ```typescript getChartDataPointTrack(): Promise; ``` Get whether chart data points track cell movement. OfficeJS: Workbook.chartDataPointTrack (#44). #### setChartDataPointTrack ```typescript setChartDataPointTrack(value: boolean): Promise; ``` Set whether chart data points track cell movement. #### getSettings ```typescript getSettings(): Promise; ``` Get workbook-level settings. #### setSettings ```typescript setSettings(updates: Partial): Promise; ``` Update workbook-level settings. #### getCustomSetting ```typescript getCustomSetting(key: string): Promise; ``` Get a custom setting value by key. Returns null if not found. #### setCustomSetting ```typescript setCustomSetting(key: string, value: string): Promise; ``` Set a custom setting value. #### deleteCustomSetting ```typescript deleteCustomSetting(key: string): Promise; ``` Delete a custom setting by key. #### listCustomSettings ```typescript listCustomSettings(): Promise>; ``` List all custom settings as key-value pairs. #### getCustomSettingCount ```typescript getCustomSettingCount(): Promise; ``` Get the number of custom settings. #### close ```typescript close(closeBehavior?: 'save' | 'skipSave'): Promise; ``` Close the workbook with optional save behavior. @param closeBehavior - 'save' exports snapshot before disposing, 'skipSave' disposes immediately (default: 'skipSave') #### dispose ```typescript dispose(): void; ``` Dispose of the workbook and release resources. #### getActiveCell ```typescript getActiveCell(): { sheetId: string; row: number; col: number } | null; ``` Active cell. Returns null in headless/no-UI contexts. #### getSelectedRanges ```typescript getSelectedRanges(): string[]; ``` Currently selected range(s) as A1 address strings. Returns [] in headless. #### getSelectedRange ```typescript getSelectedRange(): string | null; ``` Primary selected range. Returns null in headless. #### getActiveChart ```typescript getActiveChart(): string | null; ``` Active chart object ID, or null. #### getActiveShape ```typescript getActiveShape(): string | null; ``` Active shape object ID, or null. #### getActiveSlicer ```typescript getActiveSlicer(): string | null; ``` Active slicer object ID, or null. ## Worksheet ### Sub-APIs - `ws.whatIf` → WorksheetWhatIf - `ws.smartArt` → WorksheetSmartArt - `ws.changes` → WorksheetChanges - `ws.formats` → WorksheetFormats - `ws.layout` → WorksheetLayout - `ws.view` → WorksheetView - `ws.structure` → WorksheetStructure - `ws.charts` → WorksheetCharts - `ws.objects` → WorksheetObjectCollection - `ws.shapes` → WorksheetShapeCollection - `ws.pictures` → WorksheetPictureCollection - `ws.textBoxes` → WorksheetTextBoxCollection - `ws.drawings` → WorksheetDrawingCollection - `ws.equations` → WorksheetEquationCollection - `ws.wordArt` → WorksheetWordArtCollection - `ws.connectors` → WorksheetConnectorCollection - `ws.filters` → WorksheetFilters - `ws.formControls` → WorksheetFormControls - `ws.conditionalFormats` → WorksheetConditionalFormatting - `ws.validation` → WorksheetValidation - `ws.tables` → WorksheetTables - `ws.pivots` → WorksheetPivots - `ws.slicers` → WorksheetSlicers - `ws.sparklines` → WorksheetSparklines - `ws.comments` → WorksheetComments - `ws.hyperlinks` → WorksheetHyperlinks - `ws.outline` → WorksheetOutline - `ws.protection` → WorksheetProtection - `ws.print` → WorksheetPrint - `ws.settings` → WorksheetSettings - `ws.bindings` → WorksheetBindings - `ws.names` → WorksheetNames - `ws.styles` → WorksheetStyles ### Methods #### getName ```typescript getName(): Promise; ``` Get the sheet name. Async — reads from Rust via IPC (cached after first call). #### setName ```typescript setName(name: string): Promise; ``` Set the sheet name. #### getIndex ```typescript getIndex(): number; ``` Get the 0-based sheet index. #### getSheetId ```typescript getSheetId(): SheetId; ``` Get the internal sheet ID. #### setCell ```typescript setCell(address: string, value: any, options?: CellWriteOptions): Promise; ``` Set a cell value by A1 address. String values starting with "=" are treated as formulas (e.g. "=SUM(B1:B10)"). Use `options.asFormula` to force formula interpretation without the "=" prefix. #### setDateValue ```typescript setDateValue(row: number, col: number, date: Date): Promise; ``` Set a date value in a cell, automatically applying date format. #### setTimeValue ```typescript setTimeValue(row: number, col: number, date: Date): Promise; ``` Set a time value in a cell, automatically applying time format. #### getCell ```typescript getCell(address: string): Promise; ``` Get cell data by A1 address. #### getRange ```typescript getRange(range: string): Promise; ``` Get a 2D array of cell data for a range (A1 notation). #### setRange ```typescript setRange(range: string, values: any[][]): Promise; ``` Set a 2D array of values into a range (A1 notation). String values starting with "=" are treated as formulas. #### clearData ```typescript clearData(range: string): Promise; ``` Clear all cell data (values and formulas) in a range (A1 notation, e.g. "A1:C3"). #### clear ```typescript clear(range: string, applyTo?: ClearApplyTo): Promise; ``` Unified clear with mode selection (OfficeJS Range.clear equivalent). @param range - A1 range string (e.g. "A1:C3") @param applyTo - What to clear: 'all' (default), 'contents', 'formats', 'hyperlinks' #### clearOrResetContents ```typescript clearOrResetContents(range: string): Promise; ``` Clear cell contents with form control awareness (OfficeJS clearOrResetContents equivalent). For cells linked to form controls: resets the control to its default value (checkbox -> unchecked/false, comboBox -> first item/empty). For all other cells: clears contents normally (same as clear(range, 'contents')). @param range - A1 range string (e.g. "A1:C3") #### getValue ```typescript getValue(address: string): Promise; ``` Get the computed value of a cell by A1 address. Returns null for empty cells. #### getData ```typescript getData(): Promise; ``` Get all cell values in the used range as a 2D array. Returns [] if sheet is empty. #### getFormula ```typescript getFormula(address: string): Promise; ``` Get the formula of a cell by A1 address (null if not a formula cell). #### getFormulas ```typescript getFormulas(range: string): Promise<(string | null)[][]>; ``` Get formulas for a range. Returns 2D array: formula string or null per cell. #### getFormulaArray ```typescript getFormulaArray(address: string): Promise; ``` Get the array formula for a cell that is part of a dynamic array spill. If the cell is the source of a dynamic array (e.g., =SEQUENCE(5)), returns the formula. If the cell is a spill member (projected from a source), returns the source cell's formula. Returns null if the cell is not part of an array. @param address - A1-style cell address @returns The array formula string, or null if not an array cell #### getRawCellData ```typescript getRawCellData(address: string, includeFormula?: boolean): Promise; ``` Get raw cell data (value, formula, format, borders, etc.) by A1 address. #### getRawRangeData ```typescript getRawRangeData(range: string, includeFormula?: boolean): Promise; ``` Get raw data for a range as a 2D array. #### getRangeWithIdentity ```typescript getRangeWithIdentity( startRow: number, startCol: number, endRow: number, endCol: number, ): Promise; ``` Get all non-empty cells in a range with stable CellId identity. Returns a flat array of cells (not a 2D grid) — only cells with data are included. Each cell includes its CellId, position, computed value, formula text (if formula cell), and pre-formatted display string. Used by operations that need identity-aware cell data (find-replace, clipboard, cell relocation). #### describe ```typescript describe(address: string): Promise; ``` Get a human-readable description of a cell: "Revenue | =SUM(B2:B10) | [bold]" #### describeRange ```typescript describeRange(range: string, includeStyle?: boolean): Promise; ``` Get a tabular description of a range with formula abbreviation. #### summarize ```typescript summarize(options?: SummaryOptions): Promise; ``` Get a sheet overview summary for agent context. #### getUsedRange ```typescript getUsedRange(): Promise; ``` Get the used range as an A1 string, or null if the sheet is empty. #### getCurrentRegion ```typescript getCurrentRegion(row: number, col: number): Promise; ``` Get the contiguous data region around a cell (Excel's Ctrl+Shift+* / CurrentRegion). #### findDataEdge ```typescript findDataEdge( row: number, col: number, direction: 'up' | 'down' | 'left' | 'right', ): Promise<{ row: number; col: number }>; ``` Find the data edge in a direction (Excel's Ctrl+Arrow). Single bridge call to Rust. #### findLastRow ```typescript findLastRow(col: number): Promise<{ lastDataRow: number | null; lastFormatRow: number | null }>; ``` Find the last populated row in a column. Returns data and formatting edges. #### findLastColumn ```typescript findLastColumn( row: number, ): Promise<{ lastDataCol: number | null; lastFormatCol: number | null }>; ``` Find the last populated column in a row. Returns data and formatting edges. #### findCells ```typescript findCells(predicate: (cell: CellData) => boolean): Promise; ``` Find all cells matching a predicate. Returns A1 addresses. #### findByValue ```typescript findByValue(value: any): Promise; ``` Find all cells with a specific value. Returns A1 addresses. #### findByFormula ```typescript findByFormula(pattern: RegExp): Promise; ``` Find all cells whose formula matches a regex pattern. Returns A1 addresses. #### regexSearch ```typescript regexSearch(patterns: string[], options?: SearchOptions): Promise; ``` Search cells using regex patterns. #### signCheck ```typescript signCheck(range?: string, options?: SignCheckOptions): Promise; ``` Detect cells whose numeric sign disagrees with their neighbors. Returns anomalies sorted by severity — the agent decides which are real errors. #### findInRange ```typescript findInRange(range: string, text: string, options?: SearchOptions): Promise; ``` Find the first cell matching text within a range (OfficeJS Range.find equivalent). @param range - A1 range string to search within @param text - Text or regex pattern to search for @param options - Search options (matchCase, entireCell) @returns The first matching SearchResult, or null if no match found #### replaceAll ```typescript replaceAll( range: string, text: string, replacement: string, options?: SearchOptions, ): Promise; ``` Find and replace all occurrences within a range (OfficeJS Range.replaceAll equivalent). @param range - A1 range string to search within @param text - Text to find @param replacement - Replacement text @param options - Search options (matchCase, entireCell) @returns Number of replacements made #### getExtendedRange ```typescript getExtendedRange( range: string, direction: 'up' | 'down' | 'left' | 'right', activeCell?: { row: number; col: number }, ): Promise; ``` Get the extended range in a direction (OfficeJS Range.getExtendedRange / Ctrl+Shift+Arrow). From the active cell (default: top-left of range), finds the data edge in the given direction and returns a range extending from the original range to that edge. @param range - A1 range string (current selection) @param direction - Direction to extend @param activeCell - Optional active cell override (default: top-left of range) @returns Extended range as CellRange #### isEntireColumn ```typescript isEntireColumn(range: string | CellRange): boolean; ``` Check if a range represents entire column(s) (e.g., "A:C"). @param range - A1 range string or CellRange object @returns True if the range represents entire column(s) #### isEntireRow ```typescript isEntireRow(range: string | CellRange): boolean; ``` Check if a range represents entire row(s) (e.g., "1:5"). @param range - A1 range string or CellRange object @returns True if the range represents entire row(s) #### getVisibleView ```typescript getVisibleView(range: string): Promise; ``` Get only the visible (non-hidden) rows from a range (OfficeJS RangeView equivalent). Filters out rows hidden by AutoFilter or manual hide operations. Returns cell values for visible rows only, along with the absolute row indices. @param range - A1 range string (e.g., "A1:Z100") @returns Visible rows' values and their indices #### getSpecialCells ```typescript getSpecialCells(cellType: CellType, valueType?: CellValueType): Promise; ``` Find cells matching a special cell type (OfficeJS Range.getSpecialCells equivalent). Returns addresses of cells matching the specified type within the used range. Optionally filter by value type when cellType is `Constants` or `Formulas`. @param cellType - The type of cells to find @param valueType - Optional value type filter (only for Constants/Formulas) @returns Array of matching cell addresses #### getDisplayValue ```typescript getDisplayValue(address: string): Promise; ``` Get the display value (formatted string) for a cell by A1 address. #### getDisplayText ```typescript getDisplayText(range: string): Promise; ``` Get formatted display text for an entire range as a 2D array (OfficeJS Range.text equivalent). @param range - A1 range string @returns 2D array of formatted display strings #### getValueTypes ```typescript getValueTypes(range: string): Promise; ``` Get per-cell value type classification for a range (OfficeJS Range.valueTypes equivalent). @param range - A1 range string @returns 2D array of RangeValueType enums #### getNumberFormatCategories ```typescript getNumberFormatCategories(range: string): Promise; ``` Get per-cell number format category for a range (OfficeJS Range.numberFormatCategories equivalent). @param range - A1 range string @returns 2D array of NumberFormatCategory enums #### sortRange ```typescript sortRange(range: string, options: SortOptions): Promise; ``` Sort a range by the specified options. #### autoFill ```typescript autoFill( sourceRange: string, targetRange: string, fillMode?: AutoFillMode, ): Promise; ``` Autofill from source range into target range. @param sourceRange - Source range in A1 notation (e.g., "A1:A3") @param targetRange - Target range to fill into (e.g., "A4:A10") @param fillMode - Fill behavior. Default: 'auto' (detect pattern). #### fillSeries ```typescript fillSeries(range: string, options: FillSeriesOptions): Promise; ``` Fill a range with a series (Edit > Fill > Series dialog equivalent). More explicit than autoFill — caller specifies exact series parameters. The range contains BOTH source cells (first row/col) and target cells (rest). The kernel splits them based on direction. @param range - Range in A1 notation containing source + target cells @param options - Series parameters (type, step, stop, direction, etc.) #### moveTo ```typescript moveTo(sourceRange: string, targetRow: number, targetCol: number): Promise; ``` Move (relocate) cells from a source range to a target position. Moves cell values, formulas, and formatting. Formula references within the moved range are adjusted to the new position. The source range is cleared after the move. @param sourceRange - Source range in A1 notation (e.g., "A1:B10") @param targetRow - Destination top-left row (0-based) @param targetCol - Destination top-left column (0-based) #### copyFrom ```typescript copyFrom(sourceRange: string, targetRange: string, options?: CopyFromOptions): Promise; ``` Copy cells from a source range to a target range with optional paste-special behavior. Supports selective copy (values only, formulas only, formats only, or all), skip-blanks, and transpose. Maps to OfficeJS Range.copyFrom(). @param sourceRange - Source range in A1 notation (e.g., "A1:B10") @param targetRange - Target range in A1 notation (e.g., "D1:E10") @param options - Optional paste-special behavior (copyType, skipBlanks, transpose) #### setCells ```typescript setCells(cells: Array<{ addr: string; value: any }>): Promise; ``` Bulk-write scattered cell values and/or formulas in a single IPC call. Values starting with "=" are treated as formulas. Supports both A1 addressing and numeric (row, col) addressing. #### createTable ```typescript createTable(name: string, options: CreateTableOptions): Promise; ``` Create a table from headers and data in a single call. Writes `[headers, ...data]` starting at `startCell` (default "A1"), then creates an Excel table over the written range. @param name - Table name (must be unique in the workbook) @param options - Headers, data rows, and optional start cell #### toCSV ```typescript toCSV(options?: { separator?: string }): Promise; ``` Export the used range as a CSV string (RFC 4180 compliant). Fields containing commas, quotes, or newlines are quoted. Double-quotes inside fields are escaped as "". Formula injection is prevented by prefixing `=`, `+`, `-`, `@` with a tab character. @param options - Optional separator (default ",") #### toJSON ```typescript toJSON(options?: { headerRow?: number | 'none' }): Promise[]>; ``` Export the used range as an array of row objects. By default, the first row is used as header keys. Pass `headerRow: 'none'` to use column letters (A, B, C, ...) as keys. Pass `headerRow: N` to use a specific 0-based row as headers. @param options - Optional header row configuration #### getDependents ```typescript getDependents(address: string): Promise; ``` Get cells that depend on this cell by A1 address. #### getPrecedents ```typescript getPrecedents(address: string): Promise; ``` Get cells that this cell depends on by A1 address. #### getSelectionAggregates ```typescript getSelectionAggregates(ranges: CellRange[]): Promise; ``` Get aggregates (SUM, COUNT, AVG, MIN, MAX) for selected ranges. #### formatValues ```typescript formatValues(entries: FormatEntry[]): Promise; ``` Batch-format values using number format codes. Returns formatted strings. #### isVisible ```typescript isVisible(): boolean; ``` Check if the sheet is visible (sync -- local metadata). #### setVisible ```typescript setVisible(visible: boolean): Promise; ``` Show or hide the sheet. #### getVisibility ```typescript getVisibility(): Promise<'visible' | 'hidden' | 'veryHidden'>; ``` Get the visibility state of the sheet ('visible', 'hidden', or 'veryHidden'). #### setVisibility ```typescript setVisibility(state: 'visible' | 'hidden' | 'veryHidden'): Promise; ``` Set the visibility state of the sheet. #### on ```typescript on(event: SheetEvent | string, handler: (event: any) => void): () => void; ``` #### setBoundsReader ```typescript setBoundsReader(reader: IObjectBoundsReader): void; ``` Inject the bounds reader (from the renderer's SceneGraphBoundsReader) so that floating-object handles can resolve pixel bounds via `handle.getBounds()`. Calling this invalidates cached typed collections so they pick up the new reader on their next access. ## WorkbookSheets ### Methods #### add ```typescript add(name?: string, index?: number): Promise; ``` Add a new sheet to the workbook. @param name - Optional sheet name. Defaults to "SheetN". @param index - Optional 0-based position to insert the sheet. @returns The created Worksheet. #### remove ```typescript remove(target: number | string): Promise; ``` Remove a sheet by index or name. Throws if attempting to remove the last sheet. @param target - 0-based index or sheet name. #### move ```typescript move(name: string, toIndex: number): Promise; ``` Move a sheet to a new position. @param name - Sheet name (or identifier) to move. @param toIndex - Target 0-based index. #### rename ```typescript rename(target: number | string, newName: string): Promise; ``` Rename a sheet. @param target - 0-based index or current sheet name. @param newName - The new name for the sheet. #### setActive ```typescript setActive(target: number | string): void | Promise; ``` Set the active sheet. @param target - 0-based index or sheet name. #### copy ```typescript copy(source: number | string, newName?: string): Promise; ``` Copy a sheet within the workbook. @param source - 0-based index or name of the sheet to copy. @param newName - Optional name for the copy. Defaults to "SheetName (Copy)". @returns The newly created Worksheet. #### hide ```typescript hide(target: number | string): Promise; ``` Hide a sheet. Throws if attempting to hide the last visible sheet. @param target - 0-based index or sheet name. #### show ```typescript show(target: number | string): Promise; ``` Show (unhide) a sheet. @param target - 0-based index or sheet name. #### setSelectedIds ```typescript setSelectedIds(sheetIds: string[]): Promise; ``` Set which sheets are selected (multi-sheet selection for collaboration). @param sheetIds - Array of sheet IDs to mark as selected. #### on ```typescript on( event: 'sheetAdded' | 'sheetRemoved' | 'sheetRenamed' | 'activeSheetChanged', handler: (event: any) => void, ): () => void; ``` Subscribe to sheet collection events. Fires for: sheetAdded, sheetRemoved, sheetRenamed, activeSheetChanged. @param event - Event type @param handler - Event handler @returns Unsubscribe function ## WorkbookSlicers Sub-API for workbook-scoped slicer operations. ### Methods #### list ```typescript list(): Promise; ``` List all slicers across all sheets in the workbook. @returns Array of slicer summary information #### get ```typescript get(slicerId: string): Promise; ``` Get a slicer by ID from any sheet. @param slicerId - ID of the slicer @returns Full slicer state, or null if not found #### getItemAt ```typescript getItemAt(index: number): Promise; ``` Get a slicer by its zero-based index in the list. @param index - Zero-based index of the slicer @returns Slicer summary information, or null if index is out of range #### getItems ```typescript getItems(slicerId: string): Promise; ``` Get the items (values) available in a slicer by ID. @param slicerId - ID of the slicer @returns Array of slicer items with selection state #### getItem ```typescript getItem(slicerId: string, key: CellValue): Promise; ``` Get a slicer item by its string key. @param slicerId - ID of the slicer @param key - The value to look up (matched via string coercion) @returns The matching slicer item @throws KernelError if no item matches the key #### getItemOrNullObject ```typescript getItemOrNullObject(slicerId: string, key: CellValue): Promise; ``` Get a slicer item by its string key, or null if not found. @param slicerId - ID of the slicer @param key - The value to look up (matched via string coercion) @returns The matching slicer item, or null if not found #### remove ```typescript remove(slicerId: string): Promise; ``` Remove a slicer by ID from any sheet. @param slicerId - ID of the slicer to remove #### getCount ```typescript getCount(): Promise; ``` Get the total count of slicers across all sheets. @returns Number of slicers in the workbook ## WorkbookSlicerStyles ### Methods #### getDefault ```typescript getDefault(): Promise; ``` Get the workbook's default slicer style preset. Returns 'light1' if not explicitly set. #### setDefault ```typescript setDefault(style: string | null): Promise; ``` Set the workbook's default slicer style preset. Pass null to reset to 'light1'. #### getCount ```typescript getCount(): Promise; ``` Get the number of built-in slicer styles. #### getItem ```typescript getItem(name: string): Promise; ``` Get a specific slicer style by name. Returns null if not found. #### list ```typescript list(): Promise; ``` List all built-in slicer styles. #### add ```typescript add(name: string, style: SlicerCustomStyle, makeUniqueName?: boolean): Promise; ``` Add a new custom named slicer style. @param name - Desired style name. @param style - Custom style definition. @param makeUniqueName - When true, auto-appends a suffix if the name collides. Default: false. @returns The final name assigned to the style (may differ from `name` when `makeUniqueName` is true). #### getItemOrNullObject ```typescript getItemOrNullObject(name: string): Promise; ``` Get a named slicer style by name, or null if not found. Null-safe lookup. #### delete ```typescript delete(name: string): Promise; ``` Delete a custom named slicer style. @param name - The name of the style to delete. #### duplicate ```typescript duplicate(name: string): Promise; ``` Duplicate an existing named slicer style. @param name - The name of the style to duplicate. @returns The name of the newly created copy. ## WorkbookPivotTableStyles ### Methods #### getDefault ```typescript getDefault(): Promise; ``` Get the workbook's default pivot table style preset. Returns 'PivotStyleLight16' if not explicitly set. #### setDefault ```typescript setDefault(style: string | null): Promise; ``` Set the workbook's default pivot table style preset. Pass null to reset to 'PivotStyleLight16'. #### getCount ```typescript getCount(): Promise; ``` Get the count of built-in pivot table styles. #### getItem ```typescript getItem(name: string): Promise; ``` Get a pivot table style by name, or null if not found. #### list ```typescript list(): Promise; ``` List all built-in pivot table styles. ## WorkbookFunctions ### Methods #### invoke ```typescript invoke(functionName: string, ...args: unknown[]): Promise; ``` Invoke any spreadsheet function by name with arbitrary arguments. @param functionName - The function name (e.g. 'VLOOKUP', 'SUM'). @param args - Arguments: cell/range refs as strings, literals as values. @returns The evaluated result. #### vlookup ```typescript vlookup( lookupValue: CellValue, tableArray: string, colIndex: number, rangeLookup?: boolean, ): Promise; ``` VLOOKUP function. @param lookupValue - The value to search for. @param tableArray - The range reference (e.g. "A1:C10"). @param colIndex - Column index (1-based) to return. @param rangeLookup - Whether to use approximate match (default: false). #### sum ```typescript sum(...ranges: string[]): Promise; ``` SUM function. #### average ```typescript average(...ranges: string[]): Promise; ``` AVERAGE function. #### count ```typescript count(...ranges: string[]): Promise; ``` COUNT function. #### max ```typescript max(...ranges: string[]): Promise; ``` MAX function. #### min ```typescript min(...ranges: string[]): Promise; ``` MIN function. #### concatenate ```typescript concatenate(...values: CellValue[]): Promise; ``` CONCATENATE function. ## WorkbookNames ### Methods #### add ```typescript add(name: string, reference: string, comment?: string): Promise; ``` Define a new named range. @param name - The name to define. @param reference - A1-style reference (e.g. "Sheet1!$A$1:$B$10"). May omit leading "=". @param comment - Optional descriptive comment. #### get ```typescript get(name: string, scope?: string): Promise; ``` Get a named range by name. @param name - The name to look up. @param scope - Optional sheet name scope. Omit for workbook-scoped names. @returns The named range info, or null if not found. #### getRange ```typescript getRange(name: string, scope?: string): Promise; ``` Get the parsed sheet reference for a named range. Returns the sheet name and range portion for names that refer to a simple sheet!range reference. Returns null if the name is not found or if the reference is not a simple sheet!range format (e.g., a formula). @param name - The name to look up. @param scope - Optional sheet name scope. Omit for workbook-scoped names. @returns The parsed reference, or null if not found or not a simple range. #### remove ```typescript remove(name: string, scope?: string): Promise; ``` Remove a named range. @param name - The name to remove. @param scope - Optional sheet name scope. Omit for workbook-scoped names. #### update ```typescript update(name: string, updates: NamedRangeUpdateOptions): Promise; ``` Update an existing named range. @param name - The current name to update. @param updates - Fields to change (name, reference, comment). #### list ```typescript list(): Promise; ``` List all named ranges in the workbook. @returns Array of named range info objects. #### createFromSelection ```typescript createFromSelection( sheetId: SheetId, range: CellRange, options: CreateNamesFromSelectionOptions, ): Promise; ``` Create named ranges from row/column labels in a selection. Scans edges of the selection for label text and creates names referring to the corresponding data cells. @param sheetId - Sheet containing the selection. @param range - The cell range to scan for labels. @param options - Which edges to scan (top, left, bottom, right). @returns Counts of successfully created and skipped names. #### getValue ```typescript getValue(name: string, scope?: string): Promise; ``` Get the computed value of a named item as a display-formatted string. For single-cell references, returns the formatted cell value. For range references, returns the raw A1 reference string. @param name - The named item to evaluate. @param scope - Optional sheet name scope for resolution precedence. @returns The display value, or null if the name doesn't exist. #### getType ```typescript getType(name: string, scope?: string): Promise; ``` Get the OfficeJS-compatible type of a named item's resolved value. @param name - The named item to inspect. @param scope - Optional sheet name scope for resolution precedence. @returns The type string, or null if the name doesn't exist. #### getArrayValues ```typescript getArrayValues(name: string, scope?: string): Promise; ``` Get the 2D array of resolved values for a named range. For single-cell references, returns a 1×1 array. For multi-cell ranges, returns the full grid. @param name - The named item to evaluate. @param scope - Optional sheet name scope for resolution precedence. @returns The 2D value array, or null if the name doesn't exist or isn't a range. #### getArrayTypes ```typescript getArrayTypes(name: string, scope?: string): Promise; ``` Get the 2D array of type classifications for each cell in a named range. @param name - The named item to evaluate. @param scope - Optional sheet name scope for resolution precedence. @returns The 2D type array, or null if the name doesn't exist or isn't a range. #### getValueAsJson ```typescript getValueAsJson(name: string, scope?: string): Promise; ``` Get the raw typed value of a named item as a JSON-compatible value. For single-cell references, returns the cell's typed value (string, number, boolean, null, or error). For range references, returns the first cell's value. For constants, returns the constant as a string. @param name - The named item to evaluate. @param scope - Optional sheet name scope for resolution precedence. @returns The typed value, or null if the name doesn't exist. #### recalculateDependents ```typescript recalculateDependents(name: string, sheetId: SheetId, origin?: string): void; ``` Recalculate all formulas that depend on a given named range. Called after a name is created, updated, or deleted so that dependent cells reflect the new definition (or show #NAME? errors). @param name - The name that changed (case-insensitive). @param sheetId - Current active sheet for relative reference resolution. @param origin - Transaction origin (default: 'user'). ## WorkbookScenarios ### Methods #### create ```typescript create(config: ScenarioConfig): Promise; ``` Create a what-if scenario. @param config - Scenario configuration (name, changing cells, values). @returns The newly created scenario's ID. #### list ```typescript list(): Promise; ``` List all scenarios in the workbook. @returns Array of all saved scenarios. #### apply ```typescript apply(id: string): Promise; ``` Apply a scenario's values to the worksheet. @param id - The scenario ID to apply. @returns Result including cells updated count and original values for restore. #### restore ```typescript restore(originalValues: OriginalCellValue[]): Promise; ``` Restore original values from a prior apply() call and deactivate the scenario. @param originalValues - The original cell values returned by apply(). #### update ```typescript update(scenarioId: string, config: Partial): Promise; ``` Update an existing scenario's configuration. @param scenarioId - The scenario ID to update. @param config - Partial configuration with fields to change. #### delete ```typescript delete(id: string): Promise; ``` Delete a scenario. @param id - The scenario ID to delete. ## WorkbookHistory ### Methods #### undo ```typescript undo(): Promise; ``` Undo the last operation. #### redo ```typescript redo(): Promise; ``` Redo the last undone operation. #### canUndo ```typescript canUndo(): boolean; ``` Check if undo is available. Synchronous (uses cached state). #### canRedo ```typescript canRedo(): boolean; ``` Check if redo is available. Synchronous (uses cached state). #### list ```typescript list(): UndoHistoryEntry[]; ``` Get the undo history entries. Synchronous. #### goToIndex ```typescript goToIndex(index: number): Promise; ``` Undo to a specific index in the history. Performs multiple undo operations to reach the target state. @param index - Index in the history (0 = most recent operation) #### getState ```typescript getState(): Promise; ``` Get the full undo/redo state from the compute engine. Returns depth counts used by CheckpointManager to track checkpoint state. #### subscribe ```typescript subscribe(listener: (event: UndoStateChangeEvent) => void): CallableDisposable; ``` Subscribe to undo/redo state changes. Called whenever the undo stack changes (push, undo, redo, clear). @returns Unsubscribe function #### setNextDescription ```typescript setNextDescription(description: string): void; ``` Set the description for the next undo step. Call immediately before a mutation to label the undo entry. ## WorkbookStyles ### Methods #### getTableStyles ```typescript getTableStyles(): Promise; ``` Get all table styles (built-in + custom) with a `readOnly` flag. #### createTableStyle ```typescript createTableStyle(config: TableStyleConfig): Promise; ``` Create a custom table style. Returns the style name/ID. #### updateTableStyle ```typescript updateTableStyle(name: string, updates: Partial): Promise; ``` Update a custom table style. #### removeTableStyle ```typescript removeTableStyle(name: string): Promise; ``` Remove a custom table style. #### getDefaultTableStyle ```typescript getDefaultTableStyle(): Promise; ``` Get the default table style ID applied to new tables. #### setDefaultTableStyle ```typescript setDefaultTableStyle(styleId: string | undefined): Promise; ``` Set the default table style ID for new tables. Pass undefined to reset. #### duplicateTableStyle ```typescript duplicateTableStyle(name: string): Promise; ``` Duplicate an existing table style. Returns the new style name. #### getById ```typescript getById(styleId: string): Promise; ``` Get a cell format (style) by its style ID. Returns the format, or null if not found. #### getCellStyles ```typescript getCellStyles(): Promise; ``` Get all custom cell styles (excludes built-in). #### createCellStyle ```typescript createCellStyle(style: Omit): Promise; ``` Create a new custom cell style. #### updateCellStyle ```typescript updateCellStyle( styleId: string, updates: Partial>, ): Promise; ``` Update a custom cell style. Returns the updated style, or undefined if not found. #### deleteCellStyle ```typescript deleteCellStyle(styleId: string): Promise; ``` Delete a custom cell style. Returns true if deleted. ## WorkbookProperties WorkbookProperties -- Document properties sub-API interface. Provides methods to read and write document metadata (title, author, keywords, etc.) and custom document properties. ### Methods #### getDocumentProperties ```typescript getDocumentProperties(): Promise; ``` Get all document properties (author, title, keywords, etc.). #### setDocumentProperties ```typescript setDocumentProperties(props: Partial): Promise; ``` Update document properties (partial merge). #### getCustomProperty ```typescript getCustomProperty(key: string): Promise; ``` Get a custom document property by key. #### setCustomProperty ```typescript setCustomProperty(key: string, value: string): Promise; ``` Set a custom document property. #### removeCustomProperty ```typescript removeCustomProperty(key: string): Promise; ``` Remove a custom document property. #### listCustomProperties ```typescript listCustomProperties(): Promise>; ``` List all custom document properties. ## WorkbookProtection ### Methods #### protect ```typescript protect(password?: string, options?: Partial): Promise; ``` Protect workbook structure with optional password and options. #### unprotect ```typescript unprotect(password?: string): Promise; ``` Unprotect the workbook. Returns true if successful (password matches). ## WorkbookNotifications Workbook-level notifications sub-API. Provides toast/notification operations without requiring apps to import from `@mog/kernel/services/notifications`. ### Methods #### getAll ```typescript getAll(): Notification[]; ``` Get all active notifications #### subscribe ```typescript subscribe(listener: (notifications: Notification[]) => void): CallableDisposable; ``` Subscribe to notification changes. Returns CallableDisposable — call directly or .dispose() to unsubscribe. #### notify ```typescript notify(message: string, options?: NotificationOptions): string; ``` Show a notification. Returns the notification ID. #### info ```typescript info(message: string, options?: Omit): string; ``` Show an info notification. Returns the notification ID. #### success ```typescript success(message: string, options?: Omit): string; ``` Show a success notification. Returns the notification ID. #### warning ```typescript warning(message: string, options?: Omit): string; ``` Show a warning notification. Returns the notification ID. #### error ```typescript error(message: string, options?: Omit): string; ``` Show an error notification. Returns the notification ID. #### dismiss ```typescript dismiss(id: string): void; ``` Dismiss a notification by ID #### dismissAll ```typescript dismissAll(): void; ``` Dismiss all notifications ## WorkbookTheme ### Methods #### getWorkbookTheme ```typescript getWorkbookTheme(): Promise; ``` Get the workbook's OOXML theme definition (color palette + fonts). Reads from Rust via bridge — async. #### setWorkbookTheme ```typescript setWorkbookTheme(theme: ThemeDefinition): Promise; ``` Set the workbook's OOXML theme definition. Writes to Rust via bridge — async. Triggers viewport palette invalidation so subsequent renders pick up the new theme colors. #### getChromeTheme ```typescript getChromeTheme(): ChromeTheme; ``` Get the current chrome theme (canvas UI shell colors). Synchronous — TS-only, no Rust involvement. #### setChromeTheme ```typescript setChromeTheme(theme: Partial): void; ``` Set chrome theme with partial merge semantics. Merges the partial input with the **current** theme (not defaults). Triggers canvas layer re-render and CSS variable update. To reset to defaults, pass `DEFAULT_CHROME_THEME` explicitly. ## WorkbookViewport Viewport management sub-API on the Workbook. Consumer-scoped: createRegion() returns a handle with per-viewport refresh, prefetch, and lifecycle management. ### Methods #### createRegion ```typescript createRegion(sheetId: string, bounds: ViewportBounds, viewportId?: string): ViewportRegion; ``` Create a tracked viewport region. Returns a handle — dispose when done. #### resetSheetRegions ```typescript resetSheetRegions(sheetId: string): void; ``` Reset all regions for a sheet (e.g., on sheet switch). #### setRenderScheduler ```typescript setRenderScheduler(scheduler: RenderScheduler | null): void; ``` Inject (or clear) the render scheduler for "Write = Invalidate" integration. When set, mutation patches applied to viewport buffers automatically trigger a render frame via the scheduler. #### subscribe ```typescript subscribe(cb: (event: ViewportChangeEvent) => void): () => void; ``` Subscribe to viewport state change events from all viewport coordinators. Events are emitted synchronously after each state change. Returns an unsubscribe function. #### setShowFormulas ```typescript setShowFormulas(value: boolean): void; ``` Set the show-formulas mode. When true, Rust substitutes formula strings into the display text field of viewport cells that have formulas. Invalidates all prefetch bounds so the next viewport refresh fetches fresh data with the correct display mode. ## WorkbookChanges Sub-API for opt-in workbook-level change tracking. ### Methods #### track ```typescript track(options?: WorkbookTrackOptions): WorkbookChangeTracker; ``` Create a change tracker that accumulates cell-level change records across all sheets from this point forward. @param options - Optional origin filters and limit @returns A WorkbookChangeTracker handle — call collect() to drain, close() when done ## WorksheetWhatIf Sub-API for What-If analysis operations. ### Methods #### goalSeek ```typescript goalSeek(targetCell: string, targetValue: number, changingCell: string): Promise; ``` Find the input value that makes a formula produce a target result (Excel's "Goal Seek" equivalent). Use this to back-solve for an unknown assumption — e.g., find the discount rate that produces a specific NPV, or the growth rate needed to hit a revenue target. Example — find WACC that yields NPV = 0: ``` // B1 = WACC assumption, B5 = =NPV(B1, C10:C20) const result = await ws.whatIf.goalSeek('B5', 0, 'B1'); if (result.found) { await ws.cells.setCellValue('B1', result.solutionValue); } ``` The method is read-only — the changing cell is restored after evaluation. Call setCellValue() yourself to apply the solution. @param targetCell - A1 address of the cell containing the formula to evaluate @param targetValue - The desired result value @param changingCell - A1 address of the input cell to vary @returns GoalSeekResult with solutionValue if found #### dataTable ```typescript dataTable( formulaCell: string, options: { rowInputCell?: string | null; colInputCell?: string | null; rowValues: (string | number | boolean | null)[]; colValues: (string | number | boolean | null)[]; }, ): Promise; ``` Compute a sensitivity/scenario table by evaluating a formula with different input values (Excel's "What-If Data Table" equivalent). Use this for DCF sensitivity tables, LBO return grids, or any two-dimensional parameter sweep. One-variable table: provide either `rowInputCell` or `colInputCell`. Two-variable table: provide both. Example — 2D sensitivity grid (WACC x Terminal Growth Rate): ``` // B1 = WACC assumption (e.g. 0.10) // B2 = Terminal growth rate (e.g. 0.025) // B3 = =NPV(B1, C10:C20) + terminal_value (the formula to sweep) const result = await ws.whatIf.dataTable('B3', { rowInputCell: 'B1', colInputCell: 'B2', rowValues: [0.08, 0.09, 0.10, 0.11, 0.12], colValues: [0.015, 0.020, 0.025, 0.030, 0.035], }); // result.results is a 5x5 grid of NPV values // Write to sheet: iterate result.results and call setCells() ``` Input cells must already contain a value before calling this method. The method is read-only — input cells are restored after evaluation. @param formulaCell - A1 address of the cell containing the formula to evaluate @param options - Input cells and substitution values @returns 2D grid of computed results (DataTableResult) ## WorksheetSmartArt ### Methods #### add ```typescript add(config: SmartArtConfig): Promise; ``` Add a SmartArt diagram to the sheet. Returns the object ID. #### get ```typescript get(objectId: string): Promise; ``` Get a SmartArt diagram by object ID, or null if not found. #### remove ```typescript remove(objectId: string): Promise; ``` Remove a SmartArt diagram by object ID. #### list ```typescript list(): Promise; ``` List all SmartArt diagrams on the sheet. #### duplicate ```typescript duplicate(objectId: string): Promise; ``` Duplicate a SmartArt diagram. Returns the new object ID. #### addNode ```typescript addNode( objectId: string, text: string, position: NodePosition, referenceNodeId: NodeId | null, ): NodeId | Promise; ``` Add a node to a diagram. Returns the new node ID. #### removeNode ```typescript removeNode(objectId: string, nodeId: NodeId): void | Promise; ``` Remove a node from a diagram. #### updateNode ```typescript updateNode( objectId: string, nodeId: NodeId, updates: Partial, ): void | Promise; ``` Update a node's properties. #### moveNode ```typescript moveNode(objectId: string, nodeId: NodeId, direction: NodeMoveDirection): void | Promise; ``` Move a node in the hierarchy. #### getNode ```typescript getNode( objectId: string, nodeId: NodeId, ): SmartArtNode | undefined | Promise; ``` Get a node by ID. #### getDiagram ```typescript getDiagram(objectId: string): SmartArtDiagram | undefined | Promise; ``` Get a diagram by object ID. #### getDiagramsOnSheet ```typescript getDiagramsOnSheet(): SmartArtDiagram[] | Promise; ``` Get all diagrams on this sheet. #### changeLayout ```typescript changeLayout(objectId: string, newLayoutId: string): void | Promise; ``` Change the diagram layout. #### changeQuickStyle ```typescript changeQuickStyle(objectId: string, quickStyleId: string): void | Promise; ``` Change the quick style. #### changeColorTheme ```typescript changeColorTheme(objectId: string, colorThemeId: string): void | Promise; ``` Change the color theme. #### getComputedLayout ```typescript getComputedLayout( objectId: string, ): ComputedLayout | undefined | Promise; ``` Get the computed layout for a diagram. Returns cached result if valid. #### invalidateLayout ```typescript invalidateLayout(objectId: string): void; ``` Invalidate the cached layout for a diagram. #### invalidateAllLayouts ```typescript invalidateAllLayouts(): void; ``` Invalidate all cached layouts. ## WorksheetChanges Sub-API for opt-in change tracking on a worksheet. ### Methods #### track ```typescript track(options?: ChangeTrackOptions): ChangeTracker; ``` Create a change tracker that accumulates cell-level change records from this point forward. @param options - Optional scope and origin filters @returns A ChangeTracker handle — call collect() to drain, close() when done ## WorksheetFormats Sub-API for cell formatting operations on a worksheet. ### Methods #### set ```typescript set(address: string, format: CellFormat): Promise; ``` Set format for a single cell. @param address - A1-style cell address (e.g. "A1", "B3") @param format - Format properties to apply @example // Bold red currency await ws.formats.set('A1', { bold: true, fontColor: '#ff0000', numberFormat: '$#,##0.00' }); // Date format await ws.formats.set('B1', { numberFormat: 'YYYY-MM-DD' }); // Header style await ws.formats.set('A1', { bold: true, fontSize: 14, backgroundColor: '#4472c4', fontColor: '#ffffff' }); #### setRange ```typescript setRange(range: string, format: CellFormat): Promise; ``` Set format for a contiguous range. @param range - A1-style range string (e.g. "A1:B2") @param format - Format properties to apply @example // Currency column await ws.formats.setRange('B2:B100', { numberFormat: '$#,##0.00' }); // Header row with borders await ws.formats.setRange('A1:F1', { bold: true, backgroundColor: '#4472c4', fontColor: '#ffffff', borders: { bottom: { style: 'medium', color: '#2f5496' } } }); #### setRanges ```typescript setRanges(ranges: CellRange[], format: CellFormat): Promise; ``` Set format for multiple ranges, with full row/column optimization. @param ranges - Array of range objects @param format - Format properties to apply #### clear ```typescript clear(address: string): Promise; ``` Clear format from a single cell, resetting it to default. @param address - A1-style cell address #### get ```typescript get(address: string): Promise; ``` Get the fully-resolved format of a single cell. Returns a dense CellFormat with all fields present (null for unset properties, never undefined). Includes the full cascade (default → col → row → table → cell → CF) with theme colors resolved to hex. @param address - A1-style cell address @returns The resolved cell format (always an object, never null) #### getDisplayedCellProperties ```typescript getDisplayedCellProperties(address: string): Promise; ``` Get the fully-resolved displayed format of a single cell. Includes the full 6-layer cascade (default → col → row → table → cell → CF) with theme colors resolved to hex. Unlike `get()`, this includes the conditional formatting overlay. @param address - A1-style cell address @returns The displayed cell format with CF applied #### getDisplayedRangeProperties ```typescript getDisplayedRangeProperties(range: string): Promise; ``` Get displayed formats for a rectangular range. Each element includes the full 6-layer cascade with CF overlay. Maximum 10,000 cells per call. @param range - A1-style range string (e.g. "A1:C3") @returns 2D array of displayed cell formats #### adjustIndent ```typescript adjustIndent(address: string, amount: number): Promise; ``` Adjust the indent level of a cell by a relative amount. @param address - A1-style cell address @param amount - Relative indent change (positive to increase, negative to decrease) #### clearFill ```typescript clearFill(address: string): Promise; ``` Clear only fill properties of a cell (backgroundColor, patternType, patternForegroundColor, gradientFill). Unlike `clear()`, this preserves font, alignment, borders, and other formatting. @param address - A1-style cell address #### getNumberFormatCategory ```typescript getNumberFormatCategory(address: string): Promise; ``` Get the auto-derived number format category for a cell based on its format code. @param address - A1-style cell address @returns The detected NumberFormatType category #### getNumberFormatLocal ```typescript getNumberFormatLocal(address: string): Promise; ``` Get the locale-aware number format for a cell (OfficeJS Range.numberFormatLocal equivalent). Resolves the `[$-LCID]` token in the stored format code and transforms separators to match the locale's conventions. For example, a cell with format `[$-407]#,##0.00` returns `#.##0,00` (German conventions). If no LCID token is present, returns the raw format code unchanged. @param address - A1-style cell address @returns The locale-resolved format string #### setNumberFormatLocal ```typescript setNumberFormatLocal(address: string, localFormat: string, locale: string): Promise; ``` Set the locale-aware number format for a cell (OfficeJS Range.numberFormatLocal equivalent). Encodes the locale-specific format by prepending the appropriate `[$-LCID]` token and transforming separators to internal (en-US) conventions. For example, setting `#.##0,00` with locale `de-DE` stores `[$-407]#,##0.00`. @param address - A1-style cell address @param localFormat - The locale-specific format string @param locale - BCP-47 locale tag (e.g., "de-DE", "fr-FR") #### applyPattern ```typescript applyPattern( format: CellFormat, sourceRange: CellRange | null, targetRange: CellRange, ): Promise; ``` Apply a format pattern from a source range to a target range. When the target range is larger than the source range, the source format pattern is tiled to fill the target (like Excel's Format Painter with multi-cell sources). @param format - The base format to apply (used when sourceRange is null or single-cell) @param sourceRange - Source range for pattern replication, or null for simple application @param targetRange - Target range to apply formats to #### getCellProperties ```typescript getCellProperties(range: string): Promise>>; ``` Get effective (resolved) cell formats for a rectangular range. Returns a 2D array (row-major) where each element is the fully resolved format from the 5-layer cascade (default -> col -> row -> table -> cell). Cells with no explicit format may return null. @param range - A1-style range string (e.g. "A1:C3") @returns 2D array of CellFormat (or null for cells with default format) #### setCellProperties ```typescript setCellProperties( updates: Array<{ row: number; col: number; format: Partial }>, ): Promise; ``` Set cell formats for a batch of individual cells with heterogeneous formats. Unlike setRange (which applies one format to all cells), this allows each cell to receive a different format. Formats merge with existing cell formats on a per-property basis. @param updates - Array of {row, col, format} entries #### getRowProperties ```typescript getRowProperties(rows: number[]): Promise>; ``` Get row-level formats for the specified rows. Returns a Map from row index to CellFormat (only rows with explicit formats are included; rows with no format are omitted). @param rows - Row indices (0-based) @returns Map of row index to CellFormat #### setRowProperties ```typescript setRowProperties(updates: Map>): Promise; ``` Set row-level formats for multiple rows. Formats merge with existing row formats on a per-property basis. @param updates - Map of row index to format properties #### getColumnProperties ```typescript getColumnProperties(cols: number[]): Promise>; ``` Get column-level formats for the specified columns. Returns a Map from column index to CellFormat (only columns with explicit formats are included). @param cols - Column indices (0-based) @returns Map of column index to CellFormat #### setColumnProperties ```typescript setColumnProperties(updates: Map>): Promise; ``` Set column-level formats for multiple columns. Formats merge with existing column formats on a per-property basis. @param updates - Map of column index to format properties ## WorksheetLayout WorksheetLayout — Sub-API for row/column dimension and visibility operations. Provides methods to read and modify row heights, column widths, and row/column visibility (hide/unhide). ### Methods #### getRowHeight ```typescript getRowHeight(row: number): Promise; ``` Get the height of a row in pixels. @param row - Row index (0-based) @returns Row height in pixels #### setRowHeight ```typescript setRowHeight(row: number, height: number): Promise; ``` Set the height of a row. @param row - Row index (0-based) @param height - Height in pixels (must be > 0) #### getColumnWidth ```typescript getColumnWidth(col: number): Promise; ``` Get the width of a column in character-width units (relative to the Normal style font's maximum digit width, matching OOXML/Excel convention). @param col - Column index (0-based) @returns Column width in character-width units #### setColumnWidth ```typescript setColumnWidth(col: number, width: number): Promise; ``` Set the width of a column in character-width units (relative to the Normal style font's maximum digit width, matching OOXML/Excel convention). @param col - Column index (0-based) @param width - Width in character-width units (must be > 0) #### getColumnWidthPx ```typescript getColumnWidthPx(col: number): Promise; ``` Get the width of a column in pixels. @param col - Column index (0-based) @returns Column width in pixels #### setColumnWidthPx ```typescript setColumnWidthPx(col: number, widthPx: number): Promise; ``` Set the width of a column in pixels. @param col - Column index (0-based) @param widthPx - Width in pixels (must be > 0) #### autoFitColumn ```typescript autoFitColumn(col: number): Promise; ``` Auto-fit a column width to its content. @param col - Column index (0-based) #### autoFitColumns ```typescript autoFitColumns(cols: number[]): Promise; ``` Auto-fit multiple columns to their content in a single batch call. @param cols - Array of column indices (0-based) #### autoFitRow ```typescript autoFitRow(row: number): Promise; ``` Auto-fit a row height to its content. @param row - Row index (0-based) #### autoFitRows ```typescript autoFitRows(rows: number[]): Promise; ``` Auto-fit multiple rows to their content in a single batch call. @param rows - Array of row indices (0-based) #### getRowHeightsBatch ```typescript getRowHeightsBatch(startRow: number, endRow: number): Promise>; ``` Get row heights for a range of rows. @param startRow - Start row index (0-based, inclusive) @param endRow - End row index (0-based, inclusive) @returns Array of [rowIndex, height] pairs #### getColWidthsBatch ```typescript getColWidthsBatch(startCol: number, endCol: number): Promise>; ``` Get column widths for a range of columns in character-width units (relative to the Normal style font's maximum digit width, matching OOXML/Excel convention). @param startCol - Start column index (0-based, inclusive) @param endCol - End column index (0-based, inclusive) @returns Array of [colIndex, charWidth] pairs #### getColWidthsBatchPx ```typescript getColWidthsBatchPx(startCol: number, endCol: number): Promise>; ``` Get column widths for a range of columns in pixels. @param startCol - Start column index (0-based, inclusive) @param endCol - End column index (0-based, inclusive) @returns Array of [colIndex, widthPx] pairs #### setRowVisible ```typescript setRowVisible(row: number, visible: boolean): Promise; ``` Set the visibility of a single row. @param row - Row index (0-based) @param visible - True to show, false to hide #### setColumnVisible ```typescript setColumnVisible(col: number, visible: boolean): Promise; ``` Set the visibility of a single column. @param col - Column index (0-based) @param visible - True to show, false to hide #### isRowHidden ```typescript isRowHidden(row: number): Promise; ``` Check whether a row is hidden. @param row - Row index (0-based) @returns True if the row is hidden #### isColumnHidden ```typescript isColumnHidden(col: number): Promise; ``` Check whether a column is hidden. @param col - Column index (0-based) @returns True if the column is hidden #### unhideRows ```typescript unhideRows(startRow: number, endRow: number): Promise; ``` Unhide all rows in a range. @param startRow - Start row index (0-based, inclusive) @param endRow - End row index (0-based, inclusive) #### unhideColumns ```typescript unhideColumns(startCol: number, endCol: number): Promise; ``` Unhide all columns in a range. @param startCol - Start column index (0-based, inclusive) @param endCol - End column index (0-based, inclusive) #### hideRows ```typescript hideRows(rows: number[]): Promise; ``` Hide multiple rows by index. @param rows - Array of row indices to hide (0-based) #### getHiddenRowsBitmap ```typescript getHiddenRowsBitmap(): Promise>; ``` Get the set of all hidden row indices. @returns Set of hidden row indices #### getHiddenColumnsBitmap ```typescript getHiddenColumnsBitmap(): Promise>; ``` Get the set of all hidden column indices. @returns Set of hidden column indices #### resetRowHeight ```typescript resetRowHeight(row: number): Promise; ``` Reset a row's height to the sheet default. @param row - Row index (0-based) #### resetColumnWidth ```typescript resetColumnWidth(col: number): Promise; ``` Reset a column's width to the sheet default in character-width units (relative to the Normal style font's maximum digit width, matching OOXML/Excel convention). @param col - Column index (0-based) ## WorksheetView Sub-API for worksheet view and display operations. ### Methods #### freezeRows ```typescript freezeRows(count: number): Promise; ``` Freeze the top N rows. Preserves any existing column freeze. @param count - Number of rows to freeze (0 to unfreeze rows) #### freezeColumns ```typescript freezeColumns(count: number): Promise; ``` Freeze the left N columns. Preserves any existing row freeze. @param count - Number of columns to freeze (0 to unfreeze columns) #### unfreeze ```typescript unfreeze(): Promise; ``` Remove all frozen panes (both rows and columns). #### getFrozenPanes ```typescript getFrozenPanes(): Promise<{ rows: number; cols: number }>; ``` Get the current frozen panes configuration. @returns Object with the number of frozen rows and columns #### freezeAt ```typescript freezeAt(range: string): Promise; ``` Freeze rows and columns simultaneously using a range reference. The top-left cell of the range becomes the first unfrozen cell. For example, freezeAt("B3") freezes 2 rows and 1 column. @param range - A cell reference (e.g., "B3") indicating the split point #### getSplitConfig ```typescript getSplitConfig(): Promise; ``` Get the current split view configuration. @returns The split configuration, or null if the view is not split #### setSplitConfig ```typescript setSplitConfig(config: SplitViewportConfig | null): Promise; ``` Set or clear the split view configuration. @param config - Split configuration to apply, or null to remove split #### setGridlines ```typescript setGridlines(show: boolean): Promise; ``` Show or hide gridlines. @param show - True to show gridlines, false to hide #### setHeadings ```typescript setHeadings(show: boolean): Promise; ``` Show or hide row/column headings. @param show - True to show headings, false to hide #### getViewOptions ```typescript getViewOptions(): Promise; ``` Get the current view options (gridlines, headings). @returns Current view options #### getTabColor ```typescript getTabColor(): Promise; ``` Get the tab color of this worksheet. @returns The tab color as a hex string, or null if no color is set #### setTabColor ```typescript setTabColor(color: string | null): Promise; ``` Set or clear the tab color for this worksheet. @param color - Hex color string, or null to clear #### getScrollPosition ```typescript getScrollPosition(): Promise; ``` Get the persistent scroll position (cell-level) for this sheet. #### setScrollPosition ```typescript setScrollPosition(topRow: number, leftCol: number): Promise; ``` Set the persistent scroll position (cell-level) for this sheet. ## WorksheetStructure ### Methods #### insertRows ```typescript insertRows(index: number, count: number): Promise; ``` Insert rows starting at the given 0-based index. #### deleteRows ```typescript deleteRows(index: number, count: number): Promise; ``` Delete rows starting at the given 0-based index. #### insertColumns ```typescript insertColumns(index: number, count: number): Promise; ``` Insert columns starting at the given 0-based index. #### deleteColumns ```typescript deleteColumns(index: number, count: number): Promise; ``` Delete columns starting at the given 0-based index. #### insertCellsWithShift ```typescript insertCellsWithShift( startRow: number, startCol: number, endRow: number, endCol: number, direction: 'right' | 'down', ): Promise; ``` Insert cells by shifting existing cells in the specified direction. #### deleteCellsWithShift ```typescript deleteCellsWithShift( startRow: number, startCol: number, endRow: number, endCol: number, direction: 'left' | 'up', ): Promise; ``` Delete cells by shifting remaining cells in the specified direction. #### getRowCount ```typescript getRowCount(): Promise; ``` Get the number of rows with data. #### getColumnCount ```typescript getColumnCount(): Promise; ``` Get the number of columns with data. #### textToColumns ```typescript textToColumns(range: string, options: TextToColumnsOptions): Promise; ``` Split text in a column into multiple columns. #### removeDuplicates ```typescript removeDuplicates( range: string, columns: number[], hasHeaders?: boolean, ): Promise; ``` Remove duplicate rows in a range. #### merge ```typescript merge(range: string): Promise; ``` Merge cells by A1 range. #### unmerge ```typescript unmerge(range: string): Promise; ``` Unmerge cells by A1 range. #### getMergedRegions ```typescript getMergedRegions(): Promise; ``` Get all merged regions in the sheet. #### getMergeAtCell ```typescript getMergeAtCell(address: string): Promise; ``` Get the merge containing a cell by A1 address, or null if not merged. ## WorksheetCharts ### Methods #### add ```typescript add(config: ChartConfig): Promise; ``` Add a chart to the sheet. Returns the chart ID. #### get ```typescript get(chartId: string): Promise; ``` Get a chart by ID, or null if not found. #### update ```typescript update(chartId: string, updates: Partial): Promise; ``` Update a chart's configuration. #### remove ```typescript remove(chartId: string): Promise; ``` Remove a chart by ID. #### list ```typescript list(): Promise; ``` List all charts in the sheet. #### duplicate ```typescript duplicate(chartId: string): Promise; ``` Duplicate a chart, offsetting the copy by 2 rows. Returns the new chart ID. #### exportImage ```typescript exportImage(chartId: string, options?: ImageExportOptions): Promise; ``` Export a chart as an image. Note: This is a stub — actual rendering requires a canvas context. The bridge integration will be wired in Wave 4. #### setDataRange ```typescript setDataRange(chartId: string, range: string): Promise; ``` Set a chart's data range (A1 notation). #### setType ```typescript setType(chartId: string, type: ChartType, subType?: string): Promise; ``` Set a chart's type and optional sub-type. #### getCount ```typescript getCount(): Promise; ``` Get the total number of charts on this sheet. #### getByName ```typescript getByName(name: string): Promise; ``` Find a chart by its name, or null if not found. #### bringToFront ```typescript bringToFront(chartId: string): Promise; ``` Bring a chart to the front (highest z-index). #### sendToBack ```typescript sendToBack(chartId: string): Promise; ``` Send a chart to the back (lowest z-index). #### bringForward ```typescript bringForward(chartId: string): Promise; ``` Bring a chart forward by one layer. #### sendBackward ```typescript sendBackward(chartId: string): Promise; ``` Send a chart backward by one layer. #### linkToTable ```typescript linkToTable(chartId: string, tableId: string): Promise; ``` Link a chart to a table so it auto-updates with the table's data. #### unlinkFromTable ```typescript unlinkFromTable(chartId: string): Promise; ``` Unlink a chart from its source table. #### isLinkedToTable ```typescript isLinkedToTable(chartId: string): Promise; ``` Check whether a chart is linked to a table. #### addSeries ```typescript addSeries(chartId: string, config: SeriesConfig): Promise; ``` Add a data series to a chart. Returns the new series index. #### removeSeries ```typescript removeSeries(chartId: string, index: number): Promise; ``` Remove a data series by index. #### getSeries ```typescript getSeries(chartId: string, index: number): Promise; ``` Get a data series by index. #### updateSeries ```typescript updateSeries(chartId: string, index: number, updates: Partial): Promise; ``` Update a data series at the given index. #### getSeriesCount ```typescript getSeriesCount(chartId: string): Promise; ``` Get the number of data series in a chart. #### reorderSeries ```typescript reorderSeries(chartId: string, fromIndex: number, toIndex: number): Promise; ``` Reorder a series from one index to another. #### setSeriesValues ```typescript setSeriesValues(chartId: string, index: number, range: string): Promise; ``` Set the values range for a series (A1 notation). #### setSeriesCategories ```typescript setSeriesCategories(chartId: string, index: number, range: string): Promise; ``` Set the categories range for a series (A1 notation). #### formatPoint ```typescript formatPoint( chartId: string, seriesIndex: number, pointIndex: number, format: { fill?: string; border?: ChartBorder }, ): Promise; ``` Format an individual data point within a series. #### setPointDataLabel ```typescript setPointDataLabel( chartId: string, seriesIndex: number, pointIndex: number, config: DataLabelConfig, ): Promise; ``` Set the data label configuration for an individual data point. #### addTrendline ```typescript addTrendline( chartId: string, seriesIndex: number, config: TrendlineConfig, ): Promise; ``` Add a trendline to a series. Returns the new trendline index. #### removeTrendline ```typescript removeTrendline( chartId: string, seriesIndex: number, trendlineIndex: number, ): Promise; ``` Remove a trendline from a series by index. #### getTrendline ```typescript getTrendline( chartId: string, seriesIndex: number, trendlineIndex: number, ): Promise; ``` Get a trendline configuration by index, or null if not found. #### getTrendlineCount ```typescript getTrendlineCount(chartId: string, seriesIndex: number): Promise; ``` Get the number of trendlines on a series. #### getDataTable ```typescript getDataTable(chartId: string): Promise; ``` Get the chart's data table configuration, or null if none. #### getItemAt ```typescript getItemAt(index: number): Promise; ``` Get a chart by its positional index, or null if out of range. #### setBubbleSizes ```typescript setBubbleSizes(chartId: string, seriesIndex: number, range: string): Promise; ``` Set the bubble sizes range for a series (A1 notation). #### onActivated ```typescript onActivated(handler: (args: { chartId: string }) => void): { dispose(): void }; ``` Register a handler for chart activation events. Returns a disposable. #### onDeactivated ```typescript onDeactivated(handler: (args: { chartId: string }) => void): { dispose(): void }; ``` Register a handler for chart deactivation events. Returns a disposable. #### getAxisItem ```typescript getAxisItem( chartId: string, type: 'category' | 'value' | 'series', group: 'primary' | 'secondary', ): Promise; ``` Get an axis by OfficeJS type/group identifiers. #### setAxisTitle ```typescript setAxisTitle(chartId: string, axisType: 'category' | 'value', formula: string): Promise; ``` Set axis title from a formula string. #### setCategoryNames ```typescript setCategoryNames(chartId: string, range: string): Promise; ``` Set category axis labels from a cell range (A1 notation). #### getSeriesDimensionValues ```typescript getSeriesDimensionValues( chartId: string, seriesIndex: number, dimension: ChartSeriesDimension, ): Promise<(string | number)[]>; ``` Get computed values for a series dimension. #### getSeriesDimensionDataSourceString ```typescript getSeriesDimensionDataSourceString( chartId: string, seriesIndex: number, dimension: ChartSeriesDimension, ): Promise; ``` Get the range/formula string for a series dimension. #### getSeriesDimensionDataSourceType ```typescript getSeriesDimensionDataSourceType( chartId: string, seriesIndex: number, dimension: ChartSeriesDimension, ): Promise; ``` Get the data source type for a series dimension ('range' | 'literal' | 'formula'). #### getDataLabelSubstring ```typescript getDataLabelSubstring( chartId: string, seriesIndex: number, pointIndex: number, start: number, length: number, ): Promise; ``` Get a rich text substring from a data label. #### setDataLabelHeight ```typescript setDataLabelHeight( chartId: string, seriesIndex: number, pointIndex: number, value: number, ): Promise; ``` Set the height of a data label. #### setDataLabelWidth ```typescript setDataLabelWidth( chartId: string, seriesIndex: number, pointIndex: number, value: number, ): Promise; ``` Set the width of a data label. #### getDataLabelTailAnchor ```typescript getDataLabelTailAnchor( chartId: string, seriesIndex: number, pointIndex: number, ): Promise<{ row: number; col: number }>; ``` Get the tail anchor point for a data label's leader line. #### setTitleFormula ```typescript setTitleFormula(chartId: string, formula: string): Promise; ``` Set chart title from a formula string. #### getTitleSubstring ```typescript getTitleSubstring(chartId: string, start: number, length: number): Promise; ``` Get a rich text substring from the chart title. #### activate ```typescript activate(chartId: string): Promise; ``` Activate (select + focus) a chart. Emits 'chart:selected' event and scrolls chart into view. ## WorksheetObjectCollection ### Methods #### get ```typescript get(id: string): Promise; ``` Get a floating object handle by ID. Returns null if not found. #### getInfo ```typescript getInfo(id: string): Promise; ``` Get summary info (with spatial fields) for a floating object. Returns null if not found. #### list ```typescript list(): Promise; ``` List all floating objects on the sheet. #### deleteMany ```typescript deleteMany(ids: string[]): Promise; ``` Delete multiple floating objects. Returns count of successfully deleted. #### delete ```typescript delete(id: string): Promise; ``` Delete a single floating object by ID. Returns true if deleted. #### bringToFront ```typescript bringToFront(id: string): Promise; ``` Bring a floating object to the front (highest z-order). #### sendToBack ```typescript sendToBack(id: string): Promise; ``` Send a floating object to the back (lowest z-order). #### bringForward ```typescript bringForward(id: string): Promise; ``` Bring a floating object forward by one layer. #### sendBackward ```typescript sendBackward(id: string): Promise; ``` Send a floating object backward by one layer. #### update ```typescript update(objectId: string, updates: Record): Promise; ``` Update arbitrary properties of a floating object. #### convertToWordArt ```typescript convertToWordArt(objectId: string, presetId?: string): Promise; ``` Convert a text box to WordArt by applying WordArt styling. #### convertToTextBox ```typescript convertToTextBox(objectId: string): Promise; ``` Convert WordArt back to a regular text box by removing WordArt styling. #### computeObjectBounds ```typescript computeObjectBounds(objectId: string): Promise; ``` Compute pixel bounding box for a floating object (async — uses ComputeBridge). #### computeAllObjectBounds ```typescript computeAllObjectBounds(): Promise>; ``` Batch-compute pixel bounds for all floating objects on this sheet. #### group ```typescript group(ids: string[]): Promise; ``` Group multiple floating objects. Returns the group ID. #### ungroup ```typescript ungroup(groupId: string): Promise; ``` Ungroup a floating object group. ## WorksheetShapeCollection ### Methods #### get ```typescript get(id: string): Promise; ``` #### list ```typescript list(): Promise; ``` #### add ```typescript add(config: ShapeConfig): Promise; ``` #### getItemAt ```typescript getItemAt(index: number): Promise; ``` Get a shape by zero-based index. Returns null if index is out of range. ## WorksheetPictureCollection ### Methods #### get ```typescript get(id: string): Promise; ``` #### list ```typescript list(): Promise; ``` #### add ```typescript add(config: PictureConfig): Promise; ``` ## WorksheetTextBoxCollection ### Methods #### get ```typescript get(id: string): Promise; ``` #### list ```typescript list(): Promise; ``` #### add ```typescript add(config: TextBoxConfig): Promise; ``` ## WorksheetDrawingCollection ### Methods #### get ```typescript get(id: string): Promise; ``` #### list ```typescript list(): Promise; ``` #### add ```typescript add(position: Partial, options?: CreateDrawingOptions): Promise; ``` ## WorksheetEquationCollection ### Methods #### get ```typescript get(id: string): Promise; ``` #### list ```typescript list(): Promise; ``` #### add ```typescript add(config: EquationConfig): Promise; ``` ## WorksheetWordArtCollection ### Methods #### get ```typescript get(id: string): Promise; ``` #### list ```typescript list(): Promise; ``` #### add ```typescript add(config: WordArtConfig): Promise; ``` ## WorksheetConnectorCollection Connector collection — get/list only. add() deferred until ConnectorConfig exists. ### Methods #### get ```typescript get(id: string): Promise; ``` #### list ```typescript list(): Promise; ``` ## WorksheetFilters Sub-API for filter operations on a worksheet. ### Methods #### setAutoFilter ```typescript setAutoFilter(range: string): Promise; ``` Set an auto-filter on the sheet by parsing an A1-style range string. @param range - A1-style range string (e.g. "A1:D100") #### createAutoFilter ```typescript createAutoFilter(range: CellRange): Promise; ``` Create an auto-filter from a CellRange (position-based). @param range - Range object with start/end row and column #### clearAutoFilter ```typescript clearAutoFilter(): Promise; ``` Clear the auto-filter from the sheet. Removes all filters, not just criteria. #### getAutoFilter ```typescript getAutoFilter(): Promise; ``` Get the current auto-filter state. @returns The filter state, or null if no auto-filter is set #### getForRange ```typescript getForRange(range: CellRange): Promise<{ id: string } | null>; ``` Get the filter overlapping a range, or null if none. @param range - Range to check for filter overlap @returns Object with filter ID if found, or null #### remove ```typescript remove(filterId: string): Promise; ``` Remove a specific filter by its ID. @param filterId - Filter ID to remove #### setColumnFilter ```typescript setColumnFilter(col: number, criteria: ColumnFilterCriteria): Promise; ``` Set filter criteria for a column on the first auto-filter. @param col - Column index (0-based) @param criteria - Filter criteria to apply #### applyDynamicFilter ```typescript applyDynamicFilter(col: number, rule: DynamicFilterRule): Promise; ``` Apply a dynamic filter rule to a column on the first auto-filter. Dynamic filters are pre-defined rules resolved against live data, such as "above average", "below average", or date-relative rules like "today", "this month", etc. @param col - Column index (0-based) @param rule - Dynamic filter rule to apply #### clearColumnFilter ```typescript clearColumnFilter(col: number): Promise; ``` Clear filter criteria for a column on the first auto-filter. @param col - Column index (0-based) #### getUniqueValues ```typescript getUniqueValues(col: number): Promise; ``` Get unique values in a column (for filter dropdowns). Uses the first auto-filter. @param col - Column index (0-based) @returns Array of unique values #### setCriteria ```typescript setCriteria(filterId: string, col: number, criteria: ColumnFilterCriteria): Promise; ``` Set filter criteria for a column using filter ID. @param filterId - Filter ID @param col - Column index (0-based) @param criteria - Filter criteria to apply #### clearCriteria ```typescript clearCriteria(filterId: string, col: number): Promise; ``` Clear filter criteria for a column. @param filterId - Filter ID @param col - Column index (0-based) #### clearAllCriteria ```typescript clearAllCriteria(filterId: string): Promise; ``` Clear all filter criteria for a filter. Removes filters from all columns but keeps the filter structure intact. @param filterId - Filter ID #### apply ```typescript apply(filterId: string): Promise; ``` Apply a filter (Rust evaluates criteria and updates row visibility). @param filterId - Filter ID to apply #### getInfo ```typescript getInfo(filterId: string): Promise; ``` Get detailed filter info including resolved range and column filters. @param filterId - Filter ID @returns Detailed filter info, or null if not found #### getFilterUniqueValues ```typescript getFilterUniqueValues(filterId: string, col: number): Promise; ``` Get unique values for a filter column. @param filterId - Filter ID @param col - Column index (0-based) @returns Array of unique values #### list ```typescript list(): Promise; ``` List all filters in the sheet. @returns Array of filter info objects #### isEnabled ```typescript isEnabled(): Promise; ``` Whether any auto-filter exists on the sheet. @returns true if at least one filter is present #### isDataFiltered ```typescript isDataFiltered(): Promise; ``` Whether any filter on the sheet has active criteria applied. Returns true if at least one filter has non-empty column filters, meaning some rows may be hidden. @returns true if any column filter criteria are set #### listDetails ```typescript listDetails(): Promise; ``` List all filters with resolved numeric ranges and column filters. Single bridge call — avoids the N+1 pattern. @returns Array of detailed filter info objects #### getSortState ```typescript getSortState(filterId: string): Promise; ``` Get the sort state for a filter. @param filterId - Filter ID @returns Sort state, or null if no sort state set #### setSortState ```typescript setSortState(filterId: string, state: FilterSortState): Promise; ``` Set the sort state for a filter. @param filterId - Filter ID @param state - Sort state to set ## WorksheetFormControls ### Methods #### list ```typescript list(): FormControl[]; ``` Get all form controls on this sheet. #### get ```typescript get(controlId: string): FormControl | undefined; ``` Get a specific form control by ID. Returns undefined if not found or not on this sheet. #### getAtPosition ```typescript getAtPosition(row: number, col: number): FormControl[]; ``` Get form controls at a specific cell position (for hit testing). ## WorksheetConditionalFormatting Sub-API for conditional formatting operations on a worksheet. ### Methods #### add ```typescript add(ranges: CellRange[], rules: CFRuleInput[]): Promise; ``` Add a new conditional format with ranges and rules. The API assigns IDs and priorities — callers provide rule configuration only. @param ranges - Cell ranges this format applies to @param rules - Rule inputs (without id/priority) @returns The generated format ID #### get ```typescript get(formatId: string): Promise; ``` Get a conditional format by its ID. @param formatId - Format ID to look up @returns The conditional format, or null if not found #### update ```typescript update(formatId: string, updates: ConditionalFormatUpdate): Promise; ``` Update an existing conditional format. Supports replacing rules, ranges, and setting stopIfTrue on all rules. @param formatId - Format ID to update @param updates - Object with optional rules, ranges, and stopIfTrue #### clearRuleStyle ```typescript clearRuleStyle(formatId: string, ruleId: string): Promise; ``` Clear the style of a specific rule within a conditional format, resetting all style properties (font, fill, border, number format) to unset. @param formatId - Format ID containing the rule @param ruleId - Rule ID within the format to clear style for #### changeRuleType ```typescript changeRuleType(formatId: string, ruleId: string, newRule: CFRuleInput): Promise; ``` Change the type and configuration of a specific rule within a conditional format, preserving its ID and priority. This is the equivalent of OfficeJS's eight changeRuleTo*() methods, unified into one type-safe call using CFRuleInput. @param formatId - Format ID containing the rule @param ruleId - Rule ID to change @param newRule - New rule configuration (type + type-specific fields) #### getItemAt ```typescript getItemAt(index: number): Promise; ``` Get a conditional format by its index in the priority-ordered list. @param index - Zero-based index @returns The conditional format at that index, or null if out of bounds #### remove ```typescript remove(formatId: string): Promise; ``` Remove a conditional format by ID. @param formatId - Format ID to remove #### list ```typescript list(): Promise; ``` Get all conditional formats on the sheet. @returns Array of conditional format objects #### clear ```typescript clear(): Promise; ``` Clear all conditional formats from the sheet. #### clearInRanges ```typescript clearInRanges(ranges: CellRange[]): Promise; ``` Clear conditional formats that intersect with the given ranges. @param ranges - Ranges to clear conditional formats from #### reorder ```typescript reorder(formatIds: string[]): Promise; ``` Reorder conditional formats by format ID array (first = highest priority). @param formatIds - Array of format IDs in the desired order #### cloneForPaste ```typescript cloneForPaste( sourceSheetId: string, relativeCFs: Array<{ rules: any[]; rangeOffsets: Array<{ startRowOffset: number; startColOffset: number; endRowOffset: number; endColOffset: number; }>; }>, origin: { row: number; col: number }, isCut: boolean, ): Promise; ``` Clone conditional formats from source to target with offset. Used by format painter and paste operations. @param sourceSheetId - Source sheet ID (for cut operation reference removal) @param relativeCFs - Relative CF formats with range offsets @param origin - Target paste origin (row, col) @param isCut - Whether this is a cut operation ## WorksheetValidation Sub-API for data validation operations on a worksheet. ### Methods #### set ```typescript set(address: string, rule: ValidationRule): Promise; ``` Set a validation rule on a cell or range. @param address - A1-style cell or range address (e.g. "A1", "A1:B5") @param rule - Validation rule to apply #### remove ```typescript remove(address: string): Promise; ``` Remove validation from a cell (deletes any range schema covering the cell). @param address - A1-style cell address #### get ```typescript get(address: string): Promise; ``` Get the validation rule for a cell. @param address - A1-style cell address @returns The validation rule, or null if none #### getDropdownItems ```typescript getDropdownItems(address: string): Promise; ``` Get dropdown items for a cell with list validation. @param address - A1-style cell address @returns Array of dropdown item strings #### list ```typescript list(): Promise; ``` List all validation rules on the sheet. @returns Array of validation rules #### clear ```typescript clear(range: string): Promise; ``` Clear validation rules that overlap a range. @param range - A1-style range string (e.g. "A1:B5") #### delete ```typescript delete(id: string): Promise; ``` Delete a validation rule by its ID. @param id - Validation rule / range schema ID #### getErrorsInRange ```typescript getErrorsInRange( startRow: number, startCol: number, endRow: number, endCol: number, ): Promise>; ``` Get cells with validation errors in a range. @param startRow - Start row (0-based) @param startCol - Start column (0-based) @param endRow - End row (0-based) @param endCol - End column (0-based) @returns Array of {row, col} for cells with errors ## WorksheetTables Sub-API for table operations on a worksheet. ### Methods #### add ```typescript add(range: string, options?: TableOptions): Promise; ``` Create a new table from a cell range. @param range - A1-style range string (e.g. "A1:D10") @param options - Optional table creation settings (name, headers, style) @returns The created table information #### get ```typescript get(name: string): Promise; ``` Get a table by name. Tables are workbook-scoped, so the name is unique across all sheets. @param name - Table name @returns Table information, or null if not found #### list ```typescript list(): Promise; ``` List all tables in this worksheet. @returns Array of table information objects #### getAt ```typescript getAt(index: number): Promise; ``` Get a table by its position in the list of tables on this worksheet. @param index - Zero-based index into the table list @returns Table information, or null if the index is out of range #### getFirst ```typescript getFirst(): Promise; ``` Get the first table on this worksheet. Convenience shortcut equivalent to `getAt(0)`. @returns Table information, or null if no tables exist #### getColumnByName ```typescript getColumnByName(tableName: string, columnName: string): Promise; ``` Look up a column in a table by its header name. @param tableName - Table name @param columnName - Column header name to search for @returns The matching column, or null if not found #### remove ```typescript remove(name: string): Promise; ``` Remove a table definition, converting it back to a plain range. Cell data is preserved; only the table metadata is removed. @param name - Table name #### rename ```typescript rename(oldName: string, newName: string): Promise; ``` Rename a table. @param oldName - Current table name @param newName - New table name #### update ```typescript update(tableName: string, updates: Record): Promise; ``` Update a table's properties. @param tableName - Table name @param updates - Key-value pairs of properties to update #### getAtCell ```typescript getAtCell(row: number, col: number): Promise; ``` Get the table at a specific cell position, if one exists. @param row - Row index (0-based) @param col - Column index (0-based) @returns Table information, or null if no table exists at that cell #### clearFilters ```typescript clearFilters(tableName: string): Promise; ``` Clear all column filters on a table. @param tableName - Table name #### setStylePreset ```typescript setStylePreset(tableName: string, preset: string): Promise; ``` Set the visual style preset for a table. @param tableName - Table name @param preset - Style preset name (e.g. "TableStyleLight1") #### resize ```typescript resize(name: string, newRange: string): Promise; ``` Resize a table to a new range. @param name - Table name @param newRange - New A1-style range string #### addColumn ```typescript addColumn(name: string, columnName: string, position?: number): Promise; ``` Add a column to a table. @param name - Table name @param columnName - Name for the new column @param position - Column position (0-based index). If omitted, appends to the end. #### removeColumn ```typescript removeColumn(name: string, columnIndex: number): Promise; ``` Remove a column from a table by index. @param name - Table name @param columnIndex - Column index within the table (0-based) #### toggleTotalsRow ```typescript toggleTotalsRow(name: string): Promise; ``` Toggle the totals row visibility on a table. @param name - Table name #### toggleHeaderRow ```typescript toggleHeaderRow(name: string): Promise; ``` Toggle the header row visibility on a table. @param name - Table name #### applyAutoExpansion ```typescript applyAutoExpansion(tableName: string): Promise; ``` Apply auto-expansion to a table, extending it to include adjacent data. @param tableName - Table name #### setCalculatedColumn ```typescript setCalculatedColumn(tableName: string, colIndex: number, formula: string): Promise; ``` Set a calculated column formula for all data cells in a table column. @param tableName - Table name @param colIndex - Column index within the table (0-based) @param formula - The formula to set (e.g. "=[@Price]*[@Quantity]") #### clearCalculatedColumn ```typescript clearCalculatedColumn(tableName: string, colIndex: number): Promise; ``` Clear the calculated column formula from a table column, replacing with empty values. @param tableName - Table name @param colIndex - Column index within the table (0-based) #### getDataBodyRange ```typescript getDataBodyRange(name: string): Promise; ``` Get the A1-notation range covering the data body of a table (excludes header and totals rows). @param name - Table name @returns A1-notation range string, or null if the table has no data body rows #### getHeaderRowRange ```typescript getHeaderRowRange(name: string): Promise; ``` Get the A1-notation range covering the header row of a table. @param name - Table name @returns A1-notation range string, or null if the table has no header row #### getTotalRowRange ```typescript getTotalRowRange(name: string): Promise; ``` Get the A1-notation range covering the totals row of a table. @param name - Table name @returns A1-notation range string, or null if the table has no totals row #### addRow ```typescript addRow(tableName: string, index?: number, values?: CellValue[]): Promise; ``` Add a data row to a table. @param tableName - Table name @param index - Row index within the data body (0-based). If omitted, appends to the end. @param values - Optional cell values for the new row #### deleteRow ```typescript deleteRow(tableName: string, index: number): Promise; ``` Delete a data row from a table. @param tableName - Table name @param index - Row index within the data body (0-based) #### deleteRows ```typescript deleteRows(tableName: string, indices: number[]): Promise; ``` Delete multiple data rows from a table by their data-body-relative indices. Rows are deleted in descending index order to avoid index shifting. @param tableName - Table name @param indices - Array of row indices within the data body (0-based) #### deleteRowsAt ```typescript deleteRowsAt(tableName: string, index: number, count?: number): Promise; ``` Delete one or more contiguous data rows from a table starting at `index`. @param tableName - Table name @param index - Starting row index within the data body (0-based) @param count - Number of rows to delete (default 1) #### getRowCount ```typescript getRowCount(tableName: string): Promise; ``` Get the number of data rows in a table (excludes header and totals rows). @param tableName - Table name @returns Number of data rows #### getRowRange ```typescript getRowRange(tableName: string, index: number): Promise; ``` Get the A1-notation range for a specific data row. @param tableName - Table name @param index - Row index within the data body (0-based) @returns A1-notation range string #### getRowValues ```typescript getRowValues(tableName: string, index: number): Promise; ``` Get the cell values of a specific data row. @param tableName - Table name @param index - Row index within the data body (0-based) @returns Array of cell values #### setRowValues ```typescript setRowValues(tableName: string, index: number, values: CellValue[]): Promise; ``` Set the cell values of a specific data row. @param tableName - Table name @param index - Row index within the data body (0-based) @param values - Cell values to set #### getColumnDataBodyRange ```typescript getColumnDataBodyRange(tableName: string, columnIndex: number): Promise; ``` Get the A1-notation range covering the data body cells of a table column. @param tableName - Table name @param columnIndex - Column index within the table (0-based) @returns A1-notation range string, or null if no data body rows #### getColumnHeaderRange ```typescript getColumnHeaderRange(tableName: string, columnIndex: number): Promise; ``` Get the A1-notation range covering the header cell of a table column. @param tableName - Table name @param columnIndex - Column index within the table (0-based) @returns A1-notation range string, or null if no header row #### getColumnRange ```typescript getColumnRange(tableName: string, columnIndex: number): Promise; ``` Get the A1-notation range covering the entire table column (header + data + totals). @param tableName - Table name @param columnIndex - Column index within the table (0-based) @returns A1-notation range string, or null if column does not exist #### getColumnTotalRange ```typescript getColumnTotalRange(tableName: string, columnIndex: number): Promise; ``` Get the A1-notation range covering the totals cell of a table column. @param tableName - Table name @param columnIndex - Column index within the table (0-based) @returns A1-notation range string, or null if no totals row #### getColumnValues ```typescript getColumnValues(tableName: string, columnIndex: number): Promise; ``` Get the cell values of a table column (data body only). @param tableName - Table name @param columnIndex - Column index within the table (0-based) @returns Array of cell values #### setColumnValues ```typescript setColumnValues(tableName: string, columnIndex: number, values: CellValue[]): Promise; ``` Set the cell values of a table column (data body only). @param tableName - Table name @param columnIndex - Column index within the table (0-based) @param values - Cell values to set #### setHighlightFirstColumn ```typescript setHighlightFirstColumn(tableName: string, value: boolean): Promise; ``` Set whether the first column is highlighted. @param tableName - Table name @param value - Whether to highlight the first column #### setHighlightLastColumn ```typescript setHighlightLastColumn(tableName: string, value: boolean): Promise; ``` Set whether the last column is highlighted. @param tableName - Table name @param value - Whether to highlight the last column #### setShowBandedColumns ```typescript setShowBandedColumns(tableName: string, value: boolean): Promise; ``` Set whether banded columns are shown. @param tableName - Table name @param value - Whether to show banded columns #### setShowBandedRows ```typescript setShowBandedRows(tableName: string, value: boolean): Promise; ``` Set whether banded rows are shown. @param tableName - Table name @param value - Whether to show banded rows #### setShowFilterButton ```typescript setShowFilterButton(tableName: string, value: boolean): Promise; ``` Set whether filter buttons are shown on the header row. @param tableName - Table name @param value - Whether to show filter buttons #### setShowHeaders ```typescript setShowHeaders(tableName: string, visible: boolean): Promise; ``` Set whether the header row is visible. @param tableName - Table name @param visible - Whether to show the header row #### setShowTotals ```typescript setShowTotals(tableName: string, visible: boolean): Promise; ``` Set whether the totals row is visible. @param tableName - Table name @param visible - Whether to show the totals row #### sortApply ```typescript sortApply( tableName: string, fields: Array<{ columnIndex: number; ascending?: boolean }>, ): Promise; ``` Apply sort fields to a table. @param tableName - Table name @param fields - Array of sort field descriptors #### sortClear ```typescript sortClear(tableName: string): Promise; ``` Clear all sort fields from a table. @param tableName - Table name #### sortReapply ```typescript sortReapply(tableName: string): Promise; ``` Re-evaluate the most recently applied sort specification. Throws if no sort specification has been applied via `sortApply`. @param tableName - Table name #### getAutoFilter ```typescript getAutoFilter(tableName: string): Promise; ``` Get the auto-filter associated with a table. @param tableName - Table name @returns Filter information, or null if the table has no associated filter #### getRows ```typescript getRows(tableName: string): Promise; ``` Get a collection-like wrapper around the table's data rows. The returned object delegates to the existing row methods on this API. The `count` property is a snapshot taken at call time and does not live-update. @param tableName - Table name @returns A TableRowCollection object #### onTableAdded ```typescript onTableAdded(callback: (event: TableCreatedEvent) => void): CallableDisposable; ``` Subscribe to table creation events on this worksheet. Fires when a new table is added to this worksheet. @param callback - Handler invoked with the TableCreatedEvent @returns A disposable that unsubscribes the handler when disposed #### onTableDeleted ```typescript onTableDeleted(callback: (event: TableDeletedEvent) => void): CallableDisposable; ``` Subscribe to table deletion events on this worksheet. Fires when a table is removed from this worksheet. @param callback - Handler invoked with the TableDeletedEvent @returns A disposable that unsubscribes the handler when disposed #### onTableChanged ```typescript onTableChanged( tableName: string, callback: (event: TableUpdatedEvent) => void, ): CallableDisposable; ``` Subscribe to change events for a specific table. Fires when the table's structure or properties are updated (e.g. columns added/removed, style changed, renamed, resized, totals toggled, etc.). @param tableName - The name of the table to observe @param callback - Handler invoked with the TableUpdatedEvent @returns A disposable that unsubscribes the handler when disposed #### onSelectionChanged ```typescript onSelectionChanged( tableName: string, callback: (event: TableSelectionChangedEvent) => void, ): CallableDisposable; ``` Subscribe to selection change events for a specific table. Fires when the user's selection enters, moves within, or leaves the table. Note: events are only emitted once the selection machine is wired to emit `table:selection-changed`; until then the subscription is inert. @param tableName - The name of the table to observe @param callback - Handler invoked with the TableSelectionChangedEvent @returns A disposable that unsubscribes the handler when disposed ## WorksheetPivots Sub-API for pivot table operations on a worksheet. ### Methods #### add ```typescript add(config: PivotCreateConfig): Promise; ``` Create a new pivot table on this worksheet. Accepts either: - **Simple config**: `{ name, dataSource: "Sheet1!A1:D100", rowFields: ["Region"], ... }` Fields are auto-detected from source headers, placements are generated from field arrays. - **Full config**: `{ name, sourceSheetName, sourceRange, fields, placements, filters, ... }` Direct wire format — no conversion needed. @param config - Pivot table configuration @returns The created pivot table configuration (with generated id, timestamps) #### addWithSheet ```typescript addWithSheet( sheetName: string, config: PivotCreateConfig, ): Promise<{ sheetId: string; config: PivotTableConfig }>; ``` Atomically create a new sheet AND a pivot table on it. Both operations happen in a single transaction for undo atomicity. Accepts the same simple or full config formats as `add()`. @param sheetName - Name for the new sheet @param config - Pivot table configuration @returns The new sheet ID and the created pivot config #### remove ```typescript remove(name: string): Promise; ``` Remove a pivot table by name. @param name - Pivot table name #### rename ```typescript rename(pivotId: string, newName: string): Promise; ``` Rename a pivot table. @param pivotId - Pivot table ID @param newName - New name for the pivot table #### list ```typescript list(): Promise; ``` List all pivot tables on this worksheet. @returns Array of pivot table summary information #### get ```typescript get(name: string): Promise; ``` Get a pivot table handle by name. @param name - Pivot table name @returns A handle for the pivot table, or null if not found #### addField ```typescript addField( pivotId: string, fieldId: string, area: PivotFieldArea, options?: { position?: number; aggregateFunction?: AggregateFunction; sortOrder?: SortOrder; displayName?: string; showValuesAs?: ShowValuesAsConfig; }, ): Promise; ``` Add a field to a pivot table area. @param pivotId - Pivot table ID @param fieldId - Field ID to add @param area - Target area (row, column, value, or filter) @param options - Optional configuration (position, aggregateFunction, sortOrder, displayName) #### removeField ```typescript removeField(pivotId: string, fieldId: string, area: PivotFieldArea): Promise; ``` Remove a field from a pivot table area. @param pivotId - Pivot table ID @param fieldId - Field ID to remove @param area - Area to remove the field from #### moveField ```typescript moveField( pivotId: string, fieldId: string, fromArea: PivotFieldArea, toArea: PivotFieldArea, toPosition: number, ): Promise; ``` Move a field to a different area or position. @param pivotId - Pivot table ID @param fieldId - Field ID to move @param fromArea - Source area @param toArea - Target area @param toPosition - Target position within the area #### setAggregateFunction ```typescript setAggregateFunction( pivotId: string, fieldId: string, aggregateFunction: AggregateFunction, ): Promise; ``` Set the aggregate function for a value field. @param pivotId - Pivot table ID @param fieldId - Field ID (must be in the 'value' area) @param aggregateFunction - New aggregation function #### setShowValuesAs ```typescript setShowValuesAs( pivotId: string, fieldId: string, showValuesAs: ShowValuesAsConfig | null, ): Promise; ``` Set the "Show Values As" calculation for a value field. Only applies to fields in the 'value' area. Pass null to clear. @param pivotId - Pivot table ID @param fieldId - Field ID (must be in the 'value' area) @param showValuesAs - ShowValuesAs configuration, or null to clear #### setSortOrder ```typescript setSortOrder(pivotId: string, fieldId: string, sortOrder: SortOrder): Promise; ``` Set the sort order for a row or column field. @param pivotId - Pivot table ID @param fieldId - Field ID (must be in 'row' or 'column' area) @param sortOrder - Sort order ('asc', 'desc', or 'none') #### setFilter ```typescript setFilter(pivotId: string, fieldId: string, filter: Omit): Promise; ``` Set (add or update) a filter on a field. @param pivotId - Pivot table ID @param fieldId - Field ID to filter @param filter - Filter configuration (without fieldId) #### removeFilter ```typescript removeFilter(pivotId: string, fieldId: string): Promise; ``` Remove a filter from a field. @param pivotId - Pivot table ID @param fieldId - Field ID whose filter should be removed #### resetField ```typescript resetField(pivotId: string, fieldId: string): Promise; ``` Reset a field placement to defaults (clear aggregateFunction, sortOrder, displayName, showValuesAs, etc.) and remove any associated filter. @param pivotId - Pivot table ID @param fieldId - Field ID to reset #### setLayout ```typescript setLayout(pivotId: string, layout: Partial): Promise; ``` Set layout options for a pivot table. @param pivotId - Pivot table ID @param layout - Partial layout configuration to merge with existing #### setStyle ```typescript setStyle(pivotId: string, style: Partial): Promise; ``` Set style options for a pivot table. @param pivotId - Pivot table ID @param style - Partial style configuration to merge with existing #### detectFields ```typescript detectFields( sourceSheetId: string, range: { startRow: number; startCol: number; endRow: number; endCol: number }, ): Promise; ``` Detect fields from source data for pivot table creation. @param sourceSheetId - Sheet ID containing the source data @param range - Source data range @returns Array of detected pivot fields #### compute ```typescript compute(pivotId: string, forceRefresh?: boolean): Promise; ``` Compute a pivot table result (uses cache if available). @param pivotId - Pivot table ID @param forceRefresh - Force recomputation ignoring cache @returns Computed pivot table result #### queryPivot ```typescript queryPivot( pivotName: string, filters?: Record, ): Promise; ``` Query a pivot table by name, returning flat records optionally filtered by dimension values. Eliminates the need to manually traverse hierarchical PivotTableResult trees. @param pivotName - Pivot table name @param filters - Optional dimension filters: field name → value or array of values to include @returns Flat query result, or null if pivot not found or not computable #### refresh ```typescript refresh(pivotId: string): Promise; ``` Refresh a pivot table (recompute without cache). @param pivotId - Pivot table ID #### refreshAll ```typescript refreshAll(): Promise; ``` Refresh all pivot tables on this worksheet. #### getDrillDownData ```typescript getDrillDownData(pivotId: string, rowKey: string, columnKey: string): Promise; ``` Get drill-down data for a pivot table cell. @param pivotId - Pivot table ID @param rowKey - Row key from the pivot result @param columnKey - Column key from the pivot result @returns Source data rows that contribute to this cell #### addCalculatedField ```typescript addCalculatedField(pivotId: string, field: CalculatedField): Promise; ``` Add a calculated field to a pivot table. @param pivotId - Pivot table ID @param field - Calculated field definition (fieldId, name, formula) #### removeCalculatedField ```typescript removeCalculatedField(pivotId: string, fieldId: string): Promise; ``` Remove a calculated field from a pivot table. @param pivotId - Pivot table ID @param fieldId - Calculated field ID to remove #### updateCalculatedField ```typescript updateCalculatedField( pivotId: string, fieldId: string, updates: Partial>, ): Promise; ``` Update a calculated field on a pivot table. @param pivotId - Pivot table ID @param fieldId - Calculated field ID to update @param updates - Partial updates (name and/or formula) #### getRange ```typescript getRange(pivotId: string): Promise; ``` Get the full range occupied by the rendered pivot table. @param pivotId - Pivot table ID @returns CellRange covering the entire pivot table, or null if not computed #### getDataBodyRange ```typescript getDataBodyRange(pivotId: string): Promise; ``` Get the range of the data body (values only, excluding headers and totals row labels). @param pivotId - Pivot table ID @returns CellRange covering the data body, or null if not computed #### getColumnLabelRange ```typescript getColumnLabelRange(pivotId: string): Promise; ``` Get the range of column label headers. @param pivotId - Pivot table ID @returns CellRange covering the column headers, or null if not computed #### getRowLabelRange ```typescript getRowLabelRange(pivotId: string): Promise; ``` Get the range of row label headers. @param pivotId - Pivot table ID @returns CellRange covering the row headers, or null if not computed #### getFilterAxisRange ```typescript getFilterAxisRange(pivotId: string): Promise; ``` Get the range of the filter area (page fields above the pivot table). @param pivotId - Pivot table ID @returns CellRange covering filter dropdowns, or null if no filter fields #### getAllPivotItems ```typescript getAllPivotItems(pivotId: string): Promise; ``` Get pivot items for all placed fields (excluding value fields). Each item includes its display value, expansion state, and visibility. @param pivotId - Pivot table ID @returns Items grouped by field #### setPivotItemVisibility ```typescript setPivotItemVisibility( pivotId: string, fieldId: string, visibleItems: Record, ): Promise; ``` Set visibility of specific items in a field. Updates the field's filter include/exclude list. @param pivotId - Pivot table ID @param fieldId - Field ID @param visibleItems - Map of item value (as string) to visibility boolean #### toggleExpanded ```typescript toggleExpanded(pivotId: string, headerKey: string, isRow: boolean): Promise; ``` Toggle expansion state for a header. @param pivotId - Pivot table ID @param headerKey - Header key to toggle @param isRow - Whether this is a row header (true) or column header (false) @returns The new expansion state (true = expanded, false = collapsed) #### setAllExpanded ```typescript setAllExpanded(pivotId: string, expanded: boolean): Promise; ``` Set expansion state for all headers. @param pivotId - Pivot table ID @param expanded - Whether all headers should be expanded (true) or collapsed (false) #### getExpansionState ```typescript getExpansionState(pivotId: string): Promise; ``` Get the current expansion state for a pivot table. @param pivotId - Pivot table ID @returns Expansion state with expandedRows and expandedColumns maps ## WorksheetSlicers Sub-API for slicer operations on a worksheet. ### Methods #### add ```typescript add(config: SlicerConfig): Promise; ``` Create a new slicer on this worksheet. @param config - Slicer configuration (table, column, position) @returns The ID of the created slicer #### remove ```typescript remove(slicerId: string): Promise; ``` Remove a slicer from this worksheet. @param slicerId - ID of the slicer to remove #### list ```typescript list(): Promise; ``` List all slicers on this worksheet. @returns Array of slicer summary information #### get ```typescript get(slicerId: string): Promise; ``` Get a slicer by ID, including full state. @param slicerId - ID of the slicer @returns Full slicer state, or null if not found #### getItemAt ```typescript getItemAt(index: number): Promise; ``` Get a slicer by its zero-based index in the list. @param index - Zero-based index of the slicer @returns Slicer summary information, or null if index is out of range #### getItems ```typescript getItems(slicerId: string): Promise; ``` Get the items (values) available in a slicer. @param slicerId - ID of the slicer @returns Array of slicer items with selection state #### getItem ```typescript getItem(slicerId: string, key: CellValue): Promise; ``` Get a slicer item by its string key. @param slicerId - ID of the slicer @param key - The value to look up (matched via string coercion) @returns The matching slicer item @throws KernelError if no item matches the key #### getItemOrNullObject ```typescript getItemOrNullObject(slicerId: string, key: CellValue): Promise; ``` Get a slicer item by its string key, or null if not found. @param slicerId - ID of the slicer @param key - The value to look up (matched via string coercion) @returns The matching slicer item, or null if not found #### setSelection ```typescript setSelection(slicerId: string, selectedItems: CellValue[]): Promise; ``` Set the selected items in a slicer, replacing any existing selection. @param slicerId - ID of the slicer @param selectedItems - Array of values to select #### clearSelection ```typescript clearSelection(slicerId: string): Promise; ``` Clear all selections in a slicer (show all items). @param slicerId - ID of the slicer #### duplicate ```typescript duplicate(slicerId: string, offset?: { x?: number; y?: number }): Promise; ``` Duplicate a slicer with an optional position offset. @param slicerId - ID of the slicer to duplicate @param offset - Position offset in pixels (defaults to { x: 20, y: 20 }) @returns The ID of the newly created slicer #### updateConfig ```typescript updateConfig(slicerId: string, updates: Partial): Promise; ``` Update a slicer's configuration. @param slicerId - ID of the slicer @param updates - Partial configuration updates #### getState ```typescript getState(slicerId: string): Promise; ``` Get the enriched runtime state of a slicer. @param slicerId - ID of the slicer @returns Enriched slicer state including computed items and connection status ## WorksheetSparklines Sub-API for sparkline operations on a worksheet. ### Methods #### add ```typescript add( cell: { row: number; col: number }, dataRange: CellRange, type: SparklineType, options?: CreateSparklineOptions, ): Promise; ``` Add a sparkline to a cell. @param cell - Cell position (row and col, 0-based) @param dataRange - Data range for the sparkline @param type - Sparkline type (line, column, winLoss) @param options - Optional creation settings @returns The created sparkline #### addGroup ```typescript addGroup( cells: Array<{ row: number; col: number }>, dataRanges: CellRange[], type: SparklineType, options?: CreateSparklineGroupOptions, ): Promise; ``` Add a group of sparklines with shared settings. @param cells - Array of cell positions @param dataRanges - Array of data ranges (must match cells length) @param type - Sparkline type @param options - Optional group creation settings @returns The created sparkline group #### get ```typescript get(sparklineId: string): Promise; ``` Get a sparkline by ID. @param sparklineId - Sparkline identifier @returns The sparkline, or null if not found #### getAtCell ```typescript getAtCell(row: number, col: number): Promise; ``` Get the sparkline at a specific cell. @param row - Row index (0-based) @param col - Column index (0-based) @returns The sparkline at the cell, or null if none #### list ```typescript list(): Promise; ``` List all sparklines in the worksheet. @returns Array of all sparklines #### getGroup ```typescript getGroup(groupId: string): Promise; ``` Get a sparkline group by ID. @param groupId - Group identifier @returns The sparkline group, or null if not found #### listGroups ```typescript listGroups(): Promise; ``` List all sparkline groups in the worksheet. @returns Array of all sparkline groups #### update ```typescript update(sparklineId: string, updates: Partial): Promise; ``` Update a sparkline's settings. @param sparklineId - Sparkline identifier @param updates - Partial sparkline properties to update #### updateGroup ```typescript updateGroup(groupId: string, updates: Partial): Promise; ``` Update a sparkline group's settings (applies to all members). @param groupId - Group identifier @param updates - Partial group properties to update #### remove ```typescript remove(sparklineId: string): Promise; ``` Remove a sparkline. @param sparklineId - Sparkline identifier #### removeGroup ```typescript removeGroup(groupId: string): Promise; ``` Remove a sparkline group and all its member sparklines. @param groupId - Group identifier #### clearInRange ```typescript clearInRange(range: CellRange): Promise; ``` Clear all sparklines whose cell falls within a range. @param range - Range to clear sparklines from #### clearAll ```typescript clearAll(): Promise; ``` Clear all sparklines in the worksheet. #### addToGroup ```typescript addToGroup(sparklineId: string, groupId: string): Promise; ``` Add a sparkline to a group. @param sparklineId - Sparkline identifier @param groupId - Group identifier #### removeFromGroup ```typescript removeFromGroup(sparklineId: string): Promise; ``` Remove a sparkline from its group (becomes standalone). @param sparklineId - Sparkline identifier #### ungroupAll ```typescript ungroupAll(groupId: string): Promise; ``` Ungroup all sparklines in a group (members become standalone). @param groupId - Group identifier @returns IDs of sparklines that were ungrouped #### has ```typescript has(row: number, col: number): Promise; ``` Check if a cell has a sparkline. @param row - Row index (0-based) @param col - Column index (0-based) @returns True if the cell has a sparkline #### getWithDataInRange ```typescript getWithDataInRange(range: CellRange): Promise; ``` Get sparklines whose data range intersects with a given range. @param range - Range to check for data intersection @returns Sparklines with data in the range ## WorksheetComments Sub-API for comment and note operations on a worksheet. ### Methods #### addNote ```typescript addNote(address: string, text: string, author?: string): Promise; ``` Add a note to a cell. @param address - A1-style cell address (e.g. "A1") @param text - Note text @param author - Optional author name (defaults to 'api') #### getNote ```typescript getNote(address: string): Promise; ``` Get the note for a cell as a Note object. @param address - A1-style cell address @returns The Note object, or null if no note #### removeNote ```typescript removeNote(address: string): Promise; ``` Remove the note from a cell. @param address - A1-style cell address #### count ```typescript count(): Promise; ``` Get the number of comments in the worksheet. @returns The total comment count #### noteCount ```typescript noteCount(): Promise; ``` Get the number of notes (legacy comments) in the worksheet. @returns The count of notes only (excludes threaded comments) #### listNotes ```typescript listNotes(): Promise; ``` List all notes (legacy comments) in the worksheet. @returns Array of notes #### getNoteAt ```typescript getNoteAt(index: number): Promise; ``` Get a note by index from the list of all notes. @param index - Zero-based index into the notes list @returns The Note at that index, or null if out of range #### setNoteVisible ```typescript setNoteVisible(address: string, visible: boolean): Promise; ``` Set the visibility of a note at the given cell address. @param address - A1-style cell address @param visible - Whether the note should be visible #### setNoteHeight ```typescript setNoteHeight(address: string, height: number): Promise; ``` Set the height of a note callout box in points. @param address - A1-style cell address @param height - Height in points #### setNoteWidth ```typescript setNoteWidth(address: string, width: number): Promise; ``` Set the width of a note callout box in points. @param address - A1-style cell address @param width - Width in points #### add ```typescript add(address: string, text: string, author: string): Promise; ``` Add a threaded comment to a cell. @param address - A1-style cell address @param text - Comment text @param author - Author name or identifier #### update ```typescript update(commentId: string, text: string): Promise; ``` Update an existing comment's text. @param commentId - Comment identifier @param text - New comment text #### updateMentions ```typescript updateMentions( commentId: string, content: string, mentions: CommentMention[], ): Promise; ``` Update a comment with mention content (OfficeJS updateMentions equivalent). Sets content, content_type to Mention, and mentions array in a single mutation. @param commentId - Comment identifier @param content - Full comment text including mention display text @param mentions - Array of mention objects describing @mentions within the text #### delete ```typescript delete(commentId: string): Promise; ``` Delete a comment. @param commentId - Comment identifier #### resolveThread ```typescript resolveThread(threadId: string, resolved: boolean): Promise; ``` Set the resolved state of a comment thread. @param threadId - Thread identifier (cell ID) @param resolved - Whether the thread should be marked as resolved #### list ```typescript list(): Promise; ``` List all comments in the worksheet. @returns Array of all comments #### getForCell ```typescript getForCell(address: string): Promise; ``` Get all comments for a specific cell. @param address - A1-style cell address @returns Array of comments for the cell #### addReply ```typescript addReply(commentId: string, text: string, author: string): Promise; ``` Add a reply to an existing comment. @param commentId - ID of the comment to reply to @param text - Reply text @param author - Author name or identifier @returns The created reply comment #### getThread ```typescript getThread(commentId: string): Promise; ``` Get all comments in a thread (root + replies), sorted by createdAt. @param commentId - ID of any comment in the thread @returns Array of comments in the thread #### getById ```typescript getById(commentId: string): Promise; ``` Get a single comment by its ID. @param commentId - Comment identifier @returns The comment, or null if not found #### getLocation ```typescript getLocation(commentId: string): Promise; ``` Get the A1-style cell address for a comment. Resolves the comment's internal cell reference (CellId) to a human-readable address like "A1", "B3", etc. @param commentId - Comment identifier @returns The A1-style cell address, or null if the comment doesn't exist #### getParentByReplyId ```typescript getParentByReplyId(replyId: string): Promise; ``` Get the parent comment for a reply. @param replyId - ID of the reply comment @returns The parent comment, or null if not found or not a reply #### getReplyCount ```typescript getReplyCount(commentId: string): Promise; ``` Get the number of replies in a thread (excluding the root comment). @param commentId - ID of any comment in the thread @returns The reply count #### getReplyAt ```typescript getReplyAt(commentId: string, index: number): Promise; ``` Get a reply at a specific index within a thread (zero-based, excludes root). @param commentId - ID of any comment in the thread @param index - Zero-based index into the replies @returns The reply comment, or null if out of range #### getNoteLocation ```typescript getNoteLocation(address: string): Promise; ``` Get the A1-style cell address for a note. @param address - A1-style cell address @returns The A1-style cell address, or null if no note exists at that address #### hasComment ```typescript hasComment(address: string): Promise; ``` Check if a cell has any comments. @param address - A1-style cell address @returns True if the cell has at least one comment #### deleteForCell ```typescript deleteForCell(address: string): Promise; ``` Delete all comments on a cell. @param address - A1-style cell address @returns The number of comments deleted #### clear ```typescript clear(): Promise; ``` Clear all comments on the worksheet. #### clean ```typescript clean(): Promise; ``` Remove orphaned comments (comments referencing non-existent cells). @returns The number of orphaned comments removed ## WorksheetHyperlinks WorksheetHyperlinks — Sub-API for cell hyperlink operations. Provides methods to set, get, and remove hyperlinks on cells. ### Methods #### set ```typescript set(address: string, url: string): Promise; ``` Set a hyperlink on a cell. @param address - A1-style cell address (e.g. "A1") @param url - Hyperlink URL #### get ```typescript get(address: string): Promise; ``` Get the hyperlink URL for a cell. @param address - A1-style cell address @returns The hyperlink URL, or null if no hyperlink #### remove ```typescript remove(address: string): Promise; ``` Remove a hyperlink from a cell. @param address - A1-style cell address ## WorksheetOutline Sub-API for outline (row/column grouping) operations on a worksheet. ### Methods #### groupRows ```typescript groupRows(startRow: number, endRow: number): Promise; ``` Group rows in a range. @param startRow - Start row index (0-based, inclusive) @param endRow - End row index (0-based, inclusive) #### ungroupRows ```typescript ungroupRows(startRow: number, endRow: number): Promise; ``` Ungroup rows in a range. @param startRow - Start row index (0-based, inclusive) @param endRow - End row index (0-based, inclusive) #### groupColumns ```typescript groupColumns(startCol: number, endCol: number): Promise; ``` Group columns in a range. @param startCol - Start column index (0-based, inclusive) @param endCol - End column index (0-based, inclusive) #### ungroupColumns ```typescript ungroupColumns(startCol: number, endCol: number): Promise; ``` Ungroup columns in a range. @param startCol - Start column index (0-based, inclusive) @param endCol - End column index (0-based, inclusive) #### toggleCollapsed ```typescript toggleCollapsed(groupId: string): Promise; ``` Toggle the collapsed state of a group. @param groupId - Group identifier #### expandAll ```typescript expandAll(): Promise; ``` Expand all groups in the worksheet. #### collapseAll ```typescript collapseAll(): Promise; ``` Collapse all groups in the worksheet. #### getState ```typescript getState(): Promise; ``` Get the full group state for the worksheet. @returns Group state including row groups, column groups, and max levels #### getLevel ```typescript getLevel(type: 'row' | 'column', index: number): Promise; ``` Get the outline level of a specific row or column. @param type - Whether to query a row or column @param index - Row or column index (0-based) @returns The outline level (0 if not in any group) #### getMaxLevel ```typescript getMaxLevel(type: 'row' | 'column'): Promise; ``` Get the maximum outline level for rows or columns. @param type - Whether to query rows or columns @returns The maximum outline level #### subtotal ```typescript subtotal(config: SubtotalConfig): Promise; ``` Apply automatic subtotals. @param config - Subtotal configuration #### getSettings ```typescript getSettings(): Promise; ``` Get the outline display settings. @returns Current outline settings #### setSettings ```typescript setSettings(settings: Partial): Promise; ``` Update outline display settings. @param settings - Partial outline settings to update #### showOutlineLevels ```typescript showOutlineLevels(rowLevels: number, colLevels: number): Promise; ``` Show outline to a specific level for rows and/or columns. Groups at levels > the specified level are collapsed; groups at levels <= are expanded. Pass 0 to collapse all, or a number > maxLevel to expand all. @param rowLevels - Target outline level for rows (0 = collapse all rows) @param colLevels - Target outline level for columns (0 = collapse all columns) ## WorksheetProtection Sub-API for worksheet protection operations. ### Methods #### isProtected ```typescript isProtected(): Promise; ``` Check whether the sheet is currently protected. @returns True if the sheet is protected #### protect ```typescript protect(password?: string, options?: ProtectionOptions): Promise; ``` Protect the sheet with an optional password and granular permission options. @param password - Optional password to require for unprotection @param options - Granular permissions (e.g., allowSort, allowFormatCells) #### unprotect ```typescript unprotect(password?: string): Promise; ``` Unprotect the sheet. Returns true if unprotection succeeded. @param password - Password if the sheet was protected with one @returns True if the sheet was successfully unprotected #### canEditCell ```typescript canEditCell(row: number, col: number): Promise; ``` Check whether a specific cell can be edited under current protection. Returns true if the sheet is unprotected or the cell is unlocked. @param row - Row index (0-based) @param col - Column index (0-based) @returns True if the cell is editable #### canDoStructureOp ```typescript canDoStructureOp(operation: ProtectionOperation): Promise; ``` Check whether a structural operation is allowed under current protection. @param operation - Operation name (e.g., 'sort', 'insertRows', 'deleteColumns') @returns True if the operation is allowed #### canSort ```typescript canSort(): Promise; ``` Check whether sorting is allowed under current protection. Convenience shorthand for `canDoStructureOp('sort')`. @returns True if sorting is allowed #### getConfig ```typescript getConfig(): Promise; ``` Get the full protection configuration for the sheet. @returns Protection configuration including status and permission flags #### getSelectionMode ```typescript getSelectionMode(): Promise<'normal' | 'unlockedOnly' | 'none'>; ``` Get the current selection mode when the sheet is protected. @returns 'normal' (all cells selectable), 'unlockedOnly' (only unlocked cells), or 'none' (no selection) #### setSelectionMode ```typescript setSelectionMode(mode: 'normal' | 'unlockedOnly' | 'none'): Promise; ``` Set the selection mode for when the sheet is protected. Only takes effect when the sheet is actually protected. @param mode - Selection mode ## WorksheetPrint Sub-API for worksheet print and page break operations. ### Methods #### getSettings ```typescript getSettings(): Promise; ``` Get the current print settings for the sheet. @returns Current print settings #### setSettings ```typescript setSettings(settings: Partial): Promise; ``` Update print settings. Only the provided keys are changed. @param settings - Partial print settings to apply #### getArea ```typescript getArea(): Promise; ``` Get the current print area as an A1-notation range string. @returns The print area range string, or null if no print area is set #### setArea ```typescript setArea(area: string): Promise; ``` Set the print area to the specified A1-notation range. @param area - A1-notation range string (e.g., "A1:H20") #### clearArea ```typescript clearArea(): Promise; ``` Clear the print area so the entire sheet prints. #### addPageBreak ```typescript addPageBreak(type: 'horizontal' | 'vertical', position: number): Promise; ``` Add a manual page break at the specified position. @param type - 'horizontal' (row break) or 'vertical' (column break) @param position - 0-based row or column index for the break #### removePageBreak ```typescript removePageBreak(type: 'horizontal' | 'vertical', position: number): Promise; ``` Remove a manual page break at the specified position. @param type - 'horizontal' or 'vertical' @param position - 0-based row or column index of the break to remove #### getPageBreaks ```typescript getPageBreaks(): Promise<{ rowBreaks: Array<{ id: number; min: number; max: number; manual: boolean; pt: boolean }>; colBreaks: Array<{ id: number; min: number; max: number; manual: boolean; pt: boolean }>; }>; ``` Get all manual page breaks in the sheet. @returns Object containing arrays of horizontal and vertical break positions #### clearPageBreaks ```typescript clearPageBreaks(): Promise; ``` Remove all manual page breaks from the sheet. #### setPrintTitleRows ```typescript setPrintTitleRows(startRow: number, endRow: number): Promise; ``` Set the rows to repeat at the top of each printed page (print titles). @param startRow - 0-based start row index @param endRow - 0-based end row index (inclusive) #### setPrintTitleColumns ```typescript setPrintTitleColumns(startCol: number, endCol: number): Promise; ``` Set the columns to repeat at the left of each printed page (print titles). @param startCol - 0-based start column index @param endCol - 0-based end column index (inclusive) #### getPrintTitleRows ```typescript getPrintTitleRows(): Promise<[number, number] | null>; ``` Get the rows configured to repeat at the top of each printed page. @returns A [startRow, endRow] tuple (0-based, inclusive), or null if no repeat rows are set #### getPrintTitleColumns ```typescript getPrintTitleColumns(): Promise<[number, number] | null>; ``` Get the columns configured to repeat at the left of each printed page. @returns A [startCol, endCol] tuple (0-based, inclusive), or null if no repeat columns are set #### clearPrintTitles ```typescript clearPrintTitles(): Promise; ``` Clear all print titles (both repeat rows and repeat columns). Other print settings (margins, orientation, etc.) are preserved. #### setPrintMargins ```typescript setPrintMargins( unit: 'inches' | 'points' | 'centimeters', options: Partial, ): Promise; ``` Set page margins with unit conversion. Values are converted to inches (OOXML native unit) before storing. Only provided margin fields are updated; others are preserved. @param unit - Unit of the provided values: 'inches', 'points', or 'centimeters' @param options - Partial margin values to set #### getCellAfterBreak ```typescript getCellAfterBreak( type: 'horizontal' | 'vertical', position: number, ): { row: number; col: number }; ``` Get the cell position immediately after a page break. @param type - Break type: 'horizontal' (row break) or 'vertical' (column break) @param position - 0-based row or column index of the break @returns Cell coordinates of the first cell after the break #### getHeaderFooterImages ```typescript getHeaderFooterImages(): Promise; ``` Get all header/footer images for this sheet. @returns Array of image info objects, one per occupied position #### setHeaderFooterImage ```typescript setHeaderFooterImage(info: HeaderFooterImageInfo): Promise; ``` Set or replace a header/footer image at the specified position. The engine automatically manages the `&G` format code in the corresponding header/footer string. @param info - Image info including position, src (data-URL or path), and dimensions #### removeHeaderFooterImage ```typescript removeHeaderFooterImage(position: HfImagePosition): Promise; ``` Remove the header/footer image at the specified position. The engine automatically removes the `&G` format code from the corresponding header/footer string. @param position - Which of the 6 header/footer positions to clear ## WorksheetSettings Sub-API for worksheet settings operations. ### Methods #### get ```typescript get(): Promise; ``` Get all sheet settings. @returns Current sheet settings #### set ```typescript set(key: K, value: SheetSettingsInfo[K]): Promise; ``` Set an individual sheet setting by key. @param key - Setting key (e.g., 'showGridlines', 'defaultRowHeight') @param value - New value for the setting #### getCustomLists ```typescript getCustomLists(): Promise; ``` Get the workbook-level custom sort lists. @returns Array of custom lists, each being an array of string values #### setCustomLists ```typescript setCustomLists(lists: string[][]): Promise; ``` Replace all user-defined custom sort lists. @param lists - Array of custom lists to set #### getStandardHeight ```typescript getStandardHeight(): Promise; ``` Get the standard (default) row height in pixels. This is the height used for rows that haven't been explicitly sized. Read-only (matches OfficeJS semantics). #### getStandardWidth ```typescript getStandardWidth(): Promise; ``` Get the standard (default) column width in pixels. This is the width used for columns that haven't been explicitly sized. #### setStandardWidth ```typescript setStandardWidth(width: number): Promise; ``` Set the standard (default) column width in pixels. This changes the default width for all columns that haven't been explicitly sized. @param width - New default column width in pixels ## WorksheetBindings Sub-API for worksheet data binding operations. ### Methods #### list ```typescript list(): Promise; ``` List all data bindings on the sheet. @returns Array of binding info objects #### create ```typescript create(config: CreateBindingConfig): Promise; ``` Create a new data binding on the sheet. @param config - Binding configuration (connection, column mappings, etc.) #### remove ```typescript remove(bindingId: string): Promise; ``` Remove a data binding by ID. @param bindingId - The binding ID to remove #### getProjectionRange ```typescript getProjectionRange(row: number, col: number): Promise; ``` Get the spill range for a projected (dynamic array) cell. @param row - Row index (0-based) @param col - Column index (0-based) @returns The spill range, or null if the cell is not a projection source #### getProjectionSource ```typescript getProjectionSource(row: number, col: number): Promise<{ row: number; col: number } | null>; ``` Get the source cell of a projected value. @param row - Row index (0-based) @param col - Column index (0-based) @returns The source cell position, or null if the cell is not a projection #### isProjectedPosition ```typescript isProjectedPosition(row: number, col: number): Promise; ``` Check whether a cell position is a projected (spilled) value. @param row - Row index (0-based) @param col - Column index (0-based) @returns True if the cell holds a projected value #### getViewportProjectionData ```typescript getViewportProjectionData( startRow: number, startCol: number, endRow: number, endCol: number, ): Promise>; ``` Get all projection data overlapping a viewport range (batch query). Returns one entry per projection with origin position and dimensions. ## WorksheetNames Sub-API for sheet-scoped named range operations. ### Methods #### add ```typescript add(name: string, reference: string, comment?: string): Promise; ``` Add a named range scoped to this sheet. @param name - Name for the range @param reference - Cell reference (e.g., "A1:B10" or "=Sheet1!A1:B10") @param comment - Optional comment #### get ```typescript get(name: string): Promise; ``` Get a named range by name, scoped to this sheet. @param name - Name to look up @returns Named range info or null if not found #### getRange ```typescript getRange(name: string): Promise; ``` Get the range reference for a named range scoped to this sheet. @param name - Name to look up @returns Range reference or null if not found #### remove ```typescript remove(name: string): Promise; ``` Remove a named range scoped to this sheet. @param name - Name to remove #### update ```typescript update(name: string, updates: NamedRangeUpdateOptions): Promise; ``` Update a named range scoped to this sheet. @param name - Name of the range to update @param updates - Fields to update #### list ```typescript list(): Promise; ``` List all named ranges scoped to this sheet. @returns Array of named range info objects ## WorksheetStyles WorksheetStyles — Sub-API for named cell style operations. Provides methods to apply and query named cell styles on a worksheet. Named styles are defined at the workbook level (wb.styles) and applied at the worksheet level via this sub-API. Note: Mog copies format values to cells rather than storing a style reference. getStyle() is a best-effort reverse lookup that matches cell format against known style formats. ### Methods #### applyStyle ```typescript applyStyle(address: string, styleName: string): Promise; ``` Apply a named style to a cell. Resolves the style name to its format definition and applies all format properties to the target cell. @param address - A1-style cell address @param styleName - Name of the style to apply (e.g., "Normal", "Heading 1") @throws KernelError if style name is not found #### applyStyleToRange ```typescript applyStyleToRange(range: string, styleName: string): Promise; ``` Apply a named style to a range. @param range - A1-style range string (e.g. "A1:C3") @param styleName - Name of the style to apply @throws KernelError if style name is not found #### getStyle ```typescript getStyle(address: string): Promise; ``` Get the name of the named style that matches a cell's format (best-effort). Since Mog copies format values rather than storing a style reference, this performs a reverse lookup by comparing the cell's current format against all known style formats. @param address - A1-style cell address @returns Style name if a matching style is found, null otherwise --- # Types ## AccentNode Accent - Accent mark over base expression (hat, tilde, dot, etc.) ```typescript type AccentNode = { type: 'acc'; /** Accent character (defaults to combining circumflex U+0302) */ chr?: string; /** Base expression */ e: MathNode[]; } ``` ## AggregateFunction ```typescript type AggregateFunction = 'sum' | 'count' | 'counta' | 'countunique' | 'average' | 'min' | 'max' | 'product' | 'stdev' | 'stdevp' | 'var' | 'varp' ``` ## AggregateResult Aggregate values for selected cells (status bar display). ```typescript type AggregateResult = { /** Sum of numeric values */ sum: number; /** Total number of non-empty cells */ count: number; /** Number of numeric cells */ numericCount: number; /** Average of numeric values (null if no numeric cells) */ average: number | null; /** Minimum numeric value (null if no numeric cells) */ min: number | null; /** Maximum numeric value (null if no numeric cells) */ max: number | null; } ``` ## ApplyScenarioResult Result returned from applyScenario(). ```typescript type ApplyScenarioResult = { /** Number of cells that were updated with scenario values. */ cellsUpdated: number; /** CellIds that could not be found (deleted cells). */ skippedCells: string[]; /** Original values to pass to restoreScenario() later. */ originalValues: OriginalCellValue[]; } ``` ## AreaSubType ```typescript type AreaSubType = 'standard' | 'stacked' | 'percentStacked' ``` ## ArrowHead Arrow head style for connectors. ```typescript type ArrowHead = { /** Arrow head type */ type: 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'open'; /** Arrow head size */ size: 'small' | 'medium' | 'large'; } ``` ## AutoFillChange A single cell change produced by the fill engine. ```typescript type AutoFillChange = { row: number; col: number; type: 'value' | 'formula' | 'format' | 'clear'; } ``` ## AutoFillMode Fill mode for autoFill() — matches Rust FillMode enum. Covers the full OfficeJS fill behavior set. ```typescript type AutoFillMode = | 'auto' // Detect pattern automatically (default) | 'copy' // Always copy (no series) | 'series' // Force series interpretation | 'days' // Force date unit: days | 'weekdays' // Force date unit: weekdays | 'months' // Force date unit: months | 'years' // Force date unit: years | 'formats' // Copy formats only | 'values' // Copy values only (no formats) | 'withoutFormats' // Copy values + formulas, skip formats | 'linearTrend' // Force linear regression trend | 'growthTrend' ``` ## AutoFillResult Result from autoFill() — summary of what the fill engine did. ```typescript type AutoFillResult = { /** The pattern that was detected (or forced by mode) */ patternType: FillPatternType; /** Number of cells that were filled */ filledCellCount: number; /** Any warnings generated during fill */ warnings: AutoFillWarning[]; /** Per-cell changes listing each cell written */ changes: AutoFillChange[]; } ``` ## AutoFillWarning ```typescript type AutoFillWarning = { row: number; col: number; kind: AutoFillWarningKind; } ``` ## AutoFillWarningKind ```typescript type AutoFillWarningKind = | { type: 'mergedCellsInTarget' } | { type: 'formulaRefOutOfBounds'; refIndex: number } | { type: 'sourceCellEmpty' } ``` ## AutoFilterClearReceipt Receipt for clearing an auto-filter. ```typescript type AutoFilterClearReceipt = { kind: 'autoFilterClear'; } ``` ## AutoFilterSetReceipt Receipt for setting an auto-filter. ```typescript type AutoFilterSetReceipt = { kind: 'autoFilterSet'; range: string; } ``` ## AxisConfig Axis configuration (matches AxisData wire type). Wire field names: categoryAxis, valueAxis, secondaryCategoryAxis, secondaryValueAxis. Legacy aliases: xAxis, yAxis, secondaryYAxis (mapped in chart-bridge). ```typescript type AxisConfig = { categoryAxis?: SingleAxisConfig; valueAxis?: SingleAxisConfig; secondaryCategoryAxis?: SingleAxisConfig; secondaryValueAxis?: SingleAxisConfig; seriesAxis?: SingleAxisConfig; /** @deprecated Use categoryAxis instead */ xAxis?: SingleAxisConfig; /** @deprecated Use valueAxis instead */ yAxis?: SingleAxisConfig; /** @deprecated Use secondaryValueAxis instead */ secondaryYAxis?: SingleAxisConfig; } ``` ## AxisType Axis type ```typescript type AxisType = 'category' | 'value' | 'time' | 'log' ``` ## BarNode Bar - Horizontal bar over or under base ```typescript type BarNode = { type: 'bar'; /** Position: 'top' (overline) or 'bot' (underline) */ pos: 'top' | 'bot'; /** Base expression */ e: MathNode[]; } ``` ## BarSubType Chart sub-types for variations ```typescript type BarSubType = 'clustered' | 'stacked' | 'percentStacked' ``` ## BevelEffect 3D bevel effect configuration. ```typescript type BevelEffect = { /** Bevel preset type */ type: | 'none' | 'relaxed' | 'circle' | 'slope' | 'cross' | 'angle' | 'soft-round' | 'convex' | 'cool-slant' | 'divot' | 'riblet' | 'hard-edge' | 'art-deco'; /** Bevel width in pixels */ width: number; /** Bevel height in pixels */ height: number; } ``` ## BlipFill Picture/texture fill definition. ```typescript type BlipFill = { src: string; stretch?: boolean; tile?: TileSettings; } ``` ## BorderBoxNode BorderBox - Box with visible borders ```typescript type BorderBoxNode = { type: 'borderBox'; /** Hide individual borders */ hideTop?: boolean; hideBot?: boolean; hideLeft?: boolean; hideRight?: boolean; /** Strikethrough lines */ strikeH?: boolean; strikeV?: boolean; strikeBLTR?: boolean; strikeTLBR?: boolean; /** Content */ e: MathNode[]; } ``` ## BorderStyle Border style. D3: Excel-compatible border styles. All 13 Excel border styles are supported: - Solid: 'thin', 'medium', 'thick' (varying line widths) - Dashed: 'dashed', 'mediumDashed' (varying dash lengths) - Dotted: 'dotted', 'hair' (dots and very fine lines) - Double: 'double' (two parallel lines) - Dash-dot combinations: 'dashDot', 'dashDotDot', 'mediumDashDot', 'mediumDashDotDot' - Special: 'slantDashDot' (slanted dash-dot pattern) @see cells-layer.ts getBorderDashPattern() for canvas rendering @see format-mapper.ts for XLSX import/export mapping ```typescript type BorderStyle = { style: | 'none' | 'thin' | 'medium' | 'thick' | 'dashed' | 'dotted' | 'double' | 'hair' | 'mediumDashed' | 'dashDot' | 'dashDotDot' | 'mediumDashDot' | 'mediumDashDotDot' | 'slantDashDot'; color?: string; /** Tint modifier for border color (-1.0 to +1.0, ECMA-376). */ colorTint?: number; } ``` ## BoxNode Box - Invisible container for grouping/alignment ```typescript type BoxNode = { type: 'box'; /** Operator emulator (acts as operator for spacing) */ opEmu?: boolean; /** No break (keep together) */ noBreak?: boolean; /** Differential (italic d for dx) */ diff?: boolean; /** Alignment point */ aln?: boolean; /** Content */ e: MathNode[]; } ``` ## BoxplotConfig Box plot configuration ```typescript type BoxplotConfig = { showOutliers?: boolean; showMean?: boolean; whiskerType?: 'tukey' | 'minMax' | 'percentile'; } ``` ## ButtonControl Button control - triggers actions on click. Unlike other controls, Button's primary purpose is triggering actions, not storing values. linkedCellId is optional. Use cases: - Increment a counter cell on click - Trigger a macro/script (via actionId) - Navigate to another sheet/location ```typescript type ButtonControl = { type: 'button'; /** Button label text */ label: string; /** Optional - Cell to write to on click. Common patterns: - Increment counter: read current value, write value + 1 - Toggle: write opposite of current value - Fixed value: write specific value (e.g., timestamp) */ linkedCellId?: CellId; /** Action ID for future macro/script integration. Will be used to trigger named actions defined elsewhere. */ actionId?: string; /** Value to write to linked cell on click. Only used if linkedCellId is set and clickAction is 'setValue'. */ clickValue?: unknown; /** Click behavior when linkedCellId is set. - 'setValue': Write clickValue to cell - 'increment': Add 1 to current numeric value - 'decrement': Subtract 1 from current numeric value - 'toggle': Toggle boolean value */ clickAction?: 'setValue' | 'increment' | 'decrement' | 'toggle'; } ``` ## CFAboveAverageRule Above/below average rule. ```typescript type CFAboveAverageRule = { type: 'aboveAverage'; aboveAverage: boolean; equalAverage?: boolean; stdDev?: number; style: CFStyle; } ``` ## CFCellValueRule Cell value comparison rule. ```typescript type CFCellValueRule = { type: 'cellValue'; operator: CFOperator; value1: number | string; value2?: number | string; style: CFStyle; } ``` ## CFColorScale Color scale configuration (2 or 3 colors). ```typescript type CFColorScale = { minPoint: CFColorPoint; midPoint?: CFColorPoint; maxPoint: CFColorPoint; } ``` ## CFColorScaleRule Color scale rule. ```typescript type CFColorScaleRule = { type: 'colorScale'; colorScale: CFColorScale; } ``` ## CFContainsBlanksRule Contains blanks rule. ```typescript type CFContainsBlanksRule = { type: 'containsBlanks'; blanks: boolean; style: CFStyle; } ``` ## CFContainsErrorsRule Contains errors rule. ```typescript type CFContainsErrorsRule = { type: 'containsErrors'; errors: boolean; style: CFStyle; } ``` ## CFContainsTextRule Contains text rule. ```typescript type CFContainsTextRule = { type: 'containsText'; operator: CFTextOperator; text: string; style: CFStyle; } ``` ## CFDataBar Data bar configuration. ```typescript type CFDataBar = { minPoint: CFColorPoint; maxPoint: CFColorPoint; positiveColor: string; negativeColor?: string; borderColor?: string; negativeBorderColor?: string; showBorder?: boolean; gradient?: boolean; direction?: 'leftToRight' | 'rightToLeft' | 'context'; axisPosition?: CFDataBarAxisPosition; axisColor?: string; showValue?: boolean; /** When true, negative bars use the positive fill color. */ matchPositiveFillColor?: boolean; /** When true, negative bars use the positive border color. */ matchPositiveBorderColor?: boolean; /** Extension identifier for OOXML ext data bars. */ extId?: string; } ``` ## CFDataBarRule Data bar rule. ```typescript type CFDataBarRule = { type: 'dataBar'; dataBar: CFDataBar; } ``` ## CFDuplicateValuesRule Duplicate/unique values rule. ```typescript type CFDuplicateValuesRule = { type: 'duplicateValues'; unique?: boolean; style: CFStyle; } ``` ## CFFormulaRule Formula-based rule. ```typescript type CFFormulaRule = { type: 'formula'; formula: string; style: CFStyle; } ``` ## CFIconSet Icon set configuration. ```typescript type CFIconSet = { iconSetName: CFIconSetName; thresholds?: CFIconThreshold[]; reverseOrder?: boolean; showIconOnly?: boolean; /** Per-threshold custom icon overrides (null entries use default icons). */ customIcons?: (CFCustomIcon | null)[]; } ``` ## CFIconSetRule Icon set rule. ```typescript type CFIconSetRule = { type: 'iconSet'; iconSet: CFIconSet; } ``` ## CFOperator Comparison operators for cellValue rules. ```typescript type CFOperator = | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual' | 'equal' | 'notEqual' | 'between' | 'notBetween' ``` ## CFRule Union of all rule types. ```typescript type CFRule = | CFCellValueRule | CFFormulaRule | CFColorScaleRule | CFDataBarRule | CFIconSetRule | CFTop10Rule | CFAboveAverageRule | CFDuplicateValuesRule | CFContainsTextRule | CFContainsBlanksRule | CFContainsErrorsRule | CFTimePeriodRule ``` ## CFRuleInput Rule input for creating new rules (id and priority assigned by the API). Callers provide the rule configuration; the API generates id and sets priority. ```typescript type CFRuleInput = Omit ``` ## CFStyle Conditional Formatting Render Types Types needed by canvas-renderer to render conditional formatting results. These are extracted from engine to avoid circular dependencies during the canvas-renderer extraction. ## Two-tier Rust type architecture The CFStyle defined here mirrors `compute-cf/src/types/rule.rs` — the computation / rendering type used by the Rust CF evaluation engine. A separate, intentionally simplified persistence subset lives in `domain-types/src/domain/conditional_format.rs`. That domain type is auto-generated into `compute-types.gen.ts`, which is therefore NOT the rendering source of truth for CFStyle — this file is. @module contracts/conditional-format/render-types ```typescript type CFStyle = { backgroundColor?: string; fontColor?: string; bold?: boolean; italic?: boolean; underlineType?: 'none' | 'single' | 'double' | 'singleAccounting' | 'doubleAccounting'; strikethrough?: boolean; numberFormat?: string; borderColor?: string; borderStyle?: CFBorderStyle; borderTopColor?: string; borderTopStyle?: CFBorderStyle; borderBottomColor?: string; borderBottomStyle?: CFBorderStyle; borderLeftColor?: string; borderLeftStyle?: CFBorderStyle; borderRightColor?: string; borderRightStyle?: CFBorderStyle; } ``` ## CFTextOperator Text operators for containsText rules. ```typescript type CFTextOperator = 'contains' | 'notContains' | 'beginsWith' | 'endsWith' ``` ## CFTimePeriodRule Time period (date occurring) rule. ```typescript type CFTimePeriodRule = { type: 'timePeriod'; timePeriod: DatePeriod; style: CFStyle; } ``` ## CFTop10Rule Top/bottom N rule. ```typescript type CFTop10Rule = { type: 'top10'; rank: number; percent?: boolean; bottom?: boolean; style: CFStyle; } ``` ## CalcMode Calculation settings for the workbook. G.3: Supports iterative calculation for circular references. Excel allows formulas with circular references to calculate iteratively until they converge or reach the maximum iterations. When disabled (default), circular references result in #CALC! errors. @see plans/active/excel-parity/04-EDITING-BEHAVIORS-PLAN.md - G.3 ```typescript type CalcMode = 'auto' | 'autoNoTable' | 'manual' ``` ## CalculateOptions Options for wb.calculate() — all optional, backward compatible. ```typescript type CalculateOptions = { /** Calculation type (default: 'full'). - 'recalculate' — recalculate dirty cells only - 'full' — recalculate all cells - 'fullRebuild' — rebuild dependency graph and recalculate all */ calculationType?: CalculationType; /** Enable iterative calculation for circular references. - `true` — enable with default settings (100 iterations, 0.001 threshold) - `{ maxIterations?: number; maxChange?: number }` — enable with custom settings - `false` — disable (override workbook setting) - `undefined` — use workbook setting (default) */ iterative?: boolean | { maxIterations?: number; maxChange?: number }; } ``` ## CalculateResult Result from wb.calculate() — includes convergence metadata. ```typescript type CalculateResult = { /** Whether circular references were detected. */ hasCircularRefs: boolean; /** Whether iterative calculation converged. Only meaningful when hasCircularRefs is true. */ converged: boolean; /** Number of iterations performed (0 if no circular refs). */ iterations: number; /** Maximum per-cell delta at final iteration. */ maxDelta: number; /** Number of cells involved in circular references. */ circularCellCount: number; } ``` ## CalculatedField ```typescript type CalculatedField = { fieldId: string; name: string; formula: string; } ``` ## CalculationSettings ```typescript type CalculationSettings = { /** Whether to allow iterative calculation for circular references. When true, formulas with circular references calculate iteratively. When false (default), circular references show #CALC! error. */ enableIterativeCalculation: boolean; /** Maximum number of iterations for iterative calculation. Excel default: 100 */ maxIterations: number; /** Maximum change between iterations for convergence. Calculation stops when all results change by less than this amount. Excel default: 0.001 */ maxChange: number; /** Calculation mode (auto/manual/autoNoTable). Default: 'auto' */ calcMode: CalcMode; /** Whether to use full (15-digit) precision for calculations. Default: true */ fullPrecision: boolean; /** Cell reference style (true = R1C1, false = A1). Default: false */ r1c1Mode: boolean; /** Whether to perform a full calculation when the file is opened. Default: false */ fullCalcOnLoad: boolean; } ``` ## CalculationType Calculation type for `calculate()`. - 'recalculate' — recalculate dirty cells only (default) - 'full' — recalculate all cells - 'fullRebuild' — rebuild dependency graph and recalculate all ```typescript type CalculationType = 'recalculate' | 'full' | 'fullRebuild' ``` ## CallableDisposable A disposable that can also be called as a function (shorthand for dispose). This type alias stays in contracts since it's used in service interface signatures. ```typescript type CallableDisposable = (() => void) & IDisposable ``` ## CellAddress Cell address reference NOTE: sheetId is REQUIRED to ensure explicit sheet context for all cell references. This enables proper cross-sheet formula handling and dependency tracking. If you need a cell reference without sheet context (within the active sheet), use { row, col } inline or create a local type. ```typescript type CellAddress = { row: number; col: number; sheetId: string; } ``` ## CellAnchor Cell anchor point with pixel offset. Used for precise positioning relative to cell boundaries. Cell Identity Model: Uses CellId for stable references that survive row/col insert/delete. Position is resolved at render time via CellPositionLookup. @example // User places image at B5 const anchor: CellAnchor = { cellId: 'abc-123...', // CellId of B5 xOffset: 10, // 10px from cell left edge yOffset: 5 // 5px from cell top edge }; // After inserting row at row 3, the CellId is unchanged // but resolves to position (row: 5, col: 1) → image moves down ```typescript type CellAnchor = { /** Stable cell reference that survives row/col insert/delete. Resolve to current position via CellPositionLookup.getPosition(). */ cellId: CellId; /** Horizontal offset from cell top-left in pixels */ xOffset: number; /** Vertical offset from cell top-left in pixels */ yOffset: number; } ``` ## CellBorders Cell borders ECMA-376 CT_Border: Full border specification for cells. Supports standard borders (top/right/bottom/left), diagonal borders, RTL equivalents (start/end), and internal borders for ranges (vertical/horizontal). ```typescript type CellBorders = { top?: BorderStyle; right?: BorderStyle; bottom?: BorderStyle; left?: BorderStyle; diagonal?: BorderStyle & { direction?: 'up' | 'down' | 'both' }; /** Diagonal up flag (ECMA-376 CT_Border @diagonalUp). When true, diagonal line runs from bottom-left to top-right. Note: This is the spec-compliant representation. For convenience, diagonal.direction can also be used which derives from these flags. */ diagonalUp?: boolean; /** Diagonal down flag (ECMA-376 CT_Border @diagonalDown). When true, diagonal line runs from top-left to bottom-right. Note: This is the spec-compliant representation. For convenience, diagonal.direction can also be used which derives from these flags. */ diagonalDown?: boolean; /** RTL start border (maps to left in LTR, right in RTL). Used for bidirectional text support. */ start?: BorderStyle; /** RTL end border (maps to right in LTR, left in RTL). Used for bidirectional text support. */ end?: BorderStyle; /** Internal vertical border (between cells in a range). Only meaningful when applied to a range of cells. */ vertical?: BorderStyle; /** Internal horizontal border (between cells in a range). Only meaningful when applied to a range of cells. */ horizontal?: BorderStyle; /** Outline mode flag. When true, borders are applied as outline around the range. When false/undefined, borders apply to individual cells. */ outline?: boolean; } ``` ## CellData Complete cell data ```typescript type CellData = { value: CellValue; formula?: FormulaA1; format?: CellFormat; borders?: CellBorders; comment?: string; hyperlink?: string; /** Pre-formatted display string from Rust (e.g., "$1,234.50", "1/1/2024"). */ formatted?: string; } ``` ## CellFormat Cell formatting options This interface defines ALL Excel format properties that can be applied to cells. The implementation status of each property is tracked in format-registry.ts. @see FORMAT_PROPERTY_REGISTRY in format-registry.ts for implementation status ```typescript type CellFormat = { /** Excel-compatible number format code string. Common format codes: - Currency: '$#,##0.00' - Accounting: '_($* #,##0.00_);_($* (#,##0.00);_($* "-"??_);_(@_)' - Percentage: '0.00%' - Date: 'M/D/YYYY', 'YYYY-MM-DD', 'MMM D, YYYY' - Time: 'h:mm AM/PM', 'HH:mm:ss' - Number: '#,##0.00', '0.00' - Scientific: '0.00E+00' - Text: '@' - Fraction: '# ?/?' See the `formatPresets` section in api-spec.json for the full catalog of 85+ pre-defined format codes with examples. @example // Currency { numberFormat: '$#,##0.00' } // Percentage with 1 decimal { numberFormat: '0.0%' } // ISO date { numberFormat: 'YYYY-MM-DD' } */ numberFormat?: string; /** Number format category hint. Auto-detected from numberFormat when not set. Valid values: 'general' | 'number' | 'currency' | 'accounting' | 'date' | 'time' | 'percentage' | 'fraction' | 'scientific' | 'text' | 'special' | 'custom' */ numberFormatType?: NumberFormatType; fontFamily?: string; fontSize?: number; /** Theme font reference for Excel-compatible "+Headings" / "+Body" fonts. When set, the cell uses the theme's majorFont (headings) or minorFont (body) instead of fontFamily. Theme fonts are resolved at render time, allowing cells to automatically update when the workbook theme changes. Behavior: - 'major': Uses theme.fonts.majorFont (e.g., 'Calibri Light' in Office theme) - 'minor': Uses theme.fonts.minorFont (e.g., 'Calibri' in Office theme) - undefined: Uses fontFamily property (or default font if not set) When fontTheme is set, fontFamily is ignored for rendering but may still be stored for fallback purposes. This matches Excel's behavior where "+Headings" cells can have a fontFamily that's used when the theme is unavailable. @see resolveThemeFonts in theme.ts for resolution @see ThemeFonts for theme font pair definition */ fontTheme?: 'major' | 'minor'; /** Font color. Can be: - Absolute hex: '#4472c4' or '#ff0000' - Theme reference: 'theme:accent1' (uses current theme's accent1 color) - Theme with tint: 'theme:accent1:0.4' (40% lighter) or 'theme:accent1:-0.25' (25% darker) Theme references are resolved at render time via resolveThemeColors(). This enables cells to automatically update when the workbook theme changes. @see resolveThemeColors in theme.ts for resolution @see ThemeColorSlot for valid slot names (dark1, light1, accent1-6, etc.) */ fontColor?: string; /** Font color tint modifier (-1.0 to +1.0). Applied on top of fontColor. */ fontColorTint?: number; bold?: boolean; italic?: boolean; /** Underline type. Excel supports 4 underline styles: - 'none': No underline (default) - 'single': Standard underline under all characters - 'double': Two parallel lines under all characters - 'singleAccounting': Underline under text only (not spaces), for column alignment - 'doubleAccounting': Double underline under text only (not spaces), for column alignment */ underlineType?: 'none' | 'single' | 'double' | 'singleAccounting' | 'doubleAccounting'; strikethrough?: boolean; /** Superscript text (vertAlign = 'superscript' in Excel). Text is rendered smaller and raised above the baseline. */ superscript?: boolean; /** Subscript text (vertAlign = 'subscript' in Excel). Text is rendered smaller and lowered below the baseline. */ subscript?: boolean; /** Font outline effect. Draws only the outline of each character (hollow text). Rare in modern spreadsheets but supported by Excel. */ fontOutline?: boolean; /** Font shadow effect. Adds a shadow behind the text. Rare in modern spreadsheets but supported by Excel. */ fontShadow?: boolean; /** Horizontal text alignment. - 'general': Context-based (left for text, right for numbers) - Excel default - 'left': Left-align text - 'center': Center text - 'right': Right-align text - 'fill': Repeat content to fill cell width - 'justify': Justify text (distribute evenly) - 'centerContinuous': Center across selection without merging - 'distributed': Distribute text evenly with indent support */ horizontalAlign?: | 'general' | 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed'; /** Vertical text alignment. - 'top': Align to top of cell - 'middle': Center vertically (also known as 'center') - 'bottom': Align to bottom of cell - Excel default - 'justify': Justify vertically (distribute lines evenly) - 'distributed': Distribute text evenly with vertical spacing */ verticalAlign?: 'top' | 'middle' | 'bottom' | 'justify' | 'distributed'; wrapText?: boolean; /** Text rotation angle in degrees. - 0-90: Counter-clockwise rotation - 91-180: Clockwise rotation (180 - value) - 255: Vertical text (stacked characters, read top-to-bottom) */ textRotation?: number; /** Indent level (0-15). Each level adds approximately 8 pixels of indent from the cell edge. Works with left and right horizontal alignment. */ indent?: number; /** Shrink text to fit cell width. Reduces font size to fit all text within the cell width. Mutually exclusive with wrapText in Excel behavior. */ shrinkToFit?: boolean; /** Text reading order for bidirectional text support. - 'context': Determined by first character with strong directionality - 'ltr': Left-to-right (forced) - 'rtl': Right-to-left (forced) */ readingOrder?: 'context' | 'ltr' | 'rtl'; /** Auto-indent flag (ECMA-376 CT_CellAlignment/@autoIndent). */ autoIndent?: boolean; /** Background color. Can be: - Absolute hex: '#ffffff' or '#c6efce' - Theme reference: 'theme:accent1' (uses current theme's accent1 color) - Theme with tint: 'theme:accent1:0.4' (40% lighter) or 'theme:accent1:-0.25' (25% darker) Theme references are resolved at render time via resolveThemeColors(). This enables cells to automatically update when the workbook theme changes. For solid fills, this is the only color needed. For pattern fills, this is the background color behind the pattern. @see resolveThemeColors in theme.ts for resolution @see ThemeColorSlot for valid slot names (dark1, light1, accent1-6, etc.) */ backgroundColor?: string; /** Background color tint modifier (-1.0 to +1.0). Applied on top of backgroundColor. */ backgroundColorTint?: number; /** Pattern fill type. Excel supports 18 pattern types for cell backgrounds. When set (and not 'none' or 'solid'), the cell uses a pattern fill. */ patternType?: PatternType; /** Pattern foreground color. The color of the pattern itself (dots, lines, etc.). Only used when patternType is set to a non-solid pattern. */ patternForegroundColor?: string; /** Pattern foreground color tint modifier (-1.0 to +1.0). */ patternForegroundColorTint?: number; /** Gradient fill configuration. When set, overrides backgroundColor and pattern fill. Excel supports linear and path (radial) gradients. */ gradientFill?: GradientFill; /** Cell borders (top, right, bottom, left, diagonal) */ borders?: CellBorders; /** Cell is locked when sheet protection is enabled. Default is true in Excel (all cells locked by default). Only effective when the sheet's isProtected flag is true. */ locked?: boolean; /** Formula is hidden when sheet protection is enabled. When true, the cell's formula is not shown in the formula bar. The computed value is still displayed in the cell. Only effective when the sheet's isProtected flag is true. */ hidden?: boolean; /** Cell value is forced to text mode (apostrophe prefix). When true: - Raw value includes the leading apostrophe - Display value strips the apostrophe - Formula bar shows the apostrophe - Value is NOT coerced to date/number/etc. Set when user types ' as first character. Follows cell on sort/move (keyed by CellId, Cell Identity Model). @see plans/active/excel-parity/08-EDITING.md - Item 8.1 */ forcedTextMode?: boolean; /** Arbitrary extension data for future features. Use namespaced keys: "myfeature.mykey" Example: { ignoreError: true } to suppress error indicators. */ extensions?: Record; } ``` ## CellId Stable cell identifier - never changes even when cell moves. We use UUID v7 (time-sortable) for: - Uniqueness across clients (no coordination needed) - Time-sortability for debugging - Compact string representation ```typescript type CellId = string ``` ## CellIdRange A range defined by corner cell identities. This is the universal type for CRDT-safe range references used by: - Charts (data ranges, anchor positions) - Tables (table extent) - Grouping (group extent) Unlike position-based ranges, CellIdRange automatically handles: - Concurrent structure changes (insert/delete rows/cols) - Range expansion when cells inserted between corners - Correct CRDT composition under concurrent edits Position resolution happens at render/extraction time via GridIndex. @example // Chart data range A1:D10 const range: CellIdRange = { topLeftCellId: 'abc-123...', // CellId of A1 bottomRightCellId: 'def-456...' // CellId of D10 }; // After user inserts column at B: // - CellIds unchanged // - But A1 is still at (0,0), D10 is now at (9,4) // - Range automatically covers A1:E10 ```typescript type CellIdRange = { /** Cell identifier string (CellId) of the top-left corner cell */ topLeftCellId: string; /** Cell identifier string (CellId) of the bottom-right corner cell */ bottomRightCellId: string; } ``` ## CellRange Cell range reference. This is THE canonical range type for ALL range operations in the spreadsheet. Uses flat format for simplicity and JSON compatibility. Used by: XState machines, canvas coordinates, React hooks, API, events, tables, pivots ```typescript type CellRange = { startRow: number; startCol: number; endRow: number; endCol: number; /** True when entire column(s) selected via column header click */ isFullColumn?: boolean; /** True when entire row(s) selected via row header click */ isFullRow?: boolean; sheetId?: string; } ``` ## CellStyle Named cell style that can be applied to cells. Styles are a named collection of formatting properties. When applied, the format values are copied to cells (not referenced by ID). This matches Excel behavior where style changes don't affect already-styled cells. Built-in styles are defined in code and never persisted. Custom styles are stored in Yjs for collaboration. ```typescript type CellStyle = { /** Unique identifier (e.g., 'good', 'heading1', 'custom-abc123') */ id: string; /** Display name shown in UI (e.g., 'Good', 'Heading 1') */ name: string; /** Category for UI grouping */ category: StyleCategory; /** The formatting properties to apply */ format: CellFormat; /** True for built-in styles, false for user-created */ builtIn: boolean; } ``` ## CellType Cell type classification for `getSpecialCells()`. Matches OfficeJS `Excel.SpecialCellType`. ```typescript enum CellType { Blanks = 'Blanks', Constants = 'Constants', Formulas = 'Formulas', Visible = 'Visible', ConditionalFormats = 'ConditionalFormats', DataValidations = 'DataValidations', } ``` ## CellValue WorkbookFunctions -- Sub-API for programmatic function invocation. Provides namespaced access to spreadsheet function evaluation without writing to any cell (OfficeJS: `workbook.functions`). Usage: `const result = await wb.functions.sum("A1:A10")` ```typescript type CellValue = string | number | boolean | null ``` ## CellValueType Value type filter for `getSpecialCells()` when cellType is `Constants` or `Formulas`. Matches OfficeJS `Excel.SpecialCellValueType`. ```typescript enum CellValueType { Numbers = 'Numbers', Text = 'Text', Logicals = 'Logicals', Errors = 'Errors', } ``` ## CellWriteOptions Options controlling how a cell value is interpreted when written. ```typescript type CellWriteOptions = { /** If true, value is treated as a formula (prefixed with =) */ asFormula?: boolean; } ``` ## ChangeOrigin Origin of a change: direct write, formula recalculation, or remote collaborator. ```typescript type ChangeOrigin = 'direct' | 'cascade' | 'remote' ``` ## ChangeRecord WorksheetChanges — Sub-API for opt-in change tracking. Creates lightweight trackers that accumulate cell-level change records across mutations. Trackers are opt-in to avoid bloating return values; they return addresses + metadata only (no cell values) so callers can hydrate via getRange() when needed. Inspired by: - Excel OfficeJS onChanged (lightweight payload + lazy hydration) - Firestore onSnapshot (query-scoped subscriptions) - Yjs transaction.origin (source/origin tagging for collab) ```typescript type ChangeRecord = { /** Cell address in A1 notation (e.g. "B1"). */ address: string; /** 0-based row index. */ row: number; /** 0-based column index. */ col: number; /** What caused this change. */ origin: ChangeOrigin; /** Type of change. */ type: 'modified'; /** Value before the change (undefined if cell was previously empty). */ oldValue?: unknown; /** Value after the change (undefined if cell was cleared). */ newValue?: unknown; } ``` ## ChangeTrackOptions Options for creating a change tracker. ```typescript type ChangeTrackOptions = { /** Only track changes within this range (A1 notation, e.g. "A1:Z100"). Omit for whole-sheet. */ scope?: string; /** Exclude changes from these origin types. */ excludeOrigins?: ChangeOrigin[]; } ``` ## ChangeTracker A handle that accumulates change records across mutations. ```typescript type ChangeTracker = { /** Drain all accumulated changes since creation or last collect() call. Returns addresses + metadata only (no cell values) — call ws.getRange() to hydrate if needed. */ collect(): ChangeRecord[];; /** Stop tracking and release internal resources. */ close(): void;; /** Whether this tracker is still active (not closed). */ active: boolean; } ``` ## Chart Chart as returned by get/list operations. Extends ChartConfig with identity and metadata fields. ```typescript type Chart = { id: string; sheetId?: string; createdAt?: number; updatedAt?: number; } ``` ## ChartAreaConfig Chart area configuration ```typescript type ChartAreaConfig = { fill?: ChartFill; border?: ChartBorder; format?: ChartFormat; } ``` ## ChartBorder Shared chart border configuration (matches ChartBorderData wire type) ```typescript type ChartBorder = { color?: string; width?: number; style?: string; } ``` ## ChartColor Color: hex string for direct colors, object for theme-aware colors. ```typescript type ChartColor = string | { theme: string; tintShade?: number } ``` ## ChartConfig Public chart configuration -- the shape used by the unified API surface. This contains all user-facing fields for creating/updating charts. Internal-only fields (CellId anchors, zIndex, table linking cache) are defined in StoredChartConfig in the charts package. ```typescript type ChartConfig = { type: ChartType; /** Chart sub-type. For type-safe usage, prefer TypedChartConfig which constrains subType to match type. */ subType?: BarSubType | LineSubType | AreaSubType | StockSubType | RadarSubType; /** Anchor row (0-based) */ anchorRow: number; /** Anchor column (0-based) */ anchorCol: number; /** Chart width in cells */ width: number; /** Chart height in cells */ height: number; /** Data range in A1 notation (e.g., "A1:D10"). Optional when series[].values are provided. */ dataRange?: string; /** Series labels range in A1 notation */ seriesRange?: string; /** Category labels range in A1 notation */ categoryRange?: string; seriesOrientation?: SeriesOrientation; title?: string; subtitle?: string; legend?: LegendConfig; axis?: AxisConfig; colors?: string[]; series?: SeriesConfig[]; dataLabels?: DataLabelConfig; pieSlice?: PieSliceConfig; /** @deprecated Use trendlines[] instead — kept for backward compat */ trendline?: TrendlineConfig; /** Wire-compatible trendline array */ trendlines?: TrendlineConfig[]; /** Connect scatter points with lines (scatter-lines variant) */ showLines?: boolean; /** Use smooth curves for scatter lines (scatter-smooth-lines variant) */ smoothLines?: boolean; /** Fill area under radar lines */ radarFilled?: boolean; /** Show markers on radar vertices */ radarMarkers?: boolean; /** How blank cells are plotted: 'gap' (leave gap), 'zero' (treat as zero), 'span' (interpolate) */ displayBlanksAs?: 'gap' | 'zero' | 'span'; /** Whether to plot only visible cells (respecting row/column hiding) */ plotVisibleOnly?: boolean; /** Gap width between bars/columns as percentage (0-500). Applied to bar/column chart types. */ gapWidth?: number; /** Overlap between bars/columns (-100 to 100). Applied to clustered bar/column types. */ overlap?: number; /** Hole size for doughnut charts as percentage (10-90) */ doughnutHoleSize?: number; /** First slice angle for pie/doughnut charts in degrees (0-360) */ firstSliceAngle?: number; /** Bubble scale for bubble charts as percentage (0-300) */ bubbleScale?: number; /** Split type for of-pie charts (pie-of-pie, bar-of-pie) */ splitType?: 'auto' | 'value' | 'percent' | 'position' | 'custom'; /** Split value threshold for of-pie charts */ splitValue?: number; waterfall?: WaterfallConfig; histogram?: HistogramConfig; boxplot?: BoxplotConfig; heatmap?: HeatmapConfig; violin?: ViolinConfig; name?: string; chartTitle?: TitleConfig; chartArea?: ChartAreaConfig; plotArea?: PlotAreaConfig; style?: number; roundedCorners?: boolean; autoTitleDeleted?: boolean; showDataLabelsOverMaximum?: boolean; chartFormat?: ChartFormat; plotFormat?: ChartFormat; titleFormat?: ChartFormat; titleRichText?: ChartFormatString[]; titleFormula?: string; dataTable?: DataTableConfig; /** Which level of multi-level category labels to show (0-based). */ categoryLabelLevel?: number; /** Which level of multi-level series names to show (0-based). */ seriesNameLevel?: number; /** Show/hide all pivot field buttons on the chart. */ showAllFieldButtons?: boolean; /** Size of the secondary plot for PieOfPie/BarOfPie charts (5-200%). OOXML c:secondPieSize. */ secondPlotSize?: number; /** Use different colors per category. OOXML c:varyColors (chart-group level). */ varyByCategories?: boolean; /** Pivot chart display options. */ pivotOptions?: PivotChartOptions; /** Z-order command for layering charts. Accepted as a convenience field by ws.charts.update() to adjust z-index: - 'front': bring to top of stack - 'back': send to bottom of stack - 'forward': move one layer up - 'backward': move one layer down */ zOrder?: 'front' | 'back' | 'forward' | 'backward'; /** Mark shape for 3D bar/column charts (default: 'box'). Maps to OOXML c:shape. */ barShape?: 'box' | 'cylinder' | 'cone' | 'pyramid'; /** Extensible extra data for enriched chart configurations. Contains additional chart-specific settings (e.g., chartTitle font, chartArea fill) that are stored on the chart but not part of the core config schema. */ extra?: unknown; /** Chart height in points */ heightPt?: number; /** Chart width in points */ widthPt?: number; /** Left offset in points */ leftPt?: number; /** Top offset in points */ topPt?: number; /** Enable 3D bubble effect for bubble charts */ bubble3DEffect?: boolean; /** Render surface chart as wireframe */ wireframe?: boolean; /** Use surface chart top-down view (contour) */ surfaceTopView?: boolean; /** Chart color scheme index */ colorScheme?: number; } ``` ## ChartFill Fill. Maps to OOXML EG_FillProperties. ```typescript type ChartFill = | { type: 'none' } | { type: 'solid'; color: ChartColor; transparency?: number } | { type: 'gradient'; gradientType: 'linear' | 'radial' | 'rectangular'; angle?: number; stops: { position: number; color: ChartColor; transparency?: number }[]; } | { type: 'pattern'; pattern: string; foreground?: ChartColor; background?: ChartColor } ``` ## ChartFont Font. Maps to OOXML tx_pr → defRPr. ```typescript type ChartFont = { name?: string; size?: number; bold?: boolean; italic?: boolean; color?: ChartColor; underline?: | 'none' | 'single' | 'double' | 'singleAccountant' | 'doubleAccountant' | 'dash' | 'dashLong' | 'dotDash' | 'dotDotDash' | 'dotted' | 'heavy' | 'wavy' | 'wavyDouble' | 'wavyHeavy' | 'words'; strikethrough?: 'single' | 'double'; } ``` ## ChartFormat Composite format for a chart element. ```typescript type ChartFormat = { fill?: ChartFill; line?: ChartLineFormat; font?: ChartFont; textRotation?: number; shadow?: ChartShadow; } ``` ## ChartFormatString A styled text run for rich text in chart titles and data labels. ```typescript type ChartFormatString = { text: string; font?: ChartFont; } ``` ## ChartHandle Chart handle — hosting ops only. Content ops (series, categories, type, data range) via ws.charts.* ```typescript type ChartHandle = { duplicate(offsetX?: number, offsetY?: number): Promise;; getData(): Promise;; } ``` ## ChartLeaderLinesFormat Leader line formatting for data labels. ```typescript type ChartLeaderLinesFormat = { format: ChartLineFormat; } ``` ## ChartLineFormat Line/border. Maps to OOXML CT_LineProperties. ```typescript type ChartLineFormat = { color?: ChartColor; width?: number; dashStyle?: 'solid' | 'dot' | 'dash' | 'dashDot' | 'longDash' | 'longDashDot' | 'longDashDotDot'; transparency?: number; } ``` ## ChartObject Chart floating object. Integrates charts with the FloatingObjectManager to provide: - Hit-testing for selection - Drag/resize/z-order operations - Consistent interaction model with other floating objects Architecture Notes: - Uses Cell Identity Model with CellIdRange references (CRDT-safe) - Full chart configuration lives in the Charts domain module - This interface provides the FloatingObject layer for interactions - Position resolution happens at render time via CellPositionLookup @example // Chart data range A1:D10 const chart: ChartObject = { id: 'chart-1', type: 'chart', sheetId: 'sheet-abc', position: { anchorType: 'oneCell', from: { cellId: '...', xOffset: 0, yOffset: 0 }, width: 400, height: 300 }, zIndex: 1, locked: false, printable: true, chartType: 'column', anchorMode: 'oneCell', widthCells: 8, heightCells: 15, chartConfig: { series: [], axes: {} }, dataRangeIdentity: { topLeftCellId: '...', bottomRightCellId: '...' } }; ```typescript type ChartObject = { type: 'chart'; /** The type of chart (bar, line, pie, etc.) */ chartType: ChartObjectType; /** How chart anchors to cells - affects resize behavior. - 'oneCell': Chart moves with anchor cell, but doesn't resize with cell changes - 'twoCell': Chart moves and resizes with both anchor cells */ anchorMode: 'oneCell' | 'twoCell'; /** Width in cell units (for oneCell mode sizing). In twoCell mode, width is determined by the anchor cell positions. */ widthCells: number; /** Height in cell units (for oneCell mode sizing). In twoCell mode, height is determined by the anchor cell positions. */ heightCells: number; /** Full chart configuration (series, axes, legend, colors, etc.). Stored directly on the floating object as a sub-object field, following the same pattern as fill/outline/shadow on shapes. */ chartConfig: Record; /** Chart data range using CellId corners (CRDT-safe). Automatically expands when rows/cols inserted between corners. Optional because some charts may have inline data or external sources. */ dataRangeIdentity?: CellIdRange; /** Series labels range using CellId corners (CRDT-safe). Used to label each data series in the chart. */ seriesRangeIdentity?: CellIdRange; /** Category labels range using CellId corners (CRDT-safe). Used for x-axis labels in most chart types. */ categoryRangeIdentity?: CellIdRange; } ``` ## ChartObjectType Supported chart types for the ChartObject. Matches the ChartType from charts package but defined here for contracts. ```typescript type ChartObjectType = | 'bar' | 'column' | 'line' | 'area' | 'pie' | 'doughnut' | 'scatter' | 'bubble' | 'combo' | 'radar' | 'stock' | 'funnel' | 'waterfall' ``` ## ChartSeriesDimension Dimension identifiers for series data access. ```typescript type ChartSeriesDimension = 'categories' | 'values' | 'bubbleSizes' ``` ## ChartShadow Shadow effect for chart elements. ```typescript type ChartShadow = { visible?: boolean; color?: ChartColor; blur?: number; offsetX?: number; offsetY?: number; transparency?: number; } ``` ## ChartType Supported chart types with Excel parity ```typescript type ChartType = | 'bar' | 'column' | 'line' | 'area' | 'pie' | 'doughnut' | 'scatter' | 'bubble' | 'combo' | 'radar' | 'stock' | 'funnel' | 'waterfall' // OOXML roundtrip types | 'surface' | 'surface3d' | 'ofPie' | 'bar3d' | 'column3d' | 'line3d' | 'pie3d' | 'area3d' // Statistical chart types | 'histogram' | 'boxplot' | 'heatmap' | 'violin' | 'pareto' // Exploded pie variants | 'pieExploded' | 'pie3dExploded' | 'doughnutExploded' // Bubble with 3D effect | 'bubble3DEffect' // Surface variants | 'surfaceWireframe' | 'surfaceTopView' | 'surfaceTopViewWireframe' // Line with markers | 'lineMarkers' | 'lineMarkersStacked' | 'lineMarkersStacked100' // Decorative 3D shape charts (cylinder) | 'cylinderColClustered' | 'cylinderColStacked' | 'cylinderColStacked100' | 'cylinderBarClustered' | 'cylinderBarStacked' | 'cylinderBarStacked100' | 'cylinderCol' // Decorative 3D shape charts (cone) | 'coneColClustered' | 'coneColStacked' | 'coneColStacked100' | 'coneBarClustered' | 'coneBarStacked' | 'coneBarStacked100' | 'coneCol' // Decorative 3D shape charts (pyramid) | 'pyramidColClustered' | 'pyramidColStacked' | 'pyramidColStacked100' | 'pyramidBarClustered' | 'pyramidBarStacked' | 'pyramidBarStacked100' | 'pyramidCol' ``` ## CheckboxControl Checkbox control - reads/writes boolean to linked cell. NO local "checked" state - value lives in cell. This is critical for single source of truth. Data flow: 1. Render: Read from cell → `checked = store.getCellValueById(linkedCellId) === true` 2. Click: Write to cell → `store.setCellValueById(linkedCellId, !checked)` 3. EventBus fires → component re-renders with new value @example // Cell A1 contains TRUE/FALSE // Checkbox linked to A1 // Formula =IF(A1, "Yes", "No") works automatically ```typescript type CheckboxControl = { type: 'checkbox'; /** REQUIRED - Cell that holds the boolean value. Uses CellId for stability across row/col insert/delete. Expected cell values: - TRUE, true, 1 → checked - FALSE, false, 0, empty → unchecked */ linkedCellId: CellId; /** Optional label displayed next to checkbox */ label?: string; /** Value to write when checked. Default: true (boolean TRUE) */ checkedValue?: unknown; /** Value to write when unchecked. Default: false (boolean FALSE) */ uncheckedValue?: unknown; } ``` ## CheckpointInfo Information about a saved checkpoint (version snapshot). ```typescript type CheckpointInfo = { /** Unique checkpoint ID */ id: string; /** Optional human-readable label */ label?: string; /** Creation timestamp (Unix ms) */ timestamp: number; } ``` ## ChromeTheme Theme colors for the spreadsheet chrome — the UI shell surrounding cell content. Controls canvas background, gridlines, headers, selection indicators, scrollbars, and drag-drop overlays. Cell content colors are governed by ThemeDefinition / conditional formatting, not this interface. ```typescript type ChromeTheme = { canvasBackground: string; gridlineColor: string; headerBackground: string; headerText: string; headerBorder: string; headerHighlightBackground: string; headerHighlightText: string; selectionFill: string; selectionBorder: string; activeCellBorder: string; fillHandleColor: string; dragSourceColor: string; dragTargetColor: string; scrollbarTrack: string; scrollbarThumb: string; } ``` ## ClearApplyTo Determines which aspects of a range to clear. Matches OfficeJS Excel.ClearApplyTo enum. ```typescript type ClearApplyTo = 'all' | 'contents' | 'formats' | 'hyperlinks' ``` ## ClearResult Confirmation returned by clearData() and clear(). ```typescript type ClearResult = { /** Number of cells in the cleared range. */ cellCount: number; } ``` ## CodeResult Result of a code execution. ```typescript type CodeResult = { /** Whether execution completed successfully */ success: boolean; /** Captured console output */ output?: string; /** Error message (if success is false) */ error?: string; /** Execution duration in milliseconds */ duration?: number; } ``` ## ColumnFilterCriteria Column filter criteria - what's applied to a single column. Each column in a filter range can have its own criteria. Rows must match ALL column filters (AND logic across columns). ```typescript type ColumnFilterCriteria = { /** Type of filter applied to this column. - value: Checkbox list of specific values to include - condition: Operator-based rules (equals, contains, etc.) - color: Filter by cell background or font color - top10: Top/bottom N items or percent */ type: 'value' | 'condition' | 'color' | 'top10' | 'dynamic'; /** For value filters: list of values to INCLUDE (show). Unchecked values in the dropdown are excluded (hidden). Include empty string or null to show blank cells. */ values?: CellValue[]; /** For value filters: explicitly include blank cells. When present, takes precedence over inferring from values array. */ includeBlanks?: boolean; /** For condition filters: one or two filter conditions. When two conditions are present, conditionLogic determines how they combine. */ conditions?: FilterCondition[]; /** Logic for combining multiple conditions. - 'and': Row must match ALL conditions - 'or': Row must match ANY condition Default: 'and' */ conditionLogic?: 'and' | 'or'; /** For color filters: filter by background or font color. */ colorFilter?: { /** Whether to filter by background fill or font color */ type: 'background' | 'font'; /** Hex color to match (e.g., '#ff0000') */ color: string; }; /** For top/bottom N filters: show only the highest or lowest values. */ topBottom?: { /** Show top values or bottom values */ type: 'top' | 'bottom'; /** Number of items or percentage */ count: number; /** Whether count is number of items or percentage */ by: 'items' | 'percent' | 'sum'; }; /** For dynamic filters: a pre-defined rule resolved against live data. Examples: above average, below average, today, this month, etc. */ dynamicFilter?: { /** The dynamic filter rule to apply */ rule: DynamicFilterRule; }; } ``` ## ColumnMapping Column mapping for a sheet data binding. ```typescript type ColumnMapping = { /** Column index to write to (0-indexed) */ columnIndex: number; /** JSONPath or field name to extract from data */ dataPath: string; /** Optional transform formula (receives value as input) */ transform?: string; /** Header text (if headerRow >= 0) */ headerText?: string; } ``` ## ComboBoxControl ComboBox control - dropdown selection linked to cell. NO local "selectedIndex" state - value lives in cell. Cell stores the selected VALUE (string), not the index. Data flow: 1. Render: Read from cell → find matching item index 2. Select: Write to cell → `store.setCellValueById(linkedCellId, selectedItem)` 3. EventBus fires → component re-renders with new selection Items can be: - Static: `items: ['Option A', 'Option B', 'Option C']` - Dynamic: `itemsSourceRef: { startId: 'abc', endId: 'xyz' }` (range of cells) ```typescript type ComboBoxControl = { type: 'comboBox'; /** REQUIRED - Cell that holds the selected value. Uses CellId for stability across row/col insert/delete. Stores the selected item VALUE (string), not index. This makes formulas like =VLOOKUP(A1, ...) work naturally. */ linkedCellId: CellId; /** Static items list. Use this for fixed options that don't change. */ items?: string[]; /** Dynamic items from a cell range. Uses IdentityRangeRef (CellId-based) for stability. Range values are read at render time. If both `items` and `itemsSourceRef` are set, `itemsSourceRef` takes precedence. */ itemsSourceRef?: IdentityRangeRef; /** Placeholder text when no value is selected. */ placeholder?: string; /** Whether to allow typing to filter items. Default: true */ filterable?: boolean; } ``` ## Comment A comment attached to a cell. Design decisions: - Comments reference cells via CellId (stable across structure changes) - Content is RichText for formatting support - Threading via parentId enables reply chains - resolved flag supports review workflows - NO sheetId stored - it's implicit from SheetMaps location (like merges.ts) @example // Simple comment { id: 'comment-123', cellRef: 'cell-456', author: 'Alice', createdAt: 1704240000000, content: [{ text: 'This looks correct' }], threadId: 'comment-123' // First comment is its own thread root } @example // Reply to a comment { id: 'comment-789', cellRef: 'cell-456', author: 'Bob', createdAt: 1704240600000, content: [{ text: 'Thanks for checking!' }], threadId: 'comment-123', // Belongs to Alice's thread parentId: 'comment-123' // Direct reply to Alice } ```typescript type Comment = { /** Unique identifier (UUID v7 for ordering) */ id: string; /** Cell this comment is attached to (stable CellId, not position) */ cellRef: CellId; /** Comment author display name */ author: string; /** Author's user ID (for collaboration) */ authorId?: string; /** Creation timestamp (Unix ms) */ createdAt: number; /** Last modification timestamp */ modifiedAt?: number; /** Rich text content */ content: RichText; /** Thread ID for grouped comments. The first comment in a thread uses its own ID as threadId. Subsequent replies share the same threadId. */ threadId?: string; /** Parent comment ID for replies */ parentId?: string; /** Whether the thread is resolved */ resolved?: boolean; } ``` ## CommentMention A mention of a user within a comment's rich text content. ```typescript type CommentMention = { displayText: string; userId: string; email?: string; startIndex: number; length: number; } ``` ## CompoundLineStyle Compound line style. ```typescript type CompoundLineStyle = 'single' | 'double' | 'thickThin' | 'thinThick' | 'triple' ``` ## ComputedConnector Computed connector between two nodes. ```typescript type ComputedConnector = { /** Source node ID */ fromNodeId: NodeId; /** Target node ID */ toNodeId: NodeId; /** Connector type */ connectorType: ConnectorType; /** Path data for rendering */ path: ConnectorPath; /** Stroke color (CSS color string) */ stroke: string; /** Stroke width in pixels */ strokeWidth: number; /** Arrow head at start of connector */ arrowStart?: ArrowHead; /** Arrow head at end of connector */ arrowEnd?: ArrowHead; } ``` ## ComputedLayout Computed layout result (runtime cache, NOT persisted to Yjs). This is calculated by layout algorithms and cached by the bridge. Invalidated whenever the diagram structure or styling changes. Layout computation is expensive, so this cache avoids recalculating positions on every render. ```typescript type ComputedLayout = { /** Computed shape positions and styles for each node */ shapes: ComputedShape[]; /** Computed connector paths between nodes */ connectors: ComputedConnector[]; /** Overall bounds of the rendered diagram */ bounds: { width: number; height: number }; /** Version number, incremented on each layout change */ version: number; } ``` ## ComputedShape Computed shape position and style for a single node. Contains all information needed to render a node's shape. ```typescript type ComputedShape = { /** The node this shape represents */ nodeId: NodeId; /** Shape type to render */ shapeType: SmartArtShapeType; /** X position in pixels (relative to diagram origin) */ x: number; /** Y position in pixels (relative to diagram origin) */ y: number; /** Width in pixels */ width: number; /** Height in pixels */ height: number; /** Rotation angle in degrees */ rotation: number; /** Fill color (CSS color string) */ fill: string; /** Stroke/border color (CSS color string) */ stroke: string; /** Stroke width in pixels */ strokeWidth: number; /** Text content to display */ text: string; /** Text styling */ textStyle: TextStyle; /** Visual effects (shadow, glow, etc.) */ effects: ShapeEffects; } ``` ## ConditionalFormat A conditional format definition — associates rules with cell ranges. This is the public API type. The kernel stores additional internal fields (CellIdRange for CRDT-safe structure change handling) that are resolved to position-based ranges before being returned through the API. ```typescript type ConditionalFormat = { /** Unique format identifier. */ id: string; /** Sheet this format belongs to. */ sheetId?: string; /** Whether this CF was created from a pivot table. */ pivot?: boolean; /** Cell ranges this format applies to. */ ranges: CellRange[]; /** CellId-based range identities for CRDT-safe tracking. */ rangeIdentities?: { topLeftCellId: string; bottomRightCellId: string }[]; /** Rules to evaluate (sorted by priority). */ rules: CFRule[]; } ``` ## ConditionalFormatUpdate Update payload for a conditional format. ```typescript type ConditionalFormatUpdate = { /** Replace the rules array. */ rules?: CFRule[]; /** Replace the ranges this format applies to. */ ranges?: CellRange[]; /** Set stopIfTrue on all rules in this format. */ stopIfTrue?: boolean; } ``` ## ConnectorHandle ```typescript type ConnectorHandle = { /** Update connector routing, endpoints, fill, outline. ConnectorConfig pending — uses generic record. */ update(props: Record): Promise;; duplicate(offsetX?: number, offsetY?: number): Promise;; getData(): Promise;; } ``` ## ConnectorObject Connector floating object. A line or connector shape that links two objects (or floats freely). Connectors have optional arrowheads and connection site bindings. ```typescript type ConnectorObject = { type: 'connector'; /** Connector shape preset (e.g., straightConnector1, bentConnector3) */ shapeType: ShapeType; /** Start connection binding (which shape and site index) */ startConnection?: { shapeId: string; siteIndex: number }; /** End connection binding (which shape and site index) */ endConnection?: { shapeId: string; siteIndex: number }; /** Fill configuration */ fill?: ObjectFill; /** Outline/stroke configuration (includes arrowheads) */ outline?: ShapeOutline; } ``` ## ConnectorPath Path data for rendering a connector. ```typescript type ConnectorPath = { /** Path type */ type: 'line' | 'bezier' | 'polyline'; /** Points along the path */ points: Array<{ x: number; y: number }>; /** Control points for bezier curves */ controlPoints?: Array<{ x: number; y: number }>; } ``` ## ConnectorType Type of connector line between nodes. ```typescript type ConnectorType = 'straight' | 'elbow' | 'curved' | 'none' ``` ## CopyFromOptions Options for Range.copyFrom() operation. ```typescript type CopyFromOptions = { /** What to copy — defaults to 'all'. */ copyType?: CopyType; /** Skip blank source cells (preserve target values where source is empty). */ skipBlanks?: boolean; /** Transpose rows ↔ columns during copy. */ transpose?: boolean; } ``` ## CopyType Specifies what data to copy in a range copy operation. Maps to OfficeJS `Excel.RangeCopyType`. ```typescript type CopyType = 'all' | 'formulas' | 'values' | 'formats' ``` ## CreateBindingConfig Configuration for creating a sheet data binding. ```typescript type CreateBindingConfig = { /** Connection providing the data */ connectionId: string; /** Maps data fields to columns */ columnMappings: ColumnMapping[]; /** Auto-insert/delete rows to match data length (default: true) */ autoGenerateRows?: boolean; /** Row index for headers (-1 = no header row, default: 0) */ headerRow?: number; /** First row of data (0-indexed, default: 1) */ dataStartRow?: number; /** Preserve header row formatting on refresh (default: true) */ preserveHeaderFormatting?: boolean; } ``` ## CreateDrawingOptions Options for creating a new drawing object. ```typescript type CreateDrawingOptions = { /** Optional name for the drawing object */ name?: string; /** Alt text for accessibility */ altText?: string; /** Whether the drawing is locked */ locked?: boolean; /** Whether the drawing appears in print */ printable?: boolean; /** Initial background color */ backgroundColor?: string; /** Initial tool settings */ toolState?: Partial; } ``` ## CreateNamesFromSelectionOptions Options for creating named ranges from row/column labels in a selection. ```typescript type CreateNamesFromSelectionOptions = { /** Create names from labels in the top row of the selection. */ top?: boolean; /** Create names from labels in the left column of the selection. */ left?: boolean; /** Create names from labels in the bottom row of the selection. */ bottom?: boolean; /** Create names from labels in the right column of the selection. */ right?: boolean; } ``` ## CreateNamesResult Result of a create-names-from-selection operation. ```typescript type CreateNamesResult = { /** Number of names successfully created. */ success: number; /** Number of names skipped (already exist or invalid). */ skipped: number; } ``` ## CreateSparklineGroupOptions Options for creating a sparkline group. ```typescript type CreateSparklineGroupOptions = { /** Whether data is in rows (true) or columns (false) */ dataInRows?: boolean; /** Shared visual settings */ visual?: Partial; /** Shared axis settings */ axis?: Partial; } ``` ## CreateSparklineOptions Options for creating a new sparkline. ```typescript type CreateSparklineOptions = { /** Whether data is in rows (true) or columns (false) */ dataInRows?: boolean; /** Visual settings override */ visual?: Partial; /** Axis settings override */ axis?: Partial; } ``` ## CreateTableOptions Options for the one-liner createTable() convenience method. ```typescript type CreateTableOptions = { /** Column header names. */ headers: string[]; /** Data rows (each row must match headers length). */ data: CellValue[][]; /** Top-left cell address to start writing (default: "A1"). */ startCell?: string; } ``` ## CrossFilterMode ST_SlicerCacheCrossFilter mode. Canonical source: compute-types.gen.ts ```typescript type CrossFilterMode = 'none' | 'showItemsWithDataAtTop' | 'showItemsWithNoData' ``` ## CultureInfo Complete culture information for formatting numbers, dates, and currencies. All properties are required - no partial cultures allowed. Use the culture registry to get complete CultureInfo objects. @example ```typescript const culture = getCulture('de-DE'); // culture.decimalSeparator === ',' // culture.thousandsSeparator === '.' // culture.monthNames[0] === 'Januar' ``` ```typescript type CultureInfo = { /** IETF language tag (e.g., 'en-US', 'de-DE', 'ja-JP'). This is the key used to look up the culture in the registry. */ name: string; /** Human-readable display name (e.g., 'English (United States)'). Used in UI dropdowns. */ displayName: string; /** Native name in the culture's own language (e.g., 'Deutsch (Deutschland)'). */ nativeName: string; /** ISO 639-1 two-letter language code (e.g., 'en', 'de', 'ja'). */ twoLetterLanguageCode: string; /** Decimal separator character (e.g., '.' for en-US, ',' for de-DE). */ decimalSeparator: string; /** Thousands/grouping separator (e.g., ',' for en-US, '.' for de-DE, ' ' for fr-FR). */ thousandsSeparator: string; /** Negative sign (usually '-'). */ negativeSign: string; /** Positive sign (usually '+' or ''). */ positiveSign: string; /** Pattern for negative numbers. */ negativeNumberPattern: NegativeNumberPattern; /** Number of digits per group (usually 3). Some cultures use variable grouping (e.g., Indian: 3, then 2, 2, 2...). For simplicity, we use a single value in v1. */ numberGroupSize: number; /** Percent symbol (usually '%'). */ percentSymbol: string; /** Per mille symbol (‰). */ perMilleSymbol: string; /** Pattern for positive percentages. */ percentPositivePattern: PercentPositivePattern; /** Pattern for negative percentages. */ percentNegativePattern: PercentNegativePattern; /** Default currency symbol for this culture (e.g., '$', '€', '¥'). */ currencySymbol: string; /** ISO 4217 currency code (e.g., 'USD', 'EUR', 'JPY'). */ currencyCode: string; /** Pattern for positive currency values. */ currencyPositivePattern: CurrencyPositivePattern; /** Pattern for negative currency values. */ currencyNegativePattern: CurrencyNegativePattern; /** Number of decimal digits for currency (e.g., 2 for USD, 0 for JPY). */ currencyDecimalDigits: number; /** Date separator (e.g., '/' for en-US, '.' for de-DE). */ dateSeparator: string; /** Time separator (e.g., ':'). */ timeSeparator: string; /** Short date pattern (e.g., 'M/d/yyyy' for en-US, 'dd.MM.yyyy' for de-DE). Used for format code interpretation. */ shortDatePattern: string; /** Long date pattern (e.g., 'dddd, MMMM d, yyyy'). */ longDatePattern: string; /** Short time pattern (e.g., 'h:mm tt' for en-US, 'HH:mm' for de-DE). */ shortTimePattern: string; /** Long time pattern (e.g., 'h:mm:ss tt' for en-US, 'HH:mm:ss' for de-DE). */ longTimePattern: string; /** AM designator (e.g., 'AM' for en-US, '' for 24-hour cultures). */ amDesignator: string; /** PM designator (e.g., 'PM' for en-US, '' for 24-hour cultures). */ pmDesignator: string; /** First day of the week (0 = Sunday, 1 = Monday). */ firstDayOfWeek: DayOfWeek; /** Full month names (12 entries, January = index 0). */ monthNames: readonly [ string, string, string, string, string, string, string, string, string, string, string, string, ]; /** Abbreviated month names (12 entries, Jan = index 0). */ abbreviatedMonthNames: readonly [ string, string, string, string, string, string, string, string, string, string, string, string, ]; /** Full day names (7 entries, Sunday = index 0). */ dayNames: readonly [string, string, string, string, string, string, string]; /** Abbreviated day names (7 entries, Sun = index 0). */ abbreviatedDayNames: readonly [string, string, string, string, string, string, string]; /** Shortest day names (7 entries, typically 1-2 letters). Used in narrow calendar UIs. */ shortestDayNames: readonly [string, string, string, string, string, string, string]; /** String for TRUE value (e.g., 'TRUE', 'WAHR', 'VRAI'). */ trueString: string; /** String for FALSE value (e.g., 'FALSE', 'FALSCH', 'FAUX'). */ falseString: string; /** List separator (e.g., ',' for en-US, ';' for de-DE). This affects function argument separators in formulas. */ listSeparator: string; } ``` ## CurrencyNegativePattern Currency negative pattern (matches .NET NumberFormatInfo). Determines how negative currency values are displayed. 0 = ($n) - en-US accounting 1 = -$n - en-US standard 2 = $-n 3 = $n- 4 = (n$) 5 = -n$ 6 = n-$ 7 = n$- 8 = -n $ - de-DE 9 = -$ n 10 = n $- 11 = $ n- 12 = $ -n 13 = n- $ 14 = ($ n) 15 = (n $) ```typescript type CurrencyNegativePattern = | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 ``` ## CurrencyPositivePattern Currency positive pattern (matches .NET NumberFormatInfo). Determines where the currency symbol appears relative to the number. 0 = $n (symbol before, no space) - en-US 1 = n$ (symbol after, no space) 2 = $ n (symbol before, space) 3 = n $ (symbol after, space) - de-DE, fr-FR ```typescript type CurrencyPositivePattern = 0 | 1 | 2 | 3 ``` ## DataLabelConfig Data label configuration (matches DataLabelData wire type) ```typescript type DataLabelConfig = { show: boolean; position?: | 'center' | 'insideEnd' | 'insideBase' | 'outsideEnd' | 'left' | 'right' | 'top' | 'bottom' | 'bestFit' | 'callout' | 'outside' | 'inside'; format?: string; showValue?: boolean; showCategoryName?: boolean; showSeriesName?: boolean; showPercentage?: boolean; showBubbleSize?: boolean; showLegendKey?: boolean; separator?: string; showLeaderLines?: boolean; text?: string; visualFormat?: ChartFormat; numberFormat?: string; /** Text orientation angle in degrees (-90 to 90) */ textOrientation?: number; richText?: ChartFormatString[]; /** Whether the label auto-generates text from data. */ autoText?: boolean; /** Horizontal text alignment. */ horizontalAlignment?: 'left' | 'center' | 'right' | 'justify' | 'distributed'; /** Vertical text alignment. */ verticalAlignment?: 'top' | 'middle' | 'bottom' | 'justify' | 'distributed'; /** Whether the number format is linked to the source data cell format. */ linkNumberFormat?: boolean; /** Callout shape type (e.g., 'rectangle', 'roundRectangle', 'wedgeRoundRectCallout'). */ geometricShapeType?: string; /** Formula-based label text. */ formula?: string; /** X position in points (read-only, populated from render engine). */ left?: number; /** Y position in points (read-only, populated from render engine). */ top?: number; /** Height in points (read-only, populated from render engine). */ height?: number; /** Width in points (read-only, populated from render engine). */ width?: number; /** Leader line formatting configuration. */ leaderLinesFormat?: ChartLeaderLinesFormat; } ``` ## DataTableConfig Data table configuration (matches ChartDataTableData wire type). ```typescript type DataTableConfig = { showHorzBorder?: boolean; showVertBorder?: boolean; showOutline?: boolean; showKeys?: boolean; format?: ChartFormat; /** Whether to show legend keys in the data table */ showLegendKey?: boolean; /** Whether the data table is visible */ visible?: boolean; } ``` ## DataTableResult Result of Data Table operation. ```typescript type DataTableResult = { /** 2D array of computed results. results[rowIndex][colIndex] is the value when: - rowInputCell = rowValues[rowIndex] - colInputCell = colValues[colIndex] */ results: CellValue[][]; /** Total number of cells computed. */ cellCount: number; /** Time taken in milliseconds. */ elapsedMs: number; /** Whether the operation was cancelled. */ cancelled?: boolean; } ``` ## DatePeriod Date periods for timePeriod rules. ```typescript type DatePeriod = | 'yesterday' | 'today' | 'tomorrow' | 'last7Days' | 'lastWeek' | 'thisWeek' | 'nextWeek' | 'lastMonth' | 'thisMonth' | 'nextMonth' | 'lastQuarter' | 'thisQuarter' | 'nextQuarter' | 'lastYear' | 'thisYear' | 'nextYear' ``` ## DateUnit Unit for date-based series fills. ```typescript type DateUnit = 'day' | 'weekday' | 'month' | 'year' ``` ## DayOfWeek Culture/Locale types for internationalized number, date, and currency formatting. Stream G: Culture & Localization Design principles: 1. CultureInfo is immutable and complete - no partial definitions 2. Culture is workbook-level state (persisted in WorkbookSettings.culture) 3. Format codes are culture-agnostic; culture applies at render time 4. Uses IETF language tags (en-US, de-DE) not Windows locale IDs ```typescript type DayOfWeek = 0 | 1 | 2 | 3 | 4 | 5 | 6 ``` ## DeleteCellsReceipt Receipt for a deleteCellsWithShift mutation. ```typescript type DeleteCellsReceipt = { kind: 'deleteCells'; sheetId: string; range: { startRow: number; startCol: number; endRow: number; endCol: number }; direction: 'left' | 'up'; } ``` ## DeleteColumnsReceipt Receipt for a deleteColumns mutation. ```typescript type DeleteColumnsReceipt = { kind: 'deleteColumns'; sheetId: string; deletedAt: number; count: number; } ``` ## DeleteRowsReceipt Receipt for a deleteRows mutation. ```typescript type DeleteRowsReceipt = { kind: 'deleteRows'; sheetId: string; deletedAt: number; count: number; } ``` ## DelimiterNode Delimiter - Parentheses, brackets, braces, etc. ```typescript type DelimiterNode = { type: 'd'; /** Beginning character (default '(') */ begChr?: string; /** Separator character (default '|') */ sepChr?: string; /** Ending character (default ')') */ endChr?: string; /** Grow with content */ grow?: boolean; /** Shape: 'centered' or 'match' */ shp?: 'centered' | 'match'; /** Content elements (separated by sepChr) */ e: MathNode[][]; } ``` ## Direction Cardinal directions for keyboard navigation and commit actions. ```typescript type Direction = 'up' | 'down' | 'left' | 'right' ``` ## DocumentProperties ```typescript type DocumentProperties = { title?: string; creator?: string; description?: string; subject?: string; created?: string; modified?: string; lastModifiedBy?: string; category?: string; keywords?: string; company?: string; manager?: string; } ``` ## DrawingHandle ```typescript type DrawingHandle = { addStroke(stroke: InkStroke): Promise;; eraseStrokes(strokeIds: StrokeId[]): Promise;; clearStrokes(): Promise;; moveStrokes(strokeIds: StrokeId[], dx: number, dy: number): Promise;; transformStrokes(strokeIds: StrokeId[], transform: StrokeTransformParams): Promise;; findStrokesAtPoint(x: number, y: number, tolerance?: number): Promise;; duplicate(offsetX?: number, offsetY?: number): Promise;; getData(): Promise;; } ``` ## DrawingObject Drawing object floating on the spreadsheet. Extends FloatingObjectBase to integrate with the existing floating object system (selection, drag, resize, z-order, etc.). CRDT-SAFE DESIGN: - Strokes stored as Map to avoid array ordering conflicts - Uses CellId for anchors (survives row/col insert/delete) - Y.Map under the hood for concurrent editing support ```typescript type DrawingObject = { type: 'drawing'; /** Strokes in this drawing, keyed by StrokeId. Using Map instead of array for CRDT safety: - No ordering conflicts when concurrent users add strokes - O(1) lookup/delete by ID - Stable references across edits Render order is determined by stroke createdAt timestamps. */ strokes: Map; /** Current tool settings for this drawing. Persisted per-drawing to remember user preferences. */ toolState: InkToolState; /** Recognition results for strokes in this drawing. Maps from a "recognition ID" to the result. A recognition can be: - A shape recognized from one or more strokes - Text recognized from handwriting strokes */ recognitions: Map; /** Background color of the drawing canvas. - undefined = transparent (shows sheet grid) - CSS color string = solid background */ backgroundColor?: string; } ``` ## DynamicFilterRule Dynamic filter rule — pre-defined filter rules that resolve against live data (e.g. above average, date-relative). Mirrors the Rust DynamicFilterRule enum in compute-core. ```typescript type DynamicFilterRule = | 'aboveAverage' | 'belowAverage' | 'today' | 'yesterday' | 'tomorrow' | 'thisWeek' | 'lastWeek' | 'nextWeek' | 'thisMonth' | 'lastMonth' | 'nextMonth' | 'thisQuarter' | 'lastQuarter' | 'nextQuarter' | 'thisYear' | 'lastYear' | 'nextYear' ``` ## EnterKeyDirection Direction for enter key movement after committing an edit. Issue 8: Settings Panel ```typescript type EnterKeyDirection = 'down' | 'right' | 'up' | 'left' | 'none' ``` ## EqArrayNode Equation Array - Vertically aligned equations ```typescript type EqArrayNode = { type: 'eqArr'; /** Base justification */ baseJc?: 'top' | 'center' | 'bottom'; /** Maximum distribution */ maxDist?: boolean; /** Object distribution */ objDist?: boolean; /** Row spacing rule */ rSpRule?: 0 | 1 | 2 | 3 | 4; /** Row spacing value */ rSp?: number; /** Array rows */ e: MathNode[][]; } ``` ## Equation Main equation data model ```typescript type Equation = { /** Unique equation identifier */ id: EquationId; /** OMML XML string - the canonical storage format. This is what gets written to XLSX files. Example: ...... */ omml: string; /** LaTeX source (optional, for display/editing). Not stored in XLSX - regenerated from OMML on import if needed. */ latex?: string; /** Parsed AST (computed, not persisted). Used for rendering. Regenerated from OMML when needed. */ ast?: MathNode; /** Cached rendered image as data URL. Invalidated when equation changes. */ _cachedImageData?: string; /** Style options */ style: EquationStyle; } ``` ## EquationConfig Configuration for creating a new equation. ```typescript type EquationConfig = { /** LaTeX source for the equation. */ latex: string; /** X position in pixels. */ x?: number; /** Y position in pixels. */ y?: number; /** Width in pixels. */ width?: number; /** Height in pixels. */ height?: number; /** Equation style options. */ style?: EquationStyleConfig; } ``` ## EquationHandle ```typescript type EquationHandle = { update(props: EquationUpdates): Promise;; duplicate(offsetX?: number, offsetY?: number): Promise;; getData(): Promise;; } ``` ## EquationId Unique identifier for an equation ```typescript type EquationId = string & { readonly __brand: 'EquationId' } ``` ## EquationJustification Equation justification within its bounding box ```typescript type EquationJustification = 'left' | 'center' | 'right' | 'centerGroup' ``` ## EquationObject Equation floating object. Contains a mathematical equation rendered as a floating object. ```typescript type EquationObject = { type: 'equation'; /** The equation data */ equation: Equation; } ``` ## EquationStyle Equation rendering style options ```typescript type EquationStyle = { /** Math font family */ fontFamily: MathFont; /** Base font size in points */ fontSize: number; /** Text color (CSS color string) */ color: string; /** Background color (CSS color string, 'transparent' for none) */ backgroundColor: string; /** Justification */ justification: EquationJustification; /** Display mode (block) vs inline mode */ displayMode: boolean; /** Use small fractions (numerator/denominator same size as surrounding) */ smallFractions: boolean; } ``` ## EquationStyleConfig Styling options for an equation. ```typescript type EquationStyleConfig = { /** Font family (default: 'Cambria Math'). */ fontFamily?: string; /** Base font size in points. */ fontSize?: number; /** Text color (CSS). */ color?: string; /** Background color (CSS or 'transparent'). */ backgroundColor?: string; /** Display mode: block (true) vs inline (false). */ displayMode?: boolean; } ``` ## EquationUpdates Updates for an existing equation. ```typescript type EquationUpdates = { /** Updated LaTeX source. */ latex?: string; /** Updated OMML XML. */ omml?: string; /** Updated style options. */ style?: Partial; } ``` ## ErrorBarConfig Error bar configuration for series (matches ErrorBarData wire type) ```typescript type ErrorBarConfig = { visible?: boolean; direction?: string; barType?: string; valueType?: string; value?: number; noEndCap?: boolean; lineFormat?: ChartLineFormat; } ``` ## ExecuteOptions Options for code execution via `workbook.executeCode()`. ```typescript type ExecuteOptions = { /** Maximum execution time in milliseconds */ timeout?: number; /** Whether to run in a sandboxed environment */ sandbox?: boolean; } ``` ## FieldDef Schema-Driven Initialization Types These types define how Yjs structures are specified declaratively. All creation, copying, and lazy-init is derived from schemas. ARCHITECTURE: Single Source of Truth - Field definitions are declared ONCE in a schema - createFromSchema() derives structure initialization - copyFromSchema() derives copy behavior - ensureLazyFields() derives migration behavior This eliminates: - Manual field enumeration in multiple places - Divergent copy vs init logic - Missing fields in new code paths @see plans/active/refactor/SCHEMA-DRIVEN-INITIALIZATION.md ```typescript type FieldDef = { /** The Yjs type or primitive indicator. - 'Y.Map': Creates new Y.Map() - 'Y.Array': Creates new Y.Array() - 'Y.Text': Creates new Y.Text() - 'primitive': Uses the default value directly */ type: 'Y.Map' | 'Y.Array' | 'Y.Text' | 'primitive'; /** Documentation of the value type for Y.Map and Y.Array. Example: 'SerializedCellData' for cells map, 'number' for heights map. This is for documentation only - TypeScript cannot enforce Yjs internals. */ valueType?: string; /** Short name for CRDT storage efficiency (optional). Used by Cell Data schema where 'raw' -> 'r', 'formula' -> 'f', etc. If not specified, the long name (schema key) is used as-is. This is for documentation/mapping purposes. The actual Yjs storage uses the short name, while the API/runtime uses the long name (schema key). */ shortName?: string; /** Whether this field is required during structure creation. - true: Created by createFromSchema() - false: Only created on demand or via lazyInit */ required: boolean; /** Copy strategy for this field. - 'deep': Deep copy (JSON.parse/stringify for plain objects, recursive for Yjs) - 'shallow': Shallow reference copy (same object) - 'skip': Don't copy this field (omit from result) */ copy: 'deep' | 'shallow' | 'skip'; /** Whether to auto-create this field if missing. Used for migration: old documents may lack new fields. ensureLazyFields() creates fields where lazyInit=true and field is missing. */ lazyInit: boolean; /** Default value for primitive fields. Only used when type='primitive'. */ default?: unknown; } ``` ## FillDirection Direction of a fill operation relative to the source range. ```typescript type FillDirection = 'down' | 'right' | 'up' | 'left' ``` ## FillPatternType Pattern type detected by the fill engine. ```typescript type FillPatternType = | 'copy' | 'linear' | 'growth' | 'date' | 'time' | 'weekday' | 'weekdayShort' | 'month' | 'monthShort' | 'quarter' | 'ordinal' | 'textWithNumber' | 'customList' ``` ## FillSeriesOptions Options for the Fill Series dialog (Edit > Fill > Series). ```typescript type FillSeriesOptions = { direction: FillDirection; seriesType: 'linear' | 'growth' | 'date'; stepValue: number; stopValue?: number; dateUnit?: DateUnit; trend?: boolean; } ``` ## FillType Fill type for shapes, text boxes, and connectors. Matches the Rust `FillType` enum in `domain-types`. ```typescript type FillType = 'solid' | 'gradient' | 'pattern' | 'pictureAndTexture' | 'none' ``` ## FilterCondition A single filter condition with operator and value(s). Used in condition filters where users specify rules like "greater than 100" or "contains 'error'". ```typescript type FilterCondition = { /** The comparison operator */ operator: FilterOperator; /** Primary comparison value (not used for isBlank/isNotBlank) */ value?: CellValue; /** Secondary value for 'between' operator (inclusive range) */ value2?: CellValue; } ``` ## FilterDetailInfo Detailed filter information including resolved numeric range and column filters. ```typescript type FilterDetailInfo = { /** Filter ID */ id: string; /** Resolved numeric range of the filter */ range: { startRow: number; startCol: number; endRow: number; endCol: number }; /** Per-column filter criteria, keyed by header cell ID */ columnFilters: Record; } ``` ## FilterInfo Information about a filter applied to a sheet. ```typescript type FilterInfo = { /** Filter ID */ id: string; /** The filtered range */ range?: string; /** Per-column filter criteria */ columns?: Record; /** Table ID if this filter is associated with a table. */ tableId?: string; /** Per-column filter criteria, keyed by column identifier. */ columnFilters?: Record; } ``` ## FilterOperator ```typescript type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'notContains' | 'startsWith' | 'endsWith' | 'greaterThan' | 'greaterThanOrEqual' | 'lessThan' | 'lessThanOrEqual' | 'between' | 'notBetween' | 'isBlank' | 'isNotBlank' | 'aboveAverage' | 'belowAverage' ``` ## FilterSortState Sort state for a filter. ```typescript type FilterSortState = { /** Column index or header cell ID to sort by */ column: string | number; /** Sort direction */ direction: 'asc' | 'desc'; /** Sort criteria (optional, for advanced sorting) */ criteria?: any; } ``` ## FilterState API filter state — derived from Rust FilterState with A1-notation range. ```typescript type FilterState = { /** The range the auto-filter is applied to (A1 notation) */ range: string; /** Per-column filter criteria, keyed by column identifier (string) */ columnFilters: Record; } ``` ## FloatingObject Union of all floating object types. Use type narrowing on the 'type' discriminator to access specific properties. ```typescript type FloatingObject = | PictureObject | TextBoxObject | ShapeObject | ConnectorObject | ChartObject | DrawingObject | EquationObject | SmartArtObject | OleObjectObject ``` ## FloatingObjectDeleteReceipt Receipt for a floating object deletion mutation. ```typescript type FloatingObjectDeleteReceipt = { domain: 'floatingObject'; action: 'delete'; id: string; } ``` ## FloatingObjectHandle ```typescript type FloatingObjectHandle = { /** Stable object ID. */ id: string; /** Discriminator for type narrowing. */ type: FloatingObjectKind; /** Move by delta. dx/dy are pixel offsets (relative). Rust resolves to new cell anchor. */ move(dx: number, dy: number): Promise;; /** Set absolute dimensions in pixels. */ resize(width: number, height: number): Promise;; /** Set absolute rotation angle in degrees. */ rotate(angle: number): Promise;; /** Flip horizontally or vertically. */ flip(axis: 'horizontal' | 'vertical'): Promise;; bringToFront(): Promise;; sendToBack(): Promise;; bringForward(): Promise;; sendBackward(): Promise;; delete(): Promise;; duplicate(offsetX?: number, offsetY?: number): Promise;; /** Sync pixel bounds from scene graph. Null if not rendered yet. */ getBounds(): ObjectBounds | null;; /** Full object data (async — reads from store). */ getData(): Promise;; isShape(): this is ShapeHandle;; isPicture(): this is PictureHandle;; isTextBox(): this is TextBoxHandle;; isDrawing(): this is DrawingHandle;; isEquation(): this is EquationHandle;; isWordArt(): this is WordArtHandle;; isSmartArt(): this is SmartArtHandle;; isChart(): this is ChartHandle;; isConnector(): this is ConnectorHandle;; isOleObject(): this is OleObjectHandle;; isSlicer(): this is SlicerHandle;; /** Narrowing with throw — use when type is expected. */ asShape(): ShapeHandle;; asPicture(): PictureHandle;; asTextBox(): TextBoxHandle;; asDrawing(): DrawingHandle;; asEquation(): EquationHandle;; asWordArt(): WordArtHandle;; asSmartArt(): SmartArtHandle;; asChart(): ChartHandle;; asConnector(): ConnectorHandle;; asOleObject(): OleObjectHandle;; asSlicer(): SlicerHandle;; } ``` ## FloatingObjectInfo Summary information about a floating object (returned by listFloatingObjects). ```typescript type FloatingObjectInfo = { /** Unique object ID. */ id: string; /** Object type discriminator. */ type: FloatingObjectType; /** Optional display name. */ name?: string; /** X position in pixels. */ x: number; /** Y position in pixels. */ y: number; /** Width in pixels. */ width: number; /** Height in pixels. */ height: number; /** Rotation angle in degrees. */ rotation?: number; /** Flipped horizontally. */ flipH?: boolean; /** Flipped vertically. */ flipV?: boolean; /** Z-order index. */ zIndex?: number; /** Whether the object is visible. */ visible?: boolean; /** ID of the parent group (if this object is grouped). */ groupId?: string; /** Anchor mode (twoCell/oneCell/absolute). */ anchorType?: ObjectAnchorType; /** Alt text for accessibility. */ altText?: string; } ``` ## FloatingObjectKind Object type discriminator. Used for type narrowing in union types. Extends CanvasObjectType (which is `string`) with a specific union for spreadsheet object types. This ensures backward compatibility: any code expecting FloatingObjectKind still gets the specific union, while CanvasObjectType-based code accepts it as a string. Storage-layer discriminant for floating objects. Mirrors Rust FloatingObjectKind. See also FloatingObjectType in api/types.ts (API-layer superset that adds 'wordart'). Note: 'slicer' is defined here for the FloatingObjectKind union, but the full SlicerConfig type is in contracts/src/slicers.ts because slicers have significant additional properties. ```typescript type FloatingObjectKind = | 'shape' | 'connector' | 'picture' | 'textbox' | 'chart' | 'camera' | 'equation' | 'smartart' | 'drawing' | 'oleObject' | 'formControl' | 'slicer' ``` ## FloatingObjectMutationReceipt Receipt for a floating object creation or update mutation. ```typescript type FloatingObjectMutationReceipt = { domain: 'floatingObject'; action: 'create' | 'update'; id: string; object: FloatingObject; bounds: ObjectBounds; } ``` ## FloatingObjectType Type discriminator for floating objects (API layer). Superset of FloatingObjectKind (12 storage-layer variants) + 'wordart' (API-only ergonomic alias). WordArt objects are stored as Textbox with word_art config; this type lets consumers reference them directly. ```typescript type FloatingObjectType = | 'shape' | 'connector' | 'picture' | 'textbox' | 'chart' | 'camera' | 'equation' | 'smartart' | 'drawing' | 'oleObject' | 'formControl' | 'slicer' | 'wordart' ``` ## FormControl Union of all implemented form control types. Currently: Checkbox, Button, ComboBox Future: RadioButton, Slider, Spinner ```typescript type FormControl = CheckboxControl | ButtonControl | ComboBoxControl ``` ## FormatChangeResult Result of a format set/setRange operation. ```typescript type FormatChangeResult = { /** Number of cells whose formatting was changed */ cellCount: number; } ``` ## FormatEntry Entry for batch format-values call. ```typescript type FormatEntry = { /** Cell value descriptor */ value: { type: string; value?: unknown }; /** Number format code (e.g., "#,##0.00") */ formatCode: string; } ``` ## FormulaA1 A formula string WITH the `=` prefix: `"=SUM(A1:B10)"`, `"=A1+A2"`. This is the display/input format used at the Rust-TS boundary and in the UI. ```typescript type FormulaA1 = string & { readonly [formulaA1Brand]: true } ``` ## FractionNode Fraction - Numerator over denominator IMPORTANT: Uses `fractionType` field (NOT `type_`) Maps to OMML ```typescript type FractionNode = { type: 'f'; /** Fraction type: bar (stacked), skw (skewed), lin (linear), noBar (no bar) */ fractionType: 'bar' | 'skw' | 'lin' | 'noBar'; /** Numerator */ num: MathNode[]; /** Denominator */ den: MathNode[]; } ``` ## FunctionArgument ```typescript type FunctionArgument = { name: string; description: string; type: FunctionArgumentType; optional: boolean; repeating?: boolean; } ``` ## FunctionArgumentType Function Registry -- Lightweight metadata registry for Excel functions. Types remain here in contracts. Migrated from @mog/calculator. ```typescript type FunctionArgumentType = | 'number' | 'text' | 'logical' | 'reference' | 'array' | 'any' | 'date' ``` ## FunctionInfo Information about a spreadsheet function (e.g., SUM, VLOOKUP). ```typescript type FunctionInfo = { /** Function name (uppercase, e.g., "SUM") */ name: string; /** Description of what the function does */ description: string; /** Function category (e.g., "Math & Trig", "Lookup & Reference") */ category: string; /** Syntax example (e.g., "SUM(number1, [number2], ...)") */ syntax: string; /** Usage examples */ examples?: string[]; /** Function argument metadata for IntelliSense/argument hints */ arguments?: import('../utils/function-registry').FunctionArgument[]; } ``` ## FunctionNode Function - Named function like sin, cos, lim ```typescript type FunctionNode = { type: 'func'; /** Function name */ fName: MathNode[]; /** Argument */ e: MathNode[]; } ``` ## GlowEffect Glow effect configuration. ```typescript type GlowEffect = { /** Glow color (CSS color string) */ color: string; /** Glow radius in pixels */ radius: number; /** Opacity (0 = transparent, 1 = opaque) */ opacity: number; } ``` ## GoalSeekResult Result of a goal seek operation. ```typescript type GoalSeekResult = { /** Whether a solution was found */ found: boolean; /** The value found for the changing cell (if found) */ value?: number; /** Number of iterations performed */ iterations?: number; } ``` ## GradientFill Gradient fill configuration. Excel supports two gradient types: - linear: Color transitions along a line at a specified angle - path: Color transitions radially from a center point Gradients require at least 2 stops (start and end colors). ```typescript type GradientFill = { /** Type of gradient. - 'linear': Straight line gradient at specified degree - 'path': Radial/rectangular gradient from center point */ type: 'linear' | 'path'; /** Angle of linear gradient in degrees (0-359). 0 = left-to-right, 90 = bottom-to-top, etc. Only used when type is 'linear'. */ degree?: number; /** Center point for path gradients (0.0 to 1.0 for each axis). { left: 0.5, top: 0.5 } = center of cell. Only used when type is 'path'. */ center?: { left: number; top: number; }; /** Gradient color stops. Must have at least 2 stops. Stops should be ordered by position. */ stops: GradientStop[]; } ``` ## GradientStop GradientStop — Core contracts layer. Maps to CT_GradientStop (dml-main.xsd:1539) with position + color for cell formatting. ```typescript type GradientStop = { /** Position along the gradient (0.0 to 1.0). 0.0 = start of gradient, 1.0 = end of gradient. */ position: number; /** Color at this position. Can be absolute hex or theme reference. */ color: string; } ``` ## GroupCharNode Group Character - Grouping symbol (underbrace, overbrace) ```typescript type GroupCharNode = { type: 'groupChr'; /** Character (default is underbrace) */ chr?: string; /** Position: 'top' or 'bot' */ pos?: 'top' | 'bot'; /** Vertical justification */ vertJc?: 'top' | 'bot'; /** Content */ e: MathNode[]; } ``` ## GroupState State of all row/column groups on a sheet. ```typescript type GroupState = { /** All row groups */ rowGroups: any[]; /** All column groups */ columnGroups: any[]; /** Maximum outline level for rows */ maxRowLevel: number; /** Maximum outline level for columns */ maxColLevel: number; } ``` ## HeaderFooter Header/footer configuration (OOXML CT_HeaderFooter). ```typescript type HeaderFooter = { oddHeader: string | null; oddFooter: string | null; evenHeader: string | null; evenFooter: string | null; firstHeader: string | null; firstFooter: string | null; differentOddEven: boolean; differentFirst: boolean; scaleWithDoc: boolean; alignWithMargins: boolean; } ``` ## HeaderFooterImageInfo Header/footer image metadata. Stores image references (path or data-URL), not binary blobs. ```typescript type HeaderFooterImageInfo = { position: HfImagePosition; /** Image source — resolved path for imported, or data-URL for API-created */ src: string; /** Descriptive title */ title: string; /** Width in points */ widthPt: number; /** Height in points */ heightPt: number; } ``` ## HeatmapConfig Heatmap configuration ```typescript type HeatmapConfig = { colorScale?: string[]; showLabels?: boolean; minColor?: string; maxColor?: string; } ``` ## HfImagePosition Position of a header/footer image in the page layout. ```typescript type HfImagePosition = | 'leftHeader' | 'centerHeader' | 'rightHeader' | 'leftFooter' | 'centerFooter' | 'rightFooter' ``` ## HistogramConfig Histogram configuration ```typescript type HistogramConfig = { binCount?: number; binWidth?: number; cumulative?: boolean; } ``` ## IDisposable Disposable — Handle-based lifecycle management. Three primitives for consumer-scoped stateful APIs: 1. `IDisposable` — interface for any resource with explicit lifecycle. 2. `DisposableBase` — abstract class with idempotent dispose + Symbol.dispose. 3. `DisposableStore` — tracks child disposables; disposing the store disposes all children. Supports TC39 Explicit Resource Management (TS 5.2+): using region = wb.viewport.createRegion(sheetId, bounds); // auto-disposed at block exit @see plans/archive/kernel/round-5/02-HANDLE-BASED-API-PATTERN.md ```typescript type IDisposable = { dispose(): void;; [Symbol.dispose](): void;; } ``` ## IObjectBoundsReader ```typescript type IObjectBoundsReader = { /** Pixel bounds in document space. Null if object not in scene graph. */ getBounds(objectId: string): ObjectBounds | null;; /** Union bounds of all objects in a group. */ getGroupBounds(groupId: string): ObjectBounds | null;; /** Bounds for multiple objects. Skips objects not in scene graph. */ getBoundsMany(objectIds: readonly string[]): Map;; } ``` ## IdentifiedCellData Cell data enriched with stable CellId identity. Used by operations that need to reference cells by identity (not position), such as find-replace, clipboard, and cell relocation. The CellId is a CRDT-safe identifier that survives row/column insert/delete operations. Unlike `CellData` (position-implied), `IdentifiedCellData` includes explicit position and identity for flat iteration over non-empty cells in a range. ```typescript type IdentifiedCellData = { /** Stable cell identity (CRDT-safe, survives structural changes). */ cellId: string; /** Row index (0-based). */ row: number; /** Column index (0-based). */ col: number; /** The computed cell value (null for empty cells). */ value: CellValue | null; /** Formula text (e.g., "=A1+B1") when the cell contains a formula. */ formulaText?: string; /** Pre-formatted display string (e.g., "$1,234.56" for a currency-formatted number). */ displayString: string; } ``` ## IdentityRangeRef Reference to a range by corner cell identities (for formula storage). Ranges are defined by their corner cells. When rows/columns are inserted between the corners, the range automatically expands because the corner cells' positions change. ```typescript type IdentityRangeRef = { type: 'range'; /** Start cell (top-left corner) identity */ startId: CellId; /** End cell (bottom-right corner) identity */ endId: CellId; /** Absolute flags for start cell display */ startRowAbsolute: boolean; startColAbsolute: boolean; /** Absolute flags for end cell display */ endRowAbsolute: boolean; endColAbsolute: boolean; } ``` ## ImageColorType Image color transform type. ```typescript type ImageColorType = 'automatic' | 'grayScale' | 'blackAndWhite' | 'watermark' ``` ## ImageExportFormat Image export format options ```typescript type ImageExportFormat = 'png' | 'jpeg' | 'svg' ``` ## ImageExportOptions Image export options ```typescript type ImageExportOptions = { /** Image format (default: 'png') */ format?: ImageExportFormat; /** Pixel ratio for higher resolution (default: 2) */ pixelRatio?: number; /** Background color (default: '#ffffff') */ backgroundColor?: string; /** Target width in pixels (default: 640) */ width?: number; /** Target height in pixels (default: 480) */ height?: number; /** JPEG quality 0-1 (default: 0.92, only used when format is 'jpeg') */ quality?: number; /** Fitting mode (default: 'fill') */ fittingMode?: ImageFittingMode; } ``` ## ImageFittingMode Image fitting mode for exports: - 'fill': scale the chart to fill the entire target canvas (may crop) - 'fit': scale the chart to fit within the target dimensions (preserves aspect ratio) - 'fitAndCenter': same as 'fit' but centers the chart within the target canvas ```typescript type ImageFittingMode = 'fill' | 'fit' | 'fitAndCenter' ``` ## InkPoint A single point in a stroke with pressure and tilt support. Coordinates are in local drawing object space (pixels relative to drawing object bounds). Transform to sheet coordinates happens at render time. Pressure and tilt are normalized to [0, 1] ranges for consistent rendering regardless of input device. ```typescript type InkPoint = { /** X coordinate in drawing object local space (pixels) */ x: number; /** Y coordinate in drawing object local space (pixels) */ y: number; /** Pen pressure normalized to [0, 1]. - 0 = minimum pressure (or mouse with no pressure support) - 1 = maximum pressure - undefined = no pressure data (mouse, touch without pressure) Used for variable stroke width rendering. */ pressure?: number; /** Tilt angle in radians [0, PI/2]. - 0 = perpendicular to surface - PI/2 = parallel to surface - undefined = no tilt data Used for brush shape and texture effects. */ tilt?: number; /** Timestamp when this point was captured (ms since stroke start). Used for velocity calculations and replay animations. - undefined = no timing data */ timestamp?: number; } ``` ## InkStroke A complete ink stroke with all rendering properties. Strokes are immutable once created - modifications create new strokes with the same ID (for CRDT merge semantics). ```typescript type InkStroke = { /** Unique identifier for this stroke */ id: StrokeId; /** Ordered array of points composing the stroke */ points: InkPoint[]; /** Tool used to create this stroke */ tool: InkTool; /** Stroke color in CSS color format (hex, rgb, hsl) */ color: string; /** Base stroke width in pixels. Actual rendered width may vary with pressure. */ width: number; /** Stroke opacity [0, 1]. - 0 = fully transparent - 1 = fully opaque Different tools have different default opacities (e.g., highlighter defaults to ~0.4). */ opacity: number; /** User ID who created this stroke. Used for: - Collaboration: Show who drew what - Permissions: Only creator can modify their strokes - Undo: Per-user undo stacks */ createdBy: string; /** Timestamp when stroke was created (Unix ms). Used for ordering and undo/redo. */ createdAt: number; /** Whether this stroke is currently selected. This is a transient UI state, not persisted. */ selected?: boolean; } ``` ## InkTool Available ink tools for drawing. Each tool has different rendering characteristics: - pen: Solid line, pressure-sensitive width - pencil: Textured line, slight transparency - highlighter: Wide, semi-transparent, blends with background - marker: Bold, opaque, consistent width - brush: Artistic brush effects, pressure-sensitive - eraser: Removes strokes (not a drawing tool, but handled similarly) ```typescript type InkTool = 'pen' | 'pencil' | 'highlighter' | 'marker' | 'brush' | 'eraser' ``` ## InkToolSettings Default settings for a specific ink tool. Each tool can have different defaults for width, opacity, etc. These are used when creating new strokes. ```typescript type InkToolSettings = { /** Default stroke width in pixels */ width: number; /** Default opacity [0, 1] */ opacity: number; /** Default color (CSS color string) */ color: string; /** Whether this tool supports pressure sensitivity. Some tools (e.g., highlighter) ignore pressure. */ supportsPressure: boolean; } ``` ## InkToolState Current tool state for a drawing session. Tracks the active tool and its settings. ```typescript type InkToolState = { /** Currently selected tool */ activeTool: InkTool; /** Per-tool settings (user preferences) */ toolSettings: Record; } ``` ## InsertCellsReceipt Receipt for an insertCellsWithShift mutation. ```typescript type InsertCellsReceipt = { kind: 'insertCells'; sheetId: string; range: { startRow: number; startCol: number; endRow: number; endCol: number }; direction: 'right' | 'down'; } ``` ## InsertColumnsReceipt Receipt for an insertColumns mutation. ```typescript type InsertColumnsReceipt = { kind: 'insertColumns'; sheetId: string; insertedAt: number; count: number; } ``` ## InsertRowsReceipt Receipt for an insertRows mutation. ```typescript type InsertRowsReceipt = { kind: 'insertRows'; sheetId: string; insertedAt: number; count: number; } ``` ## InsertWorksheetOptions Options for insertWorksheetsFromBase64 — controls which sheets to import and where to place them in the workbook. ```typescript type InsertWorksheetOptions = { /** Which sheets to import by name. Default: all sheets. */ sheetNamesToInsert?: string[]; /** Where to insert relative to existing sheets. Default: 'end'. */ positionType?: 'before' | 'after' | 'beginning' | 'end'; /** Sheet name to position relative to (required for 'before'/'after'). */ relativeTo?: string; } ``` ## Issue ```typescript type Issue = { id: string; title: string; description?: string; status: 'open' | 'in_progress' | 'review' | 'done' | 'closed'; priority: 'low' | 'medium' | 'high' | 'critical'; type: 'bug' | 'feature' | 'task' | 'improvement'; assignee?: { id: string; name: string; email: string }; labels: string[]; createdAt: string; updatedAt: string; closedAt?: string; } ``` ## LayoutForm ```typescript type LayoutForm = 'compact' | 'outline' | 'tabular' ``` ## LegendConfig Legend configuration (matches LegendData wire type) ```typescript type LegendConfig = { show: boolean; position: string; visible: boolean; overlay?: boolean; font?: ChartFont; format?: ChartFormat; entries?: LegendEntryConfig[]; /** Custom legend X position (0-1, fraction of chart area) when position is 'custom' */ customX?: number; /** Custom legend Y position (0-1, fraction of chart area) when position is 'custom' */ customY?: number; shadow?: ChartShadow; /** Show drop shadow on legend box. */ showShadow?: boolean; /** Legend height in points (read-only, populated from render engine). */ height?: number; /** Legend width in points (read-only, populated from render engine). */ width?: number; /** Legend left position in points (read-only, populated from render engine). */ left?: number; /** Legend top position in points (read-only, populated from render engine). */ top?: number; } ``` ## LegendEntryConfig Legend entry override (show/hide individual entries). ```typescript type LegendEntryConfig = { idx: number; delete?: boolean; format?: ChartFormat; /** Whether this legend entry is visible */ visible?: boolean; } ``` ## LimLowNode Lower Limit - Base with limit below ```typescript type LimLowNode = { type: 'limLow'; /** Base expression */ e: MathNode[]; /** Limit expression */ lim: MathNode[]; } ``` ## LimUppNode Upper Limit - Base with limit above ```typescript type LimUppNode = { type: 'limUpp'; /** Base expression */ e: MathNode[]; /** Limit expression */ lim: MathNode[]; } ``` ## LineDash Detailed line dash pattern. Matches OfficeJS ShapeLineFormat.dashStyle and Rust `LineDash` enum. Uses the same 11 variants as OOXML ST_PresetLineDashVal. ```typescript type LineDash = | 'solid' | 'dot' | 'dash' | 'dashDot' | 'lgDash' | 'lgDashDot' | 'lgDashDotDot' | 'sysDash' | 'sysDot' | 'sysDashDot' | 'sysDashDotDot' ``` ## LineEndSize Arrowhead/line-end size for connector endpoints. Maps to ST_LineEndLength/ST_LineEndWidth (ECMA-376, dml-main.xsd). Canonical source; re-exported by drawing-canvas scene/types. ```typescript type LineEndSize = 'sm' | 'med' | 'lg' ``` ## LineEndType Arrowhead/line-end type for connector endpoints. Maps to ST_LineEndType (ECMA-376, dml-main.xsd). Canonical source; re-exported by drawing-canvas scene/types. ```typescript type LineEndType = 'none' | 'triangle' | 'stealth' | 'diamond' | 'oval' | 'arrow' ``` ## LineSubType ```typescript type LineSubType = | 'straight' | 'smooth' | 'stepped' | 'stacked' | 'percentStacked' | 'markers' | 'markersStacked' | 'markersPercentStacked' ``` ## MarkerStyle Marker style for scatter/line chart markers. ```typescript type MarkerStyle = | 'circle' | 'dash' | 'diamond' | 'dot' | 'none' | 'picture' | 'plus' | 'square' | 'star' | 'triangle' | 'x' | 'auto' ``` ## MathFont Math font for equation rendering Excel uses Cambria Math by default ```typescript type MathFont = | 'Cambria Math' // Default Excel math font | 'Latin Modern' // TeX-style | 'STIX Two Math' // Scientific publishing | 'XITS Math' // Based on STIX | string ``` ## MathNode Any math AST node ```typescript type MathNode = | OMath | OMathPara | AccentNode | BarNode | BoxNode | BorderBoxNode | DelimiterNode | EqArrayNode | FractionNode | FunctionNode | GroupCharNode | LimLowNode | LimUppNode | MatrixNode | NaryNode | PhantomNode | RadicalNode | PreScriptNode | SubscriptNode | SubSupNode | SuperscriptNode | MathRun ``` ## MathRun Text Run - Actual text/symbol content ```typescript type MathRun = { type: 'r'; /** Text content */ text: string; /** Run properties */ rPr?: MathRunProperties; } ``` ## MatrixNode Matrix - Mathematical matrix ```typescript type MatrixNode = { type: 'm'; /** Base justification */ baseJc?: 'top' | 'center' | 'bottom'; /** Hide placeholder */ plcHide?: boolean; /** Row spacing rule */ rSpRule?: 0 | 1 | 2 | 3 | 4; /** Column gap rule */ cGpRule?: 0 | 1 | 2 | 3 | 4; /** Row spacing */ rSp?: number; /** Column spacing */ cSp?: number; /** Column gap */ cGp?: number; /** Column properties */ mcs?: Array<{ count?: number; mcJc?: 'left' | 'center' | 'right' }>; /** Matrix rows - each row is an array of cells, each cell is an array of nodes */ mr: MathNode[][][]; } ``` ## MergeReceipt Receipt for a merge mutation. ```typescript type MergeReceipt = { kind: 'merge'; range: string; } ``` ## MergedRegion Information about a merged cell region. ```typescript type MergedRegion = { /** The merged range in A1 notation (e.g., "A1:B2") */ range: string; /** Start row (0-based) */ startRow: number; /** Start column (0-based) */ startCol: number; /** End row (0-based, inclusive) */ endRow: number; /** End column (0-based, inclusive) */ endCol: number; } ``` ## NameAddReceipt Receipt for a named range add mutation. ```typescript type NameAddReceipt = { kind: 'nameAdd'; name: string; reference: string; } ``` ## NameRemoveReceipt Receipt for a named range remove mutation. ```typescript type NameRemoveReceipt = { kind: 'nameRemove'; name: string; } ``` ## NamedItemType OfficeJS-compatible type classification for a named item's value. @see https://learn.microsoft.com/en-us/javascript/api/excel/excel.nameditemtype ```typescript type NamedItemType = | 'String' | 'Integer' | 'Double' | 'Boolean' | 'Range' | 'Error' | 'Array' ``` ## NamedRangeInfo Information about a defined name / named range. ```typescript type NamedRangeInfo = { /** The defined name */ name: string; /** The reference formula (e.g., "Sheet1!$A$1:$B$10") */ reference: string; /** Scope: undefined or sheet name (undefined = workbook scope) */ scope?: string; /** Optional descriptive comment */ comment?: string; /** Whether the name is visible in Name Manager. Hidden names are typically system-generated. */ visible?: boolean; } ``` ## NamedRangeReference Parsed reference for a named range that refers to a simple sheet!range. ```typescript type NamedRangeReference = { /** The sheet name (e.g., "Sheet1") */ sheetName: string; /** The range portion (e.g., "$A$1:$B$10") */ range: string; } ``` ## NamedRangeUpdateOptions Options for updating a named range. ```typescript type NamedRangeUpdateOptions = { /** New name (for renaming) */ name?: string; /** New reference (A1-style) */ reference?: string; /** New comment */ comment?: string; /** Whether the name is visible in Name Manager */ visible?: boolean; } ``` ## NamedSlicerStyle A named slicer style stored in the workbook (custom or built-in). ```typescript type NamedSlicerStyle = { name: string; readOnly: boolean; style: SlicerCustomStyle; } ``` ## NaryNode N-ary Operator - Summation, integral, product, etc. ```typescript type NaryNode = { type: 'nary'; /** Operator character (sum, integral, product, etc.) */ chr?: string; /** Limit location: 'undOvr' (above/below) or 'subSup' (sub/superscript) */ limLoc?: 'undOvr' | 'subSup'; /** Grow with content */ grow?: boolean; /** Hide subscript */ subHide?: boolean; /** Hide superscript */ supHide?: boolean; /** Subscript (lower limit) */ sub: MathNode[]; /** Superscript (upper limit) */ sup: MathNode[]; /** Content (integrand, summand) */ e: MathNode[]; } ``` ## NegativeNumberPattern Negative number pattern. Determines how negative numbers are displayed (outside of currency context). 0 = (n) - parentheses 1 = -n - leading minus (most common) 2 = - n - leading minus with space 3 = n- - trailing minus 4 = n - - trailing minus with space ```typescript type NegativeNumberPattern = 0 | 1 | 2 | 3 | 4 ``` ## NodeId Unique identifier for a SmartArt node. This is a branded type for type safety - prevents accidental use of arbitrary strings as NodeIds. Uses UUID v4 format. ```typescript type NodeId = string & { readonly __brand: 'SmartArtNodeId' } ``` ## NodeMoveDirection ```typescript type NodeMoveDirection = 'promote' | 'demote' | 'move-up' | 'move-down' ``` ## NodePosition ```typescript type NodePosition = 'before' | 'after' | 'above' | 'below' | 'child' ``` ## Note A cell note (simple, single string per cell). API-only type (no Rust equivalent). ```typescript type Note = { content: string; author: string; cellAddress: string; /** Visible state of the note shape. */ visible?: boolean; /** Note callout box height in points. */ height?: number; /** Note callout box width in points. */ width?: number; } ``` ## Notification A single notification ```typescript type Notification = { /** Unique ID for the notification */ id: string; /** Notification type/severity */ type: NotificationType; /** Short title (optional) */ title?: string; /** Main message content */ message: string; /** Timestamp when created */ timestamp: number; /** Auto-dismiss after this many ms (null = manual dismiss only) */ duration: number | null; /** Whether the notification can be dismissed */ dismissible: boolean; /** Optional action button */ action?: { label: string; onClick: () => void; }; } ``` ## NotificationOptions Options for system notifications. ```typescript type NotificationOptions = { /** Notification title. */ title: string; /** Notification body text. */ body?: string; /** Icon to display (URL or path). */ icon?: string; } ``` ## NotificationType Notification severity levels ```typescript type NotificationType = 'info' | 'success' | 'warning' | 'error' ``` ## NumberFormatCategory Number format category classification. Matches the FormatType enum from Rust compute-formats. ```typescript enum NumberFormatCategory { General = 'General', Number = 'Number', Currency = 'Currency', Accounting = 'Accounting', Date = 'Date', Time = 'Time', Percentage = 'Percentage', Fraction = 'Fraction', Scientific = 'Scientific', Text = 'Text', Special = 'Special', Custom = 'Custom', } ``` ## NumberFormatType ```typescript type NumberFormatType = | 'general' | 'number' | 'currency' | 'accounting' | 'date' | 'time' | 'percentage' | 'fraction' | 'scientific' | 'text' | 'special' | 'custom' ``` ## OMath Root math container - ```typescript type OMath = { type: 'oMath'; children: MathNode[]; } ``` ## OMathPara Math paragraph - ```typescript type OMathPara = { type: 'oMathPara'; justification?: 'left' | 'right' | 'center' | 'centerGroup'; equations: OMath[]; } ``` ## ObjectAnchorType How the object anchors to the sheet. Determines behavior when rows/columns are resized. ```typescript type ObjectAnchorType = | 'twoCell' // Anchored to two cells (moves and resizes with cells) | 'oneCell' // Anchored to one cell (moves but doesn't resize) | 'absolute' ``` ## ObjectBorder Border style for floating objects. ```typescript type ObjectBorder = { /** Border line style */ style: 'none' | 'solid' | 'dashed' | 'dotted'; /** Border color (CSS color string) */ color: string; /** Border width in pixels */ width: number; } ``` ## ObjectBounds Computed bounding box for a floating object in pixel coordinates. ```typescript type ObjectBounds = { x: number; y: number; width: number; height: number; rotation: number; } ``` ## ObjectFill Fill configuration for shapes and text boxes. Matches the Rust `ObjectFill` struct in `domain-types`. ```typescript type ObjectFill = { /** Fill type */ type: FillType; /** Solid fill color (CSS color string) */ color?: string; /** Gradient configuration */ gradient?: GradientFill; /** Fill transparency (0 = opaque, 1 = fully transparent). Maps to OfficeJS Shape.fill.transparency. */ transparency?: number; /** Pattern fill configuration (for type='pattern') */ pattern?: PatternFill; /** Picture/texture fill configuration (for type='pictureAndTexture') */ blip?: BlipFill; } ``` ## ObjectPosition Object position configuration. Supports cell-anchored and absolute positioning modes. ```typescript type ObjectPosition = { /** Anchor type determines how object moves/resizes with cells */ anchorType: ObjectAnchorType; /** Start anchor (top-left corner) - required for all anchor types */ from: CellAnchor; /** End anchor (bottom-right corner) - only for twoCell anchor */ to?: CellAnchor; /** Absolute X position in pixels (only for absolute anchor) */ x?: number; /** Absolute Y position in pixels (only for absolute anchor) */ y?: number; /** Width in pixels (for oneCell and absolute anchors) */ width?: number; /** Height in pixels (for oneCell and absolute anchors) */ height?: number; /** Rotation angle in degrees (0-360) */ rotation?: number; /** Flip horizontally (mirror along vertical axis) */ flipH?: boolean; /** Flip vertically (mirror along horizontal axis) */ flipV?: boolean; } ``` ## OleObjectHandle OLE object handle — hosting ops only. Parse-only type, no content mutations. ```typescript type OleObjectHandle = { duplicate(offsetX?: number, offsetY?: number): Promise;; getData(): Promise;; } ``` ## OleObjectObject OLE (Object Linking and Embedding) floating object. Represents embedded or linked objects from other applications (e.g., Word documents, PDF files, Visio drawings). The object may have a preview image (PNG/JPEG) or display as an icon. EMF/WMF previews are not supported and will have a null previewImageSrc. Architecture Notes: - Preview image is extracted during OOXML parsing and stored as a blob URL - Linked objects reference external files (isLinked); embedded objects are self-contained - dvAspect determines whether the object renders as content or as an icon - progId identifies the source application (e.g., "Word.Document.12", "AcroExch.Document") ```typescript type OleObjectObject = { type: 'oleObject'; /** OLE ProgID identifying the source application (e.g., "Word.Document.12") */ progId: string; /** Display aspect: 'content' renders the object preview, 'icon' shows an application icon */ dvAspect: 'content' | 'icon'; /** Whether the object links to an external file */ isLinked: boolean; /** Whether the object data is embedded in the workbook */ isEmbedded: boolean; /** Blob URL for the preview image (PNG/JPEG), null for EMF/WMF or missing previews */ previewImageSrc: string | null; /** Descriptive text for accessibility */ altText: string; } ``` ## OperationWarning Non-fatal warning attached to an operation result. ```typescript type OperationWarning = { /** Machine-readable warning code */ code: string; /** Human-readable description */ message: string; /** Optional structured context for programmatic handling */ context?: Record; } ``` ## OriginalCellValue A saved original cell value from before scenario application. ```typescript type OriginalCellValue = { sheetId: string; cellId: string; value: string | number | boolean | null; /** Original formula, if the cell had one. */ formula?: string; } ``` ## OuterShadowEffect Outer shadow effect (shadow cast outside the text). Creates a shadow behind the text that appears to be cast by a light source. The shadow can be positioned, blurred, scaled, and skewed for various effects including simple drop shadows and perspective shadows. @example // Simple drop shadow (bottom-right) const shadow: OuterShadowEffect = { blurRadius: 50800, // 4pt blur distance: 38100, // 3pt offset direction: 45, // 45 degrees (down-right) color: '#000000', opacity: 0.4 }; @see ECMA-376 Part 1, Section 20.1.8.52 (outerShdw) ```typescript type OuterShadowEffect = { /** Blur radius in EMUs (English Metric Units). Higher values create a softer, more diffuse shadow. 1 point = 12700 EMUs. @example 50800 // 4pt blur */ blurRadius: number; /** Shadow distance from text in EMUs. How far the shadow is offset from the text. @example 38100 // 3pt offset */ distance: number; /** Shadow direction in degrees. Angle measured clockwise from the positive x-axis. - 0 = right - 90 = down - 180 = left - 270 = up */ direction: number; /** Shadow color (CSS color string). Typically black or dark gray for standard shadows. @example '#000000' */ color: string; /** Shadow opacity (0-1). 0 = fully transparent, 1 = fully opaque. Typical values range from 0.3 to 0.6 for natural-looking shadows. */ opacity: number; /** Horizontal scale factor for perspective shadows. Values less than 1.0 compress the shadow horizontally. Values greater than 1.0 stretch the shadow horizontally. @default 1.0 (no scaling) */ scaleX?: number; /** Vertical scale factor for perspective shadows. Values less than 1.0 compress the shadow vertically. Values greater than 1.0 stretch the shadow vertically. @default 1.0 (no scaling) */ scaleY?: number; /** Skew angle X in degrees (for perspective shadows). Shears the shadow horizontally. @default 0 (no skew) */ skewX?: number; /** Skew angle Y in degrees (for perspective shadows). Shears the shadow vertically. @default 0 (no skew) */ skewY?: number; /** Shadow alignment relative to the text bounding box. Determines the anchor point for shadow positioning. @default 'b' (bottom) */ alignment?: ShadowAlignment; /** Whether shadow rotates with text when text is rotated. If true, the shadow direction is relative to the text. If false, the shadow direction is absolute (relative to the page). @default true */ rotateWithShape?: boolean; } ``` ## OutlineSettings Outline display settings for grouping. ```typescript type OutlineSettings = { /** Whether outline symbols (+/-) are visible */ showOutlineSymbols: boolean; /** Whether outline level buttons (1,2,3...) are visible */ showOutlineLevelButtons: boolean; /** Whether summary rows appear below detail rows */ summaryRowsBelow: boolean; /** Whether summary columns appear to the right of detail */ summaryColumnsRight: boolean; } ``` ## PageMargins Page margins in inches. Full OOXML representation including header/footer margins. ```typescript type PageMargins = { top: number; bottom: number; left: number; right: number; header: number; footer: number; } ``` ## Path A geometric path composed of segments. ```typescript type Path = { segments: PathSegment[]; closed: boolean; subPaths?: SubPath[]; } ``` ## PathSegment A single segment in a path. ```typescript type PathSegment = MoveTo | LineTo | CurveTo | QuadraticTo | ClosePath ``` ## PatternFill Pattern fill definition. ```typescript type PatternFill = { preset: string; foregroundColor?: string; backgroundColor?: string; } ``` ## PatternType Excel pattern fill types. Excel supports 18 pattern types for cell backgrounds. These patterns combine a foreground color (the pattern) with a background color. Pattern visualization (8x8 pixels): - none: No fill (transparent) - solid: Solid fill (fgColor only) - darkGray/mediumGray/lightGray/gray125/gray0625: Dot density patterns - darkHorizontal/lightHorizontal: Horizontal stripe patterns - darkVertical/lightVertical: Vertical stripe patterns - darkDown/lightDown: Diagonal stripes (top-left to bottom-right) - darkUp/lightUp: Diagonal stripes (bottom-left to top-right) - darkGrid/lightGrid: Grid patterns (horizontal + vertical) - darkTrellis/lightTrellis: Cross-hatch patterns (both diagonals) ```typescript type PatternType = | 'none' | 'solid' | 'darkGray' | 'mediumGray' | 'lightGray' | 'gray125' | 'gray0625' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis' ``` ## PercentNegativePattern Percent negative pattern. 0 = -n % 1 = -n% 2 = -%n 3 = %-n 4 = %n- 5 = n-% 6 = n%- 7 = -% n 8 = n %- 9 = % n- 10 = % -n 11 = n- % ```typescript type PercentNegativePattern = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 ``` ## PercentPositivePattern Percent positive pattern. 0 = n % - number, space, percent 1 = n% - number, percent (most common) 2 = %n - percent, number 3 = % n - percent, space, number ```typescript type PercentPositivePattern = 0 | 1 | 2 | 3 ``` ## PhantomNode Phantom - Invisible element for spacing ```typescript type PhantomNode = { type: 'phant'; /** Show content (false = invisible) */ show?: boolean; /** Zero width */ zeroWid?: boolean; /** Zero ascent */ zeroAsc?: boolean; /** Zero descent */ zeroDesc?: boolean; /** Transparent (show but don't contribute to size) */ transp?: boolean; /** Content */ e: MathNode[]; } ``` ## PictureAdjustments Image adjustment settings. Values mirror Excel's picture format options. ```typescript type PictureAdjustments = { /** Brightness adjustment (-100 to 100, 0 = normal) */ brightness?: number; /** Contrast adjustment (-100 to 100, 0 = normal) */ contrast?: number; /** Transparency (0 = opaque, 100 = fully transparent) */ transparency?: number; } ``` ## PictureConfig Configuration for creating a new picture. ```typescript type PictureConfig = { /** Image source: data URL, blob URL, or file path. */ src: string; /** X position in pixels. */ x?: number; /** Y position in pixels. */ y?: number; /** Width in pixels (defaults to original image width). */ width?: number; /** Height in pixels (defaults to original image height). */ height?: number; /** Accessibility alt text. */ altText?: string; /** Display name. */ name?: string; /** Image crop settings (percentage from each edge). */ crop?: PictureCrop; /** Image adjustments (brightness, contrast, transparency). */ adjustments?: PictureAdjustments; } ``` ## PictureCrop Image crop settings. Values are percentages (0-100) of original dimension to crop from each side. ```typescript type PictureCrop = { /** Percentage to crop from top (0-100) */ top: number; /** Percentage to crop from right (0-100) */ right: number; /** Percentage to crop from bottom (0-100) */ bottom: number; /** Percentage to crop from left (0-100) */ left: number; } ``` ## PictureHandle ```typescript type PictureHandle = { update(props: Partial): Promise;; duplicate(offsetX?: number, offsetY?: number): Promise;; getData(): Promise;; } ``` ## PictureObject Picture/image floating object. Supports images from various sources with cropping and adjustments. ```typescript type PictureObject = { type: 'picture'; /** Image source (data URL, blob URL, or external URL) */ src: string; /** Original image width in pixels (before scaling) */ originalWidth: number; /** Original image height in pixels (before scaling) */ originalHeight: number; /** Crop settings (percentage-based) */ crop?: PictureCrop; /** Image adjustments (brightness, contrast, transparency) */ adjustments?: PictureAdjustments; /** Border around the image */ border?: ObjectBorder; /** Image color transform type */ colorType?: ImageColorType; } ``` ## PieSliceConfig Pie/doughnut slice configuration (matches PieSliceData wire type) ```typescript type PieSliceConfig = { explosion?: number; explodedIndices?: number[]; explodeOffset?: number; /** Explode all slices simultaneously */ explodeAll?: boolean; } ``` ## PivotChartOptions Pivot chart display options (field button visibility). ```typescript type PivotChartOptions = { /** Show axis field buttons on the chart. */ showAxisFieldButtons?: boolean; /** Show legend field buttons on the chart. */ showLegendFieldButtons?: boolean; /** Show report filter field buttons on the chart. */ showReportFilterFieldButtons?: boolean; /** Show value field buttons on the chart. */ showValueFieldButtons?: boolean; } ``` ## PivotCreateConfig Input config for pivot creation — accepts either the simple ergonomic format (dataSource string + field name arrays) or the full wire format (sourceSheetName, sourceRange, fields[], placements[]). Simple format example: ```ts { name: "Sales", dataSource: "Sheet1!A1:D100", rowFields: ["Region"], columnFields: ["Year"], valueFields: [{ field: "Amount", aggregation: "sum" }] } ``` Full format example: ```ts { name: "Sales", sourceSheetName: "Sheet1", sourceRange: { startRow: 0, startCol: 0, endRow: 99, endCol: 3 }, outputSheetName: "Sheet1", outputLocation: { row: 0, col: 5 }, fields: [...], placements: [...], filters: [] } ``` ```typescript type PivotCreateConfig = | SimplePivotTableConfig | Omit ``` ## PivotExpansionState Tracks which headers are expanded/collapsed. Uses Record for TS ergonomics; Rust side uses HashSet with custom serde that accepts both array and map formats. ```typescript type PivotExpansionState = { expandedRows: Record; expandedColumns: Record; } ``` ## PivotFieldArea ```typescript type PivotFieldArea = 'row' | 'column' | 'value' | 'filter' ``` ## PivotFieldItems Collection of pivot items for a single field. Mirrors the Rust PivotFieldItems type. ```typescript type PivotFieldItems = { fieldId: string; fieldName: string; area: 'row' | 'column' | 'filter'; items: PivotItemInfo[]; } ``` ## PivotFilter ```typescript type PivotFilter = { fieldId: string; includeValues?: CellValue[]; excludeValues?: CellValue[]; condition?: PivotFilterConditionFlat; topBottom?: PivotTopBottomFilter; showItemsWithNoData?: boolean; } ``` ## PivotFilterConditionFlat ```typescript type PivotFilterConditionFlat = { operator: FilterOperator; value?: CellValue; value2?: CellValue; } ``` ## PivotItemInfo A PivotItem represents a unique value within a pivot field. Mirrors the Rust PivotItemInfo type. ```typescript type PivotItemInfo = { key: string; value: CellValue; fieldId: string; area: 'row' | 'column' | 'filter'; depth: number; isExpandable: boolean; isExpanded: boolean; isVisible: boolean; isSubtotal: boolean; isGrandTotal: boolean; childKeys?: string[]; parentKey?: string; } ``` ## PivotQueryRecord A single flat record from a pivot query result. ```typescript type PivotQueryRecord = { /** Dimension values keyed by field name (e.g., { Region: "North", Year: 2021 }) */ dimensions: Record; /** Aggregated values keyed by value field label (e.g., { "Sum of Amount": 110 }) */ values: Record; } ``` ## PivotQueryResult Result of queryPivot() — flat, agent-friendly records instead of hierarchy trees. ```typescript type PivotQueryResult = { /** Pivot table name */ pivotName: string; /** Row dimension field names */ rowFields: string[]; /** Column dimension field names */ columnFields: string[]; /** Value field labels */ valueFields: string[]; /** Flat records — one per data intersection, excluding subtotals and grand totals */ records: PivotQueryRecord[]; /** Total source row count */ sourceRowCount: number; } ``` ## PivotRefreshReceipt Receipt for a pivot table refresh mutation. ```typescript type PivotRefreshReceipt = { kind: 'pivotRefresh'; pivotId: string; } ``` ## PivotRemoveReceipt Receipt for a pivot table remove mutation. ```typescript type PivotRemoveReceipt = { kind: 'pivotRemove'; name: string; } ``` ## PivotTableConfig Configuration for creating or describing a pivot table. ```typescript type PivotTableConfig = { /** Pivot table name */ name: string; /** Source data range in A1 notation (e.g., "Sheet1!A1:E100") */ dataSource: string; /** Target sheet name (defaults to a new sheet) */ targetSheet?: string; /** Target cell address (defaults to A1) */ targetAddress?: string; /** Field names for the row area */ rowFields?: string[]; /** Field names for the column area */ columnFields?: string[]; /** Value field configurations */ valueFields?: PivotValueField[]; /** Field names for the filter area */ filterFields?: string[]; } ``` ## PivotTableHandle Handle for interacting with an existing pivot table. Returned by `worksheet.getPivotTable()`. Provides methods to query and modify the pivot table's field configuration. ```typescript type PivotTableHandle = { /** Unique pivot table identifier (readonly) */ id: string; /** Get the pivot table name */ getName(): string;; /** Get the current configuration including all fields */ getConfig(): PivotTableConfig;; /** Add a field to the row, column, or filter area */ addField(field: string, area: 'row' | 'column' | 'filter', position?: number): void;; /** Add a value field with aggregation */ addValueField(field: string, aggregation: PivotValueField['aggregation'], label?: string): void;; /** Remove a field by name */ removeField(fieldName: string): void;; /** Change the aggregation function of a value field */ changeAggregation(valueFieldLabel: string, newAggregation: PivotValueField['aggregation']): void;; /** Rename a value field's display label */ renameValueField(currentLabel: string, newLabel: string): void;; /** Refresh the pivot table from its data source */ refresh(): Promise;; /** Get all items for all non-value fields */ getAllItems(): Promise;; /** Set the "Show Values As" calculation for a value field. Pass null to clear. */ setShowValuesAs(valueFieldLabel: string, showValuesAs: ShowValuesAsConfig | null): void;; /** Set item visibility by value string -> boolean map */ setItemVisibility(fieldId: string, visibleItems: Record): void;; } ``` ## PivotTableInfo Summary information about an existing pivot table. ```typescript type PivotTableInfo = { /** Pivot table name */ name: string; /** Source data range (e.g., "Sheet1!A1:D100") */ dataSource: string; /** Range occupied by the pivot table content */ contentArea: string; /** Range occupied by filter dropdowns (if any) */ filterArea?: string; /** Output anchor location as A1 reference (e.g., "G1") */ location?: string; /** Row dimension field names */ rowFields?: string[]; /** Column dimension field names */ columnFields?: string[]; /** Value fields with aggregation info */ valueFields?: PivotValueField[]; /** Filter field names */ filterFields?: string[]; } ``` ## PivotTableLayout ```typescript type PivotTableLayout = { showRowGrandTotals?: boolean; showColumnGrandTotals?: boolean; layoutForm?: LayoutForm; subtotalLocation?: SubtotalLocation; repeatRowLabels?: boolean; insertBlankRowAfterItem?: boolean; showRowHeaders?: boolean; showColumnHeaders?: boolean; classicLayout?: boolean; grandTotalCaption?: string; rowHeaderCaption?: string; colHeaderCaption?: string; dataCaption?: string; gridDropZones?: boolean; errorCaption?: string; showError?: boolean; missingCaption?: string; showMissing?: boolean; } ``` ## PivotTableStyle ```typescript type PivotTableStyle = { styleName?: string; showRowStripes?: boolean; showColumnStripes?: boolean; } ``` ## PivotTableStyleInfo WorkbookPivotTableStyles -- Pivot table style presets and default style management. Provides access to the workbook-level default pivot table style preset. OfficeJS equivalent: `workbook.pivotTableStyles`. ```typescript type PivotTableStyleInfo = { name: string; isDefault: boolean; } ``` ## PivotTopBottomFilter ```typescript type PivotTopBottomFilter = { type: TopBottomType; n: number; by: TopBottomBy; valueFieldId?: string; } ``` ## PivotValueField A value field in a pivot table. ```typescript type PivotValueField = { /** Source field name */ field: string; /** Aggregation function */ aggregation: 'sum' | 'count' | 'average' | 'max' | 'min'; /** Custom label for the value field */ label?: string; } ``` ## PlotAreaConfig Plot area configuration ```typescript type PlotAreaConfig = { fill?: ChartFill; border?: ChartBorder; format?: ChartFormat; } ``` ## PointFormat Per-point formatting for individual data points (matches PointFormatData wire type) ```typescript type PointFormat = { idx: number; fill?: string; border?: ChartBorder; dataLabel?: DataLabelConfig; visualFormat?: ChartFormat; /** Readonly: computed value at this point (populated by get, ignored on set). */ value?: number | string; /** Per-point marker fill color. */ markerBackgroundColor?: ChartColor; /** Per-point marker border color. */ markerForegroundColor?: ChartColor; /** Per-point marker size (2-72 points). */ markerSize?: number; /** Per-point marker style. */ markerStyle?: MarkerStyle; } ``` ## PreScriptNode Pre-scripts - Subscript and superscript before base ```typescript type PreScriptNode = { type: 'sPre'; /** Subscript */ sub: MathNode[]; /** Superscript */ sup: MathNode[]; /** Base */ e: MathNode[]; } ``` ## PrintSettings Full print settings for a sheet, matching the Rust domain-types canonical type. Replaces the old lossy SheetPrintSettings. All fields are nullable where the underlying OOXML attribute is optional, using `null` to mean "not set / use default". Distinct from PrintOptions (runtime-only configuration in print-export). ```typescript type PrintSettings = { /** OOXML paper size code (1=Letter, 9=A4, etc.), null = not set */ paperSize: number | null; /** Page orientation, null = not set (defaults to portrait) */ orientation: string | null; /** Scale percentage (10-400), null = not set */ scale: number | null; /** Fit to N pages wide, null = not set */ fitToWidth: number | null; /** Fit to N pages tall, null = not set */ fitToHeight: number | null; /** Print cell gridlines */ gridlines: boolean; /** Print row/column headings */ headings: boolean; /** Center content horizontally on page */ hCentered: boolean; /** Center content vertically on page */ vCentered: boolean; /** Page margins in inches (with header/footer margins) */ margins: PageMargins | null; /** Header/footer configuration */ headerFooter: HeaderFooter | null; /** Print in black and white */ blackAndWhite: boolean; /** Draft quality */ draft: boolean; /** First page number override, null = auto */ firstPageNumber: number | null; /** Page order: "downThenOver" or "overThenDown", null = default */ pageOrder: string | null; /** Use printer defaults */ usePrinterDefaults: boolean | null; /** Horizontal DPI, null = not set */ horizontalDpi: number | null; /** Vertical DPI, null = not set */ verticalDpi: number | null; /** Relationship ID for printer settings binary, null = not set */ rId: string | null; /** Whether the sheet had printOptions element in OOXML */ hasPrintOptions: boolean; /** Whether the sheet had pageSetup element in OOXML */ hasPageSetup: boolean; /** Whether to use firstPageNumber (vs auto) */ useFirstPageNumber: boolean; /** How to print cell comments: "none" | "atEnd" | "asDisplayed", null = not set (defaults to none) */ printComments: string | null; /** How to print cell errors: "displayed" | "blank" | "dash" | "NA", null = not set (defaults to displayed) */ printErrors: string | null; } ``` ## ProtectionConfig Full protection configuration for a sheet. ```typescript type ProtectionConfig = { /** Whether the sheet is protected */ isProtected: boolean; /** Whether a password is set for protection (does not expose the hash) */ hasPasswordSet?: boolean; /** Allow selecting locked cells */ allowSelectLockedCells?: boolean; /** Allow selecting unlocked cells */ allowSelectUnlockedCells?: boolean; /** Allow formatting cells */ allowFormatCells?: boolean; /** Allow formatting columns */ allowFormatColumns?: boolean; /** Allow formatting rows */ allowFormatRows?: boolean; /** Allow inserting columns */ allowInsertColumns?: boolean; /** Allow inserting rows */ allowInsertRows?: boolean; /** Allow inserting hyperlinks */ allowInsertHyperlinks?: boolean; /** Allow deleting columns */ allowDeleteColumns?: boolean; /** Allow deleting rows */ allowDeleteRows?: boolean; /** Allow sorting */ allowSort?: boolean; /** Allow using auto-filter */ allowAutoFilter?: boolean; /** Allow using pivot tables */ allowPivotTables?: boolean; } ``` ## ProtectionOperation Valid operations for structural protection checks. ```typescript type ProtectionOperation = | 'insertRows' | 'insertColumns' | 'deleteRows' | 'deleteColumns' | 'formatCells' | 'formatRows' | 'formatColumns' | 'sort' | 'filter' | 'editObject' ``` ## ProtectionOptions Granular options for sheet protection. ```typescript type ProtectionOptions = { /** Allow selecting locked cells */ allowSelectLockedCells?: boolean; /** Allow selecting unlocked cells */ allowSelectUnlockedCells?: boolean; /** Allow formatting cells */ allowFormatCells?: boolean; /** Allow formatting columns */ allowFormatColumns?: boolean; /** Allow formatting rows */ allowFormatRows?: boolean; /** Allow inserting columns */ allowInsertColumns?: boolean; /** Allow inserting rows */ allowInsertRows?: boolean; /** Allow inserting hyperlinks */ allowInsertHyperlinks?: boolean; /** Allow deleting columns */ allowDeleteColumns?: boolean; /** Allow deleting rows */ allowDeleteRows?: boolean; /** Allow sorting */ allowSort?: boolean; /** Allow using auto-filter */ allowAutoFilter?: boolean; /** Allow using pivot tables */ allowPivotTables?: boolean; } ``` ## RadarSubType Radar chart sub-types ```typescript type RadarSubType = 'basic' | 'filled' ``` ## RadicalNode Radical - Square root or n-th root ```typescript type RadicalNode = { type: 'rad'; /** Hide degree (for square root) */ degHide?: boolean; /** Degree (n in n-th root) */ deg: MathNode[]; /** Radicand (content under root) */ e: MathNode[]; } ``` ## RangeValueType Per-cell value type classification. Matches OfficeJS Excel.RangeValueType enum values. ```typescript enum RangeValueType { Empty = 'Empty', String = 'String', Double = 'Double', Boolean = 'Boolean', Error = 'Error', } ``` ## RawCellData Complete raw cell data including formula, formatting, and metadata. Unlike `CellData` from core (which is the minimal read type), `RawCellData` includes all optional cell metadata useful for bulk reads and LLM presentation. ```typescript type RawCellData = { /** The computed cell value */ value: CellValue; /** The formula string with "=" prefix, if the cell contains a formula */ formula?: FormulaA1; /** Cell formatting */ format?: CellFormat; /** Cell borders */ borders?: CellBorders; /** Cell comment/note text */ comment?: string; /** Hyperlink URL */ hyperlink?: string; /** Whether the cell is part of a merged region */ isMerged?: boolean; /** The merged region this cell belongs to (A1 notation, e.g., "A1:B2") */ mergedRegion?: string; } ``` ## RecognitionResult Union type for all recognition results. ```typescript type RecognitionResult = RecognizedShape | RecognizedText ``` ## RecognizedShape A shape recognized from one or more ink strokes. Recognition converts freehand strokes into clean geometric shapes while preserving the original strokes for undo/redo. ```typescript type RecognizedShape = { /** Type discriminator */ type: 'shape'; /** Recognized shape type */ shapeType: RecognizedShapeType; /** Shape parameters (position, dimensions, etc.) */ params: ShapeParams; /** IDs of the source strokes that were recognized as this shape. Used for: - Undo: Can restore original strokes - Styling: Shape inherits color/width from source strokes */ sourceStrokeIds: StrokeId[]; /** Confidence score [0, 1] for the recognition */ confidence: number; /** Timestamp when recognition occurred */ recognizedAt: number; } ``` ## RecognizedText Text recognized from handwritten ink strokes. Handwriting recognition converts ink to text with multiple alternative interpretations ranked by confidence. ```typescript type RecognizedText = { /** Type discriminator */ type: 'text'; /** Primary recognized text (highest confidence) */ text: string; /** Alternative interpretations ranked by confidence. First element is same as `text` field. */ alternatives: TextAlternative[]; /** IDs of the source strokes that were recognized as this text. Used for undo and re-recognition. */ sourceStrokeIds: StrokeId[]; /** Bounding box for the recognized text */ bounds: { x: number; y: number; width: number; height: number; }; /** Timestamp when recognition occurred */ recognizedAt: number; } ``` ## RedoReceipt Receipt for a redo operation. ```typescript type RedoReceipt = { kind: 'redo'; success: boolean; } ``` ## ReflectionEffect Reflection effect configuration. ```typescript type ReflectionEffect = { /** Blur amount for the reflection */ blur: number; /** Distance from the shape to the reflection */ distance: number; /** Opacity of the reflection (0 = transparent, 1 = opaque) */ opacity: number; /** Size of the reflection relative to the shape (0-1) */ size: number; } ``` ## RemoveDuplicatesResult Result of a remove-duplicates operation. ```typescript type RemoveDuplicatesResult = { /** Number of duplicate rows removed */ removedCount: number; /** Number of unique rows remaining */ remainingCount: number; } ``` ## RenderScheduler Scheduler that bridges buffer writes to canvas layer invalidation. Implements the "Write = Invalidate" contract: when viewport buffers receive patches, they call these methods to mark the appropriate canvas layers dirty and wake the render loop. This is a contracts-level mirror of the canvas-engine RenderScheduler so that contracts does not depend on @mog/canvas-engine at runtime. ```typescript type RenderScheduler = { /** Cell value or format changed — mark cells layer dirty. */ markCellsDirty(cells?: { row: number; col: number }[]): void;; /** Row/col dimensions changed — mark cells + headers + selection dirty. */ markGeometryDirty(): void;; /** Full buffer swap or theme change — mark all layers dirty. */ markAllDirty(): void;; } ``` ## ResolvedCellFormat Dense cell format where every property is explicitly present (null when unset). Returned by formats.get(). ```typescript type ResolvedCellFormat = { [K in keyof CellFormat]-?: CellFormat[K] | null; } ``` ## RichText Type alias for rich text content. Empty array = no content, single segment with no format = plain text. ```typescript type RichText = RichTextSegment[] ``` ## RichTextSegment A segment of rich text with optional formatting. Rich text is stored as an array of segments. @example // "Hello World" with "World" in bold [ { text: "Hello " }, { text: "World", format: { bold: true } } ] ```typescript type RichTextSegment = { /** The text content of this segment */ text: string; /** Optional formatting for this segment */ format?: Partial; } ``` ## Scenario A saved scenario with metadata. ```typescript type Scenario = { /** Unique scenario ID */ id: string; /** Creation timestamp (Unix ms) */ createdAt: number; } ``` ## ScenarioConfig Configuration for creating a what-if scenario. ```typescript type ScenarioConfig = { /** Scenario name */ name: string; /** Cell addresses that change (A1 notation) */ changingCells: string[]; /** Values for the changing cells, in the same order */ values: (string | number | boolean | null)[]; /** Optional description */ comment?: string; } ``` ## Schema A schema is a record of field names to their definitions. This is the single source of truth for a Yjs structure's shape. Example: ```typescript const SHEET_MAPS_SCHEMA = { meta: { type: 'Y.Map', required: true, copy: 'deep', lazyInit: false }, cells: { type: 'Y.Map', valueType: 'SerializedCellData', required: true, copy: 'deep', lazyInit: false }, // ... etc } as const satisfies Schema; ``` ```typescript type Schema = Record ``` ## ScrollPosition Scroll position (cell-level, not pixel-level). ```typescript type ScrollPosition = { /** Top visible row index (0-based). */ topRow: number; /** Left visible column index (0-based). */ leftCol: number; } ``` ## SearchOptions Options for cell search operations. ```typescript type SearchOptions = { /** Whether the search is case-sensitive */ matchCase?: boolean; /** Whether to match the entire cell value */ entireCell?: boolean; /** Whether to search formula text instead of computed values */ searchFormulas?: boolean; /** Limit search to this range (A1 notation) */ range?: string; } ``` ## SearchResult A single search result. ```typescript type SearchResult = { /** Cell address in A1 notation */ address: string; /** The cell's display value */ value: string; /** The cell's formula (if any) */ formula?: string; } ``` ## SerializedCellData Serialized cell data for Yjs storage. Uses short keys for compact CRDT storage. NOTE: The DiffCellData type (previously in contracts/src/versioning.ts) was removed when the versioning package was deleted. ```typescript type SerializedCellData = { /** Stable cell identity */ id: CellId; /** Row position */ row: number; /** Column position */ col: number; /** Raw value (CellRawValue). Can be a primitive (string, number, boolean, null) or RichText array. Rich text is only valid for literal values, not formula results. Use isRichText() from @mog-sdk/spreadsheet-contracts to discriminate. Use rawToCellValue() to convert to CellValue when needed. */ r: CellRawValue; /** A1-style formula string without '=' prefix (backward compatible) */ f?: string; /** Parsed identity formula */ idf?: IdentityFormula; /** Computed value (omit if same as raw) */ c?: CellValue; /** Note (omit if empty) */ n?: string; /** Hyperlink URL (omit if none) */ h?: string; /** For spill anchor cells: the dimensions of the spill range. { rows, cols } where rows >= 1 and cols >= 1. Only present on the cell containing the array formula. */ spillRange?: { rows: number; cols: number }; /** For spill member cells: CellId of the anchor cell containing the formula. Points back to the cell that owns this spill range. Used for: - Determining if editing this cell should be blocked - Finding the formula when clicking a spill cell - Clearing old spill when anchor formula result changes size */ spillAnchor?: CellId; /** True if this is a legacy CSE (Ctrl+Shift+Enter) array formula. CSE formulas have fixed size and show {=formula} in the formula bar. Only present on anchor cells when isCSE is true. */ isCSE?: boolean; } ``` ## SeriesConfig Individual series configuration (matches ChartSeriesData wire type) ```typescript type SeriesConfig = { name?: string; type?: string; color?: string; values?: string; categories?: string; bubbleSize?: string; smooth?: boolean; explosion?: number; invertIfNegative?: boolean; yAxisIndex?: number; showMarkers?: boolean; markerSize?: number; markerStyle?: string; lineWidth?: number; points?: PointFormat[]; dataLabels?: DataLabelConfig; trendlines?: TrendlineConfig[]; errorBars?: ErrorBarConfig; xErrorBars?: ErrorBarConfig; yErrorBars?: ErrorBarConfig; idx?: number; order?: number; format?: ChartFormat; barShape?: string; /** Color to use when a data point is inverted (negative) */ invertColor?: ChartColor; /** Marker fill color. */ markerBackgroundColor?: ChartColor; /** Marker border color. */ markerForegroundColor?: ChartColor; /** Whether this series is hidden/filtered from the chart. */ filtered?: boolean; /** Show drop shadow on series. */ showShadow?: boolean; /** Show connector lines between pie slices (bar-of-pie, pie-of-pie). */ showConnectorLines?: boolean; /** Gap width between bars/columns as percentage (per-series override) */ gapWidth?: number; /** Overlap between bars/columns (-100 to 100, per-series override) */ overlap?: number; /** Hole size for doughnut charts as percentage (per-series override) */ doughnutHoleSize?: number; /** First slice angle for pie/doughnut charts in degrees (per-series override) */ firstSliceAngle?: number; /** Split type for of-pie charts (per-series override) */ splitType?: string; /** Split value threshold for of-pie charts (per-series override) */ splitValue?: number; /** Bubble scale as percentage (per-series override) */ bubbleScale?: number; leaderLineFormat?: ChartFormat; showLeaderLines?: boolean; /** @deprecated Use trendlines[] instead */ trendline?: TrendlineConfig; } ``` ## SeriesOrientation Data series orientation ```typescript type SeriesOrientation = 'rows' | 'columns' ``` ## SetCellsResult Result of a bulk setCells() operation. ```typescript type SetCellsResult = { /** Number of cells successfully written */ cellsWritten: number; /** Per-cell errors, if any (omitted when all succeed) */ errors?: Array<{ addr: string; error: string }> | null; /** Non-fatal warnings (e.g., deduplication, coercion) */ warnings?: OperationWarning[]; } ``` ## ShadowAlignment Shadow alignment options. Specifies the alignment of the shadow relative to the text. The shadow is positioned based on this anchor point. @see ECMA-376 Part 1, Section 20.1.10.3 (ST_RectAlignment) ```typescript type ShadowAlignment = | 'tl' // Top-left | 't' // Top-center | 'tr' // Top-right | 'l' // Middle-left | 'ctr' // Center | 'r' // Middle-right | 'bl' // Bottom-left | 'b' // Bottom-center | 'br' ``` ## ShadowEffect Drop shadow effect configuration. ```typescript type ShadowEffect = { /** Shadow color (CSS color string) */ color: string; /** Blur radius in pixels */ blur: number; /** Horizontal offset in pixels */ offsetX: number; /** Vertical offset in pixels */ offsetY: number; /** Opacity (0 = transparent, 1 = opaque) */ opacity: number; } ``` ## Shape Shape as returned by get/list operations. Extends ShapeConfig with identity and metadata fields. Same pattern as Chart extends ChartConfig. ```typescript type Shape = { /** Unique shape ID */ id: string; /** Sheet ID the shape belongs to */ sheetId: string; /** Z-order within the sheet */ zIndex: number; /** Creation timestamp (Unix ms) */ createdAt?: number; /** Last update timestamp (Unix ms) */ updatedAt?: number; } ``` ## ShapeConfig Shape configuration for creating/updating shapes. Uses simple integer positions (anchorRow/anchorCol) for the public API. Internal storage uses CellId-based ObjectPosition. Preserves full fidelity: gradient fills, arrowhead outlines, rich text. ```typescript type ShapeConfig = { /** Shape type (rect, ellipse, triangle, etc.) */ type: ShapeType; /** Anchor row (0-based) */ anchorRow: number; /** Anchor column (0-based) */ anchorCol: number; /** X offset from anchor cell in pixels */ xOffset?: number; /** Y offset from anchor cell in pixels */ yOffset?: number; /** Width in pixels */ width: number; /** Height in pixels */ height: number; /** Absolute pixel X on the sheet. When set, Rust resolves to anchorCol + xOffset. */ pixelX?: number; /** Absolute pixel Y on the sheet. When set, Rust resolves to anchorRow + yOffset. */ pixelY?: number; /** Optional name for the shape */ name?: string; /** Fill configuration (solid, gradient with stops/angle, or none) */ fill?: ObjectFill; /** Outline/stroke configuration (with optional arrowheads) */ outline?: ShapeOutline; /** Rich text content inside the shape (with CellFormat) */ text?: ShapeText; /** Shadow effect */ shadow?: OuterShadowEffect; /** Rotation angle in degrees (0-360) */ rotation?: number; /** Whether the shape is locked */ locked?: boolean; /** Shape-specific adjustments (e.g., cornerRadius for roundRect) */ adjustments?: Record; /** Whether the shape is visible (default: true). */ visible?: boolean; /** Anchor mode: how the shape anchors to cells (twoCell/oneCell/absolute). */ anchorMode?: ObjectAnchorType; /** Whether to preserve aspect ratio when resizing */ lockAspectRatio?: boolean; /** Accessibility title for the shape (distinct from alt text description) */ altTextTitle?: string; /** User-visible display name (may differ from internal name) */ displayName?: string; } ``` ## ShapeEffects Visual effects that can be applied to shapes. ```typescript type ShapeEffects = { /** Drop shadow effect */ shadow?: ShadowEffect; /** Glow effect around the shape */ glow?: GlowEffect; /** Reflection effect below the shape */ reflection?: ReflectionEffect; /** 3D bevel effect */ bevel?: BevelEffect; /** 3D transformation effect */ transform3D?: Transform3DEffect; } ``` ## ShapeHandle ```typescript type ShapeHandle = { shapeType: ShapeType; update(props: Partial): Promise;; duplicate(offsetX?: number, offsetY?: number): Promise;; getData(): Promise;; } ``` ## ShapeObject Shape floating object. A geometric shape with optional fill, outline, and text. ```typescript type ShapeObject = { type: 'shape'; /** Type of shape to render */ shapeType: ShapeType; /** Fill configuration */ fill?: ObjectFill; /** Outline/stroke configuration */ outline?: ShapeOutline; /** Text content inside the shape */ text?: ShapeText; /** Shadow effect (outer shadow / drop shadow) */ shadow?: OuterShadowEffect; /** Shape-specific adjustments. Keys depend on shape type (e.g., 'cornerRadius' for roundRect, 'arrowHeadSize' for arrows, 'starPoints' for stars). */ adjustments?: Record; } ``` ## ShapeOutline Shape outline/stroke configuration. ```typescript type ShapeOutline = { /** Outline style */ style: 'none' | 'solid' | 'dashed' | 'dotted'; /** Outline color (CSS color string) */ color: string; /** Outline width in pixels */ width: number; /** Head (start) arrowhead configuration */ headEnd?: { type: LineEndType; width?: LineEndSize; length?: LineEndSize }; /** Tail (end) arrowhead configuration */ tailEnd?: { type: LineEndType; width?: LineEndSize; length?: LineEndSize }; /** Detailed dash pattern (overrides coarse `style` when set). Matches OfficeJS 12 dash styles. */ dash?: LineDash; /** Outline transparency (0 = opaque, 1 = fully transparent). */ transparency?: number; /** Compound line style (e.g., double, thickThin). */ compound?: CompoundLineStyle; /** Whether the outline is visible. */ visible?: boolean; } ``` ## ShapeText ```typescript type ShapeText = { /** Text content */ content: string; /** Text formatting */ format?: CellFormat; /** Rich text runs for per-run formatting. When present, authoritative over content+format. */ runs?: TextRun[]; /** Vertical alignment of text within shape */ verticalAlign?: 'top' | 'middle' | 'bottom' | 'justified' | 'distributed'; /** Horizontal alignment of text within shape */ horizontalAlign?: 'left' | 'center' | 'right' | 'justify' | 'distributed'; /** Text margins within the container */ margins?: TextMargins; /** Auto-size behavior */ autoSize?: TextAutoSize; /** Text orientation */ orientation?: TextOrientation; /** Reading order / directionality */ readingOrder?: TextReadingOrder; /** Horizontal overflow behavior */ horizontalOverflow?: TextOverflow; /** Vertical overflow behavior */ verticalOverflow?: TextOverflow; } ``` ## ShapeType Available shape types. Matches common Excel/Office shape categories. ```typescript type ShapeType = | 'rect' | 'roundRect' | 'ellipse' | 'triangle' | 'rtTriangle' | 'diamond' | 'pentagon' | 'hexagon' | 'octagon' | 'parallelogram' | 'trapezoid' | 'nonIsoscelesTrapezoid' | 'heptagon' | 'decagon' | 'dodecagon' | 'teardrop' | 'pie' | 'pieWedge' | 'blockArc' | 'donut' | 'noSmoking' | 'plaque' // Rectangle variants (rounded/snipped) | 'round1Rect' | 'round2SameRect' | 'round2DiagRect' | 'snip1Rect' | 'snip2SameRect' | 'snip2DiagRect' | 'snipRoundRect' // Arrows | 'rightArrow' | 'leftArrow' | 'upArrow' | 'downArrow' | 'leftRightArrow' | 'upDownArrow' | 'quadArrow' | 'chevron' // Arrow Callouts | 'leftArrowCallout' | 'rightArrowCallout' | 'upArrowCallout' | 'downArrowCallout' | 'leftRightArrowCallout' | 'upDownArrowCallout' | 'quadArrowCallout' // Curved/Special Arrows | 'bentArrow' | 'uturnArrow' | 'circularArrow' | 'leftCircularArrow' | 'leftRightCircularArrow' | 'curvedRightArrow' | 'curvedLeftArrow' | 'curvedUpArrow' | 'curvedDownArrow' | 'swooshArrow' // Stars and banners | 'star4' | 'star5' | 'star6' | 'star7' | 'star8' | 'star10' | 'star12' | 'star16' | 'star24' | 'star32' | 'ribbon' | 'ribbon2' | 'ellipseRibbon' | 'ellipseRibbon2' | 'leftRightRibbon' | 'banner' // Callouts | 'wedgeRectCallout' | 'wedgeRoundRectCallout' | 'wedgeEllipseCallout' | 'cloud' | 'callout1' | 'callout2' | 'callout3' | 'borderCallout1' | 'borderCallout2' | 'borderCallout3' | 'accentCallout1' | 'accentCallout2' | 'accentCallout3' | 'accentBorderCallout1' | 'accentBorderCallout2' | 'accentBorderCallout3' // Lines and connectors | 'line' | 'lineArrow' | 'lineDoubleArrow' | 'curve' | 'arc' | 'connector' | 'bentConnector2' | 'bentConnector3' | 'bentConnector4' | 'bentConnector5' | 'curvedConnector2' | 'curvedConnector3' | 'curvedConnector4' | 'curvedConnector5' // Flowchart shapes | 'flowChartProcess' | 'flowChartDecision' | 'flowChartInputOutput' | 'flowChartPredefinedProcess' | 'flowChartInternalStorage' | 'flowChartDocument' | 'flowChartMultidocument' | 'flowChartTerminator' | 'flowChartPreparation' | 'flowChartManualInput' | 'flowChartManualOperation' | 'flowChartConnector' | 'flowChartPunchedCard' | 'flowChartPunchedTape' | 'flowChartSummingJunction' | 'flowChartOr' | 'flowChartCollate' | 'flowChartSort' | 'flowChartExtract' | 'flowChartMerge' | 'flowChartOfflineStorage' | 'flowChartOnlineStorage' | 'flowChartMagneticTape' | 'flowChartMagneticDisk' | 'flowChartMagneticDrum' | 'flowChartDisplay' | 'flowChartDelay' | 'flowChartAlternateProcess' | 'flowChartOffpageConnector' // Decorative symbols | 'heart' | 'lightningBolt' | 'sun' | 'moon' | 'smileyFace' | 'foldedCorner' | 'bevel' | 'frame' | 'halfFrame' | 'corner' | 'diagStripe' | 'chord' | 'can' | 'cube' | 'plus' | 'cross' | 'irregularSeal1' | 'irregularSeal2' | 'homePlate' | 'funnel' | 'verticalScroll' | 'horizontalScroll' // Action Buttons | 'actionButtonBlank' | 'actionButtonHome' | 'actionButtonHelp' | 'actionButtonInformation' | 'actionButtonForwardNext' | 'actionButtonBackPrevious' | 'actionButtonEnd' | 'actionButtonBeginning' | 'actionButtonReturn' | 'actionButtonDocument' | 'actionButtonSound' | 'actionButtonMovie' // Brackets and Braces | 'leftBracket' | 'rightBracket' | 'leftBrace' | 'rightBrace' | 'bracketPair' | 'bracePair' // Math shapes | 'mathPlus' | 'mathMinus' | 'mathMultiply' | 'mathDivide' | 'mathEqual' | 'mathNotEqual' // Miscellaneous | 'gear6' | 'gear9' | 'cornerTabs' | 'squareTabs' | 'plaqueTabs' | 'chartX' | 'chartStar' | 'chartPlus' ``` ## Sheet Minimal Sheet interface for selector functions. This represents the deserialized view of sheet data used by selectors. The floatingObjects array is the deserialized form of the Y.Map storage. ```typescript type Sheet = { /** Array of floating objects on the sheet (deserialized from Y.Map) */ floatingObjects?: FloatingObject[]; } ``` ## SheetDataBindingInfo Information about an existing sheet data binding. ```typescript type SheetDataBindingInfo = { /** Unique binding identifier */ id: string; /** Connection providing the data */ connectionId: string; /** Maps data fields to columns */ columnMappings: ColumnMapping[]; /** Auto-insert/delete rows to match data length */ autoGenerateRows: boolean; /** Row index for headers (-1 = no header row) */ headerRow: number; /** First row of data (0-indexed) */ dataStartRow: number; /** Preserve header row formatting on refresh */ preserveHeaderFormatting: boolean; /** Last refresh timestamp */ lastRefresh?: number; } ``` ## SheetEvent Coarse sheet-level event types for `ws.on()`. Each coarse type maps to one or more fine-grained internal events. Callers that need fine-grained control can use SpreadsheetEventType as an escape hatch: `ws.on('filter:applied', handler)`. ```typescript type SheetEvent = | 'cellChanged' | 'filterChanged' | 'visibilityChanged' | 'structureChanged' | 'mergeChanged' | 'tableChanged' | 'chartChanged' | 'slicerChanged' | 'sparklineChanged' | 'groupingChanged' | 'cfChanged' | 'viewportRefreshed' | 'recalcComplete' | 'nameChanged' | 'selectionChanged' | 'activated' | 'deactivated' ``` ## SheetHideReceipt Receipt for a sheet hide mutation. ```typescript type SheetHideReceipt = { kind: 'sheetHide'; name: string; } ``` ## SheetId ```typescript type SheetId = string & { readonly [__sheetId]: true } ``` ## SheetMoveReceipt Receipt for a sheet move mutation. ```typescript type SheetMoveReceipt = { kind: 'sheetMove'; name: string; newIndex: number; } ``` ## SheetRange ```typescript type SheetRange = { startRow: number; startCol: number; endRow: number; endCol: number; } ``` ## SheetRangeDescribeResult Result entry for one sheet range in a batch read. ```typescript type SheetRangeDescribeResult = { /** Sheet name (as resolved). */ sheet: string; /** The range that was actually read. */ range: string; /** The LLM-formatted description (same format as ws.describeRange). Empty string if error. */ description: string; /** Set if this entry failed (bad sheet name, empty sheet, etc.). */ error?: string; } ``` ## SheetRangeRequest A request for a range read on a specific sheet (used by wb.describeRanges). ```typescript type SheetRangeRequest = { /** Sheet name (case-insensitive lookup). */ sheet: string; /** A1-style range, e.g. "A1:M50". If omitted, reads used range. */ range?: string; } ``` ## SheetRemoveReceipt Receipt for a sheet remove mutation. ```typescript type SheetRemoveReceipt = { kind: 'sheetRemove'; removedName: string; remainingCount: number; } ``` ## SheetRenameReceipt Receipt for a sheet rename mutation. ```typescript type SheetRenameReceipt = { kind: 'sheetRename'; oldName: string; newName: string; } ``` ## SheetSettingsInfo Full sheet settings (mirrors SheetSettings from core contracts). ```typescript type SheetSettingsInfo = { /** Default row height in pixels */ defaultRowHeight: number; /** Default column width in pixels */ defaultColWidth: number; /** Whether gridlines are shown */ showGridlines: boolean; /** Whether row headers are shown */ showRowHeaders: boolean; /** Whether column headers are shown */ showColumnHeaders: boolean; /** Whether zero values are displayed (false = blank) */ showZeroValues: boolean; /** Gridline color (hex string) */ gridlineColor: string; /** Whether the sheet is protected */ isProtected: boolean; /** Whether the sheet uses right-to-left layout */ rightToLeft: boolean; } ``` ## SheetShowReceipt Receipt for a sheet show mutation. ```typescript type SheetShowReceipt = { kind: 'sheetShow'; name: string; } ``` ## SheetSnapshot A summary snapshot of a single sheet. ```typescript type SheetSnapshot = { /** Sheet ID */ id: string; /** Sheet name */ name: string; /** Sheet index (0-based) */ index: number; /** Range containing all non-empty cells (A1 notation), or null if empty */ usedRange: string | null; /** Number of cells with data */ cellCount: number; /** Number of cells with formulas */ formulaCount: number; /** Number of charts in this sheet */ chartCount: number; /** Sheet dimensions */ dimensions: { rows: number; cols: number }; } ``` ## ShowValuesAs ```typescript type ShowValuesAs = 'noCalculation' | 'percentOfGrandTotal' | 'percentOfColumnTotal' | 'percentOfRowTotal' | 'percentOfParentRowTotal' | 'percentOfParentColumnTotal' | 'difference' | 'percentDifference' | 'runningTotal' | 'percentRunningTotal' | 'rankAscending' | 'rankDescending' | 'index' ``` ## ShowValuesAsConfig ```typescript type ShowValuesAsConfig = { type: ShowValuesAs; baseField?: string; baseItem?: { type: 'relative'; position: 'previous' | 'next' } | { type: 'specific'; value: CellValue }; } ``` ## SignAnomaly A single cell whose sign disagrees with its neighbors. ```typescript type SignAnomaly = { /** A1 address of the anomalous cell. */ cell: string; /** The cell's computed numeric value. */ value: number; /** Fraction of neighbors with the opposite sign (0.0–1.0). 1.0 = every neighbor disagrees. Sorted descending. */ disagreement: number; /** The neighboring cells that were considered. */ neighbors: { cell: string; value: number }[]; } ``` ## SignCheckOptions Options for sign anomaly detection. ```typescript type SignCheckOptions = { /** Which axis to check sign consistency along. - `'column'`: compare cells vertically within each column (default). - `'row'`: compare cells horizontally within each row. - `'both'`: run both checks, merge results. */ axis?: 'column' | 'row' | 'both'; /** How many non-empty numeric neighbors to consider in each direction. Default: 3 (up to 6 neighbors total per axis). */ window?: number; } ``` ## SignCheckResult Result of a signCheck call. ```typescript type SignCheckResult = { /** Total non-zero numeric cells examined. */ cellsChecked: number; /** Cells whose sign disagrees with the majority of their neighbors. */ anomalies: SignAnomaly[]; } ``` ## SingleAxisConfig Single axis configuration (matches SingleAxisData wire type). ```typescript type SingleAxisConfig = { title?: string; visible: boolean; min?: number; max?: number; axisType?: string; gridLines?: boolean; minorGridLines?: boolean; majorUnit?: number; minorUnit?: number; tickMarks?: string; minorTickMarks?: string; numberFormat?: string; reverse?: boolean; position?: string; logBase?: number; displayUnit?: string; format?: ChartFormat; titleFormat?: ChartFormat; gridlineFormat?: ChartLineFormat; minorGridlineFormat?: ChartLineFormat; crossBetween?: string; tickLabelPosition?: string; baseTimeUnit?: string; majorTimeUnit?: string; minorTimeUnit?: string; customDisplayUnit?: number; displayUnitLabel?: string; labelAlignment?: string; labelOffset?: number; noMultiLevelLabels?: boolean; /** Scale type: linear or logarithmic */ scaleType?: 'linear' | 'logarithmic'; /** Category axis type */ categoryType?: 'automatic' | 'textAxis' | 'dateAxis'; /** Where the axis crosses */ crossesAt?: 'automatic' | 'max' | 'min' | 'custom'; /** Custom crossing value when crossesAt is 'custom' */ crossesAtValue?: number; /** Whether the axis title is visible (separate from title text content). */ titleVisible?: boolean; /** Interval between tick labels (e.g., 1 = every label, 2 = every other). */ tickLabelSpacing?: number; /** Interval between tick marks. */ tickMarkSpacing?: number; /** Whether the number format is linked to the source data cell format. */ linkNumberFormat?: boolean; /** Whether tick marks are between categories (true) or on categories (false) */ isBetweenCategories?: boolean; /** Text orientation angle in degrees (-90 to 90) */ textOrientation?: number; /** Label alignment (alias for labelAlignment) */ alignment?: string; /** @deprecated Alias for axisType — kept for backward compat with charts package */ type?: AxisType; /** @deprecated Alias for visible — kept for backward compat with charts package */ show?: boolean; } ``` ## Size A 2D size (width and height). ```typescript type Size = { width: number; height: number; } ``` ## Slicer Full slicer state including selection and position. ```typescript type Slicer = { /** Currently selected filter items */ selectedItems: CellValue[]; /** Position and dimensions in pixels */ position: { x: number; y: number; width: number; height: number }; } ``` ## SlicerConfig Configuration for creating a new slicer. ```typescript type SlicerConfig = { /** Slicer ID (generated if omitted) */ id?: string; /** Sheet ID the slicer belongs to */ sheetId?: string; /** Name of the table to connect the slicer to */ tableName?: string; /** Column name within the table to filter on */ columnName?: string; /** Display name for the slicer (auto-generated if omitted) */ name?: string; /** Position and dimensions in pixels */ position?: { x: number; y: number; width: number; height: number }; /** Data source connection (rich alternative to tableName/columnName) */ source?: SlicerSource; /** Slicer caption (header text) */ caption?: string; /** Style configuration */ style?: SlicerStyle; /** Show slicer header */ showHeader?: boolean; /** Z-order within the sheet */ zIndex?: number; /** Whether slicer position is locked */ locked?: boolean; /** Whether multi-select is enabled */ multiSelect?: boolean; /** Initial selected values */ selectedValues?: CellValue[]; /** Currently selected date range start (timeline slicers) */ selectedStartDate?: number; /** Currently selected date range end (timeline slicers) */ selectedEndDate?: number; /** Current aggregation level (timeline slicers) */ timelineLevel?: TimelineLevel; } ``` ## SlicerCustomStyle Custom slicer style definition. Canonical source: compute-types.gen.ts (Rust domain-types) ```typescript type SlicerCustomStyle = { /** Header background color */ headerBackgroundColor?: string; /** Header text color */ headerTextColor?: string; /** Header font size */ headerFontSize?: number; /** Selected item background color */ selectedBackgroundColor?: string; /** Selected item text color */ selectedTextColor?: string; /** Available item background color */ availableBackgroundColor?: string; /** Available item text color */ availableTextColor?: string; /** Unavailable item background color */ unavailableBackgroundColor?: string; /** Unavailable item text color */ unavailableTextColor?: string; /** Border color */ borderColor?: string; /** Border width in pixels */ borderWidth?: number; /** Corner radius for items */ itemBorderRadius?: number; } ``` ## SlicerHandle Slicer handle — hosting ops only. Content ops (selection, filter state) via ws.slicers.* Note: SlicerObject is not in the FloatingObject union (slicers use their own type system in contracts/src/data/slicers.ts). getData() returns the base FloatingObject type. ```typescript type SlicerHandle = { duplicate(offsetX?: number, offsetY?: number): Promise;; } ``` ## SlicerInfo Summary information about a slicer. ```typescript type SlicerInfo = { /** Unique slicer ID */ id: string; /** Programmatic name (unique within workbook). Falls back to caption if not set. */ name: string; /** Display caption (header text). */ caption: string; /** Connected table name */ tableName: string; /** Connected column name */ columnName: string; /** Source type — 'table' for table slicers, 'pivot' for pivot table slicers */ source?: { type: 'table' | 'pivot' }; /** Discriminator for timeline slicers (matches TimelineSlicerConfig.sourceType) */ sourceType?: 'timeline'; } ``` ## SlicerItem A single item in a slicer's value list. ```typescript type SlicerItem = { /** The display value */ value: CellValue; /** Whether this item is currently selected */ selected: boolean; /** Number of matching records (if available) */ count?: number; } ``` ## SlicerPivotSource Reference to a pivot field for slicer binding. ```typescript type SlicerPivotSource = { type: 'pivot'; /** Pivot table ID to connect to */ pivotId: string; /** Field name in the pivot (row/column/filter field) */ fieldName: string; /** Which area the field is in */ fieldArea: 'row' | 'column' | 'filter'; } ``` ## SlicerSortOrder Slicer sort order. Canonical source: compute-types.gen.ts ```typescript type SlicerSortOrder = 'ascending' | 'descending' | 'dataSourceOrder' ``` ## SlicerSource Union type for slicer data sources. Canonical source: compute-types.gen.ts (Rust domain-types) Generated version uses intersection with helper interfaces: `{ type: "table" } & SlicerSource_table | { type: "pivot" } & SlicerSource_pivot` Contracts uses named interface variants. Both are structurally identical (same internally-tagged discriminated union shape). No bridge conversion needed. ```typescript type SlicerSource = SlicerTableSource | SlicerPivotSource ``` ## SlicerState Minimal state type for selectors - matches XState snapshot shape. ```typescript type SlicerState = { context: { /** ID of the slicer being interacted with (null if no slicer focused) */ slicerId: string | null; /** Sheet containing the slicer */ sheetId: SheetId | null; /** Last clicked value (for shift+click range selection) */ lastClickedValue: CellValue | undefined; /** Currently hovered item value (for hover effects) */ hoveredValue: CellValue | undefined; /** Whether multi-select mode is active (Ctrl key held) */ isMultiSelectActive: boolean; /** Error message (for disconnected state, etc.) */ errorMessage: string | null; /** Whether slicer is in disconnected state (source column deleted) */ isDisconnected: boolean; }; matches(state: any): boolean;; value: string; } ``` ## SlicerStyle Complete slicer style configuration. Canonical source: compute-types.gen.ts (Rust domain-types) ```typescript type SlicerStyle = { /** Style preset (mutually exclusive with custom) */ preset?: SlicerStylePreset; /** Custom style (mutually exclusive with preset) */ custom?: SlicerCustomStyle; /** Number of columns for item layout (default: 1) */ columnCount: number; /** Button height in pixels */ buttonHeight: number; /** Show item selection indicators */ showSelectionIndicator: boolean; /** ST_SlicerCacheCrossFilter — controls cross-filtering visual indication. Replaces the previous showItemsWithNoData boolean. Default: 'showItemsWithDataAtTop' */ crossFilter: CrossFilterMode; /** Whether to use custom sort list. Default: true */ customListSort: boolean; /** Whether to show items with no matching data (x14 pivot-backed slicers). Default: true */ showItemsWithNoData: boolean; /** 'dataSourceOrder' is internal-only; never read from or written to OOXML. Import defaults to 'ascending'. */ sortOrder: SlicerSortOrder; } ``` ## SlicerStyleInfo ```typescript type SlicerStyleInfo = { name: string; isDefault: boolean; } ``` ## SlicerStylePreset Slicer style presets matching Excel's slicer style gallery. Canonical source: compute-types.gen.ts (Rust domain-types) ```typescript type SlicerStylePreset = | 'light1' | 'light2' | 'light3' | 'light4' | 'light5' | 'light6' | 'dark1' | 'dark2' | 'dark3' | 'dark4' | 'dark5' | 'dark6' | 'other1' | 'other2' ``` ## SlicerTableSource Reference to a table field for slicer binding. Uses column header CellId for Cell Identity Model compliance. **Graceful Degradation:** If the column header cell is deleted, the slicer becomes "disconnected" and shows a placeholder state. This matches Excel behavior where slicers become invalid when their source column is deleted. ```typescript type SlicerTableSource = { type: 'table'; /** Table ID to connect to */ tableId: string; /** Column header CellId - stable across column moves. If this CellId becomes orphaned (column deleted), slicer shows disconnected state. */ columnCellId: CellId; } ``` ## SmartArtCategory SmartArt diagram categories matching Excel. Each category represents a different type of visual representation: - list: Sequential or grouped items - process: Steps or stages in a workflow - cycle: Continuous or circular processes - hierarchy: Organization charts, tree structures - relationship: Connections between concepts - matrix: Grid-based relationships - pyramid: Proportional or hierarchical layers - picture: Image-centric layouts ```typescript type SmartArtCategory = | 'list' | 'process' | 'cycle' | 'hierarchy' | 'relationship' | 'matrix' | 'pyramid' | 'picture' ``` ## SmartArtConfig Configuration for creating a new SmartArt diagram. ```typescript type SmartArtConfig = { /** Layout ID (e.g., 'hierarchy/org-chart', 'process/basic-process'). */ layoutId: string; /** X position in pixels. */ x?: number; /** Y position in pixels. */ y?: number; /** Width in pixels. */ width?: number; /** Height in pixels. */ height?: number; /** Initial nodes to create. */ nodes?: SmartArtNodeConfig[]; /** Display name. */ name?: string; } ``` ## SmartArtDiagram SmartArt diagram model (deserialized TypeScript view). IMPORTANT: This interface represents the runtime/API view of the data. Actual Yjs storage uses Y.Map and Y.Array types as defined in SMARTART_DIAGRAM_SCHEMA. The bridge handles conversion between formats. NOTE: computedLayout is NOT part of this interface because it's a runtime cache managed by the bridge, not persisted data. COPY SEMANTICS: When copying a SmartArtDiagram, the bridge must: 1. Generate new NodeIds for all nodes (using createNodeId()) 2. Build oldId -> newId mapping 3. Deep-copy node data (text, styling, level, siblingOrder) 4. Remap parentId and childIds references using mapping 5. Update rootNodeIds array with new IDs 6. Preserve tree structure with new identity ```typescript type SmartArtDiagram = { /** Layout ID (e.g., 'hierarchy/org-chart', 'process/basic-process') */ layoutId: string; /** Category of the diagram */ category: SmartArtCategory; /** Map of all nodes by their ID */ nodes: Map; /** Top-level (root) node IDs in display order */ rootNodeIds: NodeId[]; /** Quick style ID (e.g., 'subtle-effect', 'moderate-effect') */ quickStyleId: string; /** Color theme ID (e.g., 'colorful-1', 'accent-1') */ colorThemeId: string; /** Layout-specific options (varies by layout type) */ layoutOptions: Record; } ``` ## SmartArtHandle SmartArt handle — hosting ops only. Content ops (nodes, layout, style) via ws.smartArt.* ```typescript type SmartArtHandle = { duplicate(offsetX?: number, offsetY?: number): Promise;; getData(): Promise;; } ``` ## SmartArtNode Single node in a SmartArt diagram. Nodes form a tree structure with parent-child relationships. Each node can have optional per-node styling that overrides diagram defaults. ```typescript type SmartArtNode = { /** Unique node identifier */ id: NodeId; /** Text content displayed in the node */ text: string; /** Hierarchy level (0 = root, 1 = child, 2 = grandchild, etc.) */ level: number; /** Parent node ID (null for root nodes) */ parentId: NodeId | null; /** Ordered child node IDs */ childIds: NodeId[]; /** Order among siblings (used for layout ordering) */ siblingOrder: number; /** Fill/background color (CSS color string) */ fillColor?: string; /** Border/stroke color (CSS color string) */ borderColor?: string; /** Text color (CSS color string) */ textColor?: string; /** Font family for node text */ fontFamily?: string; /** Font size in points */ fontSize?: number; /** Font weight */ fontWeight?: 'normal' | 'bold'; /** Font style */ fontStyle?: 'normal' | 'italic'; /** Image URL for picture layouts */ imageUrl?: string; /** How the image fits within the node bounds */ imageFit?: 'cover' | 'contain' | 'fill'; } ``` ## SmartArtNodeConfig Configuration for a SmartArt diagram node. ```typescript type SmartArtNodeConfig = { /** Node text content. */ text: string; /** Hierarchy level (0 = root). */ level?: number; /** Insertion position relative to a reference node. */ position?: 'before' | 'after' | 'child'; /** Reference node ID for positioning. */ referenceNodeId?: string; } ``` ## SmartArtNodeId SmartArt node ID type. ```typescript type SmartArtNodeId = string ``` ## SmartArtObject SmartArt floating object. SmartArt provides visual representations of information like organization charts, process flows, relationship diagrams, and hierarchies. The diagram data contains the nodes and their relationships, while layout/styling is computed at render time. Architecture Notes: - Diagram data (nodes, relationships) is persisted in Yjs via the bridge layer - Selection state (selectedNodeIds, editingNodeId) lives in XState context, NOT here - Computed layout is a runtime cache, managed by the bridge - Uses existing object-interaction-machine for selection/drag/resize ```typescript type SmartArtObject = { type: 'smartart'; /** The SmartArt diagram data including nodes, relationships, and styling. This is the persisted data - layout is computed at runtime. */ diagram: SmartArtDiagram; } ``` ## SmartArtShapeType SmartArt-specific shape types. This is a subset of the full ShapeType union from floating-objects.ts that SmartArt layouts commonly use. The names match exactly with the ShapeType definitions to ensure compatibility. ```typescript type SmartArtShapeType = | 'rect' | 'roundRect' | 'ellipse' | 'diamond' | 'hexagon' | 'chevron' | 'rightArrow' | 'pentagon' | 'trapezoid' | 'parallelogram' | 'plus' | 'star5' | 'cloud' | 'wedgeRectCallout' ``` ## SortColumn A single column sort specification. ```typescript type SortColumn = { /** Column index (0-based, relative to the sort range) */ column: number; /** Sort direction as boolean (default: true = ascending). Use `direction` for string form. */ ascending?: boolean; /** Sort direction as 'asc' | 'desc'. Takes precedence over `ascending` if both are set. */ direction?: 'asc' | 'desc'; /** What to sort by (default: 'value') */ sortBy?: 'value' | 'cellColor' | 'fontColor'; /** Case sensitive comparison (default: false) */ caseSensitive?: boolean; } ``` ## SortOptions Options for sorting a range of cells. ```typescript type SortOptions = { /** Columns to sort by, in priority order */ columns: SortColumn[]; /** Whether the first row of the range contains headers (default: false) */ hasHeaders?: boolean; } ``` ## SortOrder Sort order for pivot fields. "none" means no explicit sort — uses natural order. Maps to Option on the Rust side (None = "none"). ```typescript type SortOrder = 'asc' | 'desc' | 'none' ``` ## SplitViewportConfig Split view: 2-4 independently scrolling viewports. Split view creates independent panes that can each scroll separately, allowing users to compare distant regions of the spreadsheet. Viewport IDs by direction: - 'horizontal': 'top', 'bottom' (split along a row) - 'vertical': 'left', 'right' (split along a column) - 'both': 'topLeft', 'topRight', 'bottomLeft', 'bottomRight' (4 quadrants) @see plans/active/excel-parity/01-split-view-not-implemented.md ```typescript type SplitViewportConfig = { type: 'split'; /** Direction of the split */ direction: 'horizontal' | 'vertical' | 'both'; /** Row index for horizontal split line. Used when direction is 'horizontal' or 'both'. Defaults to 0 (ignored) when direction is 'vertical'. */ horizontalPosition: number; /** Column index for vertical split line. Used when direction is 'vertical' or 'both'. Defaults to 0 (ignored) when direction is 'horizontal'. */ verticalPosition: number; } ``` ## StockSubType Stock chart sub-types (OHLC = Open-High-Low-Close) ```typescript type StockSubType = 'hlc' | 'ohlc' | 'volume-hlc' | 'volume-ohlc' ``` ## StrokeId Unique identifier for a stroke within a drawing. Branded type provides type safety - prevents accidentally using string IDs where StrokeId is expected (and vice versa). Uses UUID v7 (time-sortable) for: - Uniqueness across clients (no coordination needed) - Time-sortability for undo/redo ordering - Compact string representation ```typescript type StrokeId = string & { readonly __brand: 'StrokeId' } ``` ## StrokeTransformParams Transform parameters for stroke transformations. ```typescript type StrokeTransformParams = { /** Transform type */ type: StrokeTransformType; /** Center point X for rotation/scale */ centerX?: number; /** Center point Y for rotation/scale */ centerY?: number; /** Rotation angle in radians (for 'rotate') */ angle?: number; /** Scale factor X (for 'scale') */ scaleX?: number; /** Scale factor Y (for 'scale') */ scaleY?: number; } ``` ## StrokeTransformType Transform type for stroke transformations. ```typescript type StrokeTransformType = 'rotate' | 'scale' | 'flip-horizontal' | 'flip-vertical' ``` ## StructureChangeSource Identifies the source of a structural change ```typescript type StructureChangeSource = 'user' | 'import' | 'api' | 'remote' | 'system' ``` ## StyleCategory Style category for grouping styles in the UI gallery. ```typescript type StyleCategory = | 'good-bad-neutral' // Good, Bad, Neutral | 'data-model' // Calculation, Check Cell, etc. | 'titles-headings' // Title, Heading 1-4 | 'themed' // Accent1-6 variations | 'number-format' // Currency, Percent, Comma | 'custom' ``` ## SubPath A single subpath within a compound path. ```typescript type SubPath = { segments: PathSegment[]; closed: boolean; } ``` ## SubSupNode Sub-Superscript - ```typescript type SubSupNode = { type: 'sSubSup'; /** Align scripts */ alnScr?: boolean; /** Base */ e: MathNode[]; /** Subscript */ sub: MathNode[]; /** Superscript */ sup: MathNode[]; } ``` ## SubscriptNode Subscript - ```typescript type SubscriptNode = { type: 'sSub'; /** Base */ e: MathNode[]; /** Subscript */ sub: MathNode[]; } ``` ## SubtotalConfig Configuration for the subtotal operation. ```typescript type SubtotalConfig = { /** Column index to group by (0-based) */ groupByColumn: number; /** Columns to subtotal (0-based indices) */ subtotalColumns: number[]; /** Aggregation function to use */ aggregation: 'sum' | 'count' | 'average' | 'max' | 'min'; /** Whether to replace existing subtotals */ replace?: boolean; } ``` ## SubtotalLocation ```typescript type SubtotalLocation = 'top' | 'bottom' ``` ## SummaryOptions Options for the `worksheet.summarize()` method. ```typescript type SummaryOptions = { /** Whether to include sample data in the summary */ includeData?: boolean; /** Maximum number of rows to include in sample data */ maxRows?: number; /** Maximum number of columns to include in sample data */ maxCols?: number; } ``` ## SuperscriptNode Superscript - ```typescript type SuperscriptNode = { type: 'sSup'; /** Base */ e: MathNode[]; /** Superscript */ sup: MathNode[]; } ``` ## TableAddColumnReceipt Receipt for a table addColumn mutation. ```typescript type TableAddColumnReceipt = { kind: 'tableAddColumn'; tableName: string; columnName: string; position: number; } ``` ## TableAddRowReceipt Receipt for a table addRow mutation. ```typescript type TableAddRowReceipt = { kind: 'tableAddRow'; tableName: string; index: number; } ``` ## TableColumn A single column in a table. Field names match the Rust-generated `TableColumn` type (compute-types.gen.ts). ```typescript type TableColumn = { /** Unique column ID */ id: string; /** Column header name */ name: string; /** Column index within the table (0-based) */ index: number; /** Total row function type */ totalsFunction: TotalsFunction | null; /** Total row label */ totalsLabel: string | null; /** Calculated column formula */ calculatedFormula?: string; } ``` ## TableConfig Complete table configuration stored in Yjs. This is the source of truth for table metadata. P0-07: Tables use CellIdRange for CRDT-safe range tracking. The rangeIdentity field stores CellId corners, and position-based range is resolved at render time via resolveTableRange(). ```typescript type TableConfig = { /** Unique table identifier */ id: string; /** Table name used in structured references (e.g., "Table1") */ name: string; /** Sheet containing the table */ sheetId: string; /** P0-07: CellId-based range (CRDT-safe). Automatically expands when rows/cols inserted inside table. Resolution to positions happens at render time. */ rangeIdentity?: CellIdRange; /** @deprecated Use rangeIdentity instead. Legacy position-based range - kept for migration only. Table range (includes header and total rows if present) */ range: CellRange; /** Whether table has a header row (default: true) */ hasHeaderRow: boolean; /** Whether table has a total row (default: false) */ hasTotalRow: boolean; /** Column definitions in order */ columns: TableColumn[]; /** Style configuration */ style: TableStyle; /** Auto-expand when data added adjacent to table (default: true) */ autoExpand: boolean; /** Show filter dropdowns in header row (default: true) */ showFilterButtons: boolean; /** Created timestamp (Unix ms) */ createdAt?: number; /** Last modified timestamp (Unix ms) */ updatedAt?: number; } ``` ## TableCreatedEvent ```typescript type TableCreatedEvent = { type: 'table:created'; sheetId: string; tableId: string; config: TableConfig; source: StructureChangeSource; } ``` ## TableCustomStyle Custom table style definition (user-defined). Allows fine-grained control over table appearance. ```typescript type TableCustomStyle = { /** Header row background color */ headerRowFill?: string; /** Header row font formatting */ headerRowFont?: CellFormat; /** Data row background color */ dataRowFill?: string; /** Alternating data row background (for banded rows) */ dataRowAltFill?: string; /** Total row background color */ totalRowFill?: string; /** Total row font formatting */ totalRowFont?: CellFormat; /** First column highlight background */ firstColumnFill?: string; /** Last column highlight background */ lastColumnFill?: string; } ``` ## TableDeleteRowReceipt Receipt for a table deleteRow mutation. ```typescript type TableDeleteRowReceipt = { kind: 'tableDeleteRow'; tableName: string; index: number; } ``` ## TableDeletedEvent ```typescript type TableDeletedEvent = { type: 'table:deleted'; sheetId: string; tableId: string; source: StructureChangeSource; } ``` ## TableInfo Information about an existing table. Field names match the Rust-generated `Table` type (compute-types.gen.ts) except `range` which is converted from `SheetRange` to A1 notation string. ```typescript type TableInfo = { /** Internal table identifier */ id: string; /** Table name */ name: string; /** Display name */ displayName: string; /** Sheet the table belongs to */ sheetId: string; /** Table range in A1 notation (converted from Rust SheetRange) */ range: string; /** Column definitions */ columns: TableColumn[]; /** Whether the table has a header row */ hasHeaderRow: boolean; /** Whether the totals row is visible */ hasTotalsRow: boolean; /** Table style name */ style: string; /** Whether banded rows are shown */ bandedRows: boolean; /** Whether banded columns are shown */ bandedColumns: boolean; /** Whether first column is emphasized */ emphasizeFirstColumn: boolean; /** Whether last column is emphasized */ emphasizeLastColumn: boolean; /** Whether filter buttons are shown */ showFilterButtons: boolean; } ``` ## TableOptions Options for creating a new table. ```typescript type TableOptions = { /** Table name (auto-generated if omitted) */ name?: string; /** Whether the first row of the range contains headers (default: true) */ hasHeaders?: boolean; /** Table style preset name */ style?: string; } ``` ## TableRemoveColumnReceipt Receipt for a table removeColumn mutation. ```typescript type TableRemoveColumnReceipt = { kind: 'tableRemoveColumn'; tableName: string; columnIndex: number; } ``` ## TableRemoveReceipt Receipt for a table remove mutation. ```typescript type TableRemoveReceipt = { kind: 'tableRemove'; tableName: string; } ``` ## TableResizeReceipt Receipt for a table resize mutation. ```typescript type TableResizeReceipt = { kind: 'tableResize'; tableName: string; newRange: string; } ``` ## TableRowCollection A collection-like wrapper around a table's data rows. Returned by `WorksheetTables.getRows()`. The `count` property is a snapshot taken at construction time and does NOT live-update. ```typescript type TableRowCollection = { /** Number of data rows (snapshot, not live). */ count: number; /** Get the cell values of a data row by index. */ getAt(index: number): Promise;; /** Add a data row. If index is omitted, appends to the end. */ add(index?: number, values?: CellValue[]): Promise;; /** Delete a data row by index. */ deleteAt(index: number): Promise;; /** Get the cell values of a data row by index. */ getValues(index: number): Promise;; /** Set the cell values of a data row by index. */ setValues(index: number, values: CellValue[]): Promise;; /** Get the A1-notation range for a data row by index. */ getRange(index: number): Promise;; } ``` ## TableSelectionChangedEvent ```typescript type TableSelectionChangedEvent = { type: 'table:selection-changed'; sheetId: string; tableId: string; tableName: string; /** The selected range within the table, or null if selection moved outside the table. */ selection: CellRange | null; source: StructureChangeSource; } ``` ## TableStyle Complete table style configuration. Either uses a preset or custom style definition. ```typescript type TableStyle = { /** Preset style name (mutually exclusive with custom) */ preset?: TableStylePreset; /** Custom style definition (mutually exclusive with preset) */ custom?: TableCustomStyle; /** Show alternating row colors */ showBandedRows?: boolean; /** Show alternating column colors */ showBandedColumns?: boolean; /** Highlight first column with special formatting */ showFirstColumnHighlight?: boolean; /** Highlight last column with special formatting */ showLastColumnHighlight?: boolean; } ``` ## TableStyleConfig Configuration for creating/updating a custom table style. ```typescript type TableStyleConfig = { /** Style name */ name: string; } ``` ## TableStyleInfoWithReadOnly A table style with a computed `readOnly` flag (built-in styles are read-only). ```typescript type TableStyleInfoWithReadOnly = TableStyleInfo & { readOnly: boolean } ``` ## TableStylePreset Table style presets matching Excel's table style gallery. Light styles (1-21), Medium styles (1-28), Dark styles (1-11). ```typescript type TableStylePreset = | 'none' // Light styles | 'light1' | 'light2' | 'light3' | 'light4' | 'light5' | 'light6' | 'light7' | 'light8' | 'light9' | 'light10' | 'light11' | 'light12' | 'light13' | 'light14' | 'light15' | 'light16' | 'light17' | 'light18' | 'light19' | 'light20' | 'light21' // Medium styles | 'medium1' | 'medium2' | 'medium3' | 'medium4' | 'medium5' | 'medium6' | 'medium7' | 'medium8' | 'medium9' | 'medium10' | 'medium11' | 'medium12' | 'medium13' | 'medium14' | 'medium15' | 'medium16' | 'medium17' | 'medium18' | 'medium19' | 'medium20' | 'medium21' | 'medium22' | 'medium23' | 'medium24' | 'medium25' | 'medium26' | 'medium27' | 'medium28' // Dark styles | 'dark1' | 'dark2' | 'dark3' | 'dark4' | 'dark5' | 'dark6' | 'dark7' | 'dark8' | 'dark9' | 'dark10' | 'dark11' ``` ## TableUpdatedEvent ```typescript type TableUpdatedEvent = { type: 'table:updated'; sheetId: string; tableId: string; changes: Partial; source: StructureChangeSource; } ``` ## TextAutoSize How text auto-sizes within its container. ```typescript type TextAutoSize = | { type: 'none' } | { type: 'textToFitShape'; fontScale?: number; lineSpacingReduction?: number } | { type: 'shapeToFitText' } ``` ## TextBoxBorder Text box border with optional corner radius. ```typescript type TextBoxBorder = { /** Corner radius in pixels (for rounded corners) */ radius?: number; } ``` ## TextBoxConfig Configuration for creating a new text box. ```typescript type TextBoxConfig = { /** Text content and formatting — shared model with ShapeData. */ text?: ShapeText; /** X position in pixels. */ x?: number; /** Y position in pixels. */ y?: number; /** Width in pixels (default: 200). */ width?: number; /** Height in pixels (default: 100). */ height?: number; /** Display name. */ name?: string; } ``` ## TextBoxHandle ```typescript type TextBoxHandle = { update(props: Partial): Promise;; duplicate(offsetX?: number, offsetY?: number): Promise;; getData(): Promise;; } ``` ## TextBoxObject Text box floating object. A rectangular container for rich text content. ```typescript type TextBoxObject = { type: 'textbox'; /** Text content and formatting — shared model with ShapeData. */ text?: ShapeText; /** Fill color/gradient for the text box background */ fill?: ObjectFill; /** Border around the text box */ border?: TextBoxBorder; /** Optional WordArt configuration for styled text effects */ wordArt?: WordArtConfig; } ``` ## TextFormat Rich Text Types Defines the rich text segment model for Excel-compatible rich text support. Rich text is stored as an array of segments, where each segment has text and optional formatting. Key design decisions: - Segment array (not formatted string) for clean storage and rendering - TextFormat matches Excel's inline rich text capabilities - Runtime utility functions live in utils/rich-text.ts and are re-exported here @see STREAM-C3-COMMENTS-RICHTEXT.md ```typescript type TextFormat = { /** Bold text */ bold?: boolean; /** Italic text */ italic?: boolean; /** Underline type (single, double, accounting styles) */ underlineType?: 'none' | 'single' | 'double' | 'singleAccounting' | 'doubleAccounting'; /** Strikethrough text */ strikethrough?: boolean; /** Font family name (e.g., "Arial", "Calibri") */ fontFamily?: string; /** Font size in points */ fontSize?: number; /** Font color in hex format (e.g., "#FF0000") */ fontColor?: string; /** Superscript text (e.g., for exponents) */ superscript?: boolean; /** Subscript text (e.g., for chemical formulas) */ subscript?: boolean; } ``` ## TextMargins Text margins within a text box or shape. ```typescript type TextMargins = { /** Top margin in pixels */ top: number; /** Right margin in pixels */ right: number; /** Bottom margin in pixels */ bottom: number; /** Left margin in pixels */ left: number; } ``` ## TextOrientation Text orientation within a shape. ```typescript type TextOrientation = | 'horizontal' | 'vertical' | 'vertical270' | 'wordArtVertical' | 'eastAsianVertical' | 'mongolianVertical' ``` ## TextOverflow Text overflow behavior. ```typescript type TextOverflow = 'overflow' | 'clip' | 'ellipsis' ``` ## TextReadingOrder Text reading order / directionality. ```typescript type TextReadingOrder = 'leftToRight' | 'rightToLeft' ``` ## TextRun Text content inside a shape. ```typescript type TextRun = { text: string; format?: CellFormat; } ``` ## TextStyle Text styling properties for node labels. ```typescript type TextStyle = { /** Font family name */ fontFamily: string; /** Font size in points */ fontSize: number; /** Font weight */ fontWeight: 'normal' | 'bold'; /** Font style */ fontStyle: 'normal' | 'italic'; /** Text color (CSS color string) */ color: string; /** Horizontal text alignment */ align: 'left' | 'center' | 'right'; /** Vertical text alignment */ verticalAlign: 'top' | 'middle' | 'bottom'; } ``` ## TextToColumnsOptions Options for text-to-columns splitting. ```typescript type TextToColumnsOptions = { /** Delimiter type */ delimiter: 'comma' | 'tab' | 'semicolon' | 'space' | 'custom'; /** Custom delimiter character (when delimiter is 'custom') */ customDelimiter?: string; /** Whether to treat consecutive delimiters as one */ treatConsecutiveAsOne?: boolean; /** Text qualifier character */ textQualifier?: '"' | "'" | 'none'; } ``` ## ThemeColorSlot All valid theme color slot names ```typescript type ThemeColorSlot = keyof ThemeColors ``` ## ThemeColors Theme Contracts Type definitions and utilities for workbook themes. Themes define color palettes and font pairs that cells can reference. Issue 4: Page Layout - Themes ```typescript type ThemeColors = { /** Primary dark color - typically black/near-black for text */ dark1: string; /** Primary light color - typically white for backgrounds */ light1: string; /** Secondary dark color */ dark2: string; /** Secondary light color */ light2: string; /** Accent color 1 - primary accent (blue in Office default) */ accent1: string; /** Accent color 2 - typically orange */ accent2: string; /** Accent color 3 - typically gray */ accent3: string; /** Accent color 4 - typically yellow/gold */ accent4: string; /** Accent color 5 - typically blue-gray */ accent5: string; /** Accent color 6 - typically green */ accent6: string; /** Hyperlink color */ hyperlink: string; /** Followed hyperlink color */ followedHyperlink: string; } ``` ## ThemeDefinition Complete theme definition including colors and fonts. ```typescript type ThemeDefinition = { /** Unique theme identifier (e.g., 'office', 'slice', 'custom-abc123') */ id: string; /** Display name shown in UI (e.g., 'Office', 'Slice') */ name: string; /** Theme color palette */ colors: ThemeColors; /** Theme font pair */ fonts: ThemeFonts; /** True for built-in themes, false for user-created */ builtIn: boolean; } ``` ## ThemeFonts Theme font pair - major (headings) and minor (body) fonts. ```typescript type ThemeFonts = { /** Font for headings (e.g., 'Calibri Light') */ majorFont: string; /** Font for body text (e.g., 'Calibri') */ minorFont: string; } ``` ## TileSettings Tile settings for picture/texture fills. ```typescript type TileSettings = { tx?: number; ty?: number; sx?: number; sy?: number; flip?: string; algn?: string; } ``` ## TimelineLevel Timeline aggregation level. Determines how dates are grouped in the timeline display. ```typescript type TimelineLevel = 'years' | 'quarters' | 'months' | 'days' ``` ## TimelineSlicerConfig Timeline slicer specific configuration. Extends base slicer for date-range filtering. ```typescript type TimelineSlicerConfig = { /** Source must be table or pivot with date column */ sourceType: 'timeline'; /** Current aggregation level */ timelineLevel: TimelineLevel; /** Start date of the data range */ dataStartDate?: number; /** End date of the data range */ dataEndDate?: number; /** Currently selected date range start */ selectedStartDate?: number; /** Currently selected date range end */ selectedEndDate?: number; /** Show the level selector in the header */ showLevelSelector: boolean; /** Show the date range label */ showDateRangeLabel: boolean; } ``` ## TitleConfig Rich title configuration ```typescript type TitleConfig = { text?: string; visible?: boolean; position?: 'top' | 'bottom' | 'left' | 'right' | 'overlay'; font?: ChartFont; format?: ChartFormat; overlay?: boolean; /** Text orientation angle in degrees (-90 to 90) */ textOrientation?: number; richText?: ChartFormatString[]; formula?: string; /** Horizontal text alignment. */ horizontalAlignment?: 'left' | 'center' | 'right'; /** Vertical text alignment. */ verticalAlignment?: 'top' | 'middle' | 'bottom'; /** Show drop shadow on title. */ showShadow?: boolean; /** Height in points (read-only, populated from render engine). */ height?: number; /** Width in points (read-only, populated from render engine). */ width?: number; /** Left position in points (read-only, populated from render engine). */ left?: number; /** Top position in points (read-only, populated from render engine). */ top?: number; } ``` ## TopBottomBy ```typescript type TopBottomBy = 'items' | 'percent' | 'sum' ``` ## TopBottomType ```typescript type TopBottomType = 'top' | 'bottom' ``` ## TotalsFunction Totals function type (matches Rust TotalsFunction). ```typescript type TotalsFunction = | 'average' | 'count' | 'countNums' | 'max' | 'min' | 'stdDev' | 'sum' | 'var' | 'custom' | 'none' ``` ## Transform3DEffect 3D transformation effect configuration. ```typescript type Transform3DEffect = { /** Rotation around X axis in degrees */ rotationX: number; /** Rotation around Y axis in degrees */ rotationY: number; /** Rotation around Z axis in degrees */ rotationZ: number; /** Perspective distance for 3D effect */ perspective: number; } ``` ## TrendlineConfig Trendline configuration (matches TrendlineData wire type) ```typescript type TrendlineConfig = { show?: boolean; type?: string; color?: string; lineWidth?: number; order?: number; period?: number; forward?: number; backward?: number; intercept?: number; displayEquation?: boolean; displayRSquared?: boolean; name?: string; lineFormat?: ChartLineFormat; label?: TrendlineLabelConfig; /** @deprecated Use displayEquation instead */ showEquation?: boolean; /** @deprecated Use displayRSquared instead */ showR2?: boolean; /** @deprecated Use forward instead */ forwardPeriod?: number; /** @deprecated Use backward instead */ backwardPeriod?: number; } ``` ## TrendlineLabelConfig Trendline label configuration. ```typescript type TrendlineLabelConfig = { text?: string; format?: ChartFormat; numberFormat?: string; } ``` ## UndoHistoryEntry An entry in the undo history. ```typescript type UndoHistoryEntry = { /** Unique identifier for this entry. */ id: string; /** Description of the operation. */ description: string; /** Timestamp of the operation (Unix ms). */ timestamp: number; } ``` ## UndoReceipt Receipt for an undo operation. ```typescript type UndoReceipt = { kind: 'undo'; success: boolean; } ``` ## UndoServiceState Undo service state ```typescript type UndoServiceState = { /** Whether undo is available */ canUndo: boolean; /** Whether redo is available */ canRedo: boolean; /** Number of items in undo stack */ undoStackSize: number; /** Number of items in redo stack */ redoStackSize: number; /** Description of next undo operation */ nextUndoDescription: string | null; /** Description of next redo operation */ nextRedoDescription: string | null; } ``` ## UndoState Full undo/redo state from the compute engine. ```typescript type UndoState = { /** Whether undo is available. */ canUndo: boolean; /** Whether redo is available. */ canRedo: boolean; /** Number of operations that can be undone. */ undoDepth: number; /** Number of operations that can be redone. */ redoDepth: number; } ``` ## UndoStateChangeEvent Undo state change event ```typescript type UndoStateChangeEvent = { /** Current state */ state: UndoServiceState; /** What triggered this change */ trigger: 'undo' | 'redo' | 'push' | 'clear' | 'external'; } ``` ## UnmergeReceipt Receipt for an unmerge mutation. ```typescript type UnmergeReceipt = { kind: 'unmerge'; range: string; } ``` ## ValidationRemoveReceipt Receipt for removing a validation rule. ```typescript type ValidationRemoveReceipt = { kind: 'validationRemove'; address: string; } ``` ## ValidationRule A data validation rule for cells. ```typescript type ValidationRule = { /** Schema ID — populated when reading, optional when creating (auto-generated if omitted) */ id?: string; /** The cell range this rule applies to in A1 notation (e.g., "A1:B5") — populated when reading */ range?: string; /** The validation type. 'none' indicates no validation rule is set. */ type: 'none' | 'list' | 'wholeNumber' | 'decimal' | 'date' | 'time' | 'textLength' | 'custom'; /** Comparison operator */ operator?: | 'equal' | 'notEqual' | 'greaterThan' | 'lessThan' | 'greaterThanOrEqual' | 'lessThanOrEqual' | 'between' | 'notBetween'; /** Primary constraint value or formula */ formula1?: string | number; /** Secondary constraint value or formula (for 'between' / 'notBetween') */ formula2?: string | number; /** Explicit list of allowed values (for 'list' type) */ values?: string[]; /** Source reference for list validation: A1 range (e.g., "=Sheet1!A1:A10") or formula (e.g., "=INDIRECT(A1)"). Prefixed with "=" for formulas. */ listSource?: string; /** Whether blank cells pass validation (default: true) */ allowBlank?: boolean; /** Whether to show a dropdown arrow for list validations */ showDropdown?: boolean; /** Whether to show an input message when the cell is selected */ showInputMessage?: boolean; /** Title for the input message */ inputTitle?: string; /** Body text for the input message */ inputMessage?: string; /** Whether to show an error alert on invalid input */ showErrorAlert?: boolean; /** Error alert style */ errorStyle?: 'stop' | 'warning' | 'information'; /** Title for the error alert */ errorTitle?: string; /** Body text for the error alert */ errorMessage?: string; } ``` ## ValidationSetReceipt Receipt for setting a validation rule. ```typescript type ValidationSetReceipt = { kind: 'validationSet'; address: string; } ``` ## ViewOptions Sheet view options (gridlines, headings). ```typescript type ViewOptions = { /** Whether gridlines are shown */ showGridlines: boolean; /** Whether row headers are shown */ showRowHeaders: boolean; /** Whether column headers are shown */ showColumnHeaders: boolean; } ``` ## ViewportBounds The visible cell range bounds for the viewport. ```typescript type ViewportBounds = { sheetId: string; startRow: number; startCol: number; endRow: number; endCol: number; } ``` ## ViewportChangeEvent Events emitted by the viewport coordinator when viewport state changes. Consumers subscribe to these events to react to data changes without polling. ```typescript type ViewportChangeEvent = | { type: 'fetch-committed' } | { type: 'cells-patched'; cells: { row: number; col: number }[] } | { type: 'dimensions-patched'; axis: 'row' | 'col' } ``` ## ViewportRegion Handle for a registered viewport region. Created by `wb.viewport.createRegion()`. The kernel tracks cell data for this region and delivers incremental updates. Dispose when the region is no longer needed (e.g., component unmount, sheet switch). Supports TC39 Explicit Resource Management: using region = wb.viewport.createRegion(sheetId, bounds); ```typescript type ViewportRegion = { /** Unique ID for this region (auto-generated). */ id: string; /** Sheet this region is tracking. */ sheetId: string; /** Update the locally-tracked visible bounds (e.g., on scroll or resize). **Important:** This updates local state only. It does NOT push bounds to the Rust compute engine. Rust-side viewport bounds (the prefetch range) are exclusively managed by the fetch manager via {@link refresh}. Pushing visible bounds here would overwrite the wider prefetch range on every scroll, causing off-screen mutations to be silently dropped. @see plans/completed/plans/fix-offscreen-mutation-display.md — Phase 5 */ updateBounds(bounds: ViewportBounds): void;; /** Request a data refresh for this region. */ refresh(scrollBehavior?: unknown): Promise;; } ``` ## ViolinConfig Violin plot configuration ```typescript type ViolinConfig = { showBox?: boolean; bandwidth?: number; side?: 'both' | 'left' | 'right'; } ``` ## VisibleRangeView The result of `getVisibleView()` — only visible (non-hidden) rows from a range. Matches the OfficeJS `RangeView` concept: a filtered view of a range that excludes hidden rows (e.g., rows hidden by AutoFilter). ```typescript type VisibleRangeView = { /** Cell values for visible rows only (2D array, same column count as input range). */ values: CellValue[][]; /** The 0-based row indices (absolute, within the sheet) of the visible rows. */ visibleRowIndices: number[]; } ``` ## WaterfallConfig Waterfall chart configuration for special bars ```typescript type WaterfallConfig = { /** Indices that are "total" bars (drawn from zero) */ totalIndices?: number[]; /** Color for positive values */ increaseColor?: string; /** Color for negative values */ decreaseColor?: string; /** Color for total bars */ totalColor?: string; } ``` ## WordArtConfig Configuration for creating new WordArt. ```typescript type WordArtConfig = { /** Text content. */ text: string; /** Preset style ID (e.g., 'fill-1', 'gradient-2'). */ presetId?: string; /** X position in pixels. */ x?: number; /** Y position in pixels. */ y?: number; /** Width in pixels. */ width?: number; /** Height in pixels. */ height?: number; /** Display name. */ name?: string; } ``` ## WordArtHandle WordArt objects are textboxes with WordArt configuration. ```typescript type WordArtHandle = { update(props: WordArtUpdates): Promise;; duplicate(offsetX?: number, offsetY?: number): Promise;; getData(): Promise;; } ``` ## WordArtUpdates Updates for existing WordArt. ```typescript type WordArtUpdates = { /** Updated text content. */ text?: string; /** Warp preset name (text geometric transformation). */ warp?: string; /** Warp adjustment values. */ warpAdjustments?: Record; /** Fill configuration. */ fill?: Record; /** Outline configuration. */ outline?: Record; /** Text effects (shadow, glow, reflection, etc.). */ effects?: Record; /** Full WordArt configuration batch update. */ config?: Record; /** Text formatting update. */ textFormat?: Record; } ``` ## WorkbookChangeRecord A single cell-level change observed by a workbook tracker. Includes sheet name. ```typescript type WorkbookChangeRecord = { /** Sheet name where the change occurred. */ sheet: string; /** Cell address in A1 notation (e.g., "B1"). */ address: string; /** 0-based row index. */ row: number; /** 0-based column index. */ col: number; /** What caused this change. */ origin: ChangeOrigin; /** Type of change. */ type: 'modified'; /** Value before the change (undefined if cell was previously empty). */ oldValue?: unknown; /** Value after the change (undefined if cell was cleared). */ newValue?: unknown; } ``` ## WorkbookChangeTracker A handle that accumulates change records across all sheets. ```typescript type WorkbookChangeTracker = { /** Drain accumulated changes since creation or last collect() call. */ collect(): WorkbookCollectResult;; /** Async version of collect() that resolves sheet names across the Rust bridge. Preferred over collect() when called from async context. Falls back to raw sheet IDs if name resolution fails. */ collectAsync(): Promise;; /** Stop tracking and release internal resources. */ close(): void;; /** Whether this tracker is still active (not closed). */ active: boolean; } ``` ## WorkbookCollectResult Result from collecting workbook-level changes. ```typescript type WorkbookCollectResult = { /** Accumulated change records. */ records: WorkbookChangeRecord[]; /** True if the tracker hit its limit and stopped accumulating. */ truncated: boolean; /** Total changes observed (may exceed records.length when truncated). */ totalObserved: number; } ``` ## WorkbookEvent Coarse workbook-level event types for `wb.on()`. These events are not sheet-scoped — they fire once for the whole workbook. ```typescript type WorkbookEvent = | 'sheetAdded' | 'sheetRemoved' | 'sheetRenamed' | 'activeSheetChanged' | 'undoStackChanged' | 'checkpointCreated' | 'namedRangeChanged' | 'scenarioChanged' | 'settingsChanged' ``` ## WorkbookProtectionOptions Workbook protection options - matches Excel behavior. Workbook protection prevents structural changes to sheets. When a workbook is protected: - Users cannot add, delete, rename, hide, unhide, or move sheets - Sheet content can still be edited (unless sheet is also protected) Plan 08: Dialogs - Task 4 (Protect Workbook Dialog) ```typescript type WorkbookProtectionOptions = { /** Protect workbook structure (prevents sheet add/delete/move/rename/hide/unhide). Default: true when protection is enabled. */ structure: boolean; } ``` ## WorkbookSettings Workbook-level settings (persisted in Yjs workbook metadata). These apply globally to the entire workbook, not per-sheet. Stream L: Settings & Toggles ```typescript type WorkbookSettings = { /** Whether horizontal scrollbar is visible (default: true) */ showHorizontalScrollbar: boolean; /** Whether vertical scrollbar is visible (default: true) */ showVerticalScrollbar: boolean; /** Whether scrollbars auto-hide when not scrolling (default: false). When true, scrollbars fade out after scroll ends and reappear on hover or scroll. Plan 09 Group 7.2: Auto-Hide Scroll Bars */ autoHideScrollBars: boolean; /** Whether the tab strip is visible (default: true) */ showTabStrip: boolean; /** Whether sheets can be reordered by dragging (default: true) */ allowSheetReorder: boolean; /** Whether the formula bar is visible (default: true) */ showFormulaBar: boolean; /** Whether to auto-fit column width on header double-click (default: true) */ autoFitOnDoubleClick: boolean; /** ID of active theme. Built-in theme IDs: 'office', 'slice', 'vapor-trail', etc. Use 'custom' to indicate a custom theme is stored in customTheme. Issue 4: Page Layout - Themes */ themeId: string; /** Override for theme fonts. When set, uses this font theme instead of the fonts from the selected theme. Built-in font theme IDs: 'office', 'arial', 'times', 'calibri', etc. undefined means use fonts from themeId. Plan 12: Fonts/Typography - Theme Font UI */ themeFontsId?: string; /** Locale/culture for number, date, and currency formatting. Uses IETF language tags: 'en-US', 'de-DE', 'ja-JP', etc. Default: 'en-US' This affects: - Decimal and thousands separators (1,234.56 vs 1.234,56) - Currency symbol position ($100 vs 100 €) - Date format patterns (MM/DD/YYYY vs DD.MM.YYYY) - Month and day name translations - AM/PM designators Stream G: Culture & Localization */ culture: string; /** Whether to show cut/copy indicator (marching ants). Default: true */ showCutCopyIndicator: boolean; /** Whether fill handle dragging is enabled. Default: true */ allowDragFill: boolean; /** Direction to move after pressing Enter. Default: 'down' */ enterKeyDirection: EnterKeyDirection; /** Whether cell drag-and-drop to move cells is enabled. Default: false (not yet implemented) */ allowCellDragDrop: boolean; /** Currently selected sheet IDs for multi-sheet operations. Default: undefined (falls back to [activeSheetId]) This is collaborative state - other users can see which sheets you have selected. Used for operations that broadcast to multiple sheets (formatting, structure changes). When multiple sheets are selected: - Formatting operations apply to all selected sheets - Structure operations (insert/delete rows/cols) apply to all selected sheets - The active sheet is always included in the selection */ selectedSheetIds?: string[]; /** Whether the workbook structure is protected. When true, prevents adding, deleting, renaming, hiding, unhiding, or moving sheets. Default: false Plan 08: Dialogs - Task 4 (Protect Workbook Dialog) */ isWorkbookProtected?: boolean; /** Hashed protection password for workbook (optional). Uses Excel-compatible XOR hash algorithm for round-trip compatibility. Empty string or undefined means no password protection. */ workbookProtectionPasswordHash?: string; /** Workbook protection options (what operations are prevented). Only relevant when isWorkbookProtected is true. If not set, defaults to DEFAULT_WORKBOOK_PROTECTION_OPTIONS. @see WorkbookProtectionOptions in protection.ts */ workbookProtectionOptions?: import('../document/protection').WorkbookProtectionOptions; /** Calculation settings including iterative calculation for circular references. If not set, defaults to DEFAULT_CALCULATION_SETTINGS. @see plans/active/excel-parity/04-EDITING-BEHAVIORS-PLAN.md - G.3 */ calculationSettings?: CalculationSettings; /** Whether the workbook uses the 1904 date system (affects all date calculations). Default: false (1900 date system). */ date1904?: boolean; /** Default table style ID for new tables created in this workbook. Can be a built-in style preset name (e.g., 'medium2', 'dark1') or a custom style ID (e.g., 'custom-abc123'). When undefined, new tables use the 'medium2' preset by default. Plan 15: Tables Excel Parity - P1-8 (Set as default style) */ defaultTableStyleId?: string; /** Whether chart data points track cell movement when cells are inserted/deleted. When true, chart data series follow their original data points even if the underlying cells shift due to row/column insertion or deletion. Default: true (matches Excel default). OfficeJS: Workbook.chartDataPointTrack */ chartDataPointTrack?: boolean; } ``` ## WorkbookSnapshot A summary snapshot of the entire workbook state. ```typescript type WorkbookSnapshot = { /** All sheets in the workbook */ sheets: SheetSnapshot[]; /** ID of the currently active sheet */ activeSheetId: string; /** Total number of sheets */ sheetCount: number; } ``` ## WorkbookTrackOptions Options for creating a workbook-level change tracker. ```typescript type WorkbookTrackOptions = { /** Filter by origin type. Omit to track all origins. */ origins?: ChangeOrigin[]; /** Max records before auto-truncation (default: 10000). */ limit?: number; } ```