40 |
41 |
42 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | The MIT License (MIT)
2 | Copyright (c) 2016 GlobalWebIndex Ltd
3 |
4 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
5 |
6 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
7 |
8 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
9 |
--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "d3scription",
3 | "version": "1.1.0",
4 | "description": "D3.js tooltip plugin made simple. With single-page apps in mind. ",
5 | "main": "index.js",
6 | "scripts": {
7 | "test": "echo \"Error: no test specified\" && exit 1",
8 | "prepublish": "npm run compile",
9 | "watch": "node_modules/webpack/bin/webpack.js --watch",
10 | "compile": "node_modules/typescript/bin/tsc index.ts -m commonjs -d && node_modules/webpack/bin/webpack.js"
11 | },
12 | "repository": {
13 | "type": "git",
14 | "url": "git+https://github.com/GlobalWebIndex/d3scription.git"
15 | },
16 | "keywords": [
17 | "d3",
18 | "tip",
19 | "tooltip",
20 | "description"
21 | ],
22 | "author": "GlobalWebIndex / Marek Fajkus",
23 | "license": "MIT",
24 | "bugs": {
25 | "url": "https://github.com/GlobalWebIndex/d3scription/issues"
26 | },
27 | "homepage": "https://github.com/GlobalWebIndex/d3scription#readme",
28 | "devDependencies": {
29 | "ts-loader": "^0.8.2",
30 | "typescript": "^2.1.0-dev.20160804",
31 | "webpack": "^1.13.1"
32 | },
33 | "dependencies": {
34 | "d3": "^4.2.1"
35 | },
36 | "publishConfig": {
37 | "registry":"https://npm.pkg.github.com"
38 | }
39 | }
40 |
--------------------------------------------------------------------------------
/index.js:
--------------------------------------------------------------------------------
1 | "use strict";
2 | ///
3 | exports.__esModule = true;
4 | var windowDimensions = {
5 | width: window.innerWidth,
6 | height: window.innerHeight
7 | };
8 | function setWindowDimmensions() {
9 | windowDimensions = {
10 | width: window.innerWidth,
11 | height: window.innerHeight
12 | };
13 | }
14 | var windowResize = window.addEventListener('resize', setWindowDimmensions);
15 | function getOffset(event, bounds, offset) {
16 | var collideVertically = (windowDimensions.height + window.scrollY) - event.pageY - offset.top - bounds.height < 0;
17 | var collideHorizontally = (windowDimensions.width + window.scrollX) - event.pageX - offset.left - bounds.width < 0;
18 | return {
19 | top: collideVertically ? event.pageY - bounds.height - offset.top : offset.top + event.pageY,
20 | left: collideHorizontally ? event.pageX - bounds.width - offset.left : event.pageX + offset.left
21 | };
22 | }
23 | var defaultOffset = { top: 10, left: 10 };
24 | function getOffsetSettings(offset) {
25 | if (!offset)
26 | return defaultOffset;
27 | return {
28 | top: offset.top === undefined ? defaultOffset.top : offset.top,
29 | left: offset.left === undefined ? defaultOffset.left : offset.left
30 | };
31 | }
32 | function d3scription(contentGetter, options) {
33 | if (options === void 0) { options = {}; }
34 | var offsetSettings = getOffsetSettings(options.offset);
35 | return function () {
36 | var tip = d3.select('body')
37 | .append('div')
38 | .attr('class', options["class"] || 'd3scription-tip')
39 | .style('position', 'absolute')
40 | .style('z-index', options.zIndex || 100)
41 | .style('visibility', 'hidden');
42 | function updateTipPosition() {
43 | var bounds = tip.node().getBoundingClientRect();
44 | var position = getOffset(d3.event, bounds, offsetSettings);
45 | tip
46 | .style("top", position.top + "px")
47 | .style("left", position.left + "px");
48 | }
49 | function setupTracking(element) {
50 | element.on('mousemove', updateTipPosition);
51 | }
52 | var publicMethods = {
53 | element: function (element) {
54 | setupTracking(element);
55 | return publicMethods;
56 | },
57 | show: function (data) {
58 | updateTipPosition();
59 | tip.html(contentGetter(data));
60 | tip.style('visibility', 'visible');
61 | return publicMethods;
62 | },
63 | update: function (data) {
64 | tip.html(contentGetter(data));
65 | return publicMethods;
66 | },
67 | hide: function () {
68 | tip.style('visibility', 'hidden');
69 | return publicMethods;
70 | },
71 | remove: function () {
72 | tip.remove();
73 | }
74 | };
75 | return publicMethods;
76 | };
77 | }
78 | exports["default"] = d3scription;
79 | // export as Global Object
80 | if (typeof window === 'object') {
81 | window['d3scription'] = d3scription;
82 | }
83 |
--------------------------------------------------------------------------------
/index.ts:
--------------------------------------------------------------------------------
1 | ///
2 |
3 | export interface Offset {
4 | top? : number;
5 | left? : number;
6 | }
7 |
8 | export interface Options {
9 | zIndex? : number;
10 | class? : string;
11 | offset? : Offset;
12 | }
13 |
14 | export interface ContentGetter extends Function {
15 | (data : T) : string;
16 | }
17 |
18 | export interface Tip {
19 | element(element : d3.Selection) : Tip;
20 | show(data : T) : Tip;
21 | update(data : T) : Tip;
22 | hide() : Tip;
23 | remove() : void;
24 | }
25 |
26 | export interface TipFactory extends Function {
27 | () : Tip
28 | }
29 |
30 | interface WindowDimensions {
31 | width : number,
32 | height : number
33 | }
34 |
35 | interface Position {
36 | top : number,
37 | left : number,
38 | }
39 |
40 | let windowDimensions : WindowDimensions = {
41 | width: window.innerWidth,
42 | height: window.innerHeight
43 | }
44 |
45 | function setWindowDimmensions() : void {
46 | windowDimensions = {
47 | width: window.innerWidth,
48 | height: window.innerHeight
49 | }
50 | }
51 |
52 | const windowResize = window.addEventListener('resize', setWindowDimmensions);
53 |
54 | function getOffset(event : MouseEvent, bounds : ClientRect, offset : Position) : Position {
55 | const collideVertically : boolean = (windowDimensions.height + window.scrollY) - event.pageY - offset.top - bounds.height < 0;
56 | const collideHorizontally : boolean = (windowDimensions.width + window.scrollX) - event.pageX - offset.left - bounds.width < 0;
57 |
58 | return {
59 | top: collideVertically ? event.pageY - bounds.height - offset.top : offset.top + event.pageY,
60 | left: collideHorizontally ? event.pageX - bounds.width - offset.left : event.pageX + offset.left
61 | };
62 | }
63 |
64 | const defaultOffset : Position = { top: 10, left: 10 };
65 | function getOffsetSettings(offset? : Offset) : Position {
66 | if (!offset) return defaultOffset;
67 | return {
68 | top: offset.top === undefined ? defaultOffset.top : offset.top,
69 | left: offset.left === undefined ? defaultOffset.left : offset.left
70 | };
71 | }
72 |
73 | export default function d3scription (contentGetter : ContentGetter, options:Options = {}) : TipFactory {
74 | const offsetSettings : Position = getOffsetSettings(options.offset);
75 |
76 | return function () : Tip {
77 | const tip : d3.Selection = d3.select('body')
78 | .append('div')
79 | .attr('class', options.class || 'd3scription-tip')
80 | .style('position', 'absolute')
81 | .style('z-index', options.zIndex || 100)
82 | .style('visibility', 'hidden');
83 |
84 | function updateTipPosition() {
85 | const bounds : ClientRect = tip.node().getBoundingClientRect();
86 | const position : Position = getOffset(d3.event, bounds, offsetSettings)
87 |
88 | tip
89 | .style("top", `${position.top}px`)
90 | .style("left", `${position.left}px`);
91 | }
92 |
93 | function setupTracking(element : d3.Selection) : void {
94 | element.on('mousemove', updateTipPosition);
95 | }
96 |
97 | const publicMethods : Tip = {
98 | element(element : d3.Selection) : Tip {
99 | setupTracking(element);
100 |
101 | return publicMethods;
102 | },
103 | show(data : T) : Tip {
104 | updateTipPosition();
105 | tip.html(contentGetter(data));
106 | tip.style('visibility', 'visible');
107 |
108 | return publicMethods;
109 | },
110 | update(data : T) : Tip {
111 | tip.html(contentGetter(data));
112 |
113 | return publicMethods;
114 | },
115 | hide() : Tip {
116 | tip.style('visibility', 'hidden');
117 |
118 | return publicMethods;
119 | },
120 | remove() : void {
121 | tip.remove();
122 | }
123 | };
124 |
125 | return publicMethods;
126 | };
127 | }
128 |
129 | // export as Global Object
130 | if (typeof window === 'object') {
131 | window['d3scription'] = d3scription;
132 | }
133 |
--------------------------------------------------------------------------------
/dist/d3scription.js:
--------------------------------------------------------------------------------
1 | var d3scription = d3scription || {}; d3scription["d3scription"] =
2 | /******/ (function(modules) { // webpackBootstrap
3 | /******/ // The module cache
4 | /******/ var installedModules = {};
5 |
6 | /******/ // The require function
7 | /******/ function __webpack_require__(moduleId) {
8 |
9 | /******/ // Check if module is in cache
10 | /******/ if(installedModules[moduleId])
11 | /******/ return installedModules[moduleId].exports;
12 |
13 | /******/ // Create a new module (and put it into the cache)
14 | /******/ var module = installedModules[moduleId] = {
15 | /******/ exports: {},
16 | /******/ id: moduleId,
17 | /******/ loaded: false
18 | /******/ };
19 |
20 | /******/ // Execute the module function
21 | /******/ modules[moduleId].call(module.exports, module, module.exports, __webpack_require__);
22 |
23 | /******/ // Flag the module as loaded
24 | /******/ module.loaded = true;
25 |
26 | /******/ // Return the exports of the module
27 | /******/ return module.exports;
28 | /******/ }
29 |
30 |
31 | /******/ // expose the modules object (__webpack_modules__)
32 | /******/ __webpack_require__.m = modules;
33 |
34 | /******/ // expose the module cache
35 | /******/ __webpack_require__.c = installedModules;
36 |
37 | /******/ // __webpack_public_path__
38 | /******/ __webpack_require__.p = "";
39 |
40 | /******/ // Load entry module and return exports
41 | /******/ return __webpack_require__(0);
42 | /******/ })
43 | /************************************************************************/
44 | /******/ ([
45 | /* 0 */
46 | /***/ (function(module, exports, __webpack_require__) {
47 |
48 | module.exports = __webpack_require__(1);
49 |
50 |
51 | /***/ }),
52 | /* 1 */
53 | /***/ (function(module, exports, __webpack_require__) {
54 |
55 | var __WEBPACK_AMD_DEFINE_ARRAY__, __WEBPACK_AMD_DEFINE_RESULT__;///
56 | !(__WEBPACK_AMD_DEFINE_ARRAY__ = [__webpack_require__, exports], __WEBPACK_AMD_DEFINE_RESULT__ = function (require, exports) {
57 | "use strict";
58 | Object.defineProperty(exports, "__esModule", { value: true });
59 | var windowDimensions = {
60 | width: window.innerWidth,
61 | height: window.innerHeight
62 | };
63 | function setWindowDimmensions() {
64 | windowDimensions = {
65 | width: window.innerWidth,
66 | height: window.innerHeight
67 | };
68 | }
69 | var windowResize = window.addEventListener('resize', setWindowDimmensions);
70 | function getOffset(event, bounds, offset) {
71 | var collideVertically = (windowDimensions.height + window.scrollY) - event.pageY - offset.top - bounds.height < 0;
72 | var collideHorizontally = (windowDimensions.width + window.scrollX) - event.pageX - offset.left - bounds.width < 0;
73 | return {
74 | top: collideVertically ? event.pageY - bounds.height - offset.top : offset.top + event.pageY,
75 | left: collideHorizontally ? event.pageX - bounds.width - offset.left : event.pageX + offset.left
76 | };
77 | }
78 | var defaultOffset = { top: 10, left: 10 };
79 | function getOffsetSettings(offset) {
80 | if (!offset)
81 | return defaultOffset;
82 | return {
83 | top: offset.top === undefined ? defaultOffset.top : offset.top,
84 | left: offset.left === undefined ? defaultOffset.left : offset.left
85 | };
86 | }
87 | function d3scription(contentGetter, options) {
88 | if (options === void 0) { options = {}; }
89 | var offsetSettings = getOffsetSettings(options.offset);
90 | return function () {
91 | var tip = d3.select('body')
92 | .append('div')
93 | .attr('class', options.class || 'd3scription-tip')
94 | .style('position', 'absolute')
95 | .style('z-index', options.zIndex || 100)
96 | .style('visibility', 'hidden');
97 | function updateTipPosition() {
98 | var bounds = tip.node().getBoundingClientRect();
99 | var position = getOffset(d3.event, bounds, offsetSettings);
100 | tip
101 | .style("top", position.top + "px")
102 | .style("left", position.left + "px");
103 | }
104 | function setupTracking(element) {
105 | element.on('mousemove', updateTipPosition);
106 | }
107 | var publicMethods = {
108 | element: function (element) {
109 | setupTracking(element);
110 | return publicMethods;
111 | },
112 | show: function (data) {
113 | updateTipPosition();
114 | tip.html(contentGetter(data));
115 | tip.style('visibility', 'visible');
116 | return publicMethods;
117 | },
118 | update: function (data) {
119 | tip.html(contentGetter(data));
120 | return publicMethods;
121 | },
122 | hide: function () {
123 | tip.style('visibility', 'hidden');
124 | return publicMethods;
125 | },
126 | remove: function () {
127 | tip.remove();
128 | }
129 | };
130 | return publicMethods;
131 | };
132 | }
133 | exports.default = d3scription;
134 | // export as Global Object
135 | if (typeof window === 'object') {
136 | window['d3scription'] = d3scription;
137 | }
138 | }.apply(exports, __WEBPACK_AMD_DEFINE_ARRAY__), __WEBPACK_AMD_DEFINE_RESULT__ !== undefined && (module.exports = __WEBPACK_AMD_DEFINE_RESULT__));
139 |
140 |
141 | /***/ })
142 | /******/ ]);
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # d3scription
2 |
3 | D3 tooltip description following mouse cursor. With window edge collision solved.
4 |
5 | 
6 |
7 | This plugin tries to be as universal and simple as possible.
8 | You can install it using your favorite dependency manager - doesn't matter if it is [NPM](http://npmjs.org/) or [bower](https://bower.io/).
9 | You can also **directly download distribution** if you do not use any of these. It supports many module systems (commonjs, AMD, TypeScript).
10 | You can easily customize look in your css and overwrite all default values by providing your own.
11 |
12 | # Instalation
13 |
14 | ## NPM
15 |
16 | This will install npm package with **commonjs** module system:
17 |
18 | ```
19 | npm install d3scription --save
20 | ```
21 |
22 | ## Bower
23 |
24 | This will install bower package with **AMD** module and **global `d3scription` variable**:
25 |
26 | ```
27 | bower install d3scription --save
28 | ```
29 |
30 | ## Direct download
31 |
32 | If you do not want to use any dependency manager in your project you can simply download [distribution](dist/d3scription.js)
33 | and place it in your project. This is exactly the same file as installed using bower. It supports **AMD modules or global `d3scription` function**.
34 |
35 | ```
36 | curl https://raw.githubusercontent.com/GlobalWebIndex/d3scription/master/dist/d3scription.js > d3scription.js
37 | ```
38 |
39 | # Usage
40 | You can use this plugin with both **JavaScript and TypeScript**. Please see [demos](demo/) for some example usage.
41 |
42 | ## JavaScript
43 |
44 | Assume you have d3scription.js file already loaded in browser together with d3.js or AMD manager is used you're able to use this plugin in similar fashion.
45 | Don't forget, that this plugin itself is dependent on D3 so you need to include d3 before you load d3scription!
46 |
47 | ```js
48 | // define some example data
49 | var data = [
50 | {
51 | x: 50,
52 | y: 100,
53 | desc: 'We are your friends...'
54 | },
55 | {
56 | x: 200,
57 | y: 50,
58 | desc: 'I love it!'
59 | }
60 | ]
61 |
62 | // select SVG element and create main group
63 | var el = d3.select('svg')
64 | .append('g');
65 |
66 | // setup plugin with description getter function and default options.
67 | // if you want to overwrite default z-index, offset or class name please see `api:setup:options section`
68 | var tipFactory = d3scription(function(d) { return d.desc; });
69 |
70 | // create tip for our main group element
71 | var tip = tipFactory()
72 | .element(el);
73 |
74 | // set data to circles
75 | var circles = el.selectAll('.circle')
76 | .data(data);
77 |
78 | // draw circles
79 | var cEnter = circles.enter()
80 | .append('circle')
81 | .attr('class', 'circle')
82 | .attr('r', 30)
83 | .attr('cx', function(d) { return d.x; })
84 | .attr('cy', function(d) { return d.y; })
85 | // setup show and hide action on mouse events
86 | .on('mouseover', tip.show)
87 | .on('mouseout', tip.hide);
88 | ```
89 |
90 | ## Typescript
91 |
92 | Usage with typescript is quite simmilar as usage with any other module system.
93 |
94 | ```typescript
95 | import d3scription from 'd3scription';
96 |
97 | interface Data {
98 | x : number;
99 | y : number;
100 | desc : string;
101 | }
102 |
103 | // define some example data
104 | const data : Data[] = [
105 | {
106 | x: 50,
107 | y: 100,
108 | desc: 'We are your friends...'
109 | },
110 | {
111 | x: 200,
112 | y: 50,
113 | desc: 'I love it!'
114 | }
115 | ]
116 |
117 | // select SVG element and create main group
118 | const el = d3.select('#first-example')
119 | .append('g');
120 |
121 | // setup plugin with description getter function and default options.
122 | // if you want to overwrite default z-index, offset or class name please see `api:setup:options section`
123 | const tipFactory = d3scription((d : Data) => d.desc);
124 |
125 | // create tip for our main group element
126 | const tip = tipFactory()
127 | .element(el);
128 |
129 | // set data to circles
130 | const circles = el.selectAll('.circle')
131 | .data(data);
132 |
133 | // draw circles
134 | const cEnter = circles.enter()
135 | .append('circle')
136 | .attr('class', 'circle')
137 | .attr('r', 30)
138 | .attr('cx', d => d.x)
139 | .attr('cy', d => d.y)
140 | // setup show and hide action on mouse events
141 | .on('mouseover', tip.show)
142 | .on('mouseout', tip.hide);
143 | ```
144 |
145 | # Styles
146 |
147 | You can import or copy [default styles](css/style.css) to your project if you want.
148 | Anyway as you can see writing your own styles for tooltip is really simple.
149 |
150 | # API
151 |
152 | Api is design as three steps process to make reuse and flow as clean as possible.
153 | These steps are `setup` > `initialize` > `use`. Folloving paragraphs describes each step individually.
154 |
155 | ## Setup
156 |
157 | First you need to setup new Tip factory (you can think about it as alternative to subclassing base class with necessary options even it's not really uses classes at all).
158 | This is done using the only public function provided by d3scription out of the box - `de3scription([contentGetter], [optionalOptions])`.
159 |
160 | This function accept two parameters - `contentGetter` and `options`.
161 |
162 | **Content getter** is just regular function which takes `data` and returns `string` content of tip.
163 | This works the same way as many d3 methods like `.attr('x', [getter])` or `.style('fill', [getter])`.
164 |
165 | ### Options
166 |
167 | Are used for overwriting default settings of plugin. It's a **hash** where every key is optional.
168 | For typescript plugin exports this interface under name `Options`.
169 | There are all possible values:
170 |
171 | * `zIndex` sets css z-index of tip element (default is 100).
172 | * `class` set custom class name for element (default is `d3scription-tip`).
173 | * `offset["top"]` top offset of tip (default is `-10`).
174 | * `offset["left"]` left offset of tip (default is `10`).
175 |
176 | You can create one settuped tipFactory and reuse it on multiple places or create as many of these factories as you wish.
177 |
178 | ### Example
179 |
180 | ```js
181 | function getDescription(data) {
182 | return data.toolTipText;
183 | }
184 | var options = {
185 | zIndex: 1000,
186 | class: 'my-tooltip',
187 | offset: {
188 | top: 20,
189 | left: 20
190 | }
191 | }
192 | var myD3scription = d3Scription(getDescription, options);
193 | var defaultD3scription = d3scription(getDescription);
194 | ```
195 |
196 | ## Factory
197 |
198 | Settup function return another function which takes **element** in which tip should be active.
199 | This is element in which tip will follow mouse. This function also creates final tip.
200 | You can create many tips from one factory using this function.
201 |
202 | ### Example
203 |
204 | ```js
205 | var element = d3.select('svg').append('g');
206 | var tip = myD3scription().element(element); // this function was returned by setup
207 | ```
208 |
209 | ## Tip
210 |
211 | Finally you'll have a tip instance returned by from factory (after passing element).
212 | Now you can call methods on this tip as you wish. Most common case is to `show(data)` and `hide()`
213 | on mouse events. you can also take advantage of `element(element)` for changing orginal element of tip
214 | or using `destroy()`.
215 |
216 | ## Tip API
217 |
218 | * `show(data)` sets content of tip and displays it.
219 | * `hide()` hides tip
220 | * `element(element)` sets new element for tip
221 | * `destroy()` removes tip from dom
222 |
223 | ## Basic Example of usage
224 |
225 | ```js
226 | // define circle elements and bind data for them
227 | var circles = el.selectAll('.circle')
228 | .data(data);
229 |
230 | // create circles and add tips actions to them
231 | var cEnter = circles.enter()
232 | .append('circle')
233 | .attr('class', 'circle')
234 | .attr('r', 30)
235 | .attr('cx', function(d) { return d.x; })
236 | .attr('cy', function(d) { return d.y; })
237 | // show tip on mouseover
238 | // NOTE: will use binded data for setting content of tip
239 | .on('mouseover', tip.show)
240 | // hide tip on mouseout event
241 | .on('mouseout', tip.hide);
242 | ```
243 | # Changelog
244 |
245 | - v1.0.1 - update position on show (fixes situations where `show` is called but `mouseMove` event doesn't happen)
246 | - v1.0.0 - improve API
247 | - v0.0.2 - window edge collision detections
248 | - v0.0.1 - initial release
249 |
250 | # Building localy
251 |
252 | All PRs are welcome! This is why we tried to made whole development setup as simple as possible.
253 |
254 | Clone repository:
255 |
256 | ```
257 | git clone git@github.com:GlobalWebIndex/d3scription.git
258 | ```
259 |
260 | Install all dependecies via NPM and Bower:
261 |
262 | ```
263 | npm install && bower install
264 | ```
265 |
266 | The main file you want to work with is [index.ts](index.ts). There are also [demo examples](demo/) where you can play with plugin.
267 |
268 | ## Building project
269 |
270 | There are few handy npm scripts already settuped up.
271 |
272 | If you want to run project as watch run:
273 |
274 | ```
275 | npm run watch
276 | ```
277 |
278 | you can then open [demo/index.html](examples) in browser. Project will be compiled in background if you made any change to source.
279 |
280 | For building distribution please run following.
281 |
282 | ```
283 | npm run compile
284 | ```
285 |
286 | This will compile all versions of plugin (including commonjs for usage with NPM).
287 |
288 | # License
289 |
290 | MIT
291 |
292 | ## About GlobalWebIndex
293 |
294 | 
295 |
296 | d3scription is maintained by GlobalWebIndex Ltd.
297 |
298 | See more about us at [www.globalwebindex.net](https://www.globalwebindex.net).
299 |
--------------------------------------------------------------------------------
/d/d3.d.ts:
--------------------------------------------------------------------------------
1 | // Type definitions for d3JS
2 | // Project: http://d3js.org/
3 | // Definitions by: Alex Ford , Boris Yankov
4 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
5 |
6 | declare namespace d3 {
7 | /**
8 | * The current version of D3.js.
9 | */
10 | export var version: string;
11 |
12 | /**
13 | * Find the first element that matches the given selector string.
14 | */
15 | export function select(selector: string): Selection;
16 |
17 | /**
18 | * Create a selection from the given node reference.
19 | */
20 | export function select(node: EventTarget): Selection;
21 |
22 | /**
23 | * Find all elements that match the given selector string.
24 | */
25 | export function selectAll(selector: string): Selection;
26 |
27 | /**
28 | * Create a selection from the given list of nodes.
29 | */
30 | export function selectAll(nodes: EventTarget[]): Selection;
31 |
32 | /**
33 | * Returns the root selection (as if by d3.select(document.documentElement)). This function may be used for 'instanceof' tests, and extending its prototype will add properties to all selections.
34 | */
35 | export function selection(): Selection;
36 |
37 | namespace selection {
38 | export var prototype: Selection;
39 |
40 | /**
41 | * Selections are grouped into arrays of nodes, with the parent tracked in the 'parentNode' property.
42 | */
43 | interface Group extends Array {
44 | parentNode: EventTarget;
45 | }
46 |
47 | interface Update {
48 | /**
49 | * Retrieve a grouped selection.
50 | */
51 | [index: number]: Group;
52 |
53 | /**
54 | * The number of groups in this selection.
55 | */
56 | length: number;
57 |
58 | /**
59 | * Retrieve the value of the given attribute for the first node in the selection.
60 | *
61 | * @param name The attribute name to query. May be prefixed (see d3.ns.prefix).
62 | */
63 | attr(name: string): string;
64 |
65 | /**
66 | * For all nodes, set the attribute to the specified constant value. Use null to remove.
67 | *
68 | * @param name The attribute name, optionally prefixed.
69 | * @param value The attribute value to use. Note that this is coerced to a string automatically.
70 | */
71 | attr(name: string, value: Primitive): Update;
72 |
73 | /**
74 | * Derive an attribute value for each node in the selection based on bound data.
75 | *
76 | * @param name The attribute name, optionally prefixed.
77 | * @param value The function of the datum (the bound data item), index (the position in the subgrouping), and outer index (overall position in nested selections) which computes the attribute value. If the function returns null, the attribute is removed.
78 | */
79 | attr(name: string, value: (datum: Datum, index: number, outerIndex: number) => Primitive): Update;
80 |
81 | /**
82 | * Set multiple properties at once using an Object. D3 iterates over all enumerable properties and either sets or computes the attribute's value based on the corresponding entry in the Object.
83 | *
84 | * @param obj A key-value mapping corresponding to attributes and values. If the value is a simple string or number, it is taken as a constant. Otherwise, it is a function that derives the attribute value.
85 | */
86 | attr(obj: { [key: string]: Primitive | ((datum: Datum, index: number, outerIndex: number) => Primitive) }): Update;
87 |
88 | /**
89 | * Returns true if the first node in this selection has the given class list. If multiple classes are specified (i.e., "foo bar"), then returns true only if all classes match.
90 | *
91 | * @param name The class list to query.
92 | */
93 | classed(name: string): boolean;
94 |
95 | /**
96 | * Adds (or removes) the given class list.
97 | *
98 | * @param name The class list to toggle. Spaces separate class names: "foo bar" is a list of two classes.
99 | * @param value If true, add the classes. If false, remove them.
100 | */
101 | classed(name: string, value: boolean): Update;
102 |
103 | /**
104 | * Determine if the given class list should be toggled for each node in the selection.
105 | *
106 | * @param name The class list. Spaces separate multiple class names.
107 | * @param value The function to run for each node. Should return true to add the class to the node, or false to remove it.
108 | */
109 | classed(name: string, value: (datum: Datum, index: number, outerIndex: number) => boolean): Update;
110 |
111 | /**
112 | * Set or derive classes for multiple class lists at once.
113 | *
114 | * @param obj An Object mapping class lists to values that are either plain booleans or functions that return booleans.
115 | */
116 | classed(obj: { [key: string]: boolean | ((datum: Datum, index: number, outerIndex: number) => boolean) }): Update;
117 |
118 | /**
119 | * Retrieve the computed style value for the first node in the selection.
120 | * @param name The CSS property name to query
121 | */
122 | style(name: string): string;
123 |
124 | /**
125 | * Set a style property for all nodes in the selection.
126 | * @param name the CSS property name
127 | * @param value the property value
128 | * @param priority if specified, either null or the string "important" (no exclamation mark)
129 | */
130 | style(name: string, value: Primitive, priority?: string): Update;
131 |
132 | /**
133 | * Derive a property value for each node in the selection.
134 | * @param name the CSS property name
135 | * @param value the function to derive the value
136 | * @param priority if specified, either null or the string "important" (no exclamation mark)
137 | */
138 | style(name: string, value: (datum: Datum, index: number, outerIndex: number) => Primitive, priority?: string): Update;
139 |
140 | /**
141 | * Set a large number of CSS properties from an object.
142 | *
143 | * @param obj an Object whose keys correspond to CSS property names and values are either constants or functions that derive property values
144 | * @param priority if specified, either null or the string "important" (no exclamation mark)
145 | */
146 | style(obj: { [key: string]: Primitive | ((datum: Datum, index: number, outerIndex: number) => Primitive) }, priority?: string): Update;
147 |
148 | /**
149 | * Retrieve an arbitrary node property such as the 'checked' property of checkboxes, or the 'value' of text boxes.
150 | *
151 | * @param name the node's property to retrieve
152 | */
153 | property(name: string): any;
154 |
155 | /**
156 | * For each node, set the property value. Internally, this sets the node property directly (e.g., node[name] = value), so take care not to mutate special properties like __proto__.
157 | *
158 | * @param name the property name
159 | * @param value the property value
160 | */
161 | property(name: string, value: any): Update;
162 |
163 | /**
164 | * For each node, derive the property value. Internally, this sets the node property directly (e.g., node[name] = value), so take care not to mutate special properties like __proto__.
165 | *
166 | * @param name the property name
167 | * @param value the function used to derive the property's value
168 | */
169 | property(name: string, value: (datum: Datum, index: number, outerIndex: number) => any): Update;
170 |
171 | /**
172 | * Set multiple node properties. Caveats apply: take care not to mutate special properties like __proto__.
173 | *
174 | * @param obj an Object whose keys correspond to node properties and values are either constants or functions that will compute a value.
175 | */
176 | property(obj: { [key: string]: any | ((datum: Datum, index: number, outerIndex: number) => any) }): Update;
177 |
178 | /**
179 | * Retrieve the textContent of the first node in the selection.
180 | */
181 | text(): string;
182 |
183 | /**
184 | * Set the textContent of each node in the selection.
185 | * @param value the text to use for all nodes
186 | */
187 | text(value: Primitive): Update;
188 |
189 | /**
190 | * Compute the textContent of each node in the selection.
191 | * @param value the function which will compute the text
192 | */
193 | text(value: (datum: Datum, index: number, outerIndex: number) => Primitive): Update;
194 |
195 | /**
196 | * Retrieve the HTML content of the first node in the selection. Uses 'innerHTML' internally and will not work with SVG or other elements without a polyfill.
197 | */
198 | html(): string;
199 |
200 | /**
201 | * Set the HTML content of every node in the selection. Uses 'innerHTML' internally and thus will not work with SVG or other elements without a polyfill.
202 | * @param value the HTML content to use.
203 | */
204 | html(value: string): Selection;
205 |
206 | /**
207 | * Compute the HTML content for each node in the selection. Uses 'innerHTML' internally and thus will not work with SVG or other elements without a polyfill.
208 | * @param value the function to compute HTML content
209 | */
210 | html(value: (datum: Datum, index: number, outerIndex: number) => string): Selection;
211 |
212 | /**
213 | * Appends a new child to each node in the selection. This child will inherit the parent's data (if available). Returns a fresh selection consisting of the newly-appended children.
214 | *
215 | * @param name the element name to append. May be prefixed (see d3.ns.prefix).
216 | */
217 | append(name: string): Selection;
218 |
219 | /**
220 | * Appends a new child to each node in the selection by computing a new node. This child will inherit the parent's data (if available). Returns a fresh selection consisting of the newly-appended children.
221 | *
222 | * @param name the function to compute a new element
223 | */
224 | append(name: (datum: Datum, index: number, outerIndex: number) => EventTarget): Update;
225 |
226 | /**
227 | * Inserts a new child to each node in the selection. This child will inherit its parent's data (if available). Returns a fresh selection consisting of the newly-inserted children.
228 | * @param name the element name to append. May be prefixed (see d3.ns.prefix).
229 | * @param before the selector to determine position (e.g., ":first-child")
230 | */
231 | insert(name: string, before: string): Update;
232 |
233 | /**
234 | * Inserts a new child to each node in the selection. This child will inherit its parent's data (if available). Returns a fresh selection consisting of the newly-inserted children.
235 | * @param name the element name to append. May be prefixed (see d3.ns.prefix).
236 | * @param before a function to determine the node to use as the next sibling
237 | */
238 | insert(name: string, before: (datum: Datum, index: number, outerIndex: number) => EventTarget): Update;
239 |
240 | /**
241 | * Inserts a new child to the end of each node in the selection by computing a new node. This child will inherit its parent's data (if available). Returns a fresh selection consisting of the newly-inserted children.
242 | * @param name the function to compute a new child
243 | * @param before the selector to determine position (e.g., ":first-child")
244 | */
245 | insert(name: (datum: Datum, index: number, outerIndex: number) => EventTarget, before: string): Update;
246 |
247 | /**
248 | * Inserts a new child to the end of each node in the selection by computing a new node. This child will inherit its parent's data (if available). Returns a fresh selection consisting of the newly-inserted children.
249 | * @param name the function to compute a new child
250 | * @param before a function to determine the node to use as the next sibling
251 | */
252 | insert(name: (datum: Datum, index: number, outerIndex: number) => EventTarget, before: (datum: Datum, index: number, outerIndex: number) => EventTarget): Update;
253 |
254 | /**
255 | * Removes the elements from the DOM. They are in a detached state and may be re-added (though there is currently no dedicated API for doing so).
256 | */
257 | remove(): Update;
258 |
259 | /**
260 | * Retrieves the data bound to the first group in this selection.
261 | */
262 | data(): Datum[];
263 |
264 | /**
265 | * Binds data to this selection.
266 | * @param data the array of data to bind to this selection
267 | * @param key the optional function to determine the unique key for each piece of data. When unspecified, uses the index of the element.
268 | */
269 | data(data: NewDatum[], key?: (datum: NewDatum, index: number, outerIndex: number) => string): Update;
270 |
271 | /**
272 | * Derives data to bind to this selection.
273 | * @param data the function to derive data. Must return an array.
274 | * @param key the optional function to determine the unique key for each data item. When unspecified, uses the index of the element.
275 | */
276 | data(data: (datum: Datum, index: number, outerIndex: number) => NewDatum[], key?: (datum: NewDatum, index: number, outerIndex: number) => string): Update;
277 |
278 | /**
279 | * Filters the selection, returning only those nodes that match the given CSS selector.
280 | * @param selector the CSS selector
281 | */
282 | filter(selector: string): Update;
283 |
284 | /**
285 | * Filters the selection, returning only those nodes for which the given function returned true.
286 | * @param selector the filter function
287 | */
288 | filter(selector: (datum: Datum, index: number, outerIndex: number) => boolean): Update;
289 |
290 | /**
291 | * Return the data item bound to the first element in the selection.
292 | */
293 | datum(): Datum;
294 |
295 | /**
296 | * Derive the data item for each node in the selection. Useful for situations such as the HTML5 'dataset' attribute.
297 | * @param value the function to compute data for each node
298 | */
299 | datum(value: (datum: Datum, index: number, outerIndex: number) => NewDatum): Update;
300 |
301 | /**
302 | * Set the data item for each node in the selection.
303 | * @param value the constant element to use for each node
304 | */
305 | datum(value: NewDatum): Update;
306 |
307 | /**
308 | * Reorders nodes in the selection based on the given comparator. Nodes are re-inserted into the document once sorted.
309 | * @param comparator the comparison function, which defaults to d3.ascending
310 | */
311 | sort(comparator?: (a: Datum, b: Datum) => number): Update;
312 |
313 | /**
314 | * Reorders nodes in the document to match the selection order. More efficient than calling sort() if the selection is already ordered.
315 | */
316 | order(): Update;
317 |
318 | /**
319 | * Returns the listener (if any) for the given event.
320 | * @param type the type of event to load the listener for. May have a namespace (e.g., ".foo") at the end.
321 | */
322 | on(type: string): (datum: Datum, index: number, outerIndex: number) => any;
323 |
324 | /**
325 | * Adds a listener for the specified event. If one was already registered, it is removed before the new listener is added. The return value of the listener function is ignored.
326 | * @param type the of event to listen to. May have a namespace (e.g., ".foo") at the end.
327 | * @param listener an event listener function, or null to unregister
328 | * @param capture sets the DOM useCapture flag
329 | */
330 | on(type: string, listener: (datum: Datum, index: number, outerIndex: number) => any, capture?: boolean): Update;
331 |
332 | /**
333 | * Begins a new transition. Interrupts any active transitions of the same name.
334 | * @param name the transition name (defaults to "")
335 | */
336 | transition(name?: string): Transition;
337 |
338 | /**
339 | * Interrupts the active transition of the provided name. Does not cancel scheduled transitions.
340 | * @param name the transition name (defaults to "")
341 | */
342 | interrupt(name?: string): Update;
343 |
344 | /**
345 | * Creates a subselection by finding the first descendent matching the selector string. Bound data is inherited.
346 | * @param selector the CSS selector to match against
347 | */
348 | select(selector: string): Update;
349 |
350 | /**
351 | * Creates a subselection by using a function to find descendent elements. Bound data is inherited.
352 | * @param selector the function to find matching descendants
353 | */
354 | select(selector: (datum: Datum, index: number, outerIndex: number) => EventTarget): Update;
355 |
356 | /**
357 | * Creates a subselection by finding all descendents that match the given selector. Bound data is not inherited.
358 | * @param selector the CSS selector to match against
359 | */
360 | selectAll(selector: string): Update;
361 |
362 | /**
363 | * Creates a subselection by using a function to find descendent elements. Bound data is not inherited.
364 | * @param selector the function to find matching descendents
365 | */
366 | selectAll(selector: (datum: Datum, index: number, outerIndex: number) => Array | NodeList): Update;
367 |
368 | /**
369 | * Invoke the given function for each element in the selection. The return value of the function is ignored.
370 | * @param func the function to invoke
371 | */
372 | each(func: (datum: Datum, index: number, outerIndex: number) => any): Update;
373 |
374 | /**
375 | * Call a function on the selection. sel.call(foo) is equivalent to foo(sel).
376 | * @param func the function to call on the selection
377 | * @param args any optional args
378 | */
379 | call(func: (sel: Update, ...args: any[]) => any, ...args: any[]): Update;
380 |
381 | /**
382 | * Returns true if the current selection is empty.
383 | */
384 | empty(): boolean;
385 |
386 | /**
387 | * Returns the first non-null element in the selection, or null otherwise.
388 | */
389 | node(): MyNode;
390 |
391 | /**
392 | * Returns the total number of elements in the selection.
393 | */
394 | size(): number;
395 |
396 | /**
397 | * Returns the placeholder nodes for each data element for which no corresponding DOM element was found.
398 | */
399 | enter(): Enter;
400 |
401 | /**
402 | * Returns a selection for those DOM nodes for which no new data element was found.
403 | */
404 | exit(): Selection;
405 | }
406 |
407 | interface Enter {
408 | append(name: string): Selection;
409 | append(name: (datum: Datum, index: number, outerIndex: number) => EventTarget): Selection;
410 |
411 | insert(name: string, before?: string): Selection;
412 | insert(name: string, before: (datum: Datum, index: number, outerIndex: number) => EventTarget): Selection;
413 | insert(name: (datum: Datum, index: number, outerIndex: number) => EventTarget, before?: string): Selection;
414 | insert(name: (datum: Datum, index: number, outerIndex: number) => EventTarget, before: (datum: Datum, index: number, outerIndex: number) => EventTarget): Selection;
415 |
416 | select(name: (datum: Datum, index: number, outerIndex: number) => EventTarget): Selection;
417 | call(func: (selection: Enter, ...args: any[]) => any, ...args: any[]): Enter;
418 |
419 | empty(): boolean;
420 | size(): number;
421 | }
422 | }
423 |
424 | /**
425 | * Administrivia: JavaScript primitive types, or "things that toString() predictably".
426 | */
427 | export type Primitive = number | string | boolean;
428 |
429 | /**
430 | * Administrivia: anything with a valueOf(): number method is comparable, so we allow it in numeric operations
431 | */
432 | interface Numeric {
433 | valueOf(): number;
434 | }
435 |
436 | /**
437 | * A grouped array of nodes.
438 | * @param Datum the data bound to this selection.
439 | */
440 | interface Selection {
441 | /**
442 | * Retrieve a grouped selection.
443 | */
444 | [index: number]: selection.Group;
445 |
446 | /**
447 | * The number of groups in this selection.
448 | */
449 | length: number;
450 |
451 | /**
452 | * Retrieve the value of the given attribute for the first node in the selection.
453 | *
454 | * @param name The attribute name to query. May be prefixed (see d3.ns.prefix).
455 | */
456 | attr(name: string): string;
457 |
458 | /**
459 | * For all nodes, set the attribute to the specified constant value. Use null to remove.
460 | *
461 | * @param name The attribute name, optionally prefixed.
462 | * @param value The attribute value to use. Note that this is coerced to a string automatically.
463 | */
464 | attr(name: string, value: Primitive): Selection;
465 |
466 | /**
467 | * Derive an attribute value for each node in the selection based on bound data.
468 | *
469 | * @param name The attribute name, optionally prefixed.
470 | * @param value The function of the datum (the bound data item), index (the position in the subgrouping), and outer index (overall position in nested selections) which computes the attribute value. If the function returns null, the attribute is removed.
471 | */
472 | attr(name: string, value: (datum: Datum, index: number, outerIndex: number) => Primitive): Selection;
473 |
474 | /**
475 | * Set multiple properties at once using an Object. D3 iterates over all enumerable properties and either sets or computes the attribute's value based on the corresponding entry in the Object.
476 | *
477 | * @param obj A key-value mapping corresponding to attributes and values. If the value is a simple string or number, it is taken as a constant. Otherwise, it is a function that derives the attribute value.
478 | */
479 | attr(obj: { [key: string]: Primitive | ((datum: Datum, index: number, outerIndex: number) => Primitive) }): Selection;
480 |
481 | /**
482 | * Returns true if the first node in this selection has the given class list. If multiple classes are specified (i.e., "foo bar"), then returns true only if all classes match.
483 | *
484 | * @param name The class list to query.
485 | */
486 | classed(name: string): boolean;
487 |
488 | /**
489 | * Adds (or removes) the given class list.
490 | *
491 | * @param name The class list to toggle. Spaces separate class names: "foo bar" is a list of two classes.
492 | * @param value If true, add the classes. If false, remove them.
493 | */
494 | classed(name: string, value: boolean): Selection;
495 |
496 | /**
497 | * Determine if the given class list should be toggled for each node in the selection.
498 | *
499 | * @param name The class list. Spaces separate multiple class names.
500 | * @param value The function to run for each node. Should return true to add the class to the node, or false to remove it.
501 | */
502 | classed(name: string, value: (datum: Datum, index: number, outerIndex: number) => boolean): Selection;
503 |
504 | /**
505 | * Set or derive classes for multiple class lists at once.
506 | *
507 | * @param obj An Object mapping class lists to values that are either plain booleans or functions that return booleans.
508 | */
509 | classed(obj: { [key: string]: boolean | ((datum: Datum, index: number, outerIndex: number) => boolean) }): Selection;
510 |
511 | /**
512 | * Retrieve the computed style value for the first node in the selection.
513 | * @param name The CSS property name to query
514 | */
515 | style(name: string): string;
516 |
517 | /**
518 | * Set a style property for all nodes in the selection.
519 | * @param name the CSS property name
520 | * @param value the property value
521 | * @param priority if specified, either null or the string "important" (no exclamation mark)
522 | */
523 | style(name: string, value: Primitive, priority?: string): Selection;
524 |
525 | /**
526 | * Derive a property value for each node in the selection.
527 | * @param name the CSS property name
528 | * @param value the function to derive the value
529 | * @param priority if specified, either null or the string "important" (no exclamation mark)
530 | */
531 | style(name: string, value: (datum: Datum, index: number, outerIndex: number) => Primitive, priority?: string): Selection;
532 |
533 | /**
534 | * Set a large number of CSS properties from an object.
535 | *
536 | * @param obj an Object whose keys correspond to CSS property names and values are either constants or functions that derive property values
537 | * @param priority if specified, either null or the string "important" (no exclamation mark)
538 | */
539 | style(obj: { [key: string]: Primitive | ((datum: Datum, index: number, outerIndex: number) => Primitive) }, priority?: string): Selection;
540 |
541 | /**
542 | * Retrieve an arbitrary node property such as the 'checked' property of checkboxes, or the 'value' of text boxes.
543 | *
544 | * @param name the node's property to retrieve
545 | */
546 | property(name: string): any;
547 |
548 | /**
549 | * For each node, set the property value. Internally, this sets the node property directly (e.g., node[name] = value), so take care not to mutate special properties like __proto__.
550 | *
551 | * @param name the property name
552 | * @param value the property value
553 | */
554 | property(name: string, value: any): Selection;
555 |
556 | /**
557 | * For each node, derive the property value. Internally, this sets the node property directly (e.g., node[name] = value), so take care not to mutate special properties like __proto__.
558 | *
559 | * @param name the property name
560 | * @param value the function used to derive the property's value
561 | */
562 | property(name: string, value: (datum: Datum, index: number, outerIndex: number) => any): Selection;
563 |
564 | /**
565 | * Set multiple node properties. Caveats apply: take care not to mutate special properties like __proto__.
566 | *
567 | * @param obj an Object whose keys correspond to node properties and values are either constants or functions that will compute a value.
568 | */
569 | property(obj: { [key: string]: any | ((datum: Datum, index: number, innerInder: number) => any) }): Selection;
570 |
571 | /**
572 | * Retrieve the textContent of the first node in the selection.
573 | */
574 | text(): string;
575 |
576 | /**
577 | * Set the textContent of each node in the selection.
578 | * @param value the text to use for all nodes
579 | */
580 | text(value: Primitive): Selection;
581 |
582 | /**
583 | * Compute the textContent of each node in the selection.
584 | * @param value the function which will compute the text
585 | */
586 | text(value: (datum: Datum, index: number, outerIndex: number) => Primitive): Selection;
587 |
588 | /**
589 | * Retrieve the HTML content of the first node in the selection. Uses 'innerHTML' internally and will not work with SVG or other elements without a polyfill.
590 | */
591 | html(): string;
592 |
593 | /**
594 | * Set the HTML content of every node in the selection. Uses 'innerHTML' internally and thus will not work with SVG or other elements without a polyfill.
595 | * @param value the HTML content to use.
596 | */
597 | html(value: string): Selection;
598 |
599 | /**
600 | * Compute the HTML content for each node in the selection. Uses 'innerHTML' internally and thus will not work with SVG or other elements without a polyfill.
601 | * @param value the function to compute HTML content
602 | */
603 | html(value: (datum: Datum, index: number, outerIndex: number) => string): Selection;
604 |
605 | /**
606 | * Appends a new child to each node in the selection. This child will inherit the parent's data (if available). Returns a fresh selection consisting of the newly-appended children.
607 | *
608 | * @param name the element name to append. May be prefixed (see d3.ns.prefix).
609 | */
610 | append(name: string): Selection;
611 |
612 | /**
613 | * Appends a new child to each node in the selection by computing a new node. This child will inherit the parent's data (if available). Returns a fresh selection consisting of the newly-appended children.
614 | *
615 | * @param name the function to compute a new element
616 | */
617 | append(name: (datum: Datum, index: number, outerIndex: number) => EventTarget): Selection;
618 |
619 | /**
620 | * Inserts a new child to each node in the selection. This child will inherit its parent's data (if available). Returns a fresh selection consisting of the newly-inserted children.
621 | * @param name the element name to append. May be prefixed (see d3.ns.prefix).
622 | * @param before the selector to determine position (e.g., ":first-child")
623 | */
624 | insert(name: string, before: string): Selection;
625 |
626 | /**
627 | * Inserts a new child to each node in the selection. This child will inherit its parent's data (if available). Returns a fresh selection consisting of the newly-inserted children.
628 | * @param name the element name to append. May be prefixed (see d3.ns.prefix).
629 | * @param before a function to determine the node to use as the next sibling
630 | */
631 | insert(name: string, before: (datum: Datum, index: number, outerIndex: number) => EventTarget): Selection;
632 |
633 | /**
634 | * Inserts a new child to the end of each node in the selection by computing a new node. This child will inherit its parent's data (if available). Returns a fresh selection consisting of the newly-inserted children.
635 | * @param name the function to compute a new child
636 | * @param before the selector to determine position (e.g., ":first-child")
637 | */
638 | insert(name: (datum: Datum, index: number, outerIndex: number) => EventTarget, before: string): Selection;
639 |
640 | /**
641 | * Inserts a new child to the end of each node in the selection by computing a new node. This child will inherit its parent's data (if available). Returns a fresh selection consisting of the newly-inserted children.
642 | * @param name the function to compute a new child
643 | * @param before a function to determine the node to use as the next sibling
644 | */
645 | insert(name: (datum: Datum, index: number, outerIndex: number) => EventTarget, before: (datum: Datum, index: number, outerIndex: number) => EventTarget): Selection;
646 |
647 | /**
648 | * Removes the elements from the DOM. They are in a detached state and may be re-added (though there is currently no dedicated API for doing so).
649 | */
650 | remove(): Selection;
651 |
652 | /**
653 | * Retrieves the data bound to the first group in this selection.
654 | */
655 | data(): Datum[];
656 |
657 | /**
658 | * Binds data to this selection.
659 | * @param data the array of data to bind to this selection
660 | * @param key the optional function to determine the unique key for each piece of data. When unspecified, uses the index of the element.
661 | */
662 | data(data: NewDatum[], key?: (datum: NewDatum, index: number, outerIndex: number) => string): selection.Update;
663 |
664 | /**
665 | * Derives data to bind to this selection.
666 | * @param data the function to derive data. Must return an array.
667 | * @param key the optional function to determine the unique key for each data item. When unspecified, uses the index of the element.
668 | */
669 | data(data: (datum: Datum, index: number, outerIndex: number) => NewDatum[], key?: (datum: NewDatum, index: number, outerIndex: number) => string): selection.Update;
670 |
671 | /**
672 | * Filters the selection, returning only those nodes that match the given CSS selector.
673 | * @param selector the CSS selector
674 | */
675 | filter(selector: string): Selection;
676 |
677 | /**
678 | * Filters the selection, returning only those nodes for which the given function returned true.
679 | * @param selector the filter function
680 | */
681 | filter(selector: (datum: Datum, index: number, outerIndex: number) => boolean): Selection;
682 |
683 | /**
684 | * Return the data item bound to the first element in the selection.
685 | */
686 | datum(): Datum;
687 |
688 | /**
689 | * Derive the data item for each node in the selection. Useful for situations such as the HTML5 'dataset' attribute.
690 | * @param value the function to compute data for each node
691 | */
692 | datum(value: (datum: Datum, index: number, outerIndex: number) => NewDatum): Selection;
693 |
694 | /**
695 | * Set the data item for each node in the selection.
696 | * @param value the constant element to use for each node
697 | */
698 | datum(value: NewDatum): Selection;
699 |
700 | /**
701 | * Reorders nodes in the selection based on the given comparator. Nodes are re-inserted into the document once sorted.
702 | * @param comparator the comparison function, which defaults to d3.ascending
703 | */
704 | sort(comparator?: (a: Datum, b: Datum) => number): Selection;
705 |
706 | /**
707 | * Reorders nodes in the document to match the selection order. More efficient than calling sort() if the selection is already ordered.
708 | */
709 | order(): Selection;
710 |
711 | /**
712 | * Returns the listener (if any) for the given event.
713 | * @param type the type of event to load the listener for. May have a namespace (e.g., ".foo") at the end.
714 | */
715 | on(type: string): (datum: Datum, index: number, outerIndex: number) => any;
716 |
717 | /**
718 | * Adds a listener for the specified event. If one was already registered, it is removed before the new listener is added. The return value of the listener function is ignored.
719 | * @param type the of event to listen to. May have a namespace (e.g., ".foo") at the end.
720 | * @param listener an event listener function, or null to unregister
721 | * @param capture sets the DOM useCapture flag
722 | */
723 | on(type: string, listener: (datum: Datum, index: number, outerIndex: number) => any, capture?: boolean): Selection;
724 |
725 | /**
726 | * Begins a new transition. Interrupts any active transitions of the same name.
727 | * @param name the transition name (defaults to "")
728 | */
729 | transition(name?: string): Transition;
730 |
731 | /**
732 | * Interrupts the active transition of the provided name. Does not cancel scheduled transitions.
733 | * @param name the transition name (defaults to "")
734 | */
735 | interrupt(name?: string): Selection;
736 |
737 | /**
738 | * Creates a subselection by finding the first descendent matching the selector string. Bound data is inherited.
739 | * @param selector the CSS selector to match against
740 | */
741 | select(selector: string): Selection;
742 |
743 | /**
744 | * Creates a subselection by using a function to find descendent elements. Bound data is inherited.
745 | * @param selector the function to find matching descendants
746 | */
747 | select(selector: (datum: Datum, index: number, outerIndex: number) => EventTarget): Selection;
748 |
749 | /**
750 | * Creates a subselection by finding all descendents that match the given selector. Bound data is not inherited.
751 | * @param selector the CSS selector to match against
752 | */
753 | selectAll(selector: string): Selection;
754 |
755 | /**
756 | * Creates a subselection by finding all descendants that match the given selector. Bound data is not inherited.
757 | *
758 | * Use this overload when data-binding a subselection (that is, sel.selectAll('.foo').data(d => ...)). The type will carry over.
759 | */
760 | selectAll(selector: string): Selection;
761 |
762 | /**
763 | * Creates a subselection by using a function to find descendent elements. Bound data is not inherited.
764 | * @param selector the function to find matching descendents
765 | */
766 | selectAll(selector: (datum: Datum, index: number, outerIndex: number) => Array | NodeList): Selection;
767 |
768 | /**
769 | * Creates a subselection by using a function to find descendent elements. Bound data is not inherited.
770 | *
771 | * Use this overload when data-binding a subselection (that is, sel.selectAll('.foo').data(d => ...)). The type will carry over.
772 | * @param selector the function to find matching descendents
773 | */
774 | selectAll(selector: (datum: Datum, index: number, outerIndex: number) => Array | NodeList): Selection;
775 |
776 | /**
777 | * Invoke the given function for each element in the selection. The return value of the function is ignored.
778 | * @param func the function to invoke
779 | */
780 | each(func: (datum: Datum, index: number, outerIndex: number) => any): Selection;
781 |
782 | /**
783 | * Call a function on the selection. sel.call(foo) is equivalent to foo(sel).
784 | * @param func the function to call on the selection
785 | * @param args any optional args
786 | */
787 | call(func: (sel: Selection, ...args: any[]) => any, ...args: any[]): Selection;
788 |
789 | /**
790 | * Returns true if the current selection is empty.
791 | */
792 | empty(): boolean;
793 |
794 | /**
795 | * Returns the first non-null element in the selection, or null otherwise.
796 | */
797 | node(): MyNode;
798 |
799 | /**
800 | * Returns the total number of elements in the selection.
801 | */
802 | size(): number;
803 | }
804 |
805 | export function transition(): Transition;
806 | namespace transition {
807 | export var prototype: Transition;
808 | }
809 |
810 | interface Transition {
811 |
812 | transition(): Transition;
813 |
814 | delay(): number;
815 | delay(delay: number): Transition;
816 | delay(delay: (datum: Datum, index: number, outerIndex: number) => number): Transition;
817 |
818 | duration(): number;
819 | duration(duration: number): Transition;
820 | duration(duration: (datum: Datum, index: number, outerIndex: number) => number): Transition;
821 |
822 | ease(): (t: number) => number;
823 | ease(value: string, ...args: any[]): Transition;
824 | ease(value: (t: number) => number): Transition;
825 |
826 | attr(name: string, value: Primitive): Transition;
827 | attr(name: string, value: (datum: Datum, index: number, outerIndex: number) => Primitive): Transition;
828 | attr(obj: { [key: string]: Primitive | ((datum: Datum, index: number, outerIndex: number) => Primitive) }): Transition;
829 |
830 | attrTween(name: string, tween: (datum: Datum, index: number, attr: string) => (t: number) => Primitive): Transition;
831 |
832 | style(name: string, value: Primitive, priority?: string): Transition;
833 | style(name: string, value: (datum: Datum, index: number, outerIndex: number) => Primitive, priority?: string): Transition;
834 | style(obj: { [key: string]: Primitive | ((datum: Datum, index: number, outerIndex: number) => Primitive) }, priority?: string): Transition;
835 |
836 | styleTween(name: string, tween: (datum: Datum, index: number, attr: string) => (t: number) => Primitive, priority?: string): Transition;
837 |
838 | text(value: Primitive): Transition;
839 | text(value: (datum: Datum, index: number, outerIndex: number) => Primitive): Transition;
840 |
841 | tween(name: string, factory: () => (t: number) => any): Transition;
842 |
843 | remove(): Transition;
844 |
845 | select(selector: string): Transition;
846 | select(selector: (d: Datum, i: number) => EventTarget): Transition;
847 |
848 | selectAll(selector: string): Transition;
849 | selectAll(selector: (d: Datum, i: number) => EventTarget[]): Transition;
850 |
851 | filter(selector: string): Transition;
852 | filter(selector: (d: Datum, i: number) => boolean): Transition;
853 |
854 | each(type: string, listener: (d: Datum, i: number) => any): Transition;
855 | each(listener: (d: Datum, i: number) => any): Transition;
856 |
857 | call(func: (transition: Transition, ...args: any[]) => any, ...args: any[]): Transition;
858 |
859 | empty(): boolean;
860 | node(): MyNode;
861 | size(): number;
862 | }
863 |
864 | export function ease(type: 'linear'): (t: number) => number;
865 | export function ease(type: 'linear-in'): (t: number) => number;
866 | export function ease(type: 'linear-out'): (t: number) => number;
867 | export function ease(type: 'linear-in-out'): (t: number) => number;
868 | export function ease(type: 'linear-out-in'): (t: number) => number;
869 |
870 | export function ease(type: 'poly', k: number): (t: number) => number;
871 | export function ease(type: 'poly-in', k: number): (t: number) => number;
872 | export function ease(type: 'poly-out', k: number): (t: number) => number;
873 | export function ease(type: 'poly-in-out', k: number): (t: number) => number;
874 | export function ease(type: 'poly-out-in', k: number): (t: number) => number;
875 |
876 | export function ease(type: 'quad'): (t: number) => number;
877 | export function ease(type: 'quad-in'): (t: number) => number;
878 | export function ease(type: 'quad-out'): (t: number) => number;
879 | export function ease(type: 'quad-in-out'): (t: number) => number;
880 | export function ease(type: 'quad-out-in'): (t: number) => number;
881 |
882 | export function ease(type: 'cubic'): (t: number) => number;
883 | export function ease(type: 'cubic-in'): (t: number) => number;
884 | export function ease(type: 'cubic-out'): (t: number) => number;
885 | export function ease(type: 'cubic-in-out'): (t: number) => number;
886 | export function ease(type: 'cubic-out-in'): (t: number) => number;
887 |
888 | export function ease(type: 'sin'): (t: number) => number;
889 | export function ease(type: 'sin-in'): (t: number) => number;
890 | export function ease(type: 'sin-out'): (t: number) => number;
891 | export function ease(type: 'sin-in-out'): (t: number) => number;
892 | export function ease(type: 'sin-out-in'): (t: number) => number;
893 |
894 | export function ease(type: 'circle'): (t: number) => number;
895 | export function ease(type: 'circle-in'): (t: number) => number;
896 | export function ease(type: 'circle-out'): (t: number) => number;
897 | export function ease(type: 'circle-in-out'): (t: number) => number;
898 | export function ease(type: 'circle-out-in'): (t: number) => number;
899 |
900 | export function ease(type: 'elastic', a?: number, b?: number): (t: number) => number;
901 | export function ease(type: 'elastic-in', a?: number, b?: number): (t: number) => number;
902 | export function ease(type: 'elastic-out', a?: number, b?: number): (t: number) => number;
903 | export function ease(type: 'elastic-in-out', a?: number, b?: number): (t: number) => number;
904 | export function ease(type: 'elastic-out-in', a?: number, b?: number): (t: number) => number;
905 |
906 | export function ease(type: 'back', s: number): (t: number) => number;
907 | export function ease(type: 'back-in', s: number): (t: number) => number;
908 | export function ease(type: 'back-out', s: number): (t: number) => number;
909 | export function ease(type: 'back-in-out', s: number): (t: number) => number;
910 | export function ease(type: 'back-out-in', s: number): (t: number) => number;
911 |
912 | export function ease(type: 'bounce'): (t: number) => number;
913 | export function ease(type: 'bounce-in'): (t: number) => number;
914 | export function ease(type: 'bounce-out'): (t: number) => number;
915 | export function ease(type: 'bounce-in-out'): (t: number) => number;
916 | export function ease(type: 'bounce-out-in'): (t: number) => number;
917 |
918 | export function ease(type: string, ...args: any[]): (t: number) => number;
919 |
920 | export function timer(func: () => any, delay?: number, time?: number): void;
921 |
922 | namespace timer {
923 | export function flush(): void;
924 | }
925 |
926 | interface BaseEvent {
927 | type: string;
928 | sourceEvent?: Event;
929 | }
930 |
931 | /**
932 | * Define a D3-specific ZoomEvent per https://github.com/mbostock/d3/wiki/Zoom-Behavior#event
933 | */
934 | interface ZoomEvent extends BaseEvent {
935 | scale: number;
936 | translate: [number, number];
937 | }
938 |
939 | /**
940 | * Define a D3-specific DragEvent per https://github.com/mbostock/d3/wiki/Drag-Behavior#on
941 | */
942 | interface DragEvent extends BaseEvent {
943 | x: number;
944 | y: number;
945 | dx: number;
946 | dy: number;
947 | }
948 |
949 | interface MEvent extends MouseEvent {
950 | pageX : number;
951 | pageY : number;
952 | }
953 |
954 | /**
955 | * The current event's value. Use this variable in a handler registered with `selection.on`.
956 | */
957 | export var event: MEvent;
958 |
959 | /**
960 | * Returns the x and y coordinates of the mouse relative to the provided container element, using d3.event for the mouse's position on the page.
961 | * @param container the container element (e.g. an SVG element)
962 | */
963 | export function mouse(container: EventTarget): [number, number];
964 |
965 | /**
966 | * Given a container element and a touch identifier, determine the x and y coordinates of the touch.
967 | * @param container the container element (e.g., an SVG