@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

package/types/src/cell/ICellHeader.d.ts

@@ -0,0 +1,142 @@
+import { IRange } from '@sheetxl/primitives';
+import { ITable } from '../table';
+import { ICell } from './ICell';
+/**
+ * A logic label for an entire span of cells in either direction.
+ */
+export interface ICellHeader {
+    /**
+     * The absolute size in pixels.
+     */
+    getSize(): number;
+    /**
+     * Returns the header text.
+     */
+    getText(): string;
+    /**
+     * Return an {@link ITable.IColumn} if the cell is the the first row of a table range.
+     */
+    getColumn(): ITable.IColumn | null;
+    /**
+     * Returns the header axis.
+     */
+    getAxis(): IRange.Axis;
+    /**
+     * Flag to indicate if column is hidden. Note - A column with a size > 0 but hidden is true is valid
+     * because when hiding a value we don't change the size so that an unhide will restore to it's previous location
+     */
+    isHidden(): boolean;
+    /**
+    * Note - size can be a function of autoFitting isCustomSize means the field has set by the user
+    * and should not be autoSize due to autoFitting (unless explicitly done so by a user gesture)
+    */
+    isCustomSize(): boolean;
+    /**
+     * Creates a new detected header from the modifiers.
+     */
+    createCellHeader(update: ICellHeader.Modifiers): ICellHeader;
+    /**
+     * If a cell has no sizing or custom formatting.
+     */
+    isEmpty(): boolean;
+    /**
+     * Returns true if the headers are logically equal.
+     * @param other
+     */
+    isEqual(other: ICellHeader): boolean;
+    /**
+     * Returns the header as an ICell.
+     */
+    asCell(): ICell;
+    /**
+     * Rows and columns sizes are managed internally as relative size to the normal styling font size.
+     * This is done to allow for the sizes to auto adjustment when the style changes.
+     *
+     * @see
+     * {@link https://support.microsoft.com/en-us/office/change-the-column-width-and-row-height-72f5e3cc-994d-43e8-ae58-9774a0905f46}
+     */
+    getSizeRelative(): number;
+    /**
+     * For runtime introspection.
+     */
+    get isICellHeader(): true;
+}
+/**
+ * {@inheritDoc ICellHeader}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICellHeader}
+ */
+export declare namespace ICellHeader {
+    /**
+     * Combine various ways to update a CellHeader.
+     */
+    type Update = ICellHeader.Modifiers | ICellHeader | null;
+    /**
+     * Allows for headers to be updated.
+     */
+    interface Modifiers {
+        /**
+         * The size of the header in either absolute or relative value.
+         *
+         * @default 'The default size for the sheet'
+         *
+         * @remarks
+         * If the size is set to a 0 this will become hidden even if hidden is set to `false`.
+         *
+         * @see
+         * {@link relativeSize}
+         */
+        size?: number | string | ((size: number) => number);
+        /**
+         * @see
+         * {@link ICellHeader.isHidden()}
+         */
+        hidden?: boolean;
+        /**
+         * @see
+         * {@link ICellHeader.isCustomSize()}
+         */
+        autoSize?: boolean;
+        /**
+         * @see
+         * {@link ICellHeader.getSizeRelative()}
+         */
+        relativeSize?: boolean;
+    }
+    /**
+     * Stores information about header runs.
+     */
+    interface JSON {
+        /**
+         * Size - height or width
+         */
+        sz?: number;
+        /**
+         * Custom size
+         */
+        csz?: boolean;
+        /**
+         * Hidden
+         */
+        h?: boolean;
+        /**
+         * Header level
+         */
+        l?: number;
+        /**
+         * Collapsed level
+         */
+        cl?: boolean;
+        /**
+         * Style id
+         *
+         * @remarks
+         * * The style id is only available for export for backward compatible `ISheet.ToJSONOptions.includeHeaderStyles` is set.
+         * * This flag is ignored during loading.
+         */
+        s?: number;
+    }
+}
+//# sourceMappingURL=ICellHeader.d.ts.map

package/types/src/cell/ICellProtection.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Additional cell protection properties.
+ *
+ */
+export interface ICellProtection {
+    /**
+     * This is specified in ooxml but not sure what behavior it has.
+     * @defaultValue true
+     */
+    isEditAllowed(): boolean;
+    /**
+     * If the formula will be hidden when the worksheet is protected.
+     * @remarks
+     * This is called hidden in ooxml but in Excel object model it is formulaHidden.
+     * @defaultValue false
+     */
+    isFormulaHidden(): boolean;
+    /**
+     * For runtime type checking.
+     */
+    readonly isICellProtection: true;
+}
+/**
+ * {@inheritDoc ICellProtection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICellProtection}
+ */
+export declare namespace ICellProtection {
+    /**
+     * Properties for ICellProperties.
+     */
+    interface Properties {
+        edit?: boolean;
+        formulaHidden?: boolean;
+    }
+    interface JSON extends Properties {
+    }
+}
+//# sourceMappingURL=ICellProtection.d.ts.map

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

