@czi-sds/data-viz 2.2.0 → 2.3.0

package/dist/index.esm.d.ts

@@ -301,7 +301,7 @@ interface ResidueRef {
 /**
  * A chain the viewer found in the structure it loaded, reported through
  * `onChainsChange` so a consumer can label, color or hide chains by name
- * without parsing the PDB itself.
+ * without parsing the structure itself.
  *
  * `chainId` is the file's own name for the chain, the same one `ResidueRef`
  * reports, and the key every chain-keyed prop takes. A chain carrying several
@@ -392,8 +392,8 @@ interface StructureStat {
   label: string;
 }
 interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> {
-  /** Structure to render, as raw PDB text. */
-  pdb: string;
+  /** 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
@@ -436,6 +436,10 @@ interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement
    * 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.
+   *
+   * 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;
   /**
@@ -458,14 +462,13 @@ interface ProteinStructureViewerProps extends Omit<HTMLAttributes<HTMLDivElement
    */
   showChainLegend?: boolean;
   /**
-   * Stop a chain from lighting up in the 3D view while its name is pointed at,
-   * in the legend or above its grid in the sequence panel.
+   * Stop other chains from dimming in the 3D view while a chain's name is
+   * pointed at, in the legend or above its grid in the sequence panel.
    *
-   * The highlight is on by default, since on a complex it is how a reader
-   * finds out which chain is which. Turn it off where the movement is more
-   * distracting than the answer is useful - a grid of viewers a pointer
-   * crosses on its way somewhere else, or a page driving its own highlighting
-   * through `selection`.
+   * The dim is on by default, since on a complex it is how a reader finds out
+   * which chain is which. Turn it off where the movement is more distracting
+   * than the answer is useful - a grid of viewers a pointer crosses on its way
+   * somewhere else, or a page driving its own highlighting through `selection`.
    * @default false
    */
   disableChainHighlightOnHover?: boolean;
@@ -551,6 +554,24 @@ 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";
+/**
+ * Infers whether `text` is PDB or mmCIF (PDBx).
+ *
+ * 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.
+ */
+declare function detectStructureFormat(text: string): StructureFormat;
+//#endregion
 //#region src/core/ProteinStructureViewer/utils/plddt.d.ts
 /**
  * AlphaFold's pLDDT confidence bands. Thresholds are on the 0-1 scale that
@@ -569,6 +590,23 @@ declare const PLDDT_COLOR_SCALE: ColorScale;
  * 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.
+ *
+ * If the file has no B-factor column, one is appended to the atom-site loop
+ * rather than leaving the scores behind.
+ */
+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$1: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<ProteinStructureViewerProps & import("react").RefAttributes<HTMLDivElement>>>;
@@ -734,4 +772,4 @@ interface StackedBarChartProps extends HTMLAttributes<HTMLDivElement> {
 //#region src/core/StackedBarChart/index.d.ts
 declare const StackedBarChart: (props: StackedBarChartProps) => JSX.Element;
 //#endregion
-export { ChainRef, type ColorScale, type ContinuousColorStop, DOWNLOAD_RESOLUTIONS, DownloadResolution, _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, StructureDownload, StructureSelection, StructureStat, injectPlddtIntoPdb, sampleColorScale, toCssGradient };
+export { ChainRef, type ColorScale, type ContinuousColorStop, DOWNLOAD_RESOLUTIONS, DownloadResolution, _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, StructureDownload, type StructureFormat, StructureSelection, StructureStat, detectStructureFormat, injectPlddt, injectPlddtIntoMmcif, injectPlddtIntoPdb, sampleColorScale, toCssGradient };