construction-gantt 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# construction-gantt
+
+## 0.1.0
+
+### Minor Changes
+
+- First public release. Ships the v0.1 scheduling engine, v0.2 MSPDI XML interop, v0.3 NZ public holidays pre-seed, and v0.4 editing-model foundation under one MIT-licensed package on npm.
+
+  ## What's in 0.1.0
+
+  ### Scheduling engine (v0.1)
+
+  - Forward + backward CPM pass with multi-path critical-path detection.
+  - All 8 MS Project constraint types (ASAP, ALAP, MSO, MFO, SNET, SNLT, FNET, FNLT).
+  - First-class negative slack (the contract-trouble signal every existing alternative clips to zero).
+  - Manual-vs-auto schedule mode per task; summary-task aggregation as `max(child finish) − min(child start)`.
+  - Working-time calendars with partial-day shifts and per-date exceptions.
+  - Multi-baseline data model — up to 11 baselines matching MS Project's `Baseline 0–10`.
+  - Public `<Gantt>` component rendering via free SVAR React Gantt; engine runs internally.
+  - Custom columns (`GanttColumn[]`) for project-specific fields.
+  - Today line + milestone markers; weekend/holiday shading; hierarchy collapse/expand.
+  - Render-only visibility filter (`visibleTaskIds`) — CPM stays correct when consumers hide tasks (ADR-005).
+
+  ### Exports (v0.1)
+
+  - `exportPNG / exportPDF / exportXLSX` via imperative ref handle.
+  - Full-project render regardless of on-screen scroll position.
+  - Behind `construction-gantt/export` subpath with lazy-imported deps (consumers who never call exports pay zero bundle cost).
+
+  ### MSPDI XML interop (v0.2)
+
+  - Pure-TS round-trip of `parseMspdi` / `serializeMspdi`.
+  - Covers Tasks + PredecessorLinks (all 4 dependency types, lag in tenths-of-a-minute), Calendars (workWeek with split shifts + exceptions), Resources (UID/Name/CalendarUID), Assignments (taskId/resourceId/units), and Baselines (per-task `<Baseline>` Number=0..10).
+  - `parseMspdi` returns `{ project, droppedFields }` — unknown elements never silently drop.
+
+  ### NZ public holidays (v0.3)
+
+  - `nzPublicHolidays(years, region)` returns `CalendarException[]` for all 13 statutory NZ regions, years 2022–2052.
+  - `nzDefaultCalendar({ years, region })` for a one-call working calendar.
+  - Matariki dates from Te Kāhui o Matariki Public Holiday Act 2022; Canterbury Show Day from employment.govt.nz year-by-year (range bounded by published years).
+
+  ### Editing model (v0.4 foundation — ADR-006)
+
+  - `useEditableProject(initial)` React hook with `enqueue / commit / cancel / undo / redo / canUndo / canRedo / isDirty`.
+  - Typed `EditCommand` interface + 6 concrete commands (Create/Update/Delete × Task/Link) + `CompositeCommand` wrapper.
+  - Ten ergonomic factories: `renameTask`, `setTaskStart`, `setTaskDuration`, `setTaskProgress`, `updateTask`, `createTask`, `deleteTask`, `linkTasks`, `updateLink`, `deleteLink`.
+  - Project-level draft overlay; single-stack undo with compound commits on draft commit.
+  - Engine recomputes (`schedule()`) on every effective state change — ADR-005 engine-first invariant preserved.
+  - UX patterns (inline-row vs modal vs drag-handle) are consumer choice — the hook is UI-agnostic.
+
+  ## License
+
+  MIT through v1.0 per ADR-004. Past releases stay MIT forever; future commercial-tier optionality reserved for v1.0+.
+
+  ## Status
+
+  292 Vitest tests, all passing. Foundational ADRs locked (ADR-001 through ADR-006). See `ROADMAP.md` for what's still pending (partial-day calendars UI, weather buffer widget, MSPDI Primavera P6 stretch, v0.4 editing-model UX patterns).

package/README.md

@@ -0,0 +1,5 @@
+# construction-gantt
+
+MIT-licensed React Gantt component for construction project management, with a real scheduling engine and MS Project-compatible data interchange.
+
+For the full story — positioning, feature list, and roadmap — see the [repository root README](../../README.md) and [DECISIONS.md](../../DECISIONS.md).

