medusa-ui-home 3.0.2 → 3.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medusa-ui-home",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "Homepage sections.",
   "type": "module",
   "license": "MIT",
@@ -21,11 +21,11 @@
     "lodash": ">=4",
     "lucide-react": "*",
     "medusa-plugin-dynamic-config": ">=0.0.31",
-    "medusa-ui-home-config": "^1.1.0",
+    "medusa-ui-home-config": "^1.0.0",
     "medusa-contact-logic-plugin": "^2.0.0",
     "medusa-reviews-logic": "^2.0.0",
     "medusa-storefront-analytics": "^1.0.0",
-    "medusa-storefront-data": "^2.5.3",
+    "medusa-storefront-data": "^2.0.0",
     "medusa-storefront-hooks": "^1.0.0",
     "medusa-wishlist-logic": "^2.0.0",
     "medusa-storefront-theme-base": "^3.0.0",
@@ -122,6 +122,11 @@
       "import": "./src/home/sections/testimonials/index.ts",
       "default": "./src/home/sections/testimonials/index.ts"
     },
+    "./sections/customerStories": {
+      "types": "./src/home/sections/customerStories/index.ts",
+      "import": "./src/home/sections/customerStories/index.ts",
+      "default": "./src/home/sections/customerStories/index.ts"
+    },
     "./sections/brandPillars": {
       "types": "./src/home/sections/brandPillars/index.ts",
       "import": "./src/home/sections/brandPillars/index.ts",
@@ -161,16 +166,6 @@
       "types": "./src/home/sections/blogPosts/index.ts",
       "import": "./src/home/sections/blogPosts/index.ts",
       "default": "./src/home/sections/blogPosts/index.ts"
-    },
-    "./catalog/page": {
-      "types": "./src/home/catalog/page.tsx",
-      "import": "./src/home/catalog/page.tsx",
-      "default": "./src/home/catalog/page.tsx"
-    },
-    "./components/home-page-json-ld": {
-      "types": "./src/home/components/home-page-json-ld.tsx",
-      "import": "./src/home/components/home-page-json-ld.tsx",
-      "default": "./src/home/components/home-page-json-ld.tsx"
     }
   },
   "typesVersions": {
@@ -192,11 +187,11 @@
     "@types/react-dom": "^18.3.5",
     "next": "^15.0.0",
     "typescript": "^5.6.0",
-    "medusa-storefront-analytics": "workspace:*",
-    "medusa-storefront-data": "workspace:*",
-    "medusa-storefront-theme-base": "workspace:*",
-    "medusa-ui-common": "workspace:*",
-    "medusa-ui-product": "workspace:*",
-    "medusa-ui-home-config": "workspace:*"
+    "medusa-storefront-analytics": "1.5.1",
+    "medusa-storefront-data": "2.5.9",
+    "medusa-storefront-theme-base": "3.0.1",
+    "medusa-ui-common": "3.0.1",
+    "medusa-ui-product": "3.0.2",
+    "medusa-ui-home-config": "1.1.3"
   }
 }

package/src/home/catalog/components/hero-banner.tsx

@@ -2,21 +2,23 @@ import Image from "next/image"
 import LocalizedClientLink from "medusa-ui-common/common/components/localized-client-link"
 import type { HomepageBanner } from "medusa-storefront-data/dynamic-config"
 
