feat(highlight): Add support to configure dimmed (unhighlight) colors for Bar and Partition charts

e2e/tests/flame_stories.test.ts

@@ -38,4 +38,24 @@ test.describe('Flame stories', () => {
       },
     );
   });
+
+  test('should dim icicle chart (linear renderer) on legend hover - fill dimming', async ({ page }) => {
+    const action = async () => {
+      await page.locator('.echLegendItem').first().hover();
+    };
+    await common.expectChartAtUrlToMatchScreenshot(page)(
+      `http://localhost:9001/?path=/story/flame-alpha--icicle-chart&globals=theme:light&knob-Clip%20text%20%28use%20linear%20renderer%29=true`,
+      { action },
+    );
+  });
+
+  test('should dim icicle chart (linear renderer) on legend hover - opacity dimming', async ({ page }) => {
+    const action = async () => {
+      await page.locator('.echLegendItem').first().hover();
+    };
+    await common.expectChartAtUrlToMatchScreenshot(page)(
+      `http://localhost:9001/?path=/story/flame-alpha--icicle-chart&globals=theme:light&knob-Clip%20text%20%28use%20linear%20renderer%29=true&knob-Use%20opacity-only%20dimming=true`,
+      { action },
+    );
+  });
 });

e2e/tests/partition_stories.test.ts

@@ -106,4 +106,26 @@ test.describe('Axis stories', () => {
       { left: 300, top: 100 },
     );
   });
+
+  eachTheme.describe(({ theme, urlParam }) => {
+    test(`should dim slices on legend hover - sunburst - ${theme}`, async ({ page }) => {
+      const action = async () => {
+        await common.moveMouseRelativeToDOMElement(page)({ left: 5, top: 5 }, '.echLegendItem');
+      };
+      await common.expectChartAtUrlToMatchScreenshot(page)(
+        `http://localhost:9001/?path=/story/legend--piechart&${urlParam}&knob-Partition Layout=sunburst&knob-flatLegend=true&knob-legendMaxDepth=2`,
+        { action },
+      );
+    });
+
+    test(`should dim slices on legend hover - treemap - ${theme}`, async ({ page }) => {
+      const action = async () => {
+        await common.moveMouseRelativeToDOMElement(page)({ left: 5, top: 5 }, '.echLegendItem');
+      };
+      await common.expectChartAtUrlToMatchScreenshot(page)(
+        `http://localhost:9001/?path=/story/legend--piechart&${urlParam}&knob-Partition Layout=treemap&knob-flatLegend=true&knob-legendMaxDepth=2`,
+        { action },
+      );
+    });
+  });
 });

e2e/tests/stylings_stories.test.ts

@@ -9,7 +9,7 @@
 import { test } from '@playwright/test';
 
 import { SeriesType } from '../constants';
