@svgrid/grid 1.1.0 → 1.1.1

package/src/clipboard.test.ts

@@ -63,6 +63,24 @@ function makeCtx(opts: FakeOptions = {}) {
     },
     _rows: buildRows(),
     selectionRange: { anchor: null, focus: null },
+    selectionRanges: [] as Array<{ anchor: any; focus: any }>,
+    // Mirrors the real controller's getSelectionRects: committed ranges + active.
+    getSelectionRects(): Array<{ minRow: number; maxRow: number; minCol: number; maxCol: number }> {
+      const rects: Array<{ minRow: number; maxRow: number; minCol: number; maxCol: number }> = []
+      const norm = (r: { anchor: any; focus: any }) =>
+        r?.anchor && r?.focus
+          ? {
+              minRow: Math.min(r.anchor.rowIndex, r.focus.rowIndex),
+              maxRow: Math.max(r.anchor.rowIndex, r.focus.rowIndex),
+              minCol: Math.min(r.anchor.colIndex, r.focus.colIndex),
+              maxCol: Math.max(r.anchor.colIndex, r.focus.colIndex),
+            }
+          : null
+      for (const r of ctx.selectionRanges) { const n = norm(r); if (n) rects.push(n) }
+      const active = norm(ctx.selectionRange)
+      if (active) rects.push(active)
+      return rects
+    },
     fillDrag: null,
     editedCellValues: {},
     userHasActivatedCell: false,
@@ -528,6 +546,37 @@ describe('copySelectionToClipboard', () => {
     expect(writeText).toHaveBeenCalledWith('a0\tb0\na1\tb1')
   })
 
