construction-gantt 0.1.0

package/src/Gantt.css

@@ -0,0 +1,23 @@
+/* Non-working day shading on the time scale.
+ * Applied to cells where the calendar has no working intervals for the
+ * given date (weekends + holiday exceptions). Construction PMs expect
+ * to see at a glance which days the crew is on site. */
+.construction-gantt-non-working {
+  background: rgba(241, 245, 249, 0.65);
+}
+
+/* Today-line marker. Red 2px vertical line; high-priority visual cue for
+ * what the date cursor is on. */
+.construction-gantt-marker-today {
+  background: #ef4444;
+  color: #ffffff;
+  font-weight: 600;
+}
+
+/* Generic milestone marker (council inspections, payment-claim dates,
+ * handover gates). Blue, less aggressive than today. */
+.construction-gantt-marker-milestone {
+  background: #2563eb;
+  color: #ffffff;
+  font-weight: 500;
+}

package/src/Gantt.tsx

@@ -0,0 +1,636 @@
+// The real <Gantt>. Consumes a Project, runs the scheduling engine, converts
+// our SVAR-agnostic data model to SVAR's ITask/ILink, renders through
+// SVAR's free-tier React component per ADR-002 (shape-c slot composition).
+//
+// Public API surface stays SVAR-agnostic: consumers pass a Project; SVAR
+// is a private implementation detail. If we ever swap renderers (per
+// ADR-002's seam), this file is the only consumer-facing change.
+
+import {
+  type IColumnConfig,
+  type ILink,
+  type ITask,
+  Gantt as SvarGantt,
+} from '@svar-ui/react-gantt';
+import '@svar-ui/react-gantt/style.css';
+import './Gantt.css';
+import { type FC, forwardRef, useImperativeHandle, useMemo, useRef } from 'react';
+import { getTaskBaselineVariance } from './baseline';
+import type {
+  GanttHandle,
+  PdfExportOptions,
+  PngExportOptions,
+  XlsxExportOptions,
+} from './export/types.js';
+import { schedule } from './schedule';
+import type {
+  Baseline,
+  BaselineIndex,
+  Calendar,
+  DependencyType,
+  Link,
+  Project,
+  Task,
+  TaskId,
+} from './types';
+import { filterTasksByVisibility } from './visibility.js';
+import { isWorkingDay } from './working-time';
+
+export interface GanttMarker {
+  start: Date;
+  text?: string;
+  /**
+   * Visual style. 'today' renders as a red line; 'milestone' as blue;
+   * 'custom' lets you supply a `css` class name yourself.
+   */
+  variant?: 'today' | 'milestone' | 'custom';
+  /** CSS class name when `variant: 'custom'`. */
+  css?: string;
+}
+
+/**
+ * Defines a column in the left-hand grid of the Gantt chart.
+ * Construction-PM-facing: these are the columns site PMs expect alongside
+ * the task name (WBS code, trade package, assigned subcontractor, etc.).
+ *
+ * This is a SVAR-agnostic type — internal conversion to SVAR's IColumnConfig
+ * happens inside the <Gantt> wrapper.
+ */
+export interface GanttColumn<TTask = Task> {
+  /** Identifier; used as SVAR column id. */
+  id: string;
+  /** Header label rendered in the column header row. */
+  header: string;
+  /**
+   * The field on the task to pluck for the default cell render.
+   * Optional — if `render` is provided, this is ignored.
+   */
+  field?: keyof TTask;
+  /** Column width in pixels. Defaults to SVAR's default if unset. */
+  width?: number;
+  /** Text alignment for the cell. */
+  align?: 'left' | 'center' | 'right';
+  /**
+   * Custom cell render. Receives the live (scheduled) task. Use for any
+   * column more complex than displaying a single field value.
+   */
+  render?: FC<{ task: Task }>;
+}
+
+export interface GanttProps {
+  project: Project;
+  /** Container height. Defaults to 500 (px). */
+  height?: number | string;
+  /** Width of one time-scale cell (per `cellWidth` SVAR prop). Default 48. */
+  cellWidth?: number;
+  /** Height of one row. */
+  cellHeight?: number;
+  /**
+   * Skip running the scheduling engine. Use when the project's tasks
+   * already have `computed` populated by a prior `schedule()` call.
+   */
+  preScheduled?: boolean;
+  /**
+   * Vertical markers (today line + arbitrary milestones).
+   * Default: a today line if the current date falls within the project
+   * window. Pass an empty array to suppress, or your own markers list to
+   * override.
+   */
+  markers?: GanttMarker[];
+  /**
+   * Show variance against this baseline index. If unset (or no matching
+   * baseline exists on `project.baselines`), bars render without variance
+   * pills. Construction-vertical use case (ADR-003): comparing the live
+   * programme against the original contract programme captured under
+   * NZS 3910 / AS 4000.
+   */
+  baselineIndex?: BaselineIndex;
+  /**
+   * Render the baseline as a separate "ghost" bar beneath each live task.
+   * Matches the MS Project baseline-view idiom construction PMs expect
+   * when reviewing variation claims. Default true when `baselineIndex`
+   * is set; pass `false` to keep variance shown only as in-bar pills.
+   */
+  showBaselineBars?: boolean;
+  /**
+   * Grid columns displayed alongside the Gantt bars.
+   *
+   * - `undefined` (default): SVAR renders its built-in columns (task name +
+   *   duration + start + end).
+   * - `[]` (empty array): hides the grid entirely (passes `columns={false}`
+   *   to SVAR).
+   * - `GanttColumn[]`: replaces SVAR's default columns with the supplied set.
+   *
+   * Construction-PM-facing columns live here: WBS code, trade package,
+   * assigned subcontractor, and similar project-specific fields.
+   */
+  columns?: GanttColumn[];
+  /**
+   * Render-only visibility filter. When set, only tasks whose `id` is in
+   * the set are rendered. **CPM still runs on the full task set** — hidden
+   * predecessors continue to drive their visible successors' computed
+   * fields. The visibility filter is a render-only concern (ADR-005).
+   *
+   * - `undefined` (default): no filter; render everything.
+   * - empty set: render nothing.
+   * - set containing ids not present in `project.tasks`: those ids are
+   *   ignored; only matching tasks render.
+   *
+   * Lifts the "filter-while-keeping-CPM-correct" domain rule that
+   * consumer apps would otherwise have to write themselves. See
+   * `visibility.ts` for the contract test.
+   */
+  visibleTaskIds?: ReadonlySet<TaskId>;
+}
+
+interface SvarTaskWithComputed extends ITask {
+  is_critical?: boolean;
+  is_late?: boolean;
+  total_slack?: number;
+  /** Working-minutes by which start has slipped against the baseline. */
+  start_variance?: number;
+  /** True if startVariance >= 30 working minutes (drifted later than plan). */
+  is_slipped?: boolean;
+  /** True if startVariance <= -30 working minutes (ahead of plan). */
+  is_ahead?: boolean;
+  /** True for phantom rows representing a baseline snapshot's position. */
+  is_baseline_ghost?: boolean;
+}
+
+interface SvarMarker {
+  start: Date;
+  text?: string;
+  css?: string;
+}
+
+export const Gantt = forwardRef<GanttHandle, GanttProps>(function Gantt(
+  {
+    project,
+    height = 500,
+    cellWidth = 48,
+    cellHeight = 42,
+    preScheduled = false,
+    markers,
+    baselineIndex,
+    showBaselineBars,
+    columns,
+    visibleTaskIds,
+  },
+  ref,
+) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const scheduled = useMemo(
+    () => (preScheduled ? project : schedule(project)),
+    [project, preScheduled],
+  );
+
+  // Visibility filter is render-only — applied AFTER schedule() has run so
+  // computed fields on visible tasks reflect the full project. ADR-005.
+  const renderableTasks = useMemo(
+    () => filterTasksByVisibility(scheduled.tasks, visibleTaskIds),
+    [scheduled.tasks, visibleTaskIds],
+  );
+
+  const calendar = useMemo(
+    () => scheduled.calendars.find((c) => c.id === scheduled.defaultCalendarId),
+    [scheduled.calendars, scheduled.defaultCalendarId],
+  );
+
+  const baseline = useMemo<Baseline | undefined>(() => {
+    if (baselineIndex === undefined) return undefined;
+    return scheduled.baselines.find((b) => b.index === baselineIndex);
+  }, [scheduled.baselines, baselineIndex]);
+
+  const ghostBarsEnabled = baseline !== undefined && (showBaselineBars ?? true);
+
+  const svarTasks: ITask[] = useMemo(() => {
+    if (!ghostBarsEnabled || !baseline) {
+      return renderableTasks.map((t) => toSvarTask(t, baseline, calendar));
+    }
+    // Interleave each real task with its baseline-snapshot ghost row.
+    // Phantoms share the real task's `parent` so they stay grouped under
+    // the same summary in hierarchy views.
+    const out: SvarTaskWithComputed[] = [];
+    for (const t of renderableTasks) {
+      out.push(toSvarTask(t, baseline, calendar));
+      if (t.type === 'summary') continue;
+      const phantom = makeBaselinePhantom(t, baseline);
+      if (phantom) out.push(phantom);
+    }
+    return out;
+  }, [renderableTasks, baseline, calendar, ghostBarsEnabled]);
+  const svarLinks: ILink[] = useMemo(() => scheduled.links.map(toSvarLink), [scheduled.links]);
+
+  const projectEnd = useMemo(() => getProjectEnd(scheduled), [scheduled]);
+  // Mark calendar referenced even when consumed only by useMemo args (TS unused-let guard)
+  void calendar;
+
+  const svarMarkers: SvarMarker[] = useMemo(
+    () => resolveMarkers(markers, scheduled.start, projectEnd),
+    [markers, scheduled.start, projectEnd],
+  );
+
+  const highlightTime = useMemo(() => buildHighlightTime(calendar), [calendar]);
+
+  // Convert our SVAR-agnostic GanttColumn[] to SVAR's IColumnConfig[].
+  // undefined → don't pass columns to SVAR (use SVAR defaults).
+  // [] → pass false to SVAR (hide grid entirely).
+  // [...] → convert each column.
+  const svarColumns: IColumnConfig[] | false | undefined = useMemo(() => {
+    if (columns === undefined) return undefined;
+    if (columns.length === 0) return false;
+    return columns.map(toSvarColumn);
+  }, [columns]);
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      async exportPNG(options?: PngExportOptions): Promise<Blob> {
+        const { exportPNG } = await import('./export/png.js');
+        return exportPNG({
+          scheduled,
+          ganttProps: {
+            cellWidth,
+            cellHeight,
+            markers,
+            baselineIndex,
+            showBaselineBars,
+            columns,
+            height,
+            visibleTaskIds,
+          },
+          options: options ?? {},
+        });
+      },
+      async exportPDF(options?: PdfExportOptions): Promise<Blob> {
+        const { exportPDF } = await import('./export/pdf.js');
+        return exportPDF({
+          scheduled,
+          ganttProps: {
+            cellWidth,
+            cellHeight,
+            markers,
+            baselineIndex,
+            showBaselineBars,
+            columns,
+            height,
+            visibleTaskIds,
+          },
+          options: options ?? {},
+        });
+      },
+      async exportXLSX(options?: XlsxExportOptions): Promise<Blob> {
+        const { exportXLSX } = await import('./export/xlsx.js');
+        return exportXLSX({ scheduled, options: options ?? {} });
+      },
+    }),
+    [
+      scheduled,
+      cellWidth,
+      cellHeight,
+      markers,
+      baselineIndex,
+      showBaselineBars,
+      columns,
+      height,
+      visibleTaskIds,
+    ],
+  );
+
+  return (
+    <div ref={containerRef} style={{ height }}>
+      <SvarGantt
+        tasks={svarTasks}
+        links={svarLinks}
+        start={scheduled.start}
+        end={projectEnd}
+        cellWidth={cellWidth}
+        cellHeight={cellHeight}
+        markers={svarMarkers}
+        highlightTime={highlightTime}
+        taskTemplate={ConstructionBar}
+        {...(svarColumns !== undefined ? { columns: svarColumns as IColumnConfig[] } : {})}
+      />
+    </div>
+  );
+});
+
+const ConstructionBar: FC<{ data: SvarTaskWithComputed }> = ({ data }) => {
+  // Phantom baseline row — render a slim outlined ghost bar.
+  if (data.is_baseline_ghost) {
+    return (
+      <div
+        style={{
+          height: '60%',
+          marginTop: '15%',
+          border: '1.5px dashed #94a3b8',
+          background: 'transparent',
+          borderRadius: 3,
+          fontSize: 9,
+          color: '#64748b',
+          display: 'flex',
+          alignItems: 'center',
+          padding: '0 6px',
+          fontStyle: 'italic',
+          whiteSpace: 'nowrap',
+        }}
+        title="Baseline position — where this task was when the baseline was captured"
+      >
+        baseline
+      </div>
+    );
+  }
+
+  const isCritical = data.is_critical ?? false;
+  const isLate = data.is_late ?? false;
+  const isSummary = data.type === 'summary';
+  const isMilestone = data.type === 'milestone';
+
+  if (isMilestone) {
+    return (
+      <div
+        style={{
+          width: '100%',
+          height: '100%',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'center',
+          color: isCritical ? '#fff' : '#1f2937',
+          fontWeight: 600,
+          fontSize: 11,
+        }}
+      >
+        ◆ {data.text}
+      </div>
+    );
+  }
+
+  const isSlipped = data.is_slipped ?? false;
+  const isAhead = data.is_ahead ?? false;
+  // Show slack indicator for non-critical, non-summary, non-milestone tasks
+  // with at least half a working day of total float. Skips the noise of "+5m"
+  // pills on the visually-critical path tasks.
+  const totalSlack = data.total_slack ?? 0;
+  const showSlackIndicator = !isSummary && !isCritical && totalSlack >= 270; // >= 30 min more than half a day
+
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 6,
+        height: '100%',
+        padding: '0 8px',
+        fontSize: 12,
+        fontWeight: isSummary ? 600 : 500,
+        color: isCritical ? '#fff' : '#1f2937',
+        background: isSummary ? 'transparent' : isCritical ? '#dc2626' : '#cbd5e1',
+        borderRadius: 4,
+        border: isSummary ? '2px solid #1e293b' : undefined,
+      }}
+    >
+      <span style={{ flex: 1, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+        {data.text}
+      </span>
+      {isSlipped && (
+        <span
+          style={{
+            padding: '0 6px',
+            background: '#fed7aa',
+            color: '#7c2d12',
+            borderRadius: 3,
+            fontSize: 10,
+            fontWeight: 700,
+            lineHeight: '16px',
+            whiteSpace: 'nowrap',
+          }}
+          title="Drifted later than the baseline"
+        >
+          +{workingMinutesToShortLabel(data.start_variance ?? 0)}
+        </span>
+      )}
+      {isAhead && (
+        <span
+          style={{
+            padding: '0 6px',
+            background: '#bbf7d0',
+            color: '#14532d',
+            borderRadius: 3,
+            fontSize: 10,
+            fontWeight: 700,
+            lineHeight: '16px',
+            whiteSpace: 'nowrap',
+          }}
+          title="Ahead of the baseline"
+        >
+          −{workingMinutesToShortLabel(data.start_variance ?? 0)}
+        </span>
+      )}
+      {showSlackIndicator && (
+        <span
+          style={{
+            padding: '0 6px',
+            background: '#dbeafe',
+            color: '#1e3a8a',
+            borderRadius: 3,
+            fontSize: 10,
+            fontWeight: 600,
+            lineHeight: '16px',
+            whiteSpace: 'nowrap',
+          }}
+          title="Total float — how much this task can slip before becoming critical"
+        >
+          {workingMinutesToShortLabel(totalSlack)} float
+        </span>
+      )}
+      {isLate && (
+        <span
+          style={{
+            padding: '0 6px',
+            background: '#fde68a',
+            color: '#78350f',
+            borderRadius: 3,
+            fontSize: 10,
+            fontWeight: 700,
+            lineHeight: '16px',
+            whiteSpace: 'nowrap',
+          }}
+          title="Negative slack — contract trouble"
+        >
+          {workingMinutesToShortLabel(data.total_slack ?? 0)} late
+        </span>
+      )}
+    </div>
+  );
+};
+
+function toSvarTask(
+  t: Task,
+  baseline: Baseline | undefined,
+  calendar: Calendar | undefined,
+): SvarTaskWithComputed {
+  const variance =
+    baseline && calendar ? getTaskBaselineVariance(t, baseline, calendar) : undefined;
+  const startVariance = variance?.startVariance ?? 0;
+
+  const base: SvarTaskWithComputed = {
+    id: t.id,
+    text: t.text,
+    start: t.start,
+    end: t.end,
+    duration: t.duration,
+    progress: t.progress,
+    type: t.type,
+    parent: t.parent,
+    is_critical: t.computed?.isCritical ?? false,
+    is_late: (t.computed?.totalSlack ?? 0) < 0,
+    total_slack: t.computed?.totalSlack ?? 0,
+    start_variance: startVariance,
+    is_slipped: startVariance >= 30,
+    is_ahead: startVariance <= -30,
+  };
+  // `open` only meaningful on summary tasks. Setting it on leaves trips
+  // SVAR's child-iteration path (null forEach).
+  if (t.type === 'summary') base.open = t.open ?? true;
+  return base;
+}
+
+function makeBaselinePhantom(t: Task, baseline: Baseline): SvarTaskWithComputed | null {
+  const snap = baseline.tasks.get(t.id);
+  if (!snap) return null;
+  return {
+    id: `${t.id}-baseline-${baseline.index}`,
+    text: '(baseline)',
+    start: snap.start,
+    end: snap.end,
+    duration: snap.duration,
+    progress: 0,
+    type: 'task',
+    parent: t.parent,
+    is_baseline_ghost: true,
+  };
+}
+
+function toSvarLink(l: Link): ILink {
+  return {
+    id: l.id,
+    source: l.source,
+    target: l.target,
+    type: dependencyTypeToSvar(l.type),
+    lag: l.lag,
+  };
+}
+
+function dependencyTypeToSvar(t: DependencyType): ILink['type'] {
+  switch (t) {
+    case 'FS':
+      return 'e2s';
+    case 'SS':
+      return 's2s';
+    case 'FF':
+      return 'e2e';
+    case 'SF':
+      return 's2e';
+  }
+}
+
+function getProjectEnd(p: Project): Date {
+  if (p.end) return p.end;
+  let latestMs = Number.NEGATIVE_INFINITY;
+  for (const t of p.tasks) {
+    if (t.end.getTime() > latestMs) latestMs = t.end.getTime();
+  }
+  // Pad by one cell so the last bar isn't clipped to the right edge.
+  const cushion = 24 * 60 * 60 * 1000; // 1 day
+  return Number.isFinite(latestMs) ? new Date(latestMs + cushion) : new Date(p.start);
+}
+
+function resolveMarkers(
+  userMarkers: GanttMarker[] | undefined,
+  projectStart: Date,
+  projectEnd: Date,
+): SvarMarker[] {
+  if (userMarkers) return userMarkers.map(toSvarMarker);
+  // Default: today line, only if today falls within the project window.
+  const today = new Date();
+  if (today >= projectStart && today <= projectEnd) {
+    return [{ start: today, text: 'Today', css: 'construction-gantt-marker-today' }];
+  }
+  return [];
+}
+
+function toSvarMarker(m: GanttMarker): SvarMarker {
+  const css =
+    m.css ??
+    (m.variant === 'milestone'
+      ? 'construction-gantt-marker-milestone'
+      : m.variant === 'today'
+        ? 'construction-gantt-marker-today'
+        : undefined);
+  return { start: m.start, text: m.text, css };
+}
+
+/**
+ * Convert a public GanttColumn to SVAR's IColumnConfig.
+ *
+ * render takes priority over field. When only field is set we emit a default
+ * cell that formats the value as a string (Date → ISO date, undefined → "").
+ * We cast row to our Task type directly — the relevant fields (id, text,
+ * start, end, duration, progress, type, parent, computed, constraint)
+ * all overlap. SVAR's internal $x/$y/$w computed fields are never passed
+ * through to the consumer's render prop.
+ */
+function toSvarColumn(c: GanttColumn): IColumnConfig {
+  let cell: IColumnConfig['cell'] | undefined;
+
+  if (c.render) {
+    const Render = c.render;
+    cell = (props: { row: unknown }) => <Render task={props.row as Task} />;
+  } else if (c.field) {
+    const field = c.field;
+    cell = (props: { row: unknown }) => {
+      const task = props.row as Task;
+      const value = task[field as keyof Task];
+      if (value === undefined || value === null) return <span />;
+      if (value instanceof Date) return <span>{value.toISOString().slice(0, 10)}</span>;
+      return <span>{String(value)}</span>;
+    };
+  }
+
+  const config: IColumnConfig = {
+    id: c.id,
+    header: c.header,
+    ...(c.width !== undefined ? { width: c.width } : {}),
+    ...(c.align !== undefined ? { align: c.align } : {}),
+    ...(cell !== undefined ? { cell } : {}),
+  };
+  return config;
+}
+
+function buildHighlightTime(
+  calendar: Calendar | undefined,
+): ((date: Date, unit: 'day' | 'hour') => string) | undefined {
+  if (!calendar) return undefined;
+  return (date, unit) => {
+    if (unit !== 'day') return '';
+    if (!isWorkingDay(date, calendar)) return 'construction-gantt-non-working';
+    return '';
+  };
+}
+
+function workingMinutesToShortLabel(minutes: number): string {
+  const abs = Math.abs(minutes);
+  if (abs >= 540) {
+    // Approximate working-days from 9h-per-day. Display is "best-effort"
+    // since real durations depend on each task's calendar — good enough
+    // for an in-bar pill.
+    const days = Math.round(abs / 540);
+    return `${days}d`;
+  }
+  if (abs >= 60) {
+    const hours = Math.round(abs / 60);
+    return `${hours}h`;
+  }
+  return `${Math.round(abs)}m`;
+}