@code-plate/iran-cities 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 2.0.0
+
+See [MIGRATION.md](./MIGRATION.md) ([فارسی](./MIGRATION.fa.md)) for upgrade steps. Supported Node.js (14+), React (16.8+) and TypeScript (3.9+) versions are unchanged.
+
+### Breaking
+- Provinces, cities, coordinates and the shared arrays returned by `getProvinces()`, `getAllCities()`, `getCities()` and `getCitiesByName()` are frozen and typed as `readonly`. Functions that returned fresh arrays in 1.x still do, and identities that were stable in 1.x are still stable.
+- `getCity(name)` / `getProvinceOfCity(name)` without a province prefer the provincial capital, then the better-known city, for names shared by several provinces. The result changed for 7 names: سردشت, شهریار, مهاباد, رضوانشهر, حاجی آباد, اردکان, چناران.
+- New required fields: `City.nameEn`, `City.aliases`, `FlatCity.provinceNameEn`, `Province.nameEn`, `Province.neighborIds`, `ProvinceListItem.nameEn` (affects hand-written objects in TypeScript only).
+- 25 Persian city names written with Arabic «ي»/«ك» now use Persian «ی»/«ک» (e.g. `كدكن` → `کدکن`). Lookups with either spelling still work; the changes are listed in `getDataChanges('1.2.0')`.
+
+### Added
+- Neighboring provinces: `getNeighborProvinces()`, `areNeighborProvinces()`, `Province.neighborIds`.
+- `@code-plate/iran-cities/boundaries`: province boundaries as GeoJSON, `getProvinceAt({ lat, lng })` and `getProvinceBoundary(id)`.
+- Components: `CityCombobox` (WAI-ARIA combobox) and `ProvinceCitySelect` in `/react/components` and `/lite/react/components`, styled by the plain-CSS `@code-plate/iran-cities/components.css` (CSS variables, dark mode, RTL, `:where()` selectors).
+- Validation: `@code-plate/iran-cities/zod` and `@code-plate/iran-cities/valibot` with `provinceIdSchema`, `cityIdSchema`, `provinceSchema`, `citySchema`, `provinceCitySchema` and custom messages.
+- Search fixes text typed with the wrong keyboard layout (`jivhk` → تهران) and exports `convertKeyboardLayout()`; opt out with `keyboardFix: false`.
+- English display names: `nameEn` (e.g. `Kohgiluyeh and Boyer-Ahmad`, `Bandar-e Gaz`) and `provinceNameEn`.
+- `DATA_VERSION`, `DATA_CHANGES` and `getDataChanges(sinceVersion)`.
+- `@code-plate/iran-cities/data/*`: CSV, JSON, SQL (PostgreSQL, MySQL, MariaDB, SQLite) and GeoJSON copies of the data.
+- `@code-plate/iran-cities/lite` and `/lite/react`: same API without coordinates.
+- `getDistance()`, `getNearestCities()`, `isAmbiguousCityName()`, `normalize()`, `SearchOptions.emptyQuery`.
+- `useProvinceCitySelect({ initialProvince, initialCity, value, onChange })`.
+- Documentation site with a live playground and an interactive map.
+
+### Changed
+- Data is stored in a packed columnar format: the data inside the bundle is about 20% smaller (brotli) and parses faster.
+- Normalization unifies «آ/أ/إ/ٱ», «ة/ۀ», «ؤ», «ى/ئ», strips diacritics, tatweel and apostrophes, and reads Persian/Arabic digits.
+- Fuzzy search caps allowed typos at a third of the query length and also matches typos at the start of longer names.
+- Search ties are broken by capital first, then Persian alphabetical order.
+- Invalid input (`undefined`, `null`, `NaN`, negative `limit`) no longer throws.
+- React entries share the core instead of bundling their own copy of the data, and start with `"use client"`.
+- Build moved from tsup (esbuild) to tsdown (Rolldown + Oxc), TypeScript 7 and `isolatedDeclarations`; `exports` serves `.d.mts` / `.d.cts`, and a plain `.d.ts` set keeps TypeScript 3.9 to 4.6 working.
+- Package license field is `MIT AND CC-BY-4.0 AND ODbL-1.0` to reflect the data sources.
+
+### Fixed
+- 25 city names used Arabic letters (see Breaking).
+- geoBoundaries labels Bandar-e Gaz county as Mazandaran; it is assigned to Golestan.
+- README said only provincial capitals have coordinates; 1152 cities do.
+- `allowScripts` in `package.json` is kept (it is npm's install-script allowlist); its stale `esbuild` entry was dropped because esbuild is no longer a dependency.
+
+### Tooling
+- Vitest unit, component, accessibility (axe-core) and property-based (fast-check) tests with coverage thresholds.
+- CI on Node.js 14–24, Deno, Bun, TypeScript 3.9–7 and Next.js 14–16; Oxlint, publint, Are The Types Wrong and size-limit budgets.
+- OpenSSF Scorecard and Dependabot.
+
 ## 1.2.0
 - **Added:** numeric `id` for provinces and cities (globally unique, stable); `isCapital`, `capitalId`, province `phoneCode`.
 - **Added:** `coordinates: { lat, lng, confidence }` for 1152 cities (GeoNames, CC BY 4.0); `confidence` is `'high' | 'medium' | 'low'`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohammad Javad Soleymani Fard
+
+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/MIGRATION.fa.md

@@ -0,0 +1,277 @@
+[English](./MIGRATION.md) | فارسی
+
+# مهاجرت از نسخه‌ی 1.x به 2.0
+
+نسخه‌ی 2.0 در بیشتر پروژه‌ها بدون هیچ تغییری جایگزین نسخه‌ی قبل می‌شود. کد جاوااسکریپت معمولی، بک‌اندهای Node.js/Express و فرم‌های رایج React/Next.js بدون تغییر کار می‌کنند. این راهنما **همه‌ی** تفاوت‌هایی را که ممکن است روی کد موجود اثر بگذارند فهرست می‌کند، توضیح می‌دهد چطور بفهمید پروژه‌تان درگیر است یا نه، و راه‌حل دقیق هر مورد را می‌گوید.
+
+همه‌ی موارد با اجرای فراخوانی‌های یکسان روی build نسخه‌ی 1.2.0 و build نسخه‌ی 2.0.0 راستی‌آزمایی شده‌اند.
+
+## فهرست
+
+- [چک‌لیست سریع](#چکلیست-سریع)
+- [چه چیزهایی تغییر نکرده](#چه-چیزهایی-تغییر-نکرده)
+- [تغییرات ناسازگار](#تغییرات-ناسازگار)
+  - [۱. داده‌های خروجی freeze شده‌اند و تایپ آرایه‌ها `readonly` است](#۱-دادههای-خروجی-freeze-شدهاند-و-تایپ-آرایهها-readonly-است)
+  - [۲. `getCity(name)` برای ۷ نام تکراری شهر دیگری برمی‌گرداند](#۲-getcityname-برای-۷-نام-تکراری-شهر-دیگری-برمیگرداند)
+  - [۳. فیلدهای اجباری جدید در تایپ‌های داده](#۳-فیلدهای-اجباری-جدید-در-تایپهای-داده)
+  - [۴. ۲۵ نام فارسی حالا با حروف فارسی نوشته می‌شوند](#۴-۲۵-نام-فارسی-حالا-با-حروف-فارسی-نوشته-میشوند)
+- [تغییرات رفتاری غیرناسازگار](#تغییرات-رفتاری-غیرناسازگار)
+- [قابلیت‌های جدید](#قابلیتهای-جدید)
+- [Next.js](#nextjs)
+- [پیدا کردن کدهای درگیر](#پیدا-کردن-کدهای-درگیر)
+- [پرسش‌های رایج](#پرسشهای-رایج)
+
+## چک‌لیست سریع
+
+۱. `npm install @code-plate/iran-cities@^2`
+
+۲. کامپایلر TypeScript را اجرا کنید. خطاهایی به شکل `TS4104: The type 'readonly City[]' is 'readonly' and cannot be assigned to the mutable type 'City[]'` مربوط به [مورد ۱](#۱-دادههای-خروجی-freeze-شدهاند-و-تایپ-آرایهها-readonly-است) هستند و خطای `Property 'aliases' is missing` (یا `nameEn`، `neighborIds`، `provinceNameEn`) مربوط به [مورد ۳](#۳-فیلدهای-اجباری-جدید-در-تایپهای-داده).
+
+۳. در کدتان دنبال جاهایی بگردید که داده‌ی برگشتی از پکیج را **تغییر** می‌دهند (`.sort(`، `.push(`، `.splice(`، `.reverse(` یا مقداردهی مثل `city.xxx =`). بخش [پیدا کردن کدهای درگیر](#پیدا-کردن-کدهای-درگیر) را ببینید.
+
+۴. اگر `getCity()` یا `getProvinceOfCity()` را با نام شهر و بدون استان صدا می‌زنید، [۷ نام](#۲-getcityname-برای-۷-نام-تکراری-شهر-دیگری-برمیگرداند) را بررسی کنید.
+
+۵. اگر `city.fa` را با نام‌های فارسی ذخیره‌شده در دیتابیس مقایسه می‌کنید، [مورد ۴](#۴-۲۵-نام-فارسی-حالا-با-حروف-فارسی-نوشته-میشوند) را ببینید.
+
+۶. اختیاری: کامپوننت‌های کلاینت را به `@code-plate/iran-cities/lite/react` ببرید تا حجم bundle کلاینت حدود یک‌سوم کم شود.
+
+## چه چیزهایی تغییر نکرده
+
+- **نسخه‌های پشتیبانی‌شده‌ی Node.js:** `engines.node` همچنان `>=14` است. فایل‌های منتشرشده روی Node.js نسخه‌های ۱۴، ۱۶، ۱۸، ۲۰، ۲۲ و ۲۴، هم به‌صورت CommonJS و هم ES module تست شده‌اند.
+- **نسخه‌های پشتیبانی‌شده‌ی TypeScript:** تایپ‌ها از TypeScript 3.9 تا 7.x کار می‌کنند، با `moduleResolution` برابر `node`/`node10`، `node16`/`nodenext` یا `bundler`.
+- **وابستگی React:** همچنان `>=16.8.0` و همچنان اختیاری است.
+- **مسیرهای import:** `@code-plate/iran-cities` و `@code-plate/iran-cities/react` تغییری نکرده‌اند. دو ساب‌پس اضافه شده و هیچ‌کدام حذف نشده.
+- **همه‌ی توابع و تایپ‌های نسخه‌ی 1.x** با همان نام و همان پارامترها وجود دارند.
+- **idها، slugها و داده‌ها:** id شهرها و استان‌ها، شناسه‌های انگلیسی، slugها، کدهای تلفن و مختصات دقیقاً مثل 1.2.0 هستند. نام‌های فارسی هم همان‌اند، به‌جز ۲۵ نام که حالا با حروف فارسی نوشته می‌شوند ([مورد ۴](#۴-۲۵-نام-فارسی-حالا-با-حروف-فارسی-نوشته-میشوند)). slugها و نام‌های قدیمی‌ای که 1.2.0 قبول می‌کرد (`gilan/sowme'eh-sara`، `kermanshah/هلشی`، `حلاشی`) همچنان کار می‌کنند.
+- **ساختار اشیا:** `Province`، `City`، `FlatCity`، `ProvinceListItem` و `Coordinates` همه‌ی فیلدهای قبلی را دارند و چند فیلد هم به آن‌ها اضافه شده ([مورد ۳](#۳-فیلدهای-اجباری-جدید-در-تایپهای-داده)).
+- **آرایه‌هایی که در 1.x هر بار تازه ساخته می‌شدند، هنوز تازه و قابل‌تغییرند:** `getProvincesList()`، `getCapitals()`، `searchCities()` و `searchProvinces()` در هر فراخوانی آرایه‌ی جدیدی برمی‌گردانند که مثل 1.x می‌توانید sort یا تغییرش دهید.
+- **آرایه‌هایی که در 1.x مشترک بودند، همان identity را دارند:** `getProvinces()`، `getAllCities()`، `getCities(...)` و `getCitiesByName(...)` مثل 1.x در هر فراخوانی همان آرایه را برمی‌گردانند و استفاده از آن‌ها در dependency arrayهای React همچنان امن است.
+- **هوک‌های React:** همان نام‌ها و همان فیلدهای خروجی (`province`، `city`، `setProvince`، `setCity`، `provinceId`، `cityId`، `selectedProvince`، `selectedCity`، `reset`، `query`، `setQuery`، `results`). `setQuery` همچنان تابع updater هم قبول می‌کند.
+
+## تغییرات ناسازگار
+
+### ۱. داده‌های خروجی freeze شده‌اند و تایپ آرایه‌ها `readonly` است
+
+**چه چیزی تغییر کرده.** در 1.x پکیج آرایه‌ها و اشیای داخلی خودش را مستقیم برمی‌گرداند. تغییر دادن آن‌ها (مثلاً `getCities('fars').sort(...)`) بی‌صدا داده‌ها را برای کل برنامه خراب می‌کرد، حتی برای درخواست‌های دیگر روی همان سرور. در 2.0 همه‌ی استان‌ها، شهرها و مختصات با `Object.freeze` قفل شده‌اند و آرایه‌های مشترک تایپ `readonly` دارند.
+
+مقادیر درگیر:
+
+| مقدار | تایپ در 1.x | تایپ در 2.0 |
+|---|---|---|
+| `getProvinces()` | `Province[]` | `readonly Province[]` |
+| `getCities(province)` | `City[]` | `readonly City[]` |
+| `getAllCities()` | `FlatCity[]` | `readonly FlatCity[]` |
+| `getCitiesByName(name)` | `FlatCity[]` | `readonly FlatCity[]` |
+| `Province.cities` | `City[]` | `readonly City[]` |
+| `useCities(province)` | `City[]` | `readonly City[]` |
+| هر شیء `Province`، `City`، `FlatCity` و `Coordinates` | قابل‌تغییر | freeze شده، فیلدها با تایپ `readonly` |
+
+درگیر نیستند: `getProvincesList()`، `getCapitals()`، `searchCities()`، `searchProvinces()`، `useProvinces()` و هوک‌های جستجو همچنان آرایه‌ی تازه و قابل‌تغییر برمی‌گردانند. اشیای برگشتی از `getProvincesList()` و `useProvinces()` هم تازه‌اند و قابل تغییر.
+
+**چطور خودش را نشان می‌دهد.**
+
+- در TypeScript: خطای `error TS4104: The type 'readonly City[]' is 'readonly' and cannot be assigned to the mutable type 'City[]'` یا `Cannot assign to 'fa' because it is a read-only property`.
+- در زمان اجرا، در ES moduleها، خروجی TypeScript و هر کد `'use strict'` (که شامل buildهای Next.js، Vite و webpack هم می‌شود): خطای `TypeError: Cannot assign to read only property ...` یا `Cannot add property ..., object is not extensible`.
+- در زمان اجرا، در CommonJS غیر strict: تغییر بی‌صدا نادیده گرفته می‌شود.
+
+**راه‌حل.**
+
+اگر فقط مقدار را می‌خوانید، تایپ را عوض کنید:
+
+```ts
+// 1.x
+const cities: City[] = getCities('fars');
+// 2.0
+const cities: readonly City[] = getCities('fars');
+```
+
+قبل از sort یا تغییر، از آرایه کپی بگیرید:
+
+```ts
+// 1.x (داده‌ی مشترک را برای همه تغییر می‌داد)
+const sorted = getCities('fars').sort((a, b) => a.fa.localeCompare(b.fa, 'fa'));
+// 2.0
+const sorted = [...getCities('fars')].sort((a, b) => a.fa.localeCompare(b.fa, 'fa'));
+```
+
+قبل از تغییر فیلدها، از اشیا کپی بگیرید:
+
+```ts
+// 1.x
+const cities = getCities('fars');
+cities.forEach((c) => { (c as any).label = c.fa; });
+// 2.0
+const cities = getCities('fars').map((c) => ({ ...c, label: c.fa }));
+```
+
+اگر مقدار را به APIای می‌دهید که آرایه‌ی قابل‌تغییر می‌خواهد، همان‌جا کپی کنید: `someFn([...getAllCities()])`.
+
+اگر یک کتابخانه‌ی دیگر اشیایی را که به آن می‌دهید تغییر می‌دهد (بعضی کامپوننت‌های جدول و select این کار را می‌کنند)، کپی عمیق بدهید: `structuredClone(getProvinces())` (Node.js 17 به بالا و همه‌ی مرورگرهای فعلی) یا `JSON.parse(JSON.stringify(getProvinces()))`.
+
+### ۲. `getCity(name)` برای ۷ نام تکراری شهر دیگری برمی‌گرداند
+
+**چه چیزی تغییر کرده.** ۲۵ نام شهر در بیش از یک استان وجود دارد. وقتی چنین نامی را **بدون** استان جستجو می‌کردید، 1.x شهری را برمی‌گرداند که کوچک‌ترین id را داشت و اغلب یک شهر کوچک بود. 2.0 به این ترتیب انتخاب می‌کند:
+
+۱. اگر یکی از آن‌ها مرکز استان باشد، همان؛ وگرنه
+۲. شهری که در داده‌ها به‌عنوان شهر شناخته‌شده‌تر علامت خورده؛ وگرنه
+۳. شهری که کوچک‌ترین id را دارد (مثل 1.x).
+
+این تغییر فقط روی `getCity(name)` و `getProvinceOfCity(name)` اثر دارد. جستجو با id، با slug یا همراه با استان (`getCity(name, province)`) تغییری نکرده است. `getCitiesByName(name)` هم تغییری نکرده و همچنان همه‌ی شهرهای هم‌نام را به ترتیب id برمی‌گرداند.
+
+فهرست کامل جستجوهایی که نتیجه‌شان عوض شده (نام فارسی و انگلیسی رفتار یکسانی دارند):
+
+| نام | نتیجه در 1.x | نتیجه در 2.0 |
+|---|---|---|
+| `سردشت` / `sardasht` | چهارمحال و بختیاری (id 104) | آذربایجان غربی (id 1179) |
+| `شهریار` / `shahriar` | آذربایجان شرقی (id 184) | تهران (id 1132) |
+| `مهاباد` / `mahabad` | اصفهان (id 270) | آذربایجان غربی (id 1171) |
+| `رضوانشهر` / `rezvanshahr` | اصفهان (id 279) | گیلان (id 408) |
+| `حاجی آباد` / `hajjiabad` | فارس (id 312) | هرمزگان (id 512) |
+| `اردکان` / `ardakan` | فارس (id 322) | یزد (id 1212) |
+| `چناران` / `chenaran` | خراسان شمالی (id 928) | خراسان رضوی (id 975) |
+
+**چه کسی درگیر است.** فقط کدی که `getCity()` یا `getProvinceOfCity()` را با یکی از این نام‌ها و **بدون** استان صدا می‌زند و به اینکه کدام شهر برمی‌گردد وابسته است؛ مثلاً کدی که ورودی متنی کاربر را به id تبدیل و ذخیره می‌کند.
+
+**راه‌حل.** به ترتیب اولویت:
+
+```ts
+// بهترین: هر وقت استان را دارید، آن را هم بدهید (نتیجه یکتاست و در 1.x و 2.0 یکسان است)
+getCity('مهاباد', 'isfahan');
+
+// یا به‌جای نام، id ذخیره و جستجو کنید
+getCityById(270);
+
+// یا نام‌های مبهم را تشخیص دهید و انتخاب را به کاربر بسپارید
+if (isAmbiguousCityName(input)) {
+  const options = getCitiesByName(input);
+}
+
+// دقیقاً رفتار 1.x (کوچک‌ترین id)
+const city = getCitiesByName(name)[0] ?? getCity(name);
+```
+
+اگر idهایی را که از جستجوی همین ۷ نام بدون استان در 1.x به دست آمده ذخیره کرده‌اید، همچنان به همان شهرهای قبلی اشاره می‌کنند و داده‌های ذخیره‌شده تغییری نمی‌کنند. فقط جستجوهای جدید شهر دیگری برمی‌گردانند.
+
+### ۳. فیلدهای اجباری جدید در تایپ‌های داده
+
+**چه چیزی تغییر کرده.** این فیلدها اضافه شده‌اند و همیشه مقدار دارند:
+
+| تایپ | فیلدهای جدید |
+|---|---|
+| `City` | `nameEn` (نام نمایشی انگلیسی، مثلاً `'Bandar-e Gaz'`)، `aliases` (املاهای دیگر و نام‌های قدیمی) |
+| `FlatCity` | دو فیلد بالا به‌علاوه‌ی `provinceNameEn` |
+| `Province` | `nameEn`، `neighborIds` |
+| `ProvinceListItem` | `nameEn` |
+
+**چه کسی درگیر است.** فقط کد TypeScriptای که این اشیا را **دستی می‌سازد**؛ معمولاً fixtureها و mockهای تست:
+
+```
+error TS2741: Property 'nameEn' is missing in type '{ ... }' but required in type 'City'.
+```
+
+**راه‌حل.** فیلدها را اضافه کنید:
+
+```ts
+const mockCity: City = { id: 1, isCapital: true, slug: 'alborz/karaj', en: 'karaj', fa: 'کرج', nameEn: 'Karaj', aliases: [] };
+```
+
+یا fixture را از داده‌ی واقعی بسازید تا همیشه با تایپ‌ها هماهنگ بماند: `const mockCity = getCityById(1)!;`
+
+### ۴. ۲۵ نام فارسی حالا با حروف فارسی نوشته می‌شوند
+
+**چه چیزی تغییر کرده.** در 1.x، نام ۲۵ شهر با حروف عربی «ي» و «ك» به‌جای «ی» و «ک» فارسی نوشته شده بود، مثل `كدكن` و `اسفرورين`. این نام‌ها در فهرست‌ها درست نمایش داده نمی‌شدند و جای اشتباهی مرتب می‌شدند. در 2.0 با حروف فارسی نوشته می‌شوند: `کدکن`، `اسفرورین`. idها، شناسه‌های انگلیسی و slugها تغییری نکرده‌اند.
+
+**چه کسی درگیر است.** فقط کدی که `city.fa` را **به‌صورت رشته‌ی خام** با مقداری که از 1.x ذخیره شده مقایسه می‌کند؛ مثلاً ستونی از نام‌های فارسی در دیتابیس. جستجوها درگیر نیستند: `getCity('كدكن')` همچنان شهر را پیدا می‌کند، چون همه‌ی lookupها هر دو حرف را نرمال می‌کنند.
+
+**راه‌حل.** به‌جای نام، id را مقایسه کنید، یا متن نرمال‌شده را:
+
+```ts
+import { normalize, getDataChanges } from '@code-plate/iran-cities';
+
+normalize(savedName) === normalize(city.fa);
+
+for (const change of getDataChanges('1.2.0')) {
+  if (change.type === 'spelling') {
+    await db.query('UPDATE addresses SET city_fa = $1 WHERE city_id = $2', [change.after?.fa, change.cityId]);
+  }
+}
+```
+
+`getDataChanges('1.2.0')` هر ۲۵ تغییر را همراه با املای قبلی و جدید برمی‌گرداند.
+
+## تغییرات رفتاری غیرناسازگار
+
+این تغییرات ممکن است نتیجه‌ی جستجو را عوض کنند؛ بیشتر به این شکل که جایی که 1.x چیزی پیدا نمی‌کرد حالا شهر پیدا می‌شود، ترتیب نتایج هم‌رتبه عوض می‌شود، یا نتیجه‌های فازی ضعیف حذف می‌شوند.
+
+| بخش | 1.x | 2.0 |
+|---|---|---|
+| نرمال‌سازی | `ي→ی`، `ك→ک`؛ فاصله، نیم‌فاصله و `-` نادیده گرفته می‌شد | علاوه بر آن `ى/ئ→ی`، `آ/أ/إ/ٱ→ا`، `ة/ۀ→ه`، `ؤ→و`؛ اعراب، کشیده‌ی `ـ`، `_` و آپاستروف نادیده گرفته می‌شوند؛ ارقام فارسی و عربی خوانده می‌شوند. حالا `getCity('ابادان')` و `getProvince('۲۸')` کار می‌کنند. |
+| نام‌های جایگزین | پشتیبانی نمی‌شد | `getCity('طهران')`، `getCity('esfahan')`، `getCity('mashad')`، `getCity('orumiyeh')`، `getCity('teheran')` و `getCity('urumieh')` به‌جای `undefined` شهر برمی‌گردانند. |
+| کد تلفن | `'021'`، `'21'`، `21` | همچنین `'۰۲۱'`، `'+9821'`، `'+98 21'` و `'0098 21'`. |
+| ترتیب جستجو | در امتیاز برابر، ترتیب داده‌ها حفظ می‌شد | در امتیاز برابر، اول مراکز استان و بعد ترتیب الفبای فارسی. به خاطر نرمال‌سازی گسترده‌تر و نام‌های جایگزین، یک جستجو ممکن است چند شهر بیشتر از قبل هم پیدا کند. |
+| جستجوی فازی (`fuzzy: true`) | برای هر جستجویی ۲ غلط تایپی مجاز بود و جستجوهای کوتاه نام‌های بی‌ربط را هم برمی‌گرداندند (`تهرن` به `اهر` و `بهمن` هم می‌رسید) | تعداد غلط مجاز حداکثر یک‌سوم طول عبارت است (`تهرن` فقط `تهران` را برمی‌گرداند) و غلط در ابتدای نام‌های بلندتر هم پیدا می‌شود. |
+| کیبورد اشتباه | `searchCities('jivhk')` چیزی برنمی‌گرداند | `تهران` را برمی‌گرداند: اگر نتیجه‌ای نباشد، عبارت طوری دوباره جستجو می‌شود که انگار با چیدمان دیگر تایپ شده. با `{ keyboardFix: false }` خاموش می‌شود. |
+| ورودی نامعتبر | `getCity(undefined)`، `searchCities(null)` و موارد مشابه خطای `TypeError` می‌دادند | مثل رشته‌ی خالی رفتار می‌کنند: `undefined`، آرایه‌ی خالی یا همه‌ی موارد. |
+| گزینه‌ی `limit` | `limit` منفی چند مورد از آخر را حذف می‌کرد | `limit` منفی یا صفر یعنی بدون محدودیت. |
+| `useProvinceCitySelect` | نام انگلیسی انتخاب‌ها را در state نگه می‌داشت | id را در state نگه می‌دارد. خروجی‌ها همان قبلی‌اند. شهری که متعلق به استان انتخاب‌شده نباشد حالا نادیده گرفته می‌شود. |
+| `@code-plate/iran-cities/react` | یک نسخه‌ی کامل جداگانه از داده‌ها داشت (حدود ۲۳۸ کیلوبایت بدون minify) | از ورودی اصلی استفاده می‌کند. برنامه‌ای که هر دو را import کند دیگر داده را دو بار ship نمی‌کند و هر دو یک نمونه‌ی مشترک دارند. |
+| `react` و `lite/react` | directive نداشتند | با `"use client"` شروع می‌شوند تا App Router در Next.js آن‌ها را ماژول کلاینت حساب کند. |
+
+## قابلیت‌های جدید
+
+- `@code-plate/iran-cities/lite` و `@code-plate/iran-cities/lite/react`: همان API بدون مختصات، حدود یک‌سوم سبک‌تر. مناسب برای انتخاب‌گر استان و شهر.
+- کامپوننت‌های دسترس‌پذیر با تم CSS خام: `CityCombobox` و `ProvinceCitySelect` از `@code-plate/iran-cities/lite/react/components` با استایل `@code-plate/iran-cities/components.css`.
+- اسکیمای اعتبارسنجی برای Zod (`/zod`) و Valibot (`/valibot`)، از جمله بررسی اینکه شهر متعلق به استان باشد.
+- استان‌های همسایه: `getNeighborProvinces(query)`، `areNeighborProvinces(a, b)` و `Province.neighborIds`.
+- مرز استان‌ها به‌صورت GeoJSON و `getProvinceAt({ lat, lng })` از `@code-plate/iran-cities/boundaries`.
+- نام نمایشی انگلیسی: `nameEn` برای استان‌ها و شهرها و `provinceNameEn` برای شهرهای مسطح.
+- `convertKeyboardLayout(text, 'fa' | 'en')`، `DATA_VERSION`، `DATA_CHANGES` و `getDataChanges(sinceVersion)`.
+- نسخه‌های CSV، SQL، JSON و GeoJSON داده‌ها در `@code-plate/iran-cities/data/*`.
+- `getDistance(from, to)` و `getNearestCities(point, { limit, minConfidence, maxDistanceKm })`.
+- `isAmbiguousCityName(name)` و `normalize(text)`.
+- `searchCities(query, { emptyQuery: 'none' })` برای query خالی به‌جای هر ۱۲۵۲ شهر، `[]` برمی‌گرداند.
+- `useProvinceCitySelect({ initialProvince, initialCity })` برای فرم‌های ویرایش، و `useProvinceCitySelect({ value, onChange })` برای حالت controlled با react-hook-form، Formik و کتابخانه‌های مشابه.
+- تایپ‌های جدید: `IranCities`، `IranCitiesGeo`، `IranCitiesHooks`، `LatLng`، `CoordinateConfidence`، `NearestCity`، `NearestCitiesOptions`، `Stats`، `ProvinceCityValue`، `ProvinceCitySelectOptions`، `ProvinceCitySelect`، `SearchState`، `CityComboboxProps`، `ProvinceCitySelectProps`، `DataChange`، `DataChangeType`، `KeyboardTarget`.
+
+## Next.js
+
+در پروژه‌ی Next.js لازم نیست چیزی را تغییر دهید. بهبودهای پیشنهادی:
+
+```tsx
+// app/page.tsx (Server Component): مستقیم از ورودی اصلی استفاده کنید
+import { getCity, getProvincesList } from '@code-plate/iran-cities';
+
+// app/address-form.tsx (Client Component): از هوک‌های lite استفاده کنید
+'use client';
+import { useProvinceCitySelect } from '@code-plate/iran-cities/lite/react';
+```
+
+- ورودی‌های هوک خودشان `"use client"` دارند. مثل هر هوک دیگری، فایل کامپوننتی که هوک را صدا می‌زند هم باید `'use client'` داشته باشد.
+- در کامپوننت‌های کلاینت از `lite/react` استفاده کنید، مگر اینکه مرورگر مختصات لازم داشته باشد. این کار حدود ۸ کیلوبایت (brotli) از bundle کلاینت کم می‌کند.
+- داده‌هایی که روی سرور می‌گیرید را می‌توانید به‌عنوان props به Client Componentها بدهید؛ اشیای freeze شده بدون مشکل serialize می‌شوند.
+- با Next.js 14 (webpack و React 18)، Next.js 15 (webpack) و Next.js 16 (Turbopack و webpack و React 19)، App Router، رندر استاتیک و `next start` راستی‌آزمایی شده است.
+
+## پیدا کردن کدهای درگیر
+
+```bash
+# مقادیری که ممکن است تغییر داده شوند (هر مورد را بررسی کنید)
+grep -rnE "get(Provinces|AllCities|Cities|CitiesByName)\([^)]*\)\.(sort|push|pop|shift|unshift|splice|reverse|fill|copyWithin)\(" src
+
+# جستجوی ۷ نامِ تغییرکرده بدون استان
+grep -rnE "get(City|ProvinceOfCity)\(['\"](سردشت|sardasht|شهریار|shahriar|مهاباد|mahabad|رضوانشهر|rezvanshahr|حاجی ?آباد|hajjiabad|اردکان|ardakan|چناران|chenaran)['\"]\)" src
+
+# اشیای City که دستی ساخته شده‌اند
+grep -rnE ":\s*(Flat)?City\s*=\s*\{" src
+```
+
+اجرای تست‌ها در حالت strict (هر test runner با ESM یا TypeScript) تغییرات ناخواسته را به `TypeError` تبدیل می‌کند و پیدا کردنشان را ساده می‌کند.
+
+## پرسش‌های رایج
+
+**می‌توانم همچنان از 1.x استفاده کنم؟** بله. 1.x همچنان کار می‌کند، ولی اصلاحات داده و قابلیت‌های جدید را نمی‌گیرد.
+
+**چرا داده‌ها freeze شده‌اند و به‌جایش همه‌جا کپی برنگردانده‌اید؟** توابعی که آرایه‌ی مشترک برمی‌گردانند در 1.x هم همین کار را می‌کردند و خیلی از برنامه‌ها به ثابت بودن identity آن‌ها وابسته‌اند (مثلاً در dependencyهای `useMemo` یا `useEffect`). کپی گرفتن در هر فراخوانی این رفتار را عوض می‌کرد و رندرهای اضافه ایجاد می‌کرد. freeze کردن identity را حفظ می‌کند و تغییر ناخواسته را به‌جای خراب کردن بی‌صدای داده‌ها، آشکار می‌کند. توابعی که در 1.x آرایه‌ی تازه برمی‌گرداندند، همچنان همین کار را می‌کنند.
+
+**idها یا slugها عوض شده‌اند؟** نه. idها و slugهای ذخیره‌شده از 1.x همچنان معتبرند.
+
+**نسخه‌ی 2.0 به Node.js، React یا TypeScript جدیدتری نیاز دارد؟** نه. حداقل‌ها همان 1.x است: Node.js 14، React 16.8 و TypeScript 3.9 برای تایپ‌ها.

package/MIGRATION.md

@@ -0,0 +1,272 @@
+English | [فارسی](./MIGRATION.fa.md)
+
+# Migrating from 1.x to 2.0
+
+Version 2.0 is mostly a drop-in upgrade. Plain JavaScript code, Node.js/Express backends and typical React/Next.js forms keep working without any change. This guide lists **every** difference that can affect existing code, how to find out whether your project is affected, and the exact fix.
+
+Each item was verified by running the same calls against the 1.2.0 build and the 2.0.0 build.
+
+## Contents
+
+- [Quick checklist](#quick-checklist)
+- [What did not change](#what-did-not-change)
+- [Breaking changes](#breaking-changes)
+  - [1. Returned data is frozen and array types are `readonly`](#1-returned-data-is-frozen-and-array-types-are-readonly)
+  - [2. `getCity(name)` picks a different city for 7 shared names](#2-getcityname-picks-a-different-city-for-7-shared-names)
+  - [3. New required fields on the data types](#3-new-required-fields-on-the-data-types)
+  - [4. 25 Persian names now use Persian letters](#4-25-persian-names-now-use-persian-letters)
+- [Behaviour changes that are not breaking](#behaviour-changes-that-are-not-breaking)
+- [New features you can adopt](#new-features-you-can-adopt)
+- [Next.js](#nextjs)
+- [Finding affected code](#finding-affected-code)
+- [FAQ](#faq)
+
+## Quick checklist
+
+1. `npm install @code-plate/iran-cities@^2`
+2. Run your TypeScript compiler. Errors of the form `TS4104: The type 'readonly City[]' is 'readonly' and cannot be assigned to the mutable type 'City[]'` are [item 1](#1-returned-data-is-frozen-and-array-types-are-readonly); `Property 'aliases' is missing` (or `nameEn`, `neighborIds`, `provinceNameEn`) is [item 3](#3-new-required-fields-on-the-data-types).
+3. Search your code for code that **modifies** data returned by the package (`.sort(`, `.push(`, `.splice(`, `.reverse(`, assignments to `city.xxx =`). See [Finding affected code](#finding-affected-code).
+4. If you call `getCity()` or `getProvinceOfCity()` with a name but without a province, check the [7 names](#2-getcityname-picks-a-different-city-for-7-shared-names).
+5. If you compare `city.fa` with Persian names stored in your database, check [item 4](#4-25-persian-names-now-use-persian-letters).
+6. Optional: switch client components to `@code-plate/iran-cities/lite/react` to cut the client bundle by about a third.
+
+## What did not change
+
+- **Supported Node.js versions:** `engines.node` is still `>=14`. The published files are tested on Node.js 14, 16, 18, 20, 22 and 24, as CommonJS and as ES modules.
+- **Supported TypeScript versions:** the type declarations work from TypeScript 3.9 up to 7.x, with `moduleResolution` set to `node`/`node10`, `node16`/`nodenext` or `bundler`.
+- **React peer dependency:** still `>=16.8.0`, still optional.
+- **Import paths:** `@code-plate/iran-cities` and `@code-plate/iran-cities/react` are unchanged. Two subpaths were added; none were removed.
+- **Every 1.x function and every exported type still exists** with the same name and the same parameters.
+- **Ids, slugs and data:** city and province ids, English ids, slugs, area codes and coordinates are identical to 1.2.0. Persian names are identical too, except 25 that now use Persian letters ([item 4](#4-25-persian-names-now-use-persian-letters)). Old slugs and names that 1.2.0 already accepted (`gilan/sowme'eh-sara`, `kermanshah/هلشی`, `حلاشی`) still resolve.
+- **Object shapes:** `Province`, `City`, `FlatCity`, `ProvinceListItem` and `Coordinates` keep every field they had. A few fields were added ([item 3](#3-new-required-fields-on-the-data-types)).
+- **Arrays that were fresh in 1.x are still fresh and mutable:** `getProvincesList()`, `getCapitals()`, `searchCities()` and `searchProvinces()` return a new array on every call, which you can sort or change freely, exactly as in 1.x.
+- **Arrays that were shared in 1.x keep the same identity:** `getProvinces()`, `getAllCities()`, `getCities(...)` and `getCitiesByName(...)` return the same array on every call, as in 1.x, so they stay safe to use in React dependency arrays.
+- **React hooks:** same names, same return fields (`province`, `city`, `setProvince`, `setCity`, `provinceId`, `cityId`, `selectedProvince`, `selectedCity`, `reset`, `query`, `setQuery`, `results`). `setQuery` still accepts an updater function.
+
+## Breaking changes
+
+### 1. Returned data is frozen and array types are `readonly`
+
+**What changed.** In 1.x the package handed out its internal arrays and objects. Changing them (for example `getCities('fars').sort(...)`) silently corrupted the data for every other part of your application, including other requests on the same server. In 2.0 all provinces, cities and coordinates are frozen with `Object.freeze`, and the shared arrays are typed as `readonly`.
+
+Affected values:
+
+| Value | 1.x type | 2.0 type |
+|---|---|---|
+| `getProvinces()` | `Province[]` | `readonly Province[]` |
+| `getCities(province)` | `City[]` | `readonly City[]` |
+| `getAllCities()` | `FlatCity[]` | `readonly FlatCity[]` |
+| `getCitiesByName(name)` | `FlatCity[]` | `readonly FlatCity[]` |
+| `Province.cities` | `City[]` | `readonly City[]` |
+| `useCities(province)` | `City[]` | `readonly City[]` |
+| Each `Province`, `City`, `FlatCity`, `Coordinates` object | mutable | frozen, properties typed `readonly` |
+
+Not affected: `getProvincesList()`, `getCapitals()`, `searchCities()`, `searchProvinces()`, `useProvinces()` and the search hooks still return fresh, mutable arrays. The objects returned by `getProvincesList()` and `useProvinces()` are fresh as well and can be modified.
+
+**How it shows up.**
+
+- TypeScript: `error TS4104: The type 'readonly City[]' is 'readonly' and cannot be assigned to the mutable type 'City[]'`, or `Cannot assign to 'fa' because it is a read-only property`.
+- At runtime, in ES modules, TypeScript output and any `'use strict'` code (this includes Next.js, Vite and webpack builds): `TypeError: Cannot assign to read only property ...` or `Cannot add property ..., object is not extensible`.
+- At runtime, in non-strict CommonJS: the change is silently ignored.
+
+**How to fix.**
+
+Change the type annotation if you only read the value:
+
+```ts
+// 1.x
+const cities: City[] = getCities('fars');
+// 2.0
+const cities: readonly City[] = getCities('fars');
+```
+
+Copy the array before sorting or changing it:
+
+```ts
+// 1.x (also changed the shared data for everyone)
+const sorted = getCities('fars').sort((a, b) => a.fa.localeCompare(b.fa, 'fa'));
+// 2.0
+const sorted = [...getCities('fars')].sort((a, b) => a.fa.localeCompare(b.fa, 'fa'));
+```
+
+Copy the objects before changing their fields:
+
+```ts
+// 1.x
+const cities = getCities('fars');
+cities.forEach((c) => { (c as any).label = c.fa; });
+// 2.0
+const cities = getCities('fars').map((c) => ({ ...c, label: c.fa }));
+```
+
+If you pass the value to an API that expects a mutable array, copy it at the call site: `someFn([...getAllCities()])`.
+
+If a third-party library mutates the objects you give it (some table and select components do), pass a deep copy: `structuredClone(getProvinces())` (Node.js 17+ and all current browsers) or `JSON.parse(JSON.stringify(getProvinces()))`.
+
+### 2. `getCity(name)` picks a different city for 7 shared names
+
+**What changed.** 25 city names exist in more than one province. When you look up such a name **without** a province, 1.x returned the one with the lowest id, which was often a small town. 2.0 returns:
+
+1. the provincial capital, if one of them is a capital; otherwise
+2. the city marked as the well-known one in the data; otherwise
+3. the one with the lowest id (same as 1.x).
+
+This affects `getCity(name)` and `getProvinceOfCity(name)` only. Lookups by id, by slug, or with a province (`getCity(name, province)`) are unchanged. `getCitiesByName(name)` is unchanged and still returns every match, ordered by id.
+
+The complete list of lookups whose result changed (Persian and English names behave the same):
+
+| Name | 1.x result | 2.0 result |
+|---|---|---|
+| `سردشت` / `sardasht` | Chaharmahal and Bakhtiari (id 104) | West Azerbaijan (id 1179) |
+| `شهریار` / `shahriar` | East Azerbaijan (id 184) | Tehran (id 1132) |
+| `مهاباد` / `mahabad` | Isfahan (id 270) | West Azerbaijan (id 1171) |
+| `رضوانشهر` / `rezvanshahr` | Isfahan (id 279) | Gilan (id 408) |
+| `حاجی آباد` / `hajjiabad` | Fars (id 312) | Hormozgan (id 512) |
+| `اردکان` / `ardakan` | Fars (id 322) | Yazd (id 1212) |
+| `چناران` / `chenaran` | North Khorasan (id 928) | Razavi Khorasan (id 975) |
+
+**Who is affected.** Only code that calls `getCity()` or `getProvinceOfCity()` with one of these names and **without** a province, and depends on which city comes back, for example code that converts free-text input to an id and stores it.
+
+**How to fix.** In order of preference:
+
+```ts
+// Best: pass the province whenever you have it (result is unambiguous, same in 1.x and 2.0)
+getCity('مهاباد', 'isfahan');
+
+// Or store and look up ids instead of names
+getCityById(270);
+
+// Or detect ambiguous names and let the user choose
+if (isAmbiguousCityName(input)) {
+  const options = getCitiesByName(input);
+}
+
+// Exact 1.x behaviour (lowest id wins)
+const city = getCitiesByName(name)[0] ?? getCity(name);
+```
+
+If you stored ids that were produced by name-only lookups of these 7 names with 1.x, they still point to the same cities as before; nothing changes for stored data. Only new lookups return the other city.
+
+### 3. New required fields on the data types
+
+**What changed.** These fields were added and are always present:
+
+| Type | New fields |
+|---|---|
+| `City` | `nameEn` (English display name, e.g. `'Bandar-e Gaz'`), `aliases` (other spellings and old names) |
+| `FlatCity` | the two above, plus `provinceNameEn` |
+| `Province` | `nameEn`, `neighborIds` |
+| `ProvinceListItem` | `nameEn` |
+
+**Who is affected.** Only TypeScript code that **creates** these objects by hand, typically test fixtures and mocks:
+
+```
+error TS2741: Property 'nameEn' is missing in type '{ ... }' but required in type 'City'.
+```
+
+**How to fix.** Add the fields:
+
+```ts
+const mockCity: City = { id: 1, isCapital: true, slug: 'alborz/karaj', en: 'karaj', fa: 'کرج', nameEn: 'Karaj', aliases: [] };
+```
+
+Or build fixtures from real data, which always stays in sync with the types: `const mockCity = getCityById(1)!;`
+
+### 4. 25 Persian names now use Persian letters
+
+**What changed.** In 1.x, 25 city names were written with the Arabic letters «ي» and «ك» instead of the Persian «ی» and «ک», for example `كدكن` and `اسفرورين`. They looked wrong in lists and sorted in the wrong place. In 2.0 they use Persian letters: `کدکن`, `اسفرورین`. Ids, English ids and slugs did not change.
+
+**Who is affected.** Only code that compares `city.fa` **as a plain string** with a value saved from 1.x, for example a database column of Persian names. Lookups are not affected: `getCity('كدكن')` still finds the city, because every lookup normalizes both letters.
+
+**How to fix.** Compare ids instead of names, or compare normalized text:
+
+```ts
+import { normalize, getDataChanges } from '@code-plate/iran-cities';
+
+normalize(savedName) === normalize(city.fa);
+
+for (const change of getDataChanges('1.2.0')) {
+  if (change.type === 'spelling') {
+    await db.query('UPDATE addresses SET city_fa = $1 WHERE city_id = $2', [change.after?.fa, change.cityId]);
+  }
+}
+```
+
+`getDataChanges('1.2.0')` lists all 25 changes with the old and new spelling.
+
+## Behaviour changes that are not breaking
+
+These changes can alter search results, mostly by finding a city where 1.x found nothing, by reordering equally ranked results, or by dropping weak fuzzy matches.
+
+| Area | 1.x | 2.0 |
+|---|---|---|
+| Normalization | `ي→ی`, `ك→ک`, ignores spaces, ZWNJ and `-` | Also `ى/ئ→ی`, `آ/أ/إ/ٱ→ا`, `ة/ۀ→ه`, `ؤ→و`; ignores diacritics, tatweel `ـ`, `_` and apostrophes; reads Persian and Arabic digits. `getCity('ابادان')` and `getProvince('۲۸')` now work. |
+| Aliases | Not supported | `getCity('طهران')`, `getCity('esfahan')`, `getCity('mashad')`, `getCity('orumiyeh')`, `getCity('teheran')`, `getCity('urumieh')` now return a city instead of `undefined`. |
+| Area codes | `'021'`, `'21'`, `21` | Also `'۰۲۱'`, `'+9821'`, `'+98 21'` and `'0098 21'`. |
+| Search ranking | Equal scores kept data order | Equal scores: provincial capitals first, then Persian alphabetical order. Because of the wider normalization and the new aliases, a query can also match a few more cities than before. |
+| Fuzzy search (`fuzzy: true`) | Allowed 2 typos for any query, so short queries matched unrelated names (`تهرن` also returned `اهر`, `بهمن`) | Allowed typos are capped at a third of the query length (`تهرن` returns only `تهران`), and typos at the start of longer names are matched too. |
+| Wrong keyboard layout | `searchCities('jivhk')` returned nothing | Returns `تهران`: when nothing matches, the query is retried as if typed on the other layout. Turn off with `{ keyboardFix: false }`. |
+| Invalid input | `getCity(undefined)`, `searchCities(null)` and similar threw `TypeError` | Return `undefined`, an empty array or all items, as for an empty string. |
+| `limit` option | A negative `limit` dropped items from the end | A negative or zero `limit` means no limit. |
+| `useProvinceCitySelect` | Kept the selected English names in state | Keeps ids in state. Returned values are the same. A city that does not belong to the selected province is now ignored. |
+| `@code-plate/iran-cities/react` | Contained its own copy of all data (about 238 KB unminified) | Reuses the main entry. Apps that import both no longer ship the data twice, and both share one instance. |
+| `react` and `lite/react` | No directive | Start with `"use client"`, so Next.js App Router treats them as client modules. |
+
+## New features you can adopt
+
+- `@code-plate/iran-cities/lite` and `@code-plate/iran-cities/lite/react`: the same API without coordinates, about a third smaller. Ideal for province/city pickers.
+- Accessible components with a plain-CSS theme: `CityCombobox` and `ProvinceCitySelect` from `@code-plate/iran-cities/lite/react/components`, styled by `@code-plate/iran-cities/components.css`.
+- Validation schemas for Zod (`/zod`) and Valibot (`/valibot`), including a check that the city belongs to the province.
+- Neighboring provinces: `getNeighborProvinces(query)`, `areNeighborProvinces(a, b)` and `Province.neighborIds`.
+- Province boundaries as GeoJSON and `getProvinceAt({ lat, lng })` from `@code-plate/iran-cities/boundaries`.
+- English display names: `nameEn` on provinces and cities, `provinceNameEn` on flat cities.
+- `convertKeyboardLayout(text, 'fa' | 'en')`, `DATA_VERSION`, `DATA_CHANGES` and `getDataChanges(sinceVersion)`.
+- CSV, SQL, JSON and GeoJSON copies of the data in `@code-plate/iran-cities/data/*`.
+- `getDistance(from, to)` and `getNearestCities(point, { limit, minConfidence, maxDistanceKm })`.
+- `isAmbiguousCityName(name)` and `normalize(text)`.
+- `searchCities(query, { emptyQuery: 'none' })` returns `[]` for an empty query instead of all 1252 cities.
+- `useProvinceCitySelect({ initialProvince, initialCity })` for edit forms, and `useProvinceCitySelect({ value, onChange })` for controlled use with react-hook-form, Formik and similar libraries.
+- New exported types: `IranCities`, `IranCitiesGeo`, `IranCitiesHooks`, `LatLng`, `CoordinateConfidence`, `NearestCity`, `NearestCitiesOptions`, `Stats`, `ProvinceCityValue`, `ProvinceCitySelectOptions`, `ProvinceCitySelect`, `SearchState`, `CityComboboxProps`, `ProvinceCitySelectProps`, `DataChange`, `DataChangeType`, `KeyboardTarget`.
+
+## Next.js
+
+Nothing has to change in a Next.js project. Recommended improvements:
+
+```tsx
+// app/page.tsx (Server Component): use the core entry directly
+import { getCity, getProvincesList } from '@code-plate/iran-cities';
+
+// app/address-form.tsx (Client Component): use the lite hooks
+'use client';
+import { useProvinceCitySelect } from '@code-plate/iran-cities/lite/react';
+```
+
+- The hook entries already contain `"use client"`. You still need `'use client'` in your own component file that calls the hooks, as with any hook.
+- Use `lite/react` in client components unless the browser needs coordinates. This keeps about 8 KB (brotli) out of the client bundle.
+- Data returned on the server can be passed to Client Components as props; frozen objects serialize normally.
+- Verified with Next.js 14 (webpack, React 18), Next.js 15 (webpack) and Next.js 16 (Turbopack and webpack, React 19), App Router, static rendering and `next start`.
+
+## Finding affected code
+
+```bash
+# Values that may be mutated (check each hit)
+grep -rnE "get(Provinces|AllCities|Cities|CitiesByName)\([^)]*\)\.(sort|push|pop|shift|unshift|splice|reverse|fill|copyWithin)\(" src
+
+# Name-only lookups of the 7 changed names
+grep -rnE "get(City|ProvinceOfCity)\(['\"](سردشت|sardasht|شهریار|shahriar|مهاباد|mahabad|رضوانشهر|rezvanshahr|حاجی ?آباد|hajjiabad|اردکان|ardakan|چناران|chenaran)['\"]\)" src
+
+# Hand-written City objects
+grep -rnE ":\s*(Flat)?City\s*=\s*\{" src
+```
+
+Running your test suite in strict mode (any ESM or TypeScript test runner) turns accidental mutations into `TypeError`s, which makes them easy to find.
+
+## FAQ
+
+**Can I keep using 1.x?** Yes. 1.x keeps working, but it will not get data fixes or new features.
+
+**Why freeze the data instead of returning copies everywhere?** The functions that return shared arrays did so in 1.x too, and many apps rely on their identity being stable (for example in `useMemo` or `useEffect` dependencies). Copying on every call would have changed that and caused extra renders. Freezing keeps identity and makes accidental mutation visible instead of silently corrupting data. Functions that returned fresh arrays in 1.x still do.
+
+**Did ids or slugs change?** No. Stored ids and slugs from 1.x stay valid.
+
+**Does 2.0 need a newer Node.js, React or TypeScript?** No. The minimums are the same as in 1.x: Node.js 14, React 16.8, and TypeScript 3.9 for the type declarations.