@czi-sds/data-viz
Version:
2023 Science Initiative Data Visualization Component Library
308 lines (307 loc) • 11.4 kB
TypeScript
/// <reference types="react" />
import { HTMLAttributes } from "react";
import { DatasetComponentOption, ECharts, EChartsOption, ScatterSeriesOption } from "echarts";
import { DiscreteColorGeneratorOptions, TooltipTableContentProps } from "@czi-sds/components";
interface CreateChartOptionsProps {
/**
* Display reference line and axis value under mouse pointer
* https://echarts.apache.org/en/option.html#axisPointer
*/
axisPointer?: EChartsOption["axisPointer"];
/**
* The data array to be visualized
* 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:
* {
* geneIndex: 0,
* cellTypeIndex: 0,
* percentage: 0.5
* }
* and you want geneIndex to be encoded to x axis and cellTypeIndex to be encoded to y axis, then make sure your encode option is:
* encode: {
* x: 'geneIndex',
* y: 'cellTypeIndex'
* }
*/
data: DatasetComponentOption["source"];
/**
* 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
* outlier points.
* By applying the `dataZoom` prop while locking the zoom level, the chart
* efficiently renders a confined portion of the heatmap. This selective
* rendering strategy becomes especially advantageous when dealing with
* extensive datasets. Instead of rendering the entire heatmap at once,
* the chart dynamically loads and renders specific segments as the user
* scrolls through the data. This approach optimizes performance and enables
* the creation of heatmaps with large amounts of data.
* https://echarts.apache.org/en/option.html#dataZoom
*/
dataZoom?: EChartsOption["dataZoom"];
/**
* 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
* especially advantageous when dealing with extensive datasets. Instead of
* rendering the entire heatmap at once, the chart dynamically loads and renders
* specific segments as the user scrolls through the data. This approach optimizes
* performance and enables the creation of heatmaps with large amounts of data.
*
* The `height` and `width` properties are used to specify the dimensions of the
* camera view port. The `active` property is used to enable or disable the camera
* view port functionality.
*/
camera?: {
active: boolean;
height: number;
width: number;
};
/**
* Customize the style of each cell item when mouse hovers on it, such as color, border, opacity, etc.
* https://echarts.apache.org/en/option.html#series-scatter.emphasis
*/
emphasis?: ScatterSeriesOption["emphasis"];
/**
* The data for the x axis
* For example:
* [{ value: "gene1", textStyle: { color: "red" } }, "gene2", "gene3"]
*/
xAxisData: CategoryAxisData;
/**
* The data for the y axis
* For example:
* [{ value: "cellType1", textStyle: { color: "red" } }, "cellType2", "cellType3"]
*/
yAxisData: CategoryAxisData;
/**
* The width of the chart in pixels
*/
width: number;
/**
* The height of the chart in pixels
*/
height: number;
/**
* Provide a mapping of data key to x/y axis encoding
* For example, if the data is:
* {
* geneIndex: 0,
* cellTypeIndex: 0,
* percentage: 0.5
* }
* and we want to encode `geneIndex` to x axis and `cellTypeIndex` to y axis, then
* encode: {
* x: 'geneIndex',
* y: 'cellTypeIndex'
* }
* https://echarts.apache.org/en/option.html#series-scatter.encode
*/
encode?: {
x: string;
y: string;
};
/**
* Customize the style of each cell item, such as color, border, opacity, etc.
* https://echarts.apache.org/en/option.html#series-scatter.itemStyle
*/
itemStyle?: ScatterSeriesOption["itemStyle"];
/**
* The shape of the symbol.
*/
symbol?: "circle" | "rect" | "roundRect";
/**
* `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:
*
* (value: Array|number, params: Object) => number|Array
*
* The first parameter value is the value in data, and the second parameter params is the rest parameters of data item.
* https://echarts.apache.org/en/option.html#series-scatter.symbolSize
*/
symbolSize?: ScatterSeriesOption["symbolSize"];
/**
* 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()
* https://echarts.apache.org/en/option.html
*/
options?: EChartsOption;
/**
* Event listeners for the chart
* https://echarts.apache.org/en/api.html#events
*/
onEvents?: Record<string, (event: unknown, chart: ECharts) => void>;
}
type OrdinalRawValue = string | number;
/**
* (thuang): This copies echarts' CategoryAxisBaseOption["data"] type, since it's not exported
*/
type CategoryAxisData = (OrdinalRawValue | {
value: OrdinalRawValue;
/**
* (thuang): This should be echarts `TextCommonOption` type, but it's not exported
*/
textStyle?: never;
})[];
interface HeatmapChartProps extends HTMLAttributes<HTMLDivElement>, CreateChartOptionsProps {
echartsRendererMode?: "svg" | "canvas";
}
declare const _default: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<HeatmapChartProps & import("react").RefAttributes<HTMLDivElement>>>;
interface StackedBarChartDataItem {
/**
* Display name for the segment
*/
name: string;
/**
* Numeric value for the segment
*/
value: number;
/**
* Color for the segment (hex or CSS color)
* If not provided, colors will be automatically generated using cubehelix palette
*/
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"
*/
unit?: string;
/**
* Disable the item (prevents all events on the corresponding legend item and bar segment)
* @default false
*/
disabled?: boolean;
/**
* Optional tooltip to display when hovering over the segment
*/
tooltip?: TooltipTableContentProps;
}
interface StackedBarChartProps extends HTMLAttributes<HTMLDivElement> {
/**
* Title to display above the chart
*/
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"
*/
badge?: string;
/**
* Hide the badge when true
* @default false
*/
hideBadge?: boolean;
/**
* Array of data items to display in the stacked bar
*/
data: StackedBarChartDataItem[];
/**
* Width of the chart - accepts any CSS width value (e.g., "100%", "20vw", "300px", or number for pixels)
* @default 100%
*/
width?: number | string;
/**
* Height of the bar in pixels (minimum 1px)
* @default 16
*/
barHeight?: number;
/**
* Whether to show the legend below the chart
* @default true
*/
showLegend?: boolean;
/**
* Whether to show percentage values 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
* @default "percentage"
*/
legendValueFormat?: "percentage" | "count";
/**
* Array of selected item indices (controlled component)
*/
selectedIndices?: number[];
/**
* Callback when legend selection changes
*/
onSelectionChange?: (selectedIndices: number[], selectedData: StackedBarChartDataItem[]) => void;
/**
* Callback when mouse enters a bar segment
*/
onSegmentMouseEnter?: (item: StackedBarChartDataItem, index: number) => void;
/**
* Callback when mouse leaves a bar segment
*/
onSegmentMouseLeave?: (item: StackedBarChartDataItem, index: number) => void;
/**
* Callback when mouse enters a legend item
*/
onLegendItemMouseEnter?: (item: StackedBarChartDataItem, index: number) => void;
/**
* Callback when mouse leaves a legend item
*/
onLegendItemMouseLeave?: (item: StackedBarChartDataItem, index: number) => void;
/**
* Callback when a bar segment is clicked
*/
onSegmentClick?: (item: StackedBarChartDataItem, index: number) => void;
/**
* Callback when a legend item is clicked
*/
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
* @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
* @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
*/
maxAmount?: number;
/**
* Label for the remaining/unknown 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)
*/
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"
*/
unit?: string;
/**
* Options for the color generator
*/
colorGeneratorOptions?: DiscreteColorGeneratorOptions;
}
declare const StackedBarChart: (props: StackedBarChartProps) => JSX.Element;
export { HeatmapChartProps, _default, _default as HeatmapChart, StackedBarChart };
export type { StackedBarChartProps, StackedBarChartDataItem };