@d3plus/core 4.9.0 → 4.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (236) hide show
  1. package/es/internal.js +3 -1
  2. package/es/src/charts/BoxWhisker/index.js +73 -4
  3. package/es/src/charts/BoxWhisker/outliers.js +68 -0
  4. package/es/src/charts/BoxWhisker/summary.js +83 -0
  5. package/es/src/charts/BoxWhisker/tooltip.js +122 -0
  6. package/es/src/charts/Bullet/index.js +2 -1
  7. package/es/src/charts/BumpChart/index.js +5 -0
  8. package/es/src/charts/Calendar/index.js +2 -1
  9. package/es/src/charts/Candlestick/aggregate.js +11 -1
  10. package/es/src/charts/Candlestick/index.js +5 -5
  11. package/es/src/charts/Chord/index.js +3 -2
  12. package/es/src/charts/Funnel/index.js +2 -1
  13. package/es/src/charts/Gauge/index.js +2 -1
  14. package/es/src/charts/Geomap/index.js +9 -3
  15. package/es/src/charts/Histogram/index.js +5 -1
  16. package/es/src/charts/Matrix/index.js +3 -2
  17. package/es/src/charts/Network/index.js +9 -4
  18. package/es/src/charts/Pack/index.js +2 -1
  19. package/es/src/charts/Pie/index.js +2 -1
  20. package/es/src/charts/Plot/axisHover.js +180 -0
  21. package/es/src/charts/Plot/axisHoverAnchors.js +174 -0
  22. package/es/src/charts/Plot/axisHoverScene.js +202 -0
  23. package/es/src/charts/Plot/barHitArea.js +81 -0
  24. package/es/src/charts/Plot/barLabelFit.js +123 -0
  25. package/es/src/charts/Plot/barWidth.js +2 -2
  26. package/es/src/charts/Plot/confidenceConfig.js +2 -2
  27. package/es/src/charts/Plot/draw.js +6 -2
  28. package/es/src/charts/Plot/index.js +25 -6
  29. package/es/src/charts/Plot/labelPlacement.js +9 -1
  30. package/es/src/charts/Plot/openDomainEnds.js +2 -5
  31. package/es/src/charts/Plot/pipeline.js +5 -3
  32. package/es/src/charts/Plot/pipelineAxisLayout.js +38 -8
  33. package/es/src/charts/Plot/pipelineDomains.js +7 -3
  34. package/es/src/charts/Plot/pipelineLineLabels.js +1 -1
  35. package/es/src/charts/Plot/plotInit.js +15 -0
  36. package/es/src/charts/Plot/plotZoom.js +15 -6
  37. package/es/src/charts/Plot/shapeDefaults.js +4 -4
  38. package/es/src/charts/Plot/sharedHoverScene.js +50 -31
  39. package/es/src/charts/Plot/sharedTooltip.js +19 -7
  40. package/es/src/charts/Plot/stackHelpers.js +13 -1
  41. package/es/src/charts/Plot/stackShareTooltip.js +9 -4
  42. package/es/src/charts/Plot/stackThreshold.js +154 -0
  43. package/es/src/charts/PolarArea/index.js +3 -2
  44. package/es/src/charts/Priestley/index.js +3 -2
  45. package/es/src/charts/Pyramid/index.js +4 -2
  46. package/es/src/charts/Radar/index.js +3 -2
  47. package/es/src/charts/RadialBar/index.js +2 -1
  48. package/es/src/charts/RadialMatrix/index.js +3 -2
  49. package/es/src/charts/Rings/index.js +5 -3
  50. package/es/src/charts/Sankey/index.js +3 -2
  51. package/es/src/charts/Treemap/applyLayout.js +14 -1
  52. package/es/src/charts/Treemap/emit.js +8 -2
  53. package/es/src/charts/Treemap/emitGroupHeaders.js +104 -0
  54. package/es/src/charts/Treemap/groupHeaders.js +95 -0
  55. package/es/src/charts/Treemap/index.js +15 -2
  56. package/es/src/charts/Treemap/thresholdFunction.js +11 -9
  57. package/es/src/charts/Waffle/index.js +4 -2
  58. package/es/src/charts/Waffle/tooltip.js +6 -2
  59. package/es/src/charts/Waterfall/index.js +4 -2
  60. package/es/src/charts/definition/makeChart.js +12 -5
  61. package/es/src/charts/drawSteps/saveChart.js +176 -0
  62. package/es/src/charts/drawSteps/saveControl.js +148 -0
  63. package/es/src/charts/drawSteps/saveControlMarkup.js +104 -0
  64. package/es/src/charts/drawSteps/tableViewMarkup.js +1 -1
  65. package/es/src/charts/drawSteps/topLeftControls.js +3 -1
  66. package/es/src/charts/drawSteps/topLeftControlsMarkup.js +1 -1
  67. package/es/src/charts/events/click.shape.js +30 -1
  68. package/es/src/charts/events/mouseenter.js +9 -0
  69. package/es/src/charts/events/mousemove.legend.js +3 -0
  70. package/es/src/charts/events/mousemove.shape.js +7 -2
  71. package/es/src/charts/facet/facetConfig.js +2 -2
  72. package/es/src/charts/facet/facetData.js +2 -2
  73. package/es/src/charts/features/axes.js +7 -6
  74. package/es/src/charts/features/axesFinal.js +23 -3
  75. package/es/src/charts/features/axesMeasure.js +54 -2
  76. package/es/src/charts/features/colorScaleBucket.js +17 -0
  77. package/es/src/charts/features/colorScaleHover.js +69 -0
  78. package/es/src/charts/features/features.js +13 -1
  79. package/es/src/charts/features/featuresColorScale.js +44 -4
  80. package/es/src/charts/features/featuresLegend.js +6 -8
  81. package/es/src/charts/features/plotPaint.js +4 -4
  82. package/es/src/charts/features/shapeEmit.js +23 -2
  83. package/es/src/charts/features/shareKey.js +15 -0
  84. package/es/src/charts/features/thresholdMembers.js +71 -0
  85. package/es/src/charts/helpers/densityChart.js +3 -1
  86. package/es/src/charts/helpers/valueTitle.js +6 -3
  87. package/es/src/charts/partition/chartFields.js +4 -3
  88. package/es/src/charts/partition/hierarchy.js +2 -0
  89. package/es/src/charts/pipeline/preDrawData.js +31 -10
  90. package/es/src/charts/pipeline/vizDraw.js +40 -29
  91. package/es/src/charts/pipeline/vizPreDraw.js +24 -15
  92. package/es/src/charts/viz/Viz.js +43 -8
  93. package/es/src/charts/viz/VizBase.js +32 -12
  94. package/es/src/charts/viz/dataPoller.js +52 -0
  95. package/es/src/charts/viz/groupRow.js +35 -0
  96. package/es/src/charts/viz/interactionOpacity.js +19 -5
  97. package/es/src/charts/viz/missingFields.js +122 -0
  98. package/es/src/charts/viz/reportHandlerError.js +10 -0
  99. package/es/src/charts/viz/shapeClassTargets.js +18 -2
  100. package/es/src/charts/viz/simpleHover.js +2 -0
  101. package/es/src/charts/viz/vizClassName.js +31 -0
  102. package/es/src/charts/viz/vizDataPolling.js +167 -0
  103. package/es/src/charts/viz/vizDefaults.js +66 -0
  104. package/es/src/charts/viz/vizFields.js +18 -2
  105. package/es/src/charts/viz/vizRender.js +8 -2
  106. package/es/src/components/Axis/Axis.js +28 -0
  107. package/es/src/components/Axis/axisDefaults.js +3 -1
  108. package/es/src/components/Axis/axisLabelAngle.js +175 -0
  109. package/es/src/components/Axis/axisLabelThinning.js +13 -4
  110. package/es/src/components/Axis/axisLayout.js +86 -19
  111. package/es/src/components/Axis/axisLayoutLabels.js +66 -13
  112. package/es/src/components/Axis/axisLayoutScale.js +3 -0
  113. package/es/src/components/Axis/axisRender.js +38 -9
  114. package/es/src/components/Axis/axisRounding.js +15 -4
  115. package/es/src/components/Axis/axisSlantWrap.js +39 -0
  116. package/es/src/components/Axis/powTicks.js +73 -0
  117. package/es/src/components/ColorScale/ColorScale.js +28 -28
  118. package/es/src/components/ColorScale/bucketBounds.js +35 -0
  119. package/es/src/components/ColorScale/colorScaleHoverMark.js +327 -0
  120. package/es/src/components/ColorScale/colorScaleRender.js +25 -1
  121. package/es/src/components/ColorScale/colorScaleScale.js +15 -9
  122. package/es/src/components/ColorScale/colorScaleType.js +26 -0
  123. package/es/src/components/TextBox.js +2 -0
  124. package/es/src/components/Timeline/Timeline.js +43 -52
  125. package/es/src/components/Timeline/brushSpan.js +78 -0
  126. package/es/src/components/Timeline/timelineConfig.js +7 -0
  127. package/es/src/components/Timeline/timelineRender.js +44 -6
  128. package/es/src/components/Tooltip.js +13 -8
  129. package/es/src/shapes/Box.js +66 -79
  130. package/es/src/shapes/boxOutlierShape.js +19 -0
  131. package/es/src/shapes/boxStats.js +35 -0
  132. package/es/src/shapes/boxStyle.js +78 -0
  133. package/es/src/shapes/boxSummary.js +174 -0
  134. package/es/src/shapes/shapeStandalone.js +2 -0
  135. package/es/src/utils/BaseClass.js +19 -0
  136. package/es/src/utils/className.js +78 -0
  137. package/es/src/utils/configWarnings.js +25 -0
  138. package/es/src/utils/fieldAccessor.js +31 -0
  139. package/es/src/utils/paintComponentScene.js +2 -0
  140. package/package.json +10 -9
  141. package/types/index.d.ts +3 -1
  142. package/types/internal.d.ts +3 -1
  143. package/types/src/charts/BoxWhisker/index.d.ts +3 -1
  144. package/types/src/charts/BoxWhisker/outliers.d.ts +25 -0
  145. package/types/src/charts/BoxWhisker/summary.d.ts +39 -0
  146. package/types/src/charts/BoxWhisker/tooltip.d.ts +36 -0
  147. package/types/src/charts/Candlestick/aggregate.d.ts +6 -0
  148. package/types/src/charts/Plot/axisHover.d.ts +68 -0
  149. package/types/src/charts/Plot/axisHoverAnchors.d.ts +88 -0
  150. package/types/src/charts/Plot/axisHoverScene.d.ts +88 -0
  151. package/types/src/charts/Plot/barHitArea.d.ts +59 -0
  152. package/types/src/charts/Plot/barLabelFit.d.ts +81 -0
  153. package/types/src/charts/Plot/index.d.ts +13 -0
  154. package/types/src/charts/Plot/labelPlacement.d.ts +5 -0
  155. package/types/src/charts/Plot/plotInit.d.ts +9 -2
  156. package/types/src/charts/Plot/plotZoom.d.ts +2 -0
  157. package/types/src/charts/Plot/sharedHoverScene.d.ts +3 -3
  158. package/types/src/charts/Plot/sharedTooltip.d.ts +11 -4
  159. package/types/src/charts/Plot/stackHelpers.d.ts +5 -0
  160. package/types/src/charts/Plot/stackThreshold.d.ts +75 -0
  161. package/types/src/charts/Treemap/emit.d.ts +2 -1
  162. package/types/src/charts/Treemap/emitGroupHeaders.d.ts +16 -0
  163. package/types/src/charts/Treemap/groupHeaders.d.ts +91 -0
  164. package/types/src/charts/Treemap/index.d.ts +2 -0
  165. package/types/src/charts/Treemap/thresholdFunction.d.ts +5 -2
  166. package/types/src/charts/definition/ChartDefinition.d.ts +14 -2
  167. package/types/src/charts/definition/makeChart.d.ts +4 -3
  168. package/types/src/charts/drawSteps/saveChart.d.ts +47 -0
  169. package/types/src/charts/drawSteps/saveControl.d.ts +9 -0
  170. package/types/src/charts/drawSteps/saveControlMarkup.d.ts +44 -0
  171. package/types/src/charts/drawSteps/tableViewMarkup.d.ts +1 -0
  172. package/types/src/charts/drawSteps/topLeftControls.d.ts +1 -1
  173. package/types/src/charts/drawSteps/topLeftControlsMarkup.d.ts +1 -1
  174. package/types/src/charts/facet/facetData.d.ts +1 -1
  175. package/types/src/charts/features/axesMeasure.d.ts +9 -1
  176. package/types/src/charts/features/colorScaleBucket.d.ts +9 -0
  177. package/types/src/charts/features/colorScaleHover.d.ts +32 -0
  178. package/types/src/charts/features/features.d.ts +8 -0
  179. package/types/src/charts/features/plotPaint.d.ts +2 -0
  180. package/types/src/charts/features/shapeEmit.d.ts +2 -0
  181. package/types/src/charts/features/shareKey.d.ts +9 -0
  182. package/types/src/charts/features/thresholdMembers.d.ts +38 -0
  183. package/types/src/charts/helpers/valueTitle.d.ts +4 -2
  184. package/types/src/charts/pipeline/stages.d.ts +2 -0
  185. package/types/src/charts/pipeline/vizDraw.d.ts +8 -3
  186. package/types/src/charts/pipeline/vizPreDraw.d.ts +3 -2
  187. package/types/src/charts/viz/Viz.d.ts +28 -4
  188. package/types/src/charts/viz/VizBase.d.ts +12 -3
  189. package/types/src/charts/viz/dataPoller.d.ts +28 -0
  190. package/types/src/charts/viz/groupRow.d.ts +24 -0
  191. package/types/src/charts/viz/interactionOpacity.d.ts +3 -1
  192. package/types/src/charts/viz/missingFields.d.ts +57 -0
  193. package/types/src/charts/viz/reportHandlerError.d.ts +7 -0
  194. package/types/src/charts/viz/shapeClassTargets.d.ts +6 -0
  195. package/types/src/charts/viz/simpleHover.d.ts +2 -1
  196. package/types/src/charts/viz/vizClassName.d.ts +23 -0
  197. package/types/src/charts/viz/vizDataPolling.d.ts +48 -0
  198. package/types/src/charts/viz/vizDefaults.d.ts +49 -0
  199. package/types/src/charts/viz/vizFields.d.ts +15 -0
  200. package/types/src/charts/viz/vizTypes.d.ts +33 -1
  201. package/types/src/components/Axis/Axis.d.ts +36 -8
  202. package/types/src/components/Axis/axisLabelAngle.d.ts +110 -0
  203. package/types/src/components/Axis/axisLabelThinning.d.ts +3 -7
  204. package/types/src/components/Axis/axisLayout.d.ts +5 -0
  205. package/types/src/components/Axis/axisLayoutLabels.d.ts +13 -0
  206. package/types/src/components/Axis/axisRounding.d.ts +6 -3
  207. package/types/src/components/Axis/axisSlantWrap.d.ts +22 -0
  208. package/types/src/components/Axis/powTicks.d.ts +29 -0
  209. package/types/src/components/ColorScale/ColorScale.d.ts +13 -0
  210. package/types/src/components/ColorScale/bucketBounds.d.ts +14 -0
  211. package/types/src/components/ColorScale/colorScaleHoverMark.d.ts +86 -0
  212. package/types/src/components/ColorScale/colorScaleScale.d.ts +3 -0
  213. package/types/src/components/ColorScale/colorScaleType.d.ts +17 -0
  214. package/types/src/components/Timeline/brushSpan.d.ts +41 -0
  215. package/types/src/components/Timeline/timelineConfig.d.ts +6 -0
  216. package/types/src/components/Timeline/timelineRender.d.ts +8 -0
  217. package/types/src/components/Tooltip.d.ts +8 -0
  218. package/types/src/shapes/Box.d.ts +1 -8
  219. package/types/src/shapes/boxOutlierShape.d.ts +9 -0
  220. package/types/src/shapes/boxStats.d.ts +19 -0
  221. package/types/src/shapes/boxStyle.d.ts +25 -0
  222. package/types/src/shapes/boxSummary.d.ts +66 -0
  223. package/types/src/shapes/emitLabels.d.ts +1 -1
  224. package/types/src/shapes/shapeConfig.d.ts +42 -4
  225. package/types/src/utils/BaseClass.d.ts +23 -0
  226. package/types/src/utils/D3Scale.d.ts +3 -0
  227. package/types/src/utils/D3plusConfig.d.ts +261 -5
  228. package/types/src/utils/className.d.ts +64 -0
  229. package/types/src/utils/configWarnings.d.ts +21 -2
  230. package/types/src/utils/fieldAccessor.d.ts +24 -0
  231. package/types/src/utils/index.d.ts +1 -1
  232. package/types/src/utils/paintComponentScene.d.ts +3 -1
  233. package/umd/d3plus-core.full.js +6405 -1068
  234. package/umd/d3plus-core.full.min.js +2 -2
  235. package/umd/d3plus-core.js +5328 -1002
  236. package/umd/d3plus-core.min.js +2 -2
