docs: add integrations page (#7421)

* add integrations page * update payment provider docs * use stripe icon
2024-05-28 13:25:03 +03:00
parent c9de1d28a4
commit 65be42c818
13 changed files with 218 additions and 41 deletions
--- a/www/apps/resources/app/architectural-modules/cache/page.mdx
+++ b/www/apps/resources/app/architectural-modules/cache/page.mdx
@@ -18,7 +18,7 @@ By default, Medusa uses the In-Memory Cache Module. This module uses a plain Jav

 This is useful for development. However, for production, it's highly recommended to use other Cache Modules, such as the Redis Cache Module.

-<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
+<ChildDocs type="item" hideItems={["Guides"]} onlyTopLevel={true} />

 ---

--- a/www/apps/resources/app/architectural-modules/event/page.mdx
+++ b/www/apps/resources/app/architectural-modules/event/page.mdx
@@ -18,7 +18,7 @@ By default, Medusa uses the Local Event Module. This module uses Node’s EventE

 This is useful for development. However, for production, it’s highly recommended to use other Event Modules, Redis Event Module.

-<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
+<ChildDocs type="item" hideItems={["Guides"]} onlyTopLevel={true} />

 ---

--- a/www/apps/resources/app/architectural-modules/file/page.mdx
+++ b/www/apps/resources/app/architectural-modules/file/page.mdx
@@ -18,7 +18,7 @@ By default, Medusa uses the Local File Module. This module uploads files to the

 This is useful for development. However, for production, it’s highly recommended to use other File Modules, such as the S3 Module.

-<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
+<ChildDocs type="item" hideItems={["Guides"]} onlyTopLevel={true} />

 ---

--- a/www/apps/resources/app/architectural-modules/notification/page.mdx
+++ b/www/apps/resources/app/architectural-modules/notification/page.mdx
@@ -20,7 +20,7 @@ By default, Medusa uses the Local Notification Module which only simulates sendi

 Medusa provides other Notification Modules that actually send notifications, such as the SendGrid Notification Provider Module.

-<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
+<ChildDocs type="item" hideItems={["Guides"]} onlyTopLevel={true} />

 ---

--- a/www/apps/resources/app/architectural-modules/page.mdx
+++ b/www/apps/resources/app/architectural-modules/page.mdx
@@ -8,4 +8,4 @@ export const metadata = {

 This section includes documentation for official Medusa architectural modules.

-<ChildDocs filters={["Guides"]} />
+<ChildDocs hideItems={["Guides"]} />
--- a/www/apps/resources/app/architectural-modules/workflow-engine/page.mdx
+++ b/www/apps/resources/app/architectural-modules/workflow-engine/page.mdx
@@ -10,4 +10,4 @@ Workflow engine modules handle tracking and recording the transactions and statu

 Medusa uses the In-Memory Workflow Engine Module by default. For production purposes, it's recommended to use the Redis Engine Module instead.

-<ChildDocs type="item" filters={["Guides"]} onlyTopLevel={true} />
+<ChildDocs type="item" hideItems={["Guides"]} onlyTopLevel={true} />
--- a/www/apps/resources/app/commerce-modules/payment/payment-provider/page.mdx
+++ b/www/apps/resources/app/commerce-modules/payment/payment-provider/page.mdx
@@ -1,19 +1,25 @@
+import { ChildDocs } from "docs-ui"
+
 export const metadata = {
-  title: `Payment Provider`,
+  title: `Payment Provider Module`,
 }

 # {metadata.title}

-In this document, you’ll learn what a payment provider is.
+In this document, you’ll learn what a payment provider module is.

-## What's a Payment Provider?
+## What's a Payment Provider Module?

-A payment provider handles payment processing. It can integrate third-party payment providers, such as Stripe or PayPal.
+A payment provider module registers a payment provider that handles payment processing. It can integrate third-party payment providers, such as Stripe.

 To authorize a payment amount with a payment provider, a payment session is created and associated with that payment provider. The payment provider is then used to handle the authorization.

 After the payment session is authorized, the payment provider is associated with the resulting payment and handles its payment processing, such as to capture or refund payment.

+### List of Payment Provider Modules
+
+<ChildDocs type="item" />
+
 ---

 ## System Payment Provider
@@ -24,7 +30,7 @@ The Payment Module provides a `system` payment provider that acts as a placehold

 ## How are Payment Providers Created?

-A payment provider is a TypeScript or JavaScript class that extends the `AbstractPaymentProvider` imported from `@medusajs/utils`. It can then be used in a payment plugin or exported in a provider module.
+A payment provider is a TypeScript or JavaScript class that extends the `AbstractPaymentProvider` imported from `@medusajs/utils`. It can then be exported as the main service of a module.

 <Note title="Tip">

--- a/www/apps/resources/app/integrations/page.mdx
+++ b/www/apps/resources/app/integrations/page.mdx
@@ -0,0 +1,31 @@
+import { ChildDocs } from "docs-ui"
+
+export const metadata = {
+  title: `Integrations`,
+}
+
+# {metadata.title}
+
+Find in this document Medusa's modules that integrate third-party services and systems.
+
+## Payment
+
+Learn how to create a payment provider in [this guide](/references/payment/provider).
+
+<ChildDocs showItems={["Payment"]} hideTitle />
+
+---
+
+## Notification
+
+Learn how to create a payment provider in [this guide](/references/notification-provider-module).
+
+<ChildDocs showItems={["Notification"]} hideTitle />
+
+---
+
+## File
+
+Learn how to create a payment provider in [this guide](/references/file-provider-module).
+
+<ChildDocs showItems={["File"]} hideTitle />
--- a/www/apps/resources/app/page.mdx
+++ b/www/apps/resources/app/page.mdx
@@ -6,7 +6,6 @@ import {
  UsersSolid,
  PuzzleSolid,
  EnvelopeSolid,
-  MagnifyingGlass,
  ArrowDownTray,
  ChartBar,
  Text,
@@ -17,7 +16,9 @@ import {
  NextJs,
  BuildingStorefront,
  CreditCardSolid,
-  ClockSolid
+  ClockSolid,
+  DocumentTextSolid,
+  Stripe
 } from "@medusajs/icons"

 # Medusa Learning Resources
@@ -69,34 +70,38 @@ Follow the [Medusa Book](https://medusa-docs-v2-git-docs-v2-medusajs.vercel.app)
  }
 ]} />

-{/* ## Plugins
+---
+
+## Integrations

 <CardList items={[
+  {
+    startIcon: <Stripe className="[&>path]:fill-medusa-fg-subtle" />,
+    title: "Stripe",
+    href: "/commerce-modules/payment/payment-provider/stripe",
+    showLinkIcon: false
+  },
  {
    startIcon: <EnvelopeSolid />,
    title: "SendGrid",
-    href: "/plugins/notifications/sendgrid",
+    href: "/architectural-modules/notification/sendgrid",
    showLinkIcon: false
  },
  {
-    startIcon: <MagnifyingGlass />,
-    title: "MeiliSearch",
-    href: "/plugins/search/meilisearch",
-    showLinkIcon: false
-  },
-  {
-    startIcon: <ChartBar />,
-    title: "Segment",
-    href: "/plugins/analytics/segment",
+    startIcon: <DocumentTextSolid />,
+    title: "S3",
+    href: "/architectural-modules/file/s3",
    showLinkIcon: false
  },
  {
    startIcon: <SquaresPlusSolid />,
-    title: "More Plugins",
-    href: "/plugins",
+    title: "More Integrations",
+    href: "/integrations",
    showLinkIcon: false
  }
-]} /> */}
+]} />
+
+---

 ## SDKs and Tools

