@thorprovider/blocks 0.1.1 → 0.1.3

package/src/blocks/e-commerce/checkout-forms/checkout-form-1.test.tsx

@@ -0,0 +1,216 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import { describe, expect, it } from 'vitest'
+import type { PaymentMethod } from '@thorprovider/types'
+import { CheckoutForm1PaymentStep } from './checkout-form-1-payment-step'
+import { CheckoutForm1ShippingStep } from './checkout-form-1-shipping-step'
+import { CheckoutForm1OrderSummary } from './checkout-form-1-order-summary'
+import type { CheckoutForm1FormData } from './checkout-form-1'
+
+const formData: CheckoutForm1FormData = {
+  email: '',
+  firstName: '',
+  lastName: '',
+  phone: '',
+  address: '',
+  city: '',
+  state: '',
+  zipCode: '',
+  country: 'US',
+  paymentMethod: 'pp_card',
+  cardNumber: '',
+  expiryDate: '',
+  cvv: '',
+  cardName: '',
+  saveInfo: false,
+  sameAsBilling: true,
+  newsletter: false,
+  promoCode: '',
+}
+
+const cardMethod: PaymentMethod = {
+  id: 'pp_card',
+  name: 'Tarjeta',
+  type: 'card',
+  isEnabled: true,
+  requiresSetup: true,
+  description: 'Paga con tarjeta',
+}
+
+const manualMethod: PaymentMethod = {
+  id: 'pp_system_default',
+  name: 'Pago manual TEST',
+  type: 'cash_on_delivery',
+  isEnabled: true,
+  requiresSetup: false,
+  description: 'Pago de prueba, sin tarjeta',
+}
+
+const noop = () => {}
+
+const formatMoney = (money: { amount: string; currencyCode: string }) =>
+  `${money.currencyCode} ${money.amount}`
+
+describe('CheckoutForm1 payment step — launch flow collects no raw card data', () => {
+  it('renders no card fields by default even for a card-type method', () => {
+    const html = renderToStaticMarkup(
+      <CheckoutForm1PaymentStep
+        formData={formData}
+        onChange={noop}
+        onCardNumberChange={noop}
+        onExpiryChange={noop}
+        paymentMethods={[cardMethod]}
+      />,
+    )
+    expect(html).not.toContain('checkout-card-number')
+    expect(html).not.toContain('checkout-cvv')
+    expect(html).toContain('Paga con tarjeta')
+  })
+
+  it('renders the approved manual TEST provider label only', () => {
+    const html = renderToStaticMarkup(
+      <CheckoutForm1PaymentStep
+        formData={{ ...formData, paymentMethod: 'pp_system_default' }}
+        onChange={noop}
+        onCardNumberChange={noop}
+        onExpiryChange={noop}
+        paymentMethods={[manualMethod]}
+      />,
+    )
+    expect(html).toContain('Pago manual TEST')
+    expect(html).toContain('Pago de prueba, sin tarjeta')
+    expect(html).not.toContain('checkout-card-number')
+  })
+
+  it('renders card fields only in the explicit legacy mode', () => {
+    const html = renderToStaticMarkup(
+      <CheckoutForm1PaymentStep
+        formData={formData}
+        onChange={noop}
+        onCardNumberChange={noop}
+        onExpiryChange={noop}
+        paymentMethods={[cardMethod]}
+        collectCardFields
+      />,
+    )
+    expect(html).toContain('checkout-card-number')
+    expect(html).toContain('checkout-cvv')
+  })
+})
+
+describe('CheckoutForm1 shipping step — controlled eligible options', () => {
+  it('renders only the supplied eligible shipping options with their prices', () => {
+    const html = renderToStaticMarkup(
+      <CheckoutForm1ShippingStep
+        formData={formData}
+        onChange={noop}
+        countries={[{ value: 'US', label: 'Estados Unidos' }]}
+        shippingOptions={[
+          { id: 'sm_std', name: 'Estándar', price: { amount: '5.00', currencyCode: 'USD' } },
+          { id: 'sm_exp', name: 'Exprés', price: { amount: '15.00', currencyCode: 'USD' } },
+        ]}
+        selectedShippingOptionId='sm_exp'
+        onSelectShippingOption={noop}
+        formatMoney={formatMoney}
+      />,
+    )
+    expect(html).toContain('Estándar')
+    expect(html).toContain('Exprés')
+    expect(html).toContain('USD 5.00')
+    expect(html).toContain('USD 15.00')
+  })
+
+  it('renders no shipping section when no options are supplied', () => {
+    const html = renderToStaticMarkup(
+      <CheckoutForm1ShippingStep formData={formData} onChange={noop} />,
+    )
+    expect(html).not.toContain('Shipping method')
+  })
+})
+
+describe('CheckoutForm1 order summary — authoritative totals and states', () => {
+  const items = [
+    {
+      id: 'line_1',
+      name: 'Taladro',
+      variant: 'Rojo',
+      quantity: 2,
+      lineTotal: { amount: '90.00', currencyCode: 'USD' },
+    },
+  ]
+
+  it('renders backend-authoritative totals verbatim', () => {
+    const html = renderToStaticMarkup(
+      <CheckoutForm1OrderSummary
+        orderSummary={{
+          items,
+          totals: {
+            subtotal: { amount: '90.00', currencyCode: 'USD' },
+            tax: { amount: '7.20', currencyCode: 'USD' },
+            shipping: { amount: '5.00', currencyCode: 'USD' },
+            total: { amount: '102.20', currencyCode: 'USD' },
+          },
+        }}
+        formatMoney={formatMoney}
+      />,
+    )
+    expect(html).toContain('USD 90.00')
+    expect(html).toContain('USD 7.20')
+    expect(html).toContain('USD 5.00')
+    expect(html).toContain('USD 102.20')
+    expect(html).not.toContain('Free shipping on orders over')
+  })
+
+  it('renders a controlled pending state without inventing amounts', () => {
+    const html = renderToStaticMarkup(
+      <CheckoutForm1OrderSummary orderSummary={{ items }} totalsState='pending' />,
+    )
+    expect(html).toContain('Actualizando totales')
+    expect(html).not.toContain('Total')
+  })
+
+  it('never renders a fake zero for absent or malformed required totals', () => {
+    const html = renderToStaticMarkup(
+      <CheckoutForm1OrderSummary
+        orderSummary={{
+          items,
+          totals: {
+            subtotal: { amount: '', currencyCode: 'USD' },
+            total: { amount: 'abc', currencyCode: 'USD' },
+          },
+        }}
+        formatMoney={formatMoney}
+      />,
+    )
+    expect(html).not.toContain('USD 0')
+    expect(html).toContain('Totales no disponibles')
+  })
+
+  it('preserves a legitimate zero total', () => {
+    const html = renderToStaticMarkup(
+      <CheckoutForm1OrderSummary
+        orderSummary={{
+          items,
+          totals: {
+            subtotal: { amount: '0', currencyCode: 'USD' },
+            total: { amount: '0', currencyCode: 'USD' },
+          },
+        }}
+        formatMoney={formatMoney}
+      />,
+    )
+    expect(html).toContain('USD 0')
+    expect(html).not.toContain('Totales no disponibles')
+  })
+
+  it('renders a controlled error state with a recovery action', () => {
+    const html = renderToStaticMarkup(
+      <CheckoutForm1OrderSummary
+        orderSummary={{ items }}
+        totalsState='error'
+        onRetryTotals={noop}
+      />,
+    )
+    expect(html).toContain('No se pudieron actualizar los totales')
+    expect(html).toContain('Reintentar')
+  })
+})

