@rowsncolumns/utils 9.2.44 → 9.4.0

package/dist/cjs/index.d.ts

@@ -24,4 +24,8 @@ export * from "./content-hash";
 export * from "./shared-string-canonical";
 export * from "./keyboard";
 export * from "./sheet-span";
+export * from "./formula-locale";
+export * from "./table-names";
+export * from "./table-totals";
+export * from "./sparkline-groups";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,QAAQ,CAAC;AACvB,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC;AACtB,cAAc,SAAS,CAAC;AACxB,cAAc,uBAAuB,CAAC;AACtC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,QAAQ,CAAC;AACvB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,CAAC"}

package/dist/cjs/index.js

@@ -27,3 +27,7 @@ tslib_1.__exportStar(require("./content-hash"), exports);
 tslib_1.__exportStar(require("./shared-string-canonical"), exports);
 tslib_1.__exportStar(require("./keyboard"), exports);
 tslib_1.__exportStar(require("./sheet-span"), exports);
+tslib_1.__exportStar(require("./formula-locale"), exports);
+tslib_1.__exportStar(require("./table-names"), exports);
+tslib_1.__exportStar(require("./table-totals"), exports);
+tslib_1.__exportStar(require("./sparkline-groups"), exports);

package/dist/cjs/sparkline-groups.d.ts

