docs: create docs workspace (#5174)

* docs: migrate ui docs to docs universe

* created yarn workspace

* added eslint and tsconfig configurations

* fix eslint configurations

* fixed eslint configurations

* shared tailwind configurations

* added shared ui package

* added more shared components

* migrating more components

* made details components shared

* move InlineCode component

* moved InputText

* moved Loading component

* Moved Modal component

* moved Select components

* Moved Tooltip component

* moved Search components

* moved ColorMode provider

* Moved Notification components and providers

* used icons package

* use UI colors in api-reference

* moved Navbar component

* used Navbar and Search in UI docs

* added Feedback to UI docs

* general enhancements

* fix color mode

* added copy colors file from ui-preset

* added features and enhancements to UI docs

* move Sidebar component and provider

* general fixes and preparations for deployment

* update docusaurus version

* adjusted versions

* fix output directory

* remove rootDirectory property

* fix yarn.lock

* moved code component

* added vale for all docs MD and MDX

* fix tests

* fix vale error

* fix deployment errors

* change ignore commands

* add output directory

* fix docs test

* general fixes

* content fixes

* fix announcement script

* added changeset

* fix vale checks

* added nofilter option

* fix vale error

www/apps/api-reference/providers/area.tsx

@@ -0,0 +1,51 @@
+"use client"
+
+import type { Area } from "@/types/openapi"
+import { useSearch } from "docs-ui"
+import { createContext, useContext, useEffect, useState } from "react"
+
+type AreaContextType = {
+  area: Area
+  setArea: (value: Area) => void
+}
+
+const AreaContext = createContext<AreaContextType | null>(null)
+
+type AreaProviderProps = {
+  area: Area
+  children: React.ReactNode
+}
+
+const AreaProvider = ({ area: passedArea, children }: AreaProviderProps) => {
+  const [area, setArea] = useState<Area>(passedArea)
+  const { defaultFilters, setDefaultFilters } = useSearch()
+
+  useEffect(() => {
+    if (!defaultFilters.includes(area)) {
+      setDefaultFilters([area])
+    }
+  }, [area, defaultFilters, setDefaultFilters])
+
+  return (
+    <AreaContext.Provider
+      value={{
+        area,
+        setArea,
+      }}
+    >
+      {children}
+    </AreaContext.Provider>
+  )
+}
+
+export default AreaProvider
+
+export const useArea = (): AreaContextType => {
+  const context = useContext(AreaContext)
+
+  if (!context) {
+    throw new Error("useAreaProvider must be used inside an AreaProvider")
+  }
+
+  return context
+}

www/apps/api-reference/providers/base-specs.tsx

@@ -0,0 +1,69 @@
+"use client"
+
+import { ExpandedDocument, SecuritySchemeObject } from "@/types/openapi"
+import { ReactNode, createContext, useContext, useState } from "react"
+
+type BaseSpecsContextType = {
+  baseSpecs: ExpandedDocument | null
+  setBaseSpecs: (value: ExpandedDocument) => void
+  getSecuritySchema: (securityName: string) => SecuritySchemeObject | null
+}
+
+const BaseSpecsContext = createContext<BaseSpecsContextType | null>(null)
+
+type BaseSpecsProviderProps = {
+  initialSpecs?: ExpandedDocument | null
+  children?: ReactNode
+}
+
+const BaseSpecsProvider = ({
+  children,
+  initialSpecs = null,
+}: BaseSpecsProviderProps) => {
+  const [baseSpecs, setBaseSpecs] = useState<ExpandedDocument | null>(
+    initialSpecs
+  )
+
+  const getSecuritySchema = (
+    securityName: string
+  ): SecuritySchemeObject | null => {
+    if (
+      baseSpecs?.components?.securitySchemes &&
+      Object.prototype.hasOwnProperty.call(
+        baseSpecs?.components?.securitySchemes,
+        securityName
+      )
+    ) {
+      const schema = baseSpecs?.components?.securitySchemes[securityName]
+      if (!("$ref" in schema)) {
+        return schema
+      }
+    }
+
+    return null
+  }
+
+  return (
+    <BaseSpecsContext.Provider
+      value={{
+        baseSpecs,
+        setBaseSpecs,
+        getSecuritySchema,
+      }}
+    >
+      {children}
+    </BaseSpecsContext.Provider>
+  )
+}
+
+export default BaseSpecsProvider
+
+export const useBaseSpecs = (): BaseSpecsContextType => {
+  const context = useContext(BaseSpecsContext)
+
+  if (!context) {
+    throw new Error("useBaseSpecs must be used inside a BaseSpecsProvider")
+  }
+
+  return context
+}

www/apps/api-reference/providers/color-mode.tsx

@@ -0,0 +1,74 @@
+"use client"
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useState,
+} from "react"
+
+type ColorMode = "light" | "dark"
+
+type ColorModeContextType = {
+  colorMode: ColorMode
+  setColorMode: (value: ColorMode) => void
+  toggleColorMode: () => void
+}
+
+const ColorModeContext = createContext<ColorModeContextType | null>(null)
+
+type ColorModeProviderProps = {
+  children: React.ReactNode
+}
+
+const ColorModeProvider = ({ children }: ColorModeProviderProps) => {
+  const [colorMode, setColorMode] = useState<ColorMode>("light")
+
+  const toggleColorMode = () =>
+    setColorMode(colorMode === "light" ? "dark" : "light")
+
+  const init = () => {
+    const theme = localStorage.getItem("theme")
+    if (theme && (theme === "light" || theme === "dark")) {
+      setColorMode(theme)
+    }
+  }
+
+  useEffect(() => {
+    init()
+  }, [])
+
+  useEffect(() => {
+    const theme = localStorage.getItem("theme")
+    if (theme !== colorMode) {
+      localStorage.setItem("theme", colorMode)
+    }
+
+    document.querySelector("html")?.setAttribute("data-theme", colorMode)
+  }, [colorMode])
+
+  return (
+    <ColorModeContext.Provider
+      value={{
+        colorMode,
+        setColorMode,
+        toggleColorMode,
+      }}
+    >
+      {children}
+    </ColorModeContext.Provider>
+  )
+}
+
+export default ColorModeProvider
+
+export const useColorMode = (): ColorModeContextType => {
+  const context = useContext(ColorModeContext)
+
+  if (!context) {
+    throw new Error("useColorMode must be used inside a ColorModeProvider")
+  }
+
+  return context
+}

