Prepared for first full release.

Author: KristofferStrube

src/KristofferStrube.Blazor.GraphEditor/Edge.cs

@@ -4,29 +4,67 @@
 
 namespace KristofferStrube.Blazor.GraphEditor;
 
+/// <summary>
+/// The edge between two <see cref="Node{TNodeData, TEdgeData}"/>s.
+/// </summary>
+/// <typeparam name="TNodeData">The type parameter for the data that backs the nodes in this graph.</typeparam>
+/// <typeparam name="TEdgeData">The type parameter for the data that backs the nodes in this graph.</typeparam>
 public class Edge<TNodeData, TEdgeData> : Line where TNodeData : IEquatable<TNodeData>
 {
+    /// <summary>
+    /// Constructs an edge.
+    /// </summary>
+    /// <param name="element">The SVG element that will be used as the base backing element for changes to the position of the edge.</param>
+    /// <param name="svg">The <see cref="SVGEditor.SVGEditor"/> that the edge resides in.</param>
     public Edge(IElement element, SVGEditor.SVGEditor svg) : base(element, svg)
     {
         UpdateLine();
     }
 
+    /// <summary>
+    /// The component type that will be used to edit this shape.
+    /// </summary>
     public override Type Presenter => typeof(EdgeEditor<TNodeData, TEdgeData>);
 
-    public GraphEditor<TNodeData, TEdgeData> GraphEditor { get; set; }
-
-    public TEdgeData Data { get; set; }
-
-    public Node<TNodeData, TEdgeData> From { get; set; }
-
-    public Node<TNodeData, TEdgeData> To { get; set; }
-
+    /// <summary>
+    /// The <see cref="GraphEditor{TNode, TEdge}"/> that this edge belongs to.
+    /// </summary>
+    public required GraphEditor<TNodeData, TEdgeData> GraphEditor { get; set; }
+
+    /// <summary>
+    /// The data that this edge will get its characteristics from.
+    /// </summary>
+    public required TEdgeData Data { get; set; }
+
+    /// <summary>
+    /// The node that the edge goes from.
+    /// </summary>
+    public required Node<TNodeData, TEdgeData> From { get; set; }
+
+    /// <summary>
+    /// The node that the edge goes to.
+    /// </summary>
+    public required Node<TNodeData, TEdgeData> To { get; set; }
+
+    /// <summary>
+    /// The width of the edge mapped from its <see cref="Data"/>.
+    /// </summary>
     public new string StrokeWidth => GraphEditor.EdgeWidthMapper(Data).AsString();
 
+    /// <summary>
+    /// The color of the edge mapped from its <see cref="Data"/>.
+    /// </summary>
     public new string Stroke => GraphEditor.EdgeColorMapper(Data);
 
+    /// <summary>
+    /// Whether the edge should show an arrow head at its <see cref="To"/> end.
+    /// </summary>
     public bool ShowArrow => GraphEditor.EdgeShowsArrow(Data);
 
+    /// <summary>
+    /// Handles when the shape is moved.
+    /// </summary>
+    /// <param name="eventArgs">The arguments from the pointer that is moved.</param>
     public override void HandlePointerMove(PointerEventArgs eventArgs)
     {
         if (SVG.EditMode is EditMode.Add)
@@ -36,6 +74,10 @@ public override void HandlePointerMove(PointerEventArgs eventArgs)
         }
     }
 
+    /// <summary>
+    /// Handles when the shape stops moving.
+    /// </summary>
+    /// <param name="eventArgs">The arguments from the pointer that stops.</param>
     public override void HandlePointerUp(PointerEventArgs eventArgs)
     {
         if (SVG.EditMode is EditMode.Add
@@ -54,6 +96,9 @@ public override void HandlePointerUp(PointerEventArgs eventArgs)
         }
     }
 
+    /// <summary>
+    /// The method that is invoked when an edge finishes its creation process.
+    /// </summary>
     public override void Complete()
     {
         if (To is null)
@@ -63,6 +108,10 @@ public override void Complete()
         }
     }
 
+    /// <summary>
+    /// Updates the coordinates of the start of the line.
+    /// </summary>
+    /// <param name="towards">The coordinates of where the edge will go towards.</param>
     public void SetStart((double x, double y) towards)
     {
         double differenceX = towards.x - From!.Cx;
@@ -76,6 +125,9 @@ public void SetStart((double x, double y) towards)
         }
     }
 
+    /// <summary>
+    /// Updates the coordinates of the start and end of the edge.
+    /// </summary>
     public void UpdateLine()
     {
         if (From is null || To is null)
@@ -100,6 +152,15 @@ public void UpdateLine()
         }
     }
 
