@uwdata/mosaic-spec 0.7.1 → 0.8.0

package/dist/types/spec/PlotFrom.d.ts

@@ -0,0 +1,20 @@
+import { ParamRef } from './Param.js';
+/**
+ * An array of inline data values to visualize. As this data does not come
+ * from a database, it can not be filtered by interactive selections.
+ */
+export type PlotDataInline = any[];
+/** Input data specification for a plot mark. */
+export interface PlotFrom {
+    /** The name of the backing data table. */
+    from: string;
+    /** A selection that filters the mark data. */
+    filterBy?: ParamRef;
+    /**
+     * A flag (default `true`) to enable any mark-specific query optimizations.
+     * If `false`, optimizations are disabled to aid testing and debugging.
+     */
+    optimize?: boolean;
+}
+/** Input data for a marks */
+export type PlotMarkData = PlotDataInline | PlotFrom;

package/dist/types/spec/PlotInteractor.d.ts

@@ -0,0 +1,8 @@
+import { Highlight } from './interactors/Highlight.js';
+import { IntervalX, IntervalY } from './interactors/Interval1D.js';
+import { IntervalXY } from './interactors/Interval2D.js';
+import { NearestX, NearestY } from './interactors/Nearest.js';
+import { Pan, PanX, PanY, PanZoom, PanZoomX, PanZoomY } from './interactors/PanZoom.js';
+import { Toggle, ToggleColor, ToggleX, ToggleY } from './interactors/Toggle.js';
+/** A plot interactor entry. */
+export type PlotInteractor = Highlight | IntervalX | IntervalY | IntervalXY | NearestX | NearestY | Toggle | ToggleX | ToggleY | ToggleColor | Pan | PanX | PanY | PanZoom | PanZoomX | PanZoomY;

package/dist/types/spec/PlotLegend.d.ts

@@ -0,0 +1,68 @@
+import { ParamRef } from './Param.js';
+/**
+ * A legend defined as an entry within a plot.
+ */
+export interface PlotLegend {
+    /**
+     * A legend of the given type.
+     * The valid types are `"color"`, `"opacity"`, and `"symbol"`.
+     */
+    legend: 'color' | 'opacity' | 'symbol';
+    /**
+     * The output selection. If specified, the legend is interactive, using a
+     * `toggle` interaction for discrete legends or an `intervalX` interaction
+     * for continuous legends.
+     */
+    as?: ParamRef;
+    /**
+     * The data field over which to generate output selection clauses. If
+     * unspecified, a matching field is retrieved from existing plot marks.
+     */
+    field?: string;
+    /**
+     * The legend label.
+     */
+    label?: string;
+    /**
+     * The size of legend ticks in a continuous legend, in pixels.
+     */
+    tickSize?: number;
+    /**
+     * The top margin of the legend component, in pixels.
+     */
+    marginTop?: number;
+    /**
+     * The right margin of the legend component, in pixels.
+     */
+    marginRight?: number;
+    /**
+     * The bottom margin of the legend component, in pixels.
+     */
+    marginBottom?: number;
+    /**
+     * The left margin of the legend component, in pixels.
+     */
+    marginLeft?: number;
+    /**
+     * The width of a continuous legend, in pixels.
+     */
+    width?: number;
+    /**
+     * The height of a continuous legend, in pixels.
+     */
+    height?: number;
+    /**
+     * The number of columns to use to layout a discrete legend.
+     */
+    columns?: number;
+}
+/**
+ * A legend defined as a top-level spec component.
+ */
+export interface Legend extends PlotLegend {
+    /**
+     * The name of the plot this legend applies to.
+     * A plot must include a `name` attribute to be referenced.
+     */
+    for: string;
+}

package/dist/types/spec/PlotMark.d.ts

