svelte-tel-input 4.0.0-next.0 → 4.0.0-next.2

package/README.md

@@ -19,7 +19,7 @@ Parse, format, and validate international phone numbers — store in [E.164](htt
 - **E.164 storage** — one canonical format, always searchable and SMS-ready
 - **Auto-detect country** from dial code (`+44` → `GB`)
 - **Smart formatting** — international display with cursor position preservation
-- **Validation** — powered by [libphonenumber-js](https://gitlab.com/catamphetamine/libphonenumber-js), with granular error types
+- **Validation** — powered with granular error types
 - **Auto placeholder** — country-specific example numbers
 - **Allowed countries** — restrict to a subset of country codes
 - **Lock country** — prevent country switching via dial codes
@@ -88,3 +88,7 @@ Full API reference, options, events, types, and examples are on the **[documenta
 ## License
 
 [MIT](LICENSE.md)
+
+## Acknowledgements
+
+Phone number parsing and validation is powered by [libphonenumber-js](https://gitlab.com/catamphetamine/libphonenumber-js) by [catamphetamine](https://gitlab.com/catamphetamine) and its contributors. This project wouldn't be possible without their work. Thank you for their work.

package/dist/components/input/TelInput.svelte

@@ -103,11 +103,10 @@
 		}
 	});
 
-	/**
-	 * Compute the initial formatted display value synchronously.
-	 * Runs on both server and client at initialization time, so SSR renders the
-	 * formatted number and the client's first render matches — no hydration mismatch.
-	 */
+	// Compute the initial formatted display value synchronously.
+	// Runs on both server and client at initialization time, so SSR renders the
+	// formatted number and the client's first render matches — no hydration mismatch.
+
 	const computeInitialDisplayValue = (): string => {
 		if (!value) return '';
 		let effectiveCountryIso2: CountryCode | null = null;
@@ -139,18 +138,16 @@
 		if (prevCountry === undefined) prevCountry = country;
 	});
 
-	/**
-	 * Shadow trackers — record every value this component writes internally so the
-	 * external-change watchers below can distinguish "we set it" vs "parent set it".
-	 * Plain let (not $state) because they are only ever read inside untrack(), never
-	 * as reactive dependencies.
-	 * Initialized to the incoming prop values so the first render never false-fires.
-	 */
+	//Shadow trackers — record every value this component writes internally so the
+	//external-change watchers below can distinguish "we set it" vs "parent set it".
+	//Plain let (not $state) because they are only ever read inside untrack(), never
+	//as reactive dependencies.
+	//Initialized to the incoming prop values so the first render never false-fires.
 	let _lastWrittenValue: string = value;
 	let _lastWrittenCountry: CountryCode | null | undefined = untrack(() => country);
 	// let isInitialized = $state(false);
 
-	/** Merge options into default opts, to be able to set just one config option. */
+	// Merge options into default opts, to be able to set just one config option.
 	const combinedOptions = $derived({
 		...defaultOptions,
 		...options
@@ -168,9 +165,9 @@
 	): ValidationError => {
 		const allowed = combinedOptions.allowedCountries;
 		if (allowed?.length && resolvedCountry != null && !allowed.includes(resolvedCountry)) {
-			return 'country_not_allowed';
+			return 'COUNTRY_NOT_ALLOWED';
 		}
-		if (isEmpty) return required ? 'required' : null;
+		if (isEmpty) return required ? 'REQUIRED' : null;
 		if (parseValid) return null;
 		// Use the granular error from detailedValue when available
 		return detailedValue?.validationError ?? 'INVALID';
@@ -287,6 +284,11 @@
 			numberHasCountry.iso2 !== prevCountry
 		) {
 			countryUpdater(numberHasCountry.iso2);
+			// Keep prevCountry in sync so that a subsequent external country change
+			// (e.g. parent sets country='DE' again) is correctly detected as a change
+			// and triggers a value reset. Without this, prevCountry would still hold
+			// the last externally-written value and the reset guard would short-circuit.
+			prevCountry = numberHasCountry.iso2;
 			// Fire the callback only here — when the country is inferred from the
 			// user's input (dial-code parsing). reset() and external prop changes
 			// do NOT fire onCountryChange.
@@ -306,13 +308,35 @@
 			detailedValue = parsePhoneInput(rawInput, normalizerCountry);
 		} catch (err) {
 			if (err instanceof ParseError) {
-				detailedValue = { isValid: false, validationError: err.message as ValidationError };
+				detailedValue = {
+					isPhoneValid: false,
+					isValid: false,
+					validationError: err.message as ValidationError
+				};
 				onError?.(err.message);
 			} else {
 				throw err;
 			}
 		}
 
+		// If the resolved country is not in allowedCountries, the phone number is
+		// intrinsically valid (libphonenumber-js says so) but the application rejects
+		// it. Patch detailedValue to reflect this so that detailedValue.isValid is
+		// consistent with the component's `valid` prop and `validationError`.
+		const _allowedCountries = combinedOptions.allowedCountries;
+		if (
+			detailedValue &&
+			_allowedCountries?.length &&
+			detailedValue.countryCode != null &&
+			!_allowedCountries.includes(detailedValue.countryCode)
+		) {
+			detailedValue = {
+				...detailedValue,
+				isValid: false,
+				validationError: 'COUNTRY_NOT_ALLOWED'
+			};
+		}
+
 		// `inputValue` is the displayed value (must stay in sync with the directive's formatting).
 		inputValue = combinedOptions.spaces
 			? (detailedValue?.formattedNumber ?? rawInput)
@@ -351,11 +375,9 @@
 		});
 	});
 