+    /// <summary>
+    /// Adds a new edge.
+    /// </summary>
+    /// <param name="SVG">The <see cref="SVGEditor.SVGEditor"/> that the shape will be create in.</param>
+    /// <param name="graphEditor">The <see cref="GraphEditor{TNode, TEdge}"/> that the edge resides in.</param>
+    /// <param name="data">The backing data that the edge will be created from.</param>
+    /// <param name="from">The <see cref="Node{TNodeData, TEdgeData}"/> that the edge goes from.</param>
+    /// <param name="to">The <see cref="Node{TNodeData, TEdgeData}"/> that the edge goes to.</param>
+    /// <returns>The new edge.</returns>
     public static Edge<TNodeData, TEdgeData> AddNew(
         SVGEditor.SVGEditor SVG,
         GraphEditor<TNodeData, TEdgeData> graphEditor,

src/KristofferStrube.Blazor.GraphEditor/GraphEditor.razor.cs

@@ -3,6 +3,11 @@
 
 namespace KristofferStrube.Blazor.GraphEditor;
 
+/// <summary>
+/// An editor for graphs consisting of nodes and edges.
+/// </summary>
+/// <typeparam name="TNode">The type that will represent the nodes in graph.</typeparam>
+/// <typeparam name="TEdge">The type that will represent the connections between the nodes in the graph.</typeparam>
 public partial class GraphEditor<TNode, TEdge> : ComponentBase where TNode : IEquatable<TNode>
 {
     private GraphEditorCallbackContext callbackContext = default!;
@@ -12,6 +17,9 @@ private string EdgeId(TEdge e)
         return NodeIdMapper(EdgeFromMapper(e)) + "-" + NodeIdMapper(EdgeToMapper(e));
     }
 
+    /// <summary>
+    /// Maps each node to an unique id.
+    /// </summary>
     [Parameter, EditorRequired]
     public required Func<TNode, string> NodeIdMapper { get; set; }
 
@@ -39,9 +47,15 @@ private string EdgeId(TEdge e)
     [Parameter]
     public Func<TNode, string?> NodeImageMapper { get; set; } = _ => null;
 
+    /// <summary>
+    /// Maps each edge to which node it goes from.
+    /// </summary>
     [Parameter, EditorRequired]
     public required Func<TEdge, TNode> EdgeFromMapper { get; set; }
 
+    /// <summary>
+    /// Maps each edge to which node it goes to.
+    /// </summary>
     [Parameter, EditorRequired]
     public required Func<TEdge, TNode> EdgeToMapper { get; set; }
 
@@ -69,25 +83,44 @@ private string EdgeId(TEdge e)
     [Parameter]
     public Func<TEdge, string> EdgeColorMapper { get; set; } = _ => "#000000";
 
-    [Parameter]
     /// <summary>
     /// Defaults to <see langword="true"/>
     /// </summary>
+    [Parameter]
     public Func<TEdge, bool> EdgeShowsArrow { get; set; } = _ => true;
 
+    /// <summary>
+    /// Callback that will be invoked when a specific node is selected by it getting focus.
+    /// </summary>
     [Parameter]
     public Func<TNode, Task>? NodeSelectionCallback { get; set; }
 
+    /// <summary>
+    /// Whether the underlying <see cref="SVGEditor.SVGEditor"/> has rendered.
+    /// </summary>
     public bool IsReadyToLoad => SVGEditor.BBox is not null;
 
+    /// <summary>
+    /// The nodes of the graph.
+    /// </summary>
     protected Dictionary<string, TNode> Nodes { get; set; } = [];
 
+    /// <summary>
+    /// The edges of the graph.
+    /// </summary>
     protected Dictionary<string, TEdge> Edges { get; set; } = [];
 
+    /// <summary>
+    /// The underlying <see cref="SVGEditor.SVGEditor"/>.
+    /// </summary>
     public SVGEditor.SVGEditor SVGEditor { get; set; } = default!;
 
+    /// <summary>
+    /// A text representation of the graph.
+    /// </summary>
     protected string Input { get; set; } = "";
 
+    /// <inheritdoc/>
     protected override void OnInitialized()
     {
         callbackContext = new()
@@ -102,6 +135,11 @@ protected override void OnInitialized()
         };
     }
 
