@svgrid/enterprise 3.0.2 → 3.0.3

package/dist/sheet/presence.js

@@ -0,0 +1,79 @@
+/**
+ * Eight colours that read as different people rather than as a heat map,
+ * stay legible as a thin box over a white sheet and over a dark one, and
+ * each carry a white name at 11px at 4.5:1 or better, so every tag wears
+ * the same white ink. The first set had five a shade too light for that.
+ */
+export const PRESENCE_COLOURS = [
+    '#e11d48', '#2563eb', '#15803d', '#7e22ce',
+    '#c2410c', '#0e7490', '#a16207', '#db2777',
+];
+/** A colour for an id: the same person gets the same one every session. */
+export function presenceColour(id) {
+    let hash = 0;
+    for (let i = 0; i < id.length; i += 1)
+        hash = (hash * 31 + id.charCodeAt(i)) >>> 0;
+    return PRESENCE_COLOURS[hash % PRESENCE_COLOURS.length];
+}
+/**
+ * The ink for a name tag on a person's colour: black or white, whichever
+ * contrasts more. White on every colour was the first version, and white
+ * on the first set's green, orange or yellow was a little over 3:1, under
+ * the 4.5:1 an 11px name needs. The built-in set is dark enough now, but a
+ * collaborator's own colour can be anything, so the tag still asks.
+ * A colour that is not a hex triplet gets white, the way it always did.
+ */
+export function presenceInk(colour) {
+    const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(colour.trim());
+    if (!hex)
+        return '#fff';
+    const digits = hex[1].length === 3 ? [...hex[1]].map((d) => d + d).join('') : hex[1];
+    const channel = (at) => {
+        const c = parseInt(digits.slice(at, at + 2), 16) / 255;
+        return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+    };
+    const luminance = 0.2126 * channel(0) + 0.7152 * channel(2) + 0.0722 * channel(4);
+    // Contrast against white is (1.05 / (L + 0.05)); against black, (L + 0.05) / 0.05.
+    return 1.05 / (luminance + 0.05) >= (luminance + 0.05) / 0.05 ? '#fff' : '#000';
+}
+/** Two initials for the tag when the box is too small for a name. */
+export function presenceInitials(name) {
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return '?';
+    if (words.length === 1)
+        return words[0].slice(0, 2).toUpperCase();
+    return `${words[0][0]}${words[words.length - 1][0]}`.toUpperCase();
+}
+/**
+ * The peers still here: the newest entry per person, anyone quiet for
+ * longer than `timeoutMs` dropped.
+ *
+ * A network gives no "goodbye" when a tab is closed, so the only honest
+ * answer to "is this person still here" is how long ago they last said
+ * anything. Fifteen seconds is the grid's own answer, and this keeps to it.
+ */
+export function livePresence(list, now = Date.now(), timeoutMs = 15000) {
+    const newest = new Map();
+    for (const person of list) {
+        if (now - (person.at ?? now) > timeoutMs)
+            continue;
+        const had = newest.get(person.id);
+        if (!had || (person.at ?? now) >= (had.at ?? now))
+            newest.set(person.id, person);
+    }
+    return [...newest.values()];
+}
+/** The peers on one sheet, in a stable order so the boxes do not swap. */
+export function presenceOnSheet(list, sheet) {
+    return list
+        .filter((person) => person.sheet.toLowerCase() === sheet.toLowerCase())
+        .sort((a, b) => a.id.localeCompare(b.id));
+}
+/** Where the tag goes: the cell named, or the top-left of the selection. */
+export function presenceAnchor(person) {
+    if (person.active)
+        return person.active;
+    const [r1, c1] = person.rect;
+    return { row: r1, col: c1 };
+}

package/dist/sheet/print.d.ts

