feat(gantt): feature parity Phases 1-5 — links, time scales, hierarchy, interactions, virtualization (#1672)

Author: baozhoutao

.changeset/gantt-dependency-links.md

@@ -0,0 +1,13 @@
+---
+"@object-ui/plugin-gantt": minor
+---
+
+Gantt feature parity, Phases 1–5: dependency links, real time scales, hierarchy, interaction polish, and virtualization.
+
+- **Dependency links** — `task.dependencies` renders as orthogonal arrows in an SVG overlay, with all four MS-Project link types (`fs`/`ss`/`ff`/`sf`) via the object form `{ id, type }`. Arrows follow bars live during drag/resize; hovering a bar highlights its links. `normalizeDependencies` (exported) accepts CSV strings, id arrays, and object arrays with id/type aliases. New dependencies can be created by dragging from a bar's link dot onto another bar (`onDependencyCreate`).
+- **Real time scales** — day/week/month/quarter modes with a two-row header (group row + unit row), weekend tinting, zoom in/out, and a jump-to-today button.
+- **Hierarchy** — `parent` builds a tree: collapsible summary rows with bracket-style summary bars aggregated from descendants, milestone diamonds, indent guides, and `aria-expanded`/`role="treeitem"` semantics. Dragging a summary bar moves its whole subtree by the same offset (live preview + one `onTaskUpdate` per task); the summary's displayed range rolls up from children, so moving a child past the parent's edge stretches the parent automatically.
+- **Interaction polish** — progress drag handle, hover tooltip, context menu (including delete), keyboard navigation/editing, inline title editing, and row drag-reorder (`onTaskReorder`).
+- **Scale** — virtualized rows *and* columns (spacer-based windowing; only the visible window is in the DOM, verified: 5,000 tasks render in ~27 ms with 26 rows in the DOM), a fullscreen toggle, and custom timeline `markers` (`{ date, label?, color? }`).
+
+Colors that the prebuilt components stylesheet doesn't emit utilities for use theme CSS variables inline, so everything renders correctly in consuming apps.

.claude/launch.json

@@ -6,6 +6,12 @@
       "runtimeExecutable": "pnpm",
       "runtimeArgs": ["--filter", "@object-ui/console", "dev"],
       "port": 5180
+    },
+    {
+      "name": "gantt-demo",
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["--dir", "packages/plugin-gantt", "exec", "vite", "demo", "--port", "5199"],
+      "port": 5199
     }
   ]
 }

ROADMAP.md

@@ -1432,6 +1432,13 @@ Plugin architecture refactoring to support true modular development, plugin isol
 - [ ] Plugin publish/validate tooling (spec v3.0.9 `PluginBuildOptions`, `PluginPublishOptions`)
 - [ ] Cross-repo plugin loading from npm packages
 
