Add Table of Contents feature for improved navigation

BlazorOpenApi/Controls/ComponentsControl.razor

@@ -2,33 +2,39 @@
 {
     @if (Value.Schemas?.Count > 0)
     {
+        <TocMember Title="Schemas">
             <h3>Schemas</h3>
             @foreach (var (name, val) in Value.Schemas)
             {
                 <h4>@name</h4>
                 <SchemaControl Value="@val"/>
             }
+        </TocMember>
     }
 
     <ResponsesControl Value="@Value.Responses"/>
 
     @if (Value.Parameters?.Count > 0)
     {
+        <TocMember Title="Parameters">
         <h3>Parameters</h3>
         @foreach (var (name, val) in Value.Parameters)
         {
             <h4>@name</h4>
             <ParametersControl Value="@ToList(val)" />
         }
+        </TocMember>
     }
 
     @if (Value.Examples?.Count > 0)
     {
+        <TocMember Title="Examples">
             <h3>Examples</h3>
             @foreach (var (name, val) in Value.Examples)
             {
                 <ExampleControl Example="@val" Name="@name"/>
             }
+        </TocMember>
     }
 }
 

BlazorOpenApi/Controls/Expander.razor

@@ -1,5 +1,5 @@
-<CascadingValue Name="OpenAPIUI_ExpandoTree_Parent" Value="_anchor">
+<CascadingValue Name="OpenAPIUI_TOC_Parent" Value="_anchor">
-    <div class="expander @Class">
+    <div id="@_anchor" class="expander @Class">
         <div class="ex-header @HeaderClass">
             @Title
             <div onclick="@(() => Toggle())">
@@ -36,9 +36,11 @@
     public string HeaderClass           { get; set; } = "";
     [Parameter]
     public string Class                 { get; set; } = "";
+    [Parameter]
+    public bool AddToTOC                { get; set; } = false;
 
-    [CascadingParameter(Name = "OpenAPIUI_ExpandoTree")]        public IExpandoTree Tree   { get; set; } = null!;
+    [CascadingParameter(Name = "OpenAPIUI_TOC")]        public ITableOfContentsTree Tree   { get; set; } = null!;
-    [CascadingParameter(Name = "OpenAPIUI_ExpandoTree_Parent")] public string Parent { get; set; } = "";
+    [CascadingParameter(Name = "OpenAPIUI_TOC_Parent")] public string               Parent { get; set; } = "";
 
     private string _anchor = $"anc{Random.Shared.Next():X8}";
 
@@ -47,14 +49,19 @@
         if (!firstRender)
             return;
 
+        if (AddToTOC)
+        {
             Tree.Add(Title, _anchor, Parent, Collapsed);
             Collapsed = Tree.IsCollapsed(Title);
         }
+    }
 
     void Toggle()
     {
         Collapsed = !Collapsed;
+        if ( AddToTOC )
             Tree.Collapse(_anchor, Collapsed);
+
         StateHasChanged();
     }
 }

BlazorOpenApi/Controls/HeaderControl.razor

@@ -1,5 +1,7 @@
 @if (Value != null)
 {
+    <TocMember Title="Header">
+
         <div class="header">
             <h1 class="h-title">@Value.Title <span class="h-version">@Value.Version</span></h1>
             <div class="h-contact">
@@ -33,6 +35,8 @@
             <h2>Description</h2>
             <MarkdownControl Value="@Value.Description"/>
         }
+
+    </TocMember>
 }
 
 @code {

BlazorOpenApi/Controls/OperationControl.razor

@@ -1,6 +1,7 @@
-@if (Value != null)
+<TocMember Title="@TocTitle" Anchor="@_anchor">
+    @if (Value != null)
     {
-    <div class="op-header @OperationClass" @onclick="Expand">
+        <div id="@_anchor" class="op-header @OperationClass" @onclick="Expand">
             <div class="op-type">@Operation</div>
             <div class="spacer op-header-text">-</div>
             <div class="op-header-text" id="@Value.OperationId">@Endpoint</div>
@@ -17,7 +18,7 @@
                     }
                 </div>
             }
