@svgrid/enterprise 3.0.1 → 3.0.3

package/dist/sheet/xlsx-drawing.d.ts

@@ -0,0 +1,99 @@
+import type { CellValue } from './ast.js';
+import type { SheetChartObject, SheetObject } from './objects.js';
+import type { Rect } from './format-store.js';
+export declare const REL_DRAWING = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing";
+export declare const REL_IMAGE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
+export declare const REL_CHART = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart";
+/** Excel measures a drawing in English Metric Units: 9525 to the pixel. */
+export declare const EMU_PER_PX = 9525;
+/**
+ * Whether a picture's source is one the .xlsx can carry: a `data:` URL of a
+ * type Excel keeps in `xl/media`. An SVG is not one (Excel wants a PNG blip
+ * with the SVG as an extension), nor is a web address, whose bytes are
+ * elsewhere. The shell asks before it inserts a picture, so what it draws
+ * is what the file will hold.
+ */
+export declare function xlsxCanCarryPicture(src: string): boolean;
+/** A data URL split into its media type and its payload, or null. */
+export declare function dataUrlParts(src: string): {
+    mime: string;
+    base64: string;
+} | null;
+export type DrawingParts = {
+    /** `xl/drawings/drawing<n>.xml`, or null when the sheet has nothing to draw. */
+    drawingPath: string | null;
+    drawingXml: string;
+    drawingRels: string;
+    /** Extra parts, keyed by their path: the chart definitions and the media. */
+    parts: Record<string, string>;
+    /** Content-type overrides these parts need. */
+    overrides: string[];
+    /** Default extensions the package must declare for the media written. */
+    extensions: string[];
+    /** Objects that could not be written, for a caller that wants to say so. */
+    skipped: SheetObject[];
+};
+export type DrawingContext = {
+    /** The sheet the objects sit on, for a chart's references. */
+    sheet: string;
+    /** 1-based index of this drawing part in the package. */
+    index: number;
+    /** The number of chart parts already written, so the next one is unique. */
+    chartsSoFar: number;
+    /** The number of media parts already written. */
+    mediaSoFar: number;
+    valueAt(row: number, col: number): CellValue;
+    textAt(row: number, col: number): string;
+};
+/**
+ * The drawing part for one sheet's objects, with the charts and the media
+ * they need.
+ *
+ * A picture whose source is not a `data:` URL is skipped rather than
+ * guessed at: its bytes are somewhere else, and a spreadsheet that opens
+ * with a broken image in it is worse than one that opens without the
+ * image.
+ */
+export declare function drawingPartsFor(objects: ReadonlyArray<SheetObject>, context: DrawingContext): DrawingParts;
+/** The lines the chart reads, worked out the way `chartSpecOf` works them
+ *  out, so the file and the screen show the same chart. */
+export declare function chartRefs(object: SheetChartObject, sheet: string): {
+    categories: string;
+    series: Array<{
+        name: string;
+        values: string;
+    }>;
+};
+/** A reference like `Sales!$B$2:$B$7`, as a rectangle on its sheet. */
+export declare function rectOfRef(text: string): {
+    sheet: string | null;
+    rect: Rect;
+} | null;
+export type DrawingReadContext = {
+    /** Parse a part, the way the reader parses every other one. */
+    parse(xml: string, what: string): Document;
+    /** The drawing part's own relationships, by id. */
+    rels: Map<string, {
+        target: string;
+        type: string;
+    }>;
+    /** Every part in the package. Media entries are data URLs by the time
+     *  they reach here, which is what an image object holds anyway. */
+    parts: Record<string, string>;
+    /** A fresh object id. */
+    newId(): string;
+    /** Column width and row height in pixels, for the one case that needs
+     *  them: a two-cell anchor, whose size is a pair of cells rather than a
+     *  measurement. Defaults to Excel's own defaults. */
+    columnWidth?(col: number): number;
+    rowHeight?(row: number): number;
+};
+/**
+ * The objects a drawing part holds.
+ *
+ * A one-cell anchor gives its size outright. A two-cell anchor, which is
+ * what most other producers write, gives a second cell instead, so the size
+ * is measured across the cells between them: approximate where the columns
+ * are not the default width, and better than dropping the picture.
+ */
+export declare function objectsFromDrawing(drawingXml: string, context: DrawingReadContext): SheetObject[];

