@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

package/types/src/scripting/enumManifest.browser.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser loader for the script enum-runtime manifest (`scripting-enums.json`).
+ *
+ * Selected via the `@sheetxl/sdk/scripting/enumManifest` conditional export (the `browser`/`default`
+ * condition). Mirrors react's ScriptEditor `loadGlobalTypes`: the local dev asset, else the published
+ * CDN copy. Keeping this browser-only keeps node builtins out of browser bundles entirely.
+ */
+export declare function loadEnumManifest(): Promise<any>;
+//# sourceMappingURL=enumManifest.browser.d.ts.map

package/types/src/scripting/enumManifest.browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enumManifest.browser.d.ts","sourceRoot":"","sources":["../../../../src/scripting/enumManifest.browser.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,GAAG,CAAC,CASrD"}

package/types/src/scripting/enumManifest.node.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Node loader for the script enum-runtime manifest (`scripting-enums.json`).
+ *
+ * Selected via the `@sheetxl/sdk/scripting/enumManifest` conditional export (the `node` condition).
+ * Reads the published asset from disk (no network at execution time). The module's location varies
+ * (published `node/esm/`, possibly chunked, vs in-repo `src/scripting/`), so walk UP from this module
+ * looking for the nearest enclosing package's `types/` (published) or `build/types/` (dev).
+ *
+ * Because this file is only ever resolved under the `node` condition, browser bundlers never see the
+ * `node:*` imports above — that is the whole point of the conditional export (vs. runtime detection).
+ */
+export declare function loadEnumManifest(): Promise<any>;
+//# sourceMappingURL=enumManifest.node.d.ts.map

package/types/src/scripting/enumManifest.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enumManifest.node.d.ts","sourceRoot":"","sources":["../../../../src/scripting/enumManifest.node.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,GAAG,CAAC,CAerD"}

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

@@ -0,0 +1,4 @@
+export * from './IScript';
+export * from './IModule';
+export * from './IFunctionCollection';
+//# sourceMappingURL=index.d.ts.map

package/types/src/scripting/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/scripting/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAE1B,cAAc,uBAAuB,CAAC"}

package/types/src/selection/IRangeSelection.d.ts

