@thorprovider/blocks 0.1.0 → 0.1.2

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,10 +192,11 @@ 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>
 
@@ -196,13 +286,22 @@ 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 +316,98 @@ 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(),
   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(),
 })
-export type Navbar4SpecProps = z.infer<typeof navbar4PropsSchema>
+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 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')
+  })
+})

package/src/lib/money.ts

@@ -0,0 +1,65 @@
+import type { Money } from '@thorprovider/types'
+
+/**
+ * Pure monetary helpers shared by the curated commerce blocks.
+ *
+ * Canonical `Money` (`@thorprovider/types`) carries a decimal string in major
+ * units (e.g. `"69.99"`) — never cents. A missing, invalid, or unresolved
+ * amount is *unavailable*, which is a different state from a legitimate `"0"`.
+ * These helpers keep that distinction in the presentation layer: they validate
+ * a complete finite decimal before any display conversion, and they never
+ * invent a currency.
+ */
+
+const COMPLETE_FINITE_DECIMAL = /^-?(?:\d+)(?:\.\d+)?$/
+
+/**
+ * True only for a complete, finite decimal string (`"0"`, `"69.99"`, `"-3.5"`).
+ * Rejects `""`, `" "`, `"1."`, `".5"`, `"1e3"`, `"abc"`, and non-strings.
+ */
+export function isCompleteFiniteDecimal(value: unknown): value is string {
+  if (typeof value !== 'string') return false
+  const trimmed = value.trim()
+  if (trimmed === '' || !COMPLETE_FINITE_DECIMAL.test(trimmed)) return false
+  return Number.isFinite(Number(trimmed))
+}
+
+/**
+ * True when a `Money` value is safe to display and price a purchase with: a
+ * complete finite decimal amount and a non-empty currency code. A valid zero
+ * (`{ amount: '0', currencyCode: 'USD' }`) is available — zero alone does not
+ * make a price unavailable.
+ */
+export function isAvailableMoney(money: Money | null | undefined): money is Money {
+  return (
+    !!money &&
+    typeof money.currencyCode === 'string' &&
+    money.currencyCode.trim() !== '' &&
+    isCompleteFiniteDecimal(money.amount)
+  )
+}
+
+/**
+ * Formats a `Money` for display, or `null` when the value is unavailable.
+ *
+ * This is the safety gate the whole curated surface relies on: an absent or
+ * malformed amount (`""`, `" "`, `"abc"`, a non-string, a missing currency)
+ * MUST NOT reach `Intl.NumberFormat`, because `Number("")` is `0` and would
+ * render a fake `$0.00` for missing data. A backend-resolved valid zero
+ * (`{ amount: "0", currencyCode: "USD" }`) is available and formats as zero.
+ *
+ * When no `formatter` is supplied the currency comes from
+ * `money.currencyCode`, so no currency is hardcoded. Callers render their own
+ * unavailable/pending/recovery state when this returns `null`.
+ */
+export function formatMoney(
+  money: Money | null | undefined,
+  formatter?: (money: Money) => string,
+): string | null {
+  if (!isAvailableMoney(money)) return null
+  if (formatter) return formatter(money)
+  return new Intl.NumberFormat(undefined, {
+    style: 'currency',
+    currency: money.currencyCode,
+  }).format(Number(money.amount))
+}

package/styles.css

@@ -0,0 +1 @@
+@source "./dist";

package/tsup.config.ts

@@ -11,6 +11,5 @@ export default defineConfig({
   sourcemap: true,
   clean: true,
   external: ['react', 'react-dom', 'clsx', 'tailwind-merge', 'lucide-react'],
-  banner: { js: "'use client';" },
   onSuccess: process.env.SKIP_TYPE_CHECK === 'true' ? undefined : 'tsc --noEmit --skipLibCheck'
 })

package/vitest.config.ts

@@ -1,9 +1,17 @@
+import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
+  resolve: {
+    // Vendored shadcn primitives under src/ui use the `@/` alias; mirror the
+    // tsconfig paths so component tests can import them.
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url)),
+    },
+  },
   test: {
     environment: 'node',
     globals: true,
     include: ['src/**/*.test.{ts,tsx}'],
   },
-})
+})