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

@@ -22,9 +22,12 @@ const useOnboarding = () => {
         children: (
           <Rating
             event="rating_onboarding"
-            onRating={() => {
+            onRating={(rating?: number) => {
+              if (rating >= 4) {
                 setTimeout(() => removeNotification(id), 1500)
+              }
             }}
+            parentNotificationId={id}
           />
         ),
       })

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

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,

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

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

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

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",
+              enter: "animate-slideInRight animate-fast",
-              exit: "animate__animated animate__slideOutRight animate__fastest",
+              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 { Button, Label, TextArea } from "@/components"
-import { useAnalytics } from "@/providers"
+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,19 +49,31 @@ export const Rating: React.FC<RatingProps> = ({
     }
     setHoverRating(0)
     setRating(selectedRating)
+    if (selectedRating >= 4) {
       for (let i = 0; i < selectedRating; i++) {
         starElms.current[i].classList.add("animate-tada")
       }
-    track(
+      submitTracking(selectedRating)
-      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 flex-col gap-docs_1")}>
       <div className={clsx("flex gap-docs_0.5", className)}>
         {starArr.map((i) => {
           const isSelected =
@@ -76,5 +108,23 @@ export const Rating: React.FC<RatingProps> = ({
           )
         })}
       </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,9 +72,10 @@ export const AnalyticsProvider = ({
         )
         .finally(() => setLoaded(true))
     }
-  }
+  }, [loaded, writeKey])
 
-  const track = async (
+  const track = useCallback(
+    async (
       event: string,
       options?: Record<string, any>,
       callback?: () => void
@@ -76,17 +89,39 @@ export const AnalyticsProvider = ({
           },
           callback
         )
-    } else if (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) {
+export type ReportLinkType = "default" | "ui"
-  return `${GITHUB_ISSUES_PREFIX}&title=${encodeURI(
+
-    title
+export function formatReportLink(
-  )}%3A%20Issue%20in%20${encodeURI(sectionTitle)}`
+  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
+  )}`
 }

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: {