docs: resdesign and restructure modules references (#5372)

* docs: change format of module reference

* description fix

* update structure + comments

* added new options to README

* small text fix

* change section ordering

* change how required/optional are shown

* remove optional text

* docs: redesigned accordion

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

@@ -17,18 +17,13 @@ export const CodeMdx = ({ className, children }: CodeMdxProps) => {
 
   const match = /language-(\w+)/.exec(className || "")
 
+  const codeContent = Array.isArray(children)
+    ? (children[0] as string)
+    : (children as string)
+
   if (match) {
-    return (
-      <CodeBlock
-        source={
-          Array.isArray(children)
-            ? (children[0] as string)
-            : (children as string)
-        }
-        lang={match[1]}
-      />
-    )
+    return <CodeBlock source={codeContent} lang={match[1]} />
   }
 
-  return <InlineCode>{children}</InlineCode>
+  return <InlineCode>{codeContent}</InlineCode>
 }

www/packages/docs-ui/src/components/Details/Summary/index.tsx

@@ -3,8 +3,8 @@ import clsx from "clsx"
 import { PlusMini } from "@medusajs/icons"
 
 export type DetailsSummaryProps = {
-  title: React.ReactNode
-  subtitle?: string
+  title?: React.ReactNode
+  subtitle?: React.ReactNode
   badge?: React.ReactNode
   expandable?: boolean
   open?: boolean
@@ -28,7 +28,9 @@ export const DetailsSummary = ({
       className={clsx(
         "py-docs_0.75 flex items-center justify-between",
         expandable && "cursor-pointer",
-        !expandable && "border-medusa-border-base border-y",
+        !expandable &&
+          "border-medusa-border-base border-y border-solid border-x-0",
+        (expandable || badge) && "gap-0.5",
         "no-marker",
         className
       )}
@@ -44,7 +46,7 @@ export const DetailsSummary = ({
           {title || children}
         </span>
         {subtitle && (
-          <span className="text-compact-medium text-medusa-fg-subtle">
+          <span className="text-compact-medium text-medusa-fg-subtle mt-0.5">
             {subtitle}
           </span>
         )}

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

@@ -10,6 +10,7 @@ export type DetailsProps = {
   openInitial?: boolean
   summaryContent?: React.ReactNode
   summaryElm?: React.ReactNode
+  heightAnimation?: boolean
 } & React.HTMLAttributes<HTMLDetailsElement>
 
 export const Details = ({
@@ -17,13 +18,23 @@ export const Details = ({
   summaryContent,
   summaryElm,
   children,
+  heightAnimation = false,
   ...props
 }: DetailsProps) => {
   const [open, setOpen] = useState(openInitial)
   const [showContent, setShowContent] = useState(openInitial)
   const ref = useRef<HTMLDetailsElement>(null)
 
-  const handleToggle = () => {
+  const handleToggle = (e: React.MouseEvent<HTMLElement>) => {
+    const targetElm = e.target as HTMLElement
+    if (targetElm.tagName.toLowerCase() === "a") {
+      window.location.href =
+        targetElm.getAttribute("href") || window.location.href
+      return
+    }
+    if (targetElm.tagName.toLowerCase() === "code") {
+      return
+    }
     if (open) {
       setShowContent(false)
     } else {
@@ -70,18 +81,45 @@ export const Details = ({
         in={showContent}
         timeout={150}
         onEnter={(node: HTMLElement) => {
-          node.classList.add(
-            "!mb-docs_2",
-            "!mt-0",
-            "translate-y-docs_1",
-            "transition-transform"
-          )
+          if (heightAnimation) {
+            node.classList.add("transition-[height]")
+            node.style.height = `0px`
+          } else {
+            node.classList.add(
+              "!mb-docs_2",
+              "!mt-0",
+              "translate-y-docs_1",
+              "transition-transform"
+            )
+          }
+        }}
+        onEntering={(node: HTMLElement) => {
+          if (heightAnimation) {
+            node.style.height = `${node.scrollHeight}px`
+          }
+        }}
+        onEntered={(node: HTMLElement) => {
+          if (heightAnimation) {
+            node.style.height = `auto`
+          }
         }}
         onExit={(node: HTMLElement) => {
-          node.classList.add("transition-transform", "!-translate-y-docs_1")
-          setTimeout(() => {
-            setOpen(false)
-          }, 100)
+          if (heightAnimation) {
+            node.style.height = `${node.scrollHeight}px`
+          } else {
+            node.classList.add("transition-transform", "!-translate-y-docs_1")
+            setTimeout(() => {
+              setOpen(false)
+            }, 100)
+          }
+        }}
+        onExiting={(node: HTMLElement) => {
+          if (heightAnimation) {
+            node.style.height = `0px`
+            setTimeout(() => {
+              setOpen(false)
+            }, 100)
+          }
         }}
       >
         <Suspense fallback={<Loading className="!mb-docs_2 !mt-0" />}>

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

@@ -6,7 +6,10 @@ import clsx from "clsx"
 
 export type MarkdownContentProps = ReactMarkdownOptions
 
-export const MarkdownContent = ({ children }: MarkdownContentProps) => {
+export const MarkdownContent = ({
+  children,
+  ...props
+}: MarkdownContentProps) => {
   return (
     <ReactMarkdown
       components={{
@@ -79,6 +82,7 @@ export const MarkdownContent = ({ children }: MarkdownContentProps) => {
           )
         },
       }}
+      {...props}
     >
       {children}
     </ReactMarkdown>