@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

package/types/src/sheet/SheetCell.d.ts

@@ -0,0 +1,335 @@
+import { ScalarType, InteropScalarType, IRange, Scalar, InteropScalar, IRuntime } from '@sheetxl/primitives';
+import { Size, Rectangle } from '@sheetxl/utils';
+import { ITransaction } from '../transaction';
+import { IProperties, ITypes } from '../type';
+import { NumberFormat } from '../numFmt';
+import { ITextFrame } from '../text';
+import { ITable } from '../table';
+import { IDataValidation } from '../dataValidation';
+import { IHyperlink } from '../hyperlink';
+import { ICalculation } from '../calculation';
+import { IComment } from '../comment';
+import { IStyle, IStyleCollection } from '../style';
+import { ICell, ICellProtection } from '../cell';
+import { ICellRanges, ICellRange } from '../cellRange';
+import { ISheetProtection } from '../sheetProtection';
+import { ISheetHeader } from '../sheetHeader';
+import { ISheet } from './ISheet';
+import { RangeState } from './_SheetStateTypes';
+import { SpillEntry } from '../calculation/spatial';
+import { CellStyleUpdater } from './style/SheetCellStyle';
+import { ICalcGrid } from '../calculation/grid';
+import { IConditionalFormat } from '../conditionalFormat';
+/**
+ * CellModifiers with all functions removed and all properties set and a type.
+ */
+export interface ResolvedCellModifiers {
+    type: ScalarType | undefined;
+    value: Scalar | null | undefined;
+    style: IStyle.Update | null | undefined;
+    hyperlink: IHyperlink.Update | undefined;
+    formula: string | null | undefined;
+    stringToParse: string | null | undefined;
+}
+interface Cache<K, V> {
+    set(key: K, value: V): void;
+    get(key: K): V | undefined;
+}
+/**
+ * Converts a `ICell.Update` into a `ResolvedCellModifiers` with no functions.
+ *
+ * * Returns a reusable object.
+ * * Will never return null.
+ *
+ * This resolves various update rules for cells.
+ * Note that this doesn't take a tv because it does a full replacement.
+ *
+ * If fromString is null then then strings will be processed without any
+ * special conditioning and this will be returned.
+ *
+ * // TODO - reuse ResolvedCellModifiers for createCellModifiersFromString.
+ * // TODO - remove style dependency and see if we can remove it.
+ */
+export declare function resolveCellModifiers(runtime: IRuntime, update: ICell.Update, optionsFromString?: ICell.ModifiersFromStringOptions | null, resolvedStringCache?: Map<string, ICell.Modifiers> | null, // assumes the same fromStringOptions is used
+isParsingCustom?: boolean): ResolvedCellModifiers | undefined;
+export declare function csOverflowable(type: ScalarType, style: IStyle, prev?: boolean, next?: boolean): boolean;
+/**
+ * Updates the overflow calc and returns a range if overflowed
+ * @internal
+ */
+export declare function calcTextOverflow(rowIndex: number, colIndex: number, type: ScalarType, style: IStyle, value: Scalar, prev: IRange.CellCoords | null, next: IRange.CellCoords | null, continuousCoords: IRange.Coords | null, cellOptions: SheetCellOptions): ICell.HorizontalOverflow | null;
+/** Guaranteed to never return null */
+export declare function csStyle(value: Scalar, range: IRange.Coords | null, intersection: RangeState.Intersection | null, options: SheetCellOptions, direct: boolean, 
+/**
+ * The range the style was QUERIED for, when wider than `range` (which is the cell it
+ * materializes at). Only the inner border rules read it — see `CreateCellStyleOptions.extent`.
+ */
+extent?: IRange.Coords): IStyle;
+/**
+ * Is `coords` spilled INTO — covered by a spill but not the ANCHOR that owns it?
+ *
+ * @remarks
+ * The one definition of that test: {@link SheetCell.isSpillOverflow} answers it for a materialized
+ * cell, autoFit's scan answers it straight off a `RangeState` intersection (such a cell paints BLANK
+ * in formula view). They must not drift, so neither owns the loop.
+ *
+ * `spills` is the raw intersection value, which is a single entry far more often than an array —
+ * that case is handled inline rather than being wrapped, so no caller allocates to ask.
+ */
+export declare function csIsSpillOverflow(spills: SpillEntry | SpillEntry[] | null | undefined, coords: IRange.CellCoords): boolean;
+/**
+ * Formula-view inputs for {@link csBestFit} — what `showFormulas` changes about a measure.
+ *
+ * @remarks
+ * Formula view has two cases, and this mirrors the SAME text production the renderer's frame uses
+ * (`SheetCell.getTextFrame(showFormula)`), so measurement cannot drift from paint:
+ * - a formula cell measures `'=' + formulaText` verbatim ({@link formulaText});
+ * - every other cell measures its **raw value** with Excel's number spelling — Excel strips
+ *   formatting entirely here (measured: a date cell shows `45292`, a percent `0.125`, a `0.00`-
+ *   formatted `1234.5` shows `1234.5`). That is `csTextFrame`'s `disabledFormatting` path.
+ */
+export interface BestFitViewOptions {
+    /**
+     * Formula view is active: measure values raw (no number format) and never substitute a
+     * dynamic/scientific width — formula view paints what it paints.
+     * @defaultValue false
+     */
+    formulaView?: boolean;
+    /**
+     * Measure this text verbatim — no number format, no wrap, no overflow. Set for a formula cell in
+     * formula view; the `type`/`value` arguments are then ignored for text production.
+     */
+    formulaText?: string;
+}
+export declare function csBestFit(type: ScalarType, style: IStyle, value: Scalar, options: SheetCellOptions, colWidth: number, isMinContent: boolean, isRowOnly: boolean, // if true we only measure the height
+customHash?: string | null, cache?: Cache<string, Readonly<Partial<Size>>>, view?: BestFitViewOptions): Readonly<Partial<Size>> | null;
+/**
+ * A coords-keyed cache of resolved `ICell`s for hot read paths (rendering).
+ *
+ * @remarks
+ * Entries are valid only for the current sheet revision and must be cleared on any mutation
+ * (see `invalidateCaches` in `Sheet`). `LRUCache` satisfies this shape.
+ */
+export interface RenderCellCache {
+    get(key: number): ICell | undefined;
+    set(key: number, value: ICell): void;
+    clear(): void;
+}
+export interface SheetCellOptions {
+    runtime: IRuntime;
+    getRange(address: ICellRange.Address): ICellRange | null;
+    getRanges: (address: ICellRanges.Address) => ICellRanges | null;
+    getCalcGrid?(): ICalcGrid;
+    /**
+     * Calculation-graph neighbors — the same engine `ICellRange` uses, which is the point: the calc
+     * grid answers in calc currency (grid stableIds, and virtual grids for named formulas) and it is
+     * this seam that translates them to sheet names and drops what is not a sheet. Going at the grid
+     * directly leaks a stableId into an address, where it prints as `#REF!`.
+     */
+    dependencyRanges?(coords: IRange.Coords, kind: 'precedents' | 'dependents', direct: boolean): ICellRanges | null;
+    doBatchCalcGrid?(callback: (calcGrid: ICalcGrid) => IRange.Coords, options?: string | ITransaction.OperationOptions): void;
+    /**
+     * Resolve a sheet's internal stableId (rename-safe) to its display name, or `null`. Threaded into
+     * {@link Formula.ConstructorOptions} so a committed formula's cross-sheet references resolve at the
+     * `getRanges` boundary instead of throwing. See {@link Formula._resolveReferences}.
+     */
+    resolveSheetScope?(stableId: string): string | null;
+    /**
+     * Formula AutoCorrect for a committed formula — threaded (via the {@link SheetCell.getFormula}
+     * cast) into {@link Formula.ConstructorOptions.autoCorrect}, whose contract this must match.
+     */
+    autoCorrect?(text: string, coords?: Partial<IRange.CellCoords>): ICalculation.IFormula | null;
+    /**
+     * Filled-copy compiler for a committed formula — threaded the same way as {@link autoCorrect},
+     * into {@link Formula.ConstructorOptions.createAt}, whose contract this must match.
+     */
+    createAt?(text: string, coords: IRange.CellCoords): ICalculation.IFormula | null;
+    sheet: ISheet;
+    styles: IStyleCollection;
+    normalStyleRanged: IProperties.ICellRanged<IStyle.Properties>;
+    nextContentful(cell: IRange.CellCoords, limit: number, isLeft?: boolean): number;
+    getProtection(): ISheetProtection;
+    colHeaders?: ISheetHeader;
+    styleUpdater?: CellStyleUpdater;
+    opener(url: string, options?: ICellRange.SelectOptions | null, target?: string, features?: string): Promise<boolean>;
+    /**
+     * Shared cross-render cache of resolved cells, consulted only when an iterator opts in via
+     * `cacheCells`. Populated/read by the render path; cleared on any sheet mutation.
+     */
+    renderCellCache?: RenderCellCache;
+}
+export declare class SheetCell implements ICell {
+    protected _ri: RangeState.Intersection | null;
+    protected _p: IRange.CellCoords | null;
+    protected _n: IRange.CellCoords | null;
+    protected _to: ICell.HorizontalOverflow | null | undefined;
+    protected _r: IRuntime;
+    protected _options: SheetCellOptions;
+    protected _coords: IRange.CellCoords | null;
+    protected _t: ScalarType;
+    protected _v: Scalar;
+    protected _d: Date | null | undefined;
+    protected _column: ITable.IColumn | null | undefined;
+    protected _cd: Readonly<IConditionalFormat.Decorations> | undefined;
+    protected _s: IStyle | undefined;
+    protected _sd: IStyle | undefined;
+    constructor(options: SheetCellOptions, coords: IRange.CellCoords | null, type?: ScalarType, value?: Scalar, intersection?: RangeState.Intersection | null, p?: IRange.CellCoords | null, // prev
+    n?: IRange.CellCoords | null);
+    /** {@inheritDoc ICell.getRange} */
+    getRange(): ICellRange;
+    /** {@inheritDoc ICell.isEqual} */
+    isEqual(other: ICell): boolean;
+    /** {@inheritDoc ICell.getCoords} */
+    getCoords(): IRange.CellCoords;
+    /** {@inheritDoc ICell.getAddress} */
+    getAddress(r1c1?: boolean): string;
+    /** {@inheritDoc ICell.getSheet} */
+    getSheet(): ISheet;
+    /** {@inheritDoc ICell.select} */
+    select(options?: ITypes.SelectOptions): Promise<boolean>;
+    /** {@inheritDoc ICell.getColumn} */
+    getColumn(): ITable.IColumn | null;
+    /** {@inheritDoc ICell.getTable} */
+    getTable(): ITable | null;
+    /** {@inheritDoc ICell.getDataValidation} */
+    getDataValidation(): IDataValidation | null;
+    /** {@inheritDoc ICell.getConditionalDecorations} */
+    getConditionalDecorations(): Readonly<IConditionalFormat.Decorations>;
+    /** {@inheritDoc ICell.getProtection} */
+    getProtection(): ICellProtection;
+    /** {@inheritDoc ICell.getTextOverflow} */
+    getTextOverflow(): Readonly<ICell.HorizontalOverflow> | null;
+    /** {@inheritDoc ICell.getRenderHorizontalAlignment} */
+    getRenderHorizontalAlignment(): ITextFrame.HorizontalAlignment;
+    /** {@inheritDoc ICell.isEmpty} */
+    isEmpty(): boolean;
+    /** {@inheritDoc ICell.getExtrusions} */
+    getExtrusions(): IRange.Coords | null;
+    /** {@inheritDoc ICell.isEditAllowed} */
+    isEditAllowed(): boolean;
+    /** {@inheritDoc ICell.isFormulaHidden} */
+    isFormulaHidden(): boolean;
+    /** {@inheritDoc ICell.isContentful} */
+    isContentful(): boolean;
+    /** {@inheritDoc ICell.getBestFit} */
+    getBestFit(colWidth?: number, minContent?: boolean): Readonly<Partial<Size>> | null;
+    /** {@inheritDoc ICell.getInsets} */
+    getInsets(): Rectangle;
+    /**
+     * The leading-edge width an icon-set decoration reserves, or `0` for a cell without one.
+     *
+     * @remarks
+     * The icon is a square of the cell's LINE HEIGHT drawn at the leading inset — where the first
+     * glyph of left-aligned text would start — and the text resumes one leading inset after it. So
+     * the reservation is the icon plus that second inset, and both terms are already font-sized: a
+     * larger font reserves proportionally more and gets a proportionally larger icon.
+     *
+     * Both are properties of the STYLE, never of the value, so the gutter cannot shift as the cell is
+     * edited — which is what lets whatever draws the icon place it from the same two numbers instead
+     * of being told where the gutter ended. Measured on the empty string because the measurer keeps
+     * THAT one globally, keyed by font: the line height is a font metric, and reading it this way
+     * outlives the styles it is read through (see {@link calcAccountingBottomInset}, same idiom).
+     */
+    protected _iconGutter(): number;
+    /** {@inheritDoc ICell.getTextFrame} */
+    getTextFrame(showFormula?: boolean): ITextFrame | null;
+    /** {@inheritDoc ICell.getTextPlacement} */
+    getTextPlacement(size: Size, useFormula?: boolean): ICell.TextPlacement | null;
+    /** {@inheritDoc ICell.getFormula} */
+    getFormula(): ICalculation.IFormula | null;
+    /** {@inheritDoc ICell.getFormulaText} */
+    getFormulaText(options?: ICalculation.FormulaTextOptions): string | null;
+    /** {@inheritDoc ICell.getCalculationStatus} */
+    getCalculationStatus(): ICalculation.ResultStatus;
+    /**
+     * A cell's graph query IS the range query over its 1×1 — same engine, same translation out of
+     * calc currency. Reaching for the calc grid here instead put a grid stableId on a public address
+     * (`'Sheet2-d8a94094-…'!C3`, rendered `#REF!`) and reported a named formula's virtual cell as a
+     * phantom `A1` on whatever sheet was asked.
+     * @internal
+     */
+    private _dependencyRanges;
+    /** {@inheritDoc ICell.getDirectDependents} */
+    getDirectDependents(): ICellRanges;
+    /** {@inheritDoc ICell.getDirectPrecedents} */
+    getDirectPrecedents(): ICellRanges;
+    /** {@inheritDoc ICell.getDependents} */
+    getDependents(): ICellRanges;
+    /** {@inheritDoc ICell.getPrecedents} */
+    getPrecedents(): ICellRanges;
+    /** {@inheritDoc ICell.getValue} */
+    getValue(): Scalar;
+    /** {@inheritDoc ICell.getType} */
+    getType(): ScalarType;
+    /** {@inheritDoc ICell.getInteropValue} */
+    getInteropValue(): InteropScalar;
+    /** {@inheritDoc ICell.getInteropType} */
+    getInteropType(): InteropScalarType;
+    /** {@inheritDoc ICell.getStyle} */
+    getStyle(direct?: boolean): IStyle;
+    /** {@inheritDoc ICell.createCell} */
+    createCell(update: ICell.Update): ICell;
+    /**
+     * A copy of this cell that reports `coords` as its merge.
+     *
+     * @remarks
+     * For projections — an `autoFill` preview — where the merged block does not exist on the sheet yet,
+     * so no state map can supply it. Everything that reads merge state off a cell
+     * ({@link ICell.getRange}, {@link ICell.getSpans}, {@link ICell.getExtrusions},
+     * {@link ICell.isTopLeft}) then reports the projected block.
+     * @internal
+     */
+    _withProjectedMerge(coords: IRange.Coords): ICell;
+    /** {@inheritDoc ICell.getNumberFormat} */
+    getNumberFormat(numberFormat?: string): NumberFormat.Parsed;
+    /** {@inheritDoc ICell.getDate} */
+    getDate(): Date | null;
+    /** {@inheritDoc ICell.getText} */
+    getText(options?: ICell.GetTextOptions): string;
+    /** {@inheritDoc ICell.getComments} */
+    getComments(): Readonly<IComment.Properties>;
+    /** {@inheritDoc ICell.getHyperlink} */
+    getHyperlink(): IHyperlink | null;
+    /** {@inheritDoc ICell.getErrors} */
+    getErrors(): readonly string[];
+    /** {@inheritDoc ICell.getWarnings} */
+    getWarnings(): readonly string[];
+    /** {@inheritDoc ICell.getSpans} */
+    getSpans(): Readonly<Size>;
+    /** {@inheritDoc ICell.isTopLeft} */
+    isTopLeft(): boolean;
+    /** {@inheritDoc ICell.getSpill} */
+    getSpill(): ICellRange | null;
+    /** {@inheritDoc ICell.isSpillOverflow} */
+    isSpillOverflow(): boolean;
+    get [Symbol.toStringTag](): string;
+    /** {@inheritDoc ICell.toString} */
+    toString(): string;
+    /** {@inheritDoc ICell.isICell} */
+    get isICell(): true;
+}
+/**
+ * Default cell when there is no value. We never return null.
+ * Needed to ensure we pass the correct options
+ * @remarks
+ * Only used for temporary cells with no coordinates.
+ */
+export declare class EmptyCell extends SheetCell {
+    constructor(options: SheetCellOptions);
+    /** {@inheritDoc ICell.isEmpty} */
+    isEmpty(): boolean;
+    /** {@inheritDoc ICell.isContentful} */
+    isContentful(): boolean;
+    toString(): string;
+}
+/**
+ * Temporary cell
+ *
+ * @remarks
+ * Only used for temporary cells with no coordinates.
+ */
+export declare class TemporaryCell extends SheetCell {
+    getAddress(r1c1?: boolean): string;
+}
+export {};
+//# sourceMappingURL=SheetCell.d.ts.map

package/types/src/sheet/SheetCollection.d.ts

@@ -0,0 +1,18 @@
+import { ISheetCollection } from './ISheetCollection';
+import { ISheet } from './ISheet';
+export declare class SheetCollection implements ISheetCollection {
+    private _add;
+    private _get;
+    constructor(add: (options: ISheetCollection.AddOptions | string | number) => ISheet, get: (name?: string, visibility?: ISheet.Visibility) => ISheet[]);
+    /** {@inheritDoc ISheetCollection.add} */
+    add(options?: ISheetCollection.AddOptions | string | number): ISheet;
+    /** {@inheritDoc ICollection.[Symbol.iterator]} */
+    [Symbol.iterator](): IterableIterator<ISheet>;
+    /** {@inheritDoc ISheetCollection.getItems} */
+    getItems(options?: ISheetCollection.GetItemsOptions): ISheet[];
+    /** {@inheritDoc ISheetCollection.getByName} */
+    getByName(name: string): ISheet;
+    /** {@inheritDoc ISheetCollection.getCount} */
+    getCount(): number;
+}
+//# sourceMappingURL=SheetCollection.d.ts.map