@thorprovider/blocks 0.1.2 → 1.0.0

package/src/blocks/e-commerce/navigation/breadcrumb.test.tsx

@@ -0,0 +1,174 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it } from 'vitest'
+
+import { Breadcrumb, breadcrumbItemSchema, breadcrumbPropsSchema } from './breadcrumb'
+
+function countNestedListItems(html: string): number {
+  const tokens = html.match(/<\/?li\b[^>]*>/g) ?? []
+  let depth = 0
+  let nested = 0
+  for (const token of tokens) {
+    if (token.startsWith('</')) {
+      depth = Math.max(0, depth - 1)
+    } else {
+      if (depth > 0) nested += 1
+      depth += 1
+    }
+  }
+  return nested
+}
+
+describe('Breadcrumb', () => {
+  it('parses a valid props object', () => {
+    const result = breadcrumbPropsSchema.parse({
+      items: [{ label: 'Home', href: '/' }, { label: 'Current' }],
+    })
+    expect(result.items).toHaveLength(2)
+  })
+
+  it('rejects a maxItems below 2', () => {
+    expect(() =>
+      breadcrumbPropsSchema.parse({ items: [], maxItems: 1 }),
+    ).toThrow()
+  })
+
+  it('requires a label on each item', () => {
+    expect(() => breadcrumbItemSchema.parse({ href: '/' })).toThrow()
+  })
+
+  it('renders nothing when there are no items', () => {
+    expect(renderToStaticMarkup(<Breadcrumb items={[]} />)).toBe('')
+  })
+
+  it('renders nothing when every label is blank', () => {
+    const html = renderToStaticMarkup(
+      <Breadcrumb items={[{ label: '  ' }, { label: '' }]} />,
+    )
+    expect(html).toBe('')
+  })
+
+  it('renders a labelled landmark with the current item as a non-link', () => {
+    const html = renderToStaticMarkup(
+      <Breadcrumb
+        items={[
+          { label: 'Home', href: '/' },
+          { label: 'Tools', href: '/categories/tools' },
+          { label: 'Drill' },
+        ]}
+      />,
+    )
+    expect(html).toContain('aria-label="Breadcrumb"')
+    expect(html).toContain('aria-current="page"')
+    expect(html).toContain('href="/categories/tools"')
+    expect(html).not.toContain('href="Drill"')
+    expect(html).toContain('Drill')
+  })
+
+  it('honours a custom landmark label', () => {
+    const html = renderToStaticMarkup(
+      <Breadcrumb
+        ariaLabel="You are here"
+        items={[{ label: 'Home', href: '/' }, { label: 'Current' }]}
+      />,
+    )
+    expect(html).toContain('aria-label="You are here"')
+  })
+
+  it('wraps the trail in the shared page container', () => {
+    const html = renderToStaticMarkup(
+      <Breadcrumb items={[{ label: 'Home', href: '/' }, { label: 'Current' }]} />,
+    )
+    expect(html).toContain('mx-auto')
+    expect(html).toContain('max-w-7xl')
+    expect(html).toContain('px-4')
+  })
+
+  it('merges a custom className onto the container', () => {
+    const html = renderToStaticMarkup(
+      <Breadcrumb
+        className="bg-primary text-primary-foreground"
+        items={[{ label: 'Home', href: '/' }, { label: 'Current' }]}
+      />,
+    )
+    expect(html).toContain('bg-primary')
+    expect(html).toContain('max-w-7xl')
+  })
+
+  it('lets a custom className override the container utility', () => {
+    const html = renderToStaticMarkup(
+      <Breadcrumb
+        className="px-0"
+        items={[{ label: 'Home', href: '/' }, { label: 'Current' }]}
+      />,
+    )
+    expect(html).toContain('px-0')
+    expect(html).not.toContain('px-4')
+  })
+
+  it('collapses intermediate levels behind an ellipsis past maxItems', () => {
+    const html = renderToStaticMarkup(
+      <Breadcrumb
+        maxItems={3}
+        items={[
+          { label: 'Home', href: '/' },
+          { label: 'A', href: '/a' },
+          { label: 'B', href: '/b' },
+          { label: 'C', href: '/c' },
+          { label: 'Current' },
+        ]}
+      />,
+    )
+    expect(html).toContain('data-slot="breadcrumb-ellipsis"')
+    expect(html).toContain('Current')
+    expect(html).not.toContain('>A<')
+  })
+
+  it('truncates long labels', () => {
+    const html = renderToStaticMarkup(
+      <Breadcrumb
+        items={[
+          { label: 'Home', href: '/' },
+          { label: 'A very long category name that would overflow the trail' },
+        ]}
+      />,
+    )
+    expect(html).toContain('max-w-[24ch]')
+    expect(html).toContain('truncate')
+  })
+
+  it('renders a mobile back link to the parent and hides the full list at base', () => {
+    const html = renderToStaticMarkup(
+      <Breadcrumb
+        items={[
+          { label: 'Home', href: '/' },
+          { label: 'Tools', href: '/categories/tools' },
+          { label: 'Drill' },
+        ]}
+      />,
+    )
+    expect(html).toContain('md:hidden')
+    expect(html).toContain('href="/categories/tools"')
+    expect(html).toContain('hidden md:flex')
+  })
+
+  it('renders no back link for a single-level trail', () => {
+    const html = renderToStaticMarkup(
+      <Breadcrumb items={[{ label: 'Only' }]} />,
+    )
+    expect(html).not.toContain('md:hidden')
+  })
+
+  it('renders separators as siblings of items, never nesting list items', () => {
+    const html = renderToStaticMarkup(
+      <Breadcrumb
+        items={[
+          { label: 'Home', href: '/' },
+          { label: 'Tools', href: '/categories/tools' },
+          { label: 'Drill' },
+        ]}
+      />,
+    )
+    expect(html).toContain('data-slot="breadcrumb-separator"')
+    expect(countNestedListItems(html)).toBe(0)
+  })
+})

