@cartbase/storefront 0.1.0

package/src/cart-drawer/index.ts

@@ -0,0 +1,69 @@
+// @cartbase/storefront/cart-drawer — barrel export
+//
+// Re-exports every cart drawer primitive + the optional default assembly.
+// Stores can import from this subpath:
+//
+//   import {
+//     CartDrawerProvider,
+//     CartDrawer,
+//     CartDrawerHeader,
+//     CartItem,
+//     CartStickyFooter,
+//     CartDrawerTemplate,
+//   } from "@cartbase/storefront/cart-drawer"
+//
+// Prefer the per-file subpaths in app code (tree-shaking + RSC boundary
+// clarity) — every file here is also exported individually in package.json.
+
+export {
+  CartDrawerProvider,
+  useCartDrawer,
+  reduceCart,
+  makeOptimisticLine,
+  type OptimisticCartAction,
+  type OptimisticAddDisplay,
+  type OptimisticCartError,
+} from "./context"
+export {
+  defaultCartDrawerLabels,
+  type CartDrawerLabels,
+} from "./labels"
+export { bulgarianCartDrawerLabels } from "./labels-bg"
+
+export { CartDrawer } from "./cart-drawer"
+export { CartDrawerHeader } from "./header"
+export { CartPromoBanner } from "./promo-banner"
+export {
+  CartTieredProgress,
+  computeTierProgress,
+  type CartTier,
+  type TierProgress,
+} from "./tiered-progress"
+export { CartItem } from "./item"
+export { CartItemQuantity } from "./item/quantity"
+export { CartItemVariant } from "./item/variant"
+export { CartItemUpsell, type UpsellProduct } from "./item/upsell"
+export { CartFreeGift } from "./free-gift"
+export { CartGiftWrap } from "./gift-wrap"
+export { CartNotes } from "./notes"
+export { CartRewardsPoints } from "./rewards-points"
+export {
+  CartCrossSellSidebar,
+  toCrossSellProduct,
+  type CrossSellSidebarProduct,
+} from "./cross-sell-sidebar"
+export {
+  CartCrossSellCarousel,
+  type CrossSellCarouselProduct,
+} from "./cross-sell-carousel"
+export {
+  CartSummaryBreakdown,
+  selectSummaryRows,
+  type SummaryCartTotals,
+  type SummaryRow,
+} from "./summary-breakdown"
+export { CartStickyFooter } from "./sticky-footer"
+export { CartPaymentBadges } from "./payment-badges"
+export { CartContinueShopping } from "./continue-shopping"
+export { CartEmpty } from "./empty"
+export { CartDrawerTemplate, type CartDrawerConfig } from "./template"

package/src/cart-drawer/item/index.tsx

