virtualized-ui 0.0.1 → 0.1.1

package/README.md

@@ -0,0 +1,192 @@
+# virtualized-ui
+
+Headless virtualized table primitives for React. Built on [TanStack Table](https://tanstack.com/table) and [TanStack Virtual](https://tanstack.com/virtual).
+
+## Installation
+
+```bash
+npm install virtualized-ui
+# or
+pnpm add virtualized-ui
+# or
+yarn add virtualized-ui
+```
+
+**Peer dependencies:** React 18+
+
+## Features
+
+- **Virtualization** - Efficiently render thousands of rows
+- **Sorting** - Single and multi-column sorting
+- **Row Selection** - Checkbox or click-based selection
+- **Row Expansion** - Expandable rows with variable heights
+- **Column Resizing** - Drag to resize columns
+- **Column Reordering** - Drag and drop columns
+- **Keyboard Navigation** - Arrow keys, Home/End, Space/Enter
+- **Infinite Scroll** - Load more data on scroll
+- **Controlled & Uncontrolled** - Flexible state management
+
+## Quick Start
+
+```tsx
+import { useVirtualTable } from 'virtualized-ui';
+import { createColumnHelper } from '@tanstack/react-table';
+
+interface Person {
+  id: number;
+  name: string;
+  age: number;
+}
+
+const columnHelper = createColumnHelper<Person>();
+
+const columns = [
+  columnHelper.accessor('name', { header: 'Name' }),
+  columnHelper.accessor('age', { header: 'Age' }),
+];
+
+function MyTable({ data }: { data: Person[] }) {
+  const {
+    table,
+    rows,
+    virtualItems,
+    totalSize,
+    containerRef,
+  } = useVirtualTable({
+    data,
+    columns,
+  });
+
+  return (
+    <div ref={containerRef} style={{ height: 400, overflow: 'auto' }}>
+      <div style={{ height: totalSize, position: 'relative' }}>
+        {virtualItems.map((virtualRow) => {
+          const row = rows[virtualRow.index];
+          return (
+            <div
+              key={row.id}
+              style={{
+                position: 'absolute',
+                top: virtualRow.start,
+                height: virtualRow.size,
+              }}
+            >
+              {row.getVisibleCells().map((cell) => (
+                <span key={cell.id}>
+                  {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                </span>
+              ))}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+```
+
+## API
+
+### `useVirtualTable<TData>(options)`
+
+The main hook that combines TanStack Table with TanStack Virtual.
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `data` | `TData[]` | required | The data array |
+| `columns` | `ColumnDef<TData>[]` | required | Column definitions |
+| `rowHeight` | `number` | `40` | Height of each row in pixels |
+| `overscan` | `number` | `5` | Number of rows to render outside viewport |
+| `enableRowSelection` | `boolean` | `false` | Enable row selection |
+| `rowSelection` | `RowSelectionState` | - | Controlled selection state |
+| `onRowSelectionChange` | `(state) => void` | - | Selection change callback |
+| `enableSorting` | `boolean` | `false` | Enable column sorting |
+| `enableMultiSort` | `boolean` | `false` | Enable multi-column sorting |
+| `sorting` | `SortingState` | - | Controlled sorting state |
+| `onSortingChange` | `(state) => void` | - | Sorting change callback |
+| `enableRowExpansion` | `boolean` | `false` | Enable expandable rows |
+| `expandedRowHeight` | `number` | `200` | Additional height for expanded rows |
+| `expanded` | `ExpandedState` | - | Controlled expansion state |
+| `onExpandedChange` | `(state) => void` | - | Expansion change callback |
+| `enableColumnResizing` | `boolean` | `false` | Enable column resizing |
+| `columnResizeMode` | `'onChange' \| 'onEnd'` | `'onChange'` | When to update sizes |
+| `enableColumnReordering` | `boolean` | `false` | Enable column reordering |
+| `enableKeyboardNavigation` | `boolean` | `false` | Enable keyboard navigation |
+| `onScrollToBottom` | `() => void` | - | Called when scrolled near bottom |
+| `scrollBottomThreshold` | `number` | `100` | Pixels from bottom to trigger callback |
+| `getRowId` | `(row) => string` | - | Custom row ID function |
+
+#### Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `table` | `Table<TData>` | TanStack Table instance |
+| `rows` | `Row<TData>[]` | Processed rows from table |
+| `virtualizer` | `Virtualizer` | TanStack Virtual instance |
+| `virtualItems` | `VirtualItem[]` | Currently visible virtual items |
+| `totalSize` | `number` | Total scrollable height |
+| `containerRef` | `RefObject<HTMLDivElement>` | Ref for scroll container |
+| `handleScroll` | `() => void` | Scroll handler for infinite scroll |
+| `handleKeyDown` | `(e) => void` | Keyboard event handler |
+| `reorderColumn` | `(from, to) => void` | Reorder columns helper |
+| `setFocusedRow` | `(index) => void` | Set focused row index |
+| `rowSelection` | `RowSelectionState` | Current selection state |
+| `sorting` | `SortingState` | Current sorting state |
+| `expanded` | `ExpandedState` | Current expansion state |
+| `columnSizing` | `ColumnSizingState` | Current column sizes |
+| `columnOrder` | `ColumnOrderState` | Current column order |
+| `focusedRowIndex` | `number` | Currently focused row |
+
+## Examples
+
+### With Row Expansion
+
+```tsx
+const { table, rows, virtualItems, totalSize, containerRef } = useVirtualTable({
+  data,
+  columns,
+  enableRowExpansion: true,
+  rowHeight: 52,
+  expandedRowHeight: 200,
+});
+```
+
+### With Infinite Scroll
+
+```tsx
+const { containerRef, handleScroll } = useVirtualTable({
+  data,
+  columns,
+  onScrollToBottom: () => fetchNextPage(),
+  scrollBottomThreshold: 500,
+});
+
+return (
+  <div ref={containerRef} onScroll={handleScroll} style={{ height: 400, overflow: 'auto' }}>
+    {/* ... */}
+  </div>
+);
+```
+
+### With Sorting
+
+```tsx
+const { table, sorting } = useVirtualTable({
+  data,
+  columns,
+  enableSorting: true,
+  enableMultiSort: true,
+});
+
+// In header:
+<th onClick={header.column.getToggleSortingHandler()}>
+  {header.column.columnDef.header}
+  {header.column.getIsSorted() === 'asc' ? ' ↑' : header.column.getIsSorted() === 'desc' ? ' ↓' : ''}
+</th>
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,477 @@
+'use strict';
+
+var react = require('react');
+var reactTable = require('@tanstack/react-table');
+var reactVirtual = require('@tanstack/react-virtual');
+var jsxRuntime = require('react/jsx-runtime');
+
+// src/VirtualTable/VirtualTable.tsx
+var DEFAULT_ROW_HEIGHT = 40;
+var DEFAULT_EXPANDED_ROW_HEIGHT = 200;
+var DEFAULT_OVERSCAN = 5;
+var DEFAULT_SCROLL_THRESHOLD = 100;
+function getColumnId(column) {
+  if ("id" in column && typeof column.id === "string") {
+    return column.id;
+  }
+  if ("accessorKey" in column && typeof column.accessorKey === "string") {
+    return column.accessorKey;
+  }
+  return "";
+}
+function useVirtualTable(options) {
+  const {
+    data,
+    columns,
+    rowHeight = DEFAULT_ROW_HEIGHT,
+    overscan = DEFAULT_OVERSCAN,
+    enableRowSelection = false,
+    rowSelection: controlledRowSelection,
+    onRowSelectionChange,
+    enableSorting = false,
+    sorting: controlledSorting,
+    onSortingChange,
+    enableMultiSort = false,
+    maxMultiSortColCount,
+    enableColumnResizing = false,
+    columnResizeMode = "onChange",
+    columnSizing: controlledColumnSizing,
+    onColumnSizingChange,
+    enableColumnReordering = false,
+    columnOrder: controlledColumnOrder,
+    onColumnOrderChange,
+    enableRowExpansion = false,
+    expanded: controlledExpanded,
+    onExpandedChange,
+    expandedRowHeight = DEFAULT_EXPANDED_ROW_HEIGHT,
+    getRowCanExpand,
+    getRowId,
+    enableKeyboardNavigation = false,
+    focusedRowIndex: controlledFocusedRowIndex,
+    onFocusedRowChange,
+    onScrollToBottom,
+    scrollBottomThreshold = DEFAULT_SCROLL_THRESHOLD
+  } = options;
+  const containerRef = react.useRef(null);
+  const defaultColumnOrder = react.useMemo(() => columns.map(getColumnId), [columns]);
+  const [internalRowSelection, setInternalRowSelection] = react.useState({});
+  const [internalSorting, setInternalSorting] = react.useState([]);
+  const [internalExpanded, setInternalExpanded] = react.useState({});
+  const [internalColumnSizing, setInternalColumnSizing] = react.useState({});
+  const [internalColumnOrder, setInternalColumnOrder] = react.useState([]);
+  const [internalFocusedRowIndex, setInternalFocusedRowIndex] = react.useState(-1);
+  const rowSelectionState = controlledRowSelection ?? internalRowSelection;
+  const sortingState = controlledSorting ?? internalSorting;
+  const expandedState = controlledExpanded ?? internalExpanded;
+  const columnSizingState = controlledColumnSizing ?? internalColumnSizing;
+  const columnOrderState = controlledColumnOrder ?? (internalColumnOrder.length ? internalColumnOrder : defaultColumnOrder);
+  const focusedRowIndex = controlledFocusedRowIndex ?? internalFocusedRowIndex;
+  const handleRowSelectionChange = react.useCallback(
+    (updater) => {
+      const newValue = typeof updater === "function" ? updater(rowSelectionState) : updater;
+      if (onRowSelectionChange) {
+        onRowSelectionChange(newValue);
+      } else {
+        setInternalRowSelection(newValue);
+      }
+    },
+    [rowSelectionState, onRowSelectionChange]
+  );
+  const handleSortingChange = react.useCallback(
+    (updater) => {
+      const newValue = typeof updater === "function" ? updater(sortingState) : updater;
+      if (onSortingChange) {
+        onSortingChange(newValue);
+      } else {
+        setInternalSorting(newValue);
+      }
+    },
+    [sortingState, onSortingChange]
+  );
+  const handleExpandedChange = react.useCallback(
+    (updater) => {
+      const newValue = typeof updater === "function" ? updater(expandedState) : updater;
+      if (onExpandedChange) {
+        onExpandedChange(newValue);
+      } else {
+        setInternalExpanded(newValue);
+      }
+    },
+    [expandedState, onExpandedChange]
+  );
+  const handleColumnSizingChange = react.useCallback(
+    (updater) => {
+      const newValue = typeof updater === "function" ? updater(columnSizingState) : updater;
+      if (onColumnSizingChange) {
+        onColumnSizingChange(newValue);
+      } else {
+        setInternalColumnSizing(newValue);
+      }
+    },
+    [columnSizingState, onColumnSizingChange]
+  );
+  const handleColumnOrderChange = react.useCallback(
+    (updater) => {
+      const newValue = typeof updater === "function" ? updater(columnOrderState) : updater;
+      if (onColumnOrderChange) {
+        onColumnOrderChange(newValue);
+      } else {
+        setInternalColumnOrder(newValue);
+      }
+    },
+    [columnOrderState, onColumnOrderChange]
+  );
+  const table = reactTable.useReactTable({
+    data,
+    columns,
+    getCoreRowModel: reactTable.getCoreRowModel(),
+    getSortedRowModel: enableSorting ? reactTable.getSortedRowModel() : void 0,
+    getExpandedRowModel: enableRowExpansion ? reactTable.getExpandedRowModel() : void 0,
+    enableRowSelection,
+    enableSorting,
+    enableMultiSort,
+    maxMultiSortColCount,
+    enableColumnResizing,
+    columnResizeMode,
+    getRowCanExpand: enableRowExpansion ? getRowCanExpand ?? (() => true) : void 0,
+    state: {
+      rowSelection: rowSelectionState,
+      sorting: sortingState,
+      expanded: expandedState,
+      columnSizing: columnSizingState,
+      columnOrder: enableColumnReordering ? columnOrderState : void 0
+    },
+    onRowSelectionChange: handleRowSelectionChange,
+    onSortingChange: handleSortingChange,
+    onExpandedChange: handleExpandedChange,
+    onColumnSizingChange: handleColumnSizingChange,
+    onColumnOrderChange: enableColumnReordering ? handleColumnOrderChange : void 0,
+    getRowId
+  });
+  const { rows } = table.getRowModel();
+  const estimateSize = react.useCallback(
+    (index) => {
+      if (!enableRowExpansion) return rowHeight;
+      const row = rows[index];
+      return row?.getIsExpanded() ? rowHeight + expandedRowHeight : rowHeight;
+    },
+    [rows, rowHeight, expandedRowHeight, enableRowExpansion]
+  );
+  const virtualizer = reactVirtual.useVirtualizer({
+    count: rows.length,
+    getScrollElement: () => containerRef.current,
+    estimateSize,
+    overscan
+  });
+  const virtualItems = virtualizer.getVirtualItems();
+  const totalSize = virtualizer.getTotalSize();
+  const handleScroll = react.useCallback(() => {
+    if (!onScrollToBottom || !containerRef.current) return;
+    const { scrollTop, scrollHeight, clientHeight } = containerRef.current;
+    const distanceFromBottom = scrollHeight - scrollTop - clientHeight;
+    if (distanceFromBottom < scrollBottomThreshold) {
+      onScrollToBottom();
+    }
+  }, [onScrollToBottom, scrollBottomThreshold]);
+  const reorderColumn = react.useCallback(
+    (draggedColumnId, targetColumnId) => {
+      const newOrder = [...columnOrderState];
+      const draggedIndex = newOrder.indexOf(draggedColumnId);
+      const targetIndex = newOrder.indexOf(targetColumnId);
+      if (draggedIndex === -1 || targetIndex === -1) return;
+      newOrder.splice(draggedIndex, 1);
+      newOrder.splice(targetIndex, 0, draggedColumnId);
+      handleColumnOrderChange(newOrder);
+    },
+    [columnOrderState, handleColumnOrderChange]
+  );
+  const setFocusedRow = react.useCallback(
+    (index) => {
+      const clampedIndex = Math.max(-1, Math.min(index, rows.length - 1));
+      if (onFocusedRowChange) {
+        onFocusedRowChange(clampedIndex);
+      } else {
+        setInternalFocusedRowIndex(clampedIndex);
+      }
+      if (clampedIndex >= 0) {
+        virtualizer.scrollToIndex(clampedIndex, { align: "auto" });
+      }
+    },
+    [rows.length, onFocusedRowChange, virtualizer]
+  );
+  const handleKeyDown = react.useCallback(
+    (e) => {
+      if (!enableKeyboardNavigation) return;
+      const currentIndex = focusedRowIndex;
+      switch (e.key) {
+        case "ArrowDown":
+          e.preventDefault();
+          setFocusedRow(currentIndex + 1);
+          break;
+        case "ArrowUp":
+          e.preventDefault();
+          setFocusedRow(currentIndex - 1);
+          break;
+        case "Home":
+          e.preventDefault();
+          setFocusedRow(0);
+          break;
+        case "End":
+          e.preventDefault();
+          setFocusedRow(rows.length - 1);
+          break;
+        case "Enter":
+          if (currentIndex >= 0 && enableRowExpansion) {
+            e.preventDefault();
+            const row = rows[currentIndex];
+            if (row?.getCanExpand()) {
+              row.toggleExpanded();
+            }
+          }
+          break;
+        case " ":
+          if (currentIndex >= 0 && enableRowSelection) {
+            e.preventDefault();
+            const row = rows[currentIndex];
+            row?.toggleSelected();
+          }
+          break;
+      }
+    },
+    [
+      enableKeyboardNavigation,
+      focusedRowIndex,
+      rows,
+      enableRowExpansion,
+      enableRowSelection,
+      setFocusedRow
+    ]
+  );
+  return {
+    table,
+    rows,
+    virtualizer,
+    virtualItems,
+    totalSize,
+    containerRef,
+    handleScroll,
+    handleKeyDown,
+    reorderColumn,
+    setFocusedRow,
+    // Expose state for consumers
+    rowSelection: rowSelectionState,
+    sorting: sortingState,
+    expanded: expandedState,
+    columnSizing: columnSizingState,
+    columnOrder: columnOrderState,
+    focusedRowIndex
+  };
+}
+var DEFAULT_HEIGHT = 400;
+function VirtualTable(props) {
+  const {
+    height = DEFAULT_HEIGHT,
+    stickyHeader = true,
+    renderExpandedRow,
+    className,
+    style,
+    ...tableOptions
+  } = props;
+  const {
+    rows,
+    virtualizer,
+    virtualItems,
+    totalSize,
+    containerRef,
+    handleScroll,
+    handleKeyDown,
+    table,
+    reorderColumn,
+    setFocusedRow,
+    focusedRowIndex
+  } = useVirtualTable(tableOptions);
+  const headerGroups = table.getHeaderGroups();
+  const enableRowExpansion = tableOptions.enableRowExpansion;
+  const enableColumnResizing = tableOptions.enableColumnResizing;
+  const enableColumnReordering = tableOptions.enableColumnReordering;
+  const enableKeyboardNavigation = tableOptions.enableKeyboardNavigation;
+  const [draggedColumnId, setDraggedColumnId] = react.useState(null);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      ref: containerRef,
+      className,
+      tabIndex: enableKeyboardNavigation ? 0 : void 0,
+      style: {
+        height,
+        overflow: "auto",
+        position: "relative",
+        outline: "none",
+        ...style
+      },
+      onScroll: handleScroll,
+      onKeyDown: enableKeyboardNavigation ? handleKeyDown : void 0,
+      children: /* @__PURE__ */ jsxRuntime.jsxs(
+        "table",
+        {
+          style: {
+            display: "grid",
+            width: "100%"
+          },
+          children: [
+            /* @__PURE__ */ jsxRuntime.jsx(
+              "thead",
+              {
+                style: {
+                  display: "grid",
+                  position: stickyHeader ? "sticky" : "relative",
+                  top: 0,
+                  zIndex: 1
+                },
+                children: headerGroups.map((headerGroup) => /* @__PURE__ */ jsxRuntime.jsx(
+                  "tr",
+                  {
+                    style: {
+                      display: "flex",
+                      width: "100%"
+                    },
+                    children: headerGroup.headers.map((header) => /* @__PURE__ */ jsxRuntime.jsxs(
+                      "th",
+                      {
+                        draggable: enableColumnReordering && !header.isPlaceholder,
+                        "data-dragging": draggedColumnId === header.column.id || void 0,
+                        onDragStart: enableColumnReordering ? (e) => {
+                          setDraggedColumnId(header.column.id);
+                          e.dataTransfer.effectAllowed = "move";
+                        } : void 0,
+                        onDragOver: enableColumnReordering ? (e) => {
+                          e.preventDefault();
+                          e.dataTransfer.dropEffect = "move";
+                        } : void 0,
+                        onDrop: enableColumnReordering ? (e) => {
+                          e.preventDefault();
+                          if (draggedColumnId && draggedColumnId !== header.column.id) {
+                            reorderColumn(draggedColumnId, header.column.id);
+                          }
+                        } : void 0,
+                        onDragEnd: enableColumnReordering ? () => setDraggedColumnId(null) : void 0,
+                        style: {
+                          flex: `0 0 ${header.getSize()}px`,
+                          cursor: enableColumnReordering ? "grab" : header.column.getCanSort() ? "pointer" : "default",
+                          position: "relative",
+                          opacity: draggedColumnId === header.column.id ? 0.5 : 1
+                        },
+                        onClick: !enableColumnReordering ? header.column.getToggleSortingHandler() : void 0,
+                        children: [
+                          header.isPlaceholder ? null : reactTable.flexRender(header.column.columnDef.header, header.getContext()),
+                          header.column.getIsSorted() === "asc" && " \u2191",
+                          header.column.getIsSorted() === "desc" && " \u2193",
+                          enableColumnResizing && header.column.getCanResize() && /* @__PURE__ */ jsxRuntime.jsx(
+                            "div",
+                            {
+                              onMouseDown: header.getResizeHandler(),
+                              onTouchStart: header.getResizeHandler(),
+                              onClick: (e) => e.stopPropagation(),
+                              className: "virtual-table-resizer",
+                              "data-resizing": header.column.getIsResizing() || void 0,
+                              style: {
+                                position: "absolute",
+                                right: 0,
+                                top: 0,
+                                height: "100%",
+                                width: "5px",
+                                cursor: "col-resize",
+                                userSelect: "none",
+                                touchAction: "none",
+                                background: header.column.getIsResizing() ? "rgba(0, 0, 0, 0.5)" : "transparent"
+                              }
+                            }
+                          )
+                        ]
+                      },
+                      header.id
+                    ))
+                  },
+                  headerGroup.id
+                ))
+              }
+            ),
+            /* @__PURE__ */ jsxRuntime.jsx(
+              "tbody",
+              {
+                style: {
+                  display: "grid",
+                  height: `${totalSize}px`,
+                  position: "relative"
+                },
+                children: virtualItems.map((virtualRow) => {
+                  const row = rows[virtualRow.index];
+                  const isExpanded = row.getIsExpanded();
+                  const canExpand = enableRowExpansion && row.getCanExpand();
+                  const isFocused = enableKeyboardNavigation && virtualRow.index === focusedRowIndex;
+                  const handleRowClick = () => {
+                    if (enableKeyboardNavigation) {
+                      setFocusedRow(virtualRow.index);
+                    }
+                    if (canExpand) {
+                      row.toggleExpanded();
+                    }
+                  };
+                  return /* @__PURE__ */ jsxRuntime.jsxs(
+                    "tr",
+                    {
+                      "data-index": virtualRow.index,
+                      "data-expanded": isExpanded || void 0,
+                      "data-focused": isFocused || void 0,
+                      ref: (node) => virtualizer.measureElement(node),
+                      style: {
+                        display: "block",
+                        position: "absolute",
+                        transform: `translateY(${virtualRow.start}px)`,
+                        width: "100%",
+                        cursor: canExpand || enableKeyboardNavigation ? "pointer" : "default"
+                      },
+                      onClick: handleRowClick,
+                      children: [
+                        /* @__PURE__ */ jsxRuntime.jsx(
+                          "div",
+                          {
+                            style: {
+                              display: "flex",
+                              width: "100%"
+                            },
+                            children: row.getVisibleCells().map((cell) => /* @__PURE__ */ jsxRuntime.jsx(
+                              "td",
+                              {
+                                style: {
+                                  flex: `0 0 ${cell.column.getSize()}px`
+                                },
+                                children: reactTable.flexRender(cell.column.columnDef.cell, cell.getContext())
+                              },
+                              cell.id
+                            ))
+                          }
+                        ),
+                        isExpanded && renderExpandedRow && /* @__PURE__ */ jsxRuntime.jsx("div", { onClick: (e) => e.stopPropagation(), style: { width: "100%" }, children: renderExpandedRow(row) })
+                      ]
+                    },
+                    row.id
+                  );
+                })
+              }
+            )
+          ]
+        }
+      )
+    }
+  );
+}
+
+Object.defineProperty(exports, "createColumnHelper", {
+  enumerable: true,
+  get: function () { return reactTable.createColumnHelper; }
+});
+exports.VirtualTable = VirtualTable;
+exports.useVirtualTable = useVirtualTable;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map