@cartbase/storefront 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Storefront SDK + UI component library for Cartbase stores: typed API client, checkout orchestration, cart drawer, product/catalog components, tracking. Source-shipped TypeScript — add it to transpilePackages.",
   "license": "MIT",
   "repository": {
@@ -103,7 +103,6 @@
     "./checkout": "./src/checkout/index.ts",
     "./checkout/context": "./src/checkout/context.tsx",
     "./checkout/labels": "./src/checkout/labels.ts",
-    "./checkout/labels-bg": "./src/checkout/labels-bg.ts",
     "./checkout/error-message": "./src/checkout/error-message.tsx",
     "./checkout/stripe-wrapper": "./src/checkout/stripe-wrapper.tsx",
     "./checkout/payment-wrapper": "./src/checkout/payment-wrapper.tsx",
@@ -127,7 +126,6 @@
     "./cart-drawer": "./src/cart-drawer/index.ts",
     "./cart-drawer/context": "./src/cart-drawer/context.tsx",
     "./cart-drawer/labels": "./src/cart-drawer/labels.ts",
-    "./cart-drawer/labels-bg": "./src/cart-drawer/labels-bg.ts",
     "./cart-drawer/cart-drawer": "./src/cart-drawer/cart-drawer.tsx",
     "./cart-drawer/header": "./src/cart-drawer/header.tsx",
     "./cart-drawer/promo-banner": "./src/cart-drawer/promo-banner.tsx",
@@ -151,7 +149,6 @@
     "./products": "./src/products/index.ts",
     "./products/context": "./src/products/context.tsx",
     "./products/labels": "./src/products/labels.ts",
-    "./products/labels-bg": "./src/products/labels-bg.ts",
     "./products/thumbnail": "./src/products/thumbnail.tsx",
     "./products/preview-price": "./src/products/preview-price.tsx",
     "./products/product-price": "./src/products/product-price.tsx",
@@ -167,7 +164,6 @@
     "./products/product-template": "./src/products/product-template.tsx",
     "./store": "./src/store/index.ts",
     "./store/labels": "./src/store/labels.ts",
-    "./store/labels-bg": "./src/store/labels-bg.ts",
     "./store/pagination": "./src/store/pagination.tsx",
     "./store/sort-select": "./src/store/sort-select.tsx",
     "./store/paginated-products": "./src/store/paginated-products.tsx",
@@ -179,7 +175,6 @@
     "./order": "./src/order/index.ts",
     "./order/context": "./src/order/context.tsx",
     "./order/labels": "./src/order/labels.ts",
-    "./order/labels-bg": "./src/order/labels-bg.ts",
     "./order/order-confirmation-header": "./src/order/order-confirmation-header.tsx",
     "./order/order-item": "./src/order/order-item.tsx",
     "./order/order-items-list": "./src/order/order-items-list.tsx",
@@ -195,25 +190,31 @@
     "./common/cart-button": "./src/common/cart-button.tsx",
     "./common/cart-button-client": "./src/common/cart-button-client.tsx",
     "./common/delete-button": "./src/common/delete-button.tsx",
+    "./common/country-flag": "./src/common/country-flag.tsx",
     "./common/country-select": "./src/common/country-select.tsx",
     "./common/language-select": "./src/common/language-select.tsx",
     "./common/skeleton": "./src/common/skeleton.tsx",
-    "./reviews-ui": "./src/reviews-ui/index.ts"
+    "./reviews-ui": "./src/reviews-ui/index.ts",
+    "./locales": "./src/locales/index.ts",
+    "./locales/en": "./src/locales/en.ts",
+    "./locales/es": "./src/locales/es.ts",
+    "./locales/bg": "./src/locales/bg.ts"
   },
   "dependencies": {
-    "@stripe/react-stripe-js": "^6.1.0",
-    "@stripe/stripe-js": "^9.1.0",
-    "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-accordion": "^1.2.12",
     "@radix-ui/react-collapsible": "^1.1.12",
     "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-label": "^2.1.8",
     "@radix-ui/react-popover": "^1.1.15",
     "@radix-ui/react-select": "^2.2.6",
     "@radix-ui/react-slot": "^1.2.4",
     "@radix-ui/react-tabs": "^1.1.13",
+    "@stripe/react-stripe-js": "^6.1.0",
+    "@stripe/stripe-js": "^9.1.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
+    "flag-icons": "^7.5.0",
     "lucide-react": "^1.8.0",
     "tailwind-merge": "^3.5.0"
   },

package/src/api/regions.ts

