D3 Version 4 Typescript Definition Files

UPDATE (09/24/2016)

MIGRATION COMPLETE

It is with a great sense of pleasure that I announce the completed migration of the D3 version 4 definitions in this repo to a production setting.

On a go forward basis the definitions will be maintained on DefinitelyTyped (DT). The definitions utilize TypeScript 2 features and are currenly contained in the types-2.0 branch.

As DefinitelyTyped/types-2.0 feeds the npm @types organization, acquiring the definitions for a project is as easy as:

npm install @types/d3-selection --save

All individual D3 modules comprising the D3 Standard Bundle as published on d3/d3 have completed definition files. There are some additional D3 module definitions for what was called "optional scope modules" in this repo.

Important: Please refer to issue Parallel Version Structure to Support D3 v4 Standard Bundle Definition and D3 v3. As a result of this issue, the published definitions under d3 still refer to the legacy version 3.5.17.

The definitions on npm @types have version numbers following a variation of semver: major.minor.patch, where major and minor correspond to the major and minor version of the corresponding D3 module. The "patch" version number corresponds to updates of the definitions file itself.

To request enhancements, open issues or PRs with changes, please, use DefinitelyTyped Issues from now on. Kindly ensure you @ mention the author(s) listed in the header of the definitions file for their awareness, when submitting issues/PRs.

As part of the transition to DT, any open issues in this repo have been migrated to DT as well. These issues have been cross-referenced to the main Defintions Request Issue 9936, which tracked the migration to DT/@types.

Thanks

Thanks go to Alex Ford, Hugues Stefanski, and Yuri Feldman for their contributions to this repo. Their hard work will forever live on in the now published definitions...subject to git version control. :tada:

Thanks as well to everyone, who participated in discussions/issues resolution.

And last but not least, thanks to Ryan Cavanaugh, Andy and Mohamed Hegazy for making TypeScript and @types possible, and of course Mike Bostock for D3. :+1: :+1: :+1:

The following sections are kept for historic reference only

Summary

This repo is intended as a staging area for typescript definitions supporting the latest major release of D3js (i.e. version 4.x) by Mike Bostock.

The definitions are written on a per module basis in reference to the now separated D3 modules. Definitions in the master branch are written on the basis of TypeScript 2.x. In particular, they make use of a new feature which allows the typing of the this context of functions. This ability is particulary beneficial for D3, as D3 frequently binds the this context of functions to the DOM Element being manipulated. The definition files are written as external modules/UMD modules.

The scope of this project covers the modules which are part of the standard D3 bundle as defined by Mike Bostock. On a best efforts basis, consideration may be given to a small number of D3 modules which are not part of the standard bundle, but are maintained by Mike Bostock.

Starting with Release Candidate 2.0.0-rc.2 work on the D3 standard bundle modules is considered functionally complete. For a module-by-module status see section Module-Level Status below.

The migration of completed definitions and their supporting shape tests to DefinitelyTyped has progressed well for the majority of the modules. This means that modules which have been successfully migrated, now have a supporting definition in the npm @types organization. These definitions can be used in conjunction with e.g. npm install @types/d3-selection --save. For the remaining modules and the definition for the D3 standard bundle itself, migration is still in progress. See the section Roadmap below for a further discussion.

For added clarity, this repo is not intended as a permanent source for definition files to be used in the regular course of working with D3 in TypeScript. As a result, this repo currently does not contain instructions for definitions acquisition using typings, or tsd (legacy). The plan is to retire this repo after successful migration to DefinitelyTyped and keep it only for historic reference.

Content

• Roadmap
• Module-Level Status
• Contributing
• Related Contributions

Roadmap

This section provides a high-level view of the road ahead to completed definitons for D3 4.x, which can be accessed by developers using standard definition acquisition methods:

• Completion of Module Definitions
• Migration to DefinitelyTyped
• TypeScript 1.8.x Compatible Definitions

