asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: improvements to API reference intro sections (#9397)

Browse Source 
- Improve intro sections of API reference to utilize divided columns
- Improve the content of the intro sections
- Add a new Workflows section to explain the workflows badge and how to use it
- Fixes to headings and add anchor for copying the link to a section
- Fixes responsiveness of intro sections on mobile devices
- Other: fix loading not showing when a sidebar category is opened.

Closes DOCS-932, DOCS-934, DOCS-937

Preview: https://api-reference-v2-git-docs-api-ref-intro-fixes-medusajs.vercel.app/v2/api/store
This commit is contained in:
Shahed Nasser
2024-10-06 16:51:08 +00:00
committed by GitHub
parent d6b452b734
commit 522d3ce764
27 changed files with 1138 additions and 284 deletions
Download Patch File Download Diff File Expand all files Collapse all files
www/packages/docs-ui/src/components/Heading/H1/index.tsx
+19
View File
@@ -0,0 +1,19 @@
import clsx from "clsx"
import React from "react"
type H1Props = React.HTMLAttributes<HTMLHeadingElement> & {
id?: string
}
export const H1 = ({ className, ...props }: H1Props) => {
return (
<h1
className={clsx(
"h1-docs [&_code]:!h1-docs [&_code]:!font-mono mb-docs_1 text-medusa-fg-base",
props.id && "scroll-m-56",
className
)}
{...props}
/>
)
}
www/packages/docs-ui/src/components/Heading/H2/index.tsx
+32
View File
@@ -0,0 +1,32 @@
import clsx from "clsx"
import React from "react"
import { Link } from "@/components"
type H2Props = React.HTMLAttributes<HTMLHeadingElement> & {
id?: string
passRef?: React.RefObject<HTMLHeadingElement>
}
export const H2 = ({ className, children, passRef, ...props }: H2Props) => {
return (
<h2
className={clsx(
"h2-docs [&_code]:!h2-docs [&_code]:!font-mono mb-docs_1 mt-docs_4 text-medusa-fg-base",
props.id && "group/h2 scroll-m-56",
className
)}
{...props}
ref={passRef}
>
{children}
{props.id && (
<Link
href={`#${props.id}`}
className="opacity-0 group-hover/h2:opacity-100 transition-opacity ml-docs_0.5 inline-block"
>
#
</Link>
)}
</h2>
)
}
www/packages/docs-ui/src/components/Heading/H3/index.tsx
+30
View File
@@ -0,0 +1,30 @@
import clsx from "clsx"
import React from "react"
import { Link } from "@/components"
type H3Props = React.HTMLAttributes<HTMLHeadingElement> & {
id?: string
}
export const H3 = ({ className, children, ...props }: H3Props) => {
return (
<h3
className={clsx(
"h3-docs [&_code]:!h3-docs [&_code]:!font-mono mb-docs_0.5 mt-docs_3 text-medusa-fg-base",
props.id && "group/h3 scroll-m-56",
className
)}
{...props}
>
{children}
{props.id && (
<Link
href={`#${props.id}`}
className="opacity-0 group-hover/h3:opacity-100 transition-opacity ml-docs_0.5 inline-block"
>
#
</Link>
)}
</h3>
)
}
www/packages/docs-ui/src/components/Heading/H4/index.tsx
+14
View File
@@ -0,0 +1,14 @@
import clsx from "clsx"
import React from "react"
export const H4 = ({
className,
...props
}: React.HTMLAttributes<HTMLHeadingElement>) => {
return (
<h4
className={clsx("mb-docs_0.5 text-medusa-fg-base text-h4", className)}
{...props}
/>
)
}
www/packages/docs-ui/src/components/Heading/index.tsx
+4
View File
@@ -0,0 +1,4 @@
export * from "./H1"
export * from "./H2"
export * from "./H3"
export * from "./H4"
www/packages/docs-ui/src/components/MDXComponents/index.tsx
+8 -73
View File
@@ -10,7 +10,10 @@ import {
DetailsSummary,
DetailsProps,
ZoomImg,
Link,
H1,
H2,
H3,
H4,
} from "@/components"
import clsx from "clsx"
import { Text } from "@medusajs/ui"
@@ -27,78 +30,10 @@ export const MDXComponents: MDXComponentsType = {
Summary: DetailsSummary,
Card,
CardList,
h1: ({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>) => {
return (
<h1
className={clsx(
"h1-docs [&_code]:!h1-docs [&_code]:!font-mono mb-docs_1 text-medusa-fg-base",
props.id && "scroll-m-56",
className
)}
{...props}
/>
)
},
h2: ({
className,
children,
...props
}: React.HTMLAttributes<HTMLHeadingElement>) => {
return (
<h2
className={clsx(
"h2-docs [&_code]:!h2-docs [&_code]:!font-mono mb-docs_1 mt-docs_4 text-medusa-fg-base",
props.id && "group/h2 scroll-m-56",
className
)}
{...props}
>
{children}
{props.id && (
<Link
href={`#${props.id}`}
className="opacity-0 group-hover/h2:opacity-100 transition-opacity ml-docs_0.5 inline-block"
>
#
</Link>
)}
</h2>
)
},
h3: ({
className,
children,
...props
}: React.HTMLAttributes<HTMLHeadingElement>) => {
return (
<h3
className={clsx(
"h3-docs [&_code]:!h3-docs [&_code]:!font-mono mb-docs_0.5 mt-docs_3 text-medusa-fg-base",
props.id && "group/h3 scroll-m-56",
className
)}
{...props}
>
{children}
{props.id && (
<Link
href={`#${props.id}`}
className="opacity-0 group-hover/h3:opacity-100 transition-opacity ml-docs_0.5 inline-block"
>
#
</Link>
)}
</h3>
)
},
h4: ({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>) => {
return (
<h4
className={clsx("mb-docs_0.5 text-medusa-fg-base text-h4", className)}
{...props}
/>
)
},
h1: H1,
h2: H2,
h3: H3,
h4: H4,
p: ({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>) => {
return (
<p
www/packages/docs-ui/src/components/Sidebar/Item/Category/index.tsx
+7 -4
View File
@@ -29,18 +29,21 @@ export const SidebarItemCategory = ({
getPersistedCategoryState,
persistState,
} = useSidebar()
const itemShowLoading = useMemo(() => {
return !item.loaded || (item.showLoadingIfEmpty && !item.children?.length)
}, [item])
useEffect(() => {
if (open && !item.loaded) {
if (open && itemShowLoading) {
setShowLoading(true)
}
}, [open])
}, [open, itemShowLoading])
useEffect(() => {
if (item.loaded && showLoading) {
if (!itemShowLoading && showLoading) {
setShowLoading(false)
}
}, [item])
}, [itemShowLoading, showLoading])
useEffect(() => {
const isActive = isChildrenActive(item)
www/packages/docs-ui/src/components/index.ts
+1
View File
@@ -24,6 +24,7 @@ export * from "./ExpandableNotice"
export * from "./FeatureFlagNotice"
export * from "./Feedback"
export * from "./Feedback/Solutions"
export * from "./Heading"
export * from "./HooksLoader"
export * from "./Icons"
export * from "./InlineIcon"
www/packages/docs-ui/src/hooks/use-active-on-scroll/index.tsx
+14 -1
View File
@@ -14,12 +14,14 @@ export type UseActiveOnScrollProps = {
rootElm?: Document | HTMLElement
enable?: boolean
useDefaultIfNoActive?: boolean
maxLevel?: number
}
export const useActiveOnScroll = ({
rootElm,
enable = true,
useDefaultIfNoActive = true,
maxLevel = 3,
}: UseActiveOnScrollProps) => {
const [items, setItems] = useState<ActiveOnScrollItem[]>([])
const [activeItemId, setActiveItemId] = useState("")
@@ -40,12 +42,23 @@ export const useActiveOnScroll = ({
return document
}, [rootElm, isBrowser, enable])
const querySelector = useMemo(() => {
let selector = ""
for (let i = 2; i <= maxLevel; i++) {
if (i > 2) {
selector += `,`
}
selector += `h${i}`
}
return selector
}, [maxLevel])
const getHeadingsInElm = useCallback(() => {
if (!isBrowser || !enable) {
return []
}
return root?.querySelectorAll("h2,h3")
return root?.querySelectorAll(querySelector)
}, [isBrowser, pathname, root, enable])
const setHeadingItems = useCallback(() => {
if (!enable) {
www/packages/docs-ui/src/layouts/main-content.tsx
+4 -1
View File
@@ -7,6 +7,7 @@ import { Bannerv2, MainNav, useIsBrowser } from ".."
export type MainContentLayoutProps = {
mainWrapperClasses?: string
contentClassName?: string
showBanner?: boolean
children: React.ReactNode
}
@@ -15,6 +16,7 @@ export const MainContentLayout = ({
children,
mainWrapperClasses,
showBanner = true,
contentClassName,
}: MainContentLayoutProps) => {
const { isBrowser } = useIsBrowser()
const { desktopSidebarOpen } = useSidebar()
@@ -57,7 +59,8 @@ export const MainContentLayout = ({
<div
className={clsx(
"flex justify-center",
"pt-docs_4 lg:pt-docs_6 pb-docs_8 lg:pb-docs_4"
"pt-docs_4 lg:pt-docs_6 pb-docs_8 lg:pb-docs_4",
contentClassName
)}
>
{children}
www/packages/docs-ui/src/layouts/wide.tsx
+1
View File
@@ -14,6 +14,7 @@ export const WideLayout = ({
<RootLayout
{...props}
mainWrapperClasses={clsx(props.mainWrapperClasses, "mx-auto flex")}
contentClassName="w-full px-1"
>
<main
className={clsx(