@@ -0,0 +1,26 @@
+import { Area, AreaX, AreaY } from './marks/Area.js';
+import { Arrow } from './marks/Arrow.js';
+import { AxisFx, AxisFy, AxisX, AxisY, GridFx, GridFy, GridX, GridY } from './marks/Axis.js';
+import { BarX, BarY } from './marks/Bar.js';
+import { Cell, CellX, CellY } from './marks/Cell.js';
+import { Contour } from './marks/Contour.js';
+import { DelaunayLink, DelaunayMesh, Hull, Voronoi, VoronoiMesh } from './marks/Delaunay.js';
+import { DenseLine } from './marks/DenseLine.js';
+import { Density, DensityX, DensityY } from './marks/Density.js';
+import { Circle, Dot, DotX, DotY, Hexagon } from './marks/Dot.js';
+import { Frame } from './marks/Frame.js';
+import { Geo, Graticule, Sphere } from './marks/Geo.js';
+import { Hexbin } from './marks/Hexbin.js';
+import { Hexgrid } from './marks/Hexgrid.js';
+import { Image } from './marks/Image.js';
+import { Line, LineX, LineY } from './marks/Line.js';
+import { Link } from './marks/Link.js';
+import { Heatmap, Raster, RasterTile } from './marks/Raster.js';
+import { Rect, RectX, RectY } from './marks/Rect.js';
+import { RegressionY } from './marks/Regression.js';
+import { RuleX, RuleY } from './marks/Rule.js';
+import { Text, TextX, TextY } from './marks/Text.js';
+import { TickX, TickY } from './marks/Tick.js';
+import { Spike, Vector, VectorX, VectorY } from './marks/Vector.js';
+/** A plot mark entry. */
+export type PlotMark = Area | AreaX | AreaY | Arrow | AxisX | AxisY | AxisFx | AxisFy | GridX | GridY | GridFx | GridFy | BarX | BarY | Cell | CellX | CellY | Contour | DelaunayLink | DelaunayMesh | Hull | Voronoi | VoronoiMesh | DenseLine | Density | DensityX | DensityY | Dot | DotX | DotY | Circle | Hexagon | Frame | Geo | Graticule | Sphere | Hexbin | Hexgrid | Image | Line | LineX | LineY | Link | Raster | Heatmap | RasterTile | Rect | RectX | RectY | RegressionY | RuleX | RuleY | Text | TextX | TextY | TickX | TickY | Vector | VectorX | VectorY | Spike;

package/dist/types/spec/PlotTypes.d.ts

