@cartbase/storefront 0.10.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.10.0",
+  "version": "0.12.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": {
@@ -51,6 +51,7 @@
     "./lib/sort-products": "./src/lib/sort-products.ts",
     "./lib/price": "./src/lib/price.tsx",
     "./lib/payment-constants": "./src/lib/payment-constants.ts",
+    "./lib/country-name": "./src/lib/country-name.ts",
     "./lib/store-api-error": "./src/lib/store-api-error.ts",
     "./lib/hooks/use-intersection": "./src/lib/hooks/use-intersection.ts",
     "./lib/hooks/use-toggle-state": "./src/lib/hooks/use-toggle-state.ts",
@@ -190,6 +191,7 @@
     "./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",
@@ -200,19 +202,20 @@
     "./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/checkout/address-form.tsx

@@ -4,6 +4,8 @@ import type { ChangeEvent } from "react"
 
 import type { CartAddress } from "../api/carts"
 import type { CustomerAddress } from "../api/customers"
+import { CountryFlag } from "../common/country-flag"
+import { countryName } from "../lib/country-name"
 import { Field } from "../primitives/field"
 import { SelectField } from "../primitives/select-field"
 import { AddressSelect } from "./address-select"
@@ -104,20 +106,26 @@ export function CheckoutAddressForm({
 
         {!hideCountry && (
           countries.length === 1 ? (
-            // Single-country region — render a readonly field showing
-            // the localized country name. (Library-default rendering
-            // when `hideCountry` isn't passed.) The actual country_code
-            // remains in formData so submission still carries it.
+            // One country — a read-only field showing its name, with its
+            // flag, so a fixed country reads the same as a chosen one. The
+            // actual country_code stays in formData, so submission still
+            // carries it.
+            //
+            // The name has THREE sources and never falls through to blank
+            // (it did until 2026-09-13, which is how evoo showed an empty
+            // Country box): the store's own word for it, the catalogue's
+            // name, then the code resolved through the runtime.
             <Field
               label={labels.country}
               name="shipping_address.country_code_display"
               value={
-                labels.singleCountryName ??
-                countries[0]?.display_name ??
-                ""
+                labels.singleCountryName ||
+                countries[0]?.display_name ||
+                countryName(countries[0]?.iso_2)
               }
               onChange={() => {}}
               readOnly
+              leading={<CountryFlag code={countries[0]?.iso_2} />}
             />
           ) : (
             <SelectField
@@ -127,6 +135,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) => (

package/src/checkout/context.tsx

@@ -50,6 +50,22 @@ export function useOrderConfirmedPath(): string {
   return useContext(CheckoutContext).orderConfirmedPath
 }
 
+/**
+ * A NESTED PROVIDER INHERITS, it does not reset (fixed 2026-09-13).
+ *
+ * This used to merge over `defaultCheckoutLabels`, which are English, so a
+ * store that mounted a second provider purely to set `orderConfirmedPath`
+ * silently threw away its whole language. That is not a hypothetical: the
+ * reference storefront does exactly that on its checkout page, so every
+ * scaffolded store ran an English checkout no matter which locale it
+ * mounted, and the Bulgarian `singleCountryName` vanished with the rest,
+ * leaving an EMPTY country field. Alexander found it on evoo.
+ *
+ * Reading the enclosing value first makes both cases right: with no
+ * provider above, the context default IS the English baseline, so a single
+ * provider behaves exactly as before; with one above, only the keys this
+ * one names change.
+ */
 export function CheckoutProvider({
   labels: labelOverrides,
   orderConfirmedPath,
@@ -59,15 +75,16 @@ export function CheckoutProvider({
   orderConfirmedPath?: string
   children: ReactNode
 }) {
+  const inherited = useContext(CheckoutContext)
   const labels: CheckoutLabels = {
-    ...defaultCheckoutLabels,
+    ...inherited.labels,
     ...labelOverrides,
   }
   return (
     <CheckoutContext.Provider
       value={{
         labels,
-        orderConfirmedPath: orderConfirmedPath ?? DEFAULT_CONFIRMED_PATH,
+        orderConfirmedPath: orderConfirmedPath ?? inherited.orderConfirmedPath,
       }}
     >
       {children}

package/src/checkout/use-checkout-orchestration.ts

@@ -10,6 +10,8 @@ import {
 } from "react"
 
 import type { StorefrontClient } from "../api/http"
+import { countryName } from "../lib/country-name"
+import { listCountries, type StoreCountry } from "../api/regions"
 import {
   completeCart,
   updateCart,
@@ -362,17 +364,57 @@ export function useCheckoutOrchestration({
       : true
   )
 
-  // Cartbase regions have no embedded countries — the caller-supplied list
-  // (or the countryCode fallback) is the authority for both the select
-  // options and the saved-address region filter.
+  /**
+   * The store's own country list, fetched when the app did not pass one.
+   *
+   * Until 2026-09-13 an app that passed nothing got a ONE-ENTRY list built
+   * from `countryCode`, and the address form renders a read-only box for a
+   * single entry, so every scaffolded store shipped a checkout offering
+   * exactly one country that the shopper could not change. The list is the
+   * platform's to answer (`GET /api/store/countries`: the store's Markets
+   * when it has declared any, the whole catalogue when it has not), so the
+   * hook asks instead of guessing.
+   *
+   * A failure here must never block a checkout: the `countryCode` fallback
+   * below still stands, and the error is reported through `logError`.
+   */
+  const [storeCountries, setStoreCountries] = useState<StoreCountry[] | null>(null)
+  const appSuppliedCountries = !!(countries && countries.length)
+
+  useEffect(() => {
+    if (appSuppliedCountries) return
+    let alive = true
+    listCountries(client)
+      .then((res) => {
+        if (alive) setStoreCountries(res.countries)
+      })
+      .catch((e: unknown) => {
+        logError(
+          "country_list_failed",
+          e instanceof Error ? e.message : "could not load the country list"
+        )
+      })
+    return () => {
+      alive = false
+    }
+  }, [client, appSuppliedCountries, logError])
+
+  // The app's own list wins, then the store's, then the single-country
+  // fallback. This is the authority for both the select options and the
+  // saved-address region filter.
   const regionCountries = useMemo(
     () =>
       countries && countries.length
         ? countries
-        : countryCode
-          ? [{ iso_2: countryCode, display_name: "" }]
-          : [],
-    [countries, countryCode]
+        : storeCountries && storeCountries.length
+          ? storeCountries
+          : countryCode
+            ? // A fallback country still needs a NAME: this used to be an
+              // empty string, and the address form rendered a blank country
+              // field for it (evoo, 2026-09-13).
+              [{ iso_2: countryCode, display_name: countryName(countryCode) }]
+            : [],
+    [countries, storeCountries, countryCode]
   )
 
   const countriesInRegion = useMemo(

package/src/common/country-flag.tsx

@@ -0,0 +1,52 @@
+import "flag-icons/css/flag-icons.min.css"
+
+import { cn } from "../lib/utils"
+
+/**
+ * A country's flag, from its ISO-3166 alpha-2 code.
+ *
+ * WHY A SPRITE AND NOT AN EMOJI: the emoji flag (🇧🇬) costs nothing and is
+ * the obvious choice, but Windows ships no flag glyphs in Segoe UI Emoji, so
+ * a Windows shopper reads the two letters "BG" instead of a flag. `flag-icons`
+ * is SVG under a CSS class, so it renders identically on every platform. It is
+ * also the same sprite the Cartbase admin draws its flags with, so a merchant
+ * sees one country treatment across the admin and their storefront.
+ *
+ * The aspect ratio is the sprite's own 4:3, sized in `em` so a flag matches
+ * the text it sits beside at any font size.
+ *
+ * Decorative by default: a flag never carries meaning a shopper cannot get
+ * from the name next to it, so it is `aria-hidden` and screen readers read
+ * the name. Pass `title` for a tooltip when the flag stands alone.
+ */
+export function CountryFlag({
+  code,
+  title,
+  className,
+}: {
+  /** ISO-3166 alpha-2, any case. Unknown or empty renders a neutral placeholder. */
+  code: string | null | undefined
+  title?: string
+  className?: string
+}) {
+  const iso2 = code?.trim().toLowerCase()
+
+  // A placeholder rather than nothing: the box holds its space, so a field
+  // does not jump when a shopper picks their country.
+  if (!iso2 || !/^[a-z]{2}$/.test(iso2)) {
+    return (
+      <span
+        className={cn("inline-block w-[1.33em] h-[1em] rounded-[2px] bg-muted", className)}
+        aria-hidden
+      />
+    )
+  }
+
+  return (
+    <span
+      className={cn(`fi fi-${iso2}`, "inline-block w-[1.33em] h-[1em] rounded-[2px] shrink-0", className)}
+      title={title}
+      aria-hidden
+    />
+  )
+}

package/src/common/index.ts

@@ -8,6 +8,7 @@ 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 { CountryFlag } from "./country-flag"
 export { CountrySelect, type CountrySelectProps } from "./country-select"
 export {
   LanguageSelect,

package/src/lib/country-name.ts

@@ -0,0 +1,59 @@
+/**
+ * The name of a country, from its ISO-3166 alpha-2 code.
+ *
+ * A code is a machine string: "bg" is how a cart address stores a country,
+ * never how a shopper reads it. The catalogue from
+ * `GET /api/store/countries` carries real names, so this is for the one case
+ * where a code arrives WITHOUT one: the checkout hook's fallback when the
+ * country list cannot be loaded. It used to hand the address form
+ * `{iso_2: "bg", display_name: ""}`, and the form rendered an EMPTY country
+ * field (found on evoo, 2026-09-13).
+ *
+ * `Intl.DisplayNames` is in the runtime, so this needs no bundled table and
+ * knows every country in every language the browser does.
+ *
+ * THE LOCALE IS EXPLICIT AND DEFAULTS TO ENGLISH ON PURPOSE. Letting Intl
+ * pick the runtime default would name the country in the SERVER's language
+ * during a server render and in the BROWSER's language after hydration,
+ * which is a hydration mismatch on any store whose visitors are not in the
+ * server's locale. Pass the store's own language to translate it:
+ *
+ *   const locale = useStorefrontLocale()
+ *   countryName("bg", locale.code)   // "България"
+ *
+ * Three behaviours verified against the runtime rather than assumed
+ * (2026-09-13): a LOWERCASE code returns itself unchanged, so the code is
+ * uppercased here; a malformed code throws `RangeError`, so it is shape
+ * checked and wrapped; and an unknown-but-well-formed code resolves to
+ * "Unknown Region" unless `fallback: "none"` is set, which is why it is set
+ * and why the uppercase code is the last resort.
+ */
+
+const cache = new Map<string, Intl.DisplayNames>()
+
+function namer(locale: string): Intl.DisplayNames | null {
+  const hit = cache.get(locale)
+  if (hit) return hit
+  try {
+    const made = new Intl.DisplayNames([locale], { type: "region", fallback: "none" })
+    cache.set(locale, made)
+    return made
+  } catch {
+    return null
+  }
+}
+
+export function countryName(
+  code: string | null | undefined,
+  locale: string = "en"
+): string {
+  const iso2 = code?.trim()
+  if (!iso2 || !/^[a-z]{2}$/i.test(iso2)) return ""
+
+  const upper = iso2.toUpperCase()
+  try {
+    return namer(locale)?.of(upper) || upper
+  } catch {
+    return upper
+  }
+}

package/src/order/context.tsx

@@ -9,6 +9,13 @@ import { defaultOrderLabels, type OrderLabels } from "./labels"
 
 const OrderLabelsContext = createContext<OrderLabels>(defaultOrderLabels)
 
+/**
+ * A nested provider INHERITS the one above it rather than resetting to the
+ * English defaults (fixed 2026-09-13, the same defect that made evoo's
+ * checkout English: see `checkout/context.tsx`). With no provider above,
+ * the context default IS the English baseline, so a single provider behaves
+ * exactly as before.
+ */
 export function OrderLabelsProvider({
   labels,
   children,
@@ -16,9 +23,8 @@ export function OrderLabelsProvider({
   labels?: Partial<OrderLabels>
   children: ReactNode
 }) {
-  const merged = labels
-    ? { ...defaultOrderLabels, ...labels }
-    : defaultOrderLabels
+  const inherited = useContext(OrderLabelsContext)
+  const merged = labels ? { ...inherited, ...labels } : inherited
 
   return (
     <OrderLabelsContext.Provider value={merged}>

package/src/primitives/field.tsx

@@ -39,6 +39,13 @@ export type FieldProps = React.InputHTMLAttributes<HTMLInputElement> & {
    * confusing it for an error.
    */
   pulse?: boolean
+  /**
+   * A mark shown inside the control, before the value: a flag, a currency
+   * symbol. Decorative and click-through. The value and the floating label
+   * make room for it. Same slot name and behaviour as `SelectField`, so a
+   * country reads the same whether it is chosen or fixed.
+   */
+  leading?: React.ReactNode
 }
 
 export const Field = React.forwardRef<HTMLInputElement, FieldProps>(
@@ -52,6 +59,7 @@ export const Field = React.forwardRef<HTMLInputElement, FieldProps>(
       onFocus,
       onBlur,
       pulse,
+      leading,
       ...props
     },
     ref
@@ -94,7 +102,8 @@ export const Field = React.forwardRef<HTMLInputElement, FieldProps>(
             onBlur?.(e)
           }}
           className={cn(
-            "w-full h-[44px] px-3 pt-[14px] pb-[2px] text-sm rounded-lg border",
+            "w-full h-[44px] pt-[14px] pb-[2px] text-sm rounded-lg border",
+            leading ? "pl-10 pr-3" : "px-3",
             "transition-colors duration-300 outline-none",
             "focus:border-primary focus:bg-primary/5",
             disabled
@@ -109,9 +118,15 @@ export const Field = React.forwardRef<HTMLInputElement, FieldProps>(
           )}
           {...props}
         />
+        {leading && (
+          <span className="absolute left-3 top-1/2 -translate-y-1/2 pointer-events-none flex items-center">
+            {leading}
+          </span>
+        )}
         <span
           className={cn(
-            "absolute pointer-events-none left-3 top-[14px] text-sm leading-4 origin-top-left",
+            "absolute pointer-events-none top-[14px] text-sm leading-4 origin-top-left",
+            leading ? "left-10" : "left-3",
             "transition-transform transition-colors duration-300 ease-out",
             showPulse ? "text-sky-600" : "text-muted-foreground",
             isActive ? "-translate-y-2 scale-[0.77]" : "translate-y-0 scale-100"

package/src/primitives/select-field.tsx

@@ -27,10 +27,19 @@ export type SelectFieldProps = React.SelectHTMLAttributes<HTMLSelectElement> & {
   label: string
   children: React.ReactNode
   className?: string
+  /**
+   * A mark shown inside the control, before the value: a flag, a currency
+   * symbol. Decorative and click-through, so the whole field still opens the
+   * select. The value and the floating label make room for it.
+   */
+  leading?: React.ReactNode
 }
 
 export const SelectField = React.forwardRef<HTMLSelectElement, SelectFieldProps>(
-  function SelectField({ label, required, disabled, children, className, value, ...props }, ref) {
+  function SelectField(
+    { label, required, disabled, children, className, value, leading, ...props },
+    ref
+  ) {
     const hasValue = value !== undefined && value !== null && value !== ""
 
     return (
@@ -41,7 +50,8 @@ export const SelectField = React.forwardRef<HTMLSelectElement, SelectFieldProps>
           disabled={disabled}
           value={value}
           className={cn(
-            "w-full h-[44px] px-3 pt-[14px] pb-[2px] pr-9 text-sm rounded-lg border transition-colors duration-150 appearance-none outline-none",
+            "w-full h-[44px] pt-[14px] pb-[2px] pr-9 text-sm rounded-lg border transition-colors duration-150 appearance-none outline-none",
+            leading ? "pl-10" : "px-3",
             "focus:border-primary focus:bg-primary/5",
             disabled
               ? "bg-muted border-border text-muted-foreground cursor-not-allowed"
@@ -51,9 +61,15 @@ export const SelectField = React.forwardRef<HTMLSelectElement, SelectFieldProps>
         >
           {children}
         </select>
+        {leading && (
+          <span className="absolute left-3 top-1/2 -translate-y-1/2 pointer-events-none flex items-center">
+            {leading}
+          </span>
+        )}
         <span
           className={cn(
-            "absolute pointer-events-none left-3 top-[14px] text-sm leading-4 origin-top-left",
+            "absolute pointer-events-none top-[14px] text-sm leading-4 origin-top-left",
+            leading ? "left-10" : "left-3",
             "transition-transform transition-colors duration-150 ease-out",
             hasValue ? "text-muted-foreground" : "text-muted-foreground",
             hasValue ? "-translate-y-2 scale-[0.77]" : "translate-y-0 scale-100"

package/src/products/context.tsx

@@ -11,6 +11,13 @@ import { defaultProductLabels, type ProductLabels } from "./labels"
 
 const ProductLabelsContext = createContext<ProductLabels>(defaultProductLabels)
 
+/**
+ * A nested provider INHERITS the one above it rather than resetting to the
+ * English defaults (fixed 2026-09-13, the same defect that made evoo's
+ * checkout English: see `checkout/context.tsx`). With no provider above,
+ * the context default IS the English baseline, so a single provider behaves
+ * exactly as before.
+ */
 export function ProductLabelsProvider({
   labels,
   children,
@@ -18,9 +25,8 @@ export function ProductLabelsProvider({
   labels?: Partial<ProductLabels>
   children: ReactNode
 }) {
-  const merged = labels
-    ? { ...defaultProductLabels, ...labels }
-    : defaultProductLabels
+  const inherited = useContext(ProductLabelsContext)
+  const merged = labels ? { ...inherited, ...labels } : inherited
 
   return (
     <ProductLabelsContext.Provider value={merged}>