@thorprovider/blocks 0.1.2 → 1.0.0

package/src/blocks/e-commerce/product-categories/category-card.test.tsx

@@ -0,0 +1,68 @@
+// @vitest-environment jsdom
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { CategoryCard } from './category-card'
+import type { ProductCategoryItem } from '../../../lib/contracts'
+
+const category: ProductCategoryItem = {
+  id: 'pcat_herramientas',
+  name: 'Herramientas',
+  description: 'Taladros y accesorios',
+  image: '/products/drill.png',
+  itemCount: 12,
+  trending: true,
+  featured: true,
+  subcategories: ['Taladros', 'Accesorios'],
+}
+
+describe('CategoryCard', () => {
+  it('renders one item without section-level chrome', () => {
+    const html = renderToStaticMarkup(<CategoryCard category={category} />)
+    expect(html).toContain('Herramientas')
+    expect(html).not.toContain('<section')
+    expect(html).not.toContain('<h2')
+  })
+
+  it('renders the selected presentation and forwards presentation-specific copy', () => {
+    expect(renderToStaticMarkup(<CategoryCard category={category} />)).toContain('/products/drill.png')
+    expect(renderToStaticMarkup(<CategoryCard category={category} presentation="icons" />)).not.toContain('<img')
+    const list = renderToStaticMarkup(
+      <CategoryCard category={category} presentation="list" itemsLabel="productos" featuredLabel="Destacada" />,
+    )
+    expect(list).toContain('Taladros y accesorios')
+    expect(list).toContain('Destacada')
+    expect(list).toContain('productos')
+  })
+
+  it('exposes an accessible browse name and invokes the category action by keyboard', async () => {
+    const user = userEvent.setup()
+    const onBrowse = vi.fn()
+    render(<CategoryCard category={category} presentation="icons" onBrowse={onBrowse} />)
+    const button = screen.getByRole('button', { name: 'Herramientas' })
+
+    button.focus()
+    await user.keyboard('{Enter}')
+    await user.keyboard(' ')
+
+    expect(onBrowse).toHaveBeenCalledTimes(2)
+    expect(onBrowse).toHaveBeenLastCalledWith(category)
+  })
+
+  it('does not add an inert focus target when browsing is unavailable', () => {
+    render(<CategoryCard category={category} presentation="icons" />)
+    expect(screen.queryByRole('button')).toBeNull()
+  })
+
+  it('gives grid and list browse buttons an accessible name containing the category', () => {
+    const grid = renderToStaticMarkup(
+      <CategoryCard category={category} onBrowse={() => undefined} browseLabel="Explorar" />,
+    )
+    const list = renderToStaticMarkup(
+      <CategoryCard category={category} presentation="list" onBrowse={() => undefined} browseLabel="Explorar" />,
+    )
+    expect(grid).toContain('aria-label="Explorar Herramientas"')
+    expect(list).toContain('aria-label="Explorar Herramientas"')
+  })
+})

package/src/blocks/e-commerce/product-categories/category-card.tsx

