Update CHANGELOG, README

CHANGELOG.md

@@ -4,12 +4,30 @@
 
 *Not yet released. These are forthcoming changes in the main branch.*
 
-The new [box mark](./README.md#box) (TODO documentation) generates a horizontal or vertical boxplot suitable for visualizing one-dimensional distributions. It is a convenience mark that composites a rule, bar, tick, and dot.
+The new [box mark](./README.md#box) generates a horizontal or vertical boxplot suitable for visualizing one-dimensional distributions. It is a convenience mark that composites a rule, bar, tick, and dot.
 
-Plot’s shorthand syntax has been expanded. The [bar mark](./README.md#bar) now supports one-dimensional shorthand: if no *options* are specified, then Plot.barX and Plot.barY can be used to visualize an array of numbers. This shorthand also now applies to the [rect mark](./README.md#rect) and the [vector mark](./README.md#vector). The [area mark](./README.md#area) now supports two-dimensional shorthand: if no *options* are specified, then Plot.area can be used to visualize an array of [x, y] tuples (similar to Plot.line).
+<img src="./img/box.png" width="640" alt="a boxplot of Michelson’s 1879 measurements of the speed of light">
+
+```js
+Plot.boxX(morley, {x: "Speed", y: "Expt"}).plot({x: {grid: true, inset: 6}})
+```
+
+[Plot’s shorthand syntax](https://observablehq.com/@observablehq/plot-shorthand) has been expanded. The [bar mark](./README.md#bar) now supports one-dimensional shorthand: if no *options* are specified, then Plot.barX and Plot.barY can be used to visualize an array of numbers. This shorthand also now applies to the [rect mark](./README.md#rect) and the [vector mark](./README.md#vector). The [area mark](./README.md#area) now supports two-dimensional shorthand: if no *options* are specified, then Plot.area can be used to visualize an array of [x, y] tuples (similar to Plot.line).
+
+<img src="./img/bar-shorthand.png" width="640" alt="a bar chart of twenty random values">
+
+```js
+Plot.barY(d3.range(20).map(Math.random)).plot()
+```
 
 The mark [sort options](./README.md#sort-options) now support implicit “width” and “height” channels, defined as |*x2* - *x1*| and |*y2* - *y1*| respectively. These channels are useful for sorting rects and bars by length. The *reverse* option defaults to true when sorting by these channels. When sorting by *y*, but not *y* channel is available, sorting will now fallback to sorting by *y2* if available; the same fallback logic applies to *x* and *x2*. (This behavior was previously supported on marks that support implicit stacking, but now applies universally to all marks.)
 
+<img src="./img/sort-length.png" width="640" alt="a bar chart of energy production by source from 1949 to present, with categorical colors assigned in order of the tallest bar">
+
+```js
+Plot.rectY(energy, {x: "Year", interval: 1, y: "Value", fill: "Description", sort: {color: "height"}})
+```
+
 The [bin transform](./README.md#bin) now supports *x* and *y* reducers, which represent the respective midpoint of the bin: (*x1* + *x2*) / 2 and (*y1* + *y2*) / 2 respectively. The [bin](./README.md#bin), [group](./README.md#group), and [window](./README.md#window) transforms now support percentile reducers of the form *pXX* where *XX* is a number in [00, 99]. For example *p25* represents the first quartile and *p75* represents the third quartile.
 
 The error message when attempting to create a standalone legend without a valid scale definition has been improved. The high cardinality warning for the implicit *z* channel has been relaxed; it is now only triggered if more than half of the values are distinct. When the axis *ticks* option is specified as null, no ticks are generated. When the axis *tickFormat* option is specified as null, no tick labels are generated.

README.md

@@ -801,6 +801,43 @@ In addition to the [standard bar channels](#bar), the following optional channel
 
 If the **x** channel is not specified, the bar will span the full horizontal extent of the plot (or facet).
 
+### Box
+
+[<img src="./img/box.png" width="640" alt="a boxplot of Michelson’s 1879 measurements of the speed of light">](https://observablehq.com/@observablehq/plot-box)
+
+[Source](./src/marks/box.js) · [Examples](https://observablehq.com/@observablehq/plot-box) · Draws either horizontal boxplots where *x* is quantitative and *y* is ordinal (if present) or vertical boxplots where *y* is quantitative and *x* is ordinal (if present). Boxplots are often used to visualize one-dimensional distributions as an alternative to a histogram. (See also the [bin transform](#bin).)
+
+The box mark is a composite mark consisting of four marks:
+
+* a [rule](#rule) representing the extreme values (not including outliers)
+* a [bar](#bar) representing the interquartile range (trimmed to the data)
+* a [tick](#tick) represent the median value, and
+* a [dot](#dot) representing outliers, if any
+
+The given *options* are passed through to these underlying marks, with the expection of the following options:
+
+* **fill** - the fill color of the bar; defaults to gray
+* **fillOpacity** - the fill opacity of the bar; defaults to 1
+* **stroke** - the stroke color of the rule, tick, and dot; defaults to *currentColor*
+* **strokeOpacity** - the stroke opacity of the rule, tick, and dot; defaults to 1
+* **strokeWidth** - the stroke width of the tick; defaults to 1
+
+#### Plot.boxX(*data*, *options*)
+
+```js
+Plot.boxX(simpsons.map(d => d.imdb_rating))
+```
+
+Returns a horizontal boxplot mark. If the **x** option is not specified, it defaults to the identity function, as when *data* is an array of numbers. If the **y** option is not specified, it defaults to null; if the **y** option is specified, it should represent an ordinal (discrete) value.
+
+#### Plot.boxY(*data*, *options*)
+
+```js
+Plot.boxY(simpsons.map(d => d.imdb_rating))
+```
+
+Returns a vertical boxplot mark. If the **y** option is not specified, it defaults to the identity function, as when *data* is an array of numbers. If the **x** option is not specified, it defaults to null; if the **x** option is specified, it should represent an ordinal (discrete) value.
+
 ### Cell
 
 [<img src="./img/cell.png" width="320" height="320" alt="a heatmap">](https://observablehq.com/@observablehq/plot-cell)