@genome-spy/core 0.72.0 → 0.74.0

package/dist/src/screenshotHarness.js

@@ -0,0 +1,241 @@
+import { embed, loadSpec } from "./index.js";
+
+const DEFAULT_CONTAINER_WIDTH = 600;
+const DEFAULT_CONTAINER_HEIGHT = 320;
+const DEFAULT_LAZY_READY_TIMEOUT_MS = 30_000;
+const READY_DELAY_MS = 100;
+
+/**
+ * @typedef {{
+ *   status: string,
+ *   detail: string,
+ *   error: string,
+ *   capture: () => Promise<{ logicalSize: { width: number, height: number }, dataUrl: string }>
+ * }} ScreenshotState
+ */
+
+/**
+ * @typedef {Window & typeof globalThis & { __genomeSpyScreenshot: ScreenshotState }} ScreenshotWindow
+ */
+
+const frameElement = /** @type {HTMLElement} */ (
+    document.querySelector("#frame")
+);
+const specPathElement = /** @type {HTMLElement} */ (
+    document.querySelector("#spec-path")
+);
+const statusElement = /** @type {HTMLElement} */ (
+    document.querySelector("#status")
+);
+const screenshotWindow = /** @type {ScreenshotWindow} */ (window);
+
+const query = new URLSearchParams(window.location.search);
+const specUrl = query.get("spec");
+const lazyReadyTimeoutMs = parseTimeoutMs(
+    query.get("lazy-timeout-ms"),
+    DEFAULT_LAZY_READY_TIMEOUT_MS
+);
+
+screenshotWindow.__genomeSpyScreenshot = {
+    status: "booting",
+    detail: "Booting screenshot harness",
+    error: "",
+    async capture() {
+        throw new Error("Screenshot harness is not ready yet.");
+    },
+};
+
+if (!specUrl) {
+    setFailure("Missing required ?spec=... query parameter.");
+} else {
+    specPathElement.textContent = specUrl;
+    frameElement.style.width = `${DEFAULT_CONTAINER_WIDTH}px`;
+    frameElement.style.height = `${DEFAULT_CONTAINER_HEIGHT}px`;
+    void initializeHarness(specUrl);
+}
+
+/**
+ * @param {string} url
+ */
+async function initializeHarness(url) {
+    try {
+        setState("loading", "Loading spec…");
+        await loadSpec(url);
+
+        setState("embedding", "Embedding visualization…");
+        const api = await embed(frameElement, url, {
+            onError(error) {
+                throw error;
+            },
+        });
+
+        if (
+            typeof api.getLogicalCanvasSize !== "function" ||
+            typeof api.getRenderedBounds !== "function" ||
+            typeof api.awaitVisibleLazyData !== "function"
+        ) {
+            throw new Error(
+                "Embed did not return a usable GenomeSpy instance."
+            );
+        }
+
+        setState("waitingForData", "Waiting for visible lazy data…");
+        await waitForVisibleLazyData(api, lazyReadyTimeoutMs);
+
+        setState("rendering", "Waiting for initial render…");
+        await waitForSettledRender();
+
+        const logicalSize = resolveExportSize(
+            api.getRenderedBounds(),
+            api.getLogicalCanvasSize()
+        );
+
+        screenshotWindow.__genomeSpyScreenshot = {
+            status: "ready",
+            detail: `Ready (${logicalSize.width}x${logicalSize.height}, DPR 1)`,
+            error: "",
+            async capture() {
+                const currentSize = resolveExportSize(
+                    api.getRenderedBounds(),
+                    api.getLogicalCanvasSize()
+                );
+                return {
+                    logicalSize: currentSize,
+                    dataUrl: api.exportCanvas(
+                        currentSize.width,
+                        currentSize.height,
+                        1,
+                        "white"
+                    ),
+                };
+            },
+        };
+
+        setStatus(`Ready (${logicalSize.width}x${logicalSize.height}, DPR 1)`);
+    } catch (error) {
+        setFailure(error instanceof Error ? error.message : String(error));
+    }
+}
+
+async function waitForSettledRender() {
+    await waitForAnimationFrame();
+    await waitForAnimationFrame();
+    await wait(READY_DELAY_MS);
+}
+
+/**
+ * @param {{
+ *   awaitVisibleLazyData: (signal?: AbortSignal) => Promise<void>
+ * }} api
+ * @param {number} timeoutMs
+ */
+async function waitForVisibleLazyData(api, timeoutMs) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const timeoutId = window.setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+
+    try {
+        await api.awaitVisibleLazyData(controller.signal);
+    } catch (error) {
+        if (timedOut) {
+            throw new Error(
+                `Timed out after ${timeoutMs} ms while waiting for visible lazy data.`,
+                { cause: error }
+            );
+        }
+
+        throw error;
+    } finally {
+        window.clearTimeout(timeoutId);
+    }
+}
+
+function waitForAnimationFrame() {
+    return new Promise((resolve) => requestAnimationFrame(() => resolve()));
+}
+
+/**
+ * @param {number} milliseconds
+ */
+function wait(milliseconds) {
+    return new Promise((resolve) => window.setTimeout(resolve, milliseconds));
+}
+
+/**
+ * @param {string | null} value
+ * @param {number} fallback
+ */
+function parseTimeoutMs(value, fallback) {
+    if (value == null) {
+        return fallback;
+    }
+
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(
+            `Invalid lazy-data timeout value: ${value}. Expected a positive number.`
+        );
+    }
+
+    return parsed;
+}
+
+/**
+ * @param {{ width: number | undefined, height: number | undefined }} renderedBounds
+ * @param {{ width: number, height: number }} logicalSize
+ */
+function resolveExportSize(renderedBounds, logicalSize) {
+    return {
+        width:
+            Number.isFinite(renderedBounds.width) && renderedBounds.width > 0
+                ? Math.ceil(renderedBounds.width)
+                : Number.isFinite(logicalSize.width) && logicalSize.width > 0
+                  ? logicalSize.width
+                  : DEFAULT_CONTAINER_WIDTH,
+        height:
+            Number.isFinite(renderedBounds.height) && renderedBounds.height > 0
+                ? Math.ceil(renderedBounds.height)
+                : Number.isFinite(logicalSize.height) && logicalSize.height > 0
+                  ? logicalSize.height
+                  : DEFAULT_CONTAINER_HEIGHT,
+    };
+}
+
+/**
+ * @param {string} message
+ */
+function setStatus(message) {
+    statusElement.textContent = message;
+}
+
+/**
+ * @param {string} status
+ * @param {string} detail
+ */
+function setState(status, detail) {
+    screenshotWindow.__genomeSpyScreenshot = {
+        ...screenshotWindow.__genomeSpyScreenshot,
+        status,
+        detail,
+    };
+    setStatus(detail);
+}
+
+/**
+ * @param {string} message
+ */
+function setFailure(message) {
+    screenshotWindow.__genomeSpyScreenshot = {
+        status: "error",
+        detail: message,
+        error: message,
+        async capture() {
+            throw new Error(message);
+        },
+    };
+    statusElement.textContent = message;
+    statusElement.style.color = "#a03018";
+}

