feature/sankey-pathid-focus

[hugomoran159]

Problem

Currently, highlighting related elements in Sankey charts is limited to adjacency (focus: 'adjacency') or full upstream/downstream paths (focus: 'trajectory'). There is no built-in way to highlight specific logical paths or flows defined directly within the user's data.

Solution

This PR introduces a new emphasis.focus option value: 'pathId'.

When emphasis: { focus: 'pathId' } is set on the Sankey series:

1. The user is expected to provide a pathId property (string, number, or array thereof) on each item in their links (or edges) data. Nodes do not require a pathId.
2. When hovering over a node, the system identifies all unique pathIds from its directly connected links.
3. When hovering over a link, the system uses the pathIds of that link.
4. The system then finds all links in the chart that share any of the identified pathIds.
5. Using the existing blur mechanism, all elements not part of this identified set (matching links and their connected nodes) are blurred.
6. The directly hovered element receives the standard 'emphasis' style. Elements related via pathId are highlighted by remaining un-blurred ("highlight by contrast").

This allows users to define and visually highlight arbitrary logical flows within their Sankey diagram based on data annotation.

Changes

• src/data/Graph.ts: Added getElementsByPathId methods to GraphNode and GraphEdge to retrieve elements based on shared pathIds found on links. Replaced Set usage with plain objects to pass linting.
• src/chart/sankey/SankeySeries.ts: Added 'pathId' to the allowed types for emphasis.focus and removed the old 'path'.
• src/chart/sankey/SankeyView.ts: Integrated the call to getElementsByPathId when focus is set to 'pathId', removed the old 'path' condition.
• test/data/energy_with_paths.json: Updated pathIds for testing logical flows.
• test/sankey.html: Updated a test case to use focus: 'pathId' and the new test data.

Testing

• Tested visually using the updated test/sankey.html example (main4) with the energy_with_paths.json dataset. The highlighting correctly identifies and un-blurs elements (nodes and links) sharing the relevant pathIds upon hover.
• Code passes npm run checktype and npm run lint.
• Project builds successfully with npm run release.

Documentation Note

The official ECharts documentation will need to be updated to include the new emphasis.focus: 'pathId' option for Sankey charts, explaining its behavior and the requirement for pathId on link data items.

[echarts-bot]

Thanks for your contribution!
The community will review it ASAP. In the meanwhile, please checkout the coding standard and Wiki about How to make a pull request.

To reviewers: If this PR is going to be described in the changelog in the future release, please make sure this PR has one of the following labels: PR: doc ready, PR: awaiting doc, PR: doc unchanged

This message is shown because the PR description doesn't contain the document related template.

[Ovilia]

Please don't include code else than src and test.