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

package/types/src/named/NamedCollection.d.ts

@@ -92,7 +92,7 @@ export declare class NamedCollection extends AbstractCollection<INamed, INamedCo
     /** The scope an unqualified query is read against — the collection's own, unless {@link _scopedTo}. */
     private _currentScope;
     /**
-     * A view of this collection anchored to ONE scope — what `ISheet.getNames()` hands out.
+     * A view of this collection anchored to ONE scope — what `IWorksheet.getNames()` hands out.
      *
      * @remarks
      * The collection a sheet inside a workbook is given IS the workbook's, whose current scope is
@@ -139,10 +139,18 @@ export declare class NamedCollection extends AbstractCollection<INamed, INamedCo
      * Global. Asked of the WORKBOOK, "add a name" means a workbook name — deliberately NOT
      * {@link _currentScope}, which follows the selected tab: reading against the sheet on screen is
      * right for a query and would be a trap for a write, silently scoping a name to whichever tab
-     * happened to be active. `ISheet.getNames()` is where a scoped one comes from — see
+     * happened to be active. `IWorksheet.getNames()` is where a scoped one comes from — see
      * {@link _scopedTo}.
      */
     addFormula(name: string, expression: string, replaceExisting?: boolean): INamed;
+    /** {@inheritDoc INamedCollection.removeUnused} */
+    removeUnused(options?: INamedCollection.RemoveUnusedOptions): Promise<number>;
+    /**
+     * {@link removeUnused}, limited to one scope — see {@link _scopedTo}.
+     *
+     * @param scope The sheet whose names are considered; `undefined` for every scope.
+     */
+    _removeUnused(options: INamedCollection.RemoveUnusedOptions | undefined, scope: string | undefined): Promise<number>;
     /** {@link addFormula}, against an explicit `scope` — see {@link _scopedTo}. */
     _addFormula(name: string, expression: string, replaceExisting?: boolean, scope?: string | null): INamed;
     /** {@inheritDoc ITransaction.ITransactional.beginCommit} */
@@ -178,7 +186,7 @@ export declare namespace NamedCollection {
      * that does not say.
      *
      * @remarks
-     * Structural rather than `ISheet` to keep this module free of that import; a sheet satisfies it.
+     * Structural rather than `IWorksheet` to keep this module free of that import; a sheet satisfies it.
      * Both members matter and for different reasons: `getName` is the scope a name resolves against,
      * and `getRanges` is what a bare address like `'A1'` is read on.
      */
@@ -237,6 +245,28 @@ export declare namespace NamedCollection {
          * / charts) leaves it undefined; those are named by the thing they belong to.
          */
         add?(options: NamedCollection.AddNamedOptions): INamed;
+        /**
+         * Resolves what `items` designate in one step, ahead of a loop that asks each item's
+         * `getRanges()` in turn.
+         *
+         * @remarks
+         * For a source whose items compile on first use (a file's defined names): asked one at a time,
+         * each compile is its own operation, and a file carrying thousands of names makes an address
+         * query cost thousands of operations. The source batches them; items that are not its own, or
+         * that answer from their text already, it leaves alone. A source whose items are derived has
+         * nothing to prepare and leaves it undefined.
+         */
+        prepareRanges?(items: readonly INamed[]): void;
+        /**
+         * Backs {@link INamedCollection.removeUnused} for the source that owns defined names.
+         *
+         * @remarks
+         * `scope`, when given, is the sheet whose own names are considered (a sheet's collection);
+         * `undefined` considers every scope.
+         */
+        removeUnused?(options: INamedCollection.RemoveUnusedOptions & {
+            scope?: string;
+        }): Promise<number>;
     }
     /**
      * What {@link Source.add} needs to define a name.
@@ -289,7 +319,7 @@ export declare namespace NamedCollection {
         /**
          * Returns the current scope.
          */
-        getCurrentScope?: () => string;
+        getCurrentScope?: () => string | null;
         /**
          * A transaction store that can be used to undo/redo changes to the names.
          */

package/types/src/numFmt/NumberFormatParser.d.ts

