@alikhalilll/a-tel-input 1.0.2 → 1.1.1

package/src/types.ts

@@ -6,9 +6,12 @@ import type {
   PhoneValidationReason,
   PhoneValidationResult,
 } from './composables/usePhoneValidation';
+import type { ATelInputValidateOn } from './composables/useTelInputValidation';
 import type { FlagUrlBuilder } from './utils/flag-url';
 import type { Size } from '@alikhalilll/a-ui-base';
 
+export type { ATelInputValidateOn } from './composables/useTelInputValidation';
+
 /** Alias for the shared `Size` scale — kept for backwards-friendly naming. */
 export type ATelInputSize = Size;
 
@@ -61,6 +64,48 @@ export type TelInputMessagesInput = Partial<Omit<TelInputMessages, 'errorMessage
 
 export interface ATelInputProps {
   class?: HTMLAttributes['class'];
+  /**
+   * Default `v-model` — the canonical **E.164** string (e.g. `'+201066105963'`).
+   *
+   * Reads + writes the full international number as a single value. Designed to drop
+   * straight into VeeValidate's `<Field v-slot="{ field }">` pattern (use
+   * `v-bind="field"`), native `<form>` submission, or any `v-model="phoneE164"` consumer.
+   *
+   * Stays in sync with the split `v-model:phone` + `v-model:country` contract — use
+   * either, or both.
+   */
+  modelValue?: string;
+  /**
+   * Forwarded to the inner `<input name="">`. Set this when participating in a native
+   * `<form>` submission, or when a form library (VeeValidate, etc.) wants a stable name.
+   */
+  name?: string;
+  /**
+   * Externally controlled error message. When set to a non-empty string the component
+   * is forced into the error visual state and renders this message via the `#error`
+   * slot — overriding internal libphonenumber validation. Wire this from VeeValidate,
+   * Zod, an async server check ("this phone is already registered"), or any custom
+   * validation layer.
+   *
+   * Pass `null` / `undefined` / `''` to defer to internal validation.
+   */
+  error?: string | null;
+  /**
+   * `true` while an async validation is in flight (e.g. a server-side uniqueness
+   * check). Renders a small spinner inside the field and sets `aria-busy="true"` on
+   * the input. Does **not** disable the field — use `loading` for that. Replace the
+   * spinner via the `#validating` slot.
+   *
+   * Designed to be bound to the `validating` ref returned by `useTelField()`.
+   */
+  validating?: boolean;
+  /**
+   * When to surface validation in the UI.
+   * - `'change'` (default) — visible state mirrors the typing-paused state.
+   * - `'blur'` — stays idle until the input has been blurred once (form-library friendly).
+   * - `'eager'` — mirror raw validation immediately, no typing pause.
+   */
+  validateOn?: ATelInputValidateOn;
   placeholder?: string;
   disabled?: boolean;
   loading?: boolean;
@@ -284,18 +329,53 @@ export interface ATelInputSlots {
   empty?: (props: { query: string }) => unknown;
   /** Replace the spinner shown in the picker slot during the debounce window. */
   detecting?: () => unknown;
+  /** Replace the spinner shown inside the field while async validation is in flight. */
+  validating?: () => unknown;
 }
 
 /**
  * Emit map for {@link ATelInput}. `update:phone` carries the digits-only string,
  * `update:country` carries the dial-number (not ISO2). Surface for consumers who
  * wire the events manually instead of via `v-model:phone` / `v-model:country`.
+ *
+ * `blur` / `focus` mirror the inner input's native events — useful for form
+ * libraries (VeeValidate's `handleBlur`, etc.).
  */
 export type ATelInputEmits = {
+  'update:modelValue': [value: string];
   'update:phone': [value: string];
   'update:country': [value: number | null];
+  blur: [event: FocusEvent];
+  focus: [event: FocusEvent];
 };
 
+/**
+ * Imperative API exposed by {@link ATelInput} via `defineExpose`. Grab it with
+ * `ref="tellRef"` + `tellRef.value?.focus()` — useful for form libraries that want
+ * to focus the offending field after a failed submit.
+ */
+export interface ATelInputExpose {
+  /** Full {@link PhoneValidationResult} for the current input. */
+  validation: import('vue').ComputedRef<PhoneValidationResult>;
+  /** Format hint + example for the currently selected country, or `null`. */
+  required: import('vue').ComputedRef<unknown>;
+  /** Selected country's dial code as a `+`-prefixed string (e.g. `+20`), or `null`. */
+  selectedDialCode: import('vue').ComputedRef<string | null>;
+  /** Raw validation state — not gated by typing pause / blur / `showValidation`. */
+  validationState: import('vue').ComputedRef<'idle' | 'valid' | 'error'>;
+  /** Surfacing-gated validation state — the one the UI actually displays. */
+  visibleValidationState: import('vue').ComputedRef<'idle' | 'valid' | 'error'>;
+  isDetecting: Readonly<import('vue').Ref<boolean>>;
+  hasFinishedTyping: Readonly<import('vue').Ref<boolean>>;
+  detectionAttempted: Readonly<import('vue').Ref<boolean>>;
+  /** Programmatically focus the inner `<input>`. */
+  focus(options?: FocusOptions): void;
+  /** Programmatically blur the inner `<input>`. */
+  blur(): void;
+  /** Programmatically select the inner `<input>`'s text. */
+  select(): void;
+}
+
 /**
  * Props for {@link ACountrySelect} — the standalone country picker. Surface
  * separately so it can be used outside `ATelInput` with full type support.

package/src/vee-validate/index.ts

@@ -0,0 +1,2 @@
+export { useTelField } from './useTelField';
+export type { UseTelFieldOptions, UseTelFieldReturn } from './useTelField';

package/src/vee-validate/useTelField.ts

@@ -0,0 +1,202 @@
+/**
+ * VeeValidate adapter for `@alikhalilll/a-tel-input`.
+ *
+ * `useTelField()` owns the two v-models (`phone` + `country`) and the canonical
+ * E.164 string used by VeeValidate / Zod / yup, and returns a single ready-to-bind
+ * object so a consumer doesn't have to glue the pieces together.
+ *
+ * Quick start:
+ *
+ * ```ts
+ * import { useTelField } from '@alikhalilll/a-tel-input/vee-validate';
+ * import { toTypedSchema } from '@vee-validate/zod';
+ * import { z } from 'zod';
+ * import { zPhone } from '@alikhalilll/a-tel-input/zod';
+ *
+ * const { phone, country, error, handleBlur, fieldProps } = useTelField('phone', {
+ *   rules: toTypedSchema(zPhone()),
+ *   validateOn: 'blur',
+ * });
+ * ```
+ *
+ * ```vue
+ * <ATelInput
+ *   v-model:phone="phone"
+ *   v-model:country="country"
+ *   v-bind="fieldProps"
+ *   @blur="handleBlur"
+ * />
+ * ```
+ *
+ * Server-side validation (e.g. "does this phone already exist?") plugs in via the
+ * `rules` callback — VeeValidate already supports async rules:
+ *
+ * ```ts
+ * const { phone, country, error, handleBlur, fieldProps, validating } = useTelField('phone', {
+ *   rules: async (value: string) => {
+ *     const sync = await zPhone().safeParseAsync(value);
+ *     if (!sync.success) return sync.error.issues[0]!.message;
+ *     const res = await $fetch('/api/phone/exists', { query: { phone: value } });
+ *     return res.exists ? 'This phone is already registered.' : true;
+ *   },
+ *   validateOn: 'blur',
+ * });
+ * ```
+ *
+ * The `validating` ref is `true` while VeeValidate's async pipeline is in flight —
+ * bind it to ATelInput's `:validating` prop to surface a spinner inside the field.
+ *
+ * `vee-validate` is an **optional peer dependency** — install it yourself in your app.
+ */
+
+import { computed, ref, watch, type ComputedRef, type MaybeRefOrGetter } from 'vue';
+import { toValue } from 'vue';
+import { useField, type FieldOptions, type RuleExpression } from 'vee-validate';
+import { usePhoneValidation } from '../composables/usePhoneValidation';
+import type { ATelInputValidateOn } from '../composables/useTelInputValidation';
+
+export interface UseTelFieldOptions {
+  /**
+   * VeeValidate rules — a function, schema, or string. Use when the field stands
+   * alone (no `useForm` / no form-level `validationSchema`).
+   *
+   * **Important**: vee-validate **ignores field-level `rules` whenever the parent
+   * `useForm` is configured with `validationSchema`**. If you need async / server-
+   * side validation inside a form, chain it onto the form schema via
+   * `z.refine(async)` instead — that's what `handleSubmit` actually awaits and what
+   * drives this composable's `validating` ref (via `meta.pending`). See the README
+   * section "Server-side validation" for the full pattern.
+   */
+  rules?: RuleExpression<string>;
+  /**
+   * Initial digits-only national number, e.g. `'1066105963'`. Defaults to `''`.
+   */
+  initialPhone?: string;
+  /**
+   * Initial dial-digit number, e.g. `20` for Egypt. Defaults to `null`.
+   */
+  initialCountry?: number | null;
+  /**
+   * Default country (ISO2 like `'EG'` or dial code like `'20'`). Forwarded as the
+   * `defaultCountry` prop on `<ATelInput>` via `fieldProps`.
+   */
+  defaultCountry?: string;
+  /**
+   * When to surface validation in the UI. Defaults to `'blur'` (the typical form-library
+   * UX). Forwarded as the `validateOn` prop on `<ATelInput>` via `fieldProps`.
+   */
+  validateOn?: ATelInputValidateOn;
+  /**
+   * Forwarded to `useField` — extra options passed verbatim to VeeValidate. Use to
+   * configure `keepValueOnUnmount`, `syncVModel`, etc.
+   */
+  fieldOptions?: Omit<FieldOptions<string>, 'initialValue'>;
+}
+
+export interface UseTelFieldReturn {
+  /** `v-model:phone` source — digits-only national number. Bind to `<ATelInput>`. */
+  phone: import('vue').Ref<string>;
+  /** `v-model:country` source — dial-digit number (e.g., `20`). Bind to `<ATelInput>`. */
+  country: import('vue').Ref<number | null>;
+  /** The canonical E.164 string fed to VeeValidate's schema (read-only). */
+  e164: ComputedRef<string>;
+  /** Current validation error message, or `undefined` when valid. From `useField`. */
+  error: import('vue').Ref<string | undefined>;
+  /** `true` while VeeValidate is running an async rule (e.g. server-side check). */
+  validating: ComputedRef<boolean>;
+  /** Whether the field has been blurred / dirtied / submitted (from VeeValidate `meta`). */
+  meta: ReturnType<typeof useField<string>>['meta'];
+  /** Forward this to `<ATelInput @blur="handleBlur">` so VeeValidate's blur trigger fires. */
+  handleBlur: ReturnType<typeof useField<string>>['handleBlur'];
+  /** Imperatively trigger validation (e.g., after a programmatic value change). */
+  validate: ReturnType<typeof useField<string>>['validate'];
+  /** Imperatively set the error message — useful for server errors not raised by `rules`. */
+  setErrors: ReturnType<typeof useField<string>>['setErrors'];
+  /** Reset the field to its initial state. */
+  resetField: ReturnType<typeof useField<string>>['resetField'];
+  /**
+   * Ready-to-bind prop bag for `<ATelInput v-bind="fieldProps">`. Carries `name`,
+   * `error`, `validateOn`, `validating`, and `defaultCountry`.
+   */
+  fieldProps: ComputedRef<{
+    name: string;
+    error: string | null;
+    validateOn: ATelInputValidateOn;
+    validating: boolean;
+    defaultCountry?: string;
+  }>;
+}
+
+/**
+ * Register a phone field with VeeValidate. See file header for usage examples.
+ *
+ * @param name  The field name (used by VeeValidate, also forwarded to the inner
+ *              `<input name="">` for native form submission).
+ * @param options See {@link UseTelFieldOptions}.
+ */
+export function useTelField(
+  name: MaybeRefOrGetter<string>,
+  options: UseTelFieldOptions = {}
+): UseTelFieldReturn {
+  const phone = ref<string>(options.initialPhone ?? '');
+  const country = ref<number | null>(options.initialCountry ?? null);
+
+  const v = usePhoneValidation();
+  void v.getCountries();
+
+  // Compose E.164 from the two v-models — this is the canonical value VeeValidate
+  // tracks. NANP (`+1`) resolves to `'US'` for validation; libphonenumber-js applies
+  // the same rule set to every NANP country so this is correct.
+  function composeE164(): string {
+    if (!phone.value) return '';
+    const dial = country.value;
+    if (dial == null) return '';
+    const matches = v.getCountriesByDial(String(dial));
+    const iso2 = matches[0]?.value;
+    if (!iso2) return '';
+    const res = v.validate({ country: { iso2 }, phone: phone.value });
+    return res.full_phone ?? '';
+  }
+
+  const initialValue = composeE164();
+
+  const field = useField<string>(name, options.rules, {
+    initialValue,
+    // Don't run rules on every keystroke — let validateOn drive when validation fires.
+    validateOnValueUpdate: false,
+    ...options.fieldOptions,
+  });
+
+  // Keep VeeValidate's value in sync with the two v-models.
+  watch(
+    [phone, country],
+    () => {
+      field.value.value = composeE164();
+    },
+    { flush: 'post' }
+  );
+
+  const validating = computed(() => !!field.meta.pending);
+
+  const fieldProps = computed(() => ({
+    name: toValue(name),
+    error: (field.errorMessage.value ?? null) as string | null,
+    validateOn: options.validateOn ?? ('blur' as ATelInputValidateOn),
+    validating: validating.value,
+    defaultCountry: options.defaultCountry,
+  }));
+
+  return {
+    phone,
+    country,
+    e164: computed(() => field.value.value ?? ''),
+    error: field.errorMessage,
+    validating,
+    meta: field.meta,
+    handleBlur: field.handleBlur,
+    validate: field.validate,
+    setErrors: field.setErrors,
+    resetField: field.resetField,
+    fieldProps,
+  };
+}

package/src/zod/index.ts

@@ -0,0 +1,259 @@
+/**
+ * Zod adapter for `@alikhalilll/a-tel-input`.
+ *
+ * Wraps the same `usePhoneValidation()` engine the component uses, so a Zod schema
+ * never disagrees with the visual validation state in the field.
+ *
+ * Three usage shapes, all backed by libphonenumber-js:
+ *
+ * 1. **E.164 string** (default) — validate a full international number:
+ *
+ *    ```ts
+ *    import { zPhone } from '@alikhalilll/a-tel-input/zod';
+ *    const schema = z.object({ phone: zPhone() });
+ *    schema.parse({ phone: '+201234567890' });
+ *    ```
+ *
+ * 2. **National number for a fixed country** — when you already know the country (e.g.,
+ *    a Saudi-only form) and only need to validate the digits the user typed:
+ *
+ *    ```ts
+ *    const schema = z.object({ phone: zPhone({ country: 'SA' }) });
+ *    ```
+ *
+ * 3. **Combined object** — matches ATelInput's two v-models out of the box:
+ *
+ *    ```ts
+ *    import { zPhoneObject } from '@alikhalilll/a-tel-input/zod';
+ *    const schema = z.object({
+ *      contact: zPhoneObject(), // -> { phone: string, country: number | null }
+ *    });
+ *    ```
+ *
+ * All three honour `allowedDialCodes` and produce a `PhoneValidationReason` localised
+ * through the same `DEFAULT_ERROR_MESSAGES` map as the component, so error wording is
+ * consistent across UI + schema.
+ *
+ * `zod` is an **optional peer dependency** — install it yourself in your app.
+ */
+
+import { z } from 'zod';
+import { parsePhoneNumberFromString } from 'libphonenumber-js';
+import {
+  usePhoneValidation,
+  type PhoneValidationReason,
+  type PhoneValidationResult,
+} from '../composables/usePhoneValidation';
+import { DEFAULT_ERROR_MESSAGES } from '../types';
+
+export interface ZPhoneOptions {
+  /**
+   * ISO 3166-1 alpha-2 country code (`'EG'`, `'SA'`, …). When set, the input is treated
+   * as a national number for that country. Leave undefined to validate a full E.164
+   * string (the country is inferred from the leading `+` dial code).
+   */
+  country?: string;
+  /**
+   * Whitelist of allowed dial-digit codes (no `+`), e.g. `['20', '966']`. Numbers from
+   * countries outside this list fail with `country_not_supported`. Matches the
+   * `allowedDialCodes` prop on `ATelInput`.
+   */
+  allowedDialCodes?: string[];
+  /**
+   * BCP-47 locale, forwarded to the validator. Doesn't change the validity outcome —
+   * only affects locale-dependent fields on the underlying validation result.
+   */
+  locale?: string;
+  /**
+   * Override the error messages used when the Zod issue is raised. Keyed by validation
+   * reason. Falls back to the same English defaults the component uses.
+   */
+  messages?: Partial<Record<PhoneValidationReason, string>>;
+  /**
+   * Custom message for the "empty input" case. By default the schema accepts an empty
+   * string — wrap with `z.string().min(1)` upstream if you want "required" semantics,
+   * or pass a non-empty `requiredMessage` to enforce it here.
+   */
+  requiredMessage?: string;
+}
+
+function messageFor(reason: PhoneValidationReason, overrides?: ZPhoneOptions['messages']) {
+  return overrides?.[reason] ?? DEFAULT_ERROR_MESSAGES[reason];
+}
+
+function failsAllowList(dialDigits: string, allowed?: string[]) {
+  if (!allowed || allowed.length === 0) return false;
+  return !allowed.includes(dialDigits);
+}
+
+/** Run the same validate() the component uses, but resolve country from an E.164 string. */
+function validateE164(
+  value: string,
+  v: ReturnType<typeof usePhoneValidation>,
+  locale?: string
+): PhoneValidationResult {
+  const trimmed = String(value ?? '').trim();
+  if (!trimmed) {
+    return {
+      ok: false,
+      reason: 'invalid_phone',
+      country: null,
+      phone: { raw: value, digits: '' },
+      full_phone: null,
+      required: null,
+    };
+  }
+  // libphonenumber wants a leading `+` to skip the country-hint requirement.
+  const e164 = trimmed.startsWith('+') ? trimmed : `+${trimmed}`;
+  const parsed = parsePhoneNumberFromString(e164);
+  if (!parsed || !parsed.country) {
+    return {
+      ok: false,
+      reason: 'parse_failed',
+      country: null,
+      phone: { raw: value, digits: '' },
+      full_phone: null,
+      required: null,
+    };
+  }
+  return v.validate({
+    country: { iso2: parsed.country },
+    phone: parsed.nationalNumber,
+    locale,
+  });
+}
+
+/**
+ * Zod schema for a phone string.
+ *
+ * @see {@link ZPhoneOptions} for behaviour modes.
+ */
+export function zPhone(options: ZPhoneOptions = {}): z.ZodType<string, z.ZodTypeDef, string> {
+  // Lazy: only construct the validator on first parse, so apps that bundle this don't
+  // pay the libphonenumber metadata load until they actually validate.
+  let _v: ReturnType<typeof usePhoneValidation> | null = null;
+  const getV = () => {
+    if (!_v) {
+      _v = usePhoneValidation();
+      void _v.getCountries();
+    }
+    return _v;
+  };
+
+  return z.string().superRefine((value, ctx) => {
+    const v = getV();
+    const isEmpty = !value || !String(value).trim();
+
+    if (isEmpty) {
+      if (options.requiredMessage) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: options.requiredMessage });
+      }
+      return;
+    }
+
+    const result: PhoneValidationResult = options.country
+      ? v.validate({ country: { iso2: options.country }, phone: value, locale: options.locale })
+      : validateE164(value, v, options.locale);
+
+    if (!result.ok) {
+      const reason = result.reason ?? 'invalid_phone';
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: messageFor(reason, options.messages),
+        params: { reason, validation: result },
+      });
+      return;
+    }
+
+    const dialDigits = result.country?.dial_code?.replace(/^\+/, '') ?? '';
+    if (failsAllowList(dialDigits, options.allowedDialCodes)) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: messageFor('country_not_supported', options.messages),
+        params: { reason: 'country_not_supported' as PhoneValidationReason, validation: result },
+      });
+    }
+  });
+}
+
+/**
+ * Zod schema for the `{ phone, country }` object shape matching `ATelInput`'s two
+ * v-models. `phone` is the digits-only national number; `country` is the dial-digit
+ * **number** (e.g. `20` for Egypt). NANP (`+1`) maps to `'US'` for validation purposes,
+ * which is correct for `isValidPhoneNumber` (all NANP countries share the same rule set).
+ */
+export function zPhoneObject(options: ZPhoneOptions = {}) {
+  let _v: ReturnType<typeof usePhoneValidation> | null = null;
+  const getV = () => {
+    if (!_v) {
+      _v = usePhoneValidation();
+      void _v.getCountries();
+    }
+    return _v;
+  };
+
+  return z
+    .object({
+      phone: z.string(),
+      country: z.number().nullable(),
+    })
+    .superRefine((input, ctx) => {
+      const v = getV();
+      const phone = (input.phone ?? '').trim();
+      const country = input.country;
+
+      if (!phone) {
+        if (options.requiredMessage) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['phone'],
+            message: options.requiredMessage,
+          });
+        }
+        return;
+      }
+
+      if (country == null) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['country'],
+          message: messageFor('missing_country', options.messages),
+        });
+        return;
+      }
+
+      const matches = v.getCountriesByDial(String(country));
+      const iso2 = matches[0]?.value ?? options.country;
+      if (!iso2) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['country'],
+          message: messageFor('country_not_supported', options.messages),
+        });
+        return;
+      }
+
+      const result = v.validate({ country: { iso2 }, phone, locale: options.locale });
+      if (!result.ok) {
+        const reason = result.reason ?? 'invalid_phone';
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['phone'],
+          message: messageFor(reason, options.messages),
+          params: { reason, validation: result },
+        });
+        return;
+      }
+
+      if (failsAllowList(String(country), options.allowedDialCodes)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: ['country'],
+          message: messageFor('country_not_supported', options.messages),
+        });
+      }
+    });
+}
+
+export { DEFAULT_ERROR_MESSAGES };
+export type { PhoneValidationReason, PhoneValidationResult };

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "@alikhalilll/a-tel-input",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "js-types-syntax": "typescript",
   "description-markup": "markdown",
   "framework": "vue",
