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

package/types/src/slicer/index.d.ts

@@ -1,2 +1,3 @@
 export * from './ISlicer';
+export * from './ISlicerStyle';
 //# sourceMappingURL=index.d.ts.map

package/types/src/sort/ISort.d.ts

@@ -1,5 +1,5 @@
 import { ScalarType, Scalar, IRange } from '@sheetxl/primitives';
-import { IStyle } from '../style';
+import { ICellStyle } from '../style';
 import { ICellRange } from '../cellRange';
 /**
  * A stateful sort object that binds criteria to a specific index within an `ITable`.
@@ -64,6 +64,8 @@ export interface ISort {
      * Clears the sort criteria and removes from sort levels.
      */
     delete(): void;
+    /** For runtime type checking. */
+    readonly isISort: true;
 }
 /**
  * Types used for sorting.
@@ -163,7 +165,7 @@ export declare namespace ISort {
          * @remarks
          * **PLACEHOLDER** - This is a placeholder for future use.
          */
-        iconSet?: IStyle.IconSet;
+        iconSet?: ICellStyle.IconSet;
         /**
          * Used with sortOn === Icon
          * @remarks
@@ -171,12 +173,10 @@ export declare namespace ISort {
          */
         iconId?: number;
         /**
-         * Used with sortOn === cellColor or fontColor
-         *
-         * @remarks
-         * **PLACEHOLDER** - This is a placeholder for future use.
+         * The format whose color sorts first, with `sortOn` {@link ISort.SortOn.FillColor} (its fill)
+         * or {@link ISort.SortOn.FontColor} (its font color).
          */
-        dxfId?: any;
+        style?: ICellStyle.Properties;
         /**
          * Sort by a custom list.
          * @remarks
@@ -313,6 +313,38 @@ export declare namespace ISort {
          * @defaultValue false
          */
         includeHidden?: boolean;
+        /**
+         * The ranges the last sort in the file covered, kept so a saved workbook says what it was
+         * read with.
+         *
+         * @remarks
+         * Excel records the range it last sorted, which need not be the table's or filter's range: it
+         * may leave out the header or run past the last row. A sort made through the model sorts the
+         * table body and clears this.
+         */
+        extent?: ISort.SortExtent;
     };
+    /**
+     * A range given by how far each of its edges sits from the edges of the table or filter range,
+     * so it moves with that range. Positive is down or right.
+     */
+    interface Extent {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    }
+    /**
+     * The ranges of a sort as a file records them.
+     */
+    interface SortExtent {
+        /** The range the sort covered. */
+        range: ISort.Extent;
+        /**
+         * Each level's range, in the order of {@link JSON.sorts}. `null` for a level that uses its
+         * column of {@link range}.
+         */
+        sorts?: (ISort.Extent | null)[];
+    }
 }
 //# sourceMappingURL=ISort.d.ts.map

package/types/src/string/IStringCollection.d.ts

@@ -1,6 +1,9 @@
 import { ICollection } from '../type';
 /**
  * Contains a collection of interned strings.
+ *
+ * @remarks
+ * Keyed by the string's id, not ordered: iteration order is unspecified.
  */
 export interface IStringCollection extends ICollection<string>, ICollection.IPersistable {
     /**
@@ -30,6 +33,8 @@ export interface IStringCollection extends ICollection<string>, ICollection.IPer
     getById(id: number): string | null;
     /** {@inheritDoc ICollection.IPersistScope} */
     beginPersist(): ICollection.IPersistScope<IStringCollection.JSON>;
+    /** For runtime type checking. */
+    readonly isIStringCollection: true;
 }
 /**
  * {@inheritDoc IStringCollection}

package/types/src/string/StringCollection.d.ts

@@ -1,6 +1,6 @@
-import { ICollection } from '../type';
+import { ICollection, AbstractCollection } from '../type';
 import { IStringCollection } from './IStringCollection';
-export declare class StringCollection implements IStringCollection {
+export declare class StringCollection extends AbstractCollection<string, IStringCollection.GetItemsOptions> implements IStringCollection {
     private _persistOpen;
     private _stringsByText;
     private _stringsById;
@@ -12,15 +12,15 @@ export declare class StringCollection implements IStringCollection {
     addMultiple(shared: string[], conflateDuplicates?: boolean): void;
     /** {@inheritDoc IStringCollection.add} */
     add(shared: string): number;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<string>;
