construction-gantt 0.1.0

package/src/editing/draft-project.ts

@@ -0,0 +1,59 @@
+import type { Project } from '../types.js';
+import type { EditCommand } from './commands.js';
+import { CompositeCommand } from './composite-command.js';
+import { EditError } from './errors.js';
+
+/**
+ * Overlay over a committed Project. Pending commands are applied
+ * left-to-right to produce the `effective` Project that the renderer
+ * reads. Commit promotes pending into a single history entry; cancel
+ * discards them.
+ *
+ * Immutable value type — all operations return new instances.
+ */
+export interface DraftProject {
+  readonly base: Project;
+  readonly pending: ReadonlyArray<EditCommand>;
+  readonly effective: Project;
+  readonly isDirty: boolean;
+}
+
+export function newDraft(base: Project): DraftProject {
+  return { base, pending: [], effective: base, isDirty: false };
+}
+
+export function enqueue(draft: DraftProject, command: EditCommand): DraftProject {
+  const effective = command.apply(draft.effective);
+  return {
+    base: draft.base,
+    pending: [...draft.pending, command],
+    effective,
+    isDirty: true,
+  };
+}
+
+export interface CommitResult {
+  /** The new committed Project (becomes the next base). */
+  readonly newBase: Project;
+  /** Single command (if pending was 1) or CompositeCommand wrapping the pending list. */
+  readonly compound: EditCommand;
+}
+
+export function commit(draft: DraftProject, label: string = 'Edit'): CommitResult {
+  if (draft.pending.length === 0) {
+    throw new EditError('cannot commit an empty draft', 'commit');
+  }
+
+  const compound =
+    draft.pending.length === 1 ? draft.pending[0] : new CompositeCommand(draft.pending, label);
+
+  if (!compound) {
+    throw new EditError('unreachable: empty pending', 'commit');
+  }
+
+  return { newBase: draft.effective, compound };
+}
+
+export function cancel(draft: DraftProject): DraftProject {
+  return newDraft(draft.base);
+}

package/src/editing/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Thrown when an EditCommand's pre-conditions fail (e.g. target task
+ * doesn't exist, FS-link-to-self, malformed patch). Caught at the hook
+ * boundary so consumers see a typed error rather than a generic Error.
+ */
+export class EditError extends Error {
+  readonly commandKind: string;
+
+  constructor(message: string, commandKind: string) {
+    super(message);
+    this.name = 'EditError';
+    this.commandKind = commandKind;
+  }
+}

package/src/editing/factories.ts

