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

package/types/src/sheetHeader/SheetHeader.d.ts

@@ -7,7 +7,7 @@ import { ICellHeader } from '../cell';
 import { ITable } from '../table';
 import { ICellHeaderRange, ICellHeaderRanges } from '../cellRange';
 import { IRangeSelection } from '../selection';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { ISheetHeader } from './ISheetHeader';
 import { ListenerEmitter } from '../listener/ListenerEmitter';
 import { CreateCellHeaderCallback } from './SheetCellHeader';
@@ -35,14 +35,14 @@ export declare class SheetHeader implements ISheetHeader {
     protected _headerRunCoords: RunCoords | null;
     protected _hasHidden: boolean;
     protected _hiddenSignature: number;
+    protected _outlineSignature: number;
     protected _lastHeaderRead: {
         offset: number;
         header: ICellHeader;
     } | null;
     protected _readCache: RunUtils.CacheSearchRunData<_Utils.CellHeaderState> | null;
     protected _lastHeaders: ITypes.RunCoordValue<_Utils.CellHeaderState>[] | null;
-    protected _lastVisibleRunsRead: number | null;
-    protected _lastVisibleRunCoords: RunCoords | null;
+    protected _metrics: ISheetHeader.IMetrics | null;
     protected _entireRunMax: number;
     protected _entireHeaderRange: ICellHeaderRange;
     protected _entireRunCoords: RunCoords;
@@ -53,8 +53,23 @@ export declare class SheetHeader implements ISheetHeader {
     constructor(options: SheetHeader.ConstructorOptions);
     /** {@inheritDoc IListener.ISource.addListeners} */
     addListeners(listeners: ISheetHeader.IListeners, options?: IListener.Options): IListener.Remove;
-    protected _invalidateMaxIndex(): void;
-    protected _invalidSizes(force?: boolean): void;
+    /**
+     * Re-derive what is cached from the sheet's extent: the indexed sizes and the maximum index.
+     *
+     * @remarks
+     * The `onViewChange` listener above does this when it hears the sheet's extent change. An
+     * operation that changes the extent and then writes against it - `Sheet.setEntireSize` grows
+     * the sheet and then inserts into the new band, which is bounds-checked against the maximum
+     * index - cannot wait to be told, so it calls this. What changed is announced here, because the
+     * listener will then find nothing left to change.
+     *
+     * @internal
+     */
+    _invalidateExtent(): void;
+    /** Returns `true` if the maximum index changed. */
+    protected _invalidateMaxIndex(): boolean;
+    /** Returns `true` if the sizes were re-indexed. */
+    protected _invalidSizes(force?: boolean): boolean;
     /**
      * Force the header to re-read configurations.
      *
@@ -65,8 +80,8 @@ export declare class SheetHeader implements ISheetHeader {
      */
     invalidate(): void;
     protected _onHeaderChange(sizeUpdate: boolean): void;
-    /** {@inheritDoc ISheetHeader.getSheet} */
-    getSheet(): ISheet;
+    /** {@inheritDoc ISheetHeader.getWorksheet} */
+    getWorksheet(): IWorksheet;
     /** {@inheritDoc ISheetHeader.getAxis} */
     getAxis(): IRange.Axis;
     /** {@inheritDoc ISheetHeader.getTextAt} */
@@ -76,6 +91,8 @@ export declare class SheetHeader implements ISheetHeader {
     } | void;
     /** {@inheritDoc ISheetHeader.getRange} */
     getRange(address: ICellHeaderRange.Address, options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRange;
+    /** {@inheritDoc ISheetHeader.getFilteredRanges} */
+    getFilteredRanges(coords?: Readonly<RunCoords>): readonly ICellHeaderRange[];
     /** {@inheritDoc ISheetHeader.getRanges} */
     getRanges(address: ICellHeaderRanges.Address, options?: ICellHeaderRange.GetRangeOptions): ICellHeaderRanges;
     /** {@inheritDoc ISheetHeader.getSelectedRange} */
@@ -98,38 +115,31 @@ export declare class SheetHeader implements ISheetHeader {
     protected _getSnapshot(coordsFrom: RunCoords, optionsMark?: ICellHeaderRange.CopyOptions): ICellHeaderRange.ISnapshot;
     /** {@inheritDoc ISheetHeader.isProtected} */
     isProtected(): boolean;
-    /** {@inheritDoc ISheetHeader.getScaleFactor} */
-    getScaleFactor(): number;
     protected get _headers(): ITypes.RunCoordValue<_Utils.CellHeaderState>[];
     protected _updatePairsInternal(setters: ICellHeaderRange.AddressUpdatePair[], options?: ICellHeaderRange.UpdateHeadersOptions): RunCoords[] | null;
-    /** {@inheritDoc ISheetHeader.hasHidden} */
-    hasHidden(): boolean;
-    /** {@inheritDoc ISheetHeader.getDefaultSize} */
-    getDefaultSize(): number;
+    /**
+     * The header runs as stored: ordered, non-overlapping, gaps are default headers.
+     *
+     * @remarks
+     * The array is replaced, never mutated, when the headers change, so its identity can key a cache.
+     *
+     * @internal
+     */
+    _getHeaderRuns(): readonly ITypes.RunCoordValue<_Utils.CellHeaderState>[];
     /** {@inheritDoc ISheetHeader.getDefaultSizeNative} */
     getDefaultSizeNative(): number;
     /** {@inheritDoc ISheetHeader.getMaxSize} */
     getMaxSize(): number;
     /** {@inheritDoc ISheetHeader.getMinSize} */
     getMinSize(): number;
-    /** {@inheritDoc ISheetHeader.getOffset} */
-    getOffset(index: number): number;
-    /** {@inheritDoc ISheetHeader.getIndex} */
-    getIndex(offset: number): number;
-    /** {@inheritDoc ISheetHeader.getVisibleIndex} */
-    getVisibleIndex(index: number): RunCoords;
-    /** {@inheritDoc ISheetHeader.getSpanSize} */
-    getSpanSize(indexFrom: number, indexTo?: number): number;
-    /** {@inheritDoc ISheetHeader.getVisibleCount} */
-    getVisibleCount(indexFrom: number, indexTo: number): number;
+    /** {@inheritDoc ISheetHeader.getMetrics} */
+    getMetrics(): ISheetHeader.IMetrics;
     /** {@inheritDoc ISheetHeader.isSelectedAll} */
     isSelectedAll(index: number): boolean;
     /** {@inheritDoc ISheetHeader.isSelected} */
     isSelected(index: number): boolean;
     /** {@inheritDoc ISheetHeader.getSelectedRuns} */
     getSelectedRuns(): readonly ITypes.RunCoordValue<boolean>[];
-    /** {@inheritDoc ISheetHeader.hiddenHeadersAt} */
-    hiddenHeadersAt(index: number, reverse?: boolean): number;
     protected _insertHeaders(index: number, amount: number): void;
     protected _deleteHeaders(index: number, amount: number): void;
     /** {@inheritDoc ITransaction.ITransactional.beginCommit} */
@@ -153,6 +163,8 @@ export declare class SheetHeader implements ISheetHeader {
     toJSON(): ISheetHeader.JSON | null;
     get [Symbol.toStringTag](): string;
     toString(): string;
+    /** {@inheritDoc ISheetHeader.isISheetHeader} */
+    get isISheetHeader(): true;
 }
 /**
  * {@inheritDoc SheetHeader}
@@ -170,9 +182,9 @@ export declare namespace SheetHeader {
      */
     interface ConstructorOptions {
         /**
-         * The {@link ISheet} containing the Headers.
+         * The {@link IWorksheet} containing the Headers.
          */
-        sheet: ISheet;
+        sheet: IWorksheet;
         /**
          * The axis of the data.
          *
@@ -231,6 +243,15 @@ export declare namespace SheetHeader {
          * @param amount
          */
         setContainerShiftedCallback?: (callback: ShiftCallback) => void;
+        /**
+         * Called when the set of hidden headers changes, as it changes: inside the operation that
+         * changed it, or with none open for an undo or a redo.
+         *
+         * @remarks
+         * The `onHiddenChange` listener hears of the same change once the operation has closed. This
+         * is for an owner that has to act within the operation.
+         */
+        hiddenChanged?: () => void;
         /**
          * JSON state to load.
          */

package/types/src/sheetHeader/_HeaderMetrics.d.ts

@@ -0,0 +1,37 @@
+import { RunCoords } from '@sheetxl/utils';
+import { ISheetHeader } from './ISheetHeader';
+import * as _Utils from './_HeaderUtils';
+/**
+ * One version of a header's measurements. Everything it reads is captured at construction: the
+ * running-size index is rebuilt (never edited) whenever a size changes, so holding the references is
+ * enough to keep answering for this version.
+ */
+export declare class HeaderMetrics implements ISheetHeader.IMetrics {
+    private readonly _indexedSizes;
+    private readonly _defaultPxSize;
+    private readonly _scaleFactor;
+    private readonly _maxIndex;
+    private readonly _hasHidden;
+    private _lastVisibleIndex;
+    private _lastVisibleRun;
+    constructor(indexedSizes: readonly _Utils.RunningHeaderSize[], defaultPxSize: number, scaleFactor: number, maxIndex: number, hasHidden: boolean);
+    /** {@inheritDoc ISheetHeader.IMetrics.getScaleFactor} */
+    getScaleFactor(): number;
+    /** {@inheritDoc ISheetHeader.IMetrics.getDefaultSize} */
+    getDefaultSize(): number;
+    /** {@inheritDoc ISheetHeader.IMetrics.getOffset} */
+    getOffset(index: number): number;
+    /** {@inheritDoc ISheetHeader.IMetrics.getIndex} */
+    getIndex(offset: number): number;
+    /** {@inheritDoc ISheetHeader.IMetrics.getSpanSize} */
+    getSpanSize(indexFrom: number, indexTo?: number): number;
+    /** {@inheritDoc ISheetHeader.IMetrics.getVisibleIndex} */
+    getVisibleIndex(index: number): Readonly<RunCoords>;
+    /** {@inheritDoc ISheetHeader.IMetrics.getVisibleCount} */
+    getVisibleCount(indexFrom: number, indexTo: number): number;
+    /** {@inheritDoc ISheetHeader.IMetrics.hiddenHeadersAt} */
+    hiddenHeadersAt(index: number, reverse?: boolean): number;
+    /** {@inheritDoc ISheetHeader.IMetrics.hasHidden} */
+    hasHidden(): boolean;
+}
+//# sourceMappingURL=_HeaderMetrics.d.ts.map

package/types/src/sheetHeader/_HeaderUtils.d.ts

@@ -2,7 +2,6 @@ import { RunCoords } from '@sheetxl/utils';
 import { IRange } from '@sheetxl/primitives';
 import { ITypes } from '../type';
 import { CacheSearchRunData } from '../collections/_RunUtils';
-import { IStyle } from '../style';
 import { ICellHeaderRange, ICellHeaderRanges } from '../cellRange';
 /**
  * Note - By using optional keys as a way to detect default values we are creating mono polymorphic objects. (perform issue in V8).
@@ -14,10 +13,12 @@ export interface CellHeaderState {
     sz?: number;
     csz?: boolean;
     h?: boolean;
-    s?: IStyle;
-    cs?: boolean;
-    /** outline level */
+    /** outline level, 1-7; absent when not grouped */
     l?: number;
+    /** collapsed; set on a group's summary header */
+    cl?: boolean;
+    /** best fit (columns) */
+    bf?: boolean;
 }
 /**
  * Use for tracking the accumulated sizes from the beginning of the headers.

package/types/src/sheetProtection/{ISheetProtection.d.ts → IWorksheetProtection.d.ts}

@@ -3,14 +3,14 @@ import { IProtection } from '../protection/IProtection';
  * Interface representing the protection settings for a sheet.
  * Extends the base `IProtection` interface with additional sheet-specific protection options.
  */
-export interface ISheetProtection extends IProtection<ISheetProtection, ISheetProtection.Properties, ISheetProtection.JSON> {
+export interface IWorksheetProtection extends IProtection<IWorksheetProtection, IWorksheetProtection.Properties, IWorksheetProtection.JSON> {
     /**
      * Retrieves the protection properties for the sheet.
      *
-     * @returns The {@link ISheetProtection.Properties} object representing the current protection settings,
-     * or `null` if the sheet is not locked.
+     * @returns The {@link IWorksheetProtection.Properties} the sheet protects with, kept while it is
+     * unprotected, or `null` when it has none.
      */
-    getProperties(): Partial<ISheetProtection.Properties> | null;
+    getProperties(): Partial<IWorksheetProtection.Properties> | null;
     /**
      * Checks if the AutoTable functionality is protected on the sheet.
      *
@@ -90,61 +90,95 @@ export interface ISheetProtection extends IProtection<ISheetProtection, ISheetPr
      */
     isSortAllowed(): boolean;
     /**
-     * Checks if selecting locked cells is protected on the sheet.
+     * Checks if formulas may be shown on the protected sheet.
      *
-     * @returns `true` if selecting locked cells is locked, `false` otherwise.
+     * @returns `false` if the sheet hides its formulas while protected.
+     *
+     * @remarks
+     * * While this is `false`, a cell's formula shows only when its style grants it
+     *   (`ICellProtection.isShowFormulas`) — an exception, the way an always-unlocked cell is one.
+     * * Defaults to `true`, and is always `true` while the sheet is not locked (including paused).
+     */
+    isShowFormulasAllowed(): boolean;
+    /**
+     * Checks if locked cells may be selected on the protected sheet.
+     *
+     * @returns `false` if the sheet refuses selection of its locked cells while protected.
+     *
+     * @remarks
+     * Defaults to `true`, and is always `true` while the sheet is not locked (including paused).
      */
     isSelectLockedCellsAllowed(): boolean;
     /**
-     * Checks if selecting unlocked cells is protected on the sheet.
+     * Checks if unlocked cells may be selected on the protected sheet.
      *
-     * @returns `true` if selecting unlocked cells is locked, `false` otherwise.
+     * @returns `false` if the sheet refuses selection of its unlocked cells while protected.
+     *
+     * @remarks
+     * Defaults to `true`, and is always `true` while the sheet is not locked (including paused).
      */
     isSelectUnlockedCellsAllowed(): boolean;
+    /** For runtime type checking. */
+    readonly isIWorksheetProtection: true;
 }
 /**
- * {@inheritDoc ISheetProtection}
+ * {@inheritDoc IWorksheetProtection}
  * @see
  * ### **Interface**
  *
- * {@link ISheetProtection}
+ * {@link IWorksheetProtection}
  */
-export declare namespace ISheetProtection {
+export declare namespace IWorksheetProtection {
+    /**
+     * @remarks
+     * There is no whole-sheet flag here: changing it is {@link IProtection.lock} and
+     * {@link IProtection.unlock}, reading it {@link IWorksheetProtection.isLocked}. It is saved as
+     * {@link IWorksheetProtection.JSON.sheet}.
+     */
     interface Properties extends IProtection.Properties {
-        /** {@inheritDoc ISheetProtection.isAutoTableAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isAutoTableAllowed} */
         autoTable?: boolean;
-        /** {@inheritDoc ISheetProtection.isDeleteColumnsAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isDeleteColumnsAllowed} */
         deleteColumns?: boolean;
-        /** {@inheritDoc ISheetProtection.isDeleteRowsAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isDeleteRowsAllowed} */
         deleteRows?: boolean;
-        /** {@inheritDoc ISheetProtection.isFormatCellsAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isFormatCellsAllowed} */
         formatCells?: boolean;
-        /** {@inheritDoc ISheetProtection.isFormatColumnsAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isFormatColumnsAllowed} */
         formatColumns?: boolean;
-        /** {@inheritDoc ISheetProtection.isFormatRowsAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isFormatRowsAllowed} */
         formatRows?: boolean;
-        /** {@inheritDoc ISheetProtection.isInsertColumnsAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isInsertColumnsAllowed} */
         insertColumns?: boolean;
-        /** {@inheritDoc ISheetProtection.isInsertHyperlinksAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isInsertHyperlinksAllowed} */
         insertHyperlinks?: boolean;
-        /** {@inheritDoc ISheetProtection.isInsertRowsAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isInsertRowsAllowed} */
         insertRows?: boolean;
-        /** {@inheritDoc ISheetProtection.isObjectsAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isObjectsAllowed} */
         objects?: boolean;
-        /** {@inheritDoc ISheetProtection.isPivotTablesAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isPivotTablesAllowed} */
         pivotTables?: boolean;
-        /** {@inheritDoc ISheetProtection.isScenariosAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isScenariosAllowed} */
         scenarios?: boolean;
-        /** {@inheritDoc ISheetProtection.isSelectLockedCellsAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isSelectLockedCellsAllowed} */
         selectLockedCells?: boolean;
-        /** {@inheritDoc ISheetProtection.isSelectUnlockedCellsAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isSelectUnlockedCellsAllowed} */
         selectUnlockedCells?: boolean;
-        /** {@inheritDoc ISheetProtection.isSortAllowed} */
+        /** {@inheritDoc IWorksheetProtection.isSortAllowed} */
         sort?: boolean;
-        sheet?: boolean;
+        /** {@inheritDoc IWorksheetProtection.isShowFormulasAllowed} */
+        showFormulas?: boolean;
     }
-    interface JSON extends ISheetProtection.Properties, IProtection.JSON {
+    interface JSON extends IWorksheetProtection.Properties, IProtection.JSON {
+        /**
+         * `true` when the whole sheet stays allowed: it is not protected, and keeps its options for the
+         * next lock. Absent, the sheet is protected.
+         *
+         * @remarks
+         * Like every allowance here, the inverse of its OOXML attribute (`sheet="1"` is protected).
+         */
+        sheet?: boolean;
     }
-    type PropertyKeys = (keyof ISheetProtection.Properties);
+    type PropertyKeys = (keyof IWorksheetProtection.Properties);
 }
-//# sourceMappingURL=ISheetProtection.d.ts.map
+//# sourceMappingURL=IWorksheetProtection.d.ts.map

package/types/src/sheetProtection/WorksheetProtection.d.ts

@@ -0,0 +1,51 @@
+import { DefaultProtection } from '../protection/DefaultProtection';
+import { IWorksheetProtection } from './IWorksheetProtection';
+export declare class WorksheetProtection extends DefaultProtection<IWorksheetProtection, IWorksheetProtection.Properties, IWorksheetProtection.JSON> implements IWorksheetProtection {
+    /** {@inheritDoc IWorksheetProtection.isAutoTableAllowed} */
+    isAutoTableAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isDeleteColumnsAllowed} */
+    isDeleteColumnsAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isDeleteRowsAllowed} */
+    isDeleteRowsAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isFormatCellsAllowed} */
+    isFormatCellsAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isFormatColumnsAllowed} */
+    isFormatColumnsAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isFormatRowsAllowed} */
+    isFormatRowsAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isInsertColumnsAllowed} */
+    isInsertColumnsAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isInsertHyperlinksAllowed} */
+    isInsertHyperlinksAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isInsertRowsAllowed} */
+    isInsertRowsAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isObjectsAllowed} */
+    isObjectsAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isPivotTablesAllowed} */
+    isPivotTablesAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isScenariosAllowed} */
+    isScenariosAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isSortAllowed} */
+    isSortAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isShowFormulasAllowed} */
+    isShowFormulasAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isSelectLockedCellsAllowed} */
+    isSelectLockedCellsAllowed(): boolean;
+    /** {@inheritDoc IWorksheetProtection.isSelectUnlockedCellsAllowed} */
+    isSelectUnlockedCellsAllowed(): boolean;
+    /**
+     * A property that a locked sheet must deny explicitly: unset is allowed, and read-only does not
+     * deny it. The opposite of {@link _isPropertyAllowed}, which a locked sheet must grant explicitly.
+     */
+    protected _isPropertyAllowedByDefault(property: IWorksheetProtection.PropertyKeys): boolean;
+    protected _getAllowedKey(): string;
+    protected _updateProperties(properties: IWorksheetProtection.Properties | null): void;
+    protected _clearProperties(): void;
+    protected _fromJSON(json: IWorksheetProtection.JSON | null): void;
+    protected _toJSON(json: IWorksheetProtection.JSON): IWorksheetProtection.JSON;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+    /** {@inheritDoc IWorksheetProtection.isIWorksheetProtection} */
+    get isIWorksheetProtection(): true;
+}
+//# sourceMappingURL=WorksheetProtection.d.ts.map

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

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