konewka17 opened a new pull request, #21562:
URL: https://github.com/apache/echarts/pull/21562
<!-- Please fill in the following information to help us review your PR more
efficiently. -->
## Brief Information
This pull request is in the type of:
- [ ] bug fixing
- [x] 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
- #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:
```js
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:
```ts
sortNodes?: boolean
```
Default:
```ts
sortNodes: true
```
When set to:
```js
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.
- [x] This PR doesn't relate to document changes
- [ ] The document should be updated later
- [ ] The document changes have been made in apache/echarts-doc#xxx
## Misc
### Security Checking
- [ ] This PR uses security-sensitive Web APIs.
<!-- PLEASE CHECK IT AGAINST:
https://github.com/apache/echarts/wiki/Security-Checklist-for-Code-Contributors
-->
### 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
- [x] 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.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
