@thorprovider/blocks 1.0.0 → 2.0.0

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

@@ -0,0 +1,550 @@
+'use client'
+
+import { useEffect, useRef, useState } from 'react'
+import { Lock } from 'lucide-react'
+import { Button } from '../../../ui/button'
+import { Card, CardContent } from '../../../ui/card'
+import { cn } from '../../../lib/utils'
+import { CheckoutContactStep } from './checkout-contact-step'
+import { CheckoutShippingStep } from './checkout-shipping-step'
+import { CheckoutPaymentStep } from './checkout-payment-step'
+import { CheckoutReviewStep } from './checkout-review-step'
+import { CheckoutOrderSummaryPanel } from './checkout-order-summary'
+import { CheckoutProgress } from './checkout-progress'
+import type { Money, PaymentMethod } from '@thorprovider/types'
+import type { CheckoutFieldErrors as GenericCheckoutFieldErrors } from './checkout-form-types'
+
+/**
+ * The canonical checkout is a page-level unit. The host owns the commercial
+ * state (values, selections, totals, submission); the block owns only the
+ * ephemeral step index of the `stepper` presentation.
+ */
+export type CheckoutPresentation = 'single-page' | 'stepper'
+
+export type CheckoutStepId = 'contact' | 'shipping' | 'payment' | 'review'
+
+/** Flat, controlled form values. No card data: payment entry belongs to the host provider surface. */
+export interface CheckoutValues {
+  email: string
+  firstName: string
+  lastName: string
+  phone: string
+  address: string
+  city: string
+  state: string
+  zipCode: string
+  country: string
+  paymentMethod: string
+  saveInfo: boolean
+  newsletter: boolean
+  promoCode: string
+}
+
+export type CheckoutValuesFieldErrors = GenericCheckoutFieldErrors<keyof CheckoutValues>
+
+export type CheckoutFieldDescriptions = Partial<Record<keyof CheckoutValues, string>>
+
+export interface CheckoutOrderLine {
+  /** Backend line identity — the stable React key. */
+  id: string | number
+  name: string
+  variant?: string
+  quantity: number
+  /** Backend-authoritative line total; rendered verbatim. */
+  lineTotal?: Money
+  /** Optional unit price shown as secondary text; never multiplied. */
+  unitPrice?: Money
+  /** Optional; an absent image is omitted rather than serialized as `""`. */
+  image?: string
+}
+
+export interface CheckoutTotals {
+  subtotal: Money
+  discount?: Money
+  tax?: Money
+  shipping?: Money
+  total: Money
+}
+
+export interface CheckoutOrderSummary {
+  items: CheckoutOrderLine[]
+  /** Backend-authoritative totals; rendered verbatim. */
+  totals?: CheckoutTotals
+}
+
+export type CheckoutTotalsState = 'idle' | 'pending' | 'error'
+
+export interface CheckoutCountryOption {
+  value: string
+  label: string
+}
+
+export interface CheckoutShippingOption {
+  /** Backend shipping method id — the controlled selection identity. */
+  id: string
+  name: string
+  price?: Money
+  description?: string
+  estimatedDays?: string
+}
+
+export type CheckoutChangeHandler = (field: keyof CheckoutValues, value: string | boolean) => void
+
+/**
+ * Every user-facing string is overridable. Neutral English defaults ship with
+ * the block; the host supplies its own copy through this object.
+ */
+export interface CheckoutLabels {
+  title: string
+  description: string
+  orderSummaryTitle: string
+  stepProgressLabel: string
+  contactStepName: string
+  shippingStepName: string
+  paymentStepName: string
+  reviewStepName: string
+  contactHeading: string
+  contactDescription: string
+  shippingHeading: string
+  shippingDescription: string
+  paymentHeading: string
+  paymentDescription: string
+  reviewHeading: string
+  reviewDescription: string
+  emailLabel: string
+  firstNameLabel: string
+  lastNameLabel: string
+  phoneLabel: string
+  addressLabel: string
+  cityLabel: string
+  stateLabel: string
+  zipCodeLabel: string
+  countryLabel: string
+  countryPlaceholder: string
+  shippingMethodLegend: string
+  paymentMethodLegend: string
+  noPaymentMethodsLabel: string
+  unavailableMethodLabel: string
+  requiresSetupLabel: string
+  saveInfoLabel: string
+  newsletterLabel: string
+  promoCodeLabel: string
+  promoPlaceholder: string
+  promoApplyLabel: string
+  subtotalLabel: string
+  discountLabel: string
+  taxLabel: string
+  shippingLabel: string
+  totalLabel: string
+  eachLabel: string
+  totalsPendingLabel: string
+  totalsErrorLabel: string
+  totalsUnavailableLabel: string
+  amountUnavailableLabel: string
+  retryLabel: string
+  reviewContactLabel: string
+  reviewShipToLabel: string
+  reviewPaymentLabel: string
+  reviewShippingLabel: string
+  reviewEmptyLabel: string
+  backLabel: string
+  continueLabel: string
+  completeOrderLabel: string
+  processingLabel: string
+  submitErrorActionLabel: string
+}
+
+const DEFAULT_LABELS: CheckoutLabels = {
+  title: 'Checkout',
+  description: '',
+  orderSummaryTitle: 'Order summary',
+  stepProgressLabel: 'Checkout progress',
+  contactStepName: 'Contact',
+  shippingStepName: 'Shipping',
+  paymentStepName: 'Payment',
+  reviewStepName: 'Review',
+  contactHeading: 'Contact information',
+  contactDescription: 'We use these details to keep you informed about your order.',
+  shippingHeading: 'Shipping address',
+  shippingDescription: 'Tell us where the order should be delivered.',
+  paymentHeading: 'Payment',
+  paymentDescription: 'Choose how you want to pay for this order.',
+  reviewHeading: 'Review your order',
+  reviewDescription: 'Check the details below before placing the order.',
+  emailLabel: 'Email',
+  firstNameLabel: 'First name',
+  lastNameLabel: 'Last name',
+  phoneLabel: 'Phone (optional)',
+  addressLabel: 'Street address',
+  cityLabel: 'City',
+  stateLabel: 'State / Province',
+  zipCodeLabel: 'ZIP / Postal code',
+  countryLabel: 'Country',
+  countryPlaceholder: 'Select a country',
+  shippingMethodLegend: 'Shipping method',
+  paymentMethodLegend: 'Payment method',
+  noPaymentMethodsLabel: 'No payment methods are available for this region.',
+  unavailableMethodLabel: 'Unavailable',
+  requiresSetupLabel: 'Requires additional setup',
+  saveInfoLabel: 'Save this information for next time',
+  newsletterLabel: 'Email me about news and offers',
+  promoCodeLabel: 'Promotional code',
+  promoPlaceholder: 'Enter the code',
+  promoApplyLabel: 'Apply',
+  subtotalLabel: 'Subtotal',
+  discountLabel: 'Discount',
+  taxLabel: 'Tax',
+  shippingLabel: 'Shipping',
+  totalLabel: 'Total',
+  eachLabel: 'each',
+  totalsPendingLabel: 'Updating totals…',
+  totalsErrorLabel: 'We could not update the order totals.',
+  totalsUnavailableLabel: 'Totals are unavailable.',
+  amountUnavailableLabel: '—',
+  retryLabel: 'Retry',
+  reviewContactLabel: 'Contact',
+  reviewShipToLabel: 'Ship to',
+  reviewPaymentLabel: 'Payment',
+  reviewShippingLabel: 'Shipping method',
+  reviewEmptyLabel: 'No details provided yet.',
+  backLabel: 'Back',
+  continueLabel: 'Continue',
+  completeOrderLabel: 'Place order',
+  processingLabel: 'Placing order…',
+  submitErrorActionLabel: 'Try again',
+}
+
+const BASE_STEPS: CheckoutStepId[] = ['contact', 'shipping', 'payment']
+
+const STEP_COPY: Record<
+  CheckoutStepId,
+  { name: keyof CheckoutLabels; heading: keyof CheckoutLabels; description: keyof CheckoutLabels }
+> = {
+  contact: {
+    name: 'contactStepName',
+    heading: 'contactHeading',
+    description: 'contactDescription',
+  },
+  shipping: {
+    name: 'shippingStepName',
+    heading: 'shippingHeading',
+    description: 'shippingDescription',
+  },
+  payment: {
+    name: 'paymentStepName',
+    heading: 'paymentHeading',
+    description: 'paymentDescription',
+  },
+  review: {
+    name: 'reviewStepName',
+    heading: 'reviewHeading',
+    description: 'reviewDescription',
+  },
+}
+
+export interface CheckoutProps {
+  presentation: CheckoutPresentation
+  /** Appends a confirmation step (`stepper`) or section (`single-page`) before submission. */
+  showReviewStep?: boolean
+  values: CheckoutValues
+  onChange: CheckoutChangeHandler
+  orderSummary?: CheckoutOrderSummary
+  totalsState?: CheckoutTotalsState
+  onRetryTotals?: () => void
+  countries?: CheckoutCountryOption[]
+  shippingOptions?: CheckoutShippingOption[]
+  selectedShippingOptionId?: string
+  onSelectShippingOption?: (id: string) => void
+  paymentMethods?: PaymentMethod[]
+  onApplyPromo?: (code: string) => void
+  promoPending?: boolean
+  /** Optional trust copy; rendered only when supplied. */
+  trustNotes?: string[]
+  labels?: Partial<CheckoutLabels>
+  /** Override money formatting (locale, currency). Defaults to `Money.currencyCode`. */
+  formatMoney?: (money: Money) => string
+  fieldErrors?: CheckoutValuesFieldErrors
+  fieldDescriptions?: CheckoutFieldDescriptions
+  /** Consulted before advancing and for every applicable step before submitting. */
+  validateStep?: (step: CheckoutStepId) => boolean
+  /** Notification only — never an authoritative controlled value. */
+  onStepChange?: (step: CheckoutStepId) => void
+  onSubmit?: (values: CheckoutValues) => void
+  submitting?: boolean
+  submitError?: string
+  onRetrySubmit?: () => void
+}
+
+export function Checkout({
+  presentation,
+  showReviewStep = false,
+  values,
+  onChange,
+  orderSummary,
+  totalsState = 'idle',
+  onRetryTotals,
+  countries,
+  shippingOptions,
+  selectedShippingOptionId,
+  onSelectShippingOption,
+  paymentMethods = [],
+  onApplyPromo,
+  promoPending = false,
+  trustNotes,
+  labels,
+  formatMoney,
+  fieldErrors,
+  fieldDescriptions,
+  validateStep,
+  onStepChange,
+  onSubmit,
+  submitting = false,
+  submitError,
+  onRetrySubmit,
+}: CheckoutProps) {
+  const resolved: CheckoutLabels = { ...DEFAULT_LABELS, ...labels }
+  const steps = showReviewStep ? [...BASE_STEPS, 'review' as const] : BASE_STEPS
+  const [stepIndex, setStepIndex] = useState(0)
+  const activeStep = steps[Math.min(stepIndex, steps.length - 1)]
+
+  const headingRef = useRef<HTMLHeadingElement>(null)
+  const hasMounted = useRef(false)
+
+  useEffect(() => {
+    if (presentation !== 'stepper') return
+    if (!hasMounted.current) {
+      hasMounted.current = true
+      return
+    }
+    headingRef.current?.focus()
+  }, [presentation, activeStep])
+
+  const moveTo = (nextIndex: number) => {
+    const next = steps[nextIndex]
+    if (!next) return
+    setStepIndex(nextIndex)
+    onStepChange?.(next)
+  }
+
+  const handleContinue = () => {
+    if (validateStep && !validateStep(activeStep)) return
+    moveTo(stepIndex + 1)
+  }
+
+  const handleBack = () => {
+    if (stepIndex === 0) return
+    moveTo(stepIndex - 1)
+  }
+
+  const handleSubmit = () => {
+    if (submitting) return
+    if (validateStep && !steps.every((step) => validateStep(step))) return
+    onSubmit?.(values)
+  }
+
+  const renderStep = (step: CheckoutStepId) => {
+    switch (step) {
+      case 'contact':
+        return (
+          <CheckoutContactStep
+            values={values}
+            onChange={onChange}
+            labels={resolved}
+            showSaveInfo={labels?.saveInfoLabel !== undefined}
+            showNewsletter={labels?.newsletterLabel !== undefined}
+            fieldErrors={fieldErrors}
+            fieldDescriptions={fieldDescriptions}
+          />
+        )
+      case 'shipping':
+        return (
+          <CheckoutShippingStep
+            values={values}
+            onChange={onChange}
+            labels={resolved}
+            countries={countries}
+            shippingOptions={shippingOptions}
+            selectedShippingOptionId={selectedShippingOptionId}
+            onSelectShippingOption={onSelectShippingOption}
+            formatMoney={formatMoney}
+            fieldErrors={fieldErrors}
+            fieldDescriptions={fieldDescriptions}
+          />
+        )
+      case 'payment':
+        return (
+          <CheckoutPaymentStep
+            values={values}
+            onChange={onChange}
+            labels={resolved}
+            paymentMethods={paymentMethods}
+            fieldErrors={fieldErrors}
+            fieldDescriptions={fieldDescriptions}
+          />
+        )
+      case 'review':
+        return (
+          <CheckoutReviewStep
+            values={values}
+            labels={resolved}
+            selectedShippingOptionId={selectedShippingOptionId}
+            shippingOptions={shippingOptions}
+            paymentMethods={paymentMethods}
+          />
+        )
+    }
+  }
+
+  const isLastStep = stepIndex === steps.length - 1
+
+  const submitAction = (
+    <Button type="button" onClick={handleSubmit} disabled={submitting}>
+      <Lock className="size-4" />
+      {submitting ? resolved.processingLabel : resolved.completeOrderLabel}
+    </Button>
+  )
+
+  const submitErrorNode = submitError ? (
+    <div
+      role="alert"
+      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"
+    >
+      <span>{submitError}</span>
+      {onRetrySubmit ? (
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          onClick={onRetrySubmit}
+          disabled={submitting}
+        >
+          {resolved.submitErrorActionLabel}
+        </Button>
+      ) : null}
+    </div>
+  ) : null
+
+  const summaryNode = orderSummary ? (
+    <div
+      className={cn(
+        'min-w-0 lg:col-span-1',
+        presentation === 'single-page' && 'lg:order-last',
+      )}
+    >
+      <CheckoutOrderSummaryPanel
+        summary={orderSummary}
+        labels={resolved}
+        totalsState={totalsState}
+        onRetryTotals={onRetryTotals}
+        promoCode={values.promoCode}
+        onPromoCodeChange={(value) => onChange('promoCode', value)}
+        onApplyPromo={onApplyPromo}
+        promoPending={promoPending}
+        trustNotes={trustNotes}
+        formatMoney={formatMoney}
+      />
+    </div>
+  ) : null
+
+  return (
+    <div className="mx-auto max-w-6xl px-4 py-12 sm:px-6 lg:px-8">
+      {(resolved.title || resolved.description) && (
+        <header className="mb-8 text-center">
+          {resolved.title ? (
+            <h1 className="text-3xl font-bold tracking-tight sm:text-4xl">{resolved.title}</h1>
+          ) : null}
+          {resolved.description ? (
+            <p className="mt-2 text-muted-foreground">{resolved.description}</p>
+          ) : null}
+        </header>
+      )}
+
+      {presentation === 'stepper' ? (
+        <CheckoutProgress
+          steps={steps.map((step) => ({
+            id: step,
+            label: resolved[STEP_COPY[step].name],
+          }))}
+          currentStep={activeStep}
+          ariaLabel={resolved.stepProgressLabel}
+        />
+      ) : null}
+
+      <div className={cn('mt-8 grid grid-cols-1 gap-6', orderSummary && 'lg:grid-cols-3')}>
+        {presentation === 'single-page' ? summaryNode : null}
+
+        <div className={cn('min-w-0', orderSummary ? 'lg:col-span-2' : 'lg:col-span-3')}>
+          <Card>
+            <CardContent className="p-6">
+              {presentation === 'stepper' ? (
+                <>
+                  <div className="mb-6">
+                    <h2 ref={headingRef} tabIndex={-1} className="text-lg font-semibold outline-none">
+                      {resolved[STEP_COPY[activeStep].heading]}
+                    </h2>
+                    <p className="text-sm text-muted-foreground">
+                      {resolved[STEP_COPY[activeStep].description]}
+                    </p>
+                  </div>
+
+                  {renderStep(activeStep)}
+                </>
+              ) : (
+                <div className="flex flex-col gap-8">
+                  {steps.map((step) => (
+                    <section key={step} className="flex flex-col gap-4">
+                      <div>
+                        <h2 className="text-lg font-semibold">
+                          {resolved[STEP_COPY[step].heading]}
+                        </h2>
+                        <p className="text-sm text-muted-foreground">
+                          {resolved[STEP_COPY[step].description]}
+                        </p>
+                      </div>
+                      {renderStep(step)}
+                    </section>
+                  ))}
+                </div>
+              )}
+
+              {submitErrorNode}
+
+              <div
+                className={cn(
+                  'mt-6 flex flex-wrap items-center gap-4',
+                  presentation === 'stepper' ? 'justify-between' : 'justify-end',
+                )}
+              >
+                {presentation === 'stepper' ? (
+                  <>
+                    <Button
+                      type="button"
+                      variant="outline"
+                      onClick={handleBack}
+                      disabled={stepIndex === 0 || submitting}
+                    >
+                      {resolved.backLabel}
+                    </Button>
+                    {isLastStep ? (
+                      submitAction
+                    ) : (
+                      <Button type="button" onClick={handleContinue} disabled={submitting}>
+                        {resolved.continueLabel}
+                      </Button>
+                    )}
+                  </>
+                ) : (
+                  submitAction
+                )}
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+
+        {presentation === 'stepper' ? summaryNode : null}
+      </div>
+    </div>
+  )
+}
+
+export default Checkout

