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

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

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}

@@ -6,13 +6,14 @@ import { IColor } from '../color';
 import { IFill } from '../fill';
 import { ITextFrame, IStyledFont } from '../text';
 import { IFont } from '../font';
-import { IBorder } from '../border';
+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 {
     /**
      * Format used for Number formatting:
      * * {@link https://docs.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.numberingformats?view=openxml-2.8.1}
@@ -24,32 +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 protection The protection or a partial property object to apply. Pass `null` to clear.
+     * @param options Optional configuration for the update.
+     */
+    setProtection(protection: ICellProtection.Update, options?: ICellStyle.UpdateOptions): ICellStyle;
+    /**
+     * Returns the borders.
+     */
+    getBorders(): IBorders;
+    /**
+     * Sets the borders.
      *
-     * @param border The border object or a shorthand property object to apply. Pass `null` to clear.
+     * This method allows updating borders using an {@link IBorders} or a shorthand property object.
+     *
+     * @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 `IBorder` object for further modifications.
+     * @returns The `IBorders` object for further modifications.
      */
-    setBorder(border: IBorder.Update, options?: IStyle.UpdateOptions): IStyle;
+    setBorders(borders: IBorders.Update, options?: ICellStyle.UpdateOptions): ICellStyle;
     /**
      * Fill properties for the background.
      */
@@ -63,23 +76,23 @@ export interface IStyle {
      * @param options Optional configuration for the update.
      * @returns The `IFill` object for further modifications.
      */
-    setFill(fill: IFill.Update, options?: IStyle.UpdateOptions): IStyle;
+    setFill(fill: IFill.Update, options?: ICellStyle.UpdateOptions): ICellStyle;
     /**
      * Sets the fill style to a solid fill.
      */
-    setFillSolid(options?: IStyle.UpdateOptions): IFill.ISolid;
+    setFillSolid(options?: ICellStyle.UpdateOptions): IFill.ISolid;
     /**
      * Sets the fill style to a gradient fill.
      */
-    setFillGradient(options?: IStyle.UpdateOptions): IFill.IGradient;
+    setFillGradient(options?: ICellStyle.UpdateOptions): IFill.IGradient;
     /**
      * Sets the fill style to a pattern fill.
      */
-    setFillPattern(options?: IStyle.UpdateOptions): IFill.IPattern;
+    setFillPattern(options?: ICellStyle.UpdateOptions): IFill.IPattern;
     /**
      * Sets the fill style to no fill.
      */
-    setFillNone(options?: IStyle.UpdateOptions): IFill.INone;
+    setFillNone(options?: ICellStyle.UpdateOptions): IFill.INone;
     /**
      * Returns the alignment for the style.
      */
@@ -93,7 +106,7 @@ 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.
      */
@@ -107,31 +120,31 @@ export interface IStyle {
      * @param options Optional configuration for the update.
      * @returns The `IStyledFont` object for further modifications.
      */
-    setFont(font: IStyledFont.Update, options?: IStyle.UpdateOptions): IStyle;
+    setFont(font: IStyledFont.Update, 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
      *
@@ -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>;
         /**
          * 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.
          */
@@ -252,20 +272,20 @@ export declare namespace IStyle {
      *
      * @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
+     * {@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} */
+    type Modifiers = Omit<IProperties.ResolvableProperties<ICellStyle.Properties>, 'font'> & {
+        /** {@inheritDoc ICellStyle.Properties.font} */
         font?: IProperties.ResolvableProperties<IStyledFont.Modifiers> | 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.
          */
@@ -337,7 +357,7 @@ export declare namespace IStyle {
         /**
          * For Persisting.
          */
-        toJSON(): IStyle.NamedJSON;
+        toJSON(): ICellStyle.NamedJSON;
         /**
          * For runtime type checking.
          */
@@ -368,7 +388,7 @@ export declare namespace IStyle {
         /**
          * The cell style properties.
          */
-        style: IStyle.Properties<C>;
+        style: ICellStyle.Properties<C>;
     }
     /**
      * For persisting.
@@ -382,7 +402,7 @@ export declare namespace IStyle {
         /**
          * Allows for style modifications.
          */
-        style: IStyle.Update;
+        style: ICellStyle.Update;
     }
     /**
      * List of BuiltIn CellStyles.
@@ -487,4 +507,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

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

@@ -0,0 +1,77 @@
+import { ICollection } from '../type';
+import { IThemeCollection } from '../theme';
+import { ISlicerStyle } from '../slicer';
+/**
+ * The slicer styles of a workbook — the built-ins (`SlicerStyleLight1`, ...) and the ones the
+ * document defines — and which of them is the default for a new slicer.
+ *
+ * @remarks
+ * Office Scripts has the same shape: `Workbook.getSlicerStyles()`, `getSlicerStyle(name)`,
+ * `getDefaultSlicerStyle()` / `setDefaultSlicerStyle(style)`.
+ *
+ * Order is the gallery's: the built-ins (Light, Other, Dark), each replaced in place by a custom
+ * style of the same name, then the document's own styles by name.
+ *
+ * `onCollectionChange` announces a style added, changed or deleted, and a change of the default.
+ *
+ * Reached from {@link IStyleCollection.getSlicerStyles}.
+ */
+export interface ISlicerStyleCollection extends ICollection<ISlicerStyle> {
+    /**
+     * 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): ISlicerStyle | null;
+    /**
+     * Adds or updates a style.
+     *
+     * @param name The name, compared case-insensitively. Setting a built-in's name customizes
+     * the built-in.
+     * @param properties The style's elements.
+     * @returns The style as stored.
+     */
+    set(name: string, properties: Omit<ISlicerStyle.ResolvableProperties, 'name'>): ISlicerStyle;
+    /**
+     * Returns the styles that match the filter, in gallery order.
+     *
+     * @param options {@link ISlicerStyleCollection.GetItemsOptions}
+     */
+    getItems(options?: ISlicerStyleCollection.GetItemsOptions): ISlicerStyle[];
+    /**
+     * Returns the style a slicer is given when it is created without one.
+     */
+    getDefault(): ISlicerStyle;
+    /**
+     * Sets the style a slicer is given when it is created without one.
+     *
+     * @param style The style, or its name. A name that matches nothing sets the default back to
+     * `SlicerStyleLight1`, the built-in default.
+     * @returns The previous default.
+     */
+    setDefault(style: ISlicerStyle | string): ISlicerStyle;
+    /** For runtime type checking. */
+    readonly isISlicerStyleCollection: true;
+}
+/**
+ * {@inheritDoc ISlicerStyleCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ISlicerStyleCollection}
+ */
+export declare namespace ISlicerStyleCollection {
+    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;
+    }
+}
+//# sourceMappingURL=ISlicerStyleCollection.d.ts.map