@genome-spy/core 0.73.0 → 0.75.0

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

@@ -268,15 +268,17 @@ export type FieldOrDatumDefWithCondition<
 /**
  * @minProperties 1
  */
-export type ValueDefWithCondition<V extends Value = Value> = Partial<
-    ValueDef<V | ExprRef>
-> & {
+export type ValueDefWithCondition<
+    V extends Value = Value,
+    T extends Type = Type,
+> = Partial<ValueDef<V | ExprRef>> & {
     /**
      * A field definition or one or more value definition(s) with a parameter predicate.
      */
     condition?:
-        | Conditional<FieldDef>
-        | Conditional<DatumDef>
+        | Conditional<MarkPropFieldDef<T>>
+        | Conditional<ScaleDatumDef>
+        | Conditional<MarkPropExprDef<T>>
         | Conditional<ValueDef<V | ExprRef>>
         | Conditional<ValueDef<V | ExprRef>>[];
 };
@@ -289,7 +291,7 @@ export type MarkPropFieldOrDatumOrExprDef<T extends Type = Type> =
 export type MarkPropDef<V extends Value, T extends Type = Type> =
     | FieldOrDatumDefWithCondition<MarkPropFieldDef<T>, V>
     | FieldOrDatumDefWithCondition<ScaleDatumDef, V>
-    | ValueDefWithCondition<V>;
+    | ValueDefWithCondition<V, T>;
 
 export type ColorDef = MarkPropDef<string | null>;
 
@@ -381,9 +383,13 @@ export type NumericMarkPropDef = MarkPropDef<number>;
 
 export type ShapeDef = MarkPropDef<string | null, TypeForShape>;
 
-export interface StringFieldDef extends FieldDefWithoutScale, FormatMixins {}
+export type StringFieldDef = FieldDef<Type> & FormatMixins;
 
-export type TextDef = StringFieldDef | StringDatumDef | ExprDef; // TODO: Conditions
+export type TextDef =
+    | StringFieldDef
+    | StringDatumDef
+    | ExprDef
+    | ValueDef<string>; // TODO: Conditions
 
 export type ChannelDef = Exclude<
     Encoding[keyof Encoding],
@@ -428,17 +434,17 @@ export interface Encoding {
      *
      * The `value` of this channel can be a number between zero and one.
      */
-    x2?: Position2Def;
+    x2?: Position2Def | null;
 
     /**
      * Y2 coordinates of the marks.
      *
      * The `value` of this channel can be a number between zero and one.
      */
-    y2?: Position2Def;
+    y2?: Position2Def | null;
 
-    dx?: NumericMarkPropDef; // TODO: Not a mark property. Fix types.
-    dy?: NumericMarkPropDef;
+    dx?: NumericMarkPropDef | MarkPropExprDef; // TODO: Not a mark property. Fix types.
+    dy?: NumericMarkPropDef | MarkPropExprDef;
 
     /**
      * Color of the marks – either fill or stroke color based on  the `filled` property of mark definition.
@@ -549,5 +555,5 @@ export interface Encoding {
     // TODO: proper type
     facetIndex?: FieldDefWithoutScale;
 
-    semanticScore?: FieldDefWithoutScale;
+    semanticScore?: FieldDefWithoutScale & Partial<TypeMixins<Type>>;
 }

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

@@ -0,0 +1,264 @@
+import { Axis, GenomeAxis } from "./axis.js";
+import {
+    LinkProps,
+    MarkPropsBase,
+    PointProps,
+    RectProps,
+    RuleProps,
+    TickProps,
+    TextProps,
+} from "./mark.js";
+import { Scale, SchemeParams } from "./scale.js";
+import { Title } from "./title.js";
+import { ViewBackgroundProps } from "./decoration.js";
+
+export type BuiltInThemeName =
+    | "genomespy"
+    | "vegalite"
+    | "quartz"
+    | "dark"
+    | "fivethirtyeight"
+    | "urbaninstitute";
+
+export type ViewConfig = ViewBackgroundProps;
+
+export type MarkConfig = Partial<Omit<MarkPropsBase, "type">>;
+
+export type PointConfig = Partial<Omit<PointProps, "type">>;
+
+export type RectConfig = Partial<Omit<RectProps, "type">>;
+
+export type RuleConfig = Partial<Omit<RuleProps, "type">>;
+
+export type TickConfig = Partial<Omit<TickProps, "type">>;
+
+export type TextConfig = Partial<Omit<TextProps, "type">>;
+
+export type LinkConfig = Partial<Omit<LinkProps, "type">>;
+
+export type AxisConfig = Partial<Axis & GenomeAxis>;
+
+type ColorSchemeConfig = string | SchemeParams;
+
+export interface ScaleConfig extends Partial<Scale> {
+    /**
+     * Defaults for nominal scales.
+     */
+    nominal?: Partial<Scale>;
+
+    /**
+     * Defaults for ordinal scales.
+     */
+    ordinal?: Partial<Scale>;
+
+    /**
+     * Defaults for quantitative scales.
+     */
+    quantitative?: Partial<Scale>;
+
+    /**
+     * Defaults for GenomeSpy's `index` scales.
+     */
+    index?: Partial<Scale>;
+
+    /**
+     * Defaults for GenomeSpy's `locus` scales.
+     */
+    locus?: Partial<Scale>;
+
+    /**
+     * Default color scheme for nominal color scales.
+     */
+    nominalColorScheme?: ColorSchemeConfig;
+
+    /**
+     * Default color scheme for ordinal color scales.
+     */
+    ordinalColorScheme?: ColorSchemeConfig;
+
+    /**
+     * Default color scheme for quantitative color scales when no named range
+     * such as `"heatmap"` or `"ramp"` applies.
+     */
+    quantitativeColorScheme?: ColorSchemeConfig;
+}
+
+export interface RangeConfig {
+    /**
+     * Named range for `shape` channels.
+     */
+    shape?: string[];
+
+    /**
+     * Named range for `size` channels.
+     */
+    size?: number[];
+
+    /**
+     * Named range for `angle` channels.
+     */
+    angle?: number[];
+
+    /**
+     * Named range for quantitative rect-like color encodings such as heatmaps.
+     */
+    heatmap?: ColorSchemeConfig;
+
+    /**
+     * Named range for quantitative ramp color encodings.
+     */
+    ramp?: ColorSchemeConfig;
+
+    /**
+     * Named range for diverging color encodings.
+     */
+    diverging?: ColorSchemeConfig;
+}
+
+export type TitleConfig = Partial<Omit<Title, "text">>;
+
+type MergeProps<A, B> = {
+    [K in keyof A | keyof B]:
+        | (K extends keyof A ? A[K] : never)
+        | (K extends keyof B ? B[K] : never);
+};
+
+type CombinedStyleConfig = MergeProps<
+    MergeProps<
+        MergeProps<
+            MergeProps<
+                MergeProps<MergeProps<MarkConfig, PointConfig>, RectConfig>,
+                RuleConfig
+            >,
+            TickConfig
+        >,
+        TextConfig
+    >,
+    MergeProps<MergeProps<LinkConfig, AxisConfig>, TitleConfig>
+>;
+
+export type StyleConfig = Partial<CombinedStyleConfig>;
+
+export interface GenomeSpyConfig {
+    /**
+     * Defaults for view background styling, including fill, stroke, shadow,
+     * and z-order properties.
+     */
+    view?: ViewConfig;
+
+    /**
+     * Defaults shared by all mark types.
+     */
+    mark?: MarkConfig;
+
+    /**
+     * Defaults for point marks.
+     */
+    point?: PointConfig;
+
+    /**
+     * Defaults for rect marks.
+     */
+    rect?: RectConfig;
+
+    /**
+     * Defaults for rule marks.
+     */
+    rule?: RuleConfig;
+
+    /**
+     * Defaults for tick marks.
+     */
+    tick?: TickConfig;
+
+    /**
+     * Defaults for text marks.
+     */
+    text?: TextConfig;
+
+    /**
+     * Defaults for link marks.
+     */
+    link?: LinkConfig;
+
+    /**
+     * Defaults shared by all axes.
+     */
+    axis?: AxisConfig;
+
+    /**
+     * Defaults for x axes.
+     */
+    axisX?: AxisConfig;
+
+    /**
+     * Defaults for y axes.
+     */
+    axisY?: AxisConfig;
+
+    /**
+     * Defaults for top-oriented axes.
+     */
+    axisTop?: AxisConfig;
+
+    /**
+     * Defaults for bottom-oriented axes.
+     */
+    axisBottom?: AxisConfig;
+
+    /**
+     * Defaults for left-oriented axes.
+     */
+    axisLeft?: AxisConfig;
+
+    /**
+     * Defaults for right-oriented axes.
+     */
+    axisRight?: AxisConfig;
+
+    /**
+     * Defaults for axes that visualize nominal data.
+     */
+    axisNominal?: AxisConfig;
+
+    /**
+     * Defaults for axes that visualize ordinal data.
+     */
+    axisOrdinal?: AxisConfig;
+
+    /**
+     * Defaults for axes that visualize quantitative data.
+     */
+    axisQuantitative?: AxisConfig;
+
+    /**
+     * Defaults for axes that visualize GenomeSpy `index` scales.
+     */
+    axisIndex?: AxisConfig;
+
+    /**
+     * Defaults for axes that visualize GenomeSpy `locus` scales.
+     */
+    axisLocus?: AxisConfig;
+
+    /**
+     * Defaults for scale behavior and scale-type-specific buckets.
+     */
+    scale?: ScaleConfig;
+
+    /**
+     * Named reusable ranges for channels such as `shape`, `size`, and color.
+     */
+    range?: RangeConfig;
+
+    /**
+     * Defaults for view titles.
+     */
+    title?: TitleConfig;
+
+    /**
+     * Named reusable style buckets that marks, axes, titles, and views can
+     * reference through their `style` properties.
+     */
+    style?: Record<string, StyleConfig>;
+}

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

@@ -50,6 +50,12 @@ export interface DataFormatBase {
 
 export interface CsvDataFormat extends DataFormatBase {
     type?: "csv" | "tsv";
+
+    /**
+     * Optional ordered list of field names for headerless CSV or TSV input.
+     * When provided, the first row is interpreted as data rather than a header row.
+     */
+    columns?: string[];
 }
 
 export interface DsvDataFormat extends DataFormatBase {
@@ -62,6 +68,12 @@ export interface DsvDataFormat extends DataFormatBase {
      * @maxLength 1
      */
     delimiter: string;
+
+    /**
+     * Optional ordered list of field names for headerless delimiter-separated input.
+     * When provided, the first row is interpreted as data rather than a header row.
+     */
+    columns?: string[];
 }
 
 export interface JsonDataFormat extends DataFormatBase {
@@ -250,6 +262,13 @@ export interface DebouncedData {
      */
     debounce?: number | ExprRef;
 
+    /**
+     * Debounce time for scale-domain driven data updates, in milliseconds.
+     *
+     * __Default value:__ `200`
+     */
+    debounceDomainChange?: number | ExprRef;
+
     /**
      * The debounce mode for data updates. If set to `"domain"`, domain change
      * events (panning and zooming) will be debounced. If set to `"window"`,

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

@@ -0,0 +1,51 @@
+import { ShadowProps } from "./mark.js";
+
+export interface ZIndexProps {
+    /**
+     * Z-order relative to the view content.
+     *
+     * Values greater than `0` render after the view marks. Values less than or
+     * equal to `0` render before the marks.
+     * The default value depends on the element type.
+     */
+    zindex?: number;
+}
+
+export interface StrokeZIndexProps {
+    /**
+     * Z-order of the stroke relative to the view content.
+     *
+     * Values greater than `0` render the stroke after the view marks. Values
+     * less than or equal to `0` render before the marks.
+     * The default value depends on the element type.
+     */
+    strokeZindex?: number;
+}
+
+export interface ViewBackgroundProps
+    extends ShadowProps, ZIndexProps, StrokeZIndexProps {
+    /**
+     * Fill color of the view background.
+     */
+    fill?: string;
+
+    /**
+     * Opacity of the view background fill.
+     */
+    fillOpacity?: number;
+
+    /**
+     * Stroke color of the view background.
+     */
+    stroke?: string;
+
+    /**
+     * Stroke width of the view background border.
+     */
+    strokeWidth?: number;
+
+    /**
+     * Opacity of the view background stroke.
+     */
+    strokeOpacity?: number;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * Collects shared example specs used by the offline example suite.
+ *
+ * @returns {string[]}
+ */
+export function collectSharedExamplePaths(): string[];
+/**
+ * @param {string} examplePath
+ * @returns {any}
+ */
+export function loadSharedExampleSpec(examplePath: string): any;
+//# sourceMappingURL=exampleFiles.d.ts.map

package/dist/src/spec/exampleFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exampleFiles.d.ts","sourceRoot":"","sources":["../../../src/spec/exampleFiles.js"],"names":[],"mappings":"AASA;;;;GAIG;AACH,6CAFa,MAAM,EAAE,CAcpB;AAED;;;GAGG;AACH,mDAHW,MAAM,GACJ,GAAG,CAMf"}

package/dist/src/spec/exampleFiles.js

@@ -0,0 +1,52 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const packageDir = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(packageDir, "..", "..", "..", "..");
+
+const sharedExampleDirs = ["examples/core", "examples/docs"];
+
+/**
+ * Collects shared example specs used by the offline example suite.
+ *
+ * @returns {string[]}
+ */
+export function collectSharedExamplePaths() {
+    /** @type {string[]} */
+    const paths = [];
+
+    for (const dir of sharedExampleDirs) {
+        visit(path.join(repoRoot, dir), (absolutePath) => {
+            const relativePath = path.relative(repoRoot, absolutePath);
+            paths.push(relativePath.split(path.sep).join("/"));
+        });
+    }
+
+    return paths.sort();
+}
+
+/**
+ * @param {string} examplePath
+ * @returns {any}
+ */
+export function loadSharedExampleSpec(examplePath) {
+    return JSON.parse(
+        fs.readFileSync(path.join(repoRoot, examplePath), "utf8")
+    );
+}
+
+/**
+ * @param {string} dir
+ * @param {(absolutePath: string) => void} visitor
+ */
+function visit(dir, visitor) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const absolutePath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            visit(absolutePath, visitor);
+        } else if (entry.isFile() && entry.name.endsWith(".json")) {
+            visitor(absolutePath);
+        }
+    }
+}

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

@@ -12,4 +12,4 @@ export type FontWeight =
 
 export type Align = "left" | "center" | "right";
 
-export type Baseline = "top" | "middle" | "bottom" | "alphabetic";
+export type Baseline = "top" | "middle" | "bottom" | "alphabetic" | "baseline";

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

@@ -3,11 +3,25 @@ import { ExprRef } from "./parameter.js";
 import { Align, Baseline, FontStyle, FontWeight } from "./font.js";
 import { Tooltip } from "./tooltip.js";
 
-export type MarkType = "rect" | "point" | "rule" | "text" | "link";
+export type MarkType = "rect" | "point" | "rule" | "tick" | "text" | "link";
 
 export interface MarkPropsBase {
     type: MarkType;
 
+    /**
+     * Named style reference(s) resolved from `config.style`.
+     * If an array is provided, later styles override earlier ones.
+     */
+    style?: string | string[];
+
+    /**
+     * Mouse cursor shown while the pointer is over the mark.
+     * Mark cursor takes precedence over enclosing view cursors.
+     *
+     * __Default value:__ browser default
+     */
+    cursor?: string | ExprRef;
+
     // Channels.
 
     /**
@@ -62,6 +76,14 @@ export interface MarkPropsBase {
      */
     minBufferSize?: number;
 
+    /**
+     * Whether the x channel should build an index for efficient subset rendering.
+     * If omitted, GenomeSpy enables indexing automatically for positional x encodings.
+     *
+     * @internal
+     */
+    buildIndex?: boolean;
+
     /**
      * Tooltip handler. If `null`, no tooltip is shown. If string, specifies
      * the [tooltip handler](https://genomespy.app/docs/api/#custom-tooltip-handlers)
@@ -196,7 +218,8 @@ export interface ViewportEdgeFadeProps {
 }
 
 export interface RectProps
-    extends MarkPropsBase,
+    extends
+        MarkPropsBase,
         SecondaryPositionProps,
         FillAndStrokeProps,
         ShadowProps {
@@ -291,15 +314,10 @@ export interface RectProps
         | ExprRef;
 }
 
-export interface RuleProps
-    extends MarkPropsBase,
-        SecondaryPositionProps,
-        SizeProps {
-    type: "rule";
-
+export interface StrokeStyleProps {
     /**
-     * The minimum length of the rule in pixels. Use this property to ensure that
-     * very short ranged rules remain visible even when the user zooms out.
+     * The minimum stroke length in pixels. Use this property to ensure that
+     * very short strokes remain visible even when the user zooms out.
      *
      * **Default value:** `0`
      */
@@ -327,8 +345,38 @@ export interface RuleProps
     strokeCap?: "butt" | "square" | "round" | ExprRef;
 }
 
+export interface RuleProps
+    extends MarkPropsBase, SecondaryPositionProps, SizeProps, StrokeStyleProps {
+    type: "rule";
+}
+
+export interface TickProps extends MarkPropsBase, StrokeStyleProps {
+    type: "tick";
+
+    /**
+     * The orientation of the tick mark.
+     *
+     * If omitted, GenomeSpy infers the orientation when one positional channel
+     * uses a band-like scale and the other does not, or when the orthogonal
+     * channel is omitted. Specify `orient` explicitly when both `x` and `y`
+     * use band-like scales.
+     *
+     * **Default value:** inferred
+     */
+    orient?: "vertical" | "horizontal";
+
+    /**
+     * The thickness of the tick mark in pixels.
+     * Equivalent to the `size` of the underlying rule mark.
+     *
+     * **Default value:** `1`
+     */
+    thickness?: number;
+}
+
 export interface TextProps
-    extends MarkPropsBase,
+    extends
+        MarkPropsBase,
         SecondaryPositionProps,
         AngleProps,
         ViewportEdgeFadeProps,
@@ -457,7 +505,8 @@ export interface TextProps
 }
 
 export interface PointProps
-    extends MarkPropsBase,
+    extends
+        MarkPropsBase,
         FillAndStrokeProps,
         AngleProps,
         SizeProps,
@@ -482,6 +531,29 @@ export interface PointProps
      */
     inwardStroke?: boolean | ExprRef;
 
+    /**
+     * Horizontal offset in pixels.
+     *
+     * **Default value:** `0`
+     */
+    dx?: number | ExprRef;
+
+    /**
+     * Vertical offset in pixels.
+     *
+     * **Default value:** `0`
+     */
+    dy?: number | ExprRef;
+
+    /**
+     * Additional padding used by sample facets.
+     *
+     * **Default value:** `0.1`
+     *
+     * @internal
+     */
+    sampleFacetPadding?: number;
+
     /**
      * Gradient strength controls the amount of the gradient eye-candy effect in the fill color.
      * Valid values are between `0` and `1`.
@@ -490,6 +562,16 @@ export interface PointProps
      */
     fillGradientStrength?: number | ExprRef;
 
+    /**
+     * The semantic score used by semantic zooming in the point mark.
+     * This is primarily intended for internal use.
+     *
+     * **Default value:** `0`
+     *
+     * @internal
+     */
+    semanticScore?: number | ExprRef;
+
     /**
      * TODO
      *
@@ -507,7 +589,8 @@ export interface PointProps
 }
 
 export interface LinkProps
-    extends MarkPropsBase,
+    extends
+        MarkPropsBase,
         SecondaryPositionProps,
         SizeProps,
         MinPickingSizeProps {
@@ -603,5 +686,6 @@ export type MarkProps =
     | RectProps
     | TextProps
     | RuleProps
+    | TickProps
     | LinkProps
     | PointProps;