@office-kit/xlsx 0.8.0

package/dist/workbook/workbook.d.ts

@@ -0,0 +1,643 @@
+import type { Chartsheet } from '../chartsheet/chartsheet';
+import { type ChartReference } from '../drawing/drawing';
+import type { CoreProperties } from '../packaging/core';
+import type { CustomProperties } from '../packaging/custom';
+import type { ExtendedProperties } from '../packaging/extended';
+import type { Stylesheet } from '../styles/stylesheet';
+import { type CellValue } from '../cell/cell';
+import type { Alignment } from '../styles/alignment';
+import type { Border } from '../styles/borders';
+import type { Fill } from '../styles/fills';
+import type { Font } from '../styles/fonts';
+import type { Protection } from '../styles/protection';
+import type { LegacyComment } from '../worksheet/comments';
+import type { Hyperlink } from '../worksheet/hyperlinks';
+import type { CellsByKindCounts, Worksheet } from '../worksheet/worksheet';
+export type SheetState = 'visible' | 'hidden' | 'veryHidden';
+/**
+ * Discriminated union over the two kinds of sheet a workbook can host. Both
+ * variants share `title` (via `sheet.title`) plus the OOXML `sheetId` and
+ * `state` attributes; consumers narrow on `kind` to reach the worksheet- vs
+ * chartsheet-specific data.
+ */
+export type SheetRef = {
+    kind: 'worksheet';
+    sheet: Worksheet;
+    sheetId: number;
+    state: SheetState;
+    rId?: string;
+} | {
+    kind: 'chartsheet';
+    sheet: Chartsheet;
+    sheetId: number;
+    state: SheetState;
+    rId?: string;
+};
+export interface Workbook {
+    sheets: SheetRef[];
+    /** Index into `sheets` of the sheet shown when Excel opens the file. */
+    activeSheetIndex: number;
+    /** Style pool; cells reference its cellXfs by index. */
+    styles: Stylesheet;
+    /** Date1904 mode toggles between Excel's two epoch systems. */
+    date1904: boolean;
+    /** Document properties (docProps/core.xml), typically auto-filled on save. */
+    properties?: CoreProperties;
+    appProperties?: ExtendedProperties;
+    customProperties?: CustomProperties;
+    /** Author display names, shared between threaded comments. */
+    authors: string[];
+    /** Workbook + sheet-scope defined names (named ranges, print areas etc). */
+    definedNames: import('./defined-names').DefinedName[];
+    /**
+     * Raw `xl/theme/theme1.xml` payload kept verbatim across read → write. The
+     * theme XML is large and seldom edited by writers; we just shuttle it.
+     */
+    themeXml?: Uint8Array;
+    /**
+     * `xl/vbaProject.bin` payload (macro-enabled workbooks). Round-tripped
+     * byte-identical when present; the writer also promotes the workbook Override
+     * to `vnd.ms-excel.sheet.macroEnabled.main+xml`.
+     */
+    vbaProject?: Uint8Array;
+    /** `xl/vbaProjectSignature.bin` payload, when the macros are signed. */
+    vbaSignature?: Uint8Array;
+    /**
+     * Pass-through bytes for parts we don't model (pivot tables, ActiveX
+     * controls, OLE embeddings, customUI ribbons, customXml items …). Keys are
+     * archive-relative paths; values are the raw bytes the loader pulled out of
+     * the zip and the writer pushes back in unchanged.
+     */
+    passthrough?: Map<string, Uint8Array>;
+    /**
+     * Override content type per pass-through path. Excel uses these in
+     * `[Content_Types].xml` so manifest validation stays intact across
+     * round-trips. Paths without an explicit override fall back to the archive
+     * Default extension.
+     */
+    passthroughContentTypes?: Map<string, string>;
+    /**
+     * Top-level `<workbook>` children that aren't `<sheets>` or `<definedNames>`
+     * (e.g. `<fileVersion>`, `<workbookPr>`, `<bookViews>`, `<calcPr>`,
+     * `<pivotCaches>`, `<extLst>`). Captured verbatim so re-saving keeps
+     * Excel-rendering fidelity for things we don't model. Split into the two
+     * halves the writer needs: anything before `<sheets>` is emitted ahead of the
+     * `<sheets>` element, the rest after `<definedNames>`.
+     */
+    workbookXmlExtras?: {
+        beforeSheets: import('../xml/tree').XmlNode[];
+        afterSheets: import('../xml/tree').XmlNode[];
+    };
+    /**
+     * `<workbookProtection>` — locks structure / window / revision tracking with
+     * the modern hash quad or the legacy 16-bit hash. Round-tripped verbatim;
+     * password hashing helpers come later.
+     */
+    workbookProtection?: import('./protection').WorkbookProtection;
+    /**
+     * `<bookViews>` — the workbook's window/tab-strip presets. Most workbooks
+     * have a single entry whose `firstSheet` / `activeTab` drive the tab the user
+     * sees first. Stored as an array because Excel allows multiple views (rare).
+     */
+    bookViews?: import('./views').WorkbookView[];
+    /**
+     * `<customWorkbookViews>` — saved per-user view presets used by the
+     * deprecated "Shared Workbook" feature. Each entry carries its own window
+     * position, active sheet, and visibility toggles.
+     */
+    customWorkbookViews?: import('./views').CustomWorkbookView[];
+    /** `<calcPr>` — calculation engine settings (calcMode / iterate / fullPrecision etc.). */
+    calcProperties?: import('./calc-properties').CalcProperties;
+    /** `<fileVersion>` — Office app/version metadata Excel records on save. */
+    fileVersion?: import('./file-version').FileVersion;
+    /** `<fileSharing>` — read-only-recommended toggle + write-protection password. */
+    fileSharing?: import('./file-sharing').FileSharing;
+    /**
+     * `<oleSize ref="…">` — bounding range Excel uses when the workbook is
+     * embedded as an OLE object inside another Office document.
+     */
+    oleSize?: string;
+    /** `<fileRecoveryPr>` — autoRecover-style flags Excel writes after a recovery save. */
+    fileRecoveryPr?: import('./file-recovery').FileRecoveryProperties;
+    /**
+     * `<pivotCaches>` — links from workbook root to xl/pivotCache parts. The
+     * underlying parts survive via the passthrough archive; this typed array
+     * preserves the cacheId ↔ rId mapping for consumers that want to introspect
+     * the pivot links.
+     */
+    pivotCaches?: ReadonlyArray<{
+        cacheId: number;
+        rId: string;
+    }>;
+    /**
+     * `<externalReferences>` — links from workbook root to xl/externalLinks
+     * parts. The numeric token in cross-workbook formulas like `[1]Sheet!A1` is
+     * the 1-based index into this array. Underlying parts continue via
+     * passthrough archive.
+     */
+    externalReferences?: ReadonlyArray<{
+        rId: string;
+    }>;
+    /** `<smartTagPr>` — Excel 2003 smart-tag persistence flags. */
+    smartTagPr?: import('./smart-tags').SmartTagProperties;
+    /** `<smartTagTypes>` — Excel 2003 smart-tag type registrations. */
+    smartTagTypes?: ReadonlyArray<import('./smart-tags').SmartTagType>;
+    /** `<functionGroups>` — built-in + user-defined XLL function groups. */
+    functionGroups?: import('./function-groups').FunctionGroups;
+    /**
+     * `<workbookPr>` — VBA codeName, defaultThemeVersion, link-update prompt
+     * mode, etc. `date1904` is mirrored here for completeness but the canonical
+     * source remains `wb.date1904`.
+     */
+    workbookProperties?: import('./workbook-properties').WorkbookProperties;
+    /**
+     * Workbook-level rels that don't match a modeled type. Re-emitted with their
+     * original Id so captured `<pivotCaches r:id="…"/>` etc. still resolve after
+     * a round-trip.
+     */
+    workbookRelsExtras?: ReadonlyArray<{
+        id: string;
+        type: string;
+        target: string;
+    }>;
+    /**
+     * Original rIds for the modeled non-sheet workbook rels so a captured extras
+     * XML referencing one of them still resolves after re-save.
+     */
+    workbookRelOriginalIds?: {
+        sharedStrings?: string;
+        styles?: string;
+        theme?: string;
+        vbaProject?: string;
+    };
+}
+/** Build an empty Workbook ready to host worksheets. */
+export declare function createWorkbook(opts?: {
+    date1904?: boolean;
+}): Workbook;
+/**
+ * Validate a sheet title against Excel's character + length rules. Returns the
+ * reason string when the title is rejected; `undefined` when valid. The same
+ * rules apply to worksheets and chartsheets.
+ *
+ * Rules:
+ *  - Type must be `string`; non-empty; length ≤ 31.
+ *  - May not contain any of `:`, `\`, `/`, `?`, `*`, `[`, `]`.
+ *  - May not start or end with an apostrophe `'`.
+ *  - May not be the literal `"History"` (case-insensitive — Excel
+ * reserves that name for the change-tracking sheet).
+ *
+ * Uniqueness is **not** checked here; pass through `addWorksheet` /
+ * `renameSheet` for the workbook-aware duplicate check.
+ */
+export declare function validateSheetTitle(title: unknown): string | undefined;
+/** Boolean form of {@link validateSheetTitle}. */
+export declare const isValidSheetTitle: (title: unknown) => title is string;
+/**
+ * Pick a unique sheet title based on `base`. If `base` itself is available,
+ * it's returned verbatim. Otherwise the helper appends ` (2)`, ` (3)`, … until
+ * it finds a free slot. The returned title always satisfies {@link
+ * validateSheetTitle} — if the base+suffix would exceed 31 chars, the base is
+ * truncated to fit.
+ *
+ * Excel treats sheet names as case-insensitive for uniqueness, so `Data` and
+ * `data` collide; the helper applies the same rule.
+ *
+ * Useful for "duplicate sheet" / "import" flows where you want Excel-like
+ * automatic uniqueification ("Sheet1 (2)").
+ */
+export declare function pickUniqueSheetTitle(wb: Workbook, base: string): string;
+/** Add a Worksheet to the Workbook. Returns the sheet for further population. */
+export declare function addWorksheet(wb: Workbook, title: string, opts?: {
+    index?: number;
+    state?: SheetState;
+}): Worksheet;
+/**
+ * 0-based tab-strip index of the sheet (worksheet *or* chartsheet) with the
+ * given title, or `-1` when not present. Useful when the caller wants to act on
+ * the index for `setActiveSheet` / `swapSheets` / similar operations without
+ * manually scanning `wb.sheets`.
+ */
+export declare function getSheetIndex(wb: Workbook, title: string): number;
+/**
+ * True iff the workbook has a sheet (worksheet *or* chartsheet) with the given
+ * title. Thin shortcut over {@link getSheetIndex}.
+ */
+export declare function hasSheet(wb: Workbook, title: string): boolean;
+/**
+ * Count sheets in the workbook, with optional kind/state filters. Mirrors the
+ * filter shape of {@link getSheetTitles} but skips the array allocation when
+ * the caller only needs the count.
+ */
+export declare function countSheets(wb: Workbook, opts?: {
+    kind?: 'worksheet' | 'chartsheet';
+    state?: SheetState;
+}): number;
+/**
+ * Sheet titles in tab-strip order. By default returns titles for every sheet
+ * (worksheets + chartsheets). Optional filters narrow to one kind
+ * (`'worksheet'` / `'chartsheet'`) or one state (`'visible' | 'hidden' |
+ * 'veryHidden'`).
+ */
+export declare function getSheetTitles(wb: Workbook, opts?: {
+    kind?: 'worksheet' | 'chartsheet';
+    state?: SheetState;
+}): string[];
+/**
+ * True iff the workbook has a **worksheet** (not a chartsheet) with the given
+ * title. Distinct from {@link hasSheet} (matches either kind) and {@link
+ * hasChartsheet} (chartsheets only).
+ */
+export declare function hasWorksheet(wb: Workbook, title: string): boolean;
+/**
+ * True iff the workbook has a **chartsheet** (not a worksheet) with the given
+ * title. Distinct from {@link hasSheet}, which matches either kind. Use this
+ * when the caller needs to discriminate before calling chartsheet-only
+ * operations.
+ */
+export declare function hasChartsheet(wb: Workbook, title: string): boolean;
+/** Look up a Worksheet by title. Returns undefined for missing names or chartsheets. */
+export declare function getSheet(wb: Workbook, title: string): Worksheet | undefined;
+/** Look up a Worksheet by index in the sheets array. Returns undefined for chartsheet slots. */
+export declare function getSheetByIndex(wb: Workbook, idx: number): Worksheet | undefined;
+/** Look up a Chartsheet by title. Returns undefined for missing names or worksheets. */
+export declare function getChartsheet(wb: Workbook, title: string): Chartsheet | undefined;
+/** Add a Chartsheet to the Workbook. Returns the chartsheet for further population. */
+export declare function addChartsheet(wb: Workbook, title: string, opts?: {
+    index?: number;
+    state?: SheetState;
+    chart?: ChartReference;
+}): Chartsheet;
+/** All worksheet titles, in display order. */
+export declare function sheetNames(wb: Workbook): string[];
+/** Remove a sheet by title. No-op if the title is not registered. */
+export declare function removeSheet(wb: Workbook, title: string): void;
+/** Set the active sheet by title; throws on unknown title. */
+export declare function setActiveSheet(wb: Workbook, title: string): void;
+/**
+ * Rename a sheet from `oldTitle` to `newTitle`. Throws if no sheet matches
+ * `oldTitle`, or if `newTitle` collides with an existing sheet (Excel requires
+ * sheet names to be unique within a workbook).
+ */
+export declare function renameSheet(wb: Workbook, oldTitle: string, newTitle: string): void;
+/**
+ * Set the visibility state on a sheet by title. Throws on unknown title.
+ * Refuses to hide the last visible sheet: an .xlsx with every sheet hidden
+ * fails to open in Excel ("Excel cannot use the object linking and embedding
+ * features because no sheet is visible"). Catching it here keeps the
+ * workbook recoverable instead of producing a save Excel will reject.
+ */
+export declare function setSheetState(wb: Workbook, title: string, state: SheetState): void;
+/** Look up the current visibility state. Throws on unknown title. */
+export declare function getSheetState(wb: Workbook, title: string): SheetState;
+/**
+ * Hide a sheet (`state: 'hidden'`). Equivalent to right-click → Hide in Excel —
+ * the user can re-show it via the Unhide dialog.
+ */
+export declare function hideSheet(wb: Workbook, title: string): void;
+/**
+ * Mark a sheet as very-hidden (`state: 'veryHidden'`). Excel won't surface it
+ * in the Unhide dialog — only reachable via VBA / API.
+ */
+export declare function veryHideSheet(wb: Workbook, title: string): void;
+/** Make a hidden / veryHidden sheet visible. */
+export declare function showSheet(wb: Workbook, title: string): void;
+/**
+ * Bulk-update visibility state for many sheets in one call. `entries` is a
+ * `Record<title, state>` map; missing titles throw via the underlying
+ * `setSheetState`.
+ */
+export declare function setSheetStates(wb: Workbook, entries: Record<string, SheetState>): void;
+/**
+ * Show every hidden / veryHidden worksheet. Returns the count unhidden. Useful
+ * for spreadsheet-wide auditing.
+ */
+export declare function showAllSheets(wb: Workbook): number;
+/**
+ * Move a sheet to a new tab-strip position. `toIndex` is clamped to `[0,
+ * sheets.length - 1]`. Adjusts `activeSheetIndex` so the same sheet stays
+ * active across the move.
+ */
+export declare function moveSheet(wb: Workbook, title: string, toIndex: number): void;
+/**
+ * Swap the tab-strip positions of two sheets by title. Both titles must exist;
+ * throws otherwise. `activeSheetIndex` follows the moved sheet so the same
+ * sheet stays active across the swap.
+ */
+export declare function swapSheets(wb: Workbook, titleA: string, titleB: string): void;
+/**
+ * Duplicate a worksheet end-to-end and append it as `newTitle`. Mirrors Excel's
+ * "Move or Copy → Create a copy" command. Cells, dimensions, styles (via shared
+ * cellXf ids), comments, hyperlinks, conditional formatting, page setup, etc.
+ * all carry over verbatim — only fields that must stay workbook-unique get
+ * rewritten:
+ *
+ *  - sheet `title` → `newTitle`
+ *  - sheet `sheetId` → freshly allocated
+ *  - each table's `id` → max(workbook table ids) + 1
+ *  - each table's `displayName` → suffixed with `opts.tableSuffix`
+ * (default `"_2"`) so it doesn't collide with the original
+ *
+ * The new sheet is inserted at the optional `index` (default: appended).
+ */
+export declare function duplicateSheet(wb: Workbook, sourceTitle: string, newTitle: string, opts?: {
+    index?: number;
+    state?: SheetState;
+    tableSuffix?: string;
+}): Worksheet;
+/**
+ * Aggregate counts about a workbook's content. Useful for quick QA after large
+ * mutations or for surfacing a "what's in this file" banner. All counts walk
+ * the typed model — they do **not** save the workbook to bytes — so the cost is
+ * O(workbook content).
+ */
+export interface WorkbookStats {
+    /** Total worksheets (excludes chartsheets). */
+    worksheetCount: number;
+    /** Total chartsheets. */
+    chartsheetCount: number;
+    /** Sum of populated cells across every worksheet. */
+    cellCount: number;
+    /** Sum of formula cells. */
+    formulaCount: number;
+    /** Sum of legacyComments across every worksheet. */
+    commentCount: number;
+    /** Sum of hyperlinks across every worksheet. */
+    hyperlinkCount: number;
+    /** Sum of mergedCells ranges. */
+    mergedRangeCount: number;
+    /** Sum of Excel tables. */
+    tableCount: number;
+    /** Workbook-level defined names. */
+    definedNameCount: number;
+    /** Custom-property entry count, 0 when no docProps/custom.xml. */
+    customPropertyCount: number;
+}
+export declare function getWorkbookStats(wb: Workbook): WorkbookStats;
+/**
+ * Workbook-wide value-kind histogram. Sums {@link countCellsByKind} across
+ * every Worksheet (chartsheets contribute no cells). Buckets have the same
+ * shape as the per-worksheet result; an empty workbook returns all-zero counts.
+ */
+export declare function getWorkbookCellsByKind(wb: Workbook): CellsByKindCounts;
+/**
+ * Resolve a sheet-qualified A1 address (`'Sheet1!A1'`) to its Cell, or
+ * `undefined` when the cell isn't materialised. Throws on malformed addresses,
+ * missing sheets, or range inputs.
+ */
+export declare function getCellAtAddress(wb: Workbook, address: string): import('../cell/cell').Cell | undefined;
+/**
+ * Set a single cell by sheet-qualified A1 address. Throws on malformed
+ * addresses, missing sheets, or range inputs.
+ */
+export declare function setCellAtAddress(wb: Workbook, address: string, value: CellValue): import('../cell/cell').Cell;
+/**
+ * True iff every Worksheet in the workbook is empty (per {@link
+ * isWorksheetEmpty}). Chartsheets carry no cells so they never affect the
+ * result. A workbook with zero worksheets is also empty by this definition.
+ *
+ * Short-circuits on the first non-empty worksheet.
+ */
+export declare function isWorkbookEmpty(wb: Workbook): boolean;
+/**
+ * Per-sheet entry inside {@link WorkbookOverview}. Holds enough metadata to
+ * make a "what's in this workbook" panel useful without forcing the caller to
+ * walk every worksheet themselves.
+ */
+export interface WorkbookSheetOverview {
+    title: string;
+    kind: 'worksheet' | 'chartsheet';
+    state: SheetState;
+    /** Populated cells in the sheet (0 for chartsheets). */
+    cellCount: number;
+    /** Populated formula cells (0 for chartsheets). */
+    formulaCount: number;
+    /** Tables registered on the sheet. */
+    tableCount: number;
+    /** Drawing items (charts + pictures) on the sheet. */
+    drawingItemCount: number;
+}
+/**
+ * High-level "what's in this workbook" snapshot. Combines the aggregate counts
+ * from {@link getWorkbookStats} and value-kind histogram from {@link
+ * getWorkbookCellsByKind} with per-sheet metadata. JSON-serialisable; suitable
+ * for a UI banner / debug dump.
+ */
+export interface WorkbookOverview {
+    worksheetCount: number;
+    chartsheetCount: number;
+    cellCount: number;
+    formulaCount: number;
+    commentCount: number;
+    hyperlinkCount: number;
+    mergedRangeCount: number;
+    tableCount: number;
+    definedNameCount: number;
+    customPropertyCount: number;
+    cellsByKind: CellsByKindCounts;
+    sheets: WorkbookSheetOverview[];
+}
+export declare function describeWorkbook(wb: Workbook): WorkbookOverview;
+/**
+ * Debug-friendly snapshot of everything resolved for a single cell: its value,
+ * the full style chain (font / fill / border / alignment / protection /
+ * numberFormat), the applied hyperlink + comment, the merged range it sits
+ * inside (if any), and the names of any tables / the count of CF / DV blocks
+ * that target it.
+ *
+ * Designed for `console.log`-style introspection — JSON-serialisable and stable
+ * in shape regardless of which axes are populated.
+ *
+ * Throws when `sheetTitle` doesn't resolve. When `ref` is a valid A1 coordinate
+ * but no cell exists there, `exists` is `false` and the style chain reflects
+ * the workbook defaults.
+ */
+export interface CellSummary {
+    ref: string;
+    sheet: string;
+    exists: boolean;
+    value: CellValue | undefined;
+    styleId: number;
+    font: Font;
+    fill: Fill;
+    border: Border;
+    alignment: Alignment;
+    protection: Protection;
+    numberFormat: string;
+    hyperlink: Hyperlink | undefined;
+    comment: LegacyComment | undefined;
+    mergedRange: string | undefined;
+    inTables: string[];
+    inDataValidations: number;
+    inConditionalFormatting: number;
+}
+export declare function getCellSummary(wb: Workbook, sheetTitle: string, ref: string): CellSummary;
+/**
+ * Iterate over every Worksheet in the workbook (skips chartsheets). Yields each
+ * worksheet in tab-strip order.
+ */
+export declare function iterWorksheets(wb: Workbook): IterableIterator<Worksheet>;
+/**
+ * Iterate only over Worksheets whose tab-strip state is `'visible'`. Hidden /
+ * veryHidden sheets are skipped. Useful for reports that should ignore
+ * back-office sheets the author has hidden.
+ */
+export declare function iterVisibleWorksheets(wb: Workbook): IterableIterator<Worksheet>;
+/**
+ * Iterate Worksheets matching the supplied state. Pass `'hidden'` to skim
+ * back-office sheets, `'veryHidden'` to find sheets only accessible via VBA,
+ * etc.
+ */
+export declare function iterWorksheetsByState(wb: Workbook, state: SheetState): IterableIterator<Worksheet>;
+/**
+ * Iterate every cell across every worksheet in the workbook. Yields `{ sheet,
+ * cell }` pairs in tab-strip order, then row-then-column within each sheet.
+ * Useful for workbook-wide audits / find-and-replace passes.
+ */
+export declare function iterAllCells(wb: Workbook): IterableIterator<{
+    sheet: Worksheet;
+    cell: import('../cell/cell').Cell;
+}>;
+/**
+ * Collect every merged range across every worksheet. Each entry carries the
+ * merge bounds plus a back-reference to the owning sheet, in tab-strip order.
+ * Equivalent to walking `iterWorksheets` and concatenating each sheet's
+ * `mergedCells`.
+ */
+export declare function getAllMergedRanges(wb: Workbook): ReadonlyArray<{
+    sheet: Worksheet;
+    range: import('../worksheet/cell-range').CellRange;
+}>;
+/**
+ * Collect every hyperlink across every worksheet. Each entry pairs the
+ * hyperlink with a back-reference to the owning sheet, in tab-strip order.
+ */
+export declare function getAllHyperlinks(wb: Workbook): ReadonlyArray<{
+    sheet: Worksheet;
+    hyperlink: import('../worksheet/hyperlinks').Hyperlink;
+}>;
+/**
+ * Collect every legacy comment across every worksheet. Each entry pairs the
+ * comment with a back-reference to the owning sheet, in tab-strip order.
+ */
+export declare function getAllComments(wb: Workbook): ReadonlyArray<{
+    sheet: Worksheet;
+    comment: import('../worksheet/comments').LegacyComment;
+}>;
+/**
+ * Collect every Excel table across every worksheet. Each entry pairs the
+ * TableDefinition with a back-reference to the owning sheet, in tab-strip
+ * order.
+ */
+export declare function getAllTables(wb: Workbook): ReadonlyArray<{
+    sheet: Worksheet;
+    table: import('../worksheet/table').TableDefinition;
+}>;
+/**
+ * Locate an Excel table by `displayName` across the whole workbook. Excel
+ * enforces uniqueness at the workbook level, so the first match wins. Returns
+ * the owning sheet + the table itself, or `undefined` when nothing matches.
+ */
+export declare function findTable(wb: Workbook, displayName: string): {
+    sheet: Worksheet;
+    table: import('../worksheet/table').TableDefinition;
+} | undefined;
+/**
+ * First cell across the workbook satisfying `predicate`. Walks every worksheet
+ * in tab-strip order, then row-then-column within each sheet (same order as
+ * {@link iterAllCells}). Returns `{ sheet, cell }` for the match, or
+ * `undefined` when nothing matches.
+ */
+export declare function findCellInWorkbook(wb: Workbook, predicate: (cell: import('../cell/cell').Cell, sheet: Worksheet) => boolean): {
+    sheet: Worksheet;
+    cell: import('../cell/cell').Cell;
+} | undefined;
+/**
+ * Every cell across the workbook satisfying `predicate`. Same iteration order
+ * as {@link iterAllCells}. Returns an array of `{ sheet, cell }` matches.
+ */
+export declare function findCellsInWorkbook(wb: Workbook, predicate: (cell: import('../cell/cell').Cell, sheet: Worksheet) => boolean): ReadonlyArray<{
+    sheet: Worksheet;
+    cell: import('../cell/cell').Cell;
+}>;
+/**
+ * Workbook-wide find-and-replace. Same matching rule as `replaceCellValues` but
+ * walks every worksheet via {@link iterAllCells}. `search` is either an
+ * exact-string match (string-valued cells only) or a predicate `(value, cell,
+ * sheet) → boolean`. `replacement` is the new `CellValue`. Returns the count of
+ * cells changed across all sheets.
+ */
+export declare function replaceCellValuesInWorkbook(wb: Workbook, search: string | ((value: import('../cell/cell').CellValue, cell: import('../cell/cell').Cell, sheet: Worksheet) => boolean), replacement: import('../cell/cell').CellValue): number;
+/**
+ * Collect every data-validation block across every worksheet. Each entry pairs
+ * the validation with a back-reference to the owning sheet, in tab-strip order.
+ */
+export declare function getAllDataValidations(wb: Workbook): ReadonlyArray<{
+    sheet: Worksheet;
+    validation: import('../worksheet/data-validations').DataValidation;
+}>;
+/**
+ * Collect every image (picture) DrawingItem across every worksheet, each paired
+ * with its owning sheet in tab-strip order.
+ */
+export declare function getAllImages(wb: Workbook): ReadonlyArray<{
+    sheet: Worksheet;
+    item: import('../drawing/drawing').DrawingItem;
+}>;
+/**
+ * Collect every chart DrawingItem across every worksheet, each paired with its
+ * owning sheet in tab-strip order.
+ */
+export declare function getAllCharts(wb: Workbook): ReadonlyArray<{
+    sheet: Worksheet;
+    item: import('../drawing/drawing').DrawingItem;
+}>;
+/**
+ * Collect every conditional-formatting block across every worksheet. Each entry
+ * pairs the CF block with a back-reference to the owning sheet, in tab-strip
+ * order.
+ */
+export declare function getAllConditionalFormatting(wb: Workbook): ReadonlyArray<{
+    sheet: Worksheet;
+    formatting: import('../worksheet/conditional-formatting').ConditionalFormatting;
+}>;
+/**
+ * Iterate over every Chartsheet in the workbook. Yields in tab-strip order,
+ * skipping regular worksheets.
+ */
+export declare function iterChartsheets(wb: Workbook): IterableIterator<Chartsheet>;
+/** Convenience: array of every Worksheet in tab-strip order. */
+export declare function listWorksheets(wb: Workbook): Worksheet[];
+/** Convenience: array of every Chartsheet in tab-strip order. */
+export declare function listChartsheets(wb: Workbook): Chartsheet[];
+/** Currently active sheet (worksheet only), or undefined if the active slot is empty or a chartsheet. */
+export declare function getActiveSheet(wb: Workbook): Worksheet | undefined;
+/**
+ * Title of whichever sheet (worksheet *or* chartsheet) is currently marked
+ * active via `wb.activeSheetIndex`. Returns `undefined` for an empty workbook
+ * or an out-of-range index.
+ *
+ * Distinct from {@link getActiveSheet} (which only returns worksheets and
+ * yields `undefined` when the active slot is a chartsheet) — this matches
+ * `wb.activeSheetIndex` regardless of kind.
+ */
+export declare function getActiveSheetTitle(wb: Workbook): string | undefined;
+/**
+ * True iff `title` matches the workbook's currently active sheet (any kind).
+ * Empty workbook returns `false` (no active sheet).
+ */
+export declare function isActiveSheet(wb: Workbook, title: string): boolean;
+/** Read-only view onto the customXml/* pass-through parts. */
+export declare function listCustomXmlParts(wb: Workbook): Array<{
+    path: string;
+    content: Uint8Array;
+}>;
+/**
+ * JSON.stringify replacer that drops the Stylesheet's internal dedup Maps. Use
+ * as `JSON.stringify(workbook, jsonReplacer)` when the workbook needs to
+ * round-trip through plain JSON (tests, debug dumps). The dedup maps are
+ * reconstructed lazily on first add.
+ */
+export declare function jsonReplacer(_key: string, value: unknown): unknown;
+/** Companion reviver for {@link jsonReplacer}. */
+export declare function jsonReviver(_key: string, value: unknown): unknown;