docs: expanded rating form + UI docs improvement (#5211)

* docs: expanded rating form + UI docs improvement

* added props table + changed example

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>
       )}
     </>

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 = ({

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

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>
   )
 }

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`

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

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"
     )

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
+  )}`
 }