@czi-sds/data-viz 2.4.2 → 2.5.0

package/dist/shared/index2.esm.d.ts

@@ -1,9 +1,11 @@
-/// <reference types="react" />
 import { t as ColorScale } from "./colorScales.esm.js";
 import { HTMLAttributes } from "react";
+import { PluginContext } from "molstar/lib/mol-plugin/context";
 import { TooltipProps } from "@czi-sds/components";
 import { PluginUISpec } from "molstar/lib/mol-plugin-ui/spec";
-import { CustomElementProperty } from "molstar/lib/mol-model-props/common/custom-element-property";
+import { PluginStateObject } from "molstar/lib/mol-plugin-state/objects";
+import { PluginUIContext } from "molstar/lib/mol-plugin-ui/context";
+import { StateObjectSelector } from "molstar/lib/mol-state";
 
 //#region src/core/ProteinStructureViewer/ProteinStructureViewer.types.d.ts
 /**
@@ -52,12 +54,12 @@ interface ResidueValueOverlay {
  * address it.
  *
  * `index` is the viewer's own key: the position in `plddt` and in
- * `residueOverlay`'s map, and what `selectedResidue` takes. `chainId`, `seqId`
- * and `insCode` are what the file says, which is what the sequence panel shows
- * and what a system that supplied the structure will recognise. They differ
- * from `index` whenever the file does not number a single chain from 1 -- a
- * crop, or a complex -- so address a residue outside the viewer with those
- * three, not with `index`.
+ * `residueOverlay`'s map, and what `selection.residues` takes. `chainId`,
+ * `seqId` and `insCode` are what the file says, which is what the sequence
+ * panel shows and what a system that supplied the structure will recognise.
+ * They differ from `index` whenever the file does not number a single chain
+ * from 1 -- a crop, or a complex -- so address a residue outside the viewer
+ * with those three, not with `index`.
  *
  * `insCode` is rarely set but is part of the address when it is: `10` and `10A`
  * are different residues on the same chain, so chain and number alone do not
@@ -101,6 +103,28 @@ interface ChainRef {
   /** Polymer residues the chain holds. */
   residueCount: number;
 }
+/**
+ * A residue as the file names it: chain, number and insertion code, which is
+ * what a system that supplied the structure will recognise. `ResidueRef`
+ * reports the same three, so a residue the viewer reported can be handed back
+ * as one of these.
+ */
+interface ResidueAddress {
+  /** Chain as named in the file (`auth_asym_id`). */
+  chainId: string;
+  /** Residue number as written in the file (`auth_seq_id`). */
+  seqId: number;
+  /** Insertion code, when the residue has one. */
+  insCode?: string;
+}
+/** A residue picked out in a color of its own, over whatever paints the rest. */
+interface ResidueHighlight extends ResidueAddress {
+  /**
+   * As `#RRGGBB`. Highlights that name none take the next color of the
+   * viewer's highlight palette, in the order they are given.
+   */
+  color?: string;
+}
 /**
  * What is selected, in the two ways a caller might say it. `null` selects
  * nothing.
@@ -118,6 +142,60 @@ interface StructureSelection {
   residues?: number[];
   /** Whole chains by `chainId`, each standing for every residue on it. */
   chains?: string[];
