@rowsncolumns/toolkit 24.5.4 → 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/tsconfig.cjs.tsbuildinfo

@@ -1 +1 @@
-{"root":["../../autofilter-condition.ts","../../csv-export.ts","../../csv-import-worker.ts","../../csv-import.ts","../../excel-export.ts","../../excel-import-session.ts","../../excel-import-worker.ts","../../helpers.ts","../../index.ts","../../indexed-colors.ts","../../ods-export.ts","../../parse.ts","../../power-query.ts","../../print-settings.ts","../../server.ts","../../theme1.ts","../../types.ts","../../vitest.config.ts","../../xlsx.d.ts","../../csv-parser/helpers.ts","../../csv-parser/types.ts","../../csv-parser/worker.ts","../../excel-parser/builtin-numfmts.ts","../../excel-parser/cfb-decryptor.ts","../../excel-parser/cfb-encryptor.ts","../../excel-parser/dv-cell-stamp.ts","../../excel-parser/helpers.ts","../../excel-parser/interface.ts","../../excel-parser/registry.ts","../../excel-parser/style-registry.ts","../../excel-parser/theme-default.ts","../../excel-parser/types.ts","../../excel-parser/utils.ts","../../excel-parser/workbook.ts","../../excel-parser/worker.ts","../../excel-parser/zip-parser-streaming.ts","../../excel-parser/zip-parser.ts","../../excel-parser/plugins/base/index.ts","../../excel-parser/plugins/ods/conditional-formatting.ts","../../excel-parser/plugins/ods/data-validations.ts","../../excel-parser/plugins/ods/formula.ts","../../excel-parser/plugins/ods/index.ts","../../excel-parser/plugins/ods/sparklines.ts","../../excel-parser/plugins/ods/styles.ts","../../excel-parser/plugins/ods/types.ts","../../excel-parser/plugins/xls/index.ts","../../excel-parser/plugins/xlsb/biff-record-reader.ts","../../excel-parser/plugins/xlsb/index.ts","../../excel-parser/plugins/xlsb/rgce-parser.ts","../../excel-parser/plugins/xlsm/index.ts","../../excel-parser/plugins/xlsx/chartex.ts","../../excel-parser/plugins/xlsx/charts.ts","../../excel-parser/plugins/xlsx/conditional-formatting.ts","../../excel-parser/plugins/xlsx/data-validations.ts","../../excel-parser/plugins/xlsx/drawing.ts","../../excel-parser/plugins/xlsx/form-controls.ts","../../excel-parser/plugins/xlsx/index.ts","../../excel-parser/plugins/xlsx/numfmt.ts","../../excel-parser/plugins/xlsx/pivots.ts","../../excel-parser/plugins/xlsx/relationships.ts","../../excel-parser/plugins/xlsx/sheet-views.ts","../../excel-parser/plugins/xlsx/styles.ts","../../excel-parser/plugins/xlsx/theme.ts","../../excel-parser/plugins/xlsx/threaded-comments.ts","../../excel-parser/plugins/xlsx/value-type-detection.ts","../../exporter/invalid-data-validation.ts","../../exporter/ods/ods-export.ts","../../exporter/ods/sparkline-builder.ts","../../exporter/xlsx/chart-builder.ts","../../exporter/xlsx/chart-templates.ts","../../exporter/xlsx/chartex-builder.ts","../../exporter/xlsx/form-controls-builder.ts","../../exporter/xlsx/future-functions.ts","../../exporter/xlsx/pivot-builder.ts","../../exporter/xlsx/power-query-builder.ts","../../exporter/xlsx/slicer-builder.ts","../../exporter/xlsx/sparkline-builder.ts","../../exporter/xlsx/style-builder.ts","../../exporter/xlsx/threaded-comments-builder.ts","../../exporter/xlsx/xlsx-export.ts","../../helpers/implicit-intersection.ts","../../helpers/theme-xml-generator.ts"],"version":"5.8.3"}
+{"root":["../../autofilter-condition.ts","../../csv-export.ts","../../csv-import-worker.ts","../../csv-import.ts","../../excel-export.ts","../../excel-import-session.ts","../../excel-import-worker.ts","../../helpers.ts","../../index.ts","../../indexed-colors.ts","../../ods-export.ts","../../parse.ts","../../power-query.ts","../../print-settings.ts","../../server.ts","../../theme1.ts","../../types.ts","../../vitest.config.ts","../../xlsx.d.ts","../../csv-parser/helpers.ts","../../csv-parser/types.ts","../../csv-parser/worker.ts","../../excel-parser/builtin-numfmts.ts","../../excel-parser/cfb-decryptor.ts","../../excel-parser/cfb-encryptor.ts","../../excel-parser/dv-cell-stamp.ts","../../excel-parser/helpers.ts","../../excel-parser/interface.ts","../../excel-parser/registry.ts","../../excel-parser/style-registry.ts","../../excel-parser/theme-default.ts","../../excel-parser/types.ts","../../excel-parser/utils.ts","../../excel-parser/workbook.ts","../../excel-parser/worker.ts","../../excel-parser/zip-parser-streaming.ts","../../excel-parser/zip-parser.ts","../../excel-parser/plugins/base/index.ts","../../excel-parser/plugins/ods/conditional-formatting.ts","../../excel-parser/plugins/ods/data-validations.ts","../../excel-parser/plugins/ods/formula.ts","../../excel-parser/plugins/ods/index.ts","../../excel-parser/plugins/ods/sparklines.ts","../../excel-parser/plugins/ods/styles.ts","../../excel-parser/plugins/ods/types.ts","../../excel-parser/plugins/xls/index.ts","../../excel-parser/plugins/xlsb/biff-record-reader.ts","../../excel-parser/plugins/xlsb/index.ts","../../excel-parser/plugins/xlsb/rgce-parser.ts","../../excel-parser/plugins/xlsm/index.ts","../../excel-parser/plugins/xlsx/chartex.ts","../../excel-parser/plugins/xlsx/charts.ts","../../excel-parser/plugins/xlsx/conditional-formatting.ts","../../excel-parser/plugins/xlsx/data-validations.ts","../../excel-parser/plugins/xlsx/drawing.ts","../../excel-parser/plugins/xlsx/form-controls.ts","../../excel-parser/plugins/xlsx/index.ts","../../excel-parser/plugins/xlsx/numfmt.ts","../../excel-parser/plugins/xlsx/pivots.ts","../../excel-parser/plugins/xlsx/relationships.ts","../../excel-parser/plugins/xlsx/sheet-views.ts","../../excel-parser/plugins/xlsx/styles.ts","../../excel-parser/plugins/xlsx/theme.ts","../../excel-parser/plugins/xlsx/threaded-comments.ts","../../excel-parser/plugins/xlsx/value-type-detection.ts","../../exporter/invalid-data-validation.ts","../../exporter/ods/ods-export.ts","../../exporter/ods/sparkline-builder.ts","../../exporter/xlsx/chart-builder.ts","../../exporter/xlsx/chart-templates.ts","../../exporter/xlsx/chartex-builder.ts","../../exporter/xlsx/form-controls-builder.ts","../../exporter/xlsx/future-functions.ts","../../exporter/xlsx/pivot-builder.ts","../../exporter/xlsx/power-query-builder.ts","../../exporter/xlsx/slicer-builder.ts","../../exporter/xlsx/sparkline-builder.ts","../../exporter/xlsx/style-builder.ts","../../exporter/xlsx/threaded-comments-builder.ts","../../exporter/xlsx/xlsx-export.ts","../../helpers/excel-formula-prefixes.ts","../../helpers/implicit-intersection.ts","../../helpers/theme-xml-generator.ts"],"version":"5.8.3"}

