@mono-lit/helper 0.0.0-stage → 0.0.1

package/dist/src/export/helpers.d.ts

@@ -0,0 +1,6 @@
+import { MonoExportFormatOptions, MonoExportHelper } from './types';
+/**
+ * Build the built-in helper map for one render. Bound to `formatting` so
+ * locale/currency choices apply consistently across every helper.
+ */
+export declare function createHelpers(formatting?: MonoExportFormatOptions): Record<string, MonoExportHelper>;

package/dist/src/export/index.d.ts

@@ -0,0 +1,13 @@
+/// <reference path="../../vue.d.ts" />
+import { MonoExportOptions, MonoExportResult } from './types';
+export type { MonoExportColumn, MonoExportFormat, MonoExportFormatOptions, MonoExportHelper, MonoExportOptions, MonoExportResult, MonoExportStyle, MonoExportStyles, } from './types';
+export { DEFAULT_STYLES } from './styles';
+export type { MonoExportDirective } from './sentinel';
+/**
+ * Render a Markdown report template.
+ *
+ * When `fileName` is given its extension selects the renderer and the file
+ * downloads automatically (pass `download: false` to suppress that). Without
+ * one, nothing is written — you just get the result object.
+ */
+export declare function exportTable(options: MonoExportOptions): Promise<MonoExportResult>;

package/dist/src/export/markdown.d.ts

@@ -0,0 +1,52 @@
+import { Root, RootContent, PhrasingContent } from 'mdast';
+import { MonoExportDirective } from './sentinel';
+export type { Root, RootContent };
+/**
+ * Parse rendered Markdown into an mdast tree, with GFM tables enabled.
+ *
+ * ── Why the table body does not go through remark ────────────────────────────
+ *
+ * remark-gfm's table parsing degrades super-linearly on the tables a REPORT
+ * produces. Measured on a 13-column export: 500 rows took 3.8s, 1 000 took 13.5s
+ * and 2 000 took 86s — doubling the rows more than quadrupled the time, and a
+ * 7 000-row export never finished at all. It is the whole of the export's cost;
+ * ExcelJS serialises the same workbook in ~200ms.
+ *
+ * The markdown a template produces is not arbitrary CommonMark, though: it is
+ * machine-generated and line-regular, one row per line, and the report helpers
+ * already escape any `|` inside a value (see `escapeCellText`). So table blocks
+ * are read line-by-line here — linear, and no micromark involved — while every
+ * other construct (headings, paragraphs, lists) is still handed to remark, which
+ * is both correct and cheap because those parts are tiny.
+ *
+ * Inline fidelity is kept per cell: a cell containing markdown syntax
+ * (`**bold**`, `[text](url)`, an image) is still parsed by remark, so links and
+ * emphasis behave exactly as before. Only plain cells take the fast path.
+ */
+export declare function parseMarkdown(md: string): Root;
+/** Inline formatting collected while flattening a run of phrasing content. */
+export interface InlineText {
+    text: string;
+    bold: boolean;
+    italic: boolean;
+    code: boolean;
+    strike: boolean;
+    /** Directives found anywhere in the run. */
+    directives: MonoExportDirective[];
+    /** Images found in the run (from `![alt](src)` — `{{image}}` is a directive). */
+    images: Array<{
+        url: string;
+        alt?: string;
+    }>;
+    /** The first link URL in the run, if any. */
+    link?: string;
+}
+/**
+ * Flatten phrasing content (the inline children of a cell, heading, paragraph
+ * or list item) into one string plus the formatting that applies to it.
+ *
+ * Excel styles a cell as a whole rather than per character run, so mixed
+ * emphasis collapses to "was there any bold/italic in here" — matching what a
+ * report author actually expects from `| **Total** | 123 |`.
+ */
+export declare function flattenInline(nodes: readonly PhrasingContent[] | undefined): InlineText;

