@genome-spy/app 0.75.0 → 0.77.0

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

@@ -0,0 +1,76 @@
+import { scalar } from "@genome-spy/core/utils/domainArray.js";
+import { SampleAttributeDef } from "@genome-spy/app/spec/sampleView.js";
+import { AttributeIdentifier } from "../types.js";
+import { PayloadAction } from "@reduxjs/toolkit";
+
+export type SampleId = string;
+
+/**
+ * Sample metadata
+ */
+export interface Sample {
+    id: SampleId;
+
+    displayName: string;
+
+    /** For internal use. Identifies the sample facet efficiently. */
+    indexNumber: number;
+}
+
+export type Metadatum = Record<string, scalar>;
+export type Metadata = Record<SampleId, Metadatum>;
+
+export interface BaseGroup {
+    /** e.g., an attribute value that forms a group. Used as a key when identifying subgroups. */
+    name: string;
+
+    /** A descriptive title for the group. May contain quantile intervals, etc. */
+    title: string;
+
+    /** Original generated title for derived groups, such as threshold intervals. */
+    generatedTitle?: string;
+}
+
+export interface SampleGroup extends BaseGroup {
+    samples: SampleId[];
+}
+
+export interface GroupGroup extends BaseGroup {
+    groups: Group[];
+}
+
+export type Group = SampleGroup | GroupGroup;
+
+export interface GroupMetadata {
+    /** e.g., an attribute that is used for partitioning */
+    attribute: AttributeIdentifier;
+}
+
+export interface SampleMetadata {
+    /** SampleIds as keys, attributes as values */
+    entities: Metadata;
+    /** Names of all available metadata attributes */
+    attributeNames: string[];
+    /** A definition for each attribute or attribute group */
+    attributeDefs?: Record<string, SampleAttributeDef>;
+}
+
+export interface SampleHierarchy {
+    /** All known samples that are available for use */
+    sampleData: {
+        ids: SampleId[];
+        entities: Record<SampleId, Sample>;
+    };
+
+    /** Metadata for samples. It's ok to have some samples missing. */
+    sampleMetadata: SampleMetadata;
+
+    /** Metadata for each hierarchy level. Does not include the root. */
+    groupMetadata: GroupMetadata[];
+
+    /** The root of the hierarchy */
+    rootGroup: Group;
+
+    // TODO: Extract this into a separate interface
+    lastAction?: PayloadAction;
+}

package/src/sampleView/types.d.ts

