@eightkk/vue-weave 1.0.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 (38) hide show
  1. package/CHANGELOG.md +42 -7
  2. package/CONTRIBUTING.md +13 -20
  3. package/README.ja.md +51 -37
  4. package/README.md +50 -36
  5. package/dist/{core-BH5rTsKp.js → core-C7J4FG_e.js} +5354 -2577
  6. package/dist/core.js +1 -1
  7. package/dist/index.js +6093 -3515
  8. package/dist/style.css +1 -1
  9. package/dist/types/components/EventCalendar.vue.d.ts +105 -0
  10. package/dist/types/components/GanttChart.vue.d.ts +15 -1
  11. package/dist/types/components/GraphPalette.vue.d.ts +38 -0
  12. package/dist/types/components/NetworkGraph.vue.d.ts +7 -1
  13. package/dist/types/components/PropertyInspector.vue.d.ts +41 -0
  14. package/dist/types/components/TaskBoard.vue.d.ts +72 -0
  15. package/dist/types/components/graphPalette.d.ts +12 -0
  16. package/dist/types/core/diagramEditor.d.ts +136 -0
  17. package/dist/types/core/earnedValue.d.ts +165 -0
  18. package/dist/types/core/eventCalendar.d.ts +214 -0
  19. package/dist/types/core/exportSvg.d.ts +8 -1
  20. package/dist/types/core/graph.d.ts +7 -2
  21. package/dist/types/core/graphCollapse.d.ts +1 -1
  22. package/dist/types/core/graphSwimlanes.d.ts +47 -0
  23. package/dist/types/core/index.d.ts +12 -0
  24. package/dist/types/core/interchange.d.ts +7 -0
  25. package/dist/types/core/interchangeDrawio.d.ts +60 -0
  26. package/dist/types/core/interchangeGraph.d.ts +153 -0
  27. package/dist/types/core/interchangeGraphMl.d.ts +32 -0
  28. package/dist/types/core/interchangeMermaid.d.ts +48 -0
  29. package/dist/types/core/sheetEditing.d.ts +36 -0
  30. package/dist/types/core/taskBoard.d.ts +150 -0
  31. package/dist/types/core/types.d.ts +49 -2
  32. package/dist/types/index.d.ts +44 -0
  33. package/docs/api.md +378 -0
  34. package/docs/architecture.md +6 -2
  35. package/docs/integration.md +180 -0
  36. package/docs/scheduling.md +31 -0
  37. package/docs/security.md +1 -0
  38. package/package.json +1 -1
@@ -92,6 +92,8 @@ Turn on `snapGrid` (with `background="dots"` to show the grid), `alignmentGuides
92
92
 
93
93
  A palette can add nodes in two ways. Drag and drop: make the palette items `draggable`, put an identifier in `dataTransfer`, set `droppable` on the graph and read it back in the `node-drop` event. Keyboard: let the same item be a button that adds the node at `getViewportCenter()`, because HTML drag and drop needs a pointer.
94
94
 
95
+ `GraphPalette` packages both ways (drag payload, `readPaletteDrop` and an `insert` event for Enter and Space), and `PropertyInspector` edits the selected node; see [Diagram editor parts](#diagram-editor-parts).
96
+
95
97
  ```vue
96
98
  <button type="button" draggable="true" @dragstart="$event.dataTransfer?.setData('application/x-node', 'task')"
97
99
  @click="addTask(graph!.getViewportCenter())">Add task</button>
@@ -167,6 +169,50 @@ const layout: GraphLayoutFunction = () => swimlanes.value
167
169
  - Use `edgeStyle: 'orthogonal'` with `avoidNodes` when edges skip ranks, so they go around the steps in between. Lane headers are not obstacles for `avoidNodes`; they sit before the first rank, so routes and edge labels between steps stay out of them.
168
170
  - `exportSvg`, `exportPng` and `renderGraphSvg({ lanes })` draw the bands and titles. Long titles are clipped to the header; the full title is the lane's accessible name and, in exports, its `<title>`.
169
171
 
