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

www/apps/api-reference/components/Tags/Operation/DescriptionSection/WorkflowBadge/index.tsx

@@ -1,6 +1,5 @@
-import { Badge, DecisionProcessIcon } from "docs-ui"
+import { DecisionProcessIcon, SourceCodeLink } from "docs-ui"
 import { config } from "../../../../../config"
-import Link from "next/link"
 
 export type TagsOperationDescriptionSectionWorkflowBadgeProps = {
   workflow: string
@@ -12,21 +11,11 @@ const TagsOperationDescriptionSectionWorkflowBadge = ({
   return (
     <p className="my-1">
       Workflow{" "}
-      <Link
+      <SourceCodeLink
-        href={`${config.baseUrl}/resources/references/medusa-workflows/${workflow}`}
+        link={`${config.baseUrl}/resources/references/medusa-workflows/${workflow}`}
-        className="align-middle"
+        text={workflow}
-        target="_blank"
+        icon={<DecisionProcessIcon />}
-        rel="noreferrer"
+      />{" "}
-      >
-        <Badge
-          variant="neutral"
-          className="inline-flex hover:bg-medusa-tag-neutral-bg-hover cursor-pointer"
-          childrenWrapperClassName="inline-flex flex-row gap-[3px] items-center"
-        >
-          <DecisionProcessIcon />
-          <span>{workflow}</span>
-        </Badge>
-      </Link>{" "}
       is used in this API route.
     </p>
   )

www/apps/resources/components/MDXComponents/index.tsx

@@ -4,6 +4,7 @@ import {
   MDXComponents as UiMdxComponents,
   TypeList,
   WorkflowDiagram,
+  SourceCodeLink,
 } from "docs-ui"
 import { CommerceModuleSections } from "../CommerceModuleSections"
 
@@ -13,6 +14,7 @@ const MDXComponents: MDXComponentsType = {
   TypeList,
   WorkflowDiagram,
   CommerceModuleSections,
+  SourceCodeLink,
 }
 
 export default MDXComponents

www/packages/docs-ui/src/components/SourceCodeLink/index.tsx

@@ -0,0 +1,37 @@
+import React from "react"
+import { Link } from "../Link"
+import { Badge } from "../Badge"
+import { Github } from "@medusajs/icons"
+import clsx from "clsx"
+
+type SourceCodeLinkProps = {
+  link: string
+  text?: string
+  icon?: React.ReactNode
+  className?: string
+}
+
+export const SourceCodeLink = ({
+  link,
+  text,
+  icon,
+  className,
+}: SourceCodeLinkProps) => {
+  return (
+    <Link
+      href={link}
+      target="_blank"
+      rel="noreferrer"
+      className={clsx("my-docs_0.5 align-middle inline-block", className)}
+    >
+      <Badge
+        variant="neutral"
+        className="inline-flex hover:bg-medusa-tag-neutral-bg-hover cursor-pointer"
+        childrenWrapperClassName="inline-flex flex-row gap-[3px] items-center"
+      >
+        {icon || <Github />}
+        <span>{text || "Source Code"}</span>
+      </Badge>
+    </Link>
+  )
+}

www/packages/docs-ui/src/components/Tooltip/index.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import React, { useId } from "react"
+import React, { forwardRef, useId } from "react"
 import { Tooltip as ReactTooltip } from "react-tooltip"
 import type { ITooltip } from "react-tooltip"
 import clsx from "clsx"
@@ -15,47 +15,52 @@ export type TooltipProps = {
 } & React.HTMLAttributes<HTMLSpanElement> &
   ITooltip
 
-export const Tooltip = ({
+export const Tooltip = forwardRef<HTMLSpanElement, TooltipProps>(
-  text = "",
+  function Tooltip(
-  tooltipClassName = "",
+    {
-  children,
+      text = "",
-  html = "",
+      tooltipClassName = "",
-  tooltipChildren,
+      children,
-  className,
+      html = "",
-  innerClassName,
+      tooltipChildren,
-  ...tooltipProps
+      className,
-}: TooltipProps) => {
+      innerClassName,
-  const elementId = useId()
+      ...tooltipProps
+    },
+    ref
+  ) {
+    const elementId = useId()
 
-  return (
+    return (
-    <span className={clsx(className, "notranslate")} translate="no">
+      <span className={clsx(className, "notranslate")} translate="no" ref={ref}>
-      <span
+        <span
-        id={elementId}
+          id={elementId}
-        data-tooltip-content={text}
+          data-tooltip-content={text}
-        data-tooltip-html={html}
+          data-tooltip-html={html}
-        data-tooltip-id={elementId}
+          data-tooltip-id={elementId}
-        className={innerClassName}
+          className={innerClassName}
-      >
+        >
-        {children}
+          {children}
+        </span>
+        <ReactTooltip
+          anchorId={elementId}
+          // anchorSelect={elementId ? `#${elementId}` : undefined}
+          className={clsx(
+            "!text-compact-x-small !shadow-elevation-tooltip dark:!shadow-elevation-tooltip-dark !rounded-docs_DEFAULT",
+            "!py-docs_0.25 !z-[399] hidden !px-docs_0.5 lg:block",
+            "!bg-medusa-bg-component",
+            "!text-medusa-fg-base text-center",
+            tooltipClassName
+          )}
+          wrapper="span"
+          noArrow={true}
+          positionStrategy={"fixed"}
+          opacity={1}
+          {...tooltipProps}
+        >
+          {tooltipChildren}
+        </ReactTooltip>
       </span>
-      <ReactTooltip
+    )
-        anchorId={elementId}
+  }
-        // anchorSelect={elementId ? `#${elementId}` : undefined}
+)
-        className={clsx(
-          "!text-compact-x-small !shadow-elevation-tooltip dark:!shadow-elevation-tooltip-dark !rounded-docs_DEFAULT",
-          "!py-docs_0.25 !z-[399] hidden !px-docs_0.5 lg:block",
-          "!bg-medusa-bg-component",
-          "!text-medusa-fg-base text-center",
-          tooltipClassName
-        )}
-        wrapper="span"
-        noArrow={true}
-        positionStrategy={"fixed"}
-        opacity={1}
-        {...tooltipProps}
-      >
-        {tooltipChildren}
-      </ReactTooltip>
-    </span>
-  )
-}

www/packages/docs-ui/src/components/TypeList/Items/index.tsx

@@ -41,6 +41,7 @@ const TypeListItem = ({
   elementKey,
   sectionTitle,
   referenceType = "method",
+  openedLevel = 0,
 }: TypeListItemProps) => {
   const { isBrowser } = useIsBrowser()
   const pathname = usePathname()
@@ -249,6 +250,7 @@ const TypeListItem = ({
           className={clsx(getItemClassNames())}
           heightAnimation={true}
           id={typeId ? typeId : ""}
+          openInitial={openedLevel >= level}
         >
           {typeItem.children && (
             <TypeListItems

www/packages/docs-ui/src/components/TypeList/index.tsx

@@ -5,6 +5,7 @@ import { Loading } from "@/components"
 export type CommonProps = {
   expandUrl?: string
   sectionTitle?: string
+  openedLevel?: number
 }
 
 export type Type = {
@@ -31,6 +32,7 @@ export const TypeList = ({
   className,
   sectionTitle,
   expandUrl,
+  openedLevel,
   ...props
 }: ParameterTypesType) => {
   return (
@@ -47,6 +49,7 @@ export const TypeList = ({
           types={types}
           expandUrl={expandUrl}
           sectionTitle={sectionTitle}
+          openedLevel={openedLevel}
         />
       </Suspense>
     </div>

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>
   )
 }

www/packages/docs-ui/src/components/index.ts

@@ -66,6 +66,7 @@ export * from "./Search/Suggestions/Item"
 export * from "./Select"
 export * from "./Sidebar"
 export * from "./Sidebar/Item"
+export * from "./SourceCodeLink"
 export * from "./Table"
 export * from "./Tabs"
 export * from "./TextArea"

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

@@ -14,7 +14,6 @@ export const baseOptions: Partial<TypeDocOptions> = {
   excludeInternal: true,
   excludeExternals: true,
   excludeReferences: true,
-  disableSources: true,
   sort: ["source-order"],
   validation: {
     notExported: false,

www/utils/packages/typedoc-plugin-markdown-medusa/src/render-utils.ts

@@ -77,6 +77,7 @@ import workflowHooksHelper from "./resources/helpers/workflow-hooks.js"
 import ifMemberShowTitleHelper from "./resources/helpers/if-member-show-title.js"
 import signatureCommentHelper from "./resources/helpers/signature-comment.js"
 import versionHelper from "./resources/helpers/version.js"
+import sourceCodeLinkHelper from "./resources/helpers/source-code-link.js"
 import { MarkdownTheme } from "./theme.js"
 import { getDirname } from "utils"
 
@@ -185,4 +186,5 @@ export function registerHelpers(theme: MarkdownTheme) {
   ifMemberShowTitleHelper(theme)
   signatureCommentHelper()
   versionHelper()
+  sourceCodeLinkHelper()
 }

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/parameter-component.ts

@@ -10,7 +10,8 @@ export default function (theme: MarkdownTheme) {
     "parameterComponent",
     function (
       this: ReflectionParameterType[],
-      options: Handlebars.HelperOptions
+      options: Handlebars.HelperOptions,
+      extraProps?: Record<string, unknown>
     ) {
       const { parameterComponent, maxLevel, parameterComponentExtraProps } =
         theme.getFormattingOptionsForLocation()
@@ -34,7 +35,10 @@ export default function (theme: MarkdownTheme) {
       return formatParameterComponent({
         parameterComponent,
         componentItems: parameters,
-        extraProps: parameterComponentExtraProps,
+        extraProps: {
+          ...parameterComponentExtraProps,
+          ...extraProps,
+        },
         sectionTitle: options.hash.sectionTitle,
       })
     }

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/source-code-link.ts

@@ -0,0 +1,17 @@
+import Handlebars from "handlebars"
+import { SignatureReflection } from "typedoc"
+
+export default function () {
+  Handlebars.registerHelper(
+    "sourceCodeLink",
+    function (this: SignatureReflection): string {
+      const source = this.parent.sources?.[0]
+
+      if (!source?.url) {
+        return ""
+      }
+
+      return `<SourceCodeLink link="${source.url}" />`
+    }
+  )
+}

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-input.ts

@@ -34,7 +34,10 @@ export default function (theme: MarkdownTheme) {
       const formattedComponent = formatParameterComponent({
         parameterComponent,
         componentItems: input,
-        extraProps: parameterComponentExtraProps,
+        extraProps: {
+          ...parameterComponentExtraProps,
+          openedLevel: 1,
+        },
         sectionTitle: options.hash.sectionTitle,
       })
 

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/helpers/step-output.ts

@@ -34,7 +34,10 @@ export default function (theme: MarkdownTheme) {
       const formattedComponent = formatParameterComponent({
         parameterComponent,
         componentItems: output,
-        extraProps: parameterComponentExtraProps,
+        extraProps: {
+          ...parameterComponentExtraProps,
+          openedLevel: 1,
+        },
         sectionTitle: options.hash.sectionTitle,
       })
 

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

@@ -60,6 +60,9 @@ export default function (theme: MarkdownTheme) {
             hash: {
               sectionTitle: hook.name,
             },
+          },
+          {
+            openedLevel: 1,
           }
         )
       })

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

@@ -34,7 +34,10 @@ export default function (theme: MarkdownTheme) {
       const formattedComponent = formatParameterComponent({
         parameterComponent,
         componentItems: input,
-        extraProps: parameterComponentExtraProps,
+        extraProps: {
+          ...parameterComponentExtraProps,
+          openedLevel: 1,
+        },
         sectionTitle: options.hash.sectionTitle,
       })
 

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

@@ -34,7 +34,10 @@ export default function (theme: MarkdownTheme) {
       const formattedComponent = formatParameterComponent({
         parameterComponent,
         componentItems: output,
-        extraProps: parameterComponentExtraProps,
+        extraProps: {
+          ...parameterComponentExtraProps,
+          openedLevel: 1,
+        },
         sectionTitle: options.hash.sectionTitle,
       })
 

www/utils/packages/typedoc-plugin-markdown-medusa/src/resources/partials/member.workflow.hbs

@@ -8,6 +8,8 @@
 
 {{/if}}
 
+{{{sourceCodeLink}}}
+
 {{#if (sectionEnabled "member_signature_example")}}
 
 {{{example this}}}

www/utils/packages/typedoc-plugin-markdown-medusa/src/utils/format-parameter-component.ts

@@ -48,9 +48,11 @@ export function formatParameterComponent({
 }: FormatParameterComponentProps): string {
   let extraPropsArr: string[] = []
   if (extraProps) {
-    extraPropsArr = Object.entries(extraProps).map(
+    extraPropsArr = Object.entries(extraProps).map(([key, value]) => {
-      ([key, value]) => `${key}=${JSON.stringify(value)}`
+      const valueJSON = JSON.stringify(value)
-    )
+      const valueStr = typeof value !== "string" ? `{${valueJSON}}` : valueJSON
+      return `${key}=${valueStr}`
+    })
   }
   // reorder component items to show required items first
   componentItems = sortComponentItems(componentItems)