@genome-spy/app 1.1.1 → 1.3.0

package/package.json

@@ -8,7 +8,7 @@
   "contributors": [],
   "license": "MIT",
   "homepage": "https://genomespy.app/",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "main": "dist/index.js",
   "module": "dist/index.es.js",
   "type": "module",
@@ -58,9 +58,10 @@
     "dev": "node dev-server.mjs",
     "build": "rm -rf dist && mkdir -p dist && vite build && vite build --config vite.agent-subpaths.config.js && npm run build:schema && node scripts/verifyProductionBundle.mjs",
     "build:schema": "mkdir -p dist && ts-json-schema-generator --path 'src/spec/*.d.ts' --type AppRootSpec > dist/schema.json",
-    "test:tsc": "npm run test:tsc:src && npm run test:tsc:tests",
+    "test:tsc": "npm run test:tsc:src && npm run test:tsc:tests && npm run test:tsc:public",
     "test:tsc:src": "tsc -p tsconfig.json --noEmit",
     "test:tsc:tests": "tsc -p tsconfig.tests.json --noEmit",
+    "test:tsc:public": "tsc -p tsconfig.public.json --noEmit",
     "smoke:examples:webgpu": "node ../core/scripts/runWebGpuExamples.mjs --scope app --all --compare-webgl",
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build"
@@ -70,7 +71,8 @@
     "@fortawesome/fontawesome-free": "^6.4.2",
     "@fortawesome/fontawesome-svg-core": "^6.4.2",
     "@fortawesome/free-solid-svg-icons": "^6.4.2",
-    "@genome-spy/core": "^1.1.1",
+    "@genome-spy/core": "^1.3.0",
+    "@genome-spy/figwig": "^0.3.0",
     "@reduxjs/toolkit": "^2.11.0",
     "d3-color": "^3.1.0",
     "idb": "^7.1.1",
@@ -83,7 +85,7 @@
     "zarrita": "^0.6.1"
   },
   "devDependencies": {
-    "@genome-spy/app-agent": "^1.1.1",
-    "@genome-spy/inspector": "^1.1.1"
+    "@genome-spy/app-agent": "^1.3.0",
+    "@genome-spy/inspector": "^1.3.0"
   }
 }

package/src/agentApi/index.d.ts

@@ -73,6 +73,8 @@ export interface AgentApi {
         paramName: string
     ): { description?: string } | undefined;
 
+    getDatumSearch(): import("@genome-spy/core/types/search.js").DatumSearch;
+    getViewApi(): import("@genome-spy/core/types/embedApi.js").ViewApi;
     getSearchableViews(): UnitView[];
 
     getViewRoot(): import("@genome-spy/core/view/view.js").default | undefined;