+  /**
+   * Residues by the address the file gives them, for a caller that knows a
+   * residue by its chain and number rather than by its position. They join
+   * `residues`, and an address the structure does not have selects nothing.
+   * The viewer reports its own selections as `residues`.
+   */
+  addresses?: ResidueAddress[];
+}
+/**
+ * How the polymer is drawn. `"surface"` is one molecular surface over the
+ * visible chains, so hiding a partner exposes the face it was bound to.
+ */
+type StructureRepresentation = "cartoon" | "surface";
+/** What paints the structure, when `colorBy` names it outright. */
+type StructureColorBy = "chain" | "plddt" | "overlay";
+type CameraProjection = "perspective" | "orthographic";
+/**
+ * Where the camera looks from, relative to the highlighted residues: straight
+ * at them from outside the structure, from the far side, or from the side.
+ * `"overview"`, and any orientation while nothing is highlighted, looks down
+ * the view's default axis at the whole structure.
+ */
+type CameraOrientation = "overview" | "facing" | "opposite" | "side";
+/**
+ * Everything that places the camera, enough to put it back exactly where it
+ * was. What `onCameraChange` reports and `initialCamera` takes.
+ */
+interface CameraState {
+  position: [number, number, number];
+  target: [number, number, number];
+  up: [number, number, number];
+  /** Field of view, in radians. */
+  fov: number;
+  /** Radius of the sphere around `target` the camera frames. */
+  radius: number;
+  /** Radius of the whole scene, which bounds how far the camera clips. */
+  radiusMax: number;
+  projection: CameraProjection;
+  /**
+   * Size of the canvas the camera framed, in pixels. Reported so an image can
+   * be rendered at the same aspect; ignored when the state is applied.
+   */
+  viewport?: {
+    width: number;
+    height: number;
+  };
+}
+/** What `onStructureLoad` reports for each structure loaded. */
+interface StructureLoadInfo {
+  /** Atoms Mol* parsed. */
+  atomCount: number;
+  /** Polymer residues across every chain, as the chains count them. */
+  residueCount: number;
+  chains: ChainRef[];
 }
 /**
  * How large a downloaded image is, in pixels.
@@ -162,21 +240,102 @@ interface StructureDownload {
    * Mol* derives from the loaded structure.
    */
   filename?: string;
+  /**
+   * Renders the image in place of the viewer's own capture, for a caller that
+   * has to bound its size, keep the viewport's aspect, or draw it some other
+   * way. Resolves with a PNG. `resolution`, `backgroundColor` and `showAxes`
+   * describe the viewer's own capture, so they are not applied to this one.
+   */
+  render?: (plugin: PluginUIContext) => Promise<Blob>;
+  /**
+   * Receives the PNG in place of a browser download, along with the name it
+   * would have been saved under, `.png` included. A sandboxed iframe blocks the
+   * download a click would otherwise start, so a bridge to its host goes here.
+   */
+  deliver?: (image: Blob, filename: string) => void | Promise<void>;
 }
+/**
+ * What a load hands to `onReady`: the structure the viewer parsed, and what it
+ * found in it.
+ */
+interface LoadedStructureInfo {
+  /**
+   * The parsed structure's cell in the plugin's state tree. Components and
+   * representations built on it are what a consumer drawing its own scene
+   * adds; they go when the next structure is loaded, along with the rest of
+   * the tree.
+   */
+  structure: StateObjectSelector<PluginStateObject.Molecule.Structure>;
+  /**
+   * Atoms Mol* parsed. A consumer holding a known count for the file can check
+   * the parse against it before trusting what is drawn.
+   */
+  atomCount: number;
+  /** The polymer chains found, as `onChainsChange` reports them. */
+  chains: ChainRef[];
+}
+/**
+ * Which part of the viewer's work an error reported to `onError` came from.
+ * `"representation"` is a representation that could not be drawn - a surface
+ * too large for its grid - which leaves the cartoon in its place.
+ */
+type ViewerErrorPhase = "init" | "load" | "capture" | "representation";
+/**
+ * Who draws the structure: the viewer, from its props, or a consumer building
+ * its own scene on the structure `onReady` hands it.
+ */
+type SceneMode = "managed" | "external";
 /** A whole-structure statistic shown along the bottom of the viewer. */
 interface StructureStat {
   value: string;
   label: string;
 }
-interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement>, "onError" | "onSelect"> {
   /** Structure to render, as raw PDB or mmCIF (PDBx) text. */
   structure: string;
   /**
    * Per-residue pLDDT confidence on a 0-1 scale, ordered by residue. When
    * supplied the structure is colored by pLDDT unless `residueOverlay` takes
-   * over.
+   * over. A `null` entry, and every residue past the end, reads as unscored
+   * and is painted neutral rather than at the bottom of the scale.
+   */
+  plddt?: (number | null)[] | null;
+  /**
+   * What paints the structure. Left undefined it follows what is supplied: a
+   * `residueOverlay` when there is one, then `plddt`, then the chain colors.
+   * Naming one makes it paint whatever else is set, which is how a toggle
+   * between confidence and chain coloring keeps both props in place. A theme
+   * with nothing to paint with leaves every residue neutral.
+   */
+  colorBy?: StructureColorBy;
+  /**
+   * How the polymer is drawn. Ligands stay ball-and-stick either way.
+   * Switching leaves the camera where it is.
+   * @default "cartoon"
+   */
+  representation?: StructureRepresentation;
+  /**
+   * Residues picked out in colors of their own, by the address the file gives
+   * them. They paint over whatever colors the rest - chain, pLDDT or overlay -
+   * and are drawn in ball-and-stick over the cartoon; on a surface, the
+   * surface itself carries them. Separate from `selection`: highlighting a
+   * residue neither selects it nor moves the camera.
+   */
+  highlights?: ResidueHighlight[];
+  /** The camera's projection. Left undefined, Mol*'s own default stands. */
+  projection?: CameraProjection;
+  /**
+   * Where the camera starts on each structure loaded, in place of fitting it
+   * to the structure. Applied once per load; moving the camera afterwards is
+   * the user's.
+   */
+  initialCamera?: CameraState | null;
+  /**
+   * Turns the camera to look at the highlighted residues from one side or
+   * another. Applied when a structure is loaded, unless `initialCamera` is
+   * set, and whenever it changes - not when the highlights do.
    */
-  plddt?: number[] | null;
+  orientation?: CameraOrientation;
   /**
    * Canvas background, as `#RRGGBB`. Defaults to the SDS theme's base
    * background, so the canvas follows the surrounding page in both modes.
@@ -210,13 +369,15 @@ interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement
   /** Per-residue values that override pLDDT coloring while set. */
   residueOverlay?: ResidueValueOverlay | null;
   /**
-   * What is selected, or null when nothing is. Controlled: the camera frames
-   * whatever the selection covers, and clearing it zooms back out to the
-   * default view.
+   * What is selected, or null when nothing is. Leave undefined to let the
+   * viewer own the selection, so clicking a residue zooms in on it with no
+   * state on the consumer's side; passing it takes that over, and a click then
+   * moves the camera only once `onSelectionChange` is echoed back here.
    *
-   * Residues are drawn in ball-and-stick over the cartoon; whole chains are
-   * left as they are and the chains around them dim, the same as hovering a
-   * chain's name.
+   * Either way the camera frames whatever the selection covers, and clearing
+   * it zooms back out to the default view. Residues are drawn in
+   * ball-and-stick over the cartoon; whole chains are left as they are and the
+   * chains around them dim, the same as hovering a chain's name.
    */
   selection?: StructureSelection | null;
   /**
@@ -228,7 +389,8 @@ interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement
   /**
    * Color per chain, by `chainId`, as `#RRGGBB`. Chains left out fall back to
    * the viewer's palette. Only visible while chain coloring is what is on
-   * screen, which is when neither `plddt` nor `residueOverlay` is set.
+   * screen: when `colorBy` says so, or, left undefined, when neither `plddt`
+   * nor `residueOverlay` is set.
    */
   chainColors?: Record<string, string>;
   /**
@@ -268,6 +430,52 @@ interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement
    * so the rest is deliberately not reactive.
    */
   molstarSpec?: Partial<PluginUISpec>;
+  /**
+   * Who draws the structure.
+   *
+   * `"managed"` draws each chain as a cartoon and its ligands as
+   * ball-and-stick, colors them from `plddt`, `residueOverlay` and
+   * `chainColors`, hides the chains `hiddenChains` names, and frames the camera
+   * on each structure it loads.
+   *
+   * `"external"` parses the structure and stops there: nothing is drawn,
+   * colored, hidden or framed, and a consumer draws its own scene on the
+   * structure `onReady` hands it. The sequence panel, selection, hover, legend
+   * and camera controls work as before; the legend describes the props rather
+   * than what the consumer drew, and its chain toggles report through
+   * `onChainVisibilityChange` without hiding anything. Mol* frames the camera
+   * on the first representation drawn into the empty scene.
+   *
+   * Read once, when the plugin is created.
+   * @default "managed"
+   */
+  sceneMode?: SceneMode;
+  /**
+   * Called with the Mol* plugin once a structure is loaded into it, and again
+   * for each structure that replaces it, which is how a consumer reaches the
+   * plugin to draw on it or drive it directly.
+   *
+   * Called once the viewer has drawn its own scene, and awaited before it
+   * starts answering clicks and hovers, so a scene built here is in place
+   * before a click reaches it. The viewer only ever recolors, hides or
+   * replaces the components it built itself, so representations added here
+   * are left as they were made. Not called for a structure that failed to
+   * load, or for a plugin the viewer disposed of first.
+   */
+  onReady?: (plugin: PluginUIContext, loaded: LoadedStructureInfo) => void | Promise<void>;
+  /**
+   * Called when creating the plugin, loading a structure, capturing an image or
+   * drawing a representation fails, in place of the message the viewer would
+   * otherwise log. A rejected `onReady` is reported as a `"load"` failure.
+   * Nothing is reported for a plugin the viewer has already disposed of.
+   */
+  onError?: (error: unknown, phase: ViewerErrorPhase) => void;
+  /**
+   * Called before the viewer disposes of a plugin it handed to `onReady`,
+   * including one whose `onReady` has not finished, so that whatever was built
+   * on it can be let go.
+   */
+  onDispose?: () => void;
   /**
    * Up to three whole-structure stats shown along the bottom. A null entry
    * reserves its column without rendering anything, so the columns never shift
@@ -288,6 +496,8 @@ interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement
    *
    * A whole-chain selection arrives as `{ chains: [id] }` rather than as every
    * index on it, so echoing it straight back into `selection` costs nothing.
+   * Fires whether or not `selection` is controlled, so a consumer can follow
+   * the viewer's own selection without owning it.
    */
   onSelectionChange?: (selection: StructureSelection | null) => void;
   /**
@@ -295,6 +505,18 @@ interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement
    * loaded. Fires with `[]` when the structure holds none.
    */
   onChainsChange?: (chains: ChainRef[]) => void;
+  /**
+   * Called for every structure that loads, reloads included - unlike
+   * `onChainsChange`, which stays quiet when the chains come back the same.
+   * What a consumer tracking "loading" and "ready" states listens for.
+   */
+  onStructureLoad?: (info: StructureLoadInfo) => void;
+  /**
+   * Called with the camera each time it comes to rest after moving, whether a
+   * drag, a zoom, a selection framing it, or a new structure fitting it. The
+   * state can be handed back as `initialCamera` to restore the view.
+   */
+  onCameraChange?: (camera: CameraState) => void;
   /**
    * Called with the chains now hidden when a visibility toggle is used. Fires
    * whether or not `hiddenChains` is controlled, so a consumer can follow the
@@ -302,6 +524,64 @@ interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement
    */
   onChainVisibilityChange?: (hiddenChains: string[]) => void;
 }
