semiotic 3.13.1 → 3.13.3

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 (276) hide show
  1. package/README.md +48 -48
  2. package/ai/artifact-surface-inventory.json +1 -1
  3. package/ai/dist/mcp-server.js +4 -4
  4. package/ai/reference.md +23 -12
  5. package/ai/schema.json +258 -96
  6. package/ai/surface-manifest.json +1 -1
  7. package/ai/task-packets/compare-category-totals.json +5 -5
  8. package/ai/task-packets/compare-category-totals.md +2 -2
  9. package/ai/task-packets/correct-published-chart.json +5 -5
  10. package/ai/task-packets/correct-published-chart.md +2 -2
  11. package/ai/task-packets/index.json +6 -6
  12. package/ai/task-packets/update-live-chart.json +5 -5
  13. package/ai/task-packets/update-live-chart.md +2 -2
  14. package/dist/c-2YFVDRU4.min.js +1 -0
  15. package/dist/c-4OVDIXAR.min.js +1 -0
  16. package/dist/c-57IIWW46.min.js +1 -0
  17. package/dist/c-5HTUQRJT.min.js +1 -0
  18. package/dist/c-5NAU4JAY.min.js +1 -0
  19. package/dist/c-62UTMRQE.min.js +1 -0
  20. package/dist/c-6QV6F3U7.min.js +1 -0
  21. package/dist/c-73ORHEHO.min.js +1 -0
  22. package/dist/c-7S46KBYD.min.js +2 -0
  23. package/dist/c-AJSS332Z.min.js +2 -0
  24. package/dist/{c-ZWJDTDEV.min.js → c-AMQAAW7G.min.js} +1 -1
  25. package/dist/c-B3X2IJRQ.min.js +1 -0
  26. package/dist/c-BLLDBVFK.min.js +38 -0
  27. package/dist/c-BQWX6NBX.min.js +1 -0
  28. package/dist/c-C7TT4J7K.min.js +1 -0
  29. package/dist/c-CJ5GA7DM.min.js +1 -0
  30. package/dist/c-D7YDFHLY.min.js +1 -0
  31. package/dist/c-DHNROAXY.min.js +1 -0
  32. package/dist/c-DMDFJQU4.min.js +1 -0
  33. package/dist/{c-RAIBDXDV.min.js → c-FRVHZIGR.min.js} +1 -1
  34. package/dist/{c-I54V24WG.min.js → c-HAZCVHI7.min.js} +1 -1
  35. package/dist/c-HN5U72U7.min.js +1 -0
  36. package/dist/c-JA5F7ITS.min.js +1 -0
  37. package/dist/{c-VZNIIKL6.min.js → c-JDI7HKEM.min.js} +1 -1
  38. package/dist/{c-ISHYKYII.min.js → c-JVZRD4GL.min.js} +1 -1
  39. package/dist/{c-HGWITEJI.min.js → c-KJGJEOSV.min.js} +1 -1
  40. package/dist/c-LDGV6TDQ.min.js +1 -0
  41. package/dist/c-LW3GP7RY.min.js +1 -0
  42. package/dist/c-M2TPZE7P.min.js +1 -0
  43. package/dist/{c-XOGN3524.min.js → c-NBBYSAQY.min.js} +2 -2
  44. package/dist/c-OA6RJZ7S.min.js +1 -0
  45. package/dist/c-OBBSIOYU.min.js +1 -0
  46. package/dist/c-OMTJIC3P.min.js +1 -0
  47. package/dist/{c-SQQZPFVY.min.js → c-QPHM7AWW.min.js} +1 -1
  48. package/dist/{c-XZJWL7UL.min.js → c-QSEAAHEU.min.js} +1 -1
  49. package/dist/c-RQWI623R.min.js +1 -0
  50. package/dist/{c-62JIVHK5.min.js → c-RWFADOKS.min.js} +1 -1
  51. package/dist/c-TFESQSWE.min.js +1 -0
  52. package/dist/{c-SDGGMIYI.min.js → c-TJGC5JEM.min.js} +1 -1
  53. package/dist/{c-4P2EM44G.min.js → c-TOXWQRXS.min.js} +3 -3
  54. package/dist/c-TX53234M.min.js +1 -0
  55. package/dist/c-TZBEQ5UY.min.js +1 -0
  56. package/dist/c-UALVQIIJ.min.js +1 -0
  57. package/dist/c-VBDWHTC7.min.js +1 -0
  58. package/dist/c-VBIPDCE7.min.js +1 -0
  59. package/dist/c-WTNRBWZZ.min.js +51 -0
  60. package/dist/{c-3GIPT46Z.min.js → c-XG4LL2VI.min.js} +1 -1
  61. package/dist/c-XPNBS3W2.min.js +1 -0
  62. package/dist/c-XT3G3YWU.min.js +1 -0
  63. package/dist/c-YCBCZFOC.min.js +1 -0
  64. package/dist/c-ZBSL4Y32.min.js +1 -0
  65. package/dist/c-ZP6O6UHV.min.js +1 -0
  66. package/dist/c-ZVL7ULNH.min.js +1 -0
  67. package/dist/components/ChartErrorBoundary.d.ts +5 -1
  68. package/dist/components/ai/intentWeights.d.ts +22 -0
  69. package/dist/components/ai/streamSchema.d.ts +98 -0
  70. package/dist/components/ai/streamingTypes.d.ts +27 -4
  71. package/dist/components/ai/suggestCharts.d.ts +10 -2
  72. package/dist/components/ai/suggestStreamCharts.d.ts +60 -13
  73. package/dist/components/ai/suggestStreamDashboard.d.ts +9 -1
  74. package/dist/components/charts/network/processSankey/frameMargins.d.ts +1 -1
  75. package/dist/components/charts/network/processSankey/labelPlacement.d.ts +1 -1
  76. package/dist/components/charts/physics/physicsHocUtils.d.ts +1 -1
  77. package/dist/components/charts/realtime/RealtimeAccumulator.d.ts +7 -0
  78. package/dist/components/charts/realtime/RealtimeHeatmap.d.ts +9 -2
  79. package/dist/components/charts/realtime/RealtimeHistogram.d.ts +13 -1
  80. package/dist/components/charts/realtime/RealtimeLineChart.types.d.ts +5 -1
  81. package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts +5 -1
  82. package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts +7 -1
  83. package/dist/components/charts/realtime/TemporalHistogram.capability.d.ts +5 -3
  84. package/dist/components/charts/realtime/aggregate.d.ts +11 -12
  85. package/dist/components/charts/realtime/defaultRealtimeTooltip.d.ts +9 -0
  86. package/dist/components/charts/realtime/eventTime.d.ts +7 -1
  87. package/dist/components/charts/realtime/useRealtimeLineIngestion.d.ts +13 -0
  88. package/dist/components/charts/shared/ChartError.d.ts +4 -6
  89. package/dist/components/charts/shared/GaugeReadout.d.ts +39 -4
  90. package/dist/components/charts/shared/axisExtent.d.ts +2 -1
  91. package/dist/components/charts/shared/chartMode.d.ts +2 -2
  92. package/dist/components/charts/shared/gaugeLayout.d.ts +69 -0
  93. package/dist/components/charts/shared/types.d.ts +4 -1
  94. package/dist/components/charts/shared/useNetworkChartSetup.d.ts +3 -0
  95. package/dist/components/charts/shared/useStreamStatus.d.ts +2 -2
  96. package/dist/components/charts/shared/withChartErrorBoundary.d.ts +14 -0
  97. package/dist/components/charts/xy/Scatterplot.streamCapability.d.ts +2 -0
  98. package/dist/components/charts/xy/WaterfallChart.d.ts +2 -0
  99. package/dist/components/charts/xy/WaterfallIndex.d.ts +12 -0
  100. package/dist/components/charts/xy/lineGapStrategy.d.ts +15 -3
  101. package/dist/components/legendGeometry.d.ts +148 -0
  102. package/dist/components/legendLayout.d.ts +20 -38
  103. package/dist/components/realtime/ReorderBuffer.d.ts +14 -0
  104. package/dist/components/realtime/SlidingExtent.d.ts +18 -0
  105. package/dist/components/realtime/WindowAccumulator.d.ts +5 -1
  106. package/dist/components/realtime/renderers/types.d.ts +1 -0
  107. package/dist/components/realtime/renderers/waterfallRenderer.d.ts +1 -1
  108. package/dist/components/recipes/atlas/resolution/appearance.d.ts +1 -1
  109. package/dist/components/recipes/atlas/resolution/scene.d.ts +1 -1
  110. package/dist/components/recipes/compositional/edgeRouting.d.ts +9 -0
  111. package/dist/components/recipes/compositional/metrics.d.ts +2 -2
  112. package/dist/components/recipes/compositional/projection.d.ts +3 -1
  113. package/dist/components/recipes/compositional/routing.d.ts +3 -1
  114. package/dist/components/recipes/compositional/testFixtures.d.ts +4 -0
  115. package/dist/components/recipes/compositional/topology.d.ts +2 -0
  116. package/dist/components/recipes/compositional/types.d.ts +10 -1
  117. package/dist/components/recipes/compositional/useCompositionalInterfaces.d.ts +20 -0
  118. package/dist/components/semiotic-ai-core.d.ts +3 -2
  119. package/dist/components/semiotic-ai-stream.d.ts +3 -2
  120. package/dist/components/semiotic-network-zoom.d.ts +1 -1
  121. package/dist/components/semiotic-recipes-react.d.ts +2 -0
  122. package/dist/components/semiotic-utils-core.d.ts +2 -0
  123. package/dist/components/server/serverChartConfigHeatmap.d.ts +13 -0
  124. package/dist/components/server/staticLegend.d.ts +5 -0
  125. package/dist/components/server/staticLegendText.d.ts +13 -0
  126. package/dist/components/server/staticSVGChrome.d.ts +2 -2
  127. package/dist/components/store/ThemeStore.d.ts +4 -1
  128. package/dist/components/store/themeCore.d.ts +2 -0
  129. package/dist/components/stream/DataSourceAdapter.d.ts +15 -62
  130. package/dist/components/stream/FrameRuntime.d.ts +3 -0
  131. package/dist/components/stream/GeoPipelineStore.d.ts +2 -0
  132. package/dist/components/stream/IngestActivity.d.ts +9 -0
  133. package/dist/components/stream/NetworkPipelineStore.d.ts +3 -1
  134. package/dist/components/stream/OrdinalPipelineStore.d.ts +5 -2
  135. package/dist/components/stream/OrdinalSVGOverlay.d.ts +1 -1
  136. package/dist/components/stream/PipelineStore.d.ts +8 -3
  137. package/dist/components/stream/accessibleDataRows.d.ts +1 -0
  138. package/dist/components/stream/axisTickUtils.d.ts +25 -5
  139. package/dist/components/stream/frameDefaultMargins.d.ts +26 -4
  140. package/dist/components/stream/frameKeyboardNavigation.d.ts +8 -1
  141. package/dist/components/stream/geoTypes.d.ts +2 -0
  142. package/dist/components/stream/graphKeyboardNavigation.d.ts +4 -2
  143. package/dist/components/stream/hitTestUtils.d.ts +7 -0
  144. package/dist/components/stream/keyboardNav.d.ts +3 -1
  145. package/dist/components/stream/mediaQuery.d.ts +2 -0
  146. package/dist/components/stream/navigationGraph.d.ts +10 -3
  147. package/dist/components/stream/networkEdgeHitIndex.d.ts +6 -2
  148. package/dist/components/stream/networkFrameKeyboardNavigation.d.ts +2 -0
  149. package/dist/components/stream/networkNavGroups.d.ts +3 -0
  150. package/dist/components/stream/networkPipelineConfig.d.ts +1 -0
  151. package/dist/components/stream/networkSceneTypes.d.ts +10 -0
  152. package/dist/components/stream/networkSpatialNavigation.d.ts +3 -0
  153. package/dist/components/stream/networkTypes.d.ts +2 -0
  154. package/dist/components/stream/networkZoom/ZoomableNetworkCustomChart.d.ts +6 -4
  155. package/dist/components/stream/networkZoom/gestures.d.ts +5 -0
  156. package/dist/components/stream/networkZoom/types.d.ts +10 -0
  157. package/dist/components/stream/ordinalAxisTicks.d.ts +27 -0
  158. package/dist/components/stream/ordinalSceneBuilders/pieScene.d.ts +10 -0
  159. package/dist/components/stream/ordinalSceneBuilders/types.d.ts +2 -0
  160. package/dist/components/stream/ordinalTypes.d.ts +11 -2
  161. package/dist/components/stream/pipelineBufferUtils.d.ts +9 -0
  162. package/dist/components/stream/pipelineConfig.d.ts +7 -0
  163. package/dist/components/stream/pipelineDomainResolution.d.ts +3 -2
  164. package/dist/components/stream/pipelineTransitionTypes.d.ts +3 -5
  165. package/dist/components/stream/pipelineTransitionUtils.d.ts +4 -0
  166. package/dist/components/stream/pipelineTransitions.d.ts +1 -13
  167. package/dist/components/stream/renderers/networkArcRenderer.d.ts +1 -3
  168. package/dist/components/stream/renderers/networkCircleRenderer.d.ts +1 -3
  169. package/dist/components/stream/renderers/networkPrimitiveRenderer.d.ts +5 -0
  170. package/dist/components/stream/renderers/networkRectRenderer.d.ts +1 -3
  171. package/dist/components/stream/renderers/renderPulse.d.ts +8 -14
  172. package/dist/components/stream/roundScaleDomain.d.ts +9 -0
  173. package/dist/components/stream/sceneToSVGShared.d.ts +9 -0
  174. package/dist/components/stream/shallowEqual.d.ts +2 -0
  175. package/dist/components/stream/stalenessBands.d.ts +1 -1
  176. package/dist/components/stream/svgOverlayUtils.d.ts +12 -0
  177. package/dist/components/stream/types.d.ts +10 -2
  178. package/dist/components/stream/useFrame.d.ts +7 -4
  179. package/dist/components/stream/useMediaPreferences.d.ts +1 -4
  180. package/dist/components/stream/useOrdinalFrameHandle.d.ts +4 -14
  181. package/dist/components/stream/useStalenessCheck.d.ts +5 -3
  182. package/dist/components/stream/useStreamingDataHandle.d.ts +24 -0
  183. package/dist/components/stream/useXYFrameHandle.d.ts +4 -14
  184. package/dist/components/stream/xyDateTicks.d.ts +33 -4
  185. package/dist/components/stream/xyFrameAxisTypes.d.ts +2 -0
  186. package/dist/components/stream/xyPlugins/registry.d.ts +7 -0
  187. package/dist/components/stream/xySceneBuilders/heatmapScene.d.ts +11 -2
  188. package/dist/components/stream/xySceneBuilders/types.d.ts +4 -0
  189. package/dist/components/types/legendTypes.d.ts +12 -1
  190. package/dist/geo.min.js +155 -152
  191. package/dist/geo.module.min.js +1 -1
  192. package/dist/network.module.min.js +1 -1
  193. package/dist/ordinal.module.min.js +1 -1
  194. package/dist/physics.module.min.js +1 -1
  195. package/dist/processSankeyLayoutWorker.js +1 -1
  196. package/dist/semiotic-ai-core.d.ts +3 -2
  197. package/dist/semiotic-ai-core.min.js +5 -5
  198. package/dist/semiotic-ai-core.module.min.js +4 -4
  199. package/dist/semiotic-ai.module.min.js +2 -2
  200. package/dist/semiotic-artifact.min.js +6 -6
  201. package/dist/semiotic-artifact.module.min.js +5 -5
  202. package/dist/semiotic-atlas-selection.module.min.js +1 -1
  203. package/dist/semiotic-atlas.module.min.js +1 -1
  204. package/dist/semiotic-client-cjs-shared.min.js +1021 -1024
  205. package/dist/semiotic-client-compositional.module.min.js +1 -1
  206. package/dist/semiotic-client-shared.module.min.js +1 -1
  207. package/dist/semiotic-experimental-auxiliary.module.min.js +2 -2
  208. package/dist/semiotic-experimental-network-resolution-react.module.min.js +1 -1
  209. package/dist/semiotic-experimental-node-auxiliary.module.min.js +3 -3
  210. package/dist/semiotic-line.module.min.js +1 -1
  211. package/dist/semiotic-network-zoom.d.ts +1 -1
  212. package/dist/semiotic-network-zoom.min.js +7 -7
  213. package/dist/semiotic-network-zoom.module.min.js +1 -1
  214. package/dist/semiotic-realtime-core.module.min.js +1 -1
  215. package/dist/semiotic-realtime-react.module.min.js +1 -1
  216. package/dist/semiotic-recipes-core-cjs-base.min.js +101 -101
  217. package/dist/semiotic-recipes-core.module.min.js +1 -1
  218. package/dist/semiotic-recipes-react.d.ts +2 -0
  219. package/dist/semiotic-recipes-react.min.js +8 -8
  220. package/dist/semiotic-server-edge-node.module.min.js +3 -3
  221. package/dist/semiotic-server-edge.min.js +399 -397
  222. package/dist/semiotic-server-edge.module.min.js +3 -3
  223. package/dist/semiotic-server-node.min.js +399 -397
  224. package/dist/semiotic-themes-core.min.js +2 -2
  225. package/dist/semiotic-themes-core.module.min.js +1 -1
  226. package/dist/semiotic-themes.min.js +2 -2
  227. package/dist/semiotic-themes.module.min.js +1 -1
  228. package/dist/semiotic-utils-core.d.ts +2 -0
  229. package/dist/semiotic-utils-core.min.js +11 -11
  230. package/dist/semiotic-utils-core.module.min.js +3 -3
  231. package/dist/semiotic-value.module.min.js +1 -1
  232. package/dist/semiotic.module.min.js +1 -1
  233. package/dist/server.min.js +399 -397
  234. package/dist/server.module.min.js +3 -3
  235. package/dist/xy.module.min.js +1 -1
  236. package/package.json +11 -11
  237. package/dist/c-2M2OPWVA.min.js +0 -37
  238. package/dist/c-2N7IU2NY.min.js +0 -1
  239. package/dist/c-3UXQGCQT.min.js +0 -1
  240. package/dist/c-4RVDKSMQ.min.js +0 -1
  241. package/dist/c-4YPPVFZH.min.js +0 -1
  242. package/dist/c-6WJKNYIG.min.js +0 -1
  243. package/dist/c-7UN2WUMI.min.js +0 -1
  244. package/dist/c-AQUX6L2O.min.js +0 -1
  245. package/dist/c-BR5QDUCR.min.js +0 -1
  246. package/dist/c-C3YQVUB6.min.js +0 -1
  247. package/dist/c-COP4OISO.min.js +0 -1
  248. package/dist/c-ENRZPF5E.min.js +0 -1
  249. package/dist/c-FAOZZE77.min.js +0 -1
  250. package/dist/c-HBLICBM6.min.js +0 -1
  251. package/dist/c-I4BEWAKT.min.js +0 -1
  252. package/dist/c-IDCFMBA4.min.js +0 -2
  253. package/dist/c-KLJDKRD5.min.js +0 -1
  254. package/dist/c-LEICSI5V.min.js +0 -1
  255. package/dist/c-MOK4RWNO.min.js +0 -1
  256. package/dist/c-N2TVSOYL.min.js +0 -2
  257. package/dist/c-NHZ2E3CI.min.js +0 -1
  258. package/dist/c-OIJL2WZH.min.js +0 -1
  259. package/dist/c-OSLNYZ3Q.min.js +0 -51
  260. package/dist/c-OWRVBUSL.min.js +0 -1
  261. package/dist/c-QIVKWHDL.min.js +0 -1
  262. package/dist/c-QUAEYF34.min.js +0 -1
  263. package/dist/c-RDFFLRKC.min.js +0 -1
  264. package/dist/c-RTU5425Z.min.js +0 -1
  265. package/dist/c-SIQVOV6A.min.js +0 -1
  266. package/dist/c-SU6Z75M2.min.js +0 -1
  267. package/dist/c-SWVXFUDL.min.js +0 -1
  268. package/dist/c-TC47SNSI.min.js +0 -1
  269. package/dist/c-VLWWXOM5.min.js +0 -1
  270. package/dist/c-VNFIRKU5.min.js +0 -1
  271. package/dist/c-W5ATXREF.min.js +0 -1
  272. package/dist/c-WFX456JK.min.js +0 -5
  273. package/dist/c-WSWMQDFZ.min.js +0 -1
  274. package/dist/c-XORVM6C5.min.js +0 -1
  275. package/dist/c-YGTMWEEF.min.js +0 -1
  276. package/dist/c-ZDCTFRA6.min.js +0 -1
