labelArrow option (#1566)

* labelArrow option

* labelArrow docs (#1568)

* document labelArrow

* *up*, *right*, *down*, *left*

* axis options edits

* copy edits

---------

Co-authored-by: Mike Bostock <[email protected]>

---------

Co-authored-by: Philippe Rivière <[email protected]>

Author: mbostock

docs/features/legends.md

@@ -62,8 +62,8 @@ When an ordinal *color* scale is used redundantly with a *symbol* scale, the *sy
 ```js
 Plot.plot({
   grid: true,
-  x: {label: "Body mass (g) →"},
-  y: {label: "↑ Flipper length (mm)"},
+  x: {label: "Body mass (g)"},
+  y: {label: "Flipper length (mm)"},
   symbol: {legend: true},
   marks: [
     Plot.dot(penguins, {x: "body_mass_g", y: "flipper_length_mm", stroke: "species", symbol: "species"})

docs/features/scales.md

@@ -574,7 +574,7 @@ The **transform** scale option allows you to apply a function to all values befo
 Plot.plot({
   y: {
     grid: true,
-    label: `↑ Temperature (°C)`,
+    label: "Temperature (°C)",
     transform: (f) => (f - 32) * (5 / 9) // convert Fahrenheit to Celsius
   },
   marks: [
@@ -624,7 +624,7 @@ Plot.plot({
   },
   y: {
     transform: (d) => d / 1e6,
-    label: "↑ Daily trade volume (millions)"
+    label: "Daily trade volume (millions)"
   },
   marks: [
     Plot.barY(aapl.slice(-40), {x: "Date", y: "Volume"}),
@@ -723,7 +723,7 @@ The **transform** option allows you to apply a function to all values before the
 ```js
 Plot.plot({
   y: {
-    label: "↑ Temperature (°F)",
+    label: "Temperature (°F)",
     transform: (f) => f * 9 / 5 + 32 // convert Celsius to Fahrenheit
   },
   marks: …
@@ -935,24 +935,28 @@ For a *band* scale, you can further fine-tune padding:
 
 Align defaults to 0.5 (centered). Band scale padding defaults to 0.1 (10% of available space reserved for separating bands), while point scale padding defaults to 0.5 (the gap between the first point and the edge is half the distance of the gap between points, and likewise for the gap between the last point and the opposite edge). Note that rounding and mark insets (e.g., for bars and rects) also affect separation between adjacent marks.
 
-Plot automatically generates [axis](../marks/axis.md) and optionally [grid](../marks/grid.md) marks for position scales. (For more control, declare these marks explicitly.) You can configure the implicit axes with the following scale options:
+Plot implicitly generates an [axis mark](../marks/axis.md) for position scales if one is not explicitly declared. (For more control, declare the axis mark explicitly.) The following [axis mark options](../marks/axis.md#axis-options) are also available as scale options, applying to the implicit axis:
 
-* **axis** - *top* or *bottom* (or *both*) for *x* and *fx*; *left* or *right* (or *both*) for *y* and *fy*; null to suppress
+* **axis** - the axis **anchor**: *top*, *bottom* (*x* or *fx*); *left*, *right* (*y* or *fy*); *both*; null to suppress
 * **ticks** - the approximate number of ticks to generate, or interval, or array of values
-* **tickSize** - the length of each tick (in pixels; default 6 for *x* and *y*, or 0 for *fx* and *fy*)
 * **tickSpacing** - the approximate number of pixels between ticks (if **ticks** is not specified)
+* **tickSize** - the length of each tick (in pixels; default 6 for *x* and *y*, or 0 for *fx* and *fy*)
 * **tickPadding** - the separation between the tick and its label (in pixels; default 3)
 * **tickFormat** - either a function or specifier string to format tick values; see [Formats](./formats.md)
 * **tickRotate** - whether to rotate tick labels (an angle in degrees clockwise; default 0)
-* **grid** - whether to draw grid lines across the plot for each tick
-* **line** - if true, draw the axis line (only for *x* and *y*)
+* **fontVariant** - the font-variant attribute for ticks; defaults to *tabular-nums* if quantitative
 * **label** - a string to label the axis
 * **labelAnchor** - the label anchor: *top*, *right*, *bottom*, *left*, or *center*
+* **labelArrow** - the label arrow: *auto* (default), *up*, *right*, *down*, *left*, *none*, or true
 * **labelOffset** - the label position offset (in pixels; default depends on margins and orientation)
-* **fontVariant** - the font-variant attribute for ticks; defaults to *tabular-nums* if quantitative
 * **ariaLabel** - a short label representing the axis in the accessibility tree
 * **ariaDescription** - a textual description for the axis
 
+For an implicit [grid mark](../marks/grid.md), use the **grid** option. For an implicit [frame mark](../marks/frame.md) along one edge of the frame, use the **line** option.
+
+* **grid** - whether to draw grid lines across the plot for each tick
+* **line** - if true, draw the axis line (only for *x* and *y*)
+
 Top-level options are also supported as shorthand: **grid** (for *x* and *y* only; see [facets](./facets.md)), **label**, **axis**, **inset**, **round**, **align**, and **padding**. If the **grid** option is true, show a grid using *currentColor*; if specified as a string, show a grid with the specified color; if an approximate number of ticks, an interval, or an array of tick values, show corresponding grid lines.
 
 ## Sort mark option

docs/features/transforms.md

@@ -28,7 +28,7 @@ For example, given a [dataset of highway traffic](https://gist.github.com/chrtze
 ```js
 Plot.plot({
   marginLeft: 120,
-  x: {label: "Vehicles per hour (thousands) →", transform: (x) => x / 1000},
+  x: {label: "Vehicles per hour (thousands)", transform: (x) => x / 1000},
   y: {label: null},
   marks: [
     Plot.ruleX([0]),
@@ -149,7 +149,7 @@ For greater control, you can also implement a custom **transform** function, all
 Plot.plot({
   y: {
     grid: true,
-    label: "↑ Unemployment (%)"
+    label: "Unemployment (%)"
   },
   color: {
     domain: [false, true],

docs/marks/area.md

@@ -67,7 +67,7 @@ When the baseline is not *y* = 0 but instead represents another dimension of dat
 ```js
 Plot.plot({
   y: {
-    label: "↑ Temperature (°F)",
+    label: "Temperature (°F)",
     grid: true
   },
   marks: [
@@ -160,7 +160,7 @@ If a **fill** channel is specified, it is assumed to be ordinal or nominal; data
 Plot.plot({
   y: {
     transform: (d) => d / 1000,
-    label: "↑ Unemployed (thousands)"
+    label: "Unemployed (thousands)"
   },
   marks: [
     Plot.areaY(industries, {x: "date", y: "unemployed", fill: "industry"}),
@@ -181,7 +181,7 @@ Or, as a streamgraph with the **offset** stack transform option:
 Plot.plot({
   y: {
     transform: (d) => d / 1000,
-    label: "↑ Unemployed (thousands)"
+    label: "Unemployed (thousands)"
   },
   marks: [
     Plot.areaY(industries, {x: "date", y: "unemployed", fill: "industry", offset: "wiggle"}),

docs/marks/arrow.md

@@ -23,10 +23,10 @@ Plot.plot({
   inset: 10,
   x: {
     type: "log",
-    label: "Population →"
+    label: "Population"
   },
   y: {
-    label: "↑ Inequality",
+    label: "Inequality",
     ticks: 4
   },
   color: {

docs/marks/axis.md

@@ -76,7 +76,7 @@ Plot.plot({
   y: {percent: true},
   marks: [
     Plot.axisX({label: null, lineWidth: 8, marginBottom: 40}),
-    Plot.axisY({label: "↑ Responses (%)"}),
+    Plot.axisY({label: "Responses (%)"}),
     Plot.barY(responses, {x: "name", y: "value"}),
     Plot.ruleY([0])
   ]
@@ -91,7 +91,7 @@ Or, you can use the **textAnchor** option to extend the *y*-axis tick labels to
 Plot.plot({
   marginTop: 0,
   marginLeft: 4,
-  x: {ticks: 4, label: "Yield (kg) →"},
+  x: {ticks: 4, label: "Yield (kg)"},
   marks: [
     Plot.barX([42, 17, 32], {y: ["🍌 banana", "🍎 apple", "🍐 pear"]}),
     Plot.axisY({textAnchor: "start", fill: "var(--vp-c-bg)", dx: 14})
@@ -349,20 +349,23 @@ Note that when an axis mark is declared explicitly (via the [**marks** plot opti
 
 In addition to the [standard mark options](../features/marks.md), the axis mark supports the following options:
 
-* **anchor** - the orientation: *top*, *bottom* (*x* or *fx*); *left*, *right* (*y* or *fy*); *both*; null to suppress
+* **anchor** - the axis orientation: *top* or *bottom* for *x* or *fx*; *left* or *right* for *y* or *fy*
 * **tickSize** - the length of the tick vector (in pixels; default 6 for *x* or *y*, or 0 for *fx* or *fy*)
 * **tickPadding** - the separation between the tick vector and its label (in pixels; default 3)
 * **tickFormat** - either a function or specifier string to format tick values; see [Formats](../features/formats.md)
 * **tickRotate** - whether to rotate tick labels (an angle in degrees clockwise; default 0)
-* **fontVariant** - the font-variant attribute for ticks; defaults to tabular-nums for quantitative axes
+* **fontVariant** - the ticks’ font-variant; defaults to *tabular-nums* for quantitative axes
 * **label** - a string to label the axis; defaults to the scale’s label, perhaps with an arrow
 * **labelAnchor** - the label anchor: *top*, *right*, *bottom*, *left*, or *center*
+* **labelArrow** - the label arrow: *auto* (default), *up*, *right*, *down*, *left*, *none*, or true
 * **labelOffset** - the label position offset (in pixels; default depends on margins and orientation)
 * **color** - the color of the ticks and labels (defaults to *currentColor*)
 * **textStroke** - the color of the stroke around tick labels (defaults to *none*)
 * **textStrokeOpacity** - the opacity of the stroke around tick labels
 * **textStrokeWidth** - the thickness of the stroke around tick labels (in pixels)
 
+The **labelArrow** option controls the arrow (↑, →, ↓, or ←) added to the axis label indicating the direction of ascending value; for example, horizontal position *x* typically increases in value going right→, while vertical position *y* typically increases in value going up↑. If *auto* (the default), the arrow will be added only if the scale is quantitative or temporal; if true, the arrow will also apply to ordinal scales, provided the domain is consistently ordered.
+
 As a composite mark, the **stroke** option affects the color of the tick vector, while the **fill** option affects the color the text labels; both default to the **color** option, which defaults to *currentColor*. The **x** and **y** channels, if specified, position the ticks; if not specified, the tick positions depend on the axis **anchor**. The orientation of the tick labels likewise depends on the **anchor**. See the [text mark](./text.md) for details on available options for the tick and axis labels.
 
 The axis mark’s [**facetAnchor**](../features/facets.md) option defaults to *top-empty* if anchor is *top*, *right-empty* if anchor is *right*, *bottom-empty* if anchor is *bottom*, and *left-empty* if anchor is *left*. This ensures the proper positioning of the axes with respect to empty facets.

docs/marks/bar.md

@@ -53,7 +53,7 @@ Above, since **y** was specified instead of **y1** and **y2**, the bar spans fro
 ```js
 Plot.plot({
   marginLeft: 60,
-  x: {label: "Frequency →"},
+  x: {label: "Frequency"},
   y: {label: null},
   color: {legend: true},
   marks: [
@@ -201,7 +201,7 @@ Plot.plot({
   marginLeft: 60,
   marginRight: 60,
   label: null,
-  x: {label: "Frequency →"},
+  x: {label: "Frequency"},
   y: {padding: 0},
   marks: [
     Plot.barX(penguins, {fy: "island", y: "sex", x: 1, inset: 0.5}),

docs/marks/box.md

@@ -65,11 +65,11 @@ Plot.plot({
   marginLeft: 60,
   y: {
     grid: true,
-    label: "↑ Price"
+    label: "Price"
   },
   x: {
     interval: 0.5,
-    label: "Carats →",
+    label: "Carats",
     labelAnchor: "right",
     tickFormat: (x) => x.toFixed(1)
   },
@@ -89,11 +89,11 @@ Plot.plot({
   marginLeft: 60,
   y: {
     grid: true,
-    label: "↑ Price"
+    label: "Price"
   },
   fx: {
     interval: 0.5,
-    label: "Carats →",
+    label: "Carats",
     labelAnchor: "right",
     tickFormat: (x) => x.toFixed(1)
   },

docs/marks/cell.md

@@ -95,8 +95,9 @@ Plot.plot({
   x: {
     ticks: simpsons.filter((d) => d.number_in_season === 1).map((d) => d.id),
     tickFormat: (x) => simpsons.find((d) => d.id === x).season,
-    label: "Season →",
-    labelAnchor: "right"
+    label: "Season",
+    labelAnchor: "right",
+    labelArrow: true
   },
   color: {
     type: "linear",

docs/marks/contour.md

@@ -91,8 +91,8 @@ We can visualize this small grid directly with a [text mark](./text.md) using th
 ```js
 Plot.plot({
   grid: true,
-  x: {domain: [0, grid.width], label: "column →"},
-  y: {domain: [0, grid.height], label: "↑ row"},
+  x: {domain: [0, grid.width], label: "column"},
+  y: {domain: [0, grid.height], label: "row"},
   marks: [
     Plot.text(grid.values, {
       text: Plot.identity,
@@ -208,8 +208,8 @@ As an alternative to interpolating discrete samples, you can supply values as a
 ```js
 Plot.plot({
   aspectRatio: 1,
-  x: {tickSpacing: 80, label: "x →"},
-  y: {tickSpacing: 80, label: "↑ y"},
+  x: {tickSpacing: 80, label: "x"},
+  y: {tickSpacing: 80, label: "y"},
   color: {type: "diverging", legend: true, label: "sin(x) cos(y)"},
   marks: [
     Plot.contour({