/
index.d.ts
1133 lines (1054 loc) · 61.4 KB
/
index.d.ts
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
// Type definitions for D3JS d3-selection module 3.0
// Project: https://github.com/d3/d3-selection/, https://d3js.org/d3-selection
// Definitions by: Tom Wanzek <https://github.com/tomwanzek>
// Alex Ford <https://github.com/gustavderdrache>
// Boris Yankov <https://github.com/borisyankov>
// denisname <https://github.com/denisname>
// Nathan Bierema <https://github.com/Methuselah96>
// Ambar Mutha <https://github.com/ambar-arkin>
// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
// Last module patch version validated against: 3.0.0
// --------------------------------------------------------------------------
// Shared Type Definitions and Interfaces
// --------------------------------------------------------------------------
/**
* BaseType serves as an alias for the 'minimal' data type which can be selected
* without 'd3-selection' trying to use properties internally which would otherwise not
* be supported.
*/
export type BaseType = Element | EnterElement | Document | Window | null;
/**
* KeyType serves as alias for valid types that d3 supports as key for data binding
*/
export type KeyType = string | number;
/**
* A helper interface which covers arguments like NodeListOf<T> or HTMLCollectionOf<T>
* argument types
*/
export interface ArrayLike<T> {
length: number;
item(index: number): T | null;
[index: number]: T;
}
/**
* An interface describing the element type of the Enter Selection group elements
* created when invoking selection.enter().
*/
export interface EnterElement {
ownerDocument: Document;
namespaceURI: string;
appendChild(newChild: Node): Node;
insertBefore(newChild: Node, refChild: Node): Node;
querySelector(selectors: string): Element;
querySelectorAll(selectors: string): NodeListOf<Element>;
}
/**
* Container element type usable for mouse/touch functions
*/
export type ContainerElement = HTMLElement | SVGSVGElement | SVGGElement;
/**
* A User interface event (e.g. mouse event, touch or MSGestureEvent) with captured clientX and clientY properties.
*/
export interface ClientPointEvent {
clientX: number;
clientY: number;
}
/**
* Interface for optional parameters map, when dispatching custom events
* on a selection
*/
export interface CustomEventParameters {
/**
* If true, the event is dispatched to ancestors in reverse tree order
*/
bubbles: boolean;
/**
* If true, event.preventDefault is allowed
*/
cancelable: boolean;
/**
* Any custom data associated with the event
*/
detail: any;
}
/**
* Callback type for selections and transitions
*/
export type ValueFn<T extends BaseType, Datum, Result> = (this: T, datum: Datum, index: number, groups: T[] | ArrayLike<T>) => Result;
/**
* TransitionLike is a helper interface to represent a quasi-Transition, without specifying the full Transition interface in this file.
* For example, wherever d3-zoom allows a Transition to be passed in as an argument, it internally immediately invokes its `selection()`
* method to retrieve the underlying Selection object before proceeding.
* d3-brush uses a subset of Transition methods internally.
* The use of this interface instead of the full imported Transition interface is [referred] to achieve
* two things:
* (1) the d3-transition module may not be required by a projects use case,
* (2) it avoids possible complications from 'module augmentation' from d3-transition to Selection.
*/
export interface TransitionLike<GElement extends BaseType, Datum> {
selection(): Selection<GElement, Datum, any, any>;
on(type: string, listener: null): TransitionLike<GElement, Datum>;
on(type: string, listener: ValueFn<GElement, Datum, void>): TransitionLike<GElement, Datum>;
tween(name: string, tweenFn: null): TransitionLike<GElement, Datum>;
tween(name: string, tweenFn: ValueFn<GElement, Datum, ((t: number) => void)>): TransitionLike<GElement, Datum>;
}
// --------------------------------------------------------------------------
// All Selection related interfaces and function
// --------------------------------------------------------------------------
/**
* Select the first element that matches the specified selector string. If no elements match the selector, returns an empty selection.
* If multiple elements match the selector, only the first matching element (in document order) will be selected.
*
* The first generic "GElement" refers to the type of element to be selected. The second generic "OldDatum" refers to the type of the
* datum, on the selected element. This is useful when re-selecting an element with a previously set, know datum type.
*
* @param selector CSS selector string
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function select<GElement extends BaseType, OldDatum>(selector: string): Selection<GElement, OldDatum, HTMLElement, any>;
/**
* Select the specified node element.
*
* The first generic "GElement" refers to the type of element to be selected. The second generic "OldDatum" refers to the type of the
* datum, on the selected element. This is useful when re-selecting an element with a previously set, know datum type.
*
* @param node An element to be selected
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function select<GElement extends BaseType, OldDatum>(node: GElement): Selection<GElement, OldDatum, null, undefined>;
/**
* Create an empty selection.
*/
export function selectAll(selector?: null): Selection<null, undefined, null, undefined>;
/**
* Select all elements that match the specified selector string. The elements will be selected in document order (top-to-bottom).
* If no elements in the document match the selector, returns an empty selection.
*
* The first generic "GElement" refers to the type of element to be selected. The second generic "OldDatum" refers to the type of the
* datum, of a selected element. This is useful when re-selecting elements with a previously set, know datum type.
*
* @param selector CSS selector string
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function selectAll<GElement extends BaseType, OldDatum>(selector: string): Selection<GElement, OldDatum, HTMLElement, any>;
/**
* Select the specified array, array-like, or iterable of nodes.
* This is useful if you already have a reference to nodes, such as `this.childNodes` within an event listener or a global such as `document.links`.
* The nodes may instead be an iterable, or a pseudo-array such as a NodeList.
*
* The first generic "GElement" refers to the type of element to be selected.
* The second generic "OldDatum" refers to the type of the datum, of a selected element.
*
* @param nodes An array, array-like, or iterable of nodes
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
export function selectAll<GElement extends BaseType, OldDatum>(nodes: GElement[] | ArrayLike<GElement> | Iterable<GElement>): Selection<GElement, OldDatum, null, undefined>;
/**
* A D3 Selection of elements.
*
* The first generic "GElement" refers to the type of the selected element(s).
* The second generic "Datum" refers to the type of the datum of a selected element(s).
* The third generic "PElement" refers to the type of the parent element(s) in the D3 selection.
* The fourth generic "PDatum" refers to the type of the datum of the parent element(s).
*/
export interface Selection<GElement extends BaseType, Datum, PElement extends BaseType, PDatum> {
// Sub-selection -------------------------
/**
* For each selected element, select the first descendant element that matches the specified selector string.
* If no element matches the specified selector for the current element, the element at the current index will
* be null in the returned selection. If multiple elements match the selector, only the first matching element
* in document order is selected. Selection.select does not affect grouping: it preserves the existing group
* structure and indexes, and propagates data (if any) to selected children.
*
* If the current element has associated data, this data is propagated to the
* corresponding selected element.
*
* The generic represents the type of the descendant element to be selected.
*
* @param selector CSS selector string
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
select<DescElement extends BaseType>(selector: string): Selection<DescElement, Datum, PElement, PDatum>;
/**
* Create an empty sub-selection. Selection.select does not affect grouping: it preserves the existing group
* structure and indexes.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
select<DescElement extends BaseType>(selector: null): Selection<null, undefined, PElement, PDatum>;
/**
* For each selected element, select the descendant element returned by the selector function.
* If no element is returned by the selector function for the current element, the element at the
* current index will be null in the returned selection. Selection.select does not affect grouping:
* it preserves the existing group structure and indexes, and propagates data (if any) to selected children.
*
* If the current element has associated data, this data is propagated to the
* corresponding selected element.
*
* The generic represents the type of the descendant element to be selected.
*
* @param selector A selector function, which is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]).
* It must return an element, or null if there is no matching element.
*/
select<DescElement extends BaseType>(selector: ValueFn<GElement, Datum, DescElement>): Selection<DescElement, Datum, PElement, PDatum>;
/**
* Create an empty sub-selection. Selection.selectAll does affect grouping: The elements in the returned
* selection are grouped by their corresponding parent node in this selection, the group at the current index will be empty.
*/
selectAll(selector?: null): Selection<null, undefined, GElement, Datum>;
/**
* For each selected element, selects the descendant elements that match the specified selector string. The elements in the returned
* selection are grouped by their corresponding parent node in this selection. If no element matches the specified selector
* for the current element, the group at the current index will be empty. Selection.selectAll does affect grouping: each selected descendant
* is grouped by the parent element in the originating selection.
*
* The selected elements do not inherit data from this selection; use selection.data to propagate data to children.
*
* The first generic "DescElement" refers to the type of descendant element to be selected. The second generic "OldDatum" refers to the type of the
* datum, of a selected element. This is useful when re-selecting elements with a previously set, know datum type.
*
* @param selector CSS selector string
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
selectAll<DescElement extends BaseType, OldDatum>(selector: string): Selection<DescElement, OldDatum, GElement, Datum>;
/**
* For each selected element, selects the descendant elements returned by the selector function. The elements in the returned
* selection are grouped by their corresponding parent node in this selection. If no element matches the specified selector
* for the current element, the group at the current index will be empty. Selection.selectAll does affect grouping: each selected descendant
* is grouped by the parent element in the originating selection.
*
* The selected elements do not inherit data from this selection; use selection.data to propagate data to children.
*
* The first generic "DescElement" refers to the type of descendant element to be selected. The second generic "OldDatum" refers to the type of the
* datum, of a selected element. This is useful when re-selecting elements with a previously set, know datum type.
*
* @param selector A selector function which is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). It must return an array of elements
* (or an iterable, or a pseudo-array, such as a NodeList), or the empty array if there are no matching elements.
*/
selectAll<DescElement extends BaseType, OldDatum>(
selector: ValueFn<GElement, Datum, DescElement[] | ArrayLike<DescElement> | Iterable<DescElement>>
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
): Selection<DescElement, OldDatum, GElement, Datum>;
/**
* Filters the selection, returning a new selection that contains only the elements for
* which the specified filter is true.
*
* The returned filtered selection preserves the parents of this selection, but like array.filter,
* it does not preserve indexes as some elements may be removed; use selection.select to preserve the index, if needed.
*
* @param selector A CSS selector string to match when filtering.
*/
filter(selector: string): Selection<GElement, Datum, PElement, PDatum>;
/**
* Filters the selection, returning a new selection that contains only the elements for
* which the specified filter is true.
*
* The returned filtered selection preserves the parents of this selection, but like array.filter,
* it does not preserve indexes as some elements may be removed; use selection.select to preserve the index, if needed.
*
* The generic refers to the type of element which will be selected after applying the filter, i.e. if the element types
* contained in a pre-filter selection are narrowed to a subset as part of the filtering.
*
* @param selector A CSS selector string to match when filtering.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
filter<FilteredElement extends BaseType>(selector: string): Selection<FilteredElement, Datum, PElement, PDatum>;
/**
* Filter the selection, returning a new selection that contains only the elements for
* which the specified filter is true.
*
* The returned filtered selection preserves the parents of this selection, but like array.filter,
* it does not preserve indexes as some elements may be removed; use selection.select to preserve the index, if needed.
*
* @param selector A value function which is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). This function should return true
* for an element to be included, and false otherwise.
*/
filter(selector: ValueFn<GElement, Datum, boolean>): Selection<GElement, Datum, PElement, PDatum>;
/**
* Filter the selection, returning a new selection that contains only the elements for
* which the specified filter is true.
*
* The returned filtered selection preserves the parents of this selection, but like array.filter,
* it does not preserve indexes as some elements may be removed; use selection.select to preserve the index, if needed.
*
* @param selector A value function which is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). This function should return true
* for an element to be included, and false otherwise.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
filter<FilteredElement extends BaseType>(selector: ValueFn<GElement, Datum, boolean>): Selection<FilteredElement, Datum, PElement, PDatum>;
/**
* Returns a new selection merging this selection with the specified other selection or transition.
* The returned selection has the same number of groups and the same parents as this selection.
* Any missing (null) elements in this selection are filled with the corresponding element,
* if present (not null), from the specified selection. (If the other selection has additional groups or parents,
* they are ignored.)
*
* This method is commonly used to merge the enter and update selections after a data-join.
* After modifying the entering and updating elements separately, you can merge the two selections and
* perform operations on both without duplicate code.
*
* This method is not intended for concatenating arbitrary selections, however: if both this selection
* and the specified other selection have (non-null) elements at the same index, this selection’s element
* is returned in the merge and the other selection’s element is ignored.
*
* @param other Selection to be merged.
*/
merge(other: Selection<GElement, Datum, PElement, PDatum> | TransitionLike<GElement, Datum>): Selection<GElement, Datum, PElement, PDatum>;
/**
* Returns a new selection with the (first) child of each element of the current selection matching the selector.
* Selects the first child that matches (if any).
*
* The generic represents the type of the descendant element to be selected.
*
* @param selector CSS selector string
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
selectChild<DescElement extends BaseType>(selector?: string): Selection<DescElement, Datum, PElement, PDatum>;
/**
* Returns a new selection with the (first) child of each element of the current selection matching the selector.
*
* The first generic represents the type of the descendant element to be selected.
* The second generic represents the type of any of the child elements.
*
* @param selector A selector function, which is evaluated for each of the children nodes, in order, being passed the child (child), the child’s index (i), and the list of children (children);
* the method selects the first child for which the selector return truthy, if any.
*/
selectChild<ResultElement extends BaseType, ChildElement extends BaseType>(
selector: (child: ChildElement, i: number, children: ChildElement[]) => boolean
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
): Selection<ResultElement, Datum, PElement, PDatum>;
/**
* Returns a new selection with the children of each element of the current selection matching the selector.
* Selects the children that match (if any)
*
* The first generic represents the type of the descendant element to be selected.
* The second generic refers to the type of the datum of the element to be selected.
*
* @param selector CSS selector string
*/
selectChildren<DescElement extends BaseType, OldDatum>(
selector?: string
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
): Selection<DescElement, OldDatum, GElement, Datum>;
/**
* Returns a new selection with the children of each element of the current selection matching the selector.
*
* The first generic represents the type of the descendant element to be selected.
* The second generic refers to the type of the datum of the element to be selected.
* The third generic represents the type of any of the child elements.
*
* @param selector A selector function, which is evaluated for each of the children nodes, in order, being passed the child (child), the child’s index (i), and the list of children (children);
* the method selects the first child for which the selector return truthy, if any.
*/
selectChildren<ResultElement extends BaseType, ResultDatum, ChildElement extends BaseType>(
selector: (child: ChildElement, i: number, children: ChildElement[]) => boolean
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
): Selection<ResultElement, ResultDatum, GElement, Datum>;
/**
* Returns the selection (for symmetry with transition.selection).
*/
selection(): this;
// Modifying -------------------------------
/**
* Return the current value of the specified attribute for the first (non-null) element in the selection.
* This is generally useful only if you know that the selection contains exactly one element.
*
* @param name Name of the attribute
*/
attr(name: string): string;
/**
* Sets the attribute with the specified name to the specified value on the selected elements and returns this selection.
* If the value is a constant, all elements are given the same attribute value;
* otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]).
* The function’s return value is then used to set each element’s attribute.
* A null value will remove the specified attribute.
*/
attr(name: string, value: null | string | number | boolean | ReadonlyArray<string | number> | ValueFn<GElement, Datum, null | string | number | boolean | ReadonlyArray<string | number>>): this;
/**
* Returns true if and only if the first (non-null) selected element has the specified classes.
* This is generally useful only if you know the selection contains exactly one element.
*
* @param names A string of space-separated class names.
*/
classed(names: string): boolean;
/**
* Assigns or unassigns the specified CSS class names on the selected elements by setting
* the class attribute or modifying the classList property and returns this selection.
* If the constant value is truthy, then all elements are assigned the specified classes; otherwise, the classes are unassigned.
*
* @param names A string of space-separated class names.
* @param value A boolean flag (true = assign / false = unassign)
*/
classed(names: string, value: boolean): this;
/**
* Assigns or unassigns the specified CSS class names on the selected elements by setting
* the class attribute or modifying the classList property and returns this selection.
* The assign/unassign status for the individual selected elements is determined by the boolean return
* value of the value function.
*
* @param names A string of space-separated class names.
* @param value A value function which is evaluated for each selected element, in order,
* being passed the current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]).
* The function’s return value is then used to assign or unassign classes on each element.
*/
classed(names: string, value: ValueFn<GElement, Datum, boolean>): this;
/**
* Returns the current value of the specified style property for the first (non-null) element in the selection.
* The current value is defined as the element’s inline value, if present, and otherwise its computed value.
* Accessing the current style value is generally useful only if you know the selection contains exactly one element.
*
* @param name Name of the style
*/
style(name: string): string;
/**
* Clear the style with the specified name for the selected elements and returns this selection.
*
* @param name Name of the style
* @param value null,to clear the style
*/
style(name: string, value: null): this;
/**
* Sets the value of the style with the specified name for the selected elements and returns this selection.
* All elements are given the same style value.
*
* @param name Name of the style
* @param value Constant value for the style
* @param priority An optional priority flag, either null or the string important (without the exclamation point)
*/
style(name: string, value: string | number | boolean, priority?: null | 'important'): this;
/**
* Sets the value of the style with the specified name for the selected elements and returns this selection.
* The value for the individual selected elements is determined by the value function.
*
* @param name Name of the style
* @param value A value function which is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). A null value will clear the style.
* @param priority An optional priority flag, either null or the string important (without the exclamation point)
*/
style(name: string, value: ValueFn<GElement, Datum, string | number | boolean | null>, priority?: null | 'important'): this;
/**
* Return the current value of the specified property for the first (non-null) element in the selection.
* This is generally useful only if you know that the selection contains exactly one element.
*
* @param name Name of the property
*/
property(name: string): any;
/**
* Look up a local variable on the first node of this selection. Note that this is not equivalent to `local.get(selection.node())` in that it will not look up locals set on the parent node(s).
*
* @param name The `d3.local` variable to look up.
*/
property<T>(name: Local<T>): T | undefined;
/**
* Sets the property with the specified name to the specified value on selected elements.
* If the value is a constant, then all elements are given the same property value;
* otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]).
* The function’s return value is then used to set each element’s property. A null value will delete the specified property.
*/
property(name: string, value: ValueFn<GElement, Datum, any> | null): this;
/**
* Sets the value of the property with the specified name for the selected elements and returns this selection.
* All elements are given the same property value.
*
* @param name Name of the property
* @param value Constant value for the property
*/
property(name: string, value: any): this;
/**
* Store a value in a `d3.local` variable.
* This is equivalent to `selection.each(function (d, i, g) { name.set(this, value.call(this, d, i, g)); })` but more concise.
*
* @param name A `d3.local` variable
* @param value A callback that returns the value to store
*/
property<T>(name: Local<T>, value: ValueFn<GElement, Datum, T>): this;
/**
* Store a value in a `d3.local` variable for each node in the selection.
* This is equivalent to `selection.each(function () { name.set(this, value); })` but more concise.
*
* @param name A `d3.local` variable
* @param value A callback that returns the value to store
*/
property<T>(name: Local<T>, value: T): this;
/**
* Returns the text content for the first (non-null) element in the selection.
* This is generally useful only if you know the selection contains exactly one element.
*/
text(): string;
/**
* Sets the text content to the specified value on all selected elements, replacing any existing child elements.
* If the value is a constant, then all elements are given the same text content;
* otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]).
* The function’s return value is then used to set each element’s text content.
* A null value will clear the content.
*/
text(value: null | string | number | boolean | ValueFn<GElement, Datum, string | number | boolean | null>): this;
/**
* Returns a string representation of the inner HTML for the first (non-null) element in the selection.
* This is generally useful only if you know the selection contains exactly one element.
*/
html(): string;
/**
* Sets the inner HTML to the specified value on all selected elements, replacing any existing child elements.
* If the value is a constant, then all elements are given the same inner HTML;
* otherwise, if the value is a function, it is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]).
* The function’s return value is then used to set each element’s inner HTML.
* A null value will clear the content.
*/
html(value: null | string | ValueFn<GElement, Datum, string | null>): this;
/**
* Appends a new element of this type (tag name) as the last child of each selected element,
* or before the next following sibling in the update selection if this is an enter selection.
* The latter behavior for enter selections allows you to insert elements into the DOM in an order consistent with the new bound data;
* however, note that selection.order may still be required if updating elements change order
* (i.e., if the order of new data is inconsistent with old data).
*
* This method returns a new selection containing the appended elements.
* Each new element inherits the data of the current elements, if any.
*
* @param type A string representing the tag name.
*/
append<K extends keyof ElementTagNameMap>(type: K): Selection<ElementTagNameMap[K], Datum, PElement, PDatum>;
/**
* Appends a new element of this type (tag name) as the last child of each selected element,
* or before the next following sibling in the update selection if this is an enter selection.
* The latter behavior for enter selections allows you to insert elements into the DOM in an order consistent with the new bound data;
* however, note that selection.order may still be required if updating elements change order
* (i.e., if the order of new data is inconsistent with old data).
*
* This method returns a new selection containing the appended elements.
* Each new element inherits the data of the current elements, if any.
*
* The generic refers to the type of the child element to be appended.
*
* @param type A string representing the tag name. The specified name may have a namespace prefix, such as svg:text
* to specify a text attribute in the SVG namespace. If no namespace is specified, the namespace will be inherited
* from the parent element; or, if the name is one of the known prefixes, the corresponding namespace will be used
* (for example, svg implies svg:svg)
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
append<ChildElement extends BaseType>(type: string): Selection<ChildElement, Datum, PElement, PDatum>;
/**
* Appends a new element of the type provided by the element creator function as the last child of each selected element,
* or before the next following sibling in the update selection if this is an enter selection.
* The latter behavior for enter selections allows you to insert elements into the DOM in an order consistent with the new bound data;
* however, note that selection.order may still be required if updating elements change order
* (i.e., if the order of new data is inconsistent with old data).
*
* This method returns a new selection containing the appended elements.
* Each new element inherits the data of the current elements, if any.
*
* The generic refers to the type of the child element to be appended.
*
* @param type A creator function which is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). This function should return
* an element to be appended. (The function typically creates a new element, but it may instead return an existing element.)
*/
append<ChildElement extends BaseType>(type: ValueFn<GElement, Datum, ChildElement>): Selection<ChildElement, Datum, PElement, PDatum>;
/**
* Inserts a new element of the specified type (tag name) before the first element matching the specified
* before selector for each selected element. For example, a before selector :first-child will prepend nodes before the first child.
* If before is not specified, it defaults to null. (To append elements in an order consistent with bound data, use selection.append.)
*
* This method returns a new selection containing the appended elements.
* Each new element inherits the data of the current elements, if any.
*
* The generic refers to the type of the child element to be appended.
*
* @param type A string representing the tag name for the element type to be inserted.
* @param before One of:
* * A CSS selector string for the element before which the insertion should occur.
* * A child selector function which is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). This function should return the child element
* before which the element should be inserted.
*/
insert<K extends keyof ElementTagNameMap>(
type: K,
before?: string | ValueFn<GElement, Datum, BaseType>
): Selection<ElementTagNameMap[K], Datum, PElement, PDatum>;
/**
* Inserts a new element of the specified type (tag name) before the first element matching the specified
* before selector for each selected element. For example, a before selector :first-child will prepend nodes before the first child.
* If before is not specified, it defaults to null. (To append elements in an order consistent with bound data, use selection.append.)
*
* This method returns a new selection containing the appended elements.
* Each new element inherits the data of the current elements, if any.
*
* The generic refers to the type of the child element to be appended.
*
* @param type One of:
* * A string representing the tag name for the element type to be inserted. The specified name may have a namespace prefix,
* such as svg:text to specify a text attribute in the SVG namespace. If no namespace is specified, the namespace will be inherited
* from the parent element; or, if the name is one of the known prefixes, the corresponding namespace will be used
* (for example, svg implies svg:svg)
* * A creator function which is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). This function should return
* an element to be inserted. (The function typically creates a new element, but it may instead return an existing element.)
* @param before One of:
* * A CSS selector string for the element before which the insertion should occur.
* * A child selector function which is evaluated for each selected element, in order, being passed the current datum (d),
* the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]). This function should return the child element
* before which the element should be inserted.
*/
insert<ChildElement extends BaseType>(
type: string | ValueFn<GElement, Datum, ChildElement>,
before?: string | ValueFn<GElement, Datum, BaseType>
): Selection<ChildElement, Datum, PElement, PDatum>;
/**
* Removes the selected elements from the document.
* Returns this selection (the removed elements) which are now detached from the DOM.
*/
remove(): this;
/**
* Inserts clones of the selected elements immediately following the selected elements and returns a selection of the newly
* added clones. If deep is true, the descendant nodes of the selected elements will be cloned as well. Otherwise, only the elements
* themselves will be cloned.
*
* @param deep Perform deep cloning if this flag is set to true.
*/
clone(deep?: boolean): Selection<GElement, Datum, PElement, PDatum>;
/**
* Return a new selection that contains a copy of each group in this selection sorted according
* to the compare function. After sorting, re-inserts elements to match the resulting order (per selection.order).
*
* Note that sorting is not guaranteed to be stable; however, it is guaranteed to have the same
* behavior as your browser’s built-in sort method on arrays.
*
* @param comparator An optional comparator function, which defaults to "ascending". The function is passed
* two elements’ data a and b to compare. It should return either a negative, positive, or zero value.
* If negative, then a should be before b; if positive, then a should be after b; otherwise, a and b are
* considered equal and the order is arbitrary.
*/
sort(comparator?: (a: Datum, b: Datum) => number): this;
/**
* Re-insert elements into the document such that the document order of each group matches the selection order.
* This is equivalent to calling selection.sort if the data is already sorted, but much faster.
*/
order(): this;
/**
* Re-insert each selected element, in order, as the last child of its parent.
*/
raise(): this;
/**
* Re-insert each selected element, in order, as the first child of its parent.
*/
lower(): this;
// Data Join ---------------------------------
/**
* Returns the array of data for the selected elements.
*/
data(): Datum[];
/**
* Joins the specified array of data with the selected elements, returning a new selection that represents
* the update selection: the elements successfully bound to data. Also defines the enter and exit selections on
* the returned selection, which can be used to add or remove elements to correspond to the new data.
*
* The data is specified for each group in the selection. If the selection has multiple groups
* (such as d3.selectAll followed by selection.selectAll), then data should typically be specified as a function.
*
* If a key function is not specified, then the first datum in data is assigned to the first selected element,
* the second datum to the second selected element, and so on.
* A key function may be specified to control which datum is assigned to which element, replacing the default join-by-index,
* by computing a string identifier for each datum and element.
*
* The update and enter selections are returned in data order, while the exit selection preserves the selection
* order prior to the join. If a key function is specified, the order of elements in the selection may not match
* their order in the document; use selection.order or selection.sort as needed.
*
* This method cannot be used to clear bound data; use selection.datum instead.
*
* For details see: {@link https://github.com/d3/d3-selection#joining-data }
*
* The generic refers to the type of the new datum to be used for the selected elements.
*
* @param data The specified data is an array or iterable of arbitrary values (e.g., numbers or objects)
* or a value function which will be evaluated for each group in order, being passed the group’s parent datum
* (d, which may be undefined), the group index (i), and the selection’s parent nodes (nodes),
* with this as the group’s parent element. The function returns an array or iterable of values for each group.
* @param key An optional key function which is evaluated for each selected element, in order, being passed the
* current datum (d), the current index (i), and the current group (nodes), with this as the current DOM element (nodes[i]); the returned string is the element’s key.
* The key function is then also evaluated for each new datum in data, being passed the current datum (d),
* the current index (i), and the group’s new data, with this as the group’s parent DOM element (nodes[i]); the returned string is the datum’s key.
* The datum for a given key is assigned to the element with the matching key. If multiple elements have the same key,
* the duplicate elements are put into the exit selection; if multiple data have the same key, the duplicate data are put into the enter selection.
*/
data<NewDatum>(
data: NewDatum[] | Iterable<NewDatum> | ValueFn<PElement, PDatum, NewDatum[] | Iterable<NewDatum>>,
key?: ValueFn<GElement | PElement, Datum | NewDatum, KeyType>
): Selection<GElement, NewDatum, PElement, PDatum>;
/**
* Appends, removes and reorders elements as necessary to match the data that was previously bound by `selection.data`, returning the merged enter and update selection.
* This method is a convenient alternative to the more explicit `selection.enter`, `selection.exit`, `selection.append` and `selection.remove`.
*
* The "matching" logic is determined by the key function passed to `selection.data`.
*/
join<K extends keyof ElementTagNameMap, OldDatum = Datum>(
enter: K,
update?: (elem: Selection<GElement, Datum, PElement, PDatum>) => Selection<GElement, Datum, PElement, PDatum> | TransitionLike<GElement, Datum> | undefined,
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
exit?: (elem: Selection<GElement, OldDatum, PElement, PDatum>) => void
): Selection<GElement | ElementTagNameMap[K], Datum, PElement, PDatum>;
/**
* Appends, removes and reorders elements as necessary to match the data that was previously bound by `selection.data`, returning the merged enter and update selection.
* This method is a convenient alternative to the more explicit `selection.enter`, `selection.exit`, `selection.append` and `selection.remove`.
*
* The "matching" logic is determined by the key function passed to `selection.data`.
*/
join<ChildElement extends BaseType, OldDatum = Datum>(
enter: string | ((elem: Selection<EnterElement, Datum, PElement, PDatum>) => Selection<ChildElement, Datum, PElement, PDatum> | TransitionLike<GElement, Datum>),
update?: (elem: Selection<GElement, Datum, PElement, PDatum>) => Selection<GElement, Datum, PElement, PDatum> | TransitionLike<GElement, Datum> | undefined,
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
exit?: (elem: Selection<GElement, OldDatum, PElement, PDatum>) => void
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
): Selection<ChildElement | GElement, Datum, PElement, PDatum>;
/**
* Return the enter selection: placeholder nodes for each datum that had no corresponding DOM element
* in the selection. (The enter selection is empty for selections not returned by selection.data.)
*/
enter(): Selection<EnterElement, Datum, PElement, PDatum>;
/**
* Returns the exit selection: existing DOM elements in the selection for which no new datum was found.
* (The exit selection is empty for selections not returned by selection.data.)
*
* IMPORTANT: The generic refers to the type of the old datum associated with the exit selection elements.
* Ensure you set the generic to the correct type, if you need to access the data on the exit selection in
* follow-up steps, e.g. to set styles as part of an exit transition before removing them.
*/
// eslint-disable-next-line @definitelytyped/no-unnecessary-generics
exit<OldDatum>(): Selection<GElement, OldDatum, PElement, PDatum>;
/**
* Returns the bound datum for the first (non-null) element in the selection.
* This is generally useful only if you know the selection contains exactly one element.
*/
datum(): Datum;
/**
* Delete the bound data for each element in the selection.
*/
datum(value: null): Selection<GElement, undefined, PElement, PDatum>;
/**
* Sets the element’s bound data using the specified value function on all selected elements.
* Unlike selection.data, this method does not compute a join and does not affect
* indexes or the enter and exit selections.
*
* The generic refers to the type of the new datum to be used for the selected elements.
*
* @param value A value function which is evaluated for each selected element, in order,
* being passed the current datum (d), the current index (i), and the current group (nodes),
* with this as the current DOM element (nodes[i]). The function is then used to set each element’s new data.
* A null value will delete the bound data.
*/
datum<NewDatum>(value: ValueFn<GElement, Datum, NewDatum>): Selection<GElement, NewDatum, PElement, PDatum>;
/**
* Sets the element’s bound data to the specified value on all selected elements.
* Unlike selection.data, this method does not compute a join and does not affect
* indexes or the enter and exit selections.
*
* The generic refers to the type of the new datum to be used for the selected elements.
*
* @param value A value object to be used as the datum for each element.
*/
datum<NewDatum>(value: NewDatum): Selection<GElement, NewDatum, PElement, PDatum>;
// Event Handling -------------------
/**
* Return the currently-assigned listener for the specified event typename on the first (non-null) selected element,
* if any, If multiple typenames are specified, the first matching listener is returned.
*
* @param typenames The typenames is a string event type, such as click, mouseover, or submit; any DOM event type supported by your browser may be used.
* The type may be optionally followed by a period (.) and a name; the optional name allows multiple callbacks to be registered
* to receive events of the same type, such as click.foo and click.bar. To specify multiple typenames, separate typenames with spaces,
* such as "input change"" or "click.foo click.bar".
*/
on(typenames: string): ((this: GElement, event: any, d: Datum) => void) | undefined;
/**
* Remove a listener for the specified event type names. To remove all listeners for a given name,
* pass null as the listener and ".foo" as the typename, where foo is the name; to remove all listeners with no name, specify "." as the typename.
*
* @param typenames The typenames is a string event type, such as click, mouseover, or submit; any DOM event type supported by your browser may be used.
* The type may be optionally followed by a period (.) and a name; the optional name allows multiple callbacks to be registered
* to receive events of the same type, such as click.foo and click.bar. To specify multiple typenames, separate typenames with spaces,
* such as "input change"" or "click.foo click.bar".
* @param listener null to indicate removal of listener
*/
on(typenames: string, listener: null): this;
/**
* Add an event listener for the specified event type names. If an event listener was previously registered for the same typename
* on a selected element, the old listener is removed before the new listener is added.
*
* When a specified event is dispatched on a selected node, the specified listener will be evaluated for each selected element.
*
* @param typenames The typenames is a string event type, such as click, mouseover, or submit; any DOM event type supported by your browser may be used.
* The type may be optionally followed by a period (.) and a name; the optional name allows multiple callbacks to be registered
* to receive events of the same type, such as click.foo and click.bar. To specify multiple typenames, separate typenames with spaces,
* such as "input change"" or "click.foo click.bar".
* @param listener A listener function which will be evaluated for each selected element,
* being passed the current event (event) and the current datum (d), with this as the current DOM element (event.currentTarget).
* Listeners always see the latest datum for their element.
* Note: while you can use event.pageX and event.pageY directly,
* it is often convenient to transform the event position to the local coordinate system of that element that received the event using d3.pointer.
* @param options An optional options object may specify characteristics about the event listener, such as wehether it is captures or passive; see element.addEventListener.
*/
on(typenames: string, listener: (this: GElement, event: any, d: Datum) => void, options?: any): this;
/**
* Dispatches a custom event of the specified type to each selected element, in order.
* An optional parameters map may be specified to set additional properties of the event.
*
* @param type Name of event to dispatch
* @param parameters An optional value map with custom event parameters
*/
dispatch(type: string, parameters?: CustomEventParameters): this;
/**
* Dispatches a custom event of the specified type to each selected element, in order.
* An optional value function returning a parameters map for each element in the selection may be specified to set additional properties of the event.
*
* @param type Name of event to dispatch
* @param parameters A value function which is evaluated for each selected element, in order,
* being passed the current datum (d), the current index (i), and the current group (nodes),
* with this as the current DOM element (nodes[i]). It must return the parameters map for the current element.
*/
dispatch(type: string, parameters?: ValueFn<GElement, Datum, CustomEventParameters>): this;
// Control Flow ----------------------
/**
* Invoke the specified function for each selected element, passing in the current datum (d),
* the current index (i), and the current group (nodes), with this of the current DOM element (nodes[i]).
* This method can be used to invoke arbitrary code for each selected element, and is useful for creating a context to access parent and child data simultaneously.
*
* @param func A function which is invoked for each selected element,
* being passed the current datum (d), the current index (i), and the current group (nodes), with this of the current DOM element (nodes[i]).
*/
each(func: ValueFn<GElement, Datum, void>): this;
/**
* Invoke the specified function exactly once, passing in this selection along with any optional arguments.
* Returns this selection.
*
* @param func A function which is passed this selection as the first argument along with any optional arguments.
* @param args List of optional arguments to be passed to the callback function.
*/
call<Args extends any[]>(func: (selection: Selection<GElement, Datum, PElement, PDatum>, ...args: Args) => void, ...args: Args): this;
/**
* Return true if this selection contains no (non-null) elements.
*/
empty(): boolean;
/**
* Return an array of all (non-null) elements in this selection.
*/
nodes(): GElement[];
/**
* Return the first (non-null) element in this selection. If the selection is empty, returns null.
*/
node(): GElement | null;
/**
* Returns the total number of elements in this selection.
*/
size(): number;
/**
* Returns an iterator over the selected (non-null) elements.
*/
[Symbol.iterator](): Iterator<GElement>;
}
/**
* Selects the root element, document.documentElement. This function can also be used to test for selections
* (instanceof d3.selection) or to extend the selection prototype.
*/
export type SelectionFn = () => Selection<HTMLElement, any, null, undefined>;
/**
* Selects the root element, document.documentElement. This function can also be used to test for selections
* (instanceof d3.selection) or to extend the selection prototype.
*/
export const selection: SelectionFn;
// ---------------------------------------------------------------------------
// pointer.js and pointers.js related
// ---------------------------------------------------------------------------
/**
* Returns a two-element array of numbers [x, y] representing the coordinates of the specified event relative to the specified target.
* event can be a MouseEvent, a PointerEvent, a Touch, or a custom event holding a UIEvent as event.sourceEvent.
*
* If target is not specified, it defaults to the source event’s currentTarget property, if available.
* If the target is an SVG element, the event’s coordinates are transformed using the inverse of the screen coordinate transformation matrix.
* If the target is an HTML element, the event’s coordinates are translated relative to the top-left corner of the target’s bounding client rectangle.
* (As such, the coordinate system can only be translated relative to the client coordinates. See also GeometryUtils.)
* Otherwise, [event.pageX, event.pageY] is returned.
*
* @param event The specified event.
* @param target The target which the coordinates are relative to.
*/
export function pointer(event: any, target?: any): [number, number];
/**
* Returns an array [[x0, y0], [x1, y1]…] of coordinates of the specified event’s pointer locations relative to the specified target.
* For touch events, the returned array of positions corresponds to the event.touches array; for other events, returns a single-element array.
*
* If target is not specified, it defaults to the source event’s currentTarget property, if any.
*
* @param event The specified event.
* @param target The target which the coordinates are relative to.
*/
export function pointers(event: any, target?: any): Array<[number, number]>;
// ---------------------------------------------------------------------------
// style
// ---------------------------------------------------------------------------
/**
* Returns the value of the style property with the specified name for the specified node.
* If the node has an inline style with the specified name, its value is returned; otherwise, the computed property value is returned.
* See also selection.style.
*
* @param node A DOM node (e.g. HTMLElement, SVGElement) for which to retrieve the style property.
* @param name Style property name.
*/
export function style(node: Element, name: string): string;
// ---------------------------------------------------------------------------
// local.js related
// ---------------------------------------------------------------------------
export interface Local<T> {
/**
* Retrieves a local variable stored on the node (or one of its parents).
*
* @param node A node element.
*/
get(node: Element): T | undefined;
/**
* Deletes the value associated with the given node. Values stored on ancestors are not affected, meaning that child nodes will still see inherited values.
*
* This function returns true if there was a value stored directly on the node, and false otherwise.
*
* @param node A node element.
*/
remove(node: Element): boolean;
/**
* Store a value for this local variable. Calling `.get()` on children of this node will also retrieve the variable's value.
*
* @param node A node element.
* @param value Value to store locally
*/
set(node: Element, value: T): T;
/**
* Obtain a string with the internally assigned property name for the local
* which is used to store the value on a node
*/
toString(): string;
}
/**
* Obtain a new local variable