@mohasinac/appkit 4.53.0 → 4.53.1

package/dist/features/homepage/components/PromoGrid.js

@@ -6,10 +6,19 @@ import { resolveMediaUrl } from "../../../utils/media-url.js";
 const __P = {
     p4: "p-[var(--appkit-space-4)]",
 };
+/** Hard cap — this layout only has slots for 4 (one hero tile + three). */
+export const PROMO_GRID_MAX_BANNERS = 4;
 export function PromoGrid({ banners, eyebrow = "LIMITED TIME", heading = "HOT DEALS & PROMOS", }) {
     if (banners.length === 0)
         return null;
-    return (_jsx(Section, { paddingY: "y-4xl", className: "bg-[var(--dark-section-alt)] [border-top:1px_solid_rgba(255,255,255,0.06)] [border-bottom:1px_solid_rgba(255,255,255,0.06)]", children: _jsxs(Div, { className: "mx-auto max-w-7xl", padding: "x-md", children: [_jsx(Row, { wrap: true, align: "end", justify: "between", gap: "sm", className: "mb-7 gap-y-2", children: _jsxs(Div, { children: [_jsx(Text, { className: "mb-1 font-black uppercase tracking-widest text-[var(--color-red)] tracking-[0.18em]", size: "xs", children: eyebrow }), _jsx(Heading, { level: 2, className: "[font-family:var(--font-bangers,Bangers,cursive)] text-[clamp(1.6rem,4vw,2.4rem)] tracking-[0.08em] text-white leading-none", children: heading })] }) }), _jsx(Div, { layout: "grid", gap: "3", className: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3", children: banners.slice(0, 4).map((banner, i) => (_jsxs(Link, { href: banner.ctaUrl, className: `group relative block overflow-hidden bg-[var(--dark-section-card)] ${i === 0 ? "sm:row-span-2 min-h-[clamp(220px,32vh,480px)]" : "min-h-[clamp(130px,16vh,240px)]"}`, children: [_jsx(Image, { src: resolveMediaUrl(banner.image), alt: banner.title, fill: true, className: "object-cover transition-transform duration-500 group-hover:scale-105", sizes: i === 0
-                                    ? "(max-width: 640px) 100vw, 40vw"
-                                    : "(max-width: 640px) 50vw, 30vw" }), _jsx(Div, { className: `absolute inset-0 ${i === 0 ? "[background:linear-gradient(to_top,rgba(0,0,0,0.9)_0%,rgba(0,0,0,0.3)_50%,transparent_100%)]" : "[background:linear-gradient(to_top,rgba(0,0,0,0.85)_0%,rgba(0,0,0,0.15)_100%)]"}` }), _jsx(Div, { className: "absolute inset-0 pointer-events-none opacity-0 transition-opacity duration-300 group-hover:opacity-100 ring-2 ring-[var(--color-yellow)] ring-inset" }), _jsxs(Div, { className: `absolute bottom-0 left-0 right-0 ${__P.p4}`, children: [_jsx(Text, { className: `leading-tight [font-family:var(--font-bangers,Bangers,cursive)] tracking-[0.06em] text-white ${i === 0 ? "text-[1.35rem]" : "text-[1rem]"}`, children: banner.title }), _jsxs(Span, { layout: "inline-flex", gap: "xs", className: "mt-1 font-black uppercase text-[var(--color-yellow)]", size: "xs", children: [banner.ctaLabel, " \u2192"] })] })] }, banner.id))) })] }) }));
+    return (_jsx(Section, { paddingY: "y-4xl", 
+        // `media-dark` IS the theme-invariant dark surface token (bg-zinc-900)
+        // — exactly what this always-dark section needs, so no raw className
+        // colour and no suppression marker.
+        surface: "media-dark", className: "border-t border-b border-white/[0.06]", children: _jsxs(Div, { className: "mx-auto max-w-7xl", padding: "x-md", children: [_jsx(Row, { wrap: true, align: "end", justify: "between", gap: "sm", className: "mb-7 gap-y-2", children: _jsxs(Div, { children: [_jsx(Text, { className: "mb-1 font-black uppercase tracking-widest text-error tracking-[0.18em]", size: "xs", children: eyebrow }), _jsx(Heading, { level: 2, family: "display", className: "tracking-[0.08em] leading-none text-white", size: "xl", mdSize: "2xl", weight: "bold", children: heading })] }) }), _jsx(Div, { layout: "grid", gap: "3", className: "grid-cols-1 sm:grid-cols-2 lg:grid-cols-3", children: banners.slice(0, PROMO_GRID_MAX_BANNERS).map((banner, i) => {
+                        const resolvedSrc = resolveMediaUrl(banner.image);
+                        return (_jsxs(Link, { href: banner.ctaUrl, className: `group relative block overflow-hidden bg-zinc-900 ${i === 0 ? "sm:row-span-2 min-h-[clamp(220px,32vh,480px)]" : "min-h-[clamp(130px,16vh,240px)]"}`, children: [resolvedSrc ? (_jsx(Image, { src: resolvedSrc, alt: banner.title, fill: true, className: "object-cover transition-transform duration-500 group-hover:scale-105", sizes: i === 0
+                                        ? "(max-width: 640px) 100vw, 40vw"
+                                        : "(max-width: 640px) 50vw, 30vw" })) : null, _jsx(Div, { className: `absolute inset-0 ${i === 0 ? "[background:linear-gradient(to_top,rgba(0,0,0,0.9)_0%,rgba(0,0,0,0.3)_50%,transparent_100%)]" : "[background:linear-gradient(to_top,rgba(0,0,0,0.85)_0%,rgba(0,0,0,0.15)_100%)]"}` }), _jsx(Div, { className: "absolute inset-0 pointer-events-none opacity-0 transition-opacity duration-300 group-hover:opacity-100 ring-2 ring-[var(--color-yellow)] ring-inset" }), _jsxs(Div, { className: `absolute bottom-0 left-0 right-0 ${__P.p4}`, children: [_jsx(Text, { family: "display", className: `leading-tight tracking-[0.06em] text-white ${i === 0 ? "text-[1.35rem]" : "text-[1rem]"}`, children: banner.title }), _jsxs(Span, { layout: "inline-flex", gap: "xs", className: "mt-1 font-black uppercase text-[var(--color-yellow)]", size: "xs", children: [banner.ctaLabel, " \u2192"] })] })] }, banner.id));
+                    }) })] }) }));
 }

