virtualized-ui 0.1.0 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "virtualized-ui",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Headless virtualized table and select components for React",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -22,6 +22,13 @@
     "dist"
   ],
   "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
   "keywords": [
     "react",
     "virtual",
@@ -63,12 +70,5 @@
     "tsup": "^8.3.0",
     "typescript": "^5.6.0",
     "vitest": "^4.0.18"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Greg Levine-Rozenvayn
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.