@@ -0,0 +1,128 @@
+import { ViewAttributeSpecifier } from "./sampleViewTypes.js";
+import { SampleHierarchy } from "./state/sampleState.js";
+import { ChromosomalLocus } from "@genome-spy/core/spec/genome.js";
+import { Scale } from "@genome-spy/core/spec/scale.js";
+
+/**
+ * Stable identifier for an abstract attribute used by actions and agent
+ * context.
+ *
+ * `type` identifies the attribute source kind, and `specifier` contains the
+ * concrete lookup information for that source.
+ *
+ * Examples:
+ * - `{ type: "SAMPLE_ATTRIBUTE", specifier: "age" }`
+ */
+export type AttributeIdentifierType =
+    | "SAMPLE_ATTRIBUTE"
+    | "VALUE_AT_LOCUS"
+    | "SAMPLE_NAME"
+    | "VIEW_ATTRIBUTE";
+
+export interface AttributeIdentifier {
+    type: AttributeIdentifierType;
+    specifier?: string | ViewAttributeSpecifier;
+}
+
+/**
+ * One endpoint of an interval.
+ */
+export type IntervalPoint = number | ChromosomalLocus;
+
+/**
+ * Interval expressed as two scalar or locus points.
+ */
+export type Interval = [IntervalPoint, IntervalPoint];
+
+/**
+ * Aggregation operators supported by interval-based attribute access.
+ */
+export type AggregationOp =
+    | "itemCount"
+    | "min"
+    | "max"
+    | "weightedMean"
+    | "variance"
+    | "count";
+
+/**
+ * Aggregation configuration for interval-derived attribute access.
+ */
+export interface AggregationSpec {
+    op: AggregationOp;
+}
+
+/**
+ * Arguments passed to attribute value providers, including the current
+ * selection of sample ids and optional interval/aggregation context.
+ */
+export interface AttributeValuesScope {
+    sampleIds: string[];
+    sampleHierarchy: SampleHierarchy;
+    interval?: Interval;
+    aggregation?: AggregationSpec;
+}
+
+/**
+ * Context passed to attribute availability hooks.
+ */
+export interface AttributeEnsureContext {
+    signal?: AbortSignal;
+}
+
+export interface AttributeInfo {
+    /**
+     * A concise name of the attribute: TODO: Used for what?
+     * @deprecated Use attribute instead
+     */
+    name: string;
+
+    attribute: AttributeIdentifier;
+
+    /** 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;
+
+    /**
+     * Optional description of the attribute. Can be used in UI and agent
+     * context to explain the meaning of the attribute.
+     */
+    description?: string;
+
+    /** Function that maps a sampleId to an attribute value */
+    accessor: (sampleId: string, sampleHierarchy: SampleHierarchy) => any;
+
+    /**
+     * Provides values for dialogs (e.g., histograms) with optional interval aggregation.
+     * Use `extractAttributeValues` for the default fallback implementation.
+     */
+    valuesProvider: (scope: AttributeValuesScope) => any[];
+
+    /** e.g., "quantitative" */
+    type: string;
+
+    /**
+     * Optional hook for ensuring attribute availability before access.
+     * Used by async intent processing to resolve lazy data dependencies.
+     */
+    ensureAvailability?: (context: AttributeEnsureContext) => Promise<void>;
+
+    /**
+     * Optional hook for awaiting post-dispatch readiness.
+     * Used by async intent processing to guarantee that state and data are ready.
+     */
+    awaitProcessed?: (context: AttributeEnsureContext) => Promise<void>;
+
+    scale?: any;
+
+    /**
+     * Authored scale definition for the source encoding, when available.
+     * Unlike `scale`, this does not include runtime-inferred defaults.
+     */
+    scaleSpec?: Scale;
+}

package/src/spec/appSpec.d.ts

@@ -0,0 +1,54 @@
+import { RootConfig } from "@genome-spy/core/spec/root.js";
+import { AppViewSpec } from "./view.js";
+
+export interface RemoteBookmarkConfig {
+    /**
+     * URL to the remote bookmark file.
+     */
+    url: string;
+
+    /**
+     * Should the user be shown a tour of the remote bookmarks when the visualization
+     * is launched? If the `initialBookmark` property is not defined, the tour starts
+     * from the first bookmark.
+     *
+     * __Default value:__ `false`
+     */
+    tour?: boolean;
+
+    /**
+     * Name of the bookmark that should be loaded as the initial state. The bookmark
+     * description dialog is shown only if the `tour` property is set to `true`.
+     */
+    initialBookmark?: string;
+
+    /**
+     * Name of the bookmark that should be loaded when the user ends the tour.
+     * If `null`, the dialog will be closed and the current state is retained.
+     * If undefined, the default state without any performed actions will be loaded.
+     */
+    afterTourBookmark?: string;
+}
+
+export interface BookmarkConfig {
+    /**
+     * Configuration for loading bookmarks from a remote JSON file.
+     */
+    remote?: RemoteBookmarkConfig;
+}
+
+interface AppRootConfig {
+    /**
+     * A unique identifier that is used in storing state bookmarks to browser's
+     * IndexedDB. This is needed to make distinction between visualizations that
+     * are served from the same origin, i.e., the same host and port.
+     */
+    specId?: string;
+
+    /**
+     * Bookmark configuration.
+     */
+    bookmarks?: BookmarkConfig;
+}
+
+export type AppRootSpec = AppViewSpec & RootConfig & AppRootConfig;