@d3plus/core 4.6.0 → 4.7.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 (172) hide show
  1. package/README.md +728 -1454
  2. package/es/index.js.map +1 -1
  3. package/es/internal.js +5 -0
  4. package/es/internal.js.map +1 -1
  5. package/es/src/charts/Chord/index.js +2 -0
  6. package/es/src/charts/Chord/index.js.map +1 -1
  7. package/es/src/charts/Geomap/applyLayout.js +3 -1
  8. package/es/src/charts/Geomap/applyLayout.js.map +1 -1
  9. package/es/src/charts/Geomap/index.js +3 -1
  10. package/es/src/charts/Geomap/index.js.map +1 -1
  11. package/es/src/charts/Matrix/emit.js +5 -4
  12. package/es/src/charts/Matrix/emit.js.map +1 -1
  13. package/es/src/charts/Network/index.js +4 -0
  14. package/es/src/charts/Network/index.js.map +1 -1
  15. package/es/src/charts/Pack/emit.js +6 -6
  16. package/es/src/charts/Pack/emit.js.map +1 -1
  17. package/es/src/charts/Pack/index.js +2 -0
  18. package/es/src/charts/Pack/index.js.map +1 -1
  19. package/es/src/charts/Pie/emit.js +5 -6
  20. package/es/src/charts/Pie/emit.js.map +1 -1
  21. package/es/src/charts/Pie/index.js +2 -0
  22. package/es/src/charts/Pie/index.js.map +1 -1
  23. package/es/src/charts/Plot/index.js +15 -1
  24. package/es/src/charts/Plot/index.js.map +1 -1
  25. package/es/src/charts/Plot/insetRegion.js +21 -0
  26. package/es/src/charts/Plot/insetRegion.js.map +1 -0
  27. package/es/src/charts/Plot/sharedHover.js +117 -16
  28. package/es/src/charts/Plot/sharedHover.js.map +1 -1
  29. package/es/src/charts/Plot/sharedTooltip.js +35 -15
  30. package/es/src/charts/Plot/sharedTooltip.js.map +1 -1
  31. package/es/src/charts/Plot/trendLines.js +140 -38
  32. package/es/src/charts/Plot/trendLines.js.map +1 -1
  33. package/es/src/charts/Plot/trendProjection.js +120 -0
  34. package/es/src/charts/Plot/trendProjection.js.map +1 -0
  35. package/es/src/charts/Plot/trendScene.js +33 -19
  36. package/es/src/charts/Plot/trendScene.js.map +1 -1
  37. package/es/src/charts/Plot/trendTooltip.js +79 -17
  38. package/es/src/charts/Plot/trendTooltip.js.map +1 -1
  39. package/es/src/charts/Priestley/emit.js +3 -4
  40. package/es/src/charts/Priestley/emit.js.map +1 -1
  41. package/es/src/charts/RadialMatrix/emit.js +4 -4
  42. package/es/src/charts/RadialMatrix/emit.js.map +1 -1
  43. package/es/src/charts/Rings/index.js +5 -1
  44. package/es/src/charts/Rings/index.js.map +1 -1
  45. package/es/src/charts/Sankey/index.js +2 -0
  46. package/es/src/charts/Sankey/index.js.map +1 -1
  47. package/es/src/charts/Tree/index.js +2 -0
  48. package/es/src/charts/Tree/index.js.map +1 -1
  49. package/es/src/charts/Treemap/emit.js +3 -4
  50. package/es/src/charts/Treemap/emit.js.map +1 -1
  51. package/es/src/charts/definition/ChartDefinition.js.map +1 -1
  52. package/es/src/charts/definition/makeChart.js +8 -2
  53. package/es/src/charts/definition/makeChart.js.map +1 -1
  54. package/es/src/charts/drawSteps/bottomRightControls.js +3 -0
  55. package/es/src/charts/drawSteps/bottomRightControls.js.map +1 -1
  56. package/es/src/charts/drawSteps/bottomRightControlsMarkup.js +135 -4
  57. package/es/src/charts/drawSteps/bottomRightControlsMarkup.js.map +1 -1
  58. package/es/src/charts/drawSteps/searchControlsMarkup.js +15 -38
  59. package/es/src/charts/drawSteps/searchControlsMarkup.js.map +1 -1
  60. package/es/src/charts/events/click.legend.js +10 -5
  61. package/es/src/charts/events/click.legend.js.map +1 -1
  62. package/es/src/charts/events/mousemove.shape.js +8 -1
  63. package/es/src/charts/events/mousemove.shape.js.map +1 -1
  64. package/es/src/charts/features/emitHelpers.js +19 -5
  65. package/es/src/charts/features/emitHelpers.js.map +1 -1
  66. package/es/src/charts/features/features.js +3 -108
  67. package/es/src/charts/features/features.js.map +1 -1
  68. package/es/src/charts/features/featuresColorScale.js +161 -0
  69. package/es/src/charts/features/featuresColorScale.js.map +1 -0
  70. package/es/src/charts/features/featuresLegend.js +145 -32
  71. package/es/src/charts/features/featuresLegend.js.map +1 -1
  72. package/es/src/charts/features/insetState.js +174 -0
  73. package/es/src/charts/features/insetState.js.map +1 -0
  74. package/es/src/charts/features/sceneBounds.js +271 -0
  75. package/es/src/charts/features/sceneBounds.js.map +1 -0
  76. package/es/src/charts/features/tooltipSwatch.js +73 -0
  77. package/es/src/charts/features/tooltipSwatch.js.map +1 -0
  78. package/es/src/charts/pipeline/insetPlacement.js +406 -0
  79. package/es/src/charts/pipeline/insetPlacement.js.map +1 -0
  80. package/es/src/charts/pipeline/runVizPipeline.js +6 -2
  81. package/es/src/charts/pipeline/runVizPipeline.js.map +1 -1
  82. package/es/src/charts/viz/Viz.js +18 -3
  83. package/es/src/charts/viz/Viz.js.map +1 -1
  84. package/es/src/charts/viz/VizBaseConfig.js +20 -24
  85. package/es/src/charts/viz/VizBaseConfig.js.map +1 -1
  86. package/es/src/charts/viz/interactionOpacity.js +21 -13
  87. package/es/src/charts/viz/interactionOpacity.js.map +1 -1
  88. package/es/src/charts/viz/linkGroup.js +386 -0
  89. package/es/src/charts/viz/linkGroup.js.map +1 -0
  90. package/es/src/charts/viz/sceneRows.js +33 -0
  91. package/es/src/charts/viz/sceneRows.js.map +1 -0
  92. package/es/src/charts/viz/vizDefaults.js +13 -8
  93. package/es/src/charts/viz/vizDefaults.js.map +1 -1
  94. package/es/src/charts/viz/vizTypes.js.map +1 -1
  95. package/es/src/components/Axis/AxisBottom.js +1 -1
  96. package/es/src/components/Axis/AxisBottom.js.map +1 -1
  97. package/es/src/components/Axis/AxisLeft.js +1 -1
  98. package/es/src/components/Axis/AxisLeft.js.map +1 -1
  99. package/es/src/components/Axis/AxisRight.js +1 -1
  100. package/es/src/components/Axis/AxisRight.js.map +1 -1
  101. package/es/src/components/Axis/AxisTop.js +1 -1
  102. package/es/src/components/Axis/AxisTop.js.map +1 -1
  103. package/es/src/components/Axis/axisLayoutLabels.js +13 -1
  104. package/es/src/components/Axis/axisLayoutLabels.js.map +1 -1
  105. package/es/src/components/ColorScale/ColorScale.js.map +1 -1
  106. package/es/src/components/Legend/legendConfig.js +2 -1
  107. package/es/src/components/Legend/legendConfig.js.map +1 -1
  108. package/es/src/components/Legend/legendRender.js +42 -5
  109. package/es/src/components/Legend/legendRender.js.map +1 -1
  110. package/es/src/components/TextBox.js +1 -1
  111. package/es/src/components/TextBox.js.map +1 -1
  112. package/es/src/shapes/Bar.js +1 -1
  113. package/es/src/shapes/Bar.js.map +1 -1
  114. package/es/src/shapes/Box.js +1 -1
  115. package/es/src/shapes/Box.js.map +1 -1
  116. package/es/src/shapes/Rect.js +1 -1
  117. package/es/src/shapes/Rect.js.map +1 -1
  118. package/es/src/shapes/Shape.js +9 -36
  119. package/es/src/shapes/Shape.js.map +1 -1
  120. package/es/src/shapes/Whisker.js +1 -1
  121. package/es/src/shapes/Whisker.js.map +1 -1
  122. package/es/src/shapes/textureKey.js +104 -0
  123. package/es/src/shapes/textureKey.js.map +1 -0
  124. package/es/src/utils/D3plusConfig.js.map +1 -1
  125. package/package.json +10 -9
  126. package/types/index.d.ts +1 -0
  127. package/types/internal.d.ts +7 -0
  128. package/types/src/charts/Plot/index.d.ts +8 -0
  129. package/types/src/charts/Plot/insetRegion.d.ts +4 -0
  130. package/types/src/charts/Plot/sharedHover.d.ts +5 -0
  131. package/types/src/charts/Plot/sharedTooltip.d.ts +10 -0
  132. package/types/src/charts/Plot/trendLines.d.ts +23 -3
  133. package/types/src/charts/Plot/trendProjection.d.ts +28 -0
  134. package/types/src/charts/Plot/trendScene.d.ts +2 -1
  135. package/types/src/charts/Plot/trendTooltip.d.ts +16 -5
  136. package/types/src/charts/definition/ChartDefinition.d.ts +9 -0
  137. package/types/src/charts/definition/makeChart.d.ts +2 -2
  138. package/types/src/charts/drawSteps/bottomRightControlsMarkup.d.ts +2 -0
  139. package/types/src/charts/drawSteps/searchControlsMarkup.d.ts +7 -5
  140. package/types/src/charts/features/emitHelpers.d.ts +10 -4
  141. package/types/src/charts/features/features.d.ts +1 -8
  142. package/types/src/charts/features/featuresColorScale.d.ts +24 -0
  143. package/types/src/charts/features/featuresLegend.d.ts +15 -0
  144. package/types/src/charts/features/insetState.d.ts +95 -0
  145. package/types/src/charts/features/sceneBounds.d.ts +18 -0
  146. package/types/src/charts/features/tooltipSwatch.d.ts +31 -0
  147. package/types/src/charts/pipeline/insetPlacement.d.ts +45 -0
  148. package/types/src/charts/pipeline/runVizPipeline.d.ts +2 -1
  149. package/types/src/charts/viz/Viz.d.ts +9 -1
  150. package/types/src/charts/viz/VizBaseConfig.d.ts +8 -12
  151. package/types/src/charts/viz/linkGroup.d.ts +96 -0
  152. package/types/src/charts/viz/sceneRows.d.ts +13 -0
  153. package/types/src/charts/viz/vizTypes.d.ts +17 -0
  154. package/types/src/components/Axis/AxisBottom.d.ts +1 -1
  155. package/types/src/components/Axis/AxisLeft.d.ts +1 -1
  156. package/types/src/components/Axis/AxisRight.d.ts +1 -1
  157. package/types/src/components/Axis/AxisTop.d.ts +1 -1
  158. package/types/src/components/ColorScale/ColorScale.d.ts +4 -4
  159. package/types/src/components/Legend/legendRender.d.ts +1 -1
  160. package/types/src/components/TextBox.d.ts +1 -1
  161. package/types/src/shapes/Bar.d.ts +1 -1
  162. package/types/src/shapes/Box.d.ts +1 -1
  163. package/types/src/shapes/Rect.d.ts +1 -1
  164. package/types/src/shapes/Whisker.d.ts +1 -1
  165. package/types/src/shapes/textureKey.d.ts +9 -0
  166. package/types/src/utils/D3plusConfig.d.ts +42 -1
  167. package/umd/d3plus-core.full.js +2393 -594
  168. package/umd/d3plus-core.full.js.map +1 -1
  169. package/umd/d3plus-core.full.min.js +1945 -1601
  170. package/umd/d3plus-core.js +1744 -404
  171. package/umd/d3plus-core.js.map +1 -1
  172. package/umd/d3plus-core.min.js +1401 -1087