@@ -0,0 +1,92 @@
+import type { DependencyType, Link, LinkId, Task, TaskId } from '../types.js';
+import {
+  CreateLinkCommand,
+  CreateTaskCommand,
+  DeleteLinkCommand,
+  DeleteTaskCommand,
+  type EditCommand,
+  UpdateLinkCommand,
+  UpdateTaskCommand,
+} from './commands.js';
+
+/**
+ * Ergonomic factory functions for constructing edit commands with
+ * descriptive labels. Consumers call these instead of `new
+ * UpdateTaskCommand(...)` so undo UI shows "Rename task to 'Foundation'"
+ * rather than the generic "Update task 'a' (text)".
+ */
+
+export function renameTask(id: TaskId, text: string): EditCommand {
+  return new UpdateTaskCommand(id, { text }, `Rename task to "${text}"`);
+}
+
+export function setTaskStart(id: TaskId, start: Date): EditCommand {
+  return new UpdateTaskCommand(id, { start }, `Move task "${String(id)}" (Start)`);
+}
+
+export function setTaskDuration(id: TaskId, minutes: number): EditCommand {
+  return new UpdateTaskCommand(
+    id,
+    { duration: minutes },
+    `Change duration of task "${String(id)}"`,
+  );
+}
+
+export function setTaskProgress(id: TaskId, percent: number): EditCommand {
+  return new UpdateTaskCommand(
+    id,
+    { progress: percent },
+    `Update progress of task "${String(id)}" to ${percent}%`,
+  );
+}
+
+export function updateTask(id: TaskId, patch: Partial<Task>): EditCommand {
+  return new UpdateTaskCommand(id, patch);
+}
+
+export function createTask(task: Task, _parent?: TaskId, _insertAfter?: TaskId): EditCommand {
+  // _parent and _insertAfter are accepted at the public surface but not
+  // wired into the underlying CreateTaskCommand in v0.4 foundation —
+  // hierarchy reordering and parent-changes are downstream concerns.
+  return new CreateTaskCommand(task);
+}
+
+export function deleteTask(id: TaskId): EditCommand {
+  return new DeleteTaskCommand(id);
+}
+
+/**
+ * Creates a CreateLinkCommand with a **deterministic** link id derived
+ * from `${source}->${target}`. This means calling `linkTasks('a', 'b')`
+ * twice produces the same id — and the second `apply()` will throw
+ * `EditError: duplicate link id`. By design: duplicate enqueues are a
+ * consumer bug we surface loudly rather than silently coalesce.
+ *
+ * Consumers who legitimately need to re-add a previously-deleted link
+ * (e.g. delete A→B, then re-create it without bringing the deleted one
+ * back via undo) should use `new CreateLinkCommand({ id: customId, … })`
+ * directly with a fresh id.
+ */
+export function linkTasks(
+  source: TaskId,
+  target: TaskId,
+  type: DependencyType = 'FS',
+  lag = 0,
+): EditCommand {
+  const link: Link = {
+    id: `${String(source)}->${String(target)}` as LinkId,
+    source,
+    target,
+    type,
+    lag,
+  };
+  return new CreateLinkCommand(link);
+}
+
+export function updateLink(id: LinkId, patch: Partial<Link>): EditCommand {
+  return new UpdateLinkCommand(id, patch);
+}
+
+export function deleteLink(id: LinkId): EditCommand {
+  return new DeleteLinkCommand(id);
+}

package/src/editing/use-editable-project.ts

@@ -0,0 +1,122 @@
+import { useMemo, useReducer, useRef } from 'react';
+import { schedule } from '../schedule.js';
+import type { Project } from '../types.js';
+import {
+  type CommandHistory,
+  redo as historyRedo,
+  undo as historyUndo,
+  newHistory,
+  pushCommand,
+} from './command-history.js';
+import type { EditCommand } from './commands.js';
+import {
+  type DraftProject,
+  cancel as draftCancel,
+  commit as draftCommit,
+  enqueue as draftEnqueue,
+  newDraft,
+} from './draft-project.js';
+
+/**
+ * Consumer-facing return shape. The renderer reads `project`
+ * unconditionally — it's always the scheduled, effective state.
+ */
+export interface EditableProject {
+  readonly project: Project;
+  readonly isDirty: boolean;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  enqueue(command: EditCommand): void;
+  commit(label?: string): void;
+  cancel(): void;
+  undo(): void;
+  redo(): void;
+}
+
+interface EditingState {
+  draft: DraftProject;
+  history: CommandHistory;
+}
+
+type EditingAction =
+  | { type: 'enqueue'; command: EditCommand }
+  | { type: 'commit'; label: string }
+  | { type: 'cancel' }
+  | { type: 'undo' }
+  | { type: 'redo' };
+
+function reducer(state: EditingState, action: EditingAction): EditingState {
+  switch (action.type) {
+    case 'enqueue':
+      return { ...state, draft: draftEnqueue(state.draft, action.command) };
+
+    case 'commit': {
+      if (state.draft.pending.length === 0) return state;
+      const { newBase, compound } = draftCommit(state.draft, action.label);
+      return {
+        draft: newDraft(newBase),
+        history: pushCommand(state.history, compound),
+      };
+    }
+
+    case 'cancel':
+      return { ...state, draft: draftCancel(state.draft) };
+
+    case 'undo': {
+      // If dirty, cancel pending first (matches VS Code / Figma).
+      const cleaned = state.draft.isDirty ? draftCancel(state.draft) : state.draft;
+      const result = historyUndo(state.history, cleaned.base);
+      if (!result) return { ...state, draft: cleaned };
+      return {
+        draft: newDraft(result.nextProject),
+        history: result.nextHistory,
+      };
+    }
+
+    case 'redo': {
+      const cleaned = state.draft.isDirty ? draftCancel(state.draft) : state.draft;
+      const result = historyRedo(state.history, cleaned.base);
+      if (!result) return { ...state, draft: cleaned };
+      return {
+        draft: newDraft(result.nextProject),
+        history: result.nextHistory,
+      };
+    }
+  }
+}
+
+/**
+ * The single hook entry point for v0.4 editing. Captures `initial` once
+ * on first mount (subsequent renders with a different `initial` are
+ * ignored — consumers reset by remounting via `key={projectId}`).
+ *
+ * Every effective state change is run through `schedule()` so the
+ * returned `project` always has fresh CPM data. Per ADR-005 (engine-first).
+ */
+export function useEditableProject(initial: Project): EditableProject {
+  // Capture initial once. useRef freezes the value across re-renders.
+  const initialRef = useRef(initial);
+
+  const [state, dispatch] = useReducer(
+    reducer,
+    undefined,
+    (): EditingState => ({
+      draft: newDraft(initialRef.current),
+      history: newHistory(),
+    }),
+  );
+
+  const scheduled = useMemo(() => schedule(state.draft.effective), [state.draft.effective]);
+
+  return {
+    project: scheduled,
+    isDirty: state.draft.isDirty,
+    canUndo: state.history.canUndo,
+    canRedo: state.history.canRedo,
+    enqueue: (command) => dispatch({ type: 'enqueue', command }),
+    commit: (label = 'Edit') => dispatch({ type: 'commit', label }),
+    cancel: () => dispatch({ type: 'cancel' }),
+    undo: () => dispatch({ type: 'undo' }),
+    redo: () => dispatch({ type: 'redo' }),
+  };
+}

