@graphty/graphty-element 2.6.1 → 3.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 (163) hide show
  1. package/dist/ai.js +3 -3
  2. package/dist/catalog.js +53 -54
  3. package/dist/chunks/{AiManager-4iQpsJW1.js → AiManager-Bhh0rR_p.js} +706 -655
  4. package/dist/chunks/GraphSession-DPoTaT3b.js +21175 -0
  5. package/dist/chunks/{GraphtyLogger-B_O67a6c.js → GraphtyLogger-BtcBJQPL.js} +1 -1
  6. package/dist/chunks/{VoiceInputAdapter-Cc6mHXTI.js → VoiceInputAdapter-CdLsJ_nG.js} +1 -1
  7. package/dist/chunks/{XRPivotCameraController-BLa89LXn.js → XRPivotCameraController-CiLJ9Gz6.js} +2 -2
  8. package/dist/chunks/algorithms-qij74zEN.js +6811 -0
  9. package/dist/chunks/{capability-check-Am2zliFj.js → capability-check-BbgTejS3.js} +1 -1
  10. package/dist/chunks/definePalette-BYt2Llxs.js +1333 -0
  11. package/dist/chunks/fields-5uVC1Pll.js +4999 -0
  12. package/dist/chunks/{format-detection-BHwrAVzW.js → format-detection-FKaDMshR.js} +1 -1
  13. package/dist/chunks/{index-BkBLbvui.js → index-Cc_6D9hV.js} +6034 -7127
  14. package/dist/chunks/interpolation-Dk206AhZ.js +105 -0
  15. package/dist/chunks/paletteRegistry-De3CGdst.js +357 -0
  16. package/dist/chunks/parse-SVp77JbE.js +669 -0
  17. package/dist/chunks/{pluginRegistry-Bs8bEkz9.js → pluginRegistry-Ddfl6Mv2.js} +27 -24
  18. package/dist/chunks/{registry-BdGvyZou.js → registry-CgMqldp4.js} +1 -1
  19. package/dist/chunks/{DataSource-BL2UzPff.js → sources-BbAJCDIH.js} +279 -108
  20. package/dist/commands.d.ts +128 -19
  21. package/dist/commands.js +49 -1
  22. package/dist/custom-elements.json +1 -1
  23. package/dist/extend.d.ts +10 -2
  24. package/dist/extend.js +64 -57
  25. package/dist/graphty-catalog.json +6 -3
  26. package/dist/graphty.bundle.js +267177 -240648
  27. package/dist/graphty.js +84 -78
  28. package/dist/index.d.ts +4 -0
  29. package/dist/logging.js +2 -2
  30. package/dist/schema.js +70 -71
  31. package/dist/session.d.ts +5 -6
  32. package/dist/session.js +40 -86
  33. package/dist/src/Edge.d.ts +31 -67
  34. package/dist/src/Graph.d.ts +335 -77
  35. package/dist/src/Node.d.ts +36 -3
  36. package/dist/src/NodeBehavior.d.ts +28 -0
  37. package/dist/src/Styles.d.ts +15 -4
  38. package/dist/src/acceleration/AccelerationController.d.ts +8 -0
  39. package/dist/src/acceleration/narrow.d.ts +9 -1
  40. package/dist/src/acceleration/types.d.ts +10 -0
  41. package/dist/src/ai/AiController.d.ts +12 -0
  42. package/dist/src/ai/AiManager.d.ts +7 -0
  43. package/dist/src/ai/commands/AlgorithmCommands.d.ts +1 -1
  44. package/dist/src/ai/commands/LayoutCommands.d.ts +1 -1
  45. package/dist/src/ai/commands/StyleCommands.d.ts +1 -1
  46. package/dist/src/ai/commands/types.d.ts +20 -1
  47. package/dist/src/algorithms/Algorithm.d.ts +21 -4
  48. package/dist/src/algorithms/BFSAlgorithm.d.ts +0 -9
  49. package/dist/src/algorithms/BellmanFordAlgorithm.d.ts +0 -14
  50. package/dist/src/algorithms/DFSAlgorithm.d.ts +1 -1
  51. package/dist/src/algorithms/FloydWarshallAlgorithm.d.ts +5 -0
  52. package/dist/src/algorithms/GirvanNewmanAlgorithm.d.ts +5 -0
  53. package/dist/src/algorithms/LeidenAlgorithm.d.ts +5 -0
  54. package/dist/src/algorithms/PageRankAlgorithm.d.ts +1 -1
  55. package/dist/src/algorithms/StronglyConnectedComponentsAlgorithm.d.ts +1 -1
  56. package/dist/src/algorithms/metrics/fields.d.ts +23 -1
  57. package/dist/src/algorithms/utils/graphUtils.d.ts +13 -1
  58. package/dist/src/catalog/paletteRegistry.d.ts +4 -4
  59. package/dist/src/catalog/registry.d.ts +3 -2
  60. package/dist/src/catalog/types.d.ts +18 -1
  61. package/dist/src/config/GraphStyle.d.ts +1 -1
  62. package/dist/src/config/StyleTemplate.d.ts +2 -2
  63. package/dist/src/config/xr-config-schema.d.ts +4 -4
  64. package/dist/src/data/CSVDataSource.d.ts +77 -22
  65. package/dist/src/data/ErrorAggregator.d.ts +5 -0
  66. package/dist/src/data/GEXFDataSource.d.ts +12 -61
  67. package/dist/src/data/GraphMLDataSource.d.ts +3 -44
  68. package/dist/src/data/GraphStore.d.ts +322 -15
  69. package/dist/src/data/JsonDataSource.d.ts +43 -1
  70. package/dist/src/data/graph-io-import.d.ts +89 -0
  71. package/dist/src/data/graph-io-records.d.ts +64 -0
  72. package/dist/src/data/lane.d.ts +23 -0
  73. package/dist/src/data/positions.d.ts +13 -0
  74. package/dist/src/data/seedPosition.d.ts +16 -0
  75. package/dist/src/errors/GraphtyError.d.ts +3 -1
  76. package/dist/src/errors/codes.d.ts +23 -0
  77. package/dist/src/events.d.ts +12 -0
  78. package/dist/src/graphty-element.d.ts +149 -54
  79. package/dist/src/input/types.d.ts +2 -0
  80. package/dist/src/layout/D3GraphLayoutEngine.d.ts +17 -3
  81. package/dist/src/layout/FixedLayoutEngine.d.ts +20 -4
  82. package/dist/src/layout/KamadaKawaiLayoutEngine.d.ts +6 -0
  83. package/dist/src/layout/LayoutEngine.d.ts +214 -116
  84. package/dist/src/layout/NGraphLayoutEngine.d.ts +10 -3
  85. package/dist/src/layout/SimulationLayoutEngine.d.ts +8 -3
  86. package/dist/src/managers/AlgorithmManager.d.ts +24 -5
  87. package/dist/src/managers/DataManager.d.ts +258 -181
  88. package/dist/src/managers/EventManager.d.ts +5 -2
  89. package/dist/src/managers/GraphContext.d.ts +7 -0
  90. package/dist/src/managers/InputManager.d.ts +11 -0
  91. package/dist/src/managers/LayoutManager.d.ts +129 -50
  92. package/dist/src/managers/RenderManager.d.ts +14 -1
  93. package/dist/src/managers/UpdateManager.d.ts +20 -0
  94. package/dist/src/screenshot/ScreenshotCapture.d.ts +1 -1
  95. package/dist/src/session/GraphSession.d.ts +83 -6
  96. package/dist/src/session/commands/algo.d.ts +169 -0
  97. package/dist/src/session/commands/config.d.ts +45 -0
  98. package/dist/src/session/commands/data.d.ts +178 -0
  99. package/dist/src/session/commands/doors.d.ts +93 -0
  100. package/dist/src/session/commands/index.d.ts +20 -0
  101. package/dist/src/session/commands/layout.d.ts +104 -0
  102. package/dist/src/session/commands/positions.d.ts +30 -0
  103. package/dist/src/session/commands/sets.d.ts +113 -0
  104. package/dist/src/session/commands/style.d.ts +92 -0
  105. package/dist/src/session/commands/view.d.ts +57 -0
  106. package/dist/src/session/commands/visibility.d.ts +41 -0
  107. package/dist/src/session/data.d.ts +131 -4
  108. package/dist/src/session/index.d.ts +1 -1
  109. package/dist/src/session/planning.d.ts +25 -8
  110. package/dist/src/session/project/Dispatcher.d.ts +905 -0
  111. package/dist/src/session/project/History.d.ts +382 -0
  112. package/dist/src/session/project/arrangement.d.ts +247 -0
  113. package/dist/src/session/project/derive.d.ts +132 -0
  114. package/dist/src/session/project/digest.d.ts +33 -0
  115. package/dist/src/session/project/draft.d.ts +194 -0
  116. package/dist/src/session/project/graphOps.d.ts +304 -0
  117. package/dist/src/session/project/ingest.d.ts +364 -0
  118. package/dist/src/session/project/state.d.ts +145 -0
  119. package/dist/src/session/project/strict.d.ts +68 -0
  120. package/dist/src/session/results/RunResult.d.ts +48 -0
  121. package/dist/src/session/results/statistics.d.ts +20 -0
  122. package/dist/src/session/runs/Run.d.ts +80 -4
  123. package/dist/src/session/runs/RunsApi.d.ts +23 -6
  124. package/dist/src/session/runs/types.d.ts +25 -6
  125. package/dist/src/session/scope/ElementMask.d.ts +14 -0
  126. package/dist/src/session/scope/ScopeApi.d.ts +3 -22
  127. package/dist/src/session/scope/spaces.d.ts +29 -0
  128. package/dist/src/session/sealed.d.ts +22 -0
  129. package/dist/src/session/selection/SelectionApi.d.ts +14 -4
  130. package/dist/src/session/sets/SetsApi.d.ts +13 -5
  131. package/dist/src/session/sets/store.d.ts +54 -53
  132. package/dist/src/session/sets/types.d.ts +5 -2
  133. package/dist/src/session/styles/Layer.d.ts +5 -0
  134. package/dist/src/session/styles/StylesApi.d.ts +68 -17
  135. package/dist/src/session/styles/autoApply.d.ts +64 -53
  136. package/dist/src/session/styles/index.d.ts +3 -3
  137. package/dist/src/session/styles/predicate.d.ts +7 -0
  138. package/dist/src/session/styles/repaint.d.ts +16 -1
  139. package/dist/src/session/styles/sources.d.ts +1 -1
  140. package/dist/src/session/types.d.ts +625 -54
  141. package/dist/src/session/visibility/VisibilityApi.d.ts +38 -18
  142. package/dist/src/session/visibility/filter.d.ts +10 -0
  143. package/dist/src/simple/defineAlgorithm.d.ts +28 -0
  144. package/dist/src/simple/defineLayout.d.ts +35 -0
  145. package/dist/src/simple/defineLogDestination.d.ts +31 -0
  146. package/dist/src/simple/definePalette.d.ts +26 -0
  147. package/dist/src/simple/definition.d.ts +106 -0
  148. package/dist/src/simple/options.d.ts +33 -0
  149. package/dist/src/simple/source.d.ts +49 -0
  150. package/dist/src/simple/types.d.ts +366 -0
  151. package/dist/src/simple/view.d.ts +107 -0
  152. package/dist/webgpu.js +2 -2
  153. package/package.json +10 -12
  154. package/dist/chunks/GraphSession-BhuHSXIo.js +0 -12819
  155. package/dist/chunks/GraphStyle-Cwr55SAE.js +0 -65
  156. package/dist/chunks/algorithms-BJ6DQMOe.js +0 -3777
  157. package/dist/chunks/detect-fyuVnlCT.js +0 -88
  158. package/dist/chunks/interpolation-DY-PNpqX.js +0 -43
  159. package/dist/chunks/optionsFromZod-CKMYSwTz.js +0 -3636
  160. package/dist/chunks/paletteRegistry-BCFSwJGK.js +0 -1196
  161. package/dist/chunks/parse-BMTqt4SS.js +0 -3658
  162. package/dist/src/data/csv-variant-detection.d.ts +0 -29
  163. package/dist/src/data/ingest.d.ts +0 -104