@@ -0,0 +1,95 @@
1
+ /**
2
+ Shared state for drawing chart chrome (the size legend, legend, or
3
+ colorScale) inside the chart's negative space instead of in a margin.
4
+ The placement itself is decided in `pipeline/insetPlacement.ts`; this
5
+ module holds the types and the small queries the features use while they
6
+ lay out, so they don't depend on the placement pipeline.
7
+
8
+ @module
9
+ */
10
+ import type { Bounds } from "@d3plus/math";
11
+ import type { SceneNode } from "@d3plus/render";
12
+ import type { VizInstance } from "../viz/vizTypes.js";
13
+ /** The chrome that can be drawn inside the chart, in the order it is tried. */
14
+ export type InsetKey = "sizeLegend" | "legend" | "colorScale";
15
+ export declare const INSET_PRIORITY: InsetKey[];
16
+ /** How a legend or colorScale is laid out when drawn inside the chart. */
17
+ export type InsetOrient = "column" | "row";
18
+ /** The region a chart offers for inset chrome, in surface coordinates. */
19
+ export interface InsetRegion {
20
+ /** The area chrome may be drawn in (e.g. the plot area). */
21
+ bounds: Bounds;
22
+ /** The boxes of the chart's marks, which chrome must stay clear of. */
23
+ obstacles: Bounds[];
24
+ }
25
+ /** Where the inset chrome landed: its background box, in surface coordinates. */
26
+ export interface InsetPlacement extends Bounds {
27
+ key: InsetKey;
28
+ orient: InsetOrient;
29
+ /** Which side of its open space the box hugs, so content smaller than it can keep to that side. */
30
+ alignX: "left" | "center" | "right";
31
+ alignY: "top" | "middle" | "bottom";
32
+ }
33
+ /**
34
+ Seeds `legendInset`/`legendInsetConfig`, and remembers the default
35
+ legend/colorScale position accessors so a placement can tell a position
36
+ the user chose (which it leaves alone) from the default. Runs after the
37
+ legend and color defaults are seeded.
38
+ */
39
+ export declare function initInsetDefaults(viz: VizInstance): void;
40
+ /** Resolved `legendInsetConfig`. */
41
+ export interface InsetStyle {
42
+ /** Gap kept between the box and the chart's marks and edges. */
43
+ padding: number;
44
+ /** Space between the box's edge and the chrome inside it. */
45
+ margin: number;
46
+ fill?: string;
47
+ fillOpacity: number;
48
+ stroke?: string;
49
+ strokeWidth: number;
50
+ rx: number;
51
+ }
52
+ /** The resolved background-box style, with the chart's defaults filled in. */
53
+ export declare function insetStyle(viz: VizInstance): InsetStyle;
54
+ /** Whether `key` is being laid out for the chart's interior this pass (so it claims no margin). */
55
+ export declare function isInsetPending(viz: VizInstance, key: InsetKey): boolean;
56
+ /** The final placement of `key`, or null when it isn't drawn inside the chart. */
57
+ export declare function insetPlacementFor(viz: VizInstance, key: InsetKey): InsetPlacement | null;
58
+ /** The orientation `key` is laid out with when inset (column until placement picks one). */
59
+ export declare function insetOrient(viz: VizInstance, key: InsetKey): InsetOrient;
60
+ /**
61
+ The largest frame a legend or colorScale may lay itself out in when inset,
62
+ for a chart area of `area`: a column takes up to 40% of the width and 60%
63
+ of the height, a row the reverse.
64
+ */
65
+ export declare function insetFrame(orient: InsetOrient, area: {
66
+ width: number;
67
+ height: number;
68
+ }): {
69
+ width: number;
70
+ height: number;
71
+ };
72
+ /** The semi-transparent box drawn behind inset chrome, so it stays legible over marks panned beneath it. */
73
+ export declare function insetBackground(viz: VizInstance, placement: InsetPlacement): SceneNode;
74
+ /**
75
+ The scene children for a legend or colorScale component: just its own
76
+ scene normally, or — when it's drawn inside the chart — its background box
77
+ plus its scene moved into the box. `bounds` is the component's
78
+ `outerBounds()` (its content box within its own frame).
79
+ */
80
+ export declare function insetComponentScene(viz: VizInstance, key: InsetKey, scene: SceneNode, bounds: {
81
+ x?: number;
82
+ y?: number;
83
+ }): SceneNode[];
84
+ /**
85
+ Where a legend or colorScale component's own frame goes so its content
86
+ (`bounds`, its `outerBounds()`) lands inside its placed box; null when it
87
+ isn't drawn inside the chart.
88
+ */
89
+ export declare function insetComponentOffset(viz: VizInstance, key: InsetKey, bounds: {
90
+ x?: number;
91
+ y?: number;
92
+ }): {
93
+ x: number;
94
+ y: number;
95
+ } | null;
@@ -0,0 +1,18 @@
1
+ /**
2
+ Bounding boxes of a chart's data marks, read off its scene graph — the
3
+ obstacles `negativeSpace` keeps chart chrome clear of.
4
+
5
+ @module
6
+ */
7
+ import type { Bounds } from "@d3plus/math";
8
+ import type { SceneNode, Transform } from "@d3plus/render";
9
+ /**
10
+ Boxes, in the coordinate space of `nodes` after `base` is applied, of
11
+ every data mark and label in a scene: datum-bearing nodes at any depth,
12
+ with group transforms composed. `::hit` duplicates and chart decorations
13
+ (axes, gridlines and other nodes without a datum) are skipped.
14
+ @param nodes The chart's scene nodes (e.g. `viz._chartScene`).
15
+ @param base A transform applied to all of them (e.g. `viz._chartTransform`).
16
+ @param skip Excludes a node and everything inside it, for decorations that carry a datum (like axis ticks).
17
+ */
18
+ export declare function markBoxes(nodes: SceneNode[], base?: Transform, skip?: (node: SceneNode) => boolean): Bounds[];
@@ -0,0 +1,31 @@
1
+ /**
2
+ The small colored glyph that ties a tooltip row or title to the mark it
3
+ describes, matching the legend's swatches: a dot with a short line through
4
+ it for a Line, a dot for a Circle, and a square for everything else.
5
+ */
6
+ import type { SceneNode } from "@d3plus/render";
7
+ import type { VizInstance } from "../viz/vizTypes.js";
8
+ /**
9
+ A swatch's HTML for a mark of `shape` in `color`, to lead a tooltip title
10
+ or row (see `withSwatch`). Empty without a color.
11
+ @param color The mark's color.
12
+ @param shape The mark's shape type (e.g. "Line", "Circle", "Bar").
13
+ */
14
+ export declare function tooltipSwatch(color?: string, shape?: string): string;
15
+ /**
16
+ Leads `text` with a swatch, centered on the text however large or bold it
17
+ is (a tooltip title, or a row's name). Just `text` without a swatch.
18
+ @param swatch The swatch HTML, from `tooltipSwatch`.
19
+ @param text The title or name it leads.
20
+ */
21
+ export declare function withSwatch(swatch: string, text: unknown): string;
22
+ /** A paint color that actually shows: not unset, "none", or transparent. */
23
+ export declare const visibleColor: (s: unknown) => string | undefined;
24
+ /**
25
+ The color a picked scene node draws in: a Line's stroke, otherwise its
26
+ fill (or stroke, for an unfilled mark). A transparent hover target (a
27
+ `::hit` node) reads its visible sibling's paint.
28
+ @param viz The chart, whose scene holds the sibling.
29
+ @param node The picked scene node.
30
+ */
31
+ export declare function nodeColor(viz: VizInstance, node: SceneNode | undefined): string | undefined;
@@ -0,0 +1,45 @@
1
+ /**
2
+ Draws one piece of chart chrome — the size legend, else the legend, else
3
+ the colorScale — inside the chart's negative space instead of in a
4
+ margin, when the chart offers a region (`ChartDefinition.insetRegion`)
5
+ and `legendInset` is on.
6
+
7
+ Placement needs the chart's laid-out marks, but chrome normally claims
8
+ its margin before the chart lays out, so the draw runs optimistically:
9
+ 1. Every candidate skips its margin claim, and the chart lays out in
10
+ the full area.
11
+ 2. The open space around the marks (`negativeSpace`) is searched for
12
+ the first candidate, in priority order, that fits.
13
+ 3. If one fits and nothing else is waiting on a margin, that draw
14
+ stands. If other candidates are showing, the chart lays out again
15
+ with them back in their margins, and the winner is fitted again in
16
+ the (smaller) chart. When nothing fits, the chart lays out normally.
17
+
18
+ @module
19
+ */
20
+ import type { Bounds } from "@d3plus/math";
21
+ import type { SceneNode } from "@d3plus/render";
22
+ import type { InsetPlacement, InsetRegion } from "../features/insetState.js";
23
+ import type { VizInstance } from "../viz/vizTypes.js";
24
+ /**
25
+ The default inset region: the chart area (or `bounds`, in surface
26
+ coordinates), with the boxes of every data mark in the chart's scene as
27
+ obstacles (less any subtree `skip` excludes). Charts opt in by returning
28
+ this from their `insetRegion`.
29
+ */
30
+ export declare function sceneInsetRegion(viz: VizInstance, bounds?: Bounds, skip?: (node: SceneNode) => boolean): InsetRegion;
31
+ /**
32
+ Where a box of `width` × `height` sits in the open rects (sorted largest
33
+ first): in the first chart corner, in `CORNERS` order, that some rect
34
+ reaching that corner has room for. When it fits in no corner, it goes in
35
+ the first rect it fits, against whichever of the rect's sides lie on the
36
+ region's edges (bottom-right when it touches both), centered along an
37
+ axis otherwise.
38
+ */
39
+ export declare function fitInset(rects: Bounds[], bounds: Bounds, width: number, height: number): (Bounds & Pick<InsetPlacement, "alignX" | "alignY">) | null;
40
+ /**
41
+ `viz._draw()`, placing chrome inside the chart's negative space when it
42
+ fits (see the module docs). Leaves `viz._insetPlacement` set to what was
43
+ placed, or null.
44
+ */
45
+ export declare function drawWithInset(viz: VizInstance): void;
@@ -13,7 +13,8 @@
13
13
  callback:
