ngxsmk-tel-input 1.6.7 → 1.6.9

package/README.md

@@ -17,20 +17,24 @@ Wraps [`intl-tel-input`](https://github.com/jackocnr/intl-tel-input) for the UI
 * 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**: Comprehensive theme system with 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
 
 ---
 
 ## ✅ 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.
 
 ---
 
@@ -204,37 +208,38 @@ Arabic + RTL example
 
 ### Inputs
 
-| Name                   | Type                                        | Default                 | Description                                                                                |
-|------------------------|---------------------------------------------|-------------------------|--------------------------------------------------------------------------------------------|
-| `initialCountry`       | `CountryCode \| 'auto'`                     | `'US'`                  | Starting country. `'auto'` uses geoIp stub (`US` by default).                              |
-| `preferredCountries`   | `CountryCode[]`                             | `['US','GB']`           | Pin these at the top.                                                                      |
-| `onlyCountries`        | `CountryCode[]`                             | —                       | Limit selectable countries.                                                                |
-| `nationalMode`         | `boolean`                                   | `false`                 | If `true`, **display** national format in the input. Value still emits E.164.              |
-| `separateDialCode`     | `boolean`                                   | `false`                 | Show dial code outside the input.                                                          |
-| `allowDropdown`        | `boolean`                                   | `true`                  | Enable/disable dropdown.                                                                   |
-| `placeholder`          | `string`                                    | `'Enter phone number'`  | Input placeholder.                                                                         |
-| `autocomplete`         | `string`                                    | `'tel'`                 | Native autocomplete.                                                                       |
-| `disabled`             | `boolean`                                   | `false`                 | Disable the control.                                                                       |
-| `label`                | `string`                                    | —                       | Optional floating label text.                                                              |
-| `hint`                 | `string`                                    | —                       | Helper text below the control.                                                             |
-| `errorText`            | `string`                                    | —                       | Custom error text.                                                                         |
-| `size`                 | `'sm' \| 'md' \| 'lg'`                      | `'md'`                  | Control height/typography.                                                                 |
-| `variant`              | `'outline' \| 'filled' \| 'underline'`      | `'outline'`             | Visual variant.                                                                            |
-| `showClear`            | `boolean`                                   | `true`                  | Show a clear (×) button when not empty.                                                    |
-| `autoFocus`            | `boolean`                                   | `false`                 | Focus on init.                                                                             |
-| `selectOnFocus`        | `boolean`                                   | `false`                 | Select all text on focus.                                                                  |
-| `formatOnBlur`         | `boolean`                                   | `true`                  | Pretty‑print on blur (national if `nationalMode`).                                         |
-| `showErrorWhenTouched` | `boolean`                                   | `true`                  | Show error styles only after blur.                                                         |
-| `dropdownAttachToBody` | `boolean`                                   | `true`                  | Attach dropdown to `<body>` (avoids clipping/overflow).                                    |
-| `dropdownZIndex`       | `number`                                    | `2000`                  | Z‑index for dropdown panel.                                                                |
-| `i18n`                 | `IntlTelI18n`                               | —                       | Localize dropdown/search/ARIA labels.                                                      |
-| `localizedCountries`   | `Partial<Record<CountryCode, string>>`      | —                       | Override country display names (ISO-2 keys).                                               |
-| `dir`                  | `'ltr' \| 'rtl'`                            | `'ltr'`                 | Text direction for the control.                                                            |
-| `autoPlaceholder`      | `'off' \| 'polite' \| 'aggressive'`         | `'polite'`              | Example placeholders. Requires `utilsScript` unless `off`.                                 |
-| `utilsScript`          | `string`                                    | —                       | Path/URL to `utils.js` (needed for example placeholders).                                  |
-| `customPlaceholder`    | `(example: string, country: any) => string` | —                       | Transform the example placeholder.                                                         |
-| `clearAriaLabel`       | `string`                                    | `'Clear phone number'`  | ARIA label for the clear button.                                                           |
+| Name                   | Type                                        | Default                 | Description                                                                   |
+|------------------------|---------------------------------------------|-------------------------|-------------------------------------------------------------------------------|
+| `initialCountry`       | `CountryCode \| 'auto'`                     | `'US'`                  | Starting country. `'auto'` uses geoIp stub (`US` by default).                 |
+| `preferredCountries`   | `CountryCode[]`                             | `['US','GB']`           | Pin these at the top.                                                         |
+| `onlyCountries`        | `CountryCode[]`                             | —                       | Limit selectable countries.                                                   |
+| `nationalMode`         | `boolean`                                   | `false`                 | If `true`, **display** national format in the input. Value still emits E.164. |
+| `separateDialCode`     | `boolean`                                   | `false`                 | Show dial code outside the input.                                             |
+| `allowDropdown`        | `boolean`                                   | `true`                  | Enable/disable dropdown.                                                      |
+| `placeholder`          | `string`                                    | `'Enter phone number'`  | Input placeholder.                                                            |
+| `autocomplete`         | `string`                                    | `'tel'`                 | Native autocomplete.                                                          |
+| `disabled`             | `boolean`                                   | `false`                 | Disable the control.                                                          |
+| `label`                | `string`                                    | —                       | Optional floating label text.                                                 |
+| `hint`                 | `string`                                    | —                       | Helper text below the control.                                                |
+| `errorText`            | `string`                                    | —                       | Custom error text.                                                            |
+| `size`                 | `'sm' \| 'md' \| 'lg'`                      | `'md'`                  | Control height/typography.                                                    |
+| `variant`              | `'outline' \| 'filled' \| 'underline'`      | `'outline'`             | Visual variant.                                                               |
+| `showClear`            | `boolean`                                   | `true`                  | Show a clear (×) button when not empty.                                       |
+| `autoFocus`            | `boolean`                                   | `false`                 | Focus on init.                                                                |
+| `selectOnFocus`        | `boolean`                                   | `false`                 | Select all text on focus.                                                     |
+| `formatOnBlur`         | `boolean`                                   | `true`                  | Pretty‑print on blur (national if `nationalMode`).                            |
+| `showErrorWhenTouched` | `boolean`                                   | `true`                  | Show error styles only after blur.                                            |
+| `dropdownAttachToBody` | `boolean`                                   | `true`                  | Attach dropdown to `<body>` (avoids clipping/overflow).                       |
+| `dropdownZIndex`       | `number`                                    | `2000`                  | Z‑index for dropdown panel.                                                   |
+| `i18n`                 | `IntlTelI18n`                               | —                       | Localize dropdown/search/ARIA labels.                                         |
+| `localizedCountries`   | `Partial<Record<CountryCode, string>>`      | —                       | Override country display names (ISO-2 keys).                                  |
+| `dir`                  | `'ltr' \| 'rtl'`                            | `'ltr'`                 | Text direction for the control.                                               |
+| `autoPlaceholder`      | `'off' \| 'polite' \| 'aggressive'`         | `'polite'`              | Example placeholders. Requires `utilsScript` unless `off`.                    |
+| `utilsScript`          | `string`                                    | —                       | Path/URL to `utils.js` (needed for example placeholders).                     |
+| `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`).
 
