@cartbase/storefront 0.1.0

package/src/common/cart-button-client.tsx

@@ -0,0 +1,39 @@
+"use client"
+
+import { ShoppingBag } from "lucide-react"
+import type { Cart } from "../api/carts"
+import { productItemCount } from "../lib/cart-helpers"
+import { useCartDrawer } from "../cart-drawer/context"
+
+/**
+ * Header cart button (badge + opens the cart drawer). Ported from
+ * `@1click/ui/src/common/cart-button-client.tsx` (v2.3.1); seams:
+ *
+ *  - `cart` is the barter decorated cart (`api/carts` `Cart`).
+ *  - Badge count uses `productItemCount` (fee-line-aware) instead of the
+ *    source's raw `reduce` — keeps the badge consistent with the cart
+ *    drawer's own count, which already excludes backend-injected fee
+ *    lines (see `lib/cart-helpers` provenance note).
+ *
+ * NOTE: depends on the sibling `cart-drawer` family's context (ported in
+ * the same batch); mount inside `<CartDrawerProvider>`.
+ */
+export function CartButtonClient({ cart }: { cart: Cart | null }) {
+  const { open } = useCartDrawer()
+  const totalItems = productItemCount(cart?.items)
+
+  return (
+    <button
+      onClick={open}
+      className="flex items-center gap-1.5 hover:text-foreground transition-colors relative"
+      data-testid="nav-cart-link"
+    >
+      <ShoppingBag className="w-5 h-5" />
+      {totalItems > 0 && (
+        <span className="absolute -top-1.5 -right-2 min-w-[18px] h-[18px] bg-foreground text-card text-[10px] font-semibold rounded-full flex items-center justify-center px-1">
+          {totalItems}
+        </span>
+      )}
+    </button>
+  )
+}

package/src/common/cart-button.tsx

@@ -0,0 +1,28 @@
+import { retrieveCart } from "../api/carts"
+import type { StorefrontClient } from "../api/http"
+import { CartButtonClient } from "./cart-button-client"
+
+/**
+ * Server wrapper for the header cart button. Ported from
+ * `@1click/ui/src/common/cart-button.tsx` (v2.3.1); data seam: the source
+ * called the cookie-reading `retrieveCart()` server action — barter takes
+ * the `StorefrontClient` + the app-persisted cart id explicitly (the app
+ * owns the cart-id cookie, see docs/storefront/carts.md) and calls
+ * `api/carts.retrieveCart`. Any fetch failure (stale id, 404) degrades to
+ * an empty button, same as the source's `.catch(() => null)`.
+ */
+export async function CartButton({
+  client,
+  cartId,
+}: {
+  client: StorefrontClient
+  /** The app's persisted cart id; null/undefined renders an empty button. */
+  cartId?: string | null
+}) {
+  const cart = cartId
+    ? await retrieveCart(client, cartId)
+        .then((res) => res.cart)
+        .catch(() => null)
+    : null
+  return <CartButtonClient cart={cart} />
+}

package/src/common/country-select.tsx

@@ -0,0 +1,65 @@
+"use client"
+
+import { useMemo } from "react"
+import type { StoreRegion } from "../api/regions"
+
+/**
+ * Region picker for the storefront footer/header. Ported from
+ * `@1click/ui/src/common/country-select.tsx` (v2.3.1) with a REAL model
+ * change forced by the SDK (SDK wins over the source):
+ *
+ *  - Medusa regions embedded a `countries[]` array and the select listed
+ *    countries; barter regions carry NO countries on the store surface
+ *    (divergence documented in `api/regions` — tax scoping is by
+ *    `tax_regions` server-side). The select therefore lists the REGIONS
+ *    themselves (`regions.listRegions`), valued by region id.
+ *  - The source called the `updateRegion(countryCode, path)` server
+ *    action bound to URL `[countryCode]` routing; barter region
+ *    persistence is app-owned (usually `carts.updateCart(client, cartId,
+ *    {region_id})` + a cookie) — so the change surfaces via `onChange`.
+ */
+type CountrySelectProps = {
+  regions: StoreRegion[]
+  /** Currently active region id. */
+  value?: string | null
+  /** Fired with the selected region; persist it app-side. */
+  onChange: (region: StoreRegion) => void
+  className?: string
+}
+
+export function CountrySelect({
+  regions,
+  value,
+  onChange,
+  className,
+}: CountrySelectProps) {
+  const options = useMemo(
+    () =>
+      [...regions].sort((a, b) => (a.name ?? "").localeCompare(b.name ?? "")),
+    [regions]
+  )
+
+  const handleChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
+    const selected = options.find((r) => r.id === e.target.value)
+    if (selected) onChange(selected)
+  }
+
+  return (
+    <select
+      value={value || ""}
+      onChange={handleChange}
+      className={
+        className ??
+        "text-sm text-foreground bg-card border border-border rounded-lg px-3 py-2"
+      }
+    >
+      {options.map((r) => (
+        <option key={r.id} value={r.id}>
+          {r.name}
+        </option>
+      ))}
+    </select>
+  )
+}
+
+export { type CountrySelectProps }

