@opencorestack/opengridx 3.3.0 → 3.4.0

package/lib/types/index.ts

@@ -178,6 +178,14 @@ export interface GridColDef<R extends GridValidRowModel = GridRowModel> {
    * @since v3.0
    */
   valueSetter?(params: GridValueSetterParams<R>): R;
+  /**
+   * Turns pasted text into this column's value (clipboard paste), instead of the default parser for
+   * the column `type` (see `docs/features/clipboard.md`). Use it for locales such as `1.234,5` or for
+   * custom codes. Throw (or return `undefined`) to reject the text: the cell is skipped with reason
+   * `'invalidValue'`. The value then goes through `valueSetter` and `processRowUpdate` like an edit.
+   * @since v3.4
+   */
+  valueParser?(text: string, params: GridValueParserParams<R>): unknown;
   /**
    * Custom ascending comparator for client-side sorting by this column, used instead of the built-in
    * type-aware comparison. `v1` / `v2` are the cell values (`valueGetter` applied) and **include
@@ -240,6 +248,16 @@ export interface GridColDef<R extends GridValidRowModel = GridRowModel> {
    * @default true
    */
   exportable?: boolean;
+
+  /**
+   * Example values for this column, put into the schema from `getGridAiSchema`
+   * (`@opencorestack/opengridx/ai`) to help a language model write filters ("Acme" → `customer`).
+   * **These values are sent to the model.** The grid never reads row data for the schema; only what
+   * you list here leaves the app, so list nothing private. Strings, numbers and booleans are used
+   * (at most 10); other values are ignored. Not used by the grid itself.
+   * @since v3.4
+   */
+  aiExamples?: unknown[];
 }
 
 /** Column definition used exclusively in List View mode. */
@@ -300,6 +318,14 @@ export interface GridValueGetterParams<R extends GridValidRowModel = GridRowMode
   value: unknown;
 }
 
