more

Author: Fil

src/marks/text.d.ts

@@ -20,10 +20,25 @@ export interface TextOptions extends MarkOptions {
   y?: ChannelValueSpec;
   text?: ChannelValue;
   frameAnchor?: FrameAnchor;
+
+  /**
+   * The [text anchor](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/text-anchor) for horizontal position; start, end, or middle.
+   */
   textAnchor?: TextAnchor;
+
+  /**
+   * The line anchor for vertical position; top, bottom, or middle.
+   */
   lineAnchor?: LineAnchor;
+
+  /** The line height in ems; defaults to 1. */
   lineHeight?: number;
+
+  /**
+   * The line width in ems, for wrapping.
+   */
   lineWidth?: number;
+
   /**
    * The **textOverflow** option can be used to truncate lines of text longer
    * than the given **lineWidth**. If the mark does not have a **title**
@@ -41,14 +56,56 @@ export interface TextOptions extends MarkOptions {
    *   (…)
    */
   textOverflow?: TextOverflow;
+
   /** If true, changes the default fontFamily and metrics to monospace. */
   monospace?: boolean;
-  /** The font family, *e.g.* "'Atkinson Hyperlegible',Roboto,sans-serif" */
+
+  /** The font name; defaults to
+   * [system-ui](https://drafts.csswg.org/css-fonts-4/#valdef-font-family-system-ui).
+   * For example, to use a custom font stack:
+   *
+   * ```js
+   * Plot.text(labels, {
+   *   x: "x", y: "y", text: "label",
+   *   fontFamily: "'Atkinson Hyperlegible',Roboto,sans-serif",
+   * })
+   * ```
+   */
   fontFamily?: string;
+
+  /** The font size in pixels; defaults to 10 */
   fontSize?: ChannelValue;
+
+  /**
+   * The [font
+   * style](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style);
+   * defaults to normal.
+   *
+   * For italic font, use fontStyle: "italic".
+   */
   fontStyle?: string;
+
+  /**
+   * The [font
+   * variant](https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant);
+   * defaults to normal.
+   *
+   * For tabular numbers, use fontVariant: "tabular-nums".
+   */
   fontVariant?: string;
+
+  /**
+   * The [font
+   * weight](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight);
+   * defaults to normal.
+   *
+   * For a boldface font, use *e.g.* fontWeight: "bold" or fontWeight: 700.
+   */
   fontWeight?: string | number;
+
+  /**
+   * The rotation angle in degrees clockwise; defaults to 0°.
+   */
   rotate?: ChannelValue;
 }
 
@@ -67,9 +124,9 @@ export interface TextYOptions extends Omit<TextOptions, "x"> {
  * channel specifies the textual contents of the mark, with line breaks ('\n',
  * '\r\n', or '\r') denoting separate lines, rendered as tspan elements spaced
  * with a relative **lineHeight** that defaults to 1. The text can be split in
- * lines of a given **lineWidth**, specified in percentage of the font size
- * (e.g. 1000 for about 20 characters). Lines might be split on words that
- * contain a soft-hyphen (\xad), replacing it with a dash (-) and a line feed.
+ * lines of a given **lineWidth**, specified in ems (e.g. 10 for about 20
+ * characters). Lines might be split on words that contain a soft-hyphen (\xad),
+ * replacing it with a dash (-) and a line feed.
  *
  * If the text is specified as numbers or dates, a default formatter will
  * automatically be applied, and the **fontVariant** will default to
@@ -86,13 +143,12 @@ export interface TextYOptions extends Omit<TextOptions, "x"> {
  * Common font options include **fontFamily**, **fontSize**, **fontStyle**,
  * **fontWeight**, and **monospace**.
  *
- * The optional **x** and **y** channels specify the position of the text, and
- * the optional **y** categorical channel specifies its vertical anchor in data
- * space. For screen-space positioning if **x** or **y** is omitted, use the
- * **frameAnchor** options. Relative to the anchor, the text can be aligned with
- * the **textAnchor** and **lineAnchor** options, and translated with the common
- * **dx** and **dy** options. The text can be rotated with the **rotate**
- * option, that defaults to 0°.
+ * The optional **x** and **y** channels specify the position of the text in
+ * data space. For screen-space positioning if **x** or **y** is omitted, use
+ * one of the **frameAnchor** options. Relative to its anchor, the text can be
+ * aligned with the **textAnchor** and **lineAnchor** options, and translated
+ * with the common **dx** and **dy** options. The text can be rotated with the
+ * **rotate** option, that defaults to 0°.
  *
  * The **textOverflow** option can be used to truncate lines of text longer than
  * the given **lineWidth**.