package/dist/src/export/resolve-data.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Turning live data sources in `options.data` into plain arrays.
+ *
+ * A template can only loop over an array, but the thing a consumer *has* is
+ * usually a devextreme DataSource. Rather than making everyone drain it by hand
+ * before every export, any DataSource-shaped value in `data` is drained here
+ * first — in chunks, honouring whatever filter / search / sort the source
+ * already carries — so the template just sees rows:
+ *
+ * ```ts
+ * data: { program: dataSourceProgramTransfer.value }
+ * ```
+ * ```hbs
+ * {{#each program}}| {{NoDokumen}} | {{currency TotalBudget}} |
+ * {{/each}}
+ * ```
+ */
+/**
+ * Replace every DataSource / store in `data`'s **top level** with its rows.
+ *
+ * Top-level only, deliberately: it's predictable, and a deep walk would mean
+ * inspecting every record of every array already in `data` — a real cost for a
+ * 10k-row export, to support a nesting nobody has asked for. A source nested
+ * deeper stays the caller's job (`await table.getData()` and pass the array).
+ *
+ * Sources are drained concurrently — several are independent queries, and a
+ * report with three of them shouldn't take three times as long.
+ */
+export declare function resolveExportData(data: Record<string, unknown> | undefined, options?: {
+    chunkSize?: number;
+}): Promise<Record<string, unknown>>;