@@ -0,0 +1,104 @@
+/**
+ * A sheet as the page File > Print opens: one standalone HTML document the
+ * browser's own print engine lays out, so fonts, CJK and RTL come out
+ * right and nothing is bundled. The print area (or the used range) as a
+ * table, column widths and row heights as the sheet shows them, hidden
+ * lines left out, merges as spans, every cell with its format and its
+ * conditional style, the title rows in a `<thead>` so they repeat on each
+ * page, gridlines and headings when the setup asks, and `@page` carrying
+ * the orientation, paper and margins. Pure: the shell hands in what a cell
+ * shows and where; a test reads the HTML back.
+ */
+import type { CellFormatEntry, Rect } from './format-store.js';
+import type { CfStyle } from './conditional-formats.js';
+import { type PageSetup } from './page-setup.js';
+export type SheetPrintCell = {
+    /** What the cell shows. */
+    text: string;
+    /**
+     * The sparkline drawn in this cell, as SVG markup ready to place. Placed
+     * behind the text, as it is on screen, so a label typed over one still
+     * reads on the page.
+     */
+    sparkline?: string;
+    /**
+     * The picture an `IMAGE` cell shows, as markup ready to place. Fitted
+     * inside the cell, as it is on screen.
+     */
+    image?: string;
+    /**
+     * The table's look on this cell, where it is inside one: Excel prints a
+     * table banded, and the shell draws the look rather than writing it into
+     * the cells, so it has to be handed in here or the page comes out plain.
+     * Laid under the cell's own format, as it is on screen.
+     */
+    table?: {
+        fill?: string;
+        color?: string;
+        bold?: boolean;
+        borderTop?: string;
+        borderBottom?: string;
+    };
+    /** An error's colour, as the sheet paints it. */
+    color?: string;
+    /** Numbers right, text left, unless the format says. */
+    align?: 'left' | 'center' | 'right';
+    entry?: CellFormatEntry;
+    cf?: CfStyle;
+};
+export type SheetPrintInput = {
+    /** The sheet's name, the page's title. */
+    name: string;
+    /** The used range: rows and columns with anything in them. */
+    rowCount: number;
+    colCount: number;
+    cellAt: (r: number, c: number) => SheetPrintCell;
+    widths: Readonly<Record<string, number>>;
+    defaultWidth: number;
+    heights: ReadonlyMap<number, number>;
+    defaultHeight: number;
+    hidden: {
+        rows: ReadonlySet<number>;
+        cols: ReadonlySet<number>;
+    };
+    merges: ReadonlyArray<Rect>;
+    setup: PageSetup;
+    /**
+     * The charts and pictures over the cells, each as markup ready to place:
+     * an `<img>`, or a chart already drawn to `<svg>`.
+     *
+     * An object is placed against its ANCHOR CELL with the offset and size it
+     * has on the sheet, so the printed page puts it where the sheet does
+     * without the print builder knowing anything about layout. One anchored
+     * outside the printed area, or to a hidden line, is left out: there is no
+     * cell on the page to hang it from.
+     */
+    objects?: ReadonlyArray<SheetPrintObject>;
+};
+export type SheetPrintObject = {
+    /** The cell it hangs from. */
+    row: number;
+    col: number;
+    /** Its offset inside that cell, and its size, in pixels. */
+    dx: number;
+    dy: number;
+    width: number;
+    height: number;
+    /** The markup, placed as it stands. The caller has escaped it. */
+    html: string;
+};
+/** The rectangles that print: the setup's area, or the whole used range. */
+export declare function printAreas(input: Pick<SheetPrintInput, 'rowCount' | 'colCount' | 'setup'>): Rect[];
+/**
+ * The used range grown to hold what floats over it.
+ *
+ * A chart is almost always anchored BELOW the numbers it reads, which is
+ * past the last row with anything typed in it. Printing the used range and
+ * nothing else would drop it, so the default area grows to cover each
+ * object's cells, walking the widths and heights out from its anchor until
+ * the object is covered. An explicit print area is left exactly as it is:
+ * someone who named a block meant that block.
+ */
+export declare function areasWithObjects(input: SheetPrintInput): Rect[];
+/** One printable HTML document for the sheet. */
+export declare function sheetPrintHtml(input: SheetPrintInput): string;

package/dist/sheet/print.js