-import { pwEach } from '../helpers';
+import { eachTheme, pwEach } from '../helpers';
 import { common } from '../page_objects';
 
 test.describe('Stylings stories', () => {
@@ -89,4 +89,58 @@ test.describe('Stylings stories', () => {
       { top: 150, right: 150 },
     );
   });
+
+  test.describe('Dimmed highlight style', () => {
+    eachTheme.describe(({ theme, urlParam }) => {
+      test(`should dim XY chart series on Bars 2 legend hover - ${theme}`, async ({ page }) => {
+        const action = async () => {
+          // Hover on the "Bars 2" legend item
+          const legendItem = page.locator('[data-ech-series-name="Bars 2"]');
+          await legendItem.hover();
+        };
+        await common.expectChartAtUrlToMatchScreenshot(page)(
+          // Hide partition chart so XY chart is the first .echChart
+          `http://localhost:9001/?path=/story/stylings--dimmed-highlight-style&${urlParam}&knob-Show Partition Chart=false`,
+          { action },
+        );
+      });
+
+      test(`should dim partition chart slices on legend hover - ${theme}`, async ({ page }) => {
+        const action = async () => {
+          // Hover on the first legend item
+          const legendItem = page.locator('.echLegendItem').first();
+          await legendItem.hover();
+        };
+        await common.expectChartAtUrlToMatchScreenshot(page)(
+          // Hide XY chart so partition chart is the only .echChart
+          `http://localhost:9001/?path=/story/stylings--dimmed-highlight-style&${urlParam}&knob-Show XY Chart=false`,
+          { action },
+        );
+      });
+    });
+
+    test('should apply opacity-only dimming on bar chart - light theme', async ({ page }) => {
+      const action = async () => {
+        // Hover on the "Bars 2" legend item
+        const legendItem = page.locator('[data-ech-series-name="Bars 2"]');
+        await legendItem.hover();
+      };
+      await common.expectChartAtUrlToMatchScreenshot(page)(
+        `http://localhost:9001/?path=/story/stylings--dimmed-highlight-style&globals=theme:light&knob-Show Partition Chart=false&knob-Use opacity-only dimming=true&knob-Alpha (opacity)=0.10`,
+        { action },
+      );
+    });
+
+    test('should apply opacity-only dimming on partition chart - dark theme', async ({ page }) => {
+      const action = async () => {
+        // Hover on the first legend item
+        const legendItem = page.locator('.echLegendItem').first();
+        await legendItem.hover();
+      };
+      await common.expectChartAtUrlToMatchScreenshot(page)(
+        `http://localhost:9001/?path=/story/stylings--dimmed-highlight-style&globals=theme:dark&knob-Show XY Chart=false&knob-Use opacity-only dimming=true&knob-Alpha (opacity)=0.15`,
+        { action },
+      );
+    });
+  });
 });

e2e/tests/waffle_stories.test.ts

@@ -8,6 +8,7 @@
 
 import { test } from '@playwright/test';
 
+import { eachTheme } from '../helpers';
 import { common } from '../page_objects/common';
 
 test.describe('Waffle', () => {
@@ -21,4 +22,16 @@ test.describe('Waffle', () => {
       'http://localhost:9001/?path=/story/waffle-alpha--test&globals=toggles.showHeader:true;toggles.showChartTitle:false;toggles.showChartDescription:false;theme:light&knob-use alpha=true',
     );
   });
+
+  eachTheme.describe(({ theme, urlParam }) => {
+    test(`should dim cells on legend hover - ${theme}`, async ({ page }) => {
+      const action = async () => {
+        await common.moveMouseRelativeToDOMElement(page)({ left: 5, top: 5 }, '.echLegendItem');
+      };
+      await common.expectChartAtUrlToMatchScreenshot(page)(
+        `http://localhost:9001/?path=/story/waffle-alpha--simple&${urlParam}`,
+        { action },
+      );
+    });
+  });
 });

packages/charts/api/charts.api.md

@@ -2315,6 +2315,13 @@ export type PartialTheme = RecursivePartial<Theme>;
 // @public
 export const Partition: <D extends BaseDatum = any>(props: SFProps<PartitionSpec<D>, keyof (typeof buildProps)["overrides"], keyof (typeof buildProps)["defaults"], keyof (typeof buildProps)["optionals"], keyof (typeof buildProps)["requires"]>) => null;
 
+// @public (undocumented)
+export type PartitionDimmedStyle = {
+    opacity: number;
+} | {
+    fill: Color | ColorVariant;
+};
+
 // @public
 export type PartitionElementEvent = [layers: Array<LayerValue>, seriesIdentifier: SeriesIdentifier];
 
