@genome-spy/app 0.76.0 → 0.78.0

package/package.json

@@ -8,7 +8,7 @@
   "contributors": [],
   "license": "MIT",
   "homepage": "https://genomespy.app/",
-  "version": "0.76.0",
+  "version": "0.78.0",
   "main": "dist/index.js",
   "module": "dist/index.es.js",
   "type": "module",
@@ -70,7 +70,7 @@
     "@fortawesome/fontawesome-free": "^6.4.2",
     "@fortawesome/fontawesome-svg-core": "^6.4.2",
     "@fortawesome/free-solid-svg-icons": "^6.4.2",
-    "@genome-spy/core": "^0.76.0",
+    "@genome-spy/core": "^0.78.0",
     "@reduxjs/toolkit": "^2.11.0",
     "d3-color": "^3.1.0",
     "idb": "^7.1.1",
@@ -82,7 +82,7 @@
     "zarrita": "^0.6.1"
   },
   "devDependencies": {
-    "@genome-spy/app-agent": "^0.76.0"
+    "@genome-spy/app-agent": "^0.78.0"
   },
-  "gitHead": "34d821cf5e864972afaa65a3290719e2fdb209c2"
+  "gitHead": "54041db3a590ae8df78fa43aa755b9e07fe3503c"
 }

package/src/agentApi/index.d.ts

@@ -23,12 +23,36 @@ import type {
 } from "../charts/sampleAttributePlotTypes.d.ts";
 import type { ScaleResolutionApi } from "@genome-spy/core/types/scaleResolutionApi.js";
 import type UnitView from "@genome-spy/core/view/unitView.js";