172
+ ## BPMN processes and flowcharts
173
+
174
+ The default renderer can draw a BPMN process or a classic flowchart without slots. Node fields choose the shape (`circle`, `stadium`, `parallelogram`, `document`, `cylinder`, `data-object`, plus the earlier `diamond`, `ellipse` and `hexagon`), a BPMN event border (`event: 'start' | 'intermediate' | 'end'`), a decorative symbol (`marker`: gateway, event or task type) and where the label goes (`labelPosition: 'below'` for small events and gateways). Edges add `dashed` and the `hollow-arrow` marker for message flows. Pools (BPMN participants) come from the `pools` option of `layoutSwimlaneGraph` and the `pools` prop.
175
+
176
+ ```ts
177
+ const event = (id: string, label: string, kind: NetworkNodeEvent, lane: string): NetworkNode<{ lane: string }> =>
178
+ ({ id, label, shape: 'circle', event: kind, labelPosition: 'below', data: { lane } })
179
+ const nodes = [
180
+ event('received', 'Order received', 'start', 'sales'),
181
+ { id: 'check', label: 'Check order', shape: 'rounded', marker: 'user', data: { lane: 'sales' } },
182
+ { id: 'accept', label: 'Accept?', shape: 'diamond', marker: 'exclusive', labelPosition: 'below', data: { lane: 'sales' } },
183
+ { id: 'orders', label: 'Orders', shape: 'cylinder', data: { lane: 'sales' } },
184
+ event('closed', 'Order closed', 'end', 'customer'),
185
+ ]
186
+ // Sequence flows keep the default arrow; message flows cross pools.
187
+ const messageFlow = (id: string, from: string, to: string): GraphEdge =>
188
+ ({ id, from, to, dashed: true, markerStart: 'circle', markerEnd: 'hollow-arrow' })
189
+ const swimlanes = computed(() => layoutSwimlaneGraph(nodes, edges, {
190
+ lanes: ['customer', 'sales', 'warehouse'],
191
+ pools: [{ id: 'buyer', label: 'Customer', lanes: ['customer'] }, { id: 'supplier', label: 'Supplier', lanes: ['sales', 'warehouse'] }],
192
+ laneOf: node => node.data?.lane,
193
+ }))
194
+ ```
195
+
196
+ ```vue
197
+ <NetworkGraph :nodes="nodes" :edges="edges" :layout="layout" :lanes="swimlanes.lanes" :pools="swimlanes.pools"
198
+ edge-style="orthogonal" connectable @connect="addFlow" />
199
+ ```
200
+
201
+ - Layouts give every node the same box. Circles and diamonds look right in square boxes, so a custom `layout` function can shrink the boxes of events and gateways around their centres and keep the rest of `layoutSwimlaneGraph`'s result. Use `edge-style="orthogonal"` or `"straight"` then: those styles route every edge from the boxes and end it on the shape's outline, while the layout's own curve paths still end on the old box sides. The demo's BPMN process example (`examples/BpmnDemo.vue`) does this.
202
+ - Labels below a shape are not part of its box. Leave room with `rowGap` and `lanePadding`; long labels can overlap neighbours or edges, and the halo keeps them readable.
203
+ - Markers, event borders and shapes are decorative: the accessible name is the label (plus `detail`). If assistive technology users need the BPMN type, put it into `detail` or a tooltip.
204
+ - Connecting, selecting, dragging and deleting work as for every node; whether a new connection is a sequence flow or a message flow (for example, by comparing the pools of its ends) is the application's decision in `validateConnection` and `@connect`.
205
+ - Ports and connection handles stay on the node box, as for the other shapes.
206
+ - `exportSvg`, `exportPng` and `renderGraphSvg({ lanes, pools })` draw the same shapes, markers, labels, dashed edges and pools.
207
+
208
+ The pools add three variables, the other new parts reuse the node and edge colours. Event borders, the cylinder rim and the data object fold (`vw-node-shape-detail`) use the node's `--vw-<tone>-line` (`--vw-<tone>-ink` when hovered, focused, selected or related), markers (`vw-node-marker`) the node ink (`--vw-on-solid` when selected), labels below (`vw-node-label-below`) `--vw-text` on a `--vw-surface-muted` halo, and dashed edges (`vw-network-edge vw-is-dashed`) the edge colour. In forced-colors mode markers and lines are `CanvasText` (`HighlightText` on a selected node), labels below `CanvasText` on a `Canvas` halo, and pools `Canvas` outlined in `CanvasText` with `CanvasText` titles.
209
+
210
+ | Variable | Default | Used for |
211
+ | --- | --- | --- |
212
+ | `--vw-pool-fill` | `--vw-surface` (`#ffffff`) | Fill of a pool frame (`vw-swimlane-pool-band`) |
213
+ | `--vw-pool-header-fill` | `--vw-surface-hover` (`#e4ecf2`) | Fill of a pool title band (`vw-swimlane-pool-header`) |
214
+ | `--vw-pool-border` | `--vw-muted` (`#4c6371`) | Outline of pool frames and title bands; titles use `--vw-lane-title` |
215
+
170
216
  ## Quantity flows (Sankey diagrams)
