feat(admin): add custom admin route ranking feature (medusajs#13946)

* ✨ Add custom admin routes ranking

* 🐛 Fix sorting

* 📝 Update admin ui-routes documentation

* ✅ Add admin menu items spec

* 🔧 Add changeset

* 🐛 Remove redundant undefined initializations

* 🔥 🔥 Move the documentation to a separate PR

* ♻️ Move sorting logic to utils

* 🔧 Update changeset

---------

Co-authored-by: Bastien MONTOIS <[email protected]>

Author: bqst

.changeset/metal-lamps-film.md

@@ -0,0 +1,7 @@
+---
+"@medusajs/admin-vite-plugin": patch
+"@medusajs/admin-sdk": patch
+"@medusajs/dashboard": patch
+---
+
+feat(dashboard): add custom admin route ranking feature

packages/admin/admin-sdk/src/config/types.ts

@@ -31,6 +31,12 @@ export interface RouteConfig {
    */
   nested?: NestedRoutePosition
 
+  /**
+   * The ranking of the route among sibling routes. Routes are sorted in ascending order (lower rank appears first).
+   * If not provided, the route will be ranked after all routes with explicit ranks.
+   */
+  rank?: number
+
   /**
    * An optional i18n namespace for translating the label. When provided, the label will be treated as a translation key.
    * @example

packages/admin/admin-vite-plugin/src/babel.ts

@@ -11,6 +11,7 @@ import {
   isJSXElement,
   isJSXFragment,
   isMemberExpression,
+  isNumericLiteral,
   isObjectExpression,
   isObjectProperty,
   isStringLiteral,
@@ -47,6 +48,7 @@ export {
   isJSXElement,
   isJSXFragment,
   isMemberExpression,
+  isNumericLiteral,
   isObjectExpression,
   isObjectProperty,
   isStringLiteral,

packages/admin/admin-vite-plugin/src/routes/__tests__/generate-menu-items.spec.ts

@@ -70,20 +70,23 @@ const expectedMenuItems = `
             icon: RouteConfig0.icon,
             path: "/one",
             nested: undefined,
+            rank: undefined,
             translationNs: undefined
           },
           {
             label: RouteConfig1.label,
             icon: undefined,
             path: "/two",
             nested: undefined,
+            rank: undefined,
             translationNs: undefined
           },
           {
             label: RouteConfig2.label,
             icon: RouteConfig2.icon,
             path: "/three",
             nested: "/products",
+            rank: undefined,
             translationNs: undefined
           }
         ]
@@ -141,6 +144,82 @@ describe("generateMenuItems", () => {
     )
   })
 
+  it("should include rank property in generated menu items", async () => {
+    const mockFilesWithRank = [
+      "Users/user/medusa/src/admin/routes/analytics/page.tsx",
+      "Users/user/medusa/src/admin/routes/reports/page.tsx",
+    ]
+
+    const mockFileContentsWithRank = [
+      `
+        import { defineRouteConfig } from "@medusajs/admin-sdk"
+
+        const Page = () => {
+            return <div>Analytics</div>
+        }
+
+        export const config = defineRouteConfig({
+            label: "Analytics",
+            icon: "ChartBar",
+            rank: 1,
+        })
+
+        export default Page
+      `,
+      `
+        import { defineRouteConfig } from "@medusajs/admin-sdk"
+
+        const Page = () => {
+            return <div>Reports</div>
+        }
+
+        export const config = defineRouteConfig({
+            label: "Reports",
+            rank: 2,
+        })
+
+        export default Page
+      `,
+    ]
+
+    vi.mocked(utils.crawl).mockResolvedValue(mockFilesWithRank)
+
+    vi.mocked(fs.readFile).mockImplementation(async (file) =>
+      Promise.resolve(
+        mockFileContentsWithRank[mockFilesWithRank.indexOf(file as string)]
+      )
+    )
+
+    const result = await generateMenuItems(
+      new Set(["Users/user/medusa/src/admin"])
+    )
+
+    const expectedMenuItemsWithRank = `
+      menuItems: [
+        {
+          label: RouteConfig0.label,
+          icon: RouteConfig0.icon,
+          path: "/analytics",
+          nested: undefined,
+          rank: 1,
+          translationNs: undefined
+        },
+        {
+          label: RouteConfig1.label,
+          icon: undefined,
+          path: "/reports",
+          nested: undefined,
+          rank: 2,
+          translationNs: undefined
+        }
+      ]
+    `
+
+    expect(utils.normalizeString(result.code)).toEqual(
+      utils.normalizeString(expectedMenuItemsWithRank)
+    )
+  })
+
   it("should handle translationNs field", async () => {
     const mockFileWithTranslation = `
       import { defineRouteConfig } from "@medusajs/admin-sdk"
@@ -176,6 +255,7 @@ describe("generateMenuItems", () => {
           icon: undefined,
           path: "/custom",
           nested: undefined,
+          rank: undefined,
           translationNs: RouteConfig0.translationNs
         }
       ]
@@ -185,4 +265,99 @@ describe("generateMenuItems", () => {
       utils.normalizeString(expectedOutput)
     )
   })
+
+  it("should handle mixed ranked and unranked routes", async () => {
+    const mockMixedFiles = [
+      "Users/user/medusa/src/admin/routes/first/page.tsx",
+      "Users/user/medusa/src/admin/routes/second/page.tsx",
+      "Users/user/medusa/src/admin/routes/third/page.tsx",
+    ]
+
+    const mockMixedContents = [
+      `
+        import { defineRouteConfig } from "@medusajs/admin-sdk"
+
+        const Page = () => {
+            return <div>First</div>
+        }
+
+        export const config = defineRouteConfig({
+            label: "First",
+            rank: 1,
+        })
+
+        export default Page
+      `,
+      `
+        import { defineRouteConfig } from "@medusajs/admin-sdk"
+
+        const Page = () => {
+            return <div>Second</div>
+        }
+
+        export const config = defineRouteConfig({
+            label: "Second",
+        })
+
+        export default Page
+      `,
+      `
+        import { defineRouteConfig } from "@medusajs/admin-sdk"
+
+        const Page = () => {
+            return <div>Third</div>
+        }
+
+        export const config = defineRouteConfig({
+            label: "Third",
+            rank: 0,
+        })
+
+        export default Page
+      `,
+    ]
+
+    vi.mocked(utils.crawl).mockResolvedValue(mockMixedFiles)
+
+    vi.mocked(fs.readFile).mockImplementation(async (file) =>
+      Promise.resolve(mockMixedContents[mockMixedFiles.indexOf(file as string)])
+    )
+
+    const result = await generateMenuItems(
+      new Set(["Users/user/medusa/src/admin"])
+    )
+
+    const expectedMixedMenuItems = `
+      menuItems: [
+        {
+          label: RouteConfig0.label,
+          icon: undefined,
+          path: "/first",
+          nested: undefined,
+          rank: 1,
+          translationNs: undefined
+        },
+        {
+          label: RouteConfig1.label,
+          icon: undefined,
+          path: "/second",
+          nested: undefined,
+          rank: undefined,
+          translationNs: undefined
+        },
+        {
+          label: RouteConfig2.label,
+          icon: undefined,
+          path: "/third",
+          nested: undefined,
+          rank: 0,
+          translationNs: undefined
+        }
+      ]
+    `
+
+    expect(utils.normalizeString(result.code)).toEqual(
+      utils.normalizeString(expectedMixedMenuItems)
+    )
+  })
 })

packages/admin/admin-vite-plugin/src/routes/generate-menu-items.ts

@@ -7,6 +7,7 @@ import { outdent } from "outdent"
 import {
   File,
   isIdentifier,
+  isNumericLiteral,
   isObjectProperty,
   isStringLiteral,
   Node,
@@ -27,15 +28,17 @@ import { getRoute } from "./helpers"
 type RouteConfig = {
   label: boolean
   icon: boolean
-  nested?: string
+  nested?: NestedRoutePosition
+  rank?: number
   translationNs?: string
 }
 
 type MenuItem = {
   icon?: string
   label: string
   path: string
-  nested?: string
+  nested?: NestedRoutePosition
+  rank?: number
   translationNs?: string
 }
 
@@ -66,12 +69,13 @@ function generateCode(results: MenuItemResult[]): string {
 }
 
 function formatMenuItem(route: MenuItem): string {
-  const { label, icon, path, nested, translationNs } = route
+  const { label, icon, path, nested, rank, translationNs } = route
   return `{
     label: ${label},
     icon: ${icon || "undefined"},
     path: "${path}",
     nested: ${nested ? `"${nested}"` : "undefined"},
+    rank: ${rank !== undefined ? rank : "undefined"},
     translationNs: ${translationNs ? `${translationNs}` : "undefined"}
   }`
 }
@@ -133,7 +137,10 @@ function generateMenuItem(
     icon: config.icon ? `${configName}.icon` : undefined,
     path: getRoute(file),
     nested: config.nested,
-    translationNs: config.translationNs ? `${configName}.translationNs` : undefined,
+    rank: config.rank,
+    translationNs: config.translationNs
+      ? `${configName}.translationNs`
+      : undefined,
   }
 }
 
@@ -225,7 +232,7 @@ function processConfigProperties(
       isObjectProperty(prop) && isIdentifier(prop.key, { name: "nested" })
   ) as ObjectProperty | undefined
 
-  let nestedValue: string | undefined = undefined
+  let nestedValue: string | undefined
 
   if (isStringLiteral(nested?.value)) {
     nestedValue = nested.value.value
@@ -255,10 +262,22 @@ function processConfigProperties(
     translationNsValue = translationNs.value.value
   }
 
+  const rank = properties.find(
+    (prop) =>
+      isObjectProperty(prop) && isIdentifier(prop.key, { name: "rank" })
+  ) as ObjectProperty | undefined
+
+  let rankValue: number | undefined
+
+  if (isNumericLiteral(rank?.value)) {
+    rankValue = rank.value.value
+  }
+
   return {
     label: hasLabel,
     icon: hasProperty("icon"),
-    nested: nestedValue,
+    nested: nestedValue as NestedRoutePosition | undefined,
+    rank: rankValue,
     translationNs: translationNsValue,
   }
 }