package/dist/sheet/xlsx-drawing.js

@@ -0,0 +1,420 @@
+/**
+ * The drawing part: the objects on a sheet, written into the .xlsx and read
+ * back out of one.
+ *
+ * Until now a chart or a picture lived in the document and nowhere else, so
+ * Save As wrote the cells and left the objects behind. Excel keeps them in
+ * a separate part per sheet (`xl/drawings/drawing1.xml`), each anchored to a
+ * cell, with a picture's bytes in `xl/media` and a chart's definition in its
+ * own part. This builds those, and reads them.
+ *
+ * Two deliberate simplifications, both visible to the reader:
+ *
+ * - Every object is a ONE-cell anchor: the cell it hangs from plus a size in
+ *   English Metric Units. That is exactly what the model holds ("move but
+ *   don't size with cells"), so nothing is invented on the way out and
+ *   nothing is lost on the way back.
+ * - A chart part carries the REFERENCES its series read, not a cached copy
+ *   of the numbers. Excel recalculates a chart from its references on open,
+ *   so a file written here redraws from the cells beside it rather than from
+ *   a snapshot that can disagree with them.
+ */
+import { colToLetters } from './address.js';
+const NS_XDR = 'http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing';
+const NS_A = 'http://schemas.openxmlformats.org/drawingml/2006/main';
+const NS_C = 'http://schemas.openxmlformats.org/drawingml/2006/chart';
+const NS_R = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+export const REL_DRAWING = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing';
+export const REL_IMAGE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image';
+export const REL_CHART = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart';
+/** Excel measures a drawing in English Metric Units: 9525 to the pixel. */
+export const EMU_PER_PX = 9525;
+const emu = (px) => Math.round(px * EMU_PER_PX);
+const px = (value) => Math.round(value / EMU_PER_PX);
+const esc = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** An absolute reference the way a chart part spells one. */
+function ref(sheet, r1, c1, r2 = r1, c2 = c1) {
+    const name = /^[A-Za-z_][A-Za-z0-9_.]*$/.test(sheet) ? sheet : `'${sheet.replace(/'/g, "''")}'`;
+    const from = `$${colToLetters(c1)}$${r1 + 1}`;
+    const to = `$${colToLetters(c2)}$${r2 + 1}`;
+    return `${name}!${from === to ? from : `${from}:${to}`}`;
+}
+/** The image types Excel writes, by the extension the media part takes. */
+const IMAGE_TYPES = {
+    'image/png': 'png',
+    'image/jpeg': 'jpeg',
+    'image/jpg': 'jpeg',
+    'image/gif': 'gif',
+    'image/webp': 'png',
+    'image/bmp': 'bmp',
+};
+/**
+ * Whether a picture's source is one the .xlsx can carry: a `data:` URL of a
+ * type Excel keeps in `xl/media`. An SVG is not one (Excel wants a PNG blip
+ * with the SVG as an extension), nor is a web address, whose bytes are
+ * elsewhere. The shell asks before it inserts a picture, so what it draws
+ * is what the file will hold.
+ */
+export function xlsxCanCarryPicture(src) {
+    const data = dataUrlParts(src);
+    return !!data && data.mime in IMAGE_TYPES;
+}
+/** A data URL split into its media type and its payload, or null. */
+export function dataUrlParts(src) {
+    const match = /^data:([^;,]+)(;base64)?,(.*)$/s.exec(src.trim());
+    if (!match)
+        return null;
+    const mime = match[1].toLowerCase();
+    // A data URL without `;base64` is percent-encoded text, which is not a
+    // picture worth writing into a spreadsheet.
+    if (!match[2])
+        return null;
+    return { mime, base64: match[3] };
+}
+/**
+ * The drawing part for one sheet's objects, with the charts and the media
+ * they need.
+ *
+ * A picture whose source is not a `data:` URL is skipped rather than
+ * guessed at: its bytes are somewhere else, and a spreadsheet that opens
+ * with a broken image in it is worse than one that opens without the
+ * image.
+ */
+export function drawingPartsFor(objects, context) {
+    const empty = {
+        drawingPath: null, drawingXml: '', drawingRels: '', parts: {}, overrides: [], extensions: [], skipped: [],
+    };
+    if (objects.length === 0)
+        return empty;
+    const anchors = [];
+    const rels = [];
+    const parts = {};
+    const overrides = [];
+    const extensions = new Set();
+    const skipped = [];
+    let charts = context.chartsSoFar;
+    let media = context.mediaSoFar;
+    let shape = 1;
+    for (const object of objects) {
+        shape += 1;
+        const rel = `rId${rels.length + 1}`;
+        if (object.kind === 'image') {
+            const data = dataUrlParts(object.src);
+            const extension = data ? IMAGE_TYPES[data.mime] : undefined;
+            if (!data || !extension) {
+                skipped.push(object);
+                continue;
+            }
+            media += 1;
+            const path = `xl/media/image${media}.${extension}`;
+            // Media rides in the parts map as the data URL it came from; the zip
+            // writer is what turns it back into bytes, so everything here stays
+            // text and stays testable.
+            parts[path] = `data:${data.mime};base64,${data.base64}`;
+            extensions.add(extension);
+            rels.push(`<Relationship Id="${rel}" Type="${REL_IMAGE}" Target="../media/image${media}.${extension}"/>`);
+            anchors.push(pictureAnchor(object, rel, shape));
+            continue;
+        }
+        charts += 1;
+        const path = `xl/charts/chart${charts}.xml`;
+        parts[path] = chartPart(object, context);
+        overrides.push(`<Override PartName="/${path}" ContentType="application/vnd.openxmlformats-officedocument.drawingml.chart+xml"/>`);
+        rels.push(`<Relationship Id="${rel}" Type="${REL_CHART}" Target="../charts/chart${charts}.xml"/>`);
+        anchors.push(chartAnchor(object, rel, shape));
+    }
+    if (anchors.length === 0)
+        return { ...empty, skipped };
+    const drawingPath = `xl/drawings/drawing${context.index}.xml`;
+    overrides.push(`<Override PartName="/${drawingPath}" ContentType="application/vnd.openxmlformats-officedocument.drawing+xml"/>`);
+    return {
+        drawingPath,
+        drawingXml: `<xdr:wsDr xmlns:xdr="${NS_XDR}" xmlns:a="${NS_A}">${anchors.join('')}</xdr:wsDr>`,
+        drawingRels: `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">${rels.join('')}</Relationships>`,
+        parts,
+        overrides,
+        extensions: [...extensions],
+        skipped,
+    };
+}
+function anchorFrom(object) {
+    const { row, col, dx, dy, width, height } = object.anchor;
+    return `<xdr:from><xdr:col>${col}</xdr:col><xdr:colOff>${emu(dx)}</xdr:colOff>`
+        + `<xdr:row>${row}</xdr:row><xdr:rowOff>${emu(dy)}</xdr:rowOff></xdr:from>`
+        + `<xdr:ext cx="${emu(width)}" cy="${emu(height)}"/>`;
+}
+function pictureAnchor(object, rel, shape) {
+    const { width, height } = object.anchor;
+    return '<xdr:oneCellAnchor>'
+        + anchorFrom(object)
+        + '<xdr:pic>'
+        + `<xdr:nvPicPr><xdr:cNvPr id="${shape}" name="Picture ${shape}"${object.alt ? ` descr="${esc(object.alt)}"` : ''}/><xdr:cNvPicPr/></xdr:nvPicPr>`
+        + `<xdr:blipFill><a:blip xmlns:r="${NS_R}" r:embed="${rel}"/><a:stretch><a:fillRect/></a:stretch></xdr:blipFill>`
+        + `<xdr:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${emu(width)}" cy="${emu(height)}"/></a:xfrm>`
+        + '<a:prstGeom prst="rect"><a:avLst/></a:prstGeom></xdr:spPr>'
+        + '</xdr:pic><xdr:clientData/></xdr:oneCellAnchor>';
+}
+function chartAnchor(object, rel, shape) {
+    const { width, height } = object.anchor;
+    return '<xdr:oneCellAnchor>'
+        + anchorFrom(object)
+        + '<xdr:graphicFrame macro="">'
+        + `<xdr:nvGraphicFramePr><xdr:cNvPr id="${shape}" name="Chart ${shape}"/><xdr:cNvGraphicFramePr/></xdr:nvGraphicFramePr>`
+        + `<xdr:xfrm><a:off x="0" y="0"/><a:ext cx="${emu(width)}" cy="${emu(height)}"/></xdr:xfrm>`
+        + `<a:graphic><a:graphicData uri="${NS_C}"><c:chart xmlns:c="${NS_C}" xmlns:r="${NS_R}" r:id="${rel}"/></a:graphicData></a:graphic>`
+        + '</xdr:graphicFrame><xdr:clientData/></xdr:oneCellAnchor>';
+}
+/** The lines the chart reads, worked out the way `chartSpecOf` works them
+ *  out, so the file and the screen show the same chart. */
+export function chartRefs(object, sheet) {
+    const [r1, c1, r2, c2] = object.range;
+    const byColumns = object.series === 'columns';
+    const seriesFrom = byColumns ? c1 : r1;
+    const seriesTo = byColumns ? c2 : r2;
+    const pointFrom = byColumns ? r1 : c1;
+    const pointTo = byColumns ? r2 : c2;
+    const firstSeries = object.headers ? seriesFrom + 1 : seriesFrom;
+    const firstPoint = object.headers ? pointFrom + 1 : pointFrom;
+    const cell = (s, p) => (byColumns ? { row: p, col: s } : { row: s, col: p });
+    const catFrom = cell(seriesFrom, firstPoint);
+    const catTo = cell(seriesFrom, pointTo);
+    const categories = object.headers ? ref(sheet, catFrom.row, catFrom.col, catTo.row, catTo.col) : '';
+    const series = [];
+    for (let s = firstSeries; s <= seriesTo; s += 1) {
+        const head = cell(s, pointFrom);
+        const from = cell(s, firstPoint);
+        const to = cell(s, pointTo);
+        series.push({
+            name: object.headers ? ref(sheet, head.row, head.col) : '',
+            values: ref(sheet, from.row, from.col, to.row, to.col),
+        });
+    }
+    return { categories, series };
+}
+/** One chart part. */
+function chartPart(object, context) {
+    const { categories, series } = chartRefs(object, context.sheet);
+    const grouping = object.stacked ? 'stacked' : object.type === 'bar' ? 'clustered' : 'standard';
+    const body = series.map((s, i) => {
+        const name = s.name ? `<c:tx><c:strRef><c:f>${esc(s.name)}</c:f></c:strRef></c:tx>` : '';
+        const cat = categories ? `<c:cat><c:strRef><c:f>${esc(categories)}</c:f></c:strRef></c:cat>` : '';
+        // Excel's own trendline element, so the line drawn here is a trendline
+        // there rather than a second series of numbers.
+        //
+        // Its place in the series matters: the schema orders a series
+        // idx, order, tx, ..., trendline, errBars, cat, val, and Excel reports a
+        // file whose elements are out of that order as one needing repair.
+        const trend = object.trend
+            ? `<c:trendline><c:trendlineType val="${object.trend === 'sma3' ? 'movingAvg' : 'linear'}"/>${object.trend === 'sma3' ? '<c:period val="3"/>' : ''}</c:trendline>`
+            : '';
+        if (object.type === 'scatter') {
+            return `<c:ser><c:idx val="${i}"/><c:order val="${i}"/>${name}${trend}`
+                + (categories ? `<c:xVal><c:numRef><c:f>${esc(categories)}</c:f></c:numRef></c:xVal>` : '')
+                + `<c:yVal><c:numRef><c:f>${esc(s.values)}</c:f></c:numRef></c:yVal></c:ser>`;
+        }
+        return `<c:ser><c:idx val="${i}"/><c:order val="${i}"/>${name}${trend}${cat}`
+            + `<c:val><c:numRef><c:f>${esc(s.values)}</c:f></c:numRef></c:val></c:ser>`;
+    }).join('');
+    const plot = object.type === 'pie'
+        ? `<c:pieChart><c:varyColors val="1"/>${body}</c:pieChart>`
+        : object.type === 'line'
+            ? `<c:lineChart><c:grouping val="${object.stacked ? 'stacked' : 'standard'}"/><c:marker val="1"/>${body}<c:axId val="1"/><c:axId val="2"/></c:lineChart>`
+            : object.type === 'area'
+                ? `<c:areaChart><c:grouping val="${object.stacked ? 'stacked' : 'standard'}"/>${body}<c:axId val="1"/><c:axId val="2"/></c:areaChart>`
+                : object.type === 'scatter'
+                    ? `<c:scatterChart><c:scatterStyle val="lineMarker"/>${body}<c:axId val="1"/><c:axId val="2"/></c:scatterChart>`
+                    : `<c:barChart><c:barDir val="col"/><c:grouping val="${grouping}"/>${object.stacked ? '<c:overlap val="100"/>' : ''}${body}<c:axId val="1"/><c:axId val="2"/></c:barChart>`;
+    const axes = object.type === 'pie'
+        ? ''
+        : `<c:${object.type === 'scatter' ? 'valAx' : 'catAx'}><c:axId val="1"/><c:scaling><c:orientation val="minMax"/></c:scaling><c:delete val="0"/><c:axPos val="b"/><c:crossAx val="2"/></c:${object.type === 'scatter' ? 'valAx' : 'catAx'}>`
+            + '<c:valAx><c:axId val="2"/><c:scaling><c:orientation val="minMax"/></c:scaling><c:delete val="0"/><c:axPos val="l"/><c:crossAx val="1"/></c:valAx>';
+    const title = object.title
+        ? `<c:title><c:tx><c:rich><a:bodyPr/><a:p><a:r><a:t>${esc(object.title)}</a:t></a:r></a:p></c:rich></c:tx><c:overlay val="0"/></c:title><c:autoTitleDeleted val="0"/>`
+        : '<c:autoTitleDeleted val="1"/>';
+    return `<c:chartSpace xmlns:c="${NS_C}" xmlns:a="${NS_A}" xmlns:r="${NS_R}">`
+        + `<c:chart>${title}<c:plotArea><c:layout/>${plot}${axes}</c:plotArea>`
+        + '<c:plotVisOnly val="1"/><c:dispBlanksAs val="gap"/></c:chart></c:chartSpace>';
+}
+// ---------------------------------------------------------------------------
+// Reading one back
+// ---------------------------------------------------------------------------
+/** The elements of one namespace, by local name, in document order. */
+function tags(root, ns, local) {
+    return [...root.getElementsByTagNameNS(ns, local)];
+}
+function first(root, ns, local) {
+    return root.getElementsByTagNameNS(ns, local)[0] ?? null;
+}
+function numberIn(root, ns, local) {
+    const el = root ? first(root, ns, local) : null;
+    const value = Number(el?.textContent ?? '');
+    return Number.isFinite(value) ? value : 0;
+}
+/** A reference like `Sales!$B$2:$B$7`, as a rectangle on its sheet. */
+export function rectOfRef(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    const bang = trimmed.lastIndexOf('!');
+    const sheetPart = bang >= 0 ? trimmed.slice(0, bang) : '';
+    const cells = bang >= 0 ? trimmed.slice(bang + 1) : trimmed;
+    const sheet = sheetPart.startsWith("'") && sheetPart.endsWith("'")
+        ? sheetPart.slice(1, -1).replace(/''/g, "'")
+        : sheetPart || null;
+    const ends = cells.split(':').map((part) => /^\$?([A-Za-z]+)\$?(\d+)$/.exec(part.trim()));
+    if (!ends[0])
+        return null;
+    const at = (m) => ({
+        col: m[1].toUpperCase().split('').reduce((n, ch) => n * 26 + (ch.charCodeAt(0) - 64), 0) - 1,
+        row: Number(m[2]) - 1,
+    });
+    const from = at(ends[0]);
+    const to = ends[1] ? at(ends[1]) : from;
+    return {
+        sheet,
+        rect: [
+            Math.min(from.row, to.row), Math.min(from.col, to.col),
+            Math.max(from.row, to.row), Math.max(from.col, to.col),
+        ],
+    };
+}
+/**
+ * The objects a drawing part holds.
+ *
+ * A one-cell anchor gives its size outright. A two-cell anchor, which is
+ * what most other producers write, gives a second cell instead, so the size
+ * is measured across the cells between them: approximate where the columns
+ * are not the default width, and better than dropping the picture.
+ */
+export function objectsFromDrawing(drawingXml, context) {
+    const root = context.parse(drawingXml, 'drawing').documentElement;
+    const out = [];
+    const anchors = [...tags(root, NS_XDR, 'oneCellAnchor'), ...tags(root, NS_XDR, 'twoCellAnchor')];
+    for (const anchor of anchors) {
+        const from = first(anchor, NS_XDR, 'from');
+        if (!from)
+            continue;
+        const col = numberIn(from, NS_XDR, 'col');
+        const row = numberIn(from, NS_XDR, 'row');
+        const dx = px(numberIn(from, NS_XDR, 'colOff'));
+        const dy = px(numberIn(from, NS_XDR, 'rowOff'));
+        const ext = first(anchor, NS_XDR, 'ext');
+        let width = ext ? px(Number(ext.getAttribute('cx') ?? 0)) : 0;
+        let height = ext ? px(Number(ext.getAttribute('cy') ?? 0)) : 0;
+        if (!width || !height) {
+            const to = first(anchor, NS_XDR, 'to');
+            const toCol = to ? numberIn(to, NS_XDR, 'col') : col + 4;
+            const toRow = to ? numberIn(to, NS_XDR, 'row') : row + 8;
+            const widthOf = context.columnWidth ?? (() => 64);
+            const heightOf = context.rowHeight ?? (() => 20);
+            width = 0;
+            height = 0;
+            for (let c = col; c < toCol; c += 1)
+                width += widthOf(c);
+            for (let r = row; r < toRow; r += 1)
+                height += heightOf(r);
+            width = Math.max(width - dx + (to ? px(numberIn(to, NS_XDR, 'colOff')) : 0), 24);
+            height = Math.max(height - dy + (to ? px(numberIn(to, NS_XDR, 'rowOff')) : 0), 24);
+        }
+        const at = { row, col, dx, dy, width, height };
+        const pic = first(anchor, NS_XDR, 'pic');
+        if (pic) {
+            const blip = first(pic, NS_A, 'blip');
+            const id = blip?.getAttributeNS(NS_R, 'embed') ?? blip?.getAttribute('r:embed');
+            const target = id ? context.rels.get(id)?.target : undefined;
+            const src = target ? context.parts[target] : undefined;
+            // Only a picture whose bytes are in the package comes back; one that
+            // points outside it would be a broken image on the sheet.
+            if (!src || !src.startsWith('data:'))
+                continue;
+            const name = first(pic, NS_XDR, 'cNvPr');
+            const alt = name?.getAttribute('descr') ?? undefined;
+            out.push({ id: context.newId(), kind: 'image', anchor: at, src, ...(alt ? { alt } : {}) });
+            continue;
+        }
+        const frame = first(anchor, NS_XDR, 'graphicFrame');
+        if (!frame)
+            continue;
+        const chartEl = first(frame, NS_C, 'chart');
+        const chartId = chartEl?.getAttributeNS(NS_R, 'id') ?? chartEl?.getAttribute('r:id');
+        const chartPath = chartId ? context.rels.get(chartId)?.target : undefined;
+        const chartXml = chartPath ? context.parts[chartPath] : undefined;
+        if (!chartXml)
+            continue;
+        const chart = chartFromPart(chartXml, at, context);
+        if (chart)
+            out.push(chart);
+    }
+    return out;
+}
+/** The chart kind a chart part describes, and the block its series read. */
+function chartFromPart(xml, anchor, context) {
+    const root = context.parse(xml, 'chart').documentElement;
+    const kinds = [
+        ['barChart', 'bar'], ['lineChart', 'line'], ['areaChart', 'area'],
+        ['pieChart', 'pie'], ['scatterChart', 'scatter'],
+    ];
+    const found = kinds.find(([tag]) => first(root, NS_C, tag) !== null);
+    if (!found)
+        return null;
+    const [tag, type] = found;
+    const plot = first(root, NS_C, tag);
+    // The block the chart reads is the union of every reference in it: the
+    // categories, the series names and the values. That is how a chart
+    // written by anything else comes back as a range rather than as a copy.
+    let sheet = null;
+    let rect = null;
+    let headers = false;
+    for (const f of tags(plot, NS_C, 'f')) {
+        const parsed = rectOfRef(f.textContent ?? '');
+        if (!parsed)
+            continue;
+        sheet = sheet ?? parsed.sheet;
+        const inside = f.parentElement?.parentElement?.localName;
+        if (inside === 'tx' || inside === 'cat' || inside === 'xVal')
+            headers = true;
+        rect = rect ? union(rect, parsed.rect) : parsed.rect;
+    }
+    if (!rect)
+        return null;
+    const series = orientationOf(plot, rect);
+    const title = first(root, NS_C, 'title');
+    const titleText = title ? [...tags(title, NS_A, 't')].map((t) => t.textContent ?? '').join('').trim() : '';
+    const grouping = first(plot, NS_C, 'grouping')?.getAttribute('val');
+    const trendKind = first(plot, NS_C, 'trendlineType')?.getAttribute('val');
+    return {
+        id: context.newId(),
+        kind: 'chart',
+        anchor,
+        range: rect,
+        type,
+        headers,
+        series,
+        ...(titleText ? { title: titleText } : {}),
+        ...(grouping === 'stacked' || grouping === 'percentStacked' ? { stacked: true } : {}),
+        ...(trendKind === 'linear' ? { trend: 'linear' } : trendKind === 'movingAvg' ? { trend: 'sma3' } : {}),
+    };
+}
+function union(a, b) {
+    return [
+        Math.min(a[0], b[0]), Math.min(a[1], b[1]),
+        Math.max(a[2], b[2]), Math.max(a[3], b[3]),
+    ];
+}
+/**
+ * Whether each series is a column of the block or a row of it, read off the
+ * first series' own reference: a reference down one column is a column.
+ */
+function orientationOf(plot, rect) {
+    const values = first(plot, NS_C, 'val') ?? first(plot, NS_C, 'yVal');
+    const f = values ? first(values, NS_C, 'f') : null;
+    const parsed = f ? rectOfRef(f.textContent ?? '') : null;
+    if (!parsed)
+        return 'columns';
+    const [r1, c1, r2, c2] = parsed.rect;
+    if (r1 !== r2 && c1 === c2)
+        return 'columns';
+    if (c1 !== c2 && r1 === r2)
+        return 'rows';
+    return rect[2] - rect[0] >= rect[3] - rect[1] ? 'columns' : 'rows';
+}