@@ -265,8 +270,9 @@ For rare patterns not covered by libphonenumber-js, the control falls back to ra
 
 ---
 
+## 🎨 Theming
 
-## 🎨 Theming (CSS variables)
+### CSS Variables
 
 Override on the element or a parent container:
 
@@ -285,7 +291,36 @@ 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.
 
 ---
 
@@ -296,10 +331,30 @@ Dark mode: wrap in a `.dark` parent — tokens adapt automatically.
 
 <div class="error" *ngIf="fg.get('phone')?.hasError('required')">Phone is required</div>
 <div class="error" *ngIf="fg.get('phone')?.hasError('phoneInvalid')">Please enter a valid phone number</div>
+<div class="error" *ngIf="fg.get('phone')?.hasError('phoneInvalidCountryCode')">Invalid country code</div>
 ```
 
+### Enhanced Validation Features
+
+The component now includes enhanced validation that detects and handles various invalid phone number scenarios:
+
+#### **Invalid Country Code Detection**
+- **Input**: `"1123456789"` or `"99123456789"`
+- **Error**: `phoneInvalidCountryCode`
+- **Reason**: "11" and "99" are not valid country codes
+
+#### **Valid Country Code, Invalid Number**
+- **Input**: `"+9111023533"` (India country code, Delhi area code, but incomplete subscriber number)
+- **Error**: `phoneInvalid`
+- **Reason**: Valid country/area codes but invalid number format
+
+#### **Valid Numbers**
+- **Input**: `"+12025551234"` (US), `"+442071234567"` (UK), `"+91112345678"` (India)
+- **Status**: Valid
+- **Output**: E.164 format string
+
 * When **valid** → control value = **E.164** string
-* When **invalid/empty** → value = **null**, and validator sets `{ phoneInvalid: true }`
+* When **invalid/empty** → value = **null**, and validator sets appropriate error type
 
 > Need national string instead of E.164? Use `(inputChange)` and store `raw`/`national` yourself, or adapt the emitter to output national.
 
@@ -345,7 +400,7 @@ 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`.
@@ -361,4 +416,4 @@ Clear `.angular/cache`, rebuild the lib, and restart `ng serve`.
 * 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: 2025-01-21