Fix initialCountry behavior for empty phone values and expose missing input typings (#84)

This PR addresses the behavior reported in Discussion #83 where
`initialCountry` was not applied when the form control value is an empty
string (`''`), causing the US flag to appear by default in first-render
scenarios. It also aligns public typings so documented inputs (e.g.
`formatOnBlur`) are recognized correctly.

## Context

In Angular form-first flows (initial value = `''`), consumers could not
reliably set the initial country via `[initialCountry]` or early
`selectCountry(...)` calls. Some users also reported missing input
typings in installed package definitions.

## What this PR changes

- Ensures `initialCountry` is respected when the bound phone value is
empty.
- Avoids transient UI artifacts (like brief duplicate dial code render)
when initializing country state.
- Aligns exported typings with supported component inputs (including
`formatOnBlur` if supported in this version).
- Keeps existing behavior unchanged for non-empty initial values and
explicit E.164 values.

## Why

- Fixes first-render country mismatch for empty values.
- Improves migration experience for teams moving from other telephone
input libraries.
- Reduces confusion caused by documentation vs typings mismatch.

## Validation

- Verified empty initial form value (`''`) with
`[initialCountry]="'AR'"` correctly shows the AR flag on first render.
- Verified no dial-code flicker/double-render during initial mount.
- Verified typings expose expected inputs in Angular templates.
- Confirmed no regressions for existing valid-number initialization
paths.

## Related discussion

- [Setting initialCountry in an empty phone ('') scenario · Discussion
#83](#83)

Author: toozuuu

.github/workflows/deploy-demo.yml

@@ -0,0 +1,61 @@
+name: Deploy Demo to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  workflow_dispatch: # Allows manual triggering
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build library
+        run: npx ng build ngxsmk-tel-input --configuration production
+
+      - name: Build demo
+        run: |
+          REPO_NAME=${GITHUB_REPOSITORY#*/}
+          npx ng build demo --configuration production --base-href /$REPO_NAME/
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './dist/demo/browser'
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+

CHANGELOG.md

@@ -7,7 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.10] - 2026-01-19
+
 ### Changed
+- **Dependencies**: Updated `intl-tel-input` to version 25 compatibility.
+- **Internal**: Migrated `preferredCountries` to `countryOrder` to support `intl-tel-input` v25.
 - **Example Components**: All example components (E-commerce Checkout, User Registration, Profile Management) now default to dark mode theme
 - **Demo App**: Default theme changed to dark mode for better visibility and consistency
 - **Navigation UI**: Fixed icon and text colors in dark mode navigation menu for better contrast and readability

CONTRIBUTING.md

@@ -6,15 +6,15 @@ By participating in this project, you are expected to uphold the project's goals
 
 ---
 
-## 💡 How to Contribute
+##  How to Contribute
 
 There are several ways you can help improve this project:
 
 1.  **Report Bugs:** Submit an issue if you find a problem.
 2.  **Suggest Features:** Open an issue to propose new functionality.
 3.  **Contribute Code:** Submit a Pull Request with bug fixes or new features.
 
-## 🐛 Reporting Bugs
+##  Reporting Bugs
 
 If you find a bug, please check the [Issues page](https://github.com/toozuuu/ngxsmk-tel-input/issues) to see if it has already been reported.
 
@@ -24,13 +24,13 @@ When submitting a new bug report, please include:
 * Your **Angular version** and the **browser** you are using.
 * A minimal reproduction link (e.g., CodePen, JSFiddle) if possible.
 
-## ✨ Suggesting Enhancements
+##  Suggesting Enhancements
 
 If you have an idea for a new feature or an enhancement, please open a new issue on the [Issues page](https://github.com/toozuuu/ngxsmk-tel-input/issues).
 
 Describe the feature, why you think it would be useful, and how it aligns with the goals of the library.
 
-## 💻 Code Contributions (Pull Requests)
+##  Code Contributions (Pull Requests)
 
 We welcome pull requests for bug fixes and new features.
 

DEPLOYMENT.md

@@ -0,0 +1,95 @@
+# Deployment Guide
+
+This guide explains how to deploy the demo application to GitHub Pages using GitHub Actions.
+
+## Prerequisites
+
+1. GitHub repository with GitHub Pages enabled
+2. GitHub Actions enabled in your repository
+
+## Setup GitHub Pages
+
+1. Go to your repository **Settings** → **Pages**
+2. Under **Source**, select **GitHub Actions**
+3. Save the settings
+
+## Automatic Deployment
+
+The demo is automatically deployed when you push to the `main` or `master` branch.
+
+### Workflow File
+
+The deployment workflow is located at `.github/workflows/deploy-demo.yml`
+
+### Manual Deployment
+
+You can also trigger the deployment manually:
+
+1. Go to **Actions** tab in your repository
+2. Select **Deploy Demo to GitHub Pages**
+3. Click **Run workflow**
+4. Select the branch and click **Run workflow**
+
+## Build Configuration
+
+The workflow:
+1. Installs dependencies
+2. Builds the library (`ngxsmk-tel-input`)
+3. Builds the demo application with the correct `base-href`
+4. Deploys to GitHub Pages
+
+### Base Href
+
+The `base-href` is automatically set based on your repository name:
+- Repository: `owner/ngxsmk-tel-input` → Base href: `/ngxsmk-tel-input/`
+
+If your repository name is different, update the workflow file:
+```yaml
+--base-href /your-repo-name/
+```
+
+## Custom Domain
+
+If you're using a custom domain:
+
+1. Update the `base-href` in the workflow to `/`
+2. Configure your custom domain in **Settings** → **Pages** → **Custom domain**
+
+## Troubleshooting
+
+### Build Fails
+
+- Check Node.js version (should be 20)
+- Verify all dependencies are in `package.json`
+- Check build logs in GitHub Actions
+
+### Pages Not Updating
+
+- Ensure GitHub Pages is set to use **GitHub Actions** as source
+- Check workflow run status in **Actions** tab
+- Verify the deployment job completed successfully
+
+### 404 Errors
+
+- Verify the `base-href` matches your repository name
+- Check that routes are configured correctly in Angular
+- Ensure `index.html` has the correct `<base href>` tag
+
+## Local Testing
+
+Test the production build locally:
+
+```bash
+# Build with production config
+npm run build:demo
+
+# Serve the built files (requires a local server)
+npx http-server dist/demo/browser -p 4200
+```
+
+Visit `http://localhost:4200` to verify the build works correctly.
+
+## Environment Variables
+
+No environment variables are required for basic deployment. If you need to add environment-specific configurations, add them to the workflow file.
+

README.md

@@ -1,56 +1,65 @@
 # 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**: 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
 * Nice UX options: label/hint/error text, sizes, variants, clear button, autofocus, select-on-focus
 * 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**
 
 > Library `peerDependencies` target Angular `>=17`. Fully compatible with Angular 17, 18, 19, 20, 21, and future versions.
 
-### 🔄 Zone.js Compatibility
+###  Zone.js Compatibility
 
 This component works seamlessly with **both Zone.js and zoneless Angular**:
 
-* ✅ **With Zone.js** (traditional Angular): Full compatibility
-* ✅ **Without Zone.js** (Angular 18+ zoneless): Full compatibility
-* ✅ **All data binding types**: Property bindings, event bindings, two-way bindings
-* ✅ **Reactive Forms & Template-driven Forms**: Full support
-* ✅ **Signals**: Compatible with Angular signals (Angular 16+)
+*  **With Zone.js** (traditional Angular): Full compatibility
+*  **Without Zone.js** (Angular 18+ zoneless): Full compatibility
+*  **All data binding types**: Property bindings, event bindings, two-way bindings
+*  **Reactive Forms & Template-driven Forms**: Full support
+*  **Signals**: Compatible with Angular signals (Angular 16+)
 
 The component automatically detects whether Zone.js is available and adapts its change detection strategy accordingly.
 
 ---
 
-## 📦 Install
+##  Install
 
 ```bash
 npm i ngxsmk-tel-input intl-tel-input libphonenumber-js
@@ -110,7 +119,7 @@ Ensure your app includes a proper viewport meta tag:
 
 ---
 
-## 🚀 Quick start (Reactive Forms)
+##  Quick start (Reactive Forms)
 
 ```ts
 // app.component.ts
@@ -171,7 +180,7 @@ export class AppComponent {
 
 ---
 
-## 📝 Template‑driven usage
+##  Template‑driven usage
 
 ```html
 <form #f="ngForm">
@@ -182,7 +191,7 @@ export class AppComponent {
 
 ---
 
-## 🈺 Localization & RTL
+##  Localization & RTL
 
 You can localize the dropdown/search labels and override country names.
 
@@ -232,7 +241,7 @@ Arabic + RTL example
 ```
 
 
-## ⚙️ API
+## ️ API
 
 ### Inputs
 
@@ -278,15 +287,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.
 
@@ -299,7 +311,7 @@ For rare patterns not covered by libphonenumber-js, the control falls back to ra
 ---
 
 
-## 🎨 Theming
+##  Theming
 
 ### CSS Variables
 
@@ -353,7 +365,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>
@@ -389,14 +401,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.
 
@@ -417,7 +429,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.
@@ -436,13 +448,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