@eightkk/vue-weave 0.0.0-stage → 1.0.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 (81) hide show
  1. package/CHANGELOG.md +517 -0
  2. package/CONTRIBUTING.md +123 -0
  3. package/LICENSE +21 -0
  4. package/README.ja.md +275 -0
  5. package/README.md +272 -2
  6. package/THIRD_PARTY_NOTICES.md +25 -0
  7. package/dist/core-BH5rTsKp.js +13606 -0
  8. package/dist/core.js +1 -0
  9. package/dist/index.js +8022 -0
  10. package/dist/style.css +2 -0
  11. package/dist/types/components/GanttChart.vue.d.ts +339 -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 +75 -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/snapshot.d.ts +388 -0
  64. package/dist/types/core/statusDate.d.ts +36 -0
  65. package/dist/types/core/timeRangeTargets.d.ts +67 -0
  66. package/dist/types/core/timeline.d.ts +194 -0
  67. package/dist/types/core/timelineView.d.ts +101 -0
  68. package/dist/types/core/types.d.ts +783 -0
  69. package/dist/types/core/viewBindings.d.ts +112 -0
  70. package/dist/types/core/windowedData.d.ts +255 -0
  71. package/dist/types/core/workCalendar.d.ts +41 -0
  72. package/dist/types/core/workingTimeScale.d.ts +33 -0
  73. package/dist/types/index.d.ts +52 -0
  74. package/docs/api.md +1989 -0
  75. package/docs/architecture.md +112 -0
  76. package/docs/code-of-conduct.md +24 -0
  77. package/docs/integration.md +931 -0
  78. package/docs/scheduling.md +586 -0
  79. package/docs/security.md +26 -0
  80. package/docs/third-party-licenses.md +33 -0
  81. package/package.json +79 -4
