@johnmorrisdotca/kuni 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -6,6 +6,41 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-10-14
+
+A country and subdivision card with a shared embed builder joins the demo and the package, tables download as Markdown and SQL, and the package has an English and Japanese documentation site with a checked example for every export. The country data, the codes and the lookups are unchanged.
+
+### Added
+
+- Add the bilingual documentation site, checked public examples, full country-resource catalogue, local search and machine-readable pages.
+- Add a country and subdivision card, embed builder and validated storage-free iframe.
+- Add per-place colours and a capital-marker switch to country cards and their builder/frame links. Hosts can receive drawing options in map loaders; capital text fields stay separate.
+- Share a package-independent embed builder for option controls, preview adapters, code tabs and shareable links.
+
+### Changed
+
+- The tests allow thirty seconds each (`vitest.config.js`), because the shared test that measures each entry point's size builds the country data and took longer than five seconds on a slow runner.
+- The API link in the header reads "API" in English, so that the header takes the same number of rows in English and in Japanese on a phone, as the demo's test of a language change asks.
+- Synchronize documentation tooling for repository layouts, generated type references, Node entry points and repository-specific README links.
+- Keep complete resource catalogues on the documentation entry index and the active resource beside core navigation; render valid default imports in HTML and Markdown.
+- Reconcile cards with the released IOC/withdrawn APIs; append optional ioc display while keeping current-country pickers and default fields unchanged.
+- Compose optional Hata flags and Chizu maps, retain dated facts and land-area scope, and expose reflected properties and native load/error events.
+- Group the package family by kind, alphabetize each group, and include the geography packages and REST in Pieces in the shared footer and README.
+- Update the shared family description for addresses in all seven supported countries, including France and Germany.
+
+## [1.3.0] - 2026-10-09
+
+### Added
+
+- **`country(code).ioc`**, the International Olympic Committee's three-letter country code (`"JPN"`, `"GER"` for Germany, `"SUI"` for Switzerland, `"TPE"` for Taiwan, `"KOS"` for Kosovo), for the 209 countries Wikidata (P984, CC0) gives one. A country with none has no `ioc` field. It is one more column in the main entry's table: the entry grew by 1.7 KB (0.8 KB gzipped).
+- **`@johnmorrisdotca/kuni/withdrawn`**, a new entry: the 31 countries ISO 3166-3 lists as withdrawn from ISO 3166-1, with `withdrawnCountries()` and `withdrawn(code)`. A record has the four-letter code (`SUHH`), the alpha-2 (`SU`), alpha-3 (`SUN`) and numeric (`810`) codes it held, its name in English and Japanese, `since` and `until` (the years the code was in force), the `successors` (the new codes ISO 3166-3 lists, in ISO's order; every record has at least one, and one may itself be withdrawn: Yugoslavia's is `CS`, which `withdrawn("CS")` resolves to Serbia and Montenegro first and Czechoslovakia after) and `reusedBy` where a current country holds the alpha-2 code now (BY, AI, BQ, GE, SK). The lookup takes any of the four codes in either case and answers every country that held it, the last one first (`withdrawn("CS")` is Serbia and Montenegro, then Czechoslovakia), and an empty list for anything else. The Soviet Union, Yugoslavia, Czechoslovakia, East Germany, Zaire, East Timor, the Netherlands Antilles and Burma are among them. The main entry is unchanged: `countries()` and `country()` never return one, so no country picker shows the USSR. It is 8 KB (2.4 KB gzipped).
+- **ISO 3166-3 is the authority for the withdrawn countries' codes, years and successors**: `WITHDRAWN_TABLE` in `scripts/withdrawn-config.ts` is the published list transcribed once (alpha-3, numeric, the years the code was in force, ISO's new codes), and `src/withdrawn.test.ts` pins the whole table, so a rebuild cannot drift from it. **Wikidata is used for their names** (English and Japanese) and for the IOC codes: a new snapshot, `data-sources/wikidata-codes-2026-10-10.json`, read by `pnpm data:codes` (CC0), turned into records by `scripts/withdrawn.ts`, which stops if the snapshot and ISO's table do not name the same 31 codes. `docs/withdrawn.md` lists every record and the Japanese names for review. The names, facts and groupings snapshots are unchanged.
+- NOTICE.md, data-sources/README.md and the README's data table say where the new data comes from and its terms.
+
+### Changed
+
+- `Country` has a new optional field, `ioc`. The table the main entry reads has one more column before the user-assigned marker; nothing that reads `country()` changes.
+
 ## [1.2.0] - 2026-10-09
 
 ### Added

package/NOTICE.md

@@ -15,6 +15,9 @@ address, the day it was read and its SHA-256.
 | Which land borders are real (two outlines touch) | Natural Earth 5.1.2 admin-0 countries at 1:50m, as drawn by `@johnmorrisdotca/chizu` 1.0.2 (a development dependency of the build; the package does not depend on it) | Public domain (Natural Earth); MIT (Chizu), below |
 | The first day of the week, the measurement system, the paper size and the clock; the UN M49 areas and their members; the members of the United Nations | Unicode CLDR 48.2 (`cldr-core` 48.2.0: weekData, measurementData, timeData, territoryContainment) | Unicode-3.0, below |
 | The members of each international body as the body lists them, the informal groupings with their definitions, the regions inside a country, the readings of the groupings' Japanese names, and the choices in `scripts/facts-config.ts` and `scripts/groupings-config.ts` | Written for this package, from the sources named beside each, read on 2026-10-09 | MIT; lists of facts |
