@genome-spy/core 0.72.0 → 0.74.0

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

@@ -42,6 +42,7 @@ export interface DataFormatBase {
      * Type of input data: `"json"`, `"csv"`, `"tsv"`, `"dsv"`.
      *
      * __Default value:__  The default format type is determined by the extension of the file URL.
+     * Compression suffixes such as `.gz` are ignored during inference.
      * If no extension is detected, `"json"` will be used by default.
      */
     type?: DataFormatType;
@@ -75,10 +76,25 @@ export interface JsonDataFormat extends DataFormatBase {
     property?: string;
 }
 
+export interface BedDataFormat extends DataFormatBase {
+    type: "bed";
+}
+
+export interface BedpeDataFormat extends DataFormatBase {
+    type: "bedpe";
+
+    /**
+     * Optional ordered list of field names for headerless BEDPE input.
+     * If omitted, BEDPE fields are resolved from the default BEDPE column
+     * order or from a matching header row when present.
+     */
+    columns?: string[];
+}
+
 /**
  * Other data format, such as `"fasta"`
  */
-export interface OtherDataFormat {
+export interface OtherDataFormat extends DataFormatBase {
     type: string;
 }
 
@@ -86,6 +102,8 @@ export type DataFormat =
     | CsvDataFormat
     | DsvDataFormat
     | JsonDataFormat
+    | BedDataFormat
+    | BedpeDataFormat
     | OtherDataFormat;
 
 export type DataFormatType = "json" | "csv" | "tsv" | "dsv" | string;
@@ -129,7 +147,7 @@ export interface UrlList {
     /**
      * The format of the data in the list.
      * If the type is `"json"`, the list is expected to be an array of strings.
-     * If the type is `"csv"` or `"tsv"`, the list is expected to be a table with a single column named `file`.
+     * If the type is `"csv"` or `"tsv"`, the list is expected to be a table with a single column named `url`.
      *
      * __Default value:__ `"txt"`
      */
@@ -139,7 +157,9 @@ export interface UrlList {
 export interface UrlData extends DataBase {
     /**
      * An URL or an array of URLs from which to load the data set.
-     * Use the `format.type` property to ensure the loaded data is correctly parsed.
+     * Gzip-compressed resources are decompressed transparently when the URL,
+     * MIME type, or payload indicates gzip content. Use the `format.type`
+     * property to ensure the loaded data is correctly parsed.
      */
     url: string | string[] | ExprRef | UrlList;
 }
@@ -230,6 +250,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/genome.d.ts

@@ -10,7 +10,7 @@ export interface GenomeConfigBase {
     name: string;
 }
 
-export interface UrlGenomeConfig extends GenomeConfigBase {
+export interface UrlGenomeDefinition {
     /**
      * A URL to a `chrom.sizes` file, which is a tab-separated file with two
      * columns: the sequence name and its size.
@@ -23,13 +23,33 @@ export interface UrlGenomeConfig extends GenomeConfigBase {
     url: string;
 }
 
-export interface InlineGenomeConfig extends GenomeConfigBase {
+export interface InlineGenomeDefinition {
     /**
      * An array of contigs/sequences in the genome assembly.
      */
     contigs: Contig[];
 }
 
+/**
+ * Genome definition for contexts where the name is provided externally
+ * (for example, as a key in root `genomes`) or not needed
+ * (for example, inline `scale.assembly`).
+ */
+export type GenomeDefinition = UrlGenomeDefinition | InlineGenomeDefinition;
+
+/**
+ * @deprecated Use `GenomeDefinition` in root `genomes` entries and `scale.assembly`.
+ */
+export type UrlGenomeConfig = GenomeConfigBase & UrlGenomeDefinition;
+
+/**
+ * @deprecated Use `GenomeDefinition` in root `genomes` entries and `scale.assembly`.
+ */
+export type InlineGenomeConfig = GenomeConfigBase & InlineGenomeDefinition;
+
+/**
+ * @deprecated Use root `genomes` and `assembly` instead of root `genome`.
+ */
 export type GenomeConfig =
     | UrlGenomeConfig
     | InlineGenomeConfig

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;