@@ -1,10 +1,11 @@
 /**
- * @cartbase/storefront/api/regions — regions, currencies, locales.
+ * @cartbase/storefront/api/regions — regions, countries, currencies, locales.
  *
  * Catalog-context primitives every storefront resolves at boot: which
- * regions exist (→ `region_id` for the pricing context), which currencies
- * the store has enabled, which locales it serves. All endpoints are anon
- * reads (`x-client-id` scoping via RLS). Docs: docs/storefront/regions.md.
+ * regions exist (→ `region_id` for the pricing context), which countries the
+ * store sells to, which currencies it has enabled, which locales it serves.
+ * All endpoints are anon reads (`x-client-id` scoping via RLS). Docs:
+ * docs/storefront/regions.md.
  */
 import type { StorefrontClient } from "./http"
 import type { IsoDateString, ListEnvelope, PaginationQuery } from "./types"
@@ -12,7 +13,9 @@ import type { IsoDateString, ListEnvelope, PaginationQuery } from "./types"
 /**
  * A store region (`barter_commerce.regions` row). NOTE: Cartbase regions carry
  * NO embedded `countries` array on the store surface (divergence from
- * Medusa's Store API — tax scoping is by `tax_regions` server-side).
+ * Medusa's Store API — tax scoping is by `tax_regions` server-side). The
+ * countries are their own call, `listCountries`, and each row carries the
+ * `region_id` it belongs to.
  */
 export interface StoreRegion {
   id: string
@@ -38,6 +41,35 @@ export interface StoreCurrency {
   updated_at: IsoDateString
 }
 
+/**
+ * A country a shopper may choose (`barter_commerce.countries` row, the store's
+ * own tenant catalogue).
+ */
+export interface StoreCountry {
+  /** Lowercase ISO-3166 alpha-2, e.g. "bg" — the value a cart address takes. */
+  iso_2: string
+  /** What a shopper reads, e.g. "Bulgaria". The code is never shown as copy. */
+  display_name: string
+  /** The catalogue's uppercase form, e.g. "BULGARIA". */
+  name: string
+  /** The region this country belongs to, null when the store has not placed it. */
+  region_id: string | null
+}
+
+export interface ListCountriesQuery extends PaginationQuery {
+  /** Case-insensitive substring match on the displayed name. */
+  q?: string
+}
+
+export interface CountryListResponse extends ListEnvelope {
+  countries: StoreCountry[]
+  /**
+   * True when this list IS the store's Markets declaration; false when the
+   * store has declared nothing and this is the whole ISO catalogue.
+   */
+  restricted: boolean
+}
+
 export interface ListRegionsQuery extends PaginationQuery {
   /** Case-insensitive substring match on region name. */
   q?: string
@@ -98,6 +130,33 @@ export async function retrieveRegion(
   return client.get(`/api/store/regions/${encodeURIComponent(regionId)}`)
 }
 
+/**
+ * List the countries a shopper may choose at checkout, ordered by the name
+ * they read.
+ *
+ * THE RULE IS THE PLATFORM'S, NOT THE STOREFRONT'S: the store's own Markets
+ * decide where it sells, and a store that has decided nothing yet sells to
+ * the whole world. So this answers with the countries the store's regions
+ * declare, and with the whole 250-entry catalogue when it declares none;
+ * `restricted` says which you got. A storefront therefore never hardcodes a
+ * country list, and never has to invent a fallback of its own.
+ *
+ * `useCheckoutOrchestration` calls this for you when you do not pass it a
+ * `countries` list, so a new store offers every country with no wiring at
+ * all. Pass your own list only to override the store's answer.
+ *
+ * Auth: anon (`x-client-id`). Errors: 400 `missing_client_id`,
+ * 400 `validation_failed`. Settings: Admin → Settings → Markets → Regions,
+ * where a region owns its countries; `limit` 1–300 (default 300, so one
+ * call carries the entire catalogue).
+ */
+export async function listCountries(
+  client: StorefrontClient,
+  query?: ListCountriesQuery
+): Promise<CountryListResponse> {
+  return client.get("/api/store/countries", { query: { ...query } })
+}
+
 /**
  * List the currencies ENABLED on this store (the `store_currencies` link
  * filters the shared currency catalog). A store with none enabled returns an

package/src/cart-drawer/index.ts

@@ -28,7 +28,6 @@ export {
   defaultCartDrawerLabels,
   type CartDrawerLabels,
 } from "./labels"
-export { bulgarianCartDrawerLabels } from "./labels-bg"
 
 export { CartDrawer } from "./cart-drawer"
 export { CartDrawerHeader } from "./header"

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

@@ -1,119 +1,117 @@
-/**
- * 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 Cartbase 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 =
-  "Няма връзка със сървъра. Моля, проверете интернет връзката и опитайте отново."
-
-/**
- * Cartbase 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 Cartbase 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)
-}
+import type { AddressErrorCopy } from "./labels"
+
+/**
+ * Recognizes an address-save failure and picks the copy for it.
+ *
+ * THE COPY IS NOT HERE. Until 2026-09-13 this file held thirteen hardcoded
+ * BULGARIAN sentences, so every merchant who installed the package showed
+ * Bulgarian on the one screen where a shopper is about to pay, with no way
+ * to override it. The copy now lives in the checkout label pack like all
+ * other copy, which means it is English by default and translated by
+ * whichever locale the store mounts.
+ *
+ * WHAT STAYS HERE IS THE RECOGNITION, and it stays on purpose: the codes
+ * and the patterns match the API's own error text, which is English wire
+ * format, not user-facing copy. Translating the matcher would break it.
+ *
+ * Ported from `@1click/ui/src/checkout/address-error-copy.ts` (v2.3.1) and
+ * adapted to the Cartbase error envelope: `StoreApiError` carries a
+ * structured `code` (POST /api/store/carts/:id, docs/storefront/carts.md),
+ * so recognition is code-first and the substring patterns are the fallback
+ * for network failures and any legacy wire.
+ *
+ * The mapping is deliberately narrow: only failures we recognize get their
+ * own sentence, and everything else gets the generic one rather than
+ * half-translated technical text.
+ */
+
+/** Cartbase cart-update error codes, mapped to a copy key. Code-first. */
+export const ADDRESS_CODE_KEYS: Record<string, keyof AddressErrorCopy> = {
+  validation_failed: "validationFailed",
+  invalid_region: "invalidRegion",
+  region_required: "regionRequired",
+  cart_completed: "cartCompleted",
+  cart_not_found: "cartNotFound",
+}
+
+/**
+ * Patterns matched in order, first match wins: most specific first,
+ * generic last. Case-insensitive. Kept verbatim from the production port.
+ */
+const PATTERNS: Array<{ match: RegExp; key: keyof AddressErrorCopy }> = [
+  // 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,
+    key: "invalidEmail",
+  },
+  {
+    match:
+      /invalid[\s_]?postal|invalid[\s_]?post(?:code|al[\s_]?code)|postal[\s_]?code[\s_]?(?:is[\s_]?)?invalid/i,
+    key: "invalidPostalCode",
+  },
+  {
+    match: /invalid[\s_]?phone|phone[\s_]?(?:number[\s_]?)?(?:is[\s_]?)?invalid/i,
+    key: "invalidPhone",
+  },
+  {
+    match:
+      /invalid[\s_]?country|country[\s_]?(?:code[\s_]?)?(?:is[\s_]?)?invalid|no[\s_]?region|invalid[\s_]?region/i,
+    key: "invalidCountry",
+  },
+  // Cart already completed — race with order placement.
+  {
+    match:
+      /cart[\s_]?(?:is[\s_]?)?already[\s_]?completed|already[\s_]?an[\s_]?order|completed[\s_]?cart/i,
+    key: "cartCompleted",
+  },
+  {
+    match: /cart[\s_]?(?:not[\s_]?found|does[\s_]?not[\s_]?exist|expired)/i,
+    key: "cartNotFound",
+  },
+  {
+    match: /failed[\s_]?to[\s_]?fetch|network[\s_]?error|networkerror|econnreset|etimedout/i,
+    key: "network",
+  },
+  // The Next.js canned Server Components production message — surface a
+  // clean fallback instead of the English placeholder. (The Cartbase 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,
+    key: "generic",
+  },
+]
+
+/** Which copy an error asks for, independent of language. */
+export function addressErrorKey(err: unknown): keyof AddressErrorCopy {
+  if (err && typeof err === "object") {
+    const code = (err as { code?: unknown }).code
+    if (typeof code === "string" && ADDRESS_CODE_KEYS[code]) return ADDRESS_CODE_KEYS[code]
+  }
+  const raw = extractMessage(err)
+  if (!raw) return "generic"
+  for (const { match, key } of PATTERNS) {
+    if (match.test(raw)) return key
+  }
+  return "generic"
+}
+
+/**
+ * Turn any thrown or returned address-save error into the sentence a
+ * shopper reads, in the store's own language.
+ */
+export function translateAddressError(err: unknown, copy: AddressErrorCopy): string {
+  return copy[addressErrorKey(err)]
+}
+
+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)
+}

package/src/checkout/address-form.tsx

@@ -4,6 +4,7 @@ import type { ChangeEvent } from "react"
 
 import type { CartAddress } from "../api/carts"
 import type { CustomerAddress } from "../api/customers"
+import { CountryFlag } from "../common/country-flag"
 import { Field } from "../primitives/field"
 import { SelectField } from "../primitives/select-field"
 import { AddressSelect } from "./address-select"
@@ -127,6 +128,11 @@ export function CheckoutAddressForm({
               value={formData["shipping_address.country_code"] ?? ""}
               onChange={onChange}
               required
+              // The chosen country's flag, inside the control. It stays a
+              // NATIVE select on purpose: a custom listbox would draw a flag
+              // per row but lose `autocomplete="country"` and the phone's own
+              // picker, and a checkout does not trade autofill for decoration.
+              leading={<CountryFlag code={formData["shipping_address.country_code"]} />}
             >
               <option value="" disabled />
               {countries.map((c) => (