npm package: @royaltics/utils
Description: 🚀 Una librería de utilidades y componentes UI reutilizables para proyectos JavaScript y TypeScript. Compatible con utilsJS y ESM.
Latest version: 1.1.2

# 📦 Royaltics Utils & UI

🚀 Una librería de utilidades y componentes UI reutilizables para proyectos JavaScript y TypeScript. Compatible con utilsJS y ESM.

---

## 📦 Índice de Componentes

- [Fechas (`src/dates`)](#fechas-srcdates)
- [Números (`src/numbers`)](#números-srcnumbers)
- [Imágenes (`src/images`)](#imágenes-srcimages)
- [Cadenas (`src/string`)](#cadenas-srcstring)
- [Descargas (`src/download`)](#descargas-srcdownload)
- [Plataforma (`src/platform`)](#plataforma-srcplatform)
- [Formularios (`src/forms`)](#formularios-srcforms)

---

## Fechas [`src/dates`](src/dates/index.ts)

- **`parseDate(date, timezone?)`**: Convierte un string a objeto Date.
- **`convertTimeZone(date)`**: Ajusta una fecha a la zona horaria local.
- **`formatDate(date, timezone?, format?)`**: Formatea una fecha a string (`YYYY-MM-DD` o `DD/MM/YYYY`).
- **`formatDateTime(date, timezone?, format?)`**: Formatea fecha y hora.
- **`formatDateLocal(date, timezone?)`**: Formatea fecha a formato local.
- **`formatTimeString(date)`**: Extrae la hora en formato `HH:mm`.
- **`nowTime()`**: Fecha y hora actual en formato string.
- **`nowDate()`**: Fecha actual en formato string.
- **`dateToStringEs(date, format?)`**: Fecha en español, ej: "Lunes, 30 de Marzo del 2023".
- **`monthsToStringEs(month)`**: Nombre del mes en español.
- **`monthsGenerate(count?, letters?)`**: Array de nombres de meses.
- **`addDaysDate(days, date?)`**: Suma días a una fecha.
- **`diffDate(date_start, date_end, type?)`**: Diferencia entre fechas en días, meses o semanas.
- **`formatTimeSince(date)`**: Tiempo transcurrido desde una fecha (ej: "Hace 2 horas").

---

## Números [`src/numbers`](src/numbers/index.ts)

- **`sumFloat(...values)`**: Suma valores como flotantes.
- **`calculateEqPercent(total, value)`**: Calcula el porcentaje de un valor respecto a un total.
- **`defaultFloat(data, default_value?)`**: Convierte a float, valor por defecto si no es válido.
- **`roundFloat(number, decimals?)`**: Redondea un número flotante.
- **`calculateDiscount(price_a, price_b)`**: Calcula el descuento entre dos precios.
- **`addTaxPorcent(price, tax_value, methodInverse?)`**: Suma o resta porcentaje de impuesto.
- **`getUtility(pvp, price, methodInverse?)`**: Calcula utilidad aplicada.
- **`getPercent(a, b)`**: Calcula el porcentaje de `a` respecto a `b`.

---

## Imágenes [`src/images`](src/images/index.ts)

- **`getDataUriFromImage(url, width?, height?)`**: Convierte una imagen a Data URI (base64) con tamaño personalizado.

---

## Cadenas [`src/string`](src/string/index.ts)

- **`fillSpaces(text, limit?, character?)`**: Rellena un texto con caracteres hasta un límite.
- **`randomString(length?)`**: Genera un string aleatorio.
- **`truncateText(message, length?, index?)`**: Trunca un texto a una longitud máxima.

---

## Descargas [`src/download`](src/download/index.ts)

- **`downloadBlob(data, fileName)`**: Fuerza la descarga de un archivo Blob en el navegador.

---

## Plataforma [`src/platform`](src/platform/index.ts)

- **`getDeviceOS()`**: Detecta el sistema operativo del dispositivo.
- **`getDeviceName()`**: Devuelve el nombre del navegador y sistema operativo.
- **`isMobileDevice()`**: Indica si el dispositivo es móvil (por ancho de pantalla).

---

## Formularios [`src/forms`](src/forms/index.ts)

### [`src/forms/format.ts`](src/forms/format.ts)

- **`parseNumberDoc(number)`**: Formatea un número de documento a `001-001-xxxxxx`.
- **`setSequence(number, limit?, serie?)`**: Formatea una secuencia numérica con ceros a la izquierda.
- **`toString(object, options?)`**: Convierte cualquier valor a string, con opciones de formato.

### [`src/forms/validator.ts`](src/forms/validator.ts)

- **`isEmpty(data, minLength?)`**: Verifica si un campo está vacío.
- **`isInteger(value)`**: Verifica si es un entero.
- **`isFloat(value)`**: Verifica si es un flotante.
- **`isUUID(value)`**: Verifica si es un UUID válido.
- **`isNumberDocument(doc_number)`**: Verifica formato de número de documento.
- **`isEmail(value)`**: Verifica si es un email válido.
- **`isURL(value)`**: Verifica si es una URL válida.
- **`isValidForm(inputs, rulesObject, toast?)`**: Valida un objeto de formulario según reglas.

---

## Ejemplo de Uso

```ts
import {
  formatDate,
  sumFloat,
  getDataUriFromImage,
  fillSpaces,
  downloadBlob,
  getDeviceOS,
  isValidForm
} from "royaltics/utils";

console.log(formatDate(new Date())); // "2023-03-30"
console.log(sumFloat("5,599", 2)); // 7.599
getDataUriFromImage("https://ejemplo.com/img.jpg").then(console.log);
console.log(fillSpaces("123", 6)); // "000123"
downloadBlob("Hola mundo", "saludo.txt");
console.log(getDeviceOS()); // "Windows", "Android", etc.

const formRules = {
  email: { rules: ["req", "email"], name: "Correo" }
};
console.log(isValidForm({ email: "test@correo.com" }, formRules)); // true
```

---

## ⚙️ Compilación y Desarrollo

Para compilar la librería:

```sh
pnpm build
```

Para ejecutar en modo desarrollo:

```sh
pnpm dev
```

---

## 📜 Licencia

MIT License © 2025 - Royaltics Solutions