@johnmorrisdotca/kuni 0.0.0-stage → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are written here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-10-09
+
+The first version: every country and its subdivisions, with ISO 3166 codes and names in English and Japanese.
+
+### Added
+
+- **`@johnmorrisdotca/kuni`**: the 250 countries (the 249 ISO 3166-1 codes and Kosovo, XK, as a user-assigned code), each with alpha-2, alpha-3 and numeric codes, its name in English and Japanese from Unicode CLDR 48.2, CLDR's short and variant forms, its own name, a reading in hiragana for a Japanese name written in kanji, its flag, continent and UN M49 subregion, calling code, currencies, top-level domain, capital, IANA time zones, languages and the kind of place its subdivisions are. Lookups: `country` (alpha-2 in either case, alpha-3 or numeric), `countries` (in code, English or Japanese order), `countryByName` (a name in either language, a short name, the country's own name or an alias such as Holland, UK, Burma or 米国), `countryName`, `flag`, `continentName`, `subregionName`, `fold` and `isCountryCode`.
+- **`/codes`**: the 250 codes alone, `COUNTRY_CODES`, `isCountryCode` and the `CountryCode` type, about 2 KB.
+- **`/subdivisions/<code>`**: one country's subdivisions as a list, one entry for each of the 200 countries that have them (Japan's 47 prefectures are under 3 KB).
+- **`/subdivisions`**: all 5,046 ISO 3166-2 subdivisions (3,590 at the first level, the rest below it, such as France's departments inside its regions), each with its code, short code, level, parent, kind of place, English name, Japanese name or `null`, and for Japan's prefectures a reading. Lookups: `subdivisions` (by level), `allSubdivisions`, `subdivision`, `subdivisionByShortCode`, `subdivisionByName` and `subdivisionsByName` (English or Japanese, with or without the word for its kind, オンタリオ for オンタリオ州), and `subdivisionTypeLabel` (都, 道, 府 and 県 for Japan; 州 for Canada's provinces).
+- **`/load`**: `loadSubdivisions(code)`, one dynamic import for each country, so a page loads only the countries somebody picks.
+- Japanese names for 3,523 of the 3,590 first-level subdivisions (3,387 from CLDR, 41 written by hand where CLDR's is wrong or out of date, 95 from Wikidata where CLDR has none) and 4,747 of all 5,046; the rest are `null`, never an English name copied in. CLDR's trailing brackets that tell a place from one of the same name elsewhere (セント・ポール (ドミニカ国), バリンゴ (カウンティ), 江原道 (北)) are taken off, 115 of them, and listed in `docs/name-rules.md`. The 46 hand-written names (`JA_NAME_OVERRIDES`: parishes as 教区, Ukraine's Japanese forms of 2022, places renamed since, Latvian spellings and others) are listed with their reasons in `docs/disagreements.md`, with the questions left for a native reader of Japanese. `docs/ja-gaps.md` lists the gaps.
+- ESM and CommonJS builds with types for both, `sideEffects: false`, no runtime dependencies, and no use of `Intl`, so a server and a browser give the same names.
+- `pnpm data` builds the data from inputs committed under `data-sources/` (CLDR's subdivision files, IANA's zone.tab and TLD list, a Wikidata snapshot), checked by SHA-256, with no network; `pnpm data:fetch` and `pnpm data:wikidata` refresh them.
+- A demo with three panels (find a country, the subdivisions of a country, look up a code) in English and Japanese, an API reference page, browser tests at a phone's width and a desk's, and the README's pictures taken from it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Morris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,127 @@
+# Notice: the data's licences
+
+The code of this package is under the MIT licence (see [LICENSE](LICENSE)). The data in `src/data/` (and
+`dist/`) is made from other people's work under their terms, which travel with it. Each data file opens with
+lines saying what it was made from, and `data-sources/sources.json` records every downloaded input with its
+address, the day it was read and its SHA-256.
+
+| What | Made from | Terms |
+| --- | --- | --- |
+| Country names in English and Japanese, their short and variant forms, alpha-3 and numeric codes, currencies, UN M49 continents and subregions | Unicode CLDR 48.2 (`cldr-localenames-full` and `cldr-core` 48.2.0 on npm) | Unicode-3.0, below |
+| Subdivision codes, English and Japanese names, the levels they are at and what they are inside | Unicode CLDR 48.2 (`common/subdivisions/en.xml`, `ja.xml`, `common/validity/subdivision.xml` at the tag `release-48-2`, and `cldr-core`'s `subdivisionContainment.json` and `aliases.json`) | Unicode-3.0, below |
+| Japanese names of the subdivisions CLDR has none for, the kana readings of Japan's prefectures, calling codes, and what kind of place each subdivision is | Wikidata, the snapshot `data-sources/wikidata-2026-10-09.json` | CC0, below |
+| Each country's own name, capital, continent and languages, and the calling code where Wikidata has none | countries-list 3.4.1 by Annexare Studio | MIT, below |
+| 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 |
+
+## Unicode CLDR
+
+The country and subdivision names, codes and regions are from the Unicode Common Locale Data Repository
+(https://cldr.unicode.org/). Its licence (https://www.unicode.org/license.txt, read on 2026-10-09) asks that
+this notice appear with all copies of the data or in its documentation:
+
+```text
+UNICODE LICENSE V3
+
+COPYRIGHT AND PERMISSION NOTICE
+
+Copyright © 2004-2026 Unicode, Inc.
+
+NOTICE TO USER: Carefully read the following legal agreement. BY
+DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
+SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
+TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
+DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of data files and any associated documentation (the "Data Files") or
+software and any associated documentation (the "Software") to deal in the
+Data Files or Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, and/or sell
+copies of the Data Files or Software, and to permit persons to whom the
+Data Files or Software are furnished to do so, provided that either (a)
+this copyright and permission notice appear with all copies of the Data
+Files or Software, or (b) this copyright and permission notice appear in
+associated Documentation.
+
+THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
+THIRD PARTY RIGHTS.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
+BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
+FILES OR SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall
+not be used in advertising or otherwise to promote the sale, use or other
+dealings in these Data Files or Software without prior written
+authorization of the copyright holder.
+
+SPDX-License-Identifier: Unicode-3.0
+```
+
+**What was changed.** Names are kept as CLDR writes them, made NFC with full-width Latin letters and digits made
+ordinary and spaces tidied, and with the superscript digit CLDR adds to tell two places of the same name apart
+(Île-de-France²) taken off. Codes CLDR retires because the place has a country code of its own (US-PR beside PR)
+are kept, as ISO 3166-2 keeps them, with the country's names. Where CLDR's Japanese name and Wikidata's differ,
+CLDR's is kept; [docs/disagreements.md](docs/disagreements.md) lists them.
+
+## Wikidata
+
+Wikidata's structured data is released under the Creative Commons CC0 License
+(https://www.wikidata.org/wiki/Wikidata:Licensing, read on 2026-10-09): no permission is needed and no credit is
+required. It is credited here anyway. The two queries are written in the snapshot file itself. A Japanese label
+is used only when CLDR has no Japanese name, when every current item for the code agrees on it, and when it is
+written in Japanese with no bracketed explanation; a reading only when Wikidata gives exactly one for the same
+name. Kinds of place are read from the English labels of the classes an item is an instance of.
+
+## countries-list
+
+```text
+The MIT License (MIT)
+
+Copyright (c) 2014 Annexare Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.```
+
+From https://github.com/annexare/Countries, version 3.4.1 on npm. Its own name (`native`), capital, continent and
+languages are used as they are; its calling code only where Wikidata has none.
+
+## IANA
+
+`zone.tab` is from the IANA time zone database, which is in the public domain. The list of top-level domains is
+published by IANA at https://data.iana.org/TLD/tlds-alpha-by-domain.txt; only which two-letter domains exist is
+read from it.
+
+## Not carried
+
+No geometry, population, area or other figure, so no database with a share-alike condition is carried: the
+richer country datasets under ODbL (mledoze/countries, REST Countries) and the GPL `country-state-city` were
+looked at and deliberately not used. GeoNames was not used either: its codes are not ISO 3166-2, and its licence
+asks for attribution on every use.
+
+## Made with
+
+`scripts/build-data.ts` reads the inputs with Node alone. `cldr-core`, `cldr-localenames-full` and
+`countries-list` are development dependencies of the build only: the package depends on nothing at run time.

package/README.md

@@ -1,3 +1,397 @@
-# Temporary Holding Version
+<h1 align="center">Kuni <sub>国</sub></h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<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>
+
+<p align="center" lang="ja">世界の国と、州・県・省などの行政区画を、ISO 3166のコードと英語・日本語の名前で収めた、依存パッケージのないTypeScriptデータセット。</p>
+
+<p align="center">
+  <a href="https://github.com/johnmorrisdotca/kuni/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/johnmorrisdotca/kuni/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.npmjs.com/package/@johnmorrisdotca/kuni"><img alt="npm" src="https://img.shields.io/npm/v/@johnmorrisdotca/kuni?color=2f5d4a"></a>
+  <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">
+</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>
+
+<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 three 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" 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,046 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. 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
+
+```sh
+npm install @johnmorrisdotca/kuni
+```
+
+```ts
+import { country, countryByName, countryName } from "@johnmorrisdotca/kuni";
+
+countryByName("ドイツ")?.alpha2;          // "DE"; "Germany", "どいつ" and "Deutschland" find it too
+countryByName("Holland")?.name.ja;        // "オランダ"
+countryName("US", "ja", { short: true }); // "アメリカ"
+country("JP")?.callingCode;               // "+81"
+```
+
+One country's subdivisions are an entry of their own, so a page that needs Japan's prefectures carries Japan's and no other:
+
+```ts
+import prefectures from "@johnmorrisdotca/kuni/subdivisions/jp";
+
+prefectures.length;   // 47
+prefectures[12];      // { code: "JP-13", name: { en: "Tokyo", ja: "東京都" }, reading: "とうきょうと", type: "metropolis", ... }
+```
+
+Install the scoped name: the unscoped `kuni` on npm is somebody else's package.
+
+## Who it is for
+
+- **Forms and profiles** that ask where somebody lives: a country select in either language, a state or prefecture select under it, and a free-text box whose "UK" or "Holland" still resolves to a code.
+- **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.
+
+## Features
+
+- **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,046 ISO 3166-2 codes in 200 countries: 3,590 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,523 of the 3,590 first-level subdivisions, and `null` for the rest, never a guess.
+- **Found by what somebody typed.** Case, accents, full-width letters, half-width kana and hiragana or katakana are folded away, and the aliases people use (Holland, UK, Burma, 米国) are known.
+- **Kinds of place**: prefecture, state, province, region and some thirty more, read from Wikidata, with the Japanese word for each (県, 州, 省) where a country's names agree on one.
+- **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.
+- **Typed, frozen, pure and the same everywhere.** ESM and CommonJS, types for both, no dependencies, no network and no `Intl`.
+
+## Use it in your project
+
+### Install
+
+```sh
+npm install @johnmorrisdotca/kuni
+# or: pnpm add @johnmorrisdotca/kuni
+# or: yarn add @johnmorrisdotca/kuni
+```
+
+It ships ES modules and CommonJS, with types for both and `sideEffects: false`. CommonJS is there because Node scripts and some packages that will read it (an address parser among them) want `require`; the rest of the family is ES modules only.
+
+### The entry points
+
+| Entry | What it carries | Size (ESM) |
+| --- | --- | --- |
+| `@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,046 subdivisions and the subdivision lookups | 216 KB, 85 KB gzipped |
+
+### 1. The countries
+
+```ts
+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
+```
+
+### 2. One country's subdivisions
+
+```ts
+import states from "@johnmorrisdotca/kuni/subdivisions/us";
+// const { SUBDIVISIONS } = require("@johnmorrisdotca/kuni/subdivisions/us");
+
+states.filter((one) => one.type === "state").length;   // 50; DC and the six outlying areas make 57
+```
+
+### 3. Loaded when they are wanted
+
+```ts
+import { loadSubdivisions } from "@johnmorrisdotca/kuni/load";
+
+const regions = await loadSubdivisions(form.country);   // [] for a country with none, null for a code that is not one
+```
+
+### 4. Every subdivision, on a server
+
+```ts
+import { subdivision, subdivisionByName, subdivisions, subdivisionTypeLabel } from "@johnmorrisdotca/kuni/subdivisions";
+
+subdivisionByName("オンタリオ州", { country: "CA" })?.code;   // "CA-ON"
+subdivisions("FR")?.length;                                  // 26 regions and overseas parts
+subdivisions("FR", { level: "all" })?.length;                // 124, with the departments
+subdivisionTypeLabel("JP-13", "ja");                         // "都"
+```
+
+### In a page, with no bundler
+
+```html
+<script type="module">
+  import { countryByName } from "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/kuni@1/dist/index.js";
+  console.log(countryByName("Holland")?.name.ja);   // オランダ
+</script>
+```
+
+## Examples
+
+### A country select, in either language
+
+```ts
+import { countries } from "@johnmorrisdotca/kuni";
+
+const options = (lang: "en" | "ja") =>
+  countries({ order: lang }).map((one) => ({ value: one.alpha2, label: `${one.flag} ${one.name[lang]}` }));
+```
+
+### A state or prefecture select that follows it
+
+```ts
+import { loadSubdivisions } from "@johnmorrisdotca/kuni/load";
+
+async function regionOptions(countryCode: string, lang: "en" | "ja") {
+  const list = (await loadSubdivisions(countryCode)) ?? [];
+  return list.filter((one) => one.level === 1).map((one) => ({ value: one.code, label: one.name[lang] ?? one.name.en }));
+}
+```
+
+The Japanese name is `null` where no source has one, so the fallback to English is the page's choice, made in the open.
+
+### What somebody typed into a free-text country box
+
+```ts
+import { countryByName } from "@johnmorrisdotca/kuni";
+
+for (const typed of ["UK", "the Netherlands", "ＵＳＡ", "どいつ", "Burma", "Narnia"]) {
+  console.log(typed, countryByName(typed)?.alpha2 ?? "(keep their words, no flag)");
+}
+// UK GB · the Netherlands NL · ＵＳＡ US · どいつ DE · Burma MM · Narnia (keep their words, no flag)
+```
+
+### A name that is two places
+
+```ts
+import { subdivisionByName, subdivisionsByName } from "@johnmorrisdotca/kuni/subdivisions";
+
+subdivisionByName("Punjab");                       // null: it is in India and in Pakistan
+subdivisionsByName("Punjab").map((one) => one.code); // ["IN-PB", "PK-PB"]
+subdivisionByName("Punjab", { country: "PK" })?.code; // "PK-PB"
+```
+
+## 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.
+
+| Entry | Exports |
+| --- | --- |
+| `@johnmorrisdotca/kuni` | `country`, `countries`, `countryByName`, `countryName`, `flag`, `continentName`, `subregionName`, `fold`, `isCountryCode`, `COUNTRY_CODES`, `CONTINENTS`, `LANGUAGES`, `VERSION`, and the types `Country`, `CountryCode`, `Continent`, `Language`, `CountriesOptions`, `CountryOrder`, `CountryNameOptions`, `Subdivision` and `SubdivisionType` |
+| `@johnmorrisdotca/kuni/codes` | `COUNTRY_CODES`, `isCountryCode` and the type `CountryCode` |
+| `@johnmorrisdotca/kuni/subdivisions` | `subdivisions`, `allSubdivisions`, `subdivision`, `subdivisionByShortCode`, `subdivisionByName`, `subdivisionsByName`, `subdivisionTypeLabel`, `SUBDIVISION_TYPES`, and the types `Subdivision`, `SubdivisionType`, `Level`, `SubdivisionsOptions` and `SubdivisionByNameOptions` |
+| `@johnmorrisdotca/kuni/subdivisions/<code>` | the country's list as the default export and as `SUBDIVISIONS` |
+| `@johnmorrisdotca/kuni/load` | `loadSubdivisions` and the type `Subdivision` |
+
+A country:
+
+```ts
+interface Country {
+  alpha2: string;                 // "JP"
+  alpha3: string;                 // "JPN"
+  numeric: string;                // "392"
+  kind: "iso" | "user";           // "user" for Kosovo, XK
+  name: { en: string; ja: string; local?: string };   // local: its own name, "Deutschland"
+  shortName?: { en?: string; ja?: string };           // "UK", アメリカ
+  reading?: string;               // hiragana, where the Japanese name is in kanji: "にほん"
+  flag: string;                   // the flag emoji
+  continent: "AF" | "AN" | "AS" | "EU" | "NA" | "OC" | "SA";
+  subregion?: string;             // UN M49: "030", Eastern Asia
+  callingCode?: string;           // "+81"; "+1" for every member of the North American plan
+  currency?: string[];            // ["JPY"]
+  tld?: string;                   // "jp"; "uk" for GB
+  capital?: { en: string };
+  zones?: string[];               // ["Asia/Tokyo"]
+  languages?: string[];           // ["ja"]
+  subdivisionType?: SubdivisionType;   // "prefecture"
+  aliases?: string[];             // other names it goes by
+}
+```
+
+A subdivision:
+
+```ts
+interface Subdivision {
+  code: string;                   // "JP-13", always the full ISO 3166-2 code
+  country: string;                // "JP"
+  shortCode: string;              // "13"
+  type: SubdivisionType | null;   // "metropolis"; null where no source says
+  level: 1 | 2 | 3;
+  parent?: string;                // "FR-IDF" for FR-75C, below the first level
+  name: { en: string; ja: string | null };
+  reading?: string;               // Japan's prefectures: "とうきょうと"
+}
+```
+
+Every function is pure and every object it hands out is frozen. A code or a name that is not one gives `null` (or an empty list), never a near miss.
+
+## Theming
+
+None, on purpose: Kuni is data and lookups, with no colours, markup or styles, so a page built on it looks however the page looks. The demo is the worked example: its panels are drawn by [`demo/demo.js`](./demo/demo.js) and [`demo/kuni.css`](./demo/kuni.css), over the family's shared stylesheet.
+
+## Limits
+
+| Limit | Value | Where |
+| --- | --- | --- |
+| Countries | 250: the 249 ISO 3166-1 codes and XK | `COUNTRY_CODES` |
+| Subdivisions | 5,046 in 200 countries; 3,590 at level 1, 1,456 at level 2, none at level 3 | `allSubdivisions` |
+| Japanese names of subdivisions | 3,523 of 3,590 at level 1 (3,387 from CLDR, 41 written by hand, 95 from Wikidata); 4,747 of all 5,046 | `name.ja`, [docs/ja-gaps.md](./docs/ja-gaps.md) |
+| Kinds of place | known for 4,739 of 5,046; the rest are `null` | `type` |
+| Readings in kana | Japan's 47 prefectures, and the 53 country names written with kanji | `reading` |
+| Languages | English and Japanese | `LANGUAGES` |
+
+Not here: cities, postal codes, coordinates, outlines, populations, and names in other languages. CLDR marks nearly all of its Japanese subdivision names "provisional"; where Wikidata names a place differently, CLDR's name is kept and the difference listed in [docs/disagreements.md](./docs/disagreements.md) (234 of 4,322 compared) for review. CLDR's trailing brackets (セント・ポール (ドミニカ国), バリンゴ (カウンティ)) are taken off by a rule listed in [docs/name-rules.md](./docs/name-rules.md), and 46 names a reviewer found wrong or out of date are written by hand, with their reasons, in [docs/disagreements.md](./docs/disagreements.md).
+
+## Accessibility
+
+Kuni draws nothing: it gives a page names, codes and readings, so what it can do for accessibility is give names a screen reader can say and a person can find by typing.
+
+- **Names in the reader's language.** Every country and nearly every first-level subdivision has a Japanese name, and Japan's prefectures and the kanji country names have readings in hiragana, for furigana or for a screen reader.
+- **Forgiving search.** A person who types in kana, in full-width letters or without accents still finds the place.
+- **Flags are never the only label.** A flag is an emoji that many screen readers say only as two letters; the demo always writes the name beside it.
+- **In the demo**, every panel is a labelled region, each box has a label, the answers are `aria-live`, the list of subdivisions is a real table with column headers, every control is at least 44 pixels square, and the page fits a phone at 390 pixels.
+- **Not yet.** The demo's colours have not been measured against WCAG contrast ratios, and its Japanese has not been read by a native reader (see [Languages](#languages)).
+
+## Browser and runtime support
+
+The package is data and plain functions, so it runs anywhere JavaScript does: any browser with ES2022 and Unicode property escapes in regular expressions, and Node. Building it from source and running its data scripts needs Node 24 or later, which runs TypeScript as it is; CI tests on Node 24 on Linux, macOS and Windows. The demo is played in a real Chromium at a phone's width (with touch) and a desk's, and in WebKit at a phone's width.
+
+## Languages
+
+Every name is in English and Japanese. The country names, the subdivision names and the kinds of place in Japanese come from Unicode CLDR and Wikidata. A few strings are written for this package: the aliases (米国, 英国, 豪州), the readings of the 53 country names written with kanji and of two prefectures, the Japanese type words the build looks for, and the demo's own words. The subdivision names have been read through by a strong, but not a native, reader of Japanese, who corrected 46 of them (listed in [docs/disagreements.md](./docs/disagreements.md), with six questions left open). **Japanese: included; not yet reviewed by a native reader. Corrections welcome.** Every line of the demo is listed beside its English in [docs/strings-ja.md](./docs/strings-ja.md), and there is an [issue template](https://github.com/johnmorrisdotca/kuni/issues/new?template=fix-a-translation.md) for fixing a name or a line.
+
+## Roadmap
+
+Not here yet, and each welcome as an [issue](https://github.com/johnmorrisdotca/kuni/issues):
+
+- Names in other languages, from CLDR, as an entry per language (`/names/<locale>`).
+- Each subdivision's name in its own language and script (Wikidata P1705).
+- The Japanese names CLDR and Wikidata both lack (listed in [docs/ja-gaps.md](./docs/ja-gaps.md)), when a source has them.
+
+Left out on purpose: geometry and coordinates (see [Chizu](https://github.com/johnmorrisdotca/chizu)), and any data under a share-alike or GPL licence.
+
+## 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
+├── 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, and a file per country
+└── subdivisions/       written by scripts/build-data.ts: the "/subdivisions/<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` holds the few things written by hand. 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.
+
+## Data and licences
+
+| What | From | Licence |
+| --- | --- | --- |
+| Country names, short and variant forms, codes, currencies, continents and subregions | Unicode CLDR 48.2 (`cldr-core`, `cldr-localenames-full`) | Unicode-3.0 |
+| Subdivision codes, names, levels and parents | Unicode CLDR 48.2 (`common/subdivisions`, validity and containment) | Unicode-3.0 |
+| Japanese names CLDR lacks, prefecture readings, calling codes, kinds of place | Wikidata, a snapshot of 2026-10-09 | CC0 |
+| Own names, capitals, continents, languages | countries-list 3.4.1 | MIT |
+| Time zones and top-level domains | IANA tzdb 2026e `zone.tab`, IANA's TLD list | Public domain; 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.
+
+## The name
+
+*Kuni* (国) is Japanese for "country": a nation, as in 国境 (*kokkyō*, a border) and 外国 (*gaikoku*, abroad). It is also the old word for a province, the 国 of Japan's former provinces (武蔵国, *Musashi no kuni*), and, in お国はどちらですか, "where are you from?", the place somebody calls home. The one word covers both halves of the data: the countries, and the regions inside them. ([Wiktionary: 国](https://en.wiktionary.org/wiki/国), which gives "country, nation" and "province".)
+
+## Where it comes from, and where it is used
+
+Kuni was written because several sites by the same author each kept their own country list: codes typed out by hand, names from `Intl.DisplayNames` that differed between the server and the browser, a few dozen aliases, and three separate tables of Japan's prefectures. It is the one list they can share.
+
+### Used by
+
+Nothing yet: it is new. Using Kuni in something? 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:
+
+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.
+
+- [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/).
+- [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/).
+- [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/).
+- [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/).
+- [Kazu](https://github.com/johnmorrisdotca/kazu) (数): grid number puzzles: Sudoku and its variants, Futoshiki and Skyscrapers. [Demo](https://johnmorrisdotca.github.io/kazu/).
+- [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/).
+- [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/).
+- [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/).
+
+**This package is Kuni.** The demos of all twenty-five share one header and footer, so each links the rest.
+
+## Development
+
+```sh
+pnpm install
+pnpm check                # lint, types, build, every test (sizes included), and the packed package
+pnpm test:package         # pack, install and import it as somebody who installed it would
+pnpm test:demo            # build the demo and play it in a real browser, at a phone's width and a desk's
+pnpm site                 # build the demo into site/, as the Pages workflow publishes it
+pnpm screenshots:readme   # take the README's pictures from the built demo, in light and dark
+pnpm data                 # rebuild src/data/ from data-sources/ (no network)
+pnpm data:report          # the coverage, and docs/ja-gaps.md
+pnpm docs:make            # rewrite docs/strings-ja.md after changing a word of the demo
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md); the commands are under [Development](#development), and the rules for the data are in its own section. Please follow the [code of conduct](./CODE_OF_CONDUCT.md). A security concern is for the [security policy](./SECURITY.md), not a public issue.
+
+## Changes
+
+See [CHANGELOG.md](./CHANGELOG.md). The first version is 1.0.0.
+
+## Licence
+
+MIT, © John Morris. The data is made from Unicode CLDR (Unicode-3.0), Wikidata (CC0), countries-list (MIT) and IANA (public domain), credited with their terms in [NOTICE.md](./NOTICE.md), which ships with the package.