@@ -82,8 +84,7 @@ export interface AgentApi {
      * This is typically the current sample view.
      */
     getFocusedView():
-        | import("@genome-spy/core/view/view.js").default
-        | undefined;
+        import("@genome-spy/core/view/view.js").default | undefined;
 
     /**
      * Returns the root spec used to summarize the top-level visualization.

package/src/agentShared/index.d.ts

@@ -67,6 +67,8 @@ export type {
     ParamValueInterval,
     ParamValueLiteral,
     ParamValuePoint,
+    ParamValueRecordPoint,
+    ParamValueCategoryPoint,
     ParamValuePointExpand,
     PointExpandMatcher,
     PointExpandOrigin,

package/src/appTypes.d.ts

@@ -1,5 +1,4 @@
 import { BookmarkEntry } from "./bookmark/databaseSchema.js";
-import { EmbedResult } from "@genome-spy/core/types/embedApi.js";
 import type { IconDefinition } from "@fortawesome/fontawesome-svg-core";
 
 export type UrlHash = Partial<BookmarkEntry>;
@@ -70,11 +69,7 @@ export interface AppUiRegistry extends AppUiHost, EventTarget {
     registerSidePanel(panel: SidePanelSpec): SidePanelHandle;
 }
 
-export type AppEmbedFunction = (
-    el: HTMLElement | string,
-    spec: import("./spec/appSpec.js").AppRootSpec | string,
-    options?: AppEmbedOptions
-) => EmbedResult;
+export type AppEmbedFunction = import("./embedTypes.js").AppEmbedFunction;
 
 export interface DependencyQueryDetails {
     /** Name of the queried dependency */

package/src/embedTypes.d.ts

@@ -1,4 +1,39 @@
 import { EmbedResult } from "@genome-spy/core/types/embedApi.js";
+import type {
+    ViewApi,
+    ViewAddress,
+    ViewHandle,
+    InsertViewOptions,
+} from "@genome-spy/core/types/embedApi.js";
+import type { AppViewSpec } from "./spec/view.js";
+import type { ImportSpec } from "@genome-spy/core/spec/view.js";
+
+/** View mutations available in GenomeSpy App, including SampleSpec insertion. */
+export interface AppViewApi extends Omit<ViewApi, "insert" | "transaction"> {
+    insert(
+        parent: ViewAddress,
+        spec: AppViewSpec | ImportSpec,
+        options?: InsertViewOptions
+    ): Promise<ViewHandle>;
+    transaction<T>(callback: (views: AppViewApi) => T | Promise<T>): Promise<T>;
+}
+
+export interface AppEmbedResult extends Omit<EmbedResult, "views"> {
+    views: AppViewApi;
+    /** Switch bookmark identity/configuration without replacing the App or cohort. */
+    setPersistenceContext(context: AppPersistenceContext | null): Promise<void>;
+}
+
+/** Source bookmark configuration; dynamic changes do not start a bookmark tour. */
+export interface AppPersistenceContext {
+    specId?: string;
+    baseUrl?: string;
+    /** Absolute URL, or a relative URL accompanied by baseUrl. */
+    remoteBookmarks?: Pick<
+        import("./spec/appSpec.js").RemoteBookmarkConfig,
+        "url"
+    >;
+}
 
 export type AppEmbedOptions = import("./appTypes.js").AppEmbedOptions;
 
@@ -6,4 +41,4 @@ export type AppEmbedFunction = (
     el: HTMLElement | string,
     spec: import("./spec/appSpec.js").AppRootSpec | string,
     options?: AppEmbedOptions
-) => Promise<EmbedResult>;
+) => Promise<AppEmbedResult>;

package/src/index.d.ts

@@ -6,6 +6,11 @@ export * from "./agentShared/index.js";
 export { BaseDialog, showDialog, showMessageDialog } from "./dialog/index.js";
 
 export declare const embed: AppEmbedFunction;
+export type {
+    AppViewApi,
+    AppEmbedResult,
+    AppPersistenceContext,
+} from "./embedTypes.d.ts";
 export type * from "./appTypes.d.ts";
 export type * from "./sampleView/types.d.ts";
 export type * from "./sampleView/state/sampleState.d.ts";
@@ -13,4 +18,5 @@ export type * from "./sampleView/state/payloadTypes.d.ts";
 export type {
     SampleAttributeDef,
     SampleAttributeType,
+    SampleSpec,
 } from "./spec/sampleView.d.ts";

package/src/spec/sampleView.d.ts

@@ -2,7 +2,12 @@ import { Data, InlineData, UrlData } from "@genome-spy/core/spec/data.js";
 import { Align, FontStyle, FontWeight } from "@genome-spy/core/spec/font.js";
 import { Scale } from "@genome-spy/core/spec/scale.js";
 import { Title } from "@genome-spy/core/spec/title.js";
