@genome-spy/core 0.48.2 → 0.49.0

package/dist/src/selection/selection.js

@@ -0,0 +1,78 @@
+import { UNIQUE_ID_KEY } from "../data/transforms/identifier.js";
+import { validateParameterName } from "../view/paramMediator.js";
+
+/**
+ * @param {import("../data/flowNode.js").Datum} datum
+ * @returns {import("../types/selectionTypes.js").SinglePointSelection}
+ */
+export function createSinglePointSelection(datum) {
+    return {
+        type: "single",
+        datum,
+        uniqueId: datum?.[UNIQUE_ID_KEY],
+    };
+}
+
+/**
+ * @param {import("../types/selectionTypes.js").Selection} selection
+ * @param {import("../data/flowNode.js").Datum} datum
+ * @param {boolean} [empty] evaluate to true if the selection is empty
+ */
+export function selectionTest(selection, datum, empty = true) {
+    if (!selection || !datum) {
+        return false;
+    }
+
+    if (isSinglePointSelection(selection)) {
+        return selection.uniqueId == null
+            ? empty
+            : selection.uniqueId === datum[UNIQUE_ID_KEY];
+    } else if (isMultiPointSelection(selection)) {
+        return selection.uniqueIds.size == 0
+            ? empty
+            : selection.uniqueIds.has(datum[UNIQUE_ID_KEY]);
+    } else {
+        throw new Error("Not a selection: " + JSON.stringify(selection));
+    }
+}
+
+/**
+ * @param {{param: string, empty?: boolean}} params
+ */
+export function makeSelectionTestExpression(params) {
+    return `selectionTest(${validateParameterName(params.param)}, datum, ${!!(
+        params.empty ?? true
+    )})`;
+}
+
+/**
+ * @param {import("../types/selectionTypes.js").Selection} selection
+ * @returns {selection is import("../types/selectionTypes.js").RangeSelection}
+ */
+export function isRangeSelection(selection) {
+    return selection.type === "range";
+}
+
+/**
+ * @param {import("../types/selectionTypes.js").Selection} selection
+ * @returns {selection is import("../types/selectionTypes.js").SinglePointSelection}
+ */
+export function isSinglePointSelection(selection) {
+    return selection.type === "single";
+}
+
+/**
+ * @param {import("../types/selectionTypes.js").Selection} selection
+ * @returns {selection is import("../types/selectionTypes.js").MultiPointSelection}
+ */
+export function isMultiPointSelection(selection) {
+    return selection.type === "multi";
+}
+
+/**
+ * @param {import("../types/selectionTypes.js").Selection} selection
+ * @returns {selection is import("../types/selectionTypes.js").ProjectedSelection}
+ */
+export function isProjectedSelection(selection) {
+    return selection.type === "projected";
+}

package/dist/src/spec/channel.d.ts

@@ -12,6 +12,7 @@ import { ExprRef } from "./parameter.js";
 import { Scale } from "./scale.js";
 import { GenomeAxis } from "./axis.js";
 
+// TODO: Rename Scalar to PrimitiveValue
 export type Scalar = string | number | boolean;
 export type Value = Scalar | ExprRef | null;
 
@@ -39,8 +40,7 @@ export type ChannelWithScale =
     | "shape"
     | "angle"
     | "dx"
-    | "dy"
-    | "sample"; // Needed for collecting sample ids (domain) from multiple views
+    | "dy";
 
 export type ChannelWithoutScale =
     | "uniqueId"
@@ -48,7 +48,8 @@ export type ChannelWithoutScale =
     | "text"
     | "facetIndex"
     | "semanticScore"
-    | "uniqueId";
+    | "uniqueId"
+    | "sample"; // Needed for collecting sample ids (domain) from multiple views
 
 export type Channel = ChannelWithScale | ChannelWithoutScale;
 
@@ -96,7 +97,7 @@ export interface TypeMixins<T extends Type> {
     type: T;
 }
 
