@uwdata/mosaic-spec 0.7.0 → 0.8.0

package/src/spec/marks/Geo.ts

@@ -0,0 +1,58 @@
+import { ParamRef } from '../Param.js';
+import { ChannelValue, ChannelValueSpec, MarkData, MarkOptions } from './Marks.js';
+
+/** Options for the geo mark. */
+export interface GeoOptions extends MarkOptions {
+  /**
+   * A required channel for the geometry to render; defaults to identity,
+   * assuming *data* is a GeoJSON object or an iterable of GeoJSON objects.
+   */
+  geometry?: ChannelValue;
+
+  /**
+   * The size of Point and MultiPoint geometries, defaulting to a constant 3
+   * pixels. If **r** is a number, it is interpreted as a constant radius in
+   * pixels; otherwise it is interpreted as a channel and the effective radius
+   * is controlled by the *r* scale, which defaults to a *sqrt* scale such that
+   * the visual area of a point is proportional to its associated value.
+   *
+   * If **r** is a channel, geometries will be sorted by descending radius by
+   * default, to limit occlusion; use the **sort** transform to control render
+   * order. Geometries with a nonpositive radius are not drawn.
+   */
+  r?: ChannelValueSpec | ParamRef;
+}
+
+/** The geo mark. */
+export interface Geo extends MarkData, GeoOptions {
+  /**
+   * A geo mark. The **geometry** channel, which defaults to the identity
+   * function assuming that *data* is a GeoJSON object or an iterable of
+   * GeoJSON objects, is projected to the plane using the plot’s top-level
+   * **projection**.
+   *
+   * If *data* is a GeoJSON feature collection, then the mark’s data is
+   * *data*.features; if *data* is a GeoJSON geometry collection, then the
+   * mark’s data is *data*.geometries; if *data* is some other GeoJSON
+   * object, then the mark’s data is the single-element array [*data*].
+   */
+  mark: 'geo';
+}
+
+/** The sphere mark. */
+export interface Sphere extends MarkOptions {
+  /**
+   * A geo mark whose *data* is the outline of the sphere on the
+   * projection’s plane. (For use with a spherical **projection** only.)
+   */
+  mark: 'sphere';
+}
+
+/** The graticule mark. */
+export interface Graticule extends MarkOptions {
+  /**
+   * A geo mark whose *data* is a 10° global graticule. (For use with a
+   * spherical **projection** only.)
+   */
+  mark: 'graticule';
+}

package/src/spec/marks/Hexbin.ts

@@ -0,0 +1,34 @@
+import { ParamRef } from '../Param.js';
+import { DotOptions } from './Dot.js';
+import { ChannelValue, MarkData, TextStyles } from './Marks.js';
+
+export interface HexbinOptions extends DotOptions, TextStyles {
+  /**
+   * The basic mark type to use for hex-binned values.
+   * Defaults to a hexagon mark; dot and text marks are also supported.
+   */
+  type?: 'dot' | 'circle' | 'hexagon' | 'text' | ParamRef;
+
+  /**
+   * The distance between centers of neighboring hexagons, in pixels; defaults
+   * to 20. If also using a hexgrid mark, use matching **binWidth** values.
+   */
+  binWidth?: number | ParamRef;
+
+  /**
+   * How to subdivide bins. If not specified, defaults to the *fill* channel,
+   * if any, or the *stroke* channel, if any. If null, bins will not be
+   * subdivided.
+   */
+  z?: ChannelValue;
+}
+
+/** The hexbin mark. */
+export interface Hexbin extends MarkData, HexbinOptions {
+  /**
+   * A hexbin mark that bins **x** and **y** data into a hexagonal grid and
+   * visualizes aggregate functions per bin (e.g., count for binned density).
+   * Aggregate functions can be used for fill, stroke, or r (radius) options.
+   */
+  mark: 'hexbin';
+}

package/src/spec/marks/Hexgrid.ts

@@ -0,0 +1,27 @@
+import { ParamRef } from '../Param.js';
+import { MarkOptions } from './Marks.js';
+
+/** Options for the hexgrid mark. */
+export interface HexgridOptions extends MarkOptions {
+  /**
+   * The distance between centers of neighboring hexagons, in pixels; defaults
+   * to 20. Should match the **binWidth** of the hexbin mark.
+   */
+  binWidth?: number | ParamRef;
+}
+
+/** The hexgrid mark. */
+export interface Hexgrid extends HexgridOptions {
+  /**
+   * The hexgrid decoration mark complements the hexbin mark, showing the
+   * outlines of all hexagons spanning the frame with a default **stroke** of
+   * *currentColor* and a default **strokeOpacity** of 0.1, similar to the
+   * default axis grids.
+   *
+   * Note that the **binWidth** option of the hexgrid mark should match that of
+   * the hexbin transform. The grid is clipped by the frame. This is a
+   * stroke-only mark, and **fill** is not supported; to fill the frame,
+   * use the frame mark.
+   */
+  mark: 'hexgrid';
+}

