Skip to content

Commit c99f0a8

Browse files
mbostockmbostock
committed
mark docs
1 parent e2f7e8e commit c99f0a8

File tree

2 files changed

+134
-34
lines changed

2 files changed

+134
-34
lines changed

‎src/mark.d.ts

Lines changed: 129 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -5,23 +5,6 @@ import type {plot} from "./plot.js";
55
import type {ScaleFunctions} from "./scales.js";
66
import type {InitializerFunction, SortOrder, TransformFunction} from "./transforms/basic.js";
77

8-
export type Facet = "auto" | "include" | "exclude" | "super";
9-
10-
export type FacetAnchor =
11-
| "top"
12-
| "right"
13-
| "bottom"
14-
| "left"
15-
| "top-left"
16-
| "top-right"
17-
| "bottom-left"
18-
| "bottom-right"
19-
| "top-empty"
20-
| "right-empty"
21-
| "bottom-empty"
22-
| "left-empty"
23-
| "empty";
24-
258
export type FrameAnchor =
269
| "middle"
2710
| "top-left"
@@ -35,20 +18,36 @@ export type FrameAnchor =
3518

3619
export type Data = Iterable<any> | ArrayLike<any>;
3720

21+
/**
22+
* A bare renderable mark implementation. Given the mark’s *index*, an object of
23+
* the plot’s *scales*, the mark’s (possibly scaled) channel *values*, the
24+
* plot’s *dimensions* and *context*, returns a new SVGElement, or null if the
25+
* mark should display nothing.
26+
*/
3827
export type RenderFunction = (
28+
/** The mark’s (filtered and transformed) index. */
3929
index: number[],
30+
/** The plot’s scale functions. */
4031
scales: ScaleFunctions,
32+
/** The mark’s (possibly scaled and transformed) channel values. */
4133
values: ChannelValues,
34+
/** The plot’s dimensions. */
4235
dimensions: Dimensions,
36+
/** The plot’s context. */
4337
context: Context
4438
) => SVGElement | null;
4539