171
217
 
172
218
  To show how much flows along each edge, such as a lot that splits and merges again or a cost allocated across departments, project the quantities with `layoutFlowGraph` and draw its bands with the `edgeBands` prop. Every band is as thick as its quantity on one scale for the whole picture, and keeps the original edge ID.
@@ -270,6 +316,15 @@ The opt-in quantity bands of NetworkGraph (`edgeBands`) stroke each band's edge
270
316
  | `--vw-flow-reference-opacity` | `.35` | Opacity of a reference (loop) band |
271
317
  | `--vw-flow-reference-dash` | `10 6`, scaled with the band width | Dash pattern of a reference band; setting it uses one pattern for every width. NetworkGraph writes the width-scaled default to an internal inline `--vw-band-dash` on each reference band; do not set that one yourself |
272
318
 
319
+ The opt-in TaskBoard component (`vw-board`) reuses the theme variables (`--vw-surface`, `--vw-surface-muted`, `--vw-border`, `--vw-text`, `--vw-muted`, `--vw-accent` and the tone families through `vw-tone-*` on each card), so the built-in dark theme and your own theme apply to it. It adds four variables; the built-in dark themes set `--vw-board-wip-warning` to `#ff8a80` and `--vw-board-drop` to `#82badf`. The board lays its columns out in a CSS grid with logical properties, so `dir="rtl"` (or an inherited right-to-left direction) places the first column on the right without extra rules. In forced-colors mode cards are outlined in `CanvasText`, the selection and focus in `Highlight`, and the drop indicator is `Highlight` (dashed `CanvasText` when the drop would exceed a WIP limit).
320
+
321
+ | Variable | Default | Used for |
322
+ | --- | --- | --- |
323
+ | `--vw-board-column-width` | `232px` (`196px` below 700 px) | Minimum width of a column; columns share any extra width |
324
+ | `--vw-board-cell-min-height` | `64px` | Minimum height of a cell, so an empty cell stays a drop target |
325
+ | `--vw-board-wip-warning` | `#a8361f` (dark `#ff8a80`) | Over-limit warning text, the count badge of a column at or over its limit and the tint of its cells |
326
+ | `--vw-board-drop` | `--vw-accent` (`#245e96`, dark `#82badf`) | Drop indicator, outline of the target cell and of a picked-up card |
327
+
273
328
  With the `group` slot, the stylesheet does not paint the slot content (the group gets `vw-has-slot`), and the transparent move handle (`vw-group-handle`) shows an `--vw-accent` outline while focused. The `minimap-node` slot content sits in a `vw-minimap-custom` group, which the minimap's rectangle fill does not reach.
274
329
 
275
330
  GanttChart editing and load overlays add `--vw-now` (now marker), `--vw-load` (load within capacity), `--vw-load-overload` (load above capacity) and `--vw-load-capacity` (dashed capacity line). Dependency lag labels (`vw-gantt-lag`) use `--vw-text` on a `--vw-surface` halo, or `--vw-dependency-highlight` for highlighted dependencies. Link handles, the dependency selection outline and the connection preview use `--vw-accent`; zoom preset buttons use `--vw-accent` and `--vw-on-solid` for the active preset.
@@ -341,6 +396,14 @@ Column resizing (`columnsResizable`) draws its separators (`vw-column-resize`) w
341
396
 
342
397
  `--vw-item-ink`, `--vw-item-line`, `--vw-item-pale` and `--vw-item-solid` are internal. The `vw-tone-*` classes set them from the tone families above, and nodes, bars and segments read them. They are not a theming API: change the tone variables (for example `--vw-blue-solid`) instead.
