@thorprovider/blocks 0.1.1 → 0.1.3

package/src/lib/contracts-curated.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, it } from 'vitest'
+import {
+  brandAccentSchema,
+  cartItemSchema,
+  ctaSchema,
+  ctaSection1PropsSchema,
+  faqBlock1PropsSchema,
+  faqItemSchema,
+  heroImageSchema,
+  logoAccentSchema,
+  moneySchema,
+  navCartItemSchema,
+  navbar4PropsSchema,
+  productOverview1PropsSchema,
+  shoppingCart4PropsSchema,
+} from './contracts'
+
+const product = {
+  id: 'p1',
+  title: 'Taladro',
+  options: [{ id: 'o1', name: 'Color', values: ['Rojo'] }],
+  variants: [
+    {
+      id: 'v1',
+      title: 'Rojo',
+      availableForSale: true,
+      selectedOptions: [{ name: 'Color', value: 'Rojo' }],
+      price: { amount: '69.99', currencyCode: 'USD' },
+    },
+    {
+      id: 'v2',
+      title: 'Gris',
+      availableForSale: true,
+      selectedOptions: [{ name: 'Color', value: 'Gris' }],
+      price: null,
+    },
+  ],
+  images: [],
+}
+
+describe('moneySchema', () => {
+  it('accepts canonical Money in major units', () => {
+    expect(moneySchema.parse({ amount: '69.99', currencyCode: 'USD' })).toEqual({
+      amount: '69.99',
+      currencyCode: 'USD',
+    })
+  })
+
+  it('rejects a missing amount', () => {
+    expect(moneySchema.safeParse({ currencyCode: 'USD' }).success).toBe(false)
+  })
+
+  it('accepts the unresolved amount sentinel "" so a whole view is not rejected', () => {
+    expect(moneySchema.safeParse({ amount: '', currencyCode: 'USD' }).success).toBe(true)
+  })
+})
+
+describe('productOverview1PropsSchema', () => {
+  it('accepts a product whose variant price is omitted or null (unavailable)', () => {
+    expect(productOverview1PropsSchema.safeParse({ product }).success).toBe(true)
+  })
+
+  it('accepts an explicit controlled selected variant id', () => {
+    expect(productOverview1PropsSchema.safeParse({ product, selectedVariantId: 'v1' }).success).toBe(true)
+  })
+
+  it('rejects a variant missing selectedOptions', () => {
+    const bad = {
+      ...product,
+      variants: [{ id: 'v1', title: 'x', availableForSale: true, price: null }],
+    }
+    expect(productOverview1PropsSchema.safeParse({ product: bad }).success).toBe(false)
+  })
+})
+
+describe('cart item schemas — absent images are omitted, never ""', () => {
+  it('accepts a nav cart line without an image', () => {
+    expect(navCartItemSchema.safeParse({ id: 'l1', name: 'x', price: 1, qty: 1 }).success).toBe(true)
+  })
+
+  it('accepts a cart line without an image and with canonical money line totals', () => {
+    const result = cartItemSchema.safeParse({
+      id: 'l1',
+      name: 'x',
+      price: 1,
+      quantity: 1,
+      lineTotal: { amount: '1.00', currencyCode: 'USD' },
+    })
+    expect(result.success).toBe(true)
+  })
+})
+
+describe('optional brand seams — present, omitted, invalid', () => {
+  it('parses an accent with and without a className', () => {
+    expect(logoAccentSchema.parse({ text: 'Cuba' })).toEqual({ text: 'Cuba' })
+    expect(brandAccentSchema.parse({ text: 'Cuba', className: 'text-brand-promo' })).toEqual({
+      text: 'Cuba',
+      className: 'text-brand-promo',
+    })
+  })
+
+  it('parses an editorial hero image', () => {
+    expect(heroImageSchema.parse({ src: '/hero.png', alt: 'Taller' })).toEqual({
+      src: '/hero.png',
+      alt: 'Taller',
+    })
+  })
+
+  it('accepts navbar props with the accent omitted (backward compatible)', () => {
+    const base = {
+      storeCategories: [],
+      shippingNote: 'Catálogo en línea',
+      utilityLinks: [],
+      logoText: 'ElectroCuba',
+    }
+    const parsed = navbar4PropsSchema.parse(base)
+    expect(parsed.logoAccent).toBeUndefined()
+  })
+
+  it('accepts navbar props with the accent present', () => {
+    const parsed = navbar4PropsSchema.parse({
+      storeCategories: [],
+      shippingNote: 'Catálogo en línea',
+      utilityLinks: [],
+      logoText: 'ElectroCuba',
+      logoAccent: { text: 'Cuba', className: 'text-brand-promo' },
+    })
+    expect(parsed.logoAccent).toEqual({ text: 'Cuba', className: 'text-brand-promo' })
+  })
+
+  it('accepts navbar props with a surface className present or omitted', () => {
+    const base = {
+      storeCategories: [],
+      shippingNote: 'Catálogo en línea',
+      utilityLinks: [],
+      logoText: 'My Shop',
+    }
+    expect(navbar4PropsSchema.parse(base).className).toBeUndefined()
+    expect(navbar4PropsSchema.parse({ ...base, className: 'bg-brand-nav text-brand-nav-foreground' }).className).toBe(
+      'bg-brand-nav text-brand-nav-foreground',
+    )
+  })
+
+  it('rejects a malformed accent or hero image', () => {
+    expect(logoAccentSchema.safeParse({}).success).toBe(false)
+    expect(heroImageSchema.safeParse({ src: '/hero.png' }).success).toBe(false)
+  })
+})
+
+describe('shoppingCart4PropsSchema — authoritative totals', () => {
+  it('accepts backend totals and a controlled totals state', () => {
+    const result = shoppingCart4PropsSchema.safeParse({
+      items: [],
+      totals: {
+        subtotal: { amount: '0', currencyCode: 'USD' },
+        total: { amount: '0', currencyCode: 'USD' },
+      },
+      totalsState: 'idle',
+    })
+    expect(result.success).toBe(true)
+  })
+
+  it('rejects an unknown totals state', () => {
+    expect(shoppingCart4PropsSchema.safeParse({ items: [], totalsState: 'loading' }).success).toBe(false)
+  })
+})
+
+describe('faqBlock1PropsSchema / ctaSection1PropsSchema — bounded editorial sections', () => {
+  const faqItem = { value: 'q1', question: '¿Envían a todo el país?', answer: 'Sí.' }
+
+  it('parses a valid faq payload', () => {
+    expect(faqBlock1PropsSchema.safeParse({ items: [faqItem], title: 'Preguntas' }).success).toBe(true)
+  })
+
+  it('parses a valid cta payload with a link or a callback-bound button', () => {
+    expect(ctaSchema.parse({ label: 'Ir', href: '/productos' })).toEqual({ label: 'Ir', href: '/productos' })
+    expect(ctaSection1PropsSchema.safeParse({ title: 'Compra', primaryCta: { label: 'Ir', href: '/x' } }).success).toBe(
+      true,
+    )
+    expect(ctaSection1PropsSchema.safeParse({ primaryCta: { label: 'Ir' } }).success).toBe(true)
+  })
+
+  it('rejects an unknown accordionType', () => {
+    expect(faqBlock1PropsSchema.safeParse({ items: [faqItem], accordionType: 'always' }).success).toBe(false)
+  })
+
+  it('rejects missing required items and item fields', () => {
+    expect(faqBlock1PropsSchema.safeParse({}).success).toBe(false)
+    expect(faqItemSchema.safeParse({ value: 'q1', question: '¿Envían?' }).success).toBe(false)
+    expect(faqItemSchema.safeParse({ question: '¿Envían?', answer: 'Sí.' }).success).toBe(false)
+  })
+
+  it('allows optional fields to be omitted', () => {
+    const faq = faqBlock1PropsSchema.parse({ items: [faqItem] })
+    expect(faq.title).toBeUndefined()
+    expect(faq.description).toBeUndefined()
+    expect(faq.accordionType).toBeUndefined()
+    const cta = ctaSection1PropsSchema.parse({})
+    expect(cta.badgeText).toBeUndefined()
+    expect(cta.primaryCta).toBeUndefined()
+  })
+
+  it('ignores React-only callbacks — they are not part of the serializable contract', () => {
+    const parsed = ctaSection1PropsSchema.parse({ title: 'X', onPrimaryClick: () => {} })
+    expect('onPrimaryClick' in parsed).toBe(false)
+  })
+})