-    /** {@inheritDoc IStringCollection.getItems} */
-    getItems(options?: IStringCollection.GetItemsOptions): string[];
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IStringCollection.GetItemsOptions): string[];
     /** {@inheritDoc IStringCollection.getById} */
     getById(id: number): string | null;
     /** {@inheritDoc ICollection.getCount} */
     getCount(): number;
     /** {@inheritDoc ICollection.IPersistable.beginPersist} */
     beginPersist(): ICollection.IPersistScope<IStringCollection.JSON>;
+    /** {@inheritDoc IStringCollection.isIStringCollection} */
+    get isIStringCollection(): true;
 }
 //# sourceMappingURL=StringCollection.d.ts.map

package/types/src/style/{IStyle.d.ts → ICellStyle.d.ts}

@@ -3,16 +3,17 @@ 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 { IFill, IFillable } from '../fill';
+import { ITextFrame } from '../text';
+import { IFont, IFontStyle } from '../font';
+import { IBorders } from '../border';
+import { ICellProtection } from '../cell';
 import { NumberFormat } from '../numFmt';
 /**
- * The `IStyle` interface combines user-applied styles with dynamic styles, such as those from tables or conditional
+ * The `ICellStyle` interface combines user-applied styles with dynamic styles, such as those from tables or conditional
  * formatting, to deliver the current appearance.
  */
