document line (observablehq#1401)

* document line

* z

Author: Fil

src/marks/area.d.ts

@@ -38,8 +38,8 @@ export interface AreaOptions extends MarkOptions, StackOptions, CurveOptions {
 
   /**
    * The optional ordinal **z** channel, for grouping data into (possibly
-   * stacked) series to be drawn as separate areas. If not specified, it
-   * defaults to **fill** if a channel, or **stroke** if a channel.
+   * stacked) series to be drawn as separate areas; defaults to **fill** if a
+   * channel, or **stroke** if a channel.
    */
   z?: ChannelValue;
 }
@@ -59,9 +59,9 @@ export interface AreaXOptions extends Omit<AreaOptions, "y1" | "y2">, BinOptions
 
   /**
    * The vertical position channel, typically bound to the *y* scale; defaults
-   * to the zero-based index of the data.
+   * to the zero-based index of the data [0, 1, 2, …].
    *
-   * If an **interval** is specified, **x** values are binned accordingly,
+   * If an **interval** is specified, **y** values are binned accordingly,
    * allowing zeroes for empty bins instead of interpolating across gaps. This
    * is recommended to “regularize” sampled data; for example, if your data
    * represents timestamped observations and you expect one observation per day,
@@ -77,6 +77,9 @@ export interface AreaXOptions extends Omit<AreaOptions, "y1" | "y2">, BinOptions
    * ```js
    * Plot.areaX(data, {y: "value", interval: 0.5, reduce: "count"})
    * ```
+   *
+   * To default to zero instead of showing gaps in data, as when the observed
+   * value represents a quantity, use the *sum* reducer.
    */
   reduce?: BinReducer;
 }
@@ -85,7 +88,7 @@ export interface AreaXOptions extends Omit<AreaOptions, "y1" | "y2">, BinOptions
 export interface AreaYOptions extends Omit<AreaOptions, "x1" | "x2">, BinOptions {
   /**
    * The horizontal position channel, typically bound to the *x* scale; defaults
-   * to the zero-based index of the data.
+   * to the zero-based index of the data [0, 1, 2, …].
    *
    * If an **interval** is specified, **x** values are binned accordingly,
    * allowing zeroes for empty bins instead of interpolating across gaps. This
@@ -114,6 +117,9 @@ export interface AreaYOptions extends Omit<AreaOptions, "x1" | "x2">, BinOptions
    * ```js
    * Plot.areaY(records, {x: "Date", interval: "month", reduce: "count"})
    * ```
+   *
+   * To default to zero instead of showing gaps in data, as when the observed
+   * value represents a quantity, use the *sum* reducer.
    */
   reduce?: BinReducer;
 }
@@ -148,7 +154,7 @@ export function area(data?: Data, options?: AreaOptions): Area;
 export function areaX(data?: Data, options?: AreaXOptions): Area;
 
 /**
- * Returns a new horizontall-oriented area for the given *data* and *options*,
+ * Returns a new horizontally-oriented area for the given *data* and *options*,
  * where the baseline and topline share **x** values, as in a time-series area
  * chart where time goes right→.
  *

src/marks/line.d.ts

@@ -4,26 +4,154 @@ import type {Data, MarkOptions, RenderableMark} from "../mark.js";
 import type {MarkerOptions} from "../marker.js";
 import type {BinOptions, BinReducer} from "../transforms/bin.js";
 
+/** Options for the line mark. */
 export interface LineOptions extends MarkOptions, MarkerOptions, CurveAutoOptions {
+  /**
+   * The required horizontal position channel, typically bound to the *x* scale.
+   */
   x?: ChannelValueSpec;
+
+  /**
+   * The required vertical position channel, typically bound to the *y* scale.
+   */
   y?: ChannelValueSpec;
+
+  /**
+   * The optional ordinal **z** channel, for grouping data into (possibly
+   * stacked) series to be drawn as separate lines. If not specified, it
+   * defaults to **fill** if a channel, or **stroke** if a channel.
+   */
   z?: ChannelValue;
 }
 
+/** Options for the lineX mark. */
 export interface LineXOptions extends LineOptions, BinOptions {
+  /**
+   * The vertical position channel, typically bound to the *y* scale; defaults
+   * to the zero-based index of the data [0, 1, 2, …].
+   *
+   * If an **interval** is specified, **y** values are binned accordingly,
+   * allowing zeroes for empty bins instead of interpolating across gaps. This
+   * is recommended to “regularize” sampled data; for example, if your data
+   * represents timestamped observations and you expect one observation per day,
+   * use *day* as the **interval**.
+   */
   y?: ChannelValueDenseBinSpec;
+
+  /**
+   * How to reduce **x** values when the **y** channel is binned with an
+   * **interval**; defaults to *first*. For example, to create a vertical
+   * density plot (count of *y* values binned every 0.5):
+   *
+   * ```js
+   * Plot.lineX(data, {y: "value", interval: 0.5, reduce: "count"})
+   * ```
+   *
+   * To default to zero instead of showing gaps in data, as when the observed
+   * value represents a quantity, use the *sum* reducer.
+   */
   reduce?: BinReducer;
 }
 