@@ -0,0 +1,164 @@
+"use client"
+
+import Image from "next/image"
+import Link from "next/link"
+import { type ReactNode } from "react"
+
+import type { CartLineItem } from "../../api/carts"
+import { DualPrice } from "../../lib/dual-price"
+import { cn } from "../../lib/utils"
+import { useCartDrawer } from "../context"
+import { CartItemQuantity } from "./quantity"
+import { CartItemVariant } from "./variant"
+
+/**
+ * CartItem — a single cart line row: thumbnail, title, variant, quantity
+ * stepper, price (with dual-currency + optional strikethrough), remove button.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/item/index.tsx` (v2.3.1). Barter
+ * data seam: `item` is the SDK's decorated `CartLineItem`
+ * (`@cartbase/storefront/api/carts`) — per-line `total`/`original_total` are
+ * server-computed EUR major units. Remove goes through the provider's
+ * SDK-wired `removeItem` (DELETE line-items/:id, returns the full decorated
+ * cart) instead of the Medusa server action. The variant row renders the
+ * line's flat `variant_title` — barter cart lines carry the variant title
+ * string, not an embedded variant object.
+ *
+ * `children` is rendered below the main row — intended for per-item upsell
+ * slots (see `CartItemUpsell` in `./upsell.tsx`).
+ */
+
+type CartItemProps = {
+  item: CartLineItem
+  currencyCode: string
+  children?: ReactNode
+}
+
+export function CartItem({ item, currencyCode, children }: CartItemProps) {
+  const { labels, hrefs, removeItem } = useCartDrawer()
+
+  // Optimistic remove: the item is filtered out of the optimistic cart
+  // immediately on click, so the row vanishes at React update speed.
+  // The deleteLineItem SDK call runs in the background. On failure
+  // useOptimistic auto-reverts (confirmed snapshot unchanged) and the
+  // row reappears.
+  const handleRemove = () => {
+    void removeItem(item.id)
+  }
+  const removing = false // optimistic remove unmounts the row immediately
+
+  const total = item.total ?? 0
+  const originalTotal = item.original_total ?? 0
+  const hasDiscount = total < originalTotal
+  const productHref = `${hrefs.productPrefix}/${item.product_handle}`
+
+  return (
+    <div
+      className={cn(
+        "px-6 py-5 transition-opacity",
+        removing && "opacity-30 pointer-events-none"
+      )}
+    >
+      <div className="flex gap-4">
+        <Link href={productHref} className="flex-shrink-0">
+          <div
+            className="w-[64px] h-[84px] sm:w-[72px] sm:h-[72px] rounded-xl overflow-hidden bg-muted relative"
+            style={{ boxShadow: "0 1px 3px rgba(0,0,0,0.06)" }}
+          >
+            {item.thumbnail ? (
+              <Image
+                src={item.thumbnail}
+                alt={item.product_title || ""}
+                fill
+                className="object-cover"
+                sizes="72px"
+              />
+            ) : (
+              <div className="w-full h-full flex items-center justify-center">
+                <svg
+                  width="20"
+                  height="20"
+                  viewBox="0 0 24 24"
+                  fill="none"
+                  stroke="currentColor"
+                  className="text-muted-foreground"
+                  strokeWidth="1.2"
+                >
+                  <rect x="3" y="3" width="18" height="18" rx="3" />
+                  <circle cx="8.5" cy="8.5" r="1.5" />
+                  <path
+                    d="M21 15l-5-5L5 21"
+                    strokeLinecap="round"
+                    strokeLinejoin="round"
+                  />
+                </svg>
+              </div>
+            )}
+          </div>
+        </Link>
+
+        <div className="flex-1 min-w-0 flex flex-col">
+          <div className="flex items-baseline justify-between gap-3">
+            <div className="min-w-0">
+              <Link
+                href={productHref}
+                className="text-sm font-semibold text-foreground hover:text-muted-foreground transition-colors line-clamp-2 leading-snug block"
+              >
+                {item.product_title}
+              </Link>
+              <CartItemVariant variantTitle={item.variant_title} />
+            </div>
+            <div className="text-right flex-shrink-0">
+              {hasDiscount && (
+                <span className="text-xs text-muted-foreground line-through block leading-none mb-0.5">
+                  <DualPrice
+                    amount={originalTotal}
+                    currencyCode={currencyCode}
+                    className="text-xs text-muted-foreground"
+                    bgnClassName="hidden"
+                  />
+                </span>
+              )}
+              <DualPrice
+                amount={total}
+                currencyCode={currencyCode}
+                className={cn(
+                  "text-sm font-bold",
+                  hasDiscount ? "text-success" : "text-foreground"
+                )}
+                bgnClassName="text-muted-foreground text-[10px] ml-1"
+              />
+            </div>
+          </div>
+
+          <div className="flex items-center justify-between mt-3">
+            <CartItemQuantity lineId={item.id} quantity={item.quantity} />
+            <button
+              type="button"
+              onClick={handleRemove}
+              className="w-8 h-8 flex items-center justify-center rounded-lg text-muted-foreground hover:text-destructive hover:bg-destructive/10 transition-all"
+              aria-label={labels.remove}
+            >
+              <svg
+                width="16"
+                height="16"
+                viewBox="0 0 16 16"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.3"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              >
+                <path d="M2.5 4.5h11M5.5 4.5V3a1 1 0 011-1h3a1 1 0 011 1v1.5M12.5 4.5v9a1 1 0 01-1 1h-7a1 1 0 01-1-1v-9" />
+                <path d="M6.5 7v4M9.5 7v4" />
+              </svg>
+            </button>
+          </div>
+        </div>
+      </div>
+
+      {children}
+      <div className="mt-5 border-b border-border" />
+    </div>
+  )
+}