package/dist/src/export/sentinel.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Sentinel directives — how presentation survives the trip through Markdown.
+ *
+ * Markdown has nowhere to hang "make this cell bold", "merge it across 4
+ * columns", or "this text reads `Rp 1.000.000` but Excel must store the number
+ * `1000000`". So the report helpers don't emit styling: they emit an invisible
+ * token next to their display text.
+ *
+ * The token is wrapped in two Unicode **private-use area** codepoints, which
+ * means:
+ * - remark parses it as ordinary text, so GFM table structure is untouched;
+ * - it can never collide with real content (no keyboard produces U+E000);
+ * - the Markdown renderer strips it, leaving the human-readable text;
+ * - the Excel renderer extracts it and applies the real formatting.
+ *
+ * The payload is JSON, **base64-encoded**. That is not paranoia: raw JSON does
+ * not survive the trip. Markdown unescapes backslash-escaped ASCII punctuation,
+ * so a number format like `"$"#,##0.00` — which JSON writes as `\"$\"#,##0.00`
+ * — comes back out of remark with the backslashes stripped, and `JSON.parse`
+ * then fails. Base64's alphabet (`A-Z a-z 0-9 + / =`) holds nothing Markdown
+ * rewrites, so the payload arrives byte-identical.
+ */
+/** Apply a named style to the cell (or block) the token sits in. */
+export interface StyleDirective {
+    k: 'style';
+    /** Named style, resolved against the merged style map. */
+    v: string;
+}
+/** Apply a named style to the entire row the token sits in. */
+export interface RowStyleDirective {
+    k: 'rowStyle';
+    v: string;
+}
+/** Merge the token's cell across `cols` columns / `rows` rows. */
+export interface MergeDirective {
+    k: 'merge';
+    cols?: number;
+    rows?: number;
+}
+/**
+ * Write an Excel formula into the token's cell. Placeholders are resolved at
+ * write time (the template can't know its own row number) — see
+ * `resolveFormula` in `excel/nodes.ts`.
+ */
+export interface FormulaDirective {
+    k: 'formula';
+    v: string;
+}
+/** Anchor an image at the token's cell. `v` is a data URL / base64 / http URL. */
+export interface ImageDirective {
+    k: 'image';
+    v: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * Carry the *raw* value behind formatted display text, so Excel gets a real
+ * number/date (summable, sortable, pivotable) while Markdown keeps the pretty
+ * string. `f` is an Excel number format.
+ */
+export interface ValueDirective {
+    k: 'val';
+    /** Raw numeric value. */
+    n?: number;
+    /** Raw date as an ISO string (JSON has no Date). */
+    d?: string;
+    /** Excel number format, e.g. `#,##0.00` or `yyyy-mm-dd`. */
+    f?: string;
+    /**
+     * The display text this value was emitted with. The renderer swaps in the raw
+     * value only when it matches the cell's *entire* text — otherwise a sentence
+     * like "Rate {{percent 0.155}} this quarter" would collapse to the bare
+     * number `0.155`, losing the prose around it.
+     */
+    t?: string;
+}
+export type MonoExportDirective = StyleDirective | RowStyleDirective | MergeDirective | FormulaDirective | ImageDirective | ValueDirective;
+/** Wrap a directive in its sentinel token, ready to be emitted by a helper. */
+export declare function encodeDirective(directive: MonoExportDirective): string;
+/** Whether a string contains at least one directive token. */
+export declare function hasDirectives(text: string): boolean;
+/**
+ * Split `text` into its visible text and the directives embedded in it.
+ * Malformed payloads are dropped rather than thrown — a broken token should
+ * never take down a whole report.
+ */
+export declare function extractDirectives(text: string): {
+    text: string;
+    directives: MonoExportDirective[];
+};
+/** Remove every directive token, leaving only the display text (Markdown output). */
+export declare function stripDirectives(text: string): string;
+/**
+ * Escape a value for safe interpolation into a GFM **table cell**. Directive
+ * tokens are skipped — they are base64 and must arrive byte-identical.
+ */
+export declare function escapeCellText(text: string): string;

package/dist/src/export/sheet-name.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Worksheet names, which Excel is fussier about than anything else in a
+ * workbook — and every rule below is one it enforces by refusing to open the
+ * file, not by degrading.
+ *
+ *   · at most 31 characters
+ *   · none of `* ? : \ / [ ]`
+ *   · cannot be empty
+ *   · cannot start or end with an apostrophe
+ *   · unique within the workbook, case-insensitively
+ *
+ * A name derived from user data — a document number like `TU/2026/001` — breaks
+ * three of those at once, so nothing may reach `addWorksheet` unsanitised.
+ */
+/**
+ * One name, made legal. Does NOT make it unique — that is
+ * {@link SheetNames.take}'s job, because uniqueness needs the whole workbook.
+ */
+export declare function sanitizeSheetName(raw: unknown, fallback?: string): string;
+/**
+ * Escape a name for use inside a reference like `#'Sheet'!A1`.
+ *
+ * The name is single-quoted there, so a literal apostrophe has to be doubled.
+ * {@link sanitizeSheetName} only strips apostrophes at the ends — one in the
+ * middle (`Bob's Data`) is legal and has to survive.
+ */
+export declare function escapeSheetRef(name: string): string;
+/** A reference to `A1` of `name`, ready to use as a hyperlink target. */
+export declare function sheetRef(name: string, cell?: string): string;
+/**
+ * The workbook's name registry.
+ *
+ * Deliberately the ONLY place a name is claimed. The implementation this feature
+ * is modelled on reserves a name up front and then dedupes a second time inside
+ * its writer against the same set — so the second call always collides with the
+ * reservation it just made, and every sheet in that workbook ends up suffixed
+ * ` (2)`. One registry, one `take()`, no second opinion.
+ */
+export declare class SheetNames {
+    /** Lower-cased claimed names: Excel's uniqueness is case-insensitive. */
+    private readonly used;
+    constructor(existing?: Iterable<string>);
+    /** Claim a legal, unique name derived from `raw`. */
+    take(raw: unknown, fallback?: string): string;
+}

package/dist/src/export/styles.d.ts

@@ -0,0 +1,33 @@
+import { MonoExportStyle, MonoExportStyles } from './types';
+/**
+ * Built-in styles. Consumers override individual keys via `options.styles`
+ * without having to redefine a whole style.
+ */
+export declare const DEFAULT_STYLES: MonoExportStyles;
+/** Merge user styles over the defaults, per style name (shallow, key by key). */
+export declare function mergeStyles(overrides?: MonoExportStyles): MonoExportStyles;
+/** Later styles win, key by key — used to layer row style → cell style. */
+export declare function combineStyles(...styles: Array<MonoExportStyle | undefined>): MonoExportStyle;
+/**
+ * ExcelJS wants `ARGB` without the `#`. Accepts `#rgb`, `#rrggbb` and
+ * `#aarrggbb`; anything already 8 hex digits is passed through.
+ */
+export declare function toArgb(color: string | undefined): string | undefined;
+/** One ExcelJS border edge. */
+interface ExcelBorderEdge {
+    style: 'thin';
+    color: {
+        argb: string;
+    };
+}
+/** The subset of ExcelJS cell style options this engine produces. */
+export interface ExcelCellStyle {
+    font?: Record<string, unknown>;
+    fill?: Record<string, unknown>;
+    alignment?: Record<string, unknown>;
+    border?: Record<string, ExcelBorderEdge>;
+    numFmt?: string;
+}
+/** Translate a semantic style into ExcelJS cell options. */
+export declare function toExcelStyle(style: MonoExportStyle): ExcelCellStyle;
+export {};

package/dist/src/export/template.d.ts

@@ -0,0 +1,10 @@
+import { MonoExportOptions } from './types';
+/**
+ * Render a report template to Markdown (still carrying directive tokens).
+ *
+ * `noEscape` is deliberate: Handlebars' default escaping is *HTML* escaping,
+ * which would turn `&` into `&` and `"` into `"` inside a spreadsheet
+ * cell. Table cells are protected instead by the `esc` helper, which the
+ * preprocessor injects only where it matters (see `expression.ts`).
+ */
+export declare function renderTemplate(options: Pick<MonoExportOptions, 'md' | 'data' | 'helpers' | 'partials' | 'formatting'>): Promise<string>;

package/dist/src/export/types.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Public types for the Markdown report engine.
+ *
+ * The engine deliberately exposes a *semantic* style vocabulary rather than raw
+ * ExcelJS objects: templates stay renderer-independent, so the same report can
+ * later be rendered to PDF/HTML/CSV by writing a new renderer instead of
+ * rewriting every template.
+ */
+/** Output formats the engine can render a template into. */
+export type MonoExportFormat = 'md' | 'xlsx';
+/**
+ * A named, renderer-independent style. Referenced from a template as
+ * `{{style "header"}}` and resolved against the merged style map.
+ */
+export interface MonoExportStyle {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    /** Font size in points. */
+    size?: number;
+    /** Font family (defaults to the workbook font). */
+    font?: string;
+    /** Text colour — `#rrggbb` or `#aarrggbb`. */
+    color?: string;
+    /** Solid background fill — `#rrggbb` or `#aarrggbb`. */
+    bg?: string;
+    align?: 'left' | 'center' | 'right';
+    valign?: 'top' | 'middle' | 'bottom';
+    /** Cell borders. `'bottom'` is handy for a header underline. */
+    border?: 'all' | 'bottom' | 'top' | 'outline' | 'none';
+    /** Border colour (defaults to a mid grey). */
+    borderColor?: string;
+    /** Excel number format, e.g. `#,##0.00`, `0.00%`, `yyyy-mm-dd`. */
+    numFmt?: string;
+    /** Wrap long text inside the cell. */
+    wrap?: boolean;
+    /** Indent level (each step ≈ 3 characters in Excel). */
+    indent?: number;
+    /** Row height in points, applied when the style lands on a whole row. */
+    height?: number;
+}
+/** The named-style map: `{ header: { bold: true }, … }`. */
+export type MonoExportStyles = Record<string, MonoExportStyle>;
+/** Per-column overrides for the generated worksheet. */
+export interface MonoExportColumn {
+    /** Column width in characters. Omit to auto-fit from content. */
+    width?: number;
+    /** Default number format for every cell in the column. */
+    numFmt?: string;
+}
+/** How `{{currency}}` / `{{number}}` / `{{date}}` format their display text. */
+export interface MonoExportFormatOptions {
+    /** BCP-47 locale for the display text (default: the runtime's locale). */
+    locale?: string;
+    /** ISO 4217 code used by `{{currency}}` (default `'USD'`). */
+    currency?: string;
+    /** Excel number format for `{{currency}}` (default: derived from `currency`). */
+    currencyFormat?: string;
+    /** Excel number format for `{{number}}` (default `'#,##0'`). */
+    numberFormat?: string;
+    /** Excel number format for `{{date}}` (default `'yyyy-mm-dd'`). */
+    dateFormat?: string;
+    /** Excel number format for `{{percent}}` (default `'0.00%'`). */
+    percentFormat?: string;
+}
+/** A Handlebars helper, as accepted by `options.helpers`. */
+export type MonoExportHelper = (...args: any[]) => unknown;
+/** Per-document detail sheets. See {@link MonoExportOptions.detail}. */
+/** One chunk of master rows, handed to {@link MonoExportDetail.load}. */
+export interface MonoExportDetailBatch {
+    /** The master rows in this chunk. */
+    data: Record<string, unknown>[];
+    /** Their key values, in `data` order, with duplicates removed. */
+    keys: unknown[];
+    /** The name of the master key field — what a filter needs to name. */
+    key: string;
+}
+export interface MonoExportDetail {
+    /**
+     * Field on the master row identifying the document. Its value is the link
+     * target the master template writes (`sheet:{{no}}`) and the basis of the
+     * sheet name. Dotted paths are accepted.
+     */
+    key: string;
+    /** Template for one detail sheet. Its context is `{ row, rows }`. */
+    md: string;
+    /**
+     * Key of `data` holding the master rows (default `'rows'`).
+     *
+     * `data` is whatever the caller passes, so the exporter cannot guess which of
+     * its keys the master template iterates.
+     */
+    from?: string;
+    /** Field holding the already-nested detail rows. Use this OR `load`. */
+    field?: string;
+    /**
+     * Fetch detail rows for a BATCH of master rows. Use this OR `field`.
+     *
+     * It is handed a chunk of master rows and their keys, and returns the detail
+     * rows for all of them in one array — the exporter groups them back per
+     * document using {@link groupBy}. One request serves a whole chunk, so a
+     * 1000-row master costs 10 requests at the default {@link loadChunk}, not
+     * 1000.
+     *
+     * ```ts
+     * load: ({ keys, key }) =>
+     *   api.lines({ filter: keys.map((id) => [key, '=', id]) })
+     * ```
+     *
+     * For an endpoint that genuinely only serves one document at a time, set
+     * `loadChunk: 1` and read `data[0]`.
+     */
+    load?: (batch: MonoExportDetailBatch) => unknown[] | Promise<unknown[]>;
+    /**
+     * How many master keys to send per `load` call (default 100).
+     *
+     * Lower it when the backend caps how many values a filter may carry, or when
+     * the generated URL would outgrow the server's limit.
+     */
+    loadChunk?: number;
+    /**
+     * How many `load` CHUNKS to have in flight at once (default 4). With the
+     * default `loadChunk` that is up to 400 documents being fetched in parallel.
+     * Ignored with `field`.
+     */
+    concurrency?: number;
+    /**
+     * Which field on a RETURNED row says which master row it belongs to.
+     * Defaults to {@link key}, which is right whenever both sides name the
+     * foreign key the same way. Dotted paths are accepted, or pass a function.
+     *
+     * Returned rows that match no master key are ignored.
+     */
+    groupBy?: string | ((row: Record<string, unknown>) => unknown);
+    /**
+     * Sheet name for a document. Defaults to the key. The result is sanitised and
+     * de-duplicated regardless, so this need not worry about Excel's rules.
+     */
+    sheetName?: (row: Record<string, unknown>) => string;
+    /** Put a `← Back` link in `A1` of each detail sheet (default `true`). */
+    back?: boolean;
+}
+export interface MonoExportOptions {
+    /** The Markdown template source (e.g. `import md from './payroll.md?raw'`). */
+    md: string;
+    /**
+     * Everything here is addressable at the top level of the template — an array
+     * loops (`{{#each company}}`), an object drills in (`{{header.Name.Full}}`).
+     *
+     * A **devextreme DataSource** (or store) may be passed in place of an array:
+     * it is drained to its rows before rendering, honouring the filter, search and
+     * sort it already carries. Only top-level values are resolved this way.
+     */
+    data?: Record<string, unknown>;
+    /**
+     * Rows per request when draining a DataSource passed in {@link data}
+     * (default `100`). A remote source can't report its size up front, so the
+     * read walks in fixed chunks until one comes back short.
+     */
+    chunkSize?: number;
+    /**
+     * Output file name. Its extension picks the renderer (`.xlsx` → Excel,
+     * `.md` → Markdown) and, unless `download` is `false`, triggers a browser
+     * download. Omit to just get the result object back.
+     */
+    fileName?: string;
+    /** Force the renderer instead of inferring it from `fileName`. */
+    format?: MonoExportFormat;
+    /** Auto-download when `fileName` is set (default `true`). */
+    download?: boolean;
+    /** Named styles, shallow-merged per name over the built-in defaults. */
+    styles?: MonoExportStyles;
+    /** Per-column width / number-format overrides, left to right. */
+    columns?: MonoExportColumn[];
+    /** Worksheet name (default `'Sheet1'`). */
+    sheetName?: string;
+    /**
+     * Give each row of the master sheet its own worksheet, reached from a link.
+     *
+     * The master template links by KEY, not by sheet name, because the final name
+     * is only known at write time (it is sanitised for Excel and de-duplicated
+     * against the workbook):
+     *
+     * ```md
+     * | [{{no}}](sheet:{{no}}) | {{total}} |
+     * ```
+     *
+     * In `.md` output that stays an ordinary Markdown link, so the same template
+     * serves both formats.
+     */
+    detail?: MonoExportDetail;
+    /** Number/date formatting used by the built-in format helpers. */
+    formatting?: MonoExportFormatOptions;
+    /**
+     * Last-mile access to the populated ExcelJS workbook, **before** anything is
+     * written — so it works even when `fileName` triggers an auto-download.
+     *
+     * Use it for what a Markdown template can't express: a second worksheet,
+     * `autoFilter`, conditional formatting, cell notes, sheet protection, print
+     * setup. Runs exactly once no matter how many times the workbook is
+     * requested, and only for `xlsx` output.
+     *
+     * @example
+     * onWorkbook: (wb) => {
+     *   const ws = wb.getWorksheet('Report')
+     *   ws.autoFilter = 'A2:D2'
+     *   ws.getCell('A1').note = 'Draft'
+     * }
+     */
+    onWorkbook?: (workbook: any) => void | Promise<void>;
+    /** Extra Handlebars helpers, merged over the built-ins. */
+    helpers?: Record<string, MonoExportHelper>;
+    /** Handlebars partials available as `{{> name}}`. */
+    partials?: Record<string, string>;
+    /**
+     * Freeze the worksheet's first N rows (default `0`). Set it to the number of
+     * rows above your table header for a sticky header in Excel.
+     */
+    freezeRows?: number;
+}
+/** What `exportTable()` / `table.export()` hand back. */
+export interface MonoExportResult {
+    /**
+     * The rendered Markdown, with every directive token stripped — safe to show
+     * in a preview pane, diff, or write to a `.md` file.
+     */
+    markdown: string;
+    /** The resolved output format (`null` when neither `fileName` nor `format` was given). */
+    format: MonoExportFormat | null;
+    /** The resolved file name, if any. */
+    fileName: string | null;
+    /**
+     * Every worksheet in the workbook, master first, in creation order — the
+     * names as Excel received them, after sanitising and de-duplication.
+     * Empty until an `xlsx` render has happened.
+     */
+    sheets: string[];
+    /**
+     * Documents that got no sheet. Without this a caller cannot tell "12 of 400
+     * had no lines" from "it all worked", which is exactly the blind spot in the
+     * implementation this feature replaces.
+     */
+    skipped: Array<{
+        key: string;
+        reason: 'empty' | 'failed';
+        error?: unknown;
+    }>;
+    /** Render to a `Blob` (defaults to the resolved format, else `'md'`). */
+    toBlob(format?: MonoExportFormat): Promise<Blob>;
+    /** Render to an `ArrayBuffer` — for uploading instead of downloading. */
+    toBuffer(format?: MonoExportFormat): Promise<ArrayBuffer>;
+    /**
+     * The populated ExcelJS workbook, for last-mile tweaks the template can't
+     * express. Requires the optional `exceljs` peer.
+     */
+    workbook(): Promise<any>;
+    /** Trigger a browser download (browser only). */
+    download(fileName?: string): Promise<void>;
+}

package/dist/src/import/coerce.d.ts

@@ -0,0 +1,38 @@
+import { MonoImportNumberFormat, MonoImportValueType } from './types';
+/**
+ * Normalise a header for lookup: NBSP → space, drop dots/underscores (`No. Dok`
+ * and `No_Dok` should both find `No Dok`), collapse whitespace, lowercase.
+ */
+export declare function normalizeHeader(value: unknown): string;
+/** Default normalisation for key comparison — forgiving about spacing and case. */
+export declare function normalizeKeyValue(value: unknown): string;
+/** Read a display string out of whatever ExcelJS put in a cell. */
+export declare function cellText(value: unknown): string;
+/**
+ * Parse a number written in an unknown locale.
+ *
+ * `'auto'` infers the separators: with both `.` and `,` present the **rightmost**
+ * is the decimal point; with only one, its position decides — exactly three
+ * trailing digits (or several occurrences) means thousands grouping, otherwise
+ * it's a decimal point. So `1.234` is one thousand two hundred, while `1.23` is
+ * one and a bit. Returns `null` when the text isn't a number at all.
+ */
+export declare function parseNumber(raw: unknown, mode?: MonoImportNumberFormat, allowNegative?: boolean): number | null;
+/** Parse a date from a Date, an ISO-ish string, or a spreadsheet serial number. */
+export declare function parseDate(raw: unknown): Date | null;
+/** Parse a boolean from the many things a human types into a yes/no column. */
+export declare function parseBoolean(raw: unknown): boolean | null;
+/**
+ * Coerce one cell for a declared column type. `undefined` means "unparseable —
+ * skip this cell" so a stray `-` in a number column can't stage `NaN`.
+ */
+export declare function coerceValue(raw: unknown, type: MonoImportValueType | undefined, opts?: {
+    numberFormat?: MonoImportNumberFormat;
+    allowNegative?: boolean;
+}): unknown;
+/**
+ * Whether a staged value would actually change the row. Numbers are compared
+ * numerically so a stored `5000` isn't "changed" by a sheet's `"5.000"`, and
+ * dates by timestamp so two equal instants don't churn.
+ */
+export declare function isSameValue(current: unknown, next: unknown, type?: MonoImportValueType): boolean;

package/dist/src/import/index.d.ts

@@ -0,0 +1,16 @@
+/// <reference path="../../vue.d.ts" />
+import { MonoImportChange, MonoImportOptions, MonoImportResult } from './types';
+export type { MonoImportAmbiguity, MonoImportChange, MonoImportColumn, MonoImportMatch, MonoImportNumberFormat, MonoImportOptions, MonoImportRejection, MonoImportResult, MonoImportType, MonoImportValueType, } from './types';
+/** What the controller supplies so this module never reaches into it. */
+export interface TableImportBridge<T = any> {
+    /** Every row the grid can produce — the default match target. */
+    getData: () => Promise<T[]>;
+    /** The controller's stable string key for a row. */
+    rowKeyOf: (row: T, index: number) => string;
+    /** The row's `keyExpr` value, for a later store update. */
+    serverKeyOf: (row: T) => unknown;
+    /** Write the patches into the staged buffer, marking them as imported. */
+    stageImported: (changes: Array<MonoImportChange<T>>) => void;
+}
+/** Run an import against a grid. The implementation behind `table.import()`. */
+export declare function importTable<T = any>(options: MonoImportOptions<T>, bridge: TableImportBridge<T>): Promise<MonoImportResult<T>>;

package/dist/src/import/match.d.ts

@@ -0,0 +1,54 @@
+import { MonoImportMatch } from './types';
+/** One key subset: the match legs it uses. */
+export type MatchScheme<T = any> = Array<MonoImportMatch<T>>;
+/** A candidate table row plus its position in the target array. */
+export interface TargetEntry<T = any> {
+    row: T;
+    index: number;
+}
+/** key string → the rows that share it (>1 means ambiguous). */
+export type SchemeIndex<T = any> = Map<string, Array<TargetEntry<T>>>;
+/**
+ * Every non-empty subset of `match` with at least `minFields` legs, ordered
+ * strongest (most legs) first.
+ *
+ * Bit-counting rather than recursion: with `n` legs there are `2^n - 1`
+ * subsets, and `n` is a handful of key columns in practice.
+ */
+export declare function buildAllSubsets<T>(match: MatchScheme<T>, minFields?: number): Array<MatchScheme<T>>;
+/** Index the target rows by one scheme's key. Collisions are kept, not dropped. */
+export declare function buildSchemeIndex<T>(scheme: MatchScheme<T>, target: readonly T[], opts?: {
+    targetFilter?: (row: T) => boolean;
+    normalize?: (v: unknown) => string;
+}): SchemeIndex<T>;
+/** A prepared matcher: schemes plus their indexes, reused across every sheet row. */
+export interface Matcher<T = any> {
+    schemes: Array<MatchScheme<T>>;
+    indexes: Array<SchemeIndex<T>>;
+    normalize: (v: unknown) => string;
+}
+export declare function createMatcher<T>(match: MatchScheme<T>, target: readonly T[], opts?: {
+    minKeyFields?: number;
+    targetFilter?: (row: T) => boolean;
+    normalize?: (v: unknown) => string;
+}): Matcher<T>;
+/** What a lookup produced. */
+export type MatchOutcome<T = any> = {
+    kind: 'hit';
+    entry: TargetEntry<T>;
+    scheme: MatchScheme<T>;
+} | {
+    kind: 'ambiguous';
+    candidates: number;
+    scheme: MatchScheme<T>;
+} | {
+    kind: 'miss';
+};
+/**
+ * Find the table row for one sheet row, strongest scheme first.
+ *
+ * An ambiguous hit is remembered but doesn't stop the search — a weaker scheme
+ * can't disambiguate, but a *different* subset of the same size might, and only
+ * if nothing unique is ever found is the ambiguity reported.
+ */
+export declare function findMatch<T>(matcher: Matcher<T>, readExcel: (leg: MonoImportMatch<T>) => unknown): MatchOutcome<T>;