country-data-filter 1.2.0 → 1.3.0

package/README.md

@@ -484,7 +484,16 @@ The dropdowns shown are determined by which `on*Change` callbacks are provided:
 
 ## Angular Location Picker
 
-A standalone PrimeNG cascade picker component for Angular 17+. Ships as raw TypeScript source — no build step required.
+A standalone PrimeNG cascade picker for Angular 17+. Ships as raw TypeScript source — no build step required.
+
+### PrimeNG version compatibility
+
+| PrimeNG version | Component to import | Selector |
+|---|---|---|
+| v17 – v19 | `LocationPickerComponent` | `<cdf-location-picker>` |
+| v20+ | `LocationPickerSelectComponent` | `<cdf-location-picker-select>` |
+
+PrimeNG v20 removed `primeng/dropdown` (`p-dropdown`). The `LocationPickerSelectComponent` uses `primeng/select` (`p-select`) which is required for v18+.
 
 ### Peer dependencies
 
@@ -507,18 +516,36 @@ Add the source path to your `tsconfig.json`:
 
 ### Import
 
+Both components are exported from the main barrel. Import by name — TypeScript will resolve the correct file:
+
+**PrimeNG v17–v19:**
+
 ```ts
 import { LocationPickerComponent } from 'country-data-filter/angular';
 ```
 
-Add to your component's `imports` array (it is a standalone component):
+**PrimeNG v20+:**
 
 ```ts
+import { LocationPickerSelectComponent } from 'country-data-filter/angular';
+```
+
+Add to your component's `imports` array (both are standalone components):
+
+```ts
+// PrimeNG v17-v19
 @Component({
   standalone: true,
   imports: [LocationPickerComponent],
   template: `<cdf-location-picker [countryControl]="countryCtrl" />`
 })
+
+// PrimeNG v20+
+@Component({
+  standalone: true,
+  imports: [LocationPickerSelectComponent],
+  template: `<cdf-location-picker-select [countryControl]="countryCtrl" />`
+})
 ```
 
 ### Basic usage — reactive forms
@@ -587,7 +614,7 @@ Passing `[cityControl]` automatically implies all levels above it.
 
 ### PrimeNG prop passthrough
 
-Pass any PrimeNG `p-dropdown` props via the `*DropdownProps` inputs:
+**v17–v19** — use `*DropdownProps` inputs:
 
 ```html
 <cdf-location-picker
@@ -597,14 +624,30 @@ Pass any PrimeNG `p-dropdown` props via the `*DropdownProps` inputs:
 </cdf-location-picker>
 ```
 
+**v20+** — use `*SelectProps` inputs (same object shape):
+
+```html
+<cdf-location-picker-select
+  [countryControl]="countryCtrl"
+  [countrySelectProps]="{ styleClass: 'w-full', appendTo: 'body', showClear: true }"
+  [provinceSelectProps]="{ styleClass: 'w-full', filter: false }">
+</cdf-location-picker-select>
+```
+
 ### Layout
 
 ```html
+<!-- v17-v19 -->
 <cdf-location-picker layout="horizontal" [countryControl]="ctrl" />
+
+<!-- v20+ -->
+<cdf-location-picker-select layout="horizontal" [countryControl]="ctrl" />
 ```
 
 ### Inputs reference
 
+Both components share the same inputs — the only difference is `*DropdownProps` vs `*SelectProps`:
+
 | Input | Type | Default | Description |
 |---|---|---|---|
 | `countryControl` | `AbstractControl` | — | Reactive form control for country |
@@ -613,10 +656,14 @@ Pass any PrimeNG `p-dropdown` props via the `*DropdownProps` inputs:
 | `cityControl` | `AbstractControl` | — | Reactive form control for city |
 | `countryLabelKey` | `'name' \| 'code' \| 'currency' \| 'countryCode'` | `'name'` | Field to use as dropdown label |
 | `countryValueKey` | `'name' \| 'code' \| 'currency' \| 'countryCode'` | `'code'` | Field to use as option value |