package/src/common/delete-button.tsx

@@ -0,0 +1,66 @@
+"use client"
+
+import { useState } from "react"
+import { Loader2, Trash2 } from "lucide-react"
+import { deleteLineItem } from "../api/carts"
+import type { StorefrontClient } from "../api/http"
+import { cn } from "../lib/utils"
+
+/**
+ * Cart-line delete button with spinner. Ported from
+ * `@1click/ui/src/common/delete-button.tsx` (v2.3.1); data seam: the
+ * source called the cookie-scoped `deleteLineItem(id)` server action —
+ * barter calls `api/carts.deleteLineItem(client, cartId, lineItemId)`
+ * (idempotent server-side) and hands the refreshed cart to `onDeleted`
+ * so the app can update its state / `router.refresh()`. The spinner
+ * resets on failure exactly like the source's `.catch`.
+ */
+type DeleteButtonProps = {
+  client: StorefrontClient
+  cartId: string
+  /** Line item id to remove. */
+  id: string
+  /** Called with the refreshed cart response after a successful delete. */
+  onDeleted?: (cart: Awaited<ReturnType<typeof deleteLineItem>>) => void
+  children?: React.ReactNode
+  className?: string
+}
+
+export function DeleteButton({
+  client,
+  cartId,
+  id,
+  onDeleted,
+  children,
+  className,
+}: DeleteButtonProps) {
+  const [isDeleting, setIsDeleting] = useState(false)
+
+  const handleDelete = async () => {
+    setIsDeleting(true)
+    try {
+      const res = await deleteLineItem(client, cartId, id)
+      onDeleted?.(res)
+    } catch {
+      setIsDeleting(false)
+    }
+  }
+
+  return (
+    <div className={cn("flex items-center justify-between text-sm", className)}>
+      <button
+        className="flex gap-x-1 text-muted-foreground hover:text-foreground cursor-pointer"
+        onClick={handleDelete}
+      >
+        {isDeleting ? (
+          <Loader2 className="w-4 h-4 animate-spin" />
+        ) : (
+          <Trash2 className="w-4 h-4" />
+        )}
+        <span>{children}</span>
+      </button>
+    </div>
+  )
+}
+
+export { type DeleteButtonProps }

package/src/common/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @cartbase/storefront/common — shared storefront chrome. Ported from
+ * `@1click/ui/src/common` (v2.3.1) + `LocalizedLink` (from the
+ * mindpages-storefront production component); barter data seams per
+ * module JSDoc.
+ */
+export { LocalizedLink, type LocalizedLinkProps } from "./localized-link"
+export { CartButton } from "./cart-button"
+export { CartButtonClient } from "./cart-button-client"
+export { DeleteButton, type DeleteButtonProps } from "./delete-button"
+export { CountrySelect, type CountrySelectProps } from "./country-select"
+export {
+  LanguageSelect,
+  localeDisplayName,
+  type LanguageSelectProps,
+} from "./language-select"
+export { Skeleton, SkeletonProductPreview } from "./skeleton"

package/src/common/language-select.tsx

