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
@@ -1,6 +1,9 @@
 export * from "./use-copy"
+export * from "./use-current-learning-path"
 export * from "./use-is-browser"
 export * from "./use-keyboard-shortcut"
+export * from "./use-page-scroll-manager"
+export * from "./use-request-runner"
 export * from "./use-scroll-utils"
 export * from "./use-search-navigation"
 export * from "./use-select"
@@ -0,0 +1,98 @@
+"use client"
+
+import React, { useEffect } from "react"
+import { useLearningPath, useNotifications } from "@/providers"
+import { LearningPathIcon } from "../../components/LearningPath/Icon"
+import { LearningPathFinish } from "../../components/LearningPath/Finish"
+import { LearningPathSteps } from "../../components/LearningPath/Steps"
+
+export const useCurrentLearningPath = () => {
+  const { path, currentStep, updatePath, endPath } = useLearningPath()
+  const step = path?.steps[currentStep]
+  const {
+    addNotification,
+    generateId,
+    removeNotification,
+    updateNotification,
+  } = useNotifications() || {}
+
+  // used when a notification closed (finished or not)
+  const handleClose = (notificationId: string, shouldEndPath = true) => {
+    if (shouldEndPath) {
+      setTimeout(() => {
+        endPath()
+      }, 500)
+    }
+    removeNotification?.(notificationId)
+  }
+
+  // used when the learning path is completely finished
+  // shows the finish step, if the path has any
+  const handleFinish = (notificationId: string) => {
+    if (path?.finish) {
+      updateNotification?.(notificationId, {
+        title: path.finish.step.title,
+        text: path.finish.step.description,
+        type: "custom",
+        layout: "default",
+        CustomIcon: (
+          <LearningPathIcon
+            className="!w-2 !h-2"
+            imgClassName="!w-1.5 !h-1.5"
+          />
+        ),
+        children: (
+          <LearningPathFinish
+            {...path.finish}
+            onRating={() =>
+              setTimeout(() => {
+                handleClose(notificationId, false)
+              }, 1500)
+            }
+          />
+        ),
+      })
+      endPath()
+    } else {
+      handleClose(notificationId)
+    }
+  }
+
+  const LearningStep = (notificationId: string) => {
+    return <LearningPathSteps onFinish={() => handleFinish(notificationId)} />
+  }
+
+  // create a notification when a path is initialized
+  useEffect(() => {
+    if (path && !path.notificationId) {
+      const id = generateId?.()
+
+      if (!id) {
+        return
+      }
+
+      addNotification?.({
+        title: path.label,
+        text: step?.description,
+        onClose: () => handleClose(id),
+        layout: "empty",
+        id,
+        children: LearningStep(id),
+        className: "flex flex-col",
+      })
+      updatePath({
+        notificationId: id,
+      })
+    }
+  }, [path])
+
+  // update an existing notification when the step changes
+  useEffect(() => {
+    if (path && path.notificationId && step) {
+      updateNotification?.(path.notificationId, {
+        text: step?.description,
+        children: LearningStep(path.notificationId),
+      })
+    }
+  }, [step])
+}
@@ -0,0 +1,75 @@
+"use client"
+
+import { usePathname } from "next/navigation"
+import { useScrollController } from "../use-scroll-utils"
+import { useEffect, useState } from "react"
+import { getScrolledTop, isElmWindow } from "../../utils"
+
+export const usePageScrollManager = () => {
+  const pathname = usePathname()
+  const { scrollableElement } = useScrollController()
+  const [checkedPageReload, setCheckedPageReload] = useState(false)
+
+  const isPageReloaded = () =>
+    (window.performance.navigation &&
+      window.performance.navigation.type === 1) ||
+    window.performance
+      .getEntriesByType("navigation")
+      .map((nav) => (nav as PerformanceNavigationTiming).type)
+      .includes("reload")
+
+  useEffect(() => {
+    if (!scrollableElement || !checkedPageReload) {
+      return
+    }
+
+    if (getScrolledTop(scrollableElement) !== 0 && !location.hash) {
+      scrollableElement?.scrollTo({
+        top: 0,
+      })
+    } else if (location.hash) {
+      // retrieve and scroll to element
+      const targetElm =
+        scrollableElement && typeof document !== "undefined"
+          ? document.getElementById(location.hash.replace("#", ""))
+          : undefined
+
+      targetElm?.scrollIntoView()
+    }
+  }, [pathname, scrollableElement])
+
+  useEffect(() => {
+    if (!scrollableElement || checkedPageReload) {
+      return
+    }
+
+    if (isPageReloaded()) {
+      const loadedScrollPosition = localStorage.getItem("scrollPos")
+      if (loadedScrollPosition) {
+        scrollableElement?.scrollTo({
+          top: parseInt(loadedScrollPosition),
+        })
+      }
+      localStorage.removeItem("scrollPos")
+    }
+
+    setCheckedPageReload(true)
+
+    window.addEventListener("beforeunload", () => {
+      const scrollPos = isElmWindow(scrollableElement)
+        ? scrollableElement.screenY
+        : scrollableElement?.scrollTop
+
+      if (scrollPos) {
+        localStorage.setItem(
+          "scrollPos",
+          `${
+            isElmWindow(scrollableElement)
+              ? scrollableElement.screenY
+              : scrollableElement?.scrollTop
+          }`
+        )
+      }
+    })
+  }, [scrollableElement])
+}
@@ -0,0 +1,59 @@
+import { ApiTestingOptions } from "types"
+
+export type useRequestRunnerProps = {
+  pushLog: (...message: string[]) => void
+  onFinish: (message: string) => void
+  replaceLog?: (message: string) => void
+}
+
+export const useRequestRunner = ({
+  pushLog,
+  onFinish,
+  replaceLog,
+}: useRequestRunnerProps) => {
+  const runRequest = (apiRequestOptions: ApiTestingOptions) => {
+    let requestUrl = apiRequestOptions.url
+    if (apiRequestOptions.pathData) {
+      Object.entries(apiRequestOptions.pathData).forEach(([key, value]) => {
+        if (typeof value === "string") {
+          requestUrl = requestUrl.replace(`{${key}}`, value)
+        }
+      })
+    }
+
+    // check if there are query params
+    if (apiRequestOptions.queryData) {
+      requestUrl += `?${new URLSearchParams(
+        apiRequestOptions.queryData as Record<string, string>
+      ).toString()}`
+    }
+
+    fetch(requestUrl, {
+      method: apiRequestOptions.method,
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: apiRequestOptions.bodyData
+        ? JSON.stringify(apiRequestOptions.bodyData)
+        : undefined,
+    })
+      .then(async (response) => response.json())
+      .then((data) => {
+        const stringifiedData = JSON.stringify(data, undefined, 2)
+        replaceLog ? replaceLog(stringifiedData) : pushLog(stringifiedData)
+      })
+      .catch((error) => {
+        pushLog(
+          `An error ocurred: ${JSON.stringify(error, undefined, 2)}`,
+          `\nThis could be a CORS error. You can resolve it by adding\nthe docs' URLto your CORS configurations:\n`,
+          `STORE_CORS=http://localhost:8000,https://docs.medusajs.com`,
+          `ADMIN_CORS=http://localhost:7001,https://docs.medusajs.com`
+        )
+      })
+      .finally(() => onFinish(`Finished running request.`))
+  }
+
+  return {
+    runRequest,
+  }
+}
@@ -19,7 +19,7 @@ import React, {
  type ReactNode,
  useState,
 } from "react"
-import { getScrolledTop as getScrolledTopUtil } from "../../utils"
+import { getScrolledTop as getScrolledTopUtil, isElmWindow } from "../../utils"

 type EventFunc = (...args: never[]) => unknown

@@ -61,9 +61,12 @@ type ScrollController = {
  getScrolledTop: () => number
 }

-function useScrollControllerContextValue(
+function useScrollControllerContextValue({
+  scrollableSelector,
+}: {
  scrollableSelector: string
-): ScrollController {
+  restoreScrollOnReload?: boolean
+}): ScrollController {
  const scrollEventsEnabledRef = useRef(true)

  const [scrollableElement, setScrollableElement] = useState<
@@ -106,8 +109,11 @@ export function ScrollControllerProvider({
 }: {
  children: ReactNode
  scrollableSelector?: string
+  restoreScrollOnReload?: boolean
 }): JSX.Element {
-  const value = useScrollControllerContextValue(scrollableSelector)
+  const value = useScrollControllerContextValue({
+    scrollableSelector,
+  })
  return (
    <ScrollMonitorContext.Provider value={value}>
      {children}