package/src/cart-drawer/item/quantity.tsx

@@ -0,0 +1,100 @@
+"use client"
+
+import { useState } from "react"
+
+import { cn } from "../../lib/utils"
+import { useCartDrawer } from "../context"
+
+/**
+ * CartItemQuantity — +/- quantity stepper for a single cart line item.
+ *
+ * Optimistic: the provider's `updateQuantity` dispatches an
+ * "update_quantity" action against the useOptimistic state BEFORE awaiting
+ * the SDK call. The stepper number changes instantly; the server work
+ * happens in the background. On failure the optimistic state reverts
+ * automatically (confirmed snapshot unchanged).
+ *
+ * Ported from `@1click/ui/src/cart-drawer/item/quantity.tsx` (v2.3.1).
+ * Barter data seam: `updateQuantity` wraps
+ * `POST /api/store/carts/:id/line-items/:lineId` with body `{quantity}` —
+ * the barter contract accepts ONLY `quantity` (no metadata on update) and
+ * quantity 0 deletes the line (unreachable here: the stepper floor is 1;
+ * removal is the dedicated remove button).
+ */
+
+type CartItemQuantityProps = {
+  lineId: string
+  quantity: number
+  maxQuantity?: number
+  className?: string
+}
+
+export function CartItemQuantity({
+  lineId,
+  quantity,
+  maxQuantity = 10,
+  className,
+}: CartItemQuantityProps) {
+  const { updateQuantity } = useCartDrawer()
+  const [updating, setUpdating] = useState(false)
+
+  const change = (newQty: number) => {
+    if (newQty < 1 || newQty > maxQuantity || updating) return
+    setUpdating(true)
+    // Resolves true/false when the server settles; failures are funneled
+    // through the provider's onOptimisticError.
+    void updateQuantity(lineId, newQty).finally(() => setUpdating(false))
+  }
+
+  return (
+    <div
+      className={cn(
+        "inline-flex items-center border border-border rounded-lg h-9",
+        updating && "opacity-50 pointer-events-none",
+        className
+      )}
+    >
+      <button
+        type="button"
+        onClick={() => change(quantity - 1)}
+        disabled={quantity <= 1}
+        className="w-9 h-full flex items-center justify-center text-muted-foreground hover:text-foreground disabled:text-muted-foreground disabled:cursor-not-allowed transition-colors"
+        aria-label="Decrease quantity"
+      >
+        <svg
+          width="12"
+          height="12"
+          viewBox="0 0 12 12"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+        >
+          <path d="M2.5 6h7" />
+        </svg>
+      </button>
+      <span className="w-8 text-center text-sm font-medium text-foreground tabular-nums select-none">
+        {quantity}
+      </span>
+      <button
+        type="button"
+        onClick={() => change(quantity + 1)}
+        disabled={quantity >= maxQuantity}
+        className="w-9 h-full flex items-center justify-center text-muted-foreground hover:text-foreground disabled:text-muted-foreground disabled:cursor-not-allowed transition-colors"
+        aria-label="Increase quantity"
+      >
+        <svg
+          width="12"
+          height="12"
+          viewBox="0 0 12 12"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="1.5"
+          strokeLinecap="round"
+        >
+          <path d="M6 2.5v7M2.5 6h7" />
+        </svg>
+      </button>
+    </div>
+  )
+}

package/src/cart-drawer/item/upsell.tsx

