Merge pull request #115 from jongalloway/feature/matrix-cell-icons

Add matrix cell icon support

Author: jongalloway

README.md

@@ -86,11 +86,11 @@ DiagramForge currently supports more than a dozen diagram types across Mermaid a
   </tr>
   <tr>
     <td align="center" valign="top" width="33%">
-      <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-matrix.expected.svg">
-        <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-matrix.expected.svg" alt="Conceptual matrix" height="96" />
+      <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-matrix-icons.expected.svg">
+        <img src="https://raw.githubusercontent.com/jongalloway/DiagramForge/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-matrix-icons.expected.svg" alt="Conceptual matrix with icons" height="96" />
       </a>
       <br />
-      <sub>Conceptual Matrix</sub>
+      <sub>Conceptual Matrix + Icons</sub>
     </td>
     <td align="center" valign="top" width="33%">
       <a href="https://github.com/jongalloway/DiagramForge/blob/main/tests/DiagramForge.E2ETests/Fixtures/conceptual-pillars-icons.expected.svg">
@@ -365,13 +365,27 @@ Supported icon-bearing diagram types today:
 - Conceptual cycle
 - Conceptual chevrons
 - Conceptual funnel
+- Conceptual matrix
 - Conceptual pillars
 - Conceptual pyramid
 - Conceptual radial
 
-Not yet supported:
+For conceptual matrix diagrams, icons are attached per cell through an optional `cells:` list in row-major order. Non-empty cell entries must contain an icon directive; use a blank `-` to leave a cell without an icon.
 
-- Conceptual matrix
+```yaml
+diagram: matrix
+rows:
+  - Important
+  - Not Important
+columns:
+  - Urgent
+  - Not Urgent
+cells:
+  - icon:builtin:cloud
+  -
+  - Lower-left [icon:heroicons:shield-check]
+  - [icon:builtin:database]
+```
 
 #### Registering an icon pack
 

src/DiagramForge/Layout/DefaultLayoutEngine.Matrix.cs

