@office-kit/xlsx 0.11.1 → 0.13.0

package/README.md

@@ -262,7 +262,10 @@ common surprise for direct ports:
   that hides a real bug elsewhere).
 - **`setCell(ws, row, col, value)`** is the @office-kit/xlsx equivalent of
   openpyxl's `ws.cell(row=r, column=c, value=v)`. Coordinates are
-  1-based on both sides.
+  1-based on both sides. `value` is mandatory: openpyxl's no-value
+  `ws.cell(row=r, column=c)` returns the cell without touching it, whereas
+  `setCell` writes whatever you pass. Use `ensureCell(ws, row, col)` for the
+  get-or-create behaviour.
 - **`makeBorder({ left: makeSide({ style: 'thin' }) })`** is the
   @office-kit/xlsx equivalent of openpyxl's
   `Border(left=Side(style='thin'))`. Same with `makeFill`, `makeFont`,

package/dist/cell/cell.d.ts

@@ -71,19 +71,51 @@ export declare function setCellValue(c: Cell, value: CellValue): void;
  * path.
  */
 export declare function bindValue(c: Cell, value: number | string | boolean | Date | null): void;
-/** Plain `=A1+B1` style formula. Cached value is optional but recommended for round-trip. */
+/**
+ * Build a formula cell value. Hand it to `setCell` when the write already
+ * carries a style id, so placing a formatted formula stays a single call;
+ * {@link setFormula} is the same thing applied to a cell you already hold.
+ *
+ * A leading `=` is stripped, so `'=SUM(A1:A3)'` and `'SUM(A1:A3)'` are
+ * interchangeable.
+ *
+ * A cached value is optional. Without one, Excel, LibreOffice and Google
+ * Sheets compute the result on open, but viewers that never calculate (Quick
+ * Look, Outlook and SharePoint previews, most thumbnailers) render the cell
+ * empty. Supply one whenever the producer can compute it.
+ */
+export declare function makeFormula(formula: string, opts?: {
+    cachedValue?: FormulaValue['cachedValue'];
+}): FormulaValue;
+/**
+ * Build an array (CSE) formula value spanning `ref`. Belongs on the top-left
+ * cell of the range, since Excel reads `ref` to know how far the result
+ * spreads.
+ */
+export declare function makeArrayFormula(ref: string, formula: string, opts?: {
+    cachedValue?: FormulaValue['cachedValue'];
+}): FormulaValue;
+/**
+ * Build a shared-formula value. The first cell in the group carries the
+ * formula text + `ref`; subsequent cells with the same `si` carry only the
+ * index, and Excel reconstructs their text by shifting the references, so
+ * their `formula` is legitimately empty.
+ */
+export declare function makeSharedFormula(si: number, formula?: string, ref?: string, opts?: {
+    cachedValue?: FormulaValue['cachedValue'];
+}): FormulaValue;
+/**
+ * Plain `A1+B1` style formula, applied in place. Same value as
+ * {@link makeFormula}, for a cell you already hold.
+ */
 export declare function setFormula(c: Cell, formula: string, opts?: {
     cachedValue?: FormulaValue['cachedValue'];
 }): void;
-/** Array (CSE) formula spanning a `ref` range. */
+/** Array (CSE) formula spanning a `ref` range, applied in place. */
 export declare function setArrayFormula(c: Cell, ref: string, formula: string, opts?: {
     cachedValue?: FormulaValue['cachedValue'];
 }): void;
-/**
- * Shared formula. The first cell in the group carries the formula text + ref;
- * subsequent cells with the same `si` carry only the index and Excel
- * reconstructs the formula via reference shifting.
- */
+/** Shared formula, applied in place. See {@link makeSharedFormula}. */
 export declare function setSharedFormula(c: Cell, si: number, formula?: string, ref?: string, opts?: {
     cachedValue?: FormulaValue['cachedValue'];
 }): void;
@@ -115,10 +147,13 @@ export interface DataTableFormulaOpts {
     cachedValue?: FormulaValue['cachedValue'];
 }
 /**
- * Set a data-table formula on a cell. Preserves all the dt-specific attributes
+ * Build a data-table formula value. Preserves all the dt-specific attributes
  * so the writer can re-emit `<f t="dataTable" r1="..." />` verbatim and Excel
- * keeps treating the cell as a Data Table cell.
+ * keeps treating the cell as a Data Table cell. Excel writes these with no
+ * formula text at all, so `formula` may be empty.
  */
