Merge pull request #106 from jongalloway/feature/icon-pack-support

feat: pluggable SVG icon pack support for architecture diagrams

Author: jongalloway

DiagramForge.slnx

@@ -4,6 +4,7 @@
   </Folder>
   <Folder Name="/src/">
     <Project Path="src/DiagramForge.Cli/DiagramForge.Cli.csproj" />
+    <Project Path="src/DiagramForge.Icons.Heroicons/DiagramForge.Icons.Heroicons.csproj" />
     <Project Path="src/DiagramForge/DiagramForge.csproj" />
   </Folder>
   <Folder Name="/tests/">

src/DiagramForge.Icons.Heroicons/DiagramForge.Icons.Heroicons.csproj

@@ -0,0 +1,36 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <ItemGroup>
+    <ProjectReference Include="..\DiagramForge\DiagramForge.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="..\..\LICENSE" Pack="true" PackagePath="" Link="LICENSE" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <PackageReference Include="MinVer" PrivateAssets="All" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <EmbeddedResource Include="IconData\heroicons.json" LogicalName="heroicons.json" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>true</IsPackable>
+
+    <PackageId>DiagramForge.Icons.Heroicons</PackageId>
+    <Title>DiagramForge Heroicons Icon Pack</Title>
+    <Description>Heroicons SVG icon pack for DiagramForge. MIT-licensed outline icons from the Heroicons project.</Description>
+    <Authors>Jon Galloway</Authors>
+    <PackageTags>diagram svg icons heroicons diagramforge</PackageTags>
+    <PackageLicenseFile>LICENSE</PackageLicenseFile>
+    <RepositoryUrl>https://github.com/jongalloway/DiagramForge</RepositoryUrl>
+    <RepositoryType>git</RepositoryType>
+    <PackageProjectUrl>https://github.com/jongalloway/DiagramForge</PackageProjectUrl>
+  </PropertyGroup>
+
+</Project>

src/DiagramForge.Icons.Heroicons/HeroiconsExtensions.cs

@@ -0,0 +1,19 @@
+namespace DiagramForge.Icons.Heroicons;
+
+/// <summary>
+/// Extension methods for registering the Heroicons icon pack with DiagramForge.
+/// </summary>
+public static class HeroiconsExtensions
+{
+    /// <summary>
+    /// Registers the Heroicons (outline, 24×24) icon pack with the renderer
+    /// under the pack name <c>"heroicons"</c>.
+    /// </summary>
+    /// <returns>The renderer, for fluent chaining.</returns>
+    public static DiagramRenderer UseHeroicons(this DiagramRenderer renderer)
+    {
+        ArgumentNullException.ThrowIfNull(renderer);
+        renderer.RegisterIconPack("heroicons", new HeroiconsProvider());
+        return renderer;
+    }
+}

src/DiagramForge.Icons.Heroicons/HeroiconsProvider.cs

@@ -0,0 +1,44 @@
+using System.Text.Json;
+using DiagramForge.Abstractions;
+using DiagramForge.Models;
+
+namespace DiagramForge.Icons.Heroicons;
+
+/// <summary>
+/// Provides Heroicons (outline, 24×24) as a DiagramForge icon pack.
+/// Icons are loaded from an embedded JSON resource on first access.
+/// </summary>
+public sealed class HeroiconsProvider : IIconProvider
+{
+    private const string ViewBox = "0 0 24 24";
+    private readonly Lazy<Dictionary<string, string>> _icons = new(LoadIcons);
+
+    /// <inheritdoc/>
+    public DiagramIcon? GetIcon(string name)
+    {
+        if (_icons.Value.TryGetValue(name, out var svgContent))
+            return new DiagramIcon("heroicons", name, ViewBox, svgContent);
+
+        return null;
+    }
+
+    /// <inheritdoc/>
+    public IEnumerable<string> AvailableIcons => _icons.Value.Keys;
+
+    private static Dictionary<string, string> LoadIcons()
+    {
+        var assembly = typeof(HeroiconsProvider).Assembly;
+        using var stream = assembly.GetManifestResourceStream("heroicons.json")
+            ?? throw new InvalidOperationException("Heroicons embedded resource not found.");
+
+        var data = JsonSerializer.Deserialize(stream, HeroiconsJsonContext.Default.DictionaryStringString)
+            ?? throw new InvalidOperationException("Failed to deserialize heroicons data.");
+
+        return new Dictionary<string, string>(data, StringComparer.OrdinalIgnoreCase);
+    }
+}
+
+[System.Text.Json.Serialization.JsonSerializable(typeof(Dictionary<string, string>))]
+internal partial class HeroiconsJsonContext : System.Text.Json.Serialization.JsonSerializerContext
+{
+}