www/apps/api-reference/providers/index.tsx

@@ -0,0 +1,44 @@
+"use client"
+
+import {
+  AnalyticsProvider,
+  ColorModeProvider,
+  MobileProvider,
+  ModalProvider,
+  NavbarProvider,
+  PageLoadingProvider,
+  ScrollControllerProvider,
+} from "docs-ui"
+import BaseSpecsProvider from "./base-specs"
+import SidebarProvider from "./sidebar"
+import SearchProvider from "./search"
+
+type ProvidersProps = {
+  children?: React.ReactNode
+}
+
+const Providers = ({ children }: ProvidersProps) => {
+  return (
+    <AnalyticsProvider writeKey={process.env.NEXT_PUBLIC_SEGMENT_API_KEY}>
+      <PageLoadingProvider>
+        <ModalProvider>
+          <ColorModeProvider>
+            <BaseSpecsProvider>
+              <SidebarProvider>
+                <NavbarProvider>
+                  <ScrollControllerProvider>
+                    <SearchProvider>
+                      <MobileProvider>{children}</MobileProvider>
+                    </SearchProvider>
+                  </ScrollControllerProvider>
+                </NavbarProvider>
+              </SidebarProvider>
+            </BaseSpecsProvider>
+          </ColorModeProvider>
+        </ModalProvider>
+      </PageLoadingProvider>
+    </AnalyticsProvider>
+  )
+}
+
+export default Providers

www/apps/api-reference/providers/loading.tsx

@@ -0,0 +1,45 @@
+import { createContext, useContext, useState } from "react"
+
+type LoadingContextType = {
+  loading: boolean
+  removeLoading: () => void
+}
+
+const LoadingContext = createContext<LoadingContextType | null>(null)
+
+type LoadingProviderProps = {
+  children: React.ReactNode
+  initialLoading?: boolean
+}
+
+const LoadingProvider = ({
+  children,
+  initialLoading = false,
+}: LoadingProviderProps) => {
+  const [loading, setLoading] = useState<boolean>(initialLoading)
+
+  const removeLoading = () => setLoading(false)
+
+  return (
+    <LoadingContext.Provider
+      value={{
+        loading,
+        removeLoading,
+      }}
+    >
+      {children}
+    </LoadingContext.Provider>
+  )
+}
+
+export default LoadingProvider
+
+export const useLoading = (): LoadingContextType => {
+  const context = useContext(LoadingContext)
+
+  if (!context) {
+    throw new Error("useLoading must be used inside a LoadingProvider")
+  }
+
+  return context
+}

www/apps/api-reference/providers/page-title.tsx

