@svgrid/grid 1.1.0 → 1.1.2

package/src/SvGrid.types.ts

@@ -150,7 +150,32 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
   showFilterMenu?: boolean;
   showFilterRow?: boolean;
   enableCellSelection?: boolean;
+  /**
+   * Prepend a header row (the column labels) to copied cell ranges, so pasting
+   * into Excel / Sheets includes the headers. Applies per copied range.
+   */
+  copyHeadersToClipboard?: boolean;
+  /**
+   * Transform each cell value on its way to the clipboard - e.g. strip
+   * currency symbols, expand codes to labels, or redact. Receives the display
+   * value plus the row/column context; return the string (or value) to copy.
+   */
+  processCellForClipboard?: (params: {
+    value: unknown;
+    column: unknown;
+    row: TData;
+    rowIndex: number;
+    columnId: string;
+  }) => unknown;
   enableInlineEditing?: boolean;
+  /**
+   * Full-row editing. When `true`, starting an edit puts the WHOLE row into
+   * edit mode - every editable cell shows an inline editor at once - and a
+   * single Enter (or focus leaving the row) commits all of them; Esc cancels
+   * the whole row. Requires `enableInlineEditing`. The full-row editor covers
+   * text / number / date / datetime / checkbox / list-select editor types.
+   */
+  fullRowEditing?: boolean;
   enableRowSummaries?: boolean;
   /**
    * Excel-style status bar under the grid showing live aggregates of the
@@ -166,12 +191,21 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
         >;
       };
   /**
-   * Show a docked Columns tool panel - the enterprise sidebar for toggling
-   * column visibility, reordering, and grouping without a right-click. A
-   * toggle button appears at the grid's top-right; the panel itself docks
-   * on the right edge.
+   * Show the docked tool panel - the enterprise sidebar with Columns and
+   * Filters tabs. A "Columns & Filters" button appears in a toolbar above the
+   * grid; the panel docks on the right edge.
    */
   toolPanel?: boolean;
+  /**
+   * Render the header column menu (⋮) as a tabbed popover - **General**,
+   * **Filter**, and **Columns** tabs (the AG-Grid layout). Defaults to `false`,
+   * which keeps the flat menu (actions list + "Choose columns" submenu).
+   */
+  columnMenuTabs?: boolean;
+  /** Open the tool panel on first render (instead of collapsed). */
+  toolPanelDefaultOpen?: boolean;
+  /** Which tab the tool panel starts on. Defaults to `'columns'`. */
+  toolPanelDefaultTab?: "columns" | "filters";
   /**
    * Quick way to pick which selection surfaces are active. `'row'` shows the
    * selection checkbox column only, `'cell'` allows rectangle/range cell
@@ -419,6 +453,53 @@ export type Props<TFeatures extends TableFeatures = TableFeatures, TData extends
   columnOrder?: ReadonlyArray<string>;
   /** Fires every time the column order changes (drag or `api.setColumnOrder`). */
   onColumnOrderChange?: (order: ReadonlyArray<string>) => void;