package/src/spec/marks/Image.ts

@@ -0,0 +1,101 @@
+import { ParamRef } from '../Param.js';
+import { FrameAnchor } from '../PlotTypes.js';
+import { ChannelValue, ChannelValueSpec, MarkData, MarkOptions } from './Marks.js';
+
+/** Options for the image mark. */
+export interface ImageOptions extends MarkOptions {
+  /**
+   * The horizontal position channel specifying the image’s center; typically
+   * bound to the *x* scale.
+   */
+  x?: ChannelValueSpec;
+
+  /**
+   * The vertical position channel specifying the image’s center; typically
+   * bound to the *y* scale.
+   */
+  y?: ChannelValueSpec;
+
+  /**
+   * The image width in pixels. When a number, it is interpreted as a constant
+   * radius in pixels; otherwise it is interpreted as a channel. Also sets the
+   * default **height**; if neither are set, defaults to 16. Images with a
+   * nonpositive width are not drawn.
+   */
+  width?: ChannelValue | ParamRef;
+
+  /**
+   * The image height in pixels. When a number, it is interpreted as a constant
+   * radius in pixels; otherwise it is interpreted as a channel. Also sets the
+   * default **height**; if neither are set, defaults to 16. Images with a
+   * nonpositive height are not drawn.
+   */
+  height?: ChannelValue | ParamRef;
+
+  /**
+   * The image clip radius, for circular images. If null (default), images are
+   * not clipped; when a number, it is interpreted as a constant in pixels;
+   * otherwise it is interpreted as a channel, typically bound to the *r* scale.
+   * Also defaults **height** and **width** to twice its value.
+   */
+  r?: ChannelValue | ParamRef;
+
+  /**
+   * The rotation angle, in degrees clockwise. When a number, it is interpreted
+   * as a constant; otherwise it is interpreted as a channel.
+   */
+  rotate?: ChannelValue | ParamRef;
+
+  /**
+   * The required image URL (or relative path). If a string that starts with a
+   * dot, slash, or URL protocol (*e.g.*, “https:”) it is assumed to be a
+   * constant; otherwise it is interpreted as a channel.
+   */
+  src?: ChannelValue | ParamRef;
+
+  /**
+   * The image [aspect ratio][1]; defaults to *xMidYMid meet*. To crop the image
+   * instead of scaling it to fit, use *xMidYMid slice*.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/preserveAspectRatio
+   */
+  preserveAspectRatio?: string | ParamRef;
+
+  /**
+   * The [cross-origin][1] behavior. See the [Plot.image notebook][2] for details.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/crossorigin
+   * [2]: https://observablehq.com/@observablehq/plot-image
+   */
+  crossOrigin?: string | ParamRef;
+
+  /**
+   * The frame anchor specifies defaults for **x** and **y** based on the plot’s
+   * frame; it may be one of the four sides (*top*, *right*, *bottom*, *left*),
+   * one of the four corners (*top-left*, *top-right*, *bottom-right*,
+   * *bottom-left*), or the *middle* of the frame.
+   */
+  frameAnchor?: FrameAnchor | ParamRef;
+
+  /**
+   * The [image-rendering attribute][1]; defaults to *auto* (bilinear). The
+   * option may be set to *pixelated* to disable bilinear interpolation for a
+   * sharper image; however, note that this is not supported in WebKit.
+   *
+   * [1]: https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/image-rendering
+   */
+  imageRendering?: string | ParamRef;
+}
+
+export interface Image extends MarkData, ImageOptions {
+  /**
+   * An image mark that draws images as in a scatterplot.
+   *
+   * If either **x** or **y** is not specified, the default is determined by
+   * the **frameAnchor** option. If none of **x**, **y**, and **frameAnchor**
+   * are specified, *data* is assumed to be an array of pairs [[*x₀*, *y₀*],
+   * [*x₁*, *y₁*], [*x₂*, *y₂*], …] such that **x** = [*x₀*, *x₁*, *x₂*, …]
+   * and **y** = [*y₀*, *y₁*, *y₂*, …].
+   */
+  mark: 'image';
+}

package/src/spec/marks/Line.ts