Completion of Module Definitions

The modules comprising the D3 Standard Bundle now have a complete working TypeScript 2 definition with accompanying tests.

A TypeScript related issue is open and tracked which pertains to the generation of a d3 global for plain-vanilla script use of individual D3 modules.

Adding complete JSDoc comments is a pending task for most modules. Given the effort involved in keeping this repo and DefinitelyTyped in sync during the migration process, completing this task might be better solved after a successfully completed migration.

(a) Open Modules (Optional Scope)

The Module-Level Status section provides a quick glance at the modules, which do not yet have a complete initial definition with tests. Currently, this affects only a limited number of optional scope modules, which do not form part of the D3 standard bundle.

For each of these modules there is one open issue for the definition and one for the related tests. Should you wish to contribute by writing a definition that is flagged as not yet started, please check the related issue for a current status. The issue is also mapped to a milestone to give a sense of prioritization.

Beyond that, please refer to the Contributing section.

(b) Open Issues

The issues in this repo, broadly fall into three categories:

1. Overarching issues related to how TypeScript definitions are written and/or deployed for easy use/maintenance by developers,
2. Module-specific 'functional' issues, and
3. Project management issues (progress tracking etc).

Please review and contribute to these open issues as you see fit.

Important: As described in the next sub-sections, this repo is in the process of being migrated to DefinitelyTyped. If an open module-specific issue for an otherwise complete module is critical/severe, I may hold off on migrating the affected module. Otherwise, preference will be given to migrating the module and carrying the related open issue over to DefinitelyTyped.

Migration to DefinitelyTyped

The process of moving essentially complete TypeScript 2 definitions and tests over to DefinitelyTyped/types-2.0 branch has, in general, progressed well.

A key rationale for using DefinitelyTyped going forward is that, it serves as the primary feeder source for the @types organization. Depending on the migration status of the individual module definitions, this means the resulting definitions are easily deployable using, e.g:

npm install @types/d3-selection --save

The main DefinitelyTyped issue thread for the migration-related questions is Request for d3.js API update from v3 to v4.1.0. This thread contains a more in depth, live disscussion of the mechanics related to the migration.

The section Module-Level Status gives a quick migration status indication by module. A slightly more granular breakout can be found here for D3 standard bundle modules and here for the optional scope modules.

TypeScript 1.8.x Compatible Definitions

Under the milestone Standard Bundle Modules (TypeScript 1.8.x) consideration is given to the preparation of definitions/tests which do not require the latest features of TypeScript 2.

The intent is to strip the unsupported features (e.g. this typing of function contexts) out, with the aim of keeping the definitions structurally as comparable as possible. A suitable wrapping of the module definitions may be required.

IMPORTANT: Activities related to this milestone are currently on hold, until the remaining migration related questions have been sufficiently resolved.

See specifically this issue comment for DefinitelyTyped related questions.

Module-Level Status

• D3 Standard Bundle Modules
• Optional Scope Modules

First of:

• As long as a D3 module does not have a definition and test file flagged as complete, the definition is available for review and comment, but not considered stable. Self-evidently, changes may also result from changes to D3 itself.

• Starting with the D3 version 4 release, D3 provides substantial flexibility with regard to (un)bundling as well as the choice between vanilla and module import use. The definitions in this repo are written as external modules/UMD module definitions. Ambient declarations are only used, when required for module augmentation (e.g. d3-transition extending the Selection interface of d3-selection).

• The availability of the d3 global for vanilla use, is somewhat related to the potential use of export as namespace d3 in UMD module definitions. The D3 standard bundle definitions file contained in this repo re-exports the modules listed in the next section. It also exposes a d3 global which can be used, where the module is not imported, but definitions are included by reference. The global is exposed using export as namespace d3.

• The individual D3 modules, currently do not merge into the d3 global when used as unbundled vanilla scripts. This is a known issue with a duplicate identifier compile error created by using export as namespace d3 at the constituent module level.

