Initial Commit

openspec/changes/enterprise-react-virtual/proposal.md

@@ -0,0 +1,109 @@
+# OpenSpec Change: enterprise-react-virtual
+
+- **Change ID**: enterprise-react-virtual
+- **Package**: `@suaveplan/react-virtual`
+- **Category**: react
+- **Target path**: `react/ui/react-virtual`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-virtual.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/react-virtual` on genesis from scratch at enterprise quality. A TypeScript-first virtualization engine for React with a headless core (`virtual-engine`, `range-calculator`), React hooks (`useVirtualList`, `useVirtualGrid`, `useVirtualScroll`), and batteries-included components (`VirtualList`, `VirtualGrid`) with generic item types, dynamic sizing via `SizeCache`, overscan, scroll-direction-aware range calculation, `SharedResizeObserver` pooling, and scroll utilities. Zero workspace runtime deps — pure React + DOM.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `VirtualError` for invalid config |
+| `@suaveplan/types` (`workspace:^`) | Shared option types |
+| `zod` (`catalog:forms`) | Engine config schemas |
+
+External: `clsx catalog:ui`, `tailwind-merge catalog:ui`, `tslib catalog:build`. React 18 peer.
+
+---
+
+## Preserved public API surface
+
+### Components
+
+`VirtualList<T>`, `VirtualGrid<T>` — with handle refs (`VirtualListHandle`, `VirtualGridHandle`) and render-prop APIs.
+
+### Hooks
+
+`useVirtualList`, `useVirtualGrid`, `useVirtualScroll`
+
+### Engine
+
+`createVirtualEngine`, `calculateVirtualItems`, `buildVirtualItems`, `calculateVisibleRange`, `calculateScrollToOffset`, `createSizeCache`, `findIndexAtOffset`, `getItemOffset`, `getItemSize`, `setItemSize`, `getScrollDirection`, `getTotalSize`
+
+### Range calculator
+
+`calculateGridRange`, `calculateGridDimensions`, `buildGridCells`, `findAxisIndex`, `getAxisOffset`, `getAxisTotalSize`, `resolveSize`
+
+### Utilities
+
+`SharedResizeObserver`, `getSharedResizeObserver`, `measureElement`, `resetSharedResizeObserver`, `throttle`, `throttleWithRaf`, `getScrollOffset`, `clampScrollOffset`, `scrollTo`, `isNearEnd`
+
+### Types
+
+`ScrollAlignment`, `ScrollDirection`, `ScrollToIndexParams`, `SizeCache`, `SizeMode`, `VirtualEngineConfig`, `VirtualEngineResult`, `VirtualItem`, `VisibleRange`, `ThrottleOptions`, `ResizeCallback`
+
+---
+
+## New additions for genesis
+
+1. **`@suaveplan/error`-backed `VirtualError`** with codes `VIRTUAL_INVALID_CONFIG`, `VIRTUAL_SCROLL_FAILED`.
+2. **Zod `VirtualEngineConfigSchema`** for runtime validation of engine options.
+3. **Stories** — `VirtualList` and `VirtualGrid` each with `default`, `dynamic-sizes`, `large-dataset` (100k items), `playground`, `a11y` stories.
+4. **`prefers-reduced-motion` scroll behavior** — `scrollTo` respects `behavior: 'instant'` when reduced motion is detected.
+5. **OTel instrumentation** — `virtual.scroll` span event with `virtual.item_count` attribute.
+
+---
+
+## File layout
+
+```text
+react/ui/react-virtual/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    core/
+      virtual-engine/ (ts + types + md + test + index)
+      range-calculator/ (ts + types + md + test + index)
+    hooks/
+      use-virtual-list/ (ts + types + md + test + index)
+      use-virtual-grid/ (ts + types + md + test + index)
+      use-virtual-scroll/ (ts + types + md + test + index)
+    components/
+      virtual-list/ (tsx + types + md + test + stories + index)
+      virtual-grid/ (tsx + types + md + test + stories + index)
+    utils/
+      resize-observer/ (ts + md + test + index)
+      scroll-utils/ (ts + md + test + index)
+    styles/
+      virtual.css
+  tests/
+    integration.test.tsx
+  e2e/
+    virtual.spec.ts
+```
+
+---
+
+## Impact
+
+`@suaveplan/react-data-table` and `@suaveplan/react-timeline` depend on this package. Must be published before them.

openspec/changes/enterprise-react-virtual/tasks.md

@@ -0,0 +1,105 @@
+# Tasks: enterprise-react-virtual
+
+**Change ID**: enterprise-react-virtual
+**Package**: `@suaveplan/react-virtual`
+**Target path**: `react/ui/react-virtual`
+**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`
+
+---
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Scaffold
+
+- [ ] Create directory tree per proposal layout.
+- [ ] Write `package.json` at `0.1.0` with `"sideEffects": ["**/*.css"]`, exports map (top-level barrel + per-module subpaths: `./core/virtual-engine/virtual-engine`, `./core/range-calculator/range-calculator`, `./hooks/use-virtual-list/use-virtual-list`, `./hooks/use-virtual-grid/use-virtual-grid`, `./hooks/use-virtual-scroll/use-virtual-scroll`, `./components/virtual-list/virtual-list`, `./components/virtual-grid/virtual-grid`, `./utils/resize-observer/resize-observer`, `./utils/scroll-utils/scroll-utils`, `./styles/virtual.css`).
+- [ ] `dependencies`: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `clsx catalog:ui`, `tailwind-merge catalog:ui`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`, `tslib catalog:build`.
+- [ ] Write `tsconfig.json`, `vitest.config.ts`, scripts.
+
+---
+
+## 2. Error codes and types
+
+- [ ] Define `VirtualError` extending `SuaveplanError`; codes: `VIRTUAL_INVALID_CONFIG`, `VIRTUAL_SCROLL_FAILED`.
+- [ ] Define all public types: `VirtualEngineConfig`, `VirtualEngineResult`, `VirtualItem`, `VisibleRange`, `SizeCache`, `SizeMode`, `ScrollDirection`, `ScrollAlignment`, `ScrollToIndexParams`, `ThrottleOptions`, `ResizeCallback`, grid-axis types.
+- [ ] Write `VirtualEngineConfigSchema` Zod schema; validate in `createVirtualEngine`.
+
+---
+
+## 3. Core engine (`src/core/virtual-engine/`)
+
+- [ ] Implement `createVirtualEngine(config)` — validates config, initialises `SizeCache`, computes initial `VirtualEngineResult`.
+- [ ] Implement `calculateVirtualItems(engine, scrollOffset, containerSize)` — returns `VirtualItem[]` with `index`, `start`, `size`, `end`, `lane`. Handles overscan.
+- [ ] Implement `buildVirtualItems`, `calculateVisibleRange`, `calculateScrollToOffset`, `createSizeCache`, `findIndexAtOffset`, `getItemOffset`, `getItemSize`, `setItemSize`, `getScrollDirection`, `getTotalSize`.
+- [ ] Write `virtual-engine.test.ts` (≤500 lines): fixed size, dynamic size, overscan, scroll direction, scroll-to-index, size cache mutation. `{ timeout: 5000 }`.
+- [ ] Write `virtual-engine.md` (≥200 words).
+
+---
+
+## 4. Range calculator (`src/core/range-calculator/`)
+
+- [ ] Implement `calculateGridRange`, `calculateGridDimensions`, `buildGridCells`, `findAxisIndex`, `getAxisOffset`, `getAxisTotalSize`, `resolveSize` for 2D grid axis math (rows + columns with mixed fixed/dynamic sizes).
+- [ ] Write `range-calculator.test.ts`, `range-calculator.md`.
+
+---
+
+## 5. Hooks
+
+### `useVirtualList`
+
+- [ ] Wraps engine + `useRef` for container scroll; integrates `SharedResizeObserver` for container size; returns `virtualItems`, `totalSize`, `scrollToIndex`.
+- [ ] Write `use-virtual-list.test.ts`, `use-virtual-list.md`.
+
+### `useVirtualGrid`
+
+- [ ] 2D binding: row + column axis, `scrollToCell(row, col)`.
+- [ ] Write `use-virtual-grid.test.ts`, `use-virtual-grid.md`.
+
+### `useVirtualScroll`
+
+- [ ] Scroll-offset observer only — RAF throttled; returns `scrollOffset`, `scrollDirection`, `isNearEnd`.
+- [ ] Write `use-virtual-scroll.test.ts`, `use-virtual-scroll.md`.
+
+---
+
+## 6. Components
+
+### `VirtualList<T>`
+
+- [ ] Render-prop component wrapping `useVirtualList`. Forwards `VirtualListHandle` ref with `scrollToIndex`.
+- [ ] `prefers-reduced-motion` scroll behavior.
+- [ ] OTel `virtual.scroll` span event.
+- [ ] Write `virtual-list.test.tsx`, `virtual-list.stories.tsx` (default, dynamic-sizes, large-dataset 100k, playground, a11y), `virtual-list.md`.
+
+### `VirtualGrid<T>`
+
+- [ ] Render-prop component wrapping `useVirtualGrid`. Forwards `VirtualGridHandle`.
+- [ ] Write `virtual-grid.test.tsx`, `virtual-grid.stories.tsx`, `virtual-grid.md`.
+
+---
+
+## 7. Utilities
+
+- [ ] `src/utils/resize-observer/resize-observer.ts` — `SharedResizeObserver` pooling (one observer per root), `getSharedResizeObserver()`, `measureElement()`, `resetSharedResizeObserver()`. Write test + md.
+- [ ] `src/utils/scroll-utils/scroll-utils.ts` — `throttle`, `throttleWithRaf`, `getScrollOffset`, `clampScrollOffset`, `scrollTo` (respects `prefers-reduced-motion`), `isNearEnd`. Write test + md.
+- [ ] `src/styles/virtual.css` — positioning helpers (absolute container, transform translate3d items).
+
+---
+
+## 8. Integration and E2E
+
+- [ ] `tests/integration.test.tsx` — `VirtualList` with 10k items: scroll offset updates virtual items, `scrollToIndex` snaps.
+- [ ] `e2e/virtual.spec.ts` — Playwright: render 100k-row list, verify only ~20 DOM nodes, scroll to bottom, `scrollToIndex(5000)` lands at correct position.
+
+---
+
+## 9. Verify and publish
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-virtual` — green.
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-virtual` — 100%.
+- [ ] `bun scripts/publish.ts --package @suaveplan/react-virtual`.
+- [ ] Archive change folder.