Add groupOrder option

Resolves #2251

CHANGELOG.md

@@ -5,6 +5,7 @@
 -   Added support for discovering a "module" comment on global files, #2165.
 -   Added copy code to clipboard button, #2153.
 -   Function `@returns` blocks will now be rendered with the return type, #2180.
+-   Added `--groupOrder` option to specify the sort order of groups, #2251.
 
 ### Bug Fixes
 

src/lib/converter/plugins/GroupPlugin.ts

@@ -24,15 +24,21 @@ export class GroupPlugin extends ConverterComponent {
     @BindOption("searchGroupBoosts")
     boosts!: Record<string, number>;
 
+    @BindOption("groupOrder")
+    groupOrder!: string[];
+
     usedBoosts = new Set<string>();
 
+    static WEIGHTS: string[] = [];
+
     /**
      * Create a new GroupPlugin instance.
      */
     override initialize() {
         this.listenTo(this.owner, {
             [Converter.EVENT_RESOLVE_BEGIN]: () => {
                 this.sortFunction = getSortFunction(this.application.options);
+                GroupPlugin.WEIGHTS = this.groupOrder;
             },
             [Converter.EVENT_RESOLVE]: this.onResolve,
             [Converter.EVENT_RESOLVE_END]: this.onEndResolve,
@@ -162,6 +168,30 @@ export class GroupPlugin extends ConverterComponent {
             }
         });
 
-        return Array.from(groups.values());
+        return Array.from(groups.values()).sort(GroupPlugin.sortGroupCallback);
+    }
+
+    /**
+     * Callback used to sort groups by name.
+     */
+    static sortGroupCallback(a: ReflectionGroup, b: ReflectionGroup): number {
+        let aWeight = GroupPlugin.WEIGHTS.indexOf(a.title);
+        let bWeight = GroupPlugin.WEIGHTS.indexOf(b.title);
+        if (aWeight === -1 || bWeight === -1) {
+            let asteriskIndex = GroupPlugin.WEIGHTS.indexOf("*");
+            if (asteriskIndex === -1) {
+                asteriskIndex = GroupPlugin.WEIGHTS.length;
+            }
+            if (aWeight === -1) {
+                aWeight = asteriskIndex;
+            }
+            if (bWeight === -1) {
+                bWeight = asteriskIndex;
+            }
+        }
+        if (aWeight === bWeight) {
+            return a.title > b.title ? 1 : -1;
+        }
+        return aWeight - bWeight;
     }
 }

src/lib/utils/options/declaration.ts

@@ -164,6 +164,7 @@ export interface TypeDocOptionMap {
     categorizeByGroup: boolean;
     defaultCategory: string;
     categoryOrder: string[];
+    groupOrder: string[];
     sort: SortStrategy[];
     kindSortOrder: ReflectionKind.KindString[];
 

src/lib/utils/options/sources/typedoc.ts

@@ -522,6 +522,32 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         help: "Specify the order in which categories appear. * indicates the relative order for categories not in the list.",
         type: ParameterType.Array,
     });
+    options.addDeclaration({
+        name: "groupOrder",
+        help: "Specify the order in which groups appear. * indicates the relative order for groups not in the list.",
+        type: ParameterType.Array,
+        // Defaults to the same as the defaultKindSortOrder in sort.ts
+        defaultValue: [
+            ReflectionKind.Reference,
+            // project is never a child so never added to a group
+            ReflectionKind.Module,
+            ReflectionKind.Namespace,
+            ReflectionKind.Enum,
+            ReflectionKind.EnumMember,
+            ReflectionKind.Class,
+            ReflectionKind.Interface,
+            ReflectionKind.TypeAlias,
+
+            ReflectionKind.Constructor,
+            ReflectionKind.Property,
+            ReflectionKind.Variable,
+            ReflectionKind.Function,
+            ReflectionKind.Accessor,
+            ReflectionKind.Method,
+
+            // others are never added to groups
+        ].map(ReflectionKind.pluralString),
+    });
     options.addDeclaration({
         name: "sort",
         help: "Specify the sort strategy for documented values.",

src/test/behavior.c2.test.ts

@@ -412,15 +412,16 @@ describe("Behavior Tests", () => {
         const A = query(project, "A");
         const B = query(project, "B");
         const C = query(project, "C");
+        const D = query(project, "D");
 
         equal(
             project.groups?.map((g) => g.title),
-            ["A", "B", "With Spaces"]
+            ["Variables", "A", "B", "With Spaces"]
         );
 
         equal(
             project.groups.map((g) => g.children),
-            [[A, B], [B], [C]]
+            [[D], [A, B], [B], [C]]
         );
     });
 
@@ -909,4 +910,13 @@ describe("Behavior Tests", () => {
 
         equal(comments, ["Bar docs", "Bar.a docs", "Foo.b docs"]);
     });
+
+    it("Allows specifying group sort order #2251", () => {
+        app.options.setValue("groupOrder", ["B", "Variables", "A"]);
+        const project = convert("groupTag");
+        equal(
+            project.groups?.map((g) => g.title),
+            ["B", "Variables", "A", "With Spaces"]
+        );
+    });
 });

src/test/converter2/behavior/groupTag.ts

@@ -13,3 +13,6 @@ export const B = 123;
  * @group With Spaces
  */
 export const C = 123;
+
+// no group
+export const D = 123;