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

(2) Support `clip` on geo/series.map
(3) Support `roamTigger: 'global' | 'selfRect'` to switch roam area to global on only self bounding rect.
(4) Support cursor style change when hovering the roaming enabled area to hint users.
(5) Fix that 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).
(6) Fix the percent base of `center` (such as `center: ['40%', '50%']`) for all View coord sys based components/series (geo/series.map/series.graph/series.tree/series.sankey). #16904 introcuded 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 `View['_rect']` is not calculated based on the current canvas rect. Therefore the percentage value is changed to based on `View['_rect'].width/height` since v6. Under this definition, users can use '0%' to map the top-left of `View['_rect']` to the center of `View['_viewRect']`.
(7) Enhance the behavior for roaming area overlapping - the upper one has higher precedence.
(8) Fix some `scaleLimit` missing.
(9) Some refactor and clarification of `RoamController` and `roamHelper`.

Author: 100pah

src/action/roamHelper.ts

@@ -43,7 +43,8 @@ import {
     GraphEdgeItemObject,
     OptionDataValueNumeric,
     CallbackDataParams,
-    DefaultEmphasisFocus
+    DefaultEmphasisFocus,
+    PreserveAspectMixin
 } from '../../util/types';
 import SeriesModel from '../../model/Series';
 import Graph from '../../data/Graph';
@@ -144,7 +145,8 @@ export interface GraphSeriesOption
     SeriesOnGeoOptionMixin, SeriesOnSingleOptionMixin,
     SymbolOptionMixin<CallbackDataParams>,
     RoamOptionMixin,