package/src/export/index.ts

@@ -0,0 +1,12 @@
+// Subpath entry: construction-gantt/export
+// Re-exports types only. Implementation modules (xlsx.ts, png.ts, pdf.ts)
+// are lazy-imported from Gantt.tsx's handle methods so consumers who
+// never call an export method don't pay the bundle cost.
+
+export type {
+  GanttHandle,
+  PdfExportOptions,
+  PngExportOptions,
+  XlsxColumn,
+  XlsxExportOptions,
+} from './types.js';

package/src/export/offscreen.tsx

@@ -0,0 +1,89 @@
+// Mounts a second <Gantt> instance in a detached, off-screen container so
+// the export pipeline can snapshot the full project regardless of the
+// on-screen viewport's scroll position. Positioned far off-screen rather
+// than display:none because hidden containers don't compute layout, which
+// breaks DOM-to-image's bounding-rect reads.
+
+import { createRoot, type Root } from 'react-dom/client';
+import { Gantt, type GanttProps } from '../Gantt.js';
+import type { Project } from '../types.js';
+
+export type OffscreenGanttProps = Pick<
+  GanttProps,
+  | 'cellWidth'
+  | 'cellHeight'
+  | 'markers'
+  | 'baselineIndex'
+  | 'showBaselineBars'
+  | 'columns'
+  | 'height'
+  | 'visibleTaskIds'
+>;
+
+export interface OffscreenHandle {
+  /** The host DOM element. The rendered Gantt is mounted inside this. */
+  container: HTMLDivElement;
+  /** Unmount + remove the container from the DOM. */
+  dispose: () => Promise<void>;
+}
+
+export async function renderOffscreen(args: {
+  scheduled: Project;
+  ganttProps: OffscreenGanttProps;
+}): Promise<OffscreenHandle> {
+  const { scheduled, ganttProps } = args;
+
+  const container = document.createElement('div');
+  container.style.position = 'absolute';
+  container.style.left = '-99999px';
+  container.style.top = '0';
+  container.style.width = 'max-content';
+  container.style.background = '#ffffff';
+  document.body.appendChild(container);
+
+  const root: Root = createRoot(container);
+  root.render(
+    <Gantt
+      project={scheduled}
+      preScheduled
+      cellWidth={ganttProps.cellWidth}
+      cellHeight={ganttProps.cellHeight}
+      markers={ganttProps.markers}
+      baselineIndex={ganttProps.baselineIndex}
+      showBaselineBars={ganttProps.showBaselineBars}
+      columns={ganttProps.columns}
+      visibleTaskIds={ganttProps.visibleTaskIds}
+      height={computeFullHeight(scheduled, ganttProps.cellHeight ?? 42)}
+    />,
+  );
+
+  // Two animation frames + font load to give SVAR time to lay out and
+  // any custom fonts time to be ready before snapshot.
+  await waitForRender();
+
+  return {
+    container,
+    async dispose() {
+      root.unmount();
+      if (container.parentNode) {
+        container.parentNode.removeChild(container);
+      }
+    },
+  };
+}
+
+function computeFullHeight(project: Project, cellHeight: number): number {
+  // Header band + one row per task. Heuristic; the off-screen container's
+  // width:max-content + the height being a lower bound mean an underestimate
+  // is harmless — content expands rather than clipping.
+  return 80 + project.tasks.length * cellHeight;
+}
+
+async function waitForRender(): Promise<void> {
+  await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+  await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+  const fonts = (document as { fonts?: { ready?: Promise<unknown> } }).fonts;
+  if (fonts?.ready) {
+    await fonts.ready;
+  }
+}