@@ -0,0 +1,93 @@
+import {
+  ChannelValue, ChannelValueSpec, CurveAutoOptions,
+  MarkData, MarkOptions, MarkerOptions
+} from './Marks.js';
+
+/** Options for the line mark. */
+export interface LineOptions extends MarkOptions, MarkerOptions, CurveAutoOptions {
+  /**
+   * The required horizontal position channel, typically bound to the *x*
+   * scale.
+   */
+  x?: ChannelValueSpec;
+
+  /**
+   * The required vertical position channel, typically bound to the *y* scale.
+   */
+  y?: ChannelValueSpec;
+
+  /**
+   * An optional ordinal channel for grouping data into (possibly stacked)
+   * series to be drawn as separate lines. If not specified, it defaults to
+   * **fill** if a channel, or **stroke** if a channel.
+   */
+  z?: ChannelValue;
+}
+
+/** Options for the lineX mark. */
+export interface LineXOptions extends LineOptions {
+  /**
+   * 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 lineY mark. */
+export interface LineYOptions extends LineOptions {
+  /**
+   * 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 line mark. */
+export interface Line extends MarkData, LineOptions {
+  /**
+   * A line mark that connects control points.
+   *
+   * Points along the line are connected in input order. If there are multiple
+   * series via the **z**, **fill**, or **stroke** channel, series are drawn in
+   * input order such that the last series is drawn on top. Typically *data* is
+   * already in sorted order, such as chronological for time series; if needed,
+   * consider a **sort** transform.
+   *
+   * If any **x** or **y** values are invalid (undefined, null, or NaN), the
+   * line will be interrupted, resulting in a break that divides the line shape
+   * into multiple segments. If a line segment consists of only a single point,
+   * it may appear invisible unless rendered with rounded or square line caps.
+   * In addition, some curves such as *cardinal-open* only render a visible
+   * segment if it contains multiple points.
+   *
+   * Variable aesthetic channels are supported: if the **stroke** is defined as
+   * a channel, the line will be broken into contiguous overlapping segments
+   * when the stroke color changes; the stroke color will apply to the interval
+   * spanning the current data point and the following data point. This
+   * behavior also applies to the **fill**, **fillOpacity**, **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: 'line';
+}
+
+/** The lineX mark. */
+export interface LineX extends MarkData, LineXOptions {
+  /**
+   * Like line, except that **x** defaults to the identity function assuming
+   * that *data* = [*x₀*, *x₁*, *x₂*, …] and **y** defaults to the zero-based
+   * index [0, 1, 2, …].
+   */
+  mark: 'lineX'
+}
+
+/** The lineY mark. */
+export interface LineY extends MarkData, LineYOptions {
+  /**
+   * Like line, except **y** defaults to the identity function and assumes
+   * that *data* = [*y₀*, *y₁*, *y₂*, …] and **x** defaults to the zero-based
+   * index [0, 1, 2, …].
+   */
+  mark: 'lineY'
+}

package/src/spec/marks/Link.ts

@@ -0,0 +1,70 @@
+import { ParamRef } from '../Param.js';
+import {
+  ChannelValueSpec, CurveAutoOptions, MarkData, MarkOptions, MarkerOptions
+} from './Marks.js';
+
+/** Options for the link mark. */
+export interface LinkOptions extends MarkOptions, MarkerOptions, CurveAutoOptions {
+  /**
+   * The horizontal position, for vertical links; typically bound to the *x*
+   * scale; shorthand for setting defaults for both **x1** and **x2**.
+   */
+  x?: ChannelValueSpec;
+
+  /**
+   * The vertical position, for horizontal links; 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 curve (interpolation) method for connecting adjacent points.
+   *
+   * Since a link has exactly two points, only the following curves (or a custom
+   * curve) are recommended: *linear*, *step*, *step-after*, *step-before*,
+   * *bump-x*, or *bump-y*. Note that the *linear* curve is incapable of showing
+   * a fill since a straight line has zero area. For a curved link, use an arrow
+   * mark with the **bend** option.
+   *
+   * If the plot uses a spherical **projection**, the default *auto* **curve**
+   * will render links as geodesics; to draw a straight line instead, use the
+   * *linear* **curve**.
+   */
+  curve?: CurveAutoOptions['curve'] | ParamRef;
+}
+
+/** The link mark. */
+export interface Link extends MarkData, LinkOptions {
+  /**
+   * A link mark, drawing line segments (curves) connecting pairs of points.
+   *
+   * If the plot uses a spherical **projection**, the default *auto* **curve**
+   * will render links as geodesics; to draw a straight line instead, use the
+   * *linear* **curve**.
+   */
+  mark: 'link';
+}