@rowsncolumns/spreadsheet-state 28.0.66

package/dist/esm/sheet-cell.js

@@ -0,0 +1,1829 @@
+import { lexify, tokenVocabulary } from "@rowsncolumns/calculator";
+import { FormulaError } from "@rowsncolumns/fast-formula-parser";
+import { getCellEffectiveValue, getCellFormattedValue, getCellUserEnteredFormat, getCellUserEnteredValue, getExtendedValueBool, getExtendedValueError, getExtendedValueFormula, getExtendedValueNumber, getExtendedValueString, getStyleId, balanceFormula, cellToAddress, getCellXfsKey, getCurrentLocale, getDefaultDateFormat, getDefaultTimeFormat, desanitizeSheetName, isAlternateFormula, isDatePattern, isDateTimePattern, isNil, isTextPattern, isValidFormula, looksLikeMarkdown, } from "@rowsncolumns/utils";
+import isEqual from "lodash/isEqual";
+import set from "lodash/set";
+import { isDataValidationFormulaRule } from "./api/data-validation";
+import { checkBooleanRule } from "./api/validation";
+import { createFormattedValue, createNumberValue, detectNumberFormatPattern, detectNumberFormatType, detectValueType, detectValueTypeAndPattern, isMultiline, isNumber, isValidURLorEmail, } from "./api/datatype";
+import { changeDecimals, getDecimalPlaces, pattern_number, pattern_number_thousands, } from "./api/decimals";
+import { formulaToRelativeReference, updateColumnName, updateNamedRangeName, updateSheetName, } from "./api/formula";
+import { getLocaleSeparators } from "./api/intl";
+import { AWAITING_CALCULATION } from "./helpers";
+export const defaultSheetId = 1;
+export const defaultCellCoords = { rowIndex: 1, columnIndex: 1 };
+// Add this helper function to determine if an object is a StyleReference
+export function isStyleReference(obj) {
+    return obj && typeof obj === "object" && ("styleId" in obj || "sid" in obj);
+}
+/**
+ * Marker persisted as `fv` on cells whose calculation is in flight (set by
+ * `setLoading()`). Exported so other modules can detect the loading state
+ * from cellData without a stringly-typed comparison.
+ */
+export const LOADING_VALUE = "Loading...";
+const excludeKeys = new Set([
+    "userEnteredValue",
+    "ue",
+    "effectiveValue",
+    "ev",
+    "formattedValue",
+    "fv",
+    "ss",
+    "effectiveFormat",
+    "ef",
+    "userEnteredFormat",
+    "uf",
+    "dataValidation",
+    "imageUrl",
+    "hyperlink",
+    "metaType",
+    "note",
+    "citationId",
+    "commentThreadId",
+    "expandable",
+    "expanded",
+    "groupKeys",
+    "pivotId",
+    "conditionalFormattingResultById",
+    "dataValidationResult",
+]);
+const hasExcelTextPrefix = (value) => {
+    return typeof value === "string" && value.startsWith("'") && value.length > 1;
+};
+/**
+ * Both halves of a `NumberFormat` can encode "General" two ways: as a
+ * missing field, or as the literal sentinel value (`"GENERAL"` for type,
+ * `"General"` for pattern). These two predicates normalize both forms so
+ * the rules above don't have to repeat `(!x || x === "…")` everywhere.
+ */
+const hasGeneralType = (format) => !format.type || format.type === "GENERAL";
+const hasGeneralPattern = (format) => !format.pattern || format.pattern === "General";
+/**
+ * "General" means the cell has no explicit number format applied. Excel's
+ * auto-format-on-input rule triggers only for General cells; any other
+ * format is preserved as-is.
+ */
+const isGeneralNumberFormat = (format) => !format || (hasGeneralType(format) && hasGeneralPattern(format));
+const stripExcelTextPrefix = (value) => value.slice(1);
+const getHyperlinkTarget = (hyperlink) => {
+    if (typeof hyperlink === "string") {
+        return hyperlink;
+    }
+    if (hyperlink.kind === "external") {
+        return hyperlink.url;
+    }
+    return hyperlink.location;
+};
+const getHyperlinkDisplay = (hyperlink) => {
+    if (typeof hyperlink === "string") {
+        return undefined;
+    }
+    return hyperlink.display;
+};
+export class SheetCell {
+    static defaultSharedStrings;
+    static defaultEnableAtFormula = false;
+    sheetId;
+    coords;
+    value;
+    userEnteredValue;
+    effectiveValue;
+    formattedValue;
+    textFormatRuns;
+    userEnteredFormat;
+    dataValidationId;
+    dataValidationRule;
+    conditionalFormattingResultById;
+    dataValidationResult;
+    defaultPattern;
+    loadingValue;
+    isLoading;
+    hyperlink;
+    imageUrl;
+    getRangeValues;
+    locale;
+    use1904;
+    lenientGrouping;
+    note;
+    commentThreadId;
+    citationId;
+    metaType;
+    expandable;
+    expanded;
+    cellData;
+    formatColor;
+    cellXfsRegistry;
+    sharedStringRegistry;
+    sharedStrings;
+    sharedStringIndex;
+    enableAtFormula;
+    originalUserEnteredFormat;
+    pivotId;
+    groupKeys;
+    version;
+    updatedAt;
+    arrayFormulaRef;
+    // Shared-formula provenance captured on xlsx import. Carries the
+    // structural grouping (xlsx `<f t="shared" si="N" ref="A1:A10">`) so the
+    // exporter can re-emit the same `t="shared"` markers. Leader cells carry
+    // both `si` and `ref`; follower cells carry only `si`. The renderer and
+    // calculator don't read this — it's pure export-side metadata that
+    // mirrors `arrayFormulaRef` (af) in lifecycle and intent. Cleared on any
+    // user formula edit so a modified cell exports as a standalone formula.
+    sharedFormulaSpec;
+    setVersion(version) {
+        this.version = version ?? undefined;
+    }
+    setUpdatedAt(timestamp) {
+        this.updatedAt = timestamp ?? undefined;
+    }
+    static setDefaultSharedStrings(sharedStrings) {
+        SheetCell.defaultSharedStrings = sharedStrings;
+    }
+    static setDefaultEnableAtFormula(enable) {
+        SheetCell.defaultEnableAtFormula = enable ?? false;
+    }
+    constructor(sheetId = defaultSheetId, coords = defaultCellCoords, cellData, options) {
+        this.assign(sheetId, coords, cellData, options);
+        this.ensureFormatsMutable();
+    }
+    setLocale(locale) {
+        this.locale = locale;
+    }
+    setUse1904(use1904) {
+        this.use1904 = use1904;
+    }
+    assign(sheetId = defaultSheetId, coords = defaultCellCoords, cellData, options) {
+        const { getRangeValues, locale = getCurrentLocale(), use1904, lenientGrouping, enableAtFormula, cellXfsRegistry, getDataValidationById, sharedStringRegistry, } = options ?? {};
+        this.sheetId = sheetId;
+        this.coords = coords;
+        this.cellData = cellData;
+        this.cellXfsRegistry = cellXfsRegistry;
+        this.sharedStringRegistry = sharedStringRegistry;
+        this.sharedStrings =
+            sharedStringRegistry?.getSharedStrings() ??
+                SheetCell.defaultSharedStrings ??
+                this.sharedStrings;
+        this.sharedStringIndex = cellData?.ss ?? undefined;
+        this.use1904 = use1904;
+        this.lenientGrouping = lenientGrouping;
+        this.enableAtFormula =
+            enableAtFormula ?? SheetCell.defaultEnableAtFormula ?? false;
+        const userEnteredFormat = cellData
+            ? getCellUserEnteredFormat(cellData)
+            : undefined;
+        // Legacy `ef` is still readable from cellData for backwards-compat at
+        // the renderer layer (see `useSheetProperties.getEffectiveFormat`),
+        // but `SheetCell` no longer tracks it as in-memory state. `uf` is the
+        // single source of truth.
+        this.userEnteredFormat = isStyleReference(userEnteredFormat)
+            ? cellXfsRegistry?.getCellXfsFromStyleId(getStyleId(userEnteredFormat))
+            : userEnteredFormat;
+        this.originalUserEnteredFormat = userEnteredFormat;
+        this.userEnteredValue = cellData
+            ? getCellUserEnteredValue(cellData)
+            : undefined;
+        this.defaultPattern = "General";
+        this.effectiveValue = cellData
+            ? getCellEffectiveValue(cellData)
+            : undefined;
+        this.formattedValue = cellData
+            ? getCellFormattedValue(cellData)
+            : undefined;
+        this.textFormatRuns = Array.isArray(cellData?.tf)
+            ? [
+                ...cellData.tf,
+            ]
+            : undefined;
+        if (this.sharedStringIndex != null) {
+            this.hydrateSharedStringValue(this.sharedStringIndex);
+        }
+        const cellDataValidation = cellData?.dataValidation;
+        // Backwards compatiblity
+        // Object based
+        if (cellDataValidation && typeof cellDataValidation === "object") {
+            this.dataValidationId = cellDataValidation.id;
+            this.dataValidationRule = cellDataValidation;
+        }
+        else {
+            // New
+            this.dataValidationId = cellDataValidation ?? undefined;
+            this.dataValidationRule = this.dataValidationId
+                ? getDataValidationById?.(this.dataValidationId)
+                : undefined;
+        }
+        this.conditionalFormattingResultById =
+            cellData?.conditionalFormattingResultById;
+        this.dataValidationResult = cellData?.dataValidationResult;
+        this.imageUrl = cellData?.imageUrl ?? undefined;
+        this.isLoading = false;
+        this.loadingValue = LOADING_VALUE;
+        this.hyperlink = cellData?.hyperlink ?? undefined;
+        this.metaType = cellData?.metaType ?? undefined;
+        this.note = cellData?.note ?? undefined;
+        this.commentThreadId = cellData?.commentThreadId ?? undefined;
+        this.citationId = cellData?.citationId ?? undefined;
+        this.expandable = cellData?.expandable ?? undefined;
+        this.expanded = cellData?.expanded ?? undefined;
+        this.getRangeValues = getRangeValues;
+        this.locale = locale;
+        this.pivotId = cellData?.pivotId;
+        this.groupKeys = cellData?.groupKeys;
+        this.version = cellData?.version ?? undefined;
+        this.updatedAt = cellData?.updatedAt ?? undefined;
+        this.arrayFormulaRef = cellData?.af ?? undefined;
+        this.sharedFormulaSpec = cellData?.sf
+            ? {
+                si: cellData.sf.si,
+                ...(cellData.sf.ref ? { ref: cellData.sf.ref } : {}),
+            }
+            : undefined;
+        return this;
+    }
+    get key() {
+        return SheetCell.generateCellKey(this.sheetId, this.coords.rowIndex, this.coords.columnIndex);
+    }
+    cloneWithFormatting() {
+        // Delete cell contents
+        this.deleteContents({ preserveTextNumberFormat: true });
+        return this;
+    }
+    updateNote(note) {
+        this.note = note;
+    }
+    updateCommentThreadId(commentThreadId) {
+        this.commentThreadId = commentThreadId;
+    }
+    clearCommentThreadId() {
+        this.commentThreadId = undefined;
+    }
+    updateCitationId(citationId) {
+        this.citationId = citationId;
+    }
+    clearCitationId() {
+        this.citationId = undefined;
+    }
+    static generateCellKey(sheetId, rowIndex, columnIndex) {
+        return `${sheetId}!${cellToAddress({
+            rowIndex: rowIndex,
+            columnIndex: columnIndex,
+        })}`;
+    }
+    /**
+     * Clears the cell's content (value, formatted value, links,
+     * notes, comments, shared-string refs, etc.).
+     *
+     * Formatting behavior is intentionally Del-key-compatible by
+     * default — Excel's Delete clears value but keeps bold / fill /
+     * etc. so users don't lose their styling when they wipe a cell.
+     * Pass `clearFormat: true` for callers that want unconditional
+     * full-clear semantics (e.g. pivot tear-down regenerating cells,
+     * "Clear All" toolbar action).
+     *
+     * Even without `clearFormat`, the method still strips
+     * `userEnteredFormat` when the existing numberFormat is one of
+     * the implicit defaults (`NUMBER` with `pattern_number` /
+     * `pattern_number_thousands`, or `TEXT`) — those formats are
+     * auto-applied based on the value's type and shouldn't outlive
+     * the value. Explicit user-applied formats (bold, fill,
+     * custom number formats) are preserved.
+     */
+    deleteContents(options) {
+        const { preserveTextNumberFormat = false, clearFormat = false, clearDataValidation = false, } = options ?? {};
+        // Stripping the validation stamp is an interactive-delete-only
+        // semantic (Del on an already-empty cell, incl. checkboxes). It must
+        // be requested explicitly — programmatic clears (changeBatch null
+        // writes, move/cut sources, fill previews) keep the validation.
+        if (clearDataValidation &&
+            !this.userEnteredValue &&
+            this.dataValidationRule) {
+            // Reset data validation
+            this.dataValidationId = undefined;
+            this.dataValidationRule = undefined;
+        }
+        this.cellData = undefined;
+        this.userEnteredValue = undefined;
+        this.effectiveValue = undefined;
+        this.formattedValue = undefined;
+        this.imageUrl = undefined;
+        this.hyperlink = undefined;
+        this.metaType = undefined;
+        this.note = undefined;
+        this.commentThreadId = undefined;
+        this.citationId = undefined;
+        this.textFormatRuns = undefined;
+        this.expandable = undefined;
+        this.expanded = undefined;
+        this.groupKeys = undefined;
+        this.version = undefined;
+        this.updatedAt = undefined;
+        this.arrayFormulaRef = undefined;
+        this.sharedFormulaSpec = undefined;
+        this.clearSharedStringIndex();
+        /**
+         * Strip userEnteredFormat. `clearFormat=true` is an
+         * unconditional wipe — used by pivot tear-down and "Clear All".
+         * Without it, only the implicit auto-applied formats go (a
+         * NUMBER cell with the default integer/thousands pattern, or
+         * a TEXT cell unless preserved). User-applied bold / fill /
+         * custom formats stay so the Del key keeps cell styling, matching
+         * Excel's behavior.
+         */
+        if (clearFormat) {
+            this.userEnteredFormat = undefined;
+            this.originalUserEnteredFormat = undefined;
+        }
+        else {
+            const numberFormat = this.userEnteredFormat?.numberFormat;
+            if ((numberFormat?.type === "NUMBER" &&
+                (numberFormat.pattern === pattern_number ||
+                    numberFormat?.pattern === pattern_number_thousands)) ||
+                (numberFormat?.type === "TEXT" && !preserveTextNumberFormat)) {
+                this.userEnteredFormat = undefined;
+                this.originalUserEnteredFormat = undefined;
+            }
+        }
+        // If there is no data validation result
+        // Preserves data validation result
+        if (!this.dataValidationRule) {
+            this.dataValidationResult = undefined;
+        }
+        this.validate();
+    }
+    deleteUserEnteredFormat() {
+        this.userEnteredFormat = undefined;
+        this.originalUserEnteredFormat = undefined;
+    }
+    /**
+     * Copy a `userEnteredFormat` from a source format onto this cell.
+     * No-op when this cell already has a format, or when the source is
+     * empty. Used by table row-expansion to propagate column-consistent
+     * formats onto newly added rows (Excel parity).
+     */
+    inheritFormat(format) {
+        if (!format)
+            return;
+        if (this.userEnteredFormat || this.originalUserEnteredFormat)
+            return;
+        this.userEnteredFormat = isStyleReference(format) ? undefined : format;
+        this.originalUserEnteredFormat = format;
+    }
+    changeFormulaSheetName(name, oldName) {
+        if (this.formula) {
+            set(this, "userEnteredValue.fv", updateSheetName(this.formula, name, oldName));
+        }
+    }
+    changeNamedRangeName(name, oldName) {
+        if (this.formula) {
+            set(this, "userEnteredValue.fv", updateNamedRangeName(this.formula, name, oldName));
+        }
+    }
+    changeFormulaColumnName(name, previousName) {
+        if (this.formula) {
+            set(this, "userEnteredValue.fv", updateColumnName(this.formula, name, previousName));
+        }
+    }
+    setLoading() {
+        // Preserve effectiveValue: Excel-style, the cell keeps showing the
+        // last calculated value while a recalc is in flight. getCellData only
+        // emits the "Loading..." placeholder when no prior value exists.
+        this.isLoading = true;
+    }
+    hideLoading() {
+        this.isLoading = false;
+    }
+    get formula() {
+        return getExtendedValueFormula(this.userEnteredValue);
+    }
+    get error() {
+        return getExtendedValueError(this.effectiveValue);
+    }
+    /**
+     * True when the current value violates the cell's data-validation rule
+     * AND the rule blocks entry. Excel's default errorStyle is "stop" — only
+     * an explicit warning/information alert downgrades the rule (mirroring
+     * the agent-write guard's strictness).
+     *
+     * Unlike `validate()`, this checks the rule SYNCHRONOUSLY via
+     * `checkBooleanRule` even for condition types that `validate()` routes
+     * through the calculator (ONE_OF_LIST dropdowns etc.) — a programmatic
+     * write path needs the verdict before committing, not one calc tick
+     * later. CUSTOM_FORMULA rules (calculator-only), rules that error while
+     * evaluating, and ONE_OF_RANGE without a range resolver all fail open,
+     * matching the agent-write guard. Used by `changeBatchStream` with
+     * `skipInvalidValues` to drop the write silently; interactive editing
+     * keeps its dialog flow.
+     */
+    get failsBlockingValidation() {
+        const rule = this.dataValidationRule;
+        if (!rule?.condition?.type) {
+            return false;
+        }
+        const style = rule.alert?.style;
+        if (style === "warning" || style === "information") {
+            return false;
+        }
+        if (rule.condition.type === "CUSTOM_FORMULA") {
+            return false;
+        }
+        try {
+            // Error values (a formula result like #REF!) aren't a validation
+            // concern — fail open, same as validate().
+            if (getExtendedValueError(this.effectiveValue)) {
+                return false;
+            }
+            const effectiveValue = this.getEffectiveValue();
+            const isBlank = effectiveValue === undefined ||
+                effectiveValue === null ||
+                (typeof effectiveValue === "string" && effectiveValue === "");
+            if (rule.allowBlank && isBlank) {
+                return false;
+            }
+            // Strict `=== false`: a rule the checker can't resolve (e.g.
+            // ONE_OF_RANGE without getRangeValues) returns undefined → fail open.
+            return (checkBooleanRule(rule, effectiveValue, undefined, this.getRangeValues, { locale: this.locale }) === false);
+        }
+        catch {
+            return false;
+        }
+    }
+    static getRelativeFormula(value, from, to, activeSheetName = "", exclusionRange, ignoreCircular = false, rowCount, columnCount, preserveAbsolutes) {
+        if (typeof value !== "string") {
+            return undefined;
+        }
+        return formulaToRelativeReference(value, from, to, activeSheetName, {
+            exclusionRange,
+            ignoreCircular,
+            rowCount,
+            columnCount,
+            preserveAbsolutes,
+        });
+    }
+    moveFormula(from, to, activeSheetName, options) {
+        /**
+         * Moving formula does not trigger a recalc
+         * The cell dependency is updated using
+         * enqueueGraphOperation
+         */
+        if (this.isFormula()) {
+            try {
+                const sourceFormula = this.formula;
+                let movedFormula = formulaToRelativeReference(sourceFormula, from, to, activeSheetName, options);
+                // Filling/moving formulas should also shift explicit refs like
+                // ='Sheet1'!A1 when the source and target rows/cols move.
+                const referencedSheetNames = lexify(sourceFormula)
+                    .tokens.map((token) => {
+                    if (token.tokenType.name === tokenVocabulary.Sheet.name) {
+                        return token.image.slice(0, -1);
+                    }
+                    if (token.tokenType.name === tokenVocabulary.SheetQuoted.name) {
+                        const desanitized = desanitizeSheetName(token.image);
+                        return desanitized ? desanitized.slice(0, -1) : undefined;
+                    }
+                    return undefined;
+                })
+                    .filter((sheetName) => Boolean(sheetName));
+                for (const sheetName of new Set(referencedSheetNames)) {
+                    if (sheetName.toLowerCase() === activeSheetName.toLowerCase()) {
+                        continue;
+                    }
+                    movedFormula = formulaToRelativeReference(movedFormula, from, to, sheetName, options);
+                }
+                this.userEnteredValue = { fv: movedFormula };
+            }
+            catch (err) {
+                console.log("Error moving formula", err, this.formula, from, to);
+                if (err instanceof FormulaError) {
+                    this.effectiveValue = {
+                        ev: {
+                            type: "Error",
+                            name: err.error,
+                            message: err.message,
+                        },
+                    };
+                }
+            }
+        }
+    }
+    isFormula() {
+        return !!getExtendedValueFormula(this.userEnteredValue);
+    }
+    isStructuredReferenceFormula() {
+        // This regex matches table references like [Column], [@Column], or TableName[Column]
+        return this.formula && /(\w+\[[@]?\w+\]|\[[@]?\w+\])/.test(this.formula);
+    }
+    ephemeral() {
+        // The formula contains absolute reference or is a table
+        return this.isStructuredReferenceFormula() || this.formula?.includes("$");
+    }
+    isEmpty() {
+        return !getExtendedValueString(this.userEnteredValue);
+    }
+    isNumberType(numType) {
+        return [
+            "NUMBER",
+            "CURRENCY",
+            "PERCENT",
+            "ACCOUNTING",
+            "FRACTION",
+            "SCIENTIFIC",
+        ].includes(numType);
+    }
+    changeDecimals(delta = 1) {
+        // Read through getNumberFormat so we pick up `uf.numberFormat` when
+        // `effectiveFormat` is empty (which is the common case now that `ef`
+        // is no longer persisted on cellData).
+        const currentNumberFormat = this.getNumberFormat();
+        const effectiveNumberType = currentNumberFormat?.type;
+        const isNumber = this.isNumberType(effectiveNumberType);
+        const effectiveValue = getExtendedValueNumber(this.effectiveValue);
+        const isGeneralNumber = effectiveNumberType === undefined || effectiveNumberType === "GENERAL";
+        const effectivePattern = currentNumberFormat?.pattern === "General"
+            ? undefined
+            : currentNumberFormat?.pattern;
+        // Blank cells stay editable when they carry an explicit numeric pattern
+        // (e.g. whole-column formatting), so later entries inherit the adjusted
+        // precision. Blank General cells have nothing to adjust.
+        if ((!isNumber && !isGeneralNumber) ||
+            (typeof effectiveValue !== "number" && !(isNumber && effectivePattern))) {
+            return;
+        }
+        const finalNumberType = isGeneralNumber ? "NUMBER" : effectiveNumberType;
+        const finalPattern = effectivePattern
+            ? effectivePattern
+            : changeDecimals(pattern_number, Math.min(
+            // The guard above ensures effectiveValue is a number whenever
+            // effectivePattern is falsy, so the 0 fallback is unreachable —
+            // it only narrows the type for getDecimalPlaces.
+            getDecimalPlaces(this.formattedValue ?? effectiveValue ?? 0, this.locale), 3), false);
+        const pattern = changeDecimals(finalPattern, delta);
+        if (pattern) {
+            if (typeof effectiveValue === "number") {
+                this.formattedValue = createFormattedValue(effectiveValue, "numberValue", pattern, this.locale);
+            }
+            if (!this.userEnteredFormat) {
+                this.userEnteredFormat = {};
+            }
+            this.userEnteredFormat.numberFormat = {
+                type: finalNumberType,
+                pattern,
+            };
+        }
+    }
+    decreaseDecimals() {
+        this.changeDecimals(-1);
+    }
+    increaseDecimals() {
+        this.changeDecimals(1);
+    }
+    setBorder(position, border) {
+        this.ensureUserEnteredFormatMutable();
+        if (!this.userEnteredFormat) {
+            this.userEnteredFormat = {};
+        }
+        const existing = this.userEnteredFormat.borders;
+        const borders = existing && Object.isExtensible(existing)
+            ? existing
+            : { ...(existing ?? {}) };
+        this.userEnteredFormat.borders = borders;
+        if (!border.color) {
+            // User is trying to clear the border
+            delete borders[position];
+        }
+        else {
+            if (isNil(border)) {
+                delete borders[position];
+            }
+            else {
+                borders[position] = border;
+            }
+        }
+    }
+    setUserEnteredBorder(position, border) {
+        this.ensureUserEnteredFormatMutable();
+        if (!this.userEnteredFormat) {
+            this.userEnteredFormat = {};
+        }
+        const existing = this.userEnteredFormat.borders;
+        const borders = existing && Object.isExtensible(existing)
+            ? existing
+            : { ...(existing ?? {}) };
+        this.userEnteredFormat.borders = borders;
+        if (!border.color) {
+            // User is trying to clear the border
+            delete borders[position];
+        }
+        else {
+            if (isNil(border)) {
+                delete borders[position];
+            }
+            else {
+                borders[position] = border;
+            }
+        }
+    }
+    setAllBorders(border) {
+        // User is trying to clear the border
+        if (!border.color) {
+            this.clearAllBorders();
+        }
+        else {
+            set(this, "userEnteredFormat.borders", {
+                top: border,
+                bottom: border,
+                left: border,
+                right: border,
+            });
+        }
+    }
+    clearAllBorders() {
+        if (this.userEnteredFormat) {
+            this.userEnteredFormat.borders = undefined;
+        }
+    }
+    setImage(imageUrl) {
+        this.imageUrl = imageUrl;
+        this.userEnteredValue = undefined;
+        this.hyperlink = undefined;
+        this.formattedValue = "";
+    }
+    isMultiline() {
+        return isMultiline(this.getUserEnteredValue());
+    }
+    /**
+     * Over write formatted value
+     * @param value
+     */
+    setFormattedValue(value) {
+        this.formattedValue = value;
+    }
+    setUserEnteredValue(value, textFormatRuns, options) {
+        if (value === "" || isNil(value)) {
+            this.clearUserEnteredValue();
+            return this;
+        }
+        // Ensure new entries can replace the previously formatted value (e.g. hyperlinks)
+        this.formattedValue = undefined;
+        // SDK / programmatic-write path: trust the caller's explicit JS type
+        // (matches stock openpyxl / Excel-Java behavior — a Python string
+        // stays a string, a Python datetime is pre-converted by the SDK and
+        // arrives as a numberValue with the appropriate numberFormat already
+        // staged by a separate ``SetCellStyle`` command). Skips the markdown,
+        // ``@``-prefix, leading-``+``, and ``detectValueTypeAndPattern``
+        // coercions that the cell-editor UX relies on.
+        if (options?.disableTypeInference) {
+            // eslint-disable-next-line no-console
+            const inferredType = typeof value === "boolean"
+                ? "boolValue"
+                : typeof value === "number"
+                    ? "numberValue"
+                    : "stringValue";
+            // For numeric values, set ``numberFormatType="NUMBER"`` so the cell
+            // doesn't get auto-interned as a shared string. ``setNumberValue``
+            // stores ``userEnteredValue.sv`` with the string representation of
+            // the number; without a non-falsy ``numberFormat.type``,
+            // ``shouldUseSharedStrings`` treats the cell as a string and the
+            // shared-string registry promotes it to ``ss``. That in turn makes
+            // a subsequent ``SetCellStyle`` with a ``numberFormat`` (e.g.
+            // ``"$#,##0.00"``) early-return inside ``setNumberFormat``
+            // (the ``!isNil(sharedStringIndex) && numberFormatType !== "TEXT"``
+            // guard), so the user's currency / percent / date pattern never
+            // lands on the cell. Stamping ``NUMBER`` here mirrors what
+            // ``detectValueTypeAndPattern`` does for a plain integer / float
+            // — only the auto-detected ``pattern`` is left undefined, so the
+            // SDK-supplied ``SetCellStyle`` is authoritative.
+            const inferredFormatType = typeof value === "number" ? "NUMBER" : undefined;
+            this.setUserEnteredValueByType(inferredType, value, textFormatRuns, inferredFormatType, typeof value === "number" ? value : undefined, undefined, undefined);
+            if (!this.isFormula()) {
+                this.validate();
+            }
+            this.setVersion((this.version ?? 0) + 1);
+            this.setUpdatedAt(Date.now());
+            return this;
+        }
+        const originalValue = value;
+        let normalizedValue = value;
+        let forceStringFromPrefix = false;
+        if (hasExcelTextPrefix(normalizedValue)) {
+            normalizedValue = stripExcelTextPrefix(normalizedValue);
+            forceStringFromPrefix = true;
+        }
+        if (typeof normalizedValue === "string" &&
+            normalizedValue.startsWith("+") &&
+            !isAlternateFormula(normalizedValue)) {
+            const plusTrimmed = normalizedValue.slice(1).trim();
+            if (isNumber(plusTrimmed, this.locale, this.lenientGrouping)) {
+                normalizedValue = plusTrimmed;
+            }
+        }
+        const forceMarkdownText = typeof normalizedValue === "string" && looksLikeMarkdown(normalizedValue);
+        const startsWithAt = typeof normalizedValue === "string" && normalizedValue.startsWith("@");
+        const forceStringFromAtPrefix = startsWithAt && !this.enableAtFormula;
+        const dataValuePattern = forceMarkdownText
+            ? ["stringValue"]
+            : forceStringFromAtPrefix
+                ? ["stringValue"]
+                : this.enableAtFormula && startsWithAt
+                    ? ["formulaValue"]
+                    : detectValueTypeAndPattern(normalizedValue, this.locale, this.lenientGrouping, this.use1904);
+        const [valueType, , numberValue, newPattern] = dataValuePattern;
+        // User forced this cell to be a text
+        const forceStringValue = this.isText(this.userEnteredFormat?.numberFormat);
+        const finalValueType = forceStringValue ||
+            forceStringFromPrefix ||
+            forceMarkdownText ||
+            forceStringFromAtPrefix
+            ? "stringValue"
+            : valueType;
+        const numberFormatType = dataValuePattern[1];
+        this.setUserEnteredValueByType(finalValueType, normalizedValue, textFormatRuns, numberFormatType, numberValue, newPattern, forceStringFromPrefix ? originalValue : undefined);
+        // Validate
+        // Formula cells preserve their prior effectiveValue across an edit
+        // (Excel-like behavior), so guarding on `getEffectiveValue()` would
+        // validate against the *stale* value. Defer validation for formulas
+        // entirely — calc-success drives it via setDataValidationResult.
+        if (!this.isFormula()) {
+            this.validate();
+        }
+        this.setVersion((this.version ?? 0) + 1);
+        this.setUpdatedAt(Date.now());
+        return this;
+    }
+    clearUserEnteredValue() {
+        this.userEnteredValue = undefined;
+        this.formattedValue = undefined;
+        this.textFormatRuns = undefined;
+        this.clearSharedStringIndex();
+        // Remove effective value too
+        this.effectiveValue = undefined;
+    }
+    clearEffectiveValueForFormula() {
+        // Remove effective value
+        this.effectiveValue = undefined;
+        this.textFormatRuns = undefined;
+        this.formattedValue = "";
+    }
+    setUserEnteredValueByType(valueType, value, textFormatRuns, numberFormatType, numberValue, newPattern, originalStringValue) {
+        switch (valueType) {
+            case "boolValue":
+                this.setBooleanValue(value);
+                break;
+            case "numberValue":
+                this.setNumberValue(value, numberFormatType, numberValue, newPattern);
+                break;
+            case "formulaValue":
+                this.setFormulaValue(value);
+                break;
+            case "stringValue":
+                // Check if its url (unless original prefix forced plain text)
+                if (!originalStringValue && isValidURLorEmail(value)) {
+                    // A fresh user entry replaces whatever string the cell held.
+                    // `setHyperlink`'s no-title branch deliberately leaves the
+                    // shared-string index alone (it also runs during hydration),
+                    // so drop it here — otherwise `getCellData` keeps serializing
+                    // the old SST slot and the cell renders the previous URL.
+                    this.clearSharedStringIndex();
+                    this.setUrl(value);
+                }
+                else {
+                    this.setStringValue(value, textFormatRuns, originalStringValue);
+                }
+                break;
+        }
+    }
+    ensureUserEnteredFormatMutable() {
+        if (this.userEnteredFormat &&
+            !Object.isExtensible(this.userEnteredFormat)) {
+            this.userEnteredFormat = { ...this.userEnteredFormat };
+        }
+    }
+    ensureFormatsMutable() {
+        this.ensureUserEnteredFormatMutable();
+    }
+    setBooleanValue(value) {
+        this.clearSharedStringIndex();
+        const effectiveValue = String(value).toUpperCase() === "TRUE";
+        set(this, "userEnteredValue", { bv: effectiveValue });
+        set(this, "effectiveValue", { bv: effectiveValue });
+        this.formattedValue = createFormattedValue(value, "boolValue", this.defaultPattern, this.locale);
+        this.ensureFormatsMutable();
+        // Excel parity: the cell's existing number format survives a boolean
+        // entry — re-typing a number later restores the styled display. Wiping
+        // `uf.numberFormat` here would silently drop a user-applied custom
+        // format the moment TRUE/FALSE was written.
+    }
+    setNumberValue(value, numberFormatType, numberValue, newPattern) {
+        this.clearSharedStringIndex();
+        // Read through getNumberFormat so we pick up either `uf.numberFormat`
+        // or the in-memory `effectiveFormat.numberFormat` (legacy `ef`-only
+        // cells loaded from older saved data populate effectiveFormat in
+        // assign()). Without this, editing a legacy ef-only currency cell
+        // would silently drop CURRENCY back to NUMBER.
+        const existingFormat = this.getNumberFormat();
+        let finalFormatType = numberFormatType;
+        let finalPattern = newPattern;
+        if (existingFormat?.type === "TEXT") {
+            finalFormatType = "TEXT";
+            finalPattern = existingFormat.pattern ?? finalPattern;
+        }
+        // Excel-like behavior: Preserve existing format when entering plain numbers
+        if (existingFormat &&
+            this.shouldPreserveExistingFormat(numberFormatType, existingFormat, newPattern, numberValue)) {
+            finalFormatType = existingFormat.type;
+            finalPattern = existingFormat.pattern ?? undefined;
+        }
+        // Calculate string value for user entered value
+        const stringValue = this.getStringValueForFormat(value, numberValue, finalFormatType);
+        // Create formatted display value
+        this.formattedValue = createFormattedValue(numberValue, "numberValue", finalPattern ?? this.defaultPattern, this.locale);
+        // Set values and alignment
+        if (finalFormatType === "TEXT") {
+            this.formattedValue = createFormattedValue(String(value), "stringValue", finalPattern ?? this.defaultPattern, this.locale);
+            set(this, "userEnteredValue", { sv: String(value) });
+            set(this, "effectiveValue", { sv: String(value) });
+        }
+        else {
+            const userString = typeof value === "string" && finalFormatType === "NUMBER"
+                ? this.normalizeUserEnteredNumber(value)
+                : typeof value === "string" && finalFormatType === "SCIENTIFIC"
+                    ? stringValue // Use expanded numeric string for scientific notation
+                    : typeof value === "string"
+                        ? value
+                        : stringValue;
+            set(this, "userEnteredValue", { sv: userString });
+            set(this, "effectiveValue", { nv: numberValue });
+        }
+        // Apply number format if specified — uf only.
+        if (finalFormatType) {
+            set(this, "userEnteredFormat.numberFormat.type", finalFormatType);
+            set(this, "userEnteredFormat.numberFormat.pattern", finalPattern);
+        }
+    }
+    normalizeUserEnteredNumber(value) {
+        const { group } = getLocaleSeparators(this.locale);
+        if (!group) {
+            return value;
+        }
+        const isWhitespaceGroup = group.trim() === "";
+        if (isWhitespaceGroup) {
+            return value.replace(/[\s\u00A0\u202F]/g, "");
+        }
+        const escaped = group.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        return value.replace(new RegExp(escaped, "g"), "");
+    }
+    shouldPreserveExistingFormat(newFormatType, existingFormat, _newPattern, _numberValue) {
+        // Excel rule, in three layers:
+        //   1. General cell                → defer to the typed value's
+        //                                    inferred format
+        //   2. Plain NUMBER input          → preserve any non-General format
+        //   3. Explicit-format input       → preserve only when the
+        //      (Currency / Percent / Date)   existing format is in the same
+        //                                    category, else switch
+        if (isGeneralNumberFormat(existingFormat))
+            return false;
+        if (!newFormatType || newFormatType === "NUMBER")
+            return true;
+        // Specific data state: General type combined with a non-General
+        // pattern is the exact shape the Custom-format dialog produces.
+        // Excel's auto-format paths always stamp a named type (CURRENCY,
+        // PERCENT, DATE, …), so a pattern paired with a General type can
+        // only have come from explicit user action (dialog or programmatic).
+        // Respect it across all inputs.
+        if (hasGeneralType(existingFormat) && !hasGeneralPattern(existingFormat)) {
+            return true;
+        }
+        // Cross-category transitions — resolve the existing format's
+        // effective category, falling back to pattern inference for
+        // pattern-only formats imported from xlsx.
+        const effectiveType = !hasGeneralType(existingFormat)
+            ? existingFormat.type
+            : this.isDateTime(existingFormat)
+                ? "DATE_TIME"
+                : this.isDate(existingFormat)
+                    ? "DATE"
+                    : "NUMBER";
+        return effectiveType === newFormatType;
+    }
+    getStringValueForFormat(value, numberValue, formatType) {
+        const isDate = this.isDate(formatType ? { type: formatType } : undefined);
+        const isDateTime = this.isDateTime(formatType ? { type: formatType } : undefined);
+        if (isDate || isDateTime) {
+            return createFormattedValue(numberValue, "numberValue", isDate ? getDefaultDateFormat(this.locale) : getDefaultTimeFormat(this.locale), this.locale);
+        }
+        if (formatType === "PERCENT") {
+            return value; // Show user entered value for percent
+        }
+        return String(numberValue);
+    }
+    setFormulaValue(formulaValue, clearEffectiveValue = false) {
+        if (formulaValue.startsWith("@") && !this.enableAtFormula) {
+            this.setStringValue(formulaValue);
+            return;
+        }
+        // A leading "==" can never start a valid formula expression (Excel/Sheets
+        // have no token for it), so values like "=== COMP DRIVERS ===" are label
+        // text, not formulas. Store them as a plain string rather than handing a
+        // never-parseable expression to the calculator. Mirrors the "@" guard
+        // above and the matching `isAFormula` classification.
+        if (formulaValue.startsWith("==")) {
+            this.setStringValue(formulaValue);
+            return;
+        }
+        this.clearSharedStringIndex();
+        // Balance parenthesis
+        formulaValue = balanceFormula(formulaValue);
+        // Sanitize formula
+        if (formulaValue.startsWith("@")) {
+            formulaValue = `=${formulaValue.slice(1)}`;
+        }
+        else if (isAlternateFormula(formulaValue)) {
+            // If it starts with @, replace it with =
+            formulaValue = `=${formulaValue}`;
+        }
+        // Convert escaped quotes \\" or \" to Excel's doubled quote format ""
+        formulaValue = formulaValue.replace(/\\+"/g, '""');
+        // Convert newline escape sequences to CHAR(10) function
+        formulaValue = formulaValue.replace(/\\n/g, '"&CHAR(10)&"');
+        // Drop xlsx round-trip provenance — the user is supplying a brand-new
+        // formula, so any source-side `<f t="array" ref="…">` or
+        // `<f t="shared" si="…">` grouping no longer applies. Without this,
+        // the exporter would replay the stale marker and either:
+        //  (a) write `<f t="array" ref="G7:G10">USER_FORMULA</f>` and spill
+        //      the user's edit across cells that weren't part of the source
+        //      array, or
+        //  (b) emit `<f t="shared" si="N"/>` (self-closing, no formula text)
+        //      and lose the user's new expression entirely.
+        // Editing a cell formula is the canonical "detach from group" action,
+        // mirroring how Excel breaks the grouping on in-place edits.
+        this.arrayFormulaRef = undefined;
+        this.sharedFormulaSpec = undefined;
+        // Set user entered value
+        this.userEnteredValue = { fv: formulaValue };
+        // Clear
+        if (clearEffectiveValue) {
+            if (isValidFormula(formulaValue)) {
+                this.clearEffectiveValueForFormula();
+            }
+            else {
+                this.formattedValue = formulaValue;
+            }
+        }
+    }
+    setStringValue(stringValue, textFormatRuns, userEnteredStringValue) {
+        this.clearSharedStringIndex();
+        this.ensureFormatsMutable();
+        const coercedValue = String(stringValue);
+        const userValue = userEnteredStringValue ?? coercedValue;
+        set(this, "userEnteredValue", { sv: userValue });
+        set(this, "effectiveValue", { sv: coercedValue });
+        // Excel parity: the cell's existing pattern still applies to text. A
+        // 4-section custom format like `[Blue]#,##0.00;[Red]-#,##0.00;[Green]"zero";[Magenta]@`
+        // uses its `@` (segment 4) branch for string values, so the literal
+        // prefixes / suffixes around `@` (e.g. `"Note: "@` → `Note: hello`) and
+        // any `[Color]` directive in that segment must flow through. Falling
+        // back to `defaultPattern` here would silently drop them.
+        const pattern = this.userEnteredFormat?.numberFormat?.pattern ?? this.defaultPattern;
+        this.formattedValue = createFormattedValue(coercedValue, "stringValue", pattern, this.locale);
+        this.textFormatRuns = textFormatRuns;
+        // Don't clear `uf.numberFormat` here. Excel preserves the cell's number
+        // format when text is entered — re-typing a number later restores the
+        // styled display, and the `@` section of the existing pattern still
+        // formats the current text value. The previous "delete unless TEXT"
+        // branch nuked any user-applied custom format the moment a string was
+        // written, which also broke the per-section color path at render time.
+    }
+    getSharedStringCandidate() {
+        return (getExtendedValueString(this.userEnteredValue) ??
+            getExtendedValueString(this.effectiveValue));
+    }
+    /**
+     * Runs attached to this cell at write-time. The shared-string
+     * registry calls this to decide whether to intern a plain or rich
+     * SST entry. Returns `undefined` when the cell has no per-segment
+     * formatting (plain interning path stays unchanged).
+     */
+    getSharedStringRichRuns() {
+        if (!this.textFormatRuns || this.textFormatRuns.length === 0) {
+            return undefined;
+        }
+        return this.textFormatRuns;
+    }
+    shouldUseSharedStrings(candidate) {
+        if (!candidate || candidate === "") {
+            return false;
+        }
+        if (hasExcelTextPrefix(candidate)) {
+            return false;
+        }
+        if (this.isFormula()) {
+            return false;
+        }
+        // The cell's effective value is numeric (or boolean) — the candidate
+        // string is just a serialized form of a real number. Promoting it to
+        // the SST would replace `ev.nv` with `ev.sv` on hydration, turning a
+        // genuine number into a text cell. That's exactly how `-12` typed
+        // into a `[Blue]…;[Red]-…;[Green]…;[Magenta]@` custom-format cell
+        // ended up rendered in magenta and left-aligned: the renderer saw a
+        // string and routed it through the `@` section instead of the
+        // negative-number section. This single guard is sufficient — a
+        // *text* value in the same custom-pattern cell still goes to the SST
+        // normally (no `ev.nv` to protect), which keeps xlsx export's
+        // string-interning optimization intact for the long-text case.
+        if (this.effectiveValue &&
+            (getExtendedValueNumber(this.effectiveValue) !== undefined ||
+                getExtendedValueBool(this.effectiveValue) !== undefined)) {
+            return false;
+        }
+        const numberFormat = this.userEnteredFormat?.numberFormat;
+        const numberFormatType = numberFormat?.type;
+        // A pattern-only format (no `type`) imported from xlsx still carries
+        // semantic intent. If the pattern is date/datetime/time, the cell is
+        // numeric in Excel's eyes — promoting it to the SST would lose that
+        // and re-emit the value as a literal text serial on save.
+        if (!numberFormatType && numberFormat?.pattern) {
+            if (isDatePattern(numberFormat.pattern) ||
+                isDateTimePattern(numberFormat.pattern)) {
+                return false;
+            }
+        }
+        return (numberFormatType === undefined ||
+            numberFormatType === "GENERAL" ||
+            numberFormatType === "TEXT");
+    }
+    getSharedStringIndex() {
+        return this.sharedStringIndex;
+    }
+    applySharedStringIndex(index) {
+        this.sharedStringIndex = index ?? undefined;
+    }
+    clearSharedStringIndex() {
+        this.sharedStringIndex = undefined;
+    }
+    hydrateSharedStringValue(index) {
+        const strings = this.sharedStrings ?? SheetCell.defaultSharedStrings ?? undefined;
+        if (!strings) {
+            return;
+        }
+        const rawValue = strings instanceof Map
+            ? strings.get(String(index))
+            : Array.isArray(strings)
+                ? strings[Number(index)]
+                : undefined;
+        // SharedStrings may hold a plain string OR a rich `{text, runs}`
+        // object. Either way we surface the plain text into `ue.sv` and
+        // hydrate the cell's `textFormatRuns` from the rich runs when
+        // present — so a cell loaded from a rich SST entry already
+        // carries the runs without a second lookup at render time.
+        let value;
+        if (typeof rawValue === "string") {
+            value = rawValue;
+        }
+        else if (rawValue &&
+            typeof rawValue === "object" &&
+            typeof rawValue.text === "string") {
+            value = rawValue.text;
+            const richRuns = rawValue.runs;
+            if (Array.isArray(richRuns) && richRuns.length > 0) {
+                this.textFormatRuns = richRuns;
+            }
+        }
+        else {
+            return;
+        }
+        if (value === undefined) {
+            return;
+        }
+        const hasEffectiveError = Boolean(getExtendedValueError(this.effectiveValue));
+        this.userEnteredValue = { sv: value };
+        if (!hasEffectiveError) {
+            this.effectiveValue = { sv: value };
+        }
+        this.formattedValue =
+            this.formattedValue ??
+                createFormattedValue(value, "stringValue", this.defaultPattern, this.locale);
+    }
+    validate() {
+        // Validation
+        if (this.dataValidationRule) {
+            try {
+                const isFormulaRule = isDataValidationFormulaRule(this.dataValidationRule);
+                const allowBlank = this.dataValidationRule.allowBlank;
+                const hasEffectiveError = Boolean(getExtendedValueError(this.effectiveValue));
+                const effectiveValue = this.getEffectiveValue();
+                const isBlank = !hasEffectiveError &&
+                    (effectiveValue === undefined ||
+                        effectiveValue === null ||
+                        (typeof effectiveValue === "string" && effectiveValue === ""));
+                const isValid = allowBlank && isBlank
+                    ? true
+                    : isFormulaRule
+                        ? this.dataValidationResult === undefined
+                            ? true
+                            : Boolean(this.dataValidationResult)
+                        : checkBooleanRule(this.dataValidationRule, effectiveValue, undefined, this.getRangeValues, { locale: this.locale });
+                if (!isValid) {
+                    // Excel parity: a value that fails data validation is *flagged*,
+                    // not erased. The cell keeps showing its `sv` / `nv` / `bv` and
+                    // gets a red indicator (sourced from the `ev.ev` invalid marker).
+                    // Previously this replaced the entire effectiveValue with just
+                    // `{ev: ...}`, which destroyed the user's data the moment a
+                    // validation rule was applied to a non-matching cell.
+                    set(this, "effectiveValue.ev", {
+                        message: "This cell's contents violate its validation rule",
+                        type: "Invalid",
+                    });
+                }
+                else {
+                    delete this.effectiveValue?.ev;
+                }
+            }
+            catch (err) {
+                set(this, "effectiveValue.ev", {
+                    type: "Error",
+                    name: err instanceof FormulaError ? err.error : "#ERROR!",
+                    message: String(err),
+                });
+            }
+        }
+        else {
+            delete this.effectiveValue?.ev;
+        }
+    }
+    setConditionalFormatResult(ruleId, value) {
+        if (!this.conditionalFormattingResultById) {
+            this.conditionalFormattingResultById = {};
+        }
+        this.conditionalFormattingResultById[ruleId] = value;
+    }
+    clearConditionalFormatResults() {
+        this.conditionalFormattingResultById = undefined;
+    }
+    setDataValidationResult(value) {
+        this.dataValidationResult = value;
+        // Validate
+        this.validate();
+    }
+    /**
+     * Refresh formatted value
+     * from effective value and effective format
+     */
+    refreshFormattedValue() {
+        const effectiveValue = this.getEffectiveValue();
+        if (isNil(effectiveValue)) {
+            this.formattedValue = undefined;
+            return;
+        }
+        const valueType = detectValueType(effectiveValue, this.locale, this.lenientGrouping);
+        switch (valueType) {
+            case "numberValue":
+                this.formattedValue = createFormattedValue(effectiveValue, "numberValue", this.getNumberFormat()?.pattern ?? this.defaultPattern, this.locale);
+                break;
+            case "boolValue":
+                this.setEffectiveBooleanValue(effectiveValue);
+                break;
+            case "stringValue":
+            default:
+                this.setEffectiveStringValue(effectiveValue);
+                break;
+        }
+    }
+    setEffectiveValue(value, isPreview = false, preserveStringLiteral = false) {
+        // Hide loading
+        this.hideLoading();
+        if (isNil(value)) {
+            this.clearEffectiveValue();
+            return this;
+        }
+        if (value instanceof FormulaError) {
+            this.setErrorValue(value);
+            return this;
+        }
+        if (value === AWAITING_CALCULATION) {
+            // AWAITING_CALCULATION is a placeholder, not a computed result: the
+            // on-demand gate publishes it when it deliberately does NOT evaluate
+            // the formula. It must never destroy a persisted result — in
+            // particular a persisted error ev (#VALUE! from a failed =AOP() run)
+            // was erased here on every subsequent open: the open pass
+            // force-enqueues persisted-error cells, the on-demand gate answers
+            // AWAITING_CALCULATION, and the removeErrorValue() below scrubbed the
+            // error from state and (via the leader's recalc broadcast) from the
+            // Y.Doc, leaving the cell blank after reload.
+            if (!this.error &&
+                (!this.effectiveValue?.structuredValue ||
+                    this.formattedValue === this.loadingValue)) {
+                this.formattedValue = value;
+            }
+            return this;
+        }
+        this.removeErrorValue();
+        if (typeof value === "object" &&
+            value.kind) {
+            this.setStructuredValue(value);
+            return this;
+        }
+        else if (typeof value === "object") {
+            // Stringify objects to be displayed in a cell
+            value = JSON.stringify(value);
+        }
+        let normalizedValue = value;
+        let forceStringFromPrefix = false;
+        if (hasExcelTextPrefix(normalizedValue)) {
+            normalizedValue = stripExcelTextPrefix(normalizedValue);
+            forceStringFromPrefix = true;
+        }
+        const valueType = (preserveStringLiteral || forceStringFromPrefix) &&
+            typeof normalizedValue === "string"
+            ? "stringValue"
+            : detectValueType(normalizedValue, this.locale, this.lenientGrouping);
+        switch (valueType) {
+            case "numberValue":
+                this.setEffectiveNumberValue(normalizedValue);
+                break;
+            case "stringValue":
+            case "formulaValue":
+                this.setEffectiveStringValue(normalizedValue);
+                break;
+            case "boolValue":
+                this.setEffectiveBooleanValue(normalizedValue);
+                break;
+        }
+        if (!isPreview) {
+            this.validate();
+            this.setVersion((this.version ?? 0) + 1);
+            this.setUpdatedAt(Date.now());
+        }
+        return this;
+    }
+    clearEffectiveValue() {
+        this.effectiveValue = undefined;
+        this.formattedValue = undefined;
+        this.cellData = undefined;
+    }
+    setErrorValue(error) {
+        this.effectiveValue = {
+            ev: {
+                type: "Error",
+                name: error.error,
+                message: error.message,
+            },
+        };
+        this.formattedValue = String(error.error);
+    }
+    removeErrorValue() {
+        delete this.effectiveValue?.ev;
+    }
+    setStructuredValue(structuredValue) {
+        switch (structuredValue.kind) {
+            case "hyperlink":
+                this.setUrl(structuredValue.url, structuredValue.title);
+                // Set structuredValue
+                set(this, "effectiveValue.structuredValue", structuredValue);
+                break;
+            case "image":
+                this.imageUrl = structuredValue.imageUrl;
+                this.formattedValue = "";
+                // Set structuredValue
+                set(this, "effectiveValue", { structuredValue });
+                break;
+            case "sparkline":
+                this.formattedValue = structuredValue.formattedValue;
+                // Set structuredValue
+                set(this, "effectiveValue", { structuredValue });
+                break;
+            default:
+                this.formattedValue = structuredValue.formattedValue;
+                // Set structuredValue
+                set(this, "effectiveValue", { structuredValue });
+                // Always set to left
+                break;
+        }
+    }
+    setEffectiveNumberValue(value) {
+        this.clearSharedStringIndex();
+        const numberFormat = this.userEnteredFormat?.numberFormat?.type ??
+            detectNumberFormatType(value, this.locale, this.lenientGrouping);
+        const numberValue = createNumberValue(value, numberFormat, this.locale, this.use1904, this.lenientGrouping);
+        const pattern = this.userEnteredFormat?.numberFormat?.pattern ??
+            detectNumberFormatPattern(value, numberValue, numberFormat, this.locale);
+        this.formattedValue = createFormattedValue(numberValue, "numberValue", pattern ?? this.defaultPattern, this.locale);
+        this.effectiveValue = { nv: numberValue };
+    }
+    setEffectiveStringValue(value) {
+        this.clearSharedStringIndex();
+        const stringValue = String(value);
+        this.effectiveValue = { sv: stringValue };
+        this.formattedValue = createFormattedValue(stringValue, "stringValue", this.defaultPattern, this.locale);
+    }
+    setEffectiveBooleanValue(value) {
+        this.clearSharedStringIndex();
+        this.effectiveValue = { bv: Boolean(value) };
+        this.formattedValue = createFormattedValue(value, "boolValue", this.defaultPattern, this.locale);
+    }
+    setHyperlink(hyperlink, title) {
+        const target = getHyperlinkTarget(hyperlink);
+        const display = title ?? getHyperlinkDisplay(hyperlink);
+        if (!target) {
+            return;
+        }
+        this.hyperlink = hyperlink;
+        if (display) {
+            this.clearSharedStringIndex();
+            this.formattedValue = display;
+            // Update both user entered and effective values
+            set(this, "userEnteredValue.sv", display);
+            set(this, "effectiveValue.sv", display);
+        }
+        else {
+            if (!this.formattedValue && target) {
+                this.formattedValue = target;
+            }
+            // Update both user entered and effective values with the URL if no
+            // title. `userEnteredValue` must be populated so consumers that read
+            // only `userEnteredValue` (e.g. the rnc-engine paste handler) see the
+            // pasted URL instead of an empty cell.
+            if (!display && target) {
+                set(this, "userEnteredValue.sv", target);
+                set(this, "effectiveValue.sv", target);
+            }
+        }
+        // Persist the hyperlink underline on `userEnteredFormat`. Writing to
+        // `effectiveFormat` here would silently drop on save/reload because
+        // `effectiveFormat` is derived at render time and not persisted (see
+        // the in-file note around `assign()` — `uf` is the single source of
+        // truth). Excel saves the underline as part of the cell's style.
+        this.ensureFormatsMutable();
+        set(this, "userEnteredFormat.textFormat.underline", true);
+    }
+    setUrl(url, title) {
+        this.setHyperlink(url, title);
+    }
+    deleteUrl() {
+        this.hyperlink = undefined;
+        // Excel parity: removing the hyperlink also removes the underline that
+        // was added when the hyperlink was applied. We only strip the
+        // underline (not the whole textFormat) so any user-applied bold /
+        // italic / color the user set on top of the hyperlink survives.
+        if (this.userEnteredFormat?.textFormat?.underline) {
+            this.ensureFormatsMutable();
+            delete this.userEnteredFormat.textFormat.underline;
+        }
+    }
+    setDataValidation(dataValidationId, dataValidationRule) {
+        this.dataValidationId = dataValidationId;
+        this.dataValidationRule = dataValidationRule;
+        // Excel parity: adding a validation rule (including a BOOLEAN /
+        // checkbox rule) does NOT mutate the cell's existing value. The rule
+        // is enforced on future edits — values that violate it get the
+        // standard "invalid value" indicator via `validate()` instead. The
+        // previous auto-coercion turned every cell into FALSE the moment a
+        // checkbox rule was applied, which destroyed user data.
+        this.validate();
+    }
+    deleteDataValidation() {
+        this.dataValidationId = undefined;
+        this.dataValidationRule = undefined;
+        // Remove any errors
+        delete this.effectiveValue?.ev;
+    }
+    clearUserEnteredFormat() {
+        this.userEnteredFormat = undefined;
+        this.originalUserEnteredFormat = undefined;
+    }
+    setUserEnteredFormat(type, value) {
+        if (type === "textFormat") {
+            this.setTextFormat(value);
+        }
+        else if (type === "numberFormat") {
+            this.setNumberFormat(value);
+        }
+        else if (type === "borders") {
+            this.setBorders(value);
+        }
+        else {
+            set(this, `userEnteredFormat.${type}`, value);
+        }
+    }
+    setTextFormat(value) {
+        this.ensureUserEnteredFormatMutable();
+        if (!this.userEnteredFormat) {
+            this.userEnteredFormat = {};
+        }
+        const existing = this.userEnteredFormat.textFormat;
+        const textFormat = existing && Object.isExtensible(existing)
+            ? existing
+            : { ...(existing ?? {}) };
+        this.userEnteredFormat.textFormat = textFormat;
+        const target = textFormat;
+        for (const key in value) {
+            if (Object.prototype.hasOwnProperty.call(value, key)) {
+                const finalValue = value[key];
+                if (isNil(finalValue)) {
+                    delete textFormat[key];
+                }
+                else {
+                    target[key] = finalValue;
+                }
+            }
+        }
+    }
+    setBorders(value) {
+        this.ensureUserEnteredFormatMutable();
+        if (!this.userEnteredFormat) {
+            this.userEnteredFormat = {};
+        }
+        const existing = this.userEnteredFormat.borders;
+        const borders = existing && Object.isExtensible(existing)
+            ? existing
+            : { ...(existing ?? {}) };
+        this.userEnteredFormat.borders = borders;
+        for (const key in value) {
+            if (Object.prototype.hasOwnProperty.call(value, key)) {
+                const borderValue = value[key];
+                if (borderValue === null || borderValue === undefined) {
+                    delete borders[key];
+                }
+                else if (!borderValue.color) {
+                    delete borders[key];
+                }
+                else {
+                    borders[key] = borderValue;
+                }
+            }
+        }
+    }
+    setNumberFormat(value) {
+        const previousFormatType = this.userEnteredFormat?.numberFormat?.type;
+        const numberFormatType = value?.type;
+        const hasUserEnteredValue = this.getUserEnteredValue() !== undefined;
+        if (!isNil(this.sharedStringIndex) &&
+            numberFormatType &&
+            numberFormatType !== "TEXT") {
+            return;
+        }
+        set(this, "userEnteredFormat.numberFormat", value);
+        const effectiveValue = this.getEffectiveValue();
+        if (effectiveValue === null || effectiveValue === undefined) {
+            return;
+        }
+        if (numberFormatType === "TEXT") {
+            const userValue = this.getUserEnteredValue();
+            this.formatAsText(userValue ?? effectiveValue, value, !hasUserEnteredValue);
+        }
+        else {
+            const preserveUserEnteredText = previousFormatType === "TEXT";
+            this.formatAsNumber(effectiveValue, value, preserveUserEnteredText, !hasUserEnteredValue);
+        }
+    }
+    formatAsText(effectiveValue, numberFormat, keepUserEnteredUnset = false) {
+        const textValue = String(effectiveValue);
+        this.formattedValue = createFormattedValue(effectiveValue, "stringValue", numberFormat?.pattern ?? this.defaultPattern, this.locale);
+        delete this.imageUrl;
+        delete this.hyperlink;
+        if (!keepUserEnteredUnset) {
+            set(this, "userEnteredValue", { sv: textValue });
+        }
+        set(this, "effectiveValue", { sv: textValue });
+    }
+    formatAsNumber(effectiveValue, numberFormat, preserveUserEnteredText = false, keepUserEnteredUnset = false) {
+        const isDate = this.isDate(numberFormat);
+        const isDateTime = this.isDateTime(numberFormat);
+        const parsedNumberValue = createNumberValue(effectiveValue, numberFormat?.type, this.locale, this.use1904, this.lenientGrouping);
+        const hasValidNumberValue = typeof parsedNumberValue === "number" && !Number.isNaN(parsedNumberValue);
+        // When conversion fails for plain text (e.g. "hello"), keep displaying text
+        // instead of showing "NaN" while still preserving the selected number format.
+        // Excel parity: the cell's pattern still applies via its `@` (text)
+        // section — e.g. `"Note: "@` renders `Note: hello`, and a `[Magenta]@`
+        // segment colors the text. Falling back to `defaultPattern` here would
+        // silently drop the user-applied custom format from the display.
+        if (!hasValidNumberValue && typeof effectiveValue === "string") {
+            const textValue = String(effectiveValue);
+            this.formattedValue = createFormattedValue(textValue, "stringValue", numberFormat?.pattern ?? this.defaultPattern, this.locale);
+            if (!keepUserEnteredUnset &&
+                (!preserveUserEnteredText || this.userEnteredValue?.sv === undefined)) {
+                set(this, "userEnteredValue", { sv: textValue });
+            }
+            set(this, "effectiveValue", { sv: textValue });
+            return;
+        }
+        const numberValue = parsedNumberValue === undefined ? effectiveValue : parsedNumberValue;
+        this.formattedValue = createFormattedValue(numberValue, "numberValue", numberFormat?.pattern ?? this.defaultPattern, this.locale);
+        const stringValue = isDate || isDateTime
+            ? createFormattedValue(numberValue, "numberValue", isDate ? getDefaultDateFormat(this.locale) : getDefaultTimeFormat(this.locale), this.locale)
+            : numberFormat?.type === "PERCENT"
+                ? this.formattedValue
+                : String(numberValue);
+        if (!keepUserEnteredUnset &&
+            (!preserveUserEnteredText || this.userEnteredValue?.sv === undefined)) {
+            set(this, "userEnteredValue.sv", stringValue);
+        }
+        set(this, "effectiveValue.nv", preserveUserEnteredText ? String(numberValue) : numberValue);
+        // Default horizontal alignment for numbers/dates/currency is computed
+        // at render time by `getDefaultHorizontalAlignment` in canvas-grid —
+        // we deliberately do NOT stamp `uf.horizontalAlignment` here so the
+        // user's explicit alignment choice (or its absence) is preserved.
+    }
+    getEffectiveValue() {
+        if (!this.effectiveValue) {
+            return undefined;
+        }
+        return (getExtendedValueNumber(this.effectiveValue) ??
+            getExtendedValueString(this.effectiveValue) ??
+            getExtendedValueBool(this.effectiveValue));
+    }
+    getUserEnteredValue() {
+        if (!this.userEnteredValue) {
+            return undefined;
+        }
+        return (getExtendedValueFormula(this.userEnteredValue) ??
+            getExtendedValueNumber(this.userEnteredValue) ??
+            getExtendedValueString(this.userEnteredValue) ??
+            getExtendedValueBool(this.userEnteredValue));
+    }
+    getNumberFormat() {
+        return this.userEnteredFormat?.numberFormat;
+    }
+    processDerivedCell(cellData) {
+        // Image url
+        if (cellData.imageUrl) {
+            this.setImage(cellData.imageUrl);
+        }
+        // Set formatted value for hyperlink
+        if (cellData.hyperlink) {
+            this.setHyperlink(cellData.hyperlink, getCellFormattedValue(cellData));
+        }
+        const structuredValue = getCellEffectiveValue(cellData)?.structuredValue;
+        if (structuredValue) {
+            this.setStructuredValue(structuredValue);
+        }
+    }
+    // Excel parity: xlsx files often carry a `numberFormat.pattern` without
+    // a corresponding `type` (the Google-Sheets style category that we layer
+    // on top). Fall back to inspecting the pattern itself so DATE / DATE_TIME
+    // / TEXT cells imported from Excel render and serialize correctly.
+    isDate(numberFormat) {
+        if (numberFormat?.type === "DATE")
+            return true;
+        if (numberFormat?.type)
+            return false;
+        return (isDatePattern(numberFormat?.pattern) &&
+            !isDateTimePattern(numberFormat?.pattern));
+    }
+    isDateTime(numberFormat) {
+        if (numberFormat?.type === "DATE_TIME")
+            return true;
+        if (numberFormat?.type)
+            return false;
+        return isDateTimePattern(numberFormat?.pattern);
+    }
+    isText(numberFormat) {
+        if (numberFormat?.type === "TEXT")
+            return true;
+        if (numberFormat?.type)
+            return false;
+        return isTextPattern(numberFormat?.pattern);
+    }
+    setGroupKeys(groupKeys) {
+        this.groupKeys = groupKeys;
+        if (groupKeys) {
+            // If a cell is not expandable and has group keys
+            // its the last child the group. Indent persists on uf so the
+            // renderer (and exporters) see it.
+            const indent = (groupKeys.length - 1) * 2 + (this.expandable ? 0 : 4);
+            if (!this.userEnteredFormat) {
+                this.userEnteredFormat = {};
+            }
+            this.userEnteredFormat.indent = Math.max(0, indent);
+        }
+    }
+    changeIndent(size = 1) {
+        const indent = this.userEnteredFormat?.indent ?? 0;
+        if (!this.userEnteredFormat) {
+            this.userEnteredFormat = {};
+        }
+        this.userEnteredFormat.indent = Math.max(0, indent + size);
+    }
+    setPivotId(pivotId) {
+        this.pivotId = pivotId;
+    }
+    expand() {
+        this.expanded = true;
+    }
+    collapse() {
+        this.expanded = false;
+    }
+    setExpandable(expandable) {
+        this.expandable = expandable;
+    }
+    setArrayFormulaRef(ref) {
+        this.arrayFormulaRef = ref ?? undefined;
+    }
+    clearArrayFormulaRef() {
+        if (!this.arrayFormulaRef) {
+            return;
+        }
+        this.arrayFormulaRef = undefined;
+    }
+    setSharedFormulaSpec(spec) {
+        this.sharedFormulaSpec = spec
+            ? { si: spec.si, ...(spec.ref ? { ref: spec.ref } : {}) }
+            : undefined;
+    }
+    clearSharedFormulaSpec() {
+        if (!this.sharedFormulaSpec) {
+            return;
+        }
+        this.sharedFormulaSpec = undefined;
+    }
+    increaseIndent() {
+        this.changeIndent(2);
+    }
+    decreaseIndent() {
+        this.changeIndent(-2);
+    }
+    clearFormatting() {
+        this.userEnteredFormat = undefined;
+        this.originalUserEnteredFormat = undefined;
+    }
+    clearHyperlink() {
+        this.hyperlink = undefined;
+    }
+    // Inherit a different set of cell data
+    inheritCellData(cellData) {
+        this.cellData = cellData;
+    }
+    getUserCellData() {
+        if (!this.cellData)
+            return undefined;
+        const result = {};
+        for (const key in this.cellData) {
+            if (!excludeKeys.has(key)) {
+                result[key] = this.cellData[key];
+            }
+        }
+        return Object.keys(result).length > 0 ? result : undefined;
+    }
+    extendCellData(newCellData) {
+        this.assign(this.sheetId, this.coords, newCellData, {
+            getRangeValues: this.getRangeValues,
+            locale: this.locale,
+            cellXfsRegistry: this.cellXfsRegistry,
+            sharedStringRegistry: this.sharedStringRegistry,
+        });
+    }
+    getUserEnteredFormat() {
+        if (isStyleReference(this.originalUserEnteredFormat) &&
+            !this.cellXfsRegistry) {
+            return this.originalUserEnteredFormat;
+        }
+        return this.userEnteredFormat;
+    }
+    /**
+     * Returns the user-entered format. The "effective" format (uf + auto-
+     * derived alignment / pattern color / formula-precedent number format /
+     * conditional formatting) is computed at render time by
+     * `useSheetProperties.getEffectiveFormat`. SheetCell no longer maintains
+     * a separate in-memory effective format.
+     *
+     * Loading-state alignment override is preserved for legacy callers that
+     * sniff this method while a cell is being recalculated.
+     */
+    getEffectiveCellFormat() {
+        if (!this.userEnteredFormat && !this.isLoading) {
+            return undefined;
+        }
+        if (this.isLoading) {
+            return {
+                ...(this.userEnteredFormat ?? {}),
+                horizontalAlignment: "center",
+            };
+        }
+        return this.userEnteredFormat ?? undefined;
+    }
+    getCellFormats(disableRegistry) {
+        // `ef` is no longer persisted: rendering derives the effective format
+        // on the fly from `uf`, the cell value, and (for formulas) precedent
+        // formats. The renderer caches the derivation so this stays cheap.
+        //
+        // Fall back to `originalUserEnteredFormat` when we never resolved a
+        // CellFormat — happens when assign() ran without a cellXfsRegistry on
+        // input that already had `uf: { sid: ... }` (e.g. the sheet-rename
+        // formula round-trip). Without this fallback the StyleReference is
+        // silently dropped on the way out.
+        const format = this.userEnteredFormat ?? this.originalUserEnteredFormat;
+        if (!format)
+            return {};
+        if (!disableRegistry &&
+            this.cellXfsRegistry?.active &&
+            this.userEnteredFormat) {
+            return { uf: { sid: getCellXfsKey(this.userEnteredFormat) } };
+        }
+        return { uf: { ...format } };
+    }
+    get isModified() {
+        return !isEqual(this.cellData, this.getCellData());
+    }
+    getCellData(options) {
+        const hasSharedString = this.sharedStringIndex != null;
+        const hasEffectiveError = Boolean(getExtendedValueError(this.effectiveValue));
+        const useSharedString = hasSharedString;
+        // Formula cells no longer persist `fv`: the renderer derives it from
+        // `effectiveValue` + the resolved number format and caches the result.
+        // Structured-value formula cells (sparkline/image/hyperlink) still get
+        // their display text from `effectiveValue.structuredValue` itself, so
+        // we don't need to write `fv` either.
+        //
+        // Exception: when `isLoading` is true, persist `fv = loadingValue` even
+        // for formula cells (and even when a prior `effectiveValue` is on the
+        // cell). The renderer surfaces "Loading..." while a recalc is in
+        // flight; calc-success clears it by writing the cell back through
+        // getCellData with isLoading=false.
+        const isFormulaCell = !!getExtendedValueFormula(this.userEnteredValue);
+        const shouldPersistFormattedValue = !useSharedString &&
+            (this.isLoading || (!isFormulaCell && this.formattedValue));
+        const newCellData = {
+            ...this.getUserCellData(),
+            // Rich-text runs are persisted on the SharedStrings entry the
+            // cell references via `ss`, not on `cellData`. See
+            // `SharedStringRegistry.registerCell` for the write path.
+            ...(this.conditionalFormattingResultById
+                ? {
+                    conditionalFormattingResultById: this.conditionalFormattingResultById,
+                }
+                : {}),
+            ...(this.dataValidationResult
+                ? { dataValidationResult: this.dataValidationResult }
+                : {}),
+            ...(!useSharedString && this.userEnteredValue
+                ? {
+                    ue: this.userEnteredValue,
+                }
+                : {}),
+            ...(this.effectiveValue && (!useSharedString || hasEffectiveError)
+                ? {
+                    ev: this.effectiveValue,
+                }
+                : {}),
+            ...(shouldPersistFormattedValue
+                ? {
+                    fv: this.isLoading ? this.loadingValue : this.formattedValue,
+                }
+                : undefined),
+            ...(hasSharedString
+                ? {
+                    ss: typeof this.sharedStringIndex === "string"
+                        ? this.sharedStringIndex
+                        : String(this.sharedStringIndex),
+                }
+                : {}),
+            ...this.getCellFormats(options?.disableRegistry),
+            ...(this.dataValidationId
+                ? {
+                    dataValidation: this.dataValidationId,
+                }
+                : {}),
+            ...(this.imageUrl
+                ? {
+                    imageUrl: this.imageUrl,
+                }
+                : {}),
+            ...(this.hyperlink
+                ? {
+                    hyperlink: this.hyperlink,
+                }
+                : {}),
+            ...(this.metaType ? { metaType: this.metaType } : {}),
+            ...(this.pivotId ? { pivotId: this.pivotId } : {}),
+            ...(this.groupKeys ? { groupKeys: this.groupKeys } : {}),
+            // Disable version and updatedAt for now
+            // ...(this.version != null ? { version: this.version } : {}),
+            // ...(this.updatedAt != null ? { updatedAt: this.updatedAt } : {}),
+            ...(this.note ? { note: this.note } : {}),
+            ...(!isNil(this.commentThreadId)
+                ? { commentThreadId: this.commentThreadId }
+                : {}),
+            ...(!isNil(this.citationId) ? { citationId: this.citationId } : {}),
+            ...(this.expandable
+                ? {
+                    expandable: this.expandable,
+                    expanded: this.expanded,
+                }
+                : {}),
+            ...(this.arrayFormulaRef ? { af: this.arrayFormulaRef } : {}),
+            ...(this.sharedFormulaSpec
+                ? {
+                    sf: {
+                        si: this.sharedFormulaSpec.si,
+                        ...(this.sharedFormulaSpec.ref
+                            ? { ref: this.sharedFormulaSpec.ref }
+                            : {}),
+                    },
+                }
+                : {}),
+        };
+        if (newCellData && Object.keys(newCellData).length === 0) {
+            return null;
+        }
+        return newCellData;
+    }
+}