@johnmorrisdotca/kuni 0.0.0-stage → 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,48 @@
+# 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.1.0] - 2026-10-09
+
+### Added
+
+- **Each country's capital in Japanese**: `country(code).capital` is now `{ en, ja }` (東京, キーウ), from Wikidata, for all 245 countries that have a capital.
+- **`@johnmorrisdotca/kuni/facts`**, a new entry so the main one stays small: for every country its population and area with the year each is for, the coordinates of the country and of its capital, the countries it shares a land border with (`[]` for an island), the side of the road it drives on, and CLDR's first day of the week, measurement system, paper size and clock. `facts(code)`, `allFacts()`, `distanceKm(from, to)` and `FACTS_READ`, the day Wikidata was read. Plain numbers and codes, for a build script to read as they are.
+- **`@johnmorrisdotca/kuni/subdivision-facts`** and **`/subdivision-facts/<code>`**: each subdivision's capital (in English and Japanese, with a reading in kana for Japan's prefectural capitals), population, area and coordinates, one country at a time, with `loadSubdivisionFacts(code)`. Complete for Japan's 47 prefectures.
+- **`@johnmorrisdotca/kuni/groupings`**: 107 groupings, each named in English and Japanese with its members, definition, source, licence and the day it was true. The seven continents; the 30 UN M49 areas; 23 international bodies (the UN, the EU with its candidates, the euro area, Schengen, the EEA, NATO, the G7 and G20, the OECD, ASEAN, the African Union, the Arab League, the GCC, the Commonwealth, OPEC, BRICS, Mercosur, the USMCA, APEC, CARICOM, the Pacific Islands Forum, the Nordic Council and Benelux) with the days members joined and left; 16 informal groupings (the Middle East, Latin America, the Caribbean, the Balkans, the Western Balkans, Scandinavia, the Nordic countries, the Baltic states, Central and Southeast Asia, the Maghreb, the Horn of Africa, the Sahel, the British Isles, Iberia, Asia-Pacific); and regions inside a country (Japan's eight 地方 and the nine-region variant, the US Census regions and divisions, Canada's five regions, the UK's four nations, Australia's states and territories). `groupings`, `grouping`, `groupingsOf` and `membersOf`, with `on` for a body's members on a past day.
+- Every public export has a doc comment, kept in the built `.d.ts` so an editor shows it, with `@param`, `@returns` and an example; the tests run every example. The API page shows each function's parameters, what it returns and its example, and each interface's fields.
+- Japan's Kinki region carries Kansai (関西地方) as its other name: `Grouping.otherNames`.
+- `docs/facts.md`, `docs/subdivision-facts.md` and `docs/groupings.md` say what was decided, how much is known, and why the rest is `null`.
+- The demo has views of its own, each at its own address: a page for each country (its outline from Chizu with the capital marked, its facts with their years, neighbours and groupings as links, furigana, the time now in each of its zones), two countries compared, every country in a table to filter, sort and narrow by grouping, a groupings explorer with a body's members on any day, three seeded quizzes (capitals, which country a region is in, calling codes) whose link gives the same questions, a country and region form widget in English or Japanese with its code to copy, search by calling code, currency or domain, and the data's quality in the open. Tables and lists download as CSV, JSON or text. Chizu is a development dependency for the demo's outlines only.
+
+### Changed
+
+- Equatorial Guinea's capital is Ciudad de la Paz (シウダ・デ・ラ・パス), where it moved in January 2026; it was Malabo.
+- **Continents follow UN M49** (from CLDR): Russia is in Europe, Cyprus in Asia, Timor-Leste in Asia, Christmas Island and the Cocos Islands in Oceania, the British Indian Ocean Territory in Africa, and the sub-Antarctic islands where M49 puts them (Bouvet Island and South Georgia in South America, Heard and McDonald in Oceania, the French Southern Lands in Africa). Antarctica is the one continent named by hand. 1.0.0 took the continent from countries-list.
+- **Norway's counties are those of 2024**, when Viken, Vestfold og Telemark and Troms og Finnmark were divided again: NO-31 Østfold, NO-32 Akershus, NO-33 Buskerud, NO-39 Vestfold, NO-40 Telemark, NO-55 Troms and NO-56 Finnmark are added and NO-30, NO-38 and NO-54 are gone, as in ISO 3166-2, which CLDR 48.2 has not caught up with. There are now 5,050 subdivisions.
+- Short names where CLDR's full name reads badly in a narrow space: DR Congo (コンゴ民主共和国) and Congo (コンゴ共和国) for "Congo - Kinshasa" and "Congo - Brazzaville", ミャンマー for ミャンマー (ビルマ), ココス諸島. Hong Kong, Macao and Myanmar already had CLDR's.
+- Each capital's Japanese name is the usual one (東京, 北京, ソウル), not a municipality's formal name, after a review.
+
+### Fixed
+
+- English subdivision names that were wrong in 1.0.0: Peterborough and Marlborough were cut short ("Peter", "Marl"); Chiayi City and Chiayi County were swapped, in Japanese too (嘉義市, 嘉義県); Bogotá was "Capital District"; Davao de Oro (ダバオ・デ・オロ州), Csongrád-Csanád and Nicaragua's two Caribbean Coast regions had their old names; Russia's republics Buryatia, Chechnya, Chuvashia, Kabardino-Balkaria, Karachay-Cherkessia and Udmurtia were adjectives, and Altai Republic and Komi Republic are told from their neighbours; Cần Thơ had lost its marks; Barisal Division and Barisal District had each other's names; and Morocco's twelve regions carried the names of the regions that held their codes before 2019 (MA-04 is Rabat-Salé-Kénitra, not Oriental), in Japanese too, where MA-11's came from a Wikidata label that was not a name. Every English name is now checked for each of these faults against Wikidata's English label, and the build stops on one nobody has decided (`docs/disagreements.md`).
+
+## [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,149 @@
+# 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 and languages, and the calling code where Wikidata has none | countries-list 3.4.1 by Annexare Studio | MIT, below |
+| Each country's capital in Japanese and its coordinates, population, area (with the year each is for), coordinates, driving side and the countries it shares a border with; each subdivision's capital, population, area and coordinates; the days members joined and left international bodies | Wikidata, the snapshot `data-sources/wikidata-facts-2026-10-09.json` | CC0, below |
+| 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 |
+| 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.
+
+The facts snapshot (`data-sources/wikidata-facts-2026-10-09.json`) holds the answers to the queries written in it:
+for every country and every subdivision, its capital with the capital's English and Japanese labels, kana name and
+coordinates; its best-ranked population and area with the day each is for; its coordinates; and, for countries, the
+side of the road it drives on, the countries it shares a border with and the international bodies it is a member
+of. `scripts/facts.ts`, `scripts/subdivision-facts.ts` and `scripts/groupings.ts` say how each is chosen. Figures are
+kept as Wikidata gives them, rounded only for coordinates (two decimal places).
+
+## Natural Earth, through Chizu
+
+Natural Earth (https://www.naturalearthdata.com/) is in the public domain: "No permission is needed to use Natural
+Earth. Crediting the authors is unnecessary." It is credited here anyway. Kuni ships no geometry. The build reads
+which countries' outlines touch from the country maps of `@johnmorrisdotca/chizu` 1.0.2 (MIT, © John Morris), drawn
+from Natural Earth 5.1.2 admin-0 countries at 1:50m, and keeps a border Wikidata states only where the outlines touch
+(or where `BORDERS_ADDED` in `scripts/facts-config.ts` says why it is a border on land). Chizu is a development
+dependency of the build and the demo; the published package depends on nothing.
+
+## 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 and languages
+are used as they are (from 1.1.0 the continent is UN M49's, from CLDR); 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, and no database with a share-alike condition: the richer country datasets under ODbL
+(mledoze/countries, REST Countries) and the GPL `country-state-city` were looked at and deliberately not used; the
+figures in `/facts` and `/subdivision-facts` are Wikidata's (CC0), and the land borders are checked against Natural
+Earth (public domain). 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`, `countries-list`
+and `@johnmorrisdotca/chizu` are development dependencies of the build (and Chizu of the demo) only: the package
+depends on nothing at run time.