docs: preparations for preview (#7267)

* configured base paths + added development banner

* fix typelist site url

* added navbar and sidebar badges

* configure algolia filters

* remove AI assistant

* remove unused imports

* change navbar text and badge

* lint fixes

* fix build error

* add to api reference rewrites

* fix build error

* fix build errors in user-guide

* fix feedback component

* add parent title to pagination

* added breadcrumbs component

* remove user-guide links

* resolve todos

* fix details about authentication

* change documentation title

* lint content

www/packages/docs-ui/src/components/Bannerv2/index.tsx

@@ -0,0 +1,15 @@
+import React from "react"
+import { Card, Link } from "../.."
+
+export const Bannerv2 = () => {
+  return (
+    <Card>
+      This documentation is for Medusa v2, which isn&apos;t ready for
+      production.
+      <br />
+      <br />
+      For production-use, refer to{" "}
+      <Link href="https://docs.medusajs.com">this documentation</Link> instead.
+    </Card>
+  )
+}

www/packages/docs-ui/src/components/Breadcrumbs/index.tsx

@@ -0,0 +1,76 @@
+"use client"
+
+import React, { useMemo } from "react"
+import { CurrentItemsState, useSidebar } from "@/providers"
+import { TriangleRightMini } from "@medusajs/icons"
+import Link from "next/link"
+import clsx from "clsx"
+
+type BreadcrumbItem = Map<string, string>
+
+export const Breadcrumbs = () => {
+  const { currentItems } = useSidebar()
+
+  const getBreadcrumbsOfItem = (item: CurrentItemsState): BreadcrumbItem => {
+    let tempBreadcrumbItems: BreadcrumbItem = new Map()
+    if (item.previousSidebar) {
+      tempBreadcrumbItems = getBreadcrumbsOfItem(item.previousSidebar)
+    }
+
+    tempBreadcrumbItems.set(
+      item.parentItem?.path || item.top[0].path || "/",
+      item.parentItem?.childSidebarTitle || item.parentItem?.title || ""
+    )
+
+    return tempBreadcrumbItems
+  }
+
+  const breadcrumbItems = useMemo(() => {
+    const tempBreadcrumbItems: BreadcrumbItem = new Map()
+    if (!currentItems) {
+      return tempBreadcrumbItems
+    }
+
+    tempBreadcrumbItems.set("/", "Home")
+
+    getBreadcrumbsOfItem(currentItems).forEach((value, key) =>
+      tempBreadcrumbItems.set(key, value)
+    )
+
+    return tempBreadcrumbItems
+  }, [currentItems])
+
+  const getBreadcrumbItemElms = (): React.ReactNode[] => {
+    const elms: React.ReactNode[] = []
+    breadcrumbItems.forEach((title, path) => {
+      elms.push(
+        <React.Fragment key={path}>
+          {elms.length !== 0 && (
+            <TriangleRightMini className={clsx("text-medusa-fg-muted")} />
+          )}
+          <Link
+            href={path}
+            className={clsx(
+              "text-compact-x-small-plus text-medusa-fg-muted",
+              "hover:text-medusa-fg-subtle transition-colors"
+            )}
+          >
+            {title}
+          </Link>
+        </React.Fragment>
+      )
+    })
+
+    return elms
+  }
+
+  return (
+    <>
+      {breadcrumbItems.size > 0 && (
+        <div className="flex gap-docs_0.25 items-center mb-docs_1">
+          {...getBreadcrumbItemElms()}
+        </div>
+      )}
+    </>
+  )
+}

www/packages/docs-ui/src/components/Navbar/Link/index.tsx

@@ -2,7 +2,7 @@
 
 import React from "react"
 import clsx from "clsx"
-import { Link, LinkProps } from "@/components"
+import { Badge, BadgeProps, Link, LinkProps } from "@/components"
 
 export type NavbarLinkProps = {
   href: string
@@ -10,6 +10,7 @@ export type NavbarLinkProps = {
   className?: string
   activeValuePattern?: RegExp
   isActive?: boolean
+  badge?: BadgeProps
 } & LinkProps
 
 export const NavbarLink = ({
@@ -17,6 +18,7 @@ export const NavbarLink = ({
   label,
   className,
   isActive,
+  badge
 }: NavbarLinkProps) => {
   return (
     <Link
@@ -30,6 +32,10 @@ export const NavbarLink = ({
       )}
     >
       {label}
+      {badge && <Badge {...badge} className={clsx(
+        badge.className,
+        "ml-docs_0.5"
+      )} />}
     </Link>
   )
 }

www/packages/docs-ui/src/components/Navbar/Logo/index.tsx

@@ -4,6 +4,7 @@ import React from "react"
 import { useColorMode } from "@/providers"
 import Link from "next/link"
 import clsx from "clsx"
+import Image from "next/image"
 
 export type NavbarLogoProps = {
   light: string
@@ -22,7 +23,7 @@ export const NavbarLogo = ({
 
   return (
     <Link href={`/`} className={clsx("flex-1", className)}>
-      <img
+      <Image
         src={colorMode === "light" ? light : dark || light}
         alt="Medusa Logo"
         height={20}

www/packages/docs-ui/src/components/Navbar/NavbarDivider/index.tsx

@@ -0,0 +1,11 @@
+import clsx from "clsx"
+import React from "react"
+
+export const NavbarDivider = () => {
+  return (
+    <div className={clsx(
+      "w-px h-1/2 bg-medusa-fg-disabled",
+      "mx-docs_0.5"
+    )}></div>
+  )
+}

www/packages/docs-ui/src/components/Navbar/index.tsx

@@ -6,10 +6,19 @@ import { NavbarLogo, NavbarLogoProps } from "./Logo"
 import { NavbarMobileMenu } from "./MobileMenu"
 import { NavbarSearchModalOpener } from "./SearchModalOpener"
 import { NavbarMobileMenuButtonProps } from "./MobileMenu/Button"
+import { NavbarDivider } from "./NavbarDivider"
+
+export type NavbarItem = {
+  type: "link"
+  props: NavbarLinkProps
+} | {
+  type: "divider"
+  props?: {}
+}
 
 export type NavbarProps = {
   logo: NavbarLogoProps
-  items: NavbarLinkProps[]
+  items: NavbarItem[]
   showSearchOpener?: boolean
   showColorModeToggle?: boolean
   additionalActionsAfter?: React.ReactNode
@@ -45,9 +54,14 @@ export const Navbar = ({
       >
         <div className="hidden w-full items-center gap-docs_0.5 lg:flex lg:w-auto lg:gap-docs_1.5">
           <NavbarLogo {...logo} />
-          {items.map((item, index) => (
-            <NavbarLink key={index} {...item} />
-          ))}
+          {items.map(({type, props}, index) => {
+            switch(type) {
+              case "divider":
+                return <NavbarDivider key={index}  />
+              default:
+                return <NavbarLink key={index} {...props} />
+            }
+          })}
         </div>
         <div className="hidden min-w-0 flex-1 items-center justify-end gap-docs_0.5 lg:flex">
           {additionalActionsBefore}

www/packages/docs-ui/src/components/Pagination/index.tsx

@@ -13,6 +13,7 @@ export const Pagination = () => {
       {previousPage && (
         <Card
           title={previousPage.title}
+          text={previousPage.parentTitle}
           startIcon={<ChevronLeft />}
           showLinkIcon={false}
           href={previousPage.link}
@@ -22,6 +23,7 @@ export const Pagination = () => {
       {nextPage && (
         <Card
           title={nextPage.title}
+          text={nextPage.parentTitle}
           endIcon={<ChevronRight />}
           showLinkIcon={false}
           href={nextPage.link}

www/packages/docs-ui/src/components/Search/index.tsx

@@ -85,6 +85,9 @@ export const Search = ({
       <InstantSearch
         indexName={algolia.mainIndexName}
         searchClient={searchClient}
+        future={{
+          preserveSharedStateOnUnmount: true
+        }}
       >
         <div className={clsx("bg-medusa-bg-base flex")}>
           <SearchBox

www/packages/docs-ui/src/components/Sidebar/Back/index.tsx

@@ -11,7 +11,7 @@ export const SidebarBack = () => {
   return (
     <div
       className={clsx(
-        "my-docs_1.5 cursor-pointer",
+        "mb-docs_1.5 cursor-pointer",
         "flex items-center gap-docs_0.5 rounded-docs_sm px-docs_0.5 py-[6px] hover:no-underline",
         "border border-transparent",
         "text-medusa-fg-subtle text-medium-plus"

www/packages/docs-ui/src/components/Sidebar/Item/index.tsx

@@ -16,6 +16,8 @@ export type SidebarItemProps = {
   expandItems?: boolean
   currentLevel?: number
   isSidebarTitle?: boolean
+  sidebarHasParent?: boolean
+  isMobile?: boolean
 } & React.AllHTMLAttributes<HTMLLIElement>
 
 export const SidebarItem = ({
@@ -24,6 +26,8 @@ export const SidebarItem = ({
   expandItems = false,
   className,
   currentLevel = 1,
+  sidebarHasParent = false,
+  isMobile = false
 }: SidebarItemProps) => {
   const [showLoading, setShowLoading] = useState(false)
   const {
@@ -34,8 +38,8 @@ export const SidebarItem = ({
     sidebarRef,
   } = useSidebar()
   const active = useMemo(
-    () => isItemActive(item, nested),
-    [isItemActive, item, nested]
+    () => !isMobile && isItemActive(item, nested),
+    [isItemActive, item, nested, isMobile]
   )
   const collapsed = !expandItems && !isItemActive(item, true)
   const ref = useRef<HTMLLIElement>(null)
@@ -131,7 +135,11 @@ export const SidebarItem = ({
   return (
     <li
       className={clsx(
-        canHaveTitleStyling && !collapsed && "my-docs_1.5",
+        canHaveTitleStyling &&
+          !collapsed && [
+            !sidebarHasParent && "my-docs_1.5",
+            sidebarHasParent && "[&:not(:first-child)]:my-docs_1.5",
+          ],
         !canHaveTitleStyling &&
           !nested &&
           active &&

www/packages/docs-ui/src/components/Sidebar/Title/index.tsx

@@ -11,9 +11,9 @@ export const SidebarTitle = ({ item }: SidebarTitleProps) => {
   return (
     <Link
       className={clsx(
-        "flex items-center justify-between gap-docs_0.5 rounded-docs_sm px-docs_0.5 py-[6px] hover:no-underline",
+        "flex items-center justify-between gap-docs_0.5 rounded-docs_sm px-docs_0.5 pb-[6px] hover:no-underline",
         "border border-transparent",
-        "text-medusa-fg-subtle text-medium-plus"
+        "text-medusa-fg-subtle text-large-plus"
       )}
       href={item.isPathHref && item.path ? item.path : `#${item.path}`}
       replace={!item.isPathHref}

www/packages/docs-ui/src/components/Sidebar/index.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import React, { useMemo } from "react"
+import React, { useMemo, useRef } from "react"
 import { useSidebar } from "@/providers"
 import clsx from "clsx"
 import { Loading } from "@/components"
@@ -12,11 +12,13 @@ import { CSSTransition, SwitchTransition } from "react-transition-group"
 export type SidebarProps = {
   className?: string
   expandItems?: boolean
+  banner?: React.ReactNode
 }
 
 export const Sidebar = ({
   className = "",
   expandItems = false,
+  banner,
 }: SidebarProps) => {
   const {
     items,
@@ -32,6 +34,11 @@ export const Sidebar = ({
     [items, currentItems]
   )
 
+  const sidebarHasParent = useMemo(
+    () => sidebarItems.parentItem !== undefined,
+    [sidebarItems]
+  )
+
   return (
     <aside
       className={clsx(
@@ -47,69 +54,76 @@ export const Sidebar = ({
         animationFillMode: "forwards",
       }}
     >
-      <SwitchTransition>
-        <CSSTransition
-          key={sidebarItems.parentItem?.title || "home"}
-          nodeRef={sidebarRef}
-          classNames={{
-            enter: "animate-fadeInLeft animate-fast",
-            exit: "animate-fadeOutLeft animate-fast",
-          }}
-          timeout={200}
-        >
-          <ul
-            className={clsx(
-              "sticky top-0 h-screen max-h-screen w-full list-none overflow-auto p-0",
-              "px-docs_1.5 pb-[57px] pt-docs_1.5"
-            )}
-            id="sidebar"
-            ref={sidebarRef}
+      <ul
+        className={clsx(
+          "sticky top-0 h-screen max-h-screen w-full list-none p-0",
+          "px-docs_1.5 pb-[57px] pt-docs_1.5",
+          "flex flex-col"
+        )}
+        id="sidebar"
+      >
+        {banner && <div className="mb-docs_1">{banner}</div>}
+        {sidebarItems.parentItem && (
+          <div className={clsx("mb-docs_1", !banner && "mt-docs_1.5")}>
+            <SidebarBack />
+            <SidebarTitle item={sidebarItems.parentItem} />
+          </div>
+        )}
+        <SwitchTransition>
+          <CSSTransition
+            key={sidebarItems.parentItem?.title || "home"}
+            nodeRef={sidebarRef}
+            classNames={{
+              enter: "animate-fadeInLeft animate-fast",
+              exit: "animate-fadeOutLeft animate-fast",
+            }}
+            timeout={200}
           >
-            {sidebarItems.parentItem && (
-              <>
-                <SidebarBack />
-                <SidebarTitle item={sidebarItems.parentItem} />
-              </>
-            )}
-            <div className="mb-docs_1.5 lg:hidden">
-              {!sidebarItems.mobile.length && !staticSidebarItems && (
-                <Loading className="px-0" />
-              )}
-              {sidebarItems.mobile.map((item, index) => (
-                <SidebarItem
-                  item={item}
-                  key={index}
-                  expandItems={expandItems}
-                />
-              ))}
+            <div className="overflow-auto" ref={sidebarRef}>
+              <div className={clsx("mb-docs_1.5 lg:hidden")}>
+                {!sidebarItems.mobile.length && !staticSidebarItems && (
+                  <Loading className="px-0" />
+                )}
+                {sidebarItems.mobile.map((item, index) => (
+                  <SidebarItem
+                    item={item}
+                    key={index}
+                    expandItems={expandItems}
+                    sidebarHasParent={sidebarHasParent}
+                    isMobile={true}
+                  />
+                ))}
+              </div>
+              <div className={clsx("mb-docs_1.5")}>
+                {!sidebarItems.top.length && !staticSidebarItems && (
+                  <Loading className="px-0" />
+                )}
+                {sidebarItems.top.map((item, index) => (
+                  <SidebarItem
+                    item={item}
+                    key={index}
+                    expandItems={expandItems}
+                    sidebarHasParent={sidebarHasParent}
+                  />
+                ))}
+              </div>
+              <div className="mb-docs_1.5">
+                {!sidebarItems.bottom.length && !staticSidebarItems && (
+                  <Loading className="px-0" />
+                )}
+                {sidebarItems.bottom.map((item, index) => (
+                  <SidebarItem
+                    item={item}
+                    key={index}
+                    expandItems={expandItems}
+                    sidebarHasParent={sidebarHasParent}
+                  />
+                ))}
+              </div>
             </div>
-            <div className="mb-docs_1.5">
-              {!sidebarItems.top.length && !staticSidebarItems && (
-                <Loading className="px-0" />
-              )}
-              {sidebarItems.top.map((item, index) => (
-                <SidebarItem
-                  item={item}
-                  key={index}
-                  expandItems={expandItems}
-                />
-              ))}
-            </div>
-            <div className="mb-docs_1.5">
-              {!sidebarItems.bottom.length && !staticSidebarItems && (
-                <Loading className="px-0" />
-              )}
-              {sidebarItems.bottom.map((item, index) => (
-                <SidebarItem
-                  item={item}
-                  key={index}
-                  expandItems={expandItems}
-                />
-              ))}
-            </div>
-          </ul>
-        </CSSTransition>
-      </SwitchTransition>
+          </CSSTransition>
+        </SwitchTransition>
+      </ul>
     </aside>
   )
 }

www/packages/docs-ui/src/components/TypeList/Items/index.tsx

@@ -21,7 +21,7 @@ import {
 } from "@medusajs/icons"
 import { decodeStr, isInView } from "@/utils"
 import { usePathname } from "next/navigation"
-import { useIsBrowser } from "../../.."
+import { useIsBrowser, useSiteConfig } from "../../.."
 
 type CommonProps = ParentCommonProps & {
   level?: number
@@ -39,10 +39,11 @@ const TypeListItem = ({
   expandUrl,
   elementKey,
   sectionTitle,
-  siteUrl = "",
 }: TypeListItemProps) => {
   const isBrowser = useIsBrowser()
   const pathname = usePathname()
+  const { config: { baseUrl, basePath } } = useSiteConfig()
+  const siteUrl = `${baseUrl}${basePath}`
 
   const groupName = useMemo(() => {
     switch (level) {

www/packages/docs-ui/src/components/TypeList/index.tsx

@@ -5,7 +5,6 @@ import { Loading } from "@/components"
 export type CommonProps = {
   expandUrl?: string
   sectionTitle?: string
-  siteUrl?: string
 }
 
 export type Type = {
@@ -30,7 +29,6 @@ const TypeListItems = lazy(async () => import("./Items"))
 export const TypeList = ({
   types,
   className,
-  siteUrl,
   sectionTitle,
   expandUrl,
   ...props
@@ -48,7 +46,6 @@ export const TypeList = ({
           types={types}
           expandUrl={expandUrl}
           sectionTitle={sectionTitle}
-          siteUrl={siteUrl}
         />
       </Suspense>
     </div>

www/packages/docs-ui/src/components/index.ts

@@ -1,8 +1,10 @@
 export * from "./AiAssistant"
 export * from "./AiAssistant/CommandIcon"
 export * from "./Badge"
+export * from "./Bannerv2"
 export * from "./Bordered"
 export * from "./BorderedIcon"
+export * from "./Breadcrumbs"
 export * from "./Button"
 export * from "./Card"
 export * from "./CardList"