ngx-dial-input 2.1.1 → 2.1.2

package/README.md

@@ -1,24 +1,204 @@
-# PhoneInput
+# PhoneInputComponent
 
-This library was generated with [Angular CLI](https://github.com/angular/angular-cli) version 17.3.0.
+> A powerful Angular phone input component with international country selection, automatic formatting, and validation.
 
-## Code scaffolding
+Part of **ngx-dial-input** library. See main [README](../../README.md) for general information.
 
-Run `ng generate component component-name --project phone-input` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module --project phone-input`.
-> Note: Don't forget to add `--project phone-input` or else it will be added to the default project in your `angular.json` file. 
+## Component Inputs
 
-## Build
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `defaultCountry` | `string` | `''` | ISO 2-letter country code (e.g., 'US', 'GB', 'IN') |
+| `placeholder` | `string` | `''` | Placeholder text in the phone input field |
+| `searchEnabled` | `boolean` | `true` | Enable/disable country search in dropdown |
+| `numberFormat` | `'international' \| 'national'` | `'international'` | Phone number format: +12015551234 (international) or 2015551234 (national) |
+| `setFirstCountry` | `string` | `''` | Pre-select a specific country |
 
-Run `ng build phone-input` to build the project. The build artifacts will be stored in the `dist/` directory.
+## Component Output
 
-## Publishing
+### phoneChange Event
 
-After building your library with `ng build phone-input`, go to the dist folder `cd dist/phone-input` and run `npm publish`.
+Emitted when phone value changes:
 
-## Running unit tests
+```typescript
+interface PhoneData {
+  e164Number: string;       // '+12015551234' - International format for storage
+  nationalNumber: string;   // '2015551234'   - Just the digits
+  dialCode: string;         // '+1'           - Country dial code
+  countryCode: string;      // 'us'           - ISO 2-letter code (lowercase)
+  isValid: boolean;         // true/false     - Validation status
+}
+```
 
-Run `ng test phone-input` to execute the unit tests via [Karma](https://karma-runner.github.io).
+## Usage Example
 
-## Further help
+### Reactive Forms
 
-To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.
+```typescript
+import { Component } from '@angular/core';
+import { FormBuilder, FormGroup, Validators } from '@angular/forms';
+import { PhoneInputModule } from 'ngx-dial-input';
+
+@Component({
+  selector: 'app-contact-form',
+  template: `
+    <form [formGroup]="form" (ngSubmit)="submit()">
+      <div class="form-group">
+        <label>Phone Number</label>
+        <phone-input
+          [defaultCountry]="'US'"
+          [placeholder]="'Enter phone number'"
+          [searchEnabled]="true"
+          formControlName="phone"
+          (phoneChange)="onPhoneChange($event)">
+        </phone-input>
+        <small *ngIf="form.get('phone').invalid && form.get('phone').touched">
+          Please enter a valid phone number
+        </small>
+      </div>
+      <button type="submit" [disabled]="form.invalid">Submit</button>
+    </form>
+  `,
+  standalone: false
+})
+export class ContactFormComponent {
+  form: FormGroup;
+
+  constructor(private fb: FormBuilder) {
+    this.form = this.fb.group({
+      phone: [null, Validators.required]
+    });
+  }
+
+  onPhoneChange(data: any) {
+    if (data.isValid) {
+      console.log('Valid phone (e164):', data.e164Number);
+    }
+  }
+
+  submit() {
+    const phoneData = this.form.get('phone').value;
+    console.log('Phone to save:', phoneData.e164Number);
+    // API call to save phone
+  }
+}
+```
+
+### With Default Country
+
+```html
+<phone-input
+  [defaultCountry]="'GB'"
+  [setFirstCountry]="'GB'"
+  [numberFormat]="'national'"
+  formControlName="phone">
+</phone-input>
+```
+
+## Validation Behavior
+
+### Empty Input
+- Initial state with no input: `isValid = false` (but no validation error)
+- Allows users to leave the field empty until they start typing
+
+### Partial Input
+- Once user starts typing, validates against country's minimum length
+- Phone with insufficient digits: `isValid = false`
+
+### Complete Input
+- Phone matching country's required length: `isValid = true`
+- Phone exceeding max length: `isValid = false`
+
+### Example
+```
+Country: United States (min: 10 digits, max: 10 digits)
+- Empty (no input): isValid = false, no error
+- Entering: '201' (3 digits): isValid = false, too short
+- Complete: '2015551234' (10 digits): isValid = true
+- Excess: '20155512345' (11 digits): isValid = false, too long
+```
+
+## Supported Features
+
+✅ **200+ Countries** with:
+- Dial codes
+- Flag images
+- Min/max phone length
+- Format patterns
+
+✅ **Smart Search**
+- Search by country name
+- Case-insensitive matching
+- Fast filtering
+
+✅ **Animations**
+- Smooth dropdown open/close
+- Responsive to user interactions
+
+✅ **Keyboard Support**
+- Arrow keys to navigate
+- Enter to select
+- Escape to close dropdown
+
+✅ **ControlValueAccessor**
+- Works with `formControlName`
+- Works with `[(ngModel)]`
+- Works with Reactive Forms and Template Forms
+
+## Building & Testing
+
+```bash
+# Build the library
+ng build phone-input
+
+# Run unit tests
+ng test phone-input --watch
+
+# Run tests (CI mode, no watch)
+ng test phone-input --watch=false --browsers=ChromeHeadless
+
+# Create distributable package
+npm run build
+```
+
+## Output Structure
+
+After building:
+```
+dist/
+  phone-input/
+    lib/
+      phone-input.component.d.ts
+      phone-input.module.d.ts
+    package.json
+    README.md
+    LICENSE
+    phone-input.d.ts  (public API)
+```
+
+## Browser Compatibility
+
+- Chrome 90+
+- Firefox 88+
+- Safari 14+
+- Edge 90+
+
+## Performance
+
+- Component uses OnPush change detection
+- Optimized country list filtering
+- Minimal re-renders
+
+## Accessibility
+
+- Semantic HTML structure
+- Keyboard navigation support
+- ARIA labels on country selector
+
+## Contributing
+
+Issues and PRs are welcome on [GitHub](https://github.com/CroemInc/ngx-dial-input)
+
+## License
+
+MIT © [CroemInc](https://github.com/CroemInc)