package/src/blocks/e-commerce/navigation/breadcrumb.tsx

@@ -0,0 +1,130 @@
+import { Fragment } from 'react'
+import { ChevronLeft } from 'lucide-react'
+import { z } from 'zod'
+
+import { cn } from '../../../lib/utils'
+import {
+  Breadcrumb as BreadcrumbRoot,
+  BreadcrumbEllipsis,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+} from '../../../ui/breadcrumb'
+
+export const breadcrumbItemSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+
+export type BreadcrumbItemData = z.infer<typeof breadcrumbItemSchema>
+
+export const breadcrumbPropsSchema = z.object({
+  items: z.array(breadcrumbItemSchema),
+  maxItems: z.number().int().min(2).optional(),
+  ariaLabel: z.string().optional(),
+  backLabel: z.string().optional(),
+  className: z.string().optional(),
+})
+
+export type BreadcrumbProps = z.infer<typeof breadcrumbPropsSchema>
+
+const DEFAULT_MAX_ITEMS = 4
+const ELLIPSIS = Symbol('breadcrumb-ellipsis')
+
+// Shared horizontal rhythm: the same max-width and responsive gutters the
+// sibling blocks (category listing, product overview) use, so the trail aligns
+// with the page content instead of sitting flush against the viewport edge.
+const CONTAINER = 'mx-auto w-full max-w-7xl px-4 py-4 sm:px-6 lg:px-8'
+
+type DisplayEntry = BreadcrumbItemData | typeof ELLIPSIS
+
+function collapseItems(
+  items: BreadcrumbItemData[],
+  maxItems: number,
+): DisplayEntry[] {
+  if (items.length <= maxItems) return items
+  return [items[0], ELLIPSIS, ...items.slice(items.length - (maxItems - 1))]
+}
+
+/**
+ * Breadcrumb trail for a real navigation path (Home → … → current).
+ *
+ * Framework-agnostic and prop-driven: plain anchors (no router) and the shared
+ * shadcn breadcrumb primitives. The last item is the current page and is never
+ * a link (`aria-current="page"`); earlier items link only when an `href` is
+ * given. Long labels truncate, and trails longer than `maxItems` collapse the
+ * intermediate levels behind an ellipsis. On mobile the full list is replaced
+ * by a single back link to the parent, so a wide trail never overflows.
+ *
+ * Renders nothing when there are no labelled items.
+ */
+export function Breadcrumb({
+  items,
+  maxItems = DEFAULT_MAX_ITEMS,
+  ariaLabel = 'Breadcrumb',
+  backLabel,
+  className,
+}: BreadcrumbProps) {
+  const clean = items.filter((item) => item.label.trim().length > 0)
+  if (clean.length === 0) return null
+
+  const parent = clean.length > 1 ? clean[clean.length - 2] : undefined
+  const entries = collapseItems(clean, maxItems)
+
+  return (
+    <BreadcrumbRoot aria-label={ariaLabel} className={cn(CONTAINER, className)}>
+      {parent ? (
+        <a
+          href={parent.href ?? '#'}
+          className="inline-flex items-center gap-1 text-sm font-medium text-muted-foreground hover:text-foreground md:hidden"
+        >
+          <ChevronLeft className="size-4" aria-hidden="true" />
+          <span className="truncate">{backLabel ?? parent.label}</span>
+        </a>
+      ) : null}
+      <BreadcrumbList className="hidden md:flex">
+        {entries.map((entry, index) => {
+          const isLast = index === entries.length - 1
+          const key =
+            entry === ELLIPSIS
+              ? 'ellipsis'
+              : `${index}:${entry.href ?? ''}:${entry.label}`
+          return (
+            <Fragment key={key}>
+              <BreadcrumbItem>
+                {entry === ELLIPSIS ? (
+                  <BreadcrumbEllipsis />
+                ) : isLast ? (
+                  <BreadcrumbPage
+                    className="max-w-[24ch] truncate"
+                    title={entry.label}
+                  >
+                    {entry.label}
+                  </BreadcrumbPage>
+                ) : entry.href ? (
+                  <BreadcrumbLink
+                    href={entry.href}
+                    className="max-w-[24ch] truncate"
+                    title={entry.label}
+                  >
+                    {entry.label}
+                  </BreadcrumbLink>
+                ) : (
+                  <span
+                    className="max-w-[24ch] truncate"
+                    title={entry.label}
+                  >
+                    {entry.label}
+                  </span>
+                )}
+              </BreadcrumbItem>
+              {!isLast ? <BreadcrumbSeparator /> : null}
+            </Fragment>
+          )
+        })}
+      </BreadcrumbList>
+    </BreadcrumbRoot>
+  )
+}

