npm - @alikhalilll/a-tel-input - Versions diffs - 1.0.1 - Mend

@alikhalilll/a-tel-input 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (44) hide show

package/LICENSE +21 -0
package/README.md +124 -0
package/dist/index.cjs +5846 -0
package/dist/index.cjs.map +1 -0
package/dist/index.d.cts +791 -0
package/dist/index.d.ts +791 -0
package/dist/index.js +5804 -0
package/dist/index.js.map +1 -0
package/dist/nuxt/index.cjs +30 -0
package/dist/nuxt/index.cjs.map +1 -0
package/dist/nuxt/index.d.cts +15 -0
package/dist/nuxt/index.d.ts +15 -0
package/dist/nuxt/index.js +30 -0
package/dist/nuxt/index.js.map +1 -0
package/dist/resolver/index.cjs +25 -0
package/dist/resolver/index.cjs.map +1 -0
package/dist/resolver/index.d.cts +14 -0
package/dist/resolver/index.d.ts +14 -0
package/dist/resolver/index.js +25 -0
package/dist/resolver/index.js.map +1 -0
package/dist/styles.css +520 -0
package/package.json +123 -0
package/src/components/ACountryFlag.vue +78 -0
package/src/components/ACountrySelect.vue +674 -0
package/src/components/ATelInput.vue +742 -0
package/src/composables/useCountryDetection.ts +247 -0
package/src/composables/useCountryMatching.ts +213 -0
package/src/composables/usePhoneValidation.ts +573 -0
package/src/composables/useTelInputValidation.ts +136 -0
package/src/composables/useTypingPhase.ts +88 -0
package/src/icons/AlertCircleIcon.vue +17 -0
package/src/icons/CheckCircleIcon.vue +16 -0
package/src/icons/CheckIcon.vue +15 -0
package/src/icons/ChevronDownIcon.vue +15 -0
package/src/icons/SearchIcon.vue +16 -0
package/src/icons/SpinnerIcon.vue +28 -0
package/src/icons/index.ts +6 -0
package/src/index.ts +36 -0
package/src/nuxt/index.ts +37 -0
package/src/resolver/index.ts +29 -0
package/src/types.ts +389 -0
package/src/utils/digits.ts +42 -0
package/src/utils/flag-url.ts +10 -0
package/web-types.json +526 -0

package/src/types.ts ADDED Viewed

