@thorprovider/blocks 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thorprovider/blocks",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Reusable, framework-agnostic React component blocks for Thor Commerce storefronts.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,7 +40,7 @@
   "license": "MIT",
   "dependencies": {
     "@base-ui/react": "^1.8.0",
-    "@thorprovider/types": "^5.7.9",
+    "@thorprovider/types": "^5.8.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cn": "^0.4.0",

package/src/blocks/e-commerce/navigation/back-to-top.test.tsx

@@ -0,0 +1,27 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it } from 'vitest'
+
+import { BackToTop, backToTopPropsSchema, resolveScrollBehavior } from './back-to-top'
+
+describe('BackToTop', () => {
+  it('parses a valid props object', () => {
+    const result = backToTopPropsSchema.parse({ threshold: 300 })
+    expect(result.threshold).toBe(300)
+  })
+
+  it('accepts an empty props object', () => {
+    expect(() => backToTopPropsSchema.parse({})).not.toThrow()
+  })
+
+  it('uses an instant jump under reduced motion', () => {
+    expect(resolveScrollBehavior(true)).toBe('auto')
+  })
+
+  it('uses a smooth scroll when motion is allowed', () => {
+    expect(resolveScrollBehavior(false)).toBe('smooth')
+  })
+
+  it('renders nothing before it becomes visible', () => {
+    expect(renderToStaticMarkup(<BackToTop />)).toBe('')
+  })
+})

package/src/blocks/e-commerce/navigation/back-to-top.tsx

@@ -0,0 +1,71 @@
+'use client'
+
+import { ArrowUp } from 'lucide-react'
+import { useEffect, useState } from 'react'
+import { z } from 'zod'
+
+import { cn } from '../../../lib/utils'
+
+export const backToTopPropsSchema = z.object({
+  threshold: z.number().optional(),
+  label: z.string().optional(),
+  className: z.string().optional(),
+})
+
+export type BackToTopProps = z.infer<typeof backToTopPropsSchema>
+
+const DEFAULT_THRESHOLD = 400
+
+/**
+ * Resolve the scroll behavior for a back-to-top activation. Pure so it can be
+ * unit-tested without a DOM: reduced motion yields an instant jump.
+ */
+export function resolveScrollBehavior(
+  prefersReducedMotion: boolean,
+): 'auto' | 'smooth' {
+  return prefersReducedMotion ? 'auto' : 'smooth'
+}
+
+/**
+ * Back-to-top control that appears once the page is scrolled past `threshold`
+ * and returns the viewport to the top. Honors `prefers-reduced-motion` (instant
+ * jump instead of a smooth scroll). Framework-agnostic; icon-only with an
+ * accessible label.
+ */
+export function BackToTop({
+  threshold = DEFAULT_THRESHOLD,
+  label = 'Back to top',
+  className,
+}: BackToTopProps) {
+  const [visible, setVisible] = useState(false)
+
+  useEffect(() => {
+    const onScroll = () => setVisible(window.scrollY > threshold)
+    onScroll()
+    window.addEventListener('scroll', onScroll, { passive: true })
+    return () => window.removeEventListener('scroll', onScroll)
+  }, [threshold])
+
+  if (!visible) return null
+
+  const handleClick = () => {
+    const reduce =
+      typeof window !== 'undefined' &&
+      window.matchMedia('(prefers-reduced-motion: reduce)').matches
+    window.scrollTo({ top: 0, behavior: resolveScrollBehavior(reduce) })
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      aria-label={label}
+      className={cn(
+        'fixed bottom-4 right-4 z-40 inline-flex size-11 items-center justify-center rounded-full border bg-card text-foreground shadow-lg transition-colors hover:bg-secondary',
+        className,
+      )}
+    >
+      <ArrowUp className="size-5" aria-hidden="true" />
+    </button>
+  )
+}

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>
+  )
+}