Document the new filling modes and options (#4251)

diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 5ec896e40cad538f138d344f6a8526e97532d1a5..041be7062af4706f38fc957ec070b15e627e6684 100644 (file)
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -27,6 +27,7 @@
   * [Polar Area](charts/polar.md)
   * [Bubble](charts/bubble.md)
   * [Scatter](charts/scatter.md)
+  * [Area](charts/area.md)
   * [Mixed](charts/mixed.md)
 * [Axes](axes/README.md)
   * [Cartesian](axes/cartesian/README.md)

diff --git a/docs/charts/README.md b/docs/charts/README.md
index 446220966418d0bbe18ddc65015a9a4a98d4f7e8..26677b04d765dcd682563448df129c8628d7370f 100644 (file)
--- a/docs/charts/README.md
+++ b/docs/charts/README.md
@@ -8,4 +8,6 @@ Chart.js comes with built-in chart types:
 * [doughnut and pie](./doughnut.md)
 * [bubble](./bubble.md)
 
-To create a new chart type, see the [developer notes](../developers/charts.md#new-charts)
\ No newline at end of file
+[Area charts](area.md) can be built from a line or radar chart using the dataset `fill` option.
+
+To create a new chart type, see the [developer notes](../developers/charts.md#new-charts)

diff --git a/docs/charts/area.md b/docs/charts/area.md
new file mode 100644 (file)
index 0000000..d51f847
--- /dev/null
+++ b/docs/charts/area.md
@@ -0,0 +1,72 @@
+# Area Charts
+
+Both [line](line.md) and [radar](radar.md) charts support a `fill` option on the dataset object which can be used to create area between two datasets or a dataset and a boundary, i.e. the scale `origin`, `start` or `end` (see [filling modes](#filling-modes)).
+
+> **Note:** this feature is implemented by the [`filler` plugin](/chartjs/Chart.js/blob/master/src/plugins/plugin.filler.js).
+
+## Filling modes
+
+| Mode | Type | Values |
+| :--- | :--- | :--- |
+| Absolute dataset index <sup>1</sup> | `Number` | `1`, `2`, `3`, ... |
+| Relative dataset index <sup>1</sup> | `String` | `'-1'`, `'-2'`, `'+1'`, ... |
+| Boundary <sup>2</sup> | `String` | `'start'`, `'end'`, `'origin'` |
+| Disabled <sup>3</sup> | `Boolean` | `false` |
+
+> <sup>1</sup> dataset filling modes have been introduced in version 2.6.0<br>
+> <sup>2</sup> prior version 2.6.0, boundary values was `'zero'`, `'top'`, `'bottom'` (deprecated)<br>
+> <sup>3</sup> for backward compatibility, `fill: true` (default) is equivalent to `fill: 'origin'`<br>
+
+**Example**
+```javascript
+new Chart(ctx, {
+    data: {
+        datasets: [
+            {fill: 'origin'},      // 0: fill to 'origin'
+            {fill: '+2'},          // 1: fill to dataset 3
+            {fill: 1},             // 2: fill to dataset 1
+            {fill: false},         // 3: no fill
+            {fill: '-2'}           // 4: fill to dataset 2
+        ]
+    }
+})
+```
+
+## Configuration
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| [`plugins.filler.propagate`](#propagate) | `Boolean` | `true` | Fill propagation when target is hidden
+
+### propagate
+Boolean (default: `true`)
+
+If `true`, the fill area will be recursively extended to the visible target defined by the `fill` value of hidden dataset targets:
+
+**Example**
+```javascript
+new Chart(ctx, {
+    data: {
+        datasets: [
+            {fill: 'origin'},   // 0: fill to 'origin'
+            {fill: '-1'},       // 1: fill to dataset 0
+            {fill: 1},          // 2: fill to dataset 1
+            {fill: false},      // 3: no fill
+            {fill: '-2'}        // 4: fill to dataset 2
+        ]
+    },
+    options: {
+        plugins: {
+            filler: {
+                propagate: true
+            }
+        }
+    }
+})
+```
+
+`propagate: true`:
+- if dataset 2 is hidden, dataset 4 will fill to dataset 1
+- if dataset 2 and 1 are hidden, dataset 4 will fill to `'origin'`
+
+`propagate: false`:
+- if dataset 2 and/or 4 are hidden, dataset 4 will not be filled

diff --git a/docs/charts/line.md b/docs/charts/line.md
index a64f436cfdb6400107ea7f9fbbbbdbd43cebde8f..ba7911fe798e0ecceb27608e9bcff6c3800ca5c9 100644 (file)
--- a/docs/charts/line.md
+++ b/docs/charts/line.md
@@ -56,7 +56,7 @@ All point* properties can be specified as an array. If these are set to an array
 | `borderCapStyle` | `String` | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap)
 | `borderJoinStyle` | `String` | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin)
 | `cubicInterpolationMode` | `String` | Algorithm used to interpolate a smooth curve from the discrete data points. [more...](#cubicInterpolationMode)
-| `fill` | `Boolean/String` | How to fill the area under the line. [more...](#fill)
+| `fill` | `Boolean/String` | How to fill the area under the line. See [area charts](area.md)
 | `lineTension` | `Number` | Bezier curve tension of the line. Set to 0 to draw straightlines. This option is ignored if monotone cubic interpolation is used.
 | `pointBackgroundColor` | `Color/Color[]` | The fill color for points.
 | `pointBorderColor` | `Color/Color[]` | The border color for points.
@@ -77,20 +77,12 @@ The following interpolation modes are supported:
 * 'default'
 * 'monotone'. 
 
-The 'default' algorithm uses a custom weighted cubic interpolation, which produces pleasant curves for all types of datasets. 
+The 'default' algorithm uses a custom weighted cubic interpolation, which produces pleasant curves for all types of datasets.
 
-The 'monotone' algorithm is more suited to `y = f(x)` datasets : it preserves monotonicity (or piecewise monotonicity) of the dataset being interpolated, and ensures local extremums (if any) stay at input data points. 
+The 'monotone' algorithm is more suited to `y = f(x)` datasets : it preserves monotonicity (or piecewise monotonicity) of the dataset being interpolated, and ensures local extremums (if any) stay at input data points.
 
 If left untouched (`undefined`), the global `options.elements.line.cubicInterpolationMode` property is used.
 
-### fill
-If `true`, fill the area under the line. The line is filled to the baseline. If the y axis has a 0 value, the line is filled to that point. If the axis has only negative values, the line is filled to the highest value. If the axis has only positive values, it is filled to the lowest value.
-
-String values to fill to specific locations are:
-* `'zero'`
-* `'top'`
-* `'bottom'`
-
 ### pointStyle
 The style of point. Options are:
 * 'circle'
@@ -246,4 +238,4 @@ new Chart(ctx, {
         responsiveAnimationDuration: 0, // animation duration after a resize
     }
 });
-```
\ No newline at end of file
+```

diff --git a/docs/charts/radar.md b/docs/charts/radar.md
index 4728ad7771d0ea28a1a8f45b54321d98073cd2b0..dd5d47b27e46656c7488812b201512dfaa561d0b 100644 (file)
--- a/docs/charts/radar.md
+++ b/docs/charts/radar.md
@@ -76,8 +76,8 @@ All point* properties can be specified as an array. If these are set to an array
 | `borderDashOffset` | `Number` | Offset for line dashes. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineDashOffset)
 | `borderCapStyle` | `String` | Cap style of the line. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineCap)
 | `borderJoinStyle` | `String` | Line joint style. See [MDN](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/lineJoin)
-| `fill` | `Boolean/String` | How to fill the area under the line. [more...](#fill)
-| `lineTension` | `Number` | Bezier curve tension of the line. Set to 0 to draw straightlines. 
+| `fill` | `Boolean/String` | How to fill the area under the line. See [area charts](area.md)
+| `lineTension` | `Number` | Bezier curve tension of the line. Set to 0 to draw straightlines.
 | `pointBackgroundColor` | `Color/Color[]` | The fill color for points.
 | `pointBorderColor` | `Color/Color[]` | The border color for points.
 | `pointBorderWidth` | `Number/Number[]` | The width of the point border in pixels.
@@ -142,4 +142,4 @@ data: {
         data: [20, 10, 4, 2]
     }]
 }
-```
\ No newline at end of file
+```

diff --git a/docs/style.css b/docs/style.css
index 89e7c7053555e2fa79eca57b9229276ce5e4c785..acdd3e5e9464e22c80192e07d3394a239bd67b8e 100644 (file)
--- a/docs/style.css
+++ b/docs/style.css
@@ -9,3 +9,7 @@ a.anchorjs-link {
 a.anchorjs-link:hover {
     color: rgba(65, 131, 196, 1);
 }
+
+sup {
+    font-size: 0.75em !important;
+}