tailjng

Librería UI y utilidades para Angular 19 con Tailwind CSS v4. Modelo híbrido: lo que es lógica compartida va en npm; los componentes visuales se copian a tu app con el CLI (estilo shadcn/ui).

¿Qué incluye?

Desde npm (import { … } from 'tailjng')

| Área | Contenido | |------|-----------| | Config | TAILJNG_CONFIG — urlBase, socketUrl para API REST | | Colores | JColorsService — variantes (primary, success_soft, error_outline, …) | | Iconos | Registro Icons en .config/icons/icons.lucide.ts (copiado con CLI) + componente JIcon | | Alertas | JAlertDialogService, JAlertToastService | | CRUD / HTTP | JGenericCrudService, JConverterCrudService, params, files, error handler | | Transformación | JTransformService, JCalendarService — fechas, moneda, tablas | | Reportes | JExcelService, filtros Excel/upload | | Interfaces | TableColumn, filtros, formularios, alertas, tema | | Shared | JFormShared, JDialogShared |

Desde el CLI (npx tailjng add <nombre>)

35 componentes UI standalone copiados a src/app/tailjng/ (ruta configurable con .tailjng/paths.json):

| Categoría | Ejemplos | |-----------|----------| | Base | badge, label, button, tooltip, dialog, progress-bar, toggle-radio | | Inputs | input, input-file, input-textarea, input-range, checkbox-input, checkbox-switch | | Selects | select-dropdown, select-multi-dropdown, select-multi-table | | Formularios | form-container, form-validation, form-sidebar | | Datos | table-complete, table-crud-complete, filter-complete, card-complete, paginator-complete | | Otros | alert-dialog, alert-toast, viewer-image, viewer-pdf, theme-generator, coach-mark |

El CLI instala dependencias transitivas automáticamente (ej. button → tooltip).

Los componentes CRUD (table-crud-complete, filter-complete, card-*, …) esperan un backend REST en TAILJNG_CONFIG.urlBase. Compatible con tailjnx (librería backend del mismo ecosistema).

Requisitos