+  it('prepends a header row when copyHeadersToClipboard is set', () => {
+    const ctx = makeCtx({
+      data: [
+        { a: 'a0', b: 'b0' },
+        { a: 'a1', b: 'b1' },
+      ],
+    })
+    ctx.props.copyHeadersToClipboard = true
+    ctx.selectionRange = {
+      anchor: { rowIndex: 0, colIndex: 0 },
+      focus: { rowIndex: 1, colIndex: 1 },
+    }
+    const cb = createClipboard(ctx)
+    cb.copySelectionToClipboard()
+    expect(writeText).toHaveBeenCalledWith('a\tb\na0\tb0\na1\tb1')
+  })
+
+  it('runs each value through processCellForClipboard', () => {
+    const ctx = makeCtx({
+      data: [{ a: 'a0', b: 'b0' }],
+    })
+    ctx.props.processCellForClipboard = ({ value }: { value: unknown }) => `[${value}]`
+    ctx.selectionRange = {
+      anchor: { rowIndex: 0, colIndex: 0 },
+      focus: { rowIndex: 0, colIndex: 1 },
+    }
+    const cb = createClipboard(ctx)
+    cb.copySelectionToClipboard()
+    expect(writeText).toHaveBeenCalledWith('[a0]\t[b0]')
+  })
+
   it('emits empty strings for missing columns and nullish values', () => {
     const ctx = makeCtx({
       columns: [{ id: 'a', field: 'a' }],

package/src/clipboard.ts

@@ -415,32 +415,60 @@ export function createClipboard<
   }
 
   function copySelectionToClipboard() {
-    const anchor = ctx.selectionRange.anchor;
-    const focus = ctx.selectionRange.focus;
-    if (!anchor || !focus) return;
-    const minRow = Math.min(anchor.rowIndex, focus.rowIndex);
-    const maxRow = Math.max(anchor.rowIndex, focus.rowIndex);
-    const minCol = Math.min(anchor.colIndex, focus.colIndex);
-    const maxCol = Math.max(anchor.colIndex, focus.colIndex);
-    const lines: Array<string> = [];
-    for (let r = minRow; r <= maxRow; r += 1) {
-      const row = ctx.allRows[r];
-      if (!row || isGroupRow(row)) continue;
-      const cells: Array<string> = [];
-      for (let c = minCol; c <= maxCol; c += 1) {
-        const column = ctx.allColumns[c];
-        if (!column) {
-          cells.push("");
-          continue;
+    // Copy every selected rectangle. Each range becomes a TSV block; multiple
+    // ranges are stacked and separated by a blank line (Sheets-style).
+    const rects = ctx.getSelectionRects() as Array<{
+      minRow: number;
+      maxRow: number;
+      minCol: number;
+      maxCol: number;
+    }>;
+    if (!rects.length) return;
+    // Optional: prepend a header row (Excel "copy with headers") and/or run
+    // each value through a consumer hook before it hits the clipboard.
+    const withHeaders = ctx.props.copyHeadersToClipboard === true;
+    const processCell = ctx.props.processCellForClipboard as
+      | ((params: { value: unknown; column: unknown; row: unknown; rowIndex: number; columnId: string }) => unknown)
+      | undefined;
+    const blocks: Array<string> = [];
+    for (const rect of rects) {
+      const lines: Array<string> = [];
+      if (withHeaders) {
+        const header: Array<string> = [];
+        for (let c = rect.minCol; c <= rect.maxCol; c += 1) {
+          const column = ctx.allColumns[c];
+          header.push(column ? toolPanelHeaderLabel(column) : "");
+        }
+        lines.push(header.join("\t"));
+      }
+      for (let r = rect.minRow; r <= rect.maxRow; r += 1) {
+        const row = ctx.allRows[r];
+        if (!row || isGroupRow(row)) continue;
+        const cells: Array<string> = [];
+        for (let c = rect.minCol; c <= rect.maxCol; c += 1) {
+          const column = ctx.allColumns[c];
+          if (!column) {
+            cells.push("");
+            continue;
+          }
+          const base = getColumnBaseValue(row, column);
+          let value: unknown = ctx.getCellDisplayValue(row.id, column.id, base);
+          if (processCell) {
+            value = processCell({
+              value,
+              column,
+              row: row.original,
+              rowIndex: r,
+              columnId: column.id,
+            });
+          }
+          cells.push(String(value ?? ""));
         }
-        const base = getColumnBaseValue(row, column);
-        const display = ctx.getCellDisplayValue(row.id, column.id, base);
-        cells.push(String(display ?? ""));
+        lines.push(cells.join("\t"));
       }
-      lines.push(cells.join("\t"));
+      blocks.push(lines.join("\n"));
     }
-    const text = lines.join("\n");
-    writeClipboardText(text);
+    writeClipboardText(blocks.join("\n\n"));
   }
 
   /**

package/src/column-groups.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import { computeColumnGroupMeta, hiddenLeavesForCollapse } from './column-groups'
+
+// A group "Q1" with an always-on Total plus Jan/Feb that only show when open.
+const columns = [
+  { field: 'name' },
+  {
+    id: 'q1',
+    header: 'Q1',
+    columns: [
+      { field: 'q1Total' },
+      { field: 'jan', columnGroupShow: 'open' },
+      { field: 'feb', columnGroupShow: 'open' },
+    ],
+  },
+  {
+    id: 'q2',
+    header: 'Q2',
+    openByDefault: true,
+    columns: [
+      { field: 'q2Total', columnGroupShow: 'closed' },
+      { field: 'apr', columnGroupShow: 'open' },
+    ],
+  },
+]
+
+describe('computeColumnGroupMeta', () => {
+  it('marks groups with columnGroupShow children as collapsible', () => {
+    const meta = computeColumnGroupMeta(columns)
+    expect([...meta.collapsibleGroupIds].sort()).toEqual(['q1', 'q2'])
+    expect(meta.defaultOpen.get('q1')).toBe(false)
+    expect(meta.defaultOpen.get('q2')).toBe(true)
+  })
+  it('maps controlled leaves to their group + show mode', () => {
+    const meta = computeColumnGroupMeta(columns)
+    expect(meta.leafControl.get('jan')).toEqual({ groupId: 'q1', show: 'open' })
+    expect(meta.leafControl.get('q2Total')).toEqual({ groupId: 'q2', show: 'closed' })
+    // untagged always-on column is not controlled
+    expect(meta.leafControl.has('q1Total')).toBe(false)
+    expect(meta.leafControl.has('name')).toBe(false)
+  })
+})
+
+describe('hiddenLeavesForCollapse', () => {
+  const meta = computeColumnGroupMeta(columns)
+  it('hides open-columns while collapsed, shows them while expanded', () => {
+    const collapsed = new Set(['q1'])
+    const hidden = hiddenLeavesForCollapse(meta, collapsed)
+    expect(hidden.jan).toBe(true)
+    expect(hidden.feb).toBe(true)
+    expect(hidden.q1Total).toBeUndefined() // always on
+  })
+  it('hides closed-columns while expanded', () => {
+    const collapsed = new Set<string>() // q2 expanded
+    const hidden = hiddenLeavesForCollapse(meta, collapsed)
+    expect(hidden.q2Total).toBe(true) // 'closed' hides when expanded
+    expect(hidden.apr).toBeUndefined() // 'open' shows when expanded
+  })
+})

package/src/column-groups.ts

@@ -0,0 +1,80 @@
+// Collapsible column groups (AG-Grid `columnGroupShow`). A column group can
+// carry a collapse toggle: its child columns tagged `columnGroupShow: 'open'`
+// show only when the group is expanded, `'closed'` show only when collapsed,
+// and untagged children always show.
+//
+// This module derives, from the user's column tree, the pure metadata the
+// controller needs: which groups are collapsible, their default state, and each
+// controlled leaf's group + show-mode. The controller turns that into a hidden
+// map (merged into column visibility) AND feeds the same hidden set into the
+// group-header colspan/width math, so headers stay aligned with the leaves.
+
+export type ColumnGroupShow = "open" | "closed";
+
+export type ColumnGroupMeta = {
+  /** Group ids that render a collapse toggle. */
+  collapsibleGroupIds: Set<string>;
+  /** Group id -> whether it starts expanded (openByDefault). */
+  defaultOpen: Map<string, boolean>;
+  /** Leaf column id -> the group controlling it + its show mode. */
+  leafControl: Map<string, { groupId: string; show: ColumnGroupShow }>;
+};
+
+// Mirror the id resolution used by the group-header derivation so group ids and
+// leaf ids line up across both.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function idOf(def: any, parentId: string | undefined, ix: number): string {
+  return def.id ?? def.field ?? `${parentId ?? "col"}_d_${ix}`;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function computeColumnGroupMeta(columns: ReadonlyArray<any>): ColumnGroupMeta {
+  const collapsibleGroupIds = new Set<string>();
+  const defaultOpen = new Map<string, boolean>();
+  const leafControl = new Map<string, { groupId: string; show: ColumnGroupShow }>();
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  function walk(defs: ReadonlyArray<any>, parentId: string | undefined, controllingGroup: string | undefined) {
+    defs.forEach((def, ix) => {
+      const id = idOf(def, parentId, ix);
+      if (def.columns?.length) {
+        // A group is collapsible when any DIRECT child declares columnGroupShow.
+        const collapsible = def.columns.some(
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (c: any) => c.columnGroupShow === "open" || c.columnGroupShow === "closed",
+        );
+        if (collapsible) {
+          collapsibleGroupIds.add(id);
+          defaultOpen.set(id, def.openByDefault === true);
+        }
+        walk(def.columns, id, collapsible ? id : controllingGroup);
+      } else {
+        const show = def.columnGroupShow;
+        if ((show === "open" || show === "closed") && controllingGroup) {
+          leafControl.set(id, { groupId: controllingGroup, show });
+        }
+      }
+    });
+  }
+
+  walk(columns, undefined, undefined);
+  return { collapsibleGroupIds, defaultOpen, leafControl };
+}
+
+/**
+ * Which leaf ids are hidden right now, given the set of collapsed group ids.
+ * `'open'` leaves hide while their group is collapsed; `'closed'` leaves hide
+ * while it is expanded.
+ */
+export function hiddenLeavesForCollapse(
+  meta: ColumnGroupMeta,
+  collapsed: ReadonlySet<string>,
+): Record<string, boolean> {
+  const hidden: Record<string, boolean> = {};
+  for (const [leafId, ctrl] of meta.leafControl) {
+    const isCollapsed = collapsed.has(ctrl.groupId);
+    const hide = ctrl.show === "open" ? isCollapsed : !isCollapsed;
+    if (hide) hidden[leafId] = true;
+  }
+  return hidden;
+}

package/src/column-types.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import { inferCellDataType, resolveColumnTypes } from './column-types'
+
+describe('inferCellDataType', () => {
+  it('classifies primitives', () => {
+    expect(inferCellDataType(42)).toBe('number')
+    expect(inferCellDataType(true)).toBe('boolean')
+    expect(inferCellDataType(new Date())).toBe('date')
+    expect(inferCellDataType('2026-06-27')).toBe('dateString')
+    expect(inferCellDataType('2026-06-27T10:00:00Z')).toBe('dateString')
+    expect(inferCellDataType('hello')).toBe('text')
+  })
+  it('returns undefined for null/undefined so nothing is forced', () => {
+    expect(inferCellDataType(null)).toBeUndefined()
+    expect(inferCellDataType(undefined)).toBeUndefined()
+  })
+})
+
+describe('resolveColumnTypes', () => {
+  it('maps explicit cellDataType to editorType + format', () => {
+    const cols = [
+      { field: 'name', cellDataType: 'text' },
+      { field: 'age', cellDataType: 'number' },
+      { field: 'active', cellDataType: 'boolean' },
+      { field: 'joined', cellDataType: 'date' },
+      { field: 'iso', cellDataType: 'dateString' },
+    ]
+    const out = resolveColumnTypes(cols, undefined, false)
+    expect(out[0].editorType).toBe('text')
+    expect(out[1].editorType).toBe('number')
+    expect(out[2].editorType).toBe('checkbox')
+    expect(out[3].editorType).toBe('date')
+    expect(out[3].format).toEqual({ type: 'date' })
+    expect(out[4].editorType).toBe('date')
+    expect(out[4].format).toBeUndefined()
+  })
+
+  it('never overrides an explicit editorType or format', () => {
+    const cols = [{ field: 'age', cellDataType: 'number', editorType: 'text', format: { type: 'currency' } }]
+    const out = resolveColumnTypes(cols, undefined, false)
+    expect(out[0].editorType).toBe('text')
+    expect(out[0].format).toEqual({ type: 'currency' })
+  })
+
+  it('infers from a sample row only when infer=true and nothing is declared', () => {
+    const cols = [
+      { field: 'age' },
+      { field: 'name' },
+      { field: 'when' },
+      { field: 'flag' },
+    ]
+    const sample = { age: 30, name: 'Ada', when: '2026-01-02', flag: false }
+    const off = resolveColumnTypes(cols, sample, false)
+    expect(off[0].editorType).toBeUndefined() // inference off
+
+    const on = resolveColumnTypes(cols, sample, true)
+    expect(on[0].editorType).toBe('number')
+    expect(on[1].editorType).toBe('text')
+    expect(on[2].editorType).toBe('date')
+    expect(on[3].editorType).toBe('checkbox')
+  })
+
+  it('recurses into header groups', () => {
+    const cols = [{ header: 'Group', columns: [{ field: 'age', cellDataType: 'number' }] }]
+    const out = resolveColumnTypes(cols, undefined, false)
+    expect(out[0].columns[0].editorType).toBe('number')
+  })
+})

package/src/column-types.ts

@@ -0,0 +1,82 @@
+// cellDataType resolution. A column's `cellDataType` (or grid-level
+// `inferColumnTypes`) is a high-level shorthand that fills in `editorType`,
+// `format`, and - transitively, via `getColumnAlign` and the filter-operator
+// tables, which both key off `editorType` - alignment and filter operators.
+//
+// Anything set explicitly on the ColumnDef always wins; this only fills gaps.
+// Resolution happens once when columns are ingested, producing plain ColumnDef
+// objects, so every downstream reader (editing, filtering, formatting,
+// alignment) sees a normal column with no new code paths.
+export type CellDataType = "text" | "number" | "boolean" | "date" | "dateString";
+
+type TypeDefaults = {
+  editorType: string;
+  format?: { type: string };
+};
+
+function defaultsFor(dt: CellDataType): TypeDefaults {
+  switch (dt) {
+    case "number":
+      return { editorType: "number" };
+    case "boolean":
+      return { editorType: "checkbox" };
+    case "date":
+      return { editorType: "date", format: { type: "date" } };
+    case "dateString":
+      // ISO date strings ('2026-06-27') - date editor, but no Date coercion.
+      return { editorType: "date" };
+    case "text":
+    default:
+      return { editorType: "text" };
+  }
+}
+
+/** Best-effort inference of a column's data type from a sample value. */
+export function inferCellDataType(value: unknown): CellDataType | undefined {
+  if (value == null) return undefined;
+  if (typeof value === "number" && Number.isFinite(value)) return "number";
+  if (typeof value === "boolean") return "boolean";
+  if (value instanceof Date) return "date";
+  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}([T\s]|$)/.test(value)) {
+    return "dateString";
+  }
+  return "text";
+}
+
+/**
+ * Resolve `cellDataType` (explicit or, when `infer` is on, inferred from
+ * `sampleRow`) into concrete `editorType` / `format` defaults. Explicit fields
+ * on the ColumnDef are preserved. Columns that resolve to no type are returned
+ * untouched. Nested column groups are resolved recursively.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function resolveColumnTypes(
+  columns: ReadonlyArray<any>,
+  sampleRow: unknown,
+  infer: boolean,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any[] {
+  return columns.map((col) => {
+    // Recurse into header groups first.
+    if (col.columns && col.columns.length) {
+      return { ...col, columns: resolveColumnTypes(col.columns, sampleRow, infer) };
+    }
+    // An explicit editorType means the author already chose - don't override.
+    const hasExplicitEditor = col.editorType != null;
+    let dt: CellDataType | undefined = col.cellDataType;
+    if (!dt && infer && !hasExplicitEditor && sampleRow != null) {
+      const field = col.field;
+      const raw =
+        col.accessorFn?.(sampleRow) ??
+        (typeof field === "string" ? (sampleRow as Record<string, unknown>)[field] : undefined);
+      dt = inferCellDataType(raw);
+    }
+    if (!dt) return col;
+    const d = defaultsFor(dt);
+    return {
+      ...col,
+      editorType: col.editorType ?? d.editorType,
+      format: col.format ?? d.format,
+    };
+  });
+}

package/src/core.ts

@@ -32,6 +32,32 @@ export type CellContext<TData extends RowData> = {
   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:
@@ -153,6 +179,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'
@@ -201,6 +266,19 @@ 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