package/dist/sheet-enable.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Register the Excel keymap. Idempotent - safe to call from every component
+ * that wants it, or once at app start. Also invoked by {@link installEnterprise}
+ * so wiring the Pro API turns the shortcuts on too.
+ */
+export declare function enableSheet(): void;

package/dist/sheet-enable.js

@@ -0,0 +1,45 @@
+/**
+ * Excel keyboard commands (Pro). `enableSheet()` registers the sheet keymap
+ * with the grid, so Ctrl+Arrow jumps to the edge of a data region, Ctrl+D and
+ * Ctrl+R fill, Ctrl+A selects the current region, and the rest of the Excel
+ * muscle memory works on any `<SvGrid>` with cell selection on.
+ *
+ * The grid ships the `registerGridShortcuts` seam for free and interprets a key
+ * itself only when nothing claims it; the commands are here. Evaluated like
+ * the rest of Enterprise, and part of the Suite edition: it works without a
+ * license key, and under a Grid-edition key, but the grid shows the unlicensed
+ * watermark and a one-time console nudge in both cases.
+ *
+ * ```ts
+ * import { setLicenseKey, enableSheet } from '@svgrid/enterprise'
+ * setLicenseKey('YOUR-KEY')
+ * enableSheet()
+ * // then: <SvGrid {data} {columns} enableCellSelection />
+ * ```
+ */
+// The Svelte-free subpath: importing the barrel would drag SvGrid.svelte into
+// this module's chunk, and into any unit test that touches it.
+import { registerGridShortcuts } from '@svgrid/grid/shortcuts';
+import { nudgeEnterpriseFor } from './license.js';
+import { handleSheetKey } from './sheet/shortcuts.js';
+import { setFillTranslator } from './sheet/commands.js';
+import { translateFormula } from './sheet/refs.js';
+let enabled = false;
+/**
+ * Register the Excel keymap. Idempotent - safe to call from every component
+ * that wants it, or once at app start. Also invoked by {@link installEnterprise}
+ * so wiring the Pro API turns the shortcuts on too.
+ */
+export function enableSheet() {
+    if (enabled)
+        return;
+    enabled = true;
+    // Priority 100 so the sheet keymap sits above anything an app registers of
+    // its own without asking for a priority.
+    registerGridShortcuts(handleSheetKey, { id: 'svgrid-sheet', priority: 100 });
+    // Teach fill about formulas. Without this Ctrl+D copies '=A1*2' down as
+    // literal text into every row; with it the relative half of each reference
+    // shifts and the absolute half does not, the way Excel fills.
+    setFillTranslator((value, delta) => translateFormula(value, delta.rows, delta.cols));
+    nudgeEnterpriseFor('spreadsheet', 'Spreadsheet');
+}

