[charts] Add baseline property to the LineChart series

docs/data/charts/lines/AreaBaseline.js

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import { LineChart } from '@mui/x-charts/LineChart';
+
+export default function AreaBaseline() {
+ return (
+ <LineChart
+ xAxis={[{ data: [1, 2, 3, 5, 8, 10] }]}
+ series={[
+ {
+ data: [2, -5.5, 2, -7.5, 1.5, 6],
+ area: true,
+ baseline: 'min',
+ },
+ ]}
+ width={500}
+ height={300}
+ />
+ );
+}

docs/data/charts/lines/AreaBaseline.tsx

@@ -0,0 +1,19 @@
+import * as React from 'react';
+import { LineChart } from '@mui/x-charts/LineChart';
+
+export default function AreaBaseline() {
+ return (
+ <LineChart
+ xAxis={[{ data: [1, 2, 3, 5, 8, 10] }]}
+ series={[
+ {
+ data: [2, -5.5, 2, -7.5, 1.5, 6],
+ area: true,
+ baseline: 'min',
+ },
+ ]}
+ width={500}
+ height={300}
+ />
+ );
+}

docs/data/charts/lines/AreaBaseline.tsx.preview

@@ -0,0 +1,12 @@
+<LineChart
+ xAxis={[{ data: [1, 2, 3, 5, 8, 10] }]}
+ series={[
+ {
+ data: [2, -5.5, 2, -7.5, 1.5, 6],
+ area: true,
+ baseline: 'min',
+ },
+ ]}
+ width={500}
+ height={300}
+/>

docs/data/charts/lines/lines.md

@@ -175,6 +175,20 @@ Different series could even have different interpolations.
 
 {{"demo": "InterpolationDemoNoSnap.js", "hideToolbar": true}}
 
+### Baseline
+
+The area chart draws a `baseline` on the Y axis `0`.
+This is useful as a base value, but customized visualizations may require a different baseline.
+
+To get the area filling the space above or below the line, set `baseline` to `"min"` or `"max"`.
+It is also possible to provide a `number` value to fix the baseline at the desired position.
+
+:::warning
+The `baseline` should not be used with stacked areas, as it will not work as expected.
+:::
+
+{{"demo": "AreaBaseline.js"}}
+
 ### Optimization
 
 To show mark elements, use `showMark` series property.

docs/pages/x/api/charts/line-series-type.json

@@ -4,6 +4,7 @@
  "properties": {
  "type": { "type": { "description": "'line'" }, "required": true },
  "area": { "type": { "description": "boolean" } },
+ "baseline": { "type": { "description": "number | 'min' | 'max'" }, "default": "0" },
  "color": { "type": { "description": "string" } },
  "connectNulls": { "type": { "description": "boolean" }, "default": "false" },
  "curve": { "type": { "description": "CurveType" } },

docs/translations/api-docs/charts/line-series-type.json

@@ -3,6 +3,9 @@
  "propertiesDescriptions": {
  "type": { "description": "" },
  "area": { "description": "" },
+ "baseline": {
+ "description": "<p>The value of the line at the base of the series area.<br /><br />- <code>&#39;min&#39;</code> the area will fill the space <strong>under</strong> the line.<br />- <code>&#39;max&#39;</code> the area will fill the space <strong>above</strong> the line.<br />- <code>number</code> the area will fill the space between this value and the line</p>\n"
+ },
  "color": { "description": "" },
  "connectNulls": {
  "description": "If <code>true</code>, line and area connect points separated by <code>null</code> values."

packages/x-charts/src/LineChart/AreaPlot.tsx

@@ -59,6 +59,7 @@ const useAggregatedData = () => {
  stackedData,
  data,
  connectNulls,
+ baseline,
  } = series[seriesId];
 
  const xAxisId = xAxisIdProp ?? xAxisKey;
@@ -97,6 +98,16 @@ const useAggregatedData = () => {
  .x((d) => xScale(d.x))
  .defined((_, i) => connectNulls || data[i] != null)
  .y0((d) => {
+ if (typeof baseline === 'number') {
+ return yScale(baseline)!;
+ }
+ if (baseline === 'max') {
+ return yScale.range()[1];
+ }
+ if (baseline === 'min') {
+ return yScale.range()[0];
+ }
+
  const value = d.y && yScale(d.y[0])!;
  if (Number.isNaN(value)) {
  return yScale.range()[0];

packages/x-charts/src/LineChart/extremums.ts

@@ -43,8 +43,11 @@ export const getExtremumY: ExtremumGetter<'line'> = (params) => {
  const { area, stackedData } = series[seriesId];
  const isArea = area !== undefined;
 
+ // Since this series is not used to display an area, we do not consider the base (the d[0]).
  const getValues: GetValuesTypes =
- isArea && axis.scaleType !== 'log' ? (d) => d : (d) => [d[1], d[1]]; // Since this series is not used to display an area, we do not consider the base (the d[0]).
+ isArea && axis.scaleType !== 'log' && typeof series[seriesId].baseline !== 'string'
+ ? (d) => d
+ : (d) => [d[1], d[1]];
 
  const seriesExtremums = getSeriesExtremums(getValues, stackedData);
 

packages/x-charts/src/models/seriesType/line.ts

@@ -82,6 +82,16 @@ export interface LineSeriesType
  * @default 'none'
  */
  stackOffset?: StackOffsetType;
+ /**
+ * The value of the line at the base of the series area.
+ *
+ * - `'min'` the area will fill the space **under** the line.
+ * - `'max'` the area will fill the space **above** the line.
+ * - `number` the area will fill the space between this value and the line
+ *
+ * @default 0
+ */
+ baseline?: number | 'min' | 'max';
 }
 
 /**