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

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

@@ -0,0 +1,109 @@
+import { ITransaction } from '../transaction';
+import { IFill, IFillable, IStroke } from '../fill';
+/**
+ * What a shape draws with: its fill and its line.
+ *
+ * @remarks
+ * A shape's style reads resolved: what the shape states itself, over what its theme style gives
+ * it (the references into the theme's format scheme that a file's `style` element names), over
+ * SheetXL's defaults for a shape that states neither. A member of a group that takes its group's
+ * fill reads the nearest enclosing group's.
+ *
+ * Writes state values on the shape: `setFill('red')` makes the fill the shape's own, and
+ * `setFill(null)` hands it back to the theme style. {@link toJSON} answers only what the shape
+ * states, never the resolved values; {@link isThemed} says whether it states anything at all.
+ * A partial fill update merges into the resolved fill, so a color on a themed shape gives a solid
+ * fill of that color; `setFillNone()` states that the shape has no fill, which is not the same as
+ * leaving it to the theme style.
+ *
+ * Every write is one undoable step, transactional like the rest of the shape.
+ *
+ * @example
+ * ```ts
+ * const style = movable.getContent<IShape>().getStyle();
+ * style.setFill('#ffd966');                    // a solid fill
+ * style.getStroke().setWidth(2.25);            // the theme's line color, wider
+ * style.update({ stroke: { fill: 'none' } });  // no line
+ * style.clear();                               // back to the theme style
+ * ```
+ */
+export interface IShapeStyle extends IFillable<IShapeStyle> {
+    /**
+     * The line, resolved. A shape that states none draws its theme style's; a line the shape
+     * states without a color takes the theme style's color, as in Excel.
+     */
+    getStroke(): IStroke;
+    /**
+     * Sets the line: a color, a stroke, or stroke properties; `null` for the theme style's.
+     */
+    setStroke(stroke: IStroke.Update, options?: ITransaction.OperationOptions): IShapeStyle;
+    /**
+     * Removes the line and returns it: the shape states that it has none.
+     */
+    setStrokeNone(options?: ITransaction.OperationOptions): IStroke;
+    /**
+     * Sets fill and line at once, as one undoable step.
+     */
+    update(update: IShapeStyle.Update, options?: ITransaction.OperationOptions): IShapeStyle;
+    /**
+     * Removes everything the shape states, leaving it to its theme style.
+     */
+    clear(options?: ITransaction.OperationOptions): IShapeStyle;
+    /**
+     * Whether the shape states nothing of its own: it draws with its theme style alone.
+     */
+    isThemed(): boolean;
+    /**
+     * What the shape states itself, never the resolved values; `null` when it states nothing.
+     */
+    toJSON(): IShapeStyle.JSON | null;
+    /**
+     * For type checking.
+     */
+    readonly isIShapeStyle: true;
+}
+/**
+ * {@inheritDoc IShapeStyle}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IShapeStyle}
+ */
+export declare namespace IShapeStyle {
+    /**
+     * The properties a shape states.
+     */
+    interface Properties {
+        /**
+         * The fill. A {@link IFill.GroupProperties | group fill} takes the fill of the group the
+         * shape is a member of.
+         */
+        fill?: IFill.SolidProperties | IFill.GradientProperties | IFill.PatternProperties | IFill.ImageProperties | IFill.NoneProperties | IFill.GroupProperties;
+        /**
+         * The line.
+         */
+        stroke?: IStroke.Properties;
+    }
+    /**
+     * Modifiers describe a partial list of properties that can be set with values or shorthand
+     * strings: a color for either, and `null` to hand one back to the theme style.
+     */
+    interface Modifiers {
+        /** {@inheritDoc IShapeStyle.setFill} */
+        fill?: IFill.Update;
+        /** {@inheritDoc IShapeStyle.setStroke} */
+        stroke?: IStroke.Update;
+    }
+    /**
+     * Options for updating a shape style: a style (what it states), modifiers, or `null` to clear.
+     */
+    type Update = IShapeStyle | Modifiers | null;
+    /**
+     * A JSON representation useful for persistence: what the shape states.
+     */
+    interface JSON {
+        fill?: IFill.JSON;
+        stroke?: IStroke.JSON;
+    }
+}
+//# sourceMappingURL=IShapeStyle.d.ts.map

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

