@rowsncolumns/utils 9.4.0 → 9.5.0

package/dist/esm/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;AAC7B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,oBAAoB,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;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC"}

package/dist/esm/index.js

@@ -28,3 +28,5 @@ export * from "./formula-locale";
 export * from "./table-names";
 export * from "./table-totals";
 export * from "./sparkline-groups";
+export * from "./rich-text-html";
+export * from "./rich-text-links";

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

@@ -0,0 +1,82 @@
+import type { TextFormat, TextFormatRun } from "@rowsncolumns/common-types";
+/**
+ * Clipboard HTML → the engine's native rich-text shape.
+ *
+ * Google Sheets and Excel both put a cell's mixed formatting into `text/html`
+ * — Google as `<span style="…">` / `<a href>` runs inside a `<td>` (wrapped in
+ * `<google-sheets-html-origin>`), Excel as `<b>` / `<font color>` /
+ * `<font class="fontN">` (class rules in `<head><style>`) / `<span style>` /
+ * `<a href>` inside a `<td>`. This module is the ONE converter every paste
+ * target uses (the grid's cell paste in `spreadsheet-state/api/parse-html`,
+ * the formula bar and the in-cell editor in `ui/editor-pm`), so a rich cell
+ * lands identically wherever it is pasted:
+ *
+ * - `text` — the full text, whitespace normalized like `extractTextContent`
+ *   (source-newlines collapse to a space, `<br>` / block boundaries become
+ *   `\n`, outer whitespace trimmed).
+ * - `runs` — `TextFormatRun`s RELATIVE to `baseFormat` (only the properties a
+ *   segment changes), adjacent equal segments merged, empty formats dropped —
+ *   the same normal form `extractTextFormatRuns` produces from the editor.
+ *   `undefined` when the text is uniformly formatted (then `baseFormat`
+ *   already says everything).
+ * - `links` — every `<a href>` in document order, as `[start, end)` spans.
+ *   A link is also carried on its run as `format.link` (Google Sheets keeps
+ *   several links per cell), and the engines promote the first run link to the
+ *   cell-level `hyperlink` on commit (Excel keeps one link per cell).
+ * - `hyperlink` — the cell-level link: an anchor wrapping the whole text
+ *   (Excel), else the first link.
+ * - `baseFormat` — the container's own formatting (the `<td>` class / inline
+ *   style), i.e. the CELL-level text format of the source cell.
+ *
+ * Styles are read from the inline `style`, the tag semantics and
+ * `getComputedStyle` (the element must be mounted — see
+ * {@link mountClipboardHtml}) so Excel's class-based `<font class="fontN">`
+ * runs resolve. `<a>` elements read inline styles only: a browser's UA sheet
+ * would otherwise paint every pasted link `-webkit-link` blue.
+ */
+export type RichTextLink = {
+    startIndex: number;
+    endIndex: number;
+    uri: string;
+};
+export type ParsedRichText = {
+    text: string;
+    runs: TextFormatRun[] | undefined;
+    links: RichTextLink[];
+    hyperlink: string | undefined;
+    baseFormat: TextFormat;
+    /** Mixed formatting or at least one link — the reasons to prefer runs over flat text. */
+    isRich: boolean;
+};
+/**
+ * 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 declare const mountClipboardHtml: (clipboardValue: string) => {
+    root: HTMLDivElement;
+    cleanup: () => void;
+};
+export declare const cssColorToHex: (value: string | null | undefined) => string | undefined;
+/** CSS font-size → points. `pt` verbatim, `px` at 96dpi, `em`/`rem` on a 16px base. */
+export declare const cssFontSizeToPt: (value: string | null | undefined) => number | undefined;
+/**
+ * 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 declare const htmlElementToRichText: (root: HTMLElement) => ParsedRichText;
+/**
+ * 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 declare const findSingleClipboardCell: (root: HTMLElement) => HTMLElement | undefined;
+/**
+ * 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 declare const clipboardHtmlToRichText: (html: string) => ParsedRichText | undefined;
+//# sourceMappingURL=rich-text-html.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rich-text-html.d.ts","sourceRoot":"","sources":["../../rich-text-html.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAK5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,MAAM,MAAM,YAAY,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,EAAE,GAAG,SAAS,CAAC;IAClC,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,UAAU,EAAE,UAAU,CAAC;IACvB,yFAAyF;IACzF,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAgGF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,gBAAgB,MAAM;;;CAmBxD,CAAC;AAEF,eAAO,MAAM,aAAa,GACxB,OAAO,MAAM,GAAG,IAAI,GAAG,SAAS,KAC/B,MAAM,GAAG,SAkBX,CAAC;AAEF,uFAAuF;AACvF,eAAO,MAAM,eAAe,GAC1B,OAAO,MAAM,GAAG,IAAI,GAAG,SAAS,KAC/B,MAAM,GAAG,SAoBX,CAAC;AA+SF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,MAAM,WAAW,KAAG,cA+DzD,CAAC;AAgBF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAClC,MAAM,WAAW,KAChB,WAAW,GAAG,SAShB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAClC,MAAM,MAAM,KACX,cAAc,GAAG,SAkBnB,CAAC"}

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/tsconfig.esm.tsbuildinfo

@@ -1 +1 @@
-{"root":["../../array.ts","../../cell-data-helpers.ts","../../color.ts","../../colors.ts","../../conditional-format.ts","../../content-hash.ts","../../data-validation.ts","../../date.ts","../../dom.ts","../../excel-number-format.ts","../../formatter.ts","../../formula-locale.ts","../../formula-refs.ts","../../formula.ts","../../index.ts","../../keyboard.ts","../../locale.ts","../../log.ts","../../memoize.ts","../../numbers.ts","../../selection.ts","../../shared-string-canonical.ts","../../sheet-span.ts","../../sort.ts","../../sparkline-groups.ts","../../string.ts","../../table-names.ts","../../table-styles.ts","../../table-totals.ts","../../typeguards.ts","../../uuid.ts","../../vitest.config.ts","../../formula-locale/formula-locale-data.generated.ts"],"version":"5.8.3"}
+{"root":["../../array.ts","../../cell-data-helpers.ts","../../color.ts","../../colors.ts","../../conditional-format.ts","../../content-hash.ts","../../data-validation.ts","../../date.ts","../../dom.ts","../../excel-number-format.ts","../../formatter.ts","../../formula-locale.ts","../../formula-refs.ts","../../formula.ts","../../index.ts","../../keyboard.ts","../../locale.ts","../../log.ts","../../memoize.ts","../../numbers.ts","../../rich-text-html.ts","../../rich-text-links.ts","../../selection.ts","../../shared-string-canonical.ts","../../sheet-span.ts","../../sort.ts","../../sparkline-groups.ts","../../string.ts","../../table-names.ts","../../table-styles.ts","../../table-totals.ts","../../typeguards.ts","../../uuid.ts","../../vitest.config.ts","../../formula-locale/formula-locale-data.generated.ts"],"version":"5.8.3"}