@origints/xlsx 0.2.0 → 0.4.0

package/dist/xlsx-cell.d.ts

@@ -1,6 +1,78 @@
 import { TYPE_LABEL } from '@origints/core';
-import { Cell as ExcelJSCell } from 'exceljs';
 import { XlsxResult, XlsxPath, CellValue, ExtendedCellValue } from './xlsx-result';
+/**
+ * Internal cell data — parser-agnostic representation.
+ * Created by the parser (SheetJS) and consumed by XlsxCell.
+ */
+export interface CellData {
+    readonly address: string;
+    readonly row: number;
+    readonly col: number;
+    /** Resolved value (formula result or plain value). */
+    readonly resolvedValue: CellValue;
+    /** Formula string, if this cell contains a formula. */
+    readonly formula?: string;
+    /** Error string, if this cell contains an error. */
+    readonly error?: string;
+    /** Hyperlink URL. */
+    readonly hyperlink?: string;
+    /** Comment/note text. */
+    readonly comment?: string;
+    /** Number format string. */
+    readonly numFmt?: string;
+    /** Whether this cell is part of a merged range. */
+    readonly isMerged: boolean;
+    /** Address of the master cell if this is a non-master merged cell. */
+    readonly masterAddress?: string;
+    /** Rich text segments (when available from the parser). */
+    readonly richText?: ReadonlyArray<RichTextSegmentData>;
+    /** Cell style data (best-effort, may not be available with all parsers). */
+    readonly style?: CellStyleData;
+}
+/** Rich text segment from the parser. */
+export interface RichTextSegmentData {
+    readonly text: string;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: boolean;
+    readonly strike?: boolean;
+    readonly color?: string;
+    readonly size?: number;
+    readonly font?: string;
+}
+/** Cell style from the parser. */
+export interface CellStyleData {
+    readonly font?: {
+        readonly name?: string;
+        readonly size?: number;
+        readonly bold?: boolean;
+        readonly italic?: boolean;
+        readonly underline?: boolean;
+        readonly strike?: boolean;
+        readonly color?: {
+            readonly argb?: string;
+            readonly theme?: number;
+        };
+    };
+    readonly fill?: {
+        readonly type?: string;
+        readonly pattern?: string;
+        readonly fgColor?: {
+            readonly argb?: string;
+        };
+    };
+    readonly border?: {
+        readonly top?: boolean;
+        readonly bottom?: boolean;
+        readonly left?: boolean;
+        readonly right?: boolean;
+    };
+    readonly alignment?: {
+        readonly horizontal?: string;
+        readonly vertical?: string;
+        readonly wrapText?: boolean;
+    };
+}
 /**
  * Cell style information.
  */
