axis mark

README.md

@@ -310,6 +310,8 @@ Plot automatically generates axes for position scales. You can configure these a
 * *scale*.**ariaLabel** - a short label representing the axis in the accessibility tree
 * *scale*.**ariaDescription** - a textual description for the axis
 
+Or use independent [axis](#axis) and [grid](#grid) marks for more extensive possibilities.
+
 Top-level options are also supported as shorthand: **grid** (for *x* and *y* only; see [facet.grid](#facet-options)), **label**, **axis**, **inset**, **round**, **align**, and **padding**.
 
 ### Projection options
@@ -958,6 +960,46 @@ Returns a new arrow with the given *data* and *options*.
 
 <!-- jsdocEnd arrow -->
 
+### Axis
+
+[Source](./src/marks/axis.js) · [Examples](https://observablehq.com/@observablehq/plot-axis) · Draws an axis.
+
+Plot automatically generates axes for position scales, and draws them below the other marks. Each axis is composed of up to 5 marks: a grid, and an axis mark which might contain a line, ticks, tick labels, and axis label.
+
+When you need more control, you can add axis and grid marks explicitely in the marks options. Note that Plot’s automatic axis for *x* is disabled when a mark’s aria-label property begins by `x-axis `—and likewise for *y*, *fx* and *fy*.
+
+#### Plot.axisX(*data*, *options*)
+
+<!-- jsdoc axisX -->
+
+```js
+Plot.axisX(inequality, {x1: "POP_1980", y1: "R90_10_1980", x2: "POP_2015", y2: "R90_10_2015", bend: true})
+```
+
+Returns a new axis with the given *data* and *options*.
+
+The optional *data* is an array of tick values—it defaults to the scale’s ticks.
+
+The axis options described in [position options](#position-options) are all supported, except the **grid** option which is handled by the [grid](#grid) mark. The *axis* option, in this context, is called **anchor** and is one of *top* or *bottom*. The **color** option controls both **stroke** for the ticks, and the **fill** for labels.
+
+The **y** channel, if any, describes the vertical position of the tick. Defaults to the axis anchor.
+
+<!-- jsdocEnd axisX -->
+
+#### Plot.axisY(*data*, *options*)
+
+…same…
+
+
+#### Plot.axisFx(*data*, *options*)
+
+…same…
+
+#### Plot.axisFy(*data*, *options*)
+
+…same…
+
+
 ### Bar
 
 [<img src="./img/bar.png" width="320" height="198" alt="a bar chart">](https://observablehq.com/@observablehq/plot-bar)
@@ -1358,6 +1400,50 @@ Plot.graticule()
 
 Returns a new geo mark with a [default 10° global graticule](https://github.com/d3/d3-geo/blob/main/README.md#geoGraticule10) geometry object and the given *options*.
 
+### Grid
+
+[Source](./src/marks/axis.js) · [Examples](https://observablehq.com/@observablehq/plot-axis) · Draws an axis-aligned grid.
+
+#### Plot.gridX(*data*, *options*)
+
+<!-- jsdoc gridX -->
+
+```js
+Plot.gridX({ strokeDasharray: "5,3" })
+```
+
+Returns a new grid with the given *data* and *options*.
+
+The optional *data* is an array of tick values—it defaults to the scale’s ticks. The grid mark draws a line for each tick value, across the whole frame.
+
+The following options are supported:
+* **strokeDasharray** - the [stroke dasharray](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray) for dashed lines, defaults to null
+
+The following options are supported as constant or data-driven channels:
+* **stroke** - the grid color, defaults to currentColor
+* **strokeWidth** - the grid’s line width, defaults to 1
+* **strokeOpacity** - the stroke opacity, defaults to 0.1
+* **y1** - the start of the line, a channel of y positions.
+* **y2** - the end of the line, a channel of y positions.
+
+All the other common options are supported when applicable (e.g., **title**).
+
+<!-- jsdocEnd gridX -->
+
+#### Plot.gridY(*data*, *options*)
+
+…same…
+
+
+#### Plot.gridFx(*data*, *options*)
+
+…same…
+
+#### Plot.gridFy(*data*, *options*)
+
+…same…
+
+
 ### Hexgrid
 
 The hexgrid mark can be used to support marks using the [hexbin](#hexbin) layout.

src/axes.js

@@ -1,172 +1,22 @@
-import {extent} from "d3";
-import {AxisX, AxisY} from "./axis.js";
-import {formatDefault} from "./format.js";
-import {isOrdinalScale, isTemporalScale, scaleOrder} from "./scales.js";
-import {position, registry} from "./scales/index.js";
-
-export function Axes(
-  {x: xScale, y: yScale, fx: fxScale, fy: fyScale},
-  {
-    x = {},
-    y = {},
-    fx = {},
-    fy = {},
-    axis = true,
-    grid,
-    line,
-    label,
-    facet: {axis: facetAxis = axis, grid: facetGrid, label: facetLabel = label} = {}
-  } = {}
-) {
-  let {axis: xAxis = axis} = x;
-  let {axis: yAxis = axis} = y;
-  let {axis: fxAxis = facetAxis} = fx;
-  let {axis: fyAxis = facetAxis} = fy;
-  if (!xScale) xAxis = null;
-  else if (xAxis === true) xAxis = "bottom";
-  if (!yScale) yAxis = null;
-  else if (yAxis === true) yAxis = "left";
-  if (!fxScale) fxAxis = null;
-  else if (fxAxis === true) fxAxis = xAxis === "bottom" ? "top" : "bottom";
-  if (!fyScale) fyAxis = null;
-  else if (fyAxis === true) fyAxis = yAxis === "left" ? "right" : "left";
-  return {
-    ...(xAxis && {x: new AxisX(xScale, {grid, line, label, ...x, axis: xAxis})}),
-    ...(yAxis && {y: new AxisY(yScale, {grid, line, label, ...y, axis: yAxis})}),
-    ...(fxAxis && {fx: new AxisX(fxScale, {name: "fx", grid: facetGrid, label: facetLabel, ...fx, axis: fxAxis})}),
-    ...(fyAxis && {fy: new AxisY(fyScale, {name: "fy", grid: facetGrid, label: facetLabel, ...fy, axis: fyAxis})})
-  };
-}
-
-// Mutates axis.ticks!
-// TODO Populate tickFormat if undefined, too?
-export function autoAxisTicks({x, y, fx, fy}, {x: xAxis, y: yAxis, fx: fxAxis, fy: fyAxis}) {
-  if (fxAxis) autoAxisTicksK(fx, fxAxis, 80);
-  if (fyAxis) autoAxisTicksK(fy, fyAxis, 35);
-  if (xAxis) autoAxisTicksK(x, xAxis, 80);
-  if (yAxis) autoAxisTicksK(y, yAxis, 35);
-}
-
-function autoAxisTicksK(scale, axis, k) {
-  if (axis.ticks === undefined) {
-    const interval = scale.interval;
-    if (interval !== undefined) {
-      const [min, max] = extent(scale.scale.domain());
-      axis.ticks = interval.range(interval.floor(min), interval.offset(interval.floor(max)));
-    } else {
-      const [min, max] = extent(scale.scale.range());
-      axis.ticks = (max - min) / k;
-    }
-  }
-  // D3’s ordinal scales simply use toString by default, but if the ordinal
-  // scale domain (or ticks) are numbers or dates (say because we’re applying a
-  // time interval to the ordinal scale), we want Plot’s default formatter.
-  if (axis.tickFormat === undefined && isOrdinalScale(scale)) {
-    axis.tickFormat = formatDefault;
-  }
-}
-
-// Mutates axis.{label,labelAnchor,labelOffset} and scale.label!
-export function autoScaleLabels(channels, scales, {x, y, fx, fy}, dimensions, options) {
-  if (fx) {
-    autoAxisLabelsX(fx, scales.fx, channels.get("fx"));
-    if (fx.labelOffset === undefined) {
-      const {facetMarginTop, facetMarginBottom} = dimensions;
-      fx.labelOffset = fx.axis === "top" ? facetMarginTop : facetMarginBottom;
-    }
-  }
-  if (fy) {
-    autoAxisLabelsY(fy, fx, scales.fy, channels.get("fy"));
-    if (fy.labelOffset === undefined) {
-      const {facetMarginLeft, facetMarginRight} = dimensions;
-      fy.labelOffset = fy.axis === "left" ? facetMarginLeft : facetMarginRight;
-    }
-  }
-  if (x) {
-    autoAxisLabelsX(x, scales.x, channels.get("x"));
-    if (x.labelOffset === undefined) {
-      const {marginTop, marginBottom, facetMarginTop, facetMarginBottom} = dimensions;
-      x.labelOffset = x.axis === "top" ? marginTop - facetMarginTop : marginBottom - facetMarginBottom;
-    }
-  }
-  if (y) {
-    autoAxisLabelsY(y, x, scales.y, channels.get("y"));
-    if (y.labelOffset === undefined) {
-      const {marginRight, marginLeft, facetMarginLeft, facetMarginRight} = dimensions;
-      y.labelOffset = y.axis === "left" ? marginLeft - facetMarginLeft : marginRight - facetMarginRight;
-    }
-  }
-  for (const [key, type] of registry) {
-    if (type !== position && scales[key]) {
-      // not already handled above
-      autoScaleLabel(key, scales[key], channels.get(key), options[key]);
-    }
-  }
-}
-
-// Mutates axis.labelAnchor, axis.label, scale.label!
-function autoAxisLabelsX(axis, scale, channels) {
-  if (axis.labelAnchor === undefined) {
-    axis.labelAnchor = isOrdinalScale(scale) ? "center" : scaleOrder(scale) < 0 ? "left" : "right";
-  }
-  if (axis.label === undefined) {
-    axis.label = inferLabel(channels, scale, axis, "x");
-  }
-  scale.label = axis.label;
-}
-
-// Mutates axis.labelAnchor, axis.label, scale.label!
-function autoAxisLabelsY(axis, opposite, scale, channels) {
-  if (axis.labelAnchor === undefined) {
-    axis.labelAnchor = isOrdinalScale(scale)
-      ? "center"
-      : opposite && opposite.axis === "top"
-      ? "bottom" // TODO scaleOrder?
-      : "top";
-  }
-  if (axis.label === undefined) {
-    axis.label = inferLabel(channels, scale, axis, "y");
-  }
-  scale.label = axis.label;
-}
-
-// Mutates scale.label!
-function autoScaleLabel(key, scale, channels, options) {
-  if (options) {
-    scale.label = options.label;
-  }
-  if (scale.label === undefined) {
-    scale.label = inferLabel(channels, scale, null, key);
-  }
-}
-
-// Channels can have labels; if all the channels for a given scale are
-// consistently labeled (i.e., have the same value if not undefined), and the
-// corresponding axis doesn’t already have an explicit label, then the channels’
-// label is promoted to the corresponding axis.
-function inferLabel(channels = [], scale, axis, key) {
-  let candidate;
-  for (const {label} of channels) {
-    if (label === undefined) continue;
-    if (candidate === undefined) candidate = label;
-    else if (candidate !== label) return;
-  }
-  if (candidate !== undefined) {
-    // Ignore the implicit label for temporal scales if it’s simply “date”.
-    if (isTemporalScale(scale) && /^(date|time|year)$/i.test(candidate)) return;
-    if (!isOrdinalScale(scale)) {
-      if (scale.percent) candidate = `${candidate} (%)`;
-      if (key === "x" || key === "y") {
-        const order = scaleOrder(scale);
-        if (order) {
-          if (key === "x" || (axis && axis.labelAnchor === "center")) {
-            candidate = (key === "x") === order < 0 ? `← ${candidate}` : `${candidate} →`;
-          } else {
-            candidate = `${order < 0 ? "↑ " : "↓ "}${candidate}`;
-          }
-        }
-      }
-    }
-  }
-  return candidate;
+import {format, utcFormat} from "d3";
+import {formatIsoDate} from "./format.js";
+import {constant, isTemporal, string} from "./options.js";
+import {isOrdinalScale} from "./scales.js";
+
+export function inferFontVariant(scale) {
+  return isOrdinalScale(scale) && scale.interval === undefined ? undefined : "tabular-nums";
+}
+
+// D3 doesn’t provide a tick format for ordinal scales; we want shorthand when
+// an ordinal domain is numbers or dates, and we want null to mean the empty
+// string, not the default identity format. TODO Remove this in favor of the
+// axis mark’s inferTickFormat.
+export function maybeAutoTickFormat(tickFormat, domain) {
+  return tickFormat === undefined
+    ? isTemporal(domain)
+      ? formatIsoDate
+      : string
+    : typeof tickFormat === "function"
+    ? tickFormat
+    : (typeof tickFormat === "string" ? (isTemporal(domain) ? utcFormat : format) : constant)(tickFormat);
 }