@svgrid/grid 1.1.0 → 1.1.2

package/src/row-drag.ts

@@ -0,0 +1,255 @@
+// Managed row dragging - reorder rows within a grid and move rows between
+// grids that share a `rowDragGroup`. "Managed" means the grid mutates its own
+// `internalData` on drop (splice out of the source, splice into the target) so
+// consumers get working drag-and-drop with zero wiring; an optional
+// `onRowDragEnd` callback lets them mirror the change into their own state.
+//
+// Cross-grid coordination rides on a module-level singleton (`bus`). Because
+// every SvGrid instance in a bundle shares this module, the source grid can
+// hand the target grid both the dragged row and a closure that removes it from
+// the source - the missing half of an HTML5 drag payload, which only carries
+// strings. Rows are matched by object identity, so this works without
+// `getRowId`.
+
+type RowDragBus = {
+  group: string | null;
+  gridId: number;
+  row: unknown;
+  removeFromSource: () => void;
+  sourceProps: { onRowDragEnd?: (e: RowDragEndEvent) => void };
+};
+
+export type RowDragEndEvent<TData = unknown> = {
+  row: TData;
+  toIndex: number;
+  sameGrid: boolean;
+  fromGridId: number;
+  toGridId: number;
+};
+
+// Shared across all grids in the bundle - this is what makes grid-to-grid work.
+let bus: RowDragBus | null = null;
+let gridSeq = 0;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createRowDrag<TFeatures, TData>(ctx: any) {
+  const gridId = ++gridSeq;
+
+  const managed = () => ctx.props.rowDragManaged === true;
+  const group = (): string | null => ctx.props.rowDragGroup ?? null;
+
+  function originalAt(rowIndex: number): unknown {
+    const r = ctx.allRows[rowIndex];
+    return r ? r.original : null;
+  }
+
+  // Can THIS grid accept the row currently on the bus? Same grid always may
+  // (a reorder); a different grid only when both opt into the same group.
+  function canAccept(): boolean {
+    if (!managed() || !bus) return false;
+    if (bus.gridId === gridId) return true;
+    return bus.group != null && bus.group === group();
+  }
+
+  function clearIndicators() {
+    ctx.rowDragActive = false;
+    ctx.rowDropIndex = null;
+    ctx.rowDropSide = null;
+  }
+
+  function emitEnd(row: unknown, toIndex: number, sameGrid: boolean, fromGridId: number) {
+    ctx.props.onRowDragEnd?.({
+      row,
+      toIndex,
+      sameGrid,
+      fromGridId,
+      toGridId: gridId,
+    } as RowDragEndEvent<TData>);
+  }
+
+  function onRowDragStart(e: DragEvent, rowIndex: number) {
+    if (!managed()) return;
+    const row = originalAt(rowIndex);
+    if (row == null) return;
+    bus = {
+      group: group(),
+      gridId,
+      row,
+      sourceProps: ctx.props,
+      removeFromSource: () => {
+        ctx.internalData = (ctx.internalData as unknown[]).filter((r) => r !== row);
+      },
+    };
+    ctx.rowDragActive = true;
+    try {
+      e.dataTransfer?.setData("text/plain", String(rowIndex));
+      if (e.dataTransfer) e.dataTransfer.effectAllowed = "move";
+    } catch {
+      // Some environments (tests) provide a partial dataTransfer.
+    }
+  }
+
+  function onRowDragOver(e: DragEvent, rowIndex: number) {
+    if (!canAccept()) return;
+    e.preventDefault();
+    if (e.dataTransfer) e.dataTransfer.dropEffect = "move";
+    const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
+    ctx.rowDropIndex = rowIndex;
+    ctx.rowDropSide = e.clientY < rect.top + rect.height / 2 ? "before" : "after";
+  }
+
+  function onRowDragLeave(rowIndex: number) {
+    if (ctx.rowDropIndex === rowIndex) {
+      ctx.rowDropIndex = null;
+      ctx.rowDropSide = null;
+    }
+  }
+
+  function onRowDrop(e: DragEvent, rowIndex: number) {
+    if (!canAccept() || !bus) return;
+    e.preventDefault();
+    e.stopPropagation(); // don't let the tbody handler also fire (end-append)
+    const side = ctx.rowDropSide ?? "before";
+    const dragged = bus.row;
+    const target = originalAt(rowIndex);
+    const sourceGridId = bus.gridId;
+    const sameGrid = sourceGridId === gridId;
+    clearIndicators();
+
+    const data = (ctx.internalData as unknown[]).slice();
+    if (sameGrid) {
+      const from = data.indexOf(dragged);
+      if (from < 0) {
+        bus = null;
+        return;
+      }
+      data.splice(from, 1);
+    }
+    let to = target != null ? data.indexOf(target) : data.length;
+    if (to < 0) to = data.length;
+    if (side === "after") to += 1;
+    data.splice(to, 0, dragged);
+    ctx.internalData = data;
+    if (!sameGrid) bus.removeFromSource();
+    emitEnd(dragged, to, sameGrid, sourceGridId);
+    bus = null;
+  }
+
+  // Dropping in the empty area below the last row, or into an empty target
+  // grid, appends. Row-level drops call stopPropagation so this only fires for
+  // genuine empty-space drops.
+  function onRowsContainerDragOver(e: DragEvent) {
+    if (!canAccept()) return;
+    e.preventDefault();
+    if (e.dataTransfer) e.dataTransfer.dropEffect = "move";
+  }
+
+  function onRowsContainerDrop(e: DragEvent) {
+    if (!canAccept() || !bus) return;
+    e.preventDefault();
+    const dragged = bus.row;
+    const sourceGridId = bus.gridId;
+    const sameGrid = sourceGridId === gridId;
+    clearIndicators();
+
+    const data = (ctx.internalData as unknown[]).slice();
+    if (sameGrid) {
+      const from = data.indexOf(dragged);
+      if (from >= 0) data.splice(from, 1);
+    }
+    data.push(dragged);
+    ctx.internalData = data;
+    if (!sameGrid) bus.removeFromSource();
+    emitEnd(dragged, data.length - 1, sameGrid, sourceGridId);
+    bus = null;
+  }
+
+  function onRowDragEnd() {
+    clearIndicators();
+    bus = null;
+  }
+
+  return {
+    onRowDragStart,
+    onRowDragOver,
+    onRowDragLeave,
+    onRowDrop,
+    onRowsContainerDragOver,
+    onRowsContainerDrop,
+    onRowDragEnd,
+    rowDragGridId: gridId,
+  };
+}
+
+/** Options for the {@link rowDropZone} action. */
+export type RowDropZoneOptions<TData = unknown> = {
+  /**
+   * Only accept rows dragged from a grid with this `rowDragGroup`. Omit to
+   * accept a managed row drag from any grid.
+   */
+  group?: string;
+  /**
+   * Called when a managed row is dropped on the element. The row has already
+   * been removed from its source grid; add it to your own list/state here.
+   */
+  onDrop: (payload: { row: TData; fromGridId: number }) => void;
+  /** Class toggled on the element while a matching row is dragged over it. */
+  overClass?: string;
+};
+
+/**
+ * Svelte action turning ANY element into an external drop target for managed
+ * row dragging - a trash can, an "assign to" bucket, a second pane. Attach with
+ * `use:rowDropZone={{ group, onDrop }}`. On drop the dragged row is removed from
+ * its source grid and handed to `onDrop`.
+ *
+ * ```svelte
+ * <div use:rowDropZone={{ group: 'board', onDrop: (e) => archive(e.row) }}>Archive</div>
+ * ```
+ */
+export function rowDropZone<TData = unknown>(
+  node: HTMLElement,
+  options: RowDropZoneOptions<TData>,
+) {
+  let opts = options;
+  const cls = () => opts.overClass ?? "sv-grid-row-dropzone-over";
+
+  function matches(): boolean {
+    if (!bus) return false;
+    return opts.group == null || bus.group === opts.group;
+  }
+  function onOver(e: DragEvent) {
+    if (!matches()) return;
+    e.preventDefault();
+    if (e.dataTransfer) e.dataTransfer.dropEffect = "move";
+    node.classList.add(cls());
+  }
+  function onLeave() {
+    node.classList.remove(cls());
+  }
+  function onDrop(e: DragEvent) {
+    if (!matches() || !bus) return;
+    e.preventDefault();
+    e.stopPropagation();
+    node.classList.remove(cls());
+    const row = bus.row as TData;
+    const fromGridId = bus.gridId;
+    bus.removeFromSource();
+    bus = null;
+    opts.onDrop({ row, fromGridId });
+  }
+
+  node.addEventListener("dragover", onOver);
+  node.addEventListener("dragleave", onLeave);
+  node.addEventListener("drop", onDrop);
+  return {
+    update(next: RowDropZoneOptions<TData>) {
+      opts = next;
+    },
+    destroy() {
+      node.removeEventListener("dragover", onOver);
+      node.removeEventListener("dragleave", onLeave);
+      node.removeEventListener("drop", onDrop);
+    },
+  };
+}