@@ -97,6 +97,12 @@
               "type": "string",
               "required": false
             },
+            {
+              "name": "error",
+              "type": "string | null",
+              "required": false,
+              "description": "Externally controlled error message. When set to a non-empty string the component\nis forced into the error visual state and renders this message via the `#error`\nslot — overriding internal libphonenumber validation. Wire this from VeeValidate,\nZod, an async server check (\"this phone is already registered\"), or any custom\nvalidation layer.\n\nPass `null` / `undefined` / `''` to defer to internal validation."
+            },
             {
               "name": "errorClass",
               "type": "string",
@@ -161,6 +167,18 @@
               "required": false,
               "description": "Localized UI strings. A single bag covering the picker, validation errors, and a11y\nlabels. Individual props (`searchPlaceholder`, `emptyText`, `loadingText`,\n`errorMessages`) take precedence over the matching `messages` key when both are set."
             },
+            {
+              "name": "modelValue",
+              "type": "string",
+              "required": false,
+              "description": "Default `v-model` — the canonical **E.164** string (e.g. `'+201066105963'`).\n\nReads + writes the full international number as a single value. Designed to drop\nstraight into VeeValidate's `<Field v-slot=\"{ field }\">` pattern (use\n`v-bind=\"field\"`), native `<form>` submission, or any `v-model=\"phoneE164\"` consumer.\n\nStays in sync with the split `v-model:phone` + `v-model:country` contract — use\neither, or both."
+            },
+            {
+              "name": "name",
+              "type": "string",
+              "required": false,
+              "description": "Forwarded to the inner `<input name=\"\">`. Set this when participating in a native\n`<form>` submission, or when a form library (VeeValidate, etc.) wants a stable name."
+            },
             {
               "name": "placeholder",
               "type": "string",
@@ -206,6 +224,18 @@
               "name": "size",
               "type": "Size",
               "required": false
+            },
+            {
+              "name": "validateOn",
+              "type": "ATelInputValidateOn",
+              "required": false,
+              "description": "When to surface validation in the UI.\n- `'change'` (default) — visible state mirrors the typing-paused state.\n- `'blur'` — stays idle until the input has been blurred once (form-library friendly).\n- `'eager'` — mirror raw validation immediately, no typing pause."
+            },
+            {
+              "name": "validating",
+              "type": "boolean",
+              "required": false,
+              "description": "`true` while an async validation is in flight (e.g. a server-side uniqueness\ncheck). Renders a small spinner inside the field and sets `aria-busy=\"true\"` on\nthe input. Does **not** disable the field — use `loading` for that. Replace the\nspinner via the `#validating` slot.\n\nDesigned to be bound to the `validating` ref returned by `useTelField()`."
             }
           ],
           "slots": [
@@ -266,13 +296,26 @@
             {
               "name": "valid-icon",
               "description": "Replace the green check shown when the number validates."
+            },
+            {
+              "name": "validating",
+              "description": "Replace the spinner shown inside the field while async validation is in flight."
             }
           ],
           "js": {
             "events": [
+              {
+                "name": "blur"
+              },
+              {
+                "name": "focus"
+              },
               {
                 "name": "update:country"
               },
+              {
+                "name": "update:modelValue"
+              },
               {
                 "name": "update:phone"
               }