• The definition and test files in this repo are currently using relative paths. This was done as an interim step to focus on the D3-related aspects of this effort.

Important: All references to "Test File" below should be read as follows. The typescript files should compile without errors to indicate the internal consistency of the typescript definitions. I.e. they are only shape tests as is the DefinitelyTyped tradition. They are expressly not meant to be used with a test runner as functional tests.

D3 Standard Bundle Modules

D3 Standard Bundle Definition

Migration on hold. Check here for detailed status.

This is a definitions file for the bundle which re-exports the constituent modules and exposes a d3 global for vanilla script use.

• [x] Definition File
• [ ] Test File

(individual modules in alphabetical order)

d3-array

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-axis

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-brush

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-chord

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

Note: Utilizes this-typing (criticality: medium)

this-typing is used accessor functions in RibbonGenerator. The this context depends on the context bound when invoking the RibbonGenerator with data. I.e. it can be global object, undefined, a custom object or anything explicitly bound using .call(...) et al. The latter is the case e.g. when using RibbonGenerator to create the path string in conjunction with a Selection or Transition for SVGPathElements' attr(...) callbacks.

d3-collection

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-color

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-dispatch

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

Note: Utilizes this-typing (criticality: medium)

d3-drag

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

Note: Utilizes this-typing (criticality: high)

this-typing is used for context-binding to DOM element.

d3-dsv

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-ease

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-force

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

Note: Utilizes this-typing (criticality: medium)

this-typing is used for context-binding of event handler to Simulation (using Simulation.on(...)).

d3-format

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-geo

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-hierarchy

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-interpolate

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-path

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-polygon

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-quadtree

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-queue

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-random

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-request

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-scale

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-selection

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

Note: Utilizes this-typing (criticality: high)

this-typing is used for context-binding to DOM element.

d3-shape

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

Note: Utilizes this-typing (criticality: medium)

this-typing is used for accessor functions in Arc, Pie, Symbol, Stack. The this context depends on the context bound when invoking the respective generator with data. I.e. it can be global object, undefined, a custom object or anything explicitly bound using .call(...) et al. The latter is the case e.g. when using symbol or arc to create the path string in conjunction with a Selection or Transition for SVGPathElements' attr(...) callbacks.

d3-time

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-time-format

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-timer

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-transition

Available through @types. Check here for detailed status.

• [x] Definition File
• [x] Test File

Note: Utilizes this-typing (criticality: high)

this-typing is used for context-binding to DOM element.

d3-voronoi

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-zoom

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

Note: Utilizes this-typing (criticality: high)

this-typing is used for context-binding to DOM element.

Optional Scope Modules

(in alphabetical order)

d3-geo-projection

• [ ] Definition File
• [ ] Test File

d3-hexbin

• [ ] Definition File
• [ ] Test File

d3-hsv

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-sankey

• [ ] Definition File
• [ ] Test File

d3-scale-chromatic

Migration in progress. Click here for details.

• [x] Definition File
• [x] Test File

d3-selection-multi

Available through @types. Migration complete.

• [x] Definition File
• [x] Test File

d3-tile

• [ ] Definition File
• [ ] Test File

Contributing

You can contribute to this repository in several ways:

• help to identify or resolve specific issues with the existing definitions,
• review the definitions and point out areas of improvement, or
• provide pull requests for as yet missing definitions.

For details of how to contribute, please see here.

Important: Contributing to this repo, means your contribution is intended to be merged into DefinitelyTyped. Once a module indicates completed migration from here to DefinitelyTyped, all new issues should be opened on DefinitelyTyped. Any related outstanding issues will be migrated over to DefinitelyTyped alond-side the module.

Related Contributions

This repo benefits from the original work on D3js 3.x typings on DefinitelyTyped for the file d3.d.ts and its tests d3-test.ts. By implication the debt is to all its contributors with primary listed responsibility of Alex Ford and Boris Yankov.