V6.1.0 supplement

README.md

@@ -246,10 +246,10 @@ The template syntax follows [etpl](https://github.com/ecomfe/etpl/blob/master/do
 Summary of the commonly used syntax:
 ```template
 --- TEMPLATE EXPRESSION ---
-The template syntax and expressions are encolsed by delimiters `{{` and `}}`.
+The template syntax and expressions are enclosed by delimiters `{{` and `}}`.
 For example,
 {{ if: condition_expression }} xxx {{ /if }}
-The expressoin within `{{` and `}}` can be considered a (restricted) JS expression.
+The expression within `{{` and `}}` can be considered a (restricted) JS expression.
 For example,
 {{ if: ${someVar1} + 'abc' === '123abc' }} ... {{ /if }}
 {{ if: !${someVar2} }} ... {{ /if }}

en/api/echarts-instance.md

@@ -630,7 +630,7 @@ The format of the input `coord` and return type are defined by each coordinate s
 
 + [only yAxis](option.html#xAxis) or [only yAxis](option.html#yAxis):
 
-    For example, convert a axis coord to pixel value:
+    For example, convert an axis coord to pixel value:
     ```ts
     // In the xAxis with id 'x0' (type: number),
     // convert coord 3000 to the horizontal pixel coordinate:

en/option/component/axis-common.md

@@ -7,21 +7,39 @@ Set this to `true`, to prevent interaction with the axis.
 
 #${prefix} triggerEvent(boolean) = false
 
-Set this to `true` to enable triggering events.
+{{ use: partial-trigger-event-common-content() }}
 
 Parameters of the event include:
 
 ```ts
 {
-    // Component type: xAxis, yAxis, radiusAxis, angleAxis
-    // Each of which has an attribute for index, e.g., xAxisIndex for xAxis
-    componentType: string,
-    // Value on axis before being formatted.
-    // Click on value label to trigger event.
-    value: '',
-    // Name of axis.
-    // Click on label name to trigger event.
-    name: ''
+    // Component type, e.g.,
+    // 'xAxis', 'yAxis', 'radiusAxis', 'angleAxis',
+    // 'singleAxis', 'parallelAxis', 'radar', etc.
+    componentType: string;
+    componentIndex: number;
+    // The same as `componentIndex`.
+    [componentType]Index?: number;
+
+    // The emitter of this event.
+    targetType: 'axisLabel' | 'axisName';
+
+    // A label string formatted by a built-in formatter;
+    // User-provided `axisLabel.formatter` does not affect this value.
+    // Present when `targetType: 'axisLabel'`.
+    value?: string;
+
+    // Present only if this is an axis label for "axis break".
+    break?: {
+        // Parsed break start.
+        start?: number;
+        // Parsed break start.
+        end?: number;
+    };
+
+    // `axis.name`.
+    // Present when `targetType: 'axisName'`.
+    name?: string;
 }
 ```
 
@@ -790,7 +808,7 @@ Option:
     Time axis, suitable for continuous time series data. As compared to value axis, it has a better formatting for time and a different tick calculation method. For example, it decides to use month, week, day or hour for tick based on the range of span.
 
 + `'log'`
-    Log axis, suitable for log data. Stacked bar or line series with `type: 'log'` axes may lead to significant visual errors and may have unintended effects in certain circumstances. Their use should be avoided.
+    Logarithmic axis. It is useful when the data spans a very large range of values or when the important pattern is about multiplicative change rather than additive change.
 
 
 {{ target: axis-common }}
@@ -1223,6 +1241,8 @@ Example:
 formatter: '{value} kg'
 // Use callback.
 formatter: function (value, index, extra?) {
+    // Notice: when using `customValues`, parameter `index` is
+    // provided since `v6.1.0`.
     return value + 'kg';
 }
 ```
@@ -1237,7 +1257,7 @@ formatter: function (value, index, extra?) {
 The break info can be obtained from the `extra` param:
 ```ts
 type AxisLabelFormatterExtraBreakPart = {
-    // If this label is a axis break start or end.
+    // If this label is an axis break start or end.
     break?: {
         type: 'start' | 'end';
         // The parsed `start`/`end`, always be numbers, and has been

en/option/component/data-zoom-inside.md

@@ -77,3 +77,20 @@ How to trigger data window move. Optional values:
 
 Whether to prevent default behavior of mouse move event.
 
+
+{{ use: partial-cursor(
+    prefix = "#",
+    version = "6.1.0",
+    defaultValue = "grab",
+    prop = "cursorGrab",
+    targetDesc = "when mouse hovers over the grabbable area"
+) }}
+
+{{ use: partial-cursor(
+    prefix = "#",
+    version = "6.1.0",
+    defaultValue = "grabbing",
+    prop = "cursorGrabbing",
+    targetDesc = "when grabbing"
+) }}
+

en/option/component/legend.md

@@ -7,7 +7,9 @@ Legend component.
 
 Legend component shows symbol, color and name of different series. You can click legends to toggle displaying series in the chart.
 
-In ECharts 3, a single echarts instance may contain multiple legend components, which makes it easier for the layout of multiple legend components.
+See [legend.data](~legend.data) for the matching rules between legend items and series or series data items.
+
+A single echarts instance may contain multiple legend components, which makes it easier for the layout of multiple legend components. (since `v3.0.0`)
 
 If there have to be too many legend items, [vertically scrollable legend](${galleryEditorPath}pie-legend&edit=1&reset=1) or [horizontally scrollable legend](${galleryEditorPath}radar2&edit=1&reset=1) are options to paginate them. Check [legend.type](~legend.type) please.
 
@@ -192,11 +194,107 @@ Icon of the legend items.
 
 ## data(Array)
 
-Data array of legend. An array item is usually a `name` representing string. (If it is a [pie chart](~series-pie), it could also be the `name` of a single data in the pie chart) of a series. Legend component would automatically calculate the color and icon according to series. Special string `''` (null string) or `'\n'` (new line string) can be used for a new line.
+<br>
+
+**Explicitly Specify `legend.data`:**
+
+`legend.data` is an array. An array item can be a string (representing `name`) or an object (containing a `name` field).
+
+If the `name` of an array item is a special string `''` or `'\n'`, this array item is only used to create a line break.
+```js
+legend: {
+    data: ['a', 'b', '\n', 'c', 'd']
+    // The final displayed items are (line wrapped):
+    //  'a' 'b'
+    //  'c' 'd'
+}
+```
+
+If the `name` of an array item dose not match any `LEGEND_TARGET`, this legend item is ignored. (See also the description of `LEGEND_TARGET` below.)
+
+<br>
 
-If `data` is not specified, it will be auto collected from series. For most of series, it will be collected from [series.name](~series.name) or the dimension name specified by `seriesName` of [series.encode](~series.encode). For some types of series like [pie](~series-pie) and [funnel](~series-funnel), it will be collected from the name field of `series.data`.
+**Automatically Collect `legend.data`:**
+
+If `legend.data` is not explicitly specified, it is automatically collected from `series` or `dataset`.
+- It is basically collected from [series.name](~series.name).
+- It can also collect from `dataset` according to the dimension specified in `seriesName` field in [series.encode](~series.encode).
+- Some series supports `LEGEND_CONTROL_SERIES_DATA_ITEM` (see details below). It is collected from the `name` field (if present) of each `series.data` item. For a single series, if these `name`s from `series.data` are collected, series name is no longer collected.
+
+Some examples:
+```ts
+option = {
+    legend: {/* No `legend.data` field is specified. */},
+    xAxis: {},
+    yAxis: {},
+    series: [{
+        type: 'line', name: 'lineA', data: [11, 22]
+    }, {
+        type: 'line', name: 'lineB', data: [111, 222]
+    }, {
+        type: 'pie', name: 'pieC',
+        data: [
+            {name: 'pieItemA', value: 9},
+            {name: 'pieItemB', value: 8},
+            {name: 'pieItemC', value: 7},
+        ]
+    }],
+}
+// The final displayed legend items are:
+//  'lineA' 'lineB' 'pieItemA' 'pieItemB' 'pieItemC'
+```
+```ts
+option = {
+    legend: {/* No `legend.data` field is specified. */},
+    dataset: {
+        source: [
+            [null, 'nameH', 'nameI', 'nameJ', 'nameK'],
+            ['2012-01', 32, 65, 71, 31],
+            ['2012-02', 41, 67, 89, 23],
+            ['2012-03', 58, 61, 97, 12],
+            ['2012-04', 67, 73, 105, 9],
+            ['2012-05', 72, 67, 122, 18],
+        ]
+    },
+    xAxis: {type: 'category'},
+    yAxis: {},
+    series: [{
+        type: 'bar',
+        // Retrieve `seriesName` from dataset column with index 1; get 'nameH'.
+        encode: {x: 0, y: 1, seriesName: 1}
+    }, {
+        type: 'bar',
+        // Retrieve `seriesName` from dataset column with index 3; get 'nameJ'.
+        encode: { x: 0, y: 3, seriesName: 3 }
+    }, {
+        type: 'bar',
+        // Retrieve `seriesName` from dataset column with index 3; get 'nameI'.
+        encode: { x: 0, y: 2, seriesName: 2 }
+    }]
+};
+// The final displayed legend items are:
+//  'nameH' 'nameJ' 'nameI'
+```
 
-If you need to set the style for a single item, you may also set the configuration of it. In this case, `name` attribute is used to represent name of `series`.
+<br>
+
+**LEGEND_TARGET and LEGEND_MATCHING_RULES:**
+
+A legend item can control the visibility of a entire series or a series data item (see `LEGEND_CONTROL_SERIES_DATA_ITEM` below). They can be called as `LEGEND_TARGET`. A `LEGEND_TARGET` is under control if and only if the `name` from `legend.data` (either explicitly specified or automatically collected) matches the name from `LEGEND_TARGET`, i.e., matches series names or series data item names.
+
+This mapping is allowed to be many-to-many. For example, if multiple series share the same series name, they can be controlled by a single legend item.
+
+<br>
+
+**LEGEND_CONTROL_SERIES_DATA_ITEM:**
+
+These series support that legend items control each series data items: [pie](~series-pie), [funnel](~series-funnel), [chord](~series-chord), [graph](~series-graph), [radar](~series-radar) and [themeRiver](~series-themeRiver). They are matched according to `name` fields of legend items and series data items.
+
+<br>
+
+**Legend Item Styles:**
+
+If you need to set the style for a single item, you may also set the configuration of it.
 
 Example:
 ```
@@ -498,11 +596,28 @@ The gap between selector button and legend component.
 
 ## triggerEvent(boolean) = false
 
-{{ use: partial-version(
+{{ use: partial-trigger-event-common-content(
     version = "6.0.0"
 ) }}
 
-Set this to `true` to enable triggering events.
+Parameters of the event include:
+
+```ts
+{
+    componentType: 'legend';
+    // legend component index. (based on echarts option)
+    componentIndex: number;
+    // The `name` of this legend item, which controls the
+    // visibility of LEGEND_TARGET.
+    // See `legend.data` for more details.
+    value: string;
+    // The index of the triggering legend item.
+    dataIndex: number;
+    // The index of the first series that matches
+    // this legend item. (based on echarts option)
+    seriesIndex: number;
+}
+```
 
 
 {{ target: partial-legend-style }}

en/option/component/matrix.md

@@ -121,3 +121,30 @@ matrix: {
     // ...
 }
 ```
+
+## triggerEvent(boolean) = false
+
+{{ use: partial-trigger-event-common-content(
+    version = "6.1.0"
+) }}
+
+Parameters of the event include:
+
+```ts
+{
+    componentType: 'matrix';
+    // legend component index. (based on echarts option)
+    componentIndex: number;
+    // The same as `componentIndex`.
+    matrixIndex: number;
+
+    targetType: 'x' | 'y' | 'body' | 'corner';
+
+    // Displayed cell text.
+    name: string;
+    // Cell value (provided by echarts option).
+    value: textValue;
+    // Cell coord. That is `MatrixXYLocator[]`.
+    coord: number;
+}
+```

en/option/component/title.md

@@ -106,7 +106,17 @@ Optional values: `'auto'`, `'top'`, `'bottom'`, `'middle'`.
 
 ## triggerEvent(boolean) = false
 
-Set this to `true` to enable triggering events
+{{ use: partial-trigger-event-common-content() }}
+
+The parameters of the event:
+
+```ts
+{
+    componentType: 'title';
+    // The index of the title component (base on echarts option)
+    componentIndex: number;
+}
+```
 
 ## padding(number|Array) = 5
 

en/option/partial/cursor.md

@@ -1,15 +1,15 @@
 
 {{ target: partial-cursor }}
 
-#${prefix|default('#')} cursor(string) = 'pointer'
+#${prefix|default('#')} ${prop|default("cursor")}(string) = ${defaultValue|default("pointer")}
 
-<ExampleUIControlEnum options="auto,pointer,move" default="pointer" />
+<ExampleUIControlEnum options="auto,pointer,move,grab,grabbing" default="pointer" />
 
 {{ if: ${version} }}
 {{ use: partial-version(
     version = ${version}
 ) }}
 {{ /if }}
 
-The mouse style when mouse hovers on an element, the same as `cursor` property in `CSS`.
+The mouse style ${targetDesc|default("when mouse hovers over an element")}, the same as `cursor` property in `CSS`.
 

en/option/partial/item-style.md

@@ -23,6 +23,8 @@ Supports callback functions, in the form of:
 Input parameters are `seriesIndex`, `dataIndex`, `data`, `value`, and etc. of data item.
 {{ /if }}
 
+${colorExtraInfo}
+
 #${prefix} borderColor(Color) = ${defaultBorderColor|default("'#000'")}
 
 <ExampleUIControlColor />

en/option/partial/matrix-header.md

@@ -44,9 +44,9 @@ data: [{
 }]
 ```
 
-If [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) is not provided, it will be collected from `series.data` or `dataset.soruce`.
+If [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) is not provided, and [matrix.${matrixDim}.length](~matrix.${matrixDim}.length) is provided, a [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) is automatically composed according to [matrix.${matrixDim}.length](~matrix.${matrixDim}.length).
 
-See [matrix data collection example](${galleryEditorPath}matrix-mini-bar-data-collection&edit=1&reset=1).
+Otherwise, if either of them are provided, [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) will be automatically collected from `series.data` or `dataset.source`. See [matrix data collection example](${galleryEditorPath}matrix-mini-bar-data-collection&edit=1&reset=1).
 
 And in this case [series.encode](~series-scatter.encode) can be used to specify the dimension from which value is collected. For example,
 ```js
@@ -81,6 +81,15 @@ See [matrix.${matrixDim}.data](~matrix.${matrixDim}.data).
 {{ use: partial-matrix-dimension-size-desc }}
 
 
+### length(number)
+
+{{ use: partial-version(version = "6.1.0") }}
+
+Users can omit [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) but only provide a [matrix.${matrixDim}.length](~matrix.${matrixDim}.length), which defines the {{ if: ${matrixDim} === 'x' }}column{{ else }}row{{ /if }} number. This is useful for headless matrix (i.e., [matrix.${matrixDim}.show](~matrix.${matrixDim}.show) is `false`), where only column and row number need to be specified.
+
+Note: [matrix.${matrixDim}.length](~matrix.${matrixDim}.length) is ignored if [matrix.${matrixDim}.data](~matrix.${matrixDim}.data) is specified.
+
+
 {{ use: partial-matrix-cell-style-option(
     prefix='##',
     name=${name}