[100pah]

Brief Information

This pull request is in the type of:

• bug fixing
• new feature
• others

See #19459 (comment)

[100pah]

This set of commits (until 7ef21ea ) update the following items:

Modify the axis break action to

chart.dispatch({
    type: 'expandAxisBreak',
    // breaks identifier:
    start: xxx,
    end: xxx,
    xAxisIndex: 'all', // or number, or number[]
});
chart.dispatch({
    type: 'collapseAxisBreak',
    // breaks identifier:
    start: xxx,
    end: xxx,
    xAxisIndex: 'all', // or number, or number[]
});
chart.dispatch({
    type: 'toggleAxisBreak',
    // breaks identifier:
    start: xxx,
    end: xxx,
    xAxisIndex: 'all', // or number, or number[]
});

This follows the pattern of the existing actions select, unselect, toggleSelect.

Refine the action event axisbreakchanged

All of the actions above trigger the same action axisbreakchanged.
This follow the format of selectchanged triggered (shared) by select, unselect, toggleSelect.

chart.on('axisbreakchanged', param => {
    // param: {
    //     type: 'axisbreakchanged';
    //     // 'expandAxisBreak' | 'collapseAxisBreak' | 'toggleAxisBreak';
    //     fromAction: 'expandAxisBreak' 
    //     fromActionPayload: ..., // payload
    //     // Only include specified breaks in action.
    //     breaks: [{
    //         start: ...,
    //         end: ...
    //         xAxisIndex: 1
    //         isExpanded: true
    //         old: { isExpanded: false }
    //     }, {
    //         start: ...,
    //         end: ...
    //         xAxisIndex: 1
    //         isExpanded: true
    //         old: { isExpanded: false }
    //         ...
    //     }]
    // }    
});

// And those TS types of actions and events are exported in `export/api/core.ts`.
export {
    AxisBreakChangedEvent,
    ExpandAxisBreakPayload,
    CollapseAxisBreakPayload,
    ToggleAxisBreakPayload,
} from '../component/axis/axisAction';

Introduce refineEvent in API registerAction

Based on the existing event selectchanged and the new event axisbreakchanged, abstract the behavior to refineEvent. It also removes the hard code (and FIXME) of register and trigger of selectchanged in echarts.ts; and axisbreakchanged is implemented by it.

echarts.registerAction({
    // Already have:
    type: 'doxxx',
    event: 'xxxchanged',
    action: (payload, ecModel, api) => {
        // ...
        return someInfoForRefiningEvent;
    },
    // New added:
    refineEvent: (actionResultBatch, payload, ecModel, api) => {
        // ...
        return {eventContent};
    }
});

• refineEvent is intended to create a user-friend event that differs from the original payload, while enabling feature connect, and being called at the last step of the "update" procedure to ensure the complete update of all models.
• If multiple actions need to share one event name, refineEvent must be used. e.g., actions 'doxxx' 'undoxxx' 'togglexxx' share one event name 'xxxchanged'. And that was not able to be achieved previously.

The rule of creating "public event" and "event for connect":

• If refineEvent provided, refineEvent creates the "public event", and "event for connect" is created internally by replicating the payload. This is because makeActionFromEvent requires the content of event to be the same as the original payload, while refineEvent creates a user-friend event that differs from the original payload.
• Else if ActionHandler returns an object, it is both the "public event" and the "event for connect".
  • (@deprecated, but keep this mechanism for backward compatibility).
• Else, replicate the payload as both the "public event" and "event for connect".

This API is only for the maintainer of echarts, rather than the users of echarts.

Fix break axis overlap with normal labels at the boundary of the axis.

Some renaming

• ScaleBreak -> AxisBreak
• axisLabel.formatter callback: break.type min/max -> start/end

Introduce axis.breakLabelLayout.moveOverlap

axis.breakLabelLayout.moveOverlap: boolean

• true: Default. Auto move apart the break labels if overlapping.
• false: Do not handle break labels overlap. See the case test/axis-break.html Introday stock. xAxis.breakLabelLayout.moveOverlap: false is set and a axisLabel.formatter is used to hide one break label and display the entire break info like 12:00/13:00.

Introduce label margin configuartion

This is relevant to overlap resolving.

• case 1: Break ends overlap. It can be moved apart a little to avoid overlap, see breakLabelLayout.moveOverlap.
• case 2: Normal axis labels overlap. Existing options axisLabel.hideOverlap, axisLabel.showMinValue, axisLabel.showMaxValue perform the hide strategy for this case.

(after applied the new introduced textMargin)

To achieve this goal, text bounding rect should be able to enlarge slightly to avoid them from visually touching.
And the expansion should be able to vary in top-bottom and left-right.

• Horizontally laid out labels may appear joined if there is no enough space between them.
  • e.g., appears 200123,456 but actually 200 123,456).

• Vertically laid-out or rotated stacked labels do not require much gap to appear neat and save space.

Thus, axisLabel.textMargin is introduced to provide this extra space for each label. In most case, its default value will suffice; users only need to know it when a detailed customization is required. textMargin follows CSS margin pattern, e.g., axisLabel.textMargin: [2, 10] means [top-bottom, left-right]. And textMargin is applied on the local rect of a text, rather than the rotated rect.

TL;DR: Introduce the name textMargin rather than reuse the existing names to avoid breaking change:

• axisLabel.margin historically has been used to indicate the gap between the axis and label.x/.y.
• label.minMargin conveys the same meaning as this textMargin but has a different nuance, it works like CSS margin collapse (gap = label1.minMargin/2 + label2.minMargin/2), and is applied on the rotated bounding rect rather than the original local rect.

zrender dependency is modified to v6

Test facilities upgrade or fixing

• Visual test:
  • Fix that visual test runtime thrown error may block the entire text execution without notification.
  • Recorded double mousedown without a mouseup will cause error in puppeteer. Added error message to users.
• testHelper:
  • Fixed some typo bugs.

[github-actions]

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

[echarts-bot]

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