refactor ProseSection into ProseSection and InertSection, to fix #215

tayloraswift · May 11, 2024 · 45b89fa · 45b89fa
1 parent bce4688
commit 45b89fa
Show file tree

Hide file tree

Showing 20 changed files with 235 additions and 142 deletions.
diff --git a/Sources/UnidocRender/Unidoc.VertexContext.swift b/Sources/UnidocRender/Unidoc.VertexContext.swift
@@ -18,6 +18,7 @@ extension Unidoc
 
         var canonical:CanonicalVersion? { get }
         var tooltips:Tooltips? { get }
+        var vertices:Table { get }
 
         /// Returns the metadata document for the principal volume of the associated page.
         var volume:VolumeMetadata { get }
@@ -28,16 +29,12 @@ extension Unidoc
 
         /// Returns the metadata document for the specified volume, if available.
         subscript(volume:Edition) -> VolumeMetadata? { get }
-        /// Returns the vertex document for the specified vertex, if available.
-        subscript(vertex:Scalar) -> AnyVertex? { get }
 
         /// Returns the vertex document for the specified vertex and its URL, if available.
         subscript(vertex id:Scalar) -> LinkReference<AnyVertex>? { get }
 
         subscript(culture id:Scalar) -> LinkReference<CultureVertex>? { get }
         subscript(article id:Scalar) -> LinkReference<ArticleVertex>? { get }
         subscript(decl id:Scalar) -> LinkReference<DeclVertex>? { get }
-
-        subscript(file id:Scalar) -> FileVertex? { get }
     }
 }
diff --git a/Sources/UnidocUI/Cones/Unidoc.Cone.swift b/Sources/UnidocUI/Cones/Unidoc.Cone.swift
@@ -85,19 +85,27 @@ extension Unidoc.Cone
 {
     var context:Unidoc.RelativePageContext { self.halo.context }
 
-    var overview:Markdown.ProseSection?
+    var overviewText:Unidoc.InertSection<Unidoc.IdentifiableVertices>?
     {
         self.writings.overview.map
         {
-            .init(self.context, bytecode: $0, outlines: self.outlines)
+            .init(bytecode: $0, outlines: self.outlines, vertices: self.context.vertices)
         }
     }
 
-    var details:Markdown.ProseSection?
+    var overview:Unidoc.ProseSection?
+    {
+        self.writings.overview.map
+        {
+            .init(bytecode: $0, outlines: self.outlines, context: self.context)
+        }
+    }
+
+    var details:Unidoc.ProseSection?
     {
         self.writings.details.map
         {
-            .init(self.context, bytecode: $0, outlines: self.outlines)
+            .init(bytecode: $0, outlines: self.outlines, context: self.context)
         }
     }
 }
diff --git a/Sources/UnidocUI/Endpoints/Blog/Unidoc.BlogEndpoint.ArticlePage.swift b/Sources/UnidocUI/Endpoints/Blog/Unidoc.BlogEndpoint.ArticlePage.swift
@@ -29,7 +29,7 @@ extension Unidoc.BlogEndpoint.ArticlePage:Unidoc.RenderablePage
 {
     var title:String { "\(self.apex.headline.safe)" }
 
-    var description:String? { self.cone.overview?.description }
+    var description:String? { self.cone.overviewText?.description }
 }
 extension Unidoc.BlogEndpoint.ArticlePage:Unidoc.StaticPage
 {

diff --git a/Sources/UnidocUI/Endpoints/Docs/Unidoc.DocsEndpoint.DeclPage.swift b/Sources/UnidocUI/Endpoints/Docs/Unidoc.DocsEndpoint.DeclPage.swift
@@ -204,7 +204,7 @@ extension Unidoc.DocsEndpoint.DeclPage:Unidoc.ApicalPage
                 $0[.code]
                 {
                     $0.class = width > 80 ? "multiline" : nil
-                } = Markdown.CodeSection.init(self.context,
+                } = Unidoc.CodeSection.init(self.context,
                     bytecode: self.apex.signature.expanded.bytecode,
                     scalars: self.apex.signature.expanded.scalars)
             }

