@svgrid/grid 1.2.21 → 1.2.23

package/dist/editing.js

@@ -299,6 +299,13 @@ export function createEditing(ctx) {
      * (no preventDefault) whenever the async API is unavailable.
      */
     function onGridPaste(event) {
+        // A cell is being edited: the focused editor input handles its own paste
+        // natively. Never hijack it for a range paste - doing so (on Firefox /
+        // insecure contexts, where the async Clipboard API is unavailable) would
+        // preventDefault the editor's paste and write to the data cell instead,
+        // so the edit "wouldn't update".
+        if (ctx.editingCell)
+            return;
         // When the async API is available the keydown handler already pasted via
         // pasteFromClipboard(); ignore the (suppressed) native event so we don't
         // paste twice.

package/dist/editors/cell-editors.d.ts

@@ -1,4 +1,4 @@
-export type CellEditorType = 'text' | 'number' | 'date' | 'datetime' | 'time' | 'password' | 'checkbox' | 'list' | 'chips' | 'select' | 'rich-select' | 'autocomplete' | 'textarea' | 'color' | 'rating';
+export type CellEditorType = 'text' | 'number' | 'date' | 'datetime' | 'time' | 'date-native' | 'datetime-native' | 'time-native' | 'password' | 'checkbox' | 'list' | 'chips' | 'select' | 'rich-select' | 'autocomplete' | 'textarea' | 'color' | 'rating';
 /** Normalized option used by list/chips editors. The optional `color`
  *  paints the chip - both in the in-cell readonly chips render and in
  *  the dropdown trigger when `renderChipsInTrigger` is on. Any CSS
@@ -20,4 +20,4 @@ export declare function normalizeEditorOptions(options: ReadonlyArray<string | n
     label?: string;
     color?: string;
 }> | undefined): CellEditorOption[];
-export declare function parseEditorValue(type: CellEditorType, value: unknown, opts?: ParseEditorValueOptions): any;
+export declare function parseEditorValue(rawType: CellEditorType, value: unknown, opts?: ParseEditorValueOptions): any;

package/dist/editors/cell-editors.js

@@ -14,7 +14,9 @@ export function normalizeEditorOptions(options) {
         };
     });
 }
-export function parseEditorValue(type, value, opts) {
+export function parseEditorValue(rawType, value, opts) {
+    // `date-native` etc. parse identically to their rich counterparts.
+    const type = rawType.replace(/-native$/, '');
     if (type === 'number') {
         const parsed = Number(value);
         return Number.isFinite(parsed) ? parsed : null;

package/dist/export-format.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Pure, render-free value formatting for data export. The grid's on-screen
+ * `formatCellValue` (see cell-render.ts) is a closure bound to a `Row<TData>`
+ * and the live table, so it can't be reused directly by an exporter that only
+ * has raw values + a column's `format` config. These helpers replicate the
+ * numeric / date / percent branches of that formatter as standalone functions:
+ *
+ *   - `formatValueForExport(value, format)` returns the display STRING a user
+ *     sees on screen, so CSV / TSV / HTML / PDF exports are faithful to the
+ *     grid ("what you see is what you export") instead of dumping raw values.
+ *   - `toExcelNumFmt(format)` maps a `CellFormatConfig` to an Excel number
+ *     format code, so an xlsx cell can stay a real number / date while still
+ *     displaying formatted (currency symbol, thousands, date pattern).
+ *
+ * Custom per-row `formatter` callbacks are intentionally NOT handled here -
+ * they may close over row/table state. Columns that need custom export text
+ * should provide an `exportValue(row)` hook at the export layer instead.
+ */
+import type { CellFormatConfig } from './core';
+export { computeColumnStat, contrastText, formatsNeedingStats, resolveCellFormat, type ColumnStat, type ConditionalFormat, type ResolvedCellFormat, } from './conditional-formatting';
+/** Best-effort coercion of a cell value to a Date. Accepts Date, epoch ms
+ *  numbers, and parseable date strings. Returns null when it isn't a date. */
+export declare function coerceExportDate(value: unknown): Date | null;
+/**
+ * Format a raw cell value to its on-screen display string using the column's
+ * `format` config. Mirrors the grid's own numeric / currency / percent / date
+ * branches. Values with no (or an unrecognised) format fall back to
+ * `String(value)`, and `null` / `undefined` become an empty string.
+ */
+export declare function formatValueForExport(value: unknown, format: CellFormatConfig | undefined): string;
+/**
+ * Map a `CellFormatConfig` to an Excel/OOXML number-format code, so an xlsx
+ * writer can keep the cell numeric/date while displaying it formatted.
+ * Returns `undefined` when the format has no natural Excel representation
+ * (or the caller should just write a string).
+ *
+ * These are deliberately conservative, widely-recognised codes:
+ *   number   → `#,##0[.00…]`   (grouping + N decimals)
+ *   currency → `"$"#,##0.00`   (symbol + grouping + 2 decimals)
+ *   percent  → `0[.00…]%`      (Excel multiplies by 100, so this pairs with a
+ *                               0..1 fraction; see `valueForExcel`)
+ *   date     → `yyyy-mm-dd`, datetime → `yyyy-mm-dd hh:mm`
+ */
+export declare function toExcelNumFmt(format: CellFormatConfig | undefined): string | undefined;
+/**
+ * Turn a grid's data rows + columns into the header-first `{ field: value }`
+ * record shape the serializers consume, applying each column's `format` so
+ * the export matches what's on screen (unless `rawValues`). Optionally
+ * restricts + reorders columns to a `columns` field subset.
+ */
+export declare function projectGridRows(dataRows: ReadonlyArray<Record<string, unknown>>, columns: ReadonlyArray<GridExportColumn>, opts?: {
+    columns?: ReadonlyArray<string>;
+    rawValues?: boolean;
+}): {
+    records: Array<Record<string, unknown>>;
+    fields: string[];
+    align: Record<string, 'left' | 'center' | 'right'>;
+};
+/**
+ * The value to write into a native xlsx cell that carries an Excel numFmt.
+ * Numbers stay numbers; percent values are divided to the 0..1 fraction Excel
+ * expects (unless the config already stores 0..1); dates become real `Date`s.
+ * Returns `{ ok: false }` when the value can't be represented natively and the
+ * caller should fall back to the formatted string.
+ */
+export declare function valueForExcel(value: unknown, format: CellFormatConfig | undefined): {
+    ok: true;
+    value: number | Date;
+} | {
+    ok: false;
+};
+export type GridExportScope = 'displayed' | 'selected' | 'all';
+/** The slice of a grid column an exporter needs. Accepts `api.getColumns()`. */
+export type GridExportColumn = {
+    field: string;
+    header: string;
+    format?: CellFormatConfig | undefined;
+    align?: 'left' | 'center' | 'right';
+};
+export type GridExportOptions = {
+    /** Base filename (no extension). Default 'grid'. */
+    filename?: string;
+    /** Which rows to export. Default 'displayed' (current view). */
+    rows?: GridExportScope;
+    /** Restrict to these fields, in this order. Default: all visible columns. */
+    columns?: string[];
+    /** Export raw values instead of the on-screen formatted display. Default false. */
+    rawValues?: boolean;
+    /** Prepend a UTF-8 BOM (csv/tsv) so Excel detects UTF-8. Default true. */
+    bom?: boolean;
+    /** Cancel a large export. */
+    signal?: AbortSignal;
+    /** Progress for large exports. */
+    onProgress?: (progress: SerializeProgress) => void;
+    /** When false, skip the browser download and just return the text. Default true. */
+    download?: boolean;
+};
+export type GridClipboardFormat = 'csv' | 'tsv' | 'markdown';
+export type GridClipboardOptions = {
+    /** Clipboard payload format. Default 'tsv' (pastes straight into Excel). */
+    format?: GridClipboardFormat;
+    rows?: GridExportScope;
+    columns?: string[];
+    rawValues?: boolean;
+};
+export type SerializeProgress = {
+    phase: 'serialize';
+    /** 0..1 completion of the row walk. */
+    ratio: number;
+    row: number;
+    total: number;
+};
+export type CsvOptions = {
+    /** Field delimiter. Default ',' (','→CSV, '\t'→TSV). */
+    delimiter?: string;
+    /** Line ending between records. Default '\r\n' (Excel-friendly). */
+    eol?: string;
+    /** Prepend a UTF-8 BOM so Excel detects UTF-8. Default true for csv/tsv. */
+    bom?: boolean;
+};
+export type SerializeOptions = {
+    onProgress?: (p: SerializeProgress) => void;
+    signal?: AbortSignal;
+    csv?: CsvOptions;
+    /** Rows processed between event-loop yields. Default 5000. */
+    chunkRows?: number;
+};
+/**
+ * Serialize projected rows to a delimited string (CSV / TSV).
+ * `rows[0]` is treated as the header row.
+ */
+export declare function serializeDelimited(rows: ReadonlyArray<Record<string, unknown>>, fields: ReadonlyArray<string>, opts?: SerializeOptions): Promise<string>;
+export type ExportCellVisual = {
+    fill?: string;
+    color?: string;
+    bold?: boolean;
+    icon?: string;
+};
+/**
+ * Serialize projected rows to a standalone HTML `<table>` document.
+ * `rows[0]` is the header row (rendered as `<th>`); the rest are `<td>`.
+ */
+export declare function serializeHtml(rows: ReadonlyArray<Record<string, unknown>>, fields: ReadonlyArray<string>, opts?: SerializeOptions & {
+    title?: string;
+    align?: Record<string, 'left' | 'center' | 'right'>;
+    /** Per-data-cell conditional-format visual (`rowIdx` is 0-based over data). */
+    cellStyle?: (rowIdx: number, colIdx: number) => ExportCellVisual | undefined;
+    /** Per-data-cell hyperlink URL. */
+    cellLink?: (rowIdx: number, colIdx: number) => string | undefined;
+}): Promise<string>;
+/**
+ * Serialize projected rows to a JSON array of `{ field: value }` objects.
+ * `rows[0]` (the header row) is dropped - JSON keys are the field names.
+ */
+export declare function serializeJson(rows: ReadonlyArray<Record<string, unknown>>, fields: ReadonlyArray<string>, opts?: SerializeOptions): Promise<string>;
+/**
+ * Serialize projected rows to a GitHub-flavored Markdown table. `rows[0]` is
+ * the header row; `align` sets the `:---`, `:--:`, `---:` markers per column.
+ */
+export declare function serializeMarkdown(rows: ReadonlyArray<Record<string, unknown>>, fields: ReadonlyArray<string>, opts?: SerializeOptions & {
+    align?: Record<string, 'left' | 'center' | 'right'>;
+}): Promise<string>;
+/**
+ * Serialize projected rows to a simple XML document:
+ * `<rows><row><field>value</field>…</row>…</rows>`. `rows[0]` (header) is
+ * dropped - element names come from the field names.
+ */
+export declare function serializeXml(rows: ReadonlyArray<Record<string, unknown>>, fields: ReadonlyArray<string>, opts?: SerializeOptions & {
+    rootTag?: string;
+    rowTag?: string;
+}): Promise<string>;
+/** Trigger a browser download of an already-built Blob. No-op guard for SSR. */
+export declare function downloadBlobFile(blob: Blob, filename: string): void;
+/** Trigger a browser download of a text blob. No-op guard for SSR. */
+export declare function downloadTextFile(text: string, filename: string, mime: string): void;
+/** Write text to the system clipboard. Throws when the API is unavailable
+ *  (insecure context / SSR). */
+export declare function copyTextToClipboard(text: string): Promise<void>;

package/dist/export-format.js

@@ -0,0 +1,419 @@
+import { formatNumericWithConfig, getDateFormatter, resolveDatePattern, } from './cell-formatting';
+// Re-export the pure conditional-formatting engine here too, so the
+// Svelte-free `@svgrid/grid/format` subpath carries it for @svgrid/enterprise's
+// export code (which must not pull in SvGrid.svelte).
+export { computeColumnStat, contrastText, formatsNeedingStats, resolveCellFormat, } from './conditional-formatting';
+/** Best-effort coercion of a cell value to a Date. Accepts Date, epoch ms
+ *  numbers, and parseable date strings. Returns null when it isn't a date. */
+export function coerceExportDate(value) {
+    if (value instanceof Date)
+        return Number.isNaN(value.getTime()) ? null : value;
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        const d = new Date(value);
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
+    if (typeof value === 'string' && value.trim() !== '') {
+        const d = new Date(value);
+        return Number.isNaN(d.getTime()) ? null : d;
+    }
+    return null;
+}
+/**
+ * Format a raw cell value to its on-screen display string using the column's
+ * `format` config. Mirrors the grid's own numeric / currency / percent / date
+ * branches. Values with no (or an unrecognised) format fall back to
+ * `String(value)`, and `null` / `undefined` become an empty string.
+ */
+export function formatValueForExport(value, format) {
+    if (value == null)
+        return '';
+    if (!format)
+        return String(value);
+    if (format.type === 'number' || format.type === 'currency' || format.type === 'percent') {
+        return formatNumericWithConfig(value, {
+            type: format.type,
+            locales: format.locales,
+            currency: format.type === 'currency' ? (format.currency ?? 'USD') : undefined,
+            valueIsPercentPoints: format.type === 'percent' ? format.valueIsPercentPoints : undefined,
+            options: format.options,
+        });
+    }
+    if (format.type === 'date' || format.type === 'datetime') {
+        const parsed = coerceExportDate(value);
+        if (parsed) {
+            const preset = resolveDatePattern(format.pattern, format.type);
+            const merged = preset || format.options
+                ? { ...preset, ...format.options }
+                : format.type === 'date'
+                    ? { year: 'numeric', month: '2-digit', day: '2-digit' }
+                    : {
+                        year: 'numeric',
+                        month: '2-digit',
+                        day: '2-digit',
+                        hour: '2-digit',
+                        minute: '2-digit',
+                    };
+            return getDateFormatter(format.locales, merged).format(parsed);
+        }
+    }
+    return String(value);
+}
+/**
+ * Map a `CellFormatConfig` to an Excel/OOXML number-format code, so an xlsx
+ * writer can keep the cell numeric/date while displaying it formatted.
+ * Returns `undefined` when the format has no natural Excel representation
+ * (or the caller should just write a string).
+ *
+ * These are deliberately conservative, widely-recognised codes:
+ *   number   → `#,##0[.00…]`   (grouping + N decimals)
+ *   currency → `"$"#,##0.00`   (symbol + grouping + 2 decimals)
+ *   percent  → `0[.00…]%`      (Excel multiplies by 100, so this pairs with a
+ *                               0..1 fraction; see `valueForExcel`)
+ *   date     → `yyyy-mm-dd`, datetime → `yyyy-mm-dd hh:mm`
+ */
+export function toExcelNumFmt(format) {
+    if (!format)
+        return undefined;
+    const decimals = () => {
+        // `options` is a union across number/date formats; only the numeric ones
+        // carry fraction-digit hints, so read them through a narrow shape.
+        const o = format.options;
+        if (o && typeof o.maximumFractionDigits === 'number')
+            return o.maximumFractionDigits;
+        if (o && typeof o.minimumFractionDigits === 'number')
+            return o.minimumFractionDigits;
+        return format.type === 'currency' ? 2 : format.type === 'number' ? 0 : 2;
+    };
+    const dp = (n) => (n > 0 ? '.' + '0'.repeat(n) : '');
+    switch (format.type) {
+        case 'number':
+            return `#,##0${dp(decimals())}`;
+        case 'currency': {
+            const sym = currencySymbol(format.currency ?? 'USD');
+            return `"${sym}"#,##0${dp(decimals())}`;
+        }
+        case 'percent':
+            return `0${dp(decimals())}%`;
+        case 'date':
+            return 'yyyy-mm-dd';
+        case 'datetime':
+            return 'yyyy-mm-dd hh:mm';
+        default:
+            return undefined;
+    }
+}
+/**
+ * Turn a grid's data rows + columns into the header-first `{ field: value }`
+ * record shape the serializers consume, applying each column's `format` so
+ * the export matches what's on screen (unless `rawValues`). Optionally
+ * restricts + reorders columns to a `columns` field subset.
+ */
+export function projectGridRows(dataRows, columns, opts = {}) {
+    const chosen = opts.columns && opts.columns.length
+        ? opts.columns
+            .map((f) => columns.find((c) => c.field === f))
+            .filter((c) => !!c)
+        : columns.filter((c) => c.field);
+    const fields = chosen.map((c) => c.field);
+    const align = {};
+    for (const c of chosen)
+        if (c.align)
+            align[c.field] = c.align;
+    const header = {};
+    for (const c of chosen)
+        header[c.field] = c.header;
+    const records = [header];
+    for (const row of dataRows) {
+        const rec = {};
+        for (const c of chosen) {
+            const raw = row[c.field];
+            rec[c.field] = opts.rawValues ? raw : formatValueForExport(raw, c.format);
+        }
+        records.push(rec);
+    }
+    return { records, fields, align };
+}
+/** A tiny currency-code → symbol map for the Excel numFmt code. Falls back
+ *  to the ISO code itself (e.g. "CHF") when we don't have a glyph. */
+function currencySymbol(code) {
+    const map = {
+        USD: '$',
+        EUR: '€',
+        GBP: '£',
+        JPY: '¥',
+        CNY: '¥',
+        INR: '₹',
+        KRW: '₩',
+        RUB: '₽',
+        BRL: 'R$',
+    };
+    return map[code.toUpperCase()] ?? code.toUpperCase();
+}
+/**
+ * The value to write into a native xlsx cell that carries an Excel numFmt.
+ * Numbers stay numbers; percent values are divided to the 0..1 fraction Excel
+ * expects (unless the config already stores 0..1); dates become real `Date`s.
+ * Returns `{ ok: false }` when the value can't be represented natively and the
+ * caller should fall back to the formatted string.
+ */
+export function valueForExcel(value, format) {
+    if (value == null || !format)
+        return { ok: false };
+    if (format.type === 'number' || format.type === 'currency') {
+        const n = typeof value === 'number' ? value : Number(value);
+        return Number.isFinite(n) ? { ok: true, value: n } : { ok: false };
+    }
+    if (format.type === 'percent') {
+        const n = typeof value === 'number' ? value : Number(value);
+        if (!Number.isFinite(n))
+            return { ok: false };
+        // Excel's percent numFmt multiplies by 100, so it wants the fraction.
+        return { ok: true, value: format.valueIsPercentPoints === true ? n / 100 : n };
+    }
+    if (format.type === 'date' || format.type === 'datetime') {
+        const d = coerceExportDate(value);
+        return d ? { ok: true, value: d } : { ok: false };
+    }
+    return { ok: false };
+}
+const EXPORT_BOM = '';
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new DOMException('Export aborted', 'AbortError');
+    }
+}
+/** Let the event loop breathe (paint a progress bar, honour an abort). */
+const yieldToLoop = () => new Promise((resolve) => setTimeout(resolve, 0));
+/** RFC-4180 quoting: wrap in double quotes and double any embedded quote
+ *  when the value contains the delimiter, a quote, or a newline. */
+function csvCell(value, delimiter) {
+    const s = value == null
+        ? ''
+        : value instanceof Date
+            ? value.toISOString()
+            : String(value);
+    if (s === '')
+        return s;
+    if (s.includes(delimiter) || s.includes('"') || s.includes('\n') || s.includes('\r')) {
+        return `"${s.replace(/"/g, '""')}"`;
+    }
+    return s;
+}
+/**
+ * Serialize projected rows to a delimited string (CSV / TSV).
+ * `rows[0]` is treated as the header row.
+ */
+export async function serializeDelimited(rows, fields, opts = {}) {
+    const delimiter = opts.csv?.delimiter ?? ',';
+    const eol = opts.csv?.eol ?? '\r\n';
+    const useBom = opts.csv?.bom ?? true;
+    const chunk = Math.max(1, opts.chunkRows ?? 5000);
+    const total = rows.length;
+    const parts = [];
+    for (let i = 0; i < rows.length; i++) {
+        throwIfAborted(opts.signal);
+        const row = rows[i];
+        parts.push(fields.map((f) => csvCell(row[f], delimiter)).join(delimiter));
+        if (i > 0 && i % chunk === 0) {
+            opts.onProgress?.({ phase: 'serialize', ratio: i / total, row: i, total });
+            await yieldToLoop();
+        }
+    }
+    opts.onProgress?.({ phase: 'serialize', ratio: 1, row: total, total });
+    const body = parts.join(eol);
+    return (useBom ? EXPORT_BOM : '') + body;
+}
+const HTML_ESCAPE = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+function htmlCell(value) {
+    const s = value == null ? '' : value instanceof Date ? value.toISOString() : String(value);
+    return s.replace(/[&<>"']/g, (c) => HTML_ESCAPE[c]);
+}
+/**
+ * Serialize projected rows to a standalone HTML `<table>` document.
+ * `rows[0]` is the header row (rendered as `<th>`); the rest are `<td>`.
+ */
+export async function serializeHtml(rows, fields, opts = {}) {
+    const chunk = Math.max(1, opts.chunkRows ?? 5000);
+    const total = rows.length;
+    const align = opts.align ?? {};
+    const cellStyle = opts.cellStyle;
+    const cellLink = opts.cellLink;
+    const title = opts.title ?? 'Grid export';
+    const head = rows[0];
+    const th = head
+        ? fields.map((f) => `<th>${htmlCell(head[f])}</th>`).join('')
+        : '';
+    const bodyParts = [];
+    for (let i = 1; i < rows.length; i++) {
+        throwIfAborted(opts.signal);
+        const row = rows[i];
+        const tds = fields
+            .map((f, ci) => {
+            const a = align[f];
+            const styles = [];
+            if (a && a !== 'left')
+                styles.push(`text-align:${a}`);
+            const cf = cellStyle?.(i - 1, ci);
+            if (cf?.fill)
+                styles.push(`background:${cf.fill}`);
+            if (cf?.color)
+                styles.push(`color:${cf.color}`);
+            if (cf?.bold)
+                styles.push('font-weight:700');
+            const style = styles.length ? ` style="${styles.join(';')}"` : '';
+            let text = cf?.icon ? `${cf.icon} ${htmlCell(row[f])}` : htmlCell(row[f]);
+            const href = cellLink?.(i - 1, ci);
+            if (href)
+                text = `<a href="${htmlCell(href)}">${text}</a>`;
+            return `<td${style}>${text}</td>`;
+        })
+            .join('');
+        bodyParts.push(`<tr>${tds}</tr>`);
+        if (i > 0 && i % chunk === 0) {
+            opts.onProgress?.({ phase: 'serialize', ratio: i / total, row: i, total });
+            await yieldToLoop();
+        }
+    }
+    opts.onProgress?.({ phase: 'serialize', ratio: 1, row: total, total });
+    return (`<!doctype html><html><head><meta charset="utf-8"><title>${htmlCell(title)}</title>` +
+        `<style>table{border-collapse:collapse;font-family:system-ui,sans-serif;font-size:13px}` +
+        `th,td{border:1px solid #d0d7de;padding:6px 10px}th{background:#f6f8fa;text-align:left}</style>` +
+        `</head><body><table><thead><tr>${th}</tr></thead><tbody>${bodyParts.join('')}</tbody></table></body></html>`);
+}
+/**
+ * Serialize projected rows to a JSON array of `{ field: value }` objects.
+ * `rows[0]` (the header row) is dropped - JSON keys are the field names.
+ */
+export async function serializeJson(rows, fields, opts = {}) {
+    const chunk = Math.max(1, opts.chunkRows ?? 5000);
+    const total = rows.length - 1;
+    const out = [];
+    for (let i = 1; i < rows.length; i++) {
+        throwIfAborted(opts.signal);
+        const src = rows[i];
+        const obj = {};
+        for (const f of fields)
+            obj[f] = src[f];
+        out.push(obj);
+        if (i > 0 && i % chunk === 0) {
+            opts.onProgress?.({ phase: 'serialize', ratio: i / total, row: i, total });
+            await yieldToLoop();
+        }
+    }
+    opts.onProgress?.({ phase: 'serialize', ratio: 1, row: total, total });
+    return JSON.stringify(out, null, 2);
+}
+/** Escape a Markdown table cell: pipes and newlines would break the row. */
+function mdCell(value) {
+    const s = value == null ? '' : value instanceof Date ? value.toISOString() : String(value);
+    return s.replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
+}
+/**
+ * Serialize projected rows to a GitHub-flavored Markdown table. `rows[0]` is
+ * the header row; `align` sets the `:---`, `:--:`, `---:` markers per column.
+ */
+export async function serializeMarkdown(rows, fields, opts = {}) {
+    const chunk = Math.max(1, opts.chunkRows ?? 5000);
+    const total = rows.length;
+    const align = opts.align ?? {};
+    const head = rows[0];
+    const headerLine = `| ${fields.map((f) => mdCell(head?.[f])).join(' | ')} |`;
+    const sepLine = `| ${fields
+        .map((f) => {
+        const a = align[f];
+        return a === 'right' ? '---:' : a === 'center' ? ':--:' : '---';
+    })
+        .join(' | ')} |`;
+    const bodyLines = [];
+    for (let i = 1; i < rows.length; i++) {
+        throwIfAborted(opts.signal);
+        const src = rows[i];
+        bodyLines.push(`| ${fields.map((f) => mdCell(src[f])).join(' | ')} |`);
+        if (i > 0 && i % chunk === 0) {
+            opts.onProgress?.({ phase: 'serialize', ratio: i / total, row: i, total });
+            await yieldToLoop();
+        }
+    }
+    opts.onProgress?.({ phase: 'serialize', ratio: 1, row: total, total });
+    return [headerLine, sepLine, ...bodyLines].join('\n') + '\n';
+}
+const XML_ESCAPE = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&apos;',
+};
+function xmlText(value) {
+    const s = value == null ? '' : value instanceof Date ? value.toISOString() : String(value);
+    return s.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F]/g, '').replace(/[&<>"']/g, (c) => XML_ESCAPE[c]);
+}
+/** Coerce a field name into a valid XML element name. */
+function xmlTag(field) {
+    const t = field.replace(/[^A-Za-z0-9_.-]/g, '_');
+    return /^[A-Za-z_]/.test(t) ? t : `_${t}`;
+}
+/**
+ * Serialize projected rows to a simple XML document:
+ * `<rows><row><field>value</field>…</row>…</rows>`. `rows[0]` (header) is
+ * dropped - element names come from the field names.
+ */
+export async function serializeXml(rows, fields, opts = {}) {
+    const chunk = Math.max(1, opts.chunkRows ?? 5000);
+    const total = rows.length - 1;
+    const root = opts.rootTag ?? 'rows';
+    const rowTag = opts.rowTag ?? 'row';
+    const tags = fields.map(xmlTag);
+    const parts = [`<?xml version="1.0" encoding="UTF-8"?>`, `<${root}>`];
+    for (let i = 1; i < rows.length; i++) {
+        throwIfAborted(opts.signal);
+        const src = rows[i];
+        const cells = fields
+            .map((f, ci) => `<${tags[ci]}>${xmlText(src[f])}</${tags[ci]}>`)
+            .join('');
+        parts.push(`  <${rowTag}>${cells}</${rowTag}>`);
+        if (i > 0 && i % chunk === 0) {
+            opts.onProgress?.({ phase: 'serialize', ratio: i / total, row: i, total });
+            await yieldToLoop();
+        }
+    }
+    parts.push(`</${root}>`);
+    opts.onProgress?.({ phase: 'serialize', ratio: 1, row: total, total });
+    return parts.join('\n');
+}
+// ----- Delivery: download + clipboard (browser-guarded) --------------------
+/** Trigger a browser download of an already-built Blob. No-op guard for SSR. */
+export function downloadBlobFile(blob, filename) {
+    if (typeof document === 'undefined' || typeof URL === 'undefined') {
+        throw new Error('@svgrid/grid: export requires a browser environment');
+    }
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+/** Trigger a browser download of a text blob. No-op guard for SSR. */
+export function downloadTextFile(text, filename, mime) {
+    if (typeof document === 'undefined' || typeof URL === 'undefined') {
+        throw new Error('@svgrid/grid: text export requires a browser environment');
+    }
+    downloadBlobFile(new Blob([text], { type: mime }), filename);
+}
+/** Write text to the system clipboard. Throws when the API is unavailable
+ *  (insecure context / SSR). */
+export async function copyTextToClipboard(text) {
+    if (typeof navigator === 'undefined' || !navigator.clipboard) {
+        throw new Error('@svgrid/grid: clipboard API is unavailable in this context');
+    }
+    await navigator.clipboard.writeText(text);
+}

package/dist/hyperformula-adapter.d.ts

@@ -43,6 +43,10 @@ export type HyperFormulaInstance = {
         row: number;
         col: number;
     }): unknown;
+    /** Bulk-load an entire sheet in one call (one recalc instead of one per
+     *  cell). Optional so minimal / mock instances still satisfy the type;
+     *  the adapter falls back to per-cell `setCellContents` when it's absent. */
+    setSheetContent?(sheetId: number, values: unknown[][]): unknown;
     destroy(): void;
     rebuildAndRecalculate(): void;
 };

