docs: added note in API reference clarifying what schemas are (#11116)

* docs: added note in API reference clarifying what schemas are

* add yarn lock

www/apps/api-reference/components/Tags/Section/Schema/index.tsx

@@ -7,6 +7,8 @@ import {
   Badge,
   CodeBlock,
   isElmWindow,
+  Link,
+  Note,
   useIsBrowser,
   useScrollController,
   useSidebar,
@@ -20,6 +22,7 @@ import { InView } from "react-intersection-observer"
 import checkElementInViewport from "../../../../utils/check-element-in-viewport"
 import { singular } from "pluralize"
 import clsx from "clsx"
+import { useArea } from "../../../../providers/area"
 
 export type TagSectionSchemaProps = {
   schema: SchemaObject
@@ -29,6 +32,7 @@ export type TagSectionSchemaProps = {
 const TagSectionSchema = ({ schema, tagName }: TagSectionSchemaProps) => {
   const paramsRef = useRef<HTMLDivElement>(null)
   const { addItems, setActivePath, activePath } = useSidebar()
+  const { displayedArea } = useArea()
   const tagSlugName = useMemo(() => getSectionId([tagName]), [tagName])
   const formattedName = useMemo(
     () => singular(tagName).replaceAll(" ", ""),
@@ -129,6 +133,16 @@ const TagSectionSchema = ({ schema, tagName }: TagSectionSchemaProps) => {
             mainContent={
               <div>
                 <h2>{formattedName} Object</h2>
+                <Note>
+                  This object&apos;s schema is as returned by Medusa&apos;s{" "}
+                  {displayedArea} API routes. However, the related model in the
+                  Medusa application may support more fields and relations. To
+                  view the models in the Medusa application and their relations,
+                  visit the{" "}
+                  <Link href="https://docs.medusajs.com/resources/commerce-modules">
+                    Commerce Modules Documentation
+                  </Link>
+                </Note>
                 <h4 className="border-medusa-border-base border-b py-1.5 mt-2">
                   Fields
                 </h4>

www/apps/api-reference/providers/area.tsx

@@ -1,12 +1,13 @@
 "use client"
 
 import type { Area } from "@/types/openapi"
-import { usePrevious, useSearch } from "docs-ui"
+import { capitalize, usePrevious, useSearch } from "docs-ui"
-import { createContext, useContext, useEffect, useState } from "react"
+import { createContext, useContext, useEffect, useMemo, useState } from "react"
 
 type AreaContextType = {
   area: Area
   prevArea: Area | undefined
+  displayedArea: string
   setArea: (value: Area) => void
 }
 
@@ -22,6 +23,10 @@ const AreaProvider = ({ area: passedArea, children }: AreaProviderProps) => {
   const prevArea = usePrevious(area)
   const { defaultFilters, setDefaultFilters } = useSearch()
 
+  const displayedArea = useMemo(() => {
+    return capitalize(area)
+  }, [area])
+
   useEffect(() => {
     if (!defaultFilters.includes(`${area}-v2`)) {
       setDefaultFilters([`${area}-v2`])
@@ -34,6 +39,7 @@ const AreaProvider = ({ area: passedArea, children }: AreaProviderProps) => {
         area,
         prevArea,
         setArea,
+        displayedArea,
       }}
     >
       {children}

www/apps/api-reference/providers/page-title.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import { createContext, useEffect } from "react"
-import { capitalize, useSidebar } from "docs-ui"
+import { useSidebar } from "docs-ui"
 import { useArea } from "./area"
 import { SidebarItemLink } from "types"
 
@@ -13,10 +13,10 @@ type PageTitleProviderProps = {
 
 const PageTitleProvider = ({ children }: PageTitleProviderProps) => {
   const { activePath, activeItem } = useSidebar()
-  const { area } = useArea()
+  const { displayedArea } = useArea()
 
   useEffect(() => {
-    const titleSuffix = `Medusa ${capitalize(area)} API Reference`
+    const titleSuffix = `Medusa ${displayedArea} API Reference`
 
     if (!activePath?.length) {
       document.title = titleSuffix
@@ -33,7 +33,7 @@ const PageTitleProvider = ({ children }: PageTitleProviderProps) => {
         }
       }
     }
-  }, [activePath, area, activeItem])
+  }, [activePath, displayedArea, activeItem])
 
   return (
     <PageTitleContext.Provider value={null}>

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

@@ -4,14 +4,13 @@ import type { LinkProps as NextLinkProps } from "next/link"
 import clsx from "clsx"
 import { TriangleRightMini } from "@medusajs/icons"
 
-export type LinkProps = {
+export type LinkProps = Partial<NextLinkProps> &
-  href?: string
+  React.AllHTMLAttributes<HTMLAnchorElement> & {
-  children?: React.ReactNode
+    href?: string
-  className?: string
+    children?: React.ReactNode
-  target?: string
+    className?: string
-  rel?: string
+    withIcon?: boolean
-  withIcon?: boolean
+  }
-} & Partial<NextLinkProps>
 
 export const Link = ({
   href,

www/yarn.lock

@@ -1676,53 +1676,50 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@medusajs/icons@npm:^1.2.1":
+"@medusajs/icons@npm:^1.2.2":
-  version: 1.2.1
+  version: 1.2.2
-  resolution: "@medusajs/icons@npm:1.2.1"
+  resolution: "@medusajs/icons@npm:1.2.2"
   peerDependencies:
     react: ^16.x || ^17.x || ^18.x
-  checksum: bdda0af295d5cd83682b5689a8fc711a03639b7d4eb5aa2a6648e99af969363ec942dc7fe3cb21e27b6b70ea5a94a9e1b5e10b28f57ae4c7211a8807f84200c8
+  checksum: 610117b959ddbd68f927caa12e70fb5fc849e8c68a25ca38f4d137aca1363f36552455aa83669847bd42753cccf36ad57b82f9bd5be7794e5b23af1046f78967
   languageName: node
   linkType: hard
 
-"@medusajs/icons@npm:^2.0.0":
+"@medusajs/icons@npm:^2.2.0":
-  version: 2.0.0
+  version: 2.3.1
-  resolution: "@medusajs/icons@npm:2.0.0"
+  resolution: "@medusajs/icons@npm:2.3.1"
   peerDependencies:
-    react: ^16.x || ^17.x || ^18.x
+    react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
-  checksum: 4cffedba777c08abc038b3bdb384c65233ef9921cd0c3132489d8ec18b146249df23b1a0492bdb3671125b435ee035db40eb2587dae1171c2bf0d3fdaba44345
+  checksum: ad37dc6061e89661b6a1158edceb8efa3106b5a8fe0284e600372133ca42a16d4f8c9575066d94cf07facf0ed28a20abf06b2d7f20cdf8b744b9eaa564322ee5
   languageName: node
   linkType: hard
 
-"@medusajs/ui-preset@npm:^1.1.2":
+"@medusajs/icons@npm:~2.0.0":
-  version: 1.1.2
+  version: 2.0.7
-  resolution: "@medusajs/ui-preset@npm:1.1.2"
+  resolution: "@medusajs/icons@npm:2.0.7"
+  peerDependencies:
+    react: ^16.x || ^17.x || ^18.x
+  checksum: 84d9d0c8fe2fb3174e286291a86292f80a71a1582b4e8bcba001bcf061a8a4b7654c88bc80c69aee6fd68961e618011e059641c92174eba413e380e148a7ea52
+  languageName: node
+  linkType: hard
+
+"@medusajs/ui-preset@npm:~1.1.2, @medusajs/ui-preset@npm:~1.1.3":
+  version: 1.1.4
+  resolution: "@medusajs/ui-preset@npm:1.1.4"
   dependencies:
     "@tailwindcss/forms": ^0.5.3
     tailwindcss-animate: ^1.0.6
   peerDependencies:
     tailwindcss: ">=3.0.0"
-  checksum: 63b525eee5d5a6a7d2d9596f6cc9015c221a3a55c83f524511d35eeb6916261baeae472e8748725480016a38e379f6a1a34e373d4ca824bbabdb151605086f94
+  checksum: 49ffcecc49c9971fe4e195b46fde3da9c3c0e8e12c7cbf0ab6186ffd71a4027019603e72496288d32742add61905e621318d379ac2dcaea6ed2d0330efecbe3c
   languageName: node
   linkType: hard
 
-"@medusajs/ui-preset@npm:^1.1.3":
+"@medusajs/ui@npm:~3.0.0":
-  version: 1.1.3
+  version: 3.0.1
-  resolution: "@medusajs/ui-preset@npm:1.1.3"
+  resolution: "@medusajs/ui@npm:3.0.1"
   dependencies:
-    "@tailwindcss/forms": ^0.5.3
+    "@medusajs/icons": ^1.2.2
-    tailwindcss-animate: ^1.0.6
-  peerDependencies:
-    tailwindcss: ">=3.0.0"
-  checksum: 36b3cbe3d1b3ab2666abe84499dc19a57fe88e886704ca82b42105b5ba078638c6af8d2032d09da12d2324c485966ef2840f6a06192690b986b3c5f025308c68
-  languageName: node
-  linkType: hard
-
-"@medusajs/ui@npm:^3.0.0":
-  version: 3.0.0
-  resolution: "@medusajs/ui@npm:3.0.0"
-  dependencies:
-    "@medusajs/icons": ^1.2.1
     "@radix-ui/react-accordion": ^1.1.2
     "@radix-ui/react-alert-dialog": ^1.0.4
     "@radix-ui/react-avatar": ^1.0.3
@@ -1754,15 +1751,15 @@ __metadata:
   peerDependencies:
     react: ^18.0.0
     react-dom: ^18.0.0
-  checksum: 06d34783a4954f51ef3a5282e59cb3fd367f58d435739525a543af84213fc22c745f10849f0178fdf7c4e19bda3872a7e3ca628e1f4498ac03c95affa98b5266
+  checksum: 07284402f4cb8c24937f4330c7217bf909fa0fb923f545cafbe24a8aa5a467d179d76d723c9faaea74516766444d6beb4ba8248496e70dbfd2750ea87383c9ad
   languageName: node
   linkType: hard
 
-"@medusajs/ui@npm:^4.0.0":
+"@medusajs/ui@npm:~4.0.0":
-  version: 4.0.0
+  version: 4.0.3
-  resolution: "@medusajs/ui@npm:4.0.0"
+  resolution: "@medusajs/ui@npm:4.0.3"
   dependencies:
-    "@medusajs/icons": ^2.0.0
+    "@medusajs/icons": ^2.2.0
     "@radix-ui/react-accordion": 1.2.0
     "@radix-ui/react-alert-dialog": 1.1.1
     "@radix-ui/react-avatar": 1.1.0
@@ -1789,9 +1786,9 @@ __metadata:
     sonner: ^1.5.0
     tailwind-merge: ^2.2.1
   peerDependencies:
-    react: ^18.0.0
+    react: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
-    react-dom: ^18.0.0
+    react-dom: ^18.0.0 || ^19.0.0 || ^19.0.0-rc
-  checksum: e4a8ebb9f937c081067e16de43c78401b2f7b17c8005f00b3be607a91326463e3ccdc7df7384100ca53199d26d3a7f961cbd3610f2fbae2336ba0c66a2dd0218
+  checksum: 8f45adfc52c2d6500c748bf0bd08bf3b9a4eeb0fa848f27c50521474b6572a97cf76a91ee8370d1d9af26575e6ab8048ec2c95156219456d3bfc608984321690
   languageName: node
   linkType: hard
 
@@ -6789,8 +6786,8 @@ __metadata:
   dependencies:
     "@mdx-js/loader": ^3.1.0
     "@mdx-js/react": ^3.1.0
-    "@medusajs/icons": ^2.0.0
+    "@medusajs/icons": ~2.0.0
-    "@medusajs/ui": ^3.0.0
+    "@medusajs/ui": ~3.0.0
     "@next/bundle-analyzer": 15.0.4
     "@next/mdx": 15.0.4
     "@react-hook/resize-observer": ^2.0.2
@@ -7131,7 +7128,7 @@ __metadata:
   dependencies:
     "@mdx-js/loader": ^3.1.0
     "@mdx-js/react": ^3.1.0
-    "@medusajs/icons": ^2.0.0
+    "@medusajs/icons": ~2.0.0
     "@next/mdx": 15.0.4
     "@types/mdx": ^2.0.13
     "@types/node": ^20
@@ -8430,8 +8427,8 @@ __metadata:
   resolution: "docs-ui@workspace:packages/docs-ui"
   dependencies:
     "@emotion/is-prop-valid": ^1.3.1
-    "@medusajs/icons": ^2.0.0
+    "@medusajs/icons": ~2.0.0
-    "@medusajs/ui": ^4.0.0
+    "@medusajs/ui": ~4.0.0
     "@next/third-parties": 15.0.4
     "@octokit/request": ^8.1.1
     "@react-hook/resize-observer": ^1.2.6
@@ -14830,7 +14827,7 @@ __metadata:
   dependencies:
     "@mdx-js/loader": ^3.1.0
     "@mdx-js/react": ^3.1.0
-    "@medusajs/icons": ^2.0.0
+    "@medusajs/icons": ~2.0.0
     "@next/bundle-analyzer": ^15.1.1
     "@next/mdx": 15.0.4
     "@types/mdx": ^2.0.13
@@ -15713,7 +15710,7 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "tailwind@workspace:packages/tailwind"
   dependencies:
-    "@medusajs/ui-preset": ^1.1.2
+    "@medusajs/ui-preset": ~1.1.2
     tailwindcss-animate: ^1.0.7
   peerDependencies:
     docs-ui: "*"
@@ -16270,7 +16267,7 @@ turbo@latest:
   version: 0.0.0-use.local
   resolution: "types@workspace:packages/types"
   dependencies:
-    "@medusajs/icons": ^2.0.0
+    "@medusajs/icons": ~2.0.0
     "@types/node": ^20.11.20
     rimraf: ^5.0.5
     tsconfig: "*"
@@ -16358,9 +16355,9 @@ turbo@latest:
   dependencies:
     "@faker-js/faker": ^8.0.2
     "@mdx-js/react": ^3.1.0
-    "@medusajs/icons": ^2.0.0
+    "@medusajs/icons": ~2.0.0
-    "@medusajs/ui": ^4.0.0
+    "@medusajs/ui": ~4.0.0
-    "@medusajs/ui-preset": ^1.1.3
+    "@medusajs/ui-preset": ~1.1.3
     "@types/node": 20.4.9
     "@types/react": "npm:types-react@rc"
     "@types/react-dom": "npm:types-react@rc"
@@ -16736,7 +16733,7 @@ turbo@latest:
   dependencies:
     "@mdx-js/loader": ^3.1.0
     "@mdx-js/react": ^3.1.0
-    "@medusajs/icons": ^2.0.0
+    "@medusajs/icons": ~2.0.0
     "@next/mdx": 15.0.4
     "@types/mdx": ^2.0.13
     "@types/node": ^20