+/** Options for the lineY mark. */
 export interface LineYOptions extends LineOptions, BinOptions {
+  /**
+   * The horizontal position channel, typically bound to the *x* scale; defaults
+   * to the zero-based index of the data [0, 1, 2, …].
+   *
+   * If an **interval** is specified, **x** values are binned accordingly,
+   * allowing zeroes for empty bins instead of interpolating across gaps. This
+   * is recommended to “regularize” sampled data; for example, if your data
+   * represents timestamped observations and you expect one observation per day,
+   * use *day* as the **interval**.
+   */
   x?: ChannelValueDenseBinSpec;
+
+  /**
+   * How to reduce **y** values when the **x** channel is binned with an
+   * **interval**; defaults to *first*. For example, for a line chart of the
+   * count of records by month:
+   *
+   * ```js
+   * Plot.lineY(records, {x: "Date", interval: "month", reduce: "count"})
+   * ```
+   *
+   * To default to zero instead of showing gaps in data, as when the observed
+   * value represents a quantity, use the *sum* reducer.
+   */
   reduce?: BinReducer;
 }
 
+/**
+ * Returns a new line for the given *data* and *options* by connecting control
+ * points. If neither the **x** nor **y** options 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₂*, …].
+ *
+ * Points along the line are connected in input order. If there are multiple
+ * series via the **z**, **fill**, or **stroke** channel, series are drawn in
+ * input order such that the last series is drawn on top. Typically *data* is
+ * already in sorted order, such as chronological for time series; if needed,
+ * consider a **sort** transform.
+ *
+ * If any **x** or **y** values are invalid (undefined, null, or NaN), the line
+ * will be interrupted, resulting in a break that divides the line shape into
+ * multiple segments. If a line segment consists of only a single point, it may
+ * appear invisible unless rendered with rounded or square line caps. In
+ * addition, some curves such as *cardinal-open* only render a visible segment
+ * if it contains multiple points.
+ *
+ * Variable aesthetic channels are supported: if the **stroke** is defined as a
+ * channel, the line will be broken into contiguous overlapping segments when
+ * the stroke color changes; the stroke color will apply to the interval
+ * spanning the current data point and the following data point. This behavior
+ * also applies to the **fill**, **fillOpacity**, **strokeOpacity**,
+ * **strokeWidth**, **opacity**, **href**, **title**, and **ariaLabel**
+ * channels. When any of these channels are used, setting an explicit **z**
+ * channel (possibly to null) is strongly recommended.
+ */
 export function line(data?: Data, options?: LineOptions): Line;
 
+/**
+ * Like line, except that **x** defaults to the identity function assuming that
+ * *data* = [*x₀*, *x₁*, *x₂*, …] and **y** defaults to the zero-based index [0,
+ * 1, 2, …]. For example, to draw a vertical line chart of a temperature series:
+ *
+ * ```js
+ * Plot.lineX(observations, {x: "temperature"})
+ * ```
+ *
+ * The **interval** option is recommended to “regularize” sampled data via an
+ * implicit binY transform. For example, if your data represents timestamped
+ * temperature measurements and you expect one sample per day, use *day* as the
+ * interval:
+ *
+ * ```js
+ * Plot.lineX(observations, {y: "date", x: "temperature", interval: "day"})
+ * ```
+ */
 export function lineX(data?: Data, options?: LineXOptions): Line;
 
+/**
+ * Like line, except **y** defaults to the identity function and assumes that
+ * *data* = [*y₀*, *y₁*, *y₂*, …] and **x** defaults to the zero-based index [0,
+ * 1, 2, …]. For example, to draw a horizontal line chart of a temperature
+ * series:
+ *
+ * ```js
+ * Plot.lineY(observations, {y: "temperature"})
+ * ```
+ *
+ * The **interval** option is recommended to “regularize” sampled data via an
+ * implicit binX transform. For example, if your data represents timestamped
+ * temperature measurements and you expect one sample per day, use *day* as the
+ * interval:
+ *
+ * ```js
+ * Plot.lineY(observations, {x: "date", y: "temperature", interval: "day"})
+ * ```
+ */
 export function lineY(data?: Data, options?: LineYOptions): Line;
 
+/** The line mark. */
 export class Line extends RenderableMark {}