@svgrid/enterprise 2.5.2 → 2.6.0

package/dist/export.d.ts

@@ -0,0 +1,323 @@
+import type { CellFormatConfig, RowData, TableFeatures } from '@svgrid/grid';
+import type { SvGridApi } from '@svgrid/grid';
+import { type CsvOptions, type SerializeProgress } from './export-serialize';
+import { type PdfBodyRow, type PdfExportOptions } from './export-pdf';
+import type { ConditionalFormat } from '@svgrid/grid/format';
+/**
+ * Export target formats.
+ *   - `xlsx` modern OOXML workbook (needs `jszip`),
+ *   - `xls`  legacy Excel 2003 XML Spreadsheet (no peer dependency),
+ *   - `pdf`  paginated document (needs `pdfmake`),
+ *   - `csv` / `tsv` / `html` / `json` / `xml` / `md` native, no peer deps.
+ */
+export type ExportFormat = 'xlsx' | 'xls' | 'pdf' | 'csv' | 'tsv' | 'html' | 'json' | 'xml' | 'md';
+export type ExportColumn<TData = RowData> = {
+    /** Data field name on the row object. */
+    field: string;
+    /** Header label to render in the exported file. Defaults to `field`. */
+    header?: string;
+    /**
+     * Column format config. When set (and `rawValues` is off), the exporter
+     * renders the value the way the grid does on screen - currency symbol,
+     * date pattern, percent, etc. Auto-populated from the grid's own columns
+     * when you don't pass `columns` explicitly.
+     */
+    format?: CellFormatConfig;
+    /** Cell alignment, carried into html / pdf output. */
+    align?: 'left' | 'center' | 'right';
+    /** Explicit column width in pixels (xlsx / xls). Overrides auto-fit. */
+    width?: number;
+    /**
+     * Turn this column's cells into hyperlinks. Return the URL for a row (or
+     * null for no link). Rendered as clickable links in xls / html / pdf /
+     * print. (xlsx via the vendored writer doesn't support cell links.)
+     */
+    link?: (row: TData) => string | null | undefined;
+    /**
+     * Escape hatch for columns whose on-screen value comes from a custom cell
+     * renderer (a snippet), a `fieldFn`, or a lookup the raw field can't
+     * express. Return the value to write for this row. Takes precedence over
+     * `format`. Return a number / Date to keep it typed in xlsx.
+     */
+    exportValue?: (row: TData) => string | number | Date | null | undefined;
+};
+/** Progress reported during an export. `phase` is 'project' while building
+ *  rows, 'serialize' while writing text formats, 'write' around the xlsx/pdf
+ *  writer. `ratio` is 0..1. */
+export type ExportProgress = SerializeProgress | {
+    phase: 'project' | 'write';
+    ratio: number;
+    row?: number;
+    total?: number;
+};
+/**
+ * The built export file. Returned by `exportData` for the dependency-free
+ * paths (csv/tsv/html/json/xml/md, xls, pdf, single-sheet xlsx) so callers can
+ * preview / upload / email / attach it instead of (or as well as) downloading.
+ * With `download: false`, nothing is downloaded and this is returned.
+ */
+export type ExportResult = {
+    blob: Blob;
+    filename: string;
+    mime: string;
+    /** Number of data rows written (excludes the header). */
+    rowCount: number;
+    byteSize: number;
+};
+/**
+ * Per-cell style descriptor. Mirrors a subset of CSS; the keys the
+ * underlying exporter honours are font / colour / background / border /
+ * alignment. Anything else is ignored gracefully.
+ */
+export type ExportCellStyle = {
+    color?: string;
+    backgroundColor?: string;
+    fontWeight?: 'normal' | 'bold' | number;
+    fontStyle?: 'normal' | 'italic';
+    fontSize?: number | string;
+    fontFamily?: string;
+    border?: string;
+    textAlign?: 'left' | 'right' | 'center';
+    verticalAlign?: 'top' | 'middle' | 'bottom';
+};
+/**
+ * Document-level style. Apply blanket styles to the header row, the
+ * value rows, or selectively per cell-reference (e.g. `'B2'`).
+ */
+export type ExportStyles = {
+    /** Style applied to every header cell. */
+    headerRow?: ExportCellStyle;
+    /** Style applied to every data row. Even / odd zebra are derived from this if `rowAlternate` is set. */
+    rows?: ExportCellStyle;
+    /** Optional zebra background for odd-indexed rows. */
+    rowAlternate?: ExportCellStyle;
+    /** Per-cell overrides keyed by Excel-style reference (`'A1'`, `'C3'`). */
+    cells?: Record<string, ExportCellStyle>;
+};
+/**
+ * Header / footer entries for xlsx + pdf. Each line is rendered top to
+ * bottom on the page. Embed an image with `{ image: dataUrl }`; embed
+ * text with `{ text: '...', style?: ExportCellStyle }`.
+ */
+export type ExportHeaderFooterLine = {
+    text: string;
+    style?: ExportCellStyle;
+} | {
+    image: string;
+    width?: number;
+    height?: number;
+} | {
+    left?: string;
+    center?: string;
+    right?: string;
+};
+export type ExportSheet<TData> = {
+    /** Sheet/tab label. Required. */
+    label: string;
+    /** Rows for this sheet. */
+    rows: ReadonlyArray<TData>;
+    /** Per-sheet columns. Falls back to the top-level `columns` if omitted. */
+    columns?: ReadonlyArray<ExportColumn<TData>>;
+    /** Per-sheet styles. */
+    styles?: ExportStyles;
+};
+/**
+ * Which rows to export:
+ *   'displayed' (default) - the current filtered / sorted / paginated view,
+ *   'selected'  - only checked rows,
+ *   'all'       - the full underlying dataset (pre-filter),
+ *   an explicit array - export exactly these.
+ */
+export type ExportRowSource<TData> = ReadonlyArray<TData> | 'displayed' | 'selected' | 'all';
+export type ExportOptions<TData> = {
+    format: ExportFormat;
+    /** Base filename (extension is appended if missing). Defaults to "grid". */
+    filename?: string;
+    /**
+     * Columns to include. If omitted, the grid's own visible columns are used
+     * (carrying their header labels + `format`), falling back to the keys of
+     * the first row.
+     */
+    columns?: ReadonlyArray<ExportColumn<TData>>;
+    /**
+     * Source rows. Defaults to `'displayed'` (the current view). Pass
+     * `'selected'` / `'all'`, or an explicit array to override.
+     */
+    rows?: ExportRowSource<TData>;
+    /**
+     * By default the exporter writes the FORMATTED display value (what the user
+     * sees) so the file matches the grid. Set `rawValues: true` to write the
+     * underlying raw values instead (numbers stay numeric in xlsx; useful for
+     * downstream data pipelines).
+     */
+    rawValues?: boolean;
+    /**
+     * Auto-carry the grid's active row grouping into the export (xlsx outline
+     * rows). On by default; set false to ignore grouping, or pass `groupBy`
+     * explicitly to override. Ignored when you pass `groupBy` / `hierarchical`
+     * / `sheets` yourself.
+     */
+    autoGroup?: boolean;
+    /** CSV / TSV tuning: delimiter, line ending, UTF-8 BOM. */
+    csv?: CsvOptions;
+    /**
+     * Freeze the header row so it stays visible when scrolling (xlsx / xls).
+     * Default true.
+     */
+    freezeHeader?: boolean;
+    /** Freeze this many leading columns (xlsx / xls). Default 0. */
+    freezeColumns?: number;
+    /**
+     * Size columns to their content (xlsx / xls). Default true. A column's
+     * explicit `width` always wins.
+     */
+    autoFitColumns?: boolean;
+    /**
+     * Export long integer IDs (> 15 significant digits) as TEXT so Excel's
+     * 15-digit float precision doesn't silently mangle them. Default false.
+     * (xlsx / xls.)
+     */
+    precisionSafe?: boolean;
+    /**
+     * Wrap the xlsx data in a native Excel Table (filter dropdowns, banded rows,
+     * structured refs). `{ totalsRow: true }` adds a totals row with live
+     * SUM/AVG formulas for numeric columns. Single-sheet xlsx only.
+     */
+    excelTable?: boolean | {
+        totalsRow?: boolean;
+        style?: string;
+    };
+    /** Progress callback for large exports (row projection + serialization). */
+    onProgress?: (progress: ExportProgress) => void;
+    /** Abort an in-flight export (checked between chunks). Throws `AbortError`. */
+    signal?: AbortSignal;
+    /**
+     * When false, don't trigger a browser download - just build the file and
+     * return it as an {@link ExportResult} (`{ blob, filename, mime, rowCount,
+     * byteSize }`) so the app can preview / upload / email it. Default true.
+     * Not supported for the vendored-writer xlsx paths (grouped / multi-sheet /
+     * images / blanket styles), which download directly.
+     */
+    download?: boolean;
+    /** PDF only. Page orientation. Defaults to "portrait" (auto-landscape for
+     *  wide grids). Shorthand for `pdf.pageOrientation`. */
+    pageOrientation?: 'portrait' | 'landscape';
+    /** PDF layout options: page size, margins, title / subtitle / logo, theme
+     *  colors, column widths, repeated header, page numbers. */
+    pdf?: PdfExportOptions;
+    /**
+     * Conditional formatting rules - the same array you pass to
+     * `<SvGrid conditionalFormats>`. Carried into the styled formats (pdf, xlsx,
+     * html): cell background / text color / bold, plus icon-set glyphs. Ignored
+     * by the data formats (csv / tsv / json / xml / md).
+     */
+    conditionalFormats?: ReadonlyArray<ConditionalFormat<TData>>;
+    /**
+     * Cell + row styles. Apply once to match a light/dark theme, or per-cell
+     * for conditional formatting. xlsx and pdf honour these; csv/tsv ignore
+     * them; html bakes them into inline `style=` attributes.
+     */
+    styles?: ExportStyles;
+    /** Page header lines (xlsx, pdf, html). Logos go here as `{ image: ... }`. */
+    header?: ReadonlyArray<ExportHeaderFooterLine>;
+    /** Page footer lines. Common pattern: page number on the right. */
+    footer?: ReadonlyArray<ExportHeaderFooterLine>;
+    /**
+     * Multi-sheet export (xlsx only). When set, each entry becomes one
+     * sheet/tab. The top-level `rows` / `columns` are ignored.
+     */
+    sheets?: ReadonlyArray<ExportSheet<TData>>;
+    /**
+     * If a row has a column whose value matches one of these field names
+     * AND the value looks like a URL or data URL, the cell is exported as
+     * an embedded image (xlsx). Defaults to `[]` (no auto-detection).
+     */
+    imageFields?: ReadonlyArray<string>;
+    /**
+     * Pixel dimensions used when embedding images. Smart's xlsx writer
+     * draws the image at this size relative to the cell origin. Defaults
+     * to `{ width: 32, height: 32 }`. Set larger for thumbnails, smaller
+     * for inline icons.
+     */
+    imageSize?: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Group flat rows by one or more field names. The exporter wraps each
+     * group in an Excel outline row (with the +/- expand button), and
+     * emits a `<value> <field>` group header above every cluster. Maps
+     * straight to Smart DataExporter's constructor `groupBy` arg. xlsx
+     * only; csv/tsv/html flatten the groups back out.
+     */
+    groupBy?: ReadonlyArray<string>;
+    /**
+     * Mark rows as a hierarchical (tree) data source. Each row should
+     * declare its own children either via the `subRows` convention or by
+     * matching the parent/child shape Smart expects on the input rows.
+     * Mutually exclusive with `groupBy`. xlsx only.
+     */
+    hierarchical?: boolean;
+    /**
+     * Merged cells to write into the sheet (xlsx / pdf). Each entry spans
+     * `colSpan` columns and `rowSpan` rows starting at the given zero-based
+     * **body** row / column index (the header row is not counted). Mirrors the
+     * grid's own `MergeSpec` shape closely, so grid merges map straight through -
+     * convert a `MergeSpec` (`{ rowIndex, columnId, rowspan, colspan }`) by
+     * resolving `columnId` to its column index. Mutually exclusive with
+     * `groupBy` / `hierarchical`.
+     */
+    merges?: ReadonlyArray<ExportMerge>;
+};
+/**
+ * A merged cell region for {@link ExportOptions.merges}. `row` / `col` are
+ * zero-based indices into the exported body (header excluded). A cell that
+ * spans two columns to the right is `{ row, col, colSpan: 2 }`.
+ */
+export type ExportMerge = {
+    row: number;
+    col: number;
+    /** Columns to span (default 1). */
+    colSpan?: number;
+    /** Rows to span (default 1). */
+    rowSpan?: number;
+};
+/** Resolve the {@link ExportRowSource} shorthand against the grid api. */
+export declare function resolveRowSource<TFeatures extends TableFeatures, TData extends RowData>(api: SvGridApi<TFeatures, TData>, source: ExportRowSource<TData> | undefined): ReadonlyArray<TData>;
+/** Resolve the export columns, carrying grid header labels + `format`. */
+export declare function resolveColumns<TFeatures extends TableFeatures, TData extends RowData>(api: SvGridApi<TFeatures, TData>, opts: Pick<ExportOptions<TData>, 'columns'>, sourceRows: ReadonlyArray<TData>): ReadonlyArray<ExportColumn<TData>>;
+/**
+ * Project source rows into the `[header, ...records]` shape the writers
+ * consume, applying per-column formatting / `exportValue`. Async so it can
+ * yield to the event loop (and honour an abort) on large datasets.
+ */
+export declare function projectRows<TData extends RowData>(sourceRows: ReadonlyArray<TData>, cols: ReadonlyArray<ExportColumn<TData>>, opts: Pick<ExportOptions<TData>, 'rawValues' | 'onProgress' | 'signal'>): Promise<Array<Record<string, unknown>>>;
+/** A `(rowIdx, colIdx) => url` resolver from column `link` hooks, or undefined
+ *  when no column defines links. */
+export declare function buildLinkResolver<TData extends RowData>(cols: ReadonlyArray<ExportColumn<TData>>, rows: ReadonlyArray<TData>): ((rowIdx: number, colIdx: number) => string | undefined) | undefined;
+/**
+ * Build a grouped PDF body: a bold group header per cluster (nested for
+ * multi-level grouping), the cluster's data rows, then a subtotal row summing
+ * the numeric / currency columns. Values use the same formatting as the grid.
+ */
+export declare function buildGroupedPdfBody<TData extends RowData>(cols: ReadonlyArray<ExportColumn<TData>>, rows: ReadonlyArray<TData>, groupBy: ReadonlyArray<string>): PdfBodyRow[];
+export declare function exportGrid<TFeatures extends TableFeatures, TData extends RowData>(api: SvGridApi<TFeatures, TData>, opts: ExportOptions<TData>): Promise<ExportResult | undefined>;
+/** Native formats that can be placed on the clipboard. */
+export type ClipboardFormat = 'csv' | 'tsv' | 'html' | 'json' | 'xml' | 'md';
+export type ClipboardExportOptions<TData> = {
+    /** Clipboard payload format. Default 'tsv' (pastes cleanly into Excel / Sheets). */
+    format?: ClipboardFormat;
+    columns?: ReadonlyArray<ExportColumn<TData>>;
+    rows?: ExportRowSource<TData>;
+    rawValues?: boolean;
+    csv?: CsvOptions;
+    onProgress?: (progress: ExportProgress) => void;
+    signal?: AbortSignal;
+};
+/**
+ * Copy the grid (current view / selection / all) to the clipboard in a native
+ * text format instead of downloading a file. Defaults to `tsv`, which pastes
+ * straight into Excel / Google Sheets as real columns. `html` writes rich
+ * `text/html` so pasted cells keep their table structure.
+ */
+export declare function copyExportToClipboard<TFeatures extends TableFeatures, TData extends RowData>(api: SvGridApi<TFeatures, TData>, opts?: ClipboardExportOptions<TData>): Promise<void>;