@uwdata/mosaic-spec 0.7.0 → 0.8.0

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

@@ -0,0 +1,278 @@
+import { ParamRef } from './Param.js';
+/** A field argument to a data transform. */
+export type TransformField = string | ParamRef;
+/** Window transform options. */
+export interface WindowOptions {
+    orderby?: TransformField | TransformField[];
+    partitionby?: TransformField | TransformField[];
+    rows?: (number | null)[] | ParamRef;
+    range?: (number | null)[] | ParamRef;
+}
+/** Aggregate transform options. */
+export interface AggregateOptions {
+    distinct?: boolean;
+}
+/** A transform argument. */
+type Arg = string | number | boolean;
+/** A zero argument transform signature. */
+type Arg0 = null | [];
+/** A single argument transform signature. */
+type Arg1 = Arg | [Arg];
+/**
+ * A two argument transform signature; both arguments are required.
+ */
+type Arg2 = [Arg, Arg];
+/**
+ * A two argument transform signature; the second argument is optional.
+ */
+type Arg2Opt = Arg | [Arg, Arg?];
+/**
+ * A three argument transform signature; the
+ * second and third arguments are optional.
+ */
+type Arg3Opt = Arg | [Arg, Arg?, Arg?];
+/** Bin transform options. */
+export interface BinOptions {
+    /**
+     * 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.
+     */
+    steps?: number;
+    /**
+     * The minimum allowed bin step size (default `0`).
+     * For example, a setting of `1` will prevent step sizes less than 1.
+     */
+    minstep?: number;
+    /**
+     * A flag requesting "nice" human-friendly step sizes (default `true`).
+     */
+    nice?: true;
+    /**
+     * Offset for computed bins (default `0`). For example, a value of `1` will
+     * result in using the next consecutive bin boundary.
+     */
+    offset?: number;
+}
+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];
+}
+export interface DateMonth {
+    /**
+     * Transform a Date value to a month boundary for cyclic comparison.
+     * Year values are collapsed to enable comparison over months only.
+     */
+    dateMonth: Arg1;
+}
+export interface DateMonthDay {
+    /**
+     * Transform a Date value to a month and day boundary for cyclic comparison.
+     * Year values are collapsed to enable comparison over months and days only.
+     */
+    dateMonthDay: Arg1;
+}
+export interface DateDay {
+    /**
+     * Transform a Date value to a day of the month for cyclic comparison.
+     * Year and month values are collapsed to enable comparison over days only.
+     */
+    dateDay: Arg1;
+}
+export interface Centroid {
+    /**
+     * Compute the 2D centroid of geometry-typed data.
+     * This transform requires the DuckDB `spatial` extension.
+     */
+    centroid: Arg1;
+}
+export interface CentroidX {
+    /**
+     * Compute the centroid x-coordinate of geometry-typed data.
+     * This transform requires the DuckDB `spatial` extension.
+     */
+    centroidX: Arg1;
+}
+export interface CentroidY {
+    /**
+     * Compute the centroid y-coordinate of geometry-typed data.
+     * This transform requires the DuckDB `spatial` extension.
+     */
+    centroidY: Arg1;
+}
+export interface GeoJSON {
+    /**
+     * Compute a GeoJSON-formatted string from geometry-typed data.
+     * This transform requires the DuckDB `spatial` extension.
+     */
+    geojson: Arg1;
+}
+export interface Argmax extends AggregateOptions, WindowOptions {
+    /**
+     * Find a value of the first column that maximizes the second column.
+     */
+    argmax: Arg2;
+}
+export interface Argmin extends AggregateOptions, WindowOptions {
+    /**
+     * Find a value of the first column that minimizes the second column.
+     */
+    argmin: Arg2;
+}
+export interface Avg extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the average (mean) value of the given column.
+     */
+    avg: Arg1;
+}
+export interface Count extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the count of records in an aggregation group.
+     */
+    count: Arg0 | Arg1;
+}
+export interface First extends AggregateOptions, WindowOptions {
+    /**
+     * Return the first column value found in an aggregation group.
+     */
+    first: Arg1;
+}
+export interface Last extends AggregateOptions, WindowOptions {
+    /**
+     * Return the last column value found in an aggregation group.
+     */
+    last: Arg1;
+}
+export interface Max extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the maximum value of the given column.
+     */
+    max: Arg1;
+}
+export interface Min extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the minimum value of the given column.
+     */
+    min: Arg1;
+}
+export interface Median extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the median value of the given column.
+     */
+    median: Arg1;
+}
+export interface Mode extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the mode value of the given column.
+     */
+    mode: Arg1;
+}
+export interface Product extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the product of the given column.
+     */
+    product: Arg1;
+}
+export interface Quantile extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the quantile value of the given column at the provided
+     * probability threshold. For example, 0.5 is the median.
+     */
+    quantile: Arg2;
+}
+export interface Sum extends AggregateOptions, WindowOptions {
+    /**
+     * Compute the sum of the given column.
+     */
+    sum: Arg1;
+}
+export interface RowNumber extends WindowOptions {
+    /**
+     * Compute the 1-based row number over an ordered window partition.
+     */
+    row_number: Arg0;
+}
+export interface Rank extends WindowOptions {
+    /**
+     * Compute the row rank over an ordered window partition.
+     * Sorting ties result in gaps in the rank numbers ([1, 1, 3, ...]).
+     */
+    rank: Arg0;
+}
+export interface DenseRank extends WindowOptions {
+    /**
+     * Compute the dense row rank (no gaps) over an ordered window partition.
+     * Sorting ties do not result in gaps in the rank numbers ( [1, 1, 2, ...]).
+     */
+    dense_rank: Arg0;
+}
+export interface PercentRank extends WindowOptions {
+    /**
+     * Compute the percetange rank over an ordered window partition.
+     */
+    percent_rank: Arg0;
+}
+export interface CumeDist extends WindowOptions {
+    /**
+     * Compute the cumulative distribution value over an ordered window
+     * partition. Equals the number of partition rows preceding or peer with
+     * the current row, divided by the total number of partition rows.
+     */
+    cume_dist: Arg0;
+}
+export interface NTile extends WindowOptions {
+    /**
+     * Compute an n-tile integer ranging from 1 to the provided argument
+     * (num_buckets), dividing the partition as equally as possible.
+     */
+    ntile: Arg1;
+}
+export interface Lag extends WindowOptions {
+    /**
+     * Compute lagging values in a column. Returns the value at the row that is
+     * `offset` (second argument, default `1`) rows before the current row within
+     * the window frame. If there is no such row, instead return `default` (third
+     * argument, default `null`). Both offset and default are evaluated with
+     * respect to the current row.
+     */
+    lag: Arg3Opt;
+}
+export interface Lead extends WindowOptions {
+    /**
+     * Compute leading values in a column. Returns the value at the row that is
+     * `offset` (second argument, default `1`) rows after the current row within
+     * the window frame. If there is no such row, instead return `default` (third
+     * argument, default `null`). Both offset and default are evaluated with
+     * respect to the current row.
+     */
+    lag: Arg3Opt;
+}
+export interface FirstValue extends WindowOptions {
+    /**
+     * Get the first value of the given column in the current window frame.
+     */
+    first_value: Arg1;
+}
+export interface LastValue extends WindowOptions {
+    /**
+     * Get the last value of the given column in the current window frame.
+     */
+    last_value: Arg1;
+}
+export interface NthValue extends WindowOptions {
+    /**
+     * Get the nth value of the given column in the current window frame,
+     * counting from one. The second argument is the offset for the nth row.
+     */
+    nth_value: Arg2Opt;
+}
+/** A data transform that maps one column value to another. */
+export type ColumnTransform = Bin | DateMonth | DateMonthDay | DateDay | Centroid | CentroidX | CentroidY | GeoJSON;
+/** An aggregate transform that combines multiple values. */
+export type AggregateTransform = Argmax | Argmin | Avg | Count | Max | Min | First | Last | Max | Min | Median | Mode | Product | Quantile | Sum;
+export type WindowTransform = RowNumber | Rank | DenseRank | PercentRank | CumeDist | NTile | Rank | Lag | Lead | FirstValue | LastValue | NthValue;
+/** A data transform. */
+export type Transform = ColumnTransform | AggregateTransform | WindowTransform;
+export {};

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