--- a/www/apps/resources/generated/files-map.mjs
+++ b/www/apps/resources/generated/files-map.mjs
@@ -807,6 +807,10 @@ export const filesMap = [
    "filePath": "/www/apps/resources/app/globals.css",
    "pathname": "/"
  },
+  {
+    "filePath": "/www/apps/resources/app/integrations/page.mdx",
+    "pathname": "/integrations"
+  },
  {
    "filePath": "/www/apps/resources/app/js-client/page.mdx",
    "pathname": "/js-client"
--- a/www/apps/resources/generated/sidebar.mjs
+++ b/www/apps/resources/generated/sidebar.mjs
@@ -2892,8 +2892,16 @@ export const generatedSidebar = [
                "loaded": true,
                "isPathHref": true,
                "path": "/commerce-modules/payment/payment-provider",
-                "title": "Payment Provider",
-                "children": []
+                "title": "Payment Provider Module",
+                "children": [
+                  {
+                    "loaded": true,
+                    "isPathHref": true,
+                    "path": "/commerce-modules/payment/payment-provider/stripe",
+                    "title": "Stripe",
+                    "children": []
+                  }
+                ]
              },
              {
                "loaded": true,
@@ -5672,6 +5680,61 @@ export const generatedSidebar = [
      }
    ]
  },
