Merge pull request #382 from apache/dev

doc: merge doc for 5.5.0

en/api/echarts.md

@@ -36,7 +36,7 @@ Creates an ECharts instance, and returns an [echartsInstance](~echartsInstance).
 
     + `devicePixelRatio` Ratio of one physical pixel to the size of one device independent pixels. Browser's `window.devicePixelRatio` is used by default.
     + `renderer`  Supports `'canvas'` or `'svg'`. See [Render by Canvas or SVG](${handbookPath}best-practices/canvas-vs-svg).
-    + `ssr` Whether to use server-side rendering. Only available in SVG rendering mode. When enabled, it will no longer render automatically every frame, you have to use the [renderToSVGString](~echartsInstance.renderToSVGString) method to get the rendered SVG string.
+    + `ssr` Whether to use server-side rendering. Only available in SVG rendering mode. When enabled, it will no longer render automatically every frame, you have to use the [renderToSVGString](~echartsInstance.renderToSVGString) method to get the rendered SVG string. See [Server Side Rendering](${handbookPath}how-to/cross-platform/server).
     + `useDirtyRect` Enable dirty rectangle rendering or not, `false` by default. See [New features in ECharts 5](${handbookPath}basics/release-note/v5-feature).
     + `useCoarsePointer` Whether to expand the response area when interacting with elements. `null` means enabling for mobile devices; `true` means always enabling; `false` means always disabling. See [Coarse Pointer](${handbookPath}how-to/interaction/coarse-pointer) for more information.
     + `pointerSize` Size of expanded interaction size in pixels. It should be used along with `opts.useCoarsePointer`.

en/option/component/angle-axis.md

@@ -19,10 +19,22 @@ The index of angle axis in Polar Coordinate. The first axis is used by default.
 
 Starting angle of axis. 90 degrees by default, standing for top position of center. 0 degree stands for right position of center.
 
-The following shows an example with startAngle of 45 deg.
+The following shows an example with `startAngle` of 45 deg.
 
 ~[400x400](${galleryViewPath}doc-example/polar-start-angle&edit=1&reset=1)
 
+## endAngle(number) = null
+
+<ExampleUIControlAngle default="null" min="-360" max="360" step="1" />
+
+{{ use: partial-version(version = '5.5.0') }}
+
+Ending angle of axis. `null` by default, standing for a whole circle.
+
+The following shows an example with `endAngle` of -180 deg.
+
+~[400x400](${galleryViewPath}doc-example/polar-end-angle&edit=1&reset=1)
+
 ## clockwise(boolean) = true
 
 <ExampleUIControlBoolean default="true" />

en/option/component/axis-common.md

@@ -147,6 +147,62 @@ Whether to show the label of the min tick. Optional values: `true`, `false`, `nu
 
 Whether to show the label of the max tick. Optional values: `true`, `false`, `null`. It is auto determined by default, that is, if labels are overlapped, the label of the max tick will not be displayed.
 
+{{ if: ${componentType} === 'xAxis' }}
+
+##${prefix} alignMinLabel(string) = null
+
+{{ use: partial-version(version = '5.5.0') }}
+
+Alignment of the label of the min tick. If set to be `null`, it's the same with other labels .
+
+Options are:
++ `'left'`
++ `'center'`
++ `'right'`
++ `null` (default)
+
+##${prefix} alignMaxLabel(string) = null
+
+{{ use: partial-version(version = '5.5.0') }}
+
+Alignment of the label of the max tick. If set to be `null`, it's the same with other labels. See [align](~${componentType}.axisLabel.align).
+
+Options are:
++ `'left'`
++ `'center'`
++ `'right'`
++ `null` (default)
+
+{{ /if }}
+
+{{ if: ${componentType} === 'yAxis' }}
+
+##${prefix} verticalAlignMinLabel(string) = null
+
+{{ use: partial-version(version = '5.5.0') }}
+
+Vertical alignment of the label of the min tick. If set to be `null`, it's the same with other labels. See [verticalAlign](~${componentType}.axisLabel.verticalAlign).
+
+Options are:
++ `'top'`
++ `'middle'`
++ `'bottom'`
++ `null` (default)
+
+##${prefix} verticalAlignMaxLabel(string) = null
+
+{{ use: partial-version(version = '5.5.0') }}
+
+Vertical alignment of the label of the max tick. If set to be `null`, it's the same with other labels. See [verticalAlign](~${componentType}.axisLabel.verticalAlign).
+
+Options are:
++ `'top'`
++ `'middle'`
++ `'bottom'`
++ `null` (default)
+
+{{ /if }}
+
 ##${prefix} hideOverlap(boolean)
 
 <ExampleUIControlBoolean />

en/option/component/tooltip.md

@@ -199,6 +199,8 @@ Useful when tooltip is cut because of `'overflow: hidden'` set on outer dom of c
     version = "4.7.0"
 ) }}
 
+(DEPRECATED, use [appendTo](~tooltip.appendTo) instead.)
+
 Whether to append the tooltip DOM element as a child of the `<body>` of the HTML page, when using [renderMode](~tooltip.renderMode) `'html'`.
 
 By default `false`, means that the tooltip DOM element will be one of a descendant of its echarts DOM container. But that means that the tooltip might be cut when overflow the container if some of the ancestors DOM element of the echarts container are styled with `overflow: hidden`. This case could also be resolved by setting [tooltip.confine](~tooltip.confine), but it might not suitable for all scenarios.
@@ -207,6 +209,20 @@ Here we provide `appendToBody: true` to auto append the tooltip element to `<bod
 
 Note that it also works when CSS transform used.
 
