@genome-spy/core 0.78.0 → 0.79.0

package/dist/src/spec/transform.d.ts

@@ -474,6 +474,153 @@ export interface MeasureTextParams extends TransformParamsBase {
     as: string;
 }
 
+export interface TruncateTextParams extends TransformParamsBase {
+    type: "truncateText";
+
+    /**
+     * The field that contains the text to be truncated.
+     */
+    field: Field;
+
+    /**
+     * Maximum text width in pixels.
+     */
+    limit?: number;
+
+    /**
+     * The font size in pixels.
+     */
+    fontSize: number;
+
+    /**
+     * The font typeface. Uses the same asynchronously loaded SDF fonts as the
+     * `"text"` mark.
+     *
+     * **Default:** `"Lato"`
+     */
+    font?: string;
+
+    /**
+     * The font style. Valid values: `"normal"` and `"italic"`.
+     *
+     * **Default:** `"normal"`
+     */
+    fontStyle?: FontStyle;
+
+    /**
+     * The font weight.
+     *
+     * **Default:** `"regular"`
+     */
+    fontWeight?: FontWeight;
+
+    /**
+     * Text appended after truncation.
+     *
+     * **Default:** `"..."`.
+     */
+    ellipsis?: string;
+
+    /**
+     * The output field where the truncated text is written.
+     *
+     * **Default:** Same as `field`.
+     */
+    as?: string;
+}
+
+export interface PackLegendLabelsParams extends TransformParamsBase {
+    type: "packLegendLabels";
+
+    /**
+     * The field that contains measured label width in pixels.
+     */
+    labelWidth: Field;
+
+    /**
+     * The direction in which entries are laid out.
+     *
+     * **Default:** `"vertical"`
+     */
+    direction?: "vertical" | "horizontal";
+
+    /**
+     * The number of columns in which to arrange entries.
+     */
+    columns?: number;
+
+    /**
+     * Symbol size in pixels squared, or a field containing per-entry symbol
+     * sizes in pixels squared.
+     *
+     * **Default:** `100`
+     */
+    symbolSize?: number | Field;
+
+    /**
+     * Symbol stroke width in pixels, or a field containing per-entry stroke
+     * widths in pixels.
+     *
+     * **Default:** `0`
+     */
+    symbolStrokeWidth?: number | Field;
+
+    /**
+     * Offset between the symbol and label in pixels.
+     *
+     * **Default:** `0`
+     */
+    labelOffset?: number;
+
+    /**
+     * Label font size in pixels.
+     *
+     * **Default:** `10`
+     */
+    fontSize?: number;
+
+    /**
+     * Padding between rows in pixels.
+     *
+     * **Default:** `0`
+     */
+    rowPadding?: number;
+
+    /**
+     * Padding between columns in pixels.
+     *
+     * **Default:** `0`
+     */
+    columnPadding?: number;
+
+    /**
+     * Horizontal offset for all generated entry coordinates in pixels.
+     *
+     * **Default:** `0`
+     */
+    xOffset?: number;
+
+    /**
+     * Horizontal offset for generated symbol coordinates in pixels.
+     *
+     * **Default:** `0`
+     */
+    symbolOffset?: number;
+
+    /**
+     * Vertical offset for all generated entry coordinates in pixels.
+     *
+     * **Default:** `0`
+     */
+    yOffset?: number;
+
+    /**
+     * Height of the pixel-space layout area. When provided, the transform also
+     * emits inverted y coordinates for GenomeSpy's unit y range.
+     */
+    yExtent?: number | ExprRef;
+}
+
 export interface MergeFacetsParams extends TransformParamsBase {
     type: "mergeFacets";
 }
@@ -606,6 +753,8 @@ export type TransformParams =
     | IdentifierParams
     | LinearizeGenomicCoordinateParams
     | MeasureTextParams
+    | TruncateTextParams
+    | PackLegendLabelsParams
     | MergeFacetsParams
     | PileupParams
     | ProjectParams

package/dist/src/spec/view.d.ts

