@uwdata/mosaic-spec 0.7.1 → 0.9.0

package/src/spec/interactors/Nearest.ts

@@ -0,0 +1,48 @@
+import { ParamRef } from '../Param.js';
+
+/** Options for nearest interactors. */
+export interface NearestOptions {
+  /**
+   * The output selection. A clause of the form `field = value`
+   * is added for the currently nearest value.
+   */
+  as: ParamRef;
+  /**
+   * The encoding channels whose domain values should be selected. For example,
+   * a setting of `['color']` selects the data value backing the color channel,
+   * whereas `['x', 'z']` selects both x and z channel domain values. If
+   * unspecified, the selected channels default to match the current pointer
+   * settings: a `nearestX` interactor selects the `['x']` channels, while
+   * a `nearest` interactor selects the `['x', 'y']` channels.
+   */
+  channels?: string[];
+  /**
+   * The fields (database column names) to use in generated selection clause
+   * predicates. If unspecified, the fields backing the selected *channels*
+   * in the first valid prior mark definition are used by default.
+   */
+  fields?: string[];
+  /**
+   * The maximum radius of a nearest selection (default 40). Marks with (x, y)
+   * coordinates outside this radius will not be selected as nearest points.
+   */
+  maxRadius?: number;
+}
+
+/** A nearest interactor. */
+export interface Nearest extends NearestOptions {
+  /** Select values from the mark closest to the pointer. */
+  select: 'nearest';
+}
+
+/** A nearestX interactor. */
+export interface NearestX extends NearestOptions {
+  /** Select values from the mark closest to the pointer *x* location. */
+  select: 'nearestX';
+}
+
+/** A nearestY interactor. */
+export interface NearestY extends NearestOptions {
+  /** Select values from the mark closest to the pointer *y* location. */
+  select: 'nearestY';
+}

package/src/spec/interactors/PanZoom.ts

@@ -0,0 +1,65 @@
+import { ParamRef } from '../Param.js';
+
+/** Options for pan/zoom interactors. */
+export interface PanZoomOptions {
+  /**
+   * The output selection for the `x` domain.
+   * A clause of the form `field BETWEEN x1 AND x2` is added for the
+   * current pan/zom interval [x1, x2].
+   */
+  x?: ParamRef;
+  /**
+   * The output selection for the `y` domain.
+   * A clause of the form `field BETWEEN y1 AND y2` is added for the
+   * current pan/zom interval [y1, y2].
+   */
+  y?: ParamRef;
+  /**
+   * The name of the field (database column) over which the `x`-component
+   * of the pan/zoom interval should be defined. If unspecified, the `x`
+   * channel field of the first valid prior mark definition is used.
+   */
+  xfield?: string;
+  /**
+   * The name of the field (database column) over which the `y`-component
+   * of the pan/zoom interval should be defined. If unspecified, the `y`
+   * channel field of the first valid prior mark definition is used.
+   */
+  yfield?: string;
+}
+
+/** A pan interactor. */
+export interface Pan extends PanZoomOptions {
+  /** Pan a plot along both the `x` and `y` scales. */
+  select: 'pan';
+}
+
+/** A panX interactor. */
+export interface PanX extends PanZoomOptions {
+  /** Pan a plot along the `x` scale only. */
+  select: 'panX';
+}
+
+/** A panY interactor. */
+export interface PanY extends PanZoomOptions {
+  /** Pan a plot along the `y` scale only. */
+  select: 'panY';
+}
+
+/** A panZoom interactor. */
+export interface PanZoom extends PanZoomOptions {
+  /** Pan and zoom a plot along both the `x` and `y` scales. */
+  select: 'panZoom';
+}
+
+/** A panZoomX interactor. */
+export interface PanZoomX extends PanZoomOptions {
+  /** Pan and zoom a plot along the `x` scale only. */
+  select: 'panZoomX';
+}
+
+/** A panZoomY interactor. */
+export interface PanZoomY extends PanZoomOptions {
+  /** Pan and zoom a plot along the `y` scale only. */
+  select: 'panZoomY';
+}

package/src/spec/interactors/Toggle.ts

