localized-regions 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { Country, CountryOption, Province, City, Option } from './types';
+/**
+ * All countries. Pass a locale (e.g. "es") to get bilingual labels like
+ * "Spain (España)". Omit or pass "en" for English-only labels.
+ */
+export declare function getCountries(opts?: {
+    locale?: string;
+}): CountryOption[];
+export declare function getCountry(code: string): Country | undefined;
+/** Bilingual (or English) display label for a single country code. */
+export declare function formatCountryLabel(code: string, locale?: string): string;
+/**
+ * Provinces for a country. Spain returns the curated 50 Provinces (RAT-1776);
+ * other countries return their ISO 3166-2 subdivisions.
+ */
+export declare function getProvinces(countryCode: string): Province[];
+export declare function getProvince(provinceCode: string): Province | undefined;
+/**
+ * Cities. With no provinceCode, returns all cities of the country. With a
+ * provinceCode, returns cities for that subdivision (Spain: mapped to the
+ * parent community, best-effort).
+ */
+export declare function getCities(countryCode: string, provinceCode?: string): City[];
+/** Country options for react-select / MUI. value = ISO code, label = bilingual. */
+export declare function countryOptions(locale?: string): Option[];
+/** Province options. value = ISO 3166-2 code, label = province name. */
+export declare function provinceOptions(countryCode: string): Option[];
+/** City options. value = label = city name (cities have no stable code). */
+export declare function cityOptions(countryCode: string, provinceCode?: string): Option[];
+export * from './types';

package/dist/index.js

@@ -0,0 +1,141 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCountries = getCountries;
+exports.getCountry = getCountry;
+exports.formatCountryLabel = formatCountryLabel;
+exports.getProvinces = getProvinces;
+exports.getProvince = getProvince;
+exports.getCities = getCities;
+exports.countryOptions = countryOptions;
+exports.provinceOptions = provinceOptions;
+exports.cityOptions = cityOptions;
+const path = __importStar(require("path"));
+const country_state_city_1 = require("country-state-city");
+const DATA = path.join(__dirname, '..', 'data');
+// Static, build-time generated data (see scripts/generate.js). Loaded at runtime
+// so tsc does not need to copy JSON into dist.
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const countries = require(path.join(DATA, 'countries.json'));
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const provinces = require(path.join(DATA, 'provinces.json'));
+function displayName(code, locale) {
+    try {
+        return new Intl.DisplayNames([locale], { type: 'region' }).of(code) || undefined;
+    }
+    catch (e) {
+        return undefined;
+    }
+}
+function buildLabel(name, localized) {
+    return localized && localized !== name ? `${name} (${localized})` : name;
+}
+/**
+ * All countries. Pass a locale (e.g. "es") to get bilingual labels like
+ * "Spain (España)". Omit or pass "en" for English-only labels.
+ */
+function getCountries(opts = {}) {
+    const { locale } = opts;
+    return countries.map((c) => {
+        const localized = locale && locale !== 'en' ? displayName(c.code, locale) : undefined;
+        return { code: c.code, name: c.name, localized, label: buildLabel(c.name, localized) };
+    });
+}
+function getCountry(code) {
+    return countries.find((c) => c.code === code.toUpperCase());
+}
+/** Bilingual (or English) display label for a single country code. */
+function formatCountryLabel(code, locale) {
+    const c = getCountry(code);
+    if (!c)
+        return code;
+    const localized = locale && locale !== 'en' ? displayName(code, locale) : undefined;
+    return buildLabel(c.name, localized);
+}
+/**
+ * Provinces for a country. Spain returns the curated 50 Provinces (RAT-1776);
+ * other countries return their ISO 3166-2 subdivisions.
+ */
+function getProvinces(countryCode) {
+    return provinces[countryCode.toUpperCase()] || [];
+}
+function getProvince(provinceCode) {
+    const cc = provinceCode.split('-')[0];
+    return getProvinces(cc).find((p) => p.code === provinceCode);
+}
+// Spain cities in the source data are grouped at the autonomous-community level,
+// not by the 50 provinces. Where the community ISO code differs from the source
+// state code, map it here. City is best-effort for Spain and is expected to be a
+// free-text field (RAT-1772).
+const ES_COMMUNITY_TO_SOURCE = {
+    'ES-IB': 'PM', // Balearic Islands
+};
+/**
+ * Cities. With no provinceCode, returns all cities of the country. With a
+ * provinceCode, returns cities for that subdivision (Spain: mapped to the
+ * parent community, best-effort).
+ */
+function getCities(countryCode, provinceCode) {
+    const cc = countryCode.toUpperCase();
+    if (!provinceCode) {
+        return country_state_city_1.City.getCitiesOfCountry(cc) || [];
+    }
+    if (cc === 'ES') {
+        const community = getProvince(provinceCode)?.communityCode;
+        if (!community)
+            return [];
+        const source = ES_COMMUNITY_TO_SOURCE[community] || community.split('-')[1];
+        return country_state_city_1.City.getCitiesOfState(cc, source) || [];
+    }
+    const bare = provinceCode.includes('-') ? provinceCode.split('-').slice(1).join('-') : provinceCode;
+    return country_state_city_1.City.getCitiesOfState(cc, bare) || [];
+}
+// --------------------------------------------------- ready-to-use dropdown options
+/** Country options for react-select / MUI. value = ISO code, label = bilingual. */
+function countryOptions(locale) {
+    return getCountries({ locale }).map((c) => ({ value: c.code, label: c.label }));
+}
+/** Province options. value = ISO 3166-2 code, label = province name. */
+function provinceOptions(countryCode) {
+    return getProvinces(countryCode).map((p) => ({ value: p.code, label: p.name }));
+}
+/** City options. value = label = city name (cities have no stable code). */
+function cityOptions(countryCode, provinceCode) {
+    return getCities(countryCode, provinceCode).map((c) => ({ value: c.name, label: c.name }));
+}
+__exportStar(require("./types"), exports);

