@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/paste-special.js

@@ -0,0 +1,601 @@
+/**
+ * Paste Special, and the HTML clipboard round-trip that makes it worth having.
+ *
+ * The grid's clipboard is TSV only: `writeText` out, `readText` in. That is
+ * fine for values and loses everything else, so a trip through Excel drops
+ * every format, every formula and every merge. Excel itself writes both
+ * `text/plain` and `text/html`, and reads the HTML back when it is there.
+ * Matching that is what makes the grid part of someone's workflow rather than
+ * an island.
+ *
+ * The HTML is a plain `<table>`, which is what Excel, Sheets, Numbers and
+ * every web app already understand. Formats ride on inline styles they all
+ * read (with Excel's `mso-number-format` beside them so Excel keeps the
+ * number format too), the number behind a formatted display rides in
+ * Excel's `x:num`, and the formula travels in a `data-formula` attribute
+ * they all ignore, so a paste into Excel keeps the look while a paste back
+ * into the grid keeps the formula.
+ *
+ * Reading goes the other way: Excel's `<style>` classes, `x:fmla` and
+ * `x:num`, and Sheets' `data-sheets-*` attributes all come through, so a
+ * block copied from either arrives with its values, formulas and formats.
+ */
+import { translateFormula, transposeFormula } from './refs.js';
+import { parseFormula } from './parse.js';
+import { visit } from './ast.js';
+import { entryToStyle } from './format-store.js';
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/**
+ * A number format the way Excel writes it in `mso-number-format`: quoted,
+ * every literal escaped with a backslash and a double quote as `\0022`.
+ * Excel reads the property back from inline styles, which is how a paste
+ * into it keeps `#,##0.00` rather than guessing a format from the text.
+ */
+export function msoNumberFormat(code) {
+    const body = code
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\0022')
+        .replace(/([^A-Za-z0-9 \\])/g, '\\$1');
+    return `"${body}"`;
+}
+/**
+ * Serialise a grid to the two clipboard flavours.
+ *
+ * The marker class is how `parseClipboardHtml` knows a paste came from a grid
+ * and can trust the `data-formula` attributes; HTML from anywhere else is
+ * read for text and styles only.
+ */
+export function buildClipboardPayload(grid, 
+/** Where the copy came from, so a pasted formula knows how far it moved.
+ *  Omit for a synthetic payload; references then paste unshifted. */
+origin) {
+    const text = grid.map((row) => row.map((cell) => cell.text).join('\t')).join('\n');
+    const rows = grid.map((row) => {
+        const cells = row.map((cell) => {
+            const numFmt = cell.format?.numFmt;
+            const style = [entryToStyle(cell.format), numFmt ? `mso-number-format:${msoNumberFormat(numFmt)}` : '']
+                .filter(Boolean)
+                .join(';');
+            const numeric = cell.value !== undefined && cell.value !== '' && Number.isFinite(Number(cell.value));
+            const attrs = [
+                style ? ` style="${esc(style)}"` : '',
+                numeric ? ` x:num="${esc(cell.value)}"` : '',
+                cell.formula ? ` data-formula="${esc(cell.formula)}"` : '',
+                numFmt ? ` data-numfmt="${esc(numFmt)}"` : '',
+            ].join('');
+            return `<td${attrs}>${esc(cell.text)}</td>`;
+        });
+        return `<tr>${cells.join('')}</tr>`;
+    });
+    const originAttr = origin
+        ? ` data-origin="${origin.row} ${origin.col}"`
+        : '';
+    // The x: namespace is Excel's; declaring it is what makes Excel read x:num.
+    const html = `<table class="svgrid-clipboard" xmlns:x="urn:schemas-microsoft-com:office:excel"${originAttr}><tbody>` +
+        rows.join('') + '</tbody></table>';
+    return { text, html };
+}
+const R1C1_REF = /\bR(?:\[(-?\d+)\]|(\d+))?C(?:\[(-?\d+)\]|(\d+))?(?![A-Za-z0-9_(])/g;
+/** Whether a formula is written in R1C1, as Google Sheets writes them. */
+export function isR1C1(formula) {
+    R1C1_REF.lastIndex = 0;
+    const outside = formula.replace(/"[^"]*"|'[^']*'/g, (m) => ' '.repeat(m.length));
+    return R1C1_REF.test(outside);
+}
+/**
+ * An R1C1 formula as A1, for the cell it lands in. `R[-1]C` is the cell
+ * above wherever the formula sits, `R2C3` is $C$2 anywhere, and a bare
+ * `RC` is the cell itself. Quoted strings and sheet names pass through.
+ */
+export function r1c1ToA1(formula, row, col) {
+    const letters = (index) => {
+        let n = index + 1;
+        let out = '';
+        while (n > 0) {
+            const rem = (n - 1) % 26;
+            out = String.fromCharCode(65 + rem) + out;
+            n = Math.floor((n - 1) / 26);
+        }
+        return out;
+    };
+    const convert = (chunk) => chunk.replace(R1C1_REF, (m, rRel, rAbs, cRel, cAbs) => {
+        const r = rAbs !== undefined ? Number(rAbs) - 1 : row + Number(rRel ?? 0);
+        const c = cAbs !== undefined ? Number(cAbs) - 1 : col + Number(cRel ?? 0);
+        if (r < 0 || c < 0)
+            return m;
+        return `${cAbs !== undefined ? '$' : ''}${letters(c)}${rAbs !== undefined ? '$' : ''}${r + 1}`;
+    });
+    // Convert only the text between quotes.
+    let out = '';
+    let start = 0;
+    const quoted = /"[^"]*"|'[^']*'/g;
+    let m;
+    while ((m = quoted.exec(formula))) {
+        out += convert(formula.slice(start, m.index)) + m[0];
+        start = m.index + m[0].length;
+    }
+    return out + convert(formula.slice(start));
+}
+/** Parse a TSV clipboard into a grid of text-only cells. */
+export function parseClipboardText(text) {
+    const lines = text.replace(/\r\n/g, '\n').split('\n');
+    if (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines.map((line) => line.split('\t').map((cellText) => ({ text: cellText })));
+}
+/**
+ * The declarations of a style string, last one wins as in CSS, with quoted
+ * values kept whole (a number format carries ';' between its sections).
+ * `background-color` folds into `background` so the two spellings override
+ * each other in order.
+ */
+function declarationsOf(style) {
+    const out = new Map();
+    let quote = null;
+    let start = 0;
+    const take = (part) => {
+        const i = part.indexOf(':');
+        if (i < 0)
+            return;
+        let prop = part.slice(0, i).trim().toLowerCase();
+        if (prop === 'background-color')
+            prop = 'background';
+        if (prop)
+            out.set(prop, part.slice(i + 1).trim());
+    };
+    for (let i = 0; i < style.length; i += 1) {
+        const ch = style[i];
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+        }
+        else if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === ';') {
+            take(style.slice(start, i));
+            start = i + 1;
+        }
+    }
+    take(style.slice(start));
+    return out;
+}
+const AUTOMATIC_COLOR = /^(?:windowtext|black|#000|#000000)$/i;
+const STYLE_TO_ENTRY = {
+    'font-weight': (v, into) => {
+        if (/^(?:bold|bolder|[6-9]00)$/i.test(v))
+            into.bold = true;
+        else
+            delete into.bold;
+    },
+    'font-style': (v, into) => {
+        if (/^(?:italic|oblique)$/i.test(v))
+            into.italic = true;
+        else
+            delete into.italic;
+    },
+    'text-decoration': (v, into) => {
+        if (/underline/i.test(v))
+            into.underline = true;
+        else
+            delete into.underline;
+        if (/line-through/i.test(v))
+            into.strike = true;
+        else
+            delete into.strike;
+    },
+    color: (v, into) => {
+        // Excel writes the automatic colour as windowtext (or black in older
+        // builds); that is "no colour set", not a black override.
+        if (AUTOMATIC_COLOR.test(v))
+            delete into.color;
+        else
+            into.color = v;
+    },
+    background: (v, into) => {
+        if (/^(?:transparent|none|auto)$/i.test(v))
+            delete into.fill;
+        else
+            into.fill = v;
+    },
+    'text-align': (v, into) => {
+        if (/^(?:left|center|right)$/i.test(v))
+            into.align = v.toLowerCase();
+        else
+            delete into.align;
+    },
+    'font-family': (v, into) => {
+        // The first family, unquoted; Excel writes "Aptos Narrow", sans-serif.
+        const first = v.split(',')[0].trim().replace(/^["']|["']$/g, '');
+        if (first)
+            into.fontFamily = first;
+    },
+    'font-size': (v, into) => {
+        const m = /^([\d.]+)(pt|px)$/i.exec(v);
+        if (!m)
+            return;
+        const n = Number(m[1]);
+        if (!Number.isFinite(n) || n <= 0)
+            return;
+        into.fontSize = m[2].toLowerCase() === 'pt' ? Math.round((n * 96) / 72) : Math.round(n);
+    },
+    'white-space': (v, into) => {
+        if (/^(?:pre-wrap|normal|pre-line)$/i.test(v))
+            into.wrap = true;
+        else
+            delete into.wrap;
+    },
+};
+/**
+ * Excel's `mso-number-format` as our number format. Excel escapes the
+ * literal characters of a code (`0\.00`), and names a few formats rather
+ * than spelling them; the names map to the codes Excel shows for them.
+ */
+const MSO_NAMED_FORMATS = {
+    general: undefined,
+    'general number': undefined,
+    standard: '#,##0.00',
+    fixed: '0.00',
+    percent: '0.00%',
+    currency: '$#,##0.00',
+    scientific: '0.00E+00',
+    'short date': 'm/d/yyyy',
+    'medium date': 'd-mmm-yy',
+    'long date': 'dddd, mmmm d, yyyy',
+    'short time': 'h:mm',
+    'medium time': 'h:mm AM/PM',
+    'long time': 'h:mm:ss AM/PM',
+    '@': '@',
+};
+export function numFmtFromMso(value) {
+    const raw = value.trim().replace(/^["']|["']$/g, '');
+    if (!raw)
+        return undefined;
+    const named = MSO_NAMED_FORMATS[raw.toLowerCase()];
+    if (raw.toLowerCase() in MSO_NAMED_FORMATS)
+        return named;
+    // Excel escapes every literal (\# \, \. \@) and writes a double quote as
+    // \0022; our codes take the literals plain.
+    return raw.replace(/\\0022/g, '"').replace(/\\([^A-Za-z0-9])/g, '$1');
+}
+function entryFromStyle(style, numFmt) {
+    const into = {};
+    if (style) {
+        for (const [prop, value] of declarationsOf(style)) {
+            if (prop === 'mso-number-format') {
+                if (numFmt !== null)
+                    continue;
+                const code = numFmtFromMso(value);
+                if (code)
+                    into.numFmt = code;
+                else
+                    delete into.numFmt;
+            }
+            else {
+                STYLE_TO_ENTRY[prop]?.(value, into);
+            }
+        }
+    }
+    if (numFmt)
+        into.numFmt = numFmt;
+    return Object.keys(into).length > 0 ? into : undefined;
+}
+/**
+ * The class rules of a clipboard document. Excel puts every cell's format in
+ * a `<style>` block keyed by `class="xl65"`, one rule per class, and only
+ * the odd override inline; the declarations are merged under the inline
+ * style so the inline one wins where both speak.
+ */
+function classStyles(doc) {
+    const out = new Map();
+    for (const styleEl of doc.querySelectorAll('style')) {
+        const css = styleEl.textContent ?? '';
+        const rule = /([^{}]+)\{([^{}]*)\}/g;
+        let m;
+        while ((m = rule.exec(css))) {
+            const declarations = m[2].replace(/\s+/g, ' ').trim();
+            for (const selector of m[1].split(',')) {
+                const cls = /\.([\w-]+)\s*$/.exec(selector.trim());
+                if (cls)
+                    out.set(cls[1], (out.get(cls[1]) ? out.get(cls[1]) + ';' : '') + declarations);
+            }
+        }
+    }
+    return out;
+}
+/** The formula a cell carries, whichever spreadsheet wrote the HTML. */
+function formulaOf(td) {
+    const own = td.getAttribute('data-formula');
+    if (own)
+        return own;
+    const excel = td.getAttribute('x:fmla');
+    if (excel)
+        return excel.startsWith('=') ? excel : `=${excel}`;
+    const sheets = td.getAttribute('data-sheets-formula');
+    if (sheets)
+        return sheets.startsWith('=') ? sheets : `=${sheets}`;
+    return undefined;
+}
+/** The raw value behind a formatted display, when the source wrote one. */
+function rawValueOf(td) {
+    const excel = td.getAttribute('x:num');
+    if (excel !== null && excel !== '' && Number.isFinite(Number(excel)))
+        return excel;
+    const sheets = td.getAttribute('data-sheets-value');
+    if (sheets) {
+        try {
+            const parsed = JSON.parse(sheets);
+            if (typeof parsed['3'] === 'number')
+                return String(parsed['3']);
+            if (typeof parsed['2'] === 'string')
+                return parsed['2'];
+            if (typeof parsed['4'] === 'boolean')
+                return parsed['4'] ? 'TRUE' : 'FALSE';
+        }
+        catch {
+            // Not JSON: the display text stands.
+        }
+    }
+    return undefined;
+}
+/** Google Sheets' number format, when the cell carries one. */
+function sheetsNumFmt(td) {
+    const raw = td.getAttribute('data-sheets-numberformat');
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        return typeof parsed['2'] === 'string' ? parsed['2'] : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Parse clipboard HTML into a grid.
+ *
+ * Uses DOMParser rather than a regex: clipboard HTML from Excel is full of
+ * conditional comments, namespaced tags and unclosed elements, and a parser
+ * that already handles all of that ships in the browser.
+ *
+ * Returns null when the HTML holds no table, so the caller falls back to TSV.
+ */
+export function readClipboardOrigin(html) {
+    if (typeof DOMParser === 'undefined')
+        return null;
+    try {
+        const table = new DOMParser().parseFromString(html, 'text/html').querySelector('table');
+        const raw = table?.getAttribute('data-origin');
+        if (!raw)
+            return null;
+        const [row, col] = raw.split(' ').map(Number);
+        return Number.isFinite(row) && Number.isFinite(col)
+            ? { row: row, col: col }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function parseClipboardHtml(html) {
+    if (typeof DOMParser === 'undefined')
+        return null;
+    let doc;
+    try {
+        doc = new DOMParser().parseFromString(html, 'text/html');
+    }
+    catch {
+        return null;
+    }
+    const table = doc.querySelector('table');
+    if (!table)
+        return null;
+    const classes = classStyles(doc);
+    const grid = [];
+    for (const tr of table.querySelectorAll('tr')) {
+        const row = [];
+        for (const td of tr.querySelectorAll('td, th')) {
+            const formula = formulaOf(td);
+            const fromClasses = (td.getAttribute('class') ?? '')
+                .split(/\s+/)
+                .map((c) => classes.get(c))
+                .filter((c) => !!c);
+            const style = [...fromClasses, td.getAttribute('style') ?? ''].filter(Boolean).join(';');
+            const raw = rawValueOf(td);
+            row.push({
+                // textContent rather than innerText: this document is never rendered,
+                // so innerText would be empty. A source that wrote the raw value
+                // beside a formatted display (Excel's x:num, Sheets' data-sheets-value)
+                // pastes the value; the format carries the look.
+                text: raw ?? (td.textContent ?? '').replace(/ /g, ' ').trim(),
+                ...(formula ? { formula } : {}),
+                ...(() => {
+                    const entry = entryFromStyle(style || null, td.getAttribute('data-numfmt') ?? sheetsNumFmt(td));
+                    return entry ? { format: entry } : {};
+                })(),
+            });
+        }
+        if (row.length > 0)
+            grid.push(row);
+    }
+    return grid.length > 0 ? grid : null;
+}
+/** Read whichever flavour is richer. */
+export function parseClipboard(payload) {
+    if (payload.html) {
+        const fromHtml = parseClipboardHtml(payload.html);
+        if (fromHtml)
+            return fromHtml;
+    }
+    return parseClipboardText(payload.text ?? '');
+}
+function transposeGrid(grid) {
+    const rows = grid.length;
+    const cols = Math.max(0, ...grid.map((r) => r.length));
+    const out = [];
+    for (let c = 0; c < cols; c += 1) {
+        const row = [];
+        for (let r = 0; r < rows; r += 1)
+            row.push(grid[r]?.[c] ?? { text: '' });
+        out.push(row);
+    }
+    return out;
+}
+function arithmetic(existing, incoming, op) {
+    const a = Number(existing);
+    const b = Number(incoming);
+    if (!Number.isFinite(a) || !Number.isFinite(b))
+        return null;
+    switch (op) {
+        case 'add': return a + b;
+        case 'subtract': return a - b;
+        case 'multiply': return a * b;
+        // Excel gives #DIV/0! here; the caller writes the error, so report null
+        // and let it decide rather than inventing a zero.
+        case 'divide': return b === 0 ? null : a / b;
+        default: return null;
+    }
+}
+/**
+ * Decide what lands in one cell. Pure, so the whole option matrix is testable
+ * without a clipboard or a grid.
+ *
+ * `offset` is how far the destination sits from where the source was copied,
+ * which is what lets a pasted formula shift its relative references. `at`
+ * is the destination itself, which an R1C1 formula (Google Sheets writes
+ * them so) needs to become A1; it then needs no offset, being relative to
+ * wherever it lands.
+ */
+export function resolvePasteCell(source, existing, opts, offset = { rows: 0, cols: 0 }, at, 
+/** Where the cell came from and lands, for a transposed paste: its
+ *  relative references are turned rather than shifted. */
+turn) {
+    if (!source)
+        return { kind: 'skip' };
+    const what = opts.what ?? 'all';
+    const operation = opts.operation ?? 'none';
+    if (opts.skipBlanks && source.text === '' && !source.formula)
+        return { kind: 'skip' };
+    if (what === 'formats')
+        return { kind: 'format', format: source.format };
+    // Arithmetic ignores formats and formulas: Excel operates on values.
+    if (operation !== 'none') {
+        const result = arithmetic(existing, source.text, operation);
+        return result === null ? { kind: 'skip' } : { kind: 'value', value: String(result) };
+    }
+    const wantsFormula = what === 'all' || what === 'formulas';
+    const value = wantsFormula && source.formula
+        ? at && isR1C1(source.formula)
+            ? r1c1ToA1(source.formula, at.row, at.col)
+            : turn
+                ? String(transposeFormula(source.formula, turn.source, turn.dest))
+                : String(translateFormula(source.formula, offset.rows, offset.cols))
+        : source.text;
+    if (what === 'values' || what === 'formulas')
+        return { kind: 'value', value };
+    return { kind: 'both', value, format: source.format };
+}
+/**
+ * A block from another application says nothing about where it was copied
+ * from, and Excel's formulas come in A1 as written: `=B2*C2` beside a
+ * price and a quantity. Pasted anywhere but A1 with no shift, that formula
+ * reads the wrong cells. What CAN be known is whether the block is
+ * self-contained: with the block read as if copied from A1, a formula whose
+ * every reference falls inside the block (a totals column, a running sum,
+ * the blocks people copy) is kept and moves with the paste from that A1;
+ * one that reaches outside is pasted as its value, which is right wherever
+ * the block lands. R1C1 formulas (Google Sheets) are left alone: they are
+ * resolved against the cell they land in.
+ */
+export function anchorForeignFormulas(grid) {
+    const rows = grid.length;
+    const cols = Math.max(0, ...grid.map((r) => r.length));
+    let anchored = false;
+    const out = grid.map((row) => row.map((cell) => {
+        if (!cell.formula || isR1C1(cell.formula))
+            return cell;
+        let inside = true;
+        try {
+            visit(parseFormula(cell.formula), (n) => {
+                // A defined name or a table reference belongs to the source
+                // workbook; a sheet-qualified reference is outside by definition.
+                if (n.k === 'name' || n.k === 'table')
+                    inside = false;
+                if (n.k === 'ref') {
+                    if (n.ref.sheet || n.ref.row === null || n.ref.row >= rows || n.ref.col >= cols)
+                        inside = false;
+                }
+                if (n.k === 'range') {
+                    if (n.from.sheet || n.to.sheet)
+                        inside = false;
+                    const r2 = Math.max(n.from.row ?? rows, n.to.row ?? rows);
+                    if (r2 >= rows || Math.max(n.from.col, n.to.col) >= cols)
+                        inside = false;
+                }
+            });
+        }
+        catch {
+            inside = false;
+        }
+        if (!inside) {
+            const { formula: _dropped, ...rest } = cell;
+            return rest;
+        }
+        anchored = true;
+        return cell;
+    }));
+    return { grid: out, origin: anchored ? { row: 0, col: 0 } : null };
+}
+/**
+ * Where each source cell lands.
+ *
+ * The reference offset is the same for every cell, not per-cell: source and
+ * destination both advance together as the grid is walked, so the shift is
+ * just `destination - origin`. Computing it per cell is how you end up
+ * translating by the destination's absolute position, which is wrong
+ * everywhere except the top-left corner.
+ *
+ * With no `origin` the offset is zero. That is right rather than lazy: a
+ * formula pasted in from another application has no position in this sheet to
+ * have moved from.
+ *
+ * `fill` is the selection's size. A block that fits it a whole number of
+ * times is repeated over it, as Excel repeats a copied cell across a
+ * selected range (or two copied rows over six selected ones); each repeat
+ * gets its own offset, so a repeated formula points where a hand-copied one
+ * would. Otherwise the block lands at the destination and keeps its shape.
+ */
+export function planPaste(grid, destination, opts = {}, origin, fill) {
+    const shaped = opts.transpose ? transposeGrid(grid) : grid;
+    const height = shaped.length;
+    const width = shaped.reduce((max, row) => Math.max(max, row.length), 0);
+    const repeats = fill && height > 0 && width > 0
+        && fill.rows % height === 0 && fill.cols % width === 0
+        && (fill.rows > height || fill.cols > width)
+        ? { rows: fill.rows / height, cols: fill.cols / width }
+        : { rows: 1, cols: 1 };
+    const out = [];
+    for (let tr = 0; tr < repeats.rows; tr += 1) {
+        for (let tc = 0; tc < repeats.cols; tc += 1) {
+            const corner = { row: destination.row + tr * height, col: destination.col + tc * width };
+            // A transposed paste turns each formula's references instead of
+            // shifting them (see `transposeFormula`); the offset is for the rest.
+            const offset = origin && !opts.transpose
+                ? { rows: corner.row - origin.row, cols: corner.col - origin.col }
+                : { rows: 0, cols: 0 };
+            for (let r = 0; r < shaped.length; r += 1) {
+                const row = shaped[r] ?? [];
+                for (let c = 0; c < row.length; c += 1) {
+                    const source = row[c];
+                    if (!source)
+                        continue;
+                    const dest = { row: corner.row + r, col: corner.col + c };
+                    // In the turned grid, (r, c) came from (c, r) of the block.
+                    const turn = opts.transpose && origin ? { source: { row: origin.row + c, col: origin.col + r }, dest } : undefined;
+                    out.push({ ...dest, source, offset, ...(turn ? { turn } : {}) });
+                }
+            }
+        }
+    }
+    return out;
+}