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

package/types/src/picture/IPicture.d.ts

@@ -4,6 +4,9 @@ import { ITransaction } from '../transaction';
 import { IResource, IResourceCollection } from '../resource';
 import { IModel } from '../model';
 import { IMovable } from '../movable';
+import { IFill, IStroke, IEffect } from '../fill';
+import { IHyperlink } from '../hyperlink';
+import { IGeometry, IShape, IShapeStyle } from '../shape';
 /**
  * Interface for working with Pictures (both Images and SVG).
  */
@@ -33,6 +36,43 @@ export interface IPicture extends IModel, IMovable.IContent {
      * ```
      */
     setResource(picture: string | IResource | IResourceCollection.AddOptions, options?: ITransaction.OperationOptions): this;
+    /**
+     * Returns the shape the picture is cropped to: its preset geometry.
+     *
+     * @remarks
+     * A DrawingML preset id ({@link IGeometry.Preset}): `rect` for a picture that is not cropped to
+     * a shape, which is most of them. A file may name a preset this SDK does not know; it is
+     * returned as the file states it.
+     */
+    getShapeType(): string;
+    /**
+     * Crops the picture to a shape, as Excel's Crop to Shape does: the image, its frame, border and
+     * effects stay; the picture is clipped to the preset's outline.
+     *
+     * A picture takes any closed preset; a line or connector preset is refused.
+     *
+     * @param shapeType A DrawingML preset id ({@link IGeometry.Preset}); `rect` crops to nothing.
+     * @throws ExpectedError for a preset the picture cannot take.
+     *
+     * @example
+     * ```ts
+     * picture.setShapeType(IGeometry.Preset.Ellipse);
+     * ```
+     */
+    setShapeType(shapeType: IGeometry.Preset | string, options?: ITransaction.OperationOptions): this;
+    /**
+     * What the picture's frame draws with: the fill behind the image and the border around it.
+     * A picture has no theme style, so each is only what the picture states; by default neither
+     * draws, and a border shows only once it has a color (a width alone draws nothing, as in
+     * Excel). The same object answers for the life of the picture.
+     *
+     * @example
+     * ```ts
+     * picture.getStyle().getStroke().setWidth(2.25);
+     * picture.getStyle().setFill('#ffd966');
+     * ```
+     */
+    getStyle(): IShapeStyle;
     /**
      * Returns an image blob.
      */
@@ -64,6 +104,13 @@ export declare namespace IPicture {
      */
     interface Properties {
     }
+    /**
+     * How the image is placed in the picture's frame (`blipFill`): the part of it shown, whether
+     * that part is stretched over the frame or tiled across it, and the adjustments made to the
+     * image itself. The same slots as an {@link IFill.ImageJSON | image fill}, without the image:
+     * a picture names its image by {@link JSON.resId}.
+     */
+    type ImageJSON = Omit<IFill.ImageProperties, 'type' | 'resId'>;
     interface JSON {
         /**
          * The resource id of the picture.
@@ -75,7 +122,57 @@ export declare namespace IPicture {
          * glues to it.
          */
         sourceId?: number;
-        effects?: string[];
+        /**
+         * How the image fills the frame: the crop (`srcRect`), stretch insets or tiling, and the
+         * image's own adjustments. Absent for the whole image stretched over the whole frame, which
+         * is what an inserted picture is.
+         */
+        image?: ImageJSON;
+        /**
+         * The shape the picture is cropped to (`prstGeom`); absent for a rectangle, i.e. not cropped
+         * to a shape.
+         */
+        geometry?: string | IGeometry.Def;
+        /** The adjust values of {@link geometry}, by name, where a handle moved them off the preset's defaults. */
+        adjustments?: Record<string, number>;
+        /**
+         * The fill behind the image (`spPr`); a transparent image shows it. Absent for none.
+         */
+        fill?: IFill.SolidJSON | IFill.GradientJSON | IFill.PatternJSON | IFill.ImageJSON | IFill.NoneJSON;
+        /** The border around the frame (`spPr/ln`). Absent for none. */
+        stroke?: IStroke.JSON;
+        /** The frame's effects (`spPr/effectLst`): a shadow, a glow, a reflection, soft edges. */
+        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?: IShape.ExtLstJSON;
+        /** The hyperlink on the picture (`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 assigned to the picture (`pic/@macro`), as the file states it. */
+        macro?: string;
+        /** `pic/@fPublished`. */
+        published?: boolean;
+        /**
+         * Edit locks (`picLocks`) by the file's own names: `noChangeAspect`, `noCrop`, `noGrp`,
+         * `noSelect`, `noRot`, `noMove`, `noResize`, `noEditPoints`, `noAdjustHandles`,
+         * `noChangeArrowheads`, `noChangeShapeType`. `noChangeAspect` is also the movable's
+         * {@link IMovable.JSON.lockAspect | aspect lock}, which wins when both are stated.
+         */
+        locks?: Record<string, boolean>;
+        /**
+         * Resizing is not relative to the original picture size (`cNvPicPr/@preferRelativeResize="0"`,
+         * Excel's "Relative to original picture size" unticked). Carried for the file.
+         *
+         * @defaultValue false
+         */
+        noRelativeResize?: boolean;
     }
     interface Details {
         /**

package/types/src/picture/Picture.d.ts

@@ -3,13 +3,15 @@ import { IResource, IResourceCollection } from '../resource';
 import { IAnchored } from '../anchored';
 import { IMovable } from '../movable/IMovable';
 import { AbstractMovableContent } from '../movable/AbstractMovableContent';
+import { IGeometry, IShapeStyle } from '../shape';
 import { IPicture } from './IPicture';
+/** The picture's JSON beyond its image: everything {@link IPicture.JSON} states but `resId`. */
+type Data = Omit<IPicture.JSON, 'resId'>;
 interface State extends AbstractMovableContent.State {
     /** The image shown. In the state so that a change of picture undoes with the rest. */
     resource: IResource;
-    effects?: string[];
-    /** The id the file gave the picture; see `IPicture.JSON.sourceId`. */
-    sourceId?: number;
+    /** What the picture states of itself beyond the image; absent for an inserted picture. */
+    data?: Data;
 }
 /**
  * Implementation for {@link IPicture}.
@@ -19,15 +21,21 @@ export declare class Picture extends AbstractMovableContent<State, IPicture.JSON
     private _detailsSource;
     private _details?;
     private _dataUrl?;
+    private _getStyles;
+    private _style;
     constructor(options: Picture.ConstructorOptions);
     /** {@inheritDoc IPicture.getType} */ getType(): string;
     toJSON(toResourceId?: (resource: IResource) => number | null): IPicture.JSON;
     /** {@inheritDoc IMovable.IContent.getTypeDescription} */
     getTypeDescription(): string;
-    /** @internal */
-    _getSourceId(): number | undefined;
-    /** @internal */
-    _ensureSourceId(next: () => number): number;
+    /** {@inheritDoc IPicture.getShapeType} */
+    getShapeType(): string;
+    /** {@inheritDoc IPicture.setShapeType} */
+    setShapeType(shapeType: IGeometry.Preset | string, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IPicture.getStyle} */
+    getStyle(): IShapeStyle;
+    /** Writes what the picture states of its fill and border: a key `undefined` is removed. */
+    private _writeStyle;
     /** {@inheritDoc IMovable.IContent.acceptRotation} */
     acceptRotation(degrees: number): number;
     /** {@inheritDoc IMovable.IContent.acceptFlip} */

package/types/src/pivot/IPivotTable.d.ts

@@ -1,5 +1,5 @@
 import { IResource } from '../resource';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { ICellRange } from '../cellRange';
 import { IAnchored } from '../anchored';
 import { IEmbeddedPart } from '../io';
@@ -21,7 +21,7 @@ export interface IPivotTable extends IAnchored {
     /**
      * Returns the sheet the table is laid out on.
      */
-    getSheet(): ISheet;
+    getWorksheet(): IWorksheet;
     /**
      * Returns the cells the table is laid out on.
      *

package/types/src/pivot/PivotTable.d.ts

@@ -1,6 +1,6 @@
 import { IRange } from '@sheetxl/primitives';
 import { IResource } from '../resource';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { Anchored } from '../anchored/Anchored';
 import { AbstractAnchored } from '../anchored/AbstractAnchored';
 import { IEmbeddedPart } from '../io';
@@ -22,7 +22,7 @@ interface State extends AbstractAnchored.State {
  * is refused. {@link getXML} restates the anchor into the part; the rest of the part is as read.
  */
 export declare class PivotTable extends AbstractAnchored<State, IPivotTable.Events> implements IPivotTable {
-    protected _sheet: ISheet;
+    protected _sheet: IWorksheet;
     protected _part: IEmbeddedPart | null;
     /** The location as the part spells it. While the anchor still says the same, the part is as read. */
     private _ref;
@@ -30,8 +30,8 @@ export declare class PivotTable extends AbstractAnchored<State, IPivotTable.Even
     protected _initialize(options: PivotTable.ConstructorOptions): void;
     /** {@inheritDoc IPivotTable.getName} */
     getName(): string;
-    /** {@inheritDoc IPivotTable.getSheet} */
-    getSheet(): ISheet;
+    /** {@inheritDoc IPivotTable.getWorksheet} */
+    getWorksheet(): IWorksheet;
     /** {@inheritDoc IPivotTable.getXML} */
     getXML(): string | null;
     /** {@inheritDoc IPivotTable.getCacheId} */
@@ -53,7 +53,7 @@ export declare class PivotTable extends AbstractAnchored<State, IPivotTable.Even
 }
 export declare namespace PivotTable {
     interface ConstructorOptions extends Anchored.ConstructorOptions<IPivotTable.JSON> {
-        sheet: ISheet;
+        sheet: IWorksheet;
         fromResourceId?: (resourceId: number) => IResource;
     }
 }

package/types/src/primitives/ReferenceRange.d.ts

@@ -19,8 +19,8 @@ export declare class ReferenceRange extends Range implements IReferenceRange {
     /**
      * Told when a body reads this reference's POSITION (`getCoords`). A reference's values are a
      * property of what it points at; its address is a property of which cell is asking, so a
-     * formula that reads it (`ROW(A13)`, `CELL("address",A13)`) cannot share its answer with another
-     * cell — see `CalcScope.perCellRead`. Set by the context that builds the reference; a view
+     * formula that reads it (`ROW(A13)`, `CELL("address",A13)`) shares its answer with another cell
+     * only where the position cannot matter — see `CalcScope.positionRead`. Set by the context that builds the reference; a view
      * (`slice`, `toType`) carries it.
      */
     protected _onCoordsRead: (() => void) | null;