@d3plus/core 4.1.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 (61) hide show
  1. package/README.md +686 -671
  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/shapes/Image.js +2 -3
  41. package/es/src/shapes/Image.js.map +1 -1
  42. package/es/src/shapes/Shape.js +35 -36
  43. package/es/src/shapes/Shape.js.map +1 -1
  44. package/es/src/shapes/sceneSort.js +304 -24
  45. package/es/src/shapes/sceneSort.js.map +1 -1
  46. package/es/src/shapes/shapeConfig.js.map +1 -1
  47. package/es/src/utils/D3plusConfig.js.map +1 -1
  48. package/package.json +9 -9
  49. package/types/src/charts/Plot/index.d.ts +22 -6
  50. package/types/src/charts/Plot/stackHelpers.d.ts +62 -4
  51. package/types/src/shapes/Image.d.ts +2 -3
  52. package/types/src/shapes/Shape.d.ts +0 -2
  53. package/types/src/shapes/sceneSort.d.ts +83 -8
  54. package/types/src/shapes/shapeConfig.d.ts +7 -0
  55. package/types/src/utils/D3plusConfig.d.ts +19 -2
  56. package/umd/d3plus-core.full.js +1581 -561
  57. package/umd/d3plus-core.full.js.map +1 -1
  58. package/umd/d3plus-core.full.min.js +1091 -927
  59. package/umd/d3plus-core.js +541 -224
  60. package/umd/d3plus-core.js.map +1 -1
  61. package/umd/d3plus-core.min.js +468 -363
@@ -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 {};
@@ -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. */
@@ -331,8 +331,25 @@ export interface D3plusConfig {
331
331
  size?: string;
332
332
  /** Whether to stack series. */
333
333
  stacked?: boolean;
334
- /** Custom order for stacked series. */
335
- 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);
336
353
  /** Subtitle text, or an accessor returning it. */
337
354
  subtitle?: string | ((data: DataPoint[]) => string);
338
355
  /** Whether the subtitle uses the visualization's internal padding when positioning, or an accessor receiving the viz. */