@rowsncolumns/toolkit 24.5.3 → 24.5.5

package/dist/cjs/helpers/excel-formula-prefixes.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Every function Excel stores behind `_xlfn.` (uppercase). One list for both
+ * directions: the exporter qualifies exactly these; the importer strips any
+ * marker it finds, list or not, so a newer function still opens cleanly.
+ */
+export declare const FUTURE_FUNCTION_NAMES: readonly string[];
+/**
+ * Future functions that Excel writes behind the worksheet-scope prefix
+ * (`_xlfn._xlws.`) rather than plain `_xlfn.` — the dynamic-array functions
+ * that also exist as worksheet-only names, plus Python in Excel.
+ */
+export declare const WORKSHEET_SCOPED_FUTURE_FUNCTIONS: ReadonlySet<string>;
+/**
+ * Remove every `_xlfn.` / `_xlws.` / `_xlpm.` / `_xludf.` storage marker from
+ * `formula` (outside string literals and quoted sheet names). Idempotent.
+ */
+export declare function stripExcelFormulaPrefixes(formula: string): string;
+/**
+ * `_xlfn.ANCHORARRAY(A1)` / `ANCHORARRAY(Sheet1!A1)` → `A1#` / `Sheet1!A1#`
+ * — Excel's stored form of the spilled-range operator back to its UI form.
+ * A call whose argument is not exactly one cell reference is left as is.
+ */
+export declare function decodeAnchorArray(formula: string): string;
+/**
+ * `A1#` / `Sheet1!A1#` → `ANCHORARRAY(A1)` / `ANCHORARRAY(Sheet1!A1)` — the
+ * spilled-range operator in the form sheet XML accepts (future-function
+ * qualification then adds the `_xlfn.` prefix). `#REF!#` is left alone.
+ */
+export declare function encodeSpilledRanges(formula: string): string;
+/**
+ * Prefix every LET / LAMBDA parameter with `_xlpm.` — at its declaration and
+ * at every use inside the call (a use as a function, `double(5)` for a
+ * LET-bound lambda, included). Parameters are the odd-position LET arguments
+ * (all but the last argument, which is the calculation) and every LAMBDA
+ * argument but the last. Already-prefixed input comes out prefixed once.
+ */
+export declare function qualifyLambdaParameters(formula: string): string;
+/**
+ * Export direction. Strip the storage markers and re-add the correct one to
+ * every future-function call in `formula`, write `A1#` as `ANCHORARRAY(A1)`
+ * (qualified to `_xlfn.ANCHORARRAY`) and prefix LET / LAMBDA parameters with
+ * `_xlpm.`. Quoted spans keep their original text. Idempotent: already
+ * qualified input comes out qualified exactly once.
+ */
+export declare function qualifyFutureFunctions(formula: string): string;
+/**
+ * Import direction. The formula as Excel displays it: every storage marker
+ * removed, `_xlfn.ANCHORARRAY(A1)` shown as `A1#`, `_xlfn.SINGLE(x)` as `@x`.
+ */
+export declare function normalizeImportedFormula(formula: string): string;
+//# sourceMappingURL=excel-formula-prefixes.d.ts.map

package/dist/cjs/helpers/excel-formula-prefixes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"excel-formula-prefixes.d.ts","sourceRoot":"","sources":["../../../helpers/excel-formula-prefixes.ts"],"names":[],"mappings":"AAoCA;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EA+KlD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,EAAE,WAAW,CAAC,MAAM,CAIhE,CAAC;AA4FH;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjE;AAuDD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CA6BzD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAkB3D;AA0CD;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAgD/D;AAID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIhE"}

package/dist/cjs/helpers/excel-formula-prefixes.js