@@ -42,6 +42,21 @@ export interface StreamFieldSchema {
42
42
  kind: StreamFieldKind;
43
43
  /** Optional role hint — overrides the engine's inference. */
44
44
  role?: StreamFieldRole;
45
+ /**
46
+ * Expected number of distinct values (categorical, boolean, or key
47
+ * fields). Lets pie/donut fits and series caveats use the real count
48
+ * instead of warning that cardinality is unknown.
49
+ */
50
+ cardinality?: number;
51
+ /**
52
+ * Whether summing this measure across events is meaningful. `true` for
53
+ * counts, amounts, and signed changes; `false` for levels such as
54
+ * prices, latencies, or percentages. Charts that sum per bin or per
55
+ * category (RealtimeHistogram, append-stream bars and pies) and the
56
+ * running-total RealtimeWaterfallChart rank lower while this is unknown
57
+ * and are excluded when it is `false`.
58
+ */
59
+ additive?: boolean;
45
60
  }
46
61
  /**
47
62
  * Schema describing what a stream emits. No data, just shape + environment hints.
@@ -49,9 +64,11 @@ export interface StreamFieldSchema {
49
64
  export interface StreamSchema {
50
65
  fields: ReadonlyArray<StreamFieldSchema>;
51
66
  /**
52
- * Hint about expected event rate. Affects chart selection — heatmaps and
53
- * waterfalls amortize high-throughput streams better than line charts do.
54
- * A number is rows per second; string bands are qualitative.
67
+ * Hint about expected event rate. Affects chart selection — binned charts
68
+ * (heatmaps, histograms) and windowed aggregation amortize high-throughput
69
+ * streams; per-event marks (swarms, waterfalls) do not. A number is rows
70
+ * per second and also sizes the suggested retention buffer; string bands
71
+ * are qualitative.
55
72
  */
