@sheetxl/primitives 0.8.0-beta.5 → 0.8.0-beta.7

package/browser/esm/index.mjs

@@ -1,5 +1,5 @@
 /**
-* @license @sheetxl/primitives - Primitives - Base types for SheetXL functions. - v0.8.0-beta.5
+* @license @sheetxl/primitives - Primitives - Base types for SheetXL functions. - v0.8.0-beta.7
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
 * License: The license can be found at https://www.sheetxl.com/license.

package/node/esm/index.mjs

@@ -1,5 +1,5 @@
 /**
-* @license @sheetxl/primitives - Primitives - Base types for SheetXL functions. - v0.8.0-beta.5
+* @license @sheetxl/primitives - Primitives - Base types for SheetXL functions. - v0.8.0-beta.7
 *
 * (C) 2026-present SheetXL Inc. & Michael T. Ford
 * License: The license can be found at https://www.sheetxl.com/license.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/primitives",
   "description": "Primitives - Base types for SheetXL functions.",
-  "version": "0.8.0-beta.5",
+  "version": "0.8.0-beta.7",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {

package/types/src/FormulaContext.d.ts

@@ -66,7 +66,7 @@ export declare class StubbedFormulaContext implements IFormulaContext {
     /** @inheritdoc IFormulaContext.formatResults */
     formatResults(numFmt: string): void;
     /** @inheritdoc IFormulaContext.filterHidden */
-    filterHidden(range: IRange, axes?: IRange.AxisSelection): IRange;
+    filterHidden(range: IRange, options?: IFormulaContext.FilterHiddenOptions): IRange;
     /** @inheritdoc IFormulaContext.filterTotals */
     filterTotals(range: IRange): IRange;
     /** @inheritdoc IFormulaContext.getFunction */
@@ -225,7 +225,7 @@ export declare class ScopedFormulaContext implements IFormulaContext {
     /** @inheritdoc IFormulaContext.formatResults */
     formatResults(numFmt: string): void;
     /** @inheritdoc IFormulaContext.filterHidden */
-    filterHidden(range: IRange, axes?: IRange.AxisSelection): IRange;
+    filterHidden(range: IRange, options?: IFormulaContext.FilterHiddenOptions): IRange;
     /** @inheritdoc IFormulaContext.filterTotals */
     filterTotals(range: IRange): IRange;
     /** @inheritdoc IFormulaContext.getFunction */

package/types/src/IFormulaContext.d.ts

@@ -219,16 +219,30 @@ export interface IFormulaContext {
      */
     getSheetIndex(sheet?: string | IReferenceRange): number;
     /**
-     * Returns a copy of a range with hidden rows or columns removed.
+     * Returns a range as it reads without its hidden rows or columns.
      *
      * @param range The range to filter.
-     * @param axes Which axis to filter on. Default is `IRange.AxisSelection.Row`.
-     * @returns A new range without the hidden rows or columns.
+     * @param options See {@link IFormulaContext.FilterHiddenOptions}.
+     * @returns `range` itself when nothing in it is hidden; otherwise the same range reading with
+     * the hidden rows or columns skipped ({@link IRange.IteratorOptions.processRowSkip}).
      *
      * @remarks
      * Use this for functions that ignore hidden data, such as `SUBTOTAL`.
+     *
+     * Nothing is copied. The shape of `range` is kept, and a reference stays a reference: a hidden
+     * cell is not visited and reads as empty, so every position still means the cell it meant, and
+     * an aggregate that ignores blanks ignores it. A computed array has no rows or columns to hide
+     * and is returned as it is.
+     *
+     * A hidden row is a hidden row, whoever hid it: a filter and the user leave the same mark, and
+     * nothing here tells them apart. What a filter adds is a state of the range's SHEET, which
+     * {@link IFormulaContext.FilterHiddenOptions.onlyWhileFiltered} reads.
+     *
+     * A formula that calls `SUBTOTAL` or `AGGREGATE` is recalculated when a row or column is hidden
+     * or shown, and when a filter is set or cleared. One that reaches this only through a custom
+     * function is not: it reads the state when it is next calculated.
      */
-    filterHidden(range: IRange, axes?: IRange.AxisSelection): IRange;
+    filterHidden(range: IRange, options?: IFormulaContext.FilterHiddenOptions): IRange;
     /**
      * Returns a copy of a range with any cell whose formula is a nested total removed.
      *
@@ -566,6 +580,28 @@ export interface IFormulaContext {
  * {@link IFormulaContext}
  */
 export declare namespace IFormulaContext {
+    /**
+     * Options for {@link IFormulaContext.filterHidden}.
+     */
+    interface FilterHiddenOptions {
+        /**
+         * Which axis to filter on.
+         * @defaultValue `IRange.AxisSelection.Row`
+         */
+        axes?: IRange.AxisSelection;
+        /**
+         * Skip the hidden rows or columns only while the range's sheet is filtered: while some
+         * AutoFilter or table on that sheet holds a condition, whether or not it hides a row. Until
+         * then `range` is returned as it is, hidden rows included.
+         *
+         * @remarks
+         * This is `SUBTOTAL` 1-11 (Excel: they "include manually hidden rows", which is what an
+         * unfiltered sheet reads as). `SUBTOTAL` 101-111 and `AGGREGATE` leave it off and skip
+         * always.
+         * @defaultValue false
+         */
+        onlyWhileFiltered?: boolean;
+    }
     /**
      * Options for {@link IFormulaContext.parseAsNumber}.
      */

package/types/src/IRange.d.ts

@@ -787,6 +787,24 @@ export declare namespace IRange {
          * If passing a large bound care must be taken.
          */
         includeEmpty?: boolean;
+        /**
+         * Skips rows of the range: given the next row that would be read, answers the row to read
+         * instead - the same row when it is read, or the next one that is (the previous, when
+         * `reverse`).
+         *
+         * @param index The 0-based row about to be read.
+         * @param reverse Whether the read runs from the last row back.
+         * @returns The row to read, at or past `index`.
+         *
+         * @remarks
+         * A skipped cell is not visited, reads as empty and is left out of the statistics; the shape
+         * of the range is unchanged. `SUBTOTAL` reads a range this way when it skips hidden rows.
+         */
+        processRowSkip?: (index: number, reverse?: boolean) => number;
+        /**
+         * Skips columns of the range, as {@link processRowSkip} skips rows.
+         */
+        processColumnSkip?: (index: number, reverse?: boolean) => number;
         /**
          * Useful for callback functions that want a this.
          */

package/types/src/IRangeStats.d.ts

@@ -160,7 +160,8 @@ export interface IRangeStats {
      *
      * - Every requested type (all types when omitted) is present with an explicit count —
      *   a `0` is a fact about the range, a missing key would be ambiguous.
-     * - Blanks report under {@link ScalarType.Null}: total cells minus non-empty values.
+     * - Blanks report under {@link ScalarType.Null}: total cells minus non-empty values. A cell the
+     *   range skips ({@link IRange.IteratorOptions.processRowSkip}) is not a blank; it is not counted.
      * - Never throws on error values — errors are population here, not faults — regardless of
      *   the `onError` iterator policy the stats were created with.
      */