+export declare function makeDataTableFormula(formula: string, opts: DataTableFormulaOpts): FormulaValue;
+/** Data-table formula, applied in place. See {@link makeDataTableFormula}. */
 export declare function setDataTableFormula(c: Cell, formula: string, opts: DataTableFormulaOpts): void;
 /** Build a `{ kind: 'error', code }` cell value. */
 export declare function makeErrorValue(code: ExcelErrorCode): {

package/dist/cell/index.d.ts

@@ -1,4 +1,4 @@
 export type { Cell, CellValue, CellValueAsStringOptions, DataTableFormulaOpts, ExcelErrorCode, FormulaKind, FormulaValue, MergedCell, } from './cell.js';
-export { bindValue, cellValueAsBoolean, cellValueAsDate, cellValueAsNumber, cellValueAsPrimitive, cellValueAsString, getCachedFormulaValue, getCoordinate, getFormulaText, isDurationValue, isEmptyCell, isErrorCell, isErrorValue, isFormulaCell, isFormulaValue, isMergedCell, isRichTextCell, isRichTextValue, makeCell, makeDurationValue, makeErrorValue, setArrayFormula, setCellValue, setDataTableFormula, setFormula, setSharedFormula, } from './cell.js';
+export { bindValue, cellValueAsBoolean, cellValueAsDate, cellValueAsNumber, cellValueAsPrimitive, cellValueAsString, getCachedFormulaValue, getCoordinate, getFormulaText, isDurationValue, isEmptyCell, isErrorCell, isErrorValue, isFormulaCell, isFormulaValue, isMergedCell, isRichTextCell, isRichTextValue, makeArrayFormula, makeCell, makeDataTableFormula, makeDurationValue, makeErrorValue, makeFormula, makeSharedFormula, setArrayFormula, setCellValue, setDataTableFormula, setFormula, setSharedFormula, } from './cell.js';
 export type { InlineFont, InlineUnderline, InlineVertAlign, RichText, TextRun, } from './rich-text.js';
 export { makeRichText, makeTextRun, richTextToString } from './rich-text.js';

package/dist/{cell-BucgGwl3.mjs → cell-Df3cKRIl.mjs}

@@ -1,6 +1,6 @@
 import { o as OpenXmlSchemaError } from "./exceptions-D-CFwxgm.mjs";
-import { a as columnLetterFromIndex, n as MAX_ROW, t as MAX_COL } from "./coordinate-96Ecci4d.mjs";
-import { t as ERROR_CODES } from "./inference-BrI9uIY4.mjs";
+import { a as columnLetterFromIndex, n as MAX_ROW, t as MAX_COL } from "./coordinate-Bt5Gni2I.mjs";
+import { i as startsWithEquals, r as normalizeFormulaText, t as ERROR_CODES } from "./inference-BMvv9cUY.mjs";
 //#region src/cell/rich-text.ts
 function makeTextRun(text, font) {
 	if (typeof text !== "string") throw new OpenXmlSchemaError("makeTextRun: text must be a string");
@@ -61,8 +61,8 @@ function setCellValue(c, value) {
 */
 function bindValue(c, value) {
 	if (typeof value === "string") {
-		if (value.length > 0 && value.charCodeAt(0) === 61) {
-			setFormula(c, value.slice(1));
+		if (startsWithEquals(value)) {
+			setFormula(c, value);
 			return;
 		}
 		if (ERROR_CODES.has(value)) {
@@ -77,51 +77,89 @@ function bindValue(c, value) {
 	}
 	c.value = value;
 }
-/** Plain `=A1+B1` style formula. Cached value is optional but recommended for round-trip. */
-function setFormula(c, formula, opts) {
-	c.value = {
+const requireFormulaText = (fn, formula) => {
+	const text = normalizeFormulaText(formula);
+	if (text.length === 0) throw new OpenXmlSchemaError(`${fn}: formula text must not be empty (got ${JSON.stringify(formula)})`);
+	return text;
+};
+/**
+* Build a formula cell value. Hand it to `setCell` when the write already
+* carries a style id, so placing a formatted formula stays a single call;
+* {@link setFormula} is the same thing applied to a cell you already hold.
+*
+* A leading `=` is stripped, so `'=SUM(A1:A3)'` and `'SUM(A1:A3)'` are
+* interchangeable.
+*
+* A cached value is optional. Without one, Excel, LibreOffice and Google
+* Sheets compute the result on open, but viewers that never calculate (Quick
+* Look, Outlook and SharePoint previews, most thumbnailers) render the cell
+* empty. Supply one whenever the producer can compute it.
+*/
+function makeFormula(formula, opts) {
+	return Object.freeze({
 		kind: "formula",
 		t: "normal",
-		formula,
+		formula: requireFormulaText("makeFormula", formula),
 		...opts?.cachedValue !== void 0 ? { cachedValue: opts.cachedValue } : {}
-	};
+	});
 }
-/** Array (CSE) formula spanning a `ref` range. */
-function setArrayFormula(c, ref, formula, opts) {
-	c.value = {
+/**
+* Build an array (CSE) formula value spanning `ref`. Belongs on the top-left
+* cell of the range, since Excel reads `ref` to know how far the result
+* spreads.
+*/
+function makeArrayFormula(ref, formula, opts) {
+	return Object.freeze({
 		kind: "formula",
 		t: "array",
-		formula,
+		formula: requireFormulaText("makeArrayFormula", formula),
 		ref,
 		...opts?.cachedValue !== void 0 ? { cachedValue: opts.cachedValue } : {}
-	};
+	});
 }
 /**
-* Shared formula. The first cell in the group carries the formula text + ref;
-* subsequent cells with the same `si` carry only the index and Excel
-* reconstructs the formula via reference shifting.
+* Build a shared-formula value. The first cell in the group carries the
+* formula text + `ref`; subsequent cells with the same `si` carry only the
+* index, and Excel reconstructs their text by shifting the references, so
+* their `formula` is legitimately empty.
 */
-function setSharedFormula(c, si, formula, ref, opts) {
-	if (!Number.isInteger(si) || si < 0) throw new OpenXmlSchemaError(`setSharedFormula: si must be a non-negative integer; got ${si}`);
-	c.value = {
+function makeSharedFormula(si, formula, ref, opts) {
+	if (!Number.isInteger(si) || si < 0) throw new OpenXmlSchemaError(`makeSharedFormula: si must be a non-negative integer; got ${si}`);
+	return Object.freeze({
 		kind: "formula",
 		t: "shared",
-		formula: formula ?? "",
+		formula: formula === void 0 ? "" : normalizeFormulaText(formula),
 		si,
 		...ref !== void 0 ? { ref } : {},
 		...opts?.cachedValue !== void 0 ? { cachedValue: opts.cachedValue } : {}
-	};
+	});
+}
+/**
+* Plain `A1+B1` style formula, applied in place. Same value as
+* {@link makeFormula}, for a cell you already hold.
+*/
+function setFormula(c, formula, opts) {
+	c.value = makeFormula(formula, opts);
+}
+/** Array (CSE) formula spanning a `ref` range, applied in place. */
+function setArrayFormula(c, ref, formula, opts) {
+	c.value = makeArrayFormula(ref, formula, opts);
+}
+/** Shared formula, applied in place. See {@link makeSharedFormula}. */
+function setSharedFormula(c, si, formula, ref, opts) {
+	c.value = makeSharedFormula(si, formula, ref, opts);
 }
 /**
-* Set a data-table formula on a cell. Preserves all the dt-specific attributes
+* Build a data-table formula value. Preserves all the dt-specific attributes
 * so the writer can re-emit `<f t="dataTable" r1="..." />` verbatim and Excel
-* keeps treating the cell as a Data Table cell.
+* keeps treating the cell as a Data Table cell. Excel writes these with no
+* formula text at all, so `formula` may be empty.
 */
-function setDataTableFormula(c, formula, opts) {
-	c.value = {
+function makeDataTableFormula(formula, opts) {
+	return Object.freeze({
 		kind: "formula",
 		t: "dataTable",
-		formula,
+		formula: normalizeFormulaText(formula),
 		ref: opts.ref,
 		...opts.r1 !== void 0 ? { r1: opts.r1 } : {},
 		...opts.r2 !== void 0 ? { r2: opts.r2 } : {},
@@ -132,7 +170,11 @@ function setDataTableFormula(c, formula, opts) {
 		...opts.aca !== void 0 ? { aca: opts.aca } : {},
 		...opts.ca !== void 0 ? { ca: opts.ca } : {},
 		...opts.cachedValue !== void 0 ? { cachedValue: opts.cachedValue } : {}
-	};
+	});
+}
+/** Data-table formula, applied in place. See {@link makeDataTableFormula}. */
+function setDataTableFormula(c, formula, opts) {
+	c.value = makeDataTableFormula(formula, opts);
 }
 /** Build a `{ kind: 'error', code }` cell value. */
 function makeErrorValue(code) {
@@ -315,6 +357,6 @@ function cellValueAsPrimitive(v) {
 	return null;
 }
 //#endregion
-export { setCellValue as C, makeRichText as D, setSharedFormula as E, makeTextRun as O, setArrayFormula as S, setFormula as T, isRichTextCell as _, cellValueAsPrimitive as a, makeDurationValue as b, getCoordinate as c, isEmptyCell as d, isErrorCell as f, isMergedCell as g, isFormulaValue as h, cellValueAsNumber as i, richTextToString as k, getFormulaText as l, isFormulaCell as m, cellValueAsBoolean as n, cellValueAsString as o, isErrorValue as p, cellValueAsDate as r, getCachedFormulaValue as s, bindValue as t, isDurationValue as u, isRichTextValue as v, setDataTableFormula as w, makeErrorValue as x, makeCell as y };
+export { setSharedFormula as A, makeErrorValue as C, setCellValue as D, setArrayFormula as E, makeTextRun as M, richTextToString as N, setDataTableFormula as O, makeDurationValue as S, makeSharedFormula as T, isRichTextCell as _, cellValueAsPrimitive as a, makeCell as b, getCoordinate as c, isEmptyCell as d, isErrorCell as f, isMergedCell as g, isFormulaValue as h, cellValueAsNumber as i, makeRichText as j, setFormula as k, getFormulaText as l, isFormulaCell as m, cellValueAsBoolean as n, cellValueAsString as o, isErrorValue as p, cellValueAsDate as r, getCachedFormulaValue as s, bindValue as t, isDurationValue as u, isRichTextValue as v, makeFormula as w, makeDataTableFormula as x, makeArrayFormula as y };
 
-//# sourceMappingURL=cell-BucgGwl3.mjs.map
+//# sourceMappingURL=cell-Df3cKRIl.mjs.map

package/dist/cell-Df3cKRIl.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cell-Df3cKRIl.mjs","names":[],"sources":["../src/cell/rich-text.ts","../src/cell/cell.ts"],"sourcesContent":["// Inline rich-text runs.\n//\n// A rich-text cell value is `{ kind: 'rich-text', runs }`. Each run is\n// a string segment with an optional InlineFont describing the in-line\n// formatting (font name, size, bold / italic / underline, colour, …).\n// Run-level fields use OOXML's short attribute names (`sz`, `b`, `i`,\n// `u`) so the writer can splice them into `<rPr>` directly without\n// renaming.\n\nimport type { Color } from '../styles/colors.js';\nimport { OpenXmlSchemaError } from '../utils/exceptions.js';\n\n/** Underline styles per openpyxl's cell-level NestedNoneSet. */\nexport type InlineUnderline = 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';\n\nexport type InlineVertAlign = 'baseline' | 'superscript' | 'subscript';\n\nexport interface InlineFont {\n  readonly name?: string;\n  readonly sz?: number;\n  readonly b?: boolean;\n  readonly i?: boolean;\n  readonly u?: InlineUnderline;\n  readonly strike?: boolean;\n  readonly outline?: boolean;\n  readonly shadow?: boolean;\n  readonly condense?: boolean;\n  readonly extend?: boolean;\n  readonly vertAlign?: InlineVertAlign;\n  readonly color?: Color;\n  readonly family?: number;\n  readonly charset?: number;\n  readonly scheme?: 'major' | 'minor';\n}\n\nexport interface TextRun {\n  readonly text: string;\n  readonly font?: InlineFont;\n}\n\n/** A frozen array of TextRuns. The shared cell value shape under `kind: 'rich-text'`. */\nexport type RichText = ReadonlyArray<TextRun>;\n\nexport function makeTextRun(text: string, font?: InlineFont): TextRun {\n  if (typeof text !== 'string') {\n    throw new OpenXmlSchemaError('makeTextRun: text must be a string');\n  }\n  return Object.freeze(font !== undefined ? { text, font } : { text });\n}\n\nexport function makeRichText(runs: ReadonlyArray<TextRun | { text: string; font?: InlineFont }>): RichText {\n  const out = runs.map((r) => (Object.isFrozen(r) ? (r as TextRun) : makeTextRun(r.text, r.font)));\n  return Object.freeze(out);\n}\n\n/**\n * Concatenate the plain-text content of a rich-text value (rich-text\n * read paths often want the raw text without formatting).\n */\nexport function richTextToString(rt: RichText): string {\n  let out = '';\n  for (const r of rt) out += r.text;\n  return out;\n}\n","// Cell value model. Mirrors openpyxl/openpyxl/cell/cell.py.\n//\n// A Cell is a plain mutable object: the worksheet stores millions of these, so\n// per-cell freezes / spreads aren't viable on the hot path. The public surface\n// stays small — makeCell + getCoordinate + targeted setters — and uses\n// discriminated unions for the special CellValue shapes (formula, rich text,\n// duration, error).\n\nimport { columnLetterFromIndex, MAX_COL, MAX_ROW } from '../utils/coordinate.js';\nimport { OpenXmlSchemaError } from '../utils/exceptions.js';\nimport { normalizeFormulaText, startsWithEquals } from '../utils/formula-text.js';\nimport { ERROR_CODES } from '../utils/inference.js';\nimport { type RichText, richTextToString } from './rich-text.js';\n\n/** Excel error tokens. */\nexport type ExcelErrorCode = '#NULL!' | '#DIV/0!' | '#VALUE!' | '#REF!' | '#NAME?' | '#NUM!' | '#N/A' | '#GETTING_DATA';\n\n/** Formula sub-kind — drives the OOXML `<f t=\"…\">` attribute. */\nexport type FormulaKind = 'normal' | 'array' | 'shared' | 'dataTable';\n\nexport interface FormulaValue {\n  readonly kind: 'formula';\n  readonly formula: string;\n  readonly t: FormulaKind;\n  /** Cached value Excel last computed for the cell, used when `data_only` reads it back. */\n  readonly cachedValue?: number | string | boolean;\n  /** Range string (`\"A1:A10\"`) for array / shared / dataTable formulas. */\n  readonly ref?: string;\n  /** Shared-formula index. */\n  readonly si?: number;\n  /** Data-table specific fields (mirrors openpyxl DataTableFormula). */\n  readonly r1?: string;\n  readonly r2?: string;\n  readonly dt2D?: boolean;\n  readonly dtr?: boolean;\n  readonly del1?: boolean;\n  readonly del2?: boolean;\n  readonly aca?: boolean;\n  readonly ca?: boolean;\n}\n\nexport type CellValue =\n  | number\n  | string\n  | boolean\n  | Date\n  | { kind: 'duration'; ms: number }\n  | { kind: 'error'; code: ExcelErrorCode }\n  | { kind: 'rich-text'; runs: RichText }\n  | FormulaValue\n  | null;\n\nexport interface Cell {\n  /** 1-based row index. */\n  row: number;\n  /** 1-based column index. */\n  col: number;\n  /** Effective cell value. `null` represents an empty cell. */\n  value: CellValue;\n  /** Index into Workbook.styles.cellXfs. 0 = default. */\n  styleId: number;\n  /** Optional reference to a Hyperlink registered on the worksheet. */\n  hyperlinkId?: number;\n  /** Optional reference to a Comment registered on the worksheet. */\n  commentId?: number;\n}\n\n/** Marker subtype for the placeholder cells inside a merged range (top-left holds the value). */\nexport interface MergedCell extends Cell {\n  merged: true;\n}\n\nconst validateCoord = (row: number, col: number): void => {\n  if (!Number.isInteger(row) || row < 1 || row > MAX_ROW) {\n    throw new OpenXmlSchemaError(`Cell row ${row} out of range [1, ${MAX_ROW}]`);\n  }\n  if (!Number.isInteger(col) || col < 1 || col > MAX_COL) {\n    throw new OpenXmlSchemaError(`Cell col ${col} out of range [1, ${MAX_COL}]`);\n  }\n};\n\n/** Build a fresh Cell. Validates coordinates against the OOXML grid bounds. */\nexport function makeCell(row: number, col: number, value: CellValue = null, styleId = 0): Cell {\n  validateCoord(row, col);\n  return { row, col, value, styleId };\n}\n\n/** Format a Cell's coordinate as the canonical \"A1\" string. */\nexport function getCoordinate(c: Cell): string {\n  return `${columnLetterFromIndex(c.col)}${c.row}`;\n}\n\n/**\n * Direct value setter. No type inference, no validation beyond the union — the\n * caller is in charge. Use {@link bindValue} for the \"do what I mean\" path.\n */\nexport function setCellValue(c: Cell, value: CellValue): void {\n  c.value = value;\n}\n\n/**\n * \"Smart\" setter: infers the cell value from a JS runtime value.\n * - `string` starting with `=` → formula\n * - `string` matching an Excel error token → error variant\n * - other primitives / Date / null pass through verbatim\n *\n * Intentionally not the default — explicit is clearer for typed code, and\n * inferring on every write costs measurable time on the worksheet write hot\n * path.\n */\nexport function bindValue(c: Cell, value: number | string | boolean | Date | null): void {\n  if (typeof value === 'string') {\n    if (startsWithEquals(value)) {\n      setFormula(c, value);\n      return;\n    }\n    if (ERROR_CODES.has(value)) {\n      c.value = { kind: 'error', code: value as ExcelErrorCode };\n      return;\n    }\n    c.value = value;\n    return;\n  }\n  c.value = value;\n}\n\n// ---- formula values --------------------------------------------------------\n\n// A `<f>` with no text is the shape Excel reports as damaged, and `'='` on its\n// own normalises to exactly that, so the kinds whose text is required reject it\n// here rather than at save time.\nconst requireFormulaText = (fn: string, formula: string): string => {\n  const text = normalizeFormulaText(formula);\n  if (text.length === 0) {\n    throw new OpenXmlSchemaError(`${fn}: formula text must not be empty (got ${JSON.stringify(formula)})`);\n  }\n  return text;\n};\n\n/**\n * Build a formula cell value. Hand it to `setCell` when the write already\n * carries a style id, so placing a formatted formula stays a single call;\n * {@link setFormula} is the same thing applied to a cell you already hold.\n *\n * A leading `=` is stripped, so `'=SUM(A1:A3)'` and `'SUM(A1:A3)'` are\n * interchangeable.\n *\n * A cached value is optional. Without one, Excel, LibreOffice and Google\n * Sheets compute the result on open, but viewers that never calculate (Quick\n * Look, Outlook and SharePoint previews, most thumbnailers) render the cell\n * empty. Supply one whenever the producer can compute it.\n */\nexport function makeFormula(\n  formula: string,\n  opts?: { cachedValue?: FormulaValue['cachedValue'] },\n): FormulaValue {\n  return Object.freeze({\n    kind: 'formula',\n    t: 'normal',\n    formula: requireFormulaText('makeFormula', formula),\n    ...(opts?.cachedValue !== undefined ? { cachedValue: opts.cachedValue } : {}),\n  });\n}\n\n/**\n * Build an array (CSE) formula value spanning `ref`. Belongs on the top-left\n * cell of the range, since Excel reads `ref` to know how far the result\n * spreads.\n */\nexport function makeArrayFormula(\n  ref: string,\n  formula: string,\n  opts?: { cachedValue?: FormulaValue['cachedValue'] },\n): FormulaValue {\n  return Object.freeze({\n    kind: 'formula',\n    t: 'array',\n    formula: requireFormulaText('makeArrayFormula', formula),\n    ref,\n    ...(opts?.cachedValue !== undefined ? { cachedValue: opts.cachedValue } : {}),\n  });\n}\n\n/**\n * Build a shared-formula value. The first cell in the group carries the\n * formula text + `ref`; subsequent cells with the same `si` carry only the\n * index, and Excel reconstructs their text by shifting the references, so\n * their `formula` is legitimately empty.\n */\nexport function makeSharedFormula(\n  si: number,\n  formula?: string,\n  ref?: string,\n  opts?: { cachedValue?: FormulaValue['cachedValue'] },\n): FormulaValue {\n  if (!Number.isInteger(si) || si < 0) {\n    throw new OpenXmlSchemaError(`makeSharedFormula: si must be a non-negative integer; got ${si}`);\n  }\n  return Object.freeze({\n    kind: 'formula',\n    t: 'shared',\n    formula: formula === undefined ? '' : normalizeFormulaText(formula),\n    si,\n    ...(ref !== undefined ? { ref } : {}),\n    ...(opts?.cachedValue !== undefined ? { cachedValue: opts.cachedValue } : {}),\n  });\n}\n\n/**\n * Plain `A1+B1` style formula, applied in place. Same value as\n * {@link makeFormula}, for a cell you already hold.\n */\nexport function setFormula(c: Cell, formula: string, opts?: { cachedValue?: FormulaValue['cachedValue'] }): void {\n  c.value = makeFormula(formula, opts);\n}\n\n/** Array (CSE) formula spanning a `ref` range, applied in place. */\nexport function setArrayFormula(\n  c: Cell,\n  ref: string,\n  formula: string,\n  opts?: { cachedValue?: FormulaValue['cachedValue'] },\n): void {\n  c.value = makeArrayFormula(ref, formula, opts);\n}\n\n/** Shared formula, applied in place. See {@link makeSharedFormula}. */\nexport function setSharedFormula(\n  c: Cell,\n  si: number,\n  formula?: string,\n  ref?: string,\n  opts?: { cachedValue?: FormulaValue['cachedValue'] },\n): void {\n  c.value = makeSharedFormula(si, formula, ref, opts);\n}\n\n/**\n * Excel data-table formula (`<f t=\"dataTable\">`). These appear as the \"What-if\n * Analysis → Data Table\" feature output: a 1- or 2-variable sensitivity grid\n * where the formula references one or two input cells. The wire format mirrors\n * openpyxl's `DataTableFormula`:\n *\n * - `ref`     — inclusive cell range the formula spans.\n * - `r1`, `r2`— input cell coordinates (\"$A$1\" etc.).\n * - `dt2D`    — true for two-variable tables (uses both r1 and r2).\n * - `dtr`     — row-direction flag (true) vs column-direction (false).\n * - `del1`/`del2` — Excel marks one of these true when the\n * corresponding input cell has been deleted; the formula keeps round-tripping\n * so Excel can show the warning state.\n * - `aca`/`ca` — alwaysCalculate / calculate flags.\n */\nexport interface DataTableFormulaOpts {\n  ref: string;\n  r1?: string;\n  r2?: string;\n  dt2D?: boolean;\n  dtr?: boolean;\n  del1?: boolean;\n  del2?: boolean;\n  aca?: boolean;\n  ca?: boolean;\n  cachedValue?: FormulaValue['cachedValue'];\n}\n\n/**\n * Build a data-table formula value. Preserves all the dt-specific attributes\n * so the writer can re-emit `<f t=\"dataTable\" r1=\"...\" />` verbatim and Excel\n * keeps treating the cell as a Data Table cell. Excel writes these with no\n * formula text at all, so `formula` may be empty.\n */\nexport function makeDataTableFormula(formula: string, opts: DataTableFormulaOpts): FormulaValue {\n  return Object.freeze({\n    kind: 'formula',\n    t: 'dataTable',\n    formula: normalizeFormulaText(formula),\n    ref: opts.ref,\n    ...(opts.r1 !== undefined ? { r1: opts.r1 } : {}),\n    ...(opts.r2 !== undefined ? { r2: opts.r2 } : {}),\n    ...(opts.dt2D !== undefined ? { dt2D: opts.dt2D } : {}),\n    ...(opts.dtr !== undefined ? { dtr: opts.dtr } : {}),\n    ...(opts.del1 !== undefined ? { del1: opts.del1 } : {}),\n    ...(opts.del2 !== undefined ? { del2: opts.del2 } : {}),\n    ...(opts.aca !== undefined ? { aca: opts.aca } : {}),\n    ...(opts.ca !== undefined ? { ca: opts.ca } : {}),\n    ...(opts.cachedValue !== undefined ? { cachedValue: opts.cachedValue } : {}),\n  });\n}\n\n/** Data-table formula, applied in place. See {@link makeDataTableFormula}. */\nexport function setDataTableFormula(c: Cell, formula: string, opts: DataTableFormulaOpts): void {\n  c.value = makeDataTableFormula(formula, opts);\n}\n\n// ---- value-shape helpers ---------------------------------------------------\n\n/** Build a `{ kind: 'error', code }` cell value. */\nexport function makeErrorValue(code: ExcelErrorCode): { kind: 'error'; code: ExcelErrorCode } {\n  if (!ERROR_CODES.has(code)) {\n    throw new OpenXmlSchemaError(`makeErrorValue: unknown error code \"${code}\"`);\n  }\n  return Object.freeze({ kind: 'error', code });\n}\n\n/** Build a `{ kind: 'duration', ms }` cell value. */\nexport function makeDurationValue(ms: number): { kind: 'duration'; ms: number } {\n  if (!Number.isFinite(ms)) {\n    throw new OpenXmlSchemaError(`makeDurationValue: ms \"${ms}\" is not finite`);\n  }\n  return Object.freeze({ kind: 'duration', ms });\n}\n\n/** True iff `c.value` is the formula variant. */\nexport function isFormulaCell(c: Cell): boolean {\n  return isFormulaValue(c.value);\n}\n\n/** True iff `c.value` is the rich-text variant. */\nexport function isRichTextCell(c: Cell): boolean {\n  return isRichTextValue(c.value);\n}\n\n/** Returns true iff the cell has no content. */\nexport function isEmptyCell(c: Cell): boolean {\n  return c.value === null;\n}\n\n/**\n * Type guard for `MergedCell` — true iff the cell is a placeholder for a\n * merged-range covered cell (the top-left of a merged range holds the value;\n * the rest are `MergedCell`). Use this to filter merge-placeholders out of\n * value-walking loops.\n */\nexport function isMergedCell(c: Cell): c is MergedCell {\n  return (c as MergedCell).merged === true;\n}\n\n/** Returns true iff the cell holds an Excel error value (`#REF!`, `#NAME?`, …). */\nexport function isErrorCell(c: Cell): boolean {\n  return isErrorValue(c.value);\n}\n\n/**\n * Get the formula text from a formula-bearing cell, or `undefined` for\n * non-formula cells. Equivalent to: isFormulaValue(c.value) ? c.value.formula :\n * undefined but spares callers the type-narrow + member access.\n */\nexport function getFormulaText(c: Cell): string | undefined {\n  return isFormulaValue(c.value) ? c.value.formula : undefined;\n}\n\n/**\n * Get the cached value Excel last computed for a formula cell, or `undefined`\n * for non-formula / uncached cells. Useful for `data_only` read paths that want\n * the displayed result without re-evaluating.\n */\nexport function getCachedFormulaValue(c: Cell): number | string | boolean | undefined {\n  return isFormulaValue(c.value) ? c.value.cachedValue : undefined;\n}\n\n// ---- value-level type guards + coercion ----------------------------------\n\n/** True iff `v` is the formula variant. */\nexport function isFormulaValue(v: CellValue): v is FormulaValue {\n  return typeof v === 'object' && v !== null && (v as { kind?: string }).kind === 'formula';\n}\n\n/** True iff `v` is the rich-text variant. */\nexport function isRichTextValue(v: CellValue): v is { kind: 'rich-text'; runs: RichText } {\n  return typeof v === 'object' && v !== null && (v as { kind?: string }).kind === 'rich-text';\n}\n\n/** True iff `v` is the error variant. */\nexport function isErrorValue(v: CellValue): v is { kind: 'error'; code: ExcelErrorCode } {\n  return typeof v === 'object' && v !== null && (v as { kind?: string }).kind === 'error';\n}\n\n/** True iff `v` is the duration variant. */\nexport function isDurationValue(v: CellValue): v is { kind: 'duration'; ms: number } {\n  return typeof v === 'object' && v !== null && (v as { kind?: string }).kind === 'duration';\n}\n\nexport interface CellValueAsStringOptions {\n  /** Renderer for `Date` cells. Defaults to `d => d.toISOString()`. */\n  dateFormat?: (value: Date) => string;\n  /** Replacement for the `null` cell value. Defaults to `''`. */\n  emptyText?: string;\n}\n\n/**\n * Coerce a CellValue to its plain-string display form. Numbers / booleans\n * convert via `String`; rich text concatenates run text; formulas yield the\n * cached value (or empty string when uncached); errors yield their Excel token;\n * durations yield `\"<ms> ms\"` with no formatting; Dates yield\n * `Date.toISOString()`; `null` yields `\"\"`.\n *\n * Pass `opts.dateFormat` to override the Date renderer (e.g. a locale-specific\n * format) and `opts.emptyText` to substitute a different placeholder for\n * `null` cells.\n */\nexport function cellValueAsString(v: CellValue, opts?: CellValueAsStringOptions): string {\n  const emptyText = opts?.emptyText ?? '';\n  if (v === null) return emptyText;\n  if (typeof v === 'string') return v;\n  if (typeof v === 'number' || typeof v === 'boolean') return String(v);\n  if (v instanceof Date) return opts?.dateFormat ? opts.dateFormat(v) : v.toISOString();\n  if (isRichTextValue(v)) return richTextToString(v.runs);\n  if (isFormulaValue(v)) {\n    if (v.cachedValue === undefined) return '';\n    return typeof v.cachedValue === 'string' ? v.cachedValue : String(v.cachedValue);\n  }\n  if (isErrorValue(v)) return v.code;\n  if (isDurationValue(v)) return `${v.ms} ms`;\n  return '';\n}\n\n/**\n * Coerce a CellValue to `boolean | undefined`. Booleans pass through; `'TRUE'`\n * / `'true'` and `'FALSE'` / `'false'` (case-insensitive) parse to true /\n * false; numbers yield `false` for 0 and `true` for any other finite value\n * (matching Excel's truthy-number coercion); formula cells return their cached\n * boolean if any. Everything else (null, Date, error, duration, rich-text,\n * non-bool strings) yields `undefined`.\n */\nexport function cellValueAsBoolean(v: CellValue): boolean | undefined {\n  if (typeof v === 'boolean') return v;\n  if (typeof v === 'number') {\n    if (!Number.isFinite(v)) return undefined;\n    return v !== 0;\n  }\n  if (typeof v === 'string') {\n    const lc = v.toLowerCase();\n    if (lc === 'true') return true;\n    if (lc === 'false') return false;\n    return undefined;\n  }\n  if (isFormulaValue(v) && typeof v.cachedValue === 'boolean') return v.cachedValue;\n  return undefined;\n}\n\n/**\n * Coerce a CellValue to a `Date` when one is meaningful. Pass-through for\n * `Date`-typed values; ISO-8601 strings (anything `new Date(s)` parses to a\n * finite time) round-trip; durations are interpreted as `new Date(ms)`.\n * Numbers, booleans, formulas, errors, rich text, and null all return\n * `undefined` — this helper does **not** apply the Excel-serial-to-Date\n * conversion (use `excelToDate` for that).\n */\nexport function cellValueAsDate(v: CellValue): Date | undefined {\n  if (v instanceof Date) return v;\n  if (typeof v === 'string') {\n    if (v === '') return undefined;\n    const t = Date.parse(v);\n    if (!Number.isFinite(t)) return undefined;\n    return new Date(t);\n  }\n  if (isDurationValue(v)) return new Date(v.ms);\n  return undefined;\n}\n\n/**\n * Coerce a CellValue to a number when one is meaningful. Booleans yield 0/1;\n * numeric strings parse via `Number(s)`; rich-text concats then parses;\n * formulas with a numeric cached value pass through. Returns `undefined` when\n * there's no sensible numeric reading (text strings, errors, dates, durations,\n * null, empty).\n */\nexport function cellValueAsNumber(v: CellValue): number | undefined {\n  if (v === null) return undefined;\n  if (typeof v === 'number') return Number.isFinite(v) ? v : undefined;\n  if (typeof v === 'boolean') return v ? 1 : 0;\n  if (typeof v === 'string') {\n    if (v === '') return undefined;\n    const n = Number(v);\n    return Number.isFinite(n) ? n : undefined;\n  }\n  if (isFormulaValue(v) && typeof v.cachedValue === 'number') return v.cachedValue;\n  return undefined;\n}\n\n/**\n * Map a CellValue to the most natural JS primitive for display / export.\n * Unlike `cellValueAsString`/`cellValueAsNumber`/etc., which each force a\n * single target type and return `undefined` when the value can't be coerced,\n * this returns whatever primitive best represents the union variant:\n *\n * - `null` → `null`\n * - `string` / `number` / `boolean` / `Date` → passthrough\n * - rich text → joined run text (`string`)\n * - formula → recursive on `cachedValue` (`null` when uncached)\n * - error → error code (`string`)\n * - duration → `ms` (`number`)\n */\nexport function cellValueAsPrimitive(v: CellValue): string | number | boolean | Date | null {\n  if (v === null) return null;\n  if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') return v;\n  if (v instanceof Date) return v;\n  if (isRichTextValue(v)) return richTextToString(v.runs);\n  if (isFormulaValue(v)) {\n    return v.cachedValue === undefined ? null : v.cachedValue;\n  }\n  if (isErrorValue(v)) return v.code;\n  if (isDurationValue(v)) return v.ms;\n  return null;\n}\n"],"mappings":"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"}

package/dist/{cell-style-DuvS_Lsg.mjs → cell-style-BFmJOmcx.mjs}

@@ -1,5 +1,5 @@
 import { o as OpenXmlSchemaError } from "./exceptions-D-CFwxgm.mjs";
-import { _n as colorToHex, bt as setCell, sn as parseRange, wn as makeColor } from "./worksheet-C5Ensf_j.mjs";
+import { Tn as makeColor, cn as parseRange, vn as colorToHex, y as ensureCell } from "./worksheet-4xW-i8j9.mjs";
 //#region src/utils/stable-stringify.ts
 const sortKeysReplacer = (_key, value) => {
 	if (value === null || typeof value !== "object" || Array.isArray(value)) return value;
@@ -655,6 +655,44 @@ function defaultCellXf() {
 		numFmtId: 0
 	});
 }
+/**
+* Resolve a style spec to the CellXf fields it sets, registering each component
+* in its pool. The result is a patch, not a whole xf: axes absent from `spec`
+* are absent here too, so a caller can either spread it over
+* {@link defaultCellXf} for a complete style or over an existing xf to merge.
+*
+* Every path that turns a user-facing style spec into an xf goes through this,
+* so a new axis on {@link CellStyleSpec} reaches the modelled writer and the
+* streaming write-only writer together.
+*/
+function buildXfPatch(ss, spec) {
+	const patch = {};
+	if (spec.font !== void 0) {
+		patch.fontId = addFont(ss, spec.font);
+		patch.applyFont = true;
+	}
+	if (spec.fill !== void 0) {
+		patch.fillId = addFill(ss, spec.fill);
+		patch.applyFill = true;
+	}
+	if (spec.border !== void 0) {
+		patch.borderId = addBorder(ss, spec.border);
+		patch.applyBorder = true;
+	}
+	if (spec.alignment !== void 0) {
+		patch.alignment = spec.alignment;
+		patch.applyAlignment = true;
+	}
+	if (spec.protection !== void 0) {
+		patch.protection = spec.protection;
+		patch.applyProtection = true;
+	}
+	if (spec.numberFormat !== void 0) {
+		patch.numFmtId = addNumFmt(ss, spec.numberFormat);
+		patch.applyNumberFormat = true;
+	}
+	return patch;
+}
 //#endregion
 //#region src/styles/named-styles.ts
 /**
@@ -1023,6 +1061,12 @@ function applyXfPatch(wb, c, patch) {
 	};
 	c.styleId = addCellXf(wb.styles, next);
 }
+/**
+* Replace the cell's font outright. `font` has to be complete: anything it
+* omits is omitted from the `<font>` record too, and each viewer then falls
+* back to its own default rather than the workbook's. Reach for {@link
+* patchCellFont} unless you really mean "this font and nothing inherited".
+*/
 function setCellFont(wb, c, font) {
 	applyXfPatch(wb, c, {
 		fontId: addFont(wb.styles, font),
@@ -1133,42 +1177,54 @@ function cloneCellStyle(sourceWb, source, targetWb, target) {
 	return target.styleId;
 }
 /**
-* Build a single CellXf id from a multi-axis style spec, then apply it to every
+* Register a style and return its `styleId`. `setCell` and `setCellByCoord`
+* take it as their last argument, `appendRow` and `appendRows` take it inside
+* `{ styleIds: [...] }`:
+*
+* ```ts
+* const INT = registerCellStyle(wb, { numberFormat: '#,##0' });
+* setCell(ws, 2, 3, 1234, INT);
+* appendRow(ws, ['de', 71_579], { styleIds: [undefined, INT] });
+* ```
+*
+* Build each distinct look once and let the write carry the formatting,
+* instead of running a styling pass over every cell afterwards.
+*
+* The id names a **complete** style, not a patch: an axis missing from `spec`
+* resolves to slot 0 of that pool, so it renders as the workbook default even
+* when the target cell previously had something there. {@link setCellStyle} is
+* the patch-an-existing-cell counterpart.
+*
+* "Workbook default" means slot 0 literally. On a workbook from
+* `createWorkbook` that is the neutral font / no fill / no border. A workbook
+* loaded from another producer may hold anything in slot 0, since nothing in
+* ECMA-376 reserves it, so pass the axis explicitly when the look has to be
+* neutral regardless of what the file arrived with.
+*/
+function registerCellStyle(wb, spec) {
+	reserveDefaultXfSlot(wb);
+	return addCellXf(wb.styles, {
+		...defaultCellXf(),
+		...buildXfPatch(wb.styles, spec)
+	});
+}
+/**
+* Build a single CellXf from a multi-axis style spec, then merge it into every
 * cell in `range`. The xf is registered once per style shape, so a 1000-cell
-* range allocates one xf — much faster than looping `setCellStyle` per cell.
+* range allocates one xf, which is much faster than looping `setCellStyle` per
+* cell.
+*
+* Each cell keeps the axes `spec` leaves out, which is what separates this from
+* {@link registerCellStyle}: the id that returns is a whole style, this is a
+* patch over whatever each cell already carried.
 */
-function setRangeStyle(wb, ws, range, opts) {
-	const patch = {};
-	if (opts.font !== void 0) {
-		patch.fontId = addFont(wb.styles, opts.font);
-		patch.applyFont = true;
-	}
-	if (opts.fill !== void 0) {
-		patch.fillId = addFill(wb.styles, opts.fill);
-		patch.applyFill = true;
-	}
-	if (opts.border !== void 0) {
-		patch.borderId = addBorder(wb.styles, opts.border);
-		patch.applyBorder = true;
-	}
-	if (opts.alignment !== void 0) {
-		patch.alignment = opts.alignment;
-		patch.applyAlignment = true;
-	}
-	if (opts.protection !== void 0) {
-		patch.protection = opts.protection;
-		patch.applyProtection = true;
-	}
-	if (opts.numberFormat !== void 0) {
-		patch.numFmtId = addNumFmt(wb.styles, opts.numberFormat);
-		patch.applyNumberFormat = true;
-	}
+function setRangeStyle(wb, ws, range, spec) {
+	const patch = buildXfPatch(wb.styles, spec);
 	if (Object.keys(patch).length === 0) return;
 	reserveDefaultXfSlot(wb);
 	const { minRow, maxRow, minCol, maxCol } = parseRange(range);
 	for (let r = minRow; r <= maxRow; r++) for (let c = minCol; c <= maxCol; c++) {
-		let cell = ws.rows.get(r)?.get(c);
-		if (!cell) cell = setCell(ws, r, c);
+		const cell = ensureCell(ws, r, c);
 		const next = {
 			...currentXf(wb.styles, cell),
 			...patch
@@ -1177,37 +1233,14 @@ function setRangeStyle(wb, ws, range, opts) {
 	}
 }
 /**
-* Combined cell-style setter. Each axis is independent — pass any subset and
-* the corresponding `applyXxx` flags get set on the underlying CellXf. Avoids
+* Combined cell-style setter, patching the cell's existing xf. Each axis is
+* independent, so pass any subset and the corresponding `applyXxx` flags get set
+* on the underlying CellXf. Avoids
 * 5+ separate stylesheet round-trips when a caller wants to style a single cell
 * across multiple axes (Excel dedupes the resulting xf record on every call).
 */
-function setCellStyle(wb, c, opts) {
-	const patch = {};
-	if (opts.font !== void 0) {
-		patch.fontId = addFont(wb.styles, opts.font);
-		patch.applyFont = true;
-	}
-	if (opts.fill !== void 0) {
-		patch.fillId = addFill(wb.styles, opts.fill);
-		patch.applyFill = true;
-	}
-	if (opts.border !== void 0) {
-		patch.borderId = addBorder(wb.styles, opts.border);
-		patch.applyBorder = true;
-	}
-	if (opts.alignment !== void 0) {
-		patch.alignment = opts.alignment;
-		patch.applyAlignment = true;
-	}
-	if (opts.protection !== void 0) {
-		patch.protection = opts.protection;
-		patch.applyProtection = true;
-	}
-	if (opts.numberFormat !== void 0) {
-		patch.numFmtId = addNumFmt(wb.styles, opts.numberFormat);
-		patch.applyNumberFormat = true;
-	}
+function setCellStyle(wb, c, spec) {
+	const patch = buildXfPatch(wb.styles, spec);
 	if (Object.keys(patch).length === 0) return;
 	applyXfPatch(wb, c, patch);
 }
@@ -1238,7 +1271,12 @@ function setRangeBackgroundColor(wb, ws, range, color) {
 		fgColor: typeof color === "string" ? makeColor({ rgb: color }) : makeColor(color)
 	}) });
 }
-/** Range-level shortcut for `setCellFont` (full Font replacement). */
+/**
+* Range-level shortcut for `setCellFont`. Replaces the whole Font on every cell
+* in the range; there is no range-level merge, so build the complete font you
+* want rather than passing `makeFont({ bold: true })` and losing the workbook
+* default.
+*/
 function setRangeFont(wb, ws, range, font) {
 	setRangeStyle(wb, ws, range, { font });
 }
@@ -1274,11 +1312,7 @@ function setRangeProtection(wb, ws, range, protection) {
 function setRangeWrapText(wb, ws, range, on = true) {
 	reserveDefaultXfSlot(wb);
 	const { minRow, maxRow, minCol, maxCol } = parseRange(range);
-	for (let r = minRow; r <= maxRow; r++) for (let c = minCol; c <= maxCol; c++) {
-		let cell = ws.rows.get(r)?.get(c);
-		if (!cell) cell = setCell(ws, r, c);
-		wrapCellText(wb, cell, on);
-	}
+	for (let r = minRow; r <= maxRow; r++) for (let c = minCol; c <= maxCol; c++) wrapCellText(wb, ensureCell(ws, r, c), on);
 }
 /**
 * Range-level Alignment setter. Two modes:
@@ -1302,27 +1336,42 @@ function setRangeAlignment(wb, ws, range, alignment, mode = "merge") {
 		return;
 	}
 	for (let r = minRow; r <= maxRow; r++) for (let c = minCol; c <= maxCol; c++) {
-		let cell = ws.rows.get(r)?.get(c);
-		if (!cell) cell = setCell(ws, r, c);
+		const cell = ensureCell(ws, r, c);
 		const cur = currentXf(wb.styles, cell).alignment;
 		setCellAlignment(wb, cell, mergeAlignment(cur, alignment));
 	}
 }
-const mergeFont = (current, patch) => makeFont({
-	...current,
-	...patch
-});
+/**
+* Merge `patch` over the cell's current font, so the fields left out keep the
+* value they already had (the workbook default, on an unstyled cell). This is
+* the way to change several font fields at once: `setCellFont(wb, c,
+* makeFont({ bold: true }))` is a legal call that registers a font carrying no
+* name and no size, and Excel, LibreOffice and Sheets each substitute a
+* different one.
+*
+* A field set to `undefined` is removed rather than kept, so
+* `patchCellFont(wb, c, { underline: undefined })` un-underlines a cell while
+* leaving the rest of its font alone. Omitting the key keeps the current value.
+*
+* The single-field setters below are this function with one field filled in.
+*/
+function patchCellFont(wb, c, patch) {
+	setCellFont(wb, c, makeFont({
+		...getCellFont(wb, c),
+		...patch
+	}));
+}
 /** Toggle bold on a cell. Preserves other font fields. */
 function setBold(wb, c, on = true) {
-	setCellFont(wb, c, mergeFont(getCellFont(wb, c), { bold: on }));
+	patchCellFont(wb, c, { bold: on });
 }
 /** Toggle italic on a cell. */
 function setItalic(wb, c, on = true) {
-	setCellFont(wb, c, mergeFont(getCellFont(wb, c), { italic: on }));
+	patchCellFont(wb, c, { italic: on });
 }
 /** Toggle strike-through on a cell. */
 function setStrikethrough(wb, c, on = true) {
-	setCellFont(wb, c, mergeFont(getCellFont(wb, c), { strike: on }));
+	patchCellFont(wb, c, { strike: on });
 }
 /**
 * Set the underline style. Pass `false` to drop underline; pass `'single' |
@@ -1330,32 +1379,22 @@ function setStrikethrough(wb, c, on = true) {
 * `true` for the most common single-line.
 */
 function setUnderline(wb, c, style = "single") {
-	const { underline: _drop, ...rest } = getCellFont(wb, c);
-	if (style === false) {
-		setCellFont(wb, c, makeFont(rest));
-		return;
-	}
-	const u = style === true ? "single" : style;
-	setCellFont(wb, c, makeFont({
-		...rest,
-		underline: u
-	}));
+	patchCellFont(wb, c, { underline: style === false ? void 0 : style === true ? "single" : style });
 }
 /** Set the font size in points (e.g. 14). Preserves other fields. */
 function setFontSize(wb, c, size) {
-	setCellFont(wb, c, mergeFont(getCellFont(wb, c), { size }));
+	patchCellFont(wb, c, { size });
 }
 /** Set the font family name (e.g. "Arial"). Preserves other fields. */
 function setFontName(wb, c, name) {
-	setCellFont(wb, c, mergeFont(getCellFont(wb, c), { name }));
+	patchCellFont(wb, c, { name });
 }
 /**
 * Set the font color. Accepts a hex string ("FFAA0033") or a partial `Color`
 * object (`{ theme: 4, tint: 0.4 }`). Preserves other font fields.
 */
 function setFontColor(wb, c, color) {
-	const colorObj = typeof color === "string" ? makeColor({ rgb: color }) : makeColor(color);
-	setCellFont(wb, c, mergeFont(getCellFont(wb, c), { color: colorObj }));
+	patchCellFont(wb, c, { color: typeof color === "string" ? makeColor({ rgb: color }) : makeColor(color) });
 }
 const mergeAlignment = (current, patch) => {
 	return makeAlignment({
@@ -1570,12 +1609,10 @@ function setRangeBorderBox(wb, ws, range, opts = { style: "thin" }) {
 		if (bottom !== void 0) sides.bottom = bottom;
 		if (left !== void 0) sides.left = left;
 		if (right !== void 0) sides.right = right;
-		let cell = ws.rows.get(r)?.get(col);
-		if (!cell) cell = setCell(ws, r, col);
-		setCellBorder(wb, cell, makeBorder(sides));
+		setCellBorder(wb, ensureCell(ws, r, col), makeBorder(sides));
 	}
 }
 //#endregion
-export { ensureBuiltinStyle as $, setCellFill as A, makeNumberFormat as At, setRangeBackgroundColor as B, makeGradientFill as Bt, setCellAsCurrency as C, FORMAT_TEXT as Ct, setCellBackgroundColor as D, isBuiltinFormat as Dt, setCellAsPercent as E, classifyDateFormat as Et, setFontColor as F, fontToCss as Ft, setRangeStyle as G, makeBorder as Gt, setRangeFont as H, makePatternFill as Ht, setFontName as I, makeFont as It, setUnderline as J, VERTICAL_ALIGNMENTS as Jt, setRangeWrapText as K, makeSide as Kt, setFontSize as L, PATTERN_TYPES as Lt, setCellNumberFormat as M, FONT_SCHEMES as Mt, setCellProtection as N, UNDERLINE_STYLES as Nt, setCellBorder as O, isDateFormat as Ot, setCellStyle as P, VERT_ALIGNS as Pt, addNamedStyle as Q, setItalic as R, fillToCss as Rt, setCellAlignment as S, FORMAT_PERCENTAGE_00 as St, setCellAsNumber as T, builtinFormatId as Tt, setRangeNumberFormat as U, SIDE_STYLES as Ut, setRangeBorderBox as V, makeGradientStop as Vt, setRangeProtection as W, borderToCss as Wt, makeProtection as X, makeAlignment as Xt, wrapCellText as Y, alignmentToCss as Yt, BUILTIN_NAMED_STYLES as Z, stableStringify as Zt, getCellNumberFormat as _, FORMAT_DATE_YYYYMMDD2 as _t, cellStyleToCss as a, addNumFmt as at, rotateCellText as b, FORMAT_NUMBER_00 as bt, clearCellStyle as c, listCellStyleXfs as ct, copyCellStyle as d, listFonts as dt, addBorder as et, formatAsHeader as f, makeStylesheet as ft, getCellFont as g, FORMAT_DATE_TIMEDELTA as gt, getCellFill as h, FORMAT_DATE_DATETIME as ht, applyNamedStyle as i, addFont as it, setCellFont as j, DEFAULT_FONT as jt, setCellBorderAll as k, isTimedeltaFormat as kt, clearRangeStyle as l, listCellXfs as lt, getCellBorder as m, BUILTIN_FORMATS_MAX_SIZE as mt, alignCellVertical as n, addCellXf as nt, centerCell as o, defaultCellXf as ot, getCellAlignment as p, BUILTIN_FORMATS as pt, setStrikethrough as q, HORIZONTAL_ALIGNMENTS as qt, applyBuiltinStyle as r, addFill as rt, clearCellBackground as s, listBorders as st, alignCellHorizontal as t, addCellStyleXf as tt, cloneCellStyle as u, listFills as ut, getCellProtection as v, FORMAT_GENERAL as vt, setCellAsDate as w, builtinFormatCode as wt, setBold as x, FORMAT_PERCENTAGE as xt, indentCell as y, FORMAT_NUMBER as yt, setRangeAlignment as z, makeFill as zt };
+export { BUILTIN_NAMED_STYLES as $, makeAlignment as $t, setCellBorder as A, isBuiltinFormat as At, setItalic as B, PATTERN_TYPES as Bt, setBold as C, FORMAT_NUMBER_00 as Ct, setCellAsNumber as D, builtinFormatCode as Dt, setCellAsDate as E, FORMAT_TEXT as Et, setCellProtection as F, FONT_SCHEMES as Ft, setRangeNumberFormat as G, makePatternFill as Gt, setRangeBackgroundColor as H, makeFill as Ht, setCellStyle as I, UNDERLINE_STYLES as It, setRangeWrapText as J, makeBorder as Jt, setRangeProtection as K, SIDE_STYLES as Kt, setFontColor as L, VERT_ALIGNS as Lt, setCellFill as M, isTimedeltaFormat as Mt, setCellFont as N, makeNumberFormat as Nt, setCellAsPercent as O, builtinFormatId as Ot, setCellNumberFormat as P, DEFAULT_FONT as Pt, makeProtection as Q, alignmentToCss as Qt, setFontName as R, fontToCss as Rt, rotateCellText as S, FORMAT_NUMBER as St, setCellAsCurrency as T, FORMAT_PERCENTAGE_00 as Tt, setRangeBorderBox as U, makeGradientFill as Ut, setRangeAlignment as V, fillToCss as Vt, setRangeFont as W, makeGradientStop as Wt, setUnderline as X, HORIZONTAL_ALIGNMENTS as Xt, setStrikethrough as Y, makeSide as Yt, wrapCellText as Z, VERTICAL_ALIGNMENTS as Zt, getCellNumberFormat as _, BUILTIN_FORMATS_MAX_SIZE as _t, cellStyleToCss as a, addFill as at, patchCellFont as b, FORMAT_DATE_YYYYMMDD2 as bt, clearCellStyle as c, buildXfPatch as ct, copyCellStyle as d, listCellStyleXfs as dt, stableStringify as en, addNamedStyle as et, formatAsHeader as f, listCellXfs as ft, getCellFont as g, BUILTIN_FORMATS as gt, getCellFill as h, makeStylesheet as ht, applyNamedStyle as i, addCellXf as it, setCellBorderAll as j, isDateFormat as jt, setCellBackgroundColor as k, classifyDateFormat as kt, clearRangeStyle as l, defaultCellXf as lt, getCellBorder as m, listFonts as mt, alignCellVertical as n, addBorder as nt, centerCell as o, addFont as ot, getCellAlignment as p, listFills as pt, setRangeStyle as q, borderToCss as qt, applyBuiltinStyle as r, addCellStyleXf as rt, clearCellBackground as s, addNumFmt as st, alignCellHorizontal as t, ensureBuiltinStyle as tt, cloneCellStyle as u, listBorders as ut, getCellProtection as v, FORMAT_DATE_DATETIME as vt, setCellAlignment as w, FORMAT_PERCENTAGE as wt, registerCellStyle as x, FORMAT_GENERAL as xt, indentCell as y, FORMAT_DATE_TIMEDELTA as yt, setFontSize as z, makeFont as zt };
 
-//# sourceMappingURL=cell-style-DuvS_Lsg.mjs.map
+//# sourceMappingURL=cell-style-BFmJOmcx.mjs.map