@@ -0,0 +1,4 @@
+export * from './ICell';
+export * from './ICellProtection';
+export * from './ICellHeader';
+//# sourceMappingURL=index.d.ts.map

package/types/src/cellRange/ICellHeaderRange.d.ts

@@ -0,0 +1,306 @@
+import { IRange } from '@sheetxl/primitives';
+import { RunCoords, ReferenceableClipboard } from '@sheetxl/utils';
+import { ITransaction } from '../transaction';
+import { ICellHeader } from '../cell';
+import { ICellRange } from './ICellRange';
+/**
+ * Represents a collection of ICellHeaders.
+ */
+export interface ICellHeaderRange {
+    /**
+     * The RunCoords for the range.
+     */
+    getCoords(): ICellHeaderRange.Coords;
+    /**
+     * Iterate over cells headers.
+     *
+     * @remarks
+     * * Callbacks can return a 'break' value to stop the visit.
+     */
+    forEach<T = any>(callback: ICellHeaderRange.ForEachCallback<T>, options?: ICellHeaderRange.IteratorOptions): T | void;
+    /**
+     * Similar to {@link forEach} but only spans that are different.
+     *
+     * @remarks
+     * * Callbacks can return a 'break' value to stop the visit.
+     */
+    forEachSpan<T = any>(callback: ICellHeaderRange.ForEachSpanCallback<T>, options?: ICellHeaderRange.IteratorOptions): T | void;
+    /**
+     * Returns the header at a location relative to the range.
+     *
+     * @param index
+     */
+    at(index: number): ICellHeader;
+    /**
+     * Set the size of the headers.
+     *
+     * @param size This can be a number of a string with units
+     * @param options {@link ICellHeaderRange.SetSizeOptions}
+     */
+    setSize(size: number | string, options?: ICellHeaderRange.SetSizeOptions): this;
+    /**
+     * Hides or show the columns for the given range.
+     *
+     * @defaultValue false
+     */
+    setHidden(hidden: boolean, options?: ICellHeaderRange.UpdateHeadersOptions): this;
+    /**
+     * Provides a convenient method for setting values with a range of calls.
+     *
+     * @remarks
+     * If an array is provided then values will be in row-major order and will
+     * repeat if the range is larger than the array
+     */
+    updateHeaders(values: ICellHeader.Update, options?: ICellHeaderRange.UpdateHeadersOptions): this;
+    /**
+     * Returns the data ranges for headers that contain information.
+     *
+     * @remarks
+     * * This is NOT the last cell that may have data or has been resized.
+     * * This also has nothing to do with the selection bounds.
+     */
+    getUsedRange(options?: ICellHeaderRange.GetRangeOptions): this;
+    /**
+     * Clear the header format. Specially this will clear the sizes.
+     */
+    clear(): this;
+    /**
+     * Returns the number of headers included in the range.
+     */
+    getCount(): number;
+    /**
+     * Returns the number of headers.
+     */
+    getHeaderCount(): number;
+    /**
+     * Returns the number of visible headers in the range.
+     */
+    getVisibleCount(): number;
+    /**
+     * Returns true if the range represents all headers.
+     */
+    isEntireHeaders(): boolean;
+    /**
+     * Returns the header axis.
+     */
+    getAxis(): IRange.Axis;
+    /**
+     * {@inheritDoc ICellRange.getSnapshot}
+     */
+    getSnapshot(options?: ICellHeaderRange.CopyOptions): ICellHeaderRange.ISnapshot;
+    /**
+     * Perform operation on all ranges.
+     *
+     * @see
+     * {@link ICellRange.doBatch}
+     */
+    doBatch<R>(callback: (commit: ITransaction.ICommit) => R | Promise<R>, options?: string | ICellHeaderRange.UpdateHeadersOptions): R | Promise<R>;
+    /**
+     * Returns the SheetHeader.
+     */
+    getSheetHeader<S>(): S;
+    /**
+     * {@inheritDoc ICellRange.getAddress}
+     */
+    getAddress(r1c1?: boolean): string;
+    /**
+     * Returns the address as a string.
+     */
+    toString(): string;
+    /**
+     * For runtime type checking.
+     */
+    readonly isICellHeaderRange: true;
+}
+/**
+ * {@inheritDoc ICellHeaderRange}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICellHeaderRange}
+ */
+export declare namespace ICellHeaderRange {
+    /**
+     * The coord type for a header range.
+     */
+    type Coords = RunCoords;
+    /**
+     * Specify either a range a run or a string.
+     *
+     * @remarks
+     * If the value is a string it will be parse as an a1 style address if it is a number it will be a zero based index.
+     */
+    type Address = Partial<IRange.Coords> | RunCoords | string | number;
+    /**
+     * Callback used for visiting a cells headers. If break is returned the visiting will stop with the
+     * break value returned.
+     *
+     * The context allows for the retrieval of additional information associated with the Cell include the
+     * {@link ICellHeader} object.
+     */
+    interface ForEachCallback<T = any> {
+        (size: number, context: ICellHeaderRange.CellHeaderContext): {
+            break: T;
+        } | void;
+    }
+    interface IteratorOptions {
+        /**
+         * The address for the range.
+         */
+        address?: ICellHeaderRange.Address;
+        /**
+         * Include all headers even empty ones.
+         *
+         * @defaultValue false
+        */
+        includeEmpty?: boolean;
+        /**
+         * Only include if the size is set and different from the default.
+         *
+         * @defaultValue false
+        */
+        includeSizes?: boolean;
+        /**
+         * Include headers that have custom styling.
+         *
+         * @defaultValue false
+         *
+         * @deprecated We are removing styles from headers (but will need in sheet for backward compatibility with Excel)
+         */
+        includeStyles?: boolean;
+        /**
+         * When scanning skip cells that are hidden via headers.
+         *
+         * @defaultValue 'all'
+         *
+         */
+        visibility?: 'hidden' | 'visible' | 'all';
+    }
+    /**
+     * Context for Iterators to provide access to the `IRange.CellCoords`, the `ICellHeader`, and additional operators.
+     */
+    interface CellHeaderContext {
+        /**
+         * Returns the index for the header
+         */
+        getIndex(): number;
+        /**
+         * Returns the CellHeader.
+         */
+        getCellHeader(): ICellHeader;
+        /**
+         * Utility method to return the offset as an address string.
+         */
+        getAddress(offset?: number, r1c1?: boolean): string;
+        /**
+         * Returns the coords for the header.
+         */
+        getCoords(): RunCoords;
+    }
+    /**
+     * Simple type to pairs an address with an update value.
+     */
+    interface AddressUpdatePair {
+        /**
+         * Allows for either a Cell or a Range.
+         */
+        address?: ICellHeaderRange.Address;
+        /**
+         * If null will clear the value.
+         */
+        update: ICellHeader.Update;
+    }
+    interface ForEachSpanCallback<T = any> {
+        (size: number, context: ICellHeaderRange.CellHeaderContext): {
+            break: T;
+        } | void;
+    }
+    interface GetRangeOptions {
+    }
+    /**
+     * Options for copying ICellHeaderRange.
+     */
+    interface CopyOptions extends ICellRange.SetValuesOptions, ReferenceableClipboard.CopyOptions {
+        /** {@inheritDoc ICellRange.CopyOptions.fitDestination} */
+        fitDestination?: boolean;
+    }
+    /**
+     * Options for `updateHeaders`.
+     */
+    interface UpdateHeadersOptions extends ITransaction.OperationOptions {
+        /**
+         * If this is set to `true` then any headers that have custom sizes will be ignored.
+         *
+         * @defaultValue false
+         */
+        skipCustomSize?: boolean;
+    }
+    /**
+     * Options for `setSize`.
+     */
+    interface SetSizeOptions extends ICellHeaderRange.UpdateHeadersOptions {
+        /**
+         * Sets if the size value is interpret as absolute or relative.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * Rows and columns sizes are managed internally as relative size to the normal styling font size.
+         * This is done to allow for the sizes to auto adjustment when the style changes.
+         *
+         * If the value is a number then the size is interpreted as relative size.
+         *
+         * If the size is set using a string that ends in 'px' This option will be ignored.
+         *
+         * @see
+         * * {@link ICellHeader.getSizeRelative()}
+         * * {@link https://support.microsoft.com/en-us/office/change-the-column-width-and-row-height-72f5e3cc-994d-43e8-ae58-9774a0905f46}
+         */
+        relativeSize?: boolean;
+        /**
+         * If this is set to `true` then the value will not be an autoSize value.
+         *
+         * @defaultValue false
+         */
+        autoSize?: boolean;
+    }
+    /**
+     * A snapshot of a header to use for laster copying.
+     */
+    interface ISnapshot<T = any> {
+        /**
+         * Called when the item is copied to a new header range.
+         */
+        copyTo(range: ICellHeaderRange, options?: ICellHeaderRange.CopyOptions): Promise<RunCoords> | RunCoords;
+        /**
+         * The RunCoords that bounds the current item.
+         */
+        getCoords?(): RunCoords;
+        /**
+         * Allow items to be copied as text.
+         */
+        toText?(): Promise<string> | string;
+        /**
+         * Allow items to be copied as html.
+         */
+        toHtml?(): Promise<string> | string;
+        /**
+         * Allow items to be copied as an image Blob.
+         */
+        toImage?(): Promise<Blob> | Blob;
+        /**
+         * The source that created the snapshot.
+         * This is used by copy to quickly do comparisons.
+         */
+        getSource(): T;
+        /**
+         * A user friendly name of a the snapshot item.
+         */
+        getName?(): string;
+        /**
+         * For runtime type checking.
+         */
+        readonly isISnapshot: true;
+    }
+}
+//# sourceMappingURL=ICellHeaderRange.d.ts.map

