numeric interval & documentation (#552)

Author: Fil

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Observable Plot - Changelog
 
+## 0.3.0
+
+*Not yet released.* These notes are a work in progress.
+
+### Marks
+
+The rect marks now accept an *interval* option that allows to derive *x1* and *x2* from *x*. A typical use case is an interval: d3.utcDay which creates a rect spanning the whole day that contains a certain date-time. The interval can be specified as an object with *floor** method that returns *x1* from *x* and an **offset** method that returns *x2* from *x1*. If the interval is specified as a (non-null) number, *x1* and *x2* are taken as the two consecutive multiples of *n* that bracket *x*.
+
 ## 0.2.1
 
 Released September 19, 2021.

README.md

@@ -801,7 +801,9 @@ The following channels are optional:
 * **x2** - the ending horizontal position; bound to the *x* scale
 * **y2** - the ending vertical position; bound to the *y* scale
 
-Typically either **x1** and **x2** are specified, or **y1** and **y2**, or both. The rect mark supports the [standard mark options](#marks), including insets and rounded corners. The **stroke** defaults to none. The **fill** defaults to currentColor if the stroke is none, and to none otherwise.
+Typically either **x1** and **x2** are specified, or **y1** and **y2**, or both. **x1** and **x2** can be derived from **x** and an **interval** object (such as d3.utcDay) with a **floor** method that returns *x1* from *x* and an **offset** method that returns *x2* from *x1*. If the interval is specified as a number *n*, *x1* and *x2* are taken as the two consecutive multiples of *n* that bracket *x*. The interval may be specified either as as {x, interval} or x: {value, interval}—typically to apply different intervals to x and y.
+
+The rect mark supports the [standard mark options](#marks), including insets and rounded corners. The **stroke** defaults to none. The **fill** defaults to currentColor if the stroke is none, and to none otherwise.
 
 #### Plot.rect(*data*, *options*)
 

src/transforms/interval.js

@@ -6,6 +6,11 @@ import {maybeInsetX, maybeInsetY} from "./inset.js";
 // chose between UTC and local time (or better, an explicit timeZone option).
 function maybeInterval(interval) {
   if (interval == null) return;
+  if (typeof interval === "number") {
+    const n = interval;
+    // Note: this offset doesn’t support the optional step argument for simplicity.
+    interval = {floor: d => n * Math.floor(d / n), offset: d => d + n};
+  }
   if (typeof interval.floor !== "function" || typeof interval.offset !== "function") throw new Error("invalid interval");
   return interval;
 }