@@ -0,0 +1,65 @@
+import { ParamRef } from '../Param.js';
+
+/** Options for toggle interactors. */
+export interface ToggleOptions {
+  /**
+   * The output selection. A clause of the form
+   * `(field = value1) OR (field = value2) ...`
+   * is added for the currently selected values.
+   */
+  as: ParamRef;
+  /**
+   * A flag indicating if peer (sibling) marks are when cross-filtering
+   * (default `true`). If set, peer marks will not be filtered by this
+   * interactor's selection in cross-filtering setups.
+   */
+  peers?: boolean;
+}
+
+/** A toggle interactor. */
+export interface Toggle extends ToggleOptions {
+  /** Select individal values. */
+  select: 'toggle';
+  /**
+   * The encoding channels over which to select values.
+   * For a selected mark, selection clauses will cover
+   * the backing data fields for each channel.
+   */
+  channels: string[];
+}
+
+/** A toggleX interactor. */
+export interface ToggleX extends ToggleOptions {
+  /**
+   * Select individal values in the `x` scale domain.
+   * Clicking or touching a mark toggles its selection status.
+   */
+  select: 'toggleX';
+}
+
+/** A toggleY interactor. */
+export interface ToggleY extends ToggleOptions {
+  /**
+   * Select individal values in the `y` scale domain.
+   * Clicking or touching a mark toggles its selection status.
+   */
+  select: 'toggleY';
+}
+
+/** A toggleZ interactor. */
+export interface ToggleZ extends ToggleOptions {
+  /**
+   * Select individal values in the `z` scale domain.
+   * Clicking or touching a mark toggles its selection status.
+   */
+  select: 'toggleZ';
+}
+
+/** A toggleColor interactor. */
+export interface ToggleColor extends ToggleOptions {
+  /**
+   * Select individal values in the `color` scale domain.
+   * Clicking or touching a mark toggles its selection status.
+   */
+  select: 'toggleColor';
+}

package/src/spec/marks/Area.ts