+    /// <summary>
+    /// Loads a graph of nodes and edges.
+    /// </summary>
+    /// <param name="nodes">The nodes of the graph.</param>
+    /// <param name="edges">The edges that are present between the given <paramref name="nodes"/>.</param>
     public async Task LoadGraph(List<TNode> nodes, List<TEdge> edges)
     {
         if (SVGEditor.BBox is not null)
@@ -139,7 +177,11 @@ public async Task LoadGraph(List<TNode> nodes, List<TEdge> edges)
         nodeElements = SVGEditor.Elements.Where(e => e is Node<TNode, TEdge>).Select(e => (Node<TNode, TEdge>)e).ToArray();
     }
 
-
+    /// <summary>
+    /// Updates the nodes and edges that are in the graph without clearing the existing ones.
+    /// </summary>
+    /// <param name="nodes">The nodes of the graph.</param>
+    /// <param name="edges">The edges that are present between the given <paramref name="nodes"/>.</param>
     public async Task UpdateGraph(List<TNode> nodes, List<TEdge> edges)
     {
         Dictionary<TNode, Node<TNode, TEdge>> newNodeElementDictionary = [];
@@ -151,11 +193,10 @@ public async Task UpdateGraph(List<TNode> nodes, List<TEdge> edges)
         foreach (TNode node in nodes)
         {
             string nodeKey = NodeIdMapper(node);
-            if (!Nodes.ContainsKey(nodeKey))
+            if (Nodes.TryAdd(nodeKey, node))
             {
                 Node<TNode, TEdge> element = Node<TNode, TEdge>.CreateNew(SVGEditor, this, node);
                 newNodeElementDictionary.Add(node, element);
-                Nodes.Add(nodeKey, node);
             }
             newSetOfNodes.Add(nodeKey);
         }
@@ -164,14 +205,13 @@ public async Task UpdateGraph(List<TNode> nodes, List<TEdge> edges)
         foreach (TEdge edge in edges)
         {
             string edgeKey = EdgeId(edge);
-            if (!Edges.ContainsKey(edgeKey))
+            if (Edges.TryAdd(edgeKey, edge))
             {
                 TNode from = EdgeFromMapper(edge);
                 TNode to = EdgeToMapper(edge);
                 Node<TNode, TEdge> fromElement = newNodeElementDictionary.TryGetValue(from, out var eFrom) ? eFrom : nodeElements.First(n => n.Data.Equals(from));
                 Node<TNode, TEdge> toElement = newNodeElementDictionary.TryGetValue(to, out var eTo) ? eTo : nodeElements.First(n => n.Data.Equals(to));
                 Edge<TNode, TEdge>.AddNew(SVGEditor, this, edge, fromElement, toElement);
-                Edges.Add(edgeKey, edge);
             }
             newSetOfEdges.Add(edgeKey);
         }
@@ -211,15 +251,18 @@ public async Task UpdateGraph(List<TNode> nodes, List<TEdge> edges)
                 double newY = 0;
                 foreach (var neighborEdge in newNodeElement.Edges)
                 {
-                    var neighborMirroredPosition = MirroredAverageOfNeighborNodes(neighborEdge, newNodeElement);
-                    newX += neighborMirroredPosition.x / newNodeElement.Edges.Count();
-                    newY += neighborMirroredPosition.y / newNodeElement.Edges.Count();
+                    var (x, y) = MirroredAverageOfNeighborNodes(neighborEdge, newNodeElement);
+                    newX += x / newNodeElement.Edges.Count;
+                    newY += y / newNodeElement.Edges.Count;
                 }
                 newNodeElement.Cx = newX;
                 newNodeElement.Cy = newY;
             }
             SVGEditor.AddElement(newNodeElement);
         }
+
+        await Task.Yield();
+        StateHasChanged();
         nodeElements = SVGEditor.Elements.Where(e => e is Node<TNode, TEdge>).Select(e => (Node<TNode, TEdge>)e).ToArray();
 
         foreach (Edge<TNode, TEdge> edge in SVGEditor.Elements.Where(e => e is Edge<TNode, TEdge>).Cast<Edge<TNode, TEdge>>())
@@ -259,18 +302,21 @@ public async Task UpdateGraph(List<TNode> nodes, List<TEdge> edges)
                 y: averageYPositionOfNeighborsNeighbors - neighborNode.Cy
             );
             var distanceBetweenAverageNeighborsNeighborsAndNeighbor = Math.Sqrt(Math.Pow(differenceBetweenAverageNeighborsNeighborsAndNeighbor.x, 2) + Math.Pow(differenceBetweenAverageNeighborsNeighborsAndNeighbor.y, 2));
