Merge branch 'main' into fil/color-legend-opacity

Author: Fil

README.md

@@ -296,7 +296,7 @@ Plot automatically generates [axis](#axis) and optionally [grid](#grid) marks fo
 * *scale*.**tickPadding** - the separation between the tick and its label (in pixels; default 3)
 * *scale*.**tickFormat** - either a function or specifier string to format tick values; see [Formats](#formats)
 * *scale*.**tickRotate** - whether to rotate tick labels (an angle in degrees clockwise; default 0)
-* *scale*.**grid** - if true, draw grid lines across the plot for each tick
+* *scale*.**grid** - whether to draw grid lines across the plot for each tick
 * *scale*.**line** - if true, draw the axis line (only for *x* and *y*)
 * *scale*.**label** - a string to label the axis
 * *scale*.**labelAnchor** - the label anchor: *top*, *right*, *bottom*, *left*, or *center*
@@ -305,7 +305,7 @@ Plot automatically generates [axis](#axis) and optionally [grid](#grid) marks fo
 * *scale*.**ariaLabel** - a short label representing the axis in the accessibility tree
 * *scale*.**ariaDescription** - a textual description for the axis
 
-Top-level options are also supported as shorthand: **grid** (for *x* and *y* only; see [facet.grid](#facet-options)), **label**, **axis**, **inset**, **round**, **align**, and **padding**.
+Top-level options are also supported as shorthand: **grid** (for *x* and *y* only; see [facet.grid](#facet-options)), **label**, **axis**, **inset**, **round**, **align**, and **padding**. If the **grid** option is true, show a grid with the currentColor stroke; if specified as a string, show a grid with the specified stroke color; if an approximate number of ticks, an interval, or an array of tick values, show corresponding grid lines.
 
 ### Projection options
 
@@ -1505,7 +1505,7 @@ Returns a new *fy* grid with the given *options*.
 
 ### Hexgrid
 
-The hexgrid mark can be used to support marks using the [hexbin](#hexbin) layout.
+The hexgrid mark can be used to support marks using the [hexbin](#hexbin) transform.
 
 #### Plot.hexgrid(*options*)
 
@@ -1978,7 +1978,7 @@ Equivalent to [Plot.vector](#plotvectordata-options) except that the **shape** d
 
 ## Decorations
 
-Decorations are static marks that do not represent data. Currently this includes only [Plot.frame](#frame), although internally Plot’s axes are implemented as decorations and may in the future be exposed here for more flexible configuration.
+Decorations are marks that do not directly represent data. Currently this includes [Plot.frame](#frame), as well as the [axes](#axis) and [grid](#grid) marks described above.
 
 ### Frame
 

src/marks/frame.d.ts

@@ -1,12 +1,40 @@
 import type {InsetOptions} from "../inset.js";
 import type {MarkOptions, RenderableMark} from "../mark.js";
 
+/** Options for the frame decoration mark. */
 export interface FrameOptions extends MarkOptions, InsetOptions {
+  /**
+   * 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;
 }
 
+/**
+ * Draws a rectangle around the plot’s frame, or if an **anchor** is given, a
+ * line on the given side. Useful for visual separation of facets, or in
+ * conjunction with axes and grids to fill the frame’s background.
+ */
 export function frame(options?: FrameOptions): Frame;
 
+/** The frame decoration mark. */
 export class Frame extends RenderableMark {}

src/marks/hexgrid.d.ts

@@ -1,9 +1,34 @@
 import type {MarkOptions, RenderableMark} from "../mark.js";
 
+/** Options for the hexgrid mark. */
 export interface HexgridOptions extends MarkOptions {
+  /**
+   * The distance between centers of neighboring hexagons, in pixels; defaults
+   * to 20. Should match the **binWidth** of the hexbin transform.
+   */
   binWidth?: number;
 }
 
+/**
+ * The hexgrid decoration mark complements the hexbin transform, showing the
+ * outlines of all hexagons spanning the frame with a default **stroke** of
+ * *currentColor* and a default **strokeOpacity** of 0.1, similar to the the
+ * default axis grids. For example:
+ *
+ * ```js
+ * Plot.plot({
+ *   marks: [
+ *     Plot.hexagon(Plot.hexbin({fill: "count"}, {binWidth: 12, x: "weight", y: "economy"})),
+ *     Plot.hexgrid({binWidth: 12})
+ *   ]
+ * })
+ * ```
+ *
+ * Note that the **binWidth** option of the hexgrid mark should match that of
+ * the hexbin transform. The grid is clipped by the frame. This is a stroke-only
+ * mark, and **fill** is not supported; to fill the frame, use the frame mark.
+ */
 export function hexgrid(options?: HexgridOptions): Hexgrid;
 
+/** The hexgrid mark. */
 export class Hexgrid extends RenderableMark {}

src/transforms/window.d.ts

@@ -65,6 +65,11 @@ export interface WindowOptions {
    * - *start* - as the first element in the window
    * - *middle* (default) - in the middle of the window, rounding down if **k** is even
    * - *end* - as the last element in the window
+   *
+   * Note that *start* and *end* are relative to input order, not natural
+   * ascending order by value. For example, if the data is in reverse
+   * chronological order, then the meaning of *start* and *end* is effectively
+   * reversed because the first data point is the most recent.
    */
   anchor?: "start" | "middle" | "end";