From 987dd8f5681697a443b9281c8e01c39ea83424b8 Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Tue, 26 Sep 2023 20:26:09 +0300
Subject: [PATCH] docs: expanded rating form + UI docs improvement (#5211)

* docs: expanded rating form + UI docs improvement

* added props table + changed example
---
 www/apps/docs/src/hooks/use-onboarding.tsx    |   7 +-
 www/apps/ui/src/components/feedback.tsx       |   2 +-
 www/apps/ui/src/components/mdx-components.tsx |  14 ++
 .../content/docs/components/focus-modal.mdx   |  27 ++++
 www/apps/ui/src/props/focus-modal.tsx         |  26 ++++
 www/apps/ui/src/registries/prop-registry.tsx  |   3 +
 .../Item/Layout/Default/index.tsx             |   4 +-
 .../components/Notification/Item/index.tsx    |   1 +
 .../src/components/Notification/index.tsx     |  13 +-
 .../docs-ui/src/components/Rating/index.tsx   | 142 ++++++++++++------
 www/packages/docs-ui/src/constants.ts         |   1 +
 .../docs-ui/src/providers/Analytics/index.tsx |  85 ++++++++---
 .../src/providers/Notification/index.tsx      |   6 +-
 .../docs-ui/src/utils/format-report-link.ts   |  20 ++-
 www/packages/tailwind/base.tailwind.config.js |  20 +++
 15 files changed, 285 insertions(+), 86 deletions(-)
 create mode 100644 www/apps/ui/src/props/focus-modal.tsx

diff --git a/www/apps/docs/src/hooks/use-onboarding.tsx b/www/apps/docs/src/hooks/use-onboarding.tsx
index a7bf5d496a..ef7f8a6a6f 100644
--- a/www/apps/docs/src/hooks/use-onboarding.tsx
+++ b/www/apps/docs/src/hooks/use-onboarding.tsx
@@ -22,9 +22,12 @@ const useOnboarding = () => {
         children: (
           <Rating
             event="rating_onboarding"
-            onRating={() => {
-              setTimeout(() => removeNotification(id), 1500)
+            onRating={(rating?: number) => {
+              if (rating >= 4) {
+                setTimeout(() => removeNotification(id), 1500)
+              }
             }}
+            parentNotificationId={id}
           />
         ),
       })
diff --git a/www/apps/ui/src/components/feedback.tsx b/www/apps/ui/src/components/feedback.tsx
index 0972a25108..b337e4874c 100644
--- a/www/apps/ui/src/components/feedback.tsx
+++ b/www/apps/ui/src/components/feedback.tsx
@@ -20,7 +20,7 @@ export const Feedback = ({ title, ...props }: FeedbackProps) => {
     <UiFeedback
       event="survey"
       pathName={absoluteUrl(pathname)}
-      reportLink={formatReportLink("UI Docs", title)}
+      reportLink={formatReportLink("UI Docs", title, "ui")}
       extraData={{
         section: title,
       }}
diff --git a/www/apps/ui/src/components/mdx-components.tsx b/www/apps/ui/src/components/mdx-components.tsx
index 58a1928f92..c9ed8ea0de 100644
--- a/www/apps/ui/src/components/mdx-components.tsx
+++ b/www/apps/ui/src/components/mdx-components.tsx
@@ -91,6 +91,20 @@ const components = {
       </ul>
     )
   },
+  ol: ({
+    className,
+    children,
+    ...props
+  }: React.HTMLAttributes<HTMLOListElement>) => {
+    return (
+      <ul
+        {...props}
+        className={clsx("list-decimal px-docs_1 mb-docs_1.5", className)}
+      >
+        {children}
+      </ul>
+    )
+  },
   li: ({
     className,
     children,
diff --git a/www/apps/ui/src/content/docs/components/focus-modal.mdx b/www/apps/ui/src/content/docs/components/focus-modal.mdx
index f1a6e8fb1d..c13966d535 100644
--- a/www/apps/ui/src/content/docs/components/focus-modal.mdx
+++ b/www/apps/ui/src/content/docs/components/focus-modal.mdx
@@ -30,6 +30,8 @@ import { FocusModal } from "@medusajs/ui"
 
 This component is based on the [Radix UI Dialog](https://www.radix-ui.com/primitives/docs/components/dialog) primitives.
 
+<ComponentProps component="focus-modal" />
+
 ### FocusModal.Header
 
 This component is based on the `div` element and supports all props of this element.
@@ -37,3 +39,28 @@ This component is based on the `div` element and supports all props of this elem
 ### FocusModal.Body
 
 This component is based on the `div` element and supports all props of this element.
+
+## Example: Control Open State
+
+---
+
+```tsx
+import { useState } from "react"
+
+const MyModal = () => {
+  const [open, setOpen] = useState(false)
+
+  return (
+    <FocusModal 
+      open={open} 
+      onOpenChange={setOpen}
+    >
+      <FocusModal.Trigger>Trigger</FocusModal.Trigger>
+      <FocusModal.Content>
+        <FocusModal.Header>Title</FocusModal.Header>
+        <FocusModal.Body>Content</FocusModal.Body>
+      </FocusModal.Content>
+    </FocusModal>
+  )
+}
+```
\ No newline at end of file
diff --git a/www/apps/ui/src/props/focus-modal.tsx b/www/apps/ui/src/props/focus-modal.tsx
new file mode 100644
index 0000000000..144564cf3e
--- /dev/null
+++ b/www/apps/ui/src/props/focus-modal.tsx
@@ -0,0 +1,26 @@
+import { PropTable } from "@/components/props-table"
+import { PropDataMap } from "@/types/props"
+
+const focusModalProps: PropDataMap = [
+  {
+    prop: "defaultOpen",
+    type: "boolean",
+  },
+  {
+    prop: "open",
+    type: "boolean",
+  },
+  {
+    prop: "onOpenChange",
+    type: {
+      type: "function",
+      signature: `(open: boolean) => void`,
+    },
+  },
+]
+
+const Props = () => {
+  return <PropTable props={focusModalProps} />
+}
+
+export default Props
diff --git a/www/apps/ui/src/registries/prop-registry.tsx b/www/apps/ui/src/registries/prop-registry.tsx
index ccefb663ac..1ee9ebba0f 100644
--- a/www/apps/ui/src/registries/prop-registry.tsx
+++ b/www/apps/ui/src/registries/prop-registry.tsx
@@ -29,6 +29,9 @@ export const PropRegistry: Record<string, PropRegistryItem> = {
   "date-picker": {
     table: React.lazy(async () => import("../props/date-picker")),
   },
+  "focus-modal": {
+    table: React.lazy(async () => import("../props/focus-modal")),
+  },
   heading: {
     table: React.lazy(async () => import("../props/heading")),
   },
diff --git a/www/packages/docs-ui/src/components/Notification/Item/Layout/Default/index.tsx b/www/packages/docs-ui/src/components/Notification/Item/Layout/Default/index.tsx
index 7a91577e89..5824975acc 100644
--- a/www/packages/docs-ui/src/components/Notification/Item/Layout/Default/index.tsx
+++ b/www/packages/docs-ui/src/components/Notification/Item/Layout/Default/index.tsx
@@ -11,6 +11,7 @@ import { Button } from "@/components"
 
 export type NotificationItemLayoutDefaultProps = NotificationItemProps & {
   handleClose: () => void
+  closeButtonText?: string
 }
 
 export const NotificationItemLayoutDefault: React.FC<
@@ -23,6 +24,7 @@ export const NotificationItemLayoutDefault: React.FC<
   isClosable = true,
   handleClose,
   CustomIcon,
+  closeButtonText = "Close",
 }) => {
   return (
     <>
@@ -74,7 +76,7 @@ export const NotificationItemLayoutDefault: React.FC<
       )}
       {isClosable && (
         <div className={clsx("p-docs_1 flex justify-end items-center")}>
-          <Button onClick={handleClose}>Close</Button>
+          <Button onClick={handleClose}>{closeButtonText}</Button>
         </div>
       )}
     </>
diff --git a/www/packages/docs-ui/src/components/Notification/Item/index.tsx b/www/packages/docs-ui/src/components/Notification/Item/index.tsx
index ccb1cf6fbe..d4598d25e9 100644
--- a/www/packages/docs-ui/src/components/Notification/Item/index.tsx
+++ b/www/packages/docs-ui/src/components/Notification/Item/index.tsx
@@ -15,6 +15,7 @@ export type NotificationItemProps = {
   show?: boolean
   setShow?: (value: boolean) => void
   onClose?: () => void
+  closeButtonText?: string
 } & React.HTMLAttributes<HTMLDivElement>
 
 export const NotificationItem = ({
diff --git a/www/packages/docs-ui/src/components/Notification/index.tsx b/www/packages/docs-ui/src/components/Notification/index.tsx
index 6fd439a80e..1e0bec8dfe 100644
--- a/www/packages/docs-ui/src/components/Notification/index.tsx
+++ b/www/packages/docs-ui/src/components/Notification/index.tsx
@@ -1,11 +1,16 @@
-import { NotificationItemType, useNotifications } from "@/providers"
+import {
+  NotificationContextType,
+  NotificationItemType,
+  useNotifications,
+} from "@/providers"
 import React from "react"
 import { NotificationItem } from "./Item"
 import { CSSTransition, TransitionGroup } from "react-transition-group"
 import clsx from "clsx"
 
 export const NotificationContainer = () => {
-  const { notifications, removeNotification } = useNotifications()
+  const { notifications, removeNotification } =
+    useNotifications() as NotificationContextType
 
   const handleClose = (notification: NotificationItemType) => {
     notification.onClose?.()
@@ -25,8 +30,8 @@ export const NotificationContainer = () => {
             key={notification.id}
             timeout={200}
             classNames={{
-              enter: "animate__animated animate__slideInRight animate__fastest",
-              exit: "animate__animated animate__slideOutRight animate__fastest",
+              enter: "animate-slideInRight animate-fast",
+              exit: "animate-slideOutRight animate-fast",
             }}
           >
             <NotificationItem
diff --git a/www/packages/docs-ui/src/components/Rating/index.tsx b/www/packages/docs-ui/src/components/Rating/index.tsx
index 81a47be813..4759425a7f 100644
--- a/www/packages/docs-ui/src/components/Rating/index.tsx
+++ b/www/packages/docs-ui/src/components/Rating/index.tsx
@@ -1,27 +1,47 @@
 "use client"
 
-import React, { useRef, useState } from "react"
+import React, { useCallback, useEffect, useRef, useState } from "react"
 import clsx from "clsx"
 import { Star, StarSolid } from "@medusajs/icons"
-import { Button } from "@/components"
-import { useAnalytics } from "@/providers"
+import { Button, Label, TextArea } from "@/components"
+import { useAnalytics, useNotifications } from "@/providers"
 
 export type RatingProps = {
   event?: string
   className?: string
-  onRating?: () => void
+  onRating?: (rating?: number) => void
+  additionalQuestion?: string
+  parentNotificationId?: string
 } & React.HTMLAttributes<HTMLDivElement>
 
 export const Rating: React.FC<RatingProps> = ({
   event = "rating",
   className = "",
   onRating,
+  additionalQuestion = "What should we improve?",
+  parentNotificationId,
 }) => {
   const [rating, setRating] = useState(0)
+  const [additionalFeedback, setAdditionalFeedback] = useState("")
   const [hoverRating, setHoverRating] = useState(0)
   const starElms = useRef<HTMLElement[]>([])
   const starArr = Array.from(Array(5).keys())
   const { track } = useAnalytics()
+  const { updateNotification } = useNotifications(true) || {}
+
+  const submitTracking = useCallback(
+    (selectedRating?: number, feedback?: string) => {
+      track(
+        event,
+        {
+          rating: selectedRating || rating,
+          additionalFeedback: feedback || additionalFeedback,
+        },
+        () => onRating?.(selectedRating || rating)
+      )
+    },
+    [rating, additionalFeedback]
+  )
 
   const handleRating = (selectedRating: number) => {
     if (rating) {
@@ -29,52 +49,82 @@ export const Rating: React.FC<RatingProps> = ({
     }
     setHoverRating(0)
     setRating(selectedRating)
-    for (let i = 0; i < selectedRating; i++) {
-      starElms.current[i].classList.add("animate-tada")
+    if (selectedRating >= 4) {
+      for (let i = 0; i < selectedRating; i++) {
+        starElms.current[i].classList.add("animate-tada")
+      }
+      submitTracking(selectedRating)
     }
-    track(
-      event,
-      {
-        rating: selectedRating,
-      },
-      () => onRating?.()
-    )
   }
 
+  useEffect(() => {
+    if (
+      rating > 0 &&
+      rating < 4 &&
+      parentNotificationId &&
+      updateNotification
+    ) {
+      // update parent notification ID
+      updateNotification(parentNotificationId, {
+        closeButtonText: "Submit",
+        onClose: () => submitTracking(rating, additionalFeedback),
+      })
+    }
+  }, [additionalFeedback, rating])
+
   return (
-    <div className={clsx("flex gap-docs_0.5", className)}>
-      {starArr.map((i) => {
-        const isSelected =
-          (rating !== 0 && rating - 1 >= i) ||
-          (hoverRating !== 0 && hoverRating - 1 >= i)
-        return (
-          <Button
-            variant="clear"
-            buttonRef={(element) => {
-              if (starElms.current.length - 1 < i) {
-                starElms.current.push(element as HTMLElement)
-              }
-            }}
-            key={i}
-            onMouseOver={() => {
-              if (!rating) {
-                setHoverRating(i + 1)
-              }
-            }}
-            onMouseLeave={() => {
-              if (!rating) {
-                setHoverRating(0)
-              }
-            }}
-            onClick={() => handleRating(i + 1)}
-          >
-            {!isSelected && <Star />}
-            {isSelected && (
-              <StarSolid className="text-medusa-tag-orange-icon" />
-            )}
-          </Button>
-        )
-      })}
+    <div className={clsx("flex flex-col gap-docs_1")}>
+      <div className={clsx("flex gap-docs_0.5", className)}>
+        {starArr.map((i) => {
+          const isSelected =
+            (rating !== 0 && rating - 1 >= i) ||
+            (hoverRating !== 0 && hoverRating - 1 >= i)
+          return (
+            <Button
+              variant="clear"
+              buttonRef={(element) => {
+                if (starElms.current.length - 1 < i) {
+                  starElms.current.push(element as HTMLElement)
+                }
+              }}
+              key={i}
+              onMouseOver={() => {
+                if (!rating) {
+                  setHoverRating(i + 1)
+                }
+              }}
+              onMouseLeave={() => {
+                if (!rating) {
+                  setHoverRating(0)
+                }
+              }}
+              onClick={() => handleRating(i + 1)}
+            >
+              {!isSelected && <Star />}
+              {isSelected && (
+                <StarSolid className="text-medusa-tag-orange-icon" />
+              )}
+            </Button>
+          )
+        })}
+      </div>
+      {rating !== 0 && rating < 4 && (
+        <div
+          className={clsx(
+            "text-medusa-fg-subtle",
+            "flex flex-col gap-docs_0.5"
+          )}
+        >
+          <Label>{additionalQuestion}</Label>
+          <TextArea
+            placeholder="I didn't like..."
+            rows={4}
+            onChange={(e) => setAdditionalFeedback(e.target.value)}
+            value={additionalFeedback}
+            className="w-full"
+          />
+        </div>
+      )}
     </div>
   )
 }
diff --git a/www/packages/docs-ui/src/constants.ts b/www/packages/docs-ui/src/constants.ts
index 534856358c..c941d9512d 100644
--- a/www/packages/docs-ui/src/constants.ts
+++ b/www/packages/docs-ui/src/constants.ts
@@ -1 +1,2 @@
 export const GITHUB_ISSUES_PREFIX = `https://github.com/medusajs/medusa/issues/new?assignees=&labels=type%3A+docs&template=docs.yml`
+export const GITHUB_UI_ISSUES_PREFIX = `https://github.com/medusajs/ui/issues/new?labels=documentation`
diff --git a/www/packages/docs-ui/src/providers/Analytics/index.tsx b/www/packages/docs-ui/src/providers/Analytics/index.tsx
index ee7c5c7f2e..16e9203a1a 100644
--- a/www/packages/docs-ui/src/providers/Analytics/index.tsx
+++ b/www/packages/docs-ui/src/providers/Analytics/index.tsx
@@ -1,6 +1,12 @@
 "use client"
 
-import React, { createContext, useContext, useEffect, useState } from "react"
+import React, {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useState,
+} from "react"
 import { Analytics, AnalyticsBrowser } from "@segment/analytics-next"
 
 export type ExtraData = {
@@ -18,6 +24,11 @@ export type AnalyticsContextType = {
   ) => void
 }
 
+export type TrackedEvent = {
+  event: string
+  options?: Record<string, any>
+}
+
 const AnalyticsContext = createContext<AnalyticsContextType | null>(null)
 
 export type AnalyticsProviderProps = {
@@ -37,8 +48,9 @@ export const AnalyticsProvider = ({
   const [loaded, setLoaded] = useState<boolean>(false)
   const [analytics, setAnalytics] = useState<Analytics | null>(null)
   const analyticsBrowser = new AnalyticsBrowser()
+  const [queue, setQueue] = useState<TrackedEvent[]>([])
 
-  const init = () => {
+  const init = useCallback(() => {
     if (!loaded) {
       analyticsBrowser
         .load(
@@ -60,33 +72,56 @@ export const AnalyticsProvider = ({
         )
         .finally(() => setLoaded(true))
     }
-  }
+  }, [loaded, writeKey])
 
-  const track = async (
-    event: string,
-    options?: Record<string, any>,
-    callback?: () => void
-  ) => {
-    if (analytics) {
-      void analytics.track(
-        event,
-        {
-          ...options,
-          uuid: analytics.user().anonymousId(),
-        },
-        callback
-      )
-    } else if (callback) {
-      console.warn(
-        "Segment is either not installed or not configured. Simulating success..."
-      )
-      callback()
-    }
-  }
+  const track = useCallback(
+    async (
+      event: string,
+      options?: Record<string, any>,
+      callback?: () => void
+    ) => {
+      if (analytics) {
+        void analytics.track(
+          event,
+          {
+            ...options,
+            uuid: analytics.user().anonymousId(),
+          },
+          callback
+        )
+      } else {
+        // push the event into the queue
+        setQueue((prevQueue) => [
+          ...prevQueue,
+          {
+            event,
+            options,
+          },
+        ])
+        if (callback) {
+          console.warn(
+            "Segment is either not installed or not configured. Simulating success..."
+          )
+          callback()
+        }
+      }
+    },
+    [analytics, loaded]
+  )
 
   useEffect(() => {
     init()
-  }, [])
+  }, [init])
+
+  useEffect(() => {
+    if (analytics && queue.length) {
+      // track stuff in queue
+      queue.forEach(async (trackEvent) =>
+        track(trackEvent.event, trackEvent.options)
+      )
+      setQueue([])
+    }
+  }, [analytics, queue])
 
   return (
     <AnalyticsContext.Provider
diff --git a/www/packages/docs-ui/src/providers/Notification/index.tsx b/www/packages/docs-ui/src/providers/Notification/index.tsx
index 5cd1466d5b..71c252fe22 100644
--- a/www/packages/docs-ui/src/providers/Notification/index.tsx
+++ b/www/packages/docs-ui/src/providers/Notification/index.tsx
@@ -122,10 +122,12 @@ export const NotificationProvider = ({
   )
 }
 
-export const useNotifications = (): NotificationContextType => {
+export const useNotifications = (
+  suppressError?: boolean
+): NotificationContextType | null => {
   const context = useContext(NotificationContext)
 
-  if (!context) {
+  if (!context && !suppressError) {
     throw new Error(
       "useNotifications must be used within a NotificationProvider"
     )
diff --git a/www/packages/docs-ui/src/utils/format-report-link.ts b/www/packages/docs-ui/src/utils/format-report-link.ts
index cfa9e42fef..1c46846153 100644
--- a/www/packages/docs-ui/src/utils/format-report-link.ts
+++ b/www/packages/docs-ui/src/utils/format-report-link.ts
@@ -1,7 +1,17 @@
-import { GITHUB_ISSUES_PREFIX } from "../constants"
+import { GITHUB_ISSUES_PREFIX, GITHUB_UI_ISSUES_PREFIX } from "../constants"
 
-export function formatReportLink(title: string, sectionTitle: string) {
-  return `${GITHUB_ISSUES_PREFIX}&title=${encodeURI(
-    title
-  )}%3A%20Issue%20in%20${encodeURI(sectionTitle)}`
+export type ReportLinkType = "default" | "ui"
+
+export function formatReportLink(
+  title: string,
+  sectionTitle: string,
+  type?: ReportLinkType
+) {
+  let prefix = GITHUB_ISSUES_PREFIX
+  if (type === "ui") {
+    prefix = GITHUB_UI_ISSUES_PREFIX
+  }
+  return `${prefix}&title=${encodeURI(title)}%3A%20Issue%20in%20${encodeURI(
+    sectionTitle
+  )}`
 }
diff --git a/www/packages/tailwind/base.tailwind.config.js b/www/packages/tailwind/base.tailwind.config.js
index 6a0086ec5a..102d60f979 100644
--- a/www/packages/tailwind/base.tailwind.config.js
+++ b/www/packages/tailwind/base.tailwind.config.js
@@ -459,11 +459,31 @@ module.exports = {
             transform: "scale3d(1, 1, 1)",
           },
         },
+        slideInRight: {
+          from: {
+            transform: "translate3d(100%, 0, 0)",
+            visibility: "visible",
+          },
+          to: {
+            transform: "translate3d(0, 0, 0)",
+          },
+        },
+        slideOutRight: {
+          from: {
+            transform: "translate3d(0, 0, 0)",
+          },
+          to: {
+            visibility: "hidden",
+            transform: "translate3d(100%, 0, 0)",
+          },
+        },
       },
       animation: {
         fadeIn: "fadeIn 500ms",
         fadeOut: "fadeOut 500ms",
         tada: "tada 1s",
+        slideInRight: "slideInRight 500ms",
+        slideOutRight: "slideOutRight 500ms",
       },
     },
     fontFamily: {