@office-kit/xlsx 0.8.0

package/dist/worksheet/worksheet.d.ts

@@ -0,0 +1,935 @@
+import type { CellValue } from '../cell/cell';
+import { type Cell } from '../cell/cell';
+import { type InlineFont, type TextRun } from '../cell/rich-text';
+import type { Drawing } from '../drawing/drawing';
+import { type Color } from '../styles/colors';
+import type { AutoFilter } from './auto-filter';
+import { type CellRange } from './cell-range';
+import type { LegacyComment } from './comments';
+import type { ConditionalFormatting } from './conditional-formatting';
+import type { DataValidation } from './data-validations';
+import { type ColumnDimension, type RowDimension } from './dimensions';
+import type { DataConsolidate } from './data-consolidate';
+import type { ScenarioList } from './scenarios';
+import type { CellWatch, IgnoredError } from './errors';
+import type { HeaderFooter, PageBreak, PageMargins, PageSetup, PrintOptions } from './page-setup';
+import type { WorksheetPhoneticProperties } from './phonetic';
+import { type SheetProperties } from './properties';
+import type { SheetProtection } from './protection';
+import type { ProtectedRange } from './protected-ranges';
+import type { SortState } from './sort-state';
+import type { WebPublishItem, WorksheetCustomProperty } from './web-publish';
+import { type Hyperlink } from './hyperlinks';
+import type { TableDefinition } from './table';
+import { type SheetView } from './views';
+export interface Worksheet {
+    title: string;
+    /** Sparse store: row index → (col index → Cell). */
+    rows: Map<number, Map<number, Cell>>;
+    /**
+     * Highest row index touched by `appendRow`; used to keep appendRow O(1)
+     * without re-scanning the row map. Direct setCell / deleteCell may move the
+     * actual maximum elsewhere.
+     */
+    _appendRowCursor: number;
+    /**
+     * Merged cell ranges. The top-left cell holds the value; the rest are mostly
+     * invisible to Excel until unmerge restores them. We persist the list as
+     * plain CellRange[] so mergeCells / unmergeCells can mutate it without
+     * rebuilding any helper structures.
+     */
+    mergedCells: CellRange[];
+    /**
+     * Per-bookView display settings. Most workbooks have exactly one view. The
+     * list stays empty until something — read or API — populates it; a lone
+     * default view doesn't earn its keep on the wire.
+     */
+    views: SheetView[];
+    /**
+     * Per-column metadata keyed by the entry's `min` index. The value's
+     * `min`/`max` may cover a multi-column run; iteration over the map yields one
+     * entry per run, in `min`-ascending order.
+     */
+    columnDimensions: Map<number, ColumnDimension>;
+    /** Per-row metadata keyed by 1-based row index. */
+    rowDimensions: Map<number, RowDimension>;
+    /** Default column width (characters) when not overridden by a column dimension. */
+    defaultColumnWidth?: number;
+    /** Default row height (points) when not overridden by a row dimension. */
+    defaultRowHeight?: number;
+    /**
+     * Highest outline depth used among `rowDimensions`. Excel uses this to size
+     * the outline button strip on the left of the row numbers. Auto-computed by
+     * the writer when undefined — set explicitly to override.
+     */
+    outlineLevelRow?: number;
+    /** Highest outline depth used among `columnDimensions`. Auto-computed by the writer when undefined. */
+    outlineLevelCol?: number;
+    /** "Custom row heights present" hint — Excel uses this to skip default-height rendering. */
+    customHeight?: boolean;
+    /** "Show rows of zero height as one row" — for hidden rows the outline collapse uses this. */
+    zeroHeight?: boolean;
+    /** Apply a thick top border to every row by default. */
+    thickTop?: boolean;
+    /** Apply a thick bottom border to every row by default. */
+    thickBottom?: boolean;
+    /** Excel's "base column width" (characters) — defaults to 8 when unset. */
+    baseColWidth?: number;
+    /** Hyperlinks. External URLs round-trip via worksheet rels; internal jumps stay inline. */
+    hyperlinks: Hyperlink[];
+    /** Data validation entries. */
+    dataValidations: DataValidation[];
+    /** AutoFilter — at most one per sheet. Excel reuses the `_xlnm._FilterDatabase` defined name. */
+    autoFilter?: AutoFilter;
+    /** Excel Table objects. Each lives in its own xl/tables/tableN.xml part. */
+    tables: TableDefinition[];
+    /** Legacy comments. Persisted as `xl/commentsN.xml` + a placeholder VML drawing. */
+    legacyComments: LegacyComment[];
+    /** Conditional formatting blocks. */
+    conditionalFormatting: ConditionalFormatting[];
+    /**
+     * `<sheetPr>` properties — VBA codeName, tab strip color, outline /
+     * page-setup defaults, etc. Top-level `<sheetPr>` lives just before
+     * `<dimension>` per ECMA-376 ordering.
+     */
+    sheetProperties?: SheetProperties;
+    /**
+     * Sheet-protection state. When `sheet=true` Excel locks the sheet against
+     * edits (subject to the per-action allow flags here). Password hashing
+     * helpers come later — for now `saltValue` / `spinCount` / `algorithmName` /
+     * `hashValue` round-trip verbatim.
+     */
+    sheetProtection?: SheetProtection;
+    /**
+     * `<protectedRanges>` — per-range edit-allowance overrides used when the
+     * sheet is otherwise protected (Review → Allow Edit Ranges).
+     */
+    protectedRanges: ProtectedRange[];
+    /**
+     * `<sortState>` — last-applied sort criteria. Excel persists this so the rows
+     * come back in the same order after a save/load cycle.
+     */
+    sortState?: SortState;
+    /**
+     * `<picture r:id="…"/>` — sheet background image (Page Layout → Background).
+     * The rId points at a media part registered in the worksheet rels (preserved
+     * via the existing relsExtras machinery).
+     */
+    backgroundPictureRId?: string;
+    /**
+     * `<legacyDrawingHF r:id="…"/>` — VML drawing used for header/footer
+     * background images on print. Parallel to legacyDrawing (which carries
+     * comment markers); the rels link rides relsExtras.
+     */
+    legacyDrawingHFRId?: string;
+    /**
+     * `<smartTags>` — per-cell smart-tag annotations (Excel 2003 era). Pairs with
+     * the workbook-level smartTagTypes registry.
+     */
+    smartTags: import('./smart-tags').CellSmartTags[];
+    /**
+     * `<customSheetViews>` — saved per-user view presets for this worksheet
+     * (Excel's "Custom Views" feature). Each entry snapshots zoom / gridline /
+     * formula / heading toggles plus its own page-setup block and break list.
+     */
+    customSheetViews: import('./custom-sheet-views').CustomSheetView[];
+    /**
+     * `<oleObjects>` — embedded OLE objects (linked Word documents, Equation
+     * editor formulas, etc.). The objectPr child is round-tripped verbatim as an
+     * XmlNode.
+     */
+    oleObjects: import('./ole-objects').OleObject[];
+    /**
+     * `<controls>` — form controls (checkboxes / list boxes / spin buttons placed
+     * via the Developer tab). The controlPr child is round-tripped verbatim.
+     */
+    controls: import('./ole-objects').FormControl[];
+    /** `<printOptions>` — gridlines, headings, horizontal/vertical centering on the printed page. */
+    printOptions?: PrintOptions;
+    /** `<pageMargins>` — six required margins in inches. */
+    pageMargins?: PageMargins;
+    /** `<pageSetup>` — paper size / orientation / scale / fitToPage / DPI etc. */
+    pageSetup?: PageSetup;
+    /** `<headerFooter>` — odd/even/first header + footer mini-format strings + flags. */
+    headerFooter?: HeaderFooter;
+    /** Manual horizontal page breaks (`<rowBreaks>`). Each entry's `id` is the row above which a new page begins. */
+    rowBreaks: PageBreak[];
+    /** Manual vertical page breaks (`<colBreaks>`). Each entry's `id` is the column to the left of which a new page begins. */
+    colBreaks: PageBreak[];
+    /**
+     * Worksheet-level `<customProperties>` — per-sheet user metadata that
+     * SharePoint workflows attach (separate from the workbook-level
+     * `docProps/custom.xml` part). The `rId` points at a Custom XML part
+     * registered in the worksheet rels (already preserved via `relsExtras`).
+     */
+    customProperties: WorksheetCustomProperty[];
+    /** `<webPublishItems>` — Excel 2007's "Publish to web" entries. Almost always empty in modern files. */
+    webPublishItems: WebPublishItem[];
+    /**
+     * `<phoneticPr>` — East-Asian furigana rendering hints (font index + IME
+     * conversion mode + alignment). Common in Japanese workbooks.
+     */
+    phoneticPr?: WorksheetPhoneticProperties;
+    /**
+     * `<dataConsolidate>` — config for Data → Consolidate. Carries the
+     * aggregation function and the source-range list.
+     */
+    dataConsolidate?: DataConsolidate;
+    /** `<scenarios>` — the Scenario Manager's saved input-cell overrides. */
+    scenarios?: ScenarioList;
+    /** Cells pinned in Excel's Watch Window (`<cellWatches><cellWatch r="…"/></cellWatches>`). */
+    cellWatches: CellWatch[];
+    /**
+     * Per-region "ignore this error class" rules (`<ignoredErrors>`). Suppresses
+     * the small green-triangle warning for the listed checks.
+     */
+    ignoredErrors: IgnoredError[];
+    /**
+     * Spreadsheet drawing — at most one per worksheet. Hosts charts / pictures /
+     * shapes. Persisted as `xl/drawings/drawingN.xml` plus a worksheet-rels
+     * entry; on the wire the worksheet body emits `<drawing r:id>`.
+     */
+    drawing?: Drawing;
+    /**
+     * Per-sheet rels entries we don't model (pivotTable / queryTable / slicer /
+     * printerSettings / customProperty / oleObject etc.). Re-emitted verbatim so
+     * Excel still resolves the captured passthrough parts after a round-trip.
+     */
+    relsExtras?: ReadonlyArray<{
+        id: string;
+        type: string;
+        target: string;
+    }>;
+    /**
+     * Top-level `<worksheet>` children we don't model — `<sheetPr>`,
+     * `<printOptions>`, `<pageMargins>`, `<pageSetup>`, `<headerFooter>`,
+     * `<rowBreaks>`, `<colBreaks>`, `<oleObjects>`, `<controls>`, `<picture>`,
+     * `<extLst>`, etc. Captured as XmlNodes; the writer emits them in two
+     * anchored slots so common ECMA-376 ordering survives a round-trip even
+     * though we don't track every position individually:
+     * - `beforeSheetData` → emitted before our `<dimension>` (typical for
+     * `<sheetPr>`).
+     * - `afterSheetData` → emitted between our `<hyperlinks>` and
+     * `<drawing>` block, which lands page setup / extLst / oleObjects in roughly
+     * the right place. Excel reads back regardless of strict ECMA position;
+     * openpyxl-emitted files round-trip cleanly.
+     */
+    bodyExtras?: {
+        beforeSheetData: import('../xml/tree').XmlNode[];
+        afterSheetData: import('../xml/tree').XmlNode[];
+    };
+}
+/** Build a Worksheet shell. */
+export declare function makeWorksheet(title: string): Worksheet;
+/** Resolve a 1-based or "A1" coordinate; returns the populated Cell or undefined. */
+export declare function getCell(ws: Worksheet, row: number, col: number): Cell | undefined;
+/**
+ * Create or update a Cell at (row, col). Existing cells keep their styleId /
+ * hyperlinkId / commentId unless explicitly overridden.
+ */
+export declare function setCell(ws: Worksheet, row: number, col: number, value?: CellValue, styleId?: number): Cell;
+/** Delete a single cell from the sheet. Empty rows are pruned. */
+export declare function deleteCell(ws: Worksheet, row: number, col: number): void;
+/**
+ * Delete every populated cell inside a range. Returns the number of cells
+ * removed. Row maps that go empty are pruned. Column / row dimensions, merges,
+ * comments etc. are left untouched.
+ */
+export declare function clearRange(ws: Worksheet, range: string): number;
+/**
+ * Wipe every populated cell on the worksheet, leaving styles, dimensions,
+ * merges, comments, hyperlinks etc. intact. Returns the count of cells removed.
+ * Useful when a sheet should be re-filled from scratch but its formatting kept.
+ */
+export declare function clearAllCells(ws: Worksheet): number;
+/**
+ * Append a row of values starting at the next empty row. Returns the row index
+ * (1-based). Mirrors openpyxl's `Worksheet.append`. `null` / `undefined`
+ * entries leave the cell empty.
+ */
+export declare function appendRow(ws: Worksheet, values: ReadonlyArray<CellValue | undefined>): number;
+/**
+ * Bulk version of {@link appendRow}: append a 2D array of values one row at a
+ * time. Returns `{firstRow, lastRow}` — both 1-based, inclusive. An empty input
+ * returns `{firstRow, lastRow: firstRow - 1}` so callers can detect the no-op
+ * without throwing.
+ *
+ * Common usage: `appendRows(ws, csvParsedRows)` for fast import.
+ */
+export declare function appendRows(ws: Worksheet, rows: ReadonlyArray<ReadonlyArray<CellValue | undefined>>): {
+    firstRow: number;
+    lastRow: number;
+};
+/**
+ * Write a 2D array of values to the sheet starting at the given A1 anchor cell.
+ * Distinct from {@link appendRows} (which always writes past
+ * `_appendRowCursor`) — this lets you place a block at an arbitrary location,
+ * e.g. mid-sheet table updates.
+ *
+ * `null` / `undefined` entries leave the corresponding cell **untouched**
+ * (existing cell + style are preserved). Pre-existing cells inside the written
+ * rectangle are overwritten in place, so their `styleId` survives the write.
+ *
+ * Returns the bounding-box of the written area as 1-based inclusive
+ * coordinates. An empty rows array returns `undefined` rather than an invalid
+ * zero-area range.
+ */
+export declare function writeRange(ws: Worksheet, startRef: string, values: ReadonlyArray<ReadonlyArray<CellValue | undefined>>): {
+    minRow: number;
+    maxRow: number;
+    minCol: number;
+    maxCol: number;
+} | undefined;
+export interface IterRowsOptions {
+    minRow?: number;
+    maxRow?: number;
+    minCol?: number;
+    maxCol?: number;
+}
+/**
+ * Iterate the worksheet rows rectangularly. Yields one row per row in
+ * `[minRow, maxRow]` — including entirely empty rows — and each yielded row
+ * has length `maxCol - minCol + 1`. Missing cell positions are `undefined`
+ * (no placeholder Cell allocations).
+ *
+ * Defaults: `minRow=1`, `maxRow=getMaxRow(ws)`, `minCol=1`,
+ * `maxCol=getMaxCol(ws)`. The default extent is the populated bounding box,
+ * not the 1M × 16K sheet limit, so the rectangular default doesn't iterate
+ * the whole grid for a small sheet.
+ *
+ * To iterate populated rows only, filter:
+ * `[...iterRows(ws)].filter(row => row.some((c) => c !== undefined))`. To
+ * iterate populated cells without row boundaries, use {@link iterCells}.
+ */
+export declare function iterRows(ws: Worksheet, opts?: IterRowsOptions): IterableIterator<(Cell | undefined)[]>;
+/**
+ * Same rectangular iteration as {@link iterRows}, but yields each cell's
+ * `.value`. Missing cell positions become `null` — already the canonical empty
+ * marker in `CellValue`.
+ */
+export declare function iterValues(ws: Worksheet, opts?: IterRowsOptions): IterableIterator<CellValue[]>;
+/**
+ * Yield every populated cell in the worksheet as a flat stream (row-major,
+ * columns ascending). Distinct from {@link iterRows} which yields one row
+ * per row in the bounding box — use this when the caller wants only the
+ * populated cells without row boundaries or rectangular padding.
+ */
+export declare function iterCells(ws: Worksheet, opts?: IterRowsOptions): IterableIterator<Cell>;
+/** Effective max row index based on populated cells (0 when empty). */
+export declare function getMaxRow(ws: Worksheet): number;
+/** Effective max column index based on populated cells (0 when empty). */
+export declare function getMaxCol(ws: Worksheet): number;
+/**
+ * Sorted list of every row index that holds at least one populated cell.
+ * Returns `[]` for an empty worksheet. Useful when a caller wants to iterate
+ * only the rows the user actually populated, without walking 1..maxRow in dense
+ * fashion.
+ */
+export declare function getPopulatedRowIndices(ws: Worksheet): number[];
+/**
+ * Sorted list of every column index that holds at least one populated cell
+ * anywhere on the sheet. Distinct columns only; returns `[]` for an empty
+ * worksheet.
+ */
+export declare function getPopulatedColumnIndices(ws: Worksheet): number[];
+/**
+ * Tally populated cells by value kind. Useful for stats / debugging dashboards
+ * that want a quick "this sheet has N strings, M formulas, K dates" snapshot.
+ *
+ * Buckets:
+ *   - `null`: empty cells (cell exists but value is null)
+ *   - `string`: plain strings
+ *   - `number`: numeric primitives
+ *   - `boolean`: TRUE / FALSE
+ *   - `date`: native `Date` instances
+ *   - `duration`: `{ kind: 'duration', ms }` values
+ *   - `error`: `#REF!` / `#VALUE!` / etc. error values
+ *   - `rich-text`: `{ kind: 'rich-text', runs }` values
+ *   - `formula`: `FormulaValue` (regardless of cached value type)
+ */
+export interface CellsByKindCounts {
+    null: number;
+    string: number;
+    number: number;
+    boolean: number;
+    date: number;
+    duration: number;
+    error: number;
+    'rich-text': number;
+    formula: number;
+}
+/**
+ * Bucket a single CellValue into one of the {@link CellsByKindCounts} keys.
+ * Shared between {@link countCellsByKind} and the workbook-wide overview so
+ * the two never drift in how they classify (e.g. `Date` vs `duration`).
+ */
+export declare function classifyCellValue(v: import('../cell/cell').CellValue): keyof CellsByKindCounts;
+export declare function countCellsByKind(ws: Worksheet): CellsByKindCounts;
+/**
+ * Sheet-qualified A1 address for a cell — `'Sheet1!A1'` for plain titles,
+ * `'\'Quarter 1\'!A1'` for titles needing quoting (spaces, apostrophes,
+ * punctuation, leading-digit). Round-trips with {@link parseSheetRange}.
+ *
+ * Useful when constructing formulas / defined-names that reference a specific
+ * cell across sheets without hand-rolling the quote logic.
+ */
+export declare function getCellAddress(ws: Worksheet, c: Cell): string;
+/**
+ * Sheet-qualified A1 range address — `'Sheet1!A1:B5'` for plain titles,
+ * `'\'Quarter 1\'!A1:B5'` for titles needing quoting. Pass any A1-style range
+ * string (single cell `'A1'`, rectangle `'A1:B5'`, row span `'1:5'`, column
+ * span `'A:E'`); the helper does no validation on `range` itself — that's the
+ * caller's responsibility.
+ */
+export declare function getRangeAddress(ws: Worksheet, range: string): string;
+/**
+ * True iff the worksheet has zero non-empty cells. Equivalent to
+ * `getNonEmptyCellCount(ws) === 0` but short-circuits on the first non-null
+ * value found, so the cost is O(first non-empty cell) rather than O(populated
+ * cells).
+ */
+export declare function isWorksheetEmpty(ws: Worksheet): boolean;
+/**
+ * Count non-empty cells. Distinct from {@link countCells} which counts every
+ * materialised cell (including ones whose `value === null`): this skips cells
+ * with a `null` value, plus optionally formulas / rich-text per the opts.
+ *
+ * Useful for "how many real values does this sheet contain" stats vs the
+ * materialised footprint.
+ */
+export declare function getNonEmptyCellCount(ws: Worksheet, opts?: {
+    includeFormulas?: boolean;
+    includeRichText?: boolean;
+}): number;
+/** Total populated cell count. */
+export declare function countCells(ws: Worksheet): number;
+/**
+ * Bounding-box of the populated cells: `{ minRow, maxRow, minCol, maxCol }`
+ * covering every cell in `ws.rows`. Returns `undefined` when the sheet is
+ * empty. Walks the sparse store once.
+ */
+export declare function getDataExtent(ws: Worksheet): {
+    minRow: number;
+    maxRow: number;
+    minCol: number;
+    maxCol: number;
+} | undefined;
+/**
+ * Same as {@link getDataExtent} but returns the canonical `"A1:E10"` range
+ * string for the bounding box, or `undefined` when the sheet is empty.
+ */
+export declare function getDataExtentRef(ws: Worksheet): string | undefined;
+/**
+ * Iterate every populated cell, yielding those for which `predicate` returns
+ * true. Iteration order is row-then-column ascending. Cells whose `.value ===
+ * null` (empty placeholders carrying only style or comment metadata) are still
+ * visited.
+ */
+export declare function findCells(ws: Worksheet, predicate: (c: Cell) => boolean): IterableIterator<Cell>;
+/** First populated cell satisfying `predicate`, or `undefined`. */
+export declare function findFirstCell(ws: Worksheet, predicate: (c: Cell) => boolean): Cell | undefined;
+/**
+ * Find-and-replace across populated string cells. `search` matches either an
+ * exact-string equal (when given a string) or every cell whose value satisfies
+ * the predicate (when given a function). `replacement` is the new value for
+ * each match. Returns the count of cells changed. Non-string-valued cells are
+ * skipped when `search` is a string; predicate-based searches see every cell.
+ */
+export declare function replaceCellValues(ws: Worksheet, search: string | ((value: CellValue, cell: Cell) => boolean), replacement: CellValue): number;
+/**
+ * Range-scoped find-and-replace. Same matching rules as {@link
+ * replaceCellValues} (string → exact-equal on string-valued cells; function →
+ * predicate over every populated cell), but only cells inside the rectangular
+ * `range` are visited. Returns the count changed.
+ */
+export declare function replaceInRange(ws: Worksheet, range: string, search: string | ((value: CellValue, cell: Cell) => boolean), replacement: CellValue): number;
+/**
+ * Iterate the populated cells inside a rectangular range. Cells that don't
+ * exist in the sparse store are skipped (no auto-allocate). Use {@link
+ * applyToRange} when you need every coordinate visited regardless of
+ * population.
+ */
+export declare function getCellsInRange(ws: Worksheet, range: string): IterableIterator<Cell>;
+/**
+ * Set a cell's value to a rich-text run array. Accepts either a pre-built
+ * `RichText` (frozen array of TextRun) or a fresh `Array<{ text, font? }>`
+ * shape — `makeRichText` normalises and freezes the runs in either case.
+ * Returns the cell.
+ */
+export declare function setCellRichText(ws: Worksheet, row: number, col: number, runs: ReadonlyArray<TextRun | {
+    text: string;
+    font?: InlineFont;
+}>, styleId?: number): Cell;
+/**
+ * Set a cell's value to a normal Excel formula. Combines `setCell` with
+ * `setFormula`. The leading `=` is stripped if present so callers can pass
+ * `'=A1+1'` or `'A1+1'` interchangeably.
+ */
+export declare function setCellFormula(ws: Worksheet, row: number, col: number, formula: string, opts?: {
+    cachedValue?: number | string | boolean;
+    styleId?: number;
+}): Cell;
+/**
+ * Set a cell's value to an array (CSE) formula spanning `ref`. Lands the
+ * formula on the top-left cell of the range — Excel reads the `ref` attribute
+ * to know how far the result spreads. Equivalent to `setCell` +
+ * `setArrayFormula`. Leading `=` is stripped.
+ */
+export declare function setCellArrayFormula(ws: Worksheet, row: number, col: number, ref: string, formula: string, opts?: {
+    cachedValue?: number | string | boolean;
+    styleId?: number;
+}): Cell;
+/** Resolve an "A1" coordinate to a numeric (col, row) pair on the sheet. */
+export declare function setCellByCoord(ws: Worksheet, coord: string, value?: CellValue, styleId?: number): Cell;
+/** Convenience getter accepting an "A1" coordinate. */
+export declare function getCellByCoord(ws: Worksheet, coord: string): Cell | undefined;
+/**
+ * Merge a range. The top-left cell keeps its value; every other cell in the
+ * range is dropped from `ws.rows` so the on-wire `<sheetData>` won't carry
+ * phantom cells underneath the merge. Mirrors openpyxl's
+ * `MergedCellRange.format()`. Idempotent for an identical range, throws when
+ * the range overlaps an existing merge.
+ */
+export declare function mergeCells(ws: Worksheet, refOrRange: string | CellRange): CellRange;
+/** Drop a previously-merged range. No-op if the range isn't registered. */
+export declare function unmergeCells(ws: Worksheet, refOrRange: string | CellRange): boolean;
+/** Read-only iterator over the worksheet's merged ranges. */
+export declare function getMergedCells(ws: Worksheet): ReadonlyArray<CellRange>;
+/** True iff (row, col) sits inside any merged range — top-left included. */
+export declare function isMergedCell(ws: Worksheet, row: number, col: number): boolean;
+/**
+ * Look up the merged range covering (row, col), or `undefined` if the
+ * coordinate isn't inside any merge. Lets callers introspect a merge without
+ * iterating `getMergedCells` themselves.
+ */
+export declare function getMergedRangeAt(ws: Worksheet, row: number, col: number): CellRange | undefined;
+/**
+ * Drop the merge that contains (row, col), if any. Returns `true` when a merge
+ * was unregistered. Useful when callers know a cell coordinate but not the
+ * original merge bounds.
+ */
+export declare function unmergeCellsAt(ws: Worksheet, row: number, col: number): boolean;
+/**
+ * Drop every merged range on the worksheet. Returns the count of merges
+ * removed. Cells that were inside the merges keep their values — only the merge
+ * metadata is gone.
+ */
+export declare function removeAllMergedRanges(ws: Worksheet): number;
+/**
+ * Freeze rows / columns above + left of `topLeftRef` ("B2" → 1 row + 1 col).
+ * Pass `undefined` to clear any existing freeze. Targets the workbook's primary
+ * SheetView (`ws.views[0]`); creates one if absent.
+ */
+export declare function setFreezePanes(ws: Worksheet, topLeftRef: string | undefined): void;
+/** Inverse of {@link setFreezePanes}; returns the top-left ref or undefined when no freeze is active. */
+export declare function getFreezePanes(ws: Worksheet): string | undefined;
+/**
+ * Freeze the top `count` rows. Equivalent to `setFreezePanes(ws, "A${count +
+ * 1}")` — Excel's "Freeze Top Row" is `freezeRows(ws, 1)`.
+ */
+export declare function freezeRows(ws: Worksheet, count: number): void;
+/**
+ * Freeze the leftmost `count` columns. Equivalent to `setFreezePanes(ws,
+ * "${columnLetter(count + 1)}1")` — Excel's "Freeze First Column" is
+ * `freezeColumns(ws, 1)`.
+ */
+export declare function freezeColumns(ws: Worksheet, count: number): void;
+/** Freeze both top `rows` rows AND left `cols` columns. */
+export declare function freezePanes(ws: Worksheet, rows: number, cols: number): void;
+/** Drop the freeze pane on the primary view. */
+export declare const unfreezePanes: (ws: Worksheet) => void;
+/**
+ * Freeze the header row (row 1) so it stays visible while scrolling. Equivalent
+ * to Excel's "View → Freeze Top Row". Shortcut for `freezeRows(ws, 1)`.
+ */
+export declare const freezeFirstRow: (ws: Worksheet) => void;
+/**
+ * Freeze the leftmost column (column A) so it stays visible while scrolling
+ * horizontally. Equivalent to Excel's "View → Freeze First Column". Shortcut
+ * for `freezeColumns(ws, 1)`.
+ */
+export declare const freezeFirstColumn: (ws: Worksheet) => void;
+/**
+ * Freeze both row 1 and column A so the header row + label column stay visible.
+ * Equivalent to selecting B2 and "View → Freeze Panes". Shortcut for
+ * `freezePanes(ws, 1, 1)`.
+ */
+export declare const freezeFirstRowAndColumn: (ws: Worksheet) => void;
+/**
+ * Set the sheet tab strip colour. Accepts either a hex string (`"FF0070C0"`) or
+ * a partial `Color` object (`{ theme: 4, tint: 0.4 }`).
+ */
+export declare function setSheetTabColor(ws: Worksheet, color: string | Partial<Color>): Color;
+/** Drop the sheet tab strip colour. */
+export declare function removeSheetTabColor(ws: Worksheet): void;
+/** Toggle gridline display on the primary SheetView. */
+export declare function setShowGridLines(ws: Worksheet, show: boolean): void;
+/** Toggle row + column header display on the primary SheetView. */
+export declare function setShowRowColHeaders(ws: Worksheet, show: boolean): void;
+/** Toggle "Show Formulas" mode on the primary SheetView. */
+export declare function setShowFormulas(ws: Worksheet, show: boolean): void;
+/** Toggle "Show a zero in cells that have a zero value" on the primary SheetView. */
+export declare function setShowZeros(ws: Worksheet, show: boolean): void;
+/** Toggle right-to-left layout on the primary SheetView. */
+export declare function setRightToLeft(ws: Worksheet, rtl: boolean): void;
+/**
+ * Set the zoom scale (percent) on the primary SheetView. Excel accepts integer
+ * percentages in `[10, 400]`.
+ */
+export declare function setSheetZoom(ws: Worksheet, scale: number): void;
+/** Switch the sheet view between Excel's "Normal" / "Page Break Preview" / "Page Layout" modes. */
+export declare function setSheetViewMode(ws: Worksheet, mode: 'normal' | 'pageBreakPreview' | 'pageLayout'): void;
+/**
+ * Set the active cell on the primary SheetView. The active cell is the one
+ * Excel highlights with the dark border when the sheet is opened. Updates the
+ * existing Selection; creates one if missing. Pass an "A1"-style ref.
+ */
+export declare function setActiveCell(ws: Worksheet, ref: string): void;
+/**
+ * Set the selected range (sqref) on the primary SheetView. Accepts a single
+ * cell ("A1"), a single range ("A1:B5"), or a multi-cell range string ("A1
+ * C3:D4"). Leaves activeCell untouched unless absent — in which case it's set
+ * to the first ref of `sqref`.
+ */
+export declare function setSelectedRange(ws: Worksheet, sqref: string): void;
+/**
+ * Set values across a rectangular range from a 2-D array. `rows[0]` is laid
+ * down starting at the top-left of `range`; subsequent rows follow. `null` /
+ * `undefined` entries skip the cell. Useful for dropping a header + data block
+ * in one call.
+ */
+export declare function setRangeValues(ws: Worksheet, range: string, rows: ReadonlyArray<ReadonlyArray<CellValue | null | undefined>>): void;
+/**
+ * Iterate over every cell coordinate in a range, calling `visit` once per (row,
+ * col). Allocates the cell on first touch so callers can mutate it freely.
+ */
+export declare function applyToRange(ws: Worksheet, range: string, visit: (cell: Cell, row: number, col: number) => void): void;
+/**
+ * Read a rectangular range as a dense 2-D array of values. Empty cells yield
+ * `null`. The shape is `[maxRow - minRow + 1] × [maxCol - minCol + 1]`. Inverse
+ * of {@link setRangeValues}.
+ */
+export declare function getRangeValues(ws: Worksheet, range: string): (CellValue | null)[][];
+/**
+ * Copy every populated cell from `source` to `target` (within the same
+ * worksheet, or across worksheets via `targetWs`). Cells are shallow-cloned:
+ * `value` and `styleId` carry over but `row`/`col` are rewritten. The target's
+ * existing cells in the destination extent are overwritten; cells outside are
+ * untouched.
+ *
+ * The source and target ranges define the top-left corner — their dimensions
+ * need not match. If the target range is smaller than the source, only the
+ * cells that fit within the target's extent are copied; if larger, only the
+ * source's extent is filled.
+ *
+ * Returns the number of cells copied.
+ */
+export declare function copyRange(ws: Worksheet, source: string, target: string, opts?: {
+    targetWs?: Worksheet;
+}): number;
+/**
+ * Move every populated cell from `source` to `target`. Equivalent to
+ * `copyRange` followed by clearing the source. When the ranges overlap on the
+ * same sheet, the copy walks in the direction that preserves data — high-to-low
+ * along any axis where the move shifts forward, low-to-high otherwise — so
+ * cells aren't overwritten before they've been read. Returns the number of
+ * cells moved.
+ */
+export declare function moveRange(ws: Worksheet, source: string, target: string, opts?: {
+    targetWs?: Worksheet;
+}): number;
+/**
+ * Read all populated values in a single column. Returns one `(CellValue |
+ * null)` per row in `[minRow, maxRow]` (defaults to row 1 .. `getMaxRow(ws)`).
+ * Empty cells yield `null`. Returns `[]` when the worksheet is empty.
+ */
+export declare function getColumnValues(ws: Worksheet, col: number, opts?: {
+    minRow?: number;
+    maxRow?: number;
+}): (CellValue | null)[];
+/**
+ * Read all populated values in a single row. Returns one `(CellValue | null)`
+ * per column in `[minCol, maxCol]` (defaults to col 1 .. `getMaxCol(ws)` when
+ * the row exists, otherwise `[]`).
+ */
+export declare function getRowValues(ws: Worksheet, row: number, opts?: {
+    minCol?: number;
+    maxCol?: number;
+}): (CellValue | null)[];
+/**
+ * Enumerate the populated cells of a row in column order. Unlike {@link
+ * getRowValues}, this skips empty columns and yields the cell objects (not just
+ * their values). Returns `[]` when the row is absent or empty.
+ */
+export declare function getCellsInRow(ws: Worksheet, row: number): Cell[];
+/**
+ * Enumerate the populated cells of a column in row order. Walks the row map and
+ * collects whichever rows carry the column. Returns `[]` when the worksheet has
+ * no cell in that column.
+ */
+export declare function getCellsInColumn(ws: Worksheet, col: number): Cell[];
+/**
+ * Look up the ColumnDimension covering `col`. The search walks every registered
+ * entry's `min..max` range; that's fine for the typical spreadsheet (a handful
+ * of column entries) and stays simple.
+ */
+export declare function getColumnDimension(ws: Worksheet, col: number): ColumnDimension | undefined;
+/**
+ * Set a single-column ColumnDimension entry covering `col`. Shadows any
+ * existing run that overlaps — runs are not split for now (callers that need
+ * range-spanning entries can write directly into `ws.columnDimensions`).
+ */
+export declare function setColumnDimension(ws: Worksheet, col: number, opts: Partial<Omit<ColumnDimension, 'min' | 'max'>>): ColumnDimension;
+/** Convenience: set a column's width, leaving other fields untouched. */
+export declare function setColumnWidth(ws: Worksheet, col: number, width: number): ColumnDimension;
+/** Convenience: hide a column. */
+export declare function hideColumn(ws: Worksheet, col: number): ColumnDimension;
+/**
+ * Convenience: unhide a column. Drops the `hidden` flag from the column's
+ * dimension entry (and removes the entry altogether when no other fields
+ * remain).
+ */
+export declare function unhideColumn(ws: Worksheet, col: number): void;
+/** Bulk-hide every column in `[fromCol, toCol]`. */
+export declare function hideColumns(ws: Worksheet, fromCol: number, toCol: number): void;
+/** Bulk-unhide every column in `[fromCol, toCol]`. */
+export declare function unhideColumns(ws: Worksheet, fromCol: number, toCol: number): void;
+/**
+ * Set the default column width (characters) for cells without an explicit
+ * ColumnDimension entry. Mirrors Excel's "Default Width" dialog. Pass
+ * `undefined` to clear.
+ */
+export declare function setDefaultColumnWidth(ws: Worksheet, width: number | undefined): void;
+/**
+ * Set the default row height (points) for rows without an explicit RowDimension
+ * entry. Mirrors Excel's "Default Row Height" dialog. Pass `undefined` to
+ * clear.
+ */
+export declare function setDefaultRowHeight(ws: Worksheet, height: number | undefined): void;
+/**
+ * Mirror Excel's "Data → Group → Rows" by stamping every row in `[fromRow,
+ * toRow]` with an outline depth of `level` (default 1). Allocates a
+ * RowDimension for each row that doesn't already have one. Ungroup with {@link
+ * ungroupRows}.
+ */
+export declare function groupRows(ws: Worksheet, fromRow: number, toRow: number, level?: number): void;
+/**
+ * Drop the outline grouping for every row in `[fromRow, toRow]`. Removes the
+ * `outlineLevel` field from each affected RowDimension.
+ */
+export declare function ungroupRows(ws: Worksheet, fromRow: number, toRow: number): void;
+/**
+ * Mirror Excel's "Data → Group → Columns" by stamping every column in
+ * `[fromCol, toCol]` with an outline depth of `level` (default 1).
+ */
+export declare function groupColumns(ws: Worksheet, fromCol: number, toCol: number, level?: number): void;
+/**
+ * Drop the outline grouping for every column in `[fromCol, toCol]`. Removes the
+ * `outlineLevel` field from each affected ColumnDimension.
+ */
+export declare function ungroupColumns(ws: Worksheet, fromCol: number, toCol: number): void;
+/**
+ * Collapse a row outline group: hide every row in `[fromRow, toRow]` and mark
+ * them `collapsed: true`. Mirrors Excel's `−` button on a grouped row strip.
+ * Rows must already carry an `outlineLevel` from {@link groupRows} for the
+ * collapse to render correctly.
+ */
+export declare function collapseRowGroup(ws: Worksheet, fromRow: number, toRow: number): void;
+/**
+ * Expand a row outline group: drop the `hidden` and `collapsed` flags on every
+ * row in `[fromRow, toRow]`. Leaves `outlineLevel` and other dimensions intact.
+ */
+export declare function expandRowGroup(ws: Worksheet, fromRow: number, toRow: number): void;
+/**
+ * Collapse a column outline group: hide + mark `collapsed: true` for every
+ * column in `[fromCol, toCol]`. Columns must already carry an `outlineLevel`
+ * from {@link groupColumns} for the collapse to render correctly.
+ */
+export declare function collapseColumnGroup(ws: Worksheet, fromCol: number, toCol: number): void;
+/**
+ * Expand a column outline group: drop `hidden` and `collapsed` from every
+ * column in `[fromCol, toCol]`. Leaves `outlineLevel` intact.
+ */
+export declare function expandColumnGroup(ws: Worksheet, fromCol: number, toCol: number): void;
+/**
+ * Approximate autofit for a column. Scans every populated cell in `col` (or in
+ * `[opts.minRow, opts.maxRow]`), measures `cellValueAsString` length, and sets
+ * the column width to `max(length) + padding`, clamped to `[opts.min ?? 4,
+ * opts.max ?? 80]` and bounded above by Excel's hard limit of 255.
+ *
+ * Note: this is a string-length approximation — Excel sizes columns with the
+ * font's actual character-width metrics. For plain ASCII in the default Calibri
+ * 11 face the result is usually within ±1 width unit; CJK / wide glyphs need
+ * extra padding.
+ *
+ * Pass `opts.workbook` (or use the `Wb` variant via `autofitColumns`) to enable
+ * font-aware scaling — each cell's length is scaled by `(cellFont.size / 11)`
+ * so 22pt headings get roughly 2× width.
+ */
+export declare function autofitColumn(ws: Worksheet, col: number, opts?: {
+    minRow?: number;
+    maxRow?: number;
+    padding?: number;
+    min?: number;
+    max?: number;
+    workbook?: {
+        styles: {
+            cellXfs: ReadonlyArray<{
+                fontId: number;
+            }>;
+            fonts: ReadonlyArray<{
+                size?: number;
+            }>;
+        };
+    };
+}): ColumnDimension | undefined;
+/**
+ * Approximate autofit for every column with at least one populated cell. Walks
+ * the worksheet once collecting per-column widest-length + applies {@link
+ * autofitColumn} per column. `opts.workbook` enables font-size-aware scaling;
+ * without it the helper falls back to plain string length.
+ */
+export declare function autofitColumns(ws: Worksheet, opts?: {
+    padding?: number;
+    min?: number;
+    max?: number;
+    workbook?: {
+        styles: {
+            cellXfs: ReadonlyArray<{
+                fontId: number;
+            }>;
+            fonts: ReadonlyArray<{
+                size?: number;
+            }>;
+        };
+    };
+}): void;
+/**
+ * Set widths for many columns in one call. `widths` maps either:
+ * - an array `[12, 16, 20]` interpreted positionally starting at
+ * column `startCol` (default 1), or
+ * - a `Record<number, number>` keyed by 1-based column index.
+ * Each entry sets `customWidth: true`.
+ */
+export declare function setColumnWidths(ws: Worksheet, widths: ReadonlyArray<number> | Record<number, number>, startCol?: number): void;
+/** Look up a row's dimension entry. */
+export declare function getRowDimension(ws: Worksheet, row: number): RowDimension | undefined;
+export declare function setRowDimension(ws: Worksheet, row: number, opts: Partial<RowDimension>): RowDimension;
+/** Convenience: set a row's height, marking customHeight=true. */
+export declare function setRowHeight(ws: Worksheet, row: number, height: number): RowDimension;
+/**
+ * Set heights for many rows in one call. `heights` accepts an array (positional
+ * from `startRow`, default 1) or a `Record<number, number>` keyed by 1-based
+ * row index. Each entry sets `customHeight: true`.
+ */
+export declare function setRowHeights(ws: Worksheet, heights: ReadonlyArray<number> | Record<number, number>, startRow?: number): void;
+/** Convenience: hide a row. */
+export declare function hideRow(ws: Worksheet, row: number): RowDimension;
+/**
+ * Convenience: unhide a row. Drops the `hidden` flag from the row's dimension
+ * entry (and removes the entry altogether when no other fields remain).
+ */
+export declare function unhideRow(ws: Worksheet, row: number): void;
+/** Bulk-hide every row in `[fromRow, toRow]`. */
+export declare function hideRows(ws: Worksheet, fromRow: number, toRow: number): void;
+/** Bulk-unhide every row in `[fromRow, toRow]`. */
+export declare function unhideRows(ws: Worksheet, fromRow: number, toRow: number): void;
+/**
+ * Replace any prior hyperlink on the same `ref` with the given options. Pass `{
+ * target }` for an external URL, `{ location }` for an internal jump, or both.
+ * Returns the resulting Hyperlink record.
+ */
+export declare function setHyperlink(ws: Worksheet, ref: string, opts: {
+    target?: string;
+    location?: string;
+    display?: string;
+    tooltip?: string;
+}): Hyperlink;
+/** Remove the hyperlink registered against `ref`. Returns true if anything was removed. */
+export declare function removeHyperlink(ws: Worksheet, ref: string): boolean;
+/** Drop every hyperlink on the worksheet. Returns the count removed. */
+export declare function removeAllHyperlinks(ws: Worksheet): number;
+/** Look up a hyperlink by its ref. */
+export declare function getHyperlink(ws: Worksheet, ref: string): Hyperlink | undefined;
+/** Read-only snapshot of every hyperlink on the sheet. */
+export declare function listHyperlinks(ws: Worksheet): ReadonlyArray<Hyperlink>;
+/**
+ * Resolve a cell to its hyperlink (if any). Walks every hyperlink entry on the
+ * worksheet and returns the first whose `ref` (a single cell `"A1"` or a range
+ * `"A1:B5"`) covers the cell's coordinate. Returns `undefined` when no entry
+ * matches.
+ */
+export declare function getCellHyperlink(ws: Worksheet, c: Cell): Hyperlink | undefined;
+/**
+ * Resolve a cell to its legacy comment (if any). Same matching rule as {@link
+ * getCellHyperlink} — the comment's `ref` may be a single cell or a range, and
+ * the first containing entry wins.
+ */
+export declare function getCellComment(ws: Worksheet, c: Cell): LegacyComment | undefined;
+/** Append a DataValidation entry. */
+export declare function addDataValidation(ws: Worksheet, dv: DataValidation): DataValidation;
+/** Drop every validation whose sqref overlaps `ref` (string parse). Returns count removed. */
+export declare function removeDataValidations(ws: Worksheet, predicate: (dv: DataValidation) => boolean): number;
+/** Read-only snapshot of every data validation block on the sheet. */
+export declare function listDataValidations(ws: Worksheet): ReadonlyArray<DataValidation>;
+/** Drop every data validation block on the worksheet. Returns the count removed. */
+export declare function removeAllDataValidations(ws: Worksheet): number;
+/** Set or replace the worksheet's AutoFilter. Pass `undefined` to clear. */
+export declare function setAutoFilter(ws: Worksheet, filter: AutoFilter | undefined): void;
+/** Read the current AutoFilter, if any. */
+export declare function getAutoFilter(ws: Worksheet): AutoFilter | undefined;
+/** Append a table. The id and displayName must be workbook-unique — the caller is responsible. */
+export declare function addTable(ws: Worksheet, table: TableDefinition): TableDefinition;
+/** Look up a table by displayName. */
+export declare function getTable(ws: Worksheet, displayName: string): TableDefinition | undefined;
+/** Read-only snapshot of every Excel table defined on the sheet. */
+export declare function listTables(ws: Worksheet): ReadonlyArray<TableDefinition>;
+/** Drop a table by displayName. Returns true when something was removed. */
+export declare function removeTable(ws: Worksheet, displayName: string): boolean;
+/** Drop every Excel table on the worksheet. Returns the count removed. */
+export declare function removeAllTables(ws: Worksheet): number;
+/** Add or replace the comment at `ref`. */
+export declare function setComment(ws: Worksheet, opts: {
+    ref: string;
+    author: string;
+    text: string;
+}): LegacyComment;
+export declare function getComment(ws: Worksheet, ref: string): LegacyComment | undefined;
+export declare function removeComment(ws: Worksheet, ref: string): boolean;
+/** Read-only snapshot of every legacy comment on the sheet. */
+export declare function listComments(ws: Worksheet): ReadonlyArray<LegacyComment>;
+/** Drop every legacy comment on the worksheet. Returns the count removed. */
+export declare function removeAllComments(ws: Worksheet): number;
+/**
+ * Replace just the text of an existing comment, leaving its ref and author
+ * untouched. Returns `true` when the comment was found.
+ */
+export declare function editCommentText(ws: Worksheet, ref: string, newText: string): boolean;
+/**
+ * Replace just the author of an existing comment, leaving its ref and text
+ * untouched. Returns `true` when the comment was found.
+ */
+export declare function editCommentAuthor(ws: Worksheet, ref: string, newAuthor: string): boolean;
+/**
+ * Rename every comment authored by `oldName` to `newName`. Returns the number
+ * of comments updated. Useful when consolidating comments after a team handoff
+ * (Excel's commentsN.xml dedups authors at save time, so a single rename
+ * collapses cleanly).
+ */
+export declare function renameCommentAuthor(ws: Worksheet, oldName: string, newName: string): number;
+/** Filter every legacy comment by author. */
+export declare function findCommentsByAuthor(ws: Worksheet, author: string): ReadonlyArray<LegacyComment>;
+/** Append a conditional formatting block. */
+export declare function addConditionalFormatting(ws: Worksheet, cf: ConditionalFormatting): ConditionalFormatting;
+/** All conditional formatting blocks (read-only view). */
+export declare function getConditionalFormatting(ws: Worksheet): ReadonlyArray<ConditionalFormatting>;
+/** Drop every conditional-formatting block on the worksheet. Returns the count removed. */
+export declare function removeAllConditionalFormatting(ws: Worksheet): number;
+/** Pin a cell to the Watch Window. Returns the pushed entry. */
+export declare function addCellWatch(ws: Worksheet, watch: CellWatch): CellWatch;
+/** Remove cell watches matching `predicate`. Returns the count removed. */
+export declare function removeCellWatches(ws: Worksheet, predicate: (w: CellWatch) => boolean): number;
+/** Append an ignored-error region. */
+export declare function addIgnoredError(ws: Worksheet, ie: IgnoredError): IgnoredError;
+/** Remove ignored-error entries matching `predicate`. Returns the count removed. */
+export declare function removeIgnoredErrors(ws: Worksheet, predicate: (ie: IgnoredError) => boolean): number;