package/dist/sheet-text.d.ts

@@ -0,0 +1,7 @@
+import { type SheetMessages } from './sheet/messages.js';
+/** A string by key, with its `{placeholders}` filled. */
+export type SheetText = (key: string, vars?: Record<string, string | number>) => string;
+/** Called by the shell: `get` reads its resolved map, so a change to the
+ *  `localization` prop reaches every reader. */
+export declare function provideSheetText(get: () => SheetMessages): void;
+export declare function useSheetText(): SheetText;

package/dist/sheet-text.js

@@ -0,0 +1,29 @@
+/**
+ * How the shell's strings reach every part of it. `SvSheet` provides the
+ * resolved map through Svelte context once; the ribbon, the tab strip, the
+ * formula bar and each dialog ask for `t` and read their strings through
+ * it. A part mounted on its own, outside a shell, gets the English
+ * defaults, so nothing needs a prop it did not have before.
+ */
+import { getContext, setContext } from 'svelte';
+import { defaultSheetMessages, formatMessage } from './sheet/messages.js';
+const KEY = Symbol.for('sv-sheet-text');
+/** Called by the shell: `get` reads its resolved map, so a change to the
+ *  `localization` prop reaches every reader. */
+export function provideSheetText(get) {
+    setContext(KEY, get);
+}
+export function useSheetText() {
+    let get;
+    try {
+        get = getContext(KEY);
+    }
+    catch {
+        get = undefined;
+    }
+    return (key, vars) => {
+        const map = get ? get() : defaultSheetMessages;
+        const text = map[key] ?? defaultSheetMessages[key] ?? key;
+        return formatMessage(text, vars);
+    };
+}