package/src/blocks/{marketing/navbars/navbar-4-account-menu.test.tsx → e-commerce/navigation/storefront-navbar-account-menu.test.tsx}

@@ -1,7 +1,7 @@
 import { Children, isValidElement, type ReactNode } from 'react'
 import { renderToStaticMarkup } from 'react-dom/server'
 import { describe, expect, it, vi } from 'vitest'
-import { Navbar4AccountMenu } from './navbar-4-account-menu'
+import { StorefrontNavbarAccountMenu } from './storefront-navbar-account-menu'
 import { DropdownMenuItem } from '../../../ui/dropdown-menu'
 
 // Inspect the block-owned menu items without mounting Radix's browser portal.
@@ -17,36 +17,36 @@ function menuItems(node: ReactNode): Record<string, unknown>[] {
 
 const user = { name: 'Ada', email: 'ada@example.test', initials: 'A' }
 
-describe('Navbar4AccountMenu absent avatar', () => {
+describe('StorefrontNavbarAccountMenu absent avatar', () => {
   it('renders the fallback initials, never an empty image source, when avatar is absent', () => {
-    const html = renderToStaticMarkup(<Navbar4AccountMenu user={user} />)
+    const html = renderToStaticMarkup(<StorefrontNavbarAccountMenu user={user} />)
     expect(html).toContain('>A<')
     expect(html).not.toContain('src=""')
     expect(html).not.toContain('<img')
   })
 
   it('treats an empty avatar string as absent rather than an empty source', () => {
-    const html = renderToStaticMarkup(<Navbar4AccountMenu user={{ ...user, avatar: '' }} />)
+    const html = renderToStaticMarkup(<StorefrontNavbarAccountMenu user={{ ...user, avatar: '' }} />)
     expect(html).toContain('>A<')
     expect(html).not.toContain('src=""')
   })
 })
 
-describe('Navbar4AccountMenu consumer actions', () => {
+describe('StorefrontNavbarAccountMenu consumer actions', () => {
   it('omits help and sign-out when no consumer actions exist', () => {
-    expect(menuItems(Navbar4AccountMenu({ user }))).toEqual([])
+    expect(menuItems(StorefrontNavbarAccountMenu({ user }))).toEqual([])
   })
 
   it('dispatches sign-out to its consumer', () => {
     const onSignOut = vi.fn()
-    const [item] = menuItems(Navbar4AccountMenu({ user, onSignOut }))
+    const [item] = menuItems(StorefrontNavbarAccountMenu({ user, onSignOut }))
     ;(item.onSelect as () => void)()
     expect(onSignOut).toHaveBeenCalledTimes(1)
   })
 
   it('prevents duplicate sign-out while the consumer reports the logout pending', () => {
     const onSignOut = vi.fn()
-    const [item] = menuItems(Navbar4AccountMenu({ user, pending: true, onSignOut }))
+    const [item] = menuItems(StorefrontNavbarAccountMenu({ user, pending: true, onSignOut }))
     expect(item.disabled).toBe(true)
     const select = item.onSelect as () => void
     select()

package/src/blocks/{marketing/navbars/navbar-4-account-menu.tsx → e-commerce/navigation/storefront-navbar-account-menu.tsx}

@@ -26,7 +26,7 @@ export interface AccountMenuItem {
   icon?: 'orders' | 'wishlist' | 'addresses' | 'settings'
 }
 
-export interface Navbar4AccountMenuProps {
+export interface StorefrontNavbarAccountMenuProps {
   /** Signed-in user. When omitted, the menu is not rendered. */
   user?: StoreUser
   /** Account links shown below the user header. Defaults to `[]`. */
@@ -43,13 +43,13 @@ const accountIcons = {
   settings: Settings,
 } as const
 
-export function Navbar4AccountMenu({
+export function StorefrontNavbarAccountMenu({
   user,
   items = [],
   onHelp,
   onSignOut,
   pending = false,
-}: Navbar4AccountMenuProps) {
+}: StorefrontNavbarAccountMenuProps) {
   if (!user) {
     return null
   }