+
+export interface AgentMetadataSourceIdentifierSummary {
+    name: string;
+    primary?: boolean;
+    caseInsensitive?: boolean;
+    stripVersionSuffix?: boolean;
+    examples: string[];
+}
+
+export interface AgentMetadataSourceSummary {
+    sourceId?: string;
+    name?: string;
+    description?: string;
+    attributeDefaults?: {
+        dataType?: string;
+        description?: string;
+    };
+    identifiers: AgentMetadataSourceIdentifierSummary[];
+}
+
 export interface AgentApi {
     /**
      * Returns the current sample hierarchy used by the agent context.
      */
     getSampleHierarchy(): SampleHierarchy | undefined;
 
+    getMetadataSourceSummaries(
+        signal?: AbortSignal
+    ): Promise<AgentMetadataSourceSummary[]>;
+
     getAttributeInfo(attribute: AttributeIdentifier): AttributeInfo | undefined;
 
     /**

package/src/bookmark/databaseSchema.d.ts

@@ -2,10 +2,15 @@ import { DBSchema } from "idb";
 import { ChromosomalLocus } from "@genome-spy/core/genome/genome.js";
 import { ViewSettingsPayload } from "../state.js";
 import { Action } from "../state/provenance.js";
+import { SampleAttributePlotDefinition } from "../charts/sampleAttributePlotTypes.js";
+
+export interface BookmarkPlotAttachment {
+    kind: "sample_attribute_plot";
+    definition: SampleAttributePlotDefinition;
+}
 
 export interface BookmarkEntry {
     name: string;
-    timestamp?: number;
 
     notes?: string;
 
@@ -23,6 +28,11 @@ export interface BookmarkEntry {
      * Settings such as view visibilities
      */
     viewSettings?: ViewSettingsPayload;
+
+    /**
+     * Plots attached to the bookmark.
+     */
+    plots?: BookmarkPlotAttachment[];
 }
 
 export interface BookmarkDB extends DBSchema {

package/src/charts/sampleAttributePlotTypes.d.ts

@@ -100,6 +100,7 @@ export type SampleAttributePlotCharacterization =
 export interface SampleAttributePlot {
     kind: "sample_attribute_plot";
     plotType: SampleAttributePlotType;
+    request: SampleAttributePlotDefinition;
     title: string;
     spec: RootSpec;
     namedData: RenderablePlotNamedData[];
@@ -129,9 +130,13 @@ export interface HierarchyScatterplotRequest {
     colorScaleRange?: string[];
 }
 
+/**
+ * User/API-facing plot request. This accepts convenience aliases and label
+ * hints that may be useful while resolving a plot, but are not persisted.
+ */
 export type SampleAttributePlotRequest =
     | {
-          plotType: "bar";
+          plotType: "bar" | "barplot";
           attribute: AttributeIdentifier;
           attributeLabel?: string;
       }
@@ -147,3 +152,23 @@ export type SampleAttributePlotRequest =
           xAttributeLabel?: string;
           yAttributeLabel?: string;
       };
+
+/**
+ * Normalized plot definition that is safe to persist in generated plots and
+ * bookmarks. It uses canonical plot type names and stores only stable attribute
+ * identifiers.
+ */
+export type SampleAttributePlotDefinition =
+    | {
+          plotType: "barplot";
+          attribute: AttributeIdentifier;
+      }
+    | {
+          plotType: "boxplot";
+          attribute: AttributeIdentifier;
+      }
+    | {
+          plotType: "scatterplot";
+          xAttribute: AttributeIdentifier;
+          yAttribute: AttributeIdentifier;
+      };

package/src/sampleView/sampleViewTypes.d.ts

@@ -6,6 +6,7 @@ import { Scalar } from "@genome-spy/core/spec/channel.js";
 import { ComplexDomain, NumericDomain } from "@genome-spy/core/spec/scale.js";
 import { AggregationSpec, Interval } from "./types.js";
 import ViewContext from "@genome-spy/core/types/viewContext.js";
+import { SampleLayoutDef } from "@genome-spy/app/spec/sampleView.js";
 import type {
     ParamSelector,
     ViewSelector,
@@ -54,6 +55,7 @@ export interface LocationContext {
     onLocationUpdate: (arg: { sampleHeight: number }) => void;
     viewContext: ViewContext;
     isStickySummaries: () => boolean;
+    sampleLayout?: SampleLayoutDef;
 }
 
 export interface BaseSpecifier {

package/src/sampleView/state/payloadTypes.d.ts

@@ -329,6 +329,90 @@ export interface RemoveGroup {
     path: string[];
 }
 
+export interface RetainGroupsByRank {
+    /**
+     * One-based grouping level to filter.
+     *
+     * `1` targets top-level groups under ROOT. `2` targets direct children of
+     * level-1 groups, and so on. For top-level categories such as cancer type,
+     * use `1`.
+     *
+     * @minimum 1
+     */
+    level: number;
+
+    /**
+     * Group-level measure used for ranking.
+     *
+     * Only `"size"` is supported. Size means group abundance: the number of
+     * descendant visible samples in the group.
+     */
+    measure: "size";
+
+    /**
+     * Number of ranked groups to retain within each ancestor partition.
+     *
+     * This is k in top-k or bottom-k requests. For example, use `5` to keep
+     * the five largest or five smallest groups.
+     *
+     * @minimum 1
+     */
+    limit: number;
+
+    /**
+     * Ranking direction.
+     *
+     * Use `"descending"` for top-k, highest values, largest groups by size, or
+     * most abundant groups. Use `"ascending"` for bottom-k, lowest values,
+     * smallest groups by size, or least abundant groups.
+     */
+    order: "descending" | "ascending";
+}
+
+export interface RetainGroupsBySize {
+    /**
+     * One-based grouping level to filter.
+     *
+     * `1` targets top-level groups under ROOT. `2` targets direct children of
+     * level-1 groups, and so on. For top-level categories such as cancer type,
+     * use `1`.
+     *
+     * @minimum 1
+     */
+    level: number;
+
+    /**
+     * Group-level measure used for thresholding.
+     *
+     * Only `"size"` is supported. Size means group abundance: the number of
+     * descendant visible samples in the group.
+     */
+    measure: "size";
+
+    /**
+     * Threshold comparison applied as `measure operator operand`.
+     */
+    operator: ComparisonOperatorType;
+
+    /**
+     * Numeric group-size threshold.
+     */
+    operand: number;
+}
+
+export interface Ungroup {
+    /**
+     * One-based grouping level to collapse.
+     *
+     * `1` collapses top-level groups under ROOT and all deeper levels into one
+     * flat ROOT sample group. `2` keeps level-1 groups but collapses their
+     * children and all deeper levels into sample lists.
+     *
+     * @minimum 1
+     */
+    level: number;
+}
+
 /**
  * Payload for filtering samples by comparing a quantitative attribute
  * against a numeric operand.

package/src/sampleView/types.d.ts

@@ -82,6 +82,9 @@ export interface AttributeInfo {
     /** More detailed name with optional formatting */
     title: string | import("lit").TemplateResult;
 
+    /** Plain short label for compact contexts and summaries. */
+    shortTitle?: string;
+
     /** Formatted attribute name for context menus (e.g., with selective emphasis). */
     emphasizedName: string | import("lit").TemplateResult;
 

package/src/spec/sampleView.d.ts

@@ -32,6 +32,11 @@ export interface SampleSpec extends Omit<ViewSpecBase, "templates"> {
      */
     metadata?: MetadataDef;
 
+    /**
+     * Layout settings for sample rows and sample groups.
+     */
+    sampleLayout?: SampleLayoutDef;
+
     /**
      * An object defining the view background and outline. The background is
      * repeated for each group.
@@ -90,6 +95,16 @@ export interface SampleAttributeDef {
      */
     barScale?: Scale;
 
+    /**
+     * Color used for metadata cells whose value is missing.
+     *
+     * If `null`, no background is drawn for missing values in this attribute.
+     * If omitted, `metadata.missingValueColor` is used. If both are
+     * omitted, the default is `null` when `barScale` is configured and
+     * `"#f0f0f0"` otherwise.
+     */
+    missingValueColor?: string | null;
+
     /**
      * Width of the column in pixels.
      */
@@ -377,6 +392,16 @@ export interface MetadataDef {
      */
     attributeWidth?: number;
 
+    /**
+     * Default color for metadata cells whose value is missing.
+     *
+     * If `null`, missing-value colors are disabled unless overridden by an
+     * attribute definition.
+     *
+     * __Default value:__ `"#f0f0f0"`
+     */
+    missingValueColor?: string | null;
+
     /**
      * Spacing between metadata columns in pixels.
      *
@@ -485,3 +510,36 @@ export interface SampleDef {
      */
     labelAlign?: Align;
 }
+
+export interface SampleLayoutDef {
+    /**
+     * Height of one sample row when the view is expanded for (close-up) inspection.
+     * In the birdseye overview, sample rows are automatically scaled to fit the available vertical space.
+     *
+     * __Default value:__ `35`
+     */
+    sampleHeight?: number;
+
+    /**
+     * Spacing between sample groups in the fitted layout.
+     *
+     * __Default value:__ `5`
+     */
+    groupSpacing?: number;
+
+    /**
+     * Spacing between sample groups in the expanded layout.
+     *
+     * __Default value:__ `15`
+     */
+    peekGroupSpacing?: number;
+
+    /**
+     * Fraction of each sample row reserved as spacing between rendered sample contents.
+     *
+     * Spacing is reduced when rows are too short to render cleanly.
+     *
+     * __Default value:__ `0.2`
+     */
+    sampleSpacingFactor?: number;
+}