feat(xychart): add per-point text labels for line charts

.changeset/add-xychart-point-labels.md

@@ -0,0 +1,5 @@
+---
+'mermaid': minor
+---
+
+feat: add per-point text labels for xychart line plots

.cspell/misc-terms.txt

@@ -3,6 +3,7 @@ Buzan
 circo
 handDrawn
 KOEPF
+MMLU
 neato
 newbranch
 validify

cypress/integration/rendering/xyChart.spec.js

@@ -879,4 +879,57 @@ describe('XY Chart', () => {
       });
     });
   });
+
+  it('should render a line chart with point labels', () => {
+    imgSnapshotTest(
+      `
+      xychart
+        title "Smallest AI models scoring above 60% on MMLU"
+        x-axis "Date" ["Apr 2022", "Feb 2023", "Jul 2023", "Sep 2023", "Apr 2024"]
+        y-axis "Parameters (B)" 0 --> 600
+        line [540 "PaLM", 65 "LLaMA-65B", 34 "Llama 2 34B", 7 "Mistral 7B", 3.8 "Phi-3-mini"]
+      `,
+      {}
+    );
+  });
+
+  it('should render a line chart with mixed labels (some points labeled, some not)', () => {
+    imgSnapshotTest(
+      `
+      xychart
+        title "Quarterly Performance"
+        x-axis [Q1, Q2, Q3, Q4]
+        y-axis "Revenue ($M)" 0 --> 100
+        line [25 "Launch", 45, 72, 90 "Target Hit"]
+      `,
+      {}
+    );
+  });
+
+  it('should render a horizontal line chart with point labels', () => {
+    imgSnapshotTest(
+      `
+      xychart horizontal
+        title "Model Sizes"
+        x-axis ["Model A", "Model B", "Model C"]
+        y-axis "Parameters" 0 --> 100
+        line [20 "Small", 50 "Medium", 90 "Large"]
+      `,
+      {}
+    );
+  });
+
+  it('should render multiple lines where only one has labels', () => {
+    imgSnapshotTest(
+      `
+      xychart
+        title "Comparison"
+        x-axis [Q1, Q2, Q3, Q4]
+        y-axis "Value" 0 --> 100
+        line [20, 40, 60, 80]
+        line [30 "Start", 50, 70, 95 "Peak"]
+      `,
+      {}
+    );
+  });
 });

demos/xychart.html

@@ -316,6 +316,26 @@ <h1>XY Charts demos with all theme config</h1>
     </pre>
     <hr />
 
