fix(visualMap): match piecewise categories on a category axis dimension

[jayzhou2309]

Brief Information

This pull request is in the type of:

• bug fixing
• new feature
• others

What does this PR do?

Make a piecewise visualMap with categories work when its dimension is also encoded onto a category axis.

Fixed issues

• [Bug] visualMap piecewise not working when categorical dataset dimension is already mapped with encode #21236: visualMap piecewise not working when categorical dataset dimension is already mapped with encode

Details

Before: What was the problem?

When a dimension is encoded onto a category axis, the data store keeps ordinal numbers (0, 1, ...) for it, not the category strings. Two visualMap paths read that stored value and pass it to VisualMapping.findPieceIndex, which compares it with the piece value 'teacher':

• incrementalApplyVisual in src/visual/visualSolution.ts (the series visual encoding). No piece matched, so every item was out of range, got symbol 'none', and the series disappeared.
• PiecewiseModel.findTargetDataIndices (hover highlight from the visualMap pieces). It found no data items.

The same option works when the dimension is not on a category axis, because the store then keeps the raw strings.

After: How does it behave after the fixing?

In categories mode, both paths map the ordinal number back to its category string through the dimension's OrdinalMeta, the same way SeriesData reads a category. VisualMapModel.isCategoryMode() returns false by default, and PiecewiseModel returns true when it is in categories mode. So continuous visualMaps and pieces/splitNumber intervals on an ordinal dimension still match on the ordinal index, as they do today.

A regression test in test/ut/spec/component/visualMap/piecewiseCategories.test.ts uses the option from the issue (a dataset, encode: {y: 'profession'} on a category yAxis, categories: ['teacher', 'doctor']):

• Before the fix: 2 of 2 fail. The symbols are ['none', 'none', 'none'] where ['diamond', 'circle', 'diamond'] is expected, and findTargetDataIndices returns [] for each piece.
• After the fix: 2 of 2 pass.
• Full unit suite (npm test): 196 of 196 pass with TZ=UTC. With the machine's local timezone, util/time › roundTime_locale fails the same way without this change.
• npx tsc --noEmit and eslint on the changed files are clean.

Not verified: rendering in a browser. The tests check the item visuals and the hover target indices, which the scatter view and the piecewise view read.

Open PR #21715 also edits src/visual/visualSolution.ts, but in applyVisual, not incrementalApplyVisual. The two changes do not overlap.

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#xxx

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

test/ut/spec/component/visualMap/piecewiseCategories.test.ts

Merging options

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

Other information

AI disclosure: an AI agent (Claude Code) reproduced the issue on master, wrote the test and the fix, and ran npx jest --config test/ut/jest.config.cjs, npx eslint, and npx tsc --noEmit.

---

_{🤖 Written and posted by an AI agent (Claude Code) on behalf of @jayzhou2309.}

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