[types-2.0] Add d3-hexbin (#12089)

* Add d3-hexbin

Add https://github.com/d3/d3-hexbin type definitions.

* Fix typo

* delete unnecessary comments

* Update after review

Use generics to control type-safety.

* Update tests

* Update fix argument name

d3-hexbin/d3-hexbin-test.ts

@@ -0,0 +1,211 @@
+/**
+ * Typescript definition tests for d3/d3-hexbin module
+ *
+ * Note: These tests are intended to test the definitions only
+ * in the sense of typing and call signature consistency. They
+ * are not intended as functional tests.
+ */
+
+import * as d3Hexbin from 'd3-hexbin';
+
+interface Point {
+    x0: number;
+    y0: number;
+}
+
+{
+    // d3.hexbin() has the expected defaults
+    const b = d3Hexbin.hexbin();
+    const extent = b.extent(); // [[0, 0], [1, 1]]
+    extent.map((x: any, y: any) => { });
+    b.x()([41, 42]); // === 41;
+    b.y()([41, 42]); // === 42;
+    b.radius();      // === 1;
+
+
+    // hexbin(points) bins the specified points into hexagonal bins
+    const bins = d3Hexbin.hexbin()([
+        [0, 0], [0, 1], [0, 2],
+        [1, 0], [1, 1], [1, 2],
+        [2, 0], [2, 1], [2, 2]
+    ])
+
+    bins.map((bin: any) => {})
+}
+
+{
+    // hexbin(points) observes the current x- and y-accessors
+    const x = function(d: any) { return d.x; },
+          y = function(d: any) { return d.y; },
+          bins = d3Hexbin.hexbin<Point>().x(x).y(y)([
+        {x0: 0, y0: 0}, {x0: 0, y0: 1}, {x0: 0, y0: 2},
+        {x0: 1, y0: 0}, {x0: 1, y0: 1}, {x0: 1, y0: 2},
+        {x0: 2, y0: 0}, {x0: 2, y0: 1}, {x0: 2, y0: 2}
+    ]);
+    bins.map((bin: any) => {});
+}
+
+{
+    // hexbin(points) observes the current radius
+    const bins = d3Hexbin.hexbin().radius(2)([
+      [0, 0], [0, 1], [0, 2],
+      [1, 0], [1, 1], [1, 2],
+      [2, 0], [2, 1], [2, 2]
+    ]);
+    bins.map((bin: any)=> {});
+}
+
+{
+    interface PointX {
+        x: number;
+        [key: number]: number;
+    }
+
+    // hexbin.x(x) sets the x-coordinate accessor
+    const x = function(d: PointX) { return d.x; },
+          b = d3Hexbin.hexbin<PointX>().x(x),
+          bins = b([{x: 1, 1: 2}]);
+
+    b.x();          // should be x;
+    bins.length;    // should be 1;
+    bins[0].x;      // should be 0.8660254037844386;
+    bins[0].y;      // should be 1.5;
+    bins[0].length  // should be 1;
+}
+
+{
+    interface PointY {
+        y: number;
+        [key: number]: number;
+    }
+    // hexbin.y(y) sets the y-coordinate accessor
+    const y = function(d: PointY) { return d.y; },
+          b = d3Hexbin.hexbin<PointY>().y(y),
+          bins = b([{0: 1, y: 2}]);
+
+    bins.length;    // should be 1;
+    bins[0].x;      // should be 0.8660254037844386;
+    bins[0].y;      // should be 1.5;
+    bins[0].length; // should be 1;
+}
+
+{
+    // hexbin.hexagon() returns the expected path
+    const path: string = d3Hexbin.hexbin().hexagon();
+}
+
+{
+    // hexbin.hexagon() observes the current bin radius
+    const path: string = d3Hexbin.hexbin().radius(2).hexagon();
+}
+
+{
+    // hexbin.hexagon(radius) observes the specified radius
+    const path: string = d3Hexbin.hexbin().hexagon(2);
+}
+
+{
+    // hexbin.hexagon(radius) uses the current bin radius if radius is null
+    let path: string = d3Hexbin.hexbin().hexagon(null);
+    path = d3Hexbin.hexbin().hexagon(undefined);
+}
+
+{
+    // hexbin.centers() returns an array of bin centers
+    const centers = d3Hexbin.hexbin().centers();
+    centers.map((x: any, y: any) => { });
+}
+
+{
+    // hexbin.centers() observes the current bin radius
+    const centers = d3Hexbin.hexbin().radius(0.5).centers();
+    centers.map((x: any, y: any) => { });
+}
+
+{
+    // hexbin.centers() observes the current extent
+    const centers = d3Hexbin.hexbin().radius(0.5)
+                            .extent([[-1.1, -1.1], [1.1, 1.1]])
+                            .centers();
+    centers.map((x, y) => { });
+}
+
+{
+    // hexbin.mesh() returns the expected path
+    const path: string = d3Hexbin.hexbin().mesh();
+}
+
+{
+    // hexbin.mesh() observes the bin radius
+    const path: string = d3Hexbin.hexbin().radius(0.5).mesh();
+}
+
+{
+    // hexbin.mesh() observes the extent
+    const path: string = d3Hexbin.hexbin().radius(0.5)
+                         .extent([[-1.1, -1.1], [1.1, 1.1]])
+                         .mesh();
+}
+
+{
+
+    let hb: d3Hexbin.Hexbin<Point>;
+    let bins: d3Hexbin.HexbinBin<Point>[];
+
+    // Create generator =======================================
+
+    hb = d3Hexbin.hexbin<Point>();
+
+    // Configure generator =====================================
+
+    // x Accessor ----------------------------------------------
+
+    let x: (d:Point) => number;
+    x = function (d: Point) { return d.x0; };
+
+    // test setter
+    hb = hb.x(x);
+
+    // test getter
+    x = hb.x();
+
+    // y Accessor ----------------------------------------------
+
+    let y: (d:Point) => number;
+    y = function (d: Point) { return d.y0; };
+
+    // test setter
+    hb = hb.y(y);
+
+    // test getter
+    y = hb.y();
+
+    // Use generator ============================================
+
+    bins = hb([
+        { x0: 0, y0: 0 }, { x0: 0, y0: 1 }, { x0: 0, y0: 2 },
+        { x0: 1, y0: 0 }, { x0: 1, y0: 1 }, { x0: 1, y0: 2 },
+        { x0: 2, y0: 0 }, { x0: 2, y0: 1 }, { x0: 2, y0: 2 }
+    ]);
+
+    interface RemappedBin {
+        binCoordinates: [number, number];
+        points: Point[];
+    }
+
+    let remappedBins: Array<RemappedBin>;
+
+    remappedBins = bins.map(bin => {
+        const x: number = bin.x; // x-coordinate of bin
+        const y: number = bin.y; // y-coordinate of bin
+        const pointsInBin: Point[] = bin.map(p => {
+            const point: Point = p;
+            return point;
+        });
+        const remapped: RemappedBin = {
+            binCoordinates: [x, y],
+            points: pointsInBin
+        };
+        return remapped;
+    });
+}

d3-hexbin/index.d.ts

@@ -0,0 +1,138 @@
+// Type definitions for D3JS d3-hexbin module v0.2.1
+// Project: https://github.com/d3/d3-hexbin/
+// Definitions by: UNCOVER TRUTH Inc. <https://github.com/uncovertruth/>, Tom Wanzek <https://github.com/tomwanzek>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
+
+export interface HexbinBin<T> extends Array<T> {
+    x: number;
+    y: number;
+}
+
+export interface Hexbin<T> {
+    /**
+     * Bins the specified array of points, returning an array of hexagonal bins.
+     * For each point in the specified points array, the x- and y-accessors are
+     * invoked to compute the x- and y-coordinates of the point, which is then
+     * used to determine which hexagonal bin to add the point.
+     * If either the x- or y-coordinate is NaN, the point is ignored and will
+     * not be in any of the returned bins.
+     */
+    (points: T[]): HexbinBin<T>[];
+
+    /**
+     * Returns the SVG path string for the hexagon centered at the origin ⟨0,0⟩.
+     * The path string is defined with relative coordinates such that you can
+     * easily translate the hexagon to the desired position.
+     * If radius is not specified, the hexbin’s current radius is used.
+     * If radius is specified, a hexagon with the specified radius is returned;
+     * this is useful for area-encoded bivariate hexbins.
+     *
+     * @param {number} radius Radius number
+     */
+    hexagon(radius?: number): string;
+
+    /**
+     * Returns an array of [x, y] points representing the centers of every
+     * hexagon in the extent.
+     */
+    centers(): Array<[number, number]>;
+
+    /**
+     * Returns an SVG path string representing the hexagonal mesh that covers
+     * the extent; the returned path is intended to be stroked.
+     * The mesh may extend slightly beyond the extent and may need to be clipped.
+     */
+    mesh(): string;
+
+    /**
+     * If x is specified, sets the x-coordinate accessor to the specified
+     * function and returns this hexbin generator.
+     *
+     * The x-coordinate accessor is used by hexbin to compute the x-coordinate
+     * of each point. The default value assumes each point is specified as
+     * a two-element array of numbers [x, y].
+     */
+    x(x: (d: T) => number): Hexbin<T>;
+
+    /**
+     * If x is not specified, returns the current x-coordinate accessor,
+     *
+     * which defaults to:
+     *
+     *   function x(d) {
+     *     return d[0];
+     *   }
+     *
+     * The x-coordinate accessor is used by hexbin to compute the x-coordinate
+     * of each point. The default value assumes each point is specified as
+     * a two-element array of numbers [x, y].
+     *
+     */
+    x(): (d: T) => number;
+
+    /**
+     * If y is specified, sets the y-coordinate accessor to the specified
+     * function and returns this hexbin generator.
+     *
+     * The y-coordinate accessor is used by hexbin to compute the y-coordinate
+     * of each point. The default value assumes each point is specified as
+     * a two-element array of numbers [x, y].
+     */
+    y(y: (d: T) => number): Hexbin<T>
+
+    /**
+     * If y is not specified, returns the current y-coordinate accessor,
+     *
+     * which defaults to:
+     *
+     *   function y(d) {
+     *     return d[1];
+     *   }
+     *
+     * The y-coordinate accessor is used by hexbin to compute the y-coordinate
+     * of each point. The default value assumes each point is specified as
+     * a two-element array of numbers [x, y].
+     */
+    y(): (d: T) => number;
+
+    /**
+     * If radius is specified, sets the radius of the hexagon to
+     * the specified number.
+     *
+     * The hexagons are pointy-topped (rather than flat-topped);
+     * the width of each hexagon is radius × 2 × sin(π / 3)
+     * and the height of each hexagon radius × 3 / 2.
+     */
+    radius(radius: number): Hexbin<T>;
+
+    /**
+     * If radius is not specified, returns the current radius,
+     * which defaults to 1.
+     *
+     * The hexagons are pointy-topped (rather than flat-topped);
+     * the width of each hexagon is radius × 2 × sin(π / 3)
+     * and the height of each hexagon radius × 3 / 2.
+     */
+    radius(): number;
+
+    /**
+     * If extent is specified, sets the hexbin generator’s extent to the
+     * specified bounds [[x0, y0], [x1, y1]] and returns the hexbin generator.
+     */
+    extent(extent: [[number, number], [number, number]]): Hexbin<T>;
+
+    /**
+     * If extent is not specified, returns the generator’s current
+     * extent [[x0, y0], [x1, y1]], where x0 and y0 are the lower bounds and
+     * x1 and y1 are the upper bounds.
+     *
+     * The extent defaults to [[0, 0], [1, 1]].
+     */
+    extent(): [[number, number], [number, number]];
+}
+
+/**
+ * Constructs a new default hexbin generator.
+ */
+export function hexbin(): Hexbin<[number, number]>;
+export function hexbin<T>(): Hexbin<T>;

d3-hexbin/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es6",
+    "noImplicitAny": true,
+    "strictNullChecks": false,
+    "baseUrl": "../",
+    "typeRoots": [
+      "../"
+    ],
+    "types": [],
+    "noEmit": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "files": [
+    "index.d.ts",
+    "d3-hexbin-test.ts"
+  ]
+}