localized-regions 1.0.2 → 1.2.0

package/README.md

@@ -24,6 +24,7 @@ provinceOptions('ES');  // [{ value: 'ES-MA', label: 'Málaga' }, { value: 'ES-B
 - **Correct Spanish provinces** - all **50 provinces** with ISO 3166-2 codes and their parent autonomous community. (Popular datasets like `country-state-city` return only ~16 of them for Spain.)
 - **Stable, invoicing-safe values** - country = ISO 3166-1 code (`ES`), province = ISO 3166-2 code (`ES-MA`). Labels are display-only.
 - **Full city database** - cities for every country, sourced from `country-state-city` at runtime.
+- **Correct Dutch cities** - the Netherlands is served from the official Dutch place register (BAG woonplaatsen), not `country-state-city`, whose NL list is 19% `Gemeente X` municipality records and missing roughly 1000 real places.
 - **Framework-agnostic** - no React / MUI / Chakra dependency. Plain data plus ready-to-use `{ value, label }` options.
 - **TypeScript types included.**
 
@@ -92,9 +93,12 @@ import { countryOptions } from 'localized-regions';
 | `getProvinces(countryCode)` | `Province[]` (Spain = curated 50) |
 | `getProvince(provinceCode)` | `Province` |
 | `getCities(countryCode, provinceCode?)` | `City[]` |
+| `cityMatches(city, input)` | `boolean` - does this city match typed input, by name or alias |
 | `countryOptions(locale?)` | `Option[]` (`{ value, label }`) |
 | `provinceOptions(countryCode)` | `Option[]` |
 | `cityOptions(countryCode, provinceCode?)` | `Option[]` |
+| `formatAddressLine1(countryCode, street, houseNumber)` | address line 1 in the country's own order |
+| `isHouseNumberFirst(countryCode)` | `boolean` - does this country write the number before the street |
 
 ## How the data is built
 
@@ -102,7 +106,8 @@ Data is generated at build time (`npm run generate`) and committed under `data/`
 
 - **Countries** - `Intl.DisplayNames` (English) plus a code list, 250 countries.
 - **Provinces** - `iso-3166-2` subdivisions. Spain is curated to 50 provinces, with 4 regional-language names aliased to their common form (Nafarroa -> Navarra, Balears -> Balearic Islands, Alacant -> Alicante, Castelló -> Castellón).
-- **Cities** - `country-state-city` at runtime.
+- **Cities** - `country-state-city` at runtime, except the Netherlands.
+- **Netherlands cities** - the official BAG woonplaats register, fetched at build time from the PDOK Locatieserver and baked into `data/cities-nl`. No runtime API call and no API key. Generation fails if a `Gemeente X` entry ever reappears.
 
 Regenerate after a data-source bump:
 
@@ -110,6 +115,50 @@ Regenerate after a data-source bump:
 npm run generate && npm run build
 ```
 
+## Netherlands cities
+
+NL city data comes from the official Dutch place register (BAG woonplaatsen, via
+the PDOK Locatieserver) rather than `country-state-city`, whose NL list contains
+325 `Gemeente X` municipality records and is missing roughly 1000 real places.
+
+The Hague is returned as `Den Haag` - the name the municipality, PostNL and
+Taaladvies all use for addresses. Its formal name `'s-Gravenhage` is kept as a
+search alias on `City.aliases`, never as a separate selectable option. Use
+`cityMatches` as your select's `filterOption` so aliases are searchable:
+
+```js
+import { getCities, cityMatches } from 'localized-regions';
+
+<Select
+  options={getCities('NL', 'NL-ZH')}
+  getOptionLabel={(c) => c.name}
+  getOptionValue={(c) => c.name}
+  filterOption={(option, input) => cityMatches(option.data, input)}
+/>
+```
+
+`getProvinces('NL')` returns the 12 real provinces. Aruba, Curacao and Sint
+Maarten are separate constituent countries, and Bonaire, Saba and Sint Eustatius
+are Caribbean special municipalities; ISO 3166-2 lists all six under NL, but they
+are not provinces and have no cities, so they are excluded.
+
+## Address line 1 order
+
+Countries disagree on whether the house number comes before or after the
+street. `formatAddressLine1` builds line 1 from the separate street and number
+(for example Google Places `route` + `street_number`) in the country's order:
+
+```js
+import { formatAddressLine1 } from 'localized-regions';
+
+formatAddressLine1('NL', 'Boerendanserdijk', '43a'); // "Boerendanserdijk 43a"
+formatAddressLine1('ES', 'Calle Mayor', '12');       // "Calle Mayor 12"
+formatAddressLine1('GB', 'Downing Street', '10');    // "10 Downing Street"
+```
+
+GB, IE, LU, FR and US put the number first; every other country puts the street
+first. A missing street or number is simply left out.
+
 ## Notes and limitations
 
 - **Spain city cascade is community-level.** The source city data groups Spanish cities under autonomous communities, not the 50 provinces, so `getCities('ES', 'ES-MA')` returns the parent community's cities (best-effort). City is best treated as a free-text field.

package/dist/address.d.ts

@@ -0,0 +1,8 @@
+/** Does this country write the house number before the street? */
+export declare function isHouseNumberFirst(countryCode: string): boolean;
+/**
+ * Address line 1 in the order the country writes it. `houseNumber` keeps any
+ * addition as given ("43a"). A missing street or number is left out rather
+ * than leaving a stray space, so `formatAddressLine1('NL', 'Dam', '')` is "Dam".
+ */
+export declare function formatAddressLine1(countryCode: string, street: string, houseNumber: string): string;

package/dist/address.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHouseNumberFirst = isHouseNumberFirst;
+exports.formatAddressLine1 = formatAddressLine1;
+/**
+ * Countries whose postal address puts the house number before the street, e.g.
+ * "10 Downing Street". Every other country writes the street first, e.g.
+ * "Boerendanserdijk 43a" (NL) or "Calle Mayor 12" (ES).
+ *
+ * ISO 3166-1 alpha-2, as Google Places returns it - the UK is "GB" (RAT-2178).
+ */
+const HOUSE_NUMBER_FIRST_COUNTRIES = new Set(['GB', 'IE', 'LU', 'FR', 'US']);
+/** Does this country write the house number before the street? */
+function isHouseNumberFirst(countryCode) {
+    return HOUSE_NUMBER_FIRST_COUNTRIES.has((countryCode ?? '').trim().toUpperCase());
+}
+/**
+ * Address line 1 in the order the country writes it. `houseNumber` keeps any
+ * addition as given ("43a"). A missing street or number is left out rather
+ * than leaving a stray space, so `formatAddressLine1('NL', 'Dam', '')` is "Dam".
+ */
+function formatAddressLine1(countryCode, street, houseNumber) {
+    const parts = isHouseNumberFirst(countryCode) ? [houseNumber, street] : [street, houseNumber];
+    return parts
+        .map((part) => (part ?? '').trim())
+        .filter(Boolean)
+        .join(' ');
+}

package/dist/data/cities-nl.d.ts

@@ -0,0 +1,3 @@
+import type { City } from '../types';
+declare const data: Record<string, City[]>;
+export default data;