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

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

@@ -1,7 +1,7 @@
 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 { ICalculation } from '../calculation';
@@ -28,7 +28,7 @@ export interface ICellRanges {
      * @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}
      */
@@ -218,35 +218,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 +334,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 +345,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 +355,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,26 +1,58 @@
 import { IResource, IResourceCollection } from '../resource';
-import { IModel, AbstractModel } from '../model';
+import { AbstractMovableContent } from '../movable/AbstractMovableContent';
+import { IEmbeddedPart } from '../io';
 import { IChart } from './IChart';
-interface State extends AbstractModel.State {
+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> 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;
+    private _series;
+    private _axes;
+    /** The part's formulas as the engine holds them, by {@link ChartXmlFacts.slots} index. */
+    private _held;
     constructor(options: Chart.ConstructorOptions);
     /** {@inheritDoc IModel.getType} */
     getType(): string;
+    /** The captured part is read once, on first ask; most charts are never asked. */
+    private _getFacts;
+    /** The engine's text for `slot` once something has moved what it names, else `null`: the part'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. */
+    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;
+    /** {@inheritDoc IChart.getSeries} */
+    getSeries(): readonly IChart.ISeries[];
+    /** {@inheritDoc IChart.getAxes} */
+    getAxes(): readonly IChart.IAxis[];
+    /** {@inheritDoc IChart.getPivotSource} */
+    getPivotSource(): string | null;
+    /** {@inheritDoc IChart.getXML} */
+    getXML(): string | null;
     /** {@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;
 }
 /**
  * Interfaces for creating `Chart` items.
@@ -34,7 +66,7 @@ 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.
          */
@@ -43,10 +75,6 @@ export declare namespace Chart {
          * Useful for load/save/copying.
          */
         beginPersistResource: () => IResourceCollection.IPersistScope<IResource.JSON>;
-        /**
-         * Allow for the default lock aspect ratio to be overwritten.
-         */
-        defaultLockAspectRatio?: boolean;
     }
 }
 export {};

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

