@desource/phone-mask-react 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @desource/phone-mask-react
+
+## 0.3.0
+
+### Minor Changes
+
+- React: Design React version of phone-mask library
+- Core: Add geoip reusable service for country detection based on IP address
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @desource/phone-mask@0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeSource Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,455 @@
+# @desource/phone-mask-react
+
+> React phone input component and hook with smart masking and Google libphonenumber data
+
+[![npm version](https://img.shields.io/npm/v/@desource/phone-mask-react?color=blue&logo=react)](https://www.npmjs.com/package/@desource/phone-mask-react)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/@desource/phone-mask-react?label=gzip%20size&color=purple)](https://bundlephobia.com/package/@desource/phone-mask-react)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/DeSource-Labs/phone-mask/blob/main/LICENSE)
+
+Beautiful, accessible, extreme small & tree-shackable React phone input with auto-formatting, country selector, and validation.
+
+## ✨ Features
+
+- 🎨 **Beautiful UI** — Modern design with light/dark themes
+- 🔍 **Smart Country Search** — Fuzzy matching with keyboard navigation
+- 🎭 **Auto-formatting** — As-you-type formatting with smart cursor
+- ✅ **Validation** — Built-in validation with visual feedback
+- 📋 **Copy Button** — One-click copy to clipboard
+- 🌐 **Auto-detection** — GeoIP and locale-based detection
+- ♿ **Accessible** — ARIA labels, keyboard navigation
+- 📱 **Mobile-friendly** — Optimized for touch devices
+- 🎯 **TypeScript** — Full type safety
+- 🪝 **Hook API** — For custom input implementations
+- ⚡ **Optimized** — Tree-shaking and code splitting
+
+## 📦 Installation
+
+```bash
+npm install @desource/phone-mask-react
+# or
+yarn add @desource/phone-mask-react
+# or
+pnpm add @desource/phone-mask-react
+```
+
+## 🚀 Quick Start
+
+### Importing
+
+Component mode:
+```tsx
+import { PhoneInput } from '@desource/phone-mask-react';
+import '@desource/phone-mask-react/assets/lib.css'; // Import styles
+```
+
+Hook mode:
+```tsx
+import { usePhoneMask } from '@desource/phone-mask-react';
+```
+
+### Component Mode
+
+```tsx
+import { useState } from 'react';
+import { PhoneInput } from '@desource/phone-mask-react';
+import '@desource/phone-mask-react/assets/lib.css'; // Import styles
+
+function App() {
+  const [phone, setPhone] = useState('');
+  const [isValid, setIsValid] = useState(false);
+
+  return (
+    <>
+      <PhoneInput
+        value={phone}
+        onChange={setPhone}
+        onValidationChange={setIsValid}
+        country="US"
+      />
+
+      {isValid && <p>✓ Valid phone number</p>}
+    </>
+  );
+}
+```
+
+### Hook Mode
+
+For custom input implementations:
+
+```tsx
+import { usePhoneMask } from '@desource/phone-mask-react';
+
+function CustomPhoneInput() {
+  const { ref, digits, full, fullFormatted, isComplete, country, setCountry } = usePhoneMask({
+    country: 'US',
+    detect: true,
+    onChange: (phone) => {
+      console.log(phone.full, phone.digits);
+    }
+  });
+
+  return (
+    <div>
+      <input ref={ref} type="tel" placeholder="Phone number" />
+      <p>Formatted: {fullFormatted}</p>
+      <p>Valid: {isComplete ? 'Yes' : 'No'}</p>
+      <p>Country: {country.name}</p>
+      <button onClick={() => setCountry('GB')}>Use UK</button>
+    </div>
+  );
+}
+```
+
+## 📖 Component API
+
+### Props
+
+```ts
+interface PhoneInputProps {
+  // Controlled value (digits only, without country code)
+  value?: string;
+
+  // Preselected country (ISO 3166-1 alpha-2)
+  country?: CountryKey;
+
+  // Auto-detect country from IP/locale
+  detect?: boolean; // Default: true
+
+  // Locale for country names
+  locale?: string; // Default: browser language
+
+  // Size variant
+  size?: 'compact' | 'normal' | 'large'; // Default: 'normal'
+
+  // Visual theme ("auto" | "light" | "dark")
+  theme?: 'auto' | 'light' | 'dark'; // Default: 'auto'
+
+  // Disabled state
+  disabled?: boolean; // Default: false
+
+  // Readonly state
+  readonly?: boolean; // Default: false
+
+  // Show copy button
+  showCopy?: boolean; // Default: true
+
+  // Show clear button
+  showClear?: boolean; // Default: false
+
+  // Show validation state (borders & outline)
+  withValidity?: boolean; // Default: true
+
+  // Custom search placeholder
+  searchPlaceholder?: string; // Default: 'Search country or code...'
+
+  // Custom no results text
+  noResultsText?: string; // Default: 'No countries found'
+
+  // Custom clear button label
+  clearButtonLabel?: string; // Default: 'Clear phone number'
+
+  // Dropdown menu custom CSS class
+  dropdownClass?: string;
+
+  // Disable default styles
+  disableDefaultStyles?: boolean; // Default: false
+
+  // Callback when the digits value changes.
+  // Returns only the digits without country code (e.g. '234567890')
+  onChange?: (digits: string) => void;
+
+  // Callback when the phone number changes.
+  // Provides an object with:
+  // - full: Full phone number with country code (e.g. +1234567890)
+  // - fullFormatted: Full phone number formatted according to country rules (e.g. +1 234-567-890)
+  // - digits: Only the digits of the phone number without country code (e.g. 234567890)
+  onPhoneChange?: (value: PhoneNumber) => void;
+
+  // Callback when the selected country changes
+  onCountryChange?: (country: MaskFull) => void;
+
+  // Callback when the validation state changes
+  onValidationChange?: (isValid: boolean) => void;
+
+  // Callback when the input is focused
+  onFocus?: (event: FocusEvent<HTMLInputElement>) => void;
+
+  // Callback when the input is blurred
+  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
+
+  // Callback when phone number is copied
+  onCopy?: (value: string) => void;
+
+  // Callback when input is cleared
+  onClear?: () => void;
+
+  // Render custom action buttons before default ones
+  renderActionsBefore?: () => ReactNode;
+
+  // Render custom flag icons in the country list and country selector
+  renderFlag?: (country: MaskFull) => ReactNode;
+
+  // Render custom copy button SVG
+  renderCopySvg?: (copied: boolean) => ReactNode;
+
+  // Render custom clear button SVG
+  renderClearSvg?: () => ReactNode;
+}
+```
+
+### Ref Methods
+
+```tsx
+const phoneInputRef = useRef<PhoneInputRef>(null);
+
+phoneInputRef.current?.focus(); // Focuses the input
+phoneInputRef.current?.blur(); // Blurs the input
+phoneInputRef.current?.clear(); // Clears the input value
+phoneInputRef.current?.selectCountry('GB'); // Programmatically selects a country by ISO code (e.g., 'US', 'DE', 'GB')
+phoneInputRef.current?.getFullNumber(); // Returns the full phone number with country code (e.g., +1234567890)
+phoneInputRef.current?.getFullFormattedNumber(); // Returns the full phone number formatted according to country rules (e.g., +1 234-567-890)
+phoneInputRef.current?.getDigits(); // Returns only the digits of the phone number without country code (e.g., 234567890)
+phoneInputRef.current?.isValid(); // Checks if the current phone number is valid
+phoneInputRef.current?.isComplete(); // Checks if the current phone number is complete
+```
+
+## 🪝 Hook API
+
+### Options
+
+```ts
+interface UsePhoneMaskOptions {
+  // Predefined country ISO code (e.g., 'US', 'DE', 'GB')
+  country?: string;
+
+  // Locale for country names (default: navigator.language)
+  locale?: string;
+
+  // Auto-detect country from IP/locale (default: false)
+  detect?: boolean;
+
+  // Value change callback
+  onChange?: (phone: PhoneNumber) => void;
+
+  // Country change callback
+  onCountryChange?: (country: MaskFull) => void;
+}
+```
+
+### Return Value
+
+```ts
+interface UsePhoneMaskReturn {
+  ref: RefObject<HTMLInputElement>;
+  digits: string;
+  full: string;
+  fullFormatted: string;
+  isComplete: boolean;
+  isEmpty: boolean;
+  shouldShowWarn: boolean;
+  country: MaskFull;
+  setCountry: (countryCode: string) => void;
+  clear: () => void;
+}
+```
+
+## 🎨 Component Styling
+
+### CSS Custom Properties
+
+Customize colors via CSS variables:
+
+```css
+.phone-input,
+.phone-dropdown {
+  /* Colors */
+  --pi-bg: #ffffff;
+  --pi-fg: #111827;
+  --pi-muted: #6b7280;
+  --pi-border: #e5e7eb;
+  --pi-border-hover: #d1d5db;
+  --pi-border-focus: #3b82f6;
+  --pi-focus-ring: 3px solid rgb(59 130 246 / 0.15);
+  --pi-disabled-bg: #f9fafb;
+  --pi-disabled-fg: #9ca3af;
+  /* Sizes */
+  --pi-font-size: 16px;
+  --pi-height: 44px;
+  /* Spacing */
+  --pi-padding: 12px;
+  /* Border radius */
+  --pi-radius: 8px;
+  /* Shadows */
+  --pi-shadow: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --pi-shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -2px rgb(0 0 0 / 0.05);
+  /* Validation */
+  --pi-warning: #f59e0b;
+  --pi-warning-light: #fbbf24;
+  --pi-success: #10b981;
+  --pi-focus-ring-warning: 3px solid rgb(245 158 11 / 0.15);
+  --pi-focus-ring-success: 3px solid rgb(16 185 129 / 0.15);
+}
+```
+
+### Dark Theme
+
+```tsx
+<PhoneInput value={phone} theme="dark" />
+```
+
+Or with CSS:
+
+```css
+.phone-input[data-theme='dark'] {
+  --pi-bg: #1f2937;
+  --pi-fg: #f9fafb;
+  --pi-border: #374151;
+}
+```
+
+## 📚 Examples
+
+### With Validation
+
+```tsx
+import { useState } from 'react';
+import { PhoneInput } from '@desource/phone-mask-react';
+
+function Example() {
+  const [phone, setPhone] = useState('');
+  const [isValid, setIsValid] = useState(false);
+
+  return (
+    <div>
+      <PhoneInput value={phone} onChange={setPhone} onValidationChange={setIsValid} />
+
+      {isValid && <span>✓ Valid phone number</span>}
+    </div>
+  );
+}
+```
+
+### Auto-detect Country
+
+```tsx
+import { useState } from 'react';
+import { PhoneInput } from '@desource/phone-mask-react';
+
+function Example() {
+  const [phone, setPhone] = useState('');
+  const [detectedCountry, setDetectedCountry] = useState('');
+
+  return (
+    <>
+      <PhoneInput
+        value={phone}
+        detect
+        onChange={setPhone}
+        onCountryChange={(country) => setDetectedCountry(country.name)}
+      />
+
+      {detectedCountry && <p>Detected: {detectedCountry}</p>}
+    </>
+  );
+}
+```
+
+### With Form Libraries
+
+#### React Hook Form
+
+```tsx
+import { useForm, Controller } from 'react-hook-form';
+import { PhoneInput } from '@desource/phone-mask-react';
+
+function Example() {
+  const { control } = useForm({
+    defaultValues: { phone: '' }
+  });
+
+  return (
+    <Controller
+      name="phone"
+      control={control}
+      render={({ field }) => (
+        <PhoneInput
+          value={field.value}
+          onChange={(digits) => field.onChange(digits)}
+          onBlur={field.onBlur}
+        />
+      )}
+    />
+  );
+}
+```
+
+### Multiple Inputs
+
+```tsx
+import { useState } from 'react';
+import { PhoneInput } from '@desource/phone-mask-react';
+
+function Example() {
+  const [form, setForm] = useState({ mobile: '', home: '', work: '' });
+
+  return (
+    <div className="form">
+      <label>
+        Mobile
+        <PhoneInput value={form.mobile} onChange={(digits) => setForm({ ...form, mobile: digits })} />
+      </label>
+
+      <label>
+        Home
+        <PhoneInput value={form.home} onChange={(digits) => setForm({ ...form, home: digits })} />
+      </label>
+
+      <label>
+        Work
+        <PhoneInput value={form.work} onChange={(digits) => setForm({ ...form, work: digits })} />
+      </label>
+    </div>
+  );
+}
+```
+
+## 🎯 Browser Support
+
+- Chrome/Edge 90+
+- Firefox 88+
+- Safari 14+
+- iOS Safari 14+
+- Chrome Mobile
+
+## 📦 What's Included
+
+```
+@desource/phone-mask-react/
+├── dist/
+│   ├── esm                     # ESM bundle + types
+│   ├── phone-mask-react.cjs.js # CommonJS bundle
+│   └── phone-mask-react.css    # Component styles
+├── README.md                   # This file
+└── package.json                # Package manifest
+```
+
+## 🔗 Related
+
+- [@desource/phone-mask](../phone-mask) — Core library
+- [@desource/phone-mask-nuxt](../phone-mask-nuxt) — Nuxt module
+- [@desource/phone-mask-vue](../phone-mask-vue) — Vue 3 bindings
+
+## 📄 License
+
+[MIT](../../LICENSE) © 2026 DeSource Labs
+
+## 🤝 Contributing
+
+See [Contributing Guide](../../CONTRIBUTING.md)
+
+---
+
+<div align="center">
+  <sub>Made with ❤️ by <a href="https://github.com/DeSource-Labs">DeSource Labs</a></sub>
+</div>

package/dist/esm/components/PhoneInput.d.ts

@@ -0,0 +1,11 @@
+import { type Ref } from 'react';
+import type { PhoneInputProps, PhoneInputRef } from '../types';
+type PhoneInputComponent = PhoneInputProps & {
+    ref?: Ref<PhoneInputRef>;
+};
+export declare const PhoneInput: {
+    ({ ref, ...props }: PhoneInputComponent): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};
+export {};
+//# sourceMappingURL=PhoneInput.d.ts.map

package/dist/esm/components/PhoneInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PhoneInput.d.ts","sourceRoot":"","sources":["../../../src/components/PhoneInput.tsx"],"names":[],"mappings":"AAAA,OAAc,EAQZ,KAAK,GAAG,EACT,MAAM,OAAO,CAAC;AAYf,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAe,MAAM,UAAU,CAAC;AAS5E,KAAK,mBAAmB,GAAG,eAAe,GAAG;IAAE,GAAG,CAAC,EAAE,GAAG,CAAC,aAAa,CAAC,CAAA;CAAE,CAAC;AAE1E,eAAO,MAAM,UAAU;wBAAuB,mBAAmB;;CAuwBhE,CAAC"}

package/dist/esm/consts.d.ts

@@ -0,0 +1,4 @@
+export declare const Delimiters: string[];
+export declare const NavigationKeys: string[];
+export declare const InvalidPattern: RegExp;
+//# sourceMappingURL=consts.d.ts.map

package/dist/esm/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../../src/consts.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU,UAAuB,CAAC;AAC/C,eAAO,MAAM,cAAc,UAA4E,CAAC;AACxG,eAAO,MAAM,cAAc,QAAgB,CAAC"}

package/dist/esm/hooks/usePhoneMask.d.ts

@@ -0,0 +1,7 @@
+import type { UsePhoneMaskOptions, UsePhoneMaskReturn } from '../types';
+/**
+ * React hook for phone number masking.
+ * Provides low-level phone masking functionality for custom input implementations.
+ */
+export declare function usePhoneMask(options?: UsePhoneMaskOptions): UsePhoneMaskReturn;
+//# sourceMappingURL=usePhoneMask.d.ts.map

package/dist/esm/hooks/usePhoneMask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePhoneMask.d.ts","sourceRoot":"","sources":["../../../src/hooks/usePhoneMask.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAe,MAAM,UAAU,CAAC;AAyBrF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,kBAAkB,CAwTlF"}

package/dist/esm/index.d.ts

@@ -0,0 +1,14 @@
+import { countPlaceholders, formatDigitsWithMap, pickMaskVariant, removeCountryCodePrefix, toArray } from '@desource/phone-mask';
+export { PhoneInput } from './components/PhoneInput';
+export { usePhoneMask } from './hooks/usePhoneMask';
+export type { PhoneInputProps, PhoneInputRef, PhoneNumber, UsePhoneMaskOptions, UsePhoneMaskReturn, Size as PhoneInputSize, Theme as PhoneInputTheme } from './types';
+export type { CountryKey as PCountryKey, MaskBase as PMaskBase, MaskBaseMap as PMaskBaseMap, Mask as PMask, MaskMap as PMaskMap, MaskWithFlag as PMaskWithFlag, MaskWithFlagMap as PMaskWithFlagMap, MaskFull as PMaskFull, MaskFullMap as PMaskFullMap } from '@desource/phone-mask';
+export declare const PMaskHelpers: {
+    getFlagEmoji: (cc: string) => string;
+    countPlaceholders: typeof countPlaceholders;
+    formatDigitsWithMap: typeof formatDigitsWithMap;
+    pickMaskVariant: typeof pickMaskVariant;
+    removeCountryCodePrefix: typeof removeCountryCodePrefix;
+    toArray: typeof toArray;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,iBAAiB,EACjB,mBAAmB,EACnB,eAAe,EACf,uBAAuB,EACvB,OAAO,EACR,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,YAAY,EACV,eAAe,EACf,aAAa,EACb,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,IAAI,IAAI,cAAc,EACtB,KAAK,IAAI,eAAe,EACzB,MAAM,SAAS,CAAC;AAEjB,YAAY,EACV,UAAU,IAAI,WAAW,EACzB,QAAQ,IAAI,SAAS,EACrB,WAAW,IAAI,YAAY,EAC3B,IAAI,IAAI,KAAK,EACb,OAAO,IAAI,QAAQ,EACnB,YAAY,IAAI,aAAa,EAC7B,eAAe,IAAI,gBAAgB,EACnC,QAAQ,IAAI,SAAS,EACrB,WAAW,IAAI,YAAY,EAC5B,MAAM,sBAAsB,CAAC;AAE9B,eAAO,MAAM,YAAY;;;;;;;CAOxB,CAAC"}