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

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

@@ -4,7 +4,7 @@ import { ITransaction } from '../transaction';
 import { IResource } from '../resource';
 import { IListener } from '../listener';
 import { IModel } from '../model';
-import { ICellRange } from '../cellRange';
+import { ICellRange, ICellRanges } from '../cellRange';
 import { IHistory } from '../history';
 import { IAnchored } from '../anchored';
 import { IMovableCollection } from './IMovableCollection';
@@ -29,9 +29,97 @@ export interface IMovable extends IAnchored, ITransaction.ITransactional, IHisto
      */
     getRange(options?: ICellRange.GetRangeOptions): ICellRange;
     /**
-     * Returns the content of the movable.
+     * Returns the content of the movable: what is drawn at this position.
+     *
+     * @remarks
+     * The content's `getType()` says which interface to read it as:
+     *
+     * | `getType()` | content |
+     * | --- | --- |
+     * | `'picture'` | {@link IPicture} |
+     * | `'chart'` | {@link IChart} |
+     * | `'shape'` | {@link IShape} — text boxes, callouts and connectors |
+     * | `'group'` | {@link IGroup} — a group of movables, each a member with its own content |
+     * | `'slicer'` | {@link ISlicer} |
+     * | `'checkBox'`, `'button'`, `'scrollBar'`, … | {@link IFormControl} — a form control, one type per kind ({@link IFormControl.Type}) |
+     *
+     * A host adds kinds of its own through {@link MovableContentRegistry}. Anything else is content
+     * that is positioned and saved but not modeled; it answers {@link IMovable.IContent} and nothing
+     * more.
+     *
+     * The content owns what identifies it: its name, its description and its id. The movable owns
+     * where it is drawn. To remove both, delete the content.
+     *
+     * @example
+     * ```ts
+     * const content = movable.getContent();
+     * if (content.getType() === 'shape') {
+     *   const text = (content as IShape).getTextFrame()?.getText();
+     * }
+     * content.delete();
+     * ```
+     */
+    getContent<T extends IMovable.IContent = IMovable.IContent>(): T;
+    /**
+     * Returns the movable that holds this one, or `null` at the root: the movable whose
+     * {@link getMovables} lists it.
+     *
+     * @remarks
+     * A member's {@link getBounds}, {@link getRotation} and {@link getFlip} are where it is drawn on
+     * the canvas, as any movable's are: what holds it hands it, when it is made, the mapping between
+     * the space its placement is kept in (a group's child space, as the file states it) and where the
+     * holder is drawn, so a member is read and edited like a root and nothing walks the chain. A
+     * member's placement changes with every movable above it, and announces
+     * {@link IMovable.Events.onBoundsChange} when it does.
+     */
+    getParent(): IMovable | null;
+    /**
+     * The movables this one holds, in z-order (the first is drawn first), or `null` when its content
+     * holds none.
+     *
+     * @remarks
+     * A group's movable holds its members. As on a sheet ({@link ISheet.getMovables}), adding to the
+     * collection places a movable here, at canvas bounds; deleting a member's content takes it out.
+     * Each member's {@link getParent} is this movable.
+     *
+     * @example
+     * ```ts
+     * for (const member of movable.getMovables()?.getItems() ?? []) {
+     *   console.log(member.getContent().getName?.(), member.getBounds());
+     * }
+     * ```
      */
