ngxsmk-tel-input 1.6.9 → 1.6.10

package/README.md

@@ -1,17 +1,17 @@
 # ngxsmk-tel-input
 
-An Angular **telephone input** component with country dropdown, flags, and robust validation/formatting.
-Wraps [`intl-tel-input`](https://github.com/jackocnr/intl-tel-input) for the UI and [`libphonenumber-js`](https://github.com/catamphetamine/libphonenumber-js) for parsing/validation. Implements `ControlValueAccessor` so it plugs into Angular Forms.
+An Angular **phone input / telephone input** component with country dropdown, flags, international formatting, and robust validation.
+Built on top of [`intl-tel-input`](https://github.com/jackocnr/intl-tel-input) + [`libphonenumber-js`](https://github.com/catamphetamine/libphonenumber-js), and fully compatible with Angular Reactive Forms and template-driven forms through `ControlValueAccessor`.
 
 > Emits **E.164** by default (e.g. `+14155550123`). SSR‑safe via lazy browser‑only import.
 
-## 🚀 Try it live on StackBlitz
+##  Try it live on StackBlitz
 
 [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/~/github.com/toozuuu/ngxsmk-tel-input)
 
 ---
 
-## ✨ Features
+##  Features
 
 * Country dropdown with flags
 * E.164 output (display can be national with `nationalMode`)
@@ -19,7 +19,7 @@ Wraps [`intl-tel-input`](https://github.com/jackocnr/intl-tel-input) for the UI
 * Built‑in validation using libphonenumber‑js
 * **Enhanced validation**: Detects invalid country codes (like "11", "99") and shows appropriate error states
 * **Mobile responsive**: Optimized for touch devices with proper tap targets, prevents iOS zoom, and responsive dropdown
-* **Dark & Light themes**: Comprehensive theme system with automatic system preference detection
+* **Dark & Light themes**: Improved dark-mode contrast, consistent code/readout colors, and automatic system preference detection
 * **Accessibility**: Full ARIA support, screen reader compatibility, keyboard navigation
 * SSR‑friendly (no `window` on the server)
 * Easy theming via CSS variables
@@ -27,9 +27,18 @@ Wraps [`intl-tel-input`](https://github.com/jackocnr/intl-tel-input) for the UI
 * Masking & caret-friendly as-you-type formatting (optional)
 * Format only when valid (formatWhenValid) and lock once valid (lockWhenValid) to prevent extra digits
 
+### Demo app highlights
+
+The workspace demo (`ng serve demo`) now includes:
+
+* polished documentation-style layout with improved spacing and visual hierarchy
+* responsive sidebar/header behavior for mobile and desktop
+* cleaner dark-mode palette with better text/background contrast
+* improved focus states and reduced-motion support for accessibility
+
 ---
 
-## ✅ Requirements
+##  Requirements
 
 * Angular **17+** (17, 18, 19, 20, 21+)
 * Node **18** or **20**
@@ -38,7 +47,7 @@ Wraps [`intl-tel-input`](https://github.com/jackocnr/intl-tel-input) for the UI
 
 ---
 
-## 📦 Install
+##  Install
 
 ```bash
 npm i ngxsmk-tel-input intl-tel-input libphonenumber-js
@@ -82,7 +91,7 @@ Restart the dev server after changes.
 
 ---
 
-## 🚀 Quick start (Reactive Forms)
+##  Quick start (Reactive Forms)
 
 ```ts
 // app.component.ts
@@ -143,7 +152,7 @@ export class AppComponent {
 
 ---
 
-## 📝 Template‑driven usage
+##  Template‑driven usage
 
 ```html
 <form #f="ngForm">
@@ -154,7 +163,7 @@ export class AppComponent {
 
 ---
 
-## 🈺 Localization & RTL
+##  Localization & RTL
 
 You can localize the dropdown/search labels and override country names.
 
@@ -204,7 +213,7 @@ Arabic + RTL example
 ```
 
 
-## ⚙️ API
+## ️ API
 
 ### Inputs
 
@@ -250,15 +259,18 @@ Arabic + RTL example
 | `countryChange`  | `{ iso2: CountryCode }`                                    | Fired when selected country changes. |
 | `validityChange` | `boolean`                                                  | Fired when validity flips.           |
 | `inputChange`    | `{ raw: string; e164: string \| null; iso2: CountryCode }` | Emitted on every keystroke.          |
+| `ready`          | `void`                                                     | Emitted after plugin + listeners finish wiring (including each re-init cycle). |
 
 ### Public methods
 
 * `focus(): void`
 * `selectCountry(iso2: CountryCode): void`
 
+For deterministic first render behavior, prefer setting `[initialCountry]` directly. If you call imperative APIs like `selectCountry(...)` immediately after mount, wait for `(ready)` first.
+
 ---
 
-## 🧠 Formatting & validity behavior
+##  Formatting & validity behavior
 
 * No formatting while invalid. As-you-type masking only starts when the digits form a valid number for the selected country.
 
@@ -270,7 +282,7 @@ For rare patterns not covered by libphonenumber-js, the control falls back to ra
 
 ---
 
-## 🎨 Theming
+##  Theming
 
 ### CSS Variables
 
@@ -324,7 +336,7 @@ Dark mode: wrap in a `.dark` parent or use `[theme]="'dark'"` — tokens adapt a
 
 ---
 
-## ✔️ Validation patterns
+## ️ Validation patterns
 
 ```html
 <ngxsmk-tel-input formControlName="phone"></ngxsmk-tel-input>
@@ -360,14 +372,14 @@ The component now includes enhanced validation that detects and handles various
 
 ---
 
-## 🌐 SSR notes
+##  SSR notes
 
 * The library lazy‑imports `intl-tel-input` only in the **browser** (guards with `isPlatformBrowser`).
 * No `window`/`document` usage on the server path.
 
 ---
 
-## 🧪 Local development
+##  Local development
 
 This repo is an Angular workspace with a library.
 
@@ -388,7 +400,7 @@ npm i ../path-to-workspace/dist/ngxsmk-tel-input/ngxsmk-tel-input-<version>.tgz
 
 ---
 
-## 🧯 Troubleshooting
+##  Troubleshooting
 
 **UI looks unstyled / bullets in dropdown**
 Add the CSS and assets in `angular.json` (see Install). Restart the dev server.
@@ -407,13 +419,13 @@ Clear `.angular/cache`, rebuild the lib, and restart `ng serve`.
 
 ---
 
-## 📃 License
+##  License
 
 [MIT](./LICENSE)
 
-## 🙌 Credits
+##  Credits
 
 * UI powered by [`intl-tel-input`](https://github.com/jackocnr/intl-tel-input)
 * Parsing & validation by [`libphonenumber-js`](https://github.com/catamphetamine/libphonenumber-js)
 
-Last updated: 2025-01-21
+Last updated: 2026-05-01