46-
export type Markish = RenderFunction | Renderable | Markish[] | null | undefined;
47-
48-
export interface Renderable {
49-
render: RenderFunction;
50-
}
51-
40+
/**
41+
* A mark implementation or mark-like object; one of:
42+
*
43+
* - a renderable mark, extending Mark and implementing *mark*.render
44+
* - a bare render function, for a one-off custom mark
45+
* - an array of mark implementations or mark-like objects
46+
* - null or undefined, to render nothing
47+
*/
48+
export type Markish = RenderableMark | RenderFunction | Markish[] | null | undefined;
49+
50+
/** Shared options for all marks. */
5251
export interface MarkOptions {
5352
// transforms
5453
filter?: ChannelValue;
@@ -57,17 +56,108 @@ export interface MarkOptions {
5756
transform?: TransformFunction;
5857
initializer?: InitializerFunction;
5958

60-
// faceting
59+
/**
60+
* The horizontal facet position, an optional channel for mark-level faceting
61+
* bound to the *fx* scale.
62+
*/
6163
fx?: ChannelValue;
64+
65+
/**
66+
* The vertical facet position, an optional channel for mark-level faceting
67+
* bound to the *fy* scale.
68+
*/
6269
fy?: ChannelValue;
63-
facet?: Facet | boolean | null;
64-
facetAnchor?: FacetAnchor | null;
6570

66-
// axis margins
71+
/**
72+
* Whether to enable or disable faceting; one of:
73+
*
74+
* - *auto* (default) - automatically determine if this mark should be faceted
75+
* - *include* (or true) - draw the subset of the mark’s data in the current facet
76+
* - *exclude* - draw the subset of the mark’s data *not* in the current facet
77+
* - *super* - draw this mark in a single frame that covers all facets
78+
* - null (or false) - repeat this mark’s data across all facets (*i.e.*, no faceting)
79+
*
80+
* When a mark uses *super* faceting, it is not allowed to use position scales
81+
* (*x*, *y*, *fx*, or *fy*); *super* faceting is intended for decorations,
82+
* such as labels and legends.
83+
*
84+
* When top-level faceting is used, the default *auto* setting is equivalent
85+
* to *include* when the mark data is strictly equal to the top-level facet
86+
* data; otherwise it is equivalent to null. When the *include* or *exclude*
87+
* facet mode is chosen, the mark data must be parallel to the top-level facet
88+
* data: the data must have the same length and order. If the data are not
89+
* parallel, then the wrong data may be shown in each facet. The default
90+
* *auto* therefore requires strict equality (`===`) for safety, and using the
91+
* facet data as mark data is recommended when using the *exclude* facet mode.
92+
* (To construct parallel data safely, consider using [*array*.map][1] on the
93+
* facet data.)
94+
*
95+
* When mark-level faceting is used, the default *auto* setting is equivalent
96+
* to *include*: the mark will be faceted if either the **fx** or **fy**
97+
* channel option (or both) is specified. The null or false option will
98+
* disable faceting, while *exclude* draws the subset of the mark’s data *not*
99+
* in the current facet.
100+
*
101+
* [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map
102+
*/
103+
facet?: "auto" | "include" | "exclude" | "super" | boolean | null;
104+
105+
/**
106+
* How to place the mark with respect to facets; one of:
107+
*
108+
* - null (default for most marks) - display the mark in each non-empty facet
109+
* - *top*, *right*, *bottom*, or *left* - display the mark only in facets on
110+
* the given side
111+
* - *top-empty*, *right-empty*, *bottom-empty*, or *left-empty* (default for
112+
* axis marks) - display the mark only in facets that have empty space on
113+
* the given side: either the margin, or an empty facet
114+
* - *empty* - display the mark in empty facets only
115+
*/
116+
facetAnchor?:
117+
| "top"
118+
| "right"
119+
| "bottom"
120+
| "left"
121+
| "top-left"
122+
| "top-right"
123+
| "bottom-left"
124+
| "bottom-right"
125+
| "top-empty"
126+
| "right-empty"
127+
| "bottom-empty"
128+
| "left-empty"
129+
| "empty"
130+
| null;
131+
132+
/**
133+
* Shorthand to set the same default for all four mark margins: **marginTop**,
134+
* **marginRight**, **marginBottom**, and **marginLeft**; typically defaults
135+
* to 0, except for axis marks.
136+
*/
67137
margin?: number;
138+
139+
/**
140+
* The mark’s top margin; the minimum distance in pixels between the top edges
141+
* of the inner and outer plot area.
142+
*/
68143
marginTop?: number;
144+
145+
/**
146+
* The mark’s right margin; the minimum distance in pixels between the right
147+
* edges of the mark’s inner and outer plot area.
148+
*/
69149
marginRight?: number;
150+
151+
/**
152+
* The mark’s bottom margin; the minimum distance in pixels between the bottom
153+
* edges of the inner and outer plot area.
154+
*/
70155
marginBottom?: number;
156+
157+
/**
158+
* The mark’s left margin; the minimum distance in pixels between the left
159+
* edges of the inner and outer plot area.
160+
*/
71161
marginLeft?: number;
72162

73163
// accessibility and interaction
@@ -104,14 +194,24 @@ export interface MarkOptions {
104194
channels?: Channels;
105195
}
106196

197+
/** The abstract base class for Mark implementations. */
107198
export class Mark {
199+
/**
200+
* Renders a new plot, prepending this mark as the first element of **marks**
201+
* of the specified *options*, and returns the corresponding SVG element, or
202+
* an HTML figure element if a caption or legend is requested.
203+
*/
108204
plot: typeof plot;
109205
}
110206

111-
export class RenderableMark extends Mark implements Renderable {
207+
/** A concrete Mark implementation. */
208+
export class RenderableMark extends Mark {
209+
/** Renders this mark, returning a new SVGElement (or null). */
112210
render: RenderFunction;
113211
}
114212

115-
export type CompoundMark = Markish[] & {plot: typeof plot};
213+
/** A compound Mark, comprising other marks. */
214+
export type CompoundMark = Markish[] & Pick<Mark, "plot">;
116215

216+
/** Given an array of marks, returns a compound mark; supports *mark.plot shorthand. */
117217
export function marks(...marks: Markish[]): CompoundMark;

‎src/plot.d.ts

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -36,11 +36,11 @@ export interface PlotOptions extends ScaleDefaults {
3636
aspectRatio?: number | boolean | null;
3737

3838
/**
39-
* Shorthand to set the same default for all four margins: marginTop,
40-
* marginRight, marginBottom, and marginLeft. Otherwise, the default margins
41-
* depend on the maximum margins of the plot’s marks. While most marks default
42-
* to zero margins (because they are drawn inside the chart area), Plot’s axis
43-
* marks have non-zero default margins.
39+
* Shorthand to set the same default for all four margins: **marginTop**,
40+
* **marginRight**, **marginBottom**, and **marginLeft**. Otherwise, the
41+
* default margins depend on the maximum margins of the plot’s marks. While
42+
* most marks default to zero margins (because they are drawn inside the chart
43+
* area), Plot’s axis marks have non-zero default margins.
4444
*/
4545
margin?: number;
4646

0 commit comments

Comments
 (0)