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

@suaveplan/react-virtual integration — useVirtual hook delegates to @suaveplan/react-virtual useVirtualList when event count > 500.
Timezone-aware TimeScaleConfig — optional timeZone: string field; all pixel math uses UTC offsets.
Collision avoidance story — Gantt stories include overlapping events demonstrating lane computation.
Hook playground stories — one story per hook showing its isolated state.
Playwright visual-regression snapshots — Canvas rendering verified via screenshot diffing.

File layout

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

3.6 KiB Raw Permalink Blame History