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/utils/check-element-in-viewport.ts

@@ -0,0 +1,16 @@
+export default function checkElementInViewport(
+  element: Element,
+  percentage = 100,
+  height?: number
+) {
+  const rect = element.getBoundingClientRect()
+  const windowHeight =
+    height || window.innerHeight || document.documentElement.clientHeight
+
+  return !(
+    Math.floor(100 - ((rect.top >= 0 ? 0 : rect.top) / +-rect.height) * 100) <
+      percentage ||
+    Math.floor(100 - ((rect.bottom - windowHeight) / rect.height) * 100) <
+      percentage
+  )
+}

www/apps/api-reference/utils/check-required.ts

@@ -0,0 +1,5 @@
+import type { SchemaObject } from "@/types/openapi"
+
+export default function checkRequired(schema: SchemaObject, property?: string) {
+  return property !== undefined && schema.required?.includes(property)
+}

www/apps/api-reference/utils/format-report-link.ts

@@ -0,0 +1,5 @@
+import { formatReportLink as uiFormatReportLink } from "docs-ui"
+
+export default function formatReportLink(area = "admin", sectionTitle: string) {
+  return uiFormatReportLink(`API Ref(${area})`, sectionTitle)
+}

www/apps/api-reference/utils/get-base-url.ts

@@ -0,0 +1,3 @@
+export default function getBaseUrl() {
+  return process.env.NEXT_PUBLIC_BASE_URL || "http://localhost:3000"
+}

www/apps/api-reference/utils/get-link-with-base-path.ts

@@ -0,0 +1,3 @@
+export default function getLinkWithBasePath(path: string): string {
+  return `${process.env.NEXT_PUBLIC_BASE_PATH || "/api"}${path}`
+}

www/apps/api-reference/utils/get-paths-of-tag.ts

@@ -0,0 +1,74 @@
+import path from "path"
+import { promises as fs } from "fs"
+import type { OpenAPIV3 } from "openapi-types"
+import type { Operation, Document } from "@/types/openapi"
+import readSpecDocument from "./read-spec-document"
+import getSectionId from "./get-section-id"
+import OpenAPIParser from "@readme/openapi-parser"
+
+type ParsedPathItemObject = OpenAPIV3.PathItemObject<Operation> & {
+  operationPath?: string
+}
+
+export default async function getPathsOfTag(
+  tagName: string,
+  area: string
+): Promise<Document> {
+  // get path files
+  const basePath = path.join(process.cwd(), `specs/${area}/paths`)
+
+  const files = await fs.readdir(basePath)
+
+  // read the path documents
+  let documents: ParsedPathItemObject[] = await Promise.all(
+    files.map(async (file) => {
+      const fileContent = (await readSpecDocument(
+        path.join(basePath, file)
+      )) as OpenAPIV3.PathItemObject<Operation>
+
+      return {
+        ...fileContent,
+        operationPath: `/${file
+          .replaceAll("_", "/")
+          .replace(/\.[A-Za-z]+$/, "")}`,
+      }
+    })
+  )
+
+  // filter out operations not related to the passed tag
+  documents = documents.filter((document) =>
+    Object.values(document).some((operation) => {
+      if (typeof operation !== "object" || !("tags" in operation)) {
+        return false
+      }
+
+      return operation.tags?.some((tag) => getSectionId([tag]) === tagName)
+    })
+  )
+
+  // dereference the references in the paths
+  let paths: Document = {
+    paths: {},
+    // These attributes are only for validation purposes
+    openapi: "3.0.0",
+    info: {
+      title: "Medusa API",
+      version: "1.0.0",
+    },
+  }
+
+  documents.forEach((document) => {
+    const documentPath = document.operationPath || ""
+    delete document.operationPath
+    paths.paths[documentPath] = document
+  })
+
+  // resolve references in paths
+  paths = (await OpenAPIParser.dereference(
+    `${basePath}/`,
+    paths,
+    {}
+  )) as unknown as Document
+
+  return paths
+}

www/apps/api-reference/utils/get-section-id.ts

@@ -0,0 +1,6 @@
+import slugify from "slugify"
+
+export default function getSectionId(path: string[]) {
+  path = path.map((p) => slugify(p.trim().toLowerCase()))
+  return path.join("_")
+}

www/apps/api-reference/utils/get-security-schema-type-name.ts

@@ -0,0 +1,16 @@
+import { OpenAPIV3 } from "openapi-types"
+
+export default function getSecuritySchemaTypeName(
+  securitySchema: OpenAPIV3.SecuritySchemeObject
+) {
+  switch (securitySchema.type) {
+    case "apiKey":
+      return "API Key"
+    case "http":
+      return "HTTP"
+    case "oauth2":
+      return "OAuth2"
+    case "openIdConnect":
+      return "OpenID Connect"
+  }
+}

www/apps/api-reference/utils/get-tag-child-sidebar-items.tsx

@@ -0,0 +1,35 @@
+import type { SidebarItemType } from "docs-ui"
+import type { Operation, PathsObject } from "@/types/openapi"
+import type { OpenAPIV3 } from "openapi-types"
+import dynamic from "next/dynamic"
+import type { MethodLabelProps } from "@/components/MethodLabel"
+import getSectionId from "./get-section-id"
+
+const MethodLabel = dynamic<MethodLabelProps>(
+  async () => import("../components/MethodLabel")
+) as React.FC<MethodLabelProps>
+
+export default function getTagChildSidebarItems(
+  paths: PathsObject
+): SidebarItemType[] {
+  const items: SidebarItemType[] = []
+  Object.entries(paths).forEach(([, operations]) => {
+    Object.entries(operations).map(([method, operation]) => {
+      const definedOperation = operation as Operation
+      const definedMethod = method as OpenAPIV3.HttpMethods
+      items.push({
+        path: getSectionId([
+          ...(definedOperation.tags || []),
+          definedOperation.operationId,
+        ]),
+        title: definedOperation.summary || definedOperation.operationId,
+        additionalElms: (
+          <MethodLabel method={definedMethod} className="h-fit" />
+        ),
+        loaded: true,
+      })
+    })
+  })
+
+  return items
+}

www/apps/api-reference/utils/get-url.ts

@@ -0,0 +1,5 @@
+import getBaseUrl from "./get-base-url"
+
+export default function getUrl(area: string, tagName?: string): string {
+  return `${getBaseUrl()}/api/${area}#${tagName}`
+}

www/apps/api-reference/utils/read-spec-document.ts

@@ -0,0 +1,8 @@
+import { promises as fs } from "fs"
+import { OpenAPIV3 } from "openapi-types"
+import { parseDocument } from "yaml"
+
+export default async function readSpecDocument(filePath: string) {
+  const fileContent = await fs.readFile(filePath, "utf-8")
+  return parseDocument(fileContent).toJS() as OpenAPIV3.PathItemObject
+}

www/apps/api-reference/utils/swr-fetcher.ts

@@ -0,0 +1,9 @@
+const fetcher = async <JSON = any>(
+  input: RequestInfo,
+  init?: RequestInit
+): Promise<JSON> => {
+  const res = await fetch(input, init)
+  return res.json()
+}
+
+export default fetcher