package/src/blocks/e-commerce/navigation/mobile-bottom-nav.test.tsx

@@ -0,0 +1,74 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it } from 'vitest'
+
+import {
+  MobileBottomNav,
+  mobileBottomNavItemSchema,
+  mobileBottomNavPropsSchema,
+} from './mobile-bottom-nav'
+
+describe('MobileBottomNav', () => {
+  it('parses a valid props object', () => {
+    const result = mobileBottomNavPropsSchema.parse({
+      items: [{ label: 'Home', href: '/', icon: 'home' }],
+    })
+    expect(result.items).toHaveLength(1)
+  })
+
+  it('requires a label and href on each item', () => {
+    expect(() => mobileBottomNavItemSchema.parse({ label: 'Home' })).toThrow()
+  })
+
+  it('rejects an unknown icon name at the boundary', () => {
+    expect(() =>
+      mobileBottomNavItemSchema.parse({
+        label: 'Home',
+        href: '/',
+        icon: 'not-an-icon',
+      }),
+    ).toThrow()
+  })
+
+  it('renders nothing when there are no destinations', () => {
+    expect(renderToStaticMarkup(<MobileBottomNav items={[]} />)).toBe('')
+  })
+
+  it('renders a labelled, mobile-only landmark offset by the safe area', () => {
+    const html = renderToStaticMarkup(
+      <MobileBottomNav
+        items={[
+          { label: 'Home', href: '/', icon: 'home' },
+          { label: 'Store', href: '/categories/all', icon: 'store' },
+        ]}
+      />,
+    )
+    expect(html).toContain('aria-label="Primary"')
+    expect(html).toContain('md:hidden')
+    expect(html).toContain('env(safe-area-inset-bottom)')
+    expect(html).toContain('h-14')
+  })
+
+  it('marks the current destination accessibly and with a non-colour cue', () => {
+    const html = renderToStaticMarkup(
+      <MobileBottomNav
+        currentHref="/categories/all"
+        items={[
+          { label: 'Home', href: '/', icon: 'home' },
+          { label: 'Store', href: '/categories/all', icon: 'store' },
+        ]}
+      />,
+    )
+    expect(html).toContain('aria-current="page"')
+    expect(html).toContain('font-semibold')
+  })
+
+  it('marks no destination when the current href matches none', () => {
+    const html = renderToStaticMarkup(
+      <MobileBottomNav
+        currentHref="/unknown"
+        items={[{ label: 'Home', href: '/', icon: 'home' }]}
+      />,
+    )
+    expect(html).not.toContain('aria-current')
+  })
+})

