@cartbase/storefront 0.1.0

package/src/cart-drawer/template.tsx

@@ -0,0 +1,225 @@
+"use client"
+
+import { useCallback, useEffect, useState } from "react"
+
+import { CartDrawer } from "./cart-drawer"
+import { CartDrawerHeader } from "./header"
+import { CartPromoBanner } from "./promo-banner"
+import { CartTieredProgress, type CartTier } from "./tiered-progress"
+import { CartItem } from "./item"
+import { CartFreeGift } from "./free-gift"
+import { CartCrossSellCarousel, type CrossSellCarouselProduct } from "./cross-sell-carousel"
+import { CartCrossSellSidebar, type CrossSellSidebarProduct } from "./cross-sell-sidebar"
+import { CartGiftWrap } from "./gift-wrap"
+import { CartNotes } from "./notes"
+import { CartRewardsPoints } from "./rewards-points"
+import { CartStickyFooter } from "./sticky-footer"
+import { CartEmpty } from "./empty"
+import { useCartDrawer } from "./context"
+import { isProductLine } from "../lib/cart-helpers"
+
+/**
+ * CartDrawerTemplate — optional default assembly that composes every cart
+ * drawer primitive into the mindpages-style layout. Every feature is
+ * opt-in via a `CartDrawerConfig` object. Pass no config and you get a
+ * minimal drawer (items + sticky footer only).
+ *
+ * Stores that want a different layout should NOT use this template.
+ * Instead, import the primitives directly and compose their own drawer
+ * body inside a `<CartDrawer>` shell. That way the store owns its
+ * composition and still gets library updates to every primitive.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/template.tsx` (v2.3.1). Barter
+ * adaptations:
+ * - Amounts are EUR major units — `rewards.pointsPerCurrency` is points
+ *   per 1 EUR (the source's `/100` minor-unit division is gone), and
+ *   `freeGift.minCartTotal` is EUR (e.g. 50 = €50).
+ * - Cross-sell `onAdd` is wired to the provider's SDK `addItem(variantId)`
+ *   automatically (the source left it unwired) — build the products via
+ *   `toCrossSellProduct` so `variantId` is set; cards without it no-op.
+ * - `crossSell.loader` example (per-store choice of source):
+ *     `async () => (await listProducts(client, { collection_id: [id],
+ *       currency_code: "eur", limit: 6 })).products
+ *       .map(toCrossSellProduct).filter(Boolean)`
+ *   or `listRelatedProducts(client, anchorHandle, { currency_code: "eur" })`.
+ */
+
+export type CartDrawerConfig = {
+  promoBanner?: {
+    message: string
+    variant?: "info" | "success" | "warning"
+  }
+  shippingTiers?: CartTier[]
+  freeGift?: {
+    title: string
+    description?: string
+    /** EUR major units. */
+    originalPrice: number
+    thumbnail?: string | null
+    /** Only render when the cart subtotal exceeds this amount (EUR). */
+    minCartTotal?: number
+  }
+  giftWrap?: {
+    /** EUR major units. */
+    price: number
+  }
+  notes?: {
+    types: ("gift" | "order")[]
+  }
+  rewards?: {
+    /** Points earned per 1 EUR of subtotal (major units). */
+    pointsPerCurrency: number
+    label?: string
+    details?: string
+  }
+  crossSell?: {
+    /** Provide your own products; pass empty array or omit to disable */
+    products?: (CrossSellSidebarProduct | CrossSellCarouselProduct)[]
+    /** Async loader called once the drawer has items. Return an empty array on failure. */
+    loader?: () => Promise<CrossSellSidebarProduct[]>
+    label?: string
+  }
+  showContinueShopping?: boolean
+}
+
+type CartDrawerTemplateProps = {
+  config?: CartDrawerConfig
+}
+
+export function CartDrawerTemplate({
+  config = {},
+}: CartDrawerTemplateProps) {
+  const { cart, addItem } = useCartDrawer()
+  // Cart drawer is pre-checkout / shopping context — render PRODUCT
+  // lines only. Backend-injected fee lines (COD fee, future surcharges)
+  // are excluded by `isProductLine`. The same predicate gates `hasItems`
+  // so a cart containing only a fee (edge case) renders empty rather
+  // than showing a single fake-product row.
+  const items = (cart?.items || []).filter(isProductLine)
+  const hasItems = items.length > 0
+  const currencyCode = cart?.currency_code || "eur"
+
+  // Subtotal is EUR major units (server truth) — points per 1 EUR.
+  const rewardsPoints = config.rewards
+    ? Math.floor((cart?.subtotal ?? 0) * config.rewards.pointsPerCurrency)
+    : 0
+
+  const showFreeGift =
+    config.freeGift &&
+    (cart?.subtotal ?? 0) >= (config.freeGift.minCartTotal ?? 0)
+
+  // Cross-sell loader — async, only fires once the drawer has items.
+  // Empty/failure state shows nothing (no fake fallback products).
+  const [crossSell, setCrossSell] = useState<CrossSellSidebarProduct[]>(
+    (config.crossSell?.products as CrossSellSidebarProduct[]) || []
+  )
+  const [crossSellLoaded, setCrossSellLoaded] = useState(
+    Boolean(config.crossSell?.products)
+  )
+
+  useEffect(() => {
+    if (!hasItems || crossSellLoaded) return
+    const loader = config.crossSell?.loader
+    if (!loader) {
+      setCrossSellLoaded(true)
+      return
+    }
+    loader()
+      .then((products) => setCrossSell(products ?? []))
+      .catch(() => setCrossSell([]))
+      .finally(() => setCrossSellLoaded(true))
+  }, [hasItems, crossSellLoaded, config.crossSell?.loader])
+
+  // Cross-sell add → the provider's SDK addItem (barter adds by variant
+  // id). Cards built without a variantId no-op.
+  const handleCrossSellAdd = useCallback(
+    (_productId: string, variantId?: string) => {
+      if (variantId) void addItem(variantId, 1)
+    },
+    [addItem]
+  )
+
+  return (
+    <CartDrawer
+      sidebar={
+        hasItems && crossSell.length > 0 ? (
+          <CartCrossSellSidebar
+            products={crossSell}
+            label={config.crossSell?.label}
+            onAdd={handleCrossSellAdd}
+          />
+        ) : undefined
+      }
+    >
+      <CartDrawerHeader />
+
+      {hasItems ? (
+        <>
+          {config.promoBanner && (
+            <CartPromoBanner
+              message={config.promoBanner.message}
+              variant={config.promoBanner.variant}
+            />
+          )}
+
+          {config.shippingTiers && (
+            <CartTieredProgress
+              tiers={config.shippingTiers}
+              currencyCode={currencyCode}
+            />
+          )}
+
+          <div className="flex-1 overflow-y-auto no-scrollbar relative z-0 bg-card">
+            {items
+              .slice()
+              .sort((a, b) =>
+                (a.created_at ?? "") > (b.created_at ?? "") ? -1 : 1
+              )
+              .map((item) => (
+                <CartItem key={item.id} item={item} currencyCode={currencyCode} />
+              ))}
+
+            {showFreeGift && config.freeGift && (
+              <CartFreeGift
+                title={config.freeGift.title}
+                description={config.freeGift.description}
+                originalPrice={config.freeGift.originalPrice}
+                currencyCode={currencyCode}
+                thumbnail={config.freeGift.thumbnail}
+              />
+            )}
+
+            {config.rewards && rewardsPoints > 0 && (
+              <CartRewardsPoints
+                points={rewardsPoints}
+                label={config.rewards.label}
+                details={config.rewards.details}
+              />
+            )}
+
+            {config.giftWrap && (
+              <CartGiftWrap
+                price={config.giftWrap.price}
+                currencyCode={currencyCode}
+              />
+            )}
+
+            {config.notes && <CartNotes types={config.notes.types} />}
+
+            {config.crossSell && crossSell.length > 0 && (
+              <CartCrossSellCarousel
+                label={config.crossSell.label}
+                products={crossSell as CrossSellCarouselProduct[]}
+                onAdd={handleCrossSellAdd}
+              />
+            )}
+          </div>
+
+          <CartStickyFooter />
+        </>
+      ) : (
+        <CartEmpty />
+      )}
+    </CartDrawer>
+  )
+}

