@genome-spy/app 0.74.0 → 0.76.0

package/dist/{zstd-C6ksIG9r.js → zstd-BAfRM3IH.js}

@@ -1,4 +1,4 @@
-import { t as e } from "./chunk-INHXZS53-fPMmEwMt.js";
+import { t as e } from "./chunk-INHXZS53-DwEV9sMh.js";
 //#region ../../node_modules/numcodecs/dist/zstd.js
 var t = (typeof document < "u" && document.currentScript?.src, function(e = {}) {
 	var t, n = e, r, i, a = new Promise((e, t) => {

package/package.json

@@ -8,24 +8,46 @@
   "contributors": [],
   "license": "MIT",
   "homepage": "https://genomespy.app/",
-  "version": "0.74.0",
+  "version": "0.76.0",
   "main": "dist/index.js",
   "module": "dist/index.es.js",
   "type": "module",
+  "types": "src/index.d.ts",
   "exports": {
     ".": {
+      "types": "./src/index.d.ts",
+      "development": "./src/index.js",
       "import": "./dist/index.es.js",
       "default": "./dist/index.js"
     },
+    "./agentApi": {
+      "types": "./src/agentApi/index.d.ts",
+      "development": "./src/agentApi/index.js",
+      "import": "./dist/agentApi.es.js",
+      "default": "./dist/agentApi.es.js"
+    },
+    "./agentShared": {
+      "types": "./src/agentShared/index.d.ts",
+      "development": "./src/agentShared/index.js",
+      "import": "./dist/agentShared.es.js",
+      "default": "./dist/agentShared.es.js"
+    },
     "./browser": {
       "import": "./dist/index.es.js",
       "default": "./dist/index.js"
     },
+    "./dialog": {
+      "types": "./src/dialog/index.d.ts",
+      "development": "./src/dialog/index.js",
+      "import": "./dist/dialog.es.js",
+      "default": "./dist/dialog.es.js"
+    },
     "./schema.json": "./dist/schema.json",
     "./style.css": "./dist/style.css"
   },
   "files": [
-    "dist/"
+    "dist/",
+    "src/**/*.d.ts"
   ],
   "repository": {
     "type": "git",
@@ -34,7 +56,7 @@
   },
   "scripts": {
     "dev": "node dev-server.mjs",
-    "build": "rm -rf dist && mkdir -p dist && vite build && npm run build:schema",
+    "build": "rm -rf dist && mkdir -p dist && vite build && vite build --config vite.agent-subpaths.config.js && npm run build:schema",
     "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:src": "tsc -p tsconfig.json --noEmit",
@@ -48,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.74.0",
+    "@genome-spy/core": "^0.76.0",
     "@reduxjs/toolkit": "^2.11.0",
     "d3-color": "^3.1.0",
     "idb": "^7.1.1",
@@ -59,5 +81,8 @@
     "redux-undo": "^1.0.1",
     "zarrita": "^0.6.1"
   },
-  "gitHead": "7648d8c8670e288486f20bd7fe73509c4844cd83"
+  "devDependencies": {
+    "@genome-spy/app-agent": "^0.76.0"
+  },
+  "gitHead": "34d821cf5e864972afaa65a3290719e2fdb209c2"
 }

package/src/agentApi/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * `agentApi` exposes App internals to the agent and plugin surfaces only.
+ * Do not add App code here that the rest of App should depend on.
+ *
+ * `AgentApi` is the centralized handle for host state, provenance, and view
+ * mutations that the extracted agent package may use.
+ */
+import type { Action } from "@reduxjs/toolkit";
+import type {
+    ActionInfo,
+    AttributeIdentifier,
+    AttributeInfo,
+    AppRootSpec,
+    AppState,
+    ProvenanceAction,
+    SampleHierarchy,
+    ViewSelector,
+} from "../agentShared/index.d.ts";
+import type {
+    SampleAttributePlot,
+    SampleAttributePlotRequest,
+    SampleAttributePlotType,
+} 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 AgentApi {
+    /**
+     * Returns the current sample hierarchy used by the agent context.
+     */
+    getSampleHierarchy(): SampleHierarchy | undefined;
+
+    getAttributeInfo(attribute: AttributeIdentifier): AttributeInfo | undefined;
+
+    /**
+     * Resolves live selection-backed intervals inside an attribute identifier to
+     * literal intervals for formatting and durable features.
+     */
+    materializeAttributeIdentifier(
+        attribute: AttributeIdentifier
+    ): AttributeIdentifier;
+
+    /**
+     * Returns the current SampleView-scoped param config.
+     *
+     * TODO(app): Make this unscoped and accept a `ParamSelector` once the
+     * agent boundary no longer needs the SampleView-local lookup.
+     */
+    getSampleViewScopedParamConfig(
+        paramName: string
+    ): { description?: string } | undefined;
+
+    getSearchableViews(): UnitView[];
+
+    getViewRoot(): import("@genome-spy/core/view/view.js").default | undefined;
+
+    /**
+     * Returns the current focus view for tree normalization and expansion.
+     * This is typically the current sample view.
+     */
+    getFocusedView():
+        | import("@genome-spy/core/view/view.js").default
+        | undefined;
+
+    /**
+     * Returns the root spec used to summarize the top-level visualization.
+     */
+    getRootSpec(): AppRootSpec;
+
+    getNamedScaleResolutions(): Map<string, ScaleResolutionApi>;
+
+    resolveViewSelector(
+        selector: ViewSelector
+    ): import("@genome-spy/core/view/view.js").default | undefined;
+
+    getSelectionFeatureFieldValues(
+        viewSelector: ViewSelector,
+        selectionSelector: import("@genome-spy/core/view/viewSelectors.js").ParamSelector,
+        field: string
+    ): unknown[] | undefined;
+
+    /**
+     * Returns the provenance actions currently available to the agent.
+     */
+    getActionHistory(): ProvenanceAction[];
+
+    getActionInfo(action: Action): ActionInfo | undefined;
+
+    /**
+     * Submits a prepared set of actions to the app intent pipeline.
+     */
+    submitIntentActions(
+        actions: Action[],
+        options?: { submissionKind?: "agent" | "bookmark" | "user" }
+    ): Promise<void>;
+
+    /**
+     * Returns the current provenance state used by selection and timeline tools.
+     */
+    getPresentProvenanceState(): AppState["provenance"]["present"] | undefined;
+
+    buildSampleAttributePlot(
+        request: SampleAttributePlotRequest
+    ): Promise<SampleAttributePlot | undefined>;
+
+    setViewVisibility(selector: ViewSelector, visibility: boolean): void;
+
+    jumpToProvenanceState(provenanceId: string): boolean;
+
+    jumpToInitialProvenanceState(): boolean;
+}
+
+export type {
+    SampleAttributePlot,
+    SampleAttributePlotRequest,
+    SampleAttributePlotType,
+};
+
+export declare function embedRenderablePlot(
+    container: HTMLElement,
+    plot: SampleAttributePlot
+): Promise<import("@genome-spy/core/types/embedApi.js").EmbedResult>;
+
+export declare function createAgentApi(app: any): AgentApi;

package/src/agentShared/index.d.ts

@@ -0,0 +1,97 @@
+/**
+ * `agentShared` exposes App internals to the agent and plugin surfaces only.
+ * Do not add App code here that the rest of App should depend on.
+ *
+ * Shared helper surface for agent-facing utilities used by the App and the
+ * future extracted agent package.
+ *
+ * Host state and mutation access stays on `AgentApi`.
+ */
+export { makeViewSelectorKey } from "../viewSettingsUtils.js";
+export { formatScopedParamName } from "../viewScopeUtils.js";
+export { serializeBookmarkableParamValue } from "../state/paramValueSerialization.js";
+export { isBaselineAction } from "../state/provenanceBaseline.js";
+export {
+    createSelectionAggregationCandidateId,
+    getContextMenuFieldInfos,
+} from "../sampleView/selectionAggregationCandidates.js";
+export { buildSelectionAggregationAttributeIdentifier } from "../sampleView/selectionAggregationAttributes.js";
+export { formatAggregationExpression } from "../sampleView/attributeAggregation/aggregationOps.js";
+export { default as templateResultToString } from "../utils/templateResultToString.js";
+export { faStyles, formStyles } from "../components/generic/componentStyles.js";
+export { default as safeMarkdown } from "../utils/safeMarkdown.js";
+export {
+    addValueColors,
+    getConcreteColorScale,
+} from "../utils/colorScaleSummary.js";
+export {
+    buildCategoricalCountsSummary,
+    buildCategoricalFieldSummary,
+    buildQuantitativeFieldSummary,
+    buildTopCategorySummary,
+} from "../utils/statistics/fieldSummary.js";
+export type { ParamSelector, ViewSelector } from "./types.d.ts";
+export type {
+    AggregationOp,
+    AttributeIdentifier,
+    AttributeIdentifierType,
+    AttributeInfo,
+    AttributeEnsureContext,
+    AttributeValuesScope,
+    AggregationSpec,
+    Interval,
+    IntervalPoint,
+} from "../sampleView/types.d.ts";
+export type { AppRootSpec } from "../spec/appSpec.d.ts";
+export type { ActionInfo, ProvenanceAction } from "../state/provenance.js";
+export type { AppState } from "../state/setupStore.js";
+export type {
+    BaseGroup,
+    Group,
+    GroupGroup,
+    GroupMetadata,
+    Metadatum,
+    Metadata,
+    Sample,
+    SampleGroup,
+    SampleHierarchy,
+    SampleId,
+    SampleMetadata,
+} from "../sampleView/state/sampleState.d.ts";
+export type {
+    ExpandPointSelectionActionPayload,
+    ParamOrigin,
+    ParamProvenanceEntry,
+    ParamProvenanceState,
+    ParamValue,
+    ParamValueInterval,
+    ParamValueLiteral,
+    ParamValuePoint,
+    ParamValuePointExpand,
+    PointExpandMatcher,
+    PointExpandOrigin,
+} from "../state/paramProvenanceTypes.d.ts";
+export type {
+    IntervalCarrier,
+    IntervalReference,
+    IntervalSpecifier,
+    LocusSpecifier,
+    FeatureFilter,
+    SelectionIntervalSource,
+    ViewAttributeSpecifier,
+    ViewRef,
+} from "../sampleView/sampleViewTypes.d.ts";
+export type * from "../sampleView/state/payloadTypes.d.ts";
+export type {
+    SampleAttributeDef,
+    SampleAttributeType,
+} from "../spec/sampleView.d.ts";
+
+type SupportedActionType =
+    | `sampleView/${import("../sampleView/state/sampleSlice.js").SampleActionType}`
+    | `paramProvenance/${keyof typeof import("../state/paramProvenanceSlice.js").paramProvenanceSlice.actions}`
+    | `viewSettings/${keyof typeof import("../viewSettingsSlice.js").viewSettingsSlice.actions}`;
+
+export declare function getActionCreator(
+    actionType: SupportedActionType
+): (payload: any) => import("@reduxjs/toolkit").PayloadAction<any>;

package/src/agentShared/types.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `agentShared` exposes App internals to the agent and plugin surfaces only.
+ * Do not add App code here that the rest of App should depend on.
+ */
+export type {
+    ParamSelector,
+    ViewSelector,
+} from "@genome-spy/core/view/viewUtilTypes.d.ts";

package/src/appTypes.d.ts

@@ -0,0 +1,75 @@
+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>;
+
+export type AppEmbedOptions =
+    import("@genome-spy/core/types/embedApi.js").EmbedOptions & {
+        showInspectorButton?: boolean;
+        plugins?: AppPlugin[];
+    };
+
+export interface ToolbarButtonSpec {
+    title: string;
+    icon: IconDefinition;
+    onClick: () => void | Promise<void>;
+}
+
+export interface AppUiHost {
+    registerToolbarButton(button: ToolbarButtonSpec): () => void;
+    registerToolbarMenuItem(
+        item: import("./utils/ui/contextMenu.js").MenuItem
+    ): () => void;
+    registerSidePanel?(panel: SidePanelSpec): SidePanelHandle;
+}
+
+export interface SidePanelSpec {
+    id: string;
+    element: HTMLElement;
+    preferredWidth?: string;
+}
+
+export interface SidePanelHandle {
+    show(): void;
+    hide(): void;
+    toggle(): boolean;
+    isVisible(): boolean;
+    dispose(): void;
+}
+
+export interface AppPluginHost {
+    readonly ui: AppUiHost;
+    getAgentApi(): Promise<import("./agentApi/index.js").AgentApi>;
+}
+
+export interface AppPlugin {
+    name?: string;
+    install(
+        host: AppPluginHost
+    ): void | (() => void) | Promise<void | (() => void)>;
+}
+
+export interface AppUiRegistry extends AppUiHost, EventTarget {
+    readonly toolbarButtons: Set<ToolbarButtonSpec>;
+    readonly toolbarMenuItems: Set<
+        import("./utils/ui/contextMenu.js").MenuItem
+    >;
+    attachAppShell(appShell: HTMLElement): void;
+    registerSidePanel(panel: SidePanelSpec): SidePanelHandle;
+}
+
+export type AppEmbedFunction = (
+    el: HTMLElement | string,
+    spec: import("./spec/appSpec.js").AppRootSpec | string,
+    options?: AppEmbedOptions
+) => EmbedResult;
+
+export interface DependencyQueryDetails {
+    /** Name of the queried dependency */
+    name: string;
+    /** Callback that will set the dependency. */
+    setter: (dependency: any) => void;
+}
+
+export type DependencyQueryEvent = CustomEvent<DependencyQueryDetails>;

package/src/bookmark/databaseSchema.d.ts

@@ -0,0 +1,33 @@
+import { DBSchema } from "idb";
+import { ChromosomalLocus } from "@genome-spy/core/genome/genome.js";
+import { ViewSettingsPayload } from "../state.js";
+import { Action } from "../state/provenance.js";
+
+export interface BookmarkEntry {
+    name: string;
+    timestamp?: number;
+
+    notes?: string;
+
+    /**
+     * Provenance
+     */
+    actions?: Action[];
+
+    /**
+     * Domains of scales that are both zoomable and named
+     */
+    scaleDomains?: Record<string, number[] | ChromosomalLocus[]>;
+
+    /**
+     * Settings such as view visibilities
+     */
+    viewSettings?: ViewSettingsPayload;
+}
+
+export interface BookmarkDB extends DBSchema {
+    bookmarks: {
+        value: BookmarkEntry;
+        key: string;
+    };
+}

package/src/charts/boxplotTypes.d.ts

@@ -0,0 +1,15 @@
+import { boxplotStats } from "../utils/statistics/boxplot.js";
+
+export type Scalar = import("@genome-spy/core/spec/channel.js").Scalar;
+
+export type BoxplotStatistics = NonNullable<
+    ReturnType<typeof boxplotStats>["statistics"]
+>;
+
+export type BoxplotStatsRow = BoxplotStatistics & Record<string, Scalar>;
+
+export type BoxplotOutlierRow = Record<string, any>;
+
+export type BoxplotFieldKey = "groupField" | "valueField" | "sampleField";
+
+export type BoxplotFieldNames = Record<BoxplotFieldKey, string>;

package/src/charts/sampleAttributePlotTypes.d.ts

@@ -0,0 +1,149 @@
+import type { RootSpec } from "@genome-spy/core/spec/root.js";
+import type { AttributeIdentifier } from "../sampleView/types.d.ts";
+import type { AttributeInfo } from "../sampleView/types.js";
+import type { SampleHierarchy } from "../sampleView/state/sampleState.js";
+import type CompositeAttributeInfoSource from "../sampleView/compositeAttributeInfoSource.js";
+
+export type SampleAttributePlotType = "barplot" | "boxplot" | "scatterplot";
+
+export interface RenderablePlotNamedData {
+    name: string;
+    rows: Record<string, any>[];
+}
+
+export interface SampleAttributePlotSummary {
+    groupCount: number;
+    sampleCount: number;
+    plottedCount: number;
+}
+
+export interface CategoryCountsPlotCharacterization {
+    kind: "category_counts";
+    encoding: {
+        x: {
+            role: "current_sample_groups" | "plotted_attribute";
+            title: string;
+        };
+        y: {
+            role: "count";
+            title: "count";
+        };
+        color?: {
+            role: "plotted_attribute";
+            title: string;
+        };
+    };
+    nonMissingCount: number;
+    missingCount: number;
+    distinctCount: number;
+    categories: Array<{
+        value: unknown;
+        count: number;
+        share: number;
+        color?: string;
+    }>;
+    groups?: Array<{
+        title: string;
+        sampleCount: number;
+        nonMissingCount: number;
+        missingCount: number;
+        topCategory?: { value: unknown; count: number; share: number };
+    }>;
+}
+
+export interface AttributeDistributionPlotCharacterization {
+    kind: "quantitative_distribution";
+    groups: Array<{
+        title: string;
+        sampleCount: number;
+        nonMissingCount: number;
+        missingCount: number;
+        min?: number;
+        q1?: number;
+        median?: number;
+        q3?: number;
+        max?: number;
+        iqr?: number;
+        outlierCount: number;
+    }>;
+    highestMedianGroup?: string;
+    lowestMedianGroup?: string;
+    largestMedianDifference?: number;
+}
+
+export interface AttributeRelationshipPlotCharacterization {
+    kind: "quantitative_relationship";
+    axisMapping: Array<{
+        axis: "x" | "y";
+        attributeIndex: number;
+        title: string;
+    }>;
+    missingPairCount: number;
+    x: { min?: number; max?: number };
+    y: { min?: number; max?: number };
+    correlation?: {
+        method: "pearson";
+        r: number;
+    };
+    groups?: Array<{
+        title: string;
+        plottedPointCount: number;
+        color?: string;
+    }>;
+}
+
+export type SampleAttributePlotCharacterization =
+    | CategoryCountsPlotCharacterization
+    | AttributeDistributionPlotCharacterization
+    | AttributeRelationshipPlotCharacterization;
+
+export interface SampleAttributePlot {
+    kind: "sample_attribute_plot";
+    plotType: SampleAttributePlotType;
+    title: string;
+    spec: RootSpec;
+    namedData: RenderablePlotNamedData[];
+    filename: string;
+    summary: SampleAttributePlotSummary;
+    characterization: SampleAttributePlotCharacterization;
+}
+
+export interface HierarchyBarplotRequest {
+    attributeInfo: AttributeInfo;
+    sampleHierarchy: SampleHierarchy;
+    attributeInfoSource: CompositeAttributeInfoSource;
+}
+
+export interface HierarchyBoxplotRequest {
+    attributeInfo: AttributeInfo;
+    sampleHierarchy: SampleHierarchy;
+    attributeInfoSource: CompositeAttributeInfoSource;
+}
+
+export interface HierarchyScatterplotRequest {
+    xAttributeInfo: AttributeInfo;
+    yAttributeInfo: AttributeInfo;
+    sampleHierarchy: SampleHierarchy;
+    attributeInfoSource: CompositeAttributeInfoSource;
+    colorScaleDomain?: string[];
+    colorScaleRange?: string[];
+}
+
+export type SampleAttributePlotRequest =
+    | {
+          plotType: "bar";
+          attribute: AttributeIdentifier;
+          attributeLabel?: string;
+      }
+    | {
+          plotType: "boxplot";
+          attribute: AttributeIdentifier;
+          attributeLabel?: string;
+      }
+    | {
+          plotType: "scatterplot";
+          xAttribute: AttributeIdentifier;
+          yAttribute: AttributeIdentifier;
+          xAttributeLabel?: string;
+          yAttributeLabel?: string;
+      };

package/src/coreSpecAugmentation.d.ts

@@ -0,0 +1,29 @@
+import { SampleSpec } from "@genome-spy/app/spec/sampleView.js";
+
+// App-specific compile-time augmentation for core spec types.
+// This file exists only to make app code type-compatible with core classes
+// that are typed against @genome-spy/core/spec/view.js.
+//
+// Important:
+// - This is not runtime behavior; declaration files do not emit JS.
+// - Core schema generation is isolated through CoreRootSpec, so these app-only
+//   extensions do not leak into @genome-spy/core/dist/schema.json.
+declare module "@genome-spy/core/spec/view.js" {
+    // App-only property. Required so aggregateSamples is accepted in app code
+    // that still references core UnitSpec / LayerSpec types.
+    interface UnitSpec {
+        aggregateSamples?: (UnitSpec | LayerSpec)[];
+    }
+
+    // Same as above for layer specs.
+    interface LayerSpec {
+        aggregateSamples?: (UnitSpec | LayerSpec)[];
+    }
+
+    // Hook declared by core. App attaches SampleSpec here so core ViewSpec /
+    // ContainerSpec are widened when app is type-checked.
+    // eslint-disable-next-line no-unused-vars
+    interface ViewSpecExtensions {
+        sample: SampleSpec;
+    }
+}

package/src/dialog/index.d.ts

@@ -0,0 +1,5 @@
+export {
+    default as BaseDialog,
+    showDialog,
+} from "../components/generic/baseDialog.js";
+export { showMessageDialog } from "../components/generic/messageDialog.js";

package/src/embedTypes.d.ts

@@ -0,0 +1,9 @@
+import { EmbedResult } from "@genome-spy/core/types/embedApi.js";
+
+export type AppEmbedOptions = import("./appTypes.js").AppEmbedOptions;
+
+export type AppEmbedFunction = (
+    el: HTMLElement | string,
+    spec: import("./spec/appSpec.js").AppRootSpec | string,
+    options?: AppEmbedOptions
+) => EmbedResult;

package/src/index.d.ts

@@ -0,0 +1,16 @@
+import type { AppEmbedFunction } from "./embedTypes.d.ts";
+
+export { GenomeSpy, GenomeSpyApp, icon, html } from "./index.js";
+export * from "./agentApi/index.js";
+export * from "./agentShared/index.js";
+export { BaseDialog, showDialog, showMessageDialog } from "./dialog/index.js";
+
+export declare const embed: AppEmbedFunction;
+export type * from "./appTypes.d.ts";
+export type * from "./sampleView/types.d.ts";
+export type * from "./sampleView/state/sampleState.d.ts";
+export type * from "./sampleView/state/payloadTypes.d.ts";
+export type {
+    SampleAttributeDef,
+    SampleAttributeType,
+} from "./spec/sampleView.d.ts";