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

docs: revise commerce modules overview pages (#10738)

Browse Source 
* revise API Key Module overview

* revise auth module

* support ref sidebar items

* remove examples

* revise cart module

* revise currency

* revise customer module

* revise fulfillment module

* revise inventory module

* revise order module

* revise payment

* revise pricing module

* revise product module

* revise promotion module

* revise region module

* revise sales channel module

* revise stock location module

* revise store module

* revise tax module

* revise user module

* lint content + fix snippets
This commit is contained in:
Shahed Nasser authored and GitHub committed 2024-12-26 10:32:16 +02:00
1 parent c8f9938865
commit ebca8fed28
112 files changed
+9465 -7731
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

www/packages/docs-ui/src/components/Breadcrumbs/index.tsx
+21 -18
View File
@@ -4,7 +4,12 @@ import React, { useMemo } from "react"
import clsx from "clsx"
import Link from "next/link"
import { SidebarItemLink } from "types"
import { CurrentItemsState, useSidebar, useSiteConfig } from "../../providers"
import {
CurrentItemsState,
isSidebarItemLink,
useSidebar,
useSiteConfig,
} from "../../providers"
import { Button } from "../Button"
import { TriangleRightMini } from "@medusajs/icons"
@@ -29,22 +34,20 @@ export const Breadcrumbs = () => {
tempBreadcrumbItems = getBreadcrumbsOfItem(item.previousSidebar)
}
const parentPath =
item.parentItem?.type === "link"
? getLinkPath(item.parentItem)
: (item.parentItem?.type === "category" &&
breadcrumbOptions?.showCategories) ||
item.parentItem?.type === "sub-category"
? "#"
: undefined
const firstItemPath =
item.default[0].type === "link"
? getLinkPath(item.default[0])
: (item.default[0].type === "category" &&
breadcrumbOptions?.showCategories) ||
item.default[0].type === "sub-category"
? "#"
: undefined
const parentPath = isSidebarItemLink(item.parentItem)
? getLinkPath(item.parentItem)
: (item.parentItem?.type === "category" &&
breadcrumbOptions?.showCategories) ||
item.parentItem?.type === "sub-category"
? "#"
: undefined
const firstItemPath = isSidebarItemLink(item.default[0])
? getLinkPath(item.default[0])
: (item.default[0].type === "category" &&
breadcrumbOptions?.showCategories) ||
item.default[0].type === "sub-category"
? "#"
: undefined
const breadcrumbPath = parentPath || firstItemPath || "/"
@@ -76,7 +79,7 @@ export const Breadcrumbs = () => {
breadcrumbOptions?.showCategories)
) {
tempBreadcrumbItems.set(
sidebarActiveItem.parentItem.type === "link"
isSidebarItemLink(sidebarActiveItem.parentItem)
? getLinkPath(sidebarActiveItem.parentItem) || "#"
: "#",
sidebarActiveItem.parentItem.chapterTitle ||
www/packages/docs-ui/src/components/ChildDocs/index.tsx
+5 -188
View File
@@ -1,193 +1,10 @@
"use client"
import React, { useMemo } from "react"
import { Card, CardList, H2, useSidebar } from "../.."
import { InteractiveSidebarItem, SidebarItem, SidebarItemLink } from "types"
import slugify from "slugify"
import { MDXComponents } from "../.."
import React from "react"
import { useChildDocs, UseChildDocsProps } from "../.."
const Hr = MDXComponents["hr"] as () => React.JSX.Element
export const ChildDocs = (props: UseChildDocsProps) => {
const { component } = useChildDocs(props)
type ChildDocsProps = {
onlyTopLevel?: boolean
type?: "sidebar" | "item"
hideItems?: string[]
showItems?: string[]
hideTitle?: boolean
childLevel?: number
}
export const ChildDocs = ({
onlyTopLevel = false,
hideItems = [],
showItems,
type = "sidebar",
hideTitle = false,
childLevel = 1,
}: ChildDocsProps) => {
const { currentItems, activeItem } = useSidebar()
const filterType = useMemo(() => {
return showItems !== undefined
? "show"
: hideItems.length > 0
? "hide"
: "all"
}, [showItems, hideItems])
const filterCondition = (item: SidebarItem): boolean => {
if (item.type === "separator") {
return false
}
switch (filterType) {
case "hide":
return (
(item.type !== "link" || !hideItems.includes(item.path)) &&
!hideItems.includes(item.title)
)
case "show":
return (
(item.type === "link" && showItems!.includes(item.path)) ||
showItems!.includes(item.title)
)
case "all":
return true
}
}
const filterItems = (items: SidebarItem[]): SidebarItem[] => {
return items
.filter(filterCondition)
.map((item) => Object.assign({}, item))
.map((item) => {
if (
item.type !== "separator" &&
item.children &&
filterType === "hide"
) {
item.children = filterItems(item.children)
}
return item
})
}
const filteredItems = useMemo(() => {
const targetItems =
type === "sidebar"
? currentItems
? Object.assign({}, currentItems)
: undefined
: {
default: [...(activeItem?.children || [])],
}
if (filterType === "all" || !targetItems) {
return targetItems
}
return {
...targetItems,
default: filterItems(targetItems.default),
}
}, [currentItems, type, activeItem, filterItems])
const filterNonInteractiveItems = (
items: SidebarItem[] | undefined
): InteractiveSidebarItem[] => {
return (
(items?.filter(
(item) => item.type !== "separator"
) as InteractiveSidebarItem[]) || []
)
}
const getChildrenForLevel = (
item: InteractiveSidebarItem,
currentLevel = 1
): InteractiveSidebarItem[] | undefined => {
if (currentLevel === childLevel) {
return filterNonInteractiveItems(item.children)
}
if (!item.children) {
return
}
const childrenResult: InteractiveSidebarItem[] = []
filterNonInteractiveItems(item.children).forEach((child) => {
const childChildren = getChildrenForLevel(child, currentLevel + 1)
if (!childChildren) {
return
}
childrenResult.push(...childChildren)
})
return childrenResult
}
const getTopLevelElms = (items?: SidebarItem[]) => {
return (
<CardList
items={
filterNonInteractiveItems(items).map((childItem) => {
const href =
childItem.type === "link"
? childItem.path
: childItem.children?.length
? (
childItem.children.find(
(item) => item.type === "link"
) as SidebarItemLink
)?.path
: "#"
return {
title: childItem.title,
href,
}
}) || []
}
/>
)
}
const getAllLevelsElms = (items?: SidebarItem[]) => {
const filteredItems = filterNonInteractiveItems(items)
return filteredItems.map((item, key) => {
const itemChildren = getChildrenForLevel(item)
const HeadingComponent = itemChildren?.length ? H2 : undefined
return (
<React.Fragment key={key}>
{HeadingComponent && (
<>
{!hideTitle && (
<HeadingComponent id={slugify(item.title)}>
{item.title}
</HeadingComponent>
)}
<CardList
items={
itemChildren?.map((childItem) => ({
title: childItem.title,
href: childItem.type === "link" ? childItem.path : "",
})) || []
}
/>
{key !== filteredItems.length - 1 && <Hr />}
</>
)}
{!HeadingComponent && item.type === "link" && (
<Card title={item.title} href={item.path} />
)}
</React.Fragment>
)
})
}
const getElms = (items?: SidebarItem[]) => {
return onlyTopLevel ? getTopLevelElms(items) : getAllLevelsElms(items)
}
return <>{getElms(filteredItems?.default)}</>
return <>{component}</>
}
www/packages/docs-ui/src/components/MDXComponents/index.tsx
+2
View File
@@ -120,3 +120,5 @@ export const MDXComponents: MDXComponentsType = {
return <ZoomImg {...rest} />
},
}
export const Hr = MDXComponents["hr"] as () => React.JSX.Element
www/packages/docs-ui/src/components/Sidebar/Item/index.tsx
+1
View File
@@ -30,6 +30,7 @@ export const SidebarItem = ({
case "sub-category":
return <SidebarItemSubCategory item={item} {...props} />
case "link":
case "ref":
return <SidebarItemLink item={item} {...props} />
case "separator":
return <DottedSeparator />
www/packages/docs-ui/src/components/Sidebar/index.tsx
+2 -2
View File
@@ -1,7 +1,7 @@
"use client"
import React, { Suspense, useMemo, useRef } from "react"
import { useSidebar } from "@/providers"
import { isSidebarItemLink, useSidebar } from "@/providers"
import clsx from "clsx"
import { Loading } from "@/components"
import { SidebarItem } from "./Item"
@@ -139,7 +139,7 @@ export const Sidebar = ({
const itemKey =
item.type === "separator"
? index
: item.type === "link"
: isSidebarItemLink(item)
? `${item.path}-${index}`
: `${item.title}-${index}`
return (
www/packages/docs-ui/src/hooks/index.ts
+1
View File
@@ -1,4 +1,5 @@
export * from "./use-active-on-scroll"
export * from "./use-child-docs"
export * from "./use-click-outside"
export * from "./use-collapsible"
export * from "./use-collapsible-code-lines"
www/packages/docs-ui/src/hooks/use-child-docs/index.tsx
+228
View File
@@ -0,0 +1,228 @@
"use client"
import React, { useMemo } from "react"
import {
Card,
CardList,
H2,
H3,
H4,
Hr,
isSidebarItemLink,
useSidebar,
} from "../.."
import { InteractiveSidebarItem, SidebarItem, SidebarItemLink } from "types"
import slugify from "slugify"
import { MDXComponents } from "../.."
type HeadingComponent = (
props: React.HTMLAttributes<HTMLHeadingElement>
) => React.JSX.Element
export type UseChildDocsProps = {
onlyTopLevel?: boolean
type?: "sidebar" | "item"
hideItems?: string[]
showItems?: string[]
hideTitle?: boolean
titleLevel?: number
childLevel?: number
itemsPerRow?: number
}
export const useChildDocs = ({
onlyTopLevel = false,
hideItems = [],
showItems,
type = "sidebar",
hideTitle = false,
titleLevel = 2,
childLevel = 1,
itemsPerRow,
}: UseChildDocsProps) => {
const { currentItems, activeItem } = useSidebar()
const TitleHeaderComponent: HeadingComponent = useMemo(() => {
switch (titleLevel) {
case 3:
return H3
case 4:
return H4
case 5:
return MDXComponents["h5"] as HeadingComponent
case 6:
return MDXComponents["h6"] as HeadingComponent
default:
return H2
}
}, [titleLevel])
const filterType = useMemo(() => {
return showItems !== undefined
? "show"
: hideItems.length > 0
? "hide"
: "all"
}, [showItems, hideItems])
const filterCondition = (item: SidebarItem): boolean => {
if (item.type === "separator") {
return false
}
switch (filterType) {
case "hide":
return (
(!isSidebarItemLink(item) || !hideItems.includes(item.path)) &&
!hideItems.includes(item.title)
)
case "show":
return (
(isSidebarItemLink(item) && showItems!.includes(item.path)) ||
showItems!.includes(item.title)
)
case "all":
return true
}
}
const filterItems = (items: SidebarItem[]): SidebarItem[] => {
return items
.filter(filterCondition)
.map((item) => Object.assign({}, item))
.map((item) => {
if (
item.type !== "separator" &&
item.children &&
filterType === "hide"
) {
item.children = filterItems(item.children)
}
return item
})
}
const filteredItems = useMemo(() => {
const targetItems =
type === "sidebar"
? currentItems
? Object.assign({}, currentItems)
: undefined
: {
default: [...(activeItem?.children || [])],
}
if (filterType === "all" || !targetItems) {
return targetItems
}
return {
...targetItems,
default: filterItems(targetItems.default),
}
}, [currentItems, type, activeItem, filterItems])
const filterNonInteractiveItems = (
items: SidebarItem[] | undefined
): InteractiveSidebarItem[] => {
return (
(items?.filter(
(item) => item.type !== "separator"
) as InteractiveSidebarItem[]) || []
)
}
const getChildrenForLevel = (
item: InteractiveSidebarItem,
currentLevel = 1
): InteractiveSidebarItem[] | undefined => {
if (currentLevel === childLevel) {
return filterNonInteractiveItems(item.children)
}
if (!item.children) {
return
}
const childrenResult: InteractiveSidebarItem[] = []
filterNonInteractiveItems(item.children).forEach((child) => {
const childChildren = getChildrenForLevel(child, currentLevel + 1)
if (!childChildren) {
return
}
childrenResult.push(...childChildren)
})
return childrenResult
}
const getTopLevelElms = (items?: SidebarItem[]) => {
return (
<CardList
items={
filterNonInteractiveItems(items).map((childItem) => {
const href = isSidebarItemLink(childItem)
? childItem.path
: childItem.children?.length
? (
childItem.children.find((item) =>
isSidebarItemLink(item)
) as SidebarItemLink
)?.path
: "#"
return {
title: childItem.title,
href,
}
}) || []
}
itemsPerRow={itemsPerRow}
/>
)
}
const getAllLevelsElms = (items?: SidebarItem[]) => {
const filteredItems = filterNonInteractiveItems(items)
return filteredItems.map((item, key) => {
const itemChildren = getChildrenForLevel(item)
const HeadingComponent = itemChildren?.length
? TitleHeaderComponent
: undefined
return (
<React.Fragment key={key}>
{HeadingComponent && (
<>
{!hideTitle && (
<HeadingComponent id={slugify(item.title.toLowerCase())}>
{item.title}
</HeadingComponent>
)}
<CardList
items={
itemChildren?.map((childItem) => ({
title: childItem.title,
href: isSidebarItemLink(childItem) ? childItem.path : "",
})) || []
}
itemsPerRow={itemsPerRow}
/>
{key !== filteredItems.length - 1 && <Hr />}
</>
)}
{!HeadingComponent && isSidebarItemLink(item) && (
<Card title={item.title} href={item.path} />
)}
</React.Fragment>
)
})
}
const getElms = (items?: SidebarItem[]) => {
return onlyTopLevel ? getTopLevelElms(items) : getAllLevelsElms(items)
}
return {
items: filteredItems,
component: getElms(filteredItems?.default),
}
}
www/packages/docs-ui/src/providers/Pagination/index.tsx
+15 -10
View File
@@ -7,7 +7,7 @@ import React, {
useMemo,
useState,
} from "react"
import { useSidebar } from "../Sidebar"
import { isSidebarItemLink, useSidebar } from "../Sidebar"
import { usePrevious } from "@uidotdev/usehooks"
import { InteractiveSidebarItem, SidebarItem } from "types"
@@ -56,7 +56,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
return undefined
}
return children[0].type === "link"
return isSidebarItemLink(children[0])
? {
...children[0],
parent: item,
@@ -69,7 +69,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
): SidebarItemWithParent[] | undefined => {
return item.children?.filter(
(childItem) =>
childItem.type === "link" ||
isSidebarItemLink(childItem) ||
(childItem.type !== "separator" &&
getChildrenWithPages(childItem)?.length)
) as SidebarItemWithParent[]
@@ -95,7 +95,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
parent: item,
}
}
} else if (item.type === "link") {
} else if (isSidebarItemLink(item)) {
foundItem = item
}
@@ -115,7 +115,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
return false
}
if (item.type === "link") {
if (isSidebarItemLink(item)) {
foundItem = item
} else if (item.children?.length) {
const childItem = getNextItem(item.children, -1)
@@ -139,7 +139,7 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
}
result.foundActive = currentItems.some((item, index) => {
if (item.type === "link" && item.path === activePath) {
if (isSidebarItemLink(item) && item.path === activePath) {
if (index !== 0) {
result.prevItem = getPrevItem(currentItems, index)
}
@@ -161,8 +161,9 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
result.prevItem = childrenResult.prevItem
result.nextItem = childrenResult.nextItem
if (!result.prevItem) {
result.prevItem =
item.type === "link" ? item : getPrevItem(currentItems, index)
result.prevItem = isSidebarItemLink(item)
? item
: getPrevItem(currentItems, index)
}
if (!result.nextItem && index !== currentItems.length - 1) {
@@ -186,7 +187,9 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
result.prevItem
? {
title: result.prevItem.title,
link: result.prevItem.type === "link" ? result.prevItem.path : "",
link: isSidebarItemLink(result.prevItem)
? result.prevItem.path
: "",
parentTitle:
result.prevItem.parent?.type !== "separator"
? result.prevItem.parent?.title
@@ -198,7 +201,9 @@ export const PaginationProvider = ({ children }: PaginationProviderProps) => {
result.nextItem
? {
title: result.nextItem.title,
link: result.nextItem.type === "link" ? result.nextItem.path : "",
link: isSidebarItemLink(result.nextItem)
? result.nextItem.path
: "",
parentTitle:
result.nextItem.parent?.type !== "separator"
? result.nextItem.parent?.title
www/packages/docs-ui/src/providers/Sidebar/index.tsx
+42 -25
View File
@@ -95,13 +95,26 @@ export type ActionType =
type LinksMap = Map<string, SidebarItemLinkWithParent>
export const isSidebarItemLink = (
item: SidebarItem | undefined,
checkRef = true
): item is SidebarItemLink => {
return (
item !== undefined &&
(item.type === "link" || (checkRef && item.type === "ref"))
)
}
const areItemsEqual = (itemA: SidebarItem, itemB: SidebarItem): boolean => {
if (itemA.type === "separator" || itemB.type === "separator") {
return false
}
const hasSameTitle = itemA.title === itemB.title
const hasSamePath =
itemA.type === "link" && itemB.type === "link" && itemA.path === itemB.path
isSidebarItemLink(itemA) &&
isSidebarItemLink(itemB) &&
itemA.type === itemB.type &&
itemA.path === itemB.path
return hasSameTitle || hasSamePath
}
@@ -116,8 +129,8 @@ const findItem = (
if (i.type === "separator") {
return false
}
if (areItemsEqual(item as SidebarItem, i) && i.type === "link") {
foundItem = i
if (areItemsEqual(item as SidebarItem, i)) {
foundItem = i as SidebarItemLink
} else if (checkChildren && i.children) {
foundItem = findItem(i.children, item)
if (foundItem && !foundItem.parentItem) {
@@ -143,7 +156,7 @@ const getLinksMap = (
return
}
if (item.type === "link") {
if (isSidebarItemLink(item)) {
map.set(item.path, {
...item,
parentItem,
@@ -246,7 +259,7 @@ export const reducer = (
: [...(i.children || []), ...items],
loaded: parent.changeLoaded
? true
: i.type === "link"
: isSidebarItemLink(i)
? i.loaded
: true,
}
@@ -355,8 +368,8 @@ export const SidebarProvider = ({
}
const isLinkActive = useCallback(
(item: SidebarItem, checkChildren = false): boolean => {
if (item.type !== "link") {
(item: SidebarItem, checkChildren = false, checkRef = true): boolean => {
if (!isSidebarItemLink(item, checkRef)) {
return false
}
@@ -399,24 +412,28 @@ export const SidebarProvider = ({
if (item.type === "separator") {
return false
}
if (item.isChildSidebar && isLinkActive(item)) {
if (item.isChildSidebar && isLinkActive(item, false, false)) {
currentSidebar = item
return true
}
if (!item.children?.length) {
return false
}
if (!currentSidebar && item.children?.length) {
const childSidebar =
getCurrentSidebar(item.children) ||
(activePath
? findItem(item.children, {
path: activePath || undefined,
type: "link",
})
: undefined)
const childSidebar =
getCurrentSidebar(item.children) ||
(activePath
? findItem(item.children, {
path: activePath,
type: "link",
})
: undefined)
if (childSidebar) {
currentSidebar = childSidebar.isChildSidebar ? childSidebar : item
}
}
currentSidebar = childSidebar
? childSidebar.isChildSidebar
? childSidebar
: item
: undefined
return currentSidebar !== undefined
})
@@ -434,7 +451,7 @@ export const SidebarProvider = ({
const previousSidebar = currentItems.previousSidebar || items
const backItem = previousSidebar.default.find(
(item) => item.type === "link" && !item.isChildSidebar
(item) => isSidebarItemLink(item) && !item.isChildSidebar
) as SidebarItemLink
if (!backItem) {
@@ -472,7 +489,7 @@ export const SidebarProvider = ({
const handleScroll = () => {
if (getScrolledTop(resolvedScrollableElement) === 0) {
const firstItemPath =
items.default.length && items.default[0].type === "link"
items.default.length && isSidebarItemLink(items.default[0])
? items.default[0].path
: ""
setActivePath(firstItemPath)
@@ -548,8 +565,8 @@ export const SidebarProvider = ({
) {
const { children, ...parentItem } = currentSidebar
const hasPreviousSidebar =
currentItems?.previousSidebar?.parentItem?.type === "link" &&
parentItem.type === "link" &&
isSidebarItemLink(currentItems?.previousSidebar?.parentItem) &&
isSidebarItemLink(parentItem) &&
currentItems.previousSidebar.parentItem.path !== parentItem.path
setCurrentItems({