[charts-pro] Add keyboard navigation to sankey by alexfauquette · Pull Request #20777 · mui/mui-x

alexfauquette · 2025-12-29T17:04:47Z

The sankey now has a keyboard navigation.

Behavior

for node:

up/down: moves the focus between nodes of the same layer
left/right: moves focus to the source/target links

for links:

up/down: moves the focus between links with the same source
left/right: moves focus to the source/target node

Decisions up to discussion

The link up/down are limited to the same source node. It might look broken when layers are simple.

Here for example if you focus a yellow link you will only be able to move to the other yellow link. But user could expect to also navigate to the other links of the same level.

But if we consider more complex use cases like this one, it not that clear to know which link should be included or not in the loop and in which order we navigate across them.

So basically the proposed behavior is a bit restrictive but fully predictable

mui-bot · 2025-12-29T17:06:30Z

Deploy preview: https://deploy-preview-20777--material-ui-x.netlify.app/

Updated pages:

docs/data/charts/sankey/sankey.md

Bundle size report

Bundle	Parsed size	Gzip size
@mui/x-data-grid	0B^(0.00%)	0B^(0.00%)
@mui/x-data-grid-pro	0B^(0.00%)	0B^(0.00%)
@mui/x-data-grid-premium	0B^(0.00%)	0B^(0.00%)
@mui/x-charts	0B^(0.00%)	0B^(0.00%)
@mui/x-charts-pro	🔺+2.85KB^(+0.61%)	🔺+687B^(+0.49%)
@mui/x-charts-premium	0B^(0.00%)	0B^(0.00%)
@mui/x-date-pickers	0B^(0.00%)	0B^(0.00%)
@mui/x-date-pickers-pro	0B^(0.00%)	0B^(0.00%)
@mui/x-tree-view	0B^(0.00%)	0B^(0.00%)
@mui/x-tree-view-pro	0B^(0.00%)	0B^(0.00%)

Details of bundle changes

Generated by 🚫 dangerJS against 977a5bc

Copilot

Pull request overview

This PR adds keyboard navigation functionality to the Sankey chart component, enabling users to navigate between nodes and links using arrow keys. The implementation includes visual focus indicators and exports the necessary hooks for consumers.

Key Changes

