npm package: @jysperu/browser-alert
Description: Utilidades modernas para gestión de alertas y diálogos en el navegador usando SweetAlert2
Author: JYS Perú
Latest version: 1.0.2

# @jysperu/browser-alert

[![npm version](https://badge.fury.io/js/@jysperu%2Fbrowser-alert.svg)](https://badge.fury.io/js/@jysperu%2Fbrowser-alert)
[![npm downloads](https://img.shields.io/npm/dm/@jysperu/browser-alert)](https://www.npmjs.com/package/@jysperu/browser-alert)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@jysperu/browser-alert)](https://bundlephobia.com/package/@jysperu/browser-alert)

Utilidades modernas para gestión de alertas y diálogos en el navegador usando **SweetAlert2**.

## 🚀 Características

- 🎨 **SweetAlert2** integrado con configuración optimizada
- 🔧 **TypeScript** completamente tipado
- ✅ **Interfaces robustas** para configuración
- 🛡️ **Manejo de errores** comprehensivo

## 📦 Instalación

```bash
npm install @jysperu/browser-alert
```

SweetAlert2 se instala automáticamente como dependencia del paquete.

## ⚡ Inicio Rápido

```typescript
import { alert_success, alert_confirm, alert_loading } from "@jysperu/browser-alert";

// Mensaje de éxito
await alert_success("¡Operación completada exitosamente!");

// Confirmación
const confirmed = await alert_confirm("¿Estás seguro de eliminar este elemento?");
if (confirmed) {
  console.log("Usuario confirmó la acción");
}

// Indicador de carga
alert_loading("Procesando", "Por favor espere...");

// Acceso directo a SweetAlert2
import { Swal } from "@jysperu/browser-alert";

await Swal.fire({
  title: "Configuración personalizada",
  html: "Usa Swal directamente para casos complejos",
  icon: "info",
});
```

## 📚 API Reference

### 🎯 alert_loading

Muestra un diálogo de carga con spinner.

```typescript
function alert_loading(title?: string, html?: string, config?: AlertMessageConfig): Promise<void>;
```

**Parámetros:**

- `title` - Título del diálogo (por defecto: "Guardando datos")
- `html` - Contenido HTML del mensaje
- `config` - Configuración adicional

**Ejemplos:**

```typescript
// Carga básica
alert_loading();

// Carga personalizada
alert_loading("Subiendo archivo", "Procesando imagen, por favor espere...");

// Con configuración adicional
alert_loading("Conectando", "Estableciendo conexión con el servidor...", {
  position: "top",
  toast: false,
});
```

### ✅ alert_confirm

Muestra un diálogo de confirmación.

```typescript
interface AlertConfirmOptions {
  icon?: "question" | "warning" | "info";
  confirmButtonText?: string;
  cancelButtonText?: string;
  hideCancelButton?: boolean;
}

function alert_confirm(html: string, title?: string, options?: AlertConfirmOptions, config?: AlertMessageConfig): Promise<boolean>;
```

**Retorna:** `true` si se confirmó, `false` si se canceló

**Ejemplos:**

```typescript
// Confirmación básica
const result = await alert_confirm("¿Desea continuar?");

// Confirmación personalizada
const result = await alert_confirm("Se eliminarán todos los datos. Esta acción no se puede deshacer.", "Confirmar eliminación", {
  icon: "warning",
  confirmButtonText: "Sí, eliminar",
  cancelButtonText: "Cancelar",
});

// Sin botón de cancelar
const result = await alert_confirm("Por favor confirme que ha leído los términos", "Aceptar términos", {
  hideCancelButton: true,
  confirmButtonText: "He leído y acepto",
});
```

### 💬 alert_message

Muestra un mensaje con icono específico.

```typescript
function alert_message(icon: "success" | "error" | "warning" | "info", html: string, title?: string, config?: AlertMessageConfig): Promise<void>;
```

**Ejemplos:**

```typescript
// Mensaje informativo
await alert_message("info", "El sistema se actualizará en 5 minutos");

// Mensaje de advertencia
await alert_message("warning", "Memoria baja disponible", "Advertencia del sistema");

// Mensaje personalizado
await alert_message("success", "Datos guardados", "Éxito", {
  timer: 3000,
  position: "top-end",
  toast: true,
});
```

### 🎉 alert_success

Muestra un mensaje de éxito.

```typescript
function alert_success(html: string, title?: string, config?: AlertMessageConfig): Promise<void>;
```

**Ejemplos:**

```typescript
// Éxito básico
await alert_success("Usuario creado correctamente");

// Éxito personalizado
await alert_success("Perfil actualizado con éxito", "Cambios guardados", { timer: 1500 });
```

### ❌ alert_error

Muestra un mensaje de error.

```typescript
function alert_error(html: string, title?: string, config?: AlertMessageConfig): Promise<void>;
```

**Ejemplos:**

```typescript
// Error básico
await alert_error("No se pudo conectar con el servidor");

// Error detallado
await alert_error("El archivo es demasiado grande. Máximo permitido: 10MB", "Error de validación", { timer: 8000 });
```

### ⚠️ alert_warning

Muestra un mensaje de advertencia.

```typescript
function alert_warning(html: string, title?: string, config?: AlertMessageConfig): Promise<void>;
```

**Ejemplo:**

```typescript
await alert_warning("La sesión expirará en 5 minutos", "Sesión por expirar");
```

### ℹ️ alert_info

Muestra un mensaje informativo.

```typescript
function alert_info(html: string, title?: string, config?: AlertMessageConfig): Promise<void>;
```

**Ejemplo:**

```typescript
await alert_info("Nueva funcionalidad disponible en el menú principal");
```

### ❌ alert_close

Cierra cualquier diálogo activo.

```typescript
function alert_close(): void;
```

**Ejemplo:**

```typescript
// Cerrar después de 3 segundos
setTimeout(() => {
  alert_close();
}, 3000);
```

## 🔧 Configuración Avanzada

### AlertMessageConfig Interface

```typescript
interface AlertMessageConfig {
  timer?: number; // Tiempo en ms para auto-cerrar
  showConfirmButton?: boolean; // Mostrar botón de confirmación
  position?: "top" | "top-start" | "top-end" | "center" | "center-start" | "center-end" | "bottom" | "bottom-start" | "bottom-end";
  toast?: boolean; // Modo toast (esquina de pantalla)
  [key: string]: any; // Cualquier opción adicional de SweetAlert2
}
```

## 🎯 Casos de Uso Prácticos

### Sistema de Autenticación

```typescript
import { alert_loading, alert_success, alert_error, alert_confirm } from "@jysperu/browser-alert";

class AuthManager {
  static async login(email: string, password: string) {
    // Mostrar indicador de carga
    alert_loading("Iniciando sesión", "Verificando credenciales...");

    try {
      const response = await fetch("/api/login", {
        method: "POST",
        body: JSON.stringify({ email, password }),
        headers: { "Content-Type": "application/json" },
      });

      if (response.ok) {
        await alert_success("¡Bienvenido!", "Inicio de sesión exitoso");
        // Redirigir al dashboard
      } else {
        await alert_error("Credenciales incorrectas", "Error de autenticación");
      }
    } catch (error) {
      await alert_error("No se pudo conectar con el servidor", "Error de conexión");
    }
  }

  static async logout() {
    const confirmed = await alert_confirm("¿Estás seguro de que deseas cerrar sesión?", "Confirmar cierre de sesión", {
      icon: "question",
      confirmButtonText: "Sí, cerrar sesión",
      cancelButtonText: "Cancelar",
    });

    if (confirmed) {
      alert_loading("Cerrando sesión...");
      // Lógica de logout
      await alert_success("Sesión cerrada correctamente");
    }
  }
}
```

## 📦 Build y Distribución

```bash
# Construir el proyecto
npm run build

# Genera automáticamente:
# └── dist/
#     ├── alert.esm.js      # ES Modules
#     ├── alert.cjs.js      # CommonJS
#     ├── alert.umd.js      # UMD
#     └── alert.d.ts        # TypeScript definitions
```

## 🌐 Compatibilidad

- ✅ Todos los navegadores modernos
- ✅ Compatible con frameworks (React, Vue, Angular)
- ✅ SSR friendly
- ✅ TypeScript nativo

## 🔗 Enlaces y Recursos

- 📘 **Repositorio**: [GitLab - browser-alert](https://gitlab.com/tiny.node/browser/alert)
- 🐛 **Issues**: [Reportar problemas](https://gitlab.com/tiny.node/browser/alert/issues)
- 📦 **npm**: [@jysperu/browser-alert](https://www.npmjs.com/package/@jysperu/browser-alert)
- 📚 **SweetAlert2**: [Documentación oficial](https://sweetalert2.github.io/)
- 🏢 **JYS Perú**: [www.jys.pe](https://www.jys.pe)

## 📄 Licencia

**MIT License** - Consulta el archivo [LICENSE](./LICENSE) para detalles completos.

```text
MIT License - Copyright (c) 2025 JYS Perú
```

---

Desarrollado con ❤️ por [**JYS Perú**](https://www.jys.pe)