docs: show hooks in when condition in workflows reference (#12552)

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

@@ -1,6 +1,10 @@
 import { MarkdownTheme } from "../../theme.js"
 import Handlebars from "handlebars"
-import { DeclarationReflection, SignatureReflection } from "typedoc"
+import {
+  DeclarationReflection,
+  DocumentReflection,
+  SignatureReflection,
+} from "typedoc"
 import { cleanUpHookInput, getHookChildren, getProjectChild } from "utils"
 import beautifyCode from "../../utils/beautify-code.js"
 
@@ -12,9 +16,30 @@ export default function (theme: MarkdownTheme) {
         return ""
       }
 
-      const hooks = this.parent.documents.filter(
-        (document) => document.comment?.modifierTags.has("@hook")
-      )
+      const hooks: {
+        hook: DocumentReflection
+        isNested: boolean
+      }[] = []
+
+      this.parent.documents.forEach((document) => {
+        if (document.comment?.modifierTags.has("@hook")) {
+          hooks.push({
+            hook: document,
+            isNested: false,
+          })
+          return
+        }
+
+        if (!document.comment?.modifierTags.has("@when")) {
+          return
+        }
+
+        const nestedHooks =
+          document.children?.filter(
+            (child) => child.comment?.modifierTags.has("@hook")
+          ) || []
+        hooks.push(...nestedHooks.map((hook) => ({ hook, isNested: true })))
+      })
 
       if (!hooks.length) {
         return ""
@@ -27,7 +52,7 @@ export default function (theme: MarkdownTheme) {
       const hooksTitleLevel = Handlebars.helpers.titleLevel()
       const hookChildren = getHookChildren(this.parent)
 
-      hooks.forEach((hook) => {
+      hooks.forEach(({ hook, isNested }) => {
         const hookReflection =
           hookChildren.find((child) => {
             if (child.name !== hook.name || !child.comment) {
@@ -70,6 +95,10 @@ export default function (theme: MarkdownTheme) {
           )}\n\n`
         }
 
+        if (isNested) {
+          str += `\n\n:::note\n\nThis hook is nested within a [when](https://docs.medusajs.com/learn/fundamentals/workflows/conditions) condition, so it may not be executed if the when condition isn't satisfied.\n\n:::\n\n`
+        }
+
         const hookExample = hookReflection.comment?.getTag(`@example`)
 
         if (hookExample) {