src/DiagramForge.Icons.Heroicons/IconData/heroicons.json

@@ -0,0 +1,20 @@
+using DiagramForge.Models;
+
+namespace DiagramForge.Abstractions;
+
+/// <summary>
+/// Provides icons by name within a single icon pack.
+/// </summary>
+public interface IIconProvider
+{
+    /// <summary>
+    /// Resolves an icon by <paramref name="name"/> within this provider's pack.
+    /// Returns <see langword="null"/> if the icon is not found.
+    /// </summary>
+    DiagramIcon? GetIcon(string name);
+
+    /// <summary>
+    /// Returns all icon names available in this provider.
+    /// </summary>
+    IEnumerable<string> AvailableIcons { get; }
+}

src/DiagramForge/Abstractions/IIconProvider.cs

@@ -11,6 +11,10 @@
     <PackageReference Include="MinVer" PrivateAssets="All" />
   </ItemGroup>
 
+  <ItemGroup>
+    <InternalsVisibleTo Include="DiagramForge.Tests" />
+  </ItemGroup>
+
   <PropertyGroup>
     <TargetFramework>net10.0</TargetFramework>
     <ImplicitUsings>enable</ImplicitUsings>

src/DiagramForge/DiagramForge.csproj

@@ -1,5 +1,6 @@
 using System.Text.Json;
 using DiagramForge.Abstractions;
+using DiagramForge.Icons;
 using DiagramForge.Layout;
 using DiagramForge.Models;
 using DiagramForge.Parsers.Conceptual;
@@ -29,6 +30,12 @@ public sealed class DiagramRenderer
     private readonly ISvgRenderer _svgRenderer;
     private readonly Theme _defaultTheme;
 
+    /// <summary>
+    /// Icon registry used to resolve <see cref="Node.IconRef"/> references to
+    /// <see cref="DiagramIcon"/> instances before rendering.
+    /// </summary>
+    public IconRegistry IconRegistry { get; } = new();
+
     /// <summary>
     /// Creates a <see cref="DiagramRenderer"/> with the default parser set, layout engine, and theme.
     /// </summary>
@@ -58,10 +65,24 @@ public DiagramRenderer(
         _layoutEngine = layoutEngine;
         _svgRenderer = svgRenderer;
         _defaultTheme = defaultTheme;
+
+        // Register built-in Mermaid architecture icons (cloud, database, disk, internet, server).
+        IconRegistry.RegisterPack("builtin", new BuiltInArchitectureIconProvider());
     }
 
     // ── Public API ────────────────────────────────────────────────────────────
 
+    /// <summary>
+    /// Registers a named icon pack. Icons can then be referenced in diagrams as
+    /// <c>packName:icon-name</c>.
+    /// </summary>
+    /// <returns>This renderer, for fluent chaining.</returns>
+    public DiagramRenderer RegisterIconPack(string packName, IIconProvider provider)
+    {
+        IconRegistry.RegisterPack(packName, provider);
+        return this;
+    }
+
     /// <summary>
     /// Converts <paramref name="diagramText"/> to an SVG string using the default theme.
     /// The correct parser is selected automatically based on the diagram text.
@@ -161,6 +182,7 @@ public string Render(string diagramText, Theme? theme, string? paletteJson, bool
             diagram.LayoutHints.EdgeRouting = frontmatter.EdgeRouting.Value;
         }
 
