@ganttloom/gantt-core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Santhoshkumar Hariharan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,388 @@
+# @ganttloom/gantt-core
+
+Framework-agnostic Gantt chart engine: layout, SVG rendering, drag/resize/link
+interactions, grouping, critical path, undo/redo, and more — zero runtime
+dependencies. If you're using React, prefer
+[`@ganttloom/gantt-react`](../gantt-react); use this package directly if
+you're integrating with something else (Vue, Svelte, vanilla JS) or want full
+control over the DOM lifecycle.
+
+## Install
+
+```bash
+npm install @ganttloom/gantt-core
+```
+
+## Quick start
+
+```ts
+import { GanttChart } from "@ganttloom/gantt-core";
+import "@ganttloom/gantt-core/styles.css";
+
+const container = document.getElementById("gantt")!;
+
+const chart = new GanttChart(
+  container,
+  [
+    { 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 },
+  ],
+  [{ fromId: "1", toId: "2", type: "FS" }],
+  { viewMode: "day", showCriticalPath: true, enableHistory: true }
+);
+
+chart.on("date-change", ({ task, start, end }) => {
+  console.log(`${task.name} moved to ${start} - ${end}`);
+});
+```
+
+Tasks and dependencies are plain objects — the chart never owns your state.
+Call `chart.setTasks(...)` / `chart.setDependencies(...)` whenever your data
+changes; call `chart.destroy()` when you're done with it.
+
+## Core concepts
+
+- **`GanttTask`** — `id`, `name`, `start`/`end` (`Date`), optional `progress`,
+  `parentId` (for grouping), `isGroup`, `isMilestone`, `collapsed`, `color`,
+  `readonly`, `baselineStart`/`baselineEnd`, `deadline`, `constraintType` /
+  `constraintDate`, `assignees`, and a free-form `data` bag.
+- **`GanttDependency`** — `fromId`, `toId`, a `type` of `"FS" | "SS" | "FF" | "SF"`,
+  and an optional `lagMs`.
+- **`GanttColumn`** — describes one column of the left-hand grid panel, with
+  an optional `accessor` to derive its cell value from a task and `getHref`
+  to render it as a link.
+- **`GanttOptions`** — everything else: view mode, theme, readonly, which
+  optional features are on, and the event callbacks. See [`src/types.ts`](./src/types.ts)
+  for the full, always-current list — it's the source of truth.
+
+## Feature options (all opt-in)
+
+| Option | What it does |
+|---|---|
+| `showCriticalPath` | Highlights the critical path (longest dependency chain) |
+| `showBaseline` | Renders `baselineStart`/`baselineEnd` as a faint bar behind the live one |
+| `showDeadlines` (default `true`) | Renders `task.deadline` as a flag marker; red when the task's end is past it |
+| `showAssigneeAvatars` | Renders `task.assignees` as small avatars/initials at the bar's left edge |
+| `enableHistory` | Turns on `chart.undo()` / `chart.redo()` for move/resize/link/progress/create actions |
+| `keyboardAccessible` | ARIA roles/labels on bars + arrow-key movement |
+| `virtualScroll` (default `true`) | Only renders DOM/SVG nodes for rows in the visible viewport |
+| `pagination` | `{ pageSize, page }` — render only a page of top-level rows |
+| `autoSchedule` | Moving/resizing a task cascades date shifts to dependent successors |
+| `calendar` | A `WorkingCalendar` (working days + holidays) — shades non-working time and, with `autoSchedule`, skips it when cascading |
+| `snapToUnit` | Round drag/resize deltas to `"hour" \| "day" \| "week"`, or `false` for raw pixels |
+| `colorScheme` | `"light" \| "dark" \| "auto"` (default `"auto"`, follows the OS preference live) |
+
+## Working-time calendars
+
+```ts
+import type { WorkingCalendar } from "@ganttloom/gantt-core";
+
+const calendar: WorkingCalendar = {
+  workingDays: [false, true, true, true, true, true, false], // Sun..Sat; this is also the default
+  holidays: ["2026-01-19", "2026-02-16"], // ISO "YYYY-MM-DD"
+};
+
+new GanttChart(container, tasks, deps, { calendar, autoSchedule: true });
+```
+
+Non-working days are shaded in the timeline. With `autoSchedule` on, a
+successor task pushed by a dependency cascade is nudged forward to the next
+working day. Standalone helpers (`isWorkingDay`, `isHoliday`, `nextWorkingDay`,
+`previousWorkingDay`, `shiftToWorkingDay`) are also exported if you need the
+same logic outside the chart.
+
+## Task constraints
+
+MSP-style constraints (`constraintType` + `constraintDate` on a `GanttTask`)
+are enforced during `autoSchedule` cascades — when a dependency pushes a
+constrained successor, its constraint is applied on top of the cascade
+before the new dates are committed:
+
+```ts
+{ id: "3", name: "Vendor delivery", start, end, constraintType: "mso", constraintDate: new Date("2026-02-01") }
+```
+
+`ConstraintType` is one of `"asap" | "alap" | "snet" | "snlt" | "fnet" | "fnlt" | "mso" | "mfo"`
+(as-soon-as-possible / as-late-as-possible / start-no-earlier/later-than /
+finish-no-earlier/later-than / must-start/finish-on). `"asap"`/`"alap"` are
+no-ops — a true as-late-as-possible schedule needs a backward pass from the
+project end date, which this incremental, per-drag engine doesn't attempt.
+The standalone `applyConstraint(range, type, date)` function is exported if
+you want the same logic elsewhere. Constraints only take effect during a
+cascade; they don't restrict a direct manual drag of the constrained task
+itself (matching how MSP flags rather than blocks a violated constraint).
+
+## Drag-to-create tasks
+
+Opt in by supplying `onTaskCreate`: dragging on an empty part of any row's
+timeline then creates a new sibling task (same `parentId` as that row) with
+the dragged date range, inserted right after that row.
+
+```ts
+new GanttChart(container, tasks, deps, {
+  onTaskCreate: (task) => console.log("created", task),
+});
+```
+
+Without `onTaskCreate`, drag-to-create is off — dragging empty timeline
+space does nothing, so existing consumers see no behavior change.
+
+## Resource histogram
+
+```ts
+import { computeResourceHistogram, renderResourceHistogramSVG } from "@ganttloom/gantt-core";
+
+const buckets = computeResourceHistogram(tasks, { capacityHoursPerDay: 8, calendar });
+// [{ assigneeId, assigneeName, date, allocatedHours, capacityHours, overallocated }, ...]
+
+document.getElementById("histogram")!.innerHTML = renderResourceHistogramSVG(buckets);
+```
+
+Each assignee is treated as fully allocated (one day's capacity) on every
+working day a task they're on spans — there's no per-task effort/FTE field
+in `GanttTask`, so that's the only allocation model the plain task data can
+support. `overallocated` is `true` once a bucket's summed hours exceed
+`capacityHours` (default 8/day).
+
+## WBS numbering
+
+```ts
+import { computeWBSCodes } from "@ganttloom/gantt-core";
+
+const wbs = computeWBSCodes(tasks); // Map<taskId, "1" | "1.1" | "1.2" | "2" | ...>
+const columns = [{ id: "wbs", title: "WBS", accessor: (t) => wbs.get(t.id) }];
+```
+
+Codes are computed fresh from the current `tasks` array (recompute after any
+reorder/renest) rather than stored on the task, keeping with "everything is
+a plain object."
+
+## Timeline markers
+
+```ts
+new GanttChart(container, tasks, deps, {
+  markers: [{ date: new Date("2026-02-01"), label: "Sprint boundary" }],
+});
+```
+
+Arbitrary labeled vertical lines on the timeline, independent of any task —
+for release dates, sprint boundaries, or any other project-wide event.
+
+## Grid column resize/reorder
+
+Both off by default; supply the corresponding handler to opt in (same
+construction-time-only wiring caveat as `onTaskCreate`):
+
+```ts
+new GanttChart(container, tasks, deps, {
+  columns,
+  onColumnResize: (columnId, width) => { /* persist the new width */ },
+  onColumnReorder: (order) => { /* persist the new column id order */ },
+});
+```
+
+Drag a column header's right edge to resize it; drag a header itself to
+reorder columns. The chart applies the change to its own internal copy of
+`columns` immediately (so the drag feels live) and calls back so you can
+persist it — same pattern as a task drag and `onDateChange`.
+
+## Task search/filter
+
+```ts
+import { filterTasks } from "@ganttloom/gantt-core";
+
+const { tasks: visible, matchedIds } = filterTasks(tasks, (t) =>
+  t.name.toLowerCase().includes(query.toLowerCase())
+);
+chart.setTasks(visible);
+```
+
+Pure/compute-only — it returns the filtered subset (keeping a matched
+task's ancestors and descendants by default, so the tree stays intact) and
+the set of directly-matched ids, which you can use to dim ancestor/descendant
+rows shown only for tree context. There's no special renderer wiring: feeding
+`chart.setTasks(visible)` a smaller array hides the rest, the same as any
+other plain-data update.
+
+## Scroll-to-today, group progress rollup, and custom cells
+
+```ts
+chart.scrollToToday(); // centers the viewport on today's date
+
+new GanttChart(container, tasks, deps, {
+  autoRollupProgress: true, // a group with no explicit `progress` averages its children's, duration-weighted
+});
+
+const columns = [
+  { id: "status", title: "Status", render: (task) => {
+      const el = document.createElement("span");
+      el.className = task.progress === 100 ? "badge-done" : "badge-pending";
+      el.textContent = task.progress === 100 ? "Done" : "Pending";
+      return el; // or return a plain string - never parsed as HTML, so it's XSS-safe by construction
+    } },
+];
+```
+
+## Row reorder and dependency editing
+
+Both off by default; supply the corresponding handler to opt in:
+
+```ts
+new GanttChart(container, tasks, deps, {
+  onTaskReorder: (draggedId, targetId, position) => {
+    // position: "before" | "after" (reorder as a sibling) | "inside" (reparent under target)
+  },
+  onDependencyDblClick: (dep) => {
+    // open your own "edit this link" UI, then call:
+    chart.updateDependency(dep.fromId, dep.toId, { type: "SS", lagMs: 3600_000 });
+  },
+});
+```
+
+Dragging a grid row onto another fires `onTaskReorder`; the chart applies
+the reorder/reparent to its own internal task list immediately (live drag
+feedback) the same way column resize does. Double-clicking a dependency
+link fires `onDependencyDblClick` — the engine has no built-in "edit link"
+popover (keeping with zero-dependency, minimal-UI scope), so build your own
+and call `chart.updateDependency(...)` (undoable) to apply the result.
+
+## Multi-select and bulk actions
+
+```ts
+new GanttChart(container, tasks, deps, {
+  selectable: true,
+  onSelectionChange: (taskIds) => console.log("selected:", taskIds),
+});
+
+// Click selects one; ctrl/cmd-click toggles; shift-click selects a range (by visible row order).
+chart.selectTask("t1");
+chart.selectTask("t2", { additive: true });
+chart.bulkShiftDates(24 * 60 * 60 * 1000); // shift every selected task by 1 day, one undo step
+chart.bulkDelete(); // remove every selected task (and touching dependencies), one undo step
+```
+
+## Split tasks
+
+```ts
+{ id: "qa", name: "QA pass", start, end, segments: [
+  { start: day1, end: day2 },
+  { start: day4, end: day5 }, // a gap, e.g. paused for an upstream fix
+] }
+```
+
+`start`/`end` stay the authoritative overall envelope (used for
+dependencies, critical path, baseline, etc.); `segments` only changes how
+the bar is *drawn* — as separate rects joined by a dashed connector.
+Dragging the whole task shifts every segment together; resizing an edge
+only adjusts the first (left) or last (right) segment's outer edge, leaving
+any gap untouched.
+
+## Task notes, auto-color, baseline history, and density presets
+
+```ts
+{ id: "t1", name: "Ship v2", start, end, notes: "Blocked on legal review" } // hover the bar for a native tooltip
+```
+
+```ts
+import { applyColorByField } from "@ganttloom/gantt-core";
+
+const colored = applyColorByField(tasks, (t) => t.assignees?.[0]?.id); // one color per first assignee
+new GanttChart(container, colored, deps);
+```
+
+```ts
+{ id: "t1", name: "Ship v2", start, end, baselines: [
+  { label: "Original plan", start: d1, end: d2 },
+  { label: "As of last Friday", start: d3, end: d4 },
+] } // rendered as multiple faint stacked bars, oldest furthest back; requires showBaseline: true
+```
+
+```ts
+import { DENSITY_PRESETS } from "@ganttloom/gantt-core";
+
+new GanttChart(container, tasks, deps, { theme: { ...DENSITY_PRESETS.compact } });
+```
+
+None of these need a core option - `notes`/`baselines` are plain `GanttTask` fields, `applyColorByField`/`DENSITY_PRESETS` are pure helpers/data you apply before constructing the chart.
+
+## Partial-day working hours
+
+```ts
+const calendar: WorkingCalendar = {
+  holidays: ["2026-01-19"],
+  workingHours: { start: 9, end: 17 }, // 9am-5pm
+};
+new GanttChart(container, tasks, deps, { calendar, autoSchedule: true, viewMode: "hour" });
+```
+
+Narrows *anchor points*, not duration math: a 3-day task cascaded by
+`autoSchedule` lands its new start within the working window (not at
+11pm), but stays a 3-calendar-day task, not "3 working-window days." Hour
+view shades individual non-working hours (not just whole non-working days).
+`isWithinWorkingHours`/`isWorkingTime`/`shiftToWorkingTime` are exported if
+you need the same logic elsewhere.
+
+## Resource leveling
+
+```ts
+const { tasks: leveled, shifted } = chart.getLeveledTasks();
+// or standalone: levelResources(tasks, dependencies, { calendar })
+chart.setTasks(leveled); // apply it
+console.log(shifted); // [{ taskId, delayMs }, ...] - what moved and by how much
+```
+
+Delays (never pulls earlier) tasks so no assignee is double-booked on a
+working day, using the same "fully allocated while active" model as
+`computeResourceHistogram` - so a leveled schedule always shows zero
+`overallocated` buckets afterward. Respects FS ("finish-to-start")
+dependencies (never places a task before its FS predecessors finish);
+SS/FF/SF aren't specifically enforced - a documented scope limit rather
+than a full constraint solver.
+
+## Multi-page PNG export
+
+```ts
+const pages = await chart.toPNGDataURLs({ pageWidthPx: 1600, pageHeightPx: 1200 });
+// [dataUrl1, dataUrl2, ...] in row-major tile order, each at full fidelity
+```
+
+For charts too large to comfortably rasterize as one image; omit the
+options to get a single image at the chart's actual size (same as
+`toPNGDataURL()`).
+
+## Keyboard navigation
+
+With `keyboardAccessible: true`: Tab/Shift+Tab move between bars (native
+browser focus order - every bar has `tabindex="0"`), arrow keys nudge a
+focused bar by a day, Enter clicks it, **Home**/**End** scroll the timeline
+to the start/end of the project's date range, and **Ctrl/Cmd+A** selects
+every visible task when `selectable` is also on.
+
+## Zoom
+
+```ts
+chart.zoomIn();       // 1.25x by default, clamps at a 400px/unit ceiling
+chart.zoomOut(1.5);   // custom factor
+chart.getZoomLevel(); // current columnWidth, in px/unit
+chart.fitToViewport(containerEl.clientWidth); // zoom-to-fit: scales so the whole project fits
+```
+
+## Export / import
+
+- `chart.toSVGString()` / `chart.toPNGDataURL()` — raster/vector snapshot of the current render.
+- `tasksToCSV(tasks)` / `tasksFromCSV(csv)` — round-trip through CSV.
+- For PDF/PPTX, see [`@ganttloom/gantt-export`](../gantt-export), which consumes
+  `chart.getRenderModel()` directly.
+
+## Theming
+
+Every visual token is a `--gantt-*` CSS custom property (see `styles.css`),
+in addition to the JS `theme` option (`Partial<GanttTheme>`) — style via
+either, or both. `colorScheme: "auto"` (the default) follows
+`prefers-color-scheme` live.
+
+## API surface
+
+The full, current type/function list is re-exported from
+[`src/index.ts`](./src/index.ts) — treat it as the reference; this README
+covers the concepts, not every signature.