@@ -9,6 +9,8 @@ import type { AccessorFn } from "./AccessorFn.js";
9
9
  import type { ConstOrAccessor, CssColor, Orient, SideOrient } from "../shapes/shapeConfig.js";
10
10
  import type { SizeLegendLineConfig, SizeLegendShapeConfig, SizeLegendTextConfig } from "../components/SizeLegend/SizeLegend.js";
11
11
  import type { SizeLegendScale, SizeLegendSize } from "../components/SizeLegend/sizeLegendLayout.js";
12
+ import type { ColorScaleTypeSetting } from "../components/ColorScale/colorScaleType.js";
13
+ import type { ColorScaleHoverMarkConfig } from "../components/ColorScale/colorScaleHoverMark.js";
12
14
  type Position = "top" | "right" | "bottom" | "left";
13
15
  /** A legend or colorScale side, or `"auto"` to let the chart choose (inside the chart when it fits, else right on wide charts and bottom otherwise). */
14
16
  type PanelPosition = Position | "auto";
@@ -103,6 +105,18 @@ export interface AxisConfig {
103
105
  */
104
106
  labels?: unknown[];
105
107
  labelOffset?: false | number;
108
+ /**
109
+ Whether to rotate the axis labels, and by how much: `true` rotates
110
+ them -90 degrees, `false` keeps them flat, and a number rotates them
111
+ by that many degrees (clockwise, so `-45` rises to the right), each
112
+ label hanging off the axis from the end of its text nearest the axis,
113
+ across from its tick, and wrapping onto up to three lines when its
114
+ neighbors leave room. Left `undefined` (the default), a horizontal
115
+ axis of categories slants its labels 30 degrees when they would not
116
+ fit flat, or stands them at -90 when they are too crowded to slant.
117
+ See Axis's `labelRotation`.
118
+ */
119
+ labelRotation?: boolean | number;
106
120
  /**
107
121
  Exact size of the space that contains the axis tick labels and title.
108
122
  Labels that need more room overflow outward instead of moving the axis
@@ -141,6 +155,25 @@ export interface AxisConfig {
141
155
  rounding?: "none" | "outside" | "inside";
142
156
  /** Scale of the axis. */
143
157
  scale?: AxisScale;
158
+ /**
159
+ The exponent of a `"pow"` axis (`scale: "pow"`): below 1 it spreads the
160
+ small values out and squeezes the large ones together (`0.5` matches
161
+ a `"sqrt"` axis), above 1 it does the opposite. Defaults to `1`, which
162
+ draws like a linear axis. Only a `"pow"` axis reads it; on any other
163
+ scale it has no effect, and a value that isn't a positive number falls
164
+ back to `1`. Ticks are spaced evenly along a power axis and rounded to
165
+ round values.
166
+ */
167
+ exponent?: number;
168
+ /**
169
+ Whether to flip the axis's direction, so its values run the other
170
+ way: a horizontal axis from right to left, a vertical one from top to
171
+ bottom (a Plot's y axis, categories included, normally runs bottom to
172
+ top, so reversing it lists them from the top). Everything placed on
173
+ the axis follows it: shapes, tick labels, gridlines, breaks, zooming,
174
+ and hover badges. Defaults to `false`.
175
+ */
176
+ reverse?: boolean;
144
177
  /** The shape drawn at each tick: `"Line"` (the default), `"Rect"`, or `"Circle"`. */
145
178
  shape?: "Line" | "Rect" | "Circle";
146
179
  /** Tick style of the axis. */
@@ -172,6 +205,12 @@ export interface AxisConfig {
172
205
  export interface TooltipConfig {
173
206
  /** The inner HTML content of the arrow element, empty by default. */
174
207
  arrow?: ((d: DataPoint) => string) | string;
208
+ /**
209
+ CSS classes added to each tooltip element, beside its fixed
210
+ `d3plus-tooltip` class, so page CSS can style one chart's tooltips: a
211
+ space-separated string or an array.
212
+ */
213
+ className?: string | string[];
175
214
  /** The background color accessor for each tooltip. */
176
215
  background?: ((d: DataPoint) => CssColor) | CssColor;
177
216
  /** The border accessor for each tooltip. */
@@ -275,9 +314,21 @@ export interface TimelineConfig {
275
314
  /** Brush event filter. */
276
315
  brushFilter?: () => boolean;
277
316
  /**
278
- The minimum number of ticks that can be highlighted when using "ticks"
279
- `buttonBehavior`. Helpful for x/y plots where selecting fewer than 2 time
280
- periods is undesirable.
317
+ The maximum number of ticks (or buttons) a selection can span; unlimited
318
+ by default. A wider brush is pulled in to it on release, keeping the end
319
+ being dragged, and a wider starting selection keeps its latest periods.
320
+ A `brushMax` below `brushMin` rises to it.
321
+ */
322
+ brushMax?: number;
323
+ /**
324
+ The minimum number of ticks (or buttons) a selection can span. Helpful
325
+ for x/y plots where selecting fewer than 2 time periods is undesirable.
326
+ A narrower brush widens to it on release: a drag keeps the end being
327
+ dragged (or, with ticks, its first tick), and a click selects the
328
+ clicked period and the ones after it. A narrower starting selection
329
+ keeps its latest period, and a chart that starts on its latest period
330
+ starts on its latest `brushMin` instead. Either way, the selection grows the other way where the
331
+ timeline runs out. Unused with `brushing: false`.
281
332
  */
282
333
  brushMin?: number;
283
334
  /** Toggles the horizontal alignment of the button timeline. */
@@ -305,6 +356,12 @@ export interface TimelineConfig {
305
356
  playButtonInterval?: number;
306
357
  /** The current selection. Defaults to the most recent period in the timeline. */
307
358
  selection?: (Date | number)[] | Date | number | false;
359
+ /**
360
+ Whether to run the timeline from its latest period to its earliest.
361
+ Selections, the default selection, and playback still read from
362
+ earliest to latest. Defaults to `false`.
363
+ */
364
+ reverse?: boolean;
308
365
  /** Toggles the snapping value. */
309
366
  snapping?: boolean;
310
367
  }
@@ -387,6 +444,46 @@ export interface ColorScaleConfig {
387
444
  bucketFormat?: (start: number, i: number, buckets: number[], values: number[]) => string;
388
445
  /** Given a bucket's minimum and maximum values, returns the full label. */
389
446
  bucketJoiner?: (min: string, max: string) => string;
447
+ /**
448
+ The kind of scale: `"linear"` or `"log"` (a continuous gradient), or
449
+ `"jenks"`, `"buckets"`, or `"quantile"` (discrete buckets). A function
450
+ picks one on each render: it receives the numeric values the scale is
451
+ built from (sorted, without null or NaN) and their `[min, max]` extent,
452
+ with the ColorScale as `this`, and returns a scale name, as in
453
+ `(values, [min, max]) => max - min > 5 ? "jenks" : "linear"`. An unknown
454
+ name logs a warning and builds a linear scale. Defaults to `"linear"`,
455
+ and to `"jenks"` in a chart's `colorScaleConfig`.
456
+ */
457
+ scale?: ColorScaleTypeSetting;
458
+ /**
459
+ Whether hovering a chart shape marks its value on the scale: an extra
460
+ axis tick at the value on the color bar, and a badge reading the value
461
+ in the axis's tick format where that tick's label would sit, covering
462
+ the labels it overlaps (a value outside the domain marks the bar's
463
+ end). A bucketed bar (`bucketAxis`) also outlines the value's bucket.
464
+ A scale drawn as discrete swatches gets no mark; the value's swatch
465
+ stays lit and the others dim instead. On charts whose shape hover is
466
+ off (`hoverOpacity: 1`, as on Geomap and Calendar or past
467
+ `dataCutoff`), that swatch highlight comes from this option too, so
468
+ `false` turns it off there. Defaults to `true`.
469
+ */
470
+ hoverMark?: boolean;
471
+ /**
472
+ Styles the `hoverMark`. `tickConfig` takes `stroke` and `strokeWidth`
473
+ (the axis ticks' own by default) and `length` (the axis's `tickSize`
474
+ by default); the badge starts where the tick ends. `badgeConfig` takes `fill`
475
+ (the value's color by default), `stroke` (the background-legible text
476
+ color by default), `strokeWidth` (default `1`), `fontColor` (a color
477
+ contrasting the fill by default), `fontFamily`, `fontSize` (default
478
+ `11`), `fontWeight` (default `400`), `padding` around the text (default
479
+ `3`; across the bar it is padded to sit as far out as the tick
480
+ labels), and `rx` corner radius (default `2`). `outlineConfig`, the
481
+ bucket outline on a `bucketAxis` bar, takes `stroke` (the
482
+ background-legible text color by default) and `strokeWidth` (default
483
+ `2`). Each is a value or a function of the
484
+ hovered value.
485
+ */
486
+ hoverMarkConfig?: ColorScaleHoverMarkConfig;
390
487
  }
391
488
  /** `colorDefaults` input: any subset of the color defaults, with `scale` also accepting an array of colors. */
392
489
  export type ColorDefaultsConfig = Partial<Omit<ColorDefaults, "scale">> & {
@@ -400,9 +497,32 @@ export type ConfidenceBandSetting = [ConfidenceBound, ConfidenceBound] | [Confid
400
497
  upper?: ConfidenceBound;
401
498
  label?: string;
402
499
  };
500
+ /** A file type the top-left download button can save the chart as. */
501
+ export type SaveFormat = "png" | "svg" | "jpg";
502
+ export interface SaveControlConfig {
503
+ /** The saved file's name, without its extension. Defaults to the chart's title, or `"download"` when it has none. */
504
+ filename?: string;
505
+ /** The file types offered, in menu order. With a single format, the button saves that format in one click, with no menu. Defaults to `["png", "svg", "jpg"]`. */
506
+ formats?: SaveFormat[];
507
+ /** The color painted behind the chart. Defaults to the page color behind the chart, so a JPG never comes out black. `false` leaves PNG and SVG files transparent. */
508
+ background?: string | false;
509
+ /** Called once the file is handed to the browser, or with the `Error` when the chart could not be saved. Without it, errors are logged to the console. */
510
+ callback?: (error?: Error) => void;
511
+ /** Other options are passed to html-to-image when saving a PNG or JPG, such as `pixelRatio` or `quality`. */
512
+ [key: string]: unknown;
513
+ }
403
514
  export interface D3plusConfig {
404
515
  /** Data array or URL string to load data from. */
405
516
  data?: DataPoint[] | string;
517
+ /**
518
+ CSS classes added to the outermost element the chart or component draws
519
+ into, beside its fixed classes, so page CSS can target it: a chart's root
520
+ `<svg class="d3plus-viz">` (and, with the Canvas renderer, its
521
+ `<canvas>`), the HTML layer holding its controls, and a standalone
522
+ component's `<svg>`. A space-separated string or an array; a new value
523
+ replaces the classes the previous one added.
524
+ */
525
+ className?: string | string[];
406
526
  /** Locale code used for text and number formatting. */
407
527
  locale?: string;
408
528
  /** The active callback function for highlighting shapes. */
@@ -428,6 +548,32 @@ export interface D3plusConfig {
428
548
  gridConfig?: Record<string, unknown>;
429
549
  shapeConfig?: Record<string, unknown>;
430
550
  };
551
+ /**
552
+ Whether hovering a Plot's mark draws a dashed guide from its point to
553
+ each axis and a badge on that axis with the point's value there,
554
+ formatted as the tooltip formats that axis's values (the axis's
555
+ `tickFormat` when set). `"x"` or `"y"` draws them for that direction
556
+ only (each including its secondary axis). A bar is badged on its value
557
+ axis only. With a discrete axis, the shared tooltip's crosshair is that
558
+ axis's guide, and the value axis follows the hovered series' point (or
559
+ the one nearest the pointer). Defaults to `true` (`"x"` on BumpChart,
560
+ whose y axes label series rather than values).
561
+ */
562
+ axisHover?: boolean | "x" | "y";
563
+ /**
564
+ Styles the `axisHover` guides and badges. `guideConfig` takes `stroke`
565
+ (the hovered mark's color by default), `strokeWidth` (default `1`),
566
+ `strokeDasharray` (default `"4 3"`), and `strokeOpacity`. `badgeConfig`
567
+ takes `fill` (the hovered mark's color by default), `fontColor` (a
568
+ color contrasting the fill by default), `fontFamily`, `fontSize`
569
+ (default `12`), `fontWeight` (default `400`), `padding` around the text
570
+ (default `4`), and `rx` corner radius (default `2`). Each is a value or
571
+ a `(d, i) => value` accessor of the hovered data row.
572
+ */
573
+ axisHoverConfig?: {
574
+ guideConfig?: Record<string, unknown>;
575
+ badgeConfig?: Record<string, unknown>;
576
+ };
431
577
  /**
432
578
  Sets text to be shown positioned absolute on top of the visualization in the bottom-right corner. This is most often used in Geomaps to display the copyright of map tiles. The text is rendered as HTML, so any valid HTML string will render as expected (eg. anchor links work).
433
579
  */
@@ -520,6 +666,27 @@ export interface D3plusConfig {
520
666
  })[]);
521
667
  /** Candlestick: the share of each period's room its candle body (or OHLC ticks) spans, from 0 to 1. Defaults to `0.7`. */
522
668
  bodyWidth?: number;
669
+ /** BoxWhisker: accessor or data key for each summary row's upper whisker end. See `boxMedian`. */
670
+ boxMax?: string | ((d: DataPoint, i: number) => number);
671
+ /**
672
+ BoxWhisker: accessor or data key for each summary row's median. Setting
673
+ it, `boxMin`, `boxQ1`, `boxQ3`, or `boxMax` draws boxes from statistics
674
+ you already have: each row is one box (placed by its `x`, or `y` when
675
+ `discrete` is `"y"`) drawn from those values, with nothing computed and
676
+ `whiskerMode` unused. All five are needed (a warning names any left
677
+ unset), and a row whose values aren't all numbers draws no box. The
678
+ value axis spans every row's statistics and outliers, and the tooltip
679
+ lists them.
680
+ */
681
+ boxMedian?: string | ((d: DataPoint, i: number) => number);
682
+ /** BoxWhisker: accessor or data key for each summary row's lower whisker end. See `boxMedian`. */
683
+ boxMin?: string | ((d: DataPoint, i: number) => number);
684
+ /** BoxWhisker: accessor or data key for each summary row's outliers, an array of values drawn as points past the whiskers. Used only with the other box statistics; see `boxMedian`. */
685
+ boxOutliers?: string | ((d: DataPoint, i: number) => number[]);
686
+ /** BoxWhisker: accessor or data key for each summary row's lower quartile, where its box starts. See `boxMedian`. */
687
+ boxQ1?: string | ((d: DataPoint, i: number) => number);
688
+ /** BoxWhisker: accessor or data key for each summary row's upper quartile, where its box ends. See `boxMedian`. */
689
+ boxQ3?: string | ((d: DataPoint, i: number) => number);
523
690
  /**
524
691
  ParallelCoordinates: the brush strips over each axis — `width` (px), the
525
692
  selection's `fill`, `fillOpacity`, `stroke`, and `strokeWidth`, and
@@ -582,7 +749,12 @@ export interface D3plusConfig {
582
749
  colorMin?: CssColor;
583
750
  colorMid?: CssColor;
584
751
  colorMax?: CssColor;
585
- scale?: AxisScale;
752
+ /** The kind of scale, or a function that picks one from the colorScale values on each render (see `ColorScaleConfig.scale`). Defaults to `"jenks"`. */
753
+ scale?: ColorScaleTypeSetting;
754
+ /** Marks a hovered shape's value on the colorScale (see `ColorScaleConfig.hoverMark`). Defaults to `true`. */
755
+ hoverMark?: boolean;
756
+ /** Styles the hover mark (see `ColorScaleConfig.hoverMarkConfig`). */
757
+ hoverMarkConfig?: ColorScaleHoverMarkConfig;
586
758
  };
587
759
  /**
588
760
  The maximum pixel size for drawing the color scale: width for horizontal scales and height for vertical scales.
@@ -658,6 +830,10 @@ export interface D3plusConfig {
658
830
  curve?: "linear" | "smooth" | "bump";
659
831
  /** Maximum number of data points to render before downsampling. */
660
832
  dataCutoff?: number;
833
+ /**
834
+ When `data` is loaded from a URL (or a request object, or an Array holding one), re-fetches it every this many milliseconds and redraws with a transition when it changes, keeping hover, zoom, legend toggles, and the timeline selection. Each poll uses the same request and `data` formatter as the first load, and a response identical to the drawn data is not redrawn. Polling waits while the browser tab is hidden or, with `detectVisible`, while the chart is scrolled out of view, and catches up as soon as it is visible again. A failed request keeps the last data, logs one warning per run of failures, and tries again on the next tick. `destroy()`, setting this to `false`, or passing new `data` stops polling. Only `data` is polled, not `links`, `nodes`, or `topojson`. Defaults to `false` (load once).
835
+ */
836
+ dataPollingInterval?: number | false;
661
837
  /**
662
838
  Calendar: the day each row falls on, as a data key or accessor returning
663
839
  a `Date`, a millisecond timestamp, or a date string (a bare
@@ -814,6 +990,41 @@ export interface D3plusConfig {
814
990
  gapSort?: false | "ascending" | "descending";
815
991
  /** Grouping key(s) or accessor function(s). */
816
992
  groupBy?: string | string[] | ((d: DataPoint) => string | number) | ((d: DataPoint) => string | number)[];
993
+ /**
994
+ Treemap: style of the group header strips (see `groupLabels`). The
995
+ accessors receive the group's merged row.
996
+ */
997
+ groupLabelConfig?: {
998
+ /** Strip color. Defaults to a darker shade of the group's color, or a neutral tone when `colorScale` colors the tiles. */
999
+ fill?: CssColor | ((d: DataPoint, i: number) => CssColor);
1000
+ /** Text color. Defaults to the color that contrasts with the strip. */
1001
+ fontColor?: CssColor | ((d: DataPoint, i: number) => CssColor);
1002
+ /** Font family. Defaults to the chart's `fontFamily`. */
1003
+ fontFamily?: string | string[];
1004
+ /** Font size, in pixels, which sets the strip's height. Defaults to `11`. */
1005
+ fontSize?: number;
1006
+ /** Font weight. Defaults to `600`. */
1007
+ fontWeight?: number | string;
1008
+ /**
1009
+ The strip's text, given the group's merged row (the same row the
1010
+ strip's hover and click handlers receive). Its tooltip title uses it
1011
+ too. Unset, or returning nothing, the strip shows the group's
1012
+ `groupBy` value at its level; the chart's own `label` names only the
1013
+ tiles, since on a merged row it can't tell a group-level field from a
1014
+ tile-level one.
1015
+ */
1016
+ label?: (d: DataPoint, i: number) => string;
1017
+ /** Space around the text inside the strip, in pixels. Defaults to `3`. */
1018
+ padding?: number;
1019
+ };
1020
+ /**
1021
+ Treemap: whether each group above the drawn tiles of a nested `groupBy`
1022
+ gets a header strip naming it, with its tiles below the strip. Every
1023
+ level above the tiles gets its own strip; a group too small for one
1024
+ gets none. Hovering a strip highlights its group, and clicking it zooms
1025
+ into that group (Back steps out). Defaults to `true`.
1026
+ */
1027
+ groupLabels?: boolean;
817
1028
  /** Padding between groups of bars in pixels. */
818
1029
  groupPadding?: number;
819
1030
  /** Overall height of the visualization in pixels. */
@@ -1087,6 +1298,42 @@ export interface D3plusConfig {
1087
1298
  radialScale?: "sqrt" | "linear";
1088
1299
  /** Row key for matrix-style layouts. */
1089
1300
  row?: string;
1301
+ /** Shows a top-left download button that saves the chart, as the reader sees it, as a PNG, SVG, or JPG file. On by default for every chart. */
1302
+ saveControl?: boolean;
1303
+ /**
1304
+ An additional CSS class name (or space-separated list of class names) applied to the download button, alongside the fixed `save-control`/`save-toggle` classes. Setting this automatically disables d3plus's built-in inline `saveControlStyle`/`saveControlStyleActive`/`saveControlStyleHover` defaults (as long as you haven't already customized them yourself), so a host page's own button styling applies through the cascade with no other configuration needed.
1305
+ */
1306
+ saveControlClassName?: string;
1307
+ /** Options for the download button: the saved file's `filename`, the `formats` it offers, the `background` painted behind the chart, a `callback`, and html-to-image options for PNG and JPG files. */
1308
+ saveControlConfig?: SaveControlConfig;
1309
+ /**
1310
+ An additional CSS class name (or space-separated list of class names) applied to the download menu, alongside its fixed `d3plus-save-menu` class (each item has the fixed `save-menu-item` class). Setting this automatically disables d3plus's built-in inline `saveControlMenuStyle`/`saveControlMenuItemStyle`/`saveControlMenuItemStyleHover` defaults (as long as you haven't already customized them yourself), so a host page's own menu styling applies through the cascade. The menu's position and open/closed display stay inline.
1311
+ */
1312
+ saveControlMenuClassName?: string;
1313
+ /**
1314
+ An object containing CSS key/value pairs that is used to style each item in the download menu. Passing `false` will remove all default styling. Automatically skipped (as if `false`) once `.saveControlMenuClassName(...)` is set, unless you've explicitly customized this yourself.
1315
+ */
1316
+ saveControlMenuItemStyle?: Record<string, unknown> | false;
1317
+ /**
1318
+ An object containing CSS key/value pairs that is used to style the download menu item under the pointer or keyboard focus. Passing `false` will remove all default styling. Automatically skipped (as if `false`) once `.saveControlMenuClassName(...)` is set, unless you've explicitly customized this yourself.
1319
+ */
1320
+ saveControlMenuItemStyleHover?: Record<string, unknown> | false;
1321
+ /**
1322
+ An object containing CSS key/value pairs that is used to style the download menu: its background, border, shadow, and spacing. Passing `false` will remove all default styling. Automatically skipped (as if `false`) once `.saveControlMenuClassName(...)` is set, unless you've explicitly customized this yourself.
1323
+ */
1324
+ saveControlMenuStyle?: Record<string, unknown> | false;
1325
+ /**
1326
+ An object containing CSS key/value pairs that is used to style the download button. Passing `false` will remove all default styling. Automatically skipped (as if `false`) once `.saveControlClassName(...)` is set, unless you've explicitly customized this yourself.
1327
+ */
1328
+ saveControlStyle?: Record<string, unknown> | false;
1329
+ /**
1330
+ An object containing CSS key/value pairs that is used to style the download button while its menu is open. Passing `false` will remove all default styling. Automatically skipped (as if `false`) once `.saveControlClassName(...)` is set, unless you've explicitly customized this yourself.
1331
+ */
1332
+ saveControlStyleActive?: Record<string, unknown> | false;
1333
+ /**
1334
+ An object containing CSS key/value pairs that is used to style the download button on hover. Passing `false` will remove all default styling. Automatically skipped (as if `false`) once `.saveControlClassName(...)` is set, unless you've explicitly customized this yourself.
1335
+ */
1336
+ saveControlStyleHover?: Record<string, unknown> | false;
1090
1337
  /**
1091
1338
  If using scroll or visibility detection, this method allow a custom override of the element to which the scroll detection function gets attached.
1092
1339
  */
@@ -1280,7 +1527,16 @@ export interface D3plusConfig {
1280
1527
  target?: string | number | ((d: DataPoint, i: number) => number) | false;
1281
1528
  /** Bullet: the target marker's `size` (a fraction of the band's thickness), `stroke`, and `strokeWidth`, each a value or a `(d, i)` accessor. */
1282
1529
  targetConfig?: Record<string, unknown>;
1283
- /** Threshold value for grouping small slices. */
1530
+ /**
1531
+ Threshold value for grouping small slices, as a share of the total
1532
+ (`0.05` is 5%). On a stacked Plot (StackedArea, or an AreaPlot,
1533
+ BarChart, or LinePlot with `stacked`), the series whose summed value
1534
+ across every position is under that share of the whole chart's total
1535
+ merge into one series, labelled by `thresholdName` and stacked on top.
1536
+ A bucket needs at least two items (a lone small item stays as
1537
+ itself), and its tooltips list the items it holds with their values.
1538
+ Off by default on Plot charts.
1539
+ */
1284
1540
  threshold?: number;
1285
1541
  /** Label for the threshold group, or a `(datum, index)` accessor. */
1286
1542
  thresholdName?: string | ((d: DataPoint, i: number) => string);
@@ -0,0 +1,64 @@
1
+ /**
2
+ The user's `className` config: CSS classes added to the outermost element
3
+ a chart or component draws into, next to its fixed d3plus classes, so page
4
+ CSS can target one chart.
5
+ */
6
+ /** The fixed classes of a scene renderer's drawing surfaces. */
7
+ export declare const RENDERER_CLASSES: string[];
8
+ /** A scene renderer, as far as `className` reads it. */
9
+ export interface ElementsSource {
10
+ elements?(): Element[];
11
+ }
12
+ /**
13
+ A scene renderer's drawing surface (its `<svg>` or `<canvas>`), leaving out
14
+ the HTML overlay layer it stacks over the drawing, where page CSS such as
15
+ a background would hide the chart.
16
+ @param renderer The scene renderer, once mounted.
17
+ @private
18
+ */
19
+ export declare function rendererSurfaces(renderer: ElementsSource | undefined): Element[];
20
+ /**
21
+ The distinct class names in a `className` value. A string is split on
22
+ whitespace, an array's entries are split the same way, and anything else
23
+ gives none.
24
+ @param value The config value.
25
+ @private
26
+ */
27
+ export declare function classNames(value: unknown): string[];
28
+ /**
29
+ Adds `value`'s classes to `el`, first removing the classes an earlier call
30
+ added that `value` no longer has. Classes the element has for any other
31
+ reason (its fixed d3plus classes) are left alone, unless an earlier call
32
+ added them.
33
+ @param el The element.
34
+ @param value The `className` config value.
35
+ @param keep Classes never to remove (the element's fixed classes).
36
+ @private
37
+ */
38
+ export declare function setUserClasses(el: Element, value: unknown, keep?: string[]): void;
39
+ /** An instance whose `className` applies to elements it reports. */
40
+ export interface ClassNameHost {
41
+ schema: {
42
+ className?: unknown;
43
+ };
44
+ _classNameTargets(): {
45
+ el: Element;
46
+ keep?: string[];
47
+ }[];
48
+ }
49
+ /**
50
+ Applies an instance's `className` to every element it currently draws
51
+ into. Before the first render there are none, and the classes are added
52
+ when it renders.
53
+ @param host The chart or component.
54
+ @private
55
+ */
56
+ export declare function applyClassName(host: ClassNameHost): void;
57
+ /**
58
+ SVG markup with `value`'s classes added to its root element, so a saved or
59
+ server-rendered chart keeps the classes its page element has.
60
+ @param markup Markup whose first tag is the root element.
61
+ @param value The `className` config value.
62
+ @private
63
+ */
64
+ export declare function withRootClasses(markup: string, value: unknown): string;
@@ -1,8 +1,10 @@
1
1
  /**
2
2
  Toggles the console warnings d3plus logs when a class receives a config
3
3
  property it does not support (like a misspelled key passed to `.config()`
4
- or `shapeConfig`). Warnings are on by default and the setting applies to
5
- every chart on the page. With no argument, returns the current setting.
4
+ or `shapeConfig`), or a config key names a data field that no row of the
5
+ chart's data has (like `y: "vlaue"`). Warnings are on by default and the
6
+ setting applies to every chart on the page. With no argument, returns the
7
+ current setting.
6
8
 
7
9
  @example
8
10
  import {configWarnings} from "@d3plus/core";
@@ -31,3 +33,20 @@ export declare function warnUnknownConfig(owner: string, key: string): void;
31
33
  @private
32
34
  */
33
35
  export declare function warnConfig(message: string): void;
36
+ /**
37
+ Logs a config warning once per `owner` and `id`, unless
38
+ `configWarnings(false)` turned them off. Use it for warnings about one
39
+ chart's own config and data, so each chart warns for itself however many
40
+ times it redraws.
41
+ @param owner The instance the warning is about.
42
+ @param id What the warning is about, so a changed message (like a longer
43
+ field list) doesn't log again.
44
+ @param message The warning.
45
+ @private
46
+ */
47
+ export declare function warnConfigOnce(owner: object, id: string, message: string): void;
48
+ /**
49
+ Whether `warnConfigOnce` would log for `owner` and `id`.
50
+ @private
51
+ */
52
+ export declare function canWarnOnce(owner: object, id: string): boolean;
@@ -0,0 +1,24 @@
1
+ import type { DataPoint } from "@d3plus/data";
2
+ /**
3
+ `accessor(key)` for a field name the user gave a config key, remembered so
4
+ the chart can warn when no row of its data has that field (see
5
+ `fieldNameOf`). A non-string key gives a plain `accessor`.
6
+ @param key The data field to read.
7
+ @private
8
+ */
9
+ export declare function fieldAccessor(key: string): (d: DataPoint) => DataPoint[keyof DataPoint];
10
+ /**
11
+ Remembers that `fn`, a function built from a user's field name (such as a
12
+ comparator ranking rows by it), reads the data field `key`.
13
+ @param fn The function.
14
+ @param key The data field it reads.
15
+ @private
16
+ */
17
+ export declare function markField<T extends object>(fn: T, key: string): T;
18
+ /**
19
+ The data field behind a function built by `fieldAccessor` or `markField`,
20
+ if any.
21
+ @param fn The value to look up.
22
+ @private
23
+ */
24
+ export declare function fieldNameOf(fn: unknown): string | undefined;
@@ -1,7 +1,7 @@
1
1
  export type { AccessorFn } from "./AccessorFn.js";
2
2
  export { default as accessor } from "./accessor.js";
3
3
  export { default as BaseClass } from "./BaseClass.js";
4
- export type { D3plusConfig, AxisConfig, ColorDefaultsConfig, ColorScaleConfig, ConfidenceBandSetting, ConfidenceBound, LegendConfig, SizeLegendConfig, TextBoxConfig, TimelineConfig, TooltipConfig, TrendLineConfig, } from "./D3plusConfig.js";
4
+ export type { D3plusConfig, AxisConfig, ColorDefaultsConfig, ColorScaleConfig, ConfidenceBandSetting, ConfidenceBound, LegendConfig, SaveControlConfig, SaveFormat, SizeLegendConfig, TextBoxConfig, TimelineConfig, TooltipConfig, TrendLineConfig, } from "./D3plusConfig.js";
5
5
  export type { D3Scale } from "./D3Scale.js";
6
6
  export { default as configPrep } from "./configPrep.js";
7
7
  export { configWarnings } from "./configWarnings.js";
@@ -13,7 +13,8 @@
13
13
  */
14
14
  import { SvgRenderer } from "@d3plus/render";
15
15
  import type { GroupNode } from "@d3plus/render";
16
- interface SceneComponent {
16
+ import { type ClassNameHost } from "./className.js";
17
+ interface SceneComponent extends ClassNameHost {
17
18
  _select?: {
18
19
  node: () => import("d3-selection").BaseType | null;
19
20
  };
@@ -21,6 +22,7 @@ interface SceneComponent {
21
22
  schema: {
22
23
  width?: number;
23
24
  height?: number;
25
+ className?: unknown;
24
26
  };
25
27
  toScene: () => GroupNode;
26
28
  }