@@ -0,0 +1,293 @@
+/**
+ * A symbol indicating a fixed scale domain. A fixed domain is initially
+ * determined from data as usual, but subsequently "fixed" so that it does not
+ * change over subsequent interactive filtering, ensring stable comparisons.
+ */
+export type Fixed = 'Fixed';
+export type LiteralTimeInterval = '3 months' | '10 years' | TimeIntervalName | (`${TimeIntervalName}s` & Record<never, never>) | (`${number} ${TimeIntervalName}` & Record<never, never>) | (`${number} ${TimeIntervalName}s` & Record<never, never>);
+/**
+ * The built-in time intervals; UTC or local time, depending on context. The
+ * *week* interval is an alias for *sunday*. The *quarter* interval is every
+ * three months, and the *half* interval is every six months, aligned at the
+ * start of the year.
+ */
+export type TimeIntervalName = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'half' | 'year' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday' | 'sunday';
+/**
+ * How to partition a continuous range into discrete intervals; one of:
+ *
+ * - a named time interval such as *day* (for date intervals)
+ * - a number (for number intervals), defining intervals at integer multiples of *n*
+ */
+export type Interval<T = any> = T extends Date ? LiteralTimeInterval : T extends number ? number : never;
+/**
+ * The built-in scale names; one of:
+ *
+ * - *x* - horizontal position
+ * - *y* - vertical position
+ * - *fx* - horizontal facet position
+ * - *fy* - vertical facet position
+ * - *r* - radius (for dots and point geos)
+ * - *color* - color
+ * - *opacity* - opacity
+ * - *symbol* - categorical symbol (for dots)
+ * - *length* - length (for vectors)
+ *
+ * Position scales may have associated axes. Color, opacity, and symbol scales
+ * may have an associated legend.
+ */
+export type ScaleName = 'x' | 'y' | 'fx' | 'fy' | 'r' | 'color' | 'opacity' | 'symbol' | 'length';
+/**
+ * The supported scale types for *x* and *y* position encodings.
+ *
+ * For quantitative data, one of:
+ *
+ * - *linear* (default) - linear transform (translate and scale)
+ * - *pow* - power (exponential) transform
+ * - *sqrt* - square-root transform; *pow* with *exponent* = 0.5
+ * - *log* - logarithmic transform
+ * - *symlog* - bi-symmetric logarithmic transform per Webber et al.
+ *
+ * For temporal data, one of:
+ *
+ * - *utc* (default, recommended) - UTC time
+ * - *time* - local time
+ *
+ * For ordinal data, one of:
+ *
+ * - *point* (for position only) - divide a continuous range into discrete points
+ * - *band* (for position only) - divide a continuous range into discrete points
+ *
+ * Other scale types:
+ *
+ * - *identity* - do not transform values when encoding
+ */
+export type PositionScaleType = 'linear' | 'pow' | 'sqrt' | 'log' | 'symlog' | 'utc' | 'time' | 'point' | 'band' | 'threshold' | 'quantile' | 'quantize' | 'identity';
+/**
+ * The supported scale types for *color* encodings.
+ *
+ * For quantitative data, one of:
+ *
+ * - *linear* (default) - linear transform (translate and scale)
+ * - *pow* - power (exponential) transform
+ * - *sqrt* - square-root transform; *pow* with *exponent* = 0.5
+ * - *log* - logarithmic transform
+ * - *symlog* - bi-symmetric logarithmic transform per Webber et al.
+ *
+ * For temporal data, one of:
+ *
+ * - *utc* (default, recommended) - UTC time
+ * - *time* - local time
+ *
+ * For ordinal data, one of:
+ *
+ * - *ordinal* - from discrete inputs to discrete outputs
+ *
+ * For color, one of:
+ *
+ * - *categorical* - equivalent to *ordinal*; defaults to *observable10*
+ * - *sequential* - equivalent to *linear*; defaults to *turbo*
+ * - *cyclical* - equivalent to *linear*; defaults to *rainbow*
+ * - *threshold* - encodes using discrete thresholds; defaults to *rdylbu*
+ * - *quantile* - encodes using quantile thresholds; defaults to *rdylbu*
+ * - *quantize* - uniformly quantizes a continuous domain; defaults to *rdylbu*
+ * - *diverging* - *linear*, but with a pivot; defaults to *rdbu*
+ * - *diverging-log* - *log*, but with a pivot; defaults to *rdbu*
+ * - *diverging-pow* - *pow*, but with a pivot; defaults to *rdbu*
+ * - *diverging-sqrt* - *sqrt*, but with a pivot; defaults to *rdbu*
+ * - *diverging-symlog* - *symlog*, but with a pivot; defaults to *rdbu*
+ *
+ * Other scale types:
+ *
+ * - *identity* - do not transform values when encoding
+ */
+export type ColorScaleType = 'linear' | 'pow' | 'sqrt' | 'log' | 'symlog' | 'utc' | 'time' | 'point' | 'band' | 'ordinal' | 'sequential' | 'cyclical' | 'diverging' | 'diverging-log' | 'diverging-pow' | 'diverging-sqrt' | 'diverging-symlog' | 'categorical' | 'threshold' | 'quantile' | 'quantize' | 'identity';
+/**
+ * The supported scale types for continuous encoding channels.
+ *
+ * For quantitative data, one of:
+ *
+ * - *linear* (default) - linear transform (translate and scale)
+ * - *pow* - power (exponential) transform
+ * - *sqrt* - square-root transform; *pow* with *exponent* = 0.5
+ * - *log* - logarithmic transform
+ * - *symlog* - bi-symmetric logarithmic transform per Webber et al.
+ *
+ * For temporal data, one of:
+ *
+ * - *utc* (default, recommended) - UTC time
+ * - *time* - local time
+ *
+ * Other scale types:
+ *
+ * - *identity* - do not transform values when encoding
+ */
+export type ContinuousScaleType = 'linear' | 'pow' | 'sqrt' | 'log' | 'symlog' | 'utc' | 'time' | 'identity';
+/**
+ * The supported scale types for discrete encoding channels. One of:
+ *
+ * - *ordinal* - from discrete inputs to discrete outputs
+ * - *identity* - do not transform values when encoding
+ */
+export type DiscreteScaleType = 'ordinal' | 'identity';
+/**
+ * The built-in projection implementations; one of:
+ *
+ * - *albers-usa* - a U.S.-centric composite projection with insets for Alaska and Hawaii
+ * - *albers* - a U.S.-centric *conic-equal-area* projection
+ * - *azimuthal-equal-area* - the azimuthal equal-area projection
+ * - *azimuthal-equidistant* - the azimuthal equidistant projection
+ * - *conic-conformal* - the conic conformal projection
+ * - *conic-equal-area* - the conic equal-area projection
+ * - *conic-equidistant* - the conic equidistant projection
+ * - *equal-earth* - the Equal Earth projection Šavrič et al., 2018
+ * - *equirectangular* - the equirectangular (plate carrée) projection
+ * - *gnomonic* - the gnomonic projection
+ * - *identity* - the identity projection
+ * - *reflect-y* - the identity projection, but flipping *y*
+ * - *mercator* - the spherical Mercator projection
+ * - *orthographic* - the orthographic projection
+ * - *stereographic* - the stereographic projection
+ * - *transverse-mercator* - the transverse spherical Mercator projection
+ */
+export type ProjectionName = 'albers-usa' | 'albers' | 'azimuthal-equal-area' | 'azimuthal-equidistant' | 'conic-conformal' | 'conic-equal-area' | 'conic-equidistant' | 'equal-earth' | 'equirectangular' | 'gnomonic' | 'identity' | 'reflect-y' | 'mercator' | 'orthographic' | 'stereographic' | 'transverse-mercator';
+/**
+ * How to interpolate range (output) values for continuous scales; one of:
+ *
+ * - *number* - linear numeric interpolation
+ * - *rgb* - red, green, blue (sRGB)
+ * - *hsl* - hue, saturation, lightness (HSL; cylindrical sRGB)
+ * - *hcl* - hue, chroma, perceptual lightness (CIELCh_ab; cylindrical CIELAB)
+ * - *lab* - perceptual lightness and opponent colors (L\*a\*b\*, CIELAB)
+ */
+export type Interpolate = 'number' | 'rgb' | 'hsl' | 'hcl' | 'lab';
+/** The built-in color schemes, cased. */
+type ColorSchemeCase = 'Accent' | 'Category10' | 'Dark2' | 'Observable10' | 'Paired' | 'Pastel1' | 'Pastel2' | 'Set1' | 'Set2' | 'Set3' | 'Tableau10' | 'BrBG' | 'PRGn' | 'PiYG' | 'PuOr' | 'RdBu' | 'RdGy' | 'RdYlBu' | 'RdYlGn' | 'Spectral' | 'BuRd' | 'BuYlRd' | 'Blues' | 'Greens' | 'Greys' | 'Oranges' | 'Purples' | 'Reds' | 'Turbo' | 'Viridis' | 'Magma' | 'Inferno' | 'Plasma' | 'Cividis' | 'Cubehelix' | 'Warm' | 'Cool' | 'BuGn' | 'BuPu' | 'GnBu' | 'OrRd' | 'PuBu' | 'PuBuGn' | 'PuRd' | 'RdPu' | 'YlGn' | 'YlGnBu' | 'YlOrBr' | 'YlOrRd' | 'Rainbow' | 'Sinebow';
+/**
+ * The built-in color schemes. For categorical data, one of:
+ *
+ * - *Accent* - eight colors
+ * - *Category10* - ten colors
+ * - *Dark2* - eight colors
+ * - *Observable10* (default) - ten colors
+ * - *Paired* - twelve paired colors
+ * - *Pastel1* - nine colors
+ * - *Pastel2* - eight colors
+ * - *Set1* - nine colors
+ * - *Set2* - eight colors
+ * - *Set3* - twelve colors
+ * - *Tableau10* - ten colors
+ *
+ * For diverging data, one of:
+ *
+ * - *BrBG* - from brown to white to blue-green
+ * - *PRGn* - from purple to white to green
+ * - *PiYG* - from pink to white to yellow-green
+ * - *PuOr* - from purple to white to orange
+ * - *RdBu* (default) - from red to white to blue
+ * - *RdGy* - from red to white to gray
+ * - *RdYlBu* - from red to yellow to blue
+ * - *RdYlGn* - from red to yellow to green
+ * - *Spectral* - from red to blue, through the spectrum
+ * - *BuRd* - from blue to white to red
+ * - *BuYlRd* - from blue to yellow to red
+ *
+ * For sequential data, one of:
+ *
+ * - *Blues* - from white to blue
+ * - *Greens* - from white to green
+ * - *Greys* - from white to gray
+ * - *Oranges* - from white to orange
+ * - *Purples* - from white to purple
+ * - *Reds* - from white to red
+ * - *Turbo* (default) - from blue to red, through the spectrum
+ * - *Viridis* - from blue to green to yellow
+ * - *Magma* - from purple to orange to yellow
+ * - *Inferno* - from purple to orange to yellow
+ * - *Plasma* - from purple to orange to yellow
+ * - *Cividis* - from blue to yellow
+ * - *Cubehelix* - from black to white, rotating hue
+ * - *Warm* - from purple to green, through warm hues
+ * - *Cool* - from green to to purple, through cool hues
+ * - *BuGn* - from light blue to dark green
+ * - *BuPu* - from light blue to dark purple
+ * - *GnBu* - from light green to dark blue
+ * - *OrRd* - from light orange to dark red
+ * - *PuBu* - from light purple to dark blue
+ * - *PuBuGn* - from light purple to blue to dark green
+ * - *PuRd* - from light purple to dark red
+ * - *RdPu* - from light red to dark purple
+ * - *YlGn* - from light yellow to dark green
+ * - *YlGnBu* - from light yellow to green to dark blue
+ * - *YlOrBr* - from light yellow to orange to dark brown
+ * - *YlOrRd* - from light yellow to orange to dark red
+ *
+ * For cyclical data, one of:
+ *
+ * - *Rainbow* (default) - the less-angry rainbow color scheme
+ * - *Sinebow* - Bumgardner and Loyd’s “sinebow” scheme
+ */
+export type ColorScheme = ColorSchemeCase | (Lowercase<ColorSchemeCase> & Record<never, never>);
+/**
+ * The built-in symbol implementations. For fill, one of:
+ *
+ * - *circle* - a circle
+ * - *cross* - a Greek cross with arms of equal length
+ * - *diamond* - a rhombus
+ * - *square* - a square
+ * - *star* - a pentagonal star (pentagram)
+ * - *triangle* - an up-pointing triangle
+ * - *wye* - a Y with arms of equal length
+ *
+ * For stroke (based on [Heman Robinson’s research][1]), one of:
+ *
+ * - *circle* - a circle
+ * - *plus* - a plus sign
+ * - *times* - an X with arms of equal length
+ * - *triangle2* - an (alternate) up-pointing triangle
+ * - *asterisk* - an asterisk
+ * - *square2* - a (alternate) square
+ * - *diamond2* - a rotated square
+ *
+ * The *hexagon* symbol is also supported.
+ *
+ * [1]: https://www.tandfonline.com/doi/abs/10.1080/10618600.2019.1637746
+ */
+export type SymbolType = 'asterisk' | 'circle' | 'cross' | 'diamond' | 'diamond2' | 'hexagon' | 'plus' | 'square' | 'square2' | 'star' | 'times' | 'triangle' | 'triangle2' | 'wye';
+/**
+ * How to anchor a mark relative to the plot’s frame; one of:
+ *
+ * - *middle* - centered in the middle
+ * - in the middle of one of the edges: *top*, *right*, *bottom*, *left*
+ * - in one of the corners: *top-left*, *top-right*, *bottom-right*, *bottom-left*
+ */
+export type FrameAnchor = 'middle' | 'top-left' | 'top' | 'top-right' | 'right' | 'bottom-right' | 'bottom' | 'bottom-left' | 'left';
+type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+export type ReducerPercentile = (`p${Digit}${Digit}` & Record<never, never>) | 'p25' | 'p50' | 'p75';
+/**
+ * How to reduce aggregated (binned or grouped) values; one of:
+ *
+ * - *first* - the first value, in input order
+ * - *last* - the last value, in input order
+ * - *count* - the number of elements (frequency)
+ * - *distinct* - the number of distinct values
+ * - *sum* - the sum of values
+ * - *proportion* - the sum proportional to the overall total (weighted frequency)
+ * - *proportion-facet* - the sum proportional to the facet total
+ * - *deviation* - the standard deviation
+ * - *min* - the minimum value
+ * - *min-index* - the zero-based index of the minimum value
+ * - *max* - the maximum value
+ * - *max-index* - the zero-based index of the maximum value
+ * - *mean* - the mean value (average)
+ * - *median* - the median value
+ * - *variance* - the variance per [Welford’s algorithm][1]
+ * - *mode* - the value with the most occurrences
+ * - *pXX* - the percentile value, where XX is a number in [00,99]
+ * - *identity* - the array of values
+ *
+ * [1]: https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance#Welford's_online_algorithm
+ */
+export type Reducer = 'first' | 'last' | 'identity' | 'count' | 'distinct' | 'sum' | 'proportion' | 'proportion-facet' | 'deviation' | 'min' | 'min-index' | 'max' | 'max-index' | 'mean' | 'median' | 'variance' | 'mode' | ReducerPercentile;
+/** The built-in curve implementations. */
+export type CurveName = 'basis' | 'basis-closed' | 'basis-open' | 'bundle' | 'bump-x' | 'bump-y' | 'cardinal' | 'cardinal-closed' | 'cardinal-open' | 'catmull-rom' | 'catmull-rom-closed' | 'catmull-rom-open' | 'linear' | 'linear-closed' | 'monotone-x' | 'monotone-y' | 'natural' | 'step' | 'step-after' | 'step-before';
+export {};

