@origints/xlsx 0.3.2 → 0.4.0

package/dist/xlsx-spec-builder.d.ts

@@ -1,6 +1,24 @@
-import { StepBuilder, ArraySpec, ObjectSpec, ExtractSpec, Spec, SpecLike } from '@origints/core';
-import { XlsxStep, Direction } from './xlsx-spec';
+import { StepBuilder, ArraySpec, ObjectSpec, ExtractSpec, Spec, SpecLike, VariableRefSpec } from '@origints/core';
+import { XlsxStep, Direction, FindAllExtract } from './xlsx-spec';
 import { CellPred, SheetPred, RowPred } from './xlsx-predicate-spec';
+/**
+ * Options for eachSlice iteration.
+ */
+export interface EachSliceOptions {
+    /** Number of columns/rows per group (default: 1). When > 1, each slice anchors at every Nth position. */
+    readonly groupSize?: number;
+}
+/**
+ * Constraints for findAll to narrow the search area.
+ */
+export interface FindAllConstraints {
+    readonly inRow?: number;
+    readonly inCol?: number;
+    readonly startRow?: number;
+    readonly endRow?: number;
+    readonly startCol?: number;
+    readonly endCol?: number;
+}
 /**
  * Spec builder at the cell level — terminal extraction and navigation methods.
  */
@@ -58,9 +76,11 @@ export declare class XlsxCellSB extends StepBuilder<XlsxStep, 'xlsx'> {
      * Each slice is passed as an XlsxSliceSB to the mapper, providing
      * header-relative column/row access via colWhere/rowWhere.
      * The mapper can return a Spec, a FluentSpec, or a plain record (auto-wrapped to ObjectSpec).
+     *
+     * @param options - Optional `{ groupSize: N }` to step by N columns/rows per slice
      */
-    eachSlice<T extends Spec>(direction: Direction, while_: RowPred, itemMapper: (slice: XlsxSliceSB) => T): ArraySpec<T>;
-    eachSlice(direction: Direction, while_: RowPred, itemMapper: (slice: XlsxSliceSB) => Record<string, SpecLike>): ArraySpec<ObjectSpec>;
+    eachSlice<T extends Spec>(direction: Direction, while_: RowPred, itemMapper: (slice: XlsxSliceSB) => T, options?: EachSliceOptions): ArraySpec<T>;
+    eachSlice(direction: Direction, while_: RowPred, itemMapper: (slice: XlsxSliceSB) => Record<string, SpecLike>, options?: EachSliceOptions): ArraySpec<ObjectSpec>;
 }
 /**
  * XLSX extract type for column definitions.
@@ -91,6 +111,10 @@ export declare class XlsxSliceSB extends StepBuilder<XlsxStep, 'xlsx'> {
     col(offset: number): XlsxCellSB;
     /** Access a row by 0-based offset from the anchor (for rotated tables) */
     row(offset: number): XlsxCellSB;
+    /** Navigate to a column whose index comes from a bound variable's CellPosition.col */
+    colAt(ref: VariableRefSpec): XlsxCellSB;
+    /** Navigate to a row whose index comes from a bound variable's CellPosition.row */
+    rowAt(ref: VariableRefSpec): XlsxCellSB;
     /**
      * Extract multiple columns at once, producing an ObjectSpec.
      *
@@ -186,6 +210,17 @@ export declare class XlsxSheetSB extends StepBuilder<XlsxStep, 'xlsx'> {
     findInRow(rowIndex: number, predicate: CellPred): XlsxCellSB;
     /** Find the first cell matching the predicate in the specified column */
     findInCol(colIndex: number, predicate: CellPred): XlsxCellSB;
