Merge pull request #462 from apache/feat-cartesian-layout

Feat cartesian layout

Author: 100pah

.gitignore

@@ -188,4 +188,6 @@ slides/webgl
 /tool/blocks-zh.json
 
 /zh-src
-/en-src
+/en-src
+
+/config/env.*-local.js

README.md

@@ -15,7 +15,7 @@ This project is part of the source of [The Apache ECharts Official Website](http
 
 ## Development
 
-### Document content development
+### Document Content Development
 
 Do not need other project.
 
@@ -28,46 +28,59 @@ It will:
 + Watch doc site src change and rebuild.
 + Watch doc markdown change and rebuild.
 
+### Local Config
 
-## Tips about writing doc
+To customize the links of `echarts-examples` and other configurations, you can create a local config file `echarts-doc/config/env.dev-local.js`, which is not tracked by git. The content can be copied from `echarts-doc/config/env.dev.js`, and then modify it as needed. `npm run dev` will use this local config file, if it exists, to replace `echarts-doc/config/env.dev.js`.
 
-### "Since version" is necessary in doc
+
+## Tips About Writing Doc
+
+### "Since Version"
+"Since Version" is necessary in doc.
 Marking "since version" indicates when a new feature was introduced.
 For example,
 ```
 {{ use: partial-version(version = "6.0.0") }}
 ```
 
-### Global variables can be used in doc
+### Global Variables
+
+These global variables can be used in doc:
++ `${galleryViewPath}`
++ `${galleryEditorPath}`
++ `${websitePath}`
 
-+ galleryViewPath
-+ galleryEditorPath
-+ websitePath
+See samples in "Reference of echarts-examples or other links"
 
-For example:
-Embed a example in doc:
+### Reference of echarts-examples or Other Links
+
+Embed an example in doc:
 ```md
+~[700X300](${galleryEditorPath}pie-legend&edit=1&reset=1)
 ~[700x300](${galleryViewPath}doc-example/aria-pie&edit=1&reset=1)
 ```
-Provide a example link in doc:
+
+Provide an example link in doc:
 ```md
 [vertically scrollable legend](${galleryEditorPath}pie-legend&edit=1&reset=1)
+[aria pie](${galleryViewPath}doc-example/aria-pie&edit=1&reset=1)
 ```
+
 Provide a website link in doc:
 ```md
 [Apache ECharts website](${websitePath}/en/download.html)
 ```
 
-### Reference of option
+### Reference of Other ECharts Option
 
 A `~` can be used to refer to a option item in the same doc. For example:
-
 ```md
 [xAxis.name](~xAxis.name)
 ```
 
 If intending to reference an anchor in different doc, it can be:
 ```md
+In api.html, reference
 [itemStyle](option.html#series.itemStyle)
 ```
 
@@ -112,6 +125,60 @@ It indicates the range of saturation (color alpha) {{ if: ${prefix} !== '#' }}fo
 
 ```
 
+### Doc Structure
+
++ Entries:
+    + the entry in source code is like `en/api/api.md`, `en/api/option.md`, they will be compiled to webpage like `api.html`, `option.html`
+
++ Shared targets (text blocks):
+    + All of the shared targets should be put into the `partial` folder, such as, `en/api/partial/xxx`, `en/optino/partial/xxx`, and named with a prefix `partial-`.
+
++ Subtitles:
+    + The doc is structured by subtitles.
+    + For example:
+        ```
+        # series.bar(Object)
+        ## propA(number|string) = null
+        some desc xxx
+        ## propB(number|string) = null
+        some desc yyy
+        ## propC(string) = ${defaultPropC|default("'auto'")}
+
+        #${prefix} someOtherProp(Object)
+        some desc zzz
+        ```
+    + `(xxx|yyy)` is the data type in that subtitle:
+        + Can only be `number`, `string`, `boolean`, `Object`, `Array`, `Function`
+        + Can be an union, such as `number|string`.
+    + `= xxx` is the default value in that subtitle:
+        + Can be omitted.
+        + Typically be `null`, `undefined`, `true`, `false`, `90` (a literal number), `some literal string`, `[0, 90]` (an literal array).
+        + The default value can be specified by a template variable, such as, `= ${someVar}`, `= ${someVar|default(123)}`, `= ${someVar|default("'auto'")}`.
+    + The top level subtitles:
+        + For example, `# series.bar(Object)`, the dot symbol represents a special meaning: the component main type is `'series'` and the component sub-type is `'bar'`.
+    + The variable `${prefix}`
+        + It is commonly used in "target: partial-xxx", which serves different subtitle levels. The value of `${prefix}` is like `'#'`, `'##'`, `'###'`, ...
+        + Typical usage:
+            ```tpl
+            When we define a "target"
+            {{ target: partial-abc-1 }}
+            #${prefix} propLayout(Object)
+            All of the subtitles should uses that prefix variable.
+            ##${prefix} x(number)
+            some desc
+            ##${prefix} y(number)
+            some desc
+            {{ /target }}
+            {{ target: partial-target-2 }}
+            ```
+            ```tpl
+            When we use that "partial-abc-1"
+            {{ target: partial-def-2 }}
+            #${prefix|default('#')} somePropA(Object)
+            {{ use: partial-abc-1(
+                prefix: ${prefix} + '#'
+            ) }}
+            ```
 
 ### Template Syntax
 
@@ -120,11 +187,22 @@ The template syntax follows [etpl](https://github.com/ecomfe/etpl/blob/master/do
 
 Summary of the commonly used syntax:
 ```template
-VARIABLE:
-some text ${someVariable} some text
-
-
-IF ELSE:
+--- TEMPLATE VARIABLE ---
+Use a variable:
+    some text ${someVariable} some text
+Variable scope:
+    The scope of any variable is "target" (see below).
+Variable filter:
+    Some predefined filters can be used in the template variable, e.g.,
+    ${someVariable|default("'auto'")} means using the string "'auto'"
+    as the default if ${someVariable} is '' or null or undefined.
+Declaration or assignment of a target-local variable:
+    {{ var: myVar = 'some' }}
+    {{ var: myVar = 123 }}
+    {{ var: myVar = ${someOtherStr} + 'some_str' }}
+
+
+--- IF ELSE ---
 {{ if: ${number1} > 0 }}
 some text xxx
 {{ elif: ${string1} === 'abc' }}
@@ -134,34 +212,40 @@ some text zzz
 {{ /if }}
 
 
-FOR LOOP:
+--- FOR LOOP ---
 {{ for: ${persons} as ${person}, ${index} }}
 some text ${index}: ${person.name}
 {{ /for }}
 
 
-TARGET (DEFINE A BLOCK):
+--- TARGET (DEFINE A TEXT BLOCK) ---
 {{ target: a_predefined_block_name_1 }}
 The input varA is ${varA}
 The input varB is ${varB}
 The input varC is ${varC}
-some other text xxx
-(The close target can be omitted, but not recommended.)
+Notice:
+- The scope of the "target name" is the entire webpage (such as, `option.html`, `api.html`), so name conflicts should be avoided.
+- "target" is not shared across webpage (such as, `option.html`, `api.html`).
+- The close tag of "target" can be omitted, but not recommended.
 {{ /target }}
 
 
-USE (USE A BLOCK):
-{{ use: a_predefined_block_name_1(
+--- USE (USE A PREDEFINED TEXT BLOCK) ---
+{{ use: a_predefined_block_name_1 }}
+{{ use: a_predefined_block_name_2(
     varA = ${myVarX},
     varB = 123,
-    varC = 'some string'
-)}}
-{{ use: a_predefined_block_name_2 }}
+    varC = 'some string',
+    prefix: ${prefix} + '##'
+) }}
+Concatenation operator `+` can be used in that string.
 ```
 
 
 ### Document Embedded Examples
 
+This is the embedded example that can be opened by clicking "try it" and then appears on the right side of the doc page.
+
 Declare the base echarts options (`ExampleBaseOption`), whose scope is each echarts component or series. A `ExampleBaseOption` can be shared by multiple options. e.g.,
 ```md
 <ExampleBaseOption name="cartesian-bar" title="直角坐标系上的柱状图" title-en="Bar on Cartesian">
@@ -199,7 +283,7 @@ npm run format
 
 Make sure have a double review on the git diff after formatted.
 
-## Sync docs between different languages.
+## Sync Docs Between Different Languages
 
 After you finished editing doc of one language. You can use following script to sync it to another language.
 

build.js

@@ -46,6 +46,11 @@ function initEnv() {
 
     let config = require('./config/env.' + envType);
 
+    const localOverridePath = './config/env.' + envType + '-local.js';
+    if (fs.existsSync(path.join(__dirname, localOverridePath))) {
+        config = require(localOverridePath);
+    }
+
     assert(path.isAbsolute(config.releaseDestDir) && path.isAbsolute(config.ecWWWGeneratedDir));
 
     config.envType = envType;

en/api/version.md

@@ -1,5 +1,9 @@
 {{ target: partial-version }}
 
+{{ if: ${deprecated} }}
+> Deprecated since `v${version}`. ${deprecated}
+{{ else }}
 > Since `v${version}`
+{{ /if }}
 
 {{ // this line break is necessary for md quote }}

en/option-gl/partial/version.md

@@ -1,5 +1,8 @@
 
 {{ target: partial-version }}
 
+{{ if: ${deprecated} }}
+> Deprecated since{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}`. ${deprecated}
+{{ else }}
 > Since{{ if: ${isECharts} }} ECharts{{ /if }} `v${version}`
-
+{{ /if }}

en/option/component/grid.md

@@ -22,17 +22,18 @@ In ECharts 2.x, there could only be one single grid component at most in a singl
 Whether to show the grid in rectangular coordinate.
 
 {{ use: partial-rect-layout-width-height(
-    componentName = "grid ",
+    componentName = "grid",
     defaultLeft = "'10%'",
     defaultTop = 60,
     defaultRight = "'10%'",
     defaultBottom = 60
 ) }}
 
 ## containLabel(boolean) = false
-
 <ExampleUIControlBoolean default="false" />
 
+{{ use: partial-version(version = "6.0.0", deprecated = 'See [grid.outerBoundsMode](~grid.outerBoundsMode).') }}
+
 Whether the grid region contains [axis tick label](~yAxis.axisLabel).
 
 + When containLabel is `false`:
@@ -42,6 +43,68 @@ Whether the grid region contains [axis tick label](~yAxis.axisLabel).
     + `grid.left` `grid.right` `grid.top` `grid.bottom` `grid.width` `grid.height` decide the location and size of the rectangle that contains the axes, and the labels of the axes.
     + Setting to `true` will help when the length of axis labels is dynamic and is hard to approximate. This will avoid labels from overflowing the container or overlapping other components.
 
+## outerBoundsMode(string) = 'auto'
+{{ use: partial-version(version = "6.0.0") }}
+
+The "outer bounds" is a constraint rectangle used to prevent axis labels and axis names from overflowing. `outerBoundsMode` defines the strategy for determining the "outer bounds".
+
+In most cases, we do not need to specify [grid.outerBoundsMode](~grid.outerBoundsMode), [grid.outerBounds](~grid.outerBounds), [grid.outerBoundsContain](~grid.outerBoundsContain) and [grid.containLabel](~grid.containLabel), as the default settings can prevent axis labels and axis names from overflowing the canvas.
+
+The grid component (Cartesian) layout strategy:
++ First, lay out axis lines based on the rect defined by [grid.left](~grid.left)/[right](~grid.right)/[top](~grid.top)/[bottom](~grid.bottom)/[width](~grid.width)/[height](~grid.height). This can meet the requirement of aligning axis lines across multiple grids.
++ Then, if axis labels and/or axis names overflow the "outer bounds", shrink the rectangle to prevent that overflow. [grid.outerBoundsContain](~grid.outerBoundsContain) determines whether axis label and axis name is confined by the "outer bounds".
+
+Options of `outerBoundsMode`:
+- `'auto'`/`null`/`undefined` (default):
+    - Behave the same as `outerBoundsMode: 'same'` when `grid.containLabel: true`.
+    - Otherwise, the "outer bounds" is determined by [grid.outerBounds](~grid.outerBounds) if specified.
+    - Otherwise, automatically determine the "outer bounds" - typically defaulting to the current canvas, or a assigned layout rectangle if this `grid` is laid out in another coordinate system (see [grid.coordinateSystem](~grid.coordinateSystem)).
+- `'none'`: Force the "outer bounds" to be infinity (i.e., no constraint), regardless of the specified [grid.outerBounds](~grid.outerBounds).
+- `'same'`: Force the "outer bounds" to be the same as the layout rectangle defined by [grid.left](~grid.left)/[right](~grid.right)/[top](~grid.top)/[bottom](~grid.bottom)/[width](~grid.width)/[height](~grid.height), regardless of the specified [grid.outerBounds](~grid.outerBounds).
+
+> The "outer bounds" encompasses the functionality of [grid.containLabel](~grid.containLabel); therefore, [grid.containLabel](~grid.containLabel) is deprecated. `grid.containLabel: true` is equivalent to `grid: {outerBoundsMode: 'same', outerBoundsContain: 'axisLabel'}`.
+> The effect might be slightly different, but usually indiscernible. You can use the code below to enforce the previous effect, though it's unnecessary in most cases.
+> ```js
+> import {use} from 'echarts/core';
+> import {LegacyGridContainLabel} from 'echarts/features';
+> use([LegacyGridContainLabel]);
+> ```
+
+**Demo**: [outerBounds example](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1).
+
+
+## outerBounds(Object)
+{{ use: partial-version(version = "6.0.0") }}
+
+See details in [grid.outerBoundsMode](~grid.outerBoundsMode).
+
+See also [outerBounds example](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1).
+
+{{ use: partial-rect-layout-width-height(
+    hostName = "`outerBounds`",
+    noZ = true,
+    prefix = '##',
+    defaultLeft = 0,
+    defaultTop = 0,
+    defaultRight = 0,
+    defaultBottom = 0
+) }}
+
+## outerBoundsContain(boolean) = 'auto'
+{{ use: partial-version(version = "6.0.0") }}
+
+Options:
+- `'auto'`/`null`/`undefined` (default):
+    - Behave the same as `outerBoundsContain: 'axisLabel'` if `containLabel: true`.
+    - Otherwise, behave the same as `outerBoundsContain: 'all'`.
+- `'all'`: The "outer bounds" constrain the grid (Cartesian) rectangle (determined by the x-axis and y-axis lines) and axis labels and axis names.
+- `'axisLabel'`: The "outer bounds" constrain the grid (Cartesian) rectangle (determined by the x-axis and y-axis lines) and axis labels, but exclude axis names.
+
+For more details, see [grid.outerBoundsMode](~grid.outerBoundsMode).
+
+See also [outerBounds example](${galleryEditorPath}doc-example/grid-outerBounds&edit=1&reset=1).
+
+
 {{ use: partial-component-common-style(
     componentName = "grid",
     prefix = '#',

en/option/component/parallel.md

@@ -13,7 +13,7 @@
 ) }}
 
 {{ use: partial-rect-layout-width-height(
-    componentName = 'parallel ',
+    componentName = 'parallel',
     defaultLeft = 80,
     defaultRight = 80,
     defaultTop = 60,

en/option/component/title.md

@@ -113,7 +113,7 @@ Set this to `true` to enable triggering events
 The gap between the main title and subtitle.
 
 {{ use: partial-rect-layout(
-    componentName = "title "
+    componentName = "title"
 ) }}
 
 {{ use: partial-component-common-style(

en/option/component/visual-map.md

@@ -358,7 +358,7 @@ Define visual channels that will mapped from dataValues that are **out of select
 See available configurations in [${visualMapName}.inRange](~${visualMapName}.inRange)
 
 {{ use: partial-rect-layout(
-    componentName = "visualMap ",
+    componentName = "visualMap",
     defaultZ = "4",
     defaultLeft = "0",
     defaultRight = "auto",