legends docs

Author: mbostock

src/legends.d.ts

@@ -1,36 +1,38 @@
 import type {ScaleName, ScaleOptions} from "./scales.js";
 
-/** The supported legend types. */
-export type LegendType = "ramp" | "swatches";
-
 /** Options for generating a scale legend. */
 export interface LegendOptions {
   /**
-   * The desired legend type; currently supported only for a discrete *color*
-   * scale of type *ordinal*, *quantile*, *quantize*, or *threshold*. One of:
+   * The desired legend type; one of:
+   *
+   * - *ramp* - place labels underneath with a connecting line, and no wrapping
+   * - *swatches* - place labels to the right, and allow wrapping
    *
-   * * *ramp* - place labels underneath with a connecting line, and no wrapping
-   * * *swatches* - place labels to the right, and allow wrapping
+   * The legend type can currently only be configured for a discrete *color*
+   * scale of type *ordinal*, *quantile*, *quantize*, or *threshold*; for other
+   * *color* scale types, or for *opacity* or *symbol* scales, the legend type
+   * cannot be changed.
    */
-  legend?: LegendType;
+  legend?: "ramp" | "swatches";
 
   /**
    * How to format tick values sampled from the scale’s domain. This may be a
    * function, which will be passed the tick value *t* and zero-based index *i*
    * and must return the corresponding string. If the domain is numbers, the
-   * tick format may also be expressed as a [d3-format
-   * string](https://github.com/d3/d3-format/blob/main/README.md#locale_format);
-   * or if the domain is dates, the tick format may also be expressed as a
-   * [d3-time-format
-   * string](https://github.com/d3/d3-time-format/blob/main/README.md#locale_format).
+   * tick format may also be expressed as a [d3-format string][1]; or if the
+   * domain is dates, the tick format may also be expressed as a [d3-time-format
+   * string][2].
+   *
+   * [1]: https://github.com/d3/d3-format/blob/main/README.md#locale_format
+   * [2]: https://github.com/d3/d3-time-format/blob/main/README.md#locale_format
    */
   tickFormat?: ScaleOptions["tickFormat"];
 
   /**
-   * The [CSS
-   * font-variant](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant)
-   * for tick labels. For non-ordinal scales, or ordinal scales without an
-   * interval, this defaults to *tabular-nums*.
+   * The [CSS font-variant][1] for tick labels. For non-ordinal scales, or
+   * ordinal scales without an interval, this defaults to *tabular-nums*.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant
    */
   fontVariant?: ScaleOptions["fontVariant"];
 
@@ -43,35 +45,77 @@ export interface LegendOptions {
    */
   className?: string | null;
 
-  /** The constant color for *opacity* scales. Defaults to black. */
+  /** The constant color the ramp; defaults to black. For *ramp* *opacity* legends only. */
   color?: string;
-
-  // symbol options
+  /** The desired fill color of symbols; use *color* for a redundant encoding. For *symbol* legends only. */
   fill?: string;
+  /** The desired fill opacity of symbols. For *symbol* legends only. */
   fillOpacity?: number;
+  /** The desired stroke color of symbols; use *color* for a redundant encoding. For *symbol* legends only. */
   stroke?: string;
+  /** The desired stroke opacity of symbols. For *symbol* legends only. */
   strokeOpacity?: number;
+  /** The desired stroke width of symbols. For *symbol* legends only. */
   strokeWidth?: number;
+  /** The desired radius of symbols in pixels. For *symbol* legends only. */
   r?: number;
 
-  // dimensions
+  /**
+   * The width of the legend in pixels. For *ramp* legends, defaults to 240; for
+   * *swatch* legends, defaults to undefined, allowing the swatches to wrap
+   * based on content flow.
+   */
   width?: number;
+
+  /**
+   * The height of the legend in pixels; defaults to 44 plus **tickSize**. For
+   * *ramp* legends only.
+   */
   height?: number;
+
+  /** The top margin in pixels; defaults to 18. For *ramp* legends only. */
   marginTop?: number;
+  /** The right margin in pixels; defaults to 0. For *ramp* legends only. */
   marginRight?: number;
+  /** The bottom margin in pixels; defaults to 16 plus **tickSize**. For *ramp* legends only. */
   marginBottom?: number;
+  /** The left margin in pixels; defaults to 0. For *ramp* legends only. */
   marginLeft?: number;
 
-  // ramp options
+  /** A textual label to place above the legend. For *ramp* legends only. */
   label?: string | null;
+
+  /**
+   * The desired approximate number of axis ticks, or an explicit array of tick
+   * values, or an interval such as *day* or *month*. For *ramp* legends only.
+   */
   ticks?: ScaleOptions["ticks"];
+
+  /**
+   * The length of axis tick marks in pixels; negative values extend in the
+   * opposite direction. For *ramp* legends only.
+   */
   tickSize?: ScaleOptions["tickSize"];
+
+  /**
+   * If true, round the output value to the nearest integer (pixel); useful for
+   * crisp edges when rendering. For *ramp* legends only.
+   */
   round?: ScaleOptions["round"];
 
-  // swatches options
+  /**
+   * The [CSS columns property][1], for a multi-column layout. For *swatches*
+   * legends only.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/CSS/columns
+   */
   columns?: string;
+
+  /** The swatch width and height in pixels; defaults to 15; For *swatches* legends only. */
   swatchSize?: number;
+  /** The swatch width in pixels; defaults to **swatchSize**; For *swatches* legends only. */
   swatchWidth?: number;
+  /** The swatch height in pixels; defaults to **swatchSize**; For *swatches* legends only. */
   swatchHeight?: number;
 }
 

src/scales.d.ts

@@ -1,6 +1,6 @@
 import type {InsetOptions} from "./inset.js";
 import type {NiceInterval, RangeInterval} from "./interval.js";
-import type {LegendType} from "./legends.js";
+import type {LegendOptions} from "./legends.js";
 import type {AxisAnchor} from "./marks/axis.js";
 
 /**
@@ -521,7 +521,7 @@ export interface ScaleOptions extends ScaleDefaults {
    *
    * For *color*, *opacity*, and *symbol* scales only. See also *plot*.legend.
    */
-  legend?: LegendType | boolean | null;
+  legend?: LegendOptions["legend"] | boolean | null;
 
   /**
    * The desired approximate number of axis ticks, or an explicit array of tick