@sheetxl/sdk 0.8.0-beta.6 → 0.8.0-beta.9

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

@@ -1,13 +1,13 @@
-import { Point, Rectangle } from '@sheetxl/utils';
-import { IListener } from '../listener';
+import { Bounds } 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 { ITextFrame } from '../text/ITextFrame';
+import { IStroke, IFill, IEffect } from '../fill';
+import { ITheme } from '../theme';
+import { ITextFrame } from '../text';
+import { IGeometry } from './IGeometry';
 /**
  * A drawn shape: a text box, a callout, a rectangle, a connector, or a group of them.
  *
@@ -16,8 +16,8 @@ import { ITextFrame } from '../text/ITextFrame';
  * whose content type is `'shape'`. The movable carries the position; the shape carries what is
  * drawn there and what is written on it.
  *
- * Reading only: a shape's preset and its text. An imported shape is otherwise kept as the source
- * wrote it and saved back unchanged.
+ * 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, IMovable.IContent {
     toJSON(toResourceId?: (resource: IResource) => number | null): IShape.JSON | null;
@@ -25,6 +25,12 @@ export interface IShape extends IModel, IMovable.IContent {
      * Returns the name of the shape.
      */
     getName(): string | null;
+    /**
+     * The image a resource id in this shape's JSON names: an image fill's `resId`, a picture
+     * member's among them, as {@link toJSON} with no scope names them. `null` when the shape holds
+     * no such resource.
+     */
+    getResource(resourceId: number): IResource | null;
     /**
      * Deletes the shape, and with it the movable that places it.
      */
@@ -33,8 +39,9 @@ export interface IShape extends IModel, IMovable.IContent {
      * Returns the kind of shape this is: its preset geometry.
      *
      * @remarks
-     * A DrawingML preset id — `rect`, `borderCallout2`, `curvedConnector3` — or `'custom'` for a
-     * shape drawn from its own path, or `'group'` for a group of shapes.
+     * A DrawingML preset id ({@link IGeometry.Preset}) — `rect`, `borderCallout2`, `curvedConnector3` —
+     * or `'custom'` for a shape drawn from its own path, or `'group'` for a group of shapes. 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
@@ -60,6 +67,48 @@ export interface IShape extends IModel, IMovable.IContent {
      * ```
      */
     getTextFrame(): ITextFrame.IText | null;
+    /**
+     * 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. A group's geometry is its members', each placed in the group's frame.
+     *
+     * @param width Width in pixels. @defaultValue the movable's bounds.
+     * @param height Height in pixels. @defaultValue the movable's bounds.
+     * @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): Promise<IGeometry | null>;
+    /** For runtime type checking. */
+    readonly isIShape: true;
 }
 /**
  * {@inheritDoc IShape}
@@ -69,6 +118,25 @@ export interface IShape extends IModel, IMovable.IContent {
  * {@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";
+        /** A group of shapes, placed together; its members are its {@link JSON.children}. */
+        readonly Group: "group";
+        /** A picture inside a group; see {@link PictureMemberJSON}. */
+        readonly Picture: "picture";
+    };
+    type Type = typeof Type[keyof typeof Type];
     /**
      * A set of values that can be set on a IShape.
      *
@@ -77,15 +145,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.
          */
@@ -97,223 +170,123 @@ 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;
-        /** The `mc:Fallback` rendition of `xml`, captured verbatim, when the source offered the shape as an
-         * `mc:AlternateContent`. An equation's fallback is where its linear text form is. */
-        fallbackXml?: 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, a group
+         * and a group's picture member state theirs.
          */
-        textBounds?: Rectangle;
-    }
-    interface Path {
-        paths: string[];
+        type?: Type;
+        fill?: IFill.SolidJSON | IFill.GradientJSON | IFill.PatternJSON | IFill.ImageJSON | IFill.NoneJSON;
+        stroke?: IStroke.JSON;
         /**
-         * 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 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.
          */
-        extrusionOk?: boolean;
+        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 how the corresponding path should be filled.
-         *
-         * @defaultValue `PathFill.Normal`
+         * Edit locks (`spLocks`/`cxnSpLocks`) by the file's own names: `noGrp`, `noSelect`, `noRot`,
+         * `noChangeAspect`, `noMove`, `noResize`, `noEditPoints`, `noAdjustHandles`,
+         * `noChangeArrowheads`, `noChangeShapeType`, `noTextEdit`.
          */
-        pathFill?: PathFill;
+        locks?: Record<string, boolean>;
+        /** A connector's glued ends. */
+        connectorEnds?: {
+            start?: ConnectorEndJSON;
+            end?: ConnectorEndJSON;
+        };
+        /** The text written on the shape, by paragraph. Absent for a shape with no text body. */
+        text?: ITextFrame.JSON;
         /**
-         * 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`
+         * A group's members in z-order. A member is read like any shape but is not captured on its
+         * own: the group's markup holds it. A member's `bounds` are in the group's child space. A
+         * picture among them is a {@link PictureMemberJSON}.
          */
-        h?: number;
+        children?: (JSON | PictureMemberJSON)[];
+        /** Where the shape sits as the file states it (`xfrm`), in pixels. For a group member, in the group's child space. */
+        bounds?: Bounds;
+        /** A group's child space (`chOff`/`chExt`), in pixels: what its members' `bounds` are stated in. */
+        childBounds?: Bounds;
+        /** Rotation in degrees as the file states it on the shape's own `xfrm`. */
+        rotation?: number;
+        /** Mirrored left to right (`xfrm/@flipH`), as the file states it. */
+        flipH?: boolean;
+        /** Mirrored top to bottom (`xfrm/@flipV`), as the file states it. */
+        flipV?: boolean;
         /**
-         * 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.
+     * A picture inside a group (`pic`): a member like any other, placed by its `bounds` in the
+     * group's child space. Its geometry is a rectangle and its image is its fill.
+     *
+     * @remarks
+     * The fill's `resId` names the image the way {@link IPicture.JSON.resId} names a placed
+     * picture's, and like it is meaningful only inside the persist scope the JSON was made in: a
+     * shape resolves it to the resource when it is created and names the resource again when it
+     * is serialized.
      */
-    interface AdjustmentHandle {
-        /**
-         * The point of the adjustment
-         */
-        pos: Point;
-    }
-    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;
-    }
-    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;
-        /**
-         * Specifies the name of the guide that will be updated with the adjustment y position from this adjust handle.
-         */
-        gdRefY: string;
-        /**
-         * 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.
-         */
-        maxX: number;
-        /**
-         * 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.
-         */
-        maxY: number;
-        /**
-         * 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.
-         */
-        minX: number;
-        /**
-         * 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;
+    interface PictureMemberJSON extends JSON {
+        type: typeof Type.Picture;
+        /** The image, as an image fill. */
+        fill?: IFill.ImageJSON;
     }
     /**
-     * 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.
+     * One glued end of a connector: the shape it is attached to, by the id the file gives that
+     * shape (its `sourceId` here), and which of that shape's connection sites.
      */