-    getContent<T extends IModel>(): T;
+    getMovables(): IMovableCollection | null;
+    /**
+     * The cells the content names, or `null` when it names none. The same as
+     * `getContent().getReferences()`; see {@link IMovable.IContent.getReferences}.
+     *
+     * @remarks
+     * Not where this movable sits, which is {@link getRange}.
+     */
+    getReferences(): ICellRanges | null;
+    /**
+     * Whether the content has settled, rather than being a stand-in for a kind still loading.
+     *
+     * @remarks
+     * A kind registered with a loader ({@link MovableContentRegistry.Lazy}) is fetched the first
+     * time a workbook holds one. Until it arrives, {@link getContent} answers a stand-in that has
+     * the kind's type, name and description, saves as it was read, and is read-only. Reading a
+     * workbook ({@link IWorkbookIO.read}) and {@link IMovableCollection.add} wait for the load, so
+     * this is only ever `false` for a workbook built directly from JSON.
+     *
+     * A kind that fails to load, or throws when created, settles as an {@link IErrorContent}.
+     */
+    isContentLoaded(): boolean;
+    /**
+     * Resolves with the content once it has settled: at once when it already has, and with an
+     * {@link IErrorContent} when it could not be made.
+     */
+    whenContentLoaded(): Promise<IMovable.IContent>;
+    /**
+     * Deletes the content, which removes this movable. The same as `getContent().delete()`.
+     */
+    delete(): void;
     /**
      * Selects the current movable.
      *
@@ -48,11 +136,12 @@ export interface IMovable extends IAnchored, ITransaction.ITransactional, IHisto
      */
     isSelected: () => boolean;
     /**
-     * Set the absolution position of a movable in pixels.
+     * Set the position and size of the movable's unrotated frame, in pixels.
      * @param bounds The new bounds.
      *
      * @remarks
-     * If only some of the points are provided then only those will be moved.
+     * If only some of the points are provided then only those will be moved. The frame is what
+     * {@link getBounds} returns; the cells the movable is anchored to follow from it and the rotation.
      */
     setBounds(bounds: Partial<Bounds>, options?: ITransaction.OperationOptions): IMovable;
     /**
@@ -65,51 +154,69 @@ export interface IMovable extends IAnchored, ITransaction.ITransactional, IHisto
      */
     scrollIntoView: (options?: globalThis.ScrollIntoViewOptions | boolean) => Promise<boolean>;
     /**
-     * Returns the absolute bounds of the movable object in pixels or `null` if not yet laid out.
+     * Returns the movable's unrotated frame in pixels, or `null` if not yet laid out.
+     *
+     * @remarks
+     * The frame is the box the movable is drawn in before it is turned by {@link getRotation}, about
+     * its center. A rotated movable is anchored to the cells of the box it occupies as rotated,
+     * which Excel takes to be the frame with its width and height swapped when the rotation is within
+     * 45° of 90° or 270°, and the frame itself otherwise.
      */
     getBounds(): Bounds | null;
     /**
-     * Set the name for a movable object.
-     *
-     * @param name The name of the IMovable.
+     * If true then the movable object is hidden.
      */
-    setName(name: string): IMovable;
+    setHidden(hidden: boolean): IMovable;
     /**
      * @see
-     * {@link setName}
-     *
-     * @returns The name or `null` if the movable has been deleted.
+     * {@link setHidden}
      */
-    getName(): string | null;
+    isHidden(): boolean;
     /**
-     * This is the alternative text use for assistive technologies.
+     * Set the rotation in degrees, clockwise about the frame's center.
+     *
+     * @remarks
+     * The frame keeps its position and size; the cells the movable is anchored to are those of the
+     * box it then occupies (see {@link getBounds}). Whether the content can be turned, and to what, is
+     * the content's to say ({@link IMovable.IContent.acceptRotation}); a chart cannot, and ignores it.
      */
-    setDescription(description: string | null): IMovable;
+    setRotation(rotation: number): IMovable;
     /**
      * @see
-     * {@link setDescription}
-     *
-     * @returns The description or `null` if none has been set (or the movable has been deleted).
+     * {@link setRotation}
      */
-    getDescription(): string | null;
+    getRotation(): number;
     /**
-     * If true then the movable object is hidden.
+     * Mirror the content within its frame, left to right and/or top to bottom.
+     *
+     * @param flip The axes to set; an axis left out keeps its value.
+     *
+     * @remarks
+     * The frame keeps its position, size and rotation: a flip is applied in the frame's own axes,
+     * before the turn, as in Excel. Whether the content can be mirrored is the content's to say
+     * ({@link IMovable.IContent.acceptFlip}); a chart cannot, and ignores it.
      */
-    setHidden(hidden: boolean): IMovable;
+    setFlip(flip: Partial<IMovable.Flip>, options?: ITransaction.OperationOptions): IMovable;
     /**
      * @see
-     * {@link setHidden}
+     * {@link setFlip}
      */
