feat(matrix): new matrix coordinate

[Ovilia]

Brief Information

This pull request is in the type of:

• bug fixing
• new feature
• others

What does this PR do?

This PR introduces a new coordinate called "Matrix".

Matrix can serve as:

• The layout system of data items of a series. The examples are listed as follows in this initial post.
• The layout system of the box of a series/component, which enables tiny charts to lay out in a table, or CSS grid layout, or even a pure data table. Some subsequent definitions/examples are provided in comment feat(matrix): new matrix coordinate #19807 (comment)

The layout base of data items of a series

Multiple series like heatmap, pie, graph, custom can be used along with it.

More applications:

Fixed issues

Details

Before: What was the problem?

After: How does it behave after the fixing?

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@c537952 and doc(matrix): add doc for apache/echarts#19807 echarts-doc#394 and doc(matrix): matrix coordinate echarts-examples#90

The full document will be published when v6.0.0 is released.
Current doc for v6.0.0-beta:

• The matrix related echarts option: matrix TS decalaration.
• The universal matrix reference from series and components: coodinateSystem reference TS declaration

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.

The pull request is marked to be PR: author is committer because you are a committer of this project.

⚠️ MISSING DOCUMENT INFO: Please make sure one of the document options are checked in this PR's description. Search "Document Info" in the description of this PR. This should be done either by the author or the reviewers of the PR.

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

[github-actions]

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

[100pah]

Roaming Infrastructure Upgrade

Support preserveAspect

Support preserveAspect preserveAspectAlign preserveAspectVerticalAlign on series.map, geo, series.graph in box layout (lay out by left/right/top/bottom/width/height).

The new introduced echarts option is:

    // Suppose a "viewport" is decided by `left`/`right`/`top`/`bottom`/`width`/`height`,
    // - null/undefined/false (default): aspect ratio will not be preserved, but stretched to fill
    //   the "viewport".
    // - 'contain'/true: The aspect ratio is preserved; the viewRect is contained by the "viewport",
    //   and scaled up as much as possible to meet the "viewport".
    // - 'cover': The aspect ratio is preserved; the viewRect covers the "viewport", and scaled down
    //   as much as possible to meet the "viewport".
    preserveAspect?: boolean | 'contain' | 'cover';
    // By default 'center'
    preserveAspectAlign?: 'left' | 'right' | 'center';
    // By default 'middle'
    preserveAspectVerticalAlign?: 'top' | 'bottom' | 'middle';

For example:

chart.setOption({
    geo: [{
        left: 10,
        right: 10,
        top: 10,
        bottom: 10,
        preserveAspect: true,
        // ...
    }]
});
// or 
chart.setOption({
    series: [{
        type: 'graph',
        left: 10,
        right: 10,
        top: 10,
        bottom: 10,
        preserveAspect: true,
        // ...
    }]
});

Support clip

Support clip on geo component and series.map.

That is, if clip: true, hide the part that overflows the given layout rect defined by left/right/top/bottom/width/height.

For example:

chart.setOption({
    geo: [{
        clip: true, // default `false`
        // These props also defines the clip area.
        left: 20, 
        top: 50, 
        right: 50, 
        bottom: 50, 
        // ...
    }]
});
// or
chart.setOption({
    series: [{
        type: 'map',
        clip: true, // default `false`
        // These props also defines the clip area.
        left: 20, 
        top: 50, 
        right: 50, 
        bottom: 50, 
        // ...
    }]
});

Support cursor style change on roaming.

Support roamTigger: 'global' | 'selfRect' to switch roam area to global on only self bounding rect on geo, series.map, series.graph, series.tree, series.sankey, series.treemap.

Before:

After:

Support cursor style change when hovering the roaming enabled area to hint users.