-| `countryDropdownProps` | `DropdownProps` | `{}` | Props spread onto the country `<p-dropdown>` |
-| `provinceDropdownProps` | `DropdownProps` | `{}` | Props spread onto the province `<p-dropdown>` |
-| `districtDropdownProps` | `DropdownProps` | `{}` | Props spread onto the district `<p-dropdown>` |
-| `cityDropdownProps` | `DropdownProps` | `{}` | Props spread onto the city `<p-dropdown>` |
+| `countryDropdownProps` *(v17–v19)* | `DropdownProps` | `{}` | Props spread onto the country `<p-dropdown>` |
+| `provinceDropdownProps` *(v17–v19)* | `DropdownProps` | `{}` | Props spread onto the province `<p-dropdown>` |
+| `districtDropdownProps` *(v17–v19)* | `DropdownProps` | `{}` | Props spread onto the district `<p-dropdown>` |
+| `cityDropdownProps` *(v17–v19)* | `DropdownProps` | `{}` | Props spread onto the city `<p-dropdown>` |
+| `countrySelectProps` *(v20+)* | `SelectProps` | `{}` | Props spread onto the country `<p-select>` |
+| `provinceSelectProps` *(v20+)* | `SelectProps` | `{}` | Props spread onto the province `<p-select>` |
+| `districtSelectProps` *(v20+)* | `SelectProps` | `{}` | Props spread onto the district `<p-select>` |
+| `citySelectProps` *(v20+)* | `SelectProps` | `{}` | Props spread onto the city `<p-select>` |
 | `layout` | `'vertical' \| 'horizontal'` | `'vertical'` | Flex direction of the wrapper |
 
 ### Outputs reference

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "country-data-filter",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Geographical data for 190 countries — provinces, districts, cities and postal codes. Includes React (Ant Design / MUI) and Angular (PrimeNG) location picker cascade components with full TypeScript support.",
   "main": "src/index.js",
   "types": "src/index.d.ts",

package/src/angular/{location-picker.component.ts → dropdown/location-picker.component.ts}

@@ -16,7 +16,7 @@ import { DropdownModule } from 'primeng/dropdown';
 import { Observable, of, Subject } from 'rxjs';
 import { startWith, switchMap, tap, takeUntil } from 'rxjs/operators';
 
