@shbernal/ts-xlsx 1.0.0

package/dist/core/worksheet.d.ts

@@ -0,0 +1,647 @@
+import { type AutoFilter } from './autofilter.ts';
+import { Cell } from './cell.ts';
+import { Column } from './column.ts';
+import { type CommentThread } from './comment-thread.ts';
+import type { ConditionalFormatting } from './conditional-formatting.ts';
+import type { DataValidation, DataValidationEntry } from './data-validation.ts';
+import { type AnchoredImage, type AnchorPoint, type ImageAnchor, type ImageEditAs } from './image.ts';
+import { INTERNAL } from './internal.ts';
+import type { HeaderFooter, PageBreak, PageMargins, PageSetup, PrintOptions } from './page-setup.ts';
+import { type ParsedPivotTable, PivotTable, type PivotTableOptions } from './pivot-table.ts';
+import type { PreservedWorksheetReference } from './preserved.ts';
+import { type SheetProtection, type SheetProtectionOptions } from './protection.ts';
+import { Range } from './range.ts';
+import { Row } from './row.ts';
+import type { CellStyle, Color, Fill } from './style.ts';
+import { Table, type TableOptions } from './table.ts';
+import type { CellValue } from './value.ts';
+export interface WorksheetState {
+    /** Sheet visibility, as Excel models it. Defaults to `visible`. */
+    readonly state: 'visible' | 'hidden' | 'veryHidden';
+}
+/** Format defaults applied to every row/column that carries no explicit override. */
+export interface WorksheetProperties {
+    /** Height, in points, for rows with no explicit height. */
+    defaultRowHeight?: number;
+    /** Width, in character units, for columns with no explicit width. */
+    defaultColWidth?: number;
+}
+/**
+ * Placement of an outline's summary rows/columns. Excel's defaults are summary *below* the detail
+ * rows and *right* of the detail columns; setting either to `false` inverts that placement so an
+ * author who groups upward gets a file that honours it. An unset flag is omitted from the written
+ * `<outlinePr>`, and an empty object emits no `<outlinePr>` at all.
+ */
+export interface OutlineProperties {
+    summaryBelow?: boolean;
+    summaryRight?: boolean;
+}
+/**
+ * A worksheet's frozen-pane view. `state` `'frozen'` locks the top `ySplit` rows and left `xSplit`
+ * columns in place while the rest scrolls; `'normal'` (the default) has no split and emits no
+ * `<pane>` — writing a normal view leaves no leftover pane markup that would trip Excel's repair
+ * prompt. An empty object is a normal view.
+ */
+export interface SheetView {
+    /** Freeze state. Absent or `'normal'` means no split. */
+    state?: 'normal' | 'frozen';
+    /** Number of columns frozen at the left; `0`/absent freezes no columns. */
+    xSplit?: number;
+    /** Number of rows frozen at the top; `0`/absent freezes no rows. */
+    ySplit?: number;
+    /** The cell anchoring the bottom-right scrolling pane; defaults to the first unfrozen cell. */
+    topLeftCell?: string;
+}
+/**
+ * Per-column formatting. A column may exist purely to carry these, with no cells. The style
+ * facets are *defaults* for the column's cells: a cell that sets a facet of its own wins, but
+ * one that leaves a facet unset inherits the column's — the same precedence Excel applies, and
+ * symmetric with how a {@link RowProperties} fill defaults a row's cells.
+ */
+export interface ColumnProperties extends CellStyle {
+    /** Stable key naming the column so a keyed-object row (see {@link Worksheet.addRow}) can place a
+     * value under it by name rather than position. In-memory only — it is not serialized to OOXML. */
+    key?: string;
+    /** Column width in character units. */
+    width?: number;
+    /** Whether the column is hidden. */
+    hidden?: boolean;
+    /** Outline (grouping) depth; 0 or absent means ungrouped. */
+    outlineLevel?: number;
+    /** Whether this column is the collapsed summary of an outline group. */
+    collapsed?: boolean;
+}
+/** A row handed to {@link Worksheet.addRow}: a positional array of cell values (a hole or `undefined`
+ * leaves that column untouched), or an object keyed by column {@link ColumnProperties.key} whose
+ * values land under the matching columns. */
+export type RowInput = (CellValue | undefined)[] | Record<string, CellValue>;
+/** Per-row formatting. A row may exist purely to carry these, with no cells. */
+export interface RowProperties {
+    /** Row height in points. */
+    height?: number;
+    /** Whether the row is hidden. */
+    hidden?: boolean;
+    /** Outline (grouping) depth; 0 or absent means ungrouped. */
+    outlineLevel?: number;
+    /** Whether this row is the collapsed summary of an outline group. */
+    collapsed?: boolean;
+    /** Background fill applied to the row's cells that carry no fill of their own. */
+    fill?: Fill;
+}
+/** One materialised cell in a {@link WorksheetModel}: its position, value, and per-cell style facets. */
+export interface CellModel extends CellStyle {
+    readonly row: number;
+    readonly col: number;
+    value: CellValue;
+    note?: string | undefined;
+}
+/**
+ * A serialisable snapshot of a worksheet's value and overlay content — its cells and their styles,
+ * the column/row/page metadata, and the sheet-level overlays (merges, data validations, conditional
+ * formattings, tables, the autofilter, protection). {@link Worksheet.model} exports one; assigning
+ * it back reproduces that content. The getter and setter cover exactly the same fields, so a
+ * `dst.model = src.model` round-trip drops none of it — an export field the import ignored would
+ * silently lose data, the historical merge-loss failure this contract exists to prevent. Both
+ * directions are driven from one field table (`core/worksheet-model.ts`), which the compiler proves
+ * covers every field below, so adding a field here without wiring it fails the build.
+ *
+ * Out of scope by design: content that carries workbook-level identity rather than pure sheet
+ * state — anchored and background images (their bytes live on the {@link Workbook}), pivot tables
+ * (their source references a live worksheet), and byte-preserved parts (charts, vector drawings,
+ * slicers) kept verbatim for round-tripping. These stay with their source sheet; a model assignment
+ * neither copies nor clears them.
+ */
+export interface WorksheetModel {
+    state: WorksheetState['state'];
+    tabColor: Color | undefined;
+    properties: WorksheetProperties;
+    outline: OutlineProperties;
+    pageSetup: PageSetup;
+    printOptions: PrintOptions;
+    pageMargins: PageMargins;
+    headerFooter: HeaderFooter;
+    rowBreaks: PageBreak[];
+    columnBreaks: PageBreak[];
+    columns: {
+        index: number;
+        properties: ColumnProperties;
+    }[];
+    rows: {
+        number: number;
+        properties: RowProperties;
+    }[];
+    cells: CellModel[];
+    merges: string[];
+    dataValidations: DataValidationEntry[];
+    conditionalFormattings: ConditionalFormatting[];
+    tables: TableOptions[];
+    autoFilter: AutoFilter | undefined;
+    protection: SheetProtection | undefined;
+}
+export declare class Worksheet {
+    #private;
+    readonly name: string;
+    /** 1-based workbook-assigned id, stable for the sheet's lifetime. */
+    readonly id: number;
+    state: WorksheetState['state'];
+    /**
+     * Colour of the sheet's tab, as an ARGB/theme {@link Color}. `undefined` leaves the tab its
+     * default colour; the writer emits no `<tabColor>` for an uncoloured sheet, so a round-trip
+     * never fabricates one.
+     */
+    tabColor: Color | undefined;
+    /** Sheet-level format defaults. Mutate in place: `sheet.properties.defaultRowHeight = 20`. */
+    readonly properties: WorksheetProperties;
+    /**
+     * Outline summary-position flags. Mutate in place: `sheet.outline.summaryBelow = false`. Empty
+     * means unset — the writer emits no `<outlinePr>` and a round-trip never fabricates one.
+     */
+    readonly outline: OutlineProperties;
+    /**
+     * The sheet's frozen-pane view. Empty (a normal view) emits no `<pane>`. Use {@link freeze} and
+     * {@link unfreeze} for the common cases, or mutate in place for finer control.
+     */
+    readonly view: SheetView;
+    /**
+     * Print-scaling and orientation. Mutate in place: `sheet.pageSetup.fitToPage = true`. Empty means
+     * unset — the writer emits neither `<pageSetUpPr>` nor `<pageSetup>` and a round-trip never
+     * fabricates them.
+     */
+    readonly pageSetup: PageSetup;
+    /**
+     * Print-toggle flags (`<printOptions>`): centring, and whether headings/gridlines print. Mutate in
+     * place: `sheet.printOptions.gridLines = true`. Empty means unset — the writer emits no element and
+     * a round-trip never fabricates one.
+     */
+    readonly printOptions: PrintOptions;
+    /** Print margins. Mutate in place: `sheet.pageMargins.left = 0.5`. Empty means unset. */
+    readonly pageMargins: PageMargins;
+    /** Page header/footer text. Mutate in place: `sheet.headerFooter.oddHeader = '&C&"..."'`. */
+    readonly headerFooter: HeaderFooter;
+    /**
+     * Manual horizontal page breaks (`<rowBreaks>`): each break's `id` is a row the print layout splits
+     * before. Mutate in place: `sheet.rowBreaks.push({id: 3})`. Empty means no manual row breaks and the
+     * writer emits no `<rowBreaks>` element.
+     */
+    readonly rowBreaks: PageBreak[];
+    /**
+     * Manual vertical page breaks (`<colBreaks>`): each break's `id` is a column the print layout splits
+     * before. Mutate in place: `sheet.columnBreaks.push({id: 3})`. Empty means no manual column breaks and
+     * the writer emits no `<colBreaks>` element.
+     */
+    readonly columnBreaks: PageBreak[];
+    constructor(name: string, id: number, state?: WorksheetState['state']);
+    /**
+     * Get the cell at an A1 reference, creating it on first access. The reference must
+     * name both a column and a row (`"B3"`); a whole-row or whole-column reference is
+     * not a cell and is rejected.
+     *
+     * Addressing a cell covered by a merged region resolves to that region's master
+     * (top-left) cell, mirroring how a spreadsheet treats the merge as one cell: a value
+     * or style written through a covered address lands on the master, and reading a
+     * covered address returns the master's. Only the master ever holds an independent
+     * value, so the serialized sheet stays well-formed (no stray value on a covered cell).
+     *
+     * @throws {SyntaxError} if the reference does not resolve to a single cell.
+     */
+    getCell(reference: string): Cell;
+    /** Whether a cell has been materialised at the given 1-based position. */
+    hasCell(row: number, col: number): boolean;
+    /**
+     * A handle on a 1-based column: its formatting, its cells, and its values. Cheap and stateless —
+     * it creates neither cells nor a format record, so asking about a column costs nothing and does
+     * not extend the used range. Writing through it (`getColumn(2).width = 12`) is what materialises
+     * the record.
+     *
+     * @throws {RangeError} if the index is not a positive integer.
+     */
+    getColumn(index: number): Column;
+    /**
+     * A handle on a 1-based row: its formatting, its cells, and its values. Cheap and stateless — it
+     * creates neither cells nor a format record, so asking about a row costs nothing and does not
+     * extend the used range. Writing through it (`getRow(3).height = 20`) is what materialises the
+     * record.
+     *
+     * @throws {RangeError} if the number is not a positive integer.
+     */
+    getRow(number: number): Row;
+    /**
+     * A handle on a rectangular block of cells — `getRange('B2:D5')`, or the same block by its
+     * inclusive corners as `getRange(2, 2, 5, 4)`. Cheap and stateless like {@link getRow} and
+     * {@link getColumn}: it creates no cells and does not extend the used range.
+     *
+     * Corners are stated **first and last, inclusive**, in either order, never as a start and a count.
+     * That is the convention for every range-shaped accessor here, so the three axes cannot disagree
+     * about what a pair of numbers means.
+     *
+     * A whole-row (`'1:1'`) or whole-column (`'A:A'`) reference is refused rather than accepted as a
+     * million-cell block: OOXML states a whole-axis default in one attribute, and {@link getRow} /
+     * {@link getColumn} are how you write it.
+     *
+     * @throws {SyntaxError} if the reference is unparseable, names another worksheet, or leaves an
+     *   axis unbounded.
+     * @throws {RangeError} if a numeric corner is not a positive integer within the sheet's bounds.
+     */
+    getRange(reference: string): Range;
+    getRange(top: number, left: number, bottom: number, right: number): Range;
+    /**
+     * The 1-based index of the last row carrying anything — data or its own formatting —
+     * or 0 for an empty sheet. Spans gaps: a value in row 5 makes this 5 even if rows 2–4
+     * are empty. This is the used-range extent, not a populated-row tally (see
+     * {@link actualRowCount}).
+     */
+    get rowCount(): number;
+    /** The number of rows that hold at least one non-empty cell, ignoring gaps and formatting-only rows. */
+    get actualRowCount(): number;
+    /**
+     * The 1-based index of the last column carrying anything — a non-empty cell or its own format
+     * properties — or 0 for an empty sheet. The used-range width, mirroring {@link rowCount} for the
+     * other axis: a value in column E makes this 5 even if columns B–D are empty.
+     */
+    get columnCount(): number;
+    /** The columns carrying format properties, as handles, in ascending index order. */
+    columns(): IterableIterator<Column>;
+    /**
+     * The rows to serialise, as handles, in ascending row order: the union of rows holding cells and
+     * rows holding only metadata (a hidden or grouped row need carry no data). Mirrors how OOXML
+     * serialises (`<row>` wrapping `<c>`) and is the writer's row surface.
+     *
+     * A handle yields its cells only when asked, so a pass that reads nothing but row attributes
+     * never assembles a cell array it will not look at.
+     */
+    rows(): IterableIterator<Row>;
+    /**
+     * Define a table over a range of this sheet. The table's shape invariants (a legal
+     * name, at least one column, at least one row) are enforced here; conflicts with the
+     * rest of the sheet (e.g. an overlapping merge) are the writer's concern.
+     *
+     * @throws {@link AuthoringError} if the name, columns, or geometry are invalid.
+     */
+    addTable(options: TableOptions): Table;
+    /** The tables defined on this sheet, in definition order. */
+    get tables(): readonly Table[];
+    /** The table with the given name (case-sensitive, the identifier Excel uses), or `undefined`.
+     * A table read back from a file is fully hydrated — its rows can be read and appended to. */
+    getTable(name: string): Table | undefined;
+    /**
+     * Add a pivot table to this (destination) sheet, summarising a source sheet's data. The source is
+     * read once, now, so the pivot is a snapshot: later edits to the source do not change it. The
+     * supported shape (one summed value field, at least one row and column field) is enforced here.
+     *
+     * @throws {@link AuthoringError} if the metric, fields, or source shape are unsupported.
+     */
+    addPivotTable(options: PivotTableOptions): PivotTable;
+    /** The pivot tables hosted on this sheet, in definition order. */
+    get pivotTables(): readonly PivotTable[];
+    /**
+     * Pivot tables reconstructed from a loaded package, in the order the reader found them — a
+     * read-only inspection view (source range, field roles, value field, aggregation). A pivot
+     * authored on this sheet via {@link addPivotTable} does not appear here; a pivot loaded from a
+     * file does not appear in {@link pivotTables}. The loaded pivots re-emit verbatim through
+     * byte-preservation, so this collection is never itself serialised.
+     */
+    get loadedPivotTables(): readonly ParsedPivotTable[];
+    /**
+     * Anchor a threaded conversation to a cell — Excel's modern review comment: an opening message, its
+     * replies, and whether the discussion was marked resolved. Distinct from a cell's legacy note
+     * ({@link Cell.note}), and mutually exclusive with one: Excel refuses to put both on one cell, and a
+     * cell carrying both is written back as the conversation alone.
+     *
+     * Every message supplies its own {@link Comment.id} and {@link Comment.date}, and names its author by
+     * {@link Comment.personId} into the workbook registry ({@link Workbook.addPerson}) — the writer has no
+     * clock and no id generator, so nothing here is invented and the same workbook always serialises to the
+     * same bytes. Every id is normalised to the brace-wrapped upper-case GUID form the format requires, so a
+     * `crypto.randomUUID()` is accepted as-is.
+     *
+     * Message ids must be unique **within this sheet**, because that is the scope in which they mean
+     * anything: a reply names its thread by the head's id inside the sheet's own part, and the legacy
+     * fallback comment binds its cell by the same id inside the sheet's own comments part. Two sheets reusing
+     * one id is therefore harmless and is not rejected — Excel's ids happen to be globally unique, but
+     * nothing resolves across a part boundary.
+     *
+     * @throws {SyntaxError} if the anchor does not resolve to a single cell, if any id is not a GUID, if a
+     * message id is already used on this sheet, or if a mention's span is not a whole number the wire can
+     * express.
+     */
+    addCommentThread(thread: CommentThread): void;
+    /**
+     * The threaded conversations on this sheet — Excel's modern review comments (author, timestamp,
+     * replies, resolved state, `@mentions`). Empty for a sheet with none. Distinct from a cell's legacy note
+     * ({@link Cell.note}).
+     */
+    get commentThreads(): readonly CommentThread[];
+    /**
+     * The conversation anchored to a cell, or `undefined` when that cell carries none. The reference is
+     * canonicalized, so an absolute `"$B$2"` finds the same thread as `"B2"`; it names the *anchor* cell,
+     * so a cell merely covered by the anchor's merged region is not a match.
+     *
+     * @throws {SyntaxError} if the reference does not resolve to a single cell.
+     */
+    commentThreadAt(reference: string): CommentThread | undefined;
+    /**
+     * Anchor a workbook image (the id returned by {@link Workbook.addImage}) to this sheet. Two shapes:
+     *
+     * - **Two-cell**: `{tl, br}` spans the rectangle from the top-left grid point to the bottom-right,
+     *   reflowing as the spanned cells resize. `editAs` (`oneCell` by default) tunes how it follows.
+     * - **One-cell**: `{tl, ext}` pins the image at `tl` at a fixed pixel size that the grid never
+     *   resizes. `ext` is in pixels and converts to EMUs internally.
+     *
+     * Grid points are 0-based (`{col: 0, row: 0}` is cell A1). A later row/column splice re-pins the
+     * anchor to the same logical position.
+     */
+    addImage(imageId: number, anchor: {
+        readonly tl: AnchorPoint;
+        readonly br: AnchorPoint;
+        readonly editAs?: ImageEditAs;
+    }): void;
+    addImage(imageId: number, anchor: {
+        readonly tl: AnchorPoint;
+        readonly ext: {
+            readonly width: number;
+            readonly height: number;
+        };
+    }): void;
+    /**
+     * Anchor an image with a pre-built model anchor in the model's own units (EMUs). This is the
+     * low-level primitive {@link addImage} builds on and the reader uses to re-pin an image parsed from
+     * a drawing part without a lossy pixel round-trip.
+     */
+    addImageAnchor(imageId: number, anchor: ImageAnchor): void;
+    /** Drop every anchor of the given workbook image from this sheet. The image stays registered on the
+     * workbook — another sheet may still show it — so only this sheet's anchors are removed; the writer
+     * then omits any media no sheet anchors any longer. */
+    removeImage(imageId: number): void;
+    /** The images anchored to this sheet, in the order they were added. */
+    get images(): readonly AnchoredImage[];
+    /** Set this sheet's background image to a workbook image (the id {@link Workbook.addImage} returned).
+     * The picture tiles behind the whole grid; it is not anchored to any cell. Passing a new id replaces
+     * the previous background. */
+    addBackgroundImage(imageId: number): void;
+    /** Remove this sheet's background image, if any. The image stays registered on the workbook. */
+    removeBackgroundImage(): void;
+    /** The workbook image id set as this sheet's background, or `undefined` when it has none. */
+    get backgroundImageId(): number | undefined;
+    /** The worksheet-level references to unmodeled package content preserved for round-tripping. */
+    get preservedReferences(): readonly PreservedWorksheetReference[];
+    /**
+     * Merge a range of cells (`"A1:B2"`). A range that overlaps an already-merged region is
+     * rejected — Excel forbids overlapping merges and writes such geometry as a corrupt file.
+     * Whole-row/column ranges (`"A:A"`) are unbounded, carry no rectangle, and are not overlap-checked.
+     *
+     * Any value already sitting in a covered non-anchor cell is discarded, keeping only the top-left
+     * anchor's — exactly how Excel collapses a range on merge. Leaving it would emit a populated `<c>`
+     * under the `<mergeCell>` ref, the geometry Excel opens with a repair prompt. Covered-cell styles
+     * survive (a border spanning the merge is legal), so only the conflicting value is cleared.
+     */
+    mergeCells(range: string): void;
+    /** The merged ranges on this sheet, in the order they were added. */
+    get merges(): readonly string[];
+    /**
+     * The sheet's autofilter — its range plus any per-column criteria — or `undefined` when the sheet
+     * carries none. Setting one turns on the header-row filter dropdowns Excel draws over the range;
+     * the writer emits both the sheet's `<autoFilter>` element and the hidden `_FilterDatabase` defined
+     * name Excel derives from it. Setting `undefined` clears the filter.
+     *
+     * A bare range string is the ergonomic common case — `sheet.autoFilter = 'A1:C10'` for dropdowns
+     * with no active criteria; pass an {@link AutoFilter} object to narrow columns. Either way the
+     * value is normalised on assignment (range to canonical `A1:C10` form) and the getter returns the
+     * structured object. The range must be a bounded rectangle — a whole-row/column reference is not a
+     * filterable region and is rejected.
+     */
+    get autoFilter(): AutoFilter | undefined;
+    set autoFilter(filter: string | AutoFilter | undefined);
+    /**
+     * Remove a merged range previously added with {@link mergeCells}, returning whether a merge with
+     * that exact range string existed. The covering rectangle is dropped alongside it, so a cell the
+     * merge had masked addresses independently again. The inverse of {@link mergeCells}.
+     */
+    unmergeCells(range: string): boolean;
+    /**
+     * Attach a data validation to a target range (`"B2:B20"`, a whole column `"B2:B1048576"`, or a
+     * space-separated `sqref` of several ranges). The rule is stored once against the range, not copied
+     * per covered cell, so a whole-column dropdown stays a single entry. A cell inside the range reports
+     * the rule through {@link dataValidationAt}.
+     *
+     * Pass `{extended: true}` to mark a rule that belongs in the 2009 extension form
+     * (`<x14:dataValidation>`) — the carrier Excel uses for a list source on another sheet and other
+     * shapes the standard element cannot express. The reader sets it for a rule found in that form so a
+     * round-trip writes it back there instead of silently corrupting the cross-sheet reference.
+     */
+    addDataValidation(sqref: string, rule: DataValidation, options?: {
+        extended?: boolean;
+    }): void;
+    /** The data validations on this sheet, each bound to its target range, in insertion order. */
+    get dataValidations(): readonly DataValidationEntry[];
+    /**
+     * Attach a conditional formatting to a target range. `formatting.ref` is an OOXML `sqref` — one
+     * range (`"A1:A10"`), a whole column, or several space-separated areas (`"A1:C1 A3:C3"`) sharing one
+     * rule set. The block is stored once against the range, defensively copied so the getter never hands
+     * back a reference into the caller's object.
+     */
+    addConditionalFormatting(formatting: ConditionalFormatting): void;
+    /** The conditional formattings on this sheet, each bound to its target range, in insertion order. */
+    get conditionalFormattings(): readonly ConditionalFormatting[];
+    /**
+     * The validation covering a cell, or `undefined` when none does. The first added rule whose range
+     * contains the cell wins, mirroring how a spreadsheet resolves overlapping validations.
+     */
+    dataValidationAt(reference: string): DataValidation | undefined;
+    /**
+     * Remove `count` rows starting at the 1-based `start`, then insert the given rows in their place.
+     * Rows below the edit shift by `inserts.length - count`: a delete pulls the tail up, an insert
+     * pushes it down, and doing both at once is a replace. Each inserted row takes either
+     * {@link RowInput} shape — a positional array from column A, or a key-addressed object — exactly
+     * like {@link addRow}. A `count` larger than the rows present simply clears the tail — it never
+     * silently becomes a no-op. Cells carry their full style to the shifted position, and merged ranges
+     * shift with the rows they cover.
+     *
+     * @throws {RangeError} if `start` is not a positive integer or `count` is negative.
+     */
+    spliceRows(start: number, count: number, ...inserts: RowInput[]): void;
+    /**
+     * Insert one row of `values` at the 1-based `pos`, shifting the rows at and below it down by one.
+     * `values` takes either {@link RowInput} shape (positional array or keyed object), like
+     * {@link addRow}. Shorthand for {@link spliceRows}`(pos, 0, values)`.
+     *
+     * @throws {RangeError} if `pos` is not a positive integer.
+     */
+    insertRow(pos: number, values: RowInput): void;
+    /**
+     * Append a row of `values` after the last used row, returning the cells it materialised.
+     * The append point is {@link rowCount}` + 1`, so the row lands below every row that holds
+     * data or its own formatting — never overwriting existing content, unlike {@link insertRow},
+     * which shifts and needs a position. Unlike {@link spliceRows}, appending shifts nothing, so
+     * it never disturbs merges or the rows above.
+     *
+     * A row takes either shape: a positional array whose values map to columns from A — a hole in a
+     * sparse array (`['a', , 'c']`) leaves that column untouched — or a keyed object whose values
+     * land under the columns carrying the matching {@link ColumnProperties.key}.
+     */
+    addRow(values: RowInput): Cell[];
+    /**
+     * Append several rows after the last used row in one call, returning the cells materialised
+     * for each. The rows stack in order — the first lands at {@link rowCount}` + 1`, the next
+     * directly below it — so a later row never collides with an earlier one even when both are
+     * value-less. Each row is an array or a keyed object independently, so a mixed batch is fine.
+     * The bulk form of {@link addRow}.
+     */
+    addRows(rows: RowInput[]): Cell[][];
+    /**
+     * Freeze the top `ySplit` rows and left `xSplit` columns in place; the rest of the sheet scrolls
+     * beneath them. `freeze(1)` pins a header row; `freeze(0, 1)` pins the first column. Passing both
+     * zero clears the freeze (equivalent to {@link unfreeze}).
+     *
+     * @throws {RangeError} if either split is a negative or non-integer count.
+     */
+    freeze(ySplit?: number, xSplit?: number): void;
+    /** Clear any frozen split, returning the sheet to a normal (fully scrolling) view. */
+    unfreeze(): void;
+    /**
+     * Copy the row at the 1-based `start`, `options.count` times (default 1). With `options.insert`
+     * (the default) the copies are inserted directly after the source, shifting the rows below — and
+     * any merged range there — down by `count`; otherwise the copies overwrite the rows immediately
+     * below without shifting. Each copy is a faithful duplicate of the source's values and per-cell
+     * styles, and carries no merge of its own, so a range can be merged onto a duplicated row afterwards.
+     *
+     * @throws {RangeError} if `start` is not a positive integer or `count` is negative.
+     */
+    duplicateRow(start: number, options?: {
+        count?: number;
+        insert?: boolean;
+    }): void;
+    /**
+     * Remove `count` columns starting at the 1-based `start`, then insert the given columns in their
+     * place — the column analog of {@link spliceRows}. Columns to the right shift by
+     * `inserts.length - count`, keeping their values and styles, and a merged range lying wholly to
+     * the right of the edit re-anchors to its new columns. Each inserted column is an array of values
+     * indexed by row (index 0 → row 1); an empty array inserts a blank column.
+     *
+     * @throws {RangeError} if `start` is not a positive integer or `count` is negative.
+     */
+    spliceColumns(start: number, count: number, ...inserts: CellValue[][]): void;
+    /**
+     * Insert one column of `values` at the 1-based `pos`, shifting the columns at and right of it over
+     * by one. `values` is an array of values indexed by row (index 0 → row 1), like
+     * {@link addColumn}. Shorthand for {@link spliceColumns}`(pos, 0, values)`.
+     *
+     * @throws {RangeError} if `pos` is not a positive integer.
+     */
+    insertColumn(pos: number, values: CellValue[]): void;
+    /**
+     * Append a column of `values` after the last used column, returning the cells it materialised.
+     * The append point is {@link columnCount}` + 1`, so the column lands right of every column that
+     * holds data or its own formatting — never overwriting existing content, unlike {@link insertColumn},
+     * which shifts and needs a position. Unlike {@link spliceColumns}, appending shifts nothing, so it
+     * never disturbs merges or the columns to its left.
+     *
+     * `values` is an array indexed by row (index 0 → row 1); a hole or an explicit `undefined` leaves
+     * that row untouched, mirroring {@link addRow}'s positional-array shape.
+     */
+    addColumn(values: CellValue[]): Cell[];
+    /**
+     * Append several columns after the last used column in one call, returning the cells materialised
+     * for each. The columns stack in order — the first lands at {@link columnCount}` + 1`, the next
+     * directly right of it — so a later column never collides with an earlier one even when both are
+     * value-less. The bulk form of {@link addColumn}.
+     */
+    addColumns(columns: CellValue[][]): Cell[][];
+    /**
+     * A snapshot of this sheet's value and overlay content (see {@link WorksheetModel}). Reading it and
+     * assigning it onto another sheet — `dst.model = src.model` — reproduces the source: merges, cells
+     * and their styles, column/row metadata, tables, the autofilter, protection, and the page setup all
+     * survive, because the getter emits and the setter consumes exactly the same fields. Identity
+     * (`name`, `id`) is not part of the model and is never touched by assignment; nor are attached parts
+     * that carry workbook-level identity (images, pivots, byte-preserved charts/drawings) — see
+     * {@link WorksheetModel} for that boundary.
+     */
+    get model(): WorksheetModel;
+    set model(model: WorksheetModel);
+    /**
+     * Protect the sheet, making the per-cell `locked`/`hidden` flags enforceable. Without a
+     * password the protection is a soft lock any consumer can lift; with one, the password is
+     * salted and hashed on the spot (the plaintext is never retained) so lifting the protection
+     * requires re-supplying it. `options` names which operations stay available to a user while
+     * the sheet is protected; anything unspecified falls to Excel's default for that operation.
+     *
+     * Re-protecting replaces any prior protection; {@link unprotect} clears it.
+     */
+    protect(password?: string, options?: SheetProtectionOptions): void;
+    /** Remove any protection previously set by {@link protect}. */
+    unprotect(): void;
+    /** The sheet's protection, or `undefined` if the sheet is unprotected. */
+    get protection(): SheetProtection | undefined;
+    /**
+     * The codec's channel into this sheet — see `core/internal.ts` for why these are not public
+     * methods. Declared last so every private field it closes over is already in scope.
+     */
+    readonly [INTERNAL]: WorksheetInternals;
+}
+/**
+ * What the library's own machinery may do to a `Worksheet` that an author may not: reinstate state
+ * read from a file, place a cell where a file or model says rather than where addressing would put
+ * it, and release a row the streaming writer has finished with. Reached as `sheet[INTERNAL]`; see
+ * `core/internal.ts`.
+ */
+export interface WorksheetInternals {
+    /**
+     * Drop a row's materialised cells and format properties, releasing its cell graph. The streaming
+     * writer calls this the moment a row is serialised so peak memory stays bounded to the rows still
+     * in flight rather than the whole sheet. Row *numbering* is the caller's concern: eviction lowers
+     * {@link Worksheet.rowCount}, so an append-driven producer must track its own high-water mark
+     * rather than lean on this sheet's used range.
+     */
+    evictRow(number: number): void;
+    /**
+     * Register a pivot table reconstructed from a loaded package — the reader's counterpart to
+     * {@link Worksheet.addPivotTable}. This records an inspectable, read-only view of a pivot the
+     * reader parsed from its OOXML parts; the pivot itself round-trips by byte-preservation, so
+     * registering it here only makes it visible via {@link Worksheet.loadedPivotTables} and never
+     * affects what the writer emits.
+     */
+    addLoadedPivotTable(pivot: ParsedPivotTable): void;
+    /**
+     * Reinstate the threaded conversations read from a file, in the order the reader found them,
+     * replacing any already held. Their authors and mentioned people are already resolved against the
+     * workbook registry, so a thread arrives self-contained.
+     *
+     * Not authoring — {@link Worksheet.addCommentThread} is that, and validates the anchor. These
+     * threads are what a re-write emits, so what the reader hands over is what the file will say.
+     */
+    restoreCommentThreads(threads: readonly CommentThread[]): void;
+    /**
+     * Record a worksheet-level reference to package content the model does not interpret, so the writer
+     * re-emits it verbatim. Called by the reader when it meets a `<drawing>` holding only vector shapes
+     * or a `<legacyDrawingHF>` header/footer image.
+     */
+    addPreservedReference(reference: PreservedWorksheetReference): void;
+    /**
+     * Reinstate an already-derived protection state — the deserialization counterpart to
+     * {@link Worksheet.protect}. A loaded `<sheetProtection>` carries its credential in finished agile
+     * form (algorithm, hash, salt, spin count) with no recoverable plaintext password, so the reader
+     * restores that credential verbatim rather than re-hashing.
+     */
+    restoreProtection(protection: SheetProtection): void;
+    /**
+     * Materialise the cell at an exact 1-based position, creating it on first access. Unlike
+     * {@link Worksheet.getCell} this performs no merge resolution: the cell returned is the one at
+     * `(row, col)` even when a merged region covers it. Loading content is where that matters — a
+     * model or a parsed file states where each value sits, and routing a covered value to its region
+     * master mid-load would move it.
+     */
+    cellAt(row: number, col: number): Cell;
+    /**
+     * The store behind a {@link Row} or {@link Column} handle. These six exist because the handles are
+     * views rather than records: they hold a sheet and a position, and every read and write goes
+     * through here to the one authoritative map. `…PropertiesOf` never fabricates, so reading a row
+     * cannot extend the used range; `ensure…` is what a write calls, so the record appears exactly
+     * when a value is set.
+     */
+    rowPropertiesOf(number: number): RowProperties | undefined;
+    ensureRowProperties(number: number): RowProperties;
+    /** The row's materialised cells in ascending column order. */
+    rowCells(number: number): Cell[];
+    columnPropertiesOf(index: number): ColumnProperties | undefined;
+    ensureColumnProperties(index: number): ColumnProperties;
+    /** The column's materialised cells in ascending row order. */
+    columnCells(index: number): Cell[];
+}