@d3plus/core 4.0.0 → 4.2.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 (79) hide show
  1. package/README.md +947 -921
  2. package/es/src/charts/AreaPlot/index.js +2 -1
  3. package/es/src/charts/AreaPlot/index.js.map +1 -1
  4. package/es/src/charts/BarChart/index.js +3 -1
  5. package/es/src/charts/BarChart/index.js.map +1 -1
  6. package/es/src/charts/BoxWhisker/index.js +2 -1
  7. package/es/src/charts/BoxWhisker/index.js.map +1 -1
  8. package/es/src/charts/BumpChart/index.js +2 -1
  9. package/es/src/charts/BumpChart/index.js.map +1 -1
  10. package/es/src/charts/Geomap/index.js +2 -1
  11. package/es/src/charts/Geomap/index.js.map +1 -1
  12. package/es/src/charts/LinePlot/index.js +2 -1
  13. package/es/src/charts/LinePlot/index.js.map +1 -1
  14. package/es/src/charts/Matrix/index.js +1 -0
  15. package/es/src/charts/Matrix/index.js.map +1 -1
  16. package/es/src/charts/Network/index.js +2 -1
  17. package/es/src/charts/Network/index.js.map +1 -1
  18. package/es/src/charts/Pack/index.js +1 -0
  19. package/es/src/charts/Pack/index.js.map +1 -1
  20. package/es/src/charts/Pie/index.js +1 -0
  21. package/es/src/charts/Pie/index.js.map +1 -1
  22. package/es/src/charts/Plot/index.js +22 -12
  23. package/es/src/charts/Plot/index.js.map +1 -1
  24. package/es/src/charts/Plot/pipelineDomains.js +3 -3
  25. package/es/src/charts/Plot/pipelineDomains.js.map +1 -1
  26. package/es/src/charts/Plot/stackHelpers.js +128 -9
  27. package/es/src/charts/Plot/stackHelpers.js.map +1 -1
  28. package/es/src/charts/Radar/index.js +2 -1
  29. package/es/src/charts/Radar/index.js.map +1 -1
  30. package/es/src/charts/RadialMatrix/index.js +1 -0
  31. package/es/src/charts/RadialMatrix/index.js.map +1 -1
  32. package/es/src/charts/Rings/index.js +2 -1
  33. package/es/src/charts/Rings/index.js.map +1 -1
  34. package/es/src/charts/Sankey/index.js +2 -1
  35. package/es/src/charts/Sankey/index.js.map +1 -1
  36. package/es/src/charts/Tree/index.js +2 -1
  37. package/es/src/charts/Tree/index.js.map +1 -1
  38. package/es/src/charts/Treemap/index.js +1 -0
  39. package/es/src/charts/Treemap/index.js.map +1 -1
  40. package/es/src/charts/events/click.legend.js +1 -1
  41. package/es/src/charts/events/click.legend.js.map +1 -1
  42. package/es/src/charts/events/mousemove.legend.js +1 -1
  43. package/es/src/charts/events/mousemove.legend.js.map +1 -1
  44. package/es/src/charts/features/features.js +3 -3
  45. package/es/src/charts/features/features.js.map +1 -1
  46. package/es/src/charts/features/featuresLegend.js +1 -1
  47. package/es/src/charts/features/featuresLegend.js.map +1 -1
  48. package/es/src/charts/viz/VizBase.js.map +1 -1
  49. package/es/src/charts/viz/VizBaseConfig.js.map +1 -1
  50. package/es/src/components/TextBox.js +21 -5
  51. package/es/src/components/TextBox.js.map +1 -1
  52. package/es/src/shapes/Circle.js +12 -4
  53. package/es/src/shapes/Circle.js.map +1 -1
  54. package/es/src/shapes/Image.js +2 -3
  55. package/es/src/shapes/Image.js.map +1 -1
  56. package/es/src/shapes/Shape.js +35 -36
  57. package/es/src/shapes/Shape.js.map +1 -1
  58. package/es/src/shapes/buildLabelData.js +59 -4
  59. package/es/src/shapes/buildLabelData.js.map +1 -1
  60. package/es/src/shapes/sceneSort.js +304 -24
  61. package/es/src/shapes/sceneSort.js.map +1 -1
  62. package/es/src/shapes/shapeConfig.js.map +1 -1
  63. package/es/src/utils/D3plusConfig.js.map +1 -1
  64. package/package.json +10 -10
  65. package/types/src/charts/Plot/index.d.ts +22 -6
  66. package/types/src/charts/Plot/stackHelpers.d.ts +62 -4
  67. package/types/src/charts/viz/VizBase.d.ts +4 -4
  68. package/types/src/charts/viz/VizBaseConfig.d.ts +4 -3
  69. package/types/src/shapes/Image.d.ts +2 -3
  70. package/types/src/shapes/Shape.d.ts +0 -2
  71. package/types/src/shapes/sceneSort.d.ts +83 -8
  72. package/types/src/shapes/shapeConfig.d.ts +7 -0
  73. package/types/src/utils/D3plusConfig.d.ts +59 -14
  74. package/umd/d3plus-core.full.js +1911 -640
  75. package/umd/d3plus-core.full.js.map +1 -1
  76. package/umd/d3plus-core.full.min.js +1192 -942
  77. package/umd/d3plus-core.js +585 -239
  78. package/umd/d3plus-core.js.map +1 -1
  79. package/umd/d3plus-core.min.js +495 -367