+/**
+ * A structure and how to draw it, as the viewer's props describe it - for a
+ * scene drawn on a plugin of the caller's, or rendered straight to an image,
+ * with no viewer involved. Each field means what the prop of the same name
+ * means.
+ */
+interface StructureSceneOptions {
+  /** Structure to draw, as raw PDB or mmCIF (PDBx) text. */
+  structure: string;
+  plddt?: (number | null)[] | null;
+  residueOverlay?: ResidueValueOverlay | null;
+  colorBy?: StructureColorBy;
+  chainColors?: Record<string, string>;
+  representation?: StructureRepresentation;
+  highlights?: ResidueHighlight[];
+  hiddenChains?: string[];
+  initialCamera?: CameraState | null;
+  orientation?: CameraOrientation;
+  projection?: CameraProjection;
+  /**
+   * Which of the light or dark neutral grays a residue without a value is
+   * painted in.
+   * @default "light"
+   */
+  mode?: "light" | "dark";
+  /**
+   * Told when a representation cannot be drawn - a surface too large for its
+   * grid, which leaves the cartoon in its place. A structure that fails to
+   * load rejects instead.
+   */
+  onError?: (error: unknown, phase: ViewerErrorPhase) => void;
+}
+/** A scene drawn on a plugin by `applyStructureScene`. */
+interface StructureSceneHandle {
+  /** What the structure last loaded holds. */
+  readonly info: StructureLoadInfo;
+  /**
+   * Applies new options in place, leaving the camera where it is. A new
+   * `structure` is loaded, and the camera placed on it, as the first was.
+   */
+  update: (options: Partial<StructureSceneOptions>) => Promise<void>;
+  /** Where the camera is now, in the form `initialCamera` takes. */
+  getCamera: () => CameraState | undefined;
+  /**
+   * Stops the scene touching the plugin. The plugin, and what was drawn on
+   * it, stay the caller's.
+   */
+  dispose: () => void;
+}
+/** What `renderStructureImage` draws, and the image it draws it into. */
+interface RenderStructureImageOptions extends StructureSceneOptions {
+  /** Width of the image, in pixels. */
+  width: number;
+  /** Height of the image, in pixels. */
+  height: number;
+  /** Background behind the structure, as `#RRGGBB`. Omit for transparent. */
+  backgroundColor?: string;
+}
 /**
  * Readout that replaces the whole-structure stats while something is hovered
  * or selected. Covers one residue or many: a drag across the sequence and a
@@ -331,61 +611,35 @@ interface ResidueReadout {
   residueCount: number;
 }
 //#endregion
-//#region src/core/ProteinStructureViewer/utils/structureFormat.d.ts
-/**
- * Structure text formats Mol* can parse from the viewer's `structure` prop.
- *
- * `"mmcif"` covers both mmCIF and PDBx; they are the same text format, and
- * that is the name Mol*'s trajectory parser uses. Binary CIF (`.bcif`) is not
- * accepted: the prop is a string.
- */
-type StructureFormat = "pdb" | "mmcif";
+//#region src/core/ProteinStructureViewer/scene/applyStructureScene.d.ts
 /**
- * Infers whether `text` is PDB or mmCIF (PDBx).
+ * Draws a structure on a Mol* plugin of your own, the way the viewer draws it:
+ * the same representations, coloring, highlights and camera, from the same
+ * options its props take. Works on any plugin - one rendering offscreen, one
+ * inside a viewer of your own - and resolves once the structure is drawn and
+ * the camera placed on it.
  *
- * mmCIF documents start with a `data_` block and name their coordinates
- * `_atom_site.`. PDB never does either, so either marker is enough. A leading
- * comment (`# ...`) before `data_` is still mmCIF.
+ * The scene clears the plugin's state to load the structure, and keeps what it
+ * draws in line with `update` from then on. It adds nothing to the plugin
+ * beyond the structure and its representations, and three color themes
+ * registered once per plugin.
  */