package/dist/export/index.cjs

@@ -0,0 +1 @@
+

package/dist/export/index.d.cts

@@ -0,0 +1,112 @@
+type TaskId = string | number;
+type ResourceId = string | number;
+type CalendarId = string | number;
+type TaskType = 'task' | 'summary' | 'milestone';
+type ScheduleMode = 'auto' | 'manual';
+/**
+ * MS Project's 8 constraint types.
+ *
+ * - ASAP / ALAP: scheduling preferences, no date required.
+ * - MSO / MFO:   hard constraints, pin the date; override predecessor logic.
+ * - SNET / SNLT / FNET / FNLT: soft date bounds.
+ *
+ * Hard constraints can produce negative slack — the contract-trouble
+ * signal we surface rather than silently clip to zero (ADR-003).
+ */
+type ConstraintType = 'ASAP' | 'ALAP' | 'MSO' | 'MFO' | 'SNET' | 'SNLT' | 'FNET' | 'FNLT';
+interface Constraint {
+    type: ConstraintType;
+    /** Required for all types except ASAP and ALAP. */
+    date?: Date;
+}
+interface Task {
+    id: TaskId;
+    text: string;
+    /** Hierarchy parent. Undefined = top-level. */
+    parent?: TaskId;
+    type: TaskType;
+    scheduleMode: ScheduleMode;
+    /**
+     * For summary tasks: are children currently expanded?
+     * Default true (expanded). Toggled by the user via the renderer's
+     * collapse/expand chevron.
+     */
+    open?: boolean;
+    /** Working-time duration in minutes. For milestones this is 0. */
+    duration: number;
+    /**
+     * User-set start / end. For manual-scheduled tasks these are authoritative.
+     * For auto-scheduled tasks the engine recomputes them and writes the
+     * result back. Either way, the engine populates `computed` with the
+     * full forward/backward-pass data.
+     */
+    start: Date;
+    end: Date;
+    /** Percent complete, 0-100. */
+    progress: number;
+    constraint?: Constraint;
+    /** Resource assignments. Order is not meaningful. */
+    resourceIds?: ResourceId[];
+    /**
+     * Calendar override. If unset, the task uses the project default calendar.
+     * If a resource on the task has a calendar, the engine reconciles them
+     * (resource calendar wins for activities depending on that resource).
+     */
+    calendarId?: CalendarId;
+    /** Populated by the scheduling engine. Read-only for user code. */
+    computed?: TaskComputed;
+}
+/**
+ * Forward/backward-pass output. Filled in by `schedule()`.
+ *
+ * `totalSlack` is the contract-trouble signal: when negative, the task is
+ * already late against a downstream constraint and the schedule is
+ * infeasible without intervention. We display this; we don't clip it.
+ */
+interface TaskComputed {
+    earlyStart: Date;
+    earlyFinish: Date;
+    lateStart: Date;
+    lateFinish: Date;
+    /** Working-minutes of total float. Can be negative. */
+    totalSlack: number;
+    /** Working-minutes of free float (slack against the earliest successor). */
+    freeSlack: number;
+    isCritical: boolean;
+}
+
+interface PngExportOptions {
+    /** Background colour for the captured canvas. Defaults to '#ffffff'. */
+    backgroundColor?: string;
+    /** Pixel ratio. Defaults to window.devicePixelRatio || 2. */
+    pixelRatio?: number;
+}
+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;
+}
+interface XlsxColumn {
+    header: string;
+    /** A key on Task, or a function returning the cell value. */
+    value: keyof Task | ((task: Task) => string | number | Date | undefined);
+}
+interface XlsxExportOptions {
+    /** Sheet name. Defaults to 'Programme'. */
+    sheetName?: string;
+    /** Override the default column set. */
+    columns?: XlsxColumn[];
+}
+interface GanttHandle {
+    exportPNG(options?: PngExportOptions): Promise<Blob>;
+    exportPDF(options?: PdfExportOptions): Promise<Blob>;
+    exportXLSX(options?: XlsxExportOptions): Promise<Blob>;
+}
+
+export type { GanttHandle, PdfExportOptions, PngExportOptions, XlsxColumn, XlsxExportOptions };
+//# sourceMappingURL=index.d.cts.map