14
14
 
15
15
  1. `viz._preDraw()` — data filtering + legend-data + drawDepth
16
- 2. `viz._draw()` — chart-specific layout + scene absorption
16
+ 2. `viz._draw()` — chart-specific layout + scene absorption, re-run
17
+ when chrome is placed inside the chart (`drawWithInset`)
17
18
  3. `zoomControls(viz)` — zoom HTML overlay (architectural carve-out)
18
19
  4. `minimapFeature.layout(viz)` — zoomed-chart viewport indicator
19
20
  5. `topLeftControlsFeature.layout(viz)` — back/table-view/search panel
@@ -2,8 +2,9 @@ import type { DataPoint } from "@d3plus/data";
2
2
  import type { PickResult, Renderer, Scene, SceneEvent } from "@d3plus/render";
3
3
  import VizBase from "./VizBase.js";
4
4
  import type { SizeLegendScale } from "../../components/SizeLegend/sizeLegendLayout.js";
5
+ import type { InsetRegion } from "../features/insetState.js";
5
6
  /**
6
- Creates an x/y plot based on an array of data. See [this example](https://d3plus.org/examples/d3plus-treemap/getting-started/) for help getting started using the treemap generator.
7
+ The base class every d3plus chart extends. Owns the shared configuration surface (data, groupBy, size and color accessors, title, legend, tooltip, timeline, zoom, table view) and the render lifecycle that each chart type's definition plugs its layout into. Not used directly; see the chart classes (BarChart, Treemap, …).
7
8
  */