-declare function detectStructureFormat(text: string): StructureFormat;
+declare function applyStructureScene(plugin: PluginContext, options: StructureSceneOptions): Promise<StructureSceneHandle>;
 //#endregion
-//#region src/core/ProteinStructureViewer/utils/plddt.d.ts
-/**
- * AlphaFold's pLDDT confidence bands. Thresholds are on the 0-1 scale that
- * `plddt` values use, ascending from lowest to highest confidence.
- */
-declare const PLDDT_COLOR_SCALE: ColorScale;
+//#region src/core/ProteinStructureViewer/scene/renderStructureImage.d.ts
 /**
- * Rewrites a PDB file's B-factor column with pLDDT scores so Mol* can read them
- * off the parsed model. B-factors occupy columns 60-66 of ATOM/HETATM lines;
- * scores arrive on a 0-1 scale and are stored on the conventional 0-100 one.
- * Residues past the end of `plddtValues` fall back to a mid-confidence 50.
+ * Renders a structure to a PNG without a viewer on the page, drawn exactly as
+ * the viewer would draw it from the same options - the image a caller can show
+ * beside the interactive view, or hand to someone who cannot open one.
  *
- * A residue is identified by chain, sequence number and insertion code. The
- * code has to be part of that: `10` and `10A` are two residues, Mol* counts
- * them as two, and treating them as one here would hand every residue after
- * them its neighbour's score.
- */
-declare function injectPlddtIntoPdb(pdbData: string, plddtValues: number[]): string;
-/**
- * Rewrites an mmCIF (PDBx) file's `_atom_site.B_iso_or_equiv` column with
- * pLDDT scores so Mol* can read them off the parsed model, the same way
- * `injectPlddtIntoPdb` rewrites the PDB B-factor column. Scores arrive on a
- * 0-1 scale and are stored on the conventional 0-100 one. Residues past the
- * end of `plddtValues` fall back to a mid-confidence 50.
+ * A plugin is created for the one image, offscreen, and disposed of once it is
+ * taken, whether or not taking it succeeded. The image is `width` by `height`
+ * exactly: rendered at that size rather than scaled, and not cropped to the
+ * structure.
  *
- * If the file has no B-factor column, one is appended to the atom-site loop
- * rather than leaving the scores behind.
+ * It needs a DOM and WebGL - a browser, or headless Chromium - and rejects
+ * when there is no WebGL to render with.
  */
