@genome-spy/core 0.48.2 → 0.50.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 {
     /**
@@ -142,8 +141,19 @@ export interface ScaleMixins {
      * An alternative channel for scale resolution.
      *
      * This is mainly for internal use and allows using `color` channel to resolve `fill` and `stroke` channels under certain circumstances.
+     *
+     * @internal
      */
     resolutionChannel?: ChannelWithScale;
+
+    /**
+     * Whether the field or evaluated expr should be included in the scale's domain.
+     *
+     * **Default value:** `true`
+     *
+     * @internal
+     */
+    contributesToScaleDomain?: boolean;
 }
 
 export interface ValueDefBase<V extends Value = Scalar> {
@@ -155,27 +165,31 @@ 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,
+        ScaleMixins,
+        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 +200,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 +212,84 @@ 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 ColorDef<F extends Field> = MarkPropDef<F, string | null>;
+export type Conditional<CD extends ConditionalTemplate> =
+    ConditionalParameter<CD>;
 
-export type SecondaryFieldDef<F extends Field> = FieldDefBase<F> & TitleMixins;
+// 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 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>>
+        | 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 +297,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 +320,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 +355,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 +395,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 +434,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 +449,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 +490,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;
 }