@svgrid/grid 1.1.0 → 1.1.1

package/dist/core.d.ts

@@ -37,6 +37,30 @@ export type CellContext<TData extends RowData> = {
     table: SvGrid<TData>;
     getValue: () => unknown;
 };
+/** Params passed to a column's `colSpan(...)` / `rowSpan(...)` callbacks. */
+export type CellSpanParams<TData extends RowData = RowData> = {
+    /** The row's underlying data object. */
+    data: TData;
+    /** Display-row index in the current (filtered/sorted) row set. */
+    rowIndex: number;
+    /** The column's id. */
+    columnId: string;
+    /** The cell's base value for this column. */
+    value: unknown;
+};
+/** Params passed to a column's `valueParser(...)` on edit commit. */
+export type ValueParserParams<TData extends RowData = RowData> = {
+    /** The value after built-in per-`editorType` coercion. */
+    newValue: unknown;
+    /** The cell's previous value. */
+    oldValue: unknown;
+    /** The raw string the editor produced (pre-coercion). */
+    rawInput: string;
+    /** The row's underlying data object. */
+    data: TData;
+    /** The column's id. */
+    columnId: string;
+};
 /**
  * Context passed to a custom `cellEditor` snippet/component. Three write
  * helpers cover the lifecycle:
@@ -110,6 +134,45 @@ export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> =
     footer?: ColumnDefTemplate<HeaderContext<TData>>;
     cell?: ColumnDefTemplate<CellContext<TData>>;
     columns?: Array<ColumnDef<TFeatures, TData>>;
+    /**
+     * Declarative cell spanning (merged cells). Return how many COLUMNS this
+     * cell spans to the right (1 = no span). Value-driven, AG-Grid-style. Feed
+     * `spansToMerges(rows, columns)` into `spreadsheetLayout` to apply - it uses
+     * the same real `colspan`/`rowspan` merge engine (no separate code path).
+     */
+    colSpan?: (params: CellSpanParams<TData>) => number;
+    /**
+     * Declarative cell spanning (merged cells). Return how many ROWS this cell
+     * spans downward (1 = no span). See `colSpan` for how to apply.
+     */
+    rowSpan?: (params: CellSpanParams<TData>) => number;
+    /**
+     * High-level data type for the column. A convenience that resolves to the
+     * right `editorType`, alignment, date `format`, and filter operators without
+     * setting each by hand:
+     *   'text' → text editor, left-aligned
+     *   'number' → number editor, right-aligned, numeric filter operators
+     *   'boolean' → checkbox editor, centered
+     *   'date' → date editor (Date values), right-aligned, `{ type: 'date' }` format
+     *   'dateString' → date editor for ISO date STRINGS (e.g. '2026-06-27')
+     * Anything you set explicitly (`editorType`, `align`, `format`) still wins -
+     * `cellDataType` only fills the gaps. Grid-level `inferColumnTypes` infers
+     * this from the first data row for columns that declare neither.
+     */
+    cellDataType?: 'text' | 'number' | 'boolean' | 'date' | 'dateString';
+    /**
+     * For a column INSIDE a collapsible column group: `'open'` shows this column
+     * only while the group is expanded, `'closed'` only while collapsed. Omit to
+     * always show it. Setting it on any direct child gives the parent group a
+     * collapse toggle. Pair with `openByDefault` on the group.
+     */
+    columnGroupShow?: 'open' | 'closed';
+    /**
+     * For a GROUP column (one with `columns: [...]`): start the group expanded.
+     * Defaults to `false` (collapsed), matching AG Grid - so only the always-on
+     * and `columnGroupShow: 'closed'` children show until the user expands it.
+     */
+    openByDefault?: boolean;
     editorType?: 'text' | 'number' | 'date' | 'datetime' | 'time' | 'password' | 'checkbox' | 'list' | 'chips' | 'select' | 'rich-select' | 'autocomplete' | 'textarea' | 'color' | 'rating';
     /**
      * Custom in-cell editor. Receives the cell context PLUS a `commit(value)`
@@ -143,6 +206,21 @@ export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> =
      * `false`.
      */
     editable?: boolean | ((context: CellContext<TData>) => boolean);
