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

package/types/src/movable/_PlacementUtils.d.ts

@@ -0,0 +1,55 @@
+import { Bounds } from '@sheetxl/utils';
+import { IMovable } from './IMovable';
+import { Movable } from './Movable';
+/**
+ * The placement math of a movable that holds movables, as DrawingML states it: a group's frame
+ * maps its child space (`chOff`/`chExt`) by a scale per axis, and its rotation and flips turn and
+ * mirror what is drawn in the frame.
+ *
+ * @remarks
+ * A member's own answers ({@link IMovable.getBounds}, {@link IMovable.getRotation},
+ * {@link IMovable.getFlip}) are already where it is drawn; this is what a group maps them with.
+ */
+export declare namespace PlacementUtils {
+    /**
+     * Where a member lands in its group's container, from where the group lands there and where the
+     * member sits in the group's child space.
+     *
+     * @remarks
+     * The member's center is scaled into the frame and its unrotated size with it. Under an uneven
+     * scale a member turned by about a quarter turn takes the y factor for its width and the x
+     * factor for its height, so it is not sheared, as PowerPoint places it (SHAPES-DESIGN §11.3).
+     * The group's flips then mirror the member's position in the frame, and its rotation turns it
+     * about the frame's center. The member's rotation is composed with the group's, reversed under
+     * one mirror since a mirror conjugates a turn into its inverse, and its flips are toggled by the
+     * group's.
+     *
+     * @param parent Where the group sits in its container: its unrotated frame, rotation and flips.
+     * @param childSpace The group's child space, in which `local` is stated.
+     * @param local Where the member sits in the child space.
+     * @returns Where the member sits in the group's container.
+     */
+    const placeInParent: (parent: Movable.Placement, childSpace: Bounds, local: Movable.Placement) => Movable.Placement;
+    /**
+     * The inverse of {@link placeInParent}: where a member must sit in the child space to land at
+     * `placed` in the group's container.
+     */
+    const placeInChild: (parent: Movable.Placement, childSpace: Bounds, placed: Movable.Placement) => Movable.Placement;
+    /** The box of `bounds` turned by `rotation` degrees about its center. */
+    const rotatedBox: (bounds: Bounds, rotation: number) => Bounds;
+    /** The smallest box holding every one of `boxes`; `null` for none. */
+    const unionBounds: (boxes: readonly Bounds[]) => Bounds | null;
+    /**
+     * How far apart, in pixels, two placements may be and still be the same: far below one EMU
+     * (1/9525 px), the finest a file states, so only the noise of mapping out of a group and back
+     * is ignored.
+     */
+    const EPSILON = 0.000001;
+    /** Whether `a` and `b` are the same box, within {@link EPSILON}. */
+    const isSameBounds: (a: Bounds, b: Bounds) => boolean;
+    /** A placement with no turn and no mirror at `bounds`. */
+    const flatPlacement: (bounds: Bounds) => Movable.Placement;
+    /** Where a movable is drawn, as one placement; `null` before it is laid out. */
+    const placementOf: (movable: IMovable) => Movable.Placement | null;
+}
+//# sourceMappingURL=_PlacementUtils.d.ts.map

package/types/src/movable/_RotatedFrame.d.ts

@@ -0,0 +1,20 @@
+import { Bounds } from '@sheetxl/utils';
+/**
+ * Whether a rotation is within 45° of a quarter turn (90° or 270°), in either direction.
+ *
+ * @remarks
+ * Excel's anchor of a rotated drawing is the box of the drawing as rotated, and Excel does not
+ * compute a true rotated bounding box: within 45° of a quarter turn the anchor is the unrotated
+ * frame with its width and height swapped, otherwise it is the frame itself. The same rule
+ * places a member rotated by a quarter turn in a group that is scaled unevenly.
+ */
+export declare const isQuarterTurn: (rotation: number) => boolean;
+/**
+ * Between a drawing's unrotated frame and its anchor, the box it occupies as rotated: within 45°
+ * of a quarter turn the sides are swapped about the same center, otherwise the box is unchanged.
+ *
+ * @remarks
+ * Its own inverse, so it maps a frame to its anchor and an anchor to its frame.
+ */
+export declare const swapForRotation: (bounds: Bounds, rotation: number) => Bounds;
+//# sourceMappingURL=_RotatedFrame.d.ts.map

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

