geo-sl 1.0.1 → 1.1.0

package/README.md

@@ -12,11 +12,11 @@
 
 ## 🗺️ 100% Comprehensive Island-wide Coverage
 
-`geo-sl` is not limited to major metropolitan areas. It provides complete, authoritative, and verified geographic coverage across the entire territory of Sri Lanka—from provincial capitals down to individual rural villages:
+`geo-sl` covers the entire territory of Sri Lanka — not just major cities and urban centers. It provides complete, authoritative, and verified geographic data from provincial capitals all the way down to individual rural villages and remote Grama Niladhari divisions:
 
 | Administrative / Geographic Level | Total Count | Scope & Details | Supported Languages |
 |---|---|---|---|
-| **Provinces** | **9** | All 9 provinces (WP, CP, SP, NP, EP, NW, NC, UV, SG) | English, සිංහල, தமிழ் |
+| **Provinces** | **9** | All 9 provinces (WP, CP, SP, NP, EP, NWP, NCP, UP, SGP) | English, සිංහල, தமிழ் |
 | **Districts** | **25** | All 25 administrative districts across the island | English, සිංහල, தமிழ் |
 | **Divisional Secretariats (DSD)** | **340** | 100% of Divisional Secretariat Divisions (MOHA) | English, සිංහල, தமிழ் |
 | **Grama Niladhari (GN) Divisions** | **14,020** | Every single village, ward, and local community | English, සිංහල, தமிழ் |
@@ -92,7 +92,7 @@ getPostalCode('මහනුවර');       // => "20000"
 // 5. Search with Relevance Ranking
 search('colombo'); // => [ { name_en: 'Colombo 1', ... }, { name_en: 'Colombo 2', ... } ]
 search('nawala');  // => [ { name_en: 'Nawala', ... }, ... ]
-search('කොළඹ');    // Sinhala search
+search('කොළඹ');    // => [ { name_en: 'Colombo 1', ... }, ... ]  (Sinhala search)
 ```
 
 ---
@@ -121,18 +121,22 @@ import { BANKS, getBanks, getBankByCode, getBranches } from 'geo-sl/banks';
 import { GN_DIVISIONS, getGNDivisions, searchGN } from 'geo-sl/gn';
 
 // Validators & Parsers (~2.3 KB)
-import { validateNIC, parseNIC, validatePhone, parsePhone, validatePostalCode } from 'geo-sl/validators';
+import { validateNIC, parseNIC, convertOldNICToNew, validatePhone, parsePhone, formatPhone, validatePostalCode } from 'geo-sl/validators';
 ```
 
 ---
 
-## 🎨 Interactive React / Next.js Cascading Form Example
+## 🎨 Interactive React / Next.js Cascading Form Examples
 
