@code-plate/iran-cities 1.2.0 → 2.0.0

package/README.fa.md

@@ -1,295 +1,622 @@
-[English](./README.md) | فارسی
+<div align="center" dir="rtl">
 
-# @code-plate/iran-cities
+[English](./README.md) · فارسی
 
-لیست کامل و آماده‌ی **استان‌ها و شهرهای ایران** (فارسی + انگلیسی)، بسته‌بندی‌شده به شکل یک کتابخانه‌ی سبک، بدون هیچ وابستگی اجباری، که در **هر پروژه‌ی جاوااسکریپتی/تایپ‌اسکریپتی** قابل استفاده است:
+# 🇮🇷 شهرهای ایران
 
-- ✅ React / Next.js (App Router و Pages Router)
-- ✅ Vue 2 / Vue 3
-- ✅ Angular
-- ✅ Svelte
-- ✅ Node.js / Express (بک‌اند خالص)
-- ✅ Vanilla JS (مرورگر یا هر باندلر دیگر)
+**همه‌ی استان‌ها و شهرهای ایران، به فارسی و انگلیسی، با جستجوی سریع و هوشمند، مختصات، مرز استان‌ها و کامپوننت‌های آماده.**
 
-هسته‌ی اصلی پکیج **هیچ وابستگی‌ای** ندارد (zero-dependency) و هم به‌صورت **CJS** و هم **ESM** ارائه می‌شود. یک ساب‌پس اختیاری (`@code-plate/iran-cities/react`) هم برای کسانی که در React کار می‌کنند وجود دارد که چند هوک آماده می‌دهد؛ اگر پروژه‌تان React نیست، هرگز این فایل import نمی‌شود و React اصلاً لازم نیست نصب شود.
+بدون وابستگی · tree-shakeable · تایپ کامل · ساخته‌شده برای Next.js
+
+[![npm version](https://img.shields.io/npm/v/@code-plate/iran-cities?color=0a7f5a&label=npm)](https://www.npmjs.com/package/@code-plate/iran-cities)
+[![npm downloads](https://img.shields.io/npm/dm/@code-plate/iran-cities?color=0a7f5a)](https://www.npmjs.com/package/@code-plate/iran-cities)
+[![CI](https://github.com/MJavadSF/Iran-Cities/actions/workflows/ci.yml/badge.svg)](https://github.com/MJavadSF/Iran-Cities/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/MJavadSF/Iran-Cities/badge)](https://scorecard.dev/viewer/?uri=github.com/MJavadSF/Iran-Cities)
+[![types](https://img.shields.io/badge/types-included-3178c6)](#typescript)
+
+**[مستندات](https://mjavadsf.github.io/Iran-Cities/fa/)** · **[زمین بازی زنده](https://mjavadsf.github.io/Iran-Cities/fa/playground/)** · **[نقشه](https://mjavadsf.github.io/Iran-Cities/fa/guides/geography/)**
+
+</div>
+
+<div dir="rtl">
+
+```ts
+import { getCity, searchCities, getNeighborProvinces } from '@code-plate/iran-cities';
+
+getCity('شيراز');              // { id: 292, fa: 'شیراز', nameEn: 'Shiraz', provinceFa: 'فارس', phoneCode: '071', ... }
+searchCities('jivhk');          // [تهران]  با کیبورد انگلیسی تایپ شده
+getNeighborProvinces('قم');     // [اصفهان، مرکزی، سمنان، تهران]
+```
+
+<table dir="rtl">
+<tr>
+<td width="33%" valign="top">
+
+### 📍 کامل
+**۳۱** استان و **۱۲۵۲** شهر با id ثابت، نام فارسی و انگلیسی، کد تلفن، مرکز استان، استان‌های همسایه و مختصات **۱۱۵۲** شهر که همگی با مرز استان‌ها بررسی شده‌اند.
+
+</td>
+<td width="33%" valign="top">
+
+### 🔎 فارسی‌فهم
+«ي/ی»، «ك/ک»، «آ/ا»، نیم‌فاصله، اعراب و ارقام فارسی را می‌شناسد، غلط تایپی را تحمل می‌کند و متنی را که با کیبورد اشتباه تایپ شده خودش درست می‌کند.
+
+</td>
+<td width="33%" valign="top">
+
+### ⚡ آماده‌ی production
+کامپوننت‌های دسترس‌پذیر با CSS خام، اسکیمای Zod و Valibot، هوک‌های `"use client"`، نسخه‌ی `lite`، داده‌ی freeze شده و تایپ‌هایی از TypeScript 3.9 تا 7.
+
+</td>
+</tr>
+</table>
+
+> [!TIP]
+> از نسخه‌ی 1.x ارتقا می‌دهید؟ بیشتر پروژه‌ها به هیچ تغییری نیاز ندارند. [راهنمای مهاجرت](./MIGRATION.fa.md) را ببینید.
+
+## فهرست
+
+- [نصب](#نصب)
+- [ورودی‌ها](#ورودیها)
+- [شروع سریع](#شروع-سریع)
+- [Next.js](#nextjs)
+- [کامپوننت‌ها](#کامپوننتها)
+- [اعتبارسنجی فرم](#اعتبارسنجی-فرم)
+- [هوک‌های React](#هوکهای-react)
+- [نقشه و جغرافیا](#نقشه-و-جغرافیا)
+- [Vue، Svelte، Angular و Express](#vue-svelte-angular-و-express)
+- [زبان‌های دیگر: CSV، SQL، JSON](#زبانهای-دیگر-csv-sql-json)
+- [مرجع API](#مرجع-api)
+- [تطبیق متن چطور کار می‌کند](#تطبیق-متن-چطور-کار-میکند)
+- [داده‌ها و منابع](#دادهها-و-منابع)
+- [سازگاری](#سازگاری)
+- [مشارکت](#مشارکت)
+- [مجوز و منابع](#مجوز-و-منابع)
 
 ## نصب
 
 ```bash
 npm install @code-plate/iran-cities
-# یا
-yarn add @code-plate/iran-cities
-# یا
+```
+
+<details>
+<summary>pnpm، yarn، bun، Deno</summary>
+
+```bash
 pnpm add @code-plate/iran-cities
+yarn add @code-plate/iran-cities
+bun add @code-plate/iran-cities
+deno add npm:@code-plate/iran-cities
 ```
 
-## داده‌ها
+</details>
 
-- `۳۱` استان
-- `۱۲۵۲` شهر
-- هر رکورد شامل `id` (شناسه‌ی عددی یکتا و پایدار)، `en` (شناسه لاتین kebab-case، مثل `tehran`) و `fa` (نام فارسی، مثل `تهران`) است.
-- هر استان `phoneCode` (کد تلفن بین‌شهری) و `capitalId` (id مرکز استان) دارد؛ هر شهر `isCapital` دارد و مراکز استان‌ها `coordinates: { lat, lng }` هم دارند.
-- `id` شهرها در **کل کشور یکتاست** (شهرهای هم‌نام مثل «مهاباد» در دو استان، دو id متفاوت دارند) و بین نسخه‌ها تغییر نمی‌کند؛ شهر جدید همیشه id بعدی را می‌گیرد.
+## ورودی‌ها
 
----
+کوچک‌ترین ورودی‌ای را انتخاب کنید که نیازتان را پوشش می‌دهد. حجم‌ها بعد از minify و فشرده‌سازی brotli و همراه با داده‌ها هستند.
 
-## استفاده در جاوااسکریپت / تایپ‌اسکریپت خالص (و Node.js/Express)
+| import | محتوا | حجم |
+|---|---|---:|
+| `@code-plate/iran-cities` | همه‌ی توابع، از جمله مختصات و فاصله | ۲۴ کیلوبایت |
+| `@code-plate/iran-cities/lite` | همان جستجو و lookup، بدون مختصات | ۱۶ کیلوبایت |
+| `@code-plate/iran-cities/react` | هوک‌های React | ۲۵ کیلوبایت |
+| `@code-plate/iran-cities/lite/react` | هوک‌های React بدون مختصات | ۱۷ کیلوبایت |
+| `@code-plate/iran-cities/lite/react/components` | `CityCombobox` و `ProvinceCitySelect` | ۱۸ کیلوبایت |
+| `@code-plate/iran-cities/react/components` | همان کامپوننت‌ها همراه با مختصات | ۲۶ کیلوبایت |
+| `@code-plate/iran-cities/components.css` | استایل کامپوننت‌ها | ۱٫۵ کیلوبایت |
+| `@code-plate/iran-cities/zod` · `/valibot` | اسکیمای اعتبارسنجی | ۱۶ کیلوبایت |
+| `@code-plate/iran-cities/boundaries` | مرز استان‌ها (GeoJSON) و `getProvinceAt` | ۵۳ کیلوبایت |
+| `@code-plate/iran-cities/data/*` | فایل‌های CSV، SQL، JSON و GeoJSON | |
+
+ورودی‌ها کد مشترک دارند، پس import کردن چند ورودی هیچ‌وقت داده را دو بار ship نمی‌کند. React، Zod و Valibot وابستگی peer اختیاری هستند.
+
+## شروع سریع
+
+### پیدا کردن
 
 ```ts
-import {
-  getProvinces,
-  getProvincesList,
-  getProvince,
-  getCities,
-  getCity,
-  getCityById,
-  getProvinceById,
-  getCitiesByName,
-  getAllCities,
-  getProvinceOfCity,
-  searchProvinces,
-  searchCities,
-  getStats,
-} from '@code-plate/iran-cities';
-
-// همه‌ی استان‌ها به همراه شهرهایشان
-getProvinces();
-// [{ id: 1, en: 'alborz', fa: 'البرز', cities: [{ id: 1, en: 'karaj', fa: 'کرج', slug: 'alborz/karaj' }, ...] }, ...]
-
-// فقط لیست استان‌ها (بدون شهر) - برای Select/Dropdown
-getProvincesList();
-// [{ id: 1, en: 'alborz', fa: 'البرز' }, { id: 2, en: 'ardabil', fa: 'اردبیل' }, ...]
-
-// گرفتن یک استان با نام انگلیسی یا فارسی
-getProvince('tehran');
-getProvince('تهران'); // همین نتیجه را می‌دهد
-getProvince(28);      // با id عددی هم کار می‌کند (رشته‌ی عددی '28' هم قبول است)
-
-// شهرهای یک استان خاص
-getCities('fars');       // بر اساس شناسه انگلیسی
-getCities('فارس');       // یا بر اساس نام فارسی، هر دو یکسان کار می‌کنند
-
-// پیدا کردن یک شهر مشخص (در کل کشور یا محدود به یک استان)
-getCity('shiraz');
-getCity('شیراز', 'fars'); // محدود به استان فارس
-
-// لیست مسطح (flat) همه‌ی شهرهای کشور همراه با استان مربوطه
-getAllCities();
-// [{ id: 1, en: 'karaj', fa: 'کرج', slug: 'alborz/karaj', provinceId: 1, provinceEn: 'alborz', provinceFa: 'البرز' }, ...]
-
-// گرفتن شهر/استان با id
-getCityById(292);     // => شیراز (provinceId: 7)
-getProvinceById(7);   // => فارس
-
-// نام‌های تکراری: همه‌ی شهرهای با این نام
-getCitiesByName('مهاباد'); // => [اصفهان/مهاباد (id 270), آذربایجان غربی/مهاباد (id 1171)]
-
-// پیدا کردن استانِ یک شهر
-getProvinceOfCity('اصفهان'); // => { id: 6, en: 'isfahan', fa: 'اصفهان', cities: [...] }
-getProvinceOfCity(292);      // با id شهر هم کار می‌کند
-
-// جستجوی زنده (autocomplete) در استان‌ها یا شهرها
-searchProvinces('خراسان');            // هر سه استان خراسان را برمی‌گرداند
-searchCities('شهر', { limit: 10 });   // ۱۰ نتیجه‌ی اول شامل «شهر»
-searchCities('mashhad', { locale: 'en' }); // جستجو فقط در نام انگلیسی
-
-// مرکز استان، کد تلفن و مختصات
-getCapital('khuzestan');        // => { id: 674, en: 'ahvaz', isCapital: true, coordinates: { lat: 31.31901, lng: 48.6842 }, phoneCode: '061', ... }
-getCapitals();                  // ۳۱ مرکز استان
-getProvinceByPhoneCode('021');  // => تهران ('21' و 21 هم قبول است)
-getCity('نجف‌آباد').phoneCode;  // => '031' (کد استانِ شهر)
-getCity('اهواز').coordinates;   // => { lat, lng, confidence } | برای شهرهای غیرمرکز استان: undefined
-
-// آمار کلی
-getStats(); // { provinceCount: 31, cityCount: 1252 }
-```
+import { getProvince, getCities, getCity, getCityById, getProvinceOfCity } from '@code-plate/iran-cities';
 
-### نکته‌ی مهم درباره‌ی جستجو
-تابع‌های `getProvince`, `getCities`, `getCity` و `getProvinceOfCity` به‌صورت **نرمال‌شده** مقایسه می‌کنند؛ یعنی تفاوت «ی» فارسی/«ي» عربی، «ک»/«ك»، نیم‌فاصله، فاصله و خط‌تیره را نادیده می‌گیرند. پس `getCity('كرج')` و `getCity('کرج')` هر دو کار می‌کنند.
+getProvince('tehran');          // با شناسه‌ی انگلیسی
+getProvince('تهران');           // با نام فارسی
+getProvince(28);                // با id (رشته‌ی '28' و '۲۸' هم کار می‌کند)
 
----
+getCities('fars');              // همه‌ی شهرهای فارس
+getCity('شیراز');               // یک شهر در کل ایران
+getCity('شیراز', 'fars');       // یک شهر داخل یک استان
+getCityById(292);               // با id سراسری
+getProvinceOfCity('اصفهان');    // استانی که شهر در آن است
+```
 
-## استفاده در Node.js / Express (بک‌اند)
+### جستجو و autocomplete
 
-```js
-const express = require('express');
-const { getProvincesList, getCities, searchCities } = require('@code-plate/iran-cities');
+```ts
+import { searchCities, searchProvinces } from '@code-plate/iran-cities';
 
-const app = express();
+searchProvinces('خراسان');                   // [خراسان جنوبی، خراسان رضوی، خراسان شمالی]
+searchCities('شهر', { limit: 10 });          // ۱۰ نتیجه‌ی اول
+searchCities('تهرن', { fuzzy: true });       // تحمل غلط تایپی: [تهران]
+searchCities('jivhk');                       // کیبورد اشتباه: [تهران]
+searchCities('', { emptyQuery: 'none' });    // [] به‌جای هر ۱۲۵۲ شهر
+```
 
-app.get('/api/provinces', (req, res) => {
-  res.json(getProvincesList());
-});
+### همسایه‌ها، مرکز استان و کد تلفن
 
-app.get('/api/cities/:province', (req, res) => {
-  res.json(getCities(req.params.province));
-});
+```ts
+import { getNeighborProvinces, areNeighborProvinces, getCapital, getProvinceByPhoneCode } from '@code-plate/iran-cities';
 
-app.get('/api/cities/search', (req, res) => {
-  res.json(searchCities(req.query.q ?? '', { limit: 20 }));
-});
+getNeighborProvinces('قم');                     // [اصفهان، مرکزی، سمنان، تهران]
+areNeighborProvinces('yazd', 'south-khorasan'); // true
+getCapital('khuzestan');                        // اهواز
+getProvinceByPhoneCode('021');                  // تهران ('21'، 21، '۰۲۱' و '+98 21' هم قبول است)
 ```
 
----
+### نام نمایشی انگلیسی
+
+```ts
+getProvince(16)?.nameEn;          // 'Kohgiluyeh and Boyer-Ahmad'  (شناسه‌ی en برابر 'kohgiluyeh-and-boyer-ahmad' است)
+getCity('bandar-e-gaz')?.nameEn;  // 'Bandar-e Gaz'
+```
 
-## استفاده در React / Next.js
+## Next.js
 
-برای React یک ساب‌پس اختیاری وجود دارد که چند هوک آماده ارائه می‌دهد:
+در **Server Componentها** از ورودی اصلی و در **Client Componentها** از هوک‌ها یا کامپوننت‌ها استفاده کنید. همه‌ی ورودی‌های React خودشان `"use client"` دارند.
 
 ```tsx
-import { useProvinces, useCities, useProvinceCitySelect, useCitySearch } from '@code-plate/iran-cities/react';
+// app/address/page.tsx (Server Component)
+import { getCity } from '@code-plate/iran-cities';
+import AddressForm from './address-form';
+import { save } from './actions';
+
+export default function Page() {
+  const city = getCity('شیراز', 'fars');
+  return <AddressForm action={save} defaultCityId={city?.id} />;
+}
+```
 
-function AddressForm() {
-  const { provinces, cities, province, setProvince, city, setCity, provinceId, cityId, selectedCity } =
-    useProvinceCitySelect();
+```tsx
+// app/address/address-form.tsx (Client Component)
+'use client';
 
-  // موقع ارسال فرم: { provinceId, cityId } را به بک‌اند بفرستید
-  // selectedCity => { id, en, fa, slug, provinceId, provinceEn, provinceFa }
+import '@code-plate/iran-cities/components.css';
+import { ProvinceCitySelect } from '@code-plate/iran-cities/lite/react/components';
 
+export default function AddressForm({ action, defaultCityId }: { action: (data: FormData) => void; defaultCityId?: number }) {
   return (
-    <>
-      <select value={province} onChange={(e) => setProvince(e.target.value)}>
-        <option value="">انتخاب استان</option>
-        {provinces.map((p) => (
-          <option key={p.id} value={p.en}>{p.fa}</option>
-        ))}
-      </select>
-
-      <select value={city} onChange={(e) => setCity(e.target.value)} disabled={!province}>
-        <option value="">انتخاب شهر</option>
-        {cities.map((c) => (
-          <option key={c.id} value={c.en}>{c.fa}</option>
-        ))}
-      </select>
-    </>
+    <form action={action}>
+      <ProvinceCitySelect provinceName="provinceId" cityName="cityId" defaultValue={{ cityId: defaultCityId }} required />
+      <button type="submit">ثبت</button>
+    </form>
   );
 }
 ```
 
-جستجوی زنده‌ی شهر (autocomplete):
+```ts
+// app/address/actions.ts
+'use server';
+
+import { provinceCitySchema } from '@code-plate/iran-cities/zod';
+
+export async function save(formData: FormData) {
+  const result = provinceCitySchema.safeParse({ provinceId: formData.get('provinceId'), cityId: formData.get('cityId') });
+  if (!result.success) return;
+}
+```
+
+> [!TIP]
+> در Client Componentها از ورودی‌های `lite` استفاده کنید، مگر اینکه مرورگر واقعاً مختصات لازم داشته باشد. این کار حدود ۸ کیلوبایت از bundle کلاینت کم می‌کند.
+
+با Next.js 14، 15 و 16 و با Turbopack و webpack تست شده است.
+
+## کامپوننت‌ها
+
+دو کامپوننت دسترس‌پذیر که با یک فایل کوچک CSS خام استایل شده‌اند (بدون Tailwind و بدون CSS-in-JS). [نسخه‌ی زنده را ببینید](https://mjavadsf.github.io/Iran-Cities/fa/guides/components/).
 
 ```tsx
-import { useCitySearch } from '@code-plate/iran-cities/react';
+'use client';
 
-function CityAutocomplete() {
-  const { query, setQuery, results } = useCitySearch('', { limit: 8 });
+import '@code-plate/iran-cities/components.css';
+import { CityCombobox, ProvinceCitySelect } from '@code-plate/iran-cities/lite/react/components';
 
-  return (
-    <div>
-      <input value={query} onChange={(e) => setQuery(e.target.value)} placeholder="نام شهر..." />
-      <ul>
-        {results.map((c) => (
-          <li key={c.id}>{c.fa} ({c.provinceFa})</li>
-        ))}
-      </ul>
-    </div>
-  );
+<ProvinceCitySelect provinceName="provinceId" cityName="cityId" onChange={({ provinceId, cityId }) => {}} />
+<CityCombobox label="شهر مقصد" name="destinationId" province="fars" onChange={(city) => {}} />
+```
+
+- **`CityCombobox`** از [الگوی combobox در WAI-ARIA](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) پیروی می‌کند: `↑` و `↓`، `Home` و `End`، `Enter` برای انتخاب، `Escape` برای بستن و `Escape` دوم برای پاک کردن. غلط تایپی را تحمل می‌کند و کیبورد اشتباه را درست می‌کند.
+- **`ProvinceCitySelect`** دو `<select>` بومی با label است و با تغییر استان، شهر خالی می‌شود.
+- هر دو **id** را از طریق فیلدهای معمولی فرم (`name`) ارسال می‌کنند، پس با فرم معمولی و Server Action کار می‌کنند. هر دو هم controlled (`value` و `onChange`) و هم uncontrolled (`defaultValue`) کار می‌کنند و بدون تغییر داخل `Controller` در react-hook-form قرار می‌گیرند.
+- پیش‌فرض راست‌به‌چپ (`dir="rtl"`)، نام انگلیسی با `locale="en"`، و حالت تاریک خودکار.
+
+تم را با متغیرهای CSS روی هر والدی تغییر دهید. همه‌ی selectorها با `:where()` نوشته شده‌اند، پس کلاس‌های خودتان بدون `!important` اولویت دارند:
+
+```css
+.checkout {
+  --ic-accent: #2563eb;
+  --ic-radius: 0.375rem;
+  --ic-height: 2.5rem;
+  --ic-font: 'Vazirmatn', sans-serif;
 }
 ```
 
-هوک‌های در دسترس در ساب‌پس `react`:
+<details>
+<summary>همه‌ی متغیرهای CSS</summary>
 
-| هوک | کاربرد |
+| متغیر | |
 |---|---|
-| `useProvinces()` | لیست استان‌ها |
-| `useCities(provinceQuery)` | شهرهای یک استان، وابسته به تغییر پارامتر |
-| `useProvinceCitySelect()` | state کامل یک فرم استان→شهر (با ریست خودکار شهر هنگام تغییر استان)؛ علاوه بر `province`/`city` مقدارهای `provinceId`, `cityId`, `selectedProvince`, `selectedCity` و `reset()` را هم برمی‌گرداند |
-| `useCitySearch(initialQuery?, options?)` | state جستجوی زنده‌ی شهر |
-| `useProvinceSearch(initialQuery?, options?)` | state جستجوی زنده‌ی استان |
+| `--ic-font`، `--ic-font-size`، `--ic-line-height` | تایپوگرافی |
+| `--ic-height`، `--ic-radius`، `--ic-gap`، `--ic-padding-inline` | اندازه و فاصله |
+| `--ic-bg`، `--ic-fg`، `--ic-muted`، `--ic-border`، `--ic-border-hover` | رنگ‌ها |
+| `--ic-accent`، `--ic-accent-soft`، `--ic-ring` | رنگ اصلی و حلقه‌ی focus |
+| `--ic-danger`، `--ic-danger-ring` | حالت نامعتبر |
+| `--ic-popover-bg`، `--ic-shadow`، `--ic-listbox-max-height` | فهرست پیشنهادها |
+| `--ic-disabled-bg`، `--ic-transition` | سایر |
+
+حالت تاریک از `prefers-color-scheme` پیروی می‌کند؛ برای اجبار، `data-theme="dark"` یا `"light"` را روی یک والد بگذارید.
+
+</details>
+
+## اعتبارسنجی فرم
+
+```ts
+import { provinceCitySchema, cityIdSchema, citySchema } from '@code-plate/iran-cities/zod';
+
+provinceCitySchema.parse({ provinceId: '7', cityId: '292' });   // { provinceId: 7, cityId: 292 }
+provinceCitySchema.safeParse({ provinceId: 28, cityId: 292 });   // خطا روی cityId: «این شهر در استان انتخاب‌شده نیست.»
+cityIdSchema.parse('۲۹۲');                                       // 292
+citySchema.parse('شیراز');                                        // شیء کامل شهر
+```
+
+همین اسکیماها برای Valibot در `@code-plate/iran-cities/valibot` هم هست. پیام‌ها به‌طور پیش‌فرض فارسی‌اند؛ با `createZodSchemas({ ... })` یا `createValibotSchemas({ ... })` پیام خودتان را بدهید.
+
+## هوک‌های React
+
+از `@code-plate/iran-cities/react` یا بدون مختصات از `@code-plate/iran-cities/lite/react` import کنید.
+
+| هوک | خروجی |
+|---|---|
+| `useProvinces()` | فهرست استان‌ها |
+| `useCities(province)` | شهرهای یک استان |
+| `useProvinceCitySelect(options?)` | همه‌ی چیزهایی که یک فیلد استان ← شهر لازم دارد؛ گزینه‌ها: `initialProvince`، `initialCity`، `value`، `onChange` |
+| `useCitySearch(initialQuery?, options?)` | `{ query, setQuery, results }` |
+| `useProvinceSearch(initialQuery?, options?)` | `{ query, setQuery, results }` |
+
+```tsx
+const { provinces, cities, province, city, setProvince, setCity, provinceId, cityId } = useProvinceCitySelect({ initialCity: 292 });
+const [value, setValue] = useState<ProvinceCityValue>({ provinceId: 7, cityId: 292 });
+useProvinceCitySelect({ value, onChange: setValue });   // controlled
+```
+
+## نقشه و جغرافیا
+
+```ts
+import { getDistance, getNearestCities } from '@code-plate/iran-cities';
+import { getProvinceAt, provinceBoundaries } from '@code-plate/iran-cities/boundaries';
+
+getDistance('tehran', 'karaj');                              // 36.5 (کیلومتر)
+getNearestCities({ lat: 29.6, lng: 52.5 }, { limit: 1 });    // [{ city: شیراز, distanceKm: 5.6 }]
+getProvinceAt({ lat: 34.64, lng: 50.88 });                   // قم
+getProvinceAt({ lat: 48.85, lng: 2.35 });                    // undefined (خارج از ایران)
+```
+
+`provinceBoundaries` یک `FeatureCollection` استاندارد GeoJSON است که مستقیم با Leaflet، MapLibre و deck.gl کار می‌کند. هر شهری که مختصات دارد به استان خودش برمی‌گردد. [نقشه را امتحان کنید](https://mjavadsf.github.io/Iran-Cities/fa/guides/geography/).
 
-> اگر پروژه‌تان Vue، Angular یا هر چیز دیگری است، فقط از مسیر اصلی (`@code-plate/iran-cities`) استفاده کنید و توابع خام (`getProvinces`, `getCities`, ...) را داخل computed/signal/observable خودتان قرار دهید — نیازی به هیچ ابزار اضافه‌ای نیست.
+## Vue، Svelte، Angular و Express
 
----
+توابع اصلی توابع ساده و همگام هستند و در هر فریم‌ورکی کار می‌کنند.
 
-## استفاده در Vue 3 (نمونه)
+<details>
+<summary><b>Vue 3</b></summary>
 
 ```vue
 <script setup>
 import { ref, computed } from 'vue';
-import { getProvincesList, getCities } from '@code-plate/iran-cities';
+import { getProvincesList, getCities } from '@code-plate/iran-cities/lite';
 
 const provinces = getProvincesList();
-const selectedProvince = ref('');
-const cities = computed(() => getCities(selectedProvince.value));
+const province = ref('');
+const cities = computed(() => getCities(province.value));
 </script>
 
 <template>
-  <select v-model="selectedProvince">
-    <option v-for="p in provinces" :key="p.en" :value="p.en">{{ p.fa }}</option>
+  <select v-model="province">
+    <option v-for="p in provinces" :key="p.id" :value="p.en">{{ p.fa }}</option>
   </select>
-  <select :disabled="!selectedProvince">
-    <option v-for="c in cities" :key="c.en" :value="c.en">{{ c.fa }}</option>
+  <select :disabled="!province">
+    <option v-for="c in cities" :key="c.id" :value="c.en">{{ c.fa }}</option>
   </select>
 </template>
 ```
 
-## استفاده در Angular (نمونه سرویس)
+</details>
+
+<details>
+<summary><b>Svelte</b></summary>
+
+```svelte
+<script>
+  import { getProvincesList, getCities } from '@code-plate/iran-cities/lite';
+
+  const provinces = getProvincesList();
+  let province = '';
+  $: cities = getCities(province);
+</script>
+
+<select bind:value={province}>
+  {#each provinces as p (p.id)}<option value={p.en}>{p.fa}</option>{/each}
+</select>
+<select disabled={!province}>
+  {#each cities as c (c.id)}<option value={c.en}>{c.fa}</option>{/each}
+</select>
+```
+
+</details>
+
+<details>
+<summary><b>Angular</b></summary>
 
 ```ts
 import { Injectable } from '@angular/core';
-import { getProvincesList, getCities, type City } from '@code-plate/iran-cities';
+import { getProvincesList, getCities, type City, type ProvinceListItem } from '@code-plate/iran-cities/lite';
 
 @Injectable({ providedIn: 'root' })
 export class IranLocationsService {
-  getProvinces() {
+  provinces(): ProvinceListItem[] {
     return getProvincesList();
   }
-  getCitiesOf(provinceEn: string): City[] {
-    return getCities(provinceEn);
+
+  citiesOf(province: string): readonly City[] {
+    return getCities(province);
   }
 }
 ```
 
----
+</details>
+
+<details>
+<summary><b>Node.js / Express</b></summary>
+
+```js
+const express = require('express');
+const { getProvincesList, getCities, searchCities } = require('@code-plate/iran-cities');
+
+const app = express();
+
+app.get('/api/provinces', (req, res) => res.json(getProvincesList()));
+app.get('/api/cities/search', (req, res) => res.json(searchCities(String(req.query.q ?? ''), { limit: 20 })));
+app.get('/api/cities/:province', (req, res) => res.json(getCities(req.params.province)));
+```
+
+مسیر جستجو قبل از `/:province` تعریف شده؛ وگرنه Express کلمه‌ی `search` را نام استان حساب می‌کند.
+
+</details>
+
+## زبان‌های دیگر: CSV، SQL، JSON
+
+پکیج همین داده‌ها را به‌صورت فایل معمولی هم دارد، برای Laravel، Django، Go یا هر دیتابیسی:
+
+| فایل | |
+|---|---|
+| `data/provinces.csv`، `data/cities.csv` | CSV با کدگذاری UTF-8 و سطر عنوان |
+| `data/provinces.json`، `data/cities.json` | آرایه‌ی مسطح JSON |
+| `data/iran-cities.sql` | جدول‌ها، کلیدهای خارجی و insertها برای PostgreSQL، MySQL، MariaDB و SQLite |
+| `data/iran-provinces.geojson` | مرز استان‌ها |
+
+```bash
+curl -O https://unpkg.com/@code-plate/iran-cities/dist/data/iran-cities.sql
+psql mydb < iran-cities.sql
+```
+
+## مرجع API
+
+هر جا query خواسته شده، می‌توانید نام فارسی، شناسه‌ی انگلیسی، نام نمایشی انگلیسی یا id عددی (عدد یا رشته، حتی با ارقام فارسی) بدهید.
+
+<details open>
+<summary><b>استان‌ها</b></summary>
+
+| تابع | خروجی |
+|---|---|
+| `getProvinces()` | `readonly Province[]` همراه با شهرها |
+| `getProvincesList()` | `ProvinceListItem[]` بدون شهرها (هر بار آرایه‌ی جدید) |
+| `getProvince(query)` | `Province \| undefined` |
+| `getProvinceById(id)` | `Province \| undefined` |
+| `getProvinceByPhoneCode(code)` | `Province \| undefined` |
+| `getProvinceOfCity(cityQuery)` | `Province \| undefined` |
+| `getNeighborProvinces(query)` | `Province[]` هم‌مرز |
+| `areNeighborProvinces(a, b)` | `boolean` |
+
+</details>
+
+<details open>
+<summary><b>شهرها</b></summary>
+
+| تابع | خروجی |
+|---|---|
+| `getCities(provinceQuery)` | `readonly City[]` |
+| `getAllCities()` | `readonly FlatCity[]` |
+| `getCity(cityQuery, provinceQuery?)` | `FlatCity \| undefined` |
+| `getCityById(id)` | `FlatCity \| undefined` |
+| `getCityBySlug(slug)` | `FlatCity \| undefined`، مثلاً `'fars/shiraz'`؛ slugهای قدیمی هم کار می‌کنند |
+| `getCitiesByName(name)` | `readonly FlatCity[]`، همه‌ی شهرهای هم‌نام یا با همان نام جایگزین |
+| `isAmbiguousCityName(name)` | `boolean` |
+| `getCapital(provinceQuery)` | `FlatCity \| undefined` |
+| `getCapitals()` | `FlatCity[]`، مراکز ۳۱ استان |
+
+</details>
+
+<details open>
+<summary><b>جستجو</b></summary>
+
+| تابع | خروجی |
+|---|---|
+| `searchCities(query, options?)` | `FlatCity[]` |
+| `searchProvinces(query, options?)` | `Province[]` |
+| `normalize(text)` | `string`، همان نرمال‌سازی‌ای که همه‌ی lookupها استفاده می‌کنند |
+| `convertKeyboardLayout(text, 'fa' \| 'en')` | `string` |
+
+| `SearchOptions` | پیش‌فرض | |
+|---|---|---|
+| `limit` | بدون محدودیت | حداکثر تعداد نتایج |
+| `locale` | `'both'` | `'fa'`، `'en'` یا `'both'` |
+| `fuzzy` | `false` | تحمل غلط تایپی |
+| `maxDistance` | `2` | حداکثر فاصله‌ی ویرایشی در حالت `fuzzy`؛ حداکثر یک‌سوم طول query |
+| `emptyQuery` | `'all'` | خروجی query خالی: `'all'` یا `'none'` |
+| `keyboardFix` | `true` | اگر نتیجه‌ای نبود، با چیدمان کیبورد دیگر دوباره جستجو می‌کند |
+
+</details>
+
+<details open>
+<summary><b>جغرافیا</b></summary>
+
+| تابع | خروجی |
+|---|---|
+| `getDistance(from, to)` | کیلومتر، یا `undefined` اگر یکی مختصات نداشته باشد |
+| `getNearestCities(point, options?)` | `{ city, distanceKm }[]` به ترتیب فاصله؛ گزینه‌ها `limit` (۵، و `0` یعنی همه)، `minConfidence` (`'low'`)، `maxDistanceKm` |
+| `getProvinceAt(point, options?)` | `Province \| undefined`؛ نقطه‌هایی که تا `maxDistanceKm` (۵) بیرون از مرز باشند به نزدیک‌ترین استان نسبت داده می‌شوند *(ورودی boundaries)* |
+| `getProvinceBoundary(id)` | یک feature از GeoJSON *(ورودی boundaries)* |
+| `provinceBoundaries` | `FeatureCollection` از GeoJSON *(ورودی boundaries)* |
+
+`from`، `to` و `point` می‌توانند query شهر یا `{ lat, lng }` باشند.
 
-## API کامل
+</details>
 
-### توابع اصلی (import از `'@code-plate/iran-cities'`)
+<details open>
+<summary><b>نسخه‌ی داده</b></summary>
 
-| تابع | ورودی | خروجی | توضیح |
-|---|---|---|---|
-| `getProvinces()` | - | `Province[]` | همه‌ی استان‌ها به همراه شهرها |
-| `getProvincesList()` | - | `{id, en, fa}[]` | فقط لیست استان‌ها |
-| `getCapital(provinceQuery)` | `string \| number` | `FlatCity \| undefined` | مرکز استان |
-| `getCapitals()` | - | `FlatCity[]` | مراکز ۳۱ استان |
-| `getProvinceByPhoneCode(code)` | `string \| number` | `Province \| undefined` | استان با کد تلفن بین‌شهری |
-| `getProvinceById(id)` | `number` | `Province \| undefined` | استان با id |
-| `getCityById(id)` | `number` | `FlatCity \| undefined` | شهر با id سراسری |
-| `getCitiesByName(name)` | `string` | `FlatCity[]` | همه‌ی شهرهای با این نام (برای نام‌های تکراری) |
-| `getProvince(query)` | `string \| number` | `Province \| undefined` | یک استان با en یا fa |
-| `getCities(provinceQuery)` | `string \| number` | `City[]` | شهرهای یک استان |
-| `getCity(cityQuery, provinceQuery?)` | `string \| number, (string \| number)?` | `FlatCity \| undefined` | یک شهر مشخص |
-| `getAllCities()` | - | `FlatCity[]` | همه‌ی شهرها به‌صورت مسطح |
-| `getProvinceOfCity(cityQuery)` | `string \| number` | `Province \| undefined` | استانِ یک شهر |
-| `searchProvinces(query, options?)` | `string, SearchOptions?` | `Province[]` | جستجوی fuzzy استان |
-| `searchCities(query, options?)` | `string, SearchOptions?` | `FlatCity[]` | جستجوی fuzzy شهر |
-| `getStats()` | - | `{provinceCount, cityCount}` | آمار کلی |
+| export | |
+|---|---|
+| `DATA_VERSION` | نسخه‌ی داده، مثلاً `'2.0.0'` |
+| `DATA_CHANGES` | همه‌ی تغییر نام‌ها، اصلاح‌های املایی و حذف‌ها از نسخه‌ی 1.0 |
+| `getDataChanges(sinceVersion?)` | تغییرات بعد از یک نسخه، برای به‌روز کردن مقادیری که ذخیره کرده‌اید |
 
-`SearchOptions`: `{ limit?: number; locale?: 'en' | 'fa' | 'both' }`
+</details>
 
-### تایپ‌ها
+### TypeScript
 
 ```ts
-interface Coordinates { lat: number; lng: number; confidence: 'high' | 'medium' | 'low'; }
-interface City { id: number; isCapital: boolean; coordinates?: Coordinates; slug: string; en: string; fa: string; }
-interface Province { id: number; en: string; fa: string; phoneCode: string; capitalId: number; cities: City[]; }
-interface FlatCity extends City { provinceId: number; provinceEn: string; provinceFa: string; phoneCode: string; }
+interface Province {
+  id: number;                       // 1 – 31
+  en: string;                       // 'fars'
+  fa: string;                       // 'فارس'
+  nameEn: string;                   // 'Fars'
+  phoneCode: string;                // '071'
+  capitalId: number;
+  neighborIds: readonly number[];
+  cities: readonly City[];
+}
+
+interface City {
+  id: number;                       // در کل ایران یکتا و هرگز دوباره استفاده نمی‌شود
+  en: string;                       // 'shiraz'
+  fa: string;                       // 'شیراز'
+  nameEn: string;                   // 'Shiraz'
+  slug: string;                     // 'fars/shiraz'
+  isCapital: boolean;
+  aliases: readonly string[];
+  coordinates?: { lat: number; lng: number; confidence: 'high' | 'medium' | 'low' };
+}
+
+interface FlatCity extends City {
+  provinceId: number;
+  provinceEn: string;
+  provinceFa: string;
+  provinceNameEn: string;
+  phoneCode: string;
+}
 ```
 
----
+همه‌ی تایپ‌ها export شده‌اند، از جمله `ProvinceListItem`، `SearchOptions`، `NearestCity`، `LatLng`، `ProvinceCityValue`، `CityComboboxProps`، `ProvinceCitySelectProps`، `DataChange` و اینترفیس‌های `IranCities`، `IranCitiesGeo` و `IranCitiesHooks`.
+
+> [!NOTE]
+> استان‌ها، شهرها و آرایه‌های مشترک با `Object.freeze` قفل شده‌اند تا یک بخش برنامه نتواند تصادفاً داده‌ها را برای بخش دیگر خراب کند. برای تغییر، اول کپی بگیرید: `[...getCities('fars')].sort(...)`. `getProvincesList()`، `getCapitals()`، `getNeighborProvinces()` و توابع جستجو خودشان آرایه‌ی جدید برمی‌گردانند.
+
+## تطبیق متن چطور کار می‌کند
+
+**نرمال‌سازی.** همه‌ی lookupها و جستجوها متن نرمال‌شده را مقایسه می‌کنند، پس این‌ها یکی حساب می‌شوند:
+
+| یکسان | |
+|---|---|
+| `ی` `ي` `ى` `ئ` | `ک` `ك` |
+| `ا` `آ` `أ` `إ` `ٱ` | `ه` `ة` `ۀ` |
+| `و` `ؤ` | `۰۱۲` `٠١٢` `012` |
+
+اعراب، کشیده (`ـ`)، نیم‌فاصله، فاصله، `-`، `_` و آپاستروف نادیده گرفته می‌شوند و بزرگی و کوچکی حروف مهم نیست.
+
+**چیدمان کیبورد.** اگر جستجو نتیجه‌ای نداشته باشد، دوباره طوری جستجو می‌شود که انگار با چیدمان دیگر تایپ شده: `jivhk` ← `تهران` و `ساهقشظ` ← `shiraz`. با `{ keyboardFix: false }` خاموش می‌شود.
+
+**ترتیب نتایج.** اول تطابق کامل، بعد شروع نام، بعد شامل‌بودن، و بعد (با `fuzzy`) فاصله‌ی ویرایشی. در امتیاز برابر، مراکز استان اول می‌آیند و بعد ترتیب الفبای فارسی.
+
+**نام‌های تکراری.** ۲۵ نام شهر در بیش از یک استان وجود دارد. بدون استان، `getCity(name)` مرکز استان را برمی‌گرداند، وگرنه شهر شناخته‌شده‌تر را، وگرنه کوچک‌ترین id را. اگر انتخاب مهم است، با `isAmbiguousCityName(name)` چک کنید و استان را هم بدهید یا انتخاب را از `getCitiesByName(name)` به کاربر بسپارید.
+
+**نام‌های جایگزین.** املاهای دیگر و نام‌های قدیمی به شهر درست می‌رسند: `طهران`، `teheran`، `esfahan`، `mashad`، `orumiyeh`، `صومعه سارا`، `حلاشی`.
 
-## توسعه
+## داده‌ها و منابع
+
+| | |
+|---|---:|
+| استان | ۳۱ |
+| شهر | ۱۲۵۲ |
+| شهر دارای مختصات | ۱۱۵۲ |
+| ↳ اطمینان `high` | ۹۷۷ |
+| ↳ اطمینان `medium` | ۹۸ |
+| ↳ اطمینان `low` | ۷۷ |
+| مرز مشترک بین استان‌ها | ۷۴ |
+
+- **`high`**: یک منبع مستقل همان نقطه را تأیید می‌کند.
+- **`medium`**: نام در GeoNames یکتاست و مکان شبیه شهر است، ولی تأیید مستقل ندارد.
+- **`low`**: فقط تطابق نام در GeoNames. برای نمایش تقریبی مناسب است و خطای چند کیلومتری ممکن است.
+
+همه‌ی مختصات در CI با مرز استان‌ها بررسی می‌شوند و هر ۱۱۵۲ نقطه داخل استان خودشان هستند. برای ۱۰۰ شهر باقی‌مانده `coordinates` برابر `undefined` است و هیچ مقدار حدسی گذاشته نشده ([فهرست و دلیل‌ها](./reports/coordinates-not-imported.csv)).
+
+همسایه‌ها از روی مرز استان‌ها محاسبه شده‌اند (حداقل ۳ کیلومتر مرز مشترک) و مرزهای فعلی را نشان می‌دهند، از جمله انتقال شهرستان طبس از یزد به خراسان جنوبی در سال ۱۳۹۲.
+
+idها هرگز تغییر نمی‌کنند و دوباره استفاده نمی‌شوند. slugهای تغییرکرده همچنان کار می‌کنند و همه‌ی تغییرات در `DATA_CHANGES` ثبت شده‌اند.
+
+## سازگاری
+
+هر نسخه در CI روی این ترکیب‌ها تست می‌شود:
+
+| | پشتیبانی |
+|---|---|
+| Node.js | 14، 16، 18، 20، 22، 24 (CommonJS و ES module) |
+| Deno، Bun | نسخه‌های فعلی |
+| TypeScript | 3.9 تا 7، با `moduleResolution` برابر `node`، `node16` یا `bundler` |
+| React | 16.8 به بالا (تست‌شده با 17، 18 و 19) |
+| Next.js | 14، 15، 16 (App Router؛ Turbopack و webpack) |
+| Zod، Valibot | Zod 3.25 به بالا و 4، Valibot 1 |
+
+هر bundler که فیلد `exports` را بشناسد (Vite، webpack، Rollup، Rolldown، esbuild، Turbopack و ...) می‌تواند از پکیج استفاده کند.
+
+## مشارکت
+
+ارزشمندترین مشارکت، اصلاح داده است؛ لطفاً منبع را هم بنویسید. [CONTRIBUTING.fa.md](./CONTRIBUTING.fa.md) را ببینید.
 
 ```bash
 npm install
-npm run build     # خروجی dist/ (cjs + esm + d.ts)
-npm run typecheck
-npm run validate  # اعتبارسنجی یکپارچگی data.json (id، slug، مرکز استان، کد تلفن، مختصات)
-npm test          # validate + typecheck
+npm test              # اعتبارسنجی داده، TypeScript 7، Oxlint، Vitest
+npm run build         # tsdown (Rolldown + Oxc)
+npm run test:dist     # smoke test فایل‌های build شده
 ```
 
-> **مختصات:** برای ۱۱۵۲ شهر از ۱۲۵۲ شهر موجود است (`coordinates: { lat, lng, confidence }`). `confidence` سه مقدار دارد: `'high'` (۹۷۷ شهر) یعنی منبع مستقل دیگری هم همان نقطه را تأیید کرده؛ `'medium'` (۹۸ شهر) یعنی نام شهر در GeoNames یکتا و شهر واقعی بوده ولی تأیید مستقل نداشته؛ `'low'` (۷۷ شهر) یعنی فقط تطبیق نام در GeoNames هست و مکانِ مطابق کوچک یا بدون جمعیت ثبت شده یا نام تقریبی تطبیق داده شده (فقط برای نمایش تقریبی؛ خطای چند تا ده‌ها کیلومتر محتمل است). برای ۱۰۰ شهر باقی‌مانده `coordinates` برابر `undefined` است و هیچ مقدار تقریبی جایگزین نمی‌شود (فهرست و دلیل: `reports/coordinates-not-imported.csv`). منبع داده: GeoNames (CC BY 4.0)، فایل `NOTICE.md`.
+برای انتشار نسخه‌ی جدید، `version` را در `package.json` و `CHANGELOG.md` به‌روز کنید و بعد:
+
+```bash
+npm publish --access public
+```
+
+`npm publish` قبل از انتشار همه‌ی بررسی‌ها را اجرا می‌کند (تست‌ها، build، smoke test، lint پکیج و بودجه‌ی حجم) و اگر یکی خطا بدهد، انتشار متوقف می‌شود.
+
+## مجوز و منابع
+
+| | منبع | مجوز |
+|---|---|---|
+| کد | همین پروژه | [MIT](./LICENSE) |
+| مختصات | [GeoNames](https://www.geonames.org) | CC BY 4.0 |
+| مرزها و همسایه‌ها | [geoBoundaries](https://www.geoboundaries.org) / © OpenStreetMap contributors | ODbL 1.0 |
+
+فیلد license پکیج `MIT AND CC-BY-4.0 AND ODbL-1.0` است. ODbL فقط وقتی اعمال می‌شود که خود داده‌ی مرزها را بازنشر کنید؛ [`NOTICE.md`](./NOTICE.md) را ببینید.
 
-## لایسنس
+<div align="center">
+<sub>ساخته‌شده با ❤️ برای توسعه‌دهنده‌های فارسی‌زبان · <a href="./CHANGELOG.md">Changelog</a> · <a href="./MIGRATION.fa.md">راهنمای مهاجرت</a> · <a href="https://mjavadsf.github.io/Iran-Cities/fa/">مستندات</a> · <a href="https://github.com/MJavadSF/Iran-Cities/issues">Issues</a></sub>
+</div>
 
-MIT
+</div>