@tipolox/litgrid-react 1.0.3 → 1.1.0

package/README.md

@@ -35,6 +35,7 @@ Render `UsersGrid` in your React application. `height` defines the viewport used
 
 - [Live demo](https://tipolox.com/litgrid/demo)
 - [Repository](https://github.com/tipolox/litgrid)
+- [v1.1.0 upgrade guide](https://github.com/tipolox/litgrid/blob/main/docs/installation.md#upgrading-to-v110)
 - [React guide](https://github.com/tipolox/litgrid/blob/main/docs/react-guide.md)
 - [API reference](https://github.com/tipolox/litgrid/blob/main/docs/api-reference.md)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tipolox/litgrid-react",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "React integration for LitGrid.",
   "type": "module",
   "main": "./dist/index.js",
@@ -15,7 +15,11 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "src/**/*.{ts,tsx}",
+    "!src/**/*.d.ts",
+    "!src/**/*.test.{ts,tsx}",
+    "!src/**/*.bench.{ts,tsx}"
   ],
   "keywords": [
     "data-grid",
@@ -38,7 +42,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@tipolox/litgrid-web": "^1.0.3"
+    "@tipolox/litgrid-web": "^1.1.0"
   },
   "peerDependencies": {
     "react": "^19.2.5",

package/src/DataGrid.tsx

@@ -0,0 +1,252 @@
+import '@tipolox/litgrid-web'
+import type {
+  BestFitColumnWidth,
+  ColumnReorderDetail,
+  ColumnStateChangeDetail,
+  ColumnVisibilityChangeDetail,
+  DataGridElement,
+  GridColumn,
+  GridColumnState,
+  GridConfig,
+  GridFilter,
+  GridPaginationState,
+  GridSelection,
+  GridTheme,
+  SelectionIntent
+} from '@tipolox/litgrid-web'
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef
+} from 'react'
+import { syncGridInputs } from './gridBindings.js'
+
+export type DataGridProps = {
+  data: unknown[]
+  columns?: GridColumn[]
+  config?: GridConfig
+  theme?: GridTheme
+  ariaLabel?: string
+  ariaDescription?: string
+  screenReaderAnnouncements?: boolean
+  height?: number
+  rowHeight?: number
+  overscan?: number
+  columnOverscan?: number
+  bestFitSampleSize?: number
+  quickSearchDebounceThreshold?: number
+  quickSearchDebounceMs?: number
+  columnStateStorageKey?: string
+  onColumnStateChange?: (detail: ColumnStateChangeDetail) => void
+  onColumnReorder?: (detail: ColumnReorderDetail) => void
+  onColumnVisibilityChange?: (detail: ColumnVisibilityChangeDetail) => void
+}
+
+export type DataGridRef = {
+  readonly gridElement: DataGridElement | null
+  getRowHeight(rowIndex: number): number
+  getColumnWidth(column: GridColumn): number
+  setRowHeight(rowIndex: number, height: number): void
+  resetRowHeight(rowIndex: number): void
+  resetAllRowHeights(): void
+  setColumnWidth(columnKey: string, width: number): void
+  resetColumnWidth(columnKey: string): void
+  resetAllColumnWidths(): void
+  moveColumn(columnKey: string, targetIndex: number): void
+  getColumnOrder(): string[]
+  setColumnOrder(columnKeys: string[]): void
+  resetColumnOrder(): void
+  setColumnVisible(columnKey: string, visible: boolean): void
+  isColumnVisible(columnKey: string): boolean
+  getVisibleColumnKeys(): string[]
+  resetColumnVisibility(): void
+  getColumnState(): GridColumnState
+  setColumnState(state: GridColumnState): void
+  resetColumnState(): void
+  bestFitColumn(columnKey: string): number | null
+  bestFitAllColumns(): BestFitColumnWidth[]
+  copySelectedCells(): Promise<boolean>
+  copySelectedRows(): Promise<boolean>
+  setQuickSearch(query: string): void
+  clearQuickSearch(): void
+  getQuickSearch(): string
+  setFilter(filter: GridFilter): void
+  clearFilter(columnKey?: string): void
+  getFilters(): GridFilter[]
+  setPage(pageIndex: number): void
+  setPageSize(pageSize: number): void
+  getPagination(): GridPaginationState
+  getTotalRowCount(): number
+  selectRow(rowIndex: number, intent?: SelectionIntent): void
+  selectAllRows(): void
+  clearSelection(): void
+  getSelection(): GridSelection
+  isRowSelected(rowIndex: number): boolean
+  isCellSelected(rowIndex: number, columnKey: string): boolean
+}
+
+export type DataGridInstance = DataGridRef
+
+const GRID_UNAVAILABLE_MESSAGE = 'LitGrid is not available before the React component is mounted.'
+
+export const DataGrid = forwardRef<DataGridRef, DataGridProps>(function DataGrid(
+  {
+    data,
+    columns = [],
+    config = {},
+    theme = 'light',
+    ariaLabel = 'Data grid',
+    ariaDescription = '',
+    screenReaderAnnouncements = true,
+    height = 320,
+    rowHeight = 36,
+    overscan = 4,
+    columnOverscan = 2,
+    bestFitSampleSize = 10,
+    quickSearchDebounceThreshold = 10000,
+    quickSearchDebounceMs = 150,
+    columnStateStorageKey,
+    onColumnStateChange,
+    onColumnReorder,
+    onColumnVisibilityChange
+  },
+  forwardedRef
+) {
+  const gridRef = useRef<DataGridElement | null>(null)
+
+  const requireGridElement = (): DataGridElement => {
+    if (!gridRef.current) throw new Error(GRID_UNAVAILABLE_MESSAGE)
+    return gridRef.current
+  }
+
+  useImperativeHandle(
+    forwardedRef,
+    () => ({
+      get gridElement() {
+        return gridRef.current
+      },
+      getRowHeight: (rowIndex: number) => requireGridElement().getRowHeight(rowIndex),
+      getColumnWidth: (column: GridColumn) => requireGridElement().getColumnWidth(column),
+      setRowHeight: (rowIndex: number, heightVal: number) => requireGridElement().setRowHeight(rowIndex, heightVal),
+      resetRowHeight: (rowIndex: number) => requireGridElement().resetRowHeight(rowIndex),
+      resetAllRowHeights: () => requireGridElement().resetAllRowHeights(),
+      setColumnWidth: (columnKey: string, width: number) => requireGridElement().setColumnWidth(columnKey, width),
+      resetColumnWidth: (columnKey: string) => requireGridElement().resetColumnWidth(columnKey),
+      resetAllColumnWidths: () => requireGridElement().resetAllColumnWidths(),
+      moveColumn: (columnKey: string, targetIndex: number) => requireGridElement().moveColumn(columnKey, targetIndex),
+      getColumnOrder: () => requireGridElement().getColumnOrder(),
+      setColumnOrder: (columnKeys: string[]) => requireGridElement().setColumnOrder(columnKeys),
+      resetColumnOrder: () => requireGridElement().resetColumnOrder(),
+      setColumnVisible: (columnKey: string, visible: boolean) => requireGridElement().setColumnVisible(columnKey, visible),
+      isColumnVisible: (columnKey: string) => requireGridElement().isColumnVisible(columnKey),
+      getVisibleColumnKeys: () => requireGridElement().getVisibleColumnKeys(),
+      resetColumnVisibility: () => requireGridElement().resetColumnVisibility(),
+      getColumnState: () => requireGridElement().getColumnState(),
+      setColumnState: (state: GridColumnState) => requireGridElement().setColumnState(state),
+      resetColumnState: () => requireGridElement().resetColumnState(),
+      bestFitColumn: (columnKey: string) => requireGridElement().bestFitColumn(columnKey),
+      bestFitAllColumns: () => requireGridElement().bestFitAllColumns(),
+      copySelectedCells: () => requireGridElement().copySelectedCells(),
+      copySelectedRows: () => requireGridElement().copySelectedRows(),
+      setQuickSearch: (query: string) => requireGridElement().setQuickSearch(query),
+      clearQuickSearch: () => requireGridElement().clearQuickSearch(),
+      getQuickSearch: () => requireGridElement().getQuickSearch(),
+      setFilter: (filter: GridFilter) => requireGridElement().setFilter(filter),
+      clearFilter: (columnKey?: string) => requireGridElement().clearFilter(columnKey),
+      getFilters: () => requireGridElement().getFilters(),
+      setPage: (pageIndex: number) => requireGridElement().setPage(pageIndex),
+      setPageSize: (pageSize: number) => requireGridElement().setPageSize(pageSize),
+      getPagination: () => requireGridElement().getPagination(),
+      getTotalRowCount: () => requireGridElement().getTotalRowCount(),
+      selectRow: (rowIndex: number, intent?: SelectionIntent) => requireGridElement().selectRow(rowIndex, intent),
+      selectAllRows: () => requireGridElement().selectAllRows(),
+      clearSelection: () => requireGridElement().clearSelection(),
+      getSelection: () => requireGridElement().getSelection(),
+      isRowSelected(rowIndex: number) {
+        return requireGridElement().isRowSelected(rowIndex)
+      },
+      isCellSelected(rowIndex: number, columnKey: string) {
+        return requireGridElement().isCellSelected(rowIndex, columnKey)
+      }
+    }),
+    []
+  )
+
+  useEffect(() => {
+    const grid = gridRef.current
+    if (!grid) return
+
+    syncGridInputs(grid, {
+      data,
+      columns,
+      config,
+      theme,
+      ariaLabel,
+      ariaDescription,
+      screenReaderAnnouncements,
+      height,
+      rowHeight,
+      overscan,
+      columnOverscan,
+      bestFitSampleSize,
+      quickSearchDebounceThreshold,
+      quickSearchDebounceMs,
+      columnStateStorageKey
+    })
+  }, [
+    data,
+    columns,
+    config,
+    theme,
+    ariaLabel,
+    ariaDescription,
+    screenReaderAnnouncements,
+    height,
+    rowHeight,
+    overscan,
+    columnOverscan,
+    bestFitSampleSize,
+    quickSearchDebounceThreshold,
+    quickSearchDebounceMs,
+    columnStateStorageKey
+  ])
+
+  useEffect(() => {
+    const element = gridRef.current
+    if (!element || !onColumnStateChange) return
+
+    const handleColumnStateChange = (event: Event) => {
+      onColumnStateChange((event as CustomEvent<ColumnStateChangeDetail>).detail)
+    }
+
+    element.addEventListener('column-state-change', handleColumnStateChange)
+    return () => element.removeEventListener('column-state-change', handleColumnStateChange)
+  }, [onColumnStateChange])
+
+  useEffect(() => {
+    const element = gridRef.current
+    if (!element || !onColumnReorder) return
+
+    const handleColumnReorder = (event: Event) => {
+      onColumnReorder((event as CustomEvent<ColumnReorderDetail>).detail)
+    }
+
+    element.addEventListener('column-reorder', handleColumnReorder)
+    return () => element.removeEventListener('column-reorder', handleColumnReorder)
+  }, [onColumnReorder])
+
+  useEffect(() => {
+    const element = gridRef.current
+    if (!element || !onColumnVisibilityChange) return
+
+    const handleColumnVisibilityChange = (event: Event) => {
+      onColumnVisibilityChange((event as CustomEvent<ColumnVisibilityChangeDetail>).detail)
+    }
+
+    element.addEventListener('column-visibility-change', handleColumnVisibilityChange)
+    return () => element.removeEventListener('column-visibility-change', handleColumnVisibilityChange)
+  }, [onColumnVisibilityChange])
+
+  return <yc-grid ref={gridRef}></yc-grid>
+})

package/src/gridBindings.ts

@@ -0,0 +1,63 @@
+import type {
+  DataGridElement,
+  GridColumn,
+  GridConfig,
+  GridTheme
+} from '@tipolox/litgrid-web'
+
+export type ReactGridInputs = {
+  data: unknown[]
+  columns: GridColumn[]
+  config: GridConfig
+  theme: GridTheme
+  ariaLabel: string
+  ariaDescription: string
+  screenReaderAnnouncements: boolean
+  height: number
+  rowHeight: number
+  overscan: number
+  columnOverscan: number
+  bestFitSampleSize: number
+  quickSearchDebounceThreshold: number
+  quickSearchDebounceMs: number
+  columnStateStorageKey?: string
+}
+
+const synchronizedInputs = new WeakMap<DataGridElement, Record<string, unknown>>()
+
+export function syncGridInputs(
+  grid: DataGridElement,
+  inputs: ReactGridInputs
+): void {
+  // Keep the existing effect-triggered synchronization contract, including
+  // in-place mutations. Navigation is retained by the structural grid setters.
+  grid.data = inputs.data
+  grid.columns = inputs.columns
+  const values = {
+    config: inputs.config,
+    theme: inputs.theme, ariaLabel: inputs.ariaLabel, ariaDescription: inputs.ariaDescription,
+    screenReaderAnnouncements: inputs.screenReaderAnnouncements,
+    viewportHeight: inputs.height, virtualRowHeight: inputs.rowHeight,
+    overscanCount: inputs.overscan, columnOverscanCount: inputs.columnOverscan,
+    bestFitSampleSize: inputs.bestFitSampleSize,
+    quickSearchDebounceThreshold: inputs.quickSearchDebounceThreshold,
+    quickSearchDebounceMs: inputs.quickSearchDebounceMs,
+    columnStateStorageKey: inputs.columnStateStorageKey ?? null
+  }
+  // Snapshot only the fixed-size configuration, never row data or column content.
+  const config = inputs.config
+  const configKey = JSON.stringify([
+    config.selection?.mode ?? 'none', config.selection?.checkboxes ?? false,
+    config.rowHeader?.enabled ?? false, config.rowHeader?.width ?? 56,
+    config.pagination?.enabled ?? false,
+    Number.isFinite(config.pagination?.pageSize) && config.pagination!.pageSize! > 0 ? Math.max(1, Math.floor(config.pagination!.pageSize!)) : 50,
+    Number.isFinite(config.pagination?.pageIndex) && config.pagination!.pageIndex! >= 0 ? Math.floor(config.pagination!.pageIndex!) : 0
+  ])
+  const previous = synchronizedInputs.get(grid)
+  for (const [key, value] of Object.entries(values)) {
+    if (!previous || (key === 'config' ? previous.configKey !== configKey : previous[key] !== value)) {
+      Reflect.set(grid, key, value)
+    }
+  }
+  synchronizedInputs.set(grid, { ...values, configKey })
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { DataGrid } from './DataGrid.js'
+export type { DataGridInstance, DataGridProps, DataGridRef } from './DataGrid.js'
+export type {
+  BestFitColumnWidth,
+  ColumnReorderDetail,
+  ColumnStateChangeDetail,
+  ColumnVisibilityChangeDetail,
+  DataGridElement,
+  GridColumn,
+  GridColumnState,
+  GridConfig,
+  GridFilter,
+  GridPaginationState,
+  GridSelection,
+  GridTheme,
+  SelectionIntent
+} from '@tipolox/litgrid-web'