56
73
  throughput?: StreamThroughput;
57
74
  /**
@@ -80,7 +97,7 @@ export interface StreamChartCapability {
80
97
  /**
81
98
  * Import specifier for generated code. Built-ins use family subpaths
82
99
  * (`semiotic/realtime`, `semiotic/ordinal`, `semiotic/value`); wrappers
83
- * may declare any string (e.g. `"@iris/charts"`).
100
+ * may declare any string (e.g. `"@acme/charts"`).
84
101
  */
85
102
  importPath: string;
86
103
  /**
@@ -95,6 +112,12 @@ export interface StreamChartCapability {
95
112
  fits: (schema: StreamSchema) => null | string;
96
113
  intentScores: Partial<Record<IntentId, StreamIntentScorer>>;
97
114
  caveats?: (schema: StreamSchema) => ReadonlyArray<string>;
115
+ /**
116
+ * Schema-specific explanations of how `buildProps` adapted the chart
117
+ * (windowed aggregation, buffer sizing, counting instead of summing).
118
+ * Appended to the suggestion's `reasons`.
119
+ */
120
+ reasons?: (schema: StreamSchema) => ReadonlyArray<string>;
98
121
  buildProps: (schema: StreamSchema) => Record<string, unknown>;
99
122
  }
100
123
  export type StreamIntentScorer = number | ((schema: StreamSchema) => number);
