@rowsncolumns/utils 9.3.0 → 9.5.0

package/dist/esm/rich-text-html.js

@@ -0,0 +1,520 @@
+import { colorStringToHex } from "./color";
+import { canUseDOM } from "./dom";
+const BLOCK_TAGS = new Set([
+    "p",
+    "div",
+    "li",
+    "ul",
+    "ol",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "pre",
+    "tr",
+    "blockquote",
+]);
+const SKIPPED_TAGS = new Set([
+    "style",
+    "script",
+    "meta",
+    "head",
+    "title",
+    "link",
+    "col",
+    "colgroup",
+    "template",
+    "noscript",
+]);
+// `<font size="N">` → points (HTML 4 size keywords).
+const FONT_SIZE_KEYWORDS = {
+    1: 8,
+    2: 10,
+    3: 12,
+    4: 14,
+    5: 18,
+    6: 24,
+    7: 36,
+};
+// CSS named colors Excel / Word actually emit (`color:red`, `<font color=red>`).
+// `getComputedStyle` in a browser already resolves names to `rgb()`, this
+// table covers inline keywords and jsdom (which reports the declared value).
+const NAMED_COLORS = {
+    black: "#000000",
+    white: "#FFFFFF",
+    red: "#FF0000",
+    green: "#008000",
+    lime: "#00FF00",
+    blue: "#0000FF",
+    yellow: "#FFFF00",
+    orange: "#FFA500",
+    purple: "#800080",
+    gray: "#808080",
+    grey: "#808080",
+    silver: "#C0C0C0",
+    maroon: "#800000",
+    navy: "#000080",
+    teal: "#008080",
+    olive: "#808000",
+    aqua: "#00FFFF",
+    cyan: "#00FFFF",
+    fuchsia: "#FF00FF",
+    magenta: "#FF00FF",
+    brown: "#A52A2A",
+    pink: "#FFC0CB",
+    gold: "#FFD700",
+    indigo: "#4B0082",
+    violet: "#EE82EE",
+    darkred: "#8B0000",
+    darkgreen: "#006400",
+    darkblue: "#00008B",
+};
+// Values that mean "no explicit color" — Excel's `windowtext`, CSS keywords.
+const NON_COLORS = new Set([
+    "windowtext",
+    "inherit",
+    "initial",
+    "unset",
+    "currentcolor",
+    "transparent",
+    "auto",
+    "",
+]);
+/**
+ * Parse an HTML clipboard payload into a hidden, mounted sandbox so
+ * `getComputedStyle` resolves the payload's own `<style>` rules (Excel's
+ * `.fontN` / `.xlNN` classes). Callers must `cleanup()` when done.
+ */
+export const mountClipboardHtml = (clipboardValue) => {
+    const parser = new DOMParser();
+    const doc = parser.parseFromString(clipboardValue, "text/html");
+    const sandbox = document.createElement("div");
+    sandbox.style.cssText =
+        "position:fixed;left:-10000px;top:-10000px;width:0;height:0;overflow:hidden;opacity:0;pointer-events:none;font-size:10pt;";
+    sandbox.innerHTML = doc.body?.innerHTML ?? "";
+    const styles = doc.head?.querySelectorAll("style") ?? [];
+    styles.forEach((style) => sandbox.appendChild(style.cloneNode(true)));
+    document.body.appendChild(sandbox);
+    return {
+        root: sandbox,
+        cleanup: () => sandbox.remove(),
+    };
+};
+export const cssColorToHex = (value) => {
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    const lower = trimmed.toLowerCase();
+    if (NON_COLORS.has(lower)) {
+        return undefined;
+    }
+    // `rgba(0, 0, 0, 0)` is the transparent default many engines report.
+    if (/^rgba\(\s*0\s*,\s*0\s*,\s*0\s*,\s*0\s*\)$/.test(lower)) {
+        return undefined;
+    }
+    const hex = colorStringToHex(trimmed);
+    if (hex) {
+        return hex.toUpperCase();
+    }
+    return NAMED_COLORS[lower];
+};
+/** CSS font-size → points. `pt` verbatim, `px` at 96dpi, `em`/`rem` on a 16px base. */
+export const cssFontSizeToPt = (value) => {
+    if (!value) {
+        return undefined;
+    }
+    const match = value.trim().match(/^(\d+(?:\.\d+)?)\s*(pt|px|rem|em)?$/i);
+    if (!match) {
+        return undefined;
+    }
+    const numeric = parseFloat(match[1]);
+    if (!Number.isFinite(numeric) || numeric <= 0) {
+        return undefined;
+    }
+    const unit = (match[2] ?? "px").toLowerCase();
+    const pt = unit === "pt"
+        ? numeric
+        : unit === "px"
+            ? numeric * 0.75
+            : numeric * 16 * 0.75;
+    return Number(pt.toFixed(1));
+};
+const firstFontFamily = (value) => {
+    if (!value) {
+        return undefined;
+    }
+    const family = value
+        .split(",")[0]
+        .trim()
+        .replace(/^["']|["']$/g, "")
+        .trim();
+    if (!family || /^(inherit|initial|unset)$/i.test(family)) {
+        return undefined;
+    }
+    return family;
+};
+const safeComputedStyle = (element) => {
+    if (!canUseDOM || typeof getComputedStyle !== "function") {
+        return null;
+    }
+    try {
+        return getComputedStyle(element);
+    }
+    catch {
+        return null;
+    }
+};
+const readWeight = (value) => {
+    if (!value) {
+        return undefined;
+    }
+    const lower = value.trim().toLowerCase();
+    if (lower === "bold" || lower === "bolder") {
+        return true;
+    }
+    if (lower === "normal" || lower === "lighter") {
+        return false;
+    }
+    const numeric = Number(lower);
+    if (Number.isFinite(numeric)) {
+        return numeric >= 600;
+    }
+    return undefined;
+};
+const normalizeWhitespace = (text) => text.replace(/[\n\r]+/g, " ").replace(/\s{2,}/g, " ");
+/**
+ * The formatting an element applies on top of `inherited`: tag semantics
+ * (`<b>`, `<font color>`, `<a href>`, …) + inline `style` + (except for
+ * anchors) the cascaded computed style.
+ */
+const readElementFormat = (element, inherited) => {
+    const format = { ...inherited };
+    const tag = element.tagName.toLowerCase();
+    let attrColor;
+    let attrFace;
+    let attrSize;
+    switch (tag) {
+        case "b":
+        case "strong":
+            format.bold = true;
+            break;
+        case "i":
+        case "em":
+            format.italic = true;
+            break;
+        case "u":
+            format.underline = true;
+            break;
+        case "s":
+        case "strike":
+        case "del":
+            format.strikethrough = true;
+            break;
+        case "sup":
+            format.baselineOffset = "superscript";
+            break;
+        case "sub":
+            format.baselineOffset = "subscript";
+            break;
+        case "font": {
+            // Presentational attributes. They rank between the inline style and
+            // the cascaded computed style below: a browser folds them into the
+            // computed value, jsdom reports the inherited one instead.
+            attrColor = cssColorToHex(element.getAttribute("color"));
+            attrFace = firstFontFamily(element.getAttribute("face"));
+            const size = parseInt(element.getAttribute("size") ?? "", 10);
+            if (!Number.isNaN(size) && FONT_SIZE_KEYWORDS[size]) {
+                attrSize = FONT_SIZE_KEYWORDS[size];
+            }
+            break;
+        }
+        case "a": {
+            const href = element.getAttribute("href");
+            if (href && href.trim()) {
+                format.link = { uri: href.trim() };
+            }
+            break;
+        }
+    }
+    const inline = element.style;
+    const computed = tag === "a" ? null : safeComputedStyle(element);
+    const pick = (inlineValue, computedValue) => (inlineValue && inlineValue.trim() ? inlineValue : computedValue);
+    const weight = readWeight(pick(inline.fontWeight, computed?.fontWeight));
+    if (weight !== undefined) {
+        format.bold = weight;
+    }
+    const fontStyle = pick(inline.fontStyle, computed?.fontStyle);
+    if (fontStyle) {
+        const lower = fontStyle.trim().toLowerCase();
+        if (lower === "italic" || lower === "oblique") {
+            format.italic = true;
+        }
+        else if (lower === "normal") {
+            format.italic = false;
+        }
+    }
+    // `text-decoration` is not inherited in CSS but propagates visually, so a
+    // parent's underline stays on (inherited state) unless a child says `none`.
+    const decoration = pick(inline.textDecoration || inline.textDecorationLine, computed?.textDecorationLine || computed?.textDecoration);
+    if (decoration) {
+        const lower = decoration.toLowerCase();
+        if (lower.includes("underline")) {
+            format.underline = true;
+        }
+        if (lower.includes("line-through")) {
+            format.strikethrough = true;
+        }
+        if (/^\s*none\s*$/.test(lower)) {
+            format.underline = false;
+            format.strikethrough = false;
+        }
+    }
+    const verticalAlign = pick(inline.verticalAlign, computed?.verticalAlign)?.toLowerCase();
+    if (verticalAlign === "super") {
+        format.baselineOffset = "superscript";
+    }
+    else if (verticalAlign === "sub") {
+        format.baselineOffset = "subscript";
+    }
+    else if (verticalAlign === "baseline" && tag !== "sup" && tag !== "sub") {
+        format.baselineOffset = null;
+    }
+    const color = cssColorToHex(inline.color) ?? attrColor ?? cssColorToHex(computed?.color);
+    if (color) {
+        format.color = color;
+    }
+    const fontSize = cssFontSizeToPt(inline.fontSize) ??
+        attrSize ??
+        cssFontSizeToPt(computed?.fontSize);
+    if (fontSize !== undefined) {
+        format.fontSize = fontSize;
+    }
+    const fontFamily = firstFontFamily(inline.fontFamily) ??
+        attrFace ??
+        firstFontFamily(computed?.fontFamily);
+    if (fontFamily) {
+        format.fontFamily = fontFamily;
+    }
+    return format;
+};
+const isBlockElement = (element) => {
+    const tag = element.tagName.toLowerCase();
+    if (BLOCK_TAGS.has(tag)) {
+        return true;
+    }
+    const display = element.style.display?.toLowerCase();
+    return display === "block" || display === "list-item";
+};
+const collectSegments = (node, inherited, segments) => {
+    if (node.nodeType === Node.TEXT_NODE) {
+        const text = normalizeWhitespace(node.textContent ?? "");
+        if (text) {
+            segments.push({ text, format: inherited });
+        }
+        return;
+    }
+    if (node.nodeType !== Node.ELEMENT_NODE) {
+        return;
+    }
+    const element = node;
+    const tag = element.tagName.toLowerCase();
+    if (SKIPPED_TAGS.has(tag)) {
+        return;
+    }
+    if (tag === "br") {
+        segments.push({ text: "\n", format: inherited });
+        return;
+    }
+    const block = isBlockElement(element);
+    if (block && segments.length && !endsWithNewline(segments)) {
+        segments.push({ text: "\n", format: inherited });
+    }
+    const format = readElementFormat(element, inherited);
+    for (const child of Array.from(element.childNodes)) {
+        collectSegments(child, format, segments);
+    }
+    if (block && segments.length && !endsWithNewline(segments)) {
+        segments.push({ text: "\n", format: inherited });
+    }
+};
+const endsWithNewline = (segments) => {
+    const last = segments[segments.length - 1];
+    return !!last && last.text.endsWith("\n");
+};
+const TEXT_KEYS = [
+    "bold",
+    "italic",
+    "underline",
+    "strikethrough",
+    "baselineOffset",
+    "color",
+    "fontSize",
+    "fontFamily",
+];
+/** The properties of `format` that differ from `base` (the run's own contribution). */
+const diffFormat = (format, base) => {
+    const diff = {};
+    for (const key of TEXT_KEYS) {
+        const value = format[key];
+        const baseValue = base[key];
+        const normalizedValue = value ?? undefined;
+        const normalizedBase = baseValue ?? undefined;
+        if (normalizedValue === normalizedBase) {
+            continue;
+        }
+        if (normalizedValue === undefined || normalizedValue === false) {
+            // A run switching OFF a base property (bold cell, normal run).
+            if (normalizedBase) {
+                diff[key] =
+                    key === "baselineOffset" ? null : false;
+            }
+            continue;
+        }
+        // Black on an unstyled base is the default text color, not a run color.
+        if (key === "color" &&
+            normalizedBase === undefined &&
+            typeof normalizedValue === "string" &&
+            normalizedValue.toUpperCase() === "#000000") {
+            continue;
+        }
+        diff[key] = normalizedValue;
+    }
+    return diff;
+};
+const sameFormat = (a, b) => {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const key of keys) {
+        const av = a[key];
+        const bv = b[key];
+        if (key === "link") {
+            if (av?.uri !== bv?.uri) {
+                return false;
+            }
+            continue;
+        }
+        if (av !== bv) {
+            return false;
+        }
+    }
+    return true;
+};
+const isEmptyFormat = (format) => Object.keys(format).length === 0;
+/**
+ * Convert a mounted element (a clipboard `<td>`, or the sandbox wrapper for
+ * table-less HTML) into the engine's rich-text shape. See the module doc.
+ */
+export const htmlElementToRichText = (root) => {
+    const baseFormat = normalizeBase(readElementFormat(root, {}));
+    const segments = [];
+    for (const child of Array.from(root.childNodes)) {
+        collectSegments(child, baseFormat, segments);
+    }
+    // Trim outer whitespace (leading/trailing spaces and line breaks) so the
+    // text matches `extractTextContent`, shifting the segments with it.
+    const joined = segments.map((s) => s.text).join("");
+    const leading = joined.length - joined.trimStart().length;
+    const text = joined.trim();
+    const runs = [];
+    const links = [];
+    let cursor = -leading;
+    for (const segment of segments) {
+        const start = Math.max(0, cursor);
+        const end = Math.min(text.length, cursor + segment.text.length);
+        cursor += segment.text.length;
+        if (end <= start) {
+            continue;
+        }
+        const format = diffFormat(segment.format, baseFormat);
+        const uri = segment.format.link?.uri;
+        if (uri) {
+            format.link = { uri };
+            const previous = links[links.length - 1];
+            if (previous && previous.uri === uri && previous.endIndex === start) {
+                previous.endIndex = end;
+            }
+            else {
+                links.push({ startIndex: start, endIndex: end, uri });
+            }
+        }
+        if (isEmptyFormat(format)) {
+            continue;
+        }
+        const previous = runs[runs.length - 1];
+        if (previous &&
+            previous.nodeType === "text" &&
+            previous.endIndex === start &&
+            sameFormat(previous.format, format)) {
+            previous.endIndex = end;
+            continue;
+        }
+        runs.push({ startIndex: start, endIndex: end, format, nodeType: "text" });
+    }
+    const wholeTextLink = links.find((link) => link.startIndex === 0 && link.endIndex === text.length);
+    const hyperlink = wholeTextLink?.uri ?? links[0]?.uri;
+    return {
+        text,
+        runs: runs.length ? runs : undefined,
+        links,
+        hyperlink,
+        baseFormat,
+        isRich: runs.length > 0 || links.length > 0,
+    };
+};
+// The base drops the segment-only `link` key and `false`/`null` values — a
+// container can't be "not bold" more than the default already is.
+const normalizeBase = (format) => {
+    const base = {};
+    for (const key of TEXT_KEYS) {
+        const value = format[key];
+        if (value === undefined || value === null || value === false) {
+            continue;
+        }
+        base[key] = value;
+    }
+    return base;
+};
+/**
+ * The element a single-cell clipboard payload's text lives in: the lone
+ * `<td>`/`<th>` of a one-cell table (Excel / Google Sheets), or the mounted
+ * wrapper for table-less HTML. `undefined` for a multi-cell table — that is a
+ * grid paste, not a rich-text one.
+ */
+export const findSingleClipboardCell = (root) => {
+    const cells = root.querySelectorAll("td,th");
+    if (cells.length > 1) {
+        return undefined;
+    }
+    if (cells.length === 1) {
+        return cells[0];
+    }
+    return root;
+};
+/**
+ * One-shot helper for the editor targets: mount the clipboard HTML, convert
+ * the single cell it carries, clean up. `undefined` when the payload is a
+ * multi-cell table or carries no formatting/links worth keeping (the caller
+ * then falls back to its plain-text handling).
+ */
+export const clipboardHtmlToRichText = (html) => {
+    if (!canUseDOM || !html?.trim()) {
+        return undefined;
+    }
+    const { root, cleanup } = mountClipboardHtml(html);
+    try {
+        const cell = findSingleClipboardCell(root);
+        if (!cell) {
+            return undefined;
+        }
+        const parsed = htmlElementToRichText(cell);
+        if (!parsed.text || !parsed.isRich) {
+            return undefined;
+        }
+        return parsed;
+    }
+    finally {
+        cleanup();
+    }
+};

package/dist/esm/rich-text-links.d.ts

@@ -0,0 +1,23 @@
+import type { TextFormatRun } from "@rowsncolumns/common-types";
+/**
+ * Reconcile a committed string's run-level links (`TextFormatRun.format.link`)
+ * with the cell-level `hyperlink`. Excel keeps ONE link per cell, painted and
+ * followed at the cell level; Google Sheets keeps several inside the text.
+ * Both engines apply this on commit (`SheetCell.setStringValue`, rnc-store
+ * `apply_set_value_rich_text`) so a rich paste lands the same way whether it
+ * came through the grid, the formula bar or the in-cell editor:
+ *
+ * - a cell without a hyperlink takes the FIRST run link as its hyperlink;
+ * - a run link equal to the cell hyperlink that spans the WHOLE text is
+ *   redundant (that is exactly what the cell hyperlink says) and is stripped
+ *   — the run itself goes when nothing else is left on it;
+ * - every other run link stays as data (the multi-link cell keeps them all).
+ */
+export type ResolvedRunLinks = {
+    runs: TextFormatRun[] | undefined | null;
+    hyperlink: string | undefined;
+    /** True when `runs` or `hyperlink` differ from the input. */
+    changed: boolean;
+};
+export declare const promoteRunLinkToHyperlink: (text: string, runs: TextFormatRun[] | undefined | null, hyperlink: string | undefined | null) => ResolvedRunLinks;
+//# sourceMappingURL=rich-text-links.d.ts.map

package/dist/esm/rich-text-links.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rich-text-links.d.ts","sourceRoot":"","sources":["../../rich-text-links.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEhE;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,aAAa,EAAE,GAAG,SAAS,GAAG,IAAI,CAAC;IACzC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,eAAO,MAAM,yBAAyB,GACpC,MAAM,MAAM,EACZ,MAAM,aAAa,EAAE,GAAG,SAAS,GAAG,IAAI,EACxC,WAAW,MAAM,GAAG,SAAS,GAAG,IAAI,KACnC,gBAkCF,CAAC"}

package/dist/esm/rich-text-links.js

@@ -0,0 +1,31 @@
+export const promoteRunLinkToHyperlink = (text, runs, hyperlink) => {
+    if (!runs || runs.length === 0) {
+        return { runs, hyperlink: hyperlink ?? undefined, changed: false };
+    }
+    const firstLink = runs.find((run) => run.nodeType !== "mention" && run.format?.link?.uri);
+    if (!firstLink || firstLink.nodeType === "mention") {
+        return { runs, hyperlink: hyperlink ?? undefined, changed: false };
+    }
+    const resolvedHyperlink = hyperlink || firstLink.format.link.uri;
+    let changed = resolvedHyperlink !== (hyperlink ?? undefined);
+    const stripped = [];
+    for (const run of runs) {
+        if (run.nodeType === "mention" ||
+            run.format?.link?.uri !== resolvedHyperlink ||
+            run.startIndex !== 0 ||
+            run.endIndex < text.length) {
+            stripped.push(run);
+            continue;
+        }
+        changed = true;
+        const { link: _link, ...rest } = run.format;
+        if (Object.keys(rest).length > 0) {
+            stripped.push({ ...run, format: rest });
+        }
+    }
+    return {
+        runs: changed ? (stripped.length ? stripped : undefined) : runs,
+        hyperlink: resolvedHyperlink,
+        changed,
+    };
+};

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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"}