Consistent alphabetical order of element groups in index and navigation (#2861)

* Sort groups of divergent elements by their key first ignoring case, then preserving it

* Add tests for sorting groups and navigation

2 files changed, 114 insertions, 0 deletions

diff --git a/plugins/base/src/test/kotlin/pageMerger/PageNodeMergerTest.kt b/plugins/base/src/test/kotlin/pageMerger/PageNodeMergerTest.kt
index 05ff55ee..01fefd3c 100644
--- a/plugins/base/src/test/kotlin/pageMerger/PageNodeMergerTest.kt
+++ b/plugins/base/src/test/kotlin/pageMerger/PageNodeMergerTest.kt
@@ -381,6 +381,46 @@ class PageNodeMergerTest : BaseAbstractTest() {
         }
     }
 
+    @Test
+    fun `should sort groups alphabetically ignoring case`() {
+        testInline(
+            """
+            |/src/main/kotlin/test/Test.kt
+            |package test
+            |
+            |/** Sequence builder */
+            |fun <T> sequence(): Sequence<T>
+            |
+            |/** Sequence SAM constructor */
+            |fun <T> Sequence(): Sequence<T>
+            |
+            |/** Sequence.any() */
+            |fun <T> Sequence<T>.any() {}
+            |
+            |/** Sequence interface */
+            |interface Sequence<T>
+        """.trimMargin(),
+            defaultConfiguration
+        ) {
+            renderingStage = { rootPageNode, _ ->
+                val packageFunctionBlocks = rootPageNode.findPackageFunctionBlocks(packageName = "test")
+                assertEquals(3, packageFunctionBlocks.size, "Expected 3 separate function groups")
+
+                packageFunctionBlocks[0].assertContainsKDocsInOrder(
+                    "Sequence.any()",
+                )
+
+                packageFunctionBlocks[1].assertContainsKDocsInOrder(
+                    "Sequence SAM constructor",
+                )
+
+                packageFunctionBlocks[2].assertContainsKDocsInOrder(
+                    "Sequence builder",
+                )
+            }
+        }
+    }
+
     private fun RootPageNode.findExtensionsOfClass(name: String): ContentDivergentGroup {
         val extensionReceiverPage = this.dfs { it is ClasslikePageNode && it.name == name } as ClasslikePageNode
         return extensionReceiverPage.content
diff --git a/plugins/base/src/test/kotlin/renderers/html/NavigationTest.kt b/plugins/base/src/test/kotlin/renderers/html/NavigationTest.kt
index 13a9e711..21b4ea3c 100644
--- a/plugins/base/src/test/kotlin/renderers/html/NavigationTest.kt
+++ b/plugins/base/src/test/kotlin/renderers/html/NavigationTest.kt
@@ -20,6 +20,80 @@ class NavigationTest : BaseAbstractTest() {
     }
 
     @Test
+    fun `should sort alphabetically ignoring case`() {
+        val writerPlugin = TestOutputWriterPlugin()
+        testInline(
+            """
+            |/src/main/kotlin/com/example/Sequences.kt
+            |package com.example
+            |
+            |fun <T> sequence(): Sequence<T>
+            |
+            |fun <T> Sequence(): Sequence<T>
+            |
+            |fun <T> Sequence<T>.any() {}
+            |
+            |interface Sequence<T>
+            """.trimMargin(),
+            configuration,
+            pluginOverrides = listOf(writerPlugin)
+        ) {
+            renderingStage = { _, _ ->
+                val content = writerPlugin.writer.navigationHtml().select("div.sideMenuPart")
+                assertEquals(6, content.size)
+
+                // Navigation menu should be the following:
+                // - root
+                //    - com.example
+                //       - any()
+                //       - Sequence interface
+                //       - Sequence()
+                //       - sequence()
+
+                content[0].assertNavigationLink(
+                    id = "root-nav-submenu",
+                    text = "root",
+                    address = "index.html",
+                )
+
+                content[1].assertNavigationLink(
+                    id = "root-nav-submenu-0",
+                    text = "com.example",
+                    address = "root/com.example/index.html",
+                )
+
+                content[2].assertNavigationLink(
+                    id = "root-nav-submenu-0-0",
+                    text = "any()",
+                    address = "root/com.example/any.html",
+                    icon = NavigationNodeIcon.FUNCTION
+                )
+
+                content[3].assertNavigationLink(
+                    id = "root-nav-submenu-0-1",
+                    text = "Sequence",
+                    address = "root/com.example/-sequence/index.html",
+                    icon = NavigationNodeIcon.INTERFACE_KT
+                )
+
+                content[4].assertNavigationLink(
+                    id = "root-nav-submenu-0-2",
+                    text = "Sequence()",
+                    address = "root/com.example/-sequence.html",
+                    icon = NavigationNodeIcon.FUNCTION
+                )
+
+                content[5].assertNavigationLink(
+                    id = "root-nav-submenu-0-3",
+                    text = "sequence()",
+                    address = "root/com.example/sequence.html",
+                    icon = NavigationNodeIcon.FUNCTION
+                )
+            }
+        }
+    }
+
+    @Test
     fun `should strike deprecated class link`() {
         val writerPlugin = TestOutputWriterPlugin()
         testInline(