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
@@ -482,6 +482,8 @@ export interface Changeset<T = Datum> {
482
482
  bounded: boolean;
483
483
  /** Hint: total dataset size when progressively chunking bounded data */
484
484
  totalSize?: number;
485
+ /** Append another chunk of the current bounded snapshot, without applying live retention. */
486
+ boundedAppend?: boolean;
485
487
  /** When true on a bounded changeset, the store replaces the buffer
486
488
  * contents but does NOT clear its category insertion-order memory
487
489
  * and marks itself as having received streaming-sourced data. Used
@@ -695,6 +697,8 @@ export interface StreamXYFrameProps<T = Datum> extends StreamSemanticInteraction
695
697
  arrowOfTime?: ArrowOfTime;
696
698
  windowMode?: WindowMode;
697
699
  windowSize?: number;
700
+ /** Maximum retained live rows in growing mode (default 100,000). */
701
+ maxCapacity?: number;
698
702
  /**
699
703
  * Ring-buffer capacity. Alias for `windowSize` — prefer this name when
700
704
  * talking to a Kafka Streams / Flink audience, where "window" means the
@@ -742,6 +746,8 @@ export interface StreamXYFrameProps<T = Datum> extends StreamSemanticInteraction
742
746
  };
743
747
  areaStyle?: (d: T) => Style;
744
748
  barStyle?: BarStyle;
749
+ /** Starting cumulative balance for waterfall charts. @default 0 */
750
+ initialValue?: number;
745
751
  waterfallStyle?: WaterfallStyle;
746
752
  swarmStyle?: SwarmStyle;
747
753
  barColors?: Record<string, string>;
@@ -750,7 +756,7 @@ export interface StreamXYFrameProps<T = Datum> extends StreamSemanticInteraction
750
756
  /**
751
757
  * Per-axis config array. See `XYFrameAxisConfig` for the full set of
752
758
  * fields — covers `tickValues`, `tickFormat`, `tickAnchor`,
753
- * `landmarkTicks`, `autoRotate`, `gridStyle`, `includeMax`,
759
+ * `landmarkTicks`, `autoRotate`, `gridStyle`, `includeMin`, `includeMax`,
754
760
  * `baseline`, `jaggedBase`, `label`, and `ticks`.
755
761
  */
756
762
  axes?: XYFrameAxisConfig[];
@@ -765,7 +771,9 @@ export interface StreamXYFrameProps<T = Datum> extends StreamSemanticInteraction
765
771
  * reaching the exact data min/max. `"exact"` pins the first
766
772
  * and last tick to the data domain and spaces intermediate
767
773
  * ticks equidistantly. Applies to both x and y axes unless an entry in
768
- * `axes` supplies its own `extent` override. */
774
+ * `axes` supplies its own `extent` override. `"rounded"` widens open y
775
+ * bounds after padding to the tick step for the final plot height; pinned
776
+ * ends and explicit tick values stay fixed. The x domain is unchanged. */
769
777
  axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
770
778
  tickFormatTime?: (value: number) => string;
771
779
  tickFormatValue?: (value: number) => string;
@@ -154,8 +154,9 @@ export interface UseFrameResult {
154
154
  * mount calls this from a layout effect so the first displayed frame
155
155
  * already includes the scene and its SVG overlay. */
156
156
  flushRender: () => void;
157
- /** Frame assigns its hover handler closure here. */
158
- hoverHandlerRef: React.MutableRefObject<(coords: HoverPointerCoords) => void>;
157
+ /** Frame assigns its hover handler closure here. Refresh updates presentation
158
+ * after a scene rebuild without replaying pointer callbacks. */
159
+ hoverHandlerRef: React.MutableRefObject<(coords: HoverPointerCoords, refresh?: boolean) => void>;
159
160
  /** Frame assigns its pointer-leave closure here. */
160
161
  hoverLeaveRef: React.MutableRefObject<() => void>;
161
162
  /** Stable callback to attach to canvas's onPointerMove (or onMouseMove).
@@ -166,10 +167,12 @@ export interface UseFrameResult {
166
167
  pointerType?: string;
167
168
  }) => void;
168
169
  /** Process a queued move before a newer synchronous activation changes state. */
169
- flushPointerMove: () => void;
170
+ flushPointerMove: (event?: Pick<React.MouseEvent, "clientX" | "clientY" | "nativeEvent">) => void;
170
171
  /** Stable callback to attach to canvas's onPointerLeave (or onMouseLeave).
171
172
  * Cancels any pending hover rAF and invokes hoverLeaveRef. */
172
- onPointerLeave: () => void;
173
+ onPointerLeave: (event?: {
174
+ type: string;
175
+ }) => void;
173
176
  /** Last pointer position over the frame. Frames use this to refresh
174
177
  * geometry-derived presentation while marks animate under a stationary
175
178
  * pointer; reading/writing the ref never schedules work by itself. */
@@ -1,8 +1,5 @@
1
1
  export { addMqlListener } from "./mediaQuery";
2
- /**
3
- * SSR-safe hook that returns true when the user prefers reduced motion.
4
- * Initializes from matchMedia synchronously to avoid a flash of animation.
5
- */
2
+ /** SSR-safe reduced-motion preference, initialized before the first paint. */
6
3
  export declare function useReducedMotion(): boolean;
7
4
  /**
8
5
  * SSR-safe hook that returns true when forced-colors or high-contrast mode is active.
@@ -1,15 +1,5 @@
1
- import { type MutableRefObject, type Ref } from "react";
2
- import type { DataSourceAdapter } from "./DataSourceAdapter";
1
+ import { type Ref } from "react";
3
2
  import type { OrdinalPipelineStore } from "./OrdinalPipelineStore";
4
- import type { HoverData, StreamOrdinalFrameHandle } from "./ordinalTypes";
5
- interface OrdinalFrameHandleOptions {
6
- storeRef: MutableRefObject<OrdinalPipelineStore | null>;
7
- adapterRef: MutableRefObject<DataSourceAdapter | null>;
8
- dirtyRef: MutableRefObject<boolean>;
9
- scheduleRender: () => void;
10
- hoverRef: MutableRefObject<HoverData | null>;
11
- setHoverPoint: (hover: HoverData | null) => void;
12
- }
13
- /** Keep imperative data mutations separate from the frame's render lifecycle. */
14
- export declare function useOrdinalFrameHandle(ref: Ref<StreamOrdinalFrameHandle>, { storeRef, adapterRef, dirtyRef, scheduleRender, hoverRef, setHoverPoint }: OrdinalFrameHandleOptions): void;
15
- export {};
3
+ import type { StreamOrdinalFrameHandle } from "./ordinalTypes";
4
+ import { type StreamingHandleOptions } from "./useStreamingDataHandle";
5
+ export declare function useOrdinalFrameHandle(ref: Ref<StreamOrdinalFrameHandle>, options: StreamingHandleOptions<OrdinalPipelineStore>): void;
@@ -1,9 +1,11 @@
1
1
  import type { StalenessConfig } from "./types";
2
2
  interface StoreWithIngestTime {
3
- lastIngestTime: number;
3
+ activity: {
4
+ elapsed(): number;
5
+ };
4
6
  }
5
7
  /**
6
- * Shared hook that polls a store's `lastIngestTime` on a 1-second interval
8
+ * Shared hook that polls a store's wall-clock activity on a 1-second interval
7
9
  * and manages staleness state. When the resolved staleness changes it sets
8
10
  * `dirtyRef.current = true` and calls `scheduleRender()` so the canvas
9
11
  * repaints with the appropriate dimming.
@@ -17,5 +19,5 @@ interface StoreWithIngestTime {
17
19
  * declared. The `isStale` / `setIsStale` state must live in the caller
18
20
  * so that the `useState` call order stays unchanged.
19
21
  */
20
- export declare function useStalenessCheck(staleness: StalenessConfig | undefined, storeRef: React.RefObject<StoreWithIngestTime | null>, dirtyRef: React.MutableRefObject<boolean>, scheduleRender: () => void, now: () => number, isStale: boolean, setIsStale: (stale: boolean) => void): void;
22
+ export declare function useStalenessCheck(staleness: StalenessConfig | undefined, storeRef: React.RefObject<StoreWithIngestTime | null>, dirtyRef: React.MutableRefObject<boolean>, scheduleRender: () => void, isStale: boolean, setIsStale: (stale: boolean) => void): void;
21
23
  export {};
@@ -0,0 +1,24 @@
1
+ import { type MutableRefObject } from "react";
2
+ import type { Datum } from "../charts/shared/datumTypes";
3
+ import type { DataSourceAdapter } from "./DataSourceAdapter";
4
+ import type { PipelineStore } from "./PipelineStore";
5
+ import type { OrdinalPipelineStore } from "./OrdinalPipelineStore";
6
+ export interface StreamingHandleOptions<S> {
7
+ storeRef: MutableRefObject<S | null>;
8
+ adapterRef: MutableRefObject<DataSourceAdapter | null>;
9
+ dirtyRef: MutableRefObject<boolean>;
10
+ scheduleRender: () => void;
11
+ invalidateInteraction: (resetFocus?: boolean) => void;
12
+ }
13
+ /** Both frame families commit mutations and dismiss stale interaction together. */
14
+ export declare function useStreamingDataHandle<S extends PipelineStore | OrdinalPipelineStore>({ storeRef, adapterRef, dirtyRef, scheduleRender, invalidateInteraction }: StreamingHandleOptions<S>): {
15
+ push: (datum: Datum) => void | undefined;
16
+ pushMany: (data: Datum[]) => void | undefined;
17
+ remove: (id: string | string[]) => Datum[];
18
+ update: (id: string | string[], updater: (d: Datum) => Datum) => Datum[];
19
+ clear: () => void;
20
+ getData: () => Datum[];
21
+ getScales: () => S["scales"];
22
+ getCustomLayout: () => S["lastCustomLayoutResult"];
23
+ getLayoutFailure: () => import("./customLayoutFailure").CustomLayoutFailureDiagnostic | null;
24
+ };
@@ -1,15 +1,5 @@
1
- import { type MutableRefObject, type Ref } from "react";
2
- import type { DataSourceAdapter } from "./DataSourceAdapter";
1
+ import { type Ref } from "react";
3
2
  import type { PipelineStore } from "./PipelineStore";
4
- import type { HoverData, StreamXYFrameHandle } from "./types";
5
- interface XYFrameHandleOptions {
6
- storeRef: MutableRefObject<PipelineStore | null>;
7
- adapterRef: MutableRefObject<DataSourceAdapter | null>;
8
- dirtyRef: MutableRefObject<boolean>;
9
- scheduleRender: () => void;
10
- hoverRef: MutableRefObject<HoverData | null>;
11
- setHoverPoint: (hover: HoverData | null) => void;
12
- }
13
- /** Keep imperative data mutations separate from the frame's render lifecycle. */
14
- export declare function useXYFrameHandle(ref: Ref<StreamXYFrameHandle>, { storeRef, adapterRef, dirtyRef, scheduleRender, hoverRef, setHoverPoint }: XYFrameHandleOptions): void;
15
- export {};
3
+ import type { StreamXYFrameHandle } from "./types";
4
+ import { type StreamingHandleOptions } from "./useStreamingDataHandle";
5
+ export declare function useXYFrameHandle(ref: Ref<StreamXYFrameHandle>, options: StreamingHandleOptions<PipelineStore>): void;
@@ -1,10 +1,39 @@
1
+ export declare function formatDateMonthDay(value: number | Date | string): string;
1
2
  /**
2
- * Auto date tick formatting for StreamXYFrame time scales.
3
- * UTC getters keep SSR and client labels identical across timezones.
3
+ * Whether a numeric time domain reads as epoch milliseconds. Streaming time
4
+ * axes fed `Date.now()` numbers use this to get clock labels instead of raw
5
+ * 13-digit integers; tick counters and seconds stay far below the threshold.
4
6
  */
5
- export declare function formatDateMonthDay(value: number | Date | string): string;
7
+ export declare function isEpochMsDomain(domain: readonly unknown[]): boolean;
8
+ /**
9
+ * The automatic x-axis formatter for a frame without its own: calendar labels
10
+ * for Date/date-string x values, and for streaming time axes whose numeric
11
+ * domain is epoch milliseconds. Shared by the live frame and static SVG.
12
+ */
13
+ export declare function resolveAutoDateTickFormatter(options: {
14
+ xIsDate: boolean;
15
+ streaming: boolean;
16
+ domain: readonly (number | Date)[];
17
+ }): ReturnType<typeof makeDateTickFormatter> | undefined;
18
+ /**
19
+ * Automatic x labels for a frame with no explicit formatter: date labels for
20
+ * a date axis or a streaming epoch-ms axis, none for heatmap band axes.
21
+ */
22
+ export declare function resolveFrameAutoXFormat(store: {
23
+ xIsDate: boolean;
24
+ } | null | undefined, scales: {
25
+ x: {
26
+ domain(): readonly (number | Date)[];
27
+ };
28
+ } | null | undefined, streaming: boolean): ReturnType<typeof makeDateTickFormatter> | undefined;
29
+ /** Whether `format` labels epoch-ms values plotted on a linear scale. */
30
+ export declare function isEpochTickFormatter(format: unknown): boolean;
6
31
  /**
7
32
  * Build a tick formatter for a numeric time domain (ms since epoch).
8
33
  * Span-based resolution: milliseconds → seconds → hours → day-month → month-year → year.
34
+ * When the axis passes its tick values (horizontal axes do), sub-day labels
35
+ * carry exactly the precision those ticks need: whole-second ticks drop
36
+ * `.000`, and off-minute or sub-second ticks gain seconds / milliseconds so
37
+ * neighbouring labels never collapse to the same text.
9
38
  */
10
- export declare function makeDateTickFormatter(domain: [number, number]): (v: number | Date | string) => string;
39
+ export declare function makeDateTickFormatter(domain: [number, number]): (v: number | Date | string, index?: number, values?: readonly number[]) => string;
@@ -63,6 +63,8 @@ export interface XYFrameAxisConfig {
63
63
  grid?: boolean;
64
64
  /** Always include the domain max as a tick, even if d3 omits it. */
65
65
  includeMax?: boolean;
66
+ /** Always include domain[0] as a tick, even if d3 omits it. */
67
+ includeMin?: boolean;
66
68
  /** Auto-rotate labels 45° when horizontal spacing is too tight. */
67
69
  autoRotate?: boolean;
68
70
  /** Highlight ticks at time boundaries (new month, year, etc.) with
@@ -5,6 +5,7 @@ import type { XYSceneContext } from "../xySceneBuilders/types";
5
5
  import type { BarSceneResult } from "../xySceneBuilders/barScene";
6
6
  import type { HoverData } from "../../realtime/types";
7
7
  import type { PipelineStore } from "../PipelineStore";
8
+ import type { LegendValue } from "../../types/legendTypes";
8
9
  /**
9
10
  * Register XY scene + canvas plugins with a value import of the plugin.
10
11
  * `package.json` has `"sideEffects": false`, so a bare
@@ -24,11 +25,17 @@ export type XYMultiHover = (hover: HoverData, store: Pick<PipelineStore, "scene"
24
25
  hasHit: boolean;
25
26
  fallbackColor: string;
26
27
  }) => HoverData;
28
+ /**
29
+ * Chart-specific legend resolution against the built scene, applied by every
30
+ * renderer before it draws the legend (for example a heatmap's cell domain).
31
+ */
32
+ export type XYSceneLegendResolver = (legend: LegendValue | undefined, scene: readonly SceneNode[], config: XYSceneContext["config"]) => LegendValue | undefined;
27
33
  export interface XYChartPlugin {
28
34
  chartType: StreamChartType;
29
35
  buildScene: XYSceneBuilder;
30
36
  canvasRenderers: StreamRendererFn[];
31
37
  multiHover?: XYMultiHover;
38
+ resolveLegend?: XYSceneLegendResolver;
32
39
  }
33
40
  export declare function registerXYPlugin(plugin: XYChartPlugin): void;
34
41
  /** Test-only: drop every plugin so HOC registration can be asserted in isolation. */
@@ -1,4 +1,13 @@
1
1
  import type { Datum } from "../../charts/shared/datumTypes";
2
- import type { HeatcellSceneNode, StreamLayout } from "../types";
3
- import type { XYSceneContext } from "./types";
2
+ import type { HeatcellSceneNode, SceneNode, StreamLayout } from "../types";
3
+ import type { XYSceneConfig, XYSceneContext } from "./types";
4
+ import { type LegendValue } from "../../types/legendTypes";
5
+ type HeatmapColorConfig = Pick<XYSceneConfig, "colorScheme" | "heatmapColorScale" | "themeSequential">;
6
+ /**
7
+ * Give a gradient legend the domain and ramp of the drawn cells, so binned,
8
+ * aggregated, and live heatmaps label the values they colour by. Every
9
+ * renderer applies this to its scene; without heatcells the legend is kept.
10
+ */
11
+ export declare function resolveHeatmapSceneLegend(legend: LegendValue | undefined, scene: readonly SceneNode[], config: HeatmapColorConfig): LegendValue | undefined;
4
12
  export declare function buildHeatmapScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): HeatcellSceneNode[];
13
+ export {};
@@ -13,6 +13,8 @@ import type { SymbolName } from "../symbolPath";
13
13
  import type { ResolvedRibbon } from "./ribbonScene";
14
14
  import type { GradientConfig } from "../../charts/shared/gradient";
15
15
  export interface XYSceneContext {
16
+ /** Resolved initial balance plus evicted deltas. */
17
+ waterfallBaseline?: number;
16
18
  scales: StreamScales;
17
19
  config: XYSceneConfig;
18
20
  getX: (d: Datum) => number;
@@ -103,6 +105,8 @@ export interface XYSceneConfig {
103
105
  /** Theme diverging scheme name — fallback when colorScheme is not set. */
104
106
  themeDiverging?: string;
105
107
  swarmStyle?: SwarmStyle;
108
+ /** Starting cumulative balance for waterfall charts. @default 0 */
109
+ initialValue?: number;
106
110
  waterfallStyle?: WaterfallStyle;
107
111
  candlestickStyle?: CandlestickStyle;
108
112
  /** True when candlestick is in range/dumbbell mode (no open/close accessors provided) */
@@ -58,7 +58,11 @@ export interface LegendLayout {
58
58
  itemGap?: number;
59
59
  /** Vertical row height for stacked legend items in pixels */
60
60
  rowHeight?: number;
61
- /** Override the alignment width used for top/bottom legends */
61
+ /**
62
+ * Override the alignment width used for top/bottom legends. For left/right
63
+ * legends, the widest box the legend may reserve (default: 30% of the chart
64
+ * width, never below 100px); longer labels truncate with an ellipsis.
65
+ */
62
66
  maxWidth?: number;
63
67
  /**
64
68
  * Space between a left/right legend and the outer SVG edge. The default is
@@ -105,4 +109,11 @@ export interface LegendProps {
105
109
  orientation?: string;
106
110
  position?: "left" | "right";
107
111
  legendLayout?: LegendLayout;
112
+ /**
113
+ * Height available to the legend. When set, a vertical legend treats
114
+ * `width` as the most it may use (items wrap into columns, labels truncate)
115
+ * and a horizontal legend stops adding rows; items that still do not fit
116
+ * are summarized as "+N more".
117
+ */
118
+ maxHeight?: number;
108
119
  }