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

package/types/src/shape/IShape.d.ts

@@ -1,28 +1,180 @@
-import { Point, Rectangle } from '@sheetxl/utils';
-import { IListener } from '../listener';
+import { Point } from '@sheetxl/utils';
+import { ITransaction } from '../transaction';
 import { IResource } from '../resource';
 import { IModel } from '../model';
+import { IMovable } from '../movable';
 import { IHyperlink } from '../hyperlink';
-import { IFill } from '../fill';
-import { IStroke } from '../fill/IStroke';
+import { IStroke, IFill, IEffect } from '../fill';
+import { ITheme } from '../theme';
+import { ITextFrame } from '../text';
+import { IGeometry } from './IGeometry';
+import { IShapeStyle } from './IShapeStyle';
 /**
- * Interface for working with IShape.
+ * A drawn shape: a text box, a callout, a rectangle, a connector.
  *
  * @remarks
+ * A shape is the content of an {@link IMovable} — `movable.getContent<IShape>()` for a movable
+ * whose content type is `'shape'`. The movable carries the position; the shape carries what is
+ * drawn there and what is written on it. A group of shapes is an {@link IGroup}, whose members are
+ * movables of their own.
  *
- * A shape does not position information
- * **PLACEHOLDER**
+ * Reading, and adjust values: a shape is JSON ({@link IShape.JSON}) that a file reads into and
+ * writes from; the editing API beyond `setAdjustments` is still to come.
  */