-            var normalizedVectorBetweenAverageNeighborsNeighborsAndNeighbor = (
-                x: differenceBetweenAverageNeighborsNeighborsAndNeighbor.x / distanceBetweenAverageNeighborsNeighborsAndNeighbor,
-                y: differenceBetweenAverageNeighborsNeighborsAndNeighbor.y / distanceBetweenAverageNeighborsNeighborsAndNeighbor
+            var (x, y) = (
+                differenceBetweenAverageNeighborsNeighborsAndNeighbor.x / distanceBetweenAverageNeighborsNeighborsAndNeighbor,
+                differenceBetweenAverageNeighborsNeighborsAndNeighbor.y / distanceBetweenAverageNeighborsNeighborsAndNeighbor
             );
 
             return (
-                x: neighborNode.Cx - normalizedVectorBetweenAverageNeighborsNeighborsAndNeighbor.x * edgeLength,
-                y: neighborNode.Cy - normalizedVectorBetweenAverageNeighborsNeighborsAndNeighbor.y * edgeLength
+                x: neighborNode.Cx - x * edgeLength,
+                y: neighborNode.Cy - y * edgeLength
             );
         }
     }
 
+    /// <summary>
+    /// Updates the layout of the nodes so that they repulse each other while staying close to the ones that they are connected to via edges.
+    /// </summary>
     public Task ForceDirectedLayout()
     {
         Span<Node<TNode, TEdge>> nodes = nodeElements.AsSpan();
@@ -329,18 +375,24 @@ public Task ForceDirectedLayout()
         return Task.CompletedTask;
     }
 
+    /// <summary>
+    /// Move all edges to the back so that they are hidden if any nodes are displayed in the same position.
+    /// </summary>
     public void MoveEdgesToBack()
     {
         var prevSelectedShapes = SVGEditor.SelectedShapes.ToList();
         SVGEditor.ClearSelectedShapes();
-        foreach (Shape shape in SVGEditor.Elements.Where(e => e is Edge<TNode, TEdge>))
+        foreach (Shape shape in SVGEditor.Elements.Where(e => e is Edge<TNode, TEdge>).Cast<Shape>())
         {
             SVGEditor.SelectShape(shape);
         }
         SVGEditor.MoveToBack();
         SVGEditor.SelectedShapes = prevSelectedShapes;
     }
 
+    /// <summary>
+    /// The elements that can be rendered in this graph. This normally doesn't need adjustments as the graph defaults to having support for the nodes and edges it shows.
+    /// </summary>
     protected List<SupportedElement> SupportedElements { get; set; } =
     [
         new(typeof(Node<TNode, TEdge>), element => element.TagName is "CIRCLE" && element.GetAttribute("data-elementtype") == "node"),

src/KristofferStrube.Blazor.GraphEditor/GraphEditorCallbackContext.cs

@@ -1,6 +1,12 @@
 namespace KristofferStrube.Blazor.GraphEditor;
 
+/// <summary>
+/// The context that specifies any functions that needs to be triggered for specific events in the graph..
+/// </summary>
 public class GraphEditorCallbackContext
 {
+    /// <summary>
+    /// The function that will be invoked when a node is selected by getting focus.
+    /// </summary>
     public required Func<string, Task> NodeSelectionCallback { get; set; }
 }

src/KristofferStrube.Blazor.GraphEditor/KristofferStrube.Blazor.GraphEditor.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk.Razor">
 
   <PropertyGroup>
-    <TargetFramework>net7.0</TargetFramework>
+    <TargetFrameworks>net7.0;net8.0</TargetFrameworks>
     <ImplicitUsings>true</ImplicitUsings>
     <EnforceCodeStyleInBuild>True</EnforceCodeStyleInBuild>
     <LangVersion>preview</LangVersion>
@@ -17,6 +17,7 @@
     <Authors>Kristoffer Strube</Authors>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageIcon>icon.png</PackageIcon>
+    <GenerateDocumentationFile>True</GenerateDocumentationFile>
   </PropertyGroup>
 
   <ItemGroup>
@@ -36,7 +37,14 @@
 
   <ItemGroup>
     <PackageReference Include="KristofferStrube.Blazor.SVGEditor" Version="0.3.0" />
-    <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="7.0.8" />
+  </ItemGroup>
+
+  <ItemGroup Condition="'$(TargetFramework)' == 'net7.0'">
+    <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="7.0.20" />
+  </ItemGroup>
+
+  <ItemGroup Condition="'$(TargetFramework)' == 'net8.0'">
+    <PackageReference Include="Microsoft.AspNetCore.Components.Web" Version="8.0.10" />
   </ItemGroup>
 
 </Project>