@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.
- package/README.md +686 -671
- package/es/src/charts/AreaPlot/index.js +2 -1
- package/es/src/charts/AreaPlot/index.js.map +1 -1
- package/es/src/charts/BarChart/index.js +3 -1
- package/es/src/charts/BarChart/index.js.map +1 -1
- package/es/src/charts/BoxWhisker/index.js +2 -1
- package/es/src/charts/BoxWhisker/index.js.map +1 -1
- package/es/src/charts/BumpChart/index.js +2 -1
- package/es/src/charts/BumpChart/index.js.map +1 -1
- package/es/src/charts/Geomap/index.js +2 -1
- package/es/src/charts/Geomap/index.js.map +1 -1
- package/es/src/charts/LinePlot/index.js +2 -1
- package/es/src/charts/LinePlot/index.js.map +1 -1
- package/es/src/charts/Matrix/index.js +1 -0
- package/es/src/charts/Matrix/index.js.map +1 -1
- package/es/src/charts/Network/index.js +2 -1
- package/es/src/charts/Network/index.js.map +1 -1
- package/es/src/charts/Pack/index.js +1 -0
- package/es/src/charts/Pack/index.js.map +1 -1
- package/es/src/charts/Pie/index.js +1 -0
- package/es/src/charts/Pie/index.js.map +1 -1
- package/es/src/charts/Plot/index.js +22 -12
- package/es/src/charts/Plot/index.js.map +1 -1
- package/es/src/charts/Plot/pipelineDomains.js +3 -3
- package/es/src/charts/Plot/pipelineDomains.js.map +1 -1
- package/es/src/charts/Plot/stackHelpers.js +128 -9
- package/es/src/charts/Plot/stackHelpers.js.map +1 -1
- package/es/src/charts/Radar/index.js +2 -1
- package/es/src/charts/Radar/index.js.map +1 -1
- package/es/src/charts/RadialMatrix/index.js +1 -0
- package/es/src/charts/RadialMatrix/index.js.map +1 -1
- package/es/src/charts/Rings/index.js +2 -1
- package/es/src/charts/Rings/index.js.map +1 -1
- package/es/src/charts/Sankey/index.js +2 -1
- package/es/src/charts/Sankey/index.js.map +1 -1
- package/es/src/charts/Tree/index.js +2 -1
- package/es/src/charts/Tree/index.js.map +1 -1
- package/es/src/charts/Treemap/index.js +1 -0
- package/es/src/charts/Treemap/index.js.map +1 -1
- package/es/src/shapes/Image.js +2 -3
- package/es/src/shapes/Image.js.map +1 -1
- package/es/src/shapes/Shape.js +35 -36
- package/es/src/shapes/Shape.js.map +1 -1
- package/es/src/shapes/sceneSort.js +304 -24
- package/es/src/shapes/sceneSort.js.map +1 -1
- package/es/src/shapes/shapeConfig.js.map +1 -1
- package/es/src/utils/D3plusConfig.js.map +1 -1
- package/package.json +9 -9
- package/types/src/charts/Plot/index.d.ts +22 -6
- package/types/src/charts/Plot/stackHelpers.d.ts +62 -4
- package/types/src/shapes/Image.d.ts +2 -3
- package/types/src/shapes/Shape.d.ts +0 -2
- package/types/src/shapes/sceneSort.d.ts +83 -8
- package/types/src/shapes/shapeConfig.d.ts +7 -0
- package/types/src/utils/D3plusConfig.d.ts +19 -2
- package/umd/d3plus-core.full.js +1581 -561
- package/umd/d3plus-core.full.js.map +1 -1
- package/umd/d3plus-core.full.min.js +1091 -927
- package/umd/d3plus-core.js +541 -224
- package/umd/d3plus-core.js.map +1 -1
- 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
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
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(_?:
|
|
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:
|
|
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
|
|
39
|
+
export declare const stackOrderTotalAscending: StackOrderFn;
|
|
15
40
|
/**
|
|
16
|
-
Stack order: the
|
|
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
|
|
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 (
|
|
49
|
-
|
|
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
|
-
|
|
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
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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
|
|
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
|
-
/**
|
|
335
|
-
|
|
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. */
|