@@ -0,0 +1,548 @@
+import { __read, __spreadArray, __values } from "tslib";
+/**
+ * Excel's file-format spelling of modern formulas, in both directions.
+ *
+ * The .xlsx grammar was frozen with Excel 2007, so every function added since
+ * is stored behind a namespace prefix the UI never shows:
+ *
+ * - `_xlfn.NAME(`        — a "future function" (`_xlfn.XLOOKUP(`, `_xlfn.IFS(`);
+ * - `_xlfn._xlws.NAME(`  — the worksheet-scoped dynamic-array functions
+ *                          (`_xlfn._xlws.FILTER(`, `_xlfn._xlws.SORT(`, `_xlfn._xlws.PY(`);
+ * - `_xlpm.name`         — every LET / LAMBDA parameter, at its declaration
+ *                          and at every use (`_xlfn.LET(_xlpm.x,A1,_xlpm.x+1)`);
+ * - `_xlfn.ANCHORARRAY(A1)` — the spilled-range operator `A1#`;
+ * - `_xlfn.SINGLE(x)`    — the implicit-intersection operator `@x`;
+ * - `_xludf.NAME(`       — a user-defined (add-in) function.
+ *
+ * Written bare, Excel does not resolve a future function: it renders the call
+ * behind the implicit-intersection operator (`=@DAYS(...)`) and evaluates
+ * `#NAME?`. Kept prefixed in the engine, `SUM(_xlfn.ANCHORARRAY(A1))` is a
+ * `#NAME?` and the formula bar shows `=_xlfn.XLOOKUP(`. So the importer
+ * removes every marker ({@link normalizeImportedFormula}) and the exporter
+ * re-adds them from one list ({@link qualifyFutureFunctions}); a formula
+ * round-trips unchanged.
+ *
+ * The list follows Microsoft's documentation of `_xlfn.`-prefixed functions
+ * ("Issue: An _xlfn. prefix is displayed in front of a function in a
+ * formula", support.microsoft.com) plus the dynamic-array / LAMBDA-era, 2024
+ * and Python-in-Excel additions that ship with the same prefix convention.
+ */
+import { lexify, tokenVocabulary } from "@rowsncolumns/calculator";
+import { decodeImplicitIntersection } from "./implicit-intersection";
+var T = tokenVocabulary;
+/**
+ * Every function Excel stores behind `_xlfn.` (uppercase). One list for both
+ * directions: the exporter qualifies exactly these; the importer strips any
+ * marker it finds, list or not, so a newer function still opens cleanly.
+ */
+export var FUTURE_FUNCTION_NAMES = [
+    "ACOT",
+    "ACOTH",
+    "AGGREGATE",
+    "ANCHORARRAY",
+    "ARABIC",
+    "ARRAYTOTEXT",
+    "BASE",
+    "BETA.DIST",
+    "BETA.INV",
+    "BINOM.DIST",
+    "BINOM.DIST.RANGE",
+    "BINOM.INV",
+    "BITAND",
+    "BITLSHIFT",
+    "BITOR",
+    "BITRSHIFT",
+    "BITXOR",
+    "BYCOL",
+    "BYROW",
+    "CEILING.MATH",
+    "CEILING.PRECISE",
+    "CHISQ.DIST",
+    "CHISQ.DIST.RT",
+    "CHISQ.INV",
+    "CHISQ.INV.RT",
+    "CHISQ.TEST",
+    "CHOOSECOLS",
+    "CHOOSEROWS",
+    "COMBINA",
+    "CONCAT",
+    "CONFIDENCE.NORM",
+    "CONFIDENCE.T",
+    "COT",
+    "COTH",
+    "COVARIANCE.P",
+    "COVARIANCE.S",
+    "CSC",
+    "CSCH",
+    "DAYS",
+    "DECIMAL",
+    "DETECTLANGUAGE",
+    "DROP",
+    "ENCODEURL",
+    "ERF.PRECISE",
+    "ERFC.PRECISE",
+    "EXPAND",
+    "EXPON.DIST",
+    "F.DIST",
+    "F.DIST.RT",
+    "F.INV",
+    "F.INV.RT",
+    "F.TEST",
+    "FIELDVALUE",
+    "FILTER",
+    "FILTERXML",
+    "FLOOR.MATH",
+    "FLOOR.PRECISE",
+    "FORECAST.ETS",
+    "FORECAST.ETS.CONFINT",
+    "FORECAST.ETS.SEASONALITY",
+    "FORECAST.ETS.STAT",
+    "FORECAST.LINEAR",
+    "FORMULATEXT",
+    "GAMMA",
+    "GAMMA.DIST",
+    "GAMMA.INV",
+    "GAMMALN.PRECISE",
+    "GAUSS",
+    "GROUPBY",
+    "HSTACK",
+    "HYPGEOM.DIST",
+    "IFNA",
+    "IFS",
+    "IMAGE",
+    "IMCOSH",
+    "IMCOT",
+    "IMCSC",
+    "IMCSCH",
+    "IMSEC",
+    "IMSECH",
+    "IMSINH",
+    "IMTAN",
+    "ISFORMULA",
+    "ISOMITTED",
+    "ISOWEEKNUM",
+    "LAMBDA",
+    "LET",
+    "LOGNORM.DIST",
+    "LOGNORM.INV",
+    "MAKEARRAY",
+    "MAP",
+    "MAXIFS",
+    "MINIFS",
+    "MODE.MULT",
+    "MODE.SNGL",
+    "MUNIT",
+    "NEGBINOM.DIST",
+    "NETWORKDAYS.INTL",
+    "NORM.DIST",
+    "NORM.INV",
+    "NORM.S.DIST",
+    "NORM.S.INV",
+    "NUMBERVALUE",
+    "PDURATION",
+    "PERCENTILE.EXC",
+    "PERCENTILE.INC",
+    "PERCENTOF",
+    "PERCENTRANK.EXC",
+    "PERCENTRANK.INC",
+    "PERMUTATIONA",
+    "PHI",
+    "PIVOTBY",
+    "POISSON.DIST",
+    "PQSOURCE",
+    "PY",
+    "PYTHON_STR",
+    "PYTHON_TYPE",
+    "PYTHON_TYPENAME",
+    "QUARTILE.EXC",
+    "QUARTILE.INC",
+    "QUERYSTRING",
+    "RANDARRAY",
+    "RANK.AVG",
+    "RANK.EQ",
+    "REDUCE",
+    "REGEXEXTRACT",
+    "REGEXREPLACE",
+    "REGEXTEST",
+    "RRI",
+    "SCAN",
+    "SEC",
+    "SECH",
+    "SEQUENCE",
+    "SHEET",
+    "SHEETS",
+    "SINGLE",
+    "SKEW.P",
+    "SORT",
+    "SORTBY",
+    "STDEV.P",
+    "STDEV.S",
+    "STOCKHISTORY",
+    "SWITCH",
+    "T.DIST",
+    "T.DIST.2T",
+    "T.DIST.RT",
+    "T.INV",
+    "T.INV.2T",
+    "T.TEST",
+    "TAKE",
+    "TEXTAFTER",
+    "TEXTBEFORE",
+    "TEXTJOIN",
+    "TEXTSPLIT",
+    "TOCOL",
+    "TOROW",
+    "TRANSLATE",
+    "TRIMRANGE",
+    "UNICHAR",
+    "UNICODE",
+    "UNIQUE",
+    "VALUETOTEXT",
+    "VAR.P",
+    "VAR.S",
+    "VSTACK",
+    "WEBSERVICE",
+    "WEIBULL.DIST",
+    "WORKDAY.INTL",
+    "WRAPCOLS",
+    "WRAPROWS",
+    "XLOOKUP",
+    "XMATCH",
+    "XOR",
+    "Z.TEST",
+];
+/**
+ * Future functions that Excel writes behind the worksheet-scope prefix
+ * (`_xlfn._xlws.`) rather than plain `_xlfn.` — the dynamic-array functions
+ * that also exist as worksheet-only names, plus Python in Excel.
+ */
+export var WORKSHEET_SCOPED_FUTURE_FUNCTIONS = new Set([
+    "FILTER",
+    "SORT",
+    "PY",
+]);
+var QUALIFIED_BY_NAME = new Map(FUTURE_FUNCTION_NAMES.map(function (name) { return [
+    name,
+    WORKSHEET_SCOPED_FUTURE_FUNCTIONS.has(name)
+        ? "_xlfn._xlws.".concat(name)
+        : "_xlfn.".concat(name),
+]; }));
+// Longest names first so `T.DIST.2T` wins over `T.DIST`. The match must be
+// followed by `(` — a bare name (e.g. the defined name `DAYS`) is not a call.
+var FUTURE_FUNCTION_REGEX = new RegExp("(" +
+    __spreadArray([], __read(FUTURE_FUNCTION_NAMES), false).sort(function (a, b) { return b.length - a.length; })
+        .map(function (name) { return name.replace(/\./g, "\\."); })
+        .join("|") +
+    ")(\\s*\\()", "gi");
+// `\b` is not enough of a left boundary: it would match the `DAYS` in
+// `_xlfn.DAYS` and in `MYDAYS`. The preceding character is checked by offset
+// instead of being consumed by the pattern, so nested calls
+// (`SORT(FILTER(...))`) still match after the enclosing one.
+var FUTURE_FUNCTION_LEFT_BOUNDARY = /[A-Za-z0-9_.$]/;
+// A storage marker starts an identifier: nothing identifier-like may precede
+// it (`MY_xlfn.X` is one name). `_xlfn._xlws.FILTER` strips in two passes.
+var STORAGE_PREFIX_REGEX = /(?<![A-Za-z0-9_])_xl(?:fn|ws|pm|udf)\./gi;
+/**
+ * Run `transform` over every unquoted span of `formula`, copying string
+ * literals (`"…"`) and quoted sheet names (`'…'`) verbatim. A doubled quote
+ * inside a span is an escaped quote; an unterminated literal consumes the
+ * rest of the formula.
+ */
+function mapUnquotedSegments(formula, transform) {
+    var result = "";
+    var segmentStart = 0;
+    var index = 0;
+    while (index < formula.length) {
+        var char = formula[index];
+        if (char !== '"' && char !== "'") {
+            index++;
+            continue;
+        }
+        result += transform(formula.slice(segmentStart, index));
+        var end = index + 1;
+        while (end < formula.length) {
+            if (formula[end] === char) {
+                if (formula[end + 1] === char) {
+                    end += 2;
+                    continue;
+                }
+                break;
+            }
+            end++;
+        }
+        var literalEnd = end < formula.length ? end + 1 : formula.length;
+        result += formula.slice(index, literalEnd);
+        index = literalEnd;
+        segmentStart = literalEnd;
+    }
+    return result + transform(formula.slice(segmentStart));
+}
+var stripSegment = function (segment) {
+    return segment.replace(STORAGE_PREFIX_REGEX, "");
+};
+function qualifySegment(segment) {
+    var stripped = stripSegment(segment);
+    return stripped.replace(FUTURE_FUNCTION_REGEX, function (match, name, open, offset) {
+        if (offset > 0 &&
+            FUTURE_FUNCTION_LEFT_BOUNDARY.test(stripped[offset - 1])) {
+            return match;
+        }
+        var qualified = QUALIFIED_BY_NAME.get(name.toUpperCase());
+        return qualified ? qualified + open : match;
+    });
+}
+/**
+ * Remove every `_xlfn.` / `_xlws.` / `_xlpm.` / `_xludf.` storage marker from
+ * `formula` (outside string literals and quoted sheet names). Idempotent.
+ */
+export function stripExcelFormulaPrefixes(formula) {
+    return mapUnquotedSegments(formula, stripSegment);
+}
+// ---------------------------------------------------------------- token helpers
+var tokenName = function (token) { var _a; return (_a = token === null || token === void 0 ? void 0 : token.tokenType) === null || _a === void 0 ? void 0 : _a.name; };
+var tokenEnd = function (token) { var _a; return ((_a = token.endOffset) !== null && _a !== void 0 ? _a : token.startOffset) + 1; };
+/** Index of the `)` closing the call / group that opens at `start`, or -1. */
+var closeParenOf = function (tokens, start) {
+    var depth = 0;
+    for (var i = start; i < tokens.length; i++) {
+        var name_1 = tokenName(tokens[i]);
+        if (name_1 === T.Function.name || name_1 === T.OpenParen.name)
+            depth++;
+        else if (name_1 === T.CloseParen.name)
+            depth--;
+        if (depth === 0)
+            return i;
+    }
+    return -1;
+};
+var isSheetPrefix = function (token) {
+    var name = tokenName(token);
+    return (name === T.Sheet.name ||
+        name === T.SheetQuoted.name ||
+        name === T.SheetRange.name);
+};
+/** Apply non-overlapping `[start, end)` replacements to `source`. */
+var applyReplacements = function (source, replacements) {
+    var e_1, _a;
+    var sorted = __spreadArray([], __read(replacements), false).sort(function (a, b) { return a.start - b.start; });
+    var out = "";
+    var cursor = 0;
+    try {
+        for (var sorted_1 = __values(sorted), sorted_1_1 = sorted_1.next(); !sorted_1_1.done; sorted_1_1 = sorted_1.next()) {
+            var r = sorted_1_1.value;
+            if (r.start < cursor)
+                continue;
+            out += source.slice(cursor, r.start) + r.text;
+            cursor = r.end;
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (sorted_1_1 && !sorted_1_1.done && (_a = sorted_1.return)) _a.call(sorted_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return out + source.slice(cursor);
+};
+var safeLexify = function (formula) {
+    try {
+        return lexify(formula).tokens;
+    }
+    catch (_a) {
+        return undefined;
+    }
+};
+// ---------------------------------------------------------------- spilled-range operator
+var ANCHORARRAY_CALL = /^(?:_xlfn\.)?ANCHORARRAY\($/i;
+/**
+ * `_xlfn.ANCHORARRAY(A1)` / `ANCHORARRAY(Sheet1!A1)` → `A1#` / `Sheet1!A1#`
+ * — Excel's stored form of the spilled-range operator back to its UI form.
+ * A call whose argument is not exactly one cell reference is left as is.
+ */
+export function decodeAnchorArray(formula) {
+    var tokens = safeLexify(formula);
+    if (!tokens)
+        return formula;
+    var replacements = [];
+    for (var i = 0; i < tokens.length; i++) {
+        var token = tokens[i];
+        if (tokenName(token) !== T.Function.name ||
+            !ANCHORARRAY_CALL.test(token.image)) {
+            continue;
+        }
+        var close_1 = closeParenOf(tokens, i);
+        if (close_1 === -1)
+            continue;
+        var inner = tokens.slice(i + 1, close_1);
+        var cell = inner[inner.length - 1];
+        var isCell = cell !== undefined &&
+            tokenName(cell) === T.Cell.name &&
+            !cell.image.endsWith("#") &&
+            (inner.length === 1 || (inner.length === 2 && isSheetPrefix(inner[0])));
+        if (!isCell)
+            continue;
+        replacements.push({
+            start: token.startOffset,
+            end: tokenEnd(tokens[close_1]),
+            text: "".concat(formula.slice(inner[0].startOffset, tokenEnd(cell)), "#"),
+        });
+    }
+    return replacements.length ? applyReplacements(formula, replacements) : formula;
+}
+/**
+ * `A1#` / `Sheet1!A1#` → `ANCHORARRAY(A1)` / `ANCHORARRAY(Sheet1!A1)` — the
+ * spilled-range operator in the form sheet XML accepts (future-function
+ * qualification then adds the `_xlfn.` prefix). `#REF!#` is left alone.
+ */
+export function encodeSpilledRanges(formula) {
+    var tokens = safeLexify(formula);
+    if (!tokens)
+        return formula;
+    var replacements = [];
+    for (var i = 0; i < tokens.length; i++) {
+        var token = tokens[i];
+        if (tokenName(token) !== T.Cell.name || !token.image.endsWith("#")) {
+            continue;
+        }
+        var first = isSheetPrefix(tokens[i - 1]) ? tokens[i - 1] : token;
+        var ref = formula.slice(first.startOffset, tokenEnd(token) - 1);
+        replacements.push({
+            start: first.startOffset,
+            end: tokenEnd(token),
+            text: "ANCHORARRAY(".concat(ref, ")"),
+        });
+    }
+    return replacements.length ? applyReplacements(formula, replacements) : formula;
+}
+// ---------------------------------------------------------------- LET / LAMBDA parameters
+var LET_CALL = /^(?:_xlfn\.)?LET\($/i;
+var LAMBDA_CALL = /^(?:_xlfn\.)?LAMBDA\($/i;
+var PARAMETER_MARKER = /^_xlpm\./i;
+/**
+ * A bare identifier at `index`: a `Name`, or a one-to-three-letter word the
+ * lexer reads as a whole-column reference (`x`, `acc`) when it is not part of
+ * an `A:A` column range.
+ */
+var isIdentifier = function (tokens, index) {
+    var name = tokenName(tokens[index]);
+    if (name === T.Name.name)
+        return true;
+    if (name !== T.Column.name)
+        return false;
+    if (/[$\d]/.test(tokens[index].image))
+        return false;
+    return (tokenName(tokens[index - 1]) !== T.Colon.name &&
+        tokenName(tokens[index + 1]) !== T.Colon.name);
+};
+/** `a, b, c` → the token index ranges of the top-level arguments of a call. */
+var topLevelArguments = function (tokens, open, close) {
+    var args = [];
+    var depth = 0;
+    var start = open + 1;
+    for (var i = open + 1; i < close; i++) {
+        var name_2 = tokenName(tokens[i]);
+        if (name_2 === T.Function.name || name_2 === T.OpenParen.name)
+            depth++;
+        else if (name_2 === T.CloseParen.name)
+            depth--;
+        else if (depth === 0 && (name_2 === T.Comma.name || name_2 === T.Semicolon.name)) {
+            args.push([start, i - 1]);
+            start = i + 1;
+        }
+    }
+    if (start <= close - 1)
+        args.push([start, close - 1]);
+    return args;
+};
+/**
+ * Prefix every LET / LAMBDA parameter with `_xlpm.` — at its declaration and
+ * at every use inside the call (a use as a function, `double(5)` for a
+ * LET-bound lambda, included). Parameters are the odd-position LET arguments
+ * (all but the last argument, which is the calculation) and every LAMBDA
+ * argument but the last. Already-prefixed input comes out prefixed once.
+ */
+export function qualifyLambdaParameters(formula) {
+    var tokens = safeLexify(formula);
+    if (!tokens)
+        return formula;
+    var replacements = new Map();
+    var _loop_1 = function (i) {
+        var token = tokens[i];
+        if (tokenName(token) !== T.Function.name)
+            return "continue";
+        var isLet = LET_CALL.test(token.image);
+        var isLambda = !isLet && LAMBDA_CALL.test(token.image);
+        if (!isLet && !isLambda)
+            return "continue";
+        var close_2 = closeParenOf(tokens, i);
+        if (close_2 === -1)
+            return "continue";
+        var args = topLevelArguments(tokens, i, close_2);
+        var params = new Set();
+        args.forEach(function (_a, index) {
+            var _b = __read(_a, 2), start = _b[0], end = _b[1];
+            var isLast = index === args.length - 1;
+            var isParameter = isLambda ? !isLast : index % 2 === 0 && !isLast;
+            if (!isParameter || start !== end)
+                return;
+            var arg = tokens[start];
+            if (!isIdentifier(tokens, start))
+                return;
+            params.add(arg.image.replace(PARAMETER_MARKER, "").toUpperCase());
+        });
+        if (!params.size)
+            return "continue";
+        for (var j = i + 1; j < close_2; j++) {
+            var inner = tokens[j];
+            var bare = void 0;
+            if (isIdentifier(tokens, j)) {
+                bare = inner.image;
+            }
+            else if (tokenName(inner) === T.Function.name) {
+                bare = inner.image.slice(0, -1);
+            }
+            else {
+                continue;
+            }
+            var stripped = bare.replace(PARAMETER_MARKER, "");
+            if (!params.has(stripped.toUpperCase()))
+                continue;
+            // Structured-reference and sheet-prefixed names are never parameters.
+            var previous = tokens[j - 1];
+            if (isSheetPrefix(previous))
+                continue;
+            replacements.set(inner.startOffset, {
+                start: inner.startOffset,
+                end: inner.startOffset + bare.length,
+                text: "_xlpm.".concat(stripped),
+            });
+        }
+    };
+    for (var i = 0; i < tokens.length; i++) {
+        _loop_1(i);
+    }
+    return replacements.size
+        ? applyReplacements(formula, __spreadArray([], __read(replacements.values()), false))
+        : formula;
+}
+// ---------------------------------------------------------------- public directions
+/**
+ * Export direction. Strip the storage markers and re-add the correct one to
+ * every future-function call in `formula`, write `A1#` as `ANCHORARRAY(A1)`
+ * (qualified to `_xlfn.ANCHORARRAY`) and prefix LET / LAMBDA parameters with
+ * `_xlpm.`. Quoted spans keep their original text. Idempotent: already
+ * qualified input comes out qualified exactly once.
+ */
+export function qualifyFutureFunctions(formula) {
+    // The qualify pass strips every marker (including `_xlpm.`) before re-adding
+    // `_xlfn.`, so the parameter pass must run last.
+    return qualifyLambdaParameters(mapUnquotedSegments(encodeSpilledRanges(formula), qualifySegment));
+}
+/**
+ * Import direction. The formula as Excel displays it: every storage marker
+ * removed, `_xlfn.ANCHORARRAY(A1)` shown as `A1#`, `_xlfn.SINGLE(x)` as `@x`.
+ */
+export function normalizeImportedFormula(formula) {
+    return decodeImplicitIntersection(decodeAnchorArray(stripExcelFormulaPrefixes(formula)));
+}

package/dist/cjs/helpers.d.ts

@@ -8,7 +8,9 @@ export declare const createDownloadableFile: (filename: string, urlOrBlob: Blob
 export declare const toArrayBuffer: (data: ArrayBuffer | Uint8Array) => ArrayBuffer;
 export declare const charsToPixel: (chars: number) => number;
 export declare const pixelToCharacters: (px: number) => number;
+/** Stored OOXML column width (padded character units) → rendered pixels. */
 export declare const columnCharsToPixel: (chars: number) => number;
+/** Rendered pixels → stored OOXML column width (padded character units). */
 export declare const columnPixelToChars: (pixel: number) => number;
 /**
  * Get range from address reference with minimal processing

package/dist/cjs/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AA+B3E,eAAO,MAAM,0BAA0B,GACrC,SAAS,MAAM,GAAG,SAAS,EAC3B,YAAY,aAAa,EACzB,iBAAiB,aAAa,EAC9B,UAAU;IACR,cAAc,CAAC,EAAE,SAAS,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,KACA,MAAM,GAAG,SA8BX,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,UAAU,MAAM,KACf,OAAO,CAAC,MAAM,GAAG,SAAS,CAiB5B,CAAC;AAEF,eAAO,MAAM,sBAAsB,GACjC,UAAU,MAAM,EAChB,WAAW,IAAI,GAAG,MAAM,8BAazB,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,MAAM,WAAW,GAAG,UAAU,KAAG,WAO9D,CAAC;AAIF,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,WAAiC,CAAC;AAC5E,eAAO,MAAM,iBAAiB,GAAI,IAAI,MAAM,WAA+B,CAAC;AAoB5E,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,WACrB,CAAC;AAE5B,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,WAClB,CAAC;AAE/B;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS;;;;;cAwBpE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAsB/C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAe7C"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAiC3E,eAAO,MAAM,0BAA0B,GACrC,SAAS,MAAM,GAAG,SAAS,EAC3B,YAAY,aAAa,EACzB,iBAAiB,aAAa,EAC9B,UAAU;IACR,cAAc,CAAC,EAAE,SAAS,CAAC;IAC3B,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,KACA,MAAM,GAAG,SA8BX,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,UAAU,MAAM,KACf,OAAO,CAAC,MAAM,GAAG,SAAS,CAiB5B,CAAC;AAEF,eAAO,MAAM,sBAAsB,GACjC,UAAU,MAAM,EAChB,WAAW,IAAI,GAAG,MAAM,8BAazB,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,MAAM,WAAW,GAAG,UAAU,KAAG,WAO9D,CAAC;AAIF,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,WAAiC,CAAC;AAC5E,eAAO,MAAM,iBAAiB,GAAI,IAAI,MAAM,WAA+B,CAAC;AAyB5E,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,WACf,CAAC;AAElC,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,GAAI,OAAO,MAAM,WAG/C,CAAC;AAEF;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS;;;;;cAwBpE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAsB/C;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAe7C"}

package/dist/cjs/helpers.js

@@ -2,6 +2,7 @@ import { __awaiter, __generator, __read } from "tslib";
 import { addressToCell, canUseDOM } from "@rowsncolumns/utils";
 // ---- Formula helpers ----
 import { alpha2number, number2Alpha } from "@rowsncolumns/utils";
+import { excelColumnWidthToPixels } from "./excel-parser/helpers";
 var CELL_ADDR_RE = /(?:'[^']+'!?|[^'!\s]+!?)?(\$?[A-Z]+\$?\d+)(?::(\$?[A-Z]+\$?\d+))?/g;
 var parseAddr = function (addr) {
     var m = /^(\$?)([A-Z]+)(\$?)(\d+)$/.exec(addr);
@@ -98,22 +99,30 @@ export var pixelToCharacters = function (px) { return Math.floor((72 / 96) * px)
 // export const pixelToDimension = (chWidth: number) =>
 //   Math.ceil((33.25 / 265) * chWidth);
 // // const dimensionToPixel = (chWidth: number) => (72 / 30) * chWidth;
-// Excel column-width / pixel conversion. Excel's rendered column box
-// includes a 5-pixel padding around the MDW (max-digit-width, 7 px for
-// Calibri 11), so the default width 8.43 renders at 64 px (8.43 × 7 + 5).
-// We keep the +5 padding form so a round-trip pixels → width → pixels is
-// an identity for the values Excel itself produces.
+// Excel column-width / pixel conversion (ECMA-376 §18.3.1.13).
 //
-//   pixels = floor(widthChars × 7 + 5)
-//   widthChars = (pixels − 5) / 7
-//
-// The "pure" ECMA-376 §18.3.1.13 formula omits the 5px padding and gives
-// 59 for default-width columns instead of Excel's actual 64.
+// OOXML `<col width>` / `<sheetFormatPr defaultColWidth>` are stored in
+// *padded* character units — Excel writes `px / MDW` (the default 64 px
+// column is stored as 9.140625, not 8.43) and renders it back as
+// `Truncate(((256 × width + Truncate(128 / MDW)) / 256) × MDW)`, which the
+// importer implements in `excelColumnWidthToPixels`. The exporter must be
+// that function's inverse so export → import is a fixed point: storing
+// `trunc(px × 256 / MDW) / 256` (Excel's own 1/256-character quantisation)
+// makes `excelColumnWidthToPixels(columnPixelToChars(px)) === px` for every
+// integer pixel width. Subtracting the 5 px cell padding here (the previous
+// `(px − 5) / 7`) shrank every column by 5 px per export/import cycle once
+// the importer stopped adding it. MDW is 7 px for the Calibri 11 /
+// Aptos Narrow 12 defaults at 96 dpi.
+var EXCEL_MAX_DIGIT_WIDTH_PX = 7;
+/** Stored OOXML column width (padded character units) → rendered pixels. */
 export var columnCharsToPixel = function (chars) {
-    return Math.floor(chars * 7 + 5);
+    return excelColumnWidthToPixels(chars);
 };
+/** Rendered pixels → stored OOXML column width (padded character units). */
 export var columnPixelToChars = function (pixel) {
-    return Math.max(0, (pixel - 5) / 7);
+    if (!Number.isFinite(pixel) || pixel <= 0)
+        return 0;
+    return Math.trunc((pixel * 256) / EXCEL_MAX_DIGIT_WIDTH_PX) / 256;
 };
 /**
  * Get range from address reference with minimal processing