@uwdata/mosaic-spec 0.9.0 → 0.11.0

package/src/spec/Param.ts

@@ -58,6 +58,20 @@ export interface Selection {
    * but not oneself (default `false`, except for `crossfilter` selections).
    */
   cross?: boolean;
+
+  /**
+   * A flag for setting an initial empty selection state. If true, a selection
+   * with no clauses corresponds to an empty selection with no records. If
+   * false, a selection with no clauses selects all values.
+   */
+  empty?: boolean;
+
+  /**
+   * Upstream selections whose clauses should be included as part of this
+   * selection. Any clauses or activations published to the upstream
+   * selections will be relayed to this selection.
+   */
+  include?: ParamRef | ParamRef[];
 }
 
 /** A Param or Selection definition. */

package/src/spec/PlotAttribute.ts

@@ -1556,6 +1556,13 @@ export interface PlotAttributes {
    */
   rNice?: boolean | number| Interval | ParamRef;
 
+  /**
+   * A textual label to show on the axis or legend; if null, show no label. By
+   * default the scale label is inferred from channel definitions, possibly with
+   * an arrow (↑, →, ↓, or ←) to indicate the direction of increasing value.
+   */
+  rLabel?: string | null | ParamRef;
+
   /**
    * If true, shorthand for a transform suitable for percentages, mapping
    * proportions in [0, 1] to [0, 100].

package/src/spec/Spec.ts

@@ -1,5 +1,5 @@
 import { DataDefinition } from './Data.js';
-import { ParamDefinition } from './Param.js';
+import { ParamDefinition, ParamRef } from './Param.js';
 import { HConcat } from './HConcat.js';
 import { VConcat } from './VConcat.js';
 import { HSpace } from './HSpace.js';

package/src/spec/Transform.ts

@@ -41,20 +41,58 @@ type Arg2Opt = Arg | [Arg, Arg?];
  */
 type Arg3Opt = Arg | [Arg, Arg?, Arg?];
 
-/** Bin transform options. */
-export interface BinOptions {
+/** Binning interval names. */
+export type BinInterval =
+  | 'date'
+  | 'number'
+  | 'millisecond'
+  | 'second'
+  | 'minute'
+  | 'hour'
+  | 'day'
+  | 'month'
+  | 'year';
+
+/* A bin transform. */
+export interface Bin {
+  /**
+   * Bin a continuous variable into discrete intervals. The bin argument
+   * specifies a data column or expression to bin. Both numerical and
+   * temporal (date/time) values are supported.
+   */
+  bin: Arg | [Arg];
+  /**
+   * The interval bin unit to use, typically used to indicate a date/time
+   * unit for binning temporal values, such as `hour`, `day`, or `month`.
+   * If `date`, the extent of data values is used to automatically select
+   * an interval for temporal data. The value `number` enforces normal
+   * numerical binning, even over temporal data. If unspecified, defaults
+   * to `number` for numerical data and `date` for temporal data.
+   */
+  interval?: BinInterval;
+  /**
+   * The step size to use between bins. When binning numerical values (or
+   * interval type `number`), this setting specifies the numerical step size.
+   * For data/time intervals, this indicates the number of steps of that unit,
+   * such as hours, days, or years.
+   */
+  step?: number;
   /**
    * The target number of binning steps to use. To accommodate human-friendly
-   * bin boundaries, the actual number of bins may diverge from this exact number.
+   * ("nice") bin boundaries, the actual number of bins may diverge from this
+   * exact value. This option is ignored when **step** is specified.
    */
   steps?: number;
   /**
-   * The minimum allowed bin step size (default `0`).
-   * For example, a setting of `1` will prevent step sizes less than 1.
+   * The minimum allowed bin step size (default `0`) when performing numerical
+   * binning. For example, a setting of `1` prevents step sizes less than 1.
+   * This option is ignored when **step** is specified.
    */
   minstep?: number;
   /**
-   * A flag requesting "nice" human-friendly step sizes (default `true`).
+   * A flag (default `true`) requesting "nice" human-friendly end points and
+   * step sizes when performing numerical binning. When **step** is specified,
+   * this option affects the binning end points (e.g., origin) only.
    */
   nice?: true;
   /**
@@ -64,15 +102,6 @@ export interface BinOptions {
   offset?: number;
 }
 
-/* A bin transform. */
-export interface Bin {
-  /**
-   * Bin a continuous variable into discrete intervals. This transform accepts
-   * a data column to bin over as well as an optional bin options object.
-   */
-  bin: Arg | [Arg] | [Arg, BinOptions];
-}
-
 /* A dateMonth transform. */
 export interface DateMonth {
   /**