343
398
 
399
+ EventCalendar uses the shared theme variables (`--vw-surface`, `--vw-surface-muted`, `--vw-surface-hover`, `--vw-text`, `--vw-muted`, `--vw-border`, `--vw-grid`, `--vw-accent`, `--vw-on-solid` and `--vw-now`) and the tone families for event backgrounds, so the built-in dark themes apply to it unchanged. Its classes start with `vw-calendar-` (for example `vw-calendar-event`, `vw-calendar-column`, `vw-calendar-month-day`, `vw-calendar-preview` and `vw-calendar-now`), with the shared `vw-is-*` modifiers (`vw-is-selected`, `vw-is-editable`, `vw-is-dragging`, `vw-is-today`, `vw-is-outside` for days of another month) and `vw-continues-before` and `vw-continues-after` on events cut by a day or week boundary. Positions use logical properties, so `dir="rtl"` mirrors it without extra rules. It adds three variables:
400
+
401
+ | Variable | Default | Used for |
402
+ | --- | --- | --- |
403
+ | `--vw-calendar-gutter` | `56px` (`42px` below 700 px wide) | Width of the hour labels and the corner of the all-day row |
404
+ | `--vw-calendar-today` | `--vw-surface-hover` | Background of today's column and month day (with the `now` prop) |
405
+ | `--vw-calendar-event-accent` | the tone's `--vw-item-solid` | Accent stripe at the inline start of an event; `CalendarEvent.color` sets it per event |
406
+
344
407
  ### Class names
345
408
 
346
409
  Every class that the components emit and the stylesheet targets starts with `vw-`, so generic utility classes in the host page (for example Tailwind's `outline` or Bootstrap's `active`) cannot restyle chart elements. Element classes are named after the element (`vw-gantt-bar`, `vw-network-node`). State and variant modifiers use the `vw-is-*` form and are always combined with an element class, for example `.vw-gantt-bar.vw-is-selected` or `.vw-network-edge.vw-is-related`. Classes you add yourself, such as a `class` attribute on the component or the content of a slot, are passed through unchanged.