@@ -0,0 +1,85 @@
+import { ITransaction } from '../transaction';
+import { IFill, IStroke } from '../fill';
+import { IFontStyle } from '../font';
+import { IShapeStyle } from './IShapeStyle';
+/**
+ * What a text box draws with: its fill, its line and the font of its text.
+ *
+ * @remarks
+ * A chart's title, legend, axes, data labels and data table are text boxes: one
+ * `getStyle()` answers how each looks, as `range.getStyle()` does for a cell. A part with no text,
+ * such as a series or the plot area, answers an {@link IShapeStyle}; `isITextBoxStyle` tells them
+ * apart.
+ *
+ * The font reads what is drawn, stated or not; what the box does not state it takes from the text
+ * around it. {@link toJSON} answers only what the box states.
+ *
+ * @example
+ * ```ts
+ * const style = chart.getTitle().getStyle();
+ * style.getFont().setBold(true);
+ * style.update({ fill: 'white', font: { size: 18, color: 'accent1' } });
+ * style.clear();                       // fill, line and font back to the chart's
+ * ```
+ */
+export interface ITextBoxStyle extends IShapeStyle {
+    /**
+     * Returns the font of the box's text.
+     */
+    getFont(): IFontStyle;
+    /** {@inheritDoc IFillable.setFill} */
+    setFill(fill: IFill.Update, options?: ITransaction.OperationOptions): ITextBoxStyle;
+    /** {@inheritDoc IShapeStyle.setStroke} */
+    setStroke(stroke: IStroke.Update, options?: ITransaction.OperationOptions): ITextBoxStyle;
+    /**
+     * Sets fill, line and font at once, as one undoable step.
+     */
+    update(update: ITextBoxStyle.Update, options?: ITransaction.OperationOptions): ITextBoxStyle;
+    /**
+     * Removes everything the box states, its font too.
+     */
+    clear(options?: ITransaction.OperationOptions): ITextBoxStyle;
+    /**
+     * What the box states itself, never the resolved values; `null` when it states nothing.
+     */
+    toJSON(): ITextBoxStyle.JSON | null;
+    /**
+     * For type checking.
+     */
+    readonly isITextBoxStyle: true;
+}
+/**
+ * {@inheritDoc ITextBoxStyle}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ITextBoxStyle}
+ */
+export declare namespace ITextBoxStyle {
+    /**
+     * The properties a text box states.
+     */
+    interface Properties extends IShapeStyle.Properties {
+        /** The font of the text. */
+        font?: IFontStyle.Properties;
+    }
+    /**
+     * A partial list of properties: {@link IShapeStyle.Modifiers} and the font. `null` for the font
+     * hands it back to the text around the box.
+     */
+    interface Modifiers extends IShapeStyle.Modifiers {
+        /** {@inheritDoc ITextBoxStyle.getFont} */
+        font?: IFontStyle.Update | null;
+    }
+    /**
+     * Options for updating a text box style: a style (what it states), modifiers, or `null` to clear.
+     */
+    type Update = ITextBoxStyle | IShapeStyle | Modifiers | null;
+    /**
+     * A JSON representation useful for persistence: what the box states.
+     */
+    interface JSON extends IShapeStyle.JSON {
+        font?: IFontStyle.JSON;
+    }
+}
+//# sourceMappingURL=ITextBoxStyle.d.ts.map

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