@@ -1,4 +1,10 @@
 export * from './IMovable';
 export * from './IMovableCollection';
-export * from './IMovableSelection';
+export * from './IErrorContent';
+export * from './MovableContentRegistry';
+export * from './AbstractMovableContent';
+/**
+ * @hidden
+ */
+export * from './IFormControl';
 //# sourceMappingURL=index.d.ts.map

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

@@ -13,7 +13,7 @@ export interface State extends AbstractModel.State {
 /**
  * Abstract implementation of `INamed`.
  */
-export declare abstract class AbstractNamed<T, S extends State, VIEW extends AbstractModel.CommitView = AbstractModel.CommitView, EVENTS extends IModel.Events = INamed.Events> extends AbstractModel<S, INamed.JSON, VIEW, EVENTS> implements INamed<T> {
+export declare abstract class AbstractNamed<T, S extends State, EVENTS extends IModel.Events = INamed.Events> extends AbstractModel<S, INamed.JSON, EVENTS> implements INamed<T> {
     /** {@inheritDoc INamed.select} */
     abstract select(options?: ITypes.SelectOptions): Promise<this>;
     /** {@inheritDoc INamed.getRanges} */

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

@@ -67,6 +67,9 @@ export interface INamed<T = any> extends IModel {
      * A reference to a *part* of this item that the given coords designate exactly, or `null`.
      *
      * @param coords The coords to match, sheet-qualified (`scope`) and in row-first order.
+     * @param home The cell of the formula the reference is for, when there is one. A reference can be
+     *   written relative to it: `Sales[@Amount]` for a table cell in the formula's own row, and from
+     *   inside the table `[@Amount]` and `[Amount]`.
      *
      * @remarks
      * * Optional
@@ -79,7 +82,7 @@ export interface INamed<T = any> extends IModel {
      * Implemented by whatever owns the parts (a table), so the collection stays out of the business
      * of knowing what kinds of items have insides.
      */
-    getPartReference?(coords: readonly IRange.Coords[]): string | null;
+    getPartReference?(coords: readonly IRange.Coords[], home?: IRange.CellCoords | null): string | null;
     /**
      * If true then the name is not visible.
      *

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

@@ -1,3 +1,4 @@
+import { IRange } from '@sheetxl/primitives';
 import { ICollection } from '../type';
 import { IListener } from '../listener';
 import { ICellRanges } from '../cellRange';
@@ -152,6 +153,21 @@ export declare namespace INamedCollection {
          * single definition, and a listener that re-reads the collection is the intended response.
          */
         onCollectionChange?(source: INamedCollection): void;
+        /**
+         * Called when an undo or a redo has moved what this collection presents, and a consumer holding
+         * it needs to re-read.
+         *
+         * @remarks
+         * Separate from {@link onCollectionChange} because a restore is not a write, and some listeners
+         * treat the two very differently: the calculation engine recalculates on a change, and firing
+         * that for a restore would recalculate a second time on top of the one the restore already did.
+         * A consumer rendering a LIST wants both, and subscribes to both.
+         *
+         * A derived name is what makes this necessary. A table's name is read back off the table rather
+         * than stored here, so an undo of a rename moves no state of this collection's and a
+         * change-only listener hears nothing.
+         */
+        onInvalidated?(source: INamedCollection): void;
         /**
          * Transaction items have a close event.
          */
@@ -225,6 +241,16 @@ export declare namespace INamedCollection {
          * the same region.
          */
         includeParts?: boolean;
+        /**
+         * The cell of the formula a part reference is for.
+         *
+         * @remarks
+         * Only read with `includeParts`. A table cell in the formula's own row is a this-row reference
+         * (`Sales[@Amount]`), and inside the table a single column drops the table name (`[Amount]`,
+         * `[@Amount]`). Without it every part is qualified (`Sales[Amount]`) and a row's cells are
+         * addresses.
+         */
+        home?: IRange.CellCoords | null;
     }
 }
 //# sourceMappingURL=INamedCollection.d.ts.map

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

@@ -1,18 +1,16 @@
+import { AbstractCollection } from '../type';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
 import { ICellRanges } from '../cellRange';
 import { INamed, INamedCollection } from '../named';
-import { ListenerEmitter } from '../listener/ListenerEmitter';
 export declare const REGEX_INVALID_NAME_FIRST_CHARS: RegExp;
 export declare const REGEX_INVALID_NAME_TRAILING_CHARS: RegExp;
 /**
  * Implementation for `INamedCollection`.
  */
-export declare class NamedCollection implements INamedCollection {
-    protected _emitter: ListenerEmitter<this, INamedCollection.IListeners>;
+export declare class NamedCollection extends AbstractCollection<INamed, INamedCollection.GetItemsOptions> implements INamedCollection {
     private _options;
-    private _transactions;
-    private _closed;
+    protected _transactions: ITransaction.IStore;
     private _lastLookup;
     private _lastLookupAddress;
     private _lastLookupType;
@@ -51,10 +49,8 @@ export declare class NamedCollection implements INamedCollection {
      * the name.
      */
     private _getOwningSource;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<INamed>;
-    /** {@inheritDoc INamedCollection.getItems} */
-    getItems(options?: INamedCollection.GetItemsOptions): INamed[];
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: INamedCollection.GetItemsOptions): INamed[];
     /** {@inheritDoc INamedCollection.getByRanges} */
     getByRanges(ranges: ICellRanges.Address, options?: INamedCollection.GetByRangesOptions): string[];
     /** {@link getByRanges}, against an explicit anchor — see {@link _scopedTo}. */
@@ -131,8 +127,6 @@ export declare class NamedCollection implements INamedCollection {
      * distinct names, so a scoped query must not report the global one as a hit.
      */
     private _findInSourcesByKey;
-    /** {@inheritDoc ICollection.getCount} */
-    getCount(): number;
     /** {@inheritDoc INamedCollection.findValidName} */
     findValidName(template: string, scope?: string | null, ignoreExisting?: boolean): string;
     /** {@inheritDoc INamedCollection.validateName} */
@@ -163,7 +157,7 @@ export declare class NamedCollection implements INamedCollection {
     private _invalidateLookup;
     /** {@inheritDoc IListener.ISource.addListeners} */
     addListeners(listeners: INamedCollection.IListeners, options?: IListener.Options): IListener.Remove;
-    isClosed(): boolean;
+    /** {@inheritDoc INamedCollection.close} */
     close(): void;
     /**
      * {@inheritDoc INamedCollection.isINamedCollection}
@@ -217,14 +211,21 @@ export declare namespace NamedCollection {
          */
         getItems(): readonly INamed[];
         /**
-         * Notified when items are added, removed, renamed or re-scoped.
+         * Notified when items are added, removed, renamed or re-scoped (`onCollectionChange`), and when
+         * an undo or a redo has moved them (`onInvalidated`).
          *
          * @remarks
-         * The aggregator re-emits this as its own `onCollectionChange`, which is also what drops its
-         * lookup memo — a source changing behind a cached result is otherwise invisible.
+         * The aggregator re-emits each as its own event of the same name, and either drops its lookup
+         * memo — a source changing behind a cached result is otherwise invisible.
+         *
+         * A source that has no restore of its own to report may implement only the first; one whose
+         * items are DERIVED (tables) has to report both, because an undo of a rename moves nothing this
+         * collection holds. The two stay separate all the way through: consumers of a restore and
+         * consumers of a write are not the same set.
          */
         addListeners(listeners: {
             onCollectionChange?: (...args: any[]) => void;
+            onInvalidated?: (...args: any[]) => void;
         }, options?: IListener.Options): IListener.Remove;
         /**
          * Creates a name owned by this source, if it can own one.

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

@@ -20,14 +20,22 @@ export declare const FIRST_CUSTOM_FORMAT_ID = 164;
 export declare const BUILT_IN_FORMAT_CODES: Readonly<Record<number, string>>;
 /**
  * Ids whose rendering adapts to the viewer's regional settings in Excel (the
- * `*`-prefixed formats in the Format Cells dialog, currency symbol ids, and
- * the regional/CJK 27-36 & 50-58 ranges).
+ * `*`-prefixed formats in the Format Cells dialog, currency symbol ids, the
+ * date/time ids Excel renders with a per-locale pattern, and the regional/CJK
+ * 27-36 & 50-58 ranges).
  *
- * Today only 14/22 render adaptively (via the Intl interception in
- * `toLocaleDateCore`); the rest resolve to their canonical en-US codes.
- * I18N-DESIGN Plane 1 substitutes LocaleProfile-derived patterns here.
+ * The date/time ids render through {@link getLocaleBuiltInFormatCode} where a
+ * locale's pattern is known, and 14/22 fall back to `Intl` otherwise
+ * (`toLocaleDateCore`). The rest resolve to their canonical en-US codes.
  */
 export declare const LOCALE_ADAPTIVE_IDS: ReadonlySet<number>;
+/**
+ * The code a built-in id renders with in `locale`, or `undefined` when the
+ * locale is not measured or renders the canonical code.
+ *
+ * @param locale BCP-47 tag. @defaultValue 'en-US'
+ */
+export declare function getLocaleBuiltInFormatCode(id: number, locale?: string): string | undefined;
 /** The raw ECMA table lookup, or `undefined` for unknown ids. */
 export declare function getBuiltInFormatCode(id: number): string | undefined;
 /**
@@ -42,8 +50,13 @@ export declare function getBuiltInFormatCode(id: number): string | undefined;
  */
 export declare function resolveNumberFormat(ref: NumberFormatRef): string;
 /**
- * Find the built-in id for a format code (exact match, lowest id wins), or
- * `undefined` if the code is not a built-in.
+ * The preset names a format may be given by (`Short Date`, `Fixed`), and the code or built-in
+ * id each stands for. A name is not a code: its letters are not tokens.
+ */
+export declare const XMLFormatMap: Readonly<Record<string, string | number>>;
+/**
+ * Find the built-in id Excel saves a format code as, or `undefined` if Excel
+ * saves it as a custom format.
  */
 export declare function findBuiltInFormatId(code: string): number | undefined;
 //# sourceMappingURL=BuiltInFormats.d.ts.map

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

@@ -138,6 +138,8 @@ export interface IFormatEngine {
     getFormatDateInfo(format: NumberFormatRef): FormatDateInfo | null;
     /** True if the format code parses (usable for live custom-code validation). */
     isValidFormat(format: NumberFormatRef): boolean;
+    /** For runtime type checking. */
+    readonly isIFormatEngine: true;
 }
 /**
  * The number-format engine.

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

@@ -29,5 +29,7 @@ export declare class NumfmtFormatEngine implements IFormatEngine {
     getFormatDateInfo(format: NumberFormatRef): FormatDateInfo | null;
     /** @inheritdoc IFormatEngine.isValidFormat */
     isValidFormat(format: NumberFormatRef): boolean;
+    /** {@inheritDoc IFormatEngine.isIFormatEngine} */
+    get isIFormatEngine(): true;
 }
 //# sourceMappingURL=NumfmtFormatEngine.d.ts.map

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

@@ -1,9 +1,18 @@
 import { ScalarType, Scalar, IRuntime } from '@sheetxl/primitives';
 import { IColor } from '../color';
-import { IStyle } from '../style';
+import { ICellStyle } from '../style';
 import { NumberFormatRef } from './BuiltInFormats';
 import { Parsed, ParserOptions } from './NumberFormatParser';
-export declare function parseNumberFormat(runtime: IRuntime, value: Scalar, style: IStyle, type: ScalarType, numberFormat: NumberFormatRef, parseColor: (val: any) => IColor): Parsed;
+/**
+ * The text a value shows under a number format: the `displayText` of {@link parseNumberFormat}
+ * without a cell or its style.
+ *
+ * @remarks
+ * For a reader of many cells that wants only their text (a filter judging a column): what a cell
+ * shows follows from its value and its format, and a run of cells shares the format.
+ */
+export declare function formatDisplayText(runtime: IRuntime, value: Scalar, numberFormat: NumberFormatRef): string;
+export declare function parseNumberFormat(runtime: IRuntime, value: Scalar, style: ICellStyle, type: ScalarType, numberFormat: NumberFormatRef, parseColor: (val: any) => IColor): Parsed;
 /**
  * The unformatted text for a number.
  *

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

@@ -43,7 +43,6 @@ export declare function toLocaleDateCore(format: NumberFormatRef, value: number,
     fmt: string;
     date: Date;
 } | null;
-export declare const XMLFormatMap: Readonly<Record<string, string | number>>;
 /**
  * Returns a legacy color as an rgb value
  */

package/types/src/numFmt/vendor/numfmt/_sheetxl.d.ts

@@ -13,3 +13,9 @@ export declare function roundDisplay(value: number, places: number): number;
 
 /** §3a — `String(value)` with the exponential form expanded to plain decimal notation. */
 export declare function toDecimalString(value: number): string;
+
+/**
+ * Which calendar (`date`) and clock (`time`) parts a format code evaluates, read off the
+ * parser. Neither for a code whose only date tokens are elapsed ones, and for an illegal code.
+ */
+export declare function dateTimeParts(pattern: string): { readonly date: boolean, readonly time: boolean };

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

@@ -0,0 +1,186 @@
+import { IRange } from '@sheetxl/primitives';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+/**
+ * The row and column groups on a sheet, and how they are laid out.
+ *
+ * @remarks
+ * There is no group object to create or delete. Every row and column carries an outline level,
+ * `0` to `7` ({@link ICellHeader.getOutlineLevel}), and a group at level *n* is a run of
+ * consecutive rows (or columns) whose level is *n* or more. Its summary row is the one just past
+ * the run, on the side {@link getSummaryDirection} names. Collapsing a group hides its detail rows.
+ *
+ * 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}.
+ *
+ * The counterpart of Excel's `Worksheet.Outline`.
+ */
+export interface IOutline extends IListener.ISource<IOutline, IOutline.Events> {
+    /**
+     * Where a group's summary sits: `down` or `up` for rows, `right` or `left` for columns.
+     *
+     * @defaultValue `down` for rows, `right` for columns.
+     */
+    getSummaryDirection(axis: IRange.Axis): IRange.Direction;
+    /**
+     * Sets where a group's summary sits.
+     *
+     * @throws `Error` If the direction does not belong to the axis (`left` for rows).
+     */
+    setSummaryDirection(axis: IRange.Axis, direction: IRange.Direction, options?: ITransaction.OperationOptions): this;
+    /**
+     * Whether the automatic outline styles are applied to summary rows and columns.
+     *
+     * @defaultValue false
+     */
+    isAutomaticStyles(): boolean;
+    /**
+     * Sets whether the automatic outline styles are applied.
+     */
+    setAutomaticStyles(automatic: boolean, options?: ITransaction.OperationOptions): this;
+    /**
+     * The deepest outline level in use on the axis; `0` when nothing is grouped.
+     */
+    getLevelCount(axis: IRange.Axis): number;
+    /**
+     * The groups on an axis, outermost level first and in order within a level.
+     *
+     * @param axis The axis.
+     * @param options Limits the groups returned.
+     */
+    getGroups(axis: IRange.Axis, options?: IOutline.GetGroupsOptions): readonly IOutline.Group[];
+    /**
+     * Expands the groups up to a level and collapses everything deeper, as the level buttons do.
+     *
+     * @param axis The axis.
+     * @param levels How many levels stay visible, from `1` (only the outermost summaries); more levels
+     * than exist shows every row or column.
+     *
+     * @remarks
+     * The counterpart of Excel's `Outline.ShowLevels` and Office Scripts' `showOutlineLevels`, one
+     * axis at a time.
+     */
+    setVisibleLevels(axis: IRange.Axis, levels: number, options?: ITransaction.OperationOptions): this;
+    /**
+     * Removes every outline level from the sheet. Hidden rows and columns stay hidden.
+     *
+     * @param axes Which levels to remove. Default `IRange.AxisSelection.Both`.
+     * @returns The current `IOutline`.
+     * @throws `Error` If the sheet is protected.
+     *
+     * @remarks
+     * The whole-sheet form of {@link ICellRange.clearGroups}, which is what Excel's Clear Outline
+     * does with one cell selected.
+     */
+    clear(axes?: IRange.AxisSelection, options?: ITransaction.OperationOptions): this;
+    /**
+     * Outlines the sheet from its formulas: a cell whose formula totals the cells on one side of it
+     * in its own column makes its row a summary row and those rows a group, and the same for
+     * columns.
+     *
+     * @returns The current `IOutline`.
+     * @throws `Error` If no summary rows or columns are found, or the sheet is protected.
+     *
+     * @remarks
+     * The counterpart of Excel's `Range.AutoOutline`, which outlines the whole sheet whatever the
+     * range. Any outline the sheet already has is removed first, and the summary direction of each
+     * axis is set to where its first summary sits: below and right, or above and left.
+     */
+    autoOutline(options?: ITransaction.OperationOptions): this;
+    /**
+     * The settings that differ from their defaults, or `null` when none do.
+     *
+     * @remarks
+     * The levels themselves are saved with the rows and columns, not here.
+     */
+    toJSON(): IOutline.JSON | null;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIOutline: true;
+}
+/**
+ * {@inheritDoc IOutline}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IOutline}
+ */
+export declare namespace IOutline {
+    /**
+     * A group of rows or columns.
+     */
+    interface Group {
+        /**
+         * The level, from `1`; level 1 is the outermost.
+         */
+        level: number;
+        /**
+         * The first detail row or column.
+         */
+        start: number;
+        /**
+         * The last detail row or column, inclusive.
+         */
+        end: number;
+        /**
+         * The summary row or column, or `null` when the group runs to the edge of the sheet on the
+         * summary side.
+         */
+        summary: number | null;
+        /**
+         * Whether the details are collapsed: every one of them is hidden, whoever hid them.
+         *
+         * @remarks
+         * Read from the hidden details, as Excel reads it. A group whose summary is itself hidden,
+         * inside a collapsed outer group, reads collapsed only when it was collapsed before the outer
+         * one; expanding the outer group leaves such a group collapsed and opens the rest.
+         */
+        collapsed: boolean;
+    }
+    /**
+     * Options for {@link IOutline.getGroups}.
+     */
+    interface GetGroupsOptions {
+        /**
+         * Only this level. Omitted returns every level.
+         */
+        level?: number;
+        /**
+         * Only groups that meet the span from here (a viewport). Includes the summary.
+         */
+        from?: number;
+        /**
+         * Only groups that meet the span to here, inclusive.
+         */
+        to?: number;
+    }
+    /**
+     * The outline settings that differ from their defaults.
+     */
+    interface JSON {
+        /**
+         * Present, as `up`, when a group's summary row sits above its details.
+         */
+        summaryRow?: 'up';
+        /**
+         * Present, as `left`, when a group's summary column sits left of its details.
+         */
+        summaryColumn?: 'left';
+        /**
+         * Present, as `true`, when the automatic outline styles are applied.
+         */
+        automaticStyles?: true;
+    }
+    interface Events {
+        /**
+         * Called when the outline changes: its settings, a level, or which details are shown.
+         */
+        onOutlineChange?(source: IOutline): void;
+    }
+    interface IListeners extends IListener.Callbacks<IOutline, IOutline.Events> {
+    }
+}
+//# sourceMappingURL=IOutline.d.ts.map