@genome-spy/core 0.78.0 → 0.79.0

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

@@ -12,7 +12,13 @@
  * Constants and utilities for data.
  */
 import { Axis } from "./axis.js";
-import { FieldName, PrimaryPositionalChannel } from "./channel.js";
+import {
+    ChannelWithScale,
+    FieldName,
+    PrimaryPositionalChannel,
+    Scalar,
+    Type as ChannelType,
+} from "./channel.js";
 import { ExprRef } from "./parameter.js";
 
 export type ParseValue =
@@ -172,14 +178,82 @@ export interface UrlList {
     type?: "json" | "csv" | "tsv";
 }
 
+export interface UrlTemplate {
+    /**
+     * URL template. The value from `values` is substituted for the placeholder
+     * named by `field`, for example `{sample}`.
+     */
+    template: string;
+
+    /**
+     * Values used for template expansion. Duplicate resolved URLs are loaded
+     * once. An ExprRef can reference reactive parameters such as
+     * `visibleSamples`.
+     */
+    values: Scalar[] | ExprRef;
+
+    /**
+     * Field name used as the template placeholder and as the datum field
+     * attached to loaded rows.
+     */
+    field: FieldName;
+
+    /**
+     * Whether to attach the template value to each loaded datum using `field`
+     * as the datum field name. Disable this when the expanded URL identifies
+     * only a file partition and the loaded data already contains the relevant
+     * identifiers.
+     *
+     * __Default value:__ `true`
+     */
+    attach?: boolean;
+
+    /**
+     * Maximum number of distinct resolved values to load. If the limit is
+     * exceeded, the source loads no data.
+     */
+    maxValues?: number;
+
+    /**
+     * Behavior when loading an expanded URL fails. The default `"error"`
+     * fails the data source. Use `"skip"` when some expanded URLs are expected
+     * to be unavailable, for example when data files for some patients have
+     * not been generated yet.
+     *
+     * __Default value:__ `"error"`
+     */
+    onLoadError?: "error" | "skip";
+}
+
+export interface IndexUrlTemplate {
+    /**
+     * URL template for index files. Uses the same values and field placeholder
+     * as the `url` template.
+     */
+    template: string;
+}
+
+export type UrlSourceRef = string | string[] | ExprRef | UrlList | UrlTemplate;
+
+export type SingleUrlSourceRef = string | ExprRef | UrlTemplate;
+
+export type MultiUrlSourceRef = string | string[] | ExprRef | UrlTemplate;
+
+export type IndexUrlSourceRef = string | ExprRef | IndexUrlTemplate;
+
 export interface UrlData extends DataBase {
     /**
-     * An URL or an array of URLs from which to load the data set.
+     * An URL, a list of URLs, or a URL expansion definition from which to load
+     * the data set.
+     *
+     * A URL template can expand values from an ExprRef and attach the expanded
+     * value as a field to loaded rows.
+     *
      * 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;
+    url: UrlSourceRef;
 }
 
 export interface InlineData extends DataBase {
@@ -263,6 +337,9 @@ export interface LazyData {
 
 export type LazyDataParams =
     | AxisTicksData
+    | LegendEntriesData
+    | LegendGradientData
+    | LegendGradientTicksData
     | AxisGenomeData
     | IndexedFastaData
     | BigWigData
@@ -312,6 +389,80 @@ export interface AxisTicksData {
     channel: PrimaryPositionalChannel;
 }
 
+/**
+ * Internal data source for generated legend entries.
+ *
+ * @internal
+ */
+export interface LegendEntriesData {
+    type: "legendEntries";
+
+    /** Which channel's scale domain to use */
+    channel: ChannelWithScale;
+
+    /** The data type of the source channel */
+    dataType?: ChannelType;
+
+    /** D3 number format specifier for labels */
+    format?: string;
+
+    /** Explicit legend values */
+    values?: Scalar[];
+
+    /** Number of representative entries to generate for quantitative scales */
+    count?: number;
+
+    /**
+     * Whether size entries should also include the scale output as a stroke
+     * width for stroke-based legend symbols.
+     *
+     * @internal
+     */
+    sizeMode?: "area" | "strokeWidth";
+}
+
+/**
+ * Internal data source for generated gradient legend ramp samples.
+ *
+ * @internal
+ */
+export interface LegendGradientData {
+    type: "legendGradient";
+
+    /** Which channel's scale domain to use */
+    channel: ChannelWithScale;
+
+    /** Number of ramp samples to generate */
+    count?: number;
+
+    /** D3 number format specifier for labels derived from this source */
+    format?: string;
+
+    /** Explicit tick values derived from this source */
+    values?: Scalar[];
+}
+
+/**
+ * Internal data source for generated gradient legend ticks.
+ *
+ * @internal
+ */
+export interface LegendGradientTicksData {
+    type: "legendGradientTicks";
+
+    /** Which channel's scale domain to use */
+    channel: ChannelWithScale;
+
+    /** Number of ticks to generate */
+    count?: number;
+
+    /** D3 number format specifier for tick labels */
+    format?: string;
+
+    /** Explicit tick values */
+    values?: Scalar[];
+}
+
 export interface AxisGenomeData {
     type: "axisGenome";
 
@@ -330,16 +481,18 @@ export interface IndexedFastaData extends DebouncedData {
     channel?: PrimaryPositionalChannel;
 
     /**
-     * URL of the fasta file.
+     * URL of the fasta file. URL templates must resolve to one URL.
      */
-    url: string;
+    url: SingleUrlSourceRef;
 
     /**
      * URL of the index file.
+     * When `url` is a template, this can be an index URL template using the
+     * same placeholder and values.
      *
      * __Default value:__ `url` + `".fai"`.
      */
-    indexUrl?: string;
+    indexUrl?: IndexUrlSourceRef;
 
     /**
      * Size of each chunk when fetching the fasta file. Data is only fetched
@@ -361,9 +514,10 @@ export interface BigWigData extends DebouncedData {
     channel?: PrimaryPositionalChannel;
 
     /**
-     * URL of the BigWig file.
+     * URL of the BigWig file. URL templates load multiple BigWig files and
+     * attach the template field to loaded rows.
      */
-    url: string | ExprRef;
+    url: MultiUrlSourceRef;
 
     /**
      * The approximate minimum width of each data bin, in pixels.
@@ -384,9 +538,10 @@ export interface BigBedData extends DebouncedData {
     channel?: PrimaryPositionalChannel;
 
     /**
-     * URL of the BigBed file.
+     * URL of the BigBed file. URL templates load multiple BigBed files and
+     * attach the template field to loaded rows.
      */
-    url: string | ExprRef;
+    url: MultiUrlSourceRef;
 
     /**
      * Size of each chunk when fetching the BigBed file. Data is only fetched
@@ -408,16 +563,18 @@ export interface BamData extends DebouncedData {
     channel?: PrimaryPositionalChannel;
 
     /**
-     * URL of the BigBed file.
+     * URL of the BAM file. URL templates must resolve to one URL.
      */
-    url: string;
+    url: SingleUrlSourceRef;
 
     /**
      * URL of the index file.
+     * When `url` is a template, this can be an index URL template using the
+     * same placeholder and values.
      *
      * __Default value:__ `url` + `".bai"`.
      */
-    indexUrl?: string;
+    indexUrl?: IndexUrlSourceRef;
 
     /**
      * Size of each chunk when fetching the BigBed file. Data is only fetched
@@ -437,16 +594,19 @@ export interface TabixData extends DebouncedData {
     channel?: PrimaryPositionalChannel;
 
     /**
-     * Url of the bgzip compressed file.
+     * URL of the bgzip-compressed file. URL templates load multiple files and
+     * attach the template field to loaded rows.
      */
-    url: string;
+    url: MultiUrlSourceRef;
 
     /**
-     * Url of the tabix index file.
+     * URL of the tabix index file.
+     * When `url` is a template, this can be an index URL template using the
+     * same placeholder and values.
      *
      * __Default value:__ `url` + `".tbi"`.
      */
-    indexUrl?: string;
+    indexUrl?: IndexUrlSourceRef;
 
     /**
      * Add a `chr` (boolean) or custom (string) prefix to the chromosome names

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

@@ -0,0 +1,246 @@
+import { Align, Baseline, FontStyle, FontWeight } from "./font.js";
+import { ExprRef } from "./parameter.js";
+
+export type LegendOrient =
+    | "left"
+    | "right"
+    | "top"
+    | "bottom"
+    | "top-left"
+    | "top-right"
+    | "bottom-left"
+    | "bottom-right";
+
+export type LegendDirection = "vertical" | "horizontal";
+
+export type LegendTitleOrient = "top" | "bottom" | "left" | "right";
+
+// TODO: Consider adding more Vega/Vega-Lite legend properties when concrete
+// use cases appear. Known gaps include tick controls (`tickCount`,
+// `tickMinStep`), explicit legend `type`, gradient sizing/styling knobs
+// (`gradientLength`, `gradientThickness`, `gradientOpacity`,
+// `gradientStrokeColor`, `gradientStrokeWidth`), label overlap controls, and
+// symbol override properties such as `symbolFillColor`, `symbolStrokeColor`,
+// `symbolOpacity`, and `symbolLimit`.
+
+/**
+ * Legend properties. The initial legend surface is adapted from Vega:
+ * https://github.com/vega/vega/
+ */
+export interface Legend {
+    /**
+     * Named style reference or references resolved from `config.style`. If an
+     * array is provided, later styles override earlier ones. Set to `null` to
+     * reset inherited legend styles.
+     */
+    style?: string | string[] | null;
+
+    /**
+     * Title text for the legend. If `null`, the title is removed.
+     */
+    title?: string | null;
+
+    /**
+     * The plot side or inside corner where the legend is placed. Side legends
+     * are placed outside the plot area. Corner legends are placed inside the
+     * plot area.
+     */
+    orient?: LegendOrient | ExprRef;
+
+    /**
+     * The direction in which legend entries are laid out.
+     */
+    direction?: LegendDirection;
+
+    /**
+     * External gap in pixels between the legend and the plot edge.
+     */
+    offset?: number;
+
+    /**
+     * Internal padding in pixels around the legend content and background.
+     */
+    padding?: number;
+
+    /**
+     * The number of columns in which to arrange symbol legend entries.
+     */
+    columns?: number;
+
+    /**
+     * Explicit values to show in the legend. For discrete symbol legends, the
+     * values define an ordered subset of entries. For quantitative symbol and
+     * gradient legends, the values define the shown representative values or
+     * ticks.
+     */
+    values?: (string | number | boolean)[];
+
+    /**
+     * Maximum label text width in pixels.
+     */
+    labelLimit?: number;
+
+    /**
+     * Fill color of the legend background.
+     */
+    backgroundFill?: string;
+
+    /**
+     * Opacity of the legend background fill.
+     */
+    backgroundFillOpacity?: number;
+
+    /**
+     * Stroke color of the legend background.
+     */
+    backgroundStroke?: string;
+
+    /**
+     * Stroke width of the legend background border.
+     */
+    backgroundStrokeWidth?: number;
+
+    /**
+     * Opacity of the legend background stroke.
+     */
+    backgroundStrokeOpacity?: number;
+
+    /**
+     * Symbol size in pixels squared.
+     */
+    symbolSize?: number;
+
+    /**
+     * Symbol shape.
+     */
+    symbolType?: string;
+
+    /**
+     * The side of the legend on which to place the title.
+     */
+    titleOrient?: LegendTitleOrient;
+}
+
+/**
+ * Legend defaults. The initial legend surface is adapted from Vega:
+ * https://github.com/vega/vega/
+ */
+export interface LegendConfig extends Legend {
+    /**
+     * Disable automatic legend creation. Use `legend: null` on an encoding
+     * channel to remove that channel's legend.
+     *
+     * __Default value:__ `false`
+     */
+    disable?: boolean | ExprRef;
+
+    /**
+     * Spacing in pixels between legends collected into the same legend region.
+     */
+    spacing?: number;
+
+    /**
+     * Padding between legend rows in pixels.
+     */
+    rowPadding?: number;
+
+    /**
+     * Padding between legend columns in pixels.
+     */
+    columnPadding?: number;
+
+    /**
+     * Horizontal alignment of legend labels.
+     */
+    labelAlign?: Align;
+
+    /**
+     * Baseline alignment of legend labels.
+     */
+    labelBaseline?: Baseline;
+
+    /**
+     * Legend label color.
+     */
+    labelColor?: string;
+
+    /**
+     * Legend label font.
+     */
+    labelFont?: string;
+
+    /**
+     * Legend label font size in pixels.
+     */
+    labelFontSize?: number;
+
+    /**
+     * Legend label font style.
+     */
+    labelFontStyle?: FontStyle;
+
+    /**
+     * Legend label font weight.
+     */
+    labelFontWeight?: FontWeight;
+
+    /**
+     * Offset between legend symbols and labels in pixels.
+     */
+    labelOffset?: number;
+
+    /**
+     * Offset applied to legend symbols in pixels.
+     */
+    symbolOffset?: number;
+
+    /**
+     * Legend symbol stroke width in pixels.
+     */
+    symbolStrokeWidth?: number;
+
+    /**
+     * Base fill color for legend symbols when the legend does not encode fill.
+     */
+    symbolBaseFillColor?: string;
+
+    /**
+     * Base stroke color for legend symbols when the legend does not encode stroke.
+     */
+    symbolBaseStrokeColor?: string;
+
+    /**
+     * Legend title color.
+     */
+    titleColor?: string;
+
+    /**
+     * Legend title font.
+     */
+    titleFont?: string;
+
+    /**
+     * Legend title font size in pixels.
+     */
+    titleFontSize?: number;
+
+    /**
+     * Legend title font style.
+     */
+    titleFontStyle?: FontStyle;
+
+    /**
+     * Legend title font weight.
+     */
+    titleFontWeight?: FontWeight;
+
+    /**
+     * Maximum title text width in pixels.
+     */
+    titleLimit?: number;
+
+    /**
+     * Padding in pixels between the legend title and the legend body.
+     */
+    titlePadding?: number;
+}

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

@@ -45,10 +45,14 @@ export interface MarkPropsBase {
     opacity?: number | ExprRef;
 
     /**
-     * If true, the mark is clipped to the UnitView's rectangle. By default, clipping
-     * is enabled for marks that have zoomable positional scales.
+     * Controls whether the mark is clipped to the UnitView's rectangle. The
+     * values `"x"` and `"y"` clip only in the corresponding screen-space
+     * direction. Inherited clipping from parent containers still applies unless
+     * `"never"` is used.
+     *
+     * __Default value:__ the direction of zoomable positional scales
      */
-    clip?: boolean | "never";
+    clip?: boolean | "x" | "y" | "never";
 
     /**
      * Offsets of the `x` and `x2` coordinates in pixels. The offset is applied
@@ -84,9 +88,17 @@ export interface MarkPropsBase {
      */
     buildIndex?: boolean;
 
+    /**
+     * Hide point-like mark instances whose anchor falls outside the inherited
+     * visible range in the given screen-space direction.
+     *
+     * @internal
+     */
+    cullByVisibleRange?: boolean | "x" | "y";
+
     /**
      * Tooltip handler. If `null`, no tooltip is shown. If string, specifies
-     * the [tooltip handler](https://genomespy.app/docs/api/#custom-tooltip-handlers)
+     * the [tooltip handler](https://genomespy.app/docs/api/embed-options/#custom-tooltip-handlers)
      * to use.
      */
     tooltip?: Tooltip;

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

@@ -22,6 +22,11 @@ export interface Title extends ZIndexProps {
      */
     text: string | ExprRef;
 
+    /**
+     * The subtitle text.
+     */
+    subtitle?: string | ExprRef;
+
     /**
      * A mark style property to apply to the title text mark. If not specified, a default style of `"group-title"` is applied.
      */
@@ -33,7 +38,11 @@ export interface Title extends ZIndexProps {
     anchor?: TitleAnchor;
 
     /**
-     * The reference frame for the anchor position, one of `"bounds"` (to anchor relative to the full bounding box) or `"group"` (to anchor relative to the group width or height).
+     * The reference frame for the title anchor. `"group"` anchors the title
+     * along the plot area. `"bounds"` anchors the title along the full bounds,
+     * including axes, legends, and other reserved space.
+     *
+     * __Default value:__ `"group"`
      */
     frame?: TitleFrame;
 
@@ -42,6 +51,18 @@ export interface Title extends ZIndexProps {
      */
     offset?: number;
 
+    /**
+     * Whether the title reserves layout space outside the plot area. Reserved
+     * titles are placed outside axes, legends, and other guide space on the same
+     * side.
+     *
+     * Setting this to `false` lets the title render without affecting layout,
+     * enabling wilder layouts where titles may overlap nearby content.
+     *
+     * __Default value:__ `true`
+     */
+    reserve?: boolean;
+
     /**
      * Z-order of the title relative to the view content.
      *
@@ -111,4 +132,40 @@ export interface Title extends ZIndexProps {
      * This can be either a string (e.g `"bold"`, `"normal"`) or a number (`100`, `200`, `300`, ..., `900` where `"normal"` = `400` and `"bold"` = `700`).
      */
     fontWeight?: FontWeight;
+
+    // ---------- Subtitle Text ----------
+    /**
+     * Text color for subtitle text.
+     */
+    subtitleColor?: string | ExprRef;
+
+    /**
+     * Font name for subtitle text.
+     */
+    subtitleFont?: string;
+
+    /**
+     * Font size in pixels for subtitle text.
+     *
+     * @minimum 0
+     */
+    subtitleFontSize?: number | ExprRef;
+
+    /**
+     * Font style for subtitle text.
+     */
+    subtitleFontStyle?: FontStyle;
+
+    /**
+     * Font weight for subtitle text.
+     * This can be either a string (e.g `"bold"`, `"normal"`) or a number (`100`, `200`, `300`, ..., `900` where `"normal"` = `400` and `"bold"` = `700`).
+     */
+    subtitleFontWeight?: FontWeight;
+
+    /**
+     * Padding in pixels between title and subtitle text.
+     *
+     * __Default value:__ `3`
+     */
+    subtitlePadding?: number;
 }