package/src/lib/contracts-server-boundary.test.ts

@@ -0,0 +1,52 @@
+// Task 6.7: `use client` must apply only to the UI entrypoint, never to the
+// pure-Zod contracts entrypoint, so server code can import and compose schemas.
+// The tsup config previously applied a global `banner`, which leaked the
+// directive onto the contracts bundle; the fix moves it into the UI source.
+//
+// The server-importable *behavior* of the contracts entry is exercised in the
+// runtime catalog boundary test (`@thorprovider/runtime`), which imports
+// `@thorprovider/blocks/contracts` and calls `extend`/`parse` in a Node server
+// context. This test pins the directive placement and the build config.
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+
+function findPkgRoot(start: string): string {
+  let dir = start
+  while (dir !== dirname(dir)) {
+    const pkg = join(dir, 'package.json')
+    if (existsSync(pkg)) {
+      const parsed = JSON.parse(readFileSync(pkg, 'utf8'))
+      if (parsed.name === '@thorprovider/blocks') return dir
+    }
+    dir = dirname(dir)
+  }
+  throw new Error('@thorprovider/blocks package root not found')
+}
+
+const pkgRoot = findPkgRoot(process.cwd())
+const read = (...parts: string[]) => readFileSync(join(pkgRoot, ...parts), 'utf8')
+const USE_CLIENT = /^['"]use client['"]/
+
+describe('blocks entrypoint boundaries (6.7)', () => {
+  it('marks only the UI entrypoint as a client module', () => {
+    expect(USE_CLIENT.test(read('src', 'index.ts').trimStart())).toBe(true)
+    expect(USE_CLIENT.test(read('src', 'lib', 'contracts.ts').trimStart())).toBe(false)
+  })
+
+  it('has no global tsup banner that would leak use client onto contracts', () => {
+    expect(read('tsup.config.ts')).not.toMatch(/banner\s*:/)
+  })
+
+  it('builds a contracts bundle with no use client directive and a UI bundle with it', () => {
+    const distContracts = join(pkgRoot, 'dist', 'contracts.mjs')
+    const distIndex = join(pkgRoot, 'dist', 'index.mjs')
+    // dist/ is build output; validate it whenever a build has run.
+    if (existsSync(distContracts)) {
+      expect(USE_CLIENT.test(readFileSync(distContracts, 'utf8').trimStart())).toBe(false)
+    }
+    if (existsSync(distIndex)) {
+      expect(USE_CLIENT.test(readFileSync(distIndex, 'utf8').trimStart())).toBe(true)
+    }
+  })
+})

package/src/lib/contracts.ts

@@ -40,6 +40,81 @@ export const PRODUCT_IMAGE_FALLBACK =
 // Data contracts
 // ---------------------------------------------------------------------------
 
+/**
+ * Canonical `Money` (`@thorprovider/types`): a decimal string in major units
+ * (`"69.99"`), never cents. A missing price is represented by omitting the
+ * field (or `null` on a nullable field), not by an empty string.
+ *
+ * The amount stays a permissive `z.string()` on purpose: an unresolved backend
+ * price may arrive as the canonical sentinel `""`, and tightening the schema
+ * would reject the whole view instead of letting the presentation layer render
+ * an unavailable state. Validity is enforced at render time by
+ * `isAvailableMoney`/`formatMoney` (a `""`/malformed amount never becomes `$0`).
+ */
+export const moneySchema: z.ZodType<Money> = z.object({
+  amount: z.string(),
+  currencyCode: z.string(),
+})
+
+const imageSchema = z.object({
+  id: z.string().optional(),
+  url: z.string(),
+  altText: z.string(),
+  width: z.number().optional(),
+  height: z.number().optional(),
+})
+
+const selectedOptionSchema = z.object({
+  name: z.string(),
+  value: z.string(),
+})
+
+export const productDetailVariantSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  sku: z.string().optional(),
+  availableForSale: z.boolean(),
+  selectedOptions: z.array(selectedOptionSchema),
+  /** Omit or null when the backend has no resolved price (purchase disabled). */
+  price: moneySchema.nullish(),
+  compareAtPrice: moneySchema.optional(),
+  image: imageSchema.optional(),
+})
+export type ProductDetailVariantSpec = z.infer<typeof productDetailVariantSchema>
+
+export const productDetailProductSchema = z.object({
+  id: z.string(),
+  handle: z.string().optional(),
+  title: z.string(),
+  description: z.string().optional(),
+  vendor: z.string().optional(),
+  options: z.array(z.object({ id: z.string(), name: z.string(), values: z.array(z.string()) })),
+  variants: z.array(productDetailVariantSchema),
+  images: z.array(imageSchema),
+  featuredImage: imageSchema.optional(),
+})
+export type ProductDetailProductSpec = z.infer<typeof productDetailProductSchema>
+
+export const productOverview1PropsSchema = z.object({
+  product: productDetailProductSchema,
+  selectedVariantId: z.string().nullable().optional(),
+  quantity: z.number().optional(),
+  rating: z.object({ value: z.number(), count: z.number() }).optional(),
+  deliveryEstimate: z.string().optional(),
+  shipping: moneySchema.optional(),
+  sizesLabel: z.string().optional(),
+  variantLabel: z.string().optional(),
+  reviewsLabel: z.string().optional(),
+  addToCartLabel: z.string().optional(),
+  outOfStockLabel: z.string().optional(),
+  unavailablePriceLabel: z.string().optional(),
+  selectVariantLabel: z.string().optional(),
+  quantityLabel: z.string().optional(),
+  deliveryEstimateLabel: z.string().optional(),
+  shippingLabel: z.string().optional(),
+})
+export type ProductOverview1SpecProps = z.infer<typeof productOverview1PropsSchema>
+
 export const cardProductSchema = z.object({
   id: z.union([z.string(), z.number()]),
   title: z.string(),
@@ -55,11 +130,25 @@ export const cartItemSchema = z.object({
   name: z.string(),
   price: z.number(),
   quantity: z.number().int().min(0),
-  image: z.string(),
+  /** Optional; absent images are omitted, never serialized as `""`. */
+  image: z.string().optional(),
   variant: z.string().optional(),
+  /** Canonical backend per-unit price, preferred for display when present. */
+  unitPrice: moneySchema.optional(),
+  /** Canonical backend line total, preferred over `price * quantity`. */
+  lineTotal: moneySchema.optional(),
 })
 export type CartItem = z.infer<typeof cartItemSchema>
 
+export const cartTotalsSchema = z.object({
+  subtotal: moneySchema,
+  discount: moneySchema.optional(),
+  tax: moneySchema.optional(),
+  shipping: moneySchema.optional(),
+  total: moneySchema,
+})
+export type CartTotals = z.infer<typeof cartTotalsSchema>
+
 export const recentlyViewedItemSchema = z.object({
   id: z.string(),
   name: z.string(),
@@ -103,17 +192,18 @@ export type UtilityLink = z.infer<typeof utilityLinkSchema>
 export const navCartItemSchema = z.object({
   id: z.string(),
   name: z.string(),
-  variant: z.string(),
+  variant: z.string().optional(),
   price: z.number(),
   qty: z.number().int().min(0),
-  image: z.string(),
+  /** Optional; absent images are omitted, never serialized as `""`. */
+  image: z.string().optional(),
 })
 export type NavCartItem = z.infer<typeof navCartItemSchema>
 
 export const storeUserSchema = z.object({
   name: z.string(),
   email: z.string(),
-  avatar: z.string(),
+  avatar: z.string().optional(),
   initials: z.string(),
 })
 export type StoreUser = z.infer<typeof storeUserSchema>
@@ -192,17 +282,74 @@ export const productCard1PropsSchema = z.object({
 })
 export type ProductCard1SpecProps = z.infer<typeof productCard1PropsSchema>
 
+/**
+ * Canonical product presentation — the serializable projection a storefront host
+ * produces from a canonical `Product` for the merchandising sections. Unlike
+ * `cardProductSchema` (legacy, numeric `price`), `price`/`compareAtPrice` carry
+ * canonical `Money` (decimal major-unit string + currency code), so the block
+ * formats in the shopper's currency and locale and renders a truthful
+ * unavailable state instead of `$0`. Optional fields are omitted, never `""`.
+ *
+ * This contract is additive: `cardProductSchema` and its consumers are
+ * unchanged, and a legacy numeric `price` still renders the legacy output.
+ */
+export const productPresentationSchema = z.object({
+  id: z.union([z.string(), z.number()]),
+  title: z.string(),
+  /** Omitted (never `""`) when the backend has no image. */
+  image: z.string().optional(),
+  imageAlt: z.string().optional(),
+  /** Product destination; omitted when unknown. */
+  href: z.string().optional(),
+  price: moneySchema,
+  /** Comparison ("was") price; rendered only when valid and higher than `price`. */
+  compareAtPrice: moneySchema.optional(),
+  /** Only from real evidence; omitted otherwise (never fabricated). */
+  rating: z.number().optional(),
+  badge: z.string().optional(),
+})
+export type ProductPresentation = z.infer<typeof productPresentationSchema>
+
+/**
+ * Serializable contract for the combined grid-and-carousel product
+ * presentation (`ProductShowcase1`). The grid pages are fixed-size, navigated
+ * manually (prev/next) with a visible current-page indication; there is no
+ * autoplay and no infinite loop. React-only callbacks are excluded.
+ */
+export const productShowcase1PropsSchema = z.object({
+  products: z.array(productPresentationSchema),
+  heading: z.string().optional(),
+  description: z.string().optional(),
+  pageSize: z.number().int().positive().optional(),
+  prevLabel: z.string().optional(),
+  nextLabel: z.string().optional(),
+  pageLabel: z.string().optional(),
+  unavailablePriceLabel: z.string().optional(),
+  emptyLabel: z.string().optional(),
+  addToCartLabel: z.string().optional(),
+})
+export type ProductShowcase1SpecProps = z.infer<typeof productShowcase1PropsSchema>
+
 export const shoppingCart4PropsSchema = z.object({
   items: z.array(cartItemSchema),
   promotions: z.array(promotionSchema).default([]),
   recentlyViewed: z.array(recentlyViewedItemSchema).optional(),
+  /** Backend-authoritative totals; rendered verbatim, never computed locally. */
+  totals: cartTotalsSchema.optional(),
+  totalsState: z.enum(['idle', 'pending', 'error']).optional(),
+  totalsErrorLabel: z.string().optional(),
+  totalsUnavailableLabel: z.string().optional(),
+  amountUnavailableLabel: z.string().optional(),
+  retryLabel: z.string().optional(),
   taxRate: z.number().optional(),
   titleLabel: z.string().optional(),
   subtotalLabel: z.string().optional(),
+  discountLabel: z.string().optional(),
   taxLabel: z.string().optional(),
   shippingLabel: z.string().optional(),
   shippingFreeLabel: z.string().optional(),
   totalLabel: z.string().optional(),
+  totalsPendingLabel: z.string().optional(),
   awayFromLabel: z.string().optional(),
   activatedLabel: z.string().optional(),
   itemsLabel: z.string().optional(),
@@ -217,19 +364,100 @@ export const shoppingCart4PropsSchema = z.object({
   checkoutLabel: z.string().optional(),
   quickCheckoutLabel: z.string().optional(),
   checkoutNowLabel: z.string().optional(),
+  emptyLabel: z.string().optional(),
+  removeLabel: z.string().optional(),
+  decreaseLabel: z.string().optional(),
+  increaseLabel: z.string().optional(),
 })
 export type ShoppingCart4SpecProps = z.infer<typeof shoppingCart4PropsSchema>
 
+/**
+ * Optional brand seams shared by the existing blocks. These mirror the
+ * components' optional props as a serializable subset (no React): an accent
+ * marks a trailing segment of the wordmark/brand name, and an editorial image
+ * is a native `<img>` source. Omitting each keeps the block's current output.
+ */
+export const logoAccentSchema = z.object({
+  text: z.string(),
+  className: z.string().optional(),
+})
+export type LogoAccent = z.infer<typeof logoAccentSchema>
+
+export const brandAccentSchema = z.object({
+  text: z.string(),
+  className: z.string().optional(),
+})
+export type BrandAccent = z.infer<typeof brandAccentSchema>
+
+export const heroImageSchema = z.object({
+  src: z.string(),
+  alt: z.string(),
+})
+export type HeroImage = z.infer<typeof heroImageSchema>
+
 export const navbar4PropsSchema = z.object({
   storeCategories: z.array(storeCategorySchema),
-  shippingNote: z.string(),
+  shippingNote: z.string().optional(),
   utilityLinks: z.array(utilityLinkSchema),
   logoText: z.string(),
   logoHref: z.string().optional(),
+  /** Optional accent for a trailing segment of `logoText`; omitted → unchanged. */
+  logoAccent: logoAccentSchema.optional(),
+  /**
+   * Consumer-supplied classes merged onto the block's outer surface as the
+   * final argument (e.g. a semantic surface token). Omitted → unchanged.
+   */
+  className: z.string().optional(),
   accountHref: z.string().optional(),
   searchQuery: z.string().optional(),
   items: z.array(navCartItemSchema).optional(),
+  /** Authoritative backend subtotal for the mini-cart. */
+  subtotal: moneySchema.optional(),
+  subtotalUnavailableLabel: z.string().optional(),
   user: storeUserSchema.optional(),
   accountMenuItems: z.array(accountMenuItemSchema).optional(),
+  accountPending: z.boolean().optional(),
+  accountUnavailable: z.boolean().optional(),
+})
+export type Navbar4SpecProps = z.infer<typeof navbar4PropsSchema>
+
+/**
+ * Serializable contracts for the two bounded editorial sections (`faq`, `cta`).
+ * These are the serializable subset of `FaqBlock1Props`/`CtaSection1Props`: the
+ * React-only callbacks (`onPrimaryClick`/`onSecondaryClick`) are intentionally
+ * excluded — the catalog adapter binds them (see design D3).
+ */
+export const ctaSchema = z.object({
+  label: z.string(),
+  href: z.string().optional(),
+})
+export type CtaSpec = z.infer<typeof ctaSchema>
+
+export const faqItemSchema = z.object({
+  value: z.string(),
+  question: z.string(),
+  answer: z.string(),
+})
+export type FaqItemSpec = z.infer<typeof faqItemSchema>
+
+export const faqBlock1PropsSchema = z.object({
+  items: z.array(faqItemSchema),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  accordionType: z.enum(['single', 'multiple']).optional(),
 })
-export type Navbar4SpecProps = z.infer<typeof navbar4PropsSchema>
+export type FaqBlock1SpecProps = z.infer<typeof faqBlock1PropsSchema>
+
+export const ctaSection1PropsSchema = z.object({
+  badgeText: z.string().optional(),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  primaryCta: ctaSchema.optional(),
+  secondaryCta: ctaSchema.optional(),
+})
+export type CtaSection1SpecProps = z.infer<typeof ctaSection1PropsSchema>
+
+// Pure monetary helpers, re-exported from the server-safe contracts entry so a
+// host boundary can validate/format `Money` without importing the React entry.
+export { isCompleteFiniteDecimal, isAvailableMoney, formatMoney } from './money'
+export { resolveAbsoluteQuantity } from './cart'

package/src/lib/money.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest'
+import { formatMoney, isAvailableMoney, isCompleteFiniteDecimal } from './money'
+
+describe('isCompleteFiniteDecimal', () => {
+  it('accepts complete finite decimals, including zero and negatives', () => {
+    for (const value of ['0', '0.00', '69.99', '-3.5', '1000']) {
+      expect(isCompleteFiniteDecimal(value)).toBe(true)
+    }
+  })
+
+  it('rejects partial, malformed, empty, and non-string input', () => {
+    for (const value of ['', ' ', '1.', '.5', '1e3', 'abc', '1,5', 'Infinity', 'NaN', null, 42, undefined]) {
+      expect(isCompleteFiniteDecimal(value)).toBe(false)
+    }
+  })
+})
+
+describe('isAvailableMoney', () => {
+  it('treats a backend-resolved valid zero as available', () => {
+    expect(isAvailableMoney({ amount: '0', currencyCode: 'USD' })).toBe(true)
+  })
+
+  it('treats a malformed amount as unavailable', () => {
+    expect(isAvailableMoney({ amount: 'n/a', currencyCode: 'USD' })).toBe(false)
+  })
+
+  it('treats a missing currency as unavailable', () => {
+    expect(isAvailableMoney({ amount: '10', currencyCode: ' ' })).toBe(false)
+  })
+
+  it('treats null/undefined as unavailable', () => {
+    expect(isAvailableMoney(null)).toBe(false)
+    expect(isAvailableMoney(undefined)).toBe(false)
+  })
+})
+
+describe('formatMoney', () => {
+  it('uses the money currency rather than a hardcoded one', () => {
+    const text = formatMoney({ amount: '69.99', currencyCode: 'EUR' })
+    expect(text).toContain('69.99')
+    expect(text).not.toContain('USD')
+  })
+
+  it('defers to a supplied formatter', () => {
+    expect(
+      formatMoney({ amount: '5', currencyCode: 'USD' }, money => `<<${money.amount} ${money.currencyCode}>>`),
+    ).toBe('<<5 USD>>')
+  })
+
+  it('returns null for absent or malformed amounts instead of a fake zero', () => {
+    expect(formatMoney({ amount: '', currencyCode: 'USD' })).toBeNull()
+    expect(formatMoney({ amount: '   ', currencyCode: 'USD' })).toBeNull()
+    expect(formatMoney({ amount: 'abc', currencyCode: 'USD' })).toBeNull()
+    expect(formatMoney({ amount: '10', currencyCode: '' })).toBeNull()
+    expect(formatMoney(null)).toBeNull()
+    expect(formatMoney(undefined)).toBeNull()
+  })
+
+  it('preserves a legitimate zero', () => {
+    expect(
+      formatMoney({ amount: '0', currencyCode: 'USD' }, money => `${money.currencyCode} ${money.amount}`),
+    ).toBe('USD 0')
+  })
+})