@@ -0,0 +1,307 @@
+import { IRange } from '@sheetxl/primitives';
+import { SelectionCoords as WellKnownSelectionCoords, RunCoordValue } from '@sheetxl/utils';
+import { IListener } from '../listener';
+import { ICell } from '../cell';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { ISheet } from '../sheet';
+/**
+ * Interface representing a range selection within a sheet.
+ */
+export interface IRangeSelection {
+    /**
+     * Navigates the sheet.
+     *
+     * @param direction The direction to navigate.
+     * @param select Whether to select the cell after navigating.
+     * @param contentful Whether to navigate to contentful cells only.
+     * @param incrementAmount The amount to increment.
+     */
+    navigate(direction: IRange.Direction, select?: boolean, contentful?: boolean, incrementAmount?: number): this;
+    /**
+     * Traverses the selection, moving to the next cell based on the axis.
+     *
+     * @param axis The axis to traverse. Default is `ICellRange.Axis.Row`.
+     * @param reverse Whether to traverse in reverse. Default is false.
+     * @param region An optional bounding region to *wrap within* when there is no explicit selection (a
+     *   bare cursor) — e.g. a table's data range, so Tab/Enter cycle inside it instead of walking off its
+     *   edge. Resolving this region is the caller's job (the view's `getRegionBounds`); omit it (the bare
+     *   sheet) and a bare-cursor traverse is a plain move.
+     *
+     * @remarks Useful for pressing tab or enter from the UI.
+     */
+    traverse(axis?: IRange.Axis, reverse?: boolean, region?: IRange.Coords): this;
+    /**
+     * Cycles the active cell around the four **visible** corners of the active range: TL → TR → BL → BR
+     * → TL. Each corner is snapped inward past hidden rows/columns (via the same hidden-skip the sheet
+     * uses for {@link navigate}/{@link traverse}), so the active cell never lands on an unseen header.
+     * A no-op when there is no selection.
+     *
+     * @remarks Useful for pressing Ctrl+. from the UI.
+     */
+    traverseCorners(): this;
+    /**
+     * Clear the hidden cells from the selection.
+     * Each selected range is split around the hidden row/column runs it spans (the {@link clear}/deselect
+     * operation, targeting hidden cells), leaving the selection over only its visible cells, as separate rectangles.
+     * The anchor cell stays put when it is visible and snaps to the first visible piece when it isn't.
+     * A no-op when the whole selection is hidden.
+     */
+    clearHidden(): this;
+    /**
+     * Selects the surrounding region and returns the new range.
+     */
+    selectRegion(options?: IRangeSelection.SelectRegionOptions): Promise<ICellRange>;
+    /**
+     * Returns the coordinates of the selection.
+     *
+     * @returns The selection coordinates.
+     */
+    getCoords(): IRangeSelection.Coords;
+    /**
+     * Updates the selection coordinates.
+     *
+     * @param coords The new coordinates.
+     * @returns The current instance.
+     */
+    updateCoords(coords: IRangeSelection.Coords): this;
+    /**
+     * Returns the **anchor** sheet — the sheet this selection is bound to for all coordinate math (merges,
+     * hidden headers, bounds) and the sheet a coord with no explicit `scope` belongs to.
+     *
+     * @remarks
+     * A selection's *ranges* may span multiple sheets (each range/cell carries its own optional `scope`
+     * sheet name — e.g. a formula's cross-sheet references), but the selection itself is always anchored to
+     * one sheet: the one it was constructed with (or, for a {@link create} picker, the sheet it was
+     * derived from). This is that sheet — the analog of {@link ICellRange.getSheet} for a selection.
+     */
+    getSheet(): ISheet;
+    /**
+     * Returns the selected cell.
+     */
+    getCell(): ICell;
+    /**
+     * Returns a first range.
+     */
+    getRange(options?: ICellRange.GetRangeOptions): ICellRange;
+    /**
+     * Returns ranges of cells for the current selection.
+     */
+    getRanges(options?: ICellRange.GetRangeOptions): ICellRanges;
+    /**
+     * Updates the selection using a new start and end.
+     *
+     * @param start The start cell.
+     * @param end The end cell. Default is the start cell.
+     * @param anchor The anchor cell.
+     */
+    clearAndModify(start: Partial<IRange.CellCoords>, end?: Partial<IRange.CellCoords>, anchor?: Partial<IRange.CellCoords>): void;
+    /**
+     * Modifies the selection around the anchor.
+     *
+     * @param cellAnchor The anchor cell.
+     * @param cellPivot The pivot cell.
+     * @param resetAnchor Whether to reset the anchor. Default is false.
+     */
+    modify(cellAnchor: Partial<IRange.CellCoords>, cellPivot?: Partial<IRange.CellCoords>, resetAnchor?: boolean): void;
+    /**
+     * Clears the range selections.
+     *
+     * @remarks This does not affect the cell.
+     */
+    clear(): void;
+    /**
+     * Appends a selection to the current selection.
+     *
+     * @param start The start cell.
+     * @param end The end cell. Default is the start cell.
+     * @param anchor The anchor cell.
+     * @remarks This is used to support the CMD key behavior in the UI.
+     */
+    append(start: IRange.CellCoords, end?: IRange.CellCoords, anchor?: Partial<IRange.CellCoords>): void;
+    /**
+     * A special range used during drag.
+     * @param range The range or null.
+     *
+     * @remarks
+     * This fires an event.
+     */
+    setAdjusting(range: IRangeSelection.Coords | null): void;
+    /**
+     * Returns the adjusting range.
+     */
+    getAdjusting(): IRangeSelection | null;
+    /**
+     * Creates a **detached, transient** selection over the *same sheet*.
+     *
+     * @remarks
+     * The returned selection is not the sheet's primary selection and is not registered on any view.
+     * It shares the sheet for all coordinate math (merges, hidden headers, bounds) but its coords are
+     * independent — mutating it never affects `sheet.getSelection()` and vice versa. Nothing needs to
+     * be disposed: it holds no sheet-level listeners, so it is reclaimed when the last reference is
+     * dropped.
+  
+     * Unspecified options default to this selection's own (`shapePolicy`, `navigationPolicy`); coords
+     * default to empty.
+     */
+    createSelection(options?: IRangeSelection.CreateTemporaryOptions): IRangeSelection;
+    /**
+     * Checks if the entire range is selected.
+     *
+     * @returns True if the entire range is selected, otherwise false.
+     */
+    isEntire(): boolean;
+    /**
+     * Projects the selection onto a header `axis` as contiguous runs of selected headers.
+     *
+     * @remarks
+     * Each run's `value` is `isSelectedAll` — whether that span covers the opposite axis entirely (an
+     * entire-row/column selection). Derived purely from the selection's coords (and the sheet's entire
+     * range), so it works for any selection — the primary or a detached {@link IRangeSelection.create}
+     * picker — and is what the header selection layer renders.
+     */
+    getSelectedRuns(axis: IRange.Axis): readonly RunCoordValue<boolean>[];
+    /**
+     * Checks if the selection is equal to another selection.
+     *
+     * @param other The other selection to compare against.
+     */
+    isEquals(other: IRangeSelection): boolean;
+    /**
+     * Checks if the top row or left column is selected.
+     */
+    hasTopOrLeft(): boolean;
+    /**
+     * Adds listeners to the selection.
+     * @param listeners The listeners to add.
+     * @param options Options for the listeners.
+     * @returns A function to remove the listeners.
+     */
+    addListeners(listeners: IRangeSelection.IListeners, options?: IListener.Options): IListener.Remove;
+}
+/**
+ * {@inheritDoc IRangeSelection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IRangeSelection}
+ */
+export declare namespace IRangeSelection {
+    /**
+   * Represents a selection of ranges with an active range and an active cell.
+   */
+    type Coords = WellKnownSelectionCoords;
+    /**
+     * How the selection represents its ranges — in particular whether a single cell is kept as a
+     * `1×1` range or collapsed to a bare anchor cell, and how many ranges are allowed.
+     *
+     * - `'cell'` — a single anchor cell; no ranges (`modify` / `append` are no-ops).
+     * - `'range'` — exactly one range; a single-cell pick is **kept as a `1×1` range** (`append` is a
+     *   no-op). For a one-range picker (a `RangeInput`).
+     * - `'ranges'` — many ranges, each **kept as a `1×1` range** when single-cell. For a multi-range
+     *   picker (a formula's references, a chart's data ranges).
+     * - `'mixed'` *(default)* — many ranges, but a lone single cell **collapses to the bare anchor
+     *   cell** (`ranges: []`). The spreadsheet selection: the cursor is a cell, not a 1×1 outline.
+     */
+    type ShapePolicy = 'cell' | 'range' | 'ranges' | 'mixed';
+    /**
+     * What a **navigation** (a plain, non-extending arrow move) does to the current selection — orthogonal
+     * to {@link ShapePolicy}, which governs the resulting *shape*:
+     * - `'clear'` *(default)* — drop the whole selection back to the single anchor cell (the spreadsheet
+     *   cursor: an arrow moves the cursor and forgets any multi-selection).
+     * - `'modify'` — re-scope the **active** range in place, **preserving the other ranges** (a range
+     *   picker moving one reference of many; the sibling references stay put).
+     */
+    type NavigationPolicy = 'clear' | 'modify';
+    /**
+     * Events for {@link IRangeSelection}.
+     */
+    interface Events {
+        /**
+         * Called when the selection changes.
+         *
+         * @param source The source of the event.
+         */
+        onChange?(source: IRangeSelection): void;
+        /**
+         * Called when the selection is adjusting.
+         *
+         * @param source The source of the event.
+         */
+        onAdjustingChange?(source: IRangeSelection): void;
+    }
+    /**
+     * Options for selecting a region.
+     */
+    interface SelectRegionOptions extends ICellRange.SelectOptions {
+        /**
+         * Whether to select content only.
+         */
+        contentOnly: boolean;
+        /**
+         * Whether to select the entire region.
+         */
+        entireRegion?: boolean;
+        /**
+         * Restrict the region to entire rows/columns along an axis, filling the enclosing region on that
+         * axis while **bounding** the *other* axis to the current active range. Named for what is selected
+         * (Excel's `Ctrl+Space` / `Shift+Space`):
+         * - `Column` — select the column(s): fill the region's **rows**, keep the current columns.
+         * - `Row` — select the row(s): fill the region's **columns**, keep the current rows.
+         * - `Both` — select the entire region on both axes.
+         *
+         * Applied to this selection's active range in place (so it also drives a temporary picker selection
+         * and preserves the other ranges), unlike the whole-selection {@link entireRegion}.
+         *
+         * @defaultValue `IRange.AxisSelection.Both`
+         */
+        axis?: IRange.AxisSelection;
+    }
+    /**
+     * Listeners for IRangeSelection events.
+     */
+    interface IListeners extends IListener.Callbacks<IRangeSelection, Events> {
+    }
+    /**
+     * Options for constructing an IRangeSelection.
+     */
+    interface ConstructorOptions {
+        /**
+         * The sheet to which the selection belongs.
+         */
+        sheet: ISheet;
+        /**
+         * Initial selection coordinates.
+         */
+        coords?: IRangeSelection.Coords;
+        /**
+         * How the selection represents its ranges (shape invariant). @see {@link ShapePolicy}
+         */
+        shapePolicy?: IRangeSelection.ShapePolicy;
+        /**
+         * What a plain arrow move does to the selection. @see {@link NavigationPolicy}
+         */
+        navigationPolicy?: IRangeSelection.NavigationPolicy;
+    }
+    /**
+     * Options for {@link IRangeSelection.create}.
+     *
+     * @remarks
+     * The temporary selection reuses the source selection's sheet, so `sheet` is not accepted here.
+     */
+    interface CreateTemporaryOptions {
+        /**
+         * Initial selection coordinates. Defaults to empty.
+         */
+        coords?: IRangeSelection.Coords;
+        /**
+         * How the selection represents its ranges (shape invariant). Defaults to the source's.
+         * @see {@link ShapePolicy}
+         */
+        shapePolicy?: IRangeSelection.ShapePolicy;
+        /**
+         * What a plain arrow move does to the selection. Defaults to the source's. @see {@link NavigationPolicy}
+         */
+        navigationPolicy?: IRangeSelection.NavigationPolicy;
+    }
+}
+//# sourceMappingURL=IRangeSelection.d.ts.map

