@shbernal/ts-xlsx 1.0.0

package/dist/io/xlsx/workbook-xml.js

@@ -0,0 +1,353 @@
+// Workbook-level serialisation: the package's `[Content_Types].xml`, its root and workbook `.rels`
+// parts, `xl/workbook.xml` (sheets, defined names, calc/protection settings, pivot-cache and slicer
+// registrations), and the `docProps` core/app property parts.
+import { mangleFormula, quoteSheetName } from "../../core/formula.js";
+import { WORKBOOK_PROTECTION_CREDENTIAL_ATTRS } from "../../core/workbook-protection.js";
+import { escapeAttr, escapeText, XML_DECLARATION } from "../../xml/xml.js";
+import { extensionOf, relativePartPath, THEME_PART_PATH } from "../opc/part-paths.js";
+import { relationship, relationshipsPart } from "../opc/rels.js";
+import { imageContentType } from "./images.js";
+import { SLICER_CACHES_EXT_URI } from "./namespaces.js";
+import { NS, REL } from "./relationships.js";
+import { x14Ext } from "./x14-ext.js";
+const CT = {
+    workbook: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml',
+    macroEnabledWorkbook: 'application/vnd.ms-excel.sheet.macroEnabled.main+xml',
+    worksheet: 'application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml',
+    styles: 'application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml',
+    theme: 'application/vnd.openxmlformats-officedocument.theme+xml',
+    core: 'application/vnd.openxmlformats-package.core-properties+xml',
+    app: 'application/vnd.openxmlformats-officedocument.extended-properties+xml',
+    table: 'application/vnd.openxmlformats-officedocument.spreadsheetml.table+xml',
+    comments: 'application/vnd.openxmlformats-officedocument.spreadsheetml.comments+xml',
+    vml: 'application/vnd.openxmlformats-officedocument.vmlDrawing',
+    drawing: 'application/vnd.openxmlformats-officedocument.drawing+xml',
+    printerSettings: 'application/vnd.openxmlformats-officedocument.spreadsheetml.printerSettings',
+    sharedStrings: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml',
+    pivotTable: 'application/vnd.openxmlformats-officedocument.spreadsheetml.pivotTable+xml',
+    pivotCacheDefinition: 'application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheDefinition+xml',
+    pivotCacheRecords: 'application/vnd.openxmlformats-officedocument.spreadsheetml.pivotCacheRecords+xml',
+    // Both threaded-comment parts are Microsoft extensions, hence the `vnd.ms-excel` vendor prefix rather
+    // than the `openxmlformats-officedocument` one every standard part carries.
+    threadedComments: 'application/vnd.ms-excel.threadedcomments+xml',
+    person: 'application/vnd.ms-excel.person+xml',
+};
+export function contentTypesXml(sheetCount, tables, commentNumbers, drawingNumbers, printerSettingsNumbers, mediaExtensions, hasSharedStrings, preservedParts, pivots, preservedWorkbookRefs, threadedCommentNumbers, hasPersons) {
+    // One extension→default-content-type map both halves read: the defaults render it, the overrides
+    // correct any preserved part whose own type differs from its extension's default. Sharing it is what
+    // keeps a `<Default>` and its `<Override>`s from ever disagreeing.
+    const extensionDefaults = buildExtensionDefaults(commentNumbers, printerSettingsNumbers, mediaExtensions, preservedParts);
+    return (XML_DECLARATION +
+        `<Types xmlns="${NS.contentTypes}">` +
+        contentTypeDefaults(extensionDefaults) +
+        contentTypeOverrides(sheetCount, tables, drawingNumbers, commentNumbers, hasSharedStrings, preservedParts, pivots, preservedWorkbookRefs, extensionDefaults, threadedCommentNumbers, hasPersons) +
+        '</Types>');
+}
+// The content type declared at the `<Default>` level for each file extension the package carries, in
+// emission order: the built-in rels/xml pair, the vml/bin/image kinds the writer itself generates,
+// then one default per *new* extension a preserved binary part introduces (first part of an extension
+// wins). Keys are lower-cased for case-insensitive extension matching; each value keeps the extension
+// token as it will be emitted so rendering stays byte-stable. A preserved `.xml` part is deliberately
+// left out — it always carries its own type as a per-part override, never a generic `xml` default.
+function buildExtensionDefaults(commentNumbers, printerSettingsNumbers, mediaExtensions, preservedParts) {
+    const defaults = new Map();
+    const add = (extension, contentType) => {
+        const key = extension.toLowerCase();
+        if (!defaults.has(key))
+            defaults.set(key, { extension, contentType });
+    };
+    add('rels', 'application/vnd.openxmlformats-package.relationships+xml');
+    add('xml', 'application/xml');
+    if (commentNumbers.length > 0)
+        add('vml', CT.vml);
+    if (printerSettingsNumbers.length > 0)
+        add('bin', CT.printerSettings);
+    for (const ext of mediaExtensions)
+        add(ext, imageContentType(ext));
+    for (const part of preservedParts) {
+        const ext = extensionOf(part.path);
+        if (ext.toLowerCase() === 'xml')
+            continue;
+        add(ext, part.contentType);
+    }
+    return defaults;
+}
+// A macro-enabled workbook's own VBA project is round-tripped as a preserved workbook reference
+// (see `isPreservedWorkbookRelType` in read.ts), so its presence is what distinguishes a re-emitted
+// .xlsm from a plain .xlsx: `xl/workbook.xml` must declare the macro-enabled content type or Excel
+// flags the package as needing repair on open.
+function isMacroEnabled(preservedWorkbookRefs) {
+    return preservedWorkbookRefs.some((ref) => ref.relType.endsWith('/vbaProject'));
+}
+// The extension-level `<Default>` declarations, rendered from the shared extension-default map (see
+// {@link buildExtensionDefaults}) in insertion order. The raw bytes of a VML, a printer-settings blob,
+// or an image carry no XML content type of their own, so each is declared once per extension rather
+// than per part; a preserved binary part whose type differs from its extension's default is corrected
+// by a per-part `<Override>` in {@link contentTypeOverrides}.
+function contentTypeDefaults(extensionDefaults) {
+    return [...extensionDefaults.values()]
+        .map(({ extension, contentType }) => defaultType(extension, contentType))
+        .join('');
+}
+// The per-part `<Override>` declarations, in canonical package order: workbook, worksheets, tables,
+// drawings, comments, the threaded-comment parts, each pivot's three parts, theme, styles, the optional
+// shared strings and threaded-comment person registry, the doc-props pair, then any preserved part whose
+// content type its extension's `<Default>` does not already carry — every `.xml` part (the generic `xml`
+// default never matches a real part type) and any binary part sharing an extension with a differently-typed
+// sibling (a `vbaProjectSignature.bin` next to a `vbaProject.bin`), which a lone extension default would
+// otherwise mis-type.
+function contentTypeOverrides(sheetCount, tables, drawingNumbers, commentNumbers, hasSharedStrings, preservedParts, pivots, preservedWorkbookRefs, extensionDefaults, threadedCommentNumbers, hasPersons) {
+    const preservedOverrides = preservedParts
+        // A preserved theme lands at the fixed theme path, whose override is already in the list below —
+        // and OPC forbids declaring the same PartName twice. The fixed declaration is the right one to
+        // keep: the part reached the model through a `.../theme` relationship, so its type is the theme
+        // type whatever the source package happened to declare.
+        .filter((part) => part.path !== THEME_PART_PATH)
+        .filter((part) => extensionDefaults.get(extensionOf(part.path).toLowerCase())?.contentType !==
+        part.contentType)
+        .map((part) => override(`/${part.path}`, part.contentType));
+    return [
+        override('/xl/workbook.xml', isMacroEnabled(preservedWorkbookRefs) ? CT.macroEnabledWorkbook : CT.workbook),
+        ...Array.from({ length: sheetCount }, (_, i) => override(`/xl/worksheets/sheet${i + 1}.xml`, CT.worksheet)),
+        ...tables.map(({ number }) => override(`/xl/tables/table${number}.xml`, CT.table)),
+        ...drawingNumbers.map((number) => override(`/xl/drawings/drawing${number}.xml`, CT.drawing)),
+        ...commentNumbers.map((number) => override(`/xl/comments${number}.xml`, CT.comments)),
+        ...threadedCommentNumbers.map((number) => override(`/xl/threadedComments/threadedComment${number}.xml`, CT.threadedComments)),
+        ...pivots.map(({ number }) => override(`/xl/pivotTables/pivotTable${number}.xml`, CT.pivotTable)),
+        ...pivots.map(({ number }) => override(`/xl/pivotCache/pivotCacheDefinition${number}.xml`, CT.pivotCacheDefinition)),
+        ...pivots.map(({ number }) => override(`/xl/pivotCache/pivotCacheRecords${number}.xml`, CT.pivotCacheRecords)),
+        override(`/${THEME_PART_PATH}`, CT.theme),
+        override('/xl/styles.xml', CT.styles),
+        ...(hasSharedStrings ? [override('/xl/sharedStrings.xml', CT.sharedStrings)] : []),
+        ...(hasPersons ? [override('/xl/persons/person.xml', CT.person)] : []),
+        override('/docProps/core.xml', CT.core),
+        override('/docProps/app.xml', CT.app),
+        ...preservedOverrides,
+    ].join('');
+}
+function override(partName, contentType) {
+    return `<Override PartName="${partName}" ContentType="${contentType}"/>`;
+}
+// A `<Default>` content-type declaration binding a file extension to the type every part with that
+// extension carries — the extension-level counterpart to {@link override}'s per-part declaration.
+function defaultType(extension, contentType) {
+    return `<Default Extension="${extension}" ContentType="${contentType}"/>`;
+}
+// The package root relationships: the three the writer regenerates from the model (the office
+// document and the core/app properties), followed by any preserved root references — customUI ribbon
+// parts, custom properties, a thumbnail — re-declared with fresh ids past the fixed three so a
+// round-trip keeps content wired from `_rels/.rels` that the model does not otherwise emit.
+export function rootRelsXml(rootRefs) {
+    return relationshipsPart([
+        relationship('rId1', REL.officeDocument, 'xl/workbook.xml'),
+        relationship('rId2', REL.coreProps, 'docProps/core.xml'),
+        relationship('rId3', REL.extProps, 'docProps/app.xml'),
+        ...rootRefs.map((ref, i) => relationship(`rId${4 + i}`, ref.relType, escapeAttr(ref.entryPath))),
+    ]);
+}
+export function workbookXml(workbook, preservedRels, pivots) {
+    const sheets = workbook.worksheets;
+    const entries = sheets
+        .map((sheet, i) => {
+        const state = sheet.state === 'visible' ? '' : ` state="${sheet.state}"`;
+        return `<sheet name="${escapeAttr(sheet.name)}" sheetId="${sheet.id}"${state} r:id="rId${i + 1}"/>`;
+    })
+        .join('');
+    return (XML_DECLARATION +
+        `<workbook xmlns="${NS.main}" xmlns:r="${NS.docRels}">` +
+        workbookProtectionXml(workbook) +
+        bookViewsXml(workbook) +
+        `<sheets>${entries}</sheets>` +
+        externalReferencesXml(preservedRels) +
+        definedNamesXml(workbook) +
+        calcPrXml(workbook) +
+        pivotCachesXml(preservedRels, pivots) +
+        workbookExtLstXml(preservedRels) +
+        '</workbook>');
+}
+// `<bookViews>` follows `<workbookProtection>` and precedes `<sheets>` in CT_Workbook order. Unlike
+// every other optional block here it is emitted unconditionally: a consumer restores the document
+// window from this rect and lays the sheet's panes out inside it, so a package without one leaves a
+// frozen split measured against an uninitialised window (see `DEFAULT_WORKBOOK_VIEW`). The
+// visibility and minimised flags are written only when they differ from the schema default, and
+// `activeTab` only for a non-first sheet — exactly the shape Excel writes for an ordinary window.
+function bookViewsXml(workbook) {
+    const view = workbook.view;
+    const activeTab = workbook.activeTabIndex;
+    const attrs = (view.visibility !== undefined && view.visibility !== 'visible'
+        ? ` visibility="${view.visibility}"`
+        : '') +
+        (view.minimized ? ' minimized="1"' : '') +
+        ` xWindow="${view.x}" yWindow="${view.y}" windowWidth="${view.width}" windowHeight="${view.height}"` +
+        (activeTab === 0 ? '' : ` activeTab="${activeTab}"`);
+    return `<bookViews><workbookView${attrs}/></bookViews>`;
+}
+// The `<externalReferences>` element registers each preserved external link (a link to a source
+// workbook), wired to the relationship reaching its `externalLink` part. It follows `<sheets>` in
+// CT_Workbook order and precedes `<definedNames>`; its child order is the `[n]` index a formula or
+// defined name resolves an external cell through, so entries are emitted by their captured
+// `externalReferenceIndex` — keeping every `[1]`, `[2]`, … pointing at the same linked workbook it did
+// before the round-trip. '' when no external link was preserved.
+function externalReferencesXml(preservedRels) {
+    const links = preservedRels
+        .filter((ref) => ref.externalReferenceIndex !== undefined)
+        .sort((a, b) => a.externalReferenceIndex - b.externalReferenceIndex);
+    if (links.length === 0)
+        return '';
+    const entries = links.map((ref) => `<externalReference r:id="${ref.relId}"/>`).join('');
+    return `<externalReferences>${entries}</externalReferences>`;
+}
+// The workbook-body `<x14:slicerCaches>` extension that registers each preserved slicer cache, wired
+// to the relationship reaching its cache part. Slicer caches (unlike pivot caches, which register in
+// `<pivotCaches>`) live only in this extension block, so re-emitting it is what lets Excel rediscover
+// the slicers. `<extLst>` is the final child of CT_Workbook. '' when no slicer cache was preserved.
+function workbookExtLstXml(preservedRels) {
+    const caches = preservedRels.filter((ref) => ref.relType.endsWith('/slicerCache'));
+    if (caches.length === 0)
+        return '';
+    const entries = caches.map((ref) => `<x14:slicerCache r:id="${ref.relId}"/>`).join('');
+    return `<extLst>${x14Ext(SLICER_CACHES_EXT_URI, `<x14:slicerCaches>${entries}</x14:slicerCaches>`)}</extLst>`;
+}
+// The `<pivotCaches>` element registers each pivot cache under the `cacheId` a pivot table resolves
+// its cache through, wired to the relationship that reaches the cache definition. It follows
+// `<calcPr>` in CT_Workbook order and carries both preserved caches (passed through from a read file)
+// and caches the writer generated for modeled pivot tables. A slicer cache (no `cacheId`) is
+// registered in a workbook extension block, not here, so it is skipped.
+function pivotCachesXml(preservedRels, pivots) {
+    const preserved = preservedRels
+        .filter((ref) => ref.pivotCacheId !== undefined)
+        .map((ref) => `<pivotCache cacheId="${escapeAttr(ref.pivotCacheId)}" r:id="${ref.relId}"/>`);
+    const generated = pivots.map((pivot) => `<pivotCache cacheId="${escapeAttr(pivot.cacheId)}" r:id="${pivot.workbookRelId}"/>`);
+    const entries = [...preserved, ...generated];
+    if (entries.length === 0)
+        return '';
+    return `<pivotCaches>${entries.join('')}</pivotCaches>`;
+}
+// `<workbookProtection>` precedes `<sheets>` in CT_Workbook order. It re-emits the workbook's
+// structure/window lock flags (each written only when true, so an unlocked aspect stays absent) and
+// the preserved password/agile-hash credential attributes verbatim. Emitted only when the workbook
+// actually declares protection — the flags or a credential — so an unprotected workbook stays clean.
+function workbookProtectionXml(workbook) {
+    const p = workbook.protection;
+    if (p === undefined)
+        return '';
+    const attrs = [];
+    if (p.lockStructure)
+        attrs.push('lockStructure="1"');
+    if (p.lockWindows)
+        attrs.push('lockWindows="1"');
+    if (p.lockRevision)
+        attrs.push('lockRevision="1"');
+    for (const key of WORKBOOK_PROTECTION_CREDENTIAL_ATTRS) {
+        const value = p.credentials?.[key];
+        if (value !== undefined)
+            attrs.push(`${key}="${escapeAttr(value)}"`);
+    }
+    if (attrs.length === 0)
+        return '';
+    return `<workbookProtection ${attrs.join(' ')}/>`;
+}
+// The `calcId` desktop Excel stamps into `<calcPr>` — the build number of the calc engine that last
+// evaluated the workbook. Consumers only compare it to decide whether cached results are stale; we
+// emit a fixed recent value alongside `fullCalcOnLoad`, which already forces a full recalculation.
+const EXCEL_CALC_ID = '171027';
+// `<calcPr>` follows `<definedNames>` in CT_Workbook order and carries the calculation settings.
+// Today the model exposes a single one: `fullCalcOnLoad`, which tells the consumer to recalculate
+// every formula on open instead of trusting the cached results. Emitted only when set, so an
+// unmarked workbook keeps the element (and its `calcId`) out of the file entirely.
+function calcPrXml(workbook) {
+    return workbook.fullCalcOnLoad ? `<calcPr calcId="${EXCEL_CALC_ID}" fullCalcOnLoad="1"/>` : '';
+}
+// The `<definedNames>` block follows `<sheets>` in the schema. A sheet-scoped name carries a
+// `localSheetId` — the 0-based position of its sheet among the `<sheet>` entries, NOT the sheet's
+// own id — so the index is resolved against the worksheet order here. The refersTo formula is the
+// element's text content, run through the same `_xlfn.` function mangling the writer applies to a
+// cell formula so a name defined as a modern function (a LAMBDA, an XLOOKUP-based name) is stored
+// under the prefix Excel requires; a plain reference has no function call and passes through
+// untouched. Only names that are actually set emit anything.
+function definedNamesXml(workbook) {
+    const sheets = workbook.worksheets;
+    const userEntries = workbook.definedNames.map((name) => {
+        const scopeAttr = name.scope === undefined
+            ? ''
+            : ` localSheetId="${sheets.findIndex((sheet) => sheet.name === name.scope)}"`;
+        const commentAttr = name.comment === undefined ? '' : ` comment="${escapeAttr(name.comment)}"`;
+        const hiddenAttr = name.hidden ? ' hidden="1"' : '';
+        return (`<definedName name="${escapeAttr(name.name)}"${scopeAttr}${commentAttr}${hiddenAttr}>` +
+            `${escapeText(mangleFormula(name.refersTo))}</definedName>`);
+    });
+    // Every sheet-level autofilter contributes the hidden, sheet-scoped `_FilterDatabase` built-in that
+    // Excel derives from its range. The reader drops these on load and rebuilds them from the sheet's
+    // `<autoFilter>`, so `Worksheet.autoFilter` stays the single source of truth and a round-trip never
+    // duplicates them.
+    const filterEntries = sheets.flatMap((sheet, index) => sheet.autoFilter === undefined
+        ? []
+        : [
+            `<definedName name="_xlnm._FilterDatabase" localSheetId="${index}" hidden="1">` +
+                `${escapeText(filterDatabaseRefersTo(sheet.name, sheet.autoFilter.ref))}</definedName>`,
+        ]);
+    const entries = [...userEntries, ...filterEntries];
+    if (entries.length === 0)
+        return '';
+    return `<definedNames>${entries.join('')}</definedNames>`;
+}
+// Build the sheet-qualified, fully-absolute reference a `_FilterDatabase` name carries
+// (`'Sheet 1'!$A$1:$C$10`) from a sheet name and its already-canonical `A1:C10` autofilter range.
+function filterDatabaseRefersTo(sheetName, range) {
+    const absolute = range.replace(/([A-Z]+)(\d+)/g, '$$$1$$$2');
+    return `${quoteSheetName(sheetName)}!${absolute}`;
+}
+// The relationships the workbook part always carries after its per-sheet rels: `styles.xml` and
+// `theme/theme1.xml`. Their count anchors every downstream rel id — `sharedStrings.xml` and the
+// threaded-comment person registry (when present), then the preserved/pivot caches — so `write.ts`
+// derives its `workbookRelBase` from this same constant rather than repeating the literal and risking
+// drift.
+export const FIXED_WORKBOOK_REL_COUNT = 2;
+export function workbookRelsXml(sheetCount, hasSharedStrings, personsRelId, preservedRels, pivots) {
+    return relationshipsPart([
+        ...Array.from({ length: sheetCount }, (_, i) => relationship(`rId${i + 1}`, REL.worksheet, `worksheets/sheet${i + 1}.xml`)),
+        relationship(`rId${sheetCount + 1}`, REL.styles, 'styles.xml'),
+        relationship(`rId${sheetCount + FIXED_WORKBOOK_REL_COUNT}`, REL.theme, relativePartPath('xl/workbook.xml', THEME_PART_PATH)),
+        ...(hasSharedStrings
+            ? [
+                relationship(`rId${sheetCount + FIXED_WORKBOOK_REL_COUNT + 1}`, REL.sharedStrings, 'sharedStrings.xml'),
+            ]
+            : []),
+        // The threaded-comment identity registry every conversation on every sheet resolves its authors and
+        // @mentions through. Workbook-level and singular, so this one relationship serves all the sheets.
+        ...(personsRelId === null
+            ? []
+            : [relationship(personsRelId, REL.person, 'persons/person.xml')]),
+        // A preserved cache's target is package-absolute; express it relative to the workbook part.
+        ...preservedRels.map((ref) => relationship(ref.relId, ref.relType, escapeAttr(relativePartPath('xl/workbook.xml', ref.entryPath)))),
+        // A generated pivot cache's workbook relationship reaches its cache definition part.
+        ...pivots.map((pivot) => relationship(pivot.workbookRelId, REL.pivotCacheDefinition, `pivotCache/pivotCacheDefinition${pivot.number}.xml`)),
+    ]);
+}
+export function corePropsXml(properties) {
+    const parts = [];
+    if (properties.creator !== undefined) {
+        parts.push(`<dc:creator>${escapeText(properties.creator)}</dc:creator>`);
+    }
+    if (properties.lastModifiedBy !== undefined) {
+        parts.push(`<cp:lastModifiedBy>${escapeText(properties.lastModifiedBy)}</cp:lastModifiedBy>`);
+    }
+    if (properties.created) {
+        parts.push(w3cdtf('created', properties.created));
+    }
+    if (properties.modified) {
+        parts.push(w3cdtf('modified', properties.modified));
+    }
+    return (XML_DECLARATION +
+        `<cp:coreProperties xmlns:cp="${NS.coreProps}" xmlns:dc="${NS.dc}" xmlns:dcterms="${NS.dcterms}" ` +
+        `xmlns:dcmitype="${NS.dcmitype}" xmlns:xsi="${NS.xsi}">` +
+        parts.join('') +
+        '</cp:coreProperties>');
+}
+function w3cdtf(element, date) {
+    return `<dcterms:${element} xsi:type="dcterms:W3CDTF">${date.toISOString()}</dcterms:${element}>`;
+}
+export function appPropsXml() {
+    return (XML_DECLARATION +
+        `<Properties xmlns="${NS.extProps}"><Application>ts-xlsx</Application></Properties>`);
+}

