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

package/types/src/{lib/file → file}/file.browser.d.ts

@@ -1,6 +1,6 @@
-import { IWorkbook } from '../../workbook';
-import { IWorkbookIO } from '../../io/IWorkbookIO';
-import { AbstractBackingStore } from '../../io/AbstractBackingStore';
+import { IWorkbook } from '../workbook';
+import { IWorkbookIO } from '../io/IWorkbookIO';
+import { AbstractBackingStore } from '../io/AbstractBackingStore';
 /**
  * The browser {@link IWorkbookIO.IBackingStore}. Reads via a file the caller supplies (or an
  * open picker when none is given) and writes via the File System Access API
@@ -11,7 +11,9 @@ import { AbstractBackingStore } from '../../io/AbstractBackingStore';
  * per-instance cache **keyed by the origin**, so a save to a bound origin can re-write silently.
  * This is an invisible optimization — a handle cannot be recreated from a string path, so holding
  * the object is the only way to re-save in place. Nothing about it is surfaced through any public
- * type; the origin's `canWrite()` reflects whether a handle is held.
+ * type; the origin's `canWrite()` reflects whether a handle is held — decided when the source is
+ * acquired, since holding the handle is the whole question. Write *permission* is a separate
+ * matter the platform only answers by prompting, which happens at save time.
  */
 export declare class BrowserBackingStore extends AbstractBackingStore {
     private _getWriteFormats;
@@ -19,14 +21,26 @@ export declare class BrowserBackingStore extends AbstractBackingStore {
     protected _defaultStringSourceType: "fetch";
     /** Writable FSA handles keyed by the Origin they back. */
     private _handleCache;
-    private _pendingOpenHandle;
     constructor(_getWriteFormats: () => Promise<IWorkbookIO.FormatType[]>, _getReadFormats?: (() => Promise<IWorkbookIO.FormatType[]>) | undefined);
-    /** @inheritdoc IWorkbookIO.IBackingStore.read */
-    read(request: IWorkbookIO.ReadRequest): Promise<IWorkbook | null>;
+    /**
+     * A File System Access handle (from an open picker, or a drop via `getAsFileSystemHandle`) can be
+     * written back to, so it reads as a writable source.
+     */
+    protected fileFromHandle(source: any): Promise<File | null>;
     /** @inheritdoc */
     protected resolveSource(): Promise<any>;
+    /**
+     * Browser sources have no real path — a picked file is identified by its handle — so a file is
+     * open when a handle held for an open workbook's origin is the same entry.
+     */
+    protected findOpenOrigin(acquired: any): Promise<IWorkbookIO.Origin | null>;
+    /**
+     * The origin of an open workbook, other than `except`, that saves back through a handle to the
+     * same file as `handle`, or `null`.
+     */
+    private _findOpenHandle;
     /** @inheritdoc */
-    protected onWorkbookRead(workbook: IWorkbook): Promise<void>;
+    protected onWorkbookRead(workbook: IWorkbook, source: any): Promise<void>;
     /** @inheritdoc */
     protected filePathToFile(filePath: string): Promise<File>;
     /** @inheritdoc IWorkbookIO.IBackingStore.write */

package/types/src/{lib/file → file}/file.node.d.ts

@@ -1,5 +1,5 @@
-import { IWorkbookIO } from '../../io/IWorkbookIO';
-import { AbstractBackingStore } from '../../io/AbstractBackingStore';
+import { IWorkbookIO } from '../io/IWorkbookIO';
+import { AbstractBackingStore } from '../io/AbstractBackingStore';
 /**
  * The node {@link IWorkbookIO.IBackingStore}. Reads from local paths via `fs`, and writes to the
  * destination {@link IWorkbookIO.Origin} handle. Node has no interactive picker, so a
@@ -12,6 +12,11 @@ export declare class FSBackingStore extends AbstractBackingStore {
     protected filePathToFile(filePath: string): Promise<File>;
     /** @inheritdoc */
     protected _canWriteLocalPath(): boolean;
+    /**
+     * Both paths are already resolved to absolute ones (reads and writes resolve them); Windows file
+     * names are case-insensitive and take either slash.
+     */
+    protected isSamePath(a: string, b: string): boolean;
     /** @inheritdoc IWorkbookIO.IBackingStore.write */
     write(request: IWorkbookIO.WriteRequest): Promise<IWorkbookIO.Origin | null>;
 }

package/types/src/fill/IEffect.d.ts

@@ -1,5 +1,6 @@
 import { Properties as CSSProperties } from 'csstype';
 import { IColor } from '../color';
+import { RectAlignment } from './RectAlignment';
 /**
  * *** **PLACEHOLDER** - Not yet implemented.
  *
@@ -89,8 +90,7 @@ export declare namespace IEffect {
     /**
      * A JSON representation useful for persistence.
      */
-    interface JSON extends Properties {
-    }
+    type JSON = OuterShadowJSON | InnerShadowJSON | PresetShadowJSON | GlowJSON | SoftEdgeJSON | ReflectionJSON;
     /**
      * Shared shape for the shadow family (`outerShdw`/`innerShdw`/`prstShdw`).
      */
@@ -137,9 +137,9 @@ export declare namespace IEffect {
          * The alignment of the shadow relative to the shape.
          *
          * @remarks
-         * (`algn` in OOXML — e.g. `'tl'`, `'ctr'`, `'br'`.)
+         * (`algn` in OOXML.)
          */
-        alignment?: string;
+        alignment?: RectAlignment;
         /**
          * Whether the shadow should rotate with the shape when the shape is rotated.
          *
@@ -374,7 +374,7 @@ export declare namespace IEffect {
          * @remarks
          * (`algn` in OOXML.)
          */
-        alignment?: string;
+        alignment?: RectAlignment;
         /**
          * Whether the reflection should rotate with the shape when the shape is rotated.
          *

package/types/src/fill/IFill.d.ts

@@ -1,7 +1,9 @@
 import { Properties as CSSProperties } from 'csstype';
 import { Rectangle, Size } from '@sheetxl/utils';
 import { IColor } from '../color';
-import { IStyle } from '../style';
+import { ITransaction } from '../transaction';
+import { IResource } from '../resource';
+import { RectAlignment } from './RectAlignment';
 /**
  * Defines how an area or shape is filled with color or a pattern.
  */
@@ -19,7 +21,7 @@ export interface IFill {
      * Different fill types will interpret the fill color differently. For example, a solid fill will use the color
      * directly, while a gradient fill may use the color as one of the gradient stops.
      */
-    setColor(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IFill;
+    setColor(color: IColor.Serializable | null, options?: ITransaction.OperationOptions): IFill;
     /**
      * Returns the fill color.
      */
@@ -87,7 +89,7 @@ export declare namespace IFill {
          * @remarks
          * * Not support in cells. This is currently only support in drawML (charts, shapes, powerpoint).
          */
-        readonly Image: "pattern";
+        readonly Image: "image";
         /**
          * An Image.
          * @remarks
@@ -138,27 +140,27 @@ export declare namespace IFill {
     };
     type GradientType = typeof GradientType[keyof typeof GradientType];
     /**
-     * Specifies how a tile is mirrored or flipped when filling a shape or container.
+     * Which of an image fill's tiles are mirrored, alternating across the fill (DrawingML `ST_TileFlipMode`).
      */
-    const TileMirror: {
+    const TileFlip: {
         /**
-         * No mirroring is applied.
+         * No tile is mirrored.
          */
         readonly None: "none";
         /**
-         * The tile is mirrored vertically (flipped along the y-axis).
+         * Every other column of tiles is mirrored horizontally.
          */
-        readonly Vertical: "v";
+        readonly Horizontal: "x";
         /**
-         * The tile is mirrored horizontally (flipped along the x-axis).
+         * Every other row of tiles is mirrored vertically.
          */
-        readonly Horizontal: "h";
+        readonly Vertical: "y";
         /**
-         * The tile is mirrored both vertically and horizontally.
+         * Tiles are mirrored horizontally across columns and vertically across rows.
          */
-        readonly Both: "b";
+        readonly Both: "xy";
     };
-    type TileMirror = typeof TileMirror[keyof typeof TileMirror];
+    type TileFlip = typeof TileFlip[keyof typeof TileFlip];
     /**
      * Contains the built-in pattern types.
      *
@@ -267,9 +269,11 @@ export declare namespace IFill {
         isRotatedWithShape?: boolean;
     }
     /**
-     * Modifiers describe a partial list of properties that can be set with values or shorthand strings.
+     * Modifiers describe a partial list of properties that can be set with values or shorthand strings:
+     * any one kind of fill, partially stated. A kind the update does not name is the one already
+     * there, or solid when a color is given.
      */
-    type Modifiers = Partial<IFill.Properties>;
+    type Modifiers = Partial<SolidProperties> | Partial<GradientProperties> | Partial<PatternProperties> | Partial<ImageProperties> | Partial<NoneProperties> | Partial<GroupProperties>;
     /**
      * Options for updating a fill.
      */
@@ -277,8 +281,7 @@ export declare namespace IFill {
     /**
      * A JSON representation useful for persistence.
      */
-    interface JSON extends Properties {
-    }
+    type JSON = NoneJSON | SolidJSON | GradientJSON | PatternJSON | ImageJSON | GroupJSON;
     /**
      * No fill is applied; the area is transparent.
      */
@@ -298,6 +301,15 @@ export declare namespace IFill {
     }
     interface NoneJSON extends NoneProperties {
     }
+    /**
+     * The fill of the group the shape is a member of (`<a:grpFill/>`): resolved by walking the
+     * shape's parents to the nearest group that states a fill, else the shape's theme style.
+     */
+    interface GroupProperties extends IFill.Properties {
+        type: typeof IFill.Type.Group;
+    }
+    interface GroupJSON extends GroupProperties {
+    }
     /**
      * A single color fill.
      */
@@ -315,7 +327,7 @@ export declare namespace IFill {
          *
          * @param color The stroke color.
          */
-        setColor(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IFill.ISolid;
+        setColor(color: IColor.Serializable | null, options?: ITransaction.OperationOptions): IFill.ISolid;
     }
     interface SolidProperties<C = IColor.Serializable> extends IFill.Properties {
         /**
@@ -331,49 +343,6 @@ export declare namespace IFill {
     }
     interface SolidJSON extends SolidProperties<string> {
     }
-    interface TileProperties {
-        /**
-         * @see
-         * {@link IFill.ITile.getAlign}
-         */
-        align?: string;
-        /**
-         * @see
-         * {@link IFill.ITile.getMirror}
-         */
-        mirror?: IFill.TileMirror;
-        /**
-         * @see
-         * {@link IFill.ITile.getBounds}
-         */
-        bounds?: Rectangle;
-        /**
-         * Create blur noise at the edges of the tile.
-         *
-         * @see {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stitchTiles}
-         */
-        stitch?: boolean;
-    }
-    /**
-     * Represents a tile used for filling shapes or other elements with a repeating pattern.
-     */
-    interface ITile {
-        /**
-         *  Specifies the alignment of the tile within its container.
-         *
-         *  @remarks
-         *  - Possible values: 'tl', 't', 'tr', 'l', 'c', 'r', 'bl', 'b', 'br' (representing top-left, top, top-right, etc.)
-         */
-        getAlign(): string;
-        /**
-         *  Determines how the tile is mirrored or flipped when filling the container.
-         */
-        getMirror(): IFill.TileMirror;
-        /**
-         *  Defines the rectangular bounds of the tile pattern.
-         */
-        getBounds(): Rectangle;
-    }
     interface GradientStopProperties<C = IColor.Serializable> {
         /**
          * @see
@@ -425,6 +394,19 @@ export declare namespace IFill {
          * {@link IFill.IGradient.getFocus}
          */
         focus?: Rectangle;
+        /**
+         * Whether a linear gradient's angle scales with the shape's aspect ratio (DrawingML `lin/@scaled`).
+         */
+        scaled?: boolean;
+        /**
+         * The rectangle the gradient is drawn in, as insets from the shape's bounds; the area outside it
+         * repeats the gradient as tiles (DrawingML `tileRect`). Absent for the whole shape.
+         */
+        tileRect?: RectInsets;
+        /**
+         * Which of the gradient's tiles are mirrored, when `tileRect` is smaller than the shape.
+         */
+        flip?: IFill.TileFlip;
     }
     /**
      * A gradient fill, where colors transition across the area.
@@ -446,7 +428,7 @@ export declare namespace IFill {
          *
          * @param stops The gradient stops.
          */
-        setStops(stops: (IGradientStop | IColor.Serializable | null)[], options?: IStyle.UpdateOptions): IFill.IGradient;
+        setStops(stops: (IGradientStop | IColor.Serializable | null)[], options?: ITransaction.OperationOptions): IFill.IGradient;
         /**
          * The type of gradient.
          * @defaultValue GradientType.Linear
@@ -457,7 +439,7 @@ export declare namespace IFill {
          *
          * @param type The gradient type.
          */
-        setGradientType(type: IFill.GradientType | null, options?: IStyle.UpdateOptions): IFill.IGradient;
+        setGradientType(type: IFill.GradientType | null, options?: ITransaction.OperationOptions): IFill.IGradient;
         /**
          * The angle of the gradient in degrees if gradient type is linear.
          */
@@ -467,7 +449,7 @@ export declare namespace IFill {
          *
          * @param angle The angle
          */
-        setAngle(angle: number | null, options?: IStyle.UpdateOptions): IFill.IGradient;
+        setAngle(angle: number | null, options?: ITransaction.OperationOptions): IFill.IGradient;
         /**
          * Used for path and circular gradients.
          */
@@ -481,7 +463,7 @@ export declare namespace IFill {
          * * For 'rect' gradients, this is the inner rectangle where the color is solid.
          * * For 'circle' gradients, the center of this rect is the focal point.
          */
-        setFocus(focus: Rectangle | null, options?: IStyle.UpdateOptions): IFill.IGradient;
+        setFocus(focus: Rectangle | null, options?: ITransaction.OperationOptions): IFill.IGradient;
         /**
          * Converts the gradient fill to a JSON representation.
          */
@@ -506,7 +488,7 @@ export declare namespace IFill {
          *
          * @param color The foreground color.
          */
-        setForeground(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IFill.IPattern;
+        setForeground(color: IColor.Serializable | null, options?: ITransaction.OperationOptions): IFill.IPattern;
         /**
          * The background color for the pattern.
          */
@@ -516,7 +498,7 @@ export declare namespace IFill {
          *
          * @param color The background color.
          */
-        setBackground(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IFill.IPattern;
+        setBackground(color: IColor.Serializable | null, options?: ITransaction.OperationOptions): IFill.IPattern;
         /**
          * The type of pattern used.
          */
@@ -526,7 +508,7 @@ export declare namespace IFill {
          *
          * @param type The pattern type.
          */
-        setPatternType(type: IFill.BuiltInSheetPattern | null, options?: IStyle.UpdateOptions): IFill.IPattern;
+        setPatternType(type: IFill.BuiltInSheetPattern | null, options?: ITransaction.OperationOptions): IFill.IPattern;
         /**
          * The two-layer, adaptive-capable form of the pattern: a solid `base` (background color) plus
          * `marks` — the foreground color masked by the pattern tile (`mask-image`). Unlike
@@ -574,24 +556,87 @@ export declare namespace IFill {
     }
     interface PatternJSON extends PatternProperties<string> {
     }
+    /**
+     * Insets of a rectangle from the edges of another, as percentages of its width and height
+     * (an inset of `-10` on the right extends past the edge by a tenth of the width).
+     */
+    interface RectInsets {
+        left?: number;
+        top?: number;
+        right?: number;
+        bottom?: number;
+    }
+    /** How a tiled image fill repeats (DrawingML `tile`). */
+    interface ImageTileProperties {
+        /** Offset of the first tile from the fill rectangle's origin, in pixels. */
+        offsetX?: number;
+        offsetY?: number;
+        /** Scale of each tile as a percentage (100 = natural size). */
+        scaleX?: number;
+        scaleY?: number;
+        /** Which tiles are mirrored. */
+        flip?: IFill.TileFlip;
+        /** Where the tiles are anchored in the shape. */
+        alignment?: RectAlignment;
+    }
+    /**
+     * An image fill: a workbook resource stretched over the shape or tiled across it.
+     *
+     * @remarks
+     * `resId` names the resource the way `IPicture.JSON.resId` names a placed picture's image 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 ImageProperties extends IFill.Properties {
+        type: typeof IFill.Type.Image;
+        /** The resource id of the image. */
+        resId?: number;
+        /** The part of the image used (`srcRect`), as insets from its edges. Absent for the whole image. */
+        sourceRect?: RectInsets;
         /**
-         * A reference to the image resource.
-         *
-         * @remarks
-         * This is a placeholder
+         * The image is stretched to a rectangle inset from the shape's bounds (`stretch/fillRect`);
+         * `{}` for the whole shape. Absent when the image is tiled.
          */
-        ref?: any;
+        stretch?: RectInsets;
+        /** The image is tiled (`tile`). Absent when it is stretched. */
+        tile?: ImageTileProperties;
         /**
-         * Indicates whether the image fill should be tiled.
-         */
-        tile?: boolean;
-        /**
-         * The resolution of the image in dots per inch (DPI).
+         * The resolution the image is rendered at, in dots per inch (`dpi`); `0` for the image's own.
          */
         dpi?: number;
+        /** The compression the image was stored for (`blip/@cstate`): `email`, `screen`, `print`, `hqprint`, `none`. */
+        compressionState?: string;
+        /** `blip/extLst` as the file states it: an opaque DrawingML fragment, written back as it was. */
+        extLst?: string;
     }
     interface ImageJSON extends ImageProperties {
     }
+    /**
+     * An image fill: a workbook resource stretched over the area or tiled across it.
+     *
+     * @remarks
+     * The image is a resource of the workbook, so the fill cannot be set from a color or a string;
+     * a shape takes one from a file or through its own picture operations. Setting a color on an
+     * image fill replaces it with a solid one.
+     */
+    interface IImage extends IFill {
+        /**
+         * Fill type is always {@link IFill.Type.Image}.
+         */
+        getType(): typeof IFill.Type.Image;
+        /**
+         * The image, when whatever holds the fill holds the resource; `null` when the fill names none
+         * or the holder cannot answer.
+         */
+        getResource(): IResource | null;
+        /**
+         * Whether the image repeats across the area rather than stretching over it.
+         */
+        isTiled(): boolean;
+        /**
+         * Converts the image fill to a JSON representation.
+         */
+        toJSON(): ImageJSON;
+    }
 }
 //# sourceMappingURL=IFill.d.ts.map