+/** Parameters passed to `GridColDef.valueParser`. @since v3.4 */
+export interface GridValueParserParams<R extends GridValidRowModel = GridRowModel> {
+  /** The row the text is pasted into, as stored now. */
+  row: R;
+  field: string;
+  colDef: GridColDef<R>;
+}
+
 /**
  * Parameters passed to the `valueSetter` function.
  * @since v3.0
@@ -803,6 +829,54 @@ export interface GridRowScrollEndParams {
   viewportHeight: number;
 }
 
+/**
+ * Why a cell of a batch edit (paste, range clear, undo, redo) was not written:
+ * - `'notEditable'`: the column is not `editable`, `isCellEditable` returned false, or the row is a
+ *   synthetic row (group header, subtotal, tree auto-parent, pivot Grand Total);
+ * - `'invalidValue'`: the pasted text does not parse for the column type (or `valueParser` rejected it);
+ * - `'changed'`: undo/redo only, the cell no longer holds the value the history recorded;
+ * - `'missing'`: undo/redo only, the row is gone.
+ * @since v3.4
+ */
+export type GridEditSkipReason = 'notEditable' | 'invalidValue' | 'changed' | 'missing';
+
+/** What a batch edit (paste, range clear, undo, redo) did. @since v3.4 */
+export interface GridBatchEditResult {
+  /** Rows whose `processRowUpdate` succeeded and that were stored, in the order they were first touched. */
+  updated: GridRowId[];
+  /** Rows whose `valueSetter` or `processRowUpdate` threw or rejected (also reported to `onProcessRowUpdateError`). */
+  failed: { id: GridRowId; error: unknown }[];
+  /** Cells that were not written, with the reason. */
+  skipped: { id: GridRowId; field: string; reason: GridEditSkipReason }[];
+}
+
+/** `onClipboardPaste` details: the batch edit result plus the text that was pasted. @since v3.4 */
+export interface GridClipboardPasteResult extends GridBatchEditResult {
+  text: string;
+}
+
+/** `onBeforeClipboardPaste` params. @since v3.4 */
+export interface GridBeforeClipboardPasteParams {
+  /** The clipboard text (`text/plain`). */
+  text: string;
+  /** The cell the paste starts from (the range's top-left cell, or the focused cell). */
+  anchor: GridCellCoordinates | null;
+}
+
+/** `onHistoryChange` params. @since v3.4 */
+export interface GridHistoryChangeParams {
+  canUndo: boolean;
+  canRedo: boolean;
+  /** Number of actions that can be undone. */
+  size: number;
+}
+
+/** `undoRedo` options. @since v3.4 */
+export interface GridUndoRedoOptions {
+  /** How many actions are kept; the oldest is dropped beyond it. Default: 100. */
+  limit?: number;
+}
+
 /** Overrideable user-visible strings for internationalisation. All fields are optional; defaults match the built-in English strings. */
 export interface GridLocaleText {
     /** Label before the rows-per-page select. Default: `"Rows per page:"` */
@@ -939,6 +1013,39 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
    */
   showCellSelectionStats?: boolean;
 
+  /**
+   * With `cellSelection` on, Ctrl/Cmd+V pastes tab-separated text (Excel, Google Sheets) into the
+   * editable cells from the range's top-left cell (or the focused cell), through `valueSetter` and
+   * `processRowUpdate`. `true` turns the shortcut off; `apiRef.pasteText()` still works. Default: false.
+   * @since v3.4
+   */
+  disableClipboardPaste?: boolean;
+  /**
+   * Fired after every paste with the result (`updated` rows, `failed` rows, `skipped` cells and why)
+   * and the pasted text. @since v3.4
+   */
+  onClipboardPaste?: (result: GridClipboardPasteResult) => void;
+  /**
+   * Called before a paste is applied. Return `false` to cancel it, or a string to paste instead of the
+   * clipboard text. A throw cancels the paste. @since v3.4
+   */
+  onBeforeClipboardPaste?: (params: GridBeforeClipboardPasteParams) => boolean | string;
+  /**
+   * With `cellSelection` on, Delete / Backspace on a range of more than one cell empties its editable
+   * cells (`null`, or `''` in string columns) as one edit. `true` turns that off. Default: false.
+   * @since v3.4
+   */
+  disableRangeClear?: boolean;
+  /**
+   * Undo and redo of cell edits, pastes and range clears: Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z and Ctrl+Y while
+   * focus is in the grid and no editor is open, and `apiRef.undo()` / `redo()`. Undo and redo write
+   * through `valueSetter` and `processRowUpdate`, like an edit. `{ limit }` sets how many actions are
+   * kept (default 100). Default: false. @since v3.4
+   */
+  undoRedo?: boolean | GridUndoRedoOptions;
+  /** Fired when what can be undone or redone changes (`undoRedo`). @since v3.4 */
+  onHistoryChange?: (params: GridHistoryChangeParams) => void;
+
   /** Loading state. With no rows the body shows skeleton rows (or `slots.loadingOverlay`); with rows, they stay and a progress bar (or `slots.loadingOverlay`) is shown over them. */
   loading?: boolean;
   /** Visual density of the grid. */
@@ -1328,4 +1435,21 @@ export interface GridApi<R extends GridValidRowModel = GridRowModel> {
    * copy; rejects when the clipboard write fails. @since v3.3
    */
   copySelectedCells: () => Promise<void>;
+
+  /**
+   * Pastes tab-separated text as Ctrl/Cmd+V does: from `anchor` (default: the range's top-left cell,
+   * else the focused cell), with `onBeforeClipboardPaste` and `onClipboardPaste`. Works with
+   * `disableClipboardPaste`. Resolves once every row's `processRowUpdate` has settled. @since v3.4
+   */
+  pasteText: (text: string, anchor?: GridCellCoordinates) => Promise<GridBatchEditResult>;
+  /** Undoes the last action (`undoRedo`). Resolves with what was written. @since v3.4 */
+  undo: () => Promise<GridBatchEditResult>;
+  /** Redoes the last undone action (`undoRedo`). @since v3.4 */
+  redo: () => Promise<GridBatchEditResult>;
+  /** Whether there is an action to undo. @since v3.4 */
+  canUndo: () => boolean;
+  /** Whether there is an undone action to redo. @since v3.4 */
+  canRedo: () => boolean;
+  /** Forgets every action (undo and redo). @since v3.4 */
+  clearHistory: () => void;
 }

package/lib/utils/editing/commit.ts

@@ -0,0 +1,69 @@
+import type { GridColDef, GridRowId, GridRowModel } from '../../types';
+
+/**
+ * The steps every committed edit shares: a single-cell edit (`useGridEditing`) and a batch edit
+ * (`useGridBatchEdit`: paste, range clear, undo, redo) build the row the same way and report errors
+ * the same way.
+ */
+
+/** A misuse of the editing contract (e.g. processRowUpdate returned nothing), as opposed to a consumer rejection. */
+export class OpenGridXEditError extends Error {}
+
+/** One committed cell change: the value before and the value stored after (both read through `getCellValue`). */
+export interface GridCellChange {
+    id: GridRowId;
+    field: string;
+    before: unknown;
+    after: unknown;
+}
+
+/** Cell values compare equal: dates by time, anything else with `Object.is`. */
+export function isSameValue(a: unknown, b: unknown): boolean {
+    if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
+    return Object.is(a, b);
+}
+
+export function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+    return typeof value === 'object' && value !== null && typeof (value as { then?: unknown }).then === 'function';
+}
+
+/**
+ * Sends an edit failure to `onProcessRowUpdateError`. Without one, a misuse of the contract is logged
+ * in development; a consumer rejection is the consumer's own and stays silent.
+ */
+export function reportEditError(error: unknown, onError: ((error: unknown) => void) | undefined): void {
+    if (onError) {
+        onError(error);
+    } else if (process.env.NODE_ENV !== 'production' && error instanceof OpenGridXEditError) {
+        console.error(error.message);
+    }
+}
+
+/** The error for a `processRowUpdate` that resolved to something other than a row object. */
+export function invalidProcessedRowError(processed: unknown, outcome: string): OpenGridXEditError {
+    return new OpenGridXEditError(
+        `[OpenGridX] processRowUpdate must return the updated row object (or a Promise of it); ` +
+        `it returned ${processed === null ? 'null' : typeof processed}. ${outcome}`
+    );
+}
+
+/** The row with one cell changed: through the column's `valueSetter`, else `row[field] = value`. */
+export function buildEditedRow<R extends GridRowModel>(
+    row: R,
+    cell: { field: string; value: unknown },
+    colDef: GridColDef<R> | undefined,
+    warnedFields: Set<string>
+): R {
+    if (colDef?.valueSetter) {
+        return colDef.valueSetter({ value: cell.value, row, field: cell.field });
+    }
+    if (colDef?.valueGetter && process.env.NODE_ENV !== 'production' && !warnedFields.has(cell.field)) {
+        warnedFields.add(cell.field);
+        console.warn(
+            `[OpenGridX] Column "${cell.field}" is editable and has a valueGetter but no valueSetter. ` +
+            `The edited value was written to row["${cell.field}"], which the valueGetter may ignore, so the cell ` +
+            'can keep showing the old value. Add a valueSetter that maps the value back onto the row.'
+        );
+    }
+    return { ...row, [cell.field]: cell.value };
+}

