/**
 * Worksheet identity, sparse cell access, merged ranges, conditional formatting,
 * data validations, hyperlinks, freeze panes, page setup, and text boxes
 * (M1.1 / M1.2 / TASK-1209–1216).
 *
 * Citations:
 * - docs/specs/worksheet-cells.md; docs/specs/merged-cells.md
 * - docs/specs/conditional-formatting.md; docs/specs/data-validations.md;
 *   docs/specs/hyperlinks.md
 * - docs/specs/freeze-panes.md; docs/specs/page-setup.md
 * - docs/specs/column-properties.md (cols / col widths)
 * - docs/specs/standard-height.md (sheetFormatPr / defaultRowHeight)
 * - docs/specs/text-boxes.md (DrawingML worksheet drawings)
 * - CT_Worksheet / sheetData / sheetViews / sheetFormatPr / cols / mergeCells /
 *   conditionalFormatting / dataValidations / hyperlinks / printOptions /
 *   pageMargins / pageSetup / drawing in transitional sml.xsd
 *
 * Merge content rule: store visible values/styles on the **top-left** cell of
 * each merge. {@link Worksheet.mergedCells} does not move or clear covered cells.
 */
import { Cell } from '../cell/cell';
import { CellModel } from '../cell/cell-model';
import { OpcPackage } from '../core/package/opc-package';
import { RichTextRun } from '../shared-strings/rich-text-xml';
import { SharedStringTable } from '../shared-strings/shared-string-table';
import { WorkbookStyles } from '../styles/workbook-styles';
import { ConditionalFormats } from '../worksheet/conditional-formatting';
import { DataValidations } from '../worksheet/data-validations';
import { FreezePanes } from '../worksheet/freeze-panes';
import { Columns } from '../worksheet/columns';
import { Rows } from '../worksheet/rows';
import { DataSorter } from '../worksheet/sort-state';
import { AutoFilter } from '../worksheet/auto-filter';
import { HyperlinksImpl, Hyperlinks } from '../worksheet/hyperlinks';
import { MergedCells } from '../worksheet/merged-cells';
import { PageSetup } from '../worksheet/page-setup';
import { Range } from '../worksheet/range';
import { Tables } from '../worksheet/tables';
import { TableEntry, TablePartsModel } from '../worksheet/table-model';
import { TextBox } from '../worksheet/text-boxes';
import { AutoShapeType, Shape, ShapesCollection } from '../worksheet/autoshapes';
import { Image } from '../worksheet/images';
import { Chart, ChartData, ChartType } from '../worksheet/charts';
import { CheckBox, CheckState, ComboBox, ComboDropStyle, EditBox, EditValidation, FormButton, FormLabel, GroupBox, ListBox, OptionButton, ScrollBar, SpinButton } from '../worksheet/form-controls';
import { CommentsImpl, AddCommentOptions, Comment, Comments } from '../worksheet/comments';
import { SheetProtectionInfo, SheetProtectionOptions } from '../worksheet/sheet-protection';
import { ProtectedRanges } from '../worksheet/protected-ranges';
import { ThreadedCommentsImpl, ThreadedComment } from '../worksheet/threaded-comments';
import { PersonsStore } from './persons';
import { SheetCollection } from './sheet-collection';
import { SheetKind, SheetVisibility, SheetXmlEntry } from './workbook-xml';
/**
 * Represents a single worksheet in a workbook, letting you read and write
 * its cells, formatting, tables, charts, and print settings.
 *
 * Public accessors (API-RULES R1.5): `cell`, `range`, `merges`,
 * `conditionalFormats`, `dataValidations`, `hyperlinks`, `freeze`, `pageSetup`, `textBoxes`, `images`.
 * View/state properties (API-RULES R1.1): `visibility`,
 * `isGridLinesVisible`, `isRowColumnHeadersVisible`, `isDisplayZeros`,
 * `isRightToLeft`, `zoom`.
 * Column layout: `setColumnWidth`, `getColumnWidth`. Row layout:
 * `setRowHeight`, `getRowHeight`. Sheet default row height: `standardHeight`.
 * Used extent: `usedRange`, `lastRow`, `lastColumn` (bounding box of residual
 * cells; `undefined` when the sheet has none).
 * Scroll anchors: `topLeftCell` (`sheetView@topLeftCell`) and
 * `paneTopLeftCell` (`pane@topLeftCell`). Not {@link selectedRange}.
 * Sorting metadata: `dataSorter`, `addDataSorter`, `removeDataSorter` (state
 * record only — never a grid sort operation).
 */
