diff --git a/src/marks/bar.d.ts b/src/marks/bar.d.ts index 9796ac483a..9cb69b46de 100644 --- a/src/marks/bar.d.ts +++ b/src/marks/bar.d.ts @@ -1,29 +1,12 @@ import type {ChannelValueIntervalSpec, ChannelValueSpec} from "../channel.js"; -import type {Interval} from "../interval.js"; import type {InsetOptions} from "../inset.js"; +import type {Interval} from "../interval.js"; import type {Data, MarkOptions, RenderableMark} from "../mark.js"; import type {StackOptions} from "../transforms/stack.js"; +import type {RectCornerOptions} from "./rect.js"; /** Options for the barX and barY marks. */ -interface BarOptions extends MarkOptions, InsetOptions, StackOptions { - /** - * The rounded corner [*x*-radius][1], either in pixels or as a percentage of - * the bar width. If **rx** is not specified, it defaults to **ry** if - * present, and otherwise draws square corners. - * - * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/rx - */ - rx?: number | string; - - /** - * The rounded corner [*y*-radius][1], either in pixels or as a percentage of - * the bar height. If **ry** is not specified, it defaults to **rx** if - * present, and otherwise draws square corners. - * - * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/ry - */ - ry?: number | string; - +interface BarOptions extends MarkOptions, InsetOptions, RectCornerOptions, StackOptions { /** * How to convert a continuous value (**x** for barX, or **y** for barY) into * an interval (**x1** and **x2** for barX, or **y1** and **y2** for barY); @@ -82,7 +65,7 @@ export interface BarXOptions extends BarOptions { x2?: ChannelValueSpec; /** - * The optional vertical position of the bar; a categorical channel typically + * The optional vertical position of the bar; a ordinal channel typically * bound to the *y* scale. If not specified, the bar spans the vertical extent * of the frame; otherwise the *y* scale must be a *band* scale. * @@ -127,10 +110,9 @@ export interface BarYOptions extends BarOptions { y2?: ChannelValueSpec; /** - * The optional horizontal position of the bar; a categorical channel - * typically bound to the *x* scale. If not specified, the bar spans the - * horizontal extent of the frame; otherwise the *x* scale must be a *band* - * scale. + * The optional horizontal position of the bar; a ordinal channel typically + * bound to the *x* scale. If not specified, the bar spans the horizontal + * extent of the frame; otherwise the *x* scale must be a *band* scale. * * If *x* represents quantitative or temporal values, use a rectY mark * instead. diff --git a/src/marks/cell.d.ts b/src/marks/cell.d.ts index 9042c04243..3d3ee26df5 100644 --- a/src/marks/cell.d.ts +++ b/src/marks/cell.d.ts @@ -1,18 +1,74 @@ import type {ChannelValueSpec} from "../channel.js"; import type {InsetOptions} from "../inset.js"; import type {Data, MarkOptions, RenderableMark} from "../mark.js"; +import type {RectCornerOptions} from "./rect.js"; -export interface CellOptions extends MarkOptions, InsetOptions { +/** Options for the cell mark. */ +export interface CellOptions extends MarkOptions, InsetOptions, RectCornerOptions { + /** + * The horizontal position of the cell; an optional ordinal channel typically + * bound to the *x* scale. If not specified, the cell spans the horizontal + * extent of the frame; otherwise the *x* scale must be a *band* scale. + * + * If *x* represents quantitative or temporal values, use a barX mark instead; + * if *y* is also quantitative or temporal, use a rect mark. + */ x?: ChannelValueSpec; + + /** + * The vertical position of the cell; an optional ordinal channel typically + * bound to the *y* scale. If not specified, the cell spans the vertical + * extent of the frame; otherwise the *y* scale must be a *band* scale. + * + * If *y* represents quantitative or temporal values, use a barY mark instead; + * if *x* is also quantitative or temporal, use a rect mark. + */ y?: ChannelValueSpec; - rx?: number | string; - ry?: number | string; } +/** + * Returns a rectangular cell mark for the given *data* and *options*. Along + * with **x** and/or **y**, a **fill** channel is typically specified to encode + * value as color. For example, for a heatmap of the IMDb ratings of Simpons + * episodes by season: + * + * ```js + * Plot.cell(simpsons, {x: "number_in_season", y: "season", fill: "imdb_rating"}) + * ``` + * + * If neither **x** nor **y** are specified, *data* is assumed to be an array of + * pairs [[*x₀*, *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that **x** = [*x₀*, + * *x₁*, *x₂*, …] and **y** = [*y₀*, *y₁*, *y₂*, …]. + * + * Both **x** and **y** should be ordinal; if only **x** is quantitative (or + * temporal), use a barX mark; if only **y** is quantitative, use a barY mark; + * if both are quantitative, use a rect mark. + */ export function cell(data?: Data, options?: CellOptions): Cell; +/** + * Like cell, but **x** defaults to the zero-based index [0, 1, 2, …], and if + * **stroke** is not a channel, **fill** defaults to the identity function, + * assuming that *data* = [*x₀*, *x₁*, *x₂*, …]. For a quick horizontal stripe + * map visualizating an array of numbers: + * + * ```js + * Plot.cellX(values) + * ``` + */ export function cellX(data?: Data, options?: CellOptions): Cell; +/** + * Like cell, but **y** defaults to the zero-based index [0, 1, 2, …], and if + * **stroke** is not a channel, **fill** defaults to the identity function, + * assuming that *data* = [*y₀*, *y₁*, *y₂*, …]. For a quick vertical stripe map + * visualizating an array of numbers: + * + * ```js + * Plot.cellY(values) + * ``` + */ export function cellY(data?: Data, options?: CellOptions): Cell; +/** The cell mark. */ export class Cell extends RenderableMark {} diff --git a/src/marks/frame.d.ts b/src/marks/frame.d.ts index 15be3ac65e..5d0e456823 100644 --- a/src/marks/frame.d.ts +++ b/src/marks/frame.d.ts @@ -1,32 +1,15 @@ import type {InsetOptions} from "../inset.js"; import type {MarkOptions, RenderableMark} from "../mark.js"; +import type {RectCornerOptions} from "./rect.js"; /** Options for the frame decoration mark. */ -export interface FrameOptions extends MarkOptions, InsetOptions { +export interface FrameOptions extends MarkOptions, InsetOptions, RectCornerOptions { /** * If null (default), the rectangular outline of the frame is drawn; otherwise * the frame is drawn as a line only on the given side, and the **rx**, * **ry**, **fill**, and **fillOpacity** options are ignored. */ anchor?: "top" | "right" | "bottom" | "left" | null; - - /** - * The rounded corner [*x*-radius][1], either in pixels or as a percentage of - * the frame width. If **rx** is not specified, it defaults to **ry** if - * present, and otherwise draws square corners. - * - * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/rx - */ - rx?: number | string; - - /** - * The rounded corner [*y*-radius][1], either in pixels or as a percentage of - * the frame height. If **ry** is not specified, it defaults to **rx** if - * present, and otherwise draws square corners. - * - * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/ry - */ - ry?: number | string; } /** diff --git a/src/marks/rect.d.ts b/src/marks/rect.d.ts index f063755eeb..3133b87b2c 100644 --- a/src/marks/rect.d.ts +++ b/src/marks/rect.d.ts @@ -4,8 +4,29 @@ import type {Interval} from "../interval.js"; import type {Data, MarkOptions, RenderableMark} from "../mark.js"; import type {StackOptions} from "../transforms/stack.js"; +/** Options for marks that render rectangles, including bar, cell, and rect. */ +export interface RectCornerOptions { + /** + * The rounded corner [*x*-radius][1], either in pixels or as a percentage of + * the rect width. If **rx** is not specified, it defaults to **ry** if + * present, and otherwise draws square corners. + * + * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/rx + */ + rx?: number | string; + + /** + * The rounded corner [*y*-radius][1], either in pixels or as a percentage of + * the rect height. If **ry** is not specified, it defaults to **rx** if + * present, and otherwise draws square corners. + * + * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/ry + */ + ry?: number | string; +} + /** Options for the rect mark. */ -export interface RectOptions extends MarkOptions, InsetOptions, StackOptions { +export interface RectOptions extends MarkOptions, InsetOptions, RectCornerOptions, StackOptions { /** * The horizontal position (or length/width) channel, typically bound to the * *x* scale. @@ -94,24 +115,6 @@ export interface RectOptions extends MarkOptions, InsetOptions, StackOptions { * or stackY for rectY). */ interval?: Interval; - - /** - * The rounded corner [*x*-radius][1], either in pixels or as a percentage of - * the bar width. If **rx** is not specified, it defaults to **ry** if - * present, and otherwise draws square corners. - * - * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/rx - */ - rx?: number | string; - - /** - * The rounded corner [*y*-radius][1], either in pixels or as a percentage of - * the bar height. If **ry** is not specified, it defaults to **rx** if - * present, and otherwise draws square corners. - * - * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/ry - */ - ry?: number | string; } /** Options for the rectX mark. */ @@ -145,8 +148,8 @@ export interface RectYOptions extends RectOptions { /** * Returns a rect mark for the given *data* and *options*. The rectangle extends * horizontally from **x1** to **x2**, and vertically from **y1** to **y2**. The - * position channels are often derived with a transform. For example, to create - * a heatmap of athletes, binned by weight and height: + * position channels are often derived with a transform. For example, for a + * heatmap of athletes, binned by weight and height: * * ```js * Plot.rect(athletes, Plot.bin({fill: "proportion"}, {x: "weight", y: "height"}))