-export interface IShape extends IModel {
+export interface IShape extends IModel, IMovable.IContent {
     toJSON(toResourceId?: (resource: IResource) => number | null): IShape.JSON | null;
     /**
      * Returns the name of the shape.
      */
-    getName(): string;
+    getName(): string | null;
     /**
-     * Returns the description of the shape.
+     * The image a resource id in this shape's JSON names: an image fill's `resId`, as {@link toJSON}
+     * with no scope names it. `null` when the shape holds no such resource.
      */
-    getDescription(): string;
+    getResource(resourceId: number): IResource | null;
+    /**
+     * Deletes the shape, and with it the movable that places it.
+     */
+    delete(options?: ITransaction.OperationOptions): void;
+    /**
+     * Returns the kind of shape this is: its preset geometry.
+     *
+     * @remarks
+     * A DrawingML preset id ({@link IGeometry.Preset}) — `rect`, `borderCallout2`, `curvedConnector3` —
+     * or `'custom'` for a shape drawn from its own path. A file may name a preset this SDK does not
+     * know; it is returned as the file states it.
+     *
+     * The preset says what a shape is for where its name does not: a callout annotates something,
+     * a connector links two shapes, and a rectangle with no text is usually a box drawn around the
+     * cells under it.
+     */
+    getShapeType(): string;
+    /**
+     * Changes the kind of shape this is, as Excel's Change Shape does: its text, fill, outline, size
+     * and placement stay; its adjust values go back to the new preset's defaults.
+     *
+     * A line or connector takes only a line or connector preset, and any other shape only another
+     * kind of preset; `custom` is not a preset.
+     *
+     * @param shapeType A DrawingML preset id ({@link IGeometry.Preset}).
+     * @throws ExpectedError for a preset the shape cannot take.
+     *
+     * @example
+     * ```ts
+     * shape.setShapeType(IGeometry.Preset.RoundRect);
+     * ```
+     */
+    setShapeType(shapeType: IGeometry.Preset | string, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns the text written on the shape.
+     *
+     * @remarks
+     * Text on a shape is a note from the workbook's author to its reader, so it is worth reading
+     * before the cells it sits beside.
+     *
+     * @returns `null` when the shape has no text body at all, as a connector does not. A shape that
+     * can hold text but has none answers with a frame whose text is `''`.
+     *
+     * @example
+     * ```ts
+     * for (const movable of sheet.getMovables().getItems({ type: 'shape' })) {
+     *   const text = movable.getContent<IShape>().getTextFrame()?.getText();
+     *   if (text) console.log(movable.getRange().toString(), text);
+     * }
+     * ```
+     */
+    getTextFrame(): ITextFrame.IText | null;
+    /**
+     * What the shape draws with: its fill and its line, resolved from what it states over its
+     * theme style. The same object answers for the life of the shape.
+     *
+     * @example
+     * ```ts
+     * shape.getStyle().setFill('#ffd966');
+     * shape.getStyle().getStroke().setWidth(2.25);
+     * ```
+     */
+    getStyle(): IShapeStyle;
+    /**
+     * Returns the adjust values set on this shape, by name.
+     *
+     * @remarks
+     * A preset's handles move its adjust values — how rounded a `roundRect` is, where a callout
+     * points. Only values that differ from the preset's defaults are stored.
+     *
+     * The values are the geometry definition's own numbers (a ratio in 100,000ths, an angle in
+     * 60,000ths of a degree), opaque to a caller: a handle drag produces them through
+     * {@link IGeometry.adjustmentsFromHandle}, and a file reads and writes them as they are.
+     */
+    getAdjustments(): Readonly<Record<string, number>>;
+    /**
+     * Sets the adjust values, replacing any already set.
+     *
+     * @param adjustments Values by name, as {@link IGeometry.adjustmentsFromHandle} returns them;
+     * `null` restores the preset's defaults. Names the preset does not declare are kept but have no
+     * effect.
+     */
+    setAdjustments(adjustments: Record<string, number> | null, options?: ITransaction.OperationOptions): this;
+    /**
+     * Evaluates the shape's geometry at a size.
+     *
+     * @remarks
+     * What evaluates a shape loads on first use, and only what that shape needs, so this is
+     * asynchronous; a workbook with no shapes loads none of it. Everything on the geometry it
+     * returns is synchronous, including evaluating it again at another size or with other adjust
+     * values. Paths, handles and sites are in sheet pixels, in the shape's own frame (its top-left
+     * is 0,0), which is how the movable layer draws them.
+     *
+     * An open path takes the line ends the shape's line declares (its own over its theme style's):
+     * its stroke is trimmed under them, and they are visited as {@link IGeometry.PathLayer.Marker}
+     * paths.
+     *
+     * @param width Width in pixels. @defaultValue the movable's bounds.
+     * @param height Height in pixels. @defaultValue the movable's bounds.
+     * @param options What to evaluate in place of the shape's own preset or adjust values, as a
+     * gesture previews them; the shape is not changed.
+     * @returns `null` for a shape whose preset is unknown, or a shape with no size. A custom
+     * geometry evaluates like a preset, from its own definition.
+     */
+    getGeometry(width?: number, height?: number, options?: IShape.GeometryOptions): Promise<IGeometry | null>;
+    /**
+     * Whether the shape is a connector: a line whose ends can be glued to other movables'
+     * connection sites.
+     */
+    isConnector(): boolean;
+    /**
+     * A connector's ends: what each is glued to, and gluing it.
+     *
+     * @returns `null` for a shape that is not a connector.
+     *
+     * @example
+     * ```ts
+     * const line = connector.getContent<IShape>().getConnectorFormat()!;
+     * line.startConnect(box, 3); // the box's right site
+     * line.getStartConnectedMovable() === box; // true, and the line follows the box from now on
+     * ```
+     */
+    getConnectorFormat(): IShape.IConnectorFormat | null;
+    /**
+     * How many connection sites the shape's geometry has: the places a connector's end can be
+     * glued, numbered from 0.
+     *
+     * @remarks
+     * Asynchronous as {@link getGeometry} is, which answers it. A shape with no geometry has none.
+     */
+    getConnectionSiteCount(): Promise<number>;
+    /**
+     * {@inheritDoc IMovable.IContent.getConnections}
+     *
+     * @remarks
+     * A shape's sites are its geometry's (`cxnLst`), not the four edges: a triangle offers three, a
+     * connector none. Answered from the geometry the shape last evaluated, so synchronous; `null`
+     * before the first evaluation, which this starts ({@link getGeometry} waits for one).
+     * {@link IMovable.getConnectionSites} answers them placed on the sheet.
+     */
+    getConnections(width: number, height: number, options?: IMovable.ConnectionsOptions): readonly IMovable.Connection[] | null;
+    /** For runtime type checking. */
+    readonly isIShape: true;
 }
 /**
  * {@inheritDoc IShape}
@@ -32,6 +184,21 @@ export interface IShape extends IModel {
  * {@link IShape}
  */
 export declare namespace IShape {
+    /**
+     * What kind of drawing a shape's JSON describes.
+     *
+     * @remarks
+     * Every kind is an `IShape` whose {@link IMovable.IContent.getType | content type} is `'shape'`;
+     * this is the one place the distinction survives a round trip. A JSON that states none is a
+     * {@link IShape.Type.Shape | shape}.
+     */
+    const Type: {
+        /** A shape drawn from a preset or custom geometry, with or without text. */
+        readonly Shape: "shape";
+        /** A connector: a line that may be glued to other shapes' connection sites. */
+        readonly Connector: "connector";
+    };
+    type Type = typeof Type[keyof typeof Type];
     /**
      * A set of values that can be set on a IShape.
      *
@@ -40,15 +207,20 @@ export declare namespace IShape {
      */
     interface Properties {
         /**
-         * The unique name of the table
+         * The name of the shape.
          */
         name?: string;
         /**
-         * The preset Geometry for the shape. This could also be custom.
+         * The geometry: a DrawingML preset name (`'rect'`, `'roundRect'`, `'wedgeEllipseCallout'`…)
+         * or a custom definition in the same form as a preset.
          *
          * @defaultValue 'rect'
          */
-        geometry?: PresetGeometry | GeometryProperties;
+        geometry?: string | IGeometry.Def;
+        /**
+         * Adjust values that differ from the preset's defaults, by name (`adj`, `adj1`…).
+         */
+        adjustments?: Record<string, number>;
         /**
          * The fill.
          */
@@ -60,220 +232,195 @@ export declare namespace IShape {
         /**
          * A hyperlink for the entire shape.
          */
-        hyperlink?: string | IHyperlink.JSON;
+        hyperlink?: IHyperlink.JSON;
     }
     /**
      * A JSON representation useful for persistence.
      */
-    interface JSON extends Omit<Properties, 'fill' | 'stroke' | 'geometry'> {
-        fill?: IFill.SolidJSON | IFill.GradientJSON | IFill.PatternJSON | IFill.NoneJSON;
-        stroke?: IStroke.JSON;
-        geometry?: string | GeometryJSON;
-        /** Which drawing element this was read from ("sp" | "cxnSp" | "grpSp") — `getType()` always
-         * reports "shape" regardless, so this is the only place the distinction survives a round trip. */
-        type?: string;
-        /** Opaque source XML fragment, captured verbatim from the source file and replayed as-is on
-         * save, for whatever this shape doesn't (yet) model structurally. */
-        xml?: string;
-        /** Original `cNvPr` id from the captured source fragment, if any; used to avoid id collisions
-         * with freshly-generated ids on write. */
-        sourceId?: number;
-    }
-    interface GeometryProperties {
-        geometry?: PresetGeometry;
-        ah: (PolarAdjustmentHandle | XYAdjustmentHandle)[];
-        av?: IShape.AdjustmentGuide[];
-        connections?: IShape.ConnectionSite[];
-        guides?: IShape.AdjustmentGuide[];
-        paths?: IShape.Path[] | string[] | string;
+    interface JSON extends Omit<Properties, 'fill' | 'stroke' | 'geometry' | 'hyperlink'> {
         /**
-         * Specifies the rectangular bounding box for text within the shape.
-         * @defaultValue `null` - The bounds of the shape,
+         * What kind of drawing this is. Absent for a {@link Type.Shape | shape}; a connector states its.
          */
-        textBounds?: Rectangle;
-    }
-    interface Path {
-        paths: string[];
+        type?: Type;
         /**
-         * Specifies that the use of 3D extrusions are possible on this path. This allows the generating application to know whether
-         * 3D extrusion can be applied in any form.
-         *
-         * @defaultValue `false`
+         * The fill. A {@link IFill.GroupJSON | group fill} takes the fill of the group the shape is a
+         * member of (the nearest one that states a fill), and the shape's theme style outside a group.
          */
-        extrusionOk?: boolean;
+        fill?: IFill.SolidJSON | IFill.GradientJSON | IFill.PatternJSON | IFill.ImageJSON | IFill.NoneJSON | IFill.GroupJSON;
+        stroke?: IStroke.JSON;
         /**
-         * Specifies how the corresponding path should be filled.
-         *
-         * @defaultValue `PathFill.Normal`
+         * The shape's effects (`spPr/effectLst`). An empty list is an explicit none: the element
+         * present and empty, which turns off the effects the shape's theme style would give it.
          */
-        pathFill?: PathFill;
+        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?: ExtLstJSON;
+        geometry?: string | IGeometry.Def;
+        /** The hyperlink on the whole shape (`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 bound to the shape (`sp/@macro`), as the file states it. */
+        macro?: string;
+        /** The cell a text box's text is linked to (`sp/@textlink`), as the file states it. */
+        textLink?: string;
+        /** The text cannot be edited while the sheet is protected (`sp/@fLocksText`). */
+        locksText?: boolean;
+        /** `sp/@fPublished`. */
+        published?: boolean;
+        /** The shape was inserted as a text box (`cNvSpPr/@txBox`). */
+        textBox?: boolean;
         /**
-         * Specifies the height, or maximum y coordinate that should be used for within the path coordinate system. This value determines
-         * the vertical placement of all points within the corresponding path as they will all be calculated using this height attribute
-         * as the max y coordinate.
-         *
-         * @defaultValue `null`
+         * Edit locks (`spLocks`/`cxnSpLocks`) by the file's own names: `noGrp`, `noSelect`, `noRot`,
+         * `noChangeAspect`, `noMove`, `noResize`, `noEditPoints`, `noAdjustHandles`,
+         * `noChangeArrowheads`, `noChangeShapeType`, `noTextEdit`.
          */
-        h?: number;
+        locks?: Record<string, boolean>;
+        /** A connector's glued ends. */
+        connectorEnds?: ConnectorEndsJSON;
+        /** The text written on the shape, by paragraph. Absent for a shape with no text body. */
+        text?: ITextFrame.JSON;
         /**
-         * Specifies if the corresponding path should have a path stroke shown. This is a boolean value that will effect on the outline of the path.
-         *
-         * @defaultValue `true`
+         * The theme style the shape draws with wherever it states no fill, stroke or text color of its
+         * own: the file's `style` element, which refers into the theme's format scheme by position.
+         * A reference not stated is Excel's for a new shape (a connector's differ: the first line, no
+         * fill); `null`, the shape has no style and draws only what it states itself.
          */
-        stroke?: boolean;
+        style?: ITheme.StyleRefsJSON | null;
         /**
-         * Specifies the width, or maximum x coordinate that should be used for within the path coordinate system. This value determines
-         * the horizontal placement of all points within the corresponding path as they will all be calculated using this width attribute
-         * as the max x coordinate.
-         *
-         * @defaultValue `null`
+         * The id the file gave the shape (`cNvPr/@id`), which is what a connector's
+         * {@link connectorEnds} name their targets by. A file writes the shape with this id again
+         * (made unique when two shapes share one, as a copy does); a shape without one takes the next.
          */
-        w?: number;
+        sourceId?: number;
     }
     /**
-     * Specifies the manner in which a path should be filled. The lightening and darkening of a path allow for certain parts of the shape
-     * to be colored lighter of darker depending on user preference.
-     */
-    const PathFill: {
-        readonly Darken: "darken";
-        readonly DarkenLess: "darkenLess";
-        readonly Lighten: "lighten";
-        readonly LightenLess: "lightenLess";
-        readonly None: "none";
-        readonly Normal: "normal";
-    };
-    type PathFill = typeof PathFill[keyof typeof PathFill];
-    /**
-     * Specifies the presence of a shape guide that will be used to govern the geometry of the specified shape.
+     * The `extLst` fragments of a shape's elements: opaque DrawingML kept as the file states it and
+     * written back as it was, the one markup that stays once the shape is otherwise JSON. A line's
+     * is on its stroke, a text body's on its body.
      */
-    interface AdjustmentGuide {
-        /**
-         * Specifies the name that will be used to reference to this guide. This name may be used just as a variable
-         * would within an equation. That is this name may be substituted for literal values within other guides or
-         * the specification of the shape path.
-         */
-        name: string;
-        /**
-         * Specifies the formula that will be used to calculate the value for a guide. Each formula has a certain
-         * number of arguments and a specific set of operations to perform on these arguments in order to generate a
-         * value for a guide. There are a total of 17 different formulas available. These are shown below with the usage
-         * for each defined
-         */
-        fmla: string;
+    interface ExtLstJSON {
+        /** `cNvPr/extLst`: the creation id and whatever else extends the non-visual properties. */
+        nonVisual?: string;
+        /** `spPr/extLst`. */
+        properties?: string;
     }
     /**
-     * These adjust handles will specify points within the geometric shape that can be used to perform certain
-     * transform operations on the shape.
+     * One glued end of a connector: the movable it is attached to, by the id the file gives that
+     * movable (its content's `sourceId` here), and which of that movable's connection sites.
      */
-    interface AdjustmentHandle {
-        /**
-         * The point of the adjustment
-         */
-        pos: Point;
+    interface ConnectorEndJSON {
+        id: number;
+        index: number;
     }
-    interface PolarAdjustmentHandle extends AdjustmentHandle {
-        type: 'polar';
-        /**
-         * Specifies the name of the guide that will be updated with the adjustment angle from this adjust handle.
-         */
-        gdRefAng: string;
-        /**
-         * Specifies the name of the guide that will be updated with the adjustment radius from this adjust handle.
-         */
-        gdRefR: string;
-        /**
-         * Specifies the maximum angle position that is allowed for this adjustment handle. If this attribute is omitted,
-         * then it will be assumed that this adjust handle cannot move angularly.
-         */
-        maxAng: number;
-        /**
-         * Specifies the maximum radial position that is allowed for this adjustment handle. If this attribute is omitted,
-         * then it will be assumed that this adjust handle cannot move radially.
-         */
-        maxR: number;
-        /**
-         * Specifies the minimum angle position that is allowed for this adjustment handle. If this attribute is omitted,
-         * then it will be assumed that this adjust handle cannot move angularly.
-         */
-        minAng: number;
-        /**
-         * Specifies the minimum radial position that is allowed for this adjustment handle. If this attribute is omitted,
-         * then it will be assumed that this adjust handle cannot move radially.
-         */
-        minR: number;
+    /** A connector's glued ends: the start of its path, and the end. */
+    interface ConnectorEndsJSON {
+        start?: ConnectorEndJSON;
+        end?: ConnectorEndJSON;
     }
-    interface XYAdjustmentHandle extends AdjustmentHandle {
-        type: 'xy';
-        /**
-         * Specifies the name of the guide that will be updated with the adjustment x position from this adjust handle.
-         */
-        gdRefX: string;
+    /** What {@link IShape.getGeometry} evaluates in place of the shape's own. */
+    interface GeometryOptions {
+        /** A preset name, as {@link IShape.getShapeType} answers. */
+        shapeType?: string;
+        /** Adjust values, as {@link IShape.getAdjustments} answers; `null` for the preset's defaults. */
+        adjustments?: Readonly<Record<string, number>> | null;
+    }
+    /** Where a glued connector goes, and the route it takes there. */
+    interface ConnectorRoute {
+        placement: IMovable.Placement;
         /**
-         * Specifies the name of the guide that will be updated with the adjustment y position from this adjust handle.
+         * The preset the connector takes when it is routed (an elbow or a curve); `null` when it
+         * keeps its own.
          */
-        gdRefY: string;
+        shapeType: string | null;
+        /** The adjust values that go with {@link shapeType}; `null` with it, or for an L. */
+        adjustments: Readonly<Record<string, number>> | null;
+    }
+    /** The kind of line a connector draws between its ends. */
+    const ConnectorType: {
+        /** One segment. */
+        readonly Straight: "straight";
+        /** Right-angled bends. */
+        readonly Elbow: "elbow";
+        /** A curve. */
+        readonly Curved: "curved";
+    };
+    type ConnectorType = typeof ConnectorType[keyof typeof ConnectorType];
+    /**
+     * A connector's two ends, each glued to a connection site of another shape or free.
+     *
+     * @remarks
+     * Gluing an end places the connector so the end lies on the site, and the connector follows the
+     * shape from then on: a move, turn, mirror or resize of the shape moves the connector in the
+     * same undoable step. A shape whose geometry has not evaluated yet is followed once it has.
+     * Sites are numbered from 0, as {@link IGeometry.forEachConnection} visits them.
+     */
+    interface IConnectorFormat {
+        /** The kind of line the connector draws. */
+        getConnectorType(): ConnectorType;
+        /** Whether the start of the connector is glued to a movable. */
+        isStartConnected(): boolean;
+        /** The movable the start is glued to; `null` when it is free or the movable is gone. */
+        getStartConnectedMovable(): IMovable | null;
+        /** The site the start is glued to; `null` when it is free. */
+        getStartConnectionSite(): number | null;
         /**
-         * Specifies the maximum horizontal position that is allowed for this adjustment handle. If this attribute is omitted,
-         * then it will be assumed that this adjust handle cannot move in the x direction.
+         * Glues the start of the connector to a connection site of a movable: a shape, a picture, a
+         * chart or a control ({@link IMovable.getConnectionSites}).
+         *
+         * @param movable The movable to glue to.
+         * @param site The site, numbered from 0.
+         * @throws If the movable is not on the same sheet, or is the connector itself.
          */
-        maxX: number;
+        startConnect(movable: IMovable, site: number, options?: ITransaction.OperationOptions): void;
+        /** Frees the start of the connector, which stays where it is. */
+        startDisconnect(options?: ITransaction.OperationOptions): void;
+        /** Whether the end of the connector is glued to a movable. */
+        isEndConnected(): boolean;
+        /** The movable the end is glued to; `null` when it is free or the movable is gone. */
+        getEndConnectedMovable(): IMovable | null;
+        /** The site the end is glued to; `null` when it is free. */
+        getEndConnectionSite(): number | null;
+        /** Glues the end of the connector to a connection site of a movable, as {@link startConnect} does the start. */
+        endConnect(movable: IMovable, site: number, options?: ITransaction.OperationOptions): void;
+        /** Frees the end of the connector, which stays where it is. */
+        endDisconnect(options?: ITransaction.OperationOptions): void;
         /**
-         * Specifies the maximum vertical position that is allowed for this adjustment handle. If this attribute is omitted,
-         * then it will be assumed that this adjust handle cannot move in the y direction.
+         * Where the connector's ends are on the sheet: its path runs from its frame's top-left to its
+         * bottom-right, and the frame's flips and turn put those corners where they are.
+         *
+         * @param placement A placement to answer for; the connector's own when omitted.
+         * @returns `null` for a connector with no placement.
          */
-        maxY: number;
+        getEndPoints(placement?: IMovable.Placement): {
+            start: Point;
+            end: Point;
+        } | null;
         /**
-         * Specifies the minimum horizontal position that is allowed for this adjustment handle. If this attribute is omitted,
-         * then it will be assumed that this adjust handle cannot move in the x direction.
+         * The placement that runs the connector from `start` to `end`, keeping its turn: the frame is
+         * the box of the two points in its own axes, mirrored on each axis the end lies before the
+         * start on. Nothing is written.
          */
-        minX: number;
+        placeEnds(start: Point, end: Point): IMovable.Placement;
         /**
-         * Specifies the minimum vertical position that is allowed for this adjustment handle. If this attribute is omitted,
-         * then it will be assumed that this adjust handle cannot move in the y direction.
-         */
-        minY: number;
-    }
-    /**
-     * A connection site allows a `ConnectionShape` to be attached to this shape. This connection will be maintained
-     * when the shape is repositioned. It should be noted that this connection is placed within the shape
-     * bounding box using the transform coordinate system which is also called the shape coordinate system,
-     * as it encompasses the entire shape.
-     */
-    interface ConnectionSite {
-        /**
-         * Specifies the incoming connector angle. This angle is the angle around the connection site that an
-         * incoming connector will try to be routed to. This allows connectors to know where the shape is in
-         * relation to the connection site and route connectors so as to avoid any overlap with the shape.
-         */
-        angle: string;
-        /**
-         * Specifies a position coordinate within the shape bounding box. It should be noted that this coordinate
-         * is placed within the shape bounding box using the transform coordinate system which is also called the
-         * shape coordinate system, as it encompasses the entire shape.
+         * Where the connector goes with each glued end on its shape's site, and the route it takes:
+         * what the sheet writes when a movable it is glued to changes, for a drawing layer to preview.
+         *
+         * @remarks
+         * An elbow or curve is routed between its ends as Excel routes it: the preset (from an L to five
+         * legs) and its adjust values follow where the shapes are. Glued at one end, the connector moves
+         * whole with a shape that only moves; any other change keeps the free end where it is.
+         *
+         * @param placements Where each movable is, as a gesture previews it; the model's when omitted.
+         * @returns `null` when no end can be placed: none is glued, or its target has not answered its sites.
          */
-        pos: Point;
-    }
-    interface GeometryJSON extends GeometryProperties {
-    }
-    interface Events extends IModel.Events {
+        getGluedRoute(placements?: (movable: IMovable) => IMovable.PlacementPreview | null): ConnectorRoute | null;
     }
-    interface IListeners extends IListener.Callbacks<IShape, IShape.Events> {
-    }
-    interface IConnection {
-    }
-    interface Connection extends IShape.JSON {
-        cxnSp?: any;
-    }
-    /**
-     * @see {@link https://c-rex.net/samples/ooxml/e1/Part4/OOXML_P4_DOCX_ST_ShapeType_topic_ID0EBTFOB.html#topic_ID0EBTFOB}
-     */
-    const PresetGeometry: {
-        readonly Line: "line";
-        readonly LineInv: "lineInv";
-        readonly triangle: "triangle";
-        readonly rtTriangle: "rtTriangle";
-        readonly Rect: "rect";
-    };
-    type PresetGeometry = typeof PresetGeometry[keyof typeof PresetGeometry];
 }
 //# sourceMappingURL=IShape.d.ts.map