@genome-spy/core 0.68.0 → 0.69.0

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

@@ -16,7 +16,6 @@ import {
 } from "./mark.js";
 import { ExprRef } from "./parameter.js";
 import { Title } from "./title.js";
-import { SampleSpec } from "./sampleView.js";
 import { Parameter } from "./parameter.js";
 
 export interface SizeDef {
@@ -46,19 +45,33 @@ export interface FacetMapping {
  * The opacity is interpolated between the specified stops.
  */
 export interface DynamicOpacity {
-    channel?: PrimaryPositionalChannel;
+    /**
+     * The positional channel whose scale domain controls the opacity.
+     * If set to `"auto"`, both `x` and `y` scales may contribute.
+     *
+     * If omitted, `x` is used when available and `y` is used as a fallback.
+     */
+    channel?: PrimaryPositionalChannel | "auto";
 
     /**
-     * Stops expressed as units (base pairs, for example) per pixel.
+     * Opacity stops expressed as units (base pairs, for example) per pixel.
+     * The values must be positive.
+     *
+     * Each stop is paired with an opacity in `values` at the same index.
+     * Stops can be constants or expression references.
      */
-    unitsPerPixel: number[];
+    unitsPerPixel: NumericStopDef[];
 
     /**
-     * Opacity values that match the given stops.
+     * Opacity values that match the given `unitsPerPixel` stops.
+     *
+     * Values outside the stop range are clamped to the nearest stop.
      */
     values: number[];
 }
 
+export type NumericStopDef = number | ExprRef;
+
 export type ViewOpacityDef = number | DynamicOpacity | ExprRef;
 
 export interface Step {
@@ -239,18 +252,35 @@ export interface ViewSpecBase extends ResolveSpec {
 
 export interface DynamicOpacitySpec {
     /**
-     * Opacity of the view and all its children. Allows implementing semantic
-     * zooming where the layers are faded in and out as the user zooms in and out.
+     * Opacity of the view and all its children.
+     *
+     * This can be:
      *
-     * TODO: Write proper documentation with examples.
+     * - a fixed number between `0` and `1`
+     * - an expression reference (`ExprRef`)
+     * - a `DynamicOpacity` definition for zoom-dependent opacity
      *
-     * **Default:** `1.0`
+     * Dynamic opacity is useful for semantic zooming where layers are faded in
+     * and out as the user zooms.
+     *
+     * Example:
+     *
+     * ```json
+     * "opacity": {
+     *   "unitsPerPixel": [100000, 40000],
+     *   "values": [0, 1]
+     * }
+     * ```
+     *
+     * In this example, the view fades in while zooming in from 100 000 to
+     * 40 000 units per pixel.
+     *
+     * __Default value:__ `1.0`
      */
     opacity?: ViewOpacityDef;
 }
 
-export interface UnitSpec
-    extends ViewSpecBase, DynamicOpacitySpec, AggregateSamplesSpec {
+export interface UnitSpec extends ViewSpecBase, DynamicOpacitySpec {
     /**
      * The background of the view, including fill, stroke, and stroke width.
      */
@@ -262,20 +292,66 @@ export interface UnitSpec
     mark: MarkType | MarkProps;
 }
 
-// TODO: Some fancy generic typing that would make Aggregating available only
-// inside SampleSpec.
-export interface AggregateSamplesSpec {
+export interface LayerSpec extends ViewSpecBase, DynamicOpacitySpec {
+    view?: ViewBackground;
+    layer: (LayerSpec | UnitSpec | MultiscaleSpec | ImportSpec)[];
+}
+
+export interface MultiscaleStops {
+    /**
+     * The metric used to evaluate zoom stops.
+     *
+     * __Default value:__ `"unitsPerPixel"`
+     */
+    metric?: "unitsPerPixel";
+
+    /**
+     * Stop values in descending order.
+     */
+    values: NumericStopDef[];
+
+    /**
+     * Which positional channel controls the stop metric.
+     *
+     * - `"auto"` averages `x` and `y` when both are available.
+     * - `"x"` uses only the `x` channel.
+     * - `"y"` uses only the `y` channel.
+     *
+     * __Default value:__ `"auto"`
+     */
+    channel?: PrimaryPositionalChannel | "auto";
+
     /**
-     * Specifies views that [aggregate](https://genomespy.app/docs/sample-collections/visualizing/#aggregation)
-     * multiple samples within the GenomeSpy App.
+     * Relative transition width around each stop.
+     *
+     * For each stop value `s`, the fade transition is evaluated in the range:
+     *
+     * - upper edge: `s * (1 + fade)`
+     * - lower edge: `s * (1 - fade)`
+     *
+     * __Default value:__ `0.5`
      */
-    aggregateSamples?: (UnitSpec | LayerSpec)[];
+    fade?: number;
 }
 
-export interface LayerSpec
-    extends ViewSpecBase, DynamicOpacitySpec, AggregateSamplesSpec {
+export type MultiscaleStopsDef = NumericStopDef[] | MultiscaleStops;
+
+export interface MultiscaleSpec extends ViewSpecBase, DynamicOpacitySpec {
     view?: ViewBackground;
-    layer: (LayerSpec | UnitSpec | ImportSpec)[];
+
+    /**
+     * Child views ordered from zoomed-out to zoomed-in detail levels.
+     */
+    multiscale: (LayerSpec | UnitSpec | MultiscaleSpec | ImportSpec)[];
+
+    /**
+     * Stop definition that controls transitions between the multiscale levels.
+     *
+     * - `number[]` is shorthand for `{ metric: "unitsPerPixel", values: ... }`
+     * - `(number | ExprRef)[]` supports mixed constants and expressions
+     * - Object form allows configuring metric, channel, and fade.
+     */
+    stops: MultiscaleStopsDef;
 }
 
 export interface FacetSpec extends ViewSpecBase {
@@ -313,25 +389,23 @@ export interface ResolveSpec {
     >;
 }
 
-export type ContainerSpec = (
-    | LayerSpec
-    //    | FacetSpec
-    | SampleSpec
-    | VConcatSpec
-    | HConcatSpec
-    | ConcatSpec
-    | UnitSpec
-) &
-    ResolveSpec;
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface ViewSpecExtensions {}
+
+export type ViewSpecExtension = ViewSpecExtensions[keyof ViewSpecExtensions];
 
-export type ViewSpec =
+export type CoreViewSpec =
     | UnitSpec
     | LayerSpec
+    | MultiscaleSpec
     //    | FacetSpec
     | VConcatSpec
     | HConcatSpec
-    | ConcatSpec
-    | SampleSpec;
+    | ConcatSpec;
+
+export type ContainerSpec = (CoreViewSpec | ViewSpecExtension) & ResolveSpec;
+
+export type ViewSpec = CoreViewSpec | ViewSpecExtension;
 
 export interface UrlImport {
     /**
@@ -362,6 +436,13 @@ export interface ImportSpec {
      */
     params?: Parameter[] | Record<string, any>;
 
+    /**
+     * Overrides the visibility of the imported view.
+     *
+     * If not specified, the imported specification's `visible` property is used.
+     */
+    visible?: boolean;
+
     /**
      * The method to import a specification.
      */

package/dist/src/tooltip/dataTooltipHandler.d.ts

@@ -1,2 +1,2 @@
-export default function dataTooltipHandler(datum: Record<string, any>, mark: import("../marks/mark.js").default, params?: Record<string, any>): Promise<string | import("lit-html").TemplateResult | HTMLElement>;
+export default function dataTooltipHandler(datum: Record<string, any>, mark: import("../marks/mark.js").default, params?: import("./tooltipHandler.js").TooltipHandlerParams, context?: import("./tooltipHandler.js").TooltipContext): Promise<string | import("lit-html").TemplateResult | HTMLElement>;
 //# sourceMappingURL=dataTooltipHandler.d.ts.map

package/dist/src/tooltip/dataTooltipHandler.js

@@ -1,10 +1,12 @@
 import { html } from "lit";
 import formatObject from "../utils/formatObject.js";
+import { flattenDatumRows } from "./flattenDatumRows.js";
+import createTooltipContext from "./tooltipContext.js";
 
 /**
  * @type {import("./tooltipHandler.js").TooltipHandler}
  */
-export default async function dataTooltipHandler(datum, mark, params) {
+export default async function dataTooltipHandler(datum, mark, params, context) {
     /**
      * @param {string} key
      * @param {object} datum
@@ -30,41 +32,30 @@ export default async function dataTooltipHandler(datum, mark, params) {
         return "";
     };
 
-    /**
-     *
-     * @param {[string, any][]} entries
-     * @param {string} [prefix]
-     * @returns {ReturnType<typeof html>[]}
-     */
-    const entriesToHtml = (entries, prefix) => {
-        const strippedEntries = entries.filter(
-            ([key, _value]) => !key.startsWith("_")
-        );
-
-        if (strippedEntries.length === 0) {
-            return;
-        }
+    const tooltipContext = context ?? createTooltipContext(datum, mark, params);
+    const rawRows = tooltipContext.flattenDatumRows
+        ? tooltipContext.flattenDatumRows()
+        : flattenDatumRows(datum);
+    const genomicRows = tooltipContext.genomicRows ?? [];
+    const hiddenRowKeys = new Set(tooltipContext.hiddenRowKeys ?? []);
 
-        return strippedEntries.map(([key, value]) =>
-            value !== null && typeof value === "object" && !Array.isArray(value)
-                ? html`${entriesToHtml(
-                      Object.entries(value),
-                      (prefix ? prefix : "") + key + "."
-                  )}`
-                : html`
-                      <tr>
-                          <th>${prefix}${key}</th>
-                          <td>${formatObject(value)} ${legend(key, datum)}</td>
-                      </tr>
-                  `
-        );
-    };
-
-    const tableContents = entriesToHtml(Object.entries(datum));
-    if (!tableContents) {
+    const visibleRawRows = rawRows.filter((row) => !hiddenRowKeys.has(row.key));
+    const orderedRows = [...genomicRows, ...visibleRawRows];
+    if (!orderedRows.length) {
         return;
     }
 
+    const tableContents = orderedRows.map((row) => {
+        const value = formatObject(row.value);
+        const valueLegend = legend(row.key, datum);
+        return html`
+            <tr>
+                <th>${row.key}</th>
+                <td>${value} ${valueLegend}</td>
+            </tr>
+        `;
+    });
+
     const table = html`
         <table class="attributes">
             ${tableContents}

package/dist/src/tooltip/dataTooltipHandler.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=dataTooltipHandler.test.d.ts.map

package/dist/src/tooltip/dataTooltipHandler.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dataTooltipHandler.test.d.ts","sourceRoot":"","sources":["../../../src/tooltip/dataTooltipHandler.test.js"],"names":[],"mappings":""}

package/dist/src/tooltip/flattenDatumRows.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @typedef {import("./tooltipHandler.js").TooltipRow} TooltipRow
+ */
+/**
+ * Flattens an object into tooltip rows using dot-separated keys.
+ * Keys starting with "_" are omitted.
+ *
+ * @param {Record<string, any>} datum
+ * @returns {TooltipRow[]}
+ */
+export function flattenDatumRows(datum: Record<string, any>): TooltipRow[];
+export type TooltipRow = import("./tooltipHandler.js").TooltipRow;
+//# sourceMappingURL=flattenDatumRows.d.ts.map

package/dist/src/tooltip/flattenDatumRows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flattenDatumRows.d.ts","sourceRoot":"","sources":["../../../src/tooltip/flattenDatumRows.js"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;GAMG;AACH,wCAHW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GACjB,UAAU,EAAE,CAOxB;yBAfY,OAAO,qBAAqB,EAAE,UAAU"}

package/dist/src/tooltip/flattenDatumRows.js

@@ -0,0 +1,47 @@
+/**
+ * @typedef {import("./tooltipHandler.js").TooltipRow} TooltipRow
+ */
+
+/**
+ * Flattens an object into tooltip rows using dot-separated keys.
+ * Keys starting with "_" are omitted.
+ *
+ * @param {Record<string, any>} datum
+ * @returns {TooltipRow[]}
+ */
+export function flattenDatumRows(datum) {
+    /** @type {TooltipRow[]} */
+    const rows = [];
+    collectRows(Object.entries(datum), rows);
+    return rows;
+}
+
+/**
+ * @param {[string, any][]} entries
+ * @param {TooltipRow[]} output
+ * @param {string} [prefix]
+ */
+function collectRows(entries, output, prefix) {
+    for (const [key, value] of entries) {
+        if (key.startsWith("_")) {
+            continue;
+        }
+
+        if (
+            value !== null &&
+            typeof value === "object" &&
+            !Array.isArray(value)
+        ) {
+            collectRows(
+                Object.entries(value),
+                output,
+                (prefix ? prefix : "") + key + "."
+            );
+        } else {
+            output.push({
+                key: (prefix ? prefix : "") + key,
+                value: value,
+            });
+        }
+    }
+}

package/dist/src/tooltip/flattenDatumRows.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=flattenDatumRows.test.d.ts.map

package/dist/src/tooltip/flattenDatumRows.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flattenDatumRows.test.d.ts","sourceRoot":"","sources":["../../../src/tooltip/flattenDatumRows.test.js"],"names":[],"mappings":""}

package/dist/src/tooltip/refseqGeneTooltipHandler.d.ts

@@ -1,2 +1,2 @@
-export default function refseqGeneTooltipHandler(datum: Record<string, any>, mark: import("../marks/mark.js").default, params?: Record<string, any>): Promise<string | import("lit-html").TemplateResult | HTMLElement>;
+export default function refseqGeneTooltipHandler(datum: Record<string, any>, mark: import("../marks/mark.js").default, params?: import("./tooltipHandler.js").TooltipHandlerParams, context?: import("./tooltipHandler.js").TooltipContext): Promise<string | import("lit-html").TemplateResult | HTMLElement>;
 //# sourceMappingURL=refseqGeneTooltipHandler.d.ts.map

package/dist/src/tooltip/refseqGeneTooltipHandler.js

@@ -23,12 +23,18 @@ export default async function refseqGeneTooltipHandler(
 ) {
     const symbol = datum.symbol;
 
+    /** @type {Record<string, string>} */
     const term = {
         ...defaultParams,
-        ...params,
         GENE: symbol,
     };
 
+    for (const [key, value] of Object.entries(params)) {
+        if (typeof value === "string") {
+            term[key] = value;
+        }
+    }
+
     let summary =
         symbolSummaryCache.get(symbol) ??
         (await debouncedFetchGeneSummary(term));

package/dist/src/tooltip/tooltipContext.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Creates a stable context object for tooltip handlers.
+ *
+ * @param {Record<string, any>} datum
+ * @param {import("../marks/mark.js").default} mark
+ * @param {import("./tooltipHandler.js").TooltipHandlerParams} [params]
+ * @returns {TooltipContext}
+ */
+export default function createTooltipContext(datum: Record<string, any>, mark: import("../marks/mark.js").default, params?: import("./tooltipHandler.js").TooltipHandlerParams): TooltipContext;
+export type TooltipContext = import("./tooltipHandler.js").TooltipContext;
+export type TooltipGenomicDisplayMode = import("./tooltipHandler.js").TooltipGenomicDisplayMode;
+export type TooltipRow = import("./tooltipHandler.js").TooltipRow;
+//# sourceMappingURL=tooltipContext.d.ts.map

package/dist/src/tooltip/tooltipContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltipContext.d.ts","sourceRoot":"","sources":["../../../src/tooltip/tooltipContext.js"],"names":[],"mappings":"AA2BA;;;;;;;GAOG;AACH,oDALW,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,QACnB,OAAO,kBAAkB,EAAE,OAAO,WAClC,OAAO,qBAAqB,EAAE,oBAAoB,GAChD,cAAc,CAgE1B;6BAhGY,OAAO,qBAAqB,EAAE,cAAc;wCAC5C,OAAO,qBAAqB,EAAE,yBAAyB;yBACvD,OAAO,qBAAqB,EAAE,UAAU"}