@eightkk/vue-weave 1.1.0 → 1.2.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 (36) hide show
  1. package/CHANGELOG.md +34 -7
  2. package/CONTRIBUTING.md +2 -2
  3. package/README.ja.md +45 -34
  4. package/README.md +45 -34
  5. package/dist/{core-LWK21xl4.js → core-C7J4FG_e.js} +4959 -2248
  6. package/dist/core.js +1 -1
  7. package/dist/index.js +5100 -3005
  8. package/dist/style.css +1 -1
  9. package/dist/types/components/EventCalendar.vue.d.ts +105 -0
  10. package/dist/types/components/GraphPalette.vue.d.ts +38 -0
  11. package/dist/types/components/NetworkGraph.vue.d.ts +7 -1
  12. package/dist/types/components/PropertyInspector.vue.d.ts +41 -0
  13. package/dist/types/components/TaskBoard.vue.d.ts +72 -0
  14. package/dist/types/components/graphPalette.d.ts +12 -0
  15. package/dist/types/core/diagramEditor.d.ts +136 -0
  16. package/dist/types/core/earnedValue.d.ts +165 -0
  17. package/dist/types/core/eventCalendar.d.ts +214 -0
  18. package/dist/types/core/exportSvg.d.ts +8 -1
  19. package/dist/types/core/graph.d.ts +7 -2
  20. package/dist/types/core/graphCollapse.d.ts +1 -1
  21. package/dist/types/core/graphSwimlanes.d.ts +47 -0
  22. package/dist/types/core/index.d.ts +11 -0
  23. package/dist/types/core/interchange.d.ts +7 -0
  24. package/dist/types/core/interchangeDrawio.d.ts +60 -0
  25. package/dist/types/core/interchangeGraph.d.ts +153 -0
  26. package/dist/types/core/interchangeGraphMl.d.ts +32 -0
  27. package/dist/types/core/interchangeMermaid.d.ts +48 -0
  28. package/dist/types/core/taskBoard.d.ts +150 -0
  29. package/dist/types/core/types.d.ts +26 -1
  30. package/dist/types/index.d.ts +44 -0
  31. package/docs/api.md +358 -0
  32. package/docs/architecture.md +6 -2
  33. package/docs/integration.md +147 -0
  34. package/docs/scheduling.md +31 -0
  35. package/docs/security.md +1 -0
  36. package/package.json +1 -1