@@ -0,0 +1,93 @@
1
+ import { type GraphEdge, type GraphLayout, type GraphLayoutOptions, type GraphNodeSize, type GraphPoint, type IdentifiedNode } from './graph.js';
2
+ /**
3
+ * A position a node already has: the top-left corner of its box, optionally with the box size and rank. A `GraphBox`
4
+ * from an earlier layout fits.
5
+ */
6
+ export type GraphKnownPosition = GraphPoint & Partial<GraphNodeSize> & {
7
+ rank?: number;
8
+ };
9
+ /** Options of `layoutGraphIncrementally`. */
10
+ /**
11
+ * Options of `layoutGraphIncrementally`: the shared layout options, where `direction` is the direction in which
12
+ * successors are placed after their predecessors, `nodeWidth` and `nodeHeight` size a node without a size of its own
13
+ * (from its position or `sizes`), `columnGap` and `rowGap` are the free space kept between boxes along and across the
14
+ * flow, and `padding` is added to the right and bottom of the layout size (and is where a graph without positions starts).
15
+ */
16
+ export interface GraphIncrementalLayoutOptions extends GraphLayoutOptions {
17
+ /** Node sizes by ID. A size in a node's position wins over this one. */
18
+ sizes?: ReadonlyMap<string, GraphNodeSize>;
19
+ /** Pinned nodes. Each must be a node with a position; it never moves, whatever the other options say. */
20
+ fixedIds?: Iterable<string>;
21
+ /**
22
+ * Relaxed mode: how far, in chart units, a positioned node that is not fixed may be pushed across the flow to free the
23
+ * place a new node wants next to its neighbours. Default 0: no positioned node moves.
24
+ */
25
+ maxDisplacement?: number;
26
+ /**
27
+ * Default false: new boxes stay at nonnegative coordinates, as the NetworkGraph `positions` prop requires, so a new
28
+ * node whose flow side would leave that area (a predecessor of a node at the left edge in LR) is placed beside its
29
+ * neighbour in the same rank instead and listed in `fallbackIds`. True lets new boxes take negative coordinates.
30
+ */
31
+ allowNegative?: boolean;
32
+ /**
33
+ * An earlier layout of the same graph. Edges whose two end boxes are unchanged in the result keep its path, label
34
+ * anchor and route metadata; the other edges get the curve drawn for a moved node.
35
+ */
36
+ previousLayout?: Pick<GraphLayout, 'boxes' | 'paths' | 'edgeLabels'> & Partial<Pick<GraphLayout, 'routes'>>;
37
+ }
38
+ /** The result of `layoutGraphIncrementally`: a complete layout, plus what happened to which node. */
39
+ export interface GraphIncrementalLayout extends GraphLayout {
40
+ /** New nodes (without a position), in the order they were placed. */
41
+ placedIds: string[];
42
+ /** Positioned nodes that the relaxed mode pushed aside, in input order. Empty unless `maxDisplacement` is positive. */
43
+ movedIds: string[];
44
+ /** New nodes placed beside their neighbour, across the flow, because their flow side would leave the nonnegative area. */
45
+ fallbackIds: string[];
46
+ }
47
+ /**
48
+ * Places the nodes of a graph that have no position yet next to the ones that do, without moving those. Every node in
49
+ * `positions` keeps its box exactly (unless the relaxed mode `maxDisplacement` pushes it, and fixed nodes never move);
50
+ * each new node goes on the flow side of its placed neighbours (after its predecessors, or before its successors when
51
+ * no predecessor is placed) in the first free place across the flow, nearest to the middle of those neighbours, below
52
+ * before above, keeping `columnGap` along and `rowGap` across the flow from every box. New nodes are placed in
53
+ * breadth-first order from the placed ones, so a chain of new nodes follows its dependency order and several new nodes
54
+ * of one neighbour stack around it. Components without any positioned node are laid out together with
55
+ * layoutLayeredGraph and placed after all other boxes across the flow (below them for LR and RL, to their right for TB
56
+ * and BT; at the padding when nothing has a position). Positions of IDs that are not nodes are ignored. Deterministic
57
+ * for the same input; self-loops and cycles are allowed. Overlap tests use a bucket grid, so the cost grows with the
58
+ * number of nodes and edges, not with their square.
59
+ *
60
+ * Edges get the curve drawn for a moved node between their boxes, or keep their path from `previousLayout` while both
61
+ * end boxes are unchanged. Throws Error for invalid graphs (as indexGraph), a fixed ID that is not a node or has no
62
+ * position, and RangeError for an unknown direction, a non-finite position, a size that is not finite and positive, and
63
+ * gaps, padding or `maxDisplacement` that are not finite and nonnegative. The inputs are not modified.
64
+ */
65
+ export declare function layoutGraphIncrementally(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[], positions: ReadonlyMap<string, GraphKnownPosition>, options?: GraphIncrementalLayoutOptions): GraphIncrementalLayout;
66
+ /** Options of `graphLayoutChangeMetrics`. */
67
+ export interface GraphLayoutChangeOptions {
68
+ /** Edges to test against unrelated boxes, with their paths from `after.paths`. Without them nothing is tested. */
69
+ edges?: readonly GraphEdge[];
70
+ }
71
+ /** What `graphLayoutChangeMetrics` measured. A diagnostic of one layout change, not a benchmark. */
72
+ export interface GraphLayoutChangeMetrics {
73
+ /** Nodes with a position before and a box after. */
74
+ compared: number;
75
+ /** Largest distance a compared node moved (between top-left corners). */
76
+ maxDisplacement: number;
77
+ /** Sum of the distances the compared nodes moved. */
78
+ totalDisplacement: number;
79
+ /** Compared nodes that moved, in the order of `before`. */
80
+ movedIds: string[];
81
+ /** Pairs of boxes of `after` whose interiors overlap. */
82
+ overlaps: number;
83
+ /** Pairs of an edge and a box other than its end boxes where the edge's path passes through the box's interior. */
84
+ edgeBoxIntersections: number;
85
+ }
86
+ /**
87
+ * Measures a layout change for tests and evaluation: how far the nodes that had a position moved, how many box pairs
88
+ * of the new layout overlap, and how many edge paths pass through boxes they do not connect (curves are sampled, so
89
+ * that count is approximate for curves). Boxes go into a bucket grid, so the cost grows with the number of boxes and
90
+ * path segments. It is a diagnostic of one change, not a quality score or benchmark. IDs of `before` without a box
91
+ * after are ignored, and edges without a path or end box are skipped. Throws RangeError for non-finite coordinates.
92
+ */
93
+ export declare function graphLayoutChangeMetrics(before: ReadonlyMap<string, GraphPoint>, after: Pick<GraphLayout, 'boxes'> & Partial<Pick<GraphLayout, 'paths'>>, options?: GraphLayoutChangeOptions): GraphLayoutChangeMetrics;
@@ -0,0 +1,15 @@
1
+ import type { GraphPoint } from './graph.js';
2
+ import type { GraphRect } from './graphView.js';
3
+ /**
4
+ * Whether a point lies inside a polygon given by its vertices in order; the polygon is closed implicitly. Uses the
5
+ * even-odd rule, so the overlapping loops of a self-intersecting lasso alternate between inside and outside. A point on
6
+ * an edge or vertex counts as inside. A polygon with fewer than three vertices contains nothing. Throws RangeError for a
7
+ * non-finite coordinate.
8
+ */
9
+ export declare function graphPointInPolygon(point: GraphPoint, polygon: readonly GraphPoint[]): boolean;
10
+ /**
11
+ * The IDs of the boxes whose centre lies inside a polygon (see graphPointInPolygon), in the iteration order of `boxes`.
12
+ * Use it with the `boxes` of a GraphLayout for a free-form (lasso) selection. A polygon with fewer than three vertices
13
+ * selects nothing. Throws RangeError for a non-finite polygon coordinate or box geometry.
14
+ */
15
+ export declare function graphNodesInPolygon(boxes: ReadonlyMap<string, GraphRect>, polygon: readonly GraphPoint[]): string[];
@@ -0,0 +1,218 @@
1
+ import { type GraphBox, type GraphEdge, type GraphLayout, type GraphLayoutDirection, type GraphLayoutRoute, type GraphNodeSize, type GraphPoint, type IdentifiedNode } from './graph.js';
2
+ import { type GraphCollapseResult, type GraphShownEdge, type GraphShownNode } from './graphCollapse.js';
3
+ import type { GraphLabels, NetworkGroup, NetworkNode } from './types.js';
4
+ /**
5
+ * Which of the two layouts NetworkGraph asks for a request is: 'shown' lays out the nodes and edges it draws (with
6
+ * collapsed groups, their proxies and re-attached edges); 'expanded' lays out the full input and is used only to place
7
+ * the proxies of collapsed groups, so only its boxes matter.
8
+ */
9
+ export type GraphLayoutScope = 'expanded' | 'shown';
10
+ /** The input of `buildGraphLayoutRequests`: everything that can change a layout. */
11
+ export interface GraphLayoutRequestInput<N extends NetworkNode = NetworkNode, E extends GraphEdge = GraphEdge, G extends NetworkGroup = NetworkGroup> {
12
+ nodes: readonly N[];
13
+ edges: readonly E[];
14
+ groups?: readonly G[];
15
+ /** Collapsed group IDs, as passed to NetworkGraph `collapsedGroupIds`. IDs of groups that do not exist are ignored. */
16
+ collapsedGroupIds?: Iterable<string>;
17
+ /** Layout direction. Default 'LR'. */
18
+ direction?: GraphLayoutDirection;
19
+ /**
20
+ * Saved or fixed node positions to pass to the layout engine. Give them only when the engine honours them: they are
21
+ * part of the input key, so every change asks for a new layout. NetworkGraph applies its `positions` prop after
22
+ * layout either way.
23
+ */
24
+ positions?: ReadonlyMap<string, GraphPoint>;
25
+ /** Node sizes to pass to the layout engine. Like `positions`, give them only when the engine uses them. */
26
+ sizes?: ReadonlyMap<string, GraphNodeSize>;
27
+ /**
28
+ * Incremental layout: nodes the engine must keep where `positions` puts them (pinned). Optional; like `positions`,
29
+ * part of the input key, so give them only when the engine honours them. IDs that are not nodes of a request (such as
30
+ * members of a collapsed group in the 'shown' request) are passed as they are; engines ignore them.
31
+ */
32
+ fixedIds?: ReadonlySet<string>;
33
+ /**
34
+ * Incremental layout: nodes that are new since the previous layout (for example the page of a graph expansion), which
35
+ * the engine places around the others. Optional and part of the input key, like `fixedIds`.
36
+ */
37
+ addedIds?: ReadonlySet<string>;
38
+ /**
39
+ * Engine settings. Must be JSON-serializable; its JSON text is part of the input key, so build it with a stable key
40
+ * order.
41
+ */
42
+ settings?: unknown;
43
+ /**
44
+ * Caller-managed version of anything else that changes the layout, such as node `data` a custom engine reads or the
45
+ * engine's own version. Default ''.
46
+ */
47
+ revision?: string;
48
+ /**
49
+ * The NetworkGraph `labels` the proxy detail text is built from (`collapsedNode` and `collapsedNodes`). Defaults "node"
50
+ * and "nodes", as in NetworkGraph.
51
+ */
52
+ labels?: Partial<Pick<GraphLabels, 'collapsedNode' | 'collapsedNodes'>>;
53
+ }
54
+ /** One layout to compute, as a layout engine or Worker receives it. */
55
+ export interface GraphLayoutRequest<N extends NetworkNode = NetworkNode, E extends GraphEdge = GraphEdge, G extends NetworkGroup = NetworkGroup> {
56
+ /** ID of this request. Responses echo it; a response to an older request is not used. */
57
+ requestId: string;
58
+ /** Identifies the layout input (see `graphLayoutInputKey`); responses echo it. */
59
+ inputKey: string;
60
+ scope: GraphLayoutScope;
61
+ revision: string;
62
+ nodes: readonly N[];
63
+ edges: readonly E[];
64
+ /** The groups drawn with these nodes: the input groups for 'expanded', the groups that stay drawn for 'shown'. */
65
+ groups: readonly G[];
66
+ direction: GraphLayoutDirection;
67
+ positions?: ReadonlyMap<string, GraphPoint>;
68
+ sizes?: ReadonlyMap<string, GraphNodeSize>;
69
+ /** Pinned nodes, as given in the input; present only when the input has some. */
70
+ fixedIds?: ReadonlySet<string>;
71
+ /** New nodes, as given in the input; present only when the input has some. */
72
+ addedIds?: ReadonlySet<string>;
73
+ settings?: unknown;
74
+ }
75
+ /** A computed layout for one request. */
76
+ export interface GraphLayoutResponse {
77
+ requestId: string;
78
+ inputKey: string;
79
+ scope: GraphLayoutScope;
80
+ layout: GraphLayout;
81
+ }
82
+ /** The requests `buildGraphLayoutRequests` makes for one input. */
83
+ export interface GraphLayoutRequests<N extends NetworkNode = NetworkNode, E extends GraphEdge = GraphEdge, G extends NetworkGroup = NetworkGroup> {
84
+ /** The layout NetworkGraph draws. */
85
+ shown: GraphLayoutRequest<GraphShownNode<N, G>, GraphShownEdge<E, G>, NetworkGroup>;
86
+ /** Present only while a group is collapsed: the full input, to place the proxies. */
87
+ expanded?: GraphLayoutRequest<N, E, G>;
88
+ /** The collapsed view, as NetworkGraph builds it, while a group is collapsed. */
89
+ collapse?: GraphCollapseResult<N, E>;
90
+ }
91
+ /** The parts of a request, other than its nodes and edges, that `graphLayoutInputKey` reads. */
92
+ export interface GraphLayoutKeyInput {
93
+ scope: GraphLayoutScope;
94
+ nodes: readonly IdentifiedNode[];
95
+ edges: readonly GraphEdge[];
96
+ groups?: readonly NetworkGroup[];
97
+ /** The active collapsed group IDs; their order does not matter. */
98
+ collapsedGroupIds?: Iterable<string>;
99
+ direction?: GraphLayoutDirection;
100
+ positions?: ReadonlyMap<string, GraphPoint>;
101
+ sizes?: ReadonlyMap<string, GraphNodeSize>;
102
+ fixedIds?: ReadonlySet<string>;
103
+ addedIds?: ReadonlySet<string>;
104
+ settings?: unknown;
105
+ revision?: string;
106
+ }
107
+ /**
108
+ * A string that identifies a layout input: the scope, direction, settings and revision, and, in order, the nodes (ID,
109
+ * label, detail, shape and ports), the edges (ID, ends, ports, label and waypoints), the groups, the collapsed group IDs
110
+ * and any positions and sizes given to the engine. A change to any of them gives a different key, even when the node IDs
111
+ * stay the same. Node and edge `data` is not read; change `revision` when it affects the layout. Throws RangeError for an
112
+ * unknown direction or scope, and for settings that cannot be serialized to JSON.
113
+ */
114
+ export declare function graphLayoutInputKey(input: GraphLayoutKeyInput): string;
115
+ /**
116
+ * The layout requests for one input, made the way NetworkGraph calls its `layout` function. Without collapsed groups
117
+ * there is one 'shown' request for the input itself. With collapsed groups (IDs of groups that do not exist are dropped,
118
+ * as NetworkGraph does) the 'shown' request holds the collapsed view from `collapseGraphGroups`, with the proxy detail
119
+ * text built from `labels` like NetworkGraph builds it, and an 'expanded' request holds the full input. The requests
120
+ * get the IDs `requestId + ':shown'` and `requestId + ':expanded'`. Throws like `collapseGraphGroups` and
121
+ * `graphLayoutInputKey`. The inputs are not modified.
122
+ */
123
+ export declare function buildGraphLayoutRequests<N extends NetworkNode, E extends GraphEdge, G extends NetworkGroup = NetworkGroup>(input: GraphLayoutRequestInput<N, E, G>, requestId: string): GraphLayoutRequests<N, E, G>;
124
+ /**
125
+ * Checks a layout computed for a request and returns it. The response must echo the request's `requestId`, `inputKey`
126
+ * and `scope` (Error otherwise, for a stale or foreign response). Every request node needs a finite box with a positive
127
+ * size. For a 'shown' request, as NetworkGraph checks its layout, the width and height must also be finite and
128
+ * positive, every edge needs a path, and route metadata, when present, must have finite points and the edge's ports.
129
+ * Throws Error for a missing box, path or map, or a mismatched route, and RangeError for invalid numbers.
130
+ */
131
+ export declare function validateGraphLayoutResponse(request: GraphLayoutRequest, response: GraphLayoutResponse): GraphLayout;
132
+ /** Options of `completeGraphLayout`. */
133
+ export interface GraphLayoutCompletionOptions {
134
+ /** Layout direction, which picks the sides of the temporary curves. Default 'LR'. */
135
+ direction?: GraphLayoutDirection;
136
+ }
137
+ /** The result of `completeGraphLayout`. */
138
+ export interface GraphLayoutCompletion {
139
+ /** The layout with temporary routes added, or the input layout when nothing was missing. */
140
+ layout: GraphLayout;
141
+ /** Edges that received a temporary built-in route, in input order. */
142
+ temporaryEdgeIds: string[];
143
+ /** Edges without a path that could not be routed because a box of an end is missing, in input order. */
144
+ unresolvedEdgeIds: string[];
145
+ }
146
+ /**
147
+ * Fills in temporary routes for the edges a cached layout has no path for, such as an edge connected while a new layout
148
+ * is computed. An edge whose end boxes both exist gets the curve the core draws for a moved node, or between its ports
149
+ * when it has named ports, and a label anchor; it is listed in `temporaryEdgeIds`, and the routing policy 'preserve'
150
+ * treats it as a built-in route, so it is redrawn when routed. Other paths, boxes and route metadata are kept. Throws
151
+ * RangeError for an unknown direction. The inputs are not modified.
152
+ */
153
+ export declare function completeGraphLayout(layout: GraphLayout, nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[], options?: GraphLayoutCompletionOptions): GraphLayoutCompletion;
154
+ /** A request to compute a layout, sent to a Worker or another layout process. */
155
+ export interface GraphLayoutRequestMessage {
156
+ type: 'request';
157
+ request: GraphLayoutRequest;
158
+ }
159
+ /** Asks the engine to stop computing a request. Its result, if one still arrives, is discarded either way. */
160
+ export interface GraphLayoutCancelMessage {
161
+ type: 'cancel';
162
+ requestId: string;
163
+ inputKey: string;
164
+ }
165
+ /** A computed layout. */
166
+ export interface GraphLayoutSuccessMessage extends GraphLayoutResponse {
167
+ type: 'success';
168
+ }
169
+ /** A failed request, with a description of the error. */
170
+ export interface GraphLayoutFailureMessage {
171
+ type: 'failure';
172
+ requestId: string;
173
+ inputKey: string;
174
+ scope: GraphLayoutScope;
175
+ message: string;
176
+ }
177
+ /** A layout Worker message as sent by structured clone, with Maps. */
178
+ export type GraphLayoutWorkerMessage = GraphLayoutRequestMessage | GraphLayoutCancelMessage | GraphLayoutSuccessMessage | GraphLayoutFailureMessage;
179
+ /** A `GraphLayout` with its Maps as entry arrays, for JSON. */
180
+ export interface GraphLayoutJson {
181
+ boxes: [string, GraphBox][];
182
+ paths: [string, string][];
183
+ edgeLabels: [string, GraphPoint][];
184
+ width: number;
185
+ height: number;
186
+ routes?: [string, GraphLayoutRoute][];
187
+ }
188
+ /** A `GraphLayoutRequest` with its Maps as entry arrays and its Sets as ID arrays, for JSON. */
189
+ export type GraphLayoutRequestJson = Omit<GraphLayoutRequest, 'positions' | 'sizes' | 'fixedIds' | 'addedIds'> & {
190
+ positions?: [string, GraphPoint][];
191
+ sizes?: [string, GraphNodeSize][];
192
+ fixedIds?: string[];
193
+ addedIds?: string[];
194
+ };
195
+ /** A layout Worker message in JSON form: every Map is an array of entries. */
196
+ export type GraphLayoutWorkerJsonMessage = {
197
+ type: 'request';
198
+ request: GraphLayoutRequestJson;
199
+ } | GraphLayoutCancelMessage | (Omit<GraphLayoutSuccessMessage, 'layout'> & {
200
+ layout: GraphLayoutJson;
201
+ }) | GraphLayoutFailureMessage;
202
+ /** Converts a layout's Maps to entry arrays, for JSON. */
203
+ export declare function graphLayoutToJson(layout: GraphLayout): GraphLayoutJson;
204
+ /** Rebuilds a layout from `graphLayoutToJson` output, checking its shape. Throws Error for malformed data. */
205
+ export declare function graphLayoutFromJson(value: unknown): GraphLayout;
206
+ /** Converts a layout Worker message to its JSON form, with every Map as an array of entries. */
207
+ export declare function graphLayoutMessageToJson(message: GraphLayoutWorkerMessage): GraphLayoutWorkerJsonMessage;
208
+ /**
209
+ * Reads a layout Worker message in JSON form (for example after `JSON.parse`), checks its shape and rebuilds its Maps.
210
+ * Throws Error for an unknown type, a missing `requestId` or `inputKey`, or malformed layout data.
211
+ */
212
+ export declare function graphLayoutMessageFromJson(value: unknown): GraphLayoutWorkerMessage;
213
+ /**
214
+ * Checks a layout Worker message received by structured clone (as `postMessage` delivers it, with Maps) and returns it.
215
+ * Throws Error for an unknown type, a missing `requestId` or `inputKey`, entry arrays where Maps are expected, or
216
+ * malformed layout data.
217
+ */
218
+ export declare function parseGraphLayoutMessage(value: unknown): GraphLayoutWorkerMessage;
@@ -0,0 +1,81 @@
1
+ import type { GraphEdge, GraphLayout, GraphLayoutOptions, IdentifiedNode } from './graph.js';
2
+ /** Options of `layoutTreeGraph`: the shared layout options (`columnGap` between depth levels, `rowGap` between adjacent leaves) plus roots. */
3
+ export interface GraphTreeLayoutOptions extends GraphLayoutOptions {
4
+ /** Node IDs placed first as tree roots. Remaining roots are nodes without incoming edges, then any node left over in a cycle. */
5
+ roots?: readonly string[];
6
+ }
7
+ export interface GraphRadialLayoutOptions {
8
+ nodeWidth?: number;
9
+ nodeHeight?: number;
10
+ /** Free space between neighbouring rings and between neighbouring nodes on one ring. */
11
+ ringGap?: number;
12
+ padding?: number;
13
+ /** Node IDs placed first as tree roots. See GraphTreeLayoutOptions.roots. */
14
+ roots?: readonly string[];
15
+ }
16
+ /**
17
+ * Tidy tree layout for forests. Depth maps to columns (LR) and leaves are spaced evenly with each parent
18
+ * centred over its children. Edges that are not tree edges are drawn as extra curves.
19
+ */
20
+ export declare function layoutTreeGraph(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[], options?: GraphTreeLayoutOptions): GraphLayout;
21
+ /**
22
+ * Radial layout: nodes sit on concentric rings by breadth-first depth from the roots. A single root is placed
23
+ * at the centre; several roots share the first ring. Each subtree receives an angular wedge proportional to its leaf count.
24
+ */
25
+ export declare function layoutRadialGraph(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[], options?: GraphRadialLayoutOptions): GraphLayout;
26
+ /** Options of `layoutCircularGraph`. `N` is the node type, so `sort` receives your own nodes. */
27
+ export interface GraphCircularLayoutOptions<N extends IdentifiedNode = IdentifiedNode> {
28
+ nodeWidth?: number;
29
+ nodeHeight?: number;
30
+ /** Free space between neighbouring boxes on the circle. */
31
+ nodeGap?: number;
32
+ padding?: number;
33
+ /** Circle radius (distance from the circle centre to the box centres). Throws a RangeError when neighbouring boxes would overlap. Default: the smallest radius that keeps `nodeGap` between neighbours. */
34
+ radius?: number;
35
+ /** Angle of the first node in radians, measured clockwise from the positive x axis in screen coordinates. Default: -Math.PI / 2 (top). */
36
+ startAngle?: number;
37
+ /** Place nodes clockwise on screen. Default true. */
38
+ clockwise?: boolean;
39
+ /** Reorders the nodes before placement (a stable sort of a copy). Default: input order. */
40
+ sort?: (a: N, b: N) => number;
41
+ }
42
+ export interface GraphGridLayoutOptions {
43
+ nodeWidth?: number;
44
+ nodeHeight?: number;
45
+ columnGap?: number;
46
+ rowGap?: number;
47
+ padding?: number;
48
+ /** Nodes per row, a positive integer. Default: Math.ceil(Math.sqrt(nodeCount)). */
49
+ columns?: number;
50
+ }
51
+ /** Options of `layoutConcentricGraph`. `N` is the node type, so `level` receives your own nodes. */
52
+ export interface GraphConcentricLayoutOptions<N extends IdentifiedNode = IdentifiedNode> {
53
+ nodeWidth?: number;
54
+ nodeHeight?: number;
55
+ /** Free space between neighbouring rings and between neighbouring nodes on one ring. */
56
+ ringGap?: number;
57
+ padding?: number;
58
+ /** Ring metric. Higher values sit closer to the centre. `degree` is the number of incident edges, self-loops excluded. Default: the degree. Must return a finite number. */
59
+ level?: (node: N, degree: number) => number;
60
+ /** Groups levels into rings: nodes share a ring when floor(level / levelWidth) is equal. Positive. Default: one ring per distinct level. */
61
+ levelWidth?: number;
62
+ /** Angle of the first node of each ring in radians. Default: -Math.PI / 2 (top). */
63
+ startAngle?: number;
64
+ }
65
+ /**
66
+ * Circular layout: all nodes sit on one circle in input order (or in `sort` order). The radius grows linearly with the
67
+ * node count so neighbouring boxes never overlap. Edges are straight lines between box borders; self-loops are small curves.
68
+ */
69
+ export declare function layoutCircularGraph<N extends IdentifiedNode>(nodes: readonly N[], edges: readonly GraphEdge[], options?: GraphCircularLayoutOptions<N>): GraphLayout;
70
+ /**
71
+ * Grid layout: nodes fill rows of `columns` in input order. `rank` is the row index. Edges are straight lines between
72
+ * box borders, so they can cross other boxes; self-loops are small curves.
73
+ */
74
+ export declare function layoutGridGraph(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[], options?: GraphGridLayoutOptions): GraphLayout;
75
+ /**
76
+ * Concentric layout: nodes sit on rings chosen by a metric (the degree by default). Higher levels are closer to the
77
+ * centre; `rank` is the ring index, 0 for the innermost. Each ring is large enough for its nodes and rings are at least
78
+ * one node diagonal plus `ringGap` apart, so boxes never overlap. Nodes keep input order within a ring. Sorting the
79
+ * distinct levels makes the work O(n + e + k log k) for k rings.
80
+ */
81
+ export declare function layoutConcentricGraph<N extends IdentifiedNode>(nodes: readonly N[], edges: readonly GraphEdge[], options?: GraphConcentricLayoutOptions<N>): GraphLayout;
@@ -0,0 +1,68 @@
1
+ import type { GraphPoint, GraphPort } from './graph.js';
2
+ import { SpatialGrid, type SpatialRect } from './graphSpatial.js';
3
+ import type { GraphRect } from './graphView.js';
4
+ type Side = GraphPort['side'];
5
+ /** One end of an orthogonal route: a point on a node border and the side of the node it leaves or enters through. */
6
+ export interface GraphRouteEnd extends GraphPoint {
7
+ side: Side;
8
+ }
9
+ /** Settings of obstacle-avoiding orthogonal routing (`findOrthogonalRoute`, `routeGraphEdges`, NetworkGraph `avoidNodes`). */
10
+ export interface GraphObstacleAvoidance {
11
+ /** Distance in chart units that routes keep from every box. Finite and nonnegative. Default 8. */
12
+ clearance?: number;
13
+ /** Extra cost of each bend, in chart units of length. Finite and nonnegative. Default 24. */
14
+ bendPenalty?: number;
15
+ }
16
+ type Rect = SpatialRect;
17
+ /**
18
+ * Internal: obstacle boxes grown by the clearance, in a uniform bucket grid (`SpatialGrid`, indexed like `inflated`)
19
+ * for segment queries. Built once per routing call in O(n) for n boxes.
20
+ */
21
+ export interface GraphObstacleIndex {
22
+ ids: readonly string[];
23
+ raw: readonly Rect[];
24
+ inflated: readonly Rect[];
25
+ clearance: number;
26
+ cell: number;
27
+ grid: SpatialGrid;
28
+ /** Sorted distinct x and y coordinates of the grown boxes' edges. */
29
+ xBorders: readonly number[];
30
+ yBorders: readonly number[];
31
+ /** Bounds of the grown boxes; undefined without boxes. */
32
+ bounds?: Rect;
33
+ /** Whether every box lies at nonnegative coordinates, so routes stay at or above 0 as the other routes do. */
34
+ nonnegative: boolean;
35
+ }
36
+ export interface ResolvedAvoidance {
37
+ clearance: number;
38
+ bendPenalty: number;
39
+ }
40
+ /** Internal: validates the `avoidNodes` option; undefined when avoidance is off. */
41
+ export declare function resolveObstacleAvoidance(value: unknown, name?: string): ResolvedAvoidance | undefined;
42
+ /** Internal: indexes boxes (in iteration order) as obstacles grown by `clearance`. */
43
+ export declare function buildGraphObstacleIndex(boxes: Iterable<readonly [string, GraphRect]>, clearance: number): GraphObstacleIndex;
44
+ /**
45
+ * Internal: whether a polyline crosses no box of the index (at box size, without clearance), except the boxes named in
46
+ * `except`.
47
+ */
48
+ export declare function graphPolylineClear(index: GraphObstacleIndex, points: readonly GraphPoint[], except: ReadonlySet<string>): boolean;
49
+ /** Internal: `findOrthogonalRoute` over a prebuilt index. The ends are assumed valid. */
50
+ export declare function routeAroundObstacles(index: GraphObstacleIndex, from: GraphRouteEnd, to: GraphRouteEnd, bendPenalty: number): GraphPoint[] | undefined;
51
+ /**
52
+ * Finds an axis-aligned route from `from` to `to` that keeps `clearance` (default 8) away from every obstacle
53
+ * rectangle, leaving `from` and entering `to` perpendicular to their sides (with a clearance of 0
54
+ * the route may run along the border of an end's own node, which only costs extra). Include the boxes of the two end nodes in
55
+ * `obstacles`: the route then never runs through them. The route minimises its length plus `bendPenalty` (default 24)
56
+ * per bend, and is deterministic for the same input. Returns the polyline from `from` to `to`, or undefined when no route
57
+ * exists or the bounded search gives up. When every input lies at nonnegative coordinates, so does the route.
58
+ *
59
+ * The search runs over a sparse grid: lines halfway between neighbouring obstacle edges (the middle of each free
60
+ * channel) and through both ends, never a pixel grid. Obstacles go into a bucket grid in O(n); the search starts in a
61
+ * region around both ends and grows it fourfold up to the whole area, each round taking O(k log k) for the k obstacles in
62
+ * the region plus A* over at most 4·lx·ly states for lx by ly lines, capped at 200,000 expanded states.
63
+ *
64
+ * Throws RangeError for a non-finite end, an unknown side, an obstacle with non-finite coordinates or a negative or
65
+ * non-finite size, and a negative or non-finite clearance or bend penalty.
66
+ */
67
+ export declare function findOrthogonalRoute(from: GraphRouteEnd, to: GraphRouteEnd, obstacles: readonly GraphRect[], options?: GraphObstacleAvoidance): GraphPoint[] | undefined;
68
+ export {};
@@ -0,0 +1,111 @@
1
+ import type { GraphConnection, GraphEdge, IdentifiedNode } from './graph.js';
2
+ /** Which way connections may use an endpoint: `in` only as a target, `out` only as a source, `both` either way. */
3
+ export type GraphPortDirection = 'in' | 'out' | 'both';
4
+ /** What one connection endpoint (a named port, or a node without ports) accepts. Every field is optional. */
5
+ export interface GraphPortRule {
6
+ /**
7
+ * The type tag of the endpoint, or a list of accepted tags. Two endpoints are compatible when either has no type or
8
+ * they share at least one tag.
9
+ */
10
+ type?: string | readonly string[];
11
+ /**
12
+ * Which way connections may use the endpoint. It applies together with `GraphPort.direction`: a port with
13
+ * `direction: 'target'` stays a target only, whatever its rule says. Default `both`.
14
+ */
15
+ direction?: GraphPortDirection;
16
+ /** The most edges that may use the endpoint, counting each edge end. A non-negative integer; omit for no limit. */
17
+ maxConnections?: number;
18
+ }
19
+ /**
20
+ * Connection rules for a graph, kept apart from the node and port data so existing data and types stay unchanged.
21
+ * A connection end on a named port uses `ports[nodeId][portId]`, a connection end without a port uses `nodes[nodeId]`,
22
+ * and either falls back to `default`. An endpoint without any rule accepts every connection.
23
+ */
24
+ export interface GraphPortRules {
25
+ /** Rules of named ports, keyed by node ID and then port ID. */
26
+ ports?: Readonly<Record<string, Readonly<Record<string, GraphPortRule>>>>;
27
+ /** Rules of the node itself, for connections without a port (the single handle of a node without ports). */
28
+ nodes?: Readonly<Record<string, GraphPortRule>>;
29
+ /** Rule of every endpoint that has no rule of its own. */
30
+ default?: GraphPortRule;
31
+ }
32
+ /** Why a connection breaks the rules. */
33
+ export type GraphConnectionRejectionCode = 'unknown-node' | 'unknown-port' | 'direction' | 'type-mismatch' | 'limit-reached';
34
+ /** A rejected connection: a machine-readable code, a readable reason, and the endpoint that broke a rule. */
35
+ export interface GraphConnectionRejection {
36
+ ok: false;
37
+ code: GraphConnectionRejectionCode;
38
+ reason: string;
39
+ /** The connection end that broke the rule. */
40
+ end: 'from' | 'to';
41
+ node: string;
42
+ port?: string;
43
+ }
44
+ /** The result of `checkGraphConnection`. */
45
+ export type GraphConnectionCheck = {
46
+ ok: true;
47
+ } | GraphConnectionRejection;
48
+ /** One rule an existing edge breaks, reported by `graphConnectionViolations`. */
49
+ export interface GraphConnectionViolation {
50
+ edgeId: string;
51
+ code: Exclude<GraphConnectionRejectionCode, 'unknown-node' | 'unknown-port'>;
52
+ reason: string;
53
+ end: 'from' | 'to';
54
+ node: string;
55
+ port?: string;
56
+ }
57
+ /** The fixed end of a connection in progress. `end` is the end the candidates would take, `to` by default. */
58
+ export interface GraphConnectionOrigin {
59
+ node: string;
60
+ port?: string;
61
+ end?: 'from' | 'to';
62
+ }
63
+ /**
64
+ * Valid targets of a connection in progress. A node without ports is a valid target when it is in `nodeIds`; a port is
65
+ * valid when `ports.get(nodeId)` has its ID. `nodeIds` also lists every node with at least one valid port.
66
+ */
67
+ export interface GraphConnectionTargets {
68
+ nodeIds: Set<string>;
69
+ ports: Map<string, Set<string>>;
70
+ }
71
+ /** Checks built once over a graph and its rules; see `createGraphConnectionChecker`. */
72
+ export interface GraphConnectionChecker {
73
+ /** Same as `checkGraphConnection` on the graph the checker was built for. */
74
+ check(connection: GraphConnection, replacingEdgeId?: string): GraphConnectionCheck;
75
+ /** Same as `graphConnectionTargets` on the graph the checker was built for. */
76
+ targets(origin: GraphConnectionOrigin, replacingEdgeId?: string): GraphConnectionTargets;
77
+ }
78
+ /**
79
+ * Builds the rule index once: validates the graph (as `indexGraph` does) and the rules, and counts the edge ends at every
80
+ * endpoint. `check` and `targets` then answer in constant time per endpoint, so a checker suits `validateConnection` and
81
+ * hints over thousands of nodes. Rules that name an unknown node or port throw an Error, an invalid `type` or
82
+ * `direction` an Error, and a negative, fractional or non-finite `maxConnections` a RangeError. Inputs are not modified.
83
+ */
84
+ export declare function createGraphConnectionChecker(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[], rules: GraphPortRules): GraphConnectionChecker;
85
+ /**
86
+ * Checks one proposed connection against the rules and the current edges. Returns `{ ok: true }`, or a rejection with
87
+ * a code (`unknown-node`, `unknown-port`, `direction`, `type-mismatch` or `limit-reached`), a readable reason and the
88
+ * endpoint that broke the rule; the checks run in that order and the first broken rule is reported. With
89
+ * `replacingEdgeId` (a reconnection), that edge is left out of the connection counts, so a port with
90
+ * `maxConnections: 1` can move its own edge. An unknown `replacingEdgeId` throws an Error; see
91
+ * `createGraphConnectionChecker` for the other errors. To check many proposals over the same data, build a checker once.
92
+ */
93
+ export declare function checkGraphConnection(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[], rules: GraphPortRules, connection: GraphConnection, replacingEdgeId?: string): GraphConnectionCheck;
94
+ /**
95
+ * The valid targets of a connection in progress from `origin`, in one pass over the nodes after indexing the edges once:
96
+ * every port, and every node without ports, that `checkGraphConnection` would accept as the other end. A node with
97
+ * ports is a target only through its ports. Self-connections are included when the rules allow them. With
98
+ * `replacingEdgeId` (a reconnection), that edge is left out of the counts. An unknown origin has no targets.
99
+ */
100
+ export declare function graphConnectionTargets(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[], rules: GraphPortRules, origin: GraphConnectionOrigin, replacingEdgeId?: string): GraphConnectionTargets;
101
+ /**
102
+ * Audits existing edges against the rules and returns every broken rule in edge order: direction and type checks per
103
+ * edge, and for a limit the edges past it, counting edge ends in input order (the first `maxConnections` ends are kept).
104
+ * An edge can appear more than once. Throws like `createGraphConnectionChecker`.
105
+ */
106
+ export declare function graphConnectionViolations(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[], rules: GraphPortRules): GraphConnectionViolation[];
107
+ /**
108
+ * A `validateConnection` function for NetworkGraph: the rules run first, and a rejection returns its reason without
109
+ * calling `validate`; otherwise `validate` (when given) decides. Build it again when the nodes, edges or rules change.
110
+ */
111
+ export declare function graphConnectionValidator(nodes: readonly IdentifiedNode[], edges: readonly GraphEdge[], rules: GraphPortRules, validate?: (connection: GraphConnection, replacingEdgeId?: string) => boolean | string | void): (connection: GraphConnection, replacingEdgeId?: string) => boolean | string | void;