-declare function injectPlddtIntoMmcif(mmcifData: string, plddtValues: number[]): string;
-/**
- * Rewrites a structure file's B-factors with pLDDT scores. Dispatches to
- * `injectPlddtIntoPdb` or `injectPlddtIntoMmcif` from `format`, or from
- * detecting the format of `data` when `format` is omitted.
- */
-declare function injectPlddt(data: string, plddtValues: number[], format?: StructureFormat): string;
-//#endregion
-//#region src/core/ProteinStructureViewer/index.d.ts
-declare const _default: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<ProteinStructureViewerProps & import("react").RefAttributes<HTMLDivElement>>>;
+declare function renderStructureImage(options: RenderStructureImageOptions): Promise<Blob>;
 //#endregion
-export { StructureStat as _, injectPlddtIntoPdb as a, ChainRef as c, ProteinStructureViewerProps as d, ResidueReadout as f, StructureSelection as g, StructureDownload as h, injectPlddtIntoMmcif as i, DOWNLOAD_RESOLUTIONS as l, ResidueValueOverlay as m, PLDDT_COLOR_SCALE as n, StructureFormat as o, ResidueRef as p, injectPlddt as r, detectStructureFormat as s, _default as t, DownloadResolution as u };
+export { StructureSceneOptions as C, ViewerErrorPhase as E, StructureSceneHandle as S, StructureStat as T, SceneMode as _, CameraState as a, StructureLoadInfo as b, DownloadResolution as c, RenderStructureImageOptions as d, ResidueAddress as f, ResidueValueOverlay as g, ResidueRef as h, CameraProjection as i, LoadedStructureInfo as l, ResidueReadout as m, applyStructureScene as n, ChainRef as o, ResidueHighlight as p, CameraOrientation as r, DOWNLOAD_RESOLUTIONS as s, renderStructureImage as t, ProteinStructureViewerProps as u, StructureColorBy as v, StructureSelection as w, StructureRepresentation as x, StructureDownload as y };