[charts] Add option to show marks only on the first/last values (mui#22645)

Author: alexfauquette

docs/data/charts/lines/LineMarkShape.js

@@ -6,9 +6,20 @@ import MenuItem from '@mui/material/MenuItem';
 import { LineChart } from '@mui/x-charts/LineChart';
 import { dataset } from '../dataset/weather';
 
+const marksMapping = {
+  true: true,
+  false: false,
+  start: 'start',
+  end: 'end',
+  '({index})=>index%2===0': ({ index }) => index % 2 === 0,
+};
+
+const marksOptions = ['true', 'false', 'start', 'end', '({index})=>index%2===0'];
+
 const shapes = ['circle', 'square', 'diamond', 'cross', 'star', 'triangle', 'wye'];
 
 export default function LineMarkShape() {
+  const [marks, setMarks] = React.useState('true');
   const [shape, setShape] = React.useState('circle');
 
   return (
@@ -17,19 +28,34 @@ export default function LineMarkShape() {
       spacing={1}
       sx={{ width: '100%', padding: 2 }}
     >
-      <TextField
-        select
-        label="shape"
-        value={shape}
-        onChange={(event) => setShape(event.target.value)}
-        sx={{ minWidth: 150 }}
-      >
-        {shapes.map((option) => (
-          <MenuItem key={option} value={option}>
-            {option}
-          </MenuItem>
-        ))}
-      </TextField>
+      <Stack direction={{ xs: 'row', md: 'column' }} spacing={1}>
+        <TextField
+          select
+          label="marks"
+          value={marks}
+          onChange={(event) => setMarks(event.target.value)}
+          sx={{ minWidth: 150 }}
+        >
+          {marksOptions.map((option) => (
+            <MenuItem key={option} value={option}>
+              {option}
+            </MenuItem>
+          ))}
+        </TextField>
+        <TextField
+          select
+          label="shape"
+          value={shape}
+          onChange={(event) => setShape(event.target.value)}
+          sx={{ minWidth: 150 }}
+        >
+          {shapes.map((option) => (
+            <MenuItem key={option} value={option}>
+              {option}
+            </MenuItem>
+          ))}
+        </TextField>
+      </Stack>
       <Box sx={{ flexGrow: 1 }}>
         <LineChart
           height={250}
@@ -39,7 +65,7 @@ export default function LineMarkShape() {
               dataKey: 'london',
               label: 'London precipitation (mm)',
               curve: 'natural',
-              showMark: true,
+              showMark: marksMapping[marks],
               shape,
             },
           ]}

docs/data/charts/lines/LineMarkShape.tsx

@@ -8,6 +8,22 @@ import { dataset } from '../dataset/weather';
 
 type Shape = 'circle' | 'square' | 'diamond' | 'cross' | 'star' | 'triangle' | 'wye';
 
+const marksMapping = {
+  true: true,
+  false: false,
+  start: 'start',
+  end: 'end',
+  '({index})=>index%2===0': ({ index }: { index: number }) => index % 2 === 0,
+} as const;
+
+const marksOptions: (keyof typeof marksMapping)[] = [
+  'true',
+  'false',
+  'start',
+  'end',
+  '({index})=>index%2===0',
+];
+
 const shapes: Shape[] = [
   'circle',
   'square',
@@ -19,6 +35,7 @@ const shapes: Shape[] = [
 ];
 
 export default function LineMarkShape() {
+  const [marks, setMarks] = React.useState<keyof typeof marksMapping>('true');
   const [shape, setShape] = React.useState<Shape>('circle');
 
   return (
@@ -27,19 +44,36 @@ export default function LineMarkShape() {
       spacing={1}
       sx={{ width: '100%', padding: 2 }}
     >
-      <TextField
-        select
-        label="shape"
-        value={shape}
-        onChange={(event) => setShape(event.target.value as Shape)}
-        sx={{ minWidth: 150 }}
-      >
-        {shapes.map((option) => (
-          <MenuItem key={option} value={option}>
-            {option}
-          </MenuItem>
-        ))}
-      </TextField>
+      <Stack direction={{ xs: 'row', md: 'column' }} spacing={1}>
+        <TextField
+          select
+          label="marks"
+          value={marks}
+          onChange={(event) =>
+            setMarks(event.target.value as keyof typeof marksMapping)
+          }
+          sx={{ minWidth: 150 }}
+        >
+          {marksOptions.map((option) => (
+            <MenuItem key={option} value={option}>
+              {option}
+            </MenuItem>
+          ))}
+        </TextField>
+        <TextField
+          select
+          label="shape"
+          value={shape}
+          onChange={(event) => setShape(event.target.value as Shape)}
+          sx={{ minWidth: 150 }}
+        >
+          {shapes.map((option) => (
+            <MenuItem key={option} value={option}>
+              {option}
+            </MenuItem>
+          ))}
+        </TextField>
+      </Stack>
       <Box sx={{ flexGrow: 1 }}>
         <LineChart
           height={250}
@@ -49,7 +83,7 @@ export default function LineMarkShape() {
               dataKey: 'london',
               label: 'London precipitation (mm)',
               curve: 'natural',
-              showMark: true,
+              showMark: marksMapping[marks],
               shape,
             },
           ]}

docs/data/charts/lines/lines.md

@@ -51,11 +51,18 @@ Set the series `area` property to `true` to fill the area under the line.
 
 ### Marks
 
-Add `showMark: true` to display marks.
+Add `showMark: true` to display marks for all values.
+
+It also accept a values `'start'` or `'end'` to display a mark on the first (or last) value of the series
 
 To modify the mark, use the property `shape`.
 It accepts 7 shapes: `'circle'`, `'square'`, `'diamond'`, `'cross'`, `'star'`, `'triangle'`, and `'wye'`.
 
+:::info
+The `'start' | 'end'` options render the highlight marks instead of the regular marks.
+As a result, while the pointer highlights a value, the start/end mark is replaced by the highlighted one.
+:::
+
 {{"demo": "LineMarkShape.js", "bg": "outline"}}
 
 ### Log scale
@@ -180,6 +187,13 @@ This uses the same curve interpolation as the rendered line (for example, `monot
 
 {{"demo": "LinePointerInteraction.js"}}
 
+### Highlight
+
+The line highlight display marks on top of the lines and marks.
+Even if you set `showMark: false`.
+
+You can turn off this behavior with the `disableHighlight` series property or the `disableLineItemHighlight` prop on the line chart.
+
 ## Styling
 
 ### Grid
@@ -244,16 +258,13 @@ Do not use `baseline` with stacked areas; the result will not match expectations
 
 ### Optimization
 
-Use the `showMark` series property to show mark elements.
-It accepts a boolean or a callback.
-The demo below uses a callback to show a mark only every two data points.
+Avoid displaying [marks](#marks) for large dataset.
 
-When a value is highlighted, a mark is drawn for that value.
-If the chart already shows marks (`showMark={true}`), the highlight mark is drawn on top.
+Either pass `'start'` or `'end'` to `showMark` to limit the number of element rendered on screen while keeping a mark for accessibility.
 
-You can turn off this behavior with the `disableHighlight` series property or the `disableLineItemHighlight` prop on the line chart.
+Or you can display a subset of the marks by providing a callback to `showMarks`.
 
-The demo shows one mark for every value with an even index.
+This demo shows one mark for values with even index.
 The highlighted point always shows a mark, whether its index is even or odd.
 
 {{"demo": "MarkOptimization.js"}}

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

@@ -25,7 +25,11 @@
     },
     "labelMarkType": { "type": { "description": "ChartsLabelMarkType" } },
     "shape": { "type": { "description": "MarkShape" } },
-    "showMark": { "type": { "description": "boolean | ((params: ShowMarkParams) => boolean)" } },
+    "showMark": {
+      "type": {
+        "description": "boolean | 'start' | 'end' | ((params: ShowMarkParams) => boolean)"
+      }
+    },
     "stack": { "type": { "description": "string" } },
     "stackOffset": { "type": { "description": "StackOffsetType" }, "default": "'none'" },
     "stackOrder": { "type": { "description": "StackOrderType" }, "default": "'none'" },

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

@@ -37,7 +37,7 @@
       "description": "The shape of the mark elements.<br />Using &#39;circle&#39; renders a <code>&amp;lt;circle /&amp;gt;</code> element, while all other options render a <code>&amp;lt;path /&amp;gt;</code> instead. The path causes a small decrease in performance.<br />By default, each series has a different shape, cycling through <code>&#39;circle&#39;</code>, <code>&#39;square&#39;</code>, <code>&#39;diamond&#39;</code>, <code>&#39;cross&#39;</code>, <code>&#39;star&#39;</code>, <code>&#39;triangle&#39;</code>, <code>&#39;wye&#39;</code>.<br />If there are more than 7 series, the shapes will repeat."
     },
     "showMark": {
-      "description": "Define which items of the series should display a mark.<br />If can be a boolean that applies to all items.<br />Or a callback that gets some item properties and returns true if the item should be displayed."
+      "description": "Define which items of the series should display a mark.<br />It can be a boolean that applies to all items.<br />It can be <code>&#39;start&#39;</code> or <code>&#39;end&#39;</code> to only display a mark on the first or last item. Such marks reuse<br />the line highlight element, so they are replaced by the highlighted item when the pointer<br />highlights a value.<br />Or a callback that gets some item properties and returns true if the item should be displayed."
     },
     "stack": {
       "description": "The key that identifies the stacking group.<br />Series with the same <code>stack</code> property will be stacked together."

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

@@ -168,6 +168,34 @@ describe('<LineChart />', () => {
     });
   });
 
+  describe('showMark', () => {
+    it('should not render highlight in stead of regular marks when set to "start"', () => {
+      render(
+        <LineChart
+          {...config}
+          series={[{ dataKey: 'v1', id: 's1', showMark: 'start' }]}
+          xAxis={[{ scaleType: 'band', dataKey: 'x' }]}
+        />,
+      );
+
+      expect(document.querySelectorAll(`.${lineClasses.mark}`)).to.have.length(0);
+      expect(document.querySelectorAll(`.${lineClasses.highlight}`)).to.have.length(1);
+    });
+
+    it('should not render highlight in stead of regular marks when set to "end"', () => {
+      render(
+        <LineChart
+          {...config}
+          series={[{ dataKey: 'v1', id: 's1', showMark: 'end' }]}
+          xAxis={[{ scaleType: 'band', dataKey: 'x' }]}
+        />,
+      );
+
+      expect(document.querySelectorAll(`.${lineClasses.mark}`)).to.have.length(0);
+      expect(document.querySelectorAll(`.${lineClasses.highlight}`)).to.have.length(1);
+    });
+  });
+
   describe('classes', () => {
     it('should apply MuiLineChart classes to area elements', () => {
       render(