@@ -0,0 +1,366 @@
1
+ /**
2
+ * @file The public types of the simple extension tier: one plain definition object per point,
3
+ * the graph view an algorithm or a layout reads, and the option short form.
4
+ *
5
+ * The simple tier covers algorithms, layouts, palettes and log destinations. File formats, data
6
+ * sources and camera motions have no simple tier yet.
7
+ *
8
+ * Every `define*` function builds an ordinary advanced registration from its definition and
9
+ * files it through the point's published verb, so a simple-tier extension IS an advanced one once
10
+ * registered.
11
+ *
12
+ * Types only: nothing here reaches Babylon.js, Lit or the DOM.
13
+ */
14
+ import type { OptionDescriptor, OptionType, PaletteDescriptor } from "../catalog/types";
15
+ /** A node id as the data spelled it. */
16
+ export type NodeId = string | number;
17
+ /**
18
+ * One option in short form. A bare number, string or boolean is an option of that type with that
19
+ * default. An object is an OptionDescriptor without `name` (the key is the name) and with
20
+ * `plainName` optional (derived from the key: "tierAttribute" reads "Tier attribute").
21
+ */
22
+ export type OptionShorthand = number | string | boolean | (Readonly<Partial<Omit<OptionDescriptor, "name" | "type" | "on">>> & {
23
+ readonly type: Exclude<OptionType, "unknown">;
24
+ /**
25
+ * For type "attribute" or "partition": whether the attribute is read from nodes (the
26
+ * default) or from edges. Carried into the generated OptionDescriptor as `on`.
27
+ */
28
+ readonly on?: "node" | "edge";
29
+ });
30
+ /** The options of one simple-tier extension, keyed by name. Order is the order a form shows. */
31
+ export type OptionsShorthand = Readonly<Record<string, OptionShorthand>>;
32
+ /** The value type one short-form option resolves to: `60` gives number, `"name"` string. */
33
+ export type ShorthandValue<S> = S extends number ? number : S extends boolean ? boolean : S extends string ? string : S extends {
34
+ readonly type: "number" | "integer" | "seed";
35
+ } ? number : S extends {
36
+ readonly type: "boolean";
37
+ } ? boolean : S extends {
38
+ readonly type: "node-id";
39
+ } ? NodeId : S extends {
40
+ readonly type: "node-set";
41
+ } ? readonly NodeId[] : S extends {
42
+ readonly type: "enum";
43
+ readonly values: readonly {
44
+ readonly value: infer V;
45
+ }[];
46
+ } ? V : string;
47
+ /**
48
+ * The resolved option values an extension's functions receive, typed from the declaration with no
49
+ * generic written by the author. An option with a default is always present; one with no default,
50
+ * or with `default: null`, may be undefined. An "attribute" option with no default is NOT BOUND
51
+ * unless the reader picks an attribute, and passing its undefined value to attr() or number()
52
+ * returns undefined.
53
+ */
54
+ export type OptionValuesOf<O extends OptionsShorthand> = {
55
+ readonly [K in keyof O]: O[K] extends number | string | boolean | {
56
+ readonly default: NonNullable<unknown>;
57
+ } ? ShorthandValue<O[K]> : ShorthandValue<O[K]> | undefined;
58
+ };
59
+ /** Members every definition has. Only `id` is required. */
60
+ export interface DefinitionBase<O extends OptionsShorthand> {
61
+ /** Permanent id: lower case, hyphenated, vendor-prefixed ("acme-hop-reach"). Kept unchanged when the extension graduates. */
62
+ readonly id: string;
63
+ /** What pickers show. Default: the id in sentence case ("acme-hop-reach" reads "Acme hop reach"). */
64
+ readonly name?: string;
65
+ /** One sentence for pickers and the catalogue. Default: "". */
66
+ readonly description?: string;
67
+ /** The options a reader may set, in short form: `{ spacing: 2, weight: { type: "attribute", on: "edge" } }`. */
68
+ readonly options?: O;
69
+ /** The extension's own semver version, recorded as provenance. */
70
+ readonly version?: string;
71
+ }
72
+ /**
73
+ * The whole graph, as nodes and edges with real ids. Iteration order is stable: numeric ids
74
+ * ascending, then string ids in code-unit order (edges by edge id), the order compareNodeIds
75
+ * defines, so a result does not depend on the order records were loaded in.
76
+ *
77
+ * Every array a view hands back (nodes(), edges(), and each node's neighbors(), edges() and
78
+ * directed forms) is frozen, built once per run and cached, so calling a method again inside a
79
+ * loop costs nothing.
80
+ */
81
+ export interface GraphView {
82
+ /** True when the definition asked for `direction: "directed"` and the graph has directed edges. */
83
+ readonly directed: boolean;
84
+ /** How many nodes the graph has. */
85
+ readonly nodeCount: number;
86
+ /** How many edges the graph has, parallel edges and self-loops each counted. */
87
+ readonly edgeCount: number;
88
+ /** Every node, in the view's order. */
89
+ nodes(): readonly NodeView[];
90
+ /** Every edge; parallel edges are separate edges, each with its own id. */
91
+ edges(): readonly EdgeView[];
92
+ /** The node with this id, or undefined. The id is matched as the data spelled it: 0 and "0" are two nodes. */
93
+ node(id: NodeId): NodeView | undefined;
94
+ /** The edge with this edge id, or undefined. */
95
+ edge(id: string): EdgeView | undefined;
96
+ /**
97
+ * The nodes grouped by the value at `path`, each group in the view's order. Groups come in
98
+ * readable order: numbers ascending, then text in natural order ("2" before "10"). A node
99
+ * without the attribute is in no group; an undefined `path` gives an empty map.
100
+ */
101
+ groupBy(path: string | undefined): ReadonlyMap<string | number | boolean, readonly NodeView[]>;
102
+ }
103
+ /** One node of the graph an algorithm or a layout reads. */
104
+ export interface NodeView {
105
+ /** The node's id, as the data spelled it. */
106
+ readonly id: NodeId;
107
+ /**
108
+ * edges().length: a self-loop counts ONCE and each parallel edge counts. This is NOT the
109
+ * built-in "degree" algorithm's number, which counts a self-loop twice and a repeated edge
110
+ * (same ends, same direction) once. NetworkX and igraph count a self-loop twice: add
111
+ * edgesTo(node).length to match them. For the number of distinct neighbours, use
112
+ * neighbors().length.
113
+ */
114
+ readonly degree: number;
115
+ /** Every adjacent node once, whichever way the edge points. Never the node itself: a self-loop is in edges() only. */
116
+ neighbors(): readonly NodeView[];
117
+ /**
118
+ * The directed forms. They throw unless the definition declares `direction: "directed"`, so a
119
+ * plugin never reads direction the view was not built with. With `direction: "directed"`, an
120
+ * undirected edge counts both ways: it is in both outEdges() and inEdges() of each end.
121
+ */
122
+ outNeighbors(): readonly NodeView[];
123
+ /** The nodes whose edges lead to this one. Needs `direction: "directed"`, as outNeighbors does. */
124
+ inNeighbors(): readonly NodeView[];
125
+ /** Every edge touching this node, parallel edges included. Use edge.other(node) for the far end. */
126
+ edges(): readonly EdgeView[];
127
+ /** The edges leaving this node. Needs `direction: "directed"`, as outNeighbors does. */
128
+ outEdges(): readonly EdgeView[];
129
+ /** The edges entering this node. Needs `direction: "directed"`, as outNeighbors does. */
130
+ inEdges(): readonly EdgeView[];
131
+ /**
132
+ * Every edge between this node and `other`, parallel edges included; empty when they are not
133
+ * adjacent. `node.edgesTo(node)` is the node's self-loops. In a directed view, only the edges
134
+ * from this node to `other`.
135
+ */
136
+ edgesTo(other: NodeView): readonly EdgeView[];
137
+ /**
138
+ * The sum of edge.weight(path) over edgesTo(other) -- w_ij, with parallel edges added together.
139
+ * undefined when there is no such edge, AND when the edges exist but none of them has a number
140
+ * at `path`; an edge without a number is left out of the sum. The weight rule is
141
+ * EdgeView.weight's.
142
+ */
143
+ weightTo(other: NodeView, path: string | undefined): number | undefined;
144
+ /**
145
+ * The weighted degree: the sum of edge.weight(path) over edges() (default "all"), or over
146
+ * outEdges() / inEdges() (which need `direction: "directed"`). With `path` undefined it is the
147
+ * degree. An edge with no number at `path` is left out and counted in the run record's warning.
148
+ * A self-loop counts once, as in degree. Computed once per node, path and direction per run,
149
+ * so calling it from edge() is cheap.
150
+ */
151
+ strength(path: string | undefined, direction?: "all" | "out" | "in"): number;
152
+ /**
153
+ * An attribute or a published result, by path: the key on the node record as loaded (`tier`
154
+ * for `{ id: 1, tier: 2 }`), a dotted path into it ("location.lat"), or a result
155
+ * ("results.clusters.group"). undefined when absent, or when `path` is undefined (an unbound
156
+ * optional "attribute" option).
157
+ */
158
+ attr(path: string | undefined): unknown;
159
+ /** attr(path) when it is a finite number; undefined otherwise. A numeric string is NOT parsed. */
160
+ number(path: string | undefined): number | undefined;
161
+ }
162
+ /** One edge of the graph an algorithm or a layout reads. */
163
+ export interface EdgeView {
164
+ /** The element's edge id: the same id a selection, a style and an export use. */
165
+ readonly id: string;
166
+ /**
167
+ * The endpoints as the data stored them. In a directed view `source` is where the edge starts.
168
+ * In an undirected view the two are just the two ends: use other(node).
169
+ */
170
+ readonly source: NodeView;
171
+ /** The other end the data stored: where a directed edge ends. */
172
+ readonly target: NodeView;
173
+ /** The end that is not `node` (a self-loop returns `node`). Throws when `node` is not an end. */
174
+ other(node: NodeView): NodeView;
175
+ /**
176
+ * The edge's weight at `path`: 1 when `path` is undefined (an unbound optional weight), the
177
+ * number when there is one, undefined when the value is missing or is not a number. A read
178
+ * that finds no number is counted in the run record's warning, never read as 0.
179
+ */
180
+ weight(path: string | undefined): number | undefined;
181
+ /** An attribute or a published result, by path, as NodeView.attr reads one. */
182
+ attr(path: string | undefined): unknown;
183
+ /** attr(path) when it is a finite number; undefined otherwise. */
184
+ number(path: string | undefined): number | undefined;
185
+ }
186
+ /** What an algorithm's function receives beside the node, edge or graph. */
187
+ export interface AlgorithmContext<V> {
188
+ /** The option values, checked and with their defaults filled in. */
189
+ readonly options: V;
190
+ /** The whole graph. */
191
+ readonly graph: GraphView;
192
+ /** Aborted when the run is cancelled. Only a whole-graph function needs it. */
193
+ readonly signal: AbortSignal;
194
+ /**
195
+ * Only a whole-graph function needs it: the share of the work done, 0 to 1. AWAIT it inside a
196
+ * loop: the promise lets the page draw a frame, and rejects with the abort reason when the run
197
+ * was cancelled.
198
+ */
199
+ progress(fraction: number): Promise<void>;
200
+ /** A sentence for the run record's caveats ("Dangling mass returns to the seeds."). */
201
+ note(text: string): void;
202
+ /** Record how an iterative method ended; a run that did not converge says so in its caveats. */
203
+ converged(converged: boolean, iterations: number): void;
204
+ }
205
+ /** A score. undefined, null, NaN or an infinity means "not measured": the element publishes nothing for it. */
206
+ export type Score = number | null | undefined;
207
+ interface AlgorithmDefinitionBase<O extends OptionsShorthand> extends DefinitionBase<O> {
208
+ /** "undirected" (the default) ignores edge direction, and the directed accessors of the view throw. */
209
+ readonly direction?: "undirected" | "directed";
210
+ /**
211
+ * Optional: the edge "attribute" option that holds weights, and what they mean. Only what the
212
+ * run record says a weight meant; the weight it records is the one the run actually read.
213
+ */
214
+ readonly weights?: {
215
+ readonly option: keyof O & string;
216
+ readonly meaning: "distance" | "strength";
217
+ };
218
+ /** For a whole-graph function that walks the graph repeatedly: the integer option that caps the passes. */
219
+ readonly passes?: keyof O & string;
220
+ }
221
+ /** A score per node, computed one node at a time. Published as a node-metric result, field "value". */
222
+ export interface NodeScoreDefinition<O extends OptionsShorthand> extends AlgorithmDefinitionBase<O> {
223
+ /** The score of one node; called once per node. Return the number itself, not a promise. */
224
+ readonly node: (node: NodeView, context: AlgorithmContext<OptionValuesOf<O>>) => Score;
225
+ readonly edge?: never;
226
+ readonly nodes?: never;
227
+ readonly groups?: never;
228
+ }
229
+ /** A score per edge, computed one edge at a time. Published as an edge-metric result, field "value". */
230
+ export interface EdgeScoreDefinition<O extends OptionsShorthand> extends AlgorithmDefinitionBase<O> {
231
+ /** The score of one edge; called once per edge. Return the number itself, not a promise. */
232
+ readonly edge: (edge: EdgeView, context: AlgorithmContext<OptionValuesOf<O>>) => Score;
233
+ readonly node?: never;
234
+ readonly nodes?: never;
235
+ readonly groups?: never;
236
+ }
237
+ /** A score per node computed over the whole graph at once (an iteration, a propagation). */
238
+ export interface WholeGraphScoreDefinition<O extends OptionsShorthand> extends AlgorithmDefinitionBase<O> {
239
+ /** Every node's score at once, as a Map keyed by node.id; may be async. */
240
+ readonly nodes: (graph: GraphView, context: AlgorithmContext<OptionValuesOf<O>>) => ReadonlyMap<NodeId, Score> | Promise<ReadonlyMap<NodeId, Score>>;
241
+ readonly node?: never;
242
+ readonly edge?: never;
243
+ readonly groups?: never;
244
+ }
245
+ /** A group per node (a clustering). Published as a community result, field "group". */
246
+ export interface GroupingDefinition<O extends OptionsShorthand> extends AlgorithmDefinitionBase<O> {
247
+ /** Every node's group at once, as a Map keyed by node.id to a number or a string; may be async. */
248
+ readonly groups: (graph: GraphView, context: AlgorithmContext<OptionValuesOf<O>>) => ReadonlyMap<NodeId, string | number | null | undefined> | Promise<ReadonlyMap<NodeId, string | number | null | undefined>>;
249
+ readonly node?: never;
250
+ readonly edge?: never;
251
+ readonly nodes?: never;
252
+ }
253
+ /** What defineAlgorithm takes: an id, options in short form and exactly one of node, edge, nodes or groups. */
254
+ export type AlgorithmDefinition<O extends OptionsShorthand> = NodeScoreDefinition<O> | EdgeScoreDefinition<O> | WholeGraphScoreDefinition<O> | GroupingDefinition<O>;
255
+ /** A position in scene units: [x, y] or [x, y, z]. A 2D position in a 3D view gets z = 0. */
256
+ export type Point = readonly [number, number] | readonly [number, number, number];
257
+ /** What a layout's `place` receives beside the graph. */
258
+ export interface LayoutContext<V> {
259
+ /** The option values, checked and with their defaults filled in. */
260
+ readonly options: V;
261
+ /** The view's dimensions. In 2D the element drops any z returned. */
262
+ readonly dimensions: 2 | 3;
263
+ /** Where a pinned or held node is, or null for a node the layout may place. */
264
+ fixed(id: NodeId): Point | null;
265
+ /** Seeded random numbers in [0, 1). Deterministic unless the definition sets `random: true`. */
266
+ random(): number;
267
+ /** Aborted when a newer layout replaces this one. */
268
+ readonly signal: AbortSignal;
269
+ /** As AlgorithmContext.progress: await it inside a loop to keep the page responsive. */
270
+ progress(fraction: number): Promise<void>;
271
+ }
272
+ /** What defineLayout takes: an id, options in short form and `place`. */
273
+ export interface LayoutDefinition<O extends OptionsShorthand> extends DefinitionBase<O> {
274
+ /** The most dimensions the layout uses. Default 3. */
275
+ readonly dimensions?: 2 | 3;
276
+ /** True when the result should change from run to run; the element then draws and records a seed. */
277
+ readonly random?: boolean;
278
+ /**
279
+ * Where each node goes, in scene units (a node at the default size is 1 unit across; +x is
280
+ * right and +y is up, as in the scene). A node
281
+ * missing from the map, or mapped to null or to a non-finite number, is UNPLACED. A value for a
282
+ * pinned or held node is ignored.
283
+ */
284
+ readonly place: (graph: GraphView, context: LayoutContext<OptionValuesOf<O>>) => ReadonlyMap<NodeId, Point | null> | Promise<ReadonlyMap<NodeId, Point | null>>;
285
+ }
286
+ /** A colour-vision deficiency a palette may claim to stay distinguishable under. */
287
+ export type ColorVisionDeficiency = PaletteDescriptor["colorblindSafe"][number];
288
+ /** What definePalette takes: an id, a kind and the colours. */
289
+ export interface PaletteDefinition {
290
+ /** Permanent id: lower case, hyphenated, vendor-prefixed ("acme-brand"). */
291
+ readonly id: string;
292
+ /** "categorical" (one colour per group), "sequential" (low to high) or "diverging" (through a middle). */
293
+ readonly kind: PaletteDescriptor["kind"];
294
+ /**
295
+ * Any colour CSS can parse EXCEPT var(), which definePalette refuses with the fix in the
296
+ * message. Normalised to six-digit hex, so an alpha channel is discarded. A categorical
297
+ * palette has one colour per group; the element never wraps. A ramp needs at least two.
298
+ */
299
+ readonly colors: readonly string[];
300
+ /** What pickers show. Default: the id in sentence case. */
301
+ readonly name?: string;
302
+ /** One sentence for pickers and the catalogue. */
303
+ readonly description?: string;
304
+ /** A claim the element takes on trust. Default: no claim. */
305
+ readonly colorblindSafe?: readonly ColorVisionDeficiency[];
306
+ }
307
+ /**
308
+ * The consumer call the simple tier adds to the element and to session.styles: the palette a
309
+ * colour binding uses when it names none, one per kind, resolved when a layer is written.
310
+ */
311
+ export interface DefaultPaletteControls {
312
+ /**
313
+ * Choose the palette each kind of colour binding uses when it names none. Call it before
314
+ * adding layers; `{ reapply: true }` repaints layers already written with the previous default.
315
+ */
316
+ setDefaultPalettes(palettes: {
317
+ readonly categorical?: string;
318
+ readonly sequential?: string;
319
+ readonly diverging?: string;
320
+ }, options?: {
321
+ readonly reapply?: boolean;
322
+ }): void;
323
+ }
324
+ /** A log level as a word, most severe first. */
325
+ export type LogLevelName = "error" | "warn" | "info" | "debug" | "trace";
326
+ /** A log record as a simple destination receives it. Frozen. */
327
+ export interface PlainLogRecord {
328
+ /** When it happened. */
329
+ readonly time: Date;
330
+ /** How severe it is. */
331
+ readonly level: LogLevelName;
332
+ /** The category path joined with "." ("graphty.layout.ngraph"). */
333
+ readonly category: string;
334
+ /** What happened, in a sentence. */
335
+ readonly message: string;
336
+ /** The facts attached, when there are any. They can hold graph content. */
337
+ readonly data?: Readonly<Record<string, unknown>>;
338
+ /** The failure as plain data, so JSON.stringify(record) keeps it. */
339
+ readonly error?: {
340
+ readonly name: string;
341
+ readonly message: string;
342
+ readonly stack?: string;
343
+ };
344
+ }
345
+ /** What defineLogDestination takes: an id and `write`. */
346
+ export interface LogDestinationDefinition {
347
+ /** Permanent id: lower case, hyphenated, vendor-prefixed ("acme-telemetry"). Defining it again replaces the earlier one. */
348
+ readonly id: string;
349
+ /** What a destination picker shows. Default: the id in sentence case. */
350
+ readonly name?: string;
351
+ /** One sentence for the catalogue. */
352
+ readonly description?: string;
353
+ /** The least severe level delivered. Default "warn". */
354
+ readonly level?: LogLevelName;
355
+ /** Only records whose category contains one of these segments. */
356
+ readonly categories?: readonly string[];
357
+ /**
358
+ * May return a promise (a fetch); the element queues, orders, retries and flushes. A rejection,
359
+ * or a promise that resolves to a fetch Response whose `ok` is false, counts as a failed send.
360
+ * `Promise<unknown>`, so `fetch(...)` (a `Promise<Response>`) can be returned as it is.
361
+ */
362
+ readonly write: (record: PlainLogRecord) => void | Promise<unknown>;
363
+ /** Attach now (the default) or only register, for a configuration to turn on by id. */
364
+ readonly attach?: boolean;
365
+ }
366
+ export {};
@@ -0,0 +1,107 @@
1
+ /**
2
+ * @file The graph view of the simple extension tier: the whole graph as nodes and edges with
3
+ * their real ids, built once per run over the element's snapshot.
4
+ *
5
+ * An author reads `node.neighbors()`, `edge.other(node)`, `node.strength("confidence")` and never
6
+ * sees a row, a typed array or an adjacency index. Everything below exists to keep the numbers
7
+ * those calls give honest:
8
+ *
9
+ * - ORDER IS THE IDS', NOT THE LOAD'S. Nodes iterate numbers ascending, then strings by code unit
10
+ * (`compareNodeIds`); edges by their numeric edge id; every node's lists follow the same order.
11
+ * So a result never depends on which record happened to arrive first.
12
+ * - A SELF-LOOP COUNTS ONCE and is never its own neighbour; PARALLEL EDGES STAY SEPARATE, each with
13
+ * its own id, and add together in `weightTo`.
14
+ * - DIRECTION IS NEVER GUESSED. A definition that did not ask for `direction: "directed"` gets a
15
+ * view whose directed accessors throw, so a plugin cannot read a direction the view was not
16
+ * built with and publish plausible wrong numbers.
17
+ * - A MISSING WEIGHT IS NEVER A ZERO. An edge with no number at the path is left out of a sum and
18
+ * counted; `viewWarnings` turns the counts into the run record's warning.
19
+ * - A PATH NOTHING CARRIES FAILS LOUDLY, at its first read, naming what the elements do carry,
20
+ * instead of reading as undefined everywhere.
21
+ *
22
+ * Every array handed back is frozen, built on first use and cached, so a call inside a loop costs
23
+ * nothing after the first.
24
+ *
25
+ * Nothing here reaches Babylon.js, Lit or the DOM.
26
+ */
27
+ import { type GraphtyErrorSource } from "../errors";
28
+ import type { ViewSource, ViewTarget } from "./source";
29
+ import type { GraphView, NodeId } from "./types";
30
+ /**
31
+ * The order every graph view iterates in: numbers ascending, then strings in code-unit order.
32
+ * Published so an order-dependent method that graduates to the advanced tier can sort the same way.
33
+ * @param a - One id.
34
+ * @param b - The other.
35
+ * @returns Negative, zero or positive.
36
+ */
37
+ export declare function compareNodeIds(a: NodeId, b: NodeId): number;
38
+ /** How a view is built. */
39
+ interface GraphViewOptions {
40
+ /** The extension's id: every message the view writes starts with it. */
41
+ readonly id: string;
42
+ /** Whether the definition declared `direction: "directed"`. */
43
+ readonly directed: boolean;
44
+ /** Which area of the element a refusal names. Default "run". */
45
+ readonly source?: GraphtyErrorSource;
46
+ }
47
+ /** The facts a refusal of a path is worded from. */
48
+ interface PathRefusalFacts {
49
+ readonly target: ViewTarget;
50
+ readonly path: string;
51
+ /** The attribute names that kind of element does carry. */
52
+ readonly carriers: readonly string[];
53
+ /** The run a `results.<run>.<field>` path names, when it is one. */
54
+ readonly run?: string;
55
+ }
56
+ /**
57
+ * An id as a message quotes it: a number bare, a string in double quotes.
58
+ * @param id - The id.
59
+ * @returns The quoted id.
60
+ */
61
+ export declare function quoteId(id: NodeId): string;
62
+ /**
63
+ * What a kind of element does carry, for a refusal: "nodes carry: tier, name".
64
+ * @param facts - What was found.
65
+ * @returns The clause, with no closing full stop.
66
+ */
67
+ export declare function carriedList(facts: PathRefusalFacts): string;
68
+ /**
69
+ * Build the graph view over a source.
70
+ * @param source - The snapshot and the value reader (see `viewSourceOf`).
71
+ * @param options - The extension id and whether its definition declared direction.
72
+ * @returns The view.
73
+ */
74
+ export declare function createGraphView(source: ViewSource, options: GraphViewOptions): GraphView;
75
+ /**
76
+ * Check a path the way a first read checks it, with the caller's own wording: how an option that
77
+ * names an attribute is checked before the author's code runs.
78
+ * @param view - The view.
79
+ * @param target - Nodes or edges.
80
+ * @param path - The path.
81
+ * @param refusal - Words the refusal from what was found.
82
+ */
83
+ export declare function requireCarried(view: GraphView, target: ViewTarget, path: string, refusal: (facts: PathRefusalFacts) => string): void;
84
+ /**
85
+ * Every path the view has read, for the run record's list of inputs.
86
+ * @param view - The view.
87
+ * @returns The paths, with the kind of element each was read on, in first-read order.
88
+ */
89
+ export declare function viewInputs(view: GraphView): readonly {
90
+ readonly target: ViewTarget;
91
+ readonly path: string;
92
+ }[];
93
+ /**
94
+ * The edge paths the run read as weights -- through edge.weight, node.strength or node.weightTo --
95
+ * which is what the run record's weight says the numbers used.
96
+ * @param view - The view.
97
+ * @returns The paths, in first-read order.
98
+ */
99
+ export declare function viewWeightPaths(view: GraphView): readonly string[];
100
+ /**
101
+ * The warnings a run over this view completes with: one per path at which some read found no
102
+ * number.
103
+ * @param view - The view.
104
+ * @returns The sentences, in first-read order; empty when every read found a number.
105
+ */
106
+ export declare function viewWarnings(view: GraphView): readonly string[];
107
+ export {};
package/dist/webgpu.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { EXACT_MAX_NODES as n, createAccelerator as p, verifyDevice as u } from "@graphty/webgpu-graph-algorithms";
2
2
  import { probeBrowserWebGpu as l, requestGpuContext as d } from "@graphty/webgpu-graph-algorithms/browser";
