@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.10

package/types/src/sheet/style/SheetDirectStyle.d.ts

@@ -1,18 +1,18 @@
 import { IRange, Scalar } from '@sheetxl/primitives';
 import { IProperties } from '../../type';
-import { IBorder } from '../../border';
-import { IStyle, IStyleCollection } from '../../style';
+import { IBorders } from '../../border';
+import { ICellStyle, IStyleCollection } from '../../style';
 import { ISpatialMap } from '../../collections/ISpatialMap';
 /**
  * `SheetDirectStyle` represents a style that spans a range of cells.
  *
  * * It can generate a list of properties for each cell in the range.
  */
-export declare class SheetDirectStyle implements ISpatialMap.IUpdatableValue, IProperties.ICellRanged<IStyle.Properties> {
+export declare class SheetDirectStyle implements ISpatialMap.IUpdatableValue, IProperties.ICellRanged<ICellStyle.Properties> {
     protected _c: IStyleCollection;
     protected _getEntireRange: (() => IRange.Coords) | null;
     protected _r: IRange.Coords;
-    protected _p: IStyle.Properties | null;
+    protected _p: ICellStyle.Properties | null;
     protected _t: IRange.Coords | null;
     protected _e: boolean;
     protected _o: IRange.AxisSelection;
@@ -23,26 +23,37 @@ export declare class SheetDirectStyle implements ISpatialMap.IUpdatableValue, IP
      * unstyled cells reads/persists correctly; intersect-merges consume `_u` so clears reach cells
      * that DO have a previous style. See the ranged-style update in Sheet.ts.
      */
-    protected _u: IStyle.Properties | undefined;
-    constructor(styles: IStyleCollection, getEntireRange: (() => IRange.Coords) | null, range: IRange.Coords, properties?: IStyle.Properties | null, tile?: IRange.Coords | null, axes?: IRange.AxisSelection);
+    protected _u: ICellStyle.Properties | undefined;
+    /** Lazily built {@link getMeasureKey}. */
+    protected _mk: string | undefined;
+    constructor(styles: IStyleCollection, getEntireRange: (() => IRange.Coords) | null, range: IRange.Coords, properties?: ICellStyle.Properties | null, tile?: IRange.Coords | null, axes?: IRange.AxisSelection);
     isEmpty(): boolean;
-    getProperties(): IStyle.Properties | null;
+    getProperties(): ICellStyle.Properties | null;
     /** {@inheritDoc IProperties.ICellRanged.getCoords} */
     getCoords(): Readonly<IRange.Coords>;
     /**
      * The update form including explicit `null` clears; only present on update templates.
      * @see {@link _u}
      */
-    getUpdateProperties(): IStyle.Properties | undefined;
+    getUpdateProperties(): ICellStyle.Properties | undefined;
+    /**
+     * A compare key over the properties that can change a MEASURED size: the named base, number
+     * format, font, the metric alignment properties (overflow / rotation / indent) and insets. Two
+     * direct styles with equal keys resolve to the same metrics for the same value, so a scan can
+     * treat distinct instances (every spatial fragment is one) as a single style run. `''` for no
+     * properties — the same key as no direct style at all. Built once per instance (immutable).
+     * @internal
+     */
+    getMeasureKey(): string;
     /** Category key partition for {@link splitByFeature} (SHEET-STYLE-SPLIT). Covers every
-     * `IStyle.Properties` key exactly once so the split is lossless. `protection` is future. */
-    static readonly BorderKeys: readonly (keyof IStyle.Properties)[];
-    static readonly FillKeys: readonly (keyof IStyle.Properties)[];
-    static readonly ContentKeys: readonly (keyof IStyle.Properties)[];
+     * `ICellStyle.Properties` key exactly once so the split is lossless. */
+    static readonly BorderKeys: readonly (keyof ICellStyle.Properties)[];
+    static readonly FillKeys: readonly (keyof ICellStyle.Properties)[];
+    static readonly ContentKeys: readonly (keyof ICellStyle.Properties)[];
     /**
      * Split this style into up to three category-scoped copies (border / fill / content) for the
      * per-feature style maps (SHEET-STYLE-SPLIT §4). The partition is **lossless** — every
-     * `IStyle.Properties` key goes to exactly one category — so merging the three reconstructs this
+     * `ICellStyle.Properties` key goes to exactly one category — so merging the three reconstructs this
      * style. Both the clean properties (`_p`) and the update form (`_u`, explicit `null` clears) are
      * partitioned. A category with no present keys returns `null`.
      * @internal
@@ -81,7 +92,7 @@ export declare class SheetDirectStyle implements ISpatialMap.IUpdatableValue, IP
      * the update form ({@link getUpdateProperties}) while the direct properties stay clean. Use when
      * resolving an update against an empty previous style for later per-run merging.
      */
-    cloneWithUpdate(updates: IStyle.Modifiers, keepNulls?: boolean): this;
+    cloneWithUpdate(updates: ICellStyle.Modifiers, keepNulls?: boolean): this;
     /** {@inheritDoc ISpatialMap.IUpdatableValue.copyTo} */
     copyTo(destination: IRange.Coords, options?: ISpatialMap.CopyOptions): ISpatialMap.Entry<this> | undefined;
     /** {@inheritDoc ISpatialMap.IUpdatableValue.canTile} */
@@ -113,18 +124,18 @@ export declare class SheetDirectStyle implements ISpatialMap.IUpdatableValue, IP
      * exists to prevent.
      * @internal
      */
-    getInnerBorder(range: IRange.Coords): Readonly<Partial<IBorder.Properties>> | null;
-    protected _localizeBorderRange(unscoped: Readonly<IBorder.Properties>, rangeUnscoped: IRange.Coords, range: IRange.Coords): Partial<IBorder.Properties> | null | undefined;
+    getInnerBorder(range: IRange.Coords): Readonly<Partial<IBorders.Properties>> | null;
+    protected _localizeBorderRange(unscoped: Readonly<IBorders.Properties>, rangeUnscoped: IRange.Coords, range: IRange.Coords): Partial<IBorders.Properties> | null | undefined;
     /**
      * Localizes the border to the cell coords.
      * Returns border properties, null, or undefined.
      * * If undefined then there was no border to localize.
      * * `null` is localize to none.
      */
-    protected _localizeBorder(unscoped: IBorder.Properties, range: IRange.Coords, rowIndex: number, colIndex: number): Partial<IBorder.Properties> | null | undefined;
+    protected _localizeBorder(unscoped: IBorders.Properties, range: IRange.Coords, rowIndex: number, colIndex: number): Partial<IBorders.Properties> | null | undefined;
     /** {@inheritDoc IProperties.ICellRanged.getPropertiesAt} */
-    getPropertiesAt(rowIndex: number, colIndex: number, value: Scalar): Readonly<IStyle.Properties>;
+    getPropertiesAt(rowIndex: number, colIndex: number, value: Scalar): Readonly<ICellStyle.Properties>;
     /** {@inheritDoc ISpatialMap.IUpdatableValue.toJSON} */
-    toJSON(): IStyle.JSON;
+    toJSON(): ICellStyle.JSON;
 }
 //# sourceMappingURL=SheetDirectStyle.d.ts.map

package/types/src/sheet/style/SheetNamedStyle.d.ts

@@ -1,15 +1,15 @@
 import { IRange } from '@sheetxl/primitives';
 import { IProperties } from '../../type';
-import { IStyle, IStyleCollection } from '../../style';
+import { ICellStyle, IStyleCollection } from '../../style';
 import { ISpatialMap } from '../../collections/ISpatialMap';
 import { SheetDirectStyle } from './SheetDirectStyle';
 export declare class NamedRangedStyle extends SheetDirectStyle {
-    constructor(styles: IStyleCollection, properties?: IStyle.Properties);
+    constructor(styles: IStyleCollection, properties?: ICellStyle.Properties);
     isEmpty(): boolean;
     /** {@inheritDoc IProperties.ICellRanged.getCoords} */
     getCoords(): Readonly<IRange.Coords>;
     /** {@inheritDoc IProperties.ICellRanged.cloneWithUpdate} */
-    cloneWithUpdate(updates: IStyle.Properties): this;
+    cloneWithUpdate(updates: ICellStyle.Properties): this;
     protected _createShifted(coords: IRange.Coords): this;
     /** {@inheritDoc ISpatialMap.IUpdatableValue.getShifted} */
     getShifted(options: ISpatialMap.ShiftDetails<this>): ISpatialMap.Entry<this> | null;
@@ -17,31 +17,31 @@ export declare class NamedRangedStyle extends SheetDirectStyle {
     getSplit(coords: [IRange.Coords, IRange.Coords], _axis: IRange.Axis): [this, this];
     /** {@inheritDoc ISpatialMap.IUpdatableValue.getMerged} */
     getMerged(other: this, coords: IRange.Coords, _axis: IRange.Axis): this | undefined;
-    getPropertiesAt(_rowIndex: number, _colIndex: number): Readonly<IStyle.Properties>;
-    toJSON(): IStyle.JSON;
+    getPropertiesAt(_rowIndex: number, _colIndex: number): Readonly<ICellStyle.Properties>;
+    toJSON(): ICellStyle.JSON;
 }
-export declare class SheetNamedStyle implements IStyle.INamed {
+export declare class SheetNamedStyle implements ICellStyle.INamed {
     private _name;
     private _properties;
     private _rangeStyle;
     private _builtInID;
     private _doDelete;
-    constructor(style: IStyleCollection, properties: Readonly<IStyle.NamedProperties>, doDelete: (style: IStyle.INamed | string) => void, builtInID?: number | null);
-    /** {@inheritDoc IStyle.INamed.getRanged} */
-    getRanged(): IProperties.ICellRanged<IStyle.Properties>;
-    /** {@inheritDoc IStyle.INamed.getName} */
+    constructor(style: IStyleCollection, properties: Readonly<ICellStyle.NamedProperties>, doDelete: (style: ICellStyle.INamed | string) => void, builtInID?: number | null);
+    /** {@inheritDoc ICellStyle.INamed.getRanged} */
+    getRanged(): IProperties.ICellRanged<ICellStyle.Properties>;
+    /** {@inheritDoc ICellStyle.INamed.getName} */
     getName(): string;
-    /** {@inheritDoc IStyle.INamed.isHidden} */
+    /** {@inheritDoc ICellStyle.INamed.isHidden} */
     isHidden(): boolean;
-    /** {@inheritDoc IStyle.INamed.getILevel} */
+    /** {@inheritDoc ICellStyle.INamed.getILevel} */
     getILevel(): number | null;
-    /** {@inheritDoc IStyle.INamed.getBuiltInID} */
+    /** {@inheritDoc ICellStyle.INamed.getBuiltInID} */
     getBuiltInID(): number | null;
-    /** {@inheritDoc IStyle.INamed.delete} */
+    /** {@inheritDoc ICellStyle.INamed.delete} */
     delete(): void;
-    /** {@inheritDoc IStyle.INamed.toJSON} */
-    toJSON(): IStyle.NamedJSON;
-    /** {@inheritDoc IStyle.INamed.isINamed} */
+    /** {@inheritDoc ICellStyle.INamed.toJSON} */
+    toJSON(): ICellStyle.NamedJSON;
+    /** {@inheritDoc ICellStyle.INamed.isINamed} */
     get isINamed(): true;
 }
 //# sourceMappingURL=SheetNamedStyle.d.ts.map

package/types/src/sheet/style/SheetTableStyle.d.ts

@@ -1,8 +1,8 @@
 import { IRange } from '@sheetxl/primitives';
 import { IProperties } from '../../type';
-import { IStyle, IStyleCollection } from '../../style';
+import { ICellStyle, IStyleCollection } from '../../style';
 import { ITableStyle, ITable } from '../../table';
-export declare class TableRangedStyle implements IProperties.ICellRanged<IStyle.Properties> {
+export declare class TableRangedStyle implements IProperties.ICellRanged<ICellStyle.Properties> {
     protected _styles: IStyleCollection;
     protected _properties: ITableStyle.Properties;
     protected _table: ITable;
@@ -13,11 +13,11 @@ export declare class TableRangedStyle implements IProperties.ICellRanged<IStyle.
      * key, so entries never go stale; the instance itself is dropped with the table's
      * `_stylePropsCache` on any table or table-styles change (see `ITable.getRangedStyle`).
      */
-    protected _permCache: Map<string, Readonly<IStyle.Properties>> | null;
+    protected _permCache: Map<string, Readonly<ICellStyle.Properties>> | null;
     constructor(table: ITable, styles: IStyleCollection, properties: ITableStyle.Properties);
     protected _resolveProperties(properties: ITableStyle.Properties): ITableStyle.Properties;
     getCoords(): IRange.Coords;
-    getPropertiesAt(rowIndex: number, colIndex: number): Readonly<IStyle.Properties>;
+    getPropertiesAt(rowIndex: number, colIndex: number): Readonly<ICellStyle.Properties>;
 }
 export declare class SheetTableStyle implements ITableStyle {
     protected _styles: IStyleCollection;
@@ -29,7 +29,7 @@ export declare class SheetTableStyle implements ITableStyle {
     /** {@inheritDoc ITableStyle.delete} */
     delete(): void;
     /** {@inheritDoc ITableStyle.getRanged} */
-    getRanged(table: ITable): IProperties.ICellRanged<IStyle.Properties>;
+    getRanged(table: ITable): IProperties.ICellRanged<ICellStyle.Properties>;
     /** {@inheritDoc ITableStyle.getProperties} */
     getProperties(): Readonly<ITableStyle.Properties>;
     /** {@inheritDoc ITableStyle.getName} */

package/types/src/sheet/style/_Resolvers.d.ts

@@ -2,12 +2,13 @@ import { TypedObject } from '@sheetxl/utils';
 import { IColor } from '../../color';
 import { IFill } from '../../fill';
 import { ITextFrame, IStyledFont } from '../../text';
-import { IBorder } from '../../border';
+import { IBorders } from '../../border';
+import { ICellProtection } from '../../cell';
 import { NumberFormat } from '../../numFmt';
-import { IStyle, IStyleCollection } from '../../style';
+import { ICellStyle, IStyleCollection } from '../../style';
 export declare const COLOR: TypedObject<IColor.Serializable, IColor, IStyleCollection>;
-export declare const BORDER_STROKE: TypedObject<IBorder.StrokeProperties<IColor.Serializable>, IBorder.IStroke, IStyleCollection>;
-export declare const CELL_BORDER: TypedObject<IBorder.Properties, IBorder, IStyleCollection>;
+export declare const BORDER_STROKE: TypedObject<IBorders.StrokeProperties<IColor.Serializable>, IBorders.IStroke, IStyleCollection>;
+export declare const CELL_BORDER: TypedObject<IBorders.Properties, IBorders, IStyleCollection>;
 export declare const CELL_NUM_FMT: TypedObject<string | NumberFormat.Type | number, any, IStyleCollection>;
 export declare const CELL_FONT: TypedObject<IStyledFont.Properties, IStyledFont, IStyleCollection>;
 export declare const CELL_ALIGNMENT: TypedObject<ITextFrame.IAlignment.Properties, ITextFrame.IAlignment, IStyleCollection>;
@@ -17,8 +18,13 @@ export declare const GRADIENT_STOP: TypedObject<IFill.GradientStopProperties, IF
 export declare const GRADIENT_STOPS: TypedObject<(IFill.GradientStopProperties | IColor.Serializable)[], (IFill.IGradientStop | IColor.Serializable)[], IStyleCollection>;
 export declare const FILL_GRADIENT: TypedObject<IFill.GradientProperties, IFill.IGradient, IStyleCollection>;
 export declare const FILL_PATTERN: TypedObject<IFill.PatternProperties, IFill.IPattern, IStyleCollection>;
+/** An image fill: a resource stretched or tiled; its properties pass as a file states them. */
+export declare const FILL_IMAGE: TypedObject<IFill.ImageProperties, IFill.IImage, IStyleCollection>;
+/** A group fill: the shape takes its group's. */
+export declare const FILL_GROUP: TypedObject<IFill.GroupProperties, IFill, IStyleCollection>;
 export declare const FILL: TypedObject<IFill.Properties | IFill.SolidProperties | IFill.GradientProperties | IFill.PatternProperties | IFill.NoneProperties, IFill.ISolid | IFill.IGradient | IFill.IPattern | IFill.INone, IStyleCollection>;
-export declare const CELL_STYLE: TypedObject<IStyle.Properties, IStyle, IStyleCollection>;
+export declare const CELL_PROTECTION: TypedObject<ICellProtection.Properties, ICellProtection, IStyleCollection>;
+export declare const CELL_STYLE: TypedObject<ICellStyle.Properties, ICellStyle, IStyleCollection>;
 /**
  * The APPLY-direction cell style. Shares {@link CELL_STYLE}'s property tree but adds a `shorthand`
  * that expands a `named` update: applying a named style covers the categories its definition
@@ -34,8 +40,8 @@ export declare const CELL_STYLE: TypedObject<IStyle.Properties, IStyle, IStyleCo
  *
  * * `named: null` clears only the reference.
  * * `Normal` covers every category (the reset style).
- * * An {@link IStyle.INamed} value is normalized to its name (resolver-level `INamed` support).
+ * * An {@link ICellStyle.INamed} value is normalized to its name (resolver-level `INamed` support).
  */
-export declare const CELL_STYLE_APPLY: TypedObject<IStyle.Properties, IStyle, IStyleCollection>;
-export declare const NAMED_CELL_STYLE: TypedObject<IStyle.NamedProperties, IStyle.INamed, IStyleCollection>;
+export declare const CELL_STYLE_APPLY: TypedObject<ICellStyle.Properties, ICellStyle, IStyleCollection>;
+export declare const NAMED_CELL_STYLE: TypedObject<ICellStyle.NamedProperties, ICellStyle.INamed, IStyleCollection>;
 //# sourceMappingURL=_Resolvers.d.ts.map

package/types/src/sheet/style/_StyleUtils.d.ts

@@ -1,13 +1,37 @@
 import { IRange } from '@sheetxl/primitives';
 import { ITypes } from '../../type';
 import { ICellHeader } from '../../cell';
-import { IStyle } from '../../style';
-import { IBorder } from '../../border';
-import { ISpatialMap } from '../../collections';
+import { ICellStyle, IStyleCollection } from '../../style';
+import { IBorders } from '../../border';
+import { ISheetProtection } from '../../sheetProtection';
+import { ISpatialMap, ISpatialQuery } from '../../collections';
 /**
+ * `alwaysUnlocked` as a cell with these direct content properties resolves it: its own, then its
+ * named style's, then Normal's.
  * @internal
  */
-export declare function isEqualStrokeProperties(a: IBorder.StrokeProperties | undefined, b: IBorder.StrokeProperties | undefined): boolean;
+export declare function resolveAlwaysUnlocked(styles: IStyleCollection, direct: Readonly<ICellStyle.Properties> | null | undefined): boolean;
+/**
+ * `showFormulas` as a cell with these direct content properties resolves it: its own, then its
+ * named style's, then Normal's.
+ * @internal
+ */
+export declare function resolveShowFormulas(styles: IStyleCollection, direct: Readonly<ICellStyle.Properties> | null | undefined): boolean;
+/**
+ * The formula entries over `bounds` that protection lets a reader see.
+ *
+ * @remarks
+ * Every range-state read takes its formulas from here, so a hidden formula is not there for cells,
+ * regions, counts or copies alike. Saving, undo, writes and calculation read the formula map
+ * directly. Only a sheet that hides its formulas pays: each run is cut to the cells whose style
+ * grants `showFormulas`.
+ * @internal
+ */
+export declare function searchVisibleFormulas(formulaSpatial: ISpatialQuery<any>, contentSpatial: ISpatialQuery<any>, bounds: IRange.Coords, protection: ISheetProtection | null | undefined, styles: IStyleCollection): ISpatialMap.Entry<any>[];
+/**
+ * @internal
+ */
+export declare function isEqualStrokeProperties(a: IBorders.StrokeProperties | undefined, b: IBorders.StrokeProperties | undefined): boolean;
 /**
  * Splits a border range into a new range with adjusted border properties.
  *
@@ -22,7 +46,7 @@ export declare function isEqualStrokeProperties(a: IBorder.StrokeProperties | un
  * carry explicit `null` clears (see SheetDirectStyle update form), and those must localize to the
  * same pieces a real stroke would.
  */
-export declare function splitBorderRange(border: IBorder.Properties, rangeFrom: IRange.Coords, rangeTo: IRange.Coords, isColumn: boolean): Partial<IBorder.Properties> | null | undefined;
+export declare function splitBorderRange(border: IBorders.Properties, rangeFrom: IRange.Coords, rangeTo: IRange.Coords, isColumn: boolean): Partial<IBorders.Properties> | null | undefined;
 /**
  * Takes a range with a border and breaks it into range parts that can be used without
  * any coordinates.
@@ -30,14 +54,14 @@ export declare function splitBorderRange(border: IBorder.Properties, rangeFrom:
  * @remarks
  * * This allows for each cell style to know how to render it's borders without dereferencing from a range.
  * * This was designed for Excel export compatibility.
- * * We don't use in internally as we want the original 'border' intent to be maintained for
+ * * We don't use in internally as we want the original 'borders' intent to be maintained for
  *   easy .toJSON and AI inference.
  * * A range that reaches the grid's terminal row/column (Excel's `<col style>` reads back as a
  *   full-height range) has no closing border at the boundary, so no end sliver is split off
  *   there — a style-only piece at the last row/column materializes real `<c>` records and
  *   Excel treats the whole grid as the used range.
  */
-export declare function splitStyleBordersIntoSame(coords: IRange.Coords, json: IStyle.JSON, entireCoords?: IRange.Coords): IRange.JSONReferenceTuple<IStyle.JSON>[];
+export declare function splitStyleBordersIntoSame(coords: IRange.Coords, json: ICellStyle.JSON, entireCoords?: IRange.Coords): IRange.JSONReferenceTuple<ICellStyle.JSON>[];
 export interface StyleRangesJSON {
     cols: ITypes.RunCoordValue<ICellHeader.JSON>[];
     rows: ITypes.RunCoordValue<ICellHeader.JSON>[];
@@ -54,8 +78,14 @@ export interface StyleRangesJSON {
  * 1. Identifying the total style count for rows and columns if > than 50% then it converts
  *    the styles into a style header.
  * 2. If then uses overlap CellRangeIterator to find any intersections.
+ *
+ * A style's border is relative to the range it is stored with (a row or column style's range is
+ * the whole row or column), so the ids are not position-independent: wherever a range is written
+ * smaller than the entry it came from, its id is re-derived from the style's JSON through `ids`,
+ * and two entries sharing an id agree on a crossing only if they draw the same edges there.
+ * Styles without a border take none of this.
  */
-export declare function promoteStylesToHeaders(styles: StyleRangesJSON, entireCoords: IRange.Coords): StyleRangesJSON;
+export declare function promoteStylesToHeaders(styles: StyleRangesJSON, entireCoords: IRange.Coords, ids: Pick<IStyleCollection.IPersistScope, 'getElementJSON' | 'getElementID'>): StyleRangesJSON;
 /**
  * Performs a shift but uses the entire range to ensure edge styles.
  *

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

@@ -70,48 +70,15 @@ export interface ISheetHeader extends ITransaction.ITransactional, IListener.ISo
      */
     isProtected(): boolean;
     /**
-     * All header sizes are returned in pixels. This is done
-     * by multiplying the scaleFactor by the size on the cellHeader.
-     */
-    getScaleFactor(): number;
-    /**
-     * Returns the offset in pixels for the given header index.
-     * @param index 0-based absolute index.
-     */
-    getOffset(index: number): number;
-    /**
-     * Returns the index for the given header offset in pixels.
-     * @param offset 0-based pixels.
-     */
-    getIndex(offset: number): number;
-    /**
-     * Returns the visibleIndex for a given absolute index.
-     * * If it's hidden it will return a range of 1 with a value before the offset and after.
-     * * If it's visible then it will return a range of 0 with the min and max that exactly match the offset.
+     * Returns the header's measurements: pixel sizes, offsets and hidden headers, as they are now.
      *
-     * @param index 0-based absolute index.
-     * @returns A {@link RunCoords} that  can be used to determine if an index is hidden.
-  
      * @remarks
-     * If this is on the edge of the bounds this will return a +/- 1 the max bounds.
+     * The returned object does not change. The header returns the same object until a measurement
+     * changes, then a new one, announced by {@link ISheetHeader.Events.onMetricsChange}. Hold on to it
+     * to keep measuring against one consistent layout; compare identities to tell whether anything
+     * moved. Calling this repeatedly is cheap.
      */
-    getVisibleIndex(index: number): Readonly<RunCoords>;
-    /**
-     * Returns the number of indices visible. Between to indices.
-     * @param indexFrom
-     * @param indexTo
-     */
-    getVisibleCount(indexFrom: number, indexTo: number): number;
-    /**
-     * Returns the size of the header in pixels. If a second argument is passed it
-     * will be the size of all the headers within the range.
-     * Note - It is expected that indexFrom will always be less than or equal to indexTo
-     */
-    getSpanSize(indexFrom: number, indexTo?: number): number;
-    /**
-     * The default header size if not adjusted.
-     */
-    getDefaultSize(): number;
+    getMetrics(): ISheetHeader.IMetrics;
     /**
      * The default header size in native units.
      */
@@ -125,20 +92,22 @@ export interface ISheetHeader extends ITransaction.ITransactional, IListener.ISo
      */
     getMinSize(): number;
     /**
-     * This is a very specific optimization function. When
-     * hiding many headers instead of scanning we can just skip.
-     * If `0` is returned then there are no hidden headers immediately
-     * following this one. If `1` is returned then only this header is hidden.
+     * Returns the ranges of headers a filter holds a condition over: on the row axis, the data rows
+     * of the AutoTable and of every table whose {@link ITable.getActiveFilters} is not empty; on
+     * the column axis none, as nothing filters columns.
      *
-     * @param index The location to start the search.
-     * @param reverse Indicates if search should scan in reverse. defaults to `false`.
-     * @returns The number of headers following the index.
-     */
-    hiddenHeadersAt(index: number, reverse?: boolean): number;
-    /**
-     * Returns true if any of the headers have the isHidden flag set to true or if any sizes are 0.
+     * @param coords Only the ranges that meet this run, when given (a viewport).
+     *
+     * @remarks
+     * A sheet with any is "filtered", as Excel has it: `SUBTOTAL` 1-11 leave out every hidden row
+     * of a filtered sheet, hand-hidden ones included, and count them all on an unfiltered one; the
+     * visible headers of these ranges are the ones drawn as filtered. A condition counts whether
+     * or not it hides a row.
+     *
+     * A row hidden by hand and a row hidden by a filter are the same hidden row; nothing records
+     * which, and clearing a filter shows both ({@link ITable.deleteFilters}).
      */
-    hasHidden(): boolean;
+    getFilteredRanges(coords?: Readonly<RunCoords>): readonly ICellHeaderRange[];
     /**
      * Returns true if header has a max selection at the given index.
      */
@@ -181,6 +150,8 @@ export interface ISheetHeader extends ITransaction.ITransactional, IListener.ISo
      */
     addListeners(listeners: ISheetHeader.IListeners, options?: IListener.Options): IListener.Remove;
     close(): void;
+    /** For runtime type checking. */
+    readonly isISheetHeader: true;
 }
 /**
  * {@inheritDoc ISheetHeader}
@@ -201,15 +172,85 @@ export declare namespace ISheetHeader {
         headers: IRange.JSONReference<ICellHeader.JSON>[];
         defaultSize?: number;
     }
+    /**
+     * The measurements of a header at one moment, from {@link ISheetHeader.getMetrics}. Sizes are in
+     * pixels: the native size of each header multiplied by the scale factor. A hidden header measures 0.
+     */
+    interface IMetrics {
+        /**
+         * The factor that converts native header sizes to pixels.
+         */
+        getScaleFactor(): number;
+        /**
+         * The default header size in pixels, for a header that has not been sized.
+         */
+        getDefaultSize(): number;
+        /**
+         * Returns the offset in pixels for the given header index.
+         *
+         * @param index 0-based absolute index.
+         */
+        getOffset(index: number): number;
+        /**
+         * Returns the index for the given header offset in pixels.
+         *
+         * @param offset 0-based pixels.
+         */
+        getIndex(offset: number): number;
+        /**
+         * Returns the size in pixels of the header at `indexFrom`, or of the headers from `indexFrom` up to
+         * (not including) `indexTo`.
+         *
+         * @param indexFrom 0-based absolute index.
+         * @param indexTo 0-based absolute index, not less than `indexFrom`. Defaults to `indexFrom + 1`.
+         */
+        getSpanSize(indexFrom: number, indexTo?: number): number;
+        /**
+         * Returns the visible run around an absolute index.
+         * * If it's hidden it will return a range of 1 with a value before the offset and after.
+         * * If it's visible then it will return a range of 0 with the min and max that exactly match the offset.
+         *
+         * @param index 0-based absolute index.
+         * @returns A {@link RunCoords} that can be used to determine if an index is hidden.
+         *
+         * @remarks
+         * If this is on the edge of the bounds this will return a +/- 1 the max bounds.
+         */
+        getVisibleIndex(index: number): Readonly<RunCoords>;
+        /**
+         * Returns the number of visible headers from `indexFrom` to `indexTo`, inclusive.
+         *
+         * @param indexFrom 0-based absolute index.
+         * @param indexTo 0-based absolute index, not less than `indexFrom`.
+         */
+        getVisibleCount(indexFrom: number, indexTo: number): number;
+        /**
+         * Returns how many hidden headers run on from `index`: `0` if `index` is visible, `1` if only it is
+         * hidden. Lets a caller skip a hidden run instead of stepping through it.
+         *
+         * @param index The location to start from.
+         * @param reverse Count backwards instead. Defaults to `false`.
+         */
+        hiddenHeadersAt(index: number, reverse?: boolean): number;
+        /**
+         * Returns `true` if any header is hidden or has a size of 0.
+         */
+        hasHidden(): boolean;
+    }
     interface Events {
         /**
-         * Called when headers sizes have changed.
+         * Called when the header's measurements change: sizes, hidden headers or the scale.
+         * {@link ISheetHeader.getMetrics} returns a new object from then on.
          */
-        onSizesChange?(source: ISheetHeader): void;
+        onMetricsChange?(source: ISheetHeader): void;
         /**
          * Called when headers visibility (hidden) has changed.
          */
         onHiddenChange?(source: ISheetHeader): void;
+        /**
+         * Called when header outline levels, or which groups are collapsed, have changed.
+         */
+        onOutlineChange?(source: ISheetHeader): void;
     }
     interface IListeners extends IListener.Callbacks<ISheetHeader, ISheetHeader.Events> {
     }

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

@@ -4,6 +4,8 @@ import { ITable } from '../table';
 import { ICell, ICellHeader } from '../cell';
 import { ISheetHeader } from './ISheetHeader';
 import type * as _Utils from './_HeaderUtils';
+/** The deepest outline level a header can hold. */
+export declare const MaxOutlineLevel = 7;
 export declare class SheetCellHeader implements ICellHeader {
     protected _sheetHeader: ISheetHeader;
     protected _index: number;
@@ -30,6 +32,8 @@ export declare class SheetCellHeader implements ICellHeader {
     asCell(): ICell;
     /** {@inheritDoc ICellHeader.getSizeRelative} */
     getSizeRelative(): number;
+    /** {@inheritDoc ICellHeader.getOutlineLevel} */
+    getOutlineLevel(): number;
     /** {@inheritDoc ICellHeader.createCellHeader} */
     createCellHeader(update: ICellHeader.Modifiers): ICellHeader;
     /** {@inheritDoc ICellHeader.isEqual} */