package/types/src/cellRange/ICellHeaderRanges.d.ts

@@ -0,0 +1,107 @@
+import { IRange } from '@sheetxl/primitives';
+import { RunCoords } from '@sheetxl/utils';
+import { ITransaction } from '../transaction';
+import { ICellHeader } from '../cell';
+import { ICellHeaderRange } from './ICellHeaderRange';
+/**
+ * An `ICellHeaderRanges` is a collection of {@link ICellHeaderRange}s.
+ *
+ * Useful when working with a discontinuous set of headers.
+ */
+export interface ICellHeaderRanges {
+    /**
+     * The RunCoords for the range.
+     */
+    getCoords(): Readonly<ICellHeaderRanges.Coords>;
+    /**
+     * Returns the header range at a location relative to the range.
+     *
+     * @param index
+     */
+    at(index: number): ICellHeaderRange;
+    /**
+     * Returns the number of headers ranges.
+     */
+    getCount(): number;
+    /**
+     * {@inheritDoc ICellHeaderRange.setHidden}
+     */
+    setHidden(hidden: boolean, options?: ICellHeaderRange.UpdateHeadersOptions): this;
+    /**
+     * {@inheritDoc ICellHeaderRange.setSize}
+     */
+    setSize(size: number | string, options?: ICellHeaderRange.SetSizeOptions): this;
+    /**
+     * {@inheritDoc ICellHeaderRange.clear}
+     */
+    clear(): this;
+    /**
+     * Returns the number of headers.
+     *
+     * @remarks
+     * This will remove overlaps.
+     */
+    getHeaderCount(): number;
+    /**
+     * {@inheritDoc ICellHeaderRange.getVisibleCount}
+     */
+    getVisibleCount(): number;
+    /**
+     * Returns true if all of the ranges cover the entire headers.
+     */
+    isEntireHeaders(): boolean;
+    /**
+     * Returns true if any of the ranges cover entire headers.
+     */
+    isEntireHeadersAny(): boolean;
+    /**
+     * {@inheritDoc ICellHeaderRange.getAxis}
+     */
+    getAxis(): IRange.Axis;
+    /**
+     * {@inheritDoc ICellHeaderRange.updateHeaders}
+     */
+    updateHeaders(values: ICellHeader.Update, options?: ICellHeaderRange.UpdateHeadersOptions): this;
+    /**
+     * {@inheritDoc ICellHeaderRange.doBatch}
+     */
+    doBatch<R>(callback: (commit: ITransaction.ICommit) => R | Promise<R>, options?: string | ICellHeaderRange.UpdateHeadersOptions): R | Promise<R>;
+    /**
+     * {@inheritDoc ICellHeaderRange.getSheetHeader}
+     */
+    getSheetHeader<S>(): S;
+    /**
+     * {@inheritDoc ICellHeaderRange.getAddress}
+     */
+    getAddress(r1c1?: boolean): string;
+    /**
+     * {@inheritDoc ICellHeaderRange.toString}
+     */
+    toString(): string;
+    /**
+     * For runtime type checking.
+     */
+    readonly isICellHeaderRanges: true;
+}
+/**
+ * {@inheritDoc ICellHeaderRanges}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICellHeaderRanges}
+ */
+export declare namespace ICellHeaderRanges {
+    /**
+     * The coord type for a header ranges.
+     */
+    type Coords = RunCoords[];
+    /**
+     * Address for multiple {@link ICellHeaderRange}s.
+     */
+    type Address = ICellHeaderRanges | string | ICellHeaderRange.Address | readonly ICellHeaderRange.Address[];
+    /**
+     * Shorthand for persisting.
+     */
+    type RefJSON = RunCoords[] | RunCoords | string;
+}
+//# sourceMappingURL=ICellHeaderRanges.d.ts.map