ngxsmk-tel-input 1.6.11 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +34 -41
  2. package/fesm2022/ngxsmk-tel-input.mjs +363 -217
  3. package/fesm2022/ngxsmk-tel-input.mjs.map +1 -1
  4. package/lib/ngxsmk-tel-input.component.d.ts +65 -34
  5. package/lib/ngxsmk-tel-input.component.d.ts.map +1 -1
  6. package/lib/ngxsmk-tel-input.service.d.ts +1 -1
  7. package/lib/ngxsmk-tel-input.service.d.ts.map +1 -1
  8. package/lib/testing/test-fixtures.d.ts +2 -0
  9. package/lib/testing/test-fixtures.d.ts.map +1 -1
  10. package/lib/types-enhanced.d.ts +4 -0
  11. package/lib/types-enhanced.d.ts.map +1 -1
  12. package/package.json +3 -3
  13. package/LICENSE +0 -21
package/README.md CHANGED
@@ -1,53 +1,45 @@
1
1
  # ngxsmk-tel-input
2
2
 
3
- An Angular **phone input / telephone input** component with country dropdown, flags, international formatting, and robust validation.
4
- 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`.
3
+ An Angular **telephone input** component with country dropdown, flags, and robust validation/formatting.
4
+ 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.
5
5
 
6
6
  > Emits **E.164** by default (e.g. `+14155550123`). SSR‑safe via lazy browser‑only import.
7
7
 
8
- ## Try it live on StackBlitz
8
+ ## Try it live on StackBlitz
9
9
 
10
10
  [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/~/github.com/toozuuu/ngxsmk-tel-input)
11
11
 
12
12
  ---
13
13
 
14
- ## Features
14
+ ## Features
15
15
 
16
16
  * Country dropdown with flags
17
- * E.164 output (display can be national with `nationalMode`)
17
+ * E.164 output (display can be configured via `nationalDisplay`)
18
18
  * Reactive & template‑driven Forms support (CVA)
19
19
  * Built‑in validation using libphonenumber‑js
20
20
  * **Enhanced validation**: Detects invalid country codes (like "11", "99") and shows appropriate error states
21
21
  * **Mobile responsive**: Optimized for touch devices with proper tap targets, prevents iOS zoom, and responsive dropdown
22
- * **Dark & Light themes**: Improved dark-mode contrast, consistent code/readout colors, and automatic system preference detection
22
+ * **Dark & Light themes**: Comprehensive theme system with automatic system preference detection
23
23
  * **Accessibility**: Full ARIA support, screen reader compatibility, keyboard navigation
24
+ * **Integrations & Ionic ready**: Built-in support for Twilio, Vonage, AWS SNS, and Ionic Framework overlays/themes (see [INTEGRATIONS.md](./INTEGRATIONS.md))
24
25
  * SSR‑friendly (no `window` on the server)
25
26
  * Easy theming via CSS variables
26
27
  * Nice UX options: label/hint/error text, sizes, variants, clear button, autofocus, select-on-focus
27
28
  * Masking & caret-friendly as-you-type formatting (optional)
28
29
  * Format only when valid (formatWhenValid) and lock once valid (lockWhenValid) to prevent extra digits
29
30
 
30
- ### Demo app highlights
31
-
32
- The workspace demo (`ng serve demo`) now includes:
33
-
34
- * polished documentation-style layout with improved spacing and visual hierarchy
35
- * responsive sidebar/header behavior for mobile and desktop
36
- * cleaner dark-mode palette with better text/background contrast
37
- * improved focus states and reduced-motion support for accessibility
38
-
39
31
  ---
40
32
 
41
- ## Requirements
33
+ ## Requirements
42
34
 
43
- * Angular **17+** (17, 18, 19, 20, 21+)
35
+ * Angular **17+** (actively tested on Angular 19)
44
36
  * Node **18** or **20**
45
37
 
46
- > Library `peerDependencies` target Angular `>=17`. Fully compatible with Angular 17, 18, 19, 20, 21, and future versions.
38
+ > Library `peerDependencies` target Angular `>=17`.
47
39
 
48
40
  ---
49
41
 
50
- ## Install
42
+ ## Install
51
43
 
52
44
  ```bash
53
45
  npm i ngxsmk-tel-input intl-tel-input libphonenumber-js
