@czi-sds/data-viz 1.0.1 → 2.0.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

@@ -6,12 +6,13 @@ import { DiscreteColorGeneratorOptions, TooltipTableContentProps } from "@czi-sd
 //#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 +28,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 +47,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 +68,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 +116,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 +141,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,6 +173,11 @@ 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>>>;
@@ -159,152 +185,157 @@ declare const _default: import("react").MemoExoticComponent<import("react").Forw
 //#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;
 }

package/dist/index.cjs.js

@@ -245,7 +245,7 @@ function generateDefaultValues(props) {
 //#endregion
 //#region src/core/HeatmapChart/hooks/useUpdateChart.ts
 const UPDATE_THROTTLE_MS = 100;
-function useUpdateChart({ axisPointer, camera, chart, data, emphasis, xAxisData, yAxisData, width, height, encode, itemStyle, symbol, symbolSize, grid, options, onEvents }) {
+function useUpdateChart({ axisPointer, camera, chart, data, dataZoom, emphasis, xAxisData, yAxisData, width, height, encode, itemStyle, symbol, symbolSize, grid, options, onEvents }) {
 	const throttledUpdateChart = (0, react.useMemo)(() => {
 		return (0, lodash.throttle)(() => {
 			if (!chart || !data || !xAxisData || !yAxisData) return;
@@ -254,6 +254,7 @@ function useUpdateChart({ axisPointer, camera, chart, data, emphasis, xAxisData,
 				axisPointer,
 				camera,
 				data,
+				dataZoom,
 				emphasis,
 				encode,
 				grid,
@@ -285,6 +286,7 @@ function useUpdateChart({ axisPointer, camera, chart, data, emphasis, xAxisData,
 		camera,
 		chart,
 		data,
+		dataZoom,
 		emphasis,
 		xAxisData,
 		yAxisData,
@@ -308,6 +310,7 @@ function useUpdateChart({ axisPointer, camera, chart, data, emphasis, xAxisData,
 		camera,
 		chart,
 		data,
+		dataZoom,
 		emphasis,
 		xAxisData,
 		yAxisData,
@@ -342,6 +345,7 @@ const _excluded$1 = [
 	"height",
 	"echartsRendererMode",
 	"camera",
+	"dataZoom",
 	"onEvents",
 	"xAxisData",
 	"yAxisData",
@@ -355,7 +359,7 @@ const _excluded$1 = [
 	"options"
 ];
 const HeatmapChart = (0, react.forwardRef)((props, ref) => {
-	const { axisPointer, width, height, echartsRendererMode = "svg", camera, onEvents, xAxisData, yAxisData, data, encode, emphasis, itemStyle, symbol, symbolSize = 5, grid, options } = props, rest = _objectWithoutProperties(props, _excluded$1);
+	const { axisPointer, width, height, echartsRendererMode = "svg", camera, dataZoom, onEvents, xAxisData, yAxisData, data, encode, emphasis, itemStyle, symbol, symbolSize = 5, grid, options } = props, rest = _objectWithoutProperties(props, _excluded$1);
 	if (!width || !height) throw Error("Heatmap must have width and height bigger than Zero!");
 	const innerRef = (0, react.useRef)(null);
 	/**
@@ -408,6 +412,7 @@ const HeatmapChart = (0, react.forwardRef)((props, ref) => {
 		camera,
 		chart,
 		data,
+		dataZoom,
 		emphasis,
 		encode,
 		grid,
@@ -660,7 +665,6 @@ const renderBarSegment = (item, options) => {
 		title: null,
 		componentSlot: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_czi_sds_components.TooltipTable, _objectSpread2({}, item.tooltip)),
 		placement: "top",
-		hasInvertedStyle: false,
 		open: hoveredIndex === item.originalIndex && !isHidden,
 		disableInteractive: true,
 		slotProps: { popper: {

package/dist/index.esm.d.ts

@@ -6,12 +6,13 @@ import { DiscreteColorGeneratorOptions, TooltipTableContentProps } from "@czi-sd
 //#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 +28,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 +47,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 +68,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 +116,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 +141,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,6 +173,11 @@ 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>>>;
@@ -159,152 +185,157 @@ declare const _default: import("react").MemoExoticComponent<import("react").Forw
 //#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;
 }

package/dist/index.esm.js

@@ -221,7 +221,7 @@ function generateDefaultValues(props) {
 //#endregion
 //#region src/core/HeatmapChart/hooks/useUpdateChart.ts
 const UPDATE_THROTTLE_MS = 100;
-function useUpdateChart({ axisPointer, camera, chart, data, emphasis, xAxisData, yAxisData, width, height, encode, itemStyle, symbol, symbolSize, grid, options, onEvents }) {
+function useUpdateChart({ axisPointer, camera, chart, data, dataZoom, emphasis, xAxisData, yAxisData, width, height, encode, itemStyle, symbol, symbolSize, grid, options, onEvents }) {
 	const throttledUpdateChart = useMemo(() => {
 		return throttle(() => {
 			if (!chart || !data || !xAxisData || !yAxisData) return;
@@ -230,6 +230,7 @@ function useUpdateChart({ axisPointer, camera, chart, data, emphasis, xAxisData,
 				axisPointer,
 				camera,
 				data,
+				dataZoom,
 				emphasis,
 				encode,
 				grid,
@@ -261,6 +262,7 @@ function useUpdateChart({ axisPointer, camera, chart, data, emphasis, xAxisData,
 		camera,
 		chart,
 		data,
+		dataZoom,
 		emphasis,
 		xAxisData,
 		yAxisData,
@@ -284,6 +286,7 @@ function useUpdateChart({ axisPointer, camera, chart, data, emphasis, xAxisData,
 		camera,
 		chart,
 		data,
+		dataZoom,
 		emphasis,
 		xAxisData,
 		yAxisData,
@@ -318,6 +321,7 @@ const _excluded$1 = [
 	"height",
 	"echartsRendererMode",
 	"camera",
+	"dataZoom",
 	"onEvents",
 	"xAxisData",
 	"yAxisData",
@@ -331,7 +335,7 @@ const _excluded$1 = [
 	"options"
 ];
 var HeatmapChart_default = memo(forwardRef((props, ref) => {
-	const { axisPointer, width, height, echartsRendererMode = "svg", camera, onEvents, xAxisData, yAxisData, data, encode, emphasis, itemStyle, symbol, symbolSize = 5, grid, options } = props, rest = _objectWithoutProperties(props, _excluded$1);
+	const { axisPointer, width, height, echartsRendererMode = "svg", camera, dataZoom, onEvents, xAxisData, yAxisData, data, encode, emphasis, itemStyle, symbol, symbolSize = 5, grid, options } = props, rest = _objectWithoutProperties(props, _excluded$1);
 	if (!width || !height) throw Error("Heatmap must have width and height bigger than Zero!");
 	const innerRef = useRef(null);
 	/**
@@ -384,6 +388,7 @@ var HeatmapChart_default = memo(forwardRef((props, ref) => {
 		camera,
 		chart,
 		data,
+		dataZoom,
 		emphasis,
 		encode,
 		grid,
@@ -635,7 +640,6 @@ const renderBarSegment = (item, options) => {
 		title: null,
 		componentSlot: /* @__PURE__ */ jsx(TooltipTable, _objectSpread2({}, item.tooltip)),
 		placement: "top",
-		hasInvertedStyle: false,
 		open: hoveredIndex === item.originalIndex && !isHidden,
 		disableInteractive: true,
 		slotProps: { popper: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@czi-sds/data-viz",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "main": "dist/index.cjs.js",
   "types": "dist/index.cjs.d.ts",
   "module": "dist/index.esm.js",
@@ -69,13 +69,12 @@
     "@types/react-dom": "^18.2.18",
     "d3-scale-chromatic": "^3.0.0",
     "react-redux": "^9.1.0",
-    "simplex-noise": "^4.0.1",
-    "style-dictionary": "^4.1.0"
+    "simplex-noise": "^4.0.1"
   },
   "dependencies": {
     "chroma-js": "^3.1.2",
     "echarts": "^6.0.0",
     "lodash": "^4.17.21"
   },
-  "gitHead": "99222cf64e2dcf5d41d771396ffba16393663bfd"
+  "gitHead": "86ab08f76d3b95b09ac6709b17f6c6d65b10d9e5"
 }