@@ -0,0 +1,110 @@
+"use client"
+
+import Image from "next/image"
+import Link from "next/link"
+
+import { convertToLocale } from "../../lib/money"
+import { useCartDrawer } from "../context"
+
+/**
+ * CartItemUpsell — slot rendered INSIDE a cart item for per-product
+ * complementary recommendations. Accepts a list of products and an
+ * onAdd handler.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/item/upsell.tsx` (v2.3.1).
+ * Barter data seam: source stores fed this from Medusa product fetches —
+ * feed it from `@cartbase/storefront/api/search` `listRelatedProducts`
+ * (per-anchor complements: manual admin picks + deterministic fallback)
+ * mapped via `toCrossSellProduct` (`../cross-sell-sidebar`). `variantId`
+ * was added to `UpsellProduct` and to the `onAdd` signature so the handler
+ * can call the provider's `addItem(variantId)` directly — barter carts add
+ * by variant id, not product id. Prices are EUR major units.
+ */
+
+export type UpsellProduct = {
+  id: string
+  title: string
+  handle: string
+  thumbnail: string | null
+  price: number
+  currencyCode: string
+  /** Variant to add (barter add-to-cart is by variant id). */
+  variantId?: string
+}
+
+type CartItemUpsellProps = {
+  label?: string
+  products: UpsellProduct[]
+  onAdd?: (productId: string, variantId?: string) => void
+}
+
+export function CartItemUpsell({
+  label,
+  products,
+  onAdd,
+}: CartItemUpsellProps) {
+  const { labels, hrefs } = useCartDrawer()
+  if (!products.length) return null
+
+  return (
+    <div className="mt-3 pt-3 border-t border-border">
+      <p className="text-xs font-medium text-muted-foreground mb-2">
+        {label ?? labels.pairsWellWith}
+      </p>
+      <div className="space-y-2">
+        {products.map((product) => (
+          <div
+            key={product.id}
+            className="flex items-center gap-3 p-2 rounded-lg bg-muted hover:bg-muted/70 transition-colors"
+          >
+            <div className="w-10 h-10 rounded-lg overflow-hidden bg-card flex-shrink-0 relative">
+              {product.thumbnail ? (
+                <Image
+                  src={product.thumbnail}
+                  alt={product.title}
+                  fill
+                  className="object-cover"
+                  sizes="40px"
+                />
+              ) : (
+                <div className="w-full h-full bg-muted" />
+              )}
+            </div>
+            <div className="flex-1 min-w-0">
+              <Link
+                href={`${hrefs.productPrefix}/${product.handle}`}
+                className="text-xs font-medium text-foreground truncate block"
+              >
+                {product.title}
+              </Link>
+              <span className="text-xs text-muted-foreground">
+                {convertToLocale({
+                  amount: product.price,
+                  currency_code: product.currencyCode,
+                })}
+              </span>
+            </div>
+            <button
+              type="button"
+              onClick={() => onAdd?.(product.id, product.variantId)}
+              className="w-7 h-7 flex items-center justify-center rounded-full border border-border text-muted-foreground hover:border-text-base hover:text-foreground transition-colors flex-shrink-0"
+              aria-label={`${labels.addToCart} ${product.title}`}
+            >
+              <svg
+                width="12"
+                height="12"
+                viewBox="0 0 12 12"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="1.5"
+                strokeLinecap="round"
+              >
+                <path d="M6 2.5v7M2.5 6h7" />
+              </svg>
+            </button>
+          </div>
+        ))}
+      </div>
+    </div>
+  )
+}

package/src/cart-drawer/item/variant.tsx