@@ -1,29 +1,113 @@
-import { IResource, IResourceCollection } from '../resource';
-import { IModel, AbstractModel } from '../model';
+import { ITransaction } from '../transaction';
+import { IResource } from '../resource';
+import { ITextFrame } from '../text';
+import { IMovable } from '../movable/IMovable';
+import { AbstractMovableContent } from '../movable/AbstractMovableContent';
+import { IGeometry } from './IGeometry';
 import { IShape } from './IShape';
-interface State extends AbstractModel.State {
+import { IShapeStyle } from './IShapeStyle';
+/** An end of a connector, as its JSON names them. */
+type ConnectorEnd = keyof IShape.ConnectorEndsJSON;
+interface State extends AbstractMovableContent.State {
     data?: any;
 }
 /**
  * Implementation for {@link IShape}.
  */
-export declare class Shape extends AbstractModel<State, IShape.JSON> implements IShape {
+export declare class Shape extends AbstractMovableContent<State, IShape.JSON> implements IShape {
+    /** The state the text frame was read from; a new state object is a new read. */
+    private _textSource;
+    private _textFrame;
+    /**
+     * The image the JSON names — an image fill's — by the resource id it names it with. Held the way
+     * a picture holds its one resource: the id is only good inside the persist scope that made the
+     * JSON, the resource is good for as long as the shape is.
+     */
+    private _resources;
+    private _getStyles;
+    private _connectorFormat;
+    private _style;
+    /** The last evaluation {@link _getDrawnRect} and {@link getConnections} answer from, and the one in flight. */
+    private _drawn;
+    private _drawnPending;
     constructor(options: Shape.ConstructorOptions);
+    protected _processAfterStateChange(state: State, commit: ITransaction.ICommit): void;
+    /** {@inheritDoc IShape.getResource} */
+    getResource(resourceId: number): IResource | null;
     /** {@inheritDoc IModel.getType} */
     getType(): string;
-    /** {@inheritDoc IShape.getName} */
-    getName(): string;
-    /** {@inheritDoc Movable.Content.getDescription} */
-    getDescription(): string;
+    /** {@inheritDoc IShape.getShapeType} */
+    getShapeType(): string;
+    /** {@inheritDoc IShape.setShapeType} */
+    setShapeType(shapeType: IGeometry.Preset | string, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IShape.getTextFrame} */
+    getTextFrame(): ITextFrame.IText | null;
+    /** {@inheritDoc IShape.getStyle} */
+    getStyle(): IShapeStyle;
+    /** Writes what the shape states of its fill and line: a key `undefined` is removed. */
+    private _writeStyle;
+    /** {@inheritDoc IShape.getAdjustments} */
+    getAdjustments(): Readonly<Record<string, number>>;
+    /** {@inheritDoc IShape.setAdjustments} */
+    setAdjustments(adjustments: Record<string, number> | null, options?: ITransaction.OperationOptions): this;
+    /**
+     * Takes the preset and adjust values a connector's route gives it, as part of the open operation
+     * that moved what it is glued to.
+     * @internal
+     */
+    _setRoute(geometry: string, adjustments: Record<string, number> | null): void;
+    /** {@inheritDoc IShape.isConnector} */
+    isConnector(): boolean;
+    /** {@inheritDoc IShape.getConnectorFormat} */
+    getConnectorFormat(): IShape.IConnectorFormat | null;
+    /** {@inheritDoc IShape.getConnectionSiteCount} */
+    getConnectionSiteCount(): Promise<number>;
+    /** What an end is glued to, as the JSON states it; `null` when it is free. @internal */
+    _connectedEnd(end: ConnectorEnd): IShape.ConnectorEndJSON | null;
+    /** The movable of the shape an end is glued to; `null` when it is free or not on the sheet. @internal */
+    _connectedMovable(end: ConnectorEnd): IMovable | null;
+    /** Glues an end to a site of `target`, as part of one operation. @internal */
+    _connect(end: ConnectorEnd, target: IMovable, site: number, options?: ITransaction.OperationOptions): void;
+    /** Frees an end; the connector stays where it is. @internal */
+    _disconnect(end: ConnectorEnd, options?: ITransaction.OperationOptions): void;
+    private _writeEnd;
+    /** The movable that places this shape is told its placement changed, as part of the open operation. */
+    private _notifyPlacementChange;
+    /** Runs `callback` folded into the current commit. */
+    private _amend;
+    /** {@inheritDoc IShape.getGeometry} */
+    getGeometry(width?: number, height?: number, options?: IShape.GeometryOptions): Promise<IGeometry | null>;
+    /**
+     * What the shape paints, in pixels in its `width` by `height` frame: its geometry's paths grown
+     * by its line. Answered from the last evaluation, scaled to the size asked; `null` before the
+     * first. A stale answer starts a new evaluation and `onReady` is called when it lands.
+     * @internal
+     */
+    _getDrawnRect(width: number, height: number, onReady: () => void): IGeometry.Rect | null;
+    /** {@inheritDoc IShape.getConnections} */
+    getConnections(width: number, height: number, options?: IMovable.ConnectionsOptions): readonly IGeometry.IConnection[] | null;
+    /**
+     * The last evaluation, whatever its size, starting a new one at this size when it is for other
+     * data or another size; `onReady` is called when that lands. `null` before any has.
+     */
+    private _evaluated;
+    /** The workbook theme the shape's style references resolve against; `null` with none to ask. */
+    private _theme;
     /** {@inheritDoc Movable.Content.toJSON} */
-    toJSON(_toResourceId?: (resource: IResource) => number | null): IShape.JSON | null;
-    /** {@inheritDoc Movable.Content.getTypeDescription} */
+    toJSON(toResourceId?: (resource: IResource) => number | null): IShape.JSON | null;
+    /** {@inheritDoc IMovable.IContent.getTypeDescription} */
     getTypeDescription(): string;
+    /** {@inheritDoc IMovable.IContent.acceptRotation} */
+    acceptRotation(degrees: number): number;
+    /** {@inheritDoc IMovable.IContent.acceptFlip} */
+    acceptFlip(flip: IMovable.Flip): IMovable.Flip;
+    /** {@inheritDoc IShape.isIShape} */
+    get isIShape(): true;
     get [Symbol.toStringTag](): string;
     toString(): string;
 }
 /**
- * Interfaces for creating `Chart` items.
+ * Interfaces for creating `Shape` items.
  *
  * @see
  * ### **Interface**
@@ -31,23 +115,25 @@ export declare class Shape extends AbstractModel<State, IShape.JSON> implements
  * {@link Shape}
  */
 export declare namespace Shape {
+    /** One evaluation of the shape's geometry: what was evaluated, at what size, and what it answered. */
+    interface Evaluated {
+        data: IShape.JSON;
+        width: number;
+        height: number;
+        /** The geometry evaluated; `null` for a preset that could not be evaluated. */
+        geometry: IGeometry | null;
+        /** What the shape paints; `null` for a preset that could not be evaluated. */
+        rect: IGeometry.Rect | null;
+        connections: readonly IGeometry.IConnection[];
+    }
     /**
      * Options for creating a shape.
      */
-    interface ConstructorOptions extends IModel.ConstructorOptions<IShape.JSON> {
+    interface ConstructorOptions extends AbstractMovableContent.ConstructorOptions<IShape.JSON> {
         /**
          * Returns an IResource from the resourceId or null if not found.
          */
         fromResourceId?: (resourceId: number) => IResource;
-        /**
-         * Useful for load/save/copying.
-         */
-        beginPersistResource: () => IResourceCollection.IPersistScope<IResource.JSON>;
-        /**
-         * Allow for the default lock aspect ratio to be overwritten.
-         */
-        defaultLockAspectRatio?: boolean;
-        getName(): string;
     }
 }
 export {};

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

@@ -0,0 +1,66 @@
+import { IFill, IStroke } from '../fill';
+import { ITheme } from '../theme';
+import { IMovable } from '../movable/IMovable';
+import { IText, ITextFrame } from '../text';
+import { IShape } from './IShape';
+/** The style references a shape takes for each one it does not state; a connector's and a text box's differ. */
+export declare function defaultStyleRefs(json: IShape.JSON | null | undefined): Readonly<ITheme.StyleRefsJSON>;
+/**
+ * A new object's JSON over what its theme gives a new object of its kind
+ * ({@link ITheme.getObjectDefaults}): a line or connector takes the line default, a text box the
+ * text box default, anything else the shape default. What the JSON states wins; a line and a text
+ * body are merged a level down, so an arrowhead the JSON states keeps the default's width and color.
+ *
+ * @remarks
+ * Call this when inserting, not when copying or loading: the object keeps what it took, and a later
+ * change to the theme's defaults does not reach it. A text box whose theme states no default takes
+ * Excel's built-in one.
+ */
+export declare function withThemeDefaults(json: IShape.JSON, theme: ITheme): IShape.JSON;
+/**
+ * `style` with every reference equal to its default left out: `undefined` when none is left,
+ * `null` (no style at all) kept.
+ */
+export declare function withoutDefaultStyleRefs(json: IShape.JSON): ITheme.StyleRefsJSON | null | undefined;
+/**
+ * SheetXL's defaults for what a shape's text does not state. A file format's writer states them in
+ * that format's terms, and its reader leaves out what equals them.
+ */
+export declare const TEXT_DEFAULTS: Readonly<{
+    /** Text is kept inside the shape ("Allow text to overflow shape" off). */
+    readonly verticalOverflow: "clip";
+    readonly horizontalOverflow: "clip";
+    /** The size of a run nothing gives one, in points. */
+    readonly size: 11;
+}>;
+/**
+ * The size a paragraph's runs inherit — its own default run, then the body's list style for its
+ * level — or `undefined` when nothing above the run states one, which is when
+ * {@link TEXT_DEFAULTS} applies.
+ */
+export declare function inheritedTextSize(text: ITextFrame.JSON, paragraph: IText.ParagraphPropertiesJSON): number | undefined;
+/**
+ * The fill a member that takes its group's fill draws with: the nearest enclosing group's that
+ * states one, through `IMovable.getParent`; `null` outside a group or with none stated.
+ */
+export declare function inheritedGroupFill(movable: IMovable | null | undefined): IFill.JSON | null;
+export interface ResolvedShapeStyle {
+    /** The fill, with the style's placeholder color substituted; `undefined` when nothing states one. */
+    fill: IFill.JSON | undefined;
+    /**
+     * The line: the shape's own over its style's, field by field, with the style's color when the
+     * shape states a line without one (an `<a:ln w="…">` alone), as in Excel. `undefined` when
+     * nothing states one.
+     */
+    stroke: IStroke.JSON | undefined;
+    /** The line width in points: stated, or Excel's implied width. */
+    strokeWidth: number;
+    /** The text color's serialized form: the style's, or by whether there is a fill to read on. */
+    fontColor: string;
+}
+/**
+ * Resolves a shape's fill, line and text color from its JSON and its workbook's theme. No style
+ * stated (`undefined`) takes SheetXL's defaults; a stated none (`null`) takes nothing.
+ */
+export declare function resolve(json: IShape.JSON | null | undefined, theme: ITheme.JSON | null, groupFill?: IFill.JSON | null): ResolvedShapeStyle;
+//# sourceMappingURL=ShapeStyleUtils.d.ts.map

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

@@ -0,0 +1,32 @@
+import { Point } from '@sheetxl/utils';
+import { IMovable } from '../movable/IMovable';
+/**
+ * A connector's frame: the map between a placed frame's own coordinates and the sheet, and the
+ * frame two ends decide. A connector's path runs from its frame's top-left to its bottom-right
+ * (`M l t ... L r b` in every connector preset); the frame's flips and rotation put those corners
+ * wherever the ends are.
+ */
+export declare const toRadians: (degrees: number) => number;
+/**
+ * A point of a movable's frame on the sheet: mirrored within the frame as its flip says, then
+ * turned with the frame about its center. The map `drawnBounds` applies to a box, for one point.
+ */
+export declare const placePoint: (placement: IMovable.Placement, local: Point) => Point;
+/** The inverse of {@link placePoint}: a point on the sheet in the frame's own coordinates. */
+export declare const unplacePoint: (placement: IMovable.Placement, point: Point) => Point;
+/** Where a placed connector's ends are on the sheet. */
+export declare const connectorEndPoints: (placement: IMovable.Placement) => {
+    start: Point;
+    end: Point;
+};
+/**
+ * The placement that runs a connector from `start` to `end`, turned by `rotation`: the box of the
+ * two points in the frame's own axes, mirrored on each axis the end lies before the start on.
+ *
+ * @remarks
+ * A turn about the frame's center leaves the center where it is, so the center is the midpoint
+ * of the two ends however the frame is turned; the start turned back about it is a corner of the
+ * unrotated frame, and the end is the opposite corner.
+ */
+export declare const placeConnector: (start: Point, end: Point, rotation?: number) => IMovable.Placement;
+//# sourceMappingURL=_ConnectorFrame.d.ts.map

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

@@ -0,0 +1,33 @@
+import { Bounds, Point } from '@sheetxl/utils';
+import { IMovable } from '../movable/IMovable';
+/** A direction on the sheet's axes, in quarter turns clockwise from +x: right, down, left, up. */
+export type Direction = 0 | 1 | 2 | 3;
+/** One end of a route: the site, the way the site faces, and the box of the shape it is on. */
+export interface RouteEnd {
+    point: Point;
+    direction: Direction;
+    box: Bounds;
+}
+/** What a routed connector is: the preset, its adjust values and where its frame is. */
+export interface Route {
+    /** `bentConnector2` to `5`, or the curved preset of the same shape. */
+    geometry: string;
+    /** The adjust values in the file's units (100000 is the whole frame); `null` for an L. */
+    adjustments: Record<string, number> | null;
+    placement: IMovable.Placement;
+    /** The bent route's corners on the sheet, from the start to the end, as the preset draws them. */
+    points: Point[];
+}
+/**
+ * The way a connector's free end faces when the other end is glued, as Excel routes it: back
+ * toward the glued end, along the axis they are further apart on; level, across the glued site.
+ */
+export declare const freeEndDirection: (free: Point, glued: Point, gluedDirection: Direction) => Direction;
+/** The direction a vector points, to the nearest quarter turn. */
+export declare const toDirection: (dx: number, dy: number) => Direction;
+/**
+ * The route Excel draws between two glued sites, as `bentConnector` presets or, with `curved`, the
+ * curved ones of the same shape. The frame is turned so the start leaves along its own x axis.
+ */
+export declare const routeConnector: (start: RouteEnd, end: RouteEnd, curved: boolean) => Route;
+//# sourceMappingURL=_ConnectorRoute.d.ts.map

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

@@ -0,0 +1,108 @@
+import { IMovable } from '../movable/IMovable';
+import { IWorksheet } from '../sheet/IWorksheet';
+import { IShape } from './IShape';
+import { Direction, Route } from './_ConnectorRoute';
+export { connectorEndPoints, placeConnector, placePoint, unplacePoint } from './_ConnectorFrame';
+/**
+ * Connectors: the connection sites of a placed movable, and the glue that keeps a connector's
+ * ends on the sites it is attached to. The frame math is `_ConnectorFrame`'s, the routing
+ * `_ConnectorRoute`'s.
+ */
+/**
+ * The sites of a content that declares none: the four edge midpoints, each leaving straight
+ * out, numbered as the `rect` preset numbers its own (top, left, bottom, right). What Excel
+ * offers on a picture, a chart, a slicer or a control.
+ */
+export declare const edgeConnections: (width: number, height: number) => readonly IMovable.Connection[];
+/** A connection site on the sheet. */
+export interface Site {
+    /** The site's index, as a connector's end names it. */
+    index: number;
+    x: number;
+    y: number;
+    /** The way a connector leaves the site, on the sheet's axes. */
+    direction: Direction;
+}
+/**
+ * The connection sites of a movable on the sheet: what its content declares, or the four edges
+ * when it declares nothing; `null` when the content cannot answer yet (`onReady` is called when
+ * it can).
+ */
+export declare const connectionSites: (movable: IMovable, placement: PlacementPreview | null, onReady: () => void) => Site[] | null;
+/** The id a connector's end names a movable by, when it has one. */
+export declare const sourceIdOf: (movable: IMovable) => number | undefined;
+/**
+ * The id a connector's end names `movable` by, giving it one when it has none yet: what a target
+ * takes when a connector first glues to it, so the file writes it with that id.
+ */
+export declare const ensureSourceId: (movable: IMovable, next: () => number) => number;
+/** The glued ends of a connector; `null` for a movable that is not a connector with any. */
+export declare const connectorEndsOf: (movable: IMovable) => IShape.ConnectorEndsJSON | null;
+/**
+ * Whether the sheet's movable `movable` is, or may hold, a connector: a connector, a group, or a
+ * shape still loading, which cannot say yet.
+ */
+export declare const mayHoldConnector: (movable: IMovable) => boolean;
+/** The movable a connector's end names, or `null` when none on the sheet has that id. */
+export declare const findBySourceId: (sheet: IWorksheet, id: number) => IMovable | null;
+/**
+ * An id no movable on the sheet has: what a target takes when a connector first glues to it, so
+ * the file writes the target with it and the connector's end names it. A file's ids start at 2.
+ */
+export declare const nextSourceId: (sheet: IWorksheet) => number;
+/** Where a movable is and, while a gesture moves its handles, the adjust values its shape takes. */
+export type PlacementPreview = IMovable.PlacementPreview;
+/** Where each movable is, for the glue: the model's placement unless the caller says otherwise. */
+export type PlacementResolver = (movable: IMovable) => PlacementPreview | null;
+export declare const modelPlacement: PlacementResolver;
+/** Where a glued connector goes: its placement and, when it is routed, its preset and adjust values. */
+export interface GluedRoute {
+    placement: IMovable.Placement;
+    /** The route, when both ends are glued on a bent or curved connector. */
+    route: Route | null;
+}
+/**
+ * Where a connector goes with each glued end on its target's site, the targets placed as
+ * `placements` says; `null` when no end could be placed (none is glued, no target is found, or
+ * none has evaluated its sites yet). An end whose target cannot be placed stays where it is.
+ *
+ * @remarks
+ * A bent or curved connector glued at both ends is routed between the two sites, as Excel routes
+ * it whenever either shape moves: a new preset, new adjust values and a frame turned to the start.
+ *
+ * Glued at one end, it moves whole with a target that only moves (`translated`; inferred from
+ * `placements` against the model when not given), as Excel moves it. Any other change keeps the
+ * free end where it is: a bent or curved connector is routed to it, the free end facing back
+ * toward the glued one.
+ */
+export declare const gluedRoute: (sheet: IWorksheet, connector: IMovable, placements: PlacementResolver, onReady: () => void, resolve?: (id: number) => IMovable | null, translated?: boolean) => GluedRoute | null;
+/** The placement a connector takes with each glued end on its target's site; see {@link gluedRoute}. */
+export declare const gluedPlacement: (sheet: IWorksheet, connector: IMovable, placements: PlacementResolver, onReady: () => void, resolve?: (id: number) => IMovable | null) => IMovable.Placement | null;
+/**
+ * Every connector on the sheet with a glued end off its site, and the placement that puts it back;
+ * read only, so a caller writes nothing when nothing moved.
+ */
+export declare const strayConnectors: (sheet: IWorksheet, onReady: () => void) => [IMovable, GluedRoute][];
+/**
+ * Writes where a connector goes onto it, touching only what differs: the turn first, which keeps
+ * the frame where it is, then the frame, the flips, and the route's preset and adjust values.
+ */
+export declare const applyPlacement: (connector: IMovable, next: GluedRoute) => void;
+/** The connectors on the sheet with an end glued to any of `targets`. */
+export declare const gluedConnectors: (sheet: IWorksheet, targets: ReadonlyMap<number, IMovable>) => IMovable[];
+/** `movables` and every movable inside them, by the id a connector names each by. */
+export declare const targetsById: (movables: readonly IMovable[]) => Map<number, IMovable>;
+/**
+ * Places every connector glued to `changed`, or to a movable inside it, as part of the open
+ * operation: a move of the target moves the connector in the same undoable step.
+ *
+ * @param onReady Called when a target's sites were not evaluated yet and are now: the caller runs
+ * the glue again, folded into the commit it belongs to.
+ */
+export declare const glueConnectorsTo: (sheet: IWorksheet, changed: IMovable, onReady: () => void, translated?: boolean) => void;
+/**
+ * Places one connector on its targets' sites, as part of the open operation: what gluing an end
+ * does once the end is recorded.
+ */
+export declare const glueConnector: (sheet: IWorksheet, connector: IMovable, onReady: () => void) => void;
+//# sourceMappingURL=_Connectors.d.ts.map

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

@@ -0,0 +1,14 @@
+import { ITheme } from '../theme';
+import { IGeometry } from './IGeometry';
+import { IShape } from './IShape';
+/**
+ * What a geometry paints, in pixels in the shape's frame: its paths' box grown by the reach of the
+ * line each is stroked with.
+ */
+export declare const getDrawnRect: (geometry: IGeometry) => IGeometry.Rect;
+/**
+ * A shape's geometry from its JSON, at `width` by `height` in pixels, loading only what it needs.
+ * `null` for a shape whose preset is not known.
+ */
+export declare const createGeometry: (json: IShape.JSON, theme: ITheme.JSON | null, width: number, height: number) => Promise<IGeometry | null>;
+//# sourceMappingURL=_Geometry.d.ts.map

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

@@ -0,0 +1,21 @@
+import { IGeometry } from './IGeometry';
+/**
+ * The lazily loaded parts of shape geometry. None is imported statically: a workbook with no
+ * shapes never loads them, a sheet of rectangles and straight lines loads at most the line ends,
+ * and any other preset loads the engine and the one chunk of definitions that holds it.
+ *
+ * Each promise is memoized once it resolves and dropped on failure, so a transient load error is
+ * retried on the next ask rather than cached forever (the same pattern as the scripting and
+ * compiler loaders).
+ */
+export type Engine = typeof import('./geometry');
+export type StrokeEnds = typeof import('./geometry/_strokeEnds');
+/** Guides, paths, handles and line ends: everything but the preset definitions. */
+export declare const loadEngine: () => Promise<Engine>;
+/** Line ends alone, for a straight line that declares a head or tail. */
+export declare const loadStrokeEnds: () => Promise<StrokeEnds>;
+/** Whether a name is a preset this SDK defines. */
+export declare const isPreset: (name: string) => boolean;
+/** A preset's built-in definition, loading the chunk that holds it; `undefined` for a name that is not a preset. */
+export declare const loadBuiltInDef: (name: string) => Promise<IGeometry.Def | undefined>;
+//# sourceMappingURL=_GeometryLoader.d.ts.map