document cell (#1396)

* document cell

* a note about barX/Y

* edits

* edit

---------

Co-authored-by: Mike Bostock <[email protected]>

Author: Fil

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.

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 {}

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;
 }
 
 /**

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"}))