@@ -5,6 +5,7 @@ import {
     ChannelWithScale,
     Encoding,
     FacetFieldDef,
+    NonPositionalChannelWithScale,
     PrimaryPositionalChannel,
 } from "./channel.js";
 import { MarkProps, MarkType, RuleProps } from "./mark.js";
@@ -14,6 +15,8 @@ import { Parameter } from "./parameter.js";
 import { GenomeSpyConfig } from "./config.js";
 import { ViewBackgroundProps, ZIndexProps } from "./decoration.js";
 import { Scale } from "./scale.js";
+import { Axis, GenomeAxis } from "./axis.js";
+import { Legend } from "./legend.js";
 
 export interface SizeDef {
     /**
@@ -27,6 +30,16 @@ export interface SizeDef {
      * for details.
      */
     grow?: number;
+
+    /**
+     * Minimum size in pixels.
+     */
+    minPx?: number;
+
+    /**
+     * Maximum size in pixels.
+     */
+    maxPx?: number;
 }
 
 // TODO: Perhaps this should be in "utils"
@@ -222,6 +235,26 @@ export interface ViewSpecBase extends ResolveSpec {
      */
     scales?: Partial<Record<ChannelWithScale, Scale>>;
 
+    /**
+     * Configures axis resolutions used by this view subtree.
+     *
+     * Use this when a composed view shares an axis across child views and the
+     * axis settings belong to the composed view rather than an individual
+     * encoding.
+     */
+    axes?: Partial<
+        Record<PrimaryPositionalChannel, Partial<Axis & GenomeAxis>>
+    >;
+
+    /**
+     * Configures legend resolutions used by this view subtree.
+     *
+     * Use this when a composed view shares a legend across child views and the
+     * legend settings belong to the composed view rather than an individual
+     * encoding.
+     */
+    legends?: Partial<Record<NonPositionalChannelWithScale, Legend>>;
+
     /**
      * Specifies a [data source](https://genomespy.app/docs/grammar/data/).
      * If omitted, the data source is inherited from the parent view.
@@ -252,9 +285,6 @@ export interface ViewSpecBase extends ResolveSpec {
 
     /**
      * View title.
-     * N.B.: Currently, GenomeSpy doesn't do bound calculation, and you need to
-     * manually specify proper padding for the view to ensure that the title is
-     * visible.
      */
     title?: string | Title;
 
@@ -401,7 +431,7 @@ export interface FacetSpec extends ViewSpecBase {
     spacing?: number;
 }
 
-export type ResolutionTarget = "scale" | "axis";
+export type ResolutionTarget = "scale" | "axis" | "legend";
 
 /**
  * `"independent"` and `"shared"` behave similarly to Vega-Lite.
@@ -417,9 +447,12 @@ export type ResolutionBehavior =
 
 export interface ResolveSpec {
     /**
-     * Specifies how scales and axes are
-     * [resolved](https://genomespy.app/docs/grammar/composition/#scale-and-axis-resolution)
+     * Specifies how scales, axes, and legends are
+     * [resolved](https://genomespy.app/docs/grammar/composition/#scale-axis-and-legend-resolution)
      * in the view hierarchy.
+     *
+     * If legend resolution is not configured explicitly, it follows the
+     * corresponding scale resolution.
      */
     resolve?: Partial<
         Record<

package/dist/src/types/embedApi.d.ts

@@ -4,6 +4,8 @@ import { RootSpec } from "../spec/root.js";
 import { GenomeSpyConfig } from "../spec/config.js";
 import { Scalar } from "../spec/channel.js";
 import { IntervalSelection } from "./selectionTypes.js";
+import { ImportSpec, ViewSpec } from "../spec/view.js";
+import { ViewSelector } from "../view/viewUtilTypes.js";
 
 /**
  * Embeds GenomeSpy into the DOM
@@ -97,10 +99,255 @@ export interface ParamApi<T = ParamValue> {
     subscribe: (listener: (value: T) => void) => () => void;
 }
 
+/**
+ * Address of a view in the live layout hierarchy.
+ *
+ * Use a `ViewSelector` for durable references to named views within import or
+ * insertion scopes. Use a `ViewHandle` for views returned by this API,
+ * including anonymous views. Use `"root"` to address the root view.
+ */
+export type ViewAddress = ViewHandle | ViewSelector | "root";
+
+/**
+ * Options for inserting a new child view or subtree.
+ */
+export interface InsertViewOptions {
+    /**
+     * Child index where the view is inserted. If omitted, the view is appended.
+     */
+    index?: number;
+
+    /**
+     * Optional scope name for the inserted subtree.
+     *
+     * The scope makes repeated instances of the same spec independently
+     * addressable by selectors. It does not replace the inserted root view's
+     * own `name`.
+     */
+    scope?: string | null;
+}
+
+/**
+ * Public view kind reported by `ViewHandle`.
+ */
+export type ViewHandleType = "unit" | "layer" | "concat" | "grid" | "unknown";
+
+/**
+ * Last rendered layout bounds for a view, in CSS pixels.
+ *
+ * The coordinate space is the embedded GenomeSpy canvas. Convert these bounds
+ * to DOM coordinates in the embedding application when positioning external
+ * controls.
+ */
+export interface ViewLayoutBounds {
+    /**
+     * Horizontal position of the view's left edge.
+     */
+    x: number;
+
+    /**
+     * Vertical position of the view's top edge.
+     */
+    y: number;
+
+    /**
+     * View width.
+     */
+    width: number;
+
+    /**
+     * View height.
+     */
+    height: number;
+}
+
+/**
+ * Options for reordering a view within its current parent container.
+ */
+export interface MoveViewOptions {
+    /**
+     * Destination child index within the target's current parent.
+     *
+     * The index is zero-based and is interpreted after temporarily removing
+     * the target from its parent. Values from `0` through the remaining child
+     * count are valid. A value equal to the remaining child count places the
+     * target last. Negative values and larger values throw.
+     *
+     * For children `[A, B, C, D]`, moving `B` with `index: 3` results in
+     * `[A, C, D, B]`.
+     */
+    index: number;
+}
+
+/**
+ * Live handle to a view in the embedded GenomeSpy instance.
+ *
+ * The exposed hierarchy matches the layout tree derived from the
+ * visualization spec: unit views and container views are represented as view
+ * handles, and child order is the layout order declared by the spec.
+ * GenomeSpy may add an implicit root layout container, for example when a
+ * root unit view needs space for axes, titles, or other guides.
+ *
+ * Handles are opaque public references. They do not expose internal `View`
+ * objects, and callers should check `isAlive()` before reusing a handle after
+ * mutations that may have removed its subtree.
+ */
+export interface ViewHandle {
+    /**
+     * Runtime-stable id for this handle.
+     *
+     * The id is stable only for the current embedded instance. It is not a
+     * bookmark or serialization format.
+     */
+    readonly id: string;
+
+    /**
+     * Explicit view name, if the view has one.
+     */
+    readonly name: string | undefined;
+
+    /**
+     * Selector for this view, if the view is addressable by selector.
+     */
+    readonly selector: ViewSelector | undefined;
+
+    /**
+     * Public view kind.
+     */
+    readonly type: ViewHandleType;
+
+    /**
+     * Returns whether the referenced view is still part of the live hierarchy.
+     */
+    isAlive: () => boolean;
+
+    /**
+     * Returns a handle to the layout parent, if the view has one.
+     */
+    parent: () => ViewHandle | undefined;
+
+    /**
+     * Returns handles for the current layout child views in spec order.
+     */
+    children: () => ViewHandle[];
+}
+
+/**
+ * API for inspecting and mutating the live layout hierarchy.
+ *
+ * The hierarchy model matches the layout tree derived from the visualization
+ * spec. The API addresses view nodes such as unit, layer, concat, and grid
+ * views, plus implicit layout containers that GenomeSpy may add at the root.
+ * It does not address rendered marks, guide primitives, DOM nodes, or other
+ * internal implementation objects.
+ *
+ * Mutations are asynchronous because view creation, imports, dataflow
+ * initialization, data loading, guide rebuilding, and layout updates may all be
+ * involved. Mutation promises resolve when the operation-specific lifecycle has
+ * completed.
+ */
+export interface ViewApi {
+    /**
+     * Returns a handle to the root layout view.
+     *
+     * The root may be an implicit layout container rather than the top-level
+     * view declared by the input spec.
+     */
+    root: () => ViewHandle;
+
+    /**
+     * Resolves an address to a live view handle.
+     *
+     * Returns `undefined` when the address cannot be resolved or when a handle
+     * no longer refers to a live view.
+     */
+    resolve: (address: ViewAddress) => ViewHandle | undefined;
+
+    /**
+     * Resolves an address to a live view handle.
+     *
+     * Throws if the address cannot be resolved or if a handle no longer refers
+     * to a live view.
+     */
+    get: (address: ViewAddress) => ViewHandle;
+
+    /**
+     * Returns the last rendered layout bounds for a view.
+     *
+     * Bounds are returned in CSS pixels in the embedded GenomeSpy canvas
+     * coordinate space. Returns `undefined` if the address is unresolved, the
+     * view is no longer live, or the view has not been rendered yet.
+     */
+    getLayoutBounds: (address: ViewAddress) => ViewLayoutBounds | undefined;
+
+    /**
+     * Subscribes to completed layout updates.
+     *
+     * The listener is called after a layout/render pass has updated view
+     * bounds. Returns an unsubscribe function.
+     */
+    subscribeToLayout: (listener: () => void) => () => void;
+
+    /**
+     * Inserts a new child view or subtree under a mutable container view.
+     *
+     * The `spec` can be an ordinary view spec or an import spec. Use
+     * `options.scope` to give the inserted instance a selector scope, allowing
+     * the same spec to be inserted multiple times and addressed independently.
+     */
+    insert: (
+        parent: ViewAddress,
+        spec: ViewSpec | ImportSpec,
+        options?: InsertViewOptions
+    ) => Promise<ViewHandle>;
+
+    /**
+     * Removes a view and disposes its subtree.
+     *
+     * Removing the root view is not supported.
+     */
+    remove: (target: ViewAddress) => Promise<void>;
+
+    /**
+     * Reorders a view within its current parent container.
+     *
+     * `options.index` is the destination index after temporarily removing the
+     * target from its current position.
+     *
+     * Moving a view to another branch of the hierarchy is not supported by the
+     * initial API.
+     */
+    move: (
+        target: ViewAddress,
+        options: MoveViewOptions
+    ) => Promise<ViewHandle>;
+
+    /**
+     * Runs multiple mutations as one ordered transaction.
+     *
+     * Implementations may defer layout and rendering work until the callback
+     * has completed.
+     */
+    transaction: <T>(
+        callback: (views: ViewApi) => T | Promise<T>
+    ) => Promise<T>;
+}
+
+/**
+ * @deprecated Use `ViewApi`. The `api.views` namespace now includes both
+ * mutation and layout observation methods.
+ */
+export type ViewMutationApi = ViewApi;
+
 /**
  * An API for controlling the embedded GenomeSpy instance.
  */
 export interface EmbedResult {
+    /**
+     * Inspects and controls the live view hierarchy.
+     */
+    views: ViewApi;
+
     /**
      * Releases all resources and unregisters event listeners, etc.
      */
@@ -121,9 +368,10 @@ export interface EmbedResult {
 
     /**
      * Returns a named `ScaleResolution` object that allows for attaching event
-     * listeners and controlling the scale domain.
+     * listeners and controlling the scale domain. Returns `undefined` when the
+     * name is not registered.
      */
-    getScaleResolutionByName: (name: string) => ScaleResolutionApi;
+    getScaleResolutionByName: (name: string) => ScaleResolutionApi | undefined;
 
     /**
      * Returns a handle for reading, writing, and subscribing to a named
@@ -173,9 +421,17 @@ export interface EmbedResult {
      * @returns A PNG data URL
      */
     exportCanvas: (
-        logicalWidth: number,
-        logicalHeight: number,
-        devicePixelRatio: number,
-        clearColor: string
+        logicalWidth?: number,
+        logicalHeight?: number,
+        devicePixelRatio?: number,
+        clearColor?: string
     ) => string;
+
+    /**
+     * Returns the internal root view for optional developer tooling.
+     *
+     * This API is intended for debug inspectors that need access to internal
+     * runtime structures without forcing debug modules into normal Core use.
+     */
+    getDebugViewRoot: () => object | undefined;
 }

package/dist/src/types/rendering.d.ts

@@ -35,10 +35,25 @@ export interface RenderingOptions {
     sampleFacetRenderingOptions?: SampleFacetRenderingOptions;
 
     /**
-     * Clip rendering using the given rectangle.
-     * Mainly intended for clipping scrollable views.
+     * Convenience shorthand for clipping rendering to the given rectangle in
+     * both directions. Core rendering internals normalize this to `clip`.
+     *
+     * Mainly intended for existing callers that need ordinary rectangular
+     * clipping.
      */
     clipRect?: Rectangle;
+
+    /**
+     * Clip rendering using the given rectangle and direction flags. Prefer this
+     * option when clipping should apply only horizontally or vertically.
+     */
+    clip?: ClipOptions;
+}
+
+export interface ClipOptions {
+    rect: Rectangle;
+    clipX: boolean;
+    clipY: boolean;
 }
 
 /**
@@ -60,7 +75,8 @@ export interface BufferedRenderingRequest {
     mark: Mark;
     callback: () => void;
     coords: Rectangle;
-    clipRect?: Rectangle;
+    clip?: ClipOptions;
+    cullClip?: ClipOptions;
 }
 
 /**

package/dist/src/types/viewContext.d.ts

@@ -10,6 +10,8 @@ import { Datum } from "../data/flowNode.js";
 import { ImportSpec, ViewSpec } from "../spec/view.js";
 import ContainerView from "../view/containerView.js";
 import { BroadcastEventType } from "../genomeSpy.js";
+import { AxisLabelClipPolicy } from "../view/axisView.js";
+import { PrimaryPositionalChannel } from "../spec/channel.js";
 
 export interface Hover {
     mark: Mark;
@@ -18,10 +20,24 @@ export interface Hover {
 
 export type DataLoadingStatus = "loading" | "complete" | "error";
 
-export interface CreateViewOptions {
-    layoutSizeParams?: "own" | "inherit";
+export interface ViewOptions {
+    /** Inherits encodings from the data parent. Authored composition children opt in. */
+    inheritEncoding?: boolean;
+    /**
+     * Controls whether the view allocates local layout-driven width/height
+     * parameters. `"own"` preserves explicitly configured ancestor params,
+     * `"inherit"` disables local layout params, and `"force"` always allocates
+     * local layout params.
+     */
+    layoutSizeParams?: "own" | "inherit" | "force";
+    /** Overrides label clipping for axes created for this view. */
+    axisLabelClipPolicy?: Partial<
+        Record<PrimaryPositionalChannel, AxisLabelClipPolicy>
+    >;
 }
 
+export type CreateViewOptions = ViewOptions;
+
 /**
  * ViewContext provides essential data and interfaces to View classes.
  */

package/dist/src/utils/arrayUtils.d.ts

@@ -31,4 +31,15 @@ export function asArray<T>(obj: T[] | T): T[];
  * @template T
  */
 export function peek<T>(arr: T[]): T;
+/**
+ * Moves an item within an array.
+ *
+ * The destination index is interpreted after temporarily removing the item.
+ *
+ * @param {T[]} arr
+ * @param {number} fromIndex
+ * @param {number} index
+ * @template T
+ */
+export function moveArrayItem<T>(arr: T[], fromIndex: number, index: number): void;
 //# sourceMappingURL=arrayUtils.d.ts.map

package/dist/src/utils/arrayUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"arrayUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/arrayUtils.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,mCAFa,CAAC,KAFH,CAAC,EAAE,KACH,CAAC,EAAE,WAKb;AAED;;;;;;GAMG;AACH,gDAFa,CAAC,EAAE,CAAC,EAAE,CAAC,KAJT,CAAC,EAAE,KACH,CAAC,EAAE,aACH,CAAS,IAAC,EAAD,CAAC,KAAE,CAAC,aACb,CAAS,IAAC,EAAD,CAAC,KAAE,CAAC,WAQvB;AAED;;;GAGG;AACH,iCAFW,GAAG,EAAE,WASf;AAED;;;;GAIG;AACH,wBAFa,CAAC,OAFH,CAAC,EAAE,GAAG,CAAC,GACL,CAAC,EAAE,CAWf;AAED;;;;;;GAMG;AACH,qBAFa,CAAC,OADH,CAAC,EAAE,KAKb"}
+{"version":3,"file":"arrayUtils.d.ts","sourceRoot":"","sources":["../../../src/utils/arrayUtils.js"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,mCAFa,CAAC,KAFH,CAAC,EAAE,KACH,CAAC,EAAE,WAKb;AAED;;;;;;GAMG;AACH,gDAFa,CAAC,EAAE,CAAC,EAAE,CAAC,KAJT,CAAC,EAAE,KACH,CAAC,EAAE,aACH,CAAS,IAAC,EAAD,CAAC,KAAE,CAAC,aACb,CAAS,IAAC,EAAD,CAAC,KAAE,CAAC,WAQvB;AAED;;;GAGG;AACH,iCAFW,GAAG,EAAE,WASf;AAED;;;;GAIG;AACH,wBAFa,CAAC,OAFH,CAAC,EAAE,GAAG,CAAC,GACL,CAAC,EAAE,CAWf;AAED;;;;;;GAMG;AACH,qBAFa,CAAC,OADH,CAAC,EAAE,KAKb;AAED;;;;;;;;;GASG;AACH,8BAFa,CAAC,OAHH,CAAC,EAAE,aACH,MAAM,SACN,MAAM,QAchB"}

package/dist/src/utils/arrayUtils.js

@@ -59,3 +59,26 @@ export function asArray(obj) {
 export function peek(arr) {
     return arr[arr.length - 1];
 }
+
+/**
+ * Moves an item within an array.
+ *
+ * The destination index is interpreted after temporarily removing the item.
+ *
+ * @param {T[]} arr
+ * @param {number} fromIndex
+ * @param {number} index
+ * @template T
+ */
+export function moveArrayItem(arr, fromIndex, index) {
+    if (fromIndex < 0 || fromIndex >= arr.length) {
+        throw new Error("Source index out of range.");
+    }
+
+    if (index < 0 || index > arr.length - 1) {
+        throw new Error("Destination index out of range.");
+    }
+
+    const [item] = arr.splice(fromIndex, 1);
+    arr.splice(index, 0, item);
+}

package/dist/src/utils/suspension.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Reference-counted suspension guard. Nested suspensions are supported and the
+ * resume callback runs only when the outermost release happens.
+ */
+export default class Suspension {
+    /**
+     * @param {() => void} [onResume]
+     */
+    constructor(onResume?: () => void);
+    get active(): boolean;
+    /**
+     * @returns {() => void}
+     */
+    suspend(): () => void;
+    #private;
+}
+//# sourceMappingURL=suspension.d.ts.map

package/dist/src/utils/suspension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suspension.d.ts","sourceRoot":"","sources":["../../../src/utils/suspension.js"],"names":[],"mappings":"AAAA;;;GAGG;AACH;IAMI;;OAEG;IACH,uBAFW,MAAM,IAAI,EAIpB;IAED,sBAEC;IAED;;OAEG;IACH,WAFa,MAAM,IAAI,CAiBtB;;CACJ"}