@sheetxl/sdk 0.7.27 → 0.7.28-beta.2

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

@@ -0,0 +1,597 @@
+import { Properties as CSSProperties } from 'csstype';
+import { Rectangle, Size } from '@sheetxl/utils';
+import { IColor } from '../color';
+import { IStyle } from '../style';
+/**
+ * Defines how an area or shape is filled with color or a pattern.
+ */
+export interface IFill {
+    /**
+     * Returns the type of fill used.
+     */
+    getType(): IFill.Type;
+    /**
+     * Set the fill color.
+     *
+     * @param color The color to set for the fill.
+     *
+     * @remarks
+     * 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;
+    /**
+     * Returns the fill color.
+     */
+    getColor(): IColor | null;
+    /**
+     * Returns the fill as a set of css string that are suitable for css.
+     *
+     * @param mode The color rendering mode (see {@link IColor.CSSMode}): a boolean bakes that mode;
+     * `'adaptive'` emits `light-dark()` so a light/dark flip needs no re-render. (Pattern fills bake
+     * their SVG data-URI body regardless — a data-URI never sees the host `color-scheme`.)
+     * @param size Indicates the size of the area being filled.
+     *
+     * @remarks
+     * Size is used for determining the scaling or tiling of the fill within the specified area.
+     * (e.g. Scaled Gradient Fill).
+     */
+    toCSS(mode?: IColor.CSSMode, size?: Size): CSSProperties;
+    /**
+     * Returns `true` if the fill has any visible styling
+     */
+    hasVisibleStyling(): boolean;
+    /**
+     * Returns `true` if the fill is equal to the other fill.
+     */
+    isEqual(other: IFill | null): boolean;
+    /**
+     * Returns the fill as a JSON object.
+     */
+    toJSON(): IFill.JSON;
+    /**
+     * For type checking.
+     */
+    readonly isIFill: true;
+}
+/**
+ * {@inheritDoc IFill}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IFill}
+ */
+export declare namespace IFill {
+    /**
+     * Types of fill styles used for painting surfaces.
+     */
+    const Type: {
+        /**
+         * No fill.
+         */
+        readonly None: "none";
+        /**
+         * A solid color.
+         */
+        readonly Solid: "solid";
+        /**
+         * A gradient
+         */
+        readonly Gradient: "gradient";
+        /**
+         * A pattern.
+         */
+        readonly Pattern: "pattern";
+        /**
+         * An Image.
+         * @remarks
+         * * Not support in cells. This is currently only support in drawML (charts, shapes, powerpoint).
+         */
+        readonly Image: "pattern";
+        /**
+         * An Image.
+         * @remarks
+         * * Not support in cells. This is currently only support in drawML (charts, shapes, powerpoint).
+         */
+        readonly Background: "background";
+        /**
+         * Inherit the fill from the group.
+         * @remarks
+         * * This has no effect if not in a group.
+         * * Not support in cells. This is currently only support in drawML (charts, shapes, powerpoint).
+         */
+        readonly Group: "group";
+        /**
+         * For allowing custom types.
+         * @remarks
+         * Placeholder and not yet implemented. This will have a function callback.
+         */
+        readonly Custom: "custom";
+    };
+    type Type = typeof Type[keyof typeof Type];
+    /**
+     * Represents the types of gradients that can be applied to shapes or other elements.
+     */
+    const GradientType: {
+        /**
+         * A linear gradient, where colors transition along a straight line.
+         */
+        readonly Linear: "linear";
+        /**
+         * A path-based gradient, where colors transition along a defined path.
+         *
+         * @remarks
+         * * Currently not directly supported by the rendering engine.
+         */
+        readonly Path: "path";
+        /**
+         * A rectangular gradient, where colors transition within a rectangular shape.
+         *
+         * @remarks
+         * Not supported by Excel or SheetXL rendering engine.
+         */
+        readonly Rect: "rect";
+        /**
+         * A shape gradient, where colors transition based on the shape of the filled area.
+         */
+        readonly Shape: "shape";
+    };
+    type GradientType = typeof GradientType[keyof typeof GradientType];
+    /**
+     * Specifies how a tile is mirrored or flipped when filling a shape or container.
+     */
+    const TileMirror: {
+        /**
+         * No mirroring is applied.
+         */
+        readonly None: "none";
+        /**
+         * The tile is mirrored vertically (flipped along the y-axis).
+         */
+        readonly Vertical: "v";
+        /**
+         * The tile is mirrored horizontally (flipped along the x-axis).
+         */
+        readonly Horizontal: "h";
+        /**
+         * The tile is mirrored both vertically and horizontally.
+         */
+        readonly Both: "b";
+    };
+    type TileMirror = typeof TileMirror[keyof typeof TileMirror];
+    /**
+     * Contains the built-in pattern types.
+     *
+     * @remarks
+     * **TODO** - Rationalize with full drawML list.
+     */
+    const BuiltInSheetPattern: {
+        /**
+         * 'None' style
+         *
+         * @remarks
+         * Acts like a none fill
+         */
+        readonly None: "none";
+        /**
+         * 'None' style
+         *
+         * @remarks
+         * Acts like a solid fill
+         */
+        readonly Solid: "solid";
+        /**
+         * 'Dark Gary' style
+         */
+        readonly DarkGray: "darkGray";
+        /**
+         * 'Medium Gray' style
+         */
+        readonly MediumGray: "mediumGray";
+        /**
+         * 'Light Gray' style
+         */
+        readonly LightGray: "lightGray";
+        /**
+         * 'Gray 0.0625' style
+         */
+        readonly Gray0625: "gray0625";
+        /**
+         * 'Gray 0.125' style
+         */
+        readonly Gray125: "gray125";
+        /**
+         * 'Dark Horizontal' style
+         */
+        readonly DarkHorizontal: "darkHorizontal";
+        /**
+         * 'Dark Vertical' style
+         */
+        readonly DarkVertical: "darkVertical";
+        /**
+         * 'Dark Down' style
+         */
+        readonly DarkDown: "darkDown";
+        /**
+         * 'Dark Up' style
+         */
+        readonly DarkUp: "darkUp";
+        /**
+         * 'Dark Grid' style
+         */
+        readonly DarkGrid: "darkGrid";
+        /**
+         * 'Dark Trellis' style
+         */
+        readonly DarkTrellis: "darkTrellis";
+        /**
+         * 'Light Horizontal' style
+         */
+        readonly LightHorizontal: "lightHorizontal";
+        /**
+         * 'Light Vertical' style
+         */
+        readonly LightVertical: "lightVertical";
+        /**
+         * 'Light Down' style
+         */
+        readonly LightDown: "lightDown";
+        /**
+         * 'Light Up' style
+         */
+        readonly LightUp: "lightUp";
+        /**
+         * 'Light Grid' style
+         */
+        readonly LightGrid: "lightGrid";
+        /**
+         * 'Light Trellis' style
+         */
+        readonly LightTrellis: "lightTrellis";
+        /**
+         * 'Custom' style
+         * @remarks
+         * Then a pattern must be provided.
+         *
+         * **Not yet implemented**
+         */
+        readonly Custom: "custom";
+    };
+    type BuiltInSheetPattern = typeof BuiltInSheetPattern[keyof typeof BuiltInSheetPattern];
+    interface Properties {
+        /**
+         * @see
+         * {@link IFill.getType}
+         */
+        type: IFill.Type;
+        isRotatedWithShape?: boolean;
+    }
+    /**
+     * Modifiers describe a partial list of properties that can be set with values or shorthand strings.
+     */
+    type Modifiers = Partial<IFill.Properties>;
+    /**
+     * Options for updating a fill.
+     */
+    type Update = IFill | Modifiers | string | null;
+    /**
+     * A JSON representation useful for persistence.
+     */
+    interface JSON extends Properties {
+    }
+    /**
+     * No fill is applied; the area is transparent.
+     */
+    interface INone extends IFill {
+        /**
+         * Fill type is always {@link IFill.Type.None}.
+         */
+        getType(): typeof IFill.Type.None;
+        toJSON(): NoneJSON;
+    }
+    interface NoneProperties extends IFill.Properties {
+        /**
+         * @see
+         * {@link IFill.ISolid.getColor}
+         */
+        type: typeof IFill.Type.None;
+    }
+    interface NoneJSON extends NoneProperties {
+    }
+    /**
+     * A single color fill.
+     */
+    interface ISolid extends IFill {
+        /**
+         * Fill type is always {@link IFill.Type.Solid}.
+         */
+        getType(): typeof IFill.Type.Solid;
+        /**
+         * Returns the color of the fill.
+         */
+        getColor(): IColor;
+        /**
+         * Sets the stroke color.
+         *
+         * @param color The stroke color.
+         */
+        setColor(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IFill.ISolid;
+    }
+    interface SolidProperties<C = IColor.Serializable> extends IFill.Properties {
+        /**
+         * @see
+         * {@link IFill.ISolid.getColor}
+         */
+        color: C;
+        /**
+         * @see
+         * {@link IFill.ISolid.getType}
+         */
+        type: typeof IFill.Type.Solid;
+    }
+    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
+         * {@link IFill.IGradientStop.getOffset}
+         */
+        offset?: number;
+        /**
+         * @see
+         * {@link IFill.IGradientStop.getColor}
+         */
+        color: C;
+    }
+    /**
+     * Indicates a color change occurs.
+     */
+    interface IGradientStop {
+        /**
+         * If not specified then the offsets will be equally weighted based off of the number of stops.
+         */
+        getOffset(): number;
+        /**
+         * The color of the stop.
+         */
+        getColor(): IColor;
+    }
+    interface GradientProperties<C = IColor.Serializable> extends IFill.Properties {
+        /**
+         * @see
+         * {@link IFill.IGradient.getType}
+         */
+        type: typeof IFill.Type.Gradient;
+        /**
+         * @see
+         * {@link IFill.IGradient.getStops}
+         */
+        stops?: (GradientStopProperties<C> | C)[];
+        /**
+         * @see
+         * {@link IFill.IGradient.getGradientType}
+         */
+        gradientType?: IFill.GradientType;
+        /**
+         * @see
+         * {@link IFill.IGradient.getAngle}
+         */
+        angle?: number;
+        /**
+         * @see
+         * {@link IFill.IGradient.getFocus}
+         */
+        focus?: Rectangle;
+    }
+    /**
+     * A gradient fill, where colors transition across the area.
+     */
+    interface IGradient extends IFill {
+        /**
+         * Fill type is always {@link IFill.Type.Gradient}.
+         */
+        getType(): typeof IFill.Type.Gradient;
+        /**
+         * The stops for the gradient.
+         *
+         * @remarks
+         * * This must be at least two stops.
+         */
+        getStops(): IGradientStop[];
+        /**
+         * Sets the gradient stops.
+         *
+         * @param stops The gradient stops.
+         */
+        setStops(stops: (IGradientStop | IColor.Serializable | null)[], options?: IStyle.UpdateOptions): IFill.IGradient;
+        /**
+         * The type of gradient.
+         * @defaultValue GradientType.Linear
+         */
+        getGradientType(): IFill.GradientType;
+        /**
+         * Sets the gradient type.
+         *
+         * @param type The gradient type.
+         */
+        setGradientType(type: IFill.GradientType | null, options?: IStyle.UpdateOptions): IFill.IGradient;
+        /**
+         * The angle of the gradient in degrees if gradient type is linear.
+         */
+        getAngle(): number;
+        /**
+         * Sets the rotation
+         *
+         * @param angle The angle
+         */
+        setAngle(angle: number | null, options?: IStyle.UpdateOptions): IFill.IGradient;
+        /**
+         * Used for path and circular gradients.
+         */
+        getFocus(): Rectangle;
+        /**
+         * Sets the focus area for the gradient.
+         *
+         * @param focus The fill area.
+         *
+         * @remarks
+         * * 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;
+        /**
+         * Converts the gradient fill to a JSON representation.
+         */
+        toJSON(): GradientJSON;
+    }
+    interface GradientJSON extends GradientProperties<string> {
+    }
+    /**
+     * A pattern fill, using a repeating pattern to fill the area.
+     */
+    interface IPattern extends IFill {
+        /**
+         * Fill type is always {@link IFill.Type.Pattern}.
+         */
+        getType(): typeof IFill.Type.Pattern;
+        /**
+         * The foreground color for the pattern.
+         */
+        getForeground(): IColor;
+        /**
+         * Sets the foreground color.
+         *
+         * @param color The foreground color.
+         */
+        setForeground(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IFill.IPattern;
+        /**
+         * The background color for the pattern.
+         */
+        getBackground(): IColor;
+        /**
+         * Sets the background color.
+         *
+         * @param color The background color.
+         */
+        setBackground(color: IColor.Serializable | null, options?: IStyle.UpdateOptions): IFill.IPattern;
+        /**
+         * The type of pattern used.
+         */
+        getPatternType(): IFill.BuiltInSheetPattern;
+        /**
+         * Sets the pattern type.
+         *
+         * @param type The pattern type.
+         */
+        setPatternType(type: IFill.BuiltInSheetPattern | null, options?: IStyle.UpdateOptions): 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
+         * {@link IFill.toCSS} (whose pattern body bakes colors into an SVG data-URI), both colors here
+         * are ordinary live CSS values, so `'adaptive'` (`light-dark()`) and `var()` resolve in place —
+         * a light/dark flip needs no re-render.
+         *
+         * Render `marks` as a child box exactly filling the `base` element (a CSS mask clips the
+         * element it is set on, so the two colors require two elements).
+         *
+         * @param mode The color rendering mode (see {@link IColor.CSSMode}).
+         * @returns The layer pair, or `null` when the pattern is `None`/`Solid` (no marks layer —
+         * render single-element via {@link IFill.toCSS}).
+         */
+        toCSSMask(mode?: IColor.CSSMode): {
+            base: CSSProperties;
+            marks: CSSProperties;
+        } | null;
+        /**
+         * Converts the pattern fill to a JSON representation.
+         */
+        toJSON(): PatternJSON;
+    }
+    interface PatternProperties<C = IColor.Serializable> extends IFill.Properties {
+        /**
+         * @see
+         * {@link IFill.IPattern.getType}
+         */
+        type: typeof IFill.Type.Pattern;
+        /**
+         * @see
+         * {@link IFill.IPattern.getForeground}
+         */
+        foreground?: C;
+        /**
+         * @see
+         * {@link IFill.IPattern.getBackground}
+         */
+        background?: C;
+        /**
+         * @see
+         * {@link IFill.IPattern.getPatternType}
+         */
+        patternType?: IFill.BuiltInSheetPattern;
+    }
+    interface PatternJSON extends PatternProperties<string> {
+    }
+    interface ImageProperties extends IFill.Properties {
+        /**
+         * A reference to the image resource.
+         *
+         * @remarks
+         * This is a placeholder
+         */
+        ref?: any;
+        /**
+         * Indicates whether the image fill should be tiled.
+         */
+        tile?: boolean;
+        /**
+         * The resolution of the image in dots per inch (DPI).
+         */
+        dpi?: number;
+    }
+    interface ImageJSON extends ImageProperties {
+    }
+}
+//# sourceMappingURL=IFill.d.ts.map