@ganttloom/gantt-core 0.2.0 → 0.4.0

package/README.md

@@ -1,11 +1,17 @@
 # @ganttloom/gantt-core
 
+[![npm](https://img.shields.io/npm/v/%40ganttloom%2Fgantt-core)](https://www.npmjs.com/package/@ganttloom/gantt-core)
+[![license](https://img.shields.io/npm/l/%40ganttloom%2Fgantt-core)](../../LICENSE)
+
 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.
+dependencies. If you're using React or Vue, prefer
+[`@ganttloom/gantt-react`](../gantt-react) or
+[`@ganttloom/gantt-vue`](../gantt-vue); use this package directly if you're
+integrating with something else (Svelte, vanilla JS) or want full control
+over the DOM lifecycle.
+
+![ganttloom overview — day-view Gantt chart with dependencies, critical path, and baselines](https://raw.githubusercontent.com/santhoshkumarhari/ganttLoom/master/docs/screenshots/overview.png)
 
 ## Install
 
@@ -186,6 +192,30 @@ 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`.
 
+## Grid column sorting
+
+Mark a column `sortable: true` and clicking its header cycles ascending →
+descending → none, with a `▲`/`▼` indicator:
+
+```ts
+new GanttChart(container, tasks, deps, {
+  columns: [
+    { id: "name", title: "Task", sortable: true },
+    { id: "assignee", title: "Assignee", accessor: (t) => t.assignees?.[0]?.name, sortable: true },
+  ],
+  onSortChange: (sort) => console.log(sort), // { columnId, direction } | null
+});
+
+chart.setSort("assignee", "desc"); // or null to clear
+chart.getSort(); // { columnId: "assignee", direction: "desc" } | null
+```
+
+Sorting reorders **siblings at every tree level** by the column's value (via
+`accessor`, or `task.name` for the conventional unaccessored "name" column)
+— the group/parent hierarchy itself is never reshuffled, only the order
+within it. A column with neither `accessor` nor the id `"name"` has nothing
+sortable to read and is a no-op if marked sortable.
+
 ## Task search/filter
 
 ```ts
@@ -246,6 +276,39 @@ 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.
 
+Double-clicking a task bar itself (not a link) fires the separate
+`onTaskDblClick(task)` — also off by default until you supply a handler.
+
+## Filling the viewport at any zoom level
+
+A short project at month/year zoom, or a chart with just a handful of
+tasks, naturally renders narrow — the timeline's pixel width is purely a
+function of the task date range and the current zoom, with no awareness of
+how much horizontal space is actually available. Set
+`autoFitToViewport: true` to stretch (never shrink) the timeline so it
+fills the container instead of leaving empty space to the right:
+
+```ts
+new GanttChart(container, tasks, deps, { autoFitToViewport: true });
+```
+
+Re-evaluated on view-mode/task changes and on container resize (via
+`ResizeObserver`). It never applies if the content is already wider than
+the container — that's what normal horizontal scrolling is for. Off by
+default, so upgrading doesn't silently change an existing chart's pixel
+layout for anyone who hasn't opted in.
+
+Separately, and always on: a short project at a coarse zoom no longer
+renders as one or two lonely ticks. The visible date range is padded out to
+a sensible minimum column count per zoom level (year: 5, quarter: 4,
+month/week: 6, day: 7, hour: 8), so a 3-month project at year zoom still
+shows a real multi-year timeline instead of a cramped sliver. Wider ranges
+are unaffected — this only ever pads, never trims.
+
+The timeline's date header also stays pinned to the top of the chart while
+you scroll a tall task list vertically (it still scrolls horizontally in
+sync with the bars), instead of scrolling out of view along with the rows.
+
 ## Multi-select and bulk actions
 
 ```ts
@@ -277,10 +340,39 @@ 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.
 
+## Hover tooltips
+
+Every bar shows a floating, CSS-customizable tooltip on hover (name, dates,
+progress, assignees, and `task.notes` if set) — not the browser's native
+`title` tooltip, so it's fully styleable:
+
+```css
+.gantt-tooltip { background: #111827; border-radius: 8px; }
+.gantt-tooltip-title { font-weight: 700; }
+```
+
+For full control over markup, `renderTooltip` works exactly like
+`GanttColumn.render` — return an `HTMLElement` to mount directly, a string
+(rendered as text, never parsed as HTML), or `null`/`undefined` to suppress
+the tooltip for that specific task:
+
+```ts
+new GanttChart(el, tasks, deps, {
+  renderTooltip: (task) => {
+    if (task.isMilestone) return null; // no tooltip on milestones
+    const div = document.createElement("div");
+    div.textContent = `${task.name} — ${task.progress ?? 0}%`;
+    return div;
+  },
+});
+```
+
+Set `showTooltip: false` to disable it entirely.
+
 ## 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
+{ id: "t1", name: "Ship v2", start, end, notes: "Blocked on legal review" } // shown as an extra line in the default tooltip
 ```
 
 ```ts
@@ -381,6 +473,56 @@ in addition to the JS `theme` option (`Partial<GanttTheme>`) — style via
 either, or both. `colorScheme: "auto"` (the default) follows
 `prefers-color-scheme` live.
 
+To override a token via CSS, target `.gantt-root` itself (the element the
+chart renders into) rather than an ancestor — the defaults are declared on
+`.gantt-root`, and a same-element declaration always wins over one inherited
+from a parent, regardless of specificity:
+
+```css
+.gantt-root {
+  --gantt-bar-color: #16a34a;
+  --gantt-critical-color: #ea580c;
+}
+```
+
+### Styling structural elements (buttons, cells, rows)
+
+Beyond color tokens, every structural/interactive element the chart renders
+has a stable, undocumented-nowhere-else class name and **no inline styles
+and no `!important`** — so plain CSS targeting these classes has full
+control, same as any element you'd render yourself:
+
+| Class | What it is |
+|---|---|
+| `.gantt-toggle` | The expand/collapse button on a group row |
+| `.gantt-grid-header-cell` | A column header cell |
+| `.gantt-grid-cell` | A grid body cell |
+| `.gantt-grid-row` | A grid body row (has a default `:hover` background) |
+| `.gantt-rename-input` | The inline text input shown while renaming a task |
+| `.gantt-tooltip` | The floating hover tooltip's container (see "Hover tooltips" above) |
+| `.gantt-tooltip-title` / `.gantt-tooltip-row` / `.gantt-tooltip-notes` | Elements inside the *default* tooltip content — irrelevant if you use `renderTooltip` |
+
+For example, to make the expand/collapse toggle look like a small round
+button instead of bare text:
+
+```css
+.gantt-toggle {
+  border-radius: 999px;
+  padding: 2px 6px;
+  background: var(--gantt-grid-color, #e5e7eb);
+}
+.gantt-toggle:hover {
+  background: var(--gantt-bar-color, #3b82f6);
+  color: #fff;
+}
+```
+
+None of this is specific to the library's own chrome, either — anything
+*you* render, like the playground demo's toolbar (`apps/playground`,
+`apps/vue-playground`), is plain HTML/CSS in your own app code with no
+library involvement at all, so it's exactly as customizable as any other
+element on your page.
+
 ## API surface
 
 The full, current type/function list is re-exported from