package/src/cart-drawer/tiered-progress.tsx

@@ -0,0 +1,168 @@
+"use client"
+
+import { convertToLocale } from "../lib/money"
+import { useCartDrawer } from "./context"
+
+/**
+ * Tiered progress bar — shows how far the cart total is from the next
+ * shipping/discount tier, with checkpoint markers along the bar.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/tiered-progress.tsx` (v2.3.1);
+ * originally extracted from mindpages-storefront
+ * src/modules/cart-drawer/cart-tiered-progress.tsx.
+ *
+ * Barter money note: `cart.total` and tier `threshold`s are EUR decimal
+ * major units (e.g. `{ threshold: 50 }` = €50) — configure tiers in major
+ * units, not cents.
+ */
+
+export type CartTier = {
+  /** EUR major units. */
+  threshold: number
+  label: string
+  icon?: "shipping" | "discount" | "gift"
+}
+
+export type TierProgress = {
+  /** 0–100, capped. */
+  progressPercent: number
+  /** First tier the amount hasn't reached yet; null when all unlocked. */
+  nextTier: CartTier | null
+  /** Amount missing to `nextTier.threshold` (0 when all unlocked). */
+  remaining: number
+}
+
+/**
+ * Pure tier math — exported for unit tests. `tiers` must be sorted
+ * ascending by threshold (the caller's config order, same contract as the
+ * source component).
+ */
+export function computeTierProgress(
+  amount: number,
+  tiers: readonly CartTier[]
+): TierProgress {
+  if (!tiers.length) {
+    return { progressPercent: 0, nextTier: null, remaining: 0 }
+  }
+  const maxThreshold = tiers[tiers.length - 1]!.threshold
+  const progressPercent =
+    maxThreshold > 0 ? Math.min((amount / maxThreshold) * 100, 100) : 100
+  const nextTier = tiers.find((t) => amount < t.threshold) ?? null
+  return {
+    progressPercent,
+    nextTier,
+    remaining: nextTier ? nextTier.threshold - amount : 0,
+  }
+}
+
+type CartTieredProgressProps = {
+  tiers: CartTier[]
+  currencyCode: string
+}
+
+export function CartTieredProgress({
+  tiers,
+  currencyCode,
+}: CartTieredProgressProps) {
+  const { cart, labels } = useCartDrawer()
+  // Tax-inclusive total (server truth — EUR major units)
+  const subtotal = cart?.total ?? 0
+
+  if (tiers.length === 0) return null
+
+  const maxThreshold = tiers[tiers.length - 1]!.threshold
+  const { progressPercent, nextTier } = computeTierProgress(subtotal, tiers)
+
+  return (
+    <div
+      className="px-6 pt-4 pb-5 flex-shrink-0 relative z-10 bg-card border-b border-border"
+      style={{ boxShadow: "0 4px 12px rgba(0,0,0,0.04)" }}
+    >
+      {nextTier ? (
+        <p className="text-[13px] text-muted-foreground mb-4">
+          <span className="font-bold text-foreground">
+            {convertToLocale({
+              amount: nextTier.threshold - subtotal,
+              currency_code: currencyCode,
+            })}
+          </span>{" "}
+          {labels.awayFromFreeShipping}
+        </p>
+      ) : (
+        <p className="text-[13px] text-success font-medium mb-4">
+          {labels.allRewardsUnlocked}
+        </p>
+      )}
+
+      <div className="relative px-3">
+        <div className="h-2 bg-muted rounded-full overflow-hidden">
+          <div
+            className="h-full rounded-full transition-all duration-700 ease-out"
+            style={{
+              width: `${progressPercent}%`,
+              background:
+                progressPercent >= 100
+                  ? "linear-gradient(90deg, oklch(var(--success)), oklch(var(--success) / 0.7))"
+                  : "linear-gradient(90deg, oklch(var(--foreground)), oklch(var(--foreground) / 0.75))",
+            }}
+          />
+        </div>
+
+        {tiers.map((tier, i) => {
+          const position = (tier.threshold / maxThreshold) * 100
+          const achieved = subtotal >= tier.threshold
+
+          return (
+            <div
+              key={i}
+              className="absolute top-0"
+              style={{ left: `${position}%` }}
+            >
+              <div
+                className={`w-5 h-5 rounded-full flex items-center justify-center -translate-x-1/2 -translate-y-[6px] border-[2.5px] border-surface ${
+                  achieved ? "bg-success" : "bg-muted"
+                }`}
+              >
+                {achieved && (
+                  <svg
+                    width="9"
+                    height="9"
+                    viewBox="0 0 10 10"
+                    fill="none"
+                    stroke="white"
+                    strokeWidth="2"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                  >
+                    <path d="M2 5l2.5 2.5L8 3" />
+                  </svg>
+                )}
+              </div>
+              <div className="-translate-x-1/2 mt-1.5 whitespace-nowrap text-center">
+                <span
+                  className={`text-[10px] block leading-tight font-medium ${
+                    achieved ? "text-success" : "text-muted-foreground"
+                  }`}
+                >
+                  {tier.label}
+                </span>
+                <span
+                  className={`text-[10px] block leading-tight tabular-nums ${
+                    achieved ? "text-success" : "text-muted-foreground"
+                  }`}
+                >
+                  {convertToLocale({
+                    amount: tier.threshold,
+                    currency_code: currencyCode,
+                  })}
+                </span>
+              </div>
+            </div>
+          )
+        })}
+      </div>
+
+      <div className="h-8" />
+    </div>
+  )
+}

