-
Notifications
You must be signed in to change notification settings - Fork 29.9k
/
index.d.ts
293 lines (260 loc) · 12.1 KB
/
index.d.ts
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
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
// Last module patch version validated against: 3.0.0
import { Selection, TransitionLike } from "d3-selection";
// --------------------------------------------------------------------------
// Shared Types and Interfaces
// --------------------------------------------------------------------------
/**
* A helper type to alias elements which can serve as a domain for an axis.
*/
export type AxisDomain = number | string | Date | { valueOf(): number };
/**
* A helper interface to describe the minimal contract to be met by a time interval
* which can be passed into the Axis.ticks(...) or Axis.tickArguments(...) methods when
* creating time series axes. Under normal circumstances the argument will be of type
* TimeInterval or CountableTimeInterval as defined in d3-time.
* NB: This helper interface has been created to avoid tight coupling of d3-axis to
* d3-time at the level of definition files. I.e. d3-time is not a
* dependency of d3-axis in the D3 Javascript implementation. This minimal contract
* is based on an analysis of how d3-axis passes a time interval argument into a time scale,
* if a time scale was set using Axis.scale(...). And in turn on how a time scale uses
* the time interval when creating ticks from it.
*/
export interface AxisTimeInterval {
range(start: Date, stop: Date, step?: number): Date[];
}
/**
* A helper interface to which a scale passed into axis must conform (at a minimum)
* for axis to use the scale without error.
*/
export interface AxisScale<Domain> {
(x: Domain): number | undefined;
domain(): Domain[];
range(): number[];
copy(): this;
bandwidth?(): number;
// TODO: Reconsider the below, note that the compiler does not differentiate the overloads w.r.t. optionality
// ticks?(count?: number): Domain[];
// ticks?(count?: AxisTimeInterval): Date[];
// tickFormat?(count?: number, specifier?: string): ((d: number) => string);
// tickFormat?(count?: number | AxisTimeInterval, specifier?: string): ((d: Date) => string);
}
/**
* A helper type to alias elements which can serve as a container for an axis.
*/
export type AxisContainerElement = SVGSVGElement | SVGGElement;
/**
* Interface defining an axis generator. The generic <Domain> is the type of the axis domain.
*/
export interface Axis<Domain> {
/**
* Render the axis to the given context.
*
* @param context A selection of or a transition defined on SVG containers (either SVG or G elements).
*/
(
context:
| Selection<SVGSVGElement, any, any, any>
| Selection<SVGGElement, any, any, any>
| TransitionLike<SVGSVGElement, any>
| TransitionLike<SVGGElement, any>,
): void;
/**
* Gets the current scale underlying the axis.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
scale<A extends AxisScale<Domain>>(): A;
/**
* Sets the scale and returns the axis.
*
* @param scale The scale to be used for axis generation.
*/
scale(scale: AxisScale<Domain>): this;
/**
* Sets the arguments that will be passed to scale.ticks and scale.tickFormat when the axis is rendered, and returns the axis generator.
*
* This method has no effect if the scale does not implement scale.ticks, as with band and point scales.
*
* This method is also a convenience function for axis.tickArguments.
*
* @param count Number of ticks that should be rendered.
* @param specifier An optional format specifier to customize how the tick values are formatted.
*/
ticks(count: number, specifier?: string): this;
/**
* Sets the arguments that will be passed to scale.ticks and scale.tickFormat when the axis is rendered, and returns the axis generator.
* Use with a TIME SCALE ONLY.
*
* This method is also a convenience function for axis.tickArguments.
*
* @param interval A time interval used to generate date-based ticks. This is typically a TimeInterval/CountableTimeInterval as defined
* in d3-time. E.g. as obtained by passing in d3.timeMinute.every(15).
* @param specifier An optional format specifier to customize how the tick values are formatted.
*/
// tslint:disable-next-line:unified-signatures
ticks(interval: AxisTimeInterval, specifier?: string): this;
/**
* Sets the arguments that will be passed to scale.ticks and scale.tickFormat when the axis is rendered, and returns the axis generator.
*
* The meaning of the arguments depends on the axis’ scale type: most commonly, the arguments are a suggested count for the number of ticks
* (or a time interval for time scales), and an optional format specifier to customize how the tick values are formatted.
*
* This method has no effect if the scale does not implement scale.ticks, as with band and point scales.
*
* To set the tick values explicitly, use axis.tickValues. To set the tick format explicitly, use axis.tickFormat.
*
* This method is also a convenience function for axis.tickArguments.
*/
ticks(arg0: any, ...args: any[]): this;
/**
* Get an array containing the currently set arguments to be passed into scale.ticks and scale.tickFormat, which defaults to the empty array.
*/
tickArguments(): any[];
/**
* Sets the arguments that will be passed to scale.ticks and scale.tickFormat when the axis is rendered, and returns the axis generator.
*
* This method has no effect if the scale does not implement scale.ticks, as with band and point scales.
* To set the tick values explicitly, use axis.tickValues. To set the tick format explicitly, use axis.tickFormat.
*
* See also axis.ticks.
*
* @param args The meaning of the arguments depends on the axis’ scale type: most commonly, the arguments are a
* suggested count for the number of ticks (or a time interval for time scales), and an optional format specifier to
* customize how the tick values are formatted.
*/
tickArguments(args: any[]): this;
/**
* Returns the current tick values, which defaults to null.
*/
tickValues(): Domain[] | null;
/**
* Specified values to be used for ticks rather than using the scale’s automatic tick generator.
* The explicit tick values take precedent over the tick arguments set by axis.tickArguments.
* However, any tick arguments will still be passed to the scale’s tickFormat function if a
* tick format is not also set.
*
* @param values An iterable with values from the Domain of the scale underlying the axis.
*/
tickValues(values: Iterable<Domain>): this;
/**
* Clears any previously-set explicit tick values and reverts back to the scale’s tick generator.
*
* @param values null
*/
tickValues(values: null): this;
/**
* Returns the currently set tick format function, which defaults to null.
*/
tickFormat(): ((domainValue: Domain, index: number) => string) | null;
/**
* Sets the tick format function and returns the axis.
*
* @param format A function mapping a value from the axis Domain to a formatted string
* for display purposes. When invoked, the format function is also passed a second argument representing the zero-based index
* of the tick label in the array of generated tick labels.
*/
tickFormat(format: (domainValue: Domain, index: number) => string): this;
/**
* Reset the tick format function. A null format indicates that the scale’s
* default formatter should be used, which is generated by calling scale.tickFormat.
* In this case, the arguments specified by axis.tickArguments
* are likewise passed to scale.tickFormat.
*
* @param format null
*/
tickFormat(format: null): this;
/**
* Get the current inner tick size, which defaults to 6.
*/
tickSize(): number;
/**
* Set the inner and outer tick size to the specified value and return the axis.
*
* @param size Tick size in pixels (Default is 6).
*/
tickSize(size: number): this;
/**
* Get the current inner tick size, which defaults to 6.
* The inner tick size controls the length of the tick lines,
* offset from the native position of the axis.
*/
tickSizeInner(): number;
/**
* Set the inner tick size to the specified value and return the axis.
* The inner tick size controls the length of the tick lines,
* offset from the native position of the axis.
*
* @param size Tick size in pixels (Default is 6).
*/
tickSizeInner(size: number): this;
/**
* Get the current outer tick size, which defaults to 6.
* The outer tick size controls the length of the square ends of the domain path,
* offset from the native position of the axis. Thus, the “outer ticks” are not actually
* ticks but part of the domain path, and their position is determined by the associated
* scale’s domain extent. Thus, outer ticks may overlap with the first or last inner tick.
* An outer tick size of 0 suppresses the square ends of the domain path,
* instead producing a straight line.
*/
tickSizeOuter(): number;
/**
* Set the current outer tick size and return the axis.
* The outer tick size controls the length of the square ends of the domain path,
* offset from the native position of the axis. Thus, the “outer ticks” are not actually
* ticks but part of the domain path, and their position is determined by the associated
* scale’s domain extent. Thus, outer ticks may overlap with the first or last inner tick.
* An outer tick size of 0 suppresses the square ends of the domain path,
* instead producing a straight line.
*
* @param size Tick size in pixels (Default is 6).
*/
tickSizeOuter(size: number): this;
/**
* Get the current padding, which defaults to 3.
*/
tickPadding(): number;
/**
* Set the current padding and return the axis.
*
* @param padding Padding in pixels (Default is 3).
*/
tickPadding(padding: number): this;
/**
* Returns the current offset which defaults to 0 on devices with a devicePixelRatio greater than 1, and 0.5px otherwise.
* This default offset ensures crisp edges on low-resolution devices.
*/
offset(): number;
/**
* Sets the offset to the specified value in pixels and returns the axis.
* Defaults to 0 on devices with a devicePixelRatio greater than 1, and 0.5px otherwise.
* This default offset ensures crisp edges on low-resolution devices.
*/
offset(offset: number): this;
}
/**
* Constructs a new top-oriented axis generator for the given scale, with empty tick arguments,
* a tick size of 6 and padding of 3. In this orientation, ticks are drawn above the horizontal domain path.
*
* @param scale The scale to be used for axis generation.
*/
export function axisTop<Domain extends AxisDomain>(scale: AxisScale<Domain>): Axis<Domain>;
/**
* Constructs a new right-oriented axis generator for the given scale, with empty tick arguments,
* a tick size of 6 and padding of 3. In this orientation, ticks are drawn to the right of the vertical domain path.
*
* @param scale The scale to be used for axis generation.
*/
export function axisRight<Domain extends AxisDomain>(scale: AxisScale<Domain>): Axis<Domain>;
/**
* Constructs a new bottom-oriented axis generator for the given scale, with empty tick arguments,
* a tick size of 6 and padding of 3. In this orientation, ticks are drawn below the horizontal domain path.
*
* @param scale The scale to be used for axis generation.
*/
export function axisBottom<Domain extends AxisDomain>(scale: AxisScale<Domain>): Axis<Domain>;
/**
* Constructs a new left-oriented axis generator for the given scale, with empty tick arguments,
* a tick size of 6 and padding of 3. In this orientation, ticks are drawn to the left of the vertical domain path.
*
* @param scale The scale to be used for axis generation.
*/
export function axisLeft<Domain extends AxisDomain>(scale: AxisScale<Domain>): Axis<Domain>;