semiotic 3.13.2 → 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 (214) hide show
  1. package/README.md +47 -46
  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-62UTMRQE.min.js +1 -0
  18. package/dist/c-6QV6F3U7.min.js +1 -0
  19. package/dist/c-7S46KBYD.min.js +2 -0
  20. package/dist/c-AJSS332Z.min.js +2 -0
  21. package/dist/c-B3X2IJRQ.min.js +1 -0
  22. package/dist/c-BLLDBVFK.min.js +38 -0
  23. package/dist/c-C7TT4J7K.min.js +1 -0
  24. package/dist/{c-ZMB3VTD4.min.js → c-CJ5GA7DM.min.js} +1 -1
  25. package/dist/c-D7YDFHLY.min.js +1 -0
  26. package/dist/{c-BR2TOCUN.min.js → c-DMDFJQU4.min.js} +1 -1
  27. package/dist/{c-JDU4Y4IW.min.js → c-FRVHZIGR.min.js} +1 -1
  28. package/dist/{c-MSZ3ZDAP.min.js → c-HAZCVHI7.min.js} +1 -1
  29. package/dist/c-HN5U72U7.min.js +1 -0
  30. package/dist/c-JA5F7ITS.min.js +1 -0
  31. package/dist/{c-ISHYKYII.min.js → c-JVZRD4GL.min.js} +1 -1
  32. package/dist/{c-OOR2LN4A.min.js → c-KJGJEOSV.min.js} +1 -1
  33. package/dist/c-M2TPZE7P.min.js +1 -0
  34. package/dist/c-OA6RJZ7S.min.js +1 -0
  35. package/dist/c-OBBSIOYU.min.js +1 -0
  36. package/dist/{c-SQQZPFVY.min.js → c-QPHM7AWW.min.js} +1 -1
  37. package/dist/{c-HOMJ3C6B.min.js → c-QSEAAHEU.min.js} +1 -1
  38. package/dist/c-RQWI623R.min.js +1 -0
  39. package/dist/{c-WFSEQ2XG.min.js → c-RWFADOKS.min.js} +1 -1
  40. package/dist/{c-SDGGMIYI.min.js → c-TJGC5JEM.min.js} +1 -1
  41. package/dist/{c-H5THWQI4.min.js → c-TOXWQRXS.min.js} +3 -3
  42. package/dist/c-VBDWHTC7.min.js +1 -0
  43. package/dist/c-VBIPDCE7.min.js +1 -0
  44. package/dist/c-WTNRBWZZ.min.js +51 -0
  45. package/dist/{c-3GIPT46Z.min.js → c-XG4LL2VI.min.js} +1 -1
  46. package/dist/c-XPNBS3W2.min.js +1 -0
  47. package/dist/c-XT3G3YWU.min.js +1 -0
  48. package/dist/c-ZP6O6UHV.min.js +1 -0
  49. package/dist/c-ZVL7ULNH.min.js +1 -0
  50. package/dist/components/ChartErrorBoundary.d.ts +5 -1
  51. package/dist/components/ai/intentWeights.d.ts +22 -0
  52. package/dist/components/ai/streamSchema.d.ts +98 -0
  53. package/dist/components/ai/streamingTypes.d.ts +27 -4
  54. package/dist/components/ai/suggestCharts.d.ts +10 -2
  55. package/dist/components/ai/suggestStreamCharts.d.ts +60 -13
  56. package/dist/components/ai/suggestStreamDashboard.d.ts +9 -1
  57. package/dist/components/charts/network/processSankey/frameMargins.d.ts +1 -1
  58. package/dist/components/charts/network/processSankey/labelPlacement.d.ts +1 -1
  59. package/dist/components/charts/physics/physicsHocUtils.d.ts +1 -1
  60. package/dist/components/charts/realtime/RealtimeAccumulator.d.ts +7 -0
  61. package/dist/components/charts/realtime/RealtimeHeatmap.d.ts +9 -2
  62. package/dist/components/charts/realtime/RealtimeHistogram.d.ts +13 -1
  63. package/dist/components/charts/realtime/RealtimeLineChart.types.d.ts +5 -1
  64. package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts +5 -1
  65. package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts +7 -1
  66. package/dist/components/charts/realtime/TemporalHistogram.capability.d.ts +5 -3
  67. package/dist/components/charts/realtime/aggregate.d.ts +11 -12
  68. package/dist/components/charts/realtime/defaultRealtimeTooltip.d.ts +9 -0
  69. package/dist/components/charts/realtime/eventTime.d.ts +7 -1
  70. package/dist/components/charts/realtime/useRealtimeLineIngestion.d.ts +13 -0
  71. package/dist/components/charts/shared/ChartError.d.ts +4 -6
  72. package/dist/components/charts/shared/GaugeReadout.d.ts +39 -4
  73. package/dist/components/charts/shared/axisExtent.d.ts +2 -1
  74. package/dist/components/charts/shared/chartMode.d.ts +2 -2
  75. package/dist/components/charts/shared/gaugeLayout.d.ts +69 -0
  76. package/dist/components/charts/shared/types.d.ts +3 -0
  77. package/dist/components/charts/shared/useNetworkChartSetup.d.ts +3 -0
  78. package/dist/components/charts/shared/useStreamStatus.d.ts +2 -2
  79. package/dist/components/charts/shared/withChartErrorBoundary.d.ts +14 -0
  80. package/dist/components/charts/xy/Scatterplot.streamCapability.d.ts +2 -0
  81. package/dist/components/charts/xy/WaterfallChart.d.ts +2 -0
  82. package/dist/components/charts/xy/WaterfallIndex.d.ts +12 -0
  83. package/dist/components/charts/xy/lineGapStrategy.d.ts +15 -3
  84. package/dist/components/legendGeometry.d.ts +148 -0
  85. package/dist/components/legendLayout.d.ts +20 -38
  86. package/dist/components/realtime/ReorderBuffer.d.ts +14 -0
  87. package/dist/components/realtime/SlidingExtent.d.ts +18 -0
  88. package/dist/components/realtime/WindowAccumulator.d.ts +5 -1
  89. package/dist/components/realtime/renderers/types.d.ts +1 -0
  90. package/dist/components/realtime/renderers/waterfallRenderer.d.ts +1 -1
  91. package/dist/components/recipes/compositional/edgeRouting.d.ts +9 -0
  92. package/dist/components/recipes/compositional/metrics.d.ts +2 -2
  93. package/dist/components/recipes/compositional/projection.d.ts +3 -1
  94. package/dist/components/recipes/compositional/routing.d.ts +3 -1
  95. package/dist/components/recipes/compositional/testFixtures.d.ts +4 -0
  96. package/dist/components/recipes/compositional/topology.d.ts +2 -0
  97. package/dist/components/recipes/compositional/types.d.ts +10 -1
  98. package/dist/components/recipes/compositional/useCompositionalInterfaces.d.ts +20 -0
  99. package/dist/components/semiotic-ai-core.d.ts +3 -2
  100. package/dist/components/semiotic-ai-stream.d.ts +3 -2
  101. package/dist/components/semiotic-recipes-react.d.ts +2 -0
  102. package/dist/components/semiotic-utils-core.d.ts +2 -0
  103. package/dist/components/server/serverChartConfigHeatmap.d.ts +13 -0
  104. package/dist/components/server/staticLegend.d.ts +5 -0
  105. package/dist/components/server/staticLegendText.d.ts +13 -0
  106. package/dist/components/server/staticSVGChrome.d.ts +2 -2
  107. package/dist/components/stream/DataSourceAdapter.d.ts +15 -62
  108. package/dist/components/stream/FrameRuntime.d.ts +3 -0
  109. package/dist/components/stream/GeoPipelineStore.d.ts +2 -0
  110. package/dist/components/stream/IngestActivity.d.ts +9 -0
  111. package/dist/components/stream/NetworkPipelineStore.d.ts +3 -1
  112. package/dist/components/stream/OrdinalPipelineStore.d.ts +5 -2
  113. package/dist/components/stream/OrdinalSVGOverlay.d.ts +1 -1
  114. package/dist/components/stream/PipelineStore.d.ts +8 -3
  115. package/dist/components/stream/accessibleDataRows.d.ts +1 -0
  116. package/dist/components/stream/axisTickUtils.d.ts +25 -5
  117. package/dist/components/stream/frameDefaultMargins.d.ts +26 -4
  118. package/dist/components/stream/frameKeyboardNavigation.d.ts +8 -1
  119. package/dist/components/stream/geoTypes.d.ts +2 -0
  120. package/dist/components/stream/graphKeyboardNavigation.d.ts +4 -2
  121. package/dist/components/stream/hitTestUtils.d.ts +7 -0
  122. package/dist/components/stream/keyboardNav.d.ts +3 -1
  123. package/dist/components/stream/navigationGraph.d.ts +10 -3
  124. package/dist/components/stream/networkFrameKeyboardNavigation.d.ts +2 -0
  125. package/dist/components/stream/networkNavGroups.d.ts +3 -0
  126. package/dist/components/stream/networkPipelineConfig.d.ts +1 -0
  127. package/dist/components/stream/networkSceneTypes.d.ts +10 -0
  128. package/dist/components/stream/networkSpatialNavigation.d.ts +3 -0
  129. package/dist/components/stream/networkTypes.d.ts +2 -0
  130. package/dist/components/stream/ordinalAxisTicks.d.ts +27 -0
  131. package/dist/components/stream/ordinalSceneBuilders/pieScene.d.ts +10 -0
  132. package/dist/components/stream/ordinalSceneBuilders/types.d.ts +2 -0
  133. package/dist/components/stream/ordinalTypes.d.ts +11 -2
  134. package/dist/components/stream/pipelineBufferUtils.d.ts +9 -0
  135. package/dist/components/stream/pipelineConfig.d.ts +7 -0
  136. package/dist/components/stream/pipelineDomainResolution.d.ts +3 -2
  137. package/dist/components/stream/roundScaleDomain.d.ts +9 -0
  138. package/dist/components/stream/stalenessBands.d.ts +1 -1
  139. package/dist/components/stream/svgOverlayUtils.d.ts +12 -0
  140. package/dist/components/stream/types.d.ts +10 -2
  141. package/dist/components/stream/useFrame.d.ts +7 -4
  142. package/dist/components/stream/useOrdinalFrameHandle.d.ts +4 -14
  143. package/dist/components/stream/useStalenessCheck.d.ts +5 -3
  144. package/dist/components/stream/useStreamingDataHandle.d.ts +24 -0
  145. package/dist/components/stream/useXYFrameHandle.d.ts +4 -14
  146. package/dist/components/stream/xyDateTicks.d.ts +33 -4
  147. package/dist/components/stream/xyFrameAxisTypes.d.ts +2 -0
  148. package/dist/components/stream/xyPlugins/registry.d.ts +7 -0
  149. package/dist/components/stream/xySceneBuilders/heatmapScene.d.ts +11 -2
  150. package/dist/components/stream/xySceneBuilders/types.d.ts +4 -0
  151. package/dist/components/types/legendTypes.d.ts +12 -1
  152. package/dist/geo.min.js +155 -152
  153. package/dist/geo.module.min.js +1 -1
  154. package/dist/network.module.min.js +1 -1
  155. package/dist/ordinal.module.min.js +1 -1
  156. package/dist/physics.module.min.js +1 -1
  157. package/dist/processSankeyLayoutWorker.js +1 -1
  158. package/dist/semiotic-ai-core.d.ts +3 -2
  159. package/dist/semiotic-ai-core.min.js +5 -5
  160. package/dist/semiotic-ai-core.module.min.js +4 -4
  161. package/dist/semiotic-ai.module.min.js +2 -2
  162. package/dist/semiotic-artifact.min.js +6 -6
  163. package/dist/semiotic-artifact.module.min.js +5 -5
  164. package/dist/semiotic-atlas-selection.module.min.js +1 -1
  165. package/dist/semiotic-atlas.module.min.js +1 -1
  166. package/dist/semiotic-client-cjs-shared.min.js +1022 -1018
  167. package/dist/semiotic-client-compositional.module.min.js +1 -1
  168. package/dist/semiotic-client-shared.module.min.js +1 -1
  169. package/dist/semiotic-experimental-auxiliary.module.min.js +1 -1
  170. package/dist/semiotic-experimental-node-auxiliary.module.min.js +1 -1
  171. package/dist/semiotic-line.module.min.js +1 -1
  172. package/dist/semiotic-realtime-core.module.min.js +1 -1
  173. package/dist/semiotic-realtime-react.module.min.js +1 -1
  174. package/dist/semiotic-recipes-core-cjs-base.min.js +101 -101
  175. package/dist/semiotic-recipes-core.module.min.js +1 -1
  176. package/dist/semiotic-recipes-react.d.ts +2 -0
  177. package/dist/semiotic-recipes-react.min.js +8 -8
  178. package/dist/semiotic-server-edge-node.module.min.js +3 -3
  179. package/dist/semiotic-server-edge.min.js +399 -394
  180. package/dist/semiotic-server-edge.module.min.js +3 -3
  181. package/dist/semiotic-server-node.min.js +399 -394
  182. package/dist/semiotic-utils-core.d.ts +2 -0
  183. package/dist/semiotic-utils-core.min.js +11 -11
  184. package/dist/semiotic-utils-core.module.min.js +3 -3
  185. package/dist/semiotic-value.module.min.js +1 -1
  186. package/dist/semiotic.module.min.js +1 -1
  187. package/dist/server.min.js +399 -394
  188. package/dist/server.module.min.js +3 -3
  189. package/dist/xy.module.min.js +1 -1
  190. package/package.json +11 -11
  191. package/dist/c-27SDQN3J.min.js +0 -1
  192. package/dist/c-2N7IU2NY.min.js +0 -1
  193. package/dist/c-4EUQNA7N.min.js +0 -2
  194. package/dist/c-5EPR4KFB.min.js +0 -1
  195. package/dist/c-5KZ3NO6X.min.js +0 -1
  196. package/dist/c-7UN2WUMI.min.js +0 -1
  197. package/dist/c-BRBTXINY.min.js +0 -1
  198. package/dist/c-C3Z7ZRAA.min.js +0 -1
  199. package/dist/c-C4WRRUZ5.min.js +0 -1
  200. package/dist/c-CXDAWBOW.min.js +0 -1
  201. package/dist/c-DJ6DT5BL.min.js +0 -51
  202. package/dist/c-DNBFFE3P.min.js +0 -1
  203. package/dist/c-HR5AH3MA.min.js +0 -1
  204. package/dist/c-HTL37JCD.min.js +0 -1
  205. package/dist/c-JS2D7A2P.min.js +0 -1
  206. package/dist/c-L6OT4OVA.min.js +0 -1
  207. package/dist/c-NB2UEX5C.min.js +0 -1
  208. package/dist/c-OU7A3IUL.min.js +0 -1
  209. package/dist/c-PNLTF6YG.min.js +0 -37
  210. package/dist/c-QVKOXC3S.min.js +0 -1
  211. package/dist/c-SIQVOV6A.min.js +0 -1
  212. package/dist/c-TBMFC5CR.min.js +0 -1
  213. package/dist/c-XF5ILLBG.min.js +0 -1
  214. package/dist/c-YQHGEETR.min.js +0 -2
