[docs] Document how to customize a subsection of a line chart (mui#13210

)

Signed-off-by: Alexandre Fauquette <[email protected]>
Co-authored-by: Jose C Quintas Jr <[email protected]>

docs/data/charts/line-demo/LineWithPrediction.js

@@ -0,0 +1,70 @@
+import * as React from 'react';
+import { LineChart, AnimatedLine } from '@mui/x-charts/LineChart';
+import { useChartId, useDrawingArea, useXScale } from '@mui/x-charts/hooks';
+
+function CustomAnimatedLine(props) {
+  const { limit, sxBefore, sxAfter, ...other } = props;
+  const { top, bottom, height, left, width } = useDrawingArea();
+  const scale = useXScale();
+  const chartId = useChartId();
+
+  if (limit === undefined) {
+    return <AnimatedLine {...other} />;
+  }
+
+  const limitPosition = scale(limit); // Convert value to x coordinate.
+
+  if (limitPosition === undefined) {
+    return <AnimatedLine {...other} />;
+  }
+
+  const clipIdleft = `${chartId}-${props.ownerState.id}-line-limit-${limit}-1`;
+  const clipIdRight = `${chartId}-${props.ownerState.id}-line-limit-${limit}-2`;
+  return (
+    <React.Fragment>
+      {/* Clip to show the line before the limit */}
+      <clipPath id={clipIdleft}>
+        <rect
+          x={left}
+          y={0}
+          width={limitPosition - left}
+          height={top + height + bottom}
+        />
+      </clipPath>
+      {/* Clip to show the line after the limit */}
+      <clipPath id={clipIdRight}>
+        <rect
+          x={limitPosition}
+          y={0}
+          width={left + width - limitPosition}
+          height={top + height + bottom}
+        />
+      </clipPath>
+      <g clipPath={`url(#${clipIdleft})`}>
+        <AnimatedLine {...other} sx={sxBefore} />
+      </g>
+      <g clipPath={`url(#${clipIdRight})`}>
+        <AnimatedLine {...other} sx={sxAfter} />
+      </g>
+    </React.Fragment>
+  );
+}
+
+export default function LineWithPrediction() {
+  return (
+    <LineChart
+      series={[
+        {
+          type: 'line',
+          data: [1, 2, 3, 4, 1, 2, 3, 4, 5],
+          valueFormatter: (v, i) => `${v}${i.dataIndex > 5 ? ' (estimated)' : ''}`,
+        },
+      ]}
+      xAxis={[{ data: [0, 1, 2, 3, 4, 5, 6, 7, 8] }]}
+      height={200}
+      width={400}
+      slots={{ line: CustomAnimatedLine }}
+      slotProps={{ line: { limit: 5, sxAfter: { strokeDasharray: '10 5' } } }}
+    />
+  );
+}

docs/data/charts/line-demo/LineWithPrediction.tsx

@@ -0,0 +1,77 @@
+import * as React from 'react';
+import { LineChart, AnimatedLine, AnimatedLineProps } from '@mui/x-charts/LineChart';
+import { useChartId, useDrawingArea, useXScale } from '@mui/x-charts/hooks';
+import { SxProps, Theme } from '@mui/system';
+
+interface CustomAnimatedLineProps extends AnimatedLineProps {
+  limit?: number;
+  sxBefore?: SxProps<Theme>;
+  sxAfter?: SxProps<Theme>;
+}
+
+function CustomAnimatedLine(props: CustomAnimatedLineProps) {
+  const { limit, sxBefore, sxAfter, ...other } = props;
+  const { top, bottom, height, left, width } = useDrawingArea();
+  const scale = useXScale();
+  const chartId = useChartId();
+
+  if (limit === undefined) {
+    return <AnimatedLine {...other} />;
+  }
+
+  const limitPosition = scale(limit); // Convert value to x coordinate.
+
+  if (limitPosition === undefined) {
+    return <AnimatedLine {...other} />;
+  }
+
+  const clipIdleft = `${chartId}-${props.ownerState.id}-line-limit-${limit}-1`;
+  const clipIdRight = `${chartId}-${props.ownerState.id}-line-limit-${limit}-2`;
+  return (
+    <React.Fragment>
+      {/* Clip to show the line before the limit */}
+      <clipPath id={clipIdleft}>
+        <rect
+          x={left}
+          y={0}
+          width={limitPosition - left}
+          height={top + height + bottom}
+        />
+      </clipPath>
+      {/* Clip to show the line after the limit */}
+      <clipPath id={clipIdRight}>
+        <rect
+          x={limitPosition}
+          y={0}
+          width={left + width - limitPosition}
+          height={top + height + bottom}
+        />
+      </clipPath>
+      <g clipPath={`url(#${clipIdleft})`}>
+        <AnimatedLine {...other} sx={sxBefore} />
+      </g>
+      <g clipPath={`url(#${clipIdRight})`}>
+        <AnimatedLine {...other} sx={sxAfter} />
+      </g>
+    </React.Fragment>
+  );
+}
+
+export default function LineWithPrediction() {
+  return (
+    <LineChart
+      series={[
+        {
+          type: 'line',
+          data: [1, 2, 3, 4, 1, 2, 3, 4, 5],
+          valueFormatter: (v, i) => `${v}${i.dataIndex > 5 ? ' (estimated)' : ''}`,
+        },
+      ]}
+      xAxis={[{ data: [0, 1, 2, 3, 4, 5, 6, 7, 8] }]}
+      height={200}
+      width={400}
+      slots={{ line: CustomAnimatedLine }}
+      slotProps={{ line: { limit: 5, sxAfter: { strokeDasharray: '10 5' } } as any }}
+    />
+  );
+}

docs/data/charts/line-demo/LineWithPrediction.tsx.preview

@@ -0,0 +1,14 @@
+<LineChart
+  series={[
+    {
+      type: 'line',
+      data: [1, 2, 3, 4, 1, 2, 3, 4, 5],
+      valueFormatter: (v, i) => `${v}${i.dataIndex > 5 ? ' (estimated)' : ''}`,
+    },
+  ]}
+  xAxis={[{ data: [0, 1, 2, 3, 4, 5, 6, 7, 8] }]}
+  height={200}
+  width={400}
+  slots={{ line: CustomAnimatedLine }}
+  slotProps={{ line: { limit: 5, sxAfter: { strokeDasharray: '10 5' } } as any }}
+/>

docs/data/charts/line-demo/line-demo.md

@@ -31,3 +31,15 @@ components: LineChart, LineElement, LineHighlightElement, LineHighlightPlot, Lin
 ## LineChartConnectNulls
 
 {{"demo": "LineChartConnectNulls.js"}}
+
+## Line with forecast
+
+To show that parts of the data have different meanings, you can render stylised lines for each of them.
+
+In the following example, the chart shows a dotted line to exemplify that the data is estimated.
+To do so, the `slots.line` is set with a custom components that render the default line twice.
+
+- The first one is clipped to show known values (from the left of the chart to the limit).
+- The second one is clipped to show predictions (from the limit to the right of the chart) with dash styling.
+
+{{"demo": "LineWithPrediction.js"}}