@opendata-ai/openchart-engine 8.0.0-rc.9 → 8.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 (271) hide show
  1. package/dist/index.d.ts +149 -12
  2. package/dist/index.js +804 -155
  3. package/dist/index.js.map +1 -1
  4. package/package.json +3 -4
  5. package/src/__test-fixtures__/specs.ts +0 -182
  6. package/src/__tests__/__snapshots__/compile-snapshot.test.ts.snap +0 -2401
  7. package/src/__tests__/annotation-behavior.test.ts +0 -852
  8. package/src/__tests__/axes.test.ts +0 -1579
  9. package/src/__tests__/compile-animation.test.ts +0 -161
  10. package/src/__tests__/compile-chart.test.ts +0 -1303
  11. package/src/__tests__/compile-footnotes.test.ts +0 -277
  12. package/src/__tests__/compile-layer.test.ts +0 -969
  13. package/src/__tests__/compile-snapshot.test.ts +0 -156
  14. package/src/__tests__/compound-labels.test.ts +0 -147
  15. package/src/__tests__/dimensions.test.ts +0 -918
  16. package/src/__tests__/encoding-sugar.test.ts +0 -390
  17. package/src/__tests__/facet.test.ts +0 -215
  18. package/src/__tests__/helpers/invariants.ts +0 -299
  19. package/src/__tests__/known-bugs.test.ts +0 -566
  20. package/src/__tests__/layout-fuzz.test.ts +0 -358
  21. package/src/__tests__/layout-invariants.test.ts +0 -535
  22. package/src/__tests__/legend.test.ts +0 -721
  23. package/src/__tests__/mark-keys.test.ts +0 -294
  24. package/src/__tests__/ranking-recipes.test.ts +0 -260
  25. package/src/__tests__/rotation.test.ts +0 -83
  26. package/src/__tests__/scales.test.ts +0 -323
  27. package/src/__tests__/series-search.test.ts +0 -92
  28. package/src/__tests__/spec-sugar.test.ts +0 -801
  29. package/src/__tests__/you-draw-it.test.ts +0 -160
  30. package/src/annotations/__tests__/compute.test.ts +0 -1672
  31. package/src/annotations/__tests__/geometry.test.ts +0 -66
  32. package/src/annotations/__tests__/placement-fuzz.test.ts +0 -256
  33. package/src/annotations/__tests__/placement-invariants.test.ts +0 -345
  34. package/src/annotations/__tests__/placement.test.ts +0 -316
  35. package/src/annotations/__tests__/resolve-text.test.ts +0 -788
  36. package/src/annotations/__tests__/rich-text.test.ts +0 -91
  37. package/src/annotations/__tests__/thinning.test.ts +0 -285
  38. package/src/annotations/collisions.ts +0 -326
  39. package/src/annotations/compute.ts +0 -333
  40. package/src/annotations/constants.ts +0 -162
  41. package/src/annotations/geometry.ts +0 -376
  42. package/src/annotations/move.ts +0 -135
  43. package/src/annotations/placement.ts +0 -636
  44. package/src/annotations/position.ts +0 -131
  45. package/src/annotations/resolve-range.ts +0 -117
  46. package/src/annotations/resolve-refline.ts +0 -157
  47. package/src/annotations/resolve-text.ts +0 -545
  48. package/src/annotations/rich-text.ts +0 -65
  49. package/src/annotations/thinning.ts +0 -190
  50. package/src/barlist/__tests__/compile-barlist.test.ts +0 -200
  51. package/src/barlist/compile-barlist.ts +0 -391
  52. package/src/barlist/types.ts +0 -28
  53. package/src/charts/__tests__/post-process.test.ts +0 -237
  54. package/src/charts/__tests__/registry.test.ts +0 -116
  55. package/src/charts/__tests__/utils.test.ts +0 -195
  56. package/src/charts/_shared/__tests__/density-filter.test.ts +0 -32
  57. package/src/charts/_shared/density-filter.ts +0 -26
  58. package/src/charts/_shared/format-label-value.ts +0 -16
  59. package/src/charts/bar/__tests__/compute.test.ts +0 -934
  60. package/src/charts/bar/__tests__/gradient-orient.test.ts +0 -127
  61. package/src/charts/bar/__tests__/labels.test.ts +0 -292
  62. package/src/charts/bar/compute.ts +0 -539
  63. package/src/charts/bar/index.ts +0 -60
  64. package/src/charts/bar/labels.ts +0 -311
  65. package/src/charts/beeswarm/__tests__/compute.test.ts +0 -280
  66. package/src/charts/beeswarm/__tests__/dodge.test.ts +0 -148
  67. package/src/charts/beeswarm/compute.ts +0 -203
  68. package/src/charts/beeswarm/dodge.ts +0 -155
  69. package/src/charts/beeswarm/index.ts +0 -32
  70. package/src/charts/builtin.ts +0 -75
  71. package/src/charts/calendar/__tests__/compute.test.ts +0 -417
  72. package/src/charts/calendar/compute.ts +0 -319
  73. package/src/charts/calendar/index.ts +0 -32
  74. package/src/charts/column/__tests__/compute.test.ts +0 -540
  75. package/src/charts/column/__tests__/labels.test.ts +0 -179
  76. package/src/charts/column/compute.ts +0 -493
  77. package/src/charts/column/index.ts +0 -53
  78. package/src/charts/column/labels.ts +0 -229
  79. package/src/charts/dot/__tests__/compute.test.ts +0 -380
  80. package/src/charts/dot/__tests__/labels.test.ts +0 -98
  81. package/src/charts/dot/compute.ts +0 -285
  82. package/src/charts/dot/index.ts +0 -62
  83. package/src/charts/dot/labels.ts +0 -121
  84. package/src/charts/line/__tests__/compute.test.ts +0 -1194
  85. package/src/charts/line/__tests__/curves.test.ts +0 -51
  86. package/src/charts/line/__tests__/labels.test.ts +0 -94
  87. package/src/charts/line/__tests__/mark-options.test.ts +0 -175
  88. package/src/charts/line/area.ts +0 -484
  89. package/src/charts/line/compute.ts +0 -356
  90. package/src/charts/line/curves.ts +0 -85
  91. package/src/charts/line/index.ts +0 -176
  92. package/src/charts/line/labels.ts +0 -177
  93. package/src/charts/parliament/__tests__/compute.test.ts +0 -411
  94. package/src/charts/parliament/compute.ts +0 -313
  95. package/src/charts/parliament/index.ts +0 -32
  96. package/src/charts/pie/__tests__/compute.test.ts +0 -384
  97. package/src/charts/pie/__tests__/labels.test.ts +0 -132
  98. package/src/charts/pie/compute.ts +0 -324
  99. package/src/charts/pie/index.ts +0 -49
  100. package/src/charts/pie/labels.ts +0 -143
  101. package/src/charts/post-process.ts +0 -229
  102. package/src/charts/range/__tests__/compute.test.ts +0 -486
  103. package/src/charts/range/compute.ts +0 -273
  104. package/src/charts/range/index.ts +0 -82
  105. package/src/charts/range/labels.ts +0 -169
  106. package/src/charts/rect/__tests__/compute.test.ts +0 -120
  107. package/src/charts/rect/index.ts +0 -127
  108. package/src/charts/registry.ts +0 -72
  109. package/src/charts/rule/index.ts +0 -139
  110. package/src/charts/scatter/__tests__/compute.test.ts +0 -488
  111. package/src/charts/scatter/__tests__/trendline.test.ts +0 -191
  112. package/src/charts/scatter/compute.ts +0 -192
  113. package/src/charts/scatter/index.ts +0 -46
  114. package/src/charts/scatter/trendline.ts +0 -100
  115. package/src/charts/text/__tests__/compute.test.ts +0 -307
  116. package/src/charts/text/index.ts +0 -141
  117. package/src/charts/tick/__tests__/compute.test.ts +0 -75
  118. package/src/charts/tick/index.ts +0 -99
  119. package/src/charts/utils.ts +0 -170
  120. package/src/charts/waffle/__tests__/compute.test.ts +0 -305
  121. package/src/charts/waffle/compute.ts +0 -197
  122. package/src/charts/waffle/index.ts +0 -31
  123. package/src/compile/__tests__/color-scale-range.test.ts +0 -158
  124. package/src/compile/__tests__/color-scale-reverse.test.ts +0 -89
  125. package/src/compile/__tests__/data-clip.test.ts +0 -127
  126. package/src/compile/__tests__/fill-patterns.test.ts +0 -154
  127. package/src/compile/__tests__/size-scale.test.ts +0 -108
  128. package/src/compile/__tests__/watermark-obstacle.test.ts +0 -93
  129. package/src/compile/color-scale-range.ts +0 -101
  130. package/src/compile/data-clip.ts +0 -48
  131. package/src/compile/fill-patterns.ts +0 -74
  132. package/src/compile/layer.ts +0 -630
  133. package/src/compile/size-scale.ts +0 -141
  134. package/src/compile/spec-sugar.ts +0 -758
  135. package/src/compile/watermark-obstacle.ts +0 -54
  136. package/src/compile/you-draw-it.ts +0 -123
  137. package/src/compile.ts +0 -1503
  138. package/src/compiler/__tests__/a11y-warnings.test.ts +0 -148
  139. package/src/compiler/__tests__/animation.test.ts +0 -177
  140. package/src/compiler/__tests__/compile.test.ts +0 -87
  141. package/src/compiler/__tests__/fixtures/vl-parity/axis-null.json +0 -19
  142. package/src/compiler/__tests__/fixtures/vl-parity/color-value.json +0 -20
  143. package/src/compiler/__tests__/fixtures/vl-parity/count-aggregate.json +0 -22
  144. package/src/compiler/__tests__/fixtures/vl-parity/data-values.json +0 -19
  145. package/src/compiler/__tests__/fixtures/vl-parity/layer-axis-null.json +0 -14
  146. package/src/compiler/__tests__/fixtures/vl-parity/layer-count.json +0 -34
  147. package/src/compiler/__tests__/fixtures/vl-parity/layer-data-values.json +0 -22
  148. package/src/compiler/__tests__/fixtures/vl-parity/layer-legend-null.json +0 -41
  149. package/src/compiler/__tests__/fixtures/vl-parity/layer-scheme.json +0 -38
  150. package/src/compiler/__tests__/fixtures/vl-parity/layer-sort.json +0 -28
  151. package/src/compiler/__tests__/fixtures/vl-parity/layer-theta.json +0 -28
  152. package/src/compiler/__tests__/fixtures/vl-parity/layer-title.json +0 -30
  153. package/src/compiler/__tests__/fixtures/vl-parity/layer-value-def.json +0 -29
  154. package/src/compiler/__tests__/fixtures/vl-parity/legend-null.json +0 -32
  155. package/src/compiler/__tests__/fixtures/vl-parity/scheme.json +0 -25
  156. package/src/compiler/__tests__/fixtures/vl-parity/sort-by-value.json +0 -19
  157. package/src/compiler/__tests__/fixtures/vl-parity/theta-arc.json +0 -19
  158. package/src/compiler/__tests__/fixtures/vl-parity/title-subtitle.json +0 -21
  159. package/src/compiler/__tests__/fixtures/vl-parity/width-height.json +0 -23
  160. package/src/compiler/__tests__/keys.test.ts +0 -83
  161. package/src/compiler/__tests__/normalize-highlight.test.ts +0 -103
  162. package/src/compiler/__tests__/normalize.test.ts +0 -399
  163. package/src/compiler/__tests__/sparkline-defaults.test.ts +0 -153
  164. package/src/compiler/__tests__/validate-did-you-mean.test.ts +0 -170
  165. package/src/compiler/__tests__/validate-highlight.test.ts +0 -112
  166. package/src/compiler/__tests__/validate-near-miss.test.ts +0 -251
  167. package/src/compiler/__tests__/validate.test.ts +0 -629
  168. package/src/compiler/__tests__/vl-parity.test.ts +0 -68
  169. package/src/compiler/a11y-warnings.ts +0 -110
  170. package/src/compiler/animation.ts +0 -142
  171. package/src/compiler/index.ts +0 -47
  172. package/src/compiler/keys.ts +0 -55
  173. package/src/compiler/normalize.ts +0 -734
  174. package/src/compiler/sparkline-defaults.ts +0 -138
  175. package/src/compiler/types.ts +0 -241
  176. package/src/compiler/validate.ts +0 -2041
  177. package/src/endpoint-labels/__tests__/compute.test.ts +0 -587
  178. package/src/endpoint-labels/compute.ts +0 -621
  179. package/src/endpoint-labels/constants.ts +0 -54
  180. package/src/endpoint-labels/format.ts +0 -60
  181. package/src/endpoint-labels/predict.ts +0 -139
  182. package/src/format/__tests__/field-format.test.ts +0 -164
  183. package/src/format/field-format.ts +0 -27
  184. package/src/geo/__tests__/compile-map.test.ts +0 -1128
  185. package/src/geo/compile-map.ts +0 -1376
  186. package/src/geo/join.ts +0 -115
  187. package/src/geo/projections.ts +0 -65
  188. package/src/geo/types.ts +0 -26
  189. package/src/graphs/__tests__/community.test.ts +0 -228
  190. package/src/graphs/__tests__/compile-graph.test.ts +0 -396
  191. package/src/graphs/__tests__/encoding.test.ts +0 -415
  192. package/src/graphs/community.ts +0 -92
  193. package/src/graphs/compile-graph.ts +0 -329
  194. package/src/graphs/encoding.ts +0 -356
  195. package/src/graphs/types.ts +0 -106
  196. package/src/index.ts +0 -177
  197. package/src/layout/__tests__/metrics.test.ts +0 -97
  198. package/src/layout/__tests__/scales-highlight.test.ts +0 -192
  199. package/src/layout/axes/rotation.ts +0 -152
  200. package/src/layout/axes/thinning.ts +0 -98
  201. package/src/layout/axes/ticks.ts +0 -409
  202. package/src/layout/axes.ts +0 -757
  203. package/src/layout/dimensions.ts +0 -912
  204. package/src/layout/facet.ts +0 -91
  205. package/src/layout/gridlines.ts +0 -84
  206. package/src/layout/metrics.ts +0 -132
  207. package/src/layout/plan.ts +0 -631
  208. package/src/layout/scales.ts +0 -1053
  209. package/src/layout/shared.ts +0 -44
  210. package/src/legend/__tests__/continuous.test.ts +0 -318
  211. package/src/legend/__tests__/redundancy.test.ts +0 -108
  212. package/src/legend/__tests__/size.test.ts +0 -348
  213. package/src/legend/__tests__/suppression.test.ts +0 -382
  214. package/src/legend/compute.ts +0 -748
  215. package/src/legend/continuous.ts +0 -327
  216. package/src/legend/size.ts +0 -407
  217. package/src/legend/suppression.ts +0 -226
  218. package/src/legend/wrap.ts +0 -117
  219. package/src/sankey/__tests__/compile-sankey.test.ts +0 -458
  220. package/src/sankey/__tests__/layout.test.ts +0 -165
  221. package/src/sankey/__tests__/node-label-wrap.test.ts +0 -114
  222. package/src/sankey/__tests__/node-sort.test.ts +0 -45
  223. package/src/sankey/compile-sankey.ts +0 -706
  224. package/src/sankey/layout.ts +0 -184
  225. package/src/sankey/types.ts +0 -41
  226. package/src/tables/__tests__/bar-column.test.ts +0 -147
  227. package/src/tables/__tests__/category-colors.test.ts +0 -230
  228. package/src/tables/__tests__/compile-table.test.ts +0 -236
  229. package/src/tables/__tests__/format-cells.test.ts +0 -143
  230. package/src/tables/__tests__/heatmap.test.ts +0 -148
  231. package/src/tables/__tests__/pagination.test.ts +0 -78
  232. package/src/tables/__tests__/search.test.ts +0 -94
  233. package/src/tables/__tests__/sort.test.ts +0 -107
  234. package/src/tables/__tests__/sparkline.test.ts +0 -122
  235. package/src/tables/bar-column.ts +0 -94
  236. package/src/tables/category-colors.ts +0 -78
  237. package/src/tables/compile-table.ts +0 -427
  238. package/src/tables/format-cells.ts +0 -115
  239. package/src/tables/heatmap.ts +0 -141
  240. package/src/tables/pagination.ts +0 -46
  241. package/src/tables/search.ts +0 -66
  242. package/src/tables/sort.ts +0 -69
  243. package/src/tables/sparkline.ts +0 -113
  244. package/src/tables/utils.ts +0 -16
  245. package/src/tilemap/__tests__/compile-tilemap.test.ts +0 -576
  246. package/src/tilemap/compile-tilemap.ts +0 -755
  247. package/src/tilemap/layout.ts +0 -172
  248. package/src/tilemap/types.ts +0 -33
  249. package/src/tooltips/__tests__/compute.test.ts +0 -582
  250. package/src/tooltips/compute.ts +0 -700
  251. package/src/transforms/__tests__/aggregate.test.ts +0 -159
  252. package/src/transforms/__tests__/bin.test.ts +0 -88
  253. package/src/transforms/__tests__/calculate.test.ts +0 -146
  254. package/src/transforms/__tests__/conditional.test.ts +0 -127
  255. package/src/transforms/__tests__/filter-relative.test.ts +0 -202
  256. package/src/transforms/__tests__/filter.test.ts +0 -59
  257. package/src/transforms/__tests__/fold.test.ts +0 -79
  258. package/src/transforms/__tests__/index.test.ts +0 -93
  259. package/src/transforms/__tests__/predicates.test.ts +0 -193
  260. package/src/transforms/__tests__/timeunit.test.ts +0 -129
  261. package/src/transforms/__tests__/window.test.ts +0 -286
  262. package/src/transforms/aggregate.ts +0 -131
  263. package/src/transforms/bin.ts +0 -87
  264. package/src/transforms/calculate.ts +0 -60
  265. package/src/transforms/conditional.ts +0 -46
  266. package/src/transforms/filter.ts +0 -122
  267. package/src/transforms/fold.ts +0 -49
  268. package/src/transforms/index.ts +0 -60
  269. package/src/transforms/predicates.ts +0 -123
  270. package/src/transforms/timeunit.ts +0 -88
  271. package/src/transforms/window.ts +0 -185
