@genome-spy/app 0.74.0 → 0.76.0

package/src/spec/view.d.ts

@@ -0,0 +1,124 @@
+import {
+    ConcatSpec as CoreConcatSpec,
+    HConcatSpec as CoreHConcatSpec,
+    ImportSpec,
+    LayerSpec as CoreLayerSpec,
+    MultiscaleSpec as CoreMultiscaleSpec,
+    UnitSpec as CoreUnitSpec,
+    VConcatSpec as CoreVConcatSpec,
+} from "@genome-spy/core/spec/view.js";
+import { SampleSpec } from "./sampleView.js";
+
+// App has two view unions:
+// - AppNestedViewSpec: legal in recursive positions (templates, children)
+// - AppViewSpec: root-level union that can additionally include SampleSpec
+//
+// This prevents nested SampleSpecs while still allowing a SampleSpec under
+// app-level concat roots.
+export type AggregatingSpec = AppUnitSpec | AppLayerSpec;
+
+export interface AggregateSamplesSpec {
+    /**
+     * Specifies views that [aggregate](https://genomespy.app/docs/sample-collections/visualizing/#aggregation)
+     * multiple samples within the GenomeSpy App.
+     */
+    aggregateSamples?: AggregatingSpec[];
+}
+
+/**
+ * App-only visibility setting exposed in the view visibility menu.
+ */
+export interface AppVisibilityGroupSpec {
+    /**
+     * Name of a mutually exclusive visibility group.
+     *
+     * Views with the same group name in the same import scope are controlled
+     * with radio buttons in the view visibility menu.
+     */
+    group: string;
+}
+
+/**
+ * App-only visibility setting exposed in the view visibility menu.
+ */
+export interface AppConfigurableVisibilitySpec {
+    /**
+     * Is the visibility configurable from the GenomeSpy App view visibility menu.
+     *
+     * Configurability requires an explicit view name that is unique in its import
+     * scope.
+     *
+     * Set to an object with `group` to make configurable views mutually
+     * exclusive in the menu (radio buttons) within the same import scope.
+     *
+     * __Default value:__ `false` for children of `layer`, `true` for others
+     */
+    configurableVisibility?: boolean | AppVisibilityGroupSpec;
+}
+
+export type AppUnitSpec = Omit<CoreUnitSpec, "aggregateSamples" | "templates"> &
+    AppConfigurableVisibilitySpec &
+    AggregateSamplesSpec & {
+        // Re-thread templates to the app union so nested views can use app-only
+        // fields (e.g. aggregateSamples), but still exclude nested SampleSpec.
+        templates?: Record<string, AppNestedViewSpec>;
+    };
+
+export type AppLayerSpec = Omit<
+    CoreLayerSpec,
+    "layer" | "aggregateSamples" | "templates"
+> &
+    AppConfigurableVisibilitySpec &
+    AggregateSamplesSpec & {
+        templates?: Record<string, AppNestedViewSpec>;
+
+        layer: (AppLayerSpec | AppUnitSpec | AppMultiscaleSpec | ImportSpec)[];
+    };
+
+export type AppMultiscaleSpec = Omit<
+    CoreMultiscaleSpec,
+    "multiscale" | "aggregateSamples" | "templates"
+> &
+    AppConfigurableVisibilitySpec &
+    AggregateSamplesSpec & {
+        templates?: Record<string, AppNestedViewSpec>;
+
+        multiscale: (
+            | AppLayerSpec
+            | AppUnitSpec
+            | AppMultiscaleSpec
+            | ImportSpec
+        )[];
+    };
+
+export type AppVConcatSpec = Omit<CoreVConcatSpec, "templates" | "vconcat"> &
+    AppConfigurableVisibilitySpec & {
+        templates?: Record<string, AppNestedViewSpec>;
+
+        vconcat: (AppViewSpec | ImportSpec)[];
+    };
+
+export type AppHConcatSpec = Omit<CoreHConcatSpec, "templates" | "hconcat"> &
+    AppConfigurableVisibilitySpec & {
+        templates?: Record<string, AppNestedViewSpec>;
+
+        hconcat: (AppViewSpec | ImportSpec)[];
+    };
+
+export type AppConcatSpec = Omit<CoreConcatSpec, "templates" | "concat"> &
+    AppConfigurableVisibilitySpec & {
+        templates?: Record<string, AppNestedViewSpec>;
+
+        concat: (AppViewSpec | ImportSpec)[];
+    };
+
+export type AppNestedViewSpec =
+    | AppUnitSpec
+    | AppLayerSpec
+    | AppMultiscaleSpec
+    | AppVConcatSpec
+    | AppHConcatSpec
+    | AppConcatSpec;
+
+// App root may contain SampleSpec, but recursive descendants cannot.
+export type AppViewSpec = AppNestedViewSpec | SampleSpec;