package/src/export/pdf-dimensions.ts

@@ -0,0 +1,64 @@
+// Pure-function image-fit math. Used by the PDF exporter to scale the
+// captured PNG onto a chosen page format with a uniform margin while
+// preserving aspect ratio. Kept separate from pdf.ts so it can be
+// Vitest-covered without instantiating jsPDF.
+
+export interface PageDimensions {
+  /** Width in millimetres. */
+  width: number;
+  /** Height in millimetres. */
+  height: number;
+}
+
+export interface ImageFit {
+  /** Image render width in millimetres. */
+  width: number;
+  /** Image render height in millimetres. */
+  height: number;
+  /** Image origin X (from top-left) in millimetres. */
+  x: number;
+  /** Image origin Y (from top-left) in millimetres. */
+  y: number;
+}
+
+// Standard print dimensions (ISO 216 + ANSI Letter), in millimetres.
+export const PAGE_DIMENSIONS_MM: Record<
+  'a4' | 'a3' | 'letter',
+  { landscape: PageDimensions; portrait: PageDimensions }
+> = {
+  a4: {
+    portrait: { width: 210, height: 297 },
+    landscape: { width: 297, height: 210 },
+  },
+  a3: {
+    portrait: { width: 297, height: 420 },
+    landscape: { width: 420, height: 297 },
+  },
+  letter: {
+    portrait: { width: 215.9, height: 279.4 },
+    landscape: { width: 279.4, height: 215.9 },
+  },
+};
+
+export function computeImageFit(args: {
+  pageWidth: number;
+  pageHeight: number;
+  margin: number;
+  pngPxWidth: number;
+  pngPxHeight: number;
+}): ImageFit {
+  const { pageWidth, pageHeight, margin, pngPxWidth, pngPxHeight } = args;
+  const availableWidth = pageWidth - 2 * margin;
+  const availableHeight = pageHeight - 2 * margin;
+
+  const widthScale = availableWidth / pngPxWidth;
+  const heightScale = availableHeight / pngPxHeight;
+  const scale = Math.min(widthScale, heightScale);
+
+  const width = pngPxWidth * scale;
+  const height = pngPxHeight * scale;
+  const x = (pageWidth - width) / 2;
+  const y = (pageHeight - height) / 2;
+
+  return { width, height, x, y };
+}

package/src/export/pdf.ts