@@ -6,6 +6,9 @@ export interface NavPoint {
6
6
  datum: Datum | null;
7
7
  /** Logical identity for aggregates whose datum is rebuilt during layout. */
8
8
  semanticKey?: string;
9
+ /** Network scene identity and optional authored navigation parent. */
10
+ navId?: string;
11
+ navParentId?: string;
9
12
  /** Shape hint for focus ring rendering */
10
13
  shape?: "circle" | "rect" | "wedge" | "geoarea" | "path";
11
14
  /** Width of rect-shaped elements (bars, sankey nodes) */
@@ -20,6 +23,10 @@ export interface NavPoint {
20
23
  category?: string;
21
24
  /** Group identifier for graph navigation (series name, category, node id) */
22
25
  group?: string;
26
+ /**
27
+ * Rank used while extracting ordinal marks in authored reading order.
28
+ */
29
+ readingOrder?: number;
23
30
  /** Index in NavGraph.flat — set by buildNavGraph for O(1) lookup */
24
31
  _flatIndex?: number;
25
32
  /** Index within its group — set by buildNavGraph for O(1) resolvePosition */
@@ -52,10 +59,10 @@ export interface NavPosition {
52
59
  }
53
60
  /**
54
61
  * Build a navigation graph from grouped NavPoints.
55
- * Points within each group are sorted by x then y.
56
- * Groups are sorted by their first-point y position (top to bottom).
62
+ * With ordered input, points and groups retain their supplied reading order.
63
+ * Otherwise points sort by x then y and groups stay in top-to-bottom order.
57
64
  */
58
- export declare function buildNavGraph(points: NavPoint[]): NavGraph;
65
+ export declare function buildNavGraph(points: NavPoint[], ordered?: boolean): NavGraph;
59
66
  /**
60
67
  * Resolve the current NavPosition from a flat index.
61
68
  * Clamps to valid range if the index is stale (e.g. scene changed between key presses).
@@ -8,5 +8,7 @@ export declare function useNetworkKeyboardNavigation(params: KeyboardInteraction
8
8
  focusedNavPointRef: import("react").RefObject<NavPoint | null>;
9
9
  neighborIndexRef: import("react").RefObject<number>;
10
10
  onKeyDown: (event: import("react").KeyboardEvent) => void;
11
+ onBlur: (event: import("react").FocusEvent<HTMLElement>) => void;
12
+ clearFocus: () => void;
11
13
  refreshKeyboardFocus: () => void;
12
14
  };
@@ -0,0 +1,3 @@
1
+ import type { NavGraph } from "./navigationGraph";
2
+ /** Authored owner/part navigation, leaving ungrouped network behavior intact. */
3
+ export declare function groupedNetworkIndex(key: string, index: number, graph: NavGraph): number | null | undefined;
@@ -6,6 +6,7 @@ import type { SemioticTheme } from "../store/themeCore";
6
6
  import type { NetworkPipelineConfig } from "./networkTypes";
7
7
  import type { StreamNetworkFrameProps } from "./networkTypes";
8
8
  export type NetworkPipelineConfigSources = Pick<StreamNetworkFrameProps, "chartType" | "nodeIDAccessor" | "sourceAccessor" | "targetAccessor" | "valueAccessor" | "edgeIdAccessor" | "edgeIdentity" | "childrenAccessor" | "hierarchySum" | "orientation" | "nodeAlign" | "nodePaddingRatio" | "nodeWidth" | "iterations" | "forceStrength" | "padAngle" | "groupWidth" | "sortGroups" | "edgeSort" | "treeOrientation" | "edgeType" | "padding" | "paddingTop" | "nodeStyle" | "edgeStyle" | "nodeLabel" | "showLabels" | "labelMode" | "colorBy" | "colorScheme" | "edgeColorBy" | "edgeOpacity" | "colorByDepth" | "nodeSize" | "nodeSizeRange" | "decay" | "pulse" | "transition" | "staleness" | "thresholds" | "orbitMode" | "orbitSize" | "orbitSpeed" | "orbitRevolution" | "orbitRevolutionStyle" | "orbitEccentricity" | "orbitShowRings" | "orbitAnimated" | "clock" | "random" | "seed" | "customNetworkLayout" | "onLayoutError" | "layoutConfig" | "perspective"> & {
9
+ activityClock?: () => number;
9
10
  tensionConfig: NetworkPipelineConfig["tensionConfig"];
10
11
  showParticles: boolean;
11
12
  particleStyle: NetworkPipelineConfig["particleStyle"];
@@ -18,6 +18,8 @@ export interface NetworkCircleNode {
18
18
  datum: SceneDatum;
19
19
  accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
20
20
  accessibility?: SceneAccessibilityMetadata["accessibility"];
21
+ /** Scene node ID of the containing keyboard navigation group. */
22
+ navParentId?: string;
21
23
  id?: string;
22
24
  label?: string;
23
25
  depth?: number;
@@ -51,6 +53,8 @@ export interface NetworkRectNode {
51
53
  datum: SceneDatum;
52
54
  accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
53
55
  accessibility?: SceneAccessibilityMetadata["accessibility"];
56
+ /** Scene node ID of the containing keyboard navigation group. */
57
+ navParentId?: string;
54
58
  id?: string;
55
59
  label?: string;
56
60
  depth?: number;
@@ -83,6 +87,8 @@ export interface NetworkArcNode {
83
87
  datum: SceneDatum;
84
88
  accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
85
89
  accessibility?: SceneAccessibilityMetadata["accessibility"];
90
+ /** Scene node ID of the containing keyboard navigation group. */
91
+ navParentId?: string;
86
92
  id?: string;
87
93
  label?: string;
88
94
  _pulseIntensity?: number;
@@ -118,6 +124,8 @@ export interface NetworkSymbolNode {
118
124
  datum: SceneDatum;
119
125
  accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
120
126
  accessibility?: SceneAccessibilityMetadata["accessibility"];
127
+ /** Scene node ID of the containing keyboard navigation group. */
128
+ navParentId?: string;
121
129
  id?: string;
122
130
  label?: string;
123
131
  depth?: number;
@@ -161,6 +169,8 @@ export interface NetworkGlyphNode {
161
169
  datum: SceneDatum;
162
170
  accessibleDatum?: SceneAccessibilityMetadata["accessibleDatum"];
163
171
  accessibility?: SceneAccessibilityMetadata["accessibility"];
172
+ /** Scene node ID of the containing keyboard navigation group. */
173
+ navParentId?: string;
164
174
  id?: string;
165
175
  label?: string;
166
176
  depth?: number;
@@ -0,0 +1,3 @@
1
+ import type { NavGraph, NavPoint } from "./navigationGraph";
2
+ /** Shared spatial arrow movement for flat networks and authored sibling groups. */
3
+ export declare function findNearestSpatial(graph: NavGraph, from: NavPoint, direction: "right" | "left" | "up" | "down", candidates?: readonly number[]): number | null;
@@ -241,6 +241,8 @@ export interface NetworkPipelineConfig {
241
241
  chartType: NetworkChartType;
242
242
  /** Frame-owned logical clock for ingest, live encodings, and transitions. */
243
243
  clock?: import("./FrameRuntime").FrameClock;
244
+ /** Wall clock for data freshness; animation continues to use `clock`. */
245
+ activityClock?: () => number;
244
246
  /** Frame-local random source used by synchronous force layout. */
245
247
  random?: import("./FrameRuntime").FrameRandom;
246
248
  /** Serializable deterministic seed, including the force-worker protocol. */
@@ -0,0 +1,27 @@
1
+ import { type AxisExtentMode } from "../charts/shared/axisExtent";
2
+ import type { OrdinalScales } from "./ordinalTypes";
3
+ /** Existing ordinal modes retain their fixed count; rounded domains and their
4
+ * ticks share the XY pixel budget along the value axis. */
5
+ export declare function ordinalAxisTickCount(layout: {
6
+ width: number;
7
+ height: number;
8
+ }, projection: string, mode?: AxisExtentMode): number;
9
+ export declare function ordinalAxisTicks(scales: OrdinalScales, layout: {
10
+ width: number;
11
+ height: number;
12
+ }, mode?: AxisExtentMode, values?: number[]): number[];
13
+ export interface OrdinalValueTick {
14
+ value: number;
15
+ pixel: number;
16
+ label: string;
17
+ }
18
+ /**
19
+ * Positioned, labelled value-axis ticks for ordinal frames. Live axes,
20
+ * underlay grids, and static exports all read this one list, so a tick whose
21
+ * label repeats its neighbour is dropped from labels and grid alike — the
22
+ * same rule XY axes apply.
23
+ */
24
+ export declare function ordinalValueTicks(scales: OrdinalScales, layout: {
25
+ width: number;
26
+ height: number;
27
+ }, mode?: AxisExtentMode, values?: number[], format?: (value: number) => string): OrdinalValueTick[];
@@ -1,3 +1,13 @@
1
1
  import type { WedgeSceneNode, OrdinalLayout } from "../ordinalTypes";
2
2
  import type { OrdinalSceneContext } from "./types";
3
+ /**
4
+ * `innerRadius` is a pixel request, but the outer radius follows the plot
5
+ * area. On a short plot the requested hole can be wider than the pie; drawing
6
+ * that inverted ring paints it outside the plot, where the clip cuts it flat.
7
+ * A hole that leaves at least a 1px ring is kept as requested (thin rings are
8
+ * a legitimate style, and gauges size their hole against the radius they
9
+ * reserve); one that does not falls back to a readable ring of
10
+ * `FALLBACK_DONUT_RING` px, or a quarter of the radius on very small donuts.
11
+ */
12
+ export declare function fitDonutInnerRadius(requested: number, outerRadius: number): number;
3
13
  export declare function buildPieScene(ctx: OrdinalSceneContext, layout: OrdinalLayout): WedgeSceneNode[];
@@ -4,6 +4,8 @@ import type { Style } from "../types";
4
4
  import type { Datum } from "../../charts/shared/datumTypes";
5
5
  export interface OrdinalSceneContext {
6
6
  scales: OrdinalScales;
7
+ /** Columns in resolved scale-domain order, including integer-like names. */
8
+ orderedColumns: OrdinalColumn[];
7
9
  columns: Record<string, OrdinalColumn>;
8
10
  config: OrdinalPipelineConfig;
9
11
  getR: (d: Datum) => number;
@@ -193,6 +193,7 @@ export interface OrdinalPipelineConfig {
193
193
  chartType: OrdinalChartType;
194
194
  runtimeMode?: "bounded" | "streaming";
195
195
  windowSize: number;
196
+ maxCapacity?: number;
196
197
  windowMode: WindowMode;
197
198
  extentPadding: number;
198
199
  /** When `"exact"`, the value-axis domain is pinned to the literal data
@@ -200,6 +201,8 @@ export interface OrdinalPipelineConfig {
200
201
  * land on the actual data bounds. Default `"nice"` keeps the existing
201
202
  * padded domain so symbols at the extremes don't clip the plot edge. */
202
203
  axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
204
+ /** Explicit ticks disable automatic value-domain rounding. */
205
+ rTickValues?: number[];
203
206
  projection: "vertical" | "horizontal" | "radial";
204
207
  categoryAccessor?: string | ((d: Datum) => string);
205
208
  valueAccessor?: string | ((d: Datum) => number) | Array<string | ((d: Datum) => number)>;
@@ -276,8 +279,10 @@ export interface OrdinalPipelineConfig {
276
279
  /** Whether to animate elements on first render (bars grow from baseline, wedges sweep in) */
277
280
  introAnimation?: boolean;
278
281
  staleness?: StalenessConfig;
279
- /** Frame-owned logical clock for ingest, pulse, staleness, and transitions. */
282
+ /** Frame-owned logical clock for ingest, pulse, and transitions. */
280
283
  clock?: import("./FrameRuntime").FrameClock;
284
+ /** Wall clock for data freshness; animation continues to use `clock`. */
285
+ activityClock?: () => number;
281
286
  /** When provided, replaces chart-type dispatch in scene building.
282
287
  * Receives an OrdinalLayoutContext (scales, dimensions, theme,
283
288
  * resolveColor) and returns scene nodes plus optional overlays. */
@@ -360,6 +365,8 @@ export interface StreamOrdinalFrameProps<T = Datum> {
360
365
  oSort?: ((a: string, b: string) => number) | boolean | "asc" | "desc" | "auto";
361
366
  windowMode?: WindowMode;
362
367
  windowSize?: number;
368
+ /** Maximum retained live rows in growing mode (default 100,000). */
369
+ maxCapacity?: number;
363
370
  connectorAccessor?: string | ((d: T) => string);
364
371
  connectorStyle?: Style | ((d: Datum) => Style);
365
372
  /** ID accessor for remove()/update() — extracts a unique identifier from each datum */
@@ -371,7 +378,9 @@ export interface StreamOrdinalFrameProps<T = Datum> {
371
378
  /** Axis extent mode for the value (r) axis. `"nice"` (default) uses
372
379
  * d3-scale's rounded tick generator. `"exact"` pins the first and
373
380
  * last tick to the actual data min and max with equidistant
374
- * intermediate ticks. The categorical (o) axis is unaffected since
381
+ * intermediate ticks. `"rounded"` widens open ends to round ticks after
382
+ * padding and final layout, retaining explicit rExtent bounds.
383
+ * The categorical (o) axis is unaffected since
375
384
  * it's a band scale, not a continuous one. Ignored when explicit
376
385
  * `rTickValues` are provided — caller has hand-picked positions. */
377
386
  axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
@@ -24,3 +24,12 @@ export declare function pushWithTimestamp<T>(buffer: RingBuffer<T>, datum: T, ti
24
24
  * ring buffer. The predicate must be the same one passed to `buffer.remove()`.
25
25
  */
26
26
  export declare function compactTimestampBufferForRemoval<T>(buffer: RingBuffer<T>, timestampBuffer: RingBuffer<number> | null | undefined, predicate: (item: T) => boolean): void;
27
+ /** The retention policy applies to live appends, not bounded snapshots. */
28
+ export interface StreamingWindowConfig {
29
+ windowSize: number;
30
+ windowMode: "sliding" | "growing";
31
+ maxCapacity?: number;
32
+ }
33
+ export declare function validateStreamingWindow(config: StreamingWindowConfig): void;
34
+ /** Resize both rings together, preserving the newest rows and their timestamps. */
35
+ export declare function resizeStreamingBuffer<T>(buffer: RingBuffer<T>, timestamps: RingBuffer<number> | null | undefined, config: StreamingWindowConfig, grow?: boolean): T[];
@@ -14,6 +14,8 @@ export interface PipelineConfig {
14
14
  runtimeMode?: "streaming" | "bounded";
15
15
  /** Optional monotonic clock owned by a frame runtime or embedding host. */
16
16
  clock?: () => number;
17
+ /** Wall clock for data freshness; animation continues to use `clock`. */
18
+ activityClock?: () => number;
17
19
  windowSize: number;
18
20
  windowMode: WindowMode;
19
21
  arrowOfTime: ArrowOfTime;
@@ -27,6 +29,9 @@ export interface PipelineConfig {
27
29
  axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
28
30
  /** Resolved y-axis mode. Falls back to `axisExtent` when omitted. */
29
31
  yAxisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
32
+ /** Value-axis tick selection, shared with the overlay when rounding domains. */
33
+ yAxisTicks?: number;
34
+ yAxisTickValues?: import("./xyFrameAxisTypes").XYFrameAxisConfig["tickValues"];
30
35
  /**
31
36
  * Hard cap for `windowMode: "growing"`. Defaults to
32
37
  * {@link DEFAULT_GROWING_MAX_CAPACITY} (100_000). Canvas scene graphs
@@ -99,6 +104,8 @@ export interface PipelineConfig {
99
104
  };
100
105
  areaStyle?: (d: Datum) => Style;
101
106
  swarmStyle?: SwarmStyle;
107
+ /** Starting cumulative balance for waterfall charts. @default 0 */
108
+ initialValue?: number;
102
109
  waterfallStyle?: WaterfallStyle;
103
110
  colorScheme?: string | string[] | Record<string, string>;
104
111
  /** Theme categorical palette — used as fallback when colorScheme is not an explicit array */
@@ -44,8 +44,8 @@ export declare function resolveCenteredBinXDomain(dataDomain: [number, number],
44
44
  * Cumulative ends of the bars `buildWaterfallScene` draws. A missing or
45
45
  * non-finite x is not a bar, so that row must not move the cursor.
46
46
  */
47
- export declare function waterfallCumulativeEnds(data: Iterable<Datum>, getX: (d: Datum) => number, getY: (d: Datum) => number): number[];
48
- export declare function resolveWaterfallYDomain(buffer: RingBuffer<Datum>, getX: (d: Datum) => number, getY: (d: Datum) => number, extentPadding: number, exactMode: boolean): [number, number];
47
+ export declare function waterfallCumulativeEnds(data: Iterable<Datum>, getX: (d: Datum) => number, getY: (d: Datum) => number, initialValue?: number): number[];
48
+ export declare function resolveWaterfallYDomain(buffer: RingBuffer<Datum>, getX: (d: Datum) => number, getY: (d: Datum) => number, extentPadding: number, exactMode: boolean, initialValue?: number): [number, number];
49
49
  /**
50
50
  * Waterfall x values identify bar centers, so the automatic domain needs half
51
51
  * of the neighboring interval beyond each edge datum. User-specified bounds
@@ -55,6 +55,7 @@ export declare function resolveWaterfallXDomain(data: Datum[], getX: (d: Datum)
55
55
  export declare function expandYDomainWithRibbons(yDomain: [number, number], bufferArray: Datum[], ribbons: ResolvedRibbon[]): [number, number];
56
56
  export declare function padYDomain(yDomain: [number, number], options: {
57
57
  exactMode: boolean;
58
+ roundedMode?: boolean;
58
59
  extentPadding: number;
59
60
  userMin?: number;
60
61
  userMax?: number;
@@ -0,0 +1,9 @@
1
+ /** Widen a continuous value scale using d3's stable nice step, retaining pinned
2
+ * ends from the already-resolved domain (including log-domain validation). */
3
+ export declare function roundScaleDomain(scale: {
4
+ domain(): number[];
5
+ domain(values: number[]): unknown;
6
+ nice(count?: number): {
7
+ domain(): number[];
8
+ };
9
+ }, count: number, pinned: readonly boolean[]): void;
@@ -19,7 +19,7 @@ export interface ResolvedStaleness {
19
19
  }
20
20
  /**
21
21
  * Resolve the dimming + band for a given idle duration. Pure — the
22
- * render path computes idle from `now - lastIngestTime` each paint and
22
+ * render path reads wall-clock idle time from the activity tracker each paint and
23
23
  * the staleness poll uses the same function to decide when to repaint.
24
24
  *
25
25
  * `idleMs` of 0 (no data yet) is treated as fresh.
@@ -1,4 +1,16 @@
1
1
  export declare function resolveHorizontalTickAnchor(mode: "middle" | "edges" | undefined, isLeftmost: boolean, isRightmost: boolean): "start" | "middle" | "end";
2
+ /**
3
+ * Horizontal offset that keeps a text tick label inside `[min, max]` (the
4
+ * frame's full width, in plot coordinates). Centred end labels — long time
5
+ * stamps especially — otherwise run past the side margin and are clipped by
6
+ * the host container. Returns 0 for any label that already fits, so interior
7
+ * ticks are untouched. Width is the shared 0.6em estimate; a slight
8
+ * overestimate only nudges the label further inside.
9
+ */
10
+ export declare function resolveHorizontalTickLabelShift(anchor: "start" | "middle" | "end", pixel: number, label: string | number, fontSize: number, bounds: {
11
+ min: number;
12
+ max: number;
13
+ }): number;
2
14
  export declare function resolveVerticalTickBaseline(mode: "middle" | "edges" | undefined, isTopmost: boolean, isBottommost: boolean): "hanging" | "middle" | "auto";
3
15
  export declare function tickPixelExtent(ticks: Array<{
4
16
  pixel: number;
@@ -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,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
  }