@@ -0,0 +1,46 @@
+"use client"
+
+/**
+ * CartItemVariant — renders the variant description (e.g. "Size M / Red")
+ * under the product title in a cart line.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/item/variant.tsx` (v2.3.1).
+ * Barter data seam: the source rendered `variant.options[].value` from an
+ * embedded Medusa variant object; barter cart lines carry the flat
+ * `variant_title` string (SDK `CartLineItem.variant_title`) instead, so
+ * that is the primary prop. Callers that fetched the full variant (PDP
+ * context) can still pass structural `options` and get the original
+ * separator rendering.
+ */
+
+type CartItemVariantProps = {
+  /** Flat variant title from the cart line (`item.variant_title`). */
+  variantTitle?: string | null
+  /** Optional option values when the caller has the full variant. */
+  options?: Array<{ value: string }> | null
+}
+
+export function CartItemVariant({ variantTitle, options }: CartItemVariantProps) {
+  if (options?.length) {
+    return (
+      <div className="flex items-center gap-2 flex-wrap">
+        {options.map((opt, i) => (
+          <span key={i} className="text-xs text-muted-foreground">
+            {opt.value}
+            {i < options.length - 1 && (
+              <span className="ml-2 text-muted-foreground">/</span>
+            )}
+          </span>
+        ))}
+      </div>
+    )
+  }
+
+  if (!variantTitle) return null
+
+  return (
+    <div className="flex items-center gap-2 flex-wrap">
+      <span className="text-xs text-muted-foreground">{variantTitle}</span>
+    </div>
+  )
+}

package/src/cart-drawer/labels-bg.ts

@@ -0,0 +1,72 @@
+import type { CartDrawerLabels } from "./labels"
+
+/**
+ * Bulgarian translations for the cart drawer.
+ *
+ * Ships alongside the English defaults so Bulgarian stores get the
+ * translated copy with a single import instead of hand-writing every
+ * string. Strings match the originals from mindpages-storefront, plus the
+ * barter summary-breakdown row additions.
+ *
+ * Usage in a store's layout:
+ *
+ *   import {
+ *     CartDrawerProvider,
+ *     bulgarianCartDrawerLabels,
+ *   } from "@cartbase/storefront/cart-drawer"
+ *
+ *   <CartDrawerProvider cart={cart} labels={bulgarianCartDrawerLabels}>
+ *     ...
+ *   </CartDrawerProvider>
+ *
+ * For multi-language stores, pick the matching labels object at render
+ * time based on the active locale (the store owns its locale cookie; see
+ * docs/storefront/regions.md for the locale catalog).
+ */
+
+export const bulgarianCartDrawerLabels: CartDrawerLabels = {
+  yourCart: "Вашата кошница",
+  item: "артикул",
+  items: "артикула",
+  closeCart: "Затвори кошницата",
+
+  emptyCartTitle: "Кошницата е празна",
+  emptyCartMessage: "Все още нямате добавени продукти.",
+  browseProducts: "Разгледай продуктите",
+
+  awayFromFreeShipping: "до безплатна доставка",
+  allRewardsUnlocked: "Всички награди са отключени",
+
+  addGiftWrap: "Добави подаръчна опаковка",
+  giftNote: "Картичка",
+  orderNote: "Бележка",
+  giftNotePlaceholder: "Добави лично съобщение...",
+  orderNotePlaceholder: "Специални инструкции за поръчката...",
+
+  estimatedRewardPoints: "Очаквани точки за награда",
+
+  pairsWellWith: "Подходящи допълнения",
+  youllLoveThis: "Ще ви хареса",
+  youMightAlsoLike: "Може да ви хареса",
+  addToCart: "Добави",
+
+  subtotal: "Междинна сума",
+  taxAndShipping: "С включен ДДС. Доставката се изчислява при плащане.",
+  shipping: "Доставка",
+  free: "БЕЗПЛАТНА",
+  calculatedAtCheckout: "Изчислява се при плащане",
+  total: "Общо",
+  secureCheckout: "Към поръчка",
+  shippingAndTaxCalculatedAtCheckout:
+    "Доставката и данъкът се изчисляват при плащане",
+
+  discount: "Отстъпка",
+  tax: "ДДС",
+  codFee: "Такса наложен платеж",
+  giftCard: "Подаръчна карта",
+  remainingToPay: "Остава за плащане",
+
+  continueShopping: "Продължи пазаруването",
+
+  remove: "Премахни",
+}