-    BoxLayoutOptionMixin {
+    BoxLayoutOptionMixin,
+    PreserveAspectMixin {
 
     type?: 'graph'
 

src/chart/graph/GraphSeries.ts

@@ -25,7 +25,6 @@ import {
     updateViewOnPan,
     RoamControllerHost
 } from '../../component/helper/roamHelper';
-import {onIrrelevantElement} from '../../component/helper/cursorHelper';
 import * as graphic from '../../util/graphic';
 import adjustEdge from './adjustEdge';
 import {getNodeGlobalScale} from './graphHelper';
@@ -45,6 +44,7 @@ import { simpleLayoutEdge } from './simpleLayoutHelper';
 import { circularLayout, rotateNodeLabel } from './circularLayoutHelper';
 import { clone, extend } from 'zrender/src/core/util';
 import ECLinePath from '../helper/LinePath';
+import { NullUndefined } from '../../util/types';
 
 function isViewCoordSys(coordSys: CoordinateSystem): coordSys is View {
     return coordSys.type === 'view';
@@ -127,7 +127,7 @@ class GraphView extends ChartView {
 
         this._updateNodeAndLinkScale();
 
-        this._updateController(seriesModel, ecModel, api);
+        this._updateController(null, seriesModel, api);
 
         clearTimeout(this._layoutTimeout);
         const forceLayout = seriesModel.forceLayout;
@@ -251,29 +251,29 @@ class GraphView extends ChartView {
     }
 
     private _updateController(
+        clipRect: graphic.BoundingRect | NullUndefined,
         seriesModel: GraphSeriesModel,
-        ecModel: GlobalModel,
         api: ExtensionAPI
     ) {
         const controller = this._controller;
         const controllerHost = this._controllerHost;
-        const group = this.group;
-
-        controller.setPointerChecker((e, x, y) => {
-            const rect = group.getBoundingRect();
-            rect.applyTransform(group.transform);
-            return rect.contain(x, y)
-                && !this._thumbnail.contain(x, y)
-                && !onIrrelevantElement(e, api, seriesModel);
-        });
+        const coordSys = seriesModel.coordinateSystem;
 
-        if (!isViewCoordSys(seriesModel.coordinateSystem)) {
+        if (!isViewCoordSys(coordSys)) {
             controller.disable();
             return;
         }
-        controller.enable(seriesModel.get('roam'));
+        controller.enable(seriesModel.get('roam'), {
+            api,
+            zInfo: {component: seriesModel},
+            triggerInfo: {
+                roamTrigger: seriesModel.get('roamTrigger'),
+                isInSelf: (e, x, y) => coordSys.containPoint([x, y]),
+                isInClip: (e, x, y) => !clipRect || clipRect.contain(x, y),
+            },
+        });
         controllerHost.zoomLimit = seriesModel.get('scaleLimit');
-        controllerHost.zoom = seriesModel.coordinateSystem.getZoom();
+        controllerHost.zoom = coordSys.getZoom();
 
         controller
             .off('pan')
@@ -292,6 +292,9 @@ class GraphView extends ChartView {
         dx: number,
         dy: number
     ): void {
+        // FIXME: should do nothing except `api.dispatchAction` here, the other logic
+        //  should be performed in the action handler; otherwise, it causes inconsistency
+        //  if user triggers this action explicitly.
         updateViewOnPan(this._controllerHost, dx, dy);
         api.dispatchAction({
             seriesId: seriesModel.id,
@@ -309,6 +312,9 @@ class GraphView extends ChartView {
         originX: number,
         originY: number
     ) {
+        // FIXME: should do nothing except `api.dispatchAction` here, the other logic
+        //  should be performed in the action handler; otherwise, it causes inconsistency
+        //  if user triggers this action explicitly.
         updateViewOnZoom(this._controllerHost, scale, originX, originY);
         api.dispatchAction({
             seriesId: seriesModel.id,

src/chart/graph/GraphView.ts

@@ -8,8 +8,8 @@ import BoundingRect from 'zrender/src/core/BoundingRect';
 import * as matrix from 'zrender/src/core/matrix';
 import * as vector from 'zrender/src/core/vector';
 import SeriesModel from '../../model/Series';
-import { BoxLayoutOptionMixin, ItemStyleOption } from '../../util/types';
-import RoamController, { RoamEventDefinition, RoamType } from '../../component/helper/RoamController';
+import { BoxLayoutOptionMixin, ItemStyleOption, RoamOptionMixin } from '../../util/types';
+import RoamController, { RoamEventDefinition } from '../../component/helper/RoamController';
 import Eventful from 'zrender/src/core/Eventful';
 import tokens from '../../visual/tokens';
 
@@ -60,7 +60,7 @@ class Thumbnail extends Eventful<Pick<RoamEventDefinition, 'zoom' | 'pan'>> {
     render(opt: {
         seriesModel: GraphSeriesModel;
         api: ExtensionAPI;
-        roamType: RoamType;
+        roamType: RoamOptionMixin['roam'];
         z2Setting: ThumbnailZ2Setting;
         seriesBoundingRect: BoundingRect,
         renderThumbnailContent: (viewGroup: graphic.Group) => void
@@ -85,22 +85,13 @@ class Thumbnail extends Eventful<Pick<RoamEventDefinition, 'zoom' | 'pan'>> {
         const itemStyle = itemStyleModel.getItemStyle();
         itemStyle.fill = seriesModel.ecModel.get('backgroundColor') || tokens.color.neutral00;
 
-        // Try to use border-box in thumbnail, see https://github.com/apache/echarts/issues/18022
-        const boxBorderWidth = itemStyle.lineWidth || 0;
+        const refContainer = layout.createBoxLayoutReference(seriesModel, api).refContainer;
         const boxContainBorder = layout.getLayoutRect(
-            {
-                left: thumbnailModel.get('left', true),
-                top: thumbnailModel.get('top', true),
-                right: thumbnailModel.get('right', true),
-                bottom: thumbnailModel.get('bottom', true),
-                width: thumbnailModel.get('width', true),
-                height: thumbnailModel.get('height', true)
-            },
-            {
-                width: api.getWidth(),
-                height: api.getHeight()
-            }
+            layout.getBoxLayoutParams(thumbnailModel, true),
+            refContainer
         );
+        // Try to use border-box in thumbnail, see https://github.com/apache/echarts/issues/18022
+        const boxBorderWidth = itemStyle.lineWidth || 0;
         const borderBoundingRect = graphic.expandOrShrinkRect(
             boxContainBorder.clone(), boxBorderWidth / 2, true, true
         );
@@ -155,7 +146,7 @@ class Thumbnail extends Eventful<Pick<RoamEventDefinition, 'zoom' | 'pan'>> {
         windowRect.__r = windowStyleModel.get('borderRadius', true);
         clipGroup.add(windowRect);
 
-        this._resetRoamController(opt.roamType);
+        this._resetRoamController(opt.roamType, z2Setting.background);
 
         this.updateWindow();
     }
@@ -188,14 +179,23 @@ class Thumbnail extends Eventful<Pick<RoamEventDefinition, 'zoom' | 'pan'>> {
         this._mtThumbnailToSerise = matrix.invert([], this._mtSeriesToThumbnail);
     }
 
-    private _resetRoamController(roamType: RoamType): void {
+    private _resetRoamController(
+        roamType: RoamOptionMixin['roam'],
+        z2: number
+    ): void {
         let thumbnailController = this._thumbnailController;
         if (!thumbnailController) {
             thumbnailController = this._thumbnailController = new RoamController(this._api.getZr());
-            thumbnailController.setPointerChecker((e, x, y) => this.contain(x, y));
         }
 
-        thumbnailController.enable(roamType);
+        thumbnailController.enable(roamType, {
+            api: this._api,
+            zInfo: {component: this._seriesModel, z2},
+            triggerInfo: {
+                roamTrigger: null,
+                isInSelf: (e, x, y) => this.contain(x, y)
+            }
+        });
         thumbnailController
             .off('pan')
             .off('zoom')

src/chart/graph/Thumbnail.ts

@@ -19,7 +19,7 @@
 
 // FIXME Where to create the simple view coordinate system
 import View from '../../coord/View';
-import {createBoxLayoutReference, getLayoutRect} from '../../util/layout';
+import {createBoxLayoutReference, getLayoutRect, applyPreserveAspect} from '../../util/layout';
 import * as bbox from 'zrender/src/core/bbox';
 import GraphSeriesModel, { GraphNodeItemOption } from './GraphSeries';
 import ExtensionAPI from '../../core/ExtensionAPI';
@@ -32,7 +32,8 @@ function getViewRect(seriesModel: GraphSeriesModel, api: ExtensionAPI, aspect: n
     const option = extend(seriesModel.getBoxLayoutParams(), {
         aspect: aspect
     });
-    return getLayoutRect(option, layoutRef.refContainer);
+    const viewRect = getLayoutRect(option, layoutRef.refContainer);
+    return applyPreserveAspect(seriesModel, viewRect, aspect);
 }
 
 export default function createViewCoordSys(ecModel: GlobalModel, api: ExtensionAPI) {
@@ -79,7 +80,7 @@ export default function createViewCoordSys(ecModel: GlobalModel, api: ExtensionA
             const bbWidth = max[0] - min[0];
             const bbHeight = max[1] - min[1];
 
-            const viewCoordSys = new View();
+            const viewCoordSys = new View(null, {api, ecModel});
             viewCoordSys.zoomLimit = seriesModel.get('scaleLimit');
 
             viewCoordSys.setBoundingRect(
@@ -90,7 +91,7 @@ export default function createViewCoordSys(ecModel: GlobalModel, api: ExtensionA
             );
 
             // Update roam info
-            viewCoordSys.setCenter(seriesModel.get('center'), {api, ecModel});
+            viewCoordSys.setCenter(seriesModel.get('center'));
             viewCoordSys.setZoom(seriesModel.get('zoom'));
 
             viewList.push(viewCoordSys);

src/chart/graph/createView.ts

@@ -29,7 +29,7 @@ import createView from './createView';
 import View from '../../coord/View';
 import GraphView from './GraphView';
 import GraphSeriesModel from './GraphSeries';
-import { RoamPayload, updateCenterAndZoom } from '../../action/roamHelper';
+import { RoamPayload, updateCenterAndZoomInAction } from '../../component/helper/roamHelper';
 import GlobalModel from '../../model/Global';
 import { noop } from 'zrender/src/core/util';
 import type ExtensionAPI from '../../core/ExtensionAPI';
@@ -79,7 +79,7 @@ export function install(registers: EChartsExtensionInstallRegisters) {
         }, function (seriesModel: GraphSeriesModel) {
             const coordSys = seriesModel.coordinateSystem as View;
 
-            const res = updateCenterAndZoom(coordSys, payload, undefined, api);
+            const res = updateCenterAndZoomInAction(coordSys, payload, seriesModel.get('scaleLimit'));
 
             seriesModel.setCenter
                 && seriesModel.setCenter(res.center);

src/chart/graph/install.ts

@@ -317,6 +317,7 @@ class SankeySeriesModel extends SeriesModel<SankeySeriesOption> {
 
         // true | false | 'move' | 'scale', see module:component/helper/RoamController.
         roam: false,
+        roamTrigger: 'global',
         center: null,
         zoom: 1,