Document the new filling modes and options (#4251)

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)

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)
+[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)

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

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
     }
 });
-```
+```

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]
     }]
 }
-```
+```

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;
+}