package/dist/src/singlePageApp.js

@@ -9,5 +9,5 @@ if (specUrl) {
     document.body.innerHTML = `
         <p style="color: firebrick">No 'spec' url parameter defined!</p>
         <p>Try this one from the "static" folder, for example:
-        <a href="?spec=examples/first.json">examples/first.json</a></p>`;
+        <a href="?spec=examples/core/first.json">examples/core/first.json</a></p>`;
 }

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

@@ -1,4 +1,5 @@
 import { Align, Baseline, FontStyle, FontWeight } from "./font.js";
+import { ZIndexProps } from "./decoration.js";
 
 export interface GenomeAxis extends Axis {
     chromTicks?: boolean;
@@ -91,7 +92,13 @@ export interface GenomeAxis extends Axis {
 
 export type AxisOrient = "top" | "bottom" | "left" | "right";
 
-export interface Axis extends BaseAxis {
+export interface Axis extends BaseAxis, ZIndexProps {
+    /**
+     * Named style reference(s) resolved from `config.style`.
+     * If an array is provided, later styles override earlier ones.
+     */
+    style?: string | string[];
+
     /**
      * 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).
      *
@@ -131,68 +138,72 @@ export interface Axis extends BaseAxis {
      * Explicitly set the visible axis tick and label values.
      */
     values?: any[];
+
+    /**
+     * Z-order of the axis relative to the view content.
+     *
+     * Values greater than `0` render after the view marks. Values less than or
+     * equal to `0` render before the marks.
+     *
+     * __Default value:__ `0`, or `10` when the view content is clipped or
+     * scrollable.
+     */
+    zindex?: number;
 }
 
-export interface BaseAxis<
-    N = number,
-    B = boolean,
-    S = string,
-    C = string,
-    FW = string,
-    FS = string,
-> {
+export interface BaseAxis {
     /**
      * The minimum extent in pixels that axis ticks and labels should use. This determines a minimum offset value for axis titles.
      *
      * __Default value:__ `30` for y-axis; `undefined` for x-axis.
      */
-    minExtent?: N;
+    minExtent?: number;
 
     /**
      * The maximum extent in pixels that axis ticks and labels should use. This determines a maximum offset value for axis titles.
      *
      * __Default value:__ `undefined`.
      */
-    maxExtent?: N;
+    maxExtent?: number;
 
     // ---------- Title ----------
     /**
      * The padding, in pixels, between title and axis.
      */
-    titlePadding?: N;
+    titlePadding?: number;
 
     /**
      * Color of the title, can be in hex color code or regular color name.
      */
-    titleColor?: C;
+    titleColor?: string;
 
     /**
      * Font of the title. (e.g., `"Helvetica Neue"`).
      */
-    titleFont?: S;
+    titleFont?: string;
 
     /**
      * Font size of the title.
      *
      * @minimum 0
      */
-    titleFontSize?: N;
+    titleFontSize?: number;
 
     /**
      * Font style of the title.
      */
-    titleFontStyle?: FS;
+    titleFontStyle?: FontStyle;
 
     /**
      * Font weight of the title.
      * This can be either a string (e.g `"bold"`, `"normal"`) or a number (`100`, `200`, `300`, ..., `900` where `"normal"` = `400` and `"bold"` = `700`).
      */
-    titleFontWeight?: FW;
+    titleFontWeight?: FontWeight;
 
     /**
      * Opacity of the axis title.
      */
-    titleOpacity?: N;
+    titleOpacity?: number;
 
     // ---------- Domain ----------
     /**
@@ -224,14 +235,14 @@ export interface BaseAxis<
      *
      * __Default value:__ `"gray"`.
      */
-    domainColor?: C;
+    domainColor?: string;
 
     /**
      * Stroke width of axis domain line
      *
      * __Default value:__ `1`
      */
-    domainWidth?: N;
+    domainWidth?: number;
 
     // ---------- Ticks ----------
     /**
@@ -239,7 +250,7 @@ export interface BaseAxis<
      *
      * __Default value:__ `true`
      */
-    ticks?: B;
+    ticks?: boolean;
 
     /**
      * The stroke cap for the tick lines' ending style. One of `"butt"`, `"round"` or `"square"`.
@@ -253,7 +264,7 @@ export interface BaseAxis<
      *
      * __Default value:__ `"gray"`
      */
-    tickColor?: C;
+    tickColor?: string;
 
     /**
      * An array of alternating [stroke, space] lengths for dashed tick mark lines.
@@ -271,7 +282,7 @@ export interface BaseAxis<
      * __Default value:__ `5`
      * @minimum 0
      */
-    tickSize?: N;
+    tickSize?: number;
 
     /**
      * The width, in pixels, of ticks.
@@ -279,7 +290,7 @@ export interface BaseAxis<
      * __Default value:__ `1`
      * @minimum 0
      */
-    tickWidth?: N;
+    tickWidth?: number;
 
     // ---------- Labels ----------
     /**
@@ -313,36 +324,36 @@ export interface BaseAxis<
     /**
      * The color of the tick label, can be in hex color code or regular color name.
      */
-    labelColor?: C;
+    labelColor?: string;
 
     /**
      * The font of the tick label.
      */
-    labelFont?: S;
+    labelFont?: string;
 
     /**
      * The font size of the label, in pixels.
      *
      * @minimum 0
      */
-    labelFontSize?: N;
+    labelFontSize?: number;
 
     /**
      * Font style of the title.
      */
-    labelFontStyle?: FS;
+    labelFontStyle?: FontStyle;
 
     /**
      * Font weight of axis tick labels.
      */
-    labelFontWeight?: FW;
+    labelFontWeight?: FontWeight;
 
     /**
      * Maximum allowed pixel width of axis tick labels.
      *
      * __Default value:__ `180`
      */
-    labelLimit?: N;
+    labelLimit?: number;
 
     /**
      * The padding, in pixels, between axis and text labels.

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

@@ -268,15 +268,17 @@ export type FieldOrDatumDefWithCondition<
 /**
  * @minProperties 1
  */
-export type ValueDefWithCondition<V extends Value = Value> = Partial<
-    ValueDef<V | ExprRef>
-> & {
+export type ValueDefWithCondition<
+    V extends Value = Value,
+    T extends Type = Type,
+> = Partial<ValueDef<V | ExprRef>> & {
     /**
      * A field definition or one or more value definition(s) with a parameter predicate.
      */
     condition?:
-        | Conditional<FieldDef>
-        | Conditional<DatumDef>
+        | Conditional<MarkPropFieldDef<T>>
+        | Conditional<ScaleDatumDef>
+        | Conditional<MarkPropExprDef<T>>
         | Conditional<ValueDef<V | ExprRef>>
         | Conditional<ValueDef<V | ExprRef>>[];
 };
@@ -289,7 +291,7 @@ export type MarkPropFieldOrDatumOrExprDef<T extends Type = Type> =
 export type MarkPropDef<V extends Value, T extends Type = Type> =
     | FieldOrDatumDefWithCondition<MarkPropFieldDef<T>, V>
     | FieldOrDatumDefWithCondition<ScaleDatumDef, V>
-    | ValueDefWithCondition<V>;
+    | ValueDefWithCondition<V, T>;
 
 export type ColorDef = MarkPropDef<string | null>;
 
@@ -381,9 +383,13 @@ export type NumericMarkPropDef = MarkPropDef<number>;
 
 export type ShapeDef = MarkPropDef<string | null, TypeForShape>;
 
-export interface StringFieldDef extends FieldDefWithoutScale, FormatMixins {}
+export type StringFieldDef = FieldDef<Type> & FormatMixins;
 
-export type TextDef = StringFieldDef | StringDatumDef | ExprDef; // TODO: Conditions
+export type TextDef =
+    | StringFieldDef
+    | StringDatumDef
+    | ExprDef
+    | ValueDef<string>; // TODO: Conditions
 
 export type ChannelDef = Exclude<
     Encoding[keyof Encoding],
@@ -549,5 +555,5 @@ export interface Encoding {
     // TODO: proper type
     facetIndex?: FieldDefWithoutScale;
 
-    semanticScore?: FieldDefWithoutScale;
+    semanticScore?: FieldDefWithoutScale & Partial<TypeMixins<Type>>;
 }