package/src/blocks/e-commerce/checkout-forms/checkout-form-1.tsx

@@ -11,7 +11,7 @@ import { CheckoutForm1PaymentStep } from './checkout-form-1-payment-step'
 import { CheckoutForm1OrderSummary } from './checkout-form-1-order-summary'
 import { CheckoutForm1Progress } from './checkout-form-1-progress'
 import { formatCardNumber, formatExpiryDate } from './card-formatting'
-import type { PaymentMethod } from '@thorprovider/types'
+import type { Money, PaymentMethod } from '@thorprovider/types'
 import type { CheckoutFieldErrors } from './checkout-form-types'
 
 export interface CheckoutForm1FormData {
@@ -44,17 +44,37 @@ export type CheckoutForm1FieldDescriptions = Partial<
 export interface CheckoutForm1OrderSummaryItem {
   id: string | number
   name: string
-  variant: string
-  price: number
+  variant?: string
   quantity: number
-  image: string
+  /** Canonical backend line total; preferred over `price * quantity`. */
+  lineTotal?: Money
+  /** @deprecated legacy numeric price, used only when `lineTotal` is absent. */
+  price?: number
+  /** Optional; an absent image is omitted rather than serialized as `""`. */
+  image?: string
 }
 
+export interface CheckoutForm1Totals {
+  subtotal: Money
+  discount?: Money
+  tax?: Money
+  shipping?: Money
+  total: Money
+}
+
+export type CheckoutForm1TotalsState = 'idle' | 'pending' | 'error'
+
 export interface CheckoutForm1OrderSummary {
   items: CheckoutForm1OrderSummaryItem[]
-  shipping: number
-  tax: number
+  /** Backend-authoritative totals; rendered verbatim when present. */
+  totals?: CheckoutForm1Totals
+  /** @deprecated legacy numeric amounts, used only when `totals` is absent. */
+  shipping?: number
+  /** @deprecated */
+  tax?: number
+  /** @deprecated */
   discount?: number
+  /** @deprecated */
   promoDiscount?: number
 }
 
@@ -63,6 +83,15 @@ export interface CheckoutForm1CountryOption {
   label: string
 }
 
+export interface CheckoutForm1ShippingOption {
+  /** Backend shipping method id — the controlled selection identity. */
+  id: string
+  name: string
+  price?: Money
+  description?: string
+  estimatedDays?: string
+}
+
 export type CheckoutForm1ChangeHandler = (
   field: keyof CheckoutForm1FormData,
   value: string | boolean
@@ -78,11 +107,35 @@ export interface CheckoutForm1Props {
   title?: string
   description?: string
   orderSummary?: CheckoutForm1OrderSummary
+  /** Controlled state of the totals fetch/mutation. */
+  totalsState?: CheckoutForm1TotalsState
+  totalsErrorLabel?: string
+  retryLabel?: string
+  onRetryTotals?: () => void
   countries?: CheckoutForm1CountryOption[]
+  /** Eligible shipping options for the cart's region/address. */
+  shippingOptions?: CheckoutForm1ShippingOption[]
+  /** Controlled selection of a shipping option id. */
+  selectedShippingOptionId?: string
+  onSelectShippingOption?: (id: string) => void
   paymentMethods?: PaymentMethod[]
   noPaymentMethodsLabel?: string
+  /** Override money formatting (locale, currency). Defaults to `Money.currencyCode`. */
+  formatMoney?: (money: Money) => string
+  /**
+   * Raw card fields are legacy-only and never collected in the launch flow.
+   * Defaults to `false`: the curated surface renders no card inputs.
+   */
+  collectCardFields?: boolean
+  onApplyPromo?: (code: string) => void
+  promoPending?: boolean
+  promoApplyLabel?: string
+  promoPlaceholder?: string
+  /** Optional trust copy; rendered only when supplied (never fabricated). */
+  trustNotes?: string[]
   backLabel?: string
   completeOrderLabel?: string
+  processingLabel?: string
   continueLabel?: string
   values: CheckoutForm1FormData
   onChange: CheckoutForm1ChangeHandler
@@ -94,17 +147,35 @@ export interface CheckoutForm1Props {
   submitting?: boolean
   /** Order-level error surfaced above the footer actions. */
   submitError?: string
+  /** Optional recovery action for a failed submission. */
+  onRetrySubmit?: () => void
+  submitErrorActionLabel?: string
 }
 
 export default function CheckoutForm1({
   title,
   description,
   orderSummary,
+  totalsState = 'idle',
+  totalsErrorLabel,
+  retryLabel,
+  onRetryTotals,
   countries,
+  shippingOptions,
+  selectedShippingOptionId,
+  onSelectShippingOption,
   paymentMethods,
   noPaymentMethodsLabel,
+  formatMoney,
+  collectCardFields = false,
+  onApplyPromo,
+  promoPending = false,
+  promoApplyLabel,
+  promoPlaceholder,
+  trustNotes,
   backLabel = 'Atrás',
   completeOrderLabel = 'Completar pedido',
+  processingLabel = 'Procesando pedido…',
   continueLabel = 'Continuar',
   values,
   onChange,
@@ -114,6 +185,8 @@ export default function CheckoutForm1({
   onSubmit,
   submitting = false,
   submitError,
+  onRetrySubmit,
+  submitErrorActionLabel = 'Reintentar',
 }: CheckoutForm1Props) {
   const [step, setStep] = useState(1)
 
@@ -175,6 +248,10 @@ export default function CheckoutForm1({
                 formData={values}
                 onChange={onChange}
                 countries={countries}
+                shippingOptions={shippingOptions}
+                selectedShippingOptionId={selectedShippingOptionId}
+                onSelectShippingOption={onSelectShippingOption}
+                formatMoney={formatMoney}
                 fieldErrors={fieldErrors}
                 fieldDescriptions={fieldDescriptions}
               />
@@ -187,6 +264,7 @@ export default function CheckoutForm1({
                 onExpiryChange={handleExpiryChange}
                 paymentMethods={paymentMethods}
                 noPaymentMethodsLabel={noPaymentMethodsLabel}
+                collectCardFields={collectCardFields}
                 fieldErrors={fieldErrors}
                 fieldDescriptions={fieldDescriptions}
               />
@@ -195,9 +273,20 @@ export default function CheckoutForm1({
             {submitError && (
               <div
                 role="alert"
-                className="mt-6 rounded-md border border-destructive/50 bg-destructive/10 px-4 py-3 text-sm text-destructive"
+                className="mt-6 flex flex-wrap items-center justify-between gap-3 rounded-md border border-destructive/50 bg-destructive/10 px-4 py-3 text-sm text-destructive"
               >
-                {submitError}
+                <span>{submitError}</span>
+                {onRetrySubmit ? (
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="sm"
+                    onClick={onRetrySubmit}
+                    disabled={submitting}
+                  >
+                    {submitErrorActionLabel}
+                  </Button>
+                ) : null}
               </div>
             )}
 
@@ -213,7 +302,7 @@ export default function CheckoutForm1({
               {isLastStep ? (
                 <Button type="button" onClick={handleSubmit} disabled={submitting}>
                   <Lock className="size-4" />
-                  {submitting ? 'Procesando pedido…' : completeOrderLabel}
+                  {submitting ? processingLabel : completeOrderLabel}
                 </Button>
               ) : (
                 <Button type="button" onClick={handleContinue} disabled={submitting}>
@@ -226,10 +315,24 @@ export default function CheckoutForm1({
 
         {orderSummary && (
           <div className="lg:col-span-1">
-            <CheckoutForm1OrderSummary orderSummary={orderSummary} />
+            <CheckoutForm1OrderSummary
+              orderSummary={orderSummary}
+              totalsState={totalsState}
+              totalsErrorLabel={totalsErrorLabel}
+              retryLabel={retryLabel}
+              onRetryTotals={onRetryTotals}
+              promoCode={values.promoCode}
+              onPromoCodeChange={(value) => onChange('promoCode', value)}
+              onApplyPromo={onApplyPromo}
+              promoPending={promoPending}
+              promoApplyLabel={promoApplyLabel}
+              promoPlaceholder={promoPlaceholder}
+              trustNotes={trustNotes}
+              formatMoney={formatMoney}
+            />
           </div>
         )}
       </div>
     </div>
   )
-}
+}

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