Merge pull request #643 from adobe/stackedBarDimensionHoverArea

Dimension Area Tooltips for Stacked Bars

Author: marshallpete

packages/constants/constants.ts

@@ -155,6 +155,9 @@ export const HOVER_SIZE = 3000;
 export const HOVER_SHAPE_COUNT = 3;
 export const HOVER_SHAPE = 'diamond';
 
+// tooltip constants
+export const DIMENSION_HOVER_AREA = 'dimensionHoverArea';
+
 //SVG Paths
 export const ROUNDED_SQUARE_PATH =
   'M -0.55 -1 h 1.1 a 0.45 0.45 0 0 1 0.45 0.45 v 1.1 a 0.45 0.45 0 0 1 -0.45 0.45 h -1.1 a 0.45 0.45 0 0 1 -0.45 -0.45 v -1.1 a 0.45 0.45 0 0 1 0.45 -0.45 z';

packages/docs/docs/api/interactivity/ChartTooltip.md

@@ -33,6 +33,37 @@ const data = [
 </Chart>;
 ```
 
+### Tooltip with dimension area targeting (stacked bars)
+
+```jsx
+<Chart data={data}>
+  <Bar type="stacked">
+    <ChartTooltip targets={['item']}>
+      {(datum) => (
+        <div>
+          <div>Series: {datum.series}</div>
+          <div>Value: {datum.value}</div>
+        </div>
+      )}
+    </ChartTooltip>
+    <ChartTooltip targets={['dimensionArea']}>
+      {(datum) => (
+        <div>
+          <div>Dimension: {datum.dimension}</div>
+          {datum.rscGroupData?.map((item, index) => (
+            <div key={index}>
+              {item.series}: {item.value}
+            </div>
+          ))}
+        </div>
+      )}
+    </ChartTooltip>
+  </Bar>
+</Chart>
+```
+
+In this example, two separate tooltips are defined: one for hovering over the actual bar marks (`item`) that shows individual segment data, and another for hovering anywhere within the dimension area (`dimensionArea`) that shows aggregated data across the dimension. The datum shape differs between these targets, so they require separate tooltip implementations.
+
 ## Props
 
 <table>
@@ -63,5 +94,11 @@ const data = [
       <td>'item'</td>
       <td>Specifies which marks on the parent should be highlighted on hover. For example if set to `dimension`, when a user hovers a mark, it will highlight all marks with the same dimension value.<br/>If an array of strings is provided, each of those key will be used to find other marks that match and should be highlighted. For example, if `highlightBy` is set to `['company', 'quarter']`, when a mark is hovered, all marks with the same company and quarter values will be highlighted.<br/>If `highlightBy` uses `series`, `dimension`, or an array of string, the `item` passed to the tooltip callback will include the `rscGroupData` key. This will have the data for all highlighted marks so that your tooltip can provide info for all the highlighted marks, not just the hovered mark.</td>
     </tr>
+    <tr>
+      <td>targets</td>
+      <td>('dimensionArea' | 'item')[]</td>
+      <td>['item']</td>
+      <td>Specifies which areas of the chart should trigger the tooltip. `item` will trigger the tooltip when hovering over the actual data mark. `dimensionArea` will trigger the tooltip when hovering anywhere within the dimension area (e.g., for stacked bars, hovering anywhere along the dimension slice).<br/><strong>Note:</strong> Currently only active for stacked bar charts.</td>
+    </tr>
   </tbody>
 </table>

packages/react-spectrum-charts/src/components/ChartTooltip/ChartTooltip.tsx

@@ -14,7 +14,7 @@ import { FC } from 'react';
 import { ChartTooltipProps } from '../../types';
 
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-const ChartTooltip: FC<ChartTooltipProps> = ({ children, excludeDataKeys, highlightBy = 'item' }) => {
+const ChartTooltip: FC<ChartTooltipProps> = ({ children, excludeDataKeys, highlightBy = 'item', targets = ['item'] }) => {
   return null;
 };
 

packages/react-spectrum-charts/src/hooks/useTooltipInteractions.tsx

@@ -14,7 +14,7 @@ import { FC } from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { Position, Options as TooltipOptions } from 'vega-tooltip';
 
-import { COMPONENT_NAME, FILTERED_TABLE, GROUP_DATA, GROUP_ID } from '@spectrum-charts/constants';
+import { COMPONENT_NAME, DIMENSION_HOVER_AREA, FILTERED_TABLE, GROUP_DATA, GROUP_ID } from '@spectrum-charts/constants';
 import { ColorScheme, LegendDescription, TooltipAnchor, TooltipPlacement } from '@spectrum-charts/vega-spec-builder';
 
 import { useChartContext } from '../context/RscChartContext';
@@ -53,6 +53,21 @@ const useTooltipsInteractions = (props: RscChartProps, sanitizedChildren: ChartC
           />
         );
       }
+      if (value[COMPONENT_NAME]?.endsWith(DIMENSION_HOVER_AREA)) {
+        const tooltipName = value[COMPONENT_NAME].replace(`_${DIMENSION_HOVER_AREA}`, '');
+        const tooltip = tooltips.find((t) => t.name === tooltipName && t.targets?.includes('dimensionArea'));
+        if (!tooltip) return '';
+
+        const tableData = chartView.current?.data(FILTERED_TABLE);
+        const dimension = value.dimension;
+        value[GROUP_DATA] = tableData?.filter((d) => d[dimension] === value[dimension]);
+
+        return renderToStaticMarkup(
+          <div className="rsc-tooltip" data-testid="rsc-tooltip">
+            {tooltip.callback(value)}
+          </div>
+        );
+      }
       // get the correct tooltip to render based on the hovered item
       const tooltip = tooltips.find((t) => t.name === value[COMPONENT_NAME]);
       if (tooltip?.callback && !('index' in value)) {

packages/react-spectrum-charts/src/hooks/useTooltips.tsx

@@ -26,6 +26,7 @@ export type TooltipDetail = {
   name: string;
   callback: TooltipHandler;
   highlightBy: ChartTooltipProps['highlightBy'];
+  targets: ChartTooltipProps['targets'];
   width?: number;
 };
 
@@ -43,6 +44,7 @@ export default function useTooltips(children: ChartChildElement[]): TooltipDetai
           name: tooltip.name,
           callback: tooltip.element.props.children,
           highlightBy: tooltip.element.props.highlightBy,
+          targets: tooltip.element.props.targets,
         })) as TooltipDetail[],
     [tooltipElements]
   );

packages/react-spectrum-charts/src/stories/components/Bar/StackedBar.story.tsx

@@ -13,10 +13,11 @@ import React, { ReactElement, createElement } from 'react';
 
 import { StoryFn } from '@storybook/react';
 
+import { GROUP_DATA, MARK_ID } from '@spectrum-charts/constants';
 import { SpectrumColor } from '@spectrum-charts/vega-spec-builder';
 
 import { Chart } from '../../../Chart';
-import { Annotation, Axis, Bar, Legend } from '../../../components';
+import { Annotation, Axis, Bar, ChartTooltip, Legend } from '../../../components';
 import useChartProps from '../../../hooks/useChartProps';
 import { bindWithProps } from '../../../test-utils';
 import { BarProps } from '../../../types';
@@ -75,6 +76,42 @@ const NegativeBarStory: StoryFn<typeof Bar> = (args): ReactElement => {
   );
 };
 
+const DimensionAreaStory: StoryFn<typeof Bar> = (args): ReactElement => {
+  const chartProps = useChartProps({ data: barSeriesData, width: 800, height: 600 });
+  return (
+    <Chart {...chartProps}>
+      <Axis position={args.orientation === 'horizontal' ? 'left' : 'bottom'} baseline title="Browser" />
+      <Axis position={args.orientation === 'horizontal' ? 'bottom' : 'left'} grid title="Downloads" />
+      <Bar {...args}>
+        <ChartTooltip>
+          {(datum) => {
+            return <>
+              <div>Operating system: {datum.operatingSystem}</div>
+              <div>Browser: {datum.browser}</div>
+              <div>Downloads: {datum.value}</div>
+            </>
+          }}
+        </ChartTooltip>
+        <ChartTooltip targets={['dimensionArea']}>
+          {(datum) => {
+            return (
+              <>
+                <div style={{ fontWeight: 'bold' }}>{datum.browser} Downloads</div>
+                {datum[GROUP_DATA]?.map((d) => (
+                  <div key={d[MARK_ID]}>
+                    {d.operatingSystem}: {d.value}
+                  </div>
+                ))}
+              </>
+            );
+          }}
+        </ChartTooltip>
+      </Bar>
+      <Legend title="Operating system" highlight />
+    </Chart>
+  );
+};
+
 const defaultProps: BarProps = {
   dimension: 'browser',
   order: 'order',
@@ -117,4 +154,9 @@ StackedBarWithUTCDatetimeFormat.args = {
   dimensionDataType: 'time',
 };
 
-export { Basic, NegativeStack, WithBarLabels, OnClick, StackedBarWithUTCDatetimeFormat };
+const TooltipOnDimensionArea = bindWithProps(DimensionAreaStory);
+TooltipOnDimensionArea.args = {
+  ...defaultProps,
+};
+
+export { Basic, NegativeStack, WithBarLabels, OnClick, StackedBarWithUTCDatetimeFormat, TooltipOnDimensionArea };

packages/react-spectrum-charts/src/stories/components/Bar/StackedBar.test.tsx

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+import { DIMENSION_HOVER_AREA, FADE_FACTOR } from '@spectrum-charts/constants';
+import { findAllMarksByGroupName, findChart, hoverNthElement, render, screen, unhoverNthElement, within } from '../../../test-utils';
+import { TooltipOnDimensionArea } from './StackedBar.story';
+
+describe('TooltipOnDimensionArea', () => {
+  test('hovering dimension area should apply highlight styling and show tooltip', async () => {
+    render(<TooltipOnDimensionArea {...TooltipOnDimensionArea.args} />);
+    const chart = await findChart();
+    expect(chart).toBeInTheDocument();
+    const dimensionAreas = await findAllMarksByGroupName(chart, `bar0_${DIMENSION_HOVER_AREA}`);
+    const bars = await findAllMarksByGroupName(chart, 'bar0');
+    expect(dimensionAreas).toHaveLength(3);
+    
+    // hovering dimension area should apply highlight styling and show tooltip
+    await hoverNthElement(dimensionAreas, 0);
+    const tooltip = await screen.findByTestId('rsc-tooltip');
+    expect(tooltip).toBeInTheDocument();
+    expect(within(tooltip).getByText('Chrome Downloads')).toBeInTheDocument();
+    expect(bars[0]).toHaveAttribute('opacity', `1`);
+    expect(bars[4]).toHaveAttribute('opacity', `${FADE_FACTOR}`);
+    
+    await unhoverNthElement(dimensionAreas, 0);
+
+    // hovering bar should do normal stuff
+    await hoverNthElement(bars, 4);
+    expect(bars[0]).toHaveAttribute('opacity', `${FADE_FACTOR}`);
+    expect(bars[4]).toHaveAttribute('opacity', `1`);
+  });
+});

packages/react-spectrum-charts/src/stories/components/MetricRange/MetricRange.story.tsx

@@ -78,7 +78,7 @@ const MetricRangeWithPopoverStory: StoryFn<typeof MetricRange> = (args): ReactEl
   );
 };
 
-const MetricRangescaleAxisToFitStory: StoryFn<typeof MetricRange> = (args): ReactElement => {
+const MetricRangeScaleAxisToFitStory: StoryFn<typeof MetricRange> = (args): ReactElement => {
   const chartProps = useChartProps({
     ...defaultChartProps,
     data: workspaceTrendsDataWithExtremeMetricRange,
@@ -146,7 +146,7 @@ WithPopover.args = {
   displayOnHover: true,
 };
 
-const ScaleAxisToFit = bindWithProps(MetricRangescaleAxisToFitStory);
+const ScaleAxisToFit = bindWithProps(MetricRangeScaleAxisToFitStory);
 ScaleAxisToFit.args = {
   lineType: 'shortDash',
   lineWidth: 'S',

packages/vega-spec-builder/src/bar/barSpecBuilder.test.ts

@@ -30,7 +30,9 @@ import {
   DEFAULT_METRIC,
   DEFAULT_OPACITY_RULE,
   DEFAULT_SECONDARY_COLOR,
+  DIMENSION_HOVER_AREA,
   FILTERED_TABLE,
+  HOVERED_ITEM,
   LINE_TYPE_SCALE,
   MARK_ID,
   OPACITY_SCALE,
@@ -471,6 +473,14 @@ describe('barSpecBuilder', () => {
         const lastRscSeriesIdSignal = signals.find(getLastRscSeriesIdSignal);
         expect(lastRscSeriesIdSignal).toBeUndefined();
       });
+
+      test('should add dimension hover area signal if has tooltip with dimension area target', () => {
+        const signals = addSignals(defaultSignals, {
+          ...defaultBarOptions,
+          chartTooltips: [{ targets: ['dimensionArea'] }],
+        });
+        expect(signals.find((signal) => signal.name === `${defaultBarOptions.name}_${DIMENSION_HOVER_AREA}_${HOVERED_ITEM}`)).toBeDefined();
+      });
     });
   });
 

packages/vega-spec-builder/src/bar/barSpecBuilder.ts

@@ -17,6 +17,7 @@ import {
   DEFAULT_CATEGORICAL_DIMENSION,
   DEFAULT_COLOR_SCHEME,
   DEFAULT_METRIC,
+  DIMENSION_HOVER_AREA,
   FILTERED_TABLE,
   LAST_RSC_SERIES_ID,
   LINE_TYPE_SCALE,
@@ -30,7 +31,7 @@ import {
 import { toCamelCase } from '@spectrum-charts/utils';
 
 import { addPopoverData, getPopovers } from '../chartPopover/chartPopoverUtils';
-import { addTooltipData, addTooltipSignals } from '../chartTooltip/chartTooltipUtils';
+import { addTooltipData, addTooltipSignals, hasTooltipWithDimensionAreaTarget } from '../chartTooltip/chartTooltipUtils';
 import { addTimeTransform, getTableData, getTransformSort } from '../data/dataUtils';
 import { getInteractiveMarkName } from '../marks/markUtils';
 import {
@@ -167,6 +168,9 @@ export const addSignals = produce<Signal[], [BarSpecOptions]>((signals, options)
     return;
   }
   addHoveredItemSignal(signals, name, undefined, 1, chartTooltips[0]?.excludeDataKeys);
+  if (hasTooltipWithDimensionAreaTarget(chartTooltips)) {
+    addHoveredItemSignal(signals, `${name}_${DIMENSION_HOVER_AREA}`);
+  }
   addTooltipSignals(signals, options);
   setTrendlineSignals(signals, options);
 });