+        ResolveIcons(diagram);
         _layoutEngine.Layout(diagram, effectiveTheme);
         return _svgRenderer.Render(diagram, effectiveTheme);
     }
@@ -183,6 +205,26 @@ public DiagramRenderer RegisterParser(IDiagramParser parser)
 
     // ── Private helpers ───────────────────────────────────────────────────────
 
+    private void ResolveIcons(Diagram diagram)
+    {
+        foreach (var node in diagram.Nodes.Values)
+        {
+            if (node.IconRef is not null)
+            {
+                var icon = IconRegistry.Resolve(node.IconRef);
+                if (icon is not null)
+                {
+                    // Sanitize the SVG content before placing it into the output SVG
+                    // to prevent XSS / injection from untrusted diagram text or icon providers.
+                    string? sanitized = SvgIconSanitizer.Sanitize(icon.SvgContent);
+                    node.ResolvedIcon = sanitized is not null
+                        ? icon with { SvgContent = sanitized }
+                        : null;
+                }
+            }
+        }
+    }
+
     private IDiagramParser? FindParser(string diagramText)
     {
         foreach (var parser in _parsers)

src/DiagramForge/DiagramRenderer.cs

@@ -0,0 +1,45 @@
+using DiagramForge.Abstractions;
+using DiagramForge.Models;
+
+namespace DiagramForge.Icons;
+
+/// <summary>
+/// Provides the five built-in Mermaid architecture diagram icons:
+/// <c>cloud</c>, <c>database</c>, <c>disk</c>, <c>internet</c>, and <c>server</c>.
+/// </summary>
+/// <remarks>
+/// SVG paths are designed to render clearly at 24×24 viewBox, matching Mermaid's
+/// built-in icon set for architecture diagrams.
+/// </remarks>
+internal sealed class BuiltInArchitectureIconProvider : IIconProvider
+{
+    private const string ViewBox = "0 0 24 24";
+
+    private static readonly Dictionary<string, string> Icons = new(StringComparer.OrdinalIgnoreCase)
+    {
+        ["cloud"] =
+            """<path d="M18.74 10.04A6.87 6.87 0 0 0 12 4C9.34 4 7.05 5.64 5.9 8.04A5.5 5.5 0 0 0 1 14c0 3.31 2.47 6 5.5 6h11.93c2.53 0 4.58-2.24 4.58-5 0-2.64-1.88-4.78-4.27-4.96z" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"/>""",
+
+        ["database"] =
+            """<g fill="none" stroke="currentColor" stroke-width="1.5"><ellipse cx="12" cy="5.5" rx="8" ry="3.5"/><path d="M4 5.5v13c0 1.93 3.58 3.5 8 3.5s8-1.57 8-3.5v-13"/><path d="M4 12c0 1.93 3.58 3.5 8 3.5s8-1.57 8-3.5"/></g>""",
+
+        ["disk"] =
+            """<g fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="12" cy="12" r="10"/><circle cx="12" cy="12" r="3"/><line x1="12" y1="2" x2="12" y2="9"/></g>""",
+
+        ["internet"] =
+            """<g fill="none" stroke="currentColor" stroke-width="1.5"><circle cx="12" cy="12" r="10"/><ellipse cx="12" cy="12" rx="4" ry="10"/><line x1="2" y1="12" x2="22" y2="12"/><path d="M4.93 5h14.14M4.93 19h14.14"/></g>""",
+
+        ["server"] =
+            """<g fill="none" stroke="currentColor" stroke-width="1.5"><rect x="2" y="2" width="20" height="8" rx="2" ry="2"/><rect x="2" y="14" width="20" height="8" rx="2" ry="2"/><circle cx="6" cy="6" r="1" fill="currentColor"/><circle cx="6" cy="18" r="1" fill="currentColor"/></g>""",
+    };
+
+    public DiagramIcon? GetIcon(string name)
+    {
+        if (Icons.TryGetValue(name, out var svgContent))
+            return new DiagramIcon("builtin", name, ViewBox, svgContent);
+
+        return null;
+    }
+
+    public IEnumerable<string> AvailableIcons => Icons.Keys;
+}