medusa-storefront-data 2.5.1 → 2.5.3

package/HOMEPAGE_CONFIG.md

@@ -1,6 +1,44 @@
 # Homepage config and page input
 
-Storefront **packages do not call** `GET /store/dynamic-config`. Segment copy uses **hardcoded JSON defaults** (`segment-data/default-page-input.json`). The **main project** fetches dynamic config once and passes optional `pageInput` overrides.
+Storefront **packages do not call** `GET /store/dynamic-config`. Each homepage section in `medusa-ui-home` keeps its **default copy in `data.json`** beside the UI. The **main project** fetches dynamic config once and passes optional `pageInput` overrides.
+
+## `medusa-ui-home` section layout
+
+Each section id is a folder under `src/home/sections/<id>/`:
+
+| File | Role |
+|------|------|
+| `data.json` | Default segment fields for dynamic-config schema |
+| `theme.ts` | Default class names for slots this section uses + `ThemeOverrides` + `mergeSectionTheme()` |
+| `dynamic-config.ts` | `*HomepageSectionField`, `*DynamicConfigStructure`, section id exports |
+| `component/` | Presentational UI (or `component/index.tsx` re-export for shared widgets) |
+| `section.tsx` | Section React wrapper only; optional `theme` prop |
+| `index.ts` | Package export (`medusa-ui-home/sections/<id>`) |
+
+Shared widgets used by multiple sections live in `src/home/components/` (`dynamic-banner`, `shoppable-gallery`, `shared/product-grid-section`, etc.).
+
+Cross-section slots (e.g. `section`, `sectionPad`, `cardSurface`) live in `src/home/theme/shared.ts` and are composed into `medusa-ui-home/theme` via `defaultHomeThemeClassNames`.
+
+### Per-section theme overrides
+
+```tsx
+import AboutBrandSection, {
+  mergeSectionTheme,
+  type ThemeOverrides,
+} from "medusa-ui-home/sections/aboutBrand"
+
+const aboutBrandTheme: ThemeOverrides = {
+  bannerTitle: "text-3xl font-black text-[var(--sf-color-secondary)]",
+}
+
+// Page / section instance
+<AboutBrandSection {...data} theme={aboutBrandTheme} />
+
+// Or merge into site home theme (Medusa theme-base)
+const homeTheme = mergeThemeSlots(defaultHomeThemeClassNames, {
+  ...mergeSectionTheme({ bannerTitle: "..." }),
+})
+```
 
 ## Tree-shakeable imports (one section)
 