Support roamTrigger: 'global' | 'selfRect'

    /**
     * Hover over an area where roaming is triggered.
     * - if `null`/`undefined`/`'selfRect'`, the trigger area is
     *   the intersection of "self bounding rect" and "clipping rect (if any)".
     * - if 'global', the trigger area is
     *   the intersection of "the entire canvas" and "clipping rect (if any)".
     * NOTE:
     *  The clipping rect, which can be enabled by `clip: true`, is typically the layout rect.
     *  The layout rect is typically determined by option `left`/`right`/`top`/`bottom`/`width`/`height`, some
     *  components/series, such as `geo` and `series.map` can also be determined by `layoutCenter`/`layoutSize`,
     *  and may modified by `preserveAspect`.
     */
    roamTrigger?: 'global' | 'selfRect' | NullUndefined

For example:

chart.setOption({
    geo: {
        roamTrigger: 'global', // by default 'selfRect' in geo component.
        // ...
    }
});

Fix the percent base of center for all coord/View coord sys based components/series

"View coord sys based components/series" is geo/series.map/series.graph/series.tree/series.sankey
Percent base of the center option is like:

chart.setOption({
    geo: {
        center: ['40%', '50%'],
        // ...
    }
});

Notice that historically the definition of this center option has always been irrelevant to some other series center like series[type='pie'].center - this center is a point on the raw data coord sys, rather than canvas viewport, and the unit is not necessarily pixel. For example, in geo component, the center option is [longitude, latitude]. This center option means that moving that center point to the center of the viewport.

#16904 introduced percentage string here, such as '33%'. But it was based on canvas width/height, which is not reasonable - the unit may incorrect, and it is unpredictable if the raw data coords are not calculated based on the current canvas rect. Therefore, the percentage value is changed to based on the raw data bounding rect since v6. Under this definition, users can use '0%' to move the top/left of the content to the center of the viewport, and use '100%' to move the bottom/right of the content to the center of the viewport.

This is a breaking change. To restore the previous behavior in v5:

chart.setOption({
    legacyViewCoordSysCenterBase: true,
    // ... 
});

Others

Enhance the behavior for roaming area overlapping

The upper one has higher precedence.

Fix some scaleLimit missing

Fix center and zoom option does not work in series.sankey.

And no relevant test case. (the roam is introduced in impl in #20321, due v6).

Some refactor and clarification of RoamController and roamHelper

[echarts-bot]

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

[100pah]

Thumbnail

The final refactor of Thumbnail is make here.
The previous thumbnail related PR:
#17471
#18039

Thumbnail is finally designed as a component.
New echarts component option is introduced:

const option = {
    series: {
        type: 'graph',
        // ...
    },
    thumbnail: {
        // ...
        seriesId: 'xxx', // Optional, use the first series.graph by default.
        seriesIndex: 0, // Optional, use the first series.graph by default.
    }
}

Currently thumbnail only support series.graph.
More other base map, such as geo, series.tree, series.sankey, can be supported based on the current data structure.

The thumbnail options:

{
    type?: string;

    id?: OptionId;
    name?: OptionName;

    z?: number;
    zlevel?: number;

    coordinateSystem?: string
    coordinateSystemUsage?: CoordinateSystemUsageOption
    coord?: CoordinateSystemDataCoord
    width?: PositionSizeOption;
    height?: PositionSizeOption;
    top?: PositionSizeOption;
    right?: PositionSizeOption;
    bottom?: PositionSizeOption;
    left?: PositionSizeOption;

    show?: boolean

    itemStyle?: ItemStyleOption
    windowStyle?: ItemStyleOption

    seriesIndex?: number | number[]
    seriesId?: string | string[]
}

The example is test/graph-thumbnail.html.

The minimal echarts option to enable thumbnail on graph:

chart.setOption({
    series: {
        type: 'graph',
        data: [{
            itemStyle: null,
            name: 'DRD2',
            value: 40,
            symbolSize: 40
        }, {
            itemStyle: null,
            name: 'ADORA2A',
            value: 0,
            symbolSize: 20
        }],
        links: [],
    },
    thumbnail: {}, // declare a thumbnail component, use the first series.graph by default.
});