@@ -2370,6 +2377,7 @@ export interface PartitionStyle extends FillFontSizeRange {
     //
     // (undocumented)
     circlePadding: Distance;
+    dimmed: PartitionDimmedStyle;
     // Warning: (ae-forgotten-export) The symbol "SizeRatio" needs to be exported by the entry point index.d.ts
     emptySizeRatio: SizeRatio;
     // (undocumented)
@@ -2655,6 +2663,14 @@ export interface RectBorderStyle {
 
 // @public (undocumented)
 export interface RectStyle {
+    dimmed: {
+        opacity: number;
+    } | {
+        fill: Color | ColorVariant;
+        texture: {
+            opacity: number;
+        };
+    };
     fill?: Color | ColorVariant;
     opacity: number;
     texture?: TexturedStyles;

packages/charts/src/chart_types/partition_chart/renderer/canvas/canvas_linear_renderers.ts

@@ -7,8 +7,15 @@
  */
 
 import type { AnimationState, ContinuousDomainFocus } from './partition';
+import { multiplyColorOpacity } from '../../../../common/color_library_wrappers';
 import { Colors } from '../../../../common/colors';
-import type { ShapeViewModel } from '../../layout/types/viewmodel_types';
+import type { LegendPath } from '../../../../state/actions/legend';
+import { getColorFromVariant } from '../../../../utils/common';
+import { getDimmedColor } from '../../../../utils/themes/dimmed_colors';
+import type { PartitionStyle } from '../../../../utils/themes/partition';
+import type { QuadViewModel, ShapeViewModel } from '../../layout/types/viewmodel_types';
+import type { LegendStrategy } from '../../layout/utils/highlighted_geoms';
+import { highlightedGeoms } from '../../layout/utils/highlighted_geoms';
 
 const linear = (x: number) => x;
 const easeInOut = (alpha: number) => (x: number) => x ** alpha / (x ** alpha + (1 - x) ** alpha);
@@ -30,8 +37,19 @@ export function renderLinearPartitionCanvas2d(
     animation,
   }: ShapeViewModel,
   { currentFocusX0, currentFocusX1, prevFocusX0, prevFocusX1 }: ContinuousDomainFocus,
+  highlightedLegendPath: LegendPath,
+  legendStrategy: LegendStrategy | undefined,
+  flatLegend: boolean | undefined,
+  partitionStyle: PartitionStyle,
   animationState: AnimationState,
 ) {
+  // Calculate which quads are highlighted for legend dimming
+  const highlightedQuadSet = new Set<QuadViewModel>();
+  if (highlightedLegendPath.length > 0) {
+    const highlighted = highlightedGeoms(legendStrategy, flatLegend, quadViewModel, highlightedLegendPath);
+    highlighted.forEach((quad) => highlightedQuadSet.add(quad));
+  }
+
   if (animation?.duration) {
     window.cancelAnimationFrame(animationState.rafId);
     render(0);
@@ -72,7 +90,8 @@ export function renderLinearPartitionCanvas2d(
     ctx.translate(diskCenter.x, diskCenter.y);
     ctx.clearRect(0, 0, width, height);
 
-    quadViewModel.forEach(({ fillColor, x0, x1, y0px: y0, y1px: y1, dataName, textColor, depth }) => {
+    quadViewModel.forEach((quad) => {
+      const { fillColor, x0, x1, y0px: y0, y1px: y1, dataName, textColor, depth } = quad;
       if (y1 - y0 <= padding) return;
 
       const fx0 = Math.max((x0 - focusX0) * scale, 0);
@@ -87,7 +106,18 @@ export function renderLinearPartitionCanvas2d(
       const fWidth = fx1 - fx0;
       const fPadding = Math.min(padding, MAX_PADDING_RATIO * fWidth);
 
-      ctx.fillStyle = fillColor;
+      const isDimmed = highlightedQuadSet.size > 0 && !highlightedQuadSet.has(quad);
+      const baseFillColor = getColorFromVariant(
+        fillColor,
+        getDimmedColor(isDimmed, partitionStyle.dimmed, 'fill', fillColor),
+      );
+      // Apply opacity when dimmed with opacity config
+      const dimmedFillColor =
+        isDimmed && 'opacity' in partitionStyle.dimmed
+          ? multiplyColorOpacity(baseFillColor, partitionStyle.dimmed.opacity)
+          : baseFillColor;
+
+      ctx.fillStyle = dimmedFillColor;
       ctx.beginPath();
       ctx.rect(fx0 + fPadding, y0 + padding / 2, fWidth - fPadding, y1 - y0 - padding);
       ctx.fill();

packages/charts/src/chart_types/partition_chart/renderer/canvas/canvas_renderers.ts

@@ -6,13 +6,17 @@
  * Side Public License, v 1.
  */
 
-import { colorToRgba, RGBATupleToString } from '../../../../common/color_library_wrappers';
+import { colorToRgba, multiplyColorOpacity, RGBATupleToString } from '../../../../common/color_library_wrappers';
 import type { Color } from '../../../../common/colors';
 import { TAU } from '../../../../common/constants';
 import type { Pixels } from '../../../../common/geometry';
 import { cssFontShorthand, HorizontalAlignment } from '../../../../common/text_utils';
 import { renderLayers, withContext } from '../../../../renderers/canvas';
 import { MIN_STROKE_WIDTH } from '../../../../renderers/canvas/primitives/line';
+import type { LegendPath } from '../../../../state/actions/legend';
+import { getColorFromVariant } from '../../../../utils/common';
+import { getDimmedColor } from '../../../../utils/themes/dimmed_colors';
+import type { PartitionStyle } from '../../../../utils/themes/partition';
 import type {
   LinkLabelVM,
   OutsideLinksViewModel,
@@ -22,6 +26,8 @@ import type {
   ShapeViewModel,
   TextRow,
 } from '../../layout/types/viewmodel_types';
+import type { LegendStrategy } from '../../layout/utils/highlighted_geoms';
+import { highlightedGeoms } from '../../layout/utils/highlighted_geoms';
 import type { LinkLabelsViewModelSpec } from '../../layout/viewmodel/link_text_layout';
 import { isSunburst } from '../../layout/viewmodel/viewmodel';
 
@@ -103,7 +109,8 @@ function renderRowSets(ctx: CanvasRenderingContext2D, rowSets: RowSet[], linkLab
 
 function renderTaperedBorder(
   ctx: CanvasRenderingContext2D,
-  { strokeWidth, strokeStyle, fillColor, x0, x1, y0px, y1px }: QuadViewModel,
+  { strokeWidth, strokeStyle, x0, x1, y0px, y1px }: QuadViewModel,
+  fillColor: Color,
 ) {
   const X0 = x0 - TAU / 4;
   const X1 = x1 - TAU / 4;
@@ -149,22 +156,56 @@ function renderTaperedBorder(
   }
 }
 
-function renderSectors(ctx: CanvasRenderingContext2D, quadViewModel: QuadViewModel[]) {
+function renderSectors(
+  ctx: CanvasRenderingContext2D,
+  quadViewModel: QuadViewModel[],
+  highlightedQuadSet: Set<QuadViewModel>,
+  partitionStyle: PartitionStyle,
+) {
   withContext(ctx, () => {
     ctx.scale(1, -1); // D3 and Canvas2d use a left-handed coordinate system (+y = down) but the ViewModel uses +y = up, so we must locally invert Y
     quadViewModel.forEach((quad: QuadViewModel) => {
-      if (quad.x0 !== quad.x1) renderTaperedBorder(ctx, quad);
+      if (quad.x0 === quad.x1) return;
+
+      const isDimmed = highlightedQuadSet.size > 0 && !highlightedQuadSet.has(quad);
+      const baseFillColor = getColorFromVariant(
+        quad.fillColor,
+        getDimmedColor(isDimmed, partitionStyle.dimmed, 'fill', quad.fillColor),
+      );
+      // Apply opacity when dimmed with opacity config
+      const fillColor =
+        isDimmed && 'opacity' in partitionStyle.dimmed
+          ? multiplyColorOpacity(baseFillColor, partitionStyle.dimmed.opacity)
+          : baseFillColor;
+      renderTaperedBorder(ctx, quad, fillColor);
     });
   });
 }
 
-function renderRectangles(ctx: CanvasRenderingContext2D, quadViewModel: QuadViewModel[]) {
+function renderRectangles(
+  ctx: CanvasRenderingContext2D,
+  quadViewModel: QuadViewModel[],
+  highlightedQuadSet: Set<QuadViewModel>,
+  partitionStyle: PartitionStyle,
+) {
   withContext(ctx, () => {
     ctx.scale(1, -1); // D3 and Canvas2d use a left-handed coordinate system (+y = down) but the ViewModel uses +y = up, so we must locally invert Y
-    quadViewModel.forEach(({ strokeWidth, fillColor, x0, x1, y0px, y1px }) => {
+    quadViewModel.forEach((quad) => {
+      const { strokeWidth, fillColor, x0, x1, y0px, y1px } = quad;
       // only draw a shape if it would show up at all
       if (x1 - x0 >= 1 && y1px - y0px >= 1) {
-        ctx.fillStyle = fillColor;
+        const isDimmed = highlightedQuadSet.size > 0 && !highlightedQuadSet.has(quad);
+        const baseFillColor = getColorFromVariant(
+          fillColor,
+          getDimmedColor(isDimmed, partitionStyle.dimmed, 'fill', fillColor),
+        );
+        // Apply opacity when dimmed with opacity config
+        const dimmedFillColor =
+          isDimmed && 'opacity' in partitionStyle.dimmed
+            ? multiplyColorOpacity(baseFillColor, partitionStyle.dimmed.opacity)
+            : baseFillColor;
+
+        ctx.fillStyle = dimmedFillColor;
         ctx.beginPath();
         ctx.moveTo(x0, y0px);
         ctx.lineTo(x0, y1px);
@@ -277,6 +318,10 @@ export function renderPartitionCanvas2d(
     panel,
     chartDimensions,
   }: ShapeViewModel,
+  highlightedLegendPath: LegendPath,
+  legendStrategy: LegendStrategy | undefined,
+  flatLegend: boolean | undefined,
+  partitionStyle: PartitionStyle,
 ) {
   const { sectorLineWidth, sectorLineStroke, linkLabel } = style;
 
@@ -322,13 +367,24 @@ export function renderPartitionCanvas2d(
     ctx.strokeStyle = sectorLineStroke;
     ctx.lineWidth = sectorLineWidth;
 
+    // Calculate which quads are highlighted for legend dimming
+    const highlightedQuadSet = new Set<QuadViewModel>();
+    if (highlightedLegendPath.length > 0) {
+      // Use highlightedGeoms to determine which quads match the legend path
+      const highlighted = highlightedGeoms(legendStrategy, flatLegend, quadViewModel, highlightedLegendPath);
+      highlighted.forEach((quad) => highlightedQuadSet.add(quad));
+    }
+
     // painter's algorithm, like that of SVG: the sequence determines what overdraws what; first element of the array is drawn first
     // (of course, with SVG, it's for ambiguous situations only, eg. when 3D transforms with different Z values aren't used, but
     // unlike SVG and esp. WebGL, Canvas2d doesn't support the 3rd dimension well, see ctx.transform / ctx.setTransform).
     // The layers are callbacks, because of the need to not bake in the `ctx`, it feels more composable and uncoupled this way.
     renderLayers(ctx, [
       // bottom layer: sectors (pie slices, ring sectors etc.)
-      () => (isSunburst(layout) ? renderSectors(ctx, quadViewModel) : renderRectangles(ctx, quadViewModel)),
+      () =>
+        isSunburst(layout)
+          ? renderSectors(ctx, quadViewModel, highlightedQuadSet, partitionStyle)
+          : renderRectangles(ctx, quadViewModel, highlightedQuadSet, partitionStyle),
 
       // all the fill-based, potentially multirow text, whether inside or outside the sector
       () => renderRowSets(ctx, rowSets, linkLineColor),