@@ -0,0 +1,26 @@
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
+import { IMovableCollection } from '../movable';
+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.
+ */
+export declare class ChartCollection extends AbstractCollection<IChart> implements IChartCollection {
+    private _movables;
+    constructor(movables: IMovableCollection);
+    /** {@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

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

@@ -1,16 +1,84 @@
 import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
 import { IResource } from '../resource';
 import { IModel } from '../model';
+import { IMovable } from '../movable';
+import { IEmbeddedPart } from '../io';
+import { ICellRange } from '../cellRange';
 /**
- * Interface for working with Charts.
+ * Interface for working with a chart.
  *
- * **PLACEHOLDER** - This is under development and not made public yet.
+ * @remarks
+ * A chart is the content of a movable, which places it — see {@link IChart.getMovable}.
+ * Until the chart is modeled it is carried as the markup it was read from and written back
+ * unchanged; {@link IChart.getXML} is the read-only view of that markup.
  */
-export interface IChart extends IModel {
-    toJSON(toResourceId?: (resource: IResource) => number | null): IChart.JSON | null;
+export interface IChart extends IModel, IMovable.IContent {
+    /**
+     * Returns the chart's title, or `null` if it has none.
+     *
+     * @remarks
+     * A title that is a reference to a cell reads as that cell's text. A chart with no title of its
+     * own answers `null` even where an application would draw one for it — a single series' name,
+     * or a placeholder.
+     */
     getChartTitle(): string | null;
+    /**
+     * Returns the chart's type, or `'unknown'`.
+     *
+     * @remarks
+     * `'column'`, `'bar'`, `'line'`, `'area'`, `'pie'`, `'doughnut'`, `'scatter'`, `'bubble'`,
+     * `'radar'`, `'stock'`, `'surface'`, `'waterfall'`, `'funnel'`, `'treemap'`, `'sunburst'`,
+     * `'histogram'`, `'boxWhisker'` and so on. A stacked chart says so after the type —
+     * `'columnStacked'`, `'areaPercentStacked'`. A chart whose series are not all drawn the same way
+     * is `'combo'`, and {@link IChart.ISeries.getChartType} says how each one is drawn.
+     */
     getChartType(): string;
-    getDescription(): string;
+    /**
+     * Returns the series the chart plots, in the order they are listed.
+     *
+     * @remarks
+     * What a series plots is stated as formulas, which follow the cells they name: inserting a row
+     * above the data moves them, and deleting the data leaves `#REF!`.
+     */
+    getSeries(): readonly IChart.ISeries[];
+    /**
+     * Returns the axes the chart shows. A pie has none.
+     */
+    getAxes(): readonly IChart.IAxis[];
+    /**
+     * Returns the name of the pivot table the chart draws, or `null` if it is not a pivot chart.
+     *
+     * @remarks
+     * A pivot chart's series are the pivot table's: they change with its layout, and the ranges its
+     * series name are wherever the table last put them.
+     */
+    getPivotSource(): string | null;
+    /**
+     * Returns the movable that places the chart on the sheet, or `null` if it is not placed by one.
+     *
+     * @remarks
+     * The movable holds the chart's position and size; the chart keeps no copy of either.
+     * Deleting the chart removes its movable.
+     */
+    getMovable(): IMovable | null;
+    /**
+     * Deletes the chart, and with it the movable that places it.
+     */
+    delete(options?: ITransaction.OperationOptions): void;
+    /**
+     * Returns the chart's own markup, or `null` if none was captured.
+     *
+     * @remarks
+     * Read-only, and the one escape hatch for what the chart does not model yet: it is the
+     * `<c:chartSpace>` the chart was read from, not the parts that markup references, with its
+     * formulas as they are now. It will be removed when the chart is modeled.
+     */
+    getXML(): string | null;
+    /** @internal */
+    toJSON(toResourceId?: (resource: IResource) => number | null): IChart.JSON | null;
+    /** For runtime type checking. */
+    readonly isIChart: true;
 }
 /**
  * {@inheritDoc IChart}
@@ -20,6 +88,88 @@ export interface IChart extends IModel {
  * {@link IChart}
  */
 export declare namespace IChart {
+    /**
+     * One series of a chart: what it is called and the cells it plots.
+     *
+     * @remarks
+     * Each part of a series is stated as a formula — `Sales!$C$4:$C$15` — the way the file and a
+     * chart's own dialog state it. The formula is the contract: it is what can say `#REF!`, name a
+     * defined name, or point at another workbook. The `get…Range` forms resolve the plain case.
+     */
+    interface ISeries {
+        /**
+         * Returns the series' name, or `null` if it has none.
+         *
+         * @remarks
+         * A name that is a reference to a cell reads as that cell's text.
+         */
+        getName(): string | null;
+        /**
+         * Returns the formula naming the series — `Sales!$C$3` — or `null` when the name is written
+         * into the chart, or there is none.
+         */
+        getNameFormula(): string | null;
+        /**
+         * Returns the formula for the values plotted, or `null` if the series states none.
+         *
+         * @remarks
+         * Values written into the chart rather than read from cells are an array literal: `{1,2,3}`.
+         */
+        getValuesFormula(): string | null;
+        /**
+         * Returns the formula for the categories the values are plotted against — the x values of a
+         * scatter or bubble series — or `null` if the series states none.
+         */
+        getCategoriesFormula(): string | null;
+        /**
+         * Returns the cells {@link getNameFormula} names, or `null`.
+         *
+         * @see {@link getValuesRange} for when there are none to return.
+         */
+        getNameRange(): ICellRange | null;
+        /**
+         * Returns the cells {@link getValuesFormula} names.
+         *
+         * @returns `null` when the formula is not one plain reference into this workbook: an array
+         * literal, a defined name, several areas, another workbook, or `#REF!`.
+         */
+        getValuesRange(): ICellRange | null;
+        /**
+         * Returns the cells {@link getCategoriesFormula} names, or `null`.
+         *
+         * @see {@link getValuesRange} for when there are none to return.
+         */
+        getCategoriesRange(): ICellRange | null;
+        /**
+         * Returns how the series is drawn. The same as {@link IChart.getChartType} except in a combo.
+         */
+        getChartType(): string;
+        /**
+         * Returns `true` if the series is plotted against the secondary axes.
+         */
+        isSecondaryAxis(): boolean;
+    }
+    /**
+     * One axis of a chart.
+     */
+    interface IAxis {
+        /**
+         * Returns what the axis measures: categories, values, dates, or — on a surface or 3-D chart —
+         * the series themselves.
+         */
+        getKind(): 'category' | 'value' | 'date' | 'series';
+        /**
+         * Returns the axis title, or `null` if it has none.
+         *
+         * @remarks
+         * Often the only place the units of a chart are stated.
+         */
+        getTitle(): string | null;
+        /**
+         * Returns the number format of the axis labels, or `null` if the axis states none.
+         */
+        getNumberFormat(): string | null;
+    }
     interface JSON {
         /** Opaque source XML fragment, captured verbatim from the source file and replayed as-is on
          * save, for whatever this chart doesn't (yet) model structurally. */
@@ -27,14 +177,18 @@ export declare namespace IChart {
         /** Original `cNvPr` id from the captured source fragment, if any; used to avoid id collisions
          * with freshly-generated ids on write. */
         sourceId?: number;
-        /** The literal `r:id` referencing the chart part inside `xml`, rewritten to match on write —
-         * `DrawingEmitter` regenerates the drawing part's own rels, so the id `xml` was captured with
-         * is not guaranteed to still be free. */
-        chartRelId?: string;
-        /** The chart part's absolute OPC path (e.g. "xl/charts/chart1.xml"), used to re-link `chartRelId`. */
-        chartTargetPath?: string;
+        /**
+         * The chart's own document part, and the parts that part references.
+         *
+         * @remarks
+         * The chart is carried as the markup it was read from until it is modeled; this is that markup
+         * and everything it needs to stay valid — its style and color definitions, the shapes drawn
+         * over it, an embedded workbook holding its data. {@link IChart.getXML} is the readable view
+         * of the chart's own markup; the rest is for writing the chart back out.
+         */
+        part?: IEmbeddedPart.JSON;
     }
-    interface Events extends IModel.Events {
+    interface Events extends IMovable.ContentEvents {
     }
     interface IListeners extends IListener.Callbacks<IChart, IChart.Events> {
     }

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

@@ -0,0 +1,25 @@
+import { ICollection } from '../type';
+import { IChart } from './IChart';
+/**
+ * Holds the {@link IChart | charts} on a sheet.
+ *
+ * @remarks
+ * A view over the sheet's movables: a chart is the content of a movable, and the movable is what
+ * places it — see {@link IChart.getMovable}. Read-only for now; a chart is added by adding a
+ * movable with chart content.
+ */
+export interface IChartCollection extends ICollection<IChart> {
+    /**
+     * Returns the charts, in the order of their movables.
+     */
+    getItems(options?: ICollection.GetItemsOptions): IChart[];
+    /**
+     * Returns the chart with the given name, or `null` if there is none.
+     *
+     * @param name The name of the chart. This is case insensitive.
+     */
+    getByName(name: string): IChart | null;
+    /** For runtime type checking. */
+    readonly isIChartCollection: true;
+}
+//# sourceMappingURL=IChartCollection.d.ts.map

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

@@ -0,0 +1,70 @@
+/**
+ * Reads what a chart's captured part can answer without a chart model behind it: what it plots,
+ * what kind of chart it is, and what it and its axes are called.
+ *
+ * @remarks
+ * An imported chart is kept as the source's markup ({@link IChart.JSON.part}) and replayed on save.
+ * Both chart vocabularies are read — `c:chartSpace`, and `cx:chartSpace` for the chart types added
+ * after it (waterfall, funnel, treemap, sunburst, histogram, box and whisker).
+ *
+ * Every formula in the part is also located ({@link ChartXmlFacts.slots}), because a formula is
+ * the one thing in the part that is not replayed verbatim: see {@link writeChartFormulas}.
+ */
+/** One formula in the part: its text, and where that text is in the markup. */
+export interface ChartFormulaSlot {
+    /** The formula as the part states it, entities decoded. */
+    text: string;
+    start: number;
+    end: number;
+}
+/** A piece of chart text: written in the chart, or read from a cell. */
+export interface ChartTextFacts {
+    /** The literal text, or what the cell held when the file was saved. */
+    text: string | null;
+    /** The {@link ChartXmlFacts.slots} index of the formula naming the cell, or `null` for a literal. */
+    slot: number | null;
+}
+/** A series dimension: the cells it reads, or the values written into the chart. */
+export interface ChartSourceFacts {
+    slot: number | null;
+    /** `{1,2,3}` — a dimension with no cells behind it. */
+    literal: string | null;
+}
+export interface ChartSeriesFacts {
+    type: string;
+    name: ChartTextFacts;
+    values: ChartSourceFacts;
+    categories: ChartSourceFacts;
+    secondary: boolean;
+}
+export interface ChartAxisFacts {
+    kind: 'category' | 'value' | 'date' | 'series';
+    title: ChartTextFacts;
+    numberFormat: string | null;
+}
+/** What {@link readChartXml} answers with. */
+export interface ChartXmlFacts {
+    type: string;
+    title: ChartTextFacts;
+    series: ChartSeriesFacts[];
+    axes: ChartAxisFacts[];
+    /** `c:pivotSource/c:name` — the pivot table a pivot chart draws, as the part names it. */
+    pivotSource: string | null;
+    slots: ChartFormulaSlot[];
+}
+/**
+ * Reads a captured chart part.
+ *
+ * @param xml The part as captured on import.
+ * @returns `null` when `xml` holds no chart.
+ */
+export declare const readChartXml: (xml: string) => ChartXmlFacts | null;
+/**
+ * The part with its formulas restated.
+ *
+ * @param xml The part {@link readChartXml} read `slots` from.
+ * @param texts The formula for each slot, or `null` to leave what the part says.
+ * @returns `xml` itself when nothing is restated.
+ */
+export declare const writeChartFormulas: (xml: string, slots: readonly ChartFormulaSlot[], texts: readonly (string | null)[]) => string;
+//# sourceMappingURL=_ChartXml.d.ts.map

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

@@ -1,5 +1,3 @@
-/**
- * @hidden
- */
 export * from './IChart';
+export * from './IChartCollection';
 //# sourceMappingURL=index.d.ts.map

package/types/src/collections/ArraysGrid.d.ts

@@ -23,7 +23,7 @@ export declare class ArraysGrid<T = any> implements IGrid<T> {
     getCoords(): RangeCoords | null;
     /** {@inheritDoc IGrid.setValues} */
     setValues(_values: Tuple.GridTuple): this;
-    getValues(coords?: RangeCoords): Tuple.BoundedTuples<T> | null;
+    getValues(coords?: RangeCoords): Tuple.Region<T> | null;
     /** {@inheritDoc IGrid.getAxis} */
     getAxis(): RangeAxis;
     /** {@inheritDoc IGrid.delete} */

package/types/src/collections/IGrid.d.ts

@@ -42,7 +42,7 @@ export interface IGrid<T = any> {
      * * Results `null` if there are no values
      * * If `coords` is not provided then all values will be retrieved.
      */
-    getValues(coords?: RangeCoords): Tuple.BoundedTuples<T> | null;
+    getValues(coords?: RangeCoords): Tuple.Region<T> | null;
     /**
      * Returns an iterator for traversing entries in the IGrid.
      *

package/types/src/collections/ISparseGrid.d.ts

@@ -12,6 +12,15 @@ export interface ISparseGrid<T = any> extends IGrid<T> {
      * Sparse grids are stored as virtual tuples of [major, minor, value].
      */
     getRuns(options?: ISparseGrid.RunIteratorOptions): ISparseGrid.RunIterableIterator<T>;
+    /**
+     * `true` when the grid reports which cells are read.
+     *
+     * @remarks
+     * A consumer that could answer from a structure derived off the stored runs — an index that
+     * opens no cell — must instead read the cells it stands for, so that the report stays exact.
+     * The calculation sets this on the grid a formula reads while its reads decide circularity.
+     */
+    readonly observesReads?: boolean;
 }
 /**
  * {@inheritDoc ISparseGrid}