-    isHidden(): boolean;
+    getFlip(): IMovable.Flip;
     /**
-     * Set the rotation in degrees.
-     */
-    setRotation(rotation: number): IMovable;
-    /**
-     * @see
-     * {@link setHidden}
+     * The movable's connection sites on the sheet, placed as it is: where a connector's end glued
+     * to each one sits.
+     *
+     * @remarks
+     * Which sites a movable has is its content's to say ({@link IMovable.IContent.getConnections}):
+     * a picture, a chart or a control offers the four edge midpoints, a shape its geometry's, a
+     * group none. Synchronous; `null` while the content has not answered yet (a shape before its
+     * first evaluation, which this starts).
+     *
+     * @param placement Where the movable is, as a gesture previews it; its own placement when omitted.
      */
-    getRotation(): number;
+    getConnectionSites(placement?: IMovable.PlacementPreview): IMovable.ConnectionSite[] | null;
+    /** The connectors on the sheet with an end glued to this movable. */
+    getGluedConnectors(): IMovable[];
     /**
      * If true then the aspect should be maintained during resize if using the corners or if
      * the api only specifies one dimension.
@@ -172,6 +279,194 @@ export interface IMovable extends IAnchored, ITransaction.ITransactional, IHisto
  * {@link IMovable}
  */
 export declare namespace IMovable {
+    /**
+     * `Events` for {@link IMovable.IContent}.
+     */
+    interface ContentEvents extends IModel.Events {
+        /**
+         * Called when the cells the content names have changed: the engine rewrote a reference the
+         * content holds after an insert, a delete, a cut or an undo. See {@link IContent.getReferences}.
+         */
+        onReferencesChange?(source: IContent): void;
+    }
+    /**
+     * Whether a movable's content is mirrored within its frame, per axis.
+     */
+    interface Flip {
+        /** Mirrored left to right. */
+        horizontal: boolean;
+        /** Mirrored top to bottom. */
+        vertical: boolean;
+    }
+    /**
+     * Where a movable is drawn: its unrotated frame, and the rotation and flips applied to it there.
+     * What {@link getBounds}, {@link getRotation} and {@link getFlip} answer, as one value.
+     */
+    interface Placement {
+        /** The unrotated frame, in the pixels of the space the placement is stated in. */
+        bounds: Bounds;
+        /** Degrees, clockwise about the frame's center. */
+        rotation: number;
+        /** How the content is mirrored within the frame, before the turn. */
+        flip: Flip;
+    }
+    /**
+     * A placement as a gesture previews it, with the adjust values the content is drawn with while
+     * the gesture drags one of its handles: a shape's connection sites move with them.
+     */
+    interface PlacementPreview extends Placement {
+        adjustments?: Readonly<Record<string, number>> | null;
+    }
+    /**
+     * A point a connector's end may be glued to, in a content's own frame (its top-left is 0,0),
+     * before the frame is placed.
+     */
+    interface Connection {
+        /** The site's number, as a connector's end names it. */
+        readonly index: number;
+        readonly x: number;
+        readonly y: number;
+        /** The direction a connector leaves the site, in degrees clockwise from +x. */
+        readonly ang: number;
+    }
+    /** A connection site on the sheet, in pixels: a {@link Connection} placed as its movable is. */
+    interface ConnectionSite {
+        /** The site's number, as {@link IShape.IConnectorFormat.startConnect} takes it. */
+        index: number;
+        x: number;
+        y: number;
+    }
+    /** What {@link IContent.getConnections} answers for, beyond the frame's size. */
+    interface ConnectionsOptions {
+        /**
+         * Adjust values a gesture has the content drawn with, in place of its own: a shape's sites
+         * move with them. `null` for the preset's defaults; omitted for the content's own.
+         */
+        adjustments?: Readonly<Record<string, number>> | null;
+        /** Called once a content that answered `null` can answer; a shape's first evaluation landing. */
+        onReady?: () => void;
+    }
+    /**
+     * What a movable draws: a chart, a picture, a shape, a slicer, a control.
+     *
+     * @remarks
+     * Content owns what identifies it, and the movable owns where it is drawn. Content can exist
+     * with no movable: a picture used as a sheet background is not placed by one.
+     *
+     * The movable owns its placement (bounds, rotation, flip) but the content says which of these
+     * it can take: a kind that defines {@link acceptRotation} can be turned and one that defines
+     * {@link acceptFlip} can be mirrored. A kind that defines neither, such as a chart, is placed by
+     * its bounds alone.
+     */
+    interface IContent {
+        /**
+         * Returns an immutable type string.
+         */
+        getType(): string;
+        /**
+         * Returns the id of the content.
+         */
+        getId(): string;
+        /**
+         * Returns the name, or `null` if the content has none.
+         *
+         * @remarks
+         * Not defined for content that is never named.
+         */
+        getName?(): string | null;
+        /**
+         * Set the name.
+         *
+         * @param name The name of the content.
+         */
+        setName?(name: string): this;
+        /**
+         * Returns the alternative text used by assistive technologies, or `null` if none has been set.
+         */
+        getDescription(): string | null;
+        /**
+         * Set the alternative text used by assistive technologies.
+         */
+        setDescription(description: string | null): this;
+        /**
+         * Returns a label for the kind of content, such as `Chart` or `Picture`.
+         */
+        getTypeDescription(): string;
+        /**
+         * Returns the movable that places the content on the sheet, or `null` if it is not placed by
+         * one.
+         */
+        getMovable(): IMovable | null;
+        /**
+         * Returns the cells the content names - a chart's series, a control's linked cell, a slicer's
+         * column - or `null` when it names none.
+         *
+         * @remarks
+         * Not where the movable sits: that is {@link IMovable.getRange}. The references are formulas
+         * the calculation engine holds, so they follow the cells they name through inserts, deletes,
+         * cuts, sheet renames and undo, and {@link ContentEvents.onReferencesChange} is announced when
+         * they have. A reference to deleted cells is left out. Without a running engine the references
+         * read as they were set.
+         */
+        getReferences(): ICellRanges | null;
+        /**
+         * Deletes the content, and with it the movable that places it.
+         */
+        delete(options?: ITransaction.OperationOptions): void;
+        /**
+         * Returns `true` if the content has been deleted.
+         */
+        isDeleted(): boolean;
+        /**
+         * The rotation this content takes when asked to turn by `degrees`, clockwise.
+         *
+         * @remarks
+         * Defined by content that can be turned, such as a shape or a picture; absent, the content
+         * cannot and no rotate handle is offered. Must be pure: it is asked throughout a gesture to
+         * draw its preview, and the answer is what the movable stores.
+         */
+        acceptRotation?(degrees: number): number;
+        /**
+         * The flip this content takes when asked to mirror as `flip` states.
+         *
+         * @remarks
+         * Defined by content that can be mirrored, such as a shape or a picture; absent, the content
+         * cannot: a frame dragged through its opposite edge is moved there but not mirrored, as Excel
+         * does with a chart. Must be pure, as {@link acceptRotation} is. A connector may accept each
+         * axis on its own.
+         */
+        acceptFlip?(flip: Flip): Flip;
+        /**
+         * How a movable of this content moves and sizes with the cells under it when it is added
+         * without an anchor type.
+         *
+         * @remarks
+         * Absent, it moves and sizes with them ({@link IAnchored.Type.TwoCell}), as Excel inserts a
+         * shape or a chart. A picture moves with its cell but keeps its size.
+         */
+        getDefaultAnchorType?(): IAnchored.Type;
+        /**
+         * Whether a movable of this content keeps its aspect ratio when resized from a corner, when it
+         * states no lock of its own.
+         *
+         * @remarks
+         * Absent, it does not. A picture does.
+         */
+        isDefaultLockAspectRatio?(): boolean;
+        /**
+         * The points a connector's end may be glued to, in a `width` by `height` frame of this
+         * content, before the frame is placed.
+         *
+         * @remarks
+         * Absent, the four edge midpoints — top, left, bottom, right, numbered in that order, each
+         * leaving straight out — as Excel offers on a picture, a chart, a slicer or a control. A
+         * shape is the exception and answers its geometry's own sites (a triangle's three, a
+         * connector's none); a group answers none, since Excel glues to a group's members and never
+         * to the group. Must be synchronous: `null` means the content cannot answer yet and will call
+         * `options.onReady` when it can.
+         */
+        getConnections?(width: number, height: number, options?: IMovable.ConnectionsOptions): readonly IMovable.Connection[] | null;
+    }
     /**
      * Extends {@link ITypes.SelectOptions} to include options for `IMovable`.
      */
@@ -185,6 +480,26 @@ export declare namespace IMovable {
          */
         addToSelection?: boolean;
     }
+    /**
+     * Options for an operation on movables that can select what it acted on.
+     */
+    interface OperationOptions extends ITransaction.OperationOptions {
+        /**
+         * Select the movables the operation leaves the user working on, once it completes.
+         *
+         * @remarks
+         * Resolved once, when the outermost operation closes: within a batch the selection is where
+         * the last operation that asked leaves it, an `addToSelection` extending what came before.
+         */
+        autoSelect?: boolean | IMovable.SelectOptions;
+        /**
+         * Select what the operation acted on when it is undone or redone: an undo lands on the
+         * selection it began with, a redo where it left the user.
+         *
+         * @defaultValue {@link autoSelect}
+         */
+        autoSelectRestore?: boolean;
+    }
     /**
      * `Events` for {@link IMovable} events.
      */
@@ -194,11 +509,8 @@ export declare namespace IMovable {
          */
         onSelectionChange?(source: IMovable): void;
         /**
-         * Called when the name has changed.
-         */
-        onNameChange?(source: IMovable): void;
-        /**
-         * Called when selection changes.
+         * Called when the bounds have changed, or, for a member of a group, when where it is drawn has:
+         * a movable above it moved, turned, mirrored or resized.
          */
         onBoundsChange?(source: IMovable): void;
         /**
@@ -274,14 +586,32 @@ export declare namespace IMovable {
          * This must align to a known movable object type. Defined in the IEmbeddedDrawing interface.
          */
         type: string;
+        /**
+         * The name of the content.
+         */
+        name?: string;
+        /**
+         * The alternative text used by assistive technologies.
+         */
+        description?: string;
         /**
          * Underlying json.
+         *
+         * @remarks
+         * Content that holds movables ({@link IMovable.getMovables}) states them here as
+         * `members`, an array of {@link IMovable.JSON}, so the kinds a tree needs are loaded before it
+         * is built.
          */
         json: J;
     }
     interface JSON<J = any> {
         /**
          * The anchor for the movable object.
+         *
+         * @remarks
+         * On the sheet, the cells of both corners and the offsets into them; an absolute anchor
+         * states `tl` as a position and `br` as a size, with no cells. A member of a group is always
+         * the latter, in the group's child space ({@link IGroup.JSON.childBounds}).
          */
         anchor: IMovable.AnchorOffset;
         /**
@@ -292,16 +622,6 @@ export declare namespace IMovable {
          * The behavior of how the movable resizes as the anchor/cells change.
          */
         anchorType?: IAnchored.Type;
-        /**
-         * The name of the movable object.
-         */
-        name?: string;
-        /**
-         * This is the alternative text use for assistive technologies.
-         *
-         * @defaultValue null
-         */
-        description?: string;
         /**
          * If true then the movable object is hidden.
          *
@@ -314,6 +634,18 @@ export declare namespace IMovable {
          * @defaultValue 0
          */
         rotation?: number;
+        /**
+         * Mirrored left to right within the frame.
+         *
+         * @defaultValue false
+         */
+        flipH?: boolean;
+        /**
+         * Mirrored top to bottom within the frame.
+         *
+         * @defaultValue false
+         */
+        flipV?: boolean;
         /**
          * Whether resizing should keep the aspect ratio.
          */

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

@@ -5,7 +5,6 @@ import { IResource, IResourceCollection } from '../resource';
 import { IListener } from '../listener';
 import { ICellRange } from '../cellRange';
 import { IMovable } from './IMovable';
-import { ITransaction } from '../transaction';
 /**
  * Holds a collection of IMovables.
  */
@@ -40,6 +39,19 @@ export interface IMovableCollection extends ICollection<IMovable>, IListener.ISo
      * @returns A Promise that will resolve to the new Movable.
      */
     addPicture(picture: string | IResource | IResourceCollection.AddOptions, options?: IMovableCollection.AddOptions): Promise<IMovable>;
+    /**
+     * Groups movables of this collection into one: a new movable whose content is an `IGroup`
+     * holding them as members, in their z-order, at the union of the boxes they occupy.
+     *
+     * @param movables Two or more movables of this collection.
+     * @param options {@link IMovableCollection.GroupOptions}
+     * @returns The group's movable.
+     *
+     * @remarks
+     * One undo step. The group's child space equals its frame, so each member keeps the size it
+     * had. `IGroup.ungroup` is the inverse.
+     */
+    group(movables: readonly IMovable[], options?: IMovableCollection.GroupOptions): Promise<IMovable>;
     /**
      * Add Listeners.
      *
@@ -47,6 +59,8 @@ export interface IMovableCollection extends ICollection<IMovable>, IListener.ISo
      * {@link IListener.ISource.addListeners}
      */
     addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** For runtime type checking. */
+    readonly isIMovableCollection: true;
 }
 /**
  * {@inheritDoc IMovableCollection}
@@ -84,11 +98,45 @@ export declare namespace IMovableCollection {
          * @defaultValue false
          */
         fullyContained?: boolean;
+        /**
+         * Also return the members of every group found, each after its group, nested groups
+         * included. The type filter applies to members too.
+         * @defaultValue false
+         */
+        deep?: boolean;
+        /**
+         * Match {@link address} against what each movable paints rather than the cells it is anchored
+         * to: its rotation, a drawing that reaches outside its frame (a callout's tail) and its line.
+         * Use it to find the movables visible in a range.
+         *
+         * @remarks
+         * A shape's drawing is known once its geometry has been evaluated, which the search starts;
+         * until then it is matched by its frame, and the collection notifies a change when the answer
+         * is ready. Ignored with {@link fullyContained}.
+         * @defaultValue false
+         */
+        drawn?: boolean;
+    }
+    /**
+     * Options for {@link IMovableCollection.group}.
+     */
+    interface GroupOptions extends IMovable.OperationOptions {
+        /**
+         * The name of the group.
+         *
+         * @defaultValue A name made from the type, such as `Group 3`.
+         */
+        name?: string;
+        /**
+         * Whether the group is selected once made.
+         * @defaultValue true
+         */
+        autoSelect?: boolean | IMovable.SelectOptions;
     }
     /**
      * Options for adding a movable to the collection.
      */
-    interface AddOptions<J = any> extends ITransaction.OperationOptions {
+    interface AddOptions<J = any> extends IMovable.OperationOptions {
         /**
          * The type of movable to add.
          */
@@ -97,6 +145,12 @@ export declare namespace IMovableCollection {
          * Initial json value.
          */
         json?: J;
+        /**
+         * The name of the content.
+         *
+         * @defaultValue A name made from the type, such as `Chart 3`.
+         */
+        name?: string;
         /**
          * If a referenceId is provided then the movable will be linked to the resource.
          * @param resourceId
@@ -104,9 +158,15 @@ export declare namespace IMovableCollection {
          */
         fromResourceId?: (resourceId: number) => IResource;
         /**
-         * The boundary for the movable object in pixels.
+         * The movable's unrotated frame in pixels (see {@link IMovable.getBounds}).
          */
         bounds?: Partial<Bounds>;
+        /**
+         * The rotation in degrees, clockwise about the frame's center.
+         *
+         * @defaultValue 0
+         */
+        rotation?: number;
         /**
          * Placement hint used only when {@link bounds} is omitted. `'viewport'` centers the (default-sized)
          * movable in the visible viewport via {@link ISheet.IListeners.onRequestViewport}, falling back to the