-import { LocationPickerService } from './location-picker.service';
+import { LocationPickerService } from '../location-picker.service';
 import {
   LocationOption,
   CountryChangeEvent,
@@ -24,14 +24,20 @@ import {
   CityChangeEvent,
   DropdownProps,
   CountryKey,
-} from './location-picker.types';
-
+} from '../location-picker.types';
+
+/**
+ * Location picker cascade component for PrimeNG v17–v19.
+ *
+ * Uses `<p-dropdown>` from `primeng/dropdown`.
+ * For PrimeNG v20+, use `LocationPickerSelectComponent` from `../select` instead.
+ */
 @Component({
   selector: 'cdf-location-picker',
   standalone: true,
   imports: [CommonModule, ReactiveFormsModule, DropdownModule],
   templateUrl: './location-picker.component.html',
-  styleUrls: ['./location-picker.component.css'],
+  styleUrls: ['../location-picker.component.css'],
 })
 export class LocationPickerComponent implements OnInit, OnDestroy {
   // ── External reactive-form controls (all optional) ──────────────────────────
@@ -41,10 +47,10 @@ export class LocationPickerComponent implements OnInit, OnDestroy {
   @Input() cityControl?: AbstractControl;
 
   // ── PrimeNG prop passthrough bags ────────────────────────────────────────────
-  @Input() countryDropdownProps: DropdownProps = {};
+  @Input() countryDropdownProps:  DropdownProps = {};
   @Input() provinceDropdownProps: DropdownProps = {};
   @Input() districtDropdownProps: DropdownProps = {};
-  @Input() cityDropdownProps: DropdownProps = {};
+  @Input() cityDropdownProps:     DropdownProps = {};
 
   // ── Country option key selectors ─────────────────────────────────────────────
   /** Which field of the country record to use as the dropdown label. Default: 'name' */
@@ -92,12 +98,10 @@ export class LocationPickerComponent implements OnInit, OnDestroy {
   constructor(private svc: LocationPickerService) {}
 
   ngOnInit(): void {
-    // Compute which dropdowns to show
     this.showCity     = !!this.cityControl;
     this.showDistrict = !!this.districtControl || this.showCity;
     this.showProvince = !!this.provinceControl || this.showDistrict;
 
-    // ── Countries (static, sorted A-Z) ──────────────────────────────────────
     const allCountries = this.svc.getCountries()
       .map(c => ({
         label: (c as any)[this.countryLabelKey] as string,
@@ -106,14 +110,12 @@ export class LocationPickerComponent implements OnInit, OnDestroy {
       .sort((a, b) => a.label.localeCompare(b.label));
     this.countryOptions$ = of(allCountries);
 
-    // Reverse map: mapped option value → raw country code (used for data lookups)
     const mappedValueToCode = new Map<string, string>(
       this.svc.getCountries().map(c => [
         (c as any)[this.countryValueKey] as string,
         c.code,
       ])
     );
-    // Forward map: raw code → mapped option value (used when auto-filling country)
     const codeToMappedValue = new Map<string, string>(
       this.svc.getCountries().map(c => [
         c.code,
@@ -121,11 +123,9 @@ export class LocationPickerComponent implements OnInit, OnDestroy {
       ])
     );
 
-    // Helper: get raw code from whatever value is stored in the country control
     const rawCode = (val: string | null): string | null =>
       val ? (mappedValueToCode.get(val) ?? val) : null;
 
-    // ── Province options (reload when country changes) ───────────────────────
     this.provinceOptions$ = this._country.valueChanges.pipe(
       takeUntil(this.destroy$),
       startWith(this._country.value),
@@ -133,7 +133,6 @@ export class LocationPickerComponent implements OnInit, OnDestroy {
         this._province.setValue(null, { emitEvent: false });
         this._district.setValue(null, { emitEvent: false });
         this._city.setValue(null, { emitEvent: false });
-        // Update placeholders from the selected country's labels
         const code = rawCode(val);
         if (code) {
           const country = this.svc.getCountries().find(c => c.code === code);
@@ -154,18 +153,15 @@ export class LocationPickerComponent implements OnInit, OnDestroy {
       }),
     );
 
-    // ── District options (reload when province changes; auto-fill country) ───
     this.districtOptions$ = this._province.valueChanges.pipe(
       takeUntil(this.destroy$),
       startWith(this._province.value),
       tap((name: string | null) => {
         this._district.setValue(null, { emitEvent: false });
         this._city.setValue(null, { emitEvent: false });
-        // Reverse lookup: if country not set, auto-fill from province name
         if (name && !this._country.value) {
           const code = this.svc.getCountryByProvince(name);
           if (code) {
-            // Set the mapped value (not the raw code) so the control stays consistent
             this._country.setValue(codeToMappedValue.get(code) ?? code);
           }
         }
@@ -178,7 +174,6 @@ export class LocationPickerComponent implements OnInit, OnDestroy {
       }),
     );
 
-    // ── City options (reload when district changes) ───────────────────────────
     this.cityOptions$ = this._district.valueChanges.pipe(
       takeUntil(this.destroy$),
       startWith(this._district.value),
@@ -192,7 +187,6 @@ export class LocationPickerComponent implements OnInit, OnDestroy {
       }),
     );
 
-    // ── Emit output events ───────────────────────────────────────────────────
     this._country.valueChanges
       .pipe(takeUntil(this.destroy$))
       .subscribe((v: string | null) => {

package/src/angular/index.ts

@@ -1,10 +1,12 @@
-export { LocationPickerComponent } from './location-picker.component';
-export { LocationPickerService } from './location-picker.service';
+export { LocationPickerComponent }       from './dropdown/location-picker.component';
+export { LocationPickerSelectComponent } from './select/location-picker.component';
+export { LocationPickerService }         from './location-picker.service';
 export type {
   LocationOption,
   CountryChangeEvent,
   NameChangeEvent,
   CityChangeEvent,
   DropdownProps,
+  SelectProps,
   CountryKey,
 } from './location-picker.types';

package/src/angular/location-picker.types.ts

@@ -31,3 +31,6 @@ export interface CityChangeEvent {
 }
 
 export type DropdownProps = Record<string, unknown>;
+
+/** Alias for use with LocationPickerSelectComponent (PrimeNG v18+) */
+export type SelectProps = DropdownProps;

package/src/angular/select/location-picker.component.html

@@ -0,0 +1,62 @@
+<div [class]="'cdf-location-picker cdf-' + layout">
+
+  <!-- Country select — always shown -->
+  <p-select
+    [formControl]="_country"
+    [options]="(countryOptions$ | async) ?? []"
+    [filter]="true"
+    [placeholder]="countrySelectProps['placeholder'] || 'Select Country'"
+    [styleClass]="countrySelectProps['styleClass']"
+    [showClear]="countrySelectProps['showClear'] ?? true"
+    [appendTo]="countrySelectProps['appendTo'] || 'body'"
+    [pt]="countrySelectProps['pt']"
+    optionLabel="label"
+    optionValue="value">
+  </p-select>
+
+  <!-- Province select -->
+  <p-select
+    *ngIf="showProvince"
+    [formControl]="_province"
+    [options]="(provinceOptions$ | async) ?? []"
+    [filter]="true"
+    [placeholder]="provinceSelectProps['placeholder'] || _provincePlaceholder"
+    [styleClass]="provinceSelectProps['styleClass']"
+    [showClear]="provinceSelectProps['showClear'] ?? true"
+    [appendTo]="provinceSelectProps['appendTo'] || 'body'"
+    [pt]="provinceSelectProps['pt']"
+    optionLabel="label"
+    optionValue="value">
+  </p-select>
+
+  <!-- District select -->
+  <p-select
+    *ngIf="showDistrict"
+    [formControl]="_district"
+    [options]="(districtOptions$ | async) ?? []"
+    [filter]="true"
+    [placeholder]="districtSelectProps['placeholder'] || _districtPlaceholder"
+    [styleClass]="districtSelectProps['styleClass']"
+    [showClear]="districtSelectProps['showClear'] ?? true"
+    [appendTo]="districtSelectProps['appendTo'] || 'body'"
+    [pt]="districtSelectProps['pt']"
+    optionLabel="label"
+    optionValue="value">
+  </p-select>
+
+  <!-- City select -->
+  <p-select
+    *ngIf="showCity"
+    [formControl]="_city"
+    [options]="(cityOptions$ | async) ?? []"
+    [filter]="true"
+    [placeholder]="citySelectProps['placeholder'] || 'Select City'"
+    [styleClass]="citySelectProps['styleClass']"
+    [showClear]="citySelectProps['showClear'] ?? true"
+    [appendTo]="citySelectProps['appendTo'] || 'body'"
+    [pt]="citySelectProps['pt']"
+    optionLabel="label"
+    optionValue="value">
+  </p-select>
+
+</div>

package/src/angular/select/location-picker.component.ts

@@ -0,0 +1,224 @@
+import {
+  Component,
+  Input,
+  Output,
+  EventEmitter,
+  OnInit,
+  OnDestroy,
+} from '@angular/core';
+import { CommonModule } from '@angular/common';
+import {
+  AbstractControl,
+  FormControl,
+  ReactiveFormsModule,
+} from '@angular/forms';
+import { SelectModule } from 'primeng/select';
+import { Observable, of, Subject } from 'rxjs';
+import { startWith, switchMap, tap, takeUntil } from 'rxjs/operators';
+
+import { LocationPickerService } from '../location-picker.service';
+import {
+  LocationOption,
+  CountryChangeEvent,
+  NameChangeEvent,
+  CityChangeEvent,
+  SelectProps,
+  CountryKey,
+} from '../location-picker.types';
+
+/**
+ * Location picker cascade component for PrimeNG v18+.
+ *
+ * Uses `<p-select>` from `primeng/select` — required for PrimeNG v20 which
+ * removed the old `<p-dropdown>` / `primeng/dropdown`.
+ * For PrimeNG v17–v19, use `LocationPickerComponent` from `../dropdown` instead.
+ */
+@Component({
+  selector: 'cdf-location-picker-select',
+  standalone: true,
+  imports: [CommonModule, ReactiveFormsModule, SelectModule],
+  templateUrl: './location-picker.component.html',
+  styleUrls: ['../location-picker.component.css'],
+})
+export class LocationPickerSelectComponent implements OnInit, OnDestroy {
+  // ── External reactive-form controls (all optional) ──────────────────────────
+  @Input() countryControl?: AbstractControl;
+  @Input() provinceControl?: AbstractControl;
+  @Input() districtControl?: AbstractControl;
+  @Input() cityControl?: AbstractControl;
+
+  // ── PrimeNG prop passthrough bags ────────────────────────────────────────────
+  @Input() countrySelectProps:  SelectProps = {};
+  @Input() provinceSelectProps: SelectProps = {};
+  @Input() districtSelectProps: SelectProps = {};
+  @Input() citySelectProps:     SelectProps = {};
+
+  // ── Country option key selectors ─────────────────────────────────────────────
+  /** Which field of the country record to use as the dropdown label. Default: 'name' */
+  @Input() countryLabelKey: CountryKey = 'name';
+  /** Which field of the country record to use as the option value. Default: 'code' */
+  @Input() countryValueKey: CountryKey = 'code';
+
+  // ── Layout ───────────────────────────────────────────────────────────────────
+  @Input() layout: 'horizontal' | 'vertical' = 'vertical';
+
+  // ── Event outputs (for users not using reactive forms) ───────────────────────
+  @Output() countryChange  = new EventEmitter<CountryChangeEvent>();
+  @Output() provinceChange = new EventEmitter<NameChangeEvent>();
+  @Output() districtChange = new EventEmitter<NameChangeEvent>();
+  @Output() cityChange     = new EventEmitter<CityChangeEvent>();
+
+  // ── Internal fallback controls ───────────────────────────────────────────────
+  private _internalCountry  = new FormControl<string | null>(null);
+  private _internalProvince = new FormControl<string | null>(null);
+  private _internalDistrict = new FormControl<string | null>(null);
+  private _internalCity     = new FormControl<string | null>(null);
+
+  get _country()  { return (this.countryControl  ?? this._internalCountry)  as FormControl; }
+  get _province() { return (this.provinceControl ?? this._internalProvince) as FormControl; }
+  get _district() { return (this.districtControl ?? this._internalDistrict) as FormControl; }
+  get _city()     { return (this.cityControl     ?? this._internalCity)     as FormControl; }
+
+  // ── Visibility flags ─────────────────────────────────────────────────────────
+  showProvince = false;
+  showDistrict = false;
+  showCity = false;
+
+  // ── Dynamic placeholder text (uses selected country's labels) ────────────────
+  _provincePlaceholder = 'Select Province';
+  _districtPlaceholder = 'Select District';
+
+  // ── Option streams ───────────────────────────────────────────────────────────
+  countryOptions$!:  Observable<LocationOption[]>;
+  provinceOptions$!: Observable<LocationOption[]>;
+  districtOptions$!: Observable<LocationOption[]>;
+  cityOptions$!:     Observable<LocationOption[]>;
+
+  private destroy$ = new Subject<void>();
+
+  constructor(private svc: LocationPickerService) {}
+
+  ngOnInit(): void {
+    this.showCity     = !!this.cityControl;
+    this.showDistrict = !!this.districtControl || this.showCity;
+    this.showProvince = !!this.provinceControl || this.showDistrict;
+
+    const allCountries = this.svc.getCountries()
+      .map(c => ({
+        label: (c as any)[this.countryLabelKey] as string,
+        value: (c as any)[this.countryValueKey] as string,
+      }))
+      .sort((a, b) => a.label.localeCompare(b.label));
+    this.countryOptions$ = of(allCountries);
+
+    const mappedValueToCode = new Map<string, string>(
+      this.svc.getCountries().map(c => [
+        (c as any)[this.countryValueKey] as string,
+        c.code,
+      ])
+    );
+    const codeToMappedValue = new Map<string, string>(
+      this.svc.getCountries().map(c => [
+        c.code,
+        (c as any)[this.countryValueKey] as string,
+      ])
+    );
+
+    const rawCode = (val: string | null): string | null =>
+      val ? (mappedValueToCode.get(val) ?? val) : null;
+
+    this.provinceOptions$ = this._country.valueChanges.pipe(
+      takeUntil(this.destroy$),
+      startWith(this._country.value),
+      tap((val: string | null) => {
+        this._province.setValue(null, { emitEvent: false });
+        this._district.setValue(null, { emitEvent: false });
+        this._city.setValue(null, { emitEvent: false });
+        const code = rawCode(val);
+        if (code) {
+          const country = this.svc.getCountries().find(c => c.code === code);
+          if (country) {
+            this._provincePlaceholder = `Select ${country.provinceLabel ?? 'Province'}`;
+            this._districtPlaceholder = `Select ${country.districtLabel ?? 'District'}`;
+          }
+        } else {
+          this._provincePlaceholder = 'Select Province';
+          this._districtPlaceholder = 'Select District';
+        }
+      }),
+      switchMap((val: string | null) => {
+        const code = rawCode(val);
+        return code
+          ? of(this.svc.getProvinces(code).map(p => ({ label: p, value: p })))
+          : of([]);
+      }),
+    );
+
+    this.districtOptions$ = this._province.valueChanges.pipe(
+      takeUntil(this.destroy$),
+      startWith(this._province.value),
+      tap((name: string | null) => {
+        this._district.setValue(null, { emitEvent: false });
+        this._city.setValue(null, { emitEvent: false });
+        if (name && !this._country.value) {
+          const code = this.svc.getCountryByProvince(name);
+          if (code) {
+            this._country.setValue(codeToMappedValue.get(code) ?? code);
+          }
+        }
+      }),
+      switchMap((name: string | null) => {
+        const code = rawCode(this._country.value);
+        return name && code
+          ? of(this.svc.getDistricts(code, name).map(d => ({ label: d, value: d })))
+          : of([]);
+      }),
+    );
+
+    this.cityOptions$ = this._district.valueChanges.pipe(
+      takeUntil(this.destroy$),
+      startWith(this._district.value),
+      tap(() => this._city.setValue(null, { emitEvent: false })),
+      switchMap((dist: string | null) => {
+        const code = rawCode(this._country.value);
+        const prov = this._province.value;
+        return dist && code && prov
+          ? of(this.svc.getCities(code, prov, dist).map(c => ({ label: c, value: c })))
+          : of([]);
+      }),
+    );
+
+    this._country.valueChanges
+      .pipe(takeUntil(this.destroy$))
+      .subscribe((v: string | null) => {
+        const code = rawCode(v);
+        const country = code ? (this.svc.getCountries().find(c => c.code === code) ?? null) : null;
+        this.countryChange.emit({ formValue: v, country });
+      });
+
+    this._province.valueChanges
+      .pipe(takeUntil(this.destroy$))
+      .subscribe((v: string | null) => this.provinceChange.emit({ name: v }));
+
+    this._district.valueChanges
+      .pipe(takeUntil(this.destroy$))
+      .subscribe((v: string | null) => this.districtChange.emit({ name: v }));
+
+    this._city.valueChanges
+      .pipe(takeUntil(this.destroy$))
+      .subscribe((v: string | null) => {
+        const code = rawCode(this._country.value);
+        const prov = this._province.value;
+        const dist = this._district.value;
+        const raw = (code && prov && dist && v)
+          ? this.svc.getCityRaw(code, prov, dist, v)
+          : null;
+        this.cityChange.emit({ name: v, postalCode: raw?.postalCode ?? '', type: raw?.type });
+      });
+  }
+
+  ngOnDestroy(): void {
+    this.destroy$.next();
+    this.destroy$.complete();
+  }
+}