-	/**
-	 * Detect externally driven value changes (e.g. parent sets bind:value, or resets to null).
-	 * The shadow `_lastWrittenValue` is stamped on every internal write inside
-	 * handleParsePhoneNumber, so any difference here means the parent changed it.
-	 */
+	//Detect externally driven value changes (e.g. parent sets bind:value, or resets to null).
+	//The shadow `_lastWrittenValue` is stamped on every internal write inside
+	//handleParsePhoneNumber, so any difference here means the parent changed it.
 	$effect(() => {
 		const currentValue = value;
 		untrack(() => {
@@ -365,11 +387,9 @@
 		});
 	});
 
-	/**
-	 * Detect externally driven country changes (e.g. parent's <select bind:value={country}>).
-	 * Stamps `_lastWrittenCountry` eagerly so the watcher doesn't re-fire when
-	 * handleParsePhoneNumber later writes country through countryUpdater.
-	 */
+	// Detect externally driven country changes (e.g. parent's <select bind:value={country}>).
+	// Stamps `_lastWrittenCountry` eagerly so the watcher doesn't re-fire when
+	// handleParsePhoneNumber later writes country through countryUpdater.
 	$effect(() => {
 		const currentCountry = country;
 		untrack(() => {
@@ -398,6 +418,13 @@
 		onLoad?.();
 	});
 
+	/**
+	 * Resets the input value and validation state.
+	 *
+	 * @param {Object} [options] - Optional settings.
+	 * @param {boolean} [options.country=false] - If true, resets the country to null; otherwise, resets to defaultCountry.
+	 * @returns {void}
+	 */
 	const reset = ({ country: resetCountry = false }: { country?: boolean } = {}) => {
 		const targetCountry = resetCountry ? null : (defaultCountry ?? null);
 		applyValidity(true, false, targetCountry);
@@ -411,6 +438,11 @@
 		onValueChange?.('', null);
 	};
 
+	/**
+	 * Checks the validity of the current input value and updates validation state.
+	 *
+	 * @returns {{ valid: boolean; error: ValidationError }} - The validity status and error type.
+	 */
 	const checkValidity = (): { valid: boolean; error: ValidationError } => {
 		if (inputValue === '') {
 			applyValidity(true, false, country);

package/dist/types/index.d.ts

@@ -16,6 +16,17 @@ export interface Country {
 export interface DetailedValue {
 	countryCode?: CountryCode | null;
 	isPossible: boolean;
+	/**
+	 * Whether the phone number itself is valid according to libphonenumber-js,
+	 * regardless of any application-level constraints (e.g. `allowedCountries`).
+	 * Use `isValid` as the source of truth for overall form validity.
+	 */
+	isPhoneValid: boolean;
+	/**
+	 * Overall validity: `true` only when the number is valid **and** all
+	 * component-level constraints (e.g. `allowedCountries`) are satisfied.
+	 * This is the field you should check in your application logic.
+	 */
 	isValid: boolean;
 	phoneNumber: string | null;
 	countryCallingCode: string | null;
@@ -32,8 +43,8 @@ export interface DetailedValue {
 
 /**
  * The reason the current phone number input is invalid.
- * - `'required'` — field is empty and `required` is `true`
- * - `'country_not_allowed'` — the resolved country is not in `options.allowedCountries`
+ * - `'REQUIRED'` — field is empty and `required` is `true`
+ * - `'COUNTRY_NOT_ALLOWED'` — the resolved country is not in `options.allowedCountries`
  * - `'TOO_SHORT'` — number has too few digits
  * - `'TOO_LONG'` — number has too many digits
  * - `'NOT_A_NUMBER'` — input does not look like a phone number at all
@@ -43,8 +54,8 @@ export interface DetailedValue {
  * - `null` — no error (input is valid)
  */
 export type ValidationError =
-	| 'required'
-	| 'country_not_allowed'
+	| 'REQUIRED'
+	| 'COUNTRY_NOT_ALLOWED'
 	| 'TOO_SHORT'
 	| 'TOO_LONG'
 	| 'NOT_A_NUMBER'
@@ -88,6 +99,9 @@ export interface TelInputOptions {
 }
 
 export interface Props extends HTMLInputAttributes {
+	/**
+	 * Autocomplete attribute for autofill hints (e.g. 'tel', 'tel-national').
+	 */
 	autocomplete?: AutoFill | null;
 	/** You can set the classes of the input field*/
 	class?: string;
@@ -124,10 +138,31 @@ export interface Props extends HTMLInputAttributes {
 	options?: TelInputOptions;
 	/** Binding to the underlying `<input>` element */
 	el?: HTMLInputElement | undefined;
+	/**
+	 * Callback fired when the country changes (auto-detected or user-selected).
+	 * @param newCountry The new country code or null.
+	 */
 	onCountryChange?: (newCountry: CountryCode | null) => void;
+	/**
+	 * Callback fired when validity changes.
+	 * @param newValidity The new validity state.
+	 * @param error The validation error type.
+	 */
 	onValidityChange?: (newValidity: boolean, error: ValidationError) => void;
+	/**
+	 * Callback fired when the value or details change.
+	 * @param newValue The new E164 value.
+	 * @param newDetails The new detailed value object.
+	 */
 	onValueChange?: (newValue: string, newDetails: Readonly<Partial<DetailedValue> | null>) => void;
+	/**
+	 * Callback fired on parse or validation errors.
+	 * @param error The error message.
+	 */
 	onError?: (error: string) => void;
+	/**
+	 * Callback fired after component initialization.
+	 */
 	onLoad?: () => void;
 }
 

package/dist/utils/helpers.js

@@ -220,6 +220,7 @@ export const parsePhoneInput = (input, country) => {
             : null,
         formattedNumber,
         isPossible: asYouType.isPossible(),
+        isPhoneValid: isValid,
         isValid,
         nationalNumber,
         phoneNumber,

package/dist/validators/index.js

@@ -32,7 +32,7 @@ import { parse } from '../utils/helpers.js';
 export function validateTelInput(value, options = {}) {
     const { required = false, allowedCountries, country } = options;
     if (!value)
-        return required ? 'required' : null;
+        return required ? 'REQUIRED' : null;
     const result = parse(value, country ?? null);
     if (!result.isValid)
         return result.validationError ?? 'INVALID';
@@ -40,7 +40,7 @@ export function validateTelInput(value, options = {}) {
         allowedCountries.length &&
         result.countryCode != null &&
         !allowedCountries.includes(result.countryCode)) {
-        return 'country_not_allowed';
+        return 'COUNTRY_NOT_ALLOWED';
     }
     return null;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "svelte-tel-input",
   "description": "svelte-tel-input",
-  "version": "4.0.0-next.0",
+  "version": "4.0.0-next.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/gyurielf/svelte-tel-input.git"
@@ -34,7 +34,7 @@
   },
   "devDependencies": {
     "@sveltejs/adapter-auto": "7.0.1",
-    "@sveltejs/kit": "^2.53.4",
+    "@sveltejs/kit": "^2.55.0",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.4",
     "@tailwindcss/vite": "^4.2.1",
@@ -43,19 +43,19 @@
     "@testing-library/user-event": "^14.6.1",
     "@types/micromatch": "^4.0.10",
     "dotenv": "^17.3.1",
-    "jsdom": "^28.1.0",
+    "jsdom": "^29.0.0",
     "micromatch": "^4.0.8",
     "postcss": "^8.5.8",
     "publint": "^0.3.18",
-    "svelte": "^5.53.11",
+    "svelte": "^5.54.0",
     "svelte-check": "^4.4.5",
     "svelte2tsx": "^0.7.52",
     "tailwindcss": "^4.2.1",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
-    "valibot": "^1.2.0",
+    "valibot": "^1.3.0",
     "vite": "^7.3.1",
-    "vitest": "^4.0.18",
+    "vitest": "^4.1.0",
     "zod": "^4.3.6"
   },
   "type": "module",