@@ -91,7 +83,7 @@ Restart the dev server after changes.
91
83
 
92
84
  ---
93
85
 
94
- ## Quick start (Reactive Forms)
86
+ ## Quick start (Reactive Forms)
95
87
 
96
88
  ```ts
97
89
  // app.component.ts
@@ -152,7 +144,7 @@ export class AppComponent {
152
144
 
153
145
  ---
154
146
 
155
- ## Template‑driven usage
147
+ ## Template‑driven usage
156
148
 
157
149
  ```html
158
150
  <form #f="ngForm">
@@ -163,7 +155,7 @@ export class AppComponent {
163
155
 
164
156
  ---
165
157
 
166
- ## Localization & RTL
158
+ ## Localization & RTL
167
159
 
168
160
  You can localize the dropdown/search labels and override country names.
169
161
 
@@ -213,19 +205,23 @@ Arabic + RTL example
213
205
  ```
214
206
 
215
207
 
216
- ## ️ API
208
+ ## API
217
209
 
218
210
  ### Inputs
219
211
 
220
212
  | Name | Type | Default | Description |
221
213
  |------------------------|---------------------------------------------|-------------------------|-------------------------------------------------------------------------------|
222
- | `initialCountry` | `CountryCode \| 'auto'` | `'US'` | Starting country. `'auto'` uses geoIp stub (`US` by default). |
214
+ | `initialCountry` | `CountryCode \| 'auto'` | `'US'` | Starting country (also respected when initial form value is `''`). `'auto'` uses geoIp stub (`US` by default). |
223
215
  | `preferredCountries` | `CountryCode[]` | `['US','GB']` | Pin these at the top. |
224
216
  | `onlyCountries` | `CountryCode[]` | — | Limit selectable countries. |
225
- | `nationalMode` | `boolean` | `false` | If `true`, **display** national format in the input. Value still emits E.164. |
226
- | `separateDialCode` | `boolean` | `false` | Show dial code outside the input. |
217
+ | `excludeCountries` | `CountryCode[]` | `[]` | Exclude specific countries from the dropdown list. |
218
+ | `searchPlaceholder` | `string` | `''` | Custom placeholder text for the dropdown search input. |
219
+ | `showFlags` | `boolean` | `true` | Hide flags completely for minimalist/text-only layouts. |
220
+ | `searchCountryFlag` | `boolean` | `true` | Hide flag icons inside the country dropdown list. |
221
+ | `nationalDisplay` | `'formatted' \| 'digits'` | `'formatted'` | Controls visible input format. Value still emits E.164. |
222
+ | `separateDialCode` | `boolean` | `true` | Show dial code outside the input. |
227
223
  | `allowDropdown` | `boolean` | `true` | Enable/disable dropdown. |
228
- | `placeholder` | `string` | `'Enter phone number'` | Input placeholder. |
224
+ | `placeholder` | `string` | — | Input placeholder. |
229
225
  | `autocomplete` | `string` | `'tel'` | Native autocomplete. |
230
226
  | `disabled` | `boolean` | `false` | Disable the control. |
231
227
  | `label` | `string` | — | Optional floating label text. |
@@ -236,14 +232,14 @@ Arabic + RTL example
236
232
  | `showClear` | `boolean` | `true` | Show a clear (×) button when not empty. |
237
233
  | `autoFocus` | `boolean` | `false` | Focus on init. |
238
234
  | `selectOnFocus` | `boolean` | `false` | Select all text on focus. |
239
- | `formatOnBlur` | `boolean` | `true` | Pretty‑print on blur (national if `nationalMode`). |
235
+ | `formatWhenValid` | `'off' \| 'blur' \| 'typing'` | `'typing'` | When to format the display value. |
240
236
  | `showErrorWhenTouched` | `boolean` | `true` | Show error styles only after blur. |
241
237
  | `dropdownAttachToBody` | `boolean` | `true` | Attach dropdown to `<body>` (avoids clipping/overflow). |
242
238
  | `dropdownZIndex` | `number` | `2000` | Z‑index for dropdown panel. |
243
239
  | `i18n` | `IntlTelI18n` | — | Localize dropdown/search/ARIA labels. |
244
240
  | `localizedCountries` | `Partial<Record<CountryCode, string>>` | — | Override country display names (ISO-2 keys). |
245
241
  | `dir` | `'ltr' \| 'rtl'` | `'ltr'` | Text direction for the control. |
246
- | `autoPlaceholder` | `'off' \| 'polite' \| 'aggressive'` | `'polite'` | Example placeholders. Requires `utilsScript` unless `off`. |
242
+ | `autoPlaceholder` | `'off' \| 'polite' \| 'aggressive'` | `'off'` | Example placeholders. Requires `utilsScript` unless `off`. |
247
243
  | `utilsScript` | `string` | — | Path/URL to `utils.js` (needed for example placeholders). |
248
244
  | `customPlaceholder` | `(example: string, country: any) => string` | — | Transform the example placeholder. |
249
245
  | `clearAriaLabel` | `string` | `'Clear phone number'` | ARIA label for the clear button. |
@@ -259,18 +255,15 @@ Arabic + RTL example
259
255
  | `countryChange` | `{ iso2: CountryCode }` | Fired when selected country changes. |
260
256
  | `validityChange` | `boolean` | Fired when validity flips. |
261
257
  | `inputChange` | `{ raw: string; e164: string \| null; iso2: CountryCode }` | Emitted on every keystroke. |
262
- | `ready` | `void` | Emitted after plugin + listeners finish wiring (including each re-init cycle). |
263
258
 
264
259
  ### Public methods
265
260
 
266
261
  * `focus(): void`
267
262
  * `selectCountry(iso2: CountryCode): void`
268
263
 
269
- For deterministic first render behavior, prefer setting `[initialCountry]` directly. If you call imperative APIs like `selectCountry(...)` immediately after mount, wait for `(ready)` first.
270
-
271
264
  ---
272
265
 
273
- ## Formatting & validity behavior
266
+ ## Formatting & validity behavior
274
267
 
275
268
  * No formatting while invalid. As-you-type masking only starts when the digits form a valid number for the selected country.
276
269
 
@@ -282,7 +275,7 @@ For rare patterns not covered by libphonenumber-js, the control falls back to ra
282
275
 
283
276
  ---
284
277
 
285
- ## Theming
278
+ ## Theming
286
279
 
287
280
  ### CSS Variables
288
281
 
@@ -336,7 +329,7 @@ Dark mode: wrap in a `.dark` parent or use `[theme]="'dark'"` — tokens adapt a
336
329
 
337
330
  ---
338
331
 
339
- ## ️ Validation patterns
332
+ ## Validation patterns
340
333
 
341
334
  ```html
342
335
  <ngxsmk-tel-input formControlName="phone"></ngxsmk-tel-input>
@@ -372,14 +365,14 @@ The component now includes enhanced validation that detects and handles various
372
365
 
373
366
  ---
374
367
 
375
- ## SSR notes
368
+ ## SSR notes
376
369
 
377
370
  * The library lazy‑imports `intl-tel-input` only in the **browser** (guards with `isPlatformBrowser`).
378
371
  * No `window`/`document` usage on the server path.
379
372
 
380
373
  ---
381
374
 
382
- ## Local development
375
+ ## Local development
383
376
 
384
377
  This repo is an Angular workspace with a library.
385
378
 
@@ -400,7 +393,7 @@ npm i ../path-to-workspace/dist/ngxsmk-tel-input/ngxsmk-tel-input-<version>.tgz
400
393
 
401
394
  ---
402
395
 
403
- ## Troubleshooting
396
+ ## Troubleshooting
404
397
 
405
398
  **UI looks unstyled / bullets in dropdown**
406
399
  Add the CSS and assets in `angular.json` (see Install). Restart the dev server.
@@ -419,13 +412,13 @@ Clear `.angular/cache`, rebuild the lib, and restart `ng serve`.
419
412
 
420
413
  ---
421
414
 
422
- ## License
415
+ ## License
423
416
 
424
417
  [MIT](./LICENSE)
425
418
 
426
- ## Credits
419
+ ## Credits
427
420
 
428
421
  * UI powered by [`intl-tel-input`](https://github.com/jackocnr/intl-tel-input)
429
422
  * Parsing & validation by [`libphonenumber-js`](https://github.com/catamphetamine/libphonenumber-js)
430
423
 
431
- Last updated: 2026-05-01
424
+ Last updated: 2025-01-21