@aiquants/virtualscroll 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 fehde-k
+
+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.

package/README.md

@@ -0,0 +1,192 @@
+# @aiquants/virtualscroll
+
+High-performance virtual scrolling component for React with variable item heights using Fenwick Tree optimization.
+
+## Features
+
+- ⚡ **High Performance**: Optimized for thousands of items with O(log n) operations
+- 📐 **Variable Heights**: Support for items with different heights
+<!-- - 🌲 **Fenwick Tree**: Advanced data structure for efficient prefix sum calculations -->
+- 🎯 **Precise Scrolling**: Accurate scroll positioning and smooth navigation
+<!-- - 🔄 **LRU Caching**: Built-in cache for optimal memory usage -->
+- 📱 **Touch Support**: Full support for touch devices
+- 🎨 **Customizable**: Flexible styling and theming options
+- 🔧 **TypeScript**: Full TypeScript support with comprehensive type definitions
+
+## Installation
+
+```bash
+npm install @aiquants/virtualscroll
+# or
+yarn add @aiquants/virtualscroll
+# or
+pnpm add @aiquants/virtualscroll
+```
+
+## Basic Usage
+
+```tsx
+import { VirtualScroll } from '@aiquants/virtualscroll'
+import { useCallback } from 'react'
+
+type Item = {
+  id: number
+  text: string
+  height: number
+}
+
+const items: Item[] = Array.from({ length: 10000 }, (_, i) => ({
+  id: i,
+  text: `Item ${i}`,
+  height: Math.floor(Math.random() * 50) + 30, // Random height between 30-80px
+}))
+
+function App() {
+  const getItem = useCallback((index: number) => items[index], [])
+  const getItemHeight = useCallback((index: number) => items[index].height, [])
+
+  return (
+    <div style={{ height: '400px', width: '100%' }}>
+      <VirtualScroll
+        itemCount={items.length}
+        getItem={getItem}
+        getItemHeight={getItemHeight}
+        viewportSize={400}
+        overscanCount={5}
+        className="border border-gray-300"
+      >
+        {(item, index) => (
+          <div
+            key={item.id}
+            style={{
+              height: item.height,
+              padding: '8px',
+              borderBottom: '1px solid #eee',
+              display: 'flex',
+              alignItems: 'center',
+            }}
+          >
+            <span>#{index}: {item.text}</span>
+          </div>
+        )}
+      </VirtualScroll>
+    </div>
+  )
+}
+```
+
+## API Reference
+
+### VirtualScroll Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `children` | `(item: T, index: number) => ReactNode` | ✅ | Render function for items |
+| `itemCount` | `number` | ✅ | Total number of items |
+| `getItem` | `(index: number) => T` | ✅ | Function to get item at index |
+| `getItemHeight` | `(index: number) => number` | ✅ | Function to get item height |
+| `viewportSize` | `number` | ✅ | Height of the visible area |
+| `overscanCount` | `number` | ❌ | Number of items to render outside viewport (default: 5) |
+| `className` | `string` | ❌ | CSS class name |
+| `onScroll` | `(position: number, totalHeight: number) => void` | ❌ | Scroll event handler |
+| `onRangeChange` | `(start: number, end: number, visibleStart: number, visibleEnd: number, position: number, totalHeight: number) => void` | ❌ | Range change handler |
+| `background` | `ReactNode` | ❌ | Background element |
+| `initialScrollIndex` | `number` | ❌ | Initial scroll index |
+| `initialScrollOffset` | `number` | ❌ | Initial scroll offset |
+
+### VirtualScrollHandle Methods
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `scrollTo` | `(position: number) => void` | Scroll to specific position |
+| `scrollToIndex` | `(index: number) => void` | Scroll to specific item index |
+| `getScrollPosition` | `() => number` | Get current scroll position |
+<!-- | `getContentSize` | `() => number` | Get total content size | -->
+<!-- | `getViewportSize` | `() => number` | Get viewport size | -->
+<!-- | `getFenwickTreeTotalHeight` | `() => number` | Get Fenwick tree total height | -->
+<!-- | `getFenwickSize` | `() => number` | Get Fenwick tree size | -->
+
+## Advanced Usage
+
+### With Ref and Scroll Control
+
+```tsx
+import { VirtualScroll, VirtualScrollHandle } from '@aiquants/virtualscroll'
+import { useRef } from 'react'
+
+function AdvancedExample() {
+  const virtualScrollRef = useRef<VirtualScrollHandle>(null)
+
+  const scrollToTop = () => {
+    virtualScrollRef.current?.scrollTo(0)
+  }
+
+  const scrollToIndex = (index: number) => {
+    virtualScrollRef.current?.scrollToIndex(index)
+  }
+
+  return (
+    <div>
+      <div>
+        <button onClick={scrollToTop}>Scroll to Top</button>
+        <button onClick={() => scrollToIndex(500)}>Scroll to Item 500</button>
+      </div>
+      <VirtualScroll
+        ref={virtualScrollRef}
+        itemCount={100000}
+        getItem={getItem}
+        getItemHeight={getItemHeight}
+        viewportSize={400}
+        onRangeChange={(start, end) => {
+          console.log(`Visible range: ${start} - ${end}`)
+        }}
+      >
+        {(item, index) => <ItemComponent item={item} index={index} />}
+      </VirtualScroll>
+    </div>
+  )
+}
+```
+
+### Custom Scrollbar Styling
+
+```tsx
+<VirtualScroll
+  itemCount={items.length}
+  getItem={getItem}
+  getItemHeight={getItemHeight}
+  viewportSize={400}
+  className="custom-virtual-scroll"
+>
+  {(item, index) => <ItemComponent item={item} index={index} />}
+</VirtualScroll>
+
+<style>
+.custom-virtual-scroll .scrollbar {
+  background-color: #f0f0f0;
+}
+
+.custom-virtual-scroll .scrollbar-thumb {
+  background-color: #007acc;
+  border-radius: 4px;
+}
+</style>
+```
+
+## Performance Tips
+
+1. **Memoize callback functions**: Use `useCallback` for `getItem` and `getItemHeight`
+2. **Optimize item rendering**: Memoize item components when possible
+3. **Adjust overscan count**: Balance between smooth scrolling and memory usage
+4. **Consider item height consistency**: More consistent heights provide better performance
+
+## Browser Support
+
+- Chrome 88+
+- Firefox 87+
+- Safari 14+
+- Edge 88+
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { spawn } from "child_process";
+import path from "path";
+import { fileURLToPath } from "url";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const args = process.argv.slice(2);
+if (args[0] === "demo") {
+  console.log("Starting demo server...");
+  const demoPath = path.join(__dirname, "..", "demo");
+  const child = spawn("pnpm", ["run", "dev"], {
+    cwd: demoPath,
+    stdio: "inherit",
+    shell: process.platform === "win32"
+  });
+  child.on("close", (code) => {
+    if (code !== 0) {
+      console.error(`Demo server process exited with code ${code}`);
+    }
+  });
+  child.on("error", (err) => {
+    console.error("Failed to start demo server:", err);
+  });
+} else {
+  console.log(`Unknown command: ${args[0]}`);
+  console.log("Usage: npx @aiquants/virtualscroll demo");
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@aiquants/virtualscroll",
+  "version": "0.1.0",
+  "description": "High-performance virtual scrolling component for React with variable item heights",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "vite build && vite build --config vite.config.cli.ts",
+    "dev": "vite build --watch",
+    "demo:dev": "cd demo && pnpm run dev",
+    "demo:build": "cd demo && pnpm run build",
+    "demo:start": "cd demo && pnpm start",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest --coverage",
+    "lint": "biome check src",
+    "lint:fix": "biome check --write src",
+    "format": "biome format --write src",
+    "format:check": "biome format src",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run typecheck && npm run build",
+    "publish:patch": "npm version patch && npm publish",
+    "publish:minor": "npm version minor && npm publish",
+    "publish:major": "npm version major && npm publish"
+  },
+  "dependencies": {
+    "react": "^19.1.1",
+    "tailwind-merge": "^2.6.0"
+  },
+  "peerDependencies": {
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@testing-library/jest-dom": "^6.6.5",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.5.2",
+    "@types/react": "^19.1.11",
+    "@types/react-dom": "^19.1.8",
+    "@vitejs/plugin-react": "^5.0.1",
+    "autoprefixer": "^10.4.21",
+    "jsdom": "^26.0.0",
+    "postcss": "^8.5.6",
+    "react-dom": "^19.1.1",
+    "rimraf": "^6.0.1",
+    "tailwindcss": "^4.1.12",
+    "tailwindcss-animate": "^1.0.7",
+    "typescript": "^5.9.2",
+    "vite": "^7.1.3",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "react",
+    "virtual-scroll",
+    "virtual-scrolling",
+    "performance",
+    "large-list",
+    "typescript",
+    "fenwick-tree",
+    "variable-height"
+  ],
+  "author": "fehde-k",
+  "license": "MIT",
+  "bin": {
+    "virtualscroll": "./dist/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}