@@ -5,7 +5,12 @@ import type { IntentId } from "./intents";
5
5
  import { type AudienceProfile, type ReceptionModality } from "./audienceProfile";
6
6
  import { type DataQualityProfile, type DataScaleProfile } from "./dataScaleProfile";
7
7
  export interface SuggestChartsOptions extends ProfileDataOptions {
8
- /** Ranking intent(s). When omitted, suggestions are ranked by mean intent score. */
8
+ /**
9
+ * Ranking intent(s). When omitted, intents are weighted from the profile:
10
+ * a time axis ranks as a trend first, categories as a ranking, two plain
11
+ * measures as a correlation. Graph, hierarchy, and geo data rank by the
12
+ * mean of each chart's non-zero intent scores.
13
+ */
9
14
  intent?: IntentId | IntentId[];
10
15
  /** Restrict to these component names. */
11
16
  allow?: ReadonlyArray<string>;
@@ -15,7 +20,10 @@ export interface SuggestChartsOptions extends ProfileDataOptions {
15
20
  maxResults?: number;
16
21
  /** Include variant-level suggestions (default true). */
17
22
  includeVariants?: boolean;
18
- /** Filter out suggestions with a composite score below this (default 0 — keep all). */
23
+ /**
24
+ * Filter out suggestions with a composite score below this. When omitted,
25
+ * charts scoring 0 for the ranking intents are dropped; pass `0` to keep them.
26
+ */
19
27
  minScore?: number;
20
28
  /** Provide a pre-built profile instead of re-deriving from data. */
21
29
  profile?: ChartDataProfile;
@@ -24,12 +24,35 @@ export interface SuggestStreamChartsResult {
24
24
  suggestions: StreamSuggestion[];
25
25
  excluded: ReadonlyArray<RejectedStreamCapability>;
26
26
  stretchSuggestions: StreamStretchSuggestion[];
27
+ /**
28
+ * Intents the ranking used: the requested ones, or the defaults inferred
29
+ * from the schema when none were passed.
30
+ * Optional for compatibility with stored results; always returned by
31
+ * `suggestStreamCharts`.
32
+ */
33
+ rankingIntents?: IntentId[];
34
+ /**
35
+ * Problems found in the schema — unknown keys, invalid kinds or hints,
36
+ * duplicate fields. Repairable ones (kind aliases) were applied before
37
+ * ranking; the rest were ignored.
38
+ * Optional for compatibility with stored results; always returned by
39
+ * `suggestStreamCharts`.
40
+ */
41
+ warnings?: string[];
27
42
  }
28
43
  export interface SuggestStreamChartsOptions {
44
+ /**
45
+ * Ranking intent(s). When omitted, intents are weighted from the schema
46
+ * (a measure over time ranks as a trend first; see `rankingIntents`).
47
+ */
29
48
  intent?: IntentId | IntentId[];
30
49
  allow?: ReadonlyArray<string>;
31
50
  deny?: ReadonlyArray<string>;
32
51
  maxResults?: number;
52
+ /**
53
+ * Drop suggestions scoring below this. When omitted, charts that score 0
54
+ * for the ranking intents are dropped; pass `0` to keep them.
55
+ */
33
56
  minScore?: number;
34
57
  capabilities?: ReadonlyArray<StreamChartCapability>;
35
58
  audience?: AudienceProfile;
@@ -43,27 +66,51 @@ export interface SuggestStreamChartsOptions {
43
66
  * dashboards, monitoring views, anywhere events arrive over time rather
44
67
  * than as a bounded table.
45
68
  *
46
- * Returns `{ suggestions, excluded, stretchSuggestions }`. `excluded`
47
- * lists every registered capability whose `fits()` rejected the schema
48
- * so a suggestion panel can say why a chart is missing. Pass `audience`
49
- * to apply familiarity/target bias and (when `exposureLevel !== 0`) fill
50
- * `stretchSuggestions`.
69
+ * Returns `{ suggestions, excluded, stretchSuggestions, rankingIntents,
70
+ * warnings }`. `excluded` lists every registered capability whose `fits()`
71
+ * rejected the schema so a suggestion panel can say why a chart is
72
+ * missing; `warnings` reports schema problems (unknown keys, invalid kinds).
73
+ * Without an `intent`, ranking weights intents from the schema. Pass
74
+ * `audience` to apply familiarity/target bias and (when
75
+ * `exposureLevel !== 0`) fill `stretchSuggestions`.
51
76
  *
52
77
  * @example
53
78
  * const { suggestions } = suggestStreamCharts({
54
79
  * fields: [
55
80
  * { name: "ts", kind: "date" },
56
- * { name: "latency_ms", kind: "numeric" },
57
- * { name: "endpoint", kind: "categorical" },
81
+ * { name: "latency_ms", kind: "numeric", additive: false },
82
+ * { name: "endpoint", kind: "categorical", cardinality: 6 },
58
83
  * ],
59
- * throughput: "high",
84
+ * throughput: 400,
60
85
  * retention: "windowed",
61
86
  * }, { intent: "trend" })
62
- * // → suggestions[0] is RealtimeHeatmap or RealtimeWaterfallChart
87
+ * // → suggestions[0] is RealtimeLineChart with
88
+ * // aggregate: { size: "1s", stat: "mean" } and seriesAccessor: "endpoint"
63
89
  */
64
- export declare function suggestStreamCharts(schema: StreamSchema, options?: SuggestStreamChartsOptions): SuggestStreamChartsResult;
90
+ export declare function suggestStreamCharts(schema: StreamSchema, options?: SuggestStreamChartsOptions): SuggestStreamChartsResult & {
91
+ rankingIntents: IntentId[];
92
+ warnings: string[];
93
+ };
94
+ /** Why one capability was or was not suggested for a schema. */
95
+ export interface StreamCapabilityExplanation {
96
+ component: string;
97
+ /**
98
+ * `suggested`: ranked (see `rank`). `excluded`: `fits()` rejected the
99
+ * schema. `filtered`: it fits, but allow/deny, `minScore`, or
100
+ * `maxResults` removed it. `unknown`: no capability has this name.
101
+ */
102
+ status: "suggested" | "excluded" | "filtered" | "unknown";
103
+ /** 1-based position among the suggestions when `status` is "suggested". */
104
+ rank?: number;
105
+ reason: string;
106
+ /** The ranked suggestion, or the unfiltered one when `status` is "filtered". */
107
+ suggestion?: StreamSuggestion;
108
+ warnings: string[];
109
+ }
65
110
  /**
66
- * Like `suggestStreamCharts`, but named for diagnostic panels that care
67
- * about the excluded list. Same result object.
111
+ * Explain stream chart fit. With a component name, returns why that chart
112
+ * was suggested, excluded, or filtered out; without one, returns the same
113
+ * result as `suggestStreamCharts`, for panels that list `excluded`.
68
114
  */
69
- export declare function explainStreamCapabilityFit(schema: StreamSchema, options?: SuggestStreamChartsOptions): SuggestStreamChartsResult;
115
+ export declare function explainStreamCapabilityFit(schema: StreamSchema, options?: SuggestStreamChartsOptions): ReturnType<typeof suggestStreamCharts>;
116
+ export declare function explainStreamCapabilityFit(schema: StreamSchema, component: string, options?: SuggestStreamChartsOptions): StreamCapabilityExplanation;
@@ -14,6 +14,12 @@ export interface StreamDashboardSuggestion {
14
14
  intentsMissing: IntentId[];
15
15
  stretchPanels: StreamStretchSuggestion[];
16
16
  schemas: ReadonlyArray<StreamSchema>;
17
+ /**
18
+ * Schema problems, prefixed with the schema index when there are several.
19
+ * Optional for compatibility with stored results; always returned by
20
+ * `suggestStreamDashboard`.
21
+ */
22
+ warnings?: string[];
17
23
  }
18
24
  export interface SuggestStreamDashboardOptions {
19
25
  intent?: IntentId | IntentId[];
@@ -32,4 +38,6 @@ export interface SuggestStreamDashboardOptions {
32
38
  * policy (`dashboard.cellBudget`, `leadFamilies`, `windowPreference`)
33
39
  * is first-class: pass it on `AudienceProfile.dashboard`.
34
40
  */
35
- export declare function suggestStreamDashboard(schemas: StreamSchema | ReadonlyArray<StreamSchema>, options?: SuggestStreamDashboardOptions): StreamDashboardSuggestion;
41
+ export declare function suggestStreamDashboard(schemas: StreamSchema | ReadonlyArray<StreamSchema>, options?: SuggestStreamDashboardOptions): StreamDashboardSuggestion & {
42
+ warnings: string[];
43
+ };
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Reserve vertical frame space only for chrome that is actually rendered.
2
+ * Reserve frame space only for chrome that is actually rendered.
3
3
  * Eight pixels clear the bare axis rule; telemetry needs its two-line
4
4
  * readout, and labeled ticks need their 20px baseline plus font descent.
5
5
  */
@@ -5,7 +5,7 @@ import type { SlotByNode } from "./layoutGeometry";
5
5
  * pixels apart. Their end-anchored labels otherwise paint over one another.
6
6
  * Stagger only horizontally-overlapping clusters within the same packed row.
7
7
  */
8
- export declare function staggerProcessSankeyLabels(bands: readonly ProcessSankeyBandSpec[], slotByNode: SlotByNode, plotH: number): ProcessSankeyBandSpec[];
8
+ export declare function staggerProcessSankeyLabels(bands: readonly ProcessSankeyBandSpec[], slotByNode: SlotByNode, plotH: number, plotW?: number): ProcessSankeyBandSpec[];
9
9
  /**
10
10
  * A vertical river can have many nodes opening on the same historical stage.
11
11
  * Place those labels in compact rows within the preceding inter-stage gap.
@@ -176,7 +176,7 @@ export declare function renderPhysicsChartState<TDatum extends Datum>(options: {
176
176
  responsiveHeight?: boolean;
177
177
  };
178
178
  }): React.ReactElement | null;
179
- export declare function renderPhysicsFrame(componentName: string, size: [number, number], children: React.ReactNode, responsiveLayout?: Pick<PhysicsChartModeResult, "responsiveContainerRef" | "responsiveHeight" | "responsiveWidth">): React.ReactElement;
179
+ export declare function renderPhysicsFrame(size: [number, number], children: React.ReactNode, responsiveLayout?: Pick<PhysicsChartModeResult, "responsiveContainerRef" | "responsiveHeight" | "responsiveWidth">): React.ReactNode;
180
180
  export declare function composePhysicsFrameGraphics(first: FrameGraphicsProp | undefined, second: FrameGraphicsProp | undefined): FrameGraphicsProp | undefined;
181
181
  export declare function resolvePhysicsTooltipProps(tooltip: TooltipProp | undefined, frameProps?: Partial<StreamPhysicsFrameProps>, options?: {
182
182
  unwrapSourceDatum?: boolean;
@@ -7,9 +7,16 @@ export declare const AGG_SERIES = "__aggSeries";
7
7
  export declare class RealtimeAccumulator {
8
8
  private readonly config;
9
9
  private readonly seriesAccessor?;
10
+ private readonly seriesRows;
10
11
  private readonly groups;
12
+ private retention;
13
+ private seed;
11
14
  constructor(config: AggregateConfig, seriesAccessor?: ChartAccessor<Datum, string> | undefined);
12
15
  push<TDatum extends Datum>(row: Datum, timeAccessor?: ChartAccessor<TDatum, CoercibleNumber>, valueAccessor?: ChartAccessor<TDatum, number>): void;
13
16
  emit(config: AggregateConfig): AggregatedRealtimeDatum[];
17
+ setRetention(retain: number): void;
18
+ /** Move all series toward closed windows without adding fake samples. */
19
+ advanceIdle(elapsed: number): void;
20
+ advanceWatermark(time: number): void;
14
21
  clear(): void;
15
22
  }
@@ -46,6 +46,8 @@ export interface RealtimeHeatmapProps<TDatum extends Datum = Datum> extends Real
46
46
  windowMode?: WindowMode;
47
47
  /** Ring buffer capacity */
48
48
  windowSize?: number;
49
+ /** Maximum live rows retained in growing mode. Defaults to 100,000. */
50
+ maxCapacity?: number;
49
51
  /** Alias for `windowSize` — ring-buffer capacity, not the aggregation window. */
50
52
  capacity?: number;
51
53
  /** Alias for `windowMode`. */
@@ -56,12 +58,17 @@ export interface RealtimeHeatmapProps<TDatum extends Datum = Datum> extends Real
56
58
  timeAccessor?: ChartAccessor<TDatum, CoercibleNumber>;
57
59
  /** Value/y accessor */
58
60
  valueAccessor?: ChartAccessor<TDatum, number>;
59
- /** Category accessor for colored cells */
61
+ /**
62
+ * Retained on source rows for tooltips and custom callbacks. Binned cells
63
+ * pool every category and are coloured by the aggregate, not by category.
64
+ */
60
65
  categoryAccessor?: ChartAccessor<TDatum, string>;
61
66
  /** Fixed time domain */
62
67
  timeExtent?: [number, number];
63
68
  /** Fixed value domain */
64
- valueExtent?: [number, number];
69
+ valueExtent?: [number | undefined, number | undefined] | [number];
70
+ /** Round open value-domain ends after padding and final plot layout. */
71
+ axisExtent?: import("../shared/axisExtent").AxisExtentMode;
65
72
  /** Extent padding factor */
66
73
  extentPadding?: number;
67
74
  /** Number of x-axis bins (default: 20) */
@@ -58,16 +58,28 @@ export interface RealtimeHistogramProps<TDatum extends Datum = Datum> extends Re
58
58
  capacityMode?: WindowMode;
59
59
  /** Ring buffer capacity */
60
60
  windowSize?: number;
61
+ /** Maximum live rows retained in growing mode. Defaults to 100,000. */
62
+ maxCapacity?: number;
61
63
  /** Controlled data array */
62
64
  data?: RealtimeData<TDatum>;
63
65
  /** Time accessor returning a number, Date, or numeric/date string. */
64
66
  timeAccessor?: ChartAccessor<TDatum, CoercibleNumber>;
65
67
  /** Value accessor */
66
68
  valueAccessor?: ChartAccessor<TDatum, number>;
69
+ /**
70
+ * What each bin totals. `"sum"` adds `valueAccessor` per bin. `"count"`
71
+ * counts events instead — every row with a valid time counts once and
72
+ * `valueAccessor` is ignored — so streams without a numeric field (click
73
+ * or log events) still bin.
74
+ * @default "sum"
75
+ */
76
+ aggregation?: "sum" | "count";
67
77
  /** Fixed time domain */
68
78
  timeExtent?: [number, number];
69
79
  /** Fixed value domain */
70
- valueExtent?: [number, number];
80
+ valueExtent?: [number | undefined, number | undefined] | [number];
81
+ /** Round open value-domain ends after padding and final plot layout. */
82
+ axisExtent?: import("../shared/axisExtent").AxisExtentMode;
71
83
  /**
72
84
  * Direction bars grow from the baseline.
73
85
  * "up" uses the normal y-domain. "down" flips the resolved value
@@ -61,6 +61,8 @@ export interface RealtimeLineChartProps<TDatum extends Datum = Datum> extends Re
61
61
  windowMode?: WindowMode;
62
62
  /** Ring buffer capacity */
63
63
  windowSize?: number;
64
+ /** Maximum live rows retained in growing mode. Defaults to 100,000. */
65
+ maxCapacity?: number;
64
66
  /**
65
67
  * Ring-buffer capacity. Alias for `windowSize` — prefer this name when
66
68
  * "window" means the aggregation window (`aggregate.window`).
@@ -79,7 +81,9 @@ export interface RealtimeLineChartProps<TDatum extends Datum = Datum> extends Re
79
81
  /** Fixed time domain */
80
82
  timeExtent?: [number, number];
81
83
  /** Fixed value domain */
82
- valueExtent?: [number, number];
84
+ valueExtent?: [number | undefined, number | undefined] | [number];
85
+ /** Round open value-domain ends after padding and final plot layout. */
86
+ axisExtent?: import("../shared/axisExtent").AxisExtentMode;
83
87
  /** Extent padding factor */
84
88
  extentPadding?: number;
85
89
  /** Line color */
@@ -50,6 +50,8 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> extends R
50
50
  capacityMode?: WindowMode;
51
51
  /** Ring buffer capacity */
52
52
  windowSize?: number;
53
+ /** Maximum live rows retained in growing mode. Defaults to 100,000. */
54
+ maxCapacity?: number;
53
55
  /** Controlled data array */
54
56
  data?: RealtimeData<TDatum>;
55
57
  /** Time accessor returning a number, Date, or numeric/date string. */
@@ -59,7 +61,9 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> extends R
59
61
  /** Fixed time domain */
60
62
  timeExtent?: [number, number];
61
63
  /** Fixed value domain */
62
- valueExtent?: [number, number];
64
+ valueExtent?: [number | undefined, number | undefined] | [number];
65
+ /** Round open value-domain ends after padding and final plot layout. */
66
+ axisExtent?: import("../shared/axisExtent").AxisExtentMode;
63
67
  /** Value-axis scale. "symlog" supports signed values while compressing large magnitudes. */
64
68
  yScaleType?: "linear" | "log" | "symlog";
65
69
  /** Extent padding factor */
@@ -50,6 +50,8 @@ export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> exten
50
50
  capacityMode?: WindowMode;
51
51
  /** Ring buffer capacity */
52
52
  windowSize?: number;
53
+ /** Maximum live rows retained in growing mode. Defaults to 100,000. */
54
+ maxCapacity?: number;
53
55
  /** Controlled data array */
54
56
  data?: RealtimeData<TDatum>;
55
57
  /** Time accessor returning a number, Date, or numeric/date string. */
@@ -59,7 +61,9 @@ export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> exten
59
61
  /** Fixed time domain */
60
62
  timeExtent?: [number, number];
61
63
  /** Fixed value domain */
62
- valueExtent?: [number, number];
64
+ valueExtent?: [number | undefined, number | undefined] | [number];
65
+ /** Round open value-domain ends after padding and final plot layout. */
66
+ axisExtent?: import("../shared/axisExtent").AxisExtentMode;
63
67
  /** Extent padding factor */
64
68
  extentPadding?: number;
65
69
  /** Age-based opacity decay for streaming bars. */
@@ -71,6 +75,8 @@ export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> exten
71
75
  /** Mark transition configuration. */
72
76
  transition?: TransitionConfig;
73
77
  /** Color for positive (gain) bars */
78
+ /** Initial cumulative balance. Evicted deltas carry forward until clear or data replacement. */
79
+ initialValue?: number;
74
80
  positiveColor?: string;
75
81
  /** Color for negative (loss) bars */
76
82
  negativeColor?: string;
@@ -1,7 +1,9 @@
1
1
  import type { StreamChartCapability } from "../../ai/streamingTypes";
2
2
  /**
3
- * TemporalHistogram is the bounded sibling of RealtimeHistogram — same chart
4
- * but for static data with a fixed window. For stream selection it competes
5
- * with RealtimeHistogram; the choice depends on retention.
3
+ * TemporalHistogram is the bounded sibling of RealtimeHistogram: same chart,
4
+ * but it takes a static `data` array and has no push API. A stream — even
5
+ * one with cumulative retention — belongs to RealtimeHistogram (which
6
+ * suggests `windowMode: "growing"` for cumulative retention), so this
7
+ * descriptor stays registered only to explain the redirect.
6
8
  */
7
9
  export declare const TemporalHistogramCapability: StreamChartCapability;
@@ -8,7 +8,9 @@ import type { Datum } from "../shared/datumTypes";
8
8
  * arrival rate. Structural window changes start a new accumulator epoch:
9
9
  * controlled `data` is replayed, while push-only history resets because the
10
10
  * transform does not retain every raw event. `stat`, `band`,
11
- * and `sigma` are readout-only and update existing windows in place.
11
+ * and `sigma` update existing windows in place when the required sketches are
12
+ * already enabled. Selecting a percentile or distinct stat enables its sketch
13
+ * automatically; enabling a new sketch starts a new epoch.
12
14
  */
13
15
  export interface AggregateConfig {
14
16
  /** Window kind. @default "tumbling" */
@@ -25,18 +27,21 @@ export interface AggregateConfig {
25
27
  band?: AggregateBand;
26
28
  /** Multiplier for the `stddev` band (drawn as value ± sigma·σ). @default 1 */
27
29
  sigma?: number;
28
- /** Keep at most this many most-recent windows per series. @default unbounded */
30
+ /** Keep at most this many recent windows per series. Push charts default to windowSize (200); bounded data defaults to unbounded. Use Infinity to opt out. */
29
31
  retain?: number;
30
32
  /**
31
- * Quantiles to emit per window (e.g. `[0.5, 0.95, 0.99]`). Structural:
33
+ * Quantiles to emit per window (e.g. `[0.5, 0.95, 0.99]`). Percentile stats
34
+ * automatically enable p50/p95/p99. Structural:
32
35
  * changing this rebuilds the accumulator (same as `window` / `size`).
33
36
  */
34
37
  percentiles?: ReadonlyArray<number>;
35
38
  /**
36
- * Track an approximate distinct count per window. Structural: changing
39
+ * Track an approximate distinct count per window (automatic for stat="distinct"). Structural: changing
37
40
  * this rebuilds the accumulator.
38
41
  */
39
42
  distinct?: boolean;
43
+ /** Advance partial windows with elapsed wall time during idle periods. Default false. */
44
+ idleAdvance?: boolean;
40
45
  }
41
46
  export declare const AGG_TIME = "time";
42
47
  export declare const AGG_VALUE = "value";
@@ -59,16 +64,10 @@ export interface AggregatedRealtimeDatum extends Datum {
59
64
  }
60
65
  /**
61
66
  * Build a `WindowAccumulator` from a config, parsing duration strings.
62
- * Returns `null` when the window width is unparseable, so the caller can
63
- * skip aggregation rather than bucket on a zero-width window.
67
+ * Returns `null` with a development warning for unparseable durations. Numeric
68
+ * configuration violations (including excessive hopping fanout) throw RangeError.
64
69
  */
65
70
  export declare function createAccumulator(config: AggregateConfig): WindowAccumulator | null;
66
- /**
67
- * Snapshot the accumulator into frame-ready rows. Each row carries the
68
- * primary stat at `value`, the window midpoint at `time`, the band
69
- * bounds (when a band is configured), and provenance fields (`count`,
70
- * partial flag, raw start/end) for tooltips and partial-window styling.
71
- */
72
71
  export declare function aggregatedRows(acc: WindowAccumulator, config: AggregateConfig): AggregatedRealtimeDatum[];
73
72
  /** Whether a config requests a band envelope. */
74
73
  export declare function hasBand(config: AggregateConfig): boolean;
@@ -14,8 +14,17 @@ interface DefaultRealtimeTooltipOptions<TDatum extends Datum = Datum> {
14
14
  */
15
15
  xLabel?: string;
16
16
  yLabel?: string;
17
+ /**
18
+ * Series/category channel. When set, the tooltip leads with the hovered
19
+ * datum's series name so multi-series charts identify the mark.
20
+ */
21
+ groupAccessor?: string | ((d: Datum) => unknown);
22
+ /** Label for the series row ("series" by default). */
23
+ groupLabel?: string;
17
24
  /** Formats a histogram bin's bounds (the chart's `tickFormatTime`). */
18
25
  formatTime?: (value: number) => string;
26
+ /** What a histogram bin totals; labels the bin total row. @default "sum" */
27
+ aggregation?: "sum" | "count";
19
28
  }
20
29
  /**
21
30
  * Build a default tooltip renderer for a Realtime HOC. Returns a
@@ -7,7 +7,9 @@ import type { Datum } from "../shared/datumTypes";
7
7
  * RealtimeLineChart's chart-specific handle exposes `flush()` to release
8
8
  * the final grace-window tail at an asserted end-of-stream boundary. A live
9
9
  * config or time-accessor change drains the prior tail before the new policy
10
- * begins, rather than abandoning buffered events.
10
+ * begins, rather than abandoning buffered events. `idleAdvance` opts into wall-time
11
+ * progression on a 250ms timer, releasing quiet tails. `maxFutureSkew` rejects
12
+ * timestamps beyond Date.now() + skew before they can move the watermark.
11
13
  */
12
14
  export interface EventTimeConfig {
13
15
  /**
@@ -21,6 +23,10 @@ export interface EventTimeConfig {
21
23
  * - `"keep"`: release it immediately, out of order (still counted).
22
24
  */
23
25
  latePolicy?: LatePolicy;
26
+ /** Reject events this far ahead of Date.now(), without poisoning the watermark. */
27
+ maxFutureSkew?: number | string;
28
+ /** Release the quiet tail using elapsed wall time. Default false. */
29
+ idleAdvance?: boolean;
24
30
  }
25
31
  /**
26
32
  * Build a `ReorderBuffer` from a config and a time accessor, parsing the
@@ -0,0 +1,13 @@
1
+ import type { Ref, RefObject } from "react";
2
+ import type { Datum } from "../shared/datumTypes";
3
+ import type { RealtimeFrameHandle } from "../../realtime/types";
4
+ import type { StreamXYFrameHandle } from "../../stream/types";
5
+ import type { RealtimeLineChartProps } from "./RealtimeLineChart.types";
6
+ import type { AggregatedRealtimeDatum } from "./aggregate";
7
+ type IngestionOptions<TDatum extends Datum> = Pick<RealtimeLineChartProps<TDatum>, "aggregate" | "eventTime" | "data" | "timeAccessor" | "valueAccessor" | "seriesAccessor" | "onObservation" | "chartId">;
8
+ /** Owns bounded aggregate publication and optional event-time ingestion. */
9
+ export declare function useRealtimeLineIngestion<TDatum extends Datum>(ref: Ref<RealtimeFrameHandle<TDatum, Datum>>, frameRef: RefObject<StreamXYFrameHandle | null>, windowSize: number, { aggregate, eventTime, data, timeAccessor, valueAccessor, seriesAccessor, onObservation, chartId }: IngestionOptions<TDatum>): {
10
+ aggEnabled: boolean;
11
+ aggRows: AggregatedRealtimeDatum[];
12
+ };
13
+ export {};
@@ -4,18 +4,16 @@ export interface ChartErrorProps {
4
4
  componentName: string;
5
5
  /** The error message to display */
6
6
  message: string;
7
- /** Optional diagnostic suggestions from diagnoseConfig */
8
- diagnosticHint?: string;
9
7
  /** Chart width */
10
- width: number;
8
+ width: number | string;
11
9
  /** Chart height */
12
- height: number;
10
+ height: number | string;
13
11
  }
14
12
  /**
15
13
  * Renders a visible, styled error state inside the chart's dimensions.
16
- * Shows the component name, error message, and a hint for developers.
14
+ * Shows the component name and error message.
17
15
  *
18
16
  * Designed to be obvious in development but not alarming in production —
19
17
  * uses muted colors that adapt to light/dark backgrounds.
20
18
  */
21
- export default function ChartError({ componentName, message, diagnosticHint, width, height, }: ChartErrorProps): React.JSX.Element;
19
+ export default function ChartError({ componentName, message, width, height }: ChartErrorProps): React.JSX.Element;
@@ -1,4 +1,14 @@
1
1
  import * as React from "react";
2
+ /**
3
+ * Vertical reach of a readout from its value center line: `above` is the
4
+ * value's half-height, `below` reaches the last caption's descenders (or the
5
+ * value's lower half when there is no caption). Layout uses this to keep the
6
+ * whole readout inside the chart.
7
+ */
8
+ export declare function gaugeReadoutExtent(fontSize: number, captionLines: number): {
9
+ above: number;
10
+ below: number;
11
+ };
2
12
  /**
3
13
  * Readout font size: `max(16, radius * 0.3)`, shrunk until the text's
4
14
  * estimated width fits across the hub, so a long string ("140 / 200") stays
@@ -6,7 +16,7 @@ import * as React from "react";
6
16
  */
7
17
  export declare function gaugeReadoutFontSize(text: string, radius: number, innerRadius?: number): number;
8
18
  /** Portable default center readout, shared by React and static GaugeChart. */
9
- export declare function GaugeReadout({ value, min, max, radius, innerRadius, showScaleLabels, label }: {
19
+ export declare function GaugeReadout({ value, min, max, radius, innerRadius, showScaleLabels, label, offsetY }: {
10
20
  value: string;
11
21
  min: number;
12
22
  max: number;
@@ -16,8 +26,27 @@ export declare function GaugeReadout({ value, min, max, radius, innerRadius, sho
16
26
  showScaleLabels: boolean;
17
27
  /** Caption beneath the value (and beneath the scale range when shown). */
18
28
  label?: React.ReactNode;
29
+ /** Value center line relative to the arc center (negative moves it up). */
30
+ offsetY?: number;
19
31
  }): React.JSX.Element;
20
32
  export type GaugeCenterContent = React.ReactNode | ((value: number, min: number, max: number) => React.ReactNode);
33
+ /**
34
+ * What the gauge center shows, resolved before layout so the arc can be sized
35
+ * around a text readout: a `readout` (default value, or string/number
36
+ * `centerContent`) whose lines are known, or an authored React `node` whose
37
+ * size is not.
38
+ */
39
+ export type GaugeCenter = {
40
+ readout: {
41
+ value: string;
42
+ showScaleLabels: boolean;
43
+ label?: string;
44
+ };
45
+ } | {
46
+ node: React.ReactNode;
47
+ } | null;
48
+ /** Caption lines a center readout draws beneath its value. */
49
+ export declare function gaugeCenterCaptionLines(center: GaugeCenter): number;
21
50
  /**
22
51
  * The gauge center for React and static GaugeChart: authored `centerContent`
23
52
  * (a function receives the value and range), else the default readout, which
@@ -25,15 +54,21 @@ export type GaugeCenterContent = React.ReactNode | ((value: number, min: number,
25
54
  * default readout, fitted to the hub, so they stay portable in static SVG;
26
55
  * other React content passes through unchanged.
27
56
  */
28
- export declare function resolveGaugeCenterContent({ centerContent, centerLabel, value, min, max, radius, innerRadius, showScaleLabels, valueFormat, compact }: {
57
+ export declare function describeGaugeCenter({ centerContent, centerLabel, value, min, max, showScaleLabels, valueFormat, compact }: {
29
58
  centerContent?: GaugeCenterContent;
30
59
  centerLabel?: string;
31
60
  value: number;
32
61
  min: number;
33
62
  max: number;
34
- radius: number;
35
- innerRadius: number;
36
63
  showScaleLabels: boolean;
37
64
  valueFormat?: (value: number) => string;
38
65
  compact: boolean;
66
+ }): GaugeCenter;
67
+ /** Render a described gauge center at the radius and offset the layout chose. */
68
+ export declare function renderGaugeCenter(center: GaugeCenter, { min, max, radius, innerRadius, offsetY }: {
69
+ min: number;
70
+ max: number;
71
+ radius: number;
72
+ innerRadius: number;
73
+ offsetY?: number;
39
74
  }): React.ReactNode | null;
@@ -25,7 +25,8 @@
25
25
  * explicit `tickValues` (e.g. `[1, 10, 100, 1000]`) — those bypass
26
26
  * `axisExtent` entirely.
27
27
  */
28
- export type AxisExtentMode = "nice" | "exact";
28
+ /** "rounded" also widens open value-domain ends during scale construction. */
29
+ export type AxisExtentMode = "nice" | "exact" | "rounded";
29
30
  /** A d3-style continuous scale (linear, time, log) — the bit we use.
30
31
  * The `domain()` return type stays as `number[]` / `Date[]` rather
31
32
  * than a strict 2-tuple because that's what d3-scale's own types
@@ -69,8 +69,8 @@ export declare function resolveChartMode(mode: ChartMode | undefined, userProps:
69
69
  height?: number;
70
70
  }): ChartModeResult;
71
71
  /**
72
- * Axis-free charts keep their established 10px regular-mode inset while
72
+ * Axis-free charts use a small inset (or layout-specific label padding) while
73
73
  * adopting the shared context/sparkline margins. Reading `resolved` here is
74
74
  * important: responsive rules may have changed the effective chart mode.
75
75
  */
76
- export declare function resolveAxisFreeMarginDefaults(resolved: Pick<ChartModeResult, "compactMode" | "marginDefaults">): ChartModeResult["marginDefaults"];
76
+ export declare function resolveAxisFreeMarginDefaults(resolved: Pick<ChartModeResult, "compactMode" | "marginDefaults">, defaults?: ChartModeResult["marginDefaults"]): ChartModeResult["marginDefaults"];