feat: enhance carousel component to support overlay content and pagination functionality

web/app/components/base/carousel/index.tsx

@@ -14,6 +14,7 @@ type CarouselProps = {
   opts?: CarouselOptions
   plugins?: CarouselPlugin
   orientation?: 'horizontal' | 'vertical'
+  overlay?: React.ReactNode
 }
 
 type CarouselContextValue = {
@@ -49,7 +50,7 @@ type TCarousel = {
 >
 
 const Carousel: TCarousel = React.forwardRef(
-  ({ orientation = 'horizontal', opts, plugins, className, children, ...props }, ref) => {
+  ({ orientation = 'horizontal', opts, plugins, overlay, className, children, ...props }, ref) => {
     const [carouselRef, api] = useEmblaCarousel(
       { ...opts, axis: orientation === 'horizontal' ? 'x' : 'y' },
       plugins,
@@ -115,14 +116,19 @@ const Carousel: TCarousel = React.forwardRef(
         }}
       >
         <div
-          ref={carouselRef}
           // onKeyDownCapture={handleKeyDown}
-          className={cn('relative overflow-hidden', className)}
+          className={cn('relative', className)}
           role="region"
           aria-roledescription="carousel"
           {...props}
         >
-          {children}
+          {overlay}
+          <div
+            ref={carouselRef}
+            className="overflow-hidden [border-radius:inherit]"
+          >
+            {children}
+          </div>
         </div>
       </CarouselContext.Provider>
     )

web/app/components/plugins/marketplace/list/carousel.tsx

@@ -2,13 +2,13 @@
 
 import type { RemixiconComponentType } from '@remixicon/react'
 import { RiArrowLeftSLine, RiArrowRightSLine } from '@remixicon/react'
-import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import { useMemo } from 'react'
+import { Carousel as BaseCarousel, useCarousel } from '@/app/components/base/carousel'
 import { cn } from '@/utils/classnames'
 
 type CarouselProps = {
   children: React.ReactNode
   className?: string
-  itemWidth?: number
   gap?: number
   showNavigation?: boolean
   showPagination?: boolean
@@ -16,22 +16,6 @@ type CarouselProps = {
   autoPlayInterval?: number
 }
 
-type ScrollState = {
-  canScrollLeft: boolean
-  canScrollRight: boolean
-  currentPage: number
-  totalPages: number
-}
-
-const SCROLL_OVERLAP_RATIO = 0.5
-
-const defaultScrollState: ScrollState = {
-  canScrollLeft: false,
-  canScrollRight: false,
-  currentPage: 0,
-  totalPages: 0,
-}
-
 type NavButtonProps = {
   direction: 'left' | 'right'
   disabled: boolean
@@ -55,200 +39,89 @@ const NavButton = ({ direction, disabled, onClick, Icon }: NavButtonProps) => (
   </button>
 )
 
+type CarouselControlsProps = {
+  showPagination: boolean
+}
+
+const CarouselControls = ({ showPagination }: CarouselControlsProps) => {
+  const { api, selectedIndex, scrollPrev, scrollNext } = useCarousel()
+  const scrollSnaps = api?.scrollSnapList() ?? []
+  const totalPages = scrollSnaps.length
+
+  if (totalPages <= 1)
+    return null
+
+  return (
+    <div className="absolute -top-10 right-0 flex items-center gap-3">
+      {showPagination && (
+        <div className="flex items-center gap-1">
+          {scrollSnaps.map((snap, index) => (
+            <button
+              key={snap}
+              className={cn(
+                'h-[5px] w-[5px] rounded-full transition-all',
+                selectedIndex === index
+                  ? 'w-4 bg-components-button-primary-bg'
+                  : 'bg-components-button-secondary-border hover:bg-components-button-secondary-border-hover',
+              )}
+              onClick={() => api?.scrollTo(index)}
+              aria-label={`Go to page ${index + 1}`}
+            />
+          ))}
+        </div>
+      )}
+
+      <div className="flex items-center gap-1">
+        <NavButton
+          direction="left"
+          disabled={totalPages <= 1}
+          onClick={scrollPrev}
+          Icon={RiArrowLeftSLine}
+        />
+        <NavButton
+          direction="right"
+          disabled={totalPages <= 1}
+          onClick={scrollNext}
+          Icon={RiArrowRightSLine}
+        />
+      </div>
+    </div>
+  )
+}
+
 const Carousel = ({
   children,
   className,
-  itemWidth = 280,
   gap = 12,
   showNavigation = true,
   showPagination = true,
   autoPlay = false,
   autoPlayInterval = 5000,
 }: CarouselProps) => {
-  const containerRef = useRef<HTMLDivElement>(null)
+  const plugins = useMemo(() => {
-  const scrollStateRef = useRef<ScrollState>(defaultScrollState)
+    if (!autoPlay)
-  const [isHovered, setIsHovered] = useState(false)
+      return []
 
-  const calculateScrollState = useCallback((container: HTMLDivElement): ScrollState => {
+    return [
-    const { scrollLeft, scrollWidth, clientWidth } = container
+      BaseCarousel.Plugin.Autoplay({
-    const canScrollLeft = scrollLeft > 0
+        delay: autoPlayInterval,
-    const canScrollRight = scrollLeft < scrollWidth - clientWidth - 1
+        stopOnInteraction: false,
-
+        stopOnMouseEnter: true,
-    // Calculate total pages based on actual scroll range
+      }),
-    const maxScrollLeft = scrollWidth - clientWidth
+    ]
-    const itemsPerPage = Math.floor(clientWidth / (itemWidth + gap))
+  }, [autoPlay, autoPlayInterval])
-    const totalItems = container.children.length
-    const pages = Math.max(1, Math.ceil(totalItems / itemsPerPage))
-
-    // Calculate current page based on scroll position ratio
-    let currentPage = 0
-    if (maxScrollLeft > 0) {
-      const scrollRatio = scrollLeft / maxScrollLeft
-      currentPage = Math.round(scrollRatio * (pages - 1))
-    }
-
-    return {
-      canScrollLeft,
-      canScrollRight,
-      totalPages: pages,
-      currentPage: Math.min(Math.max(0, currentPage), pages - 1),
-    }
-  }, [itemWidth, gap])
-
-  const subscribe = useCallback((onStoreChange: () => void) => {
-    const container = containerRef.current
-    if (!container)
-      return () => { }
-
-    const handleChange = () => {
-      scrollStateRef.current = calculateScrollState(container)
-      onStoreChange()
-    }
-
-    // Initial calculation
-    handleChange()
-
-    const resizeObserver = new ResizeObserver(handleChange)
-    resizeObserver.observe(container)
-    container.addEventListener('scroll', handleChange)
-
-    return () => {
-      resizeObserver.disconnect()
-      container.removeEventListener('scroll', handleChange)
-    }
-  }, [calculateScrollState])
-
-  const getSnapshot = useCallback(() => scrollStateRef.current, [])
-
-  const scrollState = useSyncExternalStore(subscribe, getSnapshot, getSnapshot)
-
-  // Re-subscribe when children change
-  useEffect(() => {
-    const container = containerRef.current
-    if (container)
-      scrollStateRef.current = calculateScrollState(container)
-  }, [children, calculateScrollState])
-
-  const scrollToPage = useCallback((pageIndex: number, instant = false) => {
-    const container = containerRef.current
-    if (!container)
-      return
-
-    const itemsPerPage = Math.floor(container.clientWidth / (itemWidth + gap))
-    const scrollLeft = pageIndex * itemsPerPage * (itemWidth + gap)
-
-    container.scrollTo({
-      left: scrollLeft,
-      behavior: instant ? 'instant' : 'smooth',
-    })
-  }, [itemWidth, gap])
-
-  const scroll = useCallback((direction: 'left' | 'right') => {
-    const container = containerRef.current
-    if (!container)
-      return
-
-    // Handle looping
-    if (direction === 'left' && !scrollState.canScrollLeft) {
-      // At first page, loop to last page
-      scrollToPage(scrollState.totalPages - 1, true)
-      return
-    }
-    if (direction === 'right' && !scrollState.canScrollRight) {
-      // At last page, loop to first page
-      scrollToPage(0, true)
-      return
-    }
-
-    const scrollAmount = container.clientWidth - (itemWidth * SCROLL_OVERLAP_RATIO)
-    const newScrollLeft = direction === 'left'
-      ? container.scrollLeft - scrollAmount
-      : container.scrollLeft + scrollAmount
-
-    container.scrollTo({
-      left: newScrollLeft,
-      behavior: 'smooth',
-    })
-  }, [itemWidth, scrollState.canScrollLeft, scrollState.canScrollRight, scrollState.totalPages, scrollToPage])
-
-  // Auto-play functionality
-  useEffect(() => {
-    if (!autoPlay || isHovered || scrollState.totalPages <= 1)
-      return
-
-    const interval = setInterval(() => {
-      if (scrollState.canScrollRight) {
-        scrollToPage(scrollState.currentPage + 1)
-      }
-      else {
-        // Loop back to first page instantly (no animation)
-        scrollToPage(0, true)
-      }
-    }, autoPlayInterval)
-
-    return () => clearInterval(interval)
-  }, [autoPlay, autoPlayInterval, isHovered, scrollState.totalPages, scrollState.canScrollRight, scrollState.currentPage, scrollToPage])
-
-  const handleMouseEnter = useCallback(() => setIsHovered(true), [])
-  const handleMouseLeave = useCallback(() => setIsHovered(false), [])
 
   return (
-    <div
+    <BaseCarousel
-      className={cn('relative', className)}
+      opts={{ align: 'start', containScroll: 'trimSnaps', loop: true }}
-      onMouseEnter={handleMouseEnter}
+      plugins={plugins}
-      onMouseLeave={handleMouseLeave}
+      className={className}
+      overlay={showNavigation ? <CarouselControls showPagination={showPagination} /> : null}
     >
-      {/* Navigation arrows */}
+      <BaseCarousel.Content style={{ columnGap: `${gap}px` }}>
-      {showNavigation && (
-        <div className="absolute -top-10 right-0 flex items-center gap-3">
-          {/* Pagination dots */}
-          {showPagination && scrollState.totalPages > 1 && (
-            <div className="flex items-center gap-1">
-              {Array.from({ length: scrollState.totalPages }).map((_, index) => (
-                <button
-                  key={index}
-                  className={cn(
-                    'h-[5px] w-[5px] rounded-full transition-all',
-                    scrollState.currentPage === index
-                      ? 'w-4 bg-components-button-primary-bg'
-                      : 'bg-components-button-secondary-border hover:bg-components-button-secondary-border-hover',
-                  )}
-                  onClick={() => scrollToPage(index)}
-                  aria-label={`Go to page ${index + 1}`}
-                />
-              ))}
-            </div>
-          )}
-
-          <div className="flex items-center gap-1">
-            <NavButton
-              direction="left"
-              disabled={scrollState.totalPages <= 1}
-              onClick={() => scroll('left')}
-              Icon={RiArrowLeftSLine}
-            />
-            <NavButton
-              direction="right"
-              disabled={scrollState.totalPages <= 1}
-              onClick={() => scroll('right')}
-              Icon={RiArrowRightSLine}
-            />
-          </div>
-        </div>
-      )}
-
-      {/* Scrollable container */}
-      <div
-        ref={containerRef}
-        className="no-scrollbar flex gap-3 overflow-x-auto scroll-smooth"
-        style={{
-          scrollSnapType: 'x mandatory',
-          WebkitOverflowScrolling: 'touch',
-        }}
-      >
         {children}
-      </div>
+      </BaseCarousel.Content>
-    </div>
+    </BaseCarousel>
   )
 }
 

web/app/components/plugins/marketplace/list/collection-constants.ts

@@ -2,10 +2,22 @@ export const GRID_CLASS = 'grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3
 
 export const GRID_DISPLAY_LIMIT = 4
 
-export const CAROUSEL_COLUMN_CLASS = 'flex w-[calc((100%-0px)/1)] shrink-0 flex-col gap-3 sm:w-[calc((100%-12px)/2)] lg:w-[calc((100%-24px)/3)] xl:w-[calc((100%-36px)/4)]'
+export const CAROUSEL_PAGE_CLASS = 'w-full shrink-0'
 
-/** Max visible columns at the widest (xl) breakpoint; used to decide 1-row vs 2-row carousel layout. */
+export const CAROUSEL_PAGE_GRID_CLASS = 'grid grid-cols-1 gap-3 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4'
-export const CAROUSEL_MAX_VISIBLE_COLUMNS = 4
+
+export const CAROUSEL_PAGE_SIZE = {
+  base: 2,
+  sm: 4,
+  lg: 6,
+  xl: 8,
+} as const
+
+export const CAROUSEL_BREAKPOINTS = {
+  sm: 640,
+  lg: 1024,
+  xl: 1280,
+} as const
 
 /** Collection name key that triggers carousel display (plugins: partners, templates: featured) */
 export const CAROUSEL_COLLECTION_NAMES = {

web/app/components/plugins/marketplace/list/collection-list.tsx

@@ -6,13 +6,34 @@ import type { BaseCollection } from './collection-constants'
 import type { Locale } from '@/i18n-config/language'
 import { useLocale, useTranslation } from '#i18n'
 import { RiArrowRightSLine } from '@remixicon/react'
+import { useEffect, useMemo, useState } from 'react'
 import { getLanguage } from '@/i18n-config/language'
 import { cn } from '@/utils/classnames'
 import { useMarketplaceMoreClick } from '../atoms'
 import Empty from '../empty'
-import { buildCarouselColumns, getItemKeyByField } from '../utils'
+import { buildCarouselPages, getItemKeyByField } from '../utils'
 import Carousel from './carousel'
-import { CAROUSEL_COLUMN_CLASS, CAROUSEL_MAX_VISIBLE_COLUMNS, GRID_CLASS, GRID_DISPLAY_LIMIT } from './collection-constants'
+import {
+  CAROUSEL_BREAKPOINTS,
+  CAROUSEL_PAGE_CLASS,
+  CAROUSEL_PAGE_GRID_CLASS,
+  CAROUSEL_PAGE_SIZE,
+  GRID_CLASS,
+  GRID_DISPLAY_LIMIT,
+} from './collection-constants'
+
+const getViewportWidth = () => typeof window === 'undefined' ? CAROUSEL_BREAKPOINTS.xl : window.innerWidth
+
+const getCarouselItemsPerPage = (viewportWidth: number) => {
+  if (viewportWidth >= CAROUSEL_BREAKPOINTS.xl)
+    return CAROUSEL_PAGE_SIZE.xl
+  if (viewportWidth >= CAROUSEL_BREAKPOINTS.lg)
+    return CAROUSEL_PAGE_SIZE.lg
+  if (viewportWidth >= CAROUSEL_BREAKPOINTS.sm)
+    return CAROUSEL_PAGE_SIZE.sm
+
+  return CAROUSEL_PAGE_SIZE.base
+}
 
 type ViewMoreButtonProps = {
   searchParams?: SearchParamsFromCollection
@@ -81,25 +102,38 @@ export function CarouselCollection<TItem>({
   renderCard,
   cardContainerClassName,
 }: CarouselCollectionProps<TItem>) {
-  const columns = buildCarouselColumns(items, CAROUSEL_MAX_VISIBLE_COLUMNS)
+  const [viewportWidth, setViewportWidth] = useState(getViewportWidth)
+
+  useEffect(() => {
+    const handleResize = () => setViewportWidth(window.innerWidth)
+
+    window.addEventListener('resize', handleResize)
+
+    return () => window.removeEventListener('resize', handleResize)
+  }, [])
+
+  const itemsPerPage = useMemo(() => getCarouselItemsPerPage(viewportWidth), [viewportWidth])
+  const pages = useMemo(() => buildCarouselPages(items, itemsPerPage), [items, itemsPerPage])
+  const hasMultiplePages = pages.length > 1
 
   return (
     <Carousel
-      className={cardContainerClassName}
+      showNavigation={hasMultiplePages}
-      showNavigation={items.length > 8}
+      showPagination={hasMultiplePages}
-      showPagination={items.length > 8}
+      autoPlay={hasMultiplePages}
-      autoPlay={items.length > 8}
       autoPlayInterval={5000}
     >
-      {columns.map((columnItems, idx) => (
+      {pages.map((pageItems, idx) => (
         <div
-          key={columnItems[0] ? getItemKey(columnItems[0]) : idx}
+          key={pageItems[0] ? getItemKey(pageItems[0]) : idx}
-          className={CAROUSEL_COLUMN_CLASS}
+          className={CAROUSEL_PAGE_CLASS}
           style={{ scrollSnapAlign: 'start' }}
         >
-          {columnItems.map(item => (
+          <div className={cn(CAROUSEL_PAGE_GRID_CLASS, cardContainerClassName)}>
-            <div key={getItemKey(item)}>{renderCard(item)}</div>
+            {pageItems.map(item => (
-          ))}
+              <div key={getItemKey(item)}>{renderCard(item)}</div>
+            ))}
+          </div>
         </div>
       ))}
     </Carousel>

web/app/components/plugins/marketplace/utils.ts

@@ -32,24 +32,12 @@ export function getItemKeyByField<T>(item: T, field: keyof T): string {
   return String((item as Record<string, unknown>)[field as string])
 }
 
-/**
+/** Group a flat array into pages for a carousel layout. */
- * Group a flat array into columns for a carousel grid layout.
+export function buildCarouselPages<T>(items: T[], itemsPerPage: number): T[][] {
- * When the item count exceeds `maxVisibleColumns`, items are arranged in
+  const pages: T[][] = []
- * a two-row, column-first order with the first row always fully filled.
+  for (let i = 0; i < items.length; i += itemsPerPage)
- */
+    pages.push(items.slice(i, i + itemsPerPage))
-export function buildCarouselColumns<T>(items: T[], maxVisibleColumns: number): T[][] {
+  return pages
-  const useDoubleRow = items.length > maxVisibleColumns
-  const numColumns = useDoubleRow
-    ? Math.max(maxVisibleColumns, Math.ceil(items.length / 2))
-    : items.length
-  const columns: T[][] = []
-  for (let i = 0; i < numColumns; i++) {
-    const column: T[] = [items[i]]
-    if (useDoubleRow && i + numColumns < items.length)
-      column.push(items[i + numColumns])
-    columns.push(column)
-  }
-  return columns
 }
 
 export const getPluginIconInMarketplace = (plugin: Plugin) => {