@sheetxl/sdk 0.7.26 → 0.7.28-beta.1

package/types/src/style/IStyle.d.ts

@@ -0,0 +1,485 @@
+import { Size, Rectangle } from '@sheetxl/utils';
+import { IProperties } from '../type';
+import { ITransaction } from '../transaction';
+import { ICellRange } from '../cellRange';
+import { IColor } from '../color';
+import { IFill } from '../fill';
+import { ITextFrame, IStyledFont } from '../text';
+import { IFont } from '../font';
+import { IBorder } from '../border';
+import { NumberFormat } from '../numFmt';
+/**
+ * The `IStyle` interface combines user-applied styles with dynamic styles, such as those from tables or conditional
+ * formatting, to deliver the current appearance.
+ */
+export interface IStyle {
+    /**
+     * Format used for Number formatting:
+     * * {@link https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1}
+     * * {@link https://customformats.com/}
+     *
+     * @remarks
+     * * If a number provided the builtIn numFmtId as defined in OOXML will be used.
+     * * {@link NumberFormat.Type}
+     */
+    getNumberFormat(): string;
+    /**
+     * @see {@link IStyle.getNumberFormat}
+     */
+    setNumberFormat(numFmt: string | null, options?: IStyle.UpdateOptions): IStyle;
+    /**
+     * A boolean value indicating whether the text string in a cell should be prefixed by a single quote mark (e.g., 'text).
+     * In these cases, the quote is not stored in the Shared Strings Part.
+     */
+    getQuotePrefix(): boolean;
+    /**
+     * @see {@link IStyle.getQuotePrefix}
+     */
+    setQuotePrefix(quotePrefix: boolean | null, options?: IStyle.UpdateOptions): IStyle;
+    /**
+     * Returns the border style.
+     */
+    getBorder(): IBorder;
+    /**
+     * Sets the border style.
+     *
+     * This method allows updating borders using an {@link IBorder} or a shorthand property object.
+     *
+     * @param border The border object or a shorthand property object to apply. Pass `null` to clear.
+     * @param options Optional configuration for the update.
+     * @returns The `IBorder` object for further modifications.
+     */
+    setBorder(border: IBorder.Update, options?: IStyle.UpdateOptions): IStyle;
+    /**
+     * Fill properties for the background.
+     */
+    getFill(): IFill.ISolid | IFill.IGradient | IFill.IPattern | IFill.INone;
+    /**
+     * Sets the fill style.
+     *
+     * This method allows updating fill using an {@link IFill} or a shorthand property object.
+     *
+     * @param fill The fill object or a shorthand property object to apply. Pass `null` to clear.
+     * @param options Optional configuration for the update.
+     * @returns The `IFill` object for further modifications.
+     */
+    setFill(fill: IFill.Update, options?: IStyle.UpdateOptions): IStyle;
+    /**
+     * Sets the fill style to a solid fill.
+     */
+    setFillSolid(options?: IStyle.UpdateOptions): IFill.ISolid;
+    /**
+     * Sets the fill style to a gradient fill.
+     */
+    setFillGradient(options?: IStyle.UpdateOptions): IFill.IGradient;
+    /**
+     * Sets the fill style to a pattern fill.
+     */
+    setFillPattern(options?: IStyle.UpdateOptions): IFill.IPattern;
+    /**
+     * Sets the fill style to no fill.
+     */
+    setFillNone(options?: IStyle.UpdateOptions): IFill.INone;
+    /**
+     * Returns the alignment for the style.
+     */
+    getAlignment(): ITextFrame.IAlignment;
+    /**
+     * Sets the alignment style.
+     *
+     * This method allows updating alignments using an {@link ITextFrame.IAlignment.Update} or a shorthand property object.
+     *
+     * @param alignment The alignment object or a shorthand property object to apply. Pass `null` to clear.
+     * @param options Optional configuration for the update.
+     * @returns The `ITextFrame.IAlignment` object for further modifications.
+     */
+    setAlignment(alignment: ITextFrame.IAlignment.Update, options?: IStyle.UpdateOptions): IStyle;
+    /**
+     * Returns the font for the style.
+     */
+    getFont(): IStyledFont;
+    /**
+     * Sets the font style.
+     *
+     * This method allows updating fill using an {@link IStyledFont} or a shorthand property object.
+     *
+     * @param font The font object or a shorthand property object to apply. Pass `null` to clear.
+     * @param options Optional configuration for the update.
+     * @returns The `IStyledFont` object for further modifications.
+     */
+    setFont(font: IStyledFont.Update, options?: IStyle.UpdateOptions): IStyle;
+    /**
+     * Returns an instance of the named style that this is derived from.
+     */
+    getNamed(): IStyle.INamed;
+    /**
+     * Sets the named style that this is derived from.
+     *
+     * @param named The named style to set.
+     */
+    setNamed(named: string | IStyle.INamed | null, options?: IStyle.UpdateOptions): IStyle;
+    /**
+     * Update many style properties at once.
+     *
+     * @param update The style updates.
+     * @param options Additional options for the update.
+     * @returns The `IStyle` for further modifications.
+     */
+    update(update: IStyle.Update, options?: IStyle.UpdateOptions): IStyle;
+    /**
+     * Clears all styling properties, resetting to default.
+     *
+     * @returns a reference to a normal style.
+     */
+    clear(): IStyle;
+    /**
+     * Measure the text using the styling properties
+     *
+     * @param text The text to measure.
+     * @param size Size @defaultValue 'to the cell font.size'
+     * @param family Family @defaultValue 'to the cell font.family'
+     * @param options Options for the measurement.
+     */
+    measureText(text: string, size?: number, family?: string, options?: IFont.MetricOptions): IFont.ExtendedMetrics;
+    /**
+     * Creates a simple text frame that can be used for rendering and/or measuring.
+     *
+     * @param text
+     * @param allowWrap If true then will try to wrap on natural breaks.
+     */
+    createTextFrame(text: string, allowWrap?: boolean): ITextFrame;
+    /**
+     * Returns the best fit size assuming no content.
+     */
+    getBestFit(): Partial<Size> | null;
+    /**
+     * Returns insets used for content. This does not taking into account indent because
+     * this is alignment and type specific.
+     */
+    getInsets(): Rectangle;
+    /**
+     * This is used to determine if the style has rendering
+     * artifacts even if there is no content. (For example borders or background)
+     */
+    hasVisibleStyling(): boolean;
+    /**
+     * Allows for a non managed style. Useful for tooltips or other transient styles.
+     *
+     * @param update Adjustments to the style.
+     */
+    createStyle(update: IStyle.Update): IStyle;
+    /**
+     * Returns `true` if the CellStyle is the normal style
+     */
+    isNormal(): boolean;
+    /**
+     * Returns a JSON representation of the style.
+     */
+    toJSON(): IStyle.JSON | null;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIStyle: true;
+}
+/**
+ * {@inheritDoc IStyle}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IStyle}
+ */
+export declare namespace IStyle {
+    /**
+     * The properties for IStyle.
+     */
+    interface Properties<C = IColor.Serializable> {
+        /**
+         * Font properties.
+         *
+         * @see
+         * {@link IStyle.getFont}
+         */
+        font?: IStyledFont.Properties<C>;
+        /**
+         * Fill properties.
+         *
+         * @see
+         * {@link IStyle.getFill}
+         */
+        fill?: C | IFill.SolidProperties<C> | IFill.GradientProperties<C> | IFill.PatternProperties<C> | IFill.NoneProperties;
+        /**
+         * Number Format properties.
+         *
+         * @see
+         * {@link IStyle.getNumberFormat()}
+         */
+        numberFormat?: string | NumberFormat.Type | number;
+        /**
+         * Alignment properties.
+         *
+         * @see
+         * {@link IStyle.getAlignment}
+         */
+        alignment?: ITextFrame.IAlignment.Properties;
+        /**
+         * Border properties.
+         *
+         * @see
+         * {@link IStyle.getBorder}
+         */
+        border?: IBorder.Properties;
+        /**
+         * Quote Prefix property.
+         *
+         * @see
+         * {@link IStyle.getQuotePrefix}
+         */
+        quotePrefix?: boolean;
+        /**
+         * Named style property.
+         *
+         * @see
+         * {@link IStyle.getNamed}
+         */
+        named?: IStyle.BuiltInName | string;
+        /**
+         * Custom indentation insets.
+         */
+        insets?: Partial<Rectangle>;
+    }
+    /**
+     * Enable properties to be set using string shorthands.
+     *
+     * @remarks
+     * The `font` slot is widened to {@link IStyledFont.Modifiers} rather than derived from
+     * {@link IStyle.Properties}, so that the font aliases (`bold`, `italic`) are accepted here but
+     * cannot reach the stored/serialized properties.
+     */
+    type Modifiers = Omit<IProperties.ResolvableProperties<IStyle.Properties>, 'font'> & {
+        /** {@inheritDoc IStyle.Properties.font} */
+        font?: IProperties.ResolvableProperties<IStyledFont.Modifiers> | string | null;
+    };
+    interface ModifierCallback {
+        (original: IStyle): IStyle.Modifiers;
+    }
+    /**
+     * Options for updating a style.
+     */
+    type Update = IStyle | IStyle.Modifiers | IStyle.ModifierCallback | null;
+    /**
+     * Options for Updates.
+     */
+    interface UpdateOptions extends ITransaction.OperationOptions {
+        /**
+         * Convenience method that calls autoFit after the setValues.
+         * @defaultValue `none` - No autofit.
+         *
+         * @remarks
+         * If set to `true` then autoFit will mimic the UI with the following options:
+    ```
+    {
+      skipCustomSize: true,
+      expandOnly: true,
+      minContent: true
+    }
+    ```
+         */
+        autoFit?: boolean | ICellRange.AutoFitOptions;
+    }
+    interface JSON extends Properties<string> {
+    }
+    /**
+     * Represents a named cell style that can be selected and applied across multiple cells.
+     * Named styles provide a convenient way to apply predefined or custom styling
+     * options available within the application's UI. Commonly used for both built-in
+     * and user-defined styles in spreadsheet applications.
+     */
+    interface INamed {
+        /**
+         * Returns the name for the style.
+         */
+        getName(): string;
+        /**
+         * Returns the style customizations.
+         */
+        getRanged(): IProperties.ICellRanged<IStyle.Properties>;
+        /**
+         * If 'true' do not show this style in the application UI.
+         */
+        isHidden(): boolean;
+        /**
+         * Specifies if this style is applied to outline levels in the application.
+         *
+         * @returns The outline level if this style applies to outlines, or `null`
+         * if it is not associated with any outline levels.
+         *
+         * @remarks
+         * * Outline styles allow automatic application of the style to cells at a
+         * specific outline level.
+         * * Returns `null` if outline does not affect styles.
+         * * This is only used for built-in styles RowLevel_# and ColLevel_#.
+         */
+        getILevel(): number | null;
+        /**
+         * Identifies the built-in ID for predefined styles, if applicable.
+         *
+         * @returns The built-in ID number if the style is a predefined one, or `null`
+         * if the style is custom.
+         */
+        getBuiltInID(): number | null;
+        /**
+         * Deletes the style.
+         *
+         * @remarks
+         * For built-in styles, this method will hide.
+         */
+        delete(): void;
+        /**
+         * For Persisting.
+         */
+        toJSON(): IStyle.NamedJSON;
+        /**
+         * For runtime type checking.
+         */
+        readonly isINamed: true;
+    }
+    /**
+     * Properties associated with an {@link INamed} style.
+     *
+     * @remarks
+     * Used for performing updates and saving to JSON.
+     */
+    interface NamedProperties<C = IColor.Serializable> {
+        /**
+         * @see
+         * {@link INamed.getName}
+         */
+        name: string;
+        /**
+         * @see
+         * {@link INamed.isHidden}
+         */
+        hidden?: boolean;
+        /**
+         * @see
+         * {@link INamed.getILevel}
+         */
+        iLevel?: number | null;
+        /**
+         * The cell style properties.
+         */
+        style: IStyle.Properties<C>;
+    }
+    /**
+     * For persisting.
+     */
+    interface NamedJSON extends NamedProperties<string> {
+    }
+    /**
+     * Extends the NamedProperties with the ability to use a callback on the style.
+     */
+    interface NamedUpdate extends Omit<IProperties.ResolvableProperties<NamedProperties>, 'style'> {
+        /**
+         * Allows for style modifications.
+         */
+        style: IStyle.Update;
+    }
+    /**
+     * List of BuiltIn CellStyles.
+     */
+    const BuiltInName: {
+        readonly Normal: "Normal";
+        readonly RowLevel: "RowLevel_#";
+        readonly ColLevel: "ColLevel_#";
+        readonly Comma: "Comma";
+        readonly Currency: "Currency";
+        readonly Percent: "Percent";
+        readonly Comma0: "Comma [0]";
+        readonly Currency0: "Currency [0]";
+        readonly Hyperlink: "Hyperlink";
+        readonly FollowedHyperlink: "Followed Hyperlink";
+        readonly Note: "Note";
+        readonly WarningText: "Warning Text";
+        readonly Unknown12: "??-12";
+        readonly Unknown13: "??-13";
+        readonly Unknown14: "??-14";
+        readonly Title: "Title";
+        readonly Heading1: "Heading 1";
+        readonly Heading2: "Heading 2";
+        readonly Heading3: "Heading 3";
+        readonly Heading4: "Heading 4";
+        readonly Input: "Input";
+        readonly Output: "Output";
+        readonly Calculation: "Calculation";
+        readonly CheckCell: "Check Cell";
+        readonly LinkedCell: "Linked Cell";
+        readonly Total: "Total";
+        readonly Good: "Good";
+        readonly Bad: "Bad";
+        readonly Neutral: "Neutral";
+        readonly Accent1: "Accent1";
+        readonly Accent1_20: "20% - Accent1";
+        readonly Accent1_40: "40% - Accent1";
+        readonly Accent1_60: "60% - Accent1";
+        readonly Accent2: "Accent2";
+        readonly Accent2_20: "20% - Accent2";
+        readonly Accent2_40: "40% - Accent2";
+        readonly Accent2_60: "60% - Accent2";
+        readonly Accent3: "Accent3";
+        readonly Accent3_20: "20% - Accent3";
+        readonly Accent3_40: "40% - Accent3";
+        readonly Accent3_60: "60% - Accent3";
+        readonly Accent4: "Accent4";
+        readonly Accent4_20: "20% - Accent4";
+        readonly Accent4_40: "40% - Accent4";
+        readonly Accent4_60: "60% - Accent4";
+        readonly Accent5: "Accent5";
+        readonly Accent5_20: "20% - Accent5";
+        readonly Accent5_40: "40% - Accent5";
+        readonly Accent5_60: "60% - Accent5";
+        readonly Accent6: "Accent6";
+        readonly Accent6_20: "20% - Accent6";
+        readonly Accent6_40: "40% - Accent6";
+        readonly Accent6_60: "60% - Accent6";
+        readonly ExplanatoryText: "Explanatory Text";
+    };
+    type BuiltInName = typeof BuiltInName[keyof typeof BuiltInName];
+    /**
+     * Canonical built-in style name for an ECMA-376 `builtinId` (its ordinal), or
+     * `undefined` for an unknown id.
+     *
+     * @remarks
+     * The identity of a built-in style is its `builtinId`, not the `name` string
+     * (which a file saves in the authoring language). Importers should resolve the
+     * id back to the canonical name so a `name="Standard" builtinId="0"` foreign
+     * file maps to {@link BuiltInName.Normal}.
+     */
+    function builtInNameFromId(id: number): BuiltInName | undefined;
+    /**
+     * BuiltIn IconSets used for conditional formatting.
+     */
+    const IconSet: {
+        readonly Arrows3: "3Arrows";
+        readonly ArrowsGray3: "3ArrowsGray";
+        readonly Flags3: "3Flags";
+        readonly Signs3: "3Signs";
+        readonly Symbols3: "3Symbols";
+        readonly Symbols3_2: "3Symbols2";
+        readonly TrafficLights3: "3TrafficLights1";
+        readonly TrafficLights3_2: "3TrafficLights2";
+        readonly Triangles3: "3Triangles";
+        readonly Stars3: "3Stars";
+        readonly Arrows4: "4Arrows";
+        readonly ArrowsGray4: "4ArrowsGray";
+        readonly Rating4: "4Rating";
+        readonly RedToBlack4: "4RedToBlack";
+        readonly TrafficLights4: "4TrafficLights";
+        readonly Arrows5: "5Arrows";
+        readonly ArrowsGray5: "5ArrowsGray";
+        readonly Quarters5: "5Quarters";
+        readonly Rating5: "5Rating";
+        readonly Boxes5: "5Boxes";
+    };
+    type IconSet = typeof IconSet[keyof typeof IconSet];
+}
+//# sourceMappingURL=IStyle.d.ts.map