113 lines
3.6 KiB
Markdown
113 lines
3.6 KiB
Markdown
# OpenSpec Change: enterprise-react-timeline
|
|
|
|
- **Change ID**: enterprise-react-timeline
|
|
- **Package**: `@suaveplan/react-timeline`
|
|
- **Category**: react
|
|
- **Target path**: `react/ui/react-timeline`
|
|
- **Status**: PROPOSED
|
|
- **Date**: 2026-04-24
|
|
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/react-timeline.md`
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
Deliver `@suaveplan/react-timeline` on genesis from scratch at enterprise quality. A hybrid DOM+Canvas React timeline library with three view modes: `Timeline` (horizontal scrolling), `Gantt` (dependency arrows), and `Calendar` (day/week/month grid). Ships building-block primitives, a headless layout engine, `TimelineProvider`, seven headless hooks, Canvas renderers, and time-math utilities. TypeScript generics on `TMeta` let events carry arbitrary metadata. Genesis adds `@suaveplan/react-virtual` integration for large event sets, `@suaveplan/error`-backed errors, OTel instrumentation, hook playground stories, and Playwright visual-regression snapshots.
|
|
|
|
---
|
|
|
|
## Current-state audit (genesis)
|
|
|
|
Package does not exist on genesis — fresh build.
|
|
|
|
---
|
|
|
|
## Available workspace deps on genesis
|
|
|
|
| Package | Role |
|
|
|---|---|
|
|
| `@suaveplan/error` (`workspace:^`) | `TimelineError` |
|
|
| `@suaveplan/types` (`workspace:^`) | Shared types |
|
|
| `@suaveplan/react-translate` (`workspace:^`) | i18n |
|
|
| `@suaveplan/react-virtual` (`workspace:^`) | Virtual row rendering for large event sets |
|
|
| `zod` (`catalog:forms`) | Config schemas |
|
|
| `@opentelemetry/api` (`catalog:observability`) | Span events |
|
|
|
|
External: `clsx catalog:ui`, `tailwind-merge catalog:ui`, `tslib catalog:build`. React 18 peer.
|
|
|
|
---
|
|
|
|
## Preserved public API surface
|
|
|
|
### Components
|
|
|
|
`Timeline<TMeta>`, `Gantt<TMeta>`, `Calendar<TMeta>`, `EventBar`, `GridLines`, `Marker`, `TimeRuler`, `TrackRow`, `TimelineTooltip`, `DependencyArrow`
|
|
|
|
### Context
|
|
|
|
`TimelineProvider`, `useTimelineContext`
|
|
|
|
### Engine
|
|
|
|
`computeLayout`
|
|
|
|
### Hooks
|
|
|
|
`useTimeline`, `useDrag`, `usePan`, `useScale`, `useSelection`, `useVirtual`, `useZoom`
|
|
|
|
### Canvas renderers
|
|
|
|
`drawGridLines`, `drawTrackLines`, `setupCanvas`, `drawEvents`, `drawDependencyArrows`
|
|
|
|
### Time utilities
|
|
|
|
`addTime`, `clampDate`, `dateToPixel`, `diffMs`, `generateTicks`, `pixelToDate`, `snapToGrid`
|
|
|
|
### Types
|
|
|
|
Full `TMeta`-generic type set including `TimelineEvent`, `TimelineTrack`, `TimeScaleConfig`, `LayoutResult`, `DragState`, `SelectionState`.
|
|
|
|
---
|
|
|
|
## New additions for genesis
|
|
|
|
1. **`@suaveplan/react-virtual` integration** — `useVirtual` hook delegates to `@suaveplan/react-virtual` `useVirtualList` when event count > 500.
|
|
2. **Timezone-aware `TimeScaleConfig`** — optional `timeZone: string` field; all pixel math uses UTC offsets.
|
|
3. **Collision avoidance story** — `Gantt` stories include overlapping events demonstrating lane computation.
|
|
4. **Hook playground stories** — one story per hook showing its isolated state.
|
|
5. **Playwright visual-regression snapshots** — Canvas rendering verified via screenshot diffing.
|
|
|
|
---
|
|
|
|
## File layout
|
|
|
|
```text
|
|
react/ui/react-timeline/
|
|
package.json
|
|
tsconfig.json
|
|
vitest.config.ts
|
|
src/
|
|
index.ts
|
|
core/
|
|
context/ (tsx + types + md + test + index)
|
|
engine/ (ts + types + md + test + index)
|
|
types/ (ts + md)
|
|
components/
|
|
timeline/ gantt/ calendar/
|
|
event-bar/ grid-lines/ marker/ time-ruler/
|
|
track-row/ tooltip/ dependency-arrow/
|
|
hooks/
|
|
use-timeline/ use-drag/ use-pan/ use-scale/
|
|
use-selection/ use-virtual/ use-zoom/
|
|
renderers/
|
|
canvas-renderer/ event-renderer/
|
|
utils/
|
|
cn/ time-utils/ layout/ scale-config/
|
|
styles/
|
|
timeline.css
|
|
tests/
|
|
integration.test.tsx
|
|
e2e/
|
|
timeline.spec.ts
|
|
```
|