package/lib/utils/editing/targets.ts

@@ -0,0 +1,109 @@
+import type { GridCellCoordinates, GridCellParams, GridColDef, GridRowId, GridRowMeta, GridRowModel } from '../../types';
+import { isRangeColumnField } from '../cellSelection';
+import type { CellRangeRect } from '../cellSelection';
+import { isSystemField } from '../focus';
+import { isSyntheticRowId } from '../syntheticRows';
+import { resolveCellEditable } from './index';
+import { getCellValue } from '../values';
+
+/**
+ * Where batch edits (paste, range clear, undo/redo) land: the renderable rows and the range columns
+ * (data columns, no system or grouping column) in display order, the same coordinates as a cell range.
+ */
+export interface GridEditTargetContext<R extends GridRowModel> {
+    rows: readonly R[];
+    rowIds: GridRowId[];
+    rowIndexById: Map<GridRowId, number>;
+    /** Range columns in screen order. */
+    columns: GridColDef<R>[];
+    colIndexByField: Map<string, number>;
+    /** Number of system columns before the data columns (for `isCellEditable`'s `colIndex`). */
+    dataColumnOffset: number;
+}
+
+export function buildEditTargetContext<R extends GridRowModel>(
+    rows: readonly R[],
+    getRowId: (row: R) => GridRowId,
+    navigationColumns: ReadonlyArray<GridColDef<R>>,
+): GridEditTargetContext<R> {
+    const rowIds = rows.map(getRowId);
+    const rowIndexById = new Map<GridRowId, number>();
+    rowIds.forEach((id, index) => { if (!rowIndexById.has(id)) rowIndexById.set(id, index); });
+    const columns = navigationColumns.filter(c => isRangeColumnField(c.field));
+    const colIndexByField = new Map<string, number>();
+    columns.forEach((c, index) => { colIndexByField.set(c.field, index); });
+    const dataColumnOffset = navigationColumns.filter(c => isSystemField(c.field)).length;
+    return { rows, rowIds, rowIndexById, columns, colIndexByField, dataColumnOffset };
+}
+
+export interface GridEditTargetRules<R extends GridRowModel> {
+    isCellEditable?: (params: GridCellParams<R>) => boolean;
+    rowMetaMap?: ReadonlyMap<GridRowId, GridRowMeta>;
+    /** For a cell covered by a span, the origin cell (`null` otherwise). */
+    getSpanOrigin?: (rowId: GridRowId, field: string) => { rowId: GridRowId; field: string } | null;
+}
+
+/**
+ * Whether a batch edit may write the cell at display position (r, c): a data row (not synthetic),
+ * not covered by a span whose origin is another cell, and editable by the same rule as double-click.
+ */
+export function isEditTargetWritable<R extends GridRowModel>(
+    ctx: GridEditTargetContext<R>,
+    rules: GridEditTargetRules<R>,
+    row: R,
+    r: number,
+    c: number,
+): boolean {
+    const id = ctx.rowIds[r];
+    const colDef = ctx.columns[c];
+    if (!colDef || isSyntheticRowId(id, rules.rowMetaMap)) return false;
+    const origin = rules.getSpanOrigin?.(id, colDef.field);
+    if (origin && (origin.rowId !== id || origin.field !== colDef.field)) return false;
+    return resolveCellEditable({
+        row,
+        field: colDef.field,
+        value: getCellValue(row, colDef.field, colDef),
+        colDef,
+        rowIndex: r,
+        colIndex: ctx.dataColumnOffset + c,
+        rowMeta: rules.rowMetaMap?.get(id),
+    }, rules.isCellEditable);
+}
+
+/** The rectangle around the displayed cells among `cells`, or null when none is displayed. */
+export function boundingTargetRect<R extends GridRowModel>(
+    ctx: GridEditTargetContext<R>,
+    cells: ReadonlyArray<{ id: GridRowId; field: string }>,
+): CellRangeRect | null {
+    let top = Infinity;
+    let bottom = -Infinity;
+    let left = Infinity;
+    let right = -Infinity;
+    for (const cell of cells) {
+        const r = ctx.rowIndexById.get(cell.id);
+        const c = ctx.colIndexByField.get(cell.field);
+        if (r === undefined || c === undefined) continue;
+        if (r < top) top = r;
+        if (r > bottom) bottom = r;
+        if (c < left) left = c;
+        if (c > right) right = c;
+    }
+    return top === Infinity ? null : { top, bottom, left, right };
+}
+
+/** The two corner cells of a rectangle. */
+export function rectCorners<R extends GridRowModel>(
+    ctx: GridEditTargetContext<R>,
+    rect: CellRangeRect,
+): { anchor: GridCellCoordinates; head: GridCellCoordinates } {
+    return {
+        anchor: { id: ctx.rowIds[rect.top], field: ctx.columns[rect.left].field },
+        head: { id: ctx.rowIds[rect.bottom], field: ctx.columns[rect.right].field },
+    };
+}
+
+/** Columns whose empty value is `''` rather than `null`. */
+export function isTextColumn(colDef: Pick<GridColDef, 'type'> | undefined): boolean {
+    const type = colDef?.type;
+    return type === undefined || type === 'string' || type === 'image';
+}

