@genome-spy/core 0.78.0 → 0.79.1

package/dist/src/scales/viewLevelGuideConfig.js

@@ -0,0 +1,224 @@
+import { VISIT_SKIP } from "../view/view.js";
+import { visitNonChromeViews } from "../view/viewSelectors.js";
+
+/**
+ * @typedef {import("../spec/channel.js").ChannelWithScale} ChannelWithScale
+ * @typedef {import("../spec/channel.js").PrimaryPositionalChannel} PrimaryPositionalChannel
+ * @typedef {import("../spec/axis.js").Axis & import("../spec/axis.js").GenomeAxis} AxisConfig
+ * @typedef {import("../spec/legend.js").Legend} LegendConfig
+ * @typedef {import("../view/view.js").default} View
+ * @typedef {import("./axisResolution.js").default} AxisResolution
+ * @typedef {import("./legendResolution.js").default} LegendResolution
+ *
+ * @typedef {object} ViewLevelAxisConfigMapping
+ * @prop {View} view
+ * @prop {PrimaryPositionalChannel} channel
+ * @prop {Partial<AxisConfig>} config
+ * @prop {AxisResolution | undefined} resolution
+ *
+ * @typedef {object} ViewLevelLegendConfigMapping
+ * @prop {View} view
+ * @prop {ChannelWithScale} channel
+ * @prop {LegendConfig} config
+ * @prop {LegendResolution | undefined} resolution
+ *
+ * @typedef {object} GuideConfigSpec
+ * @prop {"axes" | "legends"} configKey
+ * @prop {"axis" | "legend"} resolutionType
+ * @prop {(view: View, channel: any) => AxisResolution | LegendResolution | undefined} getResolution
+ * @prop {(view: View) => Iterable<AxisResolution | LegendResolution>} getAllResolutions
+ * @prop {(resolution: any, view: View, config: any) => void} attach
+ * @prop {(resolution: any) => { view: View } | undefined} getAttachedConfig
+ * @prop {(resolution: any, view: View) => void} clear
+ */
+
+/** @type {GuideConfigSpec} */
+const AXIS_GUIDE = {
+    configKey: "axes",
+    resolutionType: "axis",
+    getResolution: (view, channel) => view.getAxisResolution(channel),
+    getAllResolutions: (view) => Object.values(view.resolutions.axis),
+    attach: (resolution, view, config) =>
+        resolution.attachViewLevelAxisConfig(view, config),
+    getAttachedConfig: (resolution) => resolution.getViewLevelAxisConfig(),
+    clear: (resolution, view) => resolution.clearViewLevelAxisConfig(view),
+};
+
+/** @type {GuideConfigSpec} */
+const LEGEND_GUIDE = {
+    configKey: "legends",
+    resolutionType: "legend",
+    getResolution: (view, channel) => view.getLegendResolution(channel),
+    getAllResolutions: (view) => Object.values(view.resolutions.legend),
+    attach: (resolution, view, config) =>
+        resolution.attachViewLevelLegendConfig(view, config),
+    getAttachedConfig: (resolution) => resolution.getViewLevelLegendConfig(),
+    clear: (resolution, view) => resolution.clearViewLevelLegendConfig(view),
+};
+
+/**
+ * Maps view-level axis configs and attaches non-pending configs to their
+ * target resolutions.
+ *
+ * @param {View} root
+ * @returns {ViewLevelAxisConfigMapping[]}
+ */
+export function attachViewLevelAxisConfigs(root) {
+    return /** @type {ViewLevelAxisConfigMapping[]} */ (
+        attachViewLevelGuideConfigs(root, AXIS_GUIDE)
+    );
+}
+
+/**
+ * Maps view-level legend configs and attaches non-pending configs to their
+ * target resolutions.
+ *
+ * @param {View} root
+ * @returns {ViewLevelLegendConfigMapping[]}
+ */
+export function attachViewLevelLegendConfigs(root) {
+    return /** @type {ViewLevelLegendConfigMapping[]} */ (
+        attachViewLevelGuideConfigs(root, LEGEND_GUIDE)
+    );
+}
+
+/**
+ * Clears view-level guide configs owned by views in the subtree.
+ *
+ * @param {View} root
+ */
+export function clearViewLevelGuideConfigs(root) {
+    clearViewLevelGuideConfigsOfType(root, AXIS_GUIDE);
+    clearViewLevelGuideConfigsOfType(root, LEGEND_GUIDE);
+}
+
+/**
+ * @param {View} root
+ * @param {GuideConfigSpec} guide
+ * @returns {Array<ViewLevelAxisConfigMapping | ViewLevelLegendConfigMapping>}
+ */
+function attachViewLevelGuideConfigs(root, guide) {
+    clearViewLevelGuideConfigsOfType(root, guide);
+    const mappings = mapViewLevelGuideConfigs(root, guide);
+    for (const mapping of mappings) {
+        if (mapping.resolution) {
+            guide.attach(mapping.resolution, mapping.view, mapping.config);
+        }
+    }
+    return mappings;
+}
+
+/**
+ * Maps view-level guide configs to the unique guide resolution visible from
+ * each configured subtree. Configs with no matching resolution stay pending.
+ *
+ * @param {View} root
+ * @param {GuideConfigSpec} guide
+ * @returns {Array<ViewLevelAxisConfigMapping | ViewLevelLegendConfigMapping>}
+ */
+function mapViewLevelGuideConfigs(root, guide) {
+    /** @type {Array<ViewLevelAxisConfigMapping | ViewLevelLegendConfigMapping>} */
+    const mappings = [];
+
+    for (const view of root.getDescendants()) {
+        const configs = view.spec[guide.configKey];
+        if (!configs) {
+            continue;
+        }
+
+        for (const [channel, config] of Object.entries(configs)) {
+            mappings.push(
+                mapViewLevelGuideConfig(view, guide, channel, config)
+            );
+        }
+    }
+
+    return mappings;
+}
+
+/**
+ * @param {View} view
+ * @param {GuideConfigSpec} guide
+ * @param {string} channel
+ * @param {unknown} config
+ * @returns {ViewLevelAxisConfigMapping | ViewLevelLegendConfigMapping}
+ */
+function mapViewLevelGuideConfig(view, guide, channel, config) {
+    const resolutions = collectVisibleGuideResolutions(view, guide, channel);
+
+    if (resolutions.size > 1) {
+        throw new Error(
+            `View-level ${guide.configKey}.${channel} maps to multiple ${guide.resolutionType} resolutions. ` +
+                `Move ${guide.configKey}.${channel} closer to the intended subtree or configure ${guide.resolutionType} resolution explicitly.`
+        );
+    }
+
+    return {
+        view,
+        channel: /** @type {PrimaryPositionalChannel & ChannelWithScale} */ (
+            channel
+        ),
+        config: /** @type {Partial<AxisConfig> & LegendConfig} */ (config),
+        resolution: resolutions.values().next().value,
+    };
+}
+
+/**
+ * @param {View} view
+ * @param {GuideConfigSpec} guide
+ * @param {string} channel
+ * @returns {Set<AxisResolution | LegendResolution>}
+ */
+function collectVisibleGuideResolutions(view, guide, channel) {
+    /** @type {Set<AxisResolution | LegendResolution>} */
+    const resolutions = new Set();
+    visitNonChromeViews(view, (descendant) => {
+        if (
+            descendant !== view &&
+            descendant.getConfiguredOrDefaultResolution(
+                /** @type {ChannelWithScale} */ (channel),
+                guide.resolutionType
+            ) === "excluded"
+        ) {
+            return VISIT_SKIP;
+        }
+
+        const resolution = guide.getResolution(descendant, channel);
+        if (resolution) {
+            resolutions.add(resolution);
+        }
+    });
+    return resolutions;
+}
+
+/**
+ * @param {View} root
+ * @param {GuideConfigSpec} guide
+ */
+function clearViewLevelGuideConfigsOfType(root, guide) {
+    const views = new Set(root.getDescendants());
+    const resolutions = collectAllGuideResolutions(root, guide);
+
+    for (const resolution of resolutions) {
+        const config = guide.getAttachedConfig(resolution);
+        if (config && views.has(config.view)) {
+            guide.clear(resolution, config.view);
+        }
+    }
+}
+
+/**
+ * @param {View} view
+ * @param {GuideConfigSpec} guide
+ * @returns {Set<AxisResolution | LegendResolution>}
+ */
+function collectAllGuideResolutions(view, guide) {
+    /** @type {Set<AxisResolution | LegendResolution>} */
+    const resolutions = new Set();
+    for (const descendant of view.getDescendants()) {
+        for (const resolution of guide.getAllResolutions(descendant)) {
+            resolutions.add(resolution);
+        }
+    }
+    return resolutions;
+}

