@svgrid/grid 1.2.22 → 1.2.24

package/dist/editing.js

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

package/dist/editor-contract.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The shared "editor contract" for the SvGrid UI kit.
+ *
+ * Every value-bearing editor (inputs, selects, pickers) accepts this common set
+ * of props so forms, validation and accessibility behave IDENTICALLY across the
+ * kit - the same spirit as the grid's headless core, applied to the editors.
+ * Components spread their own `value` / options / behavior on top of this base.
+ *
+ * Framework-free (no Svelte, no DOM) so it can be unit-tested and reused.
+ */
+export type EditorSize = 'sm' | 'md' | 'lg';
+/** Props shared by every value-bearing editor in the kit. */
+export type SvEditorProps = {
+    /** Disable interaction + form submission. */
+    disabled?: boolean;
+    /** Read-only: the value is shown but not editable. */
+    readonly?: boolean;
+    /** Required for validation (adds `aria-required` + participates in validity). */
+    required?: boolean;
+    /** Marks the control invalid (`aria-invalid` + error styling). */
+    invalid?: boolean;
+    /** Error message; when set it is announced via `aria-describedby` and shown. */
+    error?: string;
+    /** Control size / density. */
+    size?: EditorSize;
+    /** Form field name; the editor emits a hidden input carrying its value. */
+    name?: string;
+    /** Root/control element id (the error-text id derives from it). */
+    id?: string;
+    /** Accessible name when there is no visible `<label>`. */
+    ariaLabel?: string;
+};
+/** Stable DOM id for an editor's error text, for `aria-describedby` wiring. */
+export declare const editorErrorId: (id?: string) => string | undefined;
+/** A subset of {@link SvEditorProps} that drives ARIA on the focusable control. */
+export type EditorAriaState = Pick<SvEditorProps, 'id' | 'invalid' | 'required' | 'error' | 'ariaLabel'>;
+/**
+ * ARIA attributes for the focusable control of an editor, derived from its state.
+ * Spread onto the input/button/combobox:
+ * `<input {...editorAria({ id, invalid, required, error, ariaLabel })} />`
+ * Undefined values are omitted by Svelte, so unset props add no attributes.
+ */
+export declare function editorAria(state: EditorAriaState): {
+    'aria-invalid': 'true' | undefined;
+    'aria-required': 'true' | undefined;
+    'aria-describedby': string | undefined;
+    'aria-label': string | undefined;
+};

package/dist/editor-contract.js

@@ -0,0 +1,26 @@
+/**
+ * The shared "editor contract" for the SvGrid UI kit.
+ *
+ * Every value-bearing editor (inputs, selects, pickers) accepts this common set
+ * of props so forms, validation and accessibility behave IDENTICALLY across the
+ * kit - the same spirit as the grid's headless core, applied to the editors.
+ * Components spread their own `value` / options / behavior on top of this base.
+ *
+ * Framework-free (no Svelte, no DOM) so it can be unit-tested and reused.
+ */
+/** Stable DOM id for an editor's error text, for `aria-describedby` wiring. */
+export const editorErrorId = (id) => (id ? `${id}__error` : undefined);
+/**
+ * ARIA attributes for the focusable control of an editor, derived from its state.
+ * Spread onto the input/button/combobox:
+ * `<input {...editorAria({ id, invalid, required, error, ariaLabel })} />`
+ * Undefined values are omitted by Svelte, so unset props add no attributes.
+ */
+export function editorAria(state) {
+    return {
+        'aria-invalid': state.invalid ? 'true' : undefined,
+        'aria-required': state.required ? 'true' : undefined,
+        'aria-describedby': state.error ? editorErrorId(state.id) : undefined,
+        'aria-label': state.ariaLabel,
+    };
+}

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

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

package/dist/editors/cell-editors.js

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

package/dist/export-format.d.ts

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