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

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 IWorksheet.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());
+     * }
+     * ```
+     */
+    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}.
      */
-    getContent<T extends IModel>(): T;
+    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}
-     */
-    isHidden(): boolean;
-    /**
-     * Set the rotation in degrees.
+     * {@link setFlip}
      */
-    setRotation(rotation: number): IMovable;
+    getFlip(): IMovable.Flip;
     /**
-     * @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.
@@ -123,6 +230,17 @@ export interface IMovable extends IAnchored, ITransaction.ITransactional, IHisto
      * {@link setLockAspectRatio}
      */
     isLockAspectRatio(): boolean;
+    /**
+     * Whether the movable is printed with the sheet. Excel's **Print object**.
+     *
+     * @defaultValue true
+     */
+    setPrintObject(printObject: boolean): IMovable;
+    /**
+     * @see
+     * {@link setPrintObject}
+     */
+    isPrintObject(): boolean;
     /**
      * Ses the anchor type.
      */
@@ -172,6 +290,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 +491,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 +520,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;
         /**
@@ -238,7 +561,7 @@ export declare namespace IMovable {
         /**
          * Called when the movable is copied to a new container.
          */
-        copyTo(destination: IMovable.SnapshotDestination, options?: IMovable.CopyOptions): Promise<Bounds> | Bounds;
+        copyTo(destination: IMovable.SnapshotDestination, options?: IMovable.CopyOptions): Bounds;
     }
     interface CopyOptions extends ReferenceableClipboard.CopyOptions {
         /** {@inheritDoc IMovable.SelectOptions} */
@@ -254,18 +577,6 @@ export declare namespace IMovable {
         tl: OffsetCoords;
         br: OffsetCoords;
     }
-    interface ClientData {
-        /**
-         * disable selection on movable elements when the sheet is protected
-         * @defaultValue false
-         */
-        fLocksWithSheet?: boolean;
-        /**
-         * print movable elements when printing the sheet
-         * @defaultValue true
-         */
-        fPrintsWithSheet?: boolean;
-    }
     interface ContentJSON<J> {
         /**
          * Identifies the type of movable object.
@@ -274,14 +585,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 +621,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 +633,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.
          */
@@ -321,7 +652,21 @@ export declare namespace IMovable {
         /**
          * lock specific fields*/
         locks?: any;
-        clientData?: IMovable.ClientData;
+        /**
+         * If true then the movable is left out when the sheet is printed.
+         *
+         * @defaultValue false
+         */
+        noPrint?: boolean;
+        /**
+         * If true then the movable can still be selected and edited while the sheet is protected.
+         *
+         * @remarks
+         * Carried for the file; sheet protection does not guard movables yet.
+         *
+         * @defaultValue false
+         */
+        unlocked?: boolean;
     }
 }
 //# sourceMappingURL=IMovable.d.ts.map