@alikhalilll/ui 1.2.2 → 1.2.4

package/entries/tell-input/composables/useTypingPhase.ts

@@ -0,0 +1,88 @@
+import { ref, readonly, type ComputedRef, type Ref } from 'vue';
+import { useDebounceFn } from '@vueuse/core';
+
+/**
+ * Typing-phase state machine for the tel input.
+ *
+ * Owns the three reactive flags that drive the "is the user still typing?" UX:
+ *
+ * - `isDetecting` — true while the debounce window is in flight (user is mid-burst or
+ *   has just paused). Drives the loading spinner in the picker slot.
+ * - `hasFinishedTyping` — false from the moment a key lands until the debounce settles.
+ *   Gates validation visibility, so error/success states only appear once the user pauses.
+ * - `detectionAttempted` — flips true the first time the debounce fires on non-empty
+ *   input. Used by the consumer to keep the country picker visible after a failed
+ *   detection (so the user can pick manually instead of being stranded).
+ *
+ * Design notes:
+ *
+ * - The composable is pure state — it does not know about country detection, phone
+ *   numbers, or libphonenumber. The consumer wires the `onSettle` callback to whatever
+ *   "what to do when typing pauses" logic is appropriate (typically: try to detect a
+ *   country from the current digits, mark a detection attempt, and apply the match).
+ *
+ * - `markDetectionAttempt()` is exposed separately so the caller controls *when* the
+ *   "keep the picker visible" flag flips — not every settle triggers a real attempt
+ *   (e.g. when input is empty or the user already picked a country manually).
+ *
+ * - Refs are exposed `readonly` so external code can't bypass the state machine; all
+ *   transitions go through the exposed actions.
+ */
+export interface UseTypingPhaseOptions {
+  /** Debounce window in ms. Reactive so consumers can change `detectDebounceMs` at runtime. */
+  debounceMs: ComputedRef<number>;
+  /** Fired when the debounce timer settles. Runs regardless of input state — use this
+   *  to clear loading UI, then perform any pause-triggered work (e.g. detection). */
+  onSettle?: () => void;
+}
+
+export interface UseTypingPhaseReturn {
+  isDetecting: Readonly<Ref<boolean>>;
+  hasFinishedTyping: Readonly<Ref<boolean>>;
+  detectionAttempted: Readonly<Ref<boolean>>;
+  /** Call from the input handler on every keystroke that produces non-empty input. */
+  markTyping: () => void;
+  /** Flip `detectionAttempted` to true. Call from within the `onSettle` callback when
+   *  a real detection attempt is about to run — so the picker stays visible after even
+   *  a failed match. */
+  markDetectionAttempt: () => void;
+  /** Reset all three flags to defaults. Call when the input is cleared. */
+  reset: () => void;
+}
+
+export function useTypingPhase(opts: UseTypingPhaseOptions): UseTypingPhaseReturn {
+  const isDetecting = ref(false);
+  const hasFinishedTyping = ref(true);
+  const detectionAttempted = ref(false);
+
+  const settle = useDebounceFn(() => {
+    isDetecting.value = false;
+    hasFinishedTyping.value = true;
+    opts.onSettle?.();
+  }, opts.debounceMs);
+
+  function markTyping() {
+    isDetecting.value = true;
+    hasFinishedTyping.value = false;
+    settle();
+  }
+
+  function markDetectionAttempt() {
+    detectionAttempted.value = true;
+  }
+
+  function reset() {
+    isDetecting.value = false;
+    hasFinishedTyping.value = true;
+    detectionAttempted.value = false;
+  }
+
+  return {
+    isDetecting: readonly(isDetecting),
+    hasFinishedTyping: readonly(hasFinishedTyping),
+    detectionAttempted: readonly(detectionAttempted),
+    markTyping,
+    markDetectionAttempt,
+    reset,
+  };
+}

package/entries/tell-input/index.ts

@@ -0,0 +1,29 @@
+// Components
+export { default as ATellInput } from './components/ATellInput.vue';
+export { default as ACountrySelect } from './components/ACountrySelect.vue';
+export { default as ACountryFlag } from './components/ACountryFlag.vue';
+
+// Types, variants, defaults
+export {
+  aTellInputVariants,
+  DEFAULT_ERROR_MESSAGES,
+  DEFAULT_MESSAGES,
+  resolveMessages,
+  type ATellInputProps,
+  type ATellInputSize,
+  type ATellInputVariants,
+  type ATellInputDir,
+  type TellInputMessages,
+  type TellInputMessagesInput,
+} from './utils/types';
+export { defaultFlagUrl, type FlagUrlBuilder } from './utils/flag-url';
+
+// i18n — alternative-numeral normalization
+export { normalizeDigits, LOCALE_DIGIT_RANGES } from './utils/digits';
+
+// Composables — co-located with the components since they're tel-input specific.
+export * from './composables/usePhoneValidation';
+export * from './composables/useCountryDetection';
+export * from './composables/useCountryMatching';
+export * from './composables/useTypingPhase';
+export * from './composables/useTellInputValidation';

package/entries/tell-input/utils/digits.ts

@@ -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/entries/tell-input/utils/flag-url.ts

@@ -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
+ * ATellInput / 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;

package/entries/tell-input/utils/types.ts

