@thorprovider/blocks 0.1.2 → 1.0.0

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

@@ -0,0 +1,462 @@
+'use client'
+
+import {
+  ArrowRight,
+  Baby,
+  BookOpen,
+  Boxes,
+  Cable,
+  Camera,
+  Car,
+  Dumbbell,
+  Gamepad2,
+  Gift,
+  Heart,
+  Home,
+  Laptop,
+  LayoutGrid,
+  Lightbulb,
+  Package,
+  Search,
+  ShieldCheck,
+  Shirt,
+  ShoppingBag,
+  Smartphone,
+  Sparkles,
+  Store,
+  Tag,
+  Utensils,
+  Wrench,
+  type LucideIcon,
+} from 'lucide-react'
+
+import { Badge } from '../../../ui/badge'
+import { Button } from '../../../ui/button'
+import { Card, CardContent } from '../../../ui/card'
+import { Input } from '../../../ui/input'
+import { cn } from '../../../lib/utils'
+import { PRODUCT_IMAGE_FALLBACK } from '../../../lib/contracts'
+import type { CTA } from '../../../lib/types'
+import type { ProductCategoryItem, ProductCategorySpecProps } from '../../../lib/contracts'
+
+/**
+ * The bounded presentation surface. `grid` is image-forward, `icons` is a
+ * compact icon grid, and `list` is a described row list with subcategory chips
+ * and an optional controlled search. The value changes structure, never the
+ * data contract or the callbacks.
+ */
+export type ProductCategoryPresentation = NonNullable<ProductCategorySpecProps['presentation']>
+
+export interface ProductCategoryProps {
+  /** Canonical category projection; absent optional fields degrade gracefully. */
+  categories: ProductCategoryItem[]
+  /** Bounded presentation option; defaults to `grid`. */
+  presentation?: ProductCategoryPresentation
+  title?: string
+  description?: string
+  /** Optional eyebrow label (`icons` presentation). */
+  badge?: string
+  /** Optional section-level link action. */
+  cta?: CTA
+  /** Controlled search value (`list` presentation); the host owns filtering. */
+  query?: string
+  onQueryChange?: (query: string) => void
+  onBrowse?: (category: ProductCategoryItem) => void
+  onViewAll?: () => void
+  // All user-facing copy is supplied by the host; the block ships no defaults.
+  searchPlaceholder?: string
+  searchLabel?: string
+  emptyLabel?: string
+  noResultsLabel?: string
+  browseLabel?: string
+  viewAllLabel?: string
+  trendingLabel?: string
+  featuredLabel?: string
+  itemsLabel?: string
+  /** Neutral placeholder for a missing image; defaults to `PRODUCT_IMAGE_FALLBACK`. */
+  imageFallback?: string
+  className?: string
+}
+
+/**
+ * Bounded, neutral icon vocabulary. The prop is a plain string (never a named
+ * or sector-specific enum); an unknown or absent key renders a neutral fallback.
+ */
+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,
+}
+
+const FALLBACK_ICON: LucideIcon = LayoutGrid
+
+function resolveCategoryIcon(icon: string | undefined): LucideIcon {
+  if (!icon) return FALLBACK_ICON
+  return CATEGORY_ICONS[icon] ?? FALLBACK_ICON
+}
+
+/**
+ * Formats a category item count only when it is a supplied, finite,
+ * non-negative number. Returns `undefined` for unknown or invalid values so the
+ * caller omits the count entirely (a real `0` is preserved). The optional
+ * `itemsLabel` is host-supplied copy — the block never hardcodes a unit.
+ */
+function formatCount(itemCount: number | undefined, itemsLabel: string | undefined): string | undefined {
+  if (itemCount === undefined || !Number.isFinite(itemCount) || itemCount < 0) {
+    return undefined
+  }
+  const value = itemCount.toLocaleString()
+  return itemsLabel ? `${value} ${itemsLabel}` : value
+}
+
+function resolveImage(image: string | undefined, fallback: string): string {
+  return image && image.trim() !== '' ? image : fallback
+}
+
+function SectionCta({ cta }: { cta: CTA | undefined }) {
+  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>
+  )
+}
+
+function ViewAllButton({ onViewAll, viewAllLabel }: { onViewAll?: () => void; viewAllLabel?: string }) {
+  // Purpose-gated: no handler or no label means no affordance.
+  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>
+  )
+}
+
+function GridPresentation({
+  categories,
+  title,
+  description,
+  cta,
+  onBrowse,
+  browseLabel,
+  trendingLabel,
+  itemsLabel,
+  imageFallback,
+  className,
+}: ProductCategoryProps) {
+  const fallback = imageFallback ?? PRODUCT_IMAGE_FALLBACK
+  return (
+    <section className={cn('py-12', className)}>
+      <div className='mx-auto w-full max-w-7xl px-4 sm:px-6 lg:px-8'>
+        {title || description ? (
+          <div className='mb-12 text-center'>
+            {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>
+        ) : null}
+
+        <div className='grid gap-6 sm:grid-cols-2 lg:grid-cols-3'>
+          {categories.map(category => {
+            const countLabel = formatCount(category.itemCount, itemsLabel)
+            return (
+              <Card
+                key={category.id}
+                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, fallback)}
+                    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'>
+                      {countLabel ? <span className='text-sm'>{countLabel}</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}
+                          <ArrowRight />
+                        </Button>
+                      ) : null}
+                    </div>
+                  </div>
+                </div>
+              </Card>
+            )
+          })}
+        </div>
+
+        <SectionCta cta={cta} />
+      </div>
+    </section>
+  )
+}
+
+function IconsPresentation({
+  categories,
+  title,
+  description,
+  badge,
+  cta,
+  onBrowse,
+  onViewAll,
+  viewAllLabel,
+  className,
+}: ProductCategoryProps) {
+  return (
+    <section className={cn('py-12', className)}>
+      <div className='mx-auto w-full max-w-7xl px-4 sm:px-6 lg:px-8'>
+        {badge || title || description ? (
+          <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'>{description}</p> : null}
+          </div>
+        ) : null}
+
+        <div className='mx-auto grid max-w-5xl grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4'>
+          {categories.map(category => {
+            const Icon = resolveCategoryIcon(category.icon)
+            const clickable = Boolean(onBrowse)
+            return (
+              <Card
+                key={category.id}
+                className={cn(
+                  'group relative overflow-hidden px-2 py-6 shadow-xs transition-all hover:shadow-md',
+                  clickable && 'cursor-pointer',
+                )}
+              >
+                {clickable ? (
+                  // A stretched native control keeps the whole card clickable
+                  // while focus, activation, and the accessible name come from
+                  // the platform. The Card stays non-interactive so no
+                  // block-level element is nested inside the button, and with
+                  // no browse handler there is no control and no focus target.
+                  <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>
+            )
+          })}
+        </div>
+
+        <SectionCta cta={cta} />
+        <ViewAllButton onViewAll={onViewAll} viewAllLabel={viewAllLabel} />
+      </div>
+    </section>
+  )
+}
+
+function ListPresentation({
+  categories,
+  title,
+  description,
+  query,
+  onQueryChange,
+  searchPlaceholder,
+  searchLabel,
+  emptyLabel,
+  noResultsLabel,
+  featuredLabel,
+  browseLabel,
+  itemsLabel,
+  onBrowse,
+  onViewAll,
+  viewAllLabel,
+  className,
+}: ProductCategoryProps) {
+  const hasQuery = Boolean(query && query.trim() !== '')
+  // The host owns filtering: this presentation renders exactly the categories it
+  // receives. Only the empty copy depends on whether a query is active.
+  const emptyMessage = hasQuery ? noResultsLabel ?? emptyLabel : emptyLabel
+
+  return (
+    <section className={cn('py-12', className)}>
+      <div className='mx-auto w-full max-w-7xl px-4 sm:px-6 lg:px-8'>
+        {title || description ? (
+          <div className='mb-8 text-center'>
+            {title ? (
+              <h2 className='mb-4 text-3xl font-bold tracking-tight text-balance'>{title}</h2>
+            ) : null}
+            {description ? <p className='text-muted-foreground text-lg'>{description}</p> : null}
+          </div>
+        ) : null}
+
+        {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}
+
+        {categories.length === 0 ? (
+          emptyMessage ? (
+            <p className='text-muted-foreground py-10 text-center text-sm'>{emptyMessage}</p>
+          ) : null
+        ) : (
+          <div className='grid grid-cols-1 gap-4 lg:grid-cols-2'>
+            {categories.map(category => {
+              const Icon = resolveCategoryIcon(category.icon)
+              const countLabel = formatCount(category.itemCount, itemsLabel)
+              return (
+                <Card
+                  key={category.id}
+                  className={cn(
+                    '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((sub, index) => (
+                              <span
+                                key={`${category.id}:sub:${index}`}
+                                className='bg-muted text-muted-foreground rounded-md px-2 py-1 text-xs'
+                              >
+                                {sub}
+                              </span>
+                            ))}
+                          </div>
+                        ) : null}
+
+                        {countLabel ? (
+                          <div className='text-muted-foreground text-sm'>{countLabel}</div>
+                        ) : null}
+                      </div>
+                    </div>
+
+                    {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}
+                        <ArrowRight />
+                      </Button>
+                    ) : null}
+                  </CardContent>
+                </Card>
+              )
+            })}
+          </div>
+        )}
+
+        <ViewAllButton onViewAll={onViewAll} viewAllLabel={viewAllLabel} />
+      </div>
+    </section>
+  )
+}
+
+export function ProductCategory(props: ProductCategoryProps) {
+  const presentation = props.presentation ?? 'grid'
+  if (presentation === 'icons') return <IconsPresentation {...props} />
+  if (presentation === 'list') return <ListPresentation {...props} />
+  return <GridPresentation {...props} />
+}
+
+export default ProductCategory