@eightkk/vue-weave 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/CHANGELOG.md +525 -0
  2. package/CONTRIBUTING.md +116 -0
  3. package/LICENSE +21 -0
  4. package/README.ja.md +278 -0
  5. package/README.md +275 -2
  6. package/THIRD_PARTY_NOTICES.md +25 -0
  7. package/dist/core-LWK21xl4.js +13672 -0
  8. package/dist/core.js +1 -0
  9. package/dist/index.js +8505 -0
  10. package/dist/style.css +2 -0
  11. package/dist/types/components/GanttChart.vue.d.ts +353 -0
  12. package/dist/types/components/NetworkGraph.vue.d.ts +252 -0
  13. package/dist/types/components/types.d.ts +27 -0
  14. package/dist/types/composables/useAsyncGraphLayout.d.ts +163 -0
  15. package/dist/types/composables/useEditHistory.d.ts +13 -0
  16. package/dist/types/composables/useEditTransaction.d.ts +46 -0
  17. package/dist/types/composables/useLinkedSelection.d.ts +118 -0
  18. package/dist/types/composables/useTimelineView.d.ts +24 -0
  19. package/dist/types/composables/useWindowedData.d.ts +83 -0
  20. package/dist/types/core/actuals.d.ts +170 -0
  21. package/dist/types/core/calendarFormat.d.ts +65 -0
  22. package/dist/types/core/editTransaction.d.ts +96 -0
  23. package/dist/types/core/exportSvg.d.ts +236 -0
  24. package/dist/types/core/fieldEditing.d.ts +114 -0
  25. package/dist/types/core/graph.d.ts +196 -0
  26. package/dist/types/core/graphAlgorithms.d.ts +51 -0
  27. package/dist/types/core/graphAnalysis.d.ts +96 -0
  28. package/dist/types/core/graphCollapse.d.ts +62 -0
  29. package/dist/types/core/graphCrossings.d.ts +25 -0
  30. package/dist/types/core/graphEditing.d.ts +52 -0
  31. package/dist/types/core/graphExpansion.d.ts +71 -0
  32. package/dist/types/core/graphFlow.d.ts +184 -0
  33. package/dist/types/core/graphForce.d.ts +29 -0
  34. package/dist/types/core/graphGeometry.d.ts +31 -0
  35. package/dist/types/core/graphIncremental.d.ts +93 -0
  36. package/dist/types/core/graphLasso.d.ts +15 -0
  37. package/dist/types/core/graphLayoutRequests.d.ts +218 -0
  38. package/dist/types/core/graphLayouts.d.ts +81 -0
  39. package/dist/types/core/graphObstacleRouting.d.ts +68 -0
  40. package/dist/types/core/graphPortRules.d.ts +111 -0
  41. package/dist/types/core/graphRouting.d.ts +84 -0
  42. package/dist/types/core/graphSnapping.d.ts +34 -0
  43. package/dist/types/core/graphSpatial.d.ts +49 -0
  44. package/dist/types/core/graphSwimlanes.d.ts +77 -0
  45. package/dist/types/core/graphTraversal.d.ts +51 -0
  46. package/dist/types/core/graphView.d.ts +73 -0
  47. package/dist/types/core/index.d.ts +76 -0
  48. package/dist/types/core/interchange.d.ts +6 -0
  49. package/dist/types/core/interchangeCsv.d.ts +75 -0
  50. package/dist/types/core/interchangeICalendar.d.ts +111 -0
  51. package/dist/types/core/interchangeMsProject.d.ts +339 -0
  52. package/dist/types/core/leveling.d.ts +57 -0
  53. package/dist/types/core/pert.d.ts +62 -0
  54. package/dist/types/core/placement.d.ts +100 -0
  55. package/dist/types/core/planComparison.d.ts +275 -0
  56. package/dist/types/core/resourceLoad.d.ts +65 -0
  57. package/dist/types/core/resourceTimeline.d.ts +179 -0
  58. package/dist/types/core/rowHierarchy.d.ts +25 -0
  59. package/dist/types/core/scheduleDiagnostics.d.ts +37 -0
  60. package/dist/types/core/scheduleModel.d.ts +187 -0
  61. package/dist/types/core/scheduleTrace.d.ts +118 -0
  62. package/dist/types/core/scheduling.d.ts +194 -0
  63. package/dist/types/core/sheetEditing.d.ts +36 -0
  64. package/dist/types/core/snapshot.d.ts +388 -0
  65. package/dist/types/core/statusDate.d.ts +36 -0
  66. package/dist/types/core/timeRangeTargets.d.ts +67 -0
  67. package/dist/types/core/timeline.d.ts +194 -0
  68. package/dist/types/core/timelineView.d.ts +101 -0
  69. package/dist/types/core/types.d.ts +805 -0
  70. package/dist/types/core/viewBindings.d.ts +112 -0
  71. package/dist/types/core/windowedData.d.ts +255 -0
  72. package/dist/types/core/workCalendar.d.ts +41 -0
  73. package/dist/types/core/workingTimeScale.d.ts +33 -0
  74. package/dist/types/index.d.ts +52 -0
  75. package/docs/api.md +2009 -0
  76. package/docs/architecture.md +112 -0
  77. package/docs/code-of-conduct.md +24 -0
  78. package/docs/integration.md +964 -0
  79. package/docs/scheduling.md +586 -0
  80. package/docs/security.md +26 -0
  81. package/docs/third-party-licenses.md +33 -0
  82. package/package.json +79 -4