@@ -0,0 +1,102 @@
+import type { CellInterface, GridRange, SparkLineResultOptions } from "@rowsncolumns/common-types";
+/**
+ * Excel sparkline groups (Insert → Sparklines → Line / Column / Win-Loss) on top of the
+ * `=SPARKLINE(dataRange, {options})` cell formula — the shape the XLSX importers of BOTH engines
+ * produce for an `<x14:sparklineGroup>` (one formula per `<x14:sparkline>`, the group's attributes
+ * as the option literal) and the shape the exporters fold back into a group (cells sharing one option
+ * fingerprint share one `<x14:sparklineGroup>`). A group therefore has no separate document object:
+ * it is the connected run of location cells whose SPARKLINE formulas carry identical options. That
+ * keeps live recalc, reference shifting on insert/delete and the round-trip as ordinary formula
+ * behavior on both engines.
+ */
+export type SparklineGroupType = "line" | "column" | "winloss";
+/** One sparkline of a group: the cell it paints in and the data range it charts. */
+export type SparklineGroupMember = {
+    cell: CellInterface;
+    /** As written in the formula (optionally sheet-qualified, e.g. `Data!A2:E2`). */
+    dataRange: string;
+};
+/** The group options (everything but `charttype`, which is the group's `type`). */
+export type SparklineGroupOptions = Omit<SparkLineResultOptions, "charttype">;
+export type SparklineGroup = {
+    sheetId: number;
+    type: SparklineGroupType;
+    options: SparklineGroupOptions;
+    /** In location order (top → bottom, then left → right). */
+    members: SparklineGroupMember[];
+};
+export type ParsedSparklineFormula = {
+    dataRange: string;
+    options: SparkLineResultOptions;
+};
+export declare const isSparklineFormula: (formula: unknown) => formula is string;
+/**
+ * `=SPARKLINE(A1:E1,{"charttype","column","color","#FF0000"})` → its data range and options with the
+ * keys canonicalized to `SparkLineResultOptions` (both option-literal shapes and the legacy
+ * `highpoint`/… spellings are accepted). `null` when the formula is not a SPARKLINE call.
+ */
+export declare const parseSparklineFormula: (formula: string) => ParsedSparklineFormula | null;
+/**
+ * The inverse of {@link parseSparklineFormula}: `=SPARKLINE(range)` when no option is set, else
+ * `=SPARKLINE(range,{"k",v,…})` in the importers' emission order. Unset, `false` and `line`
+ * (the default type) options are omitted.
+ */
+export declare const buildSparklineFormula: (dataRange: string, options?: SparkLineResultOptions) => string;
+export declare const sparklineTypeFromOptions: (options: SparkLineResultOptions | undefined) => SparklineGroupType;
+/** Group identity: two SPARKLINE cells belong to one group when this string matches. */
+export declare const sparklineOptionsFingerprint: (options: SparkLineResultOptions) => string;
+export type ResolveSparklineGroupArgs = {
+    sheetId: number;
+    cell: CellInterface;
+    /** The user-entered formula of a cell (`undefined` for a non-formula cell). */
+    getFormula: (sheetId: number, rowIndex: number, columnIndex: number) => string | undefined;
+    /** Upper bound on the cells walked (a runaway sheet-wide fill would freeze the UI). */
+    maxCells?: number;
+};
+/**
+ * The sparkline group containing `cell`: the 4-connected run of SPARKLINE cells around it whose
+ * options match the cell's. `undefined` when the cell holds no SPARKLINE formula.
+ */
+export declare const resolveSparklineGroup: ({ sheetId, cell, getFormula, maxCells, }: ResolveSparklineGroupArgs) => SparklineGroup | undefined;
+export type ParsedRangeAddress = {
+    /** The sheet name as typed (quotes removed), `undefined` for a local reference. */
+    sheetName?: string;
+    range: GridRange;
+};
+/** `'Q1 Data'!A1:E5` / `Sheet1!A1` / `$A$1:$E$5` → its sheet name and grid range. */
+export declare const parseRangeAddress: (address: string) => ParsedRangeAddress | null;
+/** A grid range → `A1:E5` (a single cell → `A1`), optionally sheet-qualified. */
+export declare const rangeToA1: (range: GridRange, sheetName?: string) => string;
+export type PlanSparklineGroupArgs = {
+    /** Excel's "Data Range" (may be sheet-qualified). */
+    dataRange: string;
+    /** Excel's "Location Range" — a single row or column of cells on the group's sheet. */
+    locationRange: string;
+};
+export type SparklineGroupPlan = {
+    members: SparklineGroupMember[];
+    error?: undefined;
+} | {
+    members?: undefined;
+    error: string;
+};
+/**
+ * Excel's Create Sparklines rule: one sparkline per location cell, each charting one row (or one
+ * column) of the data range. A single location cell charts the whole data range; otherwise the data
+ * range must span exactly as many rows, or exactly as many columns, as the location has cells.
+ */
+export declare const planSparklineGroup: ({ dataRange, locationRange, }: PlanSparklineGroupArgs) => SparklineGroupPlan;
+/**
+ * The location Excel's dialog is seeded with for a data selection: the column just right of the
+ * data (one sparkline per data row), or the cell right of a single-row selection.
+ */
+export declare const defaultSparklineLocation: (data: GridRange) => GridRange;
+/** The bounding range of a group's location cells (its members are a single row or column run). */
+export declare const sparklineGroupLocation: (group: SparklineGroup) => GridRange;
+/**
+ * The group's "Data Range" as Excel's Edit Group dialog shows it: the union of the members' ranges
+ * when they tile one rectangle by rows or columns; otherwise `undefined` (members chart unrelated
+ * ranges — Excel then shows the individual ranges only).
+ */
+export declare const sparklineGroupDataRange: (group: SparklineGroup) => string | undefined;
+//# sourceMappingURL=sparkline-groups.d.ts.map

package/dist/cjs/sparkline-groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sparkline-groups.d.ts","sourceRoot":"","sources":["../../sparkline-groups.ts"],"names":[],"mappings":"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"}

package/dist/cjs/sparkline-groups.js