@@ -707,6 +770,28 @@ async function layoutWithElk(request: GraphLayoutRequest) {
707
770
  - In the `shown` request of a collapsed view, `fixedIds` and `addedIds` are passed as given; IDs of members hidden in a collapsed group are not nodes of that request and are ignored.
708
771
  - Without an engine, `layoutGraphIncrementally` from `@eightkk/vue-weave/core` does the same synchronously: it keeps every positioned node exactly and places only the new ones (see [Incremental placement](api.md#incremental-placement)). Use it as the adapter, or as a fallback when the engine fails.
709
772
 
773
+ ## Diagram files: Mermaid, GraphML and draw.io
774
+
775
+ To open a diagram drawn elsewhere, read the file as text and pass it to `fromMermaid`, `fromGraphMl` or `fromDrawioAsync` (which also reads the compressed pages draw.io saves by default). The result holds the NetworkGraph props, so commit `nodes`, `edges`, `groups`, `positions` and `sizes` as one history entry and show `warnings` to the user: they say what the file contained that NetworkGraph cannot draw (styling, other shapes, ports) and what was left out.
776
+
777
+ ```ts
778
+ import { fromDrawioAsync, fromGraphMl, fromMermaid, toDrawio } from '@eightkk/vue-weave/core'
779
+
780
+ async function openDiagram(file: File) {
781
+ const text = await file.text()
782
+ const diagram = file.name.endsWith('.graphml') ? fromGraphMl(text)
783
+ : file.name.endsWith('.drawio') ? await fromDrawioAsync(text)
784
+ : fromMermaid(text)
785
+ history.commit({ nodes: diagram.nodes, edges: diagram.edges, groups: diagram.groups, positions: diagram.positions, sizes: diagram.sizes })
786
+ return diagram.warnings
787
+ }
788
+
789
+ // Save the current state for draw.io; nodes the user never moved are placed with the layered layout.
790
+ const xml = toDrawio({ nodes, edges, groups, positions, sizes }, { pageName: 'Process', direction: 'LR' })
791
+ ```
792
+
793
+ A Mermaid file has no coordinates, so NetworkGraph lays it out; use the returned `direction` in `options`. GraphML and draw.io keep the positions and sizes of every node. Keep accepted `node-move`, `nodes-move` and `node-resize` proposals in `positions` and `sizes` so the next export carries them. The readers walk groups and chains with loops, bound their work with `maxItems`, and never expand XML entities; bound the size of uploaded files yourself as well. See [Graph interchange](api.md#graph-interchange) for the mapping of shapes, markers and IDs.
794
+
710
795
  ## Export to SVG and PNG
711
796
 
712
797
  Call `exportSvg` or `exportPng` on a component ref to save the whole chart, independent of scrolling, zoom or culling. The SVG is a standalone document string; the PNG is rasterized in the browser at the `scale` you pass.
@@ -929,3 +1014,98 @@ watch(shown, ({ nodes, edges }) => {
929
1014
  ```
930
1015
 
931
1016
  Every node that was on display keeps its box exactly; each new node goes next to its loaded neighbours on the flow side (after a predecessor, before a successor) in free space, and pages without a loaded neighbour go below the graph (for LR). A predecessor of a node at the left edge is placed beside it instead, because new boxes stay at nonnegative coordinates unless `allowNegative` is set. The camera re-fits to a larger graph while it is fitted automatically; to keep the visible nodes in place on screen too, pin it before merging a page, for example `graph.value.setViewport(graph.value.getViewport())`. The Large plan demo has this as the "Keep positions when expanding" option and shows the largest move of a shown part (0).
1017
+
1018
+ ## Spreadsheet editing in a schedule
1019
+
1020
+ Turn on `spreadsheet` on a Gantt chart with editable `columns`, and the cells work like a spreadsheet: select a rectangle with Shift+click, a mouse drag or Shift+arrows, copy, cut and paste tab-separated text with other spreadsheet applications, clear with Delete, fill down with Ctrl/Cmd+D or the corner handle, and type to edit a cell. Each operation arrives as one `sheet-edit` proposal (see [Spreadsheet editing](api.md#spreadsheet-editing) for every key and rule).
1021
+
1022
+ ```vue
1023
+ <script setup lang="ts">
1024
+ import { GanttChart, applyTimelineSheetEdit, useEditHistory, type TimelineFieldEdit, type TimelineSheetChanges } from '@eightkk/vue-weave'
1025
+
1026
+ const history = useEditHistory(initialRows)
1027
+ // One helper applies a single field edit and a whole paste, fill or clear, so each is one undo step.
1028
+ function apply(change: TimelineSheetChanges<Row>) {
1029
+ history.commit(applyTimelineSheetEdit(history.state.value, change, {
1030
+ field: (row, edit) => ({ ...row, [edit.fieldId]: edit.after }),
1031
+ cell: (row, edit) => ({ ...row, [edit.columnId]: edit.after }),
1032
+ }))
1033
+ }
1034
+ // Checks the batch as a whole, for example a total or a dependency cycle across several cells.
1035
+ const checkSheet = (change: TimelineSheetChanges<Row>) => totalHours(change) <= 40 || 'More than 40 hours in total'
1036
+ </script>
1037
+
1038
+ <template>
1039
+ <GanttChart spreadsheet :rows="history.state.value" :columns="columns" :bars="bars" :range="range"
1040
+ :validate-sheet-edit="checkSheet"
1041
+ @field-edit="(edit: TimelineFieldEdit<Row>) => apply({ fieldEdits: [edit] })"
1042
+ @cell-edit="edit => apply({ cellEdits: [edit] })"
1043
+ @sheet-edit="apply"
1044
+ @sheet-edit-rejected="reason => message = reason" />
1045
+ <p role="status">{{ message }}</p>
1046
+ </template>
1047
+ ```
1048
+
1049
+ The parent derives the bars from its rows, so the chart follows every applied change. A rejected operation changes nothing; the chart announces the reason to screen readers, and the page should show it too, as above. In the [schedule sheet demo](../examples/production/WorkSheet.vue), the grid holds start constraints, durations, predecessors, resources and progress; the bars, arrows and critical path come from `scheduleTasks`, and `validateSheetEdit` rejects a paste that would create a dependency cycle.
1050
+
1051
+ ## Diagram editor parts
1052
+
1053
+ `GraphPalette` and `PropertyInspector` (see [Diagram editor parts](api.md#diagram-editor-parts)) turn a `droppable` NetworkGraph into a small diagram editor. Both are controlled: the palette reports a drop or an `insert`, and the inspector a `change`, and the application commits each as one history entry. The gallery demo "Diagram editor" puts them together.
1054
+
1055
+ ```vue
1056
+ <script setup lang="ts">
1057
+ import { computed, ref } from 'vue'
1058
+ import {
1059
+ GraphPalette, NetworkGraph, PropertyInspector, readPaletteDrop, useEditHistory,
1060
+ type GraphDrop, type GraphPaletteItem, type GraphPoint, type InspectorChange, type InspectorField, type NetworkNode,
1061
+ } from '@eightkk/vue-weave'
1062
+
1063
+ const templates: GraphPaletteItem[] = [
1064
+ { id: 'step', label: 'Step', shape: 'box', section: 'Flow' },
1065
+ { id: 'decision', label: 'Decision', shape: 'diamond', tone: 'violet', section: 'Flow' },
1066
+ ]
1067
+ const history = useEditHistory({ nodes: [] as NetworkNode[], positions: new Map<string, GraphPoint>() })
1068
+ const graph = ref<InstanceType<typeof NetworkGraph>>()
1069
+ const selectedId = ref<string>()
1070
+ const selected = computed(() => history.state.value.nodes.find(node => node.id === selectedId.value) ?? null)
1071
+
1072
+ function add(template: GraphPaletteItem, center: GraphPoint) {
1073
+ const { nodes, positions } = history.state.value
1074
+ const id = template.id + '-' + (nodes.length + 1)
1075
+ history.commit({
1076
+ nodes: [...nodes, { id, label: template.label, shape: template.shape, tone: template.tone }],
1077
+ positions: new Map(positions).set(id, { x: Math.max(0, center.x - 72), y: Math.max(0, center.y - 29) }),
1078
+ })
1079
+ selectedId.value = id
1080
+ }
1081
+ function drop(event: GraphDrop) {
1082
+ const template = templates.find(item => item.id === readPaletteDrop(event)?.id)
1083
+ if (template) add(template, graph.value!.toGraphPoint(event.clientX, event.clientY))
1084
+ }
1085
+ const fields: InspectorField<NetworkNode>[] = [
1086
+ { id: 'label', kind: 'text', label: 'Label', get: node => node.label, required: true },
1087
+ ]
1088
+ function apply(change: InspectorChange) {
1089
+ const state = history.state.value
1090
+ history.commit({ ...state, nodes: state.nodes.map(node => node.id === change.id ? { ...node, label: String(change.after) } : node) })
1091
+ }
1092
+ </script>
1093
+
1094
+ <template>
1095
+ <GraphPalette :items="templates" searchable @insert="item => add(item, graph!.getViewportCenter())" />
1096
+ <NetworkGraph ref="graph" v-model:selected-id="selectedId" :nodes="history.state.value.nodes" :edges="[]"
1097
+ :positions="history.state.value.positions" droppable @node-drop="drop" />
1098
+ <PropertyInspector :item="selected" :fields="fields" @change="apply" />
1099
+ </template>
1100
+ ```
1101
+
1102
+ Inspector fields are typed fields, so a field definition written for a GanttChart column (`TimelineColumn.field`) needs only a `label` and a getter for the inspected item. Put validation that depends on other items, such as unique labels, in `validateChange`; its reason is shown under the field. When the selection changes, or an undo changes a value that is being edited, the inspector drops the draft instead of proposing a stale change.
1103
+
1104
+ Both components use the shared variables (`--vw-surface`, `--vw-surface-muted`, `--vw-surface-hover`, `--vw-text`, `--vw-muted`, `--vw-border` and `--vw-accent`, and the tone families for the palette previews), so `vw-theme-dark` and `vw-theme-auto` apply to them. They add two variables:
1105
+
1106
+ | Variable | Default | Used for |
1107
+ | --- | --- | --- |
1108
+ | `--vw-palette-preview-width` | `48px` | Width of the shape preview of a palette item (`vw-palette-preview`); the height follows the 48 by 30 aspect ratio |
1109
+ | `--vw-inspector-error` | `#b3261e` (`#ff8a80` in the dark themes) | Messages under inspector fields (`vw-inspector-error`) and the border of an invalid control |
1110
+
1111
+ Classes: `vw-palette`, `vw-palette-search`, `vw-palette-list`, `vw-palette-section`, `vw-palette-heading`, `vw-palette-item` (with `vw-is-active` and `vw-is-disabled`), `vw-palette-preview`, `vw-palette-label`, `vw-palette-detail`, `vw-palette-empty`; `vw-inspector`, `vw-inspector-field` (with `vw-is-<kind>`, `vw-is-readonly` and `vw-is-invalid`), `vw-inspector-label`, `vw-inspector-input`, `vw-inspector-check`, `vw-inspector-color`, `vw-inspector-swatch`, `vw-inspector-description`, `vw-inspector-error` and `vw-inspector-empty`. Layout uses logical properties, so `dir="rtl"` (or an inherited right-to-left direction with `dir="auto"`) mirrors both. In forced-colors mode palette previews are drawn in `CanvasText` on `Canvas` and messages are underlined; the filter box is not printed.
@@ -217,6 +217,37 @@ Manual tasks keep their manual dates: their actuals are kept and checked, but do
217
217
 
218
218
  The scheduling demo's **Recorded actuals** option shows a finished task that overran, a late start that ran into the lunch break and resumed, an upward revision of remaining work (**Welding needs 3 h more**) and unstarted successors whose forecast moves while every actual bar stays where it was.
219
219
 
220
+ ## Earned value management
221
+
222
+ `computeEarnedValue(tasks, options)` measures a plan's performance at a status date with earned value management (EVM). Each task brings its budget (BAC), its planned (baseline) dates, its progress share from 0 to 1 and its actual cost so far. It does not schedule: take the baseline from the plan you committed to, for example a `scheduleTasks` result or the `baseline` of a `TimelineBar`, not from today's forecast, or the schedule variance disappears.
223
+
224
+ ```ts
225
+ import { computeEarnedValue, rollupEarnedValue } from '@eightkk/vue-weave/core'
226
+
227
+ const result = computeEarnedValue([
228
+ { id: 'design', budget: 10000, start: designStart, end: designEnd, progress: 0.4, actualCost: 5000, calendarId: 'office' },
229
+ { id: 'build', budget: 20000, start: buildStart, end: buildEnd },
230
+ ], { statusDate, calendars: [{ id: 'office', periods }], series: { step: day } })
231
+ result.totals.spi // budget-weighted schedule performance index, or undefined before any planned value
232
+ const engineering = rollupEarnedValue(result.tasks.filter(task => engineeringIds.has(task.id)))
233
+ ```
234
+
235
+ The three base values:
236
+
237
+ - **Planned value (PV)** is the budget of the work the plan scheduled before the status date: `budget ×` the share of `[start, end)` that lies before the status date. With a calendar the share is measured in working time, so nothing accrues during nights, weekends or holidays; without one it is elapsed time. A task whose planned dates contain no working time of its calendar falls back to elapsed time. Before its start a task has PV 0, from its end on its whole budget. A milestone (`start === end`) accrues its whole budget at its start, so its PV is the budget once the status date reaches it.
238
+ - **Earned value (EV)** is the budget of the work done: `progress × budget`. Progress is a share of the budget, so it must reflect how much of the task's value is complete, not only how much time has passed.
239
+ - **Actual cost (AC)** is the cost spent so far, in the same unit as the budget.
240
+
241
+ The derived indicators: schedule variance `SV = EV − PV` and cost variance `CV = EV − AC` (negative is late or over budget); `SPI = EV / PV` and `CPI = EV / AC` (below 1 is late or over budget); the estimate to complete `ETC`, the estimate at completion `EAC = AC + ETC`, the variance at completion `VAC = BAC − EAC`; and the to-complete performance index `TCPI = (BAC − EV) / (BAC − AC)`, the cost efficiency the remaining work needs to finish on budget. `eacMethod` chooses how the remaining work `BAC − EV` is forecast: `'cpi'` (default, `ETC = (BAC − EV) / CPI`, so `EAC = BAC / CPI` once costs are recorded), `'cpi-spi'` (`ETC = (BAC − EV) / (CPI × SPI)`, when lateness also costs money) or `'budget'` (`ETC = BAC − EV`, when the variance so far was a one-off).
242
+
243
+ A ratio whose denominator is zero is undefined and left out of the result, never NaN or Infinity: SPI before any planned value, CPI before any cost, TCPI once the budget is spent (`AC ≥ BAC`) and `percentComplete` for a zero budget. For the ETC, an undefined CPI or SPI counts as 1, so a task without recorded cost is forecast at its budget rate; a CPI of 0 (cost but no progress) leaves ETC, EAC and VAC undefined while work remains. Once a task is complete, ETC is 0 and EAC equals AC.
244
+
245
+ Totals and summary rows add up BAC, PV, EV and AC and derive the indicators from the sums (`rollupEarnedValue`), so a total SPI or CPI is weighted by budget, and a total EAC can differ from the sum of the task EACs. Pass only leaf tasks to `computeEarnedValue`; a summary task's budget is the sum of its subtasks' budgets, and including both counts it twice. Note also that SPI returns to 1 when all work is done, however late: compare finish dates as well, for example with `comparePlans` or `rescheduleFromStatusDate`.
246
+
247
+ The `series` option returns the cumulative values for an S-curve, every `step` across the plan. PV is defined at every point. EV and AC are defined only up to the status date and come from each task's `history`: records `{ time, progress, actualCost? }` before the status date, followed by its status-date values. Between records the values hold as steps; before a task's first record it contributes 0, so a task without history adds its EV and AC only at the status date. The status date is always one of the points. The library does not forecast a curve after the status date; the demo draws a straight line from AC at the status date to the EAC.
248
+
249
+ To show the figures in GanttChart, return them from `columns` (`TimelineColumn.value`), with `rollupEarnedValue` for rows that have child rows and `showSummaries` for their rollup bars, and set the chart's `statusDate`. The **Earned value** demo combines KPI tiles, an S-curve in inline SVG, EVM columns and a status date slider.
250
+
220
251
  ## Network diagram
221
252
 
222
253
  `scheduleToGraph(result, dependencies, options?)` turns a successful result into a PERT (activity-on-node) diagram for NetworkGraph: each node shows the task's early start, early finish and total float, critical tasks get the amber tone and `criticalNodeIds`, and the controlling links are returned in `criticalEdgeIds`. Edges are labelled with the link type when it is not FS and with a non-zero `lag`, formatted by `formatLag` (default `formatDependencyLag`, such as `SS +2 h`). Pass `criticalNodeIds` as NetworkGraph `relatedIds` to highlight them. See the [API reference](api.md#network-diagram-from-a-schedule).
package/docs/security.md CHANGED
@@ -23,4 +23,5 @@ Maintainers acknowledge reports in the private advisory, investigate with the re
23
23
  - Core functions process caller-provided collections synchronously. Applications should bound untrusted input sizes and move expensive workloads off the UI thread as appropriate.
24
24
  - Scheduling and resource calculations use caller-supplied calendars and constraints. Applications must validate results against their operational requirements.
25
25
  - `parseCsv`, `fromICalendar` and `fromMsProjectXml` read untrusted files as plain strings, without a DOM, network or file access. The XML reader skips a `DOCTYPE` without reading its declarations and rejects every entity other than the five predefined ones and character references, so documents cannot load external entities or expand entity definitions. Bound the size of uploaded files yourself.
26
+ - `fromMermaid`, `fromGraphMl`, `fromDrawio` and `fromDrawioAsync` read untrusted diagram files the same way; GraphML and draw.io use that XML reader. `maxItems` (default 100,000 nodes, edges and groups) bounds what a file can make them build, and `fromDrawioAsync` stops inflating a compressed draw.io page beyond `maxInflatedLength` (default 20,000,000 characters), so a small file cannot expand without bound. Imported labels are plain text: draw.io HTML labels are reduced to their text.
26
27
  - The included static demo server binds to `127.0.0.1`. It is a local preview tool; deploy built static files through your hosting service for a public demo.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@eightkk/vue-weave",
3
- "version": "1.0.0",
3
+ "version": "1.2.0",
4
4
  "description": "Composable network graphs and interactive timelines for Vue 3.",
5
5
  "type": "module",
6
6
  "license": "MIT",