@@ -0,0 +1,169 @@
+import type { HTMLAttributes } from 'vue';
+import { cva, type VariantProps } from 'class-variance-authority';
+import type { DetectionStrategy } from '../composables/useCountryDetection';
+import type { PhoneValidationReason } from '../composables/usePhoneValidation';
+import { controlHeight, controlTextSize, type Size } from '@/utils';
+
+/** Alias for the shared `Size` scale — kept for backwards-friendly naming. */
+export type ATellInputSize = Size;
+
+export const aTellInputVariants = cva(
+  // items-center (not items-stretch) so #prefix/#suffix icons centre vertically without distortion.
+  // The country trigger button and the input element both carry `h-full`, so they still fill the
+  // field height regardless of this setting.
+  'border-input bg-background ring-offset-background focus-within:ring-ring flex w-full items-center overflow-hidden rounded-md border shadow-sm transition-colors focus-within:ring-1 has-[input:disabled]:cursor-not-allowed has-[input:disabled]:opacity-50',
+  {
+    variants: {
+      size: {
+        xs: `${controlHeight.xs} ${controlTextSize.xs}`,
+        sm: `${controlHeight.sm} ${controlTextSize.sm}`,
+        md: `${controlHeight.md} ${controlTextSize.md}`,
+        lg: `${controlHeight.lg} ${controlTextSize.lg}`,
+        xl: `${controlHeight.xl} ${controlTextSize.xl}`,
+      },
+    },
+    defaultVariants: { size: 'md' },
+  }
+);
+
+export type ATellInputVariants = VariantProps<typeof aTellInputVariants>;
+
+/** Text direction for the field. `'auto'` (or omitting the prop) inherits from the
+ *  nearest `[dir]` ancestor / `<html dir>`; `'ltr'` / `'rtl'` force it. */
+export type ATellInputDir = 'ltr' | 'rtl' | 'auto';
+
+/**
+ * Every user-facing string in the tell-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 TellInputMessages {
+  /** 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 TellInputMessagesInput = Partial<Omit<TellInputMessages, 'errorMessages'>> & {
+  errorMessages?: Partial<Record<PhoneValidationReason, string>>;
+};
+
+export interface ATellInputProps {
+  class?: HTMLAttributes['class'];
+  placeholder?: string;
+  disabled?: boolean;
+  loading?: boolean;
+  size?: ATellInputSize;
+  /**
+   * 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?: ATellInputDir;
+  /**
+   * 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?: TellInputMessagesInput;
+  /**
+   * 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;
+}
+
+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 TellInputMessages} key. */
+export const DEFAULT_MESSAGES: TellInputMessages = {
+  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
+ * `ATellInput` to resolve a complete {@link TellInputMessages} object.
+ */
+export function resolveMessages(input?: TellInputMessagesInput): TellInputMessages {
+  if (!input) return DEFAULT_MESSAGES;
+  return {
+    ...DEFAULT_MESSAGES,
+    ...input,
+    errorMessages: { ...DEFAULT_ERROR_MESSAGES, ...input.errorMessages },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alikhalilll/ui",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Headless, shadcn-vue style Vue 3 component library — every component is its own importable subpath (`@alikhalilll/ui/tell-input`, `@alikhalilll/ui/popover`, …) so users pay only for what they actually use.",
   "license": "MIT",
   "author": "alikhalilll",
@@ -69,6 +69,9 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "entries/**/*.vue",
+    "entries/**/*.ts",
+    "utils/**/*.ts",
     "entries/**/README.md",
     "README.md",
     "LICENSE"

package/utils/cn.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/utils/index.ts

@@ -0,0 +1,10 @@
+export { cn } from './cn';
+export {
+  SIZES,
+  DEFAULT_SIZE,
+  controlHeight,
+  controlPaddingX,
+  controlTextSize,
+  controlHeightPx,
+  type Size,
+} from './sizes';

package/utils/sizes.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared size scale for every interactive UI component in @alikhalilll/ui.
+ *
+ *   xs = 28px · sm = 36px · md = 43px (default) · lg = 52px · xl = 60px
+ *
+ * Use the {@link controlHeight}, {@link controlPaddingX}, {@link controlTextSize}
+ * maps when building a CVA variant so every component stays in lockstep.
+ */
+
+export type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+export const SIZES: readonly Size[] = ['xs', 'sm', 'md', 'lg', 'xl'] as const;
+
+export const DEFAULT_SIZE: Size = 'md';
+
+/** Tailwind height utility per size. md uses an arbitrary value because 43px isn't on the spacing scale. */
+export const controlHeight: Record<Size, string> = {
+  xs: 'h-7',
+  sm: 'h-9',
+  md: 'h-[43px]',
+  lg: 'h-[52px]',
+  xl: 'h-[60px]',
+};
+
+export const controlPaddingX: Record<Size, string> = {
+  xs: 'px-2',
+  sm: 'px-2.5',
+  md: 'px-3',
+  lg: 'px-3.5',
+  xl: 'px-4',
+};
+
+export const controlTextSize: Record<Size, string> = {
+  xs: 'text-xs',
+  sm: 'text-sm',
+  md: 'text-sm',
+  lg: 'text-base',
+  xl: 'text-base',
+};
+
+/** Pixel values exposed so non-template code (icons, ResizeObserver, etc.) can read the height. */
+export const controlHeightPx: Record<Size, number> = {
+  xs: 28,
+  sm: 36,
+  md: 43,
+  lg: 52,
+  xl: 60,
+};