package/src/blocks/e-commerce/navigation/mobile-bottom-nav.tsx

@@ -0,0 +1,78 @@
+import { z } from 'zod'
+
+import { cn } from '../../../lib/utils'
+import { type CategoryIconName, CategoryIcon, categoryIconNameSchema } from './category-icon'
+
+export const mobileBottomNavItemSchema = z.object({
+  id: z.string().optional(),
+  label: z.string(),
+  href: z.string(),
+  icon: categoryIconNameSchema.optional(),
+})
+
+export type MobileBottomNavItem = z.infer<typeof mobileBottomNavItemSchema>
+
+export const mobileBottomNavPropsSchema = z.object({
+  items: z.array(mobileBottomNavItemSchema),
+  currentHref: z.string().optional(),
+  ariaLabel: z.string().optional(),
+  className: z.string().optional(),
+})
+
+export type MobileBottomNavProps = z.infer<typeof mobileBottomNavPropsSchema>
+
+/**
+ * Mobile-only bottom navigation offering the primary destinations.
+ *
+ * Framework-agnostic and prop-driven: plain anchors (no router). Hidden at
+ * `md` and up; offsets the iOS home indicator via `env(safe-area-inset-bottom)`;
+ * each destination meets the 44px minimum touch target. The current
+ * destination is marked with `aria-current="page"` and a non-colour cue (weight
+ * + indicator bar), never colour alone.
+ */
+export function MobileBottomNav({
+  items,
+  currentHref,
+  ariaLabel = 'Primary',
+  className,
+}: MobileBottomNavProps) {
+  if (items.length === 0) return null
+
+  return (
+    <nav
+      aria-label={ariaLabel}
+      className={cn(
+        'fixed inset-x-0 bottom-0 z-40 border-t bg-card text-foreground md:hidden',
+        className,
+      )}
+      style={{ paddingBottom: 'env(safe-area-inset-bottom)' }}
+    >
+      <ul className="flex">
+        {items.map((item) => {
+          const active = currentHref !== undefined && item.href === currentHref
+          return (
+            <li key={item.id ?? item.href} className="relative flex-1">
+              {active ? (
+                <span
+                  aria-hidden="true"
+                  className="absolute inset-x-0 top-0 mx-auto h-0.5 w-8 rounded-full bg-primary"
+                />
+              ) : null}
+              <a
+                href={item.href}
+                aria-current={active ? 'page' : undefined}
+                className={cn(
+                  'flex h-14 flex-col items-center justify-center gap-0.5 text-xs text-muted-foreground',
+                  active && 'font-semibold text-primary',
+                )}
+              >
+                <CategoryIcon name={item.icon} className="size-5" />
+                <span className="truncate">{item.label}</span>
+              </a>
+            </li>
+          )
+        })}
+      </ul>
+    </nav>
+  )
+}