-export interface FieldDefBase<F> {
+export interface FieldDefBase {
     /**
      * __Required.__ A string defining the name of the field from which to pull a data value
      * or an object defining iterated values from the [`repeat`](https://vega.github.io/vega-lite/docs/repeat.html) operator.
@@ -109,22 +110,20 @@ export interface FieldDefBase<F> {
      * See more details about escaping in the [field documentation](https://vega.github.io/vega-lite/docs/field.html).
      * 2) `field` is not required if `aggregate` is `count`.
      */
-    field?: F;
+    field?: string;
 }
 
-export type TypedFieldDef<
-    F extends Field,
-    T extends Type = any
-> = FieldDefBase<F> & TitleMixins & TypeMixins<T>;
+export type FieldDef<T extends Type = Type> =
+    | SecondaryFieldDef
+    | TypedFieldDef<T>;
 
-export type ScaleFieldDef<F extends Field, T extends Type> = TypedFieldDef<
-    F,
-    T
-> &
-    ScaleMixins;
+export type TypedFieldDef<T extends Type = Type> = FieldDefBase &
+    TitleMixins &
+    TypeMixins<T>;
 
-export type FieldDefWithoutScale<F extends Field> = FieldDefBase<F> &
-    TitleMixins;
+export type ScaleFieldDef<T extends Type> = TypedFieldDef<T> & ScaleMixins;
+
+export type FieldDefWithoutScale = FieldDefBase & TitleMixins;
 
 export interface ScaleMixins {
     /**
@@ -155,27 +154,30 @@ export interface ValueDefBase<V extends Value = Scalar> {
 
 export type ValueDef<V extends Value = Scalar> = ValueDefBase<V> & TitleMixins;
 
-export interface DatumDefBase {
+export interface DatumDef<V extends Scalar | ExprRef = Scalar | ExprRef>
+    extends Partial<TypeMixins<Type>>,
+        BandMixins,
+        TitleMixins {
     /**
      * A constant value in data domain.
      */
-    datum?: Scalar | ExprRef;
+    datum?: V;
 }
 
-export type DatumDef = DatumDefBase & TitleMixins;
-
-export interface ExprDef {
-    /** An expression. Properties of the data can be accessed through the `datum` object. */
+export interface ExprDef<>extends Partial<TypeMixins<Type>>,
+        BandMixins,
+        TitleMixins {
+    /**
+     *  An expression. Properties of the data can be accessed through the `datum` object.
+     */
     expr: string;
 }
 
 /**
  * Field definition of a mark property, which can contain a legend.
  */
-export type MarkPropFieldDef<
-    F extends Field,
-    T extends Type = Type
-> = ScaleFieldDef<F, T> & LegendMixins;
+export type MarkPropFieldDef<T extends Type = Type> = ScaleFieldDef<T> &
+    LegendMixins;
 
 export type MarkPropExprDef<T extends Type = Type> = ExprDef &
     TypeMixins<T> &
@@ -186,11 +188,6 @@ export type MarkPropDatumDef<T extends Type> = LegendMixins &
     ScaleDatumDef &
     TypeMixins<T>;
 
-export type MarkPropFieldOrDatumOrExprDef<
-    F extends Field,
-    T extends Type = Type
-> = MarkPropFieldDef<F, T> | MarkPropDatumDef<T> | MarkPropExprDef;
-
 export interface LegendMixins {
     /**
      * An object defining properties of the legend.
@@ -203,15 +200,83 @@ export interface LegendMixins {
     // TODO: legend?: Legend<ExprRef | SignalRef> | null;
 }
 
-export type MarkPropDef<
-    F extends Field,
-    V extends Value,
-    T extends Type = Type
-> = MarkPropFieldOrDatumOrExprDef<F, T> | ValueDef<V>;
+export type ConditionalTemplate =
+    | FieldDef<any>
+    | DatumDef
+    | ValueDef<any>
+    | ExprRef;
+
+export type Conditional<CD extends ConditionalTemplate> =
+    ConditionalParameter<CD>;
 
-export type ColorDef<F extends Field> = MarkPropDef<F, string | null>;
+// Source of ParameterPredicate: https://github.com/vega/vega-lite/blob/main/src/predicate.ts
+export interface ParameterPredicate {
+    /**
+     * Filter using a parameter name.
+     */
+    param: string;
+
+    /**
+     * For selection parameters, the predicate of empty selections returns true by default.
+     * Override this behavior, by setting this property `empty: false`.
+     */
+    empty?: boolean;
+}
 
-export type SecondaryFieldDef<F extends Field> = FieldDefBase<F> & TitleMixins;
+export type ConditionalParameter<CD extends ConditionalTemplate> =
+    ParameterPredicate & CD;
+
+export interface ConditionValueDefMixins<V extends Value = Value> {
+    /**
+     * One or more value definition(s) with [a parameter or a test predicate](https://vega.github.io/vega-lite/docs/condition.html).
+     *
+     * __Note:__ A field definition's `condition` property can only contain [conditional value definitions](https://vega.github.io/vega-lite/docs/condition.html#value)
+     * since Vega-Lite only allows at most one encoded field per encoding channel.
+     */
+    condition?: Conditional<ValueDef<V>> | Conditional<ValueDef<V>>[];
+}
+
+/**
+ * A FieldDef with Condition<ValueDef>
+ * {
+ *   condition: {value: ...},
+ *   field: ...,
+ *   ...
+ * }
+ */
+export type FieldOrDatumDefWithCondition<
+    F extends FieldDef<any> | DatumDef<any> = FieldDef<any> | DatumDef<any>,
+    V extends Value = Value
+> = F & ConditionValueDefMixins<V | ExprRef>;
+
+/**
+ * @minProperties 1
+ */
+export type ValueDefWithCondition<V extends Value = Value> = Partial<
+    ValueDef<V | ExprRef>
+> & {
+    /**
+     * A field definition or one or more value definition(s) with a parameter predicate.
+     */
+    condition?:
+        | Conditional<FieldDef>
+        | Conditional<DatumDef>
+        | Conditional<ValueDef<V | ExprRef>>;
+};
+
+export type MarkPropFieldOrDatumOrExprDef<T extends Type = Type> =
+    | MarkPropFieldDef<T>
+    | MarkPropDatumDef<T>
+    | MarkPropExprDef<T>;
+
+export type MarkPropDef<V extends Value, T extends Type = Type> =
+    | FieldOrDatumDefWithCondition<MarkPropFieldDef<T>, V>
+    | FieldOrDatumDefWithCondition<DatumDef, V>
+    | ValueDefWithCondition<V>;
+
+export type ColorDef = MarkPropDef<string | null>;
+
+export type SecondaryFieldDef = FieldDefBase & TitleMixins;
 
 export type NumericValueDef = ValueDef<number>;
 
@@ -219,8 +284,7 @@ export type ScaleDatumDef = ScaleMixins & DatumDef;
 
 export type PositionDatumDefBase = ScaleDatumDef & TypeMixins<Type>;
 
-export type PositionFieldDef<F extends Field> = PositionFieldDefBase<F> &
-    PositionMixins;
+export type PositionFieldDef = PositionFieldDefBase & PositionMixins;
 
 export type PositionDatumDef = PositionDatumDefBase & PositionMixins;
 
@@ -243,7 +307,7 @@ export interface PositionMixins extends BandMixins {
     axis?: GenomeAxis | null;
 }
 
-export type PositionFieldDefBase<F extends Field> = ScaleFieldDef<F, Type>;
+export type PositionFieldDefBase = ScaleFieldDef<Type>;
 
 export interface ChromPosDefBase extends BandMixins {
     /**
@@ -278,39 +342,29 @@ export type ChromPosDef = SecondaryChromPosDef &
     TypeMixins<"locus"> &
     ScaleMixins;
 
-export type PositionDef<F extends Field> =
-    | PositionFieldDef<F>
+export type PositionDef =
+    | PositionFieldDef
     | ChromPosDef
     | PositionDatumDef
     | PositionExprDef
     | PositionValueDef;
 
-export type Position2Def<F extends Field> =
-    | (SecondaryFieldDef<F> & BandMixins)
+export type Position2Def =
+    | (SecondaryFieldDef & BandMixins)
     | SecondaryChromPosDef
     | (DatumDef & BandMixins)
     | (ExprDef & BandMixins)
     | PositionValueDef;
 
-export type NumericMarkPropDef<F extends Field> = MarkPropDef<F, number>;
+export type NumericMarkPropDef = MarkPropDef<number>;
 
-export type ShapeDef<F extends Field> = MarkPropDef<
-    F,
-    string | null,
-    TypeForShape
->;
+export type ShapeDef = MarkPropDef<string | null, TypeForShape>;
 
-export interface StringFieldDef<F extends Field>
-    extends FieldDefWithoutScale<F>,
-        FormatMixins {}
+export interface StringFieldDef extends FieldDefWithoutScale, FormatMixins {}
 
-export type TextDef<F extends Field> =
-    | StringFieldDef<F>
-    | StringDatumDef
-    | ExprDef;
+export type TextDef = StringFieldDef | StringDatumDef | ExprDef; // TODO: Conditions
 
-export type ChannelDef<F extends Field = string> =
-    Encoding<F>[keyof Encoding<F>];
+export type ChannelDef = Encoding[keyof Encoding];
 
 // TODO: Does this make sense?
 export type ChannelDefWithScale = ScaleMixins & TypeMixins<Type>;
@@ -328,37 +382,37 @@ export interface XIndexDef {
     buildIndex?: boolean;
 }
 
-export interface Encoding<F extends Field = string> {
+export interface Encoding {
     /**
      * X coordinates of the marks.
      *
      * The `value` of this channel can be a number between zero and one.
      */
-    x?: PositionDef<F> & XIndexDef;
+    x?: PositionDef & XIndexDef;
 
     /**
      * Y coordinates of the marks.
      *
      * The `value` of this channel can be a number between zero and one.
      */
-    y?: PositionDef<F>;
+    y?: PositionDef;
 
     /**
      * X2 coordinates of the marks.
      *
      * The `value` of this channel can be a number between zero and one.
      */
-    x2?: Position2Def<F>;
+    x2?: Position2Def;
 
     /**
      * Y2 coordinates of the marks.
      *
      * The `value` of this channel can be a number between zero and one.
      */
-    y2?: Position2Def<F>;
+    y2?: Position2Def;
 
-    dx?: NumericMarkPropDef<F>;
-    dy?: NumericMarkPropDef<F>;
+    dx?: NumericMarkPropDef; // TODO: Not a mark property. Fix types.
+    dy?: NumericMarkPropDef;
 
     /**
      * Color of the marks – either fill or stroke color based on  the `filled` property of mark definition.
@@ -367,14 +421,14 @@ export interface Encoding<F extends Field = string> {
      * 1) For fine-grained control over both fill and stroke colors of the marks, please use the `fill` and `stroke` channels. The `fill` or `stroke` encodings have higher precedence than `color`, thus may override the `color` encoding if conflicting encodings are specified.
      * 2) See the scale documentation for more information about customizing [color scheme](https://vega.github.io/vega-lite/docs/scale.html#scheme).
      */
-    color?: ColorDef<F>;
+    color?: ColorDef;
 
     /**
      * Fill color of the marks.
      *
      * _Note:_ The `fill` encoding has higher precedence than `color`, thus may override the `color` encoding if conflicting encodings are specified.
      */
-    fill?: ColorDef<F>;
+    fill?: ColorDef;
 
     /**
      * Stroke color of the marks.
@@ -382,39 +436,39 @@ export interface Encoding<F extends Field = string> {
      * _Note:_ The `stroke` encoding has higher precedence than `color`, thus may override the `color` encoding if conflicting encodings are specified.
      */
 
-    stroke?: ColorDef<F>;
+    stroke?: ColorDef;
 
     /**
      * Opacity of the marks.
      */
-    opacity?: NumericMarkPropDef<F>;
+    opacity?: NumericMarkPropDef;
 
     /**
      * Fill opacity of the marks.
      */
-    fillOpacity?: NumericMarkPropDef<F>;
+    fillOpacity?: NumericMarkPropDef;
 
     /**
      * Stroke opacity of the marks.
      */
-    strokeOpacity?: NumericMarkPropDef<F>;
+    strokeOpacity?: NumericMarkPropDef;
 
     /**
      * Stroke width of the marks.
      */
-    strokeWidth?: NumericMarkPropDef<F>;
+    strokeWidth?: NumericMarkPropDef;
 
     /**
      * Size of the mark.
      * - For `"point"` – the symbol size, or pixel area of the mark.
      * - For `"text"` – the text's font size.
      */
-    size?: NumericMarkPropDef<F>;
+    size?: NumericMarkPropDef;
 
     /**
      * Rotation angle of point and text marks.
      */
-    angle?: NumericMarkPropDef<F>;
+    angle?: NumericMarkPropDef;
 
     /**
      * Shape of the mark.
@@ -423,32 +477,32 @@ export interface Encoding<F extends Field = string> {
      * - plotting shapes: `"circle"`, `"square"`, `"cross"`, `"diamond"`, `"triangle-up"`, `"triangle-down"`, `"triangle-right"`, or `"triangle-left"`.
      * - centered directional shape `"triangle"`
      */
-    shape?: ShapeDef<F>;
+    shape?: ShapeDef;
 
     /**
      * Text of the `text` mark.
      */
-    text?: TextDef<F>;
+    text?: TextDef;
 
     /**
      * Facet identifier for interactive filtering, sorting, and grouping in the App.
      */
-    sample?: FieldDefWithoutScale<F>;
+    sample?: FieldDefWithoutScale;
 
     /**
      * For internal use
      */
     // TODO: proper type
-    uniqueId?: FieldDefWithoutScale<F>;
+    uniqueId?: FieldDefWithoutScale;
 
     // TODO: proper type
-    search?: FieldDefWithoutScale<F>;
+    search?: FieldDefWithoutScale;
 
     /**
      * For internal use
      */
     // TODO: proper type
-    facetIndex?: FieldDefWithoutScale<F>;
+    facetIndex?: FieldDefWithoutScale;
 
-    semanticScore?: FieldDefWithoutScale<F>;
+    semanticScore?: FieldDefWithoutScale;
 }

package/dist/src/spec/mark.d.ts

@@ -386,6 +386,15 @@ export interface LinkProps extends SecondaryPositionProps {
      */
     arcFadingDistance?: [number, number] | false | ExprRef;
 
+    /**
+     * Disables fading of the link when an mark instance is subject to any point selection.
+     * As the fading distance is unavailable as a visual channel, this property allows for
+     * enhancing the visibility of the selected links.
+     *
+     * **Default value:** `true`
+     */
+    noFadingOnPointSelection?: boolean | ExprRef;
+
     /**
      * The minimum stroke width of the links when pointing with the mouse cursor.
      * Allows making very thin links easier to point at.

package/dist/src/spec/parameter.d.ts

@@ -1,3 +1,5 @@
+import { ChannelWithScale, Scalar } from "./channel.js";
+
 export interface ExprRef {
     /**
      * The expression string.
@@ -5,9 +7,7 @@ export interface ExprRef {
     expr: string;
 }
 
-// Adapted from: https://github.com/vega/vega-lite/blob/main/src/parameter.ts
-
-export interface VariableParameter {
+export interface ParameterBase {
     /**
      * A unique name for the variable parameter. Parameter names should be valid
      * JavaScript identifiers: they should contain only alphanumeric characters
@@ -16,6 +16,12 @@ export interface VariableParameter {
      */
     name: string;
 
+    push?: "outer";
+}
+
+// Adapted from: https://github.com/vega/vega-lite/blob/main/src/parameter.ts
+
+export interface VariableParameter extends ParameterBase {
     /**
      * The [initial value](http://vega.github.io/vega-lite/docs/value.html) of the parameter.
      *
@@ -144,3 +150,106 @@ export interface BindDirect {
 }
 
 export type Binding = BindCheckbox | BindRadioSelect | BindRange | BindInput;
+
+// ----------------------------------------------------------------------------
+// Adapted from: https://github.com/vega/vega-lite/blob/main/src/selection.ts
+
+type Vector2<T> = [T, T];
+
+export type SelectionType = "point" | "interval";
+export type SelectionInit = Scalar;
+export type SelectionInitInterval =
+    | Vector2<boolean>
+    | Vector2<number>
+    | Vector2<string>;
+
+export type InteractionEventType = "click" | "dblclick" | "mouseover";
+
+export interface BaseSelectionConfig<T extends SelectionType = SelectionType> {
+    /**
+     * Determines the default event processing and data query for the selection. Vega-Lite currently supports two selection types:
+     *
+     * - `"point"` -- to select multiple discrete data values; the first value is selected on `click` and additional values toggled on shift-click.
+     * - `"interval"` -- to select a continuous range of data values on `drag`.
+     */
+    type: T;
+
+    /**
+     */
+    on?: "click" | "mouseover" | "pointerover";
+
+    /**
+     * An array of encoding channels. The corresponding data field values
+     * must match for a data tuple to fall within the selection.
+     *
+     * __See also:__ The [projection with `encodings` and `fields` section](https://vega.github.io/vega-lite/docs/selection.html#project) in the documentation.
+     */
+    encodings?: ChannelWithScale[];
+
+    /**
+     * An array of field names whose values must match for a data tuple to
+     * fall within the selection.
+     *
+     * __See also:__ The [projection with `encodings` and `fields` section](https://vega.github.io/vega-lite/docs/selection.html#project) in the documentation.
+     */
+    fields?: string[];
+}
+
+export interface PointSelectionConfig extends BaseSelectionConfig<"point"> {
+    /**
+     * Controls whether data values should be toggled (inserted or removed from a point selection)
+     * when clicking with the shift key pressed.
+     *
+     * - `true` -- additional values can be selected by shift-clicking.
+     * - `false` -- only a single value can be selected at a time.
+     *
+     * __Default value:__ `true`
+     */
+    // TODO TODO TODO TODO TODO TODO TODO TODO
+    //toggle?: boolean;
+    /**
+     * A set of fields that uniquely identify a tuple. Used for bookmarking point selections
+     * in the GenomeSpy App. Still work in progress.
+     *
+     * TODO: Or maybe use the `key` channel? https://vega.github.io/vega-lite/docs/encoding.html#key
+     */
+    //keyFields?: string[];
+}
+
+export interface IntervalSelectionConfig
+    extends BaseSelectionConfig<"interval"> {
+    // TODO
+}
+
+export interface SelectionParameter<T extends SelectionType = SelectionType>
+    extends ParameterBase {
+    /**
+     * Determines the default event processing and data query for the selection. Vega-Lite currently supports two selection types:
+     *
+     * - `"point"` -- to select multiple discrete data values; the first value is selected on `click` and additional values toggled on shift-click.
+     * - `"interval"` -- to select a continuous range of data values on `drag`.
+     */
+    select:
+        | T
+        | (T extends "point"
+              ? PointSelectionConfig
+              : T extends "interval"
+              ? IntervalSelectionConfig
+              : never);
+
+    /*
+     * Initialize the selection with a mapping between [projected channels or field names](https://vega.github.io/vega-lite/docs/selection.html#project) and initial values.
+     *
+     * __See also:__ [`init`](https://vega.github.io/vega-lite/docs/value.html) documentation.
+     */
+    /*
+    // TODO TODO TODO TODO TODO TODO TODO TODO 
+    value?: T extends "point"
+        ? SelectionInit | SelectionInitMapping[]
+        : T extends "interval"
+        ? SelectionInitIntervalMapping
+        : never;
+        */
+}
+
+export type Parameter = VariableParameter | SelectionParameter;

package/dist/src/spec/root.d.ts

@@ -1,5 +1,4 @@
 import { GenomeConfig } from "./genome.js";
-import { VariableParameter } from "./parameter.js";
 import { ViewSpec } from "./view.js";
 
 interface RootConfig {