@alikhalilll/a-tel-input 1.0.1 → 1.1.0

package/src/composables/useTelInputValidation.ts

@@ -15,13 +15,15 @@ import type { TelInputMessages } from '../types';
  * component needs:
  *
  * - `validation` / `validationState` — the raw + simplified state of the current input.
- * - `visibleValidationState` — `validationState` gated by the `hasFinishedTyping` flag
- *   from {@link useTypingPhase}, so error tints / icons / messages only appear once the
- *   user has paused. This is the value the template should bind to.
+ * - `visibleValidationState` — `validationState` gated by `validateOn` + the
+ *   `hasFinishedTyping` flag from {@link useTypingPhase}, so error tints / icons /
+ *   messages only appear at the right moment (after typing pause, after blur, or eagerly).
+ *   This is the value the template should bind to.
  * - `errorMessage` — localised error string for the current `validation.reason`, or
- *   `null` when the input is empty or valid.
+ *   `null` when the input is empty / valid. When an external `error` is supplied
+ *   (e.g. from VeeValidate), it wins.
  * - `showError` / `showHint` — boolean computed properties for conditional rendering
- *   in the template; both already respect `showValidation` and the typing-pause gate.
+ *   in the template; both already respect `showValidation` and the visible-state gate.
  * - `selectedDialCode` — the human-readable dial prefix (`+20`, `+1`, …) for the
  *   selected country, used as an in-input prefix.
  *
@@ -43,6 +45,17 @@ export interface UseTelInputValidationDeps {
   getCountryByValue: UsePhoneValidationReturn['getCountryByValue'];
 }
 
+/** When to surface validation in the UI.
+ *  - `'change'` (default) — visible state mirrors the typing-paused state. Errors light up
+ *    a beat after the user stops typing. Best for inline forms.
+ *  - `'blur'` — visible state stays `'idle'` until the input has been blurred at least
+ *    once, then mirrors typing-paused state. Best for VeeValidate / form-library flows
+ *    that validate on blur.
+ *  - `'eager'` — visible state mirrors raw `validationState` immediately on every keystroke,
+ *    no typing pause. Use sparingly; can feel aggressive.
+ */
+export type ATelInputValidateOn = 'change' | 'blur' | 'eager';
+
 export interface UseTelInputValidationInputs {
   /** Digits-only national number model. */
   phone: Ref<string>;
@@ -50,6 +63,8 @@ export interface UseTelInputValidationInputs {
   selectedIso2: Ref<string>;
   /** From {@link useTypingPhase} — gates visible state during the debounce window. */
   hasFinishedTyping: Readonly<Ref<boolean>>;
+  /** Whether the input has been blurred at least once. Drives `validateOn: 'blur'`. */
+  hasBlurred: Readonly<Ref<boolean>>;
   /** Resolved i18n messages (merged defaults + consumer overrides). */
   messages: ComputedRef<TelInputMessages>;
 }
@@ -61,6 +76,15 @@ export interface UseTelInputValidationConfig {
   showValidation: () => boolean | undefined;
   /** Per-reason error string overrides. From props. */
   errorMessages: () => Partial<Record<PhoneValidationReason, string>> | undefined;
+  /** When to surface validation in the UI. Defaults to `'change'`. */
+  validateOn: () => ATelInputValidateOn | undefined;
+  /**
+   * Externally controlled error (from VeeValidate / Zod / a custom form layer). When set
+   * to a non-empty string, the component is forced into `'error'` state and surfaces this
+   * message regardless of internal validation. `null` / `undefined` / `''` defers to the
+   * internal validator.
+   */
+  externalError: () => string | null | undefined;
 }
 
 export interface UseTelInputValidationReturn {
@@ -93,25 +117,40 @@ export function useTelInputValidation(
     })
   );
 
+  const externalErrorActive = computed<boolean>(() => {
+    const e = config.externalError();
+    return typeof e === 'string' && e.length > 0;
+  });
+
   const validationState = computed<'idle' | 'valid' | 'error'>(() => {
+    if (externalErrorActive.value) return 'error';
     if (!inputs.phone.value) return 'idle';
     return validation.value.ok ? 'valid' : 'error';
   });
 
-  const visibleValidationState = computed<'idle' | 'valid' | 'error'>(() =>
-    inputs.hasFinishedTyping.value ? validationState.value : 'idle'
-  );
+  const visibleValidationState = computed<'idle' | 'valid' | 'error'>(() => {
+    if (externalErrorActive.value) return 'error';
+    const mode = config.validateOn() ?? 'change';
+    if (mode === 'eager') return validationState.value;
+    if (mode === 'blur' && !inputs.hasBlurred.value) return 'idle';
+    return inputs.hasFinishedTyping.value ? validationState.value : 'idle';
+  });
 
   const errorMessage = computed<string | null>(() => {
+    const ext = config.externalError();
+    if (typeof ext === 'string' && ext.length > 0) return ext;
     const v = validation.value;
     if (v.ok || !v.reason) return null;
     if (!inputs.phone.value) return null;
     return config.errorMessages()?.[v.reason] ?? inputs.messages.value.errorMessages[v.reason];
   });
 
-  const showError = computed<boolean>(() =>
-    Boolean(config.showValidation() && inputs.hasFinishedTyping.value && errorMessage.value)
-  );
+  const showError = computed<boolean>(() => {
+    if (!errorMessage.value) return false;
+    if (externalErrorActive.value) return true;
+    if (!config.showValidation()) return false;
+    return visibleValidationState.value === 'error';
+  });
 
   const showHint = computed<boolean>(
     () => !showError.value && !inputs.phone.value && !!required.value?.format_hint

package/src/index.ts

@@ -34,3 +34,5 @@ export * from './composables/useCountryDetection';
 export * from './composables/useCountryMatching';
 export * from './composables/useTypingPhase';
 export * from './composables/useTelInputValidation';
+export * from './composables/useCountrySelection';
+export * from './composables/useSyncedModel';

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,
+  };
+}