Merge branch 'main' into fil/ts-line

src/channel.d.ts

@@ -169,6 +169,12 @@ export type ChannelValueDenseBinSpec = ChannelValue | ({value: ChannelValue; sca
  * - *width* - impute from |*x2* - *x1*|
  * - *height* - impute from |*y2* - *y1*|
  * - null - impute from input order
+ *
+ * If the *x* channel is not defined, the *x2* channel will be used instead if
+ * available, and similarly for *y* and *y2*; this is useful for marks that
+ * implicitly stack. The *data* input is typically used in conjunction with a
+ * custom **reduce** function, as when the built-in single-channel reducers are
+ * insufficient.
  */
 export type ChannelDomainValue = ChannelName | "data" | "width" | "height" | null;
 
@@ -190,12 +196,22 @@ export interface ChannelDomainOptions {
   reverse?: boolean;
 
   /**
-   * If a positive number, limit the domain to the first *n* sorted values; if a
-   * negative number, limit the domain to the last *-n* sorted values. Otherwise
-   * slices the sorted domain from *lo* (inclusive) to *hi* (exclusive); if
-   * either *lo* or *hi* are negative, it indicates an offset from the end of
-   * the array; if *lo* is undefined it defaults to 0, and if *hi* is undefined
-   * it defaults to Infinity.
+   * If a positive number, limit the domain to the first *n* sorted values. If a
+   * negative number, limit the domain to the last *-n* sorted values. Hence, a
+   * positive **limit** with **reverse** true will return the top *n* values in
+   * descending order.
+   *
+   * If an array [*lo*, *hi*], slices the sorted domain from *lo* (inclusive) to
+   * *hi* (exclusive). As with [*array*.slice][1], if either *lo* or *hi* are
+   * negative, it indicates an offset from the end of the array; if *lo* is
+   * undefined it defaults to 0, and if *hi* is undefined it defaults to
+   * Infinity.
+   *
+   * Note: limiting the imputed domain of one scale, say *x*, does not affect
+   * the imputed domain of another scale, say *y*; each scale domain is imputed
+   * independently.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice
    */
   limit?: number | [lo?: number, hi?: number];
 }

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