export interface Worksheet {
    /** The sheet's name, shown on its tab — unique in the workbook. */
    name: string;
    /**
     * Whether the sheet is visible. Assign `false` to hide it. A sheet
     * loaded as "very hidden" reports `false` and keeps that state until
     * this property is set.
     */
    visibility: boolean;
    /**
     * Whether the sheet shows gridlines on screen. Default `true`. Hiding
     * gridlines affects only the screen — printing them is a separate
     * setting on {@link Worksheet.pageSetup}.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    isGridLinesVisible: boolean;
    /**
     * Whether the sheet shows its row numbers and column letters.
     * Default `true`. Affects only the screen, not printing.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    isRowColumnHeadersVisible: boolean;
    /**
     * Whether the sheet shows cells that contain zero. Default `true` — set
     * to `false` to leave zero-valued cells looking empty.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    isDisplayZeros: boolean;
    /**
     * Whether the sheet is laid out right-to-left — the direction used by
     * scripts like Arabic and Hebrew. Default `false`.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    isRightToLeft: boolean;
    /**
     * The zoom percentage the sheet opens at — for example `150` for 150%.
     * Default `100`.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     * @throws InvalidArgumentError when the value is not a finite integer ≥ 0
     */
    zoom: number;
    /**
     * The top-left cell of the normal scroll viewport — where the sheet is
     * scrolled to when it is not split. `undefined` when the file does not
     * store one. Not the freeze anchor and not {@link selectedRange}.
     *
     * Assign `'C10'` or `undefined` to clear. Reading this never creates cells.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     * @throws InvalidAddressError when the assigned address is not a single cell
     */
    topLeftCell: string | undefined;
    /**
     * The top-left cell of the active pane viewport (`pane` scroll anchor),
     * including split and unfrozen panes. `undefined` when there is no pane
     * or the pane does not store one. Not {@link Worksheet.topLeftCell}.
     *
     * Assigning does not create a freeze or a split. The sheet must already
     * have a pane (`freeze`, or a loaded split).
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     * @throws InvalidArgumentError when there is no pane to attach the cell to
     * @throws InvalidAddressError when the assigned address is not a single cell
     */
    paneTopLeftCell: string | undefined;
    /**
     * @private
     * Stable workbook relationship id (`r:id`).
     * Package identity — prefer sheet name/index for application code.
     */
    readonly relId: string;
    /**
     * @private
     * `CT_Sheet` sheetId.
     * Package identity — prefer sheet name/index for application code.
     */
    readonly sheetId: number;
    /**
     * @private
     * Resolved OPC part name when internal.
     * Package identity — not needed for normal spreadsheet work.
     */
    readonly partName: string | undefined;
    /** @private worksheet vs other (chartsheet, etc.). */
    readonly kind: SheetKind;
    /**
     * The merged areas on this sheet. For merging one range at a time,
     * `sheet.range('A1:B2').merge()` is often simpler.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly merges: MergedCells;
    /**
     * The conditional-formatting rules on this sheet — visual highlights
     * such as color scales, data bars, and icon sets.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly conditionalFormats: ConditionalFormats;
    /**
     * The data-validation rules on this sheet — restrictions on what can be
     * typed into cells, with optional input prompts and error alerts.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly dataValidations: DataValidations;
    /**
     * The hyperlinks on this sheet. For links on a single cell,
     * `cell.hyperlink` is often simpler.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly hyperlinks: Hyperlinks;
    /**
     * The sheet's frozen rows and columns — what stays fixed while the rest
     * scrolls.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly freeze: FreezePanes;
    /**
     * The sheet's printing settings — paper size, orientation, margins,
     * headers and footers, and what part of the sheet prints.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly pageSetup: PageSetup;
    /**
     * Internal column records for this worksheet (`cols` / `col`).
     *
     * Public authoring uses {@link Worksheet.setColumnWidth} /
     * {@link Worksheet.getColumnWidth} only. Enumeration via {@link Columns.list}
     * is package-internal (no dense allocation).
     *
     * Citations: docs/specs/column-properties.md; transitional sml.xsd
     * `CT_Cols` / `CT_Col`; ECMA-376-1 §18.3.1.17 / §18.3.1.12.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     * @private
     */
    readonly columns: Columns;
    /**
     * Set the width of a column, measured in the character units Excel uses
     * for column widths — `10` fits roughly ten characters of the default
     * font. Setting a width never creates cells.
     *
     * @param index - The 1-based column number — `1` is column A.
     * @param width - The new width, in character units (≥ 0).
     * @throws InvalidArgumentError when index or width is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    setColumnWidth(index: number, width: number): void;
    /**
     * The effective width of a column in character units, or `0` when it
     * has no custom width.
     *
     * @param index - The 1-based column number — `1` is column A.
     * @throws InvalidArgumentError when index is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    getColumnWidth(index: number): number;
    /**
     * Internal sparse row records for authored row properties (`row/@ht`).
     * Public authoring uses {@link Worksheet.setRowHeight} /
     * {@link Worksheet.getRowHeight} only.
     *
     * @private
     */
    readonly rows: Rows;
    /**
     * Set the height of a row, in points. Setting a height never creates
     * cells.
     *
     * @param index - The 1-based row number.
     * @param height - The new height, in points (≥ 0).
     * @throws InvalidArgumentError when index or height is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    setRowHeight(index: number, height: number): void;
    /**
     * The height of a row in points, or `0` when it has no custom height.
     *
     * @param index - The 1-based row number.
     * @throws InvalidArgumentError when index is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    getRowHeight(index: number): number;
    /**
     * Sheet default row height in points (`sheetFormatPr@defaultRowHeight`).
     * Returns `0` when the sheet has no authored or loaded standard height.
     * Setting authors `sheetFormatPr` with the required attribute; never densifies
     * the grid.
     *
     * Citations: docs/specs/standard-height.md; sml.xsd CT_SheetFormatPr/
     * @defaultRowHeight; API-RULES R1.4.
     *
     * @throws InvalidArgumentError when value is not a finite number ≥ 0
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    standardHeight: number;
    /**
     * The tables on this sheet — formatted, named ranges of cells with
     * headers, banded rows, and optional totals rows.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly tables: Tables;
    /**
     * The sort recorded for this sheet — a note of which range was sorted
     * and how, kept from a previous sort. The library stores and re-saves
     * it; it never rearranges cell data. `undefined` when the sheet has no
     * sort record.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly dataSorter: DataSorter | undefined;
    /**
     * Record a sort for this sheet, or replace the existing one. The range
     * itself is unaffected — no cells are moved or created.
     *
     * The range is never densified: authoring a sort state allocates no cells.
     *
     * @param range - The whole range of data to sort, like `'A1:C10'`
     *   (required).
     * @returns the sort record, for setting its flags and conditions.
     * @throws InvalidArgumentError when `range` is missing/empty
     * @throws InvalidSortStateError when `range` does not parse as an A1 range
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addDataSorter(range: string): DataSorter;
    /**
     * Remove the sheet's sort record. Does nothing when there is none.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeDataSorter(): void;
    /**
     * The filter criteria recorded for this sheet, when a filter is set.
     * Only the criteria are stored — no rows are ever hidden by this
     * library.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly autoFilter: AutoFilter | undefined;
    /**
     * Set a filter on a range of cells, or replace the existing one. Only
     * the criteria are recorded — the library never hides rows; Excel
     * applies the filter when it opens the file.
     *
     * @param range - The range to filter, like `'A1:D10'` (required).
     * @returns the filter, for choosing values per column.
     * @throws InvalidArgumentError when `range` is missing/empty
     * @throws InvalidAutoFilterError when `range` does not parse as an A1 range
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addAutoFilter(range: string): AutoFilter;
    /**
     * Remove the sheet's filter. Does nothing when there is none.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeAutoFilter(): void;
    /**
     * The text boxes on this sheet, in the order they were added.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly textBoxes: ReadonlyArray<TextBox>;
    /**
     * The shapes on this sheet — rectangles, ellipses, arrows, and other
     * preset shapes. Add with {@link addShape}.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly shapes: ShapesCollection;
    /** The pictures placed on this sheet, floating above the cells. */
    readonly images: ReadonlyArray<Image>;
    /**
     * The charts embedded on this sheet.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly charts: ReadonlyArray<Chart>;
    /**
     * The smallest rectangle that contains every cell that still has a value,
     * formula, style, or other stored content. `undefined` when the sheet has
     * no such cells.
     *
     * Column widths, row heights, merges, and the file's `dimension` hint do
     * not count by themselves. Reading this never creates cells.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly usedRange: Range | undefined;
    /**
     * The 1-based row of the bottom-most cell that still has content, or
     * `undefined` when the sheet has none. Same edge as {@link usedRange}.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly lastRow: number | undefined;
    /**
     * The 1-based column of the right-most cell that still has content
     * (`1` is column A), or `undefined` when the sheet has none. Same edge as
     * {@link usedRange}.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly lastColumn: number | undefined;
    /**
     * The cells Excel highlights on this sheet — the selection, not the cells
     * that contain data. `undefined` when the sheet has no stored selection.
     *
     * Assign a {@link Range} from {@link range}, or `undefined` to clear it.
     * Reading this never creates cells and does not change {@link usedRange}.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     * @throws InvalidAddressError when the assigned address is not a single range
     */
    selectedRange: Range | undefined;
    /**
     * Get a cell, either by its address — `sheet.cell('B2')` — or by its
     * 1-based position — `sheet.cell(2, 2)`. No storage is used until a
     * value is set on the cell.
     *
     * @throws InvalidAddressError when the address is not a single cell reference
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    cell(addressOrRow: string | number, column?: number): Cell;
    /**
     * Get a cell by its A1 address, like `'B2'`. An alias of
     * `sheet.cell(address)`.
     *
     * @throws InvalidAddressError when the address is not a single cell reference
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    getCell(address: string): Cell;
    /**
     * Get a rectangular area of cells — `sheet.range('A1:C3')` — for
     * reading or merging.
     *
     * @throws InvalidMergeRefError when the ref is malformed
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    range(ref: string): Range;
    /**
     * The merged areas on this sheet.
     * @deprecated Prefer {@link merges}. Kept as a compatibility alias.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    readonly mergedCells: MergedCells;
    /**
     * Cell handle at an A1 address.
     * @deprecated Prefer {@link cell}, which also accepts 1-based
     *   `(row, column)`. Kept as a compatibility alias.
     *
     * @throws InvalidAddressError when the address is not a single cell reference
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    getCell(address: string): Cell;
    /**
     * Add a text box anchored at a cell. Size is width and height in points
     * (72 pt = 1 in).
     *
     * @param row - The 1-based row the box's top edge is anchored to.
     * @param column - The 1-based column the box's left edge is anchored to.
     * @param width - The box's width, in points, like `144` (2 in).
     * @param height - The box's height, in points, like `72` (1 in).
     * @param text - The text shown inside the box; default empty.
     * @returns the newly created text box.
     * @throws InvalidArgumentError when geometry is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addTextBox(row: number, column: number, width: number, height: number, text?: string): TextBox;
    /**
     * Remove a text box.
     *
     * @param target - The text box to remove, or its zero-based position
     *   among the sheet's text boxes.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeTextBox(target: TextBox | number): void;
    /**
     * Add a shape anchored at a cell — a rectangle, ellipse, arrow, or
     * another preset. Size is width and height in points (72 pt = 1 in).
     * Set fill, outline, and text on the returned shape.
     *
     * @param type - The kind of shape, like `AutoShapeType.Rectangle`.
     * @param row - The 1-based row the shape's top edge is anchored to.
     * @param column - The 1-based column the shape's left edge is anchored to.
     * @param width - The shape's width, in points, like `144` (2 in).
     * @param height - The shape's height, in points, like `72` (1 in).
     * @param text - The text shown inside the shape, when any.
     * @param name - The name identifying the shape; generated when omitted.
     * @param altText - The alt text for accessibility tools, when any.
     * @param rotation - How far to turn the shape, in degrees clockwise.
     * @param moveWithCell - Whether the shape moves with its anchor cells.
     *   Default `true`.
     * @param sizeWithCell - Whether the shape resizes with its anchor cells.
     *   Default `false`.
     * @returns the newly created shape.
     * @throws InvalidArgumentError when geometry is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addShape(type: AutoShapeType, row: number, column: number, width: number, height: number, text?: string, name?: string, altText?: string, rotation?: number, moveWithCell?: boolean, sizeWithCell?: boolean): Shape;
    /**
     * Remove a shape.
     *
     * @param target - The shape to remove, or its zero-based position among
     *   the sheet's shapes.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeShape(target: Shape | number): void;
    /**
     * Add a picture to the sheet, anchored at a cell and floating above the
     * cells. The picture format is detected from `bytes`.
     *
     * @param bytes - The raw bytes of the picture file.
     * @param row - The 1-based row the picture's top edge is anchored to.
     * @param column - The 1-based column the picture's left edge is anchored to.
     * @param width - Picture width in points (72 points = 1 inch). Example: `144` = 2 inches.
     * @param height - Picture height in points (72 points = 1 inch). Example: `72` = 1 inch.
     * @returns the newly added picture.
     * @throws InvalidArgumentError when geometry or bytes are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addImage(bytes: Uint8Array, row: number, column: number, width: number, height: number): Image;
    /**
     * Remove a picture from the sheet.
     *
     * @param target - The picture to remove, or its zero-based position
     *   among the sheet's pictures.
     */
    removeImage(target: Image | number): void;
    /**
     * Add a chart on this worksheet — column, line, pie, funnel, waterfall,
     * and other {@link ChartType} layouts. Pass type, position, size, and a
     * data argument (`dataRange` string, category/values formulas, or
     * {@link ChartData}). Presentation (title, legend, axes) is set on the
     * returned {@link Chart}; more series via {@link Chart.addSeries}. Drawing
     * and chart parts are written on save.
     *
     * @param type - Chart layout from {@link ChartType}.
     * @param row - Top-left row (1-based).
     * @param column - Top-left column (1-based; 1 = A).
     * @param width - Width in points.
     * @param height - Height in points.
     * @param data - A1 range string, category-label formula string(s), or
     *   {@link ChartData}. Pass `''` to create an empty chart and add series
     *   with {@link Chart.addSeries}.
     * @param values - Values formula when `data` is category-label formula(s).
     * @returns the newly created chart.
     * @throws InvalidChartError when arguments are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addChart(type: ChartType, row: number, column: number, width: number, height: number, data: string | ReadonlyArray<string> | ChartData, values?: string): Chart;
    /**
     * Remove a chart from the sheet.
     *
     * @param target - The chart to remove, or its zero-based position among
     *   the sheet's charts.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeChart(target: Chart | number): void;
    /** The check boxes on this sheet, in the order they were added. */
    readonly checkBoxes: ReadonlyArray<CheckBox>;
    /** The combo boxes and drop-downs on this sheet. */
    readonly comboBoxes: ReadonlyArray<ComboBox>;
    /** The option buttons (radio buttons) on this sheet. */
    readonly optionButtons: ReadonlyArray<OptionButton>;
    /**
     * Add a check box anchored at a cell. Size is width and height in points
     * (72 pt = 1 in).
     *
     * @param row - The 1-based row the box's top edge is anchored to.
     * @param column - The 1-based column the box's left edge is anchored to.
     * @param width - The box's width, in points, like `72` (1 in).
     * @param height - The box's height, in points, like `18`.
     * @param name - The name identifying the box; generated when omitted.
     * @param text - The label shown beside the box.
     * @param checkState - The box's initial state; default unchecked.
     * @param linkedCell - The cell that reports the box's state.
     * @param isDisplay3DShading - Whether the box is drawn 3-D; default
     *   `true`.
     * @returns the newly created check box.
     * @throws InvalidArgumentError when options are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addCheckBox(row: number, column: number, width: number, height: number, name?: string, text?: string, checkState?: CheckState, linkedCell?: string, isDisplay3DShading?: boolean): CheckBox;
    /**
     * Add an editable combo box — a drop-down that can also be typed into.
     *
     * @param dropStyle - The kind of drop behavior; default `'combo'`.
     * @returns the newly created combo box.
     * @throws InvalidArgumentError when options are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addComboBox(row: number, column: number, width: number, height: number, name?: string, listFillRange?: string, linkedCell?: string, selectedIndex?: number, dropDownLines?: number, dropStyle?: ComboDropStyle, isDisplay3DShading?: boolean): ComboBox;
    /**
     * Add a combo box that can also be typed into, like a browser's
     * address bar with suggestions.
     *
     * @returns the newly created combo box.
     * @throws InvalidArgumentError when options are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addComboEditBox(row: number, column: number, width: number, height: number, name?: string, listFillRange?: string, linkedCell?: string, selectedIndex?: number, dropDownLines?: number, isDisplay3DShading?: boolean): ComboBox;
    /**
     * Add a simple drop-down — the list stays visible only while its button
     * is held.
     *
     * @returns the newly created combo box.
     * @throws InvalidArgumentError when options are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addComboDropdown(row: number, column: number, width: number, height: number, name?: string, listFillRange?: string, linkedCell?: string, selectedIndex?: number, dropDownLines?: number, isDisplay3DShading?: boolean): ComboBox;
    /**
     * Add an option button (radio button). Only one button in a group can
     * be selected at a time.
     *
     * @param isFirstButton - Whether this is the first button of its group —
     *   the anchor that links them. Default `false`.
     * @returns the newly created option button.
     * @throws InvalidArgumentError when options are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addOptionButton(row: number, column: number, width: number, height: number, name?: string, text?: string, checkState?: CheckState, linkedCell?: string, isDisplay3DShading?: boolean, isFirstButton?: boolean): OptionButton;
    /**
     * Remove a check box.
     *
     * @param target - The check box to remove, or its zero-based position
     *   among the sheet's check boxes.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeCheckBox(target: CheckBox | number): void;
    /**
     * Remove a combo box.
     *
     * @param target - The combo box to remove, or its zero-based position
     *   among the sheet's combo boxes.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeComboBox(target: ComboBox | number): void;
    /**
     * Remove an option button.
     *
     * @param target - The option button to remove, or its zero-based
     *   position among the sheet's option buttons.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeOptionButton(target: OptionButton | number): void;
    /** The buttons on this sheet. */
    readonly buttons: ReadonlyArray<FormButton>;
    /** The list boxes on this sheet. */
    readonly listBoxes: ReadonlyArray<ListBox>;
    /** The group boxes on this sheet — frames that group related controls. */
    readonly groupBoxes: ReadonlyArray<GroupBox>;
    /** The text labels on this sheet. */
    readonly formLabels: ReadonlyArray<FormLabel>;
    /** The scroll bars on this sheet. */
    readonly scrollBars: ReadonlyArray<ScrollBar>;
    /** The spin buttons on this sheet — up/down steppers for values. */
    readonly spinButtons: ReadonlyArray<SpinButton>;
    /** The edit boxes (text fields) on this sheet. */
    readonly editBoxes: ReadonlyArray<EditBox>;
    /**
     * Add a button that can trigger an assigned macro when clicked. The
     * macro name is stored only — it is never executed by this library.
     *
     * @param text - The text shown on the button face.
     * @param onAction - The macro to run when clicked, by name.
     * @returns the newly created button.
     * @throws InvalidArgumentError when options are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addButton(row: number, column: number, width: number, height: number, name?: string, text?: string, onAction?: string): FormButton;
    /**
     * Add a list box showing entries from a range of cells.
     *
     * @param listFillRange - The cells the list's entries come from.
     * @param linkedCell - The cell the selected entry is written to.
     * @param selectionType - How many entries can be picked; default `'single'`.
     * @returns the newly created list box.
     * @throws InvalidArgumentError when options are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addListBox(row: number, column: number, width: number, height: number, name?: string, listFillRange?: string, linkedCell?: string, selectedIndex?: number, selectionType?: 'single' | 'multi' | 'extended', selectedIndices?: ReadonlyArray<number>, isDisplay3DShading?: boolean, value?: number): ListBox;
    /**
     * Add a group box — a labeled frame that groups related controls, such
     * as a set of option buttons.
     *
     * @param text - The caption shown on the frame's border.
     * @param groupLinkedCell - The cell that reports which option button in
     *   the group is selected.
     * @returns the newly created group box.
     * @throws InvalidArgumentError when options are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addGroupBox(row: number, column: number, width: number, height: number, name?: string, text?: string, groupLinkedCell?: string): GroupBox;
    /**
     * Add a plain text label.
     *
     * @param text - The text shown on the label.
     * @param textLink - The cell whose value the label shows, when linked.
     * @returns the newly created label.
     * @throws InvalidArgumentError when options are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addFormLabel(row: number, column: number, width: number, height: number, name?: string, text?: string, textLink?: string): FormLabel;
    /**
     * Add a scroll bar for changing a value smoothly by dragging.
     *
     * @param linkedCell - The cell the position is written to.
     * @param min / max - The lowest / highest position.
     * @param incrementalChange - Movement per arrow click.
     * @param pageChange - Movement per track click.
     * @param isHorizontal - Lay the bar out horizontally; default vertical.
     * @returns the newly created scroll bar.
     * @throws InvalidArgumentError when options are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addScrollBar(row: number, column: number, width: number, height: number, name?: string, linkedCell?: string, value?: number, min?: number, max?: number, incrementalChange?: number, pageChange?: number, isHorizontal?: boolean): ScrollBar;
    /**
     * Add a spin button — paired up/down arrows that step a value.
     *
     * @param linkedCell - The cell the value is written to.
     * @param min / max - The lowest / highest value.
     * @param incrementalChange - Movement per arrow click.
     * @returns the newly created spin button.
     * @throws InvalidArgumentError when options are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addSpinButton(row: number, column: number, width: number, height: number, name?: string, linkedCell?: string, value?: number, min?: number, max?: number, incrementalChange?: number): SpinButton;
    /**
     * Add an edit box — a text field users can type into.
     *
     * @param textLink - The cell that shows what the user typed, when linked.
     * @param isMultiLine - Allow line breaks in the text.
     * @param validation - The kind of entry expected; default `'text'`.
     * @param isPassword - Mask the text like a password field.
     * @returns the newly created edit box.
     * @throws InvalidArgumentError when options are invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addEditBox(row: number, column: number, width: number, height: number, name?: string, text?: string, textLink?: string, isMultiLine?: boolean, validation?: EditValidation, isPassword?: boolean): EditBox;
    /**
     * Remove a button.
     *
     * @param target - The button to remove, or its zero-based position
     *   among the sheet's buttons.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeButton(target: FormButton | number): void;
    /**
     * Remove a list box.
     *
     * @param target - The list box to remove, or its zero-based position
     *   among the sheet's list boxes.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeListBox(target: ListBox | number): void;
    /**
     * Remove a group box.
     *
     * @param target - The group box to remove, or its zero-based position
     *   among the sheet's group boxes.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeGroupBox(target: GroupBox | number): void;
    /**
     * Remove a form label.
     *
     * @param target - The label to remove, or its zero-based position among
     *   the sheet's labels.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeFormLabel(target: FormLabel | number): void;
    /**
     * Remove a scroll bar.
     *
     * @param target - The scroll bar to remove, or its zero-based position
     *   among the sheet's scroll bars.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeScrollBar(target: ScrollBar | number): void;
    /**
     * Remove a spin button.
     *
     * @param target - The spin button to remove, or its zero-based position
     *   among the sheet's spin buttons.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeSpinButton(target: SpinButton | number): void;
    /**
     * Remove an edit box.
     *
     * @param target - The edit box to remove, or its zero-based position
     *   among the sheet's edit boxes.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeEditBox(target: EditBox | number): void;
    /**
     * Discussion threads on this sheet, in document order.
     */
    readonly threadedComments: ReadonlyArray<ThreadedComment>;
    /**
     * Remove one discussion thread and all of its replies.
     *
     * @param target - The thread to remove, or its zero-based index on the sheet.
     * @throws InvalidArgumentError when the target is invalid
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeThreadedComment(target: ThreadedComment | number): void;
    /**
     * Remove every discussion thread (and reply) on this sheet.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    clearThreadedComments(): void;
    /**
     * `true` when this worksheet is protected.
     */
    readonly isProtected: boolean;
    /**
     * Current sheet protection settings, or `undefined` when the sheet is not protected.
     */
    readonly sheetProtection: SheetProtectionInfo | undefined;
    /**
     * Protect this worksheet so users can only do what you allow.
     *
     * @param password - Optional password required to unprotect later.
     * @param options - Which actions remain allowed (select cells, format, sort, …).
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    protect(password?: string, options?: SheetProtectionOptions): void;
    /**
     * Remove worksheet protection.
     *
     * @param password - Required when the sheet was protected with a password.
     * @throws InvalidProtectionError when password is required/wrong
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    unprotect(password?: string): void;
    /**
     * Ranges users may still edit while the rest of the sheet is protected.
     */
    readonly protectedRanges: ProtectedRanges;
    /**
     * Classic sticky notes on this sheet.
     */
    readonly comments: Comments;
    /**
     * Add a classic sticky note on a cell.
     *
     * @param options - Target cell (`ref` or `row`/`column`) plus optional text, author, visibility, and size.
     * @throws InvalidCommentError when the cell already has a note
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    addComment(options: AddCommentOptions): Comment;
    /**
     * Remove a classic sticky note by handle, A1 address, or zero-based index.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    removeComment(target: Comment | string | number): void;
    /**
     * `true` when the given cell has a classic sticky note.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    hasComment(ref: string): boolean;
    hasComment(row: number, column: number): boolean;
    /**
     * Classic sticky note on the given cell, or `undefined` if none.
     *
     * @throws InvalidWorksheetError when the sheet is not a worksheet
     */
    getComment(ref: string): Comment | undefined;
    getComment(row: number, column: number): Comment | undefined;
}
/**
 * Host surface supplied by {@link Workbook} for cell SST and package I/O.
 * @private
 */