package/dist/features/homepage/components/TestimonialsCarousel.d.ts

@@ -1,6 +1,38 @@
-import type { Testimonial } from "../types";
+/**
+ * Promoted to a registered `SectionType` ("testimonials") 2026-10-19 — see
+ * `TestimonialsSectionConfig` in `schemas/firestore.ts`, which this prop shape
+ * mirrors (Firestore config must be a plain serialisable object).
+ *
+ * Three things fixed in the same pass, all required before this could render
+ * correctly on a real page rather than just compile:
+ *
+ * 1. **Testimonials are now INLINE in config**, not a read from the
+ *    `testimonials` collection shape (`Testimonial` in `types/index.ts`, with
+ *    `featured`/`sortOrder`/`active`). Those three fields are collection-row
+ *    housekeeping with no meaning inside an ordered config array — the config
+ *    IS the order, and every entry in it is already "featured" by virtue of
+ *    being configured. `avatarUrl` is dropped too: declared on the old type,
+ *    never rendered by this component.
+ * 2. **It is not a carousel** — no autoplay, no arrows, no dots, just a
+ *    horizontally-scrolling wrapped row. So the config carries no
+ *    `autoScroll`/`scrollInterval`/`loop` fields; adding them would be
+ *    `NO-RENDERER` dead weight from day one.
+ * 3. **Every colour/font var below was undefined anywhere in the codebase**
+ *    (`--section-bg`, `--card-bg`, `--card-border`, `--section-border`,
+ *    `--section-title-color`, `--text-secondary`, `--color-red`,
+ *    `--font-bangers`) — this component would have rendered with a
+ *    transparent background, no borders and the browser's default font had
+ *    it ever shipped. Migrated to the real `--appkit-*` token set (Root Cause
+ *    #21); `--color-yellow` was the one survivor (a real token, `tokens.css`).
+ */
+export interface TestimonialConfigItem {
+    id: string;
+    name: string;
+    rating: 1 | 2 | 3 | 4 | 5;
+    text: string;
+}
 export interface TestimonialsCarouselProps {
-    testimonials: Testimonial[];
+    testimonials: TestimonialConfigItem[];
     /** Eyebrow label. Default: "COLLECTOR REVIEWS". */
     eyebrow?: string;
     /** Section heading. Default: "WHAT OUR COLLECTORS SAY". */

package/dist/features/homepage/components/TestimonialsCarousel.js

@@ -3,5 +3,5 @@ import { Div, Heading, Stack, StarRating, Text } from "../../../ui/index.js";
 export function TestimonialsCarousel({ testimonials, eyebrow = "COLLECTOR REVIEWS", heading = "WHAT OUR COLLECTORS SAY", }) {
     if (testimonials.length === 0)
         return null;
-    return (_jsx(Stack, { as: "section", justify: "center", className: "bg-[var(--section-bg)] [border-top:var(--section-border)] [border-bottom:var(--section-border)] min-h-[calc(100svh-var(--header-height,4rem))] [padding-block:clamp(3rem,6vh,5rem)]", children: _jsxs(Stack, { className: "mx-auto w-full max-w-7xl sm:px-[2rem] min-h-0", padding: "x-lg", children: [_jsxs(Div, { className: "mb-6 text-left shrink-0", children: [_jsx(Text, { className: "mb-1 font-black uppercase tracking-widest text-[var(--color-red)] tracking-[0.18em]", size: "xs", children: eyebrow }), _jsx(Heading, { level: 2, className: "[font-family:var(--font-bangers,Bangers,cursive)] text-[clamp(1.8rem,4vw,2.8rem)] tracking-[0.08em] text-[var(--section-title-color)] leading-none", children: heading })] }), _jsx(Stack, { wrap: true, className: "overflow-x-auto scrollbar-none max-h-[50svh] content-start", gap: "md", children: testimonials.map((t) => (_jsxs(Stack, { padding: "5", className: "shrink-0 w-[clamp(260px,28vw,360px)] bg-[var(--card-bg)] [border:var(--card-border)]", shadow: "card", gap: "3", children: [_jsx(StarRating, { value: t.rating, readOnly: true, size: "sm" }), _jsxs(Text, { className: "flex-1 leading-relaxed text-[var(--text-secondary)]", size: "sm", children: ["\u201C", t.text, "\u201D"] }), _jsxs(Text, { className: "font-black uppercase text-[var(--color-yellow)] tracking-[0.06em]", size: "xs", children: ["\u2014 ", t.name] })] }, t.id))) })] }) }));
+    return (_jsx(Stack, { as: "section", justify: "center", surface: "muted", border: "subtle", className: "min-h-[calc(100svh-var(--header-height,4rem))] [padding-block:clamp(3rem,6vh,5rem)]", children: _jsxs(Stack, { className: "mx-auto w-full max-w-7xl sm:px-[2rem] min-h-0", padding: "x-lg", children: [_jsxs(Div, { className: "mb-6 text-left shrink-0", children: [_jsx(Text, { className: "mb-1 font-black uppercase tracking-widest text-error tracking-[0.18em]", size: "xs", children: eyebrow }), _jsx(Heading, { level: 2, family: "display", className: "tracking-[0.08em] leading-none", size: "2xl", mdSize: "3xl", weight: "bold", color: "primary", children: heading })] }), _jsx(Stack, { wrap: true, className: "overflow-x-auto scrollbar-none max-h-[50svh] content-start", gap: "md", children: testimonials.map((t) => (_jsxs(Stack, { padding: "5", surface: "card", border: "subtle", className: "shrink-0 w-[clamp(260px,28vw,360px)]", shadow: "card", gap: "3", children: [_jsx(StarRating, { value: t.rating, readOnly: true, size: "sm" }), _jsxs(Text, { className: "flex-1 leading-relaxed", size: "sm", color: "muted", children: ["\u201C", t.text, "\u201D"] }), _jsxs(Text, { className: "font-black uppercase text-[var(--color-yellow)] tracking-[0.06em]", size: "xs", children: ["\u2014 ", t.name] })] }, t.id))) })] }) }));
 }

package/dist/features/homepage/components/index.d.ts

@@ -1,24 +1,13 @@
-export { HeroSection } from "./HeroSection";
 export type { CharacterHotspotProps } from "./CharacterHotspot";
 export { CharacterHotspot } from "./CharacterHotspot";
 export type { CharacterHotspotFormProps } from "./CharacterHotspotForm";
 export { CharacterHotspotForm } from "./CharacterHotspotForm";
-export type { HeroBannerProps } from "./HeroBanner";
-export { HeroBanner } from "./HeroBanner";
 export type { HeroCarouselProps } from "./HeroCarousel";
 export { HeroCarousel } from "./HeroCarousel";
 export type { PromoGridProps } from "./PromoGrid";
 export { PromoGrid } from "./PromoGrid";
-export type { TrustBadgesProps } from "./TrustBadges";
-export { TrustBadges } from "./TrustBadges";
 export type { TestimonialsCarouselProps } from "./TestimonialsCarousel";
 export { TestimonialsCarousel } from "./TestimonialsCarousel";
-export type { BeforeAfterCardProps } from "./BeforeAfterCard";
-export { BeforeAfterCard } from "./BeforeAfterCard";
-export type { NewsletterBannerProps } from "./NewsletterBanner";
-export { NewsletterBanner } from "./NewsletterBanner";
-export { HomepageView } from "./HomepageView";
-export type { HomepageViewProps } from "./HomepageView";
 export { MarketplaceHomepageView } from "./MarketplaceHomepageView";
 export type { MarketplaceHomepageViewProps, MarketplaceHomepageViewAdSlots, } from "./MarketplaceHomepageView";
 export type { SectionCarouselProps } from "./SectionCarousel";
@@ -37,19 +26,10 @@ export type { FAQItem, FAQTab, FAQSectionProps } from "./FAQSection";
 export { FAQSection } from "./FAQSection";
 export type { NewsletterSectionProps } from "./NewsletterSection";
 export { NewsletterSection } from "./NewsletterSection";
-export type { AdvertisementBannerProps } from "./AdvertisementBanner";
-export { AdvertisementBanner } from "./AdvertisementBanner";
 export type { SecurityHighlightItem, SecurityHighlightsSectionProps, } from "./SecurityHighlightsSection";
 export { SecurityHighlightsSection } from "./SecurityHighlightsSection";
-export type { SiteFeatureItem, SiteFeaturesSectionProps, } from "./SiteFeaturesSection";
-export { SiteFeaturesSection } from "./SiteFeaturesSection";
-export type { TrustIndicatorItem, TrustIndicatorsSectionProps, } from "./TrustIndicatorsSection";
-export { TrustIndicatorsSection } from "./TrustIndicatorsSection";
 export type { WhatsAppCommunitySectionProps } from "./WhatsAppCommunitySection";
 export { WhatsAppCommunitySection } from "./WhatsAppCommunitySection";
-export { HomepageSkeleton } from "./HomepageSkeleton";
-export type { FeaturedResultItem, FeaturedResultsSectionProps, } from "./FeaturedResultsSection";
-export { FeaturedResultsSection } from "./FeaturedResultsSection";
 export type { AnnouncementBarProps } from "./AnnouncementBar";
 export { AnnouncementBar, hashBannerMessage } from "./AnnouncementBar";
 export type { ShopByCategorySectionProps } from "./ShopByCategorySection";

package/dist/features/homepage/components/index.js

@@ -1,14 +1,8 @@
-export { HeroSection } from "./HeroSection.js";
 export { CharacterHotspot } from "./CharacterHotspot.js";
 export { CharacterHotspotForm } from "./CharacterHotspotForm.js";
-export { HeroBanner } from "./HeroBanner.js";
 export { HeroCarousel } from "./HeroCarousel.js";
 export { PromoGrid } from "./PromoGrid.js";
-export { TrustBadges } from "./TrustBadges.js";
 export { TestimonialsCarousel } from "./TestimonialsCarousel.js";
-export { BeforeAfterCard } from "./BeforeAfterCard.js";
-export { NewsletterBanner } from "./NewsletterBanner.js";
-export { HomepageView } from "./HomepageView.js";
 export { MarketplaceHomepageView } from "./MarketplaceHomepageView.js";
 export { SectionCarousel } from "./SectionCarousel.js";
 export { WelcomeSection } from "./WelcomeSection.js";
@@ -18,13 +12,8 @@ export { HowItWorksSection } from "./HowItWorksSection.js";
 export { CustomerReviewsSection } from "./CustomerReviewsSection.js";
 export { FAQSection } from "./FAQSection.js";
 export { NewsletterSection } from "./NewsletterSection.js";
-export { AdvertisementBanner } from "./AdvertisementBanner.js";
 export { SecurityHighlightsSection } from "./SecurityHighlightsSection.js";
-export { SiteFeaturesSection } from "./SiteFeaturesSection.js";
-export { TrustIndicatorsSection } from "./TrustIndicatorsSection.js";
 export { WhatsAppCommunitySection } from "./WhatsAppCommunitySection.js";
-export { HomepageSkeleton } from "./HomepageSkeleton.js";
-export { FeaturedResultsSection } from "./FeaturedResultsSection.js";
 export { AnnouncementBar, hashBannerMessage } from "./AnnouncementBar.js";
 export { ShopByCategorySection } from "./ShopByCategorySection.js";
 export { FeaturedProductsSection } from "./FeaturedProductsSection.js";

package/dist/features/homepage/index.d.ts

@@ -1,6 +1,4 @@
 export * from "./types";
-export * from "./hooks/useHomepage";
-export * from "./hooks/useHomepageSections";
 export * from "./hooks/useHeroCarousel";
 export * from "./hooks/useFeaturedProducts";
 export * from "./hooks/useFeaturedAuctions";

package/dist/features/homepage/index.js

@@ -1,6 +1,4 @@
 export * from "./types/index.js";
-export * from "./hooks/useHomepage.js";
-export * from "./hooks/useHomepageSections.js";
 export * from "./hooks/useHeroCarousel.js";
 export * from "./hooks/useFeaturedProducts.js";
 export * from "./hooks/useFeaturedAuctions.js";

package/dist/features/homepage/lib/section-renderer.d.ts

@@ -47,5 +47,14 @@ export interface HomepageBrand {
     /** Short mark shown in the hero panel, e.g. "LT". */
     shortName?: string;
 }
+/**
+ * Every surface a `SectionDef` may be mounted on.
+ *
+ * `"homepage"` is the only one any renderer currently receives data for — see
+ * the note on `SectionDef.surfaces` below. The others are declared now so a
+ * reuse decision has somewhere reviewable to live, ahead of the data-loading
+ * work that would make them real.
+ */
+export type SectionSurface = "homepage" | "category" | "brand" | "product" | "store";
 export declare function renderSection(section: HomepageSectionDocument, adSlots: MarketplaceHomepageViewAdSlots | undefined, newsletterFormSlot: React.ReactNode, faqItems: FaqItem[], slides: CarouselSlide[], liveStats: LiveStatsMap, sectionData?: SectionData, brand?: HomepageBrand): React.ReactNode;
 export { AnnouncementBar, hashBannerMessage };

package/dist/features/homepage/lib/section-renderer.js

@@ -35,31 +35,55 @@ import { HomepageSectionBoundary } from "../components/HomepageSectionBoundary.j
 import { PrizeDrawsSection } from "../../products/components/PrizeDrawsSection.js";
 import { EventRafflesSection } from "../../events/components/EventRafflesSection.js";
 import { CollectionCardsSection } from "../components/CollectionCardsSection.js";
+import { HowItWorksSection } from "../components/HowItWorksSection.js";
+import { TestimonialsCarousel } from "../components/TestimonialsCarousel.js";
+import { PromoGrid } from "../components/PromoGrid.js";
 const AD_SLOT_MAP = {
     carousel: "afterHero",
     products: "afterFeaturedProducts",
     reviews: "afterReviews",
     faq: "afterFAQ",
 };
-function renderSectionElement(section, newsletterFormSlot, faqItems, slides, liveStats, sectionData, brand) {
-    const { type, config } = section;
-    switch (type) {
-        case "carousel": {
+/**
+ * One entry per `SectionType`, replacing the 25-arm `switch` this registry is
+ * carved from verbatim — every case body below is byte-identical to its
+ * switch arm, only re-homed into an object property.
+ *
+ * `Record<SectionType, SectionDef>` is EXHAUSTIVE: a `SectionType` added to
+ * the union without an entry here is a compile error, where the switch's
+ * `default: return null` let a listed-but-unhandled type render nothing with
+ * no signal anywhere. `audit-homepage-config-coverage` still passes with zero
+ * changes — it does a bare name-presence `test()` against this file as a flat
+ * string, and every config field name below is exactly where it always was.
+ */
+const SECTION_REGISTRY = {
+    carousel: {
+        surfaces: ["homepage"],
+        render: ({ config, slides }) => {
             const cfg = config;
             return (_jsx(HeroCarousel, { initialSlides: slides, title: cfg?.title, height: cfg?.height, defaultAutoplayDelayMs: cfg?.defaultAutoplayDelayMs, pauseOnHover: cfg?.pauseOnHover, showDots: cfg?.showDots, showArrows: cfg?.showArrows }));
-        }
-        case "welcome": {
+        },
+    },
+    welcome: {
+        surfaces: ["homepage"],
+        render: ({ config, brand }) => {
             const cfg = config;
             return (_jsx(WelcomeSection, { title: cleanTitle(cfg?.h1) || SECTION_TITLE.welcome, 
                 // A real `subtitle` wins; `description` is the legacy source and is
                 // still parsed for documents that only carry it.
                 subtitle: cfg?.subtitle?.trim() || parseWelcomeDescription(cfg?.description), pillLabel: cfg?.pillLabel || SECTION_COPY.welcomePill, showCTA: cfg?.showCTA ?? true, ctaLabel: cfg?.ctaText || SECTION_COPY.welcomePrimaryCta, ctaHref: cfg?.ctaLink || ROUTES.PUBLIC.PRODUCTS, secondaryCtaLabel: cfg?.secondaryCtaText || SECTION_COPY.welcomeSecondaryCta, secondaryCtaHref: cfg?.secondaryCtaLink || ROUTES.PUBLIC.PRODUCTS, trustChips: [...WELCOME_TRUST_CHIPS], brandLogoText: brand?.shortName }));
-        }
-        case "categories": {
+        },
+    },
+    categories: {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(ShopByCategorySection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.categories, viewMoreHref: ROUTES.PUBLIC.CATEGORIES, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.categories, initialItems: sectionData.categories, limit: cfg?.maxCategories, cta: cfg?.cta, filters: cfg?.filters, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "stats": {
+        },
+    },
+    stats: {
+        surfaces: ["homepage"],
+        render: ({ config, liveStats }) => {
             const cfg = config;
             const stats = Array.isArray(cfg?.stats)
                 ? cfg.stats
@@ -85,44 +109,68 @@ function renderSectionElement(section, newsletterFormSlot, faqItems, slides, liv
             if (stats.length === 0)
                 return null;
             return _jsx(StatsCounterSection, { stats: stats, title: cleanTitle(cfg?.title) });
-        }
-        case "products": {
+        },
+    },
+    products: {
+        surfaces: ["homepage", "category", "brand", "product"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(FeaturedProductsSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.products, description: cfg?.subtitle, viewMoreHref: ROUTES.PUBLIC.PRODUCTS, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.products, filterByBrand: cfg?.filterByBrand, initialItems: sectionData.products, rows: cfg?.rows, 
                 // `maxProducts` is what the admin builder's "Max items" input writes;
                 // `maxItems` is the schema's own name. The two never met, so the
                 // control had no effect. Read both, newest name first.
                 maxItems: cfg?.maxItems ?? cfg?.maxProducts, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "auctions": {
+        },
+    },
+    auctions: {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(FeaturedAuctionsSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.auctions, description: cfg?.subtitle, viewMoreHref: ROUTES.PUBLIC.AUCTIONS, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.auctions, filterByBrand: cfg?.filterByBrand, initialItems: sectionData.auctions, rows: cfg?.rows, maxItems: cfg?.maxAuctions, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "pre-orders": {
+        },
+    },
+    "pre-orders": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(FeaturedPreOrdersSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.preOrders, description: cfg?.subtitle, viewMoreHref: ROUTES.PUBLIC.PRE_ORDERS, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.preOrders, filterByBrand: cfg?.filterByBrand, initialItems: sectionData.preOrders, rows: cfg?.rows, maxItems: cfg?.maxItems, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "stores": {
+        },
+    },
+    stores: {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(FeaturedStoresSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.stores, description: cfg?.subtitle, viewMoreHref: ROUTES.PUBLIC.STORES, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.stores, initialItems: sectionData.stores, limit: cfg?.maxStores, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "events": {
+        },
+    },
+    events: {
+        surfaces: ["homepage"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(EventsSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.events, description: cfg?.subtitle, viewMoreHref: ROUTES.PUBLIC.EVENTS, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.events, initialItems: sectionData.events, limit: cfg?.maxEvents, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "reviews": {
+        },
+    },
+    reviews: {
+        surfaces: ["homepage", "category", "brand", "product"],
+        render: ({ config }) => {
             const cfg = config;
             return (_jsx(HomepageCustomerReviewsSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.reviews, viewMoreHref: ROUTES.PUBLIC.REVIEWS, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.reviews, maxReviews: cfg?.maxReviews, itemsPerView: cfg?.itemsPerView, mobileItemsPerView: cfg?.mobileItemsPerView, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "banner": {
+        },
+    },
+    banner: {
+        surfaces: ["homepage", "category", "brand", "product"],
+        render: ({ config }) => {
             const cfg = config;
             // CTAs come from the configured buttons; the component's own neutral
             // defaults fill in when none are set. Previously both labels and both
             // hrefs were hardcoded here and `buttons[]` was ignored entirely.
             const [primaryBtn, secondaryBtn] = cfg?.buttons ?? [];
             return (_jsx(CTABannerSection, { title: cfg?.content?.title || SECTION_TITLE.banner, subtitle: cfg?.content?.subtitle, description: cfg?.content?.description, height: cfg?.height, backgroundImage: cfg?.backgroundImage, primaryLabel: primaryBtn?.text, primaryHref: primaryBtn?.link, secondaryLabel: secondaryBtn?.text, secondaryHref: secondaryBtn?.link }));
-        }
-        case "trust-indicators": {
+        },
+    },
+    "trust-indicators": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, brand }) => {
             const cfg = config;
             const configured = (cfg?.indicators ?? [])
                 .filter((ind) => ind?.title?.trim())
@@ -134,8 +182,11 @@ function renderSectionElement(section, newsletterFormSlot, faqItems, slides, liv
             }));
             return (_jsx(TrustFeaturesSection, { title: cleanTitle(cfg?.title) ||
                     (brand?.name ? `Why Buyers Trust ${brand.name}` : SECTION_TITLE.trustIndicators), items: configured.length > 0 ? configured : DEFAULT_TRUST_FEATURES }));
-        }
-        case "features": {
+        },
+    },
+    features: {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
             const cfg = config;
             // `items` is the real shape; `features: string[]` is the legacy one and
             // becomes title-only cards. Neither reached the component before — it
@@ -146,15 +197,21 @@ function renderSectionElement(section, newsletterFormSlot, faqItems, slides, liv
                     .map((label, index) => ({ key: `feature-${index}`, title: label, description: "" })) ??
                 [];
             return (_jsx(SecurityHighlightsSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.features, pillLabel: cfg?.pillLabel || SECTION_COPY.featuresPill, items: configured.length > 0 ? configured : DEFAULT_SECURITY_ITEMS, learnMoreHref: cfg?.learnMoreLink || ROUTES.PUBLIC.SECURITY, learnMoreLabel: cfg?.learnMoreLabel || SECTION_COPY.featuresLearnMore }));
-        }
-        case "whatsapp-community": {
+        },
+    },
+    "whatsapp-community": {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
             const cfg = config;
             return (_jsx(WhatsAppCommunitySection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.whatsappCommunity, descriptionHtml: cfg?.description || SECTION_COPY.whatsappDescription, 
                 // No `|| 5000` fallback: inventing a member count the site cannot
                 // verify is a fabricated social-proof number.
                 memberCount: cfg?.memberCount, groupLink: cfg?.groupLink || "https://chat.whatsapp.com/", benefits: cfg?.benefits ?? [], testimonial: cfg?.testimonial, buttonText: cfg?.buttonText }));
-        }
-        case "faq": {
+        },
+    },
+    faq: {
+        surfaces: ["homepage", "category", "brand", "product"],
+        render: ({ config, faqItems }) => {
             const cfg = config;
             if (!cfg?.showOnHomepage || faqItems.length === 0)
                 return null;
@@ -177,55 +234,142 @@ function renderSectionElement(section, newsletterFormSlot, faqItems, slides, liv
             const totalFaqs = faqItems.length;
             const hasMore = totalFaqs > slicedItems.length || readSaturated;
             return (_jsx(FAQSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.faq, subtitle: cfg?.subtitle, tabs: tabs, showCategoryTabs: cfg?.showCategoryTabs ?? false, allowMultipleOpen: cfg?.allowMultipleOpen ?? false, defaultOpenCount: cfg?.defaultOpenCount ?? 0, items: slicedItems, viewMoreHref: cfg?.linkToFullPage ? ROUTES.PUBLIC.FAQS : undefined, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.faq, hasMore: hasMore, moreCount: readSaturated ? 0 : totalFaqs - slicedItems.length }));
-        }
-        case "blog-articles": {
+        },
+    },
+    "blog-articles": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(BlogArticlesSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.blogArticles, viewMoreHref: ROUTES.BLOG.LIST, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.blogArticles, initialItems: sectionData.blog, limit: cfg?.maxArticles, showReadTime: cfg?.showReadTime, showAuthor: cfg?.showAuthor, showThumbnails: cfg?.showThumbnails }));
-        }
-        case "newsletter": {
+        },
+    },
+    newsletter: {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, newsletterFormSlot }) => {
             const cfg = config;
             return (_jsx(NewsletterSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.newsletter, subtitle: cfg?.description, privacyLabel: cfg?.privacyText, privacyHref: cfg?.privacyLink, renderForm: () => newsletterFormSlot ?? null }));
-        }
-        case "brands": {
+        },
+    },
+    brands: {
+        // Homepage-only, not category/brand: a rail of OTHER brands reads as
+        // intended cross-sell on the homepage, but on a BRAND's own detail page it
+        // would compete with that brand's reason for being there. A category page
+        // has `BrandsSection` reachable via its own tabs/grid already.
+        surfaces: ["homepage"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(BrandsSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.brands, subtitle: cfg?.subtitle, limit: cfg?.maxBrands || 12, viewMoreHref: ROUTES.PUBLIC.CATEGORIES, viewMoreLabel: cfg?.viewMoreLabel || VIEW_MORE_LABEL.brands, initialItems: sectionData.brands, cta: cfg?.cta, filters: cfg?.filters, autoScroll: cfg?.autoScroll, scrollInterval: cfg?.scrollInterval, loop: cfg?.loop }));
-        }
-        case "social-feed": {
+        },
+    },
+    "social-feed": {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
             const cfg = config;
             const hasStaticPosts = Array.isArray(cfg?.posts) && cfg.posts.length > 0;
             if (!cfg?.platform || (!cfg?.handle && !hasStaticPosts))
                 return null;
             return (_jsx(SocialFeedSection, { title: cleanTitle(cfg.title) || "", subtitle: cfg.subtitle, platform: cfg.platform, handle: cfg.handle ?? "", postType: cfg.postType || "all", count: cfg.count || 9, layout: cfg.layout || "grid", showCaption: cfg.showCaption ?? true, showStats: cfg.showStats ?? true, posts: cfg.posts }));
-        }
-        case "custom-cards": {
+        },
+    },
+    "custom-cards": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config }) => {
             const cfg = config;
             if (!cfg?.cards?.length)
                 return null;
             return (_jsx(CustomCardsSection, { title: cleanTitle(cfg.title), layout: cfg.layout ?? "grid", columns: cfg.columns ?? 3, cards: cfg.cards, autoScroll: cfg.autoScroll, scrollIntervalMs: cfg.scrollIntervalMs, loop: cfg.loop }));
-        }
-        case "google-reviews": {
+        },
+    },
+    "google-reviews": {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
             const cfg = config;
             return (_jsx(GoogleReviewsSection, { placeId: cfg?.placeId ?? "", maxReviews: cfg?.maxReviews ?? 6, minRating: cfg?.minRating ?? 0, layout: cfg?.layout ?? "grid", showRating: cfg?.showRating ?? true, showDate: cfg?.showDate ?? true, linkToGoogleMaps: cfg?.linkToGoogleMaps ?? true, googleMapsUrl: cfg?.googleMapsUrl }));
-        }
-        case "featured-bundles": {
+        },
+    },
+    "featured-bundles": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
             const cfg = config;
             return (_jsx(FeaturedBundlesSection, { title: cleanTitle(cfg?.title) || SECTION_TITLE.featuredBundles, description: cfg?.subtitle, initialItems: sectionData.bundles, maxItems: cfg?.maxItems, showSavingsBadge: cfg?.showSavingsBadge, viewMoreLabel: cfg?.viewMoreLabel }));