+### P2.11 Gantt Feature Parity (vs SVAR React Gantt)
+
+> **Status:** Planned. Gap analysis done (June 2026) against [SVAR React Gantt](https://github.com/svar-widgets/react-gantt).
+> Full phased task list lives in [`packages/plugin-gantt/ROADMAP.md`](packages/plugin-gantt/ROADMAP.md):
+> Phase 1 dependency links → Phase 2 real time scales → Phase 3 hierarchy/milestones →
+> Phase 4 interaction polish → Phase 5 virtualization → Phase 6 advanced (critical path, baselines, auto-scheduling).
+
 ---
 
 ## 🔮 P3 — Future Vision (Deferred)

packages/plugin-gantt/README.md

@@ -227,11 +227,20 @@ const schema = {
 
 ## View Modes
 
-The Gantt chart supports different time scales:
+The Gantt chart renders one timeline column per unit of the active scale:
 
-- **day** - Day-by-day view
-- **week** - Week-by-week view
-- **month** - Month-by-month view
+- **day** - one column per day (weekday + weekend shading)
+- **week** - one column per week (starting Monday)
+- **month** - one column per calendar month
+- **quarter** - one column per quarter (Q1–Q4)
+
+A two-row header shows the grouping above the units (months above days/weeks,
+years above months/quarters). The toolbar's segmented control switches scales
+interactively (`onViewChange` notifies you), and the zoom buttons step the
+column width — falling through to the next coarser/finer scale at the bounds.
+Drag snapping follows the active scale: bars snap to days in day view, weeks
+in week view, and whole calendar months/quarters (duration preserved) in the
+coarse views.
 
 ```typescript
 const schema = {
@@ -241,6 +250,79 @@ const schema = {
 };
 ```
 
+## Task Hierarchy, Summaries & Milestones
+
+Give a task a `parent` (or configure `parentField` on the data-source schema)
+to build a tree: child rows indent under their parent with expand/collapse
+chevrons in the task list. Any task with children renders as a **summary**
+bracket spanning its children's combined date range, with progress rolled up
+as the duration-weighted average of its descendants — summaries are read-only,
+their children drive them.
+
+Zero-duration tasks (`end <= start`) — or tasks whose `type` is
+`'milestone'` (via `typeField`: values like `milestone`, `summary`,
+`project`, `group` are recognized) — render as diamond markers. Milestones
+can be dragged to move but not resized; dependency arrows anchor at the
+diamond center.
+
+```typescript
+const tasks = [
+  { id: 'phase1', title: 'Phase 1', start: '…', end: '…', progress: 0 },        // summary (has children)
+  { id: 't1', title: 'Design', parent: 'phase1', start: '…', end: '…', progress: 80 },
+  { id: 't2', title: 'Build', parent: 'phase1', start: '…', end: '…', progress: 20 },
+  { id: 'launch', title: 'Launch', type: 'milestone', start: '2024-07-01', end: '2024-07-01', progress: 0 },
+];
+```
+
+## Interactions
+
+Beyond drag-to-reschedule, the timeline supports:
+
+- **Progress drag** — hover a bar and drag the round grip at the progress
+  boundary; the fill follows live and `onTaskUpdate(task, { progress })`
+  commits on release (snapped to whole percent, clamped 0–100).
+- **Hover tooltip** — bars, milestones and summaries show a tooltip with
+  title, date range, duration and progress.
+- **Context menu** — right-click a bar or list row for View details / Edit
+  inline / Delete (items appear only when the matching callback is wired).
+- **Keyboard navigation** — the chart body is focusable: ↑/↓ move the row
+  selection, Enter opens the task, Delete deletes it, ←/→ collapse/expand
+  summary rows. Rows carry `treeitem` roles with `aria-level`/`aria-selected`.
+- **Drag-to-create dependency** — drag the connector dot on a bar's right
+  edge onto another bar; a dashed rubber band previews the link and
+  `onDependencyCreate(source, target, 'fs')` fires on drop. Through
+  `ObjectGantt` the new predecessor is appended to the record's
+  `dependenciesField`, preserving the field's original shape (CSV or array).
+- **Row drag-to-reorder** — pass `onTaskReorder(task, before)` to enable
+  HTML5 drag reordering in the task list (sibling-scoped; persistence is up
+  to the host, e.g. via a sort field).
+
+## Scale & Performance
+
+Rows and timeline columns are **virtualized**: only what is in (or near) the
+viewport renders, so the chart stays responsive with thousands of tasks and
+multi-year day-scale ranges. No configuration needed — windowing follows the
+scroll position automatically, and dependency arrows keep their absolute
+positions while scrolling.
+
+Two more chrome features ship with it:
+
+- **Fullscreen** — the expand button in the toolbar puts the whole chart into
+  native fullscreen (and back).
+- **Custom markers** — vertical reference lines beyond the Today marker:
+
+```tsx
+<GanttView
+  tasks={tasks}
+  markers={[
+    { date: '2026-07-01', label: 'Code freeze', color: '#ef4444' },
+    { date: '2026-07-15', label: 'Release' }, // defaults to the primary theme color
+  ]}
+/>
+```
+
+Through the schema, pass the same array as `markers` on the gantt node.
+
 ## Task Dependencies
 
 Link tasks to show dependencies:
@@ -273,6 +355,28 @@ const tasks = [
 ];
 ```
 
+Dependencies render as arrows from the predecessor bar to the dependent bar.
+Arrows follow bars live while dragging, and hovering a bar highlights its links.
+
+### Link Types
+
+Each dependency entry is either a predecessor id (`'task-1'`) or an object with
+an explicit link type:
+
+```typescript
+dependencies: [
+  { id: 'task-1', type: 'fs' },  // finish-to-start (default)
+  { id: 'task-2', type: 'ss' },  // start-to-start
+  { id: 'task-3', type: 'ff' },  // finish-to-finish
+  { id: 'task-4', type: 'sf' },  // start-to-finish
+]
+```
+
+When records come from a data source (`dependenciesField`), the field value may
+be a CSV string (`"task1, task2"`), an array of ids, or an array of objects —
+`task`/`target`/`_id` are accepted as id aliases, and long-form type names like
+`"finish_to_start"` / `"end-to-end"` map onto `fs`/`ss`/`ff`/`sf`.
+
 ## Integration with Data Sources
 
 ```typescript

packages/plugin-gantt/ROADMAP.md

@@ -0,0 +1,65 @@
+# Gantt Plugin Roadmap — Feature Parity (vs SVAR React Gantt)
+
+> **Status:** Planned. Gap analysis done (June 2026) against [SVAR React Gantt](https://github.com/svar-widgets/react-gantt).
+> Current `@object-ui/plugin-gantt` is a draggable day-scale bar chart; it lacks the project-management
+> semantics (dependencies, hierarchy, milestones, real time scales) that define a Gantt chart.
+> SVAR core is GPLv3 — feature reference only, no code reuse (we are MIT).
+>
+> Tracked from the main [ROADMAP.md](../../ROADMAP.md) § P2.11.
+
+## What we already have
+
+Bar drag/resize with day snapping + optimistic persistence, pinch-to-zoom, responsive/mobile pass,
+Today marker + jump-to-today, weekend highlighting, semantic color fallback, i18n, inline edit
+(double-click), record detail drawer on click, delete confirmation.
+
+## Phase 1 — Dependency Links Rendering (highest ROI) ✅
+
+- [x] Render dependency arrows as an SVG overlay in `GanttView` (orthogonal elbow routing, arrowhead markers, backward-link detour)
+- [x] Support the 4 link types: finish-to-start (default), start-to-start, finish-to-finish, start-to-finish — per-dependency `{ id, type }` object form; `normalizeDependencies` accepts CSV strings, id arrays, object arrays with id/type aliases
+- [x] Recompute arrow paths live during bar drag/resize preview
+- [x] Highlight a task's links on hover (and while dragging)
+- [x] Tests: link parsing (string id, array, `{id, type}` object), path anchors per type, hover highlight, drag re-render, backward links (8 new GanttView tests + 6 normalizeDependencies tests)
+
+## Phase 2 — Real Time Scales (resurrect `viewMode`) ✅
+
+- [x] Implement day/week/month/quarter column generation in `timeColumns` — calendar-true column widths over one linear ms→px mapping (`pxPerDay = columnWidth / nominalDays`), so bars, grid, links and the Today marker stay aligned in every mode
+- [x] Two-row scale header: month groups over day/week units, year groups over month/quarter units
+- [x] Restore the view-mode segmented control in the toolbar; zoom buttons fall through to the next coarser/finer granularity at min/max column width
+- [x] Drag snapping respects active granularity (day/week columns, calendar-clamped month/quarter shifts preserving duration on move)
+- [x] Tests: column generation per mode, header groups/labels, bar geometry per granularity, week + month snap behavior (8 new tests)
+
+## Phase 3 — Task Hierarchy & Types ✅
+
+- [x] `parentField` (+ `task.parent`) → task tree, depth-indented rows, expand/collapse chevrons in the task list; orphans and parent cycles surface as roots instead of dropping rows
+- [x] Summary (parent) bars: bracket-style slim bar with end caps spanning the children rollup range; read-only (children drive it)
+- [x] Milestone type: diamond marker via `typeField`/`task.type` or the `end <= start` heuristic; movable, not resizable; links anchor at the diamond center
+- [x] Auto-rollup: summary dates = min/max of descendants, progress = duration-weighted child progress (client-side, display via `data-progress`)
+- [x] Tests: tree building, orphan + cycle handling, collapse hides rows/links, summary range/progress math, milestone rendering + link anchors (9 new tests)
+
+## Phase 4 — Interaction Polish ✅
+
+- [x] Progress drag handle on the bar — grip at the progress boundary, 1% snapping, live fill preview, commits `onTaskUpdate({progress})`
+- [x] Rich hover tooltip (title, dates, duration, progress) on task bars, milestones and summary brackets
+- [x] Context menu on bar/row — View details / Edit inline / Delete; closes on outside click or Escape (add-dependency is covered by drag-to-create)
+- [x] Keyboard support: focusable gantt body, ArrowUp/Down row navigation, Enter to open, Delete to delete, ArrowLeft/Right collapse/expand; `tree`/`treeitem` roles with aria-level/-selected/-expanded
+- [x] Drag-to-create dependency — connector dot on bar edge, dashed rubber band, drop-target highlight; fires `onDependencyCreate(source, target, 'fs')`, `ObjectGantt` appends to the dependencies field preserving its shape (CSV ↔ array)
+- [x] Row drag-to-reorder — HTML5 drag in the task list, sibling-scoped, fires `onTaskReorder(task, before)` for the host to persist (sort-field wiring is host-specific)
+- [x] Tests: progress drag + clamping, tooltip, context menu routing/Escape, keyboard nav + collapse, link create + empty-space release, reorder + cross-parent guard (11 new tests)
+
+## Phase 5 — Scale & Performance ✅
+
+- [x] Virtualized row rendering (windowing) for both task list and timeline — spacer-div windowing over flattened rows (≈viewport + 6-row overscan rendered), driven by scroll position + ResizeObserver-measured viewport; dependency-link SVG keeps absolute row coordinates and skips links fully outside the window
+- [x] Virtualized timeline columns for multi-year ranges — prefix-sum column offsets + binary-free linear `visibleRange` scan; header groups, header units and the background grid render as absolutely-positioned cells inside the ±240px overscan window
+- [x] Fullscreen mode toggle — toolbar button drives the native Fullscreen API on the Gantt container, icon/aria reflect `fullscreenchange`
+- [x] Custom vertical markers — `markers` prop (`{date, label?, color?}`), rendered like the Today line on the shared ms→px mapping; out-of-range/invalid dates dropped; passed through `ObjectGantt` via `schema.markers`
+- [x] Tests: 1000-row windowing + spacer heights, scroll window shift, windowed link anchoring, multi-year column windowing, fullscreen enter/exit, marker mapping/fallback color (8 new tests)
+
+## Phase 6 — Advanced (SVAR PRO territory, differentiators)
+
+- [ ] Critical path computation + slack visualization
+- [ ] Baselines (planned vs actual bars)
+- [ ] Auto-scheduling: dependency-driven date shifting (forward, finish-to-start first)
+- [ ] Working calendar (skip weekends/holidays in duration math)
+- [ ] Undo/redo for drag/edit operations
+- [ ] Export: PNG/PDF (client-side), MS Project XML import/export

packages/plugin-gantt/demo/index.html

@@ -0,0 +1,39 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Gantt Demo</title>
+    <style>
+      /* shadcn theme tokens — the prebuilt components CSS consumes these. */
+      :root {
+        --background: 0 0% 100%;
+        --foreground: 240 10% 3.9%;
+        --card: 0 0% 100%;
+        --card-foreground: 240 10% 3.9%;
+        --popover: 0 0% 100%;
+        --popover-foreground: 240 10% 3.9%;
+        --primary: 240 5.9% 10%;
+        --primary-foreground: 0 0% 98%;
+        --secondary: 240 4.8% 95.9%;
+        --secondary-foreground: 240 5.9% 10%;
+        --muted: 240 4.8% 95.9%;
+        --muted-foreground: 240 3.8% 46.1%;
+        --accent: 240 4.8% 95.9%;
+        --accent-foreground: 240 5.9% 10%;
+        --destructive: 0 84.2% 60.2%;
+        --destructive-foreground: 0 0% 98%;
+        --border: 240 5.9% 90%;
+        --input: 240 5.9% 90%;
+        --ring: 240 5.9% 10%;
+        --radius: 0.5rem;
+      }
+      html, body, #root { height: 100%; margin: 0; }
+      body { font-family: ui-sans-serif, system-ui, -apple-system, sans-serif; }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/main.tsx"></script>
+  </body>
+</html>