package/src/cart-drawer/labels.ts

@@ -0,0 +1,119 @@
+/**
+ * Cart drawer labels — default English copy.
+ *
+ * Every user-facing string in the cart drawer comes from a `CartDrawerLabels`
+ * object. Stores override strings by passing a partial labels object to
+ * `CartDrawerProvider`. English is the baseline; stores wanting Bulgarian,
+ * German, etc. pass their own translations.
+ *
+ * Ported from `@1click/ui/src/cart-drawer/labels.ts` (v2.3.1). Barter
+ * additions: the summary-breakdown row labels (`discount`, `tax`, `codFee`,
+ * `giftCard`, `remainingToPay`) — the decorated cart carries
+ * discount/tax/COD-fee/gift-card tender fields that the breakdown renders,
+ * so the copy for those rows lives here too.
+ */
+
+export type CartDrawerLabels = {
+  // Header
+  yourCart: string
+  item: string
+  items: string
+  closeCart: string
+
+  // Empty state
+  emptyCartTitle: string
+  emptyCartMessage: string
+  browseProducts: string
+
+  // Tiered progress
+  awayFromFreeShipping: string
+  allRewardsUnlocked: string
+
+  // Gift wrap / notes
+  addGiftWrap: string
+  giftNote: string
+  orderNote: string
+  giftNotePlaceholder: string
+  orderNotePlaceholder: string
+
+  // Rewards
+  estimatedRewardPoints: string
+
+  // Cross-sell
+  pairsWellWith: string
+  youllLoveThis: string
+  youMightAlsoLike: string
+  addToCart: string
+
+  // Summary / footer
+  subtotal: string
+  taxAndShipping: string
+  shipping: string
+  free: string
+  calculatedAtCheckout: string
+  total: string
+  secureCheckout: string
+  shippingAndTaxCalculatedAtCheckout: string
+
+  // Summary breakdown rows (barter decorated-cart fields)
+  discount: string
+  tax: string
+  /** Fallback only — the server's `cod_fee_label` wins when present. */
+  codFee: string
+  /** Prefix for an applied gift-card row; rendered as `<giftCard> ••1234`. */
+  giftCard: string
+  /** Label for `gift_card_remainder` — what the remainder provider charges. */
+  remainingToPay: string
+
+  // Continue shopping
+  continueShopping: string
+
+  // A11y / buttons
+  remove: string
+}
+
+export const defaultCartDrawerLabels: CartDrawerLabels = {
+  yourCart: "Your cart",
+  item: "item",
+  items: "items",
+  closeCart: "Close cart",
+
+  emptyCartTitle: "Your cart is empty",
+  emptyCartMessage: "You haven't added any products yet.",
+  browseProducts: "Browse products",
+
+  awayFromFreeShipping: "away from free shipping",
+  allRewardsUnlocked: "All rewards unlocked",
+
+  addGiftWrap: "Add gift wrapping",
+  giftNote: "Gift note",
+  orderNote: "Order note",
+  giftNotePlaceholder: "Add a personal message...",
+  orderNotePlaceholder: "Special instructions for this order...",
+
+  estimatedRewardPoints: "Estimated reward points",
+
+  pairsWellWith: "Pairs well with",
+  youllLoveThis: "You'll love this",
+  youMightAlsoLike: "You might also like",
+  addToCart: "Add",
+
+  subtotal: "Subtotal",
+  taxAndShipping: "VAT included. Shipping calculated at checkout.",
+  shipping: "Shipping",
+  free: "FREE",
+  calculatedAtCheckout: "Calculated at checkout",
+  total: "Total",
+  secureCheckout: "Checkout",
+  shippingAndTaxCalculatedAtCheckout: "Shipping and tax calculated at checkout",
+
+  discount: "Discount",
+  tax: "VAT",
+  codFee: "Cash on delivery fee",
+  giftCard: "Gift card",
+  remainingToPay: "Remaining to pay",
+
+  continueShopping: "Continue shopping",
+
+  remove: "Remove",
+}