From 59ff802dab9b1032f9678fa19fc2dcff41f72532 Mon Sep 17 00:00:00 2001 From: Tom Wanzek Date: Mon, 3 Oct 2016 10:49:43 -0400 Subject: [PATCH] [types-2.0] d3-selection and d3-transition JSDoc comments and fixes (#11497) * d3-selection * [Chore]: Completed JSDoc comments * [Chore]: Removed outdated comments * [Enhancement]: Added some explicit setter signatures, where using the setter with `null` as a value clears the set attribute, style, property * [Enhancement]: Added explicit possible `null` return value for `touch(...)` if touch cannot, be found for the fiven identifier * d3-transition and d3-selection * **[chore](d3-selection)**: Added JSDoc comments for Selection<...> interface and param priority to style(...) * **[enhancement](d3-selection)**: Started adding some `| null` for strict null checking. In ValueFn passed into `attr`, `style`, `text`, `html`. Clarifying the ability to clear the respective property when `null` is returned. Also added `| null` to `node()` return type. * **[chore](d3-transition)**: Added JSDoc comments. * **[enhancement/fix](d3-transition)**: Updated signatures for `attrTween(...)` and `styleTween(...)` to align them with curent API doc. Added getter, remover and reduced permissible return type for interpolator to `string`. Added getter signature for `tween(...)` * **[enhancement](d3-transition)**: Added ``| null` in preparation of strict null checking support to ValueFn return types for `attr`, `style`, and `text`. Same with return type for `node()`. * [BREAKING](d3-transition): Return type of interpolators returned by tween factories in `attr` and `style` has been reduced to `string` as per API doc. (One test was adjusted accordingly) * d3-transition * [BREAKING](d3-transition): Fixed signatures for top-level `transition` method. The generics have been updated, as only the datum type in the returned transition needs to be typed. The rest is pre-determined based on a document root selection. * **[Fix](d3-transition)**: When using an existing transition as an argument, the transition type is not constrained for the argument. * Adjusted affected tests. * d3-transition * [chore](d3-transition): Updated patch version of reference module to 1.0.2 --- d3-selection/index.d.ts | 829 +++++++++++++++++++++++++-- d3-transition/d3-transition-tests.ts | 14 +- d3-transition/index.d.ts | 473 ++++++++++++++- 3 files changed, 1250 insertions(+), 66 deletions(-) diff --git a/d3-selection/index.d.ts b/d3-selection/index.d.ts index 95a9e2ad56..5919e9ce39 100644 --- a/d3-selection/index.d.ts +++ b/d3-selection/index.d.ts @@ -13,15 +13,21 @@ * be supported. */ export type BaseType = Element | EnterElement | Window; -// export type BaseType = any; // Alternative, very permissive BaseType specification for edge cases +/** + * A helper interface which covers arguments like NodeListOf or HTMLCollectionOf + * argument types + */ export interface ArrayLike { length: number; item(index: number): T; [index: number]: T; } - +/** + * An interface describing the element type of the Enter Selection group elements + * created when invoking selection.enter(). + */ export interface EnterElement { ownerDocument: Document; namespaceURI: string; @@ -70,7 +76,7 @@ export type ValueFn = (this: Element, datum: Datum, inde * The use of this interface instead of the full imported Transition interface is [referred] to achieve * two things: * (1) the d3-transition module may not be required by a projects use case, - * (2) it avoid avoids possible complications from 'module augmentation' from d3-transition to Selection. + * (2) it avoids possible complications from 'module augmentation' from d3-transition to Selection. */ export interface TransitionLike { selection(): Selection; @@ -86,48 +92,260 @@ export interface TransitionLike { // All Selection related interfaces and function // -------------------------------------------------------------------------- -// NB: Note that, d3.select does not generate the same parent element, when targeting the same DOM element with string selector -// or node element +/** + * Select the first element that matches the specified selector string. If no elements match the selector, returns an empty selection. + * If multiple elements match the selector, only the first matching element (in document order) will be selected. + * + * The first generic "GElement" refers to the type of element to be selected. The second generic "OldDatum" refers to the type of the + * datum, on the selected element. This is useful when re-selecting an element with a previously set, know datum type. + * + * @param selector CSS selector string + */ export function select(selector: string): Selection; +/** + * Select the specified node element. + * + * The first generic "GElement" refers to the type of element to be selected. The second generic "OldDatum" refers to the type of the + * datum, on the selected element. This is useful when re-selecting an element with a previously set, know datum type. + * + * @param node An element to be selected + */ export function select(node: GElement): Selection; -export function selectAll(): Selection; // _groups are set to empty array, first generic type is set to null by convention -export function selectAll(selector: null): Selection; // _groups are set to empty array, first generic type is set to null by convention +/** + * Create an empty selection. + */ +export function selectAll(): Selection; +/** + * Create an empy selection. + */ +export function selectAll(selector: null): Selection; +/** + * Select all elements that match the specified selector string. The elements will be selected in document order (top-to-bottom). + * If no elements in the document match the selector, returns an empty selection. + * + * The first generic "GElement" refers to the type of element to be selected. The second generic "OldDatum" refers to the type of the + * datum, of a selected element. This is useful when re-selecting elements with a previously set, know datum type. + * + * @param selector CSS selector string + */ export function selectAll(selector: string): Selection; +/** + * Select the specified array of nodes. + * + * The first generic "GElement" refers to the type of element to be selected. The second generic "OldDatum" refers to the type of the + * datum, of a selected element. This is useful when re-selecting elements with a previously set, know datum type. + * + * @param nodes An Array of nodes + */ export function selectAll(nodes: GElement[]): Selection; +/** + * Select the specified nodes. This signature allows the selection of nodes contained in a NodeList, HTMLCollection or similar data structure. + * + * The first generic "GElement" refers to the type of element to be selected. The second generic "OldDatum" refers to the type of the + * datum, of a selected element. This is useful when re-selecting elements with a previously set, know datum type. + * + * @param nodes An Array-like collection of nodes + */ export function selectAll(nodes: ArrayLike): Selection; - +/** + * A D3 Selection of elements. + * + * The first generic "GElement" refers to the type of the selected element(s). + * The second generic "Datum" refers to the type of the datum of a selected element(s). + * The third generic "PElement" refers to the type of the parent element(s) in the D3 selection. + * The fourth generic "PDatum" refers to the type of the datum of the parent element(s). + */ interface Selection { // Sub-selection ------------------------- + /** + * For each selected element, select the first descendant element that matches the specified selector string. + * If no element matches the specified selector for the current element, the element at the current index will + * be null in the returned selection. If multiple elements match the selector, only the first matching element + * in document order is selected. Selection.select does not affect grouping: it preserves the existing group + * structure and indexes, and propagates data (if any) to selected children. + * + * If the current element has associated data, this data is propagated to the + * corresponding selected element. + * + * The generic represents the type of the descendant element to be selected. + * + * @param selector CSS selector string + */ select(selector: string): Selection; - select(selector: null): Selection; // _groups are set to empty array, first generic type is set to null by convention + /** + * Create an empty sub-selection. Selection.select does not affect grouping: it preserves the existing group + * structure and indexes. + */ + select(selector: null): Selection; + /** + * For each selected element, select the descendant element returned by the selector function. + * If no element is returned by the selector function for the current element, the element at the + * current index will be null in the returned selection. Selection.select does not affect grouping: + * it preserves the existing group structure and indexes, and propagates data (if any) to selected children. + * + * If the current element has associated data, this data is propagated to the + * corresponding selected element. + * + * The generic represents the type of the descendant element to be selected. + * + * @param selector A selector 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. + * It must return an element, or null if there is no matching element. + */ select(selector: ValueFn): Selection; - selectAll(): Selection; // _groups are set to empty array, first generic type is set to null by convention - selectAll(selector: null): Selection; // _groups are set to empty array, first generic type is set to null by convention + /** + * Create an empty sub-selection. Selection.selectAll does affect grouping: The elements in the returned + * selection are grouped by their corresponding parent node in this selection, the group at the current index will be empty. + */ + selectAll(): Selection; + /** + * Create an empty sub-selection. Selection.selectAll does affect grouping: The elements in the returned + * selection are grouped by their corresponding parent node in this selection, the group at the current index will be empty. + */ + selectAll(selector: null): Selection; + /** + * For each selected element, selects the descendant elements that match the specified selector string. The elements in the returned + * selection are grouped by their corresponding parent node in this selection. If no element matches the specified selector + * for the current element, the group at the current index will be empty. Selection.selectAll does affect grouping: each selected descendant + * is grouped by the parent element in the originating selection. + * + * The selected elements do not inherit data from this selection; use selection.data to propagate data to children. + * + * The first generic "DescElement" refers to the type of descendant element to be selected. The second generic "OldDatum" refers to the type of the + * datum, of a selected element. This is useful when re-selecting elements with a previously set, know datum type. + * + * @param selector CSS selector string + */ selectAll(selector: string): Selection; + + /** + * For each selected element, selects the descendant elements returned by the selector function. The elements in the returned + * selection are grouped by their corresponding parent node in this selection. If no element matches the specified selector + * for the current element, the group at the current index will be empty. Selection.selectAll does affect grouping: each selected descendant + * is grouped by the parent element in the originating selection. + * + * The selected elements do not inherit data from this selection; use selection.data to propagate data to children. + * + * The first generic "DescElement" refers to the type of descendant element to be selected. The second generic "OldDatum" refers to the type of the + * datum, of a selected element. This is useful when re-selecting elements with a previously set, know datum type. + * + * @param selector A selector 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. It must return an array of elements + * (or a pseudo-array, such as a NodeList), or the empty array if there are no matching elements. + */ selectAll(selector: ValueFn | ArrayLike>): Selection; // Modifying ------------------------------- + /** + * Return the current value of the specified attribute for the first (non-null) element in the selection. + * This is generally useful only if you know that the selection contains exactly one element. + * + * @param name Name of the attribute + */ attr(name: string): string; + /** + * Clear the attribute with the specified name for the selected elements and returns this selection. + * + * @param name Name of the attribute + * @param value null,to clear the attribute + */ attr(name: string, value: null): this; + /** + * Sets the value of the attribute with the specified name for the selected elements and returns this selection. + * All elements are given the same attribute value. + * + * @param name Name of the attribute + * @param value Constant value for the attribute + */ attr(name: string, value: string | number | boolean): this; - attr(name: string, value: ValueFn): this; + /** + * Sets the value of the attribute with the specified name for the selected elements and returns this selection. + * The value for the individual selected elements is determined by the value function. + * + * @param name Name of the attribute + * @param value A 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. A null value will clear the attribute. + */ + attr(name: string, value: ValueFn): this; - classed(name: string): boolean; - classed(name: string, value: boolean): this; - classed(name: string, value: ValueFn): this; + /** + * Returns true if and only if the first (non-null) selected element has the specified classes. + * This is generally useful only if you know the selection contains exactly one element. + * + * @param name A string of space-separated class names. + */ + classed(names: string): boolean; + /** + * Assigns or unassigns the specified CSS class names on the selected elements by setting + * the class attribute or modifying the classList property and returns this selection. + * If the constant value is truthy, then all elements are assigned the specified classes; otherwise, the classes are unassigned. + * + * @param names A string of space-separated class names. + * @param value A boolean flag (true = assign / false = unassign) + */ + classed(names: string, value: boolean): this; + /** + * Assigns or unassigns the specified CSS class names on the selected elements by setting + * the class attribute or modifying the classList property and returns this selection. + * The assign/unassign status for the individual selected elements is determined by the boolean return + * value of the value function. + * + * @param names A string of space-separated class names. + * @param value A 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’s return value is then used to assign or unassign classes on each element. + */ + classed(names: string, value: ValueFn): this; + /** + * Returns the current computed value of the specified style for the first (non-null) element in the selection. + * This is generally useful only if you know that the selection contains exactly one element. + * The computed value may be different than the previously-set value, particularly if it was set using a + * shorthand property (such as the font style, which is shorthand for font-size, font-face, etc.). + * + * @param name Name of the style + */ style(name: string): string; + /** + * Clear the style with the specified name for the selected elements and returns this selection. + * + * @param name Name of the style + * @param value null,to clear the style + */ style(name: string, value: null): this; + /** + * Sets the value of the style with the specified name for the selected elements and returns this selection. + * All elements are given the same style value. + * + * @param name Name of the style + * @param value Constant value for the style + * @param priority An optional priority flag, either null or the string important (without the exclamation point) + */ style(name: string, value: string | number | boolean, priority?: null | 'important'): this; - style(name: string, value: ValueFn, priority?: null | 'important'): this; + /** + * Sets the value of the style with the specified name for the selected elements and returns this selection. + * The value for the individual selected elements is determined by the value function. + * + * @param name Name of the style + * @param value A 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. A null value will clear the style. + * @param priority An optional priority flag, either null or the string important (without the exclamation point) + */ + style(name: string, value: ValueFn, priority?: null | 'important'): this; + /** + * Return the current value of the specified property for the first (non-null) element in the selection. + * This is generally useful only if you know that the selection contains exactly one element. + * + * @param name Name of the property + */ property(name: string): any; /** * Look up a local variable on the first node of this selection. Note that this is not equivalent to `local.get(selection.node())` in that it will not look up locals set on the parent node(s). @@ -135,38 +353,201 @@ interface Selection(name: Local): T | undefined; + /** + * Sets the value of the property with the specified name for the selected elements and returns this selection. + * The value for the individual selected elements is determined by the value function. + * + * Some HTML elements have special properties that are not addressable using attributes or styles, + * such as a form field’s text value and a checkbox’s checked boolean. Use this method to get or set these properties. + * + * @param name Name of the property + * @param value A 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. A null value will clear the property. + */ property(name: string, value: ValueFn): this; + /** + * Clears the property with the specified name for the selected elements and returns this selection. + * + * @param name Name of the property + * @param value null,to clear the property + */ property(name: string, value: null): this; + /** + * Sets the value of the property with the specified name for the selected elements and returns this selection. + * All elements are given the same property value. + * + * @param name Name of the property + * @param value Constant value for the property + */ property(name: string, value: any): this; /** - * Store a value in a `d3.local` variable. This is equivalent to `selection.each(function (d, i, g) { name.set(this, value.call(this, d, i, g)); })` but more concise. + * Store a value in a `d3.local` variable. + * This is equivalent to `selection.each(function (d, i, g) { name.set(this, value.call(this, d, i, g)); })` but more concise. * * @param name A `d3.local` variable * @param value A callback that returns the value to store */ property(name: Local, value: ValueFn): this; /** - * Store a value in a `d3.local` variable for each node in the selection. This is equivalent to `selection.each(function () { name.set(this, value); })` but more concise. + * Store a value in a `d3.local` variable for each node in the selection. + * This is equivalent to `selection.each(function () { name.set(this, value); })` but more concise. * * @param name A `d3.local` variable * @param value A callback that returns the value to store */ property(name: Local, value: T): this; + /** + * Returns the text content for the first (non-null) element in the selection. + * This is generally useful only if you know the selection contains exactly one element. + */ text(): string; + /** + * Clear the text content of the selected elements and return the selection. + */ + text(value: null): this; + /** + * Sets the text content to the specified value on all selected elements, replacing any existing child elements. + * All elements are given the same text content. + * + * @param value Text content value for the elements. + */ text(value: string | number | boolean): this; - text(value: ValueFn): this; + /** + * Sets the text content to the specified value on all selected elements, replacing any existing child elements. + * All elements are given the same text content. + * + * @param value A value unction 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’s return value is then used to set each element’s text content. A null value will clear the content. + */ + text(value: ValueFn): this; + /** + * Returns a string representation of the inner HTML for the first (non-null) element in the selection. + * This is generally useful only if you know the selection contains exactly one element. + */ html(): string; + /** + * Clear the html content of the selected elements and return the selection. + */ + html(value: null): this; + /** + * Sets the inner HTML to the specified value on all selected elements, replacing any existing child elements. + * All elements are given the same inner HTML + * + * @param value String representation of inner HTML. + */ html(value: string): this; - html(value: ValueFn): this; + /** + * Sets the inner HTML to the specified value on all selected elements, replacing any existing child elements. + * The inner HTML is determined for each individual element using a value function. + * + * @param value A 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’s return value is then used to set each element’s inner HTML. A null value will clear the content. + */ + html(value: ValueFn): this; + /** + * Appends a new element of the specified type (tag name) as the last child of each selected element, or the next + * following sibling in the update selection if this is an enter selection. + * (The enter behavior allows you to insert elements into the DOM in an order consistent with bound data; + * however, the slower selection.order may still be required if updating elements change order.) + * + * This method returns a new selection containing the appended elements. + * Each new element inherits the data of the current elements, if any. + * + * The generic refers to the type of the child element to be appended. + * + * @param type A string representing the tag name. The specified name may have a namespace prefix, such as svg:text + * to specify a text attribute in the SVG namespace. If no namespace is specified, the namespace will be inherited + * from the parent element; or, if the name is one of the known prefixes, the corresponding namespace will be used + * (for example, svg implies svg:svg) + */ append(type: string): Selection; + /** + * Appends a new element of the type provided by the element creator function as the last child of each selected element, + * or the next following sibling in the update selection if this is an enter selection. + * (The enter behavior allows you to insert elements into the DOM in an order consistent with bound data; + * however, the slower selection.order may still be required if updating elements change order.) + * + * This method returns a new selection containing the appended elements. + * Each new element inherits the data of the current elements, if any. + * + * The generic refers to the type of the child element to be appended. + * + * @param type A creator 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. This function should return + * an element to be appended. (The function typically creates a new element, but it may instead return an existing element.) + */ append(type: ValueFn): Selection; + /** + * Inserts a new element of the specified type (tag name) before the element matching the specified "before" + * selector string for each selected element. + * + * This method returns a new selection containing the appended elements. + * Each new element inherits the data of the current elements, if any. + * + * The generic refers to the type of the child element to be appended. + * + * @param type A string representing the tag name for the element type to be inserted. The specified name may have a namespace prefix, + * such as svg:text to specify a text attribute in the SVG namespace. If no namespace is specified, the namespace will be inherited + * from the parent element; or, if the name is one of the known prefixes, the corresponding namespace will be used + * (for example, svg implies svg:svg) + * @param before A CSS selector string for the element before which the insertion should occur. + */ insert(type: string, before: string): Selection; + /** + * Inserts a new element of the type provided by the element creator function before the element matching the specified "before" + * selector string for each selected element. + * + * This method returns a new selection containing the appended elements. + * Each new element inherits the data of the current elements, if any. + * + * The generic refers to the type of the child element to be appended. + * + * @param type A creator 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. This function should return + * an element to be inserted. (The function typically creates a new element, but it may instead return an existing element.) + * @param before A CSS selector string for the element before which the insertion should occur. + */ insert(type: ValueFn, before: string): Selection; + /** + * Inserts a new element of the specified type (tag name) before the element returned by the "before" child selector function + * for each selected element. + * + * This method returns a new selection containing the appended elements. + * Each new element inherits the data of the current elements, if any. + * + * The generic refers to the type of the child element to be appended. + * + * @param type A string representing the tag name for the element type to be inserted. The specified name may have a namespace prefix, + * such as svg:text to specify a text attribute in the SVG namespace. If no namespace is specified, the namespace will be inherited + * from the parent element; or, if the name is one of the known prefixes, the corresponding namespace will be used + * (for example, svg implies svg:svg) + * @param before A child selector 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. This function should return the child element + * before which the element should be inserted. + */ insert(type: string, before: ValueFn): Selection; + /** + * Inserts a new element of the type provided by the element creator function before the element returned by the "before" child selector function + * for each selected element. + * + * This method returns a new selection containing the appended elements. + * Each new element inherits the data of the current elements, if any. + * + * The generic refers to the type of the child element to be appended. + * + * @param type A creator 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. This function should return + * an element to be inserted. (The function typically creates a new element, but it may instead return an existing element.) + * @param before A child selector 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. This function should return the child element + * before which the element should be inserted. + */ insert(type: ValueFn, before: ValueFn): Selection; /** @@ -175,70 +556,322 @@ interface Selection): Selection; + /** + * Filters the selection, returning a new selection that contains only the elements for + * which the specified filter is true. + * + * The returned filtered selection preserves the parents of this selection, but like array.filter, + * it does not preserve indexes as some elements may be removed; use selection.select to preserve the index, if needed. + * + * @param selector A CSS selector string to match when filtering. + */ filter(selector: string): this; + /** + * Filter the selection, returning a new selection that contains only the elements for + * which the specified filter is true. + * + * The returned filtered selection preserves the parents of this selection, but like array.filter, + * it does not preserve indexes as some elements may be removed; use selection.select to preserve the index, if needed. + * + * @param selector A 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. This function should return true + * for an element to be included, and false otherwise. + */ filter(selector: ValueFn): this; - + /** + * Return a new selection that contains a copy of each group in this selection sorted according + * to the compare function. After sorting, re-inserts elements to match the resulting order (per selection.order). + * + * Note that sorting is not guaranteed to be stable; however, it is guaranteed to have the same + * behavior as your browser’s built-in sort method on arrays. + * + * @param comparator An optional comparator function, which defaults to "ascending". The function is passed + * two elements’ data a and b to compare. It should return either a negative, positive, or zero value. + * If negative, then a should be before b; if positive, then a should be after b; otherwise, a and b are + * considered equal and the order is arbitrary. + */ sort(comparator?: (a: Datum, b: Datum) => number): this; + /** + * Re-insert elements into the document such that the document order of each group matches the selection order. + * This is equivalent to calling selection.sort if the data is already sorted, but much faster. + */ order(): this; + /** + * Re-insert each selected element, in order, as the last child of its parent. + */ raise(): this; + /** + * Re-insert each selected element, in order, as the first child of its parent. + */ lower(): this; // Data Join --------------------------------- + /** + * Returns the bound datum for the first (non-null) element in the selection. + * This is generally useful only if you know the selection contains exactly one element. + */ datum(): Datum; + /** + * Delete the bound data for each element in the selection. + */ datum(value: null): Selection; + /** + * Sets the element’s bound data using the specified value function on all selected elements. + * Unlike selection.data, this method does not compute a join and does not affect + * indexes or the enter and exit selections. + * + * The generic refers to the type of the new datum to be used for the selected elements. + * + * @param value A 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 is then used to set each element’s new data. + * A null value will delete the bound data. + */ datum(value: ValueFn): Selection; + /** + * Sets the element’s bound data to the specified value on all selected elements. + * Unlike selection.data, this method does not compute a join and does not affect + * indexes or the enter and exit selections. + * + * The generic refers to the type of the new datum to be used for the selected elements. + * + * @param value A value object to be used as the datum for each element. + */ datum(value: NewDatum): Selection; + /** + * Returns the array of data for the selected elements. + */ data(): Datum[]; + /** + * Joins the specified array of data with the selected elements, returning a new selection that it represents + * the update selection: the elements successfully bound to data. Also defines the enter and exit selections on + * the returned selection, which can be used to add or remove elements to correspond to the new data. + * + * The data is specified for each group in the selection. If the selection has multiple groups + * (such as d3.selectAll followed by selection.selectAll), then data should typically be specified as a function. + * + * If a key function is not specified, then the first datum in data is assigned to the first selected element, + * the second datum to the second selected element, and so on. + * A key function may be specified to control which datum is assigned to which element, replacing the default join-by-index. + * + * The update and enter selections are returned in data order, while the exit selection preserves the selection + * order prior to the join. If a key function is specified, the order of elements in the selection may not match + * their order in the document; use selection.order or selection.sort as needed. + * + * This method cannot be used to clear bound data; use selection.datum instead. + * + * For details see: {@link https://github.com/d3/d3-selection#joining-data } + * + * The generic refers to the type of the new datum to be used for the selected elements. + * + * @param data The specified data is an array of arbitrary values (e.g., numbers or objects). + * @param key An optional key 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 key function is then also evaluated for each new datum in data, being passed the current datum (d), + * the current index (i), and the group’s new data, with this as the group’s parent DOM element. + * The datum for a given key is assigned to the element with the matching key. If multiple elements have the same key, + * the duplicate elements are put into the exit selection; if multiple data have the same key, the duplicate data are put into the enter selection. + */ data(data: Array, key?: ValueFn): Selection; + /** + * Joins the data returned by the specified value function with the selected elements, returning a new selection that it represents + * the update selection: the elements successfully bound to data. Also defines the enter and exit selections on + * the returned selection, which can be used to add or remove elements to correspond to the new data. + * + * The data is specified for each group in the selection. + * + * If a key function is not specified, then the first datum in data is assigned to the first selected element, + * the second datum to the second selected element, and so on. + * A key function may be specified to control which datum is assigned to which element, replacing the default join-by-index. + * + * The update and enter selections are returned in data order, while the exit selection preserves the selection + * order prior to the join. If a key function is specified, the order of elements in the selection may not match + * their order in the document; use selection.order or selection.sort as needed. + * + * This method cannot be used to clear bound data; use selection.datum instead. + * + * For details see: {@link https://github.com/d3/d3-selection#joining-data } + * + * The generic refers to the type of the new datum to be used for the selected elements. + * + * @param data A value function which will be evaluated for each group in order, being passed the group’s parent datum + * (d, which may be undefined), the group index (i), and the selection’s parent nodes (nodes), + * with this as the group’s parent element. The function returns an array of values for each group. + * @param key An optional key 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 key function is then also evaluated for each new datum in data, being passed the current datum (d), + * the current index (i), and the group’s new data, with this as the group’s parent DOM element. + * The datum for a given key is assigned to the element with the matching key. If multiple elements have the same key, + * the duplicate elements are put into the exit selection; if multiple data have the same key, the duplicate data are put into the enter selection. + */ data(data: ValueFn>, key?: ValueFn): Selection; + /** + * Return the enter selection: placeholder nodes for each datum that had no corresponding DOM element + * in the selection. The enter selection is determined by selection.data, and is empty on a selection that + * is not joined to data. + */ enter(): Selection; - // The type Datum on the exit items is actually of the type prior to calling data(...), as by definition, no new data of type NewDatum exists for these - // elements. Due to the chaining, .data(...).exit(...), however, the definition would imply that the exit group elements have assumed the NewDatum type. - // This seems to imply the following workaroud: Recast the exit Selection to OldDatum, if needed, or ommit and allow exit group elements to be of type any. + /** + * Return the exit selection: existing DOM elements in the selection for which no new datum was found. + * The exit selection is determined by the previous selection.data, and is thus empty until the selection is + * joined to data. If the exit selection is retrieved more than once after a data join, subsequent calls return + * the empty selection. + * + * IMPORTANT: The generic refers to the type of the old datum associated with the exit selection elements. + * Ensure you set the generic to the correct type, if you need to access the data on the exit selection in + * follow-up steps, e.g. to set styles as part of an exit transition before removing them. + */ exit(): Selection; // Event Handling ------------------- - on(type: string): ValueFn; - on(type: string, listener: null): this; - on(type: string, listener: ValueFn, capture?: boolean): this; - + /** + * Return the currently-assigned listener for the specified event typename on the first (non-null) selected element, + * if any, If multiple typenames are specified, the first matching listener is returned. + * + * @param typenames The typenames is a string event type, such as click, mouseover, or submit; any DOM event type supported by your browser may be used. + * The type may be optionally followed by a period (.) and a name; the optional name allows multiple callbacks to be registered + * to receive events of the same type, such as click.foo and click.bar. To specify multiple typenames, separate typenames with spaces, + * such as "input change"" or "click.foo click.bar". + */ + on(typenames: string): ValueFn; + /** + * Remove a listener for the specified event type names. To remove all listeners for a given name, + * pass null as the listener and ".foo" as the typename, where foo is the name; to remove all listeners with no name, specify "." as the typename. + * + * @param typenames The typenames is a string event type, such as click, mouseover, or submit; any DOM event type supported by your browser may be used. + * The type may be optionally followed by a period (.) and a name; the optional name allows multiple callbacks to be registered + * to receive events of the same type, such as click.foo and click.bar. To specify multiple typenames, separate typenames with spaces, + * such as "input change"" or "click.foo click.bar". + * @param listener null to indicate removal of listener + */ + on(typenames: string, listener: null): this; + /** + * Add an event listener for the specified event type names. If an event listener was previously registered for the same typename + * on a selected element, the old listener is removed before the new listener is added. + * + * When a specified event is dispatched on a selected node, the specified listener will be evaluated for each selected element. + * + * An optional capture flag may be specified which corresponds to the W3C useCapture flag: + * “After initiating capture, all events of the specified type will be dispatched to the registered EventListener before being + * dispatched to any EventTargets beneath them in the tree. Events which are bubbling upward through the tree will not + * trigger an EventListener designated to use capture.” + * + * @param typenames The typenames is a string event type, such as click, mouseover, or submit; any DOM event type supported by your browser may be used. + * The type may be optionally followed by a period (.) and a name; the optional name allows multiple callbacks to be registered + * to receive events of the same type, such as click.foo and click.bar. To specify multiple typenames, separate typenames with spaces, + * such as "input change"" or "click.foo click.bar". + * @param listener A listener function which will be evaluated for each selected element, being passed the current datum (d), the current index (i), + * and the current group (nodes), with this as the current DOM element. Listeners always see the latest datum for their element, + * but the index is a property of the selection and is fixed when the listener is assigned; to update the index, re-assign the listener. + * To access the current event within a listener, use d3.event. + * @param capture An optional capture flag which corresponds to the W3C useCapture flag. + */ + on(typenames: string, listener: ValueFn, capture?: boolean): this; + /** + * Dispatches a custom event of the specified type to each selected element, in order. + * An optional parameters map may be specified to set additional properties of the event. + * + * @param type Name of event to dispatch + * @param parameters An optional value map with custom event parameters + */ dispatch(type: string, parameters?: CustomEventParameters): this; + /** + * Dispatches a custom event of the specified type to each selected element, in order. + * An optional value function returning a parameters map for each element in the selection may be specified to set additional properties of the event. + * + * @param type Name of event to dispatch + * @param parameters A 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. It must return the parameters map for the current element. + */ dispatch(type: string, parameters?: ValueFn): this; // Control Flow ---------------------- - each(valueFn: ValueFn): this; + /** + * Invoke the specified function for each selected element, passing in the current datum (d), + * the current index (i), and the current group (nodes), with this of the current DOM element. + * This method can be used to invoke arbitrary code for each selected element, and is useful for creating a context to access parent and child data simultaneously. + * + * @param func A function which is invoked for each selected element, being passed the current datum (d), the current index (i), and the current group (nodes), with this of the current DOM element. + */ + each(func: ValueFn): this; + /** + * Invoke the specified function exactly once, passing in this selection along with any optional arguments. + * Returns this selection. + * + * @param func A function which is passed this selection as the first argument along with any optional arguments. + * @param args List of optional arguments to be passed to the callback function. + */ call(func: (selection: Selection, ...args: any[]) => void, ...args: any[]): this; + /** + * Return true if this selection contains no (non-null) elements. + */ empty(): boolean; - node(): GElement; + /** + * Return the first (non-null) element in this selection. If the selection is empty, returns null. + */ + node(): GElement | null; + + /** + * Return an array of all (non-null) elements in this selection. + */ nodes(): Array; + /** + * Returns the total number of elements in this selection. + */ size(): number; } - +/** + * Selects the root element, document.documentElement. This function can also be used to test for selections + * (instanceof d3.selection) or to extend the selection prototype. + */ interface SelectionFn extends Function { (): Selection; } + +/** + * Selects the root element, document.documentElement. This function can also be used to test for selections + * (instanceof d3.selection) or to extend the selection prototype. + */ export var selection: SelectionFn; @@ -246,15 +879,50 @@ export var selection: SelectionFn; // on.js event and customEvent related // --------------------------------------------------------------------------- -// See issue #3 (https://github.com/tomwanzek/d3-v4-definitelytyped/issues/3) +/** + * A D3 Base Event + */ interface BaseEvent { + /** + * Event type + */ type: string; + /** + * The prior value of d3.event, allowing custom events to retain a reference to the originating native event. + */ sourceEvent?: any; // Could be of all sorts of types, too general: BaseEvent | Event | MouseEvent | TouchEvent | ... | OwnCustomEventType; } +/** + * The current event, if any. This is set during the invocation of an event listener, and is reset after the listener terminates. + * Use this to access standard event fields such as event.timeStamp and methods such as event.preventDefault. + * While you can use the native event.pageX and event.pageY, it is often more convenient to transform the event position to + * the local coordinate system of the container that received the event using d3.mouse, d3.touch or d3.touches. + * + * If you use Babel, Webpack, or another ES6-to-ES5 bundler, be aware that the value of d3.event changes during an event! + * An import of d3.event must be a live binding, so you may need to configure the bundler to import from D3’s ES6 modules + * rather than from the generated UMD bundle; not all bundlers observe jsnext:main. + * Also beware of conflicts with the window.event global. + */ export var event: any; // Could be of all sorts of types, too general: BaseEvent | Event | MouseEvent | TouchEvent | ... | OwnCustomEventType; - +/** + * Invokes the specified listener, using the specified "that" as "this" context and passing the specified arguments, if any. + * During the invocation, d3.event is set to the specified event; after the listener returns (or throws an error), + * d3.event is restored to its previous value. + * In addition, sets event.sourceEvent to the prior value of d3.event, allowing custom events to retain a reference to the originating native event. + * Returns the value returned by the listener. + * + * The first generic "Context" refers to the "this" context type in which the listener will be invoked. + * The second generic "Result" specifies the return type of the listener. + * + * @param event The event to which d3.event will be set during the listener invocation. + * @param listener The event listener function to be invoked. This function will be invoked with the "this" context, provided + * by the "that" argument of customEvent(...). It will be passed all optional arguments passed to customEvent(...). The function returns + * a value corresponding to the type of the second generic type. + * @param that The "this"" context which will be used for the invocation of listener. + * @param args A list of optional arguments, which will be passed to listener. + */ export function customEvent(event: BaseEvent, listener: (this: Context, ...args: any[]) => Result, that: Context, ...args: any[]): Result; // --------------------------------------------------------------------------- @@ -263,8 +931,10 @@ export function customEvent(event: BaseEvent, listener: (this: /** * Get (x, y)-coordinates of the current event relative to the specified container element. + * The container may be an HTML or SVG container element, such as a G element or an SVG element. * The coordinates are returned as a two-element array of numbers [x, y]. - * @param container + * + * @param container Container element relative to which coordinates are calculated. */ export function mouse(container: ContainerElement): [number, number]; @@ -272,9 +942,47 @@ export function mouse(container: ContainerElement): [number, number]; // touch.js and touches.js related // --------------------------------------------------------------------------- -export function touch(container: ContainerElement, identifier: number): [number, number]; -export function touch(container: ContainerElement, touches: TouchList, identifier: number): [number, number]; +/** + * Returns the x and y coordinates of the touch with the specified identifier associated + * with the current event relative to the specified container. + * The container may be an HTML or SVG container element, such as a G element or an SVG element. + * The coordinates are returned as a two-element array of numbers [x, y] or null if there is no touch with + * the specified identifier in touches, returns null; this can be useful for ignoring touchmove events + * where the only some touches have moved. + * + * If touches is not specified, it defaults to the current event’s changedTouches property. + * + * @param container Container element relative to which coordinates are calculated. + * @param identifier Touch Identifier associated with the current event. + */ +export function touch(container: ContainerElement, identifier: number): [number, number] | null; +/** + * Return the x and y coordinates of the touch with the specified identifier associated + * with the current event relative to the specified container. + * The container may be an HTML or SVG container element, such as a G element or an SVG element. + * The coordinates are returned as a two-element array of numbers [x, y] or null if there is no touch with + * the specified identifier in touches, returns null; this can be useful for ignoring touchmove events + * where the only some touches have moved. + * + * If touches is not specified, it defaults to the current event’s changedTouches property. + * + * @param container Container element relative to which coordinates are calculated. + * @param touches TouchList to be used when identifying the touch. + * @param identifier Touch Identifier associated with the current event. + */ +export function touch(container: ContainerElement, touches: TouchList, identifier: number): [number, number] | null; + +/** + * Return the x and y coordinates of the touches associated with the current event relative to the specified container. + * The container may be an HTML or SVG container element, such as a G element or an SVG element. + * The coordinates are returned as an array of two-element arrays of numbers [[x1, y1], [x2, y2], …]. + * + * If touches is not specified, it defaults to the current event’s touches property. + * + * @param container Container element relative to which coordinates are calculated. + * @param touches TouchList to be used. + */ export function touches(container: ContainerElement, touches?: TouchList): Array<[number, number]>; // --------------------------------------------------------------------------- @@ -285,16 +993,23 @@ export function touches(container: ContainerElement, touches?: TouchList): Array export interface Local { /** * Retrieves a local variable stored on the node (or one of its parents). + * + * @param node A node element. */ get(node: Element): T | undefined; /** * Deletes the value associated with the given node. Values stored on ancestors are not affected, meaning that child nodes will still see inherited values. * * This function returns true if there was a value stored directly on the node, and false otherwise. + * + * @param node A node element. */ remove(node: Element): boolean; /** * Store a value for this local variable. Calling `.get()` on children of this node will also retrieve the variable's value. + * + * @param node A node element. + * @param value Value to store locally */ set(node: Element, value: T): Element; /** @@ -306,6 +1021,8 @@ export interface Local { /** * Obtain a new local variable + * + * The generic refers to the type of the variable to store locally. */ export function local(): Local; @@ -358,6 +1075,12 @@ export var namespaces: NamespaceMap; // window.js related // --------------------------------------------------------------------------- +/** + * Returns the owner window for the specified node. If node is a node, returns the owner document’s default view; + * if node is a document, returns its default view; otherwise returns the node. + * + * @param DOMNode A DOM element + */ export function window(DOMNode: Window | Document | Element): Window; @@ -368,26 +1091,42 @@ export function window(DOMNode: Window | Document | Element): Window; /** - * Returns a closure structure which can be invoked in the 'this' context - * of a group element. Depending on the use of namespacing, the NewGElement can be HTMLElement, - * SVGElement an extension thereof or an element from a different namespace. + * Given the specified element name, returns a function which creates an element of the given name, + * assuming that "this" is the parent element. * - * @param elementName Name of the element to be added + * The generic refers to the type of the new element to be returned by the creator function. + * + * @param name Tag name of the element to be added. See "namespace" for details on supported namespace prefixes, + * such as for SVG elements. */ -export function creator(elementName: string): (this: BaseType) => NewGElement; +export function creator(name: string): (this: BaseType) => NewGElement; /** - * Returns a closure structure which can be invoked in the 'this' context - * of a group element. Returns true, if the element in the 'this' context matches the selector + * Given the specified selector, returns a function which returns true if "this" element matches the specified selector. * - * @param selector A valid selector string + * @param selector A CSS selector string. */ -export function matcher(selector: string): (this: BaseType) => boolean; +export function matcher(selector: string): (this: BaseType) => boolean; // ---------------------------------------------------------------------------- // selector.js and selectorAll.js related functions // ---------------------------------------------------------------------------- +/** + * Given the specified selector, returns a function which returns the first descendant of "this" element + * that matches the specified selector. + * + * The generic refers to the type of the returned descendant element. + * + * @param selector A CSS selector string. + */ export function selector(selector: string): (this: BaseType) => DescElement +/** + * Given the specified selector, returns a function which returns all descendants of "this" element that match the specified selector. + * + * The generic refers to the type of the returned descendant element. + * + * @param selector A CSS selector string. + */ export function selectorAll(selector: string): (this: BaseType) => NodeListOf; diff --git a/d3-transition/d3-transition-tests.ts b/d3-transition/d3-transition-tests.ts index dbfc221254..b1c4fff35c 100644 --- a/d3-transition/d3-transition-tests.ts +++ b/d3-transition/d3-transition-tests.ts @@ -16,7 +16,7 @@ import { import * as d3Transition from 'd3-transition'; import { - interpolateNumber, + interpolateString, interpolateRgb } from 'd3-interpolate'; @@ -243,7 +243,7 @@ select('body') enterTransition = enterTransition.attrTween('r', function (d, i, group) { console.log(this.r.baseVal.value); // this type is SVGCircleElement - return interpolateNumber(0, d.r); // datum type is CircleDatum + return interpolateString(0, d.r); // datum type is CircleDatum }); exitTransition = exitTransition.styleTween('fill', function (d, i, group) { @@ -375,10 +375,14 @@ topTransition = d3Transition.transition('top'); // test creation from existing transition -newEnterTransition = d3Transition.transition(enterTransition); -// newEnterTransition = d3Transition.transition(wrongElementTypeTransition);// fails, wrong group element type -// newEnterTransition = d3Transition.transition(wrongDatumTypeTransition);// fails, wrong datum type +topTransition = d3Transition.transition(enterTransition); +// tests with pre-existing datum (typed as string) +// set datum with a type of string +select('html').datum('test'); +let topTransition2: d3Transition.Transition; +topTransition2 = d3Transition.transition('top'); +topTransition2 = d3Transition.transition(enterTransition); // active(...) ---------------------------------------------------------- diff --git a/d3-transition/index.d.ts b/d3-transition/index.d.ts index ec169dcc49..d0b05b07ce 100644 --- a/d3-transition/index.d.ts +++ b/d3-transition/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for D3JS d3-transition module v1.0.1 +// Type definitions for D3JS d3-transition module v1.0.2 // Project: https://github.com/d3/d3-transition/ // Definitions by: Tom Wanzek , Alex Ford , Boris Yankov // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped @@ -10,92 +10,533 @@ import { ArrayLike, BaseType, Selection, ValueFn } from 'd3-selection'; */ declare module 'd3-selection' { export interface Selection { + /** + * Interrupts the active transition of the specified name on the selected elements, and cancels any pending transitions with the specified name, if any. + * If a name is not specified, null is used. + * + * IMPORTANT: Interrupting a transition on an element has no effect on any transitions on any descendant elements. + * For example, an axis transition consists of multiple independent, synchronized transitions on the descendants of the axis G element + * (the tick lines, the tick labels, the domain path, etc.). To interrupt the axis transition, you must therefore interrupt the descendants. + * + * @param name Name of the transition. + */ interrupt(name?: string): Transition; + /** + * Returns a new transition on the given selection with the specified name. If a name is not specified, null is used. + * The new transition is only exclusive with other transitions of the same name. + * + * @param name Name of the transition. + */ transition(name?: string): Transition; + /** + * Returns a new transition on the given selection. + * + * When using a transition instance, the returned transition has the same id and name as the specified transition. + * If a transition with the same id already exists on a selected element, the existing transition is returned for that element. + * Otherwise, the timing of the returned transition is inherited from the existing transition of the same id on the nearest ancestor of each selected element. + * Thus, this method can be used to synchronize a transition across multiple selections, + * or to re-select a transition for specific elements and modify its configuration. + * + * @param transition A transition instance. + */ transition(transition: Transition): Transition; } } - +/** + * Return the active transition on the specified node with the specified name, if any. + * If no name is specified, null is used. Returns null if there is no such active transition on the specified node. + * This method is useful for creating chained transitions. + * + * The first generic "GElement" refers to the type of element on which the returned active transition was defined. The second generic "Datum" refers to the type of the + * datum, of a selected element on which the transition is defined. The third generic refers to the type of the parent elements in the returned Transition. + * The fourth generic refers to the type of the datum defined on the parent elements in the returned Transition. + * + * @param node Element for which the active transition should be returned. + * @param name Name of the transition. + */ export function active(node: GElement, name?: string): Transition | null; +/** + * Interrupts the active transition of the specified name on the specified node, and cancels any pending transitions with the specified name, if any. + * If a name is not specified, null is used. + * + * @param node Element for which the transition should be interrupted. + * @param name Name of the transition to be interrupted. If a name is not specified, null is used. + */ export function interrupt(node: BaseType, name?: string): void; +/** + * A D3 Transition. + * + * The first generic "GElement" refers to the type of the selected element(s) in the Transition. + * The second generic "Datum" refers to the type of the datum of a selected element(s) in the Transition. + * The third generic "PElement" refers to the type of the parent element(s) in the D3 selection in the Transition. + * The fourth generic "PDatum" refers to the type of the datum of the parent element(s) in the Transition. + */ export interface Transition { // Sub-selection ------------------------- + /** + * For each selected element, select the first descendant element that matches the specified selector string, if any, + * and returns a transition on the resulting selection. The new transition has the same id, name and timing as this transition; + * however, if a transition with the same id already exists on a selected element, + * the existing transition is returned for that element. + * + * The generic represents the type of the descendant element to be selected. + * + * @param selector CSS selector string + */ select(selector: string): Transition; + /** + * For each selected element, select the descendant element returned by the selector function, if any, + * and returns a transition on the resulting selection. The new transition has the same id, name and timing as this transition; + * however, if a transition with the same id already exists on a selected element, + * the existing transition is returned for that element. + * + * The generic represents the type of the descendant element to be selected. + * + * @param selector A selector 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. + * It must return an element, or null if there is no matching element. + */ select(selector: ValueFn): Transition; - // NB: while the empty selections (null or undefined selector) are defined on the underlying object, they should not be exposed in the type definition API - // as they are meaningless on transitions.) - // selectAll(): Transition; // _groups are set to empty array, first generic type is set to undefined by convention - // selectAll(selector: null): Transition; // _groups are set to empty array, first generic type is set to undefined by convention + /** + * For each selected element, select all descendant elements that match the specified selector string, if any, + * and returns a transition on the resulting selection. The new transition has the same id, name and timing as this transition; + * however, if a transition with the same id already exists on a selected element, the existing transition is returned for that element. + * + * The first generic "DescElement" refers to the type of descendant element to be selected. The second generic "OldDatum" refers to the type of the + * datum, of a selected element. This is useful when re-selecting elements with a previously set, know datum type. + * + * @param selector CSS selector string + */ selectAll(selector: string): Transition; + /** + * For each selected element, select all descendant elements returned by the selector function, if any, + * and returns a transition on the resulting selection. The new transition has the same id, name and timing as this transition; + * however, if a transition with the same id already exists on a selected element, the existing transition is returned for that element. + * + * The first generic "DescElement" refers to the type of descendant element to be selected. The second generic "OldDatum" refers to the type of the + * datum, of a selected element. This is useful when re-selecting elements with a previously set, know datum type. + * + * @param selector A selector 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. It must return an array of elements + * (or a pseudo-array, such as a NodeList), or the empty array if there are no matching elements. + */ selectAll(selector: ValueFn | ArrayLike>): Transition; + /** + * Return the selection corresponding to this transition. + */ selection(): Selection; + + /** + * Returns a new transition on the same selected elements as this transition, scheduled to start when this transition ends. + * The new transition inherits a reference time equal to this transition’s time plus its delay and duration. + * The new transition also inherits this transition’s name, duration, and easing. + * This method can be used to schedule a sequence of chained transitions. + * + * A delay configured for the new transition will be relative to the previous transition. + */ transition(): Transition; // Modifying ------------------------------- + /** + * For each selected element, the attribute with the specified name will be cleared at the start of the transition. + * + * @param name Name of the attribute. + * @param value Use null to clear the attribute. + */ attr(name: string, value: null): this; + /** + * For each selected element, assigns the attribute tween for the attribute with the specified name to the specified target value. + * The starting value of the tween is the attribute’s value when the transition starts. + * The target value is the specified constant value for all elements. + * + * An interpolator is chosen based on the type of the target value, using the following algorithm: + * 1.) If value is a number, use interpolateNumber. + * 2.) If value is a color or a string coercible to a color, use interpolateRgb. + * 3.) Use interpolateString. + * + * To apply a different interpolator, use transition.attrTween. + * + * @param name Name of the attribute. + * @param value Target value for the attribute. + */ attr(name: string, value: string | number | boolean): this; - attr(name: string, value: ValueFn): this; - attrTween(name: string, tweenFn: ValueFn (string | number | boolean)>): this; + /** + * For each selected element, assigns the attribute tween for the attribute with the specified name to the specified target value. + * The starting value of the tween is the attribute’s value when the transition starts. + * The target value is return value of the value function evaluated for the selected element. + * + * An interpolator is chosen based on the type of the target value, using the following algorithm: + * 1.) If value is a number, use interpolateNumber. + * 2.) If value is a color or a string coercible to a color, use interpolateRgb. + * 3.) Use interpolateString. + * + * To apply a different interpolator, use transition.attrTween. + * + * @param name Name of the attribute. + * @param value A 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. + * A null value will clear the attribute at the start of the transition. + */ + attr(name: string, value: ValueFn): this; + /** + * Return the current interpolator factory for attribute with the specified name, or undefined if no such tween exists. + * + * @param name Name of attribute. + */ + attrTween(name: string): ValueFn string> | undefined; + /** + * Remove the previously-assigned attribute tween of the specified name, if any. + * + * @param name Name of attribute. + * @param factory Use null to remove previously-assigned attribute tween. + */ + attrTween(name: string, factory: null): this; + /** + * Assign the attribute tween for the attribute with the specified name to the specified interpolator factory. + * An interpolator factory is a function that returns an interpolator; when the transition starts, the factory is evaluated for each selected element. + * The returned interpolator will then be invoked for each frame of the transition, in order, + * being passed the eased time t, typically in the range [0, 1]. Lastly, the return value of the interpolator will be used to set the attribute value. + * The interpolator must return a string. + * + * @param name Name of attribute. + * @param factory An interpolator factory 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 interpolator factory returns a string interpolator, + * which takes as its argument eased time t, typically in the range [0, 1] and returns the interpolated string. + */ + attrTween(name: string, factory: ValueFn string>): this; + + /** + * For each selected element, the style with the specified name will be cleared at the start of the transition. + * + * @param name Name of the style. + * @param value Use null to clear the style. + */ style(name: string, value: null): this; + /** + * For each selected element, assigns the style tween for the style with the specified name to the specified target value. + * The starting value of the tween is the style’s value when the transition starts. + * The target value is the specified constant value for all elements. + * + * An interpolator is chosen based on the type of the target value, using the following algorithm: + * 1.) If value is a number, use interpolateNumber. + * 2.) If value is a color or a string coercible to a color, use interpolateRgb. + * 3.) Use interpolateString. + * + * To apply a different interpolator, use transition.attrTween. + * + * @param name Name of the style. + * @param value Target value for the style. + * @param priority An optional priority flag, either null or the string important (without the exclamation point) + */ style(name: string, value: string | number | boolean, priority?: null | 'important'): this; - style(name: string, value: ValueFn, priority?: null | 'important'): this; - styleTween(name: string, tweenFn: ValueFn (string | number | boolean)>, priority?: null | 'important'): this; + /** + * For each selected element, assigns the style tween for the style with the specified name to the specified target value. + * The starting value of the tween is the style's value when the transition starts. + * The target value is return value of the value function evaluated for the selected element. + * + * An interpolator is chosen based on the type of the target value, using the following algorithm: + * 1.) If value is a number, use interpolateNumber. + * 2.) If value is a color or a string coercible to a color, use interpolateRgb. + * 3.) Use interpolateString. + * + * To apply a different interpolator, use transition.attrTween. + * + * @param name Name of the style. + * @param value A 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. + * A null value will clear the style at the start of the transition. + * @param priority An optional priority flag, either null or the string important (without the exclamation point) + */ + style(name: string, value: ValueFn, priority?: null | 'important'): this; + /** + * Return the current interpolator factory for style with the specified name, or undefined if no such tween exists. + * + * @param name Name of style. + */ + styleTween(name: string): ValueFn string> | undefined; + /** + * Remove the previously-assigned style tween of the specified name, if any. + * + * @param name Name of style. + * @param factory Use null to remove previously-assigned style tween. + */ + styleTween(name: string, factory: null): this; + /** + * Assign the style tween for the style with the specified name to the specified interpolator factory. + * An interpolator factory is a function that returns an interpolator; when the transition starts, the factory is evaluated for each selected element. + * The returned interpolator will then be invoked for each frame of the transition, in order, + * being passed the eased time t, typically in the range [0, 1]. Lastly, the return value of the interpolator will be used to set the style value. + * The interpolator must return a string. + * + * @param name Name of style. + * @param factory An interpolator factory 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 interpolator factory returns a string interpolator, + * which takes as its argument eased time t, typically in the range [0, 1] and returns the interpolated string. + * @param priority An optional priority flag, either null or the string important (without the exclamation point) + */ + styleTween(name: string, factory: ValueFn string>, priority?: null | 'important'): this; + + /** + * For each selected element, the text content will be cleared, replacing any existing child elements. + * + * @param value Use null to clear the text content. + */ text(value: null): this; + /** + * For each selected element, sets the text content to the specified target value when the transition starts. + * To interpolate text rather than to set it on start, use transition.tween (for example) or + * append a replacement element and cross-fade opacity (for example). Text is not interpolated by default because it is usually undesirable. + * + * @param value Value used for text content + */ text(value: string | number | boolean): this; + /** + * For each selected element, sets the text content returned by the value function for each selected element when the transition starts. + * + * To interpolate text rather than to set it on start, use transition.tween (for example) or + * append a replacement element and cross-fade opacity (for example). Text is not interpolated by default because it is usually undesirable. + * + * @param value A 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. + * A null value will clear the text content at the start of the transition. + */ text(value: ValueFn): this; - tween(name: string): ValueFn void>; + /** + * Returns the tween with the specified name, or undefined, if no tween was previously assigned to + * that name. + * + * @param name Name of tween. + */ + tween(name: string): ValueFn void> | undefined; + /** + * Removes the tween with the specified name, if a tween was previously assigned to + * that name. + * + * @param name Name of tween. + * @param tweenFn Use null to remove a previously-assigned tween. + */ tween(name: string, tweenFn: null): this; + /** + * For each selected element, assigns the tween with the specified name with the specified value function. + * The value must be specified as a function that returns a function. + * When the transition starts, the value function is evaluated for each selected element. + * The returned function is then invoked for each frame of the transition, in order, + * being passed the eased time t, typically in the range [0, 1]. + * + * @param name Name of tween. + * @param tweenFn A tween 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 tween function returns a function + * which takes as its argument eased time t, typically in the range [0, 1] and performs the tweening activities for each transition frame. + */ tween(name: string, tweenFn: ValueFn void>): this; + /** + * For each selected element, removes the element when the transition ends, as long as the element has no other active or pending transitions. + * If the element has other active or pending transitions, does nothing. + */ remove(): this; + /** + * Returns a new transition merging this transition with the specified other transition, + * which must have the same id as this transition. The returned transition has the same number of groups, + * the same parents, the same name and the same id as this transition. + * Any missing (null) elements in this transition are filled with the corresponding element, if present (not null), from the other transition. + * + * @param other The transition to be merged. + */ merge(other: Transition): Transition; + /** + * For each selected element, selects only the elements that match the specified filter, and returns a transition on the resulting selection. + * + * The new transition has the same id, name and timing as this transition; however, if a transition with the same id already exists on a selected element, + * the existing transition is returned for that element. + * + * @param filter A CSS selector string. + */ filter(filter: string): this; + /** + * For each selected element, selects only the elements that match the specified filter, and returns a transition on the resulting selection. + * + * The new transition has the same id, name and timing as this transition; however, if a transition with the same id already exists on a selected element, + * the existing transition is returned for that element. + * + * @param filter 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 filter function returns a boolean indicating, + * whether the selected element matches. + */ filter(filter: ValueFn): this; // Event Handling ------------------- + /** + * Return the currently-assigned listener for the specified event typename on the first (non-null) selected element, if any. + * If multiple typenames are specified, the first matching listener is returned. + * + * @param typenames The typenames is one of the following string event types: start (when the transition starts), end (when the transition ends), + * interrupt (when the transition is interrupted.) Note that these are not native DOM events. The type may be optionally followed by a period (.) and a name; + * the optional name allows multiple callbacks to be registered to receive events of the same type, such as "start.foo"" and "start.bar". + * To specify multiple typenames, separate typenames with spaces, such as "interrupt end"" or "start.foo start.bar". + */ on(type: string): ValueFn; - on(type: string, listener: null): this; + /** + * Remove all listeners for a given name. + * + * @param typenames Name of the event type for which the listener should be removed. To remove all listeners for a given name use ".foo" + * as the typename, where foo is the name; to remove all listeners with no name, specify "." as the typename. + * @param listener Use null to remove listeners. + */ + on(typenames: string, listener: null): this; + /** + * Add a listener to each selected element for the specified event typenames. + * + * When a specified transition event is dispatched on a selected node, the specified listener will be invoked for each transitioning element. + * Listeners always see the latest datum for their element, but the index is a property of the selection and is fixed when the listener is assigned; + * to update the index, re-assign the listener. + * + * @param typenames The typenames is one of the following string event types: start (when the transition starts), end (when the transition ends), + * interrupt (when the transition is interrupted.) Note that these are not native DOM events. The type may be optionally followed by a period (.) and a name; + * the optional name allows multiple callbacks to be registered to receive events of the same type, such as "start.foo"" and "start.bar". + * To specify multiple typenames, separate typenames with spaces, such as "interrupt end"" or "start.foo start.bar". + * @param listener A listener function which will be evaluated for each selected element, being passed the current datum (d), the current index (i), + * and the current group (nodes), with this as the current DOM element. Listeners always see the latest datum for their element, + * but the index is a property of the selection and is fixed when the listener is assigned; to update the index, re-assign the listener. + */ on(type: string, listener: ValueFn): this; // Control Flow ---------------------- - each(valueFn: ValueFn): this; + /** + * Invoke the specified function for each selected element, passing the current datum (d), + * the current index (i), and the current group (nodes), with this of the current DOM element. + * This method can be used to invoke arbitrary code for each selected element, and is useful for creating a context to access parent and child data simultaneously. + * + * @param func A function which is invoked for each selected element, being passed the current datum (d), the current index (i), and the current group (nodes), with this of the current DOM element. + */ + each(func: ValueFn): this; + /** + * Invoke the specified function exactly once, passing in this transition along with any optional arguments. + * Returns this transition. + * + * @param func A function which is passed this transition as the first argument along with any optional arguments. + * @param args List of optional arguments to be passed to the callback function. + */ call(func: (transition: Transition, ...args: any[]) => any, ...args: any[]): this; + /** + * Return true if this transition contains no (non-null) elements. + */ empty(): boolean; - node(): GElement; + /** + * Return the first (non-null) element in this transition. If the transition is empty, returns null. + */ + node(): GElement | null; + + /** + * Return an array of all (non-null) elements in this transition. + */ nodes(): Array; + /** + * Returns the total number of elements in this transition. + */ size(): number; // Transition Configuration ---------------------- + /** + * Returns the current value of the delay for the first (non-null) element in the transition. + * This is generally useful only if you know that the transition contains exactly one element. + */ delay(): number; + /** + * For each selected element, sets the transition delay to the specified value in milliseconds. + * If a delay is not specified, it defaults to zero. + * + * @param milliseconds Number of milliseconds for the delay. + */ delay(milliseconds: number): this; + /** + * For each selected element, sets the transition delay to the value in milliseconds returned by the + * value function. + * + * @param milliseconds A value function which is evaluated for each selected element, being passed the current datum (d), + * the current index (i), and the current group (nodes), with this of the current DOM element. The return value is a number + * specifying the delay in milliseconds. + */ + delay(milliseconds: ValueFn): this; + /** + * Returns the current value of the duration for the first (non-null) element in the transition. + * This is generally useful only if you know that the transition contains exactly one element. + */ duration(): number; + /** + * For each selected element, sets the transition duration to the specified value in milliseconds. + * If a duration is not specified, it defaults to 250ms. + * + * @param duration Number of milliseconds for the duration. + */ duration(milliseconds: number): this; + /** + * For each selected element, sets the transition duration to the value in milliseconds returned by the + * value function. + * + * @param milliseconds A value function which is evaluated for each selected element, being passed the current datum (d), + * the current index (i), and the current group (nodes), with this of the current DOM element. The return value is a number + * specifying the duration in milliseconds. + */ + duration(milliseconds: ValueFn): this; + /** + * Returns the current easing function for the first (non-null) element in the transition. + * This is generally useful only if you know that the transition contains exactly one element. + */ ease(): (normalizedTime: number) => number; + /** + * Specifies the transition easing function for all selected elements. The value must be specified as a function. + * The easing function is invoked for each frame of the animation, being passed the normalized time t in the range [0, 1]; + * it must then return the eased time tʹ which is typically also in the range [0, 1]. + * A good easing function should return 0 if t = 0 and 1 if t = 1. If an easing function is not specified, + * it defaults to d3.easeCubic. + * + * @param easingFn An easing function which is passed the normalized time t in the range [0, 1]; + * it must then return the eased time tʹ which is typically also in the range [0, 1]. + * A good easing function should return 0 if t = 0 and 1 if t = 1. + */ ease(easingFn: (normalizedTime: number) => number): this; } +/** + * Returns a new transition with the specified name. If a name is not specified, null is used. + * The new transition is only exclusive with other transitions of the same name. + * + * The generic "OldDatum" refers to the type of a previously-set datum of the selected HTML element in the Transition. + * + * @param name Name of the transition. + */ +export function transition(name: string): Transition; -export function transition(name: string): Transition; -export function transition(transition: Transition): Transition; +/** + * Returns a new transition from an existing transition. + * + * When using a transition instance, the returned transition has the same id and name as the specified transition. + * + * The generic "OldDatum" refers to the type of a previously-set datum of the selected HTML element in the Transition. + * + * @param transition A transition instance. + */ +export function transition(transition: Transition): Transition;