From c13fd1b4d2b5a0dcc8a8515322b48d0dc0ed3ee8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Mon, 27 Mar 2023 17:02:46 +0200 Subject: [PATCH 1/4] document arrow --- README.md | 5 ++- src/marks/arrow.d.ts | 93 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index aa7dee9ff6..f0d0b6b529 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ + # Observable Plot **Observable Plot** is a JavaScript library for exploratory data visualization. If you are new to Plot, we highly recommend first reading these notebooks to introduce Plot’s core concepts such as *marks* and *scales*: @@ -942,8 +943,8 @@ For vertical or horizontal arrows, the **x** option can be specified as shorthan The arrow mark supports the [standard mark options](#marks). The **stroke** defaults to currentColor. The **fill** defaults to none. The **strokeWidth** defaults to 1.5, and the **strokeMiterlimit** defaults to one. The following additional options are supported: -* **bend** - the bend angle, in degrees; defaults to zero -* **headAngle** - the arrowhead angle, in degrees; defaults to 22.5° +* **bend** - the bend angle, in degrees; defaults to zero; true for 22.5° +* **headAngle** - the arrowhead angle, in degrees; defaults to 60° * **headLength** - the arrowhead scale; defaults to 8 * **insetEnd** - inset at the end of the arrow (useful if the arrow points to a dot) * **insetStart** - inset at the start of the arrow diff --git a/src/marks/arrow.d.ts b/src/marks/arrow.d.ts index d2c9d65771..a76afdca4b 100644 --- a/src/marks/arrow.d.ts +++ b/src/marks/arrow.d.ts @@ -1,21 +1,114 @@ import type {ChannelValueSpec} from "../channel.js"; import type {Data, MarkOptions, RenderableMark} from "../mark.js"; +/** Options for the arrow mark. */ export interface ArrowOptions extends MarkOptions { + /** + * The horizontal position, shorthand for both **x1** and **x2** for vertical + * arrows; bound to the *x* scale. + */ x?: ChannelValueSpec; + + /** + * The vertical position, shorthand for both **y1** and **y2** for horizontal + * arrows; bound to the *y* scale. + */ y?: ChannelValueSpec; + + /** + * The horizontal position of the start point; bound to the *x* scale. + */ x1?: ChannelValueSpec; + + /** + * The vertical position of the start point; bound to the *y* scale. + */ y1?: ChannelValueSpec; + + /** + * The horizontal position of the end point; bound to the *x* scale. + */ x2?: ChannelValueSpec; + + /** + * The vertical position of the end point; bound to the *y* scale. + */ y2?: ChannelValueSpec; + + /** + * The bend angle, in degrees, sets the angle between the straight line + * between the two points and the outgoing direction of the arrow from the + * start point. It must be within ±90°. A positive angle will produce a + * clockwise curve; a negative angle will produce a counterclockwise curve; + * zero (the default) will produce a straight line. Use true for 22.5°. + */ bend?: number | boolean; + + /** + * The **headAngle**, in degrees, determines how pointy the arrowhead is; it + * is typically between 0° and 180°. Defaults to 60. + */ headAngle?: number; + + /** + * The **headLength** determines the scale of the arrowhead relative to the + * stroke width. Assuming the default of stroke width 1.5px, the + * **headLength** is the length of the arrowhead’s side in pixels. + */ headLength?: number; + + /** + * Shorthand for insetStart and insetEnd, in pixels. + */ inset?: number; + + /** + * Inset at the start of the arrow, in pixels (useful if the arrow emerges + * from a dot). Defaults to 0. + */ insetStart?: number; + + /** + * Inset at the end of the arrow, in pixels (useful if the arrow points to a + * dot). Defaults to 0. + */ insetEnd?: number; } +/** + * Draws (possibly swoopy) arrows connecting pairs of points. For example, to + * display arrows connecting two points in a scatterplot that represent the + * population vs income inequality in 1980 and 2015 for U.S. cities: + * + * ```js + * Plot.arrow(inequality, {x1: "POP_1980", y1: "R90_10_1980", x2: "POP_2015", y2: "R90_10_2015", bend: true}) + * ``` + * + * The following channels are required: + * + * - **x1** - the starting horizontal position; bound to the *x* scale + * - **y1** - the starting vertical position; bound to the *y* scale + * - **x2** - the ending horizontal position; bound to the *x* scale + * - **y2** - the ending vertical position; bound to the *y* scale + * + * For vertical or horizontal arrows, the **x** option can be specified as + * shorthand for **x1** and **x2**, and the **y** option can be specified as + * shorthand for **y1** and **y2**, respectively. + * + * The **stroke** defaults to currentColor. The **fill** defaults to none. The + * **strokeWidth** defaults to 1.5, and the **strokeMiterlimit** defaults to + * one. The following additional options are supported: + * + * - **bend** - the bend angle, in degrees; defaults to zero (true for 22.5°) + * - **headAngle** - the arrowhead angle, in degrees; defaults to 60° + * - **headLength** - the arrowhead length, in pixels; defaults to 8. Disable + * the arrow with headLength = 0 + * - **insetEnd** - inset at the end of the arrow (useful if the arrow points to + * a dot) + * - **insetStart** - inset at the start of the arrow + * - **inset** - shorthand for the two insets + */ export function arrow(data?: Data, options?: ArrowOptions): Arrow; +/** The arrow mark. */ export class Arrow extends RenderableMark {} From 1fc73d75f6fd4aaa4a07cf1cf83b7633ad224c8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Thu, 30 Mar 2023 16:31:23 +0200 Subject: [PATCH 2/4] shorter arrow --- src/marks/arrow.d.ts | 28 +++++++--------------------- 1 file changed, 7 insertions(+), 21 deletions(-) diff --git a/src/marks/arrow.d.ts b/src/marks/arrow.d.ts index a76afdca4b..bf39e76c25 100644 --- a/src/marks/arrow.d.ts +++ b/src/marks/arrow.d.ts @@ -58,7 +58,7 @@ export interface ArrowOptions extends MarkOptions { headLength?: number; /** - * Shorthand for insetStart and insetEnd, in pixels. + * Shorthand for **insetStart** and **insetEnd**. */ inset?: number; @@ -84,29 +84,15 @@ export interface ArrowOptions extends MarkOptions { * Plot.arrow(inequality, {x1: "POP_1980", y1: "R90_10_1980", x2: "POP_2015", y2: "R90_10_2015", bend: true}) * ``` * - * The following channels are required: - * - * - **x1** - the starting horizontal position; bound to the *x* scale - * - **y1** - the starting vertical position; bound to the *y* scale - * - **x2** - the ending horizontal position; bound to the *x* scale - * - **y2** - the ending vertical position; bound to the *y* scale - * - * For vertical or horizontal arrows, the **x** option can be specified as - * shorthand for **x1** and **x2**, and the **y** option can be specified as - * shorthand for **y1** and **y2**, respectively. + * The starting point is specified by **x1** and **y1**, and the ending point by + * **x2** and **y2** (or **x** for vertical arrows, and **y** for horizontal + * arrows). The arrow’s shape configuration options include the **bend** angle, + * **headAngle** and **headLength**, as well as insets (**insetEnd** and + * **insetStart**). * * The **stroke** defaults to currentColor. The **fill** defaults to none. The * **strokeWidth** defaults to 1.5, and the **strokeMiterlimit** defaults to - * one. The following additional options are supported: - * - * - **bend** - the bend angle, in degrees; defaults to zero (true for 22.5°) - * - **headAngle** - the arrowhead angle, in degrees; defaults to 60° - * - **headLength** - the arrowhead length, in pixels; defaults to 8. Disable - * the arrow with headLength = 0 - * - **insetEnd** - inset at the end of the arrow (useful if the arrow points to - * a dot) - * - **insetStart** - inset at the start of the arrow - * - **inset** - shorthand for the two insets + * one. */ export function arrow(data?: Data, options?: ArrowOptions): Arrow; From 0417011180001f32a0e9f8ce70dd28943cf06f26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Thu, 30 Mar 2023 16:34:42 +0200 Subject: [PATCH 3/4] no space --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index f0d0b6b529..0c2386207d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,3 @@ - # Observable Plot **Observable Plot** is a JavaScript library for exploratory data visualization. If you are new to Plot, we highly recommend first reading these notebooks to introduce Plot’s core concepts such as *marks* and *scales*: From 172bfa2f81ac8711e7bafbc701d0bef16d6f3752 Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Thu, 30 Mar 2023 15:02:38 -0700 Subject: [PATCH 4/4] edits --- src/inset.d.ts | 8 ++--- src/marks/arrow.d.ts | 74 +++++++++++++++++++++++--------------------- src/marks/link.d.ts | 2 +- 3 files changed, 43 insertions(+), 41 deletions(-) diff --git a/src/inset.d.ts b/src/inset.d.ts index e035f9b041..f7db2f0e60 100644 --- a/src/inset.d.ts +++ b/src/inset.d.ts @@ -1,10 +1,10 @@ /** Options for insetting rectangular shapes. */ export interface InsetOptions { /** - * Shorthand to set the same default for all four insets: insetTop, - * insetRight, insetBottom, and insetLeft. All insets typically default to - * zero, though not always (say, a rect mark and a ban transform). A positive - * inset reduces effective area, while a negative inset increases it. + * Shorthand to set the same default for all four insets: **insetTop**, + * **insetRight**, **insetBottom**, and **insetLeft**. All insets typically + * default to zero, though not always (say when using bin transform). A + * positive inset reduces effective area, while a negative inset increases it. */ inset?: number; diff --git a/src/marks/arrow.d.ts b/src/marks/arrow.d.ts index bf39e76c25..d2bf620dc5 100644 --- a/src/marks/arrow.d.ts +++ b/src/marks/arrow.d.ts @@ -4,95 +4,97 @@ import type {Data, MarkOptions, RenderableMark} from "../mark.js"; /** Options for the arrow mark. */ export interface ArrowOptions extends MarkOptions { /** - * The horizontal position, shorthand for both **x1** and **x2** for vertical - * arrows; bound to the *x* scale. + * The horizontal position, for vertical arrows; typically bound to the *x* + * scale; shorthand for setting defaults for both **x1** and **x2**. */ x?: ChannelValueSpec; /** - * The vertical position, shorthand for both **y1** and **y2** for horizontal - * arrows; bound to the *y* scale. + * The vertical position, for horizontal arrows; typically bound to the *y* + * scale; shorthand for setting defaults for both **y1** and **y2**. */ y?: ChannelValueSpec; /** - * The horizontal position of the start point; bound to the *x* scale. + * The starting horizontal position; typically bound to the *x* scale; also + * sets a default for **x2**. */ x1?: ChannelValueSpec; /** - * The vertical position of the start point; bound to the *y* scale. + * The starting vertical position; typically bound to the *y* scale; also sets + * a default for **y2**. */ y1?: ChannelValueSpec; /** - * The horizontal position of the end point; bound to the *x* scale. + * The ending horizontal position; typically bound to the *x* scale; also sets + * a default for **x1**. */ x2?: ChannelValueSpec; /** - * The vertical position of the end point; bound to the *y* scale. + * The ending vertical position; typically bound to the *y* scale; also sets a + * default for **y1**. */ y2?: ChannelValueSpec; /** - * The bend angle, in degrees, sets the angle between the straight line - * between the two points and the outgoing direction of the arrow from the - * start point. It must be within ±90°. A positive angle will produce a - * clockwise curve; a negative angle will produce a counterclockwise curve; - * zero (the default) will produce a straight line. Use true for 22.5°. + * The angle, a constant in degrees, between the straight line intersecting + * the arrow’s two control points and the outgoing tangent direction of the + * arrow from the start point. The angle must be within ±90°; a positive angle + * will produce a clockwise curve, while a negative angle will produce a + * counterclockwise curve; zero (the default) will produce a straight line. + * Use true for 22.5°. */ bend?: number | boolean; /** - * The **headAngle**, in degrees, determines how pointy the arrowhead is; it - * is typically between 0° and 180°. Defaults to 60. + * How pointy the arrowhead is, in degrees; a constant typically between 0° + * and 180°, and defaults to 60°. */ headAngle?: number; /** - * The **headLength** determines the scale of the arrowhead relative to the - * stroke width. Assuming the default of stroke width 1.5px, the - * **headLength** is the length of the arrowhead’s side in pixels. + * The size of the arrowhead relative to the **strokeWidth**; a constant. + * Assuming the default of stroke width 1.5px, this is the length of the + * arrowhead’s side in pixels. */ headLength?: number; /** - * Shorthand for **insetStart** and **insetEnd**. + * Shorthand to set the same default for **insetStart** and **insetEnd**. */ inset?: number; /** - * Inset at the start of the arrow, in pixels (useful if the arrow emerges - * from a dot). Defaults to 0. + * The starting inset, a constant in pixels; defaults to 0. A positive inset + * shortens the arrow by moving the starting point towards the endpoint point, + * while a negative inset extends it by moving the starting point in the + * opposite direction. A positive starting inset may be useful if the arrow + * emerges from a dot. */ insetStart?: number; /** - * Inset at the end of the arrow, in pixels (useful if the arrow points to a - * dot). Defaults to 0. + * The ending inset, a constant in pixels; defaults to 0. A positive inset + * shortens the arrow by moving the ending point towards the starting point, + * while a negative inset extends it by moving the ending point in the + * opposite direction. A positive ending inset may be useful if the arrow + * points to a dot. */ insetEnd?: number; } /** - * Draws (possibly swoopy) arrows connecting pairs of points. For example, to - * display arrows connecting two points in a scatterplot that represent the - * population vs income inequality in 1980 and 2015 for U.S. cities: + * Returns a new arrow mark for the given *data* and *options*, drawing + * (possibly swoopy) arrows connecting pairs of points. For example, to draw an + * arrow connecting an observation from 1980 with an observation from 2015 in a + * scatterplot of population and revenue inequality of U.S. cities: * * ```js * Plot.arrow(inequality, {x1: "POP_1980", y1: "R90_10_1980", x2: "POP_2015", y2: "R90_10_2015", bend: true}) * ``` - * - * The starting point is specified by **x1** and **y1**, and the ending point by - * **x2** and **y2** (or **x** for vertical arrows, and **y** for horizontal - * arrows). The arrow’s shape configuration options include the **bend** angle, - * **headAngle** and **headLength**, as well as insets (**insetEnd** and - * **insetStart**). - * - * The **stroke** defaults to currentColor. The **fill** defaults to none. The - * **strokeWidth** defaults to 1.5, and the **strokeMiterlimit** defaults to - * one. */ export function arrow(data?: Data, options?: ArrowOptions): Arrow; diff --git a/src/marks/link.d.ts b/src/marks/link.d.ts index 33dc34576b..f085b00516 100644 --- a/src/marks/link.d.ts +++ b/src/marks/link.d.ts @@ -59,7 +59,7 @@ export interface LinkOptions extends MarkOptions, MarkerOptions, CurveAutoOption /** * Returns a new link mark for the given *data* and *options*, drawing line - * segments (curves) to connect pairs of points. For example, to draw a link + * segments (curves) connecting pairs of points. For example, to draw a link * connecting an observation from 1980 with an observation from 2015 in a * scatterplot of population and revenue inequality of U.S. cities: *