@@ -0,0 +1,172 @@
+'use client'
+
+import { Badge } from '../../../ui/badge'
+import { Button } from '../../../ui/button'
+import { Card, CardContent } from '../../../ui/card'
+import { cn } from '../../../lib/utils'
+import type { CategoryCardSpecProps } from '../../../lib/contracts'
+import type { ProductCategoryItem } from '../../../lib/contracts'
+import {
+  formatCount,
+  resolveCategoryIcon,
+  resolveImage,
+} from './category-shared'
+
+export type CategoryCardPresentation = NonNullable<CategoryCardSpecProps['presentation']>
+
+export interface CategoryCardProps extends CategoryCardSpecProps {
+  onBrowse?: (category: ProductCategoryItem) => void
+}
+
+function GridCell({
+  category,
+  browseLabel,
+  itemsLabel,
+  trendingLabel,
+  imageFallback,
+  onBrowse,
+}: CategoryCardProps) {
+  const count = formatCount(category.itemCount, itemsLabel)
+  return (
+    <Card className="group overflow-hidden py-0 transition-all duration-500 hover:shadow-lg">
+      <div className="relative aspect-[5/4] overflow-hidden">
+        <img
+          src={resolveImage(category.image, imageFallback)}
+          alt={category.name}
+          className="size-full object-cover transition-transform duration-500 group-hover:scale-105"
+        />
+        <div className="absolute inset-0 bg-gradient-to-t from-black/60 via-black/20 to-transparent" />
+        {category.trending && trendingLabel ? (
+          <Badge className="absolute top-4 left-4 rounded-sm px-2.5 py-0.5 font-semibold">
+            {trendingLabel}
+          </Badge>
+        ) : null}
+        <div className="absolute right-0 bottom-0 left-0 p-6 text-white">
+          <h3 className="mb-1 text-xl font-bold">{category.name}</h3>
+          {category.description ? (
+            <p className="mb-3 text-sm text-white/90">{category.description}</p>
+          ) : null}
+          <div className="flex items-center justify-between">
+            {count ? <span className="text-sm">{count}</span> : null}
+            {onBrowse && browseLabel ? (
+              <Button
+                size="sm"
+                variant="secondary"
+                aria-label={`${browseLabel} ${category.name}`}
+                className="ms-auto h-8 cursor-pointer border-white/30 bg-white/20 px-3 text-xs text-white backdrop-blur-sm hover:bg-white/30"
+                onClick={() => onBrowse(category)}
+              >
+                {browseLabel}
+              </Button>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    </Card>
+  )
+}
+
+function IconsCell({ category, onBrowse }: CategoryCardProps) {
+  const Icon = resolveCategoryIcon(category.icon)
+  const clickable = Boolean(onBrowse)
+  return (
+    <Card
+      className={cn(
+        'group relative overflow-hidden px-2 py-6 shadow-xs transition-all hover:shadow-md',
+        clickable && 'cursor-pointer',
+      )}
+    >
+      {clickable ? (
+        <button
+          type="button"
+          onClick={() => onBrowse?.(category)}
+          aria-label={category.name}
+          className="absolute inset-0 z-10 rounded-xl focus-visible:inset-ring-2 focus-visible:inset-ring-ring focus-visible:outline-none"
+        />
+      ) : null}
+      <CardContent>
+        <div className="flex flex-col gap-4">
+          <div className="bg-secondary/80 text-secondary-foreground flex size-12 items-center justify-center rounded-lg">
+            <Icon className="size-5" strokeWidth={1.5} aria-hidden="true" />
+          </div>
+          <div>
+            <h3 className="text-foreground text-lg font-semibold">{category.name}</h3>
+            {category.description ? (
+              <p className="text-muted-foreground text-sm">{category.description}</p>
+            ) : null}
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  )
+}
+
+function ListCell({
+  category,
+  browseLabel,
+  itemsLabel,
+  featuredLabel,
+  onBrowse,
+}: CategoryCardProps) {
+  const Icon = resolveCategoryIcon(category.icon)
+  const count = formatCount(category.itemCount, itemsLabel)
+  return (
+    <Card className="group hover:border-primary relative py-0 transition-all duration-200 hover:shadow-md">
+      <CardContent className="p-6">
+        <div className="flex items-start gap-4">
+          <div className="flex-shrink-0">
+            <div className="bg-primary/10 group-hover:bg-primary/20 flex size-12 items-center justify-center rounded-lg transition-colors">
+              <Icon className="text-primary size-6" aria-hidden="true" />
+            </div>
+          </div>
+          <div className="min-w-0 flex-1">
+            <div className="mb-2 flex items-center gap-2">
+              <h3 className="text-lg font-semibold">{category.name}</h3>
+              {category.featured && featuredLabel ? (
+                <Badge variant="secondary" className="rounded-sm px-2 py-0.5 font-semibold">
+                  {featuredLabel}
+                </Badge>
+              ) : null}
+            </div>
+            {category.description ? (
+              <p className="text-muted-foreground mb-3 line-clamp-2 text-sm">{category.description}</p>
+            ) : null}
+            {category.subcategories && category.subcategories.length > 0 ? (
+              <div className="mb-3 flex flex-wrap gap-2">
+                {category.subcategories.map((subcategory, index) => (
+                  <span
+                    key={`${category.id}:sub:${index}`}
+                    className="bg-muted text-muted-foreground rounded-md px-2 py-1 text-xs"
+                  >
+                    {subcategory}
+                  </span>
+                ))}
+              </div>
+            ) : null}
+            {count ? <div className="text-muted-foreground text-sm">{count}</div> : null}
+            {onBrowse && browseLabel ? (
+              <Button
+                variant="ghost"
+                size="sm"
+                aria-label={`${browseLabel} ${category.name}`}
+                className="absolute end-4 bottom-4 h-8 cursor-pointer px-3 text-xs opacity-0 transition-opacity group-hover:opacity-100 focus-visible:opacity-100"
+                onClick={() => onBrowse(category)}
+              >
+                {browseLabel}
+              </Button>
+            ) : null}
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  )
+}
+
+export function CategoryCard(props: CategoryCardProps) {
+  const presentation = props.presentation ?? 'grid'
+  if (presentation === 'icons') return <IconsCell {...props} />
+  if (presentation === 'list') return <ListCell {...props} />
+  return <GridCell {...props} />
+}
+
+export default CategoryCard

package/src/blocks/e-commerce/product-categories/category-grid.test.tsx

@@ -0,0 +1,67 @@
+// @vitest-environment jsdom
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it, vi } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { CategoryGrid } from './product-category-grid'
+import type { ProductCategoryItem } from '../../../lib/contracts'
+
+const categories: ProductCategoryItem[] = [
+  { id: 'pcat_tools', name: 'Herramientas', icon: 'wrench' },
+  { id: 'pcat_paint', name: 'Pintura', icon: 'paintbrush' },
+  { id: 'pcat_garden', name: 'Jardín', icon: 'flower' },
+]
+
+describe('CategoryGrid', () => {
+  it('renders one cell per category in source order and forwards the presentation', () => {
+    const html = renderToStaticMarkup(<CategoryGrid categories={categories} presentation="icons" />)
+    const names = categories.map(({ name }) => html.indexOf(name))
+    expect(html.match(/data-slot="card"/g) ?? []).toHaveLength(categories.length)
+    expect(names[0]).toBeLessThan(names[1])
+    expect(names[1]).toBeLessThan(names[2])
+    expect(html).not.toContain('<img')
+  })
+
+  it('caps displayed categories without reordering them', () => {
+    const html = renderToStaticMarkup(<CategoryGrid categories={categories} maxItems={2} />)
+    expect(html).toContain('Herramientas')
+    expect(html).toContain('Pintura')
+    expect(html).not.toContain('Jardín')
+  })
+
+  it('owns loading and empty states', () => {
+    const loading = renderToStaticMarkup(<CategoryGrid categories={categories} loading skeletonCount={2} />)
+    expect(loading).toContain('aria-busy="true"')
+    expect(loading.match(/animate-pulse/g) ?? []).toHaveLength(2)
+    expect(loading).not.toContain('data-slot="card"')
+    expect(renderToStaticMarkup(<CategoryGrid categories={[]} emptyLabel="Sin categorías" />)).toContain(
+      'Sin categorías',
+    )
+  })
+
+  it('controls list search and exposes an accessible label', async () => {
+    const user = userEvent.setup()
+    const onQueryChange = vi.fn()
+    render(
+      <CategoryGrid
+        categories={categories}
+        presentation="list"
+        query="tal"
+        onQueryChange={onQueryChange}
+        searchLabel="Buscar categorías"
+      />,
+    )
+    const input = screen.getByRole('searchbox', { name: 'Buscar categorías' })
+    expect((input as HTMLInputElement).value).toBe('tal')
+    await user.type(input, 'a')
+    expect(onQueryChange).toHaveBeenCalledWith('tala')
+  })
+
+  it('bubbles a cell browse action with its category', async () => {
+    const user = userEvent.setup()
+    const onBrowse = vi.fn()
+    render(<CategoryGrid categories={categories} presentation="icons" onBrowse={onBrowse} />)
+    await user.click(screen.getByRole('button', { name: 'Herramientas' }))
+    expect(onBrowse).toHaveBeenCalledExactlyOnceWith(categories[0])
+  })
+})

package/src/blocks/e-commerce/product-categories/category-shared.tsx

@@ -0,0 +1,109 @@
+import {
+  ArrowRight,
+  Baby,
+  BookOpen,
+  Boxes,
+  Cable,
+  Camera,
+  Car,
+  Dumbbell,
+  Gamepad2,
+  Gift,
+  Heart,
+  Home,
+  Laptop,
+  LayoutGrid,
+  Lightbulb,
+  Package,
+  ShieldCheck,
+  Shirt,
+  ShoppingBag,
+  Smartphone,
+  Sparkles,
+  Store,
+  Tag,
+  Utensils,
+  Wrench,
+  type LucideIcon,
+} from 'lucide-react'
+
+import { Button } from '../../../ui/button'
+import { PRODUCT_IMAGE_FALLBACK } from '../../../lib/contracts'
+import type { CTA } from '../../../lib/types'
+
+export const CATEGORY_ICONS: Record<string, LucideIcon> = {
+  grid: LayoutGrid,
+  boxes: Boxes,
+  smartphone: Smartphone,
+  laptop: Laptop,
+  camera: Camera,
+  cable: Cable,
+  wrench: Wrench,
+  shield: ShieldCheck,
+  sparkles: Sparkles,
+  lightbulb: Lightbulb,
+  package: Package,
+  tag: Tag,
+  store: Store,
+  home: Home,
+  shirt: Shirt,
+  book: BookOpen,
+  gift: Gift,
+  heart: Heart,
+  car: Car,
+  utensils: Utensils,
+  gamepad: Gamepad2,
+  baby: Baby,
+  dumbbell: Dumbbell,
+}
+
+export const FALLBACK_ICON = LayoutGrid
+
+export function resolveCategoryIcon(icon?: string): LucideIcon {
+  if (!icon) return FALLBACK_ICON
+  return CATEGORY_ICONS[icon] ?? FALLBACK_ICON
+}
+
+export function formatCount(itemCount: number | undefined, itemsLabel?: string): string | undefined {
+  if (itemCount === undefined || !Number.isFinite(itemCount) || itemCount < 0) return undefined
+  const value = itemCount.toLocaleString()
+  return itemsLabel ? `${value} ${itemsLabel}` : value
+}
+
+export function resolveImage(image: string | undefined, fallback?: string): string {
+  const candidate = typeof image === 'string' ? image.trim() : ''
+  const fallbackCandidate = typeof fallback === 'string' ? fallback.trim() : ''
+  return candidate || fallbackCandidate || PRODUCT_IMAGE_FALLBACK
+}
+
+export function SectionCta({ cta }: { cta?: CTA }) {
+  if (!cta) return null
+  return (
+    <div className="mt-12 text-center">
+      <Button size="lg" className="h-10 cursor-pointer gap-2 px-4" asChild>
+        <a href={cta.href}>
+          <ShoppingBag className="size-5" />
+          {cta.label}
+        </a>
+      </Button>
+    </div>
+  )
+}
+
+export function ViewAllButton({
+  onViewAll,
+  viewAllLabel,
+}: {
+  onViewAll?: () => void
+  viewAllLabel?: string
+}) {
+  if (!onViewAll || !viewAllLabel) return null
+  return (
+    <div className="mt-12 text-center">
+      <Button variant="outline" className="h-9 cursor-pointer px-4" onClick={onViewAll}>
+        {viewAllLabel}
+        <ArrowRight />
+      </Button>
+    </div>
+  )
+}

package/src/blocks/e-commerce/product-categories/product-category-grid.tsx

@@ -0,0 +1,170 @@
+'use client'
+
+import { Search } from 'lucide-react'
+
+import { Input } from '../../../ui/input'
+import { cn } from '../../../lib/utils'
+import type {
+  CategoryGridSpecProps,
+  ProductCategoryItem,
+} from '../../../lib/contracts'
+import { CategoryCard, type CategoryCardPresentation } from './category-card'
+import { SectionCta, ViewAllButton } from './category-shared'
+
+export type CategoryGridPresentation = NonNullable<CategoryGridSpecProps['presentation']>
+
+export interface CategoryGridProps extends CategoryGridSpecProps {
+  onBrowse?: (category: ProductCategoryItem) => void
+  onViewAll?: () => void
+  onQueryChange?: (query: string) => void
+}
+
+const CONTAINER = 'mx-auto w-full max-w-7xl px-4 sm:px-6 lg:px-8'
+
+const LAYOUT: Record<CategoryGridPresentation, string> = {
+  grid: 'grid gap-6 sm:grid-cols-2 lg:grid-cols-3',
+  icons: 'mx-auto grid max-w-5xl grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4',
+  list: 'grid grid-cols-1 gap-4 lg:grid-cols-2',
+}
+
+const SKELETON: Record<CategoryGridPresentation, string> = {
+  grid: 'aspect-[5/4]',
+  icons: 'h-36',
+  list: 'h-28',
+}
+
+function Header({
+  presentation,
+  title,
+  description,
+  badge,
+}: {
+  presentation: CategoryGridPresentation
+  title?: string
+  description?: string
+  badge?: string
+}) {
+  if (presentation === 'icons') {
+    if (!badge && !title && !description) return null
+    return (
+      <div className="mx-auto mb-12 max-w-3xl text-center">
+        {badge ? (
+          <div className="mb-4 inline-flex">
+            <span className="bg-secondary/80 text-secondary-foreground rounded-full px-4 py-1.5 text-sm font-medium">
+              {badge}
+            </span>
+          </div>
+        ) : null}
+        {title ? <h2 className="text-3xl font-bold tracking-tight text-balance">{title}</h2> : null}
+        {description ? <p className="text-muted-foreground mt-4 text-lg">{description}</p> : null}
+      </div>
+    )
+  }
+
+  if (!title && !description) return null
+  return (
+    <div className={cn('text-center', presentation === 'list' ? 'mb-8' : 'mb-12')}>
+      {title ? (
+        <h2 className={cn('text-3xl font-bold tracking-tight text-balance', presentation === 'list' && 'mb-4')}>
+          {title}
+        </h2>
+      ) : null}
+      {description ? (
+        <p className={cn('text-muted-foreground text-lg', presentation !== 'list' && 'mt-4')}>
+          {description}
+        </p>
+      ) : null}
+    </div>
+  )
+}
+
+export function CategoryGrid(props: CategoryGridProps) {
+  const presentation = props.presentation ?? 'grid'
+  const {
+    categories,
+    className,
+    title,
+    description,
+    badge,
+    cta,
+    query,
+    onQueryChange,
+    onBrowse,
+    onViewAll,
+    searchPlaceholder,
+    searchLabel,
+    emptyLabel,
+    noResultsLabel,
+    viewAllLabel,
+  } = props
+
+  const displayed =
+    props.maxItems !== undefined ? categories.slice(0, props.maxItems) : categories
+  const hasQuery = Boolean(query && query.trim() !== '')
+  const emptyMessage = hasQuery ? (noResultsLabel ?? emptyLabel) : emptyLabel
+  const skeletonCount = props.skeletonCount ?? 6
+  const cellPresentation = presentation as CategoryCardPresentation
+
+  return (
+    <section className={cn('py-12', className)}>
+      <div className={CONTAINER}>
+        <Header presentation={presentation} title={title} description={description} badge={badge} />
+
+        {presentation === 'list' && onQueryChange ? (
+          <div className="relative mx-auto mb-8 max-w-md">
+            <Search
+              className="text-muted-foreground absolute top-1/2 left-3 size-4 -translate-y-1/2"
+              aria-hidden="true"
+            />
+            <Input
+              type="search"
+              placeholder={searchPlaceholder}
+              value={query ?? ''}
+              onChange={(event) => onQueryChange(event.target.value)}
+              className="ps-9 h-9"
+              aria-label={searchLabel ?? searchPlaceholder}
+            />
+          </div>
+        ) : null}
+
+        {props.loading ? (
+          <div className={LAYOUT[presentation]} aria-busy="true">
+            {Array.from({ length: skeletonCount }, (_, index) => (
+              <div
+                key={`skeleton-${index}`}
+                className={cn('bg-muted/50 animate-pulse rounded-xl', SKELETON[presentation])}
+              />
+            ))}
+          </div>
+        ) : displayed.length === 0 ? (
+          emptyMessage ? (
+            <p className="text-muted-foreground py-10 text-center text-sm">{emptyMessage}</p>
+          ) : null
+        ) : (
+          <div className={LAYOUT[presentation]}>
+            {displayed.map((category) => (
+              <CategoryCard
+                key={category.id}
+                category={category}
+                presentation={cellPresentation}
+                browseLabel={props.browseLabel}
+                itemsLabel={props.itemsLabel}
+                trendingLabel={props.trendingLabel}
+                featuredLabel={props.featuredLabel}
+                imageFallback={props.imageFallback}
+                onBrowse={onBrowse}
+              />
+            ))}
+          </div>
+        )}
+
+        {!props.loading && presentation !== 'list' ? <SectionCta cta={cta} /> : null}
+        {!props.loading && presentation !== 'grid' ? (
+          <ViewAllButton onViewAll={onViewAll} viewAllLabel={viewAllLabel} />
+        ) : null}
+      </div>
+    </section>
+  )
+}
+
+export default CategoryGrid