-The easiest way to build a Sri Lankan checkout address form:
+`geo-sl` makes building multi-level dependent dropdowns straightforward for both e-commerce checkouts and official KYC/government forms.
+
+### 1. Delivery & Checkout Address Form (`Province ➔ District ➔ City / Postal Code`)
+
+For shipping and delivery addresses, use `getCascadingData()` or `toSelectOptions()`:
 
 ```tsx
 import React, { useState } from 'react';
-import { getCascadingData } from 'geo-sl';
+import { getCascadingData, toSelectOptions } from 'geo-sl';
 
 const addressData = getCascadingData({ lang: 'en' });
 
@@ -144,22 +148,32 @@ export function SriLankaAddressForm() {
   const currentProvince = addressData.find((p) => p.code === selectedProvince);
   const currentDistrict = currentProvince?.districts.find((d) => d.code === selectedDistrict);
 
+  // Convert to standard { label, value } options for React-Select / Shadcn / HTML select
+  const provinceOptions = toSelectOptions(addressData, 'name', 'code');
+  const districtOptions = toSelectOptions(currentProvince?.districts || [], 'name', 'code');
+  const cityOptions = toSelectOptions(
+    currentDistrict?.cities || [],
+    (c) => `${c.name} (${c.postal_code})`,
+    'name'
+  );
+
   return (
     <div className="space-y-4">
       {/* Province */}
       <select
         value={selectedProvince}
         onChange={(e) => {
-          setSelectedProvince(e.target.value as any);
-          const prov = addressData.find((p) => p.code === e.target.value);
+          const code = e.target.value;
+          setSelectedProvince(code as any);
+          const prov = addressData.find((p) => p.code === code);
           if (prov && prov.districts[0]) {
             setSelectedDistrict(prov.districts[0].code);
             setSelectedCity(prov.districts[0].cities[0]?.name || '');
           }
         }}
       >
-        {addressData.map((p) => (
-          <option key={p.code} value={p.code}>{p.name}</option>
+        {provinceOptions.map((opt) => (
+          <option key={opt.value} value={opt.value}>{opt.label}</option>
         ))}
       </select>
 
@@ -167,15 +181,16 @@ export function SriLankaAddressForm() {
       <select
         value={selectedDistrict}
         onChange={(e) => {
-          setSelectedDistrict(e.target.value as any);
-          const dist = currentProvince?.districts.find((d) => d.code === e.target.value);
+          const code = e.target.value;
+          setSelectedDistrict(code as any);
+          const dist = currentProvince?.districts.find((d) => d.code === code);
           if (dist && dist.cities[0]) {
             setSelectedCity(dist.cities[0].name);
           }
         }}
       >
-        {currentProvince?.districts.map((d) => (
-          <option key={d.code} value={d.code}>{d.name}</option>
+        {districtOptions.map((opt) => (
+          <option key={opt.value} value={opt.value}>{opt.label}</option>
         ))}
       </select>
 
@@ -184,10 +199,8 @@ export function SriLankaAddressForm() {
         value={selectedCity}
         onChange={(e) => setSelectedCity(e.target.value)}
       >
-        {currentDistrict?.cities.map((c) => (
-          <option key={c.name} value={c.name}>
-            {c.name} ({c.postal_code})
-          </option>
+        {cityOptions.map((opt) => (
+          <option key={opt.value} value={opt.value}>{opt.label}</option>
         ))}
       </select>
     </div>
@@ -195,6 +208,94 @@ export function SriLankaAddressForm() {
 }
 ```
 