package/dist/types/spec/Spec.d.ts

@@ -0,0 +1,45 @@
+import { DataDefinition } from './Data.js';
+import { ParamDefinition } from './Param.js';
+import { HConcat } from './HConcat.js';
+import { VConcat } from './VConcat.js';
+import { HSpace } from './HSpace.js';
+import { VSpace } from './VSpace.js';
+import { Menu, Search, Slider, Table } from './Input.js';
+import { Plot } from './Plot.js';
+import { PlotMark } from './PlotMark.js';
+import { Legend } from './PlotLegend.js';
+import { PlotAttributes } from './PlotAttribute.js';
+/** Specification metadata. */
+export interface Meta extends Record<string, any> {
+    /** The specification title. */
+    title?: string;
+    /** A description of the specification content.  */
+    description?: string;
+    /** Credits or other acknowledgements. */
+    credit?: string;
+}
+/** Configuration options. */
+export interface Config extends Record<string, any> {
+    extensions?: string | string[];
+}
+/** Top-level dataset definitions. */
+export type Data = Record<string, DataDefinition>;
+/** Top-level Param and Selection definitions. */
+export type Params = Record<string, ParamDefinition>;
+/** Top-level specification properties. */
+export interface SpecHead {
+    /** Specification metadata. */
+    meta?: Meta;
+    /** Configuration options. */
+    config?: Config;
+    /** Dataset definitions. */
+    data?: Data;
+    /** Param and Selection definitions. */
+    params?: Params;
+    /** A default set of attributes to apply to all plot components. */
+    plotDefaults?: PlotAttributes;
+}
+/** A specifcation component such as a plot, input widget, or layout. */
+export type Component = HConcat | VConcat | HSpace | VSpace | Menu | Search | Slider | Table | Plot | PlotMark | Legend;
+/** A declarative Mosaic specification. */
+export type Spec = SpecHead & Component;