@@ -0,0 +1,111 @@
1
+ import type { TimelineBar, TimelineRow } from './types.js';
2
+ export interface ICalendarEvent {
3
+ /** Unique within the calendar. Written as the event UID; make it globally unique, for example `id@example.com`. */
4
+ id: string;
5
+ summary: string;
6
+ /** Epoch milliseconds. */
7
+ start: number;
8
+ /** Epoch milliseconds, not before `start`. An event with `end === start` is written without DTEND. */
9
+ end: number;
10
+ description?: string;
11
+ }
12
+ export interface ICalendarOptions {
13
+ /** PRODID value. Default `-//vue-weave//Timeline export//EN`. */
14
+ productId?: string;
15
+ /** Calendar name, written as NAME and X-WR-CALNAME. */
16
+ calendarName?: string;
17
+ /** DTSTAMP of every event, in epoch milliseconds. Default `Date.now()`; pass it for reproducible output. */
18
+ timestamp?: number;
19
+ }
20
+ /**
21
+ * Build an iCalendar (RFC 5545) document with one VEVENT per event: UID, DTSTAMP, DTSTART, DTEND, SUMMARY and an
22
+ * optional DESCRIPTION. Times are written in UTC, rounded to the nearest whole second; DTEND is written only when the
23
+ * rounded end is after the rounded start. Text is escaped, lines end with CRLF and are folded at 75 octets.
24
+ * Throws an Error for empty or duplicate IDs and a missing summary, and a RangeError for non-finite or unordered times.
25
+ */
26
+ export declare function toICalendar(events: readonly ICalendarEvent[], options?: ICalendarOptions): string;
27
+ /** An event read by `fromICalendar`. It is an `ICalendarEvent`, so `toICalendar` and `timelineFromICalendar` accept it. */
28
+ export interface ICalendarImportEvent extends ICalendarEvent {
29
+ /** DTSTART was a date (`VALUE=DATE`). `start` is midnight and `end` the midnight that ends the last day (exclusive). */
30
+ allDay: boolean;
31
+ /** The RRULE of a recurring event, as written. Only the first instance is imported. */
32
+ recurrenceRule?: string;
33
+ }
34
+ export interface ICalendarImportOptions {
35
+ /**
36
+ * Offset from UTC in minutes for local times that have no zone: floating date-times, dates, and date-times whose
37
+ * TZID cannot be resolved. Default 0 (UTC), integer within ±1080.
38
+ */
39
+ utcOffsetMinutes?: number;
40
+ }
41
+ /**
42
+ * The kind of a problem `fromICalendar` worked around. `skipped-event`: an event without a readable DTSTART, with a
43
+ * RECURRENCE-ID (a changed instance of a recurring event), with a UID used before, or without END:VEVENT.
44
+ * `missing-uid`: an event without a UID, which got the ID `event-<n>`. `recurrence`: RRULE, RDATE or EXDATE, of which only
45
+ * the first instance was imported. `unknown-time-zone`: a TZID that `Intl` does not know; the time is read as local time
46
+ * at `utcOffsetMinutes`. `invalid-value`: an unreadable DTEND or DURATION (the event is an instant), or a DTEND before
47
+ * DTSTART (the event is an instant too). `malformed`: a line without a colon, or an END that does not match, which
48
+ * was ignored.
49
+ */
50
+ export type ICalendarImportWarningCode = 'skipped-event' | 'missing-uid' | 'recurrence' | 'unknown-time-zone' | 'invalid-value' | 'malformed';
51
+ export interface ICalendarImportWarning {
52
+ code: ICalendarImportWarningCode;
53
+ /** The imported ID of the event the warning is about, when it has one. */
54
+ eventId?: string;
55
+ /** The one-based line of the file where the property or component starts, after unfolding the first line of it. */
56
+ line?: number;
57
+ /** An English description for logs; match on `code`. */
58
+ message: string;
59
+ }
60
+ /** The result of `fromICalendar`. */
61
+ export interface ICalendarImport {
62
+ /** NAME or X-WR-CALNAME of the calendar, when there is one. */
63
+ name?: string;
64
+ events: ICalendarImportEvent[];
65
+ warnings: ICalendarImportWarning[];
66
+ }
67
+ /**
68
+ * Read RFC 5545 text, such as `toICalendar` output or an export of a calendar application, into events. Pure string
69
+ * parsing without a DOM, network or file access, done with loops. Lines are unfolded (CRLF, LF or CR line ends; a
70
+ * leading byte order mark is removed), property names and parameter names are case-insensitive, quoted parameter values
71
+ * are read, and TEXT values are unescaped (backslash followed by n, comma, semicolon or backslash; any other backslash is kept as written).
72
+ *
73
+ * Each VEVENT becomes an `ICalendarImportEvent` with `id` (UID), `summary` (SUMMARY, empty when missing), `description`
74
+ * when DESCRIPTION is present, `start` and `end` in epoch milliseconds. DTSTART and DTEND may be UTC (`Z`), floating,
75
+ * have a `TZID` parameter or be dates (`VALUE=DATE`). A UTC time is exact. A TZID is resolved with `Intl` as RFC 5545
76
+ * section 3.3.5 says: a local time skipped by a daylight-saving gap is read with the UTC offset before the gap
77
+ * (`DTSTART;TZID=America/New_York:20070311T023000` is 07:30 UTC, local 03:30), and a repeated local time takes its
78
+ * first occurrence. This differs from `buildWorkPeriods` and editing, which move a skipped time to the transition. The
79
+ * nonstandard prefix of `/mozilla.org/…/Europe/Berlin` is stripped, and VTIMEZONE definitions are not
80
+ * read. A floating time, a date and a time with an unknown TZID (reported) are wall-clock times at
81
+ * `options.utcOffsetMinutes`. The end is DTEND, else DTSTART plus DURATION, else the start plus one day for a date and
82
+ * the start itself for a date-time, which is an
83
+ * instant like the events `toICalendar` writes without DTEND. For a date, DTEND is the exclusive end, so the
84
+ * event spans whole days as in `[start, end)`. A DURATION (weeks, days, hours, minutes and seconds; not negative) is
85
+ * added as RFC 5545 says: its weeks and days to the local date and time of DTSTART, then its hours, minutes and seconds as
86
+ * elapsed time. So with a TZID, `P1D` ends at the same local time on the next day (23 or 25 hours across a daylight
87
+ * saving change) while `PT24H` is 24 hours; a local end time in a skipped or repeated hour is resolved like DTSTART. For
88
+ * a UTC, floating or date DTSTART, a day is 24 hours.
89
+ *
90
+ * Recurrence is not expanded: an event with RRULE, RDATE or EXDATE is imported once, at its first instance, with the
91
+ * rule in `recurrenceRule`, and a warning. Changed instances (RECURRENCE-ID) are skipped. Properties other than the
92
+ * ones above, other components (VTODO, VTIMEZONE, …) and nested components such as VALARM are ignored.
93
+ * Problems that the reader works around are listed in `warnings` instead of thrown.
94
+ *
95
+ * Throws an Error for a value that is not a string or has no BEGIN:VCALENDAR, and a RangeError for an invalid
96
+ * `utcOffsetMinutes`. The reader sets no size limit: bound the size of uploaded files yourself.
97
+ */
98
+ export declare function fromICalendar(text: string, options?: ICalendarImportOptions): ICalendarImport;
99
+ /** GanttChart data from `timelineFromICalendar`. */
100
+ export interface ICalendarTimeline {
101
+ rows: TimelineRow[];
102
+ bars: TimelineBar[];
103
+ }
104
+ /**
105
+ * Turn events, such as the result of `fromICalendar` or the input of `toICalendar`, into GanttChart rows and bars: one
106
+ * row and one bar per event, in input order, both with the event ID, the summary as label, the dates, and the
107
+ * description (when it is not empty) as the bar's `description`. An event with `start === end` is a zero-length
108
+ * milestone bar. Throws the Errors and RangeErrors of `toICalendar` for empty or duplicate IDs, a missing summary and
109
+ * non-finite or unordered times. The input is not modified.
110
+ */
111
+ export declare function timelineFromICalendar(events: readonly ICalendarEvent[]): ICalendarTimeline;
@@ -0,0 +1,339 @@
1
+ import type { ResourceAssignment, ResourceCapacity } from './resourceLoad.js';
2
+ import type { ResourceTimelineResource } from './resourceTimeline.js';
3
+ import { type TimeRange } from './timeline.js';
4
+ import { type WorkCalendar, type WorkWeek } from './workCalendar.js';
5
+ import type { TimelineBar, TimelineConstraints, TimelineDependency, TimelineDependencyType, TimelineRow } from './types.js';
6
+ export interface MsProjectTask {
7
+ id: string;
8
+ name: string;
9
+ /** Epoch milliseconds. */
10
+ start: number;
11
+ /** Epoch milliseconds, not before `start`. */
12
+ end: number;
13
+ /** Outline level from 1 (top level). Each task is at most one level below the task before it. Default 1. */
14
+ outlineLevel?: number;
15
+ /** Percent complete from 0 to 100, rounded to an integer. */
16
+ percentComplete?: number;
17
+ /** Export as a milestone. Tasks with `start === end` are always milestones. */
18
+ milestone?: boolean;
19
+ /** Saved baselines, written as `Baseline` elements; at most one per `number`. */
20
+ baselines?: readonly MsProjectBaseline[];
21
+ /**
22
+ * Scheduling constraints in epoch milliseconds, for example `TimelineBar.constraints`. A Microsoft Project task holds
23
+ * one constraint, so exactly one set constraint is written as `ConstraintType` and `ConstraintDate`. The one pair that
24
+ * Microsoft Project can express, `finishNoEarlierThan` and `finishNoLaterThan` at the same time, is written as Must
25
+ * Finish On (3); any other combination of two or more writes none.
26
+ */
27
+ constraints?: TimelineConstraints;
28
+ /** Export as an inactive task (`Active` 0), which Microsoft Project leaves out of its calculation. Default false. */
29
+ inactive?: boolean;
30
+ /**
31
+ * False exports an automatically scheduled task (`Manual` 0). Microsoft Project then recalculates its dates from its
32
+ * links, constraint and its own calendar when it opens the file, so they can move. Default true: a manually scheduled
33
+ * task that keeps the given dates.
34
+ */
35
+ manual?: boolean;
36
+ /** ID of an `MsProjectCalendar` of the project: the task's own calendar (`CalendarUID`). Default: the project calendar. */
37
+ calendarId?: string;
38
+ }
39
+ /**
40
+ * A calendar of a Microsoft Project plan: a weekly pattern with date exceptions, as `WorkWeek` of `buildWorkPeriods`
41
+ * holds it. Shift minutes are local wall-clock times.
42
+ */
43
+ export interface MsProjectCalendar {
44
+ /** Unique within the project. `toMsProjectXml` numbers calendars from 1 in input order and does not write this ID. */
45
+ id: string;
46
+ name: string;
47
+ /** Read from `IsBaseCalendar`. `toMsProjectXml` ignores it and writes every calendar as a base calendar. */
48
+ base?: boolean;
49
+ /** The ID of the calendar this one was derived from (`BaseCalendarUID`). Informational: `week` is already complete. */
50
+ baseCalendarId?: string;
51
+ /**
52
+ * The complete weekly pattern and exceptions, with everything inherited from the base calendar already applied. A
53
+ * weekday without shifts is non-working. `toMsProjectXml` writes only `weekly` and `exceptions`: `utcOffsetMinutes` and
54
+ * `timeZone` are ignored (MSPDI times are wall-clock times), and a shift that ends after minute 1440 throws a RangeError.
55
+ */
56
+ week: WorkWeek;
57
+ }
58
+ /** A resource of a Microsoft Project plan. */
59
+ export interface MsProjectResource {
60
+ /** Unique within the project. `toMsProjectXml` numbers resources from 1 in input order and does not write this ID. */
61
+ id: string;
62
+ name: string;
63
+ /**
64
+ * `Type` 0 material or 1 work; a cost resource has `IsCostResource` 1 (read also from `Type` 2). Absent counts as
65
+ * `'work'` where it matters.
66
+ */
67
+ type?: 'work' | 'material' | 'cost';
68
+ /** `MaxUnits` as a fraction of one full-time resource: 1 is 100 %, 2.5 is 250 %. Absent counts as 1. */
69
+ maxUnits?: number;
70
+ /** ID of an `MsProjectCalendar`: the resource's own working time (`CalendarUID`). */
71
+ calendarId?: string;
72
+ }
73
+ /** A resource assigned to a task. At most one assignment per task and resource. */
74
+ export interface MsProjectAssignment {
75
+ taskId: string;
76
+ resourceId: string;
77
+ /** `Units` as a fraction of full time: 1 is 100 %. Absent counts as 1. */
78
+ units?: number;
79
+ }
80
+ /**
81
+ * A saved baseline of a task. Microsoft Project numbers its baselines 0 (Baseline) to 10 (Baseline10); map your baseline
82
+ * set IDs to numbers, for example `plan` to 0 and `rev1` to 1.
83
+ */
84
+ export interface MsProjectBaseline {
85
+ /** Integer from 0 to 10. */
86
+ number: number;
87
+ /** Epoch milliseconds. */
88
+ start: number;
89
+ /** Epoch milliseconds, not before `start`. */
90
+ end: number;
91
+ }
92
+ export interface MsProjectDependency {
93
+ from: string;
94
+ to: string;
95
+ /** Default FS. */
96
+ type?: TimelineDependencyType;
97
+ /** Elapsed lag in milliseconds; negative values are leads. Written in tenths of a minute. */
98
+ lag?: number;
99
+ }
100
+ export interface MsProjectInput {
101
+ name: string;
102
+ tasks: readonly MsProjectTask[];
103
+ dependencies?: readonly MsProjectDependency[];
104
+ /** Calendars, written by `toMsProjectXml` and read by `fromMsProjectXml`. */
105
+ calendars?: readonly MsProjectCalendar[];
106
+ /** The ID of the project calendar (`CalendarUID`), one of `calendars`. */
107
+ defaultCalendarId?: string;
108
+ resources?: readonly MsProjectResource[];
109
+ assignments?: readonly MsProjectAssignment[];
110
+ }
111
+ export interface MsProjectXmlOptions {
112
+ /** Fixed offset from UTC in minutes for the written wall-clock dates. Default 0 (UTC). */
113
+ utcOffsetMinutes?: number;
114
+ }
115
+ /**
116
+ * Build a Microsoft Project XML (MSPDI) document that Microsoft Project and compatible tools can open. Each task
117
+ * becomes a manually scheduled task (so its dates are kept as given) with a UID and ID from 1 in input order, its
118
+ * name, start, finish, elapsed duration, outline level and number, milestone and summary flags and percent complete.
119
+ * Dependencies become `PredecessorLink` elements with the MSPDI link type (FF 0, FS 1, SF 2, SS 3) and the lag in
120
+ * tenths of a minute as elapsed minutes. Dates are wall-clock times at `utcOffsetMinutes` without an offset suffix.
121
+ * Start and finish are rounded to the nearest whole second, and the duration is the difference of the rounded times.
122
+ *
123
+ * Task `baselines` become `Baseline` elements (after the predecessor links) with their number, start, finish and elapsed
124
+ * duration, rounded like the task dates.
125
+ *
126
+ * A task with exactly one constraint in `constraints` gets `ConstraintType` (2 Must Start On for `fixedStart`, 4 to 7 for
127
+ * start no earlier, start no later, finish no earlier and finish no later than) and `ConstraintDate`, rounded like the
128
+ * task dates. A task can hold only one constraint in Microsoft Project, so a task with several gets none, except one
129
+ * whose constraints are exactly `finishNoEarlierThan` and `finishNoLaterThan` at the same time: it gets 3 (Must Finish
130
+ * On) with that time.
131
+ *
132
+ * A task with `inactive: true` is written with `Active` 0, and one with `manual: false` as automatically scheduled
133
+ * (`Manual` 0); without them every task is active and manually scheduled.
134
+ *
135
+ * Optional `calendars`, `resources` and `assignments` are written as `Calendars`, `Resources` and `Assignments` with UIDs
136
+ * from 1 in input order. Every calendar is written as a base calendar with its complete weekly pattern (`DayType` 1 to 7,
137
+ * Sunday first) and each exception date as a `DayType` 0 entry with a `TimePeriod`. `defaultCalendarId` and a task's
138
+ * `calendarId` become `CalendarUID`. A resource gets `Type` (0 material, 1 work; a cost resource 0 with `IsCostResource` 1),
139
+ * `MaxUnits` (when set) and `CalendarUID`, an assignment `Units` (default 1). These
140
+ * elements follow the MSPDI schema order but have not been opened in Microsoft Project itself.
141
+ *
142
+ * Not exported: a second constraint of a task (other than the Must Finish On pair), notes, custom fields, baseline
143
+ * work or cost and the base-calendar inheritance and time zone of a calendar. Task, calendar and resource IDs of the
144
+ * input are not written; the UIDs follow the input order.
145
+ *
146
+ * Throws an Error for empty or duplicate task IDs, a missing project or task name, unknown dependency ends, a
147
+ * dependency from a task to itself, unknown link types, a duplicate baseline number on a task and `inactive` or `manual`
148
+ * flags that are not booleans, and a RangeError for non-finite or unordered dates (also of baselines), an invalid
149
+ * outline level, percent complete, lag, baseline number or constraint time. Calendars, resources and assignments throw an
150
+ * Error for empty or duplicate IDs, missing names, unknown references and duplicate assignments, and a RangeError for
151
+ * invalid shifts, exception dates, `maxUnits` or `units`.
152
+ */
153
+ export declare function toMsProjectXml(project: MsProjectInput, options?: MsProjectXmlOptions): string;
154
+ /** A task read by `fromMsProjectXml`. The optional fields of `MsProjectTask` that a file always has are set. */
155
+ export interface MsProjectImportTask extends MsProjectTask {
156
+ outlineLevel: number;
157
+ percentComplete: number;
158
+ milestone: boolean;
159
+ /** `Summary` 1: the task has subtasks. */
160
+ summary: boolean;
161
+ /** `Manual` 1: a manually scheduled task. Use `{ start, end }` as `ScheduleTask.manual` to keep its dates. */
162
+ manual: boolean;
163
+ /** `Active` 0: an inactive task. */
164
+ inactive: boolean;
165
+ /**
166
+ * `Duration` in milliseconds: the working time of an automatically scheduled task, useful as `ScheduleTask.duration`.
167
+ * Absent when the file has none or it cannot be read.
168
+ */
169
+ duration?: number;
170
+ /** `'alap'` for `ConstraintType` 1 (As Late As Possible), named as `ScheduleTask.mode`. */
171
+ mode?: 'alap';
172
+ }
173
+ /**
174
+ * The kind of a problem `fromMsProjectXml` worked around. `skipped-task`: a task without a valid UID, start or finish,
175
+ * or with a UID used before. `outline-level`: an outline level more than one below the task before it, which was
176
+ * raised. `invalid-value`: an unreadable percent complete, duration, outline level or lag, which was ignored.
177
+ * `unsupported-constraint`: an unknown constraint type or a constraint without a date, which was left out. `skipped-baseline`: a baseline with an invalid or repeated number or unreadable or inverted dates.
178
+ * `unknown-predecessor`: a link from a task that was not imported. `skipped-link`: a link to another project, from a
179
+ * task to itself or of an unknown type. `percent-lag`: a lag in percent of the predecessor's duration, which was left
180
+ * out. `working-time-lag`: a lag in working time, which was read as the same amount of elapsed time.
181
+ * `skipped-calendar`: a calendar without a valid or with a repeated UID. `invalid-calendar`: a working time, exception
182
+ * or base calendar reference that cannot be read or would be circular, which was left out, or an exception with more
183
+ * than 3,660 dates, of which the first 3,660 were kept. `unsupported-calendar`: an exception recurrence that is not
184
+ * expanded (see `fromMsProjectXml`), an alternate work week or a day type that `WorkWeek` cannot hold, which was left out.
185
+ * `unknown-calendar`: a calendar UID of the project, a task or a resource that no imported calendar has, which was left
186
+ * out. `skipped-resource`: a resource without a valid UID or with a UID used before. `skipped-assignment`: an
187
+ * assignment to a task or resource that was not imported, or repeating a task and resource pair.
188
+ */
189
+ export type MsProjectImportWarningCode = 'skipped-task' | 'outline-level' | 'invalid-value' | 'unsupported-constraint' | 'skipped-baseline' | 'unknown-predecessor' | 'skipped-link' | 'percent-lag' | 'working-time-lag' | 'skipped-calendar' | 'invalid-calendar' | 'unsupported-calendar' | 'unknown-calendar' | 'skipped-resource' | 'skipped-assignment';
190
+ export interface MsProjectImportWarning {
191
+ code: MsProjectImportWarningCode;
192
+ /** The imported ID (the UID) of the task the warning is about, when there is one. */
193
+ taskId?: string;
194
+ /** The imported ID of the calendar the warning is about, when there is one. */
195
+ calendarId?: string;
196
+ /** The imported ID of the resource the warning is about, when there is one. */
197
+ resourceId?: string;
198
+ /** An English description for logs; match on `code`. */
199
+ message: string;
200
+ }
201
+ /** The result of `fromMsProjectXml`. It is an `MsProjectInput`, so `toMsProjectXml` accepts it. */
202
+ export interface MsProjectImport {
203
+ name: string;
204
+ tasks: MsProjectImportTask[];
205
+ /** In the order of their successor tasks and then of their links. `type` is always set, `lag` only when not 0. */
206
+ dependencies: MsProjectDependency[];
207
+ warnings: MsProjectImportWarning[];
208
+ /** Present when the file has calendars. Ordered as in the file; see `MsProjectCalendar`. */
209
+ calendars?: MsProjectCalendar[];
210
+ /** The project calendar (`CalendarUID`), when the file names one that was imported. */
211
+ defaultCalendarId?: string;
212
+ /** Present when the file has resources. Excludes the project's own "unassigned" resource (UID 0). */
213
+ resources?: MsProjectResource[];
214
+ /** Present when the file has assignments to imported tasks and resources. */
215
+ assignments?: MsProjectAssignment[];
216
+ }
217
+ /**
218
+ * Read a Microsoft Project XML (MSPDI) document, such as one written by Microsoft Project's "Save as XML" or by
219
+ * `toMsProjectXml`. Pure string parsing: no DOM, no network and no file access; a DOCTYPE is skipped and only the five
220
+ * predefined entities and character references are expanded. Namespaces are matched by local name.
221
+ *
222
+ * The project name is `Name` when it is not blank, else `Title`, else empty. Each `Task` except the project summary task (UID 0) and empty
223
+ * rows (`IsNull` 1) becomes an `MsProjectImportTask` with its UID as `id` and `Name`, `Start`, `Finish`, `OutlineLevel`,
224
+ * `PercentComplete`, `Milestone`, `Summary`, `Manual`, `Active`, `Duration`, its constraint and its `Baseline`
225
+ * dates. Dates are wall-clock times at `utcOffsetMinutes`, as `toMsProjectXml` writes them, unless they carry a zone.
226
+ * Constraint types 2 and 4 to 7 become `constraints` as `toMsProjectXml` maps them, type 3 (Must Finish On) becomes
227
+ * `finishNoEarlierThan` and `finishNoLaterThan` at its date, and type 1 (As Late As Possible)
228
+ * becomes `mode: 'alap'`. `PredecessorLink` elements become dependencies with their type (FF 0, FS 1, SF 2, SS 3) and
229
+ * `LinkLag` (tenths of a minute) as elapsed milliseconds. Problems that the reader works around are listed in
230
+ * `warnings` (see `MsProjectImportWarningCode`) instead of thrown.
231
+ *
232
+ * Calendars become `calendars` (`MsProjectCalendar`): the weekly working times (`DayType` 1 to 7) and the exceptions
233
+ * (`DayType` 0 entries and `Exceptions`) as one-off dates of a `WorkWeek`, with base calendars resolved so each week is
234
+ * complete. Each `Exception` is classified by its `Type` before any date is expanded. A daily exception every day
235
+ * (`Type` 1 or 7 with `Period` 1 or none), one without a `Type` or with `Type` 9, and a `DayType` 0 entry cover every
236
+ * date from `FromDate` to `ToDate`. These recurrences become their exact dates in that period: daily every N days (from
237
+ * `FromDate`), weekly every week on `DaysOfWeek`, monthly every month on day 1 to 28 or on the first to fourth or last
238
+ * Sunday to Saturday, and yearly on a day (not 29 February) or on such a position of a `Month`. With
239
+ * `EnteredByOccurrences` 1 (or `Type` 7) and a positive `Occurrences`, the first `Occurrences` dates from `FromDate` are
240
+ * taken instead of the dates up to `ToDate`. Other recurrences (weekly every two or more weeks, monthly every two or more
241
+ * months, days 29 to 31 or 29 February, positions of a day, weekday or weekend day, and `Type` 8) are left out with an
242
+ * `unsupported-calendar` warning, and an exception keeps at most 3,660 dates. The project `CalendarUID` becomes
243
+ * `defaultCalendarId` and a task's or resource's one `calendarId`. Resources (`UID`, `Name`, `Type`, `IsCostResource`,
244
+ * `MaxUnits`, `CalendarUID`) become `resources`, where `IsCostResource` 1 or `Type` 2 is a cost resource, and
245
+ * `Assignments` (`TaskUID`, `ResourceUID`, `Units`) become `assignments`; `Units` and `MaxUnits` stay fractions (1 is
246
+ * 100 %). Alternate work weeks are reported in `warnings` and left out. A working weekday without times is reported
247
+ * and left to the base calendar; an exception that is a working day without readable times is reported once, and its
248
+ * dates are days off.
249
+ *
250
+ * Not imported: notes, custom fields, baseline work and cost, lags in percent, the working-time meaning of other lags,
251
+ * resource cost rates and availability tables, assignment work, dates and contours. Throws an Error for malformed XML (with the line and column) and for a
252
+ * document whose root element is not `Project`, and a RangeError for an invalid `utcOffsetMinutes`.
253
+ */
254
+ export declare function fromMsProjectXml(xml: string, options?: MsProjectXmlOptions): MsProjectImport;
255
+ /**
256
+ * Turn the calendars of a plan, such as the result of `fromMsProjectXml`, into `WorkCalendar`s for `scheduleTasks` and
257
+ * `levelResources`: `buildWorkPeriods(range, calendar.week)` for each calendar, with the calendar's `id`. Pass the
258
+ * project's `defaultCalendarId` as `ScheduleInput.defaultCalendarId` and a task's `calendarId` as
259
+ * `ScheduleTask.calendarId`. Throws what `buildWorkPeriods` throws, for example for a range of more than 3,661 days.
260
+ */
261
+ export declare function workCalendarsFromMsProject(project: {
262
+ calendars?: readonly MsProjectCalendar[];
263
+ }, range: TimeRange): WorkCalendar[];
264
+ export interface MsProjectResourceLoadOptions {
265
+ /**
266
+ * Whole units per 100 % of a full-time resource, because `calculateResourceLoad` and `levelResources` count integer
267
+ * units while Microsoft Project uses fractions. Capacity and units are multiplied by it and rounded. Default 100, so
268
+ * one unit is 1 %; use 1 when every resource and assignment is whole-numbered.
269
+ */
270
+ unitScale?: number;
271
+ /**
272
+ * With a range, a resource with a calendar gets `periods`, the working time of that calendar inside the range, so its
273
+ * capacity is 0 outside them. Resources without a calendar are available for the whole range.
274
+ */
275
+ range?: TimeRange;
276
+ }
277
+ export interface MsProjectResourceLoad {
278
+ /** The work resources, as `calculateResourceLoad` and `levelResources` take them. */
279
+ resources: ResourceCapacity[];
280
+ /** The assignments of work resources to tasks that are not summary tasks, with `units` set. */
281
+ assignments: ResourceAssignment[];
282
+ /** `skipped-assignment` for an assignment that rounds to less than one unit. */
283
+ warnings: MsProjectImportWarning[];
284
+ }
285
+ /**
286
+ * Map the resources and assignments of a plan, such as the result of `fromMsProjectXml`, to the shapes of
287
+ * `calculateResourceLoad`, `levelResources` and `projectResourceTimeline`. Only work resources count (`type` `'work'` or
288
+ * absent); material and cost resources, and assignments to them or to summary tasks, are left out. A resource's
289
+ * `capacity` is `maxUnits` (default 1) and an assignment's `units` its `units` (default 1), both times `unitScale` and
290
+ * rounded. An assignment that rounds to 0 is left out with a warning. The input is validated like `toMsProjectXml`.
291
+ * Throws a RangeError for an invalid `unitScale`.
292
+ */
293
+ export declare function resourceLoadFromMsProject(project: MsProjectInput, options?: MsProjectResourceLoadOptions): MsProjectResourceLoad;
294
+ export interface MsProjectTimelineOptions {
295
+ /**
296
+ * The baseline set ID of a Microsoft Project baseline number. Default `baseline` for 0 and `baseline1` to
297
+ * `baseline10` for 1 to 10, as Microsoft Project names them.
298
+ */
299
+ baselineId?: (number: number) => string;
300
+ /**
301
+ * Keep the links that touch a summary task in `dependencies`, with the summary's row ID as their end, for GanttChart
302
+ * `summaryDependencies` (with `showSummaries`). Default false: they are listed in `hiddenDependencyIds` instead.
303
+ */
304
+ summaryDependencies?: boolean;
305
+ }
306
+ /** GanttChart data from `timelineFromMsProject`. */
307
+ export interface MsProjectTimeline {
308
+ rows: TimelineRow[];
309
+ bars: TimelineBar[];
310
+ /** Links between bars, with the IDs `link-1`, `link-2`, … in input order. */
311
+ dependencies: TimelineDependency[];
312
+ /**
313
+ * IDs of the links that are not in `dependencies` because one of their tasks is a summary task without a bar. Empty
314
+ * with `summaryDependencies`.
315
+ */
316
+ hiddenDependencyIds: string[];
317
+ /** Present when the plan has resources: its work resources, ready for `projectResourceTimeline`. */
318
+ resources?: ResourceTimelineResource[];
319
+ /** Present with `resources`: the assignments of those resources to bars, as `resourceLoadFromMsProject` maps them (units in percent). */
320
+ assignments?: ResourceAssignment[];
321
+ }
322
+ /**
323
+ * Turn a Microsoft Project plan, such as the result of `fromMsProjectXml` or the input of `toMsProjectXml`, into
324
+ * GanttChart rows, bars and dependencies. Every task is a row with the task ID and name, and the outline levels become
325
+ * the row hierarchy (`parentId`). A task that the next task is nested under is a summary task: its row has no bar, so
326
+ * GanttChart `showSummaries` draws it from its subtasks. Every other task gets a bar with the task ID, the name, its
327
+ * dates, `progress` (percent complete / 100), `constraints` and its baselines as named `baselines`
328
+ * (`options.baselineId`). A milestone (`milestone` or `start === end`) is a zero-length bar at its start, and an
329
+ * inactive task has `appearance: 'outline'`. Dependencies get the IDs `link-1`, `link-2`, … in input order, with
330
+ * `type` and `lag` when given; a link that touches a summary task is listed in `hiddenDependencyIds` instead, unless
331
+ * `options.summaryDependencies` keeps it in `dependencies` with the summary's row ID as its end.
332
+ *
333
+ * When the plan has `resources`, the result also has `resources` (`id`, `label` = name) and `assignments` for
334
+ * `projectResourceTimeline`, computed by `resourceLoadFromMsProject` with its default unit scale (units in percent).
335
+ *
336
+ * Throws the Errors and RangeErrors of `toMsProjectXml` for invalid tasks and dependencies, and an Error for a
337
+ * baseline set ID that is empty, `timelineBaselineId` or used for two numbers. The input is not modified.
338
+ */
339
+ export declare function timelineFromMsProject(project: MsProjectInput, options?: MsProjectTimelineOptions): MsProjectTimeline;
@@ -0,0 +1,57 @@
1
+ import { type ResourceAssignment, type ResourceCapacity, type ResourceLoadSegment } from './resourceLoad.js';
2
+ import { type ExplainedLevelResourcesResult, type ScheduleOptions } from './scheduleTrace.js';
3
+ import { type ScheduleFailure, type ScheduleInput, type ScheduleSuccess, type ScheduleTask } from './scheduling.js';
4
+ import type { TimeRange } from './timeline.js';
5
+ export interface LevelResourcesInput extends ScheduleInput {
6
+ resources: readonly ResourceCapacity[];
7
+ assignments: readonly ResourceAssignment[];
8
+ }
9
+ export interface ResourceDelay {
10
+ taskId: string;
11
+ /** Dates before leveling, with every task scheduled as soon as possible. */
12
+ before: TimeRange;
13
+ after: TimeRange;
14
+ /** `after.start - before.start`, in elapsed units. */
15
+ delay: number;
16
+ /** `capacity` when leveling constrained the task itself; `predecessor` when only a dependency moved it. */
17
+ cause: 'capacity' | 'predecessor';
18
+ /** Pauses added to a splittable task. */
19
+ pauses: readonly TimeRange[];
20
+ }
21
+ export interface LevelResourcesSuccess extends ScheduleSuccess {
22
+ /** Input tasks with the added `startNoEarlierThan` and `pauses`. `scheduleTasks` reproduces this plan from them. */
23
+ leveledTasks: readonly ScheduleTask[];
24
+ /** Tasks whose dates or work segments changed, in input order. */
25
+ delays: readonly ResourceDelay[];
26
+ /** Remaining overloaded intervals of the leveled plan, as reported by `calculateResourceLoad`. */
27
+ overloads: readonly ResourceLoadSegment[];
28
+ /** Tasks without a capacity-feasible placement within their constraints, left at their earliest dates. In input order. */
29
+ unresolvedTaskIds: readonly string[];
30
+ }
31
+ export type LevelResourcesResult = LevelResourcesSuccess | ScheduleFailure;
32
+ /**
33
+ * Delay tasks so that assigned load stays within resource capacity, using a deterministic
34
+ * priority-based serial heuristic. Each task is placed as soon as dependencies, constraints,
35
+ * calendars and remaining capacity allow; `mode` is ignored. The returned dates are those of
36
+ * `scheduleTasks` applied to the returned `leveledTasks`.
37
+ *
38
+ * Manual tasks are never moved: their capacity is reserved first, at their manual dates, and one that finds too little
39
+ * capacity there is listed in `unresolvedTaskIds`. Inactive tasks and their assignments are ignored.
40
+ *
41
+ * Capacity follows a resource's `capacityPeriods`, as in `calculateResourceLoad`, and an assignment with `workOffset` or
42
+ * `workDuration` takes capacity only during its part of the task's work at each candidate placement.
43
+ *
44
+ * Summary tasks are never placed themselves: their dates roll up from their leveled subtasks, assignments to them take
45
+ * no capacity, and they are not listed in `delays`.
46
+ *
47
+ * With `{ explain: true }`, a successful result also has a `trace`. It holds the `latest` reasons of the horizon that
48
+ * leveling may not pass and the `leveling` reasons recorded while capacity was reserved, including the resources,
49
+ * intervals and holding tasks that delayed or split a task. It does not explain the replayed `scheduleTasks` run.
50
+ */
51
+ export declare function levelResources(input: LevelResourcesInput, options?: ScheduleOptions & {
52
+ explain?: false;
53
+ }): LevelResourcesResult;
54
+ export declare function levelResources(input: LevelResourcesInput, options: ScheduleOptions & {
55
+ explain: true;
56
+ }): ExplainedLevelResourcesResult;
57
+ export declare function levelResources(input: LevelResourcesInput, options?: ScheduleOptions): LevelResourcesResult | ExplainedLevelResourcesResult;
@@ -0,0 +1,62 @@
1
+ import type { GraphEdge } from './graph.js';
2
+ import type { ScheduleSuccess, ScheduledTask } from './scheduling.js';
3
+ import type { ChartTone, NetworkNode, TimelineDependency } from './types.js';
4
+ export interface ScheduleGraphOptions {
5
+ /** Node label of a task. Defaults to the task ID. */
6
+ label?: (taskId: string) => string;
7
+ /** Time text in node details. Default UTC `YYYY-MM-DD HH:mm` of epoch milliseconds. */
8
+ formatTime?: (time: number) => string;
9
+ /** Float text in node details. Default hours of a millisecond duration, such as `1.5 h`. */
10
+ formatDuration?: (duration: number) => string;
11
+ /**
12
+ * Text of a non-zero dependency `lag` in its edge label. Default `formatDependencyLag`: signed hours of a millisecond
13
+ * lag, such as `+2 h` or `−1.5 h`. Called only for a non-zero lag.
14
+ */
15
+ formatLag?: (lag: number) => string;
16
+ /** Detail prefixes. Defaults: ES, EF and Float. */
17
+ labels?: {
18
+ earlyStart?: string;
19
+ earlyFinish?: string;
20
+ float?: string;
21
+ };
22
+ /** Tone of critical tasks. Default amber. */
23
+ criticalTone?: ChartTone;
24
+ /** Tone of the other tasks. Default blue. */
25
+ tone?: ChartTone;
26
+ }
27
+ /** `data` of a node returned by `scheduleToGraph`. */
28
+ export interface ScheduleGraphNodeData {
29
+ task: ScheduledTask;
30
+ earlyStart: number;
31
+ earlyFinish: number;
32
+ critical: boolean;
33
+ }
34
+ /** `data` of an edge returned by `scheduleToGraph`. */
35
+ export interface ScheduleGraphEdgeData {
36
+ type: NonNullable<TimelineDependency['type']>;
37
+ critical: boolean;
38
+ /** The dependency's lag; present only when it is not zero. */
39
+ lag?: number;
40
+ }
41
+ export interface ScheduleGraph {
42
+ /** One node per task, in result order, whose `data` carries the schedule values. */
43
+ nodes: NetworkNode<ScheduleGraphNodeData>[];
44
+ /** One edge per shown dependency, whose `data` carries its type, critical flag and non-zero lag. */
45
+ edges: GraphEdge<ScheduleGraphEdgeData>[];
46
+ /** IDs of the critical tasks, for example for NetworkGraph `relatedIds`. */
47
+ criticalNodeIds: Set<string>;
48
+ /** IDs of the controlling dependencies between critical tasks (`criticalDependencyIds`). */
49
+ criticalEdgeIds: Set<string>;
50
+ }
51
+ /**
52
+ * Build a PERT (activity-on-node) network diagram for NetworkGraph from a `scheduleTasks` result: one node per task,
53
+ * in result order, whose detail shows its early start, early finish and total float, and one edge per dependency with
54
+ * the dependency's ID. Critical tasks get `criticalTone` and are listed in `criticalNodeIds`; the result's
55
+ * `criticalDependencyIds` are returned as `criticalEdgeIds`. Node and edge `data` carry the schedule values
56
+ * (`ScheduleGraphNodeData`, `ScheduleGraphEdgeData`). An edge label shows the type when it is not FS and a non-zero
57
+ * lag formatted by `formatLag`, such as `SS +2 h` or `+2 h`; an FS edge without lag has no label. A dependency that
58
+ * touches a task of the result's `inactiveTaskIds` is left out, so the plan's full dependency list can be passed.
59
+ * Throws an Error for a dependency whose ends are not tasks of the result, a dependency from a task to itself, or a
60
+ * repeated dependency ID, and a RangeError for a lag that is not a finite number.
61
+ */
62
+ export declare function scheduleToGraph(result: ScheduleSuccess, dependencies: readonly TimelineDependency[], options?: ScheduleGraphOptions): ScheduleGraph;