@@ -52,23 +124,28 @@ export interface RichTextContent {
     readonly hyperlink?: string;
 }
 /**
- * A wrapper around ExcelJS Cell with full metadata preservation.
+ * A wrapper around cell data with full metadata preservation.
  *
  * XlsxCell enables typed extraction of cell values while maintaining
  * provenance information. Each cell knows its exact location in the
  * workbook, allowing full traceability.
  */
 export declare class XlsxCell {
-    private readonly cell;
+    private readonly _data;
     private readonly _path;
     private readonly _sheetName;
     get [TYPE_LABEL](): string;
     private constructor();
     /**
-     * Creates an XlsxCell from an ExcelJS cell.
+     * Creates an XlsxCell from internal cell data.
      * @internal
      */
-    static fromExcelJS(cell: ExcelJSCell, sheetName: string, file?: string): XlsxCell;
+    static create(data: CellData, sheetName: string, file?: string): XlsxCell;
+    /**
+     * Creates an empty cell for the given coordinates.
+     * @internal
+     */
+    static empty(row: number, col: number, sheetName: string, file?: string): XlsxCell;
     /**
      * Returns the cell address (e.g., "A1").
      */
@@ -123,18 +200,10 @@ export declare class XlsxCell {
     formula(): XlsxResult<string>;
     /**
      * Get the cell content as rich text with formatting preserved.
-     * Returns segments with their individual formatting properties.
      */
     richText(): XlsxResult<RichTextContent>;
     /**
      * Get the cell content as Markdown.
-     *
-     * Converts cell content including:
-     * - Bold text -> **text**
-     * - Italic text -> *text*
-     * - Strikethrough -> ~~text~~
-     * - Hyperlinks -> [text](url)
-     * - Rich text segments with mixed formatting
      */
     markdown(): XlsxResult<string>;
     /**
@@ -195,17 +264,13 @@ export declare class XlsxCell {
      */
     getOffsetCell(rowDelta: number, colDelta: number, getCell: (row: number, col: number) => XlsxCell | undefined): XlsxResult<XlsxCell>;
     /**
-     * Get the raw value, handling ExcelJS value types.
+     * Get the raw value, handling formula/error types.
      */
     private getRawValue;
     /**
      * Get the resolved value (formula result or plain value).
      */
     private getResolvedValue;
-    /**
-     * Normalize a formula result value.
-     */
-    private normalizeResult;
     /**
      * Convert Excel date number to JavaScript Date.
      * Excel dates are days since 1900-01-01 (with a leap year bug).

package/dist/xlsx-predicate-compiler.d.ts

@@ -1,11 +1,15 @@
+import { SpecScope } from '@origints/core';
 import { XlsxSheet } from './xlsx-sheet';
 import { CellPredicate } from './xlsx-query';
 import { SheetPredicate } from './xlsx-workbook';
 import { CellPredicateSpec, SheetPredicateSpec, RowPredicateSpec } from './xlsx-predicate-spec';
 /**
  * Compile a CellPredicateSpec AST into a runtime CellPredicate closure.
+ *
+ * @param spec - The predicate spec to compile
+ * @param scope - Optional scope for variable reference predicates (equalsRef, containsRef)
  */
-export declare function compileCellPredicate(spec: CellPredicateSpec): CellPredicate;
+export declare function compileCellPredicate(spec: CellPredicateSpec, scope?: SpecScope): CellPredicate;
 /**
  * Compile a SheetPredicateSpec AST into a runtime SheetPredicate closure.
  */
@@ -13,5 +17,8 @@ export declare function compileSheetPredicate(spec: SheetPredicateSpec): SheetPr
 export type RowPredicate = (sheet: XlsxSheet, row: number, anchorCol: number) => boolean;
 /**
  * Compile a RowPredicateSpec AST into a runtime RowPredicate closure.
+ *
+ * @param spec - The row predicate spec to compile
+ * @param scope - Optional scope for variable reference predicates
  */
-export declare function compileRowPredicate(spec: RowPredicateSpec): RowPredicate;
+export declare function compileRowPredicate(spec: RowPredicateSpec, scope?: SpecScope): RowPredicate;

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

@@ -1,3 +1,4 @@
+import { PredicateWrapper } from '@origints/core';
 import { CellValue } from './xlsx-result';
 export type CellPredicateSpec = {
     readonly kind: 'equals';
@@ -60,6 +61,20 @@ export type CellPredicateSpec = {
     readonly kind: 'hasHyperlink';
 } | {
     readonly kind: 'hasComment';
+} | {
+    readonly kind: 'equalsRef';
+    readonly ref: string;
+    readonly path?: readonly (string | number)[];
+} | {
+    readonly kind: 'containsRef';
+    readonly ref: string;
+    readonly path?: readonly (string | number)[];
+    readonly caseSensitive: boolean;
+} | {
+    readonly kind: 'startsWithRef';
+    readonly ref: string;
+    readonly path?: readonly (string | number)[];
+    readonly caseSensitive: boolean;
 } | {
     readonly kind: 'and';
     readonly left: CellPredicateSpec;
@@ -100,20 +115,8 @@ export type SheetPredicateSpec = {
     readonly kind: 'not';
     readonly operand: SheetPredicateSpec;
 };
-export interface CellPred {
-    readonly _spec: CellPredicateSpec;
-    and(other: CellPred): CellPred;
-    or(other: CellPred): CellPred;
-    not(): CellPred;
-    describe(): string;
-}
-export interface SheetPred {
-    readonly _spec: SheetPredicateSpec;
-    and(other: SheetPred): SheetPred;
-    or(other: SheetPred): SheetPred;
-    not(): SheetPred;
-    describe(): string;
-}
+export type CellPred = PredicateWrapper<CellPredicateSpec>;
+export type SheetPred = PredicateWrapper<SheetPredicateSpec>;
 export declare const cell: Readonly<{
     equals: (value: CellValue) => CellPred;
     contains: (text: string, caseSensitive?: boolean) => CellPred;
@@ -138,6 +141,45 @@ export declare const cell: Readonly<{
     isItalic: () => CellPred;
     hasHyperlink: () => CellPred;
     hasComment: () => CellPred;
+    /**
+     * Match when cell value equals a bound variable from ForEachSpec scope.
+     *
+     * @example
+     * ```ts
+     * forEach(
+     *   $.get('companies').strings(),
+     *   'company',
+     *   xlsxSB.firstSheet().find(cell.equalsRef('company')).string()
+     * )
+     * ```
+     */
+    equalsRef: (ref: string, path?: readonly (string | number)[]) => CellPred;
+    /**
+     * Match when cell string value contains a bound variable from ForEachSpec scope.
+     *
+     * @example
+     * ```ts
+     * forEach(
+     *   $.get('keywords').strings(),
+     *   'keyword',
+     *   xlsxSB.firstSheet().find(cell.containsRef('keyword')).string()
+     * )
+     * ```
+     */
+    containsRef: (ref: string, path?: readonly (string | number)[], caseSensitive?: boolean) => CellPred;
+    /**
+     * Match when cell string value starts with a bound variable from ForEachSpec scope.
+     *
+     * @example
+     * ```ts
+     * forEach(
+     *   $.get('companies').strings(),
+     *   'company',
+     *   xlsxSB.firstSheet().find(cell.startsWithRef('company')).string()
+     * )
+     * ```
+     */
+    startsWithRef: (ref: string, path?: readonly (string | number)[], caseSensitive?: boolean) => CellPred;
 }>;
 export declare const sheet: Readonly<{
     nameEquals: (name: string) => SheetPred;
@@ -163,13 +205,7 @@ export type RowPredicateSpec = {
     readonly kind: 'not';
     readonly operand: RowPredicateSpec;
 };
-export interface RowPred {
-    readonly _spec: RowPredicateSpec;
-    and(other: RowPred): RowPred;
-    or(other: RowPred): RowPred;
-    not(): RowPred;
-    describe(): string;
-}
+export type RowPred = PredicateWrapper<RowPredicateSpec>;
 export declare function rowCol(offset: number, predicate: CellPred): RowPred;
 export declare function describeRowPredicate(spec: RowPredicateSpec): string;
 export declare function describeSheetPredicate(spec: SheetPredicateSpec): string;

package/dist/xlsx-range.d.ts

@@ -1,8 +1,12 @@
 import { TYPE_LABEL } from '@origints/core';
-import { Worksheet } from 'exceljs';
 import { XlsxCell } from './xlsx-cell';
 import { XlsxResult, XlsxPath, CellValue } from './xlsx-result';
 import { CellPredicate } from './xlsx-query';
+/**
+ * Cell accessor function — resolves a cell by 1-based row/col.
+ * Provided by XlsxSheet so XlsxRange is decoupled from sheet internals.
+ */
+export type CellAccessor = (row: number, col: number) => XlsxResult<XlsxCell>;
 /**
  * A range of cells in an XLSX sheet.
  *
@@ -11,7 +15,7 @@ import { CellPredicate } from './xlsx-query';
  * and conversion to various formats.
  */
 export declare class XlsxRange {
-    private readonly worksheet;
+    private readonly _getCell;
     private readonly _startRow;
     private readonly _startCol;
     private readonly _endRow;
@@ -25,12 +29,12 @@ export declare class XlsxRange {
      * Creates an XlsxRange from coordinates.
      * @internal
      */
-    static fromCoords(worksheet: Worksheet, startRow: number, startCol: number, endRow: number, endCol: number, sheetName: string, file?: string): XlsxRange;
+    static fromCoords(getCell: CellAccessor, startRow: number, startCol: number, endRow: number, endCol: number, sheetName: string, file?: string): XlsxRange;
     /**
      * Creates an XlsxRange from an address string.
      * @internal
      */
-    static fromAddress(worksheet: Worksheet, address: string, sheetName: string, file?: string): XlsxResult<XlsxRange>;
+    static fromAddress(getCell: CellAccessor, address: string, sheetName: string, file?: string): XlsxResult<XlsxRange>;
     /**
      * Returns the range address (e.g., "A1:C10").
      */

package/dist/xlsx-sheet.d.ts

@@ -1,10 +1,9 @@
 import { TYPE_LABEL } from '@origints/core';
-import { Worksheet } from 'exceljs';
-import { XlsxCell } from './xlsx-cell';
+import { CellData, XlsxCell } from './xlsx-cell';
 import { XlsxRange } from './xlsx-range';
-import { XlsxCursor } from './xlsx-cursor';
-import { XlsxResult, XlsxPath, CellValue } from './xlsx-result';
+import { XlsxResult, XlsxPath } from './xlsx-result';
 import { CellPredicate } from './xlsx-query';
+import { XlsxCursor } from './xlsx-cursor';
 /**
  * Dimensions of a sheet's used range.
  */
@@ -17,23 +16,30 @@ export interface SheetDimensions {
     readonly colCount: number;
 }
 /**
- * A wrapper around ExcelJS Worksheet with navigation and query capabilities.
+ * A wrapper around sheet data with navigation and query capabilities.
  *
  * XlsxSheet provides a rich API for navigating cells, ranges, and rows
  * within a worksheet. It supports predicate-based queries and cursor-based
  * navigation for complex data extraction scenarios.
  */
 export declare class XlsxSheet {
-    private readonly worksheet;
+    get [TYPE_LABEL](): string;
+    /** Cell data from the parser — keyed by row*16384+col. */
+    private readonly _cells;
+    /** Cache for XlsxCell wrappers — avoids repeated creation. */
+    private readonly _cellCache;
+    private readonly _dims;
+    private readonly _name;
+    private readonly _index;
+    private readonly _mergeRanges;
     private readonly _path;
     private readonly _file?;
-    get [TYPE_LABEL](): string;
     private constructor();
     /**
-     * Creates an XlsxSheet from an ExcelJS worksheet.
+     * Creates an XlsxSheet from internal data.
      * @internal
      */
-    static fromExcelJS(worksheet: Worksheet, file?: string): XlsxSheet;
+    static create(cells: Map<number, CellData>, dims: SheetDimensions, name: string, index: number, mergeRanges: string[], file?: string): XlsxSheet;
     /**
      * Returns the sheet name.
      */
@@ -57,7 +63,7 @@ export declare class XlsxSheet {
     /**
      * Get the value of a cell directly.
      */
-    getValue(address: string): XlsxResult<CellValue>;
+    getValue(address: string): XlsxResult<import('./xlsx-result').CellValue>;
     /**
      * Get a range by its address (e.g., "A1:C10").
      */
@@ -109,7 +115,7 @@ export declare class XlsxSheet {
     /**
      * Find the first cell with the specified value.
      */
-    findValue(value: CellValue): XlsxResult<XlsxCell>;
+    findValue(value: import('./xlsx-result').CellValue): XlsxResult<XlsxCell>;
     /**
      * Find cells within a specific range matching the predicate.
      */
@@ -138,11 +144,6 @@ export declare class XlsxSheet {
      * Check if a cell is part of a merged range.
      */
     isMerged(address: string): boolean;
-    /**
-     * Get the underlying ExcelJS worksheet.
-     * @internal
-     */
-    getWorksheet(): Worksheet;
     /**
      * Get a cell by coordinates for internal use.
      * @internal

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

@@ -1,11 +1,29 @@
-import { ArraySpec, ExtractSpec, Spec } 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.
  */
-export declare class XlsxCellSB {
-    private readonly steps;
+export declare class XlsxCellSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
     /** @internal */
     constructor(steps: readonly XlsxStep[]);
     /** @internal Expose steps for colWhere/rowWhere headerRef */
@@ -22,6 +40,16 @@ export declare class XlsxCellSB {
     value(): ExtractSpec<XlsxStep, 'value'>;
     /** Extract cell formula */
     formula(): ExtractSpec<XlsxStep, 'formula'>;
+    /** Extract cell value as string, returning default on failure */
+    optionalString(defaultValue?: unknown): ExtractSpec<XlsxStep, 'string'>;
+    /** Extract cell value as number, returning default on failure */
+    optionalNumber(defaultValue?: unknown): ExtractSpec<XlsxStep, 'number'>;
+    /** Extract cell value as boolean, returning default on failure */
+    optionalBoolean(defaultValue?: unknown): ExtractSpec<XlsxStep, 'boolean'>;
+    /** Extract cell value as Date, returning default on failure */
+    optionalDate(defaultValue?: unknown): ExtractSpec<XlsxStep, 'date'>;
+    /** Extract raw cell value, returning default on failure */
+    optionalValue(defaultValue?: unknown): ExtractSpec<XlsxStep, 'value'>;
     /** Move right by count cells (default 1) */
     right(count?: number): XlsxCellSB;
     /** Move left by count cells (default 1) */
@@ -39,21 +67,40 @@ export declare class XlsxCellSB {
     /**
      * Iterate over cells from this position in a direction while the predicate matches.
      * Returns an ArraySpec whose items are produced by the itemMapper.
+     * The mapper can return a Spec, a FluentSpec, or a plain record (auto-wrapped to ObjectSpec).
      */
     eachCell<T extends Spec>(direction: Direction, while_: CellPred, itemMapper: (cell: XlsxCellSB) => T): ArraySpec<T>;
+    eachCell(direction: Direction, while_: CellPred, itemMapper: (cell: XlsxCellSB) => Record<string, SpecLike>): ArraySpec<ObjectSpec>;
     /**
      * Iterate over slices (rows or columns) from this cell position.
      * 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<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.
+ */
+export type XlsxExtractType = 'string' | 'number' | 'boolean' | 'date' | 'value' | 'formula';
+/**
+ * Column definition for XLSX `columns()` shorthand.
+ *
+ * - `CellPred` — `colWhere(header, pred).string()`
+ * - `[CellPred, XlsxExtractType]` — `colWhere(header, pred).{type}()`
+ * - `[number, XlsxExtractType?]` — `col(offset).{type ?? 'string'}()`
+ * - `SpecLike` — passthrough (any Spec or FluentSpec)
+ */
+export type XlsxColumnDef = CellPred | [CellPred, XlsxExtractType] | [number, XlsxExtractType?] | SpecLike;
 /**
  * Spec builder for items within a slice (row or column section).
  * Provides header-relative column/row access.
  */
-export declare class XlsxSliceSB {
-    private readonly steps;
+export declare class XlsxSliceSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
     /** @internal */
     constructor(steps: readonly XlsxStep[]);
     /** Access a column by matching its header cell against a predicate (header-relative) */
@@ -64,13 +111,33 @@ export declare class XlsxSliceSB {
     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.
+     *
+     * @example
+     * ```ts
+     * row.columns(header, {
+     *   name: cell.equals('Investment'),               // colWhere(header, pred).string()
+     *   amount: [cell.contains('Amount'), 'number'],   // colWhere(header, pred).number()
+     *   note: [2, 'string'],                            // col(2).string()
+     *   custom: fluent(row.col(0).string()).map(v => v.trim(), 'trim'),  // passthrough
+     * })
+     * ```
+     */
+    columns(headerRef: XlsxCellSB, mapping: Record<string, XlsxColumnDef>): ObjectSpec;
+    /** @internal Resolve a single column definition to a Spec */
+    private _resolveColumnDef;
 }
 /**
  * Spec builder for items within a row (receives an XlsxRange representing one row).
  * Provides column access to navigate within the row.
  */
-export declare class XlsxRowItemSB {
-    private readonly steps;
+export declare class XlsxRowItemSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
     /** @internal */
     constructor(steps: readonly XlsxStep[]);
     /** Access a column by 1-based index within the row */
@@ -81,8 +148,8 @@ export declare class XlsxRowItemSB {
 /**
  * Spec builder at the range level — cell navigation, rows, and cells collection.
  */
-export declare class XlsxRangeSB {
-    private readonly steps;
+export declare class XlsxRangeSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
     /** @internal */
     constructor(steps: readonly XlsxStep[]);
     /** Navigate to a cell by address within the range */
@@ -105,8 +172,8 @@ export declare class XlsxRangeSB {
 /**
  * Spec builder at the row level.
  */
-export declare class XlsxRowSB {
-    private readonly steps;
+export declare class XlsxRowSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
     /** @internal */
     constructor(steps: readonly XlsxStep[]);
     /** Navigate to a cell by address within this row */
@@ -117,8 +184,8 @@ export declare class XlsxRowSB {
 /**
  * Spec builder at the column level.
  */
-export declare class XlsxColSB {
-    private readonly steps;
+export declare class XlsxColSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
     /** @internal */
     constructor(steps: readonly XlsxStep[]);
     /** Navigate to a cell by address within this column */
@@ -129,8 +196,8 @@ export declare class XlsxColSB {
 /**
  * Spec builder at the sheet level — cell, range, row, column, and search navigation.
  */
-export declare class XlsxSheetSB {
-    private readonly steps;
+export declare class XlsxSheetSB extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
     /** @internal */
     constructor(steps: readonly XlsxStep[]);
     /** Navigate to a cell by address (e.g., "A1", "B2") */
@@ -143,6 +210,17 @@ export declare class XlsxSheetSB {
     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") */
@@ -161,8 +239,8 @@ export declare class XlsxSheetSB {
  *
  * Used as `$` in `emit()` after `.mapIn(parseXlsx())`.
  */
-export declare class XlsxSpecBuilder {
-    private readonly steps;
+export declare class XlsxSpecBuilder extends StepBuilder<XlsxStep, 'xlsx'> {
+    protected get format(): "xlsx";
     private constructor();
     /** Create a root spec builder */
     static root(): XlsxSpecBuilder;
@@ -175,3 +253,17 @@ export declare class XlsxSpecBuilder {
     /** 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-executor.d.ts

@@ -1,4 +1,4 @@
-import { TYPE_LABEL, ExtractionResult } from '@origints/core';
+import { TYPE_LABEL, ExtractionResult, SpecScope } from '@origints/core';
 import { XlsxSpec } from './xlsx-spec';
 import { XlsxWorkbook } from './xlsx-workbook';
 import { XlsxSheet } from './xlsx-sheet';
@@ -22,4 +22,4 @@ export declare class XlsxSliceContext {
  * - XlsxRange → starts at range level (used for row items)
  * - XlsxCell → starts at cell level (used for cell items)
  */
-export declare function executeXlsxSpec(spec: XlsxSpec, data: unknown): ExtractionResult<unknown>;
+export declare function executeXlsxSpec(spec: XlsxSpec, data: unknown, scope?: SpecScope): ExtractionResult<unknown>;