@genome-spy/core 0.77.0 → 0.79.0

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

@@ -11,6 +11,8 @@ import {
 import { Scale, SchemeParams } from "./scale.js";
 import { Title } from "./title.js";
 import { ViewBackgroundProps } from "./decoration.js";
+import { LegendConfig } from "./legend.js";
+import { Step } from "./view.js";
 
 export type BuiltInThemeName =
     | "genomespy"
@@ -20,7 +22,44 @@ export type BuiltInThemeName =
     | "fivethirtyeight"
     | "urbaninstitute";
 
-export type ViewConfig = ViewBackgroundProps;
+export interface ViewConfig extends ViewBackgroundProps {
+    /**
+     * The default width when the view has a continuous x scale.
+     *
+     * __Default value:__ `"container"`
+     */
+    continuousWidth?: number;
+
+    /**
+     * The default width when the view has a discrete x scale or no x scale.
+     * This may be a fixed width or a step size for each discrete domain value.
+     *
+     * __Default value:__ `"container"`
+     */
+    discreteWidth?: number | Step;
+
+    /**
+     * The default height when the view has a continuous y scale.
+     *
+     * __Default value:__ `"container"`
+     */
+    continuousHeight?: number;
+
+    /**
+     * The default height when the view has a discrete y scale or no y scale.
+     * This may be a fixed height or a step size for each discrete domain value.
+     *
+     * __Default value:__ `"container"`
+     */
+    discreteHeight?: number | Step;
+
+    /**
+     * Default step size for discrete view sizes.
+     *
+     * __Default value:__ none
+     */
+    step?: number;
+}
 
 export type MarkConfig = Partial<Omit<MarkPropsBase, "type">>;
 
@@ -137,7 +176,9 @@ type CombinedStyleConfig = MergeProps<
     MergeProps<MergeProps<LinkConfig, AxisConfig>, TitleConfig>
 >;
 
-export type StyleConfig = Partial<CombinedStyleConfig>;
+export type StyleConfig = Partial<
+    MergeProps<CombinedStyleConfig, LegendConfig>
+>;
 
 export interface GenomeSpyConfig {
     /**
@@ -186,6 +227,20 @@ export interface GenomeSpyConfig {
      */
     axis?: AxisConfig;
 
+    /**
+     * Defaults shared by all legends. Set `disable` to `true` to suppress
+     * automatic legend creation by default.
+     */
+    legend?: LegendConfig;
+
+    /**
+     * Defaults for legends of track-like views that use `index` or `locus`
+     * scales on the x channel.
+     *
+     * __Default value:__ `{ "style": "track-bottom" }`
+     */
+    legendTrack?: LegendConfig;
+
     /**
      * Defaults for x axes.
      */
@@ -257,8 +312,8 @@ export interface GenomeSpyConfig {
     title?: TitleConfig;
 
     /**
-     * Named reusable style buckets that marks, axes, titles, and views can
-     * reference through their `style` properties.
+     * Named reusable style buckets that marks, axes, legends, titles, and
+     * views can reference through their `style` properties.
      */
     style?: Record<string, StyleConfig>;
 }

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;