-    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.
-         */
-        pos: Point;
-    }
-    interface GeometryJSON extends GeometryProperties {
-    }
-    interface Events extends IModel.Events {
-    }
-    interface IListeners extends IListener.Callbacks<IShape, IShape.Events> {
+    interface ConnectorEndJSON {
+        id: number;
+        index: number;
     }
-    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

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

@@ -1,6 +1,8 @@
-import { IResource, IResourceCollection } from '../resource';
+import { ITransaction } from '../transaction';
+import { IResource } from '../resource';
+import { ITextFrame } from '../text';
 import { AbstractMovableContent } from '../movable/AbstractMovableContent';
-import { ITextFrame } from '../text/ITextFrame';
+import { IGeometry } from './IGeometry';
 import { IShape } from './IShape';
 interface State extends AbstractMovableContent.State {
     data?: any;
@@ -9,27 +11,55 @@ interface State extends AbstractMovableContent.State {
  * Implementation for {@link IShape}.
  */
 export declare class Shape extends AbstractMovableContent<State, IShape.JSON> implements IShape {
-    /** The state `_facts` was read from; a new state object is a new read. */
-    private _factsSource;
-    private _facts;
+    /** The state the text frame was read from; a new state object is a new read. */
+    private _textSource;
+    private _textFrame;
+    /**
+     * The images the JSON names — an image fill's, a group's picture members' — by the resource id
+     * it names them 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;
+    /** The last evaluation {@link _getDrawnRect} answers 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.getShapeType} */
     getShapeType(): string;
     /** {@inheritDoc IShape.getTextFrame} */
     getTextFrame(): ITextFrame.IText | null;
-    /** The captured fragment is read once per state, on first ask; most shapes are never asked. */
-    private _getFacts;
+    /** {@inheritDoc IShape.getAdjustments} */
+    getAdjustments(): Readonly<Record<string, number>>;
+    /** {@inheritDoc IShape.setAdjustments} */
+    setAdjustments(adjustments: Record<string, number> | null, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IShape.getGeometry} */
+    getGeometry(width?: number, height?: number): 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;
+    /** 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;
+    toJSON(toResourceId?: (resource: IResource) => number | null): IShape.JSON | null;
     /** {@inheritDoc IMovable.IContent.getTypeDescription} */
     getTypeDescription(): string;
+    /** {@inheritDoc IShape.isIShape} */
+    get isIShape(): true;
     get [Symbol.toStringTag](): string;
     toString(): string;
 }
 /**
- * Interfaces for creating `Chart` items.
+ * Interfaces for creating `Shape` items.
  *
  * @see
  * ### **Interface**
@@ -45,10 +75,6 @@ export declare namespace Shape {
          * 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.
          */

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

@@ -0,0 +1,48 @@
+import { IFill, IStroke } from '../fill';
+import { ITheme } from '../theme';
+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 picture's differ. */
+export declare function defaultStyleRefs(json: IShape.JSON | null | undefined): Readonly<ITheme.StyleRefsJSON>;
+/**
+ * `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;
+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: Partial<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): ResolvedShapeStyle;
+//# sourceMappingURL=ShapeStyleUtils.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 picture or 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

package/types/src/shape/_builtIn/_BuiltInChunks.d.ts

@@ -0,0 +1,10 @@
+import { BuiltInDef } from './_BuiltInDef';
+/** A chunk of built-in definitions. */
+export interface BuiltInChunk {
+    /** Connection-site lists shared by more than one shape in the chunk; `BuiltInDef.cxn` indexes into this. */
+    CXN_SHARED: readonly (readonly string[])[];
+    BUILT_IN: Readonly<Record<string, BuiltInDef>>;
+}
+/** Each chunk's loader and the presets it holds. */
+export declare const BUILT_IN_CHUNKS: readonly (readonly [load: () => Promise<BuiltInChunk>, names: readonly string[]])[];
+//# sourceMappingURL=_BuiltInChunks.d.ts.map