+| The International Olympic Committee's country codes; the names in English and Japanese of the countries ISO 3166-3 lists as withdrawn | Wikidata, the snapshot `data-sources/wikidata-codes-2026-10-10.json` | CC0, below |
+| The withdrawn countries' four-letter codes, alpha-3 and numeric codes, the years each code was in force and the codes that replaced them | ISO 3166-3's published list (ISO's Online Browsing Platform), transcribed once in `scripts/withdrawn-config.ts` and pinned whole by `src/withdrawn.test.ts` | A list of facts |
+| The IOC code of the Netherlands, and a few of the withdrawn countries' names | Written for this package, in `scripts/withdrawn-config.ts`, each with its reason | MIT |
 | Time zones | IANA time zone database 2026e, `zone.tab` | Public domain |
 | Country-code top-level domains | IANA's list of top-level domains (version 2026100900) | A list of facts, published by IANA |
 | The aliases ("Holland", "UK", 米国), the readings of country names written in kanji, Hokkaido's and Fukuoka's readings, and the Japanese words for kinds of place the build looks for | Written for this package, in `scripts/data-config.ts` | MIT |

package/README.md

@@ -1,4 +1,4 @@
-<h1 align="center">Kuni <sub>国</sub></h1>
+<h1 align="center">Kuni <sub>国</sub> — Countries, states and provinces</h1>
 
 <p align="center"><strong>Kuni 国: every country and its states, provinces and prefectures, with ISO 3166 codes and names in English and Japanese.</strong><br>
 A typed, zero-dependency dataset from Unicode CLDR and Wikidata, loaded one country at a time, for JavaScript and TypeScript. Look up a country or a region by code or by what somebody typed, in either language, and load only the countries you need.</p>
@@ -11,30 +11,32 @@ A typed, zero-dependency dataset from Unicode CLDR and Wikidata, loaded one coun
   <a href="./LICENSE"><img alt="MIT licence" src="https://img.shields.io/badge/licence-MIT-2f5d4a"></a>
   <img alt="No dependencies" src="https://img.shields.io/badge/dependencies-0-2f5d4a">
   <img alt="TypeScript" src="https://img.shields.io/badge/types-TypeScript-3178c6">
+  <a href="https://johnmorrisdotca.github.io/kuni/docs/api/main/index.html"><img alt="21.4 kB minified and gzipped" src="https://img.shields.io/badge/min%2Bgzip-21.4%20kB-2f5d4a"></a>
+  <a href="https://www.npmjs.com/package/@johnmorrisdotca/kuni#provenance"><img alt="Published with npm provenance" src="https://img.shields.io/badge/npm-provenance-2f5d4a"></a>
 </p>
 
-<p align="center"><a href="https://johnmorrisdotca.github.io/kuni/"><strong>Try it →</strong></a> · <a href="https://johnmorrisdotca.github.io/kuni/api.html">API reference</a></p>
+<p align="center"><a href="https://johnmorrisdotca.github.io/kuni/"><strong>Try it →</strong></a> · <a href="https://johnmorrisdotca.github.io/kuni/docs/">Documentation</a> · <a href="https://johnmorrisdotca.github.io/kuni/docs/guides/getting-started.html">Getting started</a> · <a href="https://johnmorrisdotca.github.io/kuni/api.html">API reference</a></p>
 
 <table align="center">
 <tr>
 <td align="center" valign="top">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-desk-dark.webp">
-<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-desk-light.webp" alt="The demo on a desk, in English: the header with its language chooser, the API reference link, five cloth patches and the Help switch, then a row of views (Look up, Country, Compare, All countries, Groupings, Quiz, Form widget, Data quality) and the Look up view's panels. Find a country shows ドイツ typed in and its answer: the German flag, DE, DEU and 276, Germany, ドイツ, Deutschland, Europe, Berlin, +49, EUR, .de, two time zones, and 16 states. Subdivisions of a country shows Japan picked and a table of its prefectures with code, English and Japanese name, from JP-01 Hokkaidō 北海道, and the line 47 subdivisions; the main kind is prefecture. Look up a code begins below with JP-13 typed in." width="600">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-desk-light.webp" alt="The demo on a desk, in English: the header with its language chooser, the Docs and API reference links, five cloth patches and the Help switch, then a row of views (Look up, Country, Compare, All countries, Groupings, Quiz, Form widget, Data quality) and the Look up view's panels. Find a country shows ドイツ typed in and its answer: the German flag, DE, DEU and 276, Germany, ドイツ, Deutschland, Europe, Berlin, +49, EUR, .de, two time zones, and 16 states. Subdivisions of a country shows Japan picked and a table of its prefectures with code, English and Japanese name, from JP-01 Hokkaidō 北海道, and the line 47 subdivisions; the main kind is prefecture. Look up a code begins below with JP-13 typed in." width="600">
 </picture>
 <br><em>The demo on a desk: a country found by its Japanese name, and Japan's prefectures loaded on demand.</em>
 </td>
 <td align="center" valign="top">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-phone-dark.webp">
-<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-phone-light.webp" alt="The demo on a phone, in Japanese: the header, its language chooser, patches and buttons, then the first panel, 国を探す, with ドイツ typed in, its row of examples, and the start of its answer, the German flag and DE, DEU, 276, under the row of views" width="190">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/hero-phone-light.webp" alt="The demo on a phone, in Japanese: the header, its language chooser, patches and buttons, then the first panel, 国を探す, with ドイツ typed in below the view choices and the Docs/API navigation" width="190">
 </picture>
 <br><em>On a phone, in Japanese, in the device's light or dark.</em>
 </td>
 </tr>
 </table>
 
-Kuni is the country list every site ends up keeping for itself, kept once, with what a form, a profile page or a map quiz asks of it: the 250 countries with their ISO 3166-1 codes, and their 5,050 ISO 3166-2 subdivisions (Japan's prefectures, the American states, Canada's provinces and territories, France's regions and departments), each named in English and in Japanese. Beside the names, in entries of their own so a page that only names countries does not carry them: each country's capital, population and area with the year each is for, coordinates, land borders, driving side and calendar conventions; each subdivision's capital, population and area; and 107 groupings, from the continents and the EU to Japan's eight regions. The names are Unicode CLDR's, with Wikidata filling the gaps, so they are the same on a server and in a browser, which `Intl.DisplayNames` is not. It looks a country up by what somebody typed (Holland, ＵＳＡ, にほん, 米国) and a region by its code or its name. It works in [the demo](https://johnmorrisdotca.github.io/kuni/) with nothing to install.
+Kuni is the country list every site ends up keeping for itself, kept once, with what a form, a profile page or a map quiz asks of it: the 250 countries with their ISO 3166-1 codes, and their 5,050 ISO 3166-2 subdivisions (Japan's prefectures, the American states, Canada's provinces and territories, France's regions and departments), each named in English and in Japanese. Beside the names, in entries of their own so a page that only names countries does not carry them: each country's capital, population and area with the year each is for, coordinates, land borders, driving side and calendar conventions; each subdivision's capital, population and area; and 107 groupings, from the continents and the EU to Japan's eight regions; and, in a list of its own so no country picker shows them, the 31 countries that were withdrawn from ISO 3166-1 (the Soviet Union, Yugoslavia, Czechoslovakia, East Germany, Zaire) with the codes they held and what came after. The names are Unicode CLDR's, with Wikidata filling the gaps, so they are the same on a server and in a browser, which `Intl.DisplayNames` is not. It looks a country up by what somebody typed (Holland, ＵＳＡ, にほん, 米国) and a region by its code or its name. It works in [the demo](https://johnmorrisdotca.github.io/kuni/) with nothing to install.
 
 ## In 30 seconds
 
@@ -79,10 +81,13 @@ Install the scoped name: the unscoped `kuni` on npm is somebody else's package.
 - **Sites rendered on a server and hydrated in a browser**, where `Intl.DisplayNames` spells some countries differently in Node and in Chromium and the page does not match itself.
 - **Japanese-language pages** that need アメリカ合衆国 and オンタリオ州, the four kinds of Japanese prefecture (都道府県), and prefecture readings in kana.
 - **Maps, quizzes and data pipelines** that join their own figures to a country or a region by its ISO code, or want the capital, the population, the neighbours and the groupings a quiz asks about.
+- **Old records**: a table that still says SU, YU, CS, DD or ZR, or an export from before 1993, which `withdrawn(code)` names and points to the countries that came after.
 - **Build scripts** in sister packages (a map that draws any grouping, a site with a page per prefecture) that read plain numbers, stable codes and as-of dates.
 
 ## Features
 
+### What's in it
+
 - **Every country.** The 249 ISO 3166-1 codes and Kosovo (XK, user-assigned), each with alpha-2, alpha-3 and numeric codes, its flag, continent, UN M49 subregion, calling code, currencies, top-level domain, capital, time zones and languages.
 - **Every subdivision.** 5,050 ISO 3166-2 codes in 200 countries: 3,594 at the first level and 1,456 below it (France's departments in its regions, England's councils in England), each with its level and parent.
 - **English and Japanese names** from Unicode CLDR 48.2, with CLDR's short forms (UK, アメリカ) and variants (Ivory Coast, 象牙海岸). Japanese names for 3,527 of the 3,594 first-level subdivisions, and `null` for the rest, never a guess.
@@ -91,14 +96,29 @@ Install the scoped name: the unscoped `kuni` on npm is somebody else's package.
 - **Capitals in both languages.** Every country's capital in English and Japanese (東京, キーウ), and every subdivision's capital Wikidata names (3,968 of 5,050), with readings in kana for Japan's prefectural capitals (さっぽろし).
 - **Facts with their dates** (`/facts`): population and area with the year each is for, coordinates of the country and its capital, land borders (confirmed by Natural Earth's outlines, so islands have none), the side of the road it drives on, and CLDR's first day of the week, measurement system, paper size and clock. `distanceKm` between two points.
 - **Facts about subdivisions** (`/subdivision-facts`): each one's capital, population, area and coordinates, one country at a time; complete for Japan's 47 prefectures.
+- **Withdrawn countries** (`/withdrawn`): the 31 entries of ISO 3166-3 (SU, YU, CS, DD, ZR, TP, AN, BU and the rest), each with the four-letter code, the alpha-2, alpha-3 and numeric codes it held, its name in English and Japanese, the years the code was in force and the codes ISO lists for what came after it. They are never in `countries()`, so a picker does not offer the Soviet Union; a lookup by an old code says what it was.
+- **Olympic codes**: `country(code).ioc` is the International Olympic Committee's three-letter code ("JPN", "GER" for Germany, "SUI" for Switzerland) for the 209 countries that have one.
 - **Groupings** (`/groupings`): the seven continents, the 30 UN M49 areas, 23 international bodies (the UN, the EU, the euro area, Schengen, NATO, the G7 and G20, ASEAN and more) with the days members joined and left, 16 informal groupings (the Middle East, the Balkans, Scandinavia, the Sahel) each with the definition it follows, and regions inside a country (Japan's 地方, the US Census regions, Canada's regions).
-- **Small where it matters.** The countries and lookups are about 57 KB (19 KB gzipped); one country's subdivisions are their own entry (Japan's 47, 2.9 KB) or a dynamic import.
+- **Small where it matters.** The countries and lookups are 21.4 kB minified and gzipped; one country's subdivisions are their own entry (Japan's 47, measured separately) or a dynamic import.
 - **Typed, frozen, pure and the same everywhere.** ESM and CommonJS, types for both, no dependencies, no network and no `Intl`. Every export carries a doc comment with a runnable example, which an editor shows on hover and the tests run.
 - **A demo to use, not just to read.** A page for each country, two countries compared, every country in a sortable table, the groupings explorer, three seeded quizzes, a country and region form widget with its code to copy, and the data's quality in the open, each at an address of its own and downloadable as CSV, JSON, text, a Markdown table or SQL: [the demo](https://johnmorrisdotca.github.io/kuni/).
 - **Never a guess.** A value no source gives is `null`, with the reason written down (`docs/facts.md`, `docs/subdivision-facts.md`, `docs/ja-gaps.md`), never a plausible filler.
 
+[Build a country or subdivision card](https://johnmorrisdotca.github.io/kuni/builder.html). The [embed guide](docs/embeds.md) covers its fields, properties and messages. Cards support per-place `colors` and `capital="off"` for the native Chizu map; capital text stays separate. [Map colours and markers](docs/embeds.md#map-colours-and-markers).
+
 ## Use it in your project
 
+### Install under another name
+
+```sh
+npm install countries@npm:@johnmorrisdotca/kuni
+```
+
+```ts no-check
+import { country } from "countries";
+console.log(country("JP")?.name.en);
+```
+
 ### Install
 
 ```sh
@@ -111,17 +131,20 @@ It ships ES modules and CommonJS, with types for both and `sideEffects: false`.
 
 ### The entry points
 
-| Entry | What it carries | Size (ESM) |
+| Entry | What it carries | Size (minified + gzip) |
 | --- | --- | --- |
-| `@johnmorrisdotca/kuni` | The 250 countries and the country lookups | 57 KB, 19 KB gzipped |
-| `@johnmorrisdotca/kuni/codes` | The 250 codes and `isCountryCode`, nothing else | 2 KB |
-| `@johnmorrisdotca/kuni/subdivisions/<code>` | One country's subdivisions, every level (`/subdivisions/jp`, `/subdivisions/us`, lower case) | 1 to 13 KB; Japan 2.9 KB |
-| `@johnmorrisdotca/kuni/load` | `loadSubdivisions(code)`, one dynamic import per country | 11 KB, then the country's own file |
-| `@johnmorrisdotca/kuni/subdivisions` | All 5,050 subdivisions and the subdivision lookups | 216 KB, 85 KB gzipped |
-| `@johnmorrisdotca/kuni/facts` | Every country's population, area, coordinates, borders, driving side and conventions | 25 KB, 9 KB gzipped |
-| `@johnmorrisdotca/kuni/subdivision-facts` | `loadSubdivisionFacts(code)`, one dynamic import per country | 12 KB, then the country's own file |
-| `@johnmorrisdotca/kuni/subdivision-facts/<code>` | One country's subdivision facts (`/subdivision-facts/jp`) | 1 to 16 KB; Japan 4.9 KB |
-| `@johnmorrisdotca/kuni/groupings` | The 107 groupings and their lookups | 84 KB, 16 KB gzipped |
+| `@johnmorrisdotca/kuni` | The 250 countries and the country lookups | 21.4 kB min+gzip |
+| `@johnmorrisdotca/kuni/element` | `KuniCard`, `defineCard`, `KUNI_CARD_FIELDS`, `KUNI_CARD_OPTION_KEYS`, `readCardColors`; `KuniCardOptions` | 290.5 kB min+gzip |
+| `@johnmorrisdotca/kuni/element/define` | registers the tag and re-exports the element API | 290.5 kB min+gzip |
+| `@johnmorrisdotca/kuni/codes` | The 250 codes and `isCountryCode`, nothing else | 0.6 kB min+gzip |
+| `@johnmorrisdotca/kuni/subdivisions/<code>` | One country's subdivisions, every level (`/subdivisions/jp`, `/subdivisions/us`, lower case) | 0.4–5.0 kB; Japan 1.5 kB |
+| `@johnmorrisdotca/kuni/load` | `loadSubdivisions(code)`, one dynamic import per country | 97.6 kB min+gzip |
+| `@johnmorrisdotca/kuni/subdivisions` | All 5,050 subdivisions and the subdivision lookups | 88.4 kB min+gzip |
+| `@johnmorrisdotca/kuni/facts` | Every country's population, area, coordinates, borders, driving side and conventions | 8.6 kB min+gzip |
+| `@johnmorrisdotca/kuni/subdivision-facts` | `loadSubdivisionFacts(code)`, one dynamic import per country | 161.1 kB min+gzip |
+| `@johnmorrisdotca/kuni/subdivision-facts/<code>` | One country's subdivision facts (`/subdivision-facts/jp`) | 0.4–7.3 kB; Japan 2.4 kB |
+| `@johnmorrisdotca/kuni/groupings` | The 107 groupings and their lookups | 15.9 kB min+gzip |
+| `@johnmorrisdotca/kuni/withdrawn` | The 31 withdrawn countries (ISO 3166-3) and `withdrawn(code)` | 2.1 kB min+gzip |
 
 ### 1. The countries
 
@@ -131,6 +154,7 @@ import { countries, country, countryByName } from "@johnmorrisdotca/kuni";
 country("jp");                      // alpha-2 in either case, "JPN" or "392" too
 countryByName("cote d'ivoire");     // Côte d'Ivoire, CI
 countries({ order: "ja" });         // in Japanese order, by reading where a name is in kanji
+country("DE")?.ioc;                 // "GER", the Olympic committee's code (absent where Wikidata gives none)
 ```
 
 ### 2. One country's subdivisions
@@ -206,6 +230,21 @@ groupings({ kind: "informal" }).map((one) => one.id);     // ["middle-east", "la
 
 Each grouping has `definition`, `source` (name, address and licence) and `asOf`; an informal one has `informal: true` and, where definitions disagree, a `note`. `docs/groupings.md` cross-checks the bodies' lists against Wikidata and says what each grouping follows.
 
+### 8. Withdrawn countries
+
+```ts
+import { withdrawn, withdrawnCountries } from "@johnmorrisdotca/kuni/withdrawn";
+
+withdrawn("SU")[0].name.en;          // "Soviet Union" (also by "SUHH", "SUN" or "810")
+withdrawn("SU")[0].until;            // "1992"
+withdrawn("YU")[0].successors;       // ["CS"]: ISO's new code, itself withdrawn (below)
+withdrawn("CS").map((one) => one.code); // ["CSXX", "CSHH"]: Serbia and Montenegro, then Czechoslovakia
+withdrawn("BY")[0].reusedBy;         // "BY": the Byelorussian SSR's code is Belarus's now
+withdrawnCountries().length;         // 31
+```
+
+The 31 are the entries of ISO 3166-3, whose codes, years and successors are the published list's, transcribed once and pinned whole by a test; their names in English and Japanese are Wikidata's (property P773). A successor is exactly the new code ISO lists, and may itself be withdrawn: Yugoslavia's is `CS`, which `withdrawn("CS")` answers as Serbia and Montenegro first and Czechoslovakia after. [docs/withdrawn.md](./docs/withdrawn.md) says how, and lists their Japanese names for review. They are a list of their own: `country("SU")` is still `null`, `isCountryCode("SU")` is still `false` and `countries()` never holds them. A lookup by a code answers every withdrawn country that held it, the last one first, and an empty list for anything else; a record whose alpha-2 code a current country holds now (`BY`, `AI`, `BQ`, `GE`, `SK`) says so in `reusedBy`.
+
 ### In a page, with no bundler
 
 ```html
@@ -215,6 +254,33 @@ Each grouping has `definition`, `source` (name, address and licence) and `asOf`;
 </script>
 ```
 
+### A card in a framework
+
+React 19:
+
+```jsx
+import "@johnmorrisdotca/kuni/element/define";
+export function Japan() { return <kuni-card code="JP" fields="name flag map capital" />; }
+```
+
+Configure Vue's template compiler with `isCustomElement: tag => tag.startsWith("kuni-")`:
+
+```vue
+<script setup>
+import "@johnmorrisdotca/kuni/element/define";
+</script>
+<template><kuni-card code="JP" /></template>
+```
+
+```svelte
+<script>
+  import "@johnmorrisdotca/kuni/element/define";
+</script>
+<kuni-card code="JP" fields="name codes capital"></kuni-card>
+```
+
+The `@johnmorrisdotca/kuni/element` entry exports the class and `defineCard(tag?)`; `@johnmorrisdotca/kuni/element/define` registers the tag. Both are safe to import on a server. The builder also supplies plain HTML, Vue, Svelte, Angular and iframe examples.
+
 ## Examples
 
 ### A country select, in either language
@@ -260,9 +326,51 @@ subdivisionsByName("Punjab").map((one) => one.code); // ["IN-PB", "PK-PB"]
 subdivisionByName("Punjab", { country: "PK" })?.code; // "PK-PB"
 ```
 
+
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/find-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/find-desk-light.webp" alt="The find panel showing a country found by its Japanese name and its native codes and fields" width="600">
+</picture>
+<br><em>The find panel shows a country found by its Japanese name and its native codes and fields.</em>
+
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/list-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/list-desk-light.webp" alt="The list panel showing Japan’s prefectures loaded as a native subdivision table" width="600">
+</picture>
+<br><em>The list panel shows Japan’s prefectures loaded as a native subdivision table.</em>
+
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/code-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/code-desk-light.webp" alt="The code panel showing a full subdivision code resolved to its native record" width="600">
+</picture>
+<br><em>The code panel shows a full subdivision code resolved to its native record.</em>
+
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/search-desk-dark.webp">
+<img src="https://raw.githubusercontent.com/johnmorrisdotca/kuni/main/docs/images/search-desk-light.webp" alt="The search panel showing all countries using the typed calling code, currency or domain" width="600">
+</picture>
+<br><em>The search panel shows all countries using the typed calling code, currency or domain.</em>
+
+### Validate an exact country code
+
+```ts
+import { isCountryCode } from "@johnmorrisdotca/kuni/codes";
+console.log(isCountryCode("JP"),isCountryCode("jp"));
+```
+
+### Read a dated country figure
+
+```ts
+import { facts,FACTS_READ } from "@johnmorrisdotca/kuni/facts";
+const japan=facts("JP");
+console.log(FACTS_READ,japan?.population,japan?.populationYear);
+```
+
 ## API
 
-The [API reference](https://johnmorrisdotca.github.io/kuni/api.html) lists every export of every entry point with its signature and its comment. It is made from the source by `pnpm site`, so it cannot fall behind the code.
+The [documentation](https://johnmorrisdotca.github.io/kuni/docs/) provides paired guides, local search and checked examples. The [complete country-resource catalogue](docs/guides/country-resources.md) names every existing per-country import, including subdivisions and their facts.
+
+The [API reference](https://johnmorrisdotca.github.io/kuni/api.html) lists every export of every entry point with its signature and its comment. `pnpm docs:site` retains the index anchors and builds individual reference pages from source, so the documentation stays with the code.
 
 | Entry | Exports |
 | --- | --- |
@@ -274,6 +382,7 @@ The [API reference](https://johnmorrisdotca.github.io/kuni/api.html) lists every
 | `@johnmorrisdotca/kuni/facts` | `facts`, `allFacts`, `distanceKm`, `FACTS_READ`, and the types `CountryFacts`, `LatLon`, `DrivingSide`, `WeekStart`, `MeasurementSystem`, `PaperSize` and `HourCycle` |
 | `@johnmorrisdotca/kuni/subdivision-facts` | `loadSubdivisionFacts`, and the types `SubdivisionFacts` and `LatLon` |
 | `@johnmorrisdotca/kuni/subdivision-facts/<code>` | the country's subdivision facts as the default export and as `SUBDIVISION_FACTS` |
+| `@johnmorrisdotca/kuni/withdrawn` | `withdrawn`, `withdrawnCountries`, `WITHDRAWN_READ` and the type `WithdrawnCountry` |
 | `@johnmorrisdotca/kuni/groupings` | `groupings`, `grouping`, `groupingsOf`, `membersOf`, `GROUPING_KINDS`, and the types `Grouping`, `GroupingKind`, `GroupingMember`, `GroupingName`, `GroupingOther`, `GroupingSource`, `GroupingStatus`, `GroupingsOptions` and `GroupingDateOptions` |
 
 A country:
@@ -381,6 +490,8 @@ None, on purpose: Kuni is data and lookups, with no colours, markup or styles, s
 | Area | 250 of 250 countries; 4,371 of 5,050 subdivisions | `areaKm2` |
 | Coordinates | 250 of 250 countries, 245 capitals; 4,780 of 5,050 subdivisions | `point`, `capitalPoint` |
 | Land borders | 327 pairs; 166 countries have one or more, 84 (islands, and Antarctica) none | `borders` |
+| Olympic codes | 209 of 250 countries | `ioc` |
+| Withdrawn countries | the 31 of ISO 3166-3, each with a successor | `/withdrawn` |
 | Groupings | 7 continents, 30 UN M49 areas, 23 bodies, 16 informal, 31 inside a country | `/groupings` |
 | Languages | English and Japanese | `LANGUAGES` |
 
@@ -420,25 +531,7 @@ Left out on purpose: geometry (see [Chizu](https://github.com/johnmorrisdotca/ch
 
 ## Architecture
 
-```text
-src/
-├── index.ts            the main entry: the countries and their lookups
-├── codes.ts            the "/codes" entry: the codes alone
-├── subdivisions.ts     the "/subdivisions" entry: every subdivision and its lookups
-├── load.ts             the "/load" entry: one country's subdivisions by dynamic import
-├── facts.ts            the "/facts" entry: population, area, coordinates, borders and conventions
-├── subdivision-facts.ts  the "/subdivision-facts" entry: one country's subdivision facts by dynamic import
-├── groupings.ts        the "/groupings" entry: continents, UN M49, bodies, informal groupings, regions
-├── fold.ts             folding what somebody typed: case, accents, width, kana
-├── rows.ts             turning the data's compact rows into objects
-├── types.ts            the shapes of a country and a subdivision, and the kinds of place
-├── version.ts          the package's version
-├── data/               written by scripts/build-data.ts: countries, codes, facts, groupings, and files per country
-├── subdivisions/       written by scripts/build-data.ts: the "/subdivisions/<code>" entries
-└── subdivision-facts/  written by scripts/build-data.ts: the "/subdivision-facts/<code>" entries
-```
-
-`scripts/build-data.ts` (`pnpm data`) makes `src/data/` from the inputs in `data-sources/` and three npm packages, with no network, and checks every input's SHA-256 first; run twice, it leaves the tree as it was. `scripts/data-config.ts`, `scripts/facts-config.ts` and `scripts/groupings-config.ts` hold the few things written by hand, each with its reason; `scripts/facts.ts`, `scripts/subdivision-facts.ts` and `scripts/groupings.ts` apply the rules written at their tops. Tests sit beside the code (`*.test.ts`). `scripts/` also builds the demo and its API page and checks the package as npm packs it; `demo/` is the page and `e2e/` its browser tests.
+The [architecture guide](docs/guides/architecture.md) retains the complete original source tree and explanation of data generation, lazy loading and public boundaries. Each native country resource keeps its existing file and runtime data.
 
 ## Data and licences
 
@@ -453,6 +546,8 @@ src/
 | Land borders, confirmed | Natural Earth 5.1.2 admin-0 at 1:50m, as drawn by Chizu 1.0.2 (a development dependency of the build, never of the package) | Public domain (Natural Earth); MIT (Chizu) |
 | First day of the week, measurement system, paper size, clock; UN M49; the UN's members | Unicode CLDR 48.2 (`cldr-core`) | Unicode-3.0 |
 | The bodies' members, the informal groupings and the regions inside a country | written for this package from each body's own list, on 2026-10-09 (`scripts/groupings-config.ts`) | MIT; lists of facts |
+| IOC codes, and the withdrawn countries' names | Wikidata, a snapshot of 2026-10-10 (`data-sources/wikidata-codes-2026-10-10.json`) | CC0 |
+| The withdrawn countries' codes, years and successors | ISO 3166-3's published list, transcribed once (`scripts/withdrawn-config.ts`) | A list of facts |
 | Aliases, a few readings and 46 corrected Japanese subdivision names | written for this package | MIT |
 
 [NOTICE.md](./NOTICE.md) carries the Unicode licence text and says what was changed, and [data-sources/README.md](./data-sources/README.md) says where every input came from and how to refresh it. Nothing under ODbL, CC BY-SA or the GPL is used, so the dataset is shipped under MIT with those notices.
@@ -467,45 +562,86 @@ Kuni was written because several sites by the same author each kept their own co
 
 ### Used by
 
-Nothing yet: it is new. Using Kuni in something? Open an *Add my project* issue and we will add you.
+- **[REST in Pieces](https://github.com/spxis/rest-in-pieces)**, a fake-data REST service, serves Kuni's countries (with their Olympic codes and withdrawn codes), subdivisions and groupings as an API, so a form or a test can fetch real country and region data without installing anything.
+
+Using Kuni in something else? Open an *Add my project* issue and we will add you.
 
 ### The family
 
-Kuni is not yet in the family's shared list (the template every demo's header and footer read), which is changed in every repository at once; until it is, its demo adds itself at the end. The list as it will be:
+<!-- family:start (made by scripts/family-readme.mjs from scripts/family-template.mjs; change those, not this) -->
+Kuni is one of thirty-two packages, each made for the same site, each at
+[github.com/johnmorrisdotca](https://github.com/johnmorrisdotca) or [github.com/spxis](https://github.com/spxis). The code of every one is MIT.
 
-Kuni is one of twenty-five packages, each made for the same site, each at
-[github.com/johnmorrisdotca](https://github.com/johnmorrisdotca). The code of every one is MIT.
+**Games — board**
 
-- [Korokoro](https://github.com/johnmorrisdotca/korokoro) (コロコロ): dice, with notation, exact odds, real sounds and the dice of many games. [Demo](https://johnmorrisdotca.github.io/korokoro/).
-- [Kyuubu](https://github.com/johnmorrisdotca/kyuubu) (キューブ): a turning cube for the browser, 2×2 to 7×7, with record solves to replay. [Demo](https://johnmorrisdotca.github.io/kyuubu/).
-- [Hitotsu](https://github.com/johnmorrisdotca/hitotsu) (一つ): a colour-card shedding game for two to eight, with the house rules people play. [Demo](https://johnmorrisdotca.github.io/hitotsu/).
-- [Toranpu](https://github.com/johnmorrisdotca/toranpu) (トランプ): a deck of playing cards, card games with computer players, and solitaires. [Demo](https://johnmorrisdotca.github.io/toranpu/).
-- [Tane](https://github.com/johnmorrisdotca/tane) (種): seeded random numbers and daily seeds, the same in every browser and on every server. [Demo](https://johnmorrisdotca.github.io/tane/).
+- [Domino](https://github.com/johnmorrisdotca/domino) (ドミノ): dominoes and Mexican Train. [Demo](https://johnmorrisdotca.github.io/domino/).
+- [Gunjin](https://github.com/johnmorrisdotca/gunjin) (軍人): five hidden-rank strategy games with pass-the-device play. [Demo](https://johnmorrisdotca.github.io/gunjin/).
 - [Narabe](https://github.com/johnmorrisdotca/narabe) (並べ): one rules engine for abstract board games, from gomoku and Reversi to Go and checkers. [Demo](https://johnmorrisdotca.github.io/narabe/).
+- [Sugoroku](https://github.com/johnmorrisdotca/sugoroku) (双六): backgammon and its variants, with the doubling cube and match play. [Demo](https://johnmorrisdotca.github.io/sugoroku/).
 - [Tenka](https://github.com/johnmorrisdotca/tenka) (天下): world conquest for two to six, on a map of the real world. [Demo](https://johnmorrisdotca.github.io/tenka/).
-- [Kumimoji](https://github.com/johnmorrisdotca/kumimoji) (組み文字): a crossword tile race, in English and Japanese kana. [Demo](https://johnmorrisdotca.github.io/kumimoji/).
-- [Tsunagi](https://github.com/johnmorrisdotca/tsunagi) (繋ぎ): a line-joining logic puzzle whose every level has exactly one answer. [Demo](https://johnmorrisdotca.github.io/tsunagi/).
+
+**Games — cards & tiles**
+
+- [Hitotsu](https://github.com/johnmorrisdotca/hitotsu) (一つ): a colour-card shedding game for two to eight, with the house rules people play. [Demo](https://johnmorrisdotca.github.io/hitotsu/).
 - [Jarajara](https://github.com/johnmorrisdotca/jarajara) (ジャラジャラ): mahjong tiles drawn as SVG, stacked layouts, and the matching solitaire Awase. [Demo](https://johnmorrisdotca.github.io/jarajara/).
-- [Suido](https://github.com/johnmorrisdotca/suido) (水道): a pipe puzzle: turn the pieces until the water reaches every drain. [Demo](https://johnmorrisdotca.github.io/suido/).
-- [Domino](https://github.com/johnmorrisdotca/domino) (ドミノ): dominoes and Mexican Train. [Demo](https://johnmorrisdotca.github.io/domino/).
-- [Kotoba](https://github.com/johnmorrisdotca/kotoba) (言葉): word lists and word-game rules in English, French, German and Japanese. [Demo](https://johnmorrisdotca.github.io/kotoba/).
-- [Sugoroku](https://github.com/johnmorrisdotca/sugoroku) (双六): backgammon and its variants, with the doubling cube and match play. [Demo](https://johnmorrisdotca.github.io/sugoroku/).
+- [Kumimoji](https://github.com/johnmorrisdotca/kumimoji) (組み文字): a crossword tile race, in English and Japanese kana. [Demo](https://johnmorrisdotca.github.io/kumimoji/).
+- [Toranpu](https://github.com/johnmorrisdotca/toranpu) (トランプ): a deck of playing cards, card games with computer players, and solitaires. [Demo](https://johnmorrisdotca.github.io/toranpu/).
+
+**Games — puzzles**
+
+- [Houseki](https://github.com/johnmorrisdotca/houseki) (宝石): gem and stone matching puzzles: falling triplets, stone collapse, colour chains and gem swap. [Demo](https://johnmorrisdotca.github.io/houseki/).
+- [Jirai](https://github.com/johnmorrisdotca/jirai) (地雷): minesweeper on shaped grids with verified no-guess boards. [Demo](https://johnmorrisdotca.github.io/jirai/).
+- [Karakuri](https://github.com/johnmorrisdotca/karakuri) (からくり): eight hyper-casual puzzle games, some of them physics: draw a shield, pull pins, cut ropes, slide blocks, pour tubes. [Demo](https://johnmorrisdotca.github.io/karakuri/).
 - [Kazu](https://github.com/johnmorrisdotca/kazu) (数): grid number puzzles: Sudoku and its variants, Futoshiki and Skyscrapers. [Demo](https://johnmorrisdotca.github.io/kazu/).
+- [Kyuubu](https://github.com/johnmorrisdotca/kyuubu) (キューブ): a turning cube for the browser, 2×2 to 7×7, with record solves to replay. [Demo](https://johnmorrisdotca.github.io/kyuubu/).
 - [Meikyuu](https://github.com/johnmorrisdotca/meikyuu) (迷宮): mazes on squares, hexagons, triangles and circles, made from a seed and drawn through with a finger or the mouse. [Demo](https://johnmorrisdotca.github.io/meikyuu/).
+- [Suido](https://github.com/johnmorrisdotca/suido) (水道): a pipe puzzle: turn the pieces until the water reaches every drain. [Demo](https://johnmorrisdotca.github.io/suido/).
+- [Tobiishi](https://github.com/johnmorrisdotca/tobiishi) (飛び石): peg solitaire with nine boards and seeded solvable challenges. [Demo](https://johnmorrisdotca.github.io/tobiishi/).
+- [Tsunagi](https://github.com/johnmorrisdotca/tsunagi) (繋ぎ): a line-joining logic puzzle whose every level has exactly one answer. [Demo](https://johnmorrisdotca.github.io/tsunagi/).
+
+**Games — dice & random**
+
+- [Korokoro](https://github.com/johnmorrisdotca/korokoro) (コロコロ): dice, with notation, exact odds, real sounds and the dice of many games. [Demo](https://johnmorrisdotca.github.io/korokoro/).
+- [Tane](https://github.com/johnmorrisdotca/tane) (種): seeded random numbers and daily seeds, the same in every browser and on every server. [Demo](https://johnmorrisdotca.github.io/tane/).
+
+**Language**
+
+- [Bushu](https://github.com/johnmorrisdotca/bushu) (部首): find a kanji by the parts it is made of. [Demo](https://johnmorrisdotca.github.io/bushu/).
 - [Hikidashi](https://github.com/johnmorrisdotca/hikidashi) (引き出し): a drawer of small Japanese text tools: era dates, kanji numerals, readings and sentence difficulty. [Demo](https://johnmorrisdotca.github.io/hikidashi/).
+- [Kotoba](https://github.com/johnmorrisdotca/kotoba) (言葉): word lists and word-game rules in English, French, German and Japanese. [Demo](https://johnmorrisdotca.github.io/kotoba/).
+
+**Geography & data**
+
+- [address-plus](https://github.com/johnmorrisdotca/address-plus) (アドレスプラス): parse and format addresses in the United States, Canada, Japan, Australia, France, Germany and the United Kingdom. [Demo](https://johnmorrisdotca.github.io/address-plus/).
 - [Chizu](https://github.com/johnmorrisdotca/chizu) (地図): maps of the world and of countries' regions, in English and Japanese, with a quiz and callouts. [Demo](https://johnmorrisdotca.github.io/chizu/).
-- [Bushu](https://github.com/johnmorrisdotca/bushu) (部首): find a kanji by the parts it is made of. [Demo](https://johnmorrisdotca.github.io/bushu/).
-- [Tobiishi](https://github.com/johnmorrisdotca/tobiishi) (飛び石): peg solitaire with nine boards and seeded solvable challenges. [Demo](https://johnmorrisdotca.github.io/tobiishi/).
-- [Jirai](https://github.com/johnmorrisdotca/jirai) (地雷): minesweeper on shaped grids with verified no-guess boards. [Demo](https://johnmorrisdotca.github.io/jirai/).
-- [Gunjin](https://github.com/johnmorrisdotca/gunjin) (軍人): five hidden-rank strategy games with pass-the-device play. [Demo](https://johnmorrisdotca.github.io/gunjin/).
-- [Karakuri](https://github.com/johnmorrisdotca/karakuri) (からくり): eight hyper-casual puzzle games, some of them physics: draw a shield, pull pins, cut ropes, slide blocks, pour tubes. [Demo](https://johnmorrisdotca.github.io/karakuri/).
-- [Houseki](https://github.com/johnmorrisdotca/houseki) (宝石): gem and stone matching puzzles: falling triplets, stone collapse, colour chains and gem swap. [Demo](https://johnmorrisdotca.github.io/houseki/).
-- [Kuni](https://github.com/johnmorrisdotca/kuni) (国): every country and its subdivisions, with ISO 3166 codes and names in English and Japanese. [Demo](https://johnmorrisdotca.github.io/kuni/).
+- [Hata](https://github.com/johnmorrisdotca/hata) (旗): country and regional flags as SVG, at their true proportions and keyed by ISO code. [Demo](https://johnmorrisdotca.github.io/hata/).
+- [Kuni](https://github.com/johnmorrisdotca/kuni) (国): countries and their regions, with ISO codes and names in English and Japanese. [Demo](https://johnmorrisdotca.github.io/kuni/).
+
+**Sports**
+
+- [Dougu Sports](https://github.com/johnmorrisdotca/dougu-sports) (道具): sports emblems as SVG: trophies, medals, crests, and the ball and gear of every sport, with optional 3D turning. [Demo](https://johnmorrisdotca.github.io/dougu-sports/).
+- [Kyogijo Stadiums](https://github.com/johnmorrisdotca/kyogijo-stadiums) (競技場): sports fields, rinks, courts and ballparks drawn to scale as SVG, with each team and the score on them. [Demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/).
+- [Senshu Jerseys](https://github.com/johnmorrisdotca/senshu-jerseys) (選手): sports jerseys, sweaters, kits, caps, helmets and retired-number banners as SVG, front and back, with optional 2.5D turning. [Demo](https://johnmorrisdotca.github.io/senshu-jerseys/).
+- [Taisen Brackets](https://github.com/johnmorrisdotca/taisen-brackets) (対戦): a sport-agnostic tournament bracket, drawn as SVG, from a list of ties. [Demo](https://johnmorrisdotca.github.io/taisen-brackets/).
+
+**Developer tools**
 
-**This package is Kuni.** The demos of all twenty-five share one header and footer, so each links the rest.
+- [REST in Pieces](https://github.com/spxis/rest-in-pieces) (レスト・イン・ピーシーズ): seeded test data and REST APIs for frontend development, with latency and error drills. [Demo](https://spxis.github.io/rest-in-pieces/).
+
+
+**This package is Kuni.** The demos of all thirty-two share one header and footer, so each links the rest.
+<!-- family:end -->
 
 ## Development
 
+```sh
+pnpm docs:site
+pnpm docs:check
+pnpm size --write
+```
+
+The shared generator checks real imports and guide examples. `pnpm docs:make` also refreshes the country-resource catalogue and the original language reference. `node scripts/build-data.ts --docs-only` refreshes stored generated examples without fetching or changing source data.
+
 ```sh
 pnpm install
 pnpm check                # lint, types, build, every test (sizes included), and the packed package
@@ -525,7 +661,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md); the commands are under [Development](#
 
 ## Changes
 
-See [CHANGELOG.md](./CHANGELOG.md). The latest release, 1.2.0, lets Compare colour each country and hide the capitals' dots, fits Compare's table on a phone, and downloads every list as a Markdown table and as SQL too.
+See [CHANGELOG.md](./CHANGELOG.md). The latest release, 1.4.0, adds the country card with the standard embed attributes, the shared embed builder, and the documentation site with a checked example for every export.
 
 ## Licence
 

package/dist/codes.d.cts

@@ -5,12 +5,19 @@
  * ```ts
  * import { COUNTRY_CODES } from "@johnmorrisdotca/kuni/codes";
  *
- * COUNTRY_CODES.length;   // 250
- * COUNTRY_CODES[0];       // "AD"
+ * console.log(COUNTRY_CODES.length);   // 250
+ * console.log(COUNTRY_CODES[0]);       // "AD"
  * ```
  */
 declare const COUNTRY_CODES: readonly ["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"];
-/** One of the 250 country codes, as a type: "JP" | "US" | ... */
+/** One of the 250 country codes, as a type: "JP" | "US" | ...
+ * @example
+ * ```ts
+ * import type { CountryCode } from "@johnmorrisdotca/kuni/codes";
+ * const code: CountryCode = "JP";
+ * console.log(code);
+ * ```
+ */
 type CountryCode = (typeof COUNTRY_CODES)[number];
 
 /**
@@ -23,9 +30,9 @@ type CountryCode = (typeof COUNTRY_CODES)[number];
  * ```ts
  * import { isCountryCode } from "@johnmorrisdotca/kuni/codes";
  *
- * isCountryCode("JP");   // true
- * isCountryCode("jp");   // false
- * isCountryCode("XX");   // false
+ * console.log(isCountryCode("JP"));   // true
+ * console.log(isCountryCode("jp"));   // false
+ * console.log(isCountryCode("XX"));   // false
  * ```
  */
 declare const isCountryCode: (value: unknown) => value is CountryCode;

package/dist/codes.d.ts

@@ -5,12 +5,19 @@
  * ```ts
  * import { COUNTRY_CODES } from "@johnmorrisdotca/kuni/codes";
  *
- * COUNTRY_CODES.length;   // 250
- * COUNTRY_CODES[0];       // "AD"
+ * console.log(COUNTRY_CODES.length);   // 250
+ * console.log(COUNTRY_CODES[0]);       // "AD"
  * ```
  */
 declare const COUNTRY_CODES: readonly ["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"];
-/** One of the 250 country codes, as a type: "JP" | "US" | ... */
+/** One of the 250 country codes, as a type: "JP" | "US" | ...
+ * @example
+ * ```ts
+ * import type { CountryCode } from "@johnmorrisdotca/kuni/codes";
+ * const code: CountryCode = "JP";
+ * console.log(code);
+ * ```
+ */
 type CountryCode = (typeof COUNTRY_CODES)[number];
 
 /**
@@ -23,9 +30,9 @@ type CountryCode = (typeof COUNTRY_CODES)[number];
  * ```ts
  * import { isCountryCode } from "@johnmorrisdotca/kuni/codes";
  *
- * isCountryCode("JP");   // true
- * isCountryCode("jp");   // false
- * isCountryCode("XX");   // false
+ * console.log(isCountryCode("JP"));   // true
+ * console.log(isCountryCode("jp"));   // false
+ * console.log(isCountryCode("XX"));   // false
  * ```
  */
 declare const isCountryCode: (value: unknown) => value is CountryCode;