@@ -0,0 +1,78 @@
+"use client"
+
+import { useTransition } from "react"
+
+/**
+ * Storefront language switcher. Ported from
+ * `@1click/ui/src/common/language-select.tsx` (v2.3.1); data seam:
+ *
+ *  - The locale list feeds from `api/regions.listLocales(client)` — an
+ *    array of bare codes, store default first (barter has no `{code,
+ *    name}` locale objects on the store surface; SDK wins). Display
+ *    names resolve via `localeDisplayName()` below (native-language
+ *    autonym through `Intl.DisplayNames`), overridable per store with
+ *    the `labels` map.
+ *  - The source awaited an `updateLocale(code)` server action then
+ *    `router.refresh()`; barter locale persistence is app-owned (the
+ *    cookie read by `StorefrontClient.getLocale`) — the async `onChange`
+ *    callback carries it, and the `useTransition` pending-disable UX is
+ *    preserved around it.
+ */
+
+/** Best-effort native display name for a locale code ("bg" → "български"). */
+export function localeDisplayName(code: string): string {
+  try {
+    const name = new Intl.DisplayNames([code], { type: "language" }).of(code)
+    return name || code
+  } catch {
+    return code
+  }
+}
+
+type LanguageSelectProps = {
+  /** Locale codes from `regions.listLocales` (store default first). */
+  locales: string[]
+  currentLocale: string | null
+  /** Persist the choice (cookie / server action) — awaited in a transition. */
+  onChange: (code: string) => void | Promise<void>
+  /** Optional per-store display-name overrides, keyed by code. */
+  labels?: Record<string, string>
+  className?: string
+}
+
+export function LanguageSelect({
+  locales,
+  currentLocale,
+  onChange,
+  labels,
+  className,
+}: LanguageSelectProps) {
+  const [isPending, startTransition] = useTransition()
+
+  const handleChange = (e: React.ChangeEvent<HTMLSelectElement>) => {
+    const code = e.target.value
+    startTransition(async () => {
+      await onChange(code)
+    })
+  }
+
+  return (
+    <select
+      value={currentLocale || ""}
+      onChange={handleChange}
+      disabled={isPending}
+      className={
+        className ??
+        "text-sm text-foreground bg-card border border-border rounded-lg px-3 py-2 disabled:opacity-50"
+      }
+    >
+      {locales.map((code) => (
+        <option key={code} value={code}>
+          {labels?.[code] ?? localeDisplayName(code)}
+        </option>
+      ))}
+    </select>
+  )
+}
+
+export { type LanguageSelectProps }

package/src/common/localized-link.tsx

@@ -0,0 +1,45 @@
+"use client"
+
+import Link from "next/link"
+import { useParams } from "next/navigation"
+import type { ReactNode } from "react"
+
+/**
+ * `<Link />` that persists the current URL locale/country segment without
+ * the caller passing it explicitly. Ported from the mindpages-storefront
+ * `LocalizedClientLink` (src/modules/common/components/localized-client-link)
+ * — the component `@1click/ui` consumers used for the same job.
+ *
+ * barter seam: barter storefronts default to COOKIE-based locale
+ * (`StorefrontClient.getLocale`, see docs/storefront/BUILD-A-STOREFRONT.md)
+ * with no mandatory URL segment — so the prefix is applied ONLY when the
+ * route actually has a `[countryCode]` (or custom `paramName`) dynamic
+ * param. On non-prefixed apps this renders a plain `next/link`.
+ */
+export interface LocalizedLinkProps {
+  children?: ReactNode
+  href: string
+  className?: string
+  onClick?: () => void
+  passHref?: true
+  /** Route param that carries the URL prefix. Default: `countryCode`. */
+  paramName?: string
+  [x: string]: unknown
+}
+
+export function LocalizedLink({
+  children,
+  href,
+  paramName = "countryCode",
+  ...props
+}: LocalizedLinkProps) {
+  const params = useParams()
+  const raw = params?.[paramName]
+  const prefix = typeof raw === "string" && raw ? `/${raw}` : ""
+
+  return (
+    <Link href={`${prefix}${href}`} {...props}>
+      {children}
+    </Link>
+  )
+}

package/src/common/skeleton.tsx

