doc(visualmap): add doc for seriesTargets

README.md

@@ -55,8 +55,36 @@ For example,
 {{ use: partial-version(version = ${version|minVersion('6.0.0')}) }}
     That is, if the ${version} is empty or smaller than '6.0.0', use '6.0.0'.
     Follow the version comparison rules in Semver 2.0 .
+
+{{ use: partial-version(
+    feature = '`dataIndex` is available',
+    version = '5.3.0'
+) }}
+
+{{ use: partial-version(
+    deprecated = 'Use xxx instead',
+    version = '5.1.0'
+) }}
 ```
 
+### Security Warning
+Security waning is required for unsafe APIs/options.
+For example,
+```
+{{ use: partial-security-warning }}
+Or
+{{ use: partial-security-warning(
+    desc: 'Raw HTML is allowed in this option.'
+)}}
+Or
+{{ use: partial-security-warning(
+    desc: 'Raw HTML is allowed in this option.',
+    securityRiskExclamation: '**Security risks** must be considered when xxx.'
+)}}
+```
+
+See ["Security"](https://echarts.apache.org/handbook/en/best-practices/security) for more details.
+
 ### Global Variables
 
 These global variables can be used in doc:

en/api/version.md

@@ -3,6 +3,8 @@
 <div class="doc-partial-version">
 {{ if: ${deprecated} }}
 Deprecated since `v${version}`. ${deprecated}
+{{ elif: ${feature} }}
+${feature} since `v${version}`
 {{ else }}
 Since `v${version}`
 {{ /if }}

en/option-gl/partial/version.md

@@ -4,6 +4,8 @@
 <div class="doc-partial-version">
 {{ if: ${deprecated} }}
 Deprecated since{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}`. ${deprecated}
+{{ elif: ${feature} }}
+${feature} since{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}`
 {{ else }}
 Since{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}`
 {{ /if }}

en/option/component/title.md

@@ -26,10 +26,16 @@ Set this to `false` to prevent the title from showing
 
 The main title text, supporting for `\n` for newlines.
 
+{{ use: partial-security-warning(
+    securityRiskExclamation: 'When enabling [toolbox.feature.saveAsImage](~toolbox.feature.saveAsImage), and [toolbox.feature.saveAsImage.name](~toolbox.feature.saveAsImage.name) is not provided, it has historically been using `title[0].text` instead. This usage is not recommended -- [toolbox.feature.saveAsImage.name](~toolbox.feature.saveAsImage.name) should always be specified explicitly; otherwise, **correctness** and **security risks** for a filename have to be considered in this `title.text` option.'
+)}}
+
 ## link(string) = ''
 
 The hyper link of main title text.
 
+{{ use: partial-security-url-common-warning }}
+
 ## target(string) = 'blank'
 
 Open the hyper link of main title in specified tab.
@@ -63,6 +69,8 @@ Subtitle text, supporting for `\n` for newlines.
 
 The hyper link of subtitle text.
 
+{{ use: partial-security-url-common-warning }}
+
 ## subtarget(string) = 'blank'
 
 Open the hyper link of subtitle in specified tab, options:

en/option/component/toolbox.md

@@ -63,6 +63,11 @@ Padding of text area.
 Whether to show the tool.
 
 #### title(string) = '${title}'
+{{ if: ${warnToolboxDataViewSecurity} }}
+{{ use: partial-security-warning(
+    desc: '`dataView` panel is implemented using HTML, allowing users to customize certain parts for styling and formatting. The `title` is embedded in the HTML without HTML-escaping, so it should be properly escaped before being passed in.'
+)}}
+{{ /if }}
 
 #### icon(string)
 