package/dist/src/scales/viewLevelScaleConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"viewLevelScaleConfig.d.ts","sourceRoot":"","sources":["../../../src/scales/viewLevelScaleConfig.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;GAMG;AACH,+CAHW,IAAI,GACF,2BAA2B,EAAE,CAwBzC;AAED;;;;;;GAMG;AACH,kDAHW,IAAI,GACF,2BAA2B,EAAE,CAczC;AAED;;;;GAIG;AACH,iDAFW,IAAI,QAYd;+BA/EY,OAAO,oBAAoB,EAAE,gBAAgB;oBAC7C,OAAO,kBAAkB,EAAE,KAAK;mBAChC,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO;;UAGzC,IAAI;aACJ,gBAAgB;YAChB,KAAK;gBACL,eAAe,GAAG,SAAS"}
+{"version":3,"file":"viewLevelScaleConfig.d.ts","sourceRoot":"","sources":["../../../src/scales/viewLevelScaleConfig.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH;;;;;;GAMG;AACH,+CAHW,IAAI,GACF,2BAA2B,EAAE,CAwBzC;AAED;;;;;;GAMG;AACH,kDAHW,IAAI,GACF,2BAA2B,EAAE,CAczC;AAED;;;;GAIG;AACH,iDAFW,IAAI,QAYd;+BA/EY,OAAO,oBAAoB,EAAE,gBAAgB;oBAC7C,OAAO,kBAAkB,EAAE,KAAK;mBAChC,OAAO,iBAAiB,EAAE,OAAO;8BACjC,OAAO,sBAAsB,EAAE,OAAO;;UAGzC,IAAI;aACJ,gBAAgB;YAChB,KAAK;gBACL,eAAe,GAAG,SAAS"}

package/dist/src/scales/viewLevelScaleConfig.js

@@ -1,3 +1,6 @@
+import { VISIT_SKIP } from "../view/view.js";
+import { visitNonChromeViews } from "../view/viewSelectors.js";
+
 /**
  * @typedef {import("../spec/channel.js").ChannelWithScale} ChannelWithScale
  * @typedef {import("../spec/scale.js").Scale} Scale
@@ -113,12 +116,20 @@ function mapViewLevelScaleConfig(view, channel, config) {
 function collectVisibleScaleResolutions(view, channel) {
     /** @type {Set<ScaleResolution>} */
     const resolutions = new Set();
-    for (const descendant of view.getDescendants()) {
+    visitNonChromeViews(view, (descendant) => {
+        if (
+            descendant !== view &&
+            descendant.getConfiguredOrDefaultResolution(channel, "scale") ===
+                "excluded"
+        ) {
+            return VISIT_SKIP;
+        }
+
         const resolution = descendant.getScaleResolution(channel);
         if (resolution) {
             resolutions.add(resolution);
         }
-    }
+    });
     return resolutions;
 }
 

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

