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.

www/packages/docs-ui/src/components/Note/Layout/index.tsx

@@ -0,0 +1,59 @@
+import React from "react"
+import { NoteProps } from ".."
+import clsx from "clsx"
+
+type NoteLayoutProps = NoteProps & {
+  icon: React.ReactNode
+}
+
+export const NoteLayout = ({
+  type,
+  title,
+  children,
+  icon,
+}: NoteLayoutProps) => {
+  const isDefaultStyle =
+    type === "default" ||
+    type === "success" ||
+    type === "error" ||
+    type === "check"
+  const isWarningStyle = type === "warning"
+
+  return (
+    <div
+      className={clsx(
+        "p-docs_1 border border-solid  rounded shadow-none",
+        isDefaultStyle &&
+          "bg-medusa-tag-neutral-bg border-medusa-tag-neutral-border",
+        isWarningStyle && "bg-medusa-tag-red-bg border-medusa-tag-red-border",
+        "[&_a]:no-underline [&_a]:text-medusa-fg-interactive hover:[&_a]:text-medusa-fg-interactive-hover ",
+        "mb-docs_2 alert"
+      )}
+    >
+      <div className={clsx("flex")}>
+        <span className={clsx("inline-block h-1.5 w-1.5 mr-1")}>{icon}</span>
+        <div
+          className={clsx(
+            isDefaultStyle && "text-medusa-tag-neutral-text",
+            isWarningStyle && "text-medusa-tag-red-text",
+            "text-medium flex-1 [&>*:last-child]:mb-0",
+            "[&>p>code]:px-docs_0.5 [&>p>code]:text-code-label"
+          )}
+        >
+          {title && (
+            <span
+              className={clsx(
+                "txt-compact-medium-plus block mb-docs_0.125",
+                isDefaultStyle && "text-medusa-fg-base",
+                isWarningStyle && "text-medusa-tag-red-text"
+              )}
+            >
+              {title}
+            </span>
+          )}
+          {children}
+        </div>
+      </div>
+    </div>
+  )
+}

www/packages/docs-ui/src/components/Note/Types/checks.tsx

@@ -0,0 +1,27 @@
+import React from "react"
+import { NoteProps } from ".."
+import { NoteLayout } from "../Layout"
+import { CheckCircleSolid } from "@medusajs/icons"
+import clsx from "clsx"
+
+export const CheckNote = ({
+  title = "Prerequisites",
+  icon,
+  ...props
+}: NoteProps) => {
+  return (
+    <NoteLayout
+      title={title}
+      icon={
+        icon || (
+          <CheckCircleSolid
+            className={clsx(
+              "inline-block mr-docs_0.125 text-medusa-tag-neutral-icon"
+            )}
+          />
+        )
+      }
+      {...props}
+    />
+  )
+}

www/packages/docs-ui/src/components/Note/Types/default.tsx

@@ -0,0 +1,23 @@
+import React from "react"
+import { NoteProps } from ".."
+import { NoteLayout } from "../Layout"
+import { InformationCircleSolid } from "@medusajs/icons"
+import clsx from "clsx"
+
+export const DefaultNote = ({ title = "Note", icon, ...props }: NoteProps) => {
+  return (
+    <NoteLayout
+      title={title}
+      icon={
+        icon || (
+          <InformationCircleSolid
+            className={clsx(
+              "inline-block mr-docs_0.125 text-medusa-tag-neutral-icon"
+            )}
+          />
+        )
+      }
+      {...props}
+    />
+  )
+}

www/packages/docs-ui/src/components/Note/Types/error.tsx

@@ -0,0 +1,23 @@
+import React from "react"
+import { NoteProps } from ".."
+import { NoteLayout } from "../Layout"
+import { XMark } from "@medusajs/icons"
+import clsx from "clsx"
+
+export const ErrorNote = ({ title = "Error", icon, ...props }: NoteProps) => {
+  return (
+    <NoteLayout
+      title={title}
+      icon={
+        icon || (
+          <XMark
+            className={clsx(
+              "inline-block mr-docs_0.125 text-medusa-tag-red-icon"
+            )}
+          />
+        )
+      }
+      {...props}
+    />
+  )
+}

www/packages/docs-ui/src/components/Note/Types/sucess.tsx

@@ -0,0 +1,27 @@
+import React from "react"
+import { NoteProps } from ".."
+import { NoteLayout } from "../Layout"
+import { Check } from "@medusajs/icons"
+import clsx from "clsx"
+
+export const SuccessNote = ({
+  title = "Sucess",
+  icon,
+  ...props
+}: NoteProps) => {
+  return (
+    <NoteLayout
+      title={title}
+      icon={
+        icon || (
+          <Check
+            className={clsx(
+              "inline-block mr-docs_0.125 text-medusa-tag-green-icon"
+            )}
+          />
+        )
+      }
+      {...props}
+    />
+  )
+}

www/packages/docs-ui/src/components/Note/Types/warning.tsx

@@ -0,0 +1,27 @@
+import React from "react"
+import { NoteProps } from ".."
+import { NoteLayout } from "../Layout"
+import { ExclamationCircleSolid } from "@medusajs/icons"
+import clsx from "clsx"
+
+export const WarningNote = ({
+  title = "Warning",
+  icon,
+  ...props
+}: NoteProps) => {
+  return (
+    <NoteLayout
+      title={title}
+      icon={
+        icon || (
+          <ExclamationCircleSolid
+            className={clsx(
+              "inline-block mr-docs_0.125 text-medusa-tag-red-icon"
+            )}
+          />
+        )
+      }
+      {...props}
+    />
+  )
+}

www/packages/docs-ui/src/components/Note/index.tsx

@@ -0,0 +1,28 @@
+import React from "react"
+import { WarningNote } from "./Types/warning"
+import { DefaultNote } from "./Types/default"
+import { SuccessNote } from "./Types/sucess"
+import { ErrorNote } from "./Types/error"
+import { CheckNote } from "./Types/checks"
+
+export type NoteProps = {
+  type?: "default" | "warning" | "success" | "error" | "check"
+  title?: string
+  children?: React.ReactNode
+  icon?: React.ReactNode
+}
+
+export const Note = ({ type = "default", ...props }: NoteProps) => {
+  switch (type) {
+    case "warning":
+      return <WarningNote type={type} {...props} />
+    case "success":
+      return <SuccessNote type={type} {...props} />
+    case "error":
+      return <ErrorNote type={type} {...props} />
+    case "check":
+      return <CheckNote type={type} {...props} />
+    default:
+      return <DefaultNote type={type} {...props} />
+  }
+}