forked from observablehq/plot
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathstack.d.ts
More file actions
166 lines (151 loc) · 6.73 KB
/
stack.d.ts
File metadata and controls
166 lines (151 loc) · 6.73 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
import type {ChannelValue} from "../channel.js";
import type {CompareFunction, Transformed} from "./basic.js";
/**
* A built-in stack offset method; one of:
*
* - *normalize* - rescale each stack to fill [0, 1]
* - *center* - align the centers of all stacks
* - *wiggle* - translate stacks to minimize apparent movement
*
* If a given stack has zero total value, the *normalize* offset will not adjust
* the stack’s position. Both the *center* and *wiggle* offsets ensure that the
* lowest element across stacks starts at zero for better default axes. The
* *wiggle* offset is recommended for streamgraphs in conjunction with the
* *inside-out* order. For more, see [Byron & Wattenberg][1].
*
* [1]: https://leebyron.com/streamgraph/
*/
export type StackOffsetName =
| "center"
| "normalize"
| "wiggle"
| ("expand" & Record<never, never>) // deprecated; use normalize
| ("silhouette" & Record<never, never>); // deprecated; use center
/**
* A stack offset implementation: given an *index* grouped by facet and **x**,
* the output channel values *y1* and *y2*, and the channel values *z*, mutates
* the values in *y1* and *y2* given by the *index* to translate and scale
* stacks as desired. For the stackX transform, substitute *y* for *x*, and *x1*
* & *x2* for *y1* & *y2*.
*/
export type StackOffsetFunction = (index: number[][][], y1: number[], y2: number[], z: any[]) => void;
/**
* How the baseline of stacked layers may be offset; one of:
*
* - a named stack offset method such as *wiggle* or *center*
* - a function to be passed an *index*, **y1**, **y2**, and **z** values
*/
export type StackOffset = StackOffsetName | StackOffsetFunction;
/**
* The built-in stack order methods; one of:
*
* - *x* - alias of *value*; for stackX only
* - *y* - alias of *value*; for stackY only
* - *value* - ascending value (or descending with **reverse**)
* - *sum* - total value per series
* - *appearance* - position of maximum value per series
* - *inside-out* (default with *wiggle*) - order the earliest-appearing series on the inside
*
* The *inside-out* order is recommended for streamgraphs in conjunction with
* the *wiggle* offset. For more, see [Byron & Wattenberg][1].
*
* [1]: https://leebyron.com/streamgraph/
*/
export type StackOrderName = "value" | "x" | "y" | "z" | "sum" | "appearance" | "inside-out";
/**
* How to order layers prior to stacking; one of:
*
* - a named stack order method such as *inside-out* or *sum*
* - a field name, for natural order of the corresponding values
* - an accessor function, for natural order of the corresponding values
* - a comparator function for ordering data
* - an array of explicit **z** values in the desired order
*/
export type StackOrder =
| StackOrderName
| `-${StackOrderName}`
| (string & Record<never, never>)
| ((d: any) => any) // accessor
| CompareFunction
| any[];
/** Options for the stack transform. */
export interface StackOptions {
/**
* After stacking, an optional **offset** can be applied to translate and
* scale stacks, say to produce a streamgraph; defaults to null for a zero
* baseline (**y** = 0 for stackY, and **x** = 0 for stackX). If the *wiggle*
* offset is used, the default **order** changes to *inside-out*.
*/
offset?: StackOffset | null;
/**
* The order in which stacks are layered; one of:
*
* - null (default) for input order
* - a named stack order method such as *inside-out* or *sum*
* - a field name, for natural order of the corresponding values
* - a function of data, for natural order of the corresponding values
* - an array of explicit **z** values in the desired order
*
* If the *wiggle* **offset** is used, as for a streamgraph, the default
* changes to *inside-out*.
*/
order?: StackOrder | null;
/** If true, reverse the effective order of the stacks. */
reverse?: boolean;
/**
* The **z** channel defines the series of each value in the stack. Used when
* the **order** is *sum*, *appearance*, *inside-out*, or an explicit array of
* **z** values.
*/
z?: ChannelValue;
}
/**
* Transforms a length channel **x** into starting and ending position channels
* **x1** and **x2** by “stacking” elements that share a given **y** position.
* The starting position of each element equals the ending position of the
* preceding element in the stack. Non-positive values are stacked to the left
* of zero, with **x2** to the left of **x1**. A new **x** channel is derived
* that represents the midpoint between **x1** and **x2**, for example to place
* a label. If not specified, the input channel **x** defaults to the constant
* one.
*/
export function stackX<T>(options?: T & StackOptions): Transformed<T>;
export function stackX<T>(stackOptions?: StackOptions, options?: T): Transformed<T>;
/**
* Like **stackX**, but returns the starting position **x1** as the **x**
* channel, for example to position a dot on the left-hand side of each element
* of a stack.
*/
export function stackX1<T>(options?: T & StackOptions): Transformed<T>;
export function stackX1<T>(stackOptions?: StackOptions, options?: T): Transformed<T>;
/**
* Like **stackX**, but returns the starting position **x2** as the **x**
* channel, for example to position a dot on the right-hand side of each element
* of a stack.
*/
export function stackX2<T>(options?: T & StackOptions): Transformed<T>;
export function stackX2<T>(stackOptions?: StackOptions, options?: T): Transformed<T>;
/**
* Transforms a length channel **y** into starting and ending position channels
* **y1** and **y2** by “stacking” elements that share a given **x** position.
* The starting position of each element equals the ending position of the
* preceding element in the stack. Non-positive values are stacked below zero,
* with **y2** below **y1**. A new **y** channel is derived that represents the
* midpoint between **y1** and **y2**, for example to place a label. If not
* specified, the input channel **y** defaults to the constant one.
*/
export function stackY<T>(options?: T & StackOptions): Transformed<T>;
export function stackY<T>(stackOptions?: StackOptions, options?: T): Transformed<T>;
/**
* Like **stackY**, but returns the starting position **y1** as the **y**
* channel, for example to position a dot at the bottom of each element of a
* stack.
*/
export function stackY1<T>(options?: T & StackOptions): Transformed<T>;
export function stackY1<T>(stackOptions?: StackOptions, options?: T): Transformed<T>;
/**
* Like **stackY**, but returns the ending position **y2** as the **y** channel,
* for example to position a dot at the top of each element of a stack.
*/
export function stackY2<T>(options?: T & StackOptions): Transformed<T>;
export function stackY2<T>(stackOptions?: StackOptions, options?: T): Transformed<T>;