package/dist/export/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sources":["../../src/types.ts","../../src/export/types.ts"],"mappings":"AAAA,KAAK,MAAM;AAEX,KAAK,UAAU;AACf,KAAK,UAAU;AAEf,KAAK,QAAQ;AACb,KAAK,YAAY;AACjB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,cAAc;AACnB,UAAU,UAAU;AACpB,UAAU,cAAc;AACxB;AACA,WAAW,IAAI;AACf;AACA,UAAU,IAAI;AACd,QAAQ,MAAM;AACd;AACA;AACA,aAAa,MAAM;AACnB,UAAU,QAAQ;AAClB,kBAAkB,YAAY;AAC9B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,WAAW,IAAI;AACf,SAAS,IAAI;AACb;AACA;AACA,iBAAiB,UAAU;AAC3B;AACA,kBAAkB,UAAU;AAC5B;AACA;AACA;AACA;AACA;AACA,iBAAiB,UAAU;AAC3B;AACA,eAAe,YAAY;AAC3B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,UAAU,YAAY;AACtB,gBAAgB,IAAI;AACpB,iBAAiB,IAAI;AACrB,eAAe,IAAI;AACnB,gBAAgB,IAAI;AACpB;AACA;AACA;AACA;AACA;AACA;;AC5EA,UAAU,gBAAgB;AAC1B;AACA;AACA;AACA;AACA;AACA,UAAU,gBAAgB;AAC1B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,UAAU,UAAU;AACpB;AACA;AACA,iBAAiB,IAAI,WAAW,IAAI,uBAAuB,IAAI;AAC/D;AACA,UAAU,iBAAiB;AAC3B;AACA;AACA;AACA,cAAc,UAAU;AACxB;AACA,UAAU,WAAW;AACrB,wBAAwB,gBAAgB,GAAG,OAAO,CAAC,IAAI;AACvD,wBAAwB,gBAAgB,GAAG,OAAO,CAAC,IAAI;AACvD,yBAAyB,iBAAiB,GAAG,OAAO,CAAC,IAAI;AACzD;;;;","names":[]}

package/dist/export/index.d.ts