@@ -0,0 +1,68 @@
+import { jsPDF } from 'jspdf';
+import type { GanttProps } from '../Gantt.js';
+import type { Project } from '../types.js';
+import { computeImageFit, PAGE_DIMENSIONS_MM } from './pdf-dimensions.js';
+import { exportPNG } from './png.js';
+import type { PdfExportOptions } from './types.js';
+
+export async function exportPDF(args: {
+  scheduled: Project;
+  ganttProps: Pick<
+    GanttProps,
+    | 'cellWidth'
+    | 'cellHeight'
+    | 'markers'
+    | 'baselineIndex'
+    | 'showBaselineBars'
+    | 'columns'
+    | 'height'
+    | 'visibleTaskIds'
+  >;
+  options: PdfExportOptions;
+}): Promise<Blob> {
+  const { scheduled, ganttProps, options } = args;
+  const orientation = options.orientation ?? 'landscape';
+  const format = options.format ?? 'a3';
+  const margin = options.margin ?? 10;
+  const backgroundColor = options.backgroundColor ?? '#ffffff';
+
+  const pngBlob = await exportPNG({
+    scheduled,
+    ganttProps,
+    options: { backgroundColor },
+  });
+
+  const dataUrl = await blobToDataUrl(pngBlob);
+  const { width: pngPxWidth, height: pngPxHeight } = await probeImageDimensions(dataUrl);
+
+  const page = PAGE_DIMENSIONS_MM[format][orientation];
+  const fit = computeImageFit({
+    pageWidth: page.width,
+    pageHeight: page.height,
+    margin,
+    pngPxWidth,
+    pngPxHeight,
+  });
+
+  const pdf = new jsPDF({ orientation, unit: 'mm', format });
+  pdf.addImage(dataUrl, 'PNG', fit.x, fit.y, fit.width, fit.height);
+  return pdf.output('blob');
+}
+
+function blobToDataUrl(blob: Blob): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error ?? new Error('FileReader failed'));
+    reader.readAsDataURL(blob);
+  });
+}
+
+function probeImageDimensions(dataUrl: string): Promise<{ width: number; height: number }> {
+  return new Promise((resolve, reject) => {
+    const img = new Image();
+    img.onload = () => resolve({ width: img.width, height: img.height });
+    img.onerror = () => reject(new Error('Failed to probe PNG dimensions'));
+    img.src = dataUrl;
+  });
+}

package/src/export/png.ts

@@ -0,0 +1,48 @@
+import { toBlob } from 'html-to-image';
+import type { GanttProps } from '../Gantt.js';
+import type { Project } from '../types.js';
+import { type OffscreenGanttProps, renderOffscreen } from './offscreen.js';
+import type { PngExportOptions } from './types.js';
+
+export async function exportPNG(args: {
+  scheduled: Project;
+  ganttProps: Pick<
+    GanttProps,
+    | 'cellWidth'
+    | 'cellHeight'
+    | 'markers'
+    | 'baselineIndex'
+    | 'showBaselineBars'
+    | 'columns'
+    | 'height'
+    | 'visibleTaskIds'
+  >;
+  options: PngExportOptions;
+}): Promise<Blob> {
+  const { scheduled, ganttProps, options } = args;
+
+  const pixelRatio =
+    options.pixelRatio ??
+    (typeof window !== 'undefined' && window.devicePixelRatio ? window.devicePixelRatio : 2);
+  const backgroundColor = options.backgroundColor ?? '#ffffff';
+
+  const offscreen = await renderOffscreen({
+    scheduled,
+    ganttProps: ganttProps as OffscreenGanttProps,
+  });
+
+  try {
+    const blob = await toBlob(offscreen.container, {
+      backgroundColor,
+      pixelRatio,
+      cacheBust: true,
+    });
+
+    if (!blob) {
+      throw new Error('exportPNG: html-to-image returned null');
+    }
+    return blob;
+  } finally {
+    await offscreen.dispose();
+  }
+}

package/src/export/types.ts

