@thorprovider/blocks 1.0.0 → 2.0.0

package/src/blocks/e-commerce/category-filters/category-listing.tsx

@@ -0,0 +1,934 @@
+'use client'
+
+import { useEffect, useId, useState, type ReactNode } from 'react'
+import { Search, SlidersHorizontal, X } from 'lucide-react'
+
+import { Badge } from '../../../ui/badge'
+import { Button } from '../../../ui/button'
+import { Drawer, DrawerContent, DrawerHeader, DrawerTitle } from '../../../ui/drawer'
+import { Empty, EmptyContent, EmptyDescription, EmptyHeader, EmptyTitle } from '../../../ui/empty'
+import { Input } from '../../../ui/input'
+import { Label } from '../../../ui/label'
+import {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+} from '../../../ui/pagination'
+import { RadioGroup, RadioGroupItem } from '../../../ui/radio-group'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../../../ui/select'
+import { Sheet, SheetContent, SheetHeader, SheetTitle, SheetTrigger } from '../../../ui/sheet'
+import { Skeleton } from '../../../ui/skeleton'
+import { cn } from '../../../lib/utils'
+import type { ProductPresentation } from '../../../lib/contracts'
+
+import { ProductCard } from '../product-list/product-card'
+
+import { CategoryListingFilterFields } from './category-listing-filter-fields'
+
+/** The bounded presentation surface. The data contract and callbacks are identical. */
+export type CategoryListingPresentation = 'sidebar' | 'toolbar'
+
+export interface CategoryListingOption {
+  id: string
+  label: string
+}
+
+export interface CategoryListingPriceRange {
+  min: number
+  max: number
+  step: number
+}
+
+export interface CategoryListingSortOption {
+  value: string
+  label: string
+}
+
+/**
+ * A provider-backed facet value. `count` is rendered only when it is a real
+ * non-negative number — a true zero is preserved, never recomputed or summed.
+ */
+export interface CategoryListingFacetOption {
+  value: string
+  label: string
+  count?: number
+}
+
+/**
+ * A generic facet group. The block never derives sector-specific fields
+ * (frame size, colourway, range…) and never invents groups or options.
+ */
+export interface CategoryListingFacetGroup {
+  id: string
+  label: string
+  options: CategoryListingFacetOption[]
+}
+
+/** The absolute canonical filter set emitted upward. */
+export interface CategoryListingFilters {
+  categories: string[]
+  collections: string[]
+  priceRange?: [number, number]
+  facets?: Record<string, string[]>
+}
+
+/**
+ * A typed catalog-query error the listing renders for repair. It mirrors the
+ * runtime boundary error: `fields` names the exact raw parameters to remove and
+ * `feature` is present only for `unmounted-capability`. The block never builds a
+ * host URL — it emits the fields through `onRepair`.
+ */
+export interface CategoryListingQueryError {
+  code: 'invalid-query' | 'unsupported-query' | 'unmounted-capability'
+  /** Exact raw URL parameter names that must be removed to repair the query. */
+  fields: string[]
+  message?: string
+  feature?: 'catalog-search' | 'category-filters'
+}
+
+/**
+ * The observable listing status. The host derives it from the URL boundary and
+ * the provider outcome; the block only renders it. Distinct states stay
+ * distinct — a valid empty result is never shown as an error and a raw failure
+ * is never swallowed as empty.
+ */
+export type CategoryListingStatus =
+  | { state: 'loading' }
+  | { state: 'ready' }
+  | { state: 'empty' }
+  | { state: 'invalid-query'; error: CategoryListingQueryError }
+  | { state: 'unsupported-query'; error: CategoryListingQueryError }
+  | { state: 'unmounted-capability'; error: CategoryListingQueryError }
+  | { state: 'error'; message?: string }
+
+/** The kind of canonical filter an active chip represents. */
+export type CategoryListingActiveFilterKind =
+  | 'text'
+  | 'category'
+  | 'collection'
+  | 'price'
+  | 'attribute'
+
+/**
+ * A removable active-filter chip. Built only from the actual canonical query:
+ * `params` are the raw URL parameter names carrying the filter and `value` is
+ * the specific list value to drop.
+ */
+export interface CategoryListingActiveFilter {
+  /** Stable identity for React keys and removal callbacks. */
+  id: string
+  kind: CategoryListingActiveFilterKind
+  /** Human-readable label shown on the chip. */
+  label: string
+  /** Raw URL parameter names that carry this filter. */
+  params: string[]
+  /** The specific list value this chip removes; absent for scalar filters. */
+  value?: string
+}
+
+export interface CategoryListingProps {
+  /** Bounded presentation option; defaults to `sidebar`. */
+  presentation?: CategoryListingPresentation
+
+  /** Exactly the provider-paged products for the current page. Never re-paginated. */
+  products: ProductPresentation[]
+  pagination: (number | string)[]
+
+  // ── Controlled canonical-query values ─────────────────────────────────────
+  // The listing owns no private query state: these values are authoritative and
+  // every interaction reports the absolute next value through a callback.
+  searchValue: string
+  selectedCategories: string[]
+  selectedCollections: string[]
+  selectedSort: string
+  selectedPage: number
+  selectedPageSize: number
+  selectedPriceRange?: [number, number]
+  selectedFacets?: Record<string, string[]>
+
+  // ── Provider-declared option sets ─────────────────────────────────────────
+  categories?: CategoryListingOption[]
+  collections?: CategoryListingOption[]
+  sortOptions?: CategoryListingSortOption[]
+  /**
+   * Real backend-provided price range only. When absent the price control is
+   * omitted; the block never falls back to a fabricated `0..1000` default.
+   */
+  priceRange?: CategoryListingPriceRange
+  /** Generic provider-backed facet groups; a group renders only when non-empty. */
+  facets?: CategoryListingFacetGroup[]
+  viewOptions?: number[]
+
+  // ── Per-control visibility (selected from installed features) ─────────────
+  showSearch: boolean
+  showFilters: boolean
+  showSort: boolean
+  /** Price remains gated on a real `priceRange` even when this is true. */
+  showPrice?: boolean
+
+  // ── Observable listing states + active-filter chips ───────────────────────
+  status: CategoryListingStatus
+  activeFilters: CategoryListingActiveFilter[]
+
+  // ── Copy ──────────────────────────────────────────────────────────────────
+  filtersTitle?: string
+  applyFiltersLabel?: string
+  selectedText?: string
+  clearAllLabel?: string
+  priceRangeTitle?: string
+  minLabel?: string
+  maxLabel?: string
+  categoriesTitle?: string
+  collectionsTitle?: string
+  sortTitle?: string
+  viewLabel?: string
+  viewPlaceholder?: string
+  sortPlaceholder?: string
+  productsTitle?: string
+  currentLabel?: string
+  searchLabel?: string
+  searchPlaceholder?: string
+  loadingLabel?: string
+  emptyTitle?: string
+  emptyDescription?: string
+  clearFiltersLabel?: string
+  invalidQueryTitle?: string
+  unsupportedQueryTitle?: string
+  unmountedCapabilityTitle?: string
+  errorTitle?: string
+  errorDescription?: string
+  repairLabel?: string
+  retryLabel?: string
+  activeFiltersTitle?: string
+  removeFilterLabel?: string
+
+  // ── Emit-only callbacks: the block never fetches or rewrites the URL ─────
+  onProductClick?: (product: ProductPresentation) => void
+  onPageChange?: (page: number) => void
+  onPageSizeChange?: (pageSize: number) => void
+  onSortChange?: (sort: string) => void
+  onFilterChange?: (next: CategoryListingFilters) => void
+  onSearchChange?: (value: string) => void
+  /** Empty-state clear: drops the active filters but never base scope/sort/pageSize. */
+  onClearFilters?: () => void
+  /** Invalid/unsupported/unmounted repair: receives the exact bad fields to remove. */
+  onRepair?: (remove: string[]) => void
+  /** Query/network failure retry: preserves the current query/input. */
+  onRetry?: () => void
+  /** Removes a single active-filter chip. */
+  onRemoveFilter?: (filter: CategoryListingActiveFilter) => void
+}
+
+const DEFAULT_VIEW_OPTIONS = [10, 25, 50, 100]
+
+/**
+ * Pure selection reducer shared by checkbox handlers. Exported so the emitted
+ * contract is unit-testable without a DOM (this package's tests render with
+ * `react-dom/server`).
+ */
+export function toggleFilterValue(
+  current: readonly string[],
+  value: string,
+  checked: boolean,
+): string[] {
+  return checked ? [...current, value] : current.filter(candidate => candidate !== value)
+}
+
+/** Assemble the typed absolute filter change emitted upward. */
+export function buildFilterChange(input: {
+  categories: string[]
+  collections: string[]
+  priceRange?: [number, number]
+  facets?: Record<string, string[]>
+}): CategoryListingFilters {
+  const change: CategoryListingFilters = {
+    categories: input.categories,
+    collections: input.collections,
+  }
+  if (input.priceRange) change.priceRange = input.priceRange
+  if (input.facets) change.facets = input.facets
+  return change
+}
+
+/**
+ * Reconcile the controlled search draft with the URL-backed `searchValue`.
+ *
+ * The URL is authoritative, but it only updates after an async server
+ * navigation. Binding the input directly to that lagging prop makes React reset
+ * it to the previous server value on every re-render, so fast typing loses every
+ * character but the last. This pure function keeps a local draft authoritative
+ * while the shopper is typing and adopts an external `searchValue`
+ * (navigation / reload / back-forward) only when no uncommitted edit is pending.
+ */
+export function reconcileSearchDraft(input: {
+  searchValue?: string
+  prevSearchValue?: string
+  draft: string
+}): { draft: string; prevSearchValue?: string } | null {
+  const { searchValue, prevSearchValue, draft } = input
+  if (searchValue === undefined || searchValue === prevSearchValue) return null
+  const clean = prevSearchValue === undefined || draft === prevSearchValue
+  return { draft: clean ? searchValue : draft, prevSearchValue: searchValue }
+}
+
+export interface CategoryListingStatusViewProps {
+  status: CategoryListingStatus
+  activeFilters?: CategoryListingActiveFilter[]
+  activeFiltersTitle?: string
+  removeFilterLabel?: string
+  loadingLabel?: string
+  emptyTitle?: string
+  emptyDescription?: string
+  clearFiltersLabel?: string
+  invalidQueryTitle?: string
+  unsupportedQueryTitle?: string
+  unmountedCapabilityTitle?: string
+  errorTitle?: string
+  errorDescription?: string
+  repairLabel?: string
+  retryLabel?: string
+  onClearFilters?: () => void
+  onRepair?: (remove: string[]) => void
+  onRetry?: () => void
+  onRemoveFilter?: (filter: CategoryListingActiveFilter) => void
+}
+
+/** Human-readable description naming the exact offending parameters. */
+function describeQueryError(
+  error: CategoryListingQueryError,
+  state: 'invalid-query' | 'unsupported-query' | 'unmounted-capability',
+): string {
+  const fields = error.fields.join(', ')
+  if (state === 'unmounted-capability' && error.feature) {
+    return `${fields} pertenece a la función «${error.feature}», que no está instalada.`
+  }
+  return error.message ?? `Parámetros: ${fields}`
+}
+
+/**
+ * Hooks-free presentation of the observable listing states and the removable
+ * active-filter chips. Kept separate from `CategoryListing` so the interaction
+ * contract (clear / repair / retry / chip removal) is testable by invoking the
+ * rendered handlers without a DOM. It renders no products and performs no fetch.
+ */
+export function CategoryListingStatusView({
+  status,
+  activeFilters = [],
+  activeFiltersTitle = 'Filtros activos',
+  removeFilterLabel = 'Quitar filtro',
+  loadingLabel = 'Cargando productos',
+  emptyTitle = 'Sin resultados',
+  emptyDescription = 'Ningún producto coincide con los filtros activos.',
+  clearFiltersLabel = 'Limpiar filtros',
+  invalidQueryTitle = 'Consulta no válida',
+  unsupportedQueryTitle = 'Filtro no disponible',
+  unmountedCapabilityTitle = 'Función no disponible',
+  errorTitle = 'No se pudieron cargar los productos',
+  errorDescription = 'Inténtalo de nuevo.',
+  repairLabel = 'Corregir búsqueda',
+  retryLabel = 'Reintentar',
+  onClearFilters,
+  onRepair,
+  onRetry,
+  onRemoveFilter,
+}: CategoryListingStatusViewProps) {
+  const chips =
+    activeFilters.length > 0 ? (
+      <div role='group' aria-label={activeFiltersTitle} className='flex flex-wrap items-center gap-2'>
+        {activeFilters.map(filter => (
+          <Badge key={filter.id} variant='secondary' className='gap-1 pr-1'>
+            <span>{filter.label}</span>
+            <Button
+              type='button'
+              variant='ghost'
+              size='icon-xs'
+              className='size-4 cursor-pointer rounded-full'
+              aria-label={`${removeFilterLabel}: ${filter.label}`}
+              data-action='remove-filter'
+              data-filter-id={filter.id}
+              onClick={() => onRemoveFilter?.(filter)}
+            >
+              <X aria-hidden='true' />
+            </Button>
+          </Badge>
+        ))}
+      </div>
+    ) : null
+
+  if (status.state === 'ready') return chips
+
+  let body: ReactNode
+  switch (status.state) {
+    case 'loading':
+      body = (
+        <div role='status' aria-live='polite' aria-busy='true' className='flex flex-col gap-4'>
+          <span className='sr-only'>{loadingLabel}</span>
+          <div className='grid grid-cols-1 gap-4 sm:grid-cols-2 sm:gap-6 lg:grid-cols-3'>
+            {Array.from({ length: 6 }, (_, index) => (
+              <div key={index} className='flex flex-col gap-2'>
+                <Skeleton className='aspect-3/4 w-full rounded-lg' />
+                <Skeleton className='h-4 w-3/4' />
+                <Skeleton className='h-4 w-1/3' />
+              </div>
+            ))}
+          </div>
+        </div>
+      )
+      break
+    case 'empty':
+      body = (
+        <Empty role='status'>
+          <EmptyHeader>
+            <EmptyTitle>{emptyTitle}</EmptyTitle>
+            <EmptyDescription>{emptyDescription}</EmptyDescription>
+          </EmptyHeader>
+          {onClearFilters ? (
+            <EmptyContent>
+              <Button type='button' variant='outline' data-action='clear-filters' onClick={() => onClearFilters()}>
+                {clearFiltersLabel}
+              </Button>
+            </EmptyContent>
+          ) : null}
+        </Empty>
+      )
+      break
+    case 'invalid-query':
+    case 'unsupported-query':
+    case 'unmounted-capability':
+      body = (
+        <Empty role='alert'>
+          <EmptyHeader>
+            <EmptyTitle>
+              {status.state === 'invalid-query'
+                ? invalidQueryTitle
+                : status.state === 'unsupported-query'
+                  ? unsupportedQueryTitle
+                  : unmountedCapabilityTitle}
+            </EmptyTitle>
+            <EmptyDescription>{describeQueryError(status.error, status.state)}</EmptyDescription>
+          </EmptyHeader>
+          {onRepair ? (
+            <EmptyContent>
+              <Button
+                type='button'
+                variant='outline'
+                data-action='repair'
+                onClick={() => onRepair(status.error.fields)}
+              >
+                {repairLabel}
+              </Button>
+            </EmptyContent>
+          ) : null}
+        </Empty>
+      )
+      break
+    case 'error':
+      body = (
+        <Empty role='alert'>
+          <EmptyHeader>
+            <EmptyTitle>{errorTitle}</EmptyTitle>
+            <EmptyDescription>{status.message ?? errorDescription}</EmptyDescription>
+          </EmptyHeader>
+          {onRetry ? (
+            <EmptyContent>
+              <Button type='button' variant='default' data-action='retry' onClick={() => onRetry()}>
+                {retryLabel}
+              </Button>
+            </EmptyContent>
+          ) : null}
+        </Empty>
+      )
+      break
+  }
+
+  return (
+    <div className='flex flex-col gap-4'>
+      {chips}
+      {body}
+    </div>
+  )
+}
+
+export function CategoryListing({
+  presentation = 'sidebar',
+  products,
+  pagination,
+  searchValue,
+  selectedCategories,
+  selectedCollections,
+  selectedSort,
+  selectedPage,
+  selectedPageSize,
+  selectedPriceRange,
+  selectedFacets = {},
+  categories = [],
+  collections = [],
+  sortOptions = [],
+  priceRange: priceRangeConfig,
+  facets = [],
+  viewOptions = DEFAULT_VIEW_OPTIONS,
+  showSearch,
+  showFilters,
+  showSort,
+  showPrice = true,
+  status,
+  activeFilters,
+  filtersTitle = 'Filtros',
+  applyFiltersLabel = 'Aplicar filtros',
+  selectedText = 'Filtros',
+  clearAllLabel = 'Restablecer',
+  priceRangeTitle = 'Rango de precio',
+  minLabel = 'Mínimo',
+  maxLabel = 'Máximo',
+  categoriesTitle = 'Categoría',
+  collectionsTitle = 'Colección',
+  sortTitle = 'Ordenar por',
+  viewLabel = 'Ver',
+  viewPlaceholder = 'Seleccionar',
+  sortPlaceholder = 'Ordenar por',
+  productsTitle = 'Productos',
+  currentLabel = '(actual)',
+  searchLabel = 'Buscar',
+  searchPlaceholder = 'Buscar',
+  loadingLabel,
+  emptyTitle,
+  emptyDescription,
+  clearFiltersLabel,
+  invalidQueryTitle,
+  unsupportedQueryTitle,
+  unmountedCapabilityTitle,
+  errorTitle,
+  errorDescription,
+  repairLabel,
+  retryLabel,
+  activeFiltersTitle,
+  removeFilterLabel,
+  onProductClick,
+  onPageChange,
+  onPageSizeChange,
+  onSortChange,
+  onFilterChange,
+  onSearchChange,
+  onClearFilters,
+  onRepair,
+  onRetry,
+  onRemoveFilter,
+}: CategoryListingProps) {
+  const searchInputId = useId()
+  const [draftSearch, setDraftSearch] = useState(searchValue)
+  const [prevSearchValue, setPrevSearchValue] = useState<string | undefined>(searchValue)
+  const [isSheetOpen, setIsSheetOpen] = useState(false)
+  const [isFilterDrawerOpen, setIsFilterDrawerOpen] = useState(false)
+  const [isSortDrawerOpen, setIsSortDrawerOpen] = useState(false)
+
+  const reconciledSearch = reconcileSearchDraft({ searchValue, prevSearchValue, draft: draftSearch })
+  if (reconciledSearch) {
+    setPrevSearchValue(reconciledSearch.prevSearchValue)
+    if (reconciledSearch.draft !== draftSearch) setDraftSearch(reconciledSearch.draft)
+  }
+
+  // The desktop surface owns the filters; close every mobile overlay when the
+  // viewport crosses into the desktop layout.
+  useEffect(() => {
+    const mediaQuery = window.matchMedia('(min-width: 1024px)')
+    const handleChange = (event: MediaQueryListEvent) => {
+      if (event.matches) {
+        setIsSheetOpen(false)
+        setIsFilterDrawerOpen(false)
+        setIsSortDrawerOpen(false)
+      }
+    }
+    mediaQuery.addEventListener('change', handleChange)
+    return () => mediaQuery.removeEventListener('change', handleChange)
+  }, [])
+
+  const priceRangeValue: [number, number] = priceRangeConfig
+    ? (selectedPriceRange ?? [priceRangeConfig.min, priceRangeConfig.max])
+    : [0, 0]
+
+  const emitFilters = (overrides: Partial<CategoryListingFilters> = {}) => {
+    onFilterChange?.(
+      buildFilterChange({
+        categories: selectedCategories,
+        collections: selectedCollections,
+        ...(priceRangeConfig ? { priceRange: priceRangeValue } : {}),
+        facets: selectedFacets,
+        ...overrides,
+      }),
+    )
+  }
+
+  const handleCategoryChange = (category: string, checked: boolean) => {
+    emitFilters({ categories: toggleFilterValue(selectedCategories, category, checked) })
+  }
+
+  const handleCollectionChange = (collection: string, checked: boolean) => {
+    emitFilters({ collections: toggleFilterValue(selectedCollections, collection, checked) })
+  }
+
+  const handleFacetChange = (group: CategoryListingFacetGroup, value: string, checked: boolean) => {
+    const current = selectedFacets[group.id] ?? []
+    const nextValues = toggleFilterValue(current, value, checked)
+    const nextFacets: Record<string, string[]> = { ...selectedFacets }
+    if (nextValues.length > 0) nextFacets[group.id] = nextValues
+    else delete nextFacets[group.id]
+    emitFilters({ facets: nextFacets })
+  }
+
+  const handlePriceChange = (next: [number, number]) => {
+    emitFilters({ priceRange: next })
+  }
+
+  const handleClearAll = () => {
+    emitFilters({
+      categories: [],
+      collections: [],
+      ...(priceRangeConfig ? { priceRange: [priceRangeConfig.min, priceRangeConfig.max] as [number, number] } : {}),
+      facets: {},
+    })
+  }
+
+  const handlePageSizeChange = (size: number) => {
+    if (Number.isFinite(size)) onPageSizeChange?.(size)
+  }
+
+  const handlePageChange = (page: number | string) => {
+    if (page === '...') return
+    const numeric = Number(page)
+    if (Number.isFinite(numeric)) onPageChange?.(numeric)
+  }
+
+  const handleSortChange = (sort: string) => {
+    onSortChange?.(sort)
+  }
+
+  const handleSearchChange = (text: string) => {
+    setDraftSearch(text)
+    onSearchChange?.(text)
+  }
+
+  const fields = (
+    <CategoryListingFilterFields
+      selectedText={selectedText}
+      clearAllLabel={clearAllLabel}
+      priceRangeTitle={priceRangeTitle}
+      priceRange={priceRangeValue}
+      priceRangeConfig={showPrice ? priceRangeConfig : undefined}
+      minLabel={minLabel}
+      maxLabel={maxLabel}
+      onPriceChange={handlePriceChange}
+      categoriesTitle={categoriesTitle}
+      categories={categories}
+      selectedCategories={selectedCategories}
+      onCategoryChange={handleCategoryChange}
+      collectionsTitle={collectionsTitle}
+      collections={collections}
+      selectedCollections={selectedCollections}
+      onCollectionChange={handleCollectionChange}
+      facets={facets}
+      selectedFacets={selectedFacets}
+      onFacetChange={handleFacetChange}
+      onClearAll={handleClearAll}
+    />
+  )
+
+  const sortControl = (ariaLabel: string) =>
+    showSort && sortOptions.length > 0 ? (
+      <Select value={selectedSort} onValueChange={handleSortChange}>
+        <SelectTrigger className='h-8 w-[180px]' aria-label={ariaLabel}>
+          <SelectValue placeholder={sortPlaceholder} />
+        </SelectTrigger>
+        <SelectContent>
+          {sortOptions.map(option => (
+            <SelectItem key={option.value} value={option.value}>
+              {option.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    ) : null
+
+  const searchControl = showSearch ? (
+    <div className='relative w-full sm:w-64'>
+      <label htmlFor={searchInputId} className='sr-only'>
+        {searchLabel}
+      </label>
+      <Search
+        aria-hidden='true'
+        className='text-muted-foreground pointer-events-none absolute top-1/2 left-2.5 size-4 -translate-y-1/2'
+      />
+      <Input
+        id={searchInputId}
+        type='search'
+        value={draftSearch}
+        onChange={event => handleSearchChange(event.target.value)}
+        placeholder={searchPlaceholder}
+        aria-label={searchLabel}
+        className='h-8 pl-8'
+      />
+    </div>
+  ) : null
+
+  const pageSizeControl =
+    viewOptions.length > 0 ? (
+      <div className='hidden items-center gap-2 sm:flex'>
+        <span className='text-sm'>{viewLabel}</span>
+        <Select
+          value={String(selectedPageSize)}
+          onValueChange={value => {
+            const option = viewOptions.find(candidate => String(candidate) === value)
+            handlePageSizeChange(option ?? Number(value))
+          }}
+        >
+          <SelectTrigger className='h-8 w-[100px]' aria-label={viewLabel}>
+            <SelectValue placeholder={viewPlaceholder} />
+          </SelectTrigger>
+          <SelectContent>
+            {viewOptions.map(option => (
+              <SelectItem key={option} value={String(option)}>
+                {option}
+              </SelectItem>
+            ))}
+          </SelectContent>
+        </Select>
+      </div>
+    ) : null
+
+  const statusView = (
+    <CategoryListingStatusView
+      status={status}
+      activeFilters={activeFilters}
+      loadingLabel={loadingLabel}
+      emptyTitle={emptyTitle}
+      emptyDescription={emptyDescription}
+      clearFiltersLabel={clearFiltersLabel}
+      invalidQueryTitle={invalidQueryTitle}
+      unsupportedQueryTitle={unsupportedQueryTitle}
+      unmountedCapabilityTitle={unmountedCapabilityTitle}
+      errorTitle={errorTitle}
+      errorDescription={errorDescription}
+      repairLabel={repairLabel}
+      retryLabel={retryLabel}
+      activeFiltersTitle={activeFiltersTitle}
+      removeFilterLabel={removeFilterLabel}
+      onClearFilters={onClearFilters}
+      onRepair={onRepair}
+      onRetry={onRetry}
+      onRemoveFilter={onRemoveFilter}
+    />
+  )
+
+  const results =
+    status.state === 'ready' ? (
+      <section aria-labelledby='products-heading' className='flex flex-col gap-6'>
+        <h2 id='products-heading' className='sr-only'>
+          {productsTitle}
+        </h2>
+        <ul
+          data-slot='category-listing-products'
+          className={cn(
+            'grid grid-cols-1 gap-4 sm:grid-cols-2 sm:gap-6',
+            presentation === 'sidebar' ? 'lg:grid-cols-3' : 'lg:grid-cols-4',
+          )}
+        >
+          {products.map(product => (
+            <li key={product.id}>
+              <ProductCard
+                item={product}
+                presentation='minimal'
+                hideAddToCart
+                onProductClick={onProductClick}
+              />
+            </li>
+          ))}
+        </ul>
+
+        {pagination.length > 0 ? (
+          <Pagination aria-label='Paginación'>
+            <PaginationContent>
+              {pagination.map((page, index) =>
+                page === '...' ? (
+                  <PaginationEllipsis key={`${page}-${index}`} />
+                ) : (
+                  <PaginationItem key={page}>
+                    <Button
+                      type='button'
+                      variant={selectedPage === page ? 'outline' : 'ghost'}
+                      size='icon'
+                      data-slot='pagination-link'
+                      data-active={selectedPage === page}
+                      aria-current={selectedPage === page ? 'page' : undefined}
+                      className='size-8 cursor-pointer p-0'
+                      onClick={() => handlePageChange(page)}
+                    >
+                      {page}
+                      {selectedPage === page && <span className='sr-only'>{currentLabel}</span>}
+                    </Button>
+                  </PaginationItem>
+                ),
+              )}
+            </PaginationContent>
+          </Pagination>
+        ) : null}
+      </section>
+    ) : null
+
+  return (
+    <div className='mx-auto w-full max-w-7xl px-4 py-8 sm:px-6 lg:px-8'>
+      <div className={cn('flex flex-col gap-8', presentation === 'sidebar' && 'lg:flex-row')}>
+        {presentation === 'sidebar' && showFilters ? (
+          <aside className='hidden w-full flex-none lg:block lg:w-72'>
+            <div className='max-h-100vh sticky top-4 overflow-y-auto'>
+              <div className='flex flex-col gap-6 pb-6'>{fields}</div>
+            </div>
+          </aside>
+        ) : null}
+
+        <main className='flex min-w-0 flex-1 flex-col gap-6'>
+          {presentation === 'toolbar' ? (
+            <>
+              <div className='bg-background/95 supports-[backdrop-filter]:bg-background/80 sticky top-0 z-10 -mx-4 flex items-center gap-2 border-b px-4 py-2 backdrop-blur lg:hidden'>
+                {showFilters ? (
+                  <Button
+                    type='button'
+                    variant='outline'
+                    size='sm'
+                    className='h-9 flex-1 cursor-pointer justify-start'
+                    onClick={() => setIsFilterDrawerOpen(true)}
+                  >
+                    <SlidersHorizontal aria-hidden='true' />
+                    {filtersTitle}
+                    {activeFilters.length > 0 ? (
+                      <Badge variant='secondary' className='ms-auto'>
+                        {activeFilters.length}
+                      </Badge>
+                    ) : null}
+                  </Button>
+                ) : null}
+                {showSort && sortOptions.length > 0 ? (
+                  <Button
+                    type='button'
+                    variant='outline'
+                    size='sm'
+                    className='h-9 cursor-pointer'
+                    aria-label={sortTitle}
+                    onClick={() => setIsSortDrawerOpen(true)}
+                  >
+                    {sortTitle}
+                  </Button>
+                ) : null}
+              </div>
+
+              <div className='hidden items-center gap-3 lg:flex'>
+                {showFilters ? (
+                  <Button
+                    type='button'
+                    variant='outline'
+                    size='sm'
+                    className='h-8 cursor-pointer'
+                    onClick={() => setIsFilterDrawerOpen(true)}
+                  >
+                    <SlidersHorizontal aria-hidden='true' />
+                    {filtersTitle}
+                    {activeFilters.length > 0 ? (
+                      <Badge variant='secondary'>{activeFilters.length}</Badge>
+                    ) : null}
+                  </Button>
+                ) : null}
+                <div className='ms-auto'>{sortControl(sortTitle)}</div>
+              </div>
+            </>
+          ) : null}
+
+          <div className='flex flex-wrap items-center justify-between gap-4'>
+            <div className='flex flex-1 items-center gap-4'>
+              {presentation === 'sidebar' && showFilters ? (
+                <Sheet open={isSheetOpen} onOpenChange={setIsSheetOpen}>
+                  <SheetTrigger asChild>
+                    <Button
+                      variant='outline'
+                      size='sm'
+                      className='h-8 cursor-pointer px-3 text-xs lg:hidden'
+                    >
+                      <SlidersHorizontal aria-hidden='true' />
+                      {filtersTitle}
+                    </Button>
+                  </SheetTrigger>
+                  <SheetContent side='left' className='w-full p-0 sm:w-[380px] lg:hidden'>
+                    <SheetHeader className='border-b px-6 py-4'>
+                      <SheetTitle className='text-lg'>{filtersTitle}</SheetTitle>
+                    </SheetHeader>
+                    <div className='h-[calc(100vh-4rem)] overflow-y-auto p-6'>
+                      <div className='flex flex-col gap-6'>{fields}</div>
+                    </div>
+                  </SheetContent>
+                </Sheet>
+              ) : null}
+              {searchControl}
+              {pageSizeControl}
+            </div>
+            {presentation === 'sidebar' ? (
+              <div className='flex items-center gap-4'>{sortControl(sortPlaceholder)}</div>
+            ) : null}
+          </div>
+
+          {statusView}
+          {results}
+        </main>
+      </div>
+
+      {presentation === 'toolbar' && showFilters ? (
+        <Drawer open={isFilterDrawerOpen} onOpenChange={setIsFilterDrawerOpen}>
+          <DrawerContent>
+            <DrawerHeader>
+              <DrawerTitle>{filtersTitle}</DrawerTitle>
+            </DrawerHeader>
+            <div className='min-h-0 flex-1 overflow-y-auto px-4'>{fields}</div>
+            <div className='flex items-center gap-2 border-t p-4 pb-[max(1rem,env(safe-area-inset-bottom))]'>
+              <Button type='button' variant='ghost' onClick={handleClearAll}>
+                {clearAllLabel}
+              </Button>
+              <Button type='button' className='flex-1' onClick={() => setIsFilterDrawerOpen(false)}>
+                {applyFiltersLabel}
+              </Button>
+            </div>
+          </DrawerContent>
+        </Drawer>
+      ) : null}
+
+      {presentation === 'toolbar' && showSort && sortOptions.length > 0 ? (
+        <Drawer open={isSortDrawerOpen} onOpenChange={setIsSortDrawerOpen}>
+          <DrawerContent>
+            <DrawerHeader>
+              <DrawerTitle>{sortTitle}</DrawerTitle>
+            </DrawerHeader>
+            <div className='px-4 pb-6'>
+              <RadioGroup
+                value={selectedSort}
+                onValueChange={value => {
+                  if (typeof value === 'string') {
+                    handleSortChange(value)
+                    setIsSortDrawerOpen(false)
+                  }
+                }}
+                className='gap-3'
+              >
+                {sortOptions.map(option => (
+                  <div key={option.value} className='flex items-center gap-2'>
+                    <RadioGroupItem value={option.value} id={`listing-sort-${option.value}`} />
+                    <Label htmlFor={`listing-sort-${option.value}`} className='min-h-11 font-normal'>
+                      {option.label}
+                    </Label>
+                  </div>
+                ))}
+              </RadioGroup>
+            </div>
+          </DrawerContent>
+        </Drawer>
+      ) : null}
+    </div>
+  )
+}
+
+export default CategoryListing