• Angular 19.2+ (19.x dentro del mismo major; no Angular 20/21 aún)
• Tailwind CSS 4.x (incluido si eliges Tailwind al crear el proyecto con ng new) -{
• Peers: lucide-angular, date-fns, exceljs, file-saver (el CLI los instala con init:app si faltan)
• Estilos globales en CSS o SCSS — init:app detecta cuál usa tu app

Inicio rápido

npm install tailjng

Desde la raíz de tu app Angular:

npx tailjng init:app          # Tailwind, providers, estilos (sin UI)
npx tailjng add button          # un componente + deps
npx tailjng list                # ver todos los disponibles

Opcional — alerts y mode-toggle en el mismo paso:

npx tailjng init:app --with-components

Configuración

Providers (init:app genera esto)

// src/app/config/tailjng.providers.ts
import { CurrencyPipe } from '@angular/common';
import { provideHttpClient } from '@angular/common/http';
import { provideAnimations } from '@angular/platform-browser/animations';
import { TAILJNG_CONFIG } from 'tailjng';

export const tailjngProviders = [
  provideHttpClient(),
  provideAnimations(),
  CurrencyPipe,
  {
    provide: TAILJNG_CONFIG,
    useValue: {
      urlBase: 'http://localhost:3000/api/v1',
      socketUrl: 'http://localhost:3000',
    },
  },
];

Estilos

init:app configura @import "tailwindcss", variables @theme y añade en angular.json:

"node_modules/tailjng/src/styles.css"

Uso en código

Servicios (npm)

import {
  JColorsService,
  JAlertToastService,
  JGenericCrudService,
  TAILJNG_CONFIG,
  TableColumn,
} from 'tailjng';

Componentes (copiados con CLI)

import { JButtonComponent } from './tailjng/button/button.component';
import { JDropdownSelectComponent } from './tailjng/select/select-dropdown/dropdown-select.component';
import { JAlertToastComponent } from './tailjng/alert/alert-toast/toast-alert.component';

<JAlertToast />
<JButton [text]="'Guardar'" classes="primary" [icon]="icons.save" (clicked)="save()" />

Configuración — src/app/tailjng/.config/

Colores e iconos viven fuera de los componentes UI, en subcarpetas de .config:

| Subcarpeta | Archivos | |------------|----------| | .config/colors/ | colors.config.ts, colors.safelist.css | | .config/icons/ | icons.lucide.ts (clase Icons) |

Colores — src/app/tailjng/.config/colors/

Las variantes (primary, success_soft, …) las resuelve JColorsService. Tailwind v4 no genera clases solo en runtime, así que cada proyecto tiene una carpeta editable:

| Archivo | Para qué | |---------|----------| | colors.config.ts | Lista de variantes (incluye las 77 por defecto) + las tuyas (brand, etc.) | | colors.safelist.css | Clases Tailwind que el build debe generar (@apply) |

init:app y sync:app crean esa carpeta (sin sobrescribir si ya existe), importan colors.safelist.css en tus estilos globales y registran tailjngColorsProvider.

Import del safelist según el lenguaje de estilos del proyecto:

/* styles.css */
@import "tailwindcss";
@import "./app/tailjng/.config/colors/colors.safelist.css";

/* styles.scss — todos los @use van antes de otras reglas */
@use "tailwindcss";
@use "./app/tailjng/.config/colors/colors.safelist.css";

Si falta la carpeta en un proyecto existente:

npx tailjng sync:app
# o solo los archivos:
npx tailjng add colors

Añadir un color propio — edita colors.config.ts y registra las clases nuevas en el bloque .__tailjng_custom_colors__ de colors.safelist.css:

// colors.config.ts
brand: 'bg-indigo-600 text-white hover:bg-indigo-700 border border-indigo-500 shadow-md',

/* colors.safelist.css */
.__tailjng_custom_colors__ {
  @apply bg-indigo-600 text-white hover:bg-indigo-700 border-indigo-500;
}

Uso en componentes:

<JButton classes="brand" text="Guardar" />

init:app / sync:app registran el provider automáticamente. Manualmente en app.config.ts:

import { tailjngColorsProvider } from './tailjng/.config/colors/colors.config';

providers: [
  tailjngColorsProvider,
  // ...
],

Uso en componentes (igual que siempre):

<JButton classes="primary" … />
<JButton classes="brand" … />

Select con datos estáticos

Opciones en el .ts, binding en el template:

readonly options = [
  { label: 'Pruebas', value: 'pruebas' },
  { label: 'Producción', value: 'produccion' },
];

<JDropdownSelect
  formControlName="environment"
  [options]="options"
  optionLabel="label"
  optionValue="value"
  [isSearch]="false"
  [showClear]="false"
/>

Select / toggle con API

Pasa endpoint, type="searchable" o loadOnInit según el componente; usa JGenericCrudService vía TAILJNG_CONFIG.urlBase.

Comandos CLI

| Comando | Descripción | |---------|-------------| | npx tailjng init:app | Prepara proyecto: Tailwind, deps, providers, estilos | | npx tailjng init:app --yes | Sin prompts interactivos | | npx tailjng init:app --with-components | init + mode-toggle y alerts | | npx tailjng sync:app | Tras npm install tailjng@latest — solo lo nuevo (estilos, deps, angular.json) | | npx tailjng add <nombre> | Instala componente + dependencias | | npx tailjng install-all | Instala los 35 componentes | | npx tailjng list | Lista registry e indica cuáles ya están instalados | | npx tailjng version | Versión del paquete npm instalado |

Si un componente ya existe, el CLI pregunta cómo sobrescribir (uno a uno, todos o omitir).

Estructura en tu proyecto (tras init:app + add)

tu-app/
  .postcssrc.json
  .tailjng/paths.json
  src/
    environment.ts
    app/
      config/tailjng.providers.ts
      tailjng/              ← componentes copiados por el CLI
        button/
        tooltip/
        …

Publicación e instalación

npm view tailjng version
npm install tailjng@latest

Desarrollo del paquete (mantenedores)

Este archivo se publica en npm. El runbook del monorepo está en DEV.md (raíz del workspace).