ngxsmk-tel-input 0.0.5 → 0.0.8

package/README.md

@@ -1,45 +1,37 @@
 # ngxsmk-tel-input
 
-An Angular **telephone input** component with country dropdown, flag icons, and robust validation/formatting.
-Wraps [`intl-tel-input`](https://github.com/jackocnr/intl-tel-input) for UI and uses [`libphonenumber-js`](https://github.com/catamphetamine/libphonenumber-js) for parsing & validation. Implements `ControlValueAccessor` so it plugs right into Angular Forms.
+An Angular **telephone input** with country dropdown, flags, formatting and validation.
 
-> Emits E.164 numbers by default (e.g., `+14155550123`). SSR-safe via lazy imports.
-
----
-
-## Features
-
-* ✅ Country dropdown with flags
-* ✅ E.164 output (configurable for national numbers)
-* ✅ Works with Reactive/Template-driven Forms (`ControlValueAccessor`)
-* ✅ Built-in validation (uses `libphonenumber-js`)
-* ✅ SSR-friendly (lazy `intl-tel-input` import)
-* ✅ Tiny API surface, easy to theme
+* UI: [`intl-tel-input`](https://github.com/jackocnr/intl-tel-input)
+* Parsing/validation: [`libphonenumber-js`](https://github.com/catamphetamine/libphonenumber-js)
+* Forms: Implements **ControlValueAccessor** (Reactive & Template‑driven)
+* Output: Emits **E.164** (e.g. `+14155550123`) when valid
 
 ---
 
 ## Requirements
 
-* Angular **17+**
-* Node **18+** / **20+**
+* Angular **17 – 19**
+* Node **18** or **20**
+
+> Peer deps: `@angular/* >=17 <20`
 
 ---
 
 ## Install
 
 ```bash
-# your app
 npm i ngxsmk-tel-input intl-tel-input libphonenumber-js
 ```
 
-### Add styles & assets
+### Add styles & flags (in your **app**, not the library)
 
-`intl-tel-input` ships its own CSS and flag images. Add them to your app’s `angular.json`:
+Add `intl-tel-input` CSS and copy flag images via `angular.json`:
 
 ```jsonc
 {
   "projects": {
-    "your-app": {
+    "<your-app-name>": {
       "architect": {
         "build": {
           "options": {
@@ -47,11 +39,7 @@ npm i ngxsmk-tel-input intl-tel-input libphonenumber-js
               "node_modules/intl-tel-input/build/css/intlTelInput.css"
             ],
             "assets": [
-              {
-                "glob": "**/*",
-                "input": "node_modules/intl-tel-input/build/img",
-                "output": "assets/intl-tel-input/img"
-              }
+              { "glob": "**/*", "input": "node_modules/intl-tel-input/build/img", "output": "assets/intl-tel-input/img" }
             ]
           }
         }
@@ -61,34 +49,43 @@ npm i ngxsmk-tel-input intl-tel-input libphonenumber-js
 }
 ```
 
-> If you use a custom builder, copy the flags folder to `/assets/intl-tel-input/img`.
+Optional flag URL override (put in your app’s global styles):
+
+```css
+.iti__flag { background-image: url("/assets/intl-tel-input/img/flags.png"); }
+@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
+  .iti__flag { background-image: url("/assets/intl-tel-input/img/flags@2x.png"); }
+}
+```
+
+Restart the dev server after changes.
 
 ---
 
-## Quick start (Reactive Forms)
+## Quick Start (Reactive Forms)
 
 ```ts
 // app.component.ts
 import { Component } from '@angular/core';
 import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
-import { TelInputComponent } from 'ngxsmk-tel-input';
+import { NgxsmkTelInputComponent } from 'ngxsmk-tel-input';
 
 @Component({
   selector: 'app-root',
   standalone: true,
-  imports: [ReactiveFormsModule, TelInputComponent],
+  imports: [ReactiveFormsModule, NgxsmkTelInputComponent],
   template: `
-    <form [formGroup]="fg" class="space-y-3">
-      <label for="phone">Phone</label>
+    <form [formGroup]="fg" style="max-width:420px;display:grid;gap:12px">
       <ngxsmk-tel-input
-        id="phone"
         formControlName="phone"
+        label="Phone"
+        hint="Include area code"
         [initialCountry]="'US'"
         [preferredCountries]="['US','GB','AU']"
         (countryChange)="onCountry($event)">
       </ngxsmk-tel-input>
 
-      <p *ngIf="fg.get('phone')?.hasError('phoneInvalid') && fg.get('phone')?.touched">
+      <p class="err" *ngIf="fg.get('phone')?.hasError('phoneInvalid') && fg.get('phone')?.touched">
         Please enter a valid phone number.
       </p>
 
@@ -97,26 +94,26 @@ import { TelInputComponent } from 'ngxsmk-tel-input';
   `
 })
 export class AppComponent {
-  fg = this.fb.group({
-    phone: ['', Validators.required] // control value will be E.164 string or null
-  });
-  constructor(private fb: FormBuilder) {}
-  onCountry(e: { iso2: any }) { console.log('Country changed:', e.iso2); }
+  fg = this.fb.group({ phone: ['', Validators.required] });
+  constructor(private readonly fb: FormBuilder) {}
+  onCountry(e: { iso2: string }) { console.log('country:', e.iso2); }
 }
 ```
 
-**Result:** `form.get('phone')?.value` → `'+14155550123'` (E.164) when valid, or `null` while empty/invalid.
+**Value semantics**
+
+* Valid → control value is **E.164** string (e.g. `+14155550123`)
+* Empty/invalid → value is **`null`**; validator sets `{ phoneInvalid: true }`
 
 ---
 
-## Template-driven usage
+## Template‑driven
 
 ```html
 <form #f="ngForm">
   <ngxsmk-tel-input name="phone" [(ngModel)]="phone"></ngxsmk-tel-input>
 </form>
-
-<!-- phone is a string (E.164) or null -->
+<!-- phone is an E.164 string or null -->
 ```
 
 ---
@@ -125,171 +122,111 @@ export class AppComponent {
 
 ### Inputs
 
-| Name                 | Type                    | Default                | Description                                         |
-| -------------------- | ----------------------- | ---------------------- | --------------------------------------------------- |
-| `initialCountry`     | `CountryCode \| 'auto'` | `'auto'`               | Starting country. `'auto'` uses the plugin default. |
-| `preferredCountries` | `CountryCode[]`         | `['US','GB']`          | Pinned countries at the top.                        |
-| `onlyCountries`      | `CountryCode[]`         | `undefined`            | Restrict selectable countries.                      |
-| `nationalMode`       | `boolean`               | `false`                | If `true`, emits national numbers; otherwise E.164. |
-| `placeholder`        | `string`                | `'Enter phone number'` | Input placeholder.                                  |
-| `autocomplete`       | `string`                | `'tel'`                | Native autocomplete attribute.                      |
-| `disabled`           | `boolean`               | `false`                | Disables the input.                                 |
-
-> `CountryCode` is the ISO-2 uppercase code from `libphonenumber-js` (e.g., `US`, `GB`, `AU`).
+| Name                   | Type                                   | Default                | Description                                                  |
+| ---------------------- | -------------------------------------- | ---------------------- | ------------------------------------------------------------ |
+| `initialCountry`       | `CountryCode \| 'auto'`                | `'US'`                 | Starting country (`'auto'` uses a stubbed US by default).    |
+| `preferredCountries`   | `CountryCode[]`                        | `['US','GB']`          | Pinned at the top.                                           |
+| `onlyCountries`        | `CountryCode[]`                        | —                      | Limit selectable countries.                                  |
+| `nationalMode`         | `boolean`                              | `false`                | Display national format in the box; value still emits E.164. |
+| `separateDialCode`     | `boolean`                              | `false`                | Show dial code separately.                                   |
+| `allowDropdown`        | `boolean`                              | `true`                 | Enable/disable dropdown.                                     |
+| `placeholder`          | `string`                               | `'Enter phone number'` | Native placeholder.                                          |
+| `autocomplete`         | `string`                               | `'tel'`                | Native autocomplete.                                         |
+| `disabled`             | `boolean`                              | `false`                | Disable input.                                               |
+| `label`                | `string`                               | —                      | Label text.                                                  |
+| `hint`                 | `string`                               | —                      | Helper text.                                                 |
+| `errorText`            | `string`                               | —                      | Custom error text.                                           |
+| `size`                 | `'sm' \| 'md' \| 'lg'`                 | `'md'`                 | Sizing preset.                                               |
+| `variant`              | `'outline' \| 'filled' \| 'underline'` | `'outline'`            | Visual style.                                                |
+| `showClear`            | `boolean`                              | `true`                 | Show clear (×) button.                                       |
+| `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`                 | Only show error style after blur.                            |
+| `dropdownAttachToBody` | `boolean`                              | `true`                 | Append dropdown to `<body>` to avoid clipping.               |
+| `dropdownZIndex`       | `number`                               | `2000`                 | Z‑index for dropdown panel.                                  |
+
+> `CountryCode` is the ISO‑2 code from `libphonenumber-js` (e.g., `US`, `GB`).
 
 ### Outputs
 
-| Event           | Payload                 | Description                              |
-| --------------- | ----------------------- | ---------------------------------------- |
-| `countryChange` | `{ iso2: CountryCode }` | Fires when the selected country changes. |
-
-### Value semantics
-
-* **When valid:** emits **E.164** string (e.g., `+33123456789`) unless `nationalMode` is `true`.
-* **When empty or invalid:** emits `null`.
-* **Validation:** adds `phoneInvalid` error key when the input cannot be parsed as a valid number for the selected country.
+| Event            | Payload                                                    | Description                        |
+| ---------------- | ---------------------------------------------------------- | ---------------------------------- |
+| `countryChange`  | `{ iso2: CountryCode }`                                    | When the selected country changes. |
+| `validityChange` | `boolean`                                                  | Emits when validity toggles.       |
+| `inputChange`    | `{ raw: string; e164: string \| null; iso2: CountryCode }` | Emitted on each input.             |
 
----
-
-## Validation examples
-
-```html
-<ngxsmk-tel-input formControlName="phone"></ngxsmk-tel-input>
-
-<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>
-```
-
----
-
-## Accessibility
+### Public methods
 
-* Pair with a `<label for="phone">` or wrap the input and label together.
-* The country dropdown is keyboard navigable (via `intl-tel-input`).
-* Consider additional ARIA attributes if you customize the template.
+* `focus(): void`
+* `selectCountry(iso2: CountryCode): void`
 
 ---
 
 ## Theming
 
-The component applies a minimal class to the input: `.ngxsmk-tel-input`.
-You can style it or the `intl-tel-input` container globally:
+The component exposes CSS variables for easy theming. Example:
 
-```css
-.ngxsmk-tel-input {
-  width: 100%;
-  padding: 0.5rem 0.75rem;
-}
-
-.iti {
-  width: 100%; /* make dropdown stretch */
-}
+```html
+<ngxsmk-tel-input style="
+  --tel-border:#cbd5e1;
+  --tel-ring:#22c55e;
+  --tel-radius:14px;
+  --tel-dd-item-hover: rgba(34,197,94,.12);
+  --tel-dd-z: 3000;
+"></ngxsmk-tel-input>
 ```
 
----
+Key tokens:
 
-## SSR notes
+* 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`
 
-This library lazily imports `intl-tel-input` **only in the browser**.
-No special setup required for Angular Universal. If you still see SSR errors, ensure you’re not referencing `window` in your own wrappers.
+Dark mode: wrap in a `.dark` container – tokens adapt.
 
 ---
 
-## Troubleshooting
-
-* **No flags / broken images**
-  Ensure `angular.json` asset mapping is present and that the output path matches your app’s `/assets` directory.
-
-* **Styles not applied**
-  Add `"node_modules/intl-tel-input/build/css/intlTelInput.css"` to the `styles` array in `angular.json`.
+## SSR
 
-* **Form value doesn’t update**
-  Use Angular Forms APIs (Reactive or Template-driven). For Reactive Forms, confirm the control is bound via `formControlName` and that `ReactiveFormsModule` is imported.
-
-* **Always invalid**
-  Some numbers are only valid with the correct country selected. Try typing with the `+` international prefix or set `initialCountry` appropriately.
+* `intl-tel-input` is lazy‑loaded **only in the browser** using `isPlatformBrowser` guards.
+* No direct `window`/`document` usage on the server path.
 
 ---
 
-## Example: national mode
-
-```html
-<ngxsmk-tel-input formControlName="phone" [nationalMode]="true" [initialCountry]="'GB'"></ngxsmk-tel-input>
-<!-- Value will be a national format string like '020 7946 0958' with validation tied to the selected country -->
-```
+## Troubleshooting
 
-> When using `nationalMode=true`, you’ll typically store the country code alongside the value, using `(countryChange)`.
+* **Unstyled UI / bullets** → Add CSS + assets in `angular.json`, restart dev server.
+* **Flags missing** → Verify the images were copied to `/assets/intl-tel-input/img` or add the CSS override.
+* **`TS2307: Cannot find module 'ngxsmk-tel-input'`** → Build the lib first; or add a `paths` alias to your app’s `tsconfig` if consuming locally.
+* **Peer dependency conflict** → App Angular version must satisfy `>=17 <20`.
 
 ---
 
-## Development
-
-This repo is structured as an Angular workspace with a library:
+## Local dev & publish
 
 ```bash
 # Build the library
 ng build ngxsmk-tel-input
 
-# (Optional) create a demo app and try it locally
-ng g application demo
-# import TelInputComponent in your demo app and test
-```
-
----
-
-## Publish
+# Test via tarball in another app
+cd dist/ngxsmk-tel-input && npm pack
+# in your app
+npm i ../path-to/dist/ngxsmk-tel-input/ngxsmk-tel-input-<version>.tgz
 
-```bash
-# Bump version, then:
+# Publish (from the built dist folder)
+# bump version in projects/ngxsmk-tel-input/package.json
 ng build ngxsmk-tel-input
 cd dist/ngxsmk-tel-input
 npm publish --access public
 ```
 
-> Ensure `peerDependencies` in the library’s `package.json` reflect your Angular support range.
-
----
-
-## Contributing
-
-PRs welcome! Please:
-
-1. Run `npm ci` and `ng build`.
-2. Add/adjust unit or e2e tests if you change behavior.
-3. Update this README for any API changes.
-
 ---
 
 ## License
 
 [MIT](./LICENSE)
 
----
-
 ## 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)
-
----
-
-### Appendix: `angular.json` snippet (copy-paste)
-
-```jsonc
-{
-  "styles": [
-    "node_modules/intl-tel-input/build/css/intlTelInput.css"
-  ],
-  "assets": [
-    {
-      "glob": "**/*",
-      "input": "node_modules/intl-tel-input/build/img",
-      "output": "assets/intl-tel-input/img"
-    }
-  ]
-}
-```
+* UI: `intl-tel-input`
+* Parsing/validation: `libphonenumber-js`