fix(xychart): auto-flip point labels to avoid line collision

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

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

.changeset/fix-xychart-label-line-collision.md

@@ -0,0 +1,5 @@
+---
+'mermaid': patch
+---
+
+fix: auto-flip xychart point labels to avoid collision with line on steep slopes

.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,107 @@ 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"]
+      `,
+      {}
+    );
+  });
+
+  it('should render reviewer example: label at 80 "target hit" does not collide with line', () => {
+    imgSnapshotTest(
+      `
+      xychart
+          title "Quarterly Performance"
+          x-axis [Q1, Q2, Q3, Q4]
+          y-axis "Revenue ($M)" 0 --> 100
+          line [25, 45, 80 "target hit", 90]
+      `,
+      {}
+    );
+  });
+
+  describe('Point label collision avoidance', () => {
+    it('should flip labels below line when steep descent causes collision', () => {
+      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 keep labels above line when no collision on gentle slope', () => {
+      imgSnapshotTest(
+        `
+        xychart
+          x-axis ["A", "B", "C"]
+          y-axis 0 --> 100
+          line [40 "Start", 50 "Mid", 45 "End"]
+        `,
+        {}
+      );
+    });
+    it('should handle mixed collision: some labels above, some below', () => {
+      imgSnapshotTest(
+        `
+        xychart
+          x-axis ["P1", "P2", "P3", "P4"]
+          y-axis 0 --> 500
+          line [400 "High", 50 "Low", 450 "Peak", 30 "Bottom"]
+        `,
+        {}
+      );
+    });
+  });
 });

demos/xychart.html

@@ -316,6 +316,55 @@ <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>
+
+    <hr />
+    <h1>Reviewer's failing example: label at 80 "target hit"</h1>
+    <pre class="mermaid">
+    xychart
+        title "Quarterly Performance"
+        x-axis [Q1, Q2, Q3, Q4]
+        y-axis "Revenue ($M)" 0 --> 100
+        line [25, 45, 80 "target hit", 90]
+    </pre>
+
+    <hr />
+    <h1>Label collision avoidance: steep descent</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>Label collision avoidance: zigzag pattern</h1>
+    <pre class="mermaid">
+    xychart
+      x-axis ["P1", "P2", "P3", "P4"]
+      y-axis 0 --> 500
+      line [400 "High", 50 "Low", 450 "Peak", 30 "Bottom"]
+    </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