+export type CatalogHeroCopy = {
+  badge?: string
+  desktopHeadingLine1?: string
+  desktopHeadingHighlight?: string
+  description?: string
+  primaryCtaLabel?: string
+  primaryCtaHref?: string
+  secondaryCtaLabel?: string
+  secondaryCtaHref?: string
+  mobilePrimaryCtaLabel?: string
+  mobileSecondaryCtaLabel?: string
+}
+
 type CatalogHeroBannerProps = {
   homeBanners?: HomepageBanner[] | null
   appBanners?: HomepageBanner[] | null
-  copy?: {
-    badge?: string
-    desktopHeadingLine1?: string
-    desktopHeadingHighlight?: string
-    description?: string
-    primaryCtaLabel?: string
-    primaryCtaHref?: string
-    secondaryCtaLabel?: string
-    secondaryCtaHref?: string
-    mobilePrimaryCtaLabel?: string
-    mobileSecondaryCtaLabel?: string
-  }
+  copy?: CatalogHeroCopy
 }
 
 export default function CatalogHeroBanner({
@@ -24,23 +26,15 @@ export default function CatalogHeroBanner({
   appBanners,
   copy,
 }: CatalogHeroBannerProps) {
-  const fallbackBanner: HomepageBanner = {
-    image: "/newbanner.png",
-    title: "Premium Kids Shop",
-    subtitle: "Little Trends, Quality Kids Wear",
-    description:
-      "Shop stylish kids wear for little ones and children of all years - from newborn up to 15 years.",
-    buttonName: "Shop Kids Wear",
-    buttonLink: "/store",
-  }
+  const homeBanner = homeBanners?.[0]
+  const firstAppBanner = appBanners?.[0]
 
-  const homeBanner =
-    homeBanners && homeBanners.length > 0 ? homeBanners[0] : fallbackBanner
-  const firstAppBanner = appBanners && appBanners.length > 0 ? appBanners[0] : null
+  if (!homeBanner?.image) {
+    return null
+  }
 
-  const homeBannerImage = homeBanner.image || fallbackBanner.image
   const appBanner = {
-    image: firstAppBanner?.image || "/appbanner.png",
+    image: firstAppBanner?.image || homeBanner.image,
     title: firstAppBanner?.title || homeBanner.title,
     subtitle: firstAppBanner?.subtitle || homeBanner.subtitle,
     description: firstAppBanner?.description || homeBanner.description,
@@ -48,35 +42,35 @@ export default function CatalogHeroBanner({
     buttonLink: firstAppBanner?.buttonLink || homeBanner.buttonLink,
   }
 
-  const heroBadge = copy?.badge ?? "BEST QUALITY"
-  const desktopHeadingLine1 = copy?.desktopHeadingLine1 ?? "Electronics &"
+  const headlineFromCms = Boolean(homeBanner.subtitle?.trim())
+  const heroBadge = homeBanner.title ?? copy?.badge ?? "BEST QUALITY"
+  const desktopHeadingLine1 =
+    homeBanner.subtitle ?? copy?.desktopHeadingLine1 ?? "Electronics &"
   const desktopHeadingHighlight = copy?.desktopHeadingHighlight ?? "Essentials"
   const heroDescription =
+    homeBanner.description ??
     copy?.description ??
     "Discover dependable tools, components, devices, and everyday warehouse-ready stock built for fast-moving stores with large inventories."
-  const primaryCtaLabel = copy?.primaryCtaLabel ?? "Add to Cart"
-  const primaryCtaHref = copy?.primaryCtaHref ?? homeBanner.buttonLink ?? "/store"
+  const primaryCtaLabel = homeBanner.buttonName ?? copy?.primaryCtaLabel ?? "Add to Cart"
+  const primaryCtaHref = homeBanner.buttonLink ?? copy?.primaryCtaHref ?? "/store"
   const secondaryCtaLabel = copy?.secondaryCtaLabel ?? "Explore categories"
   const secondaryCtaHref = copy?.secondaryCtaHref ?? "/categories"
-  const mobilePrimaryCtaLabel = copy?.mobilePrimaryCtaLabel ?? "Shop now"
+  const mobilePrimaryCtaLabel =
+    homeBanner.buttonName ?? copy?.mobilePrimaryCtaLabel ?? "Shop now"
   const mobileSecondaryCtaLabel = copy?.mobileSecondaryCtaLabel ?? secondaryCtaLabel
 
   return (
     <div className="relative w-full overflow-x-hidden">
       <div className="relative hidden sm:block">
-        {homeBannerImage ? (
-          <Image
-            src={homeBannerImage}
-            alt={homeBanner.title || "Home Banner"}
-            width={1920}
-            height={800}
-            sizes="100vw"
-            className="h-[420px] w-full object-cover md:h-[520px] lg:h-[580px] xl:h-[620px]"
-            priority
-          />
-        ) : (
-          <div className="h-[420px] w-full bg-white md:h-[520px] lg:h-[580px] xl:h-[620px]" />
-        )}
+        <Image
+          src={homeBanner.image}
+          alt={homeBanner.title || "Home Banner"}
+          width={1920}
+          height={800}
+          sizes="100vw"
+          className="h-[420px] w-full object-cover md:h-[520px] lg:h-[580px] xl:h-[620px]"
+          priority
+        />
 
         <div className="absolute inset-y-0 left-0 w-[82%] bg-[linear-gradient(90deg,rgba(255,255,255,0.97)_0%,rgba(255,255,255,0.92)_52%,rgba(255,255,255,0.18)_82%,transparent_100%)] md:w-[72%] lg:w-[64%] xl:w-[60%]" />
 
@@ -89,9 +83,16 @@ export default function CatalogHeroBanner({
                 </div>
 
                 <h1 className="max-w-[13ch] text-[clamp(1.8rem,4vw,3.75rem)] font-bold leading-[1.04] text-[#04122C]">
-                  {desktopHeadingLine1}
-                  <br />
-                  Hardware <span className="text-[#2A8BFF]">{desktopHeadingHighlight}</span>
+                  {headlineFromCms ? (
+                    desktopHeadingLine1
+                  ) : (
+                    <>
+                      {desktopHeadingLine1}
+                      <br />
+                      Hardware{" "}
+                      <span className="text-[#2A8BFF]">{desktopHeadingHighlight}</span>
+                    </>
+                  )}
                 </h1>
 
                 <p className="max-w-[44ch] text-[12px] font-medium leading-relaxed text-[#4B5B76] md:text-sm lg:text-base">
@@ -155,9 +156,16 @@ export default function CatalogHeroBanner({
                 </div>
 
                 <h1 className="max-w-[12ch] text-[clamp(1.9rem,8vw,2.5rem)] font-bold leading-[1.06] text-[#04122C]">
-                  {desktopHeadingLine1}
-                  <br />
-                  Hardware <span className="text-[#2A8BFF]">{desktopHeadingHighlight}</span>
+                  {headlineFromCms ? (
+                    desktopHeadingLine1
+                  ) : (
+                    <>
+                      {desktopHeadingLine1}
+                      <br />
+                      Hardware{" "}
+                      <span className="text-[#2A8BFF]">{desktopHeadingHighlight}</span>
+                    </>
+                  )}
                 </h1>
 
                 <p className="text-[12px] font-medium leading-relaxed text-[#4B5B76] line-clamp-4">

package/src/home/catalog/page.tsx

@@ -1,5 +1,4 @@
 import dynamic from "next/dynamic"
-import type { HomepageBanner } from "medusa-storefront-data/dynamic-config"
 import {
   getRegion,
   listCategories,
@@ -7,13 +6,12 @@ import {
   listProductsWithSort,
   getProductsByTag,
   loadStorefrontPageInput,
-  getHomeBannersFromPageInput,
-  getAppBannersFromPageInput,
   getTestimonialsFromPageInput,
 } from "medusa-storefront-data"
+import { loadHeroSectionData } from "medusa-storefront-data/home/sections/hero"
 import { fetchRatings } from "medusa-reviews-logic/server"
 import { HomePageJsonLd } from "../components/home-page-json-ld"
-import CatalogHeroBanner from "./components/hero-banner"
+import CatalogHeroBanner, { type CatalogHeroCopy } from "./components/hero-banner"
 import TrustStrip from "./components/trust-strip"
 import ShopByCategory from "./components/shop-by-category"
 import ShopByAge from "./components/shop-by-age"
@@ -23,11 +21,6 @@ const WhyChooseUs = dynamic(() => import("./components/why-choose-us"))
 const LovedByMoms = dynamic(() => import("./components/loved-by-moms"))
 const Testimonials = dynamic(() => import("./components/testimonials"))
 
-export type CatalogHomeFallbackBanners = {
-  home: HomepageBanner
-  app: HomepageBanner
-}
-
 export type CatalogHomeJsonLd = {
   website: Record<string, unknown>
   organization: Record<string, unknown>
@@ -35,27 +28,13 @@ export type CatalogHomeJsonLd = {
 
 export type CatalogHomePageProps = {
   params: Promise<{ countryCode: string }>
-  /** Used when CMS has no banner images. */
-  fallbackBanners: CatalogHomeFallbackBanners
-  heroCopy?: {
-    badge?: string
-    desktopHeadingLine1?: string
-    desktopHeadingHighlight?: string
-    description?: string
-    primaryCtaLabel?: string
-    primaryCtaHref?: string
-    secondaryCtaLabel?: string
-    secondaryCtaHref?: string
-    mobilePrimaryCtaLabel?: string
-    mobileSecondaryCtaLabel?: string
-  }
+  heroCopy?: CatalogHeroCopy
   jsonLd: CatalogHomeJsonLd
   className?: string
 }
 
 export default async function CatalogHomePage({
   params,
-  fallbackBanners,
   heroCopy,
   jsonLd,
   className = "bg-white w-full",
@@ -69,17 +48,6 @@ export default async function CatalogHomePage({
 
   const pageInput = await loadStorefrontPageInput()
 
-  const hero = (() => {
-    const home = getHomeBannersFromPageInput(pageInput) ?? []
-    const app = getAppBannersFromPageInput(pageInput) ?? []
-    const hasHomeImage = home.length > 0 && Boolean(home[0]?.image)
-    const hasAppImage = app.length > 0 && Boolean(app[0]?.image)
-    return {
-      homeBanners: hasHomeImage ? home : [fallbackBanners.home],
-      appBanners: hasAppImage ? app : [fallbackBanners.app],
-    }
-  })()
-
   const [
     categories,
     newArrivalsResult,
@@ -87,6 +55,7 @@ export default async function CatalogHomePage({
     testimonialsBlock,
     allRatings,
     collectionsResult,
+    hero,
   ] = await Promise.all([
     listCategories({ limit: 50 }).catch(() => []),
     listProductsWithSort({
@@ -106,6 +75,7 @@ export default async function CatalogHomePage({
       collections: [],
       count: 0,
     })),
+    loadHeroSectionData(countryCode, { pageInput }),
   ])
 
   const newArrivals =

package/src/home/sections/customerStories/component/index.tsx

@@ -0,0 +1,286 @@
+"use client"
+
+import { useCallback, useEffect, useRef, useState } from "react"
+import Image from "next/image"
+import type { HomeThemeClassNames } from "medusa-storefront-theme-base"
+import { useThemeSection } from "medusa-ui-common/providers"
+import { DEFAULT_CUSTOMER_STORIES_COPY } from "../copy-defaults"
+import CustomerStoriesSectionHeader from "./section-header"
+import type { CustomerStoryItem } from "./types"
+
+const GAP_PX = 20
+
+export type CustomerStoriesProps = {
+  title?: string
+  eyebrow?: string
+  items?: CustomerStoryItem[]
+  classNames?: Partial<HomeThemeClassNames>
+}
+
+function Stars({
+  rating,
+  classNames,
+}: {
+  rating: number
+  classNames: { stars: string; starFilled: string; starMuted: string }
+}) {
+  const clamped = Math.max(0, Math.min(5, Math.round(rating)))
+  return (
+    <div className={classNames.stars} aria-label={`${clamped} out of 5 stars`}>
+      {Array.from({ length: 5 }, (_, i) => (
+        <span
+          key={i}
+          className={i < clamped ? classNames.starFilled : classNames.starMuted}
+        >
+          ★
+        </span>
+      ))}
+    </div>
+  )
+}
+
+function Chevron({ dir }: { dir: "left" | "right" }) {
+  return (
+    <svg
+      width="18"
+      height="18"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.75"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      {dir === "left" ? (
+        <path d="M15 18l-6-6 6-6" />
+      ) : (
+        <path d="M9 18l6-6-6-6" />
+      )}
+    </svg>
+  )
+}
+
+function useCardsPerView() {
+  const [perView, setPerView] = useState(1)
+
+  useEffect(() => {
+    const mq = window.matchMedia("(min-width: 768px)")
+    const update = () => setPerView(mq.matches ? 2 : 1)
+    update()
+    mq.addEventListener("change", update)
+    return () => mq.removeEventListener("change", update)
+  }, [])
+
+  return perView
+}
+
+function StoryCard({
+  story,
+  classNames,
+}: {
+  story: CustomerStoryItem
+  classNames: {
+    card: string
+    imageWrap: string
+    image: string
+    body: string
+    quote: string
+    stars: string
+    starFilled: string
+    starMuted: string
+    name: string
+  }
+}) {
+  const rating = Number(story.rating ?? 5)
+  return (
+    <article className={classNames.card}>
+      <div className={classNames.imageWrap}>
+        <Image
+          src={story.image}
+          alt={`${story.name} — customer story`}
+          width={320}
+          height={400}
+          className={classNames.image}
+          loading="lazy"
+          unoptimized
+        />
+      </div>
+      <div className={classNames.body}>
+        <p className={classNames.quote}>&ldquo;{story.text}&rdquo;</p>
+        <Stars
+          rating={Number.isFinite(rating) ? rating : 5}
+          classNames={{
+            stars: classNames.stars,
+            starFilled: classNames.starFilled,
+            starMuted: classNames.starMuted,
+          }}
+        />
+        <p className={classNames.name}>{story.name}</p>
+      </div>
+    </article>
+  )
+}
+
+export default function CustomerStories({
+  title: titleProp,
+  eyebrow: eyebrowProp,
+  items: itemsProp,
+  classNames: classNamesProp,
+}: CustomerStoriesProps) {
+  const cn = useThemeSection("home", classNamesProp)
+  const title = titleProp?.trim() || DEFAULT_CUSTOMER_STORIES_COPY.title
+  const eyebrow = eyebrowProp?.trim() || DEFAULT_CUSTOMER_STORIES_COPY.eyebrow
+  /** Use CMS/server items only; do not fall back to package copy when server sends an empty list. */
+  const items = Array.isArray(itemsProp)
+    ? itemsProp
+    : DEFAULT_CUSTOMER_STORIES_COPY.items
+
+  const perView = useCardsPerView()
+  const [activeIndex, setActiveIndex] = useState(0)
+  const [translateX, setTranslateX] = useState(0)
+  const viewportRef = useRef<HTMLDivElement>(null)
+  const trackRef = useRef<HTMLDivElement>(null)
+
+  const maxIndex = Math.max(0, items.length - perView)
+  const dotCount = maxIndex + 1
+
+  const measureOffset = useCallback(() => {
+    const slide = trackRef.current?.querySelector<HTMLElement>("[data-story-slide]")
+    if (!slide) return 0
+    return activeIndex * (slide.offsetWidth + GAP_PX)
+  }, [activeIndex])
+
+  useEffect(() => {
+    setTranslateX(measureOffset())
+  }, [measureOffset, perView])
+
+  useEffect(() => {
+    const viewport = viewportRef.current
+    if (!viewport) return
+    const ro = new ResizeObserver(() => setTranslateX(measureOffset()))
+    ro.observe(viewport)
+    return () => ro.disconnect()
+  }, [measureOffset])
+
+  useEffect(() => {
+    setActiveIndex((i) => Math.min(i, maxIndex))
+  }, [maxIndex, perView])
+
+  const goTo = useCallback(
+    (index: number) => {
+      setActiveIndex(Math.min(Math.max(index, 0), maxIndex))
+    },
+    [maxIndex]
+  )
+
+  if (items.length === 0) return null
+
+  return (
+    <section
+      className={`${cn.customerStoriesSection ?? ""} ${cn.section ?? ""}`}
+      aria-labelledby="customer-stories-heading"
+    >
+      <CustomerStoriesSectionHeader
+        eyebrow={eyebrow}
+        title={title}
+        id="customer-stories-heading"
+        classNames={{
+          wrap: cn.customerStoriesHeaderWrap ?? "",
+          inner: cn.customerStoriesHeaderInner ?? "",
+          header: cn.customerStoriesHeader ?? "",
+          eyebrow: cn.customerStoriesEyebrow ?? "",
+          heading: cn.customerStoriesTitle ?? "",
+          accent: cn.customerStoriesAccent ?? "",
+          accentLine: cn.customerStoriesAccentLine ?? "",
+          accentGem: cn.customerStoriesAccentGem ?? "",
+        }}
+      />
+
+      <div className={cn.customerStoriesInner ?? ""}>
+        <div className={cn.customerStoriesCarouselWrap ?? ""}>
+          <div className={cn.customerStoriesSlidesRow ?? ""}>
+            {dotCount > 1 ? (
+              <>
+                <button
+                  type="button"
+                  className={`${cn.customerStoriesNavButton ?? ""} ${cn.customerStoriesNavPrev ?? ""}`}
+                  onClick={() => goTo(activeIndex - 1)}
+                  disabled={activeIndex === 0}
+                  aria-label="Previous customer story"
+                >
+                  <Chevron dir="left" />
+                </button>
+                <button
+                  type="button"
+                  className={`${cn.customerStoriesNavButton ?? ""} ${cn.customerStoriesNavNext ?? ""}`}
+                  onClick={() => goTo(activeIndex + 1)}
+                  disabled={activeIndex >= maxIndex}
+                  aria-label="Next customer story"
+                >
+                  <Chevron dir="right" />
+                </button>
+              </>
+            ) : null}
+
+            <div ref={viewportRef} className={cn.customerStoriesViewport ?? ""}>
+              <div
+                ref={trackRef}
+                className={cn.customerStoriesTrack ?? ""}
+                style={{ transform: `translate3d(-${translateX}px, 0, 0)` }}
+              >
+                {items.map((story, index) => (
+                  <div
+                    key={story.id}
+                    data-story-slide
+                    className={cn.customerStoriesSlide ?? ""}
+                    aria-hidden={
+                      index < activeIndex || index >= activeIndex + perView
+                    }
+                  >
+                    <StoryCard
+                      story={story}
+                      classNames={{
+                        card: cn.customerStoriesCard ?? "",
+                        imageWrap: cn.customerStoriesImageWrap ?? "",
+                        image: cn.customerStoriesImage ?? "",
+                        body: cn.customerStoriesBody ?? "",
+                        quote: cn.customerStoriesQuote ?? "",
+                        stars: cn.customerStoriesStars ?? "",
+                        starFilled: cn.customerStoriesStarFilled ?? "",
+                        starMuted: cn.customerStoriesStarMuted ?? "",
+                        name: cn.customerStoriesName ?? "",
+                      }}
+                    />
+                  </div>
+                ))}
+              </div>
+            </div>
+          </div>
+
+          {dotCount > 1 ? (
+            <div
+              className={cn.customerStoriesDots ?? ""}
+              role="tablist"
+              aria-label="Story slides"
+            >
+              {Array.from({ length: dotCount }).map((_, i) => (
+                <button
+                  key={i}
+                  type="button"
+                  role="tab"
+                  aria-selected={i === activeIndex}
+                  aria-label={`Go to story ${i + 1}`}
+                  className={`${cn.customerStoriesDot ?? ""} ${
+                    i === activeIndex ? cn.customerStoriesDotActive ?? "" : ""
+                  }`}
+                  onClick={() => goTo(i)}
+                />
+              ))}
+            </div>
+          ) : null}
+        </div>
+      </div>
+    </section>
+  )
+}

package/src/home/sections/customerStories/component/section-header.tsx

@@ -0,0 +1,43 @@
+type CustomerStoriesSectionHeaderProps = {
+  eyebrow?: string | null
+  title: string
+  id?: string
+  classNames: {
+    wrap: string
+    inner: string
+    header: string
+    eyebrow: string
+    heading: string
+    accent: string
+    accentLine: string
+    accentGem: string
+  }
+}
+
+export default function CustomerStoriesSectionHeader({
+  eyebrow,
+  title,
+  id,
+  classNames: cn,
+}: CustomerStoriesSectionHeaderProps) {
+  const trimmed = title.trim()
+  if (!trimmed) return null
+
+  return (
+    <div className={cn.wrap}>
+      <div className={cn.inner}>
+        <header className={cn.header}>
+          {eyebrow?.trim() ? <p className={cn.eyebrow}>{eyebrow.trim()}</p> : null}
+          <h2 id={id} className={cn.heading}>
+            {trimmed}
+          </h2>
+          <div className={cn.accent} aria-hidden>
+            <span className={cn.accentLine} />
+            <span className={cn.accentGem} />
+            <span className={`${cn.accentLine} rotate-180`} />
+          </div>
+        </header>
+      </div>
+    </div>
+  )
+}

package/src/home/sections/customerStories/component/types.ts

@@ -0,0 +1,14 @@
+export type CustomerStoryItem = {
+  id: string
+  image: string
+  text: string
+  name: string
+  rating?: number
+  location?: string
+}
+
+export type CustomerStoriesContent = {
+  title?: string
+  eyebrow?: string
+  items: CustomerStoryItem[]
+}

package/src/home/sections/customerStories/copy-defaults.ts

@@ -0,0 +1,15 @@
+import { customerStoriesSectionDefaults } from "medusa-ui-home-config/sections/customerStories/defaults"
+import type { CustomerStoryItem } from "./component/types"
+
+export type CustomerStoriesCopy = {
+  eyebrow: string
+  title: string
+  items: CustomerStoryItem[]
+}
+
+/** UI fallback copy — sourced from medusa-ui-home-config (single canonical data.json). */
+export const DEFAULT_CUSTOMER_STORIES_COPY: CustomerStoriesCopy = {
+  eyebrow: customerStoriesSectionDefaults.eyebrow,
+  title: customerStoriesSectionDefaults.title,
+  items: customerStoriesSectionDefaults.items as CustomerStoryItem[],
+}

package/src/home/sections/customerStories/index.ts

@@ -0,0 +1,17 @@
+export { default } from "./section"
+export * from "./section"
+export {
+  defaultTheme,
+  mergeSectionTheme,
+  type ThemeOverrides,
+} from "./theme"
+export { sectionTheme } from "./theme"
+export {
+  DEFAULT_CUSTOMER_STORIES_COPY,
+  type CustomerStoriesCopy,
+} from "./copy-defaults"
+export type {
+  CustomerStoryItem,
+  CustomerStoriesContent,
+} from "./component/types"
+export * from "medusa-ui-home-config/sections/customerStories"

package/src/home/sections/customerStories/section.tsx

@@ -0,0 +1,29 @@
+import type { ThemeOverrides } from "./theme"
+import type { CustomerStoriesSectionData } from "medusa-storefront-data/home/sections/customerStories"
+import CustomerStories from "./component"
+import {
+  copyEyebrow,
+  copyTitle,
+} from "medusa-ui-home/home/lib/section-copy"
+
+export type CustomerStoriesSectionProps = CustomerStoriesSectionData & {
+  /** Override class names for slots this section uses. */
+  theme?: ThemeOverrides
+}
+
+export function CustomerStoriesSection({
+  customerStories,
+  copy,
+  theme,
+}: CustomerStoriesSectionProps) {
+  return (
+    <CustomerStories
+      classNames={theme}
+      title={copyTitle(copy) || customerStories.title}
+      eyebrow={copyEyebrow(copy) || customerStories.eyebrow}
+      items={customerStories.items}
+    />
+  )
+}
+
+export default CustomerStoriesSection

package/src/home/sections/customerStories/theme.ts

@@ -0,0 +1,67 @@
+import { mergeThemeSlots } from "medusa-storefront-theme-base"
+import { pickThemeKeys } from "../../theme/pick-theme"
+import { sharedHomeTheme } from "../../theme/shared"
+
+/** Slots unique to this section (merged into the global home theme). */
+export const sectionTheme = {
+  customerStoriesSection:
+    "w-full bg-[color-mix(in_srgb,var(--sf-color-secondary)_8%,var(--sf-color-background))] py-10 md:py-12 lg:py-14",
+  customerStoriesInner: "mx-auto w-full max-w-[1440px] px-4 sm:px-6 lg:px-8",
+  customerStoriesHeaderWrap: "w-full px-4 sm:px-6 md:px-8 lg:px-12",
+  customerStoriesHeaderInner: "mx-auto w-full max-w-[1440px]",
+  customerStoriesHeader:
+    "mb-5 flex flex-col items-center text-center sm:mb-6 md:mb-7",
+  customerStoriesEyebrow:
+    "mb-1.5 text-[0.6rem] font-medium uppercase tracking-[0.24em] text-[var(--sf-color-text-muted)] sm:text-[0.65rem] [font-family:var(--sf-font-family)]",
+  customerStoriesTitle:
+    "text-2xl font-semibold leading-tight tracking-tight text-[var(--sf-color-primary)] sm:text-[1.75rem] md:text-3xl [font-family:var(--sf-font-family-heading)]",
+  customerStoriesAccent: "mx-auto mt-3 flex items-center justify-center gap-2",
+  customerStoriesAccentLine:
+    "h-px w-8 bg-gradient-to-r from-transparent to-[var(--sf-color-secondary)] sm:w-10",
+  customerStoriesAccentGem: "h-1 w-1 rotate-45 bg-[var(--sf-color-secondary)]",
+  customerStoriesCarouselWrap: "relative",
+  customerStoriesSlidesRow: "relative px-8 sm:px-10 md:px-12",
+  customerStoriesViewport: "w-full overflow-hidden",
+  customerStoriesTrack:
+    "flex gap-5 motion-safe:transition-transform motion-safe:duration-[550ms] motion-safe:ease-[cubic-bezier(0.4,0,0.2,1)]",
+  customerStoriesSlide: "w-full shrink-0 md:w-[calc((100%-20px)/2)]",
+  customerStoriesCard:
+    "flex h-[250px] w-full flex-row overflow-hidden rounded-[8px] border border-[var(--sf-color-border)] bg-[var(--sf-color-surface)] shadow-sm md:h-[272px]",
+  customerStoriesImageWrap:
+    "relative h-full w-[40%] shrink-0 overflow-hidden bg-[color-mix(in_srgb,var(--sf-color-text-muted)_12%,var(--sf-color-background-alt))]",
+  customerStoriesImage: "block h-full w-full object-cover object-top",
+  customerStoriesBody:
+    "flex min-w-0 flex-1 flex-col items-center justify-center px-6 py-5 text-center md:px-8 md:py-6",
+  customerStoriesQuote:
+    "max-w-[15.5rem] text-[13px] font-normal italic leading-[1.7] text-[var(--sf-color-text-muted)] sm:max-w-[16.5rem] sm:text-[14px] md:max-w-[17.5rem] [font-family:var(--sf-font-family-heading)]",
+  customerStoriesStars: "mt-3 flex items-center gap-1",
+  customerStoriesStarFilled: "text-sm leading-none text-[var(--sf-color-secondary)]",
+  customerStoriesStarMuted:
+    "text-sm leading-none text-[color-mix(in_srgb,var(--sf-color-text-muted)_35%,transparent)]",
+  customerStoriesName:
+    "mt-[1.125rem] text-[14px] font-bold leading-tight text-[var(--sf-color-text)] md:mt-5 md:text-[15px] [font-family:var(--sf-font-family)]",
+  customerStoriesNavButton:
+    "absolute top-1/2 z-20 flex h-8 w-8 -translate-y-1/2 items-center justify-center border-0 bg-transparent p-0 text-[var(--sf-color-text-muted)] transition-colors hover:text-[var(--sf-color-text)] disabled:pointer-events-none disabled:opacity-25",
+  customerStoriesNavPrev: "left-0",
+  customerStoriesNavNext: "right-0",
+  customerStoriesDots: "mt-7 flex items-center justify-center gap-2 md:mt-8",
+  customerStoriesDot:
+    "h-[7px] w-[7px] rounded-full bg-[color-mix(in_srgb,var(--sf-color-text-muted)_35%,transparent)] p-0 transition-colors duration-300",
+  customerStoriesDotActive: "!bg-[var(--sf-color-text)]",
+} as const
+
+export const themeKeys = ["section"] as const
+
+const sharedDefaults = pickThemeKeys(sharedHomeTheme, themeKeys)
+
+export const defaultTheme = {
+  ...sharedDefaults,
+  ...sectionTheme,
+} as const
+
+export type ThemeOverrides = Partial<typeof defaultTheme>
+
+/** Merge site or page-level overrides onto this section's default theme slots. */
+export function mergeSectionTheme(overrides?: ThemeOverrides) {
+  return mergeThemeSlots(defaultTheme, overrides)
+}

package/src/theme/default-home-theme.ts

@@ -8,6 +8,7 @@ import { sectionTheme as baptismPicksSectionTheme } from "../home/sections/bapti
 import { sectionTheme as testimonialsSectionTheme } from "../home/sections/testimonials/theme"
 import { sectionTheme as instagramPostsSectionTheme } from "../home/sections/instagramPosts/theme"
 import { sectionTheme as videoStoriesSectionTheme } from "../home/sections/videoStories/theme"
+import { sectionTheme as customerStoriesSectionTheme } from "../home/sections/customerStories/theme"
 
 export const defaultHomeThemeClassNames = {
   ...sharedHomeTheme,
@@ -19,6 +20,7 @@ export const defaultHomeThemeClassNames = {
   ...testimonialsSectionTheme,
   ...instagramPostsSectionTheme,
   ...videoStoriesSectionTheme,
+  ...customerStoriesSectionTheme,
 } as const
 
 export type HomeThemeSlots = {