npm - @jacksonavila/phone-lib - Versions diffs - 2.0.0 - Mend

@jacksonavila/phone-lib 2.0.0

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 (6) hide show

package/README.md ADDED Viewed

@@ -0,0 +1,455 @@
+# 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**.
+## Características
+- ✅ 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
+## Instalación
+### Desde npm (Después de publicar)
+```bash
+npm install @jacksonavila/phone-lib
+```
+### Desarrollo Local
+```bash
+npm install
+```
+## 🚀 Cómo Probar la Librería
+### Opción Rápida (Recomendada)
+```bash
+# 1. Instalar dependencias
+npm install
+# 2. Iniciar servidor de desarrollo
+npm run serve
+```
+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
+```bash
+# Python 3
+python -m http.server 8000
+# Node.js http-server
+npx http-server . -p 8080 -o
+# PHP
+php -S localhost:8000
+```
+**⚠️ 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)
+## Uso Básico
+### HTML
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <link rel="stylesheet" href="phone-lib.css">
+</head>
+<body>
+  <div id="phone-container"></div>
+  <script type="module">
+    import PhoneLib from './phone-lib.js';
+    const phoneLib = new PhoneLib('#phone-container', {
+      initialCountry: 'CO',
+      preferredCountries: ['CO', 'US', 'ES'],
+      showHint: true
+    });
+  </script>
+</body>
+</html>
+```
+### Opciones de Configuración
+```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)
+});
+```
+### Ejemplos de Layouts
+**Layout Integrado con código:**
+```javascript
+const phoneLib = new PhoneLib('#phone-container', {
+  layout: 'integrated',
+  showDialCode: true  // Muestra +57 en el botón
+});
+```
+**Layout Integrado sin código:**
+```javascript
+const phoneLib = new PhoneLib('#phone-container', {
+  layout: 'integrated',
+  showDialCode: false  // Solo muestra la bandera
+});
+```
+**Layout Separado con código:**
+```javascript
+const phoneLib = new PhoneLib('#phone-container', {
+  layout: 'separated',
+  showDialCode: true  // Muestra campo "Código" separado
+});
+```
+**Layout Separado sin código:**
+```javascript
+const phoneLib = new PhoneLib('#phone-container', {
+  layout: 'separated',
+  showDialCode: false  // Solo muestra País y Número
+});
+```
+### Estilos Personalizados
+Puedes personalizar los estilos usando clases CSS o estilos inline:
+**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'
+  }
+});
+```
+**Con estilos inline:**
+```javascript
+const phoneLib = new PhoneLib('#phone-container', {
+  layout: 'integrated',
+  customStyles: {
+    dropdownButton: {
+      backgroundColor: '#4a90e2',
+      borderRadius: '20px',
+      color: 'white'
+    },
+    input: {
+      borderColor: '#4a90e2',
+      fontSize: '18px'
+    }
+  }
+});
+```
+**Combinando ambos métodos:**
+```javascript
+const phoneLib = new PhoneLib('#phone-container', {
+  layout: 'separated',
+  customClasses: {
+    wrapper: 'mi-tema-personalizado'
+  },
+  customStyles: {
+    row: {
+      gap: '20px'
+    },
+    input: {
+      borderColor: '#27ae60'
+    }
+  }
+});
+```
+**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
+### `getCountry()`
+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.
+```javascript
+const dialCode = phoneLib.getDialCode(); // '+57'
+```
+### `getRaw()`
+Devuelve el número ingresado sin formato.
+```javascript
+const raw = phoneLib.getRaw(); // '3001234567'
+```
+### `getE164()`
+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.
+```javascript
+const isValid = phoneLib.isValid(); // true o false
+```
+### `formatInternational()`
+Devuelve el número en formato internacional.
+```javascript
+const international = phoneLib.formatInternational(); // '+57 300 123 4567'
+```
+### `formatNational()`
+Devuelve el número en formato nacional.
+```javascript
+const national = phoneLib.formatNational(); // '300 123 4567'
+```
+### `formatRFC3966()`
+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.).
+```javascript
+const type = phoneLib.getNumberType(); // 'MOBILE' o null
+```
+### `getInfo()`
+Devuelve un objeto con toda la información del número.
+```javascript
+const info = phoneLib.getInfo();
+// {
+//   country: 'CO',
+//   dialCode: '+57',
+//   raw: '3001234567',
+//   e164: '+573001234567',
+//   international: '+57 300 123 4567',
+//   national: '300 123 4567',
+//   rfc3966: 'tel:+57-300-123-4567',
+//   isValid: true,
+//   type: 'MOBILE',
+//   countryName: 'Colombia'
+// }
+```
+### `getCountryMetadata()`
+Devuelve información completa del país seleccionado.
+```javascript
+const metadata = phoneLib.getCountryMetadata();
+// {
+//   iso2: 'CO',
+//   name: 'Colombia',
+//   dialCode: '+57',
+//   flag: '<img...>'
+// }
+```
+### `setCountry(iso2)`
+Establece el país programáticamente.
+```javascript
+phoneLib.setCountry('ES');
+```
+### `setPhoneNumber(number)`
+Establece el número telefónico programáticamente.
+```javascript
+phoneLib.setPhoneNumber('+34600123456');
+```
+### `setValue(country, number)`
+Establece país y número juntos.
+```javascript
+phoneLib.setValue('ES', '600123456');
+```
+### `enable()` / `disable()`
+Habilita o deshabilita el componente.
+```javascript
+phoneLib.enable();
+phoneLib.disable();
+```
+### `reset()`
+Resetea el componente a valores iniciales.
+```javascript
+phoneLib.reset();
+```
+### `destroy()`
+Destruye la instancia y limpia recursos.
+```javascript
+phoneLib.destroy();
+```
+### `updateOptions(newOptions)`
+Actualiza opciones dinámicamente.
+```javascript
+phoneLib.updateOptions({
+  preferredCountries: ['CO', 'US', 'ES', 'MX']
+});
+```
+## 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.
+## Estructura de Archivos
+```
+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
+```
+## Nuevas Características (v2.0)
+### 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')
+});
+```
+### Métodos de Control Programático
+```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
+```
+### Detección Automática de País
+```javascript
+const phoneLib = new PhoneLib('#phone-container', {
+  autoDetectCountry: true  // Detecta país automáticamente al ingresar +34...
+});
+```
+### Filtrado de Países
+```javascript
+const phoneLib = new PhoneLib('#phone-container', {
+  onlyCountries: ['CO', 'US', 'ES'],      // Solo estos países
+  disabledCountries: ['CU', 'KP'],        // Deshabilitar estos
+  excludeCountries: ['XX']                // Excluir estos
+});
+```
+### Modo Readonly/Disabled
+```javascript
+const phoneLib = new PhoneLib('#phone-container', {
+  readonly: true,   // Solo lectura
+  disabled: false   // Deshabilitado
+});
+```
+### Métodos Adicionales
+```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
+```
+## Dependencias
+- `libphonenumber-js`: Para validación y formato de números telefónicos
+## Licencia
+MIT

package/package.json ADDED Viewed

@@ -0,0 +1,74 @@
+{
+  "name": "@jacksonavila/phone-lib",
+  "version": "2.0.0",
+  "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",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./phone-lib.js",
+      "require": "./phone-lib.js"
+    },
+    "./react": {
+      "import": "./phone-lib-react.jsx",
+      "require": "./phone-lib-react.js"
+    },
+    "./css": "./phone-lib.css"
+  },
+  "scripts": {
+    "serve": "npx http-server . -p 3004 -o",
+    "prepublishOnly": "echo 'Verificando archivos antes de publicar...' && node --check phone-lib.js"
+  },
+  "keywords": [
+    "phone",
+    "telephone",
+    "input",
+    "country",
+    "selector",
+    "flags",
+    "validation",
+    "libphonenumber",
+    "react",
+    "react-component",
+    "vanilla-js",
+    "phone-input",
+    "country-selector",
+    "international-phone"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "bugs": {
+    "url": ""
+  },
+  "homepage": "",
+  "dependencies": {
+    "libphonenumber-js": "^1.11.0"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "files": [
+    "phone-lib.js",
+    "phone-lib.css",
+    "phone-lib-react.jsx",
+    "phone-lib-react.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}

package/phone-lib-react.js ADDED Viewed

@@ -0,0 +1,63 @@
+/**
+ * Versión CommonJS/ESM del wrapper React para PhoneLib
+ * Para usar con import/require estándar
+ */
+import PhoneLib from './phone-lib.js';
+import './phone-lib.css';
+/**
+ * Hook de React para PhoneLib
+ * @param {Object} options - Opciones de configuración
+ * @param {string} options.containerId - ID del contenedor (opcional)
+ * @param {string} options.initialCountry - País inicial (default: 'US')
+ * @param {Array} options.preferredCountries - Países preferidos
+ * @param {boolean} options.showHint - Mostrar hint de validación
+ * @param {string} options.layout - 'integrated' o 'separated'
+ * @param {boolean} options.showDialCode - Mostrar código de marcación
+ * @param {Object} options.customClasses - Clases CSS personalizadas
+ * @param {Object} options.customStyles - Estilos inline personalizados
+ * @param {Function} options.onCountryChange - Callback cuando cambia el país
+ * @param {Function} options.onPhoneChange - Callback cuando cambia el número
+ * @param {Function} options.onValidationChange - Callback cuando cambia la validación
+ * @returns {Object} - Objeto con ref del contenedor y métodos de PhoneLib
+ */
+export function usePhoneLib(options = {}) {
+  const containerRef = React.useRef(null);
+  const phoneLibRef = React.useRef(null);
+  React.useEffect(() => {
+    if (!containerRef.current) return;
+    phoneLibRef.current = new PhoneLib(containerRef.current, options);
+    return () => {
+      if (phoneLibRef.current) {
+        phoneLibRef.current.destroy();
+        phoneLibRef.current = null;
+      }
+    };
+  }, []);
+  React.useEffect(() => {
+    if (!phoneLibRef.current) return;
+    phoneLibRef.current.updateOptions(options);
+  }, [options]);
+  return {
+    containerRef,
+    phoneLib: phoneLibRef.current,
+    // Métodos de acceso rápido
+    getCountry: () => phoneLibRef.current?.getCountry(),
+    getDialCode: () => phoneLibRef.current?.getDialCode(),
+    getRaw: () => phoneLibRef.current?.getRaw(),
+    getE164: () => phoneLibRef.current?.getE164(),
+    isValid: () => phoneLibRef.current?.isValid(),
+    getInfo: () => phoneLibRef.current?.getInfo(),
+    setCountry: (iso2) => phoneLibRef.current?.setCountry(iso2),
+    setPhoneNumber: (number) => phoneLibRef.current?.setPhoneNumber(number),
+    reset: () => phoneLibRef.current?.reset()
+  };
+}
+export default PhoneLib;