@@ -0,0 +1,154 @@
+import {
+  ChannelValue, ChannelValueSpec, CurveOptions,
+  MarkData, MarkOptions, StackOptions
+} from './Marks.js';
+
+/** Options for the area, areaX, and areaY marks. */
+export interface AreaOptions extends MarkOptions, StackOptions, CurveOptions {
+  /**
+   * The required primary (starting, often left) horizontal position channel,
+   * representing the area’s baseline, typically bound to the *x* scale. For
+   * areaX, setting this option disables the implicit stackX transform.
+   */
+  x1?: ChannelValueSpec;
+
+  /**
+   * The optional secondary (ending, often right) horizontal position channel,
+   * representing the area’s topline, typically bound to the *x* scale; if not
+   * specified, **x1** is used. For areaX, setting this option disables the
+   * implicit stackX transform.
+   */
+  x2?: ChannelValueSpec;
+
+  /**
+   * The required primary (starting, often bottom) vertical position channel,
+   * representing the area’s baseline, typically bound to the *y* scale. For
+   * areaY, setting this option disables the implicit stackY transform.
+   */
+  y1?: ChannelValueSpec;
+
+  /**
+   * The optional secondary (ending, often top) vertical position channel,
+   * representing the area’s topline, typically bound to the *y* scale; if not
+   * specified, **y1** is used. For areaY, setting this option disables the
+   * implicit stackY transform.
+   */
+  y2?: ChannelValueSpec;
+
+  /**
+   * An optional ordinal channel for grouping data into (possibly stacked)
+   * series to be drawn as separate areas; defaults to **fill** if a channel, or
+   * **stroke** if a channel.
+   */
+  z?: ChannelValue;
+}
+
+/** Options for the areaX mark. */
+export interface AreaXOptions extends Omit<AreaOptions, 'y1' | 'y2'> {
+  /**
+   * The horizontal position (or length) channel, typically bound to the *x*
+   * scale.
+   *
+   * If neither **x1** nor **x2** is specified, an implicit stackX transform is
+   * applied and **x** defaults to the identity function, assuming that *data* =
+   * [*x₀*, *x₁*, *x₂*, …]. Otherwise, if only one of **x1** or **x2** is
+   * specified, the other defaults to **x**, which defaults to zero.
+   */
+  x?: ChannelValueSpec;
+
+  /**
+   * The vertical position channel, typically bound to the *y* scale; defaults
+   * to the zero-based index of the data [0, 1, 2, …].
+   */
+  y?: ChannelValueSpec;
+}
+
+/** Options for the areaY mark. */
+export interface AreaYOptions extends Omit<AreaOptions, 'x1' | 'x2'> {
+  /**
+   * The horizontal position channel, typically bound to the *x* scale; defaults
+   * to the zero-based index of the data [0, 1, 2, …].
+   */
+  x?: ChannelValueSpec;
+
+  /**
+   * The vertical position (or length) channel, typically bound to the *y*
+   * scale.
+   *
+   * If neither **y1** nor **y2** is specified, an implicit stackY transform is
+   * applied and **y** defaults to the identity function, assuming that *data* =
+   * [*y₀*, *y₁*, *y₂*, …]. Otherwise, if only one of **y1** or **y2** is
+   * specified, the other defaults to **y**, which defaults to zero.
+   */
+  y?: ChannelValueSpec;
+}
+
+/** The area mark. */
+export interface Area extends MarkData, AreaOptions {
+  /**
+   * An area mark. The area mark is rarely used directly; it is only needed
+   * when the baseline and topline have neither *x* nor *y* values in common.
+   * Use areaY for a horizontal orientation where the baseline and topline
+   * share *x* values, or areaX for a vertical orientation where the baseline
+   * and topline share *y* values.
+   */
+  mark: 'area';
+}
+
+/** The areaX mark. */
+export interface AreaX extends MarkData, AreaXOptions {
+  /**
+   * A vertically-oriented area mark, where the baseline and topline share
+   * **y** values, as in a time-series area chart where time goes up↑.
+   *
+   * If neither **x1** nor **x2** is specified, an implicit stackX transform is
+   * applied and **x** defaults to the identity function, assuming that *data* =
+   * [*x₀*, *x₁*, *x₂*, …]. Otherwise, if only one of **x1** or **x2** is
+   * specified, the other defaults to **x**, which defaults to zero.
+   *
+   * If an **interval** is specified, **y** values are binned accordingly,
+   * allowing zeroes for empty bins instead of interpolating across gaps. This is
+   * recommended to “regularize” sampled data; for example, if your data
+   * represents timestamped observations and you expect one observation per day,
+   * use *day* as the **interval**.
+   *
+   * Variable aesthetic channels are supported: if the **fill** is defined as a
+   * channel, the area will be broken into contiguous overlapping sections when
+   * the fill color changes; the fill color will apply to the interval spanning
+   * the current data point and the following data point. This behavior also
+   * applies to the **fillOpacity**, **stroke**, **strokeOpacity**,
+   * **strokeWidth**, **opacity**, **href**, **title**, and **ariaLabel**
+   * channels. When any of these channels are used, setting an explicit **z**
+   * channel (possibly to null) is strongly recommended.
+   */
+  mark: 'areaX';
+}
+
+/** The areaY mark. */
+export interface AreaY extends MarkData, AreaYOptions {
+  /**
+   * A horizontally-oriented area mark, where the baseline and topline share
+   * **x** values, as in a time-series area chart where time goes right→.
+   *
+   * If neither **y1** nor **y2** is specified, an implicit stackY transform is
+   * applied and **y** defaults to the identity function, assuming that *data* =
+   * [*y₀*, *y₁*, *y₂*, …]. Otherwise, if only one of **y1** or **y2** is
+   * specified, the other defaults to **y**, which defaults to zero.
+   *
+   * If an **interval** is specified, **x** values are binned accordingly,
+   * allowing zeroes for empty bins instead of interpolating across gaps. This is
+   * recommended to “regularize” sampled data; for example, if your data
+   * represents timestamped observations and you expect one observation per day,
+   * use *day* as the **interval**.
+   *
+   * Variable aesthetic channels are supported: if the **fill** is defined as a
+   * channel, the area will be broken into contiguous overlapping sections when
+   * the fill color changes; the fill color will apply to the interval spanning
+   * the current data point and the following data point. This behavior also
+   * applies to the **fillOpacity**, **stroke**, **strokeOpacity**,
+   * **strokeWidth**, **opacity**, **href**, **title**, and **ariaLabel**
+   * channels. When any of these channels are used, setting an explicit **z**
+   * channel (possibly to null) is strongly recommended.
+   */
+  mark: 'areaY';
+}