package/src/blocks/e-commerce/navigation/skip-to-content.test.tsx

@@ -0,0 +1,35 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it } from 'vitest'
+
+import { SkipToContent, skipToContentPropsSchema } from './skip-to-content'
+
+describe('SkipToContent', () => {
+  it('parses a valid props object', () => {
+    const result = skipToContentPropsSchema.parse({ targetId: 'main' })
+    expect(result.targetId).toBe('main')
+  })
+
+  it('requires a targetId', () => {
+    expect(() => skipToContentPropsSchema.parse({})).toThrow()
+  })
+
+  it('renders a hidden anchor targeting the content id', () => {
+    const html = renderToStaticMarkup(<SkipToContent targetId="main" />)
+    expect(html).toContain('href="#main"')
+    expect(html).toContain('sr-only')
+    expect(html).toContain('Skip to content')
+  })
+
+  it('honours a custom label', () => {
+    const html = renderToStaticMarkup(
+      <SkipToContent targetId="content" label="Saltar al contenido" />,
+    )
+    expect(html).toContain('Saltar al contenido')
+    expect(html).toContain('href="#content"')
+  })
+
+  it('becomes visible on focus', () => {
+    const html = renderToStaticMarkup(<SkipToContent targetId="main" />)
+    expect(html).toContain('focus:not-sr-only')
+  })
+})

package/src/blocks/e-commerce/navigation/skip-to-content.tsx

@@ -0,0 +1,37 @@
+import { z } from 'zod'
+
+import { cn } from '../../../lib/utils'
+
+export const skipToContentPropsSchema = z.object({
+  targetId: z.string(),
+  label: z.string().optional(),
+  className: z.string().optional(),
+})
+
+export type SkipToContentProps = z.infer<typeof skipToContentPropsSchema>
+
+/**
+ * Skip-to-content link (WCAG 2.4.1 Bypass Blocks).
+ *
+ * Framework-agnostic and prop-driven: a plain anchor to the main content id,
+ * visually hidden until it receives focus, then pinned at the top-left with
+ * visible contrast. The target element is responsible for carrying the id (and
+ * being focusable); this block only renders the bypass affordance.
+ */
+export function SkipToContent({
+  targetId,
+  label = 'Skip to content',
+  className,
+}: SkipToContentProps) {
+  return (
+    <a
+      href={`#${targetId}`}
+      className={cn(
+        'sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-[100] focus:rounded-md focus:bg-primary focus:px-4 focus:py-2 focus:text-sm focus:font-semibold focus:text-primary-foreground focus:shadow-lg',
+        className,
+      )}
+    >
+      {label}
+    </a>
+  )
+}

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

