@czi-sds/data-viz 1.0.1 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # `@czi-sds/data-viz`
 
-Data visualization components for the [Science Design System (SDS)](https://sds.czi.design/), primarily built on [Apache ECharts](https://echarts.apache.org/). Shares the same Material UI v9 peer dependencies as `@czi-sds/components`.
+Data visualization components for the [Science Design System (SDS)](https://chanzuckerberg.github.io/sci-components/), primarily built on [Apache ECharts](https://echarts.apache.org/). Shares the same Material UI v9 peer dependencies as `@czi-sds/components`.
 
 Full documentation (usage, scripts, contributing) lives in the [repository README](https://github.com/chanzuckerberg/sci-components#readme).
 
@@ -36,7 +36,7 @@ The `@czi-sds/data-viz` release that ships with SDS `24.0.0` also requires Mater
 
 ## Links
 
-- [Design docs (Zeroheight)](https://sds.czi.design/)
+- [Design system documentation](https://chanzuckerberg.github.io/sci-components/)
 - [Full repo docs](https://github.com/chanzuckerberg/sci-components#readme)
 - [npm package](https://www.npmjs.com/package/@czi-sds/data-viz)
 - [ECharts documentation](https://echarts.apache.org/en/index.html)

package/dist/index.cjs.d.ts

@@ -3,15 +3,60 @@ import { HTMLAttributes } from "react";
 import { DatasetComponentOption, ECharts, EChartsOption, ScatterSeriesOption } from "echarts";
 import { DiscreteColorGeneratorOptions, TooltipTableContentProps } from "@czi-sds/components";
 
+//#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 {
   /**
-   * Display reference line and axis value under mouse pointer
+   * The crosshair following the pointer. One object applies to both axes; a
+   * two-entry array configures them separately.
    * https://echarts.apache.org/en/option.html#axisPointer
    */
   axisPointer?: EChartsOption["axisPointer"];
   /**
-   * The data array to be visualized
+   * The cells, as a flat array of objects whose fields are named by `encode`.
    * The data point object shape can be whatever you like, but it must be consistent with the `encode` option
    * For example, if the data point shape is:
    * {
@@ -27,6 +72,10 @@ interface CreateChartOptionsProps {
    */
   data: DatasetComponentOption["source"];
   /**
+   * ECharts' dataZoom configuration for that window, merged over the defaults
+   * it sets. One object applies to both axes; a two-entry array configures them
+   * separately. It reaches the chart only while `camera.active` is true.
+   *
    * The `dataZoom` prop is utilized for implementing zoom functionality within a
    * specific area of the chart. This feature empowers users to inspect data in
    * granular detail, obtain an overview of the entire dataset, or eliminate
@@ -42,6 +91,9 @@ interface CreateChartOptionsProps {
    */
   dataZoom?: EChartsOption["dataZoom"];
   /**
+   * Renders only a window of the grid, measured in cells, and lets the pointer
+   * pan it. Sizes are ignored unless `active` is true.
+   *
    * The `camera` prop is utilized for implementing camera view port functionality
    * within a specific area of the chart. This feature empowers users to render
    * a confined portion of the heatmap. This selective rendering strategy becomes
@@ -60,32 +112,36 @@ interface CreateChartOptionsProps {
     width: number;
   };
   /**
-   * Customize the style of each cell item when mouse hovers on it, such as color, border, opacity, etc.
+   * How a cell is drawn while the pointer is over it. Takes the same shape as
+   * `itemStyle`: color, border, opacity.
    * https://echarts.apache.org/en/option.html#series-scatter.emphasis
    */
   emphasis?: ScatterSeriesOption["emphasis"];
   /**
-   * The data for the x axis
+   * The categories along the x axis. A cell's encoded x value is an index into
+   * this array.
    * For example:
    * [{ value: "gene1", textStyle: { color: "red" } }, "gene2", "gene3"]
    */
   xAxisData: CategoryAxisData;
   /**
-   * The data for the y axis
+   * The categories along the y axis.
    * For example:
    * [{ value: "cellType1", textStyle: { color: "red" } }, "cellType2", "cellType3"]
    */
   yAxisData: CategoryAxisData;
   /**
-   * The width of the chart in pixels
+   * Width of the chart in pixels. Must be greater than zero; the component
+   * throws otherwise.
    */
   width: number;
   /**
-   * The height of the chart in pixels
+   * Height of the chart in pixels, under the same rule.
    */
   height: number;
   /**
-   * Provide a mapping of data key to x/y axis encoding
+   * Which fields of a data item place it on each axis. Omitting it leaves
+   * ECharts to guess from the field order.
    * For example, if the data is:
    * {
    *   geneIndex: 0,
@@ -104,15 +160,20 @@ interface CreateChartOptionsProps {
     y: string;
   };
   /**
-   * Customize the style of each cell item, such as color, border, opacity, etc.
+   * How a cell is painted. Its color accepts a callback receiving the data
+   * item, which is how a value becomes a color.
    * https://echarts.apache.org/en/option.html#series-scatter.itemStyle
    */
   itemStyle?: ScatterSeriesOption["itemStyle"];
   /**
-   * The shape of the symbol.
+   * The shape of a cell. Circles turn the grid into a dot plot, where diameter
+   * can carry a second measurement.
    */
   symbol?: "circle" | "rect" | "roundRect";
   /**
+   * Cell size in pixels: one number, a [width, height] pair, or a callback
+   * given the data item. Set it to the cell pitch for a solid grid.
+   *
    * `symbolSize` can be set to single numbers like 10, or use an array to represent width and height. For example, [20, 10] means symbol width is 20, and height is 10.
    *
    * If size of symbols needs to be different, you can set with callback function in the following format:
@@ -124,16 +185,20 @@ interface CreateChartOptionsProps {
    */
   symbolSize?: ScatterSeriesOption["symbolSize"];
   /**
+   * Where the plotting area sits inside the container. The function form
+   * receives the computed default, for insetting it without recomputing the
+   * size.
    * https://echarts.apache.org/en/option.html#grid
    */
   grid?: EChartsOption["grid"] | ((defaultOption: EChartsOption["grid"]) => EChartsOption["grid"]);
   /**
-   * The options object to be passed to echarts.setOption()
+   * Anything else ECharts understands, merged over the generated options.
    * https://echarts.apache.org/en/option.html
    */
   options?: EChartsOption;
   /**
-   * Event listeners for the chart
+   * ECharts event listeners by name. Each handler gets the raw event, whose
+   * data property is the cell, and the chart instance.
    * https://echarts.apache.org/en/api.html#events
    */
   onEvents?: Record<string, (event: unknown, chart: ECharts) => void>;
@@ -152,159 +217,330 @@ type CategoryAxisData = (OrdinalRawValue | {
 //#endregion
 //#region src/core/HeatmapChart/index.d.ts
 interface HeatmapChartProps extends HTMLAttributes<HTMLDivElement>, CreateChartOptionsProps {
+  /**
+   * Which renderer ECharts initialises with. Canvas copes better with very
+   * large grids. Changing it rebuilds the chart.
+   * @default "svg"
+   */
   echartsRendererMode?: "svg" | "canvas";
 }
 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;
+  /** Help tooltip attached to the legend caption. */
+  tooltip?: string;
+  /**
+   * 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 {
   /**
-   * Display name for the segment
+   * The segment's label in the legend, and the key the animations track it by.
+   * Must be unique within the chart.
    */
   name: string;
   /**
-   * Numeric value for the segment
+   * The quantity the segment stands for.
    */
   value: number;
   /**
-   * Color for the segment (hex or CSS color)
-   * If not provided, colors will be automatically generated using cubehelix palette
+   * Any CSS color. Without it the segment takes a generated palette color,
+   * which can shift as categories come and go.
    */
   color?: string;
   /**
-   * Unit label to display with the value in cumulative mode (e.g., "GB", "datasets", "MB")
-   * Only shown in legend when mode is "cumulative"
+   * A unit for this item's counted value, for data that mixes units across
+   * categories.
    */
   unit?: string;
   /**
-   * Disable the item (prevents all events on the corresponding legend item and bar segment)
+   * Takes the segment and its legend item out of every interaction: no hover,
+   * no tooltip, no selection.
    * @default false
    */
   disabled?: boolean;
   /**
-   * Optional tooltip to display when hovering over the segment
+   * 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> {
   /**
-   * Title to display above the chart
+   * A heading above the bar. It is also what makes room for the badge; with no
+   * title, no badge is drawn.
    */
   title?: string;
   /**
-   * Badge text to display next to the title
-   * If not provided, defaults to showing item count based on selection:
-   * - No selection: total count (e.g., "5")
-   * - Partial selection: selected count (e.g., "3 of 5")
-   * - All selected: "All"
+   * Overrides the badge text, which otherwise counts the data and the selection
+   * ("7", or "3 of 7").
    */
   badge?: string;
   /**
-   * Hide the badge when true
+   * Removes the badge, leaving the title on its own.
    * @default false
    */
   hideBadge?: boolean;
   /**
-   * Array of data items to display in the stacked bar
+   * The segments, in the order they are drawn.
    */
   data: StackedBarChartDataItem[];
   /**
-   * Width of the chart - accepts any CSS width value (e.g., "100%", "20vw", "300px", or number for pixels)
+   * 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 (minimum 1px)
+   * Height of the bar in pixels. Values below 1 are clamped to 1, so the bar
+   * cannot disappear.
    * @default 16
    */
   barHeight?: number;
   /**
-   * Whether to show the legend below the chart
+   * 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;
   /**
-   * Whether to show percentage values in the legend
+   * Shows each item's value beside its name in the legend.
    * @default true
    */
   showLegendValues?: boolean;
   /**
-   * Format for legend values
-   * - "percentage": Shows percentage of the item in the bar chart (e.g., "20%")
-   * - "count": Shows the count from the data object with the unit defined by the unit prop
+   * "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";
   /**
-   * Array of selected item indices (controlled component)
+   * Indices into data that are currently selected. The chart is controlled: it
+   * draws this and never changes it.
    */
   selectedIndices?: number[];
   /**
-   * Callback when legend selection changes
+   * Called with the next selection when a segment or legend item is clicked.
+   * Without it, clicking selects nothing.
    */
   onSelectionChange?: (selectedIndices: number[], selectedData: StackedBarChartDataItem[]) => void;
   /**
-   * Callback when mouse enters a bar segment
+   * 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;
   /**
-   * Callback when mouse leaves a bar segment
+   * Called when the pointer leaves a segment.
    */
   onSegmentMouseLeave?: (item: StackedBarChartDataItem, index: number) => void;
   /**
-   * Callback when mouse enters a legend item
+   * Called when the pointer enters a legend item.
    */
   onLegendItemMouseEnter?: (item: StackedBarChartDataItem, index: number) => void;
   /**
-   * Callback when mouse leaves a legend item
+   * Called when the pointer leaves a legend item.
    */
   onLegendItemMouseLeave?: (item: StackedBarChartDataItem, index: number) => void;
   /**
-   * Callback when a bar segment is clicked
+   * Fires on a segment click, alongside any selection change rather than
+   * instead of it.
    */
   onSegmentClick?: (item: StackedBarChartDataItem, index: number) => void;
   /**
-   * Callback when a legend item is clicked
+   * The same, for a click on a legend item.
    */
   onLegendItemClick?: (item: StackedBarChartDataItem, index: number) => void;
   /**
-   * Behavior to apply when items are selected
-   * - "dim": Non-selected segments become semi-transparent (20% opacity)
-   * - "hide": Non-selected segments are hidden from the bar chart
+   * 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";
   /**
-   * Chart mode - controls how segments are calculated
-   * - "proportional": Segments fill entire bar (100%), proportional to their values
-   * - "cumulative": Segments sized based on actual values relative to maxAmount
+   * Whether the bar shows a breakdown of the data (segments always fill it) or
+   * progress towards maxAmount.
    * @default "proportional"
    */
   mode?: "proportional" | "cumulative";
   /**
-   * Maximum amount for the bar (used only in "cumulative" mode)
-   * If not provided, defaults to sum of all values (no remaining segment)
-   * If provided and sum < maxAmount, shows gray "remaining" segment
+   * 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;
   /**
-   * Label for the remaining/unknown segment in cumulative mode
+   * Name of the grey gap segment in cumulative mode.
    * @default "Remaining"
    */
   remainingLabel?: string;
   /**
-   * Unit to display with the remaining segment value in cumulative mode
-   * If not provided, uses the unit from the first data item (if available)
+   * A unit for the Remaining segment's value alone.
    */
   remainingUnit?: string;
   /**
-   * Global unit to display with values in cumulative mode (e.g., "GB", "datasets", "K")
-   * Individual data items can override this with their own unit property
-   * Only shown when mode is "cumulative"
+   * The unit appended to counted values, for items that do not carry one of
+   * their own.
    */
   unit?: string;
   /**
-   * Options for the color generator
+   * Tunes the generated palette (start hue, rotations, lightness range, gamma).
+   * Items with their own color are untouched by it.
    */
   colorGeneratorOptions?: DiscreteColorGeneratorOptions;
 }
@@ -312,4 +548,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 };