8
9
  export default class Viz extends VizBase {
9
10
  /**
@@ -40,6 +41,13 @@ export default class Viz extends VizBase {
40
41
  width: number;
41
42
  height: number;
42
43
  }): SizeLegendScale | null;
44
+ /**
45
+ The region chart chrome may be drawn inside, with the chart's mark boxes
46
+ as obstacles (see `ChartDefinition.insetRegion`). Charts that leave
47
+ negative space override this; the base chart offers none.
48
+ @private
49
+ */
50
+ _insetRegion(): InsetRegion | null;
43
51
  /**
44
52
  * Applies the threshold algorithm according to the type of chart used.
45
53
  * @param {Array} data The data to process.
@@ -106,18 +106,6 @@ export default class VizBaseConfig extends BaseClass {
106
106
  When `true` (the default) and `detectVisible` is enabled, the Viz releases its DOM and scene while it is scrolled out of view and redraws when it returns, keeping the page light when there are many visualizations. Data and configuration are retained; interaction state such as zoom or selection is not, so set this to `false` to keep it. With `detectVisible` enabled, each chart's `<svg>` is also given `content-visibility: auto`, so the browser skips rendering its contents while it is far off-screen (this matters most when this is `false` and charts are kept). For a larger saving you can also apply `content-visibility: auto` and a `contain-intrinsic-size` to the container element yourself; that adds paint containment to an element you own, so it is not done automatically. Requires `IntersectionObserver`.
107
107
  */
108
108
  detectVisibleUnload(_?: boolean): this | boolean;
109
- /**
110
- Shows a button that allows for downloading the current visualization.
111
- */
112
- downloadButton(_?: boolean): this | boolean;
113
- /**
114
- Sets specific options of the saveElement function used when downloading the visualization.
115
- */
116
- downloadConfig(_?: Record<string, unknown>): this | Record<string, unknown>;
117
- /**
118
- Defines which control group to add the download button into.
119
- */
120
- downloadPosition(_?: string): this | string;
121
109
  /**
122
110
  The font family used throughout the visualization.
123
111
  */
@@ -164,6 +152,14 @@ export default class VizBaseConfig extends BaseClass {
164
152
  Defines the click functionality of categorical legend squares. When set to false, clicking will hide that category and shift+clicking will solo that category. When set to true, clicking with solo that category and shift+clicking will hide that category.
165
153
  */
166
154
  legendFilterInvert(_?: boolean | ((viz: VizBase) => boolean)): this | boolean | ((viz: VizBase) => boolean);
155
+ /**
156
+ Whether the chart may draw one of its legends inside the empty space around its marks instead of in a margin, for charts that leave room (Plot, Network, Pack, Pie, Rings, Tree, and Geomap). After the chart lays out, the size legend is tried first, then the legend, then the colorScale; the first that fits is drawn over a semi-transparent box (see `legendInsetConfig`), and any others keep their margins. Space enclosed by the marks, like the middle of a ring of points, is never used. A legend or colorScale whose position was set explicitly stays in that margin. Defaults to `true`; also accepts a function that receives the resolved chart config and returns a boolean.
157
+ */
158
+ legendInset(_?: boolean | ((config: Record<string, unknown>) => boolean)): this | boolean | ((config: Record<string, unknown>) => boolean);
159
+ /**
160
+ Style of the box drawn behind a legend placed inside the chart (see `legendInset`): `fill` (defaults to the chart's background color), `fillOpacity` (0.85), `stroke` (defaults to a faint contrasting line), `strokeWidth` (1), `rx` (corner radius, 4), `margin` (space between the box's edge and the legend, 6), and `padding` (space kept between the box and the chart's marks and edges, 10).
161
+ */
162
+ legendInsetConfig(_?: Record<string, unknown>): this | Record<string, unknown>;
167
163
  /**
168
164
  Tells the legend whether or not to use the internal padding defined by the visualization in it's positioning. For example, d3plus-plot will add padding on the left so that the legend appears centered underneath the x-axis. By default, this padding is only applied on screens larger than 600 pixels wide.
169
165
  */
@@ -0,0 +1,96 @@
1
+ import type { ColorDefaults } from "@d3plus/color";
2
+ import type { DataPoint } from "@d3plus/data";
3
+ import type { VizInstance } from "./vizTypes.js";
4
+ type Predicate = (d: DataPoint, i: number) => boolean;
5
+ /** The interaction states a link group mirrors through a predicate. */
6
+ export type LinkKind = "hover" | "active" | "highlight";
7
+ /** The object form of the `link` config: a group name plus the key and interactions to mirror. */
8
+ export interface LinkConfig {
9
+ /** Charts that share a group name are linked. */
10
+ group: string;
11
+ /** The value two charts' rows match on. A string is a data key. Defaults to the chart's own id. */
12
+ by?: string | ((d: DataPoint, i: number) => unknown);
13
+ /** Mirror hover. Defaults to `true`. */
14
+ hover?: boolean;
15
+ /** Mirror `active`. Defaults to `true`. */
16
+ active?: boolean;
17
+ /** Mirror `highlight` (including the search box). Defaults to `true`. */
18
+ highlight?: boolean;
19
+ /** Mirror legend hide/solo clicks. Defaults to `true`. */
20
+ legend?: boolean;
21
+ /** Share categorical color assignments, so a value gets the same color in every linked chart. Defaults to `true`; a chart that sets its own `colorDefaults.scale` keeps it. */
22
+ color?: boolean;
23
+ }
24
+ /** `link` as a group name, the full object form, or `false` for unlinked. */
25
+ export type LinkOption = string | false | LinkConfig;
26
+ /** A chart's `link` config with defaults filled in and `by` resolved to a function. */
27
+ export interface ResolvedLink {
28
+ group: string;
29
+ by: (d: DataPoint, i: number) => unknown;
30
+ hover: boolean;
31
+ active: boolean;
32
+ highlight: boolean;
33
+ legend: boolean;
34
+ color: boolean;
35
+ }
36
+ /** The parts of a chart `resolveLink` and `linkedColorDefaults` read. */
37
+ type LinkTarget = Pick<VizInstance, "schema"> & Partial<Pick<VizInstance, "_id" | "_linkGroup" | "_autoColorScale">>;
38
+ /** Normalizes a chart's `link` config, or returns null when it isn't linked. */
39
+ export declare function resolveLink(viz: LinkTarget): ResolvedLink | null;
40
+ /** Adds the chart to its `link` group, leaving any group it was in before. */
41
+ export declare function registerLink(viz: VizInstance): void;
42
+ /** Removes the chart from its `link` group, if any. */
43
+ export declare function unregisterLink(viz: VizInstance): void;
44
+ /** The charts currently registered under a group name. */
45
+ export declare function linkMembers(group: string): VizInstance[];
46
+ /**
47
+ The color defaults `viz` assigns categorical colors from. A linked chart
48
+ still on its own default scale (`viz._autoColorScale`) shares one scale
49
+ with the rest of its group, so each value takes the same color in every
50
+ chart however the charts order their data; the first chart to join seeds
51
+ the group's palette. A chart given its own `colorDefaults.scale`, or linked
52
+ with `color: false`, keeps its own.
53
+ */
54
+ export declare function linkedColorDefaults(viz: LinkTarget): ColorDefaults;
55
+ /**
56
+ Flattens a `by` value into comparable string keys: arrays (from
57
+ aggregated rows whose members disagree) contribute every entry, Dates
58
+ compare by time, and null/undefined contribute nothing.
59
+ */
60
+ export declare function linkKeys(value: unknown): string[];
61
+ /**
62
+ The `by` keys of every row in `viz` that `predicate` matches. Evaluates
63
+ over the painted marks (`_chartScene`), which are the rows the predicate
64
+ was written against; before a first paint it falls back to the filtered
65
+ data.
66
+ */
67
+ export declare function linkValues(viz: VizInstance, by: (d: DataPoint, i: number) => unknown, predicate: Predicate): Set<string>;
68
+ /**
69
+ A predicate matching the rows whose `by` keys include one of `values`. An
70
+ empty set matches nothing, so a chart without the linked value dims
71
+ entirely.
72
+ */
73
+ export declare function linkPredicate(link: ResolvedLink, values: Set<string>): Predicate;
74
+ /**
75
+ Overrides which rows the next broadcast from `viz` treats as matched,
76
+ for an interaction whose own predicate also matches marks it doesn't
77
+ mean to emphasize (Plot's stacked column hover keeps non-bar marks
78
+ bright). Consumed by the next `broadcastLink` call.
79
+ */
80
+ export declare function linkAs(viz: VizInstance, predicate: Predicate): void;
81
+ /**
82
+ Mirrors `viz`'s new hover/active/highlight state onto the rest of its link
83
+ group. A predicate becomes a match on its rows' `by` values; `false`
84
+ clears the same state everywhere.
85
+ */
86
+ export declare function broadcastLink(viz: VizInstance, kind: LinkKind, predicate: unknown): void;
87
+ /**
88
+ Mirrors `viz`'s legend hide/solo state onto the rest of its link group,
89
+ then re-renders each chart that changed. Matching goes through `by`, so
90
+ charts with different legend groupings still line up: a target legend item
91
+ is solo'd when any of its keys is solo'd in the source, and hidden when all
92
+ of its keys are hidden there. A target that hasn't drawn its legend yet is
93
+ skipped.
94
+ */
95
+ export declare function broadcastLegend(viz: VizInstance): void;
96
+ export {};
@@ -0,0 +1,13 @@
1
+ import type { DataPoint } from "@d3plus/data";
2
+ import type { SceneNode } from "@d3plus/render";
3
+ /** Scene mark types that carry a datum hover/active/highlight/search apply to. */
4
+ export declare const MARK_TYPES: Set<string>;
5
+ /**
6
+ Calls `fn` once per painted data mark in `nodes`, with the mark's source
7
+ row and index. The row is unwrapped one level (`datum.data ?? datum`) and
8
+ the index resolved `node.index` → `row.i` → 0, the same way
9
+ `applyInteractionOpacity` evaluates its predicates, so a predicate sees the
10
+ same arguments here as it does when the scene is dimmed. Rows are de-duped
11
+ by reference, so a mark's separate label node doesn't visit it twice.
12
+ */
13
+ export declare function forEachSceneRow(nodes: SceneNode[], fn: (row: DataPoint, i: number, node: SceneNode) => void): void;
@@ -29,6 +29,7 @@ import type { DataPoint } from "@d3plus/data";
29
29
  import type { ClipShape, SceneNode, Transform, TransitionRect } from "@d3plus/render";
30
30
  import type { Axis, ColorScale, Legend, Message, SizeLegend, TextBox, Timeline, Tooltip } from "../../components/index.js";
31
31
  import type { SizeLegendScale } from "../../components/SizeLegend/sizeLegendLayout.js";
32
+ import type { InsetKey, InsetPlacement, InsetRegion } from "../features/insetState.js";
32
33
  import type Shape from "../../shapes/Shape.js";
33
34
  import type { D3plusConfig, D3Scale } from "../../utils/index.js";
34
35
  import type { PlotPaintContext } from "../features/plotPaint.js";
@@ -183,6 +184,10 @@ export interface VizInstance {
183
184
  /** True while the current hover came from a colorScale bucket swatch. */
184
185
  _hoverBucket?: boolean;
185
186
  _highlight?: ((d: DataPoint, i?: number) => boolean) | false;
187
+ /** The `link` group this chart is registered under (see `linkGroup.ts`). */
188
+ _linkGroup?: string;
189
+ /** The categorical scale `initColorDefaults` created; linked charts still using it share their group's instead. */
190
+ _autoColorScale?: unknown;
186
191
  /** Whether the search control's input is currently open. */
187
192
  _searchOpen?: boolean;
188
193
  /** The search control's current (lowercased) search term. */
@@ -355,6 +360,15 @@ export interface VizInstance {
355
360
  _sizeLegendClass?: SizeLegend;
356
361
  /** The bottom-right corner panel reserved in `vizDrawPure` for this draw (see `bottomRightControlsMarkup.ts`). */
357
362
  _bottomRightBox?: BottomRightBox | null;
363
+ /** Chrome being laid out for the chart's interior this pass, which claims no margin (see `pipeline/insetPlacement.ts`). */
364
+ _insetPending?: Set<InsetKey> | null;
365
+ /** The chrome drawn inside the chart's negative space this draw, and where. */
366
+ _insetPlacement?: InsetPlacement | null;
367
+ /** The default `legendPosition`/`colorScalePosition` accessors; a different one means the user picked a side. */
368
+ _insetAutoPositions?: {
369
+ legend: unknown;
370
+ colorScale: unknown;
371
+ };
358
372
  /** Per-axis "is this axis time-valued" flags, set by `formatPlotData`. */
359
373
  _xTime?: boolean;
360
374
  _x2Time?: boolean;
@@ -459,10 +473,13 @@ export interface VizInstance {
459
473
  width: number;
460
474
  height: number;
461
475
  }): SizeLegendScale | null;
476
+ /** The region chart chrome may be drawn inside, with the chart's marks as obstacles (see `ChartDefinition.insetRegion`). */
477
+ _insetRegion?(): InsetRegion | null;
462
478
  toScene?(): SceneNode;
463
479
  config?(_?: D3plusConfig): D3plusConfig | this;
464
480
  active?(_?: unknown): unknown;
465
481
  hover?(_?: unknown): unknown;
482
+ highlight?(_?: unknown): unknown;
466
483
  timeFilter?(_?: ((d: DataPoint, i: number) => boolean) | false): VizInstance;
467
484
  render?(callback?: () => void): VizInstance;
468
485
  }
@@ -1,6 +1,6 @@
1
1
  import { default as Axis } from "./Axis.js";
2
2
  /**
3
- Shorthand method for creating an axis where the ticks are drawn below the horizontal domain path. Extends all functionality of the base [Axis](#Axis) class.
3
+ Axis preset whose ticks are drawn below the horizontal domain path. Accepts everything the base Axis class does.
4
4
  */
5
5
  export default class AxisBottom extends Axis {
6
6
  /**
@@ -1,6 +1,6 @@
1
1
  import { default as Axis } from "./Axis.js";
2
2
  /**
3
- Shorthand method for creating an axis where the ticks are drawn to the left of the vertical domain path. Extends all functionality of the base [Axis](#Axis) class.
3
+ Axis preset whose ticks are drawn to the left of the vertical domain path. Accepts everything the base Axis class does.
4
4
  */
5
5
  export default class AxisLeft extends Axis {
6
6
  /**
@@ -1,6 +1,6 @@
1
1
  import { default as Axis } from "./Axis.js";
2
2
  /**
3
- Shorthand method for creating an axis where the ticks are drawn to the right of the vertical domain path. Extends all functionality of the base [Axis](#Axis) class.
3
+ Axis preset whose ticks are drawn to the right of the vertical domain path. Accepts everything the base Axis class does.
4
4
  */
5
5
  export default class AxisRight extends Axis {
6
6
  /**
@@ -1,6 +1,6 @@
1
1
  import { default as Axis } from "./Axis.js";
2
2
  /**
3
- Shorthand method for creating an axis where the ticks are drawn above the vertical domain path. Extends all functionality of the base [Axis](#Axis) class.
3
+ Axis preset whose ticks are drawn above the horizontal domain path. Accepts everything the base Axis class does.
4
4
  */
5
5
  export default class AxisTop extends Axis {
6
6
  /**
@@ -52,7 +52,7 @@ export default class ColorScale extends BaseClass {
52
52
  */
53
53
  toScene(): GroupNode;
54
54
  /**
55
- The [ColorScale](http://d3plus.org/docs/#ColorScale) is constructed by combining an [Axis](http://d3plus.org/docs/#Axis) for the ticks/labels and a [Rect](http://d3plus.org/docs/#Rect) for the actual color box (or multiple boxes, as in a jenks scale). Because of this, there are separate configs for the [Axis](http://d3plus.org/docs/#Axis) class used to display the text ([axisConfig](http://d3plus.org/docs/#ColorScale.axisConfig)) and the [Rect](http://d3plus.org/docs/#Rect) class used to draw the color breaks ([rectConfig](http://d3plus.org/docs/#ColorScale.rectConfig)). This method acts as a pass-through to the config method of the [Axis](http://d3plus.org/docs/#Axis). An example usage of this method can be seen [here](http://d3plus.org/examples/d3plus-legend/colorScale-dark/).
55
+ The ColorScale is constructed by combining an Axis for the ticks/labels and a Rect for the actual color box (or multiple boxes, as in a jenks scale). Because of this, there are separate configs for the Axis class used to display the text (axisConfig) and the Rect class used to draw the color breaks (rectConfig). This method acts as a pass-through to the config method of the Axis.
56
56
  */
57
57
  axisConfig(): Record<string, unknown>;
58
58
  axisConfig(_: Record<string, unknown>): this;
@@ -62,7 +62,7 @@ export default class ColorScale extends BaseClass {
62
62
  data(): DataPoint[];
63
63
  data(_: DataPoint[]): this;
64
64
  /**
65
- A pass-through for the [TextBox](http://d3plus.org/docs/#TextBox) class used to style the labelMin and labelMax text.
65
+ A pass-through for the TextBox class used to style the labelMin and labelMax text.
66
66
  */
67
67
  labelConfig(): Record<string, unknown>;
68
68
  labelConfig(_: Record<string, unknown>): this;
@@ -77,7 +77,7 @@ export default class ColorScale extends BaseClass {
77
77
  labelMax(): string | undefined;
78
78
  labelMax(_: string): this;
79
79
  /**
80
- The [ColorScale](http://d3plus.org/docs/#ColorScale) is constructed by combining an [Axis](http://d3plus.org/docs/#Axis) for the ticks/labels and a [Rect](http://d3plus.org/docs/#Rect) for the actual color box (or multiple boxes, as in a jenks scale). Because of this, there are separate configs for the [Axis](http://d3plus.org/docs/#Axis) class used to display the text ([axisConfig](http://d3plus.org/docs/#ColorScale.axisConfig)) and the [Rect](http://d3plus.org/docs/#Rect) class used to draw the color breaks ([rectConfig](http://d3plus.org/docs/#ColorScale.rectConfig)). This method acts as a pass-through to the config method of the [Axis](http://d3plus.org/docs/#Axis). An example usage of this method can be seen [here](http://d3plus.org/examples/d3plus-legend/colorScale-dark/).
80
+ Configuration passed to the Legend that draws the scale when its values are rendered as discrete swatches instead of a continuous bar (for example a categorical or buckets scale), acting as a pass-through to that Legend's config method.
81
81
  */
82
82
  legendConfig(): Record<string, unknown>;
83
83
  legendConfig(_: Record<string, unknown>): this;
@@ -88,7 +88,7 @@ export default class ColorScale extends BaseClass {
88
88
  */
89
89
  outerBounds(): Record<string, number>;
90
90
  /**
91
- The [ColorScale](http://d3plus.org/docs/#ColorScale) is constructed by combining an [Axis](http://d3plus.org/docs/#Axis) for the ticks/labels and a [Rect](http://d3plus.org/docs/#Rect) for the actual color box (or multiple boxes, as in a jenks scale). Because of this, there are separate configs for the [Axis](http://d3plus.org/docs/#Axis) class used to display the text ([axisConfig](http://d3plus.org/docs/#ColorScale.axisConfig)) and the [Rect](http://d3plus.org/docs/#Rect) class used to draw the color breaks ([rectConfig](http://d3plus.org/docs/#ColorScale.rectConfig)). This method acts as a pass-through to the config method of the [Rect](http://d3plus.org/docs/#Rect). An example usage of this method can be seen [here](http://d3plus.org/examples/d3plus-legend/colorScale-dark/).
91
+ The ColorScale is constructed by combining an Axis for the ticks/labels and a Rect for the actual color box (or multiple boxes, as in a jenks scale). Because of this, there are separate configs for the Axis class used to display the text (axisConfig) and the Rect class used to draw the color breaks (rectConfig). This method acts as a pass-through to the config method of the Rect.
92
92
  */
93
93
  rectConfig(): Record<string, unknown>;
94
94
  rectConfig(_: Record<string, unknown>): this;
@@ -18,5 +18,5 @@ export declare function clearLegend(legend: Legend): void;
18
18
  export declare function computeLegendBounds(legend: Legend, spaceNeeded: number): void;
19
19
  /** Renders the title TextBox into the legend's title group. */
20
20
  export declare function renderLegendTitle(legend: Legend): void;
21
- /** Builds the per-shape data and renders the Circle/Rect swatch groups. */
21
+ /** Builds the per-shape data and renders the Circle/Rect swatch groups (Line entries draw in both). */
22
22
  export declare function renderLegendShapes(legend: Legend): void;
@@ -38,7 +38,7 @@ interface TextBoxDatum {
38
38
  y: number;
39
39
  }
40
40
  /**
41
- Creates a wrapped text box for each point in an array of data. See [this example](https://d3plus.org/examples/d3plus-text/getting-started/) for help getting started using the TextBox class.
41
+ Creates a wrapped text box for each point in an array of data.
42
42
  */
43
43
  export default class TextBox extends BaseClass {
44
44
  [key: string]: any;
@@ -4,7 +4,7 @@ import type { AccessorFn } from "../utils/index.js";
4
4
  import type { BarConfig } from "./shapeConfig.js";
5
5
  import Shape, { type ShapeAes } from "./Shape.js";
6
6
  /**
7
- Creates SVG areas based on an array of data.
7
+ Creates SVG bars based on an array of data.
8
8
  */
9
9
  export default class Bar extends Shape {
10
10
  /**
@@ -7,7 +7,7 @@ import Rect from "./Rect.js";
7
7
  import type { BoxConfig } from "./shapeConfig.js";
8
8
  import Whisker from "./Whisker.js";
9
9
  /**
10
- Creates SVG box based on an array of data.
10
+ Creates SVG box-and-whisker plots based on an array of data, one per group of values.
11
11
  */
12
12
  export default class Box extends BaseClass {
13
13
  [key: string]: any;
@@ -3,7 +3,7 @@ import type { D3Selection } from "@d3plus/dom";
3
3
  import type { RectConfig } from "./shapeConfig.js";
4
4
  import Shape, { type ShapeAes } from "./Shape.js";
5
5
  /**
6
- Creates SVG rectangles based on an array of data. See [this example](https://d3plus.org/examples/d3plus-shape/getting-started/) for help getting started using the rectangle generator.
6
+ Creates SVG rectangles based on an array of data.
7
7
  */
8
8
  export default class Rect extends Shape {
9
9
  /**
@@ -7,7 +7,7 @@ import Line from "./Line.js";
7
7
  import Rect from "./Rect.js";
8
8
  import type { WhiskerConfig } from "./shapeConfig.js";
9
9
  /**
10
- Creates SVG whisker based on an array of data.
10
+ Creates SVG whiskers based on an array of data: a line from each point in a given direction, capped with an endpoint shape.
11
11
  */
12
12
  export default class Whisker extends BaseClass {
13
13
  [key: string]: any;
@@ -0,0 +1,9 @@
1
+ /**
2
+ Builds the JSON key of a textures.js config for one datum, or `false` when
3
+ the datum has no texture or no fill (`"none"`, e.g. a line or link). The key is what a `pattern:<key>` scene fill
4
+ carries for the renderer backends to materialize. `fill` and `stroke` are
5
+ the shape's resolved fill and stroke for the datum, used as the texture's
6
+ default background and line colors.
7
+ @private
8
+ */
9
+ export declare function textureKey(textureVal: unknown, fill: () => unknown, stroke: () => unknown, textureDefault?: Record<string, unknown>): string | false;