+  /**
+   * Infer each column's data type (number / boolean / date / ISO date-string /
+   * text) from the first data row, for columns that declare neither an
+   * explicit `editorType` nor a `cellDataType`. Sets the matching editor,
+   * alignment, date format, and filter operators automatically. Explicit
+   * column config always wins. Defaults to `false`.
+   */
+  inferColumnTypes?: boolean;
+  /**
+   * Enables managed row dragging. When `true`, every row becomes a drag
+   * source (grab cursor + a grip in the row-number cell) and a drop
+   * indicator paints between rows during a drag. On drop the grid mutates
+   * its own internal data - reordering within the grid, or moving the row
+   * across grids that share the same {@link rowDragGroup}. Defaults to
+   * `false`.
+   */
+  rowDragManaged?: boolean;
+  /**
+   * Connection group for cross-grid row dragging. Grids that share the same
+   * non-empty `rowDragGroup` string (and have `rowDragManaged` on) can
+   * exchange rows: dragging a row out of one and dropping it into another
+   * removes it from the source and inserts it into the target. Omit to keep
+   * dragging confined to reordering within a single grid.
+   */
+  rowDragGroup?: string;
+  /**
+   * Fires on the TARGET grid after a managed row drag settles, with the
+   * moved row, its landing index, whether it stayed in the same grid, and
+   * the source / target grid ids. Use it to mirror the move into your own
+   * state (persistence, server sync). The grid has already applied the
+   * change to its internal data by the time this fires.
+   */
+  onRowDragEnd?: (event: {
+    row: TData;
+    toIndex: number;
+    sameGrid: boolean;
+    fromGridId: number;
+    toGridId: number;
+  }) => void;
+  /**
+   * Align this grid with others that share the same non-empty
+   * `alignedGridGroup` string: horizontal scroll and column-resize widths are
+   * kept in lockstep across every grid in the group. Use for a totals/header
+   * grid above a body grid, or side-by-side comparison grids that must line up.
+   * The grids should declare the same columns (matched by id) for widths to map.
+   */
+  alignedGridGroup?: string;
   /**
    * BCP-47 locale tag (or array of fallbacks) used for accent- and
    * case-insensitive text filtering / sorting / search. Powered by

package/src/a11y.contract.test.ts

@@ -1,49 +1,49 @@
-import { describe, expect, it } from 'vitest'
-import {
-  getGridCellA11yProps,
-  getGridHeaderA11yProps,
-  getGridRootA11yProps,
-  getGridRowA11yProps,
-} from './a11y'
-
-function attrsToHtml(attrs: Record<string, string | number | boolean>) {
-  return Object.entries(attrs)
-    .map(([key, value]) => `${key}="${String(value)}"`)
-    .join(' ')
-}
-
-describe('a11y contract rendering', () => {
-  it('builds expected headless markup attributes', () => {
-    const root = getGridRootA11yProps()
-    const header = getGridHeaderA11yProps({
-      sortable: true,
-      sortDirection: 'descending',
-    })
-    const row = getGridRowA11yProps(1)
-    const cell = getGridCellA11yProps({
-      rowIndex: 1,
-      colIndex: 2,
-      selected: true,
-    })
-
-    const html = [
-      `<table ${attrsToHtml(root)}><thead>`,
-      `<tr ${attrsToHtml(row)}>`,
-      `<th ${attrsToHtml(header)}>Age</th>`,
-      `</tr></thead><tbody>`,
-      `<tr ${attrsToHtml(row)}><td ${attrsToHtml(cell)}>42</td></tr>`,
-      `</tbody></table>`,
-    ].join('')
-
-    expect(html).toContain('role="grid"')
-    expect(html).toContain('role="columnheader"')
-    expect(html).toContain('aria-sort="descending"')
-    expect(html).toContain('aria-selected="true"')
-    expect(html).toContain('aria-colindex="2"')
-  })
-
-  it('creates stable active descendant ids', async () => {
-    const { getGridCellDomId } = await import('./a11y')
-    expect(getGridCellDomId('svgrid', 3, 4)).toBe('svgrid_cell_3_4')
-  })
-})
+import { describe, expect, it } from 'vitest'
+import {
+  getGridCellA11yProps,
+  getGridHeaderA11yProps,
+  getGridRootA11yProps,
+  getGridRowA11yProps,
+} from './a11y'
+
+function attrsToHtml(attrs: Record<string, string | number | boolean>) {
+  return Object.entries(attrs)
+    .map(([key, value]) => `${key}="${String(value)}"`)
+    .join(' ')
+}
+
+describe('a11y contract rendering', () => {
+  it('builds expected headless markup attributes', () => {
+    const root = getGridRootA11yProps()
+    const header = getGridHeaderA11yProps({
+      sortable: true,
+      sortDirection: 'descending',
+    })
+    const row = getGridRowA11yProps(1)
+    const cell = getGridCellA11yProps({
+      rowIndex: 1,
+      colIndex: 2,
+      selected: true,
+    })
+
+    const html = [
+      `<table ${attrsToHtml(root)}><thead>`,
+      `<tr ${attrsToHtml(row)}>`,
+      `<th ${attrsToHtml(header)}>Age</th>`,
+      `</tr></thead><tbody>`,
+      `<tr ${attrsToHtml(row)}><td ${attrsToHtml(cell)}>42</td></tr>`,
+      `</tbody></table>`,
+    ].join('')
+
+    expect(html).toContain('role="grid"')
+    expect(html).toContain('role="columnheader"')
+    expect(html).toContain('aria-sort="descending"')
+    expect(html).toContain('aria-selected="true"')
+    expect(html).toContain('aria-colindex="2"')
+  })
+
+  it('creates stable active descendant ids', async () => {
+    const { getGridCellDomId } = await import('./a11y')
+    expect(getGridCellDomId('svgrid', 3, 4)).toBe('svgrid_cell_3_4')
+  })
+})

package/src/a11y.test.ts

@@ -1,59 +1,59 @@
-import { describe, expect, it } from 'vitest'
-import {
-  getGridCellA11yProps,
-  getGridHeaderA11yProps,
-  getGridRootA11yProps,
-  getGridRowA11yProps,
-} from './a11y'
-
-describe('a11y helpers', () => {
-  it('returns grid role props', () => {
-    expect(
-      getGridRootA11yProps({
-        activeDescendantId: 'svgrid_cell_0_0',
-        rowCount: 10,
-        colCount: 5,
-      }),
-    ).toEqual({
-      role: 'grid',
-      tabindex: 0,
-      'aria-activedescendant': 'svgrid_cell_0_0',
-      'aria-rowcount': 10,
-      'aria-colcount': 5,
-    })
-  })
-
-  it('returns header sort semantics', () => {
-    expect(
-      getGridHeaderA11yProps({
-        sortable: true,
-        sortDirection: 'ascending',
-      }),
-    ).toEqual({
-      role: 'columnheader',
-      'aria-sort': 'ascending',
-    })
-  })
-
-  it('returns row and cell indices for accessibility metadata', () => {
-    expect(getGridRowA11yProps(2)).toEqual({
-      role: 'row',
-      'aria-rowindex': 2,
-    })
-
-    expect(
-      getGridCellA11yProps({
-        id: 'svgrid_cell_2_3',
-        rowIndex: 2,
-        colIndex: 3,
-        selected: true,
-      }),
-    ).toEqual({
-      role: 'gridcell',
-      id: 'svgrid_cell_2_3',
-      'aria-colindex': 3,
-      'aria-rowindex': 2,
-      'aria-selected': true,
-    })
-  })
-})
+import { describe, expect, it } from 'vitest'
+import {
+  getGridCellA11yProps,
+  getGridHeaderA11yProps,
+  getGridRootA11yProps,
+  getGridRowA11yProps,
+} from './a11y'
+
+describe('a11y helpers', () => {
+  it('returns grid role props', () => {
+    expect(
+      getGridRootA11yProps({
+        activeDescendantId: 'svgrid_cell_0_0',
+        rowCount: 10,
+        colCount: 5,
+      }),
+    ).toEqual({
+      role: 'grid',
+      tabindex: 0,
+      'aria-activedescendant': 'svgrid_cell_0_0',
+      'aria-rowcount': 10,
+      'aria-colcount': 5,
+    })
+  })
+
+  it('returns header sort semantics', () => {
+    expect(
+      getGridHeaderA11yProps({
+        sortable: true,
+        sortDirection: 'ascending',
+      }),
+    ).toEqual({
+      role: 'columnheader',
+      'aria-sort': 'ascending',
+    })
+  })
+
+  it('returns row and cell indices for accessibility metadata', () => {
+    expect(getGridRowA11yProps(2)).toEqual({
+      role: 'row',
+      'aria-rowindex': 2,
+    })
+
+    expect(
+      getGridCellA11yProps({
+        id: 'svgrid_cell_2_3',
+        rowIndex: 2,
+        colIndex: 3,
+        selected: true,
+      }),
+    ).toEqual({
+      role: 'gridcell',
+      id: 'svgrid_cell_2_3',
+      'aria-colindex': 3,
+      'aria-rowindex': 2,
+      'aria-selected': true,
+    })
+  })
+})

package/src/a11y.ts

@@ -1,59 +1,59 @@
-export type GridSortDirection = 'ascending' | 'descending' | 'none' | 'other'
-
-export type GridColumnA11yInput = {
-  sortable?: boolean
-  sortDirection?: GridSortDirection
-}
-
-export type GridCellA11yInput = {
-  colIndex?: number
-  rowIndex?: number
-  selected?: boolean
-  id?: string
-}
-
-export function getGridRootA11yProps(input: {
-  activeDescendantId?: string | null
-  rowCount?: number
-  colCount?: number
-} = {}) {
-  return {
-    role: 'grid',
-    tabindex: 0,
-    ...(input.activeDescendantId
-      ? { 'aria-activedescendant': input.activeDescendantId }
-      : {}),
-    ...(input.rowCount !== undefined ? { 'aria-rowcount': input.rowCount } : {}),
-    ...(input.colCount !== undefined ? { 'aria-colcount': input.colCount } : {}),
-  } as const
-}
-
-export function getGridHeaderA11yProps(input: GridColumnA11yInput = {}) {
-  const { sortable = false, sortDirection = 'none' } = input
-  return {
-    role: 'columnheader',
-    ...(sortable ? { 'aria-sort': sortDirection } : {}),
-  } as const
-}
-
-export function getGridRowA11yProps(rowIndex?: number) {
-  return {
-    role: 'row',
-    ...(rowIndex !== undefined ? { 'aria-rowindex': rowIndex } : {}),
-  } as const
-}
-
-export function getGridCellA11yProps(input: GridCellA11yInput = {}) {
-  const { colIndex, rowIndex, selected = false, id } = input
-  return {
-    role: 'gridcell',
-    ...(id ? { id } : {}),
-    ...(colIndex !== undefined ? { 'aria-colindex': colIndex } : {}),
-    ...(rowIndex !== undefined ? { 'aria-rowindex': rowIndex } : {}),
-    ...(selected ? { 'aria-selected': true } : {}),
-  } as const
-}
-
-export function getGridCellDomId(baseId: string, rowIndex: number, colIndex: number) {
-  return `${baseId}_cell_${rowIndex}_${colIndex}`
-}
+export type GridSortDirection = 'ascending' | 'descending' | 'none' | 'other'
+
+export type GridColumnA11yInput = {
+  sortable?: boolean
+  sortDirection?: GridSortDirection
+}
+
+export type GridCellA11yInput = {
+  colIndex?: number
+  rowIndex?: number
+  selected?: boolean
+  id?: string
+}
+
+export function getGridRootA11yProps(input: {
+  activeDescendantId?: string | null
+  rowCount?: number
+  colCount?: number
+} = {}) {
+  return {
+    role: 'grid',
+    tabindex: 0,
+    ...(input.activeDescendantId
+      ? { 'aria-activedescendant': input.activeDescendantId }
+      : {}),
+    ...(input.rowCount !== undefined ? { 'aria-rowcount': input.rowCount } : {}),
+    ...(input.colCount !== undefined ? { 'aria-colcount': input.colCount } : {}),
+  } as const
+}
+
+export function getGridHeaderA11yProps(input: GridColumnA11yInput = {}) {
+  const { sortable = false, sortDirection = 'none' } = input
+  return {
+    role: 'columnheader',
+    ...(sortable ? { 'aria-sort': sortDirection } : {}),
+  } as const
+}
+
+export function getGridRowA11yProps(rowIndex?: number) {
+  return {
+    role: 'row',
+    ...(rowIndex !== undefined ? { 'aria-rowindex': rowIndex } : {}),
+  } as const
+}
+
+export function getGridCellA11yProps(input: GridCellA11yInput = {}) {
+  const { colIndex, rowIndex, selected = false, id } = input
+  return {
+    role: 'gridcell',
+    ...(id ? { id } : {}),
+    ...(colIndex !== undefined ? { 'aria-colindex': colIndex } : {}),
+    ...(rowIndex !== undefined ? { 'aria-rowindex': rowIndex } : {}),
+    ...(selected ? { 'aria-selected': true } : {}),
+  } as const
+}
+
+export function getGridCellDomId(baseId: string, rowIndex: number, colIndex: number) {
+  return `${baseId}_cell_${rowIndex}_${colIndex}`
+}

package/src/aligned-grids.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Unit tests for aligned grids: two members sharing a group mirror horizontal
+ * scroll and column-resize widths to each other. Driven with minimal fake ctxs.
+ */
+import { describe, expect, it } from 'vitest'
+import { createAlignedGrids } from './aligned-grids'
+
+function makeCtx(group: string | undefined) {
+  return {
+    props: { alignedGridGroup: group },
+    scrollContainer: { scrollLeft: 0 } as { scrollLeft: number },
+    columnWidths: {} as Record<string, number>,
+  } as Record<string, any>
+}
+
+describe('aligned grids', () => {
+  it('mirrors horizontal scroll to peers in the same group', () => {
+    const a = makeCtx('g')
+    const b = makeCtx('g')
+    const ha = createAlignedGrids(a)
+    const hb = createAlignedGrids(b)
+    const un1 = ha.register()
+    const un2 = hb.register()
+
+    ha.broadcastScroll(240)
+    expect(b.scrollContainer.scrollLeft).toBe(240)
+    // and the other way
+    hb.broadcastScroll(80)
+    expect(a.scrollContainer.scrollLeft).toBe(80)
+    un1(); un2()
+  })
+
+  it('mirrors column-resize widths to peers (matched by column id)', () => {
+    const a = makeCtx('g')
+    const b = makeCtx('g')
+    const ha = createAlignedGrids(a)
+    const hb = createAlignedGrids(b)
+    ha.register(); hb.register()
+
+    a.columnWidths = { Feb: 180 }
+    ha.broadcastWidths()
+    expect(b.columnWidths.Feb).toBe(180)
+  })
+
+  it('does NOT mirror across different groups', () => {
+    const a = makeCtx('one')
+    const b = makeCtx('two')
+    const ha = createAlignedGrids(a)
+    const hb = createAlignedGrids(b)
+    ha.register(); hb.register()
+
+    ha.broadcastScroll(200)
+    expect(b.scrollContainer.scrollLeft).toBe(0)
+    a.columnWidths = { Feb: 999 }
+    ha.broadcastWidths()
+    expect(b.columnWidths.Feb).toBeUndefined()
+  })
+
+  it('is inert with no group set, and after unregister', () => {
+    const a = makeCtx(undefined)
+    const b = makeCtx(undefined)
+    const ha = createAlignedGrids(a)
+    const hb = createAlignedGrids(b)
+    ha.register(); hb.register()
+    ha.broadcastScroll(120)
+    expect(b.scrollContainer.scrollLeft).toBe(0)
+
+    // Grouped, then unregistered -> no longer receives updates.
+    const c = makeCtx('gg')
+    const d = makeCtx('gg')
+    const hc = createAlignedGrids(c)
+    const hd = createAlignedGrids(d)
+    const unc = hc.register()
+    const und = hd.register()
+    und() // d leaves the group
+    hc.broadcastScroll(55)
+    expect(d.scrollContainer.scrollLeft).toBe(0)
+    unc()
+  })
+})

