@rowsncolumns/utils 9.3.0 → 9.4.0

package/dist/esm/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/esm/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/esm/sparkline-groups.js

@@ -0,0 +1,387 @@
+import { addressToSelection } from "./selection";
+import { cellToAddress, desanitizeSheetName, sanitizeSheetName } from "./string";
+/** Lower-cased option key → the `SparkLineResultOptions` key the renderer reads. */
+const 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. */
+const 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",
+];
+const SPARKLINE_HEAD = /^\s*=\s*SPARKLINE\s*\(/i;
+export const isSparklineFormula = (formula) => typeof formula === "string" && SPARKLINE_HEAD.test(formula);
+/**
+ * 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).
+ */
+const splitTopLevel = (args) => {
+    const parts = [];
+    let depth = 0;
+    let quote = null;
+    let current = "";
+    for (const ch of args) {
+        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;
+    }
+    parts.push(current);
+    return parts;
+};
+/** The tokens of an option literal body (`"k",v,"k2",v2` or `"k",v;"k2",v2`), quotes intact. */
+const tokenizeLiteral = (body) => splitTopLevel(body.replace(/;/g, ","))
+    .map((t) => t.trim())
+    .filter((t) => t.length > 0);
+const parseOptionValue = (raw) => {
+    if (raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) {
+        return raw.slice(1, -1).replace(/""/g, '"');
+    }
+    const upper = raw.toUpperCase();
+    if (upper === "TRUE")
+        return true;
+    if (upper === "FALSE")
+        return false;
+    const 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.
+ */
+export const parseSparklineFormula = (formula) => {
+    if (!isSparklineFormula(formula))
+        return null;
+    const open = formula.indexOf("(");
+    const close = formula.lastIndexOf(")");
+    if (open < 0 || close < open)
+        return null;
+    const [dataArg, optionsArg] = splitTopLevel(formula.slice(open + 1, close));
+    const dataRange = dataArg?.trim() ?? "";
+    if (!dataRange)
+        return null;
+    const options = {};
+    const literal = optionsArg?.trim();
+    if (literal && literal.startsWith("{") && literal.endsWith("}")) {
+        const tokens = tokenizeLiteral(literal.slice(1, -1));
+        for (let i = 0; i + 1 < tokens.length; i += 2) {
+            const rawKey = parseOptionValue(tokens[i]);
+            const key = OPTION_KEYS[String(rawKey).toLowerCase()];
+            if (!key)
+                continue;
+            options[key] = parseOptionValue(tokens[i + 1]);
+        }
+    }
+    return { dataRange, options };
+};
+const quote = (s) => `"${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.
+ */
+export const buildSparklineFormula = (dataRange, options = {}) => {
+    const pairs = [];
+    for (const key of OPTION_ORDER) {
+        const 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)));
+        }
+    }
+    return pairs.length
+        ? `=SPARKLINE(${dataRange},{${pairs.join(",")}})`
+        : `=SPARKLINE(${dataRange})`;
+};
+export const sparklineTypeFromOptions = (options) => options?.charttype === "column" || options?.charttype === "winloss"
+    ? options.charttype
+    : "line";
+/** Group identity: two SPARKLINE cells belong to one group when this string matches. */
+export const sparklineOptionsFingerprint = (options) => OPTION_ORDER.map((key) => {
+    const value = options[key];
+    if (value === undefined || value === null || value === false)
+        return "";
+    if (key === "charttype" && value === "line")
+        return "";
+    return String(value);
+}).join("|");
+/**
+ * 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 const resolveSparklineGroup = ({ sheetId, cell, getFormula, maxCells = 4096, }) => {
+    const parse = (rowIndex, columnIndex) => {
+        const formula = getFormula(sheetId, rowIndex, columnIndex);
+        return formula ? parseSparklineFormula(formula) : null;
+    };
+    const seed = parse(cell.rowIndex, cell.columnIndex);
+    if (!seed)
+        return undefined;
+    const fingerprint = sparklineOptionsFingerprint(seed.options);
+    const key = (r, c) => `${r}:${c}`;
+    const seen = new Set([key(cell.rowIndex, cell.columnIndex)]);
+    const members = [
+        { cell: { rowIndex: cell.rowIndex, columnIndex: cell.columnIndex }, dataRange: seed.dataRange },
+    ];
+    const queue = [members[0].cell];
+    while (queue.length && members.length < maxCells) {
+        const { rowIndex, columnIndex } = queue.shift();
+        for (const [r, c] of [
+            [rowIndex - 1, columnIndex],
+            [rowIndex + 1, columnIndex],
+            [rowIndex, columnIndex - 1],
+            [rowIndex, columnIndex + 1],
+        ]) {
+            if (r < 1 || c < 1 || seen.has(key(r, c)))
+                continue;
+            seen.add(key(r, c));
+            const parsed = parse(r, c);
+            if (!parsed || sparklineOptionsFingerprint(parsed.options) !== fingerprint) {
+                continue;
+            }
+            const member = { cell: { rowIndex: r, columnIndex: c }, dataRange: parsed.dataRange };
+            members.push(member);
+            queue.push(member.cell);
+        }
+    }
+    members.sort((a, b) => a.cell.rowIndex - b.cell.rowIndex || a.cell.columnIndex - b.cell.columnIndex);
+    const { charttype: _charttype, ...options } = seed.options;
+    return { sheetId, type: sparklineTypeFromOptions(seed.options), options, members };
+};
+const 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. */
+export const parseRangeAddress = (address) => {
+    const trimmed = address.trim();
+    if (!trimmed)
+        return null;
+    const bang = trimmed.lastIndexOf("!");
+    const sheetPart = bang >= 0 ? trimmed.slice(0, bang) : undefined;
+    const cellPart = bang >= 0 ? trimmed.slice(bang + 1) : trimmed;
+    if (!A1_RANGE.test(cellPart))
+        return null;
+    const selection = addressToSelection(cellPart.replace(/\$/g, ""));
+    if (!selection)
+        return null;
+    const sheetName = sheetPart !== undefined ? String(desanitizeSheetName(sheetPart)) : undefined;
+    return { sheetName, range: selection.range };
+};
+/** A grid range → `A1:E5` (a single cell → `A1`), optionally sheet-qualified. */
+export const rangeToA1 = (range, sheetName) => {
+    const from = cellToAddress({
+        rowIndex: range.startRowIndex,
+        columnIndex: range.startColumnIndex,
+    });
+    const to = cellToAddress({
+        rowIndex: range.endRowIndex,
+        columnIndex: range.endColumnIndex,
+    });
+    const prefix = sheetName ? `${sanitizeSheetName(sheetName)}!` : "";
+    return `${prefix}${from === to ? from : `${from}:${to}`}`;
+};
+/**
+ * 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 const planSparklineGroup = ({ dataRange, locationRange, }) => {
+    const data = parseRangeAddress(dataRange);
+    if (!data)
+        return { error: "The data range is not valid." };
+    const location = parseRangeAddress(locationRange);
+    if (!location)
+        return { error: "The location range is not valid." };
+    const loc = location.range;
+    const locRows = loc.endRowIndex - loc.startRowIndex + 1;
+    const locCols = loc.endColumnIndex - loc.startColumnIndex + 1;
+    if (locRows > 1 && locCols > 1) {
+        return { error: "The location range must be a single row or column." };
+    }
+    const cells = [];
+    for (let r = loc.startRowIndex; r <= loc.endRowIndex; r++) {
+        for (let c = loc.startColumnIndex; c <= loc.endColumnIndex; c++) {
+            cells.push({ rowIndex: r, columnIndex: c });
+        }
+    }
+    const d = data.range;
+    const dataRows = d.endRowIndex - d.startRowIndex + 1;
+    const dataCols = d.endColumnIndex - d.startColumnIndex + 1;
+    const qualify = (range) => rangeToA1(range, data.sheetName);
+    if (cells.length === 1) {
+        return { members: [{ cell: cells[0], dataRange: qualify(d) }] };
+    }
+    if (dataRows === cells.length) {
+        return {
+            members: cells.map((cell, i) => ({
+                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((cell, i) => ({
+                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.",
+    };
+};
+/**
+ * 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 const defaultSparklineLocation = (data) => {
+    const rows = data.endRowIndex - data.startRowIndex + 1;
+    const 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,
+        };
+};
+/** The bounding range of a group's location cells (its members are a single row or column run). */
+export const sparklineGroupLocation = (group) => {
+    const rows = group.members.map((m) => m.cell.rowIndex);
+    const cols = group.members.map((m) => m.cell.columnIndex);
+    return {
+        startRowIndex: Math.min(...rows),
+        endRowIndex: Math.max(...rows),
+        startColumnIndex: Math.min(...cols),
+        endColumnIndex: Math.max(...cols),
+    };
+};
+/**
+ * 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 const sparklineGroupDataRange = (group) => {
+    const parsed = group.members.map((m) => parseRangeAddress(m.dataRange));
+    if (parsed.some((p) => !p))
+        return undefined;
+    const ranges = parsed;
+    const sheetName = ranges[0].sheetName;
+    if (ranges.some((r) => r.sheetName !== sheetName))
+        return undefined;
+    if (ranges.length === 1)
+        return rangeToA1(ranges[0].range, sheetName);
+    const first = ranges[0].range;
+    const byRows = ranges.every((r, i) => r.range.startColumnIndex === first.startColumnIndex &&
+        r.range.endColumnIndex === first.endColumnIndex &&
+        r.range.startRowIndex === first.startRowIndex + i &&
+        r.range.endRowIndex === r.range.startRowIndex);
+    const byCols = ranges.every((r, i) => 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;
+    const last = ranges[ranges.length - 1].range;
+    return rangeToA1({
+        startRowIndex: first.startRowIndex,
+        startColumnIndex: first.startColumnIndex,
+        endRowIndex: byRows ? last.endRowIndex : first.endRowIndex,
+        endColumnIndex: byCols ? last.endColumnIndex : first.endColumnIndex,
+    }, sheetName);
+};

package/dist/esm/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/esm/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"}

package/dist/esm/string.js

@@ -166,6 +166,49 @@ export const escapeCharacters = (str) => {
         ? str.replace(SPECIAL_CHARACTERS, "\\$1")
         : str || "";
 };
+/**
+ * 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 const wildcardPatternToRegExpSource = (pattern) => {
+    let source = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const char = pattern[i];
+        if (char === "~" && i + 1 < pattern.length) {
+            source += escapeCharacters(pattern[++i]);
+        }
+        else if (char === "*") {
+            source += ".*";
+        }
+        else if (char === "?") {
+            source += ".";
+        }
+        else {
+            source += escapeCharacters(char);
+        }
+    }
+    return source;
+};
+/**
+ * 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 const matchesWildcardPattern = (pattern, text, anchor) => {
+    const source = wildcardPatternToRegExpSource(pattern);
+    const anchored = anchor === "equals"
+        ? `^${source}$`
+        : anchor === "startsWith"
+            ? `^${source}`
+            : anchor === "endsWith"
+                ? `${source}$`
+                : source;
+    return new RegExp(anchored, "is").test(text);
+};
 /**
  * Get selection from start and end cell
  * @param start

package/dist/esm/table-names.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Excel's rules for a table name (Table Design → Table Name / "Rename an Excel table"):
+ *
+ * - starts with a letter, an underscore (`_`) or a backslash (`\`);
+ * - the rest is letters, digits, periods (`.`) and underscores — no spaces;
+ * - is not a cell reference (`A1`, `R1C1`, `XFD1048576`) and not the lone `C` / `R` shortcuts;
+ * - is at most 255 characters;
+ * - is unique across the workbook, compared case-insensitively — against the other tables AND the
+ *   defined names (Excel refuses a table named like an existing defined name, and a defined name
+ *   spelled like an existing table).
+ *
+ * Both engines create and rename tables through these checks (the rnc store mirrors them in Rust and
+ * surfaces the same messages through its `rejections` channel), and the table editor's validation
+ * schema shows the same text under the name field.
+ */
+export declare const TABLE_NAME_MAX_LENGTH = 255;
+export declare const TABLE_NAME_REQUIRED_MESSAGE = "Enter a table name.";
+export declare const TABLE_NAME_TOO_LONG_MESSAGE = "Table names can't be longer than 255 characters.";
+export declare const TABLE_NAME_SPACES_MESSAGE = "Table names can't contain spaces.";
+export declare const TABLE_NAME_LEADING_CHAR_MESSAGE = "Table names must start with a letter, an underscore (_) or a backslash (\\).";
+export declare const TABLE_NAME_INVALID_CHAR_MESSAGE = "Table names can only contain letters, numbers, periods (.) and underscores (_).";
+export declare const TABLE_NAME_CELL_REFERENCE_MESSAGE = "Table names can't be a cell reference such as A1 or R1C1.";
+export declare const tableNameDuplicateMessage: (existing: string) => string;
+export declare const tableNameDefinedNameMessage: (existing: string) => string;
+/** `create-table` with an `id` an existing table already holds is refused on both engines (#668 T-56). */
+export declare const tableIdDuplicateMessage: (id: string | number) => string;
+export declare const definedNameTableNameMessage: (existing: string) => string;
+/** True when `name` reads as a cell reference in either A1 or R1C1 notation. */
+export declare const isCellReferenceLikeName: (name: string) => boolean;
+/**
+ * The reason `name` is not an acceptable table name, or `undefined` when it is. `existingNames` are
+ * the OTHER tables' names in the workbook (leave the table being renamed out of it) and
+ * `existingDefinedNames` the workbook's defined names; duplicates against either are detected
+ * case-insensitively, the way Excel compares names.
+ */
+export declare const validateTableName: (name: string, existingNames?: Iterable<string> | null, existingDefinedNames?: Iterable<string> | null) => string | undefined;
+export declare const isValidTableName: (name: string, existingNames?: Iterable<string> | null, existingDefinedNames?: Iterable<string> | null) => boolean;
+/**
+ * The reason a defined name `name` cannot be created or renamed to — it is spelled like one of
+ * `tableNames` (case-insensitive) — or `undefined` when no table holds it. Excel keeps tables and
+ * defined names in one namespace.
+ */
+export declare const validateDefinedNameAgainstTables: (name: string, tableNames?: Iterable<string> | null) => string | undefined;
+/**
+ * The default name for a new table: `Table1`, `Table2`, … — the LOWEST number no existing table
+ * uses (case-insensitive), so a deleted table's number is reissued and the result never collides.
+ * `format` localises the pattern (`(n) => \`Tabelle${n}\``).
+ */
+export declare const getNextTableName: (existingNames: Iterable<string>, format?: (index: number) => string) => string;
+/**
+ * The name for a copy of table `base`: `Sales2`, `Sales3`, … — the LOWEST number no existing table
+ * uses (case-insensitive), the way Excel names the table on a duplicated sheet.
+ */
+export declare const getNextTableCopyName: (base: string, existingNames: Iterable<string>) => string;
+//# sourceMappingURL=table-names.d.ts.map

package/dist/esm/table-names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"table-names.d.ts","sourceRoot":"","sources":["../../table-names.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAYzC,eAAO,MAAM,2BAA2B,wBAAwB,CAAC;AACjE,eAAO,MAAM,2BAA2B,qDAA0E,CAAC;AACnH,eAAO,MAAM,yBAAyB,sCAAsC,CAAC;AAC7E,eAAO,MAAM,+BAA+B,iFACoC,CAAC;AACjF,eAAO,MAAM,+BAA+B,oFACuC,CAAC;AACpF,eAAO,MAAM,iCAAiC,8DACe,CAAC;AAC9D,eAAO,MAAM,yBAAyB,GAAI,UAAU,MAAM,WACkC,CAAC;AAC7F,eAAO,MAAM,2BAA2B,GAAI,UAAU,MAAM,WACmD,CAAC;AAChH,0GAA0G;AAC1G,eAAO,MAAM,uBAAuB,GAAI,IAAI,MAAM,GAAG,MAAM,WACK,CAAC;AACjE,eAAO,MAAM,2BAA2B,GAAI,UAAU,MAAM,WACkD,CAAC;AAmB/G,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,GAAI,MAAM,MAAM,KAAG,OAGzB,CAAC;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,MAAM,EACZ,gBAAgB,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,EACvC,uBAAuB,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,KAC7C,MAAM,GAAG,SA4BX,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAC3B,MAAM,MAAM,EACZ,gBAAgB,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,EACvC,uBAAuB,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,KAC7C,OACyE,CAAC;AAE7E;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,GAC3C,MAAM,MAAM,EACZ,aAAa,QAAQ,CAAC,MAAM,CAAC,GAAG,IAAI,KACnC,MAAM,GAAG,SAGX,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,eAAe,QAAQ,CAAC,MAAM,CAAC,EAC/B,SAAQ,CAAC,KAAK,EAAE,MAAM,KAAK,MAAmC,KAC7D,MAUF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAC/B,MAAM,MAAM,EACZ,eAAe,QAAQ,CAAC,MAAM,CAAC,KAC9B,MAUF,CAAC"}