@czi-sds/data-viz 2.2.0 → 2.4.0

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

@@ -0,0 +1,391 @@
+/// <reference types="react" />
+import { t as ColorScale } from "./colorScales.esm.js";
+import { HTMLAttributes } from "react";
+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";
+
+//#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 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 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
+ * symmetry operators appears once, under the first.
+ *
+ * Describes the chain's polymer. The ligands and ions sitting on it are drawn
+ * and are hidden and selected with it, but are not counted here or spanned by
+ * the range below - they are no part of the sequence. A chain holding nothing
+ * but heteroatoms is left out altogether, having no sequence to describe.
+ */
+interface ChainRef {
+  /** Chain as named in the file (`auth_asym_id`), e.g. `"A"`. */
+  chainId: string;
+  /** Chain as the sequence panel captions it. */
+  label: string;
+  /** Lowest 0-based residue index of the chain's polymer. */
+  startIndex: number;
+  /** Highest 0-based residue index of the chain's polymer. */
+  endIndex: number;
+  /** Polymer residues the chain holds. */
+  residueCount: number;
+}
+/**
+ * What is selected, in the two ways a caller might say it. `null` selects
+ * nothing.
+ *
+ * The two combine: `{ chains: ["A"], residues: [150] }` takes all of chain A
+ * plus one residue elsewhere. `chains` is kept as named rather than expanded
+ * into indices, so a whole-chain selection survives a round trip through a
+ * consumer's state at its original size.
+ */
+interface StructureSelection {
+  /**
+   * 0-based residue indices, counting residues in file order across the whole
+   * structure - the same index `plddt` and `residueOverlay` are keyed by.
+   */
+  residues?: number[];
+  /** Whole chains by `chainId`, each standing for every residue on it. */
+  chains?: string[];
+}
+/**
+ * How large a downloaded image is, in pixels.
+ *
+ * Named rather than given as dimensions because the aspect is Mol*'s to
+ * choose: each of these is one of its own presets, and a size picked here
+ * would have to be reconciled with the canvas the image is rendered from.
+ */
+type DownloadResolution = "low" | "medium" | "high" | "maximum";
+/** Pixel dimensions each resolution produces, for documentation and labels. */
+declare const DOWNLOAD_RESOLUTIONS: Record<DownloadResolution, string>;
+/**
+ * Turns on the capture button under the reset-camera control, and says what it
+ * should produce. Omit it and no button is drawn.
+ *
+ * The image is rendered fresh at the size asked for rather than scaled up from
+ * the canvas, so a high resolution costs time rather than sharpness - which is
+ * why the default sits in the middle rather than at the top.
+ */
+interface StructureDownload {
+  /**
+   * Size of the image. See `DOWNLOAD_RESOLUTIONS` for the pixel dimensions.
+   * @default "medium"
+   */
+  resolution?: DownloadResolution;
+  /**
+   * Background behind the structure, as `#RRGGBB`. Omit for a transparent
+   * one, which is what a figure usually wants - the viewer's own canvas color
+   * is deliberately not inherited, since a screenshot tends to outlive the
+   * theme it was taken under.
+   */
+  backgroundColor?: string;
+  /**
+   * Draw the orientation axes into the image. Independent of `showAxes`, which
+   * is about the view rather than the capture: the widget orients a reader who
+   * can turn the structure, and earns its place less in a still.
+   * @default false
+   */
+  showAxes?: boolean;
+  /**
+   * Name for the downloaded file, without an extension. Defaults to the one
+   * Mol* derives from the loaded structure.
+   */
+  filename?: 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 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.
+   */
+  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;
+  /**
+   * Adds a capture button beneath the reset-camera control, which downloads a
+   * PNG of the structure as it currently stands. Omit for no button.
+   */
+  download?: StructureDownload | null;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * Chains hidden from the 3D view, by `chainId`. Leave undefined to let the
+   * viewer own visibility itself, which is what the chain legend's toggles
+   * drive; passing it takes that over, and the toggles then only report.
+   */
+  hiddenChains?: string[];
+  /**
+   * 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.
+   */
+  chainColors?: Record<string, string>;
+  /**
+   * Show the chain legend, which lists each chain with its color and a
+   * visibility toggle. Ignored on a single-chain structure, where there is
+   * nothing to tell apart or hide.
+   * @default true
+   */
+  showChainLegend?: boolean;
+  /**
+   * 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 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;
+  /**
+   * Mol* plugin spec laid over the viewer's own, which is how the whole of
+   * Mol*'s configuration is reachable without a prop here for each setting.
+   * Anything named here wins, so `canvas3d.postprocessing`, a `PluginConfig`
+   * item, or `layout.initial` can all be set to something other than the
+   * default the viewer picked.
+   *
+   * List-valued keys - `behaviors`, `config`, `actions`, `animations`,
+   * `customFormats`, `customParamEditors` - are appended to rather than
+   * replaced. For `config` that is what lets an entry override the viewer's,
+   * since Mol* reads the list in order. It also means a behavior cannot be
+   * taken away: the ones the viewer drops stay dropped, and the ones it keeps
+   * cannot be removed from here.
+   *
+   * Read once, when the plugin is created, except for `canvas3d`, which is
+   * re-applied whenever it changes. Creating the plugin throws away the camera,
+   * so the rest is deliberately not reactive.
+   */
+  molstarSpec?: Partial<PluginUISpec>;
+  /**
+   * 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 with the new selection whenever the user makes one - clicking a
+   * residue, dragging across the sequence, clicking a chain caption - and with
+   * `null` when they click empty space to clear it.
+   *
+   * A whole-chain selection arrives as `{ chains: [id] }` rather than as every
+   * index on it, so echoing it straight back into `selection` costs nothing.
+   */
+  onSelectionChange?: (selection: StructureSelection | null) => void;
+  /**
+   * Called with the chains found in the structure, whenever a structure is
+   * loaded. Fires with `[]` when the structure holds none.
+   */
+  onChainsChange?: (chains: ChainRef[]) => 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
+   * viewer's own state without owning it.
+   */
+  onChainVisibilityChange?: (hiddenChains: string[]) => void;
+}
+/**
+ * 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
+ * whole-chain selection report through this too, as a mean over what they
+ * cover.
+ */
+interface ResidueReadout {
+  /** e.g. "PHE 17", "Chain A", or "24 residues". */
+  label: string;
+  /**
+   * pLDDT on a 0-1 scale, or null when unavailable. The mean across the
+   * residues covered when there is more than one, ignoring those without a
+   * score.
+   */
+  plddt: number | null;
+  /**
+   * Overlay value, or null when the overlay holds none - which is also what a
+   * structure paints neutral - or when no overlay is set. The mean across the
+   * residues covered when there is more than one, ignoring those the overlay
+   * says nothing about.
+   */
+  value: number | null;
+  /**
+   * Residues the readout covers, which is what makes the numbers above means
+   * rather than readings. 1 for a single residue.
+   */
+  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
+ * `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;
+/**
+ * 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: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<ProteinStructureViewerProps & import("react").RefAttributes<HTMLDivElement>>>;
+//#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 };

package/dist/shared/index3.cjs.d.ts

@@ -0,0 +1,166 @@
+/// <reference types="react" />
+import { HTMLAttributes } from "react";
+import { DiscreteColorGeneratorOptions, TooltipTableContentProps } from "@czi-sds/components";
+
+//#region src/core/StackedBarChart/StackedBarChart.types.d.ts
+interface StackedBarChartDataItem {
+  /**
+   * The segment's label in the legend, and the key the animations track it by.
+   * Must be unique within the chart.
+   */
+  name: string;
+  /**
+   * The quantity the segment stands for.
+   */
+  value: number;
+  /**
+   * Any CSS color. Without it the segment takes a generated palette color,
+   * which can shift as categories come and go.
+   */
+  color?: string;
+  /**
+   * A unit for this item's counted value, for data that mixes units across
+   * categories.
+   */
+  unit?: string;
+  /**
+   * Takes the segment and its legend item out of every interaction: no hover,
+   * no tooltip, no selection.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Content for a TooltipTable shown above the segment on hover. Use it for the
+   * breakdown behind the number; a segment without it has no tooltip.
+   */
+  tooltip?: TooltipTableContentProps;
+}
+interface StackedBarChartProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * A heading above the bar. It is also what makes room for the badge; with no
+   * title, no badge is drawn.
+   */
+  title?: string;
+  /**
+   * Overrides the badge text, which otherwise counts the data and the selection
+   * ("7", or "3 of 7").
+   */
+  badge?: string;
+  /**
+   * Removes the badge, leaving the title on its own.
+   * @default false
+   */
+  hideBadge?: boolean;
+  /**
+   * The segments, in the order they are drawn.
+   */
+  data: StackedBarChartDataItem[];
+  /**
+   * Any CSS width; a number is read as pixels. It sets the width of the whole
+   * chart, legend included.
+   * @default 100%
+   */
+  width?: number | string;
+  /**
+   * Height of the bar in pixels. Values below 1 are clamped to 1, so the bar
+   * cannot disappear.
+   * @default 16
+   */
+  barHeight?: number;
+  /**
+   * Draws the legend below the bar. It is the only place segment names appear,
+   * and the only part of the chart a keyboard can reach.
+   * @default true
+   */
+  showLegend?: boolean;
+  /**
+   * Shows each item's value beside its name in the legend.
+   * @default true
+   */
+  showLegendValues?: boolean;
+  /**
+   * "percentage" shows the segment's share of the bar, rounded. "count" shows
+   * the raw value followed by the item's unit, or the chart's unit if the item
+   * has none.
+   * @default "percentage"
+   */
+  legendValueFormat?: "percentage" | "count";
+  /**
+   * Indices into data that are currently selected. The chart is controlled: it
+   * draws this and never changes it.
+   */
+  selectedIndices?: number[];
+  /**
+   * Called with the next selection when a segment or legend item is clicked.
+   * Without it, clicking selects nothing.
+   */
+  onSelectionChange?: (selectedIndices: number[], selectedData: StackedBarChartDataItem[]) => void;
+  /**
+   * Called when the pointer enters a segment. The chart already syncs its own
+   * hover highlight between bar and legend, so this is for driving something
+   * outside it.
+   */
+  onSegmentMouseEnter?: (item: StackedBarChartDataItem, index: number) => void;
+  /**
+   * Called when the pointer leaves a segment.
+   */
+  onSegmentMouseLeave?: (item: StackedBarChartDataItem, index: number) => void;
+  /**
+   * Called when the pointer enters a legend item.
+   */
+  onLegendItemMouseEnter?: (item: StackedBarChartDataItem, index: number) => void;
+  /**
+   * Called when the pointer leaves a legend item.
+   */
+  onLegendItemMouseLeave?: (item: StackedBarChartDataItem, index: number) => void;
+  /**
+   * Fires on a segment click, alongside any selection change rather than
+   * instead of it.
+   */
+  onSegmentClick?: (item: StackedBarChartDataItem, index: number) => void;
+  /**
+   * The same, for a click on a legend item.
+   */
+  onLegendItemClick?: (item: StackedBarChartDataItem, index: number) => void;
+  /**
+   * What a selection does to the unselected segments: fade them to 20% opacity,
+   * or drop them from the bar and let the rest take the space.
+   * @default "dim"
+   */
+  selectionBehavior?: "dim" | "hide";
+  /**
+   * Whether the bar shows a breakdown of the data (segments always fill it) or
+   * progress towards maxAmount.
+   * @default "proportional"
+   */
+  mode?: "proportional" | "cumulative";
+  /**
+   * Cumulative mode only. The value the full bar represents. Any difference
+   * between it and the sum of the data is drawn as the Remaining segment.
+   */
+  maxAmount?: number;
+  /**
+   * Name of the grey gap segment in cumulative mode.
+   * @default "Remaining"
+   */
+  remainingLabel?: string;
+  /**
+   * A unit for the Remaining segment's value alone.
+   */
+  remainingUnit?: string;
+  /**
+   * The unit appended to counted values, for items that do not carry one of
+   * their own.
+   */
+  unit?: string;
+  /**
+   * Tunes the generated palette (start hue, rotations, lightness range, gamma).
+   * Items with their own color are untouched by it.
+   */
+  colorGeneratorOptions?: DiscreteColorGeneratorOptions;
+}
+//#endregion
+//#region src/core/StackedBarChart/index.d.ts
+declare const StackedBarChart: (props: StackedBarChartProps) => JSX.Element;
+//#endregion
+export { StackedBarChartDataItem as n, StackedBarChartProps as r, StackedBarChart as t };