@@ -0,0 +1,169 @@
+import { entryToStyle } from './format-store.js';
+import { colToLetters } from './address.js';
+import { mergeAt, isCoveredCell } from './merges.js';
+import { marginsCss, PAPER_SIZES } from './page-setup.js';
+const HTML_ESCAPE = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+const esc = (s) => s.replace(/[&<>"']/g, (c) => HTML_ESCAPE[c]);
+/** The rectangles that print: the setup's area, or the whole used range. */
+export function printAreas(input) {
+    if (input.setup.printArea?.length)
+        return input.setup.printArea;
+    return [[0, 0, Math.max(0, input.rowCount - 1), Math.max(0, input.colCount - 1)]];
+}
+/**
+ * The used range grown to hold what floats over it.
+ *
+ * A chart is almost always anchored BELOW the numbers it reads, which is
+ * past the last row with anything typed in it. Printing the used range and
+ * nothing else would drop it, so the default area grows to cover each
+ * object's cells, walking the widths and heights out from its anchor until
+ * the object is covered. An explicit print area is left exactly as it is:
+ * someone who named a block meant that block.
+ */
+export function areasWithObjects(input) {
+    const areas = printAreas(input);
+    if (input.setup.printArea?.length || !input.objects?.length)
+        return areas;
+    const area = areas[0];
+    let [r1, c1, r2, c2] = area;
+    for (const object of input.objects) {
+        let row = object.row;
+        for (let covered = -object.dy; covered < object.height; row += 1) {
+            covered += input.heights.get(row) ?? input.defaultHeight;
+        }
+        let col = object.col;
+        for (let covered = -object.dx; covered < object.width; col += 1) {
+            covered += input.widths[colToLetters(col)] ?? input.defaultWidth;
+        }
+        r1 = Math.min(r1, object.row);
+        c1 = Math.min(c1, object.col);
+        r2 = Math.max(r2, row - 1);
+        c2 = Math.max(c2, col - 1);
+    }
+    return [[r1, c1, r2, c2]];
+}
+/** One printable HTML document for the sheet. */
+export function sheetPrintHtml(input) {
+    const { setup } = input;
+    /** The objects hanging from each cell, so a cell is one lookup. */
+    const byAnchor = new Map();
+    for (const object of input.objects ?? []) {
+        const key = `${object.row},${object.col}`;
+        const list = byAnchor.get(key);
+        if (list)
+            list.push(object);
+        else
+            byAnchor.set(key, [object]);
+    }
+    const visibleRows = (r1, r2) => { const out = []; for (let r = r1; r <= r2; r += 1)
+        if (!input.hidden.rows.has(r))
+            out.push(r); return out; };
+    const visibleCols = (c1, c2) => { const out = []; for (let c = c1; c <= c2; c += 1)
+        if (!input.hidden.cols.has(c))
+            out.push(c); return out; };
+    const cellHtml = (r, c, area, tag = 'td') => {
+        if (isCoveredCell(input.merges, r, c))
+            return '';
+        const cell = input.cellAt(r, c);
+        const merge = mergeAt(input.merges, r, c);
+        let span = '';
+        if (merge) {
+            const cols = visibleCols(Math.max(merge[1], area[1]), Math.min(merge[3], area[3])).length;
+            const rows = visibleRows(Math.max(merge[0], area[0]), Math.min(merge[2], area[2])).length;
+            if (cols > 1)
+                span += ` colspan="${cols}"`;
+            if (rows > 1)
+                span += ` rowspan="${rows}"`;
+        }
+        const styles = [];
+        const align = cell.entry?.align ?? cell.align;
+        if (align && align !== 'left')
+            styles.push(`text-align:${align}`);
+        // The table's bands go in first, so a fill or a colour written on the
+        // cell still wins, which is the order the screen draws them in.
+        if (cell.table) {
+            if (cell.table.fill)
+                styles.push(`background:${cell.table.fill}`);
+            if (cell.table.color)
+                styles.push(`color:${cell.table.color}`);
+            if (cell.table.bold)
+                styles.push('font-weight:600');
+            if (cell.table.borderTop)
+                styles.push(`border-top:1px solid ${cell.table.borderTop}`);
+            if (cell.table.borderBottom)
+                styles.push(`border-bottom:1px solid ${cell.table.borderBottom}`);
+        }
+        const own = entryToStyle(cell.entry);
+        if (own)
+            styles.push(own);
+        if (cell.cf)
+            styles.push(entryToStyle(cell.cf));
+        if (cell.color)
+            styles.push(`color:${cell.color}`);
+        const style = styles.length ? ` style="${esc(styles.filter(Boolean).join(';'))}"` : '';
+        // A sparkline goes behind the text; an object hangs from the cell and is
+        // allowed to overflow it, which is what makes a chart bigger than one
+        // cell print as a chart rather than as a sliver.
+        const spark = cell.sparkline ? `<span class="sp">${cell.sparkline}</span>` : '';
+        const picture = cell.image ? `<span class="im">${cell.image}</span>` : '';
+        const objects = (byAnchor.get(`${r},${c}`) ?? [])
+            .map((o) => `<span class="ob" style="inset-inline-start:${o.dx}px;top:${o.dy}px;width:${o.width}px;height:${o.height}px">${o.html}</span>`)
+            .join('');
+        const classes = [spark || picture ? 'sp-cell' : '', objects ? 'ob-cell' : ''].filter(Boolean).join(' ');
+        const cls = classes ? ` class="${classes}"` : '';
+        // A cell past the written area has nothing to say, and a caller reading
+        // one is not a reason to throw during a print.
+        const text = esc(cell.text ?? '');
+        const body = spark || picture || objects
+            ? `${spark}${picture}${objects}<span class="tx">${cell.image ? '' : text}</span>`
+            : text;
+        return `<${tag}${span}${cls}${style}>${body}</${tag}>`;
+    };
+    const rowHtml = (r, cols, area, head = false) => {
+        const h = input.heights.get(r) ?? input.defaultHeight;
+        const heading = setup.headings ? `<th class="rh">${r + 1}</th>` : '';
+        return `<tr style="height:${h}px">${heading}${cols.map((c) => cellHtml(r, c, area, head ? 'th' : 'td')).join('')}</tr>`;
+    };
+    const tables = areasWithObjects(input).map((area) => {
+        const cols = visibleCols(area[1], area[3]);
+        const rows = visibleRows(area[0], area[2]);
+        const colgroup = `<colgroup>${setup.headings ? '<col style="width:40px">' : ''}${cols.map((c) => `<col style="width:${input.widths[colToLetters(c)] ?? input.defaultWidth}px">`).join('')}</colgroup>`;
+        const headings = setup.headings ? `<tr class="ch"><th class="corner"></th>${cols.map((c) => `<th>${colToLetters(c)}</th>`).join('')}</tr>` : '';
+        // The title rows repeat on every page when they sit above or inside the area.
+        const titles = setup.printTitleRows;
+        const titleRows = titles && titles[0] <= area[2] ? visibleRows(titles[0], Math.min(titles[1], area[2])).filter((r) => r < area[0] || r <= area[2]) : [];
+        const bodyRows = rows.filter((r) => !titleRows.includes(r));
+        const thead = headings || titleRows.length
+            ? `<thead>${headings}${titleRows.map((r) => rowHtml(r, cols, [Math.min(r, area[0]), area[1], area[2], area[3]], true)).join('')}</thead>`
+            : '';
+        return `<table>${colgroup}${thead}<tbody>${bodyRows.map((r) => rowHtml(r, cols, area)).join('')}</tbody></table>`;
+    });
+    const paper = PAPER_SIZES[setup.paper]?.css ?? 'A4';
+    const grid = setup.gridlines ? 'td, th { border: 1px solid #d0d0d0; }' : 'td, th { border: 1px solid transparent; }';
+    return `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>${esc(input.name)}</title>
+<style>
+  @page { size: ${paper} ${setup.orientation}; margin: ${marginsCss(setup.margins)}; }
+  @media print { body { -webkit-print-color-adjust: exact; print-color-adjust: exact; } }
+  body { font-family: Calibri, "Segoe UI", -apple-system, Roboto, sans-serif; font-size: 11pt; color: #000; margin: 0; }
+  table { border-collapse: collapse; table-layout: fixed; zoom: ${setup.scale / 100}; }
+  table + table { break-before: page; }
+  thead { display: table-header-group; }
+  tr { break-inside: avoid; }
+  ${grid}
+  td, th { padding: 1px 4px; overflow: hidden; white-space: nowrap; text-overflow: clip; text-align: left; font-weight: 400; vertical-align: bottom; }
+  th.rh, tr.ch th { background: #f2f2f2; color: #444; text-align: center; font-size: 9pt; border: 1px solid #c8c8c8; }
+  td.sp-cell, td.ob-cell { position: relative; }
+  td.ob-cell { overflow: visible; }
+  td .sp { position: absolute; inset: 1px 4px; display: block; }
+  td .sp svg { width: 100%; height: 100%; }
+  td .im { position: absolute; inset: 1px 2px; display: block; }
+  td .im img { width: 100%; height: 100%; object-fit: contain; }
+  td .ob { position: absolute; display: block; overflow: hidden; }
+  td .ob img, td .ob svg { width: 100%; height: 100%; object-fit: contain; }
+  td .tx { position: relative; }
+</style></head>
+<body>
+  ${tables.join('\n  ')}
+</body></html>`;
+}

package/dist/sheet/protection.d.ts

@@ -3,19 +3,73 @@
  * Format Cells > Protection unlocks the ones that may change, and Protect
  * Sheet turns the flags on. Until then a locked cell is an ordinary cell.
  *
+ * Two refinements ride beside the flag, as they do in Excel. The "allow
+ * all users of this worksheet to" list of the Protect Sheet dialog says
+ * which kinds of change stay open while the sheet is protected (format
+ * cells, size and hide lines, insert and delete, sort, filter); and Allow
+ * Edit Ranges names blocks that take an edit on a protected sheet whether
+ * their cells are locked or not. There is no password.
+ *
  * The rules live here so the shell, the ribbon and the commands agree on
  * them without each reading the format entry its own way.
  */
 import type { CellAddressLookup, CellFormatEntry, Rect, SheetFormatStore } from './format-store.js';
 /** What the sheet says when a protected cell is asked to change. */
 export declare const PROTECTED_MESSAGE = "The cell you're trying to change is on a protected sheet. To make a change, unprotect the sheet.";
+/**
+ * What stays allowed on a protected sheet: Excel's Protect Sheet list, the
+ * entries the shell has something behind. An absent key is not allowed.
+ */
+export type ProtectionAllow = {
+    /** Format Cells, the Home > Font / Alignment / Number buttons, merges, Lock Cell. */
+    formatCells?: boolean;
+    /** Column width, AutoFit, hide and unhide columns, the resize handle. */
+    formatColumns?: boolean;
+    /** Row height, AutoFit, hide and unhide rows, the resize handle. */
+    formatRows?: boolean;
+    insertColumns?: boolean;
+    insertRows?: boolean;
+    deleteColumns?: boolean;
+    deleteRows?: boolean;
+    /** Sort, of a block with no locked cell: Excel refuses one with, whatever this says. */
+    sort?: boolean;
+    /** Filter on and off, and the arrows' menus. */
+    autoFilter?: boolean;
+};
+export type ProtectionPermission = keyof ProtectionAllow;
+/** The list in the order Excel's dialog shows it. */
+export declare const PROTECTION_PERMISSIONS: ReadonlyArray<ProtectionPermission>;
+/** Excel's Allow Users to Edit Ranges entry: a name over some cells. */
+export type EditRange = {
+    id: string;
+    title: string;
+    rects: Rect[];
+};
+/** What a sheet keeps beside its `protected` flag. */
+export type SheetProtection = {
+    allow: ProtectionAllow;
+    ranges: EditRange[];
+};
+export declare const defaultProtection: () => SheetProtection;
 /** A cell is locked unless its format says otherwise. */
 export declare function isLocked(entry: CellFormatEntry | undefined): boolean;
+/** Whether (r, c) lies in one of the ranges that stay editable. */
+export declare function inEditRange(ranges: ReadonlyArray<EditRange>, r: number, c: number): boolean;
+/** Whether the cell holds on a protected sheet: locked, and in no edit range. */
+export declare function cellLocked(entry: CellFormatEntry | undefined, ranges: ReadonlyArray<EditRange>, r: number, c: number): boolean;
 /**
  * Whether any cell of the rectangles is locked. A protected sheet refuses
  * a change that touches one locked cell rather than doing the rest, which
  * is what Excel does and what keeps an undo step whole.
  */
-export declare function rectsHaveLocked(store: SheetFormatStore, lookup: CellAddressLookup, rects: ReadonlyArray<Rect>): boolean;
+export declare function rectsHaveLocked(store: SheetFormatStore, lookup: CellAddressLookup, rects: ReadonlyArray<Rect>, ranges?: ReadonlyArray<EditRange>): boolean;
 /** Whether the rectangles hold both locked and unlocked cells. */
 export declare function rectsMixLocked(store: SheetFormatStore, lookup: CellAddressLookup, rects: ReadonlyArray<Rect>): boolean;
+/** A copy safe to hand out or save. */
+export declare function copyProtection(protection: SheetProtection): SheetProtection;
+/** An id no other range of this session carries. */
+export declare const newEditRangeId: () => string;
+/** `B2:B10, A1 C3:C5` as rectangles; null when any piece is not a cell or a range. */
+export declare function parseRangeText(text: string): Rect[] | null;
+/** Rectangles as `B2:B10, A1`, the way the dialog lists them. */
+export declare function rangeText(rects: ReadonlyArray<Rect>): string;

package/dist/sheet/protection.js

@@ -1,15 +1,34 @@
+import { colToLetters, parseA1 } from './address.js';
 /** What the sheet says when a protected cell is asked to change. */
 export const PROTECTED_MESSAGE = "The cell you're trying to change is on a protected sheet. To make a change, unprotect the sheet.";
+/** The list in the order Excel's dialog shows it. */
+export const PROTECTION_PERMISSIONS = [
+    'formatCells', 'formatColumns', 'formatRows', 'insertColumns', 'insertRows', 'deleteColumns', 'deleteRows', 'sort', 'autoFilter',
+];
+export const defaultProtection = () => ({ allow: {}, ranges: [] });
 /** A cell is locked unless its format says otherwise. */
 export function isLocked(entry) {
     return entry?.locked !== false;
 }
+/** Whether (r, c) lies in one of the ranges that stay editable. */
+export function inEditRange(ranges, r, c) {
+    for (const range of ranges) {
+        for (const [r1, c1, r2, c2] of range.rects)
+            if (r >= r1 && r <= r2 && c >= c1 && c <= c2)
+                return true;
+    }
+    return false;
+}
+/** Whether the cell holds on a protected sheet: locked, and in no edit range. */
+export function cellLocked(entry, ranges, r, c) {
+    return isLocked(entry) && !inEditRange(ranges, r, c);
+}
 /**
  * Whether any cell of the rectangles is locked. A protected sheet refuses
  * a change that touches one locked cell rather than doing the rest, which
  * is what Excel does and what keeps an undo step whole.
  */
-export function rectsHaveLocked(store, lookup, rects) {
+export function rectsHaveLocked(store, lookup, rects, ranges = []) {
     for (const [minRow, minCol, maxRow, maxCol] of rects) {
         for (let r = minRow; r <= maxRow; r += 1) {
             for (let c = minCol; c <= maxCol; c += 1) {
@@ -17,7 +36,7 @@ export function rectsHaveLocked(store, lookup, rects) {
                 const columnId = lookup.columnIdAt(c);
                 if (rowId == null || columnId == null)
                     continue;
-                if (isLocked(store.get(rowId, columnId)))
+                if (cellLocked(store.get(rowId, columnId), ranges, r, c))
                     return true;
             }
         }
@@ -46,3 +65,37 @@ export function rectsMixLocked(store, lookup, rects) {
     }
     return false;
 }
+/** A copy safe to hand out or save. */
+export function copyProtection(protection) {
+    return {
+        allow: { ...protection.allow },
+        ranges: protection.ranges.map((range) => ({ ...range, rects: range.rects.map(([r1, c1, r2, c2]) => [r1, c1, r2, c2]) })),
+    };
+}
+let nextRangeId = 1;
+/** An id no other range of this session carries. */
+export const newEditRangeId = () => `range-${Date.now().toString(36)}-${(nextRangeId += 1).toString(36)}`;
+/** `B2:B10, A1 C3:C5` as rectangles; null when any piece is not a cell or a range. */
+export function parseRangeText(text) {
+    const pieces = text.split(/[,\s]+/).map((p) => p.trim().replace(/^=/, '')).filter(Boolean);
+    if (!pieces.length)
+        return null;
+    const out = [];
+    for (const piece of pieces) {
+        const [first, last] = piece.split(':');
+        const a = parseA1(first ?? '');
+        const b = last === undefined ? a : parseA1(last);
+        if (!a || !b || a.row === null || b.row === null)
+            return null;
+        out.push([Math.min(a.row, b.row), Math.min(a.col, b.col), Math.max(a.row, b.row), Math.max(a.col, b.col)]);
+    }
+    return out;
+}
+/** Rectangles as `B2:B10, A1`, the way the dialog lists them. */
+export function rangeText(rects) {
+    return rects.map(([r1, c1, r2, c2]) => {
+        const a = `${colToLetters(c1)}${r1 + 1}`;
+        const b = `${colToLetters(c2)}${r2 + 1}`;
+        return a === b ? a : `${a}:${b}`;
+    }).join(', ');
+}

package/dist/sheet/rects.d.ts

@@ -40,6 +40,6 @@ export type NotesMap = Record<string, Record<string, string>>;
  * is after the edit, or null when the edit deleted it, which drops its
  * notes with it.
  */
-export declare function remapNotes(notes: NotesMap, axis: 'rows' | 'cols', shift: (index: number) => number | null): NotesMap;
+export declare function remapNotes<T = string>(notes: Record<string, Record<string, T>>, axis: 'rows' | 'cols', shift: (index: number) => number | null): Record<string, Record<string, T>>;
 /** The shift function a structural edit implies, shared by every keyed part. */
 export declare function lineShift(edit: StructuralEdit): (index: number) => number | null;

package/dist/sheet/refs.d.ts

@@ -24,6 +24,25 @@ export declare function formatFormula(node: Node): string;
  * whole column of mixed literals and formulas through it.
  */
 export declare function translateFormula(text: unknown, dRow: number, dCol: number): unknown;
+/**
+ * A formula for a cell that a transposed paste moves from `source` to
+ * `dest`, its relative references turned with it.
+ *
+ * Excel rotates a relative offset on a transpose: a reference `dr` rows
+ * and `dc` columns away becomes `dc` rows and `dr` columns away. A cell
+ * inside the block moved the same way, so a formula that read the price
+ * beside it still reads that price, now above it, which is what makes a
+ * transposed totals column still total. A reference outside the block is
+ * turned too, as Excel turns it. Absolute parts stay where they point.
+ * A column-only reference has no row to turn and is left as it is.
+ */
+export declare function transposeFormula(text: unknown, source: {
+    row: number;
+    col: number;
+}, dest: {
+    row: number;
+    col: number;
+}): unknown;
 /**
  * Point every reference that names sheet `from` at `to` instead: what a
  * sheet rename owes the formulas on the other sheets and the defined
@@ -32,6 +51,35 @@ export declare function translateFormula(text: unknown, dRow: number, dCol: numb
  * name is left alone and a new name with a space comes out quoted. A
  * formula that names no such sheet is returned as it was, untouched.
  */
+/**
+ * A block of cells that has MOVED: cut and pasted somewhere else, or dragged
+ * there. `sheet` is where it was, `toSheet` where it landed, and the rect is
+ * the block's old position, zero-based and inclusive.
+ */
+export type CellMove = {
+    sheet: string;
+    toSheet: string;
+    top: number;
+    left: number;
+    bottom: number;
+    right: number;
+    dRow: number;
+    dCol: number;
+};
+/**
+ * Point every reference to a moved cell at where the cell now is.
+ *
+ * This is what a cut and paste owes the rest of the workbook, and Excel does
+ * it: moving A1 to D1 rewrites `=A1*2` as `=D1*2` rather than leaving it
+ * reading an emptied cell. A `$` makes no difference - the cell moved, so
+ * every way of naming it moves - and a RANGE only follows when the whole of
+ * it moved, which is why `=SUM(A1:A2)` stays as it is when only A1 goes.
+ *
+ * `self` is the sheet the formula lives on, so an unqualified reference is
+ * read against the right geometry; a reference that lands on another sheet
+ * takes that sheet's name, as Excel writes it.
+ */
+export declare function repointReferences(text: unknown, move: CellMove, self: string | null): unknown;
 /**
  * Excel's reference colours: the A1 references in a formula being typed,
  * each occurrence with the colour of its range, so the cells a formula