document mark

README.md

@@ -786,7 +786,7 @@ All marks support the following optional channels:
 * **strokeOpacity** - a stroke opacity; bound to the *opacity* scale
 * **strokeWidth** - a stroke width (in pixels)
 * **opacity** - an object opacity; bound to the *opacity* scale
-* **title** - a tooltip (a string of text, possibly with newlines)
+* **title** - an accessible, short-text description (a string of text, possibly with newlines)
 * **href** - a URL to link to
 * **ariaLabel** - a short label representing the value in the accessibility tree
 

src/mark.d.ts

@@ -54,7 +54,7 @@ export type RenderFunction = (
  * A mark implementation or mark-like object; one of:
  *
  * - a renderable mark, extending Mark and implementing *mark*.render
- * - a bare render function, for a one-off custom mark
+ * - a bare render function, for a custom functional mark
  * - an array of mark implementations or mark-like objects
  * - null or undefined, to render nothing
  */
@@ -83,7 +83,7 @@ export interface MarkOptions {
   reverse?: boolean;
 
   /**
-   * Either applies a transform to sort the mark’s render index by the specified
+   * Either applies a transform to sort the mark’s index by the specified
    * channel values, or imputes ordinal scale domains from this mark’s channels.
    *
    * When imputing ordinal scale domains from channel values, the **sort**
@@ -103,8 +103,7 @@ export interface MarkOptions {
    * sort: {y: {value: "x", reverse: true}}
    * ```
    *
-   * When sorting the mark’s render index, the **sort** option is instead one
-   * of:
+   * When sorting the mark’s index, the **sort** option is instead one of:
    *
    * - a function for comparing data, returning a signed number
    * - a channel value definition for sorting given values in ascending order
@@ -128,14 +127,14 @@ export interface MarkOptions {
   initializer?: InitializerFunction;
 
   /**
-   * The horizontal facet position, an optional channel for mark-level faceting
-   * bound to the *fx* scale.
+   * The horizontal facet position, a channel for mark-level faceting bound to
+   * the *fx* scale.
    */
   fx?: ChannelValue;
 
   /**
-   * The vertical facet position, an optional channel for mark-level faceting
-   * bound to the *fy* scale.
+   * The vertical facet position, a channel for mark-level faceting bound to the
+   * *fy* scale.
    */
   fy?: ChannelValue;
 
@@ -231,37 +230,213 @@ export interface MarkOptions {
    */
   marginLeft?: number;
 
-  // accessibility and interaction
+  /**
+   * The [aria-description][1]; a constant textual description.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-description
+   */
   ariaDescription?: string;
+
+  /**
+   * The [aria-hidden][1] state; a constant indicating whether the element is
+   * exposed to an accessibility API.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-hidden
+   */
   ariaHidden?: string;
+
+  /**
+   * The [aria-label][1]; a channel specifying short textual labels representing
+   * the value in the accessibility tree.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label
+   */
   ariaLabel?: ChannelValue;
+
+  /**
+   * The [pointer-events][1] property; a constant string such as *none*.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/CSS/pointer-events
+   */
   pointerEvents?: string;
+
+  /**
+   * The [title][1]; a channel specifying accessible, short textual descriptions
+   * as strings (possibly with newlines).
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title
+   */
   title?: ChannelValue;
 
-  // aesthetics
+  /**
+   * How to clip the mark; one of:
+   *
+   * - *frame* or true - clip to the plot’s frame (inner area)
+   * - *sphere* - clip to the projected sphere (*e.g.*, front hemisphere)
+   * - null or false - do not clip
+   *
+   * The *sphere* clip option requires a geographic projection.
+   */
   clip?: "frame" | "sphere" | boolean | null;
+
+  /**
+   * The horizontal offset in pixels; a constant option. On low-density screens,
+   * an additional 0.5px offset may be applied for crisp edges.
+   */
   dx?: number;
+
+  /**
+   * The vertical offset in pixels; a constant option. On low-density screens,
+   * an additional 0.5px offset may be applied for crisp edges.
+   */
   dy?: number;
+
+  /**
+   * The [fill][1]; a constant CSS color string, or a channel typically bound to
+   * the *color* scale. If all channel values are valid CSS colors, by default
+   * the channel will not be bound to the *color* scale, interpreting the colors
+   * literally.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill
+   */
   fill?: ChannelValueSpec;
+
+  /**
+   * The [fill-opacity][1]; a constant number between 0 and 1, or a channel
+   * typically bound to the *opacity* scale. If all channel values are numbers
+   * in [0, 1], by default the channel will not be bound to the *opacity* scale,
+   * interpreting the opacities literally.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/fill-opacity
+   */
   fillOpacity?: ChannelValueSpec;
+
+  /**
+   * The [stroke][1]; a constant CSS color string, or a channel typically bound
+   * to the *color* scale. If all channel values are valid CSS colors, by
+   * default the channel will not be bound to the *color* scale, interpreting
+   * the colors literally.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke
+   */
   stroke?: ChannelValueSpec;
+
+  /**
+   * The [stroke-dasharray][1]; a constant number indicating the length in
+   * pixels of alternating dashes and gaps, or a constant string of numbers
+   * separated by spaces or commas (_e.g._, *10 2* for dashes of 10 pixels
+   * separated by gaps of 2 pixels), or *none* (the default) for no dashing
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray
+   */
   strokeDasharray?: string | number;
+
+  /**
+   * The [stroke-dashoffset][1]; a constant indicating the offset in pixels of
+   * the first dash along the stroke; defaults to zero.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dashoffset
+   */
   strokeDashoffset?: string | number;
+
+  /**
+   * The [stroke-linecap][1]; a constant specifying how to cap stroked paths,
+   * such as *butt*, *round*, or *square*.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-linecap
+   */
   strokeLinecap?: string;
+
+  /**
+   * The [stroke-linejoin][1]; a constant specifying how to join stroked paths,
+   * such as *bevel*, *miter*, *miter-clip*, or *round*.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-linejoin
+   */
   strokeLinejoin?: string;
+
+  /**
+   * The [stroke-miterlimit][1]; a constant number specifying how to limit the
+   * length of *miter* joins on stroked paths.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-miterlimit
+   */
   strokeMiterlimit?: number;
+
+  /**
+   * The [stroke-opacity][1]; a constant between 0 and 1, or a channel typically
+   * bound to the *opacity* scale. If all channel values are numbers in [0, 1],
+   * by default the channel will not be bound to the *opacity* scale,
+   * interpreting the opacities literally.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-opacity
+   */
   strokeOpacity?: ChannelValueSpec;
+
+  /**
+   * The [stroke-width][1]; a constant number in pixels, or a channel.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-width
+   */
   strokeWidth?: ChannelValueSpec;
+
+  /**
+   * The [opacity][1]; a constant between 0 and 1, or a channel typically bound
+   * to the *opacity* scale. If all channel values are numbers in [0, 1], by
+   * default the channel will not be bound to the *opacity* scale, interpreting
+   * the opacities literally. For faster rendering, prefer the **strokeOpacity**
+   * or **fillOpacity** option.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/opacity
+   */
   opacity?: ChannelValueSpec;
+
+  /**
+   * The [mix-blend-mode][1]; a constant string specifying how to blend content
+   * such as *multiply*.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/CSS/mix-blend-mode
+   */
   mixBlendMode?: string;
+
+  /**
+   * The [paint-order][1]; a constant string specifying the order in which the
+   * **fill**, **stroke**, and any markers are drawn; defaults to *normal*,
+   * which draws the fill, then stroke, then markers; defaults to *stroke* for
+   * the text mark to create a “halo” around text to improve legibility.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/CSS/paint-order
+   */
   paintOrder?: string;
+
+  /**
+   * The [shape-rendering][1]; a constant string such as *crispEdges*.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/shape-rendering
+   */
   shapeRendering?: string;
 
-  // links
+  /**
+   * The [href][1]; a channel specifying URLs for clickable links. May be used
+   * in conjunction with the **target** option to open links in another window.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/href
+   */
   href?: ChannelValue;
+
+  /**
+   * The [target][1]; a constant string specifying the target window (_e.g._,
+   * *_blank*) for clickable links; used in conjunction with the **href**
+   * option.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/target
+   */
   target?: string;
 
-  // custom channels
+  /**
+   * An object defining additional custom channels. This meta option may be used
+   * by an **initializer** to declare extra channels.
+   */
   channels?: Channels;
 }