@eightkk/vue-weave 0.0.0-stage → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (82) hide show
  1. package/CHANGELOG.md +525 -0
  2. package/CONTRIBUTING.md +116 -0
  3. package/LICENSE +21 -0
  4. package/README.ja.md +278 -0
  5. package/README.md +275 -2
  6. package/THIRD_PARTY_NOTICES.md +25 -0
  7. package/dist/core-LWK21xl4.js +13672 -0
  8. package/dist/core.js +1 -0
  9. package/dist/index.js +8505 -0
  10. package/dist/style.css +2 -0
  11. package/dist/types/components/GanttChart.vue.d.ts +353 -0
  12. package/dist/types/components/NetworkGraph.vue.d.ts +252 -0
  13. package/dist/types/components/types.d.ts +27 -0
  14. package/dist/types/composables/useAsyncGraphLayout.d.ts +163 -0
  15. package/dist/types/composables/useEditHistory.d.ts +13 -0
  16. package/dist/types/composables/useEditTransaction.d.ts +46 -0
  17. package/dist/types/composables/useLinkedSelection.d.ts +118 -0
  18. package/dist/types/composables/useTimelineView.d.ts +24 -0
  19. package/dist/types/composables/useWindowedData.d.ts +83 -0
  20. package/dist/types/core/actuals.d.ts +170 -0
  21. package/dist/types/core/calendarFormat.d.ts +65 -0
  22. package/dist/types/core/editTransaction.d.ts +96 -0
  23. package/dist/types/core/exportSvg.d.ts +236 -0
  24. package/dist/types/core/fieldEditing.d.ts +114 -0
  25. package/dist/types/core/graph.d.ts +196 -0
  26. package/dist/types/core/graphAlgorithms.d.ts +51 -0
  27. package/dist/types/core/graphAnalysis.d.ts +96 -0
  28. package/dist/types/core/graphCollapse.d.ts +62 -0
  29. package/dist/types/core/graphCrossings.d.ts +25 -0
  30. package/dist/types/core/graphEditing.d.ts +52 -0
  31. package/dist/types/core/graphExpansion.d.ts +71 -0
  32. package/dist/types/core/graphFlow.d.ts +184 -0
  33. package/dist/types/core/graphForce.d.ts +29 -0
  34. package/dist/types/core/graphGeometry.d.ts +31 -0
  35. package/dist/types/core/graphIncremental.d.ts +93 -0
  36. package/dist/types/core/graphLasso.d.ts +15 -0
  37. package/dist/types/core/graphLayoutRequests.d.ts +218 -0
  38. package/dist/types/core/graphLayouts.d.ts +81 -0
  39. package/dist/types/core/graphObstacleRouting.d.ts +68 -0
  40. package/dist/types/core/graphPortRules.d.ts +111 -0
  41. package/dist/types/core/graphRouting.d.ts +84 -0
  42. package/dist/types/core/graphSnapping.d.ts +34 -0
  43. package/dist/types/core/graphSpatial.d.ts +49 -0
  44. package/dist/types/core/graphSwimlanes.d.ts +77 -0
  45. package/dist/types/core/graphTraversal.d.ts +51 -0
  46. package/dist/types/core/graphView.d.ts +73 -0
  47. package/dist/types/core/index.d.ts +76 -0
  48. package/dist/types/core/interchange.d.ts +6 -0
  49. package/dist/types/core/interchangeCsv.d.ts +75 -0
  50. package/dist/types/core/interchangeICalendar.d.ts +111 -0
  51. package/dist/types/core/interchangeMsProject.d.ts +339 -0
  52. package/dist/types/core/leveling.d.ts +57 -0
  53. package/dist/types/core/pert.d.ts +62 -0
  54. package/dist/types/core/placement.d.ts +100 -0
  55. package/dist/types/core/planComparison.d.ts +275 -0
  56. package/dist/types/core/resourceLoad.d.ts +65 -0
  57. package/dist/types/core/resourceTimeline.d.ts +179 -0
  58. package/dist/types/core/rowHierarchy.d.ts +25 -0
  59. package/dist/types/core/scheduleDiagnostics.d.ts +37 -0
  60. package/dist/types/core/scheduleModel.d.ts +187 -0
  61. package/dist/types/core/scheduleTrace.d.ts +118 -0
  62. package/dist/types/core/scheduling.d.ts +194 -0
  63. package/dist/types/core/sheetEditing.d.ts +36 -0
  64. package/dist/types/core/snapshot.d.ts +388 -0
  65. package/dist/types/core/statusDate.d.ts +36 -0
  66. package/dist/types/core/timeRangeTargets.d.ts +67 -0
  67. package/dist/types/core/timeline.d.ts +194 -0
  68. package/dist/types/core/timelineView.d.ts +101 -0
  69. package/dist/types/core/types.d.ts +805 -0
  70. package/dist/types/core/viewBindings.d.ts +112 -0
  71. package/dist/types/core/windowedData.d.ts +255 -0
  72. package/dist/types/core/workCalendar.d.ts +41 -0
  73. package/dist/types/core/workingTimeScale.d.ts +33 -0
  74. package/dist/types/index.d.ts +52 -0
  75. package/docs/api.md +2009 -0
  76. package/docs/architecture.md +112 -0
  77. package/docs/code-of-conduct.md +24 -0
  78. package/docs/integration.md +964 -0
  79. package/docs/scheduling.md +586 -0
  80. package/docs/security.md +26 -0
  81. package/docs/third-party-licenses.md +33 -0
  82. package/package.json +79 -4
