import { Bounds } from '@sheetxl/utils'; import { CellCoords } from '@sheetxl/utils'; import { ChainedError } from '@sheetxl/utils'; import { CompiledModule } from '@sheetxl/scripting'; import { CompileOptions } from '@sheetxl/scripting'; import { CompileResults } from '@sheetxl/scripting'; import { CoordUtils } from '@sheetxl/utils'; import { Direction } from '@sheetxl/utils'; import { EditMode } from '@sheetxl/utils'; import { FetchArgs } from '@sheetxl/utils'; import { FormulaError } from '@sheetxl/primitives'; import { IFormulaContext } from '@sheetxl/primitives'; import { IFunction } from '@sheetxl/primitives'; import { IRange } from '@sheetxl/primitives'; import { IReferenceRange } from '@sheetxl/primitives'; import { IRichData } from '@sheetxl/primitives'; import { IRuntime } from '@sheetxl/primitives'; import { JSONSerializableAsync } from '@sheetxl/utils'; import { JSScalar } from '@sheetxl/primitives'; import { JSScalarUpdate } from '@sheetxl/primitives'; import { Point } from '@sheetxl/utils'; import { Properties } from 'csstype'; import { RangeCoords } from '@sheetxl/utils'; import { RangeOrientation } from '@sheetxl/utils'; import { Rectangle } from '@sheetxl/utils'; import { ReferenceableClipboard } from '@sheetxl/utils'; import { RunCoords } from '@sheetxl/utils'; import { Scalar } from '@sheetxl/primitives'; import { ScalarType } from '@sheetxl/primitives'; import { SelectionCoords } from '@sheetxl/utils'; import { Size } from '@sheetxl/utils'; import { TextAlign } from 'csstype'; import { TopLeft } from '@sheetxl/utils'; import { UndoManager } from '@sheetxl/utils'; /** * Abstract implement of {@link IAnchorItem}. */ declare abstract class AbstractAnchored implements IAnchored, IListener.ISource { protected _emitter: ListenerEmitter; protected _options: IAnchored.ConstructorOptions; private _transactions; private _transactionsRemoveListener; private _closed; constructor(options: IAnchored.ConstructorOptions); /* Excluded from this release type: _getEmitter */ /** {@inheritDoc IAnchored.delete} */ delete(options?: ITransaction.OperationOptions): void; /** {@inheritDoc IAnchored.getAnchorCoords} */ getAnchorCoords(): IRange.Coords; /** {@inheritDoc IAnchored.getAnchorType} */ getAnchorType(): IAnchored.Type; /** {@inheritDoc IAnchored.isProtected} */ isProtected(): boolean; /** {@inheritDoc ITransaction.ITransactional.beginCommit} */ beginCommit(options?: string | ITransaction.OperationOptions): ITransaction; protected _getState(): Readonly; protected _beginCommit(options?: string | ITransaction.OperationOptions): ITransaction; protected _getTransactions(): ITransaction.IStore; protected _updateState(updateState?: Partial, //(prevState: STATE) => STATE, options?: ITransaction.OperationOptions, events?: (keyof EVENTS)[]): this; /* Excluded from this release type: _processContainerShift */ /* Excluded from this release type: _processBeforeCommitStart */ /* Excluded from this release type: _processStateChange */ /* Excluded from this release type: _processRestoreOrRevert */ /* Excluded from this release type: _processAnchorCoords */ /* Excluded from this release type: _processContainerLayout */ /* Excluded from this release type: _getDescription */ /* Excluded from this release type: _delete */ /* Excluded from this release type: _processContainerDelete */ /* Excluded from this release type: _processDelete */ /* Excluded from this release type: _processContainerProtection */ /** {@inheritDoc IListener.ISource.addListeners} */ addListeners(listeners: IListener.Callbacks, options?: IListener.Options): IListener.Remove; /** {@inheritDoc IAnchored.isClosed} */ isClosed(): boolean; /* Excluded from this release type: _processClose */ /** {@inheritDoc IAnchored.close} */ close(): void; /** {@inheritDoc IAnchored.isIAnchored} */ get isIAnchored(): true; } /* Excluded declaration from this release type: AbstractAnchored */ /** * Abstract implement of `IModel`. */ declare abstract class AbstractModel implements IModel { protected _emitter: ListenerEmitter; protected _options: IModel.ConstructorOptions; protected _transactions: ITransaction.IStore; protected _transactionsRemoveListener: IListener.Remove; protected _closed: boolean; constructor(options: IModel.ConstructorOptions); /* Excluded from this release type: _fromJSON */ isReadOnly(): boolean; isDeleted(): boolean; getType(): string; get isIModel(): true; /* Excluded from this release type: _processTransactionDone */ /* Excluded from this release type: _getDescription */ /* Excluded from this release type: _getState */ /* Excluded from this release type: _beginCommit */ /* Excluded from this release type: _getTransactions */ /* Excluded from this release type: _updateState */ /* Excluded from this release type: _getEmitter */ /* Excluded from this release type: _processInit */ /* Excluded from this release type: _processStateChange */ /* Excluded from this release type: _processRestoreOrRevert */ delete(options?: ITransaction.OperationOptions): void; /* Excluded from this release type: _delete */ /* Excluded from this release type: _processOnContainerDeleted */ /* Excluded from this release type: _processDelete */ /* Excluded from this release type: _processOnContainerReadOnly */ /** {@inheritDoc IListener.ISource.addListeners} */ addListeners(listeners: IListener.Callbacks, options?: IListener.Options): IListener.Remove; /** {@inheritDoc ITransaction.ITransactional.beginCommit} */ beginCommit(options?: string | ITransaction.OperationOptions): ITransaction; /** {@inheritDoc ITransaction.ITransactional.doBatch} */ doBatch(callback: (commit: ITransaction.ICommit) => Promise | R, options?: string | ITransaction.OperationOptions): Promise | R; /** {@inheritDoc ITransaction.ITransactional.isClosed} */ isClosed(): boolean; /** {@inheritDoc ITransaction.ITransactional.close} */ close(): void; } /** * Interfaces for creating `IAnchored`. * * @see * ### **Interface** * * {@link AbstractModel} */ declare namespace AbstractModel { interface State { isDeleted: boolean; } interface CommitView { } } declare abstract class AbstractTransaction implements ITransaction { protected _states: Map; protected _description: string; protected _meta: Record; protected _children: Set; protected _depth: number; protected _descriptions: string[]; protected _container: CommitContainer; protected _closed: boolean; constructor(container: CommitContainer, options: ITransaction.StoreOperationOptions); /** {@inheritDoc ITransaction.getView} */ getView(): Record; /** {@inheritDoc ITransaction.getState} */ abstract getState(model: any): STATE; /** {@inheritDoc ITransaction.rollback} */ abstract rollback(): ITransaction; /** {@inheritDoc ITransaction.getParent} */ abstract getParent(): ITransaction; /** {@inheritDoc ITransaction.getId} */ abstract getId(): string; /** {@inheritDoc ITransaction.getDepth} */ getDepth(): number; /** {@inheritDoc ITransaction.getDescription} */ getDescription(): string; /** {@inheritDoc ITransaction.getStates} */ getStates(): Map; /** {@inheritDoc ITransaction.beginTransaction} */ beginTransaction(options?: ITransaction.StoreOperationOptions, onClose?: ITransaction.CloseCallback): ITransaction; /** {@inheritDoc ITransaction.updateState} */ updateState(model: any, state: Readonly> | ((prev: Readonly) => Readonly)): STATE; /** {@inheritDoc ITransaction.commit} */ commit(options?: ITransaction.StoreOperationOptions): ITransaction; /** {@inheritDoc ITransaction.isClose} */ isClose(): boolean; protected _ensureOpen(): void; _removeChild(child: AbstractTransaction): void; protected _mergeStates(statesChild: Map): Map; } /** * Collection of functions used for parsing Address string. * * Needed for OOXML import. * @hidden */ export declare namespace AddressUtils { const fastStringToCol: (address: string) => number; const fastStringToCell: (address: string, reuse?: IRange.CellCoords) => IRange.CellCoords; const fastStringToRange: (address: string, _reuse?: IRange.Coords) => IRange.Coords; const rangeToString: RangeToString; const cellToString: CellToString; const normalizeA1ToR1C1: (formula: string, rowIndex: number, colIndex: number, tokens?: (string | IRange.FixableCellCoords)[]) => string; const resolveRelativeToA1: (tokens: (string | IRange.CellCoords)[], rowIndex: number, colIndex: number) => string; } declare const angleToPoints: (angleDeg: number, rectBounds: Bounds) => { x1: number; y1: number; x2: number; y2: number; }; declare namespace AutoFill_2 { /** * DateFill implements IAutoFill.Filler to work with Dates. */ class Date implements IAutoFill.Filler { private _options; constructor(options?: DateOptions); /** * Returns `true` if the value is a valid `Date`. * @see * {@link IAutoFill.Filler.canFill} */ canFill(value: any, _prev: JavaScriptDate): boolean; /** {@inheritDoc IAutoFill.Filler.createFillAt} */ createFillAt(values: JavaScriptDate[], options?: DateOptions): IAutoFill.FillAt; } /** * Adds additional fill options for Dates. */ interface DateOptions extends IAutoFill.Options { /** * If not provided the filler will attempt to determine. * @defaultValue `The largest date unit found or day if one is not found.` * // TODO - This doesn't support 'WeekDay' */ unit?: DateUnit; } /** * LinearFill implements IAutoFill.Filler to work with numbers. * TODO - implements stepValue/stepTo */ class Linear implements IAutoFill.Filler { private _options; constructor(options?: IAutoFill.Options); /** * Returns `true` if the value is a valid number. * @see * {@link IAutoFill.Filler.canFill} */ canFill(value: any, _prev: number): boolean; /** {@inheritDoc IAutoFill.Filler.createFillAt} */ createFillAt(values: readonly number[], options?: IAutoFill.Options): IAutoFill.FillAt | null; } /** * Ordinal implements IAutoFill.Filler to handles Strings that have a Integer value. */ class Ordinal implements IAutoFill.Filler { private _template; /** * Returns `true` if the value is a String that contains an Integer. * @see * {@link IAutoFill.Filler.canFill} */ canFill(value: any, prev: string): boolean; /** {@inheritDoc IAutoFill.Filler.createFillAt} */ createFillAt(values: readonly string[], options?: IAutoFill.Options): IAutoFill.FillAt; } /** * The Copy Filler 'copies' values in a repeating pattern. * * @remarks * This the default Filler when non is specified or no filler accepts the values * being provided. */ class Copy implements IAutoFill.Filler { /** * Always returns `true`. * @see * {@link IAutoFill.Filler.canFill} */ canFill(_value: any, _prev: any): boolean; /** {@inheritDoc IAutoFill.Filler.createFillAt} */ createFillAt(values: readonly number[], _options?: IAutoFill.Options): IAutoFill.FillAt; } /** * ListFill implements IAutoFill.Filler to work with lists. */ interface ListOptions extends IAutoFill.Options { /** * A custom set of lists */ customLists?: readonly string[][]; } /** * The List Filler uses a list of strings in a repeating pattern. * * @remarks * This the default Filler when non is specified or no filler accepts the values * being provided. */ class List implements IAutoFill.Filler { private _lists; private _map; constructor(options?: ListOptions); /** * Always returns `true`. * @see * {@link IAutoFill.Filler.canFill} */ canFill(value: string, _prev: any): boolean; /** {@inheritDoc IAutoFill.Filler.createFillAt} */ createFillAt(values: readonly string[], options?: IAutoFill.Options): IAutoFill.FillAt; } /** * A specialized `Filler` that aggregates multiple `Filler` instances to handle various data types * during autofill operations. * * It delegates the filling process to the first `Filler` in its collection whose `canFill` method * returns `true` for the given value, enabling seamless autofill functionality for mixed data types within a range. * * @remarks * This filler will also handle blanks. */ class Composite implements IAutoFill.Filler { private _fillers; constructor(fillers: IAutoFill.Filler | IAutoFill.Filler[]); /** * Always returns `true`. * @see * {@link IAutoFill.Filler.canFill} */ canFill(_value: T, _prev: T): boolean; /** {@inheritDoc IAutoFill.Filler.createFillAt} */ createFillAt(values: readonly T[], options?: IAutoFill.Options): IAutoFill.FillAt; } /** * Available Builtin Types. */ const Types: { /** * Default Fills. * This attempts to fill use `Dates`, `Linear`, `Ordinal`, then `List`. */ readonly Series: Composite; /** * Fills using individual days. */ readonly DateDays: Date; /** * Fills using months. */ readonly DateMonths: Date; /** * Fills using years. */ readonly DateYears: Date; /** * Fills with a repeating values. */ readonly Copy: Copy; }; /** * Simple methods that builds an array from a Filler. */ const fillTo: (filler: IAutoFill.Filler, values: T[], to: number, options?: IAutoFill.Options) => T[]; } export { AutoFill_2 as AutoFill } declare enum AutoNumberingSchemeType { /** * Lowercase alphabetic character enclosed in parentheses. Example: (a), (b), * (c), ... */ alphaLcParenBoth = 0, /** * Uppercase alphabetic character enclosed in parentheses. Example: (A), (B), * (C), ... */ alphaUcParenBoth = 1, /** * Lowercase alphabetic character followed by a closing parenthesis. Example: * a), b), c), ... */ alphaLcParenRight = 2, /** * Uppercase alphabetic character followed by a closing parenthesis. Example: * A), B), C), ... */ alphaUcParenRight = 3, /** * Lowercase Latin character followed by a period. Example: a., b., c., ... */ alphaLcPeriod = 4, /** * Uppercase Latin character followed by a period. Example: A., B., C., ... */ alphaUcPeriod = 5, /** * Arabic numeral enclosed in parentheses. Example: (1), (2), (3), ... */ arabicParenBoth = 6, /** * Arabic numeral followed by a closing parenthesis. Example: 1), 2), 3), ... */ arabicParenRight = 7, /** * Arabic numeral followed by a period. Example: 1., 2., 3., ... */ arabicPeriod = 8, /** * Arabic numeral. Example: 1, 2, 3, ... */ arabicPlain = 9, /** * Lowercase Roman numeral enclosed in parentheses. Example: (i), (ii), (iii), * ... */ romanLcParenBoth = 10, /** * Uppercase Roman numeral enclosed in parentheses. Example: (I), (II), (III), * ... */ romanUcParenBoth = 11, /** * Lowercase Roman numeral followed by a closing parenthesis. Example: i), ii), * iii), ... */ romanLcParenRight = 12, /** * Uppercase Roman numeral followed by a closing parenthesis. Example: I), II), * III), .... */ romanUcParenRight = 13, /** * Lowercase Roman numeral followed by a period. Example: i., ii., iii., ... */ romanLcPeriod = 14, /** * Uppercase Roman numeral followed by a period. Example: I., II., III., ... */ romanUcPeriod = 15, /** * Double byte circle numbers. */ circleNumDbPlain = 16, /** * Wingdings black circle numbers. */ circleNumWdBlackPlain = 17, /** * Wingdings white circle numbers. */ circleNumWdWhitePlain = 18, /** * Double-byte Arabic numbers with double-byte period. */ arabicDbPeriod = 19, /** * Double-byte Arabic numbers. */ arabicDbPlain = 20, /** * Simplified Chinese with single-byte period. */ ea1ChsPeriod = 21, /** * Simplified Chinese. */ ea1ChsPlain = 22, /** * Traditional Chinese with single-byte period. */ ea1ChtPeriod = 23, /** * Traditional Chinese. */ ea1ChtPlain = 24, /** * Japanese with double-byte period. */ ea1JpnChsDbPeriod = 25, /** * Japanese/Korean. */ ea1JpnKorPlain = 26, /** * Japanese/Korean with single-byte period. */ ea1JpnKorPeriod = 27, /** * Bidi Arabic 1 (AraAlpha) with ANSI minus symbol. */ arabic1Minus = 28, /** * Bidi Arabic 2 (AraAbjad) with ANSI minus symbol. */ arabic2Minus = 29, /** * Bidi Hebrew 2 with ANSI minus symbol. */ hebrew2Minus = 30, /** * Thai alphabetic character followed by a period. */ thaiAlphaPeriod = 31, /** * Thai alphabetic character followed by a closing parenthesis. */ thaiAlphaParenRight = 32, /** * Thai alphabetic character enclosed by parentheses. */ thaiAlphaParenBoth = 33, /** * Thai numeral followed by a period. */ thaiNumPeriod = 34, /** * Thai numeral followed by a closing parenthesis. */ thaiNumParenRight = 35, /** * Thai numeral enclosed in parentheses. */ thaiNumParenBoth = 36, /** * Hindi alphabetic character followed by a period. */ hindiAlphaPeriod = 37, /** * Hindi numeric character followed by a period. */ hindiNumPeriod = 38, /** * Hindi numeric character followed by a closing parenthesis. */ hindiNumParenRight = 39, /** * Hindi alphabetic character followed by a period. */ hindiAlpha1Period = 40 } /** * We need to keep track of before/after for the undo stack when not part of the transaction. */ declare interface BeforeAfterRange { beforeState: ICellRangesListenerEntry; afterState: ICellRangesListenerEntry; } /** * Points are return tl, tr, br, bl * * @param bounds {@link Bounds} * @returns A array of points [tl, tr, br, bl] */ declare const boundsToPoints: (bounds: Bounds) => Point[]; /** * The build date of the SDK. */ export declare const BUILD_DATE: string; declare interface CacheSearchRunData { runs: readonly ITypes.RunCoordValue[]; run: ITypes.RunCoordValue; index: number; } declare interface CalcNode { block: FormulaBlockEntry; colIndex: number; rowIndex: number; cycleId: number; markId: number; inDegree: number; dependents: any[]; inputs: any[]; precedents: (PrecedentCalcCache | FormulaError.Known)[]; dynamic: any[]; cachedValue: any; removed: boolean; /** * Indicates if the pending is in the pending spatial (to avoid lookup) */ pending: boolean; /** * Indicates the pending is waiting on a precedent to resolve. */ pendingPrecedents: boolean; /** * Indicates the pending is full filled and waiting for the next cycle to resolve. */ pendingResolved: boolean; pendingPromise: Promise | null; /** * The state is a bit mask with transient states. * The CalcNode is reused across cycles and cloned records for performance. * To ensure that it is correct the cycleId id must be consulted. */ state: number; error: FormulaError.Known; } /** * Implementation for {@link ICalculation}. */ export declare class Calculation extends AbstractModel implements ICalculation { protected _context: CalculationContext; protected _scope: ICalcGraphScope; protected _graphsCalcing: Map; protected _graphsAll: Map; protected _functions: IFunctionCollection; protected _runtime: IRuntime; protected _formulaParser: IFormulaParser; protected _emitter: ListenerEmitter; protected _status: ICalculation.Status; protected _statusTransition: Promise | null; constructor(options?: Calculation.ConstructorOptions); protected _getContext(): CalculationContext; protected _getScope(): ICalcGraphScope; protected _getCalcingGraphs(): Map; protected _getAllGraphs(): Map; /** @inheritdoc ICalculation.start */ start(): Promise; protected _createGraph(options: ICalcGraph.ConstructorOptions): ICalcGraph; /** @inheritdoc ICalculation.stop */ stop(): Promise; /** @inheritdoc ICalculation.getStatus */ getStatus(): ICalculation.Status; /** @inheritdoc ICalculation.ready */ ready(options?: ICalculation.CalculateOptions): Promise; /** @inheritdoc ICalculation.getFunctions */ getFunctions(): IFunctionCollection; /** @inheritdoc IFormulaContext.getRuntime */ getRuntime(): IRuntime; protected _checkReady(): void; protected _statusMessage(): string; get [Symbol.toStringTag](): string; toString(): string; } /** * Interfaces for creating `Calculation` items. * * @see * ### **Interface** * * {@link Calculation} */ export declare namespace Calculation { /** * Options for creating an ICalculation. */ export interface ConstructorOptions extends ICalculation.ConstructorOptions, IModel.ConstructorOptions { } } declare class CalculationContext implements IFormulaContext { protected _calcScope: ICalcGraphScope; protected _instanceScope: any; protected _options: ICalculation.ConstructorOptions; protected _runtime: IRuntime; protected _builtInFunctions: ReadonlyMap; protected _getFunction: (name: string) => IFunction; protected _isColumn: boolean; constructor(options?: ICalculation.ConstructorOptions, isColumn?: boolean); /** @hidden */ _setInstanceScope(instanceScope: any): void; /** @hidden */ _initialize(): Promise<{ builtInFunctions: ReadonlyMap; calcScope?: ICalcGraphScope; }>; /** * Returns a builtin map of built-in functions. */ getBuiltInFunctions(): ReadonlyMap; /** @inheritdoc IFormulaContext.getFunction */ getFunction(name: string): IFunction; /** @inheritdoc IFormulaContext.getNumberFormat */ getNumberFormat(formatText: string, value: Scalar): string; /** @inheritdoc IFormulaContext.getEntireCoords */ getEntireCoords(): IRange.Coords; /** @inheritdoc IFormulaContext.getFormulaAt */ getFormulaAt(row: number, column: number): string | null; /** @inheritdoc IFormulaContext.markVolatile */ markVolatile(): void; /** @inheritdoc IFormulaContext.formatResults */ formatResults(numFmt: string): void; /** @inheritdoc IFormulaContext.getSheetIndex */ getSheetIndex(sheetName?: string): number; /** @inheritdoc IFormulaContext.getSheetCount */ getSheetCount(): number; /** @inheritdoc IFormulaContext.isValidDate */ isValidDate(value: any): boolean; /** @inheritdoc IFormulaContext.fromOADate */ fromOADate(oaDate: number): Date; /** @inheritdoc IFormulaContext.toOADate */ toOADate(date: Date): number; protected _fromTuples(boundedTuples: Tuple.BoundedTuples, type?: ScalarType, isLiteral?: boolean): IRange; /** @inheritdoc IFormulaContext.getValueAt */ getValueAt(rowIndex: number, colIndex: number): Scalar | null; /** @inheritdoc IFormulaContext.getRange */ getSpillAt(rowIndex: number, colIndex: number): IReferenceRange | null; /** @inheritdoc IFormulaContext.getRange */ getRange(value: Scalar | Scalar[][], isLiteral?: boolean): IRange; /** @inheritdoc IFormulaContext.getPosition */ getPosition(): IRange.CellCoords; /** @inheritdoc IFormulaContext.getReference */ getReference(coords: IRange.Coords | string, r1c1?: boolean): IReferenceRange; /** @inheritdoc IFormulaContext.getAddress */ getAddress(coords?: Readonly, r1c1?: boolean): string; /** @inheritdoc IFormulaContext.parseAsDateTime */ parseAsDateTime(text: string, requireDate?: boolean): number | null; /** @inheritdoc IFormulaContext.getRuntime */ getRuntime(): IRuntime; get [Symbol.toStringTag](): string; toString(): string; } /** * Converts a camelCase string to snake_case. * * @param str The camelCase string to convert. * @returns The string converted to snake_case. * * @example * ```ts * camelToSnake('camelCaseString'); // Returns 'camel_case_string' * ``` */ declare const camelToSnake: (str: string) => string; /** * Capitalizes the first character of a string and optionally lowercases the rest of the string. * * @param str The input string to be processed. * @param lowerCaseRest A boolean flag indicating whether to convert the rest of the string to lowercase. * If `true`, the remaining characters (after the first) will be converted to lowercase. * If `false`, the remaining characters will remain unchanged. * * @returns A new string with the first character capitalized and the rest lowercased if the `lowerCaseRest` flag is `true`. * If the `lowerCaseRest` flag is `false`, only the first character is capitalized, and the rest of the string remains unchanged. * * @example * ``` * capitalize("hello"); // Returns "Hello" * capitalize("hello", true); // Returns "Hello" * capitalize("HELLO", true); // Returns "Hello" * capitalize("123abc", true); // Returns "123abc" * capitalize("", true); // Returns "" * ``` */ declare const capitalize: (str: string, lowerCaseRest?: boolean) => string; /** * Note - By using optional keys as a way to detect default values we are creating mono polymorphic objects. (perform issue in V8). * Revisit and store all keys as a single type. * 1. Create a 'default' state. We will need an isEmpty method to compare all value for pruning. (Probably just ) * 2. Only save values that are different than the default state */ declare interface CellHeaderState { sz?: number; csz?: boolean; h?: boolean; s?: IStyle; cs?: boolean; } declare namespace CellState { /* Excluded from this release type: TypeAndValue */ /** * Entries iterators are arrays of fixed length 5. */ type Entry = [ coords: IRange.CellCoords, v: Scalar, rs: RangeState.Intersection, prev: IRange.CellCoords, next: IRange.CellCoords ]; /** * Shorthand type. */ type IteratorResult = WellKnownIteratorResult; /** * Shorthand type. */ type Iterator = WellKnownIterator; /* Excluded from this release type: IteratorOptions */ } declare interface CellStyleUpdater { (update: IStyle.Update, options?: IStyle.UpdateOptions, range?: IRange.Coords): IStyle; } declare type CellToString = (cell: C) => string; /** * Return the absolute center of the bounds. */ declare const centerPoint: (bounds: Bounds) => Point; /** * Trims a string to a specified maximum length and adds an ellipsis (`…`) if the string exceeds the limit. * * @param str The string to trim. * @param maxLength The maximum length of the string before truncation (default is 36). * @returns The truncated string with an ellipsis if it exceeds the specified length. * * @example * ```ts * clampString('This is a long string', 10); // Returns 'This is a …' * ``` */ declare const clampString: (str: string, maxLength?: number) => string; /** * Takes an an inner un-rotated dimension and an outer un-rotated dimension and then will return * an un-rotated rectangle that if rotated will fit inside the outer rectangle. */ declare const clipToOuterRect: (dimInner: Size, dimOuter: Size, rotation?: number) => Size; /** * Capabilities for working with {@link IColor | colors}. * * Advanced color customization and compatibility with CSS and Office color schemes. * * Key features include: * - Accessing a collection of built-in colors (Named, Scheme, Index). * - Creating customized colors with color adjustments. * - Defining and and converting between different color models (RGB, HEX, HSL). * * @see * {@link IColor} */ export declare class Color implements IColor { private _private; constructor(value: string | IColor | IColor.Definition, schemeLookup?: IColor.SchemeLookup, indexedLookup?: IColor.IndexedLookup, last?: ColorSpace.RGBA); private _parse; private _forceDark; private _resolve; /** * @hidden * TODO - Rationalize this. Do we want a constructor a static parse? */ static parse(input: string | IColor, schemeLookup?: IColor.SchemeLookup, indexedLookup?: IColor.IndexedLookup, last?: ColorSpace.RGBA): IColor | null; /** * Returns the default color scheme lookup that Colors will use if none is provided. */ static getDefaultSchemeLookup(): IColor.SchemeLookup; /** {@inheritDoc IColor.isEqual} */ isEqual(other: any): boolean; /** {@inheritDoc IColor.getVal} */ getVal(): string; /** {@inheritDoc IColor.getAdjustments} */ getAdjustments(): readonly IColor.Adjustment[]; /** {@inheritDoc IColor.adjust} */ adjust(adjustments: IColor.Adjustment[]): IColor; /** {@inheritDoc IColor.getType} */ getType(): IColor.Type; /** {@inheritDoc IColor.toCSS} */ toCSS(darkMode?: boolean, alpha?: boolean): string; /** {@inheritDoc IColor.toRGBA} */ toRGBA(darkMode?: boolean): IColor.ISpace.RGBA; /** {@inheritDoc IColor.toHSLA} */ toHSLA(darkMode?: boolean): IColor.ISpace.HSLA; /** {@inheritDoc IColor.toHex} */ toHex(darkMode?: boolean): IColor.ISpace.HEX; /** {@inheritDoc IColor.toBlackOrWhite} */ toBlackOrWhite(darkMode?: boolean, threshold?: number): IColor; get [Symbol.toStringTag](): string; /** {@inheritDoc IColor.toString} */ toString(): string; /** {@inheritDoc IColor.isIColor} */ get isIColor(): true; } /** * Color definitions available in various ColorSpaces. */ declare namespace ColorSpace { /** * A color in the Red, Green, Blue color space. */ class RGBA { protected _private: { red: number; green: number; blue: number; alpha: number; }; constructor(red: number, green: number, blue: number, alpha?: number); get red(): number; get green(): number; get blue(): number; get alpha(): number; toString(alpha?: boolean): string; isEqual(other: ColorSpace.RGBA): boolean; isAlmostEqual(other: ColorSpace.RGBA): boolean; } /** * A color in the Hue, Saturation, Luminosity color space. */ class HSLA { private _private; constructor(hue: number, sat: number, lum: number, alpha: number); get hue(): number; get sat(): number; get lum(): number; get alpha(): number; toString(alpha?: boolean): string; isEqual(other: ColorSpace.HSLA): boolean; isAlmostEqual(other: ColorSpace.HSLA): boolean; } /** * A color (Red, Green, Blue) encoded in hexadecimal. */ class HEX extends ColorSpace.RGBA { toString(alpha?: boolean): string; } } declare interface CommitContainer { record: CommitRecord; commit: ITransaction.ICommit; } declare interface CommitEvents { address?: Map; data?: IRange.Coords[]; dataListeners?: Map; } declare interface CommitRecord { id?: string; description?: string; meta?: Record; timestamp: number; author?: any; states?: Map; operation?: ITransaction.Operation; viewBefore?: Record; viewAfter?: Record; previousId?: string; version: number; } declare interface CommitView extends AbstractModel.CommitView { } /* Excluded from this release type: CommitView_2 */ declare interface CommitView_3 { initial?: boolean; view?: ISheetView; selection?: Partial; selectOptions?: boolean | ICellRange.SelectOptions; movableSelection?: readonly IMovable[]; ranges?: readonly IRange.FixableCoords[]; events?: CommitEvents; formulas?: readonly IRange.FixableCoords[]; /** * Special case for range listeners that monitored a remove. */ merges?: readonly IRange.FixableCoords[]; listeners?: Map; /** If `true` then don't do protection check. (For example load or range listeners) */ skipProtectionCheck?: boolean; /** * We update values (cache, potentially styling, as a result of calculations) */ calculationSideEffect?: boolean; } declare function concatModifiedRuns(parts: ModifiedRuns): ITypes.RunCoordValue[]; declare class ConditionalEntry implements IProperties.ICellRanged, ISpatialMap.IUpdatableEntry { protected _c: IRange.Coords; protected _m: IConditionalFormat; constructor(coords: IRange.Coords, model: IConditionalFormat); getModel(): IConditionalFormat; /** {@inheritDoc IProperties.ICellRanged.getCoords} */ getCoords(): IRange.Coords; /** {@inheritDoc IProperties.ICellRanged.getPropertiesAt} */ getPropertiesAt(rowIndex: number, colIndex: number, value: Scalar): Readonly; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getSplit} */ getSplit(coords: readonly [IRange.Coords, IRange.Coords]): [this, this] | undefined; } /** * Used for identifying contiguously filled ranges. */ declare class ContentfulEntry { private _c; private _o; constructor(coords: IRange.Coords, orientation: IRange.Orientation); getCoords(): IRange.Coords; getOrientation(): IRange.Orientation; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getShifted} */ getShifted(options: ISpatialMap.ShiftDetails): ISpatialMap.Entry; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getMerged} */ getMerged(_other: this, coords: IRange.Coords, _orientation: IRange.Orientation): this; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getSplit} */ getSplit(coords: [IRange.Coords, IRange.Coords], _orientation: IRange.Orientation): [this, this] | undefined; getState(): IRange.Coords; } /** * Counts the number of decimal places in a numeric string. * * @param input The string representation of a number. * @returns The number of decimal places. Returns 0 if there are no decimal places. * * @example * ```ts * countDecimals('123.456'); // Returns 3 * countDecimals('123'); // Returns 0 * ``` */ declare const countDecimals: (input: string) => number; /* Excluded from this release type: CreateCellHeaderCallback */ /** * Create an invalid range. */ declare function createRangeInvalidRef(header: ISheetHeader): ICellHeaderRange; /** * Create runs from selection. */ declare const createRunsFromSelection: (header: ISheetHeader, selection: IRangeSelection.Coords, maxRange: IRange.Coords) => ITypes.RunCoordValue[]; declare const createSearchRunCache: (runs: readonly ITypes.RunCoordValue[]) => CacheSearchRunData; declare function cullRuns(runs: ITypes.RunCoordValue[], options?: CullRunsOptions): ModifiedRuns; declare interface CullRunsOptions { startOffset?: number; endOffset?: number; /** * Used to determine if a value should removed. If data is null or undefined it will also be removed. * By default an empty object will not be. */ cull?(value: T, min: number, max: number): boolean; } declare const DateUnit: { readonly Day: "d"; readonly Month: "m"; readonly Year: "y"; }; declare type DateUnit = typeof DateUnit[keyof typeof DateUnit]; export declare namespace DateUtils { export { nowWithPrecision } } declare const deepCull: (value: any, _min: number, _max: number) => boolean; declare const deepUpdate: (prevValue: any | null, newValue: any | null) => any | null; /** * A list of font sizes for showing in drop downs. */ declare const DefaultFontSizes: readonly number[]; declare class DefaultProtection implements IProtection { protected _emitter: ListenerEmitter; protected _isPaused: boolean; protected _password: Partial; protected _identities: IProtection.IdentityProvider[]; protected _properties: Partial

; protected _isReadOnly: boolean; constructor(json?: J, isReadOnly?: boolean); /** {@inheritDoc IProtection.lock} */ lock(properties?: Partial

, password?: string, algorithm?: string, spinCount?: number): Promise>; /** {@inheritDoc IProtection.unlock} */ unlock(password?: string): Promise>; /** {@inheritDoc IProtection.checkPassword} */ checkPassword(password?: string): Promise; /** {@inheritDoc IProtection.hasPassword} */ hasPassword(): boolean; /** {@inheritDoc IProtection.pause} */ pause(password?: string): Promise>; /** {@inheritDoc IProtection.resume} */ resume(): IProtection; /** {@inheritDoc IProtection.isPaused} */ isPaused(): boolean; /** {@inheritDoc IProtection.isLocked} */ isLocked(): boolean; /** {@inheritDoc IProtection.isReadOnly} */ isReadOnly(): boolean; protected _validatePassword(password?: string): Promise; getProperties(): Partial

; protected _isPropertyAllowed(property: keyof P): boolean; protected _updateProperties(properties: IProtection.Properties): void; protected _clearProperties(): void; /** {@inheritDoc IListener.ISource.addListeners} */ addListeners(listeners: IProtection.IListeners, options?: IListener.Options): IListener.Remove; fromJSON(json: J): void; protected _fromJSON(_json: J | null): void; protected _toJSON(json: Partial): Partial; /** {@inheritDoc IWorkbookProtection.toJSON} */ toJSON(): J; } declare const DefaultUnQuoteRegEx: RegExp; declare interface Entry { remove?: IListener.Remove; listeners: IListener.Callbacks; } declare type EntrySet = Set>; /** * Iterate over a collection of overlapping RangeCoord. * * This will iterator over CellCoords or RangeCoords. */ declare type ESIterator = Iterator; /** * Implements {@link ReferenceableClipboard.ReferenceItem} by creating a {@link ICellRange.ISnapshot} from * {@link ReferenceableClipboard.NativeItems}. * * @remarks * **IMPORTANT** Before this api can be used the async {@link parse} methods needs to be called and resolved. * @see * {@link parse} */ export declare class ExternalRangeClipboardItem implements ReferenceableClipboard.ReferenceItem { private _native; private _markOptions; private _styles; private _isDate1904; private _snapshot; private _parsed; constructor(native: ReferenceableClipboard.NativeItems, markOptions?: ICellRange.CopyOptions, styles?: IStyleCollection, date1904?: boolean); getItemType(): string; isCut(): boolean; toText(): string; toHtml(): string; toImage(): Blob; getItem(): ICellRange.ISnapshot; /** * Required to be called before getItem(). * @remarks * This is required because the ExternalClipboard lazy loads the parsing library. */ parse(): Promise; get isClipboardItem(): true; } /** * Tries to find a font that match the fontName exactly. If this is not found then it will use the fallback * options if provided. If there is no font and no font fallback it will return null. * @param fontName The font name to find * @returns The FontHandle */ declare const findBestMatch: (fontName: string, options?: FindBestMatchOptions) => FontHandle; declare interface FindBestMatchOptions { /** * Defaults to false */ bold?: boolean; /** * Defaults to false */ italic?: boolean; /** * A list of font names or generic font family */ fallbacks?: string[]; panose?: string; } /** * These assume a results from {@link indexHeaderSizes} are used. No error handling is performed. * sizes.length > 0. All values must be contiguous. offset must be >= 0 && offset <= size[size.length].maxOffset. * @remarks * If the current index is hidden it will return the offset before the value * @param sizes * @param offset * @returns the index for the given offset. */ declare const findIndex: (sizes: RunningHeaderSize[], offset: number, defaultSize: number) => number; declare const findIntersectMath: (p1: Point, p2: Point, min: number, max: number) => { min: number; max: number; }; /** * Searches an array of numbers for the next value. */ declare const findNextFontSize: (size: number, increase?: boolean, steps?: readonly number[]) => number; /** * Looks for a run going in a certain direction. If there isn't a run for this it will look for the next * run. If you only want the run if it is found then use {@link findRun}. * * @param runs An array of Run or RunCoords. * @param index The index that will be >= min && <= max. * @param findGreater - *`default`* `true` If true will search greater if false lesser. * @returns The index for the next run or -1 if no run was found. */ declare const findNextRunOffset: (runs: ITypes.RunCoordValue[], index: number, findGreater?: boolean) => number; /** * These assume a results from {@link indexHeaderSizes} is used. No error handling is performed. * All size runs must be contiguous. * @param sizes * @param index * @returns The offset for the given index. */ declare const findOffset: (sizes: RunningHeaderSize[], index: number, defaultSize: number) => number; declare const findRun: (runs: ITypes.RunCoordValue[], index: number) => ITypes.RunCoordValue | null; /** * Finds the visibleIndex for a given absolute index. * Returns a RunCoords. This can be used to determine if an index is hidden * If it's hidden it will return a range of 1 with a value before the offset and after. * If it's visible then it will return a range of 0 with the min and max that exactly match the offset. * @remarks * If this is on the edge of the bounds this will return a +/- 1 the max bounds. * @param index The absolute index */ declare const findRunningHiddenRuns: (sizes: RunningHeaderSize[], index: number, maxIndex?: number) => RunCoords; /** * Finds the total length between to points account for hidden spans. * No validation is done. */ declare const findRunningSpanLength: (runs: RunningHeaderSize[], from: number, to: number) => number; /** * Will try to find a valid text value from a template by incrementing a last number. * * @param template The string to use for a baseline for generating new text values. * @param isValidName A callback for validating the current text. * @returns A string for the first valid text. */ declare const findValidTextValue: (template: string, isValidName: (candidate: string) => boolean, maxIncrement?: number) => string; declare interface FontHandle { fontRef: IFont.IFontFace; loaded: boolean; } export declare namespace FontUtils { export { DefaultFontSizes, findNextFontSize } } declare class FormulaBlockEntry implements ISpatialMap.IUpdatableEntry { ref: IRange.Coords; formula: ICalcGraph.IFormulaBlock; calcs: CalcNode[][]; /** * If a calcs is provided it is assumed to be shallow cloned or ok to modify */ constructor(coords: IRange.Coords, formula: ICalcGraph.IFormulaBlock, calcs?: CalcNode[][]); toJSON(): [coords: string, text: string]; getCoords(): IRange.Coords; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getShifted} */ getShifted(options: ISpatialMap.ShiftDetails): ISpatialMap.Entry; /** * Creates a new calculation entry with once precedent updated. * @param precedent * @param index */ setReferenceAt(index: number, reference: IRange.FixableCoords): this; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getMerged} */ getMerged(other: this, coords: IRange.Coords, orientation: IRange.Orientation): this | undefined; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getSplit} */ getSplit(coords: [IRange.Coords, IRange.Coords], orientation: IRange.Orientation, offset: number): [this, this] | undefined; /** {@inheritDoc ISpatialMap.IUpdatableEntry.copyTo} */ copyTo(destination: IRange.Coords, options?: ISpatialMap.CopyOptions): this; /** {@inheritDoc ISpatialMap.IUpdatableEntry.canTile} */ canTile(_destination: IRange.Coords, _options?: ISpatialMap.CopyOptions): boolean; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getSplit} */ onRemove?(entry: ISpatialMap.Entry): void; } /** * Used by Sheet to track formula strings (but not the calculation results) */ declare class FormulaEntry { private _c; private _tokens; private _references; constructor(coords: IRange.Coords, tokens?: ICalculation.FormulaToken[], references?: readonly (IRange.FixableCoords | string | FormulaError.Known)[]); getFormulaTextAt(row: number, column: number, r1c1?: boolean): string; getTokensAt(row: number, column: number, evalIndex?: number): readonly ICalculation.FormulaToken[]; getReferencesAt(row: number, column: number): readonly (IRange.FixableCoords | string | FormulaError.Known)[]; toJSON(): [string, string]; getCoords(): IRange.Coords; } export declare namespace GeomUtils { export { unionBounds, centerPoint, boundsToPoints, minBoundingRect, rotatePoints, clipToOuterRect, findIntersectMath, angleToPoints } } /** * Extracts the base name (file name without extension) from a file path. * * @param path The file path from which to extract the base name. * @param shouldCapitalize A boolean flag indicating whether to capitalize the base name. Defaults to `false`. * * @returns The base name of the file. The base name will be capitalized if `shouldCapitalize` is `true`. * * @example * ``` * getBaseName("example.txt"); // Returns "Example" * getBaseName("/path/to/file.jpg"); // Returns "File" * getBaseName("file_without_extension", false); // Returns "file_without_extension" * getBaseName("", false); // Returns "" * ``` */ declare const getBaseName: (path: string, shouldCapitalize?: boolean) => string; /** * Extracts the file extension from a file path. * * @param path The file path from which to extract the file extension. * * @returns The file extension in lowercase. Returns an empty string if the path is invalid or has no extension. * * @example * ``` * getFileNameExtension("example.txt"); // Returns "txt" * getFileNameExtension("/path/to/file.jpg"); // Returns "jpg" * getFileNameExtension("no_extension"); // Returns "" * getFileNameExtension(""); // Returns "" * ``` */ declare const getFileNameExtension: (path: string) => string; declare function getFontList(): readonly FontHandle[]; declare interface GetTypedRangeOptions { /** * If 'true' will not return ranges that are hidden. * If partially hidden the 'fullContained' is applied. */ ignoreHidden?: boolean | IRange.Orientation; /** * Only return ranges that are completely contained with the search range. * * @defaultValue false */ fullyContained?: boolean; sort?: { orientation?: IRange.Orientation; reverse?: boolean; }; onEntry?: (value: E, entry: ISpatialMap.Entry) => T | void; noCache?: boolean; } declare interface HiddenRun extends ITypes.RunCoordValue { } /** * `IAnchored` objects are anchored to a range. */ export declare interface IAnchored { /** * Returns the anchor. */ getAnchorCoords(): IRange.Coords; /** * Returns how the anchorBounds adjust when inserting/removing rows/columns. * * @defaultValue IAnchored.Type.TwoCell */ getAnchorType?(): IAnchored.Type; /** * If the anchor is unable to be modified. */ isProtected(): boolean; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: IAnchored.IListeners, options?: IListener.Options): IListener.Remove; /** * Deletes the anchored item. */ delete(): void; /** * Similar to delete but cleans resources and can't be undone. */ close(): void; /** * Returns if the model has been closed */ isClosed(): boolean; /** * For runtime type checking. */ readonly isIAnchored: true; } /** * {@inheritDoc IAnchored} * @see * ### **Interface** * * {@link IAnchored} */ export declare namespace IAnchored { export interface Events { /** * Called when the anchor bounds are updated. */ onAnchorCoordsChange?(source: IAnchored): void; /** * Called when the anchor protection is updated. */ onProtectedChange?(source: IAnchored): void; /** * Called when the anchor is removed. */ onDelete?(source: IAnchored): void; /** * Called when the state has been updated due to a undo/redo and a rerender is required. */ onInvalidated?(source: IAnchored): void; /** * Called when the state has been updated for any reason. */ onAnyChange?(source: IAnchored): void; /** * Called when the anchor transaction is closed. */ onClose?(source: IAnchored): void; } export interface IListeners extends IListener.Callbacks { } /** * Describes how an anchored items bounds will adjust if * rows/columns are inserted/removed. */ const Type: { /** * Doesn't move when anchors moves. */ readonly Absolute: "absolute"; /** * Only moves the top left */ readonly OneCell: "oneCell"; /** * Moves both the top left and the bottom right */ readonly TwoCell: "twoCell"; }; export type Type = typeof Type[keyof typeof Type]; /** * @see * {@link IAnchored.ConstructorOptions.setContainerShiftCallback} */ export type ShiftCallback = (options: IAnchored.ShiftOptions) => IRange.Coords | void; /** * @see * {@link IAnchored.ConstructorOptions.setContainerDeleteCallback} */ export type DeleteCallback = () => void; /** * @see * {@link IAnchored.ConstructorOptions.setContainerLayoutCallback} */ export type LayoutCallback = () => void; /** * @see * {@link IAnchored.ConstructorOptions.setContainerProtectionCallback} */ export type ProtectionCallback = () => void; export interface CoordsChangeOptions { before: Readonly; after: Readonly; } export type CoordsChangeCallback = (options: CoordsChangeOptions) => void; export interface ShiftOptions { before: IRange.Coords; after: IRange.Coords; intersect: IRange.Coords; isSplit: boolean; orientation: IRange.Orientation; amount: number; } export interface ConstructorOptions { /** * The anchor used when the item is first created. */ initialAnchor: IRange.Coords; /** * If provided will allow for items to store relative ranges. */ maxRangeCoords?: IRange.Coords; /** * Notify the container that a anchor change is required. * * @param address Set the anchor on the container */ setContainerCoords?(address: ICellRange.Address): IRange.Coords; /** * Notify anchored item that the anchor bounds have changed due to an insert/remove. * * @param callback */ setContainerShiftCallback?(callback: IAnchored.ShiftCallback): void; /** * Delete from the container. */ deleteFromContainer?(options?: ITransaction.OperationOptions): void; /** * Notify anchored item that the record has been deleted from the container. * * @param callback */ setContainerDeleteCallback?(callback: IAnchored.DeleteCallback): void; /** * If protected the container can protected the item. */ isProtected?(): boolean; /** * Notify anchor it's protection has been updated from the container. * * @param callback */ setContainerProtectionCallback?(callback: IAnchored.ProtectionCallback): void; /** * Notify anchored item that the pixel bounds have changed due to a resize. * * @param callback */ setContainerLayoutCallback?(callback: IAnchored.LayoutCallback): void; /** * A transaction store that can be used to undo/redo changes. */ transactions?: ITransaction.IStore; /** * Use for the creation transaction description. */ createDescription?: string; } } /* Excluded from this release type: IAnchorEntry */ /** * The `IAutoFill` namespace provides capabilities for applying and managing auto-fill operations * within a spreadsheet. Auto-fill enables automatic generation of data based on patterns in existing data. * * ## Key Features: * - **Linear Fill**: Automatically generate sequential values for numbers or dates, continuing from existing patterns. * - **Ordinal Fill**: Fill data based on strings with numeric identifiers (e.g., Point 1, Point 2, Point 3). * - **List Fill**: Populate ranges with repeating values from predefined lists. * - **Custom Fill Handlers**: Extend auto-fill capabilities by providing custom logic for generating fill data. * * ## Motivation: * The `IAutoFill` namespace is designed to streamline the process of generating predictable data * patterns in a spreadsheet. By identifying existing patterns and applying them to empty ranges, * users can efficiently populate large datasets with minimal manual input. * * Auto-fill supports both built-in patterns, such as numbers and dates, and allows users or developers * to define their own custom fill rules to meet specific use cases. * * This namespace provides the necessary APIs to: * - Detect and extend patterns in existing data. * - Customize the fill behavior for specific types of data. * - Handle edge cases, such as non-contiguous ranges or mixed data types. * * Auto-fill reduces repetitive tasks, improving productivity and minimizing errors when working with large datasets. */ export declare namespace IAutoFill { /** * Represents a filler capable of determining if it can fill a value and creating * an {@link IAutoFill.FillAt} function for generating filled values within a single dimension (row or column). */ export interface Filler { /** * Determines if the Filler can add value to the current fill. * * @param value The value to test. Can be any type or `null`. * @param prev The previous value in the candidate set that is not a null. This is `undefined` for the first element. * @returns `true` if the value should be added. * * @remarks * * The fill array should be treated as readonly. * * The value may be any type and should return `false` if it's not supported. */ canFill: (value: any, prev: any | undefined) => boolean; /** * Create a {@link IAutoFill.FillAt} function using the provided values and options. * * @remarks * * The first elements in the values is guaranteed to never be `null`. * * Return `null` if the autofill is unable to fill. */ createFillAt: (values: readonly T[], options?: IAutoFill.Options) => FillAt | null; } /** * Represents a callback function that provides the filled value at a given offset * within a one-dimensional sequence (either a row or a column). */ export interface FillAt { /** * @param offset 0-based offset from first value. */ (offset: number): T | null; } /** * Options used when calling {@link IAutoFill.Filler.createFillAt}. */ export interface Options { /** * Override the default increment or step value used when generating a fill. * * The default it to use the existing values to determine. * * @remarks * **NOT IMPLEMENTED** * * @example * For `AutoFill.LinearFill` customize the increment between consecutive numbers * in a series (e.g., 1, 3, 5 with `stepValue: 2`). */ stepValue?: number; /** * The stopping value for autofill operations that generate a fill. * * @remarks * **NOT IMPLEMENTED** * * - Allow users to specify the maximum value up to which the autofill series should continue. */ stopValue?: number; /** * Indicates whether there is adjacent span with a different fill type. * * @remarks * - **Purpose:** This flag allows Fillers to adjust their behavior based on the presence of adjacent fills. * For instance, a numeric Filler might increment by 1 when there's an adjacent fill, but simply copy the value otherwise. */ hasDifferentAdjacentFill?: boolean; /** * Indicates whether there is adjacent span with the same fill type. * * @see * {@link hasDifferentAdjacentFill} */ hasSameTypeAdjacentFill?: boolean; /** * Indicates whether there is another fill operation being performed in the same series. */ multiFill?: boolean; /** * Indicates whether the fill operation is in reverse order. * * @remarks * If in reverse order the createFill fill be given values in reverse order. * This flag is only needed if there is a single value. */ reverse?: boolean; } } /** * Capabilities for applying and managing filters. * * AutoFilters enable dynamic filtering of data based on criteria specified per column, * allowing users to quickly focus on relevant information. * * Key features include: * - Applying filters to specific columns within a range. * - Defining filter criteria using various operators (e.g., equals, greater than, contains). * - Hiding rows that don't match the filter criteria. * - Clearing or modifying filters. */ export declare interface IAutoFilter { /** * Returns the coords that filter is applied to. * * @remarks * Returns null if not enabled. */ getCoords(): IRange.Coords | null; /** * The criteria for the filer */ getFieldAt(offset: number): IAutoFilter.Field; /** * Set the criteria at the given offset. * * @remarks * Changing the filter will reapply. */ setFieldAt(offset: number, field: IAutoFilter.Field): IAutoFilter; /** * Set all field fields. */ apply(fields: IAutoFilter.IndexedField[]): IAutoFilter; /** * Reapply criteria and sort to the range. */ reapply(): IAutoFilter; /** * Remove both the filer and sort criteria but leave the range in place. */ clear(): IAutoFilter; /** * Delete this filter. */ delete(): void; /** * Returns true unless any Field has hiddenButton set to true. */ getShowFilterButton(): boolean; /** * If false sets all filterColumns to have a hiddenButton of true * If true set hidden button to false * @param show */ setShowFilterButton(show: boolean): IAutoFilter; /** * Only one sort per table is supported so this will * return the same instance if it has already been created. */ insertSort(): IAutoSort; /** * Returns a sort for the filter. If the filter does not support sorting this should * return null. */ getSort(): IAutoSort; /** * Save a persistable version of AutoFilter */ toJSON(): IAutoFilter.JSON; } /** * {@inheritDoc IAutoFilter} * @see * ### **Interface** * * {@link IAutoFilter} */ export declare namespace IAutoFilter { const NumberFilterOperatorType: { readonly Equal: "equal"; readonly GreaterThan: "greaterThan"; readonly GreaterThanOrEqual: "greaterThanOrEqual"; readonly LessThan: "lessThan"; readonly LessThanOrEqual: "lessThanOrEqual"; readonly NotEqual: "notEqual"; }; export type NumberFilterOperatorType = typeof NumberFilterOperatorType[keyof typeof NumberFilterOperatorType]; const Type: { readonly Color: "color"; readonly Custom: "custom"; readonly Dynamic: "dynamic"; readonly Items: "items"; readonly Icon: "icon"; readonly Top10: "top10"; }; export type Type = typeof Type[keyof typeof Type]; const DynamicType: { readonly AboveAverage: "aboveAverage"; readonly BelowAverage: "belowAverage"; readonly LastMonth: "lastMonth"; readonly LastQuarter: "lastQuarter"; readonly LastWeek: "lastWeek"; readonly LastYear: "lastYear"; readonly M1: "M1"; readonly M2: "M2"; readonly M3: "M3"; readonly M4: "M4"; readonly M5: "M5"; readonly M6: "M6"; readonly M7: "M7"; readonly M8: "M8"; readonly M9: "M9"; readonly M10: "M10"; readonly M11: "M11"; readonly M12: "M12"; readonly NextMonth: "nextMonth"; readonly NextQuarter: "nextQuarter"; readonly NextWeek: "nextWeek"; readonly Null: "null"; readonly Q1: "Q1"; readonly Q2: "Q2"; readonly Q3: "Q3"; readonly Q4: "Q4"; readonly ThisMonth: "thisMonth"; readonly ThisQuarter: "thisQuarter"; readonly ThisWeek: "thisWeek"; readonly Today: "today"; readonly Tomorrow: "tomorrow"; readonly YearToDate: "yearToDate"; readonly Yesterday: "yesterday"; }; export type DynamicType = typeof DynamicType[keyof typeof DynamicType]; const DateItemGroupingType: { readonly Day: "day"; readonly Hour: "hour"; readonly Minute: "minute"; readonly Month: "month"; readonly Second: "Second"; readonly Year: "year"; }; export type DateItemGroupingType = typeof DateItemGroupingType[keyof typeof DateItemGroupingType]; export interface Criterian { /** * The type of criterian used in a filter. */ type: Type; } export interface ColorCriterian extends Criterian { /** * Type must be color; */ type: typeof Type.Color; /** * Indicated whether to filter by cell's fill color. * @defaultValue true */ cellColor?: boolean; /** * If filtered then the id */ styleId?: number; } export interface CustomFilter { /** * The type of operator the custom filter will use * @defaultValue 'match'. */ operator?: NumberFilterOperatorType; /** * The value to compare against. */ value: Scalar; } export interface CustomCriterian extends Criterian { /** * Type must be custom; */ type: typeof Type.Custom; /** * Indicated whether to filters are groups as an and or an 'or'. * @defaultValue false */ and?: boolean; /** * A list of filters */ filters: CustomFilter[]; } export interface DynamicCriterian extends Criterian { /** * Type must be Dynamic; */ type: typeof Type.Dynamic; /** * The type of dynamic filter */ dynamicType?: DynamicType; /** * The minimum value for the dynamic filter. * @see maxVal */ val?: number; /** * The maximum value for the dynamic filter. * This is required for: * today, yesterday, tomorrow, nextWeek, thisWeek, lastWeek, nextMonth, thisMonth, * lastMonth, nextQuarter, thisQuarter, lastQuarter, nextYear, thisYear, * lastYear, and yearToDate. * * @see maxVal */ maxVal?: number; } export interface DateGroupItem { /** * Grouping level. */ group?: DateItemGroupingType; /** * Day 1 - 31. */ day?: number; /** * Hour 0-23. */ hour?: number; /** * Minute 0-59. */ minute?: number; /** * Month 1-12. */ month?: number; /** * Minute 0-59. */ second?: number; /** * 4 Digits. */ year?: number; } export interface FilterItemCriterian extends Criterian { /** * Type must be Items; */ type: typeof Type.Items; /** * If true this filter by blank. */ blank?: boolean; /** * List of item filters */ items?: Scalar[]; /** * List of date group filters. */ dateGroups?: DateGroupItem[]; /** * Calendar type for date group items. */ calendarType?: string; } export interface IconCriterian extends Criterian { /** * 0-based index of an icon from an icon set. If missing then * no icon. */ iconId?: number; /** * Specifies which icon set to use. */ iconSet?: IStyle.IconSet; } export interface Top10Criterian extends Criterian { /** * The actual cell value in the range which is used to perform the comparison for this filter. */ filterVal?: number; /** * Flag indicating whether or not to filter by percent value of the column. A false value filters by number of items. */ percent?: boolean; /** * Flag indicating whether or not to filter by top order. A false value filters by bottom order. */ top?: boolean; /** * Top or bottom value to use as the filter criteria. For example "Filter by Top 10 Percent" or "Filter by Top 5 Items". */ val?: number; } export interface Field { /** * If the button is hidden. * * @remarks * The button may be hidden for other reasons like there is no filter */ hiddenButton?: boolean; /** * On ooxml but not sure what it is used for. */ showButton?: boolean; /** * The criterial for the filter field. If this is empty or null then * this is treated as not having any criteria. */ criteria?: Criterian[]; } export interface IndexedField extends IAutoFilter.Field { /** * Is either a key to find the index or a 0 based offset. */ offset: number; } export interface IColumn { /** * Returns the name of the column. */ getName(): string; /** * Returns a filter criteria for the column is one has been set. */ getField(): IAutoFilter.Field | null; /** * Set a filter criteria for the column. * * @param field The field to set for the column. * * @remarks * This will not affect any other filter fields */ setField(field: IAutoFilter.Field): IColumn; /** * Returns a sort field for the column is one has been set. */ getSortField(): ISort.Criteria | null; /** * Set a sort field for the column. * * @param field The field to set for the column. * * @remarks * This will not affect any other sort fields */ setSortField(field: ISort.Criteria): IColumn; /** * Reapply criteria and sort to the range. */ reapply(): IColumn; /** * Remove both the filer and sort criteria but leave the range in place. */ clear(): IColumn; /** * If the filter button is hidden. */ hasHiddenButton(): boolean; } export interface JSON { /** * The reference. The filter is applied to. * * @remarks * This may be blank is it can be defined by the filter container. */ ref?: string | IRange.Coords; /** * fields that define how values are filtered */ fields?: IAutoFilter.IndexedField[]; /** * AutoFilters can have SortFields. */ sort?: IAutoSort.JSON; } } /** * Capabilities for applying and managing sorting on a range. * * `AutoSort` enables dynamic sorting of data based on criteria specified per column, * allowing users to organize and arrange information effectively. * * Key features include: * - Sorting one or more columns within a range. * - Specifying sort order (ascending or descending) for each column. * - Applying custom sort options (e.g., case sensitivity). * - Clearing or modifying sort. */ export declare interface IAutoSort { /** * Returns the range that filter is applied to. */ getRange(): IRange.Coords; /** * Returns the current fields or an empty array if nothing is sorted. */ getFieldAt(offset: number): ISort.Criteria; /** * Updates the current sort fields. * @param offset Offset relative to the sort. * @param field The field to sort. */ setFieldAt(offset: number, field: ISort.Criteria): IAutoSort; /** * Set all field fields. */ apply(fields: ISort.Field[]): IAutoSort; /** * Reapply sort to the fields. */ reapply(): IAutoSort; /** * Remove the current sort. * @remarks * This is a convenience methods that does the same thing that setFields with an empty array does. */ clear(): IAutoSort; /** * Delete this sort. */ delete(): void; /** * Returns persistable state. */ toJSON(): IAutoSort.JSON; } /** * {@inheritDoc IAutoSort} * @see * ### **Interface** * * {@link IAutoSort} */ export declare namespace IAutoSort { export interface JSON extends ISort.Criteria { /** * If not defined then assume the container has default the range. */ ref?: string; /** * Sort fields. */ fields?: ISort.Field[]; } } export declare namespace IBorder { /** * @remarks * This is a limited implementation of border that matches OOXMl and Excel. * TODO - Review and rationalize with css. * * Excel online breaks weight and styling into two properties but... (I ) * * Excel only supports the enums as they are defined in OOXML. * * @see * {@link https://learn.microsoft.com/en-us/javascript/api/excel/excel.cellborder?view=excel-js-preview#excel-excel-cellborder-style-member} */ const StrokeStyle: { readonly None: "none"; readonly DashDot: "dashDot"; readonly MediumDashDot: "mediumDashDot"; readonly Dotted: "dotted"; readonly Hair: "hair"; readonly Thin: "thin"; readonly Medium: "medium"; readonly Thick: "thick"; readonly MediumDashDotDot: "mediumDashDotDot"; readonly DashDotDot: "dashDotDot"; readonly Dashed: "dashed"; readonly MediumDashed: "mediumDashed"; readonly SlantDashDot: "slantDashDot"; readonly Double: "double"; }; export type StrokeStyle = typeof StrokeStyle[keyof typeof StrokeStyle]; const Edge: { readonly Left: "left"; readonly Top: "top"; readonly Right: "right"; readonly Bottom: "bottom"; /** * @remarks * `horizontal` and `vertical` properties are supported for setting values but get converted top/left/bottom/right for individual cells. * These will always be null in the IStyle. */ readonly Horizontal: "horizontal"; /** * @inheritdoc Edge.Horizontal */ readonly Vertical: "vertical"; readonly DiagonalUp: "diagonalUp"; readonly DiagonalDown: "diagonalDown"; }; export type Edge = typeof Edge[keyof typeof Edge]; /** * Used for look ups and drop drowns. */ export interface Definition { style: StrokeStyle; description: string; width: number; pattern: number[]; } export interface IStroke { getStyle(): StrokeStyle; /** * Sets the stroke style. * * @param style The stroke style. */ setStyle(style: IBorder.StrokeStyle | string | null, options?: IStyle.UpdateOptions): IBorder.IStroke; getColor(): IColor; /** * Sets the stroke color. * * @param color The stroke color. */ setColor(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IBorder.IStroke; /** * Returns all the set properties and their values for the border. */ getProperties(): IBorder.StrokeProperties; /** * Returns a set of CSSStyleDeclaration that approximate the stroke. */ toCSS(): Partial; /** * @returns `true` StrokeStyle is `None`. */ isNone(): boolean; /** * For runtime type checking. */ readonly isIStroke: true; } export interface StrokeProperties { style?: IBorder.StrokeStyle; color?: C; } export interface StrokeJSON { style?: IBorder.StrokeStyle; color?: string; } export type Properties = { [key in IBorder.Edge]?: IBorder.StrokeProperties; }; /** * Modifiers describe a partial list of properties that can be set with values or shorthand strings. */ export type Modifiers = Partial; /** * Options for updating a border. */ export type Update = IBorder | Modifiers | string | null; /** * JSON representation of a border. */ export type JSON = { [key in IBorder.Edge]?: IBorder.StrokeJSON; }; } /** * Provides information for describing a border around a shape. */ export declare interface IBorder { /** * @returns The left border. */ getLeft(): IBorder.IStroke; /** * Sets the left border. * * @param edge The border edge. */ setLeft(edge: IBorder.IStroke | IProperties.ResolvableProperties | string | null, options?: IStyle.UpdateOptions): IBorder; /** * @returns The top border. */ getTop(): IBorder.IStroke; /** * Sets the top border. * * @param edge The border edge. */ setTop(edge: IBorder.IStroke | IProperties.ResolvableProperties | string | null, options?: IStyle.UpdateOptions): IBorder; /** * @returns The right border. */ getRight(): IBorder.IStroke; /** * Sets the right border. * * @param edge The border edge. */ setRight(edge: IBorder.IStroke | IProperties.ResolvableProperties | string | null, options?: IStyle.UpdateOptions): IBorder; /** * @returns The bottom border. */ getBottom(): IBorder.IStroke; /** * Sets the bottom border. * * @param edge The border edge. */ setBottom(edge: IBorder.IStroke | IProperties.ResolvableProperties | string | null, options?: IStyle.UpdateOptions): IBorder; /** * @returns The diagonalUp border. */ getDiagonalUp(): IBorder.IStroke; /** * Sets the diagonalUp border. * * @param edge The border edge. */ setDiagonalUp(edge: IBorder.IStroke | IProperties.ResolvableProperties | string | null, options?: IStyle.UpdateOptions): IBorder; /** * @returns The diagonalDown border. */ getDiagonalDown(): IBorder.IStroke; /** * Sets the diagonalDown border. * * @param edge The border edge. */ setDiagonalDown(edge: IBorder.IStroke | IProperties.ResolvableProperties | string | null, options?: IStyle.UpdateOptions): IBorder; /** * If there are any borders that are not none. */ isEmpty(): boolean; toJSON(): IBorder.JSON; /** * Returns all the set properties and their values for the border. */ getProperties(): IBorder.Properties; /** * List of customizations modifiers for the border. */ /** * For runtime type checking. */ readonly isIBorder: true; } /** * {@inheritDoc IBorder} * @see * ### **Interface** * * {@link IBorder} */ export declare namespace IBorder { /** * Compare two strokes for logical equality. */ const isEqualStrokes: (a: IBorder.IStroke, b: IBorder.IStroke) => boolean; /** * Returns the opposite border edge. This only works for Left,Right,Top,Bottom * all other edges return themselves. * @param edge The edge. * @returns The opposite edge or the input value. */ const oppositeEdge: (edge: Edge) => Edge; /** * List of Border definitions. This provides an order for display purposes. */ const BuiltInDefinitionsArray: Definition[]; /** * Provides a quick way to access border definitions by StrokeStyle. */ const BuiltInDefinitions: Map; } declare interface IBullet { readonly fontName: string; readonly fontSize: number; readonly autoNumberScheme: AutoNumberingSchemeType; readonly startAt: number; readonly character: string; readonly imageScale: number; readonly imageNaturalWidth: number; readonly imageNaturalHeight: number; readonly bounds?: Bounds; } /** * The calc engine used to calculate the values in a direct graph. */ declare interface ICalcGraph { /** * Set a group of cells and formula ranges. * * @param values A set of input values as BoundedTuples * @param ranges A set of formula strings as ranged entries. */ setInputs(values: Tuple.BoundedTuples, formulas: readonly ISpatialMap.Entry[]): ISpatialMap.Updates; /** * Delete all values within a range. * * @param coords The coordinates to delete. */ delete(coords: IRange.Coords | string): ISpatialMap.Entry[]; /** * Mark a range invalid. This will call the area to be recalculated on the next calculate call. * * @param coords An array of coordinates. */ invalidate(coords: (IRange.Coords | string)[]): void; /** * Execute a calculate on the Graph. * * @param options The options or a boolean. If `true' a full calculation will be done. * @returns A promise that will be resolved when the calculation is completed. * * @remarks * For async functions this will return before they are completed. */ calculate(options?: ICalculation.CalculateOptions | boolean): Promise; /** * The the value at a specific cell to a formula. * * @param coords The coords * @param formula A string formula or null to clear */ setFormulaAt(coords: IRange.CellCoords | string, formula: string | null): ISpatialMap.Updates; /** * Return a formula at a specific cell. * * @param coords The coords * @param r1c1 If 'true' then returns string as r1c1 */ getFormulaAt(coords: IRange.CellCoords | string, r1c1?: boolean): string; /** * Set a single input value for a cell. * * @param coords The coords * @param value The value */ setInputAt(coords: IRange.CellCoords | string, value: Scalar): ISpatialMap.Updates; /** * Shifts all values in the graph in a given direction. * * @param options The options for the shift. */ shift(options: ICalcGraph.ShiftOptions): this; /** * Returns a snapshot of the graph that can be used for copying. */ getSnapshot(options?: ICalcGraph.GetSnapshotOptions): ICalcGraph.ISnapshot; /** * Autofill the values from a single cell to the entire range. * * @remarks * This is similar to getSnapshot but doesn't return a promise. */ autoFill(template: IRange.Coords | string, destination: IRange.Coords | string): this; /** * Returns the resolved direct precedents for a formula. * * @param row The row of the cell to evaluate. * @param column The column of the cell to evaluate. * @param includeInvalidIntersect * @throws Error if the cell is not a formula. */ getDirectPrecedentsAt(row: number, column: number, includeInvalidIntersect?: boolean): readonly (IRange.Coords | FormulaError.Known)[] | null; /** * Returns the reference for a specific cell. * * @param row The row of the cell to evaluate. * @param column The column of the cell to evaluate. * @throws Error if the cell is not a formula. */ getReferencesAt(row: number, column: number): readonly (IRange.FixableCoords | string | FormulaError.Known)[]; /** * Sets the reference at a specific formula cell. * * @param row The row of the cell to evaluate. * @param column The column of the cell to evaluate. * @param index The index of the evaluation to use from the tokens. * @param reference The value to set * @throws Error if the cell is not a formula. */ setReferenceAt(row: number, column: number, index: number, reference: IRange.FixableCoords | string): this; /** * Evaluates a formula outside of the calculation cycle. * * @param row The row of the cell to evaluate. * @param column The column of the cell to evaluate. * @param evalIndex The index of the evaluation to use from the tokens. * @throws Error if the cell is not a formula. * * @remarks * * Used for tooltip evaluation and other static evaluations. * * Used by {@see ICalculation.IFormula.evaluate}. */ evaluateAt(row: number, column: number, evalIndex?: number): Promise; /** * Returns a copy on write clone. * * @param cloneKey A performance optimization that will avoid cloning if the same key is used. * * @remarks * If the same clone key is used then the same instance will be returned. */ clone(cloneKey?: any): this; /** {@inheritDoc ICalcGraph.addListeners} */ addListeners(listeners: ICalcGraph.IListeners, options?: IListener.Options): IListener.Remove; /** * Loads the json into the graph. * * @param json The JSON to load. * * @remarks * This will clear all values and formulas including any pending changes or invalidation. */ fromJSON(json: ICalcGraph.JSON): ICalcGraph.Results; /** * Returns a JSON representation of the calcGraph. * * @param includeData If `true` the values will be saved. */ toJSON(includeData?: boolean): Promise; } /** * {@inheritDoc ICalcGraph} * * @see * ### **Interface** * * {@link ICalcGraph} */ declare namespace ICalcGraph { interface Results { /** * The id of the calculation that was completed. * * @remarks * * Every calculation will have a unique id so this can be used to track the completion of a calculation. * * If calculations was called but no calculation was performed and event will be fired with the * previous calcCompleteId. */ cycleId: number; /** * When a full calculation is performed removes are not return and the client must clear all caches `true`. * * @defaultValue `false` */ isFull?: boolean; /** * The bounds of the result updates including tuples, spills inserts and spills removes. * * @remarks * This will be `null` if no calculation results were updated or if isFull. */ bounds?: IRange.Coords | null; /** * The results of the calculation will either be as `Map` or as a `Tuple.BoundedTuples`. * * @see * {@link CalculateOptions.asTuples} */ valueInserts?: Tuple.BoundedTuples; /** * Values that have been cleared. */ valueRemoves?: IRange.Coords[]; /** * Contains any formulas that were inserted. */ formulaInserts?: ISpatialMap.Entry[]; /** * Contains any formulas that were removed. */ formulaRemoves?: ISpatialMap.Entry[]; /** * Contains any spills that were inserted. */ spillInserts?: ISpatialMap.Entry[]; /** * Contains any spills that were removed. */ spillRemoves?: ISpatialMap.Entry[]; /** * Formatting updates due to functions. * * @remarks * Formats are not cleared. */ formatInserts?: ISpatialMap.Entry[]; /** * Contains any errors that were inserted. */ errorInserts?: ISpatialMap.Entry[]; /** * Contains any error that were removed. */ errorRemoves?: ISpatialMap.Entry[]; /** * Indicates that a pending status has been added or removed. * A `true` value indicates that the pending status has been added. * A `false` value indicates that the pending status has been removed. * * @remarks * These are guaranteed to not overlap. */ pendingUpdates?: ISpatialMap.Entry[]; } /** * Contains the formula string and the coordinates of the precedents. */ interface FormulaInsert { /** * The formula tokens. */ tokens: ICalculation.FormulaToken[]; /** * The coordinates of the formula. Used for formatting. */ precedents: IRange.Coords[]; /** * Contains the non resolved references. */ references: readonly (IRange.FixableCoords | string | FormulaError.Known)[]; } interface GetSnapshotOptions extends ReferenceableClipboard.CopyOptions { /** * The range to capture the snapshot from. If omitted the entire range will be used. */ range?: IRange.Coords | string; } /** * Provides destination details for the Snapshot when using `IHistory.ISnapshot.copyTo`. */ interface SnapshotDestination { /** * The destination calc graph to copy to. */ calcGraph: ICalcGraph; /** * The range to copy the snapshot to. */ range: IRange.Coords | string; } interface ISnapshot extends IHistory.ISnapshot { /** * Called when the table is copied to a new collection. */ copyTo(destination: ICalcGraph.SnapshotDestination, options?: ICalcGraph.CopyOptions): Promise; } /** * Options for {@link ISnapshot.copyTo}. */ interface CopyOptions extends ReferenceableClipboard.CopyOptions { /** * When pasting from a smaller range to a larger range copy will repeat or 'wallpaper' the * source values. * * @remarks * Note - If the destination range is only a single cell then fitDestination will always be applied. */ fitDestination?: boolean; /** * Have the data transposed for the original orientation. * @defaultValue false */ transpose?: boolean; } interface Error { /** * The error message. */ message?: string; /** * Some error types will give an indicate of the range location. */ coords?: string[]; } interface IFormulaBlock { /** * This is the eval used internally by graph. * precedents must be an array of either IRange or Scalar. * * @param context The context to evaluate the formula in. * @param evalIndex The index of the evaluation to use from the tokens. * @param precedents **PERFORMANCE** Allows for pre-calced precedents to be use for the evaluation. * * @remarks * The precedents can be passed in as a performance optimization graph caches them as it calculates. */ evaluate(context: IFormulaContext, evalIndex?: number, precedents?: any[]): any; /** * Return the formula as an array of formula token values. These can be used * by advanced editors. */ getTokens(): ICalculation.FormulaToken[]; /** * Return the formula string. */ getTextAt(row: number, column: number, r1c1?: boolean): string; /** * Returns the cell ranges that provide data to a formula. * * @param row The row of the formula. * @param column The column of the formula. * @param includeInvalidIntersect If `true` then invalid ranges will be included in the result. * @param verticalAbs If provided the array will be populated with flags if a vertical absolute is detected * @param horizontalAbs If provided the array will be populated with flags if a horizontal absolute is detected * * @remarks * * `[]` if no precedents are present; either because it has no formula or a formula with no inputs. * * Precedents are the logical ranges and may different the inputs into the formula. * * includeInvalidIntersect is required to manage dependencies for invalid intersections in shared formulas. */ getDirectPrecedentsAt(row: number, column: number, includeInvalidIntersect?: boolean, verticalAbs?: boolean[], horizontalAbs?: boolean[]): (IRange.Coords | FormulaError.Known)[]; /** * Returns a list of fixable coordinates used by the formula. * * @remarks * This is done to enable updates. */ getReferences(): readonly (IRange.FixableCoords | string | FormulaError.Known)[]; /** * Returns a new formula that has the reference at an index. * * @param index The index of the reference to set. * @param reference The reference to set. * * @remarks * This must align to the getReferences. * setReference does not support setting or updating named ranges */ setReferenceAt(index: number, reference: IRange.FixableCoords | null): this; /** * Wraps the formula in an implicit reference operator if hasSpill returns true and the formula * expects a spill. * * @param rowIndex The row index of the formula. * @param colIndex The column index of the formula. * @param setSpillCells - A1 notation for all of the cells that contains spills. * * @remarks * This is used for importing Excel as it doesn't always add '@' for backward compatibility. */ wrapImplicit(rowIndex: number, colIndex: number, setSpillCells: Set): this; /** * Return an error with the formula. * * @remarks * This is not a value error but that the formula is unable to resolve. */ getError(): FormulaError.Parse | null; /** * If the formula is logically equal to another formula. * * @param other The other formula block to compare to. */ isEquals(other: ICalcGraph.IFormulaBlock): boolean; } /** * Options for shifting the calc graph. */ interface ShiftOptions { /** * The range to shift. */ range: IRange.Coords; /** * The direction to shift. */ direction: IRange.Direction; /** * If `true` the this will return a clone instance of the graph if there are any modifications. * * @defaultValue false * * @remarks * This allows for a 0-1 clone on write. */ cloneIfUpdate?: boolean; } /** * Events for {@link ICalcGraph}. */ interface Events { /** * Called when the calculation has been updated and * a calculation has not been started. */ onInvalidate?(source: ICalcGraph): void; /** * Called when a calculation is started. */ onStart?(source: ICalcGraph): void; /** * Called when a calculation is started. */ onComplete?(source: ICalcGraph, results: ICalcGraph.Results): void; /** * Called when the calculation engine is unable to calc. * * @remarks * This is not when a specific function fails, but when the calculation engine is unable to complete the calculation. */ onError?(source: ICalcGraph): void; /** * Called when the CalcGraph is closed. */ onClose?(source: ICalcGraph): void; } interface IListeners extends IListener.Callbacks { } /** * Options available when creating a CalcGraph. */ interface ConstructorOptions extends ICalculation.ConstructorOptions { /** * The calculation instance that will be used to calculate the graph. * * @remarks * Required as this will contain the context */ calculation: ICalculation; /** * The Formula parser for creating FormulaBlocks. * * @remarks * This is passed in so that the Calculation engine can share lazy load */ getFormulaParser: () => IFormulaParser; /** * A callback that identifies the sheet name. */ getSheetName?(): string; /** * Callback that determines the maximum coordinates of the graph. */ getEntireCoords?: () => IRange.Coords; /** * A callback that is called when the calculation is completed. * * @remarks * This will persist through clones. */ onCalculated?: (results: ICalcGraph.Results) => void; } interface JSON { /** * The input and calced data. * * @remarks * This is usually empty as the data is managed by the client of the graph. */ data?: Tuple.GridTuple; /** * The formulas */ formulas?: [address: string, text: string][]; /** * Indicates a range was created via a dynamic array formula. * This is a specific type of dynamic. */ dynamic?: [address: string, error: boolean][]; /** * Indicates the range contains volatile functions. * * @remarks * For built-in functions volatile will be auto added. */ volatile?: string[]; } } declare interface ICalcGraphScope { rowIndex: number; colIndex: number; sheetName: string; node: CalcNode; values: ISparseGrid; spillSpatial: ISpatialMap; formulaSpatial: ISpatialMap; volatile: Set; conflatingFormats: IConflatingRanges; dynamicPrecedentsInserts: ISpatialMap.Entry[]; formula: ICalcGraph.IFormulaBlock; getEntireCoords?: () => IRange.Coords; } /** * Calculation is the process of computing formulas and then displaying the results * as values in the cells that contain the formulas. */ export declare interface ICalculation extends IModel { /** * Starts the ICalculation engine. * * @remarks * * This is required to be called before any calculations can be performed. * * This will initialize the calculation engine and prepare it for use. * * Will fire events and return a promise when the calculation is started. (or errors); */ start: () => Promise; /** * Stops the ICalculation engine. */ stop: () => Promise; /** * Returns the current status of the calculation engine. */ getStatus(): ICalculation.Status; /** * Returns the functions available for the calculation engine. */ getFunctions(): IFunctionCollection; /** @inheritdoc IFormulaContext.getRuntime */ getRuntime(): IRuntime; /** * Returns when all calculations are complete and there are no pending calculations. * * @remarks * * This is useful when needing to ensure that the values in the calculation cycle are up-to-date. * * For streaming functions still will return the current value. */ ready(): Promise; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: ICalculation.IListeners, options?: IListener.Options): IListener.Remove; } /** * {@inheritDoc ICalculation} * @see * ### **Interface** * * {@link ICalculation} */ export declare namespace ICalculation { /** * Options for when calculating. */ export interface CalculateOptions { /** * If true a full calc will be done not just invalid values */ full?: boolean; } /** * Represents a formula that can be evaluated. */ export interface IFormula { /** * Return the formula as an array of tokenized values. * * @param evalIndex Allows for a partial evaluation based on a token index. * * @remarks * These can be used by advanced editors. * * @see ICalculation.FormulaToken.evalIndex */ getTokens(evalIndex?: number): readonly ICalculation.FormulaToken[]; /** * Return the value for a formula. * * @param evalIndex Allows for a partial evaluation based on a token index. * * @remarks * The index is the {@link ICalculation.FormulaToken.evalIndex}. If not provided this will return * the value of the entire formula. * * @see ICalculation.FormulaToken.evalIndex */ evaluate(evalIndex?: number): Promise; /** * Return the formula string. * * @param r1c1 If `true` then the formula will be returned in R1C1 format. */ toText(r1c1?: boolean): string; /** * Returns the ranges that provide data to a formula. * * @remarks * * `[]` if no precedents are present; either because it has no formula or a formula with no inputs. * * Precedents are the logical ranges and may different the inputs into the formula. */ getDirectPrecedents(): readonly (IRange.FixableCoords | FormulaError.Known)[]; /** * Returns the references that are used in the formula. * * @remarks * This is different than the direct precedents as it includes references before the range * operators. This is useful for indicating to the users the static inputs and allow. */ getReferences(): readonly (IRange.FixableCoords | string | FormulaError.Known)[]; /** * Sets the reference at the given index. * * @param index The index of the reference to set. * @param reference The reference to set at the index. * * @remarks * The index must align with the getReferences() array. Will throw an error if the * index not with the reference array. */ setReferenceAt(index: number, reference: IRange.FixableCoords | null): this; } /** * Provides the function context for formulas that are arguments. */ export interface FormulaTokenContext { /** * The name of the function */ name: string; /** * If the token is part of a function this will be the index location. * * @remarks * For parens this will be `-1`. */ argIndex: number; } /** * Represents a portion of a formula for rendering typical in an editor. */ export interface FormulaToken { /** * The type of token. */ type: string; /** * This is either a string or a range coordinates. * * @remarks * If this is a IRange.Coords then is it relative. */ value: string | IRange.FixableCoords | any; /** * If the token is part of a a function this will be set. This will be the 'closest' function if nested. */ ctx?: ICalculation.FormulaTokenContext; /** * Allows for partial formula evaluation for tooltips or formula writing. * Only available for tokens types that can be evaluated. * * @remarks * To determine the 'token span' for the evaluation you can can tokens left and right * until you reach a token that has a larger evalIndex or there are no more tokens. */ evalIndex?: number; /** * Indicates that the token is part of a reference. * * @remarks * * Multiple tokens can be part of the same reference. * * The refIndex will be the offset of the range in the {@link ICalculation.IFormula.getReferences} array. */ refIndex?: number; } export interface Result { } export interface Events extends IModel.Events { /** * Called when the calculation has been updated and * a calculation has not been started. */ onStale?(source: ICalculation): void; /** * Called when a calculation is starting. */ onStarting?(source: ICalculation): void; /** * Called when a calculation is stopping. */ onStopping?(source: ICalculation): void; /** * Called when the calculation status has changed. */ onStatusChange?(source: ICalculation): void; /** * Called when a calculation is started. */ onComplete?(source: ICalculation, results: ICalculation.Result): void; /** * Called when the calculation engine is unable to calc. * * @param source * * @remarks * This is not when a specific function fails, but when the calculation engine is unable to complete the calculation. */ onError?(source: ICalculation): void; /** * Called when the ICalculation has been loaded and is ready to calc. */ onReady?(source: ICalculation): void; /** * Called when the ICalculation has been loaded and is ready to calc. */ onStop?(source: ICalculation): void; } /** * Represents the calculation engine's overall status. */ const Status: { /** * The calculation engine is in manual mode and will only update cell values when a calculation is explicitly triggered. */ readonly Ready: "ready"; /** * The calculation engine has encountered an error and is unable to perform calculations. * This status represents engine-level errors, separate from cell-level errors (which are represented as Scalar.Error values). */ readonly Error: "error"; /** * The calculation engine is starting up and initializing its internal state. */ readonly Starting: "starting"; /** * The calculation engine is stopping and cleaning up its internal state. */ readonly Stopping: "stopping"; /** * The calculation engine is disabled. */ readonly Off: "off"; }; export type Status = typeof Status[keyof typeof Status]; export interface JSON { /** * Indicates whether the workbook has completed its last calculation cycle. * * @remarks * If `true`, the workbook is up to date with calculations. */ calcCompleted?: boolean; /** * Defines the calculation mode for the workbook. * * @remarks * Possible values could include 'auto', 'manual', or 'semi-automatic'. */ calcMode?: string; /** * Specifies whether calculations should be performed when the workbook is saved. * * @remarks * If `true`, the workbook recalculates all formulas before saving. */ calcOnSave?: boolean; /** * Specifies whether calculations should be performed concurrently across multiple threads. * * @remarks * If `true`, the workbook uses multi-threading for calculations. */ concurrentCalc?: boolean; /** * Specifies whether concurrent calculations are allowed in manual calculation mode. * * @remarks * If `true`, manual calculations can utilize multiple threads. */ concurrentManualCount?: boolean; /** * Specifies whether the workbook forces a full recalculation of all formulas. * * @remarks * If `true`, all formulas will be recalculated from scratch regardless of dependencies. */ forceFullCalc?: boolean; /** * Specifies whether a full recalculation should be performed when the workbook is loaded. * * @remarks * If `true`, the workbook recalculates all formulas upon loading. */ fullCalcOnLoad?: boolean; /** * Indicates whether calculations should be performed using full precision. * * @remarks * If `true`, all calculations are performed with the maximum precision available. */ fullPrecision?: boolean; /** * Specifies whether the workbook should iterate calculations when circular references are present. * * @remarks * If `true`, the workbook allows iterative calculations to resolve circular references. */ iterate?: boolean; /** * Defines the maximum number of iterations allowed when performing iterative calculations. * * @defaultValue `100` * * @remarks * This value is only used if `iterate` is set to `true`. */ maxIterations?: number; /** * Defines the maximum change between iterations that must be reached before the iterative calculation stops. * * @defaultValue `0.001` * * @remarks * A smaller delta will make the iterative calculation more precise but may take longer to complete. * */ maxIterateChange?: number; /** * Specifies the reference mode for calculations. * * @remarks * Possible values could include 'A1' or 'R1C1', representing different reference styles. */ refMode?: string; } export interface IListeners extends IListener.Callbacks { } /** * Options available when creating a Calculation Service. */ export interface ConstructorOptions { /** * Hook to provide custom functions. * * @param name name of the function * @returns IFunction * * @remarks * Names will always be passed as the user input them but are generally treated as case insensitive */ getFunction?: (name: string) => IFunction | null; /** * Hook to provide custom names. * * @param name The name to resolve * @param scope The current scope * * @remarks * Names will always be passed as the user input them but are generally treated as case insensitive */ getNamed?: (name: string, scope?: string) => IRange.FixableCoords[] | null; getSheetIndex?: (sheetName?: string) => number; getSheetCount?: () => number; /** * Callback that determines if dates are 1904. */ isDate1904?: () => boolean; strings?: IStringCollection; errors?: IStringCollection; /** * The maximum number of iterations to perform when calculating. */ maxIterations?: number; maxIterateChange?: number; } } /** * A single unit of data and meta data within an `ICellRange`, located at a specific row and column. */ export declare interface ICell { /** * Returns the range of the cell. * * @remarks * Returns a range for a single cell. * Temporary cells will have to return InvalidRange */ getRange(): ICellRange; /** * Returns the value of the cell. * * @remarks * Returns `null` if the cell has no value. */ getValue(): Scalar; /** * Returns the type of the cell (e.g., text, number, date). */ getType(): ScalarType; /** * Returns the formula assigned to the cell. * * @remarks * Returns `null` if the cell has no formula. */ getFormula(): ICalculation.IFormula | null; /** * Returns the formula text assigned to the cell. * * @remarks * Returns `null` if the cell has no formula. */ getFormulaText(): string | null; /** * Returns the CalcStatus. */ getCalcStatus(): ICell.CalcStatus; /** * Returns the hyperlink assigned to the cell. * * @remarks * Returns `null` if no hyperlink is set. */ getHyperlink(): IHyperlink | null; /** * Retrieves a list of comments associated with the cell. * * **Note**: This feature is not yet implemented. */ getComments(): Readonly; /** * Retrieves any warnings attached to the cell. * * @remarks * Warnings differ from errors in that they may alter the display of the cell's value or type. */ getWarnings(): readonly string[]; /** * Retrieves any errors attached to the cell. */ getErrors(): readonly string[]; /** * Returns the style information applied to the cell. * * @param specific - *`default`* `true` * * @remarks * If `true`, Returns the style directly set on the cell. * Otherwise, returns the rendered style, which may include effects like * conditional or table formatting. */ getStyle(specific?: boolean): IStyle; /** * Returns the cell's value as a formatted string, applying any number formatting. * * @see * {@link toTextUnformatted} */ toText(): string; /** * Returns the cell's value as an unformatted string. * * @param useFormula If `true` this will return a text frame for formula (if there is one else). * * @remarks * Minimum formatting is still applied to certain values, such as dates, times, and percentages. */ toTextUnformatted(useFormula?: boolean): string; /** * Returns the cell's value as a JavaScript `Date` object if the cell contains a date. * * @remarks * Only returns a date if the number formatting is a date format and the cell's value * can be interpreted as a valid JavaScript `Date`. Otherwise, returns `null`. */ toDate(): Date | null; /** * Returns the cell's value as a string with additional number format details. * * @param override A custom number format to apply (optional). * * @remarks * This method always returns a formatted string and never `null`. */ getNumberFormat(override?: string): NumberFormat.Parsed; /** * Retrieves a {@link ITextFrame} containing text layout details, such as wrapping and alignment. * * @param useFormula If `true` this will return a text frame for formula (if there is one). * * @remarks * Returns `null` if the cell does not contain text or does not contain a formula. * This includes text formatting, rich text, and number formatting. */ getTextFrame(useFormula?: boolean): ITextFrame | null; /** * Calculates the optimal size required to display the cell's content. * * @param colWidth The column width, used for text wrapping calculations. Default value `the current column width`. * @param minContent If `true`, calculates the size using the min width possible. For decimal numbers this will round. * * @remarks * Returns `null` if this cell should be ignored for sizing purposes. * Either dimension can also be `null`, indicating that the specific direction should not be used. */ getBestFit(colWidth?: number, minContent?: boolean): Readonly> | null; /** * Returns protection information. */ getProtection(): ICellProtection; /** * Returns the padding around the cell's content. * * @remarks * Insets do not affect the fill or background of the cell. */ getInsets(): Readonly; /** * Returns the span dimensions for merged cells. */ getSpans(): Readonly; /** * Returns `true` if the cell is the top-left cell of a merged region, or if it is not part of a merged region. */ isTopLeft(): boolean; /** * Returns the range of the cell if it is a spill cell. */ getSpill(): ICellRange | null; /** * Returns `true` if the cell is a spill and not the top left. */ isSpillOverflow(): boolean; /** * Returns the overflow details for the cell's text overflow or `null` if the cell does not overflow. * * @remarks * * This will only return a value if iterating using `ICellRange.Orientation.Row`. */ getTextOverflow(): Readonly | null; /** * Returns the extruding range of the cell if it extends beyond its original coordinates. * * @remarks * Useful for cells that have been merged or have text overflow. This can also * be included when iterating ranges with the `extendedRange` flag set to `true`. */ getExtrusions(): Readonly | null; /** * Returns the appropriate horizontal alignment for rendering the cell's content. * * @remarks * This takes into account both the style's alignment settings and the type of data in the cell. */ getRenderHorizontalAlignment(): ITextFrame.HorizontalAlignment; /** * Return an {@link IAutoFilter.IColumn} if the cell is the the first row of an AutoFiltered range. */ getColumnFilter(): IAutoFilter.IColumn | null; /** * Returns `true` if the cell contains a value. * * @remarks * A cell can be contentful even if it has no value but contains styling or other * characteristics like row/col spans or borders. */ isContentful(): boolean; /** * Returns `true` if the cell is empty, meaning it has no value and its style is set to 'Normal'. * * @see * {@link ICell.isContentful} */ isEmpty(): boolean; /** * Returns `true` if the cell is read-only. * * @remarks * A cell can be read-only due to protection or other reasons. */ isEditAllowed(): boolean; /** * Returns `true` if the formula is hidden. */ isFormulaHidden(): boolean; /** * Compares the current cell to another instance to determine if they are logically equal. * * @param other The cell to compare to. * * @remarks * * To be equal the cells must have the same values and be at the same address. * * Useful when ICells are dynamically generated because '===' comparison is not valid. */ isEqual(other: ICell): boolean; /** * Creates a temporary copy of the cell with the specified updates applied. * * @remarks * The original cell remains unchanged, making this useful for temporary modifications. */ createTemporaryCell(modifiers: ICell.Update): ICell; /** * Returns the `CellCoords`. */ getCoords(): Readonly; /** * Returns an A1-style string address (e.g., 'A1', 'B5'). */ getA1(): string; /** * Selects the current cell. * @returns An async boolean indicating the cell was selected. */ select(options?: ITypes.SelectOptions): Promise; /** * Returns the Sheet. */ getSheet(): ISheet; /** * For runtime type checking. */ readonly isICell: true; } /** * {@inheritDoc ICell} * @see * ### **Interface** * * {@link ICell} */ export declare namespace ICell { /** * This is either: * 1. A string that can be parsed into a IRange.CellCoords (e.g. 'A1') * 2. A `IRange.CellCoords` * 3. An `ICell` */ export type Address = string | Readonly | ICell; /** * Expansive way to set cell updates options. */ export type Update = ICell | ICell.Modifiers | JSScalarUpdate | null; /** * Used for updating multiple properties on a cell at the same time. * Any value that is null will be If a value is null then this will be treated as a remove. */ export interface Modifiers { /** * If a Date is passed to it will be converted internally into an OADate number with a date format (unless the style format is also set) */ value?: T | null; /** * Update the style. */ style?: IStyle.Update; /** * Allow to to set a hyperlink to this value. */ hyperlink?: IHyperlink.Update; } /** * Configuration options for customizing the parsing of a string into an `ICell.Update` object. * Commonly used for processing CSV imports and other string-based data sources. */ export interface ModifiersFromStringOptions { /** * If `true`, the leading quote character in the string will be ignored during parsing. * This option is typically useful when importing data from CSV files. * * @defaultValue false */ ignoreQuotePrefix?: boolean; /** * If `true`, dates parsed as numbers will follow the 1904 date system. * When not specified, the setting is inherited from the containing cell's configuration. * * @defaultValue inherited from the cell container */ date1904?: boolean; /** * When `true`, strings in the format `m/d/yy` will be automatically parsed as dates. * This option is usually bypassed in favor of using localization for date formatting. * * @defaultValue false */ dateNF?: boolean; /** * Provides a custom callback for parsing strings during updates. This is particularly * useful for handling complex data transformations in CSV imports or other data bindings. * * - The `context` parameter supplies cell-specific information and utility methods. * - The callback should return an `ICell.Update` object, or `undefined` to use the default parsed value. * * @param text The input string to parse. * @param context The context providing access to cell-specific information for parsing. * * @returns The parsed `ICell.Update` object, or `undefined` to use the default value. */ parse?: (text: string, context: ICell.IteratorContext) => ICell.Update; } /** * Provides access to cell-specific information and utility functions during range iteration. * * This object serves as a context in the iterator, offering a convenient way to retrieve * the cell's coordinates, the full {@link ICell} object, and perform additional operations * like converting values to JavaScript dates or getting the cell's address. */ export interface IteratorContext { /** * Return the ScalarType of the value. */ getType(): ScalarType; /** * Retrieves the `ICell` associated with the current iteration. * * @remarks * `ICells` are dynamically created and are significantly slower to access than simple values. */ getCell(): ICell; /** * Retrieves the `IRange.CellCoords` associated with the current iteration. */ getCoords(): IRange.CellCoords; /** * Converts the given or current cell coordinates to their corresponding A1-style address string (e.g., 'A1'). * * @param coords The coordinates to convert. If not provided, the coordinates of the * current cell in the iteration will be used. * @returns The A1-style address string representing the cell coordinates. * * @remarks * The returned address can be used for further range queries or operations within the spreadsheet. */ getA1(coords?: Partial): string; /** * Convert the current value to a Javascript `Date` object, considering the containers's 1904 date system setting. * * @returns A JavaScript `Date` object representing the converted date, or `null` if the value is not a valid date (< 0 or greater than December 31, 9999). * * @remarks * Spreadsheets store dates internally as serial numbers (OADates) to optimize calculation performance. These are integer values representing * the number of days since either January 1, 1900, or January 1, 1904, depending on the container's settings. * * For type-safe date retrieval consider using the {@link ICell.toDate} method, which returns null if the cell value is not a valid date. * * @see * Refer to the following resources for more details: * {@link https://support.microsoft.com/en-us/office/date-systems-in-excel-e7fe7167-48a9-4b96-bb53-5612a800b487 | Date systems in Excel} * {@link https://learn.microsoft.com/en-us/dotnet/api/system.datetime.tooadate?view=net-8.0 | DateTime.ToOADate Method} */ toJSDate(value?: number): Date | null; } /** * Describes how text overflows horizontally outside the normal cell boundaries, * either to the left, right, or both. This is commonly used for features like * "Text Overflow" or "Center Continuous" in cells. */ export interface HorizontalOverflow { /** * The number of cells to the left that the content overflows into. * Ignored if not greater than 0. This value represents cells, not pixels. * * @defaultValue 0 */ leftIndex: number; /** * The number of cells to the right that the content overflows into. * Ignored if not greater than 0. This value represents cells, not pixels. * * @defaultValue 0 */ rightIndex: number; /** * The number of pixels by which the content overflows to the left of the current cell. * Ignored if not greater than 0. * * @defaultValue 0 */ leftOffset: number; /** * The number of pixels by which the content overflows to the right of the current cell. * Ignored if not greater than 0. * * @defaultValue 0 */ rightOffset: number; /** * The number of cells spanned by the overflow. Typically, this is 1, but * can be greater when a continuous fill is applied to the overflow. * * @defaultValue 1 */ colSpan: number; /** * The bounding box of the content within the cell, excluding any overflow. * This is relative to the cell's original size. */ colBounds: Bounds; /** * The relative position of the content's anchor within the cell. * Defines where the anchor point of the content is located. */ anchorBounds: Bounds; } /** * A value encoded as a number with an associated type. */ export interface JSONTypedValue { t: ScalarType; v: number; } /** * Reexports the `IRange.CellCoords` type for use in cell coordinates. */ export type Coords = IRange.CellCoords; /** * JSON values types that have their type embedded in the * 'format'. * * @remarks * A string value is the string id in the `IStringsCollection`. */ export type JSONUnTypedValue = number | boolean | string; /** * For persisting a single Cell value and type. * * @remarks * Styling and other advanced properties are stored as ranges. */ export type JSON = JSONUnTypedValue | JSONTypedValue; /** * Represents the calculation status. */ const CalcStatus: { /** * The cell's value is up-to-date and reflects the latest calculation. */ readonly Ready: "ready"; /** * The cell's value may not reflect the latest calculation, typically due to the calculation engine being in manual mode. */ readonly Stale: "stale"; /** * The cell's value is being calculated asynchronously, typically because the function used returned a Promise. * All dependent cells will also be in the Pending state. If the promise returns an error or times out, the cell's value will be an error value. */ readonly Pending: "pending"; /** * The cell's value is up-to-date, but the underlying data source is streaming live updates. */ readonly Streaming: "streaming"; }; export type CalcStatus = typeof CalcStatus[keyof typeof CalcStatus]; /** * Represents the types of content that can be associated with a cell or range. */ const Content: { /** * Represents the actual values stored in the cells (numbers, text, booleans, etc.). */ readonly Values: "values"; /** * Represents the formatting and styling applied to the cells (fonts, colors, borders, etc.). */ readonly Formats: "formats"; /** * Represents the formulas contained within the cells. */ readonly Formulas: "formula"; /** * Represents hyperlinks associated with the cells. */ readonly Hyperlinks: "hyperlinks"; /** * Represents tables associated with the cells. */ readonly Tables: "tables"; /** * Represents notes associated with the cells. * @remarks * **NOT IMPLEMENTED** */ readonly Notes: "notes"; /** * Represents comments attached to the cells. */ readonly Comments: "comments"; /** * Represents warnings or informational messages associated with the cells. */ readonly Warnings: "warnings"; /** * Represents error values (e.g., #DIV/0!, #N/A) within the cells. */ readonly Errors: "errors"; /** * Represents values that have merge spans. */ readonly Merges: "merges"; }; export type Content = typeof Content[keyof typeof Content]; } /** * Contains a set of resources that can be shared across multiple cell containers. * * @remarks * Used by both workbooks and sheets. */ export declare interface ICellContainerOptions { /** * Option to provide shared strings. */ strings?: IStringCollection; /** * Option to provide a shared StyleCollection. If not provided then a new StyleCollection with default theming will be used. */ styles?: IStyleCollection; /** * Option to provide shared resources. */ resources?: IResourceCollection; /** * Option to provide shared names. * * @remarks * This is not the interface because we want the instance that allows * for adding items other than named ranges. */ names?: INamedCollection; /** * Option to provide a custom calculation. */ calculation?: ICalculation; /** * If the parent has a workbook */ workbook?: IWorkbook; /** * The store for all state changes. This is provided to enable versioning, undo/redo, distributed editing, etc. * * @remarks * If not specified then an internal {@link ITransaction.IStore} will be created. */ transactions?: ITransaction.IStore; /** * Allows for address to be resolved in custom ways. * * @remarks * * This should return `null` if unresolvable but only throw and error if it is identified a a parsing error. * * This is used by `INamedCollection` to created named ranges. */ resolveRange?: (address?: ICellRange.Address) => ICellRange | null; /** * Determine if dates should be 1904 or 1900 based. * * @defaultValue false */ date1904?: boolean; /** * If `true` then the model is readonly and cannot be save. * * @defaultValue false * * @remarks * Useful when you want to load a model for viewing only and prevent any accidental changes. */ readonly?: boolean; } /** * A logic label for an entire span of cells in either direction. */ export declare interface ICellHeader { /** * The absolute size in pixels. */ getSize(): number; /** * Returns the header display. */ getDisplayText(): string; /** * The style for the header. * * @remarks * This represents a default style for the entire span. It generally is not used for formatting the header * itself. */ getStyle(): IStyle; /** * Returns orientation for the header. */ getOrientation(): IRange.Orientation; /** * Flag to indicate if column is hidden. Note - A column with a size > 0 but hidden is true is valid * because when hiding a value we don't change the size so that an unhide will restore to it's previous location */ isHidden(): boolean; /** * Note - size can be a function of autoFitting isCustomSize means the field has set by the user * and should not be autoSize due to autoFitting (unless explicitly done so by a user gesture) */ isCustomSize(): boolean; /** * Creates a new detected header from the modifiers. */ createTemporaryCellHeader(update: ICellHeader.Modifiers): ICellHeader; /** * If a cell has no sizing or custom formatting. */ isEmpty(): boolean; /** * Returns true if the headers are logically equal. * @param other */ isEqual(other: ICellHeader): boolean; /** * Returns the header as an ICell. */ asCell(): ICell; /** * Rows and columns sizes are managed internally as relative size to the normal styling font size. * This is done to allow for the sizes to auto adjustment when the style changes. * * @see * {@link https://support.microsoft.com/en-us/office/change-the-column-width-and-row-height-72f5e3cc-994d-43e8-ae58-9774a0905f46} */ getSizeRelative(): number; /** * For runtime introspection. */ get isICellHeader(): true; } /** * {@inheritDoc ICellHeader} * @see * ### **Interface** * * {@link ICellHeader} */ export declare namespace ICellHeader { /** * Combine various ways to update a CellHeader. */ export type Update = ICellHeader.Modifiers | ICellHeader | null; /** * Allows for headers to be updated. */ export interface Modifiers { /** * The size of the header in either absolute or relative value. * * @default 'The default size for the sheet' * * @remarks * If the size is set to a 0 this will become hidden even if hidden is set to `false`. * * @see * {@link relativeSize} */ size?: number | string | ((size: number) => number); /** * @see * {@link ICellHeader.isHidden()} */ hidden?: boolean; /** * @see * {@link ICellHeader.isCustomSize()} */ autoSize?: boolean; /** * @see * {@link ICellHeader.getSizeRelative()} */ relativeSize?: boolean; /** * @see * {@link ICellHeader.getStyle()} */ style?: IStyle.Update; } /** * Stores information about header runs. */ export interface JSON { min: number; max: number; /** * Size - height or width */ sz?: number; /** * Custom size */ csz?: boolean; /** * Hidden */ h?: boolean; /** * Style id */ s?: number; /** * Header level */ l?: number; /** * Collapsed level */ cl?: boolean; } } /** * Represents a collection of ICellHeaders. */ export declare interface ICellHeaderRange { /** * The RunCoords for the range. */ getCoords(): ICellHeaderRange.Coords; /** * Iterate over cells headers. * * @remarks * * Callbacks can return a 'break' value to stop the visit. */ forEach(callback: ICellHeaderRange.ForEachCallback, options?: ICellHeaderRange.IteratorOptions): T | void; /** * Returns the header at a location relative to the range. * * @param index */ at(index: number): ICellHeader; /** * Set the size of the headers. * * @param size This can be a number of a string with units * @param options {@link ICellHeaderRange.SetSizeOptions} */ setSize(size?: number | string, options?: ICellHeaderRange.SetSizeOptions): this; /** * Hides or show the columns for the given range. * * @defaultValue false */ setHidden(hidden?: boolean): this; /** * Provides a convenient method for setting values with a range of calls. * * @remarks * If an array is provided then values will be in row-major order and will * repeat if the range is larger than the array */ updateHeaders(values: ICellHeader.Update, options?: ICellHeaderRange.UpdateHeadersOptions): this; /** * Returns the data ranges for headers that contain information. * * @remarks * * This is NOT the last cell that may have data or has been resized. * * This also has nothing to do with the selection bounds. */ getUsedRange(options?: ICellHeaderRange.GetRangeOptions): this; /** * Clear the header format. Specially this will clear the sizes. */ clear(): this; /** * Returns the number of headers included in the range. */ getCount(): number; /** * Returns the number of headers. */ getHeaderCount(): number; /** * Returns the number of visible headers in the range. */ getVisibleCount(): number; /** * Returns true if the range represents all headers. */ isEntireHeaders(): boolean; /** * Returns the header orientation. */ getOrientation(): IRange.Orientation; /** * Similar to {@link forEach} but only spans that are different. * * @remarks * * Callbacks can return a 'break' value to stop the visit. */ forEachSpan(callback: ICellHeaderRange.ForEachSpanCallback, options?: ICellHeaderRange.IteratorOptions): T | void; /** * Visits visible spans. * * @remarks * * If there are no hidden headers this will still be called once. */ forEachVisibleSpan(callback: ICellHeaderRange.ForEachVisibleSpanCallback, options?: ICellHeaderRange.ForEachVisibleSpanOptions): T | void; /** * {@inheritDoc ICellRange.getSnapshot} */ getSnapshot(options?: ICellHeaderRange.CopyOptions): ICellHeaderRange.ISnapshot; /** * Perform operation on all ranges. * * @see * {@link ICellRange.doBatch} */ doBatch(callback: (commit: ITransaction.ICommit) => R | Promise, options?: string | ICellHeaderRange.UpdateHeadersOptions): R | Promise; /** * Returns the SheetHeader. */ getSheetHeader(): S; /** * {@inheritDoc ICellRange.getA1} */ getA1(): string; /** * Returns the address as a string. */ toString(): string; /** * For runtime type checking. */ readonly isICellHeaderRange: true; } /** * {@inheritDoc ICellHeaderRange} * @see * ### **Interface** * * {@link ICellHeaderRange} */ export declare namespace ICellHeaderRange { /** * The coord type for a header range. */ export type Coords = RunCoords; /** * Specify either a range a run or a string. * @remarks * If the value is a string it will be parse as an a1 style address if it is a number it will be a zero based index. */ export type Address = Partial | RunCoords | string | number; /** * Callback used for visiting a cells headers. If break is returned the visiting will stop with the * break value returned. * * The context allows for the retrieval of additional information associated with the Cell include the * {@link ICellHeader} object. */ export interface ForEachCallback { (size: number, context: ICellHeaderRange.CellHeaderContext): { break: T; } | void; } export interface IteratorOptions { /** * The address for the range. */ address?: ICellHeaderRange.Address; /** * Include all headers even empty ones. * @defaultValue false */ includeEmpty?: boolean; /** * Only include if the size is set and different from the default. * @defaultValue false */ includeSizes?: boolean; /** * Include headers that have custom styling. * @defaultValue false * @deprecated We are removing styles from headers (but will need in sheet for backward compatibility with Excel) */ includeStyles?: boolean; /** * When scanning skip cells that are hidden via headers. * @defaultValue false * @remarks * optionally a header orientation for skipping case be passed in. * An example of this is for sorting where the sort direction (row) skips hidden rows but the column direction does not. */ ignoreHidden?: boolean; } /** * Context for Iterators to provide access to the `IRange.CellCoords`, the `ICellHeader`, and additional operators. */ export interface CellHeaderContext { /** * Returns the index for the header */ getIndex(): number; /** * Returns the CellHeader. */ getCellHeader(): ICellHeader; /** * Utility method to return the offset as an A1 string. */ getA1(offset?: number): string; /** * Returns the coords for the header. */ getCoords(): RunCoords; } /** * Simple type to pairs an address with an update value. */ export interface AddressUpdatePair { /** * Allows for either a Cell or a Range. */ address?: ICellHeaderRange.Address; /** * If null will clear the value. */ update: ICellHeader.Update; } export interface ForEachSpanCallback { (size: number, context: ICellHeaderRange.CellHeaderContext): { break: T; } | void; } export interface ForEachVisibleSpanCallback { (min: number, max: number): { break: T; } | void; } export interface ForEachVisibleSpanOptions { includeHidden?: boolean; } export interface GetRangeOptions { } /** * Options for copying ICellHeaderRange. */ export interface CopyOptions extends ICellRange.SetValuesOptions, ReferenceableClipboard.CopyOptions { /** {@inheritDoc ICellRange.CopyOptions.fitDestination} */ fitDestination?: boolean; } /** * Options for `updateHeaders`. */ export interface UpdateHeadersOptions extends ITransaction.OperationOptions { /** * If this is set to `true` then any headers that have custom sizes will be ignored. * @defaultValue false */ skipCustomSize?: boolean; } /** * Options for `setSize`. */ export interface SetSizeOptions extends ITransaction.OperationOptions { /** * Sets if the size value is interpret as absolute or relative. * @defaultValue false * * @remarks * Rows and columns sizes are managed internally as relative size to the normal styling font size. * This is done to allow for the sizes to auto adjustment when the style changes. * * If the value is a number then the size is interpreted as relative size. * * If the size is set using a string that ends in 'px' This option will be ignored. * * @see * * {@link ICellHeader.getSizeRelative()} * * {@link https://support.microsoft.com/en-us/office/change-the-column-width-and-row-height-72f5e3cc-994d-43e8-ae58-9774a0905f46} */ relativeSize?: boolean; /** * If this is set to `true` then the value will not be an autoSize value. * * @defaultValue false */ autoSize?: boolean; /** * If this is set to `true` then any headers that have custom sizes will be ignored. * * @defaultValue false */ skipCustomSize?: boolean; } /** * A snapshot of a header to use for laster copying. */ export interface ISnapshot { /** * Called when the item is copied to a new header range. */ copyTo(range: ICellHeaderRange, options?: ICellHeaderRange.CopyOptions): Promise | RunCoords; /** * The RunCoords that bounds the current item. */ getCoords?(): RunCoords; /** * Allow items to be copied as text. */ toText?(): Promise | string; /** * Allow items to be copied as html. */ toHtml?(): Promise | string; /** * Allow items to be copied as an image Blob. */ toImage?(): Promise | Blob; /** * The source that created the snapshot. * This is used by copy to quickly do comparisons. */ getSource(): T; /** * A user friendly name of a the snapshot item. */ getName?(): string; /** * For runtime type checking. */ readonly isISnapshot: true; } } /** * An `ICellHeaderRanges` is a collection of {@link ICellHeaderRange}s. * * Useful when working with a discontinuous set of headers. */ export declare interface ICellHeaderRanges { /** * The RunCoords for the range. */ getCoords(): Readonly; /** * Returns the header range at a location relative to the range. * * @param index */ at(index: number): ICellHeaderRange; /** * Returns the number of headers ranges. */ getCount(): number; /** * {@inheritDoc ICellHeaderRange.setSize} */ setSize(size?: number | string, options?: ICellHeaderRange.SetSizeOptions): this; /** * {@inheritDoc ICellHeaderRange.setHidden} */ setHidden(hidden?: boolean): this; /** * {@inheritDoc ICellHeaderRange.clear} */ clear(): this; /** * Returns the number of headers. * * @remarks * This will remove overlaps. */ getHeaderCount(): number; /** * {@inheritDoc ICellHeaderRange.getVisibleCount} */ getVisibleCount(): number; /** * Returns true if all of the ranges cover the entire headers. */ isEntireHeaders(): boolean; /** * Returns true if any of the ranges cover entire headers. */ isEntireHeadersAny(): boolean; /** * {@inheritDoc ICellHeaderRange.getOrientation} */ getOrientation(): IRange.Orientation; /** * {@inheritDoc ICellHeaderRange.updateHeaders} */ updateHeaders(values: ICellHeader.Update, options?: ICellHeaderRange.UpdateHeadersOptions): this; /** * {@inheritDoc ICellHeaderRange.doBatch} */ doBatch(callback: (commit: ITransaction.ICommit) => R | Promise, options?: string | ICellHeaderRange.UpdateHeadersOptions): R | Promise; /** * {@inheritDoc ICellHeaderRange.getSheetHeader} */ getSheetHeader(): S; /** * {@inheritDoc ICellHeaderRange.getA1} */ getA1(): string; /** * {@inheritDoc ICellHeaderRange.toString} */ toString(): string; /** * For runtime type checking. */ readonly isICellHeaderRanges: true; } /** * {@inheritDoc ICellHeaderRanges} * @see * ### **Interface** * * {@link ICellHeaderRanges} */ export declare namespace ICellHeaderRanges { /** * The coord type for a header ranges. */ export type Coords = RunCoords[]; /** * Address for multiple {@link ICellHeaderRange}s. */ export type Address = ICellHeaderRanges | string | ICellHeaderRange.Address | readonly ICellHeaderRange.Address[]; /** * Shorthand for persisting. */ export type RefJSON = RunCoords[] | RunCoords | string; } /** * Additional cell protection properties. * */ export declare interface ICellProtection { /** * This is specified in ooxml but not sure what behavior it has. * @defaultValue true */ isEditAllowed(): boolean; /** * If the formula will be hidden when the worksheet is protected. * @remarks * This is called hidden in ooxml but in Excel object model it is formulaHidden. * @defaultValue false */ isFormulaHidden(): boolean; /** * For runtime type checking. */ readonly isICellProtection: true; } /** * {@inheritDoc ICellProtection} * @see * ### **Interface** * * {@link ICellProtection} */ export declare namespace ICellProtection { /** * Properties for ICellProperties. */ export interface Properties { edit?: boolean; formulaHidden?: boolean; } export interface JSON extends Properties { } } /** * A {@link ICellRange} represents a rectangular collection of {@link ICell} * within an {@link ISheet}. * * **Naming Conventions:** Methods usually adhere to the following conventions except * when adhering to a idiomatic existing conventions of Typescript (for example `size` or 'length'): * * - Methods returning information about the range (e.g., width, count) use a `get` prefix. * - Methods that transform the range's data into a different type use a `to` prefix (e.g., `toArray()`). */ export declare interface ICellRange { /** * Return an array of coords for all merges. * * * @returns A array of 'IRange.Coords` that contain merges. */ getMerges(): IRange.Coords[]; /** * Returns a cell in the range. * * @param address The address of the cell to retrieve. This must be within the range bounds. Default Value the 'top left' * * @see * {@link ICellRange.getCells} */ getCell(address?: ICell.Address): ICell; /** * Return a 2D array of {@link ICell | cells} in the shape of the range. * * @param options {@link ICellRange.GetValuesOptions} * @returns A 2D array of {@link ICell}s. * * @remarks * * Empty values will be `null`. * * {@link ICellRange.GetValuesOptions.asJSDate} is ignored; use {@link ICell.asDate()} when working with {@link ICell}. */ getCells(options?: ICellRange.GetValuesOptions): ICell[][]; /** * Returns the value for the top left `Scalar`. * * @remarks * The `ignoreHidden` option is ignored. * * @see * {@link ICellRange.getValues} */ getValue(options?: ICellRange.GetValuesOptions): Scalar | JSScalar; /** * Returns the style for the ranges. * * @see * {@link ICellRange.getStyle} */ getStyle(): IStyle; /** * Returns the intersection of the current range and the specified range. * * @param address The address of the other range to intersect with.. * @returns `ICellRange` at the intersection of the two ranges, or `null` if there's no overlap. */ getIntersect(address?: ICellRange.Address, options?: ICellRange.GetRangeOptions): this | null; /** * Returns the union of the current range with the specified range. * * @param address The address of the other range to intersect with. * @returns `ICellRange` at the union of the two ranges. */ getUnion(address?: ICellRange.Address, options?: ICellRange.GetRangeOptions): this; /** * Returns a set of non-overlapping ranges the represents the difference between the current * range and the specified range. * * @param address The address of the range to subtract from the current range. * @returns `ICellRanges` containing the resulting non-overlapping ranges, * or `null` if: * - There is no intersection between the current range and the specified address. * - The specified address is the same as or encompasses the current range. * * @remarks * - The method will always return between 0 and 4 ranges. * - If there's no intersection, it returns an `ICellRanges` containing only the current range. */ getDifferences(address: ICellRange.Address, options?: ICellRange.GetRangeOptions): ICellRanges | null; /** * Returns a range that includes the columns for the entire sheet. * For example, if the range is `A1:B2`, this method will return `A:B`. * * @param shift If `true` this will also shift the columns by the width of the range. default `false`. * @param options Additional options for getting the range. * @returns `ICellRange` at the repositioned range. */ getEntireColumns(shift?: boolean, options?: ICellRange.GetRangeOptions): this; /** * Returns a range that includes the rows for the entire sheet. * For example, if the range is `A1:B2`, this method will return `1:2`. * * @param shift If `true` this will also shift the rows by the height of the range. default `false`. * @param options Additional options for getting the range. * @returns `ICellRange` at the repositioned range. */ getEntireRows(shift?: boolean, options?: ICellRange.GetRangeOptions): this; /** * Returns a range that includes the current range up to a content edge boundary. * * @param direction The direction. * @param cell The cell to use as a starting point. * If not provide the cell closest to the edge will be used. * @returns `ICellRange` extended in the given direction. */ getExtended(direction: IRange.Direction, cell?: ICell.Address): this; /** * Returns a range with coordinates adjusted to be fixed (absolute) or flexible (relative). * * @param options Either a {@link ICellRange.GetFixedOptions} object to * specify individual coordinate settings, or a `boolean` * to adjust all coordinates at once. If a `boolean` is provided: * - `true` sets all coordinates to absolute. * - `false` sets all coordinates to relative. * @returns `ICellRange` with updated coordinate references types. * * @remarks * If no `options` are provided, this method toggles the fixed flags for the range's coordinates * based on their current settings. Calling this repeatedly will cycle between relative and absolute references. * For example: `A1` → `$A$1` → `A$1` → `$A1` → `A1` */ getFixed(options?: ICellRange.GetFixedOptions | boolean): this; /** * Returns a range with the top-left corner moved by the specified row and column offsets. * * @param rowDelta The number of rows to move the top-left corner up (negative) or down (positive). * @param colDelta The number of columns to move the top-left corner left (negative) or right (positive). * @returns `ICellRange` at the repositioned range. */ getOffsetBy(rowDelta: number, colDelta: number, options?: ICellRange.GetRangeOptions): this; /** * Returns a range repositioned to the specified starting row and column indices. * * @param rowStart The new starting row index (inclusive). * @param colStart The new starting column index (inclusive). * @returns `ICellRange` at the repositioned range. */ getOffsetTo(rowStart: number, colStart: number, options?: ICellRange.GetRangeOptions): this; /** * Returns a range with the bottom-right corner moved by the specified row and column offsets. * * @param rowDelta The number of rows to move the bottom-right corner up (negative) or down (positive). * @param colDelta The number of columns to move the bottom-right corner left (negative) or right (positive). * @returns `ICellRange` with the resized range. */ getResizeBy(rowDelta: number, colDelta: number, options?: ICellRange.GetRangeOptions): this; /** * Resizes the current range to the specified ending row and column indices. * * @param rowEnd The new ending row index (inclusive). * @param colEnd The new ending column index (inclusive). * @returns `ICellRange` with the resized range. */ getResizeTo(rowEnd: number, colEnd: number, options?: ICellRange.GetRangeOptions): this; /** * Returns a range with surrounding data or the entire range if there is no data nearby. * * @returns `ICellRange` containing either nearby content or the entire range. */ getSurrounding(options?: ICellRange.GetSurroundingOptions): this; /** * Returns the smallest range within the range that contains any used cells. * * This method returns the range of cells that have been "used," which includes cells with data, * as well as certain types of formatting or styling. It focuses on cells that have been interacted with * in some form, whether through data entry or other modifications. Merged cells and overflow values * may not always be included in this range. * * @returns `ICellRange` that contains the smallest range with used cells, or `null` if the range is empty. */ getUsedRange(options?: ICellRange.GetRangeOptions): this | null; /** * Returns a range that excludes any hidden rows or columns. * * @param options Optional parameters that can adjust how visibility is determined (e.g., by ignoring specific visibility rules). * @returns An `ICellRanges` object that contains the visible portions of the range, excluding any hidden rows or columns. * * @remarks * - If all ranges within the original selection are visible, this method returns an `ICellRanges` object with a single range and a length of `1`. * - If the entire range is hidden, the method will return `null`. * - The resulting ranges reflect the currently visible state of the sheet, including hidden rows, columns, or headers. */ getVisible(options?: ICellRange.GetVisibleOptions): ICellRanges | null; /** * Returns the header range for the rows. * * @returns `ICellHeaderRange` for the rows. */ getRowHeaders(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange; /** * Returns the header range for the columns. * * @returns `ICellHeaderRange` for the columns. */ getColumnHeaders(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange; /** * Returns the default shift {@link IRange.Orientation} for {@link insert} and {@link delete} * if no orientation is provided. * * @returns Default `IRange.Orientation` that will be used to shift the range. * @remarks * By default the direction of the shift will be the direction that shifts the fewest cells. If * the range is the same size in both directions `IRange.Orientation.Row` will be used. * * For example, a range with 5 columns and 1 row will have a default orientation of `IRange.Orientation.Row`. */ getDefaultShiftOrientation(): IRange.Orientation; /** * Returns a default sort that would be used if no overrides where provided. * * @param orientation The orientation to sort. Default Value `IRange.Orientation.Row`. * @param cell A cell location that can be used to determine the sort column. * @returns Default `ISort.DefaultSortCriteria` or `null` if there is not valid sort criteria. * * @remarks * Useful for displaying options to the ui. The default behavior will look for headers and * merges. */ getDefaultSortCriteria(orientation?: IRange.Orientation, cell?: ICell.Address): ISort.DefaultSortCriteria | null; /** * Returns a count for of values. */ getCount(): number; /** * Returns a record of multiple counts for the given types. * * @param types The type of content to count. If not specified it will return the context for all content types` * */ getCounts(types?: ICell.Content[]): ICellRange.Counts | null; /** * Returns a 2D array of {@link Scalar | values} in the shape of the range. * * @param options - * - `asJSDate` Return dates as Javascript dates instead of OADates but is slower due to need * to determine if the Cell is a date or a number. See {@link ICell.IteratorContext.toJSDate}. * defaultValue `false`. * - `maxSize` Limit the size of the results. defaultValue `10000`. * * @returns A 2D array of values. * * @remarks * * Empty values will be `null`. * * This is faster than {@link getCells} when only the values are needed. * * Setting {@link ICellRange.GetValuesOptions.asJSDate} to `true` will add make slower. */ getValues(options?: ICellRange.GetValuesOptions): Scalar[][]; /** * Returns the range value as a string. */ toText(options?: ICellRange.ToTextOptions): string; /** * Set the value(s) of one or more cells within a range. * * @param values The value to be set or a callback that will generate a value. * @param options {@link ICellRange.SetValuesOptions} * @returns The current `ICellRange`. * * @remarks * - `null` values will clear the corresponding cells. * - `undefined` values will be ignored, leaving the existing cell values unchanged. * - If an array is passed the values will be in row-major order and will repeat if the range is larger than the array * - If a single value is passed in it will repeat the entire range. */ setValues(values: ICellRange.ValuesUpdate, options?: ICellRange.SetValuesOptions): this; /** * Provides a convenient method for setting values with a range of calls. * * @param update {@link ICellRange.Update} * @param options {@link ICellRange.UpdateCellsOptions} * @returns The current `ICellRange`. * * @remarks * - **Performance** This is will always be significantly slow than setting attributes * use the related range APIs. * - For setting non contiguous values see {@link ICellRange.startIncrementalUpdates} * @see * * {@link updateStyle} * * {@link setHyperlink} */ updateCells(update: ICellRange.Update, options?: ICellRange.UpdateCellsOptions): this; /** * Set a single value to the entire range. * * @see * {@link ICellRange.setValues} */ setValue(value: ICellRange.ValuesUpdateOrCallback, options?: ICellRange.SetValuesOptions): this; /** * Set the formula for a range. * * @remarks * Identical behavior to setValue. Exists for ergonomics * @see * {@link ICellRange.setValue} */ setFormula(value: ICellRange.ValuesUpdateOrCallback, options?: ICellRange.SetValuesOptions): this; /** * Re-evaluates and formulas within the range. * @param full If `true` then all formulas will be recalculated. */ calculate(full?: boolean): this; /** * Fill the range to a destination using an array of {@link IAutoFill.Filler}. * * @param destination The range to autoFill including the current range. * @param options {@link ICellRange.AutoFillOptions} * @throws `Error` If the destination range does not overlap with the range on 3 out of 4 sides. * @returns `ICellRange` at the destination. * * @remarks * * If the range contains merges then the amount must be a 'fill' dimension must a multiple of the initialRange 'fill' dimension. * * The destination range must be the same size as the original with 1 edge adjusted. */ autoFill(destination: ICellRange.Address, options?: ICellRange.AutoFillOptions): this; /** * Adjusts the column widths and rows heights to fit the content. * * @param options {@link ICellRange.AutoFitOptions} * @returns Current `ICellRange`. */ autoFit(options?: ICellRange.AutoFitOptions): this; /** * Clear the range. * * @param applyTo {@link ICell.Content} @defaultValue ICell.Content.Values * @param options {@link ITransaction.OperationOptions} * @returns Current `ICellRange`. */ clear(applyTo?: ICell.Content, options?: ITransaction.OperationOptions): this; /** * Set the hyperlink for a range of values. * * @param hyperlink {@link IHyperlink.Update} * @param options {@link ITransaction.OperationOptions} * @returns Current `ICellRange`. * * @remarks * To clear hyperlinks either set to `null` or call `clear(ICell.Content.Hyperlinks)`. */ setHyperlink(hyperlink: IHyperlink.Update, options?: ITransaction.OperationOptions): this; /** * Update the comments for the range. * * @param comments Comment properties * @param options {@link ITransaction.OperationOptions} * @returns Current `ICellRange`. * * @remarks * **NOT FINISHED** */ setComments(comments: IComment.Properties, options?: ITransaction.OperationOptions): this; /** * Merges all cells within the selection ranges. * * @param options {@link ICellRange.MergeOptions} * @returns Current `ICellRange`. * * @remarks * If the ranges overlap then this operation will throw an exception */ merge(options?: IRange.Orientations | ICellRange.MergeOptions): this; /** * Unmerge all cells within the selection ranges. * * @param options {@link ITransaction.OperationOptions} * @returns Current `ICellRange`. */ unmerge(options?: ITransaction.OperationOptions): this; /** * Returns an iterator of ICells that match the results. * * @param options The text to search for or {@link FindOptions} */ find(options: string | ICellRange.FindOptions): Iterator; /** * Sort the given range. * * @param options `boolean` | {@link ISort.RangeOptions} * @returns Current `ICellRange`. * * @remarks * The sorting of various data types has a default priority of of boolean > string > number and dates are treated as numbers. * If `true` then the sort is reversed (descending). */ sort(options?: boolean | ISort.RangeOptions & ITransaction.OperationOptions): this; /** * Insert a new, empty range within the sheet and shifts existing cells to accommodate it. * * By default the values will direction in whichever direction the selection shape is smaller. * For example a selection with a 5 column by 1 row will direction Down (rows). * Note - This will error if direction data will fall outsize of the max sheet size. * @param options The orientation or The direction in which to shift existing cells. * Defaults to the orientation where the range's dimension is smaller (e.g., shifts down if the range is wider than it is tall). * See {@link ICellRange.getDefaultShiftOrientation} for details on the default behavior. * See {@link ITransaction.OperationOptions} * @throws `Error` If the insertion would cause data to exceed the maximum sheet size. * @returns Current `ICellRange`. */ insert(options?: IRange.Orientation | ICellRange.InsertOptions): this; /** * Delete the cells within the range and shifts the remaining cells to fill the gap. * * @param options The orientation or The direction in which to shift existing cells. * Defaults to the orientation where the range's dimension is smaller (e.g., shifts down if the range is wider than it is tall). * See {@link ICellRange.getDefaultShiftOrientation} for details on the default behavior. * See {@link ITransaction.OperationOptions} * @returns Current `ICellRange`. * * @remarks * This is different from clearing cells, which removes their content but doesn't affect the * overall sheet structure. Deleting cells results in a shift of the remaining data. */ delete(options?: IRange.Orientation | ICellRange.DeleteOptions): this; /** * Returns a snapshot of the current range's data and formatting suitable for copying or archiving. * * @param options Default options to apply during the copy operation. * @returns A `ISnapshot` object representing the range. * * @remarks * - **Option Merging:** If options are also provided during the copy operation, the two will be merged * with the copy options taking precedence. * - `getSnapshot` can be called multiple times allowing for multiple snapshots. */ getSnapshot(options?: ICellRange.CopyOptions): ICellRange.ISnapshot; /** * Inserts the contents of the `source` into the sheet, shifting existing cells to make space. * * @param source The source of the data and formatting to insert. * This can be either a range address, another range object, or an `ISnapshot` * created using the `getSnapshot` method. * @param options {@link ICellRange.InsertFromOptions} * @returns A promise that resolve to an `ICellRange` or 'null' when the copy has completed. * * @remarks * * Behaves similarly to {@link insert} and {@link copyFrom}, but instead of inserting empty space at the range * it also inserts the content of the `source`. * * Will return `null` if nothing was inserted or the source doesn't have a range. */ insertFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.InsertFromOptions): Promise; /** * Copies (or cuts) data and formatting from a specified source to the current range. * * @param source The source of the data and formatting to be copied or cut. * This can be either a range address, another range object, or an `ISnapshot` * created using the `getSnapshot` method. * @param options Additional options for customizing the paste operation (e.g., `transpose`, `skipBlanks`). * @returns A promise that resolve to an `ICellRange` or 'null' when the copy has completed. * * @remarks * * Will return `null` if nothing was inserted or the source doesn't have a range. * @see * {@link ICellRange.getSnapshot} */ copyFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.CopyOptions): Promise; /** * Update the protection for the range. * * @returns Current `ICellRange`. * * @remarks * Setting to `null` will remove protections. */ /** * Perform a set of operations as a batch. * * @param callback Function to perform the operations. * @param options Description of the operation or additional options. This will be used for tracking undo/redo and history. @defaultValue 'Range Update' * @template R - The callback return type. * @returns The result of the callback. */ doBatch(callback: (commit: ITransaction.ICommit) => Promise | R, options?: string | ITransaction.OperationOptions): Promise | R; /** * Creates a `IncrementalUpdater` for efficiently updating sparsely populated cells in a streaming low memory way. * * For contiguous or mostly contiguous updates, the {@link ICellRange.updateCells} method is simpler * and will use {@link ICellRange.IncrementalUpdater} internally. * * @param options {@link ICellRange.StartUpdateOptions} * * @remarks * - **Ordering:** By default updates must be added in either row-major or column-major order, as specified * by the `orientation` parameter, with major/minor coordinates increasing monotonically. Unless * `allowUnorderedWrites` is set to `true out of order updates will result in an error. * - **Performance:** Setting `orientation` to `IRange.Orientation.Column` is generally faster as it aligns with the internal data representation. * - **Performance:** Setting `allowUnorderedWrites` adds a nominal performance overhead for all updates and will do a full apply when an * out of order update is detected. * The default `IRange.Orientation.Row` is provided for compatibility with common spreadsheet APIs. * - **Validation:** Data validation (e.g., for protected cells or boundaries) is performed when the `apply` method is called. * - **Transactions:** * - Adding values to the `IncrementalUpdater` only builds a temporary representation of the updates. * No actual changes are made to the sheet until `apply` is called. * - This allows for safe batching of updates within a single transaction using `doBatch`. * @example ```typescript startIncrementalUpdates const updates = range.startIncrementalUpdates() .push('A1', 2) .push('A2', 567) .push('A3', 3) .push('A4', 123) .push('A5', 1) .apply(); }); ``` */ startIncrementalUpdates(options?: ICellRange.StartUpdateOptions): ICellRange.IncrementalUpdater; /** * Returns `true` if there is any content within the range. * * @returns 'boolean' indicating if there is content. * * @remarks * Some uses cases for this are checking for data to delete a sheet, checking for multiple values * for merges. */ isContentful(): boolean; /** * Returns `true` if the range represents the entire rows. */ isEntireRows(): boolean; /** * Returns `true` if the range represents the entire columns. */ isEntireColumns(): boolean; /** * Returns `true` if the range represents both entire rows and entire columns. */ isEntireRange(): boolean; /** * Returns the width of the range. */ getWidth(): number; /** * Returns the height of the range. */ getHeight(): number; /** * Returns the size of the range this is the width * height. */ get size(): number; /** * Returns the absolute bounds for the range. */ getBounds(): Bounds; /** * Indicates if the range is readonly only. * * @remarks * Not an indicator of if the range is protected but rather * if the range is being used in a way that doesn't support write operations. * (e.g. the range is being provided as a listener source {@link ICellRange.Event} * or the range belongs to a historical snapshot.) */ isReadOnly(): boolean; /** * Returns the `Coords` an A1-style address string (e.g., 'A1' or 'A1:E5'). */ getA1(): string; /** * Returns the column start. */ getColumnStart(): number; /** * Returns the top of the range. */ getRowStart(): number; /** * Returns the right of the range. */ getColumnEnd(): number; /** * Returns the bottom of the range. */ getRowEnd(): number; /** * Returns the number of columns of the range. */ getColumnCount(): number; /** * Returns the number of rows of the range. */ getRowCount(): number; /** * Checks if the ranges is empty, meaning it has no values or formatting. * * @remarks * Convenience ```getUsedRange() !== null``` or `getCount() === 0`. * * @see * {@link ICellRange.getUsedRange} */ isEmpty(): boolean; /** * Returns the Sheet. */ getSheet(): ISheet; /** * The IRange.Coords. */ getCoords(): Readonly; /** * Returns true if the range is invalid. * This can occur if a range is removed or created with invalid coordinates. */ isInvalid(): boolean; /** * Returns the address as a string. */ toString(): string; /** * Selects the current range. * * @returns An async `ICellRange`. */ select(options?: ICellRange.SelectOptions): Promise; /** * Add a listener to the range. * * @param listener {@link ICellRange.Listener} * @param options {@link ICellRange.ListenerOptions} * @returns A callback to remove. {@link IListener.Remove} * * @remarks * If the range becomes invalid through a delete this will auto remove. */ addListener(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove; /** * Returns an iterator that allows you to iterate over the individual values within the range. * * @remarks * For more advanced iteration, use {@link ICellRange.entries} or {@link ICellRange.forEach}. */ [Symbol.iterator](): IterableIterator; /** * Returns an iterator that allows you to iterate over the individual entries within the range, * yielding pairs of `IteratorContext` and a `Value`. * * @param options Configuration options for the iterator, such as filtering or sorting. * @returns An iterator that yields `[ICell.IteratorContext, Value]` tuples for each value within the range. */ entries(options?: ICellRange.IteratorOptions): IterableIterator; /** * Returns the values within the range, yielding each value. * * @param options Configuration options for the iterator, such as filtering or sorting. * @returns An iterator that yields `[ICell.IteratorContext, Value]` tuples for each value within the range. */ values(options?: ICellRange.IteratorOptions): IterableIterator; /** * Iterates over the cells within the range, applying the provided callback function to each cell. * * This method is a more scalable alternative to `getValues` or `getCells` for large or sparse ranges, * as it: * 1. Skips empty values by default. * 2. Avoids creating large arrays. * 3. Allows for early termination. * @param callback A function that will be called for each non-empty cell in the range. The callback receives: * - `value`: The `Scalar` at the current cell. * - `context`: A `IteratorContext` object providing additional information and utilities for the cell. * - The callback can return `{ break: T }` to stop the iteration early. * @param options {@link ICellRange.IteratorOptions} for configuring which cells to visit. * @template R - The callback return type. * @returns The value returned by the callback function if it explicitly returned to stop the iteration early; otherwise, `void`. */ forEach(callback: ICellRange.ForEachCallback, options?: ICellRange.IteratorOptions): B | void; /** * For runtime type checking. */ readonly isICellRange: true; } /** * {@inheritDoc ICellRange} * @see * ### **Interface** * * {@link ICellRange} */ export declare namespace ICellRange { /** * This is either: * 1. Another ICellRange * 2. A string that can be parsed into a CellRange (e.g. 'A1:B2') or a named range. * 3. Partial IRange.FixableCoords */ export type Address = ICellRange | string | Readonly> | ICell.Address; /** * Single or 2D. */ export type Update = ICell.Update | readonly ICell.Update[][]; /** * Expands the CellUpdateValue to support a single value or arrays of arrays (2d arrays). */ export type ValuesUpdate = JSScalarUpdate | readonly JSScalarUpdate[][]; /** * Allows for Values to be set via a callback. */ export type ValuesUpdateOrCallback = ValuesUpdate | ((row: number, column: number) => T | null); /** * Options for `ISheet.getRange`. */ export interface GetRangeOptions { } /** * Options for `ICellRange.delete`. */ export interface InsertOptions extends ITransaction.OperationOptions { /** * The direction in which to shift existing cells. * Defaults to the orientation where the range's dimension is smaller (e.g., shifts down if the range is wider than it is tall). * See {@link ICellRange.getDefaultShiftOrientation} */ orientation?: IRange.Orientation; } /** * Options for `ICellRange.delete`. */ export interface DeleteOptions extends ITransaction.OperationOptions { /** * The direction in which to shift existing cells. * Defaults to the orientation where the range's dimension is smaller (e.g., shifts down if the range is wider than it is tall). * See {@link ICellRange.getDefaultShiftOrientation} */ orientation?: IRange.Orientation; } /** * Shorthand for persisting. */ export type RefJSON = IRange.Coords | string; /** * Options for configuring range coordinate reference types. * Each option allows you to specify whether a coordinate should be fixed * (absolute) or flexible (relative). * * @see * {@link ICellRange.getFixed} */ export interface GetFixedOptions { /** * If `true`, sets the starting row coordinate as absolute; if `false`, * sets it as relative. Defaults to no change if not provided. */ rowStart?: boolean; /** * If `true`, sets the starting column coordinate as absolute; if `false`, * sets it as relative. Defaults to no change if not provided. */ colStart?: boolean; /** * If `true`, sets the ending row coordinate as absolute; if `false`, * sets it as relative. Defaults to no change if not provided. */ rowEnd?: boolean; /** * If `true`, sets the ending column coordinate as absolute; if `false`, * sets it as relative. Defaults to no change if not provided. */ colEnd?: boolean; } /** * Options for {@link ICellRange.getSurrounding}. */ export interface GetSurroundingOptions { /** * If `true` then only the content will be included. * * @defaultValue false * * @remarks * If `true` then tables and sheet boundaries will be ignored mimicking the behavior * of 'Ctrl+Shift+*'. */ contentOnly?: boolean; } /** * A callback to enabled additional customization during copy. * * @remarks * Return `undefined` will leave the value undefined altered. */ export interface CopyCellsCallback { (value: Scalar, context: ICell.IteratorContext, to: IRange.CellCoords, options: ICellRange.CopyOptions): ICell.Update; } /** * Options for {@link ICellRange.ISnapshot.copyTo}. */ export interface CopyOptions extends ITransaction.OperationOptions, ReferenceableClipboard.CopyOptions { /** * When pasting from a smaller range to a larger range copy will repeat or 'wallpaper' the * source values. * * @remarks * Note - If the destination range is only a single cell then fitDestination will always be applied. */ fitDestination?: boolean; /** * Have the data transposed for the original orientation. * @defaultValue false */ transpose?: boolean; /** * If `true` then blank values will not be copied. * @defaultValue false */ skipBlanks?: boolean; /** * Indicate which items are copied. */ type?: ICell.Content; /** * Indicates if the header (size) should be copied. * @remarks * The default is to only copy the headers if the range is entire header span. */ includeHeaders?: boolean; /** * Allows for undo to range selection to be altered. * * @remarks * This is used to during drag. */ undoRange?: ICellRange; /** * Callback to allow for additional customizations. */ adjustCells?: ICellRange.CopyCellsCallback; } /** * Options for {@link ICellRange.insertFrom}. * * @remarks * This extends {@link ICellRange.CopyOptions} and adds an {@{@link IRange.Orientation}. */ export interface InsertFromOptions extends ICellRange.CopyOptions { /** * The direction in which to shift existing cells. * Defaults to the orientation where the copied range's dimension is smaller. * See {@link ICellRange.getDefaultShiftOrientation} for details on the default behavior. */ orientation?: IRange.Orientation; } /** * Options for {@link ICellRange.setValues}. */ export interface SetValuesOptions extends ITransaction.OperationOptions { /** * By default setValue will attempt to parse text values into a native type. * This can be disabled or customized using the parseText flag. * Setting this to false will use the raw text value. */ textParser?: boolean | ICell.ModifiersFromStringOptions; /** * Specifies the direction for iterating over the range (row-major or column-major). * * @defaultValue `IRange.Orientation.Row` * * @remarks * Both {@link SetValuesOptions} and {@link GetValuesOptions} allow for {@link IRange.Orientation}s. */ orientation?: IRange.Orientation; /** * Convenience method that calls autoFit after the setValues. * @defaultValue `none` - No autofit. * * @remarks * If set to `true` then autoFit will mimic the UI with the following options: ``` { skipCustomSize: true, expandOnly: true, minContent: true } ``` */ autoFit?: boolean | ICellRange.AutoFitOptions; /** * Skip the bounds check when setting values. * * @remarks * When set to `true`, this option allows value arrays to exceed the * dimensions of the range. This is useful for setting values in a table * where the range is smaller than the data, but determining the exact * size requires processing the entire dataset. */ skipBoundsCheck?: boolean; } /** * Options for {@link ICellRange.getValues}. */ export interface GetValuesOptions { /** * Return dates as Javascript dates instead of OADates. This is slower for values * that are numbers as the Style needs to be read to determine if the * value should be interpreted as a date or a number. See {@link ICell.IteratorContext.asJSDate}. * * @defaultValue false */ asJSDate?: boolean; /** * Limits the maximum number of values returned. An error will be thrown if results contain more values than `maxSize`. * * @defaultValue 10000 */ maxSize?: number; /** * Specifies the primary direction for iterating over the range (row-major or column-major). * * @defaultValue IRange.Orientation.Row * @remarks * Both {@link SetValuesOptions} and {@link GetValuesOptions} allow for {@link IRange.Orientation}s. */ orientation?: IRange.Orientation; /** * Reverses the iteration order (e.g., from bottom to top for rows, or from right to left for columns). * * @defaultValue false */ reverse?: boolean; /** * Excludes hidden cells from the returned values. * * @defaultValue false * * @remarks * - When enabled, the number of returned rows or columns might be less than the range size. * - If the entire range is hidden, the result will be empty and empty Array (`[]`). * - Optionally, you can specify a `IRange.Orientation` to indicate the header orientation for skipping cases. * For example, in sorting, you might want to skip hidden rows but not hidden columns. */ ignoreHidden?: boolean | IRange.Orientation; /** {@inheritDoc ICellRange.IteratorOptions.includeMergeOverflow} */ includeMergeOverflow?: boolean; } /** * Options for {@link ICellRange.toText}. */ export interface ToTextOptions extends ICellRange.GetValuesOptions { ignoreFormatting?: boolean; } /** * Options for {@link ICellRange.autoFit}. */ export interface AutoFitOptions extends ITransaction.OperationOptions { /** * Best fit using the minimum amount of space required. * * @defaultValue false * * @remarks * When `true` the numbers will include as few decimals as allowed overflow into the next cell. */ minContent?: boolean; /** * By default autoFit will adjust in both directions. * * @defaultValue false */ expandOnly?: boolean | IRange.Orientation; /** * If this is set to `true` then any headers that have custom sizes will be ignored. * * @defaultValue false */ skipCustomSize?: boolean; /** * The orientation to autoFit. * * @defaultValue IRange.Orientations.Both */ orientations?: IRange.Orientations; } /** * Options for {@link ICellRanges.getFlattened}. */ export interface GetFlattenOptions extends GetRangeOptions { /** * Returns a set of ranges with overlaps removed and attempts to merge adjacent ranges into larger ranges. * * @param orientations The overlap detection and initial merge orientation. * @param options Additional options to control range behavior. * @returns A new `ICellRanges` object with non-overlapping, and where possible, merged ranges. * * @defaultValue `IRange.Orientations.Both`. */ orientations?: IRange.Orientations; } /** * Options for {@link ICellRange.getVisible}. */ export interface GetVisibleOptions extends GetRangeOptions { /** * The visible orientations. * * @defaultValue `IRange.Orientations.Both` */ orientations?: IRange.Orientations; } /** * Callback that will return a a temporary cell given a coords. * @see * {@link ICell.createTemporaryCell}. */ export interface AutoFillPreviewCallback { /** * Reviews a temporary cell that can be used for previewing. * * @remarks * The {@link ICell | cell} is the cell from the corner. */ (destination: ICellRange.Address): ICell; } /** * Options for {@link ICellRange.autoFill}. */ export interface AutoFillOptions extends ITransaction.OperationOptions { /** * Provide custom fillers. * * @defaultValue `AutoFill.Types.Series` */ filler?: IAutoFill.Filler; /** * Options to pass to the `IAutoFill.Filler`. * @remarks * These will also be passed if a custom filler is used. */ fillerOptions?: IAutoFill.Options; /** * If `true` then will only copy values and not formatting. * * @defaultValue false (unless starting within a table) */ contentsOnly?: boolean; /** * If a previewOnly callback is provided then autoFill will not commit any changes but will * call previewOnly with a Preview function and then return the original range. * * Useful for creating tooltips. * * @defaultValue null */ previewOnly?: (callback: ICellRange.AutoFillPreviewCallback) => void; } /** * Options for {@link ICellRange.updateCells}. */ export interface UpdateCellsOptions extends SetValuesOptions { } /** * Provides an API for efficiently performing incremental updates to specific cells within a range. * * Unless {@link ICellRange.StartUpdateOptions.allowUnorderedWrites} is `true` the updates must be written * in row-major or column-major order as determined by {@link IRange.Orientation}, with major/minor * coordinates increasing on each update, otherwise an error will be thrown. * * @example * ```typescript * const updater = range.startIncrementalUpdates(); * updater.pushAt(1, 1, "Hello"); // as row, column, primitive - fastest * updater.push({ rowIndex: 2, colIndex: 1 }, { value: "Beautiful" }); // as coordinate and json object * updater.push('A3', { value: "World" }); // as a1 string and json * updater.apply(); * ``` * @template S - The return type of {@link apply}, typically the source range (`ICellRange`). * @see {@link ICellRange.startIncrementalUpdates} */ export interface IncrementalUpdater { /** * Adds an update at a specific cell address. * * @param address The cell address to update. See {@link ICell.Address}. * @param update The update to apply. See {@link ICell.Update}. * @throws `Error` If the coordinates are out of order compared to previously added coordinates. * @returns The current `IncrementalUpdater` instance for chaining. */ push(address: ICell.Address, update: ICell.Update): this; /** * Adds an update at a specific major (row) and minor (column) index. * * This method is slightly faster than {@link push} as it bypasses address parsing. * * @param row The row index of the cell to update. * @param col The column index of the cell to update. * @param update The update to apply. See {@link ICell.Update}. * @throws `Error` If the coordinates are out of order compared to previously added coordinates. * @returns The current `IncrementalUpdater` instance for chaining. */ pushAt(row: number, col: number, update: ICell.Update): this; /** * Adds multiple updates for contiguous cells along the minor axis (columns), starting at the specified indices. * * @param row The row index of the starting cell. * @param col The column index of the starting cell. * @param updates An array of updates to apply to contiguous cells. * @throws `Error` If the coordinates are out of order compared to previously added coordinates. * @returns The current `IncrementalUpdater` instance for chaining. */ pushMultipleAt(row: number, col: number, updates: ICell.Update[]): this; /** * Finalizes and applies all queued updates to the range. * * This method commits the changes added via {@link push}, {@link pushAt}, or {@link pushMultipleAt}. * * @param options Optional settings for the update operation. * @returns The source object, typically the range (`ICellRange`). */ apply(options?: ICellRange.UpdateCellsOptions): S; } export interface StartUpdateOptions { /** * The orientation to write. */ orientation?: IRange.Orientation; /** * Allowing unordered writes is slower but relaxes the rule that the updates must be written in order. * * @defaultValue false */ allowUnorderedWrites?: boolean | ICellRange.UpdateCellsOptions; } /** * Options for {@link ICellRange.merge}. */ export interface MergeOptions extends SetValuesOptions { /** * The orientations of the merge. * * @defaultValue IRange.Orientations.Both */ orientations?: IRange.Orientations; /** * If `true` then merge will merge even if there is more than one value. * * @defaultValue false */ discardMultipleValues?: boolean; } /** * Options use for filtering elements during a find. */ export interface FindCriteria { /** * If `true` then the text search is case sensitive. * * @defaultValue false */ matchCase?: boolean; /** * If `true` the text must match the entire cell to be true. * * @defaultValue false */ matchEntireCell?: boolean; /** * Determines whether the find operation should treat the search text as a regular expression (RegEx). * * @defaultValue false * * @remarks * When `true`, the search text will be interpreted as a regular expression (RegEx), allowing for * advanced pattern matching. * * If `false`, the find operation will not use RegEx but will support three wildcard characters * for flexible searching: * * - `?` (question mark): Matches any single character. * - `*` (asterisk): Matches any number of characters, including zero. * - `~` (tilde followed by `?`, `*`, or `~`): Escapes the wildcard characters (`?` or `*`) to allow * searching for these literal characters in the text. * * Example usage: * ```ts * // Search for text matching a RegEx pattern * const Iterator results = range.find("\\d+", { useRegex: true}); // Finds numeric values * * // Search for text using wildcards * const Iterator results = range.find("abc*", { useRegex: false }); // Finds text starting with "abc" * ``` */ useRegex?: boolean; /** * An enum of the types of values to search within each field. * * @defaultValue `[FindField.Formulas]` */ fields?: ICell.Content[]; } /** * Options for {@link ICellRange.find}. */ export interface FindOptions extends FindCriteria { /** * The text to search for. */ text: string; /** * Provides custom logic for matching values during the find operation. * * @param value The current cell value being checked against the `criteria`. * @param matchDefault A default implementation of the find operation's matching logic. * You can call this in your custom logic to fall back to the default behavior if needed. * @param criteria The criteria that the find operation is trying to match. * This is typically defined by the user and passed to the find method. * @param context Contextual information about the cell, such as its address or value-related utilities. * See {@link ICell.IteratorContext} for more details. * @returns A boolean indicating if the `value` satisfies the `criteria`. * * @remarks * If `matchCustom` is provided, this function will override the default matching logic for the find operation. * Use it to implement custom search rules, while the `matchDefault` can be used as a fallback for standard criteria. * * Example usage: * ```ts * const options = { * matchCustom: (value, matchDefault, criteria, context) => { * // Custom match logic * if (typeof value === 'string' && value.includes('important')) { * return true; * } * // Fallback to default match * return matchDefault(); * } * }; * ``` */ matchCustom?: (value: Scalar, matchDefault: () => boolean, criteria: FindCriteria, context: ICell.IteratorContext) => boolean; /** * Specifies the direction of the search. * * @defaultValue IRange.Orientation.Row */ orientation?: IRange.Orientation; /** * If `true`, the search will proceed in reverse order. * * * @defaultValue false */ reverse?: boolean; /** * The starting point for the search. If not provided, the search will start * from the top left corner of the range, or from the bottom right if `reverse` is true. * * @defaultValue top left corner or bottom right if reverse */ from?: ICell.Address; /** * If `true`, the search will not wrap around to the beginning of the range after reaching * the end. By default, the search will wrap. * * @defaultValue false */ disableWrap?: boolean; } /** * Represents an immutable reference to an `ICellRange`, capturing its content and metadata. * It may include complex objects such as tables, movables, images, listeners, or other items. * * `ISnapshot` can be provided to `ICellRange.copyFrom``. */ export interface ISnapshot { /** * Copies the snapshot to the specified range. * * @param destination The destination `ICellRange` where the snapshot will be copied. * @param options {@link ICellRange.CopyOptions} * * @returns A promise that resolves when the copy is complete, or `void` if no asynchronous operation is required. */ copyTo(destination: ICellRange, options?: ICellRange.CopyOptions): Promise | IRange.Coords | null; /** * Return the options used when creating. * @remarks * This is done so that we can create a copy. */ getMarkOptions(): ICellRange.CopyOptions; /** * Retrieves the coordinates that bound the current snapshot. * * @returns The `IRange.Coords` defining the bounds of the snapshot. */ getCoords?(): Readonly; /** * Converts the snapshot to a plain text representation. * * @returns A string or promise resolving to the text representation of the snapshot. */ toText?(): Promise | string; /** * Converts the snapshot to an HTML representation. * * @returns A string or promise resolving to the HTML representation of the snapshot. */ toHtml?(): Promise | string; /** * Converts the snapshot to an image blob. * * @returns A `Blob` or promise resolving to the image representation of the snapshot. */ toImage?(): Promise | Blob; /** * Converts the snapshot to a JSON object. * * @returns A JSON object or promise resolving to the JSON representation of the snapshot. */ toJSON?(): Promise | J; /** * The source that created the snapshot. * This is used by copy to quickly do comparisons. */ getSource(): T; /** * A user friendly name of a the snapshot item. */ getName?(): string; /** * For runtime type checking. */ readonly isISnapshot: true; } /** * Callback used for visiting a collection of cells. If break is returned the visiting will stop with the * break value returned. * * The context allows for the retrieval of additional information associated with the Cell include the * {@link ICell} object. */ export interface ForEachCallback { (value: Scalar, context: ICell.IteratorContext): { break: T; } | void; } /** * Alias type for count results by type. */ export type Counts = Partial>; export interface ScrollIntoViewOptions extends globalThis.ScrollIntoViewOptions { /** * If provided then will only scroll in the provided orientation. * * @remarks * This is useful for only scrolling vertically or horizontally for insert/deleteCells */ orientation?: IRange.Orientation; } /** * Extends SelectionOptions to include the option to adjust the anchor cell. */ export interface SelectOptions extends ITypes.SelectOptions { /** * If `true` then the anchor cell will be adjusted to the top-left cell of the range. * * @defaultValue false * * @remarks * If the current anchor is not within the current range this will be forced to `true`. */ anchor?: boolean | Partial; /** * If `true` or if a valid `ScrollIntoViewOptions` object is provided, * the selected element will be scrolled into view. * * @remarks * - If a `ScrollIntoViewOptions` object is provided, it will control the exact scrolling behavior. * - If `false` (or omitted), the selected element will not be scrolled into view. * * @defaultValue false */ scrollIntoView?: boolean | ICellRange.ScrollIntoViewOptions; } /** * Options for customizing how values are retrieved from a range and returned as a 2D array. */ export interface IteratorOptions { /** * The containing range coords for the scan. * * @remarks * If not specified will scan all of the data. */ address?: T; /** * If true will visit empty cells. * This is a potentially huge performance improvement if set to false. * * @defaultValue false * * @remarks * If includeEmpty is true this will always return rectangular results. * If bounds are provided it will provide empty spaces before and after. * If passing a large bound care must be taken. */ includeEmpty?: boolean; /** * When scanning skip cells that are hidden via headers. * * @defaultValue false * * @remarks * Optionally a header orientation for skipping case be passed in. * An example of this is for sorting where the sort direction (row) skips hidden rows but the column direction does not. */ ignoreHidden?: boolean | IRange.Orientation; /** * If set to true the only the raw values will be visited. * * @defaultValue false * * @remarks * This allows for much faster reading when only the value is needed. */ ignoreCellDetails?: boolean; /** * Includes any merge overflow in first element visited. * * @defaultValue false * * @remarks * If `true` any merges that fall outside of the range will be include in the top/left most cell that the * merge intersects. Useful for rendering merged cells when the top/left is outside the viewport. */ includeMergeOverflow?: boolean; /** * The direction of the scan. * @defaultValue `IRange.Orientation.Row` */ orientation?: IRange.Orientation; /** * Iterate in reverse order. * * @defaultValue false */ reverse?: boolean; } export interface Event { /** * The source of the event. This will be a readonly range. * * @remarks * This may change shape due to insert/delete/move of cells or sheets. */ getSource(): T; /** * This is the range of data that has been changed. * * @remarks * This is different than the source range as that is the entire range area that was listened to. */ getFrom(): ICellRanges; /** * Used for moves. Represents the new location of the data that has changed. */ getTo?(): ICellRange; /** * Indicates the type of change that triggered the event. * * @remarks * * `'data'`: Data within the range has changed. * The range's address and dimensions remain the same. * * `'address'`: The range's *address* or *dimensions* have changed. This * occurs due to row/column insertions, deletions, or move operations. * * `'restore'`: The range has been restored to a different revision * (undo/redo). The 'restore' trigger is not available for transactional listeners. */ readonly trigger2?: 'data' | 'address' | 'restore'; readonly trigger: string; /** * Indicates if the event is being fired from an undo event. */ readonly isUndo?: boolean; /** * Indicates if the event is part of a transaction. * * @see * {@link ListenerOptions.transactional} */ readonly isTransactional?: boolean; /** * Indicates if the event is being fired due to a cell value change. * * @see * {@link ListenerOptions.ignoreDataChanges} */ readonly isDataChange?: boolean; /** * To string the event. */ toString(): string; /** * The timestamp of the event. */ readonly timeStamp: number; } /** * Represents a listen for a range. The listener will be called when the range's * data, address, or restore state changes, subject to the provided options. * * @remarks * If the range is deleted (rows/columns removed), the trigger will be `'address'` * `trigger` of `'address'` and `getRange().getError()` * returning `"#REF!"`. * * If the ranges is restored to a revision *before* the listener was * added, the listener will receive event with a `trigger` of `'restore'` * and `getRange().getError()` returning `"#N/A"`. */ export interface Listener { (event: Event): void; } /** * Options to control which events trigger a listener. By default, all * event types will trigger the listener. Setting any of these options to * `true` will *prevent* the listener from being called for that event type. */ export interface ListenerOptions { /** * The actual range can also change due to insert/removes or delete of a sheet. * Setting absoluteCoords to true will ignore shifts in the range. * * @defaultValue false */ ignoreShifts?: boolean; /** * If `true`, the listener will be treated as *transactional*. This has * a few implications: * * 1. **Synchronous Execution:** The listener will be called *synchronously* * as part of the same transaction that triggered the event. Any * side-effects of the listener will be included in the transaction's * commit history. * 2. **No 'restore' Events:** Transactional listeners will *never* receive * 'restore' events. They are only concerned with changes within the * current transaction. * * If `false` (the default), the listener will be called *asynchronously* * after the transaction is complete. The listener's side-effects will * *not* be part of the transaction's commit history. * * @defaultValue false */ transactional?: boolean; /** * If `true`, the listener will *not* be called when the range's * address changes (due to row/column insert/delete, or moves) * * @defaultValue false */ ignoreAddressChanges?: boolean; /** * If `true`, the listener will *not* be called when the data * within the range changes. * * @defaultValue false */ ignoreDataChanges?: boolean; /** * If `true` then the listener will be weakly and will be auto removed it the listener is gc'ed. * * @defaultValue false */ weakly?: boolean; /** * If `true` then will auto deregister once fired. */ once?: boolean; } /** * Entry for ICellRange when iterator or visiting. */ export interface Entry { /** {@inheritDoc Scalar} */ value: T; /** {@inheritDoc ICell.IteratorContext} */ context: ICell.IteratorContext; } } declare interface ICellRangeListenerEntry { id: number; offset: number; options: ICellRange.ListenerOptions; } /** * An `ICellRanges` is a collection of {@link ICellRange}s. * * Useful when working with a discontinuous set of ranges. */ export declare interface ICellRanges { /** * {@inheritDoc ICellRange.getMerges} */ getMerges(): IRange.Coords[]; /** * {@inheritDoc ICellRange.getSheet} */ getSheet(): ISheet; /** * Returns the style for the range. * * @remarks * When querying the style the values will always be for the top left. However the * set values work for the entire range. */ getStyle(): IStyle; /** * {@inheritDoc ICellRange.find} */ find(options: string | ICellRange.FindOptions): Iterator; /** * Iterates over the values, yielding each values in the collection. * * @remarks * This does not iterate over the ranges but rather the individual cells within the ranges. * @see {@link ICellRanges.entries()} */ [Symbol.iterator](): IterableIterator; /** * Returns an iterator that allows you to iterate over the individual cells within the ranges, * yielding pairs of `IteratorContext` and a `Value`. * * @param options Configuration options for the iterator, such as filtering or sorting. * @returns An iterator that yields `[ICell.IteratorContext, Value]` tuples for each value within the range. * * @remarks * If the ranges overlap this will return the same value multiple times. If each cell * should only be visited once, use {@link ICellRanges.getFlattened} to remove overlaps. */ entries(options?: ICellRange.IteratorOptions): IterableIterator; /** * {@inheritDoc ICellRange.autoFit} */ autoFit(options?: ICellRange.AutoFitOptions): this; /** * {@inheritDoc ICellRange.calculate} */ calculate(fullRecalc?: boolean): this; /** * {@inheritDoc ICellRange.clear} */ clear(applyTo?: ICell.Content, options?: ITransaction.OperationOptions): this; /** * {@inheritDoc ICellRange.merge} */ merge(options?: IRange.Orientations | ICellRange.MergeOptions): this; /** * {@inheritDoc ICellRange.unmerge} */ unmerge(options?: ITransaction.OperationOptions): this; /** * {@inheritDoc ICellRange.insert} */ insert(options?: IRange.Orientation | ICellRange.InsertOptions): this; /** * {@inheritDoc ICellRange.delete} */ delete(options?: IRange.Orientation | ICellRange.DeleteOptions): this; /** * {@inheritDoc ICellRange.insertFrom} */ insertFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.InsertFromOptions): Promise; /** * Returns a `ICellRange.ISnapshot` for all of the ranges. * * @remarks * * This will fail if the ranges are not 'aligned'. * @see * {@link ICellRange.getSnapshot} */ getSnapshot(options?: ICellRange.CopyOptions): ICellRange.ISnapshot; /** * {@inheritDoc ICellRange.copyFrom} */ copyFrom(source: ICellRange.Address | ICellRange.ISnapshot, options?: ICellRange.CopyOptions): Promise; /** * {@inheritDoc ICellRange.getEntireRows} */ getEntireRows(shiftColumns?: boolean, options?: ICellRange.GetRangeOptions): this; /** * {@inheritDoc ICellRange.getEntireColumns} */ getEntireColumns(shiftRows?: boolean, options?: ICellRange.GetRangeOptions): this; /** * {@inheritDoc ICellRange.getRowHeaders} */ getRowHeaders(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges; /** * {@inheritDoc ICellRange.getColumnHeaders} */ getColumnHeaders(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges; /** * {@inheritDoc ICellRange.getDefaultShiftOrientation} */ getDefaultShiftOrientation(): IRange.Orientation; /** * Returns a set of ranges with overlaps removed and attempts to merge adjacent ranges into larger ranges. * * @remarks * By default, ranges will also be merged into larger ranges where possible, but this behavior can be customized using the `mergeOrientation` parameter. * This method will not modify the original ranges. * @see * {@link isOverlapping} */ getFlattened(options?: ICellRange.GetFlattenOptions): this; /** * {@inheritDoc ICellRange.getVisible} */ getVisible(options?: ICellRange.GetVisibleOptions): this | null; /** * {@inheritDoc ICellRange.getA1} */ getA1(): string; /** * {@inheritDoc ICellRange.getCounts} */ getCounts(types?: Partial>): ICellRange.Counts | null; /** * {@inheritDoc ICellRange.isContentful} */ isContentful(types?: ICell.Content | ICell.Content[]): boolean; /** * Returns the count for all rows in the ranges. This will ensure rows that are included in multiples ranges are * not double counted. */ getRowCount(): number; /** * Returns the count for all columns in the ranges. This will ensure columns that are included in multiples ranges are * not double counted. */ getColumnCount(): number; /** * {@inheritDoc ICellRange.isReadOnly} */ isReadOnly(): boolean; /** * Returns a flag indicating if any of the ranges are overlapping. * * @remarks * To get a range with no overlaps {@link ICellRanges.getFlattened} can be used. */ isOverlapping(): boolean; /** * Returns `true` if all of the the ranges have selected all of the rows. * * @remarks * This is different from `isEntireRowsAny` in that it will return `true` if 'ALL' of the * ranges have isEntireRows `true`. */ isEntireRows(): boolean; /** * Returns `true` if any of the ranges have selected all of the rows. * * @remarks * This is different from `isEntireRows` in that it it will return true if 'ANY' of the * ranges have isEntireRows `true`. */ isEntireRowsAny(): boolean; /** * Returns `true` if all of the the ranges have selected all of the columns. * * @remarks * This is different from `isEntireColumnsAny` in that it will return `true` if 'ALL' of the * ranges have isEntireColumns `true`. */ isEntireColumns(): boolean; /** * Returns `true` if any of the ranges have selected all of the columns. * * @remarks * This is different from `isEntireColumns` in that it will return `true` if 'ANY' of the * ranges have isEntireColumns `true`. */ isEntireColumnsAny(): boolean; /** * Returns `true` if any of the ranges are invalid. */ isInvalidAny(): boolean; /** * Returns a ranges with coordinates adjusted to be fixed (absolute) or flexible (relative). * * @see * {@link ICellRange.getFixed} */ getFixed(options: ICellRange.GetFixedOptions | boolean): this; /** * Returns the total number of contiguous ranges in this collection. */ getCount(): number; /** * Returns the range at a specific index. * * @param index */ at(index: number): ICellRange; /** * {@inheritDoc ICellRange.doBatch} */ doBatch(callback: (commit: ITransaction.ICommit) => R | Promise, options?: string | ITransaction.OperationOptions): R | Promise; /** * The RangeCoords. */ getCoords(): readonly Readonly[]; /** * Returns true if the range is invalid. * This can occur if a range is removed or created with invalid coordinates. */ isInvalid(): boolean; /** * Returns the address as a string. */ toString(): string; /** * {@inheritDoc ICellRange.select} */ select(options?: ICellRange.SelectOptions): Promise; /** * {@inheritDoc ICellRange.addListener} */ addListener(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove; /** * Returns an iterator that allows you to iterate over the individual values within the range. * * @param options Configuration options for the iterator, such as filtering or sorting. * @returns An iterator that yields `Scalar` value, each representing a single cell within the range. */ [Symbol.iterator](options?: ICellRange.IteratorOptions): Iterator; /** * For runtime type checking. */ readonly isICellRanges: true; } /** * {@inheritDoc ICellRanges} * @see * ### **Interface** * * {@link ICellRanges} */ export declare namespace ICellRanges { /** * The coord type for a ranges. */ export type Coords = IRange.Coords[]; /** * Address for multiple {@link ICellRange}s. */ export type Address = ICellRanges | string | ICellRange.Address | readonly ICellRange.Address[]; /** * Options when visiting a ICellRanges. */ export interface IteratorOptions extends ICellRange.IteratorOptions { } /** * Shorthand for persisting. */ export type RefJSON = IRange.Coords[] | IRange.Coords | string; } declare interface ICellRangesListenerEntry { id: number; /** * We have to track the range because we can't use the node coords * as shift/split can change the coords. and our range has fixed dimensions. */ ranges: Readonly[]; handler: ICellRange.Listener; handlerW: WeakRef; removeListener: IListener.Remove; options: ICellRange.ListenerOptions; } /** * Interface for working with Charts. * * **PLACEHOLDER** - This is under development and not made public yet. */ export declare interface IChart extends IModel { toJSON(toResourceId?: (resource: IResource) => number): IChart.JSON; getDescription(): string; } /** * {@inheritDoc IChart} * @see * ### **Interface** * * {@link IChart} */ export declare namespace IChart { export interface JSON { } export interface Events extends IModel.Events { } export interface IListeners extends IListener.Callbacks { } } /** * Interface used for all ICollections. */ export declare interface ICollection { /** * Returns the items in the collection. */ getItems(options?: ICollection.GetItemsOptions): T[]; /** * Returns the total items available. * * @remarks * Useful as a quick escape for getItems. */ getCount(): number; } /** * {@inheritDoc ICollection} * @see * ### **Interface** * * {@link ICollection} */ export declare namespace ICollection { /** * Options for getting items from the collection. * * @remarks * This placeholder is extended by implementations of ICollection */ export interface GetItemsOptions { } /** * Collection that can be persisted. */ export interface IPersistable { /** * Used for saving items. Returns a handler that will allow for writing JSON records * only save the items that were accessed within the persist scope. */ beginPersist(): ICollection.IPersistScope; } /** * A transient scope for items to ids that can be used for references. * * @see * {@link IPersistable.beginPersist} */ export interface IPersistScope { /** * For a shared string this will return a number that can be used to reference the item in the persisted json. * @param item The to return an identifier for. */ add(item: JSONSerializableAsync | J): number | null; /** * For a given persist id this will return the item. * * @param id */ at(id: number): JSONSerializableAsync | J | null; /** * Called when done persisting. */ endPersist(): void; /** * Loads the json. * * @param json */ fromJSON(json: J[]): void; /** * Return a array of resources that have been added via `add`. * * @remarks * This can be called multiple times.. */ toJSONAsync(): Promise; } /** * Collection Events. */ export interface Events { /** * Called when collections have changes. */ onCollectionChange?(source: ICollection): void; /** * Called when the collection has been updated due to a undo/redo and a rerender is required. */ onInvalidated?(source: ICollection): void; } export interface IListeners extends IListener.Callbacks, ICollection.Events> { } } /** * Represents a color with optional adjustments applied. * * An `IColor` consists of: * - `baseColor`: The underlying color, which can be a scheme color (e.g., Accent1), a built-in color (e.g., 'red', 'blue'), * or defined using various color models (RGB, Hex, HSL). * - `adjustments` (optional): An ordered list of color adjustments that modify the `baseColor`. * These adjustments can include effects like grayscale, inversion, or modifications to specific color components (red, alpha, etc.). * @see * {@link AdjustmentType} */ export declare interface IColor { /** * The base value for the color before adjustments. */ getVal(): string; /** * Return the color adjustments. */ getAdjustments(): readonly IColor.Adjustment[]; /** * Return as RGBA with adjustments applied. * @param darkMode */ toRGBA(darkMode?: boolean): IColor.ISpace.RGBA; /** * Return as HSLA with adjustments applied. * @param darkMode */ toHSLA(darkMode?: boolean): IColor.ISpace.HSLA; /** * Return a HEX with adjustments applied. * @param darkMode */ toHex(darkMode?: boolean): IColor.ISpace.HEX; /** * Return a string usable with CSS color properties. * * @param darkMode If `true` dark colors will be used. * @param alpha If `true` alpha will be applied. */ toCSS(darkMode?: boolean, alpha?: boolean): string; /** * Returns a new color that is derived from this color with the adjustments applied. * @param adjustments An array of Adjustments */ adjust(adjustments: readonly IColor.Adjustment[]): IColor; /** * Returns the color as either 'black or white' depending on the luminance. * @param threshold The threshold to determine if the color is dark or light. @defaultValue '186' */ toBlackOrWhite(darkMode?: boolean, threshold?: number): IColor; /** * Return the color as a string. * @remarks */ toString(): string; /** * Return the type of color value used (e.g., scheme, named, index, hsl, rgb, hex). */ getType(): IColor.Type; /** * Returns true if the other color will resolve to the same rgb values as this color. * @param other The other color to compare. */ isEqual(other: any): boolean; /** * For runtime type checking. */ readonly isIColor: true; } /** * {@inheritDoc IColor} * @see * ### **Interface** * * {@link IColor} * * ### **Implementation** * * {@link IColor} */ export declare namespace IColor { /** * Represents a color space. */ export namespace ISpace { /** * A color in the Red, Green, Blue color space. */ export type RGBA = ColorSpace.RGBA; /** * A color in the Hue, Saturation, Luminosity color space. */ export type HSLA = ColorSpace.HSLA; /** * A color (Red, Green, Blue) encoded in hexadecimal. */ export type HEX = ColorSpace.HEX; } /** * Represents various adjustment types for color properties, allowing fine-tuned control over * attributes such as transparency, hue, saturation, luminance, and RGB components. * * The adjusts are based on the DrawML OOXML specification, with an additional adjustment type (`ETint`) * based on the Excel tint shading algorithm. * * * Adjustments can be chained to achieve complex color transformations. */ const AdjustmentType: { /** * Adjusts the transparency level of a color. */ readonly Alpha: "alpha"; /** * Adjusts the transparency offset of a color. */ readonly AlphaOff: "alphaOff"; /** * Modifies the transparency of a color by a multiplier. */ readonly AlphaMod: "alphaMod"; /** * Adjusts the hue of a color. */ readonly Hue: "hue"; /** * Adjusts the saturation of a color. */ readonly Sat: "sat"; /** * Adjusts the luminance (brightness) of a color. */ readonly Lum: "lum"; /** * Applies an offset to the hue of a color. */ readonly HueOff: "hueOff"; /** * Applies an offset to the saturation of a color. */ readonly SatOff: "satOff"; /** * Applies an offset to the luminance of a color. */ readonly LumOff: "lumOff"; /** * Modifies the hue of a color by a multiplier. */ readonly HueMod: "hueMod"; /** * Modifies the saturation of a color by a multiplier. */ readonly SatMod: "satMod"; /** * Modifies the luminance of a color by a multiplier. */ readonly LumMod: "lumMod"; /** * Adjusts the red component of a color. */ readonly Red: "red"; /** * Adjusts the green component of a color. */ readonly Green: "green"; /** * Adjusts the blue component of a color. */ readonly Blue: "blue"; /** * Applies an offset to the red component of a color. */ readonly RedOff: "redOff"; /** * Applies an offset to the green component of a color. */ readonly GreenOff: "greenOff"; /** * Applies an offset to the blue component of a color. */ readonly BlueOff: "blueOff"; /** * Modifies the red component of a color by a multiplier. */ readonly RedMod: "redMod"; /** * Modifies the green component of a color by a multiplier. */ readonly GreenMod: "greenMod"; /** * Modifies the blue component of a color by a multiplier. */ readonly BlueMod: "blueMod"; /** * Shades a color, making it darker by reducing its luminance. */ readonly Shade: "shade"; /** * Tints a color, making it lighter by increasing its luminance. */ readonly Tint: "tint"; /** * Tints a color based on Excel's specific tint shading algorithm. */ readonly ETint: "eTint"; /** * Converts a color to grayscale. */ readonly Gray: "gray"; /** * Creates a complementary color. */ readonly Comp: "comp"; /** * Inverts a color. */ readonly Inv: "inv"; /** * Applies gamma correction to a color. */ readonly Gamma: "gamma"; /** * Inverts the gamma correction of a color. */ readonly InvGamma: "invGamma"; }; export type AdjustmentType = typeof AdjustmentType[keyof typeof AdjustmentType]; /** * Represents a color adjustment. * * @remarks * All percentages are expresses as 0-100 except alpha which is 0-1. */ export type Adjustment = { [key in IColor.AdjustmentType]?: boolean | number; }; /** * Represents a value and adjustment. */ export interface Definition { val: string; adjs?: readonly IColor.Adjustment[]; } /** * Associate a color definition with a human-readable label. * @remarks * Useful for displaying color options in a UI. */ export interface DefinitionWithLabel { description: string; definition: IColor.Definition; } export type Serializable = string | IColor | (string | IColor); /** * Lookup a color by the Schema key. This should consult a DocTheme if available. */ export type SchemeLookup = (key: IColor.Scheme) => ColorSpace.RGBA; /** * Lookup a color by the Indexed value. * @see * {@link https://github.com/closedxml/closedxml/wiki/Excel-Indexed-Colors | Excel Indexed Colors} */ export type IndexedLookup = (index: number) => ColorSpace.RGBA; /** * Named (builtin) colors defined in DrawingML aka known/system colors * * This enum provides a comprehensive list of named colors, including system-defined colors, * standard HTML colors, and additional named colors. Each color is represented as a string * corresponding to its name. * * @see * * {@link https://msdn.microsoft.com/library/system.drawing.knowncolor.aspx | KnownColor Enumeration} * * {@link https://msdn.microsoft.com/library/system.windows.media.colors.aspx | Colors Class} */ const Named: { /** * The system-defined color of the active window's border. */ readonly ActiveBorder: "activeBorder"; /** * The system-defined color of the active window's caption. */ readonly ActiveCaption: "activeCaption"; /** * The system-defined color of the text in the active window's caption. */ readonly CaptionText: "captionText"; /** * The system-defined color of the application workspace. */ readonly AppWorkspace: "appWorkspace"; /** * The system-defined color of the face of a button. */ readonly BtnFace: "btnFace"; /** * The system-defined color of the shadow of a button. */ readonly BtnShadow: "btnShadow"; /** * The system-defined color of a 3D dark shadow. */ readonly DkShadow3d: "3dDkShadow"; /** * The system-defined color of the highlight of a button. */ readonly BtnHighlight: "btnHighlight"; /** * The system-defined color of a 3D light. */ readonly Light3d: "3dLight"; /** * The system-defined color of the text on a button. */ readonly BtnText: "btnText"; /** * The system-defined color of the background. */ readonly Background: "background"; /** * The system-defined color of gray text. */ readonly GrayText: "grayText"; /** * The system-defined color of the highlight. */ readonly Highlight: "highlight"; /** * The system-defined color of the text in the highlight. */ readonly HighlightText: "highlightText"; /** * The system-defined color of a hot light. */ readonly HotLight: "hotLight"; /** * The system-defined color of the inactive window's border. */ readonly InactiveBorder: "inactiveBorder"; /** * The system-defined color of the inactive window's caption. */ readonly InactiveCaption: "inactiveCaption"; /** * The system-defined color of the text in the inactive window's caption. */ readonly InactiveCaptionText: "inactiveCaptionText"; /** * The system-defined color of the background of an information tooltip. */ readonly InfoBk: "infoBk"; /** * The system-defined color of the text in an information tooltip. */ readonly InfoText: "infoText"; /** * The system-defined color of a menu. */ readonly Menu: "menu"; /** * The system-defined color of the text in a menu. */ readonly MenuText: "menuText"; /** * The system-defined color of a scroll bar. */ readonly ScrollBar: "scrollBar"; /** * The system-defined color of a window. */ readonly Window: "window"; /** * The system-defined color of a window frame. */ readonly WindowFrame: "windowFrame"; /** * The system-defined color of the text in a window. */ readonly WindowText: "windowText"; /** * The system-defined color of transparency. */ readonly Transparent: "transparent"; /** * The color AliceBlue. */ readonly AliceBlue: "aliceBlue"; /** * The color AntiqueWhite. */ readonly AntiqueWhite: "antiqueWhite"; /** * The color Aqua. */ readonly Aqua: "aqua"; /** * The color Aquamarine. */ readonly Aquamarine: "aquamarine"; /** * The color Azure. */ readonly Azure: "azure"; /** * The color Beige. */ readonly Beige: "beige"; /** * The color Bisque. */ readonly Bisque: "bisque"; /** * The color Black. */ readonly Black: "black"; /** * The color BlanchedAlmond. */ readonly BlanchedAlmond: "blanchedAlmond"; /** * The color Blue. */ readonly Blue: "blue"; /** * The color BlueViolet. */ readonly BlueViolet: "blueViolet"; /** * The color Brown. */ readonly Brown: "brown"; /** * The color BurlyWood. */ readonly BurlyWood: "burlyWood"; /** * The color CadetBlue. */ readonly CadetBlue: "cadetBlue"; /** * The color Chartreuse. */ readonly Chartreuse: "chartreuse"; /** * The color Chocolate. */ readonly Chocolate: "chocolate"; /** * The color Coral. */ readonly Coral: "coral"; /** * The color CornflowerBlue. */ readonly CornflowerBlue: "cornflowerBlue"; /** * The color Cornsilk. */ readonly Cornsilk: "cornsilk"; /** * The color Crimson. */ readonly Crimson: "crimson"; /** * The color Cyan. */ readonly Cyan: "cyan"; /** * The color DarkBlue. */ readonly DkBlue: "dkBlue"; /** * The color DarkCyan. */ readonly DkCyan: "dkCyan"; /** * The color DarkGoldenrod. */ readonly DkGoldenrod: "dkGoldenrod"; /** * The color DarkGray. */ readonly DkGray: "dkGray"; /** * The color DarkGreen. */ readonly DkGreen: "dkGreen"; /** * The color DarkKhaki. */ readonly DkKhaki: "dkKhaki"; /** * The color DarkMagenta. */ readonly DkMagenta: "dkMagenta"; /** * The color DarkOliveGreen. */ readonly DkOliveGreen: "dkOliveGreen"; /** * The color DarkOrange. */ readonly DkOrange: "dkOrange"; /** * The color DarkOrchid. */ readonly DkOrchid: "dkOrchid"; /** * The color DarkRed. */ readonly DkRed: "dkRed"; /** * The color DarkSalmon. */ readonly DkSalmon: "dkSalmon"; /** * The color DarkSeaGreen. */ readonly DkSeaGreen: "dkSeaGreen"; /** * The color DarkSlateBlue. */ readonly DkSlateBlue: "dkSlateBlue"; /** * The color DarkSlateGray. */ readonly DkSlateGray: "dkSlateGray"; /** * The color DarkTurquoise. */ readonly DkTurquoise: "dkTurquoise"; /** * The color DarkViolet. */ readonly DkViolet: "dkViolet"; /** * The color DeepPink. */ readonly DeepPink: "deepPink"; /** * The color DeepSkyBlue. */ readonly DeepSkyBlue: "deepSkyBlue"; /** * The color DimGray. */ readonly DimGray: "dimGray"; /** * The color DodgerBlue. */ readonly DodgerBlue: "dodgerBlue"; /** * The color Firebrick. */ readonly Firebrick: "firebrick"; /** * The color FloralWhite. */ readonly FloralWhite: "floralWhite"; /** * The color ForestGreen. */ readonly ForestGreen: "forestGreen"; /** * The color Fuchsia. */ readonly Fuchsia: "fuchsia"; /** * The color Gainsboro. */ readonly Gainsboro: "gainsboro"; /** * The color GhostWhite. */ readonly GhostWhite: "ghostWhite"; /** * The color Gold. */ readonly Gold: "gold"; /** * The color Goldenrod. */ readonly Goldenrod: "goldenrod"; /** * The color Gray. */ readonly Gray: "gray"; /** * The color Green. */ readonly Green: "green"; /** * The color GreenYellow. */ readonly GreenYellow: "greenYellow"; /** * The color Honeydew. */ readonly Honeydew: "honeydew"; /** * The color HotPink. */ readonly HotPink: "hotPink"; /** * The color IndianRed. */ readonly IndianRed: "indianRed"; /** * The color Indigo. */ readonly Indigo: "indigo"; /** * The color Ivory. */ readonly Ivory: "ivory"; /** * The color Khaki. */ readonly Khaki: "khaki"; /** * The color Lavender. */ readonly Lavender: "lavender"; /** * The color LavenderBlush. */ readonly LavenderBlush: "lavenderBlush"; /** * The color LawnGreen. */ readonly LawnGreen: "lawnGreen"; /** * The color LemonChiffon. */ readonly LemonChiffon: "lemonChiffon"; /** * The color LightBlue. */ readonly LtBlue: "ltBlue"; /** * The color LightCoral. */ readonly LtCoral: "ltCoral"; /** * The color LightCyan. */ readonly LtCyan: "ltCyan"; /** * The color LightGoldenrodYellow. */ readonly LtGoldenrodYellow: "ltGoldenrodYellow"; /** * The color LightGray. */ readonly LtGray: "ltGray"; /** * The color LightGreen. */ readonly LtGreen: "ltGreen"; /** * The color LightPink. */ readonly LtPink: "ltPink"; /** * The color LightSalmon. */ readonly LtSalmon: "ltSalmon"; /** * The color LightSeaGreen. */ readonly LtSeaGreen: "ltSeaGreen"; /** * The color LightSkyBlue. */ readonly LtSkyBlue: "ltSkyBlue"; /** * The color LightSlateGray. */ readonly LtSlateGray: "ltSlateGray"; /** * The color LightSteelBlue. */ readonly LtSteelBlue: "ltSteelBlue"; /** * The color LightYellow. */ readonly LtYellow: "ltYellow"; /** * The color Lime. */ readonly Lime: "lime"; /** * The color LimeGreen. */ readonly LimeGreen: "limeGreen"; /** * The color Linen. */ readonly Linen: "linen"; /** * The color Magenta. */ readonly Magenta: "magenta"; /** * The color Maroon. */ readonly Maroon: "maroon"; /** * The color MediumAquamarine. */ readonly MedAquamarine: "medAquamarine"; /** * The color MediumBlue. */ readonly MedBlue: "medBlue"; /** * The color MediumOrchid. */ readonly MedOrchid: "medOrchid"; /** * The color MediumPurple. */ readonly MedPurple: "medPurple"; /** * The color MediumSeaGreen. */ readonly MedSeaGreen: "medSeaGreen"; /** * The color MediumSlateBlue. */ readonly MedSlateBlue: "medSlateBlue"; /** * The color MediumSpringGreen. */ readonly MedSpringGreen: "medSpringGreen"; /** * The color MediumTurquoise. */ readonly MedTurquoise: "medTurquoise"; /** * The color MediumVioletRed. */ readonly MedVioletRed: "medVioletRed"; /** * The color MidnightBlue. */ readonly MidnightBlue: "midnightBlue"; /** * The color MintCream. */ readonly MintCream: "mintCream"; /** * The color MistyRose. */ readonly MistyRose: "mistyRose"; /** * The color Moccasin. */ readonly Moccasin: "moccasin"; /** * The color NavajoWhite. */ readonly NavajoWhite: "navajoWhite"; /** * The color Navy. */ readonly Navy: "navy"; /** * The color OldLace. */ readonly OldLace: "oldLace"; /** * The color Olive. */ readonly Olive: "olive"; /** * The color OliveDrab. */ readonly OliveDrab: "oliveDrab"; /** * The color Orange. */ readonly Orange: "orange"; /** * The color OrangeRed. */ readonly OrangeRed: "orangeRed"; /** * The color Orchid. */ readonly Orchid: "orchid"; /** * The color PaleGoldenrod. */ readonly PaleGoldenrod: "paleGoldenrod"; /** * The color PaleGreen. */ readonly PaleGreen: "paleGreen"; /** * The color PaleTurquoise. */ readonly PaleTurquoise: "paleTurquoise"; /** * The color PaleVioletRed. */ readonly PaleVioletRed: "paleVioletRed"; /** * The color PapayaWhip. */ readonly PapayaWhip: "papayaWhip"; /** * The color PeachPuff. */ readonly PeachPuff: "peachPuff"; /** * The color Peru. */ readonly Peru: "peru"; /** * The color Pink. */ readonly Pink: "pink"; /** * The color Plum. */ readonly Plum: "plum"; /** * The color PowderBlue. */ readonly PowderBlue: "powderBlue"; /** * The color Purple. */ readonly Purple: "purple"; /** * The color Red. */ readonly Red: "red"; /** * The color RosyBrown. */ readonly RosyBrown: "rosyBrown"; /** * The color RoyalBlue. */ readonly RoyalBlue: "royalBlue"; /** * The color SaddleBrown. */ readonly SaddleBrown: "saddleBrown"; /** * The color Salmon. */ readonly Salmon: "salmon"; /** * The color SandyBrown. */ readonly SandyBrown: "sandyBrown"; /** * The color SeaGreen. */ readonly SeaGreen: "seaGreen"; /** * The color SeaShell. */ readonly SeaShell: "seaShell"; /** * The color Sienna. */ readonly Sienna: "sienna"; /** * The color Silver. */ readonly Silver: "silver"; /** * The color SkyBlue. */ readonly SkyBlue: "skyBlue"; /** * The color SlateBlue. */ readonly SlateBlue: "slateBlue"; /** * The color SlateGray. */ readonly SlateGray: "slateGray"; /** * The color Snow. */ readonly Snow: "snow"; /** * The color SpringGreen. */ readonly SpringGreen: "springGreen"; /** * The color SteelBlue. */ readonly SteelBlue: "steelBlue"; /** * The color Tan. */ readonly Tan: "tan"; /** * The color Teal. */ readonly Teal: "teal"; /** * The color Thistle. */ readonly Thistle: "thistle"; /** * The color Tomato. */ readonly Tomato: "tomato"; /** * The color Turquoise. */ readonly Turquoise: "turquoise"; /** * The color Violet. */ readonly Violet: "violet"; /** * The color Wheat. */ readonly Wheat: "wheat"; /** * The color White. */ readonly White: "white"; /** * The color WhiteSmoke. */ readonly WhiteSmoke: "whiteSmoke"; /** * The color Yellow. */ readonly Yellow: "yellow"; /** * The color YellowGreen. */ readonly YellowGreen: "yellowGreen"; /** * The system-defined color of the face of a button. */ readonly ButtonFace: "buttonFace"; /** * The system-defined color of the highlight of a button. */ readonly ButtonHighlight: "buttonHighlight"; /** * The system-defined color of the shadow of a button. */ readonly ButtonShadow: "buttonShadow"; /** * The system-defined color of the gradient active caption. */ readonly GradientActiveCaption: "gradientActiveCaption"; /** * The system-defined color of the gradient inactive caption. */ readonly GradientInactiveCaption: "gradientInactiveCaption"; /** * The system-defined color of the menu bar. */ readonly MenuBar: "menuBar"; /** * The system-defined color of the menu highlight. */ readonly MenuHighlight: "menuHighlight"; }; export type Named = typeof Named[keyof typeof Named]; /** * Represents predefined colors from a color scheme, used in document themes. */ const Scheme: { /** * Background color 1. */ readonly Bg1: "bg1"; /** * Background color 2. */ readonly Bg2: "bg2"; /** * Text color 1. */ readonly Tx1: "tx1"; /** * Text color 2. */ readonly Tx2: "tx2"; /** * Accent color 1. */ readonly Accent1: "accent1"; /** * Accent color 2. */ readonly Accent2: "accent2"; /** * Accent color 3. */ readonly Accent3: "accent3"; /** * Accent color 4. */ readonly Accent4: "accent4"; /** * Accent color 5. */ readonly Accent5: "accent5"; /** * Accent color 6. */ readonly Accent6: "accent6"; /** * Hyperlink color. */ readonly Hlink: "hlink"; /** * Followed hyperlink color. */ readonly FolHlink: "folHlink"; }; export type Scheme = typeof Scheme[keyof typeof Scheme]; /** * Indicates the Color Type used. */ const Type: { readonly Scheme: "scheme"; readonly Named: "named"; readonly Index: "index"; readonly HSL: "hsl"; readonly RGB: "rgb"; readonly LRGB: "lrgb"; readonly Hex: "hex"; }; export type Type = typeof Type[keyof typeof Type]; } /** * TODO - Implement IComment. * TODO - how to make this threaded? * TODO - rationalize this with notes? * -Each Comment will have a unique id and a parent that it is a reply to. * * ? How to add root range.addComment(content) ? (only allows for 1 root) * https://learn.microsoft.com/en-us/javascript/api/office-scripts/excelscript/excelscript.contenttype?view=office-scripts * * Excel has a resolved/done status * Excel has mentions? */ export declare interface IComment { getContent(): string; setContent(content: string): void; getUserId(): string; delete(): void; getCreationDate(): Date; } /** * {@inheritDoc IComment} * @see * ### **Interface** * * {@link IComment} */ export declare namespace IComment { export interface Properties { /** * The content of the comment. */ content?: any; asNote?: boolean; } /** * For persisting. */ export interface JSON extends IComment.Properties { /** * Required for referencing in replies. */ id: string; /** * The id for author or the comment the comment. */ personId: string; /** * The reference for the comment. */ ref?: ICellRange.RefJSON; /** * If this is a reply, the id of the parent comment. */ parentId?: string; /** * An unordered list of mention ids. * @remarks * These are not order dependent. */ mentionsIds?: string[]; /** * The date the comment was created. */ dt?: Date | string; /** * The comment has been marked as done. */ done?: boolean; } export interface MentionJSON { /** * The id for the mention. */ id: string; /** * The id for author or the comment the comment. */ personId: string; /** * The start of the mention. */ startIndex?: number; /** * The length of the mention. */ length?: number; } /** * Represents a reference to person. Either in a comment, protection clause or mention. */ export interface PersonJSON { /** * A human readable string for the name. */ displayName: string; /** * A unique identifier. */ id: string; /** * The id for authorizing against the providerId. */ userId?: string; /** * The system that provided the person. */ providerId?: string; } } /** * Represents a conditional formatting rule for a range. * * @remarks * Used for modifying the type and rules of a conditional formatting entry. * * * Conditional formatting rules can be used to highlight, format, or modify * cell appearance based on data conditions or criteria. * * * Conditional formatting help users identify patterns, trends, and exceptions * in data by applying visual styles dynamically. */ export declare interface IConditionalFormat extends IModel, IProperties.ICellRanged { /** * Returns the ranges for conditional formatting. */ getRanges(): ICellRanges; /** * Set ranges for the conditional format. * * @param address The address. */ setRanges(address: ICellRanges.Address, options?: ITransaction.OperationOptions): this; /** * Set the type of conditional format used. * * @param type The type of conditional format. */ setType(type: IConditionalFormat.Type, options?: ITransaction.OperationOptions): this; /** * Returns the type of conditional format used. */ getType(): IConditionalFormat.Type; /** * The priority of the conditional format rule as a number relative to other rules. * * @param priority A number that determines the order of the conditional format. * * @remarks * This must always be a positive number and will be unique. If this is the same as another conditional format * then that will will be adjusted to be greater than this one. */ setPriority(priority: number, options?: ITransaction.OperationOptions): this; /** * @see {@link IConditionalFormat.setPriority} */ getPriority(): number; /** * Sets whether to stop evaluating additional conditional formatting rules if this rule is true. * * @param stopIfTrue A boolean to indicate if this is a stop. * * @remarks * This will only affect formatting rules for the current range or cell. */ setStopIfTrue(stopIfTrue: boolean, options?: ITransaction.OperationOptions): this; /** * @see {@link IConditionalFormat.setStopIfTrue} */ getStopIfTrue(): boolean; /** * Returns the cell value associated with this conditional formatting. * * @remarks * This will be `null` unless {@link IConditionalFormat.getType} is `IConditionalFormat.Type.Scalar`. */ getScalar(): any | null; /** * Returns the color scale settings for this conditional formatting. * * @remarks * This will be `null` unless {@link IConditionalFormat.getType} is `IConditionalFormat.Type.ColorScale`. */ getColorScale(): IConditionalFormat.ColorScale | null; /** * Returns the contains texts settings for this conditional formatting. * * @remarks * This will be `null` unless {@link IConditionalFormat.getType} is `IConditionalFormat.Type.ContainsText`. */ getContainsText(): any | null; /** * Returns the custom rule settings for this conditional formatting. * * @remarks * This will be `null` unless {@link IConditionalFormat.getType} is `IConditionalFormat.Type.Custom`. */ getCustom(): any | null; /** * Returns the data bar settings for this conditional formatting. * * @remarks * This will be `null` unless {@link IConditionalFormat.getType} is `IConditionalFormat.Type.DataBar`. */ getDataBar(): IConditionalFormat.DataBar | null; /** * Returns the icon set settings for this conditional formatting. * * @remarks * This will be `null` unless {@link IConditionalFormat.getType} is `IConditionalFormat.Type.IconSet`. */ getIconSet(): IConditionalFormat.IconSet | null; /** * Returns the preset rule settings for this conditional formatting. * * @remarks * This will be `null` unless {@link IConditionalFormat.getType} is `IConditionalFormat.Type.PresetCriteria`. */ getPresetCriteria(): IStyle.Properties | null; /** * Returns the top/bottom rule settings for this conditional formatting. * * @remarks * This will be `null` unless {@link IConditionalFormat.getType} is `IConditionalFormat.Type.TopBottom`. */ getTopBottom(): any | null; /** * Set multiple properties at the same time. */ update(properties: Partial, options?: ITransaction.OperationOptions): this; /** * Returns a snapshot of the conditional that can be used for copying and archiving. */ getSnapshot(options?: ReferenceableClipboard.CopyOptions): IConditionalFormat.ISnapshot; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: IConditionalFormat.IListeners, options?: IListener.Options): IListener.Remove; /** * @returns The current state as a JSON object. */ toJSON(): IConditionalFormat.JSON; /** * For runtime type checking. */ readonly isIConditionalFormat: true; } /** * Capabilities for working with conditional styling ranges. * * @see * ### **Interface** * * {@link IConditionalFormat} * * **Additional Interfaces** * * {@link IConditionalFormatCollection} */ export declare namespace IConditionalFormat { /** * Represents the various types of built-in conditional formatting rules. * * @remarks * This enum is used to define different types of conditional formatting rules * that can be applied to cells in a spreadsheet. Each type corresponds to a * specific style of formatting that adjusts based on data or predefined conditions. * Conditional formatting visually highlights cells to make patterns, trends, * or exceptions in the data more noticeable. */ const Type: { /** * This conditional formatting rule highlights cells that are above or below the average for all values in the range. */ readonly AboveAverage: "aboveAverage"; /** * This conditional formatting rule highlights cells in the range that begin with the given text. * Equivalent to using the LEFT() sheet function and comparing values. */ readonly BeginsWith: "beginsWith"; /** * This conditional formatting rule compares a cell value to a formula calculated result, using an operator. */ readonly CellIs: "cellIs"; /** * This conditional formatting rule creates a gradated color scale on the cells. * * @remarks * Applies a gradient of colors based on cell values within a range. */ readonly ColorScale: "colorScale"; /** * This conditional formatting rule highlights cells that are completely blank. * Equivalent of using LEN(TRIM()). * This means that if the cell contains only characters that TRIM() would remove, then it is considered blank. * An empty cell is also considered blank. */ readonly ContainsBlanks: "containsBlanks"; /** * This conditional formatting rule highlights cells with formula errors. * Equivalent to using ISERROR() sheet function to determine if there is a formula error. * * @remarks * Formats cells that contain error values, such as #DIV/0! or #N/A. */ readonly ContainsErrors: "containsErrors"; /** * This conditional formatting rule highlights cells containing given text. * Equivalent to using the SEARCH() sheet function to determine whether the cell contains the text. */ readonly ContainsText: "containsText"; /** * Conditional formatting based on data bars. * * @remarks * Displays a horizontal bar in cells proportional to their values. */ readonly DataBar: "dataBar"; /** * This conditional formatting rule highlights duplicated values. */ readonly DuplicateValues: "duplicateValues"; /** * This conditional formatting rule highlights cells ending with given text. * Equivalent to using the RIGHT() sheet function and comparing values. */ readonly EndsWith: "endsWith"; /** * This conditional formatting rule contains a formula to evaluate. When the formula result is true, the cell is highlighted. */ readonly Expression: "expression"; /** * Conditional formatting using icon sets. * * @remarks * Displays icons based on value ranges within cells. */ readonly IconSet: "iconSet"; /** * This conditional formatting rule highlights cells that are not blank. Equivalent of using LEN(TRIM()). * This means that if the cell contains only characters that TRIM() would remove, then it is considered blank. * An empty cell is also considered blank. */ readonly NotContainsBlanks: "notContainsBlanks"; /** * This conditional formatting rule highlights cells without formula errors. * Equivalent to using ISERROR() sheet function to determine if there is a formula error. */ readonly NotContainsErrors: "notContainsErrors"; /** * This conditional formatting rule highlights cells that do not contain given text. * Equivalent to using the SEARCH() sheet function. */ readonly NotContainsText: "notContainsText"; /** * This conditional formatting rule highlights cells containing dates in the specified time period. * The underlying value of the cell is evaluated, therefore the cell does not need to be formatted as a date to be evaluated. * For example, with a cell containing the value 38913 the conditional format shall be applied if the rule requires a value of 7/14/2006. */ readonly TimePeriod: "timePeriod"; /** * This conditional formatting rule highlights cells whose values fall in the top N or bottom N bracket, as specified. */ readonly Top10: "top10"; /** * This conditional formatting rule highlights unique values in the range. */ readonly UniqueValues: "uniqueValues"; }; export type Type = typeof Type[keyof typeof Type]; /** * Used for conditional formatting rules that require an operator. */ const OperatorType: { readonly BeginsWith: "beginsWith"; readonly Between: "between"; readonly ContainsText: "containsText"; readonly EndsWith: "endsWith"; readonly Equal: "equal"; readonly GreaterThan: "greaterThan"; readonly GreaterThanOrEqual: "greaterThanOrEqual"; readonly LessThan: "lessThan"; readonly LessThanOrEqual: "lessThanOrEqual"; readonly NotBetween: "notBetween"; readonly NotContains: "notContains"; readonly NotEqual: "notEqual"; }; export type OperatorType = typeof OperatorType[keyof typeof OperatorType]; const TimePeriod: { readonly Last7Days: "last7Days"; readonly LastMonth: "lastMonth"; readonly LastWeek: "lastWeek"; readonly NextMonth: "nextMonth"; readonly NextWeek: "nextWeek"; readonly ThisMonth: "thisMonth"; readonly ThisWeek: "thisWeek"; readonly Today: "today"; readonly Tomorrow: "tomorrow"; readonly Yesterday: "yesterday"; }; export type TimePeriod = typeof TimePeriod[keyof typeof TimePeriod]; const ConditionalBoundsType: { /** * The minimum/ midpoint / maximum value for the gradient is determined by a formula. */ readonly Formula: "formula"; /** * Indicates that the maximum value in the range shall be used as the maximum value for the gradient. */ readonly Max: "max"; /** * Indicates that the minimum value in the range shall be used as the minimum value for the gradient. */ readonly Min: "min"; /** * Indicates that the minimum / midpoint / maximum value for the gradient is specified by a constant numeric value. */ readonly Num: "num"; /** * Value indicates a percentage between the minimum and maximum values in the range shall be used as the minimum / midpoint / maximum value for the gradient. */ readonly Percent: "percent"; /** * Value indicates a percentile ranking in the range shall be used as the minimum / midpoint / maximum value for the gradient. */ readonly Percentile: "percentile"; }; export type ConditionalBoundsType = typeof ConditionalBoundsType[keyof typeof ConditionalBoundsType]; export interface Condition { type: ConditionalBoundsType; value?: number; /** * For icon sets, determines whether this threshold value uses the greater than or equal to operator. */ gte?: boolean; } /** * A color scale must have either 2 or 3 conditions. */ export interface ColorScale { conditions: IConditionalFormat.Condition[]; colors: string[]; } /** * A color scale must have either 2 or 3 conditions. */ export interface DataBar { conditions: IConditionalFormat.Condition[]; colors: string[]; maxLength?: number; minLength?: number; /** * If true, the value will be shown in the cell. */ showValue?: boolean; } /** * */ export interface IconSet { conditions: IConditionalFormat.Condition[]; /** * Allows for individual icon overrides. */ icon?: { set: IStyle.IconSet; id: number; }[]; /** * The icon set to use */ iconSet?: IStyle.IconSet; reverse?: boolean; /** * If true, the value will be shown in the cell. */ showValue?: boolean; } /** * A set of values that can be set on a IConditionalFormat. * * @see * {@link IConditionalFormat} */ export interface Properties { /** * The type of conditional formatting rule. */ type: IConditionalFormat.Type; /** * Default will be the order these are added. */ priority?: number; /** * @defaultValue false */ stopIfTrue?: boolean; aboveAverage?: boolean; equalAverage?: boolean; stdDev?: number; bottom?: boolean; percent?: boolean; rank?: number; operator?: IConditionalFormat.OperatorType; /** * Use for evaluating. The number of formula is operator dependent. */ formulas?: string[]; text?: string; timePeriod?: IConditionalFormat.TimePeriod; /** * A conditional format must have 1 only 1 of the following properties set. */ style?: IStyle.Properties; colorScale?: IConditionalFormat.ColorScale; dataBar?: IConditionalFormat.DataBar; iconSet?: IConditionalFormat.IconSet; } /** * Provides destination details for the Snapshot when using {@link IHistory.ISnapshot.copyTo}. */ export interface SnapshotDestination { conditionals: IConditionalFormatCollection; range: IRange.Coords; } export interface ISnapshot extends IHistory.ISnapshot { } /** * A JSON representation useful for persistence. */ export interface JSON extends Properties { /** * An A1 representation of a ranges that is the bounding area * for the conditionals. */ ref: IRange.Coords | IRange.Coords[] | string; /** * If associated with a pivot. * * @defaultValue false */ pivot?: boolean; } /** * IListener for {@link IConditionalFormat} events. */ export interface Events extends IModel.Events { } export interface IListeners extends IListener.Callbacks { } } /** * Holds a collection of {@link IConditionalFormat}s. */ export declare interface IConditionalFormatCollection extends ICollection { /** * Add an `IConditional` to the container. * * @param address The address of the item. * @param options {@link IConditionalFormatCollection.AddOptions} */ add(address: ICellRanges.Address, options: IConditionalFormatCollection.AddOptions): IConditionalFormat; /** * Returns items that match the filter criteria. * * If no filter criteria is provided, all items will be returned. * * @param options {@link IConditionalFormatCollection.GetItemsOptions} */ getItems(options?: IConditionalFormatCollection.GetItemsOptions): IConditionalFormat[]; } /** * {@inheritDoc IConditionalFormatCollection} * @see * ### **Interface** * * {@link IConditionalFormatCollection} */ export declare namespace IConditionalFormatCollection { /** * Options for adding a {@link IConditionalFormat}. */ export interface AddOptions extends IConditionalFormat.Properties, ITransaction.OperationOptions { } /** * Options for searching for {@link IConditionalFormat}s. */ export interface GetItemsOptions extends ICollection.GetItemsOptions { /** * If provided, the search will be limited to items that intersect the range. */ address?: ICellRange.Address; /** * Indicate if items that are in hidden headers or marked as hidden should be returned. * * @defaultValue false */ ignoreHidden?: boolean; /** * Only return items that are completely contained with the search bounds. * * @defaultValue false */ fullyContained?: boolean; /** * Search with the given name. This is case insensitive. */ name?: string; } } declare interface IConflatingRanges { append: (major: number, minor: number, value?: T) => void; done: (merge?: boolean) => ISpatialMap.Entry[]; } /** * Defines how an area or shape is filled with color or a pattern. */ export declare interface IFill { /** * Returns the type of fill used. */ getType(): IFill.Type; /** * Returns the fill as a set of css string that are suitable for css. * @remarks * * Not all fill styles will offer an exact css equivalent. * Additionally due to the nature of css having different properties for the same logic value * (for example color, backgroundColor) */ toCSS(darkMode?: boolean, bounds?: Bounds): Properties; /** * Returns the fill as a JSON object. */ toJSON(): IFill.JSON; /** * For type checking. */ readonly isIFill: true; } /** * {@inheritDoc IFill} * @see * ### **Interface** * * {@link IFill} */ export declare namespace IFill { /** * Types of fill styles used for painting surfaces. */ const Type: { /** * No fill. */ readonly None: "none"; /** * A solid color. */ readonly Solid: "solid"; /** * A gradient */ readonly Gradient: "gradient"; /** * A pattern. */ readonly Pattern: "pattern"; /** * An Image. * @remarks * * Not support in cells. This is currently only support in drawML (charts, shapes, powerpoint). */ readonly Image: "pattern"; /** * An Image. * @remarks * * Not support in cells. This is currently only support in drawML (charts, shapes, powerpoint). */ readonly Background: "background"; /** * Inherit the fill from the group. * @remarks * * This has no effect if not in a group. * * Not support in cells. This is currently only support in drawML (charts, shapes, powerpoint). */ readonly Group: "group"; /** * For allowing custom types. * @remarks * Placeholder and not yet implemented. This will have a function callback. */ readonly Custom: "custom"; }; export type Type = typeof Type[keyof typeof Type]; /** * Represents the types of gradients that can be applied to shapes or other elements. */ const GradientType: { /** * A linear gradient, where colors transition along a straight line. */ readonly Linear: "linear"; /** * A path-based gradient, where colors transition along a defined path. * * @remarks * * Currently not directly supported by the rendering engine. */ readonly Path: "path"; /** * A circular gradient, where colors transition radially from a central point. * * @remarks * Not supported by Excel. */ readonly Circular: "circular"; /** * A rectangular gradient, where colors transition within a rectangular shape. * * @remarks * Not supported by Excel or SheetXL rendering engine. */ readonly Rect: "rect"; }; export type GradientType = typeof GradientType[keyof typeof GradientType]; /** * Specifies how a tile is mirrored or flipped when filling a shape or container. */ const TileMirror: { /** * No mirroring is applied. */ readonly None: "none"; /** * The tile is mirrored vertically (flipped along the y-axis). */ readonly Vertical: "v"; /** * The tile is mirrored horizontally (flipped along the x-axis). */ readonly Horizontal: "h"; /** * The tile is mirrored both vertically and horizontally. */ readonly Both: "b"; }; export type TileMirror = typeof TileMirror[keyof typeof TileMirror]; /** * Contains the built-in pattern types. * * @remarks * **TODO** - Rationalize with full drawML list. */ const BuiltInSheetPattern: { /** * 'None' style * * @remarks * Acts like a none fill */ readonly None: "none"; /** * 'None' style * * @remarks * Acts like a solid fill */ readonly Solid: "solid"; /** * 'Dark Gary' style */ readonly DarkGray: "darkGray"; /** * 'Medium Gray' style */ readonly MediumGray: "mediumGray"; /** * 'Light Gray' style */ readonly LightGray: "lightGray"; /** * 'Gray 0.0625' style */ readonly Gray0625: "gray0625"; /** * 'Gray 0.125' style */ readonly Gray125: "gray125"; /** * 'Dark Horizontal' style */ readonly DarkHorizontal: "darkHorizontal"; /** * 'Dark Vertical' style */ readonly DarkVertical: "darkVertical"; /** * 'Dark Down' style */ readonly DarkDown: "darkDown"; /** * 'Dark Up' style */ readonly DarkUp: "darkUp"; /** * 'Dark Grid' style */ readonly DarkGrid: "darkGrid"; /** * 'Dark Trellis' style */ readonly DarkTrellis: "darkTrellis"; /** * 'Light Horizontal' style */ readonly LightHorizontal: "lightHorizontal"; /** * 'Light Vertical' style */ readonly LightVertical: "lightVertical"; /** * 'Light Down' style */ readonly LightDown: "lightDown"; /** * 'Light Up' style */ readonly LightUp: "lightUp"; /** * 'Light Grid' style */ readonly LightGrid: "lightGrid"; /** * 'Light Trellis' style */ readonly LightTrellis: "lightTrellis"; /** * 'Custom' style * @remarks * Then a pattern must be provided. * * **Not yet implemented** */ readonly Custom: "custom"; }; export type BuiltInSheetPattern = typeof BuiltInSheetPattern[keyof typeof BuiltInSheetPattern]; export interface Properties { /** * @see * {@link IFill.getType} */ type: IFill.Type; } /** * Modifiers describe a partial list of properties that can be set with values or shorthand strings. */ export type Modifiers = Partial; /** * Options for updating a fill. */ export type Update = IFill | Modifiers | string | null; /** * A JSON representation useful for persistence. */ export interface JSON extends Properties { } /** * No fill is applied; the area is transparent. */ export interface INone extends IFill { /** * Fill type is always {@link IFill.Type.None}. */ getType(): typeof IFill.Type.None; toJSON(): NoneJSON; } export interface NoneProperties extends IFill.Properties { /** * @see * {@link IFill.ISolid.getColor} */ type: typeof IFill.Type.None; } export interface NoneJSON extends NoneProperties { } /** * A single color fill. */ export interface ISolid extends IFill { /** * Fill type is always {@link IFill.Type.Solid}. */ getType(): typeof IFill.Type.Solid; /** * Returns the color of the fill. */ getColor(): IColor; /** * Sets the stroke color. * * @param color The stroke color. */ setColor(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IFill.ISolid; } export interface SolidProperties extends IFill.Properties { /** * @see * {@link IFill.ISolid.getColor} */ color: C; /** * @see * {@link IFill.ISolid.getType} */ type: typeof IFill.Type.Solid; } export interface SolidJSON extends SolidProperties { } export interface TileProperties { /** * @see * {@link IFill.ITile.getAlign} */ align?: string; /** * @see * {@link IFill.ITile.getMirror} */ mirror?: IFill.TileMirror; /** * @see * {@link IFill.ITile.getBounds} */ bounds?: Rectangle; /** * Create blur noise at the edges of the tile. * * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stitchTiles} */ stitch?: boolean; } /** * Represents a tile used for filling shapes or other elements with a repeating pattern. */ export interface ITile { /** * Specifies the alignment of the tile within its container. * * @remarks * - Possible values: 'tl', 't', 'tr', 'l', 'c', 'r', 'bl', 'b', 'br' (representing top-left, top, top-right, etc.) */ getAlign(): string; /** * Determines how the tile is mirrored or flipped when filling the container. */ getMirror(): IFill.TileMirror; /** * Defines the rectangular bounds of the tile pattern. */ getBounds(): Rectangle; } export interface GradientStopProperties { /** * @see * {@link IFill.IGradientStop.getOffset} */ offset?: number; /** * @see * {@link IFill.IGradientStop.getColor} */ color: C; } /** * Indicates a color change occurs. */ export interface IGradientStop { /** * If not specified then the offsets will be equally weighted based off of the number of stops. */ getOffset(): number; /** * The color of the stop. */ getColor(): IColor; } export interface GradientProperties extends IFill.Properties { /** * @see * {@link IFill.IGradient.getType} */ type: typeof IFill.Type.Gradient; /** * @see * {@link IFill.IGradient.getStops} */ stops?: (GradientStopProperties | C)[]; /** * @see * {@link IFill.IGradient.getGradientType} */ gradientType?: IFill.GradientType; /** * @see * {@link IFill.IGradient.getAngle} */ angle?: number; /** * @see * {@link IFill.IGradient.getFillTo} */ fillTo?: Rectangle; } /** * A gradient fill, where colors transition across the area. */ export interface IGradient extends IFill { /** * Fill type is always {@link IFill.Type.Gradient}. */ getType(): typeof IFill.Type.Gradient; /** * The stops for the gradient. * * @remarks * * This must be at least two stops. */ getStops(): IGradientStop[]; /** * Sets the gradient stops. * * @param stops The gradient stops. */ setStops(stops: (IGradientStop | IColor.Serializable | null)[], options?: IStyle.UpdateOptions): IFill.IGradient; /** * The type of gradient. * @defaultValue GradientType.Linear */ getGradientType(): IFill.GradientType; /** * Sets the gradient type. * * @param type The gradient type. */ setGradientType(type: IFill.GradientType | null, options?: IStyle.UpdateOptions): IFill.IGradient; /** * The angle of the gradient in degrees if gradient type is linear. */ getAngle(): number; /** * Sets the rotation * * @param angle The angle */ setAngle(angle: number | null, options?: IStyle.UpdateOptions): IFill.IGradient; /** * Used for path and circular gradients. */ getFillTo(): Rectangle; /** * Sets the fill area for the gradient. * * @param fillTo The fill area. */ setFillTo(fillTo: Rectangle | null, options?: IStyle.UpdateOptions): IFill.IGradient; /** * Converts the gradient fill to a JSON representation. */ toJSON(): GradientJSON; } export interface GradientJSON extends GradientProperties { } /** * A pattern fill, using a repeating pattern to fill the area. */ export interface IPattern extends IFill { /** * Fill type is always {@link IFill.Type.Pattern}. */ getType(): typeof IFill.Type.Pattern; /** * The foreground color for the pattern. */ getForeground(): IColor; /** * Sets the foreground color. * * @param color The foreground color. */ setForeground(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IFill.IPattern; /** * The background color for the pattern. */ getBackground(): IColor; /** * Sets the background color. * * @param color The background color. */ setBackground(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IFill.IPattern; /** * The type of pattern used. */ getPatternType(): IFill.BuiltInSheetPattern; /** * Sets the pattern type. * * @param type The pattern type. */ setPatternType(type: IFill.BuiltInSheetPattern | null, options?: IStyle.UpdateOptions): IFill.IPattern; /** * Converts the pattern fill to a JSON representation. */ toJSON(): PatternJSON; } export interface PatternProperties extends IFill.Properties { /** * @see * {@link IFill.IPattern.getType} */ type: typeof IFill.Type.Pattern; /** * @see * {@link IFill.IPattern.getForeground} */ foreground?: C; /** * @see * {@link IFill.IPattern.getBackground} */ background?: C; /** * @see * {@link IFill.IPattern.getPatternType} */ patternType?: IFill.BuiltInSheetPattern; } export interface PatternJSON extends PatternProperties { } } /** * Namespace for fonts * * {@link IFont} */ export declare namespace IFont { /** * Specifies the style of the font (normal, italic). */ const Style: { /** * The standard, non-italicized font style. */ readonly Normal: "normal"; /** * The italicized font style. */ readonly Italic: "italic"; }; export type Style = typeof Style[keyof typeof Style]; /** * Specifies the font scheme, indicating its role in the document's typography. */ const Scheme: { /** * The primary font used for headings and major text elements. */ readonly Major: "major"; /** * The secondary font used for body text and less prominent elements. */ readonly Minor: "minor"; /** * No specific font scheme is assigned. */ readonly None: "none"; }; export type Scheme = typeof Scheme[keyof typeof Scheme]; /** * Specifies the style of underline applied to text. */ const UnderlineStyle: { /** * No underline. */ readonly None: "none"; /** * A double underline. */ readonly Double: "double"; /** * A double underline used in accounting contexts (typically thicker and below the descenders). */ readonly DoubleAccounting: "doubleAccounting"; /** * A single underline. */ readonly Single: "single"; /** * A single underline used in accounting contexts (typically below the descenders). */ readonly SingleAccounting: "singleAccounting"; }; export type UnderlineStyle = typeof UnderlineStyle[keyof typeof UnderlineStyle]; /** * Vertical alignment of text within a line. * @see * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/vertical-align} */ const VerticalAlignment: { /** * Aligns the baseline of the cell with the baseline of all other cells in the row that are baseline-aligned. */ readonly Baseline: "baseline"; /** * Aligns the baseline of the element with the subscript-baseline of its parent. */ readonly Sub: "sub"; /** * Aligns the baseline of the element with the superscript-baseline of its parent. */ readonly Super: "super"; }; export type VerticalAlignment = typeof VerticalAlignment[keyof typeof VerticalAlignment]; /** * Advanced text metrics. */ export interface ExtendedMetrics extends Partial, Partial { /** * This is the lineHeight and includes the lineGap */ readonly lineHeight: number; } export interface Metrics { readonly underlinePosition?: number; readonly underlineThickness?: number; readonly strikePosition?: number; readonly strikeThickness?: number; readonly italicAngle?: number; readonly lineHeight: number; readonly baseline: number; readonly lineGap: number; } export interface MetricOptions { isBold?: boolean; isItalic?: boolean; letterSpacing?: number; } export interface Measurer { (text: string, size: number, family: string, options?: IFont.MetricOptions): IFont.ExtendedMetrics; } /** * Override the default mechanism for measuring text. * * @param measurer {@link IFont.Measurer} */ const setSharedMeasurer: (measurer: IFont.Measurer) => void; /** * Returns the {@link IFont.Measurer} used for measuring text. * * @see * {@link setSharedMeasurer} */ const getSharedMeasurer: () => IFont.Measurer; /** * Returns scaling to use for the current device. */ const getDeviceScale: () => number; /** * Provides a font-family fallback based on the PANOSE hex string. * * @param hexPanose The PANOSE string. * @returns a font-family fallback. */ const getPanoseFallback: (hexPanose: string) => string; /** * Represents a font face, encapsulating information about a specific typeface. */ export interface IFontFace { /** * Serializes the font face information into a JSON-compatible object. * * @returns A plain JavaScript object representing the font face data. */ toJSON(): any; /** * The name of the font face (e.g., 'Arial', 'Times New Roman'). */ getFamily(): string; /** * The pitch (or classification) of the font face (e.g., 'variable', 'fixed'). */ getPitch(): string; /** * The Panose classification string for the font face, providing information about its visual characteristics. * @returns `null` if unable to generate. */ getPanose(): string | null; /** * Returns a string representation of the font face. */ toString(): string; /** * A flag indicating that this object is an `IFont` instance. * Useful for runtime type checking. */ readonly isIFont: true; } /** * Font families supported by all/most browsers/platforms. */ const GenericName: { readonly Serif: "serif"; readonly SanSerif: "sans-serif"; readonly MonoSpace: "monospace"; readonly Cursive: "cursive"; readonly Fantasy: "fantasy"; readonly SystemUI: "system-ui"; readonly UISystem: "ui-system"; readonly UISerif: "ui-serif"; readonly UISanSerif: "ui-sans-serif"; readonly UIMonoSpace: "ui-monospace"; readonly UIRounded: "ui-rounded"; readonly Math: "math"; readonly Emoji: "emoji"; readonly Fangsong: "fangsong"; }; export type GenericName = typeof GenericName[keyof typeof GenericName]; } export declare namespace IFontCollection { export { setFontList, getFontList, FontHandle, FindBestMatchOptions, findBestMatch } } /** * This interface defines how to create IFormulaBlocks. * Additionally, it provides a way to evaluate a formula */ declare interface IFormulaParser { /** * Parse a formula string. This generates a sharable formula. * * @param context The context use to evaluate * @param textA1 The formula text in A1 notation. */ parse(context: IFormulaContext, textA1: string): ICalcGraph.IFormulaBlock; /** * Evaluate the formula using a given row and column. * * @param context The context use to evaluate * @param textA1 The formula text in A1 notation. * * @remarks * This is a convenience method that calls parse(textA1).evaluate(context). */ eval(context: IFormulaContext, textA1: string): IRange | Scalar; } /** * Collections of {@link IFunction}. */ export declare interface IFunctionCollection extends ICollection { /** * Add a custom function to a collection. * * @param options */ add(options: IFunction | IFunctionCollection.AddOptions): IFunction; /** * Returns functions that match the filter criteria. * * If no filter criteria is provided, all items will be returned. * * @param options {@link IFunctionCollection.SearchOptions} */ search(options?: IFunctionCollection.SearchOptions): Promise; /** * Convenience method for filter by name. * This is functionally equivalent to getItems({ name }); * * @param name The name to search for This is case insensitive. */ getByName(name: string): IFunction | null; } /** * {@inheritDoc IFunctionCollection} * @see * ### **Interface** * * {@link IFunctionCollection} */ export declare namespace IFunctionCollection { /** * Options for searching a function in the collection. */ export interface SearchOptions { /** * Search with the given name. This is case insensitive. */ name?: string; /** * Search all function descriptors for the given text. This is case insensitive. * * @remarks * If this is specified this will also search the name. */ text?: string; /** * Search with the given name. This is case insensitive. */ category?: string; type?: string; } export interface Events { /** * Called when the collection changes. * * @remarks * This is not used to capture individual item changes. */ onCollectionChange?(source: IFunctionCollection): void; /** * Transaction items have a close event. */ onClose?(source: IFunctionCollection): void; } export interface IListeners extends IListener.Callbacks { } /** * Add a custom function. */ export interface AddOptions { /** * Required. * * @param args * @returns the value of the function. */ execute: (args: any[]) => any; /** * Required. */ declaration: IFunction.DeclarationJSON; /** * Configuration for UI descriptor. * @param locale * @returns */ descriptor?: IFunction.DescriptorJSON | ((locale?: string) => Promise); } } /** * Primary interface for retrieving and setting values in a 2D space. * * To support infinite values IGrid uses an iterator to retrieve values. * * For read-only the minimum implementation required are: * * {@link entries} - Iterator of key/value. * * {@link getCoords} - The size and location of the data. * * For read-write the minimum addition is * * {@link setValues} - Set an IGrid.Tuple2D. * * @see `ArraysGrid` - Implementation using a 2D array. ({@link https://www.sheetxl.com | source}). * @see `GridMap` - Provides a `Map` interface for an IGrid. */ declare interface IGrid { /** * Sets values at specific coordinates within the grid using an array of `Tuple2D`. * * @param values @param values An array of `Tuple2D` objects containing the coordinates and values to set. * * @throws `Error` If the Tuple.GridTuple are invalid see {@link Tuple.GridTuple} or if any the provided * tuples extend beyond the 'maxCoords'. * * @remarks * * Clear values - Setting values to `undefined` or `null` are not treated special and will become * managed values. To clear use delete. * * Immutability - For performance reasons all arrays and values passed in are * accessed directly (zero-copy) so these should be treated as immutable. */ setValues(values: Tuple.GridTuple): this; /** * Returns an iterator for traversing entries in the IGrid. * * The entries must support all IteratorOptions. * * @remarks * Unlike map this is does not need to be an IterableIterator. */ entries(options?: IGrid.IteratorOptions): IGrid.EntryIterator; /** * Returns the bounds for all of the entries or empty if null. */ getCoords(): RangeCoords | null; /** * Determine major axis for storing values. * * This is used to indicate which orientations the 2D array for values will be * interpreted as well as the default orientation for getValues. * * @remarks * This value is only read once and should never change. * * If not implemented the client should default to `RangeOrientation.Row`. */ getOrientation?(): RangeOrientation; /** * Delete all values within a range. * * @param coords The range to delete. * * @remarks * If not implemented and setRange is then setRange will called with null values. */ delete?(coords: RangeCoords | null): boolean; /** * Shift values in a given direction. * * @param coords The range that will shift. * @param direction The direction to shift. * @returns `true` if data was shifted. * @remarks * If this is not implemented shifting ranges will be attempted using * delete and setAt (if implemented). */ shift?(coords: RangeCoords, direction: Direction): boolean; /** * Creates a logical copy of the current values. * * Undo and branching works by creating 'copies' and then rolling back or commit these later. * * @remarks * If this is not available then undo does not work for values. */ clone?(cloneKey?: any): this; /** * Create a new grid but with no data. * * @remarks * Returns an empty grid with the same configuration as the original grid. */ cloneEmpty?(cloneKey?: any): this; /** * Represents a max range or a max number. * * If this is null or undefined then it is assume to be unlimited in size. * @remarks * Coords must always be positive even if no bounds are set */ getMaxCoords?(): RangeCoords | null; /** * Iterate keys. * * @remarks * This is not required unless retrieving keys is significantly less expensive than * entries. There are few internal use cases that use only keys. * @see * {@link IGrid.entries} */ keys?(options?: IGrid.IteratorOptions): IGrid.KeyIterator; /** * Iterate values. * * @remarks * This is not required unless retrieving values is significantly less expensive than * entries. there are few internal uses cases that use only values. * @see * {@link IGrid.entries} * @param options {@link IGrid.IteratorOptions} */ values?(options?: IGrid.IteratorOptions): IGrid.ValueIterator; /** * Returns the value at a specific row and column or `undefined` if not found. * * @param row * @param column * * @remarks * This ignores hiddens rows and columns. */ getValueAt(row: number, column: number): T; /** * Sets a single value on the grid. * * @param row * @param column * * @remarks * Consider using a TupleBuilder. This is always less efficient than setValues. */ setValueAt(row: number, column: number, value: T): void; /** * Copy values from another grid. * * @param destination The grid to copy to. * @param topLeft The coordinates of the destination grid. * @param from The bounds coordinates to copy from. */ copyTo(destination: IGrid, topLeft: CellCoords, from: RangeCoords): void; /** * Returns the number of values. * * @remarks * If this is not implemented an approximation using getCoords will be assumed. */ getCount?(): number; /** * Clears all values. */ clear?(): void; } /** * {@inheritDoc IGrid} * @see * ### **Interface** * * {@link IGrid} */ declare namespace IGrid { /** * Allow for iterating over a subset of values in a given direction. */ interface IteratorOptions { /** * If `null' or `undefined` then all cells will be visited. * @defaultValue undefined */ bounds?: Partial; /** * Determines the orientation that cells are visited. * @defaultValue The ICoordsMap orientation. */ orientation?: RangeOrientation; /** * Iterate in reverse order. * @defaultValue false */ reverse?: boolean; /** * A callback function that allows customization of the iteration process by skipping specific rows. * This is a row orientated implementation of {@link IReadableList.IteratorOptions.processSkip}. * @see * {@link IReadableList.IteratorOptions.processSkip} * {@link IGrid.IteratorOptions.processColumnSkip} */ processRowSkip?: (index: number, reverse?: boolean) => number; /** * A callback function that allows customization of the iteration process by skipping specific columns. * This is a row orientated implementation of {@link IReadableList.IteratorOptions.processSkip}. * @see * {@link IReadableList.IteratorOptions.processSkip} * {@link IGrid.IteratorOptions.processRowSkip} */ processColumnSkip?: (index: number, reverse?: boolean) => number; /** * This is a performance optimization. * To avoid a large amount of object creation a reusable Iterator result can be provided. * If set to true a global instance will be used. * If multiple iterators are being used simultaneously then the client can provide * their own reusable result. * * Additionally if the reuseResults has a CellCoords defined this will also get reused. * The `globalReuseResults` is as follows * * `-1` is use as placeholder to ensure monomorphic types. * If a simple javascript type is used for the value a typed placeholder value should be * used for it as well. * ```ts { done: false, value: [ { colIndex: -1, rowIndex: -1 }, null ] } * ``` * @defaultValue false */ reuseResult?: boolean | IteratorResult; } /** * Entries iterators are arrays of fixed length 2. */ type Entry = [CellCoords, T]; /** * Shorthand type. */ type EntryIteratorResult = IteratorResult>; /** * Shorthand type. */ type EntryIterator = IterableIterator, IGrid.Entry, CellCoords>; /** * Shorthand type. */ type ValueIterator = IterableIterator; /** * Shorthand type. */ type KeyIterator = IterableIterator; } /** * Encapsulates functionalities crucial for maintaining a comprehensive version history * and audit trail within the spreadsheet application. It provides mechanisms to capture, store, * and manage snapshots of the spreadsheet's state at various points in time. * * The primary motivations behind this namespace are: * * - **Versioning and Undo/Redo**: Maintain a detailed history of changes, allowing for easy rollback or review. * - **Copy/Paste**: Create transferable references. * - **Auditing/Change logs**: Enable accountability by tracking who made changes and when they occurred. * - **Snapshot Management**: Efficiently capture and restore spreadsheet states for backup, * analysis, or reuse. * * By offering robust versioning and auditing capabilities, this namespace contributes to a more * reliable, transparent, and user-friendly spreadsheet experience. */ export declare namespace IHistory { /** * Represents an immutable reference to an `Record`, capturing its content and metadata. * @template D The type of the destination for `copyTo`. * @template S The type of the source for `getSource``. * @template C The type of the coordinates the snapshot is bound to. * @template J The type of the JSON for `toJSON`. */ export interface ISnapshot { /** * Copies the snapshot to the specified range. * * @param destination The destination `Snapshot source` where the snapshot will be copied. * @param options {@link IHistory.CopyToOptions} * * @returns A promise that resolves when the copy is complete, or `void` if no asynchronous operation is required. */ copyTo(destination: D, options?: IHistory.CopyToOptions): Promise | C; /** * The source that created the snapshot. * This is used to quickly do comparisons. */ getSource(): S; /** * Retrieves the coordinates that bound the current snapshot. * * @remarks * Different types of snapshots may have different coordinate systems. */ getCoords?(): Readonly; /** * Converts the snapshot to a plain text representation. * * @returns A string or promise resolving to the text representation of the snapshot. */ toText?(): Promise | string; /** * Converts the snapshot to an HTML representation. * * @returns A string or promise resolving to the HTML representation of the snapshot. */ toHtml?(): Promise | string; /** * Converts the snapshot to an image blob. * * @returns A `Blob` or promise resolving to the image representation of the snapshot. */ toImage?(): Promise | Blob; /** * Converts the snapshot to a JSON object. * * @returns A JSON object or promise resolving to the JSON representation of the snapshot. */ toJSON?(): Promise | J; /** * A user friendly name of a the snapshot item. */ getName?(): string; /** * Return the options used when creating. * @remarks * This is done so that we can create a copy. */ getMarkOptions(): ReferenceableClipboard.CopyOptions; /** * For runtime type checking. */ readonly isISnapshot: true; } /** * Options for creating {@link IHistory.ISnapshot}. * **PLACEHOLDER** */ export interface GetSnapshotOptions { } /** * Copy options for {@link IHistory.ISnapshot}. * **PLACEHOLDER** */ export interface CopyToOptions extends GetSnapshotOptions { } /** * Interface for objects that supports returning ISnapshot. */ export interface ISnapshotSource { /** * Represents an immutable reference to an `ICellRange`, capturing its content and metadata. * It may include complex objects such as tables, shapes, images, listeners, or other items. */ getSnapshot(options?: ReferenceableClipboard.CopyOptions): IHistory.ISnapshot; } } /** * Represents a hyperlink for linking to either a URL or a cell address. */ export declare interface IHyperlink { /** * Open the hyperlink. * * @param target Specifies where to open the linked document. DefaultValue `getTarget()`. * @param features Passed to the window open context for external resource. * * @see * [MDN Reference](https://developer.mozilla.org/docs/Web/API/Window/open) */ open(target?: '_self' | '_blank', features?: string): Promise; /** * This is either the address or the cell value. */ getDisplayText(): string; /** * This can be a url or a cell address. * * @remarks * A sheet address needs to start with a #. */ getAddress(): string; /** * Tet for showing addition information about the link that will be * displayed as a tooltip. * * @remarks * Excel has an undocumented tooltip length limit of 255 characters. */ getTooltip(): string; /** * Specified the target frame when opening this Hyperlink. * @defaultValue `newWindow` */ getTarget(): string; /** * For runtime type checking. */ readonly isIHyperlink: true; } /** * {@inheritDoc IHyperlink} * @see * ### **Interface** * * {@link IHyperlink} */ export declare namespace IHyperlink { /** * Modifiers describe a partial list of properties that can be set with values or shorthand strings. */ export type Modifiers = Partial; /** * Used when updating the the value. * @see * `ICellRange.setHyperlink` */ export type Update = IHyperlink.Modifiers | IHyperlink | string | null; /** * Properties available to `IHyperlinks`. */ export interface Properties { /** {@inheritDoc IHyperlink.getDisplayText} */ displayText?: string; /** {@inheritDoc IHyperlink.getAddress} */ address: string; /** {@inheritDoc IHyperlink.getTooltip} */ tooltip?: string; /** {@inheritDoc IHyperlink.getTarget} */ target?: string; } /** * A JSON representation useful for persistence. */ export type JSON = Partial> | string; } declare interface IList extends IListLike { /** * Returns `true` if the object implements IList. * * @remarks * Required to differentiate from Arrays and strings. */ readonly isIList: true; } /** * {@inheritDoc IList} * @see * ### **Interface** * * {@link IList} */ declare namespace IList { /** * Returns true if the object is {@link IList}. * @param arg Object to check. */ const isList: (arg: any) => boolean; /** * Returns true if the object is {@link IListLike}. * * @param arg Object to check. * * @remarks * Similar to {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/isArray | Array.isArray}. * Returns `true` for `string` and `Array` */ const isListLike: (arg: any) => boolean; /** * Helper method that wraps a native Array into a IListLike. * * @param arr The array to wrap. * @param getAt Optional function to allow for altering the value before returning. * * @remarks * Useful for callbacks */ const fromArray: (arr: any[], getAt?: (value: R | undefined, index: number) => T | undefined, setAt?: (value: T | undefined, index: number) => R | undefined, internal?: any[]) => IList; /** * Wraps a native Array into a IList. */ class ArrayList implements IList { private a; private g; private s; constructor(a: any[], getAt?: (value: any | undefined, index: number) => T | undefined, setAt?: (value: T | undefined, index: number) => any | undefined, internal?: any[]); /** {@inheritDoc IListLike.at} */ at(index: number): T | undefined; /** {@inheritDoc IListLike.fromArray} */ fromArray?(arr: T[]): IListLike; /** {@inheritDoc IListLike.length} */ get length(): number; /** {@inheritDoc IList.isIList} */ get isIList(): true; } } /** * Namespace used for listeners to events. */ export declare namespace IListener { /** * A callback for the listener. */ export interface Callback { (source: S, params?: any): any; } /** * The listener objects */ export type Callbacks = Partial<{ [Property in keyof EVENTS]: IListener.Callback; }>; /** * Additional options for a listener. */ export interface Options { /** * If true, the listener will be removed after the first time it is called. * * @defaultValue false; */ once?: boolean; /** * Determines if the listeners is part of the transaction. * * @defaultValue If the listener is added during a transaction this will be true. * * @remarks * There are subtle differences between a transactional listener and a non-transactional listener. * * A transactional listener: * * Will not be fire during undo/redo. * * Will be reverted to it's original add/remove state during an undo/redo. * * A non-transactional listener: * Will not be fire on any change. */ transactional?: boolean; } export interface Remove { (): void; } export interface ISource { /** * Add a set of callbacks to receive notification. * * @param listeners The callbacks object. * @param options Options * @returns A function that can be called to remove the listener. * * @remarks * Listeners are fired in the order that they are added. * */ addListeners(listeners: IListener.Callbacks, options?: IListener.Options): IListener.Remove; } } /** * IListLike objects are orders collections of values. * * While similar to an {@link Array} they have different implementations * to allow for more efficient of large sets of data. */ declare interface IListLike { /** * Return the max element index within the list. */ readonly length: number; /** * Optimization. * * If this is implemented then Lists will attempt to 'compact' when the List is * below a certain size. * * Return unable to generate fromArray with the values. */ fromArray?(arr: T[]): IListLike; /** * Returns the value at a given index. * * @param index The index to retrieve. * @returns The value */ at(index: number): T | undefined; } /** * An interface compatible with ES6 Map and SortedMap. This interface does not * describe the complete interface of either class, but merely the common * interface shared by both. */ declare interface IMap extends IMapSource, IMapSink { } /** * An interface for a functional map, in which the map object could be read-only * but new versions of the map can be created by calling "with" or "without" * methods to add or remove keys or key-value pairs. */ declare interface IMapF extends IMapSource, ISetF { /** Returns a copy of the tree with the specified key set (the value is undefined). */ with(key: K): IMapF; /** Returns a copy of the tree with the specified key-value pair set. */ with(key: K, value: V2, overwrite?: boolean): IMapF; /** Returns a copy of the tree with the specified key-value pairs set. */ withPairs(pairs: [K, V | V2][], overwrite: boolean): IMapF; /** Returns a copy of the tree with all the keys in the specified array present. * @param keys The keys to add. If a key is already present in the tree, * neither the existing key nor the existing value is modified. * @param returnThisIfUnchanged If true, the method returns `this` when * all of the keys are already present in the collection. The * default value may be true or false depending on the concrete * implementation of the interface (in SortedMap, the default is false.) */ withKeys(keys: K[], returnThisIfUnchanged?: boolean): IMapF; /** Returns a copy of the tree with all values altered by a callback function. */ mapValues(callback: (v: V, k: K, counter: number) => R): IMapF; /** Performs a reduce operation like the `reduce` method of `Array`. * It is used to combine all pairs into a single value, or perform conversions. */ reduce(callback: (previous: R, currentPair: [K, V], counter: number, amp: IMapF) => R, initialValue: R): R; /** Performs a reduce operation like the `reduce` method of `Array`. * It is used to combine all pairs into a single value, or perform conversions. */ reduce(callback: (previous: R | undefined, currentPair: [K, V], counter: number, map: IMapF) => R): R | undefined; without(key: K): IMapF; withoutKeys(keys: K[], returnThisIfUnchanged?: boolean): IMapF; /** Returns a copy of the tree with pairs removed whenever the callback * function returns false. */ filter(callback: (k: K, v: V, counter: number) => boolean, returnThisIfUnchanged?: boolean): IMapF; } /** * Write-only map interface (i.e. a drain into which key-value pairs can be "sunk") */ declare interface IMapSink { /** Returns true if an element in the map object existed and has been * removed, or false if the element did not exist. */ delete(key: K): boolean; /** Sets the value for the key in the map object (the return value is * boolean in SortedMap but Map returns the Map itself.) */ set(key: K, value: V): any; /** Removes all key/value pairs from the IMap object. */ clear(): void; } /** * Read-only map interface (i.e. a source of key-value pairs). */ declare interface IMapSource extends ISetSource { /** Returns the number of key/value pairs in the map object. */ size: number; /** Returns the value associated to the key, or undefined if there is none. */ get(key: K): V | undefined; /** Returns a flag asserting whether the key exists in the map object or not. */ has(key: K): boolean; /** * Calls callbackFn once for each key-value pair present in the map object. * The ES6 Map class sends the value to the callback before the key, so * this interface must do likewise. */ forEach(callbackFn: (v: V, k: K, map: IMapSource) => void, thisArg: any): void; /** Returns an iterator that provides all key-value pairs from the collection (as arrays of length 2). */ entries(): IterableIterator<[K, V]>; /** Returns a new iterator for iterating the keys of each pair. */ keys(): IterableIterator; /** Returns a new iterator for iterating the values of each pair. */ values(): IterableIterator; } /** * A model interface is a interface that has: * * 1. Eventing * 2. Transactional * 3. Potentially delete * 4. Potentially readonly */ declare interface IModel extends ITransaction.ITransactional { /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: L, options?: IListener.Options): IListener.Remove; /** * Delete the item. * * @remarks * Not all objects can be deleted. */ delete?(options?: ITransaction.OperationOptions): void; /** * If the model unable to be modified. */ isReadOnly(): boolean; /** * If the model unable to be modified. */ isDeleted(): boolean; /** * Returns an immutable type string. */ getType(): string; /** * For runtime type checking. */ readonly isIModel: true; } /** * {@inheritDoc IModel} * @see * ### **Interface** * * {@link IModel} */ declare namespace IModel { /** * IListener for {@link IModel} events. */ interface Events { /** * Called when any state has been modified. */ onAnyChange?(source: IModel): void; /** * Called when the readOnly status is updated. */ onReadOnlyChange?(source: IModel): void; /** * Called when the model has been deleted. */ onDelete?(source: IModel): void; /** * Called when the transaction is closed. */ onClose?(source: IModel): void; /** * Called when the state has been updated due to a undo/redo and a rerender is required. */ onInvalidated?(source: IModel): void; } interface IListeners extends IListener.Callbacks { } type DeletedCallback = () => void; type ReadOnlyCallback = () => void; interface ConstructorOptions { /** * Use for the creation transaction description. */ createDescription?: string; /** * The type of the model. */ type?: string; /** * If the item is readonly. */ isReadOnly?(): boolean; /** * Notify if the readonly has been updated from the container. * @param callback */ setContainerReadOnlyCallback?(callback: IModel.ReadOnlyCallback): void; /** * Delete from the container. */ deleteFromContainer?(options?: ITransaction.OperationOptions): void; /** * A transaction store that can be used to undo/redo changes to the model. */ transactions?: ITransaction.IStore; /** * JSON state to load. */ json?: J; } } /** * Used for creating maps to models */ declare interface IModelEntry { model: T; spatials: ISpatialMap.Entry[]; removeListener: IListener.Remove; processCoordsChange?: IAnchored.CoordsChangeCallback; } /** * Represents a collection of functions. This is analogous to a file. */ export declare interface IModule { /** * Returns the functions in the module. * * @remarks * This maybe be empty even if there is source. It is possible that a script might contain only comments or other non-executable code. */ getFunctions(): IFunctionCollection; /** * The human-readable source code of the script. * * @remarks * If this property is null, the module may still have compiled functions. */ getSource(): string | null; /** * The language the function is written in. */ getLanguage(): string; getErrors(): any[]; /** * The name of the module. */ getName(): string; /** * Remove the module from the collection. */ delete(): void; /** * Returns a JSON representation of the module. */ toJSON(): IModule.JSON; addListeners(listeners: IModule.IListeners, options?: IListener.Options): IListener.Remove; } /** * {@inheritDoc IModule} * @see * ### **Interface** * * {@link IModule} */ export declare namespace IModule { /** * Results for compiling a module. */ export type CompileResult = CompileResults; /** * Options for compiling a module. */ export type CompileOptions = CompileOptions; /** * Used to serialize a module. */ export type JSON = CompiledModule; export interface Events { /** * When delete is called */ onDelete?(source: IModule): void; } export interface IListeners extends IListener.Callbacks { } } /** * Represents a collection of functions. This is analogous to a file. */ declare interface IModuleCollection extends ICollection { /** * Adds the module to the collection. * * @param uid A unique identifier for the module. This can be either a name, a fully qualified path, or a url (e.g., a file name, a Git url with commit ID). * @param module The module to add. This will generally come from IScript.createModule. * @param options The options for adding the module. */ add(uid: string, module: IModule, options?: IModuleCollection.AddOptions): void; /** * Returns functions that match the filter criteria. * * If no filter criteria is provided, all items will be returned. * * @param options {@link IModuleCollection.GetItemsOptions} */ getItems(options?: IModuleCollection.GetItemsOptions): IModule[]; /** * Convenience method for filtering by name. * This is functionally equivalent to getItems({ name }); * * @param name The name to search for This is case insensitive. */ getByName(name: string): IModule | null; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: IModuleCollection.IListeners, options?: IListener.Options): IListener.Remove; /** * Returns a JSON representation of the module collection. */ toJSON(): Record; } declare namespace IModuleCollection { interface AddOptions { /** * If true, the module will be added to the collection even if it already exists. */ replace?: boolean; /** * If true, the module will be added to the collection even if it has errors. */ ignoreErrors?: boolean; } /** * Options for filtering a function in the collection. */ interface GetItemsOptions extends ICollection.GetItemsOptions { /** * Search with the given name. This is case insensitive. */ name?: string; } interface Events { /** * Called when the collection changes. * * @remarks * This is not used to capture individual item changes. */ onCollectionChange?(source: IModuleCollection): void; /** * Transaction items have a close event. */ onClose?(source: IModuleCollection): void; } interface IListeners extends IListener.Callbacks { } } /** * Capabilities for working with graphical elements that can be * arbitrarily placed (floated) within a virtual 'canvas'. * * Encompasses objects like images, charts, shapes, and custom widgets. * * Key features include: * - Inserting, positioning, resizing, and scaling movables. * - Grouping and layering multiple movables. * - Loading, saving, and copy/pasting movables. */ export declare interface IMovable extends IAnchored, IHistory.ISnapshotSource { /** * Returns the content of the movable. */ getContent(): T; /** * Selects the current movable. * * @returns An async boolean indicating the movable was selected. */ select(options?: IMovable.SelectOptions): Promise; /** * Remove the movable the current selection. * @returns A flag indicating if it was previously in the selection. */ unselect: () => boolean; /** * Returns a flag indicating if the movable is selected. */ isSelected: () => boolean; /** * Set the absolution position of a movable in pixels. * @param bounds The new bounds. * * @remarks * If only some of the points are provided then only those will be moved. */ setBounds(bounds: Partial, options?: ITransaction.OperationOptions): IMovable; /** * Scroll the movable into the viewport. * * @returns A promise that resolve to a `boolean` when the scroll is complete. * * @remarks * This will return when the scroll view is loaded but before any scroll animations have started or finished. */ scrollIntoView: (options?: globalThis.ScrollIntoViewOptions | boolean) => Promise; /** * Returns the absolute bounds of the movable object in pixels. */ getBounds(): Bounds; /** * Set the name for a movable object. * * @param name The name of the IMovable. */ setName(name: string): IMovable; /** * @see * {@link setName} */ getName(): string; /** * This is the alternative text use for assistive technologies. */ setDescription(description: string | null): IMovable; /** * @see * {@link setDescription} */ getDescription(): string; /** * If true then the movable object is hidden. */ setHidden(hidden: boolean): IMovable; /** * @see * {@link setHidden} */ isHidden(): boolean; /** * Set the rotation in degrees. */ setRotation(rotation: number): IMovable; /** * @see * {@link setHidden} */ getRotation(): number; /** * If true then the aspect should be maintained during resize if using the corners or if * the api only specifies one dimension. * * @remarks * Lock aspect ratio will have different default values depending on the movable type. */ setLockAspectRatio(locked: boolean): IMovable; /** * @see * {@link setLockAspectRatio} */ isLockAspectRatio(): boolean; /** * Ses the anchor type. */ setAnchorType(anchorType: IAnchored.Type): IMovable; /** * The order in the z plane. To adjust this use the move methods. */ getZIndex(): number; /** * Move movable to the back in the zIndex. */ moveToBack(): this; /** * Move movable backward one layer in the zIndex. */ moveBackward(): this; /** * Move movable to the font in the zIndex. */ moveToFront(): this; /** * Move movable forward one layer in the zIndex. */ moveForward(): this; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: IMovable.IListeners, options?: IListener.Options): IListener.Remove; /** * If defined this will be called when the containing sheet is being * serialized. */ toJSON?(toResourceId?: (resource: IResource) => number): IMovable.JSON; /** * A specific uuid for use in memory. * * @remarks * Useful for caches and react keys. This is not persisted. */ getUUID(): string; /** * For runtime type checking. */ readonly isIMovable: true; } /** * {@inheritDoc IMovable} * @see * ### **Interface** * * {@link IMovable} */ export declare namespace IMovable { /** * Extends {@link ITypes.SelectOptions} to include options for `IMovable`. */ export interface SelectOptions extends ITypes.SelectOptions { /** * Flag to indicate the the movable should be added to the selection * or should replace the existing selection. * * @remarks * Setting this to true is the equivalent of press the Ctrl in the UI. */ addToSelection?: boolean; } /** * `Events` for {@link IMovable} events. */ export interface Events extends IAnchored.Events { /** * Called when the isSelect status has changed. */ onSelectionChange?(source: IMovable): void; /** * Called when the name has changed. */ onNameChange?(source: IMovable): void; /** * Called when selection changes. */ onBoundsChange?(source: IMovable): void; /** * Called when the anchor type is updated. */ onAnchorTypeChange?(source: IMovable): void; /** * Called when any property has changed. */ onAnyChange?(source: IMovable): void; /** * Request that the movable become focused. * * @returns A promise indicating if the focus was honored. * * @remarks * This should only be handled by one consumer. */ onRequestFocus?(source: IMovable): Promise; } export interface IListeners extends IListener.Callbacks { } /** * Provides destination details for the Snapshot when using {@link IHistory.ISnapshot.copyTo}. */ export interface SnapshotDestination { /** * The movable collection to copy to. */ movables: IMovableCollection; /** * The bounds to copy to. */ bounds: Bounds; } export interface ISnapshot extends IHistory.ISnapshot { /** * Called when the movable is copied to a new container. */ copyTo(destination: IMovable.SnapshotDestination, options?: IMovable.CopyOptions): Promise | Bounds; } export interface CopyOptions extends ReferenceableClipboard.CopyOptions { /** {@inheritDoc IMovable.SelectOptions} */ autoSelect?: boolean | IMovable.SelectOptions; } export interface OffsetCoords extends Partial { /** The row index */ r: number; /** The column index */ c: number; } export interface AnchorOffset { tl: OffsetCoords; br: OffsetCoords; } export interface ClientData { /** * disable selection on movable elements when the sheet is protected * @defaultValue false */ fLocksWithSheet?: boolean; /** * print movable elements when printing the sheet * @defaultValue true */ fPrintsWithSheet?: boolean; } export interface ContentJSON { /** * Identifies the type of movable object. * * @remarks * This must align to a known movable object type. Defined in the IEmbeddedDrawing interface. */ type: string; /** * Underlying json. */ json: J; } export interface JSON { /** * The anchor for the movable object. */ anchor: IMovable.AnchorOffset; /** * The content of the movable object. */ content: ContentJSON; /** * The behavior of how the movable resizes as the anchor/cells change. */ anchorType?: IAnchored.Type; /** * The name of the movable object. */ name?: string; /** * This is the alternative text use for assistive technologies. * * @defaultValue null */ description?: string; /** * If true then the movable object is hidden. * * @defaultValue false */ hidden?: boolean; /** * The rotation in degrees. * * @defaultValue 0 */ rotation?: number; /** * Whether resizing should keep the aspect ratio. */ lockAspect?: boolean; /** * lock specific fields*/ locks?: any; clientData?: IMovable.ClientData; } } /** * Holds a collection of IMovables. */ export declare interface IMovableCollection extends ICollection, IListener.ISource { /** * Add a resource to the movable collection. * * @param options {@link IMovableCollection.AddOptions} * @returns A new {@link IMovable}. */ add(options?: IMovableCollection.AddOptions): Promise; /** * Returns movables that match the filter criteria. * * @param options {@link IMovableCollection.GetItemsOptions} * @returns An Array of {@link IMovable}. * * @remarks * If no filter criteria is provided, all items will be returned. */ getItems(options?: IMovableCollection.GetItemsOptions): IMovable[]; /** * Update all of the selected movable in a single transaction */ updateSelected(update: (movable: IMovable) => void, action?: string): void; /** * Add an image to the current sheet. * Returns an IMovableImage that can be used to manipulate the image or remove it. * * @param image This can be either string to a url, a Resource or an IResource.AddOptions * @param options {@link IMovableCollection.AddOptions} * @returns A Promise that will resolve to the new Movable. */ addImage(image: string | IResource | IResourceCollection.AddOptions, options?: IMovableCollection.AddOptions): Promise; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove; } /** * {@inheritDoc IMovableCollection} * @see * ### **Interface** * * {@link IMovableCollection} */ export declare namespace IMovableCollection { /** * Options for filtering a collection of movables. */ export interface GetItemsOptions extends ICollection.GetItemsOptions { /** * If provided, the search will be limited to items that intersect the range. * @remarks */ address?: ICellRange.Address; /** * Indicate if items that are in hidden headers or marked as hidden should be returned. * @defaultValue false */ ignoreHidden?: boolean; /** * The type to search for. If not provided all items will be returned. */ type?: string; /** * Only find items in this bounds. * @defaultValue Search all */ bounds?: Bounds; /** * Only return items that are completely contained with the search bounds. * @defaultValue false */ fullyContained?: boolean; } /** * Options for adding a movable to the collection. */ export interface AddOptions extends ITransaction.OperationOptions { /** * The type of movable to add. */ type?: string; /** * Initial json value. */ json?: J; /** * If a referenceId is provided then the movable will be linked to the resource. * @param resourceId * @returns IResource */ fromResourceId?: (resourceId: number) => IResource; /** * The boundary for the movable object in pixels. */ bounds?: Partial; /** * The behavior of how the movable resizes as the anchor/cells change. */ anchorType?: IAnchored.Type; /** * If unspecified no selection will occur. * * @remarks * Overrides the default autoSelect to include {@link IMovable.SelectOptions} options. */ autoSelect?: boolean | IMovable.SelectOptions; } } declare interface IMovableEntry extends IAnchorEntry { processZIndexCallback: () => void; processSelectionCallback: (selected: boolean, first: boolean) => void; zIndex: number; } /** * Manages a selection of `IMovable`a. */ export declare interface IMovableSelection extends IListener.ISource { /** * The movable selection. */ getMovableSelection(): readonly IMovable[]; /** * Select a movable object. * * @param movables * @param addToSelection */ selectMovables(movables: readonly IMovable[], addToSelection?: boolean): this; /** * Returns the movable from the selection. * * @param movables */ unselectMovables(movables: IMovable[]): this; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: IMovableSelection.IListeners, options?: IListener.Options): IListener.Remove; } /** * {@inheritDoc IMovableSelection} * @see * ### **Interface** * * {@link IMovableSelection} */ export declare namespace IMovableSelection { export interface Events { /** * Called when the selection has changed. */ onMovableSelectionChange?(source: IMovableSelection): void; } export interface IListeners extends IListener.Callbacks { } } /** * Defined names are descriptive texts that are used to represents a cell, range of cells, formula, or constant value. */ export declare interface INamed extends IModel { /** * A string to identify the type of named item. * * @remarks Immutable */ getType(): string; /** * The underlying item that is being referenced. * * @remarks Immutable */ getValue(): T; /** * Selects the current item. * * @returns An async `INamed`. */ select(options?: ITypes.SelectOptions): Promise; /** * The comment for the defined name. * * @remarks * If null then no comment */ setComment(comment: string | null, options?: ITransaction.OperationOptions): this; /** * {@link setComment} */ getComment(): string; /** * Return the ranges that are associated with the named item or null if no ranges are available. * * @remarks * * Optional */ getRanges?(): ICellRanges | null; /** * If true then the name is not visible. * * @defaultValue false * * @remarks * * Optional * * This does not affect the item itself */ setHidden?(hidden: boolean, options?: ITransaction.OperationOptions): this; /** * A string identifying the scope. This is normally a sheet name * If null then this will be treated as a global scope. * * @defaultValue `null` - Indicating global * * @remarks * * Optional */ setScope?(scope: string | null, options?: ITransaction.OperationOptions): this; /** * {@link setHidden} */ isHidden(): boolean; /** * This is the name that identifies the item. * * @param name The name. */ setName(name: string, options?: ITransaction.OperationOptions): this; /** * {@link setName} */ getName(): string; /** * A string identifying the scope. This is normally a sheet name. * @remarks * If `null` then this will be treated as a global scope. */ getScope(): string | null; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: INamed.IListeners, options?: IListener.Options): IListener.Remove; /** * Return a JSON if this can be serialize. */ toJSON?(): INamed.JSON | null; /** * For runtime type checking. */ readonly isINamed: true; } /** * {@inheritDoc INamed} * @see * ### **Interface** * * {@link INamed} */ export declare namespace INamed { /** * IListener for {@link INamed} events. */ export interface Events extends IModel.Events { /** * Called when the range is updated. */ onRangesChange?(source: INamed): void; } export interface IListeners extends IListener.Callbacks { } /** * A named type used for ranges or formulas. */ export interface IReference extends INamed { /** * A string to identify the type of named item. * * @remarks Immutable */ getType(): 'reference'; /** * The underlying item that is being referenced. * * @remarks Immutable */ getValue(): ICellRanges; /** * Allows for ranges or formulas to be added. */ setReference(ref: string | ICellRanges.Address): this; } export interface ConstructorOptions extends Omit, "type"> { value?: T | null; /** * Required to resolve ranges. */ addressToRanges?: (address: ICellRanges.Address) => ICellRanges; } /** * Defined names are descriptive text that is used to represents a cell, range of cells, formula, or constant value. */ export interface Properties { /** * The name of the defined name. * @remarks * This is the name that is used in formulas. */ name: string; /** * We track named items based on the reference. * * @remarks * If the name is used in a formula this is what will be returned. */ ref: R[]; /** * The comment for the defined name. */ comment?: string; /** * If true not shown in the ui. * * @defaultValue false */ hidden?: boolean; /** * If scope this will be the sheetName. */ scope?: string; /** * The type of named range item */ type?: string; } export interface JSON { name: string; comment?: string; hidden?: boolean; scope?: string; /** * This is interpreted by the named item */ ref?: string; } } /** * A collection of `INamed` items. */ export declare interface INamedCollection extends ICollection { /** * Add a named reference. * * @param name The name of the range. * @param reference An address or formula * @param replaceExisting If `true` will replace existing ranges if one already exists. *default* `false`. * * @remarks * This is case insensitive, must be unique, and must not have any spaces. * This will throw an error if the name is invalid or already exists. */ addReference(name: string, reference: ICellRanges.Address, replaceExisting?: boolean): INamed.IReference; /** * Add a item to the collection. * * @param named The item to add. * * @remarks * This will throw an error if `getNamed()` is invalid or am item with the same name already exists. */ add(named: INamed): INamed; /** * Return the named items. * These are sorted by type then by name. */ getItems(options?: INamedCollection.GetItemsOptions): INamed[]; /** * Lookup a named range with a given name. * * @param name Case insensitive name to lookup * @param global If `true` then will search all scopes. *default* `false` */ getByName(name: string, global?: boolean): INamed | null; /** * Lookup a named range by WorkbookRangeCoords. This will only * return a match if all the ranges are exact matches. * * @deprecated Use getItems({ address }) instead. */ lookupByRanges(ranges: ICellRanges.Address): INamed[] | null; /** * Returns a new valid name given the name return a valid name that closely matches. * This function works by incrementing either the last number or append a number. * * @param template The range to used as a template. * @param scope The scope of the range. If null then this will look for a globally scoped. *default* `null`. * @param ignoreExisting If true then won't check to see if the name is already used. *default* `false`. * @throws `Error` If the template name is invalid. * @returns A valid name. If the name used is valid then will return the same name. */ findValidName(template: string, scope?: string, ignoreExisting?: boolean): string; /** * Validates a name is valid. This is a convenience method That calls `findValidName` * and throws an error if the name returned is not the same. * * @throws `Error` If `findValidName` does not return the same value as the name checking. * * @see * {@link INamedCollection.findValidName} */ validateName(name: string, scope?: string, ignoreExisting?: boolean): void; /** * Return ranges for a given address globally scoped. * * @param address The address to resolve. */ getRanges(address: ICellRanges.Address): ICellRanges; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: INamedCollection.IListeners, options?: IListener.Options): IListener.Remove; /** * Serialize the state. */ toJSON(): INamedCollection.JSON | null; /** * Loads value from JSON, this will clear any existing state * * @param json */ fromJSON(json: INamedCollection.JSON): void; /** {@inheritDoc ITransaction.ITransactional.isClosed} */ isClosed(): boolean; /** {@inheritDoc ITransaction.ITransactional.close} */ close(): void; /** * Used for runtime reflection. */ isNamedCollection: true; } /** * {@inheritDoc INamedCollection} * @see * ### **Interface** * * {@link INamedCollection} */ export declare namespace INamedCollection { export type JSON = INamed.JSON[]; export interface Events { /** * Called when the collection changes. * * @remarks * This is not used to capture individual item changes. */ onCollectionChange?(source: INamedCollection): void; /** * Transaction items have a close event. */ onClose?(source: INamedCollection): void; } export interface IListeners extends IListener.Callbacks { } export interface GetItemsOptions extends ICollection.GetItemsOptions { /** * A string indicating the type. */ type?: string; /** * Scope specified will return only scope and global ranges. * If not specified then will return only global ranges. * * @remarks * Special case if scope === 'all' then all items will be returned. */ scope?: string | 'all'; /** * The search area. * * @defaultValue Search the global scope of the NamedCollection. */ address?: ICellRanges.Address; /** * If true return any Named that is in the bounds even if only partially bounded. * * @defaultValue false */ allowExtrudes?: boolean; } export interface ConstructorOptions { /** * Required to resolve ranges. */ addressToRanges: (address: ICellRanges.Address) => ICellRanges; /** * Returns the current scope. */ getCurrentScope?: () => string; /** * A transaction store that can be used to undo/redo changes to the names. */ transactions?: ITransaction.IStore; /** * If the collection is readonly. */ isReadOnly?: () => boolean; /** * JSON state to load. */ json?: INamedCollection.JSON; } } declare interface IndexedHeaders { sizes: RunningHeaderSize[]; hidden: HiddenRun[]; } /** * Builds a list of measurable spans. We don't allow any gaps to make search faster. * Note - These are saved as pixels so that we can render quickly. * We could be even smarter and only re-index from a given offset but optimization for later (if needed). */ declare const indexHeaderSizes: (runs: ITypes.RunCoordValue[], defaultSize: number, scaleFactor: number) => IndexedHeaders; /** * Converts a list of indices into Runs (an array of RunCoords). * * @param indices A list of indices. * @param presorted If set to true will not sort. @defaultValue false */ declare const indicesToRuns: (indices: number[], presorted?: boolean) => RunCoords[]; declare interface InternalCreateSheet { ( /** * The id of the sheet being created. */ id: number, /** * The name of the new sheet. */ name: string, /** * @defaultValue - ISheet.Visibility.Visible */ visibility: ISheet.Visibility, /** * The location of the sheet. * @defaultValue - End of sheets */ index: number, /** * The JSON representation of the sheet. */ json: ISheet.JSON): ISheet; } /* Excluded from this release type: InternalTupleUpdate */ /** * Finds the intersection of 2 runs. * @returns `null` if no intersection */ declare const intersectRuns: (a: RunCoords, b: RunCoords) => RunCoords; /** * Interface for working with Pictures (both Images and SVG). */ export declare interface IPicture extends IModel { toJSON(toResourceId?: (resource: IResource) => number): IPicture.JSON; /** * Returns an image blob. */ toImage(): Promise; /** * Return an html string. */ toHtml(): Promise | string; /** * Returns a local object URL for placing in an image tag. */ getDetails(): Promise; } /** * {@inheritDoc IPicture} * @see * ### **Interface** * * {@link IPicture} */ export declare namespace IPicture { /** * A set of values that can be set on an IPicture. * * @see * {@link IPicture} */ export interface Properties { } export interface JSON { resId?: number; effects?: string[]; } export interface Details { /** * The size of the image without any constraints. This info is determined by the file. */ getNaturalSize(): Size; /** * As a url that can be attached to the dom. */ asUrl(): string; /** * For SVG text. */ asSVGText(): string | null; } export interface Events extends IModel.Events { } export interface IListeners extends IListener.Callbacks { } } /** * Namespace for print-related configurations and settings. */ export declare namespace IPrint { /** * Interface representing multi-page print options. */ export interface MultiPage { /** * Whether content should be aligned with the page margins. */ alignWithMargins?: boolean; /** * Specifies if the first page is different from subsequent pages. */ differentFirst?: boolean; /** * Specifies if odd and even pages should have different settings. */ differentOddEven?: boolean; /** * Whether the content should scale proportionally with the document. */ scaleWithDoc?: boolean; } /** * Interface for configuring headers and footers for print, supporting * different settings for first, odd, and even pages. */ export interface HeaderFooter extends MultiPage { /** * Configuration for general header and footer settings. */ headerFooter?: MultiPage; /** * Configuration for the footer on even pages. */ evenFooter?: MultiPage; /** * Configuration for the header on even pages. */ evenHeader?: MultiPage; /** * Configuration for the footer on the first page. */ firstFooter?: MultiPage; /** * Configuration for the header on the first page. */ firstHeader?: MultiPage; /** * Configuration for the footer on odd pages. */ oddFooter?: MultiPage; /** * Configuration for the header on odd pages. */ oddHeader?: MultiPage; } /** * Interface representing the margins of a printed page, specified in inches. */ export interface PageMargin { /** * Margin from the bottom of the page. */ bottom?: number; /** * Distance of the footer from the bottom of the page. */ footer: number; /** * Distance of the header from the top of the page. */ header: number; /** * Margin from the left side of the page. */ left: number; /** * Margin from the right side of the page. */ right: number; /** * Margin from the top of the page. */ top: number; } /** * Interface for configuring page setup options for print. */ export interface PageSetup { /** * Whether to print in black and white. */ blackAndWhite?: boolean; /** * Specifies how cell comments are printed. * @see {@link https://c-rex.net/samples/ooxml/e1/Part4/OOXML_P4_DOCX_ST_CellComments_topic_ID0EXMDFB.html#topic_ID0EXMDFB} */ cellComments?: string; /** * The number of copies to print. */ copies?: number; /** * Whether to print in draft mode for quicker printing. */ draft?: boolean; /** * Specifies how errors should be displayed in the print. * @see {@link https://c-rex.net/samples/ooxml/e1/Part4/OOXML_P4_DOCX_ST_PrintError_topic_ID0EUTTFB.html#topic_ID0EUTTFB} */ errors?: string; /** * The page number to start printing from. */ firstPageNumber?: number; /** * The number of pages to fit vertically. */ fitToHeight?: number; /** * The number of pages to fit horizontally. */ fitToWidth?: number; /** * The horizontal DPI (dots per inch) for printing. */ horizontalDpi?: number; /** * The orientation of the page (portrait or landscape). * @see * {@link https://c-rex.net/samples/ooxml/e1/Part4/OOXML_P4_DOCX_ST_Orientation_topic_ID0E4XPFB.html#topic_ID0E4XPFB} */ orientation?: string; /** * Specifies the order of pages when printed. * @see * {@link https://c-rex.net/samples/ooxml/e1/Part4/OOXML_P4_DOCX_ST_PageOrder_topic_ID0EN5PFB.html#topic_ID0EN5PFB} */ pageOrder?: string; /** * Specifies the paper size for printing (enum values 1-68). * @see * {@link https://c-rex.net/samples/ooxml/e1/Part4/OOXML_P4_DOCX_pageSetup_topic_ID0EHZ54.html#topic_ID0EHZ54} */ paperSize?: number; /** * Specifies the scaling factor for printing (between 10 and 400). */ scale?: number; /** * Whether to use the first page number specified in `firstPageNumber`. */ useFirstPageNumber?: boolean; /** * Whether to use the printer's default settings for the print job. */ usePrinterDefaults?: boolean; /** * The vertical DPI (dots per inch) for printing. */ verticalDpi?: number; } /** * Interface for additional properties of page setup, * such as auto page breaks and fitting content to a page. */ export interface PageSetUpProperties { /** * Whether to automatically break pages when content overflows. */ autoPageBreak?: boolean; /** * Whether content should fit to a single page when printed. */ fitToPage?: boolean; } /** * Interface for configuring print options, such as grid lines * and content alignment. */ export interface PrintOptions { /** * Whether to print grid lines on the sheet. */ gridLines?: boolean; /** * Whether grid lines are explicitly set for printing. */ gridLinesSet?: boolean; /** * Whether to print row and column headings. */ headings?: boolean; /** * Whether content should be horizontally centered on the page. */ horizontalCentered?: boolean; /** * Whether content should be vertically centered on the page. */ verticalCentered?: boolean; } /** * Interface for outline properties used in print, such as * the summary position and style application. */ export interface OutlineProperties { /** * Whether to apply styles to outline symbols. */ applyStyles?: boolean; /** * Whether to display outline symbols in the print. */ showOutlineSymbols?: boolean; /** * Whether the summary rows are displayed below the details. */ summaryBelow?: boolean; /** * Whether the summary columns are displayed to the right of the details. */ summaryRight?: boolean; } export type Break = ITypes.RunCoordValue<{ man?: boolean; pt?: boolean; }>; } /** * Contains interfaces for working with properties. */ export declare namespace IProperties { /** * Represents an interface for ranged items with customizable properties, * supporting operations such as retrieving properties at a given coordinate, * cloning with updates, splitting, and merging. * * @typeParam P - The type representing the properties associated with the range. * @typeParam J - The type representing the JSON-serializable representation of the range. */ export interface ICellRanged

{ /** * Retrieves the coordinates for the range. * * @returns The range's coordinates. * * @remarks * The coordinates are not the coordinates where this is contained but the coordinates for access getPropertiesAt. */ getCoords(): Readonly; /** * Retrieves the properties associated with a specified cell within the range. * * @param rowIndex The row index within the range. * @param colIndex The column index within the range. * @param value The value at the coordinates. * @returns The properties associated with the specified cell as a read-only object. */ getPropertiesAt(rowIndex: number, colIndex: number, value: Scalar): Readonly

; /** * Creates a new instance of the range with specified updates applied. * * @param updates The updates to apply to the range's properties. * @returns A new `ICellRanged` instance with the applied updates. */ cloneWithUpdate?(updates: IProperties.ResolvableProperties

): this; } /** * Recursively converts a type into a derived type where any field can be a string or a function that takes the old value. */ export type ResolvableProperties = Partial<{ [Property in keyof T]: T[Property] | string | null | ResolvableProperties; }>; } /** * Interface representing the base protection functionality for both workbook and sheet protection. * This interface provides methods for locking, unlocking, and managing the protection state. */ export declare interface IProtection { /** * Locks the object (workbook or sheet or range) with the specified options and password. * * @param password The password required to unlock the object. * @param properties The properties to allow to remain unlocked. * @param algorithm The algorithm for encrypting the password. * @param spinCount The spin count for encrypting the password. * @returns The `IProtection` instance for method chaining. * * @remarks * By default all properties are locked but you can specify which properties to remain unlocked. */ lock(properties?: Partial

, password?: string, algorithm?: string, spinCount?: number): Promise>; /** * Unlocks the object (workbook or sheet) using the provided password. * * @param password The password required to unlock the object. * @returns The `IProtection` instance for method chaining. * * @remarks * If the correct password is provided, protection is removed from the object. */ unlock(password?: string): Promise>; /** * Temporarily disables protection with the provided password. * * @param password The password required to pause protection. * @returns The `IProtection` instance for method chaining. * * @remarks * This method allows temporarily pausing protection without permanently unlocking the object. * Use {@link resume} to restore protection. */ pause(password?: string): Promise>; /** * Checks if the object is currently locked. * * @returns `true` if the object is locked, `false` otherwise. * * @remarks * This method returns `true` If the lock is active. */ isLocked(): boolean; /** * Verifies if the provided password matches the current protection password. * * @param password The password to check against the current protection. * @returns `true` if the password is correct, `false` otherwise. * * @remarks * Use this method to validate the password before unlocking or modifying the protection settings. */ checkPassword(password?: string): Promise; /** * Returns true if the protection has a password. */ hasPassword(): boolean; /** * Resumes protection that was previously paused. * * @returns The `IProtection` instance for method chaining. * * @remarks * This method restores protection after it was paused using the {@link pause} method. */ resume(): IProtection; /** * Checks if the object has a locked but is paused. * * @returns `true` if the object is locked but paused, `false` otherwise. */ isPaused(): boolean; /** * If the element is protected as readonly. * * @remarks * Readonly is set cannot be changed. */ isReadOnly(): boolean; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: IProtection.IListeners, options?: IListener.Options): IListener.Remove; toJSON(): IProtection.JSON; } /** * {@inheritDoc IProtection} * @see * ### **Interface** * * {@link IProtection} */ export declare namespace IProtection { export interface Events { /** * Called when the protection has changed collections has changed have changed. */ onChange?(source: IProtection): void; /** * Called when the protection has changed collections has changed have changed. */ onLockChange?(source: IProtection): void; } export interface IListeners extends IListener.Callbacks, IProtection.Events> { } export interface Properties { } export interface JSON extends Properties { /** * If this is specified then a password will be requested to unlock. * If this is an empty object this indicates the object has been locked but without a password */ password?: Partial; identities?: IProtection.IdentityProvider[]; } /** * Represents a locally stored encrypted password. * * @see * * {@link https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.presentation.modificationverifier?view=openxml-2.8.1} */ export interface EncryptedPassword { /** * The hashed value that was generated during the protection process. * This value is typically derived from the combination of a password and a salt. */ hash: string; /** * The salt value that was used during the protection process. * The salt is combined with the password to produce the hash, adding an additional layer of security. */ salt: string; /** * The name of the hash algorithm to be used. * Common values include `SHA-256`, `SHA-384`, and `SHA-512`. * * @defaultValue `SHA-512` */ algorithm?: string; /** * The number of iterations (also known as spin count) used during the hash computation process. * A higher number increases the security by making brute-force attacks more difficult but also increases computation time. * * @defaultValue `100000`. */ spinCount?: number; } /** * **PLACEHOLDER** - Will integrate into the user identity system. */ export interface IdentityProvider { /** * Optional setting to specify the relative security descriptor. * * The descriptor defines user accounts who may edit this range without providing a password to access the range. Removing this attribute shall * remove all permissions granted or denied to users for this range. */ descriptor: string; } } /** * Interface representing a range selection within a sheet. */ export declare interface IRangeSelection { /** * Navigates the entire sheet * * @param direction The direction to navigate. * @param select Whether to select the cell after navigating. * @param contentful Whether to navigate to contentful cells only. * @param incrementAmount The amount to increment. * @returns The current instance. */ navigate(direction: IRange.Direction, select?: boolean, contentful?: boolean, incrementAmount?: number): this; /** * Checks if the entire range is selected. * @returns True if the entire range is selected, otherwise false. */ isEntire(): boolean; /** * Returns the coordinates of the selection. * @returns The selection coordinates. */ getCoords(): IRangeSelection.Coords; /** * Returns the selection as an array of IRange.Coords. * * @param coords Optional coordinates to convert. If not provided, uses the current selection. * * @remarks * The first element is always the active range. */ getRangesCoords(coords?: Partial): IRange.Coords[]; /** * Updates the selection coordinates. * * @param coords The new coordinates. * @returns The current instance. */ updateCoords(coords: IRangeSelection.Coords): this; /** * Traverses the selection, moving to the next cell based on the orientation. * * @param orientation The orientation to traverse. Default is `ICellRange.Orientation.Row`. * @param reverse Whether to traverse in reverse. Default is false. * @returns The current instance. * @remarks Useful for pressing tab or enter from the UI. */ traverse(orientation?: IRange.Orientation, reverse?: boolean): this; /** * Updates the selection using a new start and end. * * @param start The start cell. * @param end The end cell. Default is the start cell. * @param anchor The anchor cell. */ clearAndModify(start: Partial, end?: Partial, anchor?: Partial): void; /** * Modifies the selection around the anchor. * * @param cellAnchor The anchor cell. * @param cellPivot The pivot cell. * @param resetAnchor Whether to reset the anchor. Default is false. */ modify(cellAnchor: Partial, cellPivot?: Partial, resetAnchor?: boolean): void; /** * Clears the range selections. * * @remarks This does not affect the cell. */ clear(): void; /** * Appends a selection to the current selection. * * @param start The start cell. * @param end The end cell. Default is the start cell. * @param anchor The anchor cell. * @remarks This is used to support the CMD key behavior in the UI. */ append(start: IRange.CellCoords, end?: IRange.CellCoords, anchor?: Partial): void; /** * A special range used during drag. * @param range The range or null. * * @remarks * This fires an event. */ setAdjusting(range: IRangeSelection.Coords | null): void; /** * Returns the adjusting range. */ getAdjusting(): IRangeSelection.Coords | null; /** * Adds listeners to the selection. * @param listeners The listeners to add. * @param options Options for the listeners. * @returns A function to remove the listeners. */ addListeners(listeners: IRangeSelection.IListeners, options?: IListener.Options): IListener.Remove; } /** * {@inheritDoc IRangeSelection} * @see * ### **Interface** * * {@link IRangeSelection} */ export declare namespace IRangeSelection { /** * Represents a selection of ranges with an active range and an active cell. */ export type Coords = SelectionCoords; /** * Type representing different selection policies. */ export type SelectionPolicy = 'single' | 'range' | 'multiple'; /** * Type representing different new selection modes. */ export type NewSelectionMode = 'clear' | 'modify' | 'append'; /** * Events for {@link IRangeSelection}. */ export interface Events { /** * Called when the selection changes. * * @param source The source of the event. */ onChange?(source: IRangeSelection): void; /** * Called when the selection is adjusting. * * @param source The source of the event. */ onAdjustingChange?(source: IRangeSelection): void; } /** * Listeners for IRangeSelection events. */ export interface IListeners extends IListener.Callbacks { } /** * Options for constructing an IRangeSelection. */ export interface ConstructorOptions { /** * The sheet to which the selection belongs. */ sheet: ISheet; /** * Selection policy. */ selectionPolicy?: IRangeSelection.SelectionPolicy; /** * New selection mode. */ newSelectionMode?: IRangeSelection.NewSelectionMode; } } /** * A resource is an item referenced elsewhere with the application. * This will track when a resource is no longer being used and can be removed. */ export declare interface IResource extends JSONSerializableAsync { /** * Returns the resource as a Promise to array buffer. */ toBuffer(): Promise; /** * The mimetype of the resource. */ getType(): Promise; /** * An optional name for the resource. */ getName(): string | null; /** * For saving to json resources. */ toJSONAsync(): Promise; /** * Add a reference to the resource. * @param ref The object to strongly hold the resource. */ addReference(ref: any): void; /** * Delete a reference to the resource. * @param ref */ deleteReference(ref: any): void; /** * This does not follow the standard listener pattern and is only called once. * @param listener */ addUnloadListener(listener: IResource.IUnloadListener): void; /** * `true` if the resource if all references have been deleted. */ isClosed(): boolean; /** * For runtime type checking. */ readonly isIResource: true; } /** * {@inheritDoc IResource} * @see * ### **Interface** * * {@link IResource} */ export declare namespace IResource { export interface IUnloadListener { onUnload: (ref: IResource) => void; } export interface JSON { /** * A type for the data. */ type?: string; /** * A base64 encoded string of the data. */ base64: string; /** * The name of the resource. * This is optional but if provided then resource lookup will use this as a cache key. */ name?: string; } } /** * Collections of {@link IResource}. */ export declare interface IResourceCollection extends ICollection { /** * Add a resource to a collection with an initial reference. * @param resource * @remarks * Resources are not removed from the the collection. They are autoGCed when there are no references. */ add(resource: string | IResource | IResourceCollection.AddOptions): IResource; /** * Returns a list of all resources in the collection. * @param options */ getItems(options?: ICollection.GetItemsOptions): IResource[]; /** * Used for saving resource. Returns a visitor that will allow for a toJSON that * will only save the resource that were accessed within the persist scope. */ beginPersist(): IResourceCollection.IPersistScope; } /** * {@inheritDoc IResourceCollection} * @see * ### **Interface** * * {@link IResourceCollection} */ export declare namespace IResourceCollection { /** * When adding a shared source there are a number of ways to create it * Either from a base64 string, a buffer, a fetch, or a custom resolve function. */ export interface AddOptions { /** * An encoding for the resource. One and only of these should be provided */ base64?: string | Promise; fetch?: string | FetchArgs; buffer?: ArrayBuffer | Promise | (() => ArrayBuffer | Promise); file?: File | Promise; /** * Type type of the resource. * * @remarks * This must be a known type */ type?: string; /** * The name of the resource. * This is optional and purely for human consumption and is not used by the system. */ name?: string; } export interface GetItemsOptions extends ICollection.GetItemsOptions { } export interface IPersistScope { /** * For a resource this will return a number that can be used to reference the resource in the persisted json. * @param resource */ toResourceId(resource: JSONSerializableAsync): number | null; /** * For a given resourceId this will return the resource. * @param resourceId */ fromResourceId(resourceId: number): JSONSerializableAsync | null; /** * Called when done persisting. */ endPersist(): void; /** * Loads the json. * @param json */ fromJSON(json: J[]): void; /** * This can be called multiple times. */ toJSONAsync(): Promise; } } /** * Contains interfaces for working with scripts. * * @remarks * Scripts are collections of modules that contain functions. * * Modules are analogous to files, and functions are the executable code within those modules. */ export declare interface IScript { /** * Returns a collection of modules. */ getModules(): IModuleCollection; /** * Creates a module from the source code. * * @param options */ createModule(options?: IModule.CompileOptions): Promise; /** * Adds a module to the script. * @param uid * @param module * @param options */ addModule(uid: string, module: IModule, options?: IModuleCollection.AddOptions): void; /** * Executes a macro function. * * @param functionName The name of the function to execute. * @param moduleId The ID of the module containing the function. */ executeMacro(functionName: string, moduleId?: string): Promise; /** * Will start scripting engine and autoRun scripts. */ start(): Promise; /** * Returns if the script is readonly. */ isReadOnly(): boolean; /** * Convenience method for creating a module from a file. * * @remarks * equivalent to `getModules().search( { type: 'macro', name } )` */ searchFunctions(options?: IScript.SearchOptions): Promise; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: IScript.IListeners, options?: IListener.Options): IListener.Remove; /** * Returns a JSON representation of the script. */ toJSON(): Record; } /** * {@inheritDoc IFunctionCollection} * @see * ### **Interface** * * {@link IFunctionCollection} */ export declare namespace IScript { /** * Events for {@link ISheet}. */ export interface Events { /** * Called before search. */ onBeforeSearch?(source: IScript): Promise | void; /** * Called after load. */ onChange?(source: IScript): void; /** * Called before load. If any exception is thrown this * exception will be returned to the client and delete will be aborted. */ onBeforeSave?(source: IScript): Promise | void; /** * Called after save. */ onSave?(source: IScript): void; } export interface IListeners extends IListener.Callbacks { } /** * The results from a macro script */ export interface MacroResults { params: any[]; results: any; } export interface SearchOptions extends IFunctionCollection.SearchOptions { moduleName?: string; includeBuiltIn?: boolean; } } /** * An interface for a functional set, in which the set object could be read-only * but new versions of the set can be created by calling "with" or "without" * methods to add or remove keys. This is a subinterface of IMapF, * so the items in the set may be referred to as "keys". */ declare interface ISetF extends ISetSource { /** * Returns a copy of the set with the specified key included. * @description You might wonder why this method accepts only one key * instead of `...keys: K[]`. The reason is that the derived interface * IMapF expects the second parameter to be a value. Therefore * withKeys() is provided to set multiple keys at once. */ with(key: K): ISetF; /** * Returns a copy of the set with the specified key removed. */ without(key: K): ISetF; /** Returns a copy of the tree with all the keys in the specified array present. * @param keys The keys to add. * @param returnThisIfUnchanged If true, the method returns `this` when * all of the keys are already present in the collection. The * default value may be true or false depending on the concrete * implementation of the interface (in SortedMap, the default is false.) */ withKeys(keys: K[], returnThisIfUnchanged?: boolean): ISetF; /** Returns a copy of the tree with all the keys in the specified array removed. */ withoutKeys(keys: K[], returnThisIfUnchanged?: boolean): ISetF; /** Returns a copy of the tree with items removed whenever the callback * function returns false. * @param callback A function to call for each item in the set. * The second parameter to `callback` exists because ISetF * is a subinterface of IMapF. If the object is a map, v * is the value associated with the key, otherwise v could be * undefined or another copy of the third parameter (counter). */ filter(callback: (k: K, v: any, counter: number) => boolean, returnThisIfUnchanged?: boolean): ISetF; } /** * Read-only set interface (subinterface of IMapSource). * The word "set" usually means that each item in the collection is unique * (appears only once, based on a definition of equality used by the * collection.) Objects conforming to this interface aren't guaranteed not * to contain duplicates, but as an example, SortedMap implements this * interface and does not allow duplicates. */ declare interface ISetSource { /** Returns the number of key/value pairs in the map object. */ size: number; /** Returns a flag asserting whether the key exists in the map object or not. */ has(key: K): boolean; /** Returns a new iterator for iterating the items in the set (the order is implementation-dependent). */ keys(): IterableIterator; } /** * An `ISheet` represents a collection of elements (such as {@link ICellRange | ranges}, * {@link ITable | tables}, etc) contained within and visualized through a {@link ISheetView | view}. * * This interface provides methods for accessing its elements and event handling. * * Most interactions with a {@link ISheet | sheet} are done using either a {@link ICellRange | range} or {@link ICellRanges | ranges}. * * @remarks * While a {@link ISheet | sheet} can be used stand-alone it is typically used within the context of a {@link IWorkbook | workbook}. * * ### **Key Methods** * * * {@link ISheet.getRange} - For interacting with {@link ICell | cells} and {@link Scalar | values} and formatting. * * {@link ISheet.getTables} - For managing {@link ITable | tables}. * * {@link ISheet.getView} - For non-data related properties such as selection or frozen headers. * * {@link IWorkbook} - For working with collections of `ISheets`. */ export declare interface ISheet extends ITransaction.ITransactional, IListener.ISource { /** * Returns an {@link ICellRange} used to interact with a * a rectangular 2D collection of cells at a specific range. * * @param address Address of the ranges. * @param options Options for the ranges. */ getRange(address: ICellRange.Address, options?: ICellRange.GetRangeOptions): ICellRange; /** * Returns a {@link ICell} at the specified address. * * @param address Address of the cell. */ getCell(address: ICell.Address): ICell; /** * Returns an {@link ICellRanges}. An {@link ICellRanges} is an ordered list of * {@link ICellRange}s. These are used to interact with a set of contiguous 2D ranges. * * @param address Address of the ranges. * @param options Options for the ranges. */ getRanges(address: ICellRanges.Address, options?: ICellRange.GetRangeOptions): ICellRanges; /** * Returns the range for the entire sheet. * * @see * {@link ICellRange} */ getEntireRange(options?: ICellRange.GetRangeOptions): ICellRange; /** * Returns the smallest range within the sheet that contains any used cells. * @see * {@link ICellRange.getUsedRange} */ getUsedRange(options?: ICellRange.GetRangeOptions): ICellRange; /** * Returns the current selection. * * @remarks * This allows for listening to selection changes and advanced navigation. */ getSelection(): IRangeSelection; /** * Returns the selected cell. */ getSelectedCell(): ICell; /** * Returns a range of cells for the current selection. * * @see * {@link ICellRange} */ getSelectedRange(options?: ICellRange.GetRangeOptions): ICellRange; /** * Returns ranges of cells for the current selection. */ getSelectedRanges(options?: ICellRange.GetRangeOptions): ICellRanges; /** * Returns an iterator of ICells that match the results. * * @param options This is either a search string or {@link ICellRange.FindOptions}. * * @remarks * This is the equivalent of `getEntireRange().find`. * @see * {@link ICellRange.find} */ find(options: string | ICellRange.FindOptions): Iterator; /** * Enable and return an {@link IAutoFilter}. * * @remarks * Only one {@link IAutoFilter} is allowed so this will * return the same instance if it has already been created. */ insertFilter(address?: ICellRange.Address): IAutoFilter; /** * Enable and return an {@link IAutoSort}. * * @remarks * Only one {@link IAutoFilter} is supported so this will * return the same instance if it has already been created. */ insertSort(address?: ICellRange.Address): IAutoSort; /** * Returns the {@link IAutoFilter} created using {@link insertFilter}. * * @returns The current filter or `null` if there is no filter. */ getFilter(): IAutoFilter | null; /** * Returns the {@link IAutoSort} created using {@link insertSort}. * * @returns The current sort or `null` if there is no sort. */ getSort(): IAutoSort | null; /** * Returns a collection of tables that are embedded in this sheet. */ getTables(): ITableCollection; /** * Returns a collection of movables that are embedded in this sheet. */ getMovables(): IMovableCollection; /** * Returns the row headers managed by the sheet. */ getRowHeaders(): ISheetHeader; /** * Returns the column headers managed by the sheet. */ getColumnHeaders(): ISheetHeader; /** * Return a custom color or `null` if no custom color has been set. * * @defaultValue null */ getTabColor(): IColor; /** * See the tab color for the sheet. * * @param color The color * * @remarks * * If set to `null` the color will revert to the default. * * The tab color is not used by the sheet but rather by the workbook. */ setTabColor(color: IColor | string | null): this; /** * Returns the sheet protection. */ getProtection(): ISheetProtection; /** * Returns the current view settings * View settings determine how the sheet is displayed and interacted with (e.g., frozen panes, zoom level, selection) but do not affect the underlying data itself. * * @returns The {@link ISheetView} object representing the current view settings. */ getView(): ISheetView; /** * Set a specific view. * * @param view The view properties. */ setView(view: ISheetView): this; /** * Returns `IStyleCollection` associated with this sheet. */ getStyles(): IStyleCollection; /** * Returns the current shared resources. */ getResources(): IResourceCollection; /** * Returns the current shared resources. */ getStrings(): IStringCollection; /** * Returns the current shared resources. */ getTransactions(): ITransaction.IStore; /** * Indicates if the sheet is using 1904 dates. * * @remarks * This can not be set on the `ISheet`. This is managed by the sheet's container. */ isDate1904(): boolean; /** * Returns the column width as a font unit. * * This is used as an informative tooltip. * * @param pixelWidth * * @see * * {@link https://docs.microsoft.com/en-us/office/troubleshoot/excel/determine-column-widths} * * {@link https://www.ablebits.com/office-addins-blog/change-autofit-column-width-excel/} */ getColumnWidthAsFontUnit(pixelWidth: number): number; /** * Returns the {@link ICellRange | range} for a given pixel bounds. * * @param bounds */ getRangeAtBounds(bounds: Bounds, options?: ICellRange.GetRangeOptions): ICellRange; /** * Creates a cell that is not including at a coordinate but adopts all rendering. * * Useful for previewing values such as tooltip. If the coords are passed it will return * a disconnect cell update for that value. * @param update Cell Update * @param coords Optional CellCoord * @returns A detached ICell * * @remarks * Does not add to the sheet but provides a standalone ICell. */ createTemporaryCell(update: ICell.Update, coords?: IRange.FixableCellCoords): ICell; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: ISheet.IListeners, options?: IListener.Options): IListener.Remove; /** * Returns the display name for the sheet. */ getName(): string; /** * Set the display name for the sheet. */ setName(name: string): ISheet; /** * Returns the visibility of the sheet. */ getVisibility(): ISheet.Visibility; /** * Change the visibility of the sheet. * * @defaultValue ISheet.Visibility.Visible */ setVisibility(visibility?: ISheet.Visibility | boolean): ISheet; /** * Returns a collection of {@link INamed}s. */ getNames(): INamedCollection; /** * Returns the {@link ICalculation} for the sheet. */ getCalculation(): ICalculation; /** * Returns the {@link IWorkbook} for the sheet. * * @remarks * This may be `null` if not created via a workbook. */ getWorkbook(): IWorkbook | null; /** * Removes from a container. This is usually the `Workbook`. If this is being * used standalone this operation will throw an exception. */ delete(): void; /** * Select the `ISheet`. */ select(options?: ITypes.SelectOptions): Promise; /** * Attempt to scroll the range into view. * * @param coords The partial coords to scroll to. * @param options {@link ISheet.ScrollToOptions}. */ scrollTo(coords: Partial, options: ISheet.ScrollToOptions): Promise; /** * Returns a promise that will resolve to a copy of the current sheet. */ duplicate(): Promise; /** * Reorders the `ISheet` with in the container. This is generally the tab order within an `IWorkbook` but may * be the zIndex if the `ISheets` are movable. This only affects visual listings of the sheets (but selection doesn't change). * * @remarks * This is zero-based. */ setPosition(index: number): ISheet; /** * Returns a JSON representation of the sheet. * * @param ignoreData If `true` only meta data about the sheet will be saved. */ toJSON(ignoreData?: boolean): Promise; /** * Free all resources associated with the sheet. * * @remarks * * Called by workbooks when the workbook is is closed. * * This is different than delete which removes the sheet from the workbook. * * @see * {@link ISheet.addListeners} for closeEvent */ close(): void; /** * Returns true if the sheet has been closed. */ isClosed(): boolean; /** * For runtime type checking. */ readonly isISheet: true; } /** * {@inheritDoc ISheet} * @see * ### **Interface** * * {@link ISheet} * * ### **Implementation** * * {@link Sheet} */ export declare namespace ISheet { /** * The different ways to identify a range within a sheet, * supporting both relative and absolute (fixed) addressing. * * Accepts: * - `ICellRange` * - A parsable `string` representing a range address (e.g., A1 or $A$1 notation). * - A partial `IRange.Coords` object (specifying at least some of the range boundaries), * optionally with a `$fixed` flag to indicate absolute addressing. * - `ICellRange.Address` (representing a single cell within the sheet), * optionally with a `$fixed` flag to indicate absolute addressing. * * @example * ```typescript * const address1: Address = "A1:B2"; // Relative addressing (A1 notation) * const address2: Address = "$A$1:$B$2"; // Absolute addressing (A1 notation) * ``` */ export type RangeAddress = ICellRange | string | Partial | ICell.Address; /** * Represents the different ways to identify multiple ranges within a sheet. * * Accepts: * - `ICellRanges` * - A parsable `string` containing multiple range addresses separated by commas (e.g., "A1:B2,C3:D4"). * - An array of `ICellRange.Address` objects, each representing a single range. * * @example * ```typescript * const address1: ICellRanges.Address = "A1:B2,C3:D4"; // String with multiple ranges. * ``` * @remarks * This extends {@link ICellRange.Address} to support multiple values. */ export type RangesAddress = ICellRanges | string | ICellRange.Address | ICellRange.Address[]; /** * Indicates how a sheet should be available to the user. */ const Visibility: { /** * Visible in all sheet displays. * For example: Tabs, menus, and formulas) */ readonly Visible: "visible"; /** * Not visible in most menus but still available in * user unhide options as well as available to formulas. */ readonly Hidden: "hidden"; /** * Completely hidden to the user but still available via * apis. */ readonly VeryHidden: "veryHidden"; }; export type Visibility = typeof Visibility[keyof typeof Visibility]; /** * Options for scrolling to a specific range. */ export interface ScrollToOptions { /** * The partial coords to scroll to. */ coords?: Partial; /** * Any pixel offsets */ offsets?: Bounds; /** * The scrollTo options. */ scroll?: globalThis.ScrollIntoViewOptions | boolean; } /** * Events for {@link ISheet}. */ export interface Events { /** * Called when the UsedRange bounds changes. * * @remarks * Useful when interested in knowing when the bounds of the area * that is being used within the sheet changes; for example this is used * by the scrollbars to adjust the size. * @see * {@link ISheet.getUsedRange} */ onUsedRangeChange?(source: ISheet): void; /** * Called when the sheet tab color changes. */ onTabColorChange?(source: ISheet): void; /** * Called when any merges are added or removed. */ onMergesChange?(source: ISheet): void; /** * Called if any spills occur. */ onSpillsChange?(source: ISheet): void; /** * Called when any movables are added or removed. */ onMovablesChange?(source: ISheet): void; /** * Called when any table are added or removed. */ onTablesChange?(source: ISheet): void; /** * Convenience method that listens to all changes on the style. */ onStyleChange?(source: ISheet): void; /** * Called when the sizes of the cells change. * * @remarks * * This can be be due to row/column sizes changes or changing the max rows columns. * * Zoom and viewport do not change the underlying layout. */ onLayoutChange?(source: ISheet): void; /** * Called on any protection changes. */ onProtectionChange?(source: ISheet): void; /** * Called before load. If any exception is thrown this * exception will be returned to the client and delete will fail. */ onBeforeLoad?(source: ISheet, json: ISheet.JSON): void; /** * Called after load. */ onLoad?(source: ISheet): void; /** * Called before load. If any exception is thrown this * exception will be returned to the client and delete will be aborted. */ onBeforeSave?(source: ISheet): Promise | void; /** * Called after save. */ onSave?(source: ISheet, json: ISheet.JSON): void; /** * Called before delete. If any exception is thrown the * exception will be returned to the client and delete will be aborted. */ onBeforeDelete?(source: ISheet): void; /** * Request that the sheet become focused. * @returns A promise indicating if the focus was honored. * * @remarks * This should only be handled by one consumer. */ onRequestScrollIntoView?(source: ISheet, options: ISheet.ScrollToOptions): Promise; /** * Request that the sheet become focused. * @returns A promise indicating if the focus was honored. * @remarks * This should only be handled by one consumer. */ onRequestFocus?(source: ISheet): Promise; /** * Called when the sheet is deleted. */ onDelete?(source: ISheet): void; /** * Called when the `ISheetView` changes. * * This is not called when individual properties on the view change. */ onViewChange?(source: ISheet): void; /** * Called when the topLeft changes. * * @remarks * This is a delegated event from the `ISheetView`. */ onTopLeftChange?(source: ISheet): void; /** * Called when the selection changes. * * @remarks * This is a delegated event from the `ISheetView`. */ onSelectionChange?(source: ISheet): void; /** * Called when freeze or split settings have changed. * * @remarks * This is a delegated event from the `ISheetView`. */ onFreezeSplitChange?(source: ISheet): void; /** * Called when the movable selection changes. * * @remarks * This is a delegated event from the `ISheetView`. */ onMovableSelectionChange?(source: ISheet): void; /** * Called when the view changes. */ onViewChange?(source: ISheet): void; /** * Called when the name changes. */ onNameChange?(source: ISheet): void; /** * Called when the visibility changes.. */ onVisibilityChange?(source: ISheet): void; /** * Called when the state has been updated due to a undo/redo and a rerender is required. */ onInvalidated?(source: ISheet): void; /** * Called when the sheet is closed. */ onClose?(source: ISheet): void; } export interface IListeners extends IListener.Callbacks { } /** * Optional values used in the construction of am {@link ISheet}. * * @remarks * Changes to these options will be ignored after construction. */ export interface ConstructorOptions extends ICellContainerOptions { /*** * Set the maxRow size * @defaultValue 1048576 */ maxRows?: number; /*** * Set the maxRow size * @defaultValue 16384 */ maxColumns?: number; /** * When adding to another container. */ container?: ISheet.ContainerOptions; /** * A unique identifier used for identifying this sheet during operations (i.e. copy/paste). * This must be unique for all in-memory instances of a sheet. * * @returns A unique identifier for in memory operations. If not provided a default one will be used. * @remarks * This is not saved as part of the {@link ISheet.JSON} persisted model. */ uid?: () => string; /** * Initial JSON. */ json?: ISheet.JSON; } /** * Options needed for embedding a sheet into another container such as a workbook. */ export interface ContainerOptions { /** * Required to be called before from JSON. * @param self -The Sheet * * @remarks * This is needed to ensure the contain has access to the sheet reference so that * it can resolve references. */ beforeFromJSON?: (self: ISheet) => void; /** * Callback to provide a sheet with a logical name. This is used * when a sheet name property is invoked. * * @remarks * Sheets don't have a name by default but as a convenience we allow * for the name to be called from the sheet. */ getName: () => string | null; setName?: (name: string | null) => void; setNameChangeCallback?: (callback: () => void) => void; /** * Return the current index * @returns */ getIndex: () => number | null; setIndexCallback?: (callback: () => void) => void; /** * Callback to provide a sheet with a visibility. * * @remarks * Sheets don't manage this but as a convenience we allow * for the visibility to be called from the sheet. */ getVisibility?: () => ISheet.Visibility; setVisibility?: (visibility: ISheet.Visibility) => void; setVisibilityCallback?: (callback: () => void) => void; /** * Returns a copy of the sheet provided sheet. */ duplicate?: () => Promise; /** * Request that this moved. * * @param index The index to set to. * * @remarks * For traditional workbooks with not docking tabs this will be the tab position. */ setPosition?: (index: number) => boolean; /** * Request that the sheet become the active sheet. * * @returns A flag indicating that the sheet was brought to the front. * * @remarks * In a workbook context there is only one active sheet at a time but other clients * may treat this this differently. */ requestSelect?: (options?: ITypes.SelectOptions) => Promise; } /** * A set of properties for `ISheet`. */ export interface PropertiesJSON { custom?: Record; calc?: { fullCalcOnLoad?: boolean; }; ignoreErrors?: Record; /** {@inheritDoc IPrint.HeaderFooter} */ headerFooter?: IPrint.HeaderFooter; /** {@inheritDoc IPrint.PageSetup} */ pageSetup?: IPrint.PageSetup; /** {@inheritDoc IPrint.PageSetUpProperties} */ pageSetUpPr?: IPrint.PageSetUpProperties; /** {@inheritDoc IPrint.PrintOptions} */ printOptions?: IPrint.PrintOptions; /** {@inheritDoc IPrint.OutlineProperties} */ outlinePr?: IPrint.OutlineProperties; rowBreaks?: IPrint.Break[]; colBreaks?: IPrint.Break[]; phoneticPr?: { alignment?: string; fontId?: number; type: string; }; } /** * ISheet persistence structure. */ export interface JSON { data?: Tuple.GridTuple; formulas?: [address: string, text: string][]; /** * Indicates a range was created via a dynamic array formula. * This is a specific type of dynamic. */ dynamicArray?: [address: string, error: boolean][]; volatile?: string[]; cols?: ICellHeader.JSON[]; defaultColSize?: number; outlineLevelCol?: number; rows?: ICellHeader.JSON[]; defaultRowSize?: number; outlineLevelRow?: number; styles?: IStyleCollection.JSON; resources?: IResource.JSON[]; strings?: string[]; people?: IComment.PersonJSON[]; comments?: IComment.JSON[]; hyperlinks?: { r: ICellRange.RefJSON; v: IHyperlink.JSON; }[]; /** * A generalize solution for dynamic areas. * This is used for externalData * "C5:G10": { "type": "externalData", "error": false, // Or true if the last refresh failed "source": "Query1", // Example: Type-specific info "overrides": { // Object storing user edits within the region "D6": "Manual Edit", // Key = Cell Address within region "F8": 123.45 // Value = User-entered value } } */ dynamic?: { r: ICellRange.RefJSON; v: IRichData.JSON; }[]; /** * Either an object with RangeAddress to style id or an array of RangeCoordValue to style id. */ directStyles?: { r: ICellRange.RefJSON; v: number; }[]; merges?: string[]; tables?: ITable.JSON[]; movables?: IMovable.JSON[]; conditionals?: IConditionalFormat.JSON[]; filter?: IAutoFilter.JSON; sort?: IAutoSort.JSON; tabColor?: string; protection?: ISheetProtection.JSON; view?: ISheetView.JSON; } } /** * Holds a collection of {@link ISheet}s. */ export declare interface ISheetCollection extends ICollection { /** * Add an `ISheet` to the collection. */ add(options?: ISheetCollection.AddOptions | string | number): ISheet; /** * Returns sheets that match the filter criteria. * * If no filter criteria is provided, all sheets will be returned. * * @param options {@link ISheetCollection.GetItemsOptions} */ getItems(options?: ISheetCollection.GetItemsOptions): ISheet[]; /** * Returns the sheet at the given index. * @param index * @returns */ /** * Convenience method for filtering by name. This is * functionally equivalent to getItems({ name }); * * @param name The name to search for This is case insensitive. */ getByName(name: string): ISheet | null; } /** * {@inheritDoc ISheetCollection} * @see * ### **Interface** * * {@link ISheetCollection} */ export declare namespace ISheetCollection { /** * Options for adding a sheet to the collection. */ export interface AddOptions extends ITransaction.OperationOptions { /** * The name of the sheet. * * @defaultValue - A unique name as determined by {@link IWorkbook.ConstructorOptions.createSheetNameCallback}. */ name?: string; /** * Position for the sheet. * @defaultValue - After the currently active sheet. */ index?: number; } export interface GetItemsOptions extends ICollection.GetItemsOptions { /** * Indicate if items that are in hidden headers or marked as hidden should be returned. * @defaultValue false */ visibility?: ISheet.Visibility; /** * Search with the given name. This is case insensitive. */ name?: string; } } /** * Provides a programmatic interface for interacting with and modifying entire rows or columns in a spreadsheet, * allowing for actions such as inserting, deleting, resizing, and applying formatting changes. */ export declare interface ISheetHeader extends ITransaction.ITransactional, IListener.ISource { /** * Returns the header at a given offset. Will only return null for invalid header offset. To get a list of headers use {@link getRange}. * * @param index 0-based absolute index. */ at(index: number): ICellHeader; /** * Returns a displayable title for the given index. * @param index 0-based absolute index. */ getTextAt(index: number): string; /** * Returns a range of cells for the specified range. * * @param address The address or addresses of the header range to retrieve. * @param options Options for retrieving the header ranges. * @see * {@link ICellHeaderRange} */ getRange(address: ICellHeaderRange.Address, options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange; /** * Returns a collection of header ranges for the specified ranges. * * @param address The address or addresses of the header ranges to retrieve. * @param options Options for retrieving the header ranges. */ getRanges(address: ICellHeaderRanges.Address, options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges; /** * Returns the active header range that is used in the selection. */ getSelectedRange(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange; /** * Returns the active header ranges that are used in the selection. */ getSelectedRanges(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges; /** * Returns the data ranges for headers that contain information. * * @remarks * * This is NOT the last cell that may have data or has been resized. * * This also has nothing to do with the selection bounds. * @see * {@link ICellRange.getUsedRange} */ getUsedRange(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange; /** * The entire range for the header. */ getEntireRange(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange; /** * The orientation the headers manage. */ getOrientation(): IRange.Orientation; /** * Returns a flag indicating if the headers are protected by the sheet. */ isProtected(): boolean; /** * All header sizes are returned in pixels. This is done * by multiplying the scaleFactor by the size on the cellHeader. */ getScaleFactor(): number; /** * Finds the offset in pixels for the given header index * @param index 0-based absolute index. */ findOffset(index: number): number; /** * Finds the index for the given header offset in pixels. * @param offset 0-based pixels. */ findIndex(offset: number): number; /** * Finds the visibleIndex for a given absolute index. * * If it's hidden it will return a range of 1 with a value before the offset and after. * * If it's visible then it will return a range of 0 with the min and max that exactly match the offset. * * @param index 0-based absolute index. * @returns A {@link RunCoords} that can be used to determine if an index is hidden. * @remarks * If this is on the edge of the bounds this will return a +/- 1 the max bounds. */ findVisibleIndex(index: number): Readonly; /** * Returns the number of indices visible. Between to indices. * @param indexFrom * @param indexTo */ getVisibleCount(indexFrom: number, indexTo: number): number; /** * Returns the size of the header in pixels. If a second argument is passed it * will be the size of all the headers within the range. * Note - It is expected that indexFrom will always be less than or equal to indexTo */ getSpanSize(indexFrom: number, indexTo?: number): number; /** * The default header size if not adjusted. */ getDefaultSize(): number; /** * The maximum size of the header in native units. */ getMaxSize(): number; /** * The minimum size of the header in native units. */ getMinSize(): number; /** * This is a very specific optimization function. When * hiding many headers instead of scanning we can just skip. * If `0` is returned then there are no hidden headers immediately * following this one. If `1` is returned then only this header is hidden. * * @param index The location to start the search. * @param reverse Indicates if search should scan in reverse. defaults to `false`. * @returns The number of headers following the index. */ hiddenHeadersAt(index: number, reverse?: boolean): number; /** * Returns true if any of the headers have the isHidden flag set to true or if any sizes are 0. */ hasHidden(): boolean; /** * Returns true if header has a max selection at the given index. */ isSelectedAll(index: number): boolean; /** * Returns true if header has a selection at the given index. */ isSelected(index: number): boolean; /** * Returns a list of SelectedRuns. */ getSelectedRuns(): readonly ITypes.RunCoordValue[]; /** * Sets the headers. This supports setting values as a batch. * * @remarks * When setting headers the cells references by this sheet will not update. * To ensure they are updated on the sheet call updateHeaderPairs with the range from the header. */ updateHeaderPairs(pairs: ICellHeaderRange.AddressUpdatePair[], options?: ICellHeaderRange.UpdateHeadersOptions): RunCoords[] | null; /** * Returns the sheet model used for the header. */ getSheet(): ISheet; /** * Save the header state to a JSON object. */ toJSON(): ISheetHeader.JSON; /** * Load the {@link ISheetHeader.JSON} state into the header. The current state will be lost. * @deprecated - Should be added to constructor. */ fromJSON(json: ISheetHeader.JSON): void; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: ISheetHeader.IListeners, options?: IListener.Options): IListener.Remove; close(): void; } /** * {@inheritDoc ISheetHeader} * @see * ### **Interface** * * {@link ISheetHeader} */ export declare namespace ISheetHeader { /** * Run of headers with min/max embedded. (This prevents rows/columns from having min/max fields but makes persisted json a bit cleaner) */ export interface JSON { headers: ICellHeader.JSON[]; defaultSize?: number; } export interface SelectedRun { isSelectedAll: boolean; } export interface Events { /** * Called when sizes of the headers have changed. */ onSizesChange?(source: ISheetHeader): void; } export interface IListeners extends IListener.Callbacks { } } /** * Interface representing the protection settings for a sheet. * Extends the base `IProtection` interface with additional sheet-specific protection options. */ export declare interface ISheetProtection extends IProtection { /** * Retrieves the protection properties for the sheet. * * @returns The {@link ISheetProtection.Properties} object representing the current protection settings. */ getProperties(): ISheetProtection.Properties; /** * Checks if the AutoFilter functionality is protected on the sheet. * * @returns `true` if AutoFilter is locked, `false` otherwise. */ isAutoFilterAllowed(): boolean; /** * Checks if deleting columns is protected on the sheet. * * @returns `true` if deleting columns is locked, `false` otherwise. */ isDeleteColumnsAllowed(): boolean; /** * Checks if deleting rows is protected on the sheet. * * @returns `true` if deleting rows is locked, `false` otherwise. */ isDeleteRowsAllowed(): boolean; /** * Checks if formatting cells is protected on the sheet. * * @returns `true` if formatting cells is locked, `false` otherwise. */ isFormatCellsAllowed(): boolean; /** * Checks if formatting columns is protected on the sheet. * * @returns `true` if formatting columns is locked, `false` otherwise. */ isFormatColumnsAllowed(): boolean; /** * Checks if formatting rows is protected on the sheet. * * @returns `true` if formatting rows is locked, `false` otherwise. */ isFormatRowsAllowed(): boolean; /** * Checks if inserting columns is protected on the sheet. * * @returns `true` if inserting columns is locked, `false` otherwise. */ isInsertColumnsAllowed(): boolean; /** * Checks if inserting hyperlinks is protected on the sheet. * * @returns `true` if inserting hyperlinks is locked, `false` otherwise. */ isInsertHyperlinksAllowed(): boolean; /** * Checks if inserting rows is protected on the sheet. * * @returns `true` if inserting rows is locked, `false` otherwise. */ isInsertRowsAllowed(): boolean; /** * Checks if objects (e.g., charts, shapes) are protected on the sheet. * * @returns `true` if objects are locked, `false` otherwise. */ isObjectsAllowed(): boolean; /** * Checks if pivot tables are protected on the sheet. * * @returns `true` if pivot tables are locked, `false` otherwise. */ isPivotTablesAllowed(): boolean; /** * Checks if scenarios are protected on the sheet. * * @returns `true` if scenarios are locked, `false` otherwise. */ isScenariosAllowed(): boolean; /** * Checks if sorting is protected on the sheet. * * @returns `true` if sorting is locked, `false` otherwise. */ isSortAllowed(): boolean; /** * Checks if selecting locked cells is protected on the sheet. * * @returns `true` if selecting locked cells is locked, `false` otherwise. */ isSelectLockedCellsAllowed(): boolean; /** * Checks if selecting unlocked cells is protected on the sheet. * * @returns `true` if selecting unlocked cells is locked, `false` otherwise. */ isSelectUnlockedCellsAllowed(): boolean; } /** * {@inheritDoc ISheetProtection} * @see * ### **Interface** * * {@link ISheetProtection} */ export declare namespace ISheetProtection { export interface Properties extends IProtection.Properties { /** {@inheritDoc ISheetProtection.isAutoFilterAllowed} */ autoFilter?: boolean; /** {@inheritDoc ISheetProtection.isDeleteColumnsAllowed} */ deleteColumns?: boolean; /** {@inheritDoc ISheetProtection.isDeleteRowsAllowed} */ deleteRows?: boolean; /** {@inheritDoc ISheetProtection.isFormatCellsAllowed} */ formatCells?: boolean; /** {@inheritDoc ISheetProtection.isFormatColumnsAllowed} */ formatColumns?: boolean; /** {@inheritDoc ISheetProtection.isFormatRowsAllowed} */ formatRows?: boolean; /** {@inheritDoc ISheetProtection.isInsertColumnsAllowed} */ insertColumns?: boolean; /** {@inheritDoc ISheetProtection.isInsertHyperlinksAllowed} */ insertHyperlinks?: boolean; /** {@inheritDoc ISheetProtection.isInsertRowsAllowed} */ insertRows?: boolean; /** {@inheritDoc ISheetProtection.isObjectsAllowed} */ objects?: boolean; /** {@inheritDoc ISheetProtection.isPivotTablesAllowed} */ pivotTables?: boolean; /** {@inheritDoc ISheetProtection.isScenariosAllowed} */ scenarios?: boolean; /** {@inheritDoc ISheetProtection.isSelectLockedCellsAllowed} */ selectLockedCells?: boolean; /** {@inheritDoc ISheetProtection.isSelectUnlockedCellsAllowed} */ selectUnlockedCells?: boolean; /** {@inheritDoc ISheetProtection.isSortAllowed} */ sort?: boolean; sheet?: boolean; } export interface JSON extends ISheetProtection.Properties, IProtection.JSON { } export type PropertyKeys = (keyof ISheetProtection.Properties); } /** * The `ISheetView` provides properties and methods for controlling how a sheet is displayed and interacted with, * without affecting the underlying data itself. * * View settings include aspects like frozen panes, zoom level, selection, gridlines visibility, and whether formulas are displayed. * but do not affect the underlying data itself. * * @remarks * * Since views only affect the presentation of the data, changes to view settings are typically not included in the undo/redo stack. * * Multiple views can be associated to the same collection of data, each providing a different way of viewing and interacting. */ export declare interface ISheetView extends IMovableSelection, IListener.ISource { /** * The default top left corner accounting for scrolling. */ setTopLeft(topLeft: Partial | null): this; /** * @see {@link setTopLeft} */ getTopLeft(): Partial; /** * The freeze panes. */ setFreezePanes(freezePanes: ISheetView.FreezePanes): this; /** * @see {@link setFreezePanes} */ getFreezePanes(): ISheetView.FreezePanes; /** * Show/Hide row headers. * @defaultValue true; */ setShowRowHeaders(showRowHeaders: boolean): this; /** * @see {@link setShowRowHeaders} */ isShowRowHeaders(): boolean; /** * Show/Hide columns headers. * @defaultValue true; */ setShowColumnHeaders(showColumnHeaders: boolean): this; /** * @see {@link setShowColumnHeaders} */ isShowColumnHeaders(): boolean; /** * Show/Hide row gridlines. * @defaultValue true; */ setShowRowGridlines(showRowGridlines: boolean): this; /** * @see {@link setShowRowGridlines} */ isShowRowGridlines(): boolean; /** * Show/Hide column gridlines. * @defaultValue true; */ setShowColumnGridlines(showColumnGridlines: boolean): this; /** * @see {@link setShowColumnGridlines} */ isShowColumnGridlines(): boolean; /** * Style of displaying default row header text * Note - This does not affect how formulas are resolved * * @defaultValue HeaderTextStyle.A1 * // TODO - allow a function callback (but this won't be persisted) */ setRowHeaderStyle(rowHeaderStyle: ISheetView.HeaderTextStyle): this; /** * @see {@link setRowHeaderStyle} */ getRowHeaderStyle(): ISheetView.HeaderTextStyle; /** * Style of displaying default row header column * Note - This does not affect how formulas are resolved * * @defaultValue HeaderTextStyle.One * // TODO - allow a function callback (but this won't be persisted) */ setColumnHeaderStyle(columnHeaderStyle: ISheetView.HeaderTextStyle): this; /** * @see {@link setColumnHeaderStyle} */ getColumnHeaderStyle(): ISheetView.HeaderTextStyle; /** * Zoom. This is expressed as a percentage. Values can be between 10 (10%) or 400 (400%). * * @defaultValue 100 * // TODO - support zoomScaleNormal, zoomScalePageLayout, zoomScaleSheetLayoutView, */ setZoomScale(zoomScale: number): this; /** * @see {@link setZoomScale} */ getZoomScale(): number; /** * Indicate if view is showing formulas or values * * @defaultValue false */ setShowFormulas(showFormulas: boolean): this; /** * @see {@link setShowFormulas} */ isShowFormulas(): boolean; /** * Indicate whether the sheet should show 0 (zero) or blanks in cells containing zero values. * * @defaultValue true * * @remarks * When false, cells with zero value appear blank instead of showing the number zero. */ setShowZeros(showZeros: boolean): this; /** * @see {@link setShowZeros} */ isShowZeros(): boolean; /** * The color of the gridline on the sheet. * * @defaultValue null (adopts the app theme color) * * @remarks * GridLine color is a sheet view attribute but in Excel is a workbook attribute. * If null then use the app theme. */ setGridLineColor(gridLineColor: any): this; /** * @see {@link setGridLineColor} */ getGridLineColor(): any; /** * The current selection for the view. * * @remarks * This is generally not set directly but through the selection object. */ setRangeSelection(selection: IRangeSelection.Coords): this; /** * @see {@link setRangeSelection} */ getRangeSelection(): IRangeSelection.Coords; /** * Add a movable to the selection. * If addToSelection is true then the items will be added to the selection. * * @param movables The movables to select. * @param addToSelection */ selectMovables(movables: readonly IMovable[], addToSelection?: boolean): this; /** * Removes the movables from selection (if they were selected) * @param movables */ unselectMovables(movables: readonly IMovable[]): this; /** * Allow for a bulk update of the view properties. * * @param properties */ update(properties: ISheetView.Properties): this; /** * Set the view to initial values. * @param notify */ clear(notify?: boolean): this; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: ISheetView.IListeners, options?: IListener.Options): IListener.Remove; /** * Persist to JSON. * * @remarks * Returns null if it has no customized values. */ toJSON(): ISheetView.JSON | null; /** * For runtime type checking. */ readonly isISheetView: true; } /** * {@inheritDoc ISheetView} * @see * ### **Interface** * * {@link ISheetView} */ export declare namespace ISheetView { /** * The coordinates for a FreezePane. * * Can have either a coordinate or a topLeft or both. */ export interface FreezePanes { /** * At least one direction must be set. */ coords?: Partial; /** * If scrolling then this will be set. * @remarks * If the current view has a scroll offset and * freeze is called it will 'transfer' the scroll coordinates. */ topLeft?: Partial; } /** * A listener for changes to the ISheetView object. */ export interface Events extends IMovableSelection.Events { /** * Called when the sheetView changes. */ onTopLeftChange?(source: ISheetView): void; /** * Called when freeze or split settings have changed */ onFreezeSplitChange?(source: ISheetView): void; /** * Called when the selection changes. */ onRangeSelectionChange?(source: ISheetView): void; /** * Called when the movable selection changes. */ onMovableSelectionChange?(source: ISheetView): void; /** * Called when the movable selection changes. */ onAnyChange?(source: ISheetView): void; } export interface IListeners extends IListener.Callbacks { } /** * A set of values that can be set on a ISheetView. * * @see * {@link ISheetView} */ export interface Properties { /** The selection coords. */ selection?: IRangeSelection.Coords; /** {@inheritDoc ISheetView.setTopLeft} */ topLeft?: Partial; /** {@inheritDoc ISheetView.setFreezePanes} */ freezePanes?: ISheetView.FreezePanes; /** {@inheritDoc ISheetView.setShowRowHeaders} */ showRowHeaders?: boolean; /** {@inheritDoc ISheetView.setShowColumnHeaders} */ showColumnHeaders?: boolean; /** {@inheritDoc ISheetView.setShowRowGridlines} */ showRowGridlines?: boolean; /** {@inheritDoc ISheetView.setShowColumnGridlines} */ showColumnGridlines?: boolean; /** {@inheritDoc ISheetView.setRowHeaderStyle} */ rowHeaderStyle?: ISheetView.HeaderTextStyle; /** {@inheritDoc ISheetView.setColumnHeaderStyle} */ columnHeaderStyle?: ISheetView.HeaderTextStyle; /** {@inheritDoc ISheetView.setZoomScale} */ zoomScale?: number; /** {@inheritDoc ISheetView.setShowFormulas} */ showFormulas?: boolean; /** {@inheritDoc ISheetView.setShowZeros} */ showZeros?: boolean; /** {@inheritDoc ISheetView.setGridLineColor} */ gridLineColor?: string | IColor; } export interface ConstructorOptions { /** * Sheets need to be associated with a sheet. */ sheet: ISheet; /** * The state to load. */ json?: ISheetView.JSON; } /** * A JSON representation useful for persistence. */ export interface JSON extends Omit { selection?: IRangeSelection.Coords; topLeft?: string | Partial; freezePanes?: string | FreezePanes; zoomScale?: string | number; } /** * The default style for displaying the header text. * * @remarks * This is a suggestion and may be ignored by the HeaderRenderer. */ const HeaderTextStyle: { readonly A1: "a1"; readonly Zero: "zero"; readonly One: "one"; }; export type HeaderTextStyle = typeof HeaderTextStyle[keyof typeof HeaderTextStyle]; } /** * Types used for sorting. */ export declare namespace ISort { /** * Default collators for sorting. */ const SortOn: { readonly Value: "value"; readonly FillColor: "fillColor"; readonly FontColor: "fontColor"; readonly Icon: "icon"; }; export type SortOn = typeof SortOn[keyof typeof SortOn]; /** * A collator for a Scalar of a specific type. * * @remarks * Sorting supports sorting across multiple data types. Each collator * will have a type. */ export interface Collator { /** * The `ScalarType` that this collator can understand or a 'string' that represent the * type for `ScalarType.RichData; */ type: ScalarType | string; /** * Used for sorting. Equal values and `null` values are presorted and * do not need to be handled in the collator implementation. * * @param options `defaultOptions` with any user overrides. * * @remarks * * Options defined in defaultOptions with any user overrides are passed as the options. */ compare: (a: Scalar, b: Scalar, options?: Intl.CollatorOptions) => number; /** * The options passed to the collator. */ defaultOptions?: Intl.CollatorOptions; } export interface Criteria { /** * Determines whether to reverse the default sort order. * * @defaultValue false - (sorts in the default order, typically ascending) * * @remarks * The `reverse` flag flips the sort order. When set to `true`, the sort will * be performed in reverse order compared to the default (which is usually ascending). * * This flag is data-type agnostic, meaning it will reverse the default order * regardless of whether the data is numeric, alphabetic, or complex (e.g., booleans, lists). * * Example usage: * ```ts * const options: ISort.Options = { * reverse: true, // Sorts in descending order (for numbers/alphabetic) * }; * ``` */ reverse?: boolean; /** * Additional options for sorting. * * @remarks * * Excel has a matchCase flag but we use Intl.CollatorOptions * * Excel has Normal | 'TextAsNumber' but we use Intl.CollatorOptions */ collatorOptions?: Record | Intl.CollatorOptions; /** * Only value is currently supported */ sortOn?: SortOn; /** * Used with sortOn === Icon * @remarks * **PLACEHOLDER** - This is a placeholder for future use. */ iconSet?: IStyle.IconSet; /** * Used with sortOn === Icon * @remarks * **PLACEHOLDER** - This is a placeholder for future use. */ iconId?: number; /** * Used with sortOn === cellColor or fontColor * * @remarks * **PLACEHOLDER** - This is a placeholder for future use. */ dxfId?: any; /** * Sort by a custom list. * @remarks * **PLACEHOLDER** - This is a placeholder for future use. */ customList?: string; } export interface Field extends Criteria { /** * 0-based offset for the header based on orientation * * @defaultValue The first index of the selected range */ offset: number; } /** * Options for sorting with a filter. * * @remarks * This is very similar to a range sort but with a few less options. */ export interface Options extends ISort.Criteria { /** * Allows you to override individual sorts for each additional level. * All sort criteria default to the sort criteria specified on the sort option. */ fields?: (number | ISort.Field)[]; /** * 0-based offset for the header based on orientation * * @defaultValue The first index of the selected range */ offset?: number; } /** * Shows a list of options that will be used for the current sort unless overridden. */ export interface DefaultSortCriteria { /** * The cords that will be sorted. * This will include headers even if the are ignored. */ coords: IRange.Coords; /** * Options to pass to sort. */ options: ISort.RangeOptions; /** * If headers The map will contain the offset as a key by the value as string. * * @remarks * If no headers are found this will be empty. */ headers: Map; /** * The coords without any headers. */ sortCoords: IRange.Coords; } /** * Extends sort options to include options for sorting a range. * * @remarks * This include orientation, hasHeader, and includeHidden. */ export interface RangeOptions extends ISort.Options { /** * Indicate the orientation to sort. * * @defaultValue ICellRange.Orientation.Row */ orientation?: IRange.Orientation; /** * Indicate if the sort has a header. If the sort has a head this will be ignored. * * @defaultValue Use data to make a 'guess' */ hasHeader?: boolean; /** * Determine if sort should include values that are hidden. * * @defaultValue false */ includeHidden?: boolean; /** * Override the collators used. * * @defaultValue Sort.DefaultCollators */ collators?: readonly ISort.Collator[]; } } /** * An interface for a sorted map (dictionary), not including functional/persistent methods. */ declare interface ISortedMap extends IMap, ISortedMapSource { /** * Adds or overwrites a key-value pair in the collection. * @param key the key is used to determine the sort order of data in the tree. * @param value data to associate with the key * @param overwrite Whether to overwrite an existing key-value pair * (default: true). If this is false and there is an existing * key-value pair then the call to this method has no effect. * @returns `true` if a new key-value pair was added, false if the key * already existed. */ set(key: K, value: V, overwrite?: boolean | ISortedMap.SetPairCallback): boolean; /** * Adds all pairs from a list of key-value pairs. * @param pairs Pairs to add to this tree. If there are duplicate keys, * later pairs currently overwrite earlier ones (e.g. [[0,1],[0,7]] * associates 0 with 7.) * @param overwrite Whether to overwrite pairs that already exist (if false, * pairs[i] is ignored when the key pairs[i][0] already exists.) * @returns The number of pairs added to the collection. */ setPairs(pairs: [K, V][], overwrite?: boolean | ISortedMap.SetPairCallback): number; /** * Deletes a series of keys from the collection. */ deleteKeys(keys: K[]): number; /** * Removes a range of key-value pairs from the collection. * @param low The first key deleted will be greater than or equal to `low`. * @param high Deleting stops when a key larger than this is reached. * @param includeHigh Specifies whether the `high` key, if present, is deleted. * @returns The number of key-value pairs that were deleted. */ deleteRange(low: K, high: K, includeHigh: boolean): number; entries(firstKey?: K): IterableIterator<[K, V]>; keys(firstKey?: K): IterableIterator; values(firstKey?: K): IterableIterator; } /** * {@inheritDoc ISortedMap} * @see * ### **Interface** * * {@link ISortedMap} */ declare namespace ISortedMap { /** * A return type that allows for either a value or a break or a delete flag. */ type EditRangeResult = { value?: V; break?: B; delete?: boolean; }; /** * Called when a tree node is SetPairCallback. * * * If the prev value is undefined then this is a new * * If the function returns a void this the value is unchanged. */ type EditRangeCallback = (k: K, v: V, counter: number) => EditRangeResult | void; /** * Called when a tree node is SetPairCallback. * @remarks * SetPairs is different that EditRange in that it is an insert only operation. * * If the prev value is undefined then this is a new * * If the function returns a void then the value is unchanged. */ type SetPairCallback = (prev: V | undefined, key: K, value: V) => V | void; } declare interface ISortedMapF extends ISortedSetF, IMapF, ISortedMapSource { /** Returns a copy of the tree with the specified range of keys removed. */ withoutRange(low: K, high: K, includeHigh: boolean, returnThisIfUnchanged?: boolean): ISortedMapF; entries(firstKey?: K): IterableIterator<[K, V]>; keys(firstKey?: K): IterableIterator; values(firstKey?: K): IterableIterator; forRange(low: K, high: K, includeHigh: boolean, onFound?: (k: K, v: V, counter: number) => void, initialCounter?: number): number; with(key: K): ISortedMapF; with(key: K, value: V2, overwrite?: boolean): ISortedMapF; withKeys(keys: K[], returnThisIfUnchanged?: boolean): ISortedMapF; withPairs(pairs: [K, V | V2][], overwrite: boolean): ISortedMapF; mapValues(callback: (v: V, k: K, counter: number) => R): ISortedMapF; without(key: K): ISortedMapF; withoutKeys(keys: K[], returnThisIfUnchanged?: boolean): ISortedMapF; filter(callback: (k: K, v: V, counter: number) => boolean, returnThisIfUnchanged?: boolean): ISortedMapF; } /** * An data source that provides read-only access to items in sorted order. */ declare interface ISortedMapSource extends IMapSource, ISortedSetSource { /** * Returns the next pair whose key is larger than the specified key (or undefined * if there is none). If key === undefined, this function returns the lowest pair. */ nextHigherPair(key?: K, reusedPair?: [K, V]): [K, V] | undefined; /** * Returns the next pair whose key is smaller than the specified key (or undefined * if there is none). If key === undefined, this function returns the highest pair. */ nextLowerPair(key?: K, reusedPair?: [K, V]): [K, V] | undefined; /** * Builds an array of pairs from the specified range of keys, sorted by key. * Each returned pair is also an array: pair[0] is the key, pair[1] is the value. * @param low The first key in the array will be greater than or equal to `low`. * @param high This method returns when a key larger than this is reached. * @param includeHigh If the `high` key is present in the map, its pair will be * included in the output if and only if this parameter is true. Note: * if the `low` key is present, it is always included in the output. * @param maxLength Maximum length of the returned array (default: unlimited) * @description Computational complexity: O(result.length + log size) */ getRange(low: K, high: K, includeHigh?: boolean, maxLength?: number): [K, V][]; /** Calls `callback` on the specified range of keys, in ascending order by key. * @param low The first key scanned will be greater than or equal to `low`. * @param high Scanning stops when a key larger than this is reached. * @param includeHigh If the `high` key is present in the map, `onFound` is called * for that final pair if and only if this parameter is true. * @param onFound A function that is called for each key-value pair. * @param initialCounter Initial third argument of onFound. This value * increases by one each time `onFound` is called. Default: 0 * @returns Number of pairs found and the number of times `callback` was called. */ forRange(low: K, high: K, includeHigh: boolean, onFound?: (k: K, v: V, counter: number) => void, initialCounter?: number): number; /** * Returns an iterator that provides items in order by key. * @param firstKey Minimum key to include in the output. */ entries(firstKey?: K, reusedPair?: [K, V]): IterableIterator<[K, V]>; /** * Returns a new iterator for iterating the keys of each pair in ascending order. * @param firstKey Minimum key to include in the output. */ keys(firstKey?: K, reusedPair?: [K, V]): IterableIterator; /** * Returns a new iterator for iterating the values of each pair in order by key. * @param firstKey Minimum key whose associated value is included in the output. */ values(firstKey?: K, reusedPair?: [K, V]): IterableIterator; /** Performs a reduce operation like the `reduce` method of `Array`. * It is used to combine all pairs into a single value, or perform conversions. */ reduce(callback: (previous: R, currentPair: [K, V], counter: number, tree: IMapF) => R, initialValue: R): R; /** Performs a reduce operation like the `reduce` method of `Array`. * It is used to combine all pairs into a single value, or perform conversions. */ reduce(callback: (previous: R | undefined, currentPair: [K, V], counter: number, tree: IMapF) => R): R | undefined; } /** * An interface for a functional sorted set: a functional set in which the * keys (items) are sorted. This is a subinterface of ISortedMapF. */ declare interface ISortedSetF extends ISetF, ISortedSetSource { keys(firstKey?: K): IterableIterator; } /** * An data source that provides read-only access to a set of items called * "keys" in sorted order. This is a subinterface of ISortedMapSource. */ declare interface ISortedSetSource extends ISetSource { /** Gets the lowest key in the collection. */ minKey(): K | undefined; /** Gets the highest key in the collection. */ maxKey(): K | undefined; /** * Returns the next key larger than the specified key (or undefined if there is none). * Also, nextHigherKey(undefined) returns the lowest key. */ nextHigherKey(key?: K): K | undefined; /** * Returns the next key smaller than the specified key (or undefined if there is none). * Also, nextLowerKey(undefined) returns the highest key. */ nextLowerKey(key?: K): K | undefined; /** * Calls `callback` on the specified range of keys, in ascending order by key. * @param low The first key scanned will be greater than or equal to `low`. * @param high Scanning stops when a key larger than this is reached. * @param includeHigh If the `high` key is present in the map, `onFound` is called * for that final pair if and only if this parameter is true. * @param onFound A function that is called for each key pair. Because this * is a subinterface of ISortedMapSource, if there is a value * associated with the key, it is passed as the second parameter. * @param initialCounter Initial third argument of `onFound`. This value * increases by one each time `onFound` is called. Default: 0 * @returns Number of pairs found and the number of times `onFound` was called. */ forRange(low: K, high: K, includeHigh: boolean, onFound?: (k: K, v: any, counter: number) => void, initialCounter?: number): number; /** * Returns a new iterator for iterating the keys of each pair in ascending order. * @param firstKey -Minimum key to include in the output. */ keys(firstKey?: K): IterableIterator; } /** * Extends {@link IGrid} with specialized functionality for sparse grids. */ declare interface ISparseGrid extends IGrid { /** * Returns An iterator for iterating the runs. * * @remarks * Sparse grids are stored as virtual tuples of [major, minor, value]. */ getRuns(options?: ISparseGrid.RunIteratorOptions): ISparseGrid.RunIterableIterator; } /** * {@inheritDoc ISparseGrid} * @see * ### **Interface** * * {@link ISparseGrid} */ declare namespace ISparseGrid { type RunEntry = [number, number, IListLike]; /** * Shorthand type. */ type RunIterableIterator = IterableIterator>; /** * Shorthand type. */ type RunIteratorResult = IteratorResult>; /** * Run Iterator extends {@link IReadableList.IteratorOptions} but removes support for * processSkip and downcasts reuseResult. */ interface RunIteratorOptions { /** * If not specified or `null` then all values will be iterated. * * @defaultValue unspecified * * @remarks * The min and max are always small to largest regardless of reverse flag. */ bounds?: Partial; /** * If `true` will return the full range even if it is outside of the iteration bounds. * * @defaultValue `false` * * @remarks * This is used as a performance optimization for iterators that are reading gaps. (fillEmpty) */ overflowRun?: boolean; } } /** * Data structure that allows for querying 2d rectangles. */ declare interface ISpatialMap { /** * Returns all items within the search range. * * @param range The range to search * @param fullyContained Only search for ranges that are completely contained with the search range. DefaultValue `false`. */ search(range: Readonly, fullyContained?: boolean, results?: ISpatialMap.Entry[]): ISpatialMap.Entry[]; /** * Returns `true` if there are any items within the range. * * @param range The range to search */ has(range: Readonly): boolean; /** * Returns the smallest range that includes all ranges. */ getBoundingCoords(): RangeCoords; /** * A quick search for all. */ size(): number; /** * Just like `size === 0` but even quicker. */ isEmpty(): boolean; /** * Just like `search(getBoundingCoords())` but slightly faster. */ all(results?: ISpatialMap.Entry[]): ISpatialMap.Entry[]; /** * Visit all items within a range. * * @param range The range to visit. * @param visitor The visitor function to call for each item. * @param sort If provided, the ranges will be sorted in either row or column order. Default value is no sort. */ visitRanges(range: Readonly, visitor: ISpatialMap.Visitor, sort?: Direction): void; /** * Insert a an entry. * * @param entry The item to insert * @remarks * * This does not prevent duplicates. A remove is required. * * */ insert(entry: ISpatialMap.Entry): this; /** * Inserts a item but splits and merges all intersections to ensure no overlaps. * * @param entry The entry to add. * @param options Options for adding non overlapping options. * * @remarks * * This is much slower than a regular load so if the ranges are known to be non-overlapping * then the `load` method should be used. */ insertNonOverlapping(entry: ISpatialMap.Entry, options?: ISpatialMap.InsertNonOverlappingOptions): this; /** * TODO - doc this. * * @param entries the entries to manage together * @param uuid A unique identifier for the group. */ insertGroup(entries: ISpatialMap.Entry[], uuid: string): this; /** * Returns a set of non overlapping inserts and removes that would represent a copy. * * @param from The range to copy from. * @param to The range to copy to * * @remarks * This doesn't actually make the copy but returns the entries that would reflect a copy. */ createCopiedEntries(from: RangeCoords, to: RangeCoords, options?: ISpatialMap.CopyOptions, reuseInsert?: ISpatialMap.Entry[], reuseRemove?: ISpatialMap.Entry[]): ISpatialMap.Updates; /** * Optimized bulk insert. This should be used when possible. * @param entries A readonly list of RangeCoordValues */ load(entries: ReadonlyArray): this; /** * Shifts all ranges in a given direction. * * @param options The options for the shift. */ shift(options: ISpatialMap.ShiftOptions): this; /** * Remove item. * * @param entry The item to remove. * @param equals A custom equal check to determine if the item should be returned. */ remove(entry: ISpatialMap.Entry, equals?: (a: ISpatialMap.Entry, b: ISpatialMap.Entry) => boolean): this; /** * Clear the tree. */ clear(): this; /** * Returns a copy on write clone. * * @param cloneKey A performance optimization that will avoid cloning if the same key is used. * * @remarks * If the same clone key is used then the same instance will be returned. */ clone(cloneKey?: any): this; } /** * {@inheritDoc ISpatialMap} * @see * ### **Interface** * * {@link ISpatialMap} */ declare namespace ISpatialMap { /** * A visitor function that is called for each item in a range. */ type Visitor = (entry: ISpatialMap.Entry) => ISpatialMap.VisitorResults; /** * Allows for the visitor to update the results. */ type VisitorResults = { update?: ISpatialMap.Entry; delete?: boolean; break?: boolean; } | void; interface Entry extends RangeCoords { value?: T; uuid?: string; /** * If the entry is the results of a split or a merge. */ lastId?: string; } interface IUpdatableEntry { /** * Splits the range into multiple sub-ranges based on specified coordinates and orientation. * * @param destination The destination coordinates for the split. * @param orientation The orientation (horizontal/vertical) of the split. * @returns An array of the split ranges. * @throws Will throw an error if the split cannot be performed. * * @remarks * This method allows for dividing the range into smaller segments. If splitting * is not supported, an error will be thrown. */ getSplit?(destination: readonly [RangeCoords, RangeCoords], orientation: RangeOrientation, offset: number): [T, T] | undefined; /** * Attempts to merge this range with another range, based on specified coordinates * and orientation. Returns a new merged range or `undefined` if merging is not possible. * * @param other The other range to merge with. * @param coords The coordinates of the merged range. * @param orientation The orientation (horizontal/vertical) for merging. * @returns A new merged range if successful, or `undefined` if merging is not possible. * * @remarks * This method always returns a merged range that is aligned to the left/top. */ getMerged?(other: T, coords: RangeCoords, orientation: RangeOrientation): T | undefined; /** * Called when the range is shifted. * * @param options The details of the shift operation. * @returns The new shifted range entry, or `undefined` if shifting is not possible. * * @remarks * * Always happens in a direction. If not implemented, a shift will still occur. * * An insert will attempt to resize, then split, then error. * * A delete will attempt to resize, then split, then error. */ getShifted?(options: ISpatialMap.ShiftDetails): ISpatialMap.Entry | undefined; /** * Called when the node is being removed. * * @param coords The coordinates of the range being removed. * * @remarks * This is not reliably called. */ onRemove?(entry: ISpatialMap.Entry): void; /** * Copies the range to a specified destination. * * @param destination The destination coordinates. * @param options Optional parameters for the copy operation. * @returns The copied range. * * @remarks * The destination is guaranteed to be a multiple of the RangeCoords. * Will tile if `canTileTo` returns `true`; otherwise, the size will always be the same. */ copyTo?(destination: RangeCoords, options?: ISpatialMap.CopyOptions): T; /** * Returns a flag indicating whether the range can be tiled. * * @param destination The destination coordinates. * @param options Optional parameters for the tiling operation. * @returns `true` if the range can be tiled; otherwise, `false`. * * @remarks * If missing or not implemented, it is assumed that the range cannot be tiled. */ canTile?(destination: RangeCoords, options?: ISpatialMap.CopyOptions): boolean | RangeOrientation; } /** * Provide a set of options to enabled Updating entries. */ interface UpdateEntryOptions { /** * This will be recursively called to break ranges into smaller parts to ensure there is no * overlap. * * @param from The entry that is being split * @param destination The default splits * @param orientation The orientation. * @param offset The offset. 0 is far left. * @throws - Error if the split cannot be performed. * @returns An array of 2 values that represent the values for the split. */ getSplit?(from: ISpatialMap.Entry, destination: [ISpatialMap.Entry, ISpatialMap.Entry], orientation: RangeOrientation, offset: number): [ISpatialMap.Entry, ISpatialMap.Entry] | null; /** * Attempts to merge two entries in an orientations. Returns a new merged entry or `undefined` if merging is not possible. * * @param from The other range to merge with. * @param destination The coordinates of the merged range. * @param orientation The orientation (horizontal/vertical) for merging. * @returns A new merged range if successful, or `undefined` if merging is not possible. * * @remarks * This method always returns a merged range that is aligned to the left/top. */ getMerged?(from: [ISpatialMap.Entry, ISpatialMap.Entry], destination: ISpatialMap.Entry, orientation: RangeOrientation): ISpatialMap.Entry | null | undefined; /** * Return a shifted range. * * @param options The details of the shift operation. * @returns The new shifted range entry, or `undefined` if shifting is not possible. * * @remarks * * Always happens in a direction. If not implemented, a shift will still occur. * * An insert will attempt to resize, then split, then error. * * A delete will attempt to resize, then split, then error. */ getShifted?(from: ISpatialMap.Entry, destination: ISpatialMap.Entry, options: ISpatialMap.ShiftDetails): ISpatialMap.Entry | undefined; /** * Called after all splitting for any ranges that intersect. * * @param orig A node with the original value. * @param adj A node with the adjusted value. * @returns The value for the intersected ranges. * * @remarks * * This can be called multiple times on a single inset with different bounds and values to due splits. */ getIntersect?(orig: ISpatialMap.Entry, adj: ISpatialMap.Entry): ISpatialMap.Entry | null; /** * Copies the entry to a specified destination. * * @param destination The destination coordinates. * @param options Optional parameters for the copy operation. * @returns A new entry. * * @remarks * The destination is guaranteed to be a multiple of the RangeCoords. * Will tile if `canTileTo` returns `true`; otherwise, the size will always be the same. */ copyTo?(from: ISpatialMap.Entry, destination: RangeCoords, options?: ISpatialMap.CopyOptions): ISpatialMap.Entry; /** * Returns a flag indicating whether the range can be tiled. * * @param destination The destination coordinates. * @param options Optional parameters for the tiling operation. * @returns `true` if the range can be tiled; otherwise, `false`. * * @remarks * If missing or not implemented, it is assumed that the range cannot be tiled. */ canTile?(orig: ISpatialMap.Entry, destination: RangeCoords, options?: ISpatialMap.CopyOptions): boolean | RangeOrientation; /** * Called on all nodes that have been modified by either a split or an insert but not a shift. * * @param adj The adjust node. * * @remarks * * Provides a hook to track all changes. * * If `null` is return then this will be culled. */ getUpdate?(adj: ISpatialMap.Entry): ISpatialMap.Entry | null | void; /** * Called for all nodes that are being shifted. */ onShifted?(shifted: ISpatialMap.Entry[]): void; /** * called when a range is removed. This can be due to * either a remove of the entry of a shift. * * @param removes */ onRemoved?(removes: ISpatialMap.Entry[]): void; /** * Called when a value is inserted or updated. */ onUpdated?(updates: ISpatialMap.Entry[]): void; onMerged?(onMerges: ISpatialMap.Entry[]): void; /** * Called when a group is updated. * * @param entries All entries in the group. * @param uuid Any params argument passed a modification option. */ onGroupUpdate?(entries: ISpatialMap.Entry[], uuid?: string): void; /** * Called after structure has been updated with for any reason with all * inserts and removes. * * @param insert All new entries. * @param remove All removed entries. */ onUpdates?(inserts: ISpatialMap.Entry[], removes: ISpatialMap.Entry[], spatial: ISpatialMap): void; /** * Indicates whether shifting should occur when an insert is made on the trailing row or column. * * @defaultValue `false` * * @remarks * Useful for ranges that shift the value immediately before on an insert (e.g., styles). */ isTrailingEdge?: boolean; /** * Indicates if the entries should split when the range is expanding. * * @defaultValue `false` * * @remarks * Examples include formula, comments, and conditional formatting */ isSplitOnExpand?: boolean; /** * If `true` then after shift any shift entries will attempt to be merged to their nearest neighbors. * * @defaultValue `false` * * @remarks * This will cause merge to fail it there are any overlapping ranges. * Examples include styles. */ isMergeOnShift?: boolean; /** * Default for merge */ noMerge?: boolean; } /** * Options for the shift method on the Index. */ interface ShiftOptions { /** * The range to shift. */ range: RangeCoords; /** * The direction to shift. */ direction: Direction; /** * If `true` the this will return a clone index if there are any modifications. * * @defaultValue false * * @remarks * This allows for a 0-1 clone on write. */ cloneIfUpdate?: boolean; /** * Allows for a a validation of the range after the shift amount is determined * but before this shift is performed. * * @remarks * * Useful when performing inserts that may fall outside of the bounds. */ coordValidator?: CoordUtils.CoordValidator; /** * If provided this will be called to update to ensure the location if valid. */ onShift?: (options: ISpatialMap.ShiftDetails) => void; } /** * Options for {@link ISpatialMap.insertNonOverlappingOptions} */ interface InsertNonOverlappingOptions { /** * Callback function that will be be called on insert. * * @remarks * If see this will be called for each new entry creation with the original entry. */ onIntersect?: (orig: ISpatialMap.Entry, adj: ISpatialMap.Entry) => ISpatialMap.Entry; onUpdates?(inserts: ISpatialMap.Entry[], removes: ISpatialMap.Entry[], spatial: ISpatialMap): void; /** * If `true` then insert will not attempt to merge fragmented entries. * * @remarks * Useful when you want to merge all entries at the end. */ noMerge?: boolean; } /** * Pair of spatial updates when doing batch updates. */ interface Updates { inserts: ISpatialMap.Entry[]; removes: ISpatialMap.Entry[]; } /** * Details about the shift operation. */ interface ShiftDetails { before: ISpatialMap.Entry; after: ISpatialMap.Entry | null; intersect: RangeCoords; isSplit: boolean; orientation: RangeOrientation; amount: number; } /** Options */ interface ConstructorOptions { /** * Options for managing updates,splits, and merges. */ updateEntryOptions?: ISpatialMap.UpdateEntryOptions; /** * @param maxEntries An optional argument to RBush defines the maximum number of entries in a tree node. Higher * value means faster insertion and slower search, and vice versa. * @defaultValue 9. */ maxNodeEntries?: number; } interface CopyOptions { transpose?: boolean; } } /** * Checks if a string is enclosed in matching quotes. * * @param str The string to check. * @returns `true` if the string is quoted with matching characters, `false` otherwise. */ declare const isQuoted: (str: string) => boolean; /** * Contains a collection of interned strings. */ export declare interface IStringCollection extends ICollection, ICollection.IPersistable { /** * Add a string to the collection. * * @param shared A string * * @remarks * Resources are not removed from the the collection. They are autoGCed when there are no references. */ add(shared: string): number; /** * Add multiple string to the collection. * * @param shared An array of strings * @param conflateDuplicates If the same string is in the list it will be conflated. Default value `false`. * * @remarks * There are instances where Excel may have duplicate strings so by default this is false. */ addMultiple(shared: string[], conflateDuplicates?: boolean): void; /** * Returns the string for the given id. * * @param id The id */ getById(id: number): string; /** {@inheritDoc ICollection.IPersistScope} */ beginPersist(): ICollection.IPersistScope; } /** * {@inheritDoc IStringCollection} * @see * ### **Interface** * * {@link IStringCollection} */ export declare namespace IStringCollection { export interface GetItemsOptions extends ICollection.GetItemsOptions { id?: number; } /** * Alias for persist type of `string`. */ export type JSON = string; } /** * The `IStyle` interface combines user-applied styles with dynamic styles, such as those from tables or conditional * formatting, to deliver the current appearance. */ export declare interface IStyle { /** * Format used for Number formatting: * * {@link https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1} * * {@link https://customformats.com/} * * @remarks * * If a number provided the builtIn numFmtId as defined in OOXML will be used. * * {@link NumberFormat.Type} */ getNumberFormat(): string; /** * @see {@link IStyle.getNumberFormat} */ setNumberFormat(numFmt: string | null, options?: IStyle.UpdateOptions): IStyle; /** * A boolean value indicating whether the text string in a cell should be prefixed by a single quote mark (e.g., 'text). * In these cases, the quote is not stored in the Shared Strings Part. */ getQuotePrefix(): boolean; /** * @see {@link IStyle.getQuotePrefix} */ setQuotePrefix(quotePrefix: boolean | null, options?: IStyle.UpdateOptions): IStyle; /** * Returns the border style. */ getBorder(): IBorder; /** * Sets the border style. * * This method allows updating borders using an {@link IBorder} or a shorthand property object. * * @param border The border object or a shorthand property object to apply. Pass `null` to clear. * @param options Optional configuration for the update. * @returns The `IBorder` object for further modifications. */ setBorder(border: IBorder.Update, options?: IStyle.UpdateOptions): IStyle; /** * Fill properties for the background. */ getFill(): IFill.ISolid | IFill.IGradient | IFill.IPattern | IFill.INone; /** * Sets the fill style. * * This method allows updating fill using an {@link IFill} or a shorthand property object. * * @param fill The fill object or a shorthand property object to apply. Pass `null` to clear. * @param options Optional configuration for the update. * @returns The `IFill` object for further modifications. */ setFill(fill: IFill.Update, options?: IStyle.UpdateOptions): IStyle; /** * Returns the alignment for the style. */ getAlignment(): ITextFrame.IAlignment; /** * Sets the alignment style. * * This method allows updating alignments using an {@link ITextFrame.IAlignment.Update} or a shorthand property object. * * @param alignment The alignment object or a shorthand property object to apply. Pass `null` to clear. * @param options Optional configuration for the update. * @returns The `ITextFrame.IAlignment` object for further modifications. */ setAlignment(alignment: ITextFrame.IAlignment.Update, options?: IStyle.UpdateOptions): IStyle; /** * Returns the font for the style. */ getFont(): IStyledFont; /** * Sets the font style. * * This method allows updating fill using an {@link IStyledFont} or a shorthand property object. * * @param font The font object or a shorthand property object to apply. Pass `null` to clear. * @param options Optional configuration for the update. * @returns The `IStyledFont` object for further modifications. */ setFont(font: IStyledFont.Update, options?: IStyle.UpdateOptions): IStyle; /** * Returns an instance of the named style that this is derived from. */ getNamed(): IStyle.INamed; /** * Sets the named style that this is derived from. * * @param named The named style to set. */ setNamed(named: string | IStyle.INamed | null, options?: IStyle.UpdateOptions): IStyle; /** * Update many style properties at once. * * @param update {@link IStyle.Update} * @param options {@link IStyle.UpdateOptions} * @returns The `IStyle` for further modifications. */ update(update: IStyle.Update, options?: IStyle.UpdateOptions): IStyle; /** * Measure the text using the styling properties * * @param text The text to measure. * @param size Size @defaultValue 'to the cell font.size' * @param family Family @defaultValue 'to the cell font.family' * @param options Options for the measurement. */ measureText(text: string, size?: number, family?: string, options?: IFont.MetricOptions): IFont.ExtendedMetrics; /** * Creates a simple text frame that can be used for rendering and/or measuring. * * @param text * @param allowWrap If true then will try to wrap on natural breaks. */ createTemporaryTextFrame(text: string, allowWrap?: boolean): ITextFrame; /** * Returns the best fit size assuming no content. */ getBestFit(): Partial | null; /** * Returns insets used for content. This does not taking into account indent because * this is alignment and type specific. */ getInsets(): Rectangle; /** * This is used to determine if the style has rendering * artifacts even if there is no content. (For example borders or background) */ hasVisibleStyling(): boolean; /** * Allows for a non managed style. Useful for tooltips or other transient styles. * * @param update Adjustments to the style. */ createTemporaryStyle(update: IStyle.Update): IStyle; /** * Returns `true` if the CellStyle is the normal style */ isNormal(): boolean; /** * Returns a JSON representation of the style. */ toJSON(): IStyle.JSON | null; /** * For runtime type checking. */ readonly isIStyle: true; } /** * {@inheritDoc IStyle} * @see * ### **Interface** * * {@link IStyle} */ export declare namespace IStyle { /** * The properties for IStyle. */ export interface Properties { /** * Font properties. * * @see * {@link IStyle.getFont} */ font?: IStyledFont.Properties; /** * Fill properties. * * @see * {@link IStyle.getFill} */ fill?: C | IFill.SolidProperties | IFill.GradientProperties | IFill.PatternProperties | IFill.NoneProperties; /** * Number Format properties. * * @see * {@link IStyle.getNumberFormat()} */ numberFormat?: string | NumberFormat.Type | number; /** * Alignment properties. * * @see * {@link IStyle.getAlignment} */ alignment?: ITextFrame.IAlignment.Properties; /** * Border properties. * * @see * {@link IStyle.getBorder} */ border?: IBorder.Properties; /** * Quote Prefix property. * * @see * {@link IStyle.getQuotePrefix} */ quotePrefix?: boolean; /** * Named style property. * * @see * {@link IStyle.getNamed} */ named?: IStyle.BuiltInName | string; /** * Custom indentation insets. */ insets?: Partial; } /** * Enable properties to be set using string shorthands. */ export type Modifiers = IProperties.ResolvableProperties; export interface ModifierCallback { (original: IStyle): IStyle.Modifiers; } /** * Options for updating a style. */ export type Update = IStyle | IStyle.Modifiers | IStyle.ModifierCallback | null; /** * Options for Updates. */ export interface UpdateOptions extends ITransaction.OperationOptions { /** * Convenience method that calls autoFit after the setValues. * @defaultValue `none` - No autofit. * * @remarks * If set to `true` then autoFit will mimic the UI with the following options: ``` { skipCustomSize: true, expandOnly: true, minContent: true } ``` */ autoFit?: boolean | ICellRange.AutoFitOptions; } export interface JSON extends Properties { } /** * Represents a named cell style that can be selected and applied across multiple cells. * Named styles provide a convenient way to apply predefined or custom styling * options available within the application's UI. Commonly used for both built-in * and user-defined styles in spreadsheet applications. */ export interface INamed { /** * Returns the name for the style. */ getName(): string; /** * Returns the style customizations. */ getRanged(): IProperties.ICellRanged; /** * If 'true' do not show this style in the application UI. */ isHidden(): boolean; /** * Specifies if this style is applied to outline levels in the application. * * @returns The outline level if this style applies to outlines, or `null` * if it is not associated with any outline levels. * * @remarks * * Outline styles allow automatic application of the style to cells at a * specific outline level. * * Returns `null` if outline does not affect styles. */ getILevel(): number | null; /** * Identifies the built-in ID for predefined styles, if applicable. * * @returns The built-in ID number if the style is a predefined one, or `null` * if the style is custom. */ getBuiltInID(): number | null; /** * Deletes the style. * * @remarks * For built-in styles, this method will hide. */ delete(): void; /** * For Persisting. */ toJSON(): IStyle.NamedJSON; /** * For runtime type checking. */ readonly isINamed: true; } /** * Properties associated with an {@link INamed} style. * * @remarks * Used for performing updates and saving to JSON. */ export interface NamedProperties { /** * @see * {@link INamed.getName} */ name: string; /** * @see * {@link INamed.isHidden} */ hidden?: boolean; /** * @see * {@link INamed.getILevel} */ iLevel?: number | null; /** * The cell style properties. */ style: IStyle.Properties; } /** * For persisting. */ export interface NamedJSON extends NamedProperties { } /** * Extends the NamedProperties with the ability to use a callback on the style. */ export interface NamedUpdate extends Omit, 'style'> { /** * Allows for style modifications. */ style: IStyle.Update; } /** * List of BuiltIn CellStyles. */ const BuiltInName: { readonly Normal: "Normal"; readonly RowLevel: "RowLevel_#"; readonly ColLevel: "ColLevel_#"; readonly Comma: "Comma"; readonly Currency: "Currency"; readonly Percent: "Percent"; readonly Comma0: "Comma [0]"; readonly Currency0: "Currency [0]"; readonly Hyperlink: "Hyperlink"; readonly FollowedHyperlink: "Followed Hyperlink"; readonly Note: "Note"; readonly WarningText: "Warning Text"; readonly Unknown12: "??-12"; readonly Unknown13: "??-13"; readonly Unknown14: "??-14"; readonly Title: "Title"; readonly Heading1: "Heading 1"; readonly Heading2: "Heading 2"; readonly Heading3: "Heading 3"; readonly Heading4: "Heading 4"; readonly Input: "Input"; readonly Output: "Output"; readonly Calculation: "Calculation"; readonly CheckCell: "Check Cell"; readonly LinkedCell: "Linked Cell"; readonly Total: "Total"; readonly Good: "Good"; readonly Bad: "Bad"; readonly Neutral: "Neutral"; readonly Accent1: "Accent1"; readonly Accent1_20: "20% - Accent1"; readonly Accent1_40: "40% - Accent1"; readonly Accent1_60: "60% - Accent1"; readonly Accent2: "Accent2"; readonly Accent2_20: "20% - Accent2"; readonly Accent2_40: "40% - Accent2"; readonly Accent2_60: "60% - Accent2"; readonly Accent3: "Accent3"; readonly Accent3_20: "20% - Accent3"; readonly Accent3_40: "40% - Accent3"; readonly Accent3_60: "60% - Accent3"; readonly Accent4: "Accent4"; readonly Accent4_20: "20% - Accent4"; readonly Accent4_40: "40% - Accent4"; readonly Accent4_60: "60% - Accent4"; readonly Accent5: "Accent5"; readonly Accent5_20: "20% - Accent5"; readonly Accent5_40: "40% - Accent5"; readonly Accent5_60: "60% - Accent5"; readonly Accent6: "Accent6"; readonly Accent6_20: "20% - Accent6"; readonly Accent6_40: "40% - Accent6"; readonly Accent6_60: "60% - Accent6"; readonly ExplanatoryText: "Explanatory Text"; }; export type BuiltInName = typeof BuiltInName[keyof typeof BuiltInName]; /** * BuiltIn IconSets used for conditional formatting. */ const IconSet: { readonly Arrows3: "3Arrows"; readonly ArrowsGray3: "3ArrowsGray"; readonly Flags3: "3Flags"; readonly Signs3: "3Signs"; readonly Symbols3: "3Symbols"; readonly Symbols3_2: "3Symbols2"; readonly TrafficLights3: "3TrafficLights1"; readonly TrafficLights3_2: "3TrafficLights2"; readonly Arrows4: "4Arrows"; readonly ArrowsGray4: "4ArrowsGray"; readonly Rating4: "4Rating"; readonly RedToBlack4: "4RedToBlack"; readonly TrafficLights4: "4TrafficLights"; readonly Arrows5: "5Arrows"; readonly ArrowsGray5: "5ArrowsGray"; readonly Quarters5: "5Quarters"; readonly Rating5: "5Rating"; }; export type IconSet = typeof IconSet[keyof typeof IconSet]; } /** * Contains collections of Named and Table Styles. */ export declare interface IStyleCollection { /** * Returns The named style from either a custom style or a builtIn. * * @remarks * Will try to return: * 1. The custom style for the name * 2. The builtin style for the name. * 3. nul if it doesn't exist. */ getNamed(name: string): IStyle.INamed | null; /** * Returns all customized named cell styles. * * @remarks * This includes new style names and builtin overrides. */ getCustomNamed(): IStyle.INamed[]; /** * This will add or update a cell style. * * @param modifiers The Style or Style Modifiers * @param mergeIfExists If true then the style will be merged with the existing style otherwise is a replace. @defaultValue false * @returns The new style after any merges. * * @remarks * Names are case insensitive; for duplicate detection purposes. */ setNamed(modifiers: IStyle.NamedUpdate, mergeIfExists?: boolean): IStyle.INamed; /** * Returns The table style. This can be either a custom or a built in table style. * * @remarks * Will try to return: * 1. The custom style for the name * 2. The builtIn style for the name. * 3. `null` if it doesn't exist. */ getTableStyle(name?: string): ITableStyle | null; /** * Returns all customized table styles. * * @remarks * This includes new table styles and builtin overrides. */ getCustomTableStyles(): ITableStyle[]; /** * This will add or update a table style. * @param name A string of the name of the table. * @param properties The values to set for the table style. * @returns A new `ITableStyle` representing the updated style. * * @remarks * Case insensitive; for duplicate detection purposes. */ setCustomTableStyle(name: string, properties: ITableStyle.ResolvableProperties): ITableStyle; /** * Set the default table style to use if a table is created without specifying a style. * * @param name A string of the name of the table * @remarks * The style must exist or the defaultStyle will be set to 'TableStyleMedium2'. */ setDefaultTableStyle(name: string): void; /** * Returns the default ITableStyle. * @see * {@link setDefaultTableStyle} */ getDefaultTableStyle(): ITableStyle; /** * Returns the current theme */ getTheme(): ITheme; /** * Set the theme used to calculate styles. * * @param theme The ITheme to use. */ setTheme(theme: ITheme): void; /** * Themes do not contain font sizes but it is possible to set a default font size at the document or application level. */ getDefaultFontSize(): number; /** * Set the default fontSize. Note - A theme does NOT contain this. * @param fontSize The new default font size. */ setDefaultFontSize(fontSize: number): void; /** * This is available for functions that want to resolve colors for the theme used specifically for this style. */ schemeLookup(): IColor.SchemeLookup; /** * This is available for functions that want to resolve colors using the index color palette. * @see * {@link IColor.IndexedLookup} */ indexedLookup(): IColor.IndexedLookup; /** * Parses the color using the Theme being used by this style * @param str Any string that represents a color {@link IColor}. */ parseColor(str: any): IColor; /** * Returns a list of colors that were added via {@link addRecentColor}. */ recentColors(): readonly IColor[]; /** * Add a color to the mru list. This is used to populate color pickers. * * @param color The color to record. * * @remarks * Any color can be added but generally this should be limited to custom/non-themed color */ addRecentColor(color: IColor): readonly IColor[]; /** * Clears the mru color list */ clearRecentColors(): void; /** * Returns an array of colors that will be used to resolve any colors that use IndexXX or ColorXX as a key. */ getIndexedColors(): readonly IColor[]; /** * Override the default indexed colors. * @param colors An array of colors. */ setCustomIndexedColors(colors: readonly IColor[]): void; /** * Returns the customized Indexed colors. */ getCustomIndexedColors(): readonly IColor[]; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: IStyleCollection.IListeners, options?: IListener.Options): IListener.Remove; /** * Converts a list of `IStyle.Modifiers` that contain shorthand values into native values. * * @param modifiers {@link IStyle.Modifiers} * @param name Name used to normalize against. This overrides any specified in the modifiers. * @returns A valid IStyle.Modifiers with values that match the normal style removed. * * @remarks * Will also remove any value that resolve to the same values as the referenced named style (or Normal if this is not specified). */ normalize(modifiers: IStyle.Modifiers, name?: string): Partial; /** * Convenience mechanism (and slightly faster) way to call getNamed('Normal').getRanged(); */ getNormalRanged(): IProperties.ICellRanged; /** * Return a the Normal styles as an IStyle.; */ getNormal(): IStyle; /** * Checks the current name to see if this is a valid sheetName. */ validateStyleName(name: string, checkDuplicates?: boolean): void; /** * Start persisting styles. * * * This is used during save/load to allow for styles to be references by an id count. * * This is a stack so multiple begins will need to be matched with an end. * @see * {@link IStyleCollection.IPersistScope} */ beginPersist(): IStyleCollection.IPersistScope; } /** * {@inheritDoc IStyleCollection} * @see * ### **Interface** * * {@link IStyleCollection} */ export declare namespace IStyleCollection { export interface Events { /** * Notify that the named styled has changed */ onNamedStylesChange?(source: IStyleCollection): void; onTableStylesChange?(source: IStyleCollection): void; onThemeChange?(source: IStyleCollection): void; onDefaultFontChange?(source: IStyleCollection): void; onAnyChange?(source: IStyleCollection): void; } export interface IListeners extends IListener.Callbacks { } export interface JSON { /** * Used by cells styles. */ direct?: IStyle.JSON[]; /** * cells styles with a name for quick styling. */ named?: IStyle.NamedJSON[]; /** * Table styles. */ tables?: ITableStyle.JSONS; /** * A list of custom colors. */ mruColors?: string[]; /** * Overrides for indexed colors. */ indexedColors?: string[]; } /** * A transient scope for persisting styles with a given * set of StyleIDs. * * @remarks * This is done to ensure that styles across multiple * sheets are rationalized */ export interface IPersistScope { /** * End the persist scope. This will clear the stack and stop tracking access to this. */ endPersist(): void; /** * This can be called multiple times. * * @returns The state as {@link IStyleCollection.JSON}. * * @remarks * Only shared styles that have had the toResourceId called will * be shown in the persisted json. */ toJSON(): IStyleCollection.JSON; /** * Load a JSON for a StyleCollection object. * * @remarks * Once this is called the getSharedStyle is available for all * the ids defined in the JSON for the current scope. * @param json {@link IStyleCollection.JSON} */ fromJSON(json: IStyleCollection.JSON): void; /** * Given the id return the style. * This assumes that the fromJSON has been called previously. * * @param id */ getElementJSON(id: number): IStyle.JSON; /** * A 0-based style id for the given style. If this is a named style * or a style that is not available with the styles then this will return null. * * @remarks * This is a side effect operation. Calling this will cause the style to be persisted as part of the toJSON * * @param json */ getElementID(json: IStyle.JSON): number | null; } } /** * Represents a font with styling color. */ export declare interface IStyledFont { /** * This can be set as a string using html values such as 'Arial 11pt' but will be resolved to a single font. Fallbacks and fontSize will be * marshalled into their correct property. */ getFamily(): string; /** * @see {@link IStyledFont.getFamily} */ setFamily(family: string | null, options?: IStyle.UpdateOptions): IStyledFont; /** * A list of fonts and their fallbacks. These can also be provided in the fontFamily attribute but will * be normalized to here. */ getFallbacks(): string[]; /** * @see {@link IStyledFont.setFallbacks} */ setFallbacks(fallbacks: string[] | null, options?: IStyle.UpdateOptions): IStyledFont; /** * Font size is either a number in points or a string that can be converted such as '14px', '1.5em'. */ getSize(): number; /** * @see {@link IStyledFont.setSize} */ setSize(size: number | null, options?: IStyle.UpdateOptions): IStyledFont; /** * The weight of the characters. */ getWeight(): number; /** * @see {@link IStyledFont.setWeight} */ setWeight(weight: number | null, options?: IStyle.UpdateOptions): IStyledFont; /** * @default `IFont.Style.Normal` */ getStyle(): IFont.Style; /** * @see {@link IStyledFont.setStyle} */ setStyle(style: IFont.Style | null, options?: IStyle.UpdateOptions): IStyledFont; /** * The text color. * * @remarks * Currently only solid fill is supported but this will be expanded to allow all fill types similar to DrawML. */ getFill(): IColor; /** * @see {@link IStyledFont.setFill} */ setFill(fill: IColor | null, options?: IStyle.UpdateOptions): IStyledFont; /** * Adds or removes additional spacing between the characters. */ getLetterSpacing(): number; /** * @see {@link IStyledFont.setLetterSpacing} */ setLetterSpacing(letterSpacing: number | null, options?: IStyle.UpdateOptions): IStyledFont; /** * Sets the underline style. If true defaults to single. If false or null defaults to none. * * @default `IFont.UnderlineStyle.None` */ getUnderline(): IFont.UnderlineStyle; /** * @see {@link IStyledFont.setUnderline} */ setUnderline(underline: IFont.UnderlineStyle | null, options?: IStyle.UpdateOptions): IStyledFont; /** * The effect draws the text with a line through it. */ getStrike(): boolean; /** * @see {@link IStyledFont.setStrike} */ setStrike(strike: boolean | null, options?: IStyle.UpdateOptions): IStyledFont; /** * Defines the font scheme to use. * @default `IFont.Scheme.Minor` */ getScheme(): IFont.Scheme; /** * @see {@link IStyledFont.setScheme} */ setScheme(scheme: IFont.Scheme | null, options?: IStyle.UpdateOptions): IStyledFont; /** * Returns the vertical alignment of the text within a text line. * * @remarks * If the IFont.VerticalAlignment is superscript or subscript then the font size should also render smaller. */ getVerticalAlignment(): IFont.VerticalAlignment; /** * @see {@link IStyledFont.setVerticalAlignment} */ setVerticalAlignment(verticalAlignment: IFont.VerticalAlignment | null, options?: IStyle.UpdateOptions): IStyledFont; /** * The effect draws a shadow around the text. * * @remarks * Not rendered by Excel or SheetXL. */ getShadow(): boolean; /** * @see {@link IStyledFont.setShadow} */ setShadow(shadow: boolean | null, options?: IStyle.UpdateOptions): IStyledFont; /** * The effect draws the text as an outline. * * @remarks * Not rendered by Excel or SheetXL. */ getOutline(): boolean; /** * @see {@link IStyledFont.setOutline} */ setOutline(outline: boolean | null, options?: IStyle.UpdateOptions): IStyledFont; /** * The effect extends or stretches out the text. * * @remarks * Not rendered by Excel or SheetXL. */ getExtend(): boolean; /** * @see {@link IStyledFont.setExtend} */ setExtend(extend: boolean | null, options?: IStyle.UpdateOptions): IStyledFont; /** * Returns `true` if the font is either a superscript or a subscript. */ isSuperSub(): boolean; /** * Returns the size to scale the font for super/sub text. */ getSuperSubScale(): number; /** * Returns the number of pixels to shift the font for super/sub text. */ getSuperSubShift(): number; /** * Compare against another font to see if they will have the same font measure * This is used to optimize updates by not re-calcing the width/height * * @param other The other style font */ isEqualMeasure(other: IStyledFont): boolean; /** * Returns the font styles as a set of css string that are suitable for css. * * @remarks * Not all fill styles will offer an exact css equivalent. * Additionally due to the nature of css having different properties for the same logic value * (for example color, backgroundColor) */ toCSS(darkMode?: boolean, zoom?: number, ignoreNormal?: boolean): Properties; /** * Serializes to a JSON object. */ toJSON(): IStyledFont.JSON; /** * For runtime type checking. */ readonly isIStyledFont: true; } /** * {@inheritDoc IStyledFont} * @see * ### **Interface** * * {@link IStyledFont} */ export declare namespace IStyledFont { /** * Represents a font with color. */ export interface Properties { family?: string; fallbacks?: string[]; size?: number; weight?: number | string; style?: IFont.Style; fill?: C; letterSpacing?: number; underline?: boolean | IFont.UnderlineStyle | null; strike?: boolean; scheme?: IFont.Scheme; verticalAlign?: IFont.VerticalAlignment; shadow?: boolean; outline?: boolean; extend?: boolean; } /** * Modifiers describe a partial list of properties that can be set with values or shorthand strings. */ export type Modifiers = Partial>; /** * Options for updating a font. */ export type Update = IStyledFont | Modifiers | string | null; export interface JSON extends Properties { } } /** * Validates if a string is a valid email. * * @param text The string to check. * @returns `true` if the string is a valid email, `false` otherwise. */ declare const isValidEmail: (text: string) => boolean; /** * Validates if a string is a valid HTTP or HTTPS URL. * * @param value The string to check. * @returns `true` if the string is a valid HTTP or HTTPS URL, `false` otherwise. */ declare const isValidHttpUrl: (value: string) => boolean; /** * Capabilities for working with embedded tables. * * Tables offer structured data management and enhanced analysis features. * * Key features including: * - Operating on data with named and typed columns. * - Automatic filtering and sorting options. * - Creating calculated columns with dynamic formulas. * - Utilizing structured references for easier formula creation. * - Applying table styles for visual organization and improved readability. * * @see * ### **Interface** * * {@link ITable} * * **Additional Interfaces** * * {@link ITableStyle} * * {@link ITableCollection} */ export declare namespace ITable { /** * Element representing a single column for a table. */ export interface Column { /** * A string representing the unique caption of the table column. * This is what shall be displayed in the header row in the UI, and is referenced through functions. * This name shall be unique per table. */ name: string; } /** * A set of values that can be set on a ITable. * * @see * {@link ITable} */ export interface Properties { /** * The unique name of the table */ name?: string; /** * A string representing the name of the table. This is the name that shall be used in formula references, * and displayed in the UI to the spreadsheet user. * This name shall not have any spaces in it, and it must be unique amongst all other displayNames and * definedNames in the names. The character lengths and restrictions are the same as for definedNames. * * See SpreadsheetML Reference - Workbook definedNames section for details. */ description?: string; /** * An integer representing the number of header rows showing at the top of the table. * 0 means that the header row is not shown * @defaultValue 1 */ headerRowCount?: number; /** * An integer representing the number of totals rows that shall be shown at the bottom of the table. * * @defaultValue 0 */ totalsRowCount?: number; /** * If not specified then the default table style is used * If the style name isn't valid then uses a 'none' style. */ styleOptions?: ITableStyle.StyleOptions; } /** * Provides destination details for the Snapshot when using {@link IHistory.ISnapshot.copyTo}. */ export interface SnapshotDestination { tables: ITableCollection; range: IRange.Coords; } export interface ISnapshot extends IHistory.ISnapshot { /** * Called when the table is copied to a new collection. */ copyTo(destination: ITable.SnapshotDestination, options?: ReferenceableClipboard.CopyOptions): Promise; } /** * A JSON representation useful for persistence. */ export interface JSON extends Properties { /** * An A1 representation of a range that is the bounding area * for the table. * * @remarks * The reference shall include the totals row if it is shown */ ref: IRange.Coords | string; /** * Table column definitions. */ columns?: ITable.Column[]; /** * If missing than no auto filter enabled */ filter?: IAutoFilter.JSON; /** * This is available on both the filter and the table so that the sort state * can be restored if the filter was removed and re-added. */ sort?: IAutoSort.JSON; } /** * IListener for {@link ITable} events. */ export interface Events extends IAnchored.Events { /** * Called when any property changes. */ onAnyChange?(source: ITable): void; /** * Called when the table is changed. */ onStyleChange?(source: ITable): void; } export interface IListeners extends IListener.Callbacks { } export interface ConstructorOptions extends IAnchored.ConstructorOptions { sheet?: ISheet; /** * Required if there is no sheet. For example when showing table Preview. */ styles?: IStyleCollection; names?: INamedCollection; /** * JSON state to load. */ json?: ITable.JSON; readSheetHeader?: boolean; processTableUpdate?: () => void; /** * Notify the container that a named change is required. * @param name The name to change to */ setNameOnContainer?: (name: string) => void; } } /** * A Table is an embedded table that allows for advanced capabilities. * * 1. Filtering * 2. Dynamic Styling * 3. External data * 4. Structured formulas */ export declare interface ITable extends IAnchored { /** * Selects the current table. * * @returns An async boolean indicating the table was selected. */ select(options?: ICellRange.SelectOptions): Promise; /** * Add a number of rows to a table * @remarks * Not implemented * * @param offset * @param count */ addRows(offset: number, count?: number): ITable; /** * Delete the rows from the table. * @remarks * Not implemented * * @param index The index to clear from * @param count */ deleteRowsAt(index: number, count?: number): ITable; /** * Add a single column. * @remarks * Not implemented * To remove columns use the resize */ addColumn(index: number, name?: string): ITable.Column; /** * Returns the columns for this table. */ getColumns(): ITable.Column[]; /** * Returns an column for the given offset. * @param offset */ getColumnFilter(offset: number): IAutoFilter.IColumn; /** * Returns the AutoFilter used for this table. */ getFilter(): IAutoFilter; /** * Convert the existing table to a range. * This will remove the table but preserve the original * data and formatting. * @param maxCells The maximum number of convert. * @remarks * This can be an expensive operation. */ convertToRange(maxCells?: number): ICellRange; /** * Resize the table. * @param address The new size of the table. * * @remarks * This will throw an exception if: * 1. The top row changes. * 2. If doesn't overlap with the original table. * 3. If overlaps with another non-overlapping object (e.g. another table or a merge). */ resize(address: ICellRange.Address): ICellRange; /** * @see {@link setName} */ getName(): string; /** * Set the name for a table object. * * @param name A unique name. */ setName(name: string): ITable; /** * @see {@link setDescription} */ getDescription(): string; /** * This is the alternative text use for assistive technologies. * * @param description A short human readable text. Default value `null`. */ setDescription(description: string | null): ITable; /** * Returns the range for the entire table. */ getRange(): ICellRange; /** * Get the range between the header and the total. */ getUsedRange(): ICellRange; /** * Get the header range. */ getHeaderRange(): ICellRange; /** * Get the total range. */ getTotalRange(): ICellRange; /** * Get the style info. */ getStyleOptions(): ITableStyle.StyleOptions; /** * Updates the table StyleInfo. * * @param options Style options unique to the table. * * @remarks * This will merge with the existing values. */ updateStyleOptions(options: ITableStyle.StyleOptions): ITable; /** * Returns the current `ITableStyle` used. */ getStyle(): ITableStyle; /** * Returns a cell style for the given coords. * @param coords The absolute coords. * @remarks * This will return a CellStyle rendered with the table styling but not any other styling. * * * This is used by the preview. */ getStyleAt(coords: IRange.CellCoords): IStyle; /** * Specifies if totals are being shown for the table. */ getShowTotals(): boolean; /** * Specifies if totals are being shown for the table. */ setShowTotals(showTotals: boolean): ITable; /** * Specifies if headers are being shown for the table. */ getShowHeaders(): boolean; /** * Specifies if headers are being shown for the table. */ setShowHeaders(showHeaders: boolean): ITable; /** * Specifies if filter buttons are being shown. */ getShowFilterButton(): boolean; /** * Specifies if filter buttons are being shown. * @remarks * If the autoFilter is not enabled this will have no effect. */ setShowFilterButton(showFilterButton: boolean): ITable; /** * Enabled and returns an IAutoFilter. * Only one AutoFilter per table is supported so this will * return the same instance if it has already been created. */ insertFilter(): IAutoFilter; /** * Returns an IAutoFilter associated with this Table. */ getFilter(): IAutoFilter | null; /** * Only one sort per table is supported so this will. * return the same instance if it has already been created. */ insertSort(): IAutoSort; /** * Returns the current sort or null if there is no IAutoSort. * @see * {@link insertSort} */ getSort(): IAutoSort | null; /** * Returns the bounds for the ref accounting for hidden headers. * * @remarks * This is used for borders and drag areas that are based on visible edges. * excluding hidden rows/columns (headers). */ getVisibleRefRangeCoords(): IRange.Coords; /** * Returns the coords after any hidden values are applied. * @param coords The absolute coords */ getVisibleCellCoords(coords: IRange.CellCoords): IRange.CellCoords; /** * Returns a flag indicating if the header is visible due to hidden headers. */ isHeaderVisible(): boolean; /** * Returns a flag indicating if the footer is visible due to hidden headers. */ isTotalVisible(): boolean; /** * Returns a flag indicating if the first column is visible due to hidden headers. */ isFirstColumnVisible(): boolean; /** * Returns a flag indicating if the first column is visible due to hidden headers. */ isLastColumnVisible(): boolean; /** * Returns a snapshot of the table that can be used for copying and archiving. */ getSnapshot(options?: ReferenceableClipboard.CopyOptions): ITable.ISnapshot; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: ITable.IListeners, options?: IListener.Options): IListener.Remove; /** * @returns The current state as a JSON object. */ toJSON(): ITable.JSON; /** * For runtime type checking. */ readonly isITable: true; } /** * Holds a collection of {@link ITable}s. */ export declare interface ITableCollection extends ICollection { /** * Add an `ITable` to the container. * * @param address The address of the table. * @param options Additional options available when adding a table. */ add(address: ICellRange.Address, options?: ITableCollection.AddOptions): ITable; /** * Returns items that match the filter criteria. * * If no filter criteria is provided, all items will be returned. * * @param options {@link ITableCollection.GetItemsOptions} */ getItems(options?: ITableCollection.GetItemsOptions): ITable[]; /** * Convenience method for filter by name. This is * functionally equivalent to getItems({ name }); * * @param name The name to filter for This is case insensitive. */ getByName(name: string): ITable | null; } /** * {@inheritDoc ITableCollection} * @see * ### **Interface** * * {@link ITableCollection} */ export declare namespace ITableCollection { /** * Options for adding a table to the collection. */ export interface AddOptions extends ITransaction.OperationOptions { /** * If not specified then the header status will be determined from the range data. * * @defaultValue 'based on initial data set' */ hasHeader?: boolean; /** * The default style to use. If null than it will not be set * If undefined or not provided it will use the. * * @defaultValue uses the default table style */ styleName?: string; /** * If the add should clear any previous formatting. * @defaultValue false */ clearFormatting?: boolean; /** * JSON state to load. */ json?: ITable.JSON; /** * If the table is being loaded. This is used * to indicate to the table that it should not create * default values. * @defaultValue false; */ isLoad?: boolean; } export interface GetItemsOptions { /** * If provided, the filter will be limited to items that intersect the range. */ address?: ICellRange.Address; /** * Indicate if items that are in hidden headers or marked as hidden should be returned. * * @defaultValue false */ ignoreHidden?: boolean; /** * Only return items that are completely contained with the filter bounds. * * @defaultValue false */ fullyContained?: boolean; /** * Filter with the given name. This is case insensitive. */ name?: string; } } declare interface ITableEntry extends IAnchorEntry { currentName: string; removeListener: IListener.Remove; } export declare namespace ITableStyle { /** * Options used for when calling getStyleProperties. */ export interface StyleOptions { /** * A string representing the name of the table style to use with this table. * If the style name isn't valid then the spreadsheet application should use default style. * If the name is missing then no formatting will be applied. */ name?: string; /** * A Boolean indicating whether row stripe formatting is applied. True when style row stripe formatting is applied. * @defaultValue true */ showRowStripes?: boolean; /** * A Boolean indicating whether column stripe formatting is applied. True when style column stripe formatting is applied. * @defaultValue false */ showColumnStripes?: boolean; /** * A Boolean indicating whether the first column in the table should have the style applied. True if the first column has the style applied. * @defaultValue false */ showFirstColumn?: boolean; /** * A Boolean indicating whether the last column in the table should have the style applied. True if the last column has the style applied. * @defaultValue false */ showLastColumn?: boolean; } /** * The Type of element to style. */ const ElementType: { /** * The entire table. */ readonly WholeTable: "wholeTable"; readonly FirstColumnStripe: "firstColumnStripe"; readonly SecondColumnStripe: "secondColumnStripe"; readonly FirstRowStripe: "firstRowStripe"; readonly SecondRowStripe: "secondRowStripe"; readonly LastColumn: "lastColumn"; readonly FirstColumn: "firstColumn"; readonly HeaderRow: "headerRow"; readonly TotalRow: "totalRow"; readonly FirstHeaderCell: "firstHeaderCell"; readonly LastHeaderCell: "lastHeaderCell"; readonly FirstTotalCell: "firstTotalCell"; readonly LastTotalCell: "lastTotalCell"; }; export type ElementType = typeof ElementType[keyof typeof ElementType]; /** * Extends {@link IStyle.Properties} to include a size. * * @remarks * This is used to allow for different styles depending on the number of stripes * (rows or columns used for the style). */ export interface SizeBasedProperties extends IStyle.Properties { /** * The size is available for the following table elements: * * firstRowStripe * * secondRowStripe * * firstColumnStripe * * secondColumnStripe * * @defaultValue 1 */ size?: number; } /** * A table style is a collection of cell styles that are applied to a table. * These are applied in a specific order and merged to create a single cell style. * * The order is: * Whole Table * * First Column Stripe * * Second Column Stripe * * First Row Stripe * * Second Row Stripe * * Last Column * * First Column * * Header Row * * Total Row * * First Header Cell * * Last Header Cell * * First Total Cell * * Last Total Cell */ export interface Properties { /** * The name of the table style. This is the name that is shown in the UI. */ name: string; /** * If this table style should be shown as an available table style. * @remarks * table and pivot can not both be true. If both false then hidden * @defaultValue true */ table?: boolean; /** * 'True' if this table style should be shown as an available pivot table style. * @remarks * table and pivot can not both be true. If both false then hidden * @defaultValue false */ pivot?: boolean; /** * Properties for the whole table. */ wholeTable?: IStyle.Properties; /** * Properties for the first set of alternating columns. */ firstColumnStripe?: ITableStyle.SizeBasedProperties; /** * Properties for the second set of alternating columns. */ secondColumnStripe?: ITableStyle.SizeBasedProperties; /** * Properties for the first set of alternating rows. */ firstRowStripe?: ITableStyle.SizeBasedProperties; /** * Properties for the second set of alternating rows. */ secondRowStripe?: ITableStyle.SizeBasedProperties; /** * For the last column. */ lastColumn?: IStyle.Properties; /** * For the first column. */ firstColumn?: IStyle.Properties; /** * For the header row. */ headerRow?: IStyle.Properties; /** * For the first header cell. To be applied * both the header and first column must be selected. */ firstHeaderCell?: IStyle.Properties; /** * For the last header cell. To be applied * both the header and last column must be selected. */ lastHeaderCell?: IStyle.Properties; /** * For the total row. */ totalRow?: IStyle.Properties; /** * For the first total cell. To be applied * both the total and first column must be selected. */ firstTotalCell?: IStyle.Properties; /** * For the last total cell. To be applied * both the total and last column must be selected. */ lastTotalCell?: IStyle.Properties; } export type ResolvableProperties = IProperties.ResolvableProperties; export interface JSON extends ITableStyle.Properties { } /** * JSON definition for a list of TableStyles. */ export interface JSONS { defaultTableStyle?: string; defaultPivotStyle?: string; styles?: Record; } /** * Properties for a pivot table style. * * @remarks * **NOT IMPLEMENTED** */ export interface PivotProperties { name?: string; wholeTable?: IStyle.Properties; firstColumnStripe?: ITableStyle.SizeBasedProperties; secondColumnStripe?: ITableStyle.SizeBasedProperties; firstRowStripe?: ITableStyle.SizeBasedProperties; secondRowStripe?: ITableStyle.SizeBasedProperties; firstColumn?: IStyle.Properties; headerRow?: IStyle.Properties; firstHeaderCell?: IStyle.Properties; pageFieldLabels?: IStyle.Properties; pageFieldValues?: IStyle.Properties; subtotalColumn1?: IStyle.Properties; subtotalColumn2?: IStyle.Properties; subtotalColumn3?: IStyle.Properties; blankRow?: IStyle.Properties; subtotalRow1?: IStyle.Properties; subtotalRow2?: IStyle.Properties; subtotalRow3?: IStyle.Properties; columnSubheading1?: IStyle.Properties; columnSubheading2?: IStyle.Properties; columnSubheading3?: IStyle.Properties; rowSubheading1?: IStyle.Properties; rowSubheading2?: IStyle.Properties; rowSubheading3?: IStyle.Properties; grandTotalColumn?: IStyle.Properties; grandTotalRow?: IStyle.Properties; } } /** * Represents a style applied to tables, with methods for retrieving style * properties, checking its usage in different contexts, and identifying built-in styles. */ export declare interface ITableStyle { /** * Returns the name of the table style. * * @returns The name of the table style as a string. */ getName(): string; /** * Indicates whether this style appears in the list of table styles * available for selection. * * @returns `true` if the style is shown in the table styles list; otherwise, `false`. */ isShownInTableStyles(): boolean; /** * Indicates whether this style appears in the list of pivot table styles * available for selection. * * @returns `true` if the style is shown in the pivot table styles list; otherwise, `false`. */ isShownInPivotStyles(): boolean; /** * Returns a ranged interface for applying this style to a specific table. * * @param table The target `ITable` to which this style will be applied. * @returns An `ICellRanged` interface containing properties for `IStyle`. */ getRanged(table: ITable): IProperties.ICellRanged; /** * Indicates whether this style is a built-in, predefined style. * * @returns `true` if the style is a built-in style; otherwise, `false`. */ isBuiltIn(): boolean; /** * Delete the style from the collection. * * @remarks * This will only remove if the style is not a built-in style. * @see * {@link ITableStyle.isBuiltIn} */ delete(): void; /** * Returns the readonly list of properties for the style. * * @remarks * This are unresolved properties. */ getProperties(): Readonly; /** * Serializes the table style to JSON format. * * @returns A `ITableStyle.JSON` representation of the style. */ toJSON(): ITableStyle.JSON; /** * For runtime type checking. */ readonly isITableStyle: true; } /** * {@inheritDoc ITableStyle} * @see * ### **Interface** * * {@link ITableStyle} */ export declare namespace ITableStyle { /** * Special table style that doesn't style anything. This is used * for tables that have their format's cleared. */ export class Empty implements ITableStyle { private _normalStyle; constructor(normalStyle: IStyle); /** {@inheritDoc ITableStyle.getName} */ getName(): string; /** {@inheritDoc ITableStyle.isShownInTableStyles} */ isShownInTableStyles(): boolean; /** {@inheritDoc ITableStyle.isShownInPivotStyles} */ isShownInPivotStyles(): boolean; /** {@inheritDoc ITableStyle.getRanged} */ getRanged(_table: ITable): IProperties.ICellRanged; /** {@inheritDoc ITableStyle.getProperties} */ getProperties(): Readonly; /** {@inheritDoc ITableStyle.isBuiltIn} */ isBuiltIn(): true; /** {@inheritDoc ITableStyle.delete} */ delete(): void; /** {@inheritDoc ITableStyle.toJSON} */ toJSON(): ITableStyle.JSON; /** {@inheritDoc ITableStyle.isITableStyle} */ get isITableStyle(): true; } } /** * Capabilities for working with text. */ export declare namespace IText { export type ITextLine = ITextLine; export type ITextParagraph = ITextParagraph; export type ITextRun = ITextRun; export type IBullet = IBullet; /** * Specifies capitalization options for text within a text frame. */ const SmallCaps: { /** * Normal capitalization. */ readonly None: "none"; /** * Capitalize every letter but reduce the the size of all but the first letter. * * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-caps} */ readonly Small: "small"; /** * Convert all text to uppercase. */ readonly All: "all"; }; export type SmallCaps = typeof SmallCaps[keyof typeof SmallCaps]; /** * Indicate how and if a line will be drawing horizontally through the middle of the text. */ const StrikeStyle: { /** * No strike-through */ readonly None: "none"; /** * A single line. */ readonly Single: "single"; /** * A double line. */ readonly Double: "double"; }; export type StrikeStyle = typeof StrikeStyle[keyof typeof StrikeStyle]; } /** * Provided options for aligned text within a bounding box. */ export declare interface ITextBoxAlignment { /** * Types of horizontal alignment. */ getHorizontal(): ITextFrame.HorizontalAlignment; /** * Sets the horizontal alignment * * @param horizontal The horizontal alignment */ setHorizontal(horizontal: ITextFrame.HorizontalAlignment | null, options?: IStyle.UpdateOptions): ITextBoxAlignment; /** * Types of horizontal alignment. */ getVertical(): ITextFrame.VerticalAlignment; /** * Sets the vertical alignment * * @param vertical The vertical alignment */ setVertical(vertical: ITextFrame.VerticalAlignment | null, options?: IStyle.UpdateOptions): ITextBoxAlignment; /** * An integer value, where an increment of 1 represents 3 spaces. * Indicates the number of spaces (of the normal style font) of indentation for text in a cell. * * @remarks * This is only applied for alignments: left, right, and distributed. */ getIndent(): number; /** * Sets the indentation * * @param indent The indentation */ setIndent(indent: number | null, options?: IStyle.UpdateOptions): ITextBoxAlignment; /** * Indicates additional number of spaces of indentation to adjust for text in a cell. */ getRelativeIndent(): number; /** * Sets the relative indentation * * @param relativeIndent The relative indentation */ setRelativeIndent(relativeIndent: number | null, options?: IStyle.UpdateOptions): ITextBoxAlignment; /** * The behavior for text that does not fit with the cell bounds. * @see * {@link ITextFrame.Overflow} */ getOverflow(): ITextFrame.Overflow; /** * Sets the overflow behavior * * @param overflow The overflow behavior */ setOverflow(overflow: ITextFrame.Overflow | null, options?: IStyle.UpdateOptions): ITextBoxAlignment; /** * Rotation of the text. * @defaultValue 0 */ getRotation(): number; /** * Sets the rotation * * @param rotation The rotation */ setRotation(rotation: number | null, options?: IStyle.UpdateOptions): ITextBoxAlignment; /** * If the text should stack vertically instead of horizontally. */ getStacked(): boolean; /** * Sets the stacked * * @param stacked The stacked */ setStacked(stacked: boolean | null, options?: IStyle.UpdateOptions): ITextBoxAlignment; /** * If the cells justified or distributed alignment should be used on the last line of text. * (This is typical for East Asian alignments but not typical in other contexts.) */ getJustifyLastLine(): boolean; /** * Sets the justified last line * * @param justifyLastLine The justified last line */ setJustifyLastLine(justifyLastLine: boolean | null, options?: IStyle.UpdateOptions): ITextBoxAlignment; /** * The direction the cell is being read. */ getReadingDirection(): ITextFrame.ReadingDirection; /** * Sets the reading direction * * @param readingDirection The reading direction */ setReadingDirection(readingDirection: ITextFrame.ReadingDirection | null, options?: IStyle.UpdateOptions): ITextBoxAlignment; toJSON(): ITextBoxAlignment.JSON; /** * For runtime type checking. */ readonly isITextBoxAlignment: true; } /** * Provided options for aligned text within a bounding box. */ export declare namespace ITextBoxAlignment { /** * Text alignment rules for when text is placed in a bounding box. * (for example a TableCell or a Shape). */ export interface Properties { horizontal?: ITextFrame.HorizontalAlignment; vertical?: ITextFrame.VerticalAlignment; indent?: number; relativeIndent?: number; overflow?: ITextFrame.Overflow; rotation?: number; stacked?: boolean; justifyLastLine?: boolean; readingDirection?: ITextFrame.ReadingDirection; } export interface JSON extends Properties { } /** * Modifiers describe a partial list of properties that can be set with values or shorthand strings. */ export type Modifiers = Partial; /** * Options for updating an ITextBoxAlignment. */ export type Update = ITextBoxAlignment | Modifiers | string | null; } /** * Represents a rectangular container for text and its formatting within a document. * * A TextFrame allows precise control over the positioning, size (width and height), * layout, and appearance of text content. */ export declare interface ITextFrame { readonly wrapped: boolean; readonly insets: Rectangle; readonly orientation: ITextFrame.Orientation; readonly autoFit: ITextFrame.Autofit; readonly fontScale: number; readonly vertical: boolean; readonly columnCount: number; readonly columnSpacing: number; readonly verticalAlignment: ITextFrame.VerticalAlignment; /** * This is different then center aligned text. */ readonly horizontalCentered: boolean; readonly lineReduction: number; readonly isSpaceFirstLastPara: boolean; /** * Returns the presetTextWarp. * TODO - implement this. */ readonly presetTextWarp: string; readonly paragraphs: ITextParagraph[]; visitParas(visitor: TextVisitor): void; visitLines(visitor: TextVisitor): void; /** * Before using the bounds of a textFrame the layout must be called. * This will then return a a clone of this ITextFrame that can be * placed and rendered. * * @param dimensions will cause the text to wrap. If bounds are not specified or only a dimension then it will not wrap. */ layout(dimensions?: Partial): ITextFrame; /** * This is the bound of a textfield include any whitespace */ readonly bounds: Readonly; /** * This is the bound of a text not include whitespace */ readonly textBounds: Readonly; readonly lines: ITextLine[]; /** * Creates a simple text frame that can be used for rendering and/or measuring. * @param text The text to use * @param allowWrap If `true` then will try to wrap on natural breaks. Defaults the the current settings. */ createTemporaryTextFrame(text: string, allowWrap?: boolean): ITextFrame; } /** * {@inheritDoc ITextFrame} * @see * ### **Interface** * * {@link ITextFrame} */ export declare namespace ITextFrame { export namespace IAlignment { export type Properties = ITextBoxAlignment.Properties; export type JSON = ITextBoxAlignment.JSON; /** * Modifiers describe a partial list of properties that can be set with values or shorthand strings. */ export type Modifiers = ITextBoxAlignment.Modifiers; /** * Options for updating an IAlignment. */ export type Update = ITextBoxAlignment.Update; } export type IAlignment = ITextBoxAlignment; /** * Represents a tab stop within a text frame or paragraph. */ export class TabStop { /** * The position (offset) of the tab stop relative to the left margin of the container, measured in points. */ offset: number; /** * The alignment of text at the tab stop. */ align: ITextFrame.TabStopAlignment; } /** * Horizontal alignment of text within a cell. */ const HorizontalAlignment: { /** * Aligned based on the data value. * Text data is left-aligned. Numbers, dates, and times are right-aligned. Boolean types are centered. */ readonly General: "general"; /** * Aligned to the left. */ readonly Left: "left"; /** * Aligned in the center. */ readonly Center: "center"; /** * Aligned to the right. */ readonly Right: "right"; /** * Aligned to the left and right margins. * Spacing will be inserted between 'words . */ readonly Justify: "justify"; /** * Each 'word' in each line of text inside the cell is evenly distributed * across the width of the cell, with flush right and left margins. * * When there is also an indent value to apply, both the left and right side * of the cell are padded by the indent value. * A 'word' is a set of characters with no space character in them. * Two lines inside a cell are separated by a carriage return. */ readonly Distributed: "distributed"; /** * The horizontal alignment is centered across multiple cells. * The number of cells is determined by the number of consecutive blank cells * that also have an alignment of CenterContinuous. */ readonly CenterContinuous: "centerContinuous"; /** * The value of the cell should be repeated across the entire width of the cell. * If blank cells to the right also have the fill alignment, they are also filled * with the value, using a convention similar to centerContinuous. */ readonly Fill: "fill"; }; export type HorizontalAlignment = typeof HorizontalAlignment[keyof typeof HorizontalAlignment]; /** * Specifies the vertical alignment of text within a text frame. */ const VerticalAlignment: { /** * Aligned to the top. */ readonly Top: "top"; /** * Aligned to the center. */ readonly Center: "center"; /** * Aligned to the bottom. */ readonly Bottom: "bottom"; /** * The vertical alignment of lines of text is distributed vertically, * where each line of text inside the cell is evenly distributed across the height of the cell, * with flush top and bottom margins. */ readonly Justify: "justify"; /** * Just like Justify, expect that all lines with a single word are centered and the last line is also distributed. */ readonly Distributed: "distributed"; }; export type VerticalAlignment = typeof VerticalAlignment[keyof typeof VerticalAlignment]; /** * Specifies the orientation in which text is displayed. */ const Orientation: { /** * Horizontal text. This is the default. */ readonly Horizontal: "horizontal"; /** * Vertical orientation. * * @remarks * Each line is 90 degrees rotated clockwise, so it goes from top to bottom; each next line is to the left from * the previous one. */ readonly Vertical: "90"; /** * Vertical orientation. * * @remarks * Each line is 270 degrees rotated clockwise, so it goes from bottom to top; each next line is to the right from * the previous one. */ readonly Vertical270: "270"; /** * Determines if all of the text is vertical; ('one letter on top of another'). * * **Not Supported** */ readonly Stacked: "stacked"; }; export type Orientation = typeof Orientation[keyof typeof Orientation]; /** * Specifies the reading order of text within a text frame. */ const ReadingDirection: { /** * The reading direction is automatically determined based on the text content. */ readonly Auto: "auto"; /** * The reading direction is from left to right. */ readonly LeftToRight: "ltr"; /** * The reading direction is from right to left. */ readonly RightToLeft: "rtl"; }; export type ReadingDirection = typeof ReadingDirection[keyof typeof ReadingDirection]; /** * The behavior of the text when it exceeds the size of the bounding box. */ const Overflow: { /** * Visible means that the text will attempt to be visible on overflow. * It can still be obscured (either z-index, or another blocking element) or fall out of the viewport. */ readonly Visible: "visible"; /** * Wrap text to keep within the left right margins but may overflow vertically. */ readonly Wrap: "wrap"; /** * Note - This is not part of the OOXML spec */ readonly Clip: "clip"; /** * Shrinks text to fit within the bounding area */ readonly Shrink: "shrink"; /** Not OOXML spec - Not support */ readonly Ellipsis: "ellipsis"; }; export type Overflow = typeof Overflow[keyof typeof Overflow]; /** * How the text should fit within the bounding area. */ const Autofit: { /** * Specifies that text within the text body should not be auto-fit to the bounding box. * Auto-fitting is when text within a text box is scaled in order to remain inside * the text box. */ readonly None: "none"; /** * Specifies that text within the text body should be normally auto-fit to the bounding box. * AutoFitting is when text within a text box is scaled in order to remain inside the text box. * *

* Example: Consider the situation where a user is building a diagram and needs * to have the text for each shape that they are using stay within the bounds of the shape. * An easy way this might be done is by using NORMAL autofit *

*/ readonly Normal: "normal"; /** * Specifies that a shape should be auto-fit to fully contain the text described within it. * Auto-fitting is when text within a shape is scaled in order to contain all the text inside. * *

* Example: Consider the situation where a user is building a diagram and needs to have * the text for each shape that they are using stay within the bounds of the shape. * An easy way this might be done is by using SHAPE autofit *

*/ readonly Shape: "shape"; }; export type Autofit = typeof Autofit[keyof typeof Autofit]; /** * Specifies the alignment of a tab stop within a text frame or paragraph. */ const TabStopAlignment: { /** * The default tab stop alignment, typically left-aligned for left-to-right text and right-aligned for right-to-left text. */ readonly Default: "default"; /** * Aligns text at the tab stop to the left. */ readonly Left: "left"; /** * Aligns text at the tab stop to the right. */ readonly Right: "right"; /** * Centers text at the tab stop. */ readonly Center: "center"; }; export type TabStopAlignment = typeof TabStopAlignment[keyof typeof TabStopAlignment]; export interface CloneableTextFrame extends ITextFrame { clone(visitor?: TextVisitor): ITextFrame; equals(other: ITextFrame): boolean; } /** * Returns a css equivalent of the horizontal text alignment. */ const toCSSHorizontalTextAlign: (align: ITextFrame.HorizontalAlignment) => TextAlign; } /** * Represents a single line with an ITextFrame */ declare interface ITextLine { readonly bullet: IBullet; readonly runs: ITextRun[]; readonly bounds: Bounds; readonly baseline: number; } /** * Represents a collection of runs with specific information about white spacing before/after. */ declare interface ITextParagraph { /** * This is used if the run doesn't have a font or in the case where there is no run (Empty line) */ readonly defaultFontSize: number; readonly defaultTabSize: number; readonly tabOverrides: ITextFrame.TabStop[]; readonly spacingBefore: number; readonly spacingAfter: number; readonly lineSpacing: number; readonly align: ITextFrame.HorizontalAlignment; readonly endParagraphSize: number; readonly indentLevel: number; readonly leadingIndent: number; readonly hangingIndent: number; readonly rightMargin: number; readonly bullet: IBullet; readonly runs: ITextRun[]; } /** * Represents a contiguous span of characters within a text frame that share the same formatting. */ declare interface ITextRun { /** * The actual text content of the run. */ readonly text: string; /** * The font name applied to the text run. * If not specified, it inherits the font name from its parent paragraph. */ readonly fontName: string; /** * The font size applied to the text run. * If not specified, it inherits the font size from its parent paragraph. */ readonly fontSize: number; /** * Indicates whether the text is bold. */ readonly bold: boolean; /** * Indicates whether the text is italicized. */ readonly italic: boolean; readonly superSub: boolean; /** * Specifies the additional spacing between characters (in ems). */ readonly letterSpacing: number; /** * Specifies the minimum font size (in points) at which character kerning will be applied. * If omitted, kerning will be applied for all font sizes down to 0 points. */ readonly kerningMin: number; /** * Specifies the capitalization style to be applied to the text during layout and rendering. * This does not affect the actual stored text content. */ readonly smallCaps: IText.SmallCaps; /** * Vertical offset of the text (as a percentage of font height), * shifting it up (positive values) or down (negative values). * This does not affect the line height. */ readonly offset: number; /** * Specifies the strikethrough style applied to the text. */ readonly strikeStyle: IText.StrikeStyle; } /** * Defines and manages themes associated to a specific document or spreadsheet. * * These themes are saved and shared with the document, ensuring a consistent look and feel across different views or users. * * `ITheme` focuses on styling the content within the document itself, such as: * - Applying schema colors (Accent1, Accent2, etc.) to elements like charts, shapes, and tables. * - Controlling font styles and colors used within the document. * - Customizing other visual aspects specific to the document's content. * * This is distinct from an `AppTheme`, which controls the styling of the application's user interface (UI) itself, * such as the toolbar, menus, and overall color scheme, and can be specific to the application or individual user preferences. */ export declare interface ITheme { /** * Human readable text describing the theme. */ getName(): string; /** * A set of colors that are used in a document. */ getColorScheme(): ITheme.IColorScheme; /** * A set of fonts that are used in a document. */ getFontScheme(): ITheme.IFontScheme; /** * This is available for functions that want to resolve themed colors * * @remarks * In most instances the scheme lookup from the style should be used unless specifically * rendering for a theme (for example a theme chooser). */ schemeLookup(): IColor.SchemeLookup; /** * If a custom theme or built in theme. */ isCustom(): boolean; /** * Parses the color using the current Theme schema (if required) * @param str The string to parse * @throws `Error` If the string does not parse to a valid color. * * @remarks * In most instances the scheme lookup from the style should be used unless specifically * rendering for a theme. */ parseColor(str: string): IColor; /** * Creates a persistable version of Themes. * @param includeInherited If true then the inherited properties will be included. */ toJSON(includeInherited?: boolean): ITheme.JSON; } /** * {@inheritDoc ITheme} * @see * ### **Interface** * * {@link ITheme} */ export declare namespace ITheme { export interface ColorSchemeJSON extends Partial> { } /** * Built a set of colors from the theme. * @remarks * This api will undergo cleanup. */ const buildPalette: (colors: IColor.DefinitionWithLabel[], schemeLookup: IColor.SchemeLookup, map: Map, mapRGB: Map) => IColor.DefinitionWithLabel[]; export interface ColorSchemeProperties { dk1: C; lt1: C; dk2: C; lt2: C; accent1: C; accent2: C; accent3: C; accent4: C; accent5: C; accent6: C; hlink: C; folHlink: C; name: string; } /** * Represents a color scheme interface that extends the properties of ColorSchemeProperties. * * @template C - The type of the color, defaults to IColor.Serializable. */ export interface IColorScheme { /** * Gets the first dark color in the scheme. * * @returns {IColor} The first dark color. */ getDk1(): IColor; /** * Gets the first light color in the scheme. * * @returns {IColor} The first light color. */ getLt1(): IColor; /** * Gets the second dark color in the scheme. * * @returns {IColor} The second dark color. */ getDk2(): IColor; /** * Gets the second light color in the scheme. * * @returns {IColor} The second light color. */ getLt2(): IColor; /** * Gets the first accent color in the scheme. * * @returns {IColor} The first accent color. */ getAccent1(): IColor; /** * Gets the second accent color in the scheme. * * @returns {IColor} The second accent color. */ getAccent2(): IColor; /** * Gets the third accent color in the scheme. * * @returns {IColor} The third accent color. */ getAccent3(): IColor; /** * Gets the fourth accent color in the scheme. * * @returns {IColor} The fourth accent color. */ getAccent4(): IColor; /** * Gets the fifth accent color in the scheme. * * @returns {IColor} The fifth accent color. */ getAccent5(): IColor; /** * Gets the sixth accent color in the scheme. * * @returns {IColor} The sixth accent color. */ getAccent6(): IColor; /** * Gets the hyperlink color in the scheme. * * @returns {IColor} The hyperlink color. */ getHlink(): IColor; /** * Gets the followed hyperlink color in the scheme. * * @returns {IColor} The followed hyperlink color. */ getFolHlink(): IColor; } /** * Interface representing a font scheme. */ export interface IFontScheme { /** * Gets the name of the font scheme. * @returns The name of the font scheme. */ getName(): string; /** * Gets the major font of the font scheme. * @returns The major font of the font scheme. */ getMajorFont(): string; /** * Gets the fallback fonts for the major font. * @returns An array of fallback fonts for the major font. */ getMajorFallbacks(): readonly string[]; /** * Gets the minor font of the font scheme. * @returns The minor font of the font scheme. */ getMinorFont(): string; /** * Gets the fallback fonts for the minor font. * @returns An array of fallback fonts for the minor font. */ getMinorFallbacks(): readonly string[]; } export interface FontSchemeProperties { majorFont: string; majorFallbacks: string[]; minorFont: string; minorFallbacks: string[]; name: string; } export interface FontSchemeJSON extends Partial { } export interface JSON { name: string; fonts?: ITheme.FontSchemeJSON; colors?: ITheme.ColorSchemeJSON; darkColors?: ITheme.ColorSchemeJSON; } } /** * A collection of themes. */ export declare interface IThemeCollection extends ICollection { /** * Add or update a theme. * * @param theme The new theme. * @returns The original theme * * @remarks * Case insensitive; for duplicate detection purposes. */ setCustomTheme(theme: ITheme): ITheme | null; /** * Returns the theme for the given name. * * @remarks * Will try to return: * 1. The custom theme for the name * 2. The builtin theme for the name. * 3. nul if it doesn't exist. */ getByName(name: string): ITheme | null; /** * Returns all themes that match the filter criteria. * * @param options {@link IThemeCollection.GetItemsOptions} * * @remarks * * If no filter criteria is provided, all items will be returned. * * Generates a new array so this can be mutated without affecting the internal state. */ getItems(options?: IThemeCollection.GetItemsOptions): ITheme[]; /** * Remove a custom theme. * * @param theme A {@link Theme} or string. * @returns `true` if the Theme was removed. */ deleteCustomTheme(theme: ITheme | string): ITheme | null; /** * Returns the name of the default Theme. * * @returns A theme that has been set as the Default using {@link setDefaultTheme}. */ getDefaultTheme: () => ITheme; /** * Set the new default theme. * * @returns The previous default theme. */ setDefaultTheme: (theme: ITheme) => ITheme; } /** * {@inheritDoc IThemeCollection} * * @see * ### **Interface** * * {@link IThemeCollection} */ export declare namespace IThemeCollection { export type JSON = ITheme.JSON[]; export interface GetItemsOptions extends ICollection.GetItemsOptions { /** * @defaultValue `IThemeCollection.BuiltInFilterType.All` */ type?: BuiltInFilterType; /** * Allows for the filter to return a specific theme even if not in the list. */ selected?: ITheme; } const BuiltInFilterType: { readonly BuiltIn: "builtIn"; readonly All: "all"; readonly Custom: "custom"; }; export type BuiltInFilterType = typeof BuiltInFilterType[keyof typeof BuiltInFilterType]; } /** * Objects that implement this interface have ACID properties. */ export declare interface ITransaction { /** * Begin a transaction with self contained, non-eventing updates. * * @remarks * `description` is useful for debugging and logging. * * Transactions are treated as a stack so with fifo remove. When the final commit is applied * to global only the final transaction will be maintained. * * @param options The description of the transaction or options. * @param onClose A callback for when the transaction is closed (due to either a commit or rollback). */ beginTransaction(options?: ITransaction.StoreOperationOptions, onClose?: ITransaction.CloseCallback): ITransaction; /** * Commit the transaction and all children transactions to the parent transaction. * * @param options A final description or options to apply on commit. */ commit(options?: ITransaction.StoreOperationOptions): ITransaction; /** * Discard all changes and children transaction changes. */ rollback(): ITransaction; /** * If root transaction will return self. */ getParent(): ITransaction; /** * A unique id for this transaction. This will be the same id for all sub transactions. */ getId(): string; /** * Describes the current transaction. */ getDescription(): string; /** * 0-Based depth of the current transaction. If 0 then it's globally available. */ getDepth(): number; /** * Returns the state associated to a record for the current transaction or globally if there are no open transactions. * * @param model The `ITransactional` object. */ getState(model: any): Readonly; /** * Update the state for a record. * * @param model * @param state */ updateState(model: any, state: (Readonly> | ((prev: Readonly) => Readonly))): STATE; /** * All states in the current transaction. */ getStates(): Map; /** * Returns the view associated with this transaction. */ getView(): Record | null; } /** * {@inheritDoc ITransaction} * @see * ### **Interface** * * {@link ITransaction} */ export declare namespace ITransaction { /** * Objects that implement this interface allow for batch operations. */ export interface ITransactional { /** * A unique identifier for the record. This will never change. * * @remarks * This enables the record to be identified across transactions and users in a collaborative environment. */ getUUID?(): string; /** * Provides a mechanism to perform a set of operations in a batch. * * @param callback A callback that performs multiple operations all within the same transaction. * @param options Description of the operation or additional options. Used for tracking undo/redo and history. Default Value `User Operation`. */ doBatch(callback: (commit: ITransaction.ICommit) => R | Promise, options?: string | ITransaction.OperationOptions): R | Promise; /** * Batches all 'transactional' changes until they have all be committed or rolled back. * * @remarks * Any changes that are made to this object will be reflected in the local record but * not committed to the transactional store until the batch is popped. * * Useful for operations that are longer running but generally not recommended * as it keeps a transaction open. {@link doBatch} is the preferred option. * * @param options Description of the operation or additional options. Used for tracking undo/redo and history. Default Value `User Operation`. */ beginCommit(options?: string | ITransaction.OperationOptions): ITransaction; /** * Close the record and cleans resources. Can't be undone. */ close(): void; /** * Returns `true` if no more operations are allowed. */ isClosed(): boolean; } export interface ICommit { /** * Returns the unique identifier for the commit. */ getId(): string; /** * A human readable description of the commit. */ getDescription(): string; /** * Additional meta information set during open and close. */ getMeta(): Readonly>; /** * The author of the commit. */ getAuthor(): any; /** * The time the commit was created. */ getTimestamp(): number; /** * Returns the operation that was used to create the commit. * * @remarks * It is possible that a batch operation was used to create the commit. */ getOperation(): Readonly; } /** * When the first transaction this will contain the name of parameters of the input */ export interface Operation { /** * The name of the operations. * * @remarks * This name should be unique per model type. This is used for audit and collaboration. */ name: string; /** * The parameters for the operation. */ params?: PARAMS; } export interface RestoreOptions { /** * If provided restore will only select if the view matches the id. * * @defaultValue undefined - Any view will be selected. * * @remarks * This is used for collaboration. */ viewId?: string; /** * If true will force the restore even if there are open transactions. * * @defaultValue false */ force?: boolean; } export interface StoreConstructorOptions { /** * The creator of the transactions. */ author?: string; /** * If true will try to default to synchronous eventing. * * @defaultValue 'setDefaultSync' */ sync?: boolean; /** * If true will not track changes for restoring. * @defaultValue false * * @remarks * Useful for creating temporary models that don't need to be tracked. */ transient?: boolean; } export interface IStore { /** * Add a listener to listen for changes. */ addListener(listener: ITransaction.IListeners): IListener.Remove; /** * Add a listener for state changes to a specific model. * * @param model * @param listener */ addStateListener(model: any, listener: ITransaction.IStateListener): IListener.Remove; /** * Returns the last commits of commits. * @param commitId The commit id to start from. * @param max - The maximum number of commits to return. *default* `100`. */ getLog(commitId: string, max?: number): ITransaction.ICommit[]; /** * Returns the total number of commits. */ getCommitCount(): number; /** * Returns the current commit. * * @remarks * Returns either the last completed commit or the current pending. */ getCurrentCommit(): ITransaction.ICommit; /** * Returns true if there is an open transaction. */ isOpenTransaction(): boolean; /** * Returns the current view associated with the entire commit. * * @remarks * Will return `null` if there is no open transaction. */ getPendingView(): Record | null; /** * Returns the current state associated to a model for the current transaction or globally if there are no open transactions. * * @param model The `ITransactional` object. */ getState(model: any): Readonly; /** * Begin a transaction using the current commit. * @param options * @param onClose */ beginCommit(options?: ITransaction.StoreOperationOptions, onClose?: ITransaction.CloseCallback): ITransaction; /** * Used by `ITransactional` objects. Both to expose `doBatch` and to implement * their own internal transactions. */ doBatch(callback: (commit: ITransaction.ICommit) => R | Promise, options?: ITransaction.StoreOperationOptions, onClose?: ITransaction.CloseCallback): Promise | R; /** * Remove model from the commit. * * @param model The model to remove. * @returns A flag indicating if anything was removed. * * @remarks * Fires remove event. */ remove(model: any): boolean; /** * Set the state to a previous history point. * * @param commitId * @param options * * @remarks * Can be any previous restore point available in before the current commit * or after the current commit. */ restore(commitId: string, options?: ITransaction.RestoreOptions): ITransaction.ICommit; /** * Revert is similar to restore in that it moves the state but it applies view * updates in reverse order. * * @param commitId * @param options * * @remarks * Can be any previous restore point available in before the current commit * or after the current commit. */ revert(commitId: string, options?: ITransaction.RestoreOptions): ITransaction.ICommit; } /** * Listener interface for TransactionStore */ export interface IListeners { /** * Called when a commit is started. * * @param commit The commit handle. * * @remarks * This allows for additional transactional changes to be made such as transaction listeners. */ onCommitStart?(commit: ITransaction.ICommit): void; /** * Called after a successful commit. * * @param commit * * @remarks * * A rollback will not trigger this event. * * A restore/revert will trigger this event. */ onCommitEnd?(commit: ITransaction.ICommit): void; /** * Called if the commit changes for any reason. * * @param commit */ onCommitChange?(commit: ITransaction.ICommit): void; } export interface IStateListener { /** * Called synchronously at the beginning of a transaction before a record is changed. * * @remarks * If this throws an exception then all records within the transaction will not * be applied. */ onBeforeCommitStart?(state: STATE, view: VIEW, commit: ITransaction.ICommit): void; /** * Called during a transaction. * * @remarks * This is when changes should be applied. The view will only be provided if restore is used. */ onBeforeCommitEnd?(state: STATE, view: VIEW, commit: ITransaction.ICommit): void; /** * Called after the transaction. This is generally used for cleanup or ui notification. */ onAfterStateChange?(state: STATE, view: VIEW, commit: ITransaction.ICommit, isRevert: boolean, isRestore: boolean): void; /** * Called if the restore or revert is called. This is called asynchronously As should only have passive actions. */ onRestoreOrRevert?(state: STATE, view: VIEW, commit: ITransaction.ICommit, isUndo: boolean): void; /** * Called when a model is removed from the transaction. */ onClose?(commit: ITransaction.ICommit): void; } /** * Called when a transaction is closed. */ export interface CloseCallback { (transaction: ITransaction, isRollback: boolean, options: ITransaction.OperationOptions): void; } /** * Options for Operations that change the state. */ export interface OperationOptions { /** * A human description. * * @defaultValue 'determined by the set operation and locale' */ description?: string; /** * If `true` or set then this will select the affect item after the transaction is complete. * * @remarks * If this is set to `true` then any restore will also select. */ autoSelect?: boolean | ITypes.SelectOptions; } /** * Options for operations with the store. */ export interface StoreOperationOptions extends OperationOptions { /** * If set to `true`, prevents further transactions from being pushed onto the stack * until the current transaction is complete. Once the current transaction is either * committed or rolled back, this restriction is automatically lifted. * * @defaultValue false */ preventFurtherTransactions?: boolean; /** * If set to `true`, The commit will not create a new snapshot but instead merge with the existing. * * @defaultValue false * * @remarks * * Ths is used for internal listeners and historical corrections. * * This is only read for the top transaction. * * This should generally be avoided as the audits and history are lost. */ forceAmend?: boolean; /** * Stored with the commit. */ meta?: Record; /** * Used to record audit points. */ operation?: ITransaction.Operation; viewAfter?: VIEW | ((prev: VIEW) => VIEW); viewBefore?: VIEW | ((prev: VIEW) => VIEW); } } /** * A collection of types. */ export declare namespace ITypes { /** * Associate an optional value with a {@link RangeCoords}. */ export interface RangeCoordValue extends RangeCoords { value?: T; } /** * Associate an option value with a {@link RunCoords}. */ export interface RunCoordValue extends RunCoords { value?: T; } /** * Associate an option value with a {@link Bounds}. */ export interface BoundsValue extends Bounds { value?: T; } /** * Options for controlling selection behavior, including scrolling and focus. */ export interface SelectOptions { /** * If `true` or if a valid `ScrollIntoViewOptions` object is provided, * the selected element will be scrolled into view. * * @remarks * - If a `ScrollIntoViewOptions` object is provided, it will control the exact scrolling behavior. * - If `false` (or omitted), the selected element will not be scrolled into view. * * @defaultValue false */ scrollIntoView?: boolean | globalThis.ScrollIntoViewOptions; /** * If `true`, the selected element will automatically receive focus after being selected. * * @remarks * - If `false` (or omitted), the element will not automatically receive focus. * * @defaultValue false */ autoFocus?: boolean; } } /** * An `IWorkbook` represents a collection of {@link ISheet | sheets}, along with shared resources. * * This interface provides methods for accessing its elements and event handling. * * @remarks * Most interactions with a {@link IWorkbook | workbook} or {@link ISheet | sheet} are done through a * {@link ICellRange | workbook range}. * * @see * * {@link getRange} - For interacting with cell values and formatting on a single {@link ISheet | sheet}. * * {@link getSheets} - For managing {@link ISheet | sheet}. * * {@link getNames} - For managing items with defined names. */ export declare interface IWorkbook extends ITransaction.ITransactional, IListener.ISource { /** * Returns the collection of sheets within the workbook. */ getSheets(): ISheetCollection; /** * Adds a new sheet to the workbook. * * @remarks * This is a convenience method that wraps `getSheets().add`. */ addSheet(options?: ISheetCollection.AddOptions | string | number): ISheet; /** * Returns the sheet at the given offset. * * @param index A 0-based index of the sheet. * @param visibility The visibility of the sheet. */ getSheetAt(index: number, visibility?: ISheet.Visibility): ISheet; /** * Returns the sheet for the given name. * * @param name The name of the sheet. * @param visibility The visibility of the sheet. */ getSheet(name: string, visibility?: ISheet.Visibility): ISheet; /** * Returns the currently active sheet within the workbook. */ getSelectedSheet(): ISheet; /** * Returns the currently active sheet index within the workbook. */ getSelectedSheetIndex(): number; /** * Returns ranges scoped to a sheet. * * @param address Address of the ranges. * @param options {@link ICellRange.GetRangeOptions} * * @remarks * When accessing ranges from the `IWorkbook` ranges include a sheet name. * This enables cross-sheet references when working at the workbook level. * * Some examples of cross-sheet reference are: * * - Linking data and formulas across multiple sheets. * * - Consolidating data from different sheets for analysis or reporting. * * - Performing calculations or comparisons that involve values from multiple sheets. */ getRange(address: ICellRange.Address, options?: ICellRange.GetRangeOptions): ICellRange; /** * Returns an a set of ranges including sheet names. * * @param address Address of the ranges. * @param options {@link ICellRange.GetRangeOptions} * * @remarks * @see {@link IWorkbook.getRange} */ getRanges(address: ICellRanges.Address, options?: ICellRange.GetRangeOptions): ICellRanges; /** * Returns a range of cells for the current selection. */ getSelectedRange(options?: ICellRange.GetRangeOptions): ICellRange; /** * Returns ranges of cells for the current selection. */ getSelectedRanges(options?: ICellRange.GetRangeOptions): ICellRanges; /** * Returns the selected cell. */ getSelectedCell(): ICell; /** * Search the entire Workbook. * * @param options The text to search for or {@link ICellRange.FindOptions} * * @remarks * Searches all sheets. * * @see * {@link ICellRange.find} */ find(options: string | ICellRange.FindOptions): Iterator; /** * Replace all items in the iterator * * @param cells An iterator of cells to replace. * @param replace The {@link ICell.Update} or a callback to replace with. * @param options {@link IWorkbook.ReplaceOptions} */ replace(cells: Iterator, replace: ICell.Update | ((original: ICell) => ICell.Update), options?: IWorkbook.ReplaceOptions): IWorkbook.ReplaceResults; /** * Returns the next sheet in the sheets collection. If the last one it will return the first. * * @remarks * If there is only 1 sheet this will return the current sheet. */ getNextSheet(index: number): ISheet; /** * Returns the previous sheet in the sheets collection. If the first one it will return the last. * * @remarks * If there is only 1 sheet this will return the current sheet. */ getPreviousSheet(index: number): ISheet; /** * Given the name return a valid name that closely matches. * * @param sheetName The string to validate. */ findValidSheetName(sheetName: string): string; /** * Indicate if the current character is a valid character for a sheetName. * * @param character The string to validate. */ isValidSheetNameCharacter(character: string): boolean; /** * Returns the current view settings. * * View settings determine how specific workbook level elements are displayed but does not affect the underlying data itself. */ getView(): IWorkbookView; /** * Views have their own lifecycle because in a collaborative environment each user can have their own view. */ setView(view: IWorkbookView): this; /** * Returns the current `IStyleCollection` associated with this Workbook. */ getStyles(): IStyleCollection; /** * Returns the current shared resources. */ getResources(): IResourceCollection; /** * Returns the current shared resources. */ getStrings(): IStringCollection; /** * Returns the current shared resources. */ getTransactions(): ITransaction.IStore; /** * Get the current theme. */ getTheme(): ITheme; /** * Set the current theme. * * @remarks * * If `null` sets back to the default theme. * * Does not fire a theme updated event. */ setTheme(theme: ITheme | null): ITheme; /** * Returns the display name for the workbook. * * @remarks * This may be null */ getName(): string | null; /** * Set the name for the workbook. */ setName(name: string | null): IWorkbook; /** * Is date resolution 1904 instead of 1900 based. * * @see * {@link https://support.microsoft.com/en-us/office/date-systems-in-excel-e7fe7167-48a9-4b96-bb53-5612a800b487} */ isDate1904(): boolean; /** * Determine if dates should be 1904 instead of 1900 based. * * @param date1940 - default value `false` * * @see * {@link IWorkbook.isDate1904} */ setDate1904(date1940: boolean): this; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: IWorkbook.IListeners, options?: IListener.Options): IListener.Remove; /** * Returns the protection object for the workbook. */ getProtection(): IWorkbookProtection; /** * Returns the named collection for the workbook. * * These are sorted/filtered by type then by name. */ getNames(): INamedCollection; /** * Returns the {@link ICalculation} for the workbook. */ getCalculation(): ICalculation; /** * Returns any user defined functions stored with the workbook. */ getScripts(): IScript; /** * Serialize the workbook to a JSON. * * @param ignoreData If `true` only meta data about the workbook will be saved. */ toJSON(ignoreData?: boolean): Promise; /** * Returns any custom workbook options that are provided in constructor. */ readonly options: IWorkbook.ConstructorOptions; /** * Close the workbook and release any resources. * * @remarks * No further operations are allowed after a close. */ close(): void; /** * Indicates if the model has been closed. */ isClosed(): boolean; /** * For runtime type checking. */ readonly isIWorkbook: true; } /** * {@inheritDoc IWorkbook} * @see * ### **Interface** * * {@link IWorkbook} */ export declare namespace IWorkbook { /** * Represents the different ways to identify ranges within a workbook, including the sheet context. * * Accepts: * - `ICellRange` * - A parsable `string` representing a range address, optionally including the sheet name (e.g., "Sheet1!A1:B2"). * - A partial `IRange.FixableCoords` object (specifying at least some of the range boundaries), * which may include the `sheetName` property to identify the sheet. * - `IWorkbook.CellAddress` (representing a single cell within the workbook), * which may includes the `sheetName` property to identify the sheet. * * @example * ```typescript * const address1: Address = "Sheet1!A1:B2"; // A1 notation with sheet name * ``` * * @remarks * This leverages {@link ICellRange.Address} and adds the sheet name. */ export type RangeAddress = ICellRange | string | Partial | IWorkbook.CellAddress; /** * Represents the different ways to identify multiple ranges within a workbook, * including their sheet context. * * Accepts: * - `ICellRanges` * - A parsable `string` containing multiple range addresses, optionally including sheet names, * separated by commas (e.g., "Sheet1!A1:B2,Sheet2!C3:D4"). * - An array of `IWorkbook.RangeAddress` objects, each representing a single range within a workbook. * * @example * ```typescript * const address1: IWorkbook.RangesAddress = "Sheet1!A1:B2,Sheet2!C3:D4"; // String with multiple ranges and sheet names * ``` * * @remarks * This extends {@link ICellRanges.Address} to support multiple values. */ export type RangesAddress = ICellRanges | string | IWorkbook.RangeAddress | readonly IWorkbook.RangeAddress[]; /** * Represents a single cell a workbook. */ export type CellAddress = IRange.FixableCellCoords | string; /** * IListener interface for {@link IWorkbook} events. */ export interface Events { /** * Called when the sheet collections has changed have changed. */ onSheetsChange?(source: IWorkbook): void; /** * Called when the workbook theme has changed. */ onThemeChange?(source: IWorkbook): void; /** * Called when the workbook protection has changed. * * @remarks * This is different from the sheet protection. */ onProtectionChange?(source: IWorkbook): void; /** * Called before load. If any exception is thrown this * exception will be returned to the client and delete will fail. */ onBeforeLoad?(source: IWorkbook, json: IWorkbook.JSON): void; /** * Called after load. */ onLoad?(source: IWorkbook): void; /** * Called before load. If any exception is thrown this * exception will be returned to the client and delete will be aborted. */ onBeforeSave?(source: IWorkbook): Promise | void; /** * Called after save. */ onSave?(source: IWorkbook, json: IWorkbook.JSON): void; /** * Called when the workbookView changes. * * @param source {@link IWorkbook} */ onViewChange?(source: IWorkbook): void; /** * Called when the name changes. */ onNameChange?(source: IWorkbook): void; /** * Called when the scripts associated with the workbook have change. */ onScriptsChange?(source: IWorkbook): void; /** * Request that the sheet become brought to the front. * * @returns A promise indicating that the sheet has been rendered. * * @remarks * This should only be handled by one consumer. */ onRequestSelect?(source: IWorkbook, sheet: ISheet): Promise; /** * Called when the selection has changed. * * @param source The workbook instance. */ onSelectionChange?(source: IWorkbook): void; /** * Called when the workbook is closed. */ onClose?(source: IWorkbook): void; /** * Called when the state has been updated due to a undo/redo and a rerender is required. */ onInvalidated?(source: IWorkbook): void; } export interface IListeners extends IListener.Callbacks { } /** * Options for the replace operation. */ export interface ReplaceOptions extends ITransaction.OperationOptions { /** * The maximum number of cells to replace. * @defaultValue false */ maxCount?: number; /** * The orientation to replace. */ orientation?: IRange.Orientation; } export interface ReplaceResults { /** * The number of cell replaced. */ count: number; /** * The last cell replaced. */ last: ICell; } export interface JSON { sheets: SheetRefJSON[]; styles?: IStyleCollection.JSON; resources?: IResource.JSON[]; strings?: string[]; people?: IComment.PersonJSON[]; view?: IWorkbookView.JSON; theme?: ITheme.JSON; names?: INamedCollection.JSON; scripts?: Record; calc?: ICalculation.JSON; protection?: IWorkbookProtection.JSON; date1904?: boolean; } /** * Callback to allow for custom `ISheets`. The Workbook provides a default implementation. */ export interface CreateSheetCallback { ( /** * Options used for creating the Sheet instance. */ options: ISheet.ConstructorOptions, /** * The name of the new sheet. */ name: string, /** * The location of the sheet. */ index: number, /** * @defaultValue ISheet.Visibility.Visible */ visibility: ISheet.Visibility): ISheet; } /** * Options available when creating an IWorkbook. */ export interface ConstructorOptions extends ICellContainerOptions { /** * Hook to allow for custom sheet creation. */ createSheetCallback?: CreateSheetCallback; /** * Returns a human readable sheet name given a 0-based index. * * @defaultValue `Sheet${index+1}` */ createSheetNameCallback?: (index: number) => string; /** * The initial name for the workbook. */ name?: string | null; /** * Returns a valid name for the workbook. * * @param name The name to validate. * @returns The valid name. This may be different from the name provided. * @throws Error if the name is not valid. * * @remarks * This is not called if the name is null or for the initialName if provided. */ validateWorkbookName?: (name: string) => string | null | void; /** * A theme for the workbook. */ theme?: ITheme; /** * Load from JSON. */ json?: IWorkbook.JSON; } /** * Used for persisting metadata about a `ISheet`. */ export interface SheetRefJSON { /** * A unique name for the sheet. */ name: string; /** * @defaultValue ISheet.Visibility.Visible */ visibility?: ISheet.Visibility; /** * The actual sheet. */ sheet?: ISheet.JSON; } } /** * Interface representing protection settings for a workbook. * This interface allows for getting and setting passwords, * managing structure and window locks, and handling revision protection. */ export declare interface IWorkbookProtection extends IProtection { /** * Checks if the workbook structure is locked. * Locking the structure prevents changes like adding or deleting sheets. * * @returns `true` if the structure is locked, `false` otherwise. */ isStructureAllowed(): boolean; /** * Checks if workbook windows are locked. * Locking the windows prevents changes to window position and size. * * @returns `true` if windows are locked, `false` otherwise. */ isWindowsAllowed(): boolean; /** * Checks if workbook revisions are locked. * Locking revisions prevents changes to the workbook without the revision password. * * @returns `true` if revisions are locked, `false` otherwise. */ isRevisionAllowed(): boolean; } /** * {@inheritDoc IWorkbookProtection} * @see * ### **Interface** * * {@link IWorkbookProtection} */ export declare namespace IWorkbookProtection { export interface IListener { /** * Called when the protection has changed collections has changed have changed. */ onChange?(source: IWorkbookProtection): void; } export interface Properties extends IProtection.JSON { revisionsPassword?: string; structure?: boolean; windows?: boolean; revision?: boolean; } export interface JSON extends IProtection.JSON { } } /** * View settings for a single workbook. * */ export declare interface IWorkbookView { /** * Shows the visibility of the formula bar. */ setShowFormulaBar(newValue: boolean): this; /** * @see {@link IWorkbookView.setShowFormulaBar} */ isShowFormulaBar(): boolean; /** * Shows the workbook tabs. * * @defaultValue true; */ setShowTabs(newValue: boolean): this; /** * @see {@link IWorkbookView.setShowTabs} */ isShowTabs(): boolean; /** * Specifies ratio between the workbook tabs and the horizontal scroll bar. * * @defaultValue 600 * * @remarks * This is expressed as a percent * 1000. */ setTabRatio(newValue: number): this; /** * @see {@link IWorkbookView.setTabRatio} */ getTabRatio(): number; /** * show the horizontal scrollbar. * * @defaultValue true */ setShowHorizontalScrollbar(newValue: boolean): this; /** * @see {@link IWorkbookView.setShowHorizontalScrollbar} */ isShowHorizontalScrollbar(): boolean; /** * Show the vertical scrollbar. * * @defaultValue true */ setShowVerticalScrollbar(newValue: boolean): this; /** * @see {@link IWorkbookView.setShowVerticalScrollbar} */ isShowVerticalScrollbar(): boolean; /** * Show the status bar. * @defaultValue true */ setShowStatusBar(newValue: boolean): this; /** * @see {@link IWorkbookView.setShowStatusBar} */ isShowStatusBar(): boolean; /** * The id of of the activeSheet. * * @remarks * This is NOT the index of the sheet but instead the id (1 based) * If the sheets have been reordered then these won't match. */ setActiveSheetId(newValue: number | null): this; /** * @see {@link IWorkbookView.setActiveSheetId} */ getActiveSheetId(): number | null; /** * Add Listeners. * * @see * {@link IListener.ISource.addListeners} */ addListeners(listeners: IWorkbookView.IListeners, options?: IListener.Options): IListener.Remove; /** * Saves the current state to JSON. */ toJSON(): IWorkbookView.JSON | null; } /** * {@inheritDoc IWorkbookView} * @see * ### **Interface** * * {@link IWorkbookView} */ export declare namespace IWorkbookView { export interface Events { /** * Called when the workbookView changes. * * @param source {@link IWorkbookView} */ onViewChange?(source: IWorkbookView): void; } export interface IListeners extends IListener.Callbacks { } export interface ConstructorOptions { /** * The state to load */ json?: IWorkbookView.JSON; } export interface Properties { /** {@inheritDoc IWorkbookView.setShowFormulaBar} */ showFormulaBar?: boolean; /** {@inheritDoc IWorkbookView.setShowTabs} */ showTabs?: boolean; /** {@inheritDoc IWorkbookView.setTabRatio} */ tabRatio?: number; /** {@inheritDoc IWorkbookView.setShowHorizontalScrollbar} */ showHorizontalScrollbar?: boolean; /** {@inheritDoc IWorkbookView.setShowVerticalScrollbar} */ showVerticalScrollbar?: boolean; /** {@inheritDoc IWorkbookView.setShowStatusBar} */ showStatusBar?: boolean; /** {@inheritDoc IWorkbookView.setActiveSheetId} */ activeSheetId?: number | null; } export interface JSON extends Properties { } } declare type JavaScriptDate = Date; /* Excluded from this release type: leastSquaresSlopeAndIntercept */ /** * @hidden */ export declare interface LicenseDetails { getLicensee(): string | null; getExpiration(): Date | null; getDomains(): string[]; getCpuCount(): number; isEval(): boolean; isValidFor: (feature: string) => boolean; getDeveloperCount(): number; getType(): string; getExceptions(): string[]; hasExceptions(): boolean; isValid(): boolean; getFeatures(): Readonly>; getKeyFrom(): string; getBuildVersion(): string; getBuildDate(): string; } /** * LicenseManager is used to manage license keys at runtime. * * License keys can be generated by visiting {@link https://www.sheetxl.com/docs/guides/getting-started/license-key | License Keys}. */ export declare const LicenseManager: LM; /** * Manages Listeners * * @remarks * A few rules to know: * * * non-transactional listeners are fired after the commit end and are conflated. */ declare class ListenerEmitter { protected _transactions: ITransaction.IStore; protected _transactionsRemoveListener: IListener.Remove; protected _src: SOURCE; protected _listeners: EntrySet; protected _pending: Pending[]; constructor(src: SOURCE, transactions?: ITransaction.IStore); /** {@inheritDoc IListener.ISource.addListeners} */ addListeners(listeners: IListener.Callbacks, options?: IListener.Options): IListener.Remove; protected _doNotify(listeners: IListener.Callback[], removes?: IListener.Remove[], options?: NotifyOptions, fired?: Set>): Promise; /** * Notify listeners. */ notify(key: keyof EVENTS, options?: NotifyOptions): void | Promise; close(): void; } declare class LM { constructor(); /** * Set the license key provided by SheetXL. * @remarks * The license key can also be provided via a file named `sheetxl.lic` in the root of the web server. * * @param licenseKey The license key as a string. * @param force If set to `true` will replace an existing key. * * @see * {@link https://www.sheetxl.com/docs/guides/getting-started/license-key | License Keys} */ setLicenseKey(licenseKey: string, force?: boolean): Promise; private _validate; private _printBanner; private _printDetails; private _doPrint; private _print; getDetails(): Promise; /** * Print just the banner */ print(expanded?: boolean): Promise; wasPrinted(): boolean; /** * Disable printing of the banner for a period of time. * * @param The reason for suppressing the license * * @remarks * Call this to disable the license key watermark for a period of time. * This is useful for testing purposes. */ suppressPrint(reason: string): void; /** * Print just the banner */ printBanner(): Promise; /** * Print the current license details. */ printDetails(expanded?: boolean, ignoreExceptions?: boolean): Promise; /** * Generate a unique node ID. * @returns The generated node ID. * * @remarks * This will return null in the browser. */ getNodeId(): Promise; } /** * MergeEntry */ declare class MergeEntry { private _c; private _tvTl; constructor(coords: IRange.Coords, tvTl?: (coords: IRange.Coords) => Scalar | null); /** * The cell value at the top left. * We track this because we want a quick way to access * the coords state during overflow scenarios. */ tvTl(): Scalar | null; getCoords(): IRange.Coords; } declare interface MergeRunOptions { startOffset?: number; endOffset?: number; onMerge?: (a: T, b: T, sizeA: number, sizeB: number) => T | undefined | null; } /** * Merges runs. Runs must be sorted; {@link sortRuns} */ declare function mergeRuns(runs: ITypes.RunCoordValue[], options?: MergeRunOptions): ModifiedRuns; /** * Returns the minimum bounds for all the containing points. */ declare const minBoundingRect: (points: Point[]) => Bounds; declare interface ModifiedRuns { preceding: ITypes.RunCoordValue[]; modified: ITypes.RunCoordValue[]; trailing: ITypes.RunCoordValue[]; } declare const nocToPx: (noc: number, mdw: number) => number; declare interface NotifierOptions { isTransactional?: boolean; timeStamp?: number; trigger?: string; } declare interface NotifierOptions_2 { isDataChange?: boolean; isTransactional?: boolean; isUndo?: boolean; trigger?: string; from?: ICellRanges; to?: ICellRange; timeStamp?: number; } declare interface NotifyOptions { params?: T | null; source?: any; async?: boolean; transactional?: boolean; } /** * Returns Date.now() rounded to a nearest time. * * @param precision The precision of time. Set to 1 if exact. * @defaultValue The nearest minute. */ declare const nowWithPrecision: (precision?: number) => Date; /** * Capabilities for defining and applying number formats to cells. * * Number formats control how numeric values are displayed in a spreadsheet, * enabling users to present data in various ways such as currency, percentages, dates, and more. * * Key features include: * - Applying built-in number formats (e.g., currency, date, percentage). * - Creating custom number formats using format codes. * - Setting and retrieving number formats for cells or ranges. */ export declare namespace NumberFormat { export type Parsed = Parsed; /** * Represents the built-in categorization of a number format, or 'Custom' if the format is not recognized as a built-in type. * * Excel has the following: * @see * {@link https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1} */ export type Type = typeof Type[keyof typeof Type]; const Type: { readonly General: "General"; readonly Number: "Number"; readonly Currency: "Currency"; readonly Accounting: "Accounting"; readonly ShortDate: "Short Date"; readonly LongDate: "Long Date"; readonly MediumDate: "Medium Date"; readonly ShortTime: "Short Time"; readonly MediumTime: "Medium Time"; readonly LongTime: "Long Time"; readonly Comma: "Comma"; readonly Percentage: "Percentage"; readonly Fraction: "Fraction"; readonly Scientific: "Scientific"; readonly Text: "Text"; readonly Special: "Special"; readonly Custom: "Custom"; }; /** * This interface returns rendering information about the formatted text based on the numberFormat. * * https://customformats.com/ * https://exceljet.net/custom-number-formats * https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1 */ const Parser: Readonly<{ formatValue: (format: string, value: string | number, options?: ParserOptions) => string; isFractionFormat: (format: string) => boolean; adjustDecimalPlaces: (format: string, amount: number) => string; }>; export type ParserOptions = ParserOptions; const Styles: Styles; export type Styles = Styles; export type ParsedCharPlaceHolder = ParsedCharPlaceHolder; const ParseRunType: { readonly Text: "text"; readonly Repeat: "repeat"; readonly Spacing: "spacing"; }; export type ParsedRun = ParsedRun; export type ParsedRuns = ParsedRuns; export type Style = Style; export type StyleConfig = StyleConfig; } /** * Converts a number to alphabet. * @param i The number to stringify */ declare const numberToAlphabet: (i: number) => string; declare namespace OverlappingRange { interface IteratorOptions { /** * The direction of the scan. * @defaultValue RangeOrientation.Row */ orientation?: RangeOrientation; /** * Set iterator to increment by cells within an intersection. * * @defaultValue false * * @remarks * Depending on the range intersect it is possible that some scan lines will be duplicated. * This is desired as it makes merging ranges easier/possible. */ byCell?: boolean; /** * Iterate in reverse order. * @defaultValue false */ reverse?: boolean; /** * If provided then iterator results will reuse the return results. * * @defaultValue `undefined` (Creates new instances for each iterator) * * @remarks * - **Performance:** Setting this to `true` can drastically improve performance for large ranges, * but it will modify the original range data. * - **Safety:** If you need to preserve the original range data, set this to `false`. */ reuseIterator?: boolean | IteratorResult; } /** * When iterating a cursor is used to track the * current location. The coords will always move forward. */ interface Intersection { /** * The current coords. */ cell: CellCoords; /** * This is a non-overlapping virtual range. * * @remarks * This is not guaranteed to be the smallest packing size. */ range: RangeCoords; /** * All ranges at the intersection. This may be a single range. */ overlaps: ITypes.RangeCoordValue[]; } type Iterator = ESIterator; class IteratorInstance implements Iterator, IterableIterator { private _isColumn; private _isByCell; private _isReverse; private _cursor; private _reuse; private _localReuse; private _eventsMajor; private _eventMajorIndex; private _majorStart; private _majorEnd; private _eventsMinor; private _eventsMinorIterator; private _eventMinorPeek; private _minorStart; private _minorEnd; constructor(ranges: readonly ITypes.RangeCoordValue[], options?: IteratorOptions); /** * Returns the next Intersection as a IteratorResult. */ next(nextCell?: CellCoords): IteratorResult; return(_value?: Intersection): IteratorResult; throw(_e?: any): IteratorResult; [Symbol.iterator](): IterableIterator; } } /** * This interface returns rendering information about the formatted text based on the numberFormat. * * @see * * {@link https://customformats.com/} * * {@link https://exceljet.net/custom-number-formats} * * {@link https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1} */ declare interface Parsed { /** * @remarks * Never null */ readonly displayText: string; /** * If there is a conditional color then this is the color to use. */ readonly conditionalColor: IColor | null; /** * From the '*' formatChar. * A single character (usually a ' ' but can be anything) * * Repeats the next character in the format enough times to fill the column to its current width. * There shall not be more than one asterisk in one section of the format. If more than one asterisk * appears in one section of the format, all but the last asterisk shall be ignored. * [Example: if the number format is 0*x, and the value 3 is in the cell, the value 3xxxxxx is displayed. * The number of x characters that are displayed in the cell varies based on the width of the column. end example] */ readonly repeatChars: ParsedCharPlaceHolder[]; /** * If this is not null then the character should be displayed this many times. * This is is used if the text does not fit or if the value doesn't render against * the type correctly (for example a negative date) * @remarks * This is different then repeatChars in that it will only display the value * and not any additional . */ readonly repeatPlaceholder: string | null; /** * From the '_' formatChar. * An array of single characters. * * Skips the width of the next character. * Useful for lining up negative and positive values in different cells of the same column. * [Example: The number format _(0.0_);(0.0) aligns the numbers 2.3 and the column even though the * negative number is enclosed by parentheses. end example] */ readonly spacingChars: ParsedCharPlaceHolder[]; /** * The displayText broken down into runs. Useful for more complex layouts. */ readonly formattedRuns: ParsedRuns; /** * If true then the text could wrap if it doesn't fit. */ readonly canWrap: boolean; /** * Returns the value as a javascript date if possible. Will * return null if not possible. */ readonly asDate: Date | null; /** * If the format is a date format then this is true. */ readonly isDateFormat: boolean; /** * If the format is a time format then this is true. */ readonly isTimeFormat: boolean; /** * Indicates if the 1904 date convention was used during parsing. */ readonly isDate1904: boolean; } declare interface ParsedCharPlaceHolder { offset: number; char: string; } declare interface ParsedRun { type: ParseRunType; width: number; text: string; } declare interface ParsedRuns { runs: readonly ParsedRun[]; readonly length: number; readonly width: number; readonly lastRepeatIndex: number; } /* Excluded from this release type: parseHeaderRangeAddress */ /* Excluded from this release type: parseHeaderRangesAddress */ /** * Options for parsing a NumberFormat. */ declare interface ParserOptions { /** * Is date 1904 */ date1904?: boolean; /** * Parse a string of m/d/yy as date. We don't use as we do this using localization */ dateNF?: boolean; /** * Call when a repeat char */ onRepeatChar?: (offset: number, character: string) => void; /** * The character to add to the formatted string when a spacing character is * introduced. * * @defaultValue ' ' */ spacingCharacter?: string; /** * When '_' is encountered this is called. */ onSpacingChar?: (offset: number, character: string) => void; /** * When '?' this encountered this is called. * @defaultValue ' ' */ digitCharacter?: string; onDigitChar?: (offset: number) => void; locale?: string; table?: any; } declare const ParseRunType: { /** * Contains text. */ readonly Text: "text"; /** * Indicates the text at this run should repeat. */ readonly Repeat: "repeat"; /** * Indicates the text at this run should not be displayed but used for measuring white-space. */ readonly Spacing: "spacing"; }; declare type ParseRunType = typeof ParseRunType[keyof typeof ParseRunType]; declare interface Pending { commitId: string; listeners: IListener.Callback[]; removes: IListener.Remove[]; options: NotifyOptions; } declare class PersistScope implements IStyleCollection.IPersistScope { protected _state: PersistScopeState; protected _normalJSON: IStyle.JSON; protected _toJSONInternal: (jsonSheetStyleShared: IStyle.JSON[]) => IStyleCollection.JSON; protected _fromJSONInternal: (json: IStyleCollection.JSON) => void; protected _onLastEnd: () => void; protected _isClosed: boolean; constructor(state: PersistScopeState, normalJSON: IStyle.JSON, toJSONInternal: () => IStyleCollection.JSON, fromJSONInternal: (json: IStyleCollection.JSON) => void, onLastEnd: () => void); /** {@inheritDoc IStyleCollection.IPersistScope.endPersist} */ endPersist(): void; /** {@inheritDoc IStyleCollection.IPersistScope.getElementID} */ getElementID(json: IStyle.JSON): number | null; /** {@inheritDoc IStyleCollection.IPersistScope.getElementJSON} */ getElementJSON(id: number): IStyle.JSON; /** {@inheritDoc IStyleCollection.IPersistScope.fromJSON} */ fromJSON(json: IStyleCollection.JSON): void; /** {@inheritDoc IStyleCollection.IPersistScope.toJSON} */ toJSON(): IStyleCollection.JSON; } declare interface PersistScopeState { byJSONs: Map; byIds: Map; openScopes: Set; } /** * Implementation for {@link IPicture}. */ export declare class Picture extends AbstractModel implements IPicture { private _resource; private _details; private _dataUrl; constructor(options: Picture.ConstructorOptions); /** {@inheritDoc IPicture.getType} */ getType(): string; toJSON(toResourceId?: (resource: IResource) => number): IPicture.JSON; getTypeDescription(): string; /* Excluded from this release type: _asDataUrl */ /** {@inheritDoc IPicture.toHtml} */ toHtml(): Promise | string; /** {@inheritDoc IPicture.toImage} */ toImage(): Promise; /** {@inheritDoc IPicture.getDetails} */ getDetails(): Promise; /* Excluded from this release type: _fromDrawingJSON */ /* Excluded from this release type: _toDrawingJSON */ /* Excluded from this release type: _processDelete */ } /** * Interfaces for creating `Picture` items. * * @see * ### **Interface** * * {@link Picture} */ export declare namespace Picture { /** * Options for creating an IPicture. */ export interface ConstructorOptions extends IModel.ConstructorOptions { /** * Returns an IResource from the resourceId or null if not found. */ fromResourceId?: (resourceId: number) => IResource; /** * Useful for load/save/copying. */ beginPersistResource: () => IResourceCollection.IPersistScope; /** * Allow for the default lock aspect ratio to be overwritten. */ defaultLockAspectRatio?: boolean; } } /** * We resolve precedents in the mark phase but need use them * in the eval phase too so we cache these on the Calc node. */ declare interface PrecedentCalcCache extends IRange.Coords { calc: CalcNode | undefined; } declare class PrecedentEntry { blockEntry: ISpatialMap.Entry; /** * This is the shape of the dependency entry. For inputs with ranges this will be greater than 1 */ width: number; height: number; /** * Indicate the precedent index. Used for finding input in the calc entry. * `-1` for dynamic dependencies. */ index: number; /** * When a precedent has a cell address in a direction that is absolute. The entire * address is considered absolute in that direction. We must calc all nodes in that range */ $absWidth: boolean; $absHeight: boolean; /** * For dynamic dependencies we use the calc node directly but we * still need to reference the calcEntry to determine if the range * has been removed */ once?: CalcNode; } /* Excluded from this release type: ProtectionCheck */ /** * Encloses a string in the specified quote character. * * @param str The string to quote. * @param char The quote character to use (default is a single quote `'`). * @returns The quoted string. */ declare const quote: (str: string, char?: string) => string; /** * Implements {@link ReferenceableClipboard.ReferenceItem} by delegating to {@link ICellRange.ISnapshot}. */ export declare class RangeClipboardItem implements ReferenceableClipboard.ReferenceItem { protected _snapshot: ICellRange.ISnapshot; constructor(snapshot: ICellRange.ISnapshot); getItemType(): string; getItem(): ICellRange.ISnapshot; editMode(): EditMode; isCut(): boolean; getName(): string; toText(): Promise | string; toHtml(): Promise | string; toImage(): Promise | Blob; get isClipboardItem(): true; } declare class RangesListener { coords: ICellRanges.Coords | null; isRanges: boolean; spatialsIds: string[]; uuid: string; sheet: ISheet; generation: number; handler: ICellRange.Listener; handlerW: WeakRef; removeListener: IListener.Remove; options: ICellRange.ListenerOptions; constructor(uuid: string, spatialsIds: string[], coords: ICellRanges.Coords | null, isRanges: boolean, sheet: ISheet, generation: number, handler: ICellRange.Listener, handlerW: WeakRef, removeListener: IListener.Remove, options: ICellRange.ListenerOptions); delete(): void; createRangeEvent(options: NotifierOptions, customError?: string): ICellRange.Event; notify(options: NotifierOptions, customError?: string): void; processRemove(entry: ISpatialMap.Entry): RangesListener; processShift(entry: ISpatialMap.Entry): RangesListener; processSplit(_entries: ISpatialMap.Entry[]): RangesListener; processMerge(_entries: ISpatialMap.Entry[]): RangesListener; } declare class RangesListenerEntry implements ISpatialMap.IUpdatableEntry { uuid: string; groupId: string; noShift: boolean; constructor(groupId: string, uuid: string, noShift: boolean); /** {@inheritDoc ISpatialMap.IUpdatableEntry.onRemove} */ onRemove(options: IRange.Coords): void; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getShifted} */ getShifted(options: ISpatialMap.ShiftDetails): ISpatialMap.Entry; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getSplit} */ getSplit(_coords: [IRange.Coords, IRange.Coords], _orientation: IRange.Orientation): [this, this] | undefined; /** {@inheritDoc ISpatialMap.IUpdatableEntry.copyTo} */ copyTo(_destination: IRange.Coords, _options?: ISpatialMap.CopyOptions): this; /** {@inheritDoc ISpatialMap.IUpdatableEntry.canTile} */ canTile(_destination: IRange.Coords, _options?: ISpatialMap.CopyOptions): boolean; } declare namespace RangeState { /** * The boolean is used to indicate if the search result must full contained to return */ type SearchTypes = Partial>; interface IteratorOptions extends OverlappingRange.IteratorOptions { includeRangeTypes: boolean | SearchTypes; bounds?: IRange.Coords; ignoreHidden?: boolean | IRange.Orientation; includeMergeOverflow?: boolean; } interface Entry { /** * If byCell. Else null */ cell: IRange.CellCoords; /** * The cell that starts the range. */ start: IRange.CellCoords; /** * The cell that ends the range. */ end: IRange.CellCoords; /** * The CellState.Ranged. We could also make this a lazy function */ intersection: RangeState.Intersection; } /** * Shorthand type. */ type IteratorResult = WellKnownIteratorResult; /** * Shorthand type. */ type Iterator = WellKnownIterator; /* Excluded from this release type: Intersection */ /* Excluded from this release type: Type */ type Type = typeof Type[keyof typeof Type]; } declare type RangeToString = (range: Partial, defaultRange?: R, toCellString?: CellToString) => string; /** * Returns a union of all ranges in the selection. * @deprecated */ declare const rangeUnionFromSelection: (selection: IRangeSelection.Coords) => IRange.Coords; /** * Returns a list of merged and non-overlapping run coordinates. */ declare const removeOverlappingRuns: (runs: readonly Readonly>[], merge?: boolean) => RunCoords[]; export declare class Resource implements IResource { private _name; private _refs; private _listeners; private _isClosed; private _asArrayBufferResolve; private _asArrayBuffer; private _type; constructor(options: IResourceCollection.AddOptions); /** {@inheritDoc IResource.getName} */ getName(): string; /** {@inheritDoc IResource.toJSONAsync} */ toJSONAsync(): Promise; /** {@inheritDoc IResource.toBuffer} */ toBuffer(): Promise; /** {@inheritDoc IResource.getType} */ getType(): Promise; /** {@inheritDoc IResource.addReference} */ addReference(ref: any): void; /** {@inheritDoc IResource.deleteReference} */ deleteReference(ref: any): void; /** {@inheritDoc IResource.addUnloadListener} */ addUnloadListener(listener: IResource.IUnloadListener): void; /** {@inheritDoc IResource.isIResource} */ get isIResource(): true; /** {@inheritDoc IResource.isClosed} */ isClosed(): boolean; } export declare class ResourceCollection implements IResourceCollection { private _resources; private _persistOpen; constructor(); /** {@inheritDoc IResourceCollection.add} */ add(res: string | IResource | IResourceCollection.AddOptions): IResource; /** {@inheritDoc IResourceCollection.getItems} */ getItems(options?: IResourceCollection.GetItemsOptions): IResource[]; /** {@inheritDoc IResourceCollection.getCount} */ getCount(): number; /** {@inheritDoc IResourceCollection.beginPersist} */ beginPersist(): IResourceCollection.IPersistScope; } /** * Rotate all points around. * * @param points The array of points. * @param deg A number in degrees. * @returns A array of points [tl, tr, br, bl]. */ declare const rotatePoints: (points: Point[], deg: number, center?: Point) => Point[]; /** * Converts a set of RunCoords into a set of Ranges. */ declare const runCoordsToRangeCoords: (runs: readonly Readonly>[], entireRange: IRange.Coords, isColumn: boolean) => Partial[]; /** * Use for tracking the accumulated sizes from the beginning of the headers. * @remarks * This is a run but doesn't conform to the Run interface. */ declare interface RunningHeaderSize { indexMin: number; indexMax: number; spanSize: number; runningOffsetMin: number; runningOffsetMax: number; /** * The running headers up to run. */ runningHiddenRuns: number; } declare namespace RunUtils { export { unshiftRuns, unshiftAndMergeRuns, updateAndCompactRuns, concatModifiedRuns, splitAndUpdateRuns, cullRuns, mergeRuns, sortRuns, sortTwoRuns, ModifiedRuns, deepUpdate, deepCull, UpdateAndCompactOptions, shiftRuns, MergeRunOptions, findNextRunOffset, findRun, indicesToRuns, validateRuns, intersectRuns, RunVisitor, CacheSearchRunData, createSearchRunCache, searchRunsWithCache, scanRuns } } declare interface RunVisitor { (run: ITypes.RunCoordValue): { break: any; } | void; } /** * Scans all of the runs. It will scan each run exactly once. * In additional if there are gaps it will create an empty run. */ declare const scanRuns: (runs: ITypes.RunCoordValue[], visitor: RunVisitor, start?: number, end?: number) => { break: B; } | void; /** * To minimize lookups we assume that the items are generally read in order. * This allows use to cache the last run and check adjacent before doing a binary search. * * If the runs are update the an new CacheSearchRunData is required. see {@link createSearchRunCache} * * We always return a run if one is found. * * If one isn't we return a run with a null value with min/max being the empty space boundaries. * * the runIndex is always the current run or the next run (or -1 if no runs). * * We reuse cache * @param index * @param cache */ declare const searchRunsWithCache: (index: number, cache: CacheSearchRunData) => T; declare function setFontList(fontList: IFont.IFontFace[] | string[]): void; /** * Set a value on on a container unless. * 1. It's null then clears. * 2. It's undefined then ignores. */ declare function setOrClear(container: Record, key: string, newValue: T | null | undefined): void; /** * Base implementation of {@link ISheet}. */ export declare class Sheet implements ISheet { protected _options: ISheet.ConstructorOptions; protected _transactions: ITransaction.IStore; protected _ownTransactions: boolean; protected _transactionsRemoveListener: IListener.Remove; protected _lastTransactionUUID: string; protected _emitter: ListenerEmitter; protected _initializing: boolean; protected _starting: Promise; protected _strings: IStringCollection; protected _ownStrings: boolean; protected _styles: IStyleCollection; protected _ownStyles: boolean; protected _stylesRemoveListener: IListener.Remove; protected _normalStyleRanged: IProperties.ICellRanged; protected _resources: IResourceCollection; protected _ownResources: boolean; protected _names: INamedCollection; protected _ownNames: boolean; protected _namesRemoveListener: IListener.Remove; protected _calculation: ICalculation; protected _ownsCalculation: boolean; protected _workbook: IWorkbook | null; protected _tables: ITableCollection; protected _conditionals: IConditionalFormatCollection; protected _movables: IMovableCollection; protected _emitterMovables: ListenerEmitter; protected _rangesListenerSorted: SortedMap; protected _rangeListenerSpatial: ISpatialMap; protected _rangesListenerMap: Map; protected _lastCellDecoded: { address: ICell.Address; coords: IRange.CellCoords; }; protected _lastCellSelected: { coords: IRange.CellCoords; cell: ICell; }; protected _lastCellRead: { coords: IRange.CellCoords; cell: ICell; }; protected _lastValueRead: { range: IRange.Coords; isDateOrTime: boolean; }; protected _lastGetRangeRead: Record; protected _lastUsedCoordsRead: { coords: IRange.Coords; range: ICellRange; }; protected _lastActiveRead: { selection: IRangeSelection.Coords; range: ICellRange; ranges: ICellRanges; }; protected _lastRangeRead: { address: ICellRange.Address; range: ICellRange; ranges: ICellRanges; }; protected _entireCoords: IRange.Coords; protected _entireRange: ICellRange; protected _isDataColumn: boolean; protected _rangeSelection: IRangeSelection; protected _rangeSelectionListener: IRangeSelection.IListeners; protected _rangeSelectionRemoveListener: IListener.Remove; protected _view: ISheetView; protected _viewListener: ISheetView.IListeners; protected _viewRemoveListener: IListener.Remove; protected _protection: SheetProtection; protected _protectionRemoveListener: IListener.Remove; protected _tabColor: IColor; protected _isDate1904: boolean; protected _colHeaders: ISheetHeader; protected _colHeadersShiftCallback: SheetHeader.ShiftCallback; protected _colHeadersListener: ISheetHeader.IListeners; protected _colHeadersRemoveListener: IListener.Remove; protected _rowHeaders: ISheetHeader; protected _rowHeadersShiftCallback: SheetHeader.ShiftCallback; protected _rowHeadersListener: ISheetHeader.IListeners; protected _rowHeadersRemoveListener: IListener.Remove; protected _emptyCell: ICell; protected _cellOptions: SheetCellOptions; protected _closed: boolean; protected _defaultColWidthCache: number; protected _defaultRowHeightCache: number; protected _defaultFontBoundsCache: Readonly; constructor(options?: ISheet.ConstructorOptions); /* Excluded from this release type: _createRange */ /* Excluded from this release type: _createRanges */ /** {@inheritDoc ISheet.getRange} */ getRange(address: ICellRange.Address, options?: ICellRange.GetRangeOptions): ICellRange; /** {@inheritDoc ISheet.getCell} */ getCell(address: ICell.Address): ICell; /** {@inheritDoc ISheet.getRange} */ getRanges(address: ICellRanges.Address, options?: ICellRange.GetRangeOptions): ICellRanges; /** {@inheritDoc ISheet.getSelectedRange} */ getSelectedRange(options?: ICellRange.GetRangeOptions): ICellRange; /** {@inheritDoc ISheet.getSelectedRanges} */ getSelectedRanges(options?: ICellRange.GetRangeOptions): ICellRanges; /** {@inheritDoc ISheet.getEntireRange} */ getEntireRange(options?: ICellRange.GetRangeOptions): ICellRange; /** {@inheritDoc ISheet.getUsedRange} */ getUsedRange(options?: ICellRange.GetRangeOptions): ICellRange; /* Excluded from this release type: _cellToCoords */ /* Excluded from this release type: _validateCoords */ /* Excluded from this release type: _createRangeError */ /* Excluded from this release type: _protectionCheck */ /* Excluded from this release type: _rangesToCoords */ /* Excluded from this release type: _rangeToCoords */ /* Excluded from this release type: _collectRanges */ /* Excluded from this release type: _cellIterator */ /* Excluded from this release type: _rangeStateIterator */ /* Excluded from this release type: _overflowAndStops */ /* Excluded from this release type: _cellStateIterator */ /* Excluded from this release type: _indexMerges */ /* Excluded from this release type: _updateStyles */ /* Excluded from this release type: _createIncrementalUpdater */ /* Excluded from this release type: _updateTuples */ /* Excluded from this release type: _sort */ /* Excluded from this release type: _autoFill */ /* Excluded from this release type: _setHyperlinks */ /* Excluded from this release type: _updateFormulaSpatial */ /* Excluded from this release type: _realizeCalcedValues */ /* Excluded from this release type: _calculate */ /* Excluded from this release type: _calculateFull */ /* Excluded from this release type: _setComments */ /* Excluded from this release type: _clear */ /* Excluded from this release type: _merge */ /* Excluded from this release type: _unmerge */ /* Excluded from this release type: _getMerges */ /* Excluded from this release type: _clone */ /* Excluded from this release type: _getSnapshot */ /* Excluded from this release type: _copyRange */ /* Excluded from this release type: _snapShotFromSource */ /* Excluded from this release type: _copyFrom */ /* Excluded from this release type: _createFilter */ /** {@inheritDoc ISheet.insertFilter} */ insertFilter(address?: ICellRange.Address): IAutoFilter; /** {@inheritDoc ISheet.getFilter} */ getFilter(): IAutoFilter | null; /** {@inheritDoc ISheet.insertSort} */ insertSort(address?: ICellRange.Address): IAutoSort; /** {@inheritDoc ISheet.getSort} */ getSort(): IAutoSort | null; /* Excluded from this release type: _getDefaultShiftOrientation */ /* Excluded from this release type: _getDefaultSortCriteria */ /* Excluded from this release type: _insertFrom */ /* Excluded from this release type: _insertCells */ /* Excluded from this release type: _deleteCells */ /* Excluded from this release type: _autoFit */ /* Excluded from this release type: _createRangeEvent */ /* Excluded from this release type: _notifyAddressListeners */ /* Excluded from this release type: _notifyDataListeners */ /* Excluded from this release type: _notifyRangeListeners */ /* Excluded from this release type: _notifyRangeListener2 */ /* Excluded from this release type: _notifyUsedRangeChange */ /* Excluded from this release type: _notifyMergeChange */ /** {@inheritDoc ISheet.addListeners} */ addListeners(listeners: ISheet.IListeners, options?: IListener.Options): IListener.Remove; /* Excluded from this release type: _addRangesListeners */ /* Excluded from this release type: _addRangesListeners2 */ /* Excluded from this release type: _getUsedCoords */ /* Excluded from this release type: _isContentful */ /* Excluded from this release type: _getCount */ /* Excluded from this release type: _contentCounts */ /** {@inheritDoc ISheet.getSelectedCell} */ getSelectedCell(): ICell; /** {@inheritDoc ISheet.find} */ find(options?: string | ICellRange.FindOptions): Iterator; /* Excluded from this release type: _setMaxSize */ /* Excluded from this release type: _find */ /** {@inheritDoc ISheet.isDate1904} */ isDate1904(): boolean; /* Excluded from this release type: _surroundingRegion */ /* Excluded from this release type: _extendRange */ /* Excluded from this release type: _defaultFontDims */ /** {@inheritDoc ISheet.getColumnWidthAsFontUnit} */ getColumnWidthAsFontUnit(pixelWidth: number): number; /* Excluded from this release type: _defaultColWidth */ /* Excluded from this release type: _defaultRowHeight */ /** {@inheritDoc ISheet.getProtection} */ getProtection(): ISheetProtection; /* Excluded from this release type: _selectSheet */ /** {@inheritDoc ISheet.scrollTo} */ scrollTo(coords: Partial, options?: ISheet.ScrollToOptions): Promise; /* Excluded from this release type: _resolveSelectOptions */ /* Excluded from this release type: _commitAndAutoSelect */ /* Excluded from this release type: _autoSelect */ /** {@inheritDoc ISheet.getSelection} */ getSelection(): IRangeSelection; /** {@inheritDoc ISheet.getView} */ getView(): ISheetView; /** {@inheritDoc ISheet.setView} */ setView(view: ISheetView): this; /** {@inheritDoc ISheet.getTabColor} */ getTabColor(): IColor; /** {@inheritDoc ISheet.setTabColor} */ setTabColor(color: IColor | string | null): this; /** {@inheritDoc ISheet.getRowHeaders} */ getRowHeaders(): ISheetHeader; /** {@inheritDoc ISheet.getColumnHeaders} */ getColumnHeaders(): ISheetHeader; /** {@inheritDoc ISheet.toJSON} */ toJSON(ignoreData?: boolean): Promise; /** {@inheritDoc ISheet.getStyles} */ getStyles(): IStyleCollection; /** {@inheritDoc ISheet.getResources} */ getResources(): IResourceCollection; /** {@inheritDoc ISheet.getTransactions} */ getTransactions(): ITransaction.IStore; /** {@inheritDoc ISheet.getStrings} */ getStrings(): IStringCollection; /* Excluded from this release type: _searchMovables */ /* Excluded from this release type: _updateSelectedMovables */ /* Excluded from this release type: _addMovable */ /* Excluded from this release type: _addImage */ /** {@inheritDoc ISheet.getTables} */ getTables(): ITableCollection; getConditionals(): IConditionalFormatCollection; /** {@inheritDoc ISheet.getMovables} */ getMovables(): IMovableCollection; _doPerfTest(length?: number, doProfile?: boolean): void; /* Excluded from this release type: _validateOrRemoveOverlaps */ /* Excluded from this release type: _addTable */ /* Excluded from this release type: _addConditional */ /** {@inheritDoc ISheet.createTemporaryCell} */ createTemporaryCell(update: ICell.Update, coords?: IRange.CellCoords): ICell; /* Excluded from this release type: _getBoundsAtCoords */ /* Excluded from this release type: _getCoordsAtBounds */ /** {@inheritDoc ISheet.getRangeAtBounds} */ getRangeAtBounds(bounds: Bounds, options?: ICellRange.GetRangeOptions): ICellRange; /* Excluded from this release type: _getVisible */ /* Excluded from this release type: _hasRangedEntries */ /* Excluded from this release type: _getRangedEntries */ /* Excluded from this release type: _processAnchorShift */ /* Excluded from this release type: _processListenerShift */ /** {@inheritDoc ISheet.delete} */ delete(): void; /** {@inheritDoc ITransaction.ITransactional.doBatch} */ doBatch(callback: (commit: ITransaction.ICommit) => Promise | R, options?: string | ITransaction.OperationOptions): Promise | R; /** {@inheritDoc ISheet.isClosed} */ isClosed(): boolean; /** {@inheritDoc ISheet.close} */ close(): void; /** {@inheritDoc ITransaction.ITransactional.beginCommit} */ beginCommit(options?: string | ITransaction.OperationOptions): ITransaction; /* Excluded from this release type: _getState */ /* Excluded from this release type: _beginCommit */ /* Excluded from this release type: _updateState */ /* Excluded from this release type: _addEvent */ /* Excluded from this release type: _getScalar */ /* Excluded from this release type: _getStyle */ /* Excluded from this release type: _initState */ /* Excluded from this release type: _clearState */ /* Excluded from this release type: _createTableEntry */ /* Excluded from this release type: _createConditionalEntries */ /* Excluded from this release type: _createMovableEntry */ /* Excluded from this release type: _fromJSON */ /** {@inheritDoc ISheet.getName} */ getName(): string; /** {@inheritDoc ISheet.setName} */ setName(name: string): ISheet; /** {@inheritDoc ISheet.getVisibility} */ getVisibility(): ISheet.Visibility; /** {@inheritDoc ISheet.setVisibility} */ setVisibility(visibility?: ISheet.Visibility | boolean): this; /** {@inheritDoc ISheet.select} */ select(options: ITypes.SelectOptions): Promise; /** {@inheritDoc ISheet.duplicate} */ duplicate(): Promise; /** {@inheritDoc ISheet.setPosition} */ setPosition(index: number): ISheet; /** {@inheritDoc ISheet.getNames} */ getNames(): INamedCollection; /** {@inheritDoc ISheet.getCalculation} */ getCalculation(): ICalculation; /** {@inheritDoc ISheet.getWorkbook} */ getWorkbook(): IWorkbook | null; get [Symbol.toStringTag](): string; /** {@inheritDoc ICellRange.toString} */ toString(): string; /** {@inheritDoc ISheet.isISheet} */ get isISheet(): true; } declare interface SheetCellOptions { resolveRange: (address?: ICellRange.Address) => ICellRange | null; sheet: ISheet; date1904: boolean; styles: IStyleCollection; normalStyleRanged: IProperties.ICellRanged; nextContentful(cell: IRange.CellCoords, limit: number, isLeft?: boolean): number; maxCoords: IRange.Coords; getProtection(): ISheetProtection; calcGraph(): ICalcGraph; colHeaders: ISheetHeader; getRange(coords: IRange.Coords): ICellRange; styleUpdater: CellStyleUpdater; opener(url: string, options: ICellRange.SelectOptions, target?: string, features?: string): Promise; } /** * `SheetDirectStyle` represents a style that spans a range of cells. * * * It can generate a list of properties for each cell in the range. */ declare class SheetDirectStyle implements ISpatialMap.IUpdatableEntry, IProperties.ICellRanged { protected _c: IStyleCollection; protected _r: IRange.Coords; protected _p: IStyle.Properties; protected _t: IRange.Coords; protected _e: boolean; protected _o: IRange.Orientations; constructor(styles: IStyleCollection, range: IRange.Coords, properties?: IStyle.Properties, tile?: IRange.Coords, orientations?: IRange.Orientations); isEmpty(): boolean; getProperties(): IStyle.Properties; /** {@inheritDoc IProperties.ICellRanged.getCoords} */ getCoords(): Readonly; /** {@inheritDoc IProperties.ICellRanged.cloneWithUpdate} */ cloneWithUpdate(updates: IStyle.Modifiers): this; /** {@inheritDoc ISpatialMap.IUpdatableEntry.copyTo} */ copyTo(destination: IRange.Coords, options?: ISpatialMap.CopyOptions): this; /** {@inheritDoc ISpatialMap.IUpdatableEntry.canTile} */ canTile(_destination: IRange.Coords, _options?: ISpatialMap.CopyOptions): boolean; protected _createShifted(coords: IRange.Coords): this; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getShifted} */ getShifted(options: ISpatialMap.ShiftDetails): ISpatialMap.Entry; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getSplit} */ getSplit(coords: [IRange.Coords, IRange.Coords], orientation: IRange.Orientation): [this, this]; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getSplit} */ getMerged(other: this, destination: IRange.Coords, orientation: IRange.Orientation): this; /** {@inheritDoc ISpatialMap.IUpdatableEntry.hasTrailingEdge} */ hasTrailingEdge(): boolean; /** {@inheritDoc ISpatialMap.IUpdatableEntry.isMergeOnShift} */ isMergeOnShift(): boolean; protected _splitBorderRange(border: IBorder.Properties, range: IRange.Coords, rangeNew: IRange.Coords, isColumn: boolean): Partial | null | undefined; protected _localizeBorderRange(unscoped: Readonly, rangeUnscoped: IRange.Coords, range: IRange.Coords): Partial | null | undefined; /** * Localizes the border to the cell coords. * Returns border properties, null, or undefined. * * If undefined then there was no border to localize. * * `null` is localize to none. */ protected _localizeBorder(unscoped: IBorder.Properties, range: IRange.Coords, rowIndex: number, colIndex: number): Partial | null | undefined; /** {@inheritDoc IProperties.ICellRanged.getPropertiesAt} */ getPropertiesAt(rowIndex: number, colIndex: number, value: Scalar): Readonly; /** {@inheritDoc ISpatialMap.IUpdatableEntry.toJSON} */ toJSON(): IStyle.JSON; } /** * For updating and working with headers (rows/columns). */ declare class SheetHeader implements ISheetHeader { protected _emitter: ListenerEmitter; protected _options: SheetHeader.ConstructorOptions; protected _sheetRemoveListener: IListener.Remove; protected _transactions: ITransaction.IStore; protected _transactionsRemoveListener: IListener.Remove; protected _closed: boolean; protected _emptyHeader: ICellHeader; protected _scaleFactor: number; protected _defaultSize: number; protected _defaultCustomSize: number; protected _defaultPxSize: number; protected _isColumn: boolean; protected _indexedSizes: _Utils.RunningHeaderSize[]; protected _indexedHidden: _Utils.HiddenRun[]; protected _headerRunCoords: RunCoords; protected _hasCustomFormats: boolean; protected _hasStyles: boolean; protected _hasHidden: boolean; protected _lastHeaderRead: { offset: number; header: ICellHeader; }; protected _readCache: RunUtils.CacheSearchRunData<_Utils.CellHeaderState>; protected _lastHeaders: ITypes.RunCoordValue<_Utils.CellHeaderState>[]; protected _lastVisibleRunsRead: number; protected _lastVisibleRunCoords: RunCoords; protected _maxDataIndex: number; protected _maxDataRange: ICellHeaderRange; protected _maxRunCoords: RunCoords; protected _maxRangeCoords: IRange.Coords; protected _selectionRuns: readonly ITypes.RunCoordValue[]; protected _selection: IRangeSelection.Coords; protected _maxSheetCoords: IRange.Coords; constructor(options: SheetHeader.ConstructorOptions); /** {@inheritDoc IListener.ISource.addListeners} */ addListeners(listeners: ISheetHeader.IListeners, options?: IListener.Options): IListener.Remove; protected _cacheMaxIndex(): void; protected _invalidSizes(force?: boolean): void; protected _onHeaderChange(): void; /** {@inheritDoc ISheetHeader.getSheet} */ getSheet(): ISheet; /** {@inheritDoc ISheetHeader.getOrientation} */ getOrientation(): IRange.Orientation; /** {@inheritDoc ISheetHeader.getTextAt} */ getTextAt(index: number): string; protected _scanHeaders(callback: ICellHeaderRange.ForEachSpanCallback, headers: ITypes.RunCoordValue<_Utils.CellHeaderState>[], createCellHeader: CreateCellHeaderCallback, optionsRange: ICellHeaderRange.GetRangeOptions, asRun: RunCoords, options: ICellHeaderRange.IteratorOptions): { break: T; } | void; /** {@inheritDoc ISheetHeader.getRange} */ getRange(address: ICellHeaderRange.Address, options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange; /** {@inheritDoc ISheetHeader.getRanges} */ getRanges(address: ICellHeaderRanges.Address, options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges; /** {@inheritDoc ISheetHeader.getSelectedRange} */ getSelectedRange(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange; /** {@inheritDoc ISheetHeader.getSelectedRanges} */ getSelectedRanges(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges; /** {@inheritDoc ISheetHeader.getUsedRange} */ getUsedRange(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange; /** {@inheritDoc ISheetHeader.getEntireRange} */ getEntireRange(options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange; /** {@inheritDoc ISheetHeader.at} */ at(index: number): ICellHeader; /** {@inheritDoc ISheetHeader.updateHeaderPairs} */ updateHeaderPairs(pairs: ICellHeaderRange.AddressUpdatePair[], options?: ICellHeaderRange.UpdateHeadersOptions): RunCoords[] | null; protected _parseHeaderRangeAddress(address: ICellHeaderRange.Address): RunCoords; protected _update(addresses: ICellHeaderRange.Address | ICellHeaderRange.Address[], update: ICellHeader.Update, options?: ICellHeaderRange.UpdateHeadersOptions): this; protected _setSize(address: ICellHeaderRange.Address | ICellHeaderRange.Address[], size?: number | string, options?: ICellHeaderRange.SetSizeOptions): this; protected _setHidden(address: ICellHeaderRange.Address | ICellHeaderRange.Address[], hidden?: boolean): this; protected _clear(coords: RunCoords, options?: ICellHeaderRange.UpdateHeadersOptions): void; protected _getSnapshot(coordsFrom?: RunCoords, optionsMark?: ICellHeaderRange.CopyOptions): ICellHeaderRange.ISnapshot; /** {@inheritDoc ISheetHeader.isProtected} */ isProtected(): boolean; /** {@inheritDoc ISheetHeader.getScaleFactor} */ getScaleFactor(): number; protected get _headers(): ITypes.RunCoordValue<_Utils.CellHeaderState>[]; protected _updatePairsInternal(setters: ICellHeaderRange.AddressUpdatePair[], options?: ICellHeaderRange.UpdateHeadersOptions): RunCoords[] | null; /** * @deprecated */ hasCustomFormats(): boolean; /** * @deprecated */ hasCustomStyles(): boolean; /** {@inheritDoc ISheetHeader.hasHidden} */ hasHidden(): boolean; /** {@inheritDoc ISheetHeader.getDefaultSize} */ getDefaultSize(): number; /** {@inheritDoc ISheetHeader.getMaxSize} */ getMaxSize(): number; /** {@inheritDoc ISheetHeader.getMinSize} */ getMinSize(): number; /** {@inheritDoc ISheetHeader.findOffset} */ findOffset(index: number): number; /** {@inheritDoc ISheetHeader.findIndex} */ findIndex(offset: number): number; /** {@inheritDoc ISheetHeader.findVisibleIndex} */ findVisibleIndex(index: number): RunCoords; /** {@inheritDoc ISheetHeader.getSpanSize} */ getSpanSize(indexFrom: number, indexTo?: number): number; /** {@inheritDoc ISheetHeader.getVisibleCount} */ getVisibleCount(indexFrom: number, indexTo: number): number; /** {@inheritDoc ISheetHeader.isSelectedAll} */ isSelectedAll(index: number): boolean; /** {@inheritDoc ISheetHeader.isSelected} */ isSelected(index: number): boolean; /** {@inheritDoc ISheetHeader.getSelectedRuns} */ getSelectedRuns(): readonly ITypes.RunCoordValue[]; /** {@inheritDoc ISheetHeader.hiddenHeadersAt} */ hiddenHeadersAt(index: number, reverse?: boolean): number; protected _insertHeaders(index: number, amount: number): void; protected _deleteHeaders(index: number, amount: number): void; /** {@inheritDoc ITransaction.ITransactional.beginCommit} */ beginCommit(options?: string | ITransaction.OperationOptions): ITransaction; /** {@inheritDoc ITransaction.ITransactional.doBatch} */ doBatch(callback: (commit: ITransaction.ICommit) => R | Promise, options?: string | ITransaction.OperationOptions): R | Promise; /** {@inheritDoc ITransaction.ITransactional.isClosed} */ isClosed(): boolean; /** {@inheritDoc ISheetHeader.close} */ close(): void; protected _getState(): State_4; protected _beginCommit(options?: ITransaction.StoreOperationOptions): ITransaction; protected _updateState(updateState?: Partial): void; /** {@inheritDoc ISheetHeader.fromJSON} */ fromJSON(json: ISheetHeader.JSON): void; /** {@inheritDoc ISheetHeader.toJSON} */ toJSON(): ISheetHeader.JSON; get [Symbol.toStringTag](): string; toString(): string; } /** * {@inheritDoc SheetHeader} * @see * ### **Interface** * * {@link SheetHeader} */ declare namespace SheetHeader { /** * Constructor Options for Sheet Header. * @remarks * Used by `Sheet`. */ interface ConstructorOptions { /** * The {@link ISheet} containing the Headers. */ sheet: ISheet; /** * The orientation of the data. * * @defaultValue IRange.Orientation.Column * * @remarks * This is the opposite of the orientation of the layout. For examples a header that manages * columns will be visibility orientated as a row. */ orientation?: IRange.Orientation; /** * Returns the maximum range of the headers in both orientations. * * @defaultValue `{ colStart: 0, rowStart: 0, colEnd: Number.MAX_SAFE_INTEGER, rowEnd: Number.MAX_SAFE_INTEGER }` */ createCellHeader?: CreateCellHeaderCallback; transactions?: ITransaction.IStore; getUpdateId?: () => number; /** * If true the Header will error if any updates are attempted. */ isProtected?: () => boolean; /** * Return the display text at the given index. */ getTextAt?: (index: number) => string; /** * The size of the header without any customizations. * * @defaultValue 100 * * @remarks * Must be great than 0. */ defaultSize?: () => number; /** * The minimum size of the header. * * @defaultValue 0 * * @remarks * Must be great than or equal 0. */ minSize?: () => number; maxSize?: () => number; /** * A callback to return the maximum index of the header. */ maxSheetCoords: () => IRange.Coords; /** * A number that represents a scaling factor. */ scaleFactor?: () => number; /** * A callback to tell the headers to shift. * * @param index * @param amount */ setContainerShiftedCallback?: (callback: ShiftCallback) => void; /** * JSON state to load. */ json?: ISheetHeader.JSON; } /** * `Sheet`s manage the insertion and deletion of headers. To notify that this * should occur the ShiftCallback is used. */ interface ShiftCallback { (index: number, amount: number): void; } } declare type SheetKey = ISheet | SheetRef | string | number; declare class SheetProtection extends DefaultProtection implements ISheetProtection { /** {@inheritDoc ISheetProtection.isAutoFilterAllowed} */ isAutoFilterAllowed(): boolean; /** {@inheritDoc ISheetProtection.isDeleteColumnsAllowed} */ isDeleteColumnsAllowed(): boolean; /** {@inheritDoc ISheetProtection.isDeleteRowsAllowed} */ isDeleteRowsAllowed(): boolean; /** {@inheritDoc ISheetProtection.isFormatCellsAllowed} */ isFormatCellsAllowed(): boolean; /** {@inheritDoc ISheetProtection.isFormatColumnsAllowed} */ isFormatColumnsAllowed(): boolean; /** {@inheritDoc ISheetProtection.isFormatRowsAllowed} */ isFormatRowsAllowed(): boolean; /** {@inheritDoc ISheetProtection.isInsertColumnsAllowed} */ isInsertColumnsAllowed(): boolean; /** {@inheritDoc ISheetProtection.isInsertHyperlinksAllowed} */ isInsertHyperlinksAllowed(): boolean; /** {@inheritDoc ISheetProtection.isInsertRowsAllowed} */ isInsertRowsAllowed(): boolean; /** {@inheritDoc ISheetProtection.isObjectsAllowed} */ isObjectsAllowed(): boolean; /** {@inheritDoc ISheetProtection.isPivotTablesAllowed} */ isPivotTablesAllowed(): boolean; /** {@inheritDoc ISheetProtection.isScenariosAllowed} */ isScenariosAllowed(): boolean; /** {@inheritDoc ISheetProtection.isSortAllowed} */ isSortAllowed(): boolean; isSelectLockedCellsAllowed(): boolean; isSelectUnlockedCellsAllowed(): boolean; protected _updateProperties(properties: ISheetProtection.Properties | null): void; protected _clearProperties(): void; protected _fromJSON(json: ISheetProtection.JSON | null): void; protected _toJSON(json: ISheetProtection.JSON): ISheetProtection.JSON; get [Symbol.toStringTag](): string; toString(): string; } /** * The reference to a sheet with in a workbook. * These are used for finding sheet and determining * it's location/visibility within a workbook. */ declare interface SheetRef { /** * This is a unique id for the sheet. * Note - It is not the index and will not change if the sheet order is adjusted */ id: number; /** * The display name of the sheet */ name: string; /** * @defaultValue ISheet.Visibility.Visible */ visibility: ISheet.Visibility; /** * The sheet model */ sheet: ISheet; } declare const shiftRuns: (runs: ITypes.RunCoordValue[], index: number, amount?: number) => ModifiedRuns; /** * read only font face * @hidden */ export declare class SimpleFontFace implements IFont.IFontFace { _private: any; constructor(input: any); toJSON(): any; /** {@inheritDoc IFont.getFamily} */ getFamily(): string; /** {@inheritDoc IFont.getPitch} */ getPitch(): string; /** {@inheritDoc IFont.getPanose} */ getPanose(): string | undefined; toString(): any; get isIFont(): true; } /** * Converts a snake_case or kebab-case string to camelCase. * * @param str The snake_case or kebab-case string to convert. * @returns The string converted to camelCase. * * @example * ```ts * snakeToCamel('snake_case_string'); // Returns 'snakeCaseString' * snakeToCamel('kebab-case-string'); // Returns 'kebabCaseString' * ``` */ declare const snakeToCamel: (str: string) => string; /** * Contains types for {@link ISort}. */ export declare namespace Sort { const CaseInsensitiveOptions: Intl.CollatorOptions; const CaseSensitiveOptions: Intl.CollatorOptions; /** * For comparing `boolean` cell types. */ const BooleanCollator: ISort.Collator; /** * For comparing `string` `ScalarTypes`. */ const StringCollator: ISort.Collator; /** * For comparing `number` `ScalarTypes`. * * @remarks * This will include dates. */ const NumberCollator: ISort.Collator; /** * For comparing `RichData` `ScalarTypes`. * * @remarks * **PARTIAL IMPLEMENTATION** */ const RichDataCollator: ISort.Collator; /** * Default {@link ISort.RangeOptions}. */ const DefaultRangeOptions: ISort.RangeOptions; /** * The default sorting for mixed ScalarTypes. */ const DefaultCollators: readonly ISort.Collator[]; } /** * A reasonably fast collection of key-value pairs with a powerful API. * Largely compatible with the standard Map. SortedMap is a B+ tree data structure, * so the collection is sorted by key. * * B+ trees tend to use memory more efficiently than hashTables such as the * standard Map, especially when the collection contains a large number of * items. However, maintaining the sort order makes them modestly slower: * O(log size) rather than O(1). This B+ tree implementation supports O(1) * fast cloning. It also supports freeze(), which can be used to ensure that * a SortedMap is not changed accidentally. * * Confusingly, the ES6 Map.forEach(c) method calls c(value,key) instead of * c(key,value), in contrast to other methods such as set() and entries() * which put the key first. I can only assume that the order was reversed on * the theory that users would usually want to examine values and ignore keys. * SortedMap's forEach() therefore works the same way, but a second method * `.forEachPair((key,value)=>{...})` is provided which sends you the key * first and the value second; this method is slightly faster because it is * the "native" for-each method for this class. * * Out of the box, SortedMap supports keys that are numbers, strings, arrays of * numbers/strings, Date, and objects that have a valueOf() method returning a * number or string. Other data types, such as arrays of Date or custom * objects, require a custom comparator, which you must pass as the second * argument to the constructor (the first argument is an optional list of * initial items). Symbols cannot be used as keys because they are unordered * (one Symbol is never "greater" or "less" than another). * * @example * Given a {name: string, age: number} object, you can create a sorted map by * name and then by age like this: * * let map = new SortedMap(undefined, (a, b) => { * if (a.name > b.name) * return 1; // Returns a number >0 when a > b * else if (a.name < b.name) * return -1; // Returns a number <0 when a < b * else // names are equal (or incomparable) * return a.age - b.age; // Returns >0 when a.age > b.age * }); * * map.set({name:"Bill", age:17}, "happy"); * map.set({name:"Fran", age:40}, "busy & stressed"); * map.set({name:"Bill", age:55}, "recently laid off"); * map.forEachPair((k, v) => { * console.log(`Name: ${k.name} Age: ${k.age} Status: ${v}`); * }); * * @remarks * The "range" methods (`forEach, forRange, editRange`) will return the number * of elements that were scanned. In addition, the callback can return {break: R} * to stop early and return R from the outer function. * * - TODO: Test performance of preallocating values array at max size * - TODO: Add fast initialization when a sorted array is provided to constructor * * For more documentation see https://github.com/qwertie/btree-typescript * * Are you a C# developer? You might like the similar data structures I made for C#: * BDictionary, BList, etc. See http://core.loyc.net/collections/ * * @author David Piepgrass */ declare class SortedMap implements ISortedMapF, ISortedMap { private _root; _size: number; _maxNodeSize: number; /** * Provides a total order over keys (and a strict partial order over the type K) * @returns A negative value if a < b, 0 if a === b and a positive value if a > b */ _compare: (a: K, b: K) => number; /** * Initializes an SortedMap. * @param compare Custom function to compare pairs of elements in the map. * If not specified, defaultComparator will be used which is valid as long as K extends DefaultComparable. * @param entries A set of key-value pairs to initialize the map * @param maxNodeSize Branching factor (maximum items or children per node) * Must be in range 4..256. If undefined or <4 then 32 is used; if >256 then 256. */ constructor(entries?: [K, V][], compare?: (a: K, b: K) => number, maxNodeSize?: number); /** * returns the number of key-value pairs in the map. */ get size(): number; /** * Returns the number of key-value pairs in the map. * @remarks * This is the same as size. */ get length(): number; /** Returns true iff the map contains no key-value pairs. */ get isEmpty(): boolean; /** Releases the map so that its size is 0. */ clear(): void; /** * Runs a function for each key-value pair, in order from smallest to largest key. * For compatibility with ES6 Map, the argument order to the callback is * backwards: value first, then key. Call forEachPair instead to receive the key * as the first argument. * @param thisArg If provided, this parameter is assigned as the `this` * value for each callback. * @returns The number of values that were sent to the callback, * or the R value if the callback returned {break: R}. */ forEach(callback: (v: V, k: K, map: SortedMap) => { break?: R; } | void, thisArg?: any): R | number; /** * Runs a function for each key-value pair, in order from smallest to * largest key. The callback can return {break: R} (where R is any value * except undefined) to stop immediately and return R from forEachPair. * @param onFound A function that is called for each key-value pair. This * function can return {break: R} to stop early with result R. * The reason that you must return {break: R} instead of simply R * itself is for consistency with editRange(), which allows * multiple actions, not just breaking. * @param initialCounter This is the value of the third argument of * `onFound` the first time it is called. The counter increases * by one each time `onFound` is called. Default value: 0 * @returns The number of pairs sent to the callback (plus initialCounter, * if you provided one). If the callback returned {break: R} then * the R value is returned instead. */ forEachPair(callback: (k: K, v: V, counter: number) => { break?: R; } | void, initialCounter?: number): R | number; /** * Finds a pair in the map and returns the associated value. * @param defaultValue a value to return if the key was not found. * @returns The value, or defaultValue if the key was not found. * @remarks * Computational complexity: O(log size) */ get(key: K, defaultValue?: V): V | undefined; /** * Adds or overwrites a key-value pair in the collection. * @param key Key used to determine the sort order of data in the map. * @param value Value to associate with the key. * @param overwrite Whether to overwrite an existing key-value pair * (default: true). If this is false and there is an existing * key-value pair then this method has no effect. * @returns `true` if a new key-value pair was added. * @remarks * Computational complexity: O(log size) * Note: when overwriting a previous entry, the key is updated * as well as the value. This has no effect unless the new key * has data that does not affect its sort order. */ set(key: K, value: V, overwrite?: boolean | ISortedMap.SetPairCallback): boolean; /** * Returns true if the key exists in the collection, false if not. * Use get() for best performance; use has() if you need to * distinguish between "undefined value" and "key not present". * @param key Key to detect * @remarks * Computational complexity: O(log size) */ has(key: K): boolean; /** * Removes a single key-value pair from the SortedMap. * @param key Key to find * @returns `true` if a pair was found and removed, false otherwise. * @remarks * Computational complexity: O(log size) */ delete(key: K): boolean; /** * Returns a copy of the map with the specified key set (the value is undefined). */ with(key: K): SortedMap; /** * Returns a copy of the map with the specified key-value pair set. */ with(key: K, value: V2, overwrite?: boolean): SortedMap; /** * Returns a copy of the map with the specified key-value pairs set. */ withPairs(pairs: [K, V | V2][], overwrite: boolean): SortedMap; /** * Returns a copy of the map with the specified keys present. * @param keys The keys to add. If a key is already present in the map, * neither the existing key nor the existing value is modified. * @param returnThisIfUnchanged if true, returns this if all keys already * existed. Performance note: due to the architecture of this class, all * node(s) leading to existing keys are cloned even if the collection is * ultimately unchanged. */ withKeys(keys: K[], returnThisIfUnchanged?: boolean): SortedMap; /** * Returns a copy of the map with the specified key removed. * @param returnThisIfUnchanged if true, returns this if the key didn't exist. * Performance note: due to the architecture of this class, node(s) leading * to where the key would have been stored are cloned even when the key * turns out not to exist and the collection is unchanged. */ without(key: K, returnThisIfUnchanged?: boolean): SortedMap; /** * Returns a copy of the map with the specified keys removed. * @param returnThisIfUnchanged if true, returns this if none of the keys * existed. Performance note: due to the architecture of this class, * node(s) leading to where the key would have been stored are cloned * even when the key turns out not to exist. */ withoutKeys(keys: K[], returnThisIfUnchanged?: boolean): SortedMap; /** * Returns a copy of the map with the specified range of keys removed. */ withoutRange(low: K, high: K, includeHigh: boolean, returnThisIfUnchanged?: boolean): SortedMap; /** * Returns a copy of the map with pairs removed whenever the callback * function returns false. `where()` is a synonym for this method. */ filter(callback: (k: K, v: V, counter: number) => boolean, returnThisIfUnchanged?: boolean): SortedMap; /** Returns a copy of the map with all values altered by a callback function. */ mapValues(callback: (v: V, k: K, counter: number) => R): SortedMap; /** * Performs a reduce operation like the `reduce` method of `Array`. * It is used to combine all pairs into a single value, or perform * conversions. `reduce` is best understood by example. For example, * `map.reduce((P, pair) => P * pair[0], 1)` multiplies all keys * together. It means "start with P=1, and for each pair multiply * it by the key in pair[0]". Another example would be converting * the map to a Map (in this example, note that M.set returns M): * * let M = map.reduce((M, pair) => M.set(pair[0],pair[1]), new Map()) * * **Note**: the same array is sent to the callback on every iteration. */ reduce(callback: (previous: R, currentPair: [K, V], counter: number, map: SortedMap) => R, initialValue: R): R; reduce(callback: (previous: R | undefined, currentPair: [K, V], counter: number, map: SortedMap) => R): R | undefined; /** * Returns an iterator that provides items in order (ascending order if * the collection's comparator uses ascending order, as is the default.) * * @param lowestKey First key to be iterated, or undefined to start at * minKey(). If the specified key doesn't exist then iteration * starts at the next higher key (according to the comparator). * @param reusedResults Optional iterator results used repeatedly to store the iterator results, * to avoid creating a new object on every iteration. */ entries(lowestKey?: K, reusedResults?: IteratorResult<[K, V], any>): IterableIterator<[K, V]>; /** * Returns an iterator that provides items in reversed order. * * @param highestKey Key at which to start iterating, or undefined to * start at maxKey(). If the specified key doesn't exist then iteration * starts at the next lower key (according to the comparator). * @param reusedResults Optional iterator results used repeatedly to store the iterator results, * to avoid creating a new object on every iteration. * @param skipHighest Iff this flag is true and the highestKey exists in the * collection, the pair matching highestKey is skipped, not iterated. */ entriesReversed(highestKey?: K, reusedResults?: IteratorResult<[K, V], any>, skipHighest?: boolean): IterableIterator<[K, V]>; private findPath; /** * Computes the differences between `this` and `other`. * For efficiency, the diff is returned via invocations of supplied handlers. * The computation is optimized for the case in which the two trees have large amounts * of shared data (obtained by calling the `clone` or `with` APIs) and will avoid * any iteration of shared state. * The handlers can cause computation to early exit by returning {break: R}. * Neither of the collections should be changed during the comparison process (in your callbacks), as this method assumes they will not be mutated. * @param other The map to compute a diff against. * @param onlyThis Callback invoked for all keys only present in `this`. * @param onlyOther Callback invoked for all keys only present in `other`. * @param different Callback invoked for all keys with differing values. */ diffAgainst(other: SortedMap, onlyThis?: (k: K, v: V) => { break?: R; } | void, onlyOther?: (k: K, v: V) => { break?: R; } | void, different?: (k: K, vThis: V, vOther: V) => { break?: R; } | void): R | undefined; private static finishCursorWalk; private static stepToEnd; private static makeDiffCursor; /** * Advances the cursor to the next step in the walk of its map. * Cursors are walked backwards in sort order, as this allows them to leverage maxKey() in order to be compared in O(1). * @param cursor The cursor to step * @param stepToNode If true, the cursor will be advanced to the next node (skipping values) * @returns `true` if the step was completed and false if the step would have caused the cursor to move beyond the end of the map. */ private static step; /** * Compares the two cursors. Returns a value indicating which cursor is ahead in a walk. * Note that cursors are advanced in reverse sorting order. */ private static compare; /** * Returns a new iterator for iterating the keys of each pair in ascending order. * * @param firstKey Minimum key to include in the output. * @param reusedResults Optional iterator results used repeatedly to store the iterator results, * to avoid creating a new object on every iteration. */ keys(firstKey?: K, reusedResults?: IteratorResult<[K, V], any>): IterableIterator; /** * Returns a new iterator for iterating the values of each pair in order by key. * * @param firstKey Minimum key whose associated value is included in the output. * @param reusedResults Optional iterator results used repeatedly to store the iterator results, * to avoid creating a new object on every iteration. */ values(firstKey?: K, reusedResults?: IteratorResult<[K, V], any>): IterableIterator; /** Returns the maximum number of children/values before nodes will split. */ get maxNodeSize(): number; /** * Gets the lowest key in the map. Complexity: O(log size) */ minKey(): K | undefined; /** * Gets the highest key in the map. Complexity: O(1) */ maxKey(): K | undefined; /** * Quickly clones the map by marking the root node as shared. * Both copies remain editable. When you modify either copy, any * nodes that are shared (or potentially shared) between the two * copies are cloned so that the changes do not affect other copies. * This is known as copy-on-write behavior, or "lazy copying". */ clone(): SortedMap; /** * Performs a greedy clone, immediately duplicating any nodes that are * not currently marked as shared, in order to avoid marking any * additional nodes as shared. * * @param force Clone all nodes, even shared ones. */ greedyClone(force?: boolean): SortedMap; /** * Gets an array filled with the contents of the map, sorted by key. */ toArray(maxLength?: number): [K, V][]; /** * Gets an array of all keys, sorted. */ keysArray(): K[]; /** * Gets an array of all values, sorted by key. */ valuesArray(): V[]; /** * Gets a string representing the map's data based on toArray(). */ toString(): string; /** * Stores a key-value pair only if the key doesn't already exist in the map. * @returns `true` if a new key was added */ setIfNotPresent(key: K, value: V): boolean; /** * Returns the next pair whose key is larger than the specified key (or undefined if there is none). * If key === undefined, this function returns the lowest pair. * @param key The key to search for. * @param reusedPair Optional array used repeatedly to store key-value pairs, to * avoid creating a new array on every iteration. */ nextHigherPair(key: K | undefined, reusedPair?: [K, V]): [K, V] | undefined; /** * Returns the next key larger than the specified key, or undefined if there is none. * Also, nextHigherKey(undefined) returns the lowest key. */ nextHigherKey(key: K | undefined, reusedPair?: [K, V]): K | undefined; /** * Returns the next pair whose key is smaller than the specified key (or undefined if there is none). * If key === undefined, this function returns the highest pair. * @param key The key to search for. * @param reusedPair Optional array used repeatedly to store key-value pairs, to * avoid creating a new array each time you call this method. */ nextLowerPair(key: K | undefined, reusedPair?: [K, V]): [K, V] | undefined; /** * Returns the next key smaller than the specified key, or undefined if there is none. * Also, nextLowerKey(undefined) returns the highest key. */ nextLowerKey(key: K | undefined, reusedPair?: [K, V]): K | undefined; /** * Returns the key-value pair associated with the supplied key if it exists * or the pair associated with the next lower pair otherwise. If there is no * next lower pair, undefined is returned. * @param key The key to search for. * @param reusedPair Optional array used repeatedly to store key-value pairs, to * avoid creating a new array each time you call this method. */ getPairOrNextLower(key: K, reusedPair?: [K, V]): [K, V] | undefined; /** * Returns the key-value pair associated with the supplied key if it exists * or the pair associated with the next lower pair otherwise. If there is no * next lower pair, undefined is returned. * @param key The key to search for. * @param reusedPair Optional array used repeatedly to store key-value pairs, to * avoid creating a new array each time you call this method. */ getPairOrNextHigher(key: K, reusedPair?: [K, V]): [K, V] | undefined; /** * Edits the value associated with a key in the map, if it already exists. * @returns `true` if the key existed, false if not. */ changeIfPresent(key: K, value: V): boolean; /** * Builds an array of pairs from the specified range of keys, sorted by key. * Each returned pair is also an array: pair[0] is the key, pair[1] is the value. * * @param low The first key in the array will be greater than or equal to `low`. * @param high This method returns when a key larger than this is reached. * @param includeHigh If the `high` key is present, its pair will be included * in the output if and only if this parameter is true. Note: if the * `low` key is present, it is always included in the output. * @param maxLength Length limit. getRange will stop scanning the map when * the array reaches this size. * * @remarks * Computational complexity: O(result.length + log size) */ getRange(low: K, high: K, includeHigh?: boolean, maxLength?: number): [K, V][]; /** * Adds all pairs from a list of key-value pairs. * * @param pairs Pairs to add to this map. If there are duplicate keys, * later pairs currently overwrite earlier ones (e.g. [[0,1],[0,7]] * associates 0 with 7.) * @param overwrite Whether to overwrite pairs that already exist. * if false pairs[i] is ignored when the key pairs[i][0] already exists. * if SetPairCallback then this will be called on both inserts and updates. * @returns The number of pairs added to the collection. * * @remarks * Computational complexity: O(pairs.length * log(size + pairs.length)) */ setPairs(pairs: [K, V][], overwrite?: boolean | ISortedMap.SetPairCallback): number; /** * Scans the specified range of keys, in ascending order by key. * Note: the callback `onFound` must not insert or remove items in the * collection. Doing so may cause incorrect data to be sent to the * callback afterward. * * @param low The first key scanned will be greater than or equal to `low`. * @param high Scanning stops when a key larger than this is reached. * @param includeHigh If the `high` key is present, `onFound` is called for * that final pair if and only if this parameter is true. * @param onFound A function that is called for each key-value pair. This * function can return {break: R} to stop early with result R. * @param initialCounter Initial third argument of onFound. This value * increases by one each time `onFound` is called. Default: 0 * @returns The number of values found, or R if the callback returned * `{break: R}` to stop early. * * @remarks * Computational complexity: O(number of items scanned + log size) */ forRange(low: K, high: K, includeHigh: boolean, onFound?: ISortedMap.EditRangeCallback, initialCounter?: number): R | number; /** * TODO - REMOVE - To allow for editMode to be passed to forRange. */ forEditRange(low: K, high: K, includeHigh: boolean, editMode: boolean, onFound?: ISortedMap.EditRangeCallback, initialCounter?: number): ISortedMap.EditRangeResult | number | number; /** * Scans and potentially modifies values for a subsequence of keys. * Note: the callback `onFound` should ideally be a pure function. * Specifically, it must not insert items, call clone(), or change * the collection except via return value; out-of-band editing may * cause an exception or may cause incorrect data to be sent to * the callback (duplicate or missed items). It must not cause a * clone() of the collection, otherwise the clone could be modified * by changes requested by the callback. * * @param low The first key scanned will be greater than or equal to `low`. * @param high Scanning stops when a key larger than this is reached. * @param includeHigh If the `high` key is present, `onFound` is called for * that final pair if and only if this parameter is true. * @param onFound A function that is called for each key-value pair. This * function can return `{value: v}` to change the value associated * with the current key, `{delete:true}` to delete the current pair, * `{break: R}` to stop early with result R, or it can return nothing * (undefined or {}) to cause no effect and continue iterating. * `{break: R}` can be combined with one of the other two commands. * The third argument `counter` is the number of items iterated * previously; it equals 0 when `onFound` is called the first time. * @returns The number of values scanned, or R if the callback returned * `{break: R}` to stop early. * * @remarks * Computational complexity: O(number of items scanned + log size) * Note: if the map has been cloned with clone(), any shared * nodes are copied before `onFound` is called. This takes O(n) time * where n is proportional to the amount of shared data scanned. */ editRange(low: K, high: K, includeHigh: boolean, onFound: ISortedMap.EditRangeCallback, initialCounter?: number): R | number; /** * Same as `editRange` except that the callback is called for all pairs. */ editAll(onFound: ISortedMap.EditRangeCallback, initialCounter?: number): R | number; /** * Removes a range of key-value pairs from the collection. * @param low The first key scanned will be greater than or equal to `low`. * @param high Scanning stops when a key larger than this is reached. * @param includeHigh Specifies whether the `high` key, if present, is deleted. * @returns The number of key-value pairs that were deleted. * @remarks Computational complexity: O(log size + number of items deleted) */ deleteRange(low: K, high: K, includeHigh: boolean): number; /** Deletes a series of keys from the collection. */ deleteKeys(keys: K[]): number; /** * Gets the height of the tree: the number of internal nodes between the * SortedMap object and its leaf nodes (zero if there are no internal nodes). */ get height(): number; /** * Makes the object read-only to ensure it is not accidentally modified. * Freezing does not have to be permanent; unfreeze() reverses the effect. * This is accomplished by replacing mutator functions with a function * that throws an Error. Compared to using a property (e.g. this.isFrozen) * this implementation gives better performance in non-frozen SortedMaps. */ freeze(): void; /** Ensures mutations are allowed, reversing the effect of freeze(). */ unfreeze(): void; /** * Returns true if the map appears to be frozen. */ get isFrozen(): boolean; /** * Scans the tree for signs of serious bugs (e.g. this.size doesn't match * number of elements, internal nodes not caching max element properly...) * Computational complexity: O(number of nodes), i.e. O(size). This method * skips the most expensive test - whether all keys are sorted - but it * does check that maxKey() of the children of internal nodes are sorted. */ checkValid(): void; } /** * {@inheritDoc SortedMap} * @see * ### **Interface** * * {@link SortedMap} */ declare namespace SortedMap { const DeleteValue: Readonly<{ delete: true; }>; const Break: Readonly<{ break: true; }>; const DeleteRange: () => Readonly<{ delete: true; }>; /** * Types that SortedMap supports by default */ type DefaultComparable = number | string | Date | boolean | null | undefined | (number | string)[] | { valueOf: () => number | string | Date | boolean | null | undefined | (number | string)[]; }; /** A SortedMap frozen in the empty state. */ const EmptySortedMap: SortedMap; /** * Compares DefaultComparables to form a strict partial ordering. * * Handles +/-0 and NaN like Map: NaN is equal to NaN, and -0 is equal to +0. * * Arrays are compared using '<' and '>', which may cause unexpected equality: * for example [1] will be considered equal to ['1']. * * Two objects with equal valueOf compare the same, but compare unequal to * primitives that have the same value. */ function defaultComparator(a: DefaultComparable, b: DefaultComparable): number; /** * Compares items using the < and > operators. This function is probably slightly * faster than the defaultComparator for Dates and strings, but has not been benchmarked. * Unlike defaultComparator, this comparator doesn't support mixed types correctly, * i.e. use it with `SortedMap` or `SortedMap` but not `SortedMap`. * * NaN is not supported. * * Note: null is treated like 0 when compared with numbers or Date, but in general * null is not ordered with respect to strings (neither greater nor less), and * undefined is not ordered with other types. */ function simpleComparator(a: string, b: string): number; function simpleComparator(a: number | null, b: number | null): number; function simpleComparator(a: Date | null, b: Date | null): number; function simpleComparator(a: (number | string)[], b: (number | string)[]): number; } declare function sortRuns(a: ITypes.RunCoordValue[]): ITypes.RunCoordValue[]; /** * Sorts twos runs by their min values. */ declare function sortTwoRuns(a: ITypes.RunCoordValue, b: ITypes.RunCoordValue, forward?: boolean): ITypes.RunCoordValue[]; /** * Spill Entries are used to track spills. * There are two types of spills: * * Spill complete sets the input values during a calculation cycle. * * Spill errors can occur for 2 reasons. * * a. a direct input from api. * * b. a spill during a calculation cycle. */ declare class SpillEntry { private _c; private _e; private _cycleId; constructor(coords: IRange.Coords, cycleId: number, error?: boolean); getCycleId(): number; getError(): boolean; getCoords(): IRange.Coords; setError(error: boolean, cycleId: number): ISpatialMap.Entry; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getShifted} */ getShifted(options: ISpatialMap.ShiftDetails): ISpatialMap.Entry; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getMerged} */ getMerged(_other: this, coords: IRange.Coords, _orientation: IRange.Orientation): this | undefined; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getSplit} */ getSplit(coords: [IRange.Coords, IRange.Coords], _orientation: IRange.Orientation): [this, this] | undefined; } /** * Split/update algo used for formatted text. * This will split and update runs * All runs must be: * ** ordered * ** non-overlapping * Runs do not need to be contiguous. */ declare function splitAndUpdateRuns(runs: ITypes.RunCoordValue[], update: ITypes.RunCoordValue | null, onSplit?: (run: ITypes.RunCoordValue, offset: number) => T[], onUpdate?: (prevValue: T | null, newValue: U | null, run: ITypes.RunCoordValue) => T | null, inPlace?: boolean): ModifiedRuns; /** * Splits a string by a delimiter, ignoring any quoted sections. * * @param str The string to split. * @param delimiter The delimiter to split by (default is undefined). * @param quote The quote character used to ignore splits inside quoted sections (default is undefined). * @returns An array of strings split by the delimiter, ignoring quoted sections. */ declare const splitUnquoted: (str: string, delimiter?: string, quote?: string) => string[]; declare interface State extends AbstractModel.State { effects?: string[]; } declare interface State_2 extends AbstractModel.State { } /* Excluded from this release type: State_3 */ declare interface State_4 { headers: ITypes.RunCoordValue<_Utils.CellHeaderState>[]; defaultCustomSize: number; runs?: RunCoords[]; } declare interface State_5 { cellValuesGrid: ISparseGrid; contentfulSpatial: ISpatialMap; formulaSpatial: ISpatialMap; calcGraph: ICalcGraph; spillSpatial: ISpatialMap; pendingSpatial: ISpatialMap; calcErrorsSpatial: ISpatialMap; directStyleSpatial: ISpatialMap; continuousFillSpatial: ISpatialMap; mergeSpatial: ISpatialMap; hyperlinkSpatial: ISpatialMap; commentsSpatial: ISpatialMap; movableSpatial: ISpatialMap; movableMapModel: Map>; tableSpatial: ISpatialMap; tableMapModel: Map>; tableMapName: Map; conditionalSpatial: ISpatialMap; conditionalModels: Map>; rangesListenerSpatial2: ISpatialMap; rangesListenerMap2: Map; rangeListenerSpatial: ISpatialMap; rangesListenerMap: Map; unlockSpatial: ISpatialMap; filter: IAutoFilter; sort: IAutoSort; deleted: boolean; } declare interface State_6 { sheetRefsAll: SheetRef[]; sheetRefsVisibleAndHidden: SheetRef[]; sheetRefsVisible: SheetRef[]; refsById: Map; sheetsById: Map; refsByLowerCaseName: Map; sheetsByLowerCaseName: Map; refsByInstance: Map; lastId: number; sheetsCreated: Set; listenersSheets: Map; name: string | null; } export declare class StringCollection implements IStringCollection { private _persistOpen; private _stringsByText; private _stringsById; private _nextId; private _lastReadId; private _lastReadValue; constructor(); /** {@inheritDoc IStringCollection.addMultiple} */ addMultiple(shared: string[], conflateDuplicates?: boolean): void; /** {@inheritDoc IStringCollection.add} */ add(shared: string): number; /** {@inheritDoc IStringCollection.getItems} */ getItems(options?: IStringCollection.GetItemsOptions): string[]; /** {@inheritDoc IStringCollection.getById} */ getById(id: number): string; /** {@inheritDoc ICollection.getCount} */ getCount(): number; /** {@inheritDoc ICollection.IPersistable.beginPersist} */ beginPersist(): ICollection.IPersistScope; } /** * Returns meta data about the number format. */ declare interface Style { numberFormat: string; /** * Category of format/ */ formatType: Type; /** * If used in a menu it's the sort oder. * TODO - enrich this since excel and drawMl (charts are slightly different. Union these?) */ primary?: number; args?: StyleConfig; regMatch?: RegExp; } /** * Base implementation of {@link IStyleCollection} * * TODO - defaultFontSize move to theme? * */ export declare class StyleCollection implements IStyleCollection { protected _emitter: ListenerEmitter; protected _theme: ITheme; protected _defaultFontSize: number; protected _schemeLookup: IColor.SchemeLookup; protected _indexedLookup: IColor.IndexedLookup; protected _builtInsCellStyles: Map; protected _customCellStyles: Map; protected _builtInsTableStyles: Map; protected _customTableStyles: Map; protected _emptyTableStyle: ITableStyle.Empty; protected _indexedColors: readonly IColor[]; protected _mruColors: readonly IColor[]; protected _normalStyle: IStyle; protected _normalRanged: IProperties.ICellRanged; protected _defaultTableStyle: ITableStyle; protected _persistCache: PersistScopeState; constructor(theme?: ITheme, indexedColors?: string[], defaultFontSize?: number); protected _initializeNamedStyles(namedStyles: readonly IStyle.Properties[], builtInStyleMap: Map): void; protected _initializeTableStyles(): Map; protected _initializeBuiltIns(): void; /** {@inheritDoc IStyleCollection.getNormal} */ getNormal(): IStyle; /** {@inheritDoc IStyleCollection.getNormalRanged} */ getNormalRanged(): IProperties.ICellRanged; /** {@inheritDoc IStyleCollection.setTheme} */ setTheme(theme: ITheme): void; /** {@inheritDoc IStyleCollection.getTheme} */ getTheme(): ITheme; /** {@inheritDoc IStyleCollection.setDefaultFontSize} */ setDefaultFontSize(fontSize: number): void; /** {@inheritDoc IStyleCollection.getDefaultFontSize} */ getDefaultFontSize(): number; /** {@inheritDoc IStyleCollection.beginPersist} */ beginPersist(): IStyleCollection.IPersistScope; /** {@inheritDoc IStyleCollection.getNamed} */ getNamed(name: string | IStyle.BuiltInName): IStyle.INamed; /** {@inheritDoc IStyleCollection.getCustomNamed} */ getCustomNamed(): IStyle.INamed[]; /** {@inheritDoc IStyleCollection.setNamed} */ setNamed(modifiers: IStyle.NamedUpdate, mergeIfExists?: boolean): IStyle.INamed; protected _setCustomCellStyleInternal(modifiers: IStyle.NamedUpdate, mergeIfExists?: boolean, _i?: number | null): IStyle.INamed; protected _setCustomTableStyleInternal(name: string, properties: ITableStyle.ResolvableProperties): ITableStyle; protected _hideOrRemoveNamed(style: IStyle.INamed | string): boolean; /** {@inheritDoc IStyleCollection.getTableStyle} */ getTableStyle(name: string): ITableStyle | null; /** {@inheritDoc IStyleCollection.getCustomTableStyles} */ getCustomTableStyles(): ITableStyle[]; /** {@inheritDoc IStyleCollection.setDefaultTableStyle} */ setDefaultTableStyle(styleName: string): boolean; /** {@inheritDoc IStyleCollection.getDefaultTableStyle} */ getDefaultTableStyle(): ITableStyle; protected _deleteCustomTableStyle(styleName: string): boolean; /** {@inheritDoc IStyleCollection.setCustomTableStyle} */ setCustomTableStyle(name: string, properties: ITableStyle.ResolvableProperties): ITableStyle; /** {@inheritDoc IStyleCollection.validateStyleName} */ validateStyleName(name: string, checkDuplicates?: boolean): void; /** {@inheritDoc IStyleCollection.normalize} */ normalize(values: IStyle.Modifiers, name?: string): Partial; /** {@inheritDoc IStyleCollection.schemeLookup} */ schemeLookup(): IColor.SchemeLookup; /** {@inheritDoc IStyleCollection.indexedLookup} */ indexedLookup(): IColor.IndexedLookup; /** {@inheritDoc IStyleCollection.parseColor} */ parseColor(str: string): IColor; /** {@inheritDoc IStyleCollection.recentColors} */ recentColors(): readonly IColor[]; /** {@inheritDoc IStyleCollection.addRecentColor} */ addRecentColor(color: IColor): readonly IColor[]; /** {@inheritDoc IStyleCollection.clearRecentColors} */ clearRecentColors(): void; /** {@inheritDoc IStyleCollection.getIndexedColors} */ getIndexedColors(): readonly IColor[]; /** {@inheritDoc IStyleCollection.setCustomIndexedColors} */ setCustomIndexedColors(colors: readonly IColor[]): void; /** {@inheritDoc IStyleCollection.getCustomIndexedColors} */ getCustomIndexedColors(): readonly IColor[]; /** {@inheritDoc IListener.ISource.addListeners} */ addListeners(listeners: IStyleCollection.IListeners, options?: IListener.Options): IListener.Remove; protected _toJSONInternal(jsonSheetStyleShared: IStyle.JSON[]): IStyleCollection.JSON; protected _fromJSONIndexedColors(indexedColors: string[]): IColor[]; protected _fromJSONInternal(json: IStyleCollection.JSON): void; } /** * These are only returned if all segments have the same values. */ declare interface StyleConfig { separator?: boolean; decimalPlaces?: number; currencySymbol?: string; } declare class Styles { /** * Find the style for a numberFormat. */ lookupStyle(numberFormat: string | number): Style; /** * Returns an ordered list of a select set of the builtIn FormatCodes. */ lookupPrimary(): Style[]; lookupDefault(numberFormatKey: string | Type): string | null; } /** * Implementation of {@link ITable}. */ export declare class Table extends AbstractAnchored implements ITable { private _sheet; private _styles; private _stylesRemoveListener; private _headerValueListener; private _isUpdatingHeader; private _autoExpandRemoveListener; private _styleCache; private _stylePropsCache; private _processTableUpdate; private _setNameOnContainer; private _names; private _namedItem; private _filterShiftCallback; private _filterCoordsCallback; private _colHeadersSizeUnlistener; private _rowHeadersSizeUnlistener; private _visibleRange; private _isHeaderVisible; private _isTotalVisible; private _isFirstColumnVisible; private _isLastColumnVisible; private _range; constructor(options: ITable.ConstructorOptions); /** {@inheritDoc ITable.getSnapshot} */ getSnapshot(options?: ReferenceableClipboard.CopyOptions): ITable.ISnapshot; /** {@inheritDoc ITable.getAnchorType} */ getAnchorType(): IAnchored.Type; /** {@inheritDoc ITable.getStyle} */ getStyle(): ITableStyle; /** {@inheritDoc ITable.resize} */ addRows(_offset: number, count?: number): this; /** {@inheritDoc ITable.deleteRowsAt} */ deleteRowsAt(_offset: number, count?: number): this; /** {@inheritDoc ITable.addColumn} */ addColumn(offset: number, name: string): ITable.Column; /** {@inheritDoc ITable.getColumns} */ getColumns(): ITable.Column[]; /** {@inheritDoc ITable.convertToRange} */ convertToRange(maxCells?: number): ICellRange; /** {@inheritDoc ITable.resize} */ resize(address: ICellRange.Address, description?: string): ICellRange; /** {@inheritDoc ITable.getName} */ getName(): string; /** {@inheritDoc ITable.setName} */ setName(name: string): this; /** {@inheritDoc ITable.getDescription} */ getDescription(): string; /** {@inheritDoc ITable.setDescription} */ setDescription(description: string): this; /** {@inheritDoc ITable.select} */ select(options?: ICellRange.SelectOptions): Promise; /** {@inheritDoc ITable.getRange} */ getRange(): ICellRange; /* Excluded from this release type: _processRestoreOrRevert */ /* Excluded from this release type: _processAnchorCoords */ /** {@inheritDoc ITable.getRange} */ getUsedRange(): ICellRange; private _getUsedCoords; /** {@inheritDoc ITable.getHeaderRange} */ /** {@link ITable.getHeaderRange} @hidden */ getHeaderRange(): ICellRange; private _getHeaderCoords; /** {@inheritDoc ITable.getTotalRange} */ /** {@link ITable.getTotalRange} @hidden */ getTotalRange(): ICellRange; private _getTotalCoords; /** {@inheritDoc ITable.getStyleOptions} */ getStyleOptions(): ITableStyle.StyleOptions; /** {@inheritDoc ITable.updateStyleOptions} */ updateStyleOptions(options: ITableStyle.StyleOptions, description?: string): this; /** {@inheritDoc ITable.getStyleAt} */ getStyleAt(coords: IRange.CellCoords): IStyle; /** {@inheritDoc ITable.getShowTotals} */ getShowTotals(): boolean; /** {@inheritDoc ITable.setShowTotals} */ setShowTotals(showTotals: boolean): this; /** {@inheritDoc ITable.getShowHeaders} */ getShowHeaders(): boolean; /** {@inheritDoc ITable.setShowHeaders} */ setShowHeaders(showHeaders: boolean): this; /** {@inheritDoc ITable.getShowFilterButton} */ getShowFilterButton(): boolean; /** {@inheritDoc ITable.setShowFilterButton} */ setShowFilterButton(showFilterButton: boolean): this; private _applyFilterAndSort; private _processUpdate; private _createFilter; /** {@inheritDoc ITable.insertFilter} */ insertFilter(): IAutoFilter; /** {@inheritDoc ITable.getFilter} */ getFilter(): IAutoFilter | null; private _createSort; /** {@inheritDoc ITable.insertSort} */ insertSort(): IAutoSort; /** {@inheritDoc ITable.getSort} */ getSort(): IAutoSort | null; /** {@inheritDoc ITable.getColumnFilter} */ getColumnFilter(offset: number): IAutoFilter.IColumn; /** {@inheritDoc ITable.getVisibleRefRangeCoords} */ getVisibleRefRangeCoords(): IRange.Coords; /** {@inheritDoc ITable.getVisibleCellCoords} */ getVisibleCellCoords(coords: IRange.CellCoords): IRange.CellCoords; /** {@inheritDoc ITable.isHeaderVisible} */ isHeaderVisible(): boolean; /** {@inheritDoc ITable.isTotalVisible} */ isTotalVisible(): boolean; /** {@inheritDoc ITable.isFirstColumnVisible} */ isFirstColumnVisible(): boolean; /** {@inheritDoc ITable.isLastColumnVisible} */ isLastColumnVisible(): boolean; /* Excluded from this release type: _columnsFromSheet */ /* Excluded from this release type: _updateColumns */ /* Excluded from this release type: _processDelete */ /* Excluded from this release type: _processFilterUpdate */ /* Excluded from this release type: _processContainerShift */ private _modifyTable; /** {@inheritDoc IListener.ISource.addListeners} */ addListeners(listeners: ITable.IListeners, options?: IListener.Options): IListener.Remove; /* Excluded from this release type: _processStateChange */ /* Excluded from this release type: _processHeaderListener */ get [Symbol.toStringTag](): string; /** {@inheritDoc ICellRanges.toString} */ toString(): string; /** {@inheritDoc ITable.toJSON} */ toJSON(): ITable.JSON | null; private _createNamed; private _fromJSON; /** {@inheritDoc ITable.close} */ close(): void; /** {@inheritDoc ITable.isITable} */ get isITable(): true; } export declare namespace TextUtils { export { findValidTextValue, capitalize, getFileNameExtension, getBaseName, snakeToCamel, camelToSnake, clampString, countDecimals, DefaultUnQuoteRegEx, isQuoted, unquote, quote, splitUnquoted, isValidHttpUrl, isValidEmail, numberToAlphabet } } declare interface TextVisitor { visitTextRun?: (run: ITextRun, index: number, count: number) => Partial | void; visitTextParagraph?: (paragraph: ITextParagraph, index: number, count: number) => Partial | void; visitTextLine?: (line: ITextLine, index: number, count: number) => Partial | void; visitTextFrame?: (frame: ITextFrame) => Partial | void; } export declare class Theme implements ITheme { private _name; private _colors; private _fonts; private _schemeLookup; private _colorMap; private _builtInID; private _delegate; private _cacheColors; constructor(json: ITheme.JSON, delegate?: ITheme, builtIn?: number | null); get builtInID(): number | null; /** {@inheritDoc ITheme.getName} */ getName(): string; /** {@inheritDoc ITheme.isCustom} */ isCustom(): boolean; /** {@inheritDoc ITheme.getColorScheme} */ getColorScheme(): ITheme.IColorScheme; /** {@inheritDoc ITheme.getFontScheme} */ getFontScheme(): ITheme.IFontScheme; /** {@inheritDoc ITheme.schemeLookup} */ schemeLookup(): IColor.SchemeLookup; /** {@inheritDoc ITheme.parseColor} */ parseColor(str: string): IColor; /** {@inheritDoc ITheme.toJSON} */ toJSON(): ITheme.JSON; } /** * Collection of themes */ export declare class ThemeCollection implements IThemeCollection { private _customMap; private _defaultTheme; private _isReadOnly; constructor(_json?: IThemeCollection.JSON, isReadOnly?: boolean); /** {@inheritDoc IThemeCollection.getDefaultTheme} */ getDefaultTheme(): ITheme; /** {@inheritDoc IThemeCollection.setDefaultTheme} */ setDefaultTheme(theme: ITheme): ITheme; /** {@inheritDoc IThemeCollection.getByName} */ getByName(name: string): ITheme | null; /** {@inheritDoc IThemeCollection.getByName} */ getItems(options?: IThemeCollection.GetItemsOptions): ITheme[]; /** {@inheritDoc IThemeCollection.getCount} */ getCount(): number; /** {@inheritDoc IThemeCollection.setCustomTheme} */ setCustomTheme(theme: ITheme): ITheme | null; /** {@inheritDoc IThemeCollection.deleteCustomTheme} */ deleteCustomTheme(theme: ITheme | string): ITheme | null; } /** * Events are never fired on sub transactions. Only when making changes to the root * either directly or through a final commit. Any models that want to fire non transactional * events should do this directly. */ export declare class TransactionStore implements ITransaction.IStore { protected _listeners: Set; protected _listenersState: Map>; protected _commits: Map; protected _transactionStack: AbstractTransaction[]; protected _transactionOpen: boolean; protected _locked: boolean; protected _isSync: boolean; protected _isTransient: boolean; protected _author: any; protected _current: CommitContainer; protected _pending: CommitContainer; protected _cacheModel: any; protected _cacheState: any; protected _states: Map; constructor(options?: ITransaction.StoreConstructorOptions); /** * Sets the transaction store to be synchronous or asynchronous. * * @param sync * * @remarks * This is used for unit tests only. */ static setDefaultSync: (sync: boolean) => void; /** {@inheritDoc ITransaction.IStore.getLog} */ getLog(commitId: string, max?: number): ITransaction.ICommit[]; /** {@inheritDoc ITransaction.IStore.getCommitCount} */ getCommitCount(): number; /** {@inheritDoc ITransaction.IStore.isOpenTransaction} */ isOpenTransaction(): boolean; /** {@inheritDoc ITransaction.IStore.getView} */ getPendingView(): Record | null; /** {@inheritDoc ITransaction.IStore.getState} */ getState(model: any): Readonly; /** {@inheritDoc ITransaction.IStore.getCurrentCommit} */ getCurrentCommit(): ITransaction.ICommit; /** {@inheritDoc ITransaction.IStore.restore} */ restore(commitId: string, options?: ITransaction.RestoreOptions): ITransaction.ICommit; /** {@inheritDoc ITransaction.IStore.revert} */ revert(commitId: string, options?: ITransaction.RestoreOptions): ITransaction.ICommit; protected _getCommitContainer(commitId: string, options?: ITransaction.RestoreOptions): CommitContainer; protected _pruneForwards(_commitId: string): void; /** {@inheritDoc ITransaction.IStore.beginCommit} */ beginCommit(options?: ITransaction.StoreOperationOptions, onClose?: ITransaction.CloseCallback): ITransaction; /** {@inheritDoc ITransaction.IStore.doBatch} */ doBatch(callback: (commit: ITransaction.ICommit) => R | Promise, options?: ITransaction.StoreOperationOptions, onClose?: ITransaction.CloseCallback): Promise | R; /** {@inheritDoc ITransaction.IStore.remove} */ remove(model: any): boolean; /** {@inheritDoc ITransaction.IStore.addListener} */ addListener(listener: ITransaction.IListeners): IListener.Remove; /** {@inheritDoc ITransaction.IStore.addStateListener} */ addStateListener(model: any, listener: ITransaction.IStateListener): IListener.Remove; protected dispatchEvents(dispatcher: () => void, async?: boolean): void; protected _commitRecord(container: CommitContainer, states: Map, forceAmend: boolean): void; _notifyStates(event: keyof ITransaction.IStateListener, container: CommitContainer, states: Map, view?: Record, isRevert?: boolean, isRestore?: boolean, async?: boolean): void; _notify(event: keyof ITransaction.IListeners, commit: ITransaction.ICommit, async?: boolean): void; } /** * UndoManager that wraps transaction commits and restores these. */ export declare class TransactionUndoManager extends UndoManager { private _transactions; private _removeLister; constructor(transactions?: ITransaction.IStore, maxStack?: number); clear(): void; /** * Close the undo manager and remove the listener. */ close(): void; } /** * Namespace for tuples. */ export declare namespace Tuple { /** * Represents a pair of values: a numeric index represents the starting offset and an array of elements. * * This provides a convenient shorthand for scenarios where you need to associate * a contiguous span of values with a specific index or position. * @remarks * The MinorTuple is types as an Array with 2 elements for performance reasons but can be logically * conceptualized as the following type. * ``` type MinorTuple = { minor: number; values: T[]; }; * ``` */ export type MinorTuple = [minor: number, runs: IListLike]; /** * Represents a tuple associated with a specific dimension (e.g., a row or a column in a grid). * * The first element is the major index, and the second element is a `MinorTuple` representing * the minor indices and values associated with that location. */ export type MajorTuple = [major: number, minors: MinorTuple[]]; /** * Represents a collection of `MajorTuple`s, used to store data for a 2d collection of tuples. * **Validity Requirements:** * - The `major` values within a collection of `MajorTuple`s must be sorted in ascending order. * - The `minor` values within each `MinorTuple` of a `MajorTuple` must be sorted in ascending order. * - The `minors` (array of `MinorTuple`s) within a `MajorTuple` must not overlap; their ranges * (defined by the `minor` values and the `length` of the `values` arrays) should be mutually exclusive. */ export type GridTuple = MajorTuple[]; /** * Adds precomputed bounds for the `MajorTuple`s. * * @remarks * In some scenarios the maximum bounds of the tuples is required (e.g., during rendering or calculations), * providing precomputed bounds can improve performance by avoiding the need to scan the entire collection. */ export interface BoundedTuples { /** * The bounded tuples. */ tuples: Tuple.GridTuple; /** * The precomputed bounds encompassing all the `MajorTuple`s. */ bounds: Tuple.OrientatedCoords; } /** * RangeCoords expressed in relative coordinates. */ export interface OrientatedCoords { majorStart: number; minorStart: number; majorEnd: number; minorEnd: number; } /** * A builder for easily creating tuples that can be either contiguous or non-contiguous. * A builder maintains an ordered structure where major and minor values must always * increase, otherwise an error will be thrown. * * @template T - The type of values stored within the tuples. */ export interface IBuilder { /** * Adds a single value associated with a specific major and minor index. * * @param major The major index. * @param minor The minor index. * @param value The value to be added. * @throws `Error` If the point is out of order compared to previously added points * (within the same row). * * @remarks * If the value is an Array, it will be treated as a discrete value. If you want to set * multiple values along the minor axis, then use {@link addValues}. */ addValue(major: number, minor: number, value: T): IBuilder; /** * Adds multiple values associated with a specific major and minor index. * * @param major The major index. * @param minor The minor index. * @param value An array of values to be added. * @throws `Error` If the point is out of order compared to previously added points * (within the same row). */ addValues(major: number, minor: number, value: T[]): IBuilder; /** * Constructs and returns the bounded tuples based on the added values. * This method can be called multiple times. * * @returns The built bounded tuples. */ build(): Tuple.BoundedTuples; } /** * Implementation of {@link IBuilder} that that adds in aligned order. */ export class Builder implements IBuilder { private _tuples; private _minors; private _values; private _minorMin; private _minorMax; private _majorIndex; private _minorIndex; private _createList; private _offsetMajor; private _offsetMinor; constructor(createList?: (arr: Array) => IList, offsetMajor?: number, offsetMinor?: number); /** {@inheritDoc IBuilder.addValues} */ addValues(major: number, minor: number, value: T[]): IBuilder; /** {@inheritDoc IBuilder.addValue} */ addValue(major: number, minor: number, value: T): IBuilder; /** {@inheritDoc IBuilder.build} */ build(): Tuple.BoundedTuples; } /** * Transposes cell coordinates within tuples to create `MajorTuple` representations * in the opposite orientation. * * This utility efficiently converts data organized by one orientation into the opposite. */ export class TransposedBuilder implements IBuilder { private _minors; /** the currentNode the node.minorIndex >= _minorIndex */ private _current; private _first; private _majorMin; private _majorMax; private _majorIndex; private _minorIndex; private _createList; private _offsetMajor; private _offsetMinor; constructor(createList?: (arr: Array) => IListLike, offsetMajor?: number, offsetMinor?: number); /** {@inheritDoc IBuilder.addValues} */ addValues(major: number, minor: number, value: T[]): IBuilder; /** {@inheritDoc IBuilder.addValue} */ addValue(major: number, minor: number, value: T): IBuilder; /** {@inheritDoc IBuilder.build} */ build(): Tuple.BoundedTuples; } /** * Thrown when a major minor is set out of order. */ export class OutOfOrderError extends ChainedError { constructor(message?: string, cause?: Error); } } /** * Represents the built-in categorization of a number format, or 'Custom' if the format is not recognized as a built-in type. * * Excel has the following: * @see * {@link https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1} */ declare const Type: { /** * The default format, displays numbers as entered. */ readonly General: "General"; /** * Displays numbers with a thousands separator and two decimal places. */ readonly Number: "Number"; /** * Formats numbers as currency with a currency symbol and two decimal places. */ readonly Currency: "Currency"; /** * Formats numbers as currency, aligning currency symbols and decimal points in a column. */ readonly Accounting: "Accounting"; /** * Displays dates in a short format (e.g., "M/d/yyyy"). */ readonly ShortDate: "Short Date"; /** * Displays dates in a long format (e.g., "dddd, MMMM d, yyyy"). */ readonly LongDate: "Long Date"; /** * Displays dates in a medium format (e.g., "d-mmm-yy"). */ readonly MediumDate: "Medium Date"; /** * Displays times in a short format (e.g., "h:mm AM/PM"). */ readonly ShortTime: "Short Time"; /** * Displays times in a medium format (e.g., "h:mm:ss AM/PM"). */ readonly MediumTime: "Medium Time"; /** * Displays times in a long format (e.g., "h:mm:ss.000 AM/PM"). */ readonly LongTime: "Long Time"; /** * Displays numbers with a thousands separator. */ readonly Comma: "Comma"; /** * Displays numbers as percentages with a percent symbol. */ readonly Percentage: "Percentage"; /** * Displays numbers as fractions. */ readonly Fraction: "Fraction"; /** * Displays numbers in scientific notation. */ readonly Scientific: "Scientific"; /** * Treats the cell content as text, even if it appears to be a number. */ readonly Text: "Text"; /** * A placeholder for special or custom number formats. */ readonly Special: "Special"; /** * Indicates a user-defined or custom number format. */ readonly Custom: "Custom"; }; declare type Type = typeof Type[keyof typeof Type]; /** * Return the union of to 2 bounds. * @remarks * Not null same. */ declare const unionBounds: (a: Bounds, b: Bounds) => Bounds; declare class UnlockEntry { private _c; constructor(coords: IRange.Coords); getCoords(): IRange.Coords; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getShifted} */ getShifted(options: ISpatialMap.ShiftDetails): ISpatialMap.Entry; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getMerged} */ getMerged(_other: this, coords: IRange.Coords, _orientation: IRange.Orientation): this | undefined; /** {@inheritDoc ISpatialMap.IUpdatableEntry.getSplit} */ getSplit(coords: [IRange.Coords, IRange.Coords], _orientation: IRange.Orientation): [this, this] | undefined; } /** * Removes the enclosing quotes from a string. * * @param str The string to unquote. * @returns The unquoted string. */ declare const unquote: (str: string) => string; declare function unshiftAndMergeRuns(runs: ITypes.RunCoordValue[], index: number, amount?: number, options?: MergeRunOptions): ModifiedRuns; declare function unshiftRuns(runs: ITypes.RunCoordValue[], index: number, amount?: number): ModifiedRuns; declare interface UpdateAndCompactOptions { /** * Used when split two runs. * @remarks * Should always return an array with 2 values. */ onSplit?: (value: ITypes.RunCoordValue, offset: number) => T[]; /** * Returns an updated value. If not specified a deep merge is done. * * IMPORTANT - * both prevValue and newValue should be treated as frozen object and not * mutated. * A new value should always be returned. If you want to augment a value * The deepUpdateMethod is offered */ onUpdate?: (prevValue: T | null, newValue: U | null | undefined, run: ITypes.RunCoordValue) => T | null | undefined; /** * Used when attempting to merge two runs. * Returns undefined if the values can't be merged */ onMerge?: (a: T, b: T, sizeA: number, sizeB: number) => T | undefined; /** * Used to determine if a entry should removed. If value is null or undefined it will also be removed. * By default an empty object will not be. */ isCull?: (value: T, min: number, max: number) => boolean; /** * By default merge will freeze object in place to prevent mutations. * Setting this to true will allow for special cases where objects are not immutable. * * @defaultValue false */ inPlace?: boolean; } /** * Will take a list of runs and return the minimum set required. * * @param runs * @param update * @param options @UpdateAndCompactOptions */ declare function updateAndCompactRuns(runs: ITypes.RunCoordValue[], update: ITypes.RunCoordValue, options?: UpdateAndCompactOptions): ModifiedRuns; declare namespace _Utils { export { setOrClear, createRangeInvalidRef, CellHeaderState, RunningHeaderSize, HiddenRun, IndexedHeaders, nocToPx, indexHeaderSizes, findOffset, findIndex, findRunningHiddenRuns, findRunningSpanLength, rangeUnionFromSelection, createRunsFromSelection, runCoordsToRangeCoords, removeOverlappingRuns } } /** * Runs are an ordered list of RunCoords with no overlapping values. * * Examples: * * - Valid - [0, 3][4, 4][8,10] // valid runs of size 4, 1, 3 * * - Invalid - [0, 4][4, 6][8,10] // 4 overlaps * * - Invalid - [0, 3][7, 6][8,10] // second run has incorrect min/max * * - Invalid - [4, 6][0, 5][8,10] // second run is out of order * * - Valid - [] // empty but valid * @param runs A list of RunCoords. */ declare const validateRuns: (runs: RunCoords[]) => boolean; /** * The current version of the SDK. */ export declare const VERSION: string; declare interface ViewEdgeEntry { rowIndex: number; colIndex: number; continuous: IProperties.ICellRanged | null; leftIndex: number; rightIndex: number; overflow: ICell.HorizontalOverflow | null; intersection: RangeState.Intersection; scalar: Scalar | null; style: IStyle; } declare type WellKnownIterator = Iterator; declare type WellKnownIteratorResult = IteratorResult; /** * The Base implementation of {@link IWorkbook}. */ export declare class Workbook implements IWorkbook { protected _options: IWorkbook.ConstructorOptions; protected _createSheet: InternalCreateSheet; protected _createSheetName: (id: number) => string; protected _transactions: ITransaction.IStore; protected _ownTransactions: boolean; protected _transactionsRemoveListener: IListener.Remove; protected _lastTransactionUUID: string; protected _starting: Promise; protected _closed: boolean; protected _initializing: boolean; protected _emitter: ListenerEmitter; protected _scripts: IScript; protected _theme: ITheme; protected _strings: IStringCollection; protected _ownStrings: boolean; protected _styles: IStyleCollection; protected _ownStyles: boolean; protected _resources: IResourceCollection; protected _ownResources: boolean; protected _names: INamedCollection; protected _ownNames: boolean; protected _calculation: ICalculation; protected _ownsCalculation: boolean; protected _view: IWorkbookView; protected _activeSheetOffset: number; protected _sheets: ISheetCollection; protected _sheetOnNameChange: Map void>; protected _sheetOnVisibilityChange: Map void>; protected _sheetOnIndexChange: Map void>; protected _protection: WorkbookProtection; protected _listenerProtection: IListener.Remove; protected _listenerWorkbookView: IListener.Remove; protected _isDate1904: boolean; constructor(options?: IWorkbook.ConstructorOptions); protected _initState(): void; /** {@inheritDoc IWorkbook.getName} */ getName(): string | null; /** {@inheritDoc IWorkbook.setName} */ setName(name: string | null): IWorkbook; /** {@inheritDoc IWorkbook.getView} */ getView(): IWorkbookView; /** {@inheritDoc IWorkbook.setView} */ setView(view: IWorkbookView): this; /** {@inheritDoc IWorkbook.isDate1904} */ isDate1904(): boolean; /** {@inheritDoc IWorkbook.setDate1904} */ setDate1904(date1904: boolean): this; /** {@inheritDoc IWorkbook.getStyles} */ getStyles(): IStyleCollection; /** {@inheritDoc IWorkbook.getResources} */ getResources(): IResourceCollection; /** {@inheritDoc IWorkbook.getTransactions} */ getTransactions(): ITransaction.IStore; /** {@inheritDoc IWorkbook.getStrings} */ getStrings(): IStringCollection; /** {@inheritDoc IWorkbook.getTheme} */ getTheme(): ITheme; /** {@inheritDoc IWorkbook.setTheme} */ setTheme(theme: ITheme): ITheme; /** {@inheritDoc IWorkbook.getSelectedSheetIndex} */ getSelectedSheetIndex(): number; /** {@inheritDoc IWorkbook.getSelectedSheet} */ getSelectedSheet(): ISheet; /** {@inheritDoc IWorkbook.getSheet} */ getSheet(name: string, visibility?: ISheet.Visibility): ISheet; /** {@inheritDoc IWorkbook.getSheetAt} */ getSheetAt(index: number, visibility?: ISheet.Visibility): ISheet; /** {@inheritDoc IWorkbook.getSheets} */ getSheets(): ISheetCollection; /** {@inheritDoc IWorkbook.addSheet} */ addSheet(options?: ISheetCollection.AddOptions | string | number): ISheet; protected _getSheets(visibility?: ISheet.Visibility): ISheet[]; protected _getSheetRefs(visibility?: ISheet.Visibility): SheetRef[]; /* Excluded from this release type: _getSheetRef */ /* Excluded from this release type: _validateNewSheetName */ /** {@inheritDoc IWorkbook.findValidSheetName} */ findValidSheetName(str: string): string; /** {@inheritDoc IWorkbook.isValidSheetNameCharacter} */ isValidSheetNameCharacter(character: string): boolean; /* Excluded from this release type: _addSheetOptions */ /* Excluded from this release type: _nextSheetName */ /* Excluded from this release type: _addSheet */ /* Excluded from this release type: _updateSheetRefStates */ /* Excluded from this release type: _addSheetRef */ /* Excluded from this release type: _adjustRemoveSelectionIfRequired */ /* Excluded from this release type: _adjustSheetNamesIfRequired */ /* Excluded from this release type: _validateDeleteSheet */ /* Excluded from this release type: _findOffsetForId */ /** {@inheritDoc IWorkbook.find} */ find(options: string | ICellRange.FindOptions): Iterator; /** {@inheritDoc IWorkbook.replace} */ replace(cells: Iterator, replace: ICell.Update | ((original: ICell) => ICell.Update), options?: IWorkbook.ReplaceOptions): IWorkbook.ReplaceResults; /* Excluded from this release type: _nextSheetIndex */ /* Excluded from this release type: _prevSheetIndex */ /** {@inheritDoc IWorkbook.getNextSheet} */ getNextSheet(index: number): ISheet; /** {@inheritDoc IWorkbook.getPreviousSheet} */ getPreviousSheet(index: number): ISheet; /* Excluded from this release type: _duplicateSheet */ /* Excluded from this release type: _createRange */ /* Excluded from this release type: _createRanges */ /** {@inheritDoc IWorkbook.getRange} */ getRange(address: ICellRange.Address, options?: ICellRange.GetRangeOptions): ICellRange; /** {@inheritDoc IWorkbook.getRanges} */ getRanges(address: ICellRanges.Address, options?: ICellRange.GetRangeOptions): ICellRanges; /* Excluded from this release type: _activeRangeCoords */ /** {@inheritDoc IWorkbook.getSelectedRange} */ getSelectedRange(options?: ICellRange.GetRangeOptions): ICellRange; /** {@inheritDoc IWorkbook.getSelectedRanges} */ getSelectedRanges(options?: ICellRange.GetRangeOptions): ICellRanges; /** {@inheritDoc IWorkbook.getSelectedCell} */ getSelectedCell(): ICell; /* Excluded from this release type: _rangesAddressToCoords */ /* Excluded from this release type: _validateCoords */ /* Excluded from this release type: _updateSheetRef */ /* Excluded from this release type: _setSheetName */ /* Excluded from this release type: _setSheetVisibility */ /* Excluded from this release type: _moveSheet */ /* Excluded from this release type: _setSelectedSheet */ /** {@inheritDoc IWorkbook.getProtection} */ getProtection(): IWorkbookProtection; /** {@inheritDoc IWorkbook.getNames} */ getNames(): INamedCollection; /** {@inheritDoc IWorkbook.getCalculation} */ getCalculation(): ICalculation; /** {@inheritDoc IWorkbook.getScripts} */ getScripts(): IScript; /* Excluded from this release type: _notifyAllChange */ /** {@inheritDoc IWorkbook.addListeners} */ addListeners(listeners: IWorkbook.IListeners, options?: IListener.Options): IListener.Remove; /* Excluded from this release type: _sheetToWBEvent */ /* Excluded from this release type: _fromJSON */ /* Excluded from this release type: _createScripts */ /** {@inheritDoc IWorkbook.toJSON} */ toJSON(ignoreData?: boolean): Promise; /** {@inheritDoc IWorkbook.isClosed} */ isClosed(): boolean; /** {@inheritDoc IWorkbook.close} */ close(): void; /** {@inheritDoc ITransaction.ITransactional.beginCommit} */ beginCommit(options?: string | ITransaction.OperationOptions): ITransaction; /** {@inheritDoc ITransaction.ITransactional.doBatch} */ doBatch(callback: (commit: ITransaction.ICommit) => R | Promise, options?: string | ITransaction.OperationOptions): R | Promise; /* Excluded from this release type: _beginCommit */ /* Excluded from this release type: _getState */ /* Excluded from this release type: _updateState */ /** {@inheritDoc IWorkbook.options} */ get options(): IWorkbook.ConstructorOptions; get [Symbol.toStringTag](): string; toString(): string; /** {@inheritDoc IWorkbook.isIWorkbook} */ get isIWorkbook(): true; } declare class WorkbookProtection extends DefaultProtection implements IWorkbookProtection { /** {@inheritDoc IProtection.isWindowsAllowed} */ isWindowsAllowed(): boolean; /** {@inheritDoc IProtection.isRevisionAllowed} */ isRevisionAllowed(): boolean; /** {@inheritDoc IWorkbookProtection.isStructureAllowed} */ isStructureAllowed(): boolean; protected _fromJSON(json: IWorkbookProtection.JSON | null): void; protected _toJSON(json: IWorkbookProtection.JSON): IWorkbookProtection.JSON; } /** * Default Workbook View. */ export declare class WorkbookView implements IWorkbookView { private _state; protected _emitter: ListenerEmitter; constructor(options?: IWorkbookView.ConstructorOptions); isShowFormulaBar(): boolean; setShowFormulaBar(newValue: boolean): this; isShowTabs(): boolean; setShowTabs(newValue: boolean): this; getTabRatio(): number; setTabRatio(newValue: number): this; isShowHorizontalScrollbar(): boolean; setShowHorizontalScrollbar(newValue: boolean): this; isShowVerticalScrollbar(): boolean; setShowVerticalScrollbar(newValue: boolean): this; isShowStatusBar(): boolean; setShowStatusBar(newValue: boolean): this; getActiveSheetId(): number; setActiveSheetId(newValue: number): this; /** {@inheritDoc IWorkbookView.addListeners} */ addListeners(listeners: IWorkbookView.IListeners, options?: IListener.Options): IListener.Remove; toJSON(): IWorkbookView.JSON; protected _fromJSON(json: IWorkbookView.JSON, notify?: boolean): void; update(view: Partial, notify?: boolean): void; } export * from "@sheetxl/primitives"; export * from "@sheetxl/utils"; export { }