@@ -1,329 +0,0 @@
1
- /**
2
- * Graph compilation pipeline.
3
- *
4
- * Takes a raw graph spec (unknown shape), validates, normalizes, resolves
5
- * encoding channels to visual properties, assigns communities, builds
6
- * legend/tooltips/a11y, and returns a GraphCompilation.
7
- *
8
- * The pipeline mirrors compileChart's structure:
9
- * validate -> normalize -> resolve theme -> resolve visuals ->
10
- * community assignment -> legend -> tooltips -> a11y -> return
11
- *
12
- * Key difference from charts: the output does NOT include x/y positions.
13
- * The force simulation in the adapter handles layout at runtime.
14
- */
15
-
16
- import type {
17
- CompileOptions,
18
- LegendEntry,
19
- LegendLayout,
20
- ResolvedTheme,
21
- TextStyle,
22
- TooltipContent,
23
- TooltipField,
24
- } from '@opendata-ai/openchart-core';
25
- import {
26
- adaptTheme,
27
- computeChrome,
28
- defaultNumberFormatter,
29
- resolveTheme,
30
- } from '@opendata-ai/openchart-core';
31
- import { emitSpecWarnings } from '../compile/spec-sugar';
32
- import { compile as compileSpec } from '../compiler/index';
33
- import type { NormalizedGraphSpec } from '../compiler/types';
34
- import { applyCommunityColors, assignCommunities, buildCommunityColorMap } from './community';
35
- import { resolveEdgeVisuals, resolveNodeVisuals } from './encoding';
36
- import type { CompiledGraphNode, GraphCompilation, SimulationConfig } from './types';
37
-
38
- const graphNumberFormatter = defaultNumberFormatter({ allIntegers: false, surface: 'chart' });
39
-
40
- // ---------------------------------------------------------------------------
41
- // Constants
42
- // ---------------------------------------------------------------------------
43
-
44
- const SWATCH_SIZE = 12;
45
- const SWATCH_GAP = 6;
46
- const ENTRY_GAP = 16;
47
-
48
- // ---------------------------------------------------------------------------
49
- // Legend builder
50
- // ---------------------------------------------------------------------------
51
-
52
- /**
53
- * Build a legend from community assignments or nodeColor encoding.
54
- *
55
- * Built manually instead of reusing computeLegend (which assumes chart
56
- * encoding channels). Returns entries with color swatches and labels.
57
- * Position is placeholder (adapter determines actual placement).
58
- */
59
- function buildGraphLegend(
60
- nodes: CompiledGraphNode[],
61
- communityColorMap: Map<string, string>,
62
- hasCommunities: boolean,
63
- theme: ResolvedTheme,
64
- nodeColorField?: string,
65
- ): LegendLayout {
66
- const labelStyle: TextStyle = {
67
- fontFamily: theme.fonts.family,
68
- fontSize: theme.fonts.sizes.small,
69
- fontWeight: theme.fonts.weights.normal,
70
- fill: theme.colors.text,
71
- lineHeight: 1.3,
72
- };
73
-
74
- let entries: LegendEntry[];
75
-
76
- if (hasCommunities && communityColorMap.size > 0) {
77
- // One entry per community
78
- entries = [...communityColorMap.entries()].map(([label, color]) => ({
79
- label,
80
- color,
81
- shape: 'circle' as const,
82
- active: true,
83
- }));
84
- } else if (nodeColorField) {
85
- // Build legend from nodeColor encoding: group by the color field value
86
- // so each legend entry shows the categorical value (e.g. "Dataset", "bls")
87
- // rather than an arbitrary node label.
88
- const categoryColors = new Map<string, string>();
89
- for (const node of nodes) {
90
- const category = String(node.data[nodeColorField] ?? node.label ?? node.id);
91
- if (!categoryColors.has(category)) {
92
- categoryColors.set(category, node.fill);
93
- }
94
- }
95
-
96
- // Only show legend if there are multiple categories
97
- entries =
98
- categoryColors.size <= 1
99
- ? []
100
- : [...categoryColors.entries()].map(([label, color]) => ({
101
- label,
102
- color,
103
- shape: 'circle' as const,
104
- active: true,
105
- }));
106
- } else {
107
- // No communities and no color encoding: every node shares one fill, so a
108
- // legend would just list every node label against identical swatches.
109
- entries = [];
110
- }
111
-
112
- return {
113
- position: 'top',
114
- entries,
115
- bounds: { x: 0, y: 0, width: 0, height: 0 },
116
- labelStyle,
117
- swatchSize: SWATCH_SIZE,
118
- swatchGap: SWATCH_GAP,
119
- entryGap: ENTRY_GAP,
120
- swatchChipFill: theme.colors.annotationFill,
121
- };
122
- }
123
-
124
- // ---------------------------------------------------------------------------
125
- // Tooltip builder
126
- // ---------------------------------------------------------------------------
127
-
128
- /**
129
- * Build tooltip descriptors for each node.
130
- *
131
- * Keyed by node id. Shows all data fields, label, and community.
132
- */
133
- function buildGraphTooltips(nodes: CompiledGraphNode[]): Map<string, TooltipContent> {
134
- const descriptors = new Map<string, TooltipContent>();
135
-
136
- for (const node of nodes) {
137
- const fields: TooltipField[] = [];
138
-
139
- // Add community if present
140
- if (node.community != null) {
141
- fields.push({
142
- label: 'Community',
143
- value: node.community,
144
- color: node.fill,
145
- });
146
- }
147
-
148
- // Add all data fields (excluding id since it's the title)
149
- for (const [key, value] of Object.entries(node.data)) {
150
- if (key === 'id') continue;
151
- if (value == null) continue;
152
-
153
- fields.push({
154
- label: key,
155
- value: typeof value === 'number' ? graphNumberFormatter(value) : String(value),
156
- });
157
- }
158
-
159
- descriptors.set(node.id, {
160
- title: node.label ?? node.id,
161
- fields,
162
- });
163
- }
164
-
165
- return descriptors;
166
- }
167
-
168
- // ---------------------------------------------------------------------------
169
- // Public API
170
- // ---------------------------------------------------------------------------
171
-
172
- /**
173
- * Compile a graph spec into a GraphCompilation.
174
- *
175
- * Pipeline:
176
- * 1. Validate + normalize via the shared compiler pipeline
177
- * 2. Resolve theme (merge spec + options, apply dark mode)
178
- * 3. Resolve node visuals (size, color, label, stroke)
179
- * 4. Assign communities if layout.clustering is set
180
- * 5. Apply community colors (override nodeColor)
181
- * 6. Resolve edge visuals (width, color)
182
- * 7. Build legend from communities or nodeColor
183
- * 8. Build tooltip descriptors for each node
184
- * 9. Build a11y metadata
185
- * 10. Build simulation config from spec layout
186
- * 11. Build chrome from spec + theme
187
- * 12. Return GraphCompilation
188
- *
189
- * @param spec - Raw graph spec (validated at runtime).
190
- * @param options - Compile options (width, height, theme, darkMode).
191
- * @returns GraphCompilation with resolved visual properties.
192
- * @throws Error if spec is invalid or not a graph type.
193
- */
194
- export function compileGraph(spec: unknown, options: CompileOptions): GraphCompilation {
195
- // 1. Validate + normalize
196
- const { spec: normalized, warnings } = compileSpec(spec);
197
- emitSpecWarnings(warnings, options.onWarn);
198
-
199
- if (!('type' in normalized) || normalized.type !== 'graph') {
200
- throw new Error(
201
- 'compileGraph received a non-graph spec. Use compileChart or compileTable instead.',
202
- );
203
- }
204
-
205
- const graphSpec = normalized as NormalizedGraphSpec;
206
-
207
- // Resolve watermark: explicit spec value wins, then options fallback, then default true.
208
- const rawWatermark = (spec as Record<string, unknown>).watermark;
209
- const watermark = rawWatermark !== undefined ? graphSpec.watermark : (options.watermark ?? true);
210
-
211
- // 2. Resolve theme
212
- const mergedThemeConfig = options.theme
213
- ? { ...graphSpec.theme, ...options.theme }
214
- : graphSpec.theme;
215
- let theme: ResolvedTheme = resolveTheme(mergedThemeConfig);
216
- if (options.darkMode) {
217
- theme = adaptTheme(theme);
218
- }
219
-
220
- // 3. Resolve node visuals
221
- const compiledNodes = resolveNodeVisuals(
222
- graphSpec.nodes,
223
- graphSpec.encoding,
224
- graphSpec.edges,
225
- theme,
226
- graphSpec.nodeOverrides,
227
- );
228
-
229
- // 4. Assign communities (for force simulation grouping)
230
- const clusteringField = graphSpec.layout.clustering?.field;
231
- const hasCommunities = !!clusteringField;
232
- assignCommunities(compiledNodes, clusteringField);
233
-
234
- // 5. Apply community colors only when no explicit nodeColor encoding is set.
235
- // When the consumer specifies nodeColor (e.g. by nodeType or provider), that
236
- // encoding should drive both fill colors and legend entries.
237
- const hasNodeColorEncoding = !!graphSpec.encoding.nodeColor?.field;
238
- let communityColorMap = new Map<string, string>();
239
- if (hasCommunities && !hasNodeColorEncoding) {
240
- communityColorMap = buildCommunityColorMap(compiledNodes, theme);
241
- applyCommunityColors(compiledNodes, communityColorMap);
242
- }
243
-
244
- // 6. Resolve edge visuals
245
- const compiledEdges = resolveEdgeVisuals(graphSpec.edges, graphSpec.encoding, theme);
246
-
247
- // 7. Build legend (use nodeColor encoding colors when present, community otherwise)
248
- const useCommunitiesForLegend = hasCommunities && !hasNodeColorEncoding;
249
- const legend = buildGraphLegend(
250
- compiledNodes,
251
- communityColorMap,
252
- useCommunitiesForLegend,
253
- theme,
254
- graphSpec.encoding.nodeColor?.field,
255
- );
256
-
257
- // 8. Build tooltips
258
- const tooltipDescriptors = buildGraphTooltips(compiledNodes);
259
-
260
- // 9. Build a11y metadata
261
- const communityCount = communityColorMap.size;
262
- const altParts = [
263
- `Network graph with ${compiledNodes.length} nodes and ${compiledEdges.length} edges`,
264
- ];
265
- if (communityCount > 0) {
266
- altParts.push(`organized into ${communityCount} communities`);
267
- }
268
- const a11y = {
269
- altText: altParts.join(', '),
270
- dataTableFallback: compiledNodes.map((n) => [n.id, n.community ?? '', n.label ?? '']),
271
- role: 'img',
272
- keyboardNavigable: compiledNodes.length > 0,
273
- };
274
-
275
- // 10. Build simulation config
276
- const collisionPadding = graphSpec.layout.collisionPadding ?? 2;
277
- const maxRadius =
278
- compiledNodes.length > 0
279
- ? Math.max(...compiledNodes.map((n) => n.radius))
280
- : DEFAULT_COLLISION_PADDING;
281
- const simulationConfig: SimulationConfig = {
282
- chargeStrength: graphSpec.layout.chargeStrength ?? -300,
283
- linkDistance: graphSpec.layout.linkDistance ?? 30,
284
- clustering: clusteringField ? { field: clusteringField, strength: 0.5 } : null,
285
- alphaDecay: 0.0228,
286
- velocityDecay: 0.4,
287
- collisionRadius: maxRadius + collisionPadding,
288
- collisionPadding,
289
- linkStrength: graphSpec.layout.linkStrength,
290
- centerForce: graphSpec.layout.centerForce,
291
- };
292
-
293
- // 11. Build chrome
294
- const chrome = computeChrome(
295
- {
296
- title: graphSpec.chrome.title,
297
- subtitle: graphSpec.chrome.subtitle,
298
- source: graphSpec.chrome.source,
299
- byline: graphSpec.chrome.byline,
300
- footer: graphSpec.chrome.footer,
301
- },
302
- theme,
303
- options.width,
304
- options.measureText,
305
- 'full',
306
- undefined,
307
- watermark,
308
- );
309
-
310
- // 12. Return compilation
311
- return {
312
- nodes: compiledNodes,
313
- edges: compiledEdges,
314
- legend,
315
- chrome,
316
- tooltipDescriptors,
317
- a11y,
318
- theme,
319
- dimensions: {
320
- width: options.width,
321
- height: options.height,
322
- },
323
- simulationConfig,
324
- watermark,
325
- };
326
- }
327
-
328
- /** Default padding for collision radius when there are no nodes. */
329
- const DEFAULT_COLLISION_PADDING = 5;
@@ -1,356 +0,0 @@
1
- /**
2
- * Graph encoding resolution.
3
- *
4
- * Maps graph encoding channels (nodeSize, nodeColor, edgeWidth, edgeColor,
5
- * nodeLabel) to computed visual properties on nodes and edges. Uses d3 scales
6
- * the same way scatter/bubble charts do: scaleSqrt for size, scaleOrdinal
7
- * for categorical color, scaleLinear for quantitative color.
8
- */
9
-
10
- import type {
11
- GraphEdge,
12
- GraphEncoding,
13
- GraphNode,
14
- NodeOverride,
15
- ResolvedTheme,
16
- } from '@opendata-ai/openchart-core';
17
- import { max, min } from 'd3-array';
18
- import { scaleLinear, scaleOrdinal, scaleSqrt } from 'd3-scale';
19
-
20
- import type { CompiledGraphEdge, CompiledGraphNode } from './types';
21
-
22
- // ---------------------------------------------------------------------------
23
- // Constants
24
- // ---------------------------------------------------------------------------
25
-
26
- const DEFAULT_NODE_RADIUS = 5;
27
- const MIN_NODE_RADIUS = 3;
28
- const MAX_NODE_RADIUS = 12;
29
-
30
- const DEFAULT_EDGE_WIDTH = 1;
31
- const MIN_EDGE_WIDTH = 0.5;
32
- const MAX_EDGE_WIDTH = 4;
33
-
34
- const DEFAULT_STROKE_WIDTH = 1;
35
-
36
- // ---------------------------------------------------------------------------
37
- // Helpers
38
- // ---------------------------------------------------------------------------
39
-
40
- /**
41
- * Darken a hex color by a percentage.
42
- *
43
- * Doesn't use d3-color (engine doesn't depend on it). Operates directly
44
- * on hex RGB channels. Falls back to the original color on parse failure.
45
- */
46
- export function darkenColor(hex: string, amount: number = 0.2): string {
47
- // Strip # prefix
48
- const clean = hex.replace(/^#/, '');
49
- if (clean.length !== 6 && clean.length !== 3) return hex;
50
-
51
- // Expand shorthand
52
- const full =
53
- clean.length === 3
54
- ? clean
55
- .split('')
56
- .map((c) => c + c)
57
- .join('')
58
- : clean;
59
-
60
- const r = Math.max(0, Math.round(parseInt(full.substring(0, 2), 16) * (1 - amount)));
61
- const g = Math.max(0, Math.round(parseInt(full.substring(2, 4), 16) * (1 - amount)));
62
- const b = Math.max(0, Math.round(parseInt(full.substring(4, 6), 16) * (1 - amount)));
63
-
64
- return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${b.toString(16).padStart(2, '0')}`;
65
- }
66
-
67
- /**
68
- * Apply opacity to a hex color, returning an rgba string.
69
- */
70
- function hexWithOpacity(hex: string, opacity: number): string {
71
- const clean = hex.replace(/^#/, '');
72
- if (clean.length !== 6 && clean.length !== 3) {
73
- // Non-hex input: return as-is with opacity via CSS
74
- return hex;
75
- }
76
-
77
- const full =
78
- clean.length === 3
79
- ? clean
80
- .split('')
81
- .map((c) => c + c)
82
- .join('')
83
- : clean;
84
-
85
- const r = parseInt(full.substring(0, 2), 16);
86
- const g = parseInt(full.substring(2, 4), 16);
87
- const b = parseInt(full.substring(4, 6), 16);
88
-
89
- return `rgba(${r}, ${g}, ${b}, ${opacity})`;
90
- }
91
-
92
- /**
93
- * Compute the degree of each node (number of edges touching it).
94
- */
95
- function computeDegrees(nodes: GraphNode[], edges: GraphEdge[]): Map<string, number> {
96
- const degrees = new Map<string, number>();
97
- for (const node of nodes) {
98
- degrees.set(node.id, 0);
99
- }
100
- for (const edge of edges) {
101
- degrees.set(edge.source, (degrees.get(edge.source) ?? 0) + 1);
102
- degrees.set(edge.target, (degrees.get(edge.target) ?? 0) + 1);
103
- }
104
- return degrees;
105
- }
106
-
107
- // ---------------------------------------------------------------------------
108
- // Node visual resolution
109
- // ---------------------------------------------------------------------------
110
-
111
- /**
112
- * Resolve visual properties for all graph nodes.
113
- *
114
- * Applies nodeSize, nodeColor, and nodeLabel encoding channels from the
115
- * spec to produce CompiledGraphNode objects with computed fill, radius,
116
- * stroke, label, and label priority.
117
- */
118
- export function resolveNodeVisuals(
119
- nodes: GraphNode[],
120
- encoding: GraphEncoding,
121
- edges: GraphEdge[],
122
- theme: ResolvedTheme,
123
- nodeOverrides?: Record<string, NodeOverride>,
124
- ): CompiledGraphNode[] {
125
- const degrees = computeDegrees(nodes, edges);
126
- const maxDegree = Math.max(1, ...degrees.values());
127
-
128
- // Build node size scale
129
- let sizeScale: ((v: number) => number) | undefined;
130
- if (encoding.nodeSize?.field) {
131
- const field = encoding.nodeSize.field;
132
- const values = nodes.map((n) => Number(n[field])).filter((v) => Number.isFinite(v));
133
-
134
- const sizeMin = min(values) ?? 0;
135
- const sizeMax = max(values) ?? 1;
136
-
137
- sizeScale = scaleSqrt().domain([sizeMin, sizeMax]).range([MIN_NODE_RADIUS, MAX_NODE_RADIUS]);
138
- }
139
-
140
- // Build node color scale
141
- let colorFn: ((node: GraphNode) => string) | undefined;
142
- if (encoding.nodeColor?.field) {
143
- const field = encoding.nodeColor.field;
144
- const fieldType = encoding.nodeColor.type ?? 'nominal';
145
- const scaleConfig = encoding.nodeColor.scale;
146
-
147
- if (fieldType === 'quantitative') {
148
- const values = nodes.map((n) => Number(n[field])).filter((v) => Number.isFinite(v));
149
- const colorMin = min(values) ?? 0;
150
- const colorMax = max(values) ?? 1;
151
-
152
- // Use first sequential palette
153
- const seqPalettes = Object.values(theme.colors.sequential);
154
- const palette = seqPalettes.length > 0 ? seqPalettes[0] : ['#ccc', '#333'];
155
-
156
- const domain =
157
- scaleConfig?.domain && scaleConfig.domain.length === 2
158
- ? (scaleConfig.domain as [number, number])
159
- : [colorMin, colorMax];
160
- const range =
161
- scaleConfig?.range && scaleConfig.range.length >= 2
162
- ? (scaleConfig.range as string[])
163
- : [palette[0], palette[palette.length - 1]];
164
-
165
- const colorScale = scaleLinear<string>().domain(domain).range(range);
166
-
167
- colorFn = (node: GraphNode) => {
168
- const val = Number(node[field]);
169
- return Number.isFinite(val) ? colorScale(val) : theme.colors.categorical[0];
170
- };
171
- } else {
172
- // nominal/ordinal
173
- const domain =
174
- scaleConfig?.domain && Array.isArray(scaleConfig.domain)
175
- ? (scaleConfig.domain as string[])
176
- : [...new Set(nodes.map((n) => String(n[field] ?? '')))];
177
- const range =
178
- scaleConfig?.range && scaleConfig.range.length > 0
179
- ? (scaleConfig.range as string[])
180
- : theme.colors.categorical;
181
-
182
- const ordinalScale = scaleOrdinal<string>().domain(domain).range(range);
183
-
184
- colorFn = (node: GraphNode) => ordinalScale(String(node[field] ?? ''));
185
- }
186
- }
187
-
188
- const defaultColor = theme.colors.categorical[0];
189
-
190
- return nodes.map((node) => {
191
- // Radius
192
- let radius = DEFAULT_NODE_RADIUS;
193
- if (sizeScale && encoding.nodeSize?.field) {
194
- const val = Number(node[encoding.nodeSize.field]);
195
- if (Number.isFinite(val)) {
196
- radius = sizeScale(val);
197
- }
198
- }
199
-
200
- // Color
201
- const fill = colorFn ? colorFn(node) : defaultColor;
202
-
203
- // Stroke: darken fill by 20%
204
- const stroke = darkenColor(fill);
205
-
206
- // Label
207
- let label: string | undefined;
208
- if (encoding.nodeLabel?.field) {
209
- const labelVal = node[encoding.nodeLabel.field];
210
- label = labelVal != null ? String(labelVal) : undefined;
211
- } else {
212
- label = node.id;
213
- }
214
-
215
- // Label priority: degree / maxDegree (0 to 1)
216
- const degree = degrees.get(node.id) ?? 0;
217
- const labelPriority = maxDegree > 0 ? degree / maxDegree : 0;
218
-
219
- // Data: spread all original node fields
220
- const { id: _id, ...rest } = node;
221
- const data: Record<string, unknown> = { id: node.id, ...rest };
222
-
223
- // Apply per-node overrides if present
224
- const override = nodeOverrides?.[node.id];
225
- const finalFill = override?.fill ?? fill;
226
- const finalRadius = override?.radius ?? radius;
227
- const finalStrokeWidth = override?.strokeWidth ?? DEFAULT_STROKE_WIDTH;
228
- const finalStroke = override?.stroke ?? stroke;
229
- const finalLabelPriority = override?.alwaysShowLabel ? Infinity : labelPriority;
230
-
231
- return {
232
- id: node.id,
233
- radius: finalRadius,
234
- fill: finalFill,
235
- stroke: finalStroke,
236
- strokeWidth: finalStrokeWidth,
237
- label,
238
- labelPriority: finalLabelPriority,
239
- community: undefined,
240
- data,
241
- };
242
- });
243
- }
244
-
245
- // ---------------------------------------------------------------------------
246
- // Edge visual resolution
247
- // ---------------------------------------------------------------------------
248
-
249
- /**
250
- * Resolve visual properties for all graph edges.
251
- *
252
- * Applies edgeWidth and edgeColor encoding channels to produce
253
- * CompiledGraphEdge objects with computed stroke, strokeWidth, and style.
254
- */
255
- export function resolveEdgeVisuals(
256
- edges: GraphEdge[],
257
- encoding: GraphEncoding,
258
- theme: ResolvedTheme,
259
- ): CompiledGraphEdge[] {
260
- // Edge width scale
261
- let widthScale: ((v: number) => number) | undefined;
262
- if (encoding.edgeWidth?.field) {
263
- const field = encoding.edgeWidth.field;
264
- const values = edges.map((e) => Number(e[field])).filter((v) => Number.isFinite(v));
265
-
266
- const widthMin = min(values) ?? 0;
267
- const widthMax = max(values) ?? 1;
268
-
269
- widthScale = scaleLinear().domain([widthMin, widthMax]).range([MIN_EDGE_WIDTH, MAX_EDGE_WIDTH]);
270
- }
271
-
272
- // Edge color scale
273
- let edgeColorFn: ((edge: GraphEdge) => string) | undefined;
274
- if (encoding.edgeColor?.field) {
275
- const field = encoding.edgeColor.field;
276
- const fieldType = encoding.edgeColor.type ?? 'nominal';
277
- const scaleConfig = encoding.edgeColor.scale;
278
-
279
- if (fieldType === 'quantitative') {
280
- const values = edges.map((e) => Number(e[field])).filter((v) => Number.isFinite(v));
281
- const colorMin = min(values) ?? 0;
282
- const colorMax = max(values) ?? 1;
283
-
284
- const seqPalettes = Object.values(theme.colors.sequential);
285
- const palette = seqPalettes.length > 0 ? seqPalettes[0] : ['#ccc', '#333'];
286
-
287
- const domain =
288
- scaleConfig?.domain && scaleConfig.domain.length === 2
289
- ? (scaleConfig.domain as [number, number])
290
- : [colorMin, colorMax];
291
- const range =
292
- scaleConfig?.range && scaleConfig.range.length >= 2
293
- ? (scaleConfig.range as string[])
294
- : [palette[0], palette[palette.length - 1]];
295
-
296
- const colorScale = scaleLinear<string>().domain(domain).range(range);
297
-
298
- edgeColorFn = (edge: GraphEdge) => {
299
- const val = Number(edge[field]);
300
- return Number.isFinite(val) ? colorScale(val) : hexWithOpacity(theme.colors.axis, 0.4);
301
- };
302
- } else {
303
- const domain =
304
- scaleConfig?.domain && Array.isArray(scaleConfig.domain)
305
- ? (scaleConfig.domain as string[])
306
- : [...new Set(edges.map((e) => String(e[field] ?? '')))];
307
- const range =
308
- scaleConfig?.range && scaleConfig.range.length > 0
309
- ? (scaleConfig.range as string[])
310
- : theme.colors.categorical;
311
-
312
- const ordinalScale = scaleOrdinal<string>().domain(domain).range(range);
313
-
314
- edgeColorFn = (edge: GraphEdge) => ordinalScale(String(edge[field] ?? ''));
315
- }
316
- }
317
-
318
- const defaultEdgeColor = hexWithOpacity(theme.colors.axis, 0.4);
319
-
320
- // Edge style mapping (ordinal: map unique field values to solid/dashed/dotted)
321
- const EDGE_STYLES: Array<'solid' | 'dashed' | 'dotted'> = ['solid', 'dashed', 'dotted'];
322
- let styleFn: ((edge: GraphEdge) => 'solid' | 'dashed' | 'dotted') | undefined;
323
- if (encoding.edgeStyle?.field) {
324
- const field = encoding.edgeStyle.field;
325
- const uniqueValues = [...new Set(edges.map((e) => String(e[field] ?? '')))];
326
- const styleMap = new Map<string, 'solid' | 'dashed' | 'dotted'>();
327
- for (let i = 0; i < uniqueValues.length; i++) {
328
- styleMap.set(uniqueValues[i], EDGE_STYLES[i % EDGE_STYLES.length]);
329
- }
330
- styleFn = (edge: GraphEdge) => styleMap.get(String(edge[field] ?? '')) ?? 'solid';
331
- }
332
-
333
- return edges.map((edge) => {
334
- const { source, target, ...rest } = edge;
335
-
336
- let strokeWidth = DEFAULT_EDGE_WIDTH;
337
- if (widthScale && encoding.edgeWidth?.field) {
338
- const val = Number(edge[encoding.edgeWidth.field]);
339
- if (Number.isFinite(val)) {
340
- strokeWidth = widthScale(val);
341
- }
342
- }
343
-
344
- const stroke = edgeColorFn ? edgeColorFn(edge) : defaultEdgeColor;
345
- const style = styleFn ? styleFn(edge) : ('solid' as const);
346
-
347
- return {
348
- source,
349
- target,
350
- stroke,
351
- strokeWidth,
352
- style,
353
- data: { source, target, ...rest } as Record<string, unknown>,
354
- };
355
- });
356
- }