@cartbase/storefront 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.11.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",

package/src/checkout/address-form.tsx

@@ -5,6 +5,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 { countryName } from "../lib/country-name"
 import { Field } from "../primitives/field"
 import { SelectField } from "../primitives/select-field"
 import { AddressSelect } from "./address-select"
@@ -105,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

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,7 @@ import {
 } from "react"
 
 import type { StorefrontClient } from "../api/http"
+import { countryName } from "../lib/country-name"
 import { listCountries, type StoreCountry } from "../api/regions"
 import {
   completeCart,
@@ -408,7 +409,10 @@ export function useCheckoutOrchestration({
         : storeCountries && storeCountries.length
           ? storeCountries
           : countryCode
-            ? [{ iso_2: countryCode, display_name: "" }]
+            ? // 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]
   )

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/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}>