diff --git a/Sources/UnidocUI/Endpoints/Docs/Unidoc.DocsEndpoint.ProductPage.swift b/Sources/UnidocUI/Endpoints/Docs/Unidoc.DocsEndpoint.ProductPage.swift
@@ -68,7 +68,7 @@ extension Unidoc.DocsEndpoint.ProductPage:Unidoc.ApicalPage
         for id:Unidoc.Scalar in self.apex.constituents
         {
             guard
-            case .culture(let vertex)? = self.context[id],
+            let vertex:Unidoc.CultureVertex = self.context.vertices[id]?.vertex.culture,
                 vertex.module.name == self.apex.symbol
             else
             {
@@ -140,7 +140,7 @@ extension Unidoc.DocsEndpoint.ProductPage:Unidoc.ApicalPage
                     {
                         guard
                         let volume:Unidoc.VolumeMetadata = self.context[id.edition],
-                        let vertex:Unidoc.AnyVertex = self.context[id]
+                        let vertex:Unidoc.AnyVertex = self.context.vertices[id]?.vertex
                         else
                         {
                             continue

diff --git a/Sources/UnidocUI/Endpoints/Unidoc.ExportEndpoint.swift b/Sources/UnidocUI/Endpoints/Unidoc.ExportEndpoint.swift
@@ -68,13 +68,13 @@ extension Unidoc.ExportEndpoint:Unidoc.VertexEndpoint, HTTP.ServerEndpoint
         }
 
         let outlines:[Unidoc.Outline] = article.outlinesConcatenated
-        let overview:Markdown.ProseSection? = article.overview.map
+        let overview:Unidoc.ProseSection? = article.overview.map
         {
-            .init(context, bytecode: $0.markdown, outlines: outlines)
+            .init(bytecode: $0.markdown, outlines: outlines, context: context)
         }
-        let details:Markdown.ProseSection? = article.details.map
+        let details:Unidoc.ProseSection? = article.details.map
         {
-            .init(context, bytecode: $0.markdown, outlines: outlines)
+            .init(bytecode: $0.markdown, outlines: outlines, context: context)
         }
 
         let html:HTML = .init

diff --git a/Sources/UnidocUI/Page contexts/Unidoc.IdentifiablePageContext.Tooltips.swift b/Sources/UnidocUI/Page contexts/Unidoc.IdentifiablePageContext.Tooltips.swift
@@ -49,15 +49,21 @@ extension Unidoc.IdentifiablePageContext.Tooltips:HTML.OutputStreamable
                 {
                     $0[.pre, .code] = Unidoc.ImportSection.init(module: vertex.module.id)
 
-                    $0 ?= vertex.overview?.markdown.safe
+                    $0 ?= vertex.overview.map
+                    {
+                        Unidoc.InertSection<Table>.init(overview: $0, vertices: self.vertices)
+                    }
                 }
 
             case .decl(let vertex):
                 div[.a, { $0.href = uri }]
                 {
                     $0[.pre, .code] = vertex.signature.expanded.bytecode.safe
 
-                    $0 ?= vertex.overview?.markdown.safe
+                    $0 ?= vertex.overview.map
+                    {
+                        Unidoc.InertSection<Table>.init(overview: $0, vertices: self.vertices)
+                    }
                 }
 
             default:

diff --git a/Sources/UnidocUI/Page contexts/Unidoc.IdentifiablePageContext.swift b/Sources/UnidocUI/Page contexts/Unidoc.IdentifiablePageContext.swift
@@ -113,6 +113,9 @@ extension Unidoc.IdentifiablePageContext:Unidoc.VertexContext
     public final
     var tooltips:Tooltips? { self.cache.tooltips }
 
+    public final
+    var vertices:Table { self.cache.vertices }
+
     public final
     var volume:Unidoc.VolumeMetadata { self.cache.volumes.principal }
 
@@ -125,27 +128,18 @@ extension Unidoc.IdentifiablePageContext:Unidoc.VertexContext
         self.packages.metadata[id]
     }
 
-    public final
-    subscript(secondary volume:Unidoc.Edition) -> Unidoc.VolumeMetadata?
-    {
-        self.cache.volumes.secondary[volume]
-    }
     public final
     subscript(volume:Unidoc.Edition) -> Unidoc.VolumeMetadata?
     {
         self.cache.volumes[volume]
     }
-
-    public final
-    subscript(vertex:Unidoc.Scalar) -> Unidoc.AnyVertex?
-    {
-        self.cache.vertices[vertex]?.vertex
-    }
-
+}
+extension Unidoc.IdentifiablePageContext
+{
     public final
-    subscript(file id:Unidoc.Scalar) -> Unidoc.FileVertex?
+    subscript(secondary volume:Unidoc.Edition) -> Unidoc.VolumeMetadata?
     {
-        self.cache.vertices[id]?.vertex.file
+        self.cache.volumes.secondary[volume]
     }
 }
 extension Unidoc.IdentifiablePageContext

diff --git a/Sources/UnidocUI/Page contexts/Unidoc.VertexContext (ext).swift b/Sources/UnidocUI/Page contexts/Unidoc.VertexContext (ext).swift
@@ -67,7 +67,7 @@ extension Unidoc.VertexContext
     {
         guard
         let refname:String = self[file.edition]?.refname,
-        let vertex:Unidoc.FileVertex = self[file: file],
+        let vertex:Unidoc.FileVertex = self.vertices[file]?.vertex.file,
         let origin:Unidoc.PackageOrigin = self.repo?.origin
         else
         {

diff --git a/Sources/UnidocUI/Page types/Unidoc.ApicalPage.swift b/Sources/UnidocUI/Page types/Unidoc.ApicalPage.swift
@@ -18,7 +18,10 @@ extension Unidoc.ApicalPage
     var descriptionFallback:String { "No overview available" }
 
     /// This needs to be optional, to prevent the default implementation from being used.
-    var description:String? { self.cone.overview?.description ?? self.descriptionFallback }
+    var description:String?
+    {
+        self.cone.overviewText?.description ?? self.descriptionFallback
+    }
 }
 extension Unidoc.ApicalPage
     where Context == Unidoc.RelativePageContext

diff --git a/Sources/UnidocUI/Primitives/Previews/Unidoc.ArticleCard.swift b/Sources/UnidocUI/Primitives/Previews/Unidoc.ArticleCard.swift
@@ -3,7 +3,7 @@ import UnidocRecords
 
 extension Unidoc
 {
-    struct ArticleCard
+    struct ArticleCard:PreviewCard
     {
         let context:any VertexContext
 
@@ -18,10 +18,6 @@ extension Unidoc
         }
     }
 }
-extension Unidoc.ArticleCard:Unidoc.PreviewCard
-{
-    var passage:Unidoc.Passage? { self.vertex.overview }
-}
 extension Unidoc.ArticleCard:HTML.OutputStreamable
 {
     static

diff --git a/Sources/UnidocUI/Primitives/Previews/Unidoc.CultureCard.swift b/Sources/UnidocUI/Primitives/Previews/Unidoc.CultureCard.swift
@@ -3,7 +3,7 @@ import UnidocRecords
 
 extension Unidoc
 {
-    struct CultureCard
+    struct CultureCard:PreviewCard
     {
         let context:any VertexContext
 
@@ -18,10 +18,6 @@ extension Unidoc
         }
     }
 }
-extension Unidoc.CultureCard:Unidoc.PreviewCard
-{
-    var passage:Unidoc.Passage? { self.vertex.overview }
-}
 extension Unidoc.CultureCard:HTML.OutputStreamable
 {
     static

diff --git a/Sources/UnidocUI/Primitives/Previews/Unidoc.DeclCard.swift b/Sources/UnidocUI/Primitives/Previews/Unidoc.DeclCard.swift
@@ -3,7 +3,7 @@ import UnidocRecords
 
 extension Unidoc
 {
-    struct DeclCard
+    struct DeclCard:PreviewCard
     {
         let context:any VertexContext
 
@@ -18,10 +18,6 @@ extension Unidoc
         }
     }
 }
-extension Unidoc.DeclCard:Unidoc.PreviewCard
-{
-    var passage:Unidoc.Passage? { self.vertex.overview }
-}
 extension Unidoc.DeclCard:HTML.OutputStreamableAnchor
 {
     var id:String { "\(self.vertex.symbol)" }

diff --git a/Sources/UnidocUI/Primitives/Previews/Unidoc.PreviewCard.swift b/Sources/UnidocUI/Primitives/Previews/Unidoc.PreviewCard.swift
@@ -3,16 +3,18 @@ import MarkdownABI
 
 extension Unidoc
 {
-    protocol PreviewCard:HTML.OutputStreamable
+    protocol PreviewCard<Vertex>:HTML.OutputStreamable
     {
+        associatedtype Vertex:PrincipalVertex
+
         var context:any VertexContext { get }
-        var passage:Passage? { get }
+        var vertex:Vertex { get }
     }
 }
 extension Unidoc.PreviewCard
 {
-    var overview:Markdown.ProseSection?
+    var overview:Unidoc.ProseSection?
     {
-        self.passage.map { .init(self.context, overview: $0) }
+        self.vertex.overview.map { .init(overview: $0, context: self.context) }
     }
 }
diff --git a/Sources/UnidocUI/Primitives/Previews/Unidoc.ProductCard.swift b/Sources/UnidocUI/Primitives/Previews/Unidoc.ProductCard.swift
@@ -3,7 +3,7 @@ import UnidocRecords
 
 extension Unidoc
 {
-    struct ProductCard
+    struct ProductCard:PreviewCard
     {
         let context:any VertexContext
 
@@ -20,10 +20,6 @@ extension Unidoc
         }
     }
 }
-extension Unidoc.ProductCard:Unidoc.PreviewCard
-{
-    var passage:Unidoc.Passage? { nil }
-}
 extension Unidoc.ProductCard:HTML.OutputStreamable
 {
     static

diff --git a/Sources/UnidocUI/Primitives/Sections/Unidoc._LegacyTopic.swift b/Sources/UnidocUI/Primitives/Sections/Unidoc._LegacyTopic.swift
@@ -32,7 +32,10 @@ extension Unidoc._LegacyTopic:HTML.OutputStreamable
     static
     func += (section:inout HTML.ContentEncoder, self:Self)
     {
-        section ?= self.caption.map { Markdown.ProseSection.init(self.context, overview: $0) }
+        section ?= self.caption.map
+        {
+            Unidoc.ProseSection.init(overview: $0, context: self.context)
+        }
 
         section[.ul, { $0.class = "cards" }]
         {

diff --git a/Sources/UnidocUI/SymbolGraph.OutlineText (ext).swift b/Sources/UnidocUI/SymbolGraph.OutlineText (ext).swift
@@ -0,0 +1,15 @@
+import HTML
+import SymbolGraphs
+
+extension SymbolGraph.OutlineText:HTML.OutputStreamable
+{
+    /// Writes the ``path`` components only to the output HTML, using `.` as the path separator.
+    @inlinable public static
+    func += (code:inout HTML.ContentEncoder, self:Self)
+    {
+        for byte:UInt8 in self.path.utf8
+        {
+            code.append(unescaped: byte == 0x20 ? 0x2E : byte)
+        }
+    }
+}
diff --git a/Sources/UnidocUI/Markdown.CodeSection.swift → Sources/UnidocUI/Unidoc.CodeSection.swift b/Sources/UnidocUI/Markdown.CodeSection.swift → Sources/UnidocUI/Unidoc.CodeSection.swift
@@ -3,17 +3,17 @@ import MarkdownABI
 import MarkdownRendering
 import UnidocRecords
 
-extension Markdown
+extension Unidoc
 {
     struct CodeSection
     {
         let bytecode:Markdown.Bytecode
         private
         let scalars:[Unidoc.Scalar?]
         private
-        let context:any Unidoc.VertexContext
+        let context:any VertexContext
 
-        init(_ context:any Unidoc.VertexContext,
+        init(_ context:any VertexContext,
             bytecode:Markdown.Bytecode,
             scalars:[Unidoc.Scalar?])
         {
@@ -23,7 +23,7 @@ extension Markdown
         }
     }
 }
-extension Markdown.CodeSection:HTML.OutputStreamableMarkdown
+extension Unidoc.CodeSection:HTML.OutputStreamableMarkdown
 {
     func load(_ reference:Int, for attribute:inout Markdown.Bytecode.Attribute) -> String?
     {