docs: fixes and preparations for workflows reference (#8579)

- Fix the merger configuration that adds the correct slug / sidebar labels
- Add an overview page for the workflows reference.
- Fixes to components and build scripts

www/apps/resources/app/medusa-workflows-reference/page.mdx

@@ -0,0 +1,13 @@
+import { ChildDocs } from "docs-ui"
+
+export const metadata = {
+  title: `Medusa Workflows Reference`,
+}
+
+# {metadata.title}
+
+This section of the documentation provides a reference to the workflows created by Medusa. These workflows are used in the Store and Admin API routes.
+
+You can use these workflows in your customizations as well. They're available in the `@medusajs/core-flows` package.
+
+<ChildDocs childLevel={2} />

www/apps/resources/generated/files-map.mjs

@@ -683,6 +683,10 @@ export const filesMap = [
     "filePath": "/www/apps/resources/app/medusa-container-resources/page.mdx",
     "pathname": "/medusa-container-resources"
   },
+  {
+    "filePath": "/www/apps/resources/app/medusa-workflows-reference/page.mdx",
+    "pathname": "/medusa-workflows-reference"
+  },
   {
     "filePath": "/www/apps/resources/app/nextjs-starter/page.mdx",
     "pathname": "/nextjs-starter"

www/apps/resources/package.json

@@ -3,10 +3,9 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev": "yarn prep && next dev",
+    "dev": "next dev",
-    "dev:monorepo": "yarn prep && yarn dev -p 3003",
+    "dev:monorepo": "yarn dev -p 3003",
     "build": "next build",
-    "build:dev": "NODE_ENV=test yarn prep && yarn build",
     "start": "next start",
     "start:monorepo": "yarn start -p 3003",
     "lint": "next lint --fix",

www/packages/build-scripts/src/utils/get-core-flows-ref-sidebar-children.ts

@@ -45,6 +45,10 @@ export default async function getCoreFlowsRefSidebarChildren(): Promise<
       const childDirPath = path.join(namespaceBasePath, childDir.name)
       const childFile = readdirSync(childDirPath)
 
+      if (!childFile.length) {
+        continue
+      }
+
       const sidebarItem = await getSidebarItemLink({
         filePath: path.join(childDirPath, childFile[0]),
         basePath: projPath,

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

@@ -42,11 +42,11 @@ export const Card = ({
       )}
     >
       {startIcon}
-      <div className="flex items-start gap-docs_1 justify-between flex-1">
+      <div className="flex items-start gap-docs_1 justify-between flex-1 max-w-full">
-        <div className={clsx("flex flex-col", contentClassName)}>
+        <div className={clsx("flex flex-col max-w-full", contentClassName)}>
           {title && (
             <span className={clsx(badge && "flex gap-docs_0.5")}>
-              <span className="text-compact-medium-plus text-medusa-fg-base">
+              <span className="text-compact-medium-plus text-medusa-fg-base block truncate">
                 {title}
               </span>
               {badge && <Badge {...badge} />}

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

@@ -10,6 +10,7 @@ type ChildDocsProps = {
   hideItems?: string[]
   showItems?: string[]
   hideTitle?: boolean
+  childLevel?: number
 }
 
 export const ChildDocs = ({
@@ -18,6 +19,7 @@ export const ChildDocs = ({
   showItems,
   type = "sidebar",
   hideTitle = false,
+  childLevel = 1,
 }: ChildDocsProps) => {
   const { currentItems, getActiveItem } = useSidebar()
   const filterType = useMemo(() => {
@@ -79,6 +81,32 @@ export const ChildDocs = ({
     }
   }, [currentItems, type, getActiveItem, filterItems])
 
+  const getChildrenForLevel = (
+    item: SidebarItemType,
+    currentLevel = 1
+  ): SidebarItemType[] | undefined => {
+    if (currentLevel === childLevel) {
+      return item.children
+    }
+    if (!item.children) {
+      return
+    }
+
+    const childrenResult: SidebarItemType[] = []
+
+    item.children.forEach((child) => {
+      const childChildren = getChildrenForLevel(child, currentLevel + 1)
+
+      if (!childChildren) {
+        return
+      }
+
+      childrenResult.push(...childChildren)
+    })
+
+    return childrenResult
+  }
+
   const getTopLevelElms = (items?: SidebarItemType[]) => (
     <CardList
       items={
@@ -93,7 +121,8 @@ export const ChildDocs = ({
 
   const getAllLevelsElms = (items?: SidebarItemType[]) =>
     items?.map((item, key) => {
-      const HeadingComponent = item.children?.length
+      const itemChildren = getChildrenForLevel(item)
+      const HeadingComponent = itemChildren?.length
         ? MDXComponents["h2"]
         : undefined
 
@@ -104,7 +133,7 @@ export const ChildDocs = ({
               {!hideTitle && <HeadingComponent>{item.title}</HeadingComponent>}
               <CardList
                 items={
-                  item.children?.map((childItem) => ({
+                  itemChildren?.map((childItem) => ({
                     title: childItem.title,
                     href: childItem.path,
                     showLinkIcon: false,

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

@@ -11,42 +11,7 @@ const coreFlowsOptions: FormattingOptionsType = {
     workflowDiagramComponent: "WorkflowDiagram",
     mdxImports: [`import { TypeList, WorkflowDiagram } from "docs-ui"`],
   },
-  "^modules/core_flows/page\\.mdx": {
+  "^core_flows/.*/functions/.*Workflow/page\\.mdx": {
-    reflectionDescription:
-      "This section of the documentation provides a reference to Medusa's workflows and steps that you can use in your customizations.",
-    reflectionGroups: {
-      Namespaces: true,
-      Enumerations: false,
-      Classes: false,
-      Interfaces: false,
-      "Type Aliases": false,
-      Variables: false,
-      "Enumeration Members": false,
-      Functions: false,
-    },
-    hideTocHeaders: true,
-    frontmatterData: {
-      slug: "/references/medusa-workflows",
-    },
-    reflectionTitle: {
-      fullReplacement: "Medusa Workflows API Reference",
-    },
-  },
-  "^core_flows/.*/.*(Workflows|Steps)/page\\.mdx": {
-    expandMembers: false,
-    reflectionGroups: {
-      Variables: false,
-      Properties: false,
-      "Type Literals": false,
-    },
-    sections: {
-      ...baseSectionsOptions,
-      member_getterSetter: false,
-      members_categories: false,
-    },
-    hideTocHeaders: true,
-  },
-  "^core_flows/.*Workflows/functions/.*/page\\.mdx": {
     reflectionDescription:
       "This documentation provides a reference to the `{{alias}}`. It belongs to the `@medusajs/core-flows` package.",
     frontmatterData: {
@@ -59,7 +24,7 @@ const coreFlowsOptions: FormattingOptionsType = {
       suffix: "- Medusa Workflows API Reference",
     },
   },
-  "^core_flows/.*Steps/functions/.*/page\\.mdx": {
+  "^core_flows/.*/functions/.*Step/page\\.mdx": {
     reflectionDescription:
       "This documentation provides a reference to the `{{alias}}`. It belongs to the `@medusajs/core-flows` package.",
     frontmatterData: {