@@ -51,6 +51,11 @@ export interface ParsedRun {
     type: ParseRunType;
     width: number;
     text: string;
+    /**
+     * The CSS `letter-spacing` (px at the style's size) that paints `text` at `width`; see
+     * `IFont.ExtendedMetrics.renderLetterSpacing`. Absent or `0` where paint already matches.
+     */
+    letterSpacing?: number;
 }
 export interface ParsedRuns {
     runs: readonly ParsedRun[];

package/types/src/outline/IOutline.d.ts

@@ -13,7 +13,7 @@ import { ITransaction } from '../transaction';
  * Groups are made and removed with {@link ICellRange.group} and {@link ICellRange.ungroup}, or
  * from the sheet's formulas with {@link autoOutline}, and collapsed and expanded with
  * {@link ICellRange.hideGroupDetails} and {@link ICellRange.showGroupDetails}. Whether the symbols are drawn
- * is the view's: {@link ISheetView.setShowOutlineSymbols}.
+ * is the view's: {@link IWorksheetView.setShowOutlineSymbols}.
  *
  * The counterpart of Excel's `Worksheet.Outline`.
  */

package/types/src/outline/Outline.d.ts

@@ -3,7 +3,7 @@ import { RunCoords } from '@sheetxl/utils';
 import { ITypes } from '../type';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
-import { ISheet } from '../sheet/ISheet';
+import { IWorksheet } from '../sheet/IWorksheet';
 import { IOutline } from './IOutline';
 import { ListenerEmitter } from '../listener/ListenerEmitter';
 import { SheetHeader } from '../sheetHeader/SheetHeader';
@@ -56,7 +56,7 @@ export declare class Outline implements IOutline {
     protected _getState(): Readonly<State>;
     protected _updateState(update: Partial<State>, options?: ITransaction.OperationOptions): void;
     protected _header(axis: IRange.Axis): SheetHeader;
-    protected _sheet(): ISheet;
+    protected _sheet(): IWorksheet;
     /**
      * The structure of an outline and its settings need an unprotected sheet, whatever the
      * protection allows; only showing and hiding details goes by Format Rows / Format Columns.

package/types/src/picture/IPicture.d.ts

@@ -4,6 +4,9 @@ import { ITransaction } from '../transaction';
 import { IResource, IResourceCollection } from '../resource';
 import { IModel } from '../model';
 import { IMovable } from '../movable';
+import { IFill, IStroke, IEffect } from '../fill';
+import { IHyperlink } from '../hyperlink';
+import { IGeometry, IShape, IShapeStyle } from '../shape';
 /**
  * Interface for working with Pictures (both Images and SVG).
  */
@@ -33,6 +36,43 @@ export interface IPicture extends IModel, IMovable.IContent {
      * ```
      */
     setResource(picture: string | IResource | IResourceCollection.AddOptions, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns the shape the picture is cropped to: its preset geometry.
+     *
+     * @remarks
+     * A DrawingML preset id ({@link IGeometry.Preset}): `rect` for a picture that is not cropped to
+     * a shape, which is most of them. A file may name a preset this SDK does not know; it is
+     * returned as the file states it.
+     */
+    getShapeType(): string;
+    /**
+     * Crops the picture to a shape, as Excel's Crop to Shape does: the image, its frame, border and
+     * effects stay; the picture is clipped to the preset's outline.
+     *
+     * A picture takes any closed preset; a line or connector preset is refused.
+     *
+     * @param shapeType A DrawingML preset id ({@link IGeometry.Preset}); `rect` crops to nothing.
+     * @throws ExpectedError for a preset the picture cannot take.
+     *
+     * @example
+     * ```ts
+     * picture.setShapeType(IGeometry.Preset.Ellipse);
+     * ```
+     */
+    setShapeType(shapeType: IGeometry.Preset | string, options?: ITransaction.OperationOptions): this;
+    /**
+     * What the picture's frame draws with: the fill behind the image and the border around it.
+     * A picture has no theme style, so each is only what the picture states; by default neither
+     * draws, and a border shows only once it has a color (a width alone draws nothing, as in
+     * Excel). The same object answers for the life of the picture.
+     *
+     * @example
+     * ```ts
+     * picture.getStyle().getStroke().setWidth(2.25);
+     * picture.getStyle().setFill('#ffd966');
+     * ```
+     */
+    getStyle(): IShapeStyle;
     /**
      * Returns an image blob.
      */
@@ -64,6 +104,13 @@ export declare namespace IPicture {
      */
     interface Properties {
     }
+    /**
+     * How the image is placed in the picture's frame (`blipFill`): the part of it shown, whether
+     * that part is stretched over the frame or tiled across it, and the adjustments made to the
+     * image itself. The same slots as an {@link IFill.ImageJSON | image fill}, without the image:
+     * a picture names its image by {@link JSON.resId}.
+     */
+    type ImageJSON = Omit<IFill.ImageProperties, 'type' | 'resId'>;
     interface JSON {
         /**
          * The resource id of the picture.
@@ -75,7 +122,57 @@ export declare namespace IPicture {
          * glues to it.
          */
         sourceId?: number;
-        effects?: string[];
+        /**
+         * How the image fills the frame: the crop (`srcRect`), stretch insets or tiling, and the
+         * image's own adjustments. Absent for the whole image stretched over the whole frame, which
+         * is what an inserted picture is.
+         */
+        image?: ImageJSON;
+        /**
+         * The shape the picture is cropped to (`prstGeom`); absent for a rectangle, i.e. not cropped
+         * to a shape.
+         */
+        geometry?: string | IGeometry.Def;
+        /** The adjust values of {@link geometry}, by name, where a handle moved them off the preset's defaults. */
+        adjustments?: Record<string, number>;
+        /**
+         * The fill behind the image (`spPr`); a transparent image shows it. Absent for none.
+         */
+        fill?: IFill.SolidJSON | IFill.GradientJSON | IFill.PatternJSON | IFill.ImageJSON | IFill.NoneJSON;
+        /** The border around the frame (`spPr/ln`). Absent for none. */
+        stroke?: IStroke.JSON;
+        /** The frame's effects (`spPr/effectLst`): a shadow, a glow, a reflection, soft edges. */
+        effects?: IEffect.JSON[];
+        /** The 3-D scene (`spPr/scene3d`) as the file states it: an opaque DrawingML fragment. */
+        scene3d?: string;
+        /** The 3-D shape properties (`spPr/sp3d`) as the file states it: an opaque DrawingML fragment. */
+        shape3d?: string;
+        /** Extension lists kept as the file states them, by the element each extends. */
+        extLst?: IShape.ExtLstJSON;
+        /** The hyperlink on the picture (`cNvPr/hlinkClick`). */
+        hyperlink?: IHyperlink.JSON;
+        /** The hyperlink followed on hover (`cNvPr/hlinkHover`). */
+        hoverHyperlink?: IHyperlink.JSON;
+        /** The title (`cNvPr/@title`), beside the description. */
+        title?: string;
+        /** The macro assigned to the picture (`pic/@macro`), as the file states it. */
+        macro?: string;
+        /** `pic/@fPublished`. */
+        published?: boolean;
+        /**
+         * Edit locks (`picLocks`) by the file's own names: `noChangeAspect`, `noCrop`, `noGrp`,
+         * `noSelect`, `noRot`, `noMove`, `noResize`, `noEditPoints`, `noAdjustHandles`,
+         * `noChangeArrowheads`, `noChangeShapeType`. `noChangeAspect` is also the movable's
+         * {@link IMovable.JSON.lockAspect | aspect lock}, which wins when both are stated.
+         */
+        locks?: Record<string, boolean>;
+        /**
+         * Resizing is not relative to the original picture size (`cNvPicPr/@preferRelativeResize="0"`,
+         * Excel's "Relative to original picture size" unticked). Carried for the file.
+         *
+         * @defaultValue false
+         */
+        noRelativeResize?: boolean;
     }
     interface Details {
         /**

package/types/src/picture/Picture.d.ts

@@ -3,13 +3,15 @@ import { IResource, IResourceCollection } from '../resource';
 import { IAnchored } from '../anchored';
 import { IMovable } from '../movable/IMovable';
 import { AbstractMovableContent } from '../movable/AbstractMovableContent';
+import { IGeometry, IShapeStyle } from '../shape';
 import { IPicture } from './IPicture';
+/** The picture's JSON beyond its image: everything {@link IPicture.JSON} states but `resId`. */
+type Data = Omit<IPicture.JSON, 'resId'>;
 interface State extends AbstractMovableContent.State {
     /** The image shown. In the state so that a change of picture undoes with the rest. */
     resource: IResource;
-    effects?: string[];
-    /** The id the file gave the picture; see `IPicture.JSON.sourceId`. */
-    sourceId?: number;
+    /** What the picture states of itself beyond the image; absent for an inserted picture. */
+    data?: Data;
 }
 /**
  * Implementation for {@link IPicture}.
@@ -19,15 +21,21 @@ export declare class Picture extends AbstractMovableContent<State, IPicture.JSON
     private _detailsSource;
     private _details?;
     private _dataUrl?;
+    private _getStyles;
+    private _style;
     constructor(options: Picture.ConstructorOptions);
     /** {@inheritDoc IPicture.getType} */ getType(): string;
     toJSON(toResourceId?: (resource: IResource) => number | null): IPicture.JSON;
     /** {@inheritDoc IMovable.IContent.getTypeDescription} */
     getTypeDescription(): string;
-    /** @internal */
-    _getSourceId(): number | undefined;
-    /** @internal */
-    _ensureSourceId(next: () => number): number;
+    /** {@inheritDoc IPicture.getShapeType} */
+    getShapeType(): string;
+    /** {@inheritDoc IPicture.setShapeType} */
+    setShapeType(shapeType: IGeometry.Preset | string, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPicture.getStyle} */
+    getStyle(): IShapeStyle;
+    /** Writes what the picture states of its fill and border: a key `undefined` is removed. */
+    private _writeStyle;
     /** {@inheritDoc IMovable.IContent.acceptRotation} */
     acceptRotation(degrees: number): number;
     /** {@inheritDoc IMovable.IContent.acceptFlip} */

package/types/src/pivot/IPivotTable.d.ts

@@ -1,5 +1,5 @@
 import { IResource } from '../resource';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { ICellRange } from '../cellRange';
 import { IAnchored } from '../anchored';
 import { IEmbeddedPart } from '../io';
@@ -21,7 +21,7 @@ export interface IPivotTable extends IAnchored {
     /**
      * Returns the sheet the table is laid out on.
      */
-    getSheet(): ISheet;
+    getWorksheet(): IWorksheet;
     /**
      * Returns the cells the table is laid out on.
      *

package/types/src/pivot/PivotTable.d.ts

@@ -1,6 +1,6 @@
 import { IRange } from '@sheetxl/primitives';
 import { IResource } from '../resource';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { Anchored } from '../anchored/Anchored';
 import { AbstractAnchored } from '../anchored/AbstractAnchored';
 import { IEmbeddedPart } from '../io';
@@ -22,7 +22,7 @@ interface State extends AbstractAnchored.State {
  * is refused. {@link getXML} restates the anchor into the part; the rest of the part is as read.
  */
 export declare class PivotTable extends AbstractAnchored<State, IPivotTable.Events> implements IPivotTable {
-    protected _sheet: ISheet;
+    protected _sheet: IWorksheet;
     protected _part: IEmbeddedPart | null;
     /** The location as the part spells it. While the anchor still says the same, the part is as read. */
     private _ref;
@@ -30,8 +30,8 @@ export declare class PivotTable extends AbstractAnchored<State, IPivotTable.Even
     protected _initialize(options: PivotTable.ConstructorOptions): void;
     /** {@inheritDoc IPivotTable.getName} */
     getName(): string;
-    /** {@inheritDoc IPivotTable.getSheet} */
-    getSheet(): ISheet;
+    /** {@inheritDoc IPivotTable.getWorksheet} */
+    getWorksheet(): IWorksheet;
     /** {@inheritDoc IPivotTable.getXML} */
     getXML(): string | null;
     /** {@inheritDoc IPivotTable.getCacheId} */
@@ -53,7 +53,7 @@ export declare class PivotTable extends AbstractAnchored<State, IPivotTable.Even
 }
 export declare namespace PivotTable {
     interface ConstructorOptions extends Anchored.ConstructorOptions<IPivotTable.JSON> {
-        sheet: ISheet;
+        sheet: IWorksheet;
         fromResourceId?: (resourceId: number) => IResource;
     }
 }

package/types/src/primitives/AsyncValue.d.ts

@@ -0,0 +1,58 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+/**
+ * Whether any holder has been made in this process: what gates the value layer's reads (a range,
+ * the stats walks), which cannot ask a backend. Until the first `defer`, they pay nothing.
+ */
+export declare const holdersMade: () => boolean;
+/**
+ * How many times a call's latest has moved in this process. A settle writes nothing into a grid,
+ * so a cache keyed on a run that holds holders is stamped with this and stands only while it holds.
+ */
+export declare const settleCount: () => number;
+/** Records that a call's latest moved. */
+export declare const noteSettle: () => void;
+/**
+ * What a cell holds when its formula's evaluation deferred (DESIGN-ASYNC §4.4): the node's
+ * `cachedValue` and the engine grid's value at the cell. Immutable; what moves is the call, which
+ * holds the latest. Each deferring evaluation makes a new one.
+ *
+ * @remarks
+ * Seen only by the formula block and the engine. Every other reader reads it through
+ * {@link readAsync}: the push into a dependent's input, a range read of the engine grid, and the
+ * copy of results to the model, which never receives one.
+ *
+ * The calls are the calculation layer's; all a read needs of one is its latest.
+ */
+export declare class AsyncValue<C extends AsyncValue.Call = AsyncValue.Call> {
+    /**
+     * What the formula calculated, from its calls' initials. A range for an evaluation that
+     * spilled: that holder rides the spill's entry, never a cell, and no cell reads it.
+     */
+    readonly value: Scalar | IRange;
+    /** The calls the formula made, by ordinal. */
+    readonly calls: readonly C[];
+    /** The formula's root is its only call: the cell reads as that call's latest once it has one. */
+    readonly direct: boolean;
+    constructor(value: Scalar | IRange, calls: readonly C[], direct: boolean);
+    /** The brand every recognizing site reads. */
+    get isAsyncValue(): true;
+}
+export declare namespace AsyncValue {
+    /** What a holder reads of a call. */
+    interface Call {
+        /** The most recent result; `undefined` until one arrives. */
+        readonly latest: unknown;
+    }
+}
+/** Whether `value` is an {@link AsyncValue}. */
+export declare const isAsyncValue: (value: unknown) => value is AsyncValue;
+/**
+ * `value` as a reader sees it: a holder reads as its root call's latest when `direct` and the call
+ * has one, else as what the formula calculated. Anything else is itself.
+ *
+ * @remarks
+ * A blank latest reads as `0`, as a formula's blank result is stored (`finalizeValue`): the
+ * latest is the cell's value and was never finalized.
+ */
+export declare const readAsync: <T = Scalar>(value: T) => T | Scalar | IRange;
+//# sourceMappingURL=AsyncValue.d.ts.map

package/types/src/primitives/ReferenceRange.d.ts

@@ -19,8 +19,8 @@ export declare class ReferenceRange extends Range implements IReferenceRange {
     /**
      * Told when a body reads this reference's POSITION (`getCoords`). A reference's values are a
      * property of what it points at; its address is a property of which cell is asking, so a
-     * formula that reads it (`ROW(A13)`, `CELL("address",A13)`) cannot share its answer with another
-     * cell — see `CalcScope.perCellRead`. Set by the context that builds the reference; a view
+     * formula that reads it (`ROW(A13)`, `CELL("address",A13)`) shares its answer with another cell
+     * only where the position cannot matter — see `CalcScope.positionRead`. Set by the context that builds the reference; a view
      * (`slice`, `toType`) carries it.
      */
     protected _onCoordsRead: (() => void) | null;