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
GitHub
78
www/packages/docs-ui/src/components/CodeTabs/Item/index.tsx
Normal file
78
www/packages/docs-ui/src/components/CodeTabs/Item/index.tsx
Normal file
@@ -0,0 +1,78 @@
|
||||
"use client"
|
||||
|
||||
import React from "react"
|
||||
import { BaseTabType, useScrollPositionBlocker } from "@/hooks"
|
||||
import { useColorMode } from "@/providers"
|
||||
import clsx from "clsx"
|
||||
|
||||
type CodeTabProps = BaseTabType & {
|
||||
children: React.ReactNode
|
||||
isSelected?: boolean
|
||||
blockStyle?: string
|
||||
changeSelectedTab?: (tab: BaseTabType) => void
|
||||
pushRef?: (tabButton: HTMLButtonElement | null) => void
|
||||
}
|
||||
|
||||
export const CodeTab = ({
|
||||
label,
|
||||
value,
|
||||
isSelected = false,
|
||||
blockStyle = "loud",
|
||||
changeSelectedTab,
|
||||
pushRef,
|
||||
}: CodeTabProps) => {
|
||||
const { colorMode } = useColorMode()
|
||||
const { blockElementScrollPositionUntilNextRender } =
|
||||
useScrollPositionBlocker()
|
||||
|
||||
return (
|
||||
<li>
|
||||
<button
|
||||
className={clsx(
|
||||
"text-compact-small-plus xs:border-0 py-docs_0.25 px-docs_0.75 relative rounded-full border",
|
||||
!isSelected && [
|
||||
"text-medusa-code-text-subtle border-transparent",
|
||||
blockStyle === "loud" && [
|
||||
colorMode === "light" &&
|
||||
"text-medusa-code-text-subtle hover:bg-medusa-code-bg-base",
|
||||
colorMode === "dark" &&
|
||||
"text-medusa-fg-muted hover:bg-medusa-bg-component",
|
||||
],
|
||||
blockStyle === "subtle" && [
|
||||
colorMode === "light" &&
|
||||
"text-medusa-fg-subtle hover:bg-medusa-bg-base",
|
||||
colorMode === "dark" &&
|
||||
"text-medusa-code-text-subtle hover:bg-medusa-code-bg-base",
|
||||
],
|
||||
],
|
||||
isSelected && [
|
||||
"xs:!bg-transparent",
|
||||
blockStyle === "loud" && [
|
||||
colorMode === "light" &&
|
||||
"border-medusa-code-border text-medusa-code-text-base",
|
||||
colorMode === "dark" &&
|
||||
"border-medusa-border-base text-medusa-fg-base",
|
||||
],
|
||||
blockStyle === "subtle" && [
|
||||
colorMode === "light" &&
|
||||
"xs:border-medusa-border-base text-medusa-code-text-base",
|
||||
colorMode === "dark" &&
|
||||
"xs:border-medusa-code-border text-medusa-code-text-base",
|
||||
],
|
||||
]
|
||||
)}
|
||||
ref={(tabButton) => pushRef?.(tabButton)}
|
||||
onClick={(e) => {
|
||||
blockElementScrollPositionUntilNextRender(
|
||||
e.target as HTMLButtonElement
|
||||
)
|
||||
changeSelectedTab?.({ label, value })
|
||||
}}
|
||||
aria-selected={isSelected}
|
||||
role="tab"
|
||||
>
|
||||
{label}
|
||||
</button>
|
||||
</li>
|
||||
)
|
||||
}
|
||||
@@ -1,35 +1,82 @@
|
||||
"use client"
|
||||
|
||||
import React, { useCallback, useEffect, useMemo, useRef } from "react"
|
||||
import React, { Children, useCallback, useEffect, useMemo, useRef } from "react"
|
||||
import {
|
||||
BaseTabType,
|
||||
CodeBlockProps,
|
||||
CodeBlockStyle,
|
||||
useColorMode,
|
||||
useTabs,
|
||||
} from "../.."
|
||||
import clsx from "clsx"
|
||||
import { CodeBlock, CodeBlockProps } from "@/components"
|
||||
import { useTabs, BaseTabType, useScrollPositionBlocker } from "@/hooks"
|
||||
import { CodeBlockHeader } from "../CodeBlock/Header"
|
||||
|
||||
export type TabType = {
|
||||
code?: CodeBlockProps
|
||||
codeBlock?: React.ReactNode
|
||||
} & BaseTabType
|
||||
type CodeTab = BaseTabType & {
|
||||
codeProps: CodeBlockProps
|
||||
codeBlock: React.ReactNode
|
||||
}
|
||||
|
||||
export type CodeTabsProps = {
|
||||
tabs: TabType[]
|
||||
type CodeTabProps = {
|
||||
children: React.ReactNode
|
||||
className?: string
|
||||
group?: string
|
||||
title?: string
|
||||
blockStyle?: CodeBlockStyle
|
||||
}
|
||||
|
||||
export const CodeTabs = ({
|
||||
tabs,
|
||||
children,
|
||||
className,
|
||||
group = "client",
|
||||
}: CodeTabsProps) => {
|
||||
const { selectedTab, changeSelectedTab } = useTabs<TabType>({
|
||||
title,
|
||||
blockStyle = "loud",
|
||||
}: CodeTabProps) => {
|
||||
const { colorMode } = useColorMode()
|
||||
const tabs: CodeTab[] = useMemo(() => {
|
||||
const tempTabs: CodeTab[] = []
|
||||
Children.forEach(children, (child) => {
|
||||
if (
|
||||
!React.isValidElement(child) ||
|
||||
!child.props.label ||
|
||||
!child.props.value ||
|
||||
!React.isValidElement(child.props.children)
|
||||
) {
|
||||
return
|
||||
}
|
||||
|
||||
// extract child code block
|
||||
const codeBlock =
|
||||
child.props.children.type === "pre" &&
|
||||
React.isValidElement(child.props.children.props.children)
|
||||
? child.props.children.props.children
|
||||
: child.props.children
|
||||
|
||||
tempTabs.push({
|
||||
label: child.props.label,
|
||||
value: child.props.value,
|
||||
codeProps: codeBlock.props,
|
||||
codeBlock: {
|
||||
...codeBlock,
|
||||
props: {
|
||||
...codeBlock.props,
|
||||
title: undefined,
|
||||
className: clsx("!mt-0 !rounded-t-none", codeBlock.props.className),
|
||||
},
|
||||
},
|
||||
})
|
||||
})
|
||||
|
||||
return tempTabs
|
||||
}, [children])
|
||||
|
||||
const { selectedTab, changeSelectedTab } = useTabs<CodeTab>({
|
||||
tabs,
|
||||
group,
|
||||
})
|
||||
|
||||
const tabRefs: (HTMLButtonElement | null)[] = useMemo(() => [], [])
|
||||
const codeTabSelectorRef = useRef<HTMLSpanElement | null>(null)
|
||||
const codeTabsWrapperRef = useRef<HTMLDivElement | null>(null)
|
||||
const { blockElementScrollPositionUntilNextRender } =
|
||||
useScrollPositionBlocker()
|
||||
|
||||
const changeTabSelectorCoordinates = useCallback(
|
||||
(selectedTabElm: HTMLElement) => {
|
||||
@@ -71,59 +118,54 @@ export const CodeTabs = ({
|
||||
>
|
||||
<span
|
||||
className={clsx(
|
||||
"xs:absolute xs:border xs:border-solid xs:border-medusa-code-border xs:bg-medusa-code-bg-base",
|
||||
"xs:transition-all xs:duration-200 xs:ease-ease xs:top-[13px] xs:rounded-full"
|
||||
"xs:absolute xs:border xs:border-solid",
|
||||
"xs:transition-all xs:duration-200 xs:ease-ease xs:top-[13px] xs:rounded-full",
|
||||
blockStyle === "loud" && [
|
||||
colorMode === "light" &&
|
||||
"xs:border-medusa-code-border xs:bg-medusa-code-bg-base",
|
||||
colorMode === "dark" &&
|
||||
"xs:border-medusa-border-base xs:bg-medusa-bg-component",
|
||||
],
|
||||
blockStyle === "subtle" && [
|
||||
colorMode === "light" &&
|
||||
"xs:border-medusa-border-base xs:bg-medusa-bg-base",
|
||||
colorMode === "dark" &&
|
||||
"xs:border-medusa-code-border xs:bg-medusa-code-bg-base",
|
||||
]
|
||||
)}
|
||||
ref={codeTabSelectorRef}
|
||||
></span>
|
||||
<ul
|
||||
className={clsx(
|
||||
"bg-medusa-code-bg-header py-docs_0.75 flex !list-none rounded-t-docs_DEFAULT px-docs_1",
|
||||
"border-medusa-code-border border border-b-0",
|
||||
"gap-docs_0.25 mb-0"
|
||||
)}
|
||||
>
|
||||
{tabs.map((tab, index) => (
|
||||
<li key={index}>
|
||||
<button
|
||||
className={clsx(
|
||||
"text-compact-small-plus xs:border-0 py-docs_0.25 px-docs_0.75 relative rounded-full border",
|
||||
(!selectedTab || selectedTab.value !== tab.value) && [
|
||||
"text-medusa-code-text-subtle border-transparent",
|
||||
"hover:bg-medusa-code-bg-base",
|
||||
],
|
||||
selectedTab?.value === tab.value && [
|
||||
"text-medusa-code-text-base bg-medusa-code-bg-base xs:!bg-transparent",
|
||||
"xs:!bg-transparent",
|
||||
]
|
||||
)}
|
||||
ref={(tabControl) => tabRefs.push(tabControl)}
|
||||
onClick={(e) => {
|
||||
blockElementScrollPositionUntilNextRender(
|
||||
e.target as HTMLButtonElement
|
||||
)
|
||||
changeSelectedTab(tab)
|
||||
}}
|
||||
aria-selected={selectedTab?.value === tab.value}
|
||||
role="tab"
|
||||
>
|
||||
{tab.label}
|
||||
</button>
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
<>
|
||||
{selectedTab?.code && (
|
||||
<CodeBlock
|
||||
{...selectedTab?.code}
|
||||
className={clsx(
|
||||
"!mt-0 !rounded-t-none",
|
||||
selectedTab.code.className
|
||||
)}
|
||||
/>
|
||||
)}
|
||||
{selectedTab?.codeBlock && <>{selectedTab.codeBlock}</>}
|
||||
</>
|
||||
<CodeBlockHeader title={selectedTab?.codeProps?.title || title}>
|
||||
<ul
|
||||
className={clsx(
|
||||
"!list-none flex gap-docs_0.25 items-center",
|
||||
"p-0 mb-0"
|
||||
)}
|
||||
>
|
||||
{Children.map(children, (child, index) => {
|
||||
if (!React.isValidElement(child)) {
|
||||
return <></>
|
||||
}
|
||||
|
||||
return (
|
||||
<child.type
|
||||
{...child.props}
|
||||
changeSelectedTab={changeSelectedTab}
|
||||
pushRef={(tabButton: HTMLButtonElement | null) =>
|
||||
tabRefs.push(tabButton)
|
||||
}
|
||||
blockStyle={blockStyle}
|
||||
isSelected={
|
||||
!selectedTab
|
||||
? index === 0
|
||||
: selectedTab.value === child.props.value
|
||||
}
|
||||
/>
|
||||
)
|
||||
})}
|
||||
</ul>
|
||||
</CodeBlockHeader>
|
||||
{selectedTab?.codeBlock}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user