package/types/src/selection/IRangeSelection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IRangeSelection.d.ts","sourceRoot":"","sources":["../../../../src/selection/IRangeSelection.ts"],"names":[],"mappings":"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"}

package/types/src/selection/RangeSelection.d.ts

@@ -0,0 +1,144 @@
+import { IRange } from '@sheetxl/primitives';
+import { RunCoordValue } from '@sheetxl/utils';
+import { IListener } from '../listener';
+import { ICell } from '../cell';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { ISheet } from '../sheet';
+import { IRangeSelection } from './IRangeSelection';
+import { ListenerEmitter } from '../listener/ListenerEmitter';
+/**
+ * Used for managing selection of a range.
+ */
+export declare class RangeSelection {
+    protected _sheet: ISheet;
+    protected _coords: Required<IRangeSelection.Coords>;
+    protected _navigationPolicy: IRangeSelection.NavigationPolicy;
+    protected _shapePolicy: IRangeSelection.ShapePolicy;
+    protected _magicCell: IRange.CellCoords | null;
+    protected _adjusting: IRangeSelection.Coords | null;
+    protected _firstActiveCoords: IRange.CellCoords | null;
+    protected _cache: _ReadCache;
+    protected _emitter: ListenerEmitter<RangeSelection, IRangeSelection.IListeners>;
+    constructor(options: IRangeSelection.ConstructorOptions);
+    /** {@inheritDoc IRangeSelection.navigate} */
+    navigate(direction: IRange.Direction, select?: boolean, contentful?: boolean, incrementAmount?: number): this;
+    /** {@inheritDoc IRangeSelection.getCoords} */
+    getCoords(): IRangeSelection.Coords;
+    /** {@inheritDoc IRangeSelection.hasTopOrLeft} */
+    hasTopOrLeft(): boolean;
+    /** {@inheritDoc IRangeSelection.getSheet} */
+    getSheet(): ISheet;
+    /** {@inheritDoc IRangeSelection.getCell} */
+    getCell(): ICell;
+    /** {@inheritDoc IRangeSelection.getRange} */
+    getRange(options?: ICellRange.GetRangeOptions): ICellRange;
+    /** {@inheritDoc IRangeSelection.getRanges} */
+    getRanges(options?: ICellRange.GetRangeOptions): ICellRanges;
+    /** {@inheritDoc IRangeSelection.updateCoords} */
+    updateCoords(coords: IRangeSelection.Coords): this;
+    /** {@inheritDoc IRangeSelection.isEntire} */
+    isEntire(): boolean;
+    /** {@inheritDoc IRangeSelection.getSelectedRuns} */
+    getSelectedRuns(axis: IRange.Axis): readonly RunCoordValue<boolean>[];
+    /** {@inheritDoc IRangeSelection.isEquals} */
+    isEquals(other: IRangeSelection): boolean;
+    /** {@inheritDoc IRangeSelection.traverse} */
+    traverse(axis?: IRange.Axis, reverse?: boolean, region?: IRange.Coords): this;
+    /** {@inheritDoc IRangeSelection.traverseCorners} */
+    traverseCorners(): this;
+    /** {@inheritDoc IRangeSelection.clearHidden} */
+    clearHidden(): this;
+    /**
+     * The two things a header click cannot work out for itself, both Excel behaviors:
+     *
+     * 1. **Anchor at the first VISIBLE cell.** The active cell of an entire-column selection sits on the
+     *    first visible row, not row 1 — clicking `C` while scrolled to row 50 anchors `C50` (mirrored for
+     *    an entire-row selection's column). Otherwise the anchor jumps to the top of the sheet, dragging
+     *    the formula bar and the editor with it, even though the view doesn't scroll.
+     * 2. **A displayed table column selects the table's BODY**, not the whole sheet column — see
+     *    {@link _entireColumnsToTableBody}.
+     *
+     * @remarks
+     * Applied to the ACTIVE range only, and only when the caller left the anchor at that range's start —
+     * the "no opinion" position, which is all a header click can offer (it has a column, but no row). An
+     * anchor placed deeper into the span is a deliberate one (a restored/undone selection, a navigate)
+     * and is left alone. A whole-SHEET range spans both axes, so nothing applies: select-all keeps its
+     * active cell, as Excel does.
+     *
+     * The UI needs no part in this. A header's own `GridSurface` is a single non-scrolling row/column
+     * across the opposite axis, so the anchor it can compute there is always the sheet's start — exactly
+     * the "no opinion" value this fills in. A grid that CAN see the body (a standalone header sharing the
+     * body's panes) passes a real visible index instead, and that survives untouched.
+     */
+    protected _resolveEntireHeaderSelection(coords: Required<IRangeSelection.Coords>): Required<IRangeSelection.Coords>;
+    /**
+     * A column-header click inside a table selects the table's BODY column (Excel), so the whole-sheet
+     * column `C:C` becomes the table's data rows — the same thing `Ctrl+Space` gives from inside a table.
+     * `null` when the gesture isn't one of those, leaving the sheet column alone.
+     *
+     * @remarks
+     * Gated on the table's column names actually being ON DISPLAY in the header band — Excel only rebinds
+     * the click when the header shows `Region` instead of `C`, which happens once a table the cursor is in
+     * is scrolled past its own header row. That state is the sheet's (`_markColumnHeaderTableNames`), and
+     * `ICellHeader.getColumn()` is its public reading: non-null for exactly the header cells rendering a
+     * table name. Reusing it means the selection can never disagree with what the user sees.
+     *
+     * Every column of the gesture must belong to the one displayed table — dragging out past its edge is a
+     * plain multi-column sheet selection again. The header row itself stays out (Excel adds it only on a
+     * second click, which is not modelled here — a header click is stateless).
+     */
+    protected _entireColumnsToTableBody(active: Readonly<IRange.Coords>): Readonly<IRange.Coords> | null;
+    protected _isEntireRange(coords?: IRange.Coords): boolean;
+    /** {@inheritDoc IRangeSelection.selectRegion} */
+    selectRegion(options?: IRangeSelection.SelectRegionOptions): Promise<ICellRange>;
+    /** {@inheritDoc IRangeSelection.clear} */
+    clear(): void;
+    /** {@inheritDoc IRangeSelection.modify} */
+    modify(cellAnchor: Partial<IRange.CellCoords>, cellPivot?: Partial<IRange.CellCoords>, resetAnchor?: boolean): void;
+    /** {@inheritDoc IRangeSelection.append} */
+    append(start: IRange.CellCoords, end?: IRange.CellCoords, anchor?: Partial<IRange.CellCoords>): void;
+    /** {@inheritDoc IRangeSelection.clearAndModify} */
+    clearAndModify(start: Partial<IRange.CellCoords>, end?: Partial<IRange.CellCoords>, anchor?: Partial<IRange.CellCoords>): void;
+    /** {@inheritDoc IRangeSelection.setAdjusting} */
+    setAdjusting(adjusting: IRangeSelection.Coords | null): void;
+    /** {@inheritDoc IRangeSelection.getAdjusting} */
+    getAdjusting(): IRangeSelection | null;
+    /** {@inheritDoc IRangeSelection.createSelection} */
+    createSelection(options?: IRangeSelection.CreateTemporaryOptions): IRangeSelection;
+    /** {@inheritDoc IRangeSelection.addListeners} */
+    addListeners(listeners: IRangeSelection.IListeners, options?: IListener.Options): IListener.Remove;
+    protected _setSelectionRanges(ranges: readonly IRange.Coords[] | ((ranges: readonly IRange.Coords[]) => IRange.Coords[])): void;
+    protected _setSelectionCell(activeCell: IRange.CellCoords | null): this;
+    protected _isCellOutOfBounds(cell: IRange.CellCoords): boolean;
+    protected _cellToRangeActual(start: IRange.CellCoords, end: IRange.CellCoords): IRange.Coords;
+    protected _rangesFromCellOptional(selection: Required<IRangeSelection.Coords>, cell: Partial<IRange.CellCoords>, cellPivot: Partial<IRange.CellCoords>): IRange.Coords | undefined;
+    protected _getEntireRange(): IRange.Coords;
+    protected _hiddenRowsAt(index: number, reverse?: boolean): number;
+    protected _hiddenColumnsAt(index: number, reverse?: boolean): number;
+    /**
+     * Strip a `scope` annotation before addressing this selection's OWN sheet. Stored coords may be
+     * scope-ANNOTATED — a reference picker's cross-sheet cell/ranges ride this selection, and
+     * `CoordUtils.cellToRange` deliberately carries extra props through — but the selection's geometry
+     * lookups (merges, hidden headers, content edges) always resolve against `_sheet`, and
+     * `Sheet.getRange` rightly warns on a foreign scope. (Resolving a scoped range against *its own*
+     * sheet's geometry is a separate, known gap — this keeps today's local-geometry approximation,
+     * minus the false caller-error.)
+     */
+    protected _localCoords<T extends {
+        scope?: string | null;
+    }>(coords: T): T;
+    protected _getRangeFromCell(coords: IRange.CellCoords): IRange.Coords;
+    protected _canSelectionSpanMergedCells(coords: IRange.Coords): boolean;
+    protected _getMergedRanges(range: IRange.Coords): IRange.Coords[];
+    protected _isContentfulCell(): boolean;
+    protected _contentfulCellFinder(activeCoords: IRange.CellCoords, direction: IRange.Direction): number;
+    protected _scrollCellCoordsIntoView(coords: Partial<IRange.Coords>, options?: globalThis.ScrollIntoViewOptions | boolean): Promise<boolean>;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+}
+interface _ReadCache {
+    range: ICellRange | null;
+    ranges: ICellRanges | null;
+}
+export {};
+//# sourceMappingURL=RangeSelection.d.ts.map

