@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/cellRange/ICellRanges.d.ts

@@ -1,9 +1,9 @@
 import { Scalar, IRange, IRangeStats } from '@sheetxl/primitives';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
-import { IStyle } from '../style';
+import { ICellStyle } from '../style';
 import { ICell } from '../cell';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { ICalculation } from '../calculation';
 import { ICellRange } from './ICellRange';
 import { ICellHeaderRange } from './ICellHeaderRange';
@@ -19,16 +19,16 @@ export interface ICellRanges {
      */
     getMerges(): IRange.Coords[];
     /**
-     * {@inheritDoc ICellRange.getSheet}
+     * {@inheritDoc ICellRange.getWorksheet}
      */
-    getSheet(): ISheet;
+    getWorksheet(): IWorksheet;
     /**
      * Returns the style for the anchor of the ranges.
      *
      * @see
      * {@link ICellRange.getStyle}
      */
-    getStyle(): IStyle;
+    getStyle(): ICellStyle;
     /**
      * {@inheritDoc ICellRange.find}
      */
@@ -150,11 +150,11 @@ export interface ICellRanges {
      * chain to find all contributing ranges; if `false` (the default) only the direct inputs
      * are returned.
      * @remarks
-     * Returns `null` if the ranges have no precedents.
+     * Resolves `null` if the ranges have no precedents.
      * @see
      * {@link ICellRanges.getDirectPrecedents} / {@link ICellRanges.getPrecedents} for the single-cell equivalents.
      */
-    getPrecedents(entireSet?: boolean): ICellRanges | null;
+    getPrecedents(entireSet?: boolean): Promise<ICellRanges | null>;
     /**
      * Returns the ranges whose formulas reference these ranges.
      *
@@ -162,11 +162,11 @@ export interface ICellRanges {
      * chain to find the total impact of a value change; if `false` (the default) only the
      * immediate consumers are returned.
      * @remarks
-     * Returns `null` if the ranges have no dependents.
+     * Resolves `null` if the ranges have no dependents.
      * @see
      * {@link ICellRanges.getDirectDependents} / {@link ICellRanges.getDependents} for the single-cell equivalents.
      */
-    getDependents(entireSet?: boolean): ICellRanges | null;
+    getDependents(entireSet?: boolean): Promise<ICellRanges | null>;
     /**
      * {@inheritDoc ICellRange.getVisible}
      */
@@ -188,6 +188,11 @@ export interface ICellRanges {
      * the string as given, and choose the SOURCE that carries the scoping you want.
      */
     getAddress(r1c1?: boolean): string;
+    /**
+     * @deprecated Use {@link getAddress}.
+     * @hidden
+     */
+    getA1(): string;
     /**
      * {@inheritDoc ICellRange.getCounts}
      */
@@ -218,35 +223,35 @@ export interface ICellRanges {
      */
     isOverlapping(): boolean;
     /**
-     * Returns `true` if all of the the ranges have selected all of the rows.
+     * Returns `true` if every range is entire rows, such as `2:4`.
      *
      * @remarks
-     * This is different from `isEntireRowsAny` in that it will return `true` if 'ALL' of the
-     * ranges have isEntireRows `true`.
+     * {@link isEntireRowsAny} asks the same of any one range.
+     *
+     * @see {@link ICellRange.isEntireRows}
      */
     isEntireRows(): boolean;
     /**
-     * Returns `true` if any of the ranges have selected all of the rows.
+     * Returns `true` if any range is entire rows, such as `2:4`.
      *
      * @remarks
-     * This is different from `isEntireRows` in that it it will return true if 'ANY' of the
-     * ranges have isEntireRows `true`.
+     * {@link isEntireRows} asks the same of every range.
      */
     isEntireRowsAny(): boolean;
     /**
-     * Returns `true` if all of the the ranges have selected all of the columns.
+     * Returns `true` if every range is entire columns, such as `B:D`.
      *
      * @remarks
-     * This is different from `isEntireColumnsAny` in that it will return `true` if 'ALL' of the
-     * ranges have isEntireColumns `true`.
+     * {@link isEntireColumnsAny} asks the same of any one range.
+     *
+     * @see {@link ICellRange.isEntireColumns}
      */
     isEntireColumns(): boolean;
     /**
-     * Returns `true` if any of the ranges have selected all of the columns.
+     * Returns `true` if any range is entire columns, such as `B:D`.
      *
      * @remarks
-     * This is different from `isEntireColumns` in that it will return `true` if 'ANY' of the
-     * ranges have isEntireColumns `true`.
+     * {@link isEntireColumns} asks the same of every range.
      */
     isEntireColumnsAny(): boolean;
     /**
@@ -334,8 +339,10 @@ export interface ICellRanges {
     /**
      * {@link ICellRange.addWatch} across every area, as ONE expression authored at a shared origin.
      *
-     * @param formula An expression, or a formula, authored at the FIRST area's top-left.
+     * @param formula An expression, or a formula, authored at the top-left of the bounding box of
+     *                every area — which need not be a cell of any area.
      * @param callback Receives each area's results separately, with the area's index and the area.
+     * @param options How each cell is evaluated; see {@link ICellRange.WatchOptions}.
      *
      * @returns A callback removing every area's watch.
      *
@@ -343,7 +350,7 @@ export interface ICellRanges {
      * This is the form a multi-area rule wants, and the reason it exists is the anchor. A
      * conditional format over `E5:F6 E10:F11` stores ONE formula, authored at the sqref origin
      * `E5` — so `E10` must evaluate that formula FILLED to `E10`, an anchor no cell in the second
-     * area carries. Compiling each area against its own top-left instead makes area two read area
+     * area carries. Over `E7:F7 B11:C11` the origin is `B7`: the areas' order does not matter. Compiling each area against its own top-left instead makes area two read area
      * one's cells: `E5>5` read from `E10` means "is the cell five rows up greater than 5".
      *
      * So the fill lives here, where the areas are known to belong to one rule, rather than on
@@ -353,7 +360,7 @@ export interface ICellRanges {
      * One watch per area — deliberately not pooled by expression. The callback therefore fires per
      * area, and an edit touching two of them delivers twice.
      */
-    addWatch(formula: ICalculation.IFormula | string, callback: ICellRanges.WatchCallback): IListener.Remove;
+    addWatch(formula: ICalculation.IFormula | string, callback: ICellRanges.WatchCallback, options?: ICellRange.WatchOptions): IListener.Remove;
     /**
      * Returns an iterator that allows you to iterate over the individual values within the range.
      *

package/types/src/chart/Chart.d.ts

@@ -1,27 +1,262 @@
+import { Bounds, Point, Size } from '@sheetxl/utils';
 import { IResource, IResourceCollection } from '../resource';
-import { IModel, AbstractModel } from '../model';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { AbstractMovableContent } from '../movable/AbstractMovableContent';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { IEmbeddedPart } from '../io';
 import { IChart } from './IChart';
-interface State extends AbstractModel.State {
+import { ChartModel } from './model/ChartModel';
+import { ChartLayout } from './layout/ChartLayout';
+import { TextMeasurer } from './layout/TextMeasurer';
+import { createModelFromSource, newChartType, customKindOf } from './_ChartSource';
+import { ITextBoxStyle } from '../shape/ITextBoxStyle';
+export { createModelFromSource, newChartType, customKindOf };
+export { setCustomKind } from './model/_Edits';
+interface State extends AbstractMovableContent.State {
     data?: any;
 }
 /**
  * Implementation for {@link IChart}.
  */
-export declare class Chart extends AbstractModel<State, IChart.JSON> implements IChart {
+export declare class Chart extends AbstractMovableContent<State, IChart.JSON, IChart.Events> implements IChart {
+    /**
+     * The chart's document part. Held beside {@link State.data} rather than in it because the
+     * resources it carries are model references, not JSON, and have to be re-persisted per save.
+     */
+    protected _part: IEmbeddedPart | null;
+    /** The model `_read` was read from. */
+    private _readSource;
+    private _read;
+    /** The model {@link _part}'s markup states: the markup stands only while the chart says the same. */
+    private _partModel;
+    private _series;
+    /** The parts the API sets, each a view onto the model; made once, they hold across edits. */
+    private _parts;
+    /** The model's formulas as the engine holds them, by {@link ChartFacts.slots} index. */
+    private _held;
+    /** The model {@link _held} holds the formulas of. */
+    private _heldModel;
+    /** The holds of models the chart had before, so an undo holds them again as they read then. */
+    private _heldBefore;
+    /** Whether the chart is in a workbook, whose engine holds its formulas. */
+    private _canHold;
+    /** The workbook's styles, whose theme the chart's colors and fonts resolve against. */
+    private _getStyles;
     constructor(options: Chart.ConstructorOptions);
+    /**
+     * Hands every formula of the model to the engine, in slot order, and lets go of the formulas of
+     * the model it held before; a model held before (an undone `setData`) is held again from the
+     * formulas as they read then. A chart outside a workbook has no engine and reads the model as it is.
+     */
+    private _syncHolds;
     /** {@inheritDoc IModel.getType} */
     getType(): string;
+    /** The chart's model, or `null` for a chart that has none. */
+    protected _getModel(): ChartModel.ChartSpace | null;
+    /** Read once, on first ask; most charts are never asked. */
+    private _getRead;
+    /** What the read API answers from, or `null` for a chart with no model. */
+    private _getFacts;
+    /** The engine's text for `slot` once something has moved what it names, else `null`: the model's own text stands. */
+    private _movedAt;
+    /** The formula in `slot` as it is now: the engine's, and until it holds one the model's own. */
+    private _formulaAt;
+    private _formulaOf;
+    /** The cells the formula in `slot` names, when it is one plain reference. */
+    private _rangeAt;
+    /** Text read from a cell is the cell's text now; what the file cached answers where that cannot be read. */
+    private _textOf;
     /** {@inheritDoc IChart.getChartTitle} */
     getChartTitle(): string | null;
-    /** {@inheritDoc IChart.getChartTye} */
+    /** {@inheritDoc IChart.getChartType} */
     getChartType(): string;
-    /** {@inheritDoc Movable.Content.getDescription} */
-    getDescription(): string;
+    /** The parts of the chart, and what they read and write through. */
+    private _getParts;
+    /** The series parts, in plot order. */
+    private _seriesParts;
+    /** {@inheritDoc IChart.setChartType} */
+    setChartType(type: IChart.Type | string, options?: ITransaction.OperationOptions): this;
+    /** The whole chart given `type`: every series' point count for a pie's slices and a bubble's sizes. */
+    private _chartTypeEdit;
+    /** {@inheritDoc IChart.addSeries} */
+    addSeries(name?: string | ICellRange, index?: number, options?: ITransaction.OperationOptions): IChart.ISeries;
+    /** {@inheritDoc IChart.getGroups} */
+    getGroups(): readonly IChart.IChartGroup[];
+    /** {@inheritDoc IChart.setSeriesBy} */
+    setSeriesBy(seriesBy: 'rows' | 'columns', options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IChart.getPlotVisibleOnly} */
+    getPlotVisibleOnly(): boolean;
+    /** {@inheritDoc IChart.setPlotVisibleOnly} */
+    setPlotVisibleOnly(plotVisibleOnly: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IChart.getDataLabels} */
+    getDataLabels(): IChart.IDataLabels;
+    /** {@inheritDoc IChart.getPlotArea} */
+    getPlotArea(): IChart.IPlotArea;
+    /** {@inheritDoc IChart.getElementAt} */
+    getElementAt(point: Point, layout?: ChartLayout | Size): IChart.IElement | null;
+    /** {@inheritDoc IChart.getElementBounds} */
+    getElementBounds(element: IChart.IElement | string, layout?: ChartLayout | Size): Bounds | null;
+    /** The names of each layout hit-tested, kept with the layout: they are the model's at the time it was laid out. */
+    private static _hitNamesOf;
+    /** `layout` as given, or the chart laid out at the size given, or at its movable's bounds. */
+    private _layoutFor;
+    /** What the layout's ids are called as element paths. */
+    private _hitNames;
+    private _nameHits;
+    /** {@inheritDoc IChart.getDataTable} */
+    getDataTable(): IChart.IDataTable;
+    /** {@inheritDoc IChart.getChartArea} */
+    getChartArea(): IChart.IChartArea;
+    /** {@inheritDoc IChart.getStyle} */
+    getStyle(): ITextBoxStyle;
+    /** {@inheritDoc IChart.getChartStyle} */
+    getChartStyle(): number;
+    /** {@inheritDoc IChart.getRoundedCorners} */
+    getRoundedCorners(): boolean;
+    /** {@inheritDoc IChart.setRoundedCorners} */
+    setRoundedCorners(rounded: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IChart.getElement} */
+    getElement(path: string): IChart.IElement | null;
+    /** {@inheritDoc IChart.getElements} */
+    getElements(): readonly IChart.IElement[];
+    /** {@inheritDoc IChart.setElement} */
+    setElement(element: IChart.Element, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IChart.addChartSeries} */
+    addChartSeries(name?: string | ICellRange, index?: number, options?: ITransaction.OperationOptions): IChart.ISeries;
+    /** {@inheritDoc IChart.getChartGroups} */
+    getChartGroups(): readonly IChart.IChartGroup[];
+    /** {@inheritDoc IChart.getSeries} */
+    getSeries(): readonly IChart.ISeries[];
+    /** {@inheritDoc IChart.getAxes} */
+    getAxes(): IChart.IAxes;
+    /** {@inheritDoc IChart.getTitle} */
+    getTitle(): IChart.ITitle;
+    /** {@inheritDoc IChart.getLegend} */
+    getLegend(): IChart.ILegend;
+    /** {@inheritDoc IChart.getSeriesBy} */
+    getSeriesBy(): 'rows' | 'columns';
+    /** {@inheritDoc IChart.getDisplayBlanksAs} */
+    getDisplayBlanksAs(): IChart.DisplayBlanksAs;
+    /** {@inheritDoc IChart.setDisplayBlanksAs} */
+    setDisplayBlanksAs(value: IChart.DisplayBlanksAs, options?: ITransaction.OperationOptions): this;
+    private _blanksEdit;
+    /** {@inheritDoc IChart.update} */
+    update(update: IChart.Update, options?: ITransaction.OperationOptions): this;
+    /**
+     * Applies `edit` to the model as one step to undo, from the formulas as the engine holds them
+     * now: an edit starts from where they have moved to. The chart holds the formulas of the edited
+     * model; an undo holds the old ones again.
+     *
+     * @throws ExpectedError for a pivot chart, which changes with its pivot table, and for a chart of
+     * a type not yet edited (the 2016 types) unless `anyType`: the title, the legend and the type are
+     * edited on every type.
+     */
+    private _editModel;
+    /** The chart resolved against its theme and its cells now. */
+    private _resolve;
+    private _styles;
+    /** {@inheritDoc IChart.getPivotSource} */
+    getPivotSource(): string | null;
+    /** {@inheritDoc IChart.getLayout} */
+    getLayout(size?: {
+        width: number;
+        height: number;
+    }): ChartLayout | null;
+    /**
+     * {@link getLayout}, measuring the chart's text with `measurer` instead of the shared font
+     * tables.
+     * @internal
+     */
+    _getLayout(size?: {
+        width: number;
+        height: number;
+    }, measurer?: TextMeasurer): ChartLayout | null;
+    /** {@inheritDoc IChart.setData} */
+    setData(source: ICellRange | ICellRanges | string, seriesBy?: IChart.SeriesBy, options?: ITransaction.OperationOptions): this;
+    /** @internal */
+    protected _processRestoreOrRevert(state: State, commit: ITransaction.ICommit): void;
+    /** The styles a chart outside a workbook resolves against. */
+    private static _defaultStyles;
+    /**
+     * The cells a reference of the model names, read for plotting: the engine's formula for its
+     * slot, when that is one plain range of this workbook with cells behind it. Rows and columns
+     * named entire are cut to the sheet's used cells.
+     */
+    private _plotRange;
+    /** The one plain range of the defined name `expression` is, or `null` when it is no name or holds anything else. */
+    private _namedRange;
+    /**
+     * The cells a reference of the model names, as the chart reads them: hidden rows and columns
+     * left out unless the chart plots them (`plotVisOnly`), measured to be what Excel both plots and
+     * caches. `null` where they cannot be read.
+     */
+    private _readCells;
+    /** A cell as its text: a number formatted by its own cell's format, the rest as Excel shows it. */
+    private _cellText;
+    /**
+     * What the chart's cells hold now, for resolve (DESIGN-CHART §3.3): values, categories, names
+     * and the first cell's number format are read from the cells the engine's formulas name, in the
+     * order Excel reads a range (column by column, {@link inReadOrder}). Where the cells cannot be
+     * read, the model's cache answers.
+     */
+    private _dataReader;
+    /** How many listeners want `onLayoutChange`. */
+    private _layoutListeners;
+    /** What the layout depends on, listened to only while something listens for `onLayoutChange`. */
+    private _layoutSources;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IChart.IListeners, options?: IListener.Options): IListener.Remove;
+    /** The cells the chart plots, listened to by area, keyed by sheet and coords. */
+    private _dataListeners;
+    /** The sheets those cells are on, listened to for their hidden rows and columns. */
+    private _sheetListeners;
+    /** An `onLayoutChange` for a cell change is queued: one per commit, however many cells it reached. */
+    private _layoutQueued;
+    /**
+     * Listens to the chart, its movable, its theme, the fonts and the cells it plots while
+     * `onLayoutChange` has listeners.
+     */
+    private _watchLayout;
+    private _releaseLayoutSources;
+    /**
+     * One `onLayoutChange` for all the cells a commit changed: the sheet tells each area's listener
+     * in turn, synchronously, and the chart answers once they are all told.
+     */
+    private _queueLayoutChange;
+    /**
+     * Listens to each area the chart's references name now, and to its sheet for hidden rows and
+     * columns. An area still named keeps its listener - one an insert moved re-keys itself from the
+     * move it is told of - a new one is listened to, a gone one let go.
+     */
+    private _syncDataListeners;
+    /** {@inheritDoc ITransaction.ITransactional.close} */
+    close(): void;
+    /**
+     * The cache `reference` holds when read now, as Excel writes it (DESIGN-CHART §3.3, measured
+     * 2026-10-16), or `null` where its cells cannot be read and the cache it has stands.
+     */
+    private _cacheOf;
+    /**
+     * A multi-level category cache: one level per column, the innermost (the last) first, each
+     * listing its non-blank cells by row. Categories laid out in rows run the other way. Which way
+     * they run is the way the cache read from the file does; a cache that says neither stands.
+     */
+    private _levelsCache;
     /** {@inheritDoc Movable.Content.toJSON} */
-    toJSON(_toResourceId?: (resource: IResource) => number | null): IChart.JSON | null;
-    /** {@inheritDoc Movable.Content.getTypeDescription} */
+    toJSON(toResourceId?: (resource: IResource) => number | null): IChart.JSON | null;
+    /** {@inheritDoc IMovable.IContent.getTypeDescription} */
     getTypeDescription(): string;
+    /** {@inheritDoc IChart.isIChart} */
+    get isIChart(): true;
 }
+/**
+ * A number as Excel writes it into a chart cache (measured 2026-10-16, `probe-chart-values.ps1`
+ * W3): its shortest digits when 15 or fewer say it, else 17; in exponent form (`1E-3`, `1E+16`)
+ * below 0.01 and from 10^16 up. Excel sometimes writes 17 digits where fewer say the same number
+ * (`1.0000000000000001E-5`); either reads back as the same number.
+ */
+export declare const cacheNumberText: (value: number) => string;
 /**
  * Interfaces for creating `Chart` items.
  *
@@ -34,20 +269,15 @@ export declare namespace Chart {
     /**
      * Options for creating a Chart.
      */
-    interface ConstructorOptions extends IModel.ConstructorOptions<IChart.JSON> {
+    interface ConstructorOptions extends AbstractMovableContent.ConstructorOptions<IChart.JSON> {
         /**
          * Returns an IResource from the resourceId or null if not found.
          */
         fromResourceId?: (resourceId: number) => IResource;
         /**
-         * Useful for load/save/copying.
-         */
-        beginPersistResource: () => IResourceCollection.IPersistScope<IResource.JSON>;
-        /**
-         * Allow for the default lock aspect ratio to be overwritten.
+         * Useful for load/save/copying. A chart outside a workbook has none.
          */
-        defaultLockAspectRatio?: boolean;
+        beginPersistResource?: () => IResourceCollection.IPersistScope<IResource.JSON>;
     }
 }
-export {};
 //# sourceMappingURL=Chart.d.ts.map

package/types/src/chart/ChartCollection.d.ts

@@ -0,0 +1,31 @@
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
+import { IMovableCollection } from '../movable';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { IWorksheet } from '../sheet/IWorksheet';
+import { IChart } from './IChart';
+import { IChartCollection } from './IChartCollection';
+/**
+ * Implementation for {@link IChartCollection}.
+ *
+ * @remarks
+ * A live view over the movables — no store of its own and no event of its own. The movables'
+ * `onCollectionChange` is forwarded as this collection's, with this collection as the source;
+ * deleting the chart removes its movable. Adding one adds a movable whose content is the chart.
+ */
+export declare class ChartCollection extends AbstractCollection<IChart> implements IChartCollection {
+    private _movables;
+    private _sheet;
+    constructor(movables: IMovableCollection, sheet?: IWorksheet | null);
+    /** {@inheritDoc IChartCollection.add} */
+    add(source: ICellRange | ICellRanges | string, options?: IChart.AddOptions): Promise<IChart>;
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(): IChart[];
+    /** {@inheritDoc IChartCollection.getByName} */
+    getByName(name: string): IChart | null;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IChartCollection.isIChartCollection} */
+    get isIChartCollection(): true;
+}
+//# sourceMappingURL=ChartCollection.d.ts.map