+    <hr />
+    <h1>Line chart with point labels</h1>
+    <pre class="mermaid">
+    xychart
+      title "Smallest AI models scoring above 60% on MMLU"
+      x-axis "Date" ["Apr 2022", "Feb 2023", "Jul 2023", "Sep 2023", "Apr 2024"]
+      y-axis "Parameters (B)" 0 --> 600
+      line [540 "PaLM", 65 "LLaMA-65B", 34 "Llama 2 34B", 7 "Mistral 7B", 3.8 "Phi-3-mini"]
+    </pre>
+
+    <hr />
+    <h1>Line chart with mixed labels (some points labeled, some not)</h1>
+    <pre class="mermaid">
+    xychart
+      title "Quarterly Performance"
+      x-axis [Q1, Q2, Q3, Q4]
+      y-axis "Revenue ($M)" 0 --> 100
+      line [25 "Launch", 45, 72, 90 "Target Hit"]
+    </pre>
+
     <script type="module">
       import mermaid from './mermaid.esm.mjs';
       mermaid.initialize({

docs/syntax/xyChart.md

@@ -271,6 +271,49 @@ xychart
     bar [12,2,20,25,17,24]
 ```
 
+## Per-point text labels for line charts (v\<MERMAID_RELEASE_VERSION>+)
+
+Each data point in a `line` can optionally include a quoted string label after the numeric value. Labels render above points in vertical orientation, or to the right in horizontal orientation, using the line's stroke color.
+
+```mermaid-example
+xychart
+    title "Smallest AI models scoring above 60% on MMLU"
+    x-axis "Date" ["Apr 2022", "Feb 2023", "Jul 2023", "Sep 2023", "Apr 2024"]
+    y-axis "Parameters (B)" 0 --> 600
+    line [540 "PaLM", 65 "LLaMA-65B", 34 "Llama 2 34B", 7 "Mistral 7B", 3.8 "Phi-3-mini"]
+```
+
+```mermaid
+xychart
+    title "Smallest AI models scoring above 60% on MMLU"
+    x-axis "Date" ["Apr 2022", "Feb 2023", "Jul 2023", "Sep 2023", "Apr 2024"]
+    y-axis "Parameters (B)" 0 --> 600
+    line [540 "PaLM", 65 "LLaMA-65B", 34 "Llama 2 34B", 7 "Mistral 7B", 3.8 "Phi-3-mini"]
+```
+
+Labels are optional per point — you can mix labeled and unlabeled values:
+
+```mermaid-example
+xychart
+    title "Quarterly Performance"
+    x-axis [Q1, Q2, Q3, Q4]
+    y-axis "Revenue ($M)" 0 --> 100
+    line [25 "Launch", 45, 72, 90 "Target Hit"]
+```
+
+```mermaid
+xychart
+    title "Quarterly Performance"
+    x-axis [Q1, Q2, Q3, Q4]
+    y-axis "Revenue ($M)" 0 --> 100
+    line [25 "Launch", 45, 72, 90 "Target Hit"]
+```
+
+Existing syntax without labels continues to work unchanged.
+
+> **Note**
+> Point labels use a fixed font size of 12px. In vertical charts, labels appear above each point. In horizontal charts, labels appear to the right.
+
 ## Example on config and theme
 
 ```mermaid-example

packages/mermaid/src/diagrams/xychart/chartBuilder/components/plot/linePlot.ts

@@ -1,5 +1,5 @@
 import { line } from 'd3';
-import type { DrawableElem, LinePlotData, XYChartConfig } from '../../interfaces.js';
+import type { DrawableElem, LinePlotData, TextElem, XYChartConfig } from '../../interfaces.js';
 import type { Axis } from '../axis/index.js';
 
 export class LinePlot {
@@ -30,7 +30,8 @@ export class LinePlot {
     if (!path) {
       return [];
     }
-    return [
+
+    const elements: DrawableElem[] = [
       {
         groupTexts: ['plot', `line-plot-${this.plotIndex}`],
         type: 'path',
@@ -43,5 +44,52 @@ export class LinePlot {
         ],
       },
     ];
+
+    if (this.plotData.pointLabels && this.plotData.pointLabels.length > 0) {
+      const labelOffset = 10;
+      const fontSize = 12;
+      const textData: TextElem[] = [];
+
+      for (const [i, [px, py]] of finalData.entries()) {
+        const label = this.plotData.pointLabels[i];
+        if (!label) {
+          continue;
+        }
+
+        if (this.orientation === 'horizontal') {
+          textData.push({
+            x: py + labelOffset,
+            y: px,
+            text: label,
+            fill: this.plotData.strokeFill,
+            verticalPos: 'middle',
+            horizontalPos: 'left',
+            fontSize,
+            rotation: 0,
+          });
+        } else {
+          textData.push({
+            x: px,
+            y: py - labelOffset,
+            text: label,
+            fill: this.plotData.strokeFill,
+            verticalPos: 'middle',
+            horizontalPos: 'center',
+            fontSize,
+            rotation: 0,
+          });
+        }
+      }
+
+      if (textData.length > 0) {
+        elements.push({
+          groupTexts: ['plot', `line-plot-${this.plotIndex}`, 'labels'],
+          type: 'text',
+          data: textData,
+        });
+      }
+    }
+
+    return elements;
   }
 }

packages/mermaid/src/diagrams/xychart/chartBuilder/interfaces.ts

@@ -33,6 +33,7 @@ export interface LinePlotData {
   strokeFill: string;
   strokeWidth: number;
   data: SimplePlotDataType;
+  pointLabels?: string[];
 }
 
 export interface BarPlotData {

packages/mermaid/src/diagrams/xychart/parser/xychart.jison

@@ -111,12 +111,17 @@ statement
   ;
 
 plotData
-  : SQUARE_BRACES_START commaSeparatedNumbers SQUARE_BRACES_END   { $$ = $commaSeparatedNumbers }
+  : SQUARE_BRACES_START dataPoints SQUARE_BRACES_END   { $$ = $dataPoints }
   ;
 
-commaSeparatedNumbers
-  : NUMBER_WITH_DECIMAL COMMA commaSeparatedNumbers                { $$ = [Number($NUMBER_WITH_DECIMAL), ...$commaSeparatedNumbers] }
-  | NUMBER_WITH_DECIMAL                                           { $$ = [Number($NUMBER_WITH_DECIMAL)] }
+dataPoints
+  : dataPoint COMMA dataPoints                { $$ = [$dataPoint, ...$dataPoints] }
+  | dataPoint                                 { $$ = [$dataPoint] }
+  ;
+
+dataPoint
+  : NUMBER_WITH_DECIMAL STR                   { $$ = { value: Number($1), label: $2 } }
+  | NUMBER_WITH_DECIMAL                       { $$ = { value: Number($1), label: '' } }
   ;
 
 parseXAxis