@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/import.js

@@ -0,0 +1,846 @@
+/**
+ * Pro Import feature
+ * ------------------
+ *
+ * Read Excel (.xlsx), CSV, TSV, or JSON in the browser and produce a typed
+ * preview of the parsed rows, including per-cell validation errors. The
+ * caller decides whether to commit the parsed rows into the grid via
+ * `api.addRows(...)`, or to render an editing modal so the user can fix
+ * issues first.
+ *
+ * Two flavours of usage:
+ *
+ *   1. Read + preview, then commit explicitly:
+ *
+ *        const result = await api.importData({ file, format: 'auto' })
+ *        // result.headers, result.rows, result.errors
+ *        if (result.errors.length === 0) api.addRows(result.rows, 'bottom')
+ *
+ *   2. Read and commit in one go (no preview UX):
+ *
+ *        await api.importData({ file, format: 'auto', commit: true })
+ *
+ * Both go through the same polite license soft-gate as `exportData` and
+ * `print`, so unlicensed evaluation works but emits a one-time nudge.
+ */
+import { assertEnterpriseLicensed } from './license';
+// ---------------------------------------------------------------------------
+// Lazy peer dependency: jszip (xlsx only)
+// ---------------------------------------------------------------------------
+let jszipPromise = null;
+async function getJSZip() {
+    if (typeof window === 'undefined') {
+        throw new Error('@svgrid/enterprise: importData requires a browser environment');
+    }
+    const g = globalThis;
+    if (g.JSZip)
+        return g.JSZip;
+    if (!jszipPromise) {
+        jszipPromise = (async () => {
+            let mod;
+            try {
+                // Optional peer, loaded on demand (keeps consumer type-checks clean when absent).
+                // @ts-ignore - "jszip" is an optional peerDependency
+                mod = await import('jszip');
+            }
+            catch {
+                throw new Error('@svgrid/enterprise: xlsx import requires the "jszip" peer dependency. ' +
+                    'Install it with: pnpm add jszip');
+            }
+            const J = mod.default ?? mod;
+            g.JSZip = J;
+            return J;
+        })();
+    }
+    return jszipPromise;
+}
+// ---------------------------------------------------------------------------
+// Format sniffing
+// ---------------------------------------------------------------------------
+function sniffFormat(file, declared) {
+    if (declared !== 'auto')
+        return declared;
+    // File: trust the extension.
+    if (file instanceof File && file.name) {
+        const ext = file.name.toLowerCase().split('.').pop() ?? '';
+        if (ext === 'xlsx')
+            return 'xlsx';
+        if (ext === 'csv')
+            return 'csv';
+        if (ext === 'tsv' || ext === 'tab')
+            return 'tsv';
+        if (ext === 'json')
+            return 'json';
+    }
+    // String: sniff the first non-whitespace char.
+    if (typeof file === 'string') {
+        const trimmed = file.trimStart();
+        if (trimmed.startsWith('[') || trimmed.startsWith('{'))
+            return 'json';
+        // Tab-rich heads are tsv; otherwise default to csv.
+        const firstLine = trimmed.slice(0, 200).split(/\r?\n/)[0] ?? '';
+        if ((firstLine.match(/\t/g)?.length ?? 0) >= 1)
+            return 'tsv';
+        return 'csv';
+    }
+    // Blob without a filename / extension: assume xlsx (the most common case
+    // the importer is asked to handle).
+    return 'xlsx';
+}
+// ---------------------------------------------------------------------------
+// CSV / TSV parser
+// ---------------------------------------------------------------------------
+/**
+ * RFC 4180-flavour CSV / TSV parser. Handles:
+ *   - quoted fields with embedded commas / tabs / newlines
+ *   - escaped quotes ("") inside quoted fields
+ *   - both \r\n and \n line endings
+ *
+ * Doesn't aim to be the world's fastest parser - it walks the string
+ * character-by-character. For files in the 10-100k row range this is
+ * fine; for million-row imports, do the import server-side.
+ */
+function parseDelimited(text, sep) {
+    const rows = [];
+    let row = [];
+    let field = '';
+    let i = 0;
+    let inQuotes = false;
+    // Strip a UTF-8 BOM if present so the first header isn't named "ID".
+    if (text.charCodeAt(0) === 0xfeff)
+        i = 1;
+    while (i < text.length) {
+        const c = text[i];
+        if (inQuotes) {
+            if (c === '"') {
+                if (text[i + 1] === '"') {
+                    field += '"';
+                    i += 2;
+                    continue;
+                }
+                inQuotes = false;
+                i += 1;
+                continue;
+            }
+            field += c;
+            i += 1;
+            continue;
+        }
+        if (c === '"') {
+            inQuotes = true;
+            i += 1;
+            continue;
+        }
+        if (c === sep) {
+            row.push(field);
+            field = '';
+            i += 1;
+            continue;
+        }
+        if (c === '\r') {
+            if (text[i + 1] === '\n')
+                i += 1;
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+            i += 1;
+            continue;
+        }
+        if (c === '\n') {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+            i += 1;
+            continue;
+        }
+        field += c;
+        i += 1;
+    }
+    // Flush the trailing field / row (no trailing newline).
+    if (field.length > 0 || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows;
+}
+// ---------------------------------------------------------------------------
+// XLSX parser (minimal)
+// ---------------------------------------------------------------------------
+/**
+ * Minimal SpreadsheetML reader. Supports the .xlsx shape Excel and Google
+ * Sheets produce by default: one default sheet, optional shared-strings
+ * table, inline strings, numbers, and dates expressed as serial numbers.
+ *
+ * The grid does NOT try to be a fully-featured Excel reader. Formulas
+ * are read as their cached value when present. Multi-sheet imports
+ * require the caller to pre-extract the desired sheet (or for a future
+ * release).
+ */
+async function parseXlsx(file) {
+    const J = await getJSZip();
+    const buf = await file.arrayBuffer();
+    const zip = await J.loadAsync(buf);
+    // Read sharedStrings.xml if it exists.
+    let sharedStrings = [];
+    const ssEntry = zip.file('xl/sharedStrings.xml');
+    if (ssEntry) {
+        const ssText = await ssEntry.async('string');
+        sharedStrings = parseSharedStrings(ssText);
+    }
+    // Read the FIRST sheet. Workbook.xml -> rels mapping is involved; for the
+    // 99% case the first sheet lives at xl/worksheets/sheet1.xml.
+    const sheetEntry = zip.file('xl/worksheets/sheet1.xml') ??
+        zip.file('xl/worksheets/sheet 1.xml');
+    if (!sheetEntry) {
+        throw new Error('@svgrid/enterprise: could not locate sheet1.xml in the .xlsx archive');
+    }
+    const sheetText = await sheetEntry.async('string');
+    return parseSheetXml(sheetText, sharedStrings);
+}
+/** Pull every `<t>...</t>` out of sharedStrings.xml in document order. */
+function parseSharedStrings(xml) {
+    const out = [];
+    // A shared-string item may be a plain <si><t>X</t></si> or a rich-text
+    // <si><r><t>X</t></r><r><t>Y</t></r></si>. Concatenate every <t> inside
+    // each <si>.
+    const itemRe = /<si\b[^>]*>([\s\S]*?)<\/si>/g;
+    const tRe = /<t\b[^>]*>([\s\S]*?)<\/t>/g;
+    let m;
+    while ((m = itemRe.exec(xml)) !== null) {
+        let combined = '';
+        let n;
+        tRe.lastIndex = 0;
+        while ((n = tRe.exec(m[1] ?? '')) !== null) {
+            combined += decodeXmlEntities(n[1] ?? '');
+        }
+        out.push(combined);
+    }
+    return out;
+}
+function decodeXmlEntities(s) {
+    return s
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&#10;/g, '\n')
+        .replace(/&#9;/g, '\t');
+}
+/**
+ * Convert a sheet's XML body into a dense `string[][]`. Holes in the
+ * cell stream (e.g. row jumps from col B to col E) are filled with
+ * empty strings so the result is rectangular.
+ */
+function parseSheetXml(xml, sharedStrings) {
+    const rows = [];
+    const rowRe = /<row\b[^>]*>([\s\S]*?)<\/row>/g;
+    const cellRe = /<c\b([^>]*)>([\s\S]*?)<\/c>/g;
+    const inlineStrRe = /<is>\s*([\s\S]*?)\s*<\/is>/;
+    const tRe = /<t\b[^>]*>([\s\S]*?)<\/t>/g;
+    const vRe = /<v>([\s\S]*?)<\/v>/;
+    let rowMatch;
+    while ((rowMatch = rowRe.exec(xml)) !== null) {
+        const rowBody = rowMatch[1] ?? '';
+        const cells = [];
+        let cellMatch;
+        cellRe.lastIndex = 0;
+        while ((cellMatch = cellRe.exec(rowBody)) !== null) {
+            const attrs = cellMatch[1] ?? '';
+            const body = cellMatch[2] ?? '';
+            const ref = /r="([A-Z]+)\d+"/.exec(attrs)?.[1] ?? '';
+            const colIndex = colRefToIndex(ref);
+            const type = /t="([^"]+)"/.exec(attrs)?.[1] ?? 'n';
+            // Pad holes with empty strings so column alignment survives.
+            while (cells.length < colIndex)
+                cells.push('');
+            let value = '';
+            if (type === 's') {
+                const idx = Number(vRe.exec(body)?.[1] ?? '-1');
+                value = sharedStrings[idx] ?? '';
+            }
+            else if (type === 'inlineStr' || type === 'str') {
+                const inlineBody = inlineStrRe.exec(body)?.[1] ?? body;
+                let parts = '';
+                let n;
+                tRe.lastIndex = 0;
+                while ((n = tRe.exec(inlineBody)) !== null)
+                    parts += decodeXmlEntities(n[1] ?? '');
+                value = parts || decodeXmlEntities(vRe.exec(body)?.[1] ?? '');
+            }
+            else if (type === 'b') {
+                value = vRe.exec(body)?.[1] === '1' ? 'true' : 'false';
+            }
+            else {
+                // Numeric or date - we surface as the raw number string. The
+                // caller's column type then handles parsing.
+                value = decodeXmlEntities(vRe.exec(body)?.[1] ?? '');
+            }
+            cells.push(value);
+        }
+        rows.push(cells);
+    }
+    return rows;
+}
+/** Excel column reference ("A", "B", ..., "AA", ...) to a zero-based index. */
+function colRefToIndex(ref) {
+    if (!ref)
+        return 0;
+    let n = 0;
+    for (let i = 0; i < ref.length; i += 1) {
+        n = n * 26 + (ref.charCodeAt(i) - 64);
+    }
+    return Math.max(0, n - 1);
+}
+// ---------------------------------------------------------------------------
+// Coerce raw string values into typed JS values based on a sample of other
+// values in the same column. We don't ask the consumer for a schema - it
+// would defeat the "drop a file in and go" UX - but we DO want
+// "$1,234.56" to become 1234.56 and "true" to become true.
+// ---------------------------------------------------------------------------
+function inferAndCoerce(value) {
+    if (value === '')
+        return '';
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return '';
+    // Boolean
+    if (trimmed === 'true' || trimmed === 'TRUE')
+        return true;
+    if (trimmed === 'false' || trimmed === 'FALSE')
+        return false;
+    // Currency / number with grouping. Strip $, commas, whitespace.
+    if (/^[-+]?\$?\s?[\d,]+(?:\.\d+)?$/.test(trimmed)) {
+        const n = parseFloat(trimmed.replace(/[$,\s]/g, ''));
+        if (!Number.isNaN(n))
+            return n;
+    }
+    // Bare integer / float
+    if (/^[-+]?\d+(?:\.\d+)?(?:e[+-]?\d+)?$/i.test(trimmed)) {
+        const n = parseFloat(trimmed);
+        if (!Number.isNaN(n))
+            return n;
+    }
+    // ISO date (yyyy-mm-dd, optionally with time) -> keep as ISO string. We
+    // don't return a Date because most grid columns prefer strings on the
+    // wire (sort + filter + format paths are already date-aware).
+    if (/^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2})?(?:Z|[+-]\d{2}:?\d{2})?)?$/.test(trimmed)) {
+        return trimmed;
+    }
+    return trimmed;
+}
+// ---------------------------------------------------------------------------
+// Map source rows -> typed records.
+// ---------------------------------------------------------------------------
+/**
+ * Field names we refuse to write, because assigning them from untrusted file
+ * headers would let a malicious upload walk the prototype chain (prototype
+ * pollution). Applies to the default snake_case fallback AND anything a
+ * columnMap points at.
+ */
+const UNSAFE_FIELDS = new Set(['__proto__', 'prototype', 'constructor']);
+/** Resolve each source header to a target field (or null = drop the column),
+ *  honouring the columnMap and refusing blank + pollution-prone names. */
+function computeFields(headers, columnMap) {
+    return headers.map((h) => {
+        let field;
+        if (columnMap && Object.prototype.hasOwnProperty.call(columnMap, h)) {
+            field = columnMap[h] ?? null;
+        }
+        else {
+            field = h.toLowerCase().replace(/\s+/g, '_').replace(/[^a-z0-9_]/g, '');
+        }
+        if (field == null || field === '' || UNSAFE_FIELDS.has(field))
+            return null;
+        return field;
+    });
+}
+/** Build one typed record from a row of cells. Pure; no side effects on the
+ *  shared error list (returns its own). */
+function buildRecord(cells, headerCount, fields, columnTypes, outRowIndex) {
+    const rec = {};
+    const errors = [];
+    for (let i = 0; i < headerCount; i += 1) {
+        const field = fields[i];
+        if (field == null)
+            continue;
+        const raw = cells[i] ?? '';
+        const declaredType = columnTypes?.[field];
+        if (declaredType) {
+            const result = coerceTyped(raw, declaredType);
+            if (result.ok) {
+                rec[field] = result.value;
+            }
+            else {
+                errors.push({ rowIndex: outRowIndex, field, message: result.message });
+                // Park the raw string so downstream code still sees SOMETHING.
+                rec[field] = raw;
+            }
+        }
+        else {
+            rec[field] = inferAndCoerce(raw);
+        }
+    }
+    return { rec, errors };
+}
+/** Push `source` errors into `target`, stopping at `maxErrors`. Returns true
+ *  when it had to truncate. */
+function collectErrors(target, source, maxErrors) {
+    for (const e of source) {
+        if (maxErrors != null && target.length >= maxErrors)
+            return true;
+        target.push(e);
+    }
+    return false;
+}
+/** Drop duplicate rows by `key`, keeping the last occurrence in place. */
+function dedupeRows(rows, key) {
+    const idx = new Map();
+    const out = [];
+    for (const r of rows) {
+        const k = r?.[key];
+        if (k == null) {
+            out.push(r);
+            continue;
+        }
+        const at = idx.get(k);
+        if (at !== undefined)
+            out[at] = r;
+        else {
+            idx.set(k, out.length);
+            out.push(r);
+        }
+    }
+    return { rows: out, deduped: rows.length - out.length };
+}
+function isBlankRow(cells) {
+    return cells.every((c) => c === undefined || c.trim() === '');
+}
+function abortError() {
+    const e = new Error('@svgrid/enterprise: import cancelled');
+    e.name = 'AbortError';
+    return e;
+}
+/** Yield to the event loop so a long map doesn't block paint / input. */
+function nextTick() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}
+function buildRecords(matrix, columnMap, columnTypes, maxErrors) {
+    if (matrix.length === 0)
+        return { headers: [], rows: [], skipped: 0, errors: [], errorsTruncated: false };
+    const headers = (matrix[0] ?? []).map((h) => h.trim());
+    const fields = computeFields(headers, columnMap);
+    const dataRows = matrix.slice(1);
+    const out = [];
+    const errors = [];
+    let skipped = 0;
+    let errorsTruncated = false;
+    // Skipped (blank) rows don't count toward the output row index used
+    // in errors, so the indices match what the consumer's preview UI shows.
+    let outRowIndex = 0;
+    for (const cells of dataRows) {
+        if (isBlankRow(cells)) {
+            skipped += 1;
+            continue;
+        }
+        const { rec, errors: rowErrs } = buildRecord(cells, headers.length, fields, columnTypes, outRowIndex);
+        if (rowErrs.length && collectErrors(errors, rowErrs, maxErrors))
+            errorsTruncated = true;
+        out.push(rec);
+        outRowIndex += 1;
+    }
+    return { headers, rows: out, skipped, errors, errorsTruncated };
+}
+/**
+ * Strict per-type coercion used when the consumer declares
+ * `columnTypes`. Returns either `{ ok: true, value }` or
+ * `{ ok: false, message }` describing why the value couldn't be
+ * shaped into the declared type.
+ *
+ * Empty values for required types (number, date) error rather than
+ * silently coerce to 0 / null - the consumer can drop the row in
+ * their validator if blanks should be tolerated.
+ */
+function coerceTyped(raw, type) {
+    const trimmed = raw.trim();
+    // Empty cells map to `null` for most types and the empty string for
+    // `string` - this is the only case where typed import returns a
+    // null. Validator step is the right place to insist on "required".
+    if (trimmed === '') {
+        if (type === 'string')
+            return { ok: true, value: '' };
+        return { ok: true, value: null };
+    }
+    switch (type) {
+        case 'string':
+            return { ok: true, value: trimmed };
+        case 'boolean': {
+            const low = trimmed.toLowerCase();
+            if (low === 'true' || low === '1' || low === 'yes' || low === 'y')
+                return { ok: true, value: true };
+            if (low === 'false' || low === '0' || low === 'no' || low === 'n')
+                return { ok: true, value: false };
+            return { ok: false, message: `not a boolean: ${trimmed}` };
+        }
+        case 'number': {
+            const stripped = trimmed.replace(/[$,\s]/g, '');
+            const n = Number(stripped);
+            if (!Number.isFinite(n))
+                return { ok: false, message: `not a number: ${trimmed}` };
+            return { ok: true, value: n };
+        }
+        case 'integer': {
+            const stripped = trimmed.replace(/[$,\s]/g, '');
+            const n = Number(stripped);
+            if (!Number.isFinite(n) || !Number.isInteger(n)) {
+                return { ok: false, message: `not an integer: ${trimmed}` };
+            }
+            return { ok: true, value: n };
+        }
+        case 'date': {
+            // Accept ISO dates and a handful of common day-first / month-first
+            // shapes. Returns ISO yyyy-mm-dd.
+            const iso = trimmed.match(/^(\d{4})-(\d{2})-(\d{2})/);
+            if (iso)
+                return { ok: true, value: `${iso[1]}-${iso[2]}-${iso[3]}` };
+            // mm/dd/yyyy or dd/mm/yyyy - we don't try to disambiguate; the
+            // demo can declare the locale via its own validator if it cares.
+            const slash = trimmed.match(/^(\d{1,2})[/-](\d{1,2})[/-](\d{4})/);
+            if (slash) {
+                const [, a, b, y] = slash;
+                // Default to mm/dd/yyyy because it's the dominant locale where
+                // Excel exports without an explicit ISO format. Consumers
+                // wanting EU-style can pre-normalise the file.
+                return { ok: true, value: `${y}-${a.padStart(2, '0')}-${b.padStart(2, '0')}` };
+            }
+            const parsed = Date.parse(trimmed);
+            if (!Number.isNaN(parsed)) {
+                return { ok: true, value: new Date(parsed).toISOString().slice(0, 10) };
+            }
+            return { ok: false, message: `not a date: ${trimmed}` };
+        }
+        case 'datetime': {
+            // Accept anything Date.parse handles.
+            const parsed = Date.parse(trimmed);
+            if (Number.isNaN(parsed))
+                return { ok: false, message: `not a datetime: ${trimmed}` };
+            return { ok: true, value: new Date(parsed).toISOString().slice(0, 19) };
+        }
+        case 'json': {
+            try {
+                return { ok: true, value: JSON.parse(trimmed) };
+            }
+            catch {
+                return { ok: false, message: `not valid JSON: ${trimmed.slice(0, 30)}...` };
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Parse-once + map, so a UI (SvImportDialog) can read a file ONCE and then
+// re-map / re-validate as the user tweaks the column mapping without paying
+// the parse (or unzip, for xlsx) cost on every keystroke.
+// ---------------------------------------------------------------------------
+/**
+ * Read a file (or inline text) into a raw `string[][]` matrix - header row
+ * first - without any mapping, coercion, or validation. The cheap half of
+ * `importData`: parse the bytes once, then feed the matrix to
+ * `mapImportMatrix` as many times as the mapping UI needs.
+ */
+export async function readImportMatrix(file, format = 'auto', opts = {}) {
+    if (opts.signal?.aborted)
+        throw abortError();
+    // Guard the byte size BEFORE reading, so an oversized upload never lands
+    // in memory.
+    if (opts.maxBytes != null && file instanceof Blob && file.size > opts.maxBytes) {
+        throw new Error(`@svgrid/enterprise: file is ${file.size.toLocaleString()} bytes, ` +
+            `over the ${opts.maxBytes.toLocaleString()}-byte import limit.`);
+    }
+    const fmt = sniffFormat(file, format);
+    let matrix;
+    if (fmt === 'xlsx') {
+        if (typeof file === 'string') {
+            throw new Error('@svgrid/enterprise: xlsx import expects a File or Blob, not a string. ' +
+                'Use format: "csv" or "tsv" for inline text.');
+        }
+        matrix = await parseXlsx(file);
+    }
+    else if (fmt === 'json') {
+        const text = typeof file === 'string' ? file : await readText(file, opts.encoding);
+        matrix = jsonToMatrix(text);
+    }
+    else {
+        const sep = fmt === 'tsv' ? '\t' : ',';
+        const text = typeof file === 'string' ? file : await readText(file, opts.encoding);
+        matrix = parseDelimited(text, sep);
+    }
+    if (opts.signal?.aborted)
+        throw abortError();
+    return { format: fmt, matrix };
+}
+/** Run the validator over built rows, capping + flagging truncation. */
+function applyValidator(rows, errors, validator, maxErrors, startIndex = 0) {
+    if (!validator)
+        return false;
+    let truncated = false;
+    for (let i = startIndex; i < rows.length; i += 1) {
+        const errs = validator(rows[i], i);
+        if (errs.length) {
+            const mapped = errs.map((e) => ({ rowIndex: i, field: e.field, message: e.message }));
+            if (collectErrors(errors, mapped, maxErrors)) {
+                truncated = true;
+                break;
+            }
+        }
+    }
+    return truncated;
+}
+/**
+ * Apply a column map + declared types + validator to an already-parsed
+ * matrix. The pure, synchronous half of `importData` - no I/O, no license
+ * gate - so a preview UI can call it on every mapping change. For very large
+ * files prefer `mapImportMatrixAsync`, which yields to keep the UI live.
+ */
+export function mapImportMatrix(matrix, opts = {}) {
+    const built = buildRecords(matrix, opts.columnMap, opts.columnTypes, opts.maxErrors);
+    const errors = built.errors;
+    // Type-coercion errors come first; the validator runs on the rows we
+    // managed to build, so its errors share the same `rowIndex` basis.
+    let errorsTruncated = built.errorsTruncated;
+    if (applyValidator(built.rows, errors, opts.validator, opts.maxErrors))
+        errorsTruncated = true;
+    let rows = built.rows;
+    let deduped = 0;
+    if (opts.dedupeBy) {
+        const r = dedupeRows(rows, opts.dedupeBy);
+        rows = r.rows;
+        deduped = r.deduped;
+    }
+    return {
+        headers: built.headers,
+        rows,
+        errors,
+        skipped: built.skipped,
+        total: matrix.length > 0 ? matrix.length - 1 : 0,
+        errorsTruncated,
+        deduped,
+    };
+}
+/**
+ * Non-blocking sibling of `mapImportMatrix`: yields to the event loop every
+ * few thousand rows and reports progress, so mapping a 100k-row file never
+ * freezes the tab. Honors an AbortSignal. Used by `importData` and the
+ * SvImportDialog preview.
+ */
+export async function mapImportMatrixAsync(matrix, opts = {}) {
+    const headers = (matrix[0] ?? []).map((h) => h.trim());
+    const fields = computeFields(headers, opts.columnMap);
+    const dataRows = matrix.slice(1);
+    const total = dataRows.length;
+    const chunk = Math.max(1, opts.chunkSize ?? 5000);
+    const rows = [];
+    const errors = [];
+    let skipped = 0;
+    let outRowIndex = 0;
+    let errorsTruncated = false;
+    for (let i = 0; i < total; i += 1) {
+        if (opts.signal?.aborted)
+            throw abortError();
+        const cells = dataRows[i];
+        if (isBlankRow(cells)) {
+            skipped += 1;
+        }
+        else {
+            const { rec, errors: rowErrs } = buildRecord(cells, headers.length, fields, opts.columnTypes, outRowIndex);
+            if (rowErrs.length && collectErrors(errors, rowErrs, opts.maxErrors))
+                errorsTruncated = true;
+            rows.push(rec);
+            outRowIndex += 1;
+        }
+        if ((i + 1) % chunk === 0) {
+            opts.onProgress?.({ phase: 'map', ratio: total ? (i + 1) / total : 1, done: i + 1, total });
+            await nextTick();
+        }
+    }
+    if (applyValidator(rows, errors, opts.validator, opts.maxErrors))
+        errorsTruncated = true;
+    let finalRows = rows;
+    let deduped = 0;
+    if (opts.dedupeBy) {
+        const r = dedupeRows(rows, opts.dedupeBy);
+        finalRows = r.rows;
+        deduped = r.deduped;
+    }
+    opts.onProgress?.({ phase: 'map', ratio: 1, done: total, total });
+    return {
+        headers,
+        rows: finalRows,
+        errors,
+        skipped,
+        total: matrix.length > 0 ? matrix.length - 1 : 0,
+        errorsTruncated,
+        deduped,
+    };
+}
+/** Fold a header / field down to letters + digits so "Unit Price", "unit_price"
+ *  and "UnitPrice" all collapse to the same key. */
+function normalizeHeader(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+/**
+ * Fuzzy-match each source header to one of the grid's columns (by header
+ * label first, then field name) and return a `source header -> target
+ * field` map. Headers with no confident match are left OUT of the map, so
+ * `buildRecords` falls back to its snake_case default for them.
+ */
+export function autoMapColumns(headers, columns) {
+    const byKey = new Map();
+    for (const c of columns) {
+        const field = c.field ?? c.header;
+        if (!field)
+            continue;
+        // Field name is the strongest signal, so register header first then let
+        // the field key overwrite on a collision.
+        if (c.header)
+            byKey.set(normalizeHeader(c.header), field);
+        if (c.field)
+            byKey.set(normalizeHeader(c.field), c.field);
+    }
+    const map = {};
+    for (const h of headers) {
+        const hit = byKey.get(normalizeHeader(h));
+        if (hit)
+            map[h] = hit;
+    }
+    return map;
+}
+/**
+ * Infer strict import types from each grid column's `format`, so a currency
+ * / number / percent column parses "$1,234" -> 1234 and a date column parses
+ * "2026-03-04" -> an ISO date. Columns with no informative format are left
+ * out (best-effort coercion applies).
+ */
+export function inferImportColumnTypes(columns) {
+    const types = {};
+    for (const c of columns) {
+        if (!c.field)
+            continue;
+        const t = c.format?.type;
+        if (t === 'number' || t === 'currency' || t === 'percent')
+            types[c.field] = 'number';
+        else if (t === 'date')
+            types[c.field] = 'date';
+        else if (t === 'datetime')
+            types[c.field] = 'datetime';
+    }
+    return types;
+}
+// ---------------------------------------------------------------------------
+// Public entry point
+// ---------------------------------------------------------------------------
+/**
+ * Read a file (or inline text), parse, optionally validate + commit. The
+ * sister function of `exportGrid`.
+ */
+export async function importData(api, opts) {
+    assertEnterpriseLicensed('Import');
+    const { format, matrix } = await readImportMatrix(opts.file, opts.format ?? 'auto', {
+        maxBytes: opts.maxBytes,
+        encoding: opts.encoding,
+        signal: opts.signal,
+    });
+    // Enforce the row cap before we do the O(rows) mapping work: either reject
+    // outright, or truncate to the first maxRows and flag it.
+    const dataCount = matrix.length > 0 ? matrix.length - 1 : 0;
+    let workMatrix = matrix;
+    let truncated = false;
+    if (opts.maxRows != null && dataCount > opts.maxRows) {
+        if (opts.overLimit === 'truncate') {
+            workMatrix = matrix.slice(0, opts.maxRows + 1); // header + first maxRows
+            truncated = true;
+        }
+        else {
+            throw new Error(`@svgrid/enterprise: import has ${dataCount.toLocaleString()} rows, ` +
+                `over the maxRows limit of ${opts.maxRows.toLocaleString()}.`);
+        }
+    }
+    // Grid-aware auto-mapping: derive the columnMap + columnTypes from the
+    // grid's own columns, but let anything the caller passed win.
+    let columnMap = opts.columnMap;
+    let columnTypes = opts.columnTypes;
+    if (opts.autoMap) {
+        const gridCols = api.getColumns();
+        const headers = (workMatrix[0] ?? []).map((h) => h.trim());
+        columnMap = { ...autoMapColumns(headers, gridCols), ...(opts.columnMap ?? {}) };
+        columnTypes = { ...inferImportColumnTypes(gridCols), ...(opts.columnTypes ?? {}) };
+    }
+    const { headers, rows, errors, skipped, errorsTruncated, deduped } = await mapImportMatrixAsync(workMatrix, {
+        columnMap,
+        columnTypes,
+        validator: opts.validator,
+        maxErrors: opts.maxErrors,
+        dedupeBy: opts.dedupeBy,
+        signal: opts.signal,
+        onProgress: opts.onProgress,
+    });
+    if (opts.commit && errors.length === 0 && rows.length > 0) {
+        api.addRows(rows, opts.commitAt ?? 'bottom');
+    }
+    // `total` reports the ORIGINAL source row count even when truncated, so the
+    // caller can say "imported X of Y".
+    return { headers, rows, errors, skipped, total: dataCount, format, errorsTruncated, deduped, truncated };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+async function readText(blob, encoding) {
+    // The default UTF-8 path is fastest; a declared non-UTF-8 encoding (legacy
+    // Windows-1252 CSVs, etc.) routes through TextDecoder.
+    if (encoding && encoding.toLowerCase() !== 'utf-8' && encoding.toLowerCase() !== 'utf8') {
+        const buf = await blob.arrayBuffer();
+        return new TextDecoder(encoding).decode(buf);
+    }
+    return blob.text();
+}
+/** Convert JSON text containing an array of objects into a `string[][]`
+ *  matrix shaped like CSV: header row, then one row per record. */
+function jsonToMatrix(text) {
+    const parsed = JSON.parse(text);
+    if (!Array.isArray(parsed)) {
+        throw new Error('@svgrid/enterprise: JSON import expects a top-level array');
+    }
+    if (parsed.length === 0)
+        return [];
+    // Collect the union of keys across the first ~50 records so we don't
+    // miss a column present only on later rows.
+    const headers = [];
+    const seen = new Set();
+    const sample = parsed.slice(0, 50);
+    for (const r of sample) {
+        if (r && typeof r === 'object') {
+            for (const k of Object.keys(r)) {
+                if (!seen.has(k)) {
+                    seen.add(k);
+                    headers.push(k);
+                }
+            }
+        }
+    }
+    const rows = [headers.slice()];
+    for (const r of parsed) {
+        const row = [];
+        for (const h of headers) {
+            const v = r?.[h];
+            if (v == null)
+                row.push('');
+            else if (typeof v === 'object')
+                row.push(JSON.stringify(v));
+            else
+                row.push(String(v));
+        }
+        rows.push(row);
+    }
+    return rows;
+}