package/src/scroll-sync.ts

@@ -193,6 +193,8 @@ export function createScrollSync<
     if (!container) return;
     if (ctx.columnMenuFor || ctx.operatorMenuFor) ctx.closeMenus();
     scheduleScrollSync(container.scrollTop, container.scrollLeft);
+    // Mirror horizontal scroll to any aligned grids in the same group.
+    if (ctx.props.alignedGridGroup != null) ctx.broadcastAlignedScroll(container.scrollLeft);
 
     if (ctx.props.onScrollBottomReached) {
       const { scrollTop, scrollHeight, clientHeight } = container;

package/src/selection.multi-range.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Unit tests for multiple-range (Ctrl+drag) cell selection, driven through the
+ * pure range helpers of createSelection(ctx) with a minimal fake ctx.
+ */
+import { describe, expect, it } from 'vitest'
+import { createSelection } from './selection'
+
+function makeCtx() {
+  return {
+    enableCellSelectionEffective: true,
+    selectionRange: { anchor: null, focus: null },
+    selectionRanges: [],
+  } as Record<string, any>
+}
+
+describe('multiple range selection', () => {
+  it('a plain selection replaces any committed ranges', () => {
+    const ctx = makeCtx()
+    const s = createSelection(ctx)
+    s.setSelection(0, 0)
+    s.extendSelection(1, 1) // active range 0,0..1,1
+    s.setSelection(5, 5, true) // additive: commit prior, start new
+    expect(ctx.selectionRanges.length).toBe(1)
+    s.setSelection(9, 9, false) // plain: clears committed
+    expect(ctx.selectionRanges.length).toBe(0)
+  })
+
+  it('Ctrl+drag commits the prior range and keeps both highlighted', () => {
+    const ctx = makeCtx()
+    const s = createSelection(ctx)
+    s.setSelection(0, 0)
+    s.extendSelection(1, 1) // range A: rows 0-1, cols 0-1
+    s.setSelection(3, 3, true) // start range B additively
+    s.extendSelection(4, 4) // range B: rows 3-4, cols 3-4
+
+    const rects = s.getSelectionRects()
+    expect(rects.length).toBe(2)
+    // both ranges report cells as selected
+    expect(s.isCellInSelectedRange(0, 0)).toBe(true)
+    expect(s.isCellInSelectedRange(1, 1)).toBe(true)
+    expect(s.isCellInSelectedRange(4, 4)).toBe(true)
+    // a cell in neither is not selected
+    expect(s.isCellInSelectedRange(2, 2)).toBe(false)
+  })
+
+  it('getCellRangeEdges outlines each range independently', () => {
+    const ctx = makeCtx()
+    const s = createSelection(ctx)
+    s.setSelection(0, 0)
+    s.extendSelection(1, 1)
+    s.setSelection(3, 3, true)
+    s.extendSelection(4, 4)
+
+    // top-left corner of range A
+    expect(s.getCellRangeEdges(0, 0)).toEqual({ top: true, bottom: false, left: true, right: false })
+    // bottom-right corner of range B
+    expect(s.getCellRangeEdges(4, 4)).toEqual({ top: false, bottom: true, left: false, right: true })
+    // outside every range
+    expect(s.getCellRangeEdges(2, 2)).toBeNull()
+  })
+})

package/src/selection.ts

@@ -283,8 +283,44 @@ export function createSelection<
     // onBodyScroll which flushes via rAF, doing one batched update.
   }
 
