@vuer-ai/vuer-uikit 0.0.121 → 0.1.0

package/src/ui/virtual-grid/VirtualGrid.tsx

@@ -0,0 +1,345 @@
+import React, {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ComponentProps,
+} from "react";
+
+import type { VirtualGridProps } from "./types";
+import { useVirtualGrid } from "./useVirtualGrid";
+import { cn } from "../../hooks";
+
+interface VirtualGridComponentProps<T>
+  extends Omit<ComponentProps<"div">, "children">,
+    VirtualGridProps<T> {}
+
+/**
+ * VirtualGrid component - renders only visible cells for efficient grid rendering.
+ * Supports both fixed and variable row/column sizes, cell spanning, and sticky headers/columns.
+ *
+ * @param data - 2D array of cell data
+ * @param rowCount - Number of rows in the grid
+ * @param columnCount - Number of columns in the grid
+ * @param rowHeight - Height for each row (fixed or function)
+ * @param columnWidth - Width for each column (fixed or function)
+ * @param height - Container height
+ * @param width - Container width (default: '100%')
+ * @param overscanRows - Extra rows to render outside visible area (default: 2)
+ * @param overscanColumns - Extra columns to render outside visible area (default: 2)
+ * @param getCellKey - Function to get a unique key for each cell
+ * @param getColSpan - Function to get column span for a cell
+ * @param getRowSpan - Function to get row span for a cell
+ * @param children - Render function for each cell
+ * @param stickyHeader - Keep first row visible
+ * @param stickyColumn - Keep first column visible
+ */
+function VirtualGridInner<T>(
+  {
+    data,
+    rowCount,
+    columnCount,
+    rowHeight,
+    columnWidth,
+    height,
+    width = "100%",
+    overscanRows = 2,
+    overscanColumns = 2,
+    getCellKey,
+    getColSpan,
+    getRowSpan,
+    children,
+    stickyHeader = false,
+    stickyColumn = false,
+    className,
+    style,
+    ...props
+  }: VirtualGridComponentProps<T>,
+  ref: React.ForwardedRef<HTMLDivElement>,
+) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const stickyLayerRef = useRef<HTMLDivElement>(null);
+  const [scrollTop, setScrollTop] = useState(0);
+  const [scrollLeft, setScrollLeft] = useState(0);
+  const [containerWidth, setContainerWidth] = useState(0);
+  const [containerHeight, setContainerHeight] = useState(0);
+
+  // Track scroll position in ref for immediate updates
+  const scrollRef = useRef({ top: 0, left: 0 });
+
+  // Combine refs
+  const setRefs = useCallback(
+    (node: HTMLDivElement | null) => {
+      (containerRef as React.MutableRefObject<HTMLDivElement | null>).current = node;
+      if (typeof ref === "function") {
+        ref(node);
+      } else if (ref) {
+        ref.current = node;
+      }
+    },
+    [ref],
+  );
+
+  // Measure container dimensions
+  useEffect(() => {
+    const container = containerRef.current;
+    if (!container) return;
+
+    const resizeObserver = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        setContainerWidth(entry.contentRect.width);
+        setContainerHeight(entry.contentRect.height);
+      }
+    });
+
+    resizeObserver.observe(container);
+    setContainerWidth(container.clientWidth);
+    setContainerHeight(container.clientHeight);
+
+    return () => resizeObserver.disconnect();
+  }, []);
+
+  const {
+    visibleRange,
+    totalWidth,
+    totalHeight,
+    getCellStyle,
+    getRowOffset,
+    getColumnOffset,
+    getRowHeight,
+    getColumnWidth,
+  } = useVirtualGrid({
+    rowCount,
+    columnCount,
+    rowHeight,
+    columnWidth,
+    containerWidth,
+    containerHeight,
+    scrollTop,
+    scrollLeft,
+    overscanRows,
+    overscanColumns,
+    getColSpan,
+    getRowSpan,
+  });
+
+  // Handle scroll - update CSS variables immediately, debounce state updates
+  const rafRef = useRef<number | null>(null);
+
+  const handleScroll = useCallback((e: React.UIEvent<HTMLDivElement>) => {
+    const newScrollTop = e.currentTarget.scrollTop;
+    const newScrollLeft = e.currentTarget.scrollLeft;
+
+    // Update ref immediately
+    scrollRef.current = { top: newScrollTop, left: newScrollLeft };
+
+    // Update CSS variables immediately for smooth sticky positioning
+    // Round to prevent sub-pixel jitter
+    if (stickyLayerRef.current) {
+      stickyLayerRef.current.style.setProperty("--scroll-top", `${Math.round(newScrollTop)}px`);
+      stickyLayerRef.current.style.setProperty("--scroll-left", `${Math.round(newScrollLeft)}px`);
+    }
+
+    // Debounce state updates for virtualization range calculation
+    if (rafRef.current) {
+      cancelAnimationFrame(rafRef.current);
+    }
+    rafRef.current = requestAnimationFrame(() => {
+      setScrollTop(newScrollTop);
+      setScrollLeft(newScrollLeft);
+    });
+  }, []);
+
+  // Cleanup RAF on unmount
+  useEffect(() => {
+    return () => {
+      if (rafRef.current) {
+        cancelAnimationFrame(rafRef.current);
+      }
+    };
+  }, []);
+
+  // Initialize CSS variables
+  useLayoutEffect(() => {
+    if (stickyLayerRef.current) {
+      stickyLayerRef.current.style.setProperty("--scroll-top", "0px");
+      stickyLayerRef.current.style.setProperty("--scroll-left", "0px");
+    }
+  }, []);
+
+  // Track which cells are covered by spans
+  const coveredCells = new Set<string>();
+
+  // Pre-calculate covered cells from spans
+  if (getColSpan || getRowSpan) {
+    for (let row = visibleRange.startRow; row <= visibleRange.endRow; row++) {
+      for (let col = visibleRange.startCol; col <= visibleRange.endCol; col++) {
+        const colspan = getColSpan?.(row, col) ?? 1;
+        const rowspan = getRowSpan?.(row, col) ?? 1;
+
+        if (colspan > 1 || rowspan > 1) {
+          for (let r = row; r < row + rowspan; r++) {
+            for (let c = col; c < col + colspan; c++) {
+              if (r !== row || c !== col) {
+                coveredCells.add(`${r}-${c}`);
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // Render visible cells
+  const visibleCells = [];
+  for (let row = visibleRange.startRow; row <= visibleRange.endRow && row < rowCount; row++) {
+    for (let col = visibleRange.startCol; col <= visibleRange.endCol && col < columnCount; col++) {
+      // Skip cells covered by spans
+      if (coveredCells.has(`${row}-${col}`)) {
+        continue;
+      }
+
+      // Skip header row and sticky column cells - they're rendered separately
+      if ((stickyHeader && row === 0) || (stickyColumn && col === 0)) {
+        continue;
+      }
+
+      const cellData = data[row]?.[col];
+      const key = getCellKey ? getCellKey(row, col) : `${row}-${col}`;
+      const cellStyle = getCellStyle(row, col);
+
+      visibleCells.push(
+        <React.Fragment key={key}>{children(cellData, row, col, cellStyle)}</React.Fragment>,
+      );
+    }
+  }
+
+  // Style for sticky cell content - fills the wrapper
+  const stickyContentStyle = { width: "100%", height: "100%" };
+
+  // Render sticky header cells (using CSS variable for Y position)
+  const stickyHeaderCells = [];
+  if (stickyHeader && rowCount > 0) {
+    for (let col = visibleRange.startCol; col <= visibleRange.endCol && col < columnCount; col++) {
+      // Skip first column if sticky column is enabled
+      if (stickyColumn && col === 0) continue;
+      if (coveredCells.has(`0-${col}`)) continue;
+
+      const cellData = data[0]?.[col];
+      const key = getCellKey ? getCellKey(0, col) : `header-${col}`;
+
+      stickyHeaderCells.push(
+        <div
+          key={key}
+          className="sticky-header-cell"
+          style={{
+            position: "absolute",
+            top: 0,
+            left: 0,
+            width: getColumnWidth(col),
+            height: getRowHeight(0),
+            transform: `translate3d(${getColumnOffset(col)}px, var(--scroll-top, 0px), 0)`,
+            willChange: "transform",
+            zIndex: 2,
+          }}
+        >
+          {children(cellData, 0, col, stickyContentStyle)}
+        </div>,
+      );
+    }
+  }
+
+  // Render sticky column cells (using CSS variable for X position)
+  const stickyColumnCells = [];
+  if (stickyColumn && columnCount > 0) {
+    for (let row = visibleRange.startRow; row <= visibleRange.endRow && row < rowCount; row++) {
+      // Skip first row if sticky header is enabled
+      if (stickyHeader && row === 0) continue;
+      if (coveredCells.has(`${row}-0`)) continue;
+
+      const cellData = data[row]?.[0];
+      const key = getCellKey ? getCellKey(row, 0) : `sticky-col-${row}`;
+
+      stickyColumnCells.push(
+        <div
+          key={key}
+          className="sticky-column-cell"
+          style={{
+            position: "absolute",
+            top: 0,
+            left: 0,
+            width: getColumnWidth(0),
+            height: getRowHeight(row),
+            transform: `translate3d(var(--scroll-left, 0px), ${getRowOffset(row)}px, 0)`,
+            willChange: "transform",
+            zIndex: 2,
+          }}
+        >
+          {children(cellData, row, 0, stickyContentStyle)}
+        </div>,
+      );
+    }
+  }
+
+  // Render sticky corner cell (using CSS variables for both X and Y)
+  const stickyCornerCell =
+    stickyHeader && stickyColumn && rowCount > 0 && columnCount > 0 ? (
+      <div
+        key="sticky-corner"
+        className="sticky-corner-cell"
+        style={{
+          position: "absolute",
+          top: 0,
+          left: 0,
+          width: getColumnWidth(0),
+          height: getRowHeight(0),
+          transform: `translate3d(var(--scroll-left, 0px), var(--scroll-top, 0px), 0)`,
+          willChange: "transform",
+          zIndex: 3,
+        }}
+      >
+        {children(data[0]?.[0], 0, 0, stickyContentStyle)}
+      </div>
+    ) : null;
+
+  const hasStickyElements = stickyHeader || stickyColumn;
+
+  return (
+    <div
+      ref={setRefs}
+      className={cn("relative overflow-auto", className)}
+      style={{
+        height,
+        width,
+        ...style,
+      }}
+      onScroll={handleScroll}
+      {...props}
+    >
+      <div
+        ref={hasStickyElements ? stickyLayerRef : undefined}
+        style={{
+          height: totalHeight,
+          width: totalWidth,
+          position: "relative",
+        }}
+      >
+        {/* Sticky elements first - stable position in DOM during scroll */}
+        {stickyCornerCell}
+        {stickyHeaderCells}
+        {stickyColumnCells}
+        {/* Visible cells last - changes frequently during scroll */}
+        {visibleCells}
+      </div>
+    </div>
+  );
+}
+
+// Use a generic forwardRef pattern
+export const VirtualGrid = forwardRef(VirtualGridInner) as <T>(
+  props: VirtualGridComponentProps<T> & { ref?: React.ForwardedRef<HTMLDivElement> },
+) => React.ReactElement;
+
+export type { VirtualGridProps };

package/src/ui/virtual-grid/index.ts

@@ -0,0 +1,10 @@
+export { VirtualGrid } from "./VirtualGrid";
+export type {
+  VirtualGridProps,
+  RowHeight,
+  ColumnWidth,
+  GridRange,
+  UseVirtualGridOptions,
+  UseVirtualGridResult,
+} from "./types";
+export { useVirtualGrid } from "./useVirtualGrid";

package/src/ui/virtual-grid/types.ts

@@ -0,0 +1,72 @@
+import type { CSSProperties, ReactNode } from "react";
+
+export type RowHeight = number | ((rowIndex: number) => number);
+export type ColumnWidth = number | ((colIndex: number) => number);
+
+export interface VirtualGridProps<T> {
+  /** 2D array of cell data */
+  data: T[][];
+  /** Number of rows in the grid */
+  rowCount: number;
+  /** Number of columns in the grid */
+  columnCount: number;
+  /** Height for each row - fixed number or function returning height for a given row */
+  rowHeight: RowHeight;
+  /** Width for each column - fixed number or function returning width for a given column */
+  columnWidth: ColumnWidth;
+  /** Container height */
+  height: number | string;
+  /** Container width (default: '100%') */
+  width?: number | string;
+  /** Number of extra rows to render outside visible area (default: 2) */
+  overscanRows?: number;
+  /** Number of extra columns to render outside visible area (default: 2) */
+  overscanColumns?: number;
+  /** Function to get a unique key for each cell */
+  getCellKey?: (row: number, col: number) => string;
+  /** Function to get column span for a cell (default: 1) */
+  getColSpan?: (row: number, col: number) => number;
+  /** Function to get row span for a cell (default: 1) */
+  getRowSpan?: (row: number, col: number) => number;
+  /** Render function for each cell */
+  children: (data: T, row: number, col: number, style: CSSProperties) => ReactNode;
+  /** Keep first row visible when scrolling vertically */
+  stickyHeader?: boolean;
+  /** Keep first column visible when scrolling horizontally */
+  stickyColumn?: boolean;
+  /** Additional className for the container */
+  className?: string;
+}
+
+export interface GridRange {
+  startRow: number;
+  endRow: number;
+  startCol: number;
+  endCol: number;
+}
+
+export interface UseVirtualGridOptions {
+  rowCount: number;
+  columnCount: number;
+  rowHeight: RowHeight;
+  columnWidth: ColumnWidth;
+  containerWidth: number;
+  containerHeight: number;
+  scrollTop: number;
+  scrollLeft: number;
+  overscanRows: number;
+  overscanColumns: number;
+  getColSpan?: (row: number, col: number) => number;
+  getRowSpan?: (row: number, col: number) => number;
+}
+
+export interface UseVirtualGridResult {
+  visibleRange: GridRange;
+  totalWidth: number;
+  totalHeight: number;
+  getRowOffset: (rowIndex: number) => number;
+  getColumnOffset: (colIndex: number) => number;
+  getRowHeight: (rowIndex: number) => number;
+  getColumnWidth: (colIndex: number) => number;
+  getCellStyle: (row: number, col: number) => CSSProperties;
+}

package/src/ui/virtual-grid/useVirtualGrid.ts

@@ -0,0 +1,243 @@
+import { useCallback, useMemo, type CSSProperties } from "react";
+
+import type {
+  ColumnWidth,
+  GridRange,
+  RowHeight,
+  UseVirtualGridOptions,
+  UseVirtualGridResult,
+} from "./types";
+
+/**
+ * Get the height for a row
+ */
+function getHeight(rowHeight: RowHeight, rowIndex: number): number {
+  return typeof rowHeight === "function" ? rowHeight(rowIndex) : rowHeight;
+}
+
+/**
+ * Get the width for a column
+ */
+function getWidth(columnWidth: ColumnWidth, colIndex: number): number {
+  return typeof columnWidth === "function" ? columnWidth(colIndex) : columnWidth;
+}
+
+/**
+ * Binary search to find the start index for a given offset
+ */
+function findStartIndex(
+  count: number,
+  scrollOffset: number,
+  getSize: (index: number) => number,
+): number {
+  if (count === 0) return 0;
+
+  let offset = 0;
+  let low = 0;
+  let high = count - 1;
+
+  // Binary search approximation
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+
+    // Calculate offset for mid
+    let midOffset = 0;
+    for (let i = 0; i < mid; i++) {
+      midOffset += getSize(i);
+    }
+
+    if (midOffset < scrollOffset) {
+      low = mid + 1;
+      offset = midOffset;
+    } else if (midOffset > scrollOffset) {
+      high = mid - 1;
+    } else {
+      return mid;
+    }
+  }
+
+  // Fine-tune by scanning from low
+  let index = Math.max(0, low - 1);
+  offset = 0;
+  for (let i = 0; i < index; i++) {
+    offset += getSize(i);
+  }
+
+  while (index < count - 1 && offset + getSize(index) <= scrollOffset) {
+    offset += getSize(index);
+    index++;
+  }
+
+  return index;
+}
+
+/**
+ * Hook for virtualizing a 2D grid of items
+ */
+export function useVirtualGrid({
+  rowCount,
+  columnCount,
+  rowHeight,
+  columnWidth,
+  containerWidth,
+  containerHeight,
+  scrollTop,
+  scrollLeft,
+  overscanRows,
+  overscanColumns,
+  getColSpan = () => 1,
+  getRowSpan = () => 1,
+}: UseVirtualGridOptions): UseVirtualGridResult {
+  // Memoize size functions
+  const getRowHeightFn = useCallback((index: number) => getHeight(rowHeight, index), [rowHeight]);
+
+  const getColumnWidthFn = useCallback(
+    (index: number) => getWidth(columnWidth, index),
+    [columnWidth],
+  );
+
+  // Calculate total dimensions
+  const totalHeight = useMemo(() => {
+    let height = 0;
+    for (let i = 0; i < rowCount; i++) {
+      height += getRowHeightFn(i);
+    }
+    return height;
+  }, [rowCount, getRowHeightFn]);
+
+  const totalWidth = useMemo(() => {
+    let width = 0;
+    for (let i = 0; i < columnCount; i++) {
+      width += getColumnWidthFn(i);
+    }
+    return width;
+  }, [columnCount, getColumnWidthFn]);
+
+  // Calculate row offsets (memoized)
+  const rowOffsets = useMemo(() => {
+    const offsets: number[] = [0];
+    for (let i = 0; i < rowCount; i++) {
+      offsets.push(offsets[i] + getRowHeightFn(i));
+    }
+    return offsets;
+  }, [rowCount, getRowHeightFn]);
+
+  // Calculate column offsets (memoized)
+  const columnOffsets = useMemo(() => {
+    const offsets: number[] = [0];
+    for (let i = 0; i < columnCount; i++) {
+      offsets.push(offsets[i] + getColumnWidthFn(i));
+    }
+    return offsets;
+  }, [columnCount, getColumnWidthFn]);
+
+  // Get offset for a row
+  const getRowOffset = useCallback((rowIndex: number) => rowOffsets[rowIndex] ?? 0, [rowOffsets]);
+
+  // Get offset for a column
+  const getColumnOffset = useCallback(
+    (colIndex: number) => columnOffsets[colIndex] ?? 0,
+    [columnOffsets],
+  );
+
+  // Calculate visible range
+  const visibleRange = useMemo<GridRange>(() => {
+    if (rowCount === 0 || columnCount === 0) {
+      return { startRow: 0, endRow: 0, startCol: 0, endCol: 0 };
+    }
+
+    // Find start row
+    const startRow = findStartIndex(rowCount, scrollTop, getRowHeightFn);
+
+    // Find end row
+    let endRow = startRow;
+    let accumulatedHeight = getRowOffset(startRow) - scrollTop;
+    while (endRow < rowCount - 1 && accumulatedHeight < containerHeight) {
+      accumulatedHeight += getRowHeightFn(endRow);
+      endRow++;
+    }
+
+    // Find start column
+    const startCol = findStartIndex(columnCount, scrollLeft, getColumnWidthFn);
+
+    // Find end column
+    let endCol = startCol;
+    let accumulatedWidth = getColumnOffset(startCol) - scrollLeft;
+    while (endCol < columnCount - 1 && accumulatedWidth < containerWidth) {
+      accumulatedWidth += getColumnWidthFn(endCol);
+      endCol++;
+    }
+
+    return {
+      startRow: Math.max(0, startRow - overscanRows),
+      endRow: Math.min(rowCount - 1, endRow + overscanRows),
+      startCol: Math.max(0, startCol - overscanColumns),
+      endCol: Math.min(columnCount - 1, endCol + overscanColumns),
+    };
+  }, [
+    rowCount,
+    columnCount,
+    scrollTop,
+    scrollLeft,
+    containerHeight,
+    containerWidth,
+    overscanRows,
+    overscanColumns,
+    getRowHeightFn,
+    getColumnWidthFn,
+    getRowOffset,
+    getColumnOffset,
+  ]);
+
+  // Get style for a cell
+  const getCellStyle = useCallback(
+    (row: number, col: number): CSSProperties => {
+      const top = getRowOffset(row);
+      const left = getColumnOffset(col);
+
+      // Calculate width with colspan
+      const colspan = getColSpan(row, col);
+      let width = 0;
+      for (let c = col; c < col + colspan && c < columnCount; c++) {
+        width += getColumnWidthFn(c);
+      }
+
+      // Calculate height with rowspan
+      const rowspan = getRowSpan(row, col);
+      let height = 0;
+      for (let r = row; r < row + rowspan && r < rowCount; r++) {
+        height += getRowHeightFn(r);
+      }
+
+      return {
+        position: "absolute",
+        top: 0,
+        left: 0,
+        width,
+        height,
+        transform: `translate(${left}px, ${top}px)`,
+      };
+    },
+    [
+      getRowOffset,
+      getColumnOffset,
+      getColSpan,
+      getRowSpan,
+      columnCount,
+      rowCount,
+      getColumnWidthFn,
+      getRowHeightFn,
+    ],
+  );
+
+  return {
+    visibleRange,
+    totalWidth,
+    totalHeight,
+    getRowOffset,
+    getColumnOffset,
+    getRowHeight: getRowHeightFn,
+    getColumnWidth: getColumnWidthFn,
+    getCellStyle,
+  };
+}