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;