edits

Author: mbostock

src/marks/vector.d.ts

@@ -1,80 +1,114 @@
 import type {ChannelValue, ChannelValueSpec} from "../channel.js";
 import type {Data, FrameAnchor, MarkOptions, RenderableMark} from "../mark.js";
 
+/** The built-in vector shape implementations. */
 export type VectorShapeName = "arrow" | "spike";
 
-/**
- * A custom vector shape implementation.
- */
+/** A vector shape implementation. */
 export interface VectorShapeImplementation {
   draw(context: CanvasPath, length: number, radius: number): void;
 }
 
+/** How to draw a vector. */
 export type VectorShape = VectorShapeName | VectorShapeImplementation;
 
+/** Options for the vector mark. */
 export interface VectorOptions extends MarkOptions {
-  /** A channel for the horizontal position. */
+  /**
+   * The horizontal position of the vector’s anchor point; an optional channel
+   * bound to the *x* scale. Default depends on the **frameAnchor**.
+   */
   x?: ChannelValueSpec;
-  /** A channel for the vertical position. */
+
+  /**
+   * The vertical position of the vector’s anchor point; an optional channel bound to the
+   * *y* scale. Default depends on the **frameAnchor**.
+   */
   y?: ChannelValueSpec;
+
   /**
-   * The radius channel (in pixels) describes the mark’s secondary dimension
-   * (typically the *arrow* head’s span, or the *spike*’s base).
+   * The vector shape’s radius, such as half the width of the *arrow*’s head or
+   * the *spike*’s base; a constant number in pixels. Defaults to 3.5 pixels.
    */
-  r?: ChannelValueSpec;
+  r?: number;
+
   /**
-   * The length of the shape, typically associated with a linear *length* scale.
+   * The vector’s length; either an optional channel bound to the *length* scale
+   * or a constant number in pixels. Defaults to 12 pixels.
    */
   length?: ChannelValueSpec;
-  /** Vector rotation, in degrees; with rotate = 0, the shape points up. */
+
+  /**
+   * The vector’s orientation (rotation angle); either a constant number in
+   * degrees clockwise, or an optional channel (with no associated scale).
+   * Defaults to 0 degrees with the vector pointing up; positive angles proceed
+   * clockwise.
+   */
   rotate?: ChannelValue;
-  /** Vector shape, as a name (*arrow* or *spike*), or as a custom implementation. */
+
+  /** The shape of the vector; a constant. Defaults to *arrow*. */
   shape?: VectorShape;
-  /** Vector anchor; by default a vector is anchored at its base (*start*). */
+
+  /**
+   * The vector’s position along its orientation relative to its anchor point; a
+   * constant. Assuming a default **rotate** angle of 0°, one of:
+   *
+   * * *start* - from [*x*, *y*] to [*x*, *y* - *l*]
+   * * *middle* (default) - from [*x*, *y* + *l* / 2] to [*x*, *y* - *l* / 2]
+   * * *end* - from [*x*, *y* + *l*] to [*x*, *y*]
+   *
+   * where [*x*, *y*] is the vector’s anchor point and *l* is the vector’s
+   * (possibly scaled) length in pixels.
+   */
   anchor?: "start" | "middle" | "end";
+
   /**
-   * The frame anchor, for vectors without a position, or positioned on a single
-   * (*x* or *y*) dimension in a two-dimensional frame.
+   * The vector’s frame anchor, to default **x** and **y** relative to the
+   * frame; a constant representing one of the frame corners (*top-left*,
+   * *top-right*, *bottom-right*, *bottom-left*), sides (*top*, *right*,
+   * *bottom*, *left*), or *middle* (default). Has no effect if both **x** and
+   * **y** are specified.
    */
   frameAnchor?: FrameAnchor;
 }
 
 /**
- * A vector of the given **length**, drawn in the **shape** of an arrow from its
- * **anchor** at the given [**x**, **y**] position, and an orientation indicated
- * by **rotate**. To create a vector field representing a wind map:
+ * Returns a new vector mark for the given *data* and *options*. For example, to
+ * create a vector field from spatial samples of wind observations:
  *
  * ```js
  * Plot.vector(wind, {x: "longitude", y: "latitude", length: "speed", rotate: "direction"})
  * ```
  *
- * By default, accepts an array of coordinates pairs (tuples) as *data*.
+ * If none of **frameAnchor**, **x**, and **y** are specified, then **x** and
+ * **y** default to accessors assuming that *data* contains tuples [[*x₀*,
+ * *y₀*], [*x₁*, *y₁*], [*x₂*, *y₂*], …]
  */
 export function vector(data?: Data, options?: VectorOptions): Vector;
 
 /**
- * The vector mark, but the **x** channel defaults to identity, positioning one
- * arrow for each horizontal position passed as *data*.
+ * Like vector, but **x** instead defaults to the identity function and **y**
+ * defaults to null, assuming that *data* is an array of numbers [*x₀*, *x₁*,
+ * *x₂*, …].
  */
 export function vectorX(data?: Data, options?: VectorOptions): Vector;
 
 /**
- * The vector mark, but the **y** channel defaults to identity, positioning one
- * arrow for each vertical position passed as *data*.
+ * Like vector, but **y** instead defaults to the identity function and **x**
+ * defaults to null, assuming that *data* is an array of numbers [*y₀*, *y₁*,
+ * *y₂*, …].
  */
 export function vectorY(data?: Data, options?: VectorOptions): Vector;
 
 /**
- * A variant of the vector mark where the **shape** defaults to *spike*, the
- * **stroke** defaults to *currentColor*, the **strokeWidth** defaults to 1, the
- * **fill** defaults to **stroke**, the **fillOpacity** defaults to 0.3, and the
- * **anchor** defaults to *start*. Typically used to create a spike map:
+ * Like vector, but with default *options* suitable for drawing a spike map. For
+ * example, to show city populations:
  *
  * ```js
- * Plot.spike(counties, {stroke: "red", length: "population"})
+ * Plot.spike(cities, {x: "longitude", y: "latitude", stroke: "red", length: "population"})
  * ```
  */
 export function spike(data?: Data, options?: VectorOptions): Vector;
 
-/** The vector mark */
+/** The vector mark. */
 export class Vector extends RenderableMark {}