@@ -1,3 +1,4 @@
1
+ import { type StackOffsetFn, type StackOrderFn, type StackOrderInput } from "./stackHelpers.js";
1
2
  import { type PlotPaintContext } from "../features/plotPaint.js";
2
3
  import Viz from "../viz/Viz.js";
3
4
  import type { Scene } from "@d3plus/render";
@@ -122,13 +123,28 @@ export default class Plot extends Viz {
122
123
  */
123
124
  size(_?: PlotAccessorArg | false): this | PlotAccessor;
124
125
  /**
125
- Sets the stack offset. If *value* is not specified, returns the current stack offset function.
126
- */
127
- stackOffset(_?: string | ((series: number[][], order: number[]) => void)): this | ((series: number[][], order: number[]) => void);
128
- /**
129
- Sets the stack order. If *value* is not specified, returns the current stack order function.
126
+ Sets the vertical offset applied to stacked series. Accepts a named
127
+ offset — `"diverging"` (default), `"none"`, `"expand"`, `"silhouette"`,
128
+ or `"wiggle"` — or a custom offset function. Unknown names warn and fall
129
+ back to `"diverging"`. If *value* is not specified, returns the current
130
+ stack offset function.
131
+ */
132
+ stackOffset(_?: string | StackOffsetFn): this | StackOffsetFn;
133
+ /**
134
+ Sets the order of stacked series, from the bottom of the stack upward.
135
+ Accepts:
136
+ - a named order: `"descending"` (default) / `"ascending"` by summed
137
+ value, `"key"` / `"keyReverse"` alphabetically by series key,
138
+ `"none"` / `"data"` for input order, or d3's `"insideOut"`,
139
+ `"appearance"`, `"reverse"`;
140
+ - an Array of series keys for an explicit order;
141
+ - a value accessor, or a `{value, order}` config, to rank series by an
142
+ aggregate of any data field.
143
+
144
+ Unknown named strings warn and fall back to `"descending"`. If *value*
145
+ is not specified, returns the current stack order.
130
146
  */
131
- stackOrder(_?: string | ((series: number[][]) => number[])): this | ((series: number[][]) => number[]);
147
+ stackOrder(_?: StackOrderInput): this | StackOrderFn | string[];
132
148
  /**
133
149
  Accessor function or string key for the x-axis value of each data point.
134
150
  */
@@ -1,24 +1,82 @@
1
1
  /**
2
2
  d3-stack ordering + offset helpers used by Plot's `stackOrder` /
3
3
  `stackOffset` accessors and their constructor defaults.
4
+
5
+ `resolveStackOrder` / `resolveStackOffset` normalize the many shapes a
6
+ user can pass (named string, data key, value accessor, `{value, order}`
7
+ config, explicit key array, or raw comparator) into the single value the
8
+ pipeline applies: a tagged comparator or an array of series keys.
4
9
  */
5
10
  import * as d3Shape from "d3-shape";
11
+ import type { DataPoint } from "@d3plus/data";
6
12
  type Series = d3Shape.Series<Record<string, unknown>, string>;
13
+ /** A resolved d3-stack order comparator. Tagged with `__d3plusStackOrder` so
14
+ the `stackOrder` setter can tell an already-resolved order (e.g. the
15
+ constructor default, or a value round-tripped by `config()` reset) from a
16
+ raw user value accessor that still needs wrapping. */
17
+ export type StackOrderFn = ((series: Series[]) => number[]) & {
18
+ __d3plusStackOrder?: true;
19
+ };
20
+ /** Per-datum value accessor accepted for field-based ordering. */
21
+ type ValueAccessor = (d: DataPoint, i?: number) => unknown;
22
+ /** `{value, order}` config for ordering series by an arbitrary data field. */
23
+ export interface StackOrderFieldConfig {
24
+ /** Data key or accessor whose aggregated value ranks each series. */
25
+ value: string | ValueAccessor;
26
+ /** Sort direction of the aggregate (default `"descending"`). */
27
+ order?: "ascending" | "descending";
28
+ }
29
+ /** Every shape `Plot.stackOrder` accepts. */
30
+ export type StackOrderInput = string | string[] | StackOrderFieldConfig | ValueAccessor | StackOrderFn;
7
31
  /**
8
32
  Sums a single stack series, ignoring non-numeric segments.
9
33
  */
10
34
  export declare function stackSum(series: Series): number;
11
35
  /**
12
- Stack order: ascending by series key, tie-broken by summed value.
36
+ Stack order: series with the smallest summed value on the bottom of the
37
+ stack (matches d3's `stackOrderAscending`).
13
38
  */
14
- export declare function stackOrderAscending(series: Series[]): number[];
39
+ export declare const stackOrderTotalAscending: StackOrderFn;
15
40
  /**
16
- Stack order: the reverse of {@link stackOrderAscending}.
41
+ Stack order: series with the largest summed value on the bottom of the
42
+ stack (matches d3's `stackOrderDescending`). Plot's default.
17
43
  */
18
- export declare function stackOrderDescending(series: Series[]): number[];
44
+ export declare const stackOrderTotalDescending: StackOrderFn;
45
+ /**
46
+ Stack order: ascending by series key (A→Z from the bottom), tie-broken by
47
+ ascending summed value.
48
+ */
49
+ export declare const stackOrderKey: StackOrderFn;
50
+ /**
51
+ Stack order: the reverse of {@link stackOrderKey} (Z→A from the bottom).
52
+ */
53
+ export declare const stackOrderKeyReverse: StackOrderFn;
54
+ /**
55
+ Builds a stack order that ranks each series by an aggregate (sum) of a
56
+ data field, letting users order stacks by any value in their data rather
57
+ than only the plotted one. `value` receives each series' original datum.
58
+ */
59
+ export declare function stackOrderField(value: ValueAccessor, order?: "ascending" | "descending"): StackOrderFn;
60
+ /** The named orders accepted by `Plot.stackOrder`, for docs/validation. */
61
+ export declare const stackOrderNames: string[];
62
+ /**
63
+ Normalizes any `stackOrder` input into a value Plot's pipeline can apply:
64
+ a tagged comparator, or an explicit array of series keys. Warns and falls
65
+ back to the default on an unrecognized name.
66
+ */
67
+ export declare function resolveStackOrder(input: StackOrderInput): StackOrderFn | string[];
19
68
  /**
20
69
  Diverging stack offset: positive segments stack upward from zero,
21
70
  negative segments stack downward.
22
71
  */
23
72
  export declare function stackOffsetDiverging(series: Series[], order: number[]): void;
73
+ /** A stack offset function, as applied by d3-stack. */
74
+ export type StackOffsetFn = (series: number[][][], order: number[]) => void;
75
+ /** The named offsets accepted by `Plot.stackOffset`, for docs/validation. */
76
+ export declare const stackOffsetNames: string[];
77
+ /**
78
+ Normalizes a `stackOffset` input into an offset function. Warns and falls
79
+ back to the diverging default on an unrecognized name.
80
+ */
81
+ export declare function resolveStackOffset(input: string | StackOffsetFn): StackOffsetFn;
24
82
  export {};
@@ -63,7 +63,7 @@ export default class VizBase extends VizBaseConfig {
63
63
  /**
64
64
  Tells the subtitle 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 subtitle appears centered above the x-axis. By default, this padding is only applied on screens larger than 600 pixels wide.
65
65
  */
66
- subtitlePadding(_?: boolean | (() => boolean)): this | boolean | (() => boolean);
66
+ subtitlePadding(_?: boolean | ((viz: VizBase) => boolean)): this | boolean | ((viz: VizBase) => boolean);
67
67
  /**
68
68
  The threshold value for bucketing small data points together.
69
69
  */
@@ -92,7 +92,7 @@ export default class VizBase extends VizBaseConfig {
92
92
  /**
93
93
  Tells the timeline 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 timeline appears centered underneath the x-axis. By default, this padding is only applied on screens larger than 600 pixels wide.
94
94
  */
95
- timelinePadding(_?: boolean | (() => boolean)): this | boolean | (() => boolean);
95
+ timelinePadding(_?: boolean | ((viz: VizBase) => boolean)): this | boolean | ((viz: VizBase) => boolean);
96
96
  /**
97
97
  Accessor function or string for the visualization's title.
98
98
  */
@@ -104,7 +104,7 @@ export default class VizBase extends VizBaseConfig {
104
104
  /**
105
105
  Tells the title 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 title appears centered above the x-axis. By default, this padding is only applied on screens larger than 600 pixels wide.
106
106
  */
107
- titlePadding(_?: boolean | (() => boolean)): this | boolean | (() => boolean);
107
+ titlePadding(_?: boolean | ((viz: VizBase) => boolean)): this | boolean | ((viz: VizBase) => boolean);
108
108
  /**
109
109
  Whether to display tooltips on hover.
110
110
  */
@@ -128,7 +128,7 @@ export default class VizBase extends VizBaseConfig {
128
128
  /**
129
129
  Tells the total 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 total appears centered above the x-axis. By default, this padding is only applied on screens larger than 600 pixels wide.
130
130
  */
131
- totalPadding(_?: boolean | (() => boolean)): this | boolean | (() => boolean);
131
+ totalPadding(_?: boolean | ((viz: VizBase) => boolean)): this | boolean | ((viz: VizBase) => boolean);
132
132
  /**
133
133
  The pixel stroke-width of the zoom brush area.
134
134
  */
@@ -1,5 +1,6 @@
1
1
  import type { DataPoint } from "@d3plus/data";
2
2
  import { BaseClass } from "../../utils/index.js";
3
+ import type VizBase from "./VizBase.js";
3
4
  /**
4
5
  First half of the fluent config accessors shared by every Viz chart
5
6
  (`active` through `legendTooltip`). Split from `VizBase` purely so each
@@ -44,7 +45,7 @@ export default class VizBaseConfig extends BaseClass {
44
45
  /**
45
46
  Tells the colorScale 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 colorScale appears centered above the x-axis. By default, this padding is only applied on screens larger than 600 pixels wide.
46
47
  */
47
- colorScalePadding(_?: boolean | (() => boolean)): this | boolean | (() => boolean);
48
+ colorScalePadding(_?: boolean | ((viz: VizBase) => boolean)): this | boolean | ((viz: VizBase) => boolean);
48
49
  /**
49
50
  Defines which side of the visualization to anchor the color scale. Acceptable values are `"top"`, `"bottom"`, `"left"`, `"right"`, and `false`. A `false` value will cause the color scale to not be displayed, but will still color shapes based on the scale.
50
51
  */
@@ -140,11 +141,11 @@ export default class VizBaseConfig extends BaseClass {
140
141
  /**
141
142
  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.
142
143
  */
143
- legendFilterInvert(_?: boolean | (() => boolean)): this | boolean | (() => boolean);
144
+ legendFilterInvert(_?: boolean | ((viz: VizBase) => boolean)): this | boolean | ((viz: VizBase) => boolean);
144
145
  /**
145
146
  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.
146
147
  */
147
- legendPadding(_?: boolean | (() => boolean)): this | boolean | (() => boolean);
148
+ legendPadding(_?: boolean | ((viz: VizBase) => boolean)): this | boolean | ((viz: VizBase) => boolean);
148
149
  /**
149
150
  Defines which side of the visualization to anchor the legend. Expected values are `"top"`, `"bottom"`, `"left"`, and `"right"`.
150
151
  */
@@ -45,9 +45,8 @@ export default class Image {
45
45
  /**
46
46
  Compute-mode scene emission. Mirrors Shape.toScene's shape — a
47
47
  keyed GroupNode wrapping per-datum ImageNodes. Used by chart
48
- compositors (Shape._backgroundImageClass, plotPaint) that need
49
- Image to participate in the scene graph rather than emit
50
- d3-selection DOM.
48
+ compositors (e.g. plotPaint) that need Image to participate in the
49
+ scene graph rather than emit d3-selection DOM.
51
50
  */
52
51
  toScene(): GroupNode;
53
52
  /**
@@ -21,13 +21,11 @@ export interface ShapeAes {
21
21
  x?: number;
22
22
  y?: number;
23
23
  }
24
- import Image from "./Image.js";
25
24
  /**
26
25
  An abstracted class for generating shapes.
27
26
  */
28
27
  export default class Shape extends BaseClass {
29
28
  [key: string]: any;
30
- _backgroundImageClass: Image;
31
29
  _data: DataPoint[];
32
30
  _labelClass: TextBox;
33
31
  _name: string;
@@ -1,6 +1,35 @@
1
1
  import type { DataPoint } from "@d3plus/data";
2
- import type { SceneNode } from "@d3plus/render";
3
- import type Image from "./Image.js";
2
+ import type { ClipShape, SceneNode, Transform } from "@d3plus/render";
3
+ /** How a backgroundImage fits its shape: `cover` fills the bounding box (cropping
4
+ the overflow, clipped to the shape); `contain` fits the whole image, centered
5
+ and fully visible, inside the shape's largest inscribed rectangle. */
6
+ export type BackgroundImageFit = "cover" | "contain";
7
+ /** A per-datum background image collected during `Shape.toScene`, before it is
8
+ emitted as a clipped, transformed group by {@link emitBackgroundImages}. */
9
+ export interface BackgroundImageSpec {
10
+ key: string | number;
11
+ index: number;
12
+ /** The source datum, carried so hover/active dimming treats the image like its
13
+ shape (dims + raises together). */
14
+ datum?: DataPoint;
15
+ /** The image URL. */
16
+ url: string;
17
+ /** The image box in the shape's LOCAL coordinate space (pre-transform). */
18
+ box: {
19
+ x: number;
20
+ y: number;
21
+ width: number;
22
+ height: number;
23
+ };
24
+ /** The shape's own geometry as a clip region (local space), or undefined. */
25
+ clip?: ClipShape;
26
+ /** SVG `preserveAspectRatio` — `slice` (cover) or `meet` (contain). */
27
+ preserveAspectRatio: string;
28
+ /** The shape's resolved node opacity — the fade-in target on enter (default 1). */
29
+ opacity?: number;
30
+ /** The shape's transform, carried on the wrapping group. */
31
+ transform?: Transform;
32
+ }
4
33
  /**
5
34
  Ranks `data` by a `sort` layering comparator WITHOUT reordering it. Returns
6
35
  `rank[i]` = the paint position of datum `i` (lower = painted first = behind),
@@ -11,10 +40,56 @@ import type Image from "./Image.js";
11
40
  */
12
41
  export declare function sortRanks(data: DataPoint[], sortFn: ((a: DataPoint, b: DataPoint) => number) | null | undefined): number[] | null;
13
42
  /**
14
- Renders the per-datum background images collected during `Shape.toScene` as
15
- flat sibling nodes. When `rank` is set (a `sort` comparator is active) every
16
- returned node needs a `z` — otherwise the backend sort would collapse the
17
- images to 0 and interleave them among the geometry — so they are placed
18
- above all geometry (ranks span `0..dataLen-1`) while keeping their own order.
43
+ The local-space bounding box `{x, y, width, height}` a backgroundImage fills,
44
+ derived from a datum's scene geometry. Rect/Bar geometry is already a box;
45
+ Circle is centered at (cx, cy) with radius r; a `path` uses the exact
46
+ (DOM-free) bounds of its `d`; Area/Line fall back to their polygon `points`.
47
+ Returns null when no finite extent can be determined.
19
48
  */
20
- export declare function emitBackgroundImages(bgClass: Image, imageData: DataPoint[], rank: number[] | null, dataLen: number): SceneNode[];
49
+ export declare function backgroundImageBox(g: Record<string, unknown>, points: [number, number][]): {
50
+ x: number;
51
+ y: number;
52
+ width: number;
53
+ height: number;
54
+ } | null;
55
+ /**
56
+ The shape's own geometry expressed as a clip region in its LOCAL coordinate
57
+ space, so a background image can be clipped to the shape itself (a Path image
58
+ is clipped to the path, a Circle image to the circle, etc.). Returns
59
+ undefined when the geometry has no usable outline.
60
+ */
61
+ export declare function backgroundImageClip(g: Record<string, unknown>, points: [number, number][]): ClipShape | undefined;
62
+ /**
63
+ Resolves a backgroundImage's box + clip + `preserveAspectRatio` for a datum's
64
+ geometry, honoring the fit mode:
65
+
66
+ - `cover` — the image fills the shape's bounding box and is cropped
67
+ (`xMidYMid slice`), clipped to the shape's own outline.
68
+ - `contain` — the whole image is centered and fully visible inside the shape:
69
+ it is fit (`xMidYMid meet`) into the shape's largest inscribed axis-aligned
70
+ rectangle (a Rect uses itself; a Circle its inscribed square; a Path/Area
71
+ uses `largestRect` of its polygon). No clip is needed since the box already
72
+ sits inside the shape.
73
+
74
+ Returns null when no usable box can be derived.
75
+ */
76
+ export declare function backgroundImageLayout(g: Record<string, unknown>, points: [number, number][], fit: BackgroundImageFit): {
77
+ box: {
78
+ x: number;
79
+ y: number;
80
+ width: number;
81
+ height: number;
82
+ };
83
+ clip?: ClipShape;
84
+ preserveAspectRatio: string;
85
+ } | null;
86
+ /**
87
+ Emits the per-datum background images collected during `Shape.toScene`. Each
88
+ image is wrapped in its own group carrying the shape's datum + transform, so
89
+ it is clipped to the shape's outline, positioned in local space, and dims/
90
+ raises together with its shape on hover. The image is non-interactive (and
91
+ keyed apart from the shape) so pointer events pass through to the shape below.
92
+ When `rank` is set (a `sort` comparator is active) every group needs a `z`
93
+ so the backend sort keeps images above the geometry in their own order.
94
+ */
95
+ export declare function emitBackgroundImages(specs: BackgroundImageSpec[], rank: number[] | null, dataLen: number): SceneNode[];
@@ -52,6 +52,13 @@ export interface BaseShapeConfig {
52
52
  ariaLabel?: ConstOrAccessor<string>;
53
53
  /** Optional background image per datum (url or accessor returning a url). */
54
54
  backgroundImage?: ConstOrAccessor<string>;
55
+ /**
56
+ How a `backgroundImage` fits its shape: `"cover"` (default) fills the
57
+ shape's bounding box, cropping the overflow and clipping to the outline;
58
+ `"contain"` fits the whole image, centered and fully visible, inside the
59
+ shape's largest inscribed rectangle.
60
+ */
61
+ backgroundImageFit?: ConstOrAccessor<"cover" | "contain">;
55
62
  /** Discrete-axis key ("x" | "y") for charts that flip layout per axis. */
56
63
  discrete?: "x" | "y";
57
64
  /** Animation duration in ms. */
@@ -1,4 +1,5 @@
1
1
  import type { DataPoint } from "@d3plus/data";
2
+ import type VizBase from "../charts/viz/VizBase.js";
2
3
  import type { AccessorFn } from "./AccessorFn.js";
3
4
  type Position = "top" | "right" | "bottom" | "left";
4
5
  type DataPointAccessor<T> = string | ((d: DataPoint) => T);
@@ -217,8 +218,10 @@ export interface D3plusConfig {
217
218
  colorMax?: string;
218
219
  scale?: AxisScale;
219
220
  };
220
- /** Position of the color scale, or false to hide it. */
221
- colorScalePosition?: false | Position;
221
+ /** Whether the color scale uses the visualization's internal padding when positioning, or an accessor receiving the viz. */
222
+ colorScalePadding?: boolean | ((viz: VizBase) => boolean);
223
+ /** Position of the color scale, `false` to hide it, or an accessor returning either. */
224
+ colorScalePosition?: false | Position | (() => false | Position);
222
225
  /** Column key for matrix-style layouts. */
223
226
  column?: string;
224
227
  /**
@@ -248,21 +251,34 @@ export interface D3plusConfig {
248
251
  groupPadding?: number;
249
252
  /** Overall height of the visualization in pixels. */
250
253
  height?: number;
254
+ /** Color for legend shapes whose grouping is hidden (via legend click), or a `(datum, index)` accessor. */
255
+ hiddenColor?: string | ((d: DataPoint, i: number) => string);
256
+ /** Opacity for legend labels whose grouping is hidden (via legend click), or a `(datum, index)` accessor. */
257
+ hiddenOpacity?: number | ((d: DataPoint, i: number) => number);
251
258
  /** The hover callback function for highlighting shapes on mouseover. */
252
259
  hover?: ((d: DataPoint, i: number) => boolean) | false | null;
253
260
  /** Persistently emphasizes matching marks (keep color) and grays the rest. */
254
261
  highlight?: ((d: DataPoint, i: number) => boolean) | false | null;
255
262
  /** Label accessor for shapes. */
256
263
  label?: string | string[] | false | AccessorFn;
257
- /** Whether to show the legend. */
258
- legend?: boolean;
264
+ /**
265
+ Controls legend visibility. Pass `false` to hide it, `true` to always
266
+ show it, or a `(config, data) => boolean` accessor to decide dynamically
267
+ — the chart defaults use an accessor to auto-hide the legend when it
268
+ would be redundant.
269
+ */
270
+ legend?: boolean | ((config: D3plusConfig, arr: DataPoint[]) => boolean);
259
271
  /** Configuration for the legend component. */
260
272
  legendConfig?: {
261
273
  label?: DataPointAccessor<string>;
262
274
  shapeConfig?: Record<string, string | number>;
263
275
  };
264
- /** Position of the legend. */
265
- legendPosition?: Position;
276
+ /** Inverts legend click behavior (click hides / shift-click solos, or the reverse), or an accessor receiving the viz. */
277
+ legendFilterInvert?: boolean | ((viz: VizBase) => boolean);
278
+ /** Whether the legend uses the visualization's internal padding when positioning, or an accessor receiving the viz. */
279
+ legendPadding?: boolean | ((viz: VizBase) => boolean);
280
+ /** Position of the legend, or an accessor returning it. */
281
+ legendPosition?: Position | (() => Position);
266
282
  /** Custom sort comparator for legend items. */
267
283
  legendSort?: (a: DataPoint, b: DataPoint) => number;
268
284
  /** Tooltip configuration for legend items. */
@@ -271,10 +287,12 @@ export interface D3plusConfig {
271
287
  lineLabels?: boolean;
272
288
  /** Whether to show the loading message. */
273
289
  loadingMessage?: boolean;
274
- /** Custom HTML content for the loading indicator. */
275
- loadingHTML?: string;
290
+ /** Custom HTML content for the loading indicator, or a function receiving the viz instance. */
291
+ loadingHTML?: string | ((viz: VizBase) => string);
276
292
  /** Metric key for the visualization. */
277
293
  metric?: string;
294
+ /** Custom HTML content shown when no data is supplied, or a function receiving the viz instance. */
295
+ noDataHTML?: string | ((viz: VizBase) => string);
278
296
  /** Ocean color for geomaps (any CSS value including 'transparent'). */
279
297
  ocean?: string;
280
298
  /** Event listeners keyed by event name. */
@@ -313,8 +331,29 @@ export interface D3plusConfig {
313
331
  size?: string;
314
332
  /** Whether to stack series. */
315
333
  stacked?: boolean;
316
- /** Custom order for stacked series. */
317
- stackOrder?: string[];
334
+ /**
335
+ Vertical offset applied to stacked series. One of `"diverging"`
336
+ (default — positive and negative values split around zero), `"none"`,
337
+ `"expand"` (normalize each stack to 100%), `"silhouette"` (streamgraph),
338
+ or `"wiggle"` (minimize slope changes); or a custom offset function.
339
+ */
340
+ stackOffset?: string | ((series: number[][][], order: number[]) => void);
341
+ /**
342
+ Order of stacked series, from the bottom of the stack upward. Accepts a
343
+ named order (`"descending"` [default] / `"ascending"` by summed value,
344
+ `"key"` / `"keyReverse"` alphabetically, `"none"` / `"data"` for input
345
+ order, or d3's `"insideOut"` / `"appearance"` / `"reverse"`), an Array of
346
+ series keys for an explicit order, a value accessor, or a `{value, order}`
347
+ config to rank series by an aggregate of any data field.
348
+ */
349
+ stackOrder?: string | string[] | {
350
+ value: string | ((d: DataPoint) => unknown);
351
+ order?: "ascending" | "descending";
352
+ } | ((d: DataPoint) => unknown);
353
+ /** Subtitle text, or an accessor returning it. */
354
+ subtitle?: string | ((data: DataPoint[]) => string);
355
+ /** Whether the subtitle uses the visualization's internal padding when positioning, or an accessor receiving the viz. */
356
+ subtitlePadding?: boolean | ((viz: VizBase) => boolean);
318
357
  /** Value accessor for treemaps and aggregation. */
319
358
  sum?: DataPointAccessor<number>;
320
359
  /** Accessible description applied to the root SVG (`<desc>`). */
@@ -323,8 +362,8 @@ export interface D3plusConfig {
323
362
  svgTitle?: string;
324
363
  /** Threshold value for grouping small slices. */
325
364
  threshold?: number;
326
- /** Label for the threshold group. */
327
- thresholdName?: string;
365
+ /** Label for the threshold group, or a `(datum, index)` accessor. */
366
+ thresholdName?: string | ((d: DataPoint, i: number) => string);
328
367
  /** URL to XYZ map tiles. */
329
368
  tileUrl?: string;
330
369
  /** Whether to show map tiles. */
@@ -335,12 +374,16 @@ export interface D3plusConfig {
335
374
  timeFilter?: ((d: DataPoint, i: number) => boolean) | false;
336
375
  /** Whether to show the timeline component. */
337
376
  timeline?: boolean;
377
+ /** Whether the timeline uses the visualization's internal padding when positioning, or an accessor receiving the viz. */
378
+ timelinePadding?: boolean | ((viz: VizBase) => boolean);
338
379
  /** Chart title or title accessor function. */
339
380
  title?: string | ((data: DataPoint[]) => string);
340
381
  /** CSS style configuration for the title. */
341
382
  titleConfig?: Record<string, string | number>;
342
- /** Whether to show tooltips. */
343
- tooltip?: boolean;
383
+ /** Whether the title uses the visualization's internal padding when positioning, or an accessor receiving the viz. */
384
+ titlePadding?: boolean | ((viz: VizBase) => boolean);
385
+ /** Whether to show tooltips, or a `(datum, index)` accessor deciding per mark. */
386
+ tooltip?: boolean | ((d: DataPoint, i: number) => boolean);
344
387
  /** Configuration for the tooltip component. */
345
388
  tooltipConfig?: TooltipConfig;
346
389
  /** Path or object for the topojson data. */
@@ -349,6 +392,8 @@ export interface D3plusConfig {
349
392
  topojsonFill?: string;
350
393
  /** Accessor function for topojson feature IDs. */
351
394
  topojsonId?: (obj: Record<string, unknown>) => string;
395
+ /** Whether the total uses the visualization's internal padding when positioning, or an accessor receiving the viz. */
396
+ totalPadding?: boolean | ((viz: VizBase) => boolean);
352
397
  /** Value accessor for the visualization. */
353
398
  value?: DataPointAccessor<number>;
354
399
  /** Overall width of the visualization in pixels. */