@@ -0,0 +1,389 @@
+import type { HTMLAttributes } from 'vue';
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { DetectionStrategy, DetectCountryOptions } from './composables/useCountryDetection';
+import type {
+  CountryOption,
+  PhoneValidationReason,
+  PhoneValidationResult,
+} from './composables/usePhoneValidation';
+import type { FlagUrlBuilder } from './utils/flag-url';
+import type { Size } from '@alikhalilll/a-ui-base';
+/** Alias for the shared `Size` scale — kept for backwards-friendly naming. */
+export type ATelInputSize = Size;
+// Field styling now lives entirely in ATelInput.vue's scoped CSS — sizes/states are driven
+// by the `data-size` / `data-state` attributes set in the template. The cva wrapper survives
+// so consumers can still call `aTelInputVariants({ size: 'md' })` (returns the field class);
+// the per-size class slots are empty placeholders that exist only to preserve the type.
+export const aTelInputVariants = cva('a-tel-input__field', {
+  variants: {
+    size: { xs: '', sm: '', md: '', lg: '', xl: '' },
+  },
+  defaultVariants: { size: 'md' },
+});
+export type ATelInputVariants = VariantProps<typeof aTelInputVariants>;
+/** Text direction for the field. `'auto'` (or omitting the prop) inherits from the
+ *  nearest `[dir]` ancestor / `<html dir>`; `'ltr'` / `'rtl'` force it. */
+export type ATelInputDir = 'ltr' | 'rtl' | 'auto';
+/**
+ * Every user-facing string in the tel-input UI, bundled so a consumer can localize the
+ * component in one prop. Each key has an English default in {@link DEFAULT_MESSAGES}.
+ */
+export interface TelInputMessages {
+  /** Placeholder of the country-picker search box. */
+  searchPlaceholder: string;
+  /** Shown when a search yields no countries. */
+  emptyText: string;
+  /** Shown while the country list is loading. */
+  loadingText: string;
+  /** Header of the "Suggested" group (current + recent picks). */
+  suggestedLabel: string;
+  /** Header of the full country list. */
+  allCountriesLabel: string;
+  /** Validation error text, keyed by reason. */
+  errorMessages: Record<PhoneValidationReason, string>;
+  /** Prefix of the country trigger's `aria-label`, e.g. `"Country: Egypt"`. */
+  countryLabel: string;
+  /** `aria-label` of the country trigger when no country is selected. */
+  selectCountryLabel: string;
+  /** `aria-label` of the phone input element. */
+  phoneInputLabel: string;
+}
+/** Partial override shape for the `messages` prop — every key (and every error reason) is optional. */
+export type TelInputMessagesInput = Partial<Omit<TelInputMessages, 'errorMessages'>> & {
+  errorMessages?: Partial<Record<PhoneValidationReason, string>>;
+};
+export interface ATelInputProps {
+  class?: HTMLAttributes['class'];
+  placeholder?: string;
+  disabled?: boolean;
+  loading?: boolean;
+  size?: ATelInputSize;
+  /**
+   * Text direction. Omit (or pass `'auto'`) to inherit from the page — RTL pages get an
+   * RTL field automatically. Pass `'ltr'` / `'rtl'` to force it.
+   */
+  dir?: ATelInputDir;
+  /**
+   * BCP-47 locale (e.g. `'ar'`, `'fr'`). When set, country names render localized via
+   * `Intl.DisplayNames` and the format hint uses the locale's numerals.
+   */
+  locale?: string;
+  /**
+   * Localized UI strings. A single bag covering the picker, validation errors, and a11y
+   * labels. Individual props (`searchPlaceholder`, `emptyText`, `loadingText`,
+   * `errorMessages`) take precedence over the matching `messages` key when both are set.
+   */
+  messages?: TelInputMessagesInput;
+  /**
+   * Whitelist of allowed dial-digit codes (no `+`), e.g. `['20', '966']`.
+   * Countries outside this list are still shown in the picker but rendered as disabled.
+   */
+  allowedDialCodes?: string[];
+  /** Light up the field's validation styling — coloured border + ring on the input and the
+   *  error message line below — when the number is valid / invalid. Default `false`, so the
+   *  field stays neutral and validation surfacing is left to the consumer (via the
+   *  `validation` ref exposure). */
+  showValidation?: boolean;
+  /** Show the green check / red alert icon at the end of the field. Default `false`; opt
+   *  in with `true`. Independent of `showValidation` — you can show the icon without the
+   *  coloured field, or vice versa. The slots `#valid-icon` / `#error-icon` still apply. */
+  showValidationIcon?: boolean;
+  /**
+   * Country auto-detect strategy. Defaults to `'auto'` — try IP geolocation first, then
+   * timezone, then `navigator.language`, finally `defaultCountry`.
+   */
+  detectCountry?: DetectionStrategy;
+  /**
+   * Initial country. Accepts either an ISO2 code (`'EG'`) or a dial-digit string
+   * (`'20'`, `'+20'`). When set, the picker is visible at mount with this country
+   * pre-selected — overrides the hidden-until-detected default.
+   */
+  defaultCountry?: string;
+  /** Override the IP geolocation endpoint. Must return JSON with `country_code` or `country`. */
+  ipEndpoint?: string;
+  /** Localized strings for the country picker UI. */
+  searchPlaceholder?: string;
+  emptyText?: string;
+  loadingText?: string;
+  /** Error labels keyed by reason. Each gets a sensible English default. */
+  errorMessages?: Partial<Record<PhoneValidationReason, string>>;
+  /**
+   * When true, the country picker is hidden until a leading dial code is detected in the
+   * phone input. Every keystroke runs a longest-prefix match against known dial codes; on
+   * first match the picker reveals with that country and the matched dial digits are
+   * stripped from `phone`. Skips the onMount IP/timezone/locale detection chain.
+   */
+  detectFromInput?: boolean;
+  /**
+   * Debounce window (ms) for `detectFromInput` detection. Each keystroke schedules the
+   * libphonenumber parse + lookup; bursts of typing/paste collapse into a single call.
+   * Clearing the input is not debounced — the picker hides immediately. Default 150ms.
+   */
+  detectDebounceMs?: number;
+  /** Override the flag URL builder, forwarded to ACountrySelect. */
+  flagUrl?: (iso2: string, width: number) => string;
+  /** Custom search predicate, forwarded to ACountrySelect. */
+  searcher?: (query: string, country: CountryOption) => boolean;
+  /** Provide your own country list, forwarded to ACountrySelect. */
+  countries?: CountryOption[];
+  /**
+   * Fully custom country detection. When provided, this function runs in place of the
+   * built-in chain — `detectCountry`-style options are still honored but the function
+   * receives them and is free to ignore them.
+   */
+  detector?: (options: DetectCountryOptions) => Promise<string | null | undefined>;
+  /** Forwarded to ACountrySelect: classes for the popover content surface. */
+  contentClass?: string;
+  /** Forwarded to ACountrySelect: classes for the desktop popover surface. */
+  popoverClass?: string;
+  /** Forwarded to ACountrySelect: classes for the mobile drawer surface. */
+  drawerClass?: string;
+  /** Classes for the inner phone field input element. */
+  inputClass?: string;
+  /** Classes for the outer wrapper that holds country select + input. */
+  fieldClass?: string;
+  /** Classes for the helper hint line. */
+  hintClass?: string;
+  /** Classes for the error message line. */
+  errorClass?: string;
+  /**
+   * How page scroll is blocked while the country popover is open. Defaults to `'events'`
+   * (sticky-safe document-level lock). Pass `'body'` for the legacy
+   * `body { overflow: hidden }` lock, or `'none'` to leave page scrolling alone.
+   */
+  scrollLock?: 'events' | 'body' | 'none';
+}
+/**
+ * Props for {@link ACountryFlag} — the standalone flag image component. Renders a
+ * `flagcdn` image for an ISO2 code with an automatic text-badge fallback when the
+ * image fails to load. Surface separately so it can be used outside `ATelInput`
+ * (e.g., in a custom country picker).
+ */
+export interface ACountryFlagProps {
+  /** ISO 3166-1 alpha-2 country code, case-insensitive. */
+  iso2: string;
+  /** Pixel width served by flagcdn. 40 is crisp at retina up to ~24px wide. */
+  width?: number;
+  /** Optional explicit URL override. When set, `iso2` / `width` / `flagUrl` are ignored. */
+  src?: string | null;
+  /** Function `(iso2, width) => string` — fully replace the URL builder. */
+  flagUrl?: FlagUrlBuilder;
+  alt?: string;
+  class?: HTMLAttributes['class'];
+}
+/**
+ * Slot prop shape for {@link ACountryFlag}. The `empty` slot is rendered when no
+ * flag URL is available and no ISO2 fallback can be derived.
+ */
+export interface ACountryFlagSlots {
+  /** Rendered when the flag URL is unavailable and no ISO2 text fallback can be derived. */
+  empty?: () => unknown;
+}
+export const DEFAULT_ERROR_MESSAGES: Record<PhoneValidationReason, string> = {
+  missing_country: 'Please select a country.',
+  country_not_supported: 'This country is not supported.',
+  phone_has_non_digits: 'Phone number can only contain digits.',
+  too_short: 'Phone number is too short.',
+  too_long: 'Phone number is too long.',
+  invalid_phone: 'Phone number is invalid.',
+  parse_failed: 'Could not parse phone number.',
+};
+/** English defaults for every {@link TelInputMessages} key. */
+export const DEFAULT_MESSAGES: TelInputMessages = {
+  searchPlaceholder: 'Search country or +code…',
+  emptyText: 'No countries found.',
+  loadingText: 'Loading countries…',
+  suggestedLabel: 'Suggested',
+  allCountriesLabel: 'All countries',
+  errorMessages: DEFAULT_ERROR_MESSAGES,
+  countryLabel: 'Country',
+  selectCountryLabel: 'Select country',
+  phoneInputLabel: 'Phone number',
+};
+/**
+ * Merge a partial `messages` override onto the English defaults. Used internally by
+ * `ATelInput` to resolve a complete {@link TelInputMessages} object.
+ */
+export function resolveMessages(input?: TelInputMessagesInput): TelInputMessages {
+  if (!input) return DEFAULT_MESSAGES;
+  return {
+    ...DEFAULT_MESSAGES,
+    ...input,
+    errorMessages: { ...DEFAULT_ERROR_MESSAGES, ...input.errorMessages },
+  };
+}
+/**
+ * Slot prop shape for {@link ATelInput}. Use to get full slot-prop type inference
+ * when overriding slots in a consumer template:
+ *
+ *   <ATelInput #suffix="{ validationState }">…</ATelInput>
+ *                     ↑ inferred as `'idle' | 'valid' | 'error'`
+ *
+ * Or in TypeScript code:
+ *   type SuffixProps = Parameters<NonNullable<ATelInputSlots['suffix']>>[0];
+ */
+export interface ATelInputSlots {
+  /** Content before the country select trigger (e.g. an icon). */
+  prefix?: () => unknown;
+  /** Content between the input and the validation icons. */
+  suffix?: (props: {
+    validationState: 'idle' | 'valid' | 'error';
+    validation: PhoneValidationResult;
+  }) => unknown;
+  /** Replace the green check shown when the number validates. */
+  'valid-icon'?: () => unknown;
+  /** Replace the warning icon shown when the number fails validation. */
+  'error-icon'?: (props: { reason: string }) => unknown;
+  /** Replace the dim helper line shown below the input when empty. */
+  hint?: (props: { country: string; formatHint: string; example: string | null }) => unknown;
+  /** Replace the error message rendered when invalid. */
+  error?: (props: {
+    message: string;
+    reason: string;
+    validation: PhoneValidationResult;
+  }) => unknown;
+  /** Forwarded to ACountrySelect — replace the trigger button. */
+  trigger?: (props: {
+    selectedCountry: CountryOption | null;
+    open: boolean;
+    sizeClasses: string;
+  }) => unknown;
+  /** Forwarded to ACountrySelect — replace the chevron. */
+  chevron?: (props: { open: boolean }) => unknown;
+  /** Forwarded — replace any flag rendering. */
+  flag?: (props: { country: CountryOption; context: 'trigger' | 'item' }) => unknown;
+  /** Forwarded — replace each country list row. */
+  item?: (props: {
+    country: CountryOption;
+    selected: boolean;
+    disabled: boolean;
+    select: () => void;
+  }) => unknown;
+  /** Forwarded — section header. */
+  'group-header'?: (props: { label: string; group: 'suggested' | 'all' }) => unknown;
+  /** Forwarded — search bar. */
+  search?: (props: {
+    value: string;
+    setValue: (v: string) => void;
+    isSearching: boolean;
+  }) => unknown;
+  loading?: () => unknown;
+  empty?: (props: { query: string }) => unknown;
+  /** Replace the spinner shown in the picker slot during the debounce window. */
+  detecting?: () => 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`.
+ */
+export type ATelInputEmits = {
+  'update:phone': [value: string];
+  'update:country': [value: number | null];
+};
+/**
+ * Props for {@link ACountrySelect} — the standalone country picker. Surface
+ * separately so it can be used outside `ATelInput` with full type support.
+ */
+export interface ACountrySelectProps {
+  class?: HTMLAttributes['class'];
+  triggerClass?: HTMLAttributes['class'];
+  contentClass?: HTMLAttributes['class'];
+  popoverClass?: HTMLAttributes['class'];
+  drawerClass?: HTMLAttributes['class'];
+  searchPlaceholder?: string;
+  emptyText?: string;
+  loadingText?: string;
+  suggestedLabel?: string;
+  allCountriesLabel?: string;
+  /** ISO2 codes that are selectable. Others are listed but disabled. */
+  allowedDialCodes?: string[];
+  disabled?: boolean;
+  /** Drives the trigger button padding + text size. Matches ATelInput's `size`. */
+  size?: ATelInputSize;
+  /** Max items rendered under the "Suggested" header (current + recents, deduped). */
+  suggestedLimit?: number;
+  /** Cap the number of matching countries shown in search results. */
+  maxResults?: number;
+  /** Override the flag URL builder, e.g. `(iso, w) => `/flags/${iso}.svg``. */
+  flagUrl?: (iso2: string, width: number) => string;
+  /** Custom search predicate. Default: substring match on the precomputed `search_key`. */
+  searcher?: (query: string, country: CountryOption) => boolean;
+  /** Provide your own country list (bypasses the REST Countries fetch). */
+  countries?: CountryOption[];
+  /** Override the right-side kbd hints. Pass `null` to hide. */
+  kbdOpen?: string | null;
+  kbdClose?: string | null;
+  /** BCP-47 locale — country names render localized via `Intl.DisplayNames`. */
+  locale?: string;
+  /** Prefix of the trigger's `aria-label` when a country is selected, e.g. `"Country"`. */
+  countryLabel?: string;
+  /** Trigger's `aria-label` when no country is selected. */
+  selectCountryLabel?: string;
+  /** How page scroll is blocked while the popover is open. Default `'events'`. */
+  scrollLock?: 'events' | 'body' | 'none';
+}
+/**
+ * Slot prop shape for {@link ACountrySelect}. Forwarded versions of these slots
+ * also appear on {@link ATelInputSlots} (`trigger`, `chevron`, `flag`, `item`,
+ * etc.) — keep them in sync when changing one.
+ */
+export interface ACountrySelectSlots {
+  /** Replace the entire country picker trigger button. */
+  trigger?: (props: {
+    selectedCountry: CountryOption | null;
+    open: boolean;
+    sizeClasses: string;
+  }) => unknown;
+  /** Replace the chevron icon. */
+  chevron?: (props: { open: boolean }) => unknown;
+  /** Replace just the flag rendered in the trigger and items. */
+  flag?: (props: { country: CountryOption; context: 'trigger' | 'item' }) => unknown;
+  /** Replace the entire search bar (input + icon + kbd). */
+  search?: (props: {
+    value: string;
+    setValue: (v: string) => void;
+    isSearching: boolean;
+  }) => unknown;
+  /** Replace the search-bar leading icon. */
+  'search-icon'?: () => unknown;
+  /** Replace the loading state. */
+  loading?: () => unknown;
+  /** Replace the empty/no-results state. */
+  empty?: (props: { query: string }) => unknown;
+  /** Replace a section header. */
+  'group-header'?: (props: { label: string; group: 'suggested' | 'all' }) => unknown;
+  /** Replace each country list row. */
+  item?: (props: {
+    country: CountryOption;
+    selected: boolean;
+    disabled: boolean;
+    select: () => void;
+  }) => unknown;
+  /** Replace just the right-side check icon for the selected row. */
+  'item-check'?: (props: { country: CountryOption }) => unknown;
+}
+/**
+ * Emit map for {@link ACountrySelect}. The `selected` is `v-model:selected`,
+ * carrying the ISO2 code of the picked country.
+ */
+export type ACountrySelectEmits = {
+  'update:selected': [value: string];
+};

package/src/utils/digits.ts ADDED Viewed

@@ -0,0 +1,42 @@
+/**
+ * Alternative-numeral support. Phone numbers are routinely entered with the digits of the
+ * user's own script — Arabic-Indic, Persian/Urdu, Devanagari, Bengali. `libphonenumber-js`
+ * and our own `\d` cleanup only understand ASCII `0-9`, so anything else silently becomes
+ * an empty number. `normalizeDigits` folds those scripts down to ASCII before validation.
+ */
+/**
+ * Base code points of contiguous decimal-digit blocks. Each block runs `base`‥`base+9`
+ * for digit `0`‥`9`, so the ASCII digit is `codePoint - base`. Add a script by appending
+ * one entry here.
+ */
+export const LOCALE_DIGIT_RANGES: { name: string; base: number }[] = [
+  { name: 'arabic-indic', base: 0x0660 }, // ٠١٢٣٤٥٦٧٨٩
+  { name: 'extended-arabic', base: 0x06f0 }, // ۰۱۲۳۴۵۶۷۸۹ — Persian / Urdu
+  { name: 'devanagari', base: 0x0966 }, // ०१२३४५६७८९
+  { name: 'bengali', base: 0x09e6 }, // ০১২৩৪৫৬৭৮৯
+];
+/** Lookup of every non-ASCII digit code point → its ASCII character. */
+const DIGIT_MAP: Map<number, string> = (() => {
+  const map = new Map<number, string>();
+  for (const { base } of LOCALE_DIGIT_RANGES) {
+    for (let d = 0; d <= 9; d++) map.set(base + d, String(d));
+  }
+  return map;
+})();
+/**
+ * Replace any supported non-ASCII decimal digit with its ASCII equivalent. Every other
+ * character (spaces, `+`, separators, letters) is left untouched — callers still run their
+ * own `\D` cleanup afterwards.
+ */
+export function normalizeDigits(input: string): string {
+  const str = String(input ?? '');
+  let out = '';
+  for (const ch of str) {
+    const cp = ch.codePointAt(0);
+    out += (cp != null && DIGIT_MAP.get(cp)) || ch;
+  }
+  return out;
+}

package/src/utils/flag-url.ts ADDED Viewed

@@ -0,0 +1,10 @@
+/**
+ * Default flag URL builder — flagcdn.com hosts PNG flags at multiple widths and is
+ * generous with caching + no API key required. Swap via the `flagUrl` prop on
+ * ATelInput / ACountrySelect / ACountryFlag to use any other source.
+ */
+export function defaultFlagUrl(iso2: string, width = 40): string {
+  return `https://flagcdn.com/w${width}/${iso2.toLowerCase()}.png`;
+}
+export type FlagUrlBuilder = (iso2: string, width: number) => string;