package/src/state/paramProvenanceTypes.d.ts

@@ -0,0 +1,215 @@
+import type { Scalar } from "@genome-spy/core/spec/channel.js";
+import type { ChromosomalLocus } from "@genome-spy/core/spec/genome.js";
+import type {
+    ParamSelector,
+    ViewSelector,
+} from "@genome-spy/core/view/viewUtilTypes.d.ts";
+import type {
+    SelectionExpansionPredicate,
+    SelectionExpansionRule,
+} from "./selectionExpansionTypes.d.ts";
+
+/**
+ * Shared type aliases for param provenance payloads.
+ *
+ * These types describe the bookmarkable selection state that can be replayed
+ * and surfaced to the agent.
+ */
+export type ParamValueLiteral = {
+    /**
+     * Literal param value.
+     */
+    type: "value";
+
+    /**
+     * Stored literal value.
+     */
+    value: any;
+};
+
+export type ParamValueInterval = {
+    /**
+     * Interval selection value.
+     */
+    type: "interval";
+
+    /**
+     * Interval endpoints keyed by encoding channel.
+     */
+    intervals: Partial<
+        Record<
+            "x" | "y",
+            [number, number] | [ChromosomalLocus, ChromosomalLocus] | null
+        >
+    >;
+};
+
+export type ParamValuePoint = {
+    /**
+     * Point selection value.
+     */
+    type: "point";
+
+    /**
+     * Fields used to identify selected points.
+     */
+    keyFields: string[];
+
+    /**
+     * Selected key tuples.
+     */
+    keys: Scalar[][];
+};
+
+/**
+ * Origin of a param value derived from a datum or interval lookup.
+ */
+export type ParamOrigin = {
+    /**
+     * Origin type.
+     */
+    type: "datum";
+
+    /**
+     * View that contributed the value.
+     */
+    view: ViewSelector;
+
+    /**
+     * Field that supplied the value.
+     */
+    keyField: string;
+
+    /**
+     * Scalar value captured from the source datum.
+     */
+    key: Scalar;
+
+    /**
+     * Optional interval sources used for replay and diagnostics.
+     */
+    intervalSources?: Record<string, { start?: string; end?: string }>;
+};
+
+/**
+ * Back-reference for point selection expansion.
+ */
+export type PointExpandOrigin = {
+    /**
+     * View that produced the point selection.
+     */
+    view: ViewSelector;
+
+    /**
+     * Selected tuple captured at expansion time.
+     */
+    keyTuple: Scalar[];
+
+    /**
+     * Legacy support: older bookmarks may include these.
+     * New payloads should omit them.
+     */
+    keyFields?: string[];
+
+    /**
+     * Legacy datum marker retained for old bookmarks.
+     */
+    type?: "datum";
+};
+
+/**
+ * Matcher used to expand a point selection either by rule or predicate.
+ */
+export type PointExpandMatcher =
+    | { rule: SelectionExpansionRule; predicate?: never }
+    | { predicate: SelectionExpansionPredicate; rule?: never };
+
+/**
+ * Expanded point selection value stored in provenance.
+ */
+export type ParamValuePointExpand = {
+    /**
+     * Expanded point-selection value.
+     */
+    type: "pointExpand";
+
+    /**
+     * Operation applied to the current selection.
+     */
+    operation: "replace" | "add" | "remove" | "toggle";
+
+    /**
+     * Optional partitioning fields used during expansion.
+     */
+    partitionBy?: string[];
+
+    /**
+     * Original point selection that was expanded.
+     */
+    origin: PointExpandOrigin;
+} & PointExpandMatcher;
+
+/**
+ * Bookmarkable param value stored in provenance.
+ */
+export type ParamValue =
+    | ParamValueLiteral
+    | ParamValueInterval
+    | ParamValuePoint
+    | ParamValuePointExpand;
+
+/**
+ * Payload for creating or updating a reactive selection or parameter value,
+ * including point selections, interval selections, and genomic-region
+ * selections.
+ */
+export interface ParamProvenanceEntry {
+    /**
+     * Structured selector for the parameter.
+     */
+    selector: ParamSelector;
+
+    /**
+     * Serialized parameter value.
+     */
+    value: ParamValue;
+
+    /**
+     * Optional datum origin for replayable values.
+     */
+    origin?: ParamOrigin;
+}
+
+/**
+ * Payload for expanding a point selection.
+ */
+export type ExpandPointSelectionActionPayload = {
+    /**
+     * Target param selector.
+     */
+    selector: ParamSelector;
+
+    /**
+     * Expansion operation.
+     */
+    operation: "replace" | "add" | "remove" | "toggle";
+
+    /**
+     * Optional partitioning fields for the expansion.
+     */
+    partitionBy?: string[];
+
+    /**
+     * Back-reference to the point selection origin.
+     */
+    origin: PointExpandOrigin;
+    // TODO(app): Consider optional replay-drift diagnostics here, for example
+    // expectedMatchCount/sourceDataFingerprint, if semantic replay warnings are needed.
+} & PointExpandMatcher;
+
+/**
+ * Param provenance map keyed by selector key.
+ */
+export type ParamProvenanceState = {
+    entries: Record<string, ParamProvenanceEntry>;
+};