3
- import { r as h } from "./chunks/registry-BdGvyZou.js";
4
- import { G as s } from "./chunks/pluginRegistry-Bs8bEkz9.js";
3
+ import { r as h } from "./chunks/registry-CgMqldp4.js";
4
+ import { G as s } from "./chunks/pluginRegistry-Ddfl6Mv2.js";
5
5
  const a = "webgpu-graph-algorithms", w = /* @__PURE__ */ new Set(["kind", "ctx", "options", "dispose", "verify"]);
6
6
  function b(o, e) {
7
7
  for (const [r, t] of Object.entries(o))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@graphty/graphty-element",
3
- "version": "2.6.1",
3
+ "version": "3.0.0",
4
4
  "description": "A Web Component library for 3D/2D graph visualization built with Lit and Babylon.js",
5
5
  "type": "module",
6
6
  "customElements": "./dist/custom-elements.json",
@@ -113,7 +113,6 @@
113
113
  "@types/hammerjs": "^2.0.46",
114
114
  "@types/jmespath": "^0.15.2",
115
115
  "@types/lodash": "^4.17.19",
116
- "@types/papaparse": "^5.5.0",
117
116
  "@types/toposort": "^2.0.7",
118
117
  "@vitest/browser-playwright": "4.1.11",
119
118
  "ai": "^5.0.104",
@@ -137,9 +136,9 @@
137
136
  "vite-plugin-eslint": "^1.8.1",
138
137
  "vitepress": "^1.6.3",
139
138
  "vitest": "4.1.11",
140
- "@graphty/remote-logger": "^1.3.10",
141
- "@graphty/graph-samples": "^0.1.6",
142
- "@graphty/webgpu-graph-algorithms": "^0.6.11"
139
+ "@graphty/graph-samples": "^0.1.8",
140
+ "@graphty/remote-logger": "^1.3.12",
141
+ "@graphty/webgpu-graph-algorithms": "^0.6.13"
143
142
  },
