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.
2024-03-18 07:47:35 +00:00
parent 56a6ec0227
commit bb87db8342
2008 changed files with 15716 additions and 10536 deletions
@@ -0,0 +1,26 @@
+"use client"
+
+import React from "react"
+import { useSidebar } from "../../../providers"
+import clsx from "clsx"
+import { ArrowUturnLeft } from "@medusajs/icons"
+
+export const SidebarBack = () => {
+  const { goBack } = useSidebar()
+
+  return (
+    <div
+      className={clsx(
+        "my-docs_1.5 cursor-pointer",
+        "flex items-center gap-docs_0.5 rounded-docs_sm px-docs_0.5 py-[6px] hover:no-underline",
+        "border border-transparent",
+        "text-medusa-fg-subtle text-medium-plus"
+      )}
+      tabIndex={-1}
+      onClick={goBack}
+    >
+      <ArrowUturnLeft className="mr-docs_0.5" />
+      <span>Back</span>
+    </div>
+  )
+}
@@ -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>
      )}
@@ -0,0 +1,27 @@
+import React from "react"
+import Link from "next/link"
+import clsx from "clsx"
+import { SidebarItemType } from "types"
+
+type SidebarTitleProps = {
+  item: SidebarItemType
+}
+
+export const SidebarTitle = ({ item }: SidebarTitleProps) => {
+  return (
+    <Link
+      className={clsx(
+        "flex items-center justify-between gap-docs_0.5 rounded-docs_sm px-docs_0.5 py-[6px] hover:no-underline",
+        "border border-transparent",
+        "text-medusa-fg-subtle text-medium-plus"
+      )}
+      href={item.isPathHref && item.path ? item.path : `#${item.path}`}
+      replace={!item.isPathHref}
+      shallow={!item.isPathHref}
+      {...item.linkProps}
+    >
+      <span>{item.childSidebarTitle || item.title}</span>
+      {item.additionalElms}
+    </Link>
+  )
+}
@@ -1,10 +1,13 @@
 "use client"

-import React from "react"
+import React, { useMemo } from "react"
 import { useSidebar } from "@/providers"
 import clsx from "clsx"
 import { Loading } from "@/components"
 import { SidebarItem } from "./Item"
+import { SidebarTitle } from "./Title"
+import { SidebarBack } from "./Back"
+import { CSSTransition, SwitchTransition } from "react-transition-group"

 export type SidebarProps = {
  className?: string
@@ -15,12 +18,24 @@ export const Sidebar = ({
  className = "",
  expandItems = false,
 }: SidebarProps) => {
-  const { items, mobileSidebarOpen, desktopSidebarOpen } = useSidebar()
+  const {
+    items,
+    currentItems,
+    mobileSidebarOpen,
+    desktopSidebarOpen,
+    staticSidebarItems,
+    sidebarRef,
+  } = useSidebar()
+
+  const sidebarItems = useMemo(
+    () => currentItems || items,
+    [items, currentItems]
+  )

  return (
    <aside
      className={clsx(
-        "clip bg-docs-bg dark:bg-docs-bg-dark w-ref-sidebar block",
+        "clip bg-docs-bg dark:bg-docs-bg-dark block",
        "border-medusa-border-base border-0 border-r border-solid",
        "fixed -left-full top-0 h-screen transition-[left] lg:relative lg:left-0 lg:top-auto lg:h-auto",
        "lg:w-sidebar w-full",
@@ -32,32 +47,69 @@ export const Sidebar = ({
        animationFillMode: "forwards",
      }}
    >
-      <ul
-        className={clsx(
-          "sticky top-0 h-screen max-h-screen w-full list-none overflow-auto p-0",
-          "px-docs_1.5 pb-[57px] pt-docs_1.5"
-        )}
-        id="sidebar"
-      >
-        <div className="mb-docs_1.5 lg:hidden">
-          {!items.mobile.length && <Loading className="px-0" />}
-          {items.mobile.map((item, index) => (
-            <SidebarItem item={item} key={index} expandItems={expandItems} />
-          ))}
-        </div>
-        <div className="mb-docs_1.5">
-          {!items.top.length && <Loading className="px-0" />}
-          {items.top.map((item, index) => (
-            <SidebarItem item={item} key={index} expandItems={expandItems} />
-          ))}
-        </div>
-        <div className="mb-docs_1.5">
-          {!items.bottom.length && <Loading className="px-0" />}
-          {items.bottom.map((item, index) => (
-            <SidebarItem item={item} key={index} expandItems={expandItems} />
-          ))}
-        </div>
-      </ul>
+      <SwitchTransition>
+        <CSSTransition
+          key={sidebarItems.parentItem?.title || "home"}
+          nodeRef={sidebarRef}
+          classNames={{
+            enter: "animate-fadeInLeft animate-fast",
+            exit: "animate-fadeOutLeft animate-fast",
+          }}
+          timeout={200}
+        >
+          <ul
+            className={clsx(
+              "sticky top-0 h-screen max-h-screen w-full list-none overflow-auto p-0",
+              "px-docs_1.5 pb-[57px] pt-docs_1.5"
+            )}
+            id="sidebar"
+            ref={sidebarRef}
+          >
+            {sidebarItems.parentItem && (
+              <>
+                <SidebarBack />
+                <SidebarTitle item={sidebarItems.parentItem} />
+              </>
+            )}
+            <div className="mb-docs_1.5 lg:hidden">
+              {!sidebarItems.mobile.length && !staticSidebarItems && (
+                <Loading className="px-0" />
+              )}
+              {sidebarItems.mobile.map((item, index) => (
+                <SidebarItem
+                  item={item}
+                  key={index}
+                  expandItems={expandItems}
+                />
+              ))}
+            </div>
+            <div className="mb-docs_1.5">
+              {!sidebarItems.top.length && !staticSidebarItems && (
+                <Loading className="px-0" />
+              )}
+              {sidebarItems.top.map((item, index) => (
+                <SidebarItem
+                  item={item}
+                  key={index}
+                  expandItems={expandItems}
+                />
+              ))}
+            </div>
+            <div className="mb-docs_1.5">
+              {!sidebarItems.bottom.length && !staticSidebarItems && (
+                <Loading className="px-0" />
+              )}
+              {sidebarItems.bottom.map((item, index) => (
+                <SidebarItem
+                  item={item}
+                  key={index}
+                  expandItems={expandItems}
+                />
+              ))}
+            </div>
+          </ul>
+        </CSSTransition>
+      </SwitchTransition>
    </aside>
  )
 }