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

3 files changed, 18 insertions, 3 deletions

diff --git a/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt b/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt
index ecce70e8..4dae21c8 100644
--- a/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt
+++ b/plugins/base/src/main/kotlin/renderers/html/NavigationDataProvider.kt
@@ -6,6 +6,7 @@ import org.jetbrains.dokka.base.transformers.documentables.isDeprecated
 import org.jetbrains.dokka.base.transformers.documentables.isException
 import org.jetbrains.dokka.base.translators.documentables.DocumentableLanguage
 import org.jetbrains.dokka.base.translators.documentables.documentableLanguage
+import org.jetbrains.dokka.base.utils.canonicalAlphabeticalOrder
 import org.jetbrains.dokka.model.*
 import org.jetbrains.dokka.pages.*
 
@@ -90,6 +91,9 @@ abstract class NavigationDataProvider {
         }
     }
 
+    private val navigationNodeOrder: Comparator<NavigationNode> =
+        compareBy(canonicalAlphabeticalOrder) { it.name }
+
     private fun ContentPage.navigableChildren() =
         if (this is ClasslikePage) {
             this.navigableChildren()
@@ -97,7 +101,7 @@ abstract class NavigationDataProvider {
             children
                 .filterIsInstance<ContentPage>()
                 .map { visit(it) }
-                .sortedBy { it.name.toLowerCase() }
+                .sortedWith(navigationNodeOrder)
         }
 
     private fun ClasslikePage.navigableChildren(): List<NavigationNode> {
@@ -111,7 +115,7 @@ abstract class NavigationDataProvider {
             // no sorting for enum entries, should be the same order as in source code
             navigableChildren
         } else {
-            navigableChildren.sortedBy { it.name.toLowerCase() }
+            navigableChildren.sortedWith(navigationNodeOrder)
         }
     }
 }
diff --git a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
index 25f3c450..6006af5b 100644
--- a/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
+++ b/plugins/base/src/main/kotlin/translators/documentables/DefaultPageCreator.kt
@@ -9,6 +9,7 @@ import org.jetbrains.dokka.base.transformers.documentables.ClashingDriIdentifier
 import org.jetbrains.dokka.base.transformers.pages.comments.CommentsToContentConverter
 import org.jetbrains.dokka.base.transformers.pages.tags.CustomTagContentProvider
 import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder.DocumentableContentBuilder
+import org.jetbrains.dokka.base.utils.canonicalAlphabeticalOrder
 import org.jetbrains.dokka.links.Callable
 import org.jetbrains.dokka.links.DRI
 import org.jetbrains.dokka.model.*
@@ -508,6 +509,9 @@ open class DefaultPageCreator(
         }
     }
 
+    private val groupKeyComparator: Comparator<Map.Entry<String?, *>> =
+        compareBy(nullsFirst(canonicalAlphabeticalOrder)) { it.key }
+
     protected open fun DocumentableContentBuilder.divergentBlock(
         name: String,
         collection: Collection<Documentable>,
@@ -525,7 +529,7 @@ open class DefaultPageCreator(
                     .groupBy { it.name } // This groupBy should probably use LocationProvider
                     // This hacks displaying actual typealias signatures along classlike ones
                     .mapValues { if (it.value.any { it is DClasslike }) it.value.filter { it !is DTypeAlias } else it.value }
-                    .entries.sortedBy { it.key }
+                    .entries.sortedWith(groupKeyComparator)
                     .forEach { (elementName, elements) -> // This groupBy should probably use LocationProvider
                         val sortedElements = sortDivergentElementsDeterministically(elements)
                         row(
diff --git a/plugins/base/src/main/kotlin/utils/alphabeticalOrder.kt b/plugins/base/src/main/kotlin/utils/alphabeticalOrder.kt
new file mode 100644
index 00000000..68b9cde8
--- /dev/null
+++ b/plugins/base/src/main/kotlin/utils/alphabeticalOrder.kt
@@ -0,0 +1,7 @@
+package org.jetbrains.dokka.base.utils
+
+
+/**
+ * Canonical alphabetical order to sort named elements
+ */
+internal val canonicalAlphabeticalOrder: Comparator<in String> = String.CASE_INSENSITIVE_ORDER.thenBy { it }
\ No newline at end of file