@@ -22,12 +22,16 @@ private static void LayoutMatrixDiagram(
 
         double titleOffset = !string.IsNullOrWhiteSpace(diagram.Title) ? theme.TitleFontSize + 8 : 0;
         double baseFontSize = cells.Max(node => node.Label.FontSize ?? theme.FontSize);
-        int maxLineCount = cells.Max(node => GetTextLineCount(node.Label));
-        double maxTextWidth = cells.Max(node => EstimateTextWidth(node.Label, node.Label.FontSize ?? theme.FontSize));
-
-        double cellWidth = Math.Max(minW + 24, maxTextWidth + theme.NodePadding * 2.5);
-        double textBlockHeight = Math.Max(1, maxLineCount) * baseFontSize * 1.15;
-        double cellHeight = Math.Max(nodeH + baseFontSize * 0.7, textBlockHeight + theme.NodePadding * 2.6);
+        double cellWidth = cells.Max(node =>
+            EnsureIconWidth(node, theme, Math.Max(minW + 24, EstimateTextWidth(node.Label, node.Label.FontSize ?? theme.FontSize) + theme.NodePadding * 2.5)));
+        double cellHeight = cells.Max(node =>
+        {
+            double fontSize = node.Label.FontSize ?? theme.FontSize;
+            int lineCount = Math.Max(1, GetTextLineCount(node.Label));
+            double textBlockHeight = lineCount * fontSize * 1.15;
+            double baseHeight = Math.Max(nodeH + baseFontSize * 0.7, textBlockHeight + theme.NodePadding * 2.6);
+            return EnsureIconHeight(node, baseHeight);
+        });
         double gap = Math.Max(theme.NodePadding, 18);
 
         string[] palette = theme.NodePalette is { Count: > 0 }

src/DiagramForge/Parsers/Conceptual/ConceptualDslParser.Matrix.cs

@@ -9,22 +9,45 @@ private static void ParseMatrixDiagram(string[] lines, IDiagramSemanticModelBuil
     {
         int rowsLine = FindSectionLine(lines, "rows");
         int colsLine = FindSectionLine(lines, "columns");
+        int cellsLine = FindSectionLine(lines, "cells");
 
         var rows = rowsLine >= 0 ? ReadListItems(lines, rowsLine + 1) : [];
         var cols = colsLine >= 0 ? ReadListItems(lines, colsLine + 1) : [];
+        var cells = cellsLine >= 0 ? ReadListItems(lines, cellsLine + 1) : [];
 
         if (rows.Count == 0 || cols.Count == 0)
             throw new DiagramParseException("Matrix diagram requires non-empty 'rows' and 'columns' sections.");
 
         if (rows.Count != 2 || cols.Count != 2)
             throw new DiagramParseException("Matrix diagram currently supports exactly 2 rows and 2 columns.");
 
+        int maxCellCount = rows.Count * cols.Count;
+        if (cells.Count > maxCellCount)
+            throw new DiagramParseException($"Matrix diagram supports at most {maxCellCount} 'cells' entries, but {cells.Count} were provided.");
+
         for (int r = 0; r < rows.Count; r++)
         {
             for (int c = 0; c < cols.Count; c++)
             {
                 var nodeId = $"cell_{r}_{c}";
                 var node = new Node(nodeId, $"{cols[c]}\n{rows[r]}");
+                int cellIndex = (r * cols.Count) + c;
+                if (cellIndex < cells.Count)
+                {
+                    string cellValue = cells[cellIndex];
+                    if (!string.IsNullOrWhiteSpace(cellValue))
+                    {
+                        var spec = ParseIconLabeledText(cellValue);
+                        if (spec.IconRef is null)
+                        {
+                            throw new DiagramParseException(
+                                $"Matrix 'cells' entry {cellIndex + 1} must be blank or contain an icon directive like 'icon:pack:name'.");
+                        }
+
+                        node.IconRef = spec.IconRef;
+                    }
+                }
+
                 node.Metadata["matrix:row"] = r;
                 node.Metadata["matrix:column"] = c;
                 node.Metadata["matrix:rowLabel"] = rows[r];

tests/DiagramForge.E2ETests/Fixtures/conceptual-matrix-icons.expected.svg

@@ -0,0 +1,15 @@
+---
+theme: presentation
+---
+diagram: matrix
+rows:
+  - Important
+  - Not Important
+columns:
+  - Urgent
+  - Not Urgent
+cells:
+  - icon:builtin:cloud
+  -
+  - Lower-left [icon:heroicons:shield-check]
+  - [icon:builtin:database]

tests/DiagramForge.E2ETests/Fixtures/conceptual-matrix-icons.input

@@ -1,5 +1,6 @@
 using DiagramForge.Layout;
 using DiagramForge.Models;
+using DiagramForge.Rendering;
 
 namespace DiagramForge.Tests.Layout;
 
@@ -309,6 +310,30 @@ public void Layout_MatrixDiagram_PlacesQuadrantsInTwoByTwoGrid()
         Assert.Equal(topLeft.Height / 2, Convert.ToDouble(topLeft.Metadata["label:centerY"], System.Globalization.CultureInfo.InvariantCulture));
     }
 
+    [Fact]
+    public void Layout_MatrixDiagram_WithIcons_MakesCellsLargeEnoughForIconArea()
+    {
+        var diagram = new Diagram { DiagramType = "matrix" };
+
+        var withIcon = MatrixCell("cell_0_0", "Urgent\nImportant", 0, 0);
+        withIcon.ResolvedIcon = new DiagramIcon("builtin", "cloud", "0 0 24 24", "<path d=\"M0 0h24v24H0z\" />");
+
+        diagram.AddNode(withIcon)
+               .AddNode(MatrixCell("cell_0_1", "Not Urgent\nImportant", 0, 1))
+               .AddNode(MatrixCell("cell_1_0", "Urgent\nNot Important", 1, 0))
+               .AddNode(MatrixCell("cell_1_1", "Not Urgent\nNot Important", 1, 1));
+
+        _engine.Layout(diagram, _theme);
+
+        double minIconWidth = SvgNodeWriter.DefaultIconSize + (2 * _theme.NodePadding);
+        double minIconHeight = SvgNodeWriter.DefaultIconSize + SvgNodeWriter.IconLabelGap;
+
+        Assert.True(withIcon.Width >= minIconWidth,
+            $"Expected icon-bearing matrix cell width {withIcon.Width} to be >= {minIconWidth}.");
+        Assert.True(withIcon.Height >= diagram.LayoutHints.MinNodeHeight + minIconHeight,
+            $"Expected icon-bearing matrix cell height {withIcon.Height} to include icon area of at least {minIconHeight}.");
+    }
+
     [Fact]
     public void Layout_Pyramid_AssignsTriangularSegmentMetadata()
     {