-import { ViewSpecBase, ViewBackground } from "@genome-spy/core/spec/view.js";
+import { ExprRef } from "@genome-spy/core/spec/parameter.js";
+import {
+    ViewSpecBase,
+    ViewBackground,
+    SizeDef,
+} from "@genome-spy/core/spec/view.js";
 import {
     AppConfigurableVisibilitySpec,
     AppLayerSpec,
@@ -13,7 +18,16 @@ import {
 /**
  * A view specification for a SampleView.
  */
-export interface SampleSpec extends Omit<ViewSpecBase, "templates"> {
+export interface SampleSpec extends Omit<
+    ViewSpecBase,
+    "templates" | "viewportWidth" | "viewportHeight"
+> {
+    /** Visible width. Sample views do not support viewport anchors. */
+    viewportWidth?: SizeDef | number | ExprRef | "container";
+
+    /** Visible height. Sample views do not support viewport anchors. */
+    viewportHeight?: SizeDef | number | ExprRef | "container";
+
     /**
      * Is the SampleView visibility configurable from the GenomeSpy App toolbar.
      *
@@ -95,11 +109,7 @@ export interface SampleYAxisDef {
 export type SampleAttributeType = "nominal" | "ordinal" | "quantitative";
 
 export type SampleAttributeSemanticType =
-    | "subjectId"
-    | "modelSystemId"
-    | "timeToEvent"
-    | "eventStatus"
-    | "category";
+    "subjectId" | "modelSystemId" | "timeToEvent" | "eventStatus" | "category";
 
 export interface SampleAttributeDef {
     /**
@@ -155,7 +165,15 @@ export interface SampleAttributeDef {
     title?: string;
 }
 
-export interface SampleIdentityDef {
+/**
+ * The authoritative sample collection. Use `"metadata"` to select the sole
+ * metadata source, or reference a specific source with `metadataSource`.
+ * Explicit data remains available for a separate cohort or ordering.
+ */
+export type SampleIdentityDef =
+    DataSampleIdentityDef | MetadataSampleIdentityDef | "metadata";
+
+export interface DataSampleIdentityDef {
     /**
      * Data source that defines the sample set for the view.
      *
@@ -179,6 +197,26 @@ export interface SampleIdentityDef {
     displayNameField?: string;
 }
 
+export interface MetadataSampleIdentityDef {
+    /**
+     * Id of the configured metadata source that defines the sample set and
+     * ordering. Canonical sample ids come from that backend, independently of
+     * which metadata columns are imported. For Figwig, ids are track names.
+     *
+     * @minLength 1
+     */
+    metadataSource: string;
+
+    /**
+     * Field in the source containing user-visible sample labels. It may be
+     * excluded from displayed metadata columns. Missing labels fall back to ids.
+     * The backend must support reading the configured label field.
+     *
+     * If omitted, canonical sample ids are used.
+     */
+    displayNameField?: string;
+}
+
 export interface ColumnIdentifierField {
     /**
      * Name of the identifier field shown in UI and diagnostics.
@@ -231,6 +269,19 @@ export interface DataBackendDef {
     sampleIdField?: string;
 }
 
+export interface FigWigBackendDef {
+    backend: "figwig";
+
+    /**
+     * URL to a Figwig file containing per-track metadata. Track names must
+     * match the sample ids in the view. Custom track attributes become metadata
+     * columns. Reserved `name`, `dtype`, and `group` fields, and the App's
+     * canonical identifier field `sample`, are excluded.
+     * Only file metadata is read, without decoding genomic signal.
+     */
+    url: string;
+}
+
 export interface ZarrMatrixLayoutDef {
     /**
      * Path to matrix values, arranged as sample rows by metadata columns.
@@ -309,6 +360,7 @@ export interface ArrowBackendDef {
 
 export type MetadataBackendDef =
     | DataBackendDef
+    | FigWigBackendDef
     | ZarrBackendDef
     | ParquetBackendDef
     | ArrowBackendDef;
@@ -352,9 +404,9 @@ export interface MetadataSourceDef {
     /**
      * Column ids that must never be imported from this source.
      *
-     * The data backend always excludes its `sampleIdField` automatically, so
-     * this property is only needed for other helper columns such as display
-     * labels.
+     * The data backend excludes its `sampleIdField`, and the Figwig backend
+     * excludes reserved track fields and `sample` automatically. Use this
+     * property for other helper columns such as display labels.
      */
     excludeColumns?: string[];
 
@@ -405,8 +457,7 @@ export interface MetadataSourceImportDef {
 }
 
 export type MetadataSourceEntry =
-    | MetadataSourceDef
-    | { import: MetadataSourceImportDef };
+    MetadataSourceDef | { import: MetadataSourceImportDef };
 
 export interface MetadataDef {
     /**
@@ -501,6 +552,10 @@ export interface MetadataDef {
 export interface SampleDef {
     /**
      * Defines the sample ids and optional display names for the sample view.
+     * Use `"metadata"` for the sole metadata source, or
+     * `{"metadataSource": "source-id", "displayNameField": "label"}` to
+     * select a source and its labels. Identity is read even when that source's
+     * metadata columns have `initialLoad: false`.
      *
      * If omitted, sample ids are inferred from the `sample` channel in the view
      * data.

package/src/spec/view.d.ts

@@ -1,11 +1,15 @@
 import {
     ConcatSpec as CoreConcatSpec,
+    FacetSpec as CoreFacetSpec,
     HConcatSpec as CoreHConcatSpec,
     ImportSpec,
     LayerSpec as CoreLayerSpec,
     MultiscaleSpec as CoreMultiscaleSpec,
     UnitSpec as CoreUnitSpec,
     VConcatSpec as CoreVConcatSpec,
+    SurroundSpec as CoreSurroundSpec,
+    SurroundSideSpec as CoreSurroundSideSpec,
+    Side,
 } from "@genome-spy/core/spec/view.js";
 import { SampleSpec } from "./sampleView.js";
 
@@ -84,10 +88,7 @@ export type AppMultiscaleSpec = Omit<
         templates?: Record<string, AppNestedViewSpec>;
 
         multiscale: (
-            | AppLayerSpec
-            | AppUnitSpec
-            | AppMultiscaleSpec
-            | ImportSpec
+            AppLayerSpec | AppUnitSpec | AppMultiscaleSpec | ImportSpec
         )[];
     };
 
@@ -98,6 +99,13 @@ export type AppVConcatSpec = Omit<CoreVConcatSpec, "templates" | "vconcat"> &
         vconcat: (AppViewSpec | ImportSpec)[];
     };
 
+export type AppFacetSpec = Omit<CoreFacetSpec, "templates" | "spec"> &
+    AppConfigurableVisibilitySpec & {
+        templates?: Record<string, AppNestedViewSpec>;
+
+        spec: AppLayerSpec | AppUnitSpec | ImportSpec;
+    };
+
 export type AppHConcatSpec = Omit<CoreHConcatSpec, "templates" | "hconcat"> &
     AppConfigurableVisibilitySpec & {
         templates?: Record<string, AppNestedViewSpec>;
@@ -112,13 +120,44 @@ export type AppConcatSpec = Omit<CoreConcatSpec, "templates" | "concat"> &
         concat: (AppViewSpec | ImportSpec)[];
     };
 
+export type AppSurroundPlotSpec =
+    AppUnitSpec | AppLayerSpec | AppMultiscaleSpec | ImportSpec;
+
+export type AppSurroundSideSpec = Omit<
+    CoreSurroundSideSpec,
+    "templates" | "views"
+> &
+    AppConfigurableVisibilitySpec & {
+        templates?: Record<string, AppNestedViewSpec>;
+        views: (AppSurroundPlotSpec | AppSurroundSpec)[];
+    };
+
+export type AppSurroundSides = Partial<
+    Record<
+        Side,
+        AppSurroundSideSpec | (AppSurroundPlotSpec | AppSurroundSpec)[]
+    >
+>;
+
+export type AppSurroundSpec = Omit<
+    CoreSurroundSpec,
+    "templates" | "spec" | "surround"
+> &
+    AppConfigurableVisibilitySpec & {
+        templates?: Record<string, AppNestedViewSpec>;
+        spec: AppSurroundPlotSpec;
+        surround: AppSurroundSides;
+    };
+
 export type AppNestedViewSpec =
     | AppUnitSpec
     | AppLayerSpec
     | AppMultiscaleSpec
+    | AppFacetSpec
     | AppVConcatSpec
     | AppHConcatSpec
-    | AppConcatSpec;
+    | AppConcatSpec
+    | AppSurroundSpec;
 
 // App root may contain SampleSpec, but recursive descendants cannot.
 export type AppViewSpec = AppNestedViewSpec | SampleSpec;

package/src/state/paramProvenanceTypes.d.ts

@@ -1,5 +1,9 @@
 import type { Scalar } from "@genome-spy/core/spec/channel.js";
 import type { ChromosomalLocus } from "@genome-spy/core/spec/genome.js";
+import type {
+    CategorySelectionChannel,
+    GradientSelectionChannel,
+} from "@genome-spy/core/spec/parameter.js";
 import type {
     ParamSelector,
     ViewSelector,
@@ -41,15 +45,24 @@ export type ParamValueInterval = {
             "x" | "y",
             [number, number] | [ChromosomalLocus, ChromosomalLocus] | null
         >
-    >;
+    > &
+        Partial<
+            Record<
+                GradientSelectionChannel,
+                [number, number | "Infinity"] | null
+            >
+        >;
 };
 
-export type ParamValuePoint = {
+export type ParamValueRecordPoint = {
     /**
      * Point selection value.
      */
     type: "point";
 
+    /** Omitted by existing record bookmarks. */
+    membership?: "records";
+
     /**
      * Fields used to identify selected points.
      */
@@ -61,6 +74,16 @@ export type ParamValuePoint = {
     keys: Scalar[][];
 };
 
+/** Raw categorical membership, independent of source rows and scale domains. */
+export type ParamValueCategoryPoint = {
+    type: "point";
+    membership: "categories";
+    encodings: [CategorySelectionChannel];
+    values: [Scalar][];
+};
+
+export type ParamValuePoint = ParamValueRecordPoint | ParamValueCategoryPoint;
+
 /**
  * Origin of a param value derived from a datum or interval lookup.
  */

package/src/state.d.ts

@@ -1,55 +1,18 @@
 import { StateWithHistory } from "redux-undo";
 import { SampleHierarchy } from "./sampleView/state/sampleState.js";
-import {
-    ParamSelector,
-    ViewSelector,
-} from "@genome-spy/core/view/viewUtilTypes.d.ts";
-import { Scalar } from "@genome-spy/core/spec/channel.js";
-import { ChromosomalLocus } from "@genome-spy/core/spec/genome.js";
-
-export interface ParamValueLiteral {
-    type: "value";
-    value: any;
-}
-
-export interface ParamValueInterval {
-    type: "interval";
-    intervals: Partial<
-        Record<
-            "x" | "y",
-            [number, number] | [ChromosomalLocus, ChromosomalLocus] | null
-        >
-    >;
-}
-
-export interface ParamValuePoint {
-    type: "point";
-    keyFields: string[];
-    keys: Scalar[][];
-}
-
-export type ParamValue =
-    | ParamValueLiteral
-    | ParamValueInterval
-    | ParamValuePoint;
-
-export interface ParamOrigin {
-    type: "datum";
-    view: ViewSelector;
-    keyField: string;
-    key: Scalar;
-    intervalSources?: Record<string, { start?: string; end?: string }>;
-}
-
-export interface ParamProvenanceEntry {
-    selector: ParamSelector;
-    value: ParamValue;
-    origin?: ParamOrigin;
-}
-
-export interface ParamProvenanceState {
-    entries: Record<string, ParamProvenanceEntry>;
-}
+import type { ParamProvenanceState } from "./state/paramProvenanceTypes.d.ts";
+
+export type {
+    ParamValueLiteral,
+    ParamValueInterval,
+    ParamValuePoint,
+    ParamValueRecordPoint,
+    ParamValueCategoryPoint,
+    ParamValue,
+    ParamOrigin,
+    ParamProvenanceEntry,
+    ParamProvenanceState,
+} from "./state/paramProvenanceTypes.d.ts";
 
 export interface ViewSettings {
     /**
@@ -66,8 +29,7 @@ export interface ViewVisibilityEntry {
 }
 
 export type ViewVisibilityWire =
-    | ViewVisibilityEntry[]
-    | Record<string, boolean>;
+    ViewVisibilityEntry[] | Record<string, boolean>;
 
 export interface ViewSettingsPayload {
     visibilities?: ViewVisibilityWire;