package/src/state/selectionExpansionTypes.d.ts

@@ -0,0 +1,77 @@
+import type { Scalar } from "@genome-spy/core/spec/channel.js";
+
+export type SelectionLeafValue = Scalar | null;
+
+export type SelectionExpansionLeafPredicate =
+    | {
+          field: string;
+          op: "eq";
+          value: SelectionLeafValue;
+      }
+    | {
+          field: string;
+          op: "eq";
+          valueFromField: string;
+      }
+    | {
+          field: string;
+          op: "in";
+          values: SelectionLeafValue[];
+      };
+
+export type LogicalAnd = {
+    and: SelectionExpansionPredicate[];
+};
+
+export type LogicalOr = {
+    or: SelectionExpansionPredicate[];
+};
+
+export type LogicalNot = {
+    not: SelectionExpansionPredicate;
+};
+
+export type SelectionExpansionPredicate =
+    | SelectionExpansionLeafPredicate
+    | LogicalAnd
+    | LogicalOr
+    | LogicalNot;
+
+export type SelectionExpansionRule = {
+    kind: "sameFieldValue";
+    field: string;
+};
+
+export type SelectionExpansionMatcher =
+    | SelectionExpansionPredicate
+    | SelectionExpansionRule;
+
+export type ResolvedSelectionExpansionLeafPredicate =
+    | {
+          field: string;
+          op: "eq";
+          value: SelectionLeafValue;
+      }
+    | {
+          field: string;
+          op: "in";
+          values: SelectionLeafValue[];
+      };
+
+export type ResolvedLogicalAnd = {
+    and: ResolvedSelectionExpansionPredicate[];
+};
+
+export type ResolvedLogicalOr = {
+    or: ResolvedSelectionExpansionPredicate[];
+};
+
+export type ResolvedLogicalNot = {
+    not: ResolvedSelectionExpansionPredicate;
+};
+
+export type ResolvedSelectionExpansionPredicate =
+    | ResolvedSelectionExpansionLeafPredicate
+    | ResolvedLogicalAnd
+    | ResolvedLogicalOr
+    | ResolvedLogicalNot;

package/src/state.d.ts