-        @if (_expanded)
+            @if (!Collapsed)
             {
                 <svg width="24px" height="24px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
                     <path d="M18 15L12 9L6 15" stroke="var(--oa-fg-lighter)" stroke-width="2" />
@@ -31,7 +32,7 @@
             }
 
         </div>
-    @if ( _expanded )
+        @if (!Collapsed)
         {
             <div class="operation">
 
@@ -64,6 +65,7 @@
             </div>
         }
     }
+</TocMember>
 
 @code {
     [Parameter]
@@ -73,13 +75,20 @@
     [Parameter]
     public string Endpoint { get; set; } = "";
 
+    [CascadingParameter(Name = "OpenAPIUI_TOC")] public ITableOfContentsTree Tree { get; set; } = null!;
+    [CascadingParameter(Name = "OpenAPIUI_TOC_Parent")] public string Parent { get; set; } = "";
+
+    private string _anchor = $"op_anc{Random.Shared.Next():X8}";
+    private string TocTitle => $"{Endpoint} - [{Operation.ToString().ToUpper()}] {Value?.Summary}";
+
     private string OperationClass => $"op-{Operation.ToString().ToLower()}";
 
-    private bool _expanded = true;
+    private bool Collapsed => Tree.IsCollapsed(_anchor);
 
     private void Expand()
     {
-        _expanded = !_expanded;
+        var collapsed = !Tree.IsCollapsed(_anchor);
+        Tree.Collapse(_anchor, collapsed);
         StateHasChanged();
     }
 

BlazorOpenApi/Controls/PathControl.razor

@@ -1,5 +1,6 @@
 @if (!string.IsNullOrWhiteSpace(Key) || Value != null)
 {
+    <TocMember Title="@Key">
         @if (!string.IsNullOrWhiteSpace(@Value?.Summary) || !string.IsNullOrWhiteSpace(Value?.Description))
         {
             <div class="pa-header">
@@ -30,6 +31,7 @@
                 }
             }
         </div>
+    </TocMember>
 }
 
 @code {

BlazorOpenApi/Controls/ServersControl.razor

@@ -1,5 +1,6 @@
 @if (Value != null && Value.Count > 0)
 {
+    <TocMember Title="Servers">
         <h2>Servers</h2>
         <table class="servers">
             @foreach (var server in Value)
@@ -57,6 +58,7 @@
                 }
             }
         </table>