144
143
  "peerDependencies": {
145
144
  "@ai-sdk/anthropic": "^2.0.50",
@@ -151,7 +150,7 @@
151
150
  "ai": "^5.0.104",
152
151
  "encrypt-storage": "^2.14.7",
153
152
  "lit": "^3.0.0",
154
- "@graphty/webgpu-graph-algorithms": "^0.6.11"
153
+ "@graphty/webgpu-graph-algorithms": "^0.6.13"
155
154
  },
156
155
  "peerDependenciesMeta": {
157
156
  "@ai-sdk/anthropic": {
@@ -180,18 +179,17 @@
180
179
  "@jsonhero/schema-infer": "^0.1.5",
181
180
  "colorjs.io": "^0.5.2",
182
181
  "d3-force-3d": "^3.0.6",
183
- "fast-xml-parser": "^5.3.1",
184
182
  "hammerjs": "^2.0.8",
185
183
  "jmespath": "^0.16.0",
186
184
  "ngraph.forcelayout": "^3.3.1",
187
185
  "ngraph.graph": "^20.0.1",
188
186
  "p-queue": "^8.1.1",
189
- "papaparse": "^5.5.3",
190
187
  "toposort": "^2.0.2",
191
188
  "zod": "^3.25.28",
192
- "@graphty/graph-format": "^1.1.1",
193
- "@graphty/algorithms": "^2.1.1",
194
- "@graphty/layout": "^1.10.4"
189
+ "@graphty/algorithms": "^2.2.0",
190
+ "@graphty/graph-format": "^1.2.0",
191
+ "@graphty/layout": "^2.0.0",
192
+ "@graphty/graph-io": "^0.3.10"
195
193
  },
196
194
  "overrides": {
197
195
  "storybook": "$storybook"
@@ -256,7 +254,7 @@
256
254
  "lint:knip": "cd .. && ./tools/run-knip.sh --workspace graphty-element",
257
255
  "dev": "vite --force --mode development --port ${PORT:?start it through servherd, which sets PORT} --strictPort",
258
256
  "dev:xr": "node examples/xr/xr-demo-server.js",
259
- "build": "vite build && vite build --config vite.bundle.config.ts && tsc --project tsconfig.build.json && node scripts/generate-catalog-json.mjs",
257
+ "build": "vite build && vite build --config vite.bundle.config.ts && tsc --project tsconfig.build.json && node scripts/generate-catalog-json.mjs && node --experimental-strip-types scripts/write-doors-json.mjs",
260
258
  "preview": "vite preview --port ${PORT:?start it through servherd, which sets PORT} --strictPort",
261
259
  "build:storybook": "npm run build-storybook",
262
260
  "storybook": "rm -rf node_modules/.vite && npm run build-storybook && storybook dev -p ${PORT:?start it through servherd, which sets PORT} --host ${HOST:-localhost} ${HTTPS_CERT_PATH:+--https --ssl-cert $HTTPS_CERT_PATH --ssl-key $HTTPS_KEY_PATH} --no-open",