@@ -0,0 +1,97 @@
+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>;
+}
+
+export interface ViewSettings {
+    /**
+     * Visibilities of views keyed by selector keys. The keys are derived from
+     * view selectors and may also include legacy view names from old bookmarks.
+     */
+    visibilities: Record<string, boolean>;
+}
+
+export interface ViewVisibilityEntry {
+    scope: string[];
+    view: string;
+    visible: boolean;
+}
+
+export type ViewVisibilityWire =
+    | ViewVisibilityEntry[]
+    | Record<string, boolean>;
+
+export interface ViewSettingsPayload {
+    visibilities?: ViewVisibilityWire;
+}
+
+export interface State {
+    viewSettings: ViewSettings;
+    /**
+     * Tracks async intent status and records provenance indices for rollback.
+     */
+    intentStatus?: {
+        status: "idle" | "running" | "error" | "canceled";
+        submissionKind?: "user" | "agent" | "bookmark";
+        startIndex?: number;
+        lastSuccessfulIndex?: number;
+        totalActions?: number;
+        currentIndex?: number;
+        currentAction?: import("@reduxjs/toolkit").Action;
+        failedAction?: import("@reduxjs/toolkit").Action;
+        error?: string;
+    };
+    provenance?: StateWithHistory<{
+        sampleView: SampleHierarchy;
+        paramProvenance: ParamProvenanceState;
+        lastAction: import("@reduxjs/toolkit").Action;
+    }>;
+}

package/src/types/lz-string.d.ts

@@ -0,0 +1,24 @@
+/*
+ * Source: https://github.com/pieroxy/lz-string/blob/master/typings/lz-string.d.ts
+
+ * The original typings didn't resolve for some reason
+ */
+
+declare module "lz-string" {
+    export function compressToBase64(input: string): string;
+    export function decompressFromBase64(input: string): string;
+
+    export function compressToUTF16(input: string): string;
+    export function decompressFromUTF16(compressed: string): string;
+
+    export function compressToUint8Array(uncompressed: string): Uint8Array;
+    export function decompressFromUint8Array(compressed: Uint8Array): string;
+
+    export function compressToEncodedURIComponent(input: string): string;
+    export function decompressFromEncodedURIComponent(
+        compressed: string
+    ): string;
+
+    export function compress(input: string): string;
+    export function decompress(compressed: string): string;
+}

package/src/types/vega-loader.d.ts

@@ -0,0 +1 @@
+declare module "vega-loader";

package/src/utils/colorScaleSummary.d.ts

@@ -0,0 +1,15 @@
+export interface ConcreteColorScale {
+    domain: unknown[];
+    range: string[];
+}
+
+export declare function getConcreteColorScale(
+    scale: unknown
+): ConcreteColorScale | undefined;
+
+export declare function addValueColors<T>(
+    items: T[],
+    getValue: (item: T) => unknown,
+    domain: unknown,
+    range: unknown
+): Array<T & { color?: string }>;

package/src/utils/statistics/fieldSummary.d.ts

@@ -0,0 +1,49 @@
+export interface QuantitativeFieldSummary {
+    nonMissingCount: number;
+    missingCount: number;
+    min?: number;
+    max?: number;
+    mean?: number;
+    median?: number;
+    p05?: number;
+    p95?: number;
+    q1?: number;
+    q3?: number;
+    iqr?: number;
+}
+
+export interface CategoryCountSummary {
+    value: unknown;
+    count: number;
+    share: number;
+}
+
+export interface CategoricalFieldSummary {
+    nonMissingCount: number;
+    missingCount: number;
+    distinctCount: number;
+    categories: CategoryCountSummary[];
+    truncated: boolean;
+    otherCount?: number;
+    otherShare?: number;
+}
+
+export declare function buildQuantitativeFieldSummary(
+    values: unknown[]
+): QuantitativeFieldSummary;
+
+export declare function buildCategoricalFieldSummary(
+    values: unknown[]
+): CategoricalFieldSummary;
+
+export declare function buildCategoricalCountsSummary(
+    counts: Map<unknown, number>,
+    nonMissingCount: number,
+    missingCount: number,
+    maxCategories?: number
+): CategoricalFieldSummary;
+
+export declare function buildTopCategorySummary(
+    counts: Map<unknown, number>,
+    nonMissingCount: number
+): CategoryCountSummary | undefined;

package/src/vite-env.d.ts

@@ -0,0 +1,6 @@
+/* eslint-disable no-unused-vars */
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+    readonly VITE_AGENT_BASE_URL?: string;
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2018-2026 Kari Lavikka
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.