From 936954e0b4c7814c3d86900eb7b2317cd2a7e6e5 Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Tue, 7 Jan 2025 14:59:39 +0200 Subject: [PATCH] docs: fix divider in API reference + clean up layout (#10861) * docs: fix divider in API reference + clean up layout * fix build error --- www/apps/api-reference/app/admin/page.tsx | 11 --- www/apps/api-reference/app/store/page.tsx | 11 --- .../components/Section/Container/index.tsx | 16 ++-- .../components/Section/Divider/index.tsx | 5 +- .../Operation/DescriptionSection/index.tsx | 6 +- .../components/Tags/Operation/index.tsx | 7 +- .../components/Tags/Section/Schema/index.tsx | 54 ++++++------- .../components/Tags/Section/index.tsx | 76 ++++++++++--------- .../layouts/DividedMarkdown/index.tsx | 4 +- www/apps/api-reference/markdown/admin.mdx | 4 +- www/apps/api-reference/markdown/store.mdx | 4 +- .../src/components/WideSection/index.tsx | 25 ++++++ www/packages/docs-ui/src/components/index.ts | 1 + www/packages/docs-ui/src/layouts/wide.tsx | 9 +-- 14 files changed, 120 insertions(+), 113 deletions(-) create mode 100644 www/packages/docs-ui/src/components/WideSection/index.tsx diff --git a/www/apps/api-reference/app/admin/page.tsx b/www/apps/api-reference/app/admin/page.tsx index e6958853cc..8e21e80339 100644 --- 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 () => { -

- Medusa V2 Admin API Reference -

{/* @ts-ignore React v19 doesn't see MDX as valid component */} diff --git a/www/apps/api-reference/app/store/page.tsx b/www/apps/api-reference/app/store/page.tsx index 7ea33394d5..4b2ea8ff70 100644 --- 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 () => { -

- Medusa V2 Store API Reference -

{/* @ts-ignore React v19 doesn't see MDX as valid component */} diff --git a/www/apps/api-reference/components/Section/Container/index.tsx b/www/apps/api-reference/components/Section/Container/index.tsx index 9de1251bed..6775e13445 100644 --- 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( function SectionContainer( - { children, noTopPadding = false, noDivider = false }, + { children, noTopPadding = false, noDivider = false, className }, ref ) { return (
- {children} - {!noDivider && ( - + className={clsx( + "relative pb-4 md:pb-7", + !noTopPadding && "pt-7", + className )} + > + {children} + {!noDivider && }
) } diff --git a/www/apps/api-reference/components/Section/Divider/index.tsx b/www/apps/api-reference/components/Section/Divider/index.tsx index c58791662f..2119d3ac6e 100644 --- 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 (
) } diff --git a/www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx b/www/apps/api-reference/components/Tags/Operation/DescriptionSection/index.tsx index 995a6fecb3..396b1ecda8 100644 --- 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 ( <> -

+

{operation.summary} {operation.deprecated && ( @@ -57,7 +57,7 @@ const TagsOperationDescriptionSection = ({ badgeClassName="ml-0.5" /> )} -

+
diff --git a/www/apps/api-reference/components/Tags/Operation/index.tsx b/www/apps/api-reference/components/Tags/Operation/index.tsx index 1dd618621d..02ef1ca8a8 100644 --- 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( async () => import("./CodeSection") @@ -116,7 +116,7 @@ const TagOperation = ({ } }} > -
@@ -144,8 +144,7 @@ const TagOperation = ({ />
)} - - + ) } diff --git a/www/apps/api-reference/components/Tags/Section/Schema/index.tsx b/www/apps/api-reference/components/Tags/Section/Schema/index.tsx index ffdd2885ae..ff3e06eb0c 100644 --- 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} > - -

{formattedName} Object

-

- Fields -

- - - } - codeContent={ - - {examples.length && ( - - )} - - } - /> + + +

{formattedName} Object

+

+ Fields +

+ + + } + codeContent={ + <> + {examples.length && ( + + )} + + } + /> + ) diff --git a/www/apps/api-reference/components/Tags/Section/index.tsx b/www/apps/api-reference/components/Tags/Section/index.tsx index ecfbd777d8..1af2397587 100644 --- 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) => { } }} > - -

{tag.name}

- {tag.description && ( -
- -
- )} - {tag.externalDocs && ( -

- Related guide:{" "} - - {tag.externalDocs.description || "Read More"} - -

- )} - - - - } - codeContent={<>} - /> + + +

{tag.name}

+ {tag.description && ( +
+ +
+ )} + {tag.externalDocs && ( +

+ Related guide:{" "} + + {tag.externalDocs.description || "Read More"} + +

+ )} + + + } + codeContent={<>} + /> + {schemaData && ( )} diff --git a/www/apps/api-reference/layouts/DividedMarkdown/index.tsx b/www/apps/api-reference/layouts/DividedMarkdown/index.tsx index dd3960c8ad..d25b977d21 100644 --- 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 index eb8f3eb6b7..10b670564c 100644 --- 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" +

Medusa V2 Admin API Reference

+ 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 index a68dc51cc7..bfbfb45de1 100644 --- 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" +

Medusa V2 Store API Reference

+ 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 new file mode 100644 index 0000000000..6fd749c077 --- /dev/null +++ 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 & { + as?: "div" | "main" +} + +export const WideSection = ({ + children, + className, + as = "div", +}: WideSectionProps) => { + const Component = as + return ( + + {children} + + ) +} diff --git a/www/packages/docs-ui/src/components/index.ts b/www/packages/docs-ui/src/components/index.ts index 91bf299c1e..7c2fdef9b6 100644 --- 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" diff --git a/www/packages/docs-ui/src/layouts/wide.tsx b/www/packages/docs-ui/src/layouts/wide.tsx index 605bae7d7d..55ea74be47 100644 --- a/www/packages/docs-ui/src/layouts/wide.tsx +++ b/www/packages/docs-ui/src/layouts/wide.tsx @@ -15,14 +15,9 @@ export const WideLayout = ({ -
+
{showBreadcrumbs && } {children} {feedbackComponent}