+    /**
+     * Find all cells matching a predicate, returning CellPosition[].
+     * Use with forEach/flatForEach to iterate over discovered positions.
+     *
+     * @example
+     * ```ts
+     * const headers = $.firstSheet().findAll(cell.equals('Revenue'))
+     * flatForEach(headers, 'hdr', fromRef('hdr').down().eachSlice('down', hasData, ...))
+     * ```
+     */
+    findAll(predicate: CellPred, constraints?: FindAllConstraints): ExtractSpec<XlsxStep, FindAllExtract>;
     /** Find the first cell matching the predicate in the specified range */
     findInRange(rangeRef: string, predicate: CellPred): XlsxCellSB;
     /** Navigate to a range by address (e.g., "A1:C10") */
@@ -218,3 +253,17 @@ export declare class XlsxSpecBuilder extends StepBuilder<XlsxStep, 'xlsx'> {
     /** Find a sheet matching the predicate */
     findSheet(predicate: SheetPred): XlsxSheetSB;
 }
+/**
+ * Create a cell-level spec builder starting from a variable-bound CellPosition.
+ * Use with forEach/flatForEach over findAll results to navigate from discovered positions.
+ *
+ * @example
+ * ```ts
+ * forEach(
+ *   $.firstSheet().findAll(cell.equals('Revenue')),
+ *   'hdr',
+ *   fromRef('hdr').down().string()
+ * )
+ * ```
+ */
+export declare function fromRef(ref: string, path?: readonly (string | number)[]): XlsxCellSB;

package/dist/xlsx-spec.d.ts

@@ -72,6 +72,15 @@ export type XlsxStep = {
     readonly kind: 'rowWhere';
     readonly headerRef: Spec;
     readonly predicate: CellPredicateSpec;
+} | {
+    readonly kind: 'fromRef';
+    readonly ref: string;
+    readonly path?: readonly (string | number)[];
+} | {
+    readonly kind: 'colAtRef';
+    readonly ref: string;
+    readonly path?: readonly (string | number)[];
+    readonly component: 'col' | 'row';
 } | {
     readonly kind: 'range';
     readonly ref: string;
@@ -103,6 +112,32 @@ export interface EachSliceExtract {
     readonly kind: 'eachSlice';
     readonly direction: Direction;
     readonly while: RowPredicateSpec;
+    readonly groupSize?: number;
+}
+/**
+ * Position of a cell in a workbook, used as a variable-bound value
+ * from findAll for dynamic navigation.
+ */
+export interface CellPosition {
+    readonly row: number;
+    readonly col: number;
+    readonly sheetName?: string;
+}
+/**
+ * Specification for finding all cells matching a predicate.
+ * Returns CellPosition[] at runtime.
+ */
+export interface FindAllExtract {
+    readonly kind: 'findAll';
+    readonly predicate: CellPredicateSpec;
+    readonly constraints?: {
+        readonly inRow?: number;
+        readonly inCol?: number;
+        readonly startRow?: number;
+        readonly endRow?: number;
+        readonly startCol?: number;
+        readonly endCol?: number;
+    };
 }
 /**
  * The terminal extraction type for an XLSX value.
@@ -111,7 +146,7 @@ export interface EachSliceExtract {
  * - Range-level (produce arrays): 'rows', 'cells'
  * - Cell-level (produce arrays): EachCellExtract, EachSliceExtract
  */
-export type XlsxExtract = 'string' | 'number' | 'boolean' | 'date' | 'value' | 'formula' | 'rows' | 'cells' | EachCellExtract | EachSliceExtract;
+export type XlsxExtract = 'string' | 'number' | 'boolean' | 'date' | 'value' | 'formula' | 'rows' | 'cells' | EachCellExtract | EachSliceExtract | FindAllExtract;
 /**
  * A complete XLSX extraction spec.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@origints/xlsx",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "XLSX parsing for Origins with full traceability to sheets, ranges, and cells.",
   "type": "module",
   "license": "MIT",
@@ -50,7 +50,7 @@
     "xlsx": "^0.18.5"
   },
   "peerDependencies": {
-    "@origints/core": "^0.3.0"
+    "@origints/core": "^0.4.0"
   },
   "devDependencies": {
     "@origints/core": "workspace:*",