ngxsmk-tel-input 1.6.8 → 1.6.10

package/README.md

@@ -1,41 +1,53 @@
 # 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`)
 * Reactive & template‑driven Forms support (CVA)
 * 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**: 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
 * Nice UX options: label/hint/error text, sizes, variants, clear button, autofocus, select-on-focus
-* New: Masking & caret-friendly as-you-type formatting (optional)
-* New: Format only when valid (formatWhenValid) and lock once valid (lockWhenValid) to prevent extra digits
+* 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 – 19**
+* Angular **17+** (17, 18, 19, 20, 21+)
 * Node **18** or **20**
 
-> Library `peerDependencies` target Angular `>=17 <20`. Your app can be 17, 18, or 19.
+> Library `peerDependencies` target Angular `>=17`. Fully compatible with Angular 17, 18, 19, 20, 21, and future versions.
 
 ---
 
-## 📦 Install
+##  Install
 
 ```bash
 npm i ngxsmk-tel-input intl-tel-input libphonenumber-js
@@ -79,7 +91,7 @@ Restart the dev server after changes.
 
 ---
 
-## 🚀 Quick start (Reactive Forms)
+##  Quick start (Reactive Forms)
 
 ```ts
 // app.component.ts
@@ -140,7 +152,7 @@ export class AppComponent {
 
 ---
 
-## 📝 Template‑driven usage
+##  Template‑driven usage
 
 ```html
 <form #f="ngForm">
@@ -151,7 +163,7 @@ export class AppComponent {
 
 ---
 
-## 🈺 Localization & RTL
+##  Localization & RTL
 
 You can localize the dropdown/search labels and override country names.
 
@@ -201,7 +213,7 @@ Arabic + RTL example
 ```
 
 
-## ⚙️ API
+## ️ API
 
 ### Inputs
 
@@ -236,6 +248,7 @@ Arabic + RTL example
 | `customPlaceholder`    | `(example: string, country: any) => string` | —                       | Transform the example placeholder.                                            |
 | `clearAriaLabel`       | `string`                                    | `'Clear phone number'`  | ARIA label for the clear button.                                              |
 | `lockWhenValid`        | `boolean`                                   | `true`                  | Prevent appending extra digits once the number is valid (editing/replacing still allowed). |
+| `theme`                | `'light' \| 'dark' \| 'auto'`               | `'auto'`                | Theme preference for the component.                                          |
 
 > `CountryCode` is the ISO‑2 uppercase code from `libphonenumber-js` (e.g. `US`, `GB`).
 
@@ -246,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.
 
@@ -266,7 +282,9 @@ For rare patterns not covered by libphonenumber-js, the control falls back to ra
 
 ---
 
-## 🎨 Theming (CSS variables)
+##  Theming
+
+### CSS Variables
 
 Override on the element or a parent container:
 
@@ -285,11 +303,40 @@ Available tokens:
 * Input: `--tel-bg`, `--tel-fg`, `--tel-border`, `--tel-border-hover`, `--tel-ring`, `--tel-placeholder`, `--tel-error`, `--tel-radius`, `--tel-focus-shadow`
 * Dropdown: `--tel-dd-bg`, `--tel-dd-border`, `--tel-dd-shadow`, `--tel-dd-radius`, `--tel-dd-item-hover`, `--tel-dd-search-bg`, `--tel-dd-z`
 
-Dark mode: wrap in a `.dark` parent — tokens adapt automatically.
+### Theme Support
+
+The component supports light, dark, and auto themes:
+
+```ts
+import { NgxsmkTelInputComponent, ThemeService } from 'ngxsmk-tel-input';
+
+// Component-level theme
+<ngxsmk-tel-input [theme]="'dark'"></ngxsmk-tel-input>
+
+// Global theme management
+@Component({})
+export class MyComponent {
+  private themeService = inject(ThemeService);
+  
+  setDarkTheme() {
+    this.themeService.setTheme('dark');
+  }
+  
+  // Subscribe to theme changes
+  theme$ = this.themeService.currentTheme$;
+}
+```
+
+Themes:
+- `'light'`: Light theme
+- `'dark'`: Dark theme  
+- `'auto'`: Automatically follows system preference (default)
+
+Dark mode: wrap in a `.dark` parent or use `[theme]="'dark'"` — tokens adapt automatically.
 
 ---
 
-## ✔️ Validation patterns
+## ️ Validation patterns
 
 ```html
 <ngxsmk-tel-input formControlName="phone"></ngxsmk-tel-input>
@@ -325,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.
 
@@ -353,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.
@@ -365,20 +412,20 @@ Ensure the assets copy exists under `/assets/intl-tel-input/img` and add the CSS
 Build the library first so `dist/ngxsmk-tel-input` exists. If using workspace aliasing, add a `paths` entry to the root `tsconfig.base.json`.
 
 **Peer dependency conflict when installing**
-The lib peers are `@angular/* >=17 <20`. Upgrade your app or install a compatible version.
+The lib peers are `@angular/* >=17`. Ensure your app uses Angular 17 or higher.
 
 **Vite/Angular “Failed to resolve import …”**
 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-08-29
+Last updated: 2026-05-01