package/src/spec/marks/Arrow.ts

@@ -0,0 +1,108 @@
+import { ParamRef } from '../Param.js';
+import { ChannelValueSpec, MarkData, MarkOptions } from './Marks.js';
+
+/** Options for the arrow mark. */
+export interface ArrowOptions extends MarkOptions {
+  /**
+   * The horizontal position, for vertical arrows; typically bound to the *x*
+   * scale; shorthand for setting defaults for both **x1** and **x2**.
+   */
+  x?: ChannelValueSpec;
+
+  /**
+   * The vertical position, for horizontal arrows; typically bound to the *y*
+   * scale; shorthand for setting defaults for both **y1** and **y2**.
+   */
+  y?: ChannelValueSpec;
+
+  /**
+   * The starting horizontal position; typically bound to the *x* scale; also
+   * sets a default for **x2**.
+   */
+  x1?: ChannelValueSpec;
+
+  /**
+   * The starting vertical position; typically bound to the *y* scale; also
+   * sets a default for **y2**.
+   */
+  y1?: ChannelValueSpec;
+
+  /**
+   * The ending horizontal position; typically bound to the *x* scale; also
+   * sets a default for **x1**.
+   */
+  x2?: ChannelValueSpec;
+
+  /**
+   * The ending vertical position; typically bound to the *y* scale; also sets
+   * a default for **y1**.
+   */
+  y2?: ChannelValueSpec;
+
+  /**
+   * The angle, a constant in degrees, between the straight line intersecting
+   * the arrow’s two control points and the outgoing tangent direction of the
+   * arrow from the start point. The angle must be within ±90°; a positive
+   * angle will produce a clockwise curve, while a negative angle will produce
+   * a counterclockwise curve; zero (the default) will produce a straight line.
+   * Use true for 22.5°.
+   */
+  bend?: number | boolean | ParamRef;
+
+  /**
+   * How pointy the arrowhead is, in degrees; a constant typically between 0°
+   * and 180°, and defaults to 60°.
+   */
+  headAngle?: number | ParamRef;
+
+  /**
+   * The size of the arrowhead relative to the **strokeWidth**; a constant.
+   * Assuming the default of stroke width 1.5px, this is the length of the
+   * arrowhead’s side in pixels.
+   */
+  headLength?: number | ParamRef;
+
+  /**
+   * Shorthand to set the same default for **insetStart** and **insetEnd**.
+   */
+  inset?: number | ParamRef;
+
+  /**
+   * The starting inset, a constant in pixels; defaults to 0. A positive inset
+   * shortens the arrow by moving the starting point towards the endpoint
+   * point, while a negative inset extends it by moving the starting point in
+   * the opposite direction. A positive starting inset may be useful if the
+   * arrow emerges from a dot.
+   */
+  insetStart?: number | ParamRef;
+
+  /**
+   * The ending inset, a constant in pixels; defaults to 0. A positive inset
+   * shortens the arrow by moving the ending point towards the starting point,
+   * while a negative inset extends it by moving the ending point in the
+   * opposite direction. A positive ending inset may be useful if the arrow
+   * points to a dot.
+   */
+  insetEnd?: number | ParamRef;
+
+  /**
+   * The sweep order; defaults to 1 indicating a positive (clockwise) bend
+   * angle; -1 indicates a negative (anticlockwise) bend angle; 0 effectively
+   * clears the bend angle. If set to *-x*, the bend angle is flipped when the
+   * ending point is to the left of the starting point — ensuring all arrows
+   * bulge up (down if bend is negative); if set to *-y*, the bend angle is
+   * flipped when the ending point is above the starting point — ensuring all
+   * arrows bulge right (left if bend is negative); the sign is negated for
+   * *+x* and *+y*.
+   */
+  sweep?: number | '+x' | '-x' | '+y' | '-y' | ParamRef;
+}
+
+/** The arrow mark. */
+export interface Arrow extends MarkData, ArrowOptions {
+  /**
+   * An arrow mark, drawing (possibly swoopy) arrows connecting pairs of
+   * points.
+   */
+  mark: 'arrow';
+}