@@ -0,0 +1,8 @@
+import { Component } from './Spec.js';
+/** A vconcat component. */
+export interface VConcat {
+    /**
+     * Vertically concatenate components in a column layout.
+     */
+    vconcat: Component[];
+}

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

@@ -0,0 +1,9 @@
+/** A vspace component. */
+export interface VSpace {
+    /**
+     * Vertical space to place between components.
+     * Number values indicate screen pixels.
+     * String values may use CSS units (em, pt, px, etc).
+     */
+    vspace: number | string;
+}

package/dist/types/spec/interactors/Highlight.d.ts

@@ -0,0 +1,37 @@
+import { ParamRef } from '../Param.js';
+/** A highlight interactor. */
+export interface Highlight {
+    /**
+     * Highlight selected marks by deemphasizing the others.
+     */
+    select: 'highlight';
+    /**
+     * The input selection. Unselected marks are deemphasized.
+     */
+    by: ParamRef;
+    /**
+     * The overall opacity of deemphasized marks.
+     * By default the opacity is set to 0.2.
+     */
+    opacity?: number;
+    /**
+     * The fill opacity of deemphasized marks.
+     * By default the fill opacity is unchanged.
+     */
+    fillOpacity?: number;
+    /**
+     * The stroke opacity of deemphasized marks.
+     * By default the stroke opacity is unchanged.
+     */
+    strokeOpacity?: number;
+    /**
+     * The fill color of deemphasized marks.
+     * By default the fill is unchanged.
+     */
+    fill?: string;
+    /**
+     * The stroke color of deemphasized marks.
+     * By default the stroke is unchanged.
+     */
+    stroke?: string;
+}

