docs: prep for v2 documentation (#6710)
This PR includes documentation that preps for v2 docs (but doesn't introduce new docs). _Note: The number of file changes in the PR is due to find-and-replace within the `references` which is unavoidable. Let me know if I should move it to another PR._ ## Changes - Change Medusa version in base OAS used for v2. - Fix to docblock generator related to not catching all path parameters. - Added typedoc plugin that generates ER Diagrams, which will be used specifically for data model references in commerce modules. - Changed OAS tool to output references in `www/apps/api-reference/specs-v2` directory when the `--v2` option is used. - Added a version switcher to the API reference to switch between V1 and V2. This switcher is enabled by an environment variable, so it won't be visible/usable at the moment. - Upgraded docusaurus to v3.0.1 - Added new Vale rules to ensure correct spelling of Medusa Admin and module names. - Added new components to the `docs-ui` package that will be used in future documentation changes.
This commit is contained in:
Shahed Nasser
@@ -1,17 +1,21 @@
|
||||
"use client"
|
||||
|
||||
// @refresh reset
|
||||
|
||||
import React, { useEffect, useMemo, useRef, useState } from "react"
|
||||
import type { SidebarItemType } from "@/providers"
|
||||
import { useSidebar } from "@/providers"
|
||||
import clsx from "clsx"
|
||||
import Link from "next/link"
|
||||
import { checkSidebarItemVisibility } from "@/utils"
|
||||
import { Loading } from "@/components"
|
||||
import { SidebarItemType } from "types"
|
||||
|
||||
export type SidebarItemProps = {
|
||||
item: SidebarItemType
|
||||
nested?: boolean
|
||||
expandItems?: boolean
|
||||
currentLevel?: number
|
||||
isSidebarTitle?: boolean
|
||||
} & React.AllHTMLAttributes<HTMLLIElement>
|
||||
|
||||
export const SidebarItem = ({
|
||||
@@ -19,9 +23,16 @@ export const SidebarItem = ({
|
||||
nested = false,
|
||||
expandItems = false,
|
||||
className,
|
||||
currentLevel = 1,
|
||||
}: SidebarItemProps) => {
|
||||
const [showLoading, setShowLoading] = useState(false)
|
||||
const { isItemActive, setMobileSidebarOpen: setSidebarOpen } = useSidebar()
|
||||
const {
|
||||
isItemActive,
|
||||
setMobileSidebarOpen: setSidebarOpen,
|
||||
disableActiveTransition,
|
||||
noTitleStyling,
|
||||
sidebarRef,
|
||||
} = useSidebar()
|
||||
const active = useMemo(
|
||||
() => isItemActive(item, nested),
|
||||
[isItemActive, item, nested]
|
||||
@@ -29,49 +40,106 @@ export const SidebarItem = ({
|
||||
const collapsed = !expandItems && !isItemActive(item, true)
|
||||
const ref = useRef<HTMLLIElement>(null)
|
||||
|
||||
const itemChildren = useMemo(() => {
|
||||
return item.isChildSidebar ? undefined : item.children
|
||||
}, [item])
|
||||
const canHaveTitleStyling = useMemo(
|
||||
() =>
|
||||
item.hasTitleStyling ||
|
||||
((itemChildren?.length || !item.loaded) && !noTitleStyling && !nested),
|
||||
[itemChildren, noTitleStyling, item, nested]
|
||||
)
|
||||
|
||||
const classNames = useMemo(
|
||||
() =>
|
||||
clsx(
|
||||
"flex items-center justify-between gap-docs_0.5 rounded-docs_sm px-docs_0.5 py-[6px] hover:no-underline",
|
||||
"border",
|
||||
!canHaveTitleStyling && "text-compact-small-plus text-medusa-fg-subtle",
|
||||
canHaveTitleStyling &&
|
||||
"text-compact-x-small-plus text-medusa-fg-muted uppercase",
|
||||
item.path !== undefined &&
|
||||
active && ["!text-medusa-fg-base bg-medusa-bg-base-pressed"],
|
||||
(item.path === undefined || !active) && "border-transparent",
|
||||
item.path !== undefined && active && " border-medusa-border-base",
|
||||
item.path !== undefined &&
|
||||
!active &&
|
||||
"hover:bg-medusa-bg-base-hover border-transparent"
|
||||
),
|
||||
[canHaveTitleStyling, active, item.path]
|
||||
)
|
||||
|
||||
/**
|
||||
* Tries to place the item in the center of the sidebar
|
||||
*/
|
||||
const newTopCalculator = (): number => {
|
||||
if (!sidebarRef.current || !ref.current) {
|
||||
return 0
|
||||
}
|
||||
const sidebarBoundingRect = sidebarRef.current.getBoundingClientRect()
|
||||
const sidebarHalf = sidebarBoundingRect.height / 2
|
||||
const itemTop = ref.current.offsetTop
|
||||
const itemBottom =
|
||||
itemTop + (ref.current.children.item(0) as HTMLElement)?.clientHeight
|
||||
|
||||
// try deducting half
|
||||
let newTop = itemTop - sidebarHalf
|
||||
let newBottom = newTop + sidebarBoundingRect.height
|
||||
if (newTop <= itemTop && newBottom >= itemBottom) {
|
||||
return newTop
|
||||
}
|
||||
|
||||
// try adding half
|
||||
newTop = itemTop + sidebarHalf
|
||||
newBottom = newTop + sidebarBoundingRect.height
|
||||
if (newTop <= itemTop && newBottom >= itemBottom) {
|
||||
return newTop
|
||||
}
|
||||
|
||||
//return the item's top minus some top margin
|
||||
return itemTop - sidebarBoundingRect.top
|
||||
}
|
||||
|
||||
useEffect(() => {
|
||||
if (active && ref.current && window.innerWidth >= 1025) {
|
||||
if (
|
||||
active &&
|
||||
ref.current &&
|
||||
sidebarRef.current &&
|
||||
window.innerWidth >= 1025
|
||||
) {
|
||||
if (
|
||||
!checkSidebarItemVisibility(ref.current, {
|
||||
topMargin: 57,
|
||||
})
|
||||
!disableActiveTransition &&
|
||||
!checkSidebarItemVisibility(
|
||||
(ref.current.children.item(0) as HTMLElement) || ref.current,
|
||||
!disableActiveTransition
|
||||
)
|
||||
) {
|
||||
// scroll to element
|
||||
ref.current.scrollIntoView({
|
||||
block: "center",
|
||||
})
|
||||
} else if (disableActiveTransition) {
|
||||
sidebarRef.current.scrollTo({
|
||||
top: newTopCalculator(),
|
||||
})
|
||||
}
|
||||
}
|
||||
if (active) {
|
||||
setShowLoading(true)
|
||||
}
|
||||
}, [active])
|
||||
|
||||
const classNames = useMemo(
|
||||
() =>
|
||||
clsx(
|
||||
"flex items-center justify-between gap-docs_0.5 rounded-docs_sm px-docs_0.5 py-[6px] hover:no-underline",
|
||||
!item.children && "text-compact-small-plus text-medusa-fg-subtle",
|
||||
item.children &&
|
||||
"text-compact-x-small-plus text-medusa-fg-muted uppercase",
|
||||
item.path !== undefined &&
|
||||
active && ["!text-medusa-fg-base bg-medusa-bg-base-pressed"],
|
||||
item.path !== undefined && active && "border border-medusa-border-base",
|
||||
item.path !== undefined &&
|
||||
!active &&
|
||||
"hover:bg-medusa-bg-base-hover border-transparent"
|
||||
),
|
||||
[item.children, active, item.path]
|
||||
)
|
||||
}, [active, sidebarRef.current, disableActiveTransition])
|
||||
|
||||
return (
|
||||
<li
|
||||
className={clsx(
|
||||
item.children && !collapsed && "my-docs_1.5",
|
||||
!item.children && !nested && active && "mt-docs_1.5",
|
||||
canHaveTitleStyling && !collapsed && "my-docs_1.5",
|
||||
!canHaveTitleStyling &&
|
||||
!nested &&
|
||||
active &&
|
||||
!disableActiveTransition &&
|
||||
"mt-docs_1.5",
|
||||
!expandItems &&
|
||||
((item.children && !collapsed) ||
|
||||
(!item.children && !nested && active)) &&
|
||||
((canHaveTitleStyling && !collapsed) ||
|
||||
(!canHaveTitleStyling && !nested && active)) &&
|
||||
"-translate-y-docs_1 transition-transform",
|
||||
className
|
||||
)}
|
||||
@@ -93,17 +161,20 @@ export const SidebarItem = ({
|
||||
setSidebarOpen(false)
|
||||
}
|
||||
}}
|
||||
replace
|
||||
shallow
|
||||
replace={!item.isPathHref}
|
||||
shallow={!item.isPathHref}
|
||||
{...item.linkProps}
|
||||
>
|
||||
<span>{item.title}</span>
|
||||
{item.additionalElms}
|
||||
</Link>
|
||||
)}
|
||||
{item.children && (
|
||||
{itemChildren && (
|
||||
<ul
|
||||
className={clsx("ease-ease overflow-hidden", collapsed && "m-0 h-0")}
|
||||
style={{
|
||||
paddingLeft: noTitleStyling ? `${currentLevel * 6}px` : 0,
|
||||
}}
|
||||
>
|
||||
{showLoading && !item.loaded && (
|
||||
<Loading
|
||||
@@ -112,8 +183,14 @@ export const SidebarItem = ({
|
||||
barClassName="h-[20px]"
|
||||
/>
|
||||
)}
|
||||
{item.children?.map((childItem, index) => (
|
||||
<SidebarItem item={childItem} key={index} nested={true} />
|
||||
{itemChildren?.map((childItem, index) => (
|
||||
<SidebarItem
|
||||
item={childItem}
|
||||
key={index}
|
||||
nested={true}
|
||||
currentLevel={currentLevel + 1}
|
||||
expandItems={expandItems}
|
||||
/>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
|
||||
Reference in New Issue
Block a user