package/types/src/selection/RangeSelection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RangeSelection.d.ts","sourceRoot":"","sources":["../../../../src/selection/RangeSelection.ts"],"names":[],"mappings":"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"}

package/types/src/selection/_RangeSelectionUtils.d.ts

@@ -0,0 +1,32 @@
+import { IRange } from '@sheetxl/primitives';
+import { SelectionTraversalUtils, RunCoordValue } from '@sheetxl/utils';
+import { IRangeSelection } from './IRangeSelection';
+/**
+ * Projects a selection onto a header `axis` as contiguous runs of selected headers — the header-axis
+ * span of each range, merged where they overlap. Each run's `value` is `isSelectedAll`: whether the
+ * range covers the *opposite* axis entirely (`maxRange`), i.e. an entire-row/column selection.
+ *
+ * @remarks
+ * A pure function of `(axis, coords, entireCoords)` — the projection that backs both
+ * {@link IRangeSelection.getSelectedRuns} and the sheet header's selected-run cache.
+ */
+export declare function createSelectedRuns(axis: IRange.Axis, selection: IRangeSelection.Coords, maxRange: IRange.Coords): RunCoordValue<boolean>[];
+export declare function getVisibleHeaders(hiddenAt: SelectionTraversalUtils.HiddenHeadersAt | undefined, startIndex: number, stopIndex: number): number[];
+export declare function mergeSelection(selection: IRangeSelection.Coords, activeSelection: IRangeSelection.Coords, entireRangeCoords: IRange.Coords): Required<IRangeSelection.Coords>;
+/**
+ * Returns the cells as an ordered list of ranges.  The first range is the active range.
+ * If there are no ranges then the active coord will be returns as a range.
+ *
+ * @remarks
+ * * Always return at least 1 range unless the selection is null.
+ */
+export declare function selectionToRangesCoords(selection: Partial<IRangeSelection.Coords> | null): IRange.Coords[] | null;
+/**
+ * Creates a IRangeSelection.Coords from an array of ranges.
+ *
+ * @param ranges The ranges to include in the selection.
+ * @param cell If provided will try to fit within the cell
+ * @param rangeIndex *default* `ranges.length 1 unless this is a single cell then -1`.
+ */
+export declare function rangesToSelectionCoords(ranges: readonly IRange.Coords[], cell?: IRange.CellCoords, rangeIndex?: number): IRangeSelection.Coords | null;
+//# sourceMappingURL=_RangeSelectionUtils.d.ts.map