package/lib/utils/parsing.ts

@@ -0,0 +1,252 @@
+import type { GridColDef, GridValidRowModel } from '../types';
+import { toDate } from './values';
+
+/**
+ * Text → typed values: the TSV reader clipboard paste uses, and the per-column-type parsers paste,
+ * `GridColDef.valueParser` defaults and the `/ai` validator share. Pure and React-free.
+ *
+ * Every pattern here is linear (CodeQL scans every push): no adjacent quantifiers that can match the
+ * same characters.
+ */
+
+/** A parsed value, or `{ ok: false }` when the text does not fit the column type. */
+export type GridParsedValue = { ok: true; value: unknown } | { ok: false };
+
+const INVALID: GridParsedValue = { ok: false };
+const valid = (value: unknown): GridParsedValue => ({ ok: true, value });
+
+/**
+ * Splits tab-separated text the way Excel, Google Sheets and LibreOffice write it: tabs between
+ * columns, `\r\n`, `\n` or `\r` between rows. A field that starts with a double quote is quoted: it
+ * may hold tabs, line breaks and doubled quotes (`""` → `"`), the reverse of `escapeTsvField`. A
+ * quote inside an unquoted field is kept as is. A trailing empty line is ignored, so `"a\tb\n"` is one
+ * row. Empty text gives no rows.
+ */
+export function parseTsv(text: string): string[][] {
+    const rows: string[][] = [];
+    if (text === '') return rows;
+    let row: string[] = [];
+    let field = '';
+    let i = 0;
+    const n = text.length;
+    let fieldStart = true;
+    while (i < n) {
+        const ch = text[i];
+        if (fieldStart && ch === '"') {
+            // A quoted field: read to the closing quote, `""` being one quote.
+            let j = i + 1;
+            let value = '';
+            let closed = false;
+            while (j < n) {
+                const q = text[j];
+                if (q === '"') {
+                    if (text[j + 1] === '"') {
+                        value += '"';
+                        j += 2;
+                        continue;
+                    }
+                    closed = true;
+                    j += 1;
+                    break;
+                }
+                value += q;
+                j += 1;
+            }
+            if (!closed) {
+                // No closing quote: not a quoted field after all, read the quote as text.
+                field += ch;
+                i += 1;
+                fieldStart = false;
+                continue;
+            }
+            field += value;
+            i = j;
+            fieldStart = false;
+            continue;
+        }
+        fieldStart = false;
+        if (ch === '\t') {
+            row.push(field);
+            field = '';
+            fieldStart = true;
+            i += 1;
+        } else if (ch === '\n' || ch === '\r') {
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = '';
+            fieldStart = true;
+            i += ch === '\r' && text[i + 1] === '\n' ? 2 : 1;
+        } else {
+            field += ch;
+            i += 1;
+        }
+    }
+    // The last line, unless the text ended with a line break (Excel always adds one).
+    if (!fieldStart || row.length > 0 || field !== '') {
+        row.push(field);
+        rows.push(row);
+    }
+    return rows;
+}
+
+const PLAIN_NUMBER = /^\d+(?:\.\d*)?(?:e[+-]?\d+)?$/i;
+const LEADING_DOT_NUMBER = /^\.\d+(?:e[+-]?\d+)?$/i;
+const GROUPED_NUMBER = /^\d{1,3}(?:,\d{3})+(?:\.\d*)?$/;
+// Currency symbols (Unicode Sc) and every kind of space, including the no-break spaces Excel uses
+// as a thousands separator.
+const STRIPPED_CHARS = /[\p{Sc}\s]/gu;
+
+/**
+ * A number as spreadsheets copy it: `1234.5`, `1,234.5` (comma thousands groups only), `-12`,
+ * `(12)` (accounting negative), `12%` (→ 0.12), `1e3`, with currency symbols and spaces stripped.
+ * Empty text is `null`. `1,5` is not accepted (it is ambiguous): use a `valueParser` for
+ * decimal-comma locales.
+ */
+export function parseNumberText(text: string): GridParsedValue {
+    let s = text.replace(STRIPPED_CHARS, '');
+    if (s === '') return text.trim() === '' ? valid(null) : INVALID;
+    let negative = false;
+    if (s.startsWith('(') && s.endsWith(')')) {
+        negative = true;
+        s = s.slice(1, -1);
+    }
+    if (s.startsWith('-') || s.startsWith('+') || s.startsWith('−')) {
+        if (s[0] !== '+') negative = !negative;
+        s = s.slice(1);
+    }
+    let percent = false;
+    if (s.endsWith('%')) {
+        percent = true;
+        s = s.slice(0, -1);
+    }
+    if (GROUPED_NUMBER.test(s)) s = s.split(',').join('');
+    else if (!PLAIN_NUMBER.test(s) && !LEADING_DOT_NUMBER.test(s)) return INVALID;
+    let value = Number(s);
+    if (!Number.isFinite(value)) return INVALID;
+    if (percent) value /= 100;
+    if (negative) value = -value;
+    return valid(value);
+}
+
+const ISO_DATE_PREFIX = /^(\d{4}-\d{2}-\d{2})/;
+const pad2 = (n: number) => String(n).padStart(2, '0');
+const localDay = (date: Date) => `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
+
+/**
+ * A date: ISO `2026-10-07` (read as that local calendar day) or anything `Date.parse` accepts. Empty
+ * text is `null`. The result takes the kind of `current` (the value the cell holds now), as the date
+ * editor does: a timestamp stays a timestamp, a date string stays a `YYYY-MM-DD` string (an ISO
+ * date-time string keeps its time part); otherwise it is a `Date`.
+ */
+export function parseDateText(text: string, current?: unknown): GridParsedValue {
+    const trimmed = text.trim();
+    if (trimmed === '') return valid(null);
+    const date = toDate(trimmed);
+    if (!date) return INVALID;
+    if (typeof current === 'number') return valid(date.getTime());
+    if (typeof current === 'string') {
+        const day = localDay(date);
+        return valid(ISO_DATE_PREFIX.test(current) && current.length > 10 ? day + current.slice(10) : day);
+    }
+    return valid(date);
+}
+
+/** Text read as `true` / `false`, besides the grid's own `Yes` / `No` cell labels. Lower case. */
+const TRUE_WORDS = new Set(['true', 'yes', '1']);
+const FALSE_WORDS = new Set(['false', 'no', '0']);
+
+export interface GridBooleanLabels {
+    /** Text shown for `true` (the grid shows `Yes`). */
+    trueLabel?: string;
+    /** Text shown for `false` (the grid shows `No`). */
+    falseLabel?: string;
+}
+
+/**
+ * A boolean: `true`/`false`, `yes`/`no` (the grid's own `Yes` / `No` cell labels), `1`/`0` and any
+ * `labels` given, case-insensitive. Empty text is `null`.
+ */
+export function parseBooleanText(text: string, labels?: GridBooleanLabels): GridParsedValue {
+    const s = text.trim().toLowerCase();
+    if (s === '') return valid(null);
+    if (labels?.trueLabel !== undefined && s === labels.trueLabel.trim().toLowerCase()) return valid(true);
+    if (labels?.falseLabel !== undefined && s === labels.falseLabel.trim().toLowerCase()) return valid(false);
+    if (TRUE_WORDS.has(s)) return valid(true);
+    if (FALSE_WORDS.has(s)) return valid(false);
+    return INVALID;
+}
+
+type ValueOption = NonNullable<GridColDef['valueOptions']>[number];
+
+/**
+ * A `singleSelect` value: the option whose value or label matches the text, case-insensitive (values
+ * first). Returns the option's own value, so a numeric option stays a number. Empty text is `null`.
+ */
+export function parseSingleSelectText(text: string, options: readonly ValueOption[] | undefined): GridParsedValue {
+    const s = text.trim();
+    if (s === '') return valid(null);
+    if (!options || options.length === 0) return INVALID;
+    const lower = s.toLowerCase();
+    for (const option of options) {
+        const value = typeof option === 'object' ? option.value : option;
+        if (String(value).toLowerCase() === lower) return valid(value);
+    }
+    for (const option of options) {
+        if (typeof option === 'object' && option.label.toLowerCase() === lower) return valid(option.value);
+    }
+    return INVALID;
+}
+
+type ParserColumn = Pick<GridColDef, 'type' | 'valueOptions'>;
+
+export interface GridParseTextOptions {
+    /** The value the cell holds now: a parsed date takes its kind (see `parseDateText`). */
+    current?: unknown;
+    /** Extra boolean labels, besides `Yes` / `No`. */
+    booleanLabels?: GridBooleanLabels;
+}
+
+/**
+ * Parses cell text by the column `type`, without `valueParser`:
+ *
+ * | type | accepted |
+ * | :--- | :--- |
+ * | `string` (default), `image` | the text as is (an empty cell is `''`) |
+ * | `number` | `parseNumberText` |
+ * | `date` | `parseDateText` |
+ * | `boolean` | `parseBooleanText` |
+ * | `singleSelect` | `parseSingleSelectText` |
+ *
+ * An empty cell is `null` for every type but `string` / `image`.
+ */
+export function parseValueByType(text: string, colDef: ParserColumn | undefined, options?: GridParseTextOptions): GridParsedValue {
+    switch (colDef?.type) {
+        case 'number': return parseNumberText(text);
+        case 'date': return parseDateText(text, options?.current);
+        case 'boolean': return parseBooleanText(text, options?.booleanLabels);
+        case 'singleSelect': return parseSingleSelectText(text, colDef.valueOptions);
+        default: return valid(text);
+    }
+}
+
+/**
+ * Parses the text pasted into one cell: the column's `valueParser` when it has one (a throw, or a
+ * returned `undefined`, rejects the text), otherwise `parseValueByType`.
+ */
+export function parseCellText<R extends GridValidRowModel>(
+    text: string,
+    colDef: GridColDef<R>,
+    row: R,
+    options?: GridParseTextOptions,
+): GridParsedValue {
+    const { valueParser } = colDef;
+    if (!valueParser) return parseValueByType(text, colDef as unknown as ParserColumn, options);
+    let value: unknown;
+    try {
+        value = valueParser(text, { row, field: colDef.field, colDef });
+    } catch {
+        return INVALID;
+    }
+    return value === undefined ? INVALID : valid(value);
+}