-  function setSelection(rowIndex: number, colIndex: number) {
+  // Normalize a range to a rectangle, or null when incomplete.
+  function rangeRect(range: SelectionRange | null) {
+    const a = range?.anchor;
+    const f = range?.focus;
+    if (!a || !f) return null;
+    return {
+      minRow: Math.min(a.rowIndex, f.rowIndex),
+      maxRow: Math.max(a.rowIndex, f.rowIndex),
+      minCol: Math.min(a.colIndex, f.colIndex),
+      maxCol: Math.max(a.colIndex, f.colIndex),
+    };
+  }
+
+  // Every selected rectangle: the committed extra ranges plus the active one.
+  // Order matters for copy (added-order); the active range comes last.
+  function getSelectionRects() {
+    const rects = [] as Array<{ minRow: number; maxRow: number; minCol: number; maxCol: number }>;
+    for (const r of (ctx.selectionRanges as SelectionRange[]) ?? []) {
+      const rect = rangeRect(r);
+      if (rect) rects.push(rect);
+    }
+    const active = rangeRect(ctx.selectionRange);
+    if (active) rects.push(active);
+    return rects;
+  }
+
+  function setSelection(rowIndex: number, colIndex: number, additive = false) {
     if (!ctx.enableCellSelectionEffective) return;
+    if (additive) {
+      // Commit the current active range (if any) and start a fresh one, so the
+      // previous rectangle stays highlighted alongside the new Ctrl+drag.
+      const active = ctx.selectionRange as SelectionRange;
+      if (active.anchor && active.focus) {
+        ctx.selectionRanges = [...(ctx.selectionRanges as SelectionRange[]), active];
+      }
+    } else {
+      ctx.selectionRanges = [];
+    }
     const point = { rowIndex, colIndex };
     ctx.selectionRange = { anchor: point, focus: point };
   }
@@ -296,47 +332,43 @@ export function createSelection<
   }
 
   function isCellInSelectedRange(rowIndex: number, colIndex: number) {
-    const anchor = ctx.selectionRange.anchor;
-    const focus = ctx.selectionRange.focus;
-    if (!anchor || !focus) return false;
-    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);
-    return (
-      rowIndex >= minRow &&
-      rowIndex <= maxRow &&
-      colIndex >= minCol &&
-      colIndex <= maxCol
-    );
+    for (const rect of getSelectionRects()) {
+      if (
+        rowIndex >= rect.minRow &&
+        rowIndex <= rect.maxRow &&
+        colIndex >= rect.minCol &&
+        colIndex <= rect.maxCol
+      ) {
+        return true;
+      }
+    }
+    return false;
   }
 
   /**
-   * Returns which sides of the selection rectangle a cell sits on, for the
-   * Excel-style outline. Returns null when the cell is outside the range.
+   * Returns which sides of a selection rectangle a cell sits on, for the
+   * Excel-style outline. With multiple ranges, the edges of the FIRST range
+   * that contains the cell are returned (active range checked last so its
+   * outline wins on overlap). Returns null when the cell is in no range.
    */
   function getCellRangeEdges(rowIndex: number, colIndex: number) {
-    const anchor = ctx.selectionRange.anchor;
-    const focus = ctx.selectionRange.focus;
-    if (!anchor || !focus) return null;
-    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);
-    if (
-      rowIndex < minRow ||
-      rowIndex > maxRow ||
-      colIndex < minCol ||
-      colIndex > maxCol
-    ) {
-      return null;
+    for (const rect of getSelectionRects()) {
+      if (
+        rowIndex < rect.minRow ||
+        rowIndex > rect.maxRow ||
+        colIndex < rect.minCol ||
+        colIndex > rect.maxCol
+      ) {
+        continue;
+      }
+      return {
+        top: rowIndex === rect.minRow,
+        bottom: rowIndex === rect.maxRow,
+        left: colIndex === rect.minCol,
+        right: colIndex === rect.maxCol,
+      };
     }
-    return {
-      top: rowIndex === minRow,
-      bottom: rowIndex === maxRow,
-      left: colIndex === minCol,
-      right: colIndex === maxCol,
-    };
+    return null;
   }
 
   /** Returns true when the given cell is inside the fill-drag preview
@@ -398,7 +430,8 @@ export function createSelection<
       setActiveCell(rowIndex, colIndex);
     } else {
       setActiveCell(rowIndex, colIndex);
-      setSelection(rowIndex, colIndex);
+      // Ctrl/Cmd starts an ADDITIONAL range, keeping prior ranges highlighted.
+      setSelection(rowIndex, colIndex, event.ctrlKey || event.metaKey);
       // Range drag-select is a mouse/pen affordance. On touch, starting a drag
       // here would rubber-band a selection AND fight the browser's native
       // scroll (we never preventDefault), so a finger-drag to scroll the grid
@@ -533,6 +566,7 @@ export function createSelection<
     extendSelection,
     isCellInSelectedRange,
     getCellRangeEdges,
+    getSelectionRects,
     isInFillPreview,
     findColumnById,
     onCellPointerDown,

package/src/spreadsheet.test.ts

@@ -1,6 +1,6 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
-import { spreadsheetLayout } from './spreadsheet'
-import type { SpreadsheetActionOptions } from './spreadsheet'
+import { spreadsheetLayout, spansToMerges } from './spreadsheet'
+import type { SpreadsheetActionOptions, SpanColumn } from './spreadsheet'
 
 // jsdom does not implement the global `CSS` object, which `findCell` uses via
 // `CSS.escape`. Provide a minimal polyfill so the action's selector queries
@@ -443,3 +443,47 @@ describe('spreadsheetLayout - update + cleanup', () => {
     action.destroy()
   })
 })
+
+describe('spansToMerges - declarative colSpan/rowSpan -> MergeSpec[]', () => {
+  type Row = { region: string; q: string; amt: number }
+  const rows: Row[] = [
+    { region: 'AMER', q: 'Q1', amt: 1 },
+    { region: 'AMER', q: 'Q2', amt: 2 },
+    { region: 'AMER', q: 'Q3', amt: 3 },
+    { region: 'EMEA', q: 'Q1', amt: 4 },
+    { region: 'EMEA', q: 'Q2', amt: 5 },
+  ]
+  // Merge each run of equal `region` values downward.
+  function regionRowSpan(): SpanColumn<Row>['rowSpan'] {
+    return ({ data, rowIndex }) => {
+      if (rowIndex > 0 && rows[rowIndex - 1]!.region === data.region) return 1 // covered
+      let n = 1
+      while (rows[rowIndex + n]?.region === data.region) n += 1
+      return n
+    }
+  }
+
+  it('emits a rowspan merge at each run origin and skips covered rows', () => {
+    const columns: SpanColumn<Row>[] = [{ id: 'region', field: 'region', rowSpan: regionRowSpan() }]
+    const merges = spansToMerges(rows, columns)
+    // AMER spans rows 0..2 (rowspan 3), EMEA spans rows 3..4 (rowspan 2).
+    expect(merges).toEqual([
+      { rowIndex: 0, columnId: 'region', colspan: undefined, rowspan: 3 },
+      { rowIndex: 3, columnId: 'region', colspan: undefined, rowspan: 2 },
+    ])
+  })
+
+  it('supports colSpan and marks covered columns', () => {
+    const columns: SpanColumn<Row>[] = [
+      { id: 'a', field: 'region', colSpan: ({ rowIndex }) => (rowIndex === 0 ? 2 : 1) },
+      { id: 'b', field: 'q' },
+      { id: 'c', field: 'amt' },
+    ]
+    const merges = spansToMerges(rows.slice(0, 1), columns)
+    expect(merges).toEqual([{ rowIndex: 0, columnId: 'a', colspan: 2, rowspan: undefined }])
+  })
+
+  it('returns no merges when no column defines spans', () => {
+    expect(spansToMerges(rows, [{ id: 'region', field: 'region' }])).toEqual([])
+  })
+})

package/src/spreadsheet.ts

@@ -45,6 +45,64 @@ export type MergeSpec = {
   colspan?: number
 }
 
+/** A column with declarative spanning callbacks, as accepted by
+ *  `spansToMerges`. Matches the relevant slice of `ColumnDef`. */
+export type SpanColumn<TData = Record<string, unknown>> = {
+  id: string
+  field?: string
+  colSpan?: (params: { data: TData; rowIndex: number; columnId: string; value: unknown }) => number
+  rowSpan?: (params: { data: TData; rowIndex: number; columnId: string; value: unknown }) => number
+}
+
+/**
+ * Turn declarative per-column `colSpan` / `rowSpan` callbacks into a
+ * `MergeSpec[]` you can hand to `spreadsheetLayout` - so value-driven,
+ * AG-Grid-style spanning runs on the SAME real colspan/rowspan merge engine
+ * instead of a second code path. Recompute after sort/filter (indexes are
+ * display-row indexes). A common pattern is "merge runs of equal values":
+ *
+ *   { field: 'region', rowSpan: ({ data, rowIndex }) =>
+ *       rows.filter((r, i) => i >= rowIndex && r.region === data.region &&
+ *         (i === rowIndex || rows[i-1].region === data.region)).length }
+ */
+export function spansToMerges<TData = Record<string, unknown>>(
+  rows: ReadonlyArray<TData>,
+  columns: ReadonlyArray<SpanColumn<TData>>,
+  getValue?: (row: TData, columnId: string) => unknown,
+): MergeSpec[] {
+  const merges: MergeSpec[] = []
+  const covered = new Set<string>()
+  for (let r = 0; r < rows.length; r += 1) {
+    const row = rows[r]!
+    for (let ci = 0; ci < columns.length; ci += 1) {
+      const col = columns[ci]!
+      if (!col.colSpan && !col.rowSpan) continue
+      const key = `${r}:${ci}`
+      if (covered.has(key)) continue
+      const value = getValue
+        ? getValue(row, col.id)
+        : (row as Record<string, unknown>)[col.field ?? col.id]
+      const params = { data: row, rowIndex: r, columnId: col.id, value }
+      const cs = Math.max(1, Math.floor(col.colSpan?.(params) ?? 1))
+      const rs = Math.max(1, Math.floor(col.rowSpan?.(params) ?? 1))
+      if (cs <= 1 && rs <= 1) continue
+      merges.push({
+        rowIndex: r,
+        columnId: col.id,
+        colspan: cs > 1 ? cs : undefined,
+        rowspan: rs > 1 ? rs : undefined,
+      })
+      for (let dr = 0; dr < rs; dr += 1) {
+        for (let dc = 0; dc < cs; dc += 1) {
+          if (dr === 0 && dc === 0) continue
+          covered.add(`${r + dr}:${ci + dc}`)
+        }
+      }
+    }
+  }
+  return merges
+}
+
 /** Borders for one cell. Edges left unset render as the default
  *  cell border (i.e. no override). */
 export type CellBorderSpec = {

package/src/static-functions.ts

@@ -1,11 +1,11 @@
-export {
-  createCoreRowModel,
-  createExpandedRowModel,
-  createFilteredRowModel,
-  createGroupedRowModel,
-  createPaginatedRowModel,
-  createSortedRowModel,
-  filterFns,
-  sortFns,
-  tableFeatures,
-} from './core'
+export {
+  createCoreRowModel,
+  createExpandedRowModel,
+  createFilteredRowModel,
+  createGroupedRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  filterFns,
+  sortFns,
+  tableFeatures,
+} from './core'