@jacksonavila/phone-lib 2.0.0 → 2.0.2

package/README.md

@@ -1,275 +1,572 @@
 # PhoneLib 📱
 
-Librería JavaScript para integrar fácilmente un input de teléfono con selector de país, banderas y validación de números telefónicos. **Compatible con Vanilla JavaScript y React**.
+Modern JavaScript library to easily integrate a phone input with country selector, flags, and phone number validation. **Compatible with Vanilla JavaScript and React**.
 
-## Características
+Librería JavaScript moderna para integrar fácilmente un input de teléfono con selector de país, banderas y validación de números telefónicos. **Compatible con Vanilla JavaScript y React**.
 
-- ✅ Dropdown con países mostrando nombre, código ISO2, código de marcación y bandera
-- ✅ Input de tipo "tel" con formato automático según el país seleccionado
-- ✅ Validación de números telefónicos usando `libphonenumber-js`
-- ✅ API pública completa con métodos para obtener información del número
-- ✅ Opciones de configuración flexibles
-- ✅ Estilos CSS modernos y responsivos
-- ✅ **Soporte para Vanilla JavaScript y React**
-- ✅ Eventos y callbacks personalizables
-- ✅ Control programático completo
-- ✅ Detección automática de país
-- ✅ Filtrado de países
-- ✅ Modo readonly/disabled
+[![npm version](https://img.shields.io/npm/v/@jacksonavila/phone-lib.svg)](https://www.npmjs.com/package/@jacksonavila/phone-lib)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## Instalación
+---
 
-### Desde npm (Después de publicar)
+## ✨ Features / Características
 
-```bash
-npm install @jacksonavila/phone-lib
-```
-
-### Desarrollo Local
-
-```bash
-npm install
-```
+- ✅ **Country dropdown** / **Dropdown de países** showing name, ISO2 code, dial code, and flag
+- ✅ **Tel input** / **Input tipo tel** with automatic formatting based on selected country
+- ✅ **Phone number validation** / **Validación de números** using `libphonenumber-js`
+- ✅ **Complete public API** / **API pública completa** with methods to get number information
+- ✅ **Vanilla JavaScript and React support** / **Soporte para Vanilla JavaScript y React**
+- ✅ **Two layouts available** / **Dos layouts disponibles**: integrated and separated
+- ✅ **Customizable events and callbacks** / **Eventos y callbacks** personalizables
+- ✅ **Full programmatic control** / **Control programático** completo
+- ✅ **Automatic country detection** / **Detección automática** de país
+- ✅ **Country filtering** / **Filtrado de países** (include/exclude/disable)
+- ✅ **Readonly/disabled mode** / **Modo readonly/disabled**
+- ✅ **Modern responsive CSS** / **Estilos CSS modernos** y responsivos
+- ✅ **Improved accessibility** / **Accesibilidad mejorada** (ARIA labels, keyboard navigation)
 
-## 🚀 Cómo Probar la Librería
+---
 
-### Opción Rápida (Recomendada)
+## 📦 Installation / Instalación
 
 ```bash
-# 1. Instalar dependencias
-npm install
-
-# 2. Iniciar servidor de desarrollo
-npm run serve
+npm install @jacksonavila/phone-lib
 ```
 
-Esto abrirá automáticamente tu navegador en `http://localhost:3004` con todos los demos disponibles.
-
-### Archivos de Demo Disponibles
-
-Una vez que el servidor esté corriendo, puedes probar:
-
-- **`demo.html`** - Ejemplo básico con layout integrado
-- **`demo-separated.html`** - Layout separado
-- **`demo-all-layouts.html`** - Comparación de todos los layouts
-- **`demo-features.html`** - Todas las nuevas características (eventos, control programático, etc.)
-- **`demo-react.html`** - Ejemplo con React
-
-### Otras Opciones de Servidor
+### Dependencies / Dependencias
 
 ```bash
-# Python 3
-python -m http.server 8000
-
-# Node.js http-server
-npx http-server . -p 8080 -o
+# For React projects / Para proyectos React
+npm install react react-dom
 
-# PHP
-php -S localhost:8000
+# libphonenumber-js is installed automatically
+# libphonenumber-js se instala automáticamente
 ```
 
-**⚠️ Importante:** No abras los archivos directamente con `file://` - necesitas un servidor HTTP debido a los módulos ES6.
+---
 
-📖 **Para más detalles sobre cómo probar**, consulta [`TESTING.md`](./TESTING.md)
+## 🚀 Quick Start / Inicio Rápido
 
-## Uso Básico
-
-### HTML
+### Vanilla JavaScript
 
 ```html
 <!DOCTYPE html>
 <html>
 <head>
-  <link rel="stylesheet" href="phone-lib.css">
+  <link rel="stylesheet" href="node_modules/@jacksonavila/phone-lib/phone-lib.css">
 </head>
 <body>
   <div id="phone-container"></div>
-  
+
   <script type="module">
-    import PhoneLib from './phone-lib.js';
-    
+    import PhoneLib from '@jacksonavila/phone-lib';
+
     const phoneLib = new PhoneLib('#phone-container', {
       initialCountry: 'CO',
-      preferredCountries: ['CO', 'US', 'ES'],
-      showHint: true
+      layout: 'integrated',
+      showDialCode: true
     });
+
+    // Get number information / Obtener información del número
+    const info = phoneLib.getInfo();
+    console.log(info);
   </script>
 </body>
 </html>
 ```
 
-### Opciones de Configuración
+### React
+
+```jsx
+import React from 'react';
+import PhoneLibReact from '@jacksonavila/phone-lib/react';
+import '@jacksonavila/phone-lib/css';
+
+function App() {
+  return (
+    <PhoneLibReact
+      initialCountry="CO"
+      layout="integrated"
+      showDialCode={true}
+    />
+  );
+}
+
+export default App;
+```
+
+---
+
+## 📖 Complete Usage Guide / Guía de Uso Completa
+
+### Vanilla JavaScript
+
+#### Basic Example / Ejemplo Básico
 
 ```javascript
-const phoneLib = new PhoneLib(container, {
-  initialCountry: 'CO',           // País inicial (código ISO2)
-  preferredCountries: ['CO', 'US'], // Países que aparecen primero en la lista
-  showHint: true,                  // Mostrar hint de validación
-  layout: 'integrated',            // 'integrated' o 'separated'
-  showDialCode: true               // Mostrar código de marcación (true/false)
+import PhoneLib from '@jacksonavila/phone-lib';
+import '@jacksonavila/phone-lib/css';
+
+const phoneLib = new PhoneLib('#phone-container', {
+  initialCountry: 'CO',
+  preferredCountries: ['CO', 'US', 'ES'],
+  showHint: true,
+  layout: 'integrated',
+  showDialCode: true
 });
 ```
 
-### Ejemplos de Layouts
+#### With Events and Callbacks / Con Eventos y Callbacks
 
-**Layout Integrado con código:**
 ```javascript
+import PhoneLib from '@jacksonavila/phone-lib';
+import '@jacksonavila/phone-lib/css';
+
 const phoneLib = new PhoneLib('#phone-container', {
+  initialCountry: 'CO',
+  
+  // Callbacks
+  onCountryChange: (country, dialCode, countryName) => {
+    console.log('Country changed / País cambiado:', country, dialCode, countryName);
+  },
+  
+  onPhoneChange: (phoneNumber, isValid, country) => {
+    console.log('Number / Número:', phoneNumber, 'Valid / Válido:', isValid);
+    if (isValid) {
+      const info = phoneLib.getInfo();
+      console.log('Complete info / Información completa:', info);
+    }
+  },
+  
+  onValidationChange: (isValid, phoneNumber) => {
+    console.log('Validation / Validación:', isValid ? 'Valid / Válido' : 'Invalid / Inválido');
+  },
+  
+  onFocus: () => console.log('Input focused / Input enfocado'),
+  onBlur: () => console.log('Input blurred / Input perdió foco')
+});
+
+// Listen to custom DOM events / Escuchar eventos DOM personalizados
+document.getElementById('phone-container').addEventListener('phoneLib:countryChange', (e) => {
+  console.log('DOM event / Evento DOM:', e.detail);
+});
+```
+
+#### Programmatic Control / Control Programático
+
+```javascript
+// Set values / Establecer valores
+phoneLib.setCountry('ES');
+phoneLib.setPhoneNumber('+34600123456');
+phoneLib.setValue('US', '5551234567');
+
+// Control state / Controlar estado
+phoneLib.enable();
+phoneLib.disable();
+phoneLib.reset();
+
+// Get information / Obtener información
+const country = phoneLib.getCountry();        // 'CO'
+const dialCode = phoneLib.getDialCode();      // '+57'
+const raw = phoneLib.getRaw();                // '3001234567'
+const e164 = phoneLib.getE164();              // '+573001234567'
+const isValid = phoneLib.isValid();           // true/false
+const info = phoneLib.getInfo();              // Complete object / Objeto completo
+```
+
+#### Form Integration / Integración con Formularios
+
+```html
+<form id="contact-form">
+  <div id="phone-container"></div>
+  <button type="submit">Submit / Enviar</button>
+</form>
+
+<script type="module">
+  import PhoneLib from '@jacksonavila/phone-lib';
+  import '@jacksonavila/phone-lib/css';
+
+  const phoneLib = new PhoneLib('#phone-container', {
+    initialCountry: 'CO',
+    validateOnInput: true
+  });
+
+  document.getElementById('contact-form').addEventListener('submit', (e) => {
+    e.preventDefault();
+    
+    const phoneInfo = phoneLib.getInfo();
+    
+    if (!phoneInfo.isValid) {
+      alert('Please enter a valid number / Por favor ingrese un número válido');
+      return;
+    }
+
+    // Send data / Enviar datos
+    const formData = {
+      phone: phoneInfo.e164,
+      country: phoneInfo.country,
+      // ... other fields / otros campos
+    };
+
+    console.log('Sending / Enviando:', formData);
+  });
+</script>
+```
+
+### React
+
+#### Basic Example / Ejemplo Básico
+
+```jsx
+import React from 'react';
+import PhoneLibReact from '@jacksonavila/phone-lib/react';
+import '@jacksonavila/phone-lib/css';
+
+function App() {
+  return (
+    <PhoneLibReact
+      initialCountry="CO"
+      layout="integrated"
+      showDialCode={true}
+    />
+  );
+}
+
+export default App;
+```
+
+#### With Ref and Methods / Con Ref y Métodos
+
+```jsx
+import React, { useRef } from 'react';
+import PhoneLibReact from '@jacksonavila/phone-lib/react';
+import '@jacksonavila/phone-lib/css';
+
+function App() {
+  const phoneLibRef = useRef(null);
+
+  const handleSubmit = () => {
+    const info = phoneLibRef.current.getInfo();
+    
+    if (!info.isValid) {
+      alert('Invalid number / Número inválido');
+      return;
+    }
+
+    console.log('Send / Enviar:', info.e164);
+  };
+
+  return (
+    <div>
+      <PhoneLibReact
+        ref={phoneLibRef}
+        initialCountry="CO"
+        layout="integrated"
+        onPhoneChange={(phone, isValid) => {
+          console.log('Number / Número:', phone, 'Valid / Válido:', isValid);
+        }}
+      />
+      <button onClick={handleSubmit}>Submit / Enviar</button>
+    </div>
+  );
+}
+```
+
+#### With React State / Con Estado de React
+
+```jsx
+import React, { useState, useRef } from 'react';
+import PhoneLibReact from '@jacksonavila/phone-lib/react';
+import '@jacksonavila/phone-lib/css';
+
+function PhoneForm() {
+  const phoneLibRef = useRef(null);
+  const [phoneData, setPhoneData] = useState(null);
+
+  const handleGetData = () => {
+    const info = phoneLibRef.current.getInfo();
+    setPhoneData(info);
+  };
+
+  return (
+    <div>
+      <PhoneLibReact
+        ref={phoneLibRef}
+        initialCountry="CO"
+        onPhoneChange={(phone, isValid) => {
+          if (isValid) {
+            const info = phoneLibRef.current.getInfo();
+            setPhoneData(info);
+          }
+        }}
+      />
+      
+      {phoneData && (
+        <div>
+          <p>Country / País: {phoneData.country}</p>
+          <p>Number / Número: {phoneData.e164}</p>
+          <p>Valid / Válido: {phoneData.isValid ? 'Yes / Sí' : 'No'}</p>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+#### React Form Integration / Integración con Formularios React
+
+```jsx
+import React, { useRef } from 'react';
+import PhoneLibReact from '@jacksonavila/phone-lib/react';
+import '@jacksonavila/phone-lib/css';
+
+function ContactForm() {
+  const phoneLibRef = useRef(null);
+  const formRef = useRef(null);
+
+  const handleSubmit = (e) => {
+    e.preventDefault();
+    
+    const phoneInfo = phoneLibRef.current.getInfo();
+    
+    if (!phoneInfo.isValid) {
+      alert('Please enter a valid number / Por favor ingrese un número válido');
+      return;
+    }
+
+    const formData = {
+      name: formRef.current.name.value,
+      email: formRef.current.email.value,
+      phone: phoneInfo.e164,
+      country: phoneInfo.country
+    };
+
+    // Send data / Enviar datos
+    fetch('/api/contact', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(formData)
+    });
+  };
+
+  return (
+    <form ref={formRef} onSubmit={handleSubmit}>
+      <input name="name" placeholder="Name / Nombre" required />
+      <input name="email" type="email" placeholder="Email" required />
+      
+      <PhoneLibReact
+        ref={phoneLibRef}
+        initialCountry="CO"
+        validateOnInput={true}
+      />
+      
+      <button type="submit">Submit / Enviar</button>
+    </form>
+  );
+}
+```
+
+---
+
+## 🎨 Available Layouts / Layouts Disponibles
+
+### Integrated Layout / Layout Integrado (Default)
+
+The country selector and input are on the same line / El selector de país y el input están en la misma línea:
+
+```javascript
+const phoneLib = new PhoneLib('#container', {
   layout: 'integrated',
-  showDialCode: true  // Muestra +57 en el botón
+  showDialCode: true  // Shows +57 in button / Muestra +57 en el botón
 });
 ```
 
-**Layout Integrado sin código:**
+**With code visible / Con código visible:**
+- Shows / Muestra: `[🇨🇴 +57 ▼] [300 123 4567]`
+
+**Without code visible / Sin código visible:**
 ```javascript
-const phoneLib = new PhoneLib('#phone-container', {
+const phoneLib = new PhoneLib('#container', {
   layout: 'integrated',
-  showDialCode: false  // Solo muestra la bandera
+  showDialCode: false  // Only shows flag / Solo muestra la bandera
 });
 ```
+- Shows / Muestra: `[🇨🇴 ▼] [300 123 4567]`
+
+### Separated Layout / Layout Separado
+
+Fields are separated in a row / Los campos están separados en una fila:
 
-**Layout Separado con código:**
 ```javascript
-const phoneLib = new PhoneLib('#phone-container', {
+const phoneLib = new PhoneLib('#container', {
   layout: 'separated',
-  showDialCode: true  // Muestra campo "Código" separado
+  showDialCode: true  // Shows separate "Code" field / Muestra campo "Código" separado
 });
 ```
 
-**Layout Separado sin código:**
+**With code visible / Con código visible:**
+- Shows / Muestra: `[Country / País: 🇨🇴 Colombia ▼] [Code / Código: +57] [Number / Número: 300 123 4567]`
+
+**Without code visible / Sin código visible:**
 ```javascript
-const phoneLib = new PhoneLib('#phone-container', {
+const phoneLib = new PhoneLib('#container', {
   layout: 'separated',
-  showDialCode: false  // Solo muestra País y Número
+  showDialCode: false  // Only shows Country and Number / Solo muestra País y Número
 });
 ```
+- Shows / Muestra: `[Country / País: 🇨🇴 Colombia ▼] [Number / Número: 300 123 4567]`
 
-### Estilos Personalizados
+---
 
-Puedes personalizar los estilos usando clases CSS o estilos inline:
+## ⚙️ Configuration Options / Opciones de Configuración
+
+### Basic Options / Opciones Básicas
 
-**Con clases CSS personalizadas:**
 ```javascript
-const phoneLib = new PhoneLib('#phone-container', {
-  layout: 'integrated',
-  customClasses: {
-    wrapper: 'mi-clase-personalizada',
-    dropdownButton: 'mi-boton-personalizado',
-    input: 'mi-input-personalizado'
-  }
-});
+{
+  initialCountry: 'CO',              // Initial country / País inicial (ISO2)
+  preferredCountries: ['CO', 'US'],  // Countries that appear first / Países que aparecen primero
+  showHint: true,                    // Show validation hint / Mostrar hint de validación
+  layout: 'integrated',              // 'integrated' or 'separated' / 'integrated' o 'separated'
+  showDialCode: true                 // Show dial code / Mostrar código de marcación
+}
 ```
 
-**Con estilos inline:**
+### Advanced Options / Opciones Avanzadas
+
 ```javascript
-const phoneLib = new PhoneLib('#phone-container', {
-  layout: 'integrated',
+{
+  // Detection and validation / Detección y validación
+  autoDetectCountry: true,            // Auto-detect country / Detectar país automáticamente
+  validateOnInput: false,             // Validate while typing / Validar mientras se escribe
+  
+  // Country filtering / Filtrado de países
+  onlyCountries: ['CO', 'US', 'ES'],  // Only these countries / Solo estos países
+  disabledCountries: ['CU', 'KP'],    // Disable these / Deshabilitar estos
+  excludeCountries: ['XX'],           // Exclude these / Excluir estos
+  
+  // States / Estados
+  readonly: false,                   // Read-only mode / Modo solo lectura
+  disabled: false,                   // Disabled component / Componente deshabilitado
+  
+  // Customization / Personalización
+  placeholder: 'Enter your number',   // Custom placeholder / Placeholder personalizado
+  countryLabel: 'Country',            // Label for selector / Label para selector
+  dialCodeLabel: 'Code',             // Label for code / Label para código
+  phoneLabel: 'Phone number',         // Label for number / Label para número
+  
+  // Messages / Mensajes
+  messages: {
+    invalid: 'Invalid number',
+    valid: '✓ Valid number'
+  },
+  
+  // Styles / Estilos
+  customClasses: {
+    wrapper: 'my-class',
+    input: 'my-input'
+  },
   customStyles: {
-    dropdownButton: {
-      backgroundColor: '#4a90e2',
-      borderRadius: '20px',
-      color: 'white'
-    },
     input: {
-      borderColor: '#4a90e2',
-      fontSize: '18px'
+      borderColor: '#4a90e2'
     }
   }
-});
+}
 ```
 
-**Combinando ambos métodos:**
+### Callbacks and Events / Callbacks y Eventos
+
 ```javascript
-const phoneLib = new PhoneLib('#phone-container', {
-  layout: 'separated',
-  customClasses: {
-    wrapper: 'mi-tema-personalizado'
+{
+  onCountryChange: (country, dialCode, countryName) => {
+    // Country changed / País cambiado
   },
-  customStyles: {
-    row: {
-      gap: '20px'
-    },
-    input: {
-      borderColor: '#27ae60'
-    }
+  onPhoneChange: (phoneNumber, isValid, country) => {
+    // Number changed / Número cambiado
+  },
+  onValidationChange: (isValid, phoneNumber) => {
+    // Validation changed / Validación cambiada
+  },
+  onFocus: () => {
+    // Input focused / Input enfocado
+  },
+  onBlur: () => {
+    // Input blurred / Input perdió foco
   }
-});
+}
 ```
 
-**Elementos personalizables:**
-- `wrapper` - Contenedor principal
-- `dropdownButton` - Botón del selector de país
-- `input` - Campo de entrada de teléfono
-- `dialCodeInput` - Campo de código (solo layout separado)
-- `row` - Fila del grid (solo layout separado)
+---
 
-## API Pública
+## 📚 Public API
 
-### `getCountry()`
-Devuelve el código ISO2 del país seleccionado.
+### Reading Methods / Métodos de Lectura
+
+#### `getCountry()`
+Returns the ISO2 code of the selected country / Devuelve el código ISO2 del país seleccionado.
 
 ```javascript
 const country = phoneLib.getCountry(); // 'CO'
 ```
 
-### `getDialCode()`
-Devuelve el código de marcación del país seleccionado.
+#### `getDialCode()`
+Returns the dial code of the selected country / Devuelve el código de marcación del país seleccionado.
 
 ```javascript
 const dialCode = phoneLib.getDialCode(); // '+57'
 ```
 
-### `getRaw()`
-Devuelve el número ingresado sin formato.
+#### `getRaw()`
+Returns the entered number without formatting (digits only) / Devuelve el número ingresado sin formato (solo dígitos).
 
 ```javascript
 const raw = phoneLib.getRaw(); // '3001234567'
 ```
 
-### `getE164()`
-Devuelve el número en formato E.164.
+#### `getE164()`
+Returns the number in E.164 format / Devuelve el número en formato E.164.
 
 ```javascript
 const e164 = phoneLib.getE164(); // '+573001234567'
 ```
 
-### `isValid()`
-Devuelve `true` si el número es válido, `false` en caso contrario.
+#### `isValid()`
+Returns `true` if the number is valid, `false` otherwise / Devuelve `true` si el número es válido, `false` en caso contrario.
 
 ```javascript
 const isValid = phoneLib.isValid(); // true o false
 ```
 
-### `formatInternational()`
-Devuelve el número en formato internacional.
+#### `formatInternational()`
+Returns the number in international format / Devuelve el número en formato internacional.
 
 ```javascript
 const international = phoneLib.formatInternational(); // '+57 300 123 4567'
 ```
 
-### `formatNational()`
-Devuelve el número en formato nacional.
+#### `formatNational()`
+Returns the number in national format / Devuelve el número en formato nacional.
 
 ```javascript
 const national = phoneLib.formatNational(); // '300 123 4567'
 ```
 
-### `formatRFC3966()`
-Devuelve el número en formato RFC3966.
+#### `formatRFC3966()`
+Returns the number in RFC3966 format / Devuelve el número en formato RFC3966.
 
 ```javascript
 const rfc3966 = phoneLib.formatRFC3966(); // 'tel:+57-300-123-4567'
 ```
 
-### `getNumberType()`
-Devuelve el tipo de número (MOBILE, FIXED_LINE, etc.).
+#### `getNumberType()`
+Returns the number type (MOBILE, FIXED_LINE, etc.) / Devuelve el tipo de número (MOBILE, FIXED_LINE, etc.).
 
 ```javascript
 const type = phoneLib.getNumberType(); // 'MOBILE' o null
 ```
 
-### `getInfo()`
-Devuelve un objeto con toda la información del número.
+#### `getInfo()`
+Returns an object with all number information / Devuelve un objeto con toda la información del número.
 
 ```javascript
 const info = phoneLib.getInfo();
@@ -287,8 +584,8 @@ const info = phoneLib.getInfo();
 // }
 ```
 
-### `getCountryMetadata()`
-Devuelve información completa del país seleccionado.
+#### `getCountryMetadata()`
+Returns complete information about the selected country / Devuelve información completa del país seleccionado.
 
 ```javascript
 const metadata = phoneLib.getCountryMetadata();
@@ -300,51 +597,53 @@ const metadata = phoneLib.getCountryMetadata();
 // }
 ```
 
-### `setCountry(iso2)`
-Establece el país programáticamente.
+### Control Methods / Métodos de Control
+
+#### `setCountry(iso2)`
+Sets the country programmatically / Establece el país programáticamente.
 
 ```javascript
 phoneLib.setCountry('ES');
 ```
 
-### `setPhoneNumber(number)`
-Establece el número telefónico programáticamente.
+#### `setPhoneNumber(number)`
+Sets the phone number programmatically / Establece el número telefónico programáticamente.
 
 ```javascript
 phoneLib.setPhoneNumber('+34600123456');
 ```
 
-### `setValue(country, number)`
-Establece país y número juntos.
+#### `setValue(country, number)`
+Sets both country and number / Establece país y número juntos.
 
 ```javascript
 phoneLib.setValue('ES', '600123456');
 ```
 
-### `enable()` / `disable()`
-Habilita o deshabilita el componente.
+#### `enable()` / `disable()`
+Enables or disables the component / Habilita o deshabilita el componente.
 
 ```javascript
 phoneLib.enable();
 phoneLib.disable();
 ```
 
-### `reset()`
-Resetea el componente a valores iniciales.
+#### `reset()`
+Resets the component to initial values / Resetea el componente a valores iniciales.
 
 ```javascript
 phoneLib.reset();
 ```
 
-### `destroy()`
-Destruye la instancia y limpia recursos.
+#### `destroy()`
+Destroys the instance and cleans up resources / Destruye la instancia y limpia recursos.
 
 ```javascript
 phoneLib.destroy();
 ```
 
-### `updateOptions(newOptions)`
-Actualiza opciones dinámicamente.
+#### `updateOptions(newOptions)`
+Updates options dynamically / Actualiza opciones dinámicamente.
 
 ```javascript
 phoneLib.updateOptions({
@@ -352,104 +651,227 @@ phoneLib.updateOptions({
 });
 ```
 
-## Ejemplos Completos
+---
 
-### Vanilla JavaScript
-- `demo.html` - Layout integrado con código
-- `demo-separated.html` - Layout separado con código
-- `demo-all-layouts.html` - Comparación de todos los layouts disponibles
-- `demo-features.html` - Demostración de todas las nuevas características
-
-### React
-- `demo-react.html` - Ejemplo básico con React (usando Babel Standalone para demo)
-- `phone-lib-react.jsx` - Componente React completo para usar en tu proyecto
-
-Ver estos archivos para ejemplos completos de integración con actualización en tiempo real de la información del número.
+## 🎨 Custom Styling / Estilos Personalizados
 
-## Estructura de Archivos
+### With CSS Classes / Con Clases CSS
 
-```
-phone-lib/
-├── phone-lib.js          # Código principal de la librería (Vanilla JS)
-├── phone-lib.css         # Estilos CSS
-├── phone-lib-react.jsx   # Componente React wrapper
-├── phone-lib-react.js    # Versión CommonJS/ESM del wrapper React
-├── demo.html             # Ejemplo básico Vanilla JS
-├── demo-separated.html   # Ejemplo layout separado
-├── demo-all-layouts.html # Comparación de layouts
-├── demo-features.html    # Nuevas características
-├── demo-react.html       # Ejemplo React (demo)
-├── package.json          # Dependencias
-└── README.md             # Documentación
+```javascript
+const phoneLib = new PhoneLib('#container', {
+  customClasses: {
+    wrapper: 'my-custom-class',
+    dropdownButton: 'my-custom-button',
+    input: 'my-custom-input'
+  }
+});
 ```
 
-## Nuevas Características (v2.0)
+### With Inline Styles / Con Estilos Inline
 
-### Eventos y Callbacks
 ```javascript
-const phoneLib = new PhoneLib('#phone-container', {
-  onCountryChange: (country, dialCode, countryName) => {
-    console.log('País cambiado:', country, dialCode);
-  },
-  onPhoneChange: (phoneNumber, isValid, country) => {
-    console.log('Número cambiado:', phoneNumber);
-  },
-  onValidationChange: (isValid, phoneNumber) => {
-    console.log('Validación:', isValid);
-  },
-  onFocus: () => console.log('Input enfocado'),
-  onBlur: () => console.log('Input perdió foco')
+const phoneLib = new PhoneLib('#container', {
+  customStyles: {
+    dropdownButton: {
+      backgroundColor: '#4a90e2',
+      borderRadius: '20px',
+      color: 'white'
+    },
+    input: {
+      borderColor: '#4a90e2',
+      fontSize: '18px'
+    }
+  }
 });
 ```
 
-### Métodos de Control Programático
+### Customizable Elements / Elementos Personalizables
+
+- `wrapper` - Main container / Contenedor principal
+- `dropdownButton` - Country selector button / Botón del selector de país
+- `input` - Phone input field / Campo de entrada de teléfono
+- `dialCodeInput` - Dial code field (separated layout only) / Campo de código (solo layout separado)
+- `row` - Grid row (separated layout only) / Fila del grid (solo layout separado)
+
+---
+
+## 🔧 Advanced Examples / Ejemplos Avanzados
+
+### Automatic Country Detection / Detección Automática de País
+
 ```javascript
-phoneLib.setCountry('ES');              // Establecer país
-phoneLib.setPhoneNumber('600123456');   // Establecer número
-phoneLib.setValue('ES', '600123456');   // Establecer ambos
-phoneLib.enable();                      // Habilitar
-phoneLib.disable();                     // Deshabilitar
-phoneLib.reset();                       // Resetear
-phoneLib.destroy();                     // Destruir instancia
+const phoneLib = new PhoneLib('#container', {
+  autoDetectCountry: true  // Detects country when entering +34... / Detecta país al ingresar +34...
+});
+
+// User types / Usuario escribe: +34 600 123 456
+// Automatically changes to Spain / Automáticamente cambia a España
 ```
 
-### Detección Automática de País
+### Country Filtering / Filtrado de Países
+
 ```javascript
-const phoneLib = new PhoneLib('#phone-container', {
-  autoDetectCountry: true  // Detecta país automáticamente al ingresar +34...
+const phoneLib = new PhoneLib('#container', {
+  // Only show these countries / Solo mostrar estos países
+  onlyCountries: ['CO', 'US', 'ES', 'MX'],
+  
+  // Disable these countries (appear but can't be selected) / Deshabilitar estos países
+  disabledCountries: ['CU', 'KP'],
+  
+  // Exclude these countries (don't appear in list) / Excluir estos países
+  excludeCountries: ['XX']
 });
 ```
 
-### Filtrado de Países
+### Real-time Validation / Validación en Tiempo Real
+
 ```javascript
-const phoneLib = new PhoneLib('#phone-container', {
-  onlyCountries: ['CO', 'US', 'ES'],      // Solo estos países
-  disabledCountries: ['CU', 'KP'],        // Deshabilitar estos
-  excludeCountries: ['XX']                // Excluir estos
+const phoneLib = new PhoneLib('#container', {
+  validateOnInput: true,  // Validate while user types / Valida mientras el usuario escribe
+  
+  onValidationChange: (isValid) => {
+    if (isValid) {
+      console.log('Valid number! / ¡Número válido!');
+    }
+  }
 });
 ```
 
-### Modo Readonly/Disabled
+### Readonly/Disabled Mode / Modo Readonly/Disabled
+
 ```javascript
-const phoneLib = new PhoneLib('#phone-container', {
-  readonly: true,   // Solo lectura
-  disabled: false   // Deshabilitado
+// Read-only / Solo lectura
+const phoneLib = new PhoneLib('#container', {
+  readonly: true
+});
+
+// Disabled / Deshabilitado
+const phoneLib = new PhoneLib('#container', {
+  disabled: true
 });
 ```
 
-### Métodos Adicionales
+---
+
+## 📱 React Component Props
+
+| Prop | Type | Default | Description / Descripción |
+|------|------|---------|--------------------------|
+| `initialCountry` | string | `'US'` | Initial country (ISO2) / País inicial (ISO2) |
+| `preferredCountries` | array | `[]` | Preferred countries / Países preferidos |
+| `showHint` | boolean | `true` | Show validation hint / Mostrar hint de validación |
+| `layout` | string | `'integrated'` | `'integrated'` or `'separated'` / `'integrated'` o `'separated'` |
+| `showDialCode` | boolean | `true` | Show dial code / Mostrar código de marcación |
+| `autoDetectCountry` | boolean | `false` | Auto-detect country / Detectar país automáticamente |
+| `validateOnInput` | boolean | `false` | Validate while typing / Validar mientras se escribe |
+| `disabledCountries` | array | `[]` | Disabled countries / Países deshabilitados |
+| `onlyCountries` | array | `[]` | Only these countries / Solo estos países |
+| `excludeCountries` | array | `[]` | Exclude these countries / Excluir estos países |
+| `readonly` | boolean | `false` | Read-only mode / Modo solo lectura |
+| `disabled` | boolean | `false` | Disabled component / Componente deshabilitado |
+| `placeholder` | string | `null` | Custom placeholder / Placeholder personalizado |
+| `countryLabel` | string | `'Country'` / `'País'` | Label for selector / Label para selector |
+| `dialCodeLabel` | string | `'Code'` / `'Código'` | Label for code / Label para código |
+| `phoneLabel` | string | `'Phone number'` / `'Número de teléfono'` | Label for number / Label para número |
+| `customClasses` | object | `{}` | Custom CSS classes / Clases CSS personalizadas |
+| `customStyles` | object | `{}` | Inline styles / Estilos inline personalizados |
+| `messages` | object | `{}` | Custom messages / Mensajes personalizables |
+| `ariaLabels` | object | `{}` | ARIA labels / Labels ARIA personalizables |
+| `onCountryChange` | function | `null` | Callback when country changes / Callback cuando cambia el país |
+| `onPhoneChange` | function | `null` | Callback when number changes / Callback cuando cambia el número |
+| `onValidationChange` | function | `null` | Callback when validation changes / Callback cuando cambia la validación |
+| `onFocus` | function | `null` | Callback when focused / Callback cuando se enfoca |
+| `onBlur` | function | `null` | Callback when blurred / Callback cuando pierde foco |
+
+---
+
+## 🧪 Development and Testing / Desarrollo y Pruebas
+
+### Run Demos Locally / Ejecutar Demos Localmente
+
+```bash
+# Install dependencies / Instalar dependencias
+npm install
+
+# Start development server / Iniciar servidor de desarrollo
+npm run serve
+```
+
+This will open `http://localhost:3004` with all available demos / Esto abrirá `http://localhost:3004` con todos los demos disponibles.
+
+### Demo Files / Archivos de Demo
+
+- `demo.html` - Basic integrated layout / Layout integrado básico
+- `demo-separated.html` - Separated layout / Layout separado
+- `demo-all-layouts.html` - All layouts comparison / Comparación de todos los layouts
+- `demo-features.html` - All features / Todas las características
+- `demo-react.html` - React example / Ejemplo con React
+
+---
+
+## 📦 Package Structure / Estructura del Paquete
+
+```
+@jacksonavila/phone-lib/
+├── phone-lib.js          # Main code (Vanilla JS) / Código principal (Vanilla JS)
+├── phone-lib.css         # CSS styles / Estilos CSS
+├── phone-lib-react.jsx   # React component / Componente React
+├── phone-lib-react.js    # CommonJS/ESM React version / Versión CommonJS/ESM React
+└── README.md             # Documentation / Documentación
+```
+
+### Import Paths / Rutas de Importación
+
 ```javascript
-phoneLib.formatNational();        // Formato nacional
-phoneLib.formatRFC3966();         // Formato RFC3966
-phoneLib.getNumberType();         // Tipo (MOBILE, FIXED_LINE, etc.)
-phoneLib.getInfo();               // Objeto completo con toda la info
-phoneLib.getCountryMetadata();    // Metadata del país
+// Main library (Vanilla JS) / Librería principal (Vanilla JS)
+import PhoneLib from '@jacksonavila/phone-lib';
+
+// React component / Componente React
+import PhoneLibReact from '@jacksonavila/phone-lib/react';
+
+// CSS styles / Estilos CSS
+import '@jacksonavila/phone-lib/css';
+
+// Or with full paths / O con rutas completas
+import PhoneLib from '@jacksonavila/phone-lib/phone-lib.js';
+import PhoneLibReact from '@jacksonavila/phone-lib/phone-lib-react.jsx';
+import '@jacksonavila/phone-lib/phone-lib.css';
 ```
 
-## Dependencias
+---
+
+## 🤝 Contributing / Contribuir
+
+Contributions are welcome / Las contribuciones son bienvenidas. Please / Por favor:
+
+1. Fork the project / Haz fork del proyecto
+2. Create a feature branch / Crea una rama para tu feature (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes / Commit tus cambios (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch / Push a la rama (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request / Abre un Pull Request
+
+---
+
+## 📄 License / Licencia
+
+This project is licensed under the MIT License / Este proyecto está bajo la Licencia MIT - see the [LICENSE](LICENSE) file for details / ver el archivo [LICENSE](LICENSE) para más detalles.
+
+---
+
+## 🙏 Acknowledgments / Agradecimientos
+
+- [libphonenumber-js](https://github.com/catamphetamine/libphonenumber-js) - For phone number validation and formatting / Para validación y formato de números telefónicos
+
+---
+
+## 📞 Support / Soporte
+
+If you have questions or find any issues / Si tienes preguntas o encuentras algún problema:
 
-- `libphonenumber-js`: Para validación y formato de números telefónicos
+- Open an [issue](https://github.com/tu-usuario/phone-lib/issues) on GitHub
+- Check the [complete documentation](./USAGE.md) / Consulta la [documentación completa](./USAGE.md)
+- Review the [examples](./demo.html) / Revisa los [ejemplos](./demo.html)
 
-## Licencia
+---
 
-MIT
+**Made with ❤️ for the developer community / Hecho con ❤️ para la comunidad de desarrolladores**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacksonavila/phone-lib",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Librería JavaScript para input de teléfono con selector de país y banderas - Compatible con Vanilla JS y React",
   "main": "phone-lib.js",
   "module": "phone-lib.js",