@@ -33,7 +71,7 @@ export default async function Page({
 | `medusa-ui-home/sections/promoAnnouncements` | `medusa-storefront-data/home/sections/promoAnnouncements` |
 | … | … (all `HomeSectionId` values) |
 
-Run `node scripts/generate-home-section-exports.mjs` after adding a section.
+Run `node scripts/generate-home-section-exports.mjs` after adding a section (creates `sections/<id>/` export entries in `medusa-ui-home` and loader paths in `medusa-storefront-data`).
 
 ## Themed pages (tree-shakeable)
 
@@ -108,25 +146,60 @@ const pageInput = homepageConfigFromDynamicResponse(await getDynamicConfig())
 
 Pass `pageInput` only where you need CMS overrides; omit it to use package JSON defaults.
 
-## Medusa backend admin schemas (`medusa-ui-home`)
+## Medusa backend admin schemas (`medusa-ui-home-config`)
 
-UI and dynamic-config schema live in the same section file — import only what you register:
+Use **`medusa-ui-home-config`** in the Medusa server (CommonJS `require` + ESM `import`). Do not import `medusa-ui-home` in `medusa-config` — that package is ESM-only (React UI).
+
+```js
+const { homepageSectionFields } = require("medusa-ui-home-config")
+const { aboutBrandHomepageSectionField } = require(
+  "medusa-ui-home-config/sections/aboutBrand",
+)
+```
 
 ```ts
-import HeroSection, {
-  heroHomepageSectionField,
-  bannerSlide,
-} from "medusa-ui-home/sections/hero"
-import { whyChooseUsHomepageSectionField } from "medusa-ui-home/sections/whyChooseUs"
+import { homepageSectionFields } from "medusa-ui-home-config"
+import { heroHomepageSectionField, bannerSlide } from "medusa-ui-home-config/sections/hero"
 ```
 
-Compose `options.configs` in your Medusa project from each section’s `*HomepageSectionField` (and site-level structures you define locally). Merge API responses with `homepageConfigFromDynamicResponse` from `medusa-storefront-data/dynamic-config`.
+Compose `options.configs` from `homepageSectionFields` or individual `*HomepageSectionField` exports. Merge API responses with `homepageConfigFromDynamicResponse` from `medusa-storefront-data/dynamic-config`.
+
+Help page FAQs use **`helpFaqHomepageSectionField`** from `medusa-ui-home-config/sections/helpFaq` (also included in `homepageSectionFields`). Store in `homepage-config.sections.helpFaq`:
+
+```json
+{
+  "sections": {
+    "helpFaq": {
+      "eyebrow": "Knowledge Base",
+      "title": "Frequently Asked",
+      "titleHighlight": "Questions",
+      "subtitle": "Browse FAQs by topic.",
+      "categories": [
+        {
+          "category": "Order & Delivery",
+          "icon": "🚚",
+          "color": "from-blue-500 to-cyan-400",
+          "items": [
+            { "question": "When will I receive my order?", "answer": "…" }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
+
+Legacy flat `faq-array` entries are still supported and are grouped by `faq-category`.
+
+Storefront UI still imports from `medusa-ui-home/sections/<id>`.
 
 ## API reference
 
 | Export | Use |
 |--------|-----|
 | `loadHeroSectionData`, `loadNewArrivalsSectionData`, … | **One section** catalog + copy |
+| `loadHelpFaqSectionData` | Help page FAQ (`sections.helpFaq`) |
+| `getHelpFaqFromPageInput(pageInput)` | FAQ categories + section header copy |
 | `getDynamicConfig()` | **Main project only** |
 | `get*FromPageInput(pageInput)` | Read CMS copy/banners without fetching |
 | `homepageConfigFromDynamicResponse(raw)` | Merge API → `pageInput` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "medusa-storefront-data",
-  "version": "2.5.1",
+  "version": "2.5.3",
   "type": "module",
   "description": "Medusa storefront server data layer extracted from Next.js storefront",
   "license": "MIT",
@@ -53,120 +53,165 @@
       "import": "./src/server/index.ts",
       "default": "./src/server/index.ts"
     },
-    "./home/sections/promoAnnouncements": {
-      "types": "./dist/server/home-sections/promo-announcements.d.ts",
-      "import": "./src/server/home-sections/promo-announcements.ts",
-      "default": "./src/server/home-sections/promo-announcements.ts"
-    },
-    "./home/sections/hero": {
-      "types": "./dist/server/home-sections/hero.d.ts",
-      "import": "./src/server/home-sections/hero.ts",
-      "default": "./src/server/home-sections/hero.ts"
-    },
-    "./home/sections/categoryPills": {
-      "types": "./dist/server/home-sections/category-pills.d.ts",
-      "import": "./src/server/home-sections/category-pills.ts",
-      "default": "./src/server/home-sections/category-pills.ts"
-    },
-    "./home/sections/newArrivals": {
-      "types": "./dist/server/home-sections/new-arrivals.d.ts",
-      "import": "./src/server/home-sections/new-arrivals.ts",
-      "default": "./src/server/home-sections/new-arrivals.ts"
-    },
-    "./home/sections/newArrivalsClassic": {
-      "types": "./dist/server/home-sections/new-arrivals-classic.d.ts",
-      "import": "./src/server/home-sections/new-arrivals-classic.ts",
-      "default": "./src/server/home-sections/new-arrivals-classic.ts"
-    },
-    "./home/sections/promoCountdown": {
-      "types": "./dist/server/home-sections/promo-countdown.d.ts",
-      "import": "./src/server/home-sections/promo-countdown.ts",
-      "default": "./src/server/home-sections/promo-countdown.ts"
-    },
-    "./home/sections/celebrityTrust": {
-      "types": "./dist/server/home-sections/celebrity-trust.d.ts",
-      "import": "./src/server/home-sections/celebrity-trust.ts",
-      "default": "./src/server/home-sections/celebrity-trust.ts"
-    },
-    "./home/sections/luxeFavourites": {
-      "types": "./dist/server/home-sections/luxe-favourites.d.ts",
-      "import": "./src/server/home-sections/luxe-favourites.ts",
-      "default": "./src/server/home-sections/luxe-favourites.ts"
-    },
-    "./home/sections/shopByCategory": {
-      "types": "./dist/server/home-sections/shop-by-category.d.ts",
-      "import": "./src/server/home-sections/shop-by-category.ts",
-      "default": "./src/server/home-sections/shop-by-category.ts"
-    },
-    "./home/sections/baptism": {
-      "types": "./dist/server/home-sections/baptism.d.ts",
-      "import": "./src/server/home-sections/baptism.ts",
-      "default": "./src/server/home-sections/baptism.ts"
-    },
-    "./home/sections/baptismPicks": {
-      "types": "./dist/server/home-sections/baptism-picks.d.ts",
-      "import": "./src/server/home-sections/baptism-picks.ts",
-      "default": "./src/server/home-sections/baptism-picks.ts"
-    },
-    "./home/sections/themeDresses": {
-      "types": "./dist/server/home-sections/theme-dresses.d.ts",
-      "import": "./src/server/home-sections/theme-dresses.ts",
-      "default": "./src/server/home-sections/theme-dresses.ts"
-    },
-    "./home/sections/brandMarquee": {
-      "types": "./dist/server/home-sections/brand-marquee.d.ts",
-      "import": "./src/server/home-sections/brand-marquee.ts",
-      "default": "./src/server/home-sections/brand-marquee.ts"
-    },
-    "./home/sections/aboutBrand": {
-      "types": "./dist/server/home-sections/about-brand.d.ts",
-      "import": "./src/server/home-sections/about-brand.ts",
-      "default": "./src/server/home-sections/about-brand.ts"
-    },
-    "./home/sections/testimonials": {
-      "types": "./dist/server/home-sections/testimonials.d.ts",
-      "import": "./src/server/home-sections/testimonials.ts",
-      "default": "./src/server/home-sections/testimonials.ts"
-    },
-    "./home/sections/brandPillars": {
-      "types": "./dist/server/home-sections/brand-pillars.d.ts",
-      "import": "./src/server/home-sections/brand-pillars.ts",
-      "default": "./src/server/home-sections/brand-pillars.ts"
-    },
-    "./home/sections/instagramPosts": {
-      "types": "./dist/server/home-sections/instagram-posts.d.ts",
-      "import": "./src/server/home-sections/instagram-posts.ts",
-      "default": "./src/server/home-sections/instagram-posts.ts"
-    },
-    "./home/sections/features": {
-      "types": "./dist/server/home-sections/features.d.ts",
-      "import": "./src/server/home-sections/features.ts",
-      "default": "./src/server/home-sections/features.ts"
-    },
-    "./home/sections/shopByAge": {
-      "types": "./dist/server/home-sections/shop-by-age.d.ts",
-      "import": "./src/server/home-sections/shop-by-age.ts",
-      "default": "./src/server/home-sections/shop-by-age.ts"
-    },
-    "./home/sections/whyChooseUs": {
-      "types": "./dist/server/home-sections/why-choose-us.d.ts",
-      "import": "./src/server/home-sections/why-choose-us.ts",
-      "default": "./src/server/home-sections/why-choose-us.ts"
-    },
-    "./home/sections/lovedByMoms": {
-      "types": "./dist/server/home-sections/loved-by-moms.d.ts",
-      "import": "./src/server/home-sections/loved-by-moms.ts",
-      "default": "./src/server/home-sections/loved-by-moms.ts"
-    },
-    "./home/sections/videoStories": {
-      "types": "./dist/server/home-sections/video-stories.d.ts",
-      "import": "./src/server/home-sections/video-stories.ts",
-      "default": "./src/server/home-sections/video-stories.ts"
-    },
-    "./home/sections/blogPosts": {
-      "types": "./dist/server/home-sections/blog-posts.d.ts",
-      "import": "./src/server/home-sections/blog-posts.ts",
-      "default": "./src/server/home-sections/blog-posts.ts"
+    "./cookies": {
+      "types": "./dist/cookies.d.ts",
+      "import": "./src/cookies.ts",
+      "default": "./src/cookies.ts"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./src/config.ts",
+      "default": "./src/config.ts"
+    },
+    "./locale-header": {
+      "types": "./dist/util/get-locale-header.d.ts",
+      "import": "./src/util/get-locale-header.ts",
+      "default": "./src/util/get-locale-header.ts"
+    },
+    "./medusa-error": {
+      "types": "./dist/util/medusa-error.d.ts",
+      "import": "./src/util/medusa-error.ts",
+      "default": "./src/util/medusa-error.ts"
+    },
+    "./sort-products": {
+      "types": "./dist/util/sort-products.d.ts",
+      "import": "./src/util/sort-products.ts",
+      "default": "./src/util/sort-products.ts"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "import": "./src/middleware.ts",
+      "default": "./src/middleware.ts"
+    },
+    "./edge": {
+      "types": "./dist/edge.d.ts",
+      "import": "./src/edge.ts",
+      "default": "./src/edge.ts"
+    },
+    "./cart": {
+      "types": "./dist/server/cart.d.ts",
+      "import": "./src/server/cart.ts",
+      "default": "./src/server/cart.ts"
+    },
+    "./categories": {
+      "types": "./dist/server/categories.d.ts",
+      "import": "./src/server/categories.ts",
+      "default": "./src/server/categories.ts"
+    },
+    "./collections": {
+      "types": "./dist/server/collections.d.ts",
+      "import": "./src/server/collections.ts",
+      "default": "./src/server/collections.ts"
+    },
+    "./contact": {
+      "types": "./dist/server/contact.d.ts",
+      "import": "./src/server/contact.ts",
+      "default": "./src/server/contact.ts"
+    },
+    "./customer": {
+      "types": "./dist/server/customer.d.ts",
+      "import": "./src/server/customer.ts",
+      "default": "./src/server/customer.ts"
+    },
+    "./customer-registration": {
+      "types": "./dist/server/customer-registration.d.ts",
+      "import": "./src/server/customer-registration.ts",
+      "default": "./src/server/customer-registration.ts"
+    },
+    "./dynamic-config": {
+      "types": "./dist/server/dynamic-config.d.ts",
+      "import": "./src/server/dynamic-config.ts",
+      "default": "./src/server/dynamic-config.ts"
+    },
+    "./help/sections/helpFaq": {
+      "types": "./dist/server/help-sections/help-faq.d.ts",
+      "import": "./src/server/help-sections/help-faq.ts",
+      "default": "./src/server/help-sections/help-faq.ts"
+    },
+    "./fulfillment": {
+      "types": "./dist/server/fulfillment.d.ts",
+      "import": "./src/server/fulfillment.ts",
+      "default": "./src/server/fulfillment.ts"
+    },
+    "./guest": {
+      "types": "./dist/server/guest.d.ts",
+      "import": "./src/server/guest.ts",
+      "default": "./src/server/guest.ts"
+    },
+    "./home": {
+      "types": "./dist/server/home.d.ts",
+      "import": "./src/server/home.ts",
+      "default": "./src/server/home.ts"
+    },
+    "./locale-actions": {
+      "types": "./dist/server/locale-actions.d.ts",
+      "import": "./src/server/locale-actions.ts",
+      "default": "./src/server/locale-actions.ts"
+    },
+    "./locales": {
+      "types": "./dist/server/locales.d.ts",
+      "import": "./src/server/locales.ts",
+      "default": "./src/server/locales.ts"
+    },
+    "./notifications": {
+      "types": "./dist/server/notifications.d.ts",
+      "import": "./src/server/notifications.ts",
+      "default": "./src/server/notifications.ts"
+    },
+    "./onboarding": {
+      "types": "./dist/server/onboarding.d.ts",
+      "import": "./src/server/onboarding.ts",
+      "default": "./src/server/onboarding.ts"
+    },
+    "./orders": {
+      "types": "./dist/server/orders.d.ts",
+      "import": "./src/server/orders.ts",
+      "default": "./src/server/orders.ts"
+    },
+    "./payment": {
+      "types": "./dist/server/payment.d.ts",
+      "import": "./src/server/payment.ts",
+      "default": "./src/server/payment.ts"
+    },
+    "./payment-details": {
+      "types": "./dist/server/payment-details.d.ts",
+      "import": "./src/server/payment-details.ts",
+      "default": "./src/server/payment-details.ts"
+    },
+    "./pincode": {
+      "types": "./dist/server/pincode.d.ts",
+      "import": "./src/server/pincode.ts",
+      "default": "./src/server/pincode.ts"
+    },
+    "./products": {
+      "types": "./dist/server/products.d.ts",
+      "import": "./src/server/products.ts",
+      "default": "./src/server/products.ts"
+    },
+    "./regions": {
+      "types": "./dist/server/regions.d.ts",
+      "import": "./src/server/regions.ts",
+      "default": "./src/server/regions.ts"
+    },
+    "./returns": {
+      "types": "./dist/server/returns.d.ts",
+      "import": "./src/server/returns.ts",
+      "default": "./src/server/returns.ts"
+    },
+    "./swaps": {
+      "types": "./dist/server/swaps.d.ts",
+      "import": "./src/server/swaps.ts",
+      "default": "./src/server/swaps.ts"
+    },
+    "./variants": {
+      "types": "./dist/server/variants.d.ts",
+      "import": "./src/server/variants.ts",
+      "default": "./src/server/variants.ts"
+    },
+    "./wishlist": {
+      "types": "./dist/server/wishlist.d.ts",
+      "import": "./src/server/wishlist.ts",
+      "default": "./src/server/wishlist.ts"
     }
   },
   "main": "./dist/server/index.js",

package/src/server/cart.ts

@@ -740,7 +740,7 @@ export async function placeOrder(cartId?: string) {
   }
 
   if (cartRes?.type === "order") {
-    const order = cartRes.order as HttpTypes.StoreOrder
+    const order = cartRes.order as unknown as HttpTypes.StoreOrder
     const countryCode = order.shipping_address?.country_code?.toLowerCase()
 
     const orderCacheTag = await getCacheTag("orders")

package/src/server/dynamic-config.ts

@@ -523,22 +523,100 @@ export function getSocialLinksFromPageInput(
 }
 
 
-export function getFaqsFromPageInput(
+export type HelpFaqItem = { q: string; a: string }
+
+export type HelpFaqCategory = {
+  category: string
+  icon?: string
+  color?: string
+  items: HelpFaqItem[]
+}
+
+export type HelpFaqSectionCopy = {
+  eyebrow?: string
+  title?: string
+  titleHighlight?: string
+  subtitle?: string
+}
+
+export type HelpFaqConfig = {
+  sectionCopy: HelpFaqSectionCopy
+  categories: HelpFaqCategory[]
+}
+
+function asConfigObject(value: unknown): Record<string, unknown> | null {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value as Record<string, unknown>
+  }
+  return null
+}
+
+function asConfigArray(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : []
+}
+
+function parseHelpFaqItems(itemsRaw: unknown): HelpFaqItem[] {
+  const items: HelpFaqItem[] = []
+  for (const item of asConfigArray(itemsRaw)) {
+    const faq =
+      asConfigObject((item as Record<string, unknown>)?.faq) ?? asConfigObject(item)
+    if (!faq) continue
+    const q = String(
+      faq.question ?? faq["faq-question"] ?? faq.q ?? ""
+    ).trim()
+    const a = String(faq.answer ?? faq["faq-answer"] ?? faq.a ?? "").trim()
+    if (q && a) items.push({ q, a })
+  }
+  return items
+}
+
+function parseHelpFaqCategoriesFromBlock(
+  block: Record<string, unknown>
+): HelpFaqCategory[] {
+  const raw = block.categories
+  if (!Array.isArray(raw)) return []
+
+  const categories: HelpFaqCategory[] = []
+  for (const row of raw) {
+    const cat =
+      asConfigObject((row as Record<string, unknown>)?.category) ??
+      asConfigObject(row)
+    if (!cat) continue
+    const category = String(cat.category ?? cat.name ?? "").trim()
+    const items = parseHelpFaqItems(cat.items)
+    if (!category || items.length === 0) continue
+    categories.push({
+      category,
+      icon: String(cat.icon ?? "❓").trim() || "❓",
+      color:
+        String(cat.color ?? "from-violet-500 to-purple-400").trim() ||
+        "from-violet-500 to-purple-400",
+      items,
+    })
+  }
+  return categories
+}
+
+function parseHelpFaqCategoriesFromLegacyArray(
   pageInput?: HomepageConfig | null
-): Array<{ category: string; items: Array<{ q: string; a: string }> }> | null {
+): HelpFaqCategory[] {
   const config = resolvePageInput(pageInput)
   const faqsRaw = config["faq-array"] || []
-  if (!Array.isArray(faqsRaw) || faqsRaw.length === 0) return null
+  if (!Array.isArray(faqsRaw) || faqsRaw.length === 0) return []
+
   const categoriesMap: Record<
     string,
-    { displayCategory: string; items: Array<{ q: string; a: string }> }
+    { displayCategory: string; items: HelpFaqItem[] }
   > = {}
+
   faqsRaw.forEach((item: Record<string, unknown>) => {
-    const faq = (item?.["faq"] || item) as Record<string, unknown>
-    const displayCategory = String(faq?.["faq-category"] || "General Questions").trim()
+    const faq = (item?.faq || item) as Record<string, unknown>
+    const displayCategory = String(
+      faq?.["faq-category"] || faq?.category || "General Questions"
+    ).trim()
     const categoryKey = displayCategory.toLowerCase()
-    const q = String(faq?.["faq-question"] || "").trim()
-    const a = String(faq?.["faq-answer"] || "").trim()
+    const q = String(faq?.["faq-question"] || faq?.question || "").trim()
+    const a = String(faq?.["faq-answer"] || faq?.answer || "").trim()
     if (q && a) {
       if (!categoriesMap[categoryKey]) {
         categoriesMap[categoryKey] = { displayCategory, items: [] }
@@ -546,11 +624,53 @@ export function getFaqsFromPageInput(
       categoriesMap[categoryKey].items.push({ q, a })
     }
   })
-  const faqs = Object.values(categoriesMap).map((catData) => ({
-    category: catData.displayCategory,
-    items: catData.items,
+
+  return Object.values(categoriesMap).map((cat) => ({
+    category: cat.displayCategory,
+    icon: "❓",
+    color: "from-violet-500 to-purple-400",
+    items: cat.items,
   }))
-  return faqs.length > 0 ? faqs : null
+}
+
+function helpFaqBlockToSectionCopy(
+  block: Record<string, unknown>
+): HelpFaqSectionCopy {
+  const copy = parseSectionCopy(block)
+  return {
+    eyebrow: copy.eyebrow ?? undefined,
+    title: copy.title ?? copy.name ?? undefined,
+    titleHighlight:
+      typeof block.titleHighlight === "string"
+        ? block.titleHighlight
+        : undefined,
+    subtitle: copy.subtitle ?? copy.description ?? copy.text ?? undefined,
+  }
+}
+
+/**
+ * Help page FAQ — `sections.helpFaq` (preferred) with legacy `faq-array` fallback.
+ */
+export function getHelpFaqFromPageInput(
+  pageInput?: HomepageConfig | null
+): HelpFaqConfig {
+  const block = getMergedSectionBlock("helpFaq", pageInput)
+  const sectionCopy = helpFaqBlockToSectionCopy(block)
+
+  let categories = parseHelpFaqCategoriesFromBlock(block)
+  if (categories.length === 0) {
+    categories = parseHelpFaqCategoriesFromLegacyArray(pageInput)
+  }
+
+  return { sectionCopy, categories }
+}
+
+/** FAQ categories for the help template (null when empty). */
+export function getFaqsFromPageInput(
+  pageInput?: HomepageConfig | null
+): HelpFaqCategory[] | null {
+  const { categories } = getHelpFaqFromPageInput(pageInput)
+  return categories.length > 0 ? categories : null
 }