diff --git a/d3-brush/index.d.ts b/d3-brush/index.d.ts index c1fd783668..fc2fcb739d 100644 --- a/d3-brush/index.d.ts +++ b/d3-brush/index.d.ts @@ -12,35 +12,235 @@ import { ArrayLike, Selection, TransitionLike, ValueFn } from 'd3-selection'; */ export type BrushSelection = [[number, number], [number, number]] | [number, number]; - +/** + * A D3 brush behavior + * + * The generic refers to the type of the datum for the group element on which brush behavior is defined. + */ export interface BrushBehavior { + /** + * Applies the brush to the specified group, which must be a selection of SVG G elements. + * This function is typically not invoked directly, and is instead invoked via selection.call. + * + * For details see: {@link https://github.com/d3/d3-brush#_brush} + * + * @param group A D3 selection of SVG G elements. + * @param args Optional arguments to be passed in. + */ (group: Selection, ...args: any[]): void; + /** + * Clear the active selection of the brush on the specified SVG G element(s) selection. + * + * @param group A D3 selection of SVG G elements. + * @param selection Use null to clear the active brush selection. + */ + move(group: Selection, selection: null): void; + /** + * Sets the active selection of the brush on the specified SVG G element(s) selection + * to the provided array. + * + * @param group A D3 selection of SVG G elements. + * @param selection An array specifying the new active brush selection. 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. For an x-brush, it must be defined as [x0, x1]; + * for a y-brush, it must be defined as [y0, y1]. + */ move(group: Selection, selection: BrushSelection): void; + /** + * Sets the active selection of the brush on the specified SVG G element(s) selection + * based on the array returned by a value function invoked for each selection element. + * + * @param group A D3 selection of SVG G elements. + * @param selection A selection value function which is evaluated for each selected element, + * in order, being passed the current datum (d), the current index (i), and the current group (nodes), + * with this as the current DOM element. The function returns an array specifying the new active brush selection. + * 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. For an x-brush, it must be defined as [x0, x1]; + * for a y-brush, it must be defined as [y0, y1]. + */ move(group: Selection, selection: ValueFn): void; + /** + * Clear the active selection of the brush on the specified SVG G element(s) transition. + * + * @param group A D3 transition on SVG G elements. + * @param selection Use null to clear the active brush selection. + */ + move(group: Selection, selection: null): void; + /** + * Sets the active selection of the brush on the specified SVG G element(s) transition + * to the provided array. + * + * @param group A D3 transition on SVG G elements. + * @param selection An array specifying the new active brush selection. 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. For an x-brush, it must be defined as [x0, x1]; + * for a y-brush, it must be defined as [y0, y1]. + */ move(group: TransitionLike, selection: BrushSelection): void; + /** + * Sets the active selection of the brush on the specified SVG G element(s) transition + * based on the array returned by a value function invoked for each transitioning element. + * + * @param group A D3 transition on SVG G elements. + * @param selection A selection value function which is evaluated for each selected element, + * in order, being passed the current datum (d), the current index (i), and the current group (nodes), + * with this as the current DOM element. The function returns an array specifying the new active brush selection. + * 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. For an x-brush, it must be defined as [x0, x1]; + * for a y-brush, it must be defined as [y0, y1]. + */ move(group: TransitionLike, selection: ValueFn): void; + /** + * Returns the current extent accessor. + */ extent(): ValueFn; + /** + * Set the brushable extent to the specified array of points and returns this brush. + * + * The brush extent determines the size of the invisible overlay and also constrains the brush selection; + * the brush selection cannot go outside the brush extent. + * + * @param extent array of points [[x0, y0], [x1, y1]], where [x0, y0] is the top-left corner + * and [x1, y1] is the bottom-right corner. + */ extent(extent: [[number, number], [number, number]]): this; + /** + * Set the brushable extent to the specified array of points returned by the accessor function + * evaluated for each element in the selection/transition and returns this brush. + * + * The brush extent determines the size of the invisible overlay and also constrains the brush selection; + * the brush selection cannot go outside the brush extent. + * + * @param extent An extent accessor function which is evaluated for each selected element, + * in order, being passed the current datum (d), the current index (i), and the current group (nodes), + * with this as the current DOM element. The function returns an array of points [[x0, y0], [x1, y1]], + * where [x0, y0] is the top-left corner and [x1, y1] is the bottom-right corner. + */ extent(extent: ValueFn): this; + + /** + * Returns the current filter function. + */ filter(): ValueFn; + /** + * Sets the filter to the specified filter function and returns the brush. + * + * If the filter returns falsey, the initiating event is ignored and no brush gesture is started. + * Thus, the filter determines which input events are ignored. The default filter ignores mousedown events on secondary buttons, + * since those buttons are typically intended for other purposes, such as the context menu. + * + * @param filterFn A filter function which is evaluated for each selected element, + * in order, being passed the current datum (d), the current index (i), and the current group (nodes), + * with this as the current DOM element. The function returns a boolean value. + */ filter(filterFn: ValueFn): this; + + /** + * Returns the current handle size, which defaults to six. + */ handleSize(): number; + /** + * Sets the size of the brush handles to the specified number and returns the brush. + * + * This method must be called before applying the brush to a selection; + * changing the handle size does not affect brushes that were previously rendered. + * The default size is 6. + * + * @param size Size of the handle. + */ handleSize(size: number): this; + + /** + * Returns the first currently-assigned listener matching the specified typenames, if any. + * + * @param typenames The typenames is a string containing one or more typename separated by whitespace. + * Each typename is a type, optionally followed by a period (.) and a name, such as "brush.foo"" and "brush.bar"; + * the name allows multiple listeners to be registered for the same type. The type must be one of the following: + * start (at the start of a brush gesture, such as on mousedown), brush (when the brush moves, such as on mousemove), or + * end (at the end of a brush gesture, such as on mouseup.) + */ on(typenames: string): ValueFn; - on(typenames: string, callback: null): this; - on(typenames: string, callback: ValueFn): this; + /** + * Removes the current event listeners for the specified typenames, if any. + * + * @param typenames The typenames is a string containing one or more typename separated by whitespace. + * Each typename is a type, optionally followed by a period (.) and a name, such as "brush.foo"" and "brush.bar"; + * the name allows multiple listeners to be registered for the same type. The type must be one of the following: + * start (at the start of a brush gesture, such as on mousedown), brush (when the brush moves, such as on mousemove), or + * end (at the end of a brush gesture, such as on mouseup.) + * @param listener Use null to remove the listener. + */ + on(typenames: string, listener: null): this; + /** + * Sets the event listener for the specified typenames and returns the brush. + * If an event listener was already registered for the same type and name, + * the existing listener is removed before the new listener is added. + * When a specified event is dispatched, each listener will be invoked with the same context and arguments as selection.on listeners. + * + * @param typenames The typenames is a string containing one or more typename separated by whitespace. + * Each typename is a type, optionally followed by a period (.) and a name, such as "brush.foo"" and "brush.bar"; + * the name allows multiple listeners to be registered for the same type. The type must be one of the following: + * start (at the start of a brush gesture, such as on mousedown), brush (when the brush moves, such as on mousemove), or + * end (at the end of a brush gesture, such as on mouseup.) + * @param listener An event listener function which is evaluated for each selected element, + * in order, being passed the current datum (d), the current index (i), and the current group (nodes), + * with this as the current DOM element. + */ + on(typenames: string, listener: ValueFn): this; } +/** + * Create a new two-dimensional brush. + * + * The generic "Datum" refers to the type of the data of the selected svg:g element to + * which the returned BrushBEhavoir will be applied. + */ export function brush(): BrushBehavior; +/** + * Creates a new one-dimensional brush along the x-dimension. + * + * The generic "Datum" refers to the type of the data of the selected svg:g element to + * which the returned BrushBEhavoir will be applied. + */ export function brushX(): BrushBehavior; +/** + * Creates a new one-dimensional brush along the y-dimension. + * + * The generic "Datum" refers to the type of the data of the selected svg:g element to + * which the returned BrushBEhavoir will be applied. + */ export function brushY(): BrushBehavior; -export function brushSelection(node: SVGGElement): BrushSelection; +/** + * Return the current brush selection for the specified node. Internally, an element’s brush state is stored as element.__brush; + * however, you should use this method rather than accessing it directly. If the given node has no selection, returns null. + * Otherwise, the selection is defined as an array of numbers. + * + * @param node The node for which the brush selection should be returned. + */ +export function brushSelection(node: SVGGElement): BrushSelection | null; +/** + * D3 brush event + * + * The generic refers to the type of the datum for the group element on which brush was defined. + */ export interface D3BrushEvent { + /** + * The BrushBehavior associated with the event + */ target: BrushBehavior; + /** + * The event type for the BrushEvent + */ type: 'start' | 'brush' | 'end' | string; // Leave failsafe string type for cases like 'brush.foo' + /** + * The current brush selection associated with the event. + */ selection: BrushSelection; + /** + * The underlying input event, such as mousemove or touchmove. + */ sourceEvent: any; } diff --git a/d3-drag/index.d.ts b/d3-drag/index.d.ts index 9ec6605753..60c140f313 100644 --- a/d3-drag/index.d.ts +++ b/d3-drag/index.d.ts @@ -29,44 +29,333 @@ export type DragContainerElement = HTMLElement | SVGSVGElement | SVGGElement; // * of the subject and the pointer can be preserved during the drag gesture. */ export interface SubjectPosition { + /** + * x-coordinate + */ x: number; + /** + * y-coordinate + */ y: number; } +/** + * A D3 Drag Behavior + * + * The first generic refers to the type of element to be dragged. + * The second generic refers to the type of the datum of the dragged element. + * The third generic refers to the type of the drag behavior subject. + * + * The subject of a drag gesture represents the thing being dragged. + * It is computed when an initiating input event is received, + * such as a mousedown or touchstart, immediately before the drag gesture starts. + * The subject is then exposed as event.subject on subsequent drag events for this gesture. + * + * The default subject is the datum of the element in the originating selection (see drag) + * that received the initiating input event; if this datum is undefined, + * an object representing the coordinates of the pointer is created. + * When dragging circle elements in SVG, the default subject is thus the datum of the circle being dragged. + * With Canvas, the default subject is the canvas element’s datum (regardless of where on the canvas you click). + * In this case, a custom subject accessor would be more appropriate, + * such as one that picks the closest circle to the mouse within a given search radius. + */ export interface DragBehavior extends Function { + /** + * Applies the drag behavior to the selected elements. + * This function is typically not invoked directly, and is instead invoked via selection.call. + * + * For details see: {@link https://github.com/d3/d3-drag#_drag} + * + * @param selection A D3 selection of elements. + * @param args Optional arguments to be passed in. + */ (selection: Selection, ...args: any[]): void; + + /** + * Returns the current container accessor function. + */ container(): ValueFn; + /** + * Sets the container accessor to the specified function and returns the drag behavior. + * + * The container of a drag gesture determines the coordinate system of subsequent drag events, + * affecting event.x and event.y. The element returned by the container accessor is subsequently + * passed to d3.mouse or d3.touch, as appropriate, to determine the local coordinates of the pointer. + * + * The default container accessor returns the parent node of the element in the originating selection (see drag) + * that received the initiating input event. This is often appropriate when dragging SVG or HTML elements, + * since those elements are typically positioned relative to a parent. For dragging graphical elements with a Canvas, + * however, you may want to redefine the container as the initiating element itself, using "this" in the accessor + * function. + * + * @param accessor A container accessor function which is evaluated for each selected element, + * in order, being passed the current datum (d), the current index (i), and the current group (nodes), + * with this as the current DOM element. The function returns the container element. + */ container(accessor: ValueFn): this; + /** + * Sets the container accessor to the specified object and returns the drag behavior. + * + * The container of a drag gesture determines the coordinate system of subsequent drag events, + * affecting event.x and event.y. The element returned by the container accessor is subsequently + * passed to d3.mouse or d3.touch, as appropriate, to determine the local coordinates of the pointer. + * + * The default container accessor returns the parent node of the element in the originating selection (see drag) + * that received the initiating input event. This is often appropriate when dragging SVG or HTML elements, + * since those elements are typically positioned relative to a parent. For dragging graphical elements with a Canvas, + * however, you may want to redefine the container as the initiating element itself, such as drag.container(canvas). + * + * @param container Container element for the drag gesture. + */ container(container: DragContainerElement): this; + + /** + * Returns the current filter function. + */ filter(): ValueFn; + + /** + * Sets the filter to the specified filter function and returns the drag behavior. + * + * If the filter returns falsey, the initiating event is ignored and no drag gesture is started. + * Thus, the filter determines which input events are ignored. The default filter ignores mousedown events on secondary buttons, + * since those buttons are typically intended for other purposes, such as the context menu. + * + * @param filterFn A filter function which is evaluated for each selected element, + * in order, being passed the current datum (d), the current index (i), and the current group (nodes), + * with this as the current DOM element. The function returns a boolean value. + */ filter(filterFn: ValueFn): this; + + /** + * Returns the current subject accessor functions. + */ subject(): ValueFn; + /** + * Sets the subject accessor to the specified function and returns the drag behavior. + * + * The subject of a drag gesture represents the thing being dragged. + * It is computed when an initiating input event is received, + * such as a mousedown or touchstart, immediately before the drag gesture starts. + * The subject is then exposed as event.subject on subsequent drag events for this gesture. + * + * The default subject is the datum of the element in the originating selection (see drag) + * that received the initiating input event; if this datum is undefined, + * an object representing the coordinates of the pointer is created. + * When dragging circle elements in SVG, the default subject is thus the datum of the circle being dragged. + * With Canvas, the default subject is the canvas element’s datum (regardless of where on the canvas you click). + * In this case, a custom subject accessor would be more appropriate, + * such as one that picks the closest circle to the mouse within a given search radius. + * + * + * + * The subject of a drag gesture may not be changed after the gesture starts. + * + * During the evaluation of the subject accessor, d3.event is a beforestart drag event. + * Use event.sourceEvent to access the initiating input event and event.identifier to + * access the touch identifier. The event.x and event.y are relative to the container, + * and are computed using d3.mouse or d3.touch as appropriate. + * + * @param accessor An extent accessor function which is evaluated for each selected element, + * in order, being passed the current datum (d), the current index (i), and the current group (nodes), + * with this as the current DOM element.The returned subject should be an object that exposes x and y properties, + * so that the relative position of the subject and the pointer can be preserved during the drag gesture. + * If the subject is null or undefined, no drag gesture is started for this pointer; + * however, other starting touches may yet start drag gestures. + */ subject(accessor: ValueFn): this; + + /** + * Return the first currently-assigned listener matching the specified typenames, if any. + * + * @param typenames The typenames is a string containing one or more typename separated by whitespace. + * Each typename is a type, optionally followed by a period (.) and a name, such as "drag.foo"" and "drag.bar"; + * the name allows multiple listeners to be registered for the same type. The type must be one of the following: + * start (after a new pointer becomes active [on mousedown or touchstart]), drag (after an active pointer moves [on mousemove or touchmove], or + * end (after an active pointer becomes inactive [on mouseup, touchend or touchcancel].) + */ on(typenames: string): ValueFn; - on(typenames: string, callback: null): this; - on(typenames: string, callback: ValueFn): this; + /** + * Remove the current event listeners for the specified typenames, if any, return the drag behavior. + * + * @param typenames The typenames is a string containing one or more typename separated by whitespace. + * Each typename is a type, optionally followed by a period (.) and a name, such as "drag.foo"" and "drag.bar"; + * the name allows multiple listeners to be registered for the same type. The type must be one of the following: + * start (after a new pointer becomes active [on mousedown or touchstart]), drag (after an active pointer moves [on mousemove or touchmove], or + * end (after an active pointer becomes inactive [on mouseup, touchend or touchcancel].) + * @param listener Use null to remove the listener. + */ + on(typenames: string, listener: null): this; + /** + * Set the event listener for the specified typenames and return the drag behavior. + * If an event listener was already registered for the same type and name, + * the existing listener is removed before the new listener is added. + * When a specified event is dispatched, each listener will be invoked with the same context and arguments as selection.on listeners. + * + * Changes to registered listeners via drag.on during a drag gesture do not affect the current drag gesture. + * Instead, you must use event.on, which also allows you to register temporary event listeners for the current drag gesture. + * Separate events are dispatched for each active pointer during a drag gesture. + * For example, if simultaneously dragging multiple subjects with multiple fingers, a start event is dispatched for each finger, + * even if both fingers start touching simultaneously. + * + * @param typenames The typenames is a string containing one or more typename separated by whitespace. + * Each typename is a type, optionally followed by a period (.) and a name, such as "drag.foo"" and "drag.bar"; + * the name allows multiple listeners to be registered for the same type. The type must be one of the following: + * start (after a new pointer becomes active [on mousedown or touchstart]), drag (after an active pointer moves [on mousemove or touchmove], or + * end (after an active pointer becomes inactive [on mouseup, touchend or touchcancel].) + * @param listener An event listener function which is evaluated for each selected element, + * in order, being passed the current datum (d), the current index (i), and the current group (nodes), + * with this as the current DOM element. + */ + on(typenames: string, listener: ValueFn): this; } +/** + * Creates a new drag behavior. The returned behavior, drag, is both an object and a function, and is + * typically applied to selected elements via selection.call. + * + * Use this signature when using the default subject accessor. + * + * The first generic refers to the type of element to be dragged. + * The second generic refers to the type of the datum of the dragged element. + */ export function drag(): DragBehavior; +/** + * Creates a new drag behavior. The returned behavior, drag, is both an object and a function, and is + * typically applied to selected elements via selection.call. + * + * Use this signature when using a custom subject accessor. + * + * The first generic refers to the type of element to be dragged. + * The second generic refers to the type of the datum of the dragged element. + * The third generic refers to the type of the drag behavior subject. + */ export function drag(): DragBehavior; - +/** + * D3 Drag event + * + * The first generic refers to the type of element to be dragged. + * The second generic refers to the type of the datum of the dragged element. + * The third generic refers to the type of the drag behavior subject. + */ export interface D3DragEvent { + /** + * The DragBehavior associated with the event + */ target: DragBehavior; + /** + * The event type for the DragEvent + */ type: 'start' | 'drag' | 'end' | string; // Leave failsafe string type for cases like 'drag.foo' + /** + * The drag subject, defined by drag.subject. + */ subject: Subject; + /** + * The new x-coordinate of the subject, relative to the container + */ x: number; + /** + * The new y-coordinate of the subject, relative to the container + */ y: number; + /** + * The change in x-coordinate since the previous drag event. + */ dx: number; + /** + * The change in y-coordinate since the previous drag event. + */ dy: number; + /** + * The string “mouse”, or a numeric touch identifier. + */ identifier: 'mouse' | number; + /** + * The number of currently active drag gestures (on start and end, not including this one). + * + * The event.active field is useful for detecting the first start event and the last end event + * in a sequence of concurrent drag gestures: it is zero when the first drag gesture starts, + * and zero when the last drag gesture ends. + */ active: number; + /** + * The underlying input event, such as mousemove or touchmove. + */ sourceEvent: any; + /** + * Return the first currently-assigned listener matching the specified typenames, if any. + * + * Equivalent to drag.on, but only applies to the current drag gesture. Before the drag gesture starts, + * a copy of the current drag event listeners is made. This copy is bound to the current drag gesture + * and modified by event.on. This is useful for temporary listeners that only receive events for the current drag gesture. + * + * @param typenames The typenames is a string containing one or more typename separated by whitespace. + * Each typename is a type, optionally followed by a period (.) and a name, such as "drag.foo"" and "drag.bar"; + * the name allows multiple listeners to be registered for the same type. The type must be one of the following: + * start (after a new pointer becomes active [on mousedown or touchstart]), drag (after an active pointer moves [on mousemove or touchmove], or + * end (after an active pointer becomes inactive [on mouseup, touchend or touchcancel].) + */ on(typenames: string): ValueFn; - on(typenames: string, callback: null): this; - on(typenames: string, callback: ValueFn): this; + /** + * Remove the current event listeners for the specified typenames, if any, return the drag behavior. + * + * Equivalent to drag.on, but only applies to the current drag gesture. Before the drag gesture starts, + * a copy of the current drag event listeners is made. This copy is bound to the current drag gesture + * and modified by event.on. This is useful for temporary listeners that only receive events for the current drag gesture. + * + * @param typenames The typenames is a string containing one or more typename separated by whitespace. + * Each typename is a type, optionally followed by a period (.) and a name, such as "drag.foo"" and "drag.bar"; + * the name allows multiple listeners to be registered for the same type. The type must be one of the following: + * start (after a new pointer becomes active [on mousedown or touchstart]), drag (after an active pointer moves [on mousemove or touchmove], or + * end (after an active pointer becomes inactive [on mouseup, touchend or touchcancel].) + * @param listener Use null to remove the listener. + */ + on(typenames: string, listener: null): this; + /** + * Set the event listener for the specified typenames and return the drag behavior. + * If an event listener was already registered for the same type and name, + * the existing listener is removed before the new listener is added. + * When a specified event is dispatched, each listener will be invoked with the same context and arguments as selection.on listeners. + * + * Equivalent to drag.on, but only applies to the current drag gesture. Before the drag gesture starts, + * a copy of the current drag event listeners is made. This copy is bound to the current drag gesture + * and modified by event.on. This is useful for temporary listeners that only receive events for the current drag gesture. + * + * @param typenames The typenames is a string containing one or more typename separated by whitespace. + * Each typename is a type, optionally followed by a period (.) and a name, such as "drag.foo"" and "drag.bar"; + * the name allows multiple listeners to be registered for the same type. The type must be one of the following: + * start (after a new pointer becomes active [on mousedown or touchstart]), drag (after an active pointer moves [on mousemove or touchmove], or + * end (after an active pointer becomes inactive [on mouseup, touchend or touchcancel].) + * @param listener An event listener function which is evaluated for each selected element, + * in order, being passed the current datum (d), the current index (i), and the current group (nodes), + * with this as the current DOM element. + */ + on(typenames: string, listener: ValueFn): this; } +/** + * Prevents native drag-and-drop and text selection on the specified window. + * As an alternative to preventing the default action of mousedown events, + * this method prevents undesirable default actions following mousedown. In supported browsers, + * this means capturing dragstart and selectstart events, preventing the associated default actions, + * and immediately stopping their propagation. In browsers that do not support selection events, + * the user-select CSS property is set to none on the document element. + * This method is intended to be called on mousedown, followed by d3.dragEnable on mouseup. + * + * @param window The window for which drag should be disabled. + */ export function dragDisable(window: Window): void; +/** + * Allows native drag-and-drop and text selection on the specified window; undoes the effect of d3.dragDisable. + * This method is intended to be called on mouseup, preceded by d3.dragDisable on mousedown. + * If noclick is true, this method also temporarily suppresses click events. + * The suppression of click events expires after a zero-millisecond timeout, + * such that it only suppress the click event that would immediately follow the current mouseup event, if any. + * + * @param window The window for which drag should be (re-)enabled. + * @param noClick An optional flag. If noclick is true, this method also temporarily suppresses click events. + */ export function dragEnable(window: Window, noClick?: boolean): void;