fix: reach non-children nodes in tree traversal (#411)

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/iamgio/quarkdown/pull/411" target="_blank">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://static.devin.ai/assets/gh-open-in-devin-review-dark.svg?v=1">
    <img src="https://static.devin.ai/assets/gh-open-in-devin-review-light.svg?v=1" alt="Open with Devin">
  </picture>
</a>
<!-- devin-review-badge-end -->

Author: iamgio

CHANGELOG.md

@@ -135,10 +135,14 @@ Thanks @szy1840!
 
 When editing long paged documents with live preview, the scroll position could sometimes be restored only partially because of long paged.js load times. The swap now reliably waits for the content to be fully loaded.
 
-#### Fixed Mermaid diagrams breaking page breaks
+#### Fixed Mermaid diagrams preventing page breaks
 
 Fixed an issue that caused Mermaid diagrams in `paged` documents to cause subsequent content to overflow instead of being pushed to the next page.
 
+#### Fixed tree traversal not reaching non-body nodes
+
+Fixed an issue that caused tree traversal-dependent features, such as cross-references, to not work in titles of `.box` and `.collapse`, and in block quote attributions.
+
 #### Improved lexer performance
 
 The lexer has been optimized to reduce regex builds to a minimum, resulting in significantly improved performance for large documents.

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/base/block/BlockQuote.kt

@@ -5,19 +5,23 @@ import com.quarkdown.core.ast.NestableNode
 import com.quarkdown.core.ast.Node
 import com.quarkdown.core.rendering.representable.RenderRepresentable
 import com.quarkdown.core.rendering.representable.RenderRepresentableVisitor
+import com.quarkdown.core.util.node.group
 import com.quarkdown.core.visitor.node.NodeVisitor
 
 /**
  * A block quote.
  * @param type information type. If `null`, the quote does not have a particular type
  * @param attribution additional author or source of the quote
- * @param children content
+ * @param content body content of the quote
  */
 class BlockQuote(
     val type: Type? = null,
     val attribution: InlineContent? = null,
-    override val children: List<Node>,
+    val content: List<Node>,
 ) : NestableNode {
+    override val children: List<Node>
+        get() = content + attribution.group()
+
     override fun <T> accept(visitor: NodeVisitor<T>) = visitor.visit(this)
 
     /**

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/base/block/Table.kt

@@ -10,6 +10,7 @@ import com.quarkdown.core.ast.quarkdown.CaptionableNode
 import com.quarkdown.core.ast.quarkdown.reference.CrossReferenceableNode
 import com.quarkdown.core.rendering.representable.RenderRepresentable
 import com.quarkdown.core.rendering.representable.RenderRepresentableVisitor
+import com.quarkdown.core.util.node.group
 import com.quarkdown.core.visitor.node.NodeVisitor
 
 /**
@@ -31,16 +32,17 @@ class Table(
     override val kindLocalizationKey: String
         get() = LocalizedKindKeys.TABLE
 
-    // Exposing all the cell contents as this table's direct children
-    // allows visiting them during a tree traversal.
-    // If they were isolated, they would be unreachable.
+    /**
+     * Exposes all the cell contents and caption as this table's direct children
+     * allowing visiting them during a tree traversal. If they were isolated, they would be unreachable.
+     */
     override val children: List<Node>
         get() =
             columns
                 .asSequence()
                 .flatMap { it.cells + it.header }
                 .flatMap { it.text }
-                .toList()
+                .toList() + caption.group()
 
     /**
      * A column of a table.

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/quarkdown/CaptionableNode.kt

@@ -1,15 +1,26 @@
 package com.quarkdown.core.ast.quarkdown
 
 import com.quarkdown.core.ast.InlineContent
+import com.quarkdown.core.ast.NestableNode
 import com.quarkdown.core.ast.Node
+import com.quarkdown.core.util.node.group
 
 /**
  * A node that may have a caption, such as a [com.quarkdown.core.ast.base.block.Table] or a [com.quarkdown.core.ast.quarkdown.block.ImageFigure].
  * The caption is a sequence of inline nodes, which accepts further inline formatting (e.g. emphasis, links).
+ *
+ * Extends [NestableNode] so that the caption content is reachable by AST tree traversals.
  */
-interface CaptionableNode : Node {
+interface CaptionableNode : NestableNode {
     /**
      * The optional caption, as inline content. If `null`, this node has no caption.
      */
     val caption: InlineContent?
+
+    /**
+     * Caption nodes grouped into a single container, making them visible to tree traversals.
+     * Subclasses that define their own [children] must include this in their override.
+     */
+    override val children: List<Node>
+        get() = listOf(caption.group())
 }

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/quarkdown/block/Box.kt

@@ -11,6 +11,7 @@ import com.quarkdown.core.document.size.Size
 import com.quarkdown.core.misc.color.Color
 import com.quarkdown.core.rendering.representable.RenderRepresentable
 import com.quarkdown.core.rendering.representable.RenderRepresentableVisitor
+import com.quarkdown.core.util.node.group
 import com.quarkdown.core.util.takeLines
 import com.quarkdown.core.visitor.node.NodeVisitor
 
@@ -26,16 +27,19 @@ private const val ERROR_MAX_SOURCE_TEXT_LINES = 10
  * @param padding padding of the box. If `null`, the box uses the default value
  * @param backgroundColor background color of the box. If `null`, the box uses the default value
  * @param foregroundColor foreground color of the box. If `null`, the box uses the default value
- * @param children content of the box
+ * @param content body content of the box
  */
 class Box(
     val title: InlineContent?,
     val type: Type,
     val padding: Size? = null,
     val backgroundColor: Color? = null,
     val foregroundColor: Color? = null,
-    override val children: List<Node>,
+    val content: List<Node>,
 ) : NestableNode {
+    override val children: List<Node>
+        get() = content + title.group()
+
     override fun <T> accept(visitor: NodeVisitor<T>) = visitor.visit(this)
 
     /**
@@ -87,7 +91,7 @@ class Box(
                     text("Error" + if (title != null) ": $title" else "")
                 },
             type = Type.ERROR,
-            children = content,
+            content = content,
         )
 
         /**

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/quarkdown/block/Collapse.kt

@@ -3,17 +3,22 @@ package com.quarkdown.core.ast.quarkdown.block
 import com.quarkdown.core.ast.InlineContent
 import com.quarkdown.core.ast.NestableNode
 import com.quarkdown.core.ast.Node
+import com.quarkdown.core.util.node.group
 import com.quarkdown.core.visitor.node.NodeVisitor
 
 /**
  * A collapsible block, whose content can be hidden or shown by interacting with it.
  * @param title title of the block
  * @param isOpen whether the block is open at the beginning
+ * @param content body content of the block
  */
 class Collapse(
     val title: InlineContent,
     val isOpen: Boolean,
-    override val children: List<Node>,
+    val content: List<Node>,
 ) : NestableNode {
+    override val children: List<Node>
+        get() = content + title.group()
+
     override fun <T> accept(visitor: NodeVisitor<T>): T = visitor.visit(this)
 }

quarkdown-core/src/main/kotlin/com/quarkdown/core/ast/quarkdown/block/Figure.kt

@@ -9,6 +9,7 @@ import com.quarkdown.core.ast.attributes.location.LocationTrackableNode
 import com.quarkdown.core.ast.base.inline.Image
 import com.quarkdown.core.ast.quarkdown.CaptionableNode
 import com.quarkdown.core.ast.quarkdown.reference.CrossReferenceableNode
+import com.quarkdown.core.util.node.group
 import com.quarkdown.core.visitor.node.NodeVisitor
 
 /**
@@ -28,6 +29,9 @@ open class Figure<T : Node>(
     CrossReferenceableNode,
     CaptionableNode,
     LocalizedKind {
+    override val children: List<Node>
+        get() = listOf(child, caption.group())
+
     override val kindLocalizationKey: String
         get() = LocalizedKindKeys.FIGURE
 

quarkdown-core/src/main/kotlin/com/quarkdown/core/util/node/NodeUtils.kt

@@ -10,6 +10,12 @@ import com.quarkdown.core.ast.dsl.buildInline
 import com.quarkdown.core.ast.quarkdown.inline.TextSymbol
 import com.quarkdown.core.visitor.node.NodeVisitor
 
+/**
+ * Groups nodes into an [AstRoot] container.
+ * @return an empty [AstRoot] if `null`
+ */
+fun List<Node>?.group(): AstRoot = AstRoot(this.orEmpty())
+
 /**
  * Returns a sequence of all nodes in the tree, where [this] is the root node.
  * The sequence is generated by traversing the tree in depth-first order.

quarkdown-core/src/test/kotlin/com/quarkdown/core/AstDslTest.kt

@@ -89,7 +89,7 @@ class AstDslTest {
                         ),
                     ),
                     BlockQuote(
-                        children =
+                        content =
                             listOf(
                                 Paragraph(
                                     listOf(

quarkdown-core/src/test/kotlin/com/quarkdown/core/BlockParserTest.kt

@@ -399,10 +399,10 @@ class BlockParserTest {
         }
 
         with(nodes.next()) {
-            assertEquals(1, children.size)
-            children.first().let { inner ->
+            assertEquals(1, content.size)
+            content.first().let { inner ->
                 assertIs<BlockQuote>(inner)
-                assertEquals("You miss 100% of the shots you don’t take.", inner.children.toPlainText())
+                assertEquals("You miss 100% of the shots you don’t take.", inner.content.toPlainText())
                 assertNodeEquals(Text("Wayne Gretzky"), inner.attribution!!.single())
             }
             assertNodeEquals(Emphasis(listOf(Text("Michael Scott"))), attribution!!.single())