document interval-aware group transform

docs/features/scales.md

@@ -638,6 +638,8 @@ Plot.plot({
 As an added bonus, the **fontVariant** and **type** options are no longer needed because Plot now understands that the *x* scale, despite being *ordinal*, represents daily observations.
 :::
 
+While the example above relies on the **interval** being promoted to the scale’s **transform**, the [stack](../transforms/stack.md), [bin](../transforms/bin.md), and [group](../transforms/group.md) transforms are also interval-aware: they apply the scale’s **interval**, if any, *before* grouping values. (This results in the interval being applied twice, both before and after the mark transform, but the second application has no effect since interval application is idempotent.)
+
 The **interval** option can also be used for quantitative and temporal scales. This enforces uniformity, say rounding timed observations down to the nearest hour, which may be helpful for the [stack transform](../transforms/stack.md) among other uses.
 
 ## Scale options

docs/features/transforms.md

@@ -175,7 +175,7 @@ Plot.plot({
 ```
 :::
 
-The **transform** function is passed two arguments, *data* and *facets*, representing the mark’s data and facet indexes; it must then return a {*data*, *facets*} object with the transformed data and facet indexes. The *facets* are represented as a nested array of arrays such as [[0, 1, 3, …], [2, 5, 10, …], …]; each element in *facets* specifies the zero-based indexes of elements in *data* that are in a given facet (*i.e.*, have a distinct value in the associated *fx* or *fy* dimension).
+The **transform** function is passed three arguments, *data*, *facets*, and *options* representing the mark’s data and facet indexes, and the plot’s options; it must then return a {*data*, *facets*} object with the transformed data and facet indexes. The *facets* are represented as a nested array of arrays such as [[0, 1, 3, …], [2, 5, 10, …], …]; each element in *facets* specifies the zero-based indexes of elements in *data* that are in a given facet (*i.e.*, have a distinct value in the associated *fx* or *fy* dimension).
 
 If the **transform** option is specified, it supersedes any basic transforms (*i.e.*, the **filter**, **sort** and **reverse** options are ignored). However, the **transform** option is rarely used directly; instead one of Plot’s built-in transforms are used, and these transforms automatically compose with the basic **filter**, **sort** and **reverse** transforms.
 

src/transforms/basic.d.ts

@@ -1,17 +1,22 @@
+import type {PlotOptions} from "../plot.js";
 import type {ChannelName, Channels, ChannelValue} from "../channel.js";
 import type {Context} from "../context.js";
 import type {Dimensions} from "../dimensions.js";
 import type {ScaleFunctions} from "../scales.js";
 
 /**
- * A mark transform function is passed the mark’s *data* and a nested index into
- * the data, *facets*. The transform function returns new mark data and facets;
- * the returned **data** defaults to the passed *data*, and the returned
- * **facets** defaults to the passed *facets*. The mark is the *this* context.
- * Transform functions can also trigger side-effects, say to populate
- * lazily-derived columns; see also Plot.column.
+ * A mark transform function is passed the mark’s *data*, a nested index into
+ * the data, *facets*, and the plot’s *options*. The transform function returns
+ * new mark data and facets; the returned **data** defaults to the passed
+ * *data*, and the returned **facets** defaults to the passed *facets*. The mark
+ * is the *this* context. Transform functions can also trigger side-effects, say
+ * to populate lazily-derived columns; see also Plot.column.
  */
-export type TransformFunction = (data: any[], facets: number[][]) => {data?: any[]; facets?: number[][]};
+export type TransformFunction = (
+  data: any[],
+  facets: number[][],
+  options?: PlotOptions
+) => {data?: any[]; facets?: number[][]};
 
 /**
  * A mark initializer function is passed the mark’s (possibly transformed)