docs: support version in events reference (#12422)

* docs: support version in events reference

* remove changes in events output

* remove events emitted in comments

* remove customer updated event

* check for emitEventStep usage

* fixes

www/utils/packages/docs-generator/src/classes/kinds/events.ts

@@ -124,8 +124,18 @@ class EventsKindGenerator extends DefaultKindGenerator<ts.VariableDeclaration> {
       }
 
       this.workflows[workflowName] = workflowFile
-      if (workflowFile.includes("emitEventStep")) {
-        this.workflowsEmittingEvents[workflowName] = workflowFile
+      // remove comments in case the emitEventStep is commented out
+      const workflowWithoutComments = workflowFile.replace(
+        /\/\*[\s\S]*?\*\/|\/\/.*/g,
+        ""
+      )
+      // the emitEventStep should be mentioned at least twice in the workflow
+      // including the import statement
+      const emitEventStepCount = (
+        workflowWithoutComments.match(/emitEventStep/g) || []
+      ).length
+      if (emitEventStepCount >= 2) {
+        this.workflowsEmittingEvents[workflowName] = workflowWithoutComments
       }
     }
   }

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/events-listing.ts

@@ -116,6 +116,21 @@ function formatEventsType(
       }
     }
 
+    const versionTag = event.comment?.blockTags.find(
+      (tag) => tag.tag === "@version"
+    )
+
+    if (versionTag) {
+      eventName += `\n`
+      const versionText = versionTag.content
+        .map((content) => content.text)
+        .join("")
+        .trim()
+      eventName += `<Tooltip text="This event was added in version v${versionText}">`
+      eventName += `<Badge variant="blue">v${versionText}</Badge>`
+      eventName += `</Tooltip>`
+    }
+
     content.push(`    <Table.Row>`)
     content.push(`      <Table.Cell>\n${eventName}\n</Table.Cell>`)
     content.push(`      <Table.Cell>\n${eventDescription}\n</Table.Cell>`)
@@ -152,6 +167,10 @@ function formatEventsType(
       .join("")
       .trim()
 
+    const versionTag = event.comment?.blockTags.find(
+      (tag) => tag.tag === "@version"
+    )
+
     content.push(
       getEventHeading({
         titleLevel: subtitleLevel,
@@ -159,6 +178,12 @@ function formatEventsType(
         payload: eventPayload || "",
         deprecated: !!deprecatedTag,
         deprecatedMessage,
+        version: versionTag
+          ? versionTag.content
+              .map((content) => content.text)
+              .join("")
+              .trim()
+          : undefined,
       })
     )
     content.push("")
@@ -191,12 +216,14 @@ function getEventHeading({
   payload,
   deprecated = false,
   deprecatedMessage,
+  version,
 }: {
   titleLevel: number
   eventName: string
   payload: string
   deprecated?: boolean
   deprecatedMessage?: string
+  version?: string
 }) {
   const heading = [eventName]
   if (deprecated) {
@@ -210,6 +237,14 @@ function getEventHeading({
       heading.push(`</Tooltip>`)
     }
   }
+  if (version) {
+    if (deprecated) {
+      heading.push(`\n`)
+    }
+    heading.push(`<Tooltip text="This event was added in version v${version}">`)
+    heading.push(`<Badge variant="blue">v${version}</Badge>`)
+    heading.push(`</Tooltip>`)
+  }
   return `<EventHeader headerLvl="${titleLevel}" headerProps={{ id: "${getEventNameSlug(
     eventName
   )}", children: (<>${heading.join(

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

@@ -41,10 +41,24 @@ export default function () {
         const eventPayloadFormatted = eventPayload
           .replace("```ts\n", "")
           .replace("\n```", "")
-        const isDeprecated = commentContent.length >= 4
+        const isDeprecatedOrHasVersion = commentContent.length >= 4
+        const deprecatedIndex = isDeprecatedOrHasVersion
+          ? commentContent.slice(3).findIndex((c) => c.trim() === "deprecated")
+          : -1
+        const isDeprecated = deprecatedIndex !== -1
+        const deprecatedText = (
+          isDeprecated ? commentContent[3 + deprecatedIndex] || "" : ""
+        ).trim()
+        const version = isDeprecatedOrHasVersion
+          ? commentContent
+              .slice(3)
+              .find((c) => c.trim().startsWith("version: "))
+          : undefined
+        const versionText = (
+          version ? version.replace("version: ", "") : ""
+        ).trim()
 
         if (isDeprecated) {
-          const deprecatedText = commentContent[4]?.trim()
           eventNameFormatted += `\n`
           if (deprecatedText) {
             eventNameFormatted += `<Tooltip text="${deprecatedText}">`
@@ -55,6 +69,13 @@ export default function () {
           }
         }
 
+        if (versionText) {
+          eventNameFormatted += `\n\n`
+          eventNameFormatted += `<Tooltip text="This event was added in version v${versionText}">`
+          eventNameFormatted += `<Badge variant="blue">v${versionText}</Badge>`
+          eventNameFormatted += `</Tooltip>\n`
+        }
+
         str += `    <Table.Row>\n`
         str += `      <Table.Cell>\n${eventNameFormatted}\n</Table.Cell>\n`
         str += `      <Table.Cell>\n${eventDescription}\n</Table.Cell>\n`

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

@@ -915,6 +915,12 @@ class WorkflowsPlugin {
             commentText += ` -- ${event.deprecated_message}`
           }
         }
+        if (event.version) {
+          commentText += ` -- version: ${event.version}`
+        }
+        if (event.name === "order-edit.canceled") {
+          console.log(event, commentText)
+        }
         return new CommentTag(`@workflowEvent`, [
           {
             kind: "text",