@@ -0,0 +1,43 @@
+"use client"
+
+import { createContext, useEffect } from "react"
+import { capitalize, useSidebar } from "docs-ui"
+import { useArea } from "./area"
+
+const PageTitleContext = createContext(null)
+
+type PageTitleProviderProps = {
+  children: React.ReactNode
+}
+
+const PageTitleProvider = ({ children }: PageTitleProviderProps) => {
+  const { activePath, getActiveItem } = useSidebar()
+  const { area } = useArea()
+
+  useEffect(() => {
+    const titleSuffix = `Medusa ${capitalize(area)} API Reference`
+
+    if (!activePath?.length) {
+      document.title = titleSuffix
+    } else {
+      const activeItem = getActiveItem()
+      if (activeItem?.path === activePath) {
+        document.title = `${activeItem?.title} - ${titleSuffix}`
+      } else {
+        // find the child that matches the active path
+        const item = activeItem?.children?.find((i) => i.path === activePath)
+        if (item) {
+          document.title = `${item.title} - ${titleSuffix}`
+        }
+      }
+    }
+  }, [activePath, area, getActiveItem])
+
+  return (
+    <PageTitleContext.Provider value={null}>
+      {children}
+    </PageTitleContext.Provider>
+  )
+}
+
+export default PageTitleProvider

www/apps/api-reference/providers/search.tsx

@@ -0,0 +1,75 @@
+"use client"
+
+import { usePageLoading, SearchProvider as UiSearchProvider } from "docs-ui"
+import getBaseUrl from "../utils/get-base-url"
+
+type SearchProviderProps = {
+  children: React.ReactNode
+}
+
+const SearchProvider = ({ children }: SearchProviderProps) => {
+  const { isLoading } = usePageLoading()
+  return (
+    <UiSearchProvider
+      algolia={{
+        appId: process.env.NEXT_PUBLIC_ALGOLIA_APP_ID || "temp",
+        apiKey: process.env.NEXT_PUBLIC_ALGOLIA_API_KEY || "temp",
+        mainIndexName: process.env.NEXT_PUBLIC_API_ALGOLIA_INDEX_NAME || "temp",
+        indices: [
+          process.env.NEXT_PUBLIC_API_ALGOLIA_INDEX_NAME || "temp",
+          process.env.NEXT_PUBLIC_DOCS_ALGOLIA_INDEX_NAME || "temp",
+        ],
+      }}
+      searchProps={{
+        isLoading,
+        suggestions: [
+          {
+            title: "Search Suggestions",
+            items: [
+              "Authentication",
+              "Expanding fields",
+              "Selecting fields",
+              "Pagination",
+              "Query parameter types",
+            ],
+          },
+        ],
+        checkInternalPattern: new RegExp(`^${getBaseUrl()}/api/(admin|store)`),
+        filterOptions: [
+          {
+            value: "admin",
+            label: "Admin API",
+          },
+          {
+            value: "store",
+            label: "Store API",
+          },
+          {
+            value: "docs",
+            label: "Docs",
+          },
+          {
+            value: "user-guide",
+            label: "User Guide",
+          },
+          {
+            value: "plugins",
+            label: "Plugins",
+          },
+          {
+            value: "reference",
+            label: "References",
+          },
+          {
+            value: "ui",
+            label: "UI",
+          },
+        ],
+      }}
+    >
+      {children}
+    </UiSearchProvider>
+  )
+}
+
+export default SearchProvider

www/apps/api-reference/providers/sidebar.tsx

@@ -0,0 +1,58 @@
+"use client"
+import { SidebarProvider as UiSidebarProvider, usePageLoading } from "docs-ui"
+
+type SidebarProviderProps = {
+  children?: React.ReactNode
+}
+
+const SidebarProvider = ({ children }: SidebarProviderProps) => {
+  const { isLoading, setIsLoading } = usePageLoading()
+
+  return (
+    <UiSidebarProvider
+      isLoading={isLoading}
+      setIsLoading={setIsLoading}
+      shouldHandleHashChange={true}
+      initialItems={{
+        top: [
+          {
+            title: "Introduction",
+            path: "",
+            loaded: true,
+          },
+        ],
+        bottom: [],
+        mobile: [
+          {
+            title: "Docs",
+            path: "https://docs.medusajs.com/",
+            loaded: true,
+            isPathHref: true,
+          },
+          {
+            title: "User Guide",
+            path: "https://docs.medusajs.com/user-guide",
+            loaded: true,
+            isPathHref: true,
+          },
+          {
+            title: "Store API",
+            path: "/api/store",
+            loaded: true,
+            isPathHref: true,
+          },
+          {
+            title: "Admin API",
+            path: "/api/admin",
+            loaded: true,
+            isPathHref: true,
+          },
+        ],
+      }}
+    >
+      {children}
+    </UiSidebarProvider>
+  )
+}
+
+export default SidebarProvider