export interface WorksheetCellHost {
    readonly package: OpcPackage;
    sharedStrings(): SharedStringTable;
    /** Workbook styles table (cellXfs / ensure*). */
    styles(): WorkbookStyles;
    /** Workbook persons store (threaded-comment authors). */
    persons(): PersonsStore;
    /**
     * Live workbook 1904 date-system flag (`workbookPr/@date1904`).
     * Used by {@link Cell.dateTime} serial conversion.
     */
    date1904(): boolean;
    markDirty(): void;
    /** Allocate the next table part name (`/xl/tables/tableN.xml`). */
    nextTablePartName(): string;
    /** Record an observed table id for workbook-unique max+1 allocation. */
    noteTableId(id: number): void;
    /**
     * After a dirty flush densifies sheet table parts to `table1..count`,
     * advance workbook allocation so the next add uses `table{count+1}`.
     */
    noteTablePartCount(count: number): void;
    /** Allocate the next workbook-unique table id (max observed + 1). */
    allocateTableId(): number;
}
/**
 * Mutable worksheet implementation.
 * @private
 */
export declare class WorksheetImpl implements Worksheet {
    private collection;
    private _name;
    private _visibility;
    private readonly _sheetId;
    private readonly _relId;
    private readonly _partName;
    private readonly _kind;
    private readonly extraAttrsXml;
    /** Sparse storage: row → col → model. */
    private readonly cellRows;
    private sheetMeta;
    private sheetDataLoaded;
    private cellsDirty;
    private cellHost;
    private readonly _mergedCells;
    private readonly _conditionalFormats;
    private readonly _dataValidations;
    private readonly _hyperlinks;
    private readonly _freeze;
    private readonly _columns;
    private readonly _rowProperties;
    private readonly _sheetFormat;
    private readonly _sortState;
    private readonly _autoFilter;
    private readonly _pageSetup;
    /** Lazy tables collection; host wires into the wire plumbing lazily. */
    private _tables;
    /**
     * Worksheet `tableParts` refs from the parsed part plus lazily resolved
     * table entries (`CT_Table`). TASK-1210 wire scope: parse/serialize +
     * package plumbing; the public `Worksheet.tables` façade lands in
     * TASK-1211.
     */
    private tablePartsModel;
    /**
     * Resolved tables in file order: relId (worksheet relationship id) and the
     * parsed table entry. Entries whose part failed to parse or is missing are
     * soft-skipped here but their package parts stay untouched (preserve).
     */
    private readonly tableEntries;
    private tablesResolved;
    /**
     * Entries mutated since the last flush (localized mutation: only these
     * table parts are rewritten; untouched siblings keep their original bytes).
     */
    private readonly dirtyTableEntries;
    private readonly _textBoxes;
    private readonly _autoShapes;
    private readonly _images;
    private readonly _charts;
    private readonly _formControls;
    private readonly _comments;
    private readonly _protection;
    private readonly _protectedRanges;
    private readonly _threadedComments;
    constructor(collection: SheetCollection, entry: SheetXmlEntry, partName: string | undefined, kind: SheetKind);
    /** @private */
    bindCollection(collection: SheetCollection): void;
    /** @private */
    bindCellHost(host: WorksheetCellHost): void;
    name: string;
    visibility: boolean;
    /**
     * On-screen gridline visibility (`sheetView@showGridLines`).
     *
     * Citations: docs/specs/worksheet-view.md; transitional sml.xsd
     * `CT_SheetView/@showGridLines` (default `true`); API-RULES R1.2 / R1.4.
     */
    isGridLinesVisible: boolean;
    /**
     * Row/column header visibility (`sheetView@showRowColHeaders`).
     *
     * Citations: docs/specs/worksheet-view.md; transitional sml.xsd
     * `CT_SheetView/@showRowColHeaders` (default `true`); API-RULES R1.2 / R1.4.
     */
    isRowColumnHeadersVisible: boolean;
    /**
     * Zero-value display (`sheetView@showZeros`).
     *
     * Citations: docs/specs/worksheet-view.md; transitional sml.xsd
     * `CT_SheetView/@showZeros` (default `true`); API-RULES R1.2 / R1.4.
     */
    isDisplayZeros: boolean;
    /**
     * Right-to-left layout (`sheetView@rightToLeft`).
     *
     * Citations: docs/specs/worksheet-view.md; transitional sml.xsd
     * `CT_SheetView/@rightToLeft` (default `false`); API-RULES R1.2 / R1.4.
     */
    isRightToLeft: boolean;
    /**
     * Display zoom percentage (`sheetView@zoomScale`).
     *
     * Citations: docs/specs/worksheet-view.md; transitional sml.xsd
     * `CT_SheetView/@zoomScale` (default `100`); API-RULES R1.2 / R1.4.
     */
    zoom: number;
    /**
     * Column records (`cols` / `col`).
     *
     * Citations: docs/specs/column-properties.md; sml.xsd `CT_Cols` / `CT_Col`.
     */
    /** @private */
    readonly columns: Columns;
    /**
     * Set custom width for one 1-based column (OOXML character units).
     */
    setColumnWidth(index: number, width: number): void;
    /**
     * Effective column width, or `0` when unset.
     */
    getColumnWidth(index: number): number;
    /** Sparse authored row records (`row/@ht` / `@customHeight`). @private */
    readonly rows: Rows;
    /** Set custom height for one 1-based row in points. */
    setRowHeight(index: number, height: number): void;
    /** Effective authored row height in points, or `0` when unset. */
    getRowHeight(index: number): number;
    /**
     * Sheet default row height in points (`sheetFormatPr@defaultRowHeight`),
     * or `0` when unset.
     */
    standardHeight: number;
    /**
     * Sort state (`CT_Worksheet/sortState`) — the record Excel persists after
     * a user sort; the grid is never touched.
     *
     * Citations: docs/specs/sort-state.md; sml.xsd `CT_SortState` /
     * `CT_SortCondition`; ECMA-376-1 §18.3.1.91 / §18.3.1.92.
     */
    readonly dataSorter: DataSorter | undefined;
    /**
     * Author (or replace) the sort state. Replaces any existing record: the
     * schema permits at most one `sortState` per worksheet.
     */
    addDataSorter(range: string): DataSorter;
    /**
     * Remove the sort state entirely (no-op when absent).
     */
    removeDataSorter(): void;
    /**
     * AutoFilter criteria metadata (`CT_Worksheet/autoFilter`) — the record
     * Excel persists for filter drop-downs; the grid is never filtered or
     * row-hidden by this library (P1 metadata only).
     *
     * Citations: docs/specs/auto-filter.md; sml.xsd `CT_AutoFilter` /
     * `CT_FilterColumn` / `CT_Filters` / `CT_Filter`; ECMA-376-1 §18.3.1.2 /
     * §18.3.2.6–§18.3.2.8.
     */
    readonly autoFilter: AutoFilter | undefined;
    /**
     * Author (or replace) the AutoFilter. Replaces any existing record: the
     * schema permits at most one `autoFilter` per worksheet. Prior AutoFilter
     * handles from a previous generation throw on use.
     */
    addAutoFilter(range: string): AutoFilter;
    /**
     * Remove the AutoFilter entirely (no-op when absent).
     */
    removeAutoFilter(): void;
    /** @private Package relationship id used by workbook serialization. */
    readonly relId: string;
    /** @private Stable OOXML sheet id used by workbook serialization. */
    readonly sheetId: number;
    /** @private OPC part name used by workbook serialization. */
    readonly partName: string | undefined;
    /** @private Worksheet metadata discriminator used by package handling. */
    readonly kind: SheetKind;
    /**
     * Merge regions collection for this worksheet.
     *
     * Sole public merges surface (API-RULES R1.5).
     *
     * Citations: ECMA-376-1 §18.3.1.55; docs/specs/merged-cells.md; API-RULES R1.5.
     */
    readonly merges: MergedCells;
    /**
     * Conditional formatting collection. Loads sheet data on first access for worksheets.
     *
     * Citations: ECMA-376-1 §18.3.1.18 / §18.3.1.10; docs/specs/conditional-formatting.md;
     * API-RULES R1.5 / R5.1.
     */
    readonly conditionalFormats: ConditionalFormats;
    /**
     * Merged ranges collection. Compatibility alias for {@link merges}
     * (canonical L1 name per API-RULES R1.5).
     * @deprecated Prefer {@link merges}.
     */
    readonly mergedCells: MergedCells;
    /**
     * Data validations collection. Loads sheet data on first access for worksheets.
     */
    readonly dataValidations: DataValidations;
    /**
     * Hyperlinks collection. Loads sheet data on first access for worksheets.
     *
     * Citations: ECMA-376-1 §18.3.1.47–48; docs/specs/hyperlinks.md; API-RULES R1.5 / R5.1.
     */
    readonly hyperlinks: Hyperlinks;
    /**
     * Freeze panes (`sheet.freeze`). Loads sheet data on first access.
     *
     * Citations: docs/specs/freeze-panes.md; API-RULES R1.4 / R1.5.
     */
    readonly freeze: FreezePanes;
    /**
     * Page setup (`sheet.pageSetup`). Loads sheet data on first access.
     *
     * Citations: docs/specs/page-setup.md; API-RULES R1.5 / R3.5 / R4.
     */
    readonly pageSetup: PageSetup;
    /**
     * Text boxes on this worksheet (snapshot). Loads sheet + drawing on access.
     *
     * Citations: docs/specs/text-boxes.md; API-RULES R1.5 / R5.1.
     */
    readonly textBoxes: ReadonlyArray<TextBox>;
    /**
     * Autoshapes on this worksheet. Loads sheet + drawing on access.
     *
     * Citations: docs/specs/autoshapes.md; API-RULES R1.5 / R5.1.
     */
    readonly shapes: ShapesCollection;
    /**
     * Floating pictures on this worksheet. Pictures are drawing objects above
     * cells, not cell values or backgrounds.
     */
    readonly images: ReadonlyArray<Image>;
    /**
     * Classic charts on this worksheet. Loads sheet + drawing/chart parts on access.
     *
     * Citations: docs/specs/charts.md; API-RULES R1.5 / R5.1.
     */
    readonly charts: ReadonlyArray<Chart>;
    /**
     * Add a text box. Drawing package side effects defer to save/flush.
     *
     * Citations: docs/specs/text-boxes.md; API-RULES R1.1 / R2 / R5.1.
     */
    addTextBox(row: number, column: number, width: number, height: number, text?: string): TextBox;
    /**
     * Remove a text box by handle or 0-based index.
     *
     * Citations: docs/specs/text-boxes.md; API-RULES R1.1.
     */
    removeTextBox(target: TextBox | number): void;
    /**
     * Add an autoshape. Drawing package side effects defer to save/flush.
     *
     * Citations: docs/specs/autoshapes.md; API-RULES R1.1 / R2 / R5.1.
     */
    addShape(type: AutoShapeType, row: number, column: number, width: number, height: number, text?: string, name?: string, altText?: string, rotation?: number, moveWithCell?: boolean, sizeWithCell?: boolean): Shape;
    /**
     * Remove an autoshape by handle or 0-based index.
     *
     * Citations: docs/specs/autoshapes.md; API-RULES R1.1.
     */
    removeShape(target: Shape | number): void;
    /** Add a floating picture above the worksheet grid. */
    addImage(bytes: Uint8Array, row: number, column: number, width: number, height: number): Image;
    /** Remove a floating picture by handle or zero-based index. */
    removeImage(target: Image | number): void;
    /**
     * Add a chart on this worksheet. Accepts any {@link ChartType} with
     * positional geometry and a data argument. Drawing and chart package parts
     * are written on save/flush.
     *
     * Citations: docs/specs/charts.md; API-RULES R1.1 / R2 / R5.1.
     */
    addChart(type: ChartType, row: number, column: number, width: number, height: number, data: string | ReadonlyArray<string> | ChartData, values?: string): Chart;
    /**
     * Remove a chart by handle or 0-based index.
     *
     * Citations: docs/specs/charts.md; API-RULES R1.1.
     */
    removeChart(target: Chart | number): void;
    /**
     * Check boxes on this worksheet (VML form controls). Snapshot.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.5 / R5.1.
     */
    readonly checkBoxes: ReadonlyArray<CheckBox>;
    /**
     * Combo boxes on this worksheet (VML form controls). Snapshot.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.5 / R5.1.
     */
    readonly comboBoxes: ReadonlyArray<ComboBox>;
    /**
     * Option buttons on this worksheet (VML form controls). Snapshot.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.5 / R5.1.
     */
    readonly optionButtons: ReadonlyArray<OptionButton>;
    /**
     * Add a check box. VML package side effects defer to save/flush.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1 / R2 / R5.1.
     */
    addCheckBox(row: number, column: number, width: number, height: number, name?: string, text?: string, checkState?: CheckState, linkedCell?: string, isDisplay3DShading?: boolean): CheckBox;
    /**
     * Add a combo box (`DropStyle` combo). VML package side effects defer to save/flush.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1 / R2 / R5.1.
     */
    addComboBox(row: number, column: number, width: number, height: number, name?: string, listFillRange?: string, linkedCell?: string, selectedIndex?: number, dropDownLines?: number, dropStyle?: ComboDropStyle, isDisplay3DShading?: boolean): ComboBox;
    /**
     * Add an editable combo box (`DropStyle` comboedit).
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1 / R2 / R5.1.
     */
    addComboEditBox(row: number, column: number, width: number, height: number, name?: string, listFillRange?: string, linkedCell?: string, selectedIndex?: number, dropDownLines?: number, isDisplay3DShading?: boolean): ComboBox;
    /**
     * Add a simple drop-down (`DropStyle` simple).
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1 / R2 / R5.1.
     */
    addComboDropdown(row: number, column: number, width: number, height: number, name?: string, listFillRange?: string, linkedCell?: string, selectedIndex?: number, dropDownLines?: number, isDisplay3DShading?: boolean): ComboBox;
    /**
     * Add an option button (radio). VML package side effects defer to save/flush.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1 / R2 / R5.1.
     */
    addOptionButton(row: number, column: number, width: number, height: number, name?: string, text?: string, checkState?: CheckState, linkedCell?: string, isDisplay3DShading?: boolean, isFirstButton?: boolean): OptionButton;
    /**
     * Remove a check box by handle or 0-based index.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1.
     */
    removeCheckBox(target: CheckBox | number): void;
    /**
     * Remove a combo box by handle or 0-based index.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1.
     */
    removeComboBox(target: ComboBox | number): void;
    /**
     * Remove an option button by handle or 0-based index.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1.
     */
    removeOptionButton(target: OptionButton | number): void;
    /**
     * Buttons on this worksheet (VML form controls). Snapshot.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.5 / R5.1.
     */
    readonly buttons: ReadonlyArray<FormButton>;
    /**
     * List boxes on this worksheet (VML form controls). Snapshot.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.5 / R5.1.
     */
    readonly listBoxes: ReadonlyArray<ListBox>;
    /**
     * Group boxes on this worksheet (VML form controls). Snapshot.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.5 / R5.1.
     */
    readonly groupBoxes: ReadonlyArray<GroupBox>;
    /**
     * Form labels on this worksheet (VML form controls). Snapshot.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.5 / R5.1.
     */
    readonly formLabels: ReadonlyArray<FormLabel>;
    /**
     * Scroll bars on this worksheet (VML form controls). Snapshot.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.5 / R5.1.
     */
    readonly scrollBars: ReadonlyArray<ScrollBar>;
    /**
     * Spin buttons on this worksheet (VML form controls). Snapshot.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.5 / R5.1.
     */
    readonly spinButtons: ReadonlyArray<SpinButton>;
    /**
     * Edit boxes on this worksheet (VML form controls). Snapshot.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.5 / R5.1.
     */
    readonly editBoxes: ReadonlyArray<EditBox>;
    /**
     * Add a button. VML package side effects defer to save/flush.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1 / R2 / R5.1.
     */
    addButton(row: number, column: number, width: number, height: number, name?: string, text?: string, onAction?: string): FormButton;
    /**
     * Add a list box. VML package side effects defer to save/flush.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1 / R2 / R5.1.
     */
    addListBox(row: number, column: number, width: number, height: number, name?: string, listFillRange?: string, linkedCell?: string, selectedIndex?: number, selectionType?: 'single' | 'multi' | 'extended', selectedIndices?: ReadonlyArray<number>, isDisplay3DShading?: boolean, value?: number): ListBox;
    /**
     * Add a group box. VML package side effects defer to save/flush.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1 / R2 / R5.1.
     */
    addGroupBox(row: number, column: number, width: number, height: number, name?: string, text?: string, groupLinkedCell?: string): GroupBox;
    /**
     * Add a form label. VML package side effects defer to save/flush.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1 / R2 / R5.1.
     */
    addFormLabel(row: number, column: number, width: number, height: number, name?: string, text?: string, textLink?: string): FormLabel;
    /**
     * Add a scroll bar. VML package side effects defer to save/flush.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1 / R2 / R5.1.
     */
    addScrollBar(row: number, column: number, width: number, height: number, name?: string, linkedCell?: string, value?: number, min?: number, max?: number, incrementalChange?: number, pageChange?: number, isHorizontal?: boolean): ScrollBar;
    /**
     * Add a spin button. VML package side effects defer to save/flush.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1 / R2 / R5.1.
     */
    addSpinButton(row: number, column: number, width: number, height: number, name?: string, linkedCell?: string, value?: number, min?: number, max?: number, incrementalChange?: number): SpinButton;
    /**
     * Add an edit box. VML package side effects defer to save/flush.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1 / R2 / R5.1.
     */
    addEditBox(row: number, column: number, width: number, height: number, name?: string, text?: string, textLink?: string, isMultiLine?: boolean, validation?: EditValidation, isPassword?: boolean): EditBox;
    /**
     * Remove a button by handle or 0-based index.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1.
     */
    removeButton(target: FormButton | number): void;
    /**
     * Remove a list box by handle or 0-based index.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1.
     */
    removeListBox(target: ListBox | number): void;
    /**
     * Remove a group box by handle or 0-based index.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1.
     */
    removeGroupBox(target: GroupBox | number): void;
    /**
     * Remove a form label by handle or 0-based index.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1.
     */
    removeFormLabel(target: FormLabel | number): void;
    /**
     * Remove a scroll bar by handle or 0-based index.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1.
     */
    removeScrollBar(target: ScrollBar | number): void;
    /**
     * Remove a spin button by handle or 0-based index.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1.
     */
    removeSpinButton(target: SpinButton | number): void;
    /**
     * Remove an edit box by handle or 0-based index.
     *
     * Citations: docs/specs/form-controls.md; API-RULES R1.1.
     */
    removeEditBox(target: EditBox | number): void;
    /**
     * Discussion threads on this sheet, in document order.
     */
    readonly threadedComments: ReadonlyArray<ThreadedComment>;
    /**
     * `true` when this worksheet is protected.
     */
    readonly isProtected: boolean;
    /**
     * Current sheet protection settings, or `undefined` when the sheet is not protected.
     */
    readonly sheetProtection: SheetProtectionInfo | undefined;
    /**
     * Protect this worksheet so users can only do what you allow.
     *
     * @param password - Optional password required to unprotect later.
     * @param options - Which actions remain allowed (select cells, format, sort, …).
     */
    protect(password?: string, options?: SheetProtectionOptions): void;
    /**
     * Remove worksheet protection.
     *
     * @param password - Required when the sheet was protected with a password.
     */
    unprotect(password?: string): void;
    /**
     * Ranges users may still edit while the rest of the sheet is protected.
     */
    readonly protectedRanges: ProtectedRanges;
    /**
     * Classic sticky notes on this sheet.
     */
    readonly comments: Comments;
    /**
     * Add a classic sticky note on a cell.
     */
    addComment(options: AddCommentOptions): Comment;
    /**
     * Remove a classic sticky note by handle, A1 address, or zero-based index.
     */
    removeComment(target: Comment | string | number): void;
    /**
     * `true` when the given cell has a classic sticky note.
     */
    hasComment(a: string | number, b?: number): boolean;
    /**
     * Classic sticky note on the given cell, or `undefined` if none.
     */
    getComment(a: string | number, b?: number): Comment | undefined;
    /**
     * Mutable hyperlinks store for cell property wiring.
     * @private
     */
    readonly hyperlinksImpl: HyperlinksImpl;
    /**
     * Mutable threaded-comments store for cell property wiring.
     * @private
     */
    readonly threadedCommentsImpl: ThreadedCommentsImpl;
    /**
     * Mutable classic-comments store for cell property wiring.
     * @private
     */
    readonly commentsImpl: CommentsImpl;
    /**
     * Remove one discussion thread and all of its replies.
     *
     * @param target - The thread to remove, or its zero-based index on the sheet.
     */
    removeThreadedComment(target: ThreadedComment | number): void;
    /**
     * Remove every discussion thread (and reply) on this sheet.
     */
    clearThreadedComments(): void;
    /**
     * Tables collection. Resolves table parts lazily on first access.
     */
    readonly tables: Tables;
    /** Host adapter between the public tables collection and the wire plumbing. */
    private createTablesHost;
    /**
     * Bounding box of residual sparse cells, or `undefined` when none.
     *
     * Same cells that write `dimension@ref` (`computeDimensionRef`). Column
     * widths, row heights, and the stored dimension hint do not extend it.
     * Reading never allocates cells.
     *
     * Assumption: `lastRow` / `lastColumn` are 1-based numbers, not a `Row`
     * handle — this library has no public `Row` type (API-RULES R3.1 names
     * `Row | undefined`; user also asked for `lastColumn`).
     *
     * Citations: docs/specs/worksheet-cells.md; ECMA-376-1 `CT_SheetDimension`;
     * API-RULES R3.1.
     */
    readonly usedRange: Range | undefined;
    /**
     * 1-based last row of {@link usedRange}, or `undefined` when empty.
     */
    readonly lastRow: number | undefined;
    /**
     * 1-based last column of {@link usedRange}, or `undefined` when empty.
     */
    readonly lastColumn: number | undefined;
    /**
     * Excel highlight of the primary sheet view (`selection@sqref` on the
     * topLeft pane). Not {@link usedRange}.
     *
     * Citations: docs/specs/worksheet-view.md; ECMA-376-1 §18.3.1.78
     * `selection`; transitional sml.xsd `CT_Selection`; `[MS-OI29500]`
     * §2.1.649; API-RULES R1.4.
     *
     * Assumption: one public range — the active area of the topLeft pane.
     * Other pane selections and multi-area `sqref` lists stay in the file
     * and are not rewritten by a read.
     */
    selectedRange: Range | undefined;
    /**
     * Normal scroll viewport (`sheetView@topLeftCell`). Not the freeze pane
     * anchor and not {@link selectedRange}.
     *
     * Citations: ECMA-376-1 §18.3.1.87; transitional sml.xsd `CT_SheetView`
     * `@topLeftCell` (`ST_CellRef`, optional, no default); API-RULES R1.4.
     */
    topLeftCell: string | undefined;
    /**
     * Active pane scroll anchor (`pane@topLeftCell`) for frozen, split, and
     * frozenSplit panes. Does not invent a pane.
     *
     * Citations: ECMA-376-1 §18.3.1.66; transitional sml.xsd `CT_Pane`
     * `@topLeftCell`; `[MS-OI29500]` §2.1.640 (optional when `state` is
     * `split`, required otherwise — clearing a frozen pane's anchor is a
     * deliberate caller choice, not repaired on save).
     */
    paneTopLeftCell: string | undefined;
    /**
     * Address-based cell accessor (A1 or 0-based row/col overload).
     *
     * Sole public cell accessor (API-RULES R1.5).
     *
     * Citations: docs/specs/cell-storage.md; API-RULES R1.4 / R1.5.
     */
    cell(addressOrRow: string | number, column?: number): Cell;
    /**
     * Range view over an A1 ref (`A1` or `A1:B2`).
     */
    range(ref: string): Range;
    /**
     * Cell handle at an A1 address.
     * @deprecated Compatibility alias for {@link cell} (canonical L1
     * accessor per API-RULES R1.5); kept for existing consumers.
     */
    getCell(address: string): Cell;
    /** @private */
    setNameInternal(name: string): void;
    /** @private */
    setVisibilityInternal(visibility: SheetVisibility): void;
    /** @private */
    toXmlEntry(): SheetXmlEntry;
    /** @private */
    ensureSheetDataLoaded(): void;
    /** @private */
    getCellModel(row: number, col: number): CellModel | undefined;
    /** @private */
    putCellModel(model: CellModel): void;
    /** @private */
    deleteCellModel(row: number, col: number): void;
    /** @private */
    markCellsDirty(): void;
    /** @private */
    resolveSharedString(index: number): string;
    /** @private */
    appendSharedString(text: string): number;
    /**
     * Append rich shared-string runs (always new index; never plain-dedup).
     * @private
     */
    appendRichSharedString(runs: ReadonlyArray<RichTextRun>): number;
    /**
     * Structured runs for an SST index (plain → single run).
     * @private
     */
    getRichSharedStringRuns(index: number): RichTextRun[];
    /**
     * Entry kind at SST index (`plain` | `rich`).
     * @private
     */
    sharedStringEntryKind(index: number): 'plain' | 'rich';
    /** @private */
    addSharedStringReferences(delta: number): void;
    /**
     * Workbook styles table for cell styleIndex / applyStyle.
     * @private
     */
    styles(): WorkbookStyles;
    /**
     * Workbook 1904 date-system flag for cell date serial conversion.
     * @private
     */
    date1904(): boolean;
    /**
     * Resolve `tableParts` refs to table parts and parse them (lazy, once).
     * Soft-skips a table whose part is missing or unparseable; the part itself
     * and its worksheet relationship are left untouched in the package so an
     * unmodified workbook round-trips unchanged.
     * @private
     */
    private ensureTablesResolved;
    /**
     * Internal table model access (TASK-1211 wraps this with the public API).
     * Resolves lazily; returned array is the live internal store.
     * @private
     */
    internalTables(): {
        relId: string;
        entry: TableEntry;
    }[];
    /**
     * `tableParts` model for the parse path (TASK-1211 mutates through
     * `internalTables` + this).
     * @private
     */
    internalTablePartsModel(): TablePartsModel;
    /**
     * Allocate the next workbook-unique table id (host-owned max + 1).
     * Existing ids are never renumbered.
     * @private
     */
    allocateTableId(): number;
    /**
     * Allocate a fresh worksheet relationship id for a new table part.
     * Unique within this worksheet's relationships part, counting both
     * persisted relationships and pending entries not yet flushed.
     * @private
     */
    allocateTableRelId(): string;
    /**
     * Write tables back to the package: table parts (`/xl/tables/tableN.xml`)
     * with content-type Override + worksheet relationship, and `tableParts`
     * refs on the sheet part. Removal of the part/Override/relationship for
     * dropped tables happens through `internalSetTables` bookkeeping.
     * @private
     */
    flushTablesIfDirty(): void;
    /**
     * Replace the full table set (TASK-1211 public API calls this).
     * Records dropped parts/rels so flush removes them from the package, and
     * marks the sheet part dirty (the `tableParts` element lives on it).
     * @private
     */
    internalSetTables(entries: ReadonlyArray<{
        relId: string;
        entry: TableEntry;
    }>, removedRelIds: ReadonlyArray<string>, removedPartNames: ReadonlyArray<string>): void;
    /** Track tables mutation for flush. */
    private tablesDirty;
    private readonly droppedTableRelIds;
    private readonly droppedTableParts;
    /**
     * True when table entries changed since last flush.
     * @private
     */
    readonly hasDirtyTables: boolean;
    /**
     * Write sheetData, merges, conditional formatting, data validations, hyperlinks,
     * freeze panes, page setup, and tables + table parts back to the package when dirty.
     * @private
     */
    flushIfDirty(): void;
    /**
     * Inclusive corners of residual cells, or `undefined` when the sheet has
     * none. Walks the sparse map only — never allocates, never reads
     * `dimension@ref`.
     */
    private usedCellBounds;
    /**
     * `tableParts` model snapshot for the sheet write, consistent with the
     * lazily resolved entries (flush tables first when they changed).
     */
    private ensureTablePartsForFlush;
    /**
     * Snapshot whether any cell/merge/CF/data-validation/hyperlink/freeze/page-setup
     * /text-box mutation is pending.
     * @private
     */
    readonly hasDirtyCells: boolean;
    private putCellModelInternal;
    private collectCells;
    private requireCellHost;
}