+---
+
+### 2. Administrative & Village Form (`Province ➔ District ➔ DS Division ➔ Village / GN`)
+
+For banking KYC, voter registration, legal documentation, or government administrative forms, query on-demand down to the **14,020 official villages (Grama Niladhari divisions)**:
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import { getProvinces, getDistrictsByProvince, getDivisionsByDistrict, toSelectOptions } from 'geo-sl';
+import { getVillagesByDivision, searchVillages, type Village } from 'geo-sl/gn';
+
+export function SriLankaAdministrativeForm() {
+  const [provinceCode, setProvinceCode] = useState('WP');
+  const [district, setDistrict] = useState('Colombo');
+  const [division, setDivision] = useState('Colombo');
+  const [villages, setVillages] = useState<readonly Village[]>([]);
+  const [selectedVillage, setSelectedVillage] = useState('');
+
+  // Load villages dynamically whenever the DS division changes
+  useEffect(() => {
+    const list = getVillagesByDivision(division);
+    setVillages(list);
+    if (list.length > 0) setSelectedVillage(list[0].code);
+  }, [division]);
+
+  const provinces = toSelectOptions(getProvinces(), 'name', 'code');
+  const districts = toSelectOptions(getDistrictsByProvince(provinceCode), 'name', 'name_en');
+  const divisions = toSelectOptions(getDivisionsByDistrict(district), 'name', 'name_en');
+  const villageOptions = toSelectOptions(
+    villages,
+    (v) => `${v.name} (${v.code})`,
+    'code'
+  );
+
+  return (
+    <form className="space-y-4">
+      {/* 1. Province */}
+      <select
+        value={provinceCode}
+        onChange={(e) => {
+          setProvinceCode(e.target.value);
+          const firstDist = getDistrictsByProvince(e.target.value)[0];
+          if (firstDist) {
+            setDistrict(firstDist.name_en);
+            const firstDiv = getDivisionsByDistrict(firstDist.name_en)[0];
+            if (firstDiv) setDivision(firstDiv.name_en);
+          }
+        }}
+      >
+        {provinces.map((p) => <option key={p.value} value={p.value}>{p.label}</option>)}
+      </select>
+
+      {/* 2. District */}
+      <select
+        value={district}
+        onChange={(e) => {
+          setDistrict(e.target.value);
+          const firstDiv = getDivisionsByDistrict(e.target.value)[0];
+          if (firstDiv) setDivision(firstDiv.name_en);
+        }}
+      >
+        {districts.map((d) => <option key={d.value} value={d.value}>{d.label}</option>)}
+      </select>
+
+      {/* 3. DS Division */}
+      <select
+        value={division}
+        onChange={(e) => setDivision(e.target.value)}
+      >
+        {divisions.map((div) => <option key={div.value} value={div.value}>{div.label}</option>)}
+      </select>
+
+      {/* 4. Village (Grama Niladhari Division) */}
+      <select
+        value={selectedVillage}
+        onChange={(e) => setSelectedVillage(e.target.value)}
+      >
+        {villageOptions.map((v) => <option key={v.value} value={v.value}>{v.label}</option>)}
+      </select>
+    </form>
+  );
+}
+```
+
+> [!TIP]
+> **Autocomplete for Villages:** With 14,000+ villages, you can also use `searchVillages('Mattakkuliya', { district: 'Colombo', limit: 10 })` to power modern searchable comboboxes (Shadcn, Headless UI, Radix) across English, Sinhala (`මට්ටක්කුලිය`), and Tamil (`மட்டக்குளி`).
+
+
 ---
 
 ## 🏦 CBSL Bank & Branch Codes (`geo-sl/banks`)
@@ -209,7 +310,7 @@ const allBanks = getBanks();
 
 // Find Bank of Ceylon
 const boc = getBankByCode('7010');
-console.log(boc.name); // "Bank of Ceylon"
+console.log(boc?.name); // "Bank of Ceylon"
 
 // Get all branches for a bank
 const branches = getBranches('7010');
@@ -222,12 +323,16 @@ const branches = getBranches('7010');
 
 ### Provinces
 * `getProvinces(options?: { lang?: 'en' | 'si' | 'ta' }): Province[]`
-* `getProvinceByCode(code: string, options?: { lang?: 'en' | 'si' | 'ta' }): Province | undefined`
+* `getProvince(codeOrId: string): Province | undefined` – primary lookup by code (e.g. `'WP'`), ID, or English name.
+* `getProvinceName(codeOrId: string, lang?: Language): string | undefined`
+* `getProvinceByCode(code: string, options?: { lang?: 'en' | 'si' | 'ta' }): Province | undefined` – alias for `getProvince`
 
 ### Districts
 * `getDistricts(province?: string, options?: { lang?: 'en' | 'si' | 'ta' }): District[]`
-* `getDistrictByCode(code: string, options?: { lang?: 'en' | 'si' | 'ta' }): District | undefined`
+* `getDistrict(codeOrId: string): District | undefined` – primary lookup by abbreviation (e.g. `'CO'`), ID, or English name.
+* `getDistrictName(codeOrId: string, lang?: Language): string | undefined`
 * `getDistrictsByProvince(province: string, options?: { lang?: 'en' | 'si' | 'ta' }): District[]`
+* `getDistrictByCode(code: string, options?: { lang?: 'en' | 'si' | 'ta' }): District | undefined` – alias for `getDistrict`
 
 ### Cities & Postal Codes
 * `getCities(district?: string, options?: { lang?: 'en' | 'si' | 'ta' }): City[]`
@@ -235,36 +340,47 @@ const branches = getBranches('7010');
 * `getCitiesByProvince(province: string, options?: { lang?: 'en' | 'si' | 'ta' }): City[]`
 * `getPostalCode(cityName: string): string | undefined`
 * `getCityByPostalCode(postalCode: string | number, lang?: 'en' | 'si' | 'ta'): City | undefined`
-* `isValidPostalCode(postalCode: string | number): boolean`
-* `lookupPostalCode(code: string | number, options?: { lang?: 'en' | 'si' | 'ta' }): City | undefined`
-* `lookupAllByPostalCode(code: string | number, options?: { lang?: 'en' | 'si' | 'ta' }): City[]`
+* `isValidPostalCode(postalCode: string | number): boolean` – checks existence against the Sri Lanka Post database.
+* `lookupPostalCode(code: string | number, options?: { lang?: 'en' | 'si' | 'ta' }): City | undefined` – alias for `getCityByPostalCode`
+* `lookupAllByPostalCode(code: string | number, options?: { lang?: 'en' | 'si' | 'ta' }): City[]` – returns all offices sharing a postal code.
 * `search(query: string, options?: { limit?: number; lang?: 'en' | 'si' | 'ta'; district?: string; province?: string }): City[]`
 
-### Cascading Hierarchy
-* `getCascadingData(options?: { lang?: 'en' | 'si' | 'ta' }): CascadingProvince[]`
+### Cascading Hierarchy & Form Helpers
+* `getCascadingData(options?: { lang?: 'en' | 'si' | 'ta' }): CascadingProvince[]` – pre-nested tree (Province ➔ District ➔ Cities).
+* `getAdministrativeCascadingData(options?: { lang?: 'en' | 'si' | 'ta' }): CascadingAdministrativeProvince[]` – pre-nested tree (Province ➔ District ➔ DS Divisions).
+* `toSelectOptions<T>(items, labelKey, valueKey): SelectOption[]` – universal formatter converting data objects into `{ label, value }` pairs for UI dropdowns.
 
 ### Administrative Divisions (MOHA)
 * `getDivisions(district?: string, options?: { lang?: 'en' | 'si' | 'ta' }): Division[]`
 * `getDivisionsByDistrict(district: string, options?: { lang?: 'en' | 'si' | 'ta' }): Division[]`
+* `getDivisionsByProvince(province: string, options?: { lang?: 'en' | 'si' | 'ta' }): Division[]`
 
 ### Financial Institutions (CBSL / LankaPay)
-* `getBanks(): Bank[]`
-* `getBankByCode(code: string | number): Bank | undefined`
-* `getBranches(bankCode: string | number): Branch[]`
+* `getBanks(): readonly Bank[]`
+* `getBank(codeOrId: string | number): Bank | undefined` – primary lookup by 4-digit CBSL code, ID, or bank name.
+* `getBankByCode(codeOrId: string | number): Bank | undefined` – alias for `getBank`
+* `getBranches(bankCode: string | number): readonly Branch[]`
 * `getBranchByCode(bankCode: string | number, branchCode: string | number): Branch | undefined`
 * `searchBranches(bankCode: string | number, query: string): Branch[]`
 
-### Grama Niladhari (GN) Divisions (`geo-sl/gn`)
+### Grama Niladhari (GN) & Village Divisions (`geo-sl/gn`)
 * `getGNDivisions(options?: { lang?: 'en' | 'si' | 'ta' }): GNDivision[]`
 * `getGNDivisionsByDSD(divisionName: string, options?: { lang?: 'en' | 'si' | 'ta' }): GNDivision[]`
 * `getGNDivisionsByDistrict(districtName: string, options?: { lang?: 'en' | 'si' | 'ta' }): GNDivision[]`
 * `findGNByCode(code: string, options?: { lang?: 'en' | 'si' | 'ta' }): GNDivision | undefined`
 * `searchGN(query: string, options?: { limit?: number; lang?: 'en' | 'si' | 'ta'; district?: string; division?: string }): GNDivision[]`
+* **Village Aliases:**
+  * `getVillages(options?)` – alias for `getGNDivisions`
+  * `getVillagesByDivision(divisionName, options?)` – alias for `getGNDivisionsByDSD`
+  * `getVillagesByDistrict(districtName, options?)` – alias for `getGNDivisionsByDistrict`
+  * `findVillageByCode(code, options?)` – alias for `findGNByCode`
+  * `searchVillages(query, options?)` – alias for `searchGN`
+  * `VILLAGES` – alias for `GN_DIVISIONS`
 
 ### Sri Lanka Validators & Parsers (`geo-sl/validators`)
 * `validateNIC(nic: string): boolean`
 * `parseNIC(nic: string): ParsedNIC | null` – parses birthdate, gender, age, voter eligibility from Old (9+V/X) and New (12 digits) NICs.
-* `convertOldNICToNew(oldNic: string): string | null` – converts 9-digit old NIC to 12-digit format.
+* `convertOldNICToNew(oldNic: string): string | null` – converts 10-character old NIC (9 digits + V/X) to 12-digit new format.
 * `validatePhone(phone: string): boolean`
 * `parsePhone(phone: string): ParsedPhone | null` – parses operator (Dialog, Mobitel, Hutch, Airtel), type (mobile/fixed), and formats.
 * `formatPhone(phone: string, style?: 'international' | 'local' | 'e164'): string | null`
@@ -281,15 +397,21 @@ import type {
   Bank,
   Branch,
   GNDivision,
+  Village,
+  SelectOption,
   CascadingProvince,
   CascadingDistrict,
+  CascadingAdministrativeProvince,
+  CascadingAdministrativeDistrict,
+  CascadingAdministrativeDivision,
   ParsedNIC,
   ParsedPhone,
   Language,
   ProvinceCode,
   DistrictCode,
   QueryOptions,
-  SearchOptions
+  SearchOptions,
+  VillageSearchOptions
 } from 'geo-sl';
 ```