Implements keyboard navigation handler for Sankey charts with arrow key support for navigating nodes (up/down within layers, left/right to connected links) and links (up/down among same-source links, left/right to source/target nodes)
Adds FocusedSankeyNode and FocusedSankeyLink components to visually indicate the currently focused element with a stroke outline
Exports useFocusedItem hook from x-charts and x-charts-pro packages for programmatic access to the focused item

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
packages/x-charts-pro/src/SankeyChart/seriesConfig/keyboardFocusHandler.ts	New keyboard navigation logic for Sankey charts, handling arrow key navigation between nodes and links
packages/x-charts-pro/src/SankeyChart/FocusedSankeyNode.tsx	Component rendering focus indicator rectangle for focused nodes
packages/x-charts-pro/src/SankeyChart/FocusedSankeyLink.tsx	Component rendering focus indicator path for focused links
packages/x-charts-pro/src/SankeyChart/SankeyChart.tsx	Integrates FocusedSankeyNode and FocusedSankeyLink components, adds enableKeyboardNavigation prop
packages/x-charts-pro/src/SankeyChart/SankeyChart.plugins.ts	Registers keyboard navigation plugin for Sankey charts
packages/x-charts-pro/src/SankeyChart/seriesConfig/index.ts	Adds keyboardFocusHandler to Sankey series configuration
packages/x-charts/src/hooks/useFocusedItem.ts	New hook to access the currently focused item from keyboard navigation state
packages/x-charts/src/hooks/index.ts	Exports useFocusedItem hook
packages/x-charts/src/internals/plugins/featurePlugins/useChartKeyboardNavigation/index.ts	Exports keyboard focus handler types
packages/x-charts/src/internals/plugins/featurePlugins/useChartKeyboardNavigation/keyboardFocusHandler.types.ts	Updates type signatures to support series-specific type parameters
packages/x-charts/src/internals/plugins/models/chart.ts	Adds TSeriesType generic parameter to ChartState type
packages/x-charts/src/internals/plugins/corePlugins/corePlugins.ts	Updates ChartCorePluginSignatures to be generic over series type
scripts/x-charts.exports.json	Adds useFocusedItem to exports
scripts/x-charts-pro.exports.json	Adds FocusedSankeyLink, FocusedSankeyNode, and useFocusedItem to exports
scripts/x-charts-premium.exports.json	Adds useFocusedItem to exports
docs/*	Adds API documentation pages and updates sankey documentation with new components

packages/x-charts-pro/src/SankeyChart/seriesConfig/keyboardFocusHandler.ts

Copilot · 2025-12-29T19:06:08Z

packages/x-charts-pro/src/SankeyChart/seriesConfig/keyboardFocusHandler.ts

+import type { KeyboardFocusHandler, FocusedItemUpdater } from '@mui/x-charts/internals';
+
+// ====================================================================================================================
+//
+// Info: This files use node.layer and not node.depth to navigate between nodes on the same level.
+//
+// - depth is the graph depth, starting at 0 on the left, increasing by 1 for each link to the right.
+// - layer is the visual level of the node. It takes into consideration the node alignment (left/right/justify/center)
+//
+// ====================================================================================================================
+
+const getFirstNode: FocusedItemUpdater<'sankey', 'sankey'> = (_, state) => {
+  // If no node is defined, find the first node with layer = 0
+  const seriesId = state.series.defaultizedSeries.sankey?.seriesOrder[0];
+  if (!seriesId || !state.series.defaultizedSeries.sankey) {
+    return null;
+  }
+  const series = state.series.defaultizedSeries.sankey.series[seriesId];
+
+  if (series.data.nodes.length > 0) {
+    const index = series.data.nodes.findIndex((node) => node.layer === 0);
+    return { seriesId, type: 'sankey', subType: 'node', nodeId: series.data.nodes[index].id };
+  }
+  return null;
+};
+
+const getNodeToNode =
+  (step: -1 | 1): FocusedItemUpdater<'sankey', 'sankey'> =>
+  (currentItem, state) => {
+    if (currentItem && currentItem.subType === 'node') {
+      const data = state.series.defaultizedSeries.sankey?.series[currentItem.seriesId].data;
+      const currentNodeIndex = data?.nodes.findIndex((node) => node.id === currentItem.nodeId);
+
+      if (currentNodeIndex === undefined || currentNodeIndex < 0 || !data) {
+        return getFirstNode(null, state);
+      }
+
+      const currentNode = data.nodes[currentNodeIndex];
+      for (let i = 1; i <= data.nodes.length; i += 1) {
+        const index = (data.nodes.length + currentNodeIndex + step * i) % data.nodes.length;
+        if (data.nodes[index].layer === currentNode.layer) {
+          return {
+            seriesId: currentItem.seriesId,
+            type: 'sankey',
+            subType: 'node',
+            nodeId: data.nodes[index].id,
+          };
+        }
+      }
+    }
+    // If we fail, we fallback on the fist node
+    return getFirstNode(null, state);
+  };
+
+const getNodeToLink =
+  (step: 'source' | 'target'): FocusedItemUpdater<'sankey', 'sankey'> =>
+  (currentItem, state) => {
+    if (currentItem && currentItem.subType === 'node') {
+      const data = state.series.defaultizedSeries.sankey?.series[currentItem.seriesId].data;
+      const currentNodeIndex = data?.nodes.findIndex((node) => node.id === currentItem.nodeId);
+
+      if (currentNodeIndex === undefined || currentNodeIndex < 0 || !data) {
+        return getFirstNode(null, state);
+      }
+
+      const currentNode = data.nodes[currentNodeIndex];
+
+      const links = step === 'source' ? currentNode.sourceLinks : currentNode.targetLinks;
+      if (links.length === 0) {
+        // No link in that direction, we stay where we are.
+        return currentItem;
+      }
+      return {
+        seriesId: currentItem.seriesId,
+        type: 'sankey',
+        subType: 'link',
+        sourceId: links[0].source.id,
+        targetId: links[0].target.id,
+      };
+    }
+    // If we fail, we fallback on the fist node
+    return getFirstNode(null, state);
+  };
+
+const getLinkToNode =
+  (step: 'source' | 'target'): FocusedItemUpdater<'sankey', 'sankey'> =>
+  (currentItem, state) => {
+    if (currentItem && currentItem.subType === 'link') {
+      const nodeId = step === 'source' ? currentItem.sourceId : currentItem.targetId;
+      return { seriesId: currentItem.seriesId, type: 'sankey', subType: 'node', nodeId };
+    }
+    return getFirstNode(null, state);
+  };
+
+const getLinkToLink =
+  (step: -1 | 1): FocusedItemUpdater<'sankey', 'sankey'> =>
+  (currentItem, state) => {
+    if (currentItem && currentItem.subType === 'link') {
+      const data = state.series.defaultizedSeries.sankey?.series[currentItem.seriesId].data;
+      const currentLinkIndex = data?.links.findIndex(
+        (link) =>
+          link.source.id === currentItem.sourceId && link.target.id === currentItem.targetId,
+      );
+
+      if (currentLinkIndex === undefined || currentLinkIndex < 0 || !data) {
+        return getFirstNode(null, state);
+      }
+
+      for (let i = 1; i <= data.links.length; i += 1) {
+        const index = (data.links.length + currentLinkIndex + step * i) % data.links.length;
+        if (data.links[index].source.id === currentItem.sourceId) {
+          return {
+            seriesId: currentItem.seriesId,
+            type: 'sankey',
+            subType: 'link',
+            sourceId: data.links[index].source.id,
+            targetId: data.links[index].target.id,
+          };
+        }
+      }
+    }
+
+    return getFirstNode(null, state);
+  };
+
+const keyboardFocusHandler: KeyboardFocusHandler<'sankey', 'sankey'> =
+  (event) => (currentItem, state) => {
+    const isLink = currentItem?.subType === 'link';
+
+    switch (event.key) {
+      case 'ArrowDown':
+        return isLink ? getLinkToLink(1)(currentItem, state) : getNodeToNode(1)(currentItem, state);
+      case 'ArrowUp':
+        return isLink
+          ? getLinkToLink(-1)(currentItem, state)
+          : getNodeToNode(-1)(currentItem, state);
+      case 'ArrowRight':
+        return isLink
+          ? getLinkToNode('target')(currentItem, state)
+          : getNodeToLink('source')(currentItem, state);
+      case 'ArrowLeft':
+        return isLink
+          ? getLinkToNode('source')(currentItem, state)
+          : getNodeToLink('target')(currentItem, state);
+
+      default:
+        return null;
+    }
+  };
+
+export default keyboardFocusHandler;


The keyboard navigation logic lacks test coverage. The repository has comprehensive testing for similar components (e.g., FunnelChart, Heatmap) and hooks (e.g., useFunnelSeries, useSankeySeries). Consider adding tests to verify:

Navigation between nodes in the same layer (up/down arrows)

Navigation between links with the same source (up/down arrows)

Navigation from nodes to source/target links (left/right arrows)

Navigation from links to source/target nodes (left/right arrows)

Edge cases like empty nodes, no links in a direction, and wrapping behavior

@copilot add a new commit to apply changes based on this feedback

packages/x-charts-pro/src/SankeyChart/FocusedSankeyNode.tsx

packages/x-charts-pro/src/SankeyChart/FocusedSankeyLink.tsx

packages/x-charts-pro/src/SankeyChart/seriesConfig/keyboardFocusHandler.ts

codspeed-hq · 2025-12-30T09:13:06Z

Merging this PR will not alter performance

✅ 14 untouched benchmarks

_{Comparing alexfauquette:keyboard-sankey (977a5bc) with master (d1ccc97)¹}

No successful run was found on master (2e1869b) during the generation of this report, so d1ccc97 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

github-actions · 2025-12-30T11:35:31Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

packages/x-charts-pro/src/SankeyChart/seriesConfig/keyboardFocusHandler.ts

github-actions · 2026-01-12T15:49:36Z

This pull request has conflicts, please resolve those before we can evaluate the pull request.

JCQuintas

Overall I agree with the behaviour.

If we get issues with this, we could try other options

A more "stateful one", where if moving backwards then up/down should iterate over the target's links.
One that takes into account the "link color" keyword? If linkOptions.color: 'target' then iterate over the targets links.

JCQuintas · 2026-01-13T16:45:43Z

packages/x-charts-pro/src/SankeyChart/seriesConfig/keyboardFocusHandler.ts

+    }
+  };
+
+export default keyboardFocusHandler;


We tend to export functions instead

I don't understand you point.

For now all the similar files are doing

const keyboardFocusHandler: KeyboardFocusHandler<'pie', 'pie'> = (event) => ... export default keyboardFocusHandler

JCQuintas · 2026-01-13T16:51:50Z

packages/x-charts/src/internals/plugins/models/chart.ts

+  TSeriesType extends ChartSeriesType = ChartSeriesType,
+> = MergeSignaturesProperty<[...ChartCorePluginSignatures<TSeriesType>, ...TSignatures], 'state'> &


Snhould these type changes be in a separate pr?

I could extract it if you prefer. Just that it does not make lot of sens to add this generic in a dedicated PR since it would not be used

No need, only if you expect issues out of it 😅

bernardobelchior · 2026-01-14T09:32:42Z

The algorithm seems to work well in most cases, but here's one where it fails, probably because we're checking that the source and target are the same, but in this case there's an intermediate node.

Here I'm pressing Arrow Down / Arrow Up on every node and link:

Screen.Recording.2026-01-14.at.10.31.12.mov

It's this demo

alexfauquette · 2026-01-14T09:58:58Z

The algorithm seems to work well in most cases, but here's one where it fails, probably because we're checking that the source and target are the same, but in this case there's an intermediate node.

From what I understand, you expect to be able to move from node B to the link E->D

For me it's not a good behavior. In this particular example it looks obvious but on more complex examples, if you can mover between links that don't have the same source, the behavior could look random.

It looks obvious that ArrowDown from B-D or A-B should lead to E-D.
But ArrowUp from E-D should move focus to ... I don't know

And that's a toy example. If you open that navigation, the second screenshot in the description would became a nighmare to navigate

bernardobelchior

Sorry, I forgot to submit my comments 😅

bernardobelchior · 2026-01-14T09:26:20Z

packages/x-charts-pro/src/SankeyChart/FocusedSankeyLink.tsx

+    return null;
+  }
+
+  const link = layout?.links.find(


Suggested change

const link = layout?.links.find(

const link = layout.links.find(

bernardobelchior · 2026-01-14T09:26:49Z

packages/x-charts-pro/src/SankeyChart/FocusedSankeyNode.tsx

+  if (!focusedItem || focusedItem.type !== 'sankey' || focusedItem.subType !== 'node' || !layout) {
+    return null;
+  }
+  const node = layout?.nodes.find(({ id }) => id === focusedItem.nodeId);


Suggested change

const node = layout?.nodes.find(({ id }) => id === focusedItem.nodeId);

const node = layout.nodes.find(({ id }) => id === focusedItem.nodeId);

bernardobelchior · 2026-01-14T09:27:33Z

packages/x-charts-pro/src/SankeyChart/FocusedSankeyNode.tsx

+      width={x1 - x0}
+      height={y1 - y0}
+      fill="none"
+      stroke={(theme.vars ?? theme).palette.text.primary}


Should we always use (theme.vars ?? theme)? I think we might have some places where we don't do this

bernardobelchior · 2026-01-14T09:29:22Z

docs/data/charts/sankey/sankey.md

 title: React Sankey chart
 productId: x-charts
-components: SankeyChart, SankeyPlot, SankeyTooltip, SankeyTooltipContent, SankeyDataProvider
+components: SankeyChart, SankeyPlot, SankeyTooltip, SankeyTooltipContent, SankeyDataProvider, FocusedSankeyNode, FocusedSankeyLink


Should we explain in the docs that these components should be added to the chart when using composition?

bernardobelchior · 2026-01-14T13:44:38Z

From what I understand, you expect to be able to move from node B to the link E->D

Yes

For me it's not a good behavior. In this particular example it looks obvious but on more complex examples, if you can mover between links that don't have the same source, the behavior could look random.

It looks obvious that ArrowDown from B-D or A-B should lead to E-D. But ArrowUp from E-D should move focus to

To the link A-B IMO

And that's a toy example. If you open that navigation, the second screenshot in the description would became a nighmare to navigate

Which one do you mean?

alexfauquette added 2 commits December 29, 2025 16:59

[charts-pro] Add keyboard navigation to sankey

daf69e2

scripts

9e569a5

alexfauquette requested review from a team and prakhargupta1 as code owners December 29, 2025 17:04

alexfauquette added type: enhancement It’s an improvement, but we can’t make up our mind whether it's a bug fix or a new feature. scope: charts Changes related to the charts. labels Dec 29, 2025

Janpot requested a review from Copilot December 29, 2025 18:59

Copilot started reviewing on behalf of Janpot December 29, 2025 18:59 View session

Copilot AI reviewed Dec 29, 2025

View reviewed changes

ts fix and typo

0eb6a0d

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Dec 30, 2025

Add tests

cf6afcb

alexfauquette commented Dec 30, 2025

View reviewed changes

packages/x-charts-pro/src/SankeyChart/seriesConfig/keyboardFocusHandler.ts Outdated Show resolved Hide resolved

oliviertassinari added the plan: Pro Impact at least one Pro user. label Dec 30, 2025

Merge remote-tracking branch 'upstream/master' into keyboard-sankey

019d234

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jan 6, 2026

add-test

2b47421

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jan 12, 2026

alexfauquette added 2 commits January 13, 2026 11:37

Merge remote-tracking branch 'upstream/master' into keyboard-sankey

92488dc

scripts

bd28ec4

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged. label Jan 13, 2026

fix types

977a5bc

alexfauquette requested review from JCQuintas and bernardobelchior as code owners January 13, 2026 16:11

JCQuintas approved these changes Jan 13, 2026

View reviewed changes

alexfauquette merged commit 8571f67 into mui:master Jan 14, 2026
22 checks passed

bernardobelchior reviewed Jan 14, 2026

View reviewed changes

		TSeriesType extends ChartSeriesType = ChartSeriesType,
		> = MergeSignaturesProperty<[...ChartCorePluginSignatures<TSeriesType>, ...TSignatures], 'state'> &

	const link = layout?.links.find(
	const link = layout.links.find(

	const node = layout?.nodes.find(({ id }) => id === focusedItem.nodeId);
	const node = layout.nodes.find(({ id }) => id === focusedItem.nodeId);

Uh oh!

Conversation

alexfauquette commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Behavior

Decisions up to discussion

Uh oh!

mui-bot commented Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle size report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Key Changes

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codspeed-hq bot commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will not alter performance

Footnotes

Uh oh!

github-actions bot commented Dec 30, 2025

Uh oh!

Uh oh!

github-actions bot commented Jan 12, 2026

Uh oh!

JCQuintas left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bernardobelchior commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexfauquette commented Jan 14, 2026

Uh oh!

Uh oh!

bernardobelchior left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bernardobelchior commented Jan 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

alexfauquette commented Dec 29, 2025 •

edited

Loading

mui-bot commented Dec 29, 2025 •

edited

Loading

codspeed-hq bot commented Dec 30, 2025 •

edited

Loading

bernardobelchior commented Jan 14, 2026 •

edited

Loading