+## appendTo() = Function | HTMLElement | string | null
+
+{{ use: partial-version(
+    version = "5.5.0"
+) }}
+
+Which DOM element to append the tooltip to. Only avaiable when using [renderMode](~tooltip.renderMode) `'html'`.
+
+The default value is `null``, which means that the tooltip's DOM node will be added as a descendant node of the chart’s DOM container. However, this approach can cause the tooltip to be truncated if it extends beyond the container, due to ancestors of the chart's DOM container having overflow: hidden set. This issue can be partially addressed using tooltip.confine, but it may not cover all scenarios.
+
+For such scenarios, `appendTo` can be specified. When it is a function, the interface is in the form of `(chartContainer: HTMLElement) => HTMLElement | undefined | null`, which means it returns the node that the tooltip's DOM node should be added to. Returning `undefined` or `null` indicates that the default logic described above should be used. Returning an HTMLElement means that it should be added under that node.
+
+Note that it also works when CSS transform used.
+
 ## className(string)
 
 <ExampleUIControlText />

en/option/partial/clip.md

@@ -16,7 +16,8 @@ If clip the overflow on the coordinate system. Clip results varies between serie
 + Line：Clip the overflowed line.
 + Lines: Clip all the overflowed.
 + Candlestick: Ignore the elements exceeds the coordinate system.
++ PictorialBar: Clip all the overflowed. (Supported since v5.5.0)
 + Custom: Clip all the olverflowed.
 
-All these series have default value `true` except custom series. Set it to `false` if you don't want to clip.
+All these series have default value `true` except pictorialBar and custom series. Set it to `false` if you don't want to clip.
 

en/option/partial/encode-dimensions.md

@@ -60,9 +60,14 @@ encode: {
     // Using dimensions[3] as the name of each data item. This is useful in charts like
     // 'pie', 'funnel', where data item name can be displayed in legend.
     itemName: 3,
-    // Using dimensions[4] as the groupId of each data item. groupId will be used to categorize the data. And to determine
-    // How the merge and split animation are performed in the universal transition. See universalTransition option for detail.
-    itemGroupId: 4
+    // Using dimensions[4] as the group ID for each data item. With universalTransition enabled,
+    // the data items from the old option and those from the new one, if sharing a same group ID,
+    // will then be matched and applied to a proper animation after `setOption` is called.
+    itemGroupId: 4,
+    // Using dimension[5] as the child group ID for each data item. This option is introduced to
+    // make multiple levels drilldown and aggregation animation come true. See childGroupId for more.
+    // Since v5.5.0
+    itemChildGroupId: 5
 }
 
 // These properties only work in cartesian(grid) coordinate system:

en/option/partial/group-id.md

@@ -3,15 +3,63 @@
 
 ## dataGroupId(string)
 
-A groupID common to all data in the series. the groupID will be used to classify the data and determine how merge and split animations are performed in the universal transition animation.
-
-If you are using the [dataset](~dataset) component to represent the data, it is recommended to use `encode.itemGroupID` to specify which dimension is encoded as the groupID.
+A group ID assigned to all data items in the series.
 
+This option has a lower priority than `groupId`, which means when `groupId` is specified for a certain data item the `dataGroupId` will be simply ignored for that data item. For more information, please see `series.data.groupId`.
 
 
 {{ target: partial-data-group-id }}
 
 #${prefix} groupId(string)
 
-The groupID of this data item. groupID will be used to classify the data.
+The group ID of a data item. When `universalTransition` is enabled, the data items from the old option and those from the new one, if sharing a same group ID, will then be matched and applied to a proper animation after `setOption` is called.
+
+If a data item is not specified with a `groupId`, Apache ECharts will try to use `series.dataGroupId` as the group ID for the data item. If `series.dataGroupId` is not specified either, Apache ECharts will fall back to using the data item's ID as its group ID.
+
+If you are using the [dataset](~dataset) component to represent data, you are recommended to use `encode.itemGroupId` to specify the dimension that is to be encoded as the group ID.
+
+
+{{ target: partial-data-child-group-id }}
+
+#${prefix} childGroupId(string)
+
+{{ use: partial-version(
+    version = "5.5.0"
+) }}
+
+The group ID of the child data of a data item. This option is introduced to make multiple levels drilldown and aggregation animation possilbe.
+
+~[700x300](${galleryViewPath}doc-example/bar-multi-drilldown&edit=1&reset=1)
+
+Before `childGroupId` is introduced, developers actually can use `groupId` to make drilldown and aggregation animation already, but with the limit on the times that a continious drilldown or aggregation can happen, which is only one time.
+
+`childGroupId`, together with `groupId`, help to form "parent-child" relationships between data items of different options, such as:
+
+```text
+data: [                        data: [                        data: [
+  {                              {                              {
+    name: 'Animals',               name: 'Dogs',                  name: 'Corgi',
+    value: 3,                      value: 3,                      value: 5,
+    groupId: 'things',             groupId: 'animals',            groupId: 'dogs'
+    childGroupId: 'animals'        childGroupId: 'dogs'         },
+  },                             },                             {
+  {                              {                                name: 'Bulldog',
+    name: 'Fruits',                name: 'Cats',                  value: 6,
+    value: 3,                      value: 4,                      groupId: 'dogs'
+    groupId: 'things',             groupId: 'animals',          },
+    childGroupId: 'fruits'         childGroupId: 'cats',        {
+  },                             },                               name: 'Shiba Inu',
+  {                              {                                value: 7,
+    name: 'Cars',                  name: 'Birds',                 groupId: 'dogs'
+    value: 2,                      value: 3,                    }
+    groupId: 'things',             groupId: 'animals',        ]
+    childGroupId: 'cars'           childGroupId: 'birds'
+  }                              }
+]                              ]
+```
+
+The 3 groups of data above come from 3 options, and by specifying `groupId` and `childGroupId` for the data items a relationship of "parent-child-grandChild" is formed in the 3 options. In this way,  after `setOption` is called, Apache ECharts will try to find the "parent-child" or "child-parent" relationship of the old option and the new one. If the relationship exists, the matching data items will be applied to a drilldown animation or an aggregation one.
+
+If a data item has no child data then there is no need to specify a `childGroupId` at all.
 
+If you are using the [dataset](~dataset) component to represent data, you are recommended to use `encode.itemChildGroupId` to specify the dimension that is to be encoded as the child group ID.

en/option/partial/tooltip-common.md

@@ -357,7 +357,7 @@ Callback function for formatting the value section in tooltip.
 
 Interface:
 ```ts
