docs: revise commerce modules overview pages (#10738)

* 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
2024-12-26 10:32:16 +02:00
parent c8f9938865
commit ebca8fed28
112 changed files with 9465 additions and 7731 deletions
@@ -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 ||
@@ -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}</>
 }
@@ -120,3 +120,5 @@ export const MDXComponents: MDXComponentsType = {
    return <ZoomImg {...rest} />
  },
 }
+
+export const Hr = MDXComponents["hr"] as () => React.JSX.Element
@@ -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 />
@@ -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 (