angular-phone-number/README.md

A comprehensive international phone number input component for Angular applications with country selection, validation, and formatting.

# Angular Phone Number

A comprehensive international phone number input component for Angular applications with country selection, validation, and formatting.

## Installation

To install the Angular Phone Number package, run the following command:

```sh
npm i angular-phone-number
```

This package implements country-specific validations using [libphonenumber-js](https://www.npmjs.com/package/libphonenumber-js).

Install the required dependencies:

```sh
npm i libphonenumber-js -D
```

## Flag Assets Setup

**Important:** To display country flags correctly, you need to copy the flag assets to your project:

1. Copy the flag assets from the package to your project:
   ```sh
   cp -r node_modules/angular-phone-number/assets/flags src/assets
   ```

2. Ensure your Angular project is configured to include the assets folder in your `angular.json` file:
   ```json
   "assets": [
     "src/favicon.ico",
     "src/assets"
   ],
   ```

## Usage

Import the `AngularPhoneNumber` module into your module file:

```typescript
import { AngularPhoneNumber } from 'angular-phone-number';
```

Add `AngularPhoneNumber` to your module imports:

```typescript
@NgModule({
  imports: [AngularPhoneNumber]
})
export class AppModule { }
```

This package displays country names in both Arabic and English.

## Example

Here is an example of how to use the Angular Phone Number component in your application:

```typescript
@Component({
  selector: 'app-root',
  template: `
    <form [formGroup]="myForm">
      <angular-phone-number
        formControlName="phoneNumber"
        [defaultCountry]="'LK'"
        [preferredCountries]="['LK', 'IN', 'GB']"
        [error]="myForm.get('phoneNumber')?.touched && myForm.get('phoneNumber')?.invalid"
        (countryChanged)="onCountryChanged($event)"
        (inputChanged)="onInputChanged($event)"
      ></angular-phone-number>
    </form>
  `,
  styles: []
})
export class AppComponent {
  myForm: FormGroup = new FormGroup({
    phoneNumber: new FormControl(''),
  });
  
  onCountryChanged(event: any) {
    console.log('Country changed:', event);
  }

  onInputChanged(event: any) {
    console.log('Input changed:', event);
  }
}
```

## Options

The following options are available for the Angular Phone Number component:

| Option               | Type          | Default           | Description                                   |
| -------------------- | ------------- | ----------------- | --------------------------------------------- |
| `defaultCountry`     | `string`      | `null`            | Set the default country from the list.        |
| `preferredCountries` | `string[]`    | `All countries`   | List of country codes to be displayed.        |
| `error`              | `boolean`     | `false`           | Display the error status in the input box.    |
| `border`             | `boolean`     | `true`            | Display borders around the input box.         |
| `language`           | `ar` `en`     | `en`              | Change country name based on language.        |
| `mode`               | `ar` `all`    | `all`             | When set to 'ar', prioritizes Arabic countries in the list. |
| `priorityCountries`  | `string[]`    | `[]`              | List of country codes to display first in the dropdown. |
| `(countryChanged)`   | `EventEmitter`| `null`            | Emits an event when the country is changed.   |
| `(inputChanged)`     | `EventEmitter`| `null`            | Emits an event when the input is changed.     |

## Country Ordering Features

### Arabic Countries Mode

The `mode` input allows you to prioritize Arabic countries in the dropdown list:

```html
<angular-phone-number 
  [mode]="'ar'" 
  [defaultCountry]="'SA'">
</angular-phone-number>
```

When `mode="ar"` is set, all Arabic countries will be displayed at the top of the dropdown list.

### Priority Countries

The `priorityCountries` input allows you to specify which countries should appear first in the dropdown:

```html
<angular-phone-number 
  [priorityCountries]="['US', 'CA', 'GB']" 
  [defaultCountry]="'US'">
</angular-phone-number>
```

This will display USA, Canada, and Great Britain at the top of the list, in that exact order.

### Combining Ordering Features

You can use both features together:

```html
<angular-phone-number 
  [mode]="'ar'" 
  [priorityCountries]="['EG', 'SA', 'AE']" 
  [defaultCountry]="'EG'">
</angular-phone-number>
```

**Note:** When both features are used, `priorityCountries` takes precedence over the `mode` setting.

## Important Notes

- `preferredCountries` filters the dropdown to only show the specified countries.
- `priorityCountries` shows the specified countries first, followed by all other countries.

## Country List

The component supports a comprehensive list of countries with their respective codes. Here are some examples:

- US: United States
- GB: United Kingdom
- IN: India
- LK: Sri Lanka
- CA: Canada
- AU: Australia

The full list includes over 200 countries and territories with their ISO codes.