@@ -0,0 +1,112 @@
+type TaskId = string | number;
+type ResourceId = string | number;
+type CalendarId = string | number;
+type TaskType = 'task' | 'summary' | 'milestone';
+type ScheduleMode = 'auto' | 'manual';
+/**
+ * MS Project's 8 constraint types.
+ *
+ * - ASAP / ALAP: scheduling preferences, no date required.
+ * - MSO / MFO:   hard constraints, pin the date; override predecessor logic.
+ * - SNET / SNLT / FNET / FNLT: soft date bounds.
+ *
+ * Hard constraints can produce negative slack — the contract-trouble
+ * signal we surface rather than silently clip to zero (ADR-003).
+ */
+type ConstraintType = 'ASAP' | 'ALAP' | 'MSO' | 'MFO' | 'SNET' | 'SNLT' | 'FNET' | 'FNLT';
+interface Constraint {
+    type: ConstraintType;
+    /** Required for all types except ASAP and ALAP. */
+    date?: Date;
+}
+interface Task {
+    id: TaskId;
+    text: string;
+    /** Hierarchy parent. Undefined = top-level. */
+    parent?: TaskId;
+    type: TaskType;
+    scheduleMode: ScheduleMode;
+    /**
+     * For summary tasks: are children currently expanded?
+     * Default true (expanded). Toggled by the user via the renderer's
+     * collapse/expand chevron.
+     */
+    open?: boolean;
+    /** Working-time duration in minutes. For milestones this is 0. */
+    duration: number;
+    /**
+     * User-set start / end. For manual-scheduled tasks these are authoritative.
+     * For auto-scheduled tasks the engine recomputes them and writes the
+     * result back. Either way, the engine populates `computed` with the
+     * full forward/backward-pass data.
+     */
+    start: Date;
+    end: Date;
+    /** Percent complete, 0-100. */
+    progress: number;
+    constraint?: Constraint;
+    /** Resource assignments. Order is not meaningful. */
+    resourceIds?: ResourceId[];
+    /**
+     * Calendar override. If unset, the task uses the project default calendar.
+     * If a resource on the task has a calendar, the engine reconciles them
+     * (resource calendar wins for activities depending on that resource).
+     */
+    calendarId?: CalendarId;
+    /** Populated by the scheduling engine. Read-only for user code. */
+    computed?: TaskComputed;
+}
+/**
+ * Forward/backward-pass output. Filled in by `schedule()`.
+ *
+ * `totalSlack` is the contract-trouble signal: when negative, the task is
+ * already late against a downstream constraint and the schedule is
+ * infeasible without intervention. We display this; we don't clip it.
+ */
+interface TaskComputed {
+    earlyStart: Date;
+    earlyFinish: Date;
+    lateStart: Date;
+    lateFinish: Date;
+    /** Working-minutes of total float. Can be negative. */
+    totalSlack: number;
+    /** Working-minutes of free float (slack against the earliest successor). */
+    freeSlack: number;
+    isCritical: boolean;
+}
+
+interface PngExportOptions {
+    /** Background colour for the captured canvas. Defaults to '#ffffff'. */
+    backgroundColor?: string;
+    /** Pixel ratio. Defaults to window.devicePixelRatio || 2. */
+    pixelRatio?: number;
+}
+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;
+}
+interface XlsxColumn {
+    header: string;
+    /** A key on Task, or a function returning the cell value. */
+    value: keyof Task | ((task: Task) => string | number | Date | undefined);
+}
+interface XlsxExportOptions {
+    /** Sheet name. Defaults to 'Programme'. */
+    sheetName?: string;
+    /** Override the default column set. */
+    columns?: XlsxColumn[];
+}
+interface GanttHandle {
+    exportPNG(options?: PngExportOptions): Promise<Blob>;
+    exportPDF(options?: PdfExportOptions): Promise<Blob>;
+    exportXLSX(options?: XlsxExportOptions): Promise<Blob>;
+}
+
+export type { GanttHandle, PdfExportOptions, PngExportOptions, XlsxColumn, XlsxExportOptions };
+//# sourceMappingURL=index.d.ts.map

package/dist/export/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sources":["../../src/types.ts","../../src/export/types.ts"],"mappings":"AAAA,KAAK,MAAM;AAEX,KAAK,UAAU;AACf,KAAK,UAAU;AAEf,KAAK,QAAQ;AACb,KAAK,YAAY;AACjB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,KAAK,cAAc;AACnB,UAAU,UAAU;AACpB,UAAU,cAAc;AACxB;AACA,WAAW,IAAI;AACf;AACA,UAAU,IAAI;AACd,QAAQ,MAAM;AACd;AACA;AACA,aAAa,MAAM;AACnB,UAAU,QAAQ;AAClB,kBAAkB,YAAY;AAC9B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,WAAW,IAAI;AACf,SAAS,IAAI;AACb;AACA;AACA,iBAAiB,UAAU;AAC3B;AACA,kBAAkB,UAAU;AAC5B;AACA;AACA;AACA;AACA;AACA,iBAAiB,UAAU;AAC3B;AACA,eAAe,YAAY;AAC3B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,UAAU,YAAY;AACtB,gBAAgB,IAAI;AACpB,iBAAiB,IAAI;AACrB,eAAe,IAAI;AACnB,gBAAgB,IAAI;AACpB;AACA;AACA;AACA;AACA;AACA;;AC5EA,UAAU,gBAAgB;AAC1B;AACA;AACA;AACA;AACA;AACA,UAAU,gBAAgB;AAC1B;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,UAAU,UAAU;AACpB;AACA;AACA,iBAAiB,IAAI,WAAW,IAAI,uBAAuB,IAAI;AAC/D;AACA,UAAU,iBAAiB;AAC3B;AACA;AACA;AACA,cAAc,UAAU;AACxB;AACA,UAAU,WAAW;AACrB,wBAAwB,gBAAgB,GAAG,OAAO,CAAC,IAAI;AACvD,wBAAwB,gBAAgB,GAAG,OAAO,CAAC,IAAI;AACvD,yBAAyB,iBAAiB,GAAG,OAAO,CAAC,IAAI;AACzD;;;;","names":[]}

package/dist/export/index.js

@@ -0,0 +1 @@
+