docs: fix page title in reference pagesnot showing + refactor workflows reference (#10537)

* docs: fix references title + refactor workflow reference generation

* update references sidebar

www/apps/resources/app/references/[...slug]/page.tsx

@@ -12,6 +12,8 @@ import MDXComponents from "@/components/MDXComponents"
 import mdxOptions from "../../../mdx-options.mjs"
 import { slugChanges } from "../../../generated/slug-changes.mjs"
 import { filesMap } from "../../../generated/files-map.mjs"
+import { Metadata } from "next"
+import { cache } from "react"
 
 type PageProps = {
   params: Promise<{
@@ -23,28 +25,20 @@ export default async function ReferencesPage(props: PageProps) {
   const params = await props.params
   const { slug } = params
 
-  // ensure that Vercel loads references files
-  path.join(process.cwd(), "references")
-  const monoRepoPath = path.resolve("..", "..", "..")
+  const fileData = await loadFile(slug)
 
-  const pathname = `/references/${slug.join("/")}`
-  const fileDetails =
-    slugChanges.find((f) => f.newSlug === pathname) ||
-    filesMap.find((f) => f.pathname === pathname)
-  if (!fileDetails) {
+  if (!fileData) {
     return notFound()
   }
-  const fullPath = path.join(monoRepoPath, fileDetails.filePath)
-  const fileContent = await fs.readFile(fullPath, "utf-8")
 
   const pluginOptions = {
-    filePath: fullPath,
+    filePath: fileData.path,
     basePath: process.cwd(),
   }
 
   return (
     <MDXRemote
-      source={fileContent}
+      source={fileData.content}
       components={MDXComponents}
       options={{
         mdxOptions: {
@@ -79,3 +73,55 @@ export default async function ReferencesPage(props: PageProps) {
     />
   )
 }
+
+export async function generateMetadata({
+  params,
+}: PageProps): Promise<Metadata> {
+  // read route params
+  const slug = (await params).slug
+  const metadata: Metadata = {}
+
+  const fileData = await loadFile(slug)
+
+  if (!fileData) {
+    return metadata
+  }
+
+  const pageTitleMatch = /#(?<title>[\w -]+)/.exec(fileData.content)
+
+  if (!pageTitleMatch?.groups?.title) {
+    return metadata
+  }
+
+  metadata.title = pageTitleMatch.groups.title
+
+  return metadata
+}
+
+const loadFile = cache(
+  async (
+    slug: string[]
+  ): Promise<
+    | {
+        content: string
+        path: string
+      }
+    | undefined
+  > => {
+    path.join(process.cwd(), "references")
+    const monoRepoPath = path.resolve("..", "..", "..")
+
+    const pathname = `/references/${slug.join("/")}`
+    const fileDetails =
+      slugChanges.find((f) => f.newSlug === pathname) ||
+      filesMap.find((f) => f.pathname === pathname)
+    if (!fileDetails) {
+      return undefined
+    }
+    const fullPath = path.join(monoRepoPath, fileDetails.filePath)
+    return {
+      content: await fs.readFile(fullPath, "utf-8"),
+      path: fullPath,
+    }
+  }
+)

www/apps/resources/generated/sidebar.mjs

@@ -9802,7 +9802,7 @@ export const generatedSidebar = [
         "isPathHref": true,
         "type": "link",
         "path": "/service-factory-reference",
-        "title": "Service Factory Reference",
+        "title": "Service Factory",
         "isChildSidebar": true,
         "children": [
           {
@@ -9902,7 +9902,7 @@ export const generatedSidebar = [
         "isPathHref": true,
         "type": "link",
         "path": "/references/helper-steps",
-        "title": "Helper Steps Reference",
+        "title": "Helper Steps",
         "isChildSidebar": true,
         "autogenerate_path": "/references/helper_steps/functions",
         "children": [
@@ -9976,7 +9976,7 @@ export const generatedSidebar = [
         "loaded": true,
         "isPathHref": true,
         "type": "link",
-        "title": "Core Workflows Reference",
+        "title": "Core Workflows",
         "path": "/medusa-workflows-reference",
         "isChildSidebar": true,
         "custom_autogenerate": "core-flows",
@@ -15114,7 +15114,7 @@ export const generatedSidebar = [
         "loaded": true,
         "isPathHref": true,
         "type": "link",
-        "title": "Testing Framework Reference",
+        "title": "Testing Framework",
         "path": "/test-tools-reference",
         "isChildSidebar": true,
         "children": [

www/apps/resources/sidebar.mjs

@@ -2404,7 +2404,7 @@ export const sidebar = sidebarAttachHrefCommonOptions([
       {
         type: "link",
         path: "/service-factory-reference",
-        title: "Service Factory Reference",
+        title: "Service Factory",
         isChildSidebar: true,
         children: [
           {
@@ -2422,20 +2422,20 @@ export const sidebar = sidebarAttachHrefCommonOptions([
       {
         type: "link",
         path: "/references/helper-steps",
-        title: "Helper Steps Reference",
+        title: "Helper Steps",
         isChildSidebar: true,
         autogenerate_path: "/references/helper_steps/functions",
       },
       {
         type: "link",
-        title: "Core Workflows Reference",
+        title: "Core Workflows",
         path: "/medusa-workflows-reference",
         isChildSidebar: true,
         custom_autogenerate: "core-flows",
       },
       {
         type: "link",
-        title: "Testing Framework Reference",
+        title: "Testing Framework",
         path: "/test-tools-reference",
         isChildSidebar: true,
         children: [

www/apps/resources/tsconfig.json

@@ -11,7 +11,8 @@
       "../../node_modules/@types",
       "./node_modules/@types",
       "./types"
-    ]
+    ],
+    "target": "es2018"
   },
   "include": [
     "next-env.d.ts",

www/utils/packages/typedoc-generate-references/src/constants/merger-options.ts

@@ -30,9 +30,6 @@ const allowedProjectDocuments: AllowedProjectDocumentsOption = {
     [ReflectionKind.Method]: true,
     [ReflectionKind.Property]: true,
   },
-  "core-flows": {
-    [ReflectionKind.Function]: true,
-  },
 }
 
 modules.forEach((module) => {
@@ -47,7 +44,11 @@ dmlModules.forEach((module) => {
   }
 })
 
-getNamespaceNames(getCoreFlowNamespaces()).forEach((namespace) => {
+const { mainNamespaces: mainCoreFlowNamespaces } = getNamespaceNames(
+  getCoreFlowNamespaces()
+)
+
+mainCoreFlowNamespaces.forEach((namespace) => {
   allowedProjectDocuments[namespace] = {
     ...commonAllowedDocuments,
   }

www/utils/packages/typedoc-generate-references/src/utils/get-namespaces.ts

@@ -67,8 +67,23 @@ export function getCoreFlowNamespaces(): NamespaceGenerateDetails[] {
   return namespaces
 }
 
-export function getNamespaceNames(
-  namespaces: NamespaceGenerateDetails[]
-): string[] {
-  return namespaces.map((namespace) => namespace.name)
+export function getNamespaceNames(namespaces: NamespaceGenerateDetails[]): {
+  mainNamespaces: string[]
+  childNamespaces: string[]
+} {
+  const mainNamespaces: string[] = []
+  const childNamespaces: string[] = []
+
+  namespaces.map((namespace) => {
+    mainNamespaces.push(namespace.name)
+    childNamespaces.push(
+      ...(namespace.children?.map((childNamespace) => childNamespace.name) ||
+        [])
+    )
+  })
+
+  return {
+    mainNamespaces,
+    childNamespaces,
+  }
 }

www/utils/packages/typedoc-plugin-custom/src/generate-path-namespaces.ts

@@ -2,10 +2,10 @@ import { minimatch } from "minimatch"
 import {
   Application,
   Comment,
-  Context,
   Converter,
   DeclarationReflection,
   ParameterType,
+  ProjectReflection,
   ReflectionKind,
 } from "typedoc"
 import { NamespaceGenerateDetails } from "types"
@@ -35,17 +35,18 @@ export function load(app: Application) {
       "generatePathNamespaces"
     ) as unknown as NamespaceGenerateDetails[]
 
-    const generatePathNamespaces = (ns: NamespaceGenerateDetails[]) => {
+    const generatePathNamespaces = (
+      ns: NamespaceGenerateDetails[],
+      parent: ProjectReflection | DeclarationReflection = context.project
+    ) => {
       const createdNamespaces: DeclarationReflection[] = []
       ns.forEach((namespace) => {
-        const genNamespace = createNamespace(context, namespace)
+        const genNamespace = createNamespace(parent, namespace)
 
         generatedNamespaces.set(namespace.pathPattern, genNamespace)
 
         if (namespace.children) {
-          generatePathNamespaces(namespace.children).forEach((child) =>
-            genNamespace.addChild(child)
-          )
+          generatePathNamespaces(namespace.children, genNamespace)
         }
 
         createdNamespaces.push(genNamespace)
@@ -102,24 +103,27 @@ export function load(app: Application) {
 
       const namespace = findNamespace(namespaces)
 
-      namespace?.addChild(reflection)
+      if (namespace) {
+        context.project.removeChild(reflection)
+        namespace?.addChild(reflection)
+      }
     }
   )
 }
 
 function createNamespace(
-  context: Context,
+  parent: DeclarationReflection | ProjectReflection,
   namespace: NamespaceGenerateDetails
 ): DeclarationReflection {
-  const genNamespace = context.createDeclarationReflection(
+  const reflection = new DeclarationReflection(
+    namespace.name,
     ReflectionKind.Namespace,
-    void 0,
-    void 0,
-    namespace.name
+    parent
   )
+  parent.addChild(reflection)
 
   if (namespace.description) {
-    genNamespace.comment = new Comment([
+    reflection.comment = new Comment([
       {
         kind: "text",
         text: namespace.description,
@@ -127,5 +131,5 @@ function createNamespace(
     ])
   }
 
-  return genNamespace
+  return reflection
 }

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/workflow-diagram.ts

@@ -1,9 +1,12 @@
 import { MarkdownTheme } from "../../theme"
 import * as Handlebars from "handlebars"
-import { DocumentReflection, SignatureReflection } from "typedoc"
+import {
+  DocumentReflection,
+  ReflectionKind,
+  SignatureReflection,
+} from "typedoc"
 import { formatWorkflowDiagramComponent } from "../../utils/format-workflow-diagram-component"
-import { getProjectChild } from "utils"
-import { getWorkflowReflectionFromNamespace } from "../../utils/workflow-utils"
+import { findReflectionInNamespaces, getProjectChild } from "utils"
 
 export default function (theme: MarkdownTheme) {
   Handlebars.registerHelper(
@@ -81,7 +84,13 @@ function getStep({
       : "step"
 
   const namespaceRefl = theme.project
-    ? getWorkflowReflectionFromNamespace(theme.project, document.name)
+    ? findReflectionInNamespaces(
+        theme.project
+          .getChildrenByKind(ReflectionKind.Module)
+          .find((moduleRef) => moduleRef.name === "core-flows") ||
+          theme.project,
+        document.name
+      )
     : undefined
 
   const associatedReflection =

www/utils/packages/typedoc-plugin-workflows/src/plugin.ts

@@ -15,7 +15,7 @@ import {
 import ts, { SyntaxKind, VariableStatement } from "typescript"
 import { WorkflowManager, WorkflowDefinition } from "@medusajs/orchestration"
 import Helper from "./utils/helper"
-import { isWorkflow, isWorkflowStep } from "utils"
+import { findReflectionInNamespaces, isWorkflow, isWorkflowStep } from "utils"
 import { StepType } from "./types"
 
 type ParsedStep = {
@@ -253,8 +253,10 @@ class WorkflowsPlugin {
           workflowName: workflowVarName,
         })
       } else {
-        const initializerReflection =
-          context.project.getChildByName(initializerName)
+        const initializerReflection = findReflectionInNamespaces(
+          context.project,
+          initializerName
+        )
 
         if (
           !initializerReflection ||

www/utils/packages/typedoc-plugin-workflows/src/utils/helper.ts

@@ -5,7 +5,7 @@ import {
 } from "typedoc"
 import ts from "typescript"
 import { StepModifier, StepType } from "../types"
-import { capitalize } from "utils"
+import { capitalize, findReflectionInNamespaces } from "utils"
 
 /**
  * A class of helper methods.
@@ -173,7 +173,9 @@ export default class Helper {
     project: ProjectReflection
   ): string | undefined {
     // load it from the project
-    const idVarReflection = project.getChildByName(refName)
+    const idVarReflection =
+      project.getChildByName(refName) ||
+      findReflectionInNamespaces(project, refName)
 
     if (
       !idVarReflection ||

www/utils/packages/utils/src/workflow-utils.ts

@@ -1,4 +1,12 @@
-import { ReferenceType, SignatureReflection, SomeType } from "typedoc"
+import {
+  DeclarationReflection,
+  ProjectReflection,
+  ReferenceType,
+  Reflection,
+  ReflectionKind,
+  SignatureReflection,
+  SomeType,
+} from "typedoc"
 
 export function isWorkflow(reflection: SignatureReflection): boolean {
   return (
@@ -60,3 +68,21 @@ function isAllowedType(type: SomeType | undefined): boolean {
       !disallowedIntrinsicTypeNames.includes(type.name))
   )
 }
+
+export function findReflectionInNamespaces(
+  parent: ProjectReflection | DeclarationReflection,
+  childName: string
+): Reflection | undefined {
+  let childReflection: Reflection | undefined
+  parent.getChildrenByKind(ReflectionKind.Namespace).some((namespace) => {
+    childReflection = namespace.getChildByName(childName)
+
+    if (!childReflection) {
+      childReflection = findReflectionInNamespaces(namespace, childName)
+    }
+
+    return childReflection !== undefined
+  })
+
+  return childReflection
+}