UNPKG

12.7 kBTypeScriptView Raw
1// Last module patch version validated against: 3.0.0
2
3import { Selection, TransitionLike, ValueFn } from "d3-selection";
4
5/**
6 * Type alias for a BrushSelection. For a two-dimensional brush, it must be defined as [[x0, y0], [x1, y1]],
7 * where x0 is the minimum x-value, y0 is the minimum y-value, x1 is the maximum x-value, and y1 is the maximum y-value.
8 * For an x-brush, it must be defined as [x0, x1]; for a y-brush, it must be defined as [y0, y1].
9 */
10export type BrushSelection = [[number, number], [number, number]] | [number, number];
11
12/**
13 * A D3 brush behavior
14 *
15 * The generic refers to the type of the datum for the group element on which brush behavior is defined.
16 */
17export interface BrushBehavior<Datum> {
18 /**
19 * Applies the brush to the specified group, which must be a selection of SVG G elements.
20 * This function is typically not invoked directly, and is instead invoked via selection.call.
21 *
22 * For details see: {@link https://github.com/d3/d3-brush#_brush}
23 *
24 * @param group A D3 selection of SVG G elements.
25 * @param args Optional arguments to be passed in.
26 */
27 (group: Selection<SVGGElement, Datum, any, any>, ...args: any[]): void;
28 /**
29 * Clear the active selection of the brush on the specified SVG G element(s) selection.
30 *
31 * @param group A selection or a transition of SVG G elements
32 * @param selection The selection must be defined as an array of numbers, or null to clear the brush selection.
33 * For a two-dimensional brush, it must be defined as [[x0, y0], [x1, y1]], where x0 is the minimum x-value, y0 is the minimum y-value, x1 is the maximum x-value, and y1 is the maximum y-value.
34 * For an x-brush, it must be defined as [x0, x1]; for a y-brush, it must be defined as [y0, y1].
35 * The selection may also be specified as a function which returns such an array;
36 * if a function, it is invoked for each selected element, being passed the current datum d and index i, with the this context as the current DOM element.
37 * The returned array defines the brush selection for that element.
38 * @param event
39 */
40 move(
41 group: Selection<SVGGElement, Datum, any, any> | TransitionLike<SVGGElement, Datum>,
42 selection: null | BrushSelection | ValueFn<SVGGElement, Datum, BrushSelection>,
43 event?: Event,
44 ): void;
45
46 /**
47 * Clear the active selection of the brush on the specified SVG G element(s) selection.
48 *
49 * @param group A D3 selection of SVG G elements.
50 * @param event
51 */
52 clear(group: Selection<SVGGElement, Datum, any, any>, event?: Event): void;
53
54 /**
55 * Returns the current extent accessor.
56 */
57 extent(): ValueFn<SVGGElement, Datum, [[number, number], [number, number]]>;
58 /**
59 * Set the brushable extent to the specified array of points and returns this brush.
60 *
61 * The brush extent determines the size of the invisible overlay and also constrains the brush selection;
62 * the brush selection cannot go outside the brush extent.
63 *
64 * @param extent array of points [[x0, y0], [x1, y1]], where [x0, y0] is the top-left corner
65 * and [x1, y1] is the bottom-right corner.
66 */
67 extent(extent: [[number, number], [number, number]]): this;
68 /**
69 * Set the brushable extent to the specified array of points returned by the accessor function
70 * evaluated for each element in the selection/transition and returns this brush.
71 *
72 * The brush extent determines the size of the invisible overlay and also constrains the brush selection;
73 * the brush selection cannot go outside the brush extent.
74 *
75 * @param extent An extent accessor function which is evaluated for each selected element,
76 * in order, being passed the current datum (d), the current index (i), and the current group (nodes),
77 * with this as the current DOM element. The function returns an array of points [[x0, y0], [x1, y1]],
78 * where [x0, y0] is the top-left corner and [x1, y1] is the bottom-right corner.
79 */
80 extent(extent: ValueFn<SVGGElement, Datum, [[number, number], [number, number]]>): this;
81
82 /**
83 * Returns the current filter function.
84 */
85 filter(): (this: SVGGElement, event: any, d: Datum) => boolean;
86 /**
87 * Sets the filter to the specified filter function and returns the brush.
88 *
89 * If the filter returns falsey, the initiating event is ignored and no brush gesture is started.
90 * Thus, the filter determines which input events are ignored. The default filter ignores mousedown events on secondary buttons,
91 * since those buttons are typically intended for other purposes, such as the context menu.
92 *
93 * @param filterFn A filter function which is evaluated for each selected element,
94 * in order, being passed the current event `event` and datum `d`, with the `this` context as the current DOM element.
95 * The function returns a boolean value.
96 */
97 filter(filterFn: (this: SVGGElement, event: any, d: Datum) => boolean): this;
98
99 /**
100 * Returns the current touch support detector, which defaults to a function returning true,
101 * if the "ontouchstart" event is supported on the current element.
102 */
103 touchable(): ValueFn<SVGGElement, Datum, boolean>;
104 /**
105 * Sets the touch support detector to the specified boolean value and returns the brush.
106 *
107 * Touch event listeners are only registered if the detector returns truthy for the corresponding element when the brush is applied.
108 * The default detector works well for most browsers that are capable of touch input, but not all; Chrome’s mobile device emulator, for example,
109 * fails detection.
110 *
111 * @param touchable A boolean value. true when touch event listeners should be applied to the corresponding element, otherwise false.
112 */
113 touchable(touchable: boolean): this;
114 /**
115 * Sets the touch support detector to the specified function and returns the drag behavior.
116 *
117 * Touch event listeners are only registered if the detector returns truthy for the corresponding element when the brush is applied.
118 * The default detector works well for most browsers that are capable of touch input, but not all; Chrome’s mobile device emulator, for example,
119 * fails detection.
120 *
121 * @param touchable A touch support detector function, which returns true when touch event listeners should be applied to the corresponding element.
122 * The function is evaluated for each selected element to which the brush was applied, in order, being passed the current datum (d),
123 * the current index (i), and the current group (nodes), with this as the current DOM element. The function returns a boolean value.
124 */
125 touchable(touchable: ValueFn<SVGGElement, Datum, boolean>): this;
126
127 /**
128 * Returns the current key modifiers flag.
129 */
130 keyModifiers(): boolean;
131 /**
132 * Sets the key modifiers flag and returns the brush.
133 *
134 * The key modifiers flag determines whether the brush listens to key events during brushing.
135 * The default value is true.
136 *
137 * @param modifiers New value for key modifiers flag.
138 */
139 keyModifiers(modifiers: boolean): this;
140
141 /**
142 * Returns the current handle size, which defaults to six.
143 */
144 handleSize(): number;
145 /**
146 * Sets the size of the brush handles to the specified number and returns the brush.
147 *
148 * This method must be called before applying the brush to a selection;
149 * changing the handle size does not affect brushes that were previously rendered.
150 * The default size is 6.
151 *
152 * @param size Size of the handle.
153 */
154 handleSize(size: number): this;
155
156 /**
157 * Returns the first currently-assigned listener matching the specified typenames, if any.
158 *
159 * @param typenames The typenames is a string containing one or more typename separated by whitespace.
160 * Each typename is a type, optionally followed by a period (.) and a name, such as "brush.foo"" and "brush.bar";
161 * the name allows multiple listeners to be registered for the same type. The type must be one of the following:
162 * start (at the start of a brush gesture, such as on mousedown), brush (when the brush moves, such as on mousemove), or
163 * end (at the end of a brush gesture, such as on mouseup.)
164 */
165 on(typenames: string): ((this: SVGGElement, event: any, d: Datum) => void) | undefined;
166 /**
167 * Removes the current event listeners for the specified typenames, if any.
168 *
169 * @param typenames The typenames is a string containing one or more typename separated by whitespace.
170 * Each typename is a type, optionally followed by a period (.) and a name, such as "brush.foo"" and "brush.bar";
171 * the name allows multiple listeners to be registered for the same type. The type must be one of the following:
172 * start (at the start of a brush gesture, such as on mousedown), brush (when the brush moves, such as on mousemove), or
173 * end (at the end of a brush gesture, such as on mouseup.)
174 * @param listener Use null to remove the listener.
175 */
176 on(typenames: string, listener: null): this;
177 /**
178 * Sets the event listener for the specified typenames and returns the brush.
179 * If an event listener was already registered for the same type and name,
180 * the existing listener is removed before the new listener is added.
181 * When a specified event is dispatched, each listener will be invoked with the same context and arguments as selection.on listeners.
182 *
183 * @param typenames The typenames is a string containing one or more typename separated by whitespace.
184 * Each typename is a type, optionally followed by a period (.) and a name, such as "brush.foo"" and "brush.bar";
185 * the name allows multiple listeners to be registered for the same type. The type must be one of the following:
186 * start (at the start of a brush gesture, such as on mousedown), brush (when the brush moves, such as on mousemove), or
187 * end (at the end of a brush gesture, such as on mouseup.)
188 * @param listener An event listener function which is evaluated for each selected element,
189 * in order, being passed the current event `event` and datum `d`, with the `this` context as the current DOM element.
190 */
191 on(typenames: string, listener: (this: SVGGElement, event: any, d: Datum) => void): this;
192}
193
194/**
195 * Create a new two-dimensional brush.
196 *
197 * The generic "Datum" refers to the type of the data of the selected svg:g element to
198 * which the returned BrushBehavior will be applied.
199 */
200// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
201export function brush<Datum>(): BrushBehavior<Datum>;
202/**
203 * Creates a new one-dimensional brush along the x-dimension.
204 *
205 * The generic "Datum" refers to the type of the data of the selected svg:g element to
206 * which the returned BrushBehavior will be applied.
207 */
208// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
209export function brushX<Datum>(): BrushBehavior<Datum>;
210/**
211 * Creates a new one-dimensional brush along the y-dimension.
212 *
213 * The generic "Datum" refers to the type of the data of the selected svg:g element to
214 * which the returned BrushBehavior will be applied.
215 */
216// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
217export function brushY<Datum>(): BrushBehavior<Datum>;
218
219/**
220 * Return the current brush selection for the specified node. Internally, an elements brush state is stored as element.__brush;
221 * however, you should use this method rather than accessing it directly. If the given node has no selection, returns null.
222 * Otherwise, the selection is defined as an array of numbers.
223 *
224 * @param node The node for which the brush selection should be returned.
225 */
226export function brushSelection(node: SVGGElement): BrushSelection | null;
227
228/**
229 * D3 brush event
230 *
231 * The generic refers to the type of the datum for the group element on which brush was defined.
232 */
233export interface D3BrushEvent<Datum> {
234 /**
235 * The BrushBehavior associated with the event
236 */
237 target: BrushBehavior<Datum>;
238 /**
239 * The event type for the BrushEvent
240 */
241 type: "start" | "brush" | "end" | string; // Leave failsafe string type for cases like 'brush.foo'
242 /**
243 * The current brush selection associated with the event.
244 * This is null when the selection is empty.
245 */
246 selection: BrushSelection | null;
247 /**
248 * The underlying input event, such as mousemove or touchmove.
249 */
250 sourceEvent: any;
251 /**
252 * The mode of the brush.
253 */
254 mode: "drag" | "space" | "handle" | "center";
255}
256
\No newline at end of file