docs: DX improvements to a workflow / step reference page (#10906)

www/packages/docs-ui/src/components/WorkflowDiagram/Common/Legend/index.tsx

@@ -0,0 +1,37 @@
+import React from "react"
+import { InlineCode } from "../../../InlineCode"
+import { Text } from "@medusajs/ui"
+import { Bolt, InformationCircle } from "@medusajs/icons"
+
+export const WorkflowDiagramLegend = () => {
+  return (
+    <div className="flex gap-docs_0.5 mt-1">
+      <div className="flex items-center gap-docs_0.5">
+        <div className="flex size-[20px] items-center justify-center text-medusa-tag-orange-icon">
+          <Bolt />
+        </div>
+        <Text
+          size="xsmall"
+          leading="compact"
+          weight="plus"
+          className="select-none"
+        >
+          Workflow Hook
+        </Text>
+      </div>
+      <div className="flex items-center gap-docs_0.5">
+        <div className="flex size-[20px] items-center justify-center text-medusa-tag-green-icon">
+          <InformationCircle />
+        </div>
+        <Text
+          size="xsmall"
+          leading="compact"
+          weight="plus"
+          className="select-none"
+        >
+          Step conditioned by <InlineCode>when</InlineCode>
+        </Text>
+      </div>
+    </div>
+  )
+}

www/packages/docs-ui/src/components/WorkflowDiagram/Common/Node/index.tsx

@@ -3,7 +3,7 @@
 import { Text } from "@medusajs/ui"
 import clsx from "clsx"
 import Link from "next/link"
-import React, { useMemo } from "react"
+import React, { useEffect, useMemo, useRef, useState } from "react"
 import { WorkflowStepUi } from "types"
 import { InlineCode, MarkdownContent, Tooltip } from "../../.."
 import { Bolt, InformationCircle } from "@medusajs/icons"
@@ -14,11 +14,34 @@ export type WorkflowDiagramNodeProps = {
 
 export const WorkflowDiagramStepNode = ({ step }: WorkflowDiagramNodeProps) => {
   const stepId = step.name.split(".").pop()
+  const [offset, setOffset] = useState<number | undefined>(undefined)
+  const ref = useRef<HTMLSpanElement>(null)
 
   const description = useMemo(() => {
     return step.description?.replaceAll(/:::[a-z]*/g, "") || ""
   }, [step.description])
 
+  useEffect(() => {
+    if (!ref.current) {
+      return
+    }
+
+    // find parent
+    const diagramParent = ref.current.closest(".workflow-list-diagram")
+    const nodeParent = ref.current.closest(".workflow-node-group")
+
+    if (!diagramParent || !nodeParent) {
+      return
+    }
+
+    const nodeBoundingRect = nodeParent.getBoundingClientRect()
+    const diagramBoundingRect = diagramParent.getBoundingClientRect()
+
+    setOffset(
+      Math.max(diagramBoundingRect.width - nodeBoundingRect.width + 10, 10)
+    )
+  }, [ref.current])
+
   return (
     <Tooltip
       tooltipClassName="!text-left max-w-[300px] text-pretty overflow-scroll"
@@ -43,6 +66,8 @@ export const WorkflowDiagramStepNode = ({ step }: WorkflowDiagramNodeProps) => {
       }
       clickable={true}
       place="right"
+      offset={offset}
+      ref={ref}
     >
       <Link
         href={step.link || `#${step.name}`}

www/packages/docs-ui/src/components/WorkflowDiagram/List/Depth/index.tsx

@@ -14,7 +14,7 @@ export const WorkflowDiagramListDepth = ({
   cluster,
 }: WorkflowDiagramListDepthProps) => {
   return (
-    <div className="flex items-start">
+    <div className="flex items-start workflow-node-group w-fit">
       <WorkflowDiagramLine step={cluster} />
       <div className="flex flex-col justify-center gap-y-docs_0.5">
         {cluster.map((step, index) => (

www/packages/docs-ui/src/components/WorkflowDiagram/List/index.tsx

@@ -4,6 +4,7 @@ import React from "react"
 import { createNodeClusters, getNextCluster } from "../../../utils"
 import { WorkflowDiagramCommonProps } from "../../.."
 import { WorkflowDiagramListDepth } from "./Depth"
+import { WorkflowDiagramLegend } from "../Common/Legend"
 
 export const WorkflowDiagramList = ({
   workflow,
@@ -11,7 +12,7 @@ export const WorkflowDiagramList = ({
   const clusters = createNodeClusters(workflow.steps)
 
   return (
-    <div className="flex flex-col gap-docs_0.5 my-docs_1">
+    <div className="flex flex-col gap-docs_0.5 my-docs_1 workflow-list-diagram w-fit">
       {Object.entries(clusters).map(([depth, cluster]) => {
         const next = getNextCluster(clusters, Number(depth))
 
@@ -19,6 +20,7 @@ export const WorkflowDiagramList = ({
           <WorkflowDiagramListDepth cluster={cluster} next={next} key={depth} />
         )
       })}
+      <WorkflowDiagramLegend />
     </div>
   )
 }