create-cartbase 0.1.8 → 0.1.10

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.9.0",
+    "@cartbase/storefront": "^0.11.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