feat(visualMap): add seriesTargets option for multiple series-dimension mappings

[Justin-ZS]

Brief Information

This pull request is in the type of:

• bug fixing
• new feature
• others

What does this PR do?

official demo

option =  {
    visualMap: {   
        // Introduce a new option `target`.
        // When `target` is provided, `visualMap.seriesIndex`, `visualMap.seriesId`, `visualMap.dimension`
        // are ignored.
        target: [{
            seriesIndex: 3,
            dimension: 2,
        }, {
            seriesId: 'xxx', // either seriesId or seriesIndex
            dimension: 1,
        },
        ...
        ]
    }
};

Fixed issues

#20662
#14346
Also fix #20347:

Details

Before: What was the problem?

Single visualMap cannot be used for 2d dataset.

After: How does it behave after the fixing?

mapping series to dimension by seriesTargets

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 doc(visualmap): add doc for seriesTargets echarts-doc#485

Misc

ZRender Changes

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

Related test cases or examples to use the new APIs

N.A.

Others

Merging options

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

Other information

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

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]

I don't think it's intuitive to use dimension: [1,2] to represent seriesIndex: 0 -> 1, 1 -> 2, 2 -> 2. Instead, it's more like using both dimension 1 and 2.

I think the problem of #20662 should be best solved using the third demo @MatthiasMert gave. I would suggest closing this PR unless a more solid reason is given. Thanks for your contribution anyway.

[Justin-ZS]

I don't think it's intuitive to use dimension: [1,2] to represent seriesIndex: 0 -> 1, 1 -> 2, 2 -> 2. Instead, it's more like using both dimension 1 and 2.

I think the problem of #20662 should be best solved using the third demo @MatthiasMert gave. I would suggest closing this PR unless a more solid reason is given. Thanks for your contribution anyway.

Using the same visualMap on 2d dataset requires the dataset to be splitted looks overkill.
dimension: [1,2] cannot be explained as using both dimension 1 and 2 since one series can use only one dimension
using both dimension 1 and 2 is technically impossible, unless you choose to provide a function to aggreagte multiple values

[Ovilia]

It's true that using both dimension 1 and 2 is technically impossible. Even though, it's misleading to provide such API design. Again, I would suggest using the 3rd solution or avoid using dataset in your case. Adding a new feature should take a lot of things into consideration so I would say it's not quite a good design of API unless a better plan is proposed.

[Justin-ZS]

It's true that using both dimension 1 and 2 is technically impossible. Even though, it's misleading to provide such API design. Again, I would suggest using the 3rd solution or avoid using dataset in your case. Adding a new feature should take a lot of things into consideration so I would say it's not quite a good design of API unless a better plan is proposed.

Again, the suggested workaround (splitting the dataset) is unacceptable in my use case.

I understand your concerns about the API design.
I do think this PR is a simple and clear solution for similar cases.
We can provide detailed document to clarify the correct uasge.

Even if user is misled into thinking it as using both dimension 1 and 2, user will still use the numeric dimension unless they want to map multiple dimensions.
Then, they will find the correct usage through document or just a few attempts.

if you insist, I will keep this PR open until a better solutiion is proposed.

[Ovilia]

Why is the suggested workaround (splitting the dataset) unacceptable?

[Justin-ZS]

Why is the suggested workaround (splitting the dataset) unacceptable?

It requires huge refactoring (tooltip, axis. series and so on) and maintaining two implementations.
And the splitted datasets may cause other limitations or bugs.
As a workaround for now, I added the same visualmap for each series and only show the first controller.
When selection changes, use setOption to sync the state cross all visualMaps.
But the hoverLink interaction cannot be synced.

[Ovilia]

I don't think it should require huge work to refactor from dataset to not. And besides, you can try with AI to help.

[100pah]

I think the basic requirement is reasonable. A visualMap component should be able to control multiple series, and the dimension for each series should be able to configured.

But I'm afraid the current proposed API is not intuitive and seems hard to understand.
I also believe that complicated default value strategies (e.g., if no seriesIndex provided, then xxx) should not be introduced unless necessary, as it may cause unexpected behavior and confuse users.

For this requirement, in my opinion, the API can be designed as:

option =  {
    visualMap: {   
        // Introduce a new option `target`.
        // When `target` is provided, `visualMap.seriesIndex`, `visualMap.seriesId`, `visualMap.dimension`
        // are ignored.
        target: [{
            seriesIndex: 3,
            dimension: 2,
        }, {
            seriesId: 'xxx', // either seriesId or seriesIndex
            dimension: 1,
        },
        ...
        ]
    }
};

[Justin-ZS]

I think the basic requirement is reasonable. A visualMap component should be able to control multiple series, and the dimension for each series should be able to configured.

But I'm afraid the current proposed API is not intuitive and seems hard to understand. I also believe that complicated default value strategies (e.g., if no seriesIndex provided, then xxx) should not be introduced unless necessary, as it may cause unexpected behavior and confuse users.

For this requirement, in my opinion, the API can be designed as:

option =  {
    visualMap: {   
        // Introduce a new option `target`.
        // When `target` is provided, `visualMap.seriesIndex`, `visualMap.seriesId`, `visualMap.dimension`
        // are ignored.
        target: [{
            seriesIndex: 3,
            dimension: 2,
        }, {
            seriesId: 'xxx', // either seriesId or seriesIndex
            dimension: 1,
        },
        ...
        ]
    }
};

VisualMap already has a target property.
I will use the name seriesTargets

[Justin-ZS]

@Ovilia @100pah
PR has been updated accordingly.
Could you help to review again? Thanks!

[github-actions]

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

[plainheart]

I noticed that this validation only outputs warnings during the development process. How about moving the __DEV__ check outside? - This helps reduce the distribution file size.

if (__DEV__) {
    const seriesTargets = opt.seriesTargets;
    if (seriesTargets && zrUtil.isArray(seriesTargets)) {
        each(seriesTargets, function (target) {
            if (!zrUtil.isObject(target) || target.dimension == null) {
                console.warn('Each seriesTarget should have a dimension property');
            }
            if (target.seriesIndex == null && target.seriesId == null) {
                console.warn('Each seriesTarget should have either seriesIndex or seriesId');
            }
        });
    }
}

[Justin-ZS]

done

[plainheart]

There seems to be no const of usage for the array iteration in the codebase. As the current coding style, maybe the zrUtil.each utility should be used here.

[Justin-ZS]

done

[Ovilia]

LGTM

[echarts-bot]

Congratulations! Your PR has been merged. Thanks for your contribution! 👍