@@ -0,0 +1,42 @@
+// Public types for the construction-gantt/export subpath.
+// Imported by the core <Gantt> for its ref handle, and re-exported
+// from the subpath entry for direct consumer use.
+
+import type { Task } from '../types.js';
+
+export interface PngExportOptions {
+  /** Background colour for the captured canvas. Defaults to '#ffffff'. */
+  backgroundColor?: string;
+  /** Pixel ratio. Defaults to window.devicePixelRatio || 2. */
+  pixelRatio?: number;
+}
+
+export interface PdfExportOptions {
+  /** Page orientation. Defaults to 'landscape' (Gantt charts are wide). */
+  orientation?: 'landscape' | 'portrait';
+  /** Page size. Defaults to 'a3'. */
+  format?: 'a4' | 'a3' | 'letter';
+  /** Margin in mm. Defaults to 10. */
+  margin?: number;
+  /** Background colour for the underlying PNG. Defaults to '#ffffff'. */
+  backgroundColor?: string;
+}
+
+export interface XlsxColumn {
+  header: string;
+  /** A key on Task, or a function returning the cell value. */
+  value: keyof Task | ((task: Task) => string | number | Date | undefined);
+}
+
+export interface XlsxExportOptions {
+  /** Sheet name. Defaults to 'Programme'. */
+  sheetName?: string;
+  /** Override the default column set. */
+  columns?: XlsxColumn[];
+}
+
+export interface GanttHandle {
+  exportPNG(options?: PngExportOptions): Promise<Blob>;
+  exportPDF(options?: PdfExportOptions): Promise<Blob>;
+  exportXLSX(options?: XlsxExportOptions): Promise<Blob>;
+}

package/src/export/xlsx.ts

@@ -0,0 +1,70 @@
+import * as XLSX from 'xlsx';
+import type { Project, Task } from '../types.js';
+import type { XlsxColumn, XlsxExportOptions } from './types.js';
+
+export type SheetCell = string | number | Date;
+export type SheetRow = SheetCell[];
+
+export const DEFAULT_XLSX_COLUMNS: XlsxColumn[] = [
+  { header: 'ID', value: 'id' },
+  { header: 'Name', value: 'text' },
+  { header: 'Start', value: 'start' },
+  { header: 'End', value: 'end' },
+  { header: 'Duration (working minutes)', value: 'duration' },
+  {
+    header: 'Critical',
+    value: (t: Task) => (t.computed?.isCritical ? 'Y' : 'N'),
+  },
+  {
+    header: 'Total slack (working minutes)',
+    value: (t: Task) => t.computed?.totalSlack ?? 0,
+  },
+  { header: 'Progress (%)', value: 'progress' },
+  {
+    header: 'Parent',
+    value: (t: Task) => t.parent ?? '',
+  },
+];
+
+export function buildSheetRows(project: Project, columns: XlsxColumn[]): SheetRow[] {
+  const header: SheetRow = columns.map((c) => c.header);
+  const dataRows: SheetRow[] = project.tasks.map((task) => columns.map((c) => readCell(task, c)));
+  return [header, ...dataRows];
+}
+
+function readCell(task: Task, column: XlsxColumn): SheetCell {
+  if (typeof column.value === 'function') {
+    const raw = column.value(task);
+    return raw ?? '';
+  }
+  const raw = task[column.value];
+  if (raw === undefined || raw === null) return '';
+  if (raw instanceof Date) return raw;
+  if (typeof raw === 'number' || typeof raw === 'string') return raw;
+  return String(raw);
+}
+
+export async function exportXLSX({
+  scheduled,
+  options,
+}: {
+  scheduled: Project;
+  options: XlsxExportOptions;
+}): Promise<Blob> {
+  const columns = options.columns ?? DEFAULT_XLSX_COLUMNS;
+  const sheetName = options.sheetName ?? 'Programme';
+
+  const rows = buildSheetRows(scheduled, columns);
+  const sheet = XLSX.utils.aoa_to_sheet(rows, { cellDates: true });
+  const workbook = XLSX.utils.book_new();
+  XLSX.utils.book_append_sheet(workbook, sheet, sheetName);
+
+  const arrayBuffer = XLSX.write(workbook, {
+    type: 'array',
+    bookType: 'xlsx',
+  }) as ArrayBuffer;
+
+  return new Blob([arrayBuffer], {
+    type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  });
+}