@@ -0,0 +1,452 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sparklineGroupDataRange = exports.sparklineGroupLocation = exports.defaultSparklineLocation = exports.planSparklineGroup = exports.rangeToA1 = exports.parseRangeAddress = exports.resolveSparklineGroup = exports.sparklineOptionsFingerprint = exports.sparklineTypeFromOptions = exports.buildSparklineFormula = exports.parseSparklineFormula = exports.isSparklineFormula = void 0;
+var tslib_1 = require("tslib");
+var selection_1 = require("./selection");
+var string_1 = require("./string");
+/** Lower-cased option key → the `SparkLineResultOptions` key the renderer reads. */
+var OPTION_KEYS = {
+    charttype: "charttype",
+    color: "color",
+    colorhigh: "colorHigh",
+    colorlow: "colorLow",
+    colorfirst: "colorFirst",
+    colorlast: "colorLast",
+    colormarkers: "colorMarkers",
+    colornegative: "colorNegative",
+    emptycells: "emptycells",
+    dateaxis: "dateaxis",
+    markers: "markers",
+    high: "high",
+    highpoint: "high",
+    low: "low",
+    lowpoint: "low",
+    first: "first",
+    firstpoint: "first",
+    last: "last",
+    lastpoint: "last",
+    negative: "negative",
+    negativepoints: "negative",
+    axis: "axis",
+    rtl: "rtl",
+    displayhidden: "displayhidden",
+    lineweight: "lineweight",
+    max: "max",
+    min: "min",
+    minaxistype: "minaxistype",
+    maxaxistype: "maxaxistype",
+};
+/** Emission order of `buildSparklineFormula` — the XLSX importers' order, so a group written here
+ * and a group read from a workbook produce byte-identical formulas. */
+var OPTION_ORDER = [
+    "charttype",
+    "color",
+    "colorHigh",
+    "colorLow",
+    "colorFirst",
+    "colorLast",
+    "colorMarkers",
+    "colorNegative",
+    "emptycells",
+    "dateaxis",
+    "markers",
+    "high",
+    "low",
+    "first",
+    "last",
+    "negative",
+    "axis",
+    "rtl",
+    "displayhidden",
+    "lineweight",
+    "max",
+    "min",
+    "minaxistype",
+    "maxaxistype",
+];
+var SPARKLINE_HEAD = /^\s*=\s*SPARKLINE\s*\(/i;
+var isSparklineFormula = function (formula) {
+    return typeof formula === "string" && SPARKLINE_HEAD.test(formula);
+};
+exports.isSparklineFormula = isSparklineFormula;
+/**
+ * Split the argument list of a SPARKLINE call at its top-level commas, honoring quotes, braces and
+ * nested parentheses (so `'Q1, Q2'!A1:E1` and `{...}` literals stay whole).
+ */
+var splitTopLevel = function (args) {
+    var e_1, _a;
+    var parts = [];
+    var depth = 0;
+    var quote = null;
+    var current = "";
+    try {
+        for (var args_1 = tslib_1.__values(args), args_1_1 = args_1.next(); !args_1_1.done; args_1_1 = args_1.next()) {
+            var ch = args_1_1.value;
+            if (quote) {
+                current += ch;
+                if (ch === quote)
+                    quote = null;
+                continue;
+            }
+            if (ch === "'" || ch === '"') {
+                quote = ch;
+                current += ch;
+                continue;
+            }
+            if (ch === "(" || ch === "{")
+                depth++;
+            if (ch === ")" || ch === "}")
+                depth--;
+            if (ch === "," && depth === 0) {
+                parts.push(current);
+                current = "";
+                continue;
+            }
+            current += ch;
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (args_1_1 && !args_1_1.done && (_a = args_1.return)) _a.call(args_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    parts.push(current);
+    return parts;
+};
+/** The tokens of an option literal body (`"k",v,"k2",v2` or `"k",v;"k2",v2`), quotes intact. */
+var tokenizeLiteral = function (body) {
+    return splitTopLevel(body.replace(/;/g, ","))
+        .map(function (t) { return t.trim(); })
+        .filter(function (t) { return t.length > 0; });
+};
+var parseOptionValue = function (raw) {
+    if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) {
+        return raw.slice(1, -1).replace(/""/g, '"');
+    }
+    var upper = raw.toUpperCase();
+    if (upper === "TRUE")
+        return true;
+    if (upper === "FALSE")
+        return false;
+    var n = Number(raw);
+    return Number.isFinite(n) ? n : raw;
+};
+/**
+ * `=SPARKLINE(A1:E1,{"charttype","column","color","#FF0000"})` → its data range and options with the
+ * keys canonicalized to `SparkLineResultOptions` (both option-literal shapes and the legacy
+ * `highpoint`/… spellings are accepted). `null` when the formula is not a SPARKLINE call.
+ */
+var parseSparklineFormula = function (formula) {
+    var _a;
+    if (!(0, exports.isSparklineFormula)(formula))
+        return null;
+    var open = formula.indexOf("(");
+    var close = formula.lastIndexOf(")");
+    if (open < 0 || close < open)
+        return null;
+    var _b = tslib_1.__read(splitTopLevel(formula.slice(open + 1, close)), 2), dataArg = _b[0], optionsArg = _b[1];
+    var dataRange = (_a = dataArg === null || dataArg === void 0 ? void 0 : dataArg.trim()) !== null && _a !== void 0 ? _a : "";
+    if (!dataRange)
+        return null;
+    var options = {};
+    var literal = optionsArg === null || optionsArg === void 0 ? void 0 : optionsArg.trim();
+    if (literal && literal.startsWith("{") && literal.endsWith("}")) {
+        var tokens = tokenizeLiteral(literal.slice(1, -1));
+        for (var i = 0; i + 1 < tokens.length; i += 2) {
+            var rawKey = parseOptionValue(tokens[i]);
+            var key = OPTION_KEYS[String(rawKey).toLowerCase()];
+            if (!key)
+                continue;
+            options[key] = parseOptionValue(tokens[i + 1]);
+        }
+    }
+    return { dataRange: dataRange, options: options };
+};
+exports.parseSparklineFormula = parseSparklineFormula;
+var quote = function (s) { return "\"".concat(s.replace(/"/g, '""'), "\""); };
+/**
+ * The inverse of {@link parseSparklineFormula}: `=SPARKLINE(range)` when no option is set, else
+ * `=SPARKLINE(range,{"k",v,…})` in the importers' emission order. Unset, `false` and `line`
+ * (the default type) options are omitted.
+ */
+var buildSparklineFormula = function (dataRange, options) {
+    var e_2, _a;
+    if (options === void 0) { options = {}; }
+    var pairs = [];
+    try {
+        for (var OPTION_ORDER_1 = tslib_1.__values(OPTION_ORDER), OPTION_ORDER_1_1 = OPTION_ORDER_1.next(); !OPTION_ORDER_1_1.done; OPTION_ORDER_1_1 = OPTION_ORDER_1.next()) {
+            var key = OPTION_ORDER_1_1.value;
+            var value = options[key];
+            if (value === undefined || value === null || value === false)
+                continue;
+            if (key === "charttype" && value === "line")
+                continue;
+            if (typeof value === "boolean") {
+                pairs.push(quote(key), "TRUE");
+            }
+            else if (typeof value === "number") {
+                if (!Number.isFinite(value))
+                    continue;
+                pairs.push(quote(key), String(value));
+            }
+            else {
+                pairs.push(quote(key), quote(String(value)));
+            }
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (OPTION_ORDER_1_1 && !OPTION_ORDER_1_1.done && (_a = OPTION_ORDER_1.return)) _a.call(OPTION_ORDER_1);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    return pairs.length
+        ? "=SPARKLINE(".concat(dataRange, ",{").concat(pairs.join(","), "})")
+        : "=SPARKLINE(".concat(dataRange, ")");
+};
+exports.buildSparklineFormula = buildSparklineFormula;
+var sparklineTypeFromOptions = function (options) {
+    return (options === null || options === void 0 ? void 0 : options.charttype) === "column" || (options === null || options === void 0 ? void 0 : options.charttype) === "winloss"
+        ? options.charttype
+        : "line";
+};
+exports.sparklineTypeFromOptions = sparklineTypeFromOptions;
+/** Group identity: two SPARKLINE cells belong to one group when this string matches. */
+var sparklineOptionsFingerprint = function (options) {
+    return OPTION_ORDER.map(function (key) {
+        var value = options[key];
+        if (value === undefined || value === null || value === false)
+            return "";
+        if (key === "charttype" && value === "line")
+            return "";
+        return String(value);
+    }).join("|");
+};
+exports.sparklineOptionsFingerprint = sparklineOptionsFingerprint;
+/**
+ * The sparkline group containing `cell`: the 4-connected run of SPARKLINE cells around it whose
+ * options match the cell's. `undefined` when the cell holds no SPARKLINE formula.
+ */
+var resolveSparklineGroup = function (_a) {
+    var e_3, _b;
+    var sheetId = _a.sheetId, cell = _a.cell, getFormula = _a.getFormula, _c = _a.maxCells, maxCells = _c === void 0 ? 4096 : _c;
+    var parse = function (rowIndex, columnIndex) {
+        var formula = getFormula(sheetId, rowIndex, columnIndex);
+        return formula ? (0, exports.parseSparklineFormula)(formula) : null;
+    };
+    var seed = parse(cell.rowIndex, cell.columnIndex);
+    if (!seed)
+        return undefined;
+    var fingerprint = (0, exports.sparklineOptionsFingerprint)(seed.options);
+    var key = function (r, c) { return "".concat(r, ":").concat(c); };
+    var seen = new Set([key(cell.rowIndex, cell.columnIndex)]);
+    var members = [
+        { cell: { rowIndex: cell.rowIndex, columnIndex: cell.columnIndex }, dataRange: seed.dataRange },
+    ];
+    var queue = [members[0].cell];
+    while (queue.length && members.length < maxCells) {
+        var _d = queue.shift(), rowIndex = _d.rowIndex, columnIndex = _d.columnIndex;
+        try {
+            for (var _e = (e_3 = void 0, tslib_1.__values([
+                [rowIndex - 1, columnIndex],
+                [rowIndex + 1, columnIndex],
+                [rowIndex, columnIndex - 1],
+                [rowIndex, columnIndex + 1],
+            ])), _f = _e.next(); !_f.done; _f = _e.next()) {
+                var _g = tslib_1.__read(_f.value, 2), r = _g[0], c = _g[1];
+                if (r < 1 || c < 1 || seen.has(key(r, c)))
+                    continue;
+                seen.add(key(r, c));
+                var parsed = parse(r, c);
+                if (!parsed || (0, exports.sparklineOptionsFingerprint)(parsed.options) !== fingerprint) {
+                    continue;
+                }
+                var member = { cell: { rowIndex: r, columnIndex: c }, dataRange: parsed.dataRange };
+                members.push(member);
+                queue.push(member.cell);
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (_f && !_f.done && (_b = _e.return)) _b.call(_e);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+    }
+    members.sort(function (a, b) { return a.cell.rowIndex - b.cell.rowIndex || a.cell.columnIndex - b.cell.columnIndex; });
+    var _h = seed.options, _charttype = _h.charttype, options = tslib_1.__rest(_h, ["charttype"]);
+    return { sheetId: sheetId, type: (0, exports.sparklineTypeFromOptions)(seed.options), options: options, members: members };
+};
+exports.resolveSparklineGroup = resolveSparklineGroup;
+var A1_RANGE = /^\$?[A-Za-z]{1,3}\$?\d+(?::\$?[A-Za-z]{1,3}\$?\d+)?$/;
+/** `'Q1 Data'!A1:E5` / `Sheet1!A1` / `$A$1:$E$5` → its sheet name and grid range. */
+var parseRangeAddress = function (address) {
+    var trimmed = address.trim();
+    if (!trimmed)
+        return null;
+    var bang = trimmed.lastIndexOf("!");
+    var sheetPart = bang >= 0 ? trimmed.slice(0, bang) : undefined;
+    var cellPart = bang >= 0 ? trimmed.slice(bang + 1) : trimmed;
+    if (!A1_RANGE.test(cellPart))
+        return null;
+    var selection = (0, selection_1.addressToSelection)(cellPart.replace(/\$/g, ""));
+    if (!selection)
+        return null;
+    var sheetName = sheetPart !== undefined ? String((0, string_1.desanitizeSheetName)(sheetPart)) : undefined;
+    return { sheetName: sheetName, range: selection.range };
+};
+exports.parseRangeAddress = parseRangeAddress;
+/** A grid range → `A1:E5` (a single cell → `A1`), optionally sheet-qualified. */
+var rangeToA1 = function (range, sheetName) {
+    var from = (0, string_1.cellToAddress)({
+        rowIndex: range.startRowIndex,
+        columnIndex: range.startColumnIndex,
+    });
+    var to = (0, string_1.cellToAddress)({
+        rowIndex: range.endRowIndex,
+        columnIndex: range.endColumnIndex,
+    });
+    var prefix = sheetName ? "".concat((0, string_1.sanitizeSheetName)(sheetName), "!") : "";
+    return "".concat(prefix).concat(from === to ? from : "".concat(from, ":").concat(to));
+};
+exports.rangeToA1 = rangeToA1;
+/**
+ * Excel's Create Sparklines rule: one sparkline per location cell, each charting one row (or one
+ * column) of the data range. A single location cell charts the whole data range; otherwise the data
+ * range must span exactly as many rows, or exactly as many columns, as the location has cells.
+ */
+var planSparklineGroup = function (_a) {
+    var dataRange = _a.dataRange, locationRange = _a.locationRange;
+    var data = (0, exports.parseRangeAddress)(dataRange);
+    if (!data)
+        return { error: "The data range is not valid." };
+    var location = (0, exports.parseRangeAddress)(locationRange);
+    if (!location)
+        return { error: "The location range is not valid." };
+    var loc = location.range;
+    var locRows = loc.endRowIndex - loc.startRowIndex + 1;
+    var locCols = loc.endColumnIndex - loc.startColumnIndex + 1;
+    if (locRows > 1 && locCols > 1) {
+        return { error: "The location range must be a single row or column." };
+    }
+    var cells = [];
+    for (var r = loc.startRowIndex; r <= loc.endRowIndex; r++) {
+        for (var c = loc.startColumnIndex; c <= loc.endColumnIndex; c++) {
+            cells.push({ rowIndex: r, columnIndex: c });
+        }
+    }
+    var d = data.range;
+    var dataRows = d.endRowIndex - d.startRowIndex + 1;
+    var dataCols = d.endColumnIndex - d.startColumnIndex + 1;
+    var qualify = function (range) { return (0, exports.rangeToA1)(range, data.sheetName); };
+    if (cells.length === 1) {
+        return { members: [{ cell: cells[0], dataRange: qualify(d) }] };
+    }
+    if (dataRows === cells.length) {
+        return {
+            members: cells.map(function (cell, i) { return ({
+                cell: cell,
+                dataRange: qualify({
+                    startRowIndex: d.startRowIndex + i,
+                    endRowIndex: d.startRowIndex + i,
+                    startColumnIndex: d.startColumnIndex,
+                    endColumnIndex: d.endColumnIndex,
+                }),
+            }); }),
+        };
+    }
+    if (dataCols === cells.length) {
+        return {
+            members: cells.map(function (cell, i) { return ({
+                cell: cell,
+                dataRange: qualify({
+                    startRowIndex: d.startRowIndex,
+                    endRowIndex: d.endRowIndex,
+                    startColumnIndex: d.startColumnIndex + i,
+                    endColumnIndex: d.startColumnIndex + i,
+                }),
+            }); }),
+        };
+    }
+    return {
+        error: "The data range must have the same number of rows or columns as the location range.",
+    };
+};
+exports.planSparklineGroup = planSparklineGroup;
+/**
+ * The location Excel's dialog is seeded with for a data selection: the column just right of the
+ * data (one sparkline per data row), or the cell right of a single-row selection.
+ */
+var defaultSparklineLocation = function (data) {
+    var rows = data.endRowIndex - data.startRowIndex + 1;
+    var columnIndex = data.endColumnIndex + 1;
+    return rows > 1
+        ? {
+            startRowIndex: data.startRowIndex,
+            endRowIndex: data.endRowIndex,
+            startColumnIndex: columnIndex,
+            endColumnIndex: columnIndex,
+        }
+        : {
+            startRowIndex: data.startRowIndex,
+            endRowIndex: data.startRowIndex,
+            startColumnIndex: columnIndex,
+            endColumnIndex: columnIndex,
+        };
+};
+exports.defaultSparklineLocation = defaultSparklineLocation;
+/** The bounding range of a group's location cells (its members are a single row or column run). */
+var sparklineGroupLocation = function (group) {
+    var rows = group.members.map(function (m) { return m.cell.rowIndex; });
+    var cols = group.members.map(function (m) { return m.cell.columnIndex; });
+    return {
+        startRowIndex: Math.min.apply(Math, tslib_1.__spreadArray([], tslib_1.__read(rows), false)),
+        endRowIndex: Math.max.apply(Math, tslib_1.__spreadArray([], tslib_1.__read(rows), false)),
+        startColumnIndex: Math.min.apply(Math, tslib_1.__spreadArray([], tslib_1.__read(cols), false)),
+        endColumnIndex: Math.max.apply(Math, tslib_1.__spreadArray([], tslib_1.__read(cols), false)),
+    };
+};
+exports.sparklineGroupLocation = sparklineGroupLocation;
+/**
+ * The group's "Data Range" as Excel's Edit Group dialog shows it: the union of the members' ranges
+ * when they tile one rectangle by rows or columns; otherwise `undefined` (members chart unrelated
+ * ranges — Excel then shows the individual ranges only).
+ */
+var sparklineGroupDataRange = function (group) {
+    var parsed = group.members.map(function (m) { return (0, exports.parseRangeAddress)(m.dataRange); });
+    if (parsed.some(function (p) { return !p; }))
+        return undefined;
+    var ranges = parsed;
+    var sheetName = ranges[0].sheetName;
+    if (ranges.some(function (r) { return r.sheetName !== sheetName; }))
+        return undefined;
+    if (ranges.length === 1)
+        return (0, exports.rangeToA1)(ranges[0].range, sheetName);
+    var first = ranges[0].range;
+    var byRows = ranges.every(function (r, i) {
+        return r.range.startColumnIndex === first.startColumnIndex &&
+            r.range.endColumnIndex === first.endColumnIndex &&
+            r.range.startRowIndex === first.startRowIndex + i &&
+            r.range.endRowIndex === r.range.startRowIndex;
+    });
+    var byCols = ranges.every(function (r, i) {
+        return r.range.startRowIndex === first.startRowIndex &&
+            r.range.endRowIndex === first.endRowIndex &&
+            r.range.startColumnIndex === first.startColumnIndex + i &&
+            r.range.endColumnIndex === r.range.startColumnIndex;
+    });
+    if (!byRows && !byCols)
+        return undefined;
+    var last = ranges[ranges.length - 1].range;
+    return (0, exports.rangeToA1)({
+        startRowIndex: first.startRowIndex,
+        startColumnIndex: first.startColumnIndex,
+        endRowIndex: byRows ? last.endRowIndex : first.endRowIndex,
+        endColumnIndex: byCols ? last.endColumnIndex : first.endColumnIndex,
+    }, sheetName);
+};
+exports.sparklineGroupDataRange = sparklineGroupDataRange;

package/dist/cjs/string.d.ts

@@ -52,6 +52,21 @@ export declare const desanitizeSheetName: (name: string | undefined) => string |
  * @returns
  */
 export declare const escapeCharacters: (str: string) => string;
+/**
+ * Regular-expression source for an Excel wildcard pattern: `*` matches any run
+ * of characters, `?` exactly one, and `~` escapes the next character (`~*` is a
+ * literal asterisk). Every other character is matched literally. Callers anchor
+ * the source (`^…$` for "equals", `^…` for "begins with", …) and compile it
+ * case-insensitively — Excel's text criteria never distinguish case.
+ */
+export declare const wildcardPatternToRegExpSource: (pattern: string) => string;
+/**
+ * Does `text` satisfy an Excel wildcard `pattern` (see
+ * `wildcardPatternToRegExpSource`) under the given anchoring? `equals` is a
+ * whole-string match, `startsWith` / `endsWith` anchor one side, `contains`
+ * neither. Case-insensitive like Excel's AutoFilter and COUNTIF.
+ */
+export declare const matchesWildcardPattern: (pattern: string, text: string, anchor: "equals" | "startsWith" | "endsWith" | "contains") => boolean;
 /**
  * Get selection from start and end cell
  * @param start

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

@@ -1 +1 @@
-{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../string.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAK3E;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,aAAa,KAAG,SAKvD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,MAAM,EACf,UAAS;IACP,QAAQ,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,KACL,aAAa,GAAG,IAuDlB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,MAAM,uBAEvD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,uBAErD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,aAAa,GAAG,IAAI,EAC1B,0BAAwB,EACxB,uBAAqB,EACrB,sBAAoB,EACpB,mBAAiB,KAChB,MAAM,GAAG,IAiBX,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,WAAW,MAAM,GAAG,SAAS,EAC7B,OAAO,SAAS,WAUjB,CAAC;AAGF,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,GAAG,SAAS,uBASzD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,GAAG,SAAS,uBAgB3D,CAAC;AAKF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,WAI3C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,aAAa,EACpB,MAAK,aAAa,GAAG,IAAY,KAChC,SAQF,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,WAKzD,CAAC;AAUF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,WAoB/C,CAAC"}
+{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../string.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAK3E;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,aAAa,KAAG,SAKvD,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,SAAS,MAAM,EACf,UAAS;IACP,QAAQ,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,KACL,aAAa,GAAG,IAuDlB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,wBAAwB,GAAI,SAAS,MAAM,uBAEvD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,uBAErD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,MAAM,aAAa,GAAG,IAAI,EAC1B,0BAAwB,EACxB,uBAAqB,EACrB,sBAAoB,EACpB,mBAAiB,KAChB,MAAM,GAAG,IAiBX,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAC7B,WAAW,MAAM,GAAG,SAAS,EAC7B,OAAO,SAAS,WAUjB,CAAC;AAGF,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,GAAG,SAAS,uBASzD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,GAAG,SAAS,uBAgB3D,CAAC;AAKF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,WAI3C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,GAAI,SAAS,MAAM,KAAG,MAe/D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GACjC,SAAS,MAAM,EACf,MAAM,MAAM,EACZ,QAAQ,QAAQ,GAAG,YAAY,GAAG,UAAU,GAAG,UAAU,KACxD,OAWF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,GACnC,OAAO,aAAa,EACpB,MAAK,aAAa,GAAG,IAAY,KAChC,SAQF,CAAC;AAEF,eAAO,MAAM,QAAQ,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,WAKzD,CAAC;AAUF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,MAAM,WAoB/C,CAAC"}