docs: improvements and fixes to components in API reference (#9410)

- Change layout of parameters for clearer display
- Fix schema code blocks being longer than container
- switch between showing required to showing optional indicator
- Fixed code tabs not having copy / report buttons

Closes DOCS-936

Preview: https://api-reference-v2-git-docs-api-ref-comp-improv-medusajs.vercel.app/v2/api/store

www/packages/docs-ui/src/components/CodeBlock/Actions/index.tsx

@@ -15,7 +15,7 @@ export type CodeBlockActionsProps = {
   inInnerCode?: boolean
   isCollapsed: boolean
   canShowApiTesting?: boolean
-  onApiTesting: React.Dispatch<React.SetStateAction<boolean>>
+  onApiTesting?: React.Dispatch<React.SetStateAction<boolean>>
   noReport?: boolean
   noCopy?: boolean
 }
@@ -91,7 +91,7 @@ export const CodeBlockActions = ({
                 inHeader && "p-[4.5px]",
                 "cursor-pointer"
               )}
-              onClick={() => onApiTesting(true)}
+              onClick={() => onApiTesting?.(true)}
             >
               <PlaySolid className={clsx(iconClassName)} />
             </span>

www/packages/docs-ui/src/components/CodeBlock/Header/Wrapper/index.tsx

@@ -0,0 +1,46 @@
+import clsx from "clsx"
+import React, { useMemo } from "react"
+import { useColorMode } from "../../../../providers"
+import { CodeBlockStyle } from "../../../.."
+
+type CodeBlockHeaderWrapperProps = {
+  blockStyle?: CodeBlockStyle
+  children: React.ReactNode
+}
+
+export const CodeBlockHeaderWrapper = React.forwardRef<
+  HTMLDivElement,
+  CodeBlockHeaderWrapperProps
+>(function CodeBlockHeaderWrapper({ children, blockStyle = "loud" }, ref) {
+  const { colorMode } = useColorMode()
+
+  const bgColor = useMemo(
+    () =>
+      clsx(
+        blockStyle === "loud" && "bg-medusa-contrast-bg-base",
+        blockStyle === "subtle" && [
+          colorMode === "light" && "bg-medusa-bg-component",
+          colorMode === "dark" && "bg-medusa-code-bg-header",
+        ]
+      ),
+    [blockStyle, colorMode]
+  )
+
+  return (
+    <div
+      className={clsx(
+        "py-docs_0.5 px-docs_1 mb-0",
+        "rounded-t-docs_lg relative flex justify-between items-center",
+        blockStyle === "subtle" && [
+          "border border-solid border-b-0",
+          colorMode === "light" && "border-medusa-border-base",
+          colorMode === "dark" && "border-medusa-code-border",
+        ],
+        bgColor
+      )}
+      ref={ref}
+    >
+      {children}
+    </div>
+  )
+})

www/packages/docs-ui/src/components/CodeBlock/Header/index.tsx

@@ -6,6 +6,7 @@ import { CodeBlockStyle } from ".."
 import { useColorMode } from "@/providers"
 import { Badge, BadgeVariant } from "@/components"
 import { CodeBlockActions, CodeBlockActionsProps } from "../Actions"
+import { CodeBlockHeaderWrapper } from "./Wrapper"
 
 export type CodeBlockHeaderMeta = {
   badgeLabel?: string
@@ -27,17 +28,6 @@ export const CodeBlockHeader = ({
 }: CodeBlockHeaderProps) => {
   const { colorMode } = useColorMode()
 
-  const bgColor = useMemo(
-    () =>
-      clsx(
-        blockStyle === "loud" && "bg-medusa-contrast-bg-base",
-        blockStyle === "subtle" && [
-          colorMode === "light" && "bg-medusa-bg-component",
-          colorMode === "dark" && "bg-medusa-code-bg-header",
-        ]
-      ),
-    [blockStyle, colorMode]
-  )
   const titleColor = useMemo(
     () =>
       clsx(
@@ -51,18 +41,7 @@ export const CodeBlockHeader = ({
   )
 
   return (
-    <div
-      className={clsx(
-        "py-docs_0.5 px-docs_1 mb-0",
-        "rounded-t-docs_lg relative flex justify-between items-center",
-        blockStyle === "subtle" && [
-          "border border-solid border-b-0",
-          colorMode === "light" && "border-medusa-border-base",
-          colorMode === "dark" && "border-medusa-code-border",
-        ],
-        bgColor
-      )}
-    >
+    <CodeBlockHeaderWrapper blockStyle={blockStyle}>
       <div className={clsx("flex-1", "flex gap-docs_0.75 items-start")}>
         {badgeLabel && (
           <Badge variant={badgeColor || "code"} className="font-base">
@@ -76,6 +55,6 @@ export const CodeBlockHeader = ({
         )}
       </div>
       <CodeBlockActions {...actionsProps} />
-    </div>
+    </CodeBlockHeaderWrapper>
   )
 }

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

@@ -51,6 +51,7 @@ export type CodeBlockProps = {
   collapsed?: boolean
   blockStyle?: CodeBlockStyle
   children?: React.ReactNode
+  style?: React.HTMLAttributes<HTMLDivElement>["style"]
 } & CodeBlockMetaFields &
   Omit<HighlightProps, "code" | "language" | "children">
 
@@ -71,6 +72,7 @@ export const CodeBlock = ({
   collapsibleLines,
   expandButtonLabel,
   isTerminal,
+  style,
   ...rest
 }: CodeBlockProps) => {
   if (!source && typeof children === "string") {
@@ -92,10 +94,14 @@ export const CodeBlock = ({
       : isTerminal
   }, [isTerminal, lang])
   const codeTitle = useMemo(() => {
-    if (title || hasTabs) {
+    if (title) {
       return title
     }
 
+    if (hasTabs) {
+      return ""
+    }
+
     if (isTerminalCode) {
       return "Terminal"
     }
@@ -329,6 +335,7 @@ export const CodeBlock = ({
             !hasInnerCodeBlock && "rounded-docs_DEFAULT",
             className
           )}
+          style={style}
         >
           <Highlight
             theme={codeTheme}
@@ -370,9 +377,6 @@ export const CodeBlock = ({
                     !hasInnerCodeBlock &&
                       tokens.length <= 1 &&
                       "px-docs_1 py-[6px]",
-                    !codeTitle.length &&
-                      (!noCopy || !noReport) &&
-                      "xs:max-w-[83%]",
                     (noLineNumbers ||
                       (tokens.length <= 1 && !isTerminalCode)) &&
                       "pl-docs_1",

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

@@ -10,6 +10,8 @@ import {
   useTabs,
 } from "../.."
 import clsx from "clsx"
+import { CodeBlockActions, CodeBlockActionsProps } from "../CodeBlock/Actions"
+import { CodeBlockHeaderWrapper } from "../CodeBlock/Header/Wrapper"
 
 type CodeTab = BaseTabType & {
   codeProps: CodeBlockProps
@@ -132,6 +134,23 @@ export const CodeTabs = ({
     }
   }, [codeTabSelectorRef, tabRefs, changeTabSelectorCoordinates, selectedTab])
 
+  const actionsProps: CodeBlockActionsProps | undefined = useMemo(() => {
+    if (!selectedTab) {
+      return
+    }
+
+    return {
+      source: selectedTab?.codeProps.source,
+      blockStyle,
+      noReport: selectedTab?.codeProps.noReport,
+      noCopy: selectedTab?.codeProps.noCopy,
+      inInnerCode: true,
+      showGradientBg: false,
+      inHeader: true,
+      isCollapsed: false,
+    }
+  }, [selectedTab])
+
   return (
     <div
       className={clsx(
@@ -142,16 +161,7 @@ export const CodeTabs = ({
         className
       )}
     >
-      <div
-        className={clsx(
-          "flex gap-docs_0.75 relative",
-          "pt-[10px] px-docs_1 pb-px",
-          blockStyle === "loud" &&
-            selectedTab?.codeProps.title &&
-            "border border-solid border-b border-medusa-contrast-border-bot"
-        )}
-        ref={codeTabsWrapperRef}
-      >
+      <CodeBlockHeaderWrapper blockStyle={blockStyle} ref={codeTabsWrapperRef}>
         <span
           className={clsx(
             "xs:absolute xs:transition-all xs:duration-200 xs:ease-ease xs:bottom-0",
@@ -198,7 +208,8 @@ export const CodeTabs = ({
             {selectedTab.codeProps.badgeLabel}
           </Badge>
         )}
-      </div>
+        {actionsProps && <CodeBlockActions {...actionsProps} />}
+      </CodeBlockHeaderWrapper>
       {selectedTab?.codeBlock}
     </div>
   )