-        }
-        case "prize-draws": {
+        },
+    },
+    "prize-draws": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config }) => {
             const cfg = config;
             return _jsx(PrizeDrawsSection, { config: cfg ?? {} });
-        }
-        case "event-raffles": {
+        },
+    },
+    "event-raffles": {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
             const cfg = config;
             return _jsx(EventRafflesSection, { config: cfg ?? {} });
-        }
-        case "collection-cards": {
-            const cfg = config;
-            return (_jsx(CollectionCardsSection, { config: cfg ?? { collections: [] } }));
-        }
-        default:
-            return null;
-    }
+        },
+    },
+    "collection-cards": {
+        surfaces: ["homepage", "category", "brand"],
+        render: ({ config, sectionData }) => {
+            const cfg = config;
+            return (_jsx(CollectionCardsSection, { config: cfg ?? { collections: [] }, 
+                // The `categories`/`brands`/`stores` arrays homepage already fetches
+                // for ITS OWN same-named sections — zero extra round-trips. See the
+                // component's own docstring for why only these three are wired.
+                sectionData: {
+                    categories: sectionData.categories,
+                    brands: sectionData.brands,
+                    stores: sectionData.stores,
+                } }));
+        },
+    },
+    // Promoted out of the orphan-component set 2026-10-19 (see each component's
+    // own docstring for the config-serialisability fixes this required).
+    "how-it-works": {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
+            const cfg = config;
+            if (!cfg?.title || !Array.isArray(cfg.steps) || cfg.steps.length === 0)
+                return null;
+            return (_jsx(HowItWorksSection, { title: cfg.title, subtitle: cfg.subtitle, pillLabel: cfg.pillLabel, ctaLabel: cfg.ctaLabel, ctaLink: cfg.ctaLink, steps: cfg.steps }));
+        },
+    },
+    testimonials: {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
+            const cfg = config;
+            if (!Array.isArray(cfg?.testimonials) || cfg.testimonials.length === 0)
+                return null;
+            return (_jsx(TestimonialsCarousel, { eyebrow: cfg.eyebrow, heading: cfg.heading, testimonials: cfg.testimonials }));
+        },
+    },
+    "promo-grid": {
+        surfaces: ["homepage"],
+        render: ({ config }) => {
+            const cfg = config;
+            if (!Array.isArray(cfg?.banners) || cfg.banners.length === 0)
+                return null;
+            return (_jsx(PromoGrid, { eyebrow: cfg.eyebrow, heading: cfg.heading, banners: cfg.banners }));
+        },
+    },
+};
+function renderSectionElement(section, newsletterFormSlot, faqItems, slides, liveStats, sectionData, brand) {
+    const def = SECTION_REGISTRY[section.type];
+    // No `default` arm left to fall through to — an unmapped `SectionType` is a
+    // compile error on the registry object above, not a runtime `null`. This
+    // branch only guards a value that bypassed the type system (a raw Firestore
+    // read of a document whose `type` predates the current union).
+    if (!def)
+        return null;
+    return def.render({
+        config: section.config,
+        newsletterFormSlot,
+        faqItems,
+        slides,
+        liveStats,
+        sectionData,
+        brand,
+    });
 }
 export function renderSection(section, adSlots, newsletterFormSlot, faqItems, slides, liveStats, sectionData = {}, brand) {
     const sectionElement = renderSectionElement(section, newsletterFormSlot, faqItems, slides, liveStats, sectionData, brand);

package/dist/features/homepage/repository/homepage-sections.repository.d.ts

@@ -5,7 +5,7 @@
  */
 import type { JsonValue } from "@mohasinac/appkit";
 import { BaseRepository, type FirebaseSieveFields, type FirebaseSieveResult, type SieveModel } from "../../../providers/db-firebase";
-import { type HomepageSectionCreateInput, type HomepageSectionDocument, type SectionType } from "../schemas";
+import { type HomepageSectionCreateInput, type HomepageSectionDocument, type SectionSurface, type SectionType } from "../schemas";
 export declare class HomepageSectionsRepository extends BaseRepository<HomepageSectionDocument> {
     constructor();
     static readonly SIEVE_FIELDS: FirebaseSieveFields;
@@ -34,9 +34,41 @@ export declare class HomepageSectionsRepository extends BaseRepository<HomepageS
      * below deliberately keeps replace semantics — that is its whole purpose.
      */
     update(id: string, data: Partial<HomepageSectionDocument>): Promise<HomepageSectionDocument>;
-    getEnabledSections(): Promise<HomepageSectionDocument[]>;
+    /**
+     * Enabled sections for one surface, in `order`.
+     *
+     * 🛑 The parameter DEFAULTS to `"homepage"`, and that default is the safety
+     * property, not a convenience. This method previously returned every enabled
+     * row regardless of surface — so the moment a category-surface row exists,
+     * an unfiltered homepage would render it. Defaulting here means the existing
+     * homepage call site is correct with no change at all, and a caller that
+     * wants another surface has to say so.
+     *
+     * 🛑 The surface is matched IN MEMORY, deliberately. The only composite index
+     * on this collection is `(enabled, order)`;
+     * `where(enabled).where(surface).orderBy(order)` is a three-field composite it
+     * does not cover, and Firestore throws FAILED_PRECONDITION at RUNTIME rather
+     * than at build time. `MarketplaceHomepageView` already filters sections in
+     * memory for the listing-type gate — this follows that precedent. Section
+     * counts are tens, so the read is unchanged in cost.
+     */
+    getEnabledSections(surface?: SectionSurface): Promise<HomepageSectionDocument[]>;
     getDisabledSections(): Promise<HomepageSectionDocument[]>;
-    getSectionByType(type: SectionType): Promise<HomepageSectionDocument | null>;
+    /**
+     * 🛑 `surface` is NOT optional in spirit, even though it defaults.
+     *
+     * This was `where(type == X).limit(1)`, which assumed ONE document per type.
+     * With surfaces that assumption is false — a `products` section can exist on
+     * the homepage AND on a category page — and `limit(1)` would return whichever
+     * Firestore happened to order first. An arbitrary-but-plausible answer is the
+     * worst failure shape available here, because nothing errors.
+     *
+     * The surface is matched IN MEMORY rather than added as a second `where`: the
+     * only composite index on this collection is `(enabled, order)`, and
+     * `where(type).where(surface)` needs one that does not exist. Fetching the few
+     * rows of a type and picking by surface costs nothing at these counts.
+     */
+    getSectionByType(type: SectionType, surface?: SectionSurface): Promise<HomepageSectionDocument | null>;
     enableSection(sectionId: string): Promise<HomepageSectionDocument>;
     disableSection(sectionId: string): Promise<HomepageSectionDocument>;
     toggleSection(sectionId: string): Promise<HomepageSectionDocument>;