@@ -0,0 +1,29 @@
+import { cn } from "../lib/utils"
+
+/**
+ * Loading skeletons. Verbatim port of `@1click/ui/src/common/skeleton.tsx`
+ * (v2.3.1) — pure UI over theme tokens.
+ */
+type SkeletonProps = {
+  className?: string
+}
+
+export function Skeleton({ className }: SkeletonProps) {
+  return (
+    <div
+      className={cn("animate-pulse rounded bg-muted", className)}
+    />
+  )
+}
+
+export function SkeletonProductPreview() {
+  return (
+    <div className="animate-pulse">
+      <div className="aspect-[9/16] w-full bg-muted rounded-lg" />
+      <div className="flex justify-between mt-2">
+        <div className="w-2/5 h-6 bg-muted rounded" />
+        <div className="w-1/5 h-6 bg-muted rounded" />
+      </div>
+    </div>
+  )
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @cartbase/storefront — root barrel.
+ *
+ * `@cartbase/storefront/api` is the SDK layer (typed store-API client).
+ * Component families ship under their own subpath exports (stage 3) and are
+ * NOT re-exported here — UI imports stay per-module so tree-shaking and
+ * client/server boundaries stay explicit, same discipline as @1click/ui.
+ */
+
+export * from "./api/types"
+export { StorefrontClient } from "./api/http"
+export type { StorefrontClientConfig } from "./api/http"

package/src/lib/cart-helpers.ts

@@ -0,0 +1,113 @@
+/**
+ * Cart line predicates and product-only totals helpers.
+ *
+ * Ported from `@1click/ui/src/lib/cart-helpers.ts` (v2.3.1) with its
+ * production reasoning intact; the `@medusajs/types` generic constraint is
+ * replaced by the structural `LineLike` shape so this module stays decoupled
+ * from any SDK layer (barter cart/order line items are structurally
+ * compatible: they carry `metadata`, `total`, `quantity`).
+ *
+ * Why this exists. There is no native "fee" / "surcharge" primitive in the
+ * order model — the canonical way to add a non-product charge that flows
+ * through totals, tax, and refund pipelines is a line item with a metadata
+ * flag, which is what the COD-fee flow does. The trade-off: that line item
+ * appears in `cart.items` everywhere — the cart drawer, order page, mobile
+ * bars, anything that iterates the cart. Without filtering it appears as a
+ * fake product (empty thumbnail + qty stepper). With each surface filtering
+ * inline we get 8+ copies of the same predicate that drift apart over time.
+ *
+ * Single source of truth. Every customer-facing render surface that
+ * iterates `cart.items` (or `order.items`) calls `isProductLine`.
+ * Every total computed for a customer-facing context (drawer footer,
+ * pre-checkout subtotal display) calls `productTotal`. If we ever add
+ * another surcharge type, the predicate gets one new check; every
+ * surface inherits it.
+ *
+ * Where this is NOT used. The checkout summary and the order totals
+ * intentionally render the fee — there it's a separate "Cash on
+ * delivery fee" row in the totals breakdown, sourced from
+ * `findFeeLine`. Customer SHOULD see the fee in checkout / on the
+ * order; they should NOT see it in the cart drawer pre-checkout.
+ *
+ * Money note (barter): amounts are decimal EUR major units everywhere in
+ * the store API — the arithmetic below is unit-agnostic and unchanged.
+ */
+
+export const COD_FEE_METADATA_KEY = "is_cod_fee"
+
+/** Structural shape of a cart/order line — any richer DTO satisfies it. */
+export type LineLike = {
+  metadata?: Record<string, unknown> | null
+  total?: number | null
+  subtotal?: number | null
+  unit_price?: number | null
+  quantity?: number
+}
+
+/**
+ * Returns true when the line is a customer-facing product (anything
+ * the customer chose to buy), false for backend-injected fee lines.
+ *
+ * Tight check: only excludes lines explicitly tagged `is_cod_fee=true`.
+ * Lines with no metadata, null metadata, or any other metadata pass
+ * through unchanged — never filter a real product because of a
+ * missing flag.
+ */
+export function isProductLine(item: LineLike): boolean {
+  const meta = item.metadata
+  if (!meta || typeof meta !== "object") return true
+  return (meta as Record<string, unknown>)[COD_FEE_METADATA_KEY] !== true
+}
+
+/** Inverse of `isProductLine`. Useful when the caller needs the fee. */
+export function isFeeLine(item: LineLike): boolean {
+  return !isProductLine(item)
+}
+
+/**
+ * Sum of line totals for product lines only. Suitable for cart-drawer
+ * surfaces in pre-checkout context where shipping/tax/fees should NOT
+ * leak into the displayed subtotal.
+ *
+ * Reads `item.total` (gross of tax for tax-inclusive items, post-line-
+ * adjustments) which matches what every cart surface already shows on
+ * a per-line basis — keeps the visible per-line price and the visible
+ * subtotal arithmetically consistent.
+ */
+export function productTotal(items: readonly LineLike[] | null | undefined): number {
+  if (!items?.length) return 0
+  let sum = 0
+  for (const item of items) {
+    if (!isProductLine(item)) continue
+    sum += Number(item.total ?? 0)
+  }
+  return sum
+}
+
+/** Sum of `quantity` over product lines only. */
+export function productItemCount(
+  items: readonly LineLike[] | null | undefined
+): number {
+  if (!items?.length) return 0
+  let count = 0
+  for (const item of items) {
+    if (!isProductLine(item)) continue
+    count += Number(item.quantity ?? 0)
+  }
+  return count
+}
+
+/**
+ * The fee line item from a cart or order, if present. Returns null
+ * when no fee was applied (Card flow, or the COD-fee step skipped due
+ * to config / currency mismatch).
+ */
+export function findFeeLine<T extends LineLike>(
+  items: readonly T[] | null | undefined
+): T | null {
+  if (!items?.length) return null
+  for (const item of items) {
+    if (isFeeLine(item)) return item
+  }
+  return null
+}

package/src/lib/dual-price.tsx

@@ -0,0 +1,73 @@
+"use client"
+
+import * as React from "react"
+
+import { cn } from "./utils"
+import { convertToLocale } from "./money"
+
+/**
+ * DualPrice — render a EUR price with BGN next to it.
+ *
+ * Bulgarian law (Дв, effective through 2026-08) requires showing both EUR
+ * and BGN on every price displayed to consumers. Fixed statutory rate:
+ *   1 EUR = 1.95583 BGN
+ *
+ * For non-EUR currencies the BGN leg is skipped and only the primary locale
+ * currency is shown. The component is stateless and side-effect-free — safe
+ * to render in server components and client components alike.
+ *
+ * The EUR-to-BGN rate and the law's expiry date are baked in for now. When
+ * the law expires (or when a store outside Bulgaria consumes this library),
+ * we'll move both to a BrandingContext value so each store can override.
+ *
+ * @example
+ *   <DualPrice amount={19.99} currencyCode="eur" />
+ *   // → "€19.99  39,10 лв."
+ */
+
+const EUR_TO_BGN = 1.95583
+
+function toBGN(eurAmount: number): string {
+  const bgn = eurAmount * EUR_TO_BGN
+  return bgn.toFixed(2).replace(".", ",") + " лв."
+}
+
+export type DualPriceProps = {
+  /** Amount in major units of the primary currency (e.g. 19.99 for €19.99) */
+  amount: number
+  /** ISO currency code (case-insensitive). Only "eur" triggers the BGN leg. */
+  currencyCode: string
+  /** Optional class for the outer span */
+  className?: string
+  /** Optional class for the BGN leg (defaults to small muted) */
+  bgnClassName?: string
+}
+
+export function DualPrice({
+  amount,
+  currencyCode,
+  className,
+  bgnClassName,
+}: DualPriceProps): React.ReactElement {
+  const isEur = currencyCode?.toLowerCase() === "eur"
+
+  if (!isEur) {
+    return (
+      <span className={className}>
+        {convertToLocale({ amount, currency_code: currencyCode })}
+      </span>
+    )
+  }
+
+  return (
+    <span className={className}>
+      {convertToLocale({ amount, currency_code: currencyCode })}
+      <span className={cn("ml-1.5 text-muted-foreground/70 font-normal", bgnClassName)}>
+        {toBGN(amount)}
+      </span>
+    </span>
+  )
+}
+
+/** Exposed for advanced callers that need the rate directly. */
+export const EUR_TO_BGN_RATE = EUR_TO_BGN

package/src/lib/get-percentage-diff.ts

@@ -0,0 +1,5 @@
+export const getPercentageDiff = (original: number, calculated: number) => {
+  const diff = original - calculated
+  const decrease = (diff / original) * 100
+  return decrease.toFixed()
+}