@@ -0,0 +1,236 @@
1
+ import { type GraphEdge, type GraphLayout } from './graph.js';
2
+ import { type GraphSwimlaneBand } from './graphSwimlanes.js';
3
+ import { type GraphEdgeBand } from './graphFlow.js';
4
+ import { type DependencyPathStyle, type TimeRange, type TimeScale } from './timeline.js';
5
+ import type { ChartTone, NetworkNode, TimelineBand, TimelineBar, TimelineColumn, TimelineDependency, TimelineLoadRow, TimelineLoadSegment, TimelineMarker, TimelineMarkerRange, TimelineRow } from './types.js';
6
+ import type { TimelineConstraintKind } from './types.js';
7
+ /** Colours of one tone, matching the `--vw-<tone>-*` custom properties. */
8
+ export interface SvgToneColors {
9
+ ink: string;
10
+ line: string;
11
+ pale: string;
12
+ solid: string;
13
+ }
14
+ /** Colours used by the SVG exporters. Each field mirrors a `--vw-*` custom property. */
15
+ export interface SvgExportTheme {
16
+ surface: string;
17
+ surfaceMuted: string;
18
+ text: string;
19
+ muted: string;
20
+ border: string;
21
+ grid: string;
22
+ edge: string;
23
+ accent: string;
24
+ onSolid: string;
25
+ /** Text colour on marker and now-flag labels. */
26
+ markerInk: string;
27
+ /** The single baseline, and the first slot when several baseline sets are drawn (`--vw-baseline`). */
28
+ baseline: string;
29
+ /** The second baseline slot (`--vw-baseline-2`). Defaults to `defaultSvgExportTheme.baseline2`. */
30
+ baseline2?: string;
31
+ /** The third baseline slot (`--vw-baseline-3`). Defaults to `defaultSvgExportTheme.baseline3`. */
32
+ baseline3?: string;
33
+ marker: string;
34
+ now: string;
35
+ load: string;
36
+ loadOverload: string;
37
+ loadCapacity: string;
38
+ dependencyHighlight: string;
39
+ /** Non-working time shading (`--vw-non-working`). Optional for compatibility; defaults to `defaultSvgExportTheme.nonWorking`. */
40
+ nonWorking?: string;
41
+ /** Outline of critical bars (`--vw-critical`). Defaults to `defaultSvgExportTheme.critical`. */
42
+ critical?: string;
43
+ /** Float lines (`--vw-float`). Defaults to `defaultSvgExportTheme.float`. */
44
+ float?: string;
45
+ /** Deadline indicators and the late outline (`--vw-deadline`). Defaults to `defaultSvgExportTheme.deadline`. */
46
+ deadline?: string;
47
+ /** Status-date line and progress line (`--vw-status`). Defaults to `defaultSvgExportTheme.status`. */
48
+ status?: string;
49
+ /** Scheduling constraint markers (`--vw-constraint`). Defaults to `defaultSvgExportTheme.constraint`. */
50
+ constraint?: string;
51
+ /** Violated constraint markers (`--vw-constraint-violated`). Defaults to `defaultSvgExportTheme.constraintViolated`. */
52
+ constraintViolated?: string;
53
+ /** Fill of marker ranges without a tone (`--vw-range`). Defaults to `defaultSvgExportTheme.range`. */
54
+ range?: string;
55
+ /** Label text of marker ranges without a tone (`--vw-range-ink`). Defaults to `defaultSvgExportTheme.rangeInk`. */
56
+ rangeInk?: string;
57
+ /** Edge line of marker range labels without a tone (`--vw-range-line`). Defaults to `defaultSvgExportTheme.rangeLine`. */
58
+ rangeLine?: string;
59
+ tones: Record<ChartTone, SvgToneColors>;
60
+ }
61
+ /** A partial theme; omitted colours fall back to `defaultSvgExportTheme`. */
62
+ export type SvgExportThemeInput = Partial<Omit<SvgExportTheme, 'tones'>> & {
63
+ tones?: Partial<Record<ChartTone, Partial<SvgToneColors>>>;
64
+ };
65
+ /** The stylesheet's fallback colours. */
66
+ export declare const defaultSvgExportTheme: Readonly<Required<SvgExportTheme>>;
67
+ /** Options shared by the SVG exporters. */
68
+ export interface SvgExportOptions {
69
+ /** Colours; omitted values use `defaultSvgExportTheme`. */
70
+ theme?: SvgExportThemeInput;
71
+ /** CSS font-family list written on the root element. */
72
+ fontFamily?: string;
73
+ /** Document title, written as `<title>` and the accessible name. */
74
+ title?: string;
75
+ /** Paint an opaque background. Default true. */
76
+ background?: boolean;
77
+ /** Prefix for the IDs of markers and clip paths, so several exports can be inlined in one page. Default `vw-export`. */
78
+ idPrefix?: string;
79
+ /** Text direction of labels. For timelines, `rtl` also mirrors the time axis and places row headings on the right. */
80
+ direction?: 'ltr' | 'rtl';
81
+ }
82
+ /** Escape text for XML content and attribute values and drop characters that XML 1.0 does not allow. */
83
+ export declare function escapeXml(value: string): string;
84
+ /** A group rectangle in layout coordinates, for example the groups NetworkGraph draws. */
85
+ export interface GraphSvgGroup {
86
+ id: string;
87
+ label: string;
88
+ x: number;
89
+ y: number;
90
+ width: number;
91
+ height: number;
92
+ }
93
+ /** `N` and `E` type the nodes and edges that the label callbacks receive. */
94
+ export interface GraphSvgOptions<N extends NetworkNode = NetworkNode, E extends GraphEdge = GraphEdge> extends SvgExportOptions {
95
+ /** Group rectangles drawn behind the nodes. */
96
+ groups?: readonly GraphSvgGroup[];
97
+ /**
98
+ * Swimlane bands drawn behind the groups, edges and nodes, each with its title clipped to its header area, for
99
+ * example the `lanes` of a `layoutSwimlaneGraph` result. Throws like NetworkGraph `lanes` for invalid lanes.
100
+ */
101
+ lanes?: readonly GraphSwimlaneBand[];
102
+ /** Node IDs drawn in the selected style. */
103
+ selectedIds?: Iterable<string>;
104
+ /** Node IDs whose box gets the highlight outline, like NetworkGraph `highlightedNodeIds`. Unknown IDs are ignored. */
105
+ highlightedNodeIds?: Iterable<string>;
106
+ /** Edge IDs drawn as highlighted edges, like NetworkGraph `highlightedEdgeIds`. Unknown IDs are ignored. */
107
+ highlightedEdgeIds?: Iterable<string>;
108
+ /** Colour of highlighted nodes and edges. Defaults to the theme's `dependencyHighlight`. */
109
+ highlightColor?: string;
110
+ /** Margin around the content, in pixels. Default 16. */
111
+ padding?: number;
112
+ /** Node title text. Defaults to `node.label`. */
113
+ nodeLabel?: (node: N) => string;
114
+ /** Node detail text. Defaults to `node.detail`. */
115
+ nodeDetail?: (node: N) => string | undefined;
116
+ /** Edge label text. Defaults to `edge.label`. */
117
+ edgeLabel?: (edge: E) => string | undefined;
118
+ /**
119
+ * Edges drawn as bands with real width, like the NetworkGraph `edgeBands` prop (for example `graphFlowBands` of a
120
+ * `layoutFlowGraph` result): a translucent stroke of the band width without markers, dashed for a reference band,
121
+ * with the band label as its `<title>`. Bands are drawn widest first, before the other edges, so thin bands stay
122
+ * visible. Unknown IDs are ignored. Throws RangeError for a width that is not finite and at least 0.
123
+ */
124
+ edgeBands?: ReadonlyMap<string, GraphEdgeBand>;
125
+ }
126
+ /**
127
+ * Build a standalone SVG document of a whole graph with the default node rendering. Every node, edge, label and
128
+ * group is included regardless of any camera or culling. Node shapes and edge markers are drawn like NetworkGraph draws
129
+ * them; hollow markers are filled with the theme's `surfaceMuted`, and animated edges are dashed without motion. Throws
130
+ * RangeError for an unknown edge marker. Runs without a DOM.
131
+ */
132
+ export declare function renderGraphSvg<N extends NetworkNode, E extends GraphEdge>(layout: GraphLayout, nodes: readonly N[], edges: readonly E[], options?: GraphSvgOptions<N, E>): string;
133
+ /** `R` and `B` type the rows and bars that `columns`, `rowLabel` and `barLabel` receive. */
134
+ export interface TimelineSvgOptions<R extends TimelineRow = TimelineRow, B extends TimelineBar = TimelineBar> extends SvgExportOptions {
135
+ /** Collapsed parent rows; their descendants and the descendants' bars are omitted. */
136
+ collapsedIds?: Iterable<string>;
137
+ /** Export only this time window. Defaults to the whole scale, from `toTime(0)` to `toTime(width)`. */
138
+ timeRange?: TimeRange;
139
+ /** Export only displayed rows `start` (inclusive) to `end` (exclusive), counted after collapsing. */
140
+ rowRange?: {
141
+ start: number;
142
+ end: number;
143
+ };
144
+ /** Default 66. At least 8 + laneCount × 14. */
145
+ rowHeight?: number;
146
+ /** Default 1. */
147
+ laneCount?: number;
148
+ /** Width of the row heading column in pixels. Default 154. */
149
+ labelWidth?: number;
150
+ /** Extra columns after the row heading column. */
151
+ columns?: readonly TimelineColumn<R>[];
152
+ /** Draw rollup bars on parent rows without bars of their own. */
153
+ showSummaries?: boolean;
154
+ /**
155
+ * As GanttChart `summaryDependencies`: a dependency end may name a summary row instead of a bar. Such an end joins
156
+ * the start or finish edge of the row's rollup bar, so it is drawn only with `showSummaries` and when the row has a
157
+ * rollup (descendant bars and no bar of its own); otherwise the dependency is left out. Default false.
158
+ */
159
+ summaryDependencies?: boolean;
160
+ headerBands?: readonly (readonly TimelineBand[])[];
161
+ markers?: readonly TimelineMarker[];
162
+ /**
163
+ * Highlighted half-open ranges, as GanttChart `markerRanges`: a band across the body (or across `rowIds` only) with
164
+ * its label at the bottom of the header, drawn with its tone or the `range` theme colours at 70% opacity.
165
+ */
166
+ markerRanges?: readonly TimelineMarkerRange[];
167
+ /** Time of a "now" line. */
168
+ now?: number;
169
+ /** Tick interval. Defaults to the first of `tickSteps` that is at least 76 px wide. */
170
+ tickStep?: number;
171
+ /** Candidate tick intervals. Default 30 minutes to 24 hours in milliseconds. */
172
+ tickSteps?: readonly number[];
173
+ /** Tick alignment. Defaults to the start of the scale. */
174
+ tickAnchor?: number;
175
+ /** Tick and tooltip labels. Default UTC HH:mm. */
176
+ formatTime?: (time: number) => string;
177
+ /** Text of the label drawn on a dependency with a non-zero `lag`. Default `formatDependencyLag` (signed hours of milliseconds). */
178
+ formatLag?: (lag: number) => string;
179
+ /**
180
+ * Baseline sets to draw, in slot order, as GanttChart `baselineIds`: at most `timelineBaselineLimit` unique IDs, with
181
+ * `timelineBaselineId` for `TimelineBar.baseline`. Default: the first three of `timelineBaselineIds(bars)`.
182
+ */
183
+ baselineIds?: readonly string[];
184
+ /** Label of a baseline set in titles. Default "Baseline" for `timelineBaselineId` and the set ID otherwise. */
185
+ baselineLabel?: (id: string) => string;
186
+ /** Text of a baseline variance in titles. Default `formatDependencyLag` (signed hours of milliseconds). */
187
+ formatVariance?: (delta: number) => string;
188
+ /** Words before the start, finish and duration variances in titles. Defaults "start", "finish" and "duration". */
189
+ varianceLabels?: {
190
+ start?: string;
191
+ finish?: string;
192
+ duration?: string;
193
+ };
194
+ /** Heading of the row column. Default "Rows". */
195
+ rowHeading?: string;
196
+ /** Label of the now line. Default "Now". */
197
+ nowLabel?: string;
198
+ loadRows?: readonly TimelineLoadRow[];
199
+ loadSegments?: readonly TimelineLoadSegment[];
200
+ /** Default 44. At least 16. */
201
+ loadRowHeight?: number;
202
+ highlightedDependencyIds?: Iterable<string>;
203
+ /** Shape of the dependency connectors, as GanttChart `dependencyStyle`. Default `orthogonal`. */
204
+ dependencyStyle?: DependencyPathStyle;
205
+ /**
206
+ * Bars drawn with the highlight outline and the `vw-is-highlighted` class, as GanttChart `highlightedBarIds`. The
207
+ * outline uses the `dependencyHighlight` theme colour.
208
+ */
209
+ highlightedBarIds?: Iterable<string>;
210
+ /** Half-open intervals shaded as non-working time behind the grid, over the task and load rows. May overlap. */
211
+ nonWorkingPeriods?: readonly TimeRange[];
212
+ /** Time of a status-date line. */
213
+ statusDate?: number;
214
+ /** Label of the status-date line. Default "Status date". */
215
+ statusDateLabel?: string;
216
+ /** With `statusDate`, draw a progress line that kinks to the progress point of each bar that is behind or ahead. */
217
+ showProgressLine?: boolean;
218
+ /**
219
+ * Text of each constraint kind in the titles of constraint markers. Defaults "Start no earlier than", "Start no later
220
+ * than", "Finish no earlier than", "Finish no later than" and "Must start on".
221
+ */
222
+ constraintLabels?: Partial<Record<TimelineConstraintKind, string>>;
223
+ /** Added to the title of a violated constraint marker. Default "violated". */
224
+ constraintViolatedLabel?: string;
225
+ /** Bar label text. Defaults to `bar.label`. */
226
+ barLabel?: (bar: B) => string;
227
+ /** Row heading text. Defaults to `row.label`. */
228
+ rowLabel?: (row: R) => string;
229
+ }
230
+ /**
231
+ * Build a standalone SVG document of a timeline with the default rendering: row headings and columns, header bands
232
+ * and ticks, bars with progress, milestones, baselines, summaries, dependencies, markers, marker ranges, the now line and
233
+ * load rows.
234
+ * Every displayed row is included (collapsed descendants are omitted) unless `rowRange` narrows it. Runs without a DOM.
235
+ */
236
+ export declare function renderTimelineSvg<R extends TimelineRow, B extends TimelineBar>(rows: readonly R[], bars: readonly B[], dependencies: readonly TimelineDependency[], scale: TimeScale, options?: TimelineSvgOptions<R, B>): string;
@@ -0,0 +1,114 @@
1
+ import type { TimelineRow } from './types.js';
2
+ export type FieldPrimitive = string | number | boolean | null;
3
+ /** An array is a multiple selection. `null` is the empty value. */
4
+ export type FieldValue = FieldPrimitive | readonly FieldPrimitive[];
5
+ export type TimelineFieldKind = 'text' | 'number' | 'time' | 'duration' | 'select' | 'checkbox';
6
+ export interface FieldChoice {
7
+ value: string | number;
8
+ label?: string;
9
+ }
10
+ /** What a duration field edits: wall-clock time or time on the work calendar. */
11
+ export type FieldDurationBasis = 'elapsed' | 'working';
12
+ export interface TimelineFieldSpec<R extends TimelineRow = TimelineRow> {
13
+ id: string;
14
+ kind: TimelineFieldKind;
15
+ /** Raw value of the row. `column.value` only supplies display text. */
16
+ get: (row: R) => FieldValue;
17
+ /** Custom text parser. It replaces the built-in parser for the kind. */
18
+ parse?: (text: string) => FieldValue | {
19
+ error: string;
20
+ };
21
+ /** Custom formatter. It replaces the built-in formatter for the kind. */
22
+ format?: (value: FieldValue) => string;
23
+ required?: boolean;
24
+ /**
25
+ * Allowed options for `select`. The built-in formatter shows a choice's `label` (else its value) and the built-in
26
+ * parser reads a label or a value back; see {@link parseFieldValue} for how duplicate labels are resolved.
27
+ */
28
+ choices?: readonly FieldChoice[];
29
+ /**
30
+ * `select` only: accept an array of choices. The built-in formatter joins the entries with `, ` and writes an entry
31
+ * that is empty, contains a comma or a double quote, or starts or ends with whitespace in double quotes, with inner
32
+ * quotes doubled (as in CSV). The built-in parser splits the text at unquoted commas and reads each entry like a
33
+ * single selection.
34
+ */
35
+ multiple?: boolean;
36
+ /** Inclusive lower bound for `number`, `time` and `duration`. */
37
+ min?: number;
38
+ /** Inclusive upper bound for `number`, `time` and `duration`. */
39
+ max?: number;
40
+ /** `number` only: require an integer. */
41
+ integer?: boolean;
42
+ /** `duration` only: accept negative values. Other kinds are not restricted unless `min` says so. */
43
+ allowNegative?: boolean;
44
+ /**
45
+ * `time` only: IANA time zone name (for example `Asia/Tokyo`) used for text without an offset. Daylight saving
46
+ * is applied; a skipped wall time resolves to the transition and a repeated one to its earlier occurrence.
47
+ * The built-in formatter appends the offset (for example `2026-11-01 01:30 -05:00`) to a wall time that occurs
48
+ * twice, so formatted text parses back to the same instant. Takes precedence over `utcOffsetMinutes`.
49
+ */
50
+ timeZone?: string;
51
+ /**
52
+ * `time` only: fixed offset from UTC in minutes (for example 540 for UTC+09:00). The built-in parser
53
+ * and formatter never use the runtime's local time zone. Without it, `parse` and `format` are required
54
+ * for `time` fields (unless `timeZone` is set); an offset written in the text itself (`Z`, `+09:00`) wins over this one.
55
+ */
56
+ utcOffsetMinutes?: number;
57
+ /** `duration` only: whether the value is elapsed or working time. Surfaced for editors to display. */
58
+ durationBasis?: FieldDurationBasis;
59
+ /** `duration` only: model units in one displayed unit (3600000 for hours when the model uses milliseconds). Default 1. */
60
+ unitSize?: number;
61
+ /** `duration` only: optional suffix such as `h`, appended when formatting and accepted when parsing. */
62
+ unitLabel?: string;
63
+ }
64
+ export interface TimelineFieldEdit<R extends TimelineRow = TimelineRow> {
65
+ rowId: R['id'];
66
+ columnId: string;
67
+ fieldId: string;
68
+ before: FieldValue;
69
+ after: FieldValue;
70
+ source: 'pointer' | 'keyboard';
71
+ }
72
+ export type FieldErrorCode = 'required' | 'invalid' | 'negative' | 'range' | 'integer' | 'choice' | 'time-zone' | 'custom';
73
+ export type FieldCheck = {
74
+ ok: true;
75
+ } | {
76
+ ok: false;
77
+ code: FieldErrorCode;
78
+ error: string;
79
+ };
80
+ export type FieldParseResult = {
81
+ ok: true;
82
+ value: FieldValue;
83
+ } | {
84
+ ok: false;
85
+ code: FieldErrorCode;
86
+ error: string;
87
+ };
88
+ /** True when two field values are equal; arrays compare element by element and in order. */
89
+ export declare function fieldValuesEqual(a: FieldValue, b: FieldValue): boolean;
90
+ /**
91
+ * Read editor text into a field value. Empty text (after trimming) is `null`, or a `required` error;
92
+ * `0` and negative numbers are values, not empty. The result is also checked with {@link validateFieldValue}.
93
+ *
94
+ * The built-in parsers read what {@link formatFieldValue} writes, so formatting a valid value and parsing the text
95
+ * gives the same value back:
96
+ * - `select`: a choice's label, or its value. A label that exactly one choice shows wins over a value. Text that
97
+ * matches several choices (a shared label with no single matching value) is a `choice` error; the formatter then
98
+ * shows values instead. With `multiple`, the text is split at unquoted commas into an array, in order. An entry in
99
+ * double quotes (`"Cut, weld"`, with `""` for a quote inside) is read exactly, commas and surrounding whitespace
100
+ * included; unquoted entries are trimmed. An empty unquoted entry (`a,,b`) or an unclosed quote is `invalid`.
101
+ * Throws an Error when some choice has no text that names it (its label and value both read as other choices).
102
+ * - `time` with `timeZone`: a trailing offset (`-05:00`, `Z`) picks one occurrence of a repeated wall time; without
103
+ * one, the earlier occurrence is used.
104
+ */
105
+ export declare function parseFieldValue(spec: TimelineFieldSpec<any>, text: string): FieldParseResult;
106
+ /** Check a value against the spec. `null` is empty: valid unless `required`. */
107
+ export declare function validateFieldValue(spec: TimelineFieldSpec<any>, value: FieldValue): FieldCheck;
108
+ /**
109
+ * Turn a field value into editor text. `null` becomes an empty string; `0` stays `0`. The built-in formats read back
110
+ * with {@link parseFieldValue}: a `select` shows each choice by its label unless the label does not name it (then by
111
+ * its value), a multiple `select` quotes entries that contain a comma, a quote or surrounding whitespace, and a `time`
112
+ * with `timeZone` appends the offset to a wall time that occurs twice.
113
+ */
114
+ export declare function formatFieldValue(spec: TimelineFieldSpec<any>, value: FieldValue): string;
@@ -0,0 +1,196 @@
1
+ import { type GraphRoutingPolicy } from './graphGeometry.js';
2
+ import type { GraphEdgeStyle } from './graphRouting.js';
3
+ export interface GraphPort {
4
+ id: string;
5
+ side: 'left' | 'right' | 'top' | 'bottom';
6
+ direction?: 'source' | 'target' | 'both';
7
+ offset?: number;
8
+ label?: string;
9
+ }
10
+ export interface IdentifiedNode {
11
+ id: string;
12
+ ports?: readonly GraphPort[];
13
+ }
14
+ /** An edge between two nodes. `D` types the optional `data` payload; it defaults to `unknown`. */
15
+ export interface GraphEdge<D = unknown> extends GraphConnection {
16
+ id: string;
17
+ label?: string;
18
+ /** Application data. The components pass it through untouched. */
19
+ data?: D;
20
+ /**
21
+ * Optional waypoints in chart coordinates. `routeGraphEdges` (and NetworkGraph) draws the edge through them: a
22
+ * polyline in the straight and orthogonal styles and a smooth curve through the points in the curve style.
23
+ */
24
+ points?: readonly GraphPoint[];
25
+ /** Routing style of this edge. Overrides the NetworkGraph `edgeStyle` prop and the `style` option of `routeGraphEdges`. */
26
+ edgeStyle?: GraphEdgeStyle;
27
+ /** Decoration at the target end, drawn by NetworkGraph and `renderGraphSvg`. Default `'arrow'`. */
28
+ markerEnd?: GraphEdgeMarker;
29
+ /** Decoration at the source end, drawn by NetworkGraph and `renderGraphSvg`. Default `'none'`. */
30
+ markerStart?: GraphEdgeMarker;
31
+ /**
32
+ * Draws the default NetworkGraph edge with a dash pattern that flows from source to target (class `vw-is-animated`),
33
+ * still under `prefers-reduced-motion: reduce` and in print. `renderGraphSvg` draws it dashed without motion.
34
+ */
35
+ animated?: boolean;
36
+ }
37
+ /**
38
+ * A decoration at one end of an edge. `arrow` is the filled arrowhead NetworkGraph has always drawn, `open-arrow` a
39
+ * line arrowhead, `circle` and `diamond` hollow shapes filled with the graph background, `bar` a line across the edge
40
+ * and `none` no decoration.
41
+ */
42
+ export type GraphEdgeMarker = 'arrow' | 'open-arrow' | 'circle' | 'diamond' | 'bar' | 'none';
43
+ export interface GraphIndex {
44
+ incoming: Map<string, string[]>;
45
+ outgoing: Map<string, string[]>;
46
+ }
47
+ export declare function indexGraph(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[]): GraphIndex;
48
+ export declare function graphNeighborhood(index: GraphIndex, id: string, maxHops?: number): Set<string>;
49
+ export interface GraphBox {
50
+ x: number;
51
+ y: number;
52
+ width: number;
53
+ height: number;
54
+ rank: number;
55
+ }
56
+ /**
57
+ * Optional metadata of one routed edge, which an external layout or router can return next to its SVG path. The
58
+ * `preserve` routing policy uses it to check that a kept route still starts and ends where the edge does: at the named
59
+ * port when the edge has one, on the given box side, and at the same points as the path.
60
+ */
61
+ export interface GraphLayoutRoute {
62
+ /** First point of the route, on the source box border (at the source port when the edge has one). */
63
+ start: GraphPoint;
64
+ /** Last point of the route, on the target box border (at the target port when the edge has one). */
65
+ end: GraphPoint;
66
+ /** The source port the route leaves from; it must equal the edge's `fromPort`. */
67
+ fromPort?: string;
68
+ /** The target port the route enters; it must equal the edge's `toPort`. */
69
+ toPort?: string;
70
+ /** The side of the source box the route leaves through (its first direction of travel is away from it). */
71
+ fromSide?: GraphPort['side'];
72
+ /** The side of the target box the route enters through (its last direction of travel is into it). */
73
+ toSide?: GraphPort['side'];
74
+ /** Bend points between `start` and `end`, in order. */
75
+ points?: readonly GraphPoint[];
76
+ }
77
+ export interface GraphLayout {
78
+ boxes: Map<string, GraphBox>;
79
+ paths: Map<string, string>;
80
+ edgeLabels: Map<string, {
81
+ x: number;
82
+ y: number;
83
+ }>;
84
+ width: number;
85
+ height: number;
86
+ /**
87
+ * Optional route metadata by edge ID. The built-in layouts do not set it. When a layout has it, `applyGraphPositions`,
88
+ * `applyGraphSizes`, `routeGraphPorts` and `routeGraphEdges` carry it into their results: entries of edges that a
89
+ * moved or resized node rerouted are removed, and entries of edges that the port or style routing redrew are replaced.
90
+ */
91
+ routes?: Map<string, GraphLayoutRoute>;
92
+ }
93
+ /** LR and TB are the defaults; RL and BT mirror them so ranks grow right-to-left or bottom-to-top. */
94
+ export type GraphLayoutDirection = 'LR' | 'TB' | 'RL' | 'BT';
95
+ /** Ordering heuristic that reduces edge crossings between adjacent ranks. */
96
+ export type GraphCrossingReduction = 'none' | 'barycenter' | 'median';
97
+ /**
98
+ * Options shared by the rank-based layouts (layered, tree, swimlane and incremental). Defaults: direction LR, nodes
99
+ * 144 by 58, columnGap 50, rowGap 24, padding 20. Sizes must be finite numbers > 0 and gaps and padding finite
100
+ * numbers ≥ 0, otherwise the layout throws a RangeError that names the option.
101
+ */
102
+ export interface GraphLayoutOptions {
103
+ /** Flow direction: ranks grow along it. Default 'LR'. */
104
+ direction?: GraphLayoutDirection;
105
+ /** Width of a node box. Default 144. */
106
+ nodeWidth?: number;
107
+ /** Height of a node box. Default 58. */
108
+ nodeHeight?: number;
109
+ /** Free space between ranks along the flow (between depth levels in the tree layout). Default 50. */
110
+ columnGap?: number;
111
+ /** Free space between neighbouring boxes of one rank across the flow (between adjacent leaves in the tree layout, between nodes of one lane in one rank in the swimlane layout). Default 24. */
112
+ rowGap?: number;
113
+ /** Margin around the layout. Default 20. */
114
+ padding?: number;
115
+ }
116
+ /** Options accepted by layoutLayeredGraph: the shared layout options plus opt-in crossing reduction. */
117
+ export interface GraphLayeredLayoutOptions extends GraphLayoutOptions {
118
+ /** Opt-in reordering of nodes within each rank. Default 'none' keeps input order. */
119
+ crossingReduction?: GraphCrossingReduction;
120
+ /** Maximum number of alternating down/up sweeps when crossingReduction is enabled. Default 8. */
121
+ crossingSweeps?: number;
122
+ }
123
+ /**
124
+ * Deterministic layered layout. Ranks come from the condensation of the strongly connected components, so every node of
125
+ * a cycle shares one rank: a large cycle becomes a single column (or row for TB and BT) whose length grows with the
126
+ * number of nodes, and the edges inside it use same-rank side routes. A 5,000-node cycle with the default sizes is
127
+ * about 214 by 410,000 units. Break or filter large cycles before layout (findGraphCycles finds them), or use
128
+ * layoutForceGraph, when that shape is not wanted.
129
+ */
130
+ export declare function layoutLayeredGraph(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[], options?: GraphLayeredLayoutOptions): GraphLayout;
131
+ export interface GraphPoint {
132
+ x: number;
133
+ y: number;
134
+ }
135
+ export interface GraphNodeMove {
136
+ id: string;
137
+ before: GraphPoint;
138
+ after: GraphPoint;
139
+ }
140
+ export interface GraphConnection {
141
+ from: string;
142
+ to: string;
143
+ fromPort?: string;
144
+ toPort?: string;
145
+ }
146
+ export interface GraphReconnect {
147
+ id: string;
148
+ before: GraphConnection;
149
+ after: GraphConnection;
150
+ }
151
+ export interface GraphGroup {
152
+ id: string;
153
+ label: string;
154
+ nodeIds: readonly string[];
155
+ }
156
+ /** The point of a port on a box side. Throws Error when `port.side` is not left, right, top or bottom. */
157
+ export declare function graphPortAnchor(box: GraphBox, port: GraphPort): GraphPoint;
158
+ /**
159
+ * Where an edge meets its node. A named port gives its anchor. Otherwise, when the edge has an `id` and the layout
160
+ * has a path for it, the drawn start or end point of that path is used, with the box side closest to it. Without a
161
+ * path the side follows `direction`. Rendering and editing handles therefore agree after nodes are moved or when a
162
+ * custom layout chooses its own sides. Throws an Error naming the edge and the node when the node has no layout box,
163
+ * and an Error naming the node and the port when the port side is not left, right, top or bottom.
164
+ */
165
+ export declare function graphEdgeEndpoint(layout: GraphLayout, nodes: ReadonlyMap<string, IdentifiedNode>, edge: GraphConnection, end: 'from' | 'to', direction: GraphLayoutDirection): {
166
+ side: "left" | "right" | "top" | "bottom";
167
+ x: number;
168
+ y: number;
169
+ };
170
+ /** Options of `routeGraphPorts`. */
171
+ export interface GraphPortRouteOptions {
172
+ /**
173
+ * Default 'builtin': every edge with a named port is redrawn as a curve between its port anchors. 'preserve' keeps the
174
+ * route of a port edge that the layout drew itself when it still starts and ends at its ports (see `isGraphRouteValid`),
175
+ * and redraws only the others, such as the edges of a moved or resized node or of a changed port.
176
+ */
177
+ policy?: GraphRoutingPolicy;
178
+ }
179
+ /**
180
+ * Route named endpoints after the node layout and any saved positions are applied. With `policy: 'preserve'`, valid
181
+ * routes from the layout are kept. Throws RangeError for an unknown policy.
182
+ */
183
+ export declare function routeGraphPorts(layout: GraphLayout, nodes: ReadonlyMap<string, IdentifiedNode>, edges: readonly GraphEdge[], direction: GraphLayoutDirection, options?: GraphPortRouteOptions): GraphLayout;
184
+ /** Apply saved positions without changing the original layout or untouched routes. */
185
+ export declare function applyGraphPositions(layout: GraphLayout, edges: readonly GraphEdge[], positions: ReadonlyMap<string, GraphPoint>, direction?: GraphLayoutDirection): GraphLayout;
186
+ /** A node size for the `applyGraphSizes` overlay, in chart units. */
187
+ export interface GraphNodeSize {
188
+ width: number;
189
+ height: number;
190
+ }
191
+ /**
192
+ * Apply saved node sizes on top of a layout (after any positions), keeping each box's top-left corner. Edges that touch
193
+ * a resized node are rerouted like moved ones; other routes are kept. IDs without a box are ignored. Throws RangeError
194
+ * for a size that is not finite and positive. Returns the same layout when nothing changes.
195
+ */
196
+ export declare function applyGraphSizes(layout: GraphLayout, edges: readonly GraphEdge[], sizes: ReadonlyMap<string, GraphNodeSize>, direction?: GraphLayoutDirection): GraphLayout;
@@ -0,0 +1,51 @@
1
+ import type { GraphEdge, IdentifiedNode } from './graph.js';
2
+ export interface TopologicalOrderResult {
3
+ /** Nodes in dependency order (input order breaks ties). Nodes on or behind a cycle are omitted. */
4
+ order: string[];
5
+ /** True when every node was ordered. */
6
+ acyclic: boolean;
7
+ /** Nodes that could not be ordered because they lie on a cycle or depend on one, in input order. */
8
+ blocked: string[];
9
+ }
10
+ /** Kahn's algorithm. A self-loop is a cycle. Never throws for cycles; unknown edge endpoints throw an Error. */
11
+ export declare function topologicalOrder(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[]): TopologicalOrderResult;
12
+ /**
13
+ * Strongly connected components that contain a cycle: every component with more than one node, plus
14
+ * each node with a self-loop. Members follow input order and components are ordered by their first member.
15
+ */
16
+ export declare function findGraphCycles(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[]): string[][];
17
+ export interface ShortestGraphPathOptions {
18
+ /** Default true follows edge direction only; false lets edges be walked in both directions. */
19
+ directed?: boolean;
20
+ /** Edge cost; must be finite and nonnegative. Without it every edge costs 1 (breadth-first search). */
21
+ weight?: (edge: GraphEdge) => number;
22
+ }
23
+ export interface GraphPathResult {
24
+ /** Node IDs from the start to the end, inclusive. */
25
+ nodeIds: string[];
26
+ /** IDs of the traversed edges, one fewer than nodeIds. */
27
+ edgeIds: string[];
28
+ /** Total cost: the edge count, or the sum of weights. */
29
+ distance: number;
30
+ }
31
+ /** Cheapest path between two nodes, or null when the target is unreachable. Ties favour earlier edges in input order. */
32
+ export declare function shortestGraphPath(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[], fromId: string, toId: string, options?: ShortestGraphPathOptions): GraphPathResult | null;
33
+ export interface GraphSearchOptions {
34
+ /** Fields compared against the text query. Default both. */
35
+ fields?: readonly ('id' | 'label')[];
36
+ }
37
+ export interface GraphFilterOptions extends GraphSearchOptions {
38
+ /** Also keep nodes within this many hops (either direction) of a match. Default 0. */
39
+ neighborhood?: number;
40
+ }
41
+ export type GraphNodeMatch<N> = string | ((node: N) => boolean);
42
+ /** Case-insensitive substring search over node id and label. An empty query matches every node. Returns a new array in input order. */
43
+ export declare function searchGraphNodes<N extends IdentifiedNode>(nodes: readonly N[], query: string, options?: GraphSearchOptions): N[];
44
+ /**
45
+ * Keep the nodes selected by a predicate or text query, optionally widened to an N-hop neighbourhood,
46
+ * together with the edges whose endpoints both survive. Inputs are not mutated.
47
+ */
48
+ export declare function filterGraph<N extends IdentifiedNode, E extends GraphEdge>(nodes: readonly N[], edges: readonly E[], match: GraphNodeMatch<N>, options?: GraphFilterOptions): {
49
+ nodes: N[];
50
+ edges: E[];
51
+ };