package/dist/io/xlsx/worksheet-xml.d.ts

@@ -0,0 +1,86 @@
+import type { Cell } from '../../core/cell.ts';
+import type { ColumnProperties, RowProperties, Worksheet } from '../../core/worksheet.ts';
+import { type HyperlinkPlan } from './hyperlinks.ts';
+import type { BackgroundPlan, CommentPlan, DrawingPlan, PivotPlan, PreservedReferencePlan, PrinterSettingsPlan, TablePlan, ThreadedCommentPlan } from './package-plan.ts';
+import { type SharedFormulaRole } from './shared-formulas.ts';
+import type { SharedStringTable } from './shared-strings.ts';
+import type { StyleRegistry } from './styles.ts';
+/**
+ * The used-cell extent of a sheet — the top-left/bottom-right grid bounds that fold into the
+ * `<dimension>`. Rows carrying only formatting (a row height, an outline level) do not extend the
+ * used range, matching how Excel records `<dimension>`, so {@link add} ignores them. A fresh extent
+ * holds the `Infinity`/`-Infinity` sentinels; {@link isEmpty} reports that no used cell has been seen.
+ */
+export declare class Extent {
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+    constructor(seed?: Extent);
+    /** Whether no used cell has been folded in yet — the sheet's dimension is then the lone cell `A1`. */
+    get isEmpty(): boolean;
+    /** Fold a rendered row's used-column span into the extent. `minCol` is `Infinity` when the row
+     * carried no cells (only formatting), which extends nothing. */
+    add(row: number, minCol: number, maxCol: number): void;
+}
+/**
+ * A worksheet's eagerly-serialised rows: each row's `<row>` XML tagged with its number (so it merges
+ * into ascending order with the sheet's remaining live rows, whatever order it was committed in), plus
+ * the used-cell {@link Extent} they span. The buffered pass folds that extent into the sheet's dimension.
+ */
+export interface FlushedSheet {
+    readonly rows: ReadonlyArray<{
+        readonly number: number;
+        readonly xml: string;
+    }>;
+    readonly extent: Extent;
+    /**
+     * The deepest row outline level among the flushed rows. Carried across the eviction because
+     * `<sheetFormatPr outlineLevelRow>` is derived from every row on the sheet, and a flushed row's
+     * properties are gone from the model by the time the header is serialised.
+     */
+    readonly maxRowOutlineLevel: number;
+}
+export interface SheetReferences {
+    readonly drawingRelId: string | null;
+    readonly legacyDrawingRelId: string | null;
+    readonly printerSettingsRelId: string | null;
+    readonly backgroundRelId: string | null;
+    readonly legacyDrawingHFRelId: string | null;
+    readonly slicerRelIds: readonly string[];
+}
+export declare function worksheetXml(sheet: Worksheet, tables: readonly TablePlan[], styles: StyleRegistry, references: SheetReferences, hyperlinks: readonly HyperlinkPlan[], sharedStrings: SharedStringTable | null, active: boolean, flushed?: FlushedSheet): string;
+/**
+ * A column's style facets are defaults its cells inherit unless they override them; the writer
+ * composes each cell's full style up front (cell over row over column, per facet) so a cell that
+ * overrides one facet still carries the column's others, rather than silently dropping them. Frozen
+ * once by the streaming writer at its first flush so every eagerly-rendered row sees the same defaults.
+ */
+export declare function buildColumnDefaults(sheet: Worksheet): Map<number, ColumnProperties>;
+/** The whole-sheet context a single row needs to serialise: the column defaults it inherits, the
+ * style/string tables it interns into, the shared-formula roles its cells play, and the collapsed
+ * outline summaries whose toggle it must stamp. The streaming writer supplies empty shared-formula
+ * and collapsed-summary sets, since those are whole-sheet derivations a flushed row cannot join. */
+export interface RowRenderContext {
+    readonly columnDefaults: ReadonlyMap<number, ColumnProperties>;
+    readonly styles: StyleRegistry;
+    readonly sharedStrings: SharedStringTable | null;
+    readonly sharedRoles: ReadonlyMap<string, SharedFormulaRole>;
+    readonly collapsedSummaries: ReadonlySet<number>;
+}
+/**
+ * Serialise one row to its `<row>` element, or '' when the row has neither data nor its own
+ * formatting. Returns the used-column bounds (`Infinity`/`-Infinity` when nothing was rendered) so a
+ * caller can fold them into the sheet dimension. Shared by the buffered sheet pass and the streaming
+ * writer's eager flush, so both emit byte-identical rows.
+ */
+export declare function renderRow(entry: {
+    readonly number: number;
+    readonly cells: readonly Cell[];
+    readonly properties: RowProperties | undefined;
+}, ctx: RowRenderContext): {
+    xml: string;
+    minCol: number;
+    maxCol: number;
+};
+export declare function worksheetRelsXml(tables: readonly TablePlan[], drawing: DrawingPlan | null, comments: CommentPlan | null, threadedComments: ThreadedCommentPlan | null, printerSettings: PrinterSettingsPlan | null, background: BackgroundPlan | null, hyperlinks: readonly HyperlinkPlan[], preservedReferences: readonly PreservedReferencePlan[], pivots: readonly PivotPlan[]): string;