docs: fix divider in API reference + clean up layout (medusajs#10861)

* docs: fix divider in API reference + clean up layout * fix build error
Klomgor · Jan 7, 2025 · 936954e · 936954e
1 parent 54a3db7
commit 936954e
Show file tree

Hide file tree

Showing 14 changed files with 120 additions and 113 deletions.
diff --git a/www/apps/api-reference/app/admin/page.tsx b/www/apps/api-reference/app/admin/page.tsx
@@ -3,10 +3,8 @@ import AreaProvider from "@/providers/area"
 import AdminContent from "@/markdown/admin.mdx"
 import Tags from "@/components/Tags"
 import PageTitleProvider from "@/providers/page-title"
-import { H1 } from "docs-ui"
 import { getBaseSpecs } from "../../lib"
 import BaseSpecsProvider from "../../providers/base-specs"
-import clsx from "clsx"
 import React from "react"
 
 const AdminPage = async () => {
@@ -16,15 +14,6 @@ const AdminPage = async () => {
     <BaseSpecsProvider baseSpecs={data}>
       <AreaProvider area={"admin"}>
         <PageTitleProvider>
-          <H1
-            className={clsx(
-              "!h2-docs lg:pl-4",
-              "scroll-m-[184px] lg:scroll-m-[264px]"
-            )}
-            id="introduction"
-          >
-            Medusa V2 Admin API Reference
-          </H1>
           {/* @ts-ignore React v19 doesn't see MDX as valid component */}
           <AdminContent />
           <Tags tags={data?.tags} />

diff --git a/www/apps/api-reference/app/store/page.tsx b/www/apps/api-reference/app/store/page.tsx
@@ -3,10 +3,8 @@ import AreaProvider from "@/providers/area"
 import StoreContent from "@/markdown/store.mdx"
 import Tags from "@/components/Tags"
 import PageTitleProvider from "@/providers/page-title"
-import { H1 } from "docs-ui"
 import { getBaseSpecs } from "../../lib"
 import BaseSpecsProvider from "../../providers/base-specs"
-import clsx from "clsx"
 
 const StorePage = async () => {
   const data = await getBaseSpecs("store")
@@ -15,15 +13,6 @@ const StorePage = async () => {
     <BaseSpecsProvider baseSpecs={data}>
       <AreaProvider area={"store"}>
         <PageTitleProvider>
-          <H1
-            className={clsx(
-              "!h2-docs lg:pl-4",
-              "scroll-m-[184px] lg:scroll-m-[264px]"
-            )}
-            id="introduction"
-          >
-            Medusa V2 Store API Reference
-          </H1>
           {/* @ts-ignore React v19 doesn't see MDX as valid component */}
           <StoreContent />
           <Tags tags={data?.tags} />

diff --git a/www/apps/api-reference/components/Section/Container/index.tsx b/www/apps/api-reference/components/Section/Container/index.tsx
@@ -1,27 +1,31 @@
 import clsx from "clsx"
 import SectionDivider from "../Divider"
 import { forwardRef } from "react"
+import { WideSection } from "docs-ui"
 
 type SectionContainerProps = {
   children: React.ReactNode
   noTopPadding?: boolean
   noDivider?: boolean
+  className?: string
 }
 
 const SectionContainer = forwardRef<HTMLDivElement, SectionContainerProps>(
   function SectionContainer(
-    { children, noTopPadding = false, noDivider = false },
+    { children, noTopPadding = false, noDivider = false, className },
     ref
   ) {
     return (
       <div
-        className={clsx("relative pb-4 md:pb-7", !noTopPadding && "pt-7")}
         ref={ref}
-      >
-        {children}
-        {!noDivider && (
-          <SectionDivider className="-left-[16px] lg:!-left-1/4" />
+        className={clsx(
+          "relative pb-4 md:pb-7",
+          !noTopPadding && "pt-7",
+          className
         )}
+      >
+        <WideSection>{children}</WideSection>
+        {!noDivider && <SectionDivider />}
       </div>
     )
   }

diff --git a/www/apps/api-reference/components/Section/Divider/index.tsx b/www/apps/api-reference/components/Section/Divider/index.tsx
@@ -7,10 +7,7 @@ type SectionDividerProps = {
 const SectionDivider = ({ className }: SectionDividerProps) => {
   return (
     <hr
-      className={clsx(
-        "absolute bottom-0 -left-1.5 z-0 m-0 w-screen lg:left-0",
-        className
-      )}
+      className={clsx("absolute bottom-0 z-0 m-0 w-screen left-0", className)}
     />
   )
 }

diff --git a/www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx b/www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx
@@ -8,7 +8,7 @@ import dynamic from "next/dynamic"
 import TagsOperationDescriptionSectionParameters from "./Parameters"
 import MDXContentClient from "@/components/MDXContent/Client"
 import { useArea } from "../../../../providers/area"
-import { Feedback, Badge, Link, FeatureFlagNotice } from "docs-ui"
+import { Feedback, Badge, Link, FeatureFlagNotice, H2 } from "docs-ui"
 import { usePathname } from "next/navigation"
 import { TagsOperationDescriptionSectionWorkflowBadgeProps } from "./WorkflowBadge"
 
@@ -43,7 +43,7 @@ const TagsOperationDescriptionSection = ({
 
   return (
     <>
-      <h2>
+      <H2>
         {operation.summary}
         {operation.deprecated && (
           <Badge variant="orange" className="ml-0.5">
@@ -57,7 +57,7 @@ const TagsOperationDescriptionSection = ({
             badgeClassName="ml-0.5"
           />
         )}
-      </h2>
+      </H2>
       <div className="my-1">
         <MDXContentClient content={operation.description} />
       </div>

diff --git a/www/apps/api-reference/components/Tags/Operation/index.tsx b/www/apps/api-reference/components/Tags/Operation/index.tsx
@@ -18,9 +18,9 @@ import TagsOperationDescriptionSection from "./DescriptionSection"
 import DividedLayout from "@/layouts/Divided"
 import { useLoading } from "@/providers/loading"
 import { useRouter } from "next/navigation"
-import SectionDivider from "../../Section/Divider"
 import checkElementInViewport from "../../../utils/check-element-in-viewport"
 import DividedLoading from "../../DividedLoading"
+import SectionContainer from "../../Section/Container"
 
 const TagOperationCodeSection = dynamic<TagOperationCodeSectionProps>(
   async () => import("./CodeSection")
@@ -116,7 +116,7 @@ const TagOperation = ({
         }
       }}
     >
-      <div
+      <SectionContainer
         ref={nodeRef}
         className={clsx("relative min-h-screen w-full pb-7", className)}
       >
@@ -144,8 +144,7 @@ const TagOperation = ({
             />
           </div>
         )}
-        <SectionDivider className="-left-[16px] lg:!-left-1/4" />
-      </div>
+      </SectionContainer>
     </InView>
   )
 }

diff --git a/www/apps/api-reference/components/Tags/Section/Schema/index.tsx b/www/apps/api-reference/components/Tags/Section/Schema/index.tsx
@@ -124,32 +124,34 @@ const TagSectionSchema = ({ schema, tagName }: TagSectionSchemaProps) => {
         root={root}
         threshold={0.1}
       >
-        <DividedLayout
-          mainContent={
-            <SectionContainer ref={paramsRef}>
-              <h2>{formattedName} Object</h2>
-              <h4 className="border-medusa-border-base border-b py-1.5 mt-2">
-                Fields
-              </h4>
-              <TagOperationParameters schemaObject={schema} topLevel={true} />
-            </SectionContainer>
-          }
-          codeContent={
-            <SectionContainer noDivider>
-              {examples.length && (
-                <CodeBlock
-                  source={examples[0].content}
-                  lang="json"
-                  title={`The ${formattedName} Object`}
-                  className={clsx("overflow-auto")}
-                  style={{
-                    maxHeight: "100vh",
-                  }}
-                />
-              )}
-            </SectionContainer>
-          }
-        />
+        <SectionContainer ref={paramsRef}>
+          <DividedLayout
+            mainContent={
+              <div>
+                <h2>{formattedName} Object</h2>
+                <h4 className="border-medusa-border-base border-b py-1.5 mt-2">
+                  Fields
+                </h4>
+                <TagOperationParameters schemaObject={schema} topLevel={true} />
+              </div>
+            }
+            codeContent={
+              <>
+                {examples.length && (
+                  <CodeBlock
+                    source={examples[0].content}
+                    lang="json"
+                    title={`The ${formattedName} Object`}
+                    className={clsx("overflow-auto")}
+                    style={{
+                      maxHeight: "100vh",
+                    }}
+                  />
+                )}
+              </>
+            }
+          />
+        </SectionContainer>
       </InView>
     </Suspense>
   )

diff --git a/www/apps/api-reference/components/Tags/Section/index.tsx b/www/apps/api-reference/components/Tags/Section/index.tsx
@@ -4,6 +4,7 @@ import getSectionId from "@/utils/get-section-id"
 import { InView } from "react-intersection-observer"
 import { useEffect, useMemo, useState } from "react"
 import {
+  H2,
   isElmWindow,
   swrFetcher,
   useIsBrowser,
@@ -135,43 +136,44 @@ const TagSectionComponent = ({ tag }: TagSectionProps) => {
         }
       }}
     >
-      <DividedLayout
-        mainContent={
-          <SectionContainer noDivider={true}>
-            <h2>{tag.name}</h2>
-            {tag.description && (
-              <Section>
-                <MDXContentClient
-                  content={tag.description}
-                  scope={{
-                    addToSidebar: false,
-                  }}
-                />
-              </Section>
-            )}
-            {tag.externalDocs && (
-              <p className="mt-1">
-                <span className="text-medium-plus">Related guide:</span>{" "}
-                <Link href={tag.externalDocs.url} target="_blank">
-                  {tag.externalDocs.description || "Read More"}
-                </Link>
-              </p>
-            )}
-            <Feedback
-              event="survey_api-ref"
-              extraData={{
-                area,
-                section: tag.name,
-              }}
-              pathName={pathname}
-              vertical
-              question="Was this section helpful?"
-            />
-            <SectionDivider className="-left-[16px] lg:!-left-[30%]" />
-          </SectionContainer>
-        }
-        codeContent={<></>}
-      />
+      <SectionContainer>
+        <DividedLayout
+          mainContent={
+            <div>
+              <H2>{tag.name}</H2>
+              {tag.description && (
+                <Section>
+                  <MDXContentClient
+                    content={tag.description}
+                    scope={{
+                      addToSidebar: false,
+                    }}
+                  />
+                </Section>
+              )}
+              {tag.externalDocs && (
+                <p className="mt-1">
+                  <span className="text-medium-plus">Related guide:</span>{" "}
+                  <Link href={tag.externalDocs.url} target="_blank">
+                    {tag.externalDocs.description || "Read More"}
+                  </Link>
+                </p>
+              )}
+              <Feedback
+                event="survey_api-ref"
+                extraData={{
+                  area,
+                  section: tag.name,
+                }}
+                pathName={pathname}
+                vertical
+                question="Was this section helpful?"
+              />
+            </div>
+          }
+          codeContent={<></>}
+        />
+      </SectionContainer>
       {schemaData && (
         <TagSectionSchema schema={schemaData.schema} tagName={tag.name} />
       )}

diff --git a/www/apps/api-reference/layouts/DividedMarkdown/index.tsx b/www/apps/api-reference/layouts/DividedMarkdown/index.tsx
@@ -12,8 +12,8 @@ const DividedMarkdownLayout = ({
   const childArr = React.isValidElement(children)
     ? [children]
     : Array.isArray(children)
-    ? children
-    : []
+      ? children
+      : []
 
   if (!childArr.length) {
     return <></>

diff --git a/www/apps/api-reference/markdown/admin.mdx b/www/apps/api-reference/markdown/admin.mdx
@@ -1,4 +1,4 @@
-import { Feedback, CodeTabs, CodeTab } from "docs-ui"
+import { Feedback, CodeTabs, CodeTab, H1 } from "docs-ui"
 import SectionContainer from "@/components/Section/Container"
 import DividedMarkdownLayout from "@/layouts/DividedMarkdown"
 import { 
@@ -17,6 +17,8 @@ import ClientLibraries from "./client-libraries.mdx"
 
 <DividedMarkdownContent>
 
+<H1 className={"!h2-docs scroll-m-[184px] lg:scroll-m-[264px]"} id="introduction">Medusa V2 Admin API Reference</H1>
+
 This API reference includes Medusa v2's Admin APIs, which are REST APIs exposed by the Medusa application. They are used to perform admin functionalities or create an admin dashboard to access and manipulate your commerce store's data.
 
 All API Routes are prefixed with `/admin`. So, during development, the API Routes will be available under the path `http://localhost:9000/admin`. For production, replace `http://localhost:9000` with your Medusa application URL.

diff --git a/www/apps/api-reference/markdown/store.mdx b/www/apps/api-reference/markdown/store.mdx
@@ -5,7 +5,7 @@ import {
   DividedMarkdownCode
 } from "@/layouts/DividedMarkdown/Sections"
 import Section from "@/components/Section"
-import { Feedback, CodeTabs, CodeTab } from "docs-ui"
+import { Feedback, CodeTabs, CodeTab, H1 } from "docs-ui"
 
 import ClientLibraries from "./client-libraries.mdx"
 
@@ -17,6 +17,8 @@ import ClientLibraries from "./client-libraries.mdx"
 
 <DividedMarkdownContent>
 
+<H1 className={"!h2-docs scroll-m-[184px] lg:scroll-m-[264px]"} id="introduction">Medusa V2 Store API Reference</H1>
+
 This API reference includes Medusa v2's Store APIs, which are REST APIs exposed by the Medusa application. They are used to create a storefront for your commerce store, such as a webshop or a commerce mobile app.
 
 All API Routes are prefixed with `/store`. So, during development, the API Routes will be available under the path `http://localhost:9000/store`. For production, replace `http://localhost:9000` with your Medusa application URL.

diff --git a/www/packages/docs-ui/src/components/WideSection/index.tsx b/www/packages/docs-ui/src/components/WideSection/index.tsx
@@ -0,0 +1,25 @@
+import React from "react"
+import clsx from "clsx"
+
+type WideSectionProps = React.AllHTMLAttributes<HTMLElement> & {
+  as?: "div" | "main"
+}
+
+export const WideSection = ({
+  children,
+  className,
+  as = "div",
+}: WideSectionProps) => {
+  const Component = as
+  return (
+    <Component
+      className={clsx(
+        "max-w-inner-content-xs sm:max-w-inner-content-sm md:max-w-inner-content-md",
+        "lg:max-w-lg-wide-content xl:max-w-xl-wide-content px-1 lg:px-0 mx-auto",
+        className
+      )}
+    >
+      {children}
+    </Component>
+  )
+}
diff --git a/www/packages/docs-ui/src/components/index.ts b/www/packages/docs-ui/src/components/index.ts
@@ -74,5 +74,6 @@ export * from "./Toggle"
 export * from "./Tooltip"
 export * from "./TypeList"
 export * from "./VerticalCodeTabs"
+export * from "./WideSection"
 export * from "./WorkflowDiagram"
 export * from "./ZoomImg"