package/docs/api.md CHANGED
@@ -55,6 +55,7 @@ The prop checks of GanttChart and NetworkGraph follow the same class rule: a Ran
55
55
  - [Node shapes, edge markers, animated and parallel edges](#node-shapes-edge-markers-animated-and-parallel-edges)
56
56
  - [Label editing, lasso selection and item slots](#label-editing-lasso-selection-and-item-slots)
57
57
  - [Swimlanes](#swimlanes)
58
+ - [BPMN and flowchart shapes, markers and pools](#bpmn-and-flowchart-shapes-markers-and-pools)
58
59
  - [Quantity bands](#quantity-bands)
59
60
  - [GanttChart](#ganttchart)
60
61
  - [Editing contract](#editing-contract)
@@ -78,6 +79,10 @@ The prop checks of GanttChart and NetworkGraph follow the same class rule: a Ran
78
79
  - [Row hierarchy moves, status date and progress line](#row-hierarchy-moves-status-date-and-progress-line)
79
80
  - [Scheduling constraints](#scheduling-constraints)
80
81
  - [Timeline editing helpers](#timeline-editing-helpers)
82
+ - [EventCalendar](#eventcalendar)
83
+ - [Event calendar helpers](#event-calendar-helpers)
84
+ - [TaskBoard](#taskboard)
85
+ - [Task board helpers](#task-board-helpers)
81
86
  - [Core entry point](#core-entry-point)
82
87
  - [Graph routing](#graph-routing)
83
88
  - [Layout defaults and option checks](#layout-defaults-and-option-checks)
@@ -90,9 +95,11 @@ The prop checks of GanttChart and NetworkGraph follow the same class rule: a Ran
90
95
  - [Row trees and summaries](#row-trees-and-summaries)
91
96
  - [Calendars, scheduling and resource load](#calendars-scheduling-and-resource-load)
92
97
  - [Recorded actuals](#recorded-actuals)
98
+ - [Earned value management](#earned-value-management)
93
99
  - [Interchange exports](#interchange-exports)
94
100
  - [Microsoft Project import](#microsoft-project-import)
95
101
  - [iCalendar import](#icalendar-import)
102
+ - [Graph interchange](#graph-interchange)
96
103
  - [Network diagram from a schedule](#network-diagram-from-a-schedule)
97
104
  - [Linked views](#linked-views)
98
105
  - [Time range exploration](#time-range-exploration)
@@ -108,6 +115,7 @@ The prop checks of GanttChart and NetworkGraph follow the same class rule: a Ran
108
115
  - [Export to SVG and PNG](#export-to-svg-and-png)
109
116
  - [Right-to-left layout](#right-to-left-layout)
110
117
  - [Typed data](#typed-data)
118
+ - [Diagram editor parts](#diagram-editor-parts)
111
119
 
112
120
  ## NetworkGraph
113
121
 
@@ -418,6 +426,40 @@ function moveStep(change: GraphNodeMove) {
418
426
 
419
427
  Bands do not follow saved `positions`: a node placed through `positions` outside its band stays drawn where it is, and `graphSwimlaneAt` on its box tells the application. Lanes and groups are independent; a group frame is drawn above the bands. With `dir="rtl"` the lane titles are right-aligned in their header with `direction: rtl`; like the rest of the graph geometry, the bands and headers are not mirrored (use `direction: 'RL'` in the layout for a flow from right to left, which also puts the headers on the right).
420
428
 
429
+ ### BPMN and flowchart shapes, markers and pools
430
+
431
+ Opt-in additions for BPMN processes and classic flowcharts. Without them the server markup, routes, exports and accessible names are unchanged.
432
+
433
+ | API | Behavior |
434
+ | --- | --- |
435
+ | NetworkNode.shape (flowchart shapes) | `NetworkFlowchartShape`, part of `NetworkNodeShape`: `'circle'` (a true circle centred in the box with the radius of the shorter half side, a BPMN event), `'stadium'` (a terminator: a rectangle with half-circle ends), `'parallelogram'` (input or output; the sides slant by `min(0.36 × height, width / 4)`), `'document'` (a wavy bottom that dips at the inline start and rises at the end, within the box), `'cylinder'` (a data store or database, with the front rim of its top drawn as a separate line) and `'data-object'` (a page with a folded top-right corner, also drawn as a separate line). Like diamond, ellipse and hexagon they are drawn 2 units inside the node box (an `ellipse`, `polygon` or `path` with the class `vw-node-shape`; the rim and the fold are a `path` with the class `vw-node-shape-detail`), the text is centred (a cylinder moves it down by half its rim) and clipped to the box, and the minimap, connection handles, resize handles and the focus ring keep the box. Unknown values still draw a box. |
436
+ | NetworkNode.event | `NetworkNodeEvent`: `'start'` (the normal thin border), `'intermediate'` (a second outline 4 units inside the first, class `vw-node-shape-inner` or, for the rectangle shapes, a `rect`) or `'end'` (a 3.5-unit border, class `vw-node-event-end`). The outline gets the class `vw-node-event-<event>`. Meant for `circle`, it works on every shape. Unknown values are ignored. |
437
+ | NetworkNode.marker | `NetworkNodeMarker`, a decorative BPMN symbol in the node ink (a `g` with the class `vw-node-marker`, `aria-hidden="true"` and `data-vw-marker`): the gateway symbols `'exclusive'` (×), `'parallel'` (+), `'inclusive'` (a thick circle) and `'event-based'` (a pentagon in a double circle) and the event symbols `'message'` (an envelope) and `'timer'` (a clock), centred and sized to the shorter side of the box; and the task types `'user'`, `'service'` and `'manual'`, a 16-unit icon in the top inline-start corner (top right with `dir="rtl"`, the manual hand mirrored). With a task icon, the text of a rectangle starts 30 units from the inline-start edge instead of 13. Centred symbols do not move the text, so give events and gateways `labelPosition: 'below'`. Unknown values draw nothing. |
438
+ | NetworkNode.labelPosition | `NetworkNodeLabelPosition`: `'inside'` (default) or `'below'`. Below draws the label and detail centred under the box (baselines 17 and 32 units below its bottom), outside the clipped node content (class `vw-node-label-below`), in `--vw-text` with a halo in `--vw-surface-muted`, also when the node is selected. The text is not clipped and not part of the layout box, so leave room for it (`rowGap`, `lanePadding`); `renderGraphSvg` widens its bounds for it. |
439
+ | GraphEdge.dashed | Draws the default edge with a static dash pattern (class `vw-is-dashed`, `stroke-dasharray: 5 4`; `5 4` in `renderGraphSvg`), for BPMN message flows and data associations. `animated` wins when both are set. `collapseGraphGroups` keeps it on a merged edge only when every merged edge agrees. |
440
+ | GraphEdgeMarker `'hollow-arrow'` | A triangle filled with the graph background (class `vw-edge-marker-hollow`, `surfaceMuted` in exports), the end of a BPMN message flow. A message flow is `{ dashed: true, markerStart: 'circle', markerEnd: 'hollow-arrow' }`; a data association `{ dashed: true, markerEnd: 'open-arrow' }`. |
441
+ | pools | readonly GraphSwimlanePoolBand[] / undefined. Opt-in. Pools (BPMN participants), usually the `pools` of a `layoutSwimlaneGraph` result, drawn in the lanes layer: each pool is an SVG group (role group, class `vw-swimlane-pool`, `data-vw-pool`) named by its label, with a frame (`vw-swimlane-pool-band`), a title band (`vw-swimlane-pool-header`) and the title centred in the band and clipped to it (`vw-swimlane-pool-title`), rotated by −90° to read from bottom to top when the band is taller than it is wide. The `lanes` whose IDs a pool lists in `laneIds` are drawn inside its group, after its frame; other lanes follow the pools. Pools are part of the fitted content, exportSvg and exportPng, and never take the pointer. An invalid or repeated ID (`Invalid swimlane pool ID: <value>`, `Duplicate swimlane pool ID: <id>`), a label that is not a string or `laneIds` that are not an array of IDs throw Error, and geometry that is not finite or has a negative size throws RangeError while rendering. A title band of zero size draws no band and no title. |
442
+
443
+ Where edges meet flowchart shapes: straight edges, and curve or straight edges through waypoints or spread as parallel edges, end where the line from the node centre meets the outline (curves are followed to within about 0.1 units). Unlike diamond, ellipse and hexagon, a flowchart shape need not touch the middle of every box side (a circle in a wide box, the slanted sides of a parallelogram, the wave of a document), so the ends of orthogonal routes that are not at a named port slide along their first (or last) leg onto the outline. The layout's own curve paths, and the long-edge bypass lanes the orthogonal style keeps, still end on the box sides: give circles and diamonds square boxes (a custom `layout` that shrinks their boxes, `sizes`, or square `nodeWidth` and `nodeHeight`) or use the orthogonal or straight edge style. Named ports and connection handles stay on the box sides.
444
+
445
+ `layoutSwimlaneGraph` takes the opt-in `pools` (`GraphSwimlanePoolSpec[]`: `{ id, label?, lanes }`), `poolHeaderSize` (default 32) and `poolGap` (default 24, in place of `laneGap` between lanes of different pools) options and then returns `pools` (`GraphSwimlanePool[]`, in display order: `{ id, label, index, laneIds, x, y, width, height, header }`). Every lane must belong to exactly one pool and the lanes of a pool must be consecutive in `lanes` (in any order in the pool); otherwise it throws Error (`Unknown swimlane in swimlane pool <id>: <lane>`, `Swimlane <lane> is in more than one pool`, `The lanes of swimlane pool <id> must be consecutive`, `Swimlane <lane> is in no pool`, `Swimlane pool needs at least one lane: <id>`, and the ID texts with the kind `swimlane pool`); a `poolHeaderSize` or `poolGap` that is not finite and nonnegative throws RangeError. Each pool's title band sits at the flow start before the lane headers, so every lane band starts `poolHeaderSize` later and the nodes `poolHeaderSize` further along the flow; the lane of a pool with a single lane gets a zero-size header, as a BPMN pool without lanes. TB and BT turn the pools with the lanes (the title band on top or at the bottom, read without rotation). Without `pools` the result is unchanged and has no `pools` field.
446
+
447
+ ```ts
448
+ const swimlanes = computed(() => layoutSwimlaneGraph(nodes.value, edges.value, {
449
+ lanes: [{ id: 'customer', label: 'Customer' }, { id: 'sales', label: 'Sales' }, { id: 'warehouse', label: 'Warehouse' }],
450
+ pools: [{ id: 'buyer', label: 'Customer', lanes: ['customer'] }, { id: 'supplier', label: 'Supplier', lanes: ['sales', 'warehouse'] }],
451
+ laneOf: node => node.data.lane,
452
+ }))
453
+ ```
454
+
455
+ ```vue
456
+ <NetworkGraph :nodes="nodes" :edges="edges" :layout="() => swimlanes" :lanes="swimlanes.lanes" :pools="swimlanes.pools" edge-style="orthogonal" />
457
+ ```
458
+
459
+ `renderGraphSvg` takes the same `pools` (drawn before the lanes: a `g class="vw-swimlane-pool"` with a `title`, a `surface` frame and a `surfaceMuted` title band with 1.5-unit `muted` borders and the 13-unit bold title, validated like the prop) and draws flowchart shapes (`stroke-linejoin="round"` on paths and polygons, the rim and fold as unfilled lines at most 1.5 units wide), event borders (an `end` border at least 3.5 units, an `intermediate` second outline), markers (a `g` with `fill="none"` and the stroke in the tone's ink, or `onSolid` when selected), labels below (outside the node's nested `svg`, in `text` with a `surfaceMuted` halo) and dashed edges like NetworkGraph draws them; exportSvg and exportPng follow.
460
+
461
+ Accessibility: the accessible name of a node stays its label and detail; shapes, event borders and markers are decorative and are not announced. Put the BPMN meaning that matters into the label or the `detail` (for example "Order received" with the detail "message start event"), or describe it in your own `tooltip`.
462
+
421
463
  ### Quantity bands
422
464
 
423
465
  | API | Behavior |
@@ -1031,6 +1073,143 @@ const headerBands = [
1031
1073
  ]
1032
1074
  ```
1033
1075
 
1076
+ ## EventCalendar
1077
+
1078
+ A third controlled component for appointment-style scheduling: a day or week time grid with an all-day row, a month grid, and an optional day view with one column per resource (rooms, machines, people). Like the other components it never changes its props: moves, resizes, resource changes and new events are emitted as proposals that the parent validates and applies. It is generic over the event type `E extends CalendarEvent`, inferred from `events`; its public type is `EventCalendarComponent` and its template ref type `EventCalendarExposed<E>`.
1079
+
1080
+ ```vue
1081
+ <EventCalendar
1082
+ v-model:view="view" v-model:date="date" v-model:selected-id="selectedId"
1083
+ :events="events" :resources="rooms" :now="now" time-zone="Europe/Berlin" locale="en-GB" creatable
1084
+ :validate-edit="noDoubleBooking" @edit="apply" @create="add" @range-change="load"
1085
+ />
1086
+ ```
1087
+
1088
+ | Prop | Type / default | Meaning |
1089
+ | --- | --- | --- |
1090
+ | events | readonly E[] (E extends CalendarEvent) / required | Events with `id`, `label` and a half-open `[start, end)` interval in epoch milliseconds; see below |
1091
+ | date | number / required | Anchor date of the view. Supports `v-model:date`; without a listener the calendar still navigates with local state |
1092
+ | view | `'day' \| 'week' \| 'month'` / `'week'` | Supports `v-model:view`, with local state like `date` |
1093
+ | weekStartsOn | number / 1 | First day of a week, 0 = Sunday to 6 = Saturday |
1094
+ | timeZone | string / `'UTC'` | IANA time zone of the days, hours and labels. Days start at local midnight, also across daylight-saving changes |
1095
+ | locale | string or readonly string[] / `'en-US'` | Locale of the labels. The runtime's default locale and time zone are never used, so server and client render the same text |
1096
+ | dayStart, dayEnd | integer / 0, 24 | First and last-plus-one hour of the time grid (`0 <= dayStart < dayEnd <= 24`). Events outside are clipped |
1097
+ | hourHeight | number / 48 | Pixels per hour of the time grid |
1098
+ | height | number or CSS length / 480 | Height of the scrolling time grid |
1099
+ | snap | number / 15 | Step of pointer and keyboard edits of timed events, **in minutes** |
1100
+ | createDuration | number / 4 × snap | Minutes of an event created by a click without a drag |
1101
+ | resources | readonly CalendarResource[] / undefined | `{ id, label, detail? }`. The day view shows one column per resource; events of other resources, or without `resourceId`, are not shown there. Every `resourceId` must name a resource |
1102
+ | readonly | boolean / false | Disables editing and creating |
1103
+ | creatable | boolean / false | A drag (or click) on an empty part of the time grid, the all-day row or a month day proposes a new event through `create` |
1104
+ | validateEdit, validateCreate | EventCalendarEditValidator, EventCalendarCreateValidator / undefined | Synchronous checks; see below |
1105
+ | selectedId | string / undefined | Selected event; supports `v-model:selected-id` |
1106
+ | labels | Partial<EventCalendarLabels> / English | Toolbar, view names, "All day", "+N more", hints, rejection texts, `now` and `empty` |
1107
+ | showToolbar | boolean / true | The built-in toolbar: Previous, Today, Next, the title and the view switch (a group of `aria-pressed` buttons) |
1108
+ | now | number / undefined | Draws the now line (`labels.now`) in today's column and enables Today. Supply it for deterministic and server-rendered output; the calendar never reads the clock |
1109
+ | formatTime | (time: number) => string / `intlTimeFormatter({ locale, timeZone })` | Times in event labels and accessible names |
1110
+ | maxMonthLanes | integer / 3 | Event lanes per week of the month view; more events collapse into a "+N more" button that opens the day view |
1111
+ | dir | ChartDirection / `'ltr'` | `rtl` mirrors the grid (logical CSS properties) and swaps Left and Right of the keyboard edits |
1112
+
1113
+ `CalendarEvent<D>` has `id`, `start`, `end`, `label` and the optional `allDay` (drawn in the all-day row and moved by whole days; give local midnights), `resourceId`, `color` (a CSS colour for the event's accent stripe, `--vw-calendar-event-accent`), `tone` (teal, blue, amber or violet; default blue), `editable` (default true; false keeps one event fixed) and `data` (D). Events of 24 hours or more are drawn in the all-day row too but keep their times. A zero-duration event is a point in time. Overlapping timed events are placed side by side by `layoutCalendarDayEvents`, multi-day events stacked by `packCalendarEventLanes`; both are deterministic, so the drawing does not depend on the order of `events`.
1114
+
1115
+ | Event | Payload | Meaning |
1116
+ | --- | --- | --- |
1117
+ | edit | EventCalendarEdit | `{ id, before, after, mode: 'move' \| 'start' \| 'end', source: 'pointer' \| 'keyboard', resource?: { before, after } }`, the GanttChart `TimelineEdit` shape with `resource` in place of `row`. The parent applies `after` (and `resource.after`) |
1118
+ | edit-rejected | change, reason | `validateEdit` returned false (reason `labels.rejected`) or a string |
1119
+ | create | EventCalendarCreate | `{ start, end, allDay, resourceId?, source: 'pointer' }`. The parent assigns an ID and adds the event |
1120
+ | create-rejected | proposal, reason | `validateCreate` returned false (`labels.createRejected`) or a string |
1121
+ | select, update:selectedId | id | Click or Space on an event |
1122
+ | event-activate | id, source | Double click or Enter |
1123
+ | update:date, update:view | date, view | Toolbar navigation and the month day buttons ("Show day …"), which open the day view |
1124
+ | range-change | range, view | The visible range (`eventCalendarRange` of the view and date) after mounting and whenever it changes: load the events that overlap it |
1125
+ | edit-cancel | EventCalendarEditCancel | `{ reason: 'escape' \| 'source-changed' \| 'pointer-cancel' \| 'api', eventIds }` when a pointer gesture in flight ends without a proposal |
1126
+ | validation-error | Error | Invalid events (`Invalid event ID`, `Duplicate event ID`, `RangeError: Event <id> must have finite start <= end`), resources (`Unknown resource in event <id>: <resourceId>`), view, date, weekStartsOn, time zone, hours, hourHeight, snap, createDuration, maxMonthLanes or now. The calendar then shows its empty state and rethrows the error, like GanttChart |
1127
+
1128
+ The validators follow the GanttChart contract: return true or nothing to accept, false for the default message, or a string for a specific message. A rejection emits the `-rejected` event and announces the reason in a polite live region, which also announces the new title after navigation. Validators are synchronous; persist in the `edit` or `create` listener.
1129
+
1130
+ Editing. A pointer drag moves an event (to another day or, in the resource view, another resource column); the top and bottom edges of a timed event resize its start and end in `snap` steps, measured as displacement so an off-grid start keeps its offset; the end edge of an all-day event resizes it by days. In the month view and the all-day row, events move by whole days, keeping their local times. A dashed preview follows the pointer; the proposal is emitted on release, and the click that ends a drag does not select. Keyboard edits are proposed one step per key press: on a timed event Up and Down move by `snap` and Shift+Up/Down resize the end; Left and Right move by a day, or in the resource view to the previous or next resource; in the month view and the all-day row Left and Right move by a day, Up and Down by a week (month view) and Shift+Left/Right resize the end of an all-day event. The focus follows the event after the parent applies the edit. Escape, pointer cancellation and loss of capture discard a drag; new `events`, `resources`, view, date, time zone, week start, hours, `hourHeight`, `snap` or `readonly` cancel it with reason `source-changed`. Each event is one button whose name is its label, date and time (or "All day") and resource, such as `Design review, Wed, Nov 11 10:00–11:00, Atlas`; an event drawn in several columns or weeks is focusable once.
1131
+
1132
+ Slots: `event({ event, range, selected, allDay, view })` replaces the content of an event button (use non-interactive content), `toolbar({ title, view, date, previous, next, today, setView })` replaces the toolbar content, and `empty()`. Methods: `cancelEdit()` cancels a gesture in flight (reason `api`); `scrollToTime(time)` scrolls the time grid to the time of day of `time`.
1133
+
1134
+ The component renders on the server: it reads the DOM only in event handlers and after mounting, and it creates its hint IDs with `useId()`.
1135
+
1136
+ ### Event calendar helpers
1137
+
1138
+ The core entry exports the calendar arithmetic and layout that EventCalendar uses, so a server or worker can compute the same ranges. Days follow local dates in `timeZone` (IANA, default UTC) with `weekStartsOn` (default 1); invalid views, dates, week starts and zones throw RangeError.
1139
+
1140
+ | Function | Result |
1141
+ | --- | --- |
1142
+ | `eventCalendarRange(view, date, options?)` | The half-open range a view shows: the local day, the week from `weekStartsOn`, or the whole weeks of the month grid |
1143
+ | `eventCalendarDays(view, date, options?)` | The `EventCalendarDay`s of that range (`start`, `end`, `year`, `month` 1–12, `day`, `weekday`, `inMonth`) |
1144
+ | `eventCalendarMonthGrid(date, options?)` | The month grid as four to six weeks of seven days |
1145
+ | `shiftEventCalendarDate(view, date, steps, options?)` | The anchor `steps` days, weeks or months away, keeping the local time; months clamp the day (January 31 + 1 month is the end of February) |
1146
+ | `eventCalendarTimeOfDay(day, time, options?)`, `eventCalendarTimeAt(day, timeOfDay, options?)` | Local wall-clock milliseconds since the midnight of `day`, and back. A time grid stays 24 hours tall on 23- and 25-hour days |
1147
+ | `layoutCalendarDayEvents(events, range, { minDuration? })` | `CalendarEventColumn[]`: events clipped to the day, with `column` and `columns` of their overlap group. `minDuration` extends short events for the overlap test only |
1148
+ | `packCalendarEventLanes(events, days)` | `{ segments, lanes }`: per event the lowest free `lane`, the covered `startIndex`/`endIndex` and `continuesBefore`/`continuesAfter` |
1149
+ | `validateCalendarEvents(events, resources?)` | Throws for invalid or duplicate IDs, bad intervals and unknown resources, with the texts above |
1150
+
1151
+ Related exported types: `EventCalendarView`, `CalendarEvent`, `CalendarResource`, `EventCalendarOptions`, `EventCalendarDay`, `CalendarEventColumn`, `CalendarEventLane`, `CalendarEventLaneLayout`, `EventCalendarEdit`, `EventCalendarCreate`, `EventCalendarEditValidator`, `EventCalendarCreateValidator`, `EventCalendarEditCancel`, `EventCalendarEditCancelReason`, `EventCalendarLabels`, `EventCalendarComponent` and `EventCalendarExposed`.
1152
+
1153
+ ## TaskBoard
1154
+
1155
+ An opt-in third controlled component: a kanban board that shows cards in status columns, optionally split into horizontal swimlanes. It never changes its data. A drag or keyboard move becomes a `card-move` proposal, and the parent applies it, for example with `applyBoardCardMove`. It is designed to sit next to a GanttChart on the same tasks: give the bars and the cards the same IDs and share one selected ID (see the "Task board" demo).
1156
+
1157
+ | Prop | Type / default | Meaning |
1158
+ | --- | --- | --- |
1159
+ | columns | readonly TaskBoardColumn[] / required | Status columns in display order: unique ID, label, optional detail and optional `wipLimit` (a non-negative integer) |
1160
+ | cards | readonly C[] (C extends TaskBoardCard) / required | ID, `columnId`, `laneId` (required on a board with lanes), label, optional detail, tone, `draggable` (false keeps the card in place) and data (`TaskBoardCard<D>`). The array order is the order inside every cell. C is inferred |
1161
+ | lanes | readonly TaskBoardLane[] / undefined | Horizontal swimlanes in display order: unique ID, label and optional detail. Without lanes (or with an empty array) the board has one row of cells and card `laneId`s are ignored |
1162
+ | selectedId | string / undefined | Controlled selected card, drawn with `vw-is-selected` and `aria-pressed="true"`; supports `v-model:selected-id` |
1163
+ | readonly | boolean / false | Disables moves; cards can still be selected and activated |
1164
+ | validateCardMove | TaskBoardCardMoveValidator / undefined | Synchronous check of a proposal: true or undefined accepts, false (default message `labels.moveRejected`, "This card move was rejected.") or a reason string rejects |
1165
+ | labels | Partial<TaskBoardLabels> / English | region ("Task board"), empty, emptyCell, card, cards, wipLimit, overLimit, moveHint, moveRejected, pickedUp, moved, moveCancelled, position, of and lane |
1166
+ | dir | ChartDirection / ltr | `rtl` places the first column on the right and swaps Left and Right; with `auto` the board follows the inherited direction |
1167
+ | height | number or CSS string / undefined | Height of the scroll viewport; by default the board is as tall as its content |
1168
+ | autoScroll | boolean / true | Scrolls the viewport while a pointer drag is held within 36 px of one of its edges |
1169
+
1170
+ | Event | Payload | Meaning |
1171
+ | --- | --- | --- |
1172
+ | card-move | TaskBoardCardMove | Proposal: `id`, `before` and `after` positions (`columnId`, `laneId` on a board with lanes, `index`) and `source` (`pointer` or `keyboard`). `after.index` counts the cards of the target cell without the moved card. Apply it with `applyBoardCardMove(cards, change)`. A drop on the card's own position proposes nothing |
1173
+ | card-move-rejected | (change, reason) | `validateCardMove` rejected the proposal; the reason is announced in the live region |
1174
+ | card-move-cancel | TaskBoardMoveCancel | A pick-up or drag ended without a proposal: `id`, `before`, `source` and `reason`: `escape` (Escape or the exposed `cancelMove()`), `pointer-cancel` (pointer cancellation or lost capture), `no-target` (released outside every cell), `blur` (the picked-up card lost focus) or `data-change` (`cards`, `columns`, `lanes` or `readonly` changed) |
1175
+ | card-activate | id | A card was activated by click or Enter, or by Space on a card that cannot move |
1176
+ | update:selectedId | id | The same activation, for `v-model:selected-id`; not emitted when the card is already selected |
1177
+ | validation-error | Error | Invalid columns, lanes or cards (the errors of `groupBoardCards`). The board renders its empty state and the error is rethrown, as in GanttChart |
1178
+
1179
+ Slots are `card({ card, selected, moving, column, lane })` (inside the card button, so keep it non-interactive), `column-header({ column, status })` with the `TaskBoardColumnStatus` of the column, and `empty({ column, lane })` for a cell without cards (without `column` for a board without columns). Methods are `focusCard(id)` and `cancelMove()`. The public component type is `TaskBoardComponent`, and `TaskBoardExposed<C>` types a template ref.
1180
+
1181
+ **Markup and accessibility.** The scroll viewport is a focusable `region` named `labels.region`. Each cell is a `list` named after its column, or "column · lane" on a board with lanes (for example "Doing · Web team"), and described by the column's count, WIP limit and over-limit state ("4 cards, WIP limit 3, Over WIP limit"). A card is a `button` named by its label, with `aria-pressed` for the selection; a movable card is described by `labels.moveHint`. Column headers show the count as "count / limit"; a column over its limit gets `vw-is-over-limit` and the visible `labels.overLimit` warning, and one at its limit `vw-is-at-limit`. A WIP limit never blocks a move by itself: reject such moves in `validateCardMove` if they must not happen.
1182
+
1183
+ **Pointer.** A press on a movable card and a move of 4 px start a drag with the mouse, a pen or touch (movable cards have `touch-action: none`). The card follows the pointer (`vw-is-dragging`), and a drop indicator (`vw-board-drop`, with `vw-is-over-limit` when the drop would take another column over its limit) shows the place between the cards of the cell under the pointer (`vw-is-target`). Release proposes the move; Escape, pointer cancellation and data changes cancel it. A click without a drag selects and activates the card. `cards`, `columns` and `lanes` are watched by reference: pass new arrays instead of mutating them, and keep `columns` and `lanes` out of inline template literals, which are new arrays on every render of the parent and would cancel a move in progress.
1184
+
1185
+ **Keyboard.** Space picks a movable card up (`vw-is-picked`) and announces its place ("Picked up Billing API. To do, lane API team, position 1 of 1."). Up and Down move the drop indicator through the cell and on into the previous or next lane, Left and Right to the neighbouring column in the visual direction, Home and End to the first and last place of the cell; each step is announced ("Doing, lane API team, position 1 of 3, Over WIP limit."). Space or Enter drops, Escape or moving the focus away cancels. The card keeps the focus, also after the parent applies the move and the card is drawn in its new cell. Without a pick-up, Enter activates the card and the arrow keys move the focus to the neighbouring card.
1186
+
1187
+ ```ts
1188
+ import { applyBoardCardMove, type TaskBoardCardMove } from '@eightkk/vue-weave'
1189
+
1190
+ function validateCardMove(change: TaskBoardCardMove) {
1191
+ const task = cards.value.find(card => card.id === change.id)
1192
+ return change.after.columnId !== 'done' || (task?.data?.progress ?? 0) >= 1 || 'Finish the work first.'
1193
+ }
1194
+ function moveCard(change: TaskBoardCardMove) {
1195
+ cards.value = applyBoardCardMove(cards.value, change, { columns, lanes })
1196
+ }
1197
+ // <TaskBoard v-model:selected-id="selectedId" :columns="columns" :lanes="lanes" :cards="cards"
1198
+ // :validate-card-move="validateCardMove" @card-move="moveCard" />
1199
+ // <GanttChart :rows="rows" :bars="bars" :range="range" :selected-ids="new Set(selectedId ? [selectedId] : [])"
1200
+ // @select="id => selectedId = id" />
1201
+ ```
1202
+
1203
+ ### Task board helpers
1204
+
1205
+ These functions are part of `@eightkk/vue-weave/core` and do not need Vue.
1206
+
1207
+ | Function | Result |
1208
+ | --- | --- |
1209
+ | groupBoardCards(cards, columns, lanes?) | `TaskBoardGroups`: `rows` (one per lane in lane order, or one without `laneId` when there are no lanes), each with one `TaskBoardCell` per column holding its cards in `cards` order; `columns`, one `TaskBoardColumnStatus` per column with `count` over all lanes, `wipLimit`, `atLimit` (`count >= wipLimit`) and `overLimit` (`count > wipLimit`); and `positions`, every card's `TaskBoardPosition` by ID. Throws `Invalid column ID`, `Duplicate card ID` and the like for IDs (kinds `column`, `lane` and `card`), `Unknown column in card <id>: <value>` and `Unknown lane in card <id>: <value>` (also for a missing `laneId` on a board with lanes), and a RangeError for a WIP limit that is not a non-negative integer |
1210
+ | boardCardPosition(cards, id, { lanes }?) | The `TaskBoardPosition` of one card; with `lanes: true` the index counts only the cards of the same lane. Throws `Unknown card in board: <id>` |
1211
+ | applyBoardCardMove(cards, move, { columns, lanes }?) | A new array in which the card has the target column (and lane when `after.laneId` is set) and sits before the card that had `after.index` in the target cell, or after the cell's last card. Other cards are kept as they are; the moved card is a shallow copy. A move whose positions have no `laneId` treats each column as one cell and keeps the card's `laneId`. With `columns` or `lanes`, the target must name one (`Unknown column in card move <id>: <value>`, `Unknown lane in card move <id>: <value>`). Throws an Error for an unknown card, a move that names a lane in only one position, and a stale move whose `before` is not the card's current position (`Stale card move for <id>: …`), and a RangeError for an index that is not an integer from 0 to the size of the target cell |
1212
+
1034
1213
  ## Core entry point
1035
1214
 
1036
1215
  Import pure functions and types from `@eightkk/vue-weave/core`. The Vue entry also re-exports them. Core has no Vue or DOM runtime dependency and does not mutate input data.
@@ -1077,6 +1256,8 @@ Import pure functions and types from `@eightkk/vue-weave/core`. The Vue entry al
1077
1256
  | fromMsProjectXml(xml, options?), timelineFromMsProject(project, options?) | Microsoft Project XML import: an `MsProjectImport` with tasks, links, calendars, resources, assignments and warnings, then GanttChart rows, bars and links; see [Microsoft Project import](#microsoft-project-import) |
1078
1257
  | workCalendarsFromMsProject(project, range), resourceLoadFromMsProject(project, options?) | Imported calendars as `WorkCalendar[]`, and imported resources and assignments as the shapes of `calculateResourceLoad`, `levelResources` and `projectResourceTimeline`; see [Microsoft Project import](#microsoft-project-import) |
1079
1258
  | fromICalendar(text, options?), timelineFromICalendar(events) | iCalendar import: an `ICalendarImport` with events and warnings, then GanttChart rows and bars; see [iCalendar import](#icalendar-import) |
1259
+ | toMermaid(graph, options?), toGraphMl(graph, options?), toDrawio(graph, options?) | NetworkGraph nodes, edges, nested groups, positions and sizes as a Mermaid flowchart, GraphML or an uncompressed draw.io file; see [Graph interchange](#graph-interchange) |
1260
+ | fromMermaid(text, options?), fromGraphMl(xml, options?), fromDrawio(xml, options?), fromDrawioAsync(xml, options?) | Diagram import: a `GraphInterchangeImport` with the NetworkGraph props and warnings; `fromDrawioAsync` also reads compressed draw.io pages; see [Graph interchange](#graph-interchange) |
1080
1261
  | calculateResourceLoad(range, tasks, resources, assignments, options?) | Compare scheduled work with capacity over half-open intervals. Segments with the same tasks may share one `taskIds` array. `options.inactiveTaskIds` ignores the assignments of inactive tasks |
1081
1262
  | assignmentWorkPeriods(work, assignment) | The elapsed periods of a task's `work` that an assignment covers: all of it, or the part given by `workOffset` and `workDuration`, clipped to the work |
1082
1263
  | levelResources(input) | Delay tasks with a deterministic priority heuristic so that assigned load stays within capacity |
@@ -1191,6 +1372,7 @@ Same-rank edges (inside a cycle) and self-loops of the layered, tree and swimlan
1191
1372
  | headerSize | Thickness of the header along the flow. Default 120 for LR and RL, 32 for TB and BT; 0 draws no header. |
1192
1373
  | padding | Margin around the bands. Default 20. |
1193
1374
  | crossingReduction, crossingSweeps | `barycenter` (default) or `none`; positive integer sweep limit, default 8. |
1375
+ | pools, poolHeaderSize, poolGap | Opt-in pools (BPMN participants) around consecutive lanes, the thickness of their title band (default 32) and the space between pools (default 24); see [BPMN and flowchart shapes, markers and pools](#bpmn-and-flowchart-shapes-markers-and-pools). |
1194
1376
 
1195
1377
  `GraphSwimlaneLayoutOptions` extends `GraphLayoutOptions`. Sizes that are not finite or are negative (and node sizes of 0) throw `RangeError` (see [Layout defaults and option checks](#layout-defaults-and-option-checks)), as do an unknown direction or crossing method; the graph errors of `indexGraph` (duplicate IDs, unknown endpoints) throw `Error`.
1196
1378
 
@@ -1422,6 +1604,56 @@ An `ActualsDiagnostic` has the shape of a `PlanningDiagnostic` (`id`, `code`, `s
1422
1604
 
1423
1605
  Related exported types: `RescheduleFromActualsFields`.
1424
1606
 
1607
+ ### Earned value management
1608
+
1609
+ `computeEarnedValue(tasks, options)` calculates earned value management (EVM) figures for a plan at a status date. It does not schedule anything: pass each task's budget and baseline dates, for example from a `scheduleTasks` result or a `TimelineBar` baseline, and its progress and cost so far. See [Earned value management](scheduling.md#earned-value-management) for the formulas and assumptions.
1610
+
1611
+ `EarnedValueTask`:
1612
+
1613
+ | Field | Meaning |
1614
+ | --- | --- |
1615
+ | `id` | Task ID; an invalid or duplicate ID throws an Error (`Invalid task ID: …`, `Duplicate task ID: …`) |
1616
+ | `budget` | Budget at completion (BAC), a finite number ≥ 0 in any currency or effort unit |
1617
+ | `start`, `end` | Planned (baseline) dates, half-open `[start, end)`, finite with `end ≥ start`; `end === start` is a milestone |
1618
+ | `progress` | Optional completed share at the status date, 0 to 1 like `TimelineBar.progress`. Default: the last `history` record's progress, else 0 |
1619
+ | `actualCost` | Optional actual cost (AC) up to the status date, finite and ≥ 0. Default: the last `history` record's cost, else 0 |
1620
+ | `calendarId` | Optional calendar of `options.calendars`; planned value then accrues over its working time only |
1621
+ | `history` | Optional `EarnedValueRecord[]` (`{ time, progress, actualCost? }`) before the status date, by strictly increasing `time`, for the EV and AC curves. A record without `actualCost` keeps the previous cost |
1622
+
1623
+ `EarnedValueOptions`:
1624
+
1625
+ | Option | Meaning |
1626
+ | --- | --- |
1627
+ | `statusDate` | Required finite time. PV counts the planned work in `[start, statusDate)` |
1628
+ | `calendars`, `defaultCalendarId` | `WorkCalendar[]` as for `scheduleTasks` (only `id` and `periods` are read; periods need finite endpoints and positive length, in any unit) and the calendar of tasks without `calendarId`. Without a calendar, PV accrues linearly over elapsed time |
1629
+ | `eacMethod` | `EarnedValueEacMethod`: `'cpi'` (default), `'cpi-spi'` or `'budget'` |
1630
+ | `series` | `EarnedValueSeriesOptions` `{ step, start?, end? }`: calculate the cumulative series every `step` from `start` (default: the earliest planned start) to `end` (default: the latest planned end or the status date). At most `maxEarnedValuePoints` (100,000) points |
1631
+
1632
+ `EarnedValueResult` has `statusDate`, `eacMethod`, `tasks` (an `EarnedValueTaskResult` with `id` per task, in input order), `totals` and `series`. Each task and the totals are `EarnedValueMetrics`:
1633
+
1634
+ | Field | Formula | Undefined when |
1635
+ | --- | --- | --- |
1636
+ | `bac` | `budget` | |
1637
+ | `pv` | `bac ×` planned share before the status date | |
1638
+ | `ev` | `progress × bac` | |
1639
+ | `ac` | `actualCost` | |
1640
+ | `sv`, `cv` | `ev − pv`, `ev − ac` | |
1641
+ | `spi` | `ev / pv` | `pv` is 0 |
1642
+ | `cpi` | `ev / ac` | `ac` is 0 |
1643
+ | `etc` | `(bac − ev) / index`; 0 when `ev = bac`. The index is `cpi` (`'cpi'`), `cpi × spi` (`'cpi-spi'`) or 1 (`'budget'`), where an undefined CPI or SPI counts as 1 | work remains and the index is 0 |
1644
+ | `eac` | `ac + etc` | `etc` is undefined |
1645
+ | `vac` | `bac − eac` | `eac` is undefined |
1646
+ | `tcpi` | `(bac − ev) / (bac − ac)` | `bac − ac ≤ 0` (the budget is spent) |
1647
+ | `percentComplete` | `ev / bac` | `bac` is 0 |
1648
+
1649
+ An undefined ratio is left out of the object; no field is ever NaN or Infinity. `totals` is `rollupEarnedValue(tasks, { eacMethod })`. Each `EarnedValuePoint` of `series` has `time` and `pv`, and, at points up to the status date, `ev` and `ac`; the status date is always a point inside the series range.
1650
+
1651
+ `rollupEarnedValue(items, options?)` sums `bac`, `pv`, `ev` and `ac` of any `EarnedValueAmounts[]` (such as some task results) and derives the indicators from the sums, for a summary row or any group. An empty list gives zeros. Values that are not finite numbers ≥ 0 throw a RangeError (`ev of earned value item 0 must be a finite number ≥ 0 (got -1)`).
1652
+
1653
+ Errors of `computeEarnedValue`: RangeError for `statusDate must be a finite number (got …)`, `Budget of task <id> must be a finite number ≥ 0 (got …)`, `Planned dates of task <id> must be finite with end ≥ start (got …)`, `Progress must be between zero and one: <id>` (with ` (history)` for a record), `Actual cost must be a finite number ≥ 0: <id> (got …)`, `History times of task <id> must be finite, strictly increasing and not after the status date (got …)`, `Working periods must have finite endpoints and positive length (calendar <id>)`, `series.step must be a finite number > 0 (got …)`, `series.start`/`series.end` that are not finite or end before the start, and a series with too many points; Error for tasks that are not an array, missing options, an invalid or duplicate task or calendar ID, `Unknown calendar: <id>` (with ` (task <id>)` for a task's calendar), `History must be an array: <id>`, `Invalid history record: <id>` and `Unknown EAC method: …`. The arguments are not modified.
1654
+
1655
+ GanttChart needs no new prop to show EVM figures: return them from `TimelineColumn.value(row)`, using `rollupEarnedValue` over a summary row's tasks, and pass the status date as `statusDate`. Related exported types: `EarnedValueTask`, `EarnedValueRecord`, `EarnedValueOptions`, `EarnedValueSeriesOptions`, `EarnedValueEacMethod`, `EarnedValueAmounts`, `EarnedValueMetrics`, `EarnedValueTaskResult`, `EarnedValuePoint`, `EarnedValueResult`.
1656
+
1425
1657
  ### Interchange exports
1426
1658
 
1427
1659
  The core entry builds three interchange formats as strings, and reads CSV, Microsoft Project XML and iCalendar back, without a DOM or dependencies. Save them with a `Blob` (`application/xml`, `text/calendar` or `text/csv`) or send them from a server.
@@ -1550,6 +1782,72 @@ const { rows, bars } = timelineFromICalendar(events)
1550
1782
 
1551
1783
  Related exported types: `ICalendarImportWarningCode`.
1552
1784
 
1785
+ ### Graph interchange
1786
+
1787
+ The core entry writes and reads NetworkGraph diagrams in three diagram formats, as strings, without a DOM or dependencies: Mermaid flowcharts, GraphML (including yEd files) and draw.io (diagrams.net). The writers take a `GraphInterchangeInput` (`nodes`, `edges`, optional `groups`, and `positions` with top-left corners and `sizes`, as the NetworkGraph props) and check it as NetworkGraph does, with the same Errors and RangeErrors; they never change it. The readers return a `GraphInterchangeImport`: `nodes`, `edges`, `groups` (nested with `parentId`, parents first, only groups with nodes), `positions` and `sizes` (Maps, empty for Mermaid), `direction` (Mermaid only, `TD` read as `TB`) and `warnings`. An import is itself a `GraphInterchangeInput`, so it can be written again, and its fields go straight into NetworkGraph:
1788
+
1789
+ ```ts
1790
+ import { fromDrawioAsync, toMermaid } from '@eightkk/vue-weave/core'
1791
+
1792
+ const diagram = await fromDrawioAsync(await file.text())
1793
+ for (const warning of diagram.warnings) console.warn(warning.code, warning.message)
1794
+ // <NetworkGraph :nodes="diagram.nodes" :edges="diagram.edges" :groups="diagram.groups"
1795
+ // :positions="diagram.positions" :sizes="diagram.sizes" />
1796
+ const mermaid = toMermaid(diagram, { direction: 'TD' })
1797
+ ```
1798
+
1799
+ | Export | Behavior |
1800
+ | --- | --- |
1801
+ | toMermaid(graph, options?) | A `flowchart` (`MermaidOptions.direction` `TD`, `TB`, `LR`, `RL` or `BT`, default `LR`). Nodes are declared once with their shape and quoted label (then `<br>` and the detail when there is one); groups become nested `subgraph id["label"] … end` blocks with their direct members; edges follow, with labels as `\|"label"\|`. `MermaidOptions.edgeIds` writes edge IDs as `a e1@--> b` (Mermaid 11.6 and later; default false). Positions, sizes, tones, ports, waypoints and edge styles have no Mermaid form |
1802
+ | fromMermaid(text, options?) | Reads the subset of the flowchart syntax described under **Mermaid reading** |
1803
+ | toGraphMl(graph, options?) | GraphML with `<key>` definitions for the node `label`, `detail`, `shape`, `tone`, `x`, `y`, `width` and `height` and the edge `label`, `markerStart`, `markerEnd`, `edgeStyle`, `animated` and `points` (`x,y x,y …`). Groups are nodes with a nested `<graph>` (ID `<group>:`) that holds their members and nested groups; edges are in the top-level graph. `GraphMlOptions.directed` (default true) sets `edgedefault` |
1804
+ | fromGraphMl(xml, options?) | Reads those keys (matched by `attr.name`; `name` is also read as the label; `<default>` values apply; other keys are ignored) and yEd graphics: the first `y:NodeLabel` (its first line as label, the rest as detail), `y:Geometry`, the `y:Shape` type or `y:GenericNode` configuration, and the `y:EdgeLabel`, `y:Arrows` and `y:Path` points of edges. A node with a nested graph is a group. In an undirected graph (`edgedefault="undirected"`, or `directed="false"` on the edge) an edge without a marker gets `markerEnd: 'none'` |
1805
+ | toDrawio(graph, options?) | An uncompressed `mxfile` with one page (`DrawioOptions.pageName`, default `Page-1`). Nodes are vertex cells with the label (and a line break and the detail) as value, a shape style, the tone as draw.io fill and stroke colours plus `vwTone`, and their geometry (default size 144 by 58; nodes without a position are placed with `layoutLayeredGraph` (with slots as large as the largest node size, so wide nodes do not overlap), or around the saved boxes and their sizes with `layoutGraphIncrementally` when some nodes have positions, in `DrawioOptions.direction`, default `LR`). Groups are container cells around their members, whose geometry is relative to the container. Edges carry `endArrow` and `startArrow`, the edge style, `flowAnimation=1` and their waypoints |
1806
+ | fromDrawio(xml, options?) | Reads an uncompressed `mxfile` (the first page, or `DrawioImportOptions.page` by zero-based index or by name) or a bare `mxGraphModel`. HTML labels (`html=1`) lose their markup and keep their line breaks; the first line is the label and the rest the detail. A vertex that contains vertices is a group (containers, swimlanes and `group` cells), and child geometry is made absolute. `UserObject` and `object` wrappers and text cells on edges (edge labels) are read. A compressed page throws an Error that points to `fromDrawioAsync` |
1807
+ | fromDrawioAsync(xml, options?) | `fromDrawio` that also inflates compressed pages (base64, raw deflate and URI encoding), the default of draw.io files, with the standard `DecompressionStream('deflate-raw')` of browsers, workers and Node.js (an Error where the runtime has none). `DrawioAsyncImportOptions.maxInflatedLength` (default 20,000,000 characters) bounds the inflated page; beyond it the promise rejects with a RangeError |
1808
+
1809
+ **Shapes and markers.** Each format maps the NetworkGraph shapes through one table, so a new shape is a new row:
1810
+
1811
+ | `shape` | Mermaid | draw.io style | Also read from |
1812
+ | --- | --- | --- | --- |
1813
+ | `box` (default) | `id["…"]` | `rounded=0` | Mermaid `rect`, `proc`; yEd `rectangle`; draw.io `text`, `label` |
1814
+ | `rounded` | `id("…")` | `rounded=1` | Mermaid `rounded`, `event`; yEd `roundrectangle` |
1815
+ | `diamond` | `id{"…"}` | `rhombus` | Mermaid `diam`, `decision`; yEd `diamond` and the flowchart `decision` |
1816
+ | `ellipse` | `id(("…"))` (read back as `circle`) | `ellipse` | yEd `ellipse`, `oval` |
1817
+ | `hexagon` | `id{{"…"}}` | `shape=hexagon` | Mermaid `hex`, `prepare`; yEd `hexagon` |
1818
+ | `circle` | `id(("…"))` | `ellipse;aspect=fixed;vwShape=circle` | Mermaid `circle`, `circ`, `sm-circ`, `start`, `stop`; draw.io flowchart `on-page_reference` |
1819
+ | `stadium` | `id(["…"])` | `rounded=1;arcSize=50;vwShape=stadium` | Mermaid `terminal`, `pill`; draw.io flowchart `terminator` |
1820
+ | `parallelogram` | `id[/"…"/]` | `shape=parallelogram` | Mermaid `lean-r`, `lean-l`, `in-out`; yEd `parallelogram`; draw.io flowchart `data` |
1821
+ | `document` | `id["…"]` (a box) | `shape=document` | Mermaid `doc`; draw.io flowchart `document` |
1822
+ | `cylinder` | `id[("…")]` | `shape=cylinder3` | Mermaid `cyl`, `db`, `database`; draw.io flowchart `database`, `stored_data` |
1823
+ | `data-object` | `id["…"]` (a box) | `shape=note` | `dataobject`, `card` |
1824
+
1825
+ Other shapes in a file (Mermaid subroutines and trapezoids, yEd octagons, …) are read as boxes with an `unsupported-shape` warning, and a shape the writers do not know is written as a box. The readers leave `shape` unset for boxes, except for GraphML's own `shape` key. Markers: Mermaid has `-->` for an arrow end (also for `open-arrow`, `hollow-arrow` and `diamond`, which have no Mermaid form), `---` for `markerEnd: 'none'`, `--o` for `circle` and `--x` for `bar`, with a matching start (`<-->`, `o--o`, `x--x`) when `markerStart` has the same form; draw.io uses `classic`, `open`, `block` without fill (`hollow-arrow`), `oval`, `diamond`, `dash` and `none`, and `dashed=1` for `GraphEdge.dashed` (GraphML has a `dashed` key; Mermaid does not keep it); the yEd arrow types `standard`, `delta`, `plain`, `white_delta` (as `hollow-arrow`), `circle`, `transparent_circle`, `diamond`, `white_diamond`, `dash` and `skewed_dash` are read, and other ends become arrows with an `unsupported-style` warning.
1826
+
1827
+ **Mermaid reading.** The text starts with `flowchart` or `graph` (leading spaces are allowed) (leading spaces are allowed) (also `flowchart-elk`) and an optional direction; `%%` comment lines, `%%{…}%%` directives and front matter are skipped, `maxItems` is checked as nodes and subgraphs are met and before `&` lists are expanded into edges, and statements end at a line break or `;` (an ignored statement such as `style a fill:red;` and a `subgraph` line end at their `;` outside quotes, so `subgraph g; a --> b; end` is read as one line). Read: node declarations with every Mermaid delimiter (`[ ]`, `( )`, `{ }`, `(( ))`, `{{ }}`, `([ ])`, `[[ ]]`, `[( )]`, `[/ /]`, `> ]`, …), quoted or unquoted text and `@{ shape: …, label: … }`; chains (`a --> b --> c`) and `&` lists (`a & b --> c`, every pair); the links `-->`, `---`, `-.->`, `-.-`, `==>`, `===` and their longer forms, with `o` and `x` ends, `<` starts, `|label|` or `-- label -->` text and `id@` edge IDs; and nested `subgraph id[title] … end` blocks as groups (`subgraph title` uses the title as ID, `subgraph "title"` gets `subGraph<n>`). Entity codes (`#35;`, `#quot;`) are decoded. A node belongs to the first subgraph it is mentioned in, or to a subgraph nested in that one; a mention in another subgraph is reported as `group-member`. The line style of dotted and thick links is not kept. Edges get the IDs `e1`, `e2`, … unless they have an `id@`. Ignored with an `unsupported-statement` warning (with its `line`): `classDef`, `class`, `:::class`, `style`, `click`, `linkStyle`, `direction` inside a subgraph, `accTitle`, `accDescr`, front matter and invisible `~~~` links. Another diagram type (`sequenceDiagram`, `classDiagram`, …) throws `Unsupported Mermaid diagram type: <type>`, and syntax the reader cannot follow throws `Invalid Mermaid flowchart at line <n>, column <n>: <reason>`.
1828
+
1829
+ **IDs.** Mermaid IDs cannot be quoted, so `toMermaid` writes an ID that is not ASCII letters, digits and underscores, is a Mermaid keyword (`end`, `graph`, `subgraph`, `style`, `class`, …) or starts with `vw_` as `vw_` followed by its letters and digits, with every other character as `_<hex code point>_`: `a b` becomes `vw_a_20_b` and `end` becomes `vw_end`. When it encodes an ID it writes the comment line `%% vue-weave: encoded-ids` after the header, and `fromMermaid` decodes IDs of that form only in text with that line, so IDs round-trip and the IDs of other Mermaid files are kept as written (`order` and `vw_order` stay two nodes). Nodes and groups share one ID space in Mermaid and GraphML, and all cells share one in draw.io: a group (or draw.io edge) whose ID another item already has is written with a suffix (`_g` in Mermaid, `-2` in GraphML and draw.io). GraphML and draw.io edges without an ID get `e1`, `e2`, … (skipping IDs in use).
1830
+
1831
+ **Round trips.** `fromGraphMl(toGraphMl(graph))` gives back every node, edge and group field listed above, and the positions and sizes exactly. `fromDrawio(toDrawio(graph))` does too, except that `box` shapes come back unset and every node gets a size. `fromMermaid(toMermaid(graph))` keeps IDs, labels, details, shapes, groups, edge labels and the markers that have a Mermaid form; nodes come back in declaration order (ungrouped nodes first). No format writes ports, `data`, `draggable`, `deletable`, `resizable` or the ports of edges.
1832
+
1833
+ **Warnings** (`GraphInterchangeWarning`: `code`, optional `id` of the node, edge or group, `line` for Mermaid, an English `message`):
1834
+
1835
+ | code | Cause and handling |
1836
+ | --- | --- |
1837
+ | `unsupported-statement` | A Mermaid statement that is read but ignored (see **Mermaid reading**) |
1838
+ | `unsupported-shape` | A shape NetworkGraph does not draw: read as a box |
1839
+ | `unsupported-style` | An edge end NetworkGraph does not draw: read as an arrow |
1840
+ | `unsupported-element` | GraphML hyperedges, ports and further top-level graphs; draw.io elements and cells that are neither a vertex nor an edge: left out |
1841
+ | `skipped-node`, `skipped-group` | A node or group without an ID or with an ID used before, and a group without any node (also through nested groups): left out |
1842
+ | `skipped-edge` | An edge with an ID used before, without both ends, or with an end that is not an imported node (a group or a missing node): left out |
1843
+ | `group-member` | A Mermaid node mentioned in a second subgraph: it stays in the first |
1844
+ | `invalid-value` | An unreadable or non-positive coordinate, size or waypoint, or an unknown tone or edge style: left out |
1845
+ | `shifted-positions` | Coordinates below 0 (yEd and draw.io allow them, NetworkGraph does not): every position and waypoint moves by the same amount |
1846
+
1847
+ **Untrusted files.** The GraphML and draw.io readers use the XML reader of `fromMsProjectXml` (see **Reading** under [Microsoft Project import](#microsoft-project-import)): a `DOCTYPE` is skipped, declared entities are never expanded and nothing outside the text is loaded. All readers walk nested groups and chains with loops, and `GraphInterchangeImportOptions.maxItems` (default 100,000) bounds the nodes, edges and groups together; past it the reader throws a RangeError. The readers throw an Error for malformed XML (with the line and column), a document of another kind (`Not a GraphML document`, `Not a draw.io document`, `Not a Mermaid flowchart`), a draw.io page that does not exist and a value that is not a string.
1848
+
1849
+ Related exported types: `GraphInterchangeWarningCode`, `MermaidDirection`, `MermaidOptions`, `GraphMlOptions`, `DrawioOptions`, `DrawioImportOptions`, `DrawioAsyncImportOptions`.
1850
+
1553
1851
  ### Network diagram from a schedule
1554
1852
 
1555
1853
  `scheduleToGraph(result, dependencies, options?)` turns a successful `scheduleTasks` (or `propagateEdit`, `rescheduleFromStatusDate`) result into an activity-on-node diagram for NetworkGraph. It returns a `ScheduleGraph`: `nodes` (one `NetworkNode<ScheduleGraphNodeData>` per task in result order, with ID, label, a detail with the early start, early finish and total float, and `data` of type `ScheduleGraphNodeData`: `task`, `earlyStart`, `earlyFinish` and `critical`), `edges` (one `GraphEdge<ScheduleGraphEdgeData>` per dependency with the dependency's ID, a label and `data` of type `ScheduleGraphEdgeData`: `type`, `critical` and, only for a non-zero lag, `lag`), `criticalNodeIds` and `criticalEdgeIds` (the result's `criticalDependencyIds`). Because the arrays carry these data types, `graph.nodes[0].data?.critical` and `graph.edges[0].data?.lag` are typed without casts, and NetworkGraph slots and events infer the same data types. Critical tasks get the `criticalTone` (default amber) and the others the `tone` (default blue). For an ALAP task the early dates are `earliestStart` and `earliestEnd`. An edge label shows the dependency type when it is not FS and a non-zero `lag` formatted by `formatLag`, separated by a space: `SS`, `+2 h`, `SS +2 h` or `FF −0.5 h` (a lead). An FS dependency without lag, or with a lag of 0, has no label. A dependency that touches a task listed in the result's `inactiveTaskIds` is left out, so the plan's full dependency list can be passed; a manual task is a node like any other, with zero float.
@@ -2007,3 +2305,63 @@ chart.value?.exportSvg({ barLabel: bar => `${bar.label} ${bar.data?.cost}` })
2007
2305
  ```
2008
2306
 
2009
2307
  The public component types are `NetworkGraphComponent` and `GanttChartComponent`. Core helpers that return the items they receive keep their types as well: `moveTimelineRow`, `indentTimelineRow`, `outdentTimelineRow`, `removeTimelineBars`, `assignLanes`, `createTimelineRowTree`, `collapseGraphGroups`, `removeGraphElements`, `cloneGraphElements`, `searchGraphNodes` and `filterGraph`, and the label callbacks of `renderGraphSvg` and `renderTimelineSvg`.
2308
+
2309
+ ## Diagram editor parts
2310
+
2311
+ Two small controlled components for building a diagram editor around NetworkGraph: `GraphPalette`, a list of node templates to drag onto the graph or insert from the keyboard, and `PropertyInspector`, a form generated from typed field definitions for the selected item. Both are exported from the Vue entry with their public component types (`GraphPaletteComponent`, `PropertyInspectorComponent`) and template ref types (`GraphPaletteExposed`, `PropertyInspectorExposed`); their data types and `graphPaletteMimeType` are also in `@eightkk/vue-weave/core`. Neither changes the graph or the item: the application applies what they report, for example as one `useEditHistory` entry. Both render on the server, take `dir` (`ltr`, `rtl` or `auto`, as for the charts; `rtl` writes `dir="rtl"` and adds `vw-rtl`, `auto` writes nothing and follows the inherited direction) and follow the dark themes.
2312
+
2313
+ ### GraphPalette
2314
+
2315
+ | API | Behavior |
2316
+ | --- | --- |
2317
+ | items | readonly GraphPaletteItem<D>[] / required. `id` (unique, the ID rule of [Validation and errors](#validation-and-errors) with the kind `palette item`), `label`, optional `detail`, `shape` (`NetworkNodeShape`, drawn in a 48 by 30 preview with the node outlines of NetworkGraph; default `box`), `tone` (default `blue`), `section`, `keywords`, `disabled` and `data`. D is inferred and reaches the `item` slot and `insert`. |
2318
+ | searchable | boolean / false. Shows a filter box (`type="search"`) above the list. Every word of the text must occur, ignoring case, in the label, detail, section or keywords of an item. ArrowDown in the box focuses the first shown item; Escape clears a non-empty filter. When nothing matches, a `role="status"` paragraph says so (`labels.noMatches`). |
2319
+ | labels | Partial<GraphPaletteLabels> / English. `region` (accessible name of the list, default `Shape palette`), `search` (`Filter shapes`) and `noMatches`. |
2320
+ | dir | ChartDirection / `ltr`. |
2321
+ | insert(item) | Enter or Space on a focused, enabled item: the keyboard alternative to dragging it, because HTML drag and drop needs a pointer. Held keys do not repeat it. Add the node at `getViewportCenter()` of the graph. |
2322
+ | item slot | `{ item, active }`. Replaces the preview, label and detail of an item; the option element, its keyboard handling and its drag stay. |
2323
+ | focusItem(id?) | Exposed method. Focuses an item (default: the one with the tab stop) and resolves to false when it is not shown. |
2324
+
2325
+ The list is a `listbox` of `option` elements; items with a `section` are grouped under a heading in a `group` named by it, in the order of each section's first item, and items without one are listed without a heading. One option takes the tab stop (`tabindex="0"`, `aria-selected="true"`, class `vw-is-active`): the last focused item while it is shown, else the first shown one. ArrowUp, ArrowDown, Home and End move focus between the shown items. A `disabled` item is listed with `aria-disabled="true"`, is not draggable and does not emit `insert`.
2326
+
2327
+ Each enabled item is `draggable`. On `dragstart` it puts the JSON text `{ "id": ..., "data": ... }` under `graphPaletteMimeType` (`application/x-vue-weave-palette+json`; `data` is left out when it cannot be serialised) and its label under `text/plain`, with `effectAllowed = 'copy'`. `readPaletteDrop(source)` (Vue entry; it reads a `DataTransfer`) takes the `node-drop` event of a `droppable` NetworkGraph, the `bar-drop` event of GanttChart or a `DataTransfer` and returns `{ id, data? }`, or undefined for a drop without a palette payload, with malformed JSON or without a non-empty string `id`. Any page can start a drag with this type, so look the ID up in your own items rather than trusting `data`.
2328
+
2329
+ ```vue
2330
+ <GraphPalette :items="templates" searchable @insert="item => addNode(item, graph!.getViewportCenter())" />
2331
+ <NetworkGraph ref="graph" :nodes="nodes" :edges="edges" :positions="positions" droppable
2332
+ @node-drop="drop => { const hit = readPaletteDrop(drop); const item = templates.find(t => t.id === hit?.id); if (item) addNode(item, graph!.toGraphPoint(drop.clientX, drop.clientY)) }" />
2333
+ ```
2334
+
2335
+ Related exported types: `GraphPaletteItem`, `GraphPaletteLabels`, `GraphPaletteDrop`, `PaletteDropSource`.
2336
+
2337
+ ### PropertyInspector
2338
+
2339
+ | API | Behavior |
2340
+ | --- | --- |
2341
+ | item | T / null / undefined (T extends `InspectorItem`, `{ id: string }`). The inspected item; without one the form shows `labels.empty` or the `empty` slot. T is inferred from `item` and `fields`. |
2342
+ | fields | readonly InspectorField<T>[] / required. A [typed field](#typed-fields-and-timeline-views) (`TimelineFieldSpec`: `required`, `choices`, `multiple`, `min`, `max`, `integer`, `parse`, `format`, `timeZone`, and so on) whose `get(item)` returns the raw value, plus `label`, `kind`, optional `readonly`, `description` and `placeholder`. IDs follow the ID rule with the kind `inspector field`; an unknown kind is a RangeError and a `select` without `choices` an Error, thrown while rendering. |
2343
+ | validateChange | (change, item) => boolean / string / void. Synchronous. False or a reason rejects the change: the reason (or `labels.rejected`) is shown under the field and `change-rejected` is emitted. |
2344
+ | labels | Partial<PropertyInspectorLabels> / English. `region` (accessible name of the form, default `Properties`), `empty`, `rejected` and `none` (the empty choice of an optional select, `(none)`). |
2345
+ | dir | ChartDirection / `ltr`. |
2346
+ | change(change) | InspectorChange: `id` (the item), `field` (the field ID), `before` and `after` (`FieldValue`). Emitted for a committed value that passes the field checks and `validateChange` and differs from `before` (`fieldValuesEqual`). The parent updates the item to accept. |
2347
+ | change-rejected(change, reason) | A change refused by `validateChange`. |
2348
+ | field-<id> slot | PropertyInspectorFieldSlot<T>: `field`, `item`, `value`, `text`, `error`, `readonly`, `inputId` (the ID the label points to), `describedBy`, and `commit(value)`, `commitText(text)` and `cancel()`, which run the same checks as the built-in controls. Replaces the control of one field; its label, description and message stay. |
2349
+ | empty slot | Replaces the empty-state text. |
2350
+ | focusField(id) | Exposed method. Focuses the control of a field; returns false when it is not shown. |
2351
+ | cancelEdits() | Exposed method. Drops every draft and message without a proposal. |
2352
+
2353
+ Controls by `kind`: `text`, `number`, `time` and `duration` are text inputs (`inputmode="decimal"` for numbers and durations) parsed with `parseFieldValue` and shown with `formatFieldValue`; `select` is a `select` (a multiple one with `multiple`), `checkbox` a checkbox and `color` a colour input whose value is lowercase `#rrggbb` text (the built-in parser of a `color` field accepts `#rgb` and `#rrggbb`). A `readonly` text field is a `readonly` input; other read-only controls are disabled. Every control is named by its `label` element and described by the field's `description` and message (`aria-describedby`); an invalid field has `aria-invalid="true"` and its message is a `role="alert"` paragraph.
2354
+
2355
+ Text is a draft until it is committed with Enter or on blur; Escape drops the draft and its message; when there was one, the key does not propagate further. A parse or check failure (`required`, `range`, the colour format, a custom parser) keeps the draft and shows the message without emitting anything; a rejected draft is not proposed again on blur. Selects, checkboxes and colour inputs commit on `change`, and the control returns to the current value until the parent applies the change, so a rejected or ignored change leaves the old value. The form never shows a value the item does not have once a draft is gone.
2356
+
2357
+ Stale source data cancels an edit: when `item` changes to another ID, every draft and message is dropped; when the value under a draft or message changes (an undo, a collaborator, another view), that draft or message is dropped without a proposal. Drafts of fields whose value did not change are kept.
2358
+
2359
+ ```ts
2360
+ const fields: InspectorField<MyNode>[] = [
2361
+ { id: 'label', kind: 'text', label: 'Label', get: node => node.label, required: true },
2362
+ { id: 'shape', kind: 'select', label: 'Shape', get: node => node.shape ?? 'box', required: true, choices: [{ value: 'box' }, { value: 'diamond' }] },
2363
+ { id: 'accent', kind: 'color', label: 'Accent', get: node => node.data?.accent ?? null },
2364
+ ]
2365
+ ```
2366
+
2367
+ Related exported types: `InspectorItem`, `InspectorField`, `InspectorFieldKind`, `InspectorChange`, `InspectorChangeValidator`, `PropertyInspectorLabels`, `PropertyInspectorFieldSlot`.
@@ -6,7 +6,7 @@ The package has three boundaries.
6
6
  - src/components owns measurement, SVG/HTML rendering, local camera/scroll state and transient pointer previews. Persistent selection and accepted schedule data belong to the parent.
7
7
  - examples contains business data and validation. Components do not import examples.
8
8
 
9
- Planning screens around the components (an unplanned-task backlog, an inspector, a diagnostics list, a context toolbar, typed cell editors, save-status and conflict messages) are reference implementations in `examples/components/` and the planning demos. They are not part of the package: the library adds only core functions, composables and the props, events, slots and methods of the two components that such screens need, and the stylesheet styles only states the components draw themselves (highlights and selected load segments).
9
+ Planning screens around the components (an unplanned-task backlog, an inspector, a diagnostics list, a context toolbar, typed cell editors, save-status and conflict messages) are reference implementations in `examples/components/` and the planning demos. They are not part of the package: the library adds only core functions, composables and the props, events, slots and methods of the components that such screens need, and the stylesheet styles only states the components draw themselves (highlights and selected load segments).
10
10
 
11
11
  ## Three models
12
12
 
@@ -36,6 +36,10 @@ This is a deterministic layout baseline. Dense edge sets and cycles can produce
36
36
 
37
37
  Lanes are a separate, display-only input of NetworkGraph (`lanes`) rather than groups: a group frame follows its member nodes, cannot be empty and moves its members when dragged, while a lane band has geometry of its own that spans the whole flow, exists without nodes and never moves anything. The bands are one layer below the group frames, part of the fitted content, the minimap and the export, and never take the pointer. The component does not interpret lane membership; `graphSwimlaneAt` lets the application map a `node-move` proposal to a lane and apply its own rules. Lane headers are not obstacles for `avoidNodes`; they lie before the first rank, outside the routes between nodes.
38
38
 
39
+ ### Flowchart shapes and pools
40
+
41
+ The flowchart and BPMN shapes share one internal geometry module with the earlier outline shapes (`graphShapes.ts`), used by the default renderer, edge routing and `renderGraphSvg`, so all three draw and clip the same outline. Straight-line clipping and the orthogonal end correction intersect the outline as a polygon (curves sampled finely, circles exactly), because these shapes need not touch the middle of every box side. Event borders, markers and labels below the box are decoration of the default renderer only: they change neither the box nor the routes, and markers are `aria-hidden`. Pools are, like lanes, display-only geometry from `layoutSwimlaneGraph`: the layout adds a title band per pool before the lane headers and a gap between pools, and NetworkGraph draws each pool as a group around its own lanes.
42
+
39
43
  ### Asynchronous layouts
40
44
 
41
45
  The `layout` prop stays synchronous. `useAsyncGraphLayout` turns the input into the same requests NetworkGraph would make (`buildGraphLayoutRequests`: a `shown` request and, with collapsed groups, an `expanded` one), each identified by a request ID and an input key that covers nodes, edges, ports, sizes, positions, groups, the collapsed set, direction, settings and a caller revision. A display frame holds one input together with its layouts and changes only when every layout of that input is ready, so nodes are never drawn with another input's geometry; late, cancelled and superseded results are dropped. The `layout` function it returns reads the displayed frame and keeps its identity, so a new frame neither re-fits the camera nor, while NetworkGraph reports a gesture in flight (`gesture-start` and `gesture-end`, bound through `gestureListeners`), cancels it. Nothing is requested during server rendering; an optional synchronous `initialLayout` gives the server and the first client render the same frame.
@@ -88,7 +92,7 @@ Scheduling constraints on bars are display data with an editing contract like th
88
92
 
89
93
  ## Component internals
90
94
 
91
- The two components keep rendering, measurement and gesture handling in their single-file components. Pure arithmetic lives in plain TypeScript modules beside them, which the package does not export, so it can be read and tested without the component.
95
+ The components keep rendering, measurement and gesture handling in their single-file components. Pure arithmetic lives in plain TypeScript modules beside them, which the package does not export, so it can be read and tested without the component.
92
96
 
93
97
  - `src/components/networkGraph/`: the drag-preview layout (`previewLayout(context, change)` layers the changed boxes, paths and labels over the saved layout and records which nodes and edges changed, so only those items update), the `avoidNodes` preview rerouting index, group frame geometry, port keys, the move, snap and resize arithmetic, and the default node and marker drawings.
94
98
  - `src/components/ganttChart/`: geometry and windowing, prop validation, the edit arithmetic for keys, drag to create and `cascade`, row hierarchy moves and the tooltip composable. One `Gesture` record holds the pointer gesture in flight; previews stay in their own reactive refs.