@sheetxl/sdk 0.8.0-beta.10 → 0.8.0-beta.12

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

@@ -3,7 +3,7 @@ import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
 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,9 +19,9 @@ 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.
      *
@@ -72,14 +72,15 @@ export interface ICellRanges {
      * This is Excel's `Ctrl+Enter` fill: the same scalar is written to all selected cells — across every
      * discontiguous range — as a single {@link ICellRanges.doBatch} operation (one undo step). A formula
      * string (e.g. `"=A1+1"`) is coerced and its relative references adjust per cell, exactly as
-     * {@link ICellRange.setValue} does within one range.
+     * {@link ICellRange.setValue} does within one range. It takes what that does: a `Date`, or a rich
+     * value's JSON (`{ type, data }`), which each cell makes into its own value.
      *
      * Only the scalar-broadcast form exists (no `setValues`): a 2D shape has no coherent meaning spread
      * across discontiguous ranges of differing sizes.
      * @see
      * {@link ICellRange.setValue}
      */
-    setValue(value: ICellRange.ScalarUpdate, options?: ICellRange.SetValuesOptions): this;
+    setValue(value: ICellRange.InteropScalarUpdate, options?: ICellRange.SetValuesOptions): this;
     /**
      * {@inheritDoc ICellRange.merge}
      */
@@ -188,6 +189,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}
      */
@@ -330,7 +336,7 @@ export interface ICellRanges {
     /**
      * {@inheritDoc ICellRange.addListener}
      */
-    addListener(listener: ICellRange.Listener, options?: ICellRange.ListenerOptions): IListener.Remove;
+    addListener(listener: ICellRange.Listener<ICellRanges>, options?: ICellRange.ListenerOptions): IListener.Remove;
     /**
      * {@link ICellRange.addWatch} across every area, as ONE expression authored at a shared origin.
      *

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

@@ -1,34 +1,66 @@
+import { Bounds, Point, Size } from '@sheetxl/utils';
 import { IResource, IResourceCollection } from '../resource';
+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';
+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 AbstractMovableContent<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 markup `_facts` was read from. */
-    private _factsSource;
-    private _facts;
+    /** 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;
-    private _axes;
-    /** The part's formulas as the engine holds them, by {@link ChartXmlFacts.slots} index. */
+    /** 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 captured part is read once, on first ask; most charts are never asked. */
+    /** 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 part's own text stands. */
+    /** 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 part's own. */
+    /** 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. */
@@ -39,14 +71,178 @@ export declare class Chart extends AbstractMovableContent<State, IChart.JSON> im
     getChartTitle(): string | null;
     /** {@inheritDoc IChart.getChartType} */
     getChartType(): 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(): readonly IChart.IAxis[];
+    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.getXML} */
-    getXML(): 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 IMovable.IContent.getTypeDescription} */
@@ -54,6 +250,13 @@ export declare class Chart extends AbstractMovableContent<State, IChart.JSON> im
     /** {@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.
  *
@@ -72,10 +275,9 @@ export declare namespace Chart {
          */
         fromResourceId?: (resourceId: number) => IResource;
         /**
-         * Useful for load/save/copying.
+         * Useful for load/save/copying. A chart outside a workbook has none.
          */
-        beginPersistResource: () => IResourceCollection.IPersistScope<IResource.JSON>;
+        beginPersistResource?: () => IResourceCollection.IPersistScope<IResource.JSON>;
     }
 }
-export {};
 //# sourceMappingURL=Chart.d.ts.map

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

@@ -1,6 +1,8 @@
 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';
 /**
@@ -9,11 +11,14 @@ import { IChartCollection } from './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.
+ * 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;
-    constructor(movables: IMovableCollection);
+    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} */