+    /**
+     * Transform the committed edit value before it is written to the row.
+     * Runs after the built-in per-`editorType` coercion, so `newValue` is
+     * already type-parsed; return the final value to store (e.g. round a
+     * number, uppercase a code, look up an id). AG-Grid-style `valueParser`.
+     */
+    valueParser?: (params: ValueParserParams<TData>) => unknown;
+    /**
+     * Briefly flash / highlight this column's cell when its value changes
+     * (streaming feeds, edits, server pushes). `true` uses the default flash;
+     * pass `{ className }` to apply your own animation class instead.
+     */
+    cellFlash?: boolean | {
+        className?: string;
+    };
     /**
      * When `false`, this column never shows a sort indicator and clicking
      * its header is a no-op - `api.setSort(thisColumn, ...)` is also
@@ -203,6 +281,13 @@ export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> =
     sparkline?: SparklineConfig;
     /** Initial column width in pixels. Falls back to the grid's `columnWidth` prop. */
     width?: number;
+    /**
+     * Initial visibility. Set `false` to start the column hidden while still
+     * listing it in the Choose Columns UI for the user to re-enable. Applied
+     * once at mount; after that `api.setColumnVisible` / user toggles win.
+     * On a group column, `false` hides the whole group's leaf columns.
+     */
+    visible?: boolean;
     /**
      * Horizontal alignment for header and body cells. When omitted, the
      * default is inferred from `editorType`:

package/dist/editing.d.ts

@@ -13,6 +13,12 @@ export declare function createEditing<TFeatures extends TableFeatures = TableFea
     getRowColumnValue: (row: Row<TData>, columnId: string) => unknown;
     getCellDisplayValue: (rowId: string, columnId: string, baseValue: unknown) => any;
     startEditingWithChar: (rowIndex: number, colIndex: number, char: string) => boolean;
+    startEditing: (rowIndex: number, columnId: string) => boolean;
+    stopEditing: (cancel?: boolean) => boolean;
+    startFullRowEdit: (rowIndex: number) => boolean;
+    setFullRowDraft: (columnId: string, value: unknown) => void;
+    commitFullRowEdit: () => void;
+    cancelFullRowEdit: () => void;
     saveEditingCell: () => void;
     applyHistoryStep: (step: HistoryStep, direction: "undo" | "redo") => void;
     updateEditingCellValue: (value: string) => void;
@@ -20,5 +26,6 @@ export declare function createEditing<TFeatures extends TableFeatures = TableFea
     focusOnMount: (node: HTMLInputElement | HTMLTextAreaElement) => void;
     onCellDoubleClick: (rowIndex: number, colIndex: number) => void;
     pasteFromClipboard: () => Promise<void>;
+    onGridPaste: (event: ClipboardEvent) => void;
 };
 export {};

package/dist/editing.js

@@ -110,27 +110,39 @@ export function createEditing(ctx) {
             multiple: column?.columnDef.editorMultiple === true,
         });
         let oldValue = undefined;
+        let finalValue = parsedValue;
         if (row?.original && column?.columnDef.field) {
             oldValue = row.original[column.columnDef.field];
+            // Per-column valueParser refines the type-coerced value before storing.
+            const parser = column.columnDef.valueParser;
+            if (parser) {
+                finalValue = parser({
+                    newValue: parsedValue,
+                    oldValue,
+                    rawInput: ctx.editingCell.value,
+                    data: row.original,
+                    columnId: ctx.editingCell.columnId,
+                });
+            }
             row.original[column.columnDef.field] =
-                parsedValue;
+                finalValue;
         }
         const key = getCellKey(ctx.editingCell.rowId, ctx.editingCell.columnId);
         ctx.editedCellValues = {
             ...ctx.editedCellValues,
-            [key]: parsedValue,
+            [key]: finalValue,
         };
         ctx.grid.store.setState((prev) => ({ ...prev }));
         // Record into the history at the current pointer. Any forward
         // history (steps the user could have redone) is truncated - this
         // is the standard "edit invalidates redo" rule.
-        if (oldValue !== parsedValue && row?.original && column?.columnDef.field) {
+        if (oldValue !== finalValue && row?.original && column?.columnDef.field) {
             const step = {
                 rowId: ctx.editingCell.rowId,
                 columnId: ctx.editingCell.columnId,
                 field: column.columnDef.field,
                 before: oldValue,
-                after: parsedValue,
+                after: finalValue,
             };
             const truncated = ctx.history.slice(0, ctx.historyPtr + 1);
             truncated.push(step);
@@ -156,7 +168,7 @@ export function createEditing(ctx) {
                 rowIndex,
                 columnId: column.id,
                 oldValue,
-                newValue: parsedValue,
+                newValue: finalValue,
                 row: row.original,
             });
         }
@@ -228,6 +240,13 @@ export function createEditing(ctx) {
             return;
         if (isGroupRow(row))
             return;
+        // Full-row editing: put the whole row into edit instead of one cell.
+        if (ctx.props.fullRowEditing) {
+            if (ctx.fullRowEdit?.rowId === row.id)
+                return;
+            startFullRowEdit(rowIndex);
+            return;
+        }
         if (!isCellEditable(column, row))
             return;
         if (ctx.editingCell?.rowId === row.id && ctx.editingCell?.columnId === column.id)
@@ -255,6 +274,12 @@ export function createEditing(ctx) {
         ctx.setSelection(rowIndex, colIndex);
     }
     async function pasteFromClipboard() {
+        // Preferred path: the async Clipboard API. Requires a secure context
+        // (HTTPS or localhost) AND read permission; it also works on Firefox,
+        // where the native `paste` event does NOT fire on a non-editable element.
+        // On plain HTTP (a XAMPP/Apache LAN host) `navigator.clipboard` is
+        // undefined - there the Ctrl+V keydown handler skips preventDefault and
+        // lets the browser deliver a native `paste` event to `onGridPaste`.
         if (!navigator.clipboard?.readText)
             return;
         let text;
@@ -264,6 +289,28 @@ export function createEditing(ctx) {
         catch {
             return;
         }
+        applyPastedText(text);
+    }
+    /**
+     * Native `paste` ClipboardEvent fallback (insecure-context path). A real
+     * Ctrl/Cmd+V on the focused grid root fires this with `clipboardData`
+     * readable even over plain HTTP and with no permission prompt. Wired on the
+     * grid root in SvGrid.svelte; the keydown handler lets the gesture through
+     * (no preventDefault) whenever the async API is unavailable.
+     */
+    function onGridPaste(event) {
+        // When the async API is available the keydown handler already pasted via
+        // pasteFromClipboard(); ignore the (suppressed) native event so we don't
+        // paste twice.
+        if (typeof navigator.clipboard?.readText === "function")
+            return;
+        const text = event.clipboardData?.getData("text/plain") ?? "";
+        if (!text)
+            return;
+        event.preventDefault();
+        applyPastedText(text);
+    }
+    function applyPastedText(text) {
         const anchor = ctx.selectionRange.anchor ?? ctx.grid.getState().activeCell;
         if (!anchor)
             return;
@@ -326,12 +373,150 @@ export function createEditing(ctx) {
         ctx.internalData = next;
         ctx.grid.store.setState((prev) => ({ ...prev }));
     }
+    /** Programmatically begin editing a cell (mirrors a double-click). */
+    function startEditing(rowIndex, columnId) {
+        if (!ctx.editingEnabled)
+            return false;
+        const row = ctx.allRows[rowIndex];
+        if (!row || isGroupRow(row))
+            return false;
+        const colIndex = ctx.allColumns.findIndex((c) => c.id === columnId);
+        if (colIndex < 0)
+            return false;
+        const column = ctx.allColumns[colIndex];
+        if (!isCellEditable(column, row))
+            return false;
+        if (ctx.editingCell?.rowId === row.id &&
+            ctx.editingCell?.columnId === columnId)
+            return true;
+        onCellDoubleClick(rowIndex, colIndex);
+        return (ctx.editingCell?.rowId === row.id &&
+            ctx.editingCell?.columnId === columnId);
+    }
+    /** Commit (default) or cancel the active edit, if any. */
+    function stopEditing(cancel = false) {
+        if (!ctx.editingCell)
+            return false;
+        if (cancel) {
+            ctx.editingCell = null;
+        }
+        else {
+            saveEditingCell();
+        }
+        return true;
+    }
+    // ---- Full-row editing -------------------------------------------------
+    /** Put the whole row into edit mode, seeding a draft per editable column. */
+    function startFullRowEdit(rowIndex) {
+        if (!ctx.editingEnabled || !ctx.props.fullRowEditing)
+            return false;
+        const row = ctx.allRows[rowIndex];
+        if (!row || isGroupRow(row))
+            return false;
+        if (ctx.fullRowEdit && ctx.fullRowEdit.rowId !== row.id)
+            commitFullRowEdit();
+        ctx.editingCell = null; // never both at once
+        const draft = {};
+        for (const column of ctx.allColumns) {
+            if (!column.columnDef.field)
+                continue;
+            if (!isCellEditable(column, row))
+                continue;
+            draft[column.id] = getCellDisplayValue(row.id, column.id, row.getCellValueByColumnId(column.id));
+        }
+        ctx.fullRowEdit = { rowId: row.id, draft };
+        ctx.setActiveCell(rowIndex, Math.max(0, ctx.allColumns.findIndex((c) => c.id in draft)));
+        return true;
+    }
+    /** Stage one column's draft value during full-row editing. */
+    function setFullRowDraft(columnId, value) {
+        const fr = ctx.fullRowEdit;
+        if (!fr)
+            return;
+        ctx.fullRowEdit = { rowId: fr.rowId, draft: { ...fr.draft, [columnId]: value } };
+    }
+    /** Commit every drafted column of the full-row edit in one data update. */
+    function commitFullRowEdit() {
+        const fr = ctx.fullRowEdit;
+        if (!fr)
+            return;
+        const row = ctx.allRows.find((r) => r.id === fr.rowId);
+        if (!row?.original) {
+            ctx.fullRowEdit = null;
+            return;
+        }
+        const changed = [];
+        for (const column of ctx.allColumns) {
+            if (!(column.id in fr.draft))
+                continue;
+            const field = column.columnDef.field;
+            if (!field)
+                continue;
+            const editorType = (column.columnDef.editorType ?? "text");
+            const parsed = parseEditorValue(editorType, fr.draft[column.id], {
+                multiple: column.columnDef.editorMultiple === true,
+            });
+            const oldValue = row.original[field];
+            const parser = column.columnDef.valueParser;
+            const finalValue = parser
+                ? parser({
+                    newValue: parsed,
+                    oldValue,
+                    rawInput: String(fr.draft[column.id] ?? ""),
+                    data: row.original,
+                    columnId: column.id,
+                })
+                : parsed;
+            if (oldValue !== finalValue) {
+                row.original[field] = finalValue;
+                const key = getCellKey(fr.rowId, column.id);
+                ctx.editedCellValues = { ...ctx.editedCellValues, [key]: finalValue };
+                changed.push({ columnId: column.id, field, before: oldValue, after: finalValue });
+            }
+        }
+        // Record the whole-row change as consecutive history steps.
+        if (changed.length) {
+            let hist = ctx.history.slice(0, ctx.historyPtr + 1);
+            for (const c of changed) {
+                hist.push({ rowId: fr.rowId, columnId: c.columnId, field: c.field, before: c.before, after: c.after });
+            }
+            if (hist.length > ctx.UNDO_LIMIT)
+                hist = hist.slice(hist.length - ctx.UNDO_LIMIT);
+            ctx.history = hist;
+            ctx.historyPtr = ctx.history.length - 1;
+            ctx.historyVersion += 1;
+        }
+        ctx.grid.store.setState((prev) => ({ ...prev }));
+        if (ctx.props.onCellValueChange && changed.length) {
+            const rowIndex = ctx.internalData.indexOf(row.original);
+            for (const c of changed) {
+                ctx.props.onCellValueChange({
+                    rowIndex,
+                    columnId: c.columnId,
+                    oldValue: c.before,
+                    newValue: c.after,
+                    row: row.original,
+                });
+            }
+        }
+        ctx.fullRowEdit = null;
+    }
+    /** Discard the full-row edit. */
+    function cancelFullRowEdit() {
+        ctx.fullRowEdit = null;
+    }
     return {
         isCellEditable,
         isCellEditableAt,
         getRowColumnValue,
         getCellDisplayValue,
         startEditingWithChar,
+        startEditing,
+        stopEditing,
+        startFullRowEdit,
+        setFullRowDraft,
+        commitFullRowEdit,
+        cancelFullRowEdit,
         saveEditingCell,
         applyHistoryStep,
         updateEditingCellValue,
@@ -339,5 +524,6 @@ export function createEditing(ctx) {
         focusOnMount,
         onCellDoubleClick,
         pasteFromClipboard,
+        onGridPaste,
     };
 }

package/dist/editing.test.d.ts

@@ -0,0 +1 @@
+export {};