@genome-spy/core 0.77.0 → 0.79.0

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

@@ -0,0 +1,45 @@
+/**
+ * @typedef {import("../spec/channel.js").ChannelWithScale} ChannelWithScale
+ * @typedef {import("../spec/scale.js").Scale} Scale
+ * @typedef {import("../view/view.js").default} View
+ * @typedef {import("./scaleResolution.js").default} ScaleResolution
+ *
+ * @typedef {object} ViewLevelScaleConfigMapping
+ * @prop {View} view
+ * @prop {ChannelWithScale} channel
+ * @prop {Scale} config
+ * @prop {ScaleResolution | undefined} resolution
+ */
+/**
+ * Maps view-level scale configs to the unique scale resolution visible from
+ * each configured subtree. Configs with no matching resolution stay pending.
+ *
+ * @param {View} root
+ * @returns {ViewLevelScaleConfigMapping[]}
+ */
+export function mapViewLevelScaleConfigs(root: View): ViewLevelScaleConfigMapping[];
+/**
+ * Maps view-level scale configs and attaches non-pending configs to their
+ * target resolutions.
+ *
+ * @param {View} root
+ * @returns {ViewLevelScaleConfigMapping[]}
+ */
+export function attachViewLevelScaleConfigs(root: View): ViewLevelScaleConfigMapping[];
+/**
+ * Clears view-level scale configs owned by views in the subtree.
+ *
+ * @param {View} root
+ */
+export function clearViewLevelScaleConfigs(root: View): void;
+export type ChannelWithScale = import("../spec/channel.js").ChannelWithScale;
+export type Scale = import("../spec/scale.js").Scale;
+export type View = import("../view/view.js").default;
+export type ScaleResolution = import("./scaleResolution.js").default;
+export type ViewLevelScaleConfigMapping = {
+    view: View;
+    channel: ChannelWithScale;
+    config: Scale;
+    resolution: ScaleResolution | undefined;
+};
+//# sourceMappingURL=viewLevelScaleConfig.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,149 @@
+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
+ * @typedef {import("../view/view.js").default} View
+ * @typedef {import("./scaleResolution.js").default} ScaleResolution
+ *
+ * @typedef {object} ViewLevelScaleConfigMapping
+ * @prop {View} view
+ * @prop {ChannelWithScale} channel
+ * @prop {Scale} config
+ * @prop {ScaleResolution | undefined} resolution
+ */
+
+/**
+ * Maps view-level scale configs to the unique scale resolution visible from
+ * each configured subtree. Configs with no matching resolution stay pending.
+ *
+ * @param {View} root
+ * @returns {ViewLevelScaleConfigMapping[]}
+ */
+export function mapViewLevelScaleConfigs(root) {
+    /** @type {ViewLevelScaleConfigMapping[]} */
+    const mappings = [];
+
+    for (const view of root.getDescendants()) {
+        const scales = view.spec.scales;
+        if (!scales) {
+            continue;
+        }
+
+        for (const [channel, config] of Object.entries(scales)) {
+            mappings.push(
+                mapViewLevelScaleConfig(
+                    view,
+                    /** @type {ChannelWithScale} */ (channel),
+                    config
+                )
+            );
+        }
+    }
+
+    return mappings;
+}
+
+/**
+ * Maps view-level scale configs and attaches non-pending configs to their
+ * target resolutions.
+ *
+ * @param {View} root
+ * @returns {ViewLevelScaleConfigMapping[]}
+ */
+export function attachViewLevelScaleConfigs(root) {
+    clearViewLevelScaleConfigs(root);
+    const mappings = mapViewLevelScaleConfigs(root);
+    for (const mapping of mappings) {
+        if (mapping.resolution) {
+            mapping.resolution.attachViewLevelScaleConfig(
+                mapping.view,
+                mapping.config
+            );
+        }
+    }
+    return mappings;
+}
+
+/**
+ * Clears view-level scale configs owned by views in the subtree.
+ *
+ * @param {View} root
+ */
+export function clearViewLevelScaleConfigs(root) {
+    const views = new Set(root.getDescendants());
+    const resolutions = collectAllScaleResolutions(root);
+
+    for (const resolution of resolutions) {
+        const config = resolution.getViewLevelScaleConfig();
+        if (config && views.has(config.view)) {
+            resolution.clearViewLevelScaleConfig(config.view);
+        }
+    }
+}
+
+/**
+ * @param {View} view
+ * @param {ChannelWithScale} channel
+ * @param {Scale} config
+ * @returns {ViewLevelScaleConfigMapping}
+ */
+function mapViewLevelScaleConfig(view, channel, config) {
+    const resolutions = collectVisibleScaleResolutions(view, channel);
+
+    if (resolutions.size > 1) {
+        throw new Error(
+            `View-level scales.${channel} maps to multiple scale resolutions. ` +
+                `Move scales.${channel} closer to the intended subtree or configure scale resolution explicitly.`
+        );
+    }
+
+    const resolution = resolutions.values().next().value;
+    return {
+        view,
+        channel,
+        config,
+        resolution,
+    };
+}
+
+/**
+ * @param {View} view
+ * @param {ChannelWithScale} channel
+ * @returns {Set<ScaleResolution>}
+ */
+function collectVisibleScaleResolutions(view, channel) {
+    /** @type {Set<ScaleResolution>} */
+    const resolutions = new Set();
+    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;
+}
+
+/**
+ * @param {View} view
+ * @returns {Set<ScaleResolution>}
+ */
+function collectAllScaleResolutions(view) {
+    /** @type {Set<ScaleResolution>} */
+    const resolutions = new Set();
+    for (const descendant of view.getDescendants()) {
+        for (const resolution of Object.values(descendant.resolutions.scale)) {
+            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 {
     /**