@ganttloom/gantt-vue 0.5.1 → 0.6.1

package/README.md

@@ -1,272 +1,359 @@
-# @ganttloom/gantt-vue
-
-[![npm](https://img.shields.io/npm/v/%40ganttloom%2Fgantt-vue)](https://www.npmjs.com/package/@ganttloom/gantt-vue)
-[![license](https://img.shields.io/npm/l/%40ganttloom%2Fgantt-vue)](../../LICENSE)
-
-Vue 3 component wrapping [`@ganttloom/gantt-core`](../gantt-core). A thin
-wrapper: it owns no scheduling logic of its own, just Vue lifecycle,
-props-as-events, and an exposed handle for the escape hatches (undo/redo,
-zoom, export) that don't fit the declarative-props model.
-
-![ganttloom overview — day-view Gantt chart with dependencies, critical path, and baselines](https://raw.githubusercontent.com/santhoshkumarhari/ganttLoom/master/docs/screenshots/overview.png)
-
-## Install
-
-```bash
-npm install @ganttloom/gantt-vue
-# vue >=3.3 is a peer dependency
-```
-
-## Quick start
-
-```vue
-<script setup lang="ts">
-import { GanttChart } from "@ganttloom/gantt-vue";
-
-const tasks = [
-  { id: "1", name: "Design", start: new Date("2026-01-05"), end: new Date("2026-01-09"), progress: 60 },
-  { id: "2", name: "Build", start: new Date("2026-01-09"), end: new Date("2026-01-16"), progress: 10 },
-];
-const dependencies = [{ fromId: "1", toId: "2", type: "FS" as const }];
-</script>
-
-<template>
-  <GanttChart
-    :tasks="tasks"
-    :dependencies="dependencies"
-    view-mode="day"
-    show-critical-path
-    enable-history
-    @date-change="(task, start, end) => console.log(task.name, start, end)"
-  />
-</template>
-```
-
-`<GanttChart />` bundles `@ganttloom/gantt-core`'s default stylesheet
-automatically. Props mirror `@ganttloom/gantt-core`'s `GanttOptions`
-one-to-one (in kebab-case, per Vue convention) — see that package's README
-for what each one does. Pass new array/object references to trigger a sync
-(`setTasks`/`setDependencies`/`setOptions` underneath); mutating in place
-won't re-render.
-
-`class`/`style` fall through onto the chart's root element automatically —
-there's no separate prop for them.
-
-## Imperative handle
-
-Props/events cover the declarative surface (tasks, dependencies, view
-options, event listeners). For everything else, use a template ref:
-
-```vue
-<script setup lang="ts">
-import { ref } from "vue";
-import { GanttChart, type GanttChartHandle } from "@ganttloom/gantt-vue";
-
-const chartRef = ref<GanttChartHandle | null>(null);
-</script>
-
-<template>
-  <button @click="chartRef?.undo()">Undo</button>
-  <button @click="chartRef?.zoomIn()">Zoom in</button>
-  <GanttChart ref="chartRef" :tasks="tasks" enable-history />
-</template>
-```
-
-The exposed `GanttChartHandle` has: `undo`/`redo`/`canUndo`/`canRedo`,
-`expandAll`/`collapseAll`/`toggleGroup`, `removeDependency`,
-`updateDependency`, `updateTask`, `setViewMode`,
-`zoomIn`/`zoomOut`/`getZoomLevel`, `fitToViewport`, `scrollToToday`,
-`scrollToRangeStart`/`scrollToRangeEnd`, `getPageCount`/`setPage`,
-`getResourceHistogram`, `getLeveledTasks`,
-`selectTask`/`selectAllVisible`/`clearSelection`/`getSelectedTaskIds`/`bulkShiftDates`/`bulkDelete`,
-`setSort`/`getSort`, `toSVGString`/`toPNGDataURL`/`toPNGDataURLs`,
-`getRenderModel`, and `getInstance()` for direct access to the underlying
-`@ganttloom/gantt-core` `GanttChart` when you need something not on this
-list.
-
-## Multi-select and bulk actions
-
-```vue
-<GanttChart
-  :tasks="tasks"
-  selectable
-  @selection-change="(taskIds) => (selectedCount = taskIds.length)"
-/>
-```
-
-Click selects one bar, ctrl/cmd-click toggles it into the selection,
-shift-click selects a range. Then drive it from the handle:
-`chartRef.value?.bulkShiftDates(dayMs)`, `chartRef.value?.bulkDelete()`.
-
-## Row reorder and dependency editing
-
-```vue
-<GanttChart
-  :tasks="tasks"
-  @task-reorder="(draggedId, targetId, position) => { /* position: before | after | inside */ }"
-  @dependency-dblclick="(dep) => {
-    // show your own 'edit link' UI, then:
-    chartRef?.updateDependency(dep.fromId, dep.toId, { type: 'SS' });
-  }"
-/>
-```
-
-Both off by default (same construction-time-only wiring caveat as
-`task-create` below — attach the listener from the first render).
-Double-clicking a task bar itself fires the separate
-`@task-dblclick="(task) => ..."`, same caveat.
-
-## Filling the viewport at any zoom level
-
-A short project at month/year zoom, or just a handful of tasks, naturally
-renders narrow. `auto-fit-to-viewport` stretches (never shrinks) the
-timeline to fill the container instead of leaving empty space:
-
-```vue
-<GanttChart :tasks="tasks" auto-fit-to-viewport />
-```
-
-Off by default — upgrading doesn't silently change an existing chart's
-pixel layout for anyone who hasn't opted in.
-
-Always on, separately: the visible range is padded to a minimum tick count
-per zoom level, so a short project at year/quarter zoom never collapses
-into one or two lonely columns, and the date header stays pinned to the
-top while scrolling a tall task list vertically (still scrolling
-horizontally in sync with the bars).
-
-## Header position
-
-`header-position` places the grid and timeline headers at `"top"` (the
-default), `"bottom"`, or `"none"` to hide them entirely:
-
-```vue
-<GanttChart :tasks="tasks" header-position="bottom" />
-```
-
-## Drag-to-create
-
-Off by default; attach a `@task-create` listener to turn it on (the core
-only wires the drag listener when a creation handler is present, so existing
-consumers see no behavior change):
-
-```vue
-<GanttChart :tasks="tasks" @task-create="(task) => console.log('created', task)" />
-```
-
-> The core only checks for a listener **at mount** (same caveat as the other
-> gated events above) — attach it from the first render if you want
-> drag-to-create enabled; toggling it on after mount won't retroactively wire it.
-
-## Timeline markers, column resize/reorder, and search
-
-```vue
-<script setup lang="ts">
-import { filterTasks } from "@ganttloom/gantt-vue";
-</script>
-
-<template>
-  <GanttChart
-    :tasks="filterTasks(tasks, (t) => t.name.includes(query)).tasks"
-    :markers="[{ date: releaseDate, label: 'Release' }]"
-    @column-resize="(id, width) => (columnWidths[id] = width)"
-    @column-reorder="(order) => (columnOrder = order)"
-  />
-</template>
-```
-
-See `@ganttloom/gantt-core`'s README for the full behavior of each — the
-props/events here are 1:1 mirrors of its `GanttOptions` fields, and
-`filterTasks` is a pure re-export.
-
-## Column sorting
-
-Mark a column `sortable`; clicking its header cycles asc → desc → none:
-
-```vue
-<GanttChart
-  :tasks="tasks"
-  :columns="[{ id: 'name', title: 'Task', sortable: true }]"
-  @sort-change="(sort) => console.log(sort)"
-/>
-```
-
-`chartRef.value?.setSort(columnId, direction)` / `.getSort()` are also
-available on the handle.
-
-## Resource leveling and multi-page PNG export
-
-```ts
-const { tasks: leveled, shifted } = chartRef.value!.getLeveledTasks();
-if (shifted.length) tasks.value = leveled; // if you're holding tasks in your own state
-
-const pages = await chartRef.value!.toPNGDataURLs({ pageWidthPx: 1600, pageHeightPx: 1200 });
-```
-
-## Resource histogram
-
-```vue
-<script setup lang="ts">
-import { computed } from "vue";
-import { renderResourceHistogramSVG } from "@ganttloom/gantt-vue";
-
-const histogramSvg = computed(() => renderResourceHistogramSVG(chartRef.value?.getResourceHistogram() ?? []));
-</script>
-
-<template>
-  <div v-html="histogramSvg" />
-</template>
-```
-
-## Hover tooltips
-
-On by default (name/dates/progress/assignees/notes), styled via plain CSS
-(`.gantt-tooltip`, see `gantt-core`'s README) — not the browser's native
-tooltip. `renderTooltip` fully replaces the content:
-
-```vue
-<GanttChart
-  :tasks="tasks"
-  :render-tooltip="(task) => (task.isMilestone ? null : `${task.name} — ${task.progress ?? 0}%`)"
-/>
-```
-
-Set `:show-tooltip="false"` to disable it entirely.
-
-## `useGanttChart` (lower-level composable)
-
-If you want to own the container element/DOM tree yourself instead of using
-`<GanttChart />`:
-
-```vue
-<script setup lang="ts">
-import { ref } from "vue";
-import { useGanttChart, type GanttTask, type GanttDependency } from "@ganttloom/gantt-vue";
-
-const props = defineProps<{ tasks: GanttTask[]; dependencies: GanttDependency[] }>();
-const containerRef = ref<HTMLDivElement | null>(null);
-const { chart, canUndo, canRedo } = useGanttChart(
-  containerRef,
-  () => props.tasks,
-  () => props.dependencies,
-  () => ({ enableHistory: true })
-);
-</script>
-
-<template>
-  <div ref="containerRef" />
-</template>
-```
-
-`useGanttChart` takes getter functions (not refs) for `tasks`/`dependencies`/`options`
-so it can track whatever reactive source each one reads — a prop, a `ref`, a `computed`.
-
-## Re-exported types & helpers
-
-For convenience, this package re-exports every `@ganttloom/gantt-core` type
-(`GanttTask`, `GanttDependency`, `GanttColumn`, `GanttTheme`, `ViewMode`,
-`WorkingCalendar`, `ConstraintType`, `ResourceLoadBucket`, etc.) and the
-standalone helper functions (`computeWBSCodes`, `applyConstraint`,
-`isWorkingDay`, `nextWorkingDay`, `computeResourceHistogram`,
-`renderResourceHistogramSVG`, ...) so you never need
-`@ganttloom/gantt-core` as a direct dependency just to reference them.
+# @ganttloom/gantt-vue
+
+[![npm](https://img.shields.io/npm/v/%40ganttloom%2Fgantt-vue)](https://www.npmjs.com/package/@ganttloom/gantt-vue)
+[![license](https://img.shields.io/npm/l/%40ganttloom%2Fgantt-vue)](../../LICENSE)
+
+Vue 3 component wrapping [`@ganttloom/gantt-core`](../gantt-core). A thin
+wrapper: it owns no scheduling logic of its own, just Vue lifecycle,
+props-as-events, and an exposed handle for the escape hatches (undo/redo,
+zoom, export) that don't fit the declarative-props model.
+
+![ganttloom overview — day-view Gantt chart with dependencies, critical path, and baselines](https://raw.githubusercontent.com/santhoshkumarhari/ganttLoom/master/docs/screenshots/overview.png)
+
+## Install
+
+```bash
+npm install @ganttloom/gantt-vue
+# vue >=3.3 is a peer dependency
+```
+
+## Quick start
+
+```vue
+<script setup lang="ts">
+import { GanttChart } from "@ganttloom/gantt-vue";
+
+const tasks = [
+  { id: "1", name: "Design", start: new Date("2026-01-05"), end: new Date("2026-01-09"), progress: 60 },
+  { id: "2", name: "Build", start: new Date("2026-01-09"), end: new Date("2026-01-16"), progress: 10 },
+];
+const dependencies = [{ fromId: "1", toId: "2", type: "FS" as const }];
+</script>
+
+<template>
+  <GanttChart
+    :tasks="tasks"
+    :dependencies="dependencies"
+    view-mode="day"
+    show-critical-path
+    enable-history
+    @date-change="(task, start, end) => console.log(task.name, start, end)"
+  />
+</template>
+```
+
+`<GanttChart />` injects `@ganttloom/gantt-core`'s default stylesheet
+automatically (a `<style>` tag added to `<head>` on first mount; no CSS
+import, so the package also loads under SSR/Node/Jest). Props mirror `@ganttloom/gantt-core`'s `GanttOptions`
+one-to-one (in kebab-case, per Vue convention) — see that package's README
+for what each one does. Pass new array/object references to trigger a sync
+(`setTasks`/`setDependencies`/`setOptions` underneath); mutating in place
+won't re-render.
+
+`class`/`style` fall through onto the chart's root element automatically —
+there's no separate prop for them.
+
+## Imperative handle
+
+Props/events cover the declarative surface (tasks, dependencies, view
+options, event listeners). For everything else, use a template ref:
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { GanttChart, type GanttChartHandle } from "@ganttloom/gantt-vue";
+
+const chartRef = ref<GanttChartHandle | null>(null);
+</script>
+
+<template>
+  <button @click="chartRef?.undo()">Undo</button>
+  <button @click="chartRef?.zoomIn()">Zoom in</button>
+  <GanttChart ref="chartRef" :tasks="tasks" enable-history />
+</template>
+```
+
+The exposed `GanttChartHandle` has: `undo`/`redo`/`canUndo`/`canRedo`,
+`expandAll`/`collapseAll`/`toggleGroup`, `removeDependency`,
+`updateDependency`, `updateTask`, `setViewMode`,
+`zoomIn`/`zoomOut`/`getZoomLevel`, `fitToViewport`, `scrollToToday`,
+`scrollToRangeStart`/`scrollToRangeEnd`, `getPageCount`/`setPage`,
+`getResourceHistogram`, `getLeveledTasks`,
+`selectTask`/`selectAllVisible`/`clearSelection`/`getSelectedTaskIds`/`bulkShiftDates`/`bulkDelete`,
+`setSort`/`getSort`, `toSVGString`/`toPNGDataURL`/`toPNGDataURLs`,
+`getRenderModel`, and `getInstance()` for direct access to the underlying
+`@ganttloom/gantt-core` `GanttChart` when you need something not on this
+list.
+
+## Multi-select and bulk actions
+
+```vue
+<GanttChart
+  :tasks="tasks"
+  selectable
+  @selection-change="(taskIds) => (selectedCount = taskIds.length)"
+/>
+```
+
+Click selects one bar, ctrl/cmd-click toggles it into the selection,
+shift-click selects a range. Then drive it from the handle:
+`chartRef.value?.bulkShiftDates(dayMs)`, `chartRef.value?.bulkDelete()`.
+
+## Row reorder and dependency editing
+
+```vue
+<GanttChart
+  :tasks="tasks"
+  @task-reorder="(draggedId, targetId, position) => { /* position: before | after | inside */ }"
+  @dependency-dblclick="(dep) => {
+    // show your own 'edit link' UI, then:
+    chartRef?.updateDependency(dep.fromId, dep.toId, { type: 'SS' });
+  }"
+/>
+```
+
+Both off by default (same construction-time-only wiring caveat as
+`task-create` below — attach the listener from the first render).
+Double-clicking a task bar itself fires the separate
+`@task-dblclick="(task) => ..."`, same caveat.
+
+## Filling the viewport at any zoom level
+
+A short project at month/year zoom, or just a handful of tasks, naturally
+renders narrow. `auto-fit-to-viewport` stretches (never shrinks) the
+timeline to fill the container instead of leaving empty space:
+
+```vue
+<GanttChart :tasks="tasks" auto-fit-to-viewport />
+```
+
+Off by default — upgrading doesn't silently change an existing chart's
+pixel layout for anyone who hasn't opted in.
+
+Always on, separately: the visible range is padded to a minimum tick count
+per zoom level, so a short project at year/quarter zoom never collapses
+into one or two lonely columns, and the date header stays pinned to the
+top while scrolling a tall task list vertically (still scrolling
+horizontally in sync with the bars).
+
+## Header position
+
+`header-position` places the grid and timeline headers at `"top"` (the
+default), `"bottom"`, or `"none"` to hide them entirely:
+
+```vue
+<GanttChart :tasks="tasks" header-position="bottom" />
+```
+
+## Drag-to-create
+
+Off by default; attach a `@task-create` listener to turn it on (the core
+only wires the drag listener when a creation handler is present, so existing
+consumers see no behavior change):
+
+```vue
+<GanttChart :tasks="tasks" @task-create="(task) => console.log('created', task)" />
+```
+
+> The core only checks for a listener **at mount** (same caveat as the other
+> gated events above) — attach it from the first render if you want
+> drag-to-create enabled; toggling it on after mount won't retroactively wire it.
+
+## Timeline markers, column resize/reorder, and search
+
+```vue
+<script setup lang="ts">
+import { filterTasks } from "@ganttloom/gantt-vue";
+</script>
+
+<template>
+  <GanttChart
+    :tasks="filterTasks(tasks, (t) => t.name.includes(query)).tasks"
+    :markers="[{ date: releaseDate, label: 'Release' }]"
+    @column-resize="(id, width) => (columnWidths[id] = width)"
+    @column-reorder="(order) => (columnOrder = order)"
+  />
+</template>
+```
+
+See `@ganttloom/gantt-core`'s README for the full behavior of each — the
+props/events here are 1:1 mirrors of its `GanttOptions` fields, and
+`filterTasks` is a pure re-export.
+
+## Column sorting
+
+Mark a column `sortable`; clicking its header cycles asc → desc → none:
+
+```vue
+<GanttChart
+  :tasks="tasks"
+  :columns="[{ id: 'name', title: 'Task', sortable: true }]"
+  @sort-change="(sort) => console.log(sort)"
+/>
+```
+
+`chartRef.value?.setSort(columnId, direction)` / `.getSort()` are also
+available on the handle.
+
+## Resource leveling and multi-page PNG export
+
+```ts
+const { tasks: leveled, shifted } = chartRef.value!.getLeveledTasks();
+if (shifted.length) tasks.value = leveled; // if you're holding tasks in your own state
+
+const pages = await chartRef.value!.toPNGDataURLs({ pageWidthPx: 1600, pageHeightPx: 1200 });
+```
+
+## Resource histogram
+
+```vue
+<script setup lang="ts">
+import { computed } from "vue";
+import { renderResourceHistogramSVG } from "@ganttloom/gantt-vue";
+
+const histogramSvg = computed(() => renderResourceHistogramSVG(chartRef.value?.getResourceHistogram() ?? []));
+</script>
+
+<template>
+  <div v-html="histogramSvg" />
+</template>
+```
+
+## Hover tooltips
+
+On by default (name/dates/progress/assignees/notes), styled via plain CSS
+(`.gantt-tooltip`, see `gantt-core`'s README) — not the browser's native
+tooltip. `renderTooltip` fully replaces the content:
+
+```vue
+<GanttChart
+  :tasks="tasks"
+  :render-tooltip="(task) => (task.isMilestone ? null : `${task.name} — ${task.progress ?? 0}%`)"
+/>
+```
+
+Set `:show-tooltip="false"` to disable it entirely.
+
+## i18n / overridable labels
+
+A handful of built-in strings (aria-labels, the default name for a
+newly-created task, the tooltip's date/progress formatting) can be overridden
+via the `labels` prop — see `gantt-core`'s README for the full field list:
+
+```vue
+<GanttChart
+  :tasks="tasks"
+  :labels="{
+    expand: 'Développer',
+    collapse: 'Réduire',
+    newTaskName: 'Nouvelle tâche',
+    formatDate: (d) => d.toLocaleDateString('fr-FR'),
+  }"
+/>
+```
+
+`labels.formatTickLabel` overrides the timeline header's own day/week/month
+tick labels (distinct from `formatDate` above, which only covers the tooltip
+and bar aria-label) - it receives each tick's `Date` and the current
+`view-mode`:
+
+```vue
+<GanttChart
+  :tasks="tasks"
+  view-mode="week"
+  :labels="{ formatTickLabel: (date, viewMode) => date.toLocaleDateString('fr-FR') }"
+/>
+```
+
+## Custom sort comparator
+
+Set `sortFn` on a sortable `GanttColumn` to fully control its comparison
+instead of the default accessor-based one - see `gantt-core`'s README for
+details:
+
+```vue
+<GanttChart
+  :tasks="tasks"
+  :columns="[
+    {
+      id: 'priority',
+      title: 'Priority',
+      accessor: (t) => t.data?.priority,
+      sortable: true,
+      sortFn: (a, b) => (a.data?.priority === 'high' ? -1 : 1),
+    },
+  ]"
+/>
+```
+
+## Custom task-bar rendering
+
+`render-bar` lets you draw custom SVG content into a task bar (icons,
+patterns, extra shapes) without forking the renderer - see `gantt-core`'s
+README for the append-only contract that keeps drag/resize hit-testing intact:
+
+```vue
+<GanttChart
+  :tasks="tasks"
+  :render-bar="
+    ({ task, bar, group }) => {
+      if (!task.data?.flagged) return;
+      const icon = document.createElementNS('http://www.w3.org/2000/svg', 'text');
+      icon.setAttribute('x', String(bar.width + 6));
+      icon.setAttribute('y', '-4');
+      icon.textContent = '⚑';
+      group.appendChild(icon);
+    }
+  "
+/>
+```
+
+## Arbitrary attributes on the root element
+
+`<GanttChart>` has a single root `<div>`, so any attribute you pass that
+isn't a declared prop - `id`, `data-*`, `aria-*`, `class`, `style`, etc. -
+falls through onto it automatically (Vue's default [attribute
+inheritance](https://vuejs.org/guide/components/attrs.html)), no extra prop
+needed:
+
+```vue
+<GanttChart :tasks="tasks" data-testid="project-gantt" aria-label="Project schedule" />
+```
+
+## `useGanttChart` (lower-level composable)
+
+If you want to own the container element/DOM tree yourself instead of using
+`<GanttChart />`:
+
+```vue
+<script setup lang="ts">
+import { ref } from "vue";
+import { useGanttChart, type GanttTask, type GanttDependency } from "@ganttloom/gantt-vue";
+
+const props = defineProps<{ tasks: GanttTask[]; dependencies: GanttDependency[] }>();
+const containerRef = ref<HTMLDivElement | null>(null);
+const { chart, canUndo, canRedo } = useGanttChart(
+  containerRef,
+  () => props.tasks,
+  () => props.dependencies,
+  () => ({ enableHistory: true })
+);
+</script>
+
+<template>
+  <div ref="containerRef" />
+</template>
+```
+
+`useGanttChart` takes getter functions (not refs) for `tasks`/`dependencies`/`options`
+so it can track whatever reactive source each one reads — a prop, a `ref`, a `computed`.
+
+## Re-exported types & helpers
+
+For convenience, this package re-exports every `@ganttloom/gantt-core` type
+(`GanttTask`, `GanttDependency`, `GanttColumn`, `GanttTheme`, `ViewMode`,
+`WorkingCalendar`, `ConstraintType`, `ResourceLoadBucket`, etc.) and the
+standalone helper functions (`computeWBSCodes`, `applyConstraint`,
+`isWorkingDay`, `nextWorkingDay`, `computeResourceHistogram`,
+`renderResourceHistogramSVG`, ...) so you never need
+`@ganttloom/gantt-core` as a direct dependency just to reference them.