@@ -0,0 +1,122 @@
+// @vitest-environment jsdom
+import { renderToStaticMarkup } from 'react-dom/server'
+import { beforeAll, 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 { CategoryGrid } from './product-category-grid'
+import type { ProductCategoryItem } from '../../../lib/contracts'
+
+beforeAll(() => {
+  ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
+})
+
+const category: ProductCategoryItem = {
+  id: 'pcat_herramientas',
+  handle: 'herramientas',
+  name: 'Herramientas',
+  description: 'Taladros y accesorios',
+  image: '/products/drill.png',
+  itemCount: 12,
+  trending: true,
+  featured: true,
+  subcategories: ['Taladros', 'Accesorios'],
+}
+
+const categories: ProductCategoryItem[] = [
+  category,
+  { ...category, id: 'pcat_pintura', handle: 'pintura', name: 'Pintura', image: undefined },
+  { ...category, id: 'pcat_jardin', handle: 'jardin', name: 'Jardín' },
+]
+
+const card = (extra: Record<string, unknown> = {}) =>
+  renderToStaticMarkup(<CategoryCard category={category} {...extra} />)
+
+const grid = (extra: Record<string, unknown> = {}) =>
+  renderToStaticMarkup(<CategoryGrid categories={categories} {...extra} />)
+
+describe('CategoryCard — item cell', () => {
+  it('renders a single category without section chrome', () => {
+    const html = card()
+    expect(html).toContain('Herramientas')
+    expect(html).not.toContain('<section')
+    expect(html).not.toContain('<h2')
+  })
+
+  it('renders the image for the grid presentation and omits it for icons', () => {
+    expect(card()).toContain('/products/drill.png')
+    expect(card({ presentation: 'icons' })).not.toContain('<img')
+  })
+
+  it('keeps counts honest (zero and unknown are not invented)', () => {
+    expect(card()).toContain('12')
+    expect(renderToStaticMarkup(<CategoryCard category={{ ...category, itemCount: undefined }} />)).not.toContain('items</span>')
+    expect(renderToStaticMarkup(<CategoryCard category={{ ...category, itemCount: 0 }} />)).not.toContain('items</span>')
+  })
+
+  it('only exposes browse when a handler exists', () => {
+    expect(card({ browseLabel: 'Ver' })).not.toContain('Ver Herramientas')
+    const html = card({ browseLabel: 'Ver', onBrowse: vi.fn() })
+    expect(html).toContain('aria-label="Ver Herramientas"')
+  })
+
+  it('renders the list cell with description, chips and featured badge', () => {
+    const html = card({ presentation: 'list', featuredLabel: 'Destacada', itemsLabel: 'productos' })
+    expect(html).toContain('Taladros y accesorios')
+    expect(html).toContain('Taladros')
+    expect(html).toContain('Destacada')
+    expect(html).toContain('productos')
+  })
+})
+
+describe('CategoryGrid — listing', () => {
+  it('renders one cell per category', () => {
+    const html = grid()
+    expect(html).toContain('Herramientas')
+    expect(html).toContain('Pintura')
+    expect(html).toContain('Jardín')
+    expect(html.match(/data-slot="card"/g) ?? []).toHaveLength(3)
+  })
+
+  it('caps the rendered collection with maxItems', () => {
+    const html = grid({ maxItems: 2 })
+    expect(html).toContain('Herramientas')
+    expect(html).toContain('Pintura')
+    expect(html).not.toContain('Jardín')
+  })
+
+  it('owns its loading state with skeletons and no cells', () => {
+    const html = grid({ loading: true, skeletonCount: 3 })
+    expect(html).toContain('aria-busy="true"')
+    expect(html).not.toContain('data-slot="card"')
+  })
+
+  it('owns its empty state', () => {
+    expect(renderToStaticMarkup(<CategoryGrid categories={[]} emptyLabel="Sin categorías" />)).toContain('Sin categorías')
+  })
+
+  it('renders the search control only in the list presentation', () => {
+    expect(grid({ presentation: 'grid', onQueryChange: vi.fn() })).not.toContain('type="search"')
+    expect(grid({ presentation: 'list', onQueryChange: vi.fn(), searchPlaceholder: 'Buscar' })).toContain('type="search"')
+  })
+
+  it('renders view-all only outside the grid and the section cta only outside the list', () => {
+    const withBoth = { cta: { label: 'Comprar', href: '/tienda' }, onViewAll: vi.fn(), viewAllLabel: 'Ver todo' }
+    const gridHtml = grid({ presentation: 'grid', ...withBoth })
+    expect(gridHtml).toContain('Comprar')
+    expect(gridHtml).not.toContain('Ver todo')
+    const listHtml = grid({ presentation: 'list', ...withBoth })
+    expect(listHtml).toContain('Ver todo')
+    expect(listHtml).not.toContain('Comprar')
+  })
+
+  it('forwards the controlled query to the search input', 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.getByLabelText('Buscar categorías') as HTMLInputElement
+    expect(input.value).toBe('tal')
+    await user.type(input, 'a')
+    expect(onQueryChange).toHaveBeenCalled()
+  })
+})