package/dist/sources/auth-supabase.js

@@ -9,10 +9,10 @@
  *     await auth.signIn(email, password)
  *     // ... auth.signOut(); auth.dispose() on unmount
  */
-import { nudgeEnterprise } from '../license.js';
+import { nudgeEnterpriseFor } from '../license.js';
 const userOf = (session) => session?.user ? { id: session.user.id, email: session.user.email } : null;
 export function createSupabaseAuth(config) {
-    nudgeEnterprise('Studio'); // soft-gate; never blocks
+    nudgeEnterpriseFor('studio', 'Studio'); // evaluation nudge; never blocks
     let state = { user: null, loading: true, error: null };
     const emit = () => config.onChange({ ...state });
     const set = (patch) => {

package/dist/sources/realtime-supabase.js

@@ -17,9 +17,9 @@
  * coalesce bursts into a single refetch. For per-row effects (e.g. flashing a
  * changed row) read the normalized event passed to `onChange`.
  */
-import { nudgeEnterprise } from '../license.js';
+import { nudgeEnterpriseFor } from '../license.js';
 export function createSupabaseRealtime(config) {
-    nudgeEnterprise('Studio'); // soft-gate; never blocks
+    nudgeEnterpriseFor('studio', 'Studio'); // evaluation nudge; never blocks
     const schema = config.schema ?? 'public';
     const channelName = config.channelName ?? `svgrid:${schema}:${config.table}`;
     let timer;

package/dist/sources/rest.d.ts

@@ -32,7 +32,11 @@ export type RestDataSourceConfig<TData extends RowData> = {
     query?: Record<string, string>;
     /** Build read query params from the grid request. Override for bespoke APIs. */
     buildQuery?: (request: ServerRequest) => Record<string, string>;
-    /** Parse a read response body into rows + total. Override for bespoke shapes. */
-    parse?: (body: unknown, response: Response) => ServerResult<TData>;
+    /**
+     * Parse a read response body into rows + total. Override for bespoke
+     * shapes. Receives the request too, so a parser can tell a short last
+     * block from a full one when the API sends no total.
+     */
+    parse?: (body: unknown, response: Response, request: ServerRequest) => ServerResult<TData>;
 };
 export declare function createRestDataSource<TData extends RowData>(config: RestDataSourceConfig<TData>): WritableDataSource<TData>;