@mohasinac/appkit 2.3.1 → 2.4.0

package/dist/features/homepage/schemas/firestore.d.ts

@@ -2,45 +2,77 @@
  * Homepage Feature Firestore Document Types & Constants
  * Covers: carousel slides, homepage sections
  */
-export interface GridCard {
-    id: string;
-    gridRow: 1 | 2;
-    gridCol: 1 | 2 | 3;
-    background: {
-        type: "color" | "gradient" | "image" | "video";
-        value: string;
-        overlay?: {
-            enabled: boolean;
-            color: string;
-            opacity: number;
-        };
+/** Unified background for a slide or card — supports image, video, solid color, or gradient. */
+export interface CarouselBackground {
+    type: "image" | "video" | "color" | "gradient";
+    /** URL for image/video backgrounds */
+    url?: string;
+    /** Mobile-optimised URL (image/video) */
+    mobileUrl?: string;
+    /** Poster frame URL for video backgrounds */
+    thumbnail?: string;
+    /** Hex/token value for solid-color backgrounds */
+    color?: string;
+    /** Gradient start color (token or hex) */
+    gradientFrom?: string;
+    /** Gradient end color (token or hex) */
+    gradientTo?: string;
+    /** Gradient angle in degrees (0–360) */
+    gradientAngle?: number;
+    /** Dim overlay drawn on top of image/video */
+    dimOverlay?: {
+        enabled: boolean;
+        opacity: number;
     };
+}
+export type CarouselSlideHeight = "viewport" | "tall" | "medium";
+export type CarouselHoverEffect = "scale" | "color" | "glow" | "none";
+/** A content card placed in one of 6 grid zones (2 rows × 3 cols). */
+export interface CarouselCard {
+    id: string;
+    /** Zone 1–6: row 1 = zones 1–3, row 2 = zones 4–6 */
+    zone: 1 | 2 | 3 | 4 | 5 | 6;
+    /** On mobile, collapse to row-1 centre (zone 2) or row-2 centre (zone 5) */
+    mobileZone?: 2 | 5;
+    background: CarouselBackground;
     content?: {
+        eyebrow?: string;
         title?: string;
         subtitle?: string;
         description?: string;
         textColor?: string;
+        textAlign?: "left" | "center" | "right";
     };
     buttons?: Array<{
         id?: string;
         text: string;
-        link: string;
-        variant: "primary" | "secondary" | "outline";
-        openInNewTab: boolean;
+        href: string;
+        variant: "primary" | "secondary" | "outline" | "ghost" | "link";
+        openInNewTab?: boolean;
     }>;
-    isButtonOnly: boolean;
-    sizing?: {
-        width?: "auto" | "full" | "1/2" | "1/3" | "2/3";
-        height?: "auto" | "full" | "sm" | "md" | "lg";
+    hover?: {
+        effect: CarouselHoverEffect;
+        scaleValue?: number;
+        colorValue?: string;
     };
+    isButtonOnly?: boolean;
+    /** Legacy — kept for backward compat; use `zone` instead */
+    gridRow?: 1 | 2;
+    /** Legacy — kept for backward compat; use `zone` instead */
+    gridCol?: 1 | 2 | 3;
 }
-export type GridCardCreateInput = Omit<GridCard, "id">;
+/** @deprecated Use CarouselCard. This alias is kept for backward compatibility. */
+export type GridCard = CarouselCard;
+export type GridCardCreateInput = Omit<CarouselCard, "id">;
 export interface CarouselSlideDocument {
     id: string;
     title: string;
     order: number;
     active: boolean;
-    media: {
+    /** New unified background field (CF1). */
+    background?: CarouselBackground;
+    /** @deprecated Use `background`. Kept for backward compat — component falls back gracefully. */
+    media?: {
         type: "image" | "video";
         url: string;
         alt?: string;
@@ -50,18 +82,17 @@ export interface CarouselSlideDocument {
         url: string;
         openInNewTab: boolean;
     };
+    /** @deprecated Use `background.mobileUrl`. Kept for backward compat. */
     mobileMedia?: {
         type: "image" | "video";
         url: string;
         alt?: string;
     };
-    cards: GridCard[];
+    cards: CarouselCard[];
     overlay?: {
-        /** Visual overlay — dims the background image */
         enabled?: boolean;
         color?: string;
         opacity?: number;
-        /** Content overlay — text and CTA layered over the slide */
         title?: string;
         subtitle?: string;
         description?: string;
@@ -73,6 +104,10 @@ export interface CarouselSlideDocument {
             openInNewTab: boolean;
         };
     };
+    settings?: {
+        autoplayDelayMs?: number;
+        height?: CarouselSlideHeight;
+    };
     analytics?: {
         views: number;
         lastViewed?: Date;
@@ -89,9 +124,9 @@ export declare const GRID_CONFIG: {
     readonly cols: 3;
 };
 export declare const DEFAULT_CAROUSEL_SLIDE_DATA: Partial<CarouselSlideDocument>;
-export declare const CAROUSEL_SLIDES_PUBLIC_FIELDS: readonly ["id", "title", "order", "active", "media", "link", "mobileMedia", "cards", "overlay"];
+export declare const CAROUSEL_SLIDES_PUBLIC_FIELDS: readonly ["id", "title", "order", "active", "background", "media", "link", "mobileMedia", "cards", "overlay", "settings"];
 export type CarouselSlideCreateInput = Omit<CarouselSlideDocument, "id" | "createdAt" | "updatedAt">;
-export type CarouselSlideUpdateInput = Partial<Pick<CarouselSlideDocument, "title" | "order" | "active" | "media" | "link" | "mobileMedia" | "cards">>;
+export type CarouselSlideUpdateInput = Partial<Pick<CarouselSlideDocument, "title" | "order" | "active" | "background" | "media" | "link" | "mobileMedia" | "cards" | "overlay" | "settings">>;
 export declare const carouselSlideQueryHelpers: {
     readonly active: () => readonly ["active", "==", true];
     readonly inactive: () => readonly ["active", "==", false];
@@ -100,6 +135,15 @@ export declare const carouselSlideQueryHelpers: {
 export declare function createCarouselId(title: string): string;
 export declare function isValidGridPosition(gridRow: number, gridCol: number): boolean;
 export declare function canActivateSlide(currentActiveCount: number): boolean;
+/** Config for the hero carousel section — references the carouselSlides collection. */
+export interface CarouselSectionConfig {
+    title?: string;
+    height?: CarouselSlideHeight;
+    defaultAutoplayDelayMs?: number;
+    pauseOnHover?: boolean;
+    showDots?: boolean;
+    showArrows?: boolean;
+}
 export interface WelcomeSectionConfig {
     h1: string;
     subtitle: string;
@@ -139,13 +183,31 @@ export interface ProductsSectionConfig {
     mobileItemsPerRow: 1;
     autoScroll: boolean;
     scrollInterval: number;
+    filterByBrand?: string;
+    sortBy?: "latest" | "oldest" | "priceLow" | "priceHigh" | "featured" | "onSale" | "popular";
+    filterByCategory?: string;
+    maxCount?: 5 | 10 | 20;
+    loop?: boolean;
 }
+/**
+ * Metrics that the homepage stats section can resolve live from Firestore.
+ * When a stat has source "live" and a matching metric, the value field is
+ * used only as a fallback (shown if the live fetch fails or is still loading).
+ */
+export type LiveStatMetric = "total_listings" | "verified_sellers" | "total_buyers" | "platform_rating" | "total_orders" | "total_reviews";
 export interface StatsSectionConfig {
     title?: string;
     stats: Array<{
         key: string;
         label: string;
+        /** Fallback value shown when source is "static" or when a live fetch fails. */
         value: string;
+        /** "live" resolves the value from Firestore at render time; "static" uses value as-is. */
+        source?: "static" | "live";
+        /** Which Firestore metric to fetch when source is "live". */
+        metric?: LiveStatMetric;
+        /** Optional suffix appended after the live value (e.g. "★", "+"). */
+        suffix?: string;
     }>;
 }
 export interface AuctionsSectionConfig {
@@ -157,6 +219,11 @@ export interface AuctionsSectionConfig {
     mobileItemsPerRow: 1;
     autoScroll: boolean;
     scrollInterval: number;
+    filterByBrand?: string;
+    sortBy?: "latest" | "oldest" | "priceLow" | "priceHigh" | "featured" | "onSale" | "popular";
+    filterByCategory?: string;
+    maxCount?: 5 | 10 | 20;
+    loop?: boolean;
 }
 export interface ReviewsSectionConfig {
     title: string;
@@ -165,6 +232,8 @@ export interface ReviewsSectionConfig {
     mobileItemsPerView: 1;
     autoScroll: boolean;
     scrollInterval: number;
+    source?: "platform" | "google";
+    placeId?: string;
 }
 export interface WhatsAppCommunitySectionConfig {
     title: string;
@@ -186,7 +255,7 @@ export interface FAQSectionConfig {
     displayCount: number;
     expandedByDefault: boolean;
     linkToFullPage: boolean;
-    categories: Array<"general" | "shipping" | "returns" | "payment" | "account" | "products" | "sellers">;
+    categories: Array<"general" | "orders_payment" | "shipping_delivery" | "returns_refunds" | "product_information" | "account_security" | "technical_support">;
 }
 export interface BlogArticlesSectionConfig {
     title: string;
@@ -209,6 +278,10 @@ export interface StoresSectionConfig {
     maxStores: number;
     autoScroll: boolean;
     scrollInterval: number;
+    sortBy?: "latest" | "oldest" | "priceLow" | "priceHigh" | "featured" | "onSale" | "popular";
+    filterByCategory?: string;
+    maxCount?: 5 | 10 | 20;
+    loop?: boolean;
 }
 export interface EventsSectionConfig {
     title: string;
@@ -216,6 +289,42 @@ export interface EventsSectionConfig {
     maxEvents: number;
     autoScroll: boolean;
     scrollInterval: number;
+    sortBy?: "latest" | "oldest" | "priceLow" | "priceHigh" | "featured" | "onSale" | "popular";
+    filterByCategory?: string;
+    maxCount?: 5 | 10 | 20;
+    loop?: boolean;
+}
+export type SocialPlatform = "instagram" | "facebook" | "tiktok" | "deviantart";
+export type SocialPostType = "all" | "images" | "videos" | "reels";
+export type SocialFeedLayout = "grid" | "masonry" | "carousel";
+export interface SocialFeedSectionConfig {
+    title: string;
+    subtitle?: string;
+    platform: SocialPlatform;
+    /** Username, page ID, or handle for the platform account */
+    handle: string;
+    postType: SocialPostType;
+    /** Number of posts to display (4–12) */
+    count: number;
+    layout: SocialFeedLayout;
+    showCaption: boolean;
+    showStats: boolean;
+}
+/** Normalised social post returned by /api/social-feed */
+export interface SocialPost {
+    id: string;
+    platform: SocialPlatform;
+    imageUrl: string;
+    videoThumbnailUrl?: string;
+    caption?: string;
+    permalink: string;
+    mediaType: "image" | "video" | "carousel";
+    stats: {
+        likes?: number;
+        views?: number;
+        comments?: number;
+    };
+    publishedAt: string;
 }
 export interface PreOrdersSectionConfig {
     title: string;
@@ -226,6 +335,11 @@ export interface PreOrdersSectionConfig {
     mobileItemsPerRow: 1;
     autoScroll: boolean;
     scrollInterval: number;
+    filterByBrand?: string;
+    sortBy?: "latest" | "oldest" | "priceLow" | "priceHigh" | "featured" | "onSale" | "popular";
+    filterByCategory?: string;
+    maxCount?: 5 | 10 | 20;
+    loop?: boolean;
 }
 export interface BannerSectionConfig {
     height: "sm" | "md" | "lg" | "xl";
@@ -245,8 +359,45 @@ export interface BannerSectionConfig {
     clickable: boolean;
     clickLink?: string;
 }
-export type SectionType = "welcome" | "stats" | "trust-indicators" | "categories" | "brands" | "products" | "pre-orders" | "auctions" | "banner" | "features" | "reviews" | "whatsapp-community" | "faq" | "blog-articles" | "newsletter" | "stores" | "events";
-export type SectionConfig = WelcomeSectionConfig | StatsSectionConfig | TrustIndicatorsSectionConfig | CategoriesSectionConfig | BrandsSectionConfig | ProductsSectionConfig | PreOrdersSectionConfig | AuctionsSectionConfig | BannerSectionConfig | FeaturesSectionConfig | ReviewsSectionConfig | WhatsAppCommunitySectionConfig | FAQSectionConfig | BlogArticlesSectionConfig | NewsletterSectionConfig | StoresSectionConfig | EventsSectionConfig;
+export interface CustomCardsCard {
+    id: string;
+    image?: string;
+    imageAlt?: string;
+    eyebrow?: string;
+    title?: string;
+    body?: string;
+    buttons?: Array<{
+        label: string;
+        href: string;
+        variant: "primary" | "secondary" | "outline" | "ghost";
+        target?: "_blank" | "_self";
+    }>;
+    formEmbed?: string;
+    backgroundColor?: string;
+    textColor?: string;
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "full";
+    shadowLevel?: "none" | "sm" | "md" | "lg";
+}
+export interface CustomCardsSectionConfig {
+    title?: string;
+    layout: "grid" | "row" | "masonry";
+    columns?: 1 | 2 | 3 | 4;
+    cards: CustomCardsCard[];
+    autoScroll?: boolean;
+    scrollIntervalMs?: number;
+}
+export interface GoogleReviewsSectionConfig {
+    placeId: string;
+    maxReviews?: number;
+    minRating?: number;
+    layout?: "grid" | "carousel";
+    showRating?: boolean;
+    showDate?: boolean;
+    linkToGoogleMaps?: boolean;
+    googleMapsUrl?: string;
+}
+export type SectionType = "welcome" | "carousel" | "stats" | "trust-indicators" | "categories" | "brands" | "products" | "pre-orders" | "auctions" | "banner" | "features" | "reviews" | "whatsapp-community" | "faq" | "blog-articles" | "newsletter" | "stores" | "events" | "social-feed" | "custom-cards" | "google-reviews";
+export type SectionConfig = CarouselSectionConfig | WelcomeSectionConfig | StatsSectionConfig | TrustIndicatorsSectionConfig | CategoriesSectionConfig | BrandsSectionConfig | ProductsSectionConfig | PreOrdersSectionConfig | AuctionsSectionConfig | BannerSectionConfig | FeaturesSectionConfig | ReviewsSectionConfig | WhatsAppCommunitySectionConfig | FAQSectionConfig | BlogArticlesSectionConfig | NewsletterSectionConfig | StoresSectionConfig | EventsSectionConfig | SocialFeedSectionConfig | CustomCardsSectionConfig | GoogleReviewsSectionConfig;
 export interface HomepageSectionDocument {
     id: string;
     type: SectionType;

package/dist/features/homepage/schemas/firestore.js

@@ -22,11 +22,13 @@ export const CAROUSEL_SLIDES_PUBLIC_FIELDS = [
     "title",
     "order",
     "active",
+    "background",
     "media",
     "link",
     "mobileMedia",
     "cards",
     "overlay",
+    "settings",
 ];
 export const carouselSlideQueryHelpers = {
     active: () => ["active", "==", true],
@@ -53,7 +55,8 @@ export const HOMEPAGE_SECTIONS_INDEXED_FIELDS = [
 ];
 export const DEFAULT_SECTION_ORDER = {
     welcome: 1,
-    stats: 2,
+    carousel: 2,
+    stats: 3,
     "trust-indicators": 3,
     categories: 2,
     brands: 2,
@@ -69,6 +72,9 @@ export const DEFAULT_SECTION_ORDER = {
     newsletter: 9,
     stores: 10,
     events: 11,
+    "social-feed": 12,
+    "custom-cards": 13,
+    "google-reviews": 14,
 };
 export const BANNER_HEIGHTS = {
     sm: "200px",

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

@@ -98,52 +98,77 @@ export interface BeforeAfterItem {
     caption: string;
     sortOrder: number;
 }
+export type CarouselSlideHeight = "viewport" | "tall" | "medium";
+export type CarouselHoverEffect = "scale" | "color" | "glow" | "none";
+/** Unified background for a slide or a card. */
+export interface CarouselBackground {
+    type: "image" | "video" | "color" | "gradient";
+    url?: string;
+    mobileUrl?: string;
+    thumbnail?: string;
+    color?: string;
+    gradientFrom?: string;
+    gradientTo?: string;
+    gradientAngle?: number;
+    dimOverlay?: {
+        enabled: boolean;
+        opacity: number;
+    };
+}
 export interface CarouselSlideCard {
     id: string;
-    gridRow: 1 | 2;
-    gridCol: 1 | 2 | 3;
-    background: {
-        type: "color" | "gradient" | "image" | "transparent";
-        value: string;
-    };
+    /** Zone 1–6: row 1 = zones 1–3, row 2 = zones 4–6. */
+    zone: 1 | 2 | 3 | 4 | 5 | 6;
+    mobileZone?: 2 | 5;
+    background: CarouselBackground;
     content?: {
+        eyebrow?: string;
         title?: string;
         subtitle?: string;
         description?: string;
+        textColor?: string;
+        textAlign?: "left" | "center" | "right";
     };
     buttons?: Array<{
-        id: string;
+        id?: string;
         text: string;
-        link: string;
-        variant: "primary" | "secondary" | "outline";
-        openInNewTab: boolean;
+        href: string;
+        variant: "primary" | "secondary" | "outline" | "ghost" | "link";
+        openInNewTab?: boolean;
     }>;
-    isButtonOnly: boolean;
-    sizing?: {
-        widthPct?: 25 | 50 | 75 | 100;
-        heightPct?: 25 | 50 | 75 | 100;
-        padding?: "none" | "sm" | "md" | "lg";
+    hover?: {
+        effect: CarouselHoverEffect;
+        scaleValue?: number;
+        colorValue?: string;
     };
+    isButtonOnly?: boolean;
+    /** @deprecated Use zone. */
+    gridRow?: 1 | 2;
+    /** @deprecated Use zone. */
+    gridCol?: 1 | 2 | 3;
 }
 export interface CarouselSlide {
     id: string;
     title: string;
     order: number;
     active: boolean;
-    media: {
+    background?: CarouselBackground;
+    /** @deprecated Use background. Kept for backward compat. */
+    media?: {
         type: "image" | "video";
         url: string;
-        alt: string;
+        alt?: string;
         thumbnail?: string;
     };
     link?: {
         url: string;
         openInNewTab: boolean;
     };
+    /** @deprecated Use background.mobileUrl. Kept for backward compat. */
     mobileMedia?: {
         type: "image" | "video";
         url: string;
-        alt: string;
+        alt?: string;
     };
     cards: CarouselSlideCard[];
     overlay?: {
@@ -151,13 +176,17 @@ export interface CarouselSlide {
         subtitle?: string;
         description?: string;
         button?: {
-            id: string;
+            id?: string;
             text: string;
             link: string;
             variant: "primary" | "secondary" | "outline";
             openInNewTab: boolean;
         };
     };
+    settings?: {
+        autoplayDelayMs?: number;
+        height?: CarouselSlideHeight;
+    };
     createdAt?: string;
     updatedAt?: string;
 }

package/dist/features/layout/AppLayoutShell.d.ts

@@ -12,6 +12,8 @@ export interface AppLayoutShellSidebarLink {
 export interface AppLayoutShellSidebarSection {
     title?: string;
     items: AppLayoutShellSidebarLink[];
+    /** When true, this section is expanded by default. */
+    defaultOpen?: boolean;
 }
 export interface AppLayoutShellSidebarAction {
     href: string;
@@ -32,6 +34,9 @@ export interface AppLayoutShellProps {
     logoHref: string;
     promotionsHref?: string;
     cartHref: string;
+    wishlistHref?: string;
+    /** Auth UID passed through to TitleBar for wishlist merge-on-login and sync. */
+    userId?: string | null;
     profileHref: string;
     loginHref: string;
     homeHref: string;
@@ -51,7 +56,9 @@ export interface AppLayoutShellProps {
     onLogout?: () => void;
     /** Href for the admin dashboard — shown in sidebar Dashboard section when user.role is admin. */
     adminHref?: string;
-    /** Href for the seller dashboard — shown in sidebar Dashboard section when user.role is admin or seller. */
+    /** Href for the store management dashboard — shown in sidebar Dashboard section when user.role is admin or seller. */
+    storeHref?: string;
+    /** @deprecated Use storeHref */
     sellerHref?: string;
     /** Href for the user orders page — auto-generates PROFILE section in sidebar. */
     userOrdersHref?: string;
@@ -72,6 +79,8 @@ export interface AppLayoutShellProps {
         settings?: string;
         dashboardSectionTitle?: string;
         adminDashboard?: string;
+        storeDashboard?: string;
+        /** @deprecated Use storeDashboard */
         sellerDashboard?: string;
         logout?: string;
     };
@@ -95,4 +104,4 @@ export interface AppLayoutShellProps {
         };
     };
 }
-export declare function AppLayoutShell({ children, navItems, sidebarItems, sidebarSections, sidebarPrimaryActions, sidebarTitle, hiddenNavItems, user, brandName, brandShortName, logoHref, promotionsHref, cartHref, profileHref, loginHref, homeHref, shopHref, footer, searchSlot, searchSlotRenderer, titleBarNavSlot, titleBarNotificationSlot, titleBarDevSlot, titleBarPromoStripText, showThemeToggle, suppressDashboardNav, hideSidebarToggle, onLogout, adminHref, sellerHref, userOrdersHref, userWishlistHref, userSettingsHref, sidebarLocaleSlot, showThemeToggleInSidebar, sidebarProfileLabels, eventBannerSlot, lightBackground, darkBackground, }: AppLayoutShellProps): import("react/jsx-runtime").JSX.Element;
+export declare function AppLayoutShell({ children, navItems, sidebarItems, sidebarSections, sidebarPrimaryActions, sidebarTitle, hiddenNavItems, user, brandName, brandShortName, logoHref, promotionsHref, cartHref, wishlistHref, userId, profileHref, loginHref, homeHref, shopHref, footer, searchSlot, searchSlotRenderer, titleBarNavSlot, titleBarNotificationSlot, titleBarDevSlot, titleBarPromoStripText, showThemeToggle, suppressDashboardNav, hideSidebarToggle, onLogout, adminHref, storeHref, sellerHref, userOrdersHref, userWishlistHref, userSettingsHref, sidebarLocaleSlot, showThemeToggleInSidebar, sidebarProfileLabels, eventBannerSlot, lightBackground, darkBackground, }: AppLayoutShellProps): import("react/jsx-runtime").JSX.Element;