package/src/aligned-grids.ts

@@ -0,0 +1,87 @@
+// Aligned grids - keep two or more independent grids in lockstep on horizontal
+// scroll and column widths. Grids that share the same `alignedGridGroup` string
+// register with a module-level registry (same pattern as managed row dragging);
+// when one scrolls horizontally or a column is resized, the others follow.
+//
+// Loop-safety without flags: scroll sync no-ops when the target already has the
+// value (so the echo scroll event never fires); width sync compares a serialized
+// snapshot and pre-seeds it on apply, so the reactive effect that fires after
+// applying a peer's widths sees "no change" and doesn't echo.
+
+type Member = {
+  id: number;
+  applyScroll: (left: number) => void;
+  applyWidths: (widths: Record<string, number>) => void;
+};
+
+// Shared across every grid in the bundle.
+const groups = new Map<string, Map<number, Member>>();
+let seq = 0;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createAlignedGrids<TFeatures, TData>(ctx: any) {
+  const id = ++seq;
+  let lastWidthsSerial = "";
+
+  const group = (): string | null => ctx.props.alignedGridGroup ?? null;
+
+  function peers(): Member[] {
+    const g = group();
+    if (!g) return [];
+    const m = groups.get(g);
+    if (!m) return [];
+    const out: Member[] = [];
+    for (const member of m.values()) if (member.id !== id) out.push(member);
+    return out;
+  }
+
+  const self: Member = {
+    id,
+    applyScroll(left: number) {
+      const el = ctx.scrollContainer as HTMLElement | null;
+      // Only set when it differs, so no echo scroll event fires -> no loop.
+      if (el && el.scrollLeft !== left) el.scrollLeft = left;
+    },
+    applyWidths(widths: Record<string, number>) {
+      const merged = { ...(ctx.columnWidths as Record<string, number>), ...widths };
+      // Pre-seed the serial so the columnWidths effect that fires after this
+      // set sees an unchanged snapshot and skips its own broadcast.
+      lastWidthsSerial = JSON.stringify(merged);
+      ctx.columnWidths = merged;
+    },
+  };
+
+  // Register on mount; returns the unregister for the effect's cleanup.
+  function register(): () => void {
+    const g = group();
+    if (!g) return () => {};
+    let m = groups.get(g);
+    if (!m) {
+      m = new Map();
+      groups.set(g, m);
+    }
+    m.set(id, self);
+    return () => {
+      const mm = groups.get(g);
+      if (!mm) return;
+      mm.delete(id);
+      if (!mm.size) groups.delete(g);
+    };
+  }
+
+  function broadcastScroll(left: number) {
+    const p = peers();
+    for (const member of p) member.applyScroll(left);
+  }
+
+  function broadcastWidths() {
+    if (!group()) return;
+    const serial = JSON.stringify((ctx.columnWidths as Record<string, number>) ?? {});
+    if (serial === lastWidthsSerial) return; // nothing new (or echo of an apply)
+    lastWidthsSerial = serial;
+    const w = ctx.columnWidths as Record<string, number>;
+    for (const member of peers()) member.applyWidths(w);
+  }
+
+  return { register, broadcastScroll, broadcastWidths, alignedGridId: id };
+}