@czi-sds/data-viz 2.0.0 → 2.1.1

package/dist/index.esm.d.ts

@@ -1,8 +1,53 @@
 /// <reference types="react" />
 import { DatasetComponentOption, ECharts, EChartsOption, ScatterSeriesOption } from "echarts";
 import { HTMLAttributes } from "react";
-import { DiscreteColorGeneratorOptions, TooltipTableContentProps } from "@czi-sds/components";
+import { DiscreteColorGeneratorOptions, TooltipProps, TooltipTableContentProps } from "@czi-sds/components";
+import { CustomElementProperty } from "molstar/lib/mol-model-props/common/custom-element-property";
 
+//#region src/common/colorScales.d.ts
+/** RGB triplet with each channel in the range 0-255. */
+type Rgb = [number, number, number];
+/** A stop on a continuous color scale, positioned at `t` in the range 0-1. */
+interface ContinuousColorStop {
+  t: number;
+  color: string;
+}
+/**
+ * A band on a stepped color scale. `threshold` is the upper bound of the band
+ * on the normalized 0-1 value range; `label` is rendered above the band in the
+ * legend.
+ */
+interface SteppedColorStop {
+  threshold: number;
+  color: string;
+  label: string;
+}
+/**
+ * How values map to colors, both in a visualization and in its legend. A
+ * continuous scale interpolates between its stops and renders as a gradient
+ * bar; a stepped scale renders as discrete bands.
+ */
+type ColorScale = {
+  kind: "continuous";
+  stops: ContinuousColorStop[];
+} | {
+  kind: "stepped";
+  stops: SteppedColorStop[];
+};
+/**
+ * Perceptually uniform sequential scale (matplotlib's plasma), the default for
+ * value overlays.
+ */
+declare const PLASMA_COLOR_SCALE: ColorScale;
+/**
+ * Colors a raw value against a scale, normalizing it into `min`-`max` first.
+ * Returns null when the value sits at or below `min`, or when the range is
+ * degenerate, so callers can fall back to a neutral color.
+ */
+declare function sampleColorScale(scale: ColorScale, value: number, max: number, min?: number): Rgb | null;
+/** CSS `linear-gradient` spanning a continuous scale, for the legend bar. */
+declare function toCssGradient(stops: ContinuousColorStop[]): string;
+//#endregion
 //#region src/core/HeatmapChart/hooks/utils.d.ts
 interface CreateChartOptionsProps {
   /**
@@ -182,6 +227,177 @@ interface HeatmapChartProps extends HTMLAttributes<HTMLDivElement>, CreateChartO
 }
 declare const _default: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<HeatmapChartProps & import("react").RefAttributes<HTMLDivElement>>>;
 //#endregion
+//#region src/core/ProteinStructureViewer/ProteinStructureViewer.types.d.ts
+/**
+ * Per-residue values painted onto the structure in place of the default pLDDT
+ * coloring, along with the legend that describes them.
+ */
+interface ResidueValueOverlay {
+  /** 0-based residue index to value. Residues absent from the map read as 0. */
+  values: Map<number, number>;
+  /** Value mapped to the top of the color scale. */
+  max: number;
+  /**
+   * Values at or below this render in a neutral gray rather than on the scale.
+   * Values above it are normalized into `min`-`max` before being sampled, so
+   * this is also what the legend's lower tick reports.
+   * @default 0
+   */
+  min?: number;
+  /**
+   * Scale used to color residues and to draw the legend.
+   * @default PLASMA_COLOR_SCALE
+   */
+  colorScale?: ColorScale;
+  /** Legend caption, e.g. "Feature activation". */
+  label?: string;
+  /**
+   * Title of the help tooltip on the legend caption. The common case: a
+   * string is enough. Use `tooltipProps` when the tooltip needs a subtitle, a
+   * custom body, or any other SDS Tooltip prop. Overrides
+   * `tooltipProps.title` when both are set.
+   */
+  tooltip?: string;
+  /**
+   * Props forwarded to the SDS Tooltip on the legend caption. The trigger is
+   * the caption's help icon, so `children` is omitted.
+   */
+  tooltipProps?: Partial<Omit<TooltipProps, "children">>;
+  /**
+   * Label for the per-residue readout that replaces a stat slot on hover.
+   * @default "Value"
+   */
+  readoutLabel?: string;
+}
+/**
+ * A residue the user pointed at, in each of the ways a caller might need to
+ * 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`.
+ *
+ * `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
+ * name one.
+ */
+interface ResidueRef {
+  /** 0-based position in the structure, counting residues in file order. */
+  index: number;
+  /** Three-letter residue code, e.g. `"LYS"`. */
+  compId: string;
+  /** Chain the residue sits on, as named in the file. */
+  chainId: string;
+  /** Residue number as written in the file. */
+  seqId: number;
+  /** Insertion code, or `""` when the residue has none. */
+  insCode: string;
+}
+/** A whole-structure statistic shown along the bottom of the viewer. */
+interface StructureStat {
+  value: string;
+  label: string;
+}
+interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
+  /** Structure to render, as raw PDB text. */
+  pdb: 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.
+   */
+  plddt?: number[] | null;
+  /**
+   * Canvas background, as `#RRGGBB`. Defaults to the SDS theme's base
+   * background, so the canvas follows the surrounding page in both modes.
+   */
+  backgroundColor?: string;
+  /**
+   * Sequence panel background, as any CSS color. Defaults to the SDS theme's
+   * primary surface, so the panel follows the surrounding page in both modes.
+   */
+  sequenceViewerBackgroundColor?: string;
+  /**
+   * Show the orientation axes widget and the reset-camera button.
+   * @default true
+   */
+  showAxes?: boolean;
+  /**
+   * Show the sequence panel pinned along the bottom of the viewer.
+   * @default true
+   */
+  showSequenceViewer?: boolean;
+  /**
+   * Show the stats and color scale legend overlaid on the viewer.
+   * @default true
+   */
+  showLegend?: boolean;
+  /** Per-residue values that override pLDDT coloring while set. */
+  residueOverlay?: ResidueValueOverlay | null;
+  /**
+   * 0-based index of the selected residue, or null when none is selected.
+   * Controlled: selecting a residue zooms the camera in on it, and clearing the
+   * selection zooms back out to the default view.
+   */
+  selectedResidue?: number | null;
+  /**
+   * Up to three whole-structure stats shown along the bottom. A null entry
+   * reserves its column without rendering anything, so the columns never shift
+   * as values come and go.
+   */
+  stats?: (StructureStat | null)[];
+  /** Called with the clicked residue. */
+  onResidueClick?: (residue: ResidueRef) => void;
+  /**
+   * Called as the pointer moves over residues, and with `null` when it leaves
+   * the structure.
+   */
+  onResidueHover?: (residue: ResidueRef | null) => void;
+  /** Called when the user clicks empty space, clearing the selection. */
+  onSelectionClear?: () => void;
+}
+/**
+ * Per-residue readout that replaces the whole-structure stats while a residue
+ * is hovered or selected.
+ */
+interface ResidueReadout {
+  /** e.g. "PHE 17" */
+  label: string;
+  /** Residue pLDDT on a 0-1 scale, or null when unavailable. */
+  plddt: number | null;
+  /**
+   * Residue overlay value, or null when the overlay holds none for it - which
+   * is also what a structure paints neutral - or when no overlay is set.
+   */
+  value: number | null;
+}
+//#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;
+/**
+ * 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.
+ *
+ * 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;
+//#endregion
+//#region src/core/ProteinStructureViewer/index.d.ts
+declare const _default$1: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<ProteinStructureViewerProps & import("react").RefAttributes<HTMLDivElement>>>;
+//#endregion
 //#region src/core/StackedBarChart/StackedBarChart.types.d.ts
 interface StackedBarChartDataItem {
   /**
@@ -343,4 +559,4 @@ interface StackedBarChartProps extends HTMLAttributes<HTMLDivElement> {
 //#region src/core/StackedBarChart/index.d.ts
 declare const StackedBarChart: (props: StackedBarChartProps) => JSX.Element;
 //#endregion
-export { _default as HeatmapChart, HeatmapChartProps, StackedBarChart, type StackedBarChartDataItem, type StackedBarChartProps };
+export { type ColorScale, type ContinuousColorStop, _default as HeatmapChart, HeatmapChartProps, PLASMA_COLOR_SCALE, PLDDT_COLOR_SCALE, _default$1 as ProteinStructureViewer, ProteinStructureViewerProps, ResidueReadout, ResidueRef, ResidueValueOverlay, StackedBarChart, type StackedBarChartDataItem, type StackedBarChartProps, type SteppedColorStop, StructureStat, injectPlddtIntoPdb, sampleColorScale, toCssGradient };