package/dist/types.d.ts

@@ -0,0 +1,41 @@
+export interface Country {
+    /** ISO 3166-1 alpha-2 code, e.g. "ES" */
+    code: string;
+    /** English name, e.g. "Spain" */
+    name: string;
+}
+export interface CountryOption {
+    code: string;
+    /** English name */
+    name: string;
+    /** Name in the requested locale, e.g. "España" (undefined when locale is en/absent) */
+    localized?: string;
+    /** Display label, e.g. "Spain (España)" when localized, else "Spain" */
+    label: string;
+}
+export interface Province {
+    /** ISO 3166-2 code, e.g. "ES-MA" */
+    code: string;
+    /** Parent country ISO 3166-1 alpha-2 code, e.g. "ES" */
+    countryCode: string;
+    /** Province name, e.g. "Málaga" */
+    name: string;
+    /** Parent autonomous community / region name (Spain only), e.g. "Andalusia" */
+    community?: string;
+    /** Parent autonomous community ISO 3166-2 code (Spain only), e.g. "ES-AN" */
+    communityCode?: string;
+    /** iso-3166-2 subdivision type for non-Spain countries, e.g. "Province" / "State" */
+    type?: string;
+}
+export interface City {
+    name: string;
+    countryCode: string;
+    stateCode?: string;
+    latitude?: string;
+    longitude?: string;
+}
+/** react-select / MUI style option */
+export interface Option {
+    value: string;
+    label: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "localized-regions",
+  "version": "1.0.0",
+  "description": "Country, province and city data with bilingual localized labels (e.g. \"Spain (España)\") and ISO 3166-1 / ISO 3166-2 codes. Ships all 50 Spanish provinces. Framework-agnostic, drop-in options for react-select and MUI dropdowns.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "data",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "generate": "node scripts/generate.js",
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run generate && npm run build"
+  },
+  "keywords": [
+    "country",
+    "countries",
+    "province",
+    "provinces",
+    "city",
+    "cities",
+    "region",
+    "regions",
+    "iso-3166",
+    "iso-3166-1",
+    "iso-3166-2",
+    "country-codes",
+    "country-list",
+    "country-names",
+    "localized",
+    "bilingual",
+    "i18n",
+    "localization",
+    "country-picker",
+    "country-select",
+    "province-select",
+    "region-picker",
+    "dropdown",
+    "react-select",
+    "mui",
+    "spain",
+    "spanish-provinces",
+    "provincias",
+    "autonomous-communities",
+    "subdivisions",
+    "address",
+    "geo"
+  ],
+  "homepage": "https://github.com/amit-2011/localized-regions-#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amit-2011/localized-regions-.git"
+  },
+  "bugs": {
+    "url": "https://github.com/amit-2011/localized-regions-/issues"
+  },
+  "author": "Amit Tank <amit@techvoot.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=14"
+  },
+  "dependencies": {
+    "country-state-city": "^3.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "iso-3166-2": "^1.0.0",
+    "typescript": "^5.4.0"
+  }
+}