-(value: number | string) => string
+(value: number | string, dataIndex: number) => string
 ```
 
 Example:

en/option/partial/universal-transition.md

@@ -11,7 +11,7 @@ Configuration related to universal transition animation.
 
 Universal Transition provides the ability to morph between any series. With this feature enabled, each time `setOption`, transitions between series with the same `id` will be automatically associated with each other.
 
-One-to-many or many-to-one animations such as drill-down, aggregation, etc. can also be achieved by specifying groups of data such as `encode.itemGroupId` or `dataGroupId`.
+One-to-many or many-to-one animations such as drill-down, aggregation, etc. can also be achieved by specifying data items' `groupId` and `childGroupId`.
 
 This can be enabled directly by configuring `universalTransition: true` in the series. It is also possible to provide an object for more detailed configuration.
 

en/option/series/bar.md

@@ -159,13 +159,14 @@ How to stack values if the [stack](~series-bar.stack) property has been set. Opt
 
 ## sampling(string)
 
-The dowmsampling strategy used when the data size is much larger than pixel size. It will improve the performance when turned on. Defaults to be turned off, indicating that all the data points will be drawn.
+The downsampling strategy used when the data size is much larger than pixel size. It will improve the performance when turned on. Defaults to be turned off, indicating that all the data points will be drawn.
 
 Options:
 + `'lttb'` Use Largest-Triangle-Three-Bucket algorithm to filter points. It will keep the trends and extremas.
 + `'average'` Use average value of filter points
-+ `'max'` Use maximum value of filter points
 + `'min'` Use minimum value of filter points
++ `'max'` Use maximum value of filter points
++ `'minmax'` Use maximum extremum absolute value of filter points (Since `v5.5.0`)
 + `'sum'` Use sum of filter points
 
 {{ use: partial-cursor() }}
@@ -216,6 +217,10 @@ The value of a single data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 {{ use: partial-bar-state(
     prefix = "##",
     topLevel = false,

en/option/series/boxplot.md

@@ -191,6 +191,10 @@ Value of data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### itemStyle(Object)
 
 Style of a single data.

en/option/series/candlestick.md

@@ -210,6 +210,10 @@ Value of data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### itemStyle(Object)
 
 Style of a candle box.

en/option/series/custom.md

@@ -444,6 +444,10 @@ Value of data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### itemStyle(Object)
 
 {{ use: partial-item-style(

en/option/series/heatmap.md

@@ -154,6 +154,10 @@ Value of data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### label(Object)
 
 It is valid with [coordinateSystem](~series-heatmap.coordinateSystem) of 'cartesian2d' value.

en/option/series/line.md

@@ -299,13 +299,14 @@ Here are 2 examples of broken line chart with dual value axis, showing the diffe
 
 ## sampling(string)
 
-The dowmsampling strategy used when the data size is much larger than pixel size. It will improve the performance when turned on. Defaults to be turned off, indicating that all the data points will be drawn.
+The downsampling strategy used when the data size is much larger than pixel size. It will improve the performance when turned on. Defaults to be turned off, indicating that all the data points will be drawn.
 
 Options:
 + `'lttb'` Use Largest-Triangle-Three-Bucket algorithm to filter points. It will keep the trends and extremas.
 + `'average'` Use average value of filter points
-+ `'max'` Use maximum value of filter points
 + `'min'` Use minimum value of filter points
++ `'max'` Use maximum value of filter points
++ `'minmax'` Use maximum extremum absolute value of filter points (Since `v5.5.0`)
 + `'sum'` Use sum of filter points
 
 {{ use: partial-series-dimensions(
@@ -338,6 +339,10 @@ The value of a single data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 {{ use: partial-symbol(
     defaultSymbol = "'circle'",
     defaultSymbolSize = 4,
@@ -491,3 +496,4 @@ Select state of specified single data.
     prefix = "####",
     hasInherit = ${state} === 'emphasis'
 ) }}
+

en/option/series/lines.md

@@ -208,6 +208,10 @@ the name of data.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### coords(Array)
 
 An array includes two ore more than two coordinates. Each coordinate could be `[x, y]` in [rectangular coordinate](~grid) and `[lng, lat]` in [geographic coordinate](~geo).

en/option/series/map.md

@@ -104,6 +104,10 @@ The numerical value of this area.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 ### selected(boolean) = false
 
 Whether the are selected.

en/option/series/pictorialBar.md

@@ -195,6 +195,10 @@ The value of a single data item.
     prefix = '##'
 ) }}
 
+{{ use: partial-data-child-group-id(
+    prefix = '##'
+) }}
+
 {{ use: pictorialBar-symbol-attrs(
     prefix = "##",
     useZ2 = true
@@ -280,6 +284,11 @@ Select state of the specified single data.
     hasType = true
 ) }}
 
+{{ use: partial-clip(
+    prefix = "#",
+    defaultClip = false
+) }}
+
 {{ use: partial-z-zlevel(
     prefix = "#",
     componentName = "Pictorial bar chart "