@opendata-ai/openchart-engine 8.0.0-rc.10 → 8.0.0-rc.11

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 (270) hide show
  1. package/dist/index.js +2 -3
  2. package/dist/index.js.map +1 -1
  3. package/package.json +3 -4
  4. package/src/__test-fixtures__/specs.ts +0 -182
  5. package/src/__tests__/__snapshots__/compile-snapshot.test.ts.snap +0 -2401
  6. package/src/__tests__/annotation-behavior.test.ts +0 -852
  7. package/src/__tests__/axes.test.ts +0 -1579
  8. package/src/__tests__/compile-animation.test.ts +0 -161
  9. package/src/__tests__/compile-chart.test.ts +0 -1303
  10. package/src/__tests__/compile-footnotes.test.ts +0 -277
  11. package/src/__tests__/compile-layer.test.ts +0 -969
  12. package/src/__tests__/compile-snapshot.test.ts +0 -156
  13. package/src/__tests__/compound-labels.test.ts +0 -147
  14. package/src/__tests__/dimensions.test.ts +0 -918
  15. package/src/__tests__/encoding-sugar.test.ts +0 -390
  16. package/src/__tests__/facet.test.ts +0 -359
  17. package/src/__tests__/helpers/invariants.ts +0 -299
  18. package/src/__tests__/known-bugs.test.ts +0 -566
  19. package/src/__tests__/layout-fuzz.test.ts +0 -358
  20. package/src/__tests__/layout-invariants.test.ts +0 -535
  21. package/src/__tests__/legend.test.ts +0 -721
  22. package/src/__tests__/mark-keys.test.ts +0 -294
  23. package/src/__tests__/ranking-recipes.test.ts +0 -260
  24. package/src/__tests__/rotation.test.ts +0 -83
  25. package/src/__tests__/scales.test.ts +0 -323
  26. package/src/__tests__/series-search.test.ts +0 -92
  27. package/src/__tests__/spec-sugar.test.ts +0 -801
  28. package/src/__tests__/you-draw-it.test.ts +0 -160
  29. package/src/annotations/__tests__/compute.test.ts +0 -1672
  30. package/src/annotations/__tests__/geometry.test.ts +0 -66
  31. package/src/annotations/__tests__/placement-fuzz.test.ts +0 -256
  32. package/src/annotations/__tests__/placement-invariants.test.ts +0 -345
  33. package/src/annotations/__tests__/placement.test.ts +0 -316
  34. package/src/annotations/__tests__/resolve-text.test.ts +0 -788
  35. package/src/annotations/__tests__/rich-text.test.ts +0 -91
  36. package/src/annotations/__tests__/thinning.test.ts +0 -285
  37. package/src/annotations/collisions.ts +0 -326
  38. package/src/annotations/compute.ts +0 -333
  39. package/src/annotations/constants.ts +0 -162
  40. package/src/annotations/geometry.ts +0 -376
  41. package/src/annotations/move.ts +0 -135
  42. package/src/annotations/placement.ts +0 -636
  43. package/src/annotations/position.ts +0 -131
  44. package/src/annotations/resolve-range.ts +0 -117
  45. package/src/annotations/resolve-refline.ts +0 -157
  46. package/src/annotations/resolve-text.ts +0 -545
  47. package/src/annotations/rich-text.ts +0 -65
  48. package/src/annotations/thinning.ts +0 -190
  49. package/src/barlist/__tests__/compile-barlist.test.ts +0 -200
  50. package/src/barlist/compile-barlist.ts +0 -391
  51. package/src/barlist/types.ts +0 -28
  52. package/src/charts/__tests__/post-process.test.ts +0 -237
  53. package/src/charts/__tests__/registry.test.ts +0 -116
  54. package/src/charts/__tests__/utils.test.ts +0 -195
  55. package/src/charts/_shared/__tests__/density-filter.test.ts +0 -32
  56. package/src/charts/_shared/density-filter.ts +0 -26
  57. package/src/charts/_shared/format-label-value.ts +0 -16
  58. package/src/charts/bar/__tests__/compute.test.ts +0 -934
  59. package/src/charts/bar/__tests__/gradient-orient.test.ts +0 -127
  60. package/src/charts/bar/__tests__/labels.test.ts +0 -292
  61. package/src/charts/bar/compute.ts +0 -539
  62. package/src/charts/bar/index.ts +0 -60
  63. package/src/charts/bar/labels.ts +0 -311
  64. package/src/charts/beeswarm/__tests__/compute.test.ts +0 -280
  65. package/src/charts/beeswarm/__tests__/dodge.test.ts +0 -148
  66. package/src/charts/beeswarm/compute.ts +0 -203
  67. package/src/charts/beeswarm/dodge.ts +0 -155
  68. package/src/charts/beeswarm/index.ts +0 -32
  69. package/src/charts/builtin.ts +0 -75
  70. package/src/charts/calendar/__tests__/compute.test.ts +0 -417
  71. package/src/charts/calendar/compute.ts +0 -319
  72. package/src/charts/calendar/index.ts +0 -32
  73. package/src/charts/column/__tests__/compute.test.ts +0 -540
  74. package/src/charts/column/__tests__/labels.test.ts +0 -179
  75. package/src/charts/column/compute.ts +0 -493
  76. package/src/charts/column/index.ts +0 -53
  77. package/src/charts/column/labels.ts +0 -229
  78. package/src/charts/dot/__tests__/compute.test.ts +0 -380
  79. package/src/charts/dot/__tests__/labels.test.ts +0 -98
  80. package/src/charts/dot/compute.ts +0 -285
  81. package/src/charts/dot/index.ts +0 -62
  82. package/src/charts/dot/labels.ts +0 -121
  83. package/src/charts/line/__tests__/compute.test.ts +0 -1194
  84. package/src/charts/line/__tests__/curves.test.ts +0 -51
  85. package/src/charts/line/__tests__/labels.test.ts +0 -94
  86. package/src/charts/line/__tests__/mark-options.test.ts +0 -175
  87. package/src/charts/line/area.ts +0 -484
  88. package/src/charts/line/compute.ts +0 -356
  89. package/src/charts/line/curves.ts +0 -85
  90. package/src/charts/line/index.ts +0 -176
  91. package/src/charts/line/labels.ts +0 -177
  92. package/src/charts/parliament/__tests__/compute.test.ts +0 -411
  93. package/src/charts/parliament/compute.ts +0 -313
  94. package/src/charts/parliament/index.ts +0 -32
  95. package/src/charts/pie/__tests__/compute.test.ts +0 -384
  96. package/src/charts/pie/__tests__/labels.test.ts +0 -132
  97. package/src/charts/pie/compute.ts +0 -324
  98. package/src/charts/pie/index.ts +0 -49
  99. package/src/charts/pie/labels.ts +0 -143
  100. package/src/charts/post-process.ts +0 -229
  101. package/src/charts/range/__tests__/compute.test.ts +0 -486
  102. package/src/charts/range/compute.ts +0 -273
  103. package/src/charts/range/index.ts +0 -82
  104. package/src/charts/range/labels.ts +0 -169
  105. package/src/charts/rect/__tests__/compute.test.ts +0 -120
  106. package/src/charts/rect/index.ts +0 -127
  107. package/src/charts/registry.ts +0 -72
  108. package/src/charts/rule/index.ts +0 -139
  109. package/src/charts/scatter/__tests__/compute.test.ts +0 -488
  110. package/src/charts/scatter/__tests__/trendline.test.ts +0 -191
  111. package/src/charts/scatter/compute.ts +0 -192
  112. package/src/charts/scatter/index.ts +0 -46
  113. package/src/charts/scatter/trendline.ts +0 -100
  114. package/src/charts/text/__tests__/compute.test.ts +0 -307
  115. package/src/charts/text/index.ts +0 -141
  116. package/src/charts/tick/__tests__/compute.test.ts +0 -75
  117. package/src/charts/tick/index.ts +0 -99
  118. package/src/charts/utils.ts +0 -170
  119. package/src/charts/waffle/__tests__/compute.test.ts +0 -305
  120. package/src/charts/waffle/compute.ts +0 -197
  121. package/src/charts/waffle/index.ts +0 -31
  122. package/src/compile/__tests__/color-scale-range.test.ts +0 -158
  123. package/src/compile/__tests__/color-scale-reverse.test.ts +0 -89
  124. package/src/compile/__tests__/data-clip.test.ts +0 -127
  125. package/src/compile/__tests__/fill-patterns.test.ts +0 -154
  126. package/src/compile/__tests__/size-scale.test.ts +0 -108
  127. package/src/compile/__tests__/watermark-obstacle.test.ts +0 -93
  128. package/src/compile/color-scale-range.ts +0 -101
  129. package/src/compile/data-clip.ts +0 -48
  130. package/src/compile/fill-patterns.ts +0 -74
  131. package/src/compile/layer.ts +0 -630
  132. package/src/compile/size-scale.ts +0 -141
  133. package/src/compile/spec-sugar.ts +0 -767
  134. package/src/compile/watermark-obstacle.ts +0 -54
  135. package/src/compile/you-draw-it.ts +0 -123
  136. package/src/compile.ts +0 -1548
  137. package/src/compiler/__tests__/a11y-warnings.test.ts +0 -148
  138. package/src/compiler/__tests__/animation.test.ts +0 -177
  139. package/src/compiler/__tests__/compile.test.ts +0 -87
  140. package/src/compiler/__tests__/fixtures/vl-parity/axis-null.json +0 -19
  141. package/src/compiler/__tests__/fixtures/vl-parity/color-value.json +0 -20
  142. package/src/compiler/__tests__/fixtures/vl-parity/count-aggregate.json +0 -22
  143. package/src/compiler/__tests__/fixtures/vl-parity/data-values.json +0 -19
  144. package/src/compiler/__tests__/fixtures/vl-parity/layer-axis-null.json +0 -14
  145. package/src/compiler/__tests__/fixtures/vl-parity/layer-count.json +0 -34
  146. package/src/compiler/__tests__/fixtures/vl-parity/layer-data-values.json +0 -22
  147. package/src/compiler/__tests__/fixtures/vl-parity/layer-legend-null.json +0 -41
  148. package/src/compiler/__tests__/fixtures/vl-parity/layer-scheme.json +0 -38
  149. package/src/compiler/__tests__/fixtures/vl-parity/layer-sort.json +0 -28
  150. package/src/compiler/__tests__/fixtures/vl-parity/layer-theta.json +0 -28
  151. package/src/compiler/__tests__/fixtures/vl-parity/layer-title.json +0 -30
  152. package/src/compiler/__tests__/fixtures/vl-parity/layer-value-def.json +0 -29
  153. package/src/compiler/__tests__/fixtures/vl-parity/legend-null.json +0 -32
  154. package/src/compiler/__tests__/fixtures/vl-parity/scheme.json +0 -25
  155. package/src/compiler/__tests__/fixtures/vl-parity/sort-by-value.json +0 -19
  156. package/src/compiler/__tests__/fixtures/vl-parity/theta-arc.json +0 -19
  157. package/src/compiler/__tests__/fixtures/vl-parity/title-subtitle.json +0 -21
  158. package/src/compiler/__tests__/fixtures/vl-parity/width-height.json +0 -23
  159. package/src/compiler/__tests__/keys.test.ts +0 -83
  160. package/src/compiler/__tests__/normalize-highlight.test.ts +0 -103
  161. package/src/compiler/__tests__/normalize.test.ts +0 -399
  162. package/src/compiler/__tests__/sparkline-defaults.test.ts +0 -153
  163. package/src/compiler/__tests__/validate-did-you-mean.test.ts +0 -170
  164. package/src/compiler/__tests__/validate-highlight.test.ts +0 -112
  165. package/src/compiler/__tests__/validate-near-miss.test.ts +0 -251
  166. package/src/compiler/__tests__/validate.test.ts +0 -731
  167. package/src/compiler/__tests__/vl-parity.test.ts +0 -68
  168. package/src/compiler/a11y-warnings.ts +0 -110
  169. package/src/compiler/animation.ts +0 -142
  170. package/src/compiler/index.ts +0 -47
  171. package/src/compiler/keys.ts +0 -55
  172. package/src/compiler/normalize.ts +0 -734
  173. package/src/compiler/sparkline-defaults.ts +0 -138
  174. package/src/compiler/types.ts +0 -241
  175. package/src/compiler/validate.ts +0 -2093
  176. package/src/endpoint-labels/__tests__/compute.test.ts +0 -587
  177. package/src/endpoint-labels/compute.ts +0 -621
  178. package/src/endpoint-labels/constants.ts +0 -54
  179. package/src/endpoint-labels/format.ts +0 -60
  180. package/src/endpoint-labels/predict.ts +0 -139
  181. package/src/format/__tests__/field-format.test.ts +0 -164
  182. package/src/format/field-format.ts +0 -27
  183. package/src/geo/__tests__/compile-map.test.ts +0 -1128
  184. package/src/geo/compile-map.ts +0 -1376
  185. package/src/geo/join.ts +0 -115
  186. package/src/geo/projections.ts +0 -65
  187. package/src/geo/types.ts +0 -26
  188. package/src/graphs/__tests__/community.test.ts +0 -228
  189. package/src/graphs/__tests__/compile-graph.test.ts +0 -396
  190. package/src/graphs/__tests__/encoding.test.ts +0 -415
  191. package/src/graphs/community.ts +0 -92
  192. package/src/graphs/compile-graph.ts +0 -329
  193. package/src/graphs/encoding.ts +0 -356
  194. package/src/graphs/types.ts +0 -106
  195. package/src/index.ts +0 -177
  196. package/src/layout/__tests__/metrics.test.ts +0 -97
  197. package/src/layout/__tests__/scales-highlight.test.ts +0 -192
  198. package/src/layout/axes/rotation.ts +0 -152
  199. package/src/layout/axes/thinning.ts +0 -98
  200. package/src/layout/axes/ticks.ts +0 -409
  201. package/src/layout/axes.ts +0 -757
  202. package/src/layout/dimensions.ts +0 -912
  203. package/src/layout/facet.ts +0 -91
  204. package/src/layout/gridlines.ts +0 -84
  205. package/src/layout/metrics.ts +0 -132
  206. package/src/layout/plan.ts +0 -631
  207. package/src/layout/scales.ts +0 -1053
  208. package/src/layout/shared.ts +0 -44
  209. package/src/legend/__tests__/continuous.test.ts +0 -318
  210. package/src/legend/__tests__/redundancy.test.ts +0 -108
  211. package/src/legend/__tests__/size.test.ts +0 -348
  212. package/src/legend/__tests__/suppression.test.ts +0 -382
  213. package/src/legend/compute.ts +0 -748
  214. package/src/legend/continuous.ts +0 -327
  215. package/src/legend/size.ts +0 -407
  216. package/src/legend/suppression.ts +0 -226
  217. package/src/legend/wrap.ts +0 -117
  218. package/src/sankey/__tests__/compile-sankey.test.ts +0 -458
  219. package/src/sankey/__tests__/layout.test.ts +0 -165
  220. package/src/sankey/__tests__/node-label-wrap.test.ts +0 -114
  221. package/src/sankey/__tests__/node-sort.test.ts +0 -45
  222. package/src/sankey/compile-sankey.ts +0 -706
  223. package/src/sankey/layout.ts +0 -184
  224. package/src/sankey/types.ts +0 -41
  225. package/src/tables/__tests__/bar-column.test.ts +0 -147
  226. package/src/tables/__tests__/category-colors.test.ts +0 -230
  227. package/src/tables/__tests__/compile-table.test.ts +0 -236
  228. package/src/tables/__tests__/format-cells.test.ts +0 -143
  229. package/src/tables/__tests__/heatmap.test.ts +0 -148
  230. package/src/tables/__tests__/pagination.test.ts +0 -78
  231. package/src/tables/__tests__/search.test.ts +0 -94
  232. package/src/tables/__tests__/sort.test.ts +0 -107
  233. package/src/tables/__tests__/sparkline.test.ts +0 -122
  234. package/src/tables/bar-column.ts +0 -94
  235. package/src/tables/category-colors.ts +0 -78
  236. package/src/tables/compile-table.ts +0 -427
  237. package/src/tables/format-cells.ts +0 -115
  238. package/src/tables/heatmap.ts +0 -141
  239. package/src/tables/pagination.ts +0 -46
  240. package/src/tables/search.ts +0 -66
  241. package/src/tables/sort.ts +0 -69
  242. package/src/tables/sparkline.ts +0 -113
  243. package/src/tables/utils.ts +0 -16
  244. package/src/tilemap/__tests__/compile-tilemap.test.ts +0 -576
  245. package/src/tilemap/compile-tilemap.ts +0 -755
  246. package/src/tilemap/layout.ts +0 -172
  247. package/src/tilemap/types.ts +0 -33
  248. package/src/tooltips/__tests__/compute.test.ts +0 -582
  249. package/src/tooltips/compute.ts +0 -700
  250. package/src/transforms/__tests__/aggregate.test.ts +0 -159
  251. package/src/transforms/__tests__/bin.test.ts +0 -88
  252. package/src/transforms/__tests__/calculate.test.ts +0 -146
  253. package/src/transforms/__tests__/conditional.test.ts +0 -127
  254. package/src/transforms/__tests__/filter-relative.test.ts +0 -202
  255. package/src/transforms/__tests__/filter.test.ts +0 -59
  256. package/src/transforms/__tests__/fold.test.ts +0 -79
  257. package/src/transforms/__tests__/index.test.ts +0 -93
  258. package/src/transforms/__tests__/predicates.test.ts +0 -193
  259. package/src/transforms/__tests__/timeunit.test.ts +0 -129
  260. package/src/transforms/__tests__/window.test.ts +0 -286
  261. package/src/transforms/aggregate.ts +0 -131
  262. package/src/transforms/bin.ts +0 -87
  263. package/src/transforms/calculate.ts +0 -60
  264. package/src/transforms/conditional.ts +0 -46
  265. package/src/transforms/filter.ts +0 -122
  266. package/src/transforms/fold.ts +0 -49
  267. package/src/transforms/index.ts +0 -60
  268. package/src/transforms/predicates.ts +0 -123
  269. package/src/transforms/timeunit.ts +0 -88
  270. 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
- }