@@ -169,11 +174,20 @@ File suffix of the image saved.
 + If the `renderer` is set to be `'canvas'` when chart [initialized](api.html#echarts.init) (default), then `'png'` (default) and `'jpg'` are supported.
 + If the `renderer` is set to be `'svg'` when when chart [initialized](api.html#echarts.init), then only `'svg'` is supported for `type` (`'svg'` type is supported since `v4.8.0`).
 
+{{ use: partial-security-warning(
+    securityRiskExclamation: 'This value will be used as the file extension. However, it has not historically been validated internally. So do not input an invalid value; otherwise, **security risks** have to be considered.'
+)}}
+
 #### name(string)
 
 <ExampleUIControlText />
 
-Name to save the image, whose default value is [title.text](~title.text).
+Name (file stem) to save the image. If it is not provided, [title[0].text](~title.text) (if any) has historically been used. The full download filename is `{name}.{type}`
+
+{{ use: partial-security-warning(
+    securityRiskExclamation: 'It is recommended to always specify this `name` explicitly, and do not use text from untrusted sources. Otherwise, **correctness** and **security risks** for a filename have to be considered.'
+)}}
+
 
 #### backgroundColor(Color) = 'auto'
 
@@ -214,7 +228,8 @@ Restore configuration item.
 Data view tool, which could display data in current chart and updates chart after being edited.
 
 {{ use: feature-common(
-    title = "data view"
+    title = "data view",
+    warnToolboxDataViewSecurity = true
 ) }}
 
 #### readOnly(boolean) = false
@@ -231,22 +246,26 @@ Whether it is read-only.
 
 Define a function to present dataView. It is used to replace default textarea for richer data editing. It can return a DOM object, or an HTML string.
 
+{{ use: partial-security-warning(
+    desc: '`dataView` panel is implemented using HTML, allowing users to customize certain parts for styling and formatting. The HTML provided by `optionToContent` is embedded in the panel HTML without HTML-escaping, so it should be properly escaped before being passed in.'
+)}}
+
 For example:
 ```ts
 optionToContent: function(opt) {
     var axisData = opt.xAxis[0].data;
     var series = opt.series;
     var table = '<table style="width:100%;text-align:center"><tbody><tr>'
-                 + '<td>Time:</td>'
-                 + '<td>' + series[0].name + '</td>'
-                 + '<td>' + series[1].name + '</td>'
-                 + '</tr>';
+        + '<td>Time:</td>'
+        + '<td>' + echarts.format.encodeHTML(series[0].name) + '</td>'
+        + '<td>' + echarts.format.encodeHTML(series[1].name) + '</td>'
+        + '</tr>';
     for (var i = 0, l = axisData.length; i < l; i++) {
         table += '<tr>'
-                 + '<td>' + axisData[i] + '</td>'
-                 + '<td>' + series[0].data[i] + '</td>'
-                 + '<td>' + series[1].data[i] + '</td>'
-                 + '</tr>';
+            + '<td>' + echarts.format.encodeHTML(axisData[i]) + '</td>'
+            + '<td>' + echarts.format.encodeHTML(series[0].data[i]) + '</td>'
+            + '<td>' + echarts.format.encodeHTML(series[1].data[i]) + '</td>'
+            + '</tr>';
     }
     table += '</tbody></table>';
     return table;
@@ -265,6 +284,10 @@ When optionToContent is used, if you want to support refreshing chart after data
 
 There are 3 names in data view, which are `['data view', 'turn off' and 'refresh']`.
 
+{{ use: partial-security-warning(
+    desc: '`dataView` panel is implemented using HTML, allowing users to customize certain parts for styling and formatting. The items in `lang` are embedded in the HTML without HTML-escaping, so it should be properly escaped before being passed in.'
+)}}
+
 #### backgroundColor(string) = '#fff'
 
 <ExampleUIControlColor default="#fff" />

en/option/component/visual-map.md

@@ -325,6 +325,47 @@ Specify visual mapping should be performed on which series, from which
 Can be a id or a list of ids.
 All series are used by default.
 
+## seriesTargets(Array)
+
+{{ use: partial-version(version = "6.0.1") }}
+
+Specify multiple series with their corresponding dimension mappings. When `seriesTargets` is configured, `seriesIndex`, `seriesId`, and `dimension` will be ignored.
+
+This option allows a single `visualMap` component to map multiple dimensions to their respective series simultaneously, which is particularly useful when working with datasets.
+
+Each target object should contain the following properties:
+- `seriesIndex` or `seriesId`: Specify the series (choose one)
+- `dimension`: Specify the data dimension for that series
+
+Example:
+```javascript
+option = {
+    tooltip: {},
+    dataset: {
+        source: [
+            ['product', '2015', '2016', '2017'],
+            ['Matcha Latte', 43.3, 85.8, 93.7],
+            ['Milk Tea', 83.1, 73.4, 55.1],
+            ['Cheese Cocoa', 86.4, 65.2, 82.5],
+            ['Walnut Brownie', 72.4, 53.9, 39.1]
+        ]
+    },
+    xAxis: { type: 'category' },
+    yAxis: {},
+    series: [{ type: 'bar' }, { type: 'bar' }, { type: 'bar' }],
+    visualMap: {
+        type: 'piecewise',
+        min: 30,
+        max: 100,
+        seriesTargets: [
+            { seriesIndex: 0, dimension: 1 },
+            { seriesIndex: 1, dimension: 2 },
+            { seriesIndex: 2, dimension: 3 }
+        ]
+    }
+};
+```
+
 ## hoverLink(boolean) = true
 
 `hoverLink` enable highlight certain graphical elements of chart when mouse hovers on some place of `visualMap` component that is corresponding to those graphical elements by visual mapping.

en/option/partial/security-warning.md

@@ -0,0 +1,13 @@
+{{ target: partial-security-warning }}
+<div class="doc-partial-security-warning">
+<span class="warning-title">[WARNING]:</span> ${desc} {{ if: ${securityRiskExclamation} }}${securityRiskExclamation}{{ else }}**Security risks** must be considered when using it.{{ /if }} See document ["Security Guidelines"](${handbookPath}best-practices/security) for recommendations on safe usage.
+</div>
+{{ /target }}
+
+
+{{ target: partial-security-url-common-warning }}
+{{ use: partial-security-warning(
+    desc: 'This URL string is accepted directly without any internal sanitization.',
+    securityRiskExclamation: '**Security risks** must be considered if it comes from untrusted sources.'
+)}}
+{{ /target }}

en/option/partial/tooltip-common.md

@@ -305,7 +305,33 @@ formatter: '{b0}: {c0}<br />{b1}: {c1}'
 The format of callback function:
 
 ```ts
-(params: Object|Array, ticket: string, callback: (ticket: string, html: string)) => string | HTMLElement | HTMLElement[]
+(params: Object|Array, ticket: string, callback: (ticket: string, html: string | HTMLElement | HTMLElement[])) => string | HTMLElement | HTMLElement[]
+```
+
+{{ use: partial-security-warning(
+    desc: '`tooltip` is implemented in HTML (unless [tooltip.renderMode](~tooltip.renderMode) is set as `richText`), allowing users to customize the HTML in this way. The content in the HTML must be properly escaped before being passed in.'
+)}}
+
+**HTML-escaping must be enforced** before passing the HTML to ECharts. For example,
+```js
+{
+    tooltip: {
+        formatter: params => {
+            const { name, value } = params;
+            // HTML-escaping must be performed.
+            // Otherwise, the rendering may be incorrect if `name` or
+            // `value` contain special charactors like '<', '>', etc.
+            // Additionally, unescaped strings may introduces XSS risks
+            // if `name` or `value` come from untrusted sources, where
+            // malicious code may be injected into that strings.
+            return echarts.format.encodeHTML(name)
+                + '<b>' + echarts.format.encodeHTML(value) + '</b>';
+            // NOTE: `echarts.format.encodeHTML` is an utility that converts special
+            //  characters ('&', '<', '>', '"', "'") to their corresponding HTML entities.
+            //  This is just an example -- any HTML-escaping utility can be used.
+        }
+    }
+}
 ```
 
 The first parameter `params` is the data that the formatter needs. Its format is shown as follows:
@@ -369,13 +395,18 @@ Interface:
 (value: number | string, dataIndex: number) => string
 ```
 
-> `dataIndex` is provided since `v5.5.0`.
+{{ use: partial-version(
+    feature = '`dataIndex` is provided',
+    version = '5.5.0'
+) }}
 
 Example:
 ```ts
 // Add $ prefix
 valueFormatter: (value) => '$' + value.toFixed(2)
 ```
+
+> **[NOTE]:** Different from [tooltip.formater](~tooltip.formatter), raw HTML is NOT accepted in this approach -- the returned content will be escaped internally before rendering.
 {{ /if }}
 
 #${prefix} backgroundColor(Color) = 'rgba(50,50,50,0.7)'
@@ -446,3 +477,7 @@ Extra CSS style for floating layer. The following is an example for adding shado
 extraCssText: 'box-shadow: 0 0 3px rgba(0, 0, 0, 0.3);'
 ```
 
+{{ use: partial-security-warning(
+    desc: '`tooltip` is implemented in HTML (unless [tooltip.renderMode](~tooltip.renderMode) is set as `richText`), allowing users to customize the CSS text of the box in this way.',
+    securityRiskExclamation: '**Security risks** must be considered if the CSS text comes from untrusted sources.'
+)}}

en/option/partial/version.md

@@ -4,6 +4,8 @@
 <div class="doc-partial-version">
 {{ if: ${deprecated} }}
 Deprecated since `v${version}`. ${deprecated}
+{{ elif: ${feature} }}
+${feature} since `v${version}`
 {{ else }}
 Since `v${version}`
 {{ /if }}

en/option/series/sunburst.md

@@ -215,6 +215,8 @@ Link address that redirects to when this sector is clicked. Only useful when [se
 
 See [series-sunburst.data.target](~series-sunburst.data.target).
 
+{{ use: partial-security-url-common-warning }}
+
 ### target(string) = 'blank'
 
 Like `target` attribute of HTML `<a>`, which can either be `'blank'` or `'self'`. See [series-sunburst.data.link](~series-sunburst.data.link).

en/option/series/treemap.md

@@ -391,6 +391,8 @@ Enable hyperlink jump when clicking on node. It is available when [series-treema
 
 See [series-treemap.data.target](~series-treemap.data.target).
 
+{{ use: partial-security-url-common-warning }}
+
 ### target(string) = 'blank'
 
 The same meaning as `target` in `html` `<a>` label, See [series-treemap.data.link](~series-treemap.data.link). Option values are: `'blank'` or `'self'`.

en/tutorial/visual-map.md

@@ -145,4 +145,34 @@ option = {
 };
 ```
 
+Example C (Using seriesTargets to map different dimensions for different series):
+
+```javascript
+option = {
+    tooltip: {},
+    dataset: {
+        source: [
+            ['product', '2015', '2016', '2017'],
+            ['Matcha Latte', 43.3, 85.8, 93.7],
+            ['Milk Tea', 83.1, 73.4, 55.1],
+            ['Cheese Cocoa', 86.4, 65.2, 82.5],
+            ['Walnut Brownie', 72.4, 53.9, 39.1]
+        ]
+    },
+    xAxis: { type: 'category' },
+    yAxis: {},
+    series: [{ type: 'bar' }, { type: 'bar' }, { type: 'bar' }],
+    visualMap: {
+        type: 'piecewise',
+        min: 30,
+        max: 100,
+        seriesTargets: [
+            { seriesIndex: 0, dimension: 1 },
+            { seriesIndex: 1, dimension: 2 },
+            { seriesIndex: 2, dimension: 3 }
+        ]
+    }
+};
+```
+
 For more information, please refer to [visualMap.inRange](option.html#visualMap.inRange) and [visualMap.outOfRange](option.html#visualMap.outOfRange).

src/style/mixin.scss

@@ -93,4 +93,22 @@
             color: #0086b3;
         }
     }
+
+    .doc-partial-security-warning {
+        font-size: 13px;
+        background: rgba(254, 226, 226, 1);
+        margin: 10px 20px 10px 0;
+        padding: 10px;
+        border-left: 2px solid rgba(248, 113, 113, 1);
+        color: rgb(100, 116, 139);
+
+        code {
+            background: rgba(254, 202, 202, 1);
+        }
+
+        .warning-title {
+            font-weight: bold;
+            color: rgba(185, 28, 28, 1);
+        }
+    }
 }

zh/api/version.md

@@ -3,6 +3,8 @@
 <div class="doc-partial-version">
 {{ if: ${deprecated} }}
 从 `v${version}` 开始不推荐使用（deprecated）。${deprecated}
+{{ elif: ${feature} }}
+${feature} 从 `v${version}` 开始支持
 {{ else }}
 从 `v${version}` 开始支持
 {{ /if }}

zh/option-gl/partial/version.md

@@ -4,6 +4,8 @@
 <div class="doc-partial-version">
 {{ if: ${deprecated} }}
 从{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}` 开始不推荐使用（deprecated）。${deprecated}
+{{ elif: ${feature} }}
+${feature} 从{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}` 开始支持
 {{ else }}
 从{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}` 开始支持
 {{ /if }}