package/dist/types/spec/interactors/Interval1D.d.ts

@@ -0,0 +1,63 @@
+import { ParamRef } from '../Param.js';
+/** Styles for rectangular selection brushes. */
+export interface BrushStyles {
+    /**
+     * The overall opacity of the brush rectangle.
+     */
+    opacity?: number;
+    /**
+     * The fill opacity of the brush rectangle.
+     */
+    fillOpacity?: number;
+    /**
+     * The stroke opacity of the brush rectangle.
+     */
+    strokeOpacity?: number;
+    /**
+     * The fill color of the brush rectangle.
+     */
+    fill?: string;
+    /**
+     * The stroke color of the brush rectangle.
+     */
+    stroke?: string;
+}
+/** Options for 1D interval interactors. */
+export interface Interval1DOptions {
+    /**
+     * The output selection. A clause of the form `field BETWEEN lo AND hi`
+     * is added for the currently selected interval [lo, hi].
+     */
+    as: ParamRef;
+    /**
+     * The name of the field (database column) over which the interval
+     * selection should be defined. If unspecified, the  channel field of the
+     * first valid prior mark definition is used.
+     */
+    field?: string;
+    /**
+     * The size of an interative pixel (default `1`). Larger pixel sizes reduce
+     * the brush resolution, which can reduce the size of data cube indexes.
+     */
+    pixelSize?: number;
+    /**
+     * 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;
+    /**
+     * CSS styles for the brush (SVG `rect`) element.
+     */
+    brush?: BrushStyles;
+}
+/** An intervalX interactor. */
+export interface IntervalX extends Interval1DOptions {
+    /** Select a continuous 1D interval selection over the `x` scale domain. */
+    select: 'intervalX';
+}
+/** An intervalY interactor. */
+export interface IntervalY extends Interval1DOptions {
+    /** Select a continuous 1D interval selection over the `y` scale domain. */
+    select: 'intervalY';
+}

package/dist/types/spec/interactors/Interval2D.d.ts

@@ -0,0 +1,46 @@
+import { ParamRef } from '../Param.js';
+import { BrushStyles } from './Interval1D.js';
+/** Options for 2D interval interactors. */
+export interface Interval2DOptions {
+    /**
+     * The output selection. A clause of the form
+     * `(xfield BETWEEN x1 AND x2) AND (yfield BETWEEN y1 AND y2)`
+     * is added for the currently selected intervals.
+     */
+    as: ParamRef;
+    /**
+     * The name of the field (database column) over which the `x`-component
+     * of the interval selection 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 interval selection should be defined. If unspecified, the `y`
+     * channel field of the first valid prior mark definition is used.
+     */
+    yfield?: string;
+    /**
+     * The size of an interative pixel (default `1`). Larger pixel sizes reduce
+     * the brush resolution, which can reduce the size of data cube indexes.
+     */
+    pixelSize?: number;
+    /**
+     * 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;
+    /**
+     * CSS styles for the brush (SVG `rect`) element.
+     */
+    brush?: BrushStyles;
+}
+/** An intervalXY interactor. */
+export interface IntervalXY extends Interval2DOptions {
+    /**
+     * Select a continuous 2D interval selection
+     * over the `x` and `y` scale domains.
+     */
+    select: 'intervalXY';
+}

package/dist/types/spec/interactors/Nearest.d.ts

@@ -0,0 +1,25 @@
+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 name of the field (database column) over which the nearest
+     * selection should be defined. If unspecified, the  channel field of the
+     * first valid prior mark definition is used.
+     */
+    field?: string;
+}
+/** A nearestX interactor. */
+export interface NearestX extends NearestOptions {
+    /** Select the **x** domain value of the mark closest to the pointer. */
+    select: 'nearestX';
+}
+/** A nearestY interactor. */
+export interface NearestY extends NearestOptions {
+    /** Select the **y** domain value of the mark closest to the pointer. */
+    select: 'nearestY';
+}

package/dist/types/spec/interactors/PanZoom.d.ts

@@ -0,0 +1,58 @@
+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/dist/types/spec/interactors/Toggle.d.ts

@@ -0,0 +1,51 @@
+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 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';
+}