+  {
+    "loaded": true,
+    "isPathHref": true,
+    "path": "/integrations",
+    "title": "Integrations",
+    "isChildSidebar": true,
+    "hasTitleStyling": true,
+    "children": [
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "title": "File",
+        "hasTitleStyling": true,
+        "children": [
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "path": "/architectural-modules/file/s3",
+            "title": "AWS S3 (and Compatible APIs)",
+            "children": []
+          }
+        ]
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "title": "Notification",
+        "hasTitleStyling": true,
+        "children": [
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "path": "/architectural-modules/notification/sendgrid",
+            "title": "SendGrid",
+            "children": []
+          }
+        ]
+      },
+      {
+        "loaded": true,
+        "isPathHref": true,
+        "title": "Payment",
+        "hasTitleStyling": true,
+        "children": [
+          {
+            "loaded": true,
+            "isPathHref": true,
+            "path": "/commerce-modules/payment/payment-provider/stripe",
+            "title": "Stripe",
+            "children": []
+          }
+        ]
+      }
+    ]
+  },
  {
    "loaded": true,
    "isPathHref": true,
--- a/www/apps/resources/sidebar.mjs
+++ b/www/apps/resources/sidebar.mjs
@@ -567,7 +567,13 @@ export const sidebar = sidebarAttachHrefCommonOptions([
              },
              {
                path: "/commerce-modules/payment/payment-provider",
-                title: "Payment Provider",
+                title: "Payment Provider Module",
+                children: [
+                  {
+                    path: "/commerce-modules/payment/payment-provider/stripe",
+                    title: "Stripe",
+                  },
+                ],
              },
              {
                path: "/commerce-modules/payment/payment-flow",
@@ -1169,6 +1175,44 @@ export const sidebar = sidebarAttachHrefCommonOptions([
      },
    ],
  },
+  {
+    path: "/integrations",
+    title: "Integrations",
+    isChildSidebar: true,
+    hasTitleStyling: true,
+    children: [
+      {
+        title: "File",
+        hasTitleStyling: true,
+        children: [
+          {
+            path: "/architectural-modules/file/s3",
+            title: "AWS S3 (and Compatible APIs)",
+          },
+        ],
+      },
+      {
+        title: "Notification",
+        hasTitleStyling: true,
+        children: [
+          {
+            path: "/architectural-modules/notification/sendgrid",
+            title: "SendGrid",
+          },
+        ],
+      },
+      {
+        title: "Payment",
+        hasTitleStyling: true,
+        children: [
+          {
+            path: "/commerce-modules/payment/payment-provider/stripe",
+            title: "Stripe",
+          },
+        ],
+      },
+    ],
+  },
  {
    title: "SDKs and Tools",
    hasTitleStyling: true,
--- a/www/packages/docs-ui/src/components/ChildDocs/index.tsx
+++ b/www/packages/docs-ui/src/components/ChildDocs/index.tsx
@@ -7,26 +7,50 @@ import { SidebarItemType } from "types"
 type ChildDocsProps = {
  onlyTopLevel?: boolean
  type?: "sidebar" | "item"
-  filters?: string[]
+  hideItems?: string[]
+  showItems?: string[]
+  hideTitle?: boolean
 }

 export const ChildDocs = ({
  onlyTopLevel = false,
-  filters = [],
+  hideItems = [],
+  showItems,
  type = "sidebar",
+  hideTitle = false,
 }: ChildDocsProps) => {
  const { currentItems, getActiveItem } = useSidebar()
+  const filterType = useMemo(() => {
+    return showItems !== undefined
+      ? "show"
+      : hideItems.length > 0
+      ? "hide"
+      : "all"
+  }, [showItems, hideItems])
+
+  const filterCondition = (item: SidebarItemType): boolean => {
+    switch (filterType) {
+      case "hide":
+        return (
+          (!item.path || !hideItems.includes(item.path)) &&
+          !hideItems.includes(item.title)
+        )
+      case "show":
+        return (
+          (item.path !== undefined && showItems!.includes(item.path)) ||
+          showItems!.includes(item.title)
+        )
+      case "all":
+        return true
+    }
+  }

  const filterItems = (items: SidebarItemType[]): SidebarItemType[] => {
    return items
-      .filter(
-        (item) =>
-          (!item.path || !filters.includes(item.path)) &&
-          !filters.includes(item.title)
-      )
+      .filter(filterCondition)
      .map((item) => Object.assign({}, item))
      .map((item) => {
-        if (item.children) {
+        if (item.children && filterType === "hide") {
          item.children = filterItems(item.children)
        }

@@ -44,7 +68,7 @@ export const ChildDocs = ({
            top: [...(getActiveItem()?.children || [])],
            bottom: [],
          }
-    if (!filters.length || !targetItems) {
+    if (filterType === "all" || !targetItems) {
      return targetItems
    }

@@ -53,7 +77,7 @@ export const ChildDocs = ({
      top: filterItems(targetItems.top),
      bottom: filterItems(targetItems.bottom),
    }
-  }, [currentItems, type, getActiveItem])
+  }, [currentItems, type, getActiveItem, filterItems])

  const getTopLevelElms = (items?: SidebarItemType[]) => (
    <CardList
@@ -77,7 +101,7 @@ export const ChildDocs = ({
        <React.Fragment key={key}>
          {HeadingComponent && (
            <>
-              <HeadingComponent>{item.title}</HeadingComponent>
+              {!hideTitle && <HeadingComponent>{item.title}</HeadingComponent>}
              <CardList
                items={
                  item.children?.map((childItem) => ({