+    </TocMember>
 }
 
 @code {

BlazorOpenApi/Controls/TableOfContents.razor

@@ -0,0 +1,48 @@
+@inject IJSRuntime _js;
+@implements IDisposable
+
+<div class="@Class">
+    <a @onclick="(async() => await ScrolltoAnchor())">@Title</a>
+    @foreach (var child in Tree.GetChildren(Anchor))
+    {
+        <TableOfContents Title="@child.Name" Anchor="@child.Anchor" class="toc-level" Tree="@Tree"/>
+    }
+</div>
+
+@code{
+    [Parameter] public string Class              { get; set; } = "toc-level";
+    [Parameter] public string Anchor             { get; set; } = "";
+    [Parameter] public string Title              { get; set; } = "";
+    [Parameter] public ITableOfContentsTree Tree { get; set; } = null!;
+
+    private string AdaptedTitle => string.IsNullOrWhiteSpace(Title) ? "Root" : Title;
+    private bool _initialized;
+
+    protected override void OnParametersSet()
+    {
+        base.OnParametersSet();
+        if (Tree != null && !_initialized)
+        {
+            Tree.Changed += OnTocChanged;
+            _initialized = true;
+        }
+    }
+
+    public void Dispose()
+    {
+        if (Tree != null)
+        {
+            Tree.Changed -= OnTocChanged;
+        }
+    }
+
+    private void OnTocChanged(object? sender, EventArgs e)
+    {
+        StateHasChanged();
+    }
+
+    private async Task ScrolltoAnchor()
+    {
+        await _js.InvokeVoidAsync("ScrollTo", Anchor);
+    }
+}

BlazorOpenApi/Controls/TocMember.razor

@@ -0,0 +1,45 @@
+@if (string.IsNullOrWhiteSpace(Anchor))
+{
+    <CascadingValue Name="OpenAPIUI_TOC_Parent" Value="@_anchor">
+        <div id="@_anchor">
+            @if (ChildContent != null)
+            {
+                @ChildContent
+            }
+        </div>
+    </CascadingValue>
+}
+else
+{
+    <CascadingValue Name="OpenAPIUI_TOC_Parent" Value="@Anchor">
+        <div>
+            @if (ChildContent != null)
+            {
+                @ChildContent
+            }
+        </div>
+    </CascadingValue>
+}
+
+
+@code{
+    [Parameter] public string Title     { get; set; } = "";
+    [Parameter] public string Anchor    { get; set; } = "";
+    [Parameter] public bool   Collapsed { get; set; }
+
+    [Parameter] public RenderFragment? ChildContent { get; set; }
+
+    [CascadingParameter(Name = "OpenAPIUI_TOC")]        public ITableOfContentsTree Tree   { get; set; } = null!;
+    [CascadingParameter(Name = "OpenAPIUI_TOC_Parent")] public string               Parent { get; set; } = "";
+
+    private string _anchor = $"anc{Random.Shared.Next():X8}";
+
+    protected override void OnAfterRender(bool firstRender)
+    {
+        if (!firstRender)
+            return;
+
+        Tree.Add(Title, string.IsNullOrWhiteSpace(Anchor) ? _anchor : Anchor, Parent, Collapsed);
+    }
+
+}

BlazorOpenApi/ITableOfContentsTree.cs

@@ -6,21 +6,25 @@ using System.Threading.Tasks;
 
 namespace BlazorOpenApi;
 
-public class ExpandoTreeNode
+public class TocTreeNode
 {
     public string Name { get; set; } = string.Empty;
     public string Anchor { get; set; } = string.Empty;
     public string ParentAnchor { get; set; } = string.Empty;
     public bool Collapsed { get; set; }
+
+    public override string ToString() => $"Name: {Name}, Anchor: {Anchor}, ParentAnchor: {ParentAnchor}, Collapsed: {Collapsed}";
 }
 
-public interface IExpandoTree
+public interface ITableOfContentsTree
 {
+    public event EventHandler Changed;
+
     void Add(string name, string anchor, string parentAnchor, bool collapsed);
     void Collapse(string anchor, bool collapsed);
     bool IsCollapsed(string anchor);
     bool Exists(string anchor);
-    ExpandoTreeNode[] GetChildren(string anchor);
+    TocTreeNode[] GetChildren(string anchor);
 }
 
 //implement IExpandoTree

BlazorOpenApi/OpenAPIUIControl.razor

@@ -2,6 +2,7 @@
 @using Microsoft.OpenApi.Models
 @using Microsoft.OpenApi.Readers
 
+<script src="_content/BlazorOpenApi/js/BlazorOpenAPI.js"></script>
 
 @if (Palette != null )
 {
@@ -10,29 +11,36 @@
 
 <div class="openapi-ui">
     <CascadingValue Value="@_api" IsFixed="true">
-        <CascadingValue Name="OpenAPIUI_ExpandoTree" Value="_tree" IsFixed="true">
+        <CascadingValue Name="OpenAPIUI_TOC" Value="@_tree" IsFixed="true">
+
+            <TableOfContents Tree="@_tree" />
 
             <HeaderControl Value="@_api.Info" DownloadUrl="@Url" />
             <ServersControl Value="@_api.Servers" />
             @if (_api.Paths?.Count > 0)
             {
+                <TocMember Title="Endpoints">
                     <h2>Endpoints</h2>
-                foreach (var path in _api.Paths)
+                    @foreach (var path in _api.Paths)
                     {
                         if (!string.IsNullOrWhiteSpace(path.Key) || path.Value != null)
                         {
                             <PathControl Key="@path.Key" Value="@path.Value" />
                         }
                     }
+                </TocMember>
             }
             @if (_api.Components != null)
             {
+                <TocMember Title="Components">
                     <h2>Components</h2>
                     <ComponentsControl Value="@_api.Components" />
+                </TocMember>
             }
 
         </CascadingValue>
     </CascadingValue>
+
 </div>
 
 @code {
@@ -44,10 +52,17 @@
     private string _loadedFor = "";
 
     private OpenApiDocument _api = new();
-    private IExpandoTree _tree = new ExpandoTree();
+    private ITableOfContentsTree _tree = new TableOfContentsTree();
 
     private MarkupString PaletteStr => Palette?.AsMarkupString ?? new();
 
+    protected override void OnAfterRender(bool firstRender)
+    {
+        if (!firstRender)
+            return;
+        StateHasChanged();
+    }
+
     protected override async Task OnParametersSetAsync()
     {
         var loadedFromUrl  = _loadedFor == Url && !string.IsNullOrWhiteSpace(Url);

BlazorOpenApi/TableOfContentsTree.cs

@@ -4,19 +4,26 @@ using System.Linq;
 
 namespace BlazorOpenApi;
 
-internal class ExpandoTree : IExpandoTree
+internal class TableOfContentsTree : ITableOfContentsTree
 {
-    private readonly Dictionary<string, ExpandoTreeNode> _nodes = new();
+    private readonly Dictionary<string, TocTreeNode> _nodes = new();
     private readonly List<string> _order = new();
 
+    public event EventHandler Changed;
+
     public void Add(string name, string anchor, string parentAnchor, bool collapsed)
     {
         if (_nodes.ContainsKey(anchor))
         {
-            throw new InvalidOperationException($"A node with anchor '{anchor}' already exists.");
+            throw new InvalidOperationException($"A node with anchor '{anchor}' already exists for {name}.");
         }
 
-        var node = new ExpandoTreeNode
+        if ( parentAnchor != "" && !_nodes.ContainsKey(parentAnchor))
+        {
+            throw new InvalidOperationException($"A parent anchor '{parentAnchor}' is not registered for {name}.");
+        }
+
+        var node = new TocTreeNode
         {
             Name         = name,
             Anchor       = anchor,
@@ -26,6 +33,11 @@ internal class ExpandoTree : IExpandoTree
 
         _nodes[anchor] = node;
         _order.Add(anchor);
+
+        if ( Changed != null )
+        {
+            Changed(this, EventArgs.Empty);
+        }
     }
 
     public void Collapse(string anchor, bool collapsed)
@@ -47,7 +59,7 @@ internal class ExpandoTree : IExpandoTree
 
     public bool Exists(string anchor) => _nodes.ContainsKey(anchor);
 
-    public ExpandoTreeNode[] GetChildren(string anchor) => _order
+    public TocTreeNode[] GetChildren(string anchor) => _order
             .Where(x => _nodes[x].ParentAnchor == anchor)
             .Select(x => _nodes[x])
             .ToArray();

BlazorOpenApi/wwwroot/css/openapi-ui.css

@@ -1,4 +1,9 @@
-.descriminator      {}
+.toc-level {
+    margin-left: 20px;
+}
+
+.descriminator {
+}
 
 .example            {}
 .e-item             {}

BlazorOpenApi/wwwroot/js/BlazorOpenAPI.js

@@ -0,0 +1,10 @@
+function ScrollTo(elementId) {
+    var element = document.getElementById(elementId);
+    if (element != null) {
+        element.scrollIntoView({
+            block: "start"
+//            behavior: 'smooth'
+        });
+        window.scrollBy(0, -64); // Adjust scrolling with a negative value here
+    }
+}

Demo/Shared/MainLayout.razor

@@ -20,13 +20,13 @@
             <MudSwitch @bind-Value="@IsDarkMode" Color="MudBlazor.Color.Primary" Class="ma-4" T="bool" Label="Dark Mode" />
         </div>
     </MudDrawer>
-    <MudMainContent>
     <CascadingValue Value="@IsDarkMode">
-            <MudContainer MaxWidth="MaxWidth.ExtraExtraLarge" Class="pt-2">
+        <MudMainContent>
+            <MudContainer MaxWidth="MaxWidth.ExtraExtraLarge">
                 @Body
             </MudContainer>
-        </CascadingValue>
         </MudMainContent>
+    </CascadingValue>
 </MudLayout>
 
 @code {