create-cartbase 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cartbase",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
   "license": "MIT",
   "type": "module",

package/template/app/docs/components.md

@@ -353,8 +353,13 @@ code-first through the error-copy maps, never raw API strings.
 - **Props contract** — `{client, cart, customer, availableShippingMethods,
   availablePaymentMethods, countryCode?, countries?, paymentMethodFilter?,
   orderConfirmedPath?, onOrderPlaced?,
-  resolveTrackingMetadata?, logError?}`. `countries` is caller-supplied
-  (Cartbase regions embed NO countries array). Fee prediction is never
+  resolveTrackingMetadata?, logError?}`. `countries` is OPTIONAL and is an
+  override: omit it and the hook calls `GET /api/store/countries` itself, so
+  the address form offers the countries the store's Markets declare, or the
+  whole catalogue when it declares none (0.11.0 — before that, omitting it
+  produced a ONE-country read-only field). A failure to load the list never
+  blocks a checkout: it falls back to `countryCode` and reports through
+  `logError` as `country_list_failed`. Fee prediction is never
   hardcoded: each method LISTING entry carries its own
   `fee_amount`/`fee_label`. `logError` replaces the legacy log writers
   (all production log points preserved). Returns the full orchestration
@@ -412,9 +417,16 @@ code-first through the error-copy maps, never raw API strings.
   `addressesInRegion`.
 - **Props contract** — everything from the hook (`formData`,
   `handleFormChange`, `handleFieldBlur`, `regionCountries`, `addressInput`,
-  `addressError`, `pulseFields`); `hideCountry?` for single-country stores
-  (single-entry lists render a readonly localized country field).
-- **Settings** — regions/countries (via the caller-supplied list).
+  `addressError`, `pulseFields`); `hideCountry?` for single-country stores.
+  The country field is a NATIVE select carrying the chosen country's flag,
+  and it keeps `autocomplete="country"` on purpose: a custom listbox would
+  draw a flag per row but lose browser autofill and the phone's own picker,
+  and a checkout does not trade autofill for decoration. A list of exactly
+  one country still renders as a read-only name, which is right for a store
+  that truly sells to one country and is no longer the default for everyone
+  else (0.11.0).
+- **Settings** — Admin → Settings → Markets → Regions, read through
+  `GET /api/store/countries`.
 
 ### `<CheckoutShippingMethodList />` — `checkout/shipping-method-list`
 
@@ -1092,12 +1104,27 @@ Shared storefront chrome, production-proven.
 
 ### `<CountrySelect regions value? onChange />` — `common/country-select`
 
-- **Purpose** — region picker. SDK-forced divergence from the source:
-  Cartbase regions carry NO `countries[]` embed on the store surface, so
-  the select lists REGIONS (`api/regions.listRegions`), valued by region
-  id; persistence is app-owned via `onChange` (usually
-  `carts.updateCart(client, cartId, {region_id})` + a cookie).
-- **Settings** — Regions (Settings → Regions): which rows exist.
+- **Purpose** — the market picker for a header or footer. It lists REGIONS
+  (`api/regions.listRegions`), valued by region id; persistence is app-owned
+  via `onChange` (usually `carts.updateCart(client, cartId, {region_id})` +
+  a cookie). The name is a leftover from the ported source and is wrong for
+  what it does: it selects a market, not a country. Use
+  `listCountries` + `CountryFlag` when you want a country.
+- **Settings** — Admin → Settings → Markets → Regions: which rows exist.
+
+### `<CountryFlag code title? className? />` — `common/country-flag`
+
+- **Purpose** — a country's flag from its ISO-3166 alpha-2 code, at the size
+  of the text beside it. An unknown or empty code renders a neutral box that
+  holds the same space, so a field does not jump when a shopper picks their
+  country.
+- **Why a sprite and not an emoji** — Windows ships no flag glyphs, so an
+  emoji flag reads as the two letters "BG" there. This draws `flag-icons`
+  SVG under a CSS class, which renders the same on every platform, and it is
+  the same sprite the Cartbase admin uses, so one country treatment runs
+  across the admin and the storefront.
+- **Accessibility** — decorative and `aria-hidden`: a flag never carries
+  meaning the name beside it does not. Pass `title` when it stands alone.
 
 ### `<LanguageSelect locales currentLocale onChange labels? />` — `common/language-select`
 

package/template/app/docs/regions.md

@@ -108,6 +108,69 @@ curl -s "$BASE/api/store/regions/reg_doesnotexist$RUN" \
 
 ---
 
+## GET /api/store/countries
+
+- **Purpose** — the countries a shopper may choose at checkout.
+
+**The rule is the platform's, not your 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 endpoint answers with:
+
+- the countries the store's regions declare, when it has declared any
+  (`"restricted": true`), or
+- the whole 250-entry ISO catalogue, when it has declared none
+  (`"restricted": false`).
+
+Either way your code hardcodes no country list and invents no fallback of
+its own. A merchant changes the answer in Admin → Settings → Markets →
+Regions, where a region owns its countries.
+
+```jsonc
+// query (all optional)
+{
+  "q": "bulg",   // case-insensitive substring on the displayed name
+  "limit": 300,  // 1–300, default 300 — the whole catalogue in one call
+  "offset": 0
+}
+```
+
+- **Response** — ordered by `display_name`, the name a shopper reads.
+
+```jsonc
+{
+  "countries": [
+    {
+      "iso_2": "bg",              // lowercase alpha-2: the cart address value
+      "display_name": "Bulgaria", // what a shopper reads
+      "name": "BULGARIA",         // the catalogue's uppercase form
+      "region_id": "reg_01..."    // null when the store has not placed it
+    }
+  ],
+  "count": 250,
+  "offset": 0,
+  "limit": 300,
+  "restricted": false
+}
+```
+
+```bash
+# every country the store offers, and which of the two lists you received
+curl -s "$BASE/api/store/countries" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"restricted"'
+```
+
+- **SDK** — `listCountries(client, query?)` from
+  `@cartbase/storefront/api/regions`.
+- **Components** — the checkout address form's country select.
+  `useCheckoutOrchestration` CALLS THIS FOR YOU when you do not pass a
+  `countries` list, so a new store offers every country with no wiring;
+  pass your own list only to override the store's answer. The chosen
+  country's flag is drawn by `CountryFlag`
+  (`@cartbase/storefront/common/country-flag`).
+- **Settings** — Admin → Settings → Markets → Regions.
+
+---
+
 ## GET /api/store/currencies
 
 - **Purpose** — list the currencies ENABLED on this store (the shared

package/template/app/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@cartbase/storefront": "^0.10.0",
+    "@cartbase/storefront": "^0.12.0",
     "next": "16.2.4",
     "react": "19.2.4",
     "react-dom": "19.2.4"

package/template/app/src/app/checkout/checkout-page-client.tsx

@@ -32,8 +32,19 @@ export function CheckoutPageClient({
         customer={null}
         availableShippingMethods={shippingOptions}
         availablePaymentMethods={paymentProviders}
-        countryCode="bg"
-        countries={[{ iso_2: "bg", display_name: "Bulgaria" }]}
+        // NO COUNTRY LIST HERE, on purpose (2026-09-13). This file is the
+        // seed for every scaffolded store, and it used to pass
+        // `countries={[{iso_2:"bg", display_name:"Bulgaria"}]}` with
+        // `countryCode="bg"`, so every store on earth shipped a checkout
+        // offering one country, Bulgaria, in a box the shopper could not
+        // change. The list belongs to the store, not to this file: omit the
+        // prop and the hook reads GET /api/store/countries, which answers
+        // with the countries the store's Markets declare, or with the whole
+        // world when it has declared none.
+        //
+        // A single-market store adds `countryCode="xx"` here to preselect
+        // its country, and a store that sells to exactly one country gets
+        // the read-only field automatically, because its Markets say so.
         // Per-store rule (the documented paymentMethodFilter seam): this
         // reference store checks out offline via its merchant methods only
         // (pp_* kill: method entries carry payment_method_id, processors