@@ -2,20 +2,103 @@ import { Align, Baseline, FontStyle, FontWeight } from "./font.js";
 import { ZIndexProps } from "./decoration.js";
 
 export interface GenomeAxis extends Axis {
+    /**
+     * A boolean flag indicating if chromosome boundary ticks should be included as part of the genome axis.
+     *
+     * __Default value:__ `true`
+     */
     chromTicks?: boolean;
+
+    /**
+     * The size in pixels of chromosome boundary ticks.
+     *
+     * __Default value:__ `18`
+     * @minimum 0
+     */
     chromTickSize?: number;
+
+    /**
+     * The width, in pixels, of chromosome boundary ticks.
+     *
+     * __Default value:__ `1`
+     * @minimum 0
+     */
     chromTickWidth?: number;
+
+    /**
+     * The color of chromosome boundary ticks.
+     *
+     * __Default value:__ `"#989898"`
+     */
     chromTickColor?: string;
+
+    /**
+     * An array of alternating [stroke, space] lengths for dashed chromosome boundary ticks.
+     *
+     * __Default value:__ `[4, 2]`
+     */
     chromTickDash?: number[];
+
+    /**
+     * The pixel offset at which to start drawing with the chromosome tick dash array.
+     *
+     * __Default value:__ `1`
+     */
     chromTickDashOffset?: number;
 
+    /**
+     * A boolean flag indicating if chromosome name labels should be included as part of the genome axis.
+     *
+     * __Default value:__ `true`
+     */
     chromLabels?: boolean;
+
+    /**
+     * The font of chromosome name labels.
+     */
     chromLabelFont?: string;
+
+    /**
+     * Font size of chromosome name labels, in pixels.
+     *
+     * __Default value:__ `13`
+     * @minimum 0
+     */
     chromLabelFontSize?: number;
+
+    /**
+     * Font weight of chromosome name labels.
+     *
+     * __Default value:__ `"normal"`
+     */
     chromLabelFontWeight?: FontWeight;
+
+    /**
+     * Font style of chromosome name labels.
+     *
+     * __Default value:__ `"normal"`
+     */
     chromLabelFontStyle?: FontStyle;
+
+    /**
+     * Text color of chromosome name labels.
+     *
+     * __Default value:__ `"black"`
+     */
     chromLabelColor?: string;
+
+    /**
+     * The padding, in pixels, between chromosome boundary ticks and chromosome name labels.
+     *
+     * __Default value:__ `7`
+     */
     chromLabelPadding?: number;
+
+    /**
+     * Horizontal text alignment of chromosome name labels.
+     *
+     * __Default value:__ `"left"`
+     */
     chromLabelAlign?: Align;
     // TODO: chromLabelPerpendicularPadding
 
@@ -92,12 +175,15 @@ export interface GenomeAxis extends Axis {
 
 export type AxisOrient = "top" | "bottom" | "left" | "right";
 
+export type AxisPlacement = "outside" | "inside";
+
 export interface Axis extends BaseAxis, ZIndexProps {
     /**
      * Named style reference(s) resolved from `config.style`.
-     * If an array is provided, later styles override earlier ones.
+     * If an array is provided, later styles override earlier ones. Set to
+     * `null` to reset inherited axis styles.
      */
-    style?: string | string[];
+    style?: string | string[] | null;
 
     /**
      * The orientation of the axis. One of `"top"`, `"bottom"`, `"left"` or `"right"`. The orientation can be used to further specialize the axis type (e.g., a y axis oriented for the right edge of the chart).
@@ -106,6 +192,13 @@ export interface Axis extends BaseAxis, ZIndexProps {
      */
     orient?: AxisOrient;
 
+    /**
+     * Placement of the axis relative to the plotting area. Outside axes reserve layout space outside the plot. Inside axes are mirrored into the plot and do not reserve external layout space.
+     *
+     * __Default value:__ `"outside"`.
+     */
+    placement?: AxisPlacement;
+
     /**
      * The format specifier pattern for axis labels.
      * Must be a legal [d3-format](https://github.com/d3/d3-format#locale_format) specifier.
@@ -113,10 +206,23 @@ export interface Axis extends BaseAxis, ZIndexProps {
     format?: string;
 
     /**
-     * A title for the axis (none by default). Set to `null` to remove it.
+     * A title for the axis. By default, the title is derived from the encoding title,
+     * field, or expression. Set to `null` to remove it.
      */
     title?: string | null;
 
+    /**
+     * Fitting mode for the axis title. `"point"` anchors the title at the
+     * center of the axis without constraining its length. `"range"` constrains
+     * the title to the axis span using
+     * [ranged text](https://genomespy.app/docs/grammar/mark/text/#ranged-text),
+     * allowing it to be squeezed to fit and kept visible inside scrollable
+     * viewports.
+     *
+     * __Default value:__ `"point"`
+     */
+    titleFit?: "point" | "range";
+
     /**
      * The orthogonal offset in pixels by which to displace the axis from its position along the edge of the chart.
      */

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

@@ -11,6 +11,7 @@
 import { ExprRef } from "./parameter.js";
 import { Scale } from "./scale.js";
 import { GenomeAxis } from "./axis.js";
+import { Legend } from "./legend.js";
 
 // TODO: Rename Scalar to PrimitiveValue
 export type Scalar = string | number | boolean;
@@ -42,6 +43,11 @@ export type ChannelWithScale =
     | "dx"
     | "dy";
 
+export type NonPositionalChannelWithScale = Exclude<
+    ChannelWithScale,
+    PositionalChannel
+>;
+
 export type ChannelWithoutScale =
     | "uniqueId"
     | "search"
@@ -217,7 +223,8 @@ export interface ExprDef
  * Field definition of a mark property, which can contain a legend.
  */
 export type MarkPropFieldDef<T extends Type = Type> = ScaleFieldDef<T> &
-    LegendMixins;
+    LegendMixins &
+    FormatMixins;
 
 export type MarkPropExprDef<T extends Type = Type> = ExprDef &
     TypeMixins<T> &
@@ -237,8 +244,16 @@ export type MarkPropDatumDef<T extends Type> = LegendMixins &
  *
  * __See also:__ [`legend`](https://vega.github.io/vega-lite/docs/legend.html) documentation.
  */
-// TODO: legend?: Legend<ExprRef | SignalRef> | null;
-export type LegendMixins = Record<string, never>;
+export interface LegendMixins {
+    /**
+     * Legend properties for the encoding channel. If `null`, the legend for
+     * the channel is removed. If an object is provided, a legend is created
+     * even when legends are disabled by default in the config.
+     *
+     * __Default value:__ If undefined, configured legend defaults are applied.
+     */
+    legend?: Legend | null;
+}
 
 export type ConditionalTemplate =
     | FieldDef<any>
@@ -429,7 +444,11 @@ export type ChannelDef = Exclude<
 // TODO: Does this make sense?
 export type ChannelDefWithScale = ScaleMixins &
     TypeMixins<Type> &
-    DomainContributionMixins;
+    DomainContributionMixins &
+    TitleMixins &
+    Partial<FormatMixins> & {
+        axis?: GenomeAxis | null;
+    };
 
 export interface XIndexDef {
     /**

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>;
 }