package/src/checkout/address-error-copy.ts

@@ -0,0 +1,119 @@
+/**
+ * Translates address-save errors into user-friendly Bulgarian copy for the
+ * checkout address surface.
+ *
+ * Ported from `@1click/ui/src/checkout/address-error-copy.ts` (v2.3.1) and
+ * adapted to the barter error envelope: `StoreApiError` carries a structured
+ * `code` (POST /api/store/carts/:id — docs/storefront/carts.md), so
+ * translation is code-first; the substring patterns stay as the fallback for
+ * network failures and any legacy wire.
+ *
+ * The mapping is deliberately narrow: only translate errors we recognize;
+ * everything else falls back to a clean generic message rather than
+ * half-translated text.
+ */
+
+const GENERIC_FALLBACK =
+  "Възникна проблем при запазване на адреса. Моля, проверете данните и опитайте отново."
+
+const NETWORK_FALLBACK =
+  "Няма връзка със сървъра. Моля, проверете интернет връзката и опитайте отново."
+
+/**
+ * Barter cart-update error codes → BG copy (POST /api/store/carts/:id,
+ * docs/storefront/carts.md). Code-first, matched before any pattern.
+ */
+export const ADDRESS_ERROR_CODE_COPY: Record<string, string> = {
+  validation_failed:
+    "Някое от полетата не е валидно. Моля, проверете данните и опитайте отново.",
+  invalid_region: "Невалидна държава. Моля, презаредете страницата.",
+  region_required: "Регионът на доставка не е валиден. Моля, презаредете страницата.",
+  cart_completed:
+    "Поръчката вече е финализирана. Моля, проверете имейла си за потвърждение.",
+  cart_not_found: "Сесията на количката изтече. Моля, презаредете страницата.",
+}
+
+/**
+ * Patterns matched in order — first match wins. List most specific
+ * first, generic last. Match is case-insensitive (regexes carry /i).
+ * Kept verbatim from the production port.
+ */
+const PATTERNS: Array<{ match: RegExp; copy: string }> = [
+  // Email validation — confirmed (in @1click production) as the most common
+  // address-save failure shape.
+  {
+    match: /invalid[\s_]?(?:request:?\s*)?invalid[\s_]?email|invalid[\s_]?email/i,
+    copy: "Невалиден имейл адрес. Моля, проверете изписването.",
+  },
+  // Postal / postcode validation
+  {
+    match: /invalid[\s_]?postal|invalid[\s_]?post(?:code|al[\s_]?code)|postal[\s_]?code[\s_]?(?:is[\s_]?)?invalid/i,
+    copy: "Невалиден пощенски код. Моля, въведете 4-цифрен код.",
+  },
+  // Phone validation
+  {
+    match: /invalid[\s_]?phone|phone[\s_]?(?:number[\s_]?)?(?:is[\s_]?)?invalid/i,
+    copy: "Невалиден телефонен номер. Моля, проверете цифрите.",
+  },
+  // Country / region mismatch
+  {
+    match: /invalid[\s_]?country|country[\s_]?(?:code[\s_]?)?(?:is[\s_]?)?invalid|no[\s_]?region|invalid[\s_]?region/i,
+    copy: "Невалидна държава. Моля, презаредете страницата.",
+  },
+  // Cart already completed — race with order placement
+  {
+    match: /cart[\s_]?(?:is[\s_]?)?already[\s_]?completed|already[\s_]?an[\s_]?order|completed[\s_]?cart/i,
+    copy: "Поръчката вече е финализирана. Моля, проверете имейла си за потвърждение.",
+  },
+  // Cart not found / expired
+  {
+    match: /cart[\s_]?(?:not[\s_]?found|does[\s_]?not[\s_]?exist|expired)/i,
+    copy: "Сесията на количката изтече. Моля, презаредете страницата.",
+  },
+  // Network / fetch failure
+  {
+    match: /failed[\s_]?to[\s_]?fetch|network[\s_]?error|networkerror|econnreset|etimedout/i,
+    copy: NETWORK_FALLBACK,
+  },
+  // The Next.js canned Server Components production message — surface a
+  // clean fallback instead of the English placeholder. (The barter SDK
+  // throws from the browser, so this only fires for stores that proxy the
+  // save through a server action.)
+  {
+    match: /server[\s_]?components[\s_]?render|digest property is included/i,
+    copy: GENERIC_FALLBACK,
+  },
+]
+
+/**
+ * Translate any thrown / returned address-save error into
+ * customer-facing Bulgarian copy. Returns the generic fallback when
+ * the error doesn't match a known code or pattern.
+ */
+export function translateAddressError(err: unknown): string {
+  if (err && typeof err === "object") {
+    const code = (err as { code?: unknown }).code
+    if (typeof code === "string" && ADDRESS_ERROR_CODE_COPY[code]) {
+      return ADDRESS_ERROR_CODE_COPY[code]
+    }
+  }
+
+  const raw = extractMessage(err)
+  if (!raw) return GENERIC_FALLBACK
+
+  for (const { match, copy } of PATTERNS) {
+    if (match.test(raw)) return copy
+  }
+  return GENERIC_FALLBACK
+}
+
+function extractMessage(err: unknown): string {
+  if (!err) return ""
+  if (typeof err === "string") return err
+  if (err instanceof Error) return err.message
+  if (typeof err === "object" && err !== null) {
+    const e = err as { message?: string; code?: string; type?: string }
+    return [e.message, e.code, e.type].filter(Boolean).join(" ")
+  }
+  return String(err)
+}