gp-grid-react 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -1,15 +1,20 @@
 import React from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region ../core/src/types.d.ts
+/** Cell data type primitive types */
 type CellDataType = "text" | "number" | "boolean" | "date" | "dateString" | "dateTime" | "dateTimeString" | "object";
+/** Cell value type */
 type CellValue = string | number | boolean | Date | object | null;
+/** Row type */
 type Row = unknown;
+/** Sort direction type */
 type SortDirection = "asc" | "desc";
+/** Sort model type */
 type SortModel = {
   colId: string;
   direction: SortDirection;
 };
+/** Filter model type */
 type FilterModel = Record<string, string>;
 interface ColumnDefinition {
   field: string;
@@ -33,68 +38,88 @@ interface CellRange {
   endRow: number;
   endCol: number;
 }
+/** Data source request */
 interface DataSourceRequest {
+  /** Pagination */
   pagination: {
+    /** Page index */
     pageIndex: number;
+    /** Page size */
     pageSize: number;
   };
+  /** Sort */
   sort?: SortModel[];
+  /** Filter */
   filter?: FilterModel;
 }
+/** Data source response */
 interface DataSourceResponse<TData = Row> {
+  /** Rows */
   rows: TData[];
+  /** Total rows */
   totalRows: number;
 }
 interface DataSource<TData = Row> {
   fetch(request: DataSourceRequest): Promise<DataSourceResponse<TData>>;
 }
+/** Slot lifecycle instructions */
 interface CreateSlotInstruction {
   type: "CREATE_SLOT";
   slotId: string;
 }
+/** Destroy slot instruction */
 interface DestroySlotInstruction {
   type: "DESTROY_SLOT";
   slotId: string;
 }
+/** Assign slot instruction */
 interface AssignSlotInstruction {
   type: "ASSIGN_SLOT";
   slotId: string;
   rowIndex: number;
   rowData: Row;
 }
+/** Move slot instruction */
 interface MoveSlotInstruction {
   type: "MOVE_SLOT";
   slotId: string;
   translateY: number;
 }
+/** Selection instructions */
 interface SetActiveCellInstruction {
   type: "SET_ACTIVE_CELL";
   position: CellPosition | null;
 }
+/** Set selection range instruction */
 interface SetSelectionRangeInstruction {
   type: "SET_SELECTION_RANGE";
   range: CellRange | null;
 }
+/** Edit instructions */
 interface StartEditInstruction {
   type: "START_EDIT";
   row: number;
   col: number;
   initialValue: CellValue;
 }
+/** Stop edit instruction */
 interface StopEditInstruction {
   type: "STOP_EDIT";
 }
+/** Commit edit instruction */
 interface CommitEditInstruction {
   type: "COMMIT_EDIT";
   row: number;
   col: number;
   value: CellValue;
 }
+/** Layout instructions */
 interface SetContentSizeInstruction {
   type: "SET_CONTENT_SIZE";
   width: number;
   height: number;
 }
+/** Update header instruction */
 interface UpdateHeaderInstruction {
   type: "UPDATE_HEADER";
   colIndex: number;
@@ -102,15 +127,18 @@ interface UpdateHeaderInstruction {
   sortDirection?: SortDirection;
   sortIndex?: number;
 }
+/** Fill handle instructions */
 interface StartFillInstruction {
   type: "START_FILL";
   sourceRange: CellRange;
 }
+/** Update fill instruction */
 interface UpdateFillInstruction {
   type: "UPDATE_FILL";
   targetRow: number;
   targetCol: number;
 }
+/** Commit fill instruction */
 interface CommitFillInstruction {
   type: "COMMIT_FILL";
   filledCells: Array<{
@@ -119,42 +147,73 @@ interface CommitFillInstruction {
     value: CellValue;
   }>;
 }
+/** Cancel fill instruction */
 interface CancelFillInstruction {
   type: "CANCEL_FILL";
 }
+/** Data loading instruction */
 interface DataLoadingInstruction {
   type: "DATA_LOADING";
 }
+/** Data loaded instruction */
 interface DataLoadedInstruction {
   type: "DATA_LOADED";
   totalRows: number;
 }
+/** Data error instruction */
 interface DataErrorInstruction {
   type: "DATA_ERROR";
   error: string;
 }
-type GridInstruction = CreateSlotInstruction | DestroySlotInstruction | AssignSlotInstruction | MoveSlotInstruction | SetActiveCellInstruction | SetSelectionRangeInstruction | StartEditInstruction | StopEditInstruction | CommitEditInstruction | SetContentSizeInstruction | UpdateHeaderInstruction | StartFillInstruction | UpdateFillInstruction | CommitFillInstruction | CancelFillInstruction | DataLoadingInstruction | DataLoadedInstruction | DataErrorInstruction;
+/** Union type of all instructions */
+type GridInstruction = /** Slot lifecycle */
+CreateSlotInstruction | DestroySlotInstruction | AssignSlotInstruction | MoveSlotInstruction
+/** Selection */ | SetActiveCellInstruction | SetSelectionRangeInstruction
+/** Editing */ | StartEditInstruction | StopEditInstruction | CommitEditInstruction
+/** Layout */ | SetContentSizeInstruction | UpdateHeaderInstruction
+/** Fill handle */ | StartFillInstruction | UpdateFillInstruction | CommitFillInstruction | CancelFillInstruction
+/** Data */ | DataLoadingInstruction | DataLoadedInstruction | DataErrorInstruction;
+/** Cell renderer params */
 interface CellRendererParams {
+  /** Cell value */
   value: CellValue;
+  /** Row data */
   rowData: Row;
+  /** Column definition */
   column: ColumnDefinition;
+  /** Row index */
   rowIndex: number;
+  /** Column index */
   colIndex: number;
+  /** Is active cell */
   isActive: boolean;
+  /** Is selected cell */
   isSelected: boolean;
+  /** Is editing cell */
   isEditing: boolean;
 }
+/** Edit renderer params */
 interface EditRendererParams extends CellRendererParams {
+  /** Initial value */
   initialValue: CellValue;
+  /** On value change */
   onValueChange: (newValue: CellValue) => void;
+  /** On commit */
   onCommit: () => void;
+  /** On cancel */
   onCancel: () => void;
 }
+/** Header renderer params */
 interface HeaderRendererParams {
+  /** Column definition */
   column: ColumnDefinition;
+  /** Column index */
   colIndex: number;
+  /** Sort direction */
   sortDirection?: SortDirection;
+  /** Sort index */
   sortIndex?: number;
+  /** On sort */
   onSort: (direction: SortDirection | null, addToExisting: boolean) => void;
 }
 //#endregion
@@ -162,10 +221,13 @@ interface HeaderRendererParams {
 /**
  * Creates a client-side data source that holds all data in memory.
  * Sorting and filtering are performed client-side.
+ * For large datasets (10k+ rows), sorting is automatically offloaded to a Web Worker.
  */
 declare function createClientDataSource<TData extends Row = Row>(data: TData[], options?: {
   /** Custom field accessor for nested properties */
   getFieldValue?: (row: TData, field: string) => CellValue;
+  /** Use Web Worker for sorting large datasets (default: true) */
+  useWorker?: boolean;
 }): DataSource<TData>;
 type ServerFetchFunction<TData> = (request: DataSourceRequest) => Promise<DataSourceResponse<TData>>;
 /**
@@ -180,32 +242,53 @@ declare function createServerDataSource<TData extends Row = Row>(fetchFn: Server
 declare function createDataSourceFromArray<TData extends Row = Row>(data: TData[]): DataSource<TData>;
 //#endregion
 //#region src/Grid.d.ts
+/** React cell renderer: A function that renders a cell */
 type ReactCellRenderer = (params: CellRendererParams) => React.ReactNode;
+/** React edit renderer: A function that renders the cell while in edit mode */
 type ReactEditRenderer = (params: EditRendererParams) => React.ReactNode;
+/** React header renderer: A function that renders a header cell */
 type ReactHeaderRenderer = (params: HeaderRendererParams) => React.ReactNode;
+/** Grid component props */
 interface GridProps<TData extends Row = Row> {
+  /** Column definitions */
   columns: ColumnDefinition[];
   /** Data source for the grid */
   dataSource?: DataSource<TData>;
   /** Legacy: Raw row data (will be wrapped in a client data source) */
   rowData?: TData[];
+  /** Row height in pixels */
   rowHeight: number;
+  /** Header height in pixels: Default to row height */
   headerHeight?: number;
+  /** Overscan: How many rows to render outside the viewport */
   overscan?: number;
-  /** Show filter row below headers */
+  /** Show filter row below headers: Default to false */
   showFilters?: boolean;
-  /** Debounce time for filter input (ms) */
+  /** Debounce time for filter input (ms): Default to 300 */
   filterDebounce?: number;
-  /** Enable dark mode styling */
+  /** Enable dark mode styling: Default to false */
   darkMode?: boolean;
+  /** Wheel scroll dampening factor when virtual scrolling is active (0-1): Default 0.1 */
+  wheelDampening?: number;
+  /** Renderer registries */
   cellRenderers?: Record<string, ReactCellRenderer>;
+  /** Edit renderer registries */
   editRenderers?: Record<string, ReactEditRenderer>;
+  /** Header renderer registries */
   headerRenderers?: Record<string, ReactHeaderRenderer>;
+  /** Global cell renderer */
   cellRenderer?: ReactCellRenderer;
+  /** Global edit renderer */
   editRenderer?: ReactEditRenderer;
+  /** Global header renderer */
   headerRenderer?: ReactHeaderRenderer;
 }
-declare function Grid<TData extends Row = Row>(props: GridProps<TData>): react_jsx_runtime0.JSX.Element;
+/**
+ * Grid component
+ * @param props - Grid component props
+ * @returns Grid React component
+ */
+declare function Grid<TData extends Row = Row>(props: GridProps<TData>): React.ReactNode;
 //#endregion
 export { type CellDataType, type CellPosition, type CellRange, type CellRendererParams, type CellValue, type ColumnDefinition, type DataSource, type DataSourceRequest, type DataSourceResponse, type EditRendererParams, type FilterModel, Grid, type GridInstruction, type GridProps, type HeaderRendererParams, type ReactCellRenderer, type ReactEditRenderer, type ReactHeaderRenderer, type Row, type SortDirection, type SortModel, createClientDataSource, createDataSourceFromArray, createServerDataSource };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -540,9 +540,14 @@ function createInitialState() {
 		totalRows: 0
 	};
 }
+/**
+* Grid component
+* @param props - Grid component props
+* @returns Grid React component
+*/
 function Grid(props) {
 	injectStyles();
-	const { columns, dataSource: providedDataSource, rowData, rowHeight, headerHeight = rowHeight, overscan = 3, showFilters = false, filterDebounce = 300, darkMode = false, cellRenderers = {}, editRenderers = {}, headerRenderers = {}, cellRenderer, editRenderer, headerRenderer } = props;
+	const { columns, dataSource: providedDataSource, rowData, rowHeight, headerHeight = rowHeight, overscan = 3, showFilters = false, filterDebounce = 300, darkMode = false, wheelDampening = .1, cellRenderers = {}, editRenderers = {}, headerRenderers = {}, cellRenderer, editRenderer, headerRenderer } = props;
 	const containerRef = useRef(null);
 	const coreRef = useRef(null);
 	const [state, dispatch] = useReducer(gridReducer, null, createInitialState);
@@ -603,6 +608,15 @@ function Grid(props) {
 		if (!container || !core) return;
 		core.setViewport(container.scrollTop, container.scrollLeft, container.clientWidth, container.clientHeight);
 	}, []);
+	const handleWheel = useCallback((e) => {
+		const container = containerRef.current;
+		const core = coreRef.current;
+		if (!container || !core) return;
+		if (!core.isScalingActive()) return;
+		e.preventDefault();
+		container.scrollTop += e.deltaY * wheelDampening;
+		container.scrollLeft += e.deltaX * wheelDampening;
+	}, [wheelDampening]);
 	useEffect(() => {
 		const container = containerRef.current;
 		const core = coreRef.current;
@@ -696,23 +710,24 @@ function Grid(props) {
 		if (!state.activeCell || !containerRef.current || state.editingCell) return;
 		const { row, col } = state.activeCell;
 		const container = containerRef.current;
-		const cellTop = row * rowHeight + totalHeaderHeight;
-		const cellBottom = cellTop + rowHeight;
+		const core = coreRef.current;
+		if (!core) return;
+		const { start: visibleStart, end: visibleEnd } = core.getVisibleRowRange();
+		if (row < visibleStart) container.scrollTop = core.getScrollTopForRow(row);
+		else if (row > visibleEnd) {
+			const visibleRows = Math.max(1, visibleEnd - visibleStart);
+			const targetFirstRow = Math.max(0, row - visibleRows);
+			container.scrollTop = core.getScrollTopForRow(targetFirstRow);
+		}
 		const cellLeft = columnPositions[col] ?? 0;
 		const cellRight = cellLeft + (columns[col]?.width ?? 0);
-		const visibleTop = container.scrollTop + totalHeaderHeight;
-		const visibleBottom = container.scrollTop + container.clientHeight;
 		const visibleLeft = container.scrollLeft;
 		const visibleRight = container.scrollLeft + container.clientWidth;
-		if (cellTop < visibleTop) container.scrollTop = cellTop - totalHeaderHeight;
-		else if (cellBottom > visibleBottom) container.scrollTop = cellBottom - container.clientHeight;
 		if (cellLeft < visibleLeft) container.scrollLeft = cellLeft;
 		else if (cellRight > visibleRight) container.scrollLeft = cellRight - container.clientWidth;
 	}, [
 		state.activeCell,
 		state.editingCell,
-		rowHeight,
-		totalHeaderHeight,
 		columnPositions,
 		columns
 	]);
@@ -782,7 +797,7 @@ function Grid(props) {
 			const scrollTop = container.scrollTop;
 			const mouseX = e.clientX - rect.left + scrollLeft;
 			const mouseY = e.clientY - rect.top + scrollTop - totalHeaderHeight;
-			const targetRow = Math.max(0, Math.floor(mouseY / rowHeight));
+			const targetRow = Math.max(0, core.getRowIndexAtDisplayY(mouseY, scrollTop));
 			let targetCol = 0;
 			for (let i = 0; i < columnPositions.length - 1; i++) {
 				if (mouseX >= columnPositions[i] && mouseX < columnPositions[i + 1]) {
@@ -858,7 +873,7 @@ function Grid(props) {
 			const scrollTop = container.scrollTop;
 			const mouseX = e.clientX - rect.left + scrollLeft;
 			const mouseY = e.clientY - rect.top + scrollTop - totalHeaderHeight;
-			const targetRow = Math.max(0, Math.min(Math.floor(mouseY / rowHeight), core.getRowCount() - 1));
+			const targetRow = Math.max(0, Math.min(core.getRowIndexAtDisplayY(mouseY, scrollTop), core.getRowCount() - 1));
 			let targetCol = 0;
 			for (let i = 0; i < columnPositions.length - 1; i++) {
 				if (mouseX >= columnPositions[i] && mouseX < columnPositions[i + 1]) {
@@ -911,7 +926,6 @@ function Grid(props) {
 	}, [
 		isDraggingSelection,
 		totalHeaderHeight,
-		rowHeight,
 		columnPositions,
 		columns.length
 	]);
@@ -1060,7 +1074,7 @@ function Grid(props) {
 	}, [headerRenderers, headerRenderer]);
 	const slotsArray = useMemo(() => Array.from(state.slots.values()), [state.slots]);
 	const fillHandlePosition = useMemo(() => {
-		const { activeCell, selectionRange } = state;
+		const { activeCell, selectionRange, slots } = state;
 		if (!activeCell && !selectionRange) return null;
 		let row, col;
 		let minCol, maxCol;
@@ -1079,7 +1093,12 @@ function Grid(props) {
 			const column = columns[c];
 			if (!column || column.editable !== true) return null;
 		}
-		const cellTop = row * rowHeight + totalHeaderHeight;
+		let cellTop = null;
+		for (const slot of slots.values()) if (slot.rowIndex === row) {
+			cellTop = slot.translateY;
+			break;
+		}
+		if (cellTop === null) return null;
 		const cellLeft = columnPositions[col] ?? 0;
 		const cellWidth = columns[col]?.width ?? 0;
 		return {
@@ -1089,8 +1108,8 @@ function Grid(props) {
 	}, [
 		state.activeCell,
 		state.selectionRange,
+		state.slots,
 		rowHeight,
-		totalHeaderHeight,
 		columnPositions,
 		columns
 	]);
@@ -1104,6 +1123,7 @@ function Grid(props) {
 			position: "relative"
 		},
 		onScroll: handleScroll,
+		onWheel: handleWheel,
 		onKeyDown: handleKeyDown,
 		tabIndex: 0,
 		children: /* @__PURE__ */ jsxs("div", {