@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/business/import-core.js

@@ -0,0 +1,281 @@
+/**
+ * Import helpers — React-free and worker-safe: encoding / delimiter sniffing, CSV and XLSX
+ * reading (lazy), locale-folded header auto-mapping, locale-aware cell parsing and row
+ * validation. `papaparse` and `read-excel-file` are loaded only when a file is read.
+ */
+import { parseDecimal } from "../format/core.js";
+import { foldText } from "../lib/text.js";
+import { isValidIban } from "../locale-data/core/iban.js";
+/** Turkish letters in Windows-1254 that are something else in Windows-1252. */
+const TR_1254 = new Set([0xd0, 0xf0, 0xdd, 0xfd, 0xde, 0xfe]);
+/**
+ * Guesses encoding and delimiter from the first bytes. Invalid UTF-8 with Turkish code points
+ * → Windows-1254 (Excel on Turkish Windows), else Windows-1252.
+ */
+export function sniffCsv(bytes) {
+    const hasBom = bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf;
+    let encoding = "utf-8";
+    if (!hasBom) {
+        try {
+            new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, 64 * 1024));
+        }
+        catch {
+            let tr = 0;
+            for (let i = 0; i < Math.min(bytes.length, 64 * 1024); i++)
+                if (TR_1254.has(bytes[i]))
+                    tr++;
+            encoding = tr > 0 ? "windows-1254" : "windows-1252";
+        }
+    }
+    const head = decodeText(bytes.subarray(0, 16 * 1024), encoding);
+    return { encoding, delimiter: sniffDelimiter(head), hasBom };
+}
+/** Bytes → text in an encoding (drops a UTF-8 BOM). */
+export function decodeText(bytes, encoding) {
+    let text;
+    try {
+        text = new TextDecoder(encoding).decode(bytes);
+    }
+    catch {
+        text = new TextDecoder("utf-8").decode(bytes);
+    }
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+/** The delimiter that splits the first lines most consistently. */
+export function sniffDelimiter(text) {
+    const lines = text.split(/\r?\n/).filter((l) => l.trim()).slice(0, 8);
+    const score = (d) => {
+        const counts = lines.map((l) => {
+            let n = 0;
+            let q = false;
+            for (const ch of l) {
+                if (ch === '"')
+                    q = !q;
+                else if (ch === d && !q)
+                    n++;
+            }
+            return n;
+        });
+        if (!counts.length || counts[0] === 0)
+            return 0;
+        const same = counts.filter((c) => c === counts[0]).length;
+        return counts[0] * (same / counts.length);
+    };
+    const candidates = [";", ",", "\t"];
+    return candidates.reduce((best, d) => (score(d) > score(best) ? d : best), ",");
+}
+/** True when decoded text has replacement characters or typical mojibake ("ç", "ı"). */
+export function looksGarbled(text) {
+    return /�/.test(text) || /Ã[\u0080-¿§¶¼]|Ä[±°ž]|Å[Ÿž]/.test(text.slice(0, 20000));
+}
+/** CSV text → rows (lazy `papaparse`). */
+export async function parseCsv(text, delimiter) {
+    const Papa = (await import("papaparse")).default;
+    const res = Papa.parse(text, { delimiter: delimiter ?? "", skipEmptyLines: "greedy" });
+    return res.data.map((r) => r.map((c) => (c ?? "").trim()));
+}
+function cellToString(v) {
+    if (v == null)
+        return "";
+    if (v instanceof Date) {
+        const p = (n) => String(n).padStart(2, "0");
+        return `${v.getUTCFullYear()}-${p(v.getUTCMonth() + 1)}-${p(v.getUTCDate())}`;
+    }
+    return String(v).trim();
+}
+/** An XLSX file → sheets of string rows (lazy `read-excel-file`). */
+export async function readXlsx(file) {
+    const mod = await import("read-excel-file/browser");
+    const sheets = await mod.default(file);
+    return sheets.map((s) => ({ name: s.sheet, rows: s.data.map((r) => r.map(cellToString)) }));
+}
+const norm = (s, locale) => foldText(s, locale).replace(/[^\p{L}\p{N}]+/gu, "");
+/**
+ * Maps file headers to fields: exact folded match on id, label or aliases first, then
+ * containment. Locale folding makes "E-posta" ≈ "eposta" ≈ "EPOSTA". Each field is used once.
+ */
+export function autoMap(headers, fields, locale = "en-US") {
+    const out = {};
+    const used = new Set();
+    const names = fields.map((f) => ({ id: f.id, keys: [f.id, f.label, ...(f.aliases ?? [])].map((k) => norm(k, locale)).filter(Boolean) }));
+    headers.forEach((h, i) => {
+        const n = norm(h, locale);
+        const exact = names.find((f) => !used.has(f.id) && f.keys.includes(n));
+        if (exact && n) {
+            out[i] = exact.id;
+            used.add(exact.id);
+        }
+        else
+            out[i] = null;
+    });
+    headers.forEach((h, i) => {
+        if (out[i])
+            return;
+        const n = norm(h, locale);
+        if (n.length < 3)
+            return;
+        const loose = names.find((f) => !used.has(f.id) && f.keys.some((k) => k.length >= 3 && (n.includes(k) || k.includes(n))));
+        if (loose) {
+            out[i] = loose.id;
+            used.add(loose.id);
+        }
+    });
+    return out;
+}
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/;
+const TRUE = new Set(["true", "yes", "y", "1", "x", "evet", "e", "var", "on"]);
+const FALSE = new Set(["false", "no", "n", "0", "hayir", "h", "yok", "off", ""]);
+export const importCellMessages = {
+    number: "Not a number",
+    date: "Not a date (use YYYY-MM-DD)",
+    boolean: "Use yes or no",
+    enum: "Not one of: {options}",
+    email: "Not an email address",
+    phone: "Not a phone number",
+    iban: "IBAN check digits don't match",
+    required: "Required",
+    duplicate: "Duplicate of row {row}",
+};
+const pad = (n) => String(n).padStart(2, "0");
+function isoFromParts(y, m, d) {
+    if (m < 1 || m > 12 || d < 1 || d > 31 || y < 1000)
+        return null;
+    const dt = new Date(Date.UTC(y, m - 1, d));
+    if (dt.getUTCMonth() !== m - 1)
+        return null;
+    return `${y}-${pad(m)}-${pad(d)}`;
+}
+/** "2026-11-10", "10.11.2026", "10/11/2026" (month first for en-US), Excel serials → "YYYY-MM-DD". */
+export function parseDateCell(v, locale = "en-US") {
+    const s = v.trim();
+    let m = /^(\d{4})-(\d{1,2})-(\d{1,2})(?:[T ].*)?$/.exec(s);
+    if (m)
+        return isoFromParts(+m[1], +m[2], +m[3]);
+    m = /^(\d{1,2})[./-](\d{1,2})[./-](\d{2,4})$/.exec(s);
+    if (m) {
+        const y = m[3].length === 2 ? 2000 + +m[3] : +m[3];
+        const monthFirst = /^en-(US|PH)$/i.test(locale) || (+m[2] > 12 && +m[1] <= 12);
+        return monthFirst ? isoFromParts(y, +m[1], +m[2]) : isoFromParts(y, +m[2], +m[1]);
+    }
+    if (/^\d{4,5}(\.\d+)?$/.test(s)) {
+        const serial = Math.floor(Number(s));
+        if (serial > 0 && serial < 80000) {
+            const dt = new Date(Date.UTC(1899, 11, 30) + serial * 86400000);
+            return `${dt.getUTCFullYear()}-${pad(dt.getUTCMonth() + 1)}-${pad(dt.getUTCDate())}`;
+        }
+    }
+    return null;
+}
+/** One cell → typed value or a message. Number and date formats follow the file's locale. */
+export function parseCell(v, field, locale = "en-US", messages = importCellMessages) {
+    const s = v.trim();
+    if (!s)
+        return { value: field.type === "boolean" ? false : null };
+    switch (field.type) {
+        case "number": {
+            const d = parseDecimal(s, locale);
+            return d == null ? { value: null, error: messages.number } : { value: Number(d) };
+        }
+        case "money": {
+            const d = parseDecimal(s, locale);
+            return d == null ? { value: null, error: messages.number } : { value: d };
+        }
+        case "date": {
+            const d = parseDateCell(s, locale);
+            return d ? { value: d } : { value: null, error: messages.date };
+        }
+        case "boolean": {
+            const f = foldText(s, locale);
+            if (TRUE.has(f))
+                return { value: true };
+            if (FALSE.has(f))
+                return { value: false };
+            return { value: null, error: messages.boolean };
+        }
+        case "enum": {
+            const f = norm(s, locale);
+            const opt = field.options?.find((o) => [o.value, o.label, ...(o.aliases ?? [])].some((k) => norm(k, locale) === f));
+            return opt ? { value: opt.value } : { value: null, error: messages.enum.replace("{options}", (field.options ?? []).map((o) => o.label).join(", ")) };
+        }
+        case "email":
+            return EMAIL.test(s) ? { value: s.toLowerCase() } : { value: null, error: messages.email };
+        case "phone": {
+            const digits = s.replace(/[^\d+]/g, "");
+            const count = digits.replace(/\D/g, "").length;
+            return count >= 7 && count <= 15 ? { value: digits } : { value: null, error: messages.phone };
+        }
+        case "iban":
+            return isValidIban(s) ? { value: s.replace(/\s+/g, "").toUpperCase() } : { value: null, error: messages.iban };
+        default:
+            return { value: s };
+    }
+}
+/** Mapped raw rows → typed values, errors and warnings per field. */
+export function validateImport(rows, mapping, fields, options = {}) {
+    const { locale = "en-US", dedupeKeys, messages = importCellMessages } = options;
+    const byId = new Map(fields.map((f) => [f.id, f]));
+    const seen = new Map();
+    return rows.map((cells, i) => {
+        const raw = {};
+        for (const [col, id] of Object.entries(mapping))
+            if (id)
+                raw[id] = cells[Number(col)] ?? "";
+        return validateImportRow(raw, i + 1, byId, { locale, messages, dedupeKeys, seen });
+    });
+}
+/** Re-validates one row after an inline fix. */
+export function validateImportRow(raw, row, fields, o = {}) {
+    const byId = fields instanceof Map ? fields : new Map(fields.map((f) => [f.id, f]));
+    const locale = o.locale ?? "en-US";
+    const messages = o.messages ?? importCellMessages;
+    const values = {};
+    const errors = {};
+    const warnings = {};
+    for (const f of byId.values()) {
+        const v = raw[f.id] ?? "";
+        if (!v.trim()) {
+            if (f.required)
+                errors[f.id] = messages.required;
+            values[f.id] = f.type === "boolean" ? false : null;
+            continue;
+        }
+        const p = parseCell(v, f, locale, messages);
+        if (p.error)
+            errors[f.id] = p.error;
+        else {
+            const custom = f.validate?.(v, raw);
+            if (custom)
+                errors[f.id] = custom;
+            values[f.id] = f.normalize ? f.normalize(String(p.value)) : p.value;
+        }
+        if (p.warning)
+            warnings[f.id] = p.warning;
+    }
+    if (o.dedupeKeys?.length && o.seen) {
+        const key = o.dedupeKeys.map((k) => foldText(String(raw[k] ?? ""), locale)).join("\u0000");
+        if (key.replace(/\u0000/g, "")) {
+            const first = o.seen.get(key);
+            if (first !== undefined)
+                warnings[o.dedupeKeys[0]] = messages.duplicate.replace("{row}", String(first));
+            else
+                o.seen.set(key, row);
+        }
+    }
+    return { row, raw, values, errors, warnings };
+}
+/** Applies a saved template to the current headers. */
+export function applyTemplate(headers, template, locale = "en-US") {
+    const out = {};
+    headers.forEach((h, i) => (out[i] = template.mapping[norm(h, locale)] ?? null));
+    return out;
+}
+/** The current mapping as a template body. */
+export function mappingToTemplate(headers, mapping, locale = "en-US") {
+    const out = {};
+    headers.forEach((h, i) => {
+        const id = mapping[i];
+        if (id)
+            out[norm(h, locale)] = id;
+    });
+    return out;
+}

package/dist/business/import-wizard.d.ts

@@ -0,0 +1,186 @@
+import * as React from "react";
+import { type LabelFn } from "../lib/labels.js";
+import { importCellMessages, type ImportField, type ImportRowResult, type MappingTemplate } from "./import-core.js";
+export declare const importWizardLabels: {
+    stepUpload: string;
+    stepUploadHint: string;
+    stepMap: string;
+    stepMapHint: string;
+    stepReview: string;
+    stepReviewHint: string;
+    stepImport: string;
+    stepImportHint: string;
+    sample: string;
+    parsing: string;
+    parseFailed: string;
+    noFile: string;
+    noRows: string;
+    tooMany: string;
+    fileSummary: string;
+    encoding: string;
+    delimiter: string;
+    sheet: string;
+    header: string;
+    fileLocale: string;
+    fileLocaleHint: string;
+    garbled: string;
+    garbledBody: string;
+    tryEncoding: string;
+    column: string;
+    sampleValue: string;
+    field: string;
+    mapsTo: string;
+    ignore: string;
+    required: string;
+    unmapped: string;
+    mappedCount: string;
+    template: string;
+    applyTemplate: string;
+    saveTemplate: string;
+    templateName: string;
+    templateSaved: string;
+    templatePlaceholder: string;
+    encUtf8: string;
+    enc1254: string;
+    enc1252: string;
+    delimComma: string;
+    delimSemicolon: string;
+    delimTab: string;
+    counts: string;
+    onlyErrors: string;
+    nextError: string;
+    showing: string;
+    row: string;
+    fix: string;
+    allInvalid: string;
+    strategy: string;
+    skip: string;
+    skipHint: string;
+    update: string;
+    updateHint: string;
+    create: string;
+    createHint: string;
+    dryRun: string;
+    dryRunHint: string;
+    willImport: string;
+    start: string;
+    startDry: string;
+    importing: string;
+    cancel: string;
+    cancelled: string;
+    leave: string;
+    reportTitle: string;
+    reportDry: string;
+    reportPartial: string;
+    reportSummary: string;
+    failedRows: string;
+    error: string;
+    downloadFailed: string;
+    again: string;
+    done: string;
+};
+export type ImportWizardLabels = typeof importWizardLabels;
+export type ImportStrategy = "skip" | "update" | "create";
+export interface ImportContext {
+    signal: AbortSignal;
+    /** Report rows written so far within this chunk. */
+    onProgress: (done: number) => void;
+    strategy: ImportStrategy;
+    dryRun: boolean;
+    /** Index of the chunk's first row among all valid rows. */
+    offset: number;
+}
+export interface ImportResult {
+    ok: number;
+    /** `row` = 0-based index within the rows passed in. */
+    failed: {
+        row: number;
+        error: string;
+    }[];
+}
+export interface ImportWizardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+    fields: ImportField[];
+    /** Fields that identify an existing record (enables the duplicate strategy). */
+    dedupeKeys?: string[];
+    /** Default 50,000. */
+    maxRows?: number;
+    /** Bytes. Default 20 MB. */
+    maxSize?: number;
+    /** Rows per `onImport` call. Default 200. */
+    chunkSize?: number;
+    /** Called per chunk with typed values. */
+    onImport: (rows: Record<string, unknown>[], ctx: ImportContext) => Promise<ImportResult>;
+    templates?: {
+        list: () => Promise<MappingTemplate[]>;
+        save: (t: MappingTemplate) => Promise<void>;
+    };
+    sampleFile?: {
+        name: string;
+        href: string;
+    };
+    /** Locales offered for number / date parsing. Default: UI locale, en-US, en-GB, tr-TR, de-DE. */
+    fileLocales?: {
+        value: string;
+        label: string;
+    }[];
+    /** After the report: "Done". */
+    onDone?: (report: ImportReport) => void;
+    /** Rows shown in the review table. Default 200. */
+    previewLimit?: number;
+    labels?: Partial<ImportWizardLabels>;
+}
+export interface ImportReport {
+    ok: number;
+    failed: {
+        row: number;
+        error: string;
+        raw: Record<string, string>;
+    }[];
+    skipped: number;
+    dryRun: boolean;
+    cancelled: boolean;
+}
+/**
+ * Imports CSV / XLSX into any collection: upload (encoding, delimiter, sheet, header) → column
+ * mapping (auto + templates) → review with inline fixes → duplicate strategy, dry run and a
+ * chunked, cancellable import → report with a failed-rows download. Built on Multi-step form.
+ *
+ * ```tsx
+ * <ImportWizard fields={contactFields} dedupeKeys={["email"]} onImport={(rows, { signal }) => api.contacts.bulk(rows, { signal })} />
+ * ```
+ */
+export declare const ImportWizard: React.ForwardRefExoticComponent<ImportWizardProps & React.RefAttributes<HTMLDivElement>>;
+export interface ImportMappingProps {
+    headers: string[];
+    /** First data row, shown as a sample. */
+    sample?: string[];
+    fields: ImportField[];
+    mapping: Record<number, string | null>;
+    onMappingChange: (m: Record<number, string | null>) => void;
+    toolbar?: React.ReactNode;
+    labels?: Partial<ImportWizardLabels>;
+}
+/** Column → field mapping: one labelled Select per file column. Usable alone. */
+export declare function ImportMapping({ headers, sample, fields, mapping, onMappingChange, toolbar, labels, t: tProp }: ImportMappingProps & {
+    t?: LabelFn<ImportWizardLabels>;
+}): React.JSX.Element;
+export interface ImportReviewProps {
+    results: ImportRowResult[];
+    /** Mapped fields, as table columns. */
+    fields: ImportField[];
+    onlyErrors: boolean;
+    onOnlyErrorsChange: (v: boolean) => void;
+    errorCount: number;
+    warningCount: number;
+    errorRowCount: number;
+    /** Inline fix: index into `results`. */
+    onFix?: (index: number, field: string, value: string) => void;
+    onNextError?: () => void;
+    limit?: number;
+    labels?: Partial<ImportWizardLabels>;
+}
+/** Validation preview: counts, an "only problems" filter and editable error cells (F8 = next error). */
+export declare function ImportReview({ results, fields, onlyErrors, onOnlyErrorsChange, errorCount, warningCount, errorRowCount, onFix, onNextError, limit, labels, t: tProp }: ImportReviewProps & {
+    t?: LabelFn<ImportWizardLabels>;
+}): React.JSX.Element;
+export { importCellMessages };