@cartbase/storefront 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cartbase/storefront",
-  "version": "0.10.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": {
@@ -190,6 +190,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 +201,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,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) => (

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

@@ -10,6 +10,7 @@ import {
 } from "react"
 
 import type { StorefrontClient } from "../api/http"
+import { listCountries, type StoreCountry } from "../api/regions"
 import {
   completeCart,
   updateCart,
@@ -362,17 +363,54 @@ 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
+            ? [{ iso_2: countryCode, display_name: "" }]
+            : [],
+    [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/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"