-export interface IStyle {
+export interface ICellStyle extends IFillable<ICellStyle, IFill.ISolid | IFill.IGradient | IFill.IPattern | IFill.INone, ICellStyle.UpdateOptions> {
     /**
      * Format used for Number formatting:
      * * {@link https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1}
@@ -24,62 +25,44 @@ export interface IStyle {
      */
     getNumberFormat(): string;
     /**
-     * @see {@link IStyle.getNumberFormat}
+     * @see {@link ICellStyle.getNumberFormat}
      */
-    setNumberFormat(numFmt: string | null, options?: IStyle.UpdateOptions): IStyle;
+    setNumberFormat(numFmt: string | null, options?: ICellStyle.UpdateOptions): ICellStyle;
     /**
      * 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}
+     * @see {@link ICellStyle.getQuotePrefix}
      */
-    setQuotePrefix(quotePrefix: boolean | null, options?: IStyle.UpdateOptions): IStyle;
+    setQuotePrefix(quotePrefix: boolean | null, options?: ICellStyle.UpdateOptions): ICellStyle;
     /**
-     * Returns the border style.
+     * Returns the protection format: whether the cell stays editable, and whether it shows its
+     * formula, while its sheet is protected.
      */
-    getBorder(): IBorder;
+    getProtection(): ICellProtection;
     /**
-     * Sets the border style.
+     * Sets the protection format.
      *
-     * 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 protection The protection or a partial 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;
+    setProtection(protection: ICellProtection.Update, options?: ICellStyle.UpdateOptions): ICellStyle;
     /**
-     * Fill properties for the background.
+     * Returns the borders.
      */
-    getFill(): IFill.ISolid | IFill.IGradient | IFill.IPattern | IFill.INone;
+    getBorders(): IBorders;
     /**
-     * Sets the fill style.
+     * Sets the borders.
      *
-     * This method allows updating fill using an {@link IFill} or a shorthand property object.
+     * This method allows updating borders using an {@link IBorders} or a shorthand property object.
      *
-     * @param fill The fill object or a shorthand property object to apply. Pass `null` to clear.
+     * @param borders The borders 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.
+     * @returns The `IBorders` object for further modifications.
      */
-    setFillNone(options?: IStyle.UpdateOptions): IFill.INone;
+    setBorders(borders: IBorders.Update, options?: ICellStyle.UpdateOptions): ICellStyle;
     /**
      * Returns the alignment for the style.
      */
@@ -93,45 +76,74 @@ export interface IStyle {
      * @param options Optional configuration for the update.
      * @returns The `ITextFrame.IAlignment` object for further modifications.
      */
-    setAlignment(alignment: ITextFrame.IAlignment.Update, options?: IStyle.UpdateOptions): IStyle;
+    setAlignment(alignment: ITextFrame.IAlignment.Update, options?: ICellStyle.UpdateOptions): ICellStyle;
     /**
-     * Returns the font for the style.
+     * Exists to have api parity with Office Scripts. Returns the SheetXL value (`'center'`), not
+     * Office Scripts' capitalized name, so what is read can be passed straight back to a setter.
+     *
+     * @deprecated Use {@link getAlignment}`().getHorizontal()`.
+     * @hidden
+     */
+    getHorizontalAlignment(): ITextFrame.HorizontalAlignment;
+    /**
+     * Exists to have api parity with Office Scripts. Returns the SheetXL value (`'top'`), not
+     * Office Scripts' capitalized name, so what is read can be passed straight back to a setter.
+     *
+     * @deprecated Use {@link getAlignment}`().getVertical()`.
+     * @hidden
      */
-    getFont(): IStyledFont;
+    getVerticalAlignment(): ITextFrame.VerticalAlignment;
     /**
-     * Sets the font style.
+     * Exists to have api parity with Office Scripts, whose capitalized names (`'Center'`) are accepted.
      *
-     * This method allows updating fill using an {@link IStyledFont} or a shorthand property object.
+     * @deprecated Use {@link setAlignment}`({ horizontal: 'center' })`.
+     * @hidden
+     */
+    setHorizontalAlignment(horizontal: ITextFrame.HorizontalAlignment | string): ICellStyle;
+    /**
+     * Exists to have api parity with Office Scripts, whose capitalized names (`'Top'`) are accepted.
      *
-     * @param font The font object or a shorthand property object to apply. Pass `null` to clear.
+     * @deprecated Use {@link setAlignment}`({ vertical: 'top' })`.
+     * @hidden
+     */
+    setVerticalAlignment(vertical: ITextFrame.VerticalAlignment | string): ICellStyle;
+    /**
+     * Returns the font for the style.
+     */
+    getFont(): IFontStyle;
+    /**
+     * Sets the font.
+     *
+     * @param font Another text style, its properties, or a CSS font shorthand (`'bold 12pt Arial'`).
+     * Pass `null` to clear.
      * @param options Optional configuration for the update.
-     * @returns The `IStyledFont` object for further modifications.
+     * @returns The updated style.
      */
-    setFont(font: IStyledFont.Update, options?: IStyle.UpdateOptions): IStyle;
+    setFont(font: IFontStyle | IFontStyle.Update | string | null, options?: ICellStyle.UpdateOptions): ICellStyle;
     /**
      * Returns an instance of the named style that this is derived from.
      */
-    getNamed(): IStyle.INamed;
+    getNamed(): ICellStyle.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;
+    setNamed(named: string | ICellStyle.INamed | null, options?: ICellStyle.UpdateOptions): ICellStyle;
     /**
      * Update many style properties at once.
      *
      * @param update The style updates.
      * @param options Additional options for the update.
-     * @returns The `IStyle` for further modifications.
+     * @returns The `ICellStyle` for further modifications.
      */
-    update(update: IStyle.Update, options?: IStyle.UpdateOptions): IStyle;
+    update(update: ICellStyle.Update, options?: ICellStyle.UpdateOptions): ICellStyle;
     /**
      * Clears all styling properties, resetting to default.
      *
      * @returns a reference to a normal style.
      */
-    clear(): IStyle;
+    clear(): ICellStyle;
     /**
      * Measure the text using the styling properties
      *
@@ -153,8 +165,9 @@ export interface IStyle {
      */
     getBestFit(): Partial<Size> | null;
     /**
-     * Returns insets used for content. This does not taking into account indent because
-     * this is alignment and type specific.
+     * Returns the insets content is laid out inside: Excel's, a quarter of the font's widest digit
+     * a side (2 px at Calibri 11) and 1 px above and below. Indent is not included because it
+     * depends on the alignment and the value's type.
      */
     getInsets(): Rectangle;
     /**
@@ -167,7 +180,7 @@ export interface IStyle {
      *
      * @param update Adjustments to the style.
      */
-    createStyle(update: IStyle.Update): IStyle;
+    createStyle(update: ICellStyle.Update): ICellStyle;
     /**
      * Returns `true` if the CellStyle is the normal style
      */
@@ -175,73 +188,80 @@ export interface IStyle {
     /**
      * Returns a JSON representation of the style.
      */
-    toJSON(): IStyle.JSON | null;
+    toJSON(): ICellStyle.JSON | null;
     /**
      * For runtime type checking.
      */
-    readonly isIStyle: true;
+    readonly isICellStyle: true;
 }
 /**
- * {@inheritDoc IStyle}
+ * {@inheritDoc ICellStyle}
  * @see
  * ### **Interface**
  *
- * {@link IStyle}
+ * {@link ICellStyle}
  */
-export declare namespace IStyle {
+export declare namespace ICellStyle {
     /**
-     * The properties for IStyle.
+     * The properties for ICellStyle.
      */
     interface Properties<C = IColor.Serializable> {
         /**
          * Font properties.
          *
          * @see
-         * {@link IStyle.getFont}
+         * {@link ICellStyle.getFont}
          */
-        font?: IStyledFont.Properties<C>;
+        font?: IFontStyle.Properties<C>;
         /**
          * Fill properties.
          *
          * @see
-         * {@link IStyle.getFill}
+         * {@link ICellStyle.getFill}
          */
         fill?: C | IFill.SolidProperties<C> | IFill.GradientProperties<C> | IFill.PatternProperties<C> | IFill.NoneProperties;
         /**
          * Number Format properties.
          *
          * @see
-         * {@link IStyle.getNumberFormat()}
+         * {@link ICellStyle.getNumberFormat()}
          */
         numberFormat?: string | NumberFormat.Type | number;
         /**
          * Alignment properties.
          *
          * @see
-         * {@link IStyle.getAlignment}
+         * {@link ICellStyle.getAlignment}
          */
         alignment?: ITextFrame.IAlignment.Properties;
         /**
          * Border properties.
          *
          * @see
-         * {@link IStyle.getBorder}
+         * {@link ICellStyle.getBorders}
          */
-        border?: IBorder.Properties;
+        borders?: IBorders.Properties;
         /**
          * Quote Prefix property.
          *
          * @see
-         * {@link IStyle.getQuotePrefix}
+         * {@link ICellStyle.getQuotePrefix}
          */
         quotePrefix?: boolean;
+        /**
+         * Protection properties.
+         *
+         * @see
+         * {@link ICellStyle.getProtection}
+         */
+        protection?: ICellProtection.Properties;
         /**
          * Named style property.
          *
          * @see
-         * {@link IStyle.getNamed}
+         * {@link ICellStyle.getNamed}
          */
-        named?: IStyle.BuiltInName | string;
+        named?: ICellStyle.BuiltInName | string;
         /**
          * Custom indentation insets.
          */
@@ -251,21 +271,21 @@ export declare namespace IStyle {
      * 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
+     * The `font` slot is widened to {@link IFontStyle.Update} rather than derived from
+     * {@link ICellStyle.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;
+    type Modifiers = Omit<IProperties.ResolvableProperties<ICellStyle.Properties>, 'font'> & {
+        /** {@inheritDoc ICellStyle.Properties.font} */
+        font?: IProperties.ResolvableProperties<IFontStyle.Update> | string | null;
     };
     interface ModifierCallback {
-        (original: IStyle): IStyle.Modifiers;
+        (original: ICellStyle): ICellStyle.Modifiers;
     }
     /**
      * Options for updating a style.
      */
-    type Update = IStyle | IStyle.Modifiers | IStyle.ModifierCallback | null;
+    type Update = ICellStyle | ICellStyle.Modifiers | ICellStyle.ModifierCallback | null;
     /**
      * Options for Updates.
      */
@@ -302,7 +322,7 @@ export declare namespace IStyle {
         /**
          * Returns the style customizations.
          */
-        getRanged(): IProperties.ICellRanged<IStyle.Properties>;
+        getRanged(): IProperties.ICellRanged<ICellStyle.Properties>;
         /**
          * If 'true' do not show this style in the application UI.
          */
@@ -327,6 +347,13 @@ export declare namespace IStyle {
          * if the style is custom.
          */
         getBuiltInID(): number | null;
+        /**
+         * Whether this built-in style's definition has been changed from the predefined one.
+         *
+         * @remarks
+         * Always `false` for a style that is not built in.
+         */
+        isCustomized(): boolean;
         /**
          * Deletes the style.
          *
@@ -337,7 +364,7 @@ export declare namespace IStyle {
         /**
          * For Persisting.
          */
-        toJSON(): IStyle.NamedJSON;
+        toJSON(): ICellStyle.NamedJSON;
         /**
          * For runtime type checking.
          */
@@ -365,10 +392,15 @@ export declare namespace IStyle {
          * {@link INamed.getILevel}
          */
         iLevel?: number | null;
+        /**
+         * @see
+         * {@link INamed.isCustomized}
+         */
+        customized?: boolean;
         /**
          * The cell style properties.
          */
-        style: IStyle.Properties<C>;
+        style: ICellStyle.Properties<C>;
     }
     /**
      * For persisting.
@@ -382,7 +414,7 @@ export declare namespace IStyle {
         /**
          * Allows for style modifications.
          */
-        style: IStyle.Update;
+        style: ICellStyle.Update;
     }
     /**
      * List of BuiltIn CellStyles.
@@ -487,4 +519,4 @@ export declare namespace IStyle {
     };
     type IconSet = typeof IconSet[keyof typeof IconSet];
 }
-//# sourceMappingURL=IStyle.d.ts.map
+//# sourceMappingURL=ICellStyle.d.ts.map

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

@@ -0,0 +1,72 @@
+import { ICollection } from '../type';
+import { IThemeCollection } from '../theme';
+import { ICellStyle } from './ICellStyle';
+/**
+ * The named cell styles of a workbook — the built-ins (`Normal`, `Heading 1`, `Good`, ...) and
+ * the ones the document defines.
+ *
+ * @remarks
+ * Office Scripts calls these predefined cell styles (`Workbook.getPredefinedCellStyles()`).
+ *
+ * Order is the gallery's: the built-ins in their definition order, each replaced in place by a
+ * custom style of the same name, then the document's own styles by name. A hidden style is
+ * left out unless asked for — see {@link INamedStyleCollection.GetItemsOptions.includeHidden}.
+ *
+ * Reached from {@link IStyleCollection.getNamedStyles}.
+ */
+export interface INamedStyleCollection extends ICollection<ICellStyle.INamed> {
+    /**
+     * Returns the style with the given name, or `null` if there is none.
+     *
+     * @param name The name, compared case-insensitively.
+     *
+     * @remarks
+     * A custom style of a built-in's name replaces the built-in, and is what is returned.
+     */
+    getByName(name: string): ICellStyle.INamed | null;
+    /**
+     * Adds or updates a style.
+     *
+     * @param update The name, the style, and any of the other {@link ICellStyle.NamedProperties}.
+     * @param mergeIfExists If `true` the style is merged over the existing one of that name;
+     * otherwise it replaces it. @defaultValue `false`
+     * @returns The style as stored.
+     *
+     * @remarks
+     * Names are case-insensitive. Setting a built-in's name customizes the built-in.
+     */
+    set(update: ICellStyle.NamedUpdate, mergeIfExists?: boolean): ICellStyle.INamed;
+    /**
+     * Returns the styles that match the filter, in gallery order.
+     *
+     * @param options {@link INamedStyleCollection.GetItemsOptions}
+     */
+    getItems(options?: INamedStyleCollection.GetItemsOptions): ICellStyle.INamed[];
+    /** For runtime type checking. */
+    readonly isINamedStyleCollection: true;
+}
+/**
+ * {@inheritDoc INamedStyleCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link INamedStyleCollection}
+ */
+export declare namespace INamedStyleCollection {
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * Which styles: the built-ins, the document's own (a customized built-in is one of the
+         * document's own), or every style.
+         *
+         * @defaultValue `IThemeCollection.BuiltInFilterType.All`
+         */
+        type?: IThemeCollection.BuiltInFilterType;
+        /**
+         * Include styles marked hidden — a deleted built-in is a hidden one.
+         *
+         * @defaultValue `false`
+         */
+        includeHidden?: boolean;
+    }
+}
+//# sourceMappingURL=INamedStyleCollection.d.ts.map