feat(sankey): support disabling node sorting. close #21561

[konewka17]

Brief Information

This pull request is in the type of:

• bug fixing
• new feature
• others

What does this PR do?

Adds a new Sankey series option sortNodes?: boolean that allows disabling automatic node sorting within each depth level while preserving all other layout optimizations.

Fixed issues

• [Feature] Sankey: allow disabling automatic node sorting while still using positioning iterations #21561: Allow preserving custom node ordering within Sankey depth levels

Details

Before: What was the problem?

Currently, the Sankey layout automatically sorts nodes within each depth level to reduce edge crossings and improve visual clarity. While this generally produces good layouts, it prevents developers from enforcing a custom semantic ordering of nodes within the same level.

In many practical use cases, node order within a level conveys meaning (e.g. ranking, process steps, grouped categories, or domain-specific logic). The automatic sorting step overrides the input order, making diagrams harder to interpret or inconsistent with external logic.

A common workaround is to set:

layoutIterations: 0

However, this disables useful layout behaviors such as:

• vertical alignment optimization
• collision resolution improvements
• balanced node spacing
• refined edge positioning via Gauss–Seidel relaxation

As a result, nodes in each depth column remain aligned at the top, often producing visually suboptimal layouts.

Developers currently lack a way to preserve node order while still benefiting from layout optimization.

---

After: How does it behave after the fixing?

A new optional series configuration property is introduced:

sortNodes?: boolean

Default:

sortNodes: true

When set to:

series: {
  type: 'sankey',
  sortNodes: false
}

the layout algorithm:

• preserves the original input order of nodes within each depth level
• skips the per-column sorting step during collision resolution
• continues to apply:
  • node breadth calculation
  • node scaling
  • collision resolution adjustments
  • Gauss–Seidel relaxation iterations
  • edge positioning and thickness calculation

This enables deterministic node ordering without sacrificing layout quality.

A visual test case was added to test/sankey.html demonstrating the preserved ordering behavior.

Implementation details:

• Added sortNodes?: boolean to SankeySeriesOption
• Default value set to true to ensure backward compatibility
• Propagated sortNodes into the layout pipeline
• Conditionally skipped sorting inside resolveCollisions
• Added test scenario for manual verification

Document Info

One of the following should be checked.

• This PR doesn't relate to document changes
• The document should be updated later
• The document changes have been made in apache/echarts-doc#500
  

Misc

Security Checking

• This PR uses security-sensitive Web APIs.

ZRender Changes

• This PR depends on ZRender changes (ecomfe/zrender#xxx).

Related test cases or examples to use the new APIs

Added manual visual test in:

test/sankey.html

Test demonstrates that:

sortNodes: false

preserves input node ordering within each depth level while keeping layout iterations active.

Merging options

• Please squash the commits into a single one when merging.

Other information

This feature provides a minimal API addition that enables deterministic ordering of nodes within Sankey depth levels, while preserving existing layout improvements.

It serves as a practical alternative to layoutIterations: 0, which disables useful layout refinements.

Demonstration of the fix

[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.

Please DO NOT commit the files in dist, i18n, and ssr/client/dist folders in a non-release pull request. These folders are for release use only.

[echarts-bot]

Document changes are required in this PR. Please also make a PR to apache/echarts-doc for document changes and update the issue id in the PR description. When the doc PR is merged, the maintainers will remove the PR: awaiting doc label.

[Ovilia]

Thanks for your contribution.

I think the name of the new option could comply with sunburst.sort, whose default value is 'desc'. You don't need to implement 'asc' or function value in this PR until such requirement is raised up. When it is set to be null, it won't sort. When it's undefined, it should be taken as 'desc' for compatibility.

[github-actions]

The changes brought by this PR can be previewed at: https://echarts.apache.org/examples/editor?version=PR-21562@6418ca2

[konewka17]

Nice suggestion @Ovilia, I've implemented it. Documentation is updated accordingly