ngxsmk-tel-input 1.6.9 → 1.6.11

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sachin Dilshan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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