package/dist/hyperformula-adapter.js

@@ -31,12 +31,21 @@ export function createHyperFormulaSheet(config) {
     const colByField = new Map();
     fields.forEach((f, i) => colByField.set(f, i));
     // 1. Seed HF with every cell. HF expects raw strings for formulas
-    //    (`'=A1+B1'`) and primitives for everything else.
-    for (let r = 0; r < rows.length; r += 1) {
-        const row = rows[r];
-        for (let c = 0; c < fields.length; c += 1) {
-            const field = fields[c];
-            hf.setCellContents({ sheet: sheetId, row: r, col: c }, row[field]);
+    //    (`'=A1+B1'`) and primitives for everything else. Prefer a single bulk
+    //    `setSheetContent` write - it recalculates ONCE instead of once per
+    //    setCellContents, ~3x faster to mount a large sheet (e.g. 200x26). Fall
+    //    back to per-cell for instances that don't expose it.
+    if (typeof hf.setSheetContent === 'function') {
+        const grid = rows.map((row) => fields.map((f) => row[f]));
+        hf.setSheetContent(sheetId, grid);
+    }
+    else {
+        for (let r = 0; r < rows.length; r += 1) {
+            const row = rows[r];
+            for (let c = 0; c < fields.length; c += 1) {
+                const field = fields[c];
+                hf.setCellContents({ sheet: sheetId, row: r, col: c }, row[field]);
+            }
         }
     }
     /** Pull computed values out of HF into a fresh row array. Preserves