package/types/src/selection/_RangeSelectionUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_RangeSelectionUtils.d.ts","sourceRoot":"","sources":["../../../../src/selection/_RangeSelectionUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EACoB,KAAK,uBAAuB,EAAE,KAAK,aAAa,EAC1E,MAAM,gBAAgB,CAAC;AAIxB,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,CAAC,IAAI,EACjB,SAAS,EAAE,eAAe,CAAC,MAAM,EACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,GACtB,aAAa,CAAC,OAAO,CAAC,EAAE,CAuB1B;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,uBAAuB,CAAC,eAAe,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAahJ;AAGD,wBAAgB,cAAc,CAC5B,SAAS,EAAE,eAAe,CAAC,MAAM,EACjC,eAAe,EAAE,eAAe,CAAC,MAAM,EACvC,iBAAiB,EAAE,MAAM,CAAC,MAAM,GAC/B,QAAQ,CAAC,eAAe,CAAC,MAAM,CAAC,CA+FlC;AAwBD;;;;;;GAMG;AAEH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,OAAO,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,IAAI,CAgBjH;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,MAAM,CAAC,MAAM,EAAE,EAChC,IAAI,CAAC,EAAE,MAAM,CAAC,UAAU,EACxB,UAAU,GAAE,MAAS,GACpB,eAAe,CAAC,MAAM,GAAG,IAAI,CAmB/B"}

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

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

package/types/src/selection/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/selection/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}