package/dist/esm/autofilter-condition.js

@@ -233,6 +233,10 @@ const singleCustomFilterToCondition = (filter) => {
     const operator = filter.operator ?? "equal";
     const val = String(filter.val ?? "");
     // Text wildcards: equal/notEqual carrying * map back to contains/starts/ends.
+    // A NEGATED begins-with / ends-with (`notEqual` + `x*` / `*x`, Excel's "does
+    // not begin / end with") has no condition type of its own — it falls through
+    // to TEXT_NOT_EQ with the wildcard value verbatim, so the export writes
+    // `notEqual` + `x*` back unchanged instead of flipping it to `equal`.
     if ((operator === "equal" || operator === "notEqual") && /[*?]/.test(val)) {
         const negated = operator === "notEqual";
         const lead = val.startsWith("*");
@@ -244,10 +248,10 @@ const singleCustomFilterToCondition = (filter) => {
                 values: [{ userEnteredValue: core }],
             };
         }
-        if (trail) {
+        if (trail && !negated) {
             return { type: "TEXT_STARTS_WITH", values: [{ userEnteredValue: core }] };
         }
-        if (lead) {
+        if (lead && !negated) {
             return { type: "TEXT_ENDS_WITH", values: [{ userEnteredValue: core }] };
         }
     }

package/dist/esm/excel-parser/helpers.d.ts

@@ -1,5 +1,7 @@
 import type { GridRange } from "@rowsncolumns/common-types";
-import type { Column, FilterSpec, SortSpecs, TableTotalsRowFunction } from "@rowsncolumns/spreadsheet";
+import type { Column, DateGroupFilter, FilterSpec, SortSpecs, TableTotalsRowFunction } from "@rowsncolumns/spreadsheet";
+/** The engine's "(Blanks)" checklist entry — Excel's `<filters blank="1">`. */
+export declare const BLANK_LABEL = "(Blanks)";
 export declare const getRangeFromAddressRef: (ref: string) => GridRange | undefined;
 /**
  * OOXML `<col width>` (and `<sheetFormatPr defaultColWidth>`) → pixels.
@@ -24,6 +26,12 @@ export declare const isTableTotalsRowFunction: (value: unknown) => value is Tabl
  * present so columns without a totals row stay `{ name }`.
  */
 export declare const parseTableColumnTotals: (colDef: any) => Pick<Column, "totalsRowFunction" | "totalsRowLabel" | "totalsRowFormula">;
+/**
+ * A `<dateGroupItem>`'s attributes → the criteria's date-group entry, or
+ * `undefined` without a year. `dateTimeGrouping` defaults to `day` like the
+ * schema.
+ */
+export declare function dateGroupFilterFromAttributes(attrs: Record<string, unknown> | undefined): DateGroupFilter | undefined;
 export declare function createFilterSpecsFromAutoFilter(autoFilter: any, 
 /**
  * Optional dxf resolver — called with (dxfId, cellColor) to return a

package/dist/esm/excel-parser/helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../excel-parser/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAEV,MAAM,EACN,UAAU,EACV,SAAS,EACT,sBAAsB,EACvB,MAAM,2BAA2B,CAAC;AAUnC,eAAO,MAAM,sBAAsB,GAAI,KAAK,MAAM,KAAG,SAAS,GAAG,SAIhE,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,UAMrD;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,UAMpC;AAmBD,eAAO,MAAM,wBAAwB,GACnC,OAAO,OAAO,KACb,KAAK,IAAI,sBACwD,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,QAAQ,GAAG,KACV,IAAI,CAAC,MAAM,EAAE,mBAAmB,GAAG,gBAAgB,GAAG,kBAAkB,CAmB1E,CAAC;AAqBF,wBAAgB,+BAA+B,CAC7C,UAAU,EAAE,GAAG;AACf;;;;GAIG;AACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,gBA0G5E;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAgBtE;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,GAAG,EACd,KAAK,EAAE,SAAS,EAChB,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,GAC1E,SAAS,EAAE,CA2Cb;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,wBAkB3D"}
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../excel-parser/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAEV,MAAM,EACN,eAAe,EACf,UAAU,EACV,SAAS,EACT,sBAAsB,EACvB,MAAM,2BAA2B,CAAC;AAUnC,+EAA+E;AAC/E,eAAO,MAAM,WAAW,aAAa,CAAC;AAEtC,eAAO,MAAM,sBAAsB,GAAI,KAAK,MAAM,KAAG,SAAS,GAAG,SAIhE,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,UAMrD;AAED,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,UAMpC;AAmBD,eAAO,MAAM,wBAAwB,GACnC,OAAO,OAAO,KACb,KAAK,IAAI,sBACwD,CAAC;AAErE;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,QAAQ,GAAG,KACV,IAAI,CAAC,MAAM,EAAE,mBAAmB,GAAG,gBAAgB,GAAG,kBAAkB,CAmB1E,CAAC;AAqBF;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACzC,eAAe,GAAG,SAAS,CA8B7B;AAED,wBAAgB,+BAA+B,CAC7C,UAAU,EAAE,GAAG;AACf;;;;GAIG;AACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,gBAgI5E;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,CAgBtE;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,GAAG,EACd,KAAK,EAAE,SAAS,EAChB,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,GAC1E,SAAS,EAAE,CA2Cb;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,WAAW,wBAkB3D"}