@types/d3-shape
Version:
TypeScript definitions for d3-shape
930 lines (888 loc) • 133 kB
TypeScript
// Last module patch version validated against: 3.1.0
import { Path } from "d3-path";
declare global {
interface CanvasRenderingContext2D {} // eslint-disable-line @typescript-eslint/no-empty-interface
}
// -----------------------------------------------------------------------------------
// Shared Types and Interfaces
// -----------------------------------------------------------------------------------
/**
* @deprecated
* This interface is used to bridge the gap between two incompatible versions of TypeScript (see [#25944](https://github.com/Microsoft/TypeScript/pull/25944)).
* Use `CanvasPathMethods` instead with TS <= 3.0 and `CanvasPath` with TS >= 3.1.
*/
export interface CanvasPath_D3Shape {
arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void;
arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
bezierCurveTo(cp1x: number, cp1y: number, cp2x: number, cp2y: number, x: number, y: number): void;
closePath(): void;
ellipse(
x: number,
y: number,
radiusX: number,
radiusY: number,
rotation: number,
startAngle: number,
endAngle: number,
anticlockwise?: boolean,
): void;
lineTo(x: number, y: number): void;
moveTo(x: number, y: number): void;
quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
rect(x: number, y: number, w: number, h: number): void;
}
// -----------------------------------------------------------------------------------
// Arc Generator
// -----------------------------------------------------------------------------------
/**
* Interface corresponding to the minimum data type assumed by the accessor functions of the Arc generator.
*/
export interface DefaultArcObject {
/**
* Inner radius of arc.
*/
innerRadius: number;
/**
* Outer radius of arc.
*/
outerRadius: number;
/**
* Start angle of arc. The angle is specified in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
*/
startAngle: number;
/**
* End angle of arc. The angle is specified in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
*/
endAngle: number;
/**
* Optional. Pad angle of arc in radians.
*/
padAngle?: number | undefined;
}
/**
* The arc generator produces a circular or annular sector, as in a pie or donut chart.
*
* If the difference between the start and end angles (the angular span) is greater than τ, the arc generator will produce a complete circle or annulus.
* If it is less than τ, arcs may have rounded corners and angular padding. Arcs are always centered at ⟨0,0⟩; use a transform (see: SVG, Canvas) to move the arc to a different position.
*
* See also the pie generator, which computes the necessary angles to represent an array of data as a pie or donut chart; these angles can then be passed to an arc generator.
*
* The first generic corresponds to the type of the "this" context within which the arc generator and its accessor functions will be invoked.
*
* The second generic corresponds to the datum type for which the arc is to be generated.
*/
export interface Arc<This, Datum> {
/**
* Generates an arc for the given arguments.
*
* IMPORTANT: If the rendering context of the arc generator is null,
* then the arc is returned as a path data string.
*
* The "this" context within which this function is invoked, will be the context within which the accessor methods of the generator are invoked.
* All arguments passed into this function, will be passed to the accessor functions of the generator.
*
* @param d The datum for which the arc is to be generated.
*/
(this: This, d: Datum, ...args: any[]): string | null;
/**
* Generates an arc for the given arguments.
*
* IMPORTANT: If the arc generator has been configured with a rendering context,
* then the arc is rendered to this context as a sequence of path method calls and this function returns void.
*
* The "this" context within which this function is invoked, will be the context within which the accessor methods of the generator are invoked.
* All arguments passed into this function, will be passed to the accessor functions of the generator.
*
* @param d The datum for which the arc is to be generated.
*/
(this: This, d: Datum, ...args: any[]): void;
/**
* Computes the midpoint [x, y] of the center line of the arc that would be generated by the given arguments.
*
* To be consistent with the generated arc, the accessors must be deterministic, i.e., return the same value given the same arguments.
* The midpoint is defined as (startAngle + endAngle) / 2 and (innerRadius + outerRadius) / 2.
*
* Note that this is not the geometric center of the arc, which may be outside the arc;
* this method is merely a convenience for positioning labels.
*
* The method is invoked in the same "this" context as the generator was invoked in and
* receives the same arguments that are passed into the arc generator.
*
* @param d The datum for which the arc is to be generated.
*/
centroid(d: Datum, ...args: any[]): [number, number];
/**
* Returns the current inner radius accessor, which defaults to a function returning the innerRadius property
* of the first argument passed into it.
*/
innerRadius(): (this: This, d: Datum, ...args: any[]) => number;
/**
* Sets the inner radius to the specified number and returns this arc generator.
*
* Specifying the inner radius as a function is useful for constructing a stacked polar bar chart, often in conjunction with a sqrt scale.
* More commonly, a constant inner radius is used for a donut or pie chart. If the outer radius is smaller than the inner radius, the inner and outer radii are swapped.
* A negative value is treated as zero.
*
* @param radius Constant radius.
*/
innerRadius(radius: number): this;
/**
* Sets the inner radius to the specified function and returns this arc generator.
*
* Specifying the inner radius as a function is useful for constructing a stacked polar bar chart, often in conjunction with a sqrt scale.
* More commonly, a constant inner radius is used for a donut or pie chart. If the outer radius is smaller than the inner radius, the inner and outer radii are swapped.
* A negative value is treated as zero.
*
* @param radius An accessor function returning a number to be used as a radius. The accessor function is invoked in the same "this" context as the generator was invoked in and
* receives the same arguments that were passed into the arc generator.
*/
innerRadius(radius: (this: This, d: Datum, ...args: any[]) => number): this;
/**
* Returns the current outer radius accessor, which defaults to a function returning the outerRadius property
* of the first argument passed into it.
*/
outerRadius(): (this: This, d: Datum, ...args: any[]) => number;
/**
* Sets the outer radius to the specified number and returns this arc generator.
*
* Specifying the outer radius as a function is useful for constructing a coxcomb or polar bar chart,
* often in conjunction with a sqrt scale. More commonly, a constant outer radius is used for a pie or donut chart.
* If the outer radius is smaller than the inner radius, the inner and outer radii are swapped.
* A negative value is treated as zero.
*
* @param radius Constant radius.
*/
outerRadius(radius: number): this;
/**
* Sets the outer radius to the specified function and returns this arc generator.
*
* Specifying the outer radius as a function is useful for constructing a coxcomb or polar bar chart,
* often in conjunction with a sqrt scale. More commonly, a constant outer radius is used for a pie or donut chart.
* If the outer radius is smaller than the inner radius, the inner and outer radii are swapped.
* A negative value is treated as zero.
*
* @param radius An accessor function returning a number to be used as a radius. The accessor function is invoked in the same "this" context as the generator was invoked in and
* receives the same arguments that were passed into the arc generator.
*/
outerRadius(radius: (this: This, d: Datum, ...args: any[]) => number): this;
/**
* Returns the current corner radius accessor, which defaults to a function returning a constant value of zero.
*/
cornerRadius(): (this: This, d: Datum, ...args: any[]) => number;
/**
* Sets the corner radius to the specified number and returns this arc generator.
*
* If the corner radius is greater than zero, the corners of the arc are rounded using circles of the given radius.
* For a circular sector, the two outer corners are rounded; for an annular sector, all four corners are rounded.
*
* The corner radius may not be larger than (outerRadius - innerRadius) / 2.
* In addition, for arcs whose angular span is less than π, the corner radius may be reduced as two adjacent rounded corners intersect.
* This is occurs more often with the inner corners.
*
* @param radius Constant radius.
*/
cornerRadius(radius: number): this;
/**
* Sets the corner radius to the specified function and returns this arc generator.
*
* The corner radius may not be larger than (outerRadius - innerRadius) / 2.
* In addition, for arcs whose angular span is less than π, the corner radius may be reduced as two adjacent rounded corners intersect.
* This is occurs more often with the inner corners.
*
* @param radius An accessor function returning a number to be used as a radius. The accessor function is invoked in the same "this" context as the generator was invoked in and
* receives the same arguments that were passed into the arc generator.
*/
cornerRadius(radius: (this: This, d: Datum, ...args: any[]) => number): this;
/**
* Returns the current start angle accessor, which defaults to a function returning the startAngle property
* of the first argument passed into it.
*/
startAngle(): (this: This, d: Datum, ...args: any[]) => number;
/**
* Sets the start angle to the specified number and returns this arc generator.
*
* The angle is specified in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
* If |endAngle - startAngle| ≥ τ, a complete circle or annulus is generated rather than a sector.
*
* @param angle Constant angle in radians.
*/
startAngle(angle: number): this;
/**
* Sets the start angle to the specified function and returns this arc generator.
*
* The angle is specified in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
* If |endAngle - startAngle| ≥ τ, a complete circle or annulus is generated rather than a sector.
*
* @param angle An accessor function returning a number in radians to be used as an angle. The accessor function is invoked in the same "this" context as the generator was invoked in and
* receives the same arguments that were passed into the arc generator.
*/
startAngle(angle: (this: This, d: Datum, ...args: any[]) => number): this;
/**
* Returns the current end angle accessor, which defaults to a function returning the endAngle property
* of the first argument passed into it.
*/
endAngle(): (this: This, d: Datum, ...args: any[]) => number;
/**
* Sets the end angle to the specified number and returns this arc generator.
*
* The angle is specified in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
* If |endAngle - startAngle| ≥ τ, a complete circle or annulus is generated rather than a sector.
*
* @param angle Constant angle in radians.
*/
endAngle(angle: number): this;
/**
* Sets the end angle to the specified function and returns this arc generator.
*
* The angle is specified in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
* If |endAngle - startAngle| ≥ τ, a complete circle or annulus is generated rather than a sector.
*
* @param angle An accessor function returning a number in radians to be used as an angle. The accessor function is invoked in the same "this" context as the generator was invoked in and
* receives the same arguments that were passed into the arc generator.
*/
endAngle(angle: (this: This, d: Datum, ...args: any[]) => number): this;
/**
* Returns the current pad angle accessor, which defaults to a function returning the padAngle property
* of the first argument passed into it, or false if no data are passed in or the property is not defined.
*/
padAngle(): (this: This, d: Datum, ...args: any[]) => number | undefined;
/**
* Sets the pad angle to the specified number and returns this arc generator.
*
* The pad angle is converted to a fixed linear distance separating adjacent arcs, defined as padRadius * padAngle. This distance is subtracted equally from the start and end of the arc.
* If the arc forms a complete circle or annulus, as when |endAngle - startAngle| ≥ τ, the pad angle is ignored. If the inner radius or angular span is small relative to the pad angle,
* it may not be possible to maintain parallel edges between adjacent arcs. In this case, the inner edge of the arc may collapse to a point, similar to a circular sector.
* For this reason, padding is typically only applied to annular sectors (i.e., when innerRadius is positive).
*
* The recommended minimum inner radius when using padding is outerRadius * padAngle / sin(θ), where θ is the angular span of the smallest arc before padding.
* For example, if the outer radius is 200 pixels and the pad angle is 0.02 radians, a reasonable θ is 0.04 radians, and a reasonable inner radius is 100 pixels.
*
* Often, the pad angle is not set directly on the arc generator, but is instead computed by the pie generator so as to ensure that the area of padded arcs is proportional to their value;
* see pie.padAngle. See the pie padding animation for illustration.
* If you apply a constant pad angle to the arc generator directly, it tends to subtract disproportionately from smaller arcs, introducing distortion.
*
* @param angle Constant angle in radians.
*/
padAngle(angle: number | undefined): this;
/**
* Sets the pad angle to the specified function and returns this arc generator.
*
* The pad angle is converted to a fixed linear distance separating adjacent arcs, defined as padRadius * padAngle. This distance is subtracted equally from the start and end of the arc.
* If the arc forms a complete circle or annulus, as when |endAngle - startAngle| ≥ τ, the pad angle is ignored. If the inner radius or angular span is small relative to the pad angle,
* it may not be possible to maintain parallel edges between adjacent arcs. In this case, the inner edge of the arc may collapse to a point, similar to a circular sector.
* For this reason, padding is typically only applied to annular sectors (i.e., when innerRadius is positive).
*
* The recommended minimum inner radius when using padding is outerRadius * padAngle / sin(θ), where θ is the angular span of the smallest arc before padding.
* For example, if the outer radius is 200 pixels and the pad angle is 0.02 radians, a reasonable θ is 0.04 radians, and a reasonable inner radius is 100 pixels.
*
* Often, the pad angle is not set directly on the arc generator, but is instead computed by the pie generator so as to ensure that the area of padded arcs is proportional to their value;
* see pie.padAngle. See the pie padding animation for illustration.
* If you apply a constant pad angle to the arc generator directly, it tends to subtract disproportionately from smaller arcs, introducing distortion.
*
* @param angle An accessor function returning a number in radians to be used as an angle. The accessor function is invoked in the same "this" context as the generator was invoked in and
* receives the same arguments that were passed into the arc generator.
*/
padAngle(angle: (this: This, d: Datum, ...args: any[]) => number | undefined): this;
/**
* Returns the current pad radius accessor, which defaults to null, indicating that the pad radius should be automatically computed as sqrt(innerRadius * innerRadius + outerRadius * outerRadius).
*/
padRadius(): ((this: This, d: Datum, ...args: any[]) => number) | null;
/**
* Sets the pad radius to the specified function or number and returns this arc generator.
* The pad radius determines the fixed linear distance separating adjacent arcs, defined as padRadius * padAngle.
*/
padRadius(radius: null | number | ((this: This, d: Datum, ...args: any[]) => number)): this;
/**
* Returns the current rendering context, which defaults to null.
*/
context(): CanvasRenderingContext2D | null;
/**
* Sets the context and returns this arc generator.
* If context is not specified, returns the current context, which defaults to null.
*/
context(context: CanvasRenderingContext2D | null): this;
}
/**
* Constructs a new arc generator with the default settings.
*
* Ensure that the accessors used with the arc generator correspond to the arguments passed into them,
* or set them to constants as appropriate.
*/
export function arc(): Arc<any, DefaultArcObject>;
/**
* Constructs a new arc generator with the default settings.
*
* Ensure that the accessors used with the arc generator correspond to the arguments passed into them,
* or set them to constants as appropriate.
*
* The generic corresponds to the datum type representing a arc.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function arc<Datum>(): Arc<any, Datum>;
/**
* Constructs a new arc generator with the default settings.
*
* Ensure that the accessors used with the arc generator correspond to the arguments passed into them,
* or set them to constants as appropriate.
*
* The first generic corresponds to the type of the "this" context within which the arc generator and its accessor functions will be invoked.
*
* The second generic corresponds to the datum type representing a arc.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function arc<This, Datum>(): Arc<This, Datum>;
// -----------------------------------------------------------------------------------
// Pie Generator
// -----------------------------------------------------------------------------------
/**
* Element of the Arc Datums Array created by invoking the Pie generator.
*
* The generic refers to the data type of an element in the input array passed into the Pie generator.
*/
export interface PieArcDatum<T> {
/**
* The input datum; the corresponding element in the input data array of the Pie generator.
*/
data: T;
/**
* The numeric value of the arc.
*/
value: number;
/**
* The zero-based sorted index of the arc.
*/
index: number;
/**
* The start angle of the arc.
* If the pie generator was configured to be used for the arc generator,
* then the units are in radians with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
*/
startAngle: number;
/**
* The end angle of the arc.
* If the pie generator was configured to be used for the arc generator,
* then the units are in radians with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
*/
endAngle: number;
/**
* The pad angle of the arc. If the pie generator was configured to be used for the arc generator, than the units are in radians.
*/
padAngle: number;
}
/**
* The pie generator does not produce a shape directly, but instead computes the necessary angles to represent a tabular dataset as a pie or donut chart;
* these angles can then be passed to an arc generator.
*
* The first generic corresponds to the type of the "this" context within which the pie generator and its accessor functions will be invoked.
*
* The second generic refers to the data type of an element in the input array passed into the Pie generator.
*/
export interface Pie<This, Datum> {
/**
* Generates a pie for the given array of data, returning an array of objects representing each datum’s arc angles.
* Any additional arguments are arbitrary; they are simply propagated to the pie generator’s accessor functions along with the this object.
* The length of the returned array is the same as data, and each element i in the returned array corresponds to the element i in the input data.
*
* This representation is designed to work with the arc generator’s default startAngle, endAngle and padAngle accessors.
* The angular units are arbitrary, but if you plan to use the pie generator in conjunction with an arc generator,
* you should specify angles in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
*
* @param data Array of data elements.
*/
(this: This, data: Datum[], ...args: any[]): Array<PieArcDatum<Datum>>;
/**
* Returns the current value accessor, which defaults to a function returning the first argument passed into it.
* The default value accessor assumes that the input data are numbers, or that they are coercible to numbers using valueOf.
*/
value(): (d: Datum, i: number, data: Datum[]) => number;
/**
* Sets the value accessor to use the specified constant number and returns this pie generator.
*
* @param value Constant value to be used.
*/
value(value: number): this;
/**
* Sets the value accessor to use the specified function and returns this pie generator.
*
* When a pie is generated, the value accessor will be invoked for each element in the input data array.
* The default value accessor assumes that the input data are numbers, or that they are coercible to numbers using valueOf.
* If your data are not simply numbers, then you should specify an accessor that returns the corresponding numeric value for a given datum.
*
* @param value A value accessor function, which is invoked for each element in the input data array, being passed the element d, the index i, and the array data as three arguments.
* It returns a numeric value.
*/
value(value: (d: Datum, i: number, data: Datum[]) => number): this;
/**
* Returns the current data comparator, which defaults to null.
*/
sort(): ((a: Datum, b: Datum) => number) | null;
/**
* Sets the data comparator to the specified function and returns this pie generator.
*
* If both the data comparator and the value comparator are null, then arcs are positioned in the original input order.
* Otherwise, the data is sorted according to the data comparator, and the resulting order is used. Setting the data comparator implicitly sets the value comparator to null.
*
* Sorting does not affect the order of the generated arc array which is always in the same order as the input data array; it merely affects the computed angles of each arc.
* The first arc starts at the start angle and the last arc ends at the end angle.
*
* @param comparator A compare function takes two arguments a and b, each elements from the input data array.
* If the arc for a should be before the arc for b, then the comparator must return a number less than zero;
* if the arc for a should be after the arc for b, then the comparator must return a number greater than zero;
* returning zero means that the relative order of a and b is unspecified.
*/
sort(comparator: (a: Datum, b: Datum) => number): this;
/**
* Sets the data comparator to null and returns this pie generator.
*
* If both the data comparator and the value comparator are null, then arcs are positioned in the original input order.
*
* @param comparator null, to set the pie generator to use the original input order or use the sortValues comparator, if any.
*/
sort(comparator: null): this;
/**
* Returns the current value comparator, which defaults to descending value.
*/
sortValues(): ((a: number, b: number) => number) | null;
/**
* Sets the value comparator to the specified function and returns this pie generator.
*
* If both the data comparator and the value comparator are null, then arcs are positioned in the original input order.
* Otherwise, the data is sorted according to the data comparator, and the resulting order is used.
* Setting the value comparator implicitly sets the data comparator to null.
*
* The value comparator is similar to the data comparator, except the two arguments a and b are values derived from the input data array using the value accessor, not the data elements.
* If the arc for a should be before the arc for b, then the comparator must return a number less than zero;
* if the arc for a should be after the arc for b, then the comparator must return a number greater than zero;
* returning zero means that the relative order of a and b is unspecified.
*/
sortValues(comparator: ((a: number, b: number) => number) | null): this;
/**
* Returns the current start angle accessor, which defaults to a function returning a constant zero.
*/
startAngle(): (this: This, data: Datum[], ...args: any[]) => number;
/**
* Sets the overall start angle of the pie to the specified number and returns this pie generator.
*
* The default start angle is zero.
*
* The start angle here means the overall start angle of the pie, i.e., the start angle of the first arc.
* The start angle accessor is invoked once, being passed the same arguments and this context as the pie generator.
* The units of angle are arbitrary, but if you plan to use the pie generator in conjunction with an arc generator,
* you should specify an angle in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
*
* @param angle A constant angle.
*/
startAngle(angle: number): this;
/**
* Sets the overall start angle of the pie to the specified function and returns this pie generator.
*
* The default start angle is zero.
*
* The start angle here means the overall start angle of the pie, i.e., the start angle of the first arc.
* The start angle accessor is invoked once, being passed the same arguments and this context as the pie generator.
* The units of angle are arbitrary, but if you plan to use the pie generator in conjunction with an arc generator,
* you should specify an angle in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
*
* @param angle An angle accessor function, which is invoked once, being passed the same arguments and this context as the pie generator.
*/
startAngle(angle: (this: This, data: Datum[], ...args: any[]) => number): this;
/**
* Returns the current end angle accessor, which defaults to a function returning a constant 2*pi.
*/
endAngle(): (this: This, data: Datum[], ...args: any[]) => number;
/**
* Sets the overall end angle of the pie to the specified number and returns this pie generator.
*
* The default end angle is 2*pi.
*
* The end angle here means the overall end angle of the pie, i.e., the end angle of the last arc.
* The units of angle are arbitrary, but if you plan to use the pie generator in conjunction with an arc generator,
* you should specify an angle in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
*
* The value of the end angle is constrained to startAngle ± τ, such that |endAngle - startAngle| ≤ τ.
*
* @param angle A constant angle.
*/
endAngle(angle: number): this;
/**
* Sets the overall end angle of the pie to the specified function and returns this pie generator.
*
* The default end angle is 2*pi.
*
* The end angle here means the overall end angle of the pie, i.e., the end angle of the last arc.
* The end angle accessor is invoked once, being passed the same arguments and this context as the pie generator.
* The units of angle are arbitrary, but if you plan to use the pie generator in conjunction with an arc generator,
* you should specify an angle in radians, with 0 at -y (12 o’clock) and positive angles proceeding clockwise.
*
* The value of the end angle is constrained to startAngle ± τ, such that |endAngle - startAngle| ≤ τ.
*
* @param angle An angle accessor function, which is invoked once, being passed the same arguments and this context as the pie generator.
*/
endAngle(angle: (this: This, data: Datum[], ...args: any[]) => number): this;
/**
* Returns the current pad angle accessor, which defaults to a function returning a constant zero.
*/
padAngle(): (this: This, data: Datum[], ...args: any[]) => number;
/**
* Sets the pad angle to the specified number and returns this pie generator.
*
* The pad angle here means the angular separation between each adjacent arc.
* The total amount of padding reserved is the specified angle times the number of elements in the input data array, and at most |endAngle - startAngle|;
* the remaining space is then divided proportionally by value such that the relative area of each arc is preserved.
* The units of angle are arbitrary, but if you plan to use the pie generator in conjunction with an arc generator, you should specify an angle in radians.
*
* @param angle A constant angle.
*/
padAngle(angle: number): this;
/**
* Sets the pad angle to the specified function and returns this pie generator.
*
* The pad angle here means the angular separation between each adjacent arc.
* The total amount of padding reserved is the specified angle times the number of elements in the input data array, and at most |endAngle - startAngle|;
* the remaining space is then divided proportionally by value such that the relative area of each arc is preserved.
* The pad angle accessor is invoked once, being passed the same arguments and this context as the pie generator.
* The units of angle are arbitrary, but if you plan to use the pie generator in conjunction with an arc generator, you should specify an angle in radians.
*
* @param angle An angle accessor function, which is invoked once, being passed the same arguments and this context as the pie generator.
*/
padAngle(angle: (this: This, data: Datum[], ...args: any[]) => number): this;
}
/**
* Constructs a new pie generator with the default settings.
*
* Ensure that the accessors used with the pie generator correspond to the arguments passed into them,
* or set them to constants as appropriate.
*/
export function pie(): Pie<any, number | { valueOf(): number }>;
/**
* Constructs a new pie generator with the default settings.
*
* Ensure that the accessors used with the pie generator correspond to the arguments passed into them,
* or set them to constants as appropriate.
*
* The generic refers to the data type of an element in the input array passed into the Pie generator.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function pie<Datum>(): Pie<any, Datum>;
/**
* Constructs a new pie generator with the default settings.
*
* Ensure that the accessors used with the pie generator correspond to the arguments passed into them,
* or set them to constants as appropriate.
*
* The first generic corresponds to the type of the "this" context within which the pie generator and its accessor functions will be invoked.
*
* The second generic refers to the data type of an element in the input array passed into the Pie generator.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function pie<This, Datum>(): Pie<This, Datum>;
// -----------------------------------------------------------------------------------
// Line Generators
// -----------------------------------------------------------------------------------
/**
* The line generator produces a spline or polyline, as in a line chart.
* Lines also appear in many other visualization types, such as the links in hierarchical edge bundling.
*
* The generic refers to the data type of an element in the input array passed into the line generator.
*/
export interface Line<Datum> {
/**
* Generates a line for the given array of data. Depending on this line generator’s associated curve,
* the given input data may need to be sorted by x-value before being passed to the line generator.
*
* IMPORTANT: If the rendering context of the line generator is null,
* then the line is returned as a path data string.
*
* @param data Array of data elements.
*/
(data: Iterable<Datum> | Datum[]): string | null;
/**
* Generates a line for the given array of data. Depending on this line generator’s associated curve,
* the given input data may need to be sorted by x-value before being passed to the line generator.
*
* IMPORTANT: If the line generator has been configured with a rendering context,
* then the line is rendered to this context as a sequence of path method calls and this function returns void.
*
* @param data Array of data elements.
*/
(data: Iterable<Datum> | Datum[]): void;
/**
* Returns the current x-coordinate accessor function, which defaults to a function returning first element of a two-element array of numbers.
*/
x(): (d: Datum, index: number, data: Datum[]) => number;
/**
* Sets the x accessor to the specified number and returns this line generator.
*
* @param x A constant x-coordinate value.
*/
x(x: number): this;
/**
* Sets the x accessor to the specified function and returns this line generator.
*
* When a line is generated, the x accessor will be invoked for each defined element in the input data array.
*
* The default x accessor assumes that the input data are two-element arrays of numbers. If your data are in a different format, or if you wish to transform the data before rendering,
* then you should specify a custom accessor.
*
* @param x A coordinate accessor function which returns the x-coordinate value. The x accessor will be invoked for each defined element in the input data array,
* being passed the element d, the index i, and the array data as three arguments.
*/
x(x: (d: Datum, index: number, data: Datum[]) => number): this;
/**
* Returns the current y-coordinate accessor function, which defaults to a function returning second element of a two-element array of numbers.
*/
y(): (d: Datum, index: number, data: Datum[]) => number;
/**
* Sets the y accessor to the specified number and returns this line generator.
*
* @param y A constant y-coordinate value.
*/
y(y: number): this;
/**
* Sets the y accessor to the specified function and returns this line generator.
*
* When a line is generated, the y accessor will be invoked for each defined element in the input data array.
*
* The default y accessor assumes that the input data are two-element arrays of numbers. If your data are in a different format, or if you wish to transform the data before rendering,
* then you should specify a custom accessor.
*
* @param y A coordinate accessor function which returns the y-coordinate value. The y accessor will be invoked for each defined element in the input data array,
* being passed the element d, the index i, and the array data as three arguments.
*/
y(y: (d: Datum, index: number, data: Datum[]) => number): this;
/**
* Returns the current defined accessor, which defaults to a function returning a constant boolean value of true.
*/
defined(): (d: Datum, index: number, data: Datum[]) => boolean;
/**
* Sets the defined accessor to the specified boolean and returns this line generator.
*
* The default accessor for defined returns a constant boolean value of true, thus assumes that the input data is always defined.
*
* When a line is generated, the defined accessor will be invoked for each element in the input data array,
* being passed the element d, the index i, and the array data as three arguments.
* If the given element is defined (i.e., if the defined accessor returns a truthy value for this element),
* the x and y accessors will subsequently be evaluated and the point will be added to the current line segment.
* Otherwise, the element will be skipped, the current line segment will be ended, and a new line segment will be generated for the next defined point.
* As a result, the generated line may have several discrete segments.
*
* Note that if a line segment consists of only a single point, it may appear invisible unless rendered with rounded or square line caps.
* In addition, some curves such as curveCardinalOpen only render a visible segment if it contains multiple points.
*
* @param defined A boolean constant.
*/
defined(defined: boolean): this;
/**
* Sets the defined accessor to the specified function and returns this line generator.
*
* The default accessor for defined returns a constant boolean value of true, thus assumes that the input data is always defined.
*
* When a line is generated, the defined accessor will be invoked for each element in the input data array,
* being passed the element d, the index i, and the array data as three arguments.
* If the given element is defined (i.e., if the defined accessor returns a truthy value for this element),
* the x and y accessors will subsequently be evaluated and the point will be added to the current line segment.
* Otherwise, the element will be skipped, the current line segment will be ended, and a new line segment will be generated for the next defined point.
* As a result, the generated line may have several discrete segments.
*
* Note that if a line segment consists of only a single point, it may appear invisible unless rendered with rounded or square line caps.
* In addition, some curves such as curveCardinalOpen only render a visible segment if it contains multiple points.
*
* @param defined An accessor function which returns a boolean value. The accessor will be invoked for each defined element in the input data array,
* being passed the element d, the index i, and the array data as three arguments.
*/
defined(defined: (d: Datum, index: number, data: Datum[]) => boolean): this;
/**
* Returns the current curve factory, which defaults to curveLinear.
*/
curve(): CurveFactory | CurveFactoryLineOnly;
/**
* Returns the current curve factory, which defaults to curveLinear.
*
* The generic allows to cast the curve factory to a specific type, if known.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
curve<C extends CurveFactory | CurveFactoryLineOnly>(): C;
/**
* Sets the curve factory and returns this line generator.
*
* @param curve A valid curve factory.
*/
curve(curve: CurveFactory | CurveFactoryLineOnly): this;
/**
* Returns the current rendering context, which defaults to null.
*/
context(): CanvasRenderingContext2D | null;
/**
* Sets the context and returns this line generator.
*/
context(context: CanvasRenderingContext2D | null): this;
}
/**
* Constructs a new line generator with the default settings.
*
* If x or y are specified, sets the corresponding accessors to the specified function or number and returns this line generator.
*
* The generic refers to the data type of an element in the input array passed into the line generator.
*
* @param x Sets the x accessor
* @param y Sets the y accessor
*/
export function line<Datum = [number, number]>(
x?: number | ((d: Datum, index: number, data: Datum[]) => number),
y?: number | ((d: Datum, index: number, data: Datum[]) => number),
): Line<Datum>;
/**
* The radial line generator produces a spline or polyline, as in a line chart.
*
* A radial line generator is equivalent to the standard Cartesian line generator,
* except the x and y accessors are replaced with angle and radius accessors.
* Radial lines are always positioned relative to ⟨0,0⟩; use a transform (see: SVG, Canvas) to change the origin.
*
* The generic refers to the data type of an element in the input array passed into the line generator.
*/
export interface LineRadial<Datum> {
/**
* Generates a radial line for the given array of data. Depending on this radial line generator’s associated curve,
* the given input data may need to be sorted by x-value before being passed to the line generator.
*
* IMPORTANT: If the rendering context of the radial line generator is null,
* then the radial line is returned as a path data string.
*
* @param data Array of data elements.
*/
(data: Iterable<Datum> | Datum[]): string | null;
/**
* Generates a radial line for the given array of data. Depending on this radial line generator’s associated curve,
* the given input data may need to be sorted by x-value before being passed to the radial line generator.
*
* IMPORTANT: If the radial line generator has been configured with a rendering context,
* then the radial line is rendered to this context as a sequence of path method calls and this function returns void.
*
* @param data Array of data elements.
*/
(data: Iterable<Datum> | Datum[]): void;
/**
* Returns the current angle accessor function, which defaults to a function returning first element of a two-element array of numbers.
*/
angle(): (d: Datum, index: number, data: Datum[]) => number;
/**
* Sets the angle accessor to the specified number and returns this radial line generator.
*
* @param angle A constant angle value in radians, with 0 at -y (12 o’clock).
*/
angle(angle: number): this;
/**
* Sets the angle accessor to the specified function and returns this radial line generator.
*
* When a radial line is generated, the angle accessor will be invoked for each defined element in the input data array.
*
* The default angle accessor assumes that the input data are two-element arrays of numbers. If your data are in a different format, or if you wish to transform the data before rendering,
* then you should specify a custom accessor.
*
* @param angle An angle accessor function which returns the angle value in radians, with 0 at -y (12 o’clock). The angle accessor will be invoked for each defined element in the input data array,
* being passed the element d, the index i, and the array data as three arguments.
*/
angle(angle: (d: Datum, index: number, data: Datum[]) => number): this;
/**
* Returns the current radius accessor function, which defaults to a function returning second element of a two-element array of numbers.
*/
radius(): (d: Datum, index: number, data: Datum[]) => number;
/**
* Sets the radius accessor to the specified number and returns this radial line generator.
*
* @param radius A constant radius value.
*/
radius(radius: number): this;
/**
* Sets the radius accessor to the specified function and returns this radial line generator.
*
* When a radial line is generated, the radius accessor will be invoked for each defined element in the input data array.
*
* The default radius accessor assumes that the input data are two-element arrays of numbers. If your data are in a different format, or if you wish to transform the data before rendering,
* then you should specify a custom accessor.
*
* @param radius A radius accessor function which returns the radius value. The radius accessor will be invoked for each defined element in the input data array,
* being passed the element d, the index i, and the array data as three arguments.
*/
radius(radius: (d: Datum, index: number, data: Datum[]) => number): this;
/**
* Returns the current defined accessor, which defaults to a function returning a constant boolean value of true.
*/
defined(): (d: Datum, index: number, data: Datum[]) => boolean;
/**
* Sets the defined accessor to the specified boolean and returns this radial line generator.
*
* The default accessor for defined returns a constant boolean value of true, thus assumes that the input data is always defined.
*
* When a radial line is generated, the defined accessor will be invoked for each element in the input data array,
* being passed the element d, the index i, and the array data as three arguments.
* If the given element is defined (i.e., if the defined accessor returns a truthy value for this element),
* the angle and radius accessors will subsequently be evaluated and the point will be added to the current radial line segment.
* Otherwise, the element will be skipped, the current radial line segment will be ended, and a new radial line segment will be generated for the next defined point.
* As a result, the generated radial line may have several discrete segments.
*
* Note that if a radial line segment consists of only a single point, it may appear invisible unless rendered with rounded or square line caps.
* In addition, some curves such as curveCardinalOpen only render a visible segment if it contains multiple points.
*
* @param defined A boolean constant.
*/
defined(defined: boolean): this;
/**
* Sets the defined accessor to the specified function and returns this radial line generator.
*
* The default accessor for defined returns a constant boolean value of true, thus assumes that the input data is always defined.
*
* When a radial line is generated, the defined accessor will be invoked for each element in the input data array,
* being passed the element d, the index i, and the array data as three arguments.
* If the given element is defined (i.e., if the defined accessor returns a truthy value for this element),
* the angle and radius accessors will subsequently be evaluated and the point will be added to the current radial line segment.
* Otherwise, the element will be skipped, the current radial line segment will be ended, and a new radial line segment will be generated for the next defined point.
* As a result, the generated radial line may have several discrete segments.
*
* Note that if a radial line segment consists of only a single point, it may appear invisible unless rendered with rounded or square line caps.
* In addition, some curves such as curveCardinalOpen only render a visible segment if it contains multiple points.
*
* @param defined An accessor function which returns a boolean value. The accessor will be invoked for each defined element in the input data array,
* being passed the element d, the index i, and the array data as three arguments.
*/
defined(defined: (d: Datum, index: number, data: Datum[]) => boolean): this;
/**
* Returns the current curve factory, which defaults to curveLinear.
*/
curve(): CurveFactory | CurveFactoryLineOnly;
/**
* Returns the current curve factory, which defaults to curveLinear.
*
* The generic allows to cast the curve factory to a specific type, if known.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
curve<C extends CurveFactory | CurveFactoryLineOnly>(): C;
/**
* Sets the curve factory and returns this radial line generator.
*
* Note that curveMonotoneX or curveMonotoneY are not recommended for radial lines because they assume that the data is monotonic in x or y,
* which is typically untrue of radial lines.
*
* @param curve A valid curve factory.
*/
curve(curve: CurveFactory | CurveFactoryLineOnly): this;
/**
* Returns the current rendering context, which defaults to null.
*/
context(): CanvasRenderingContext2D | null;
/**
* Equivalent to line.context.
*/
context(context: CanvasRenderingContext2D | null): this;
}
/**
* Constructs a new radial line generator with the default settings.
*
* Ensure that the accessors used with the radial line generator correspond to the arguments passed into them,
* or set them to constants as appropriate.
*/
export function lineRadial(): LineRadial<[number, number]>;
/**
* Constructs a new radial line generator with the default settings.
*
* Ensure that the acc