@escape-game-over/atlas 0.1.4 → 0.1.5

package/docs/NOT-BUILT.md

@@ -180,20 +180,28 @@ exactly the set displayed — never a number typed in beside a shorter list.
 
 ### Should `CurrencyCode` and `CountryCode` spell out the ISO lists?
 
-**Not now.**
+**`CountryCode` now does. `CurrencyCode` still does not, for the reason that
+used to cover both.**
 
-Both are shapes rather than vocabularies — `` `${Letter}${Letter}${Letter}` ``
-and `` `${Letter}${Letter}` `` — so `"XYZ"` and `"ZZ"` type-check. ISO 4217 has
+Both were shapes rather than vocabularies — `` `${Letter}${Letter}${Letter}` ``
+and `` `${Letter}${Letter}` `` — so `"XYZ"` and `"ZZ"` type-checked. ISO 4217 has
 around 180 active codes and ISO 3166-1 alpha-2 has 249; both are small, closed
 and effectively frozen, so enumerating them is possible in a way the [IANA
 language registry](https://www.iana.org/assignments/language-subtag-registry) is
 not — which is the case `LanguageTag` in `config.ts` declines and says why.
 
-Left as shapes because the mistake is not one anyone has made: a currency is
-written once per project, beside the prices it applies to, and a wrong one is
-visible the first time a page renders. That is a different risk from a typo in a
-directive nobody reads. Worth revisiting if a project ever computes a code
-rather than writing it.
+What moved is not the risk, it is the reason to hold the list at all. A country
+menu needs the codes *as data* — `countriesFor` renders and sorts them per
+locale — and once the list exists, deriving the type from it is free and the
+shape is strictly worse: it admitted 676 strings for 250 countries, including
+the withdrawn codes (`SU`, `YU`, `AN`) that look plausible enough to be typed by
+accident. So `CountryCode` is now `(typeof COUNTRY_CODES)[number]`, defined in
+`countries.ts` and re-exported from `contact.ts` beside `PostalAddress`.
+
+`CurrencyCode` stays a shape, because nothing needs a currency *list*: a
+currency is written once per project, beside the prices it applies to, and a
+wrong one is visible the first time a page renders. Enumerate it the day
+something renders a currency picker, and not before.
 
 ### Should `@type` be checked against schema.org's vocabulary?
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.4",
+    "version": "0.1.5",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/contact.ts

@@ -1,4 +1,5 @@
-import type { Digit, Letter } from "./types.ts";
+import type { CountryCode } from "./countries.ts";
+import type { Digit } from "./types.ts";
 import { warn } from "./warn.ts";
 
 /**
@@ -129,13 +130,13 @@ export function mailtoHref(email: EmailAddress): string {
 }
 
 /**
- * An ISO 3166-1 alpha-2 country code: `"IT"`, `"GR"`, `"RO"`.
+ * Re-exported so an address and its country code stay one import.
  *
- * Two uppercase letters, which is what `addressCountry` is read as. A name —
- * `"Italy"`, `"Ιταλία"` — is a translation of a country rather than an
- * identifier for one, and belongs in the sentence a page prints, not here.
+ * Defined beside the list it is read from — see `countries.ts`. Imported at the
+ * top as well: `export … from` forwards a name without binding it here, and
+ * `PostalAddress` below needs it in scope.
  */
-export type CountryCode = `${Letter}${Letter}`;
+export type { CountryCode };
 
 /**
  * Where a place is, to the precision a map needs.

package/src/countries.ts

@@ -0,0 +1,314 @@
+/**
+ * Every country a form can offer, as ISO 3166-1 alpha-2.
+ *
+ * Codes rather than names, which is the point on a multilingual site:
+ * `countriesFor` turns each one into the reader's own word for it and sorts
+ * them the way that language sorts. A list of English names would put "Czech
+ * Republic" in front of a Romanian reader and file it under C.
+ *
+ * The code is also what a form should submit, so an enquiry from Germany files
+ * the same whether it was picked as "Deutschland" or "Germany".
+ *
+ * Derived from ICU's region list rather than typed out: every two-letter code
+ * it answers to, less the withdrawn and transitional reservations it still
+ * knows (`SU`, `YU`, `DD`, `ZR`, `AN`, `UK`…) and the aggregates that are not
+ * countries (`EU`, `UN`, `QO`…). 250 entries: the 249 ISO assigns, plus `XK`
+ * for Kosovo, which is user-assigned and in common use.
+ *
+ * **This is a list, not a policy.** It says which codes are well-formed, not
+ * which countries a business will trade with — that is a per-project answer and
+ * belongs in the project, by filtering this.
+ */
+export const COUNTRY_CODES = [
+    "AD",
+    "AE",
+    "AF",
+    "AG",
+    "AI",
+    "AL",
+    "AM",
+    "AO",
+    "AQ",
+    "AR",
+    "AS",
+    "AT",
+    "AU",
+    "AW",
+    "AX",
+    "AZ",
+    "BA",
+    "BB",
+    "BD",
+    "BE",
+    "BF",
+    "BG",
+    "BH",
+    "BI",
+    "BJ",
+    "BL",
+    "BM",
+    "BN",
+    "BO",
+    "BQ",
+    "BR",
+    "BS",
+    "BT",
+    "BV",
+    "BW",
+    "BY",
+    "BZ",
+    "CA",
+    "CC",
+    "CD",
+    "CF",
+    "CG",
+    "CH",
+    "CI",
+    "CK",
+    "CL",
+    "CM",
+    "CN",
+    "CO",
+    "CR",
+    "CU",
+    "CV",
+    "CW",
+    "CX",
+    "CY",
+    "CZ",
+    "DE",
+    "DJ",
+    "DK",
+    "DM",
+    "DO",
+    "DZ",
+    "EC",
+    "EE",
+    "EG",
+    "EH",
+    "ER",
+    "ES",
+    "ET",
+    "FI",
+    "FJ",
+    "FK",
+    "FM",
+    "FO",
+    "FR",
+    "GA",
+    "GB",
+    "GD",
+    "GE",
+    "GF",
+    "GG",
+    "GH",
+    "GI",
+    "GL",
+    "GM",
+    "GN",
+    "GP",
+    "GQ",
+    "GR",
+    "GS",
+    "GT",
+    "GU",
+    "GW",
+    "GY",
+    "HK",
+    "HM",
+    "HN",
+    "HR",
+    "HT",
+    "HU",
+    "ID",
+    "IE",
+    "IL",
+    "IM",
+    "IN",
+    "IO",
+    "IQ",
+    "IR",
+    "IS",
+    "IT",
+    "JE",
+    "JM",
+    "JO",
+    "JP",
+    "KE",
+    "KG",
+    "KH",
+    "KI",
+    "KM",
+    "KN",
+    "KP",
+    "KR",
+    "KW",
+    "KY",
+    "KZ",
+    "LA",
+    "LB",
+    "LC",
+    "LI",
+    "LK",
+    "LR",
+    "LS",
+    "LT",
+    "LU",
+    "LV",
+    "LY",
+    "MA",
+    "MC",
+    "MD",
+    "ME",
+    "MF",
+    "MG",
+    "MH",
+    "MK",
+    "ML",
+    "MM",
+    "MN",
+    "MO",
+    "MP",
+    "MQ",
+    "MR",
+    "MS",
+    "MT",
+    "MU",
+    "MV",
+    "MW",
+    "MX",
+    "MY",
+    "MZ",
+    "NA",
+    "NC",
+    "NE",
+    "NF",
+    "NG",
+    "NI",
+    "NL",
+    "NO",
+    "NP",
+    "NR",
+    "NU",
+    "NZ",
+    "OM",
+    "PA",
+    "PE",
+    "PF",
+    "PG",
+    "PH",
+    "PK",
+    "PL",
+    "PM",
+    "PN",
+    "PR",
+    "PS",
+    "PT",
+    "PW",
+    "PY",
+    "QA",
+    "RE",
+    "RO",
+    "RS",
+    "RU",
+    "RW",
+    "SA",
+    "SB",
+    "SC",
+    "SD",
+    "SE",
+    "SG",
+    "SH",
+    "SI",
+    "SJ",
+    "SK",
+    "SL",
+    "SM",
+    "SN",
+    "SO",
+    "SR",
+    "SS",
+    "ST",
+    "SV",
+    "SX",
+    "SY",
+    "SZ",
+    "TC",
+    "TD",
+    "TF",
+    "TG",
+    "TH",
+    "TJ",
+    "TK",
+    "TL",
+    "TM",
+    "TN",
+    "TO",
+    "TR",
+    "TT",
+    "TV",
+    "TW",
+    "TZ",
+    "UA",
+    "UG",
+    "UM",
+    "US",
+    "UY",
+    "UZ",
+    "VA",
+    "VC",
+    "VE",
+    "VG",
+    "VI",
+    "VN",
+    "VU",
+    "WF",
+    "WS",
+    "XK",
+    "YE",
+    "YT",
+    "ZA",
+    "ZM",
+    "ZW",
+] as const;
+
+/**
+ * An ISO 3166-1 alpha-2 country code: `"IT"`, `"GR"`, `"RO"`.
+ *
+ * Read off the list above rather than described as a shape. `${Letter}${Letter}`
+ * admits all 676 two-letter strings, of which some 400 are not countries, so it
+ * accepted `"XX"` and every typo that happened to be two capitals. This accepts
+ * the 250 that exist and nothing else — including refusing the withdrawn codes
+ * (`SU`, `YU`, `AN`), which look plausible and are the ones worth catching.
+ *
+ * A name — `"Italy"`, `"Ιταλία"` — is a translation of a country rather than an
+ * identifier for one, and belongs in the sentence a page prints. `countriesFor`
+ * is what turns one of these into that.
+ */
+export type CountryCode = (typeof COUNTRY_CODES)[number];
+
+/** One country, in one language. */
+export interface NamedCountry {
+    readonly code: CountryCode;
+    readonly name: string;
+}
+
+/**
+ * The list as one locale reads it: each code with its own name, A to Z in that
+ * language.
+ *
+ * Both halves are locale-dependent, so neither can be cached across locales —
+ * "Ägypten" sorts second in German and "Egypt" fifth in English, and a build
+ * that sorted once would ship one language's order to all of them.
+ *
+ * `Intl.DisplayNames` falls back to the code itself for anything it does not
+ * know, which is what keeps this total: an option always has a label.
+ */
+export function countriesFor(locale: string): readonly NamedCountry[] {
+    const names = new Intl.DisplayNames([locale], { type: "region" });
+    const collator = new Intl.Collator(locale);
+    return COUNTRY_CODES.map((code) => ({
+        code,
+        name: names.of(code) ?? code,
+    })).sort((a, b) => collator.compare(a.name, b.name));
+}

package/src/index.ts

@@ -60,6 +60,11 @@ export {
     type MailEndpoint,
     sendContactMessage,
 } from "./contact-form.ts";
+export {
+    COUNTRY_CODES,
+    countriesFor,
+    type NamedCountry,
+} from "./countries.ts";
 export type { GeneratedFile } from "./file.ts";
 export type { PublicFilePath, PublicFileRegistry } from "./files.ts";
 export {