Angular - ngx-core

Paquete: @tiendana/ngx-core

@tiendana/ngx-core es la librería principal para el desarrollo de aplicaciones Angular en Tiendana. Proporciona una colección robusta de componentes, directivas, pipes y utilidades diseñadas para trabajar en armonía con el Sistema de Diseño.

Instalación

npm install @tiendana/ngx-core @tiendana/utils @tiendana/api-types @tiendana/web-foundation @ngx-translate/core

Dependencias Peer

Paquete	Versión	Requerido
@angular/core, @angular/common	>=19	Sí
@tiendana/utils	>=0.4.0	Sí
@ngx-translate/core	>=16.0.4	Sí
@tiendana/api-types	>=1.x.x	Sí
@tiendana/web-foundation	>=0.5.4	Opcional
@angular/router	>=19	Opcional
@amplitude/analytics-browser	>=2.x	Opcional; obligatorio si importas @tiendana/ngx-core/tracking (detalles)

Estructura del Paquete

La librería está modularizada en puntos de entrada secundarios (secondary entry points) para optimizar el tree-shaking y mantener el código organizado.

🏠 Raíz

Paquete: @tiendana/ngx-core

El punto de entrada raíz solo expone la constante NGX_CORE_VERSION. Todo lo demás vive en los puntos de entrada secundarios.

🧩 Componentes UI

Paquete: @tiendana/ngx-core/ui

Contiene todos los componentes visuales y directivas de interfaz. Consulta la vista general de UI.

• Componentes Standalone (Angular 19+)
• Basados en Signals
• Integración nativa con tokens de diseño

🛠️ Pipes

Paquete: @tiendana/ngx-core/pipes

Colección de pipes puros para transformación de datos en plantillas.

• Formateo de monedas y fechas
• Manipulación de strings y arrays

✅ Validadores

Paquete: @tiendana/ngx-core/validators

Validadores personalizados para Angular Reactive Forms.

• Validaciones síncronas y asíncronas
• Validaciones de negocio específicas

📝 Formularios

Paquete: @tiendana/ngx-core/forms

Utilidades para el manejo avanzado de formularios.

• Manejo de errores tipados
• Helpers para ControlValueAccessor

Consulta la vista general de formularios.

📊 Tracking

Paquete: @tiendana/ngx-core/tracking

Analítica de producto declarativa: directiva tdnTrack, TrackingService y proveedor de Amplitude.

• PageView automático por ruta
• Múltiples proveedores
• @amplitude/analytics-browser como peer opcional

Consulta la vista general de Tracking.

🔶 Logomark

Paquete: @tiendana/ngx-core/logomark

Componente tdn-logomark que muestra el logomark animado de Tiendana. Consulta logomark y el módulo base en utilidades.

Características Principales

• Angular 19+: Aprovecha las últimas características como Signals y Control Flow.
• Standalone First: Todos los componentes y directivas son standalone, eliminando la necesidad de NgModules.
• Strict Typing: Desarrollado con TypeScript en modo estricto para máxima seguridad.
• Tree-Shakeable: Importa solo lo que necesitas gracias a los puntos de entrada secundarios.
• Tokens de Configuración: Todos los componentes personalizables exponen tokens de Angular (InjectionToken) para configuración global o por módulo.

Sistema de Tokens de Configuración

Muchos componentes en @tiendana/ngx-core utilizan tokens de Angular (InjectionToken) para permitir la configuración global de comportamientos predeterminados. Esto te permite:

✅ Configurar todos los componentes del mismo tipo desde un solo lugar
✅ Sobrescribir configuraciones a nivel de módulo o componente
✅ Mantener consistencia visual y de comportamiento en toda la aplicación

Ejemplo de Uso

import { bootstrapApplication } from '@angular/platform-browser';
import { TDN_DATE_INPUT_DEFAULT_SETTINGS_TOKEN } from '@tiendana/ngx-core/forms';

bootstrapApplication(AppComponent, {
  providers: [
    {
      provide: TDN_DATE_INPUT_DEFAULT_SETTINGS_TOKEN,
      useValue: {
        inputFormat: 'dd-MM-yyyy',
        autoClose: true
      }
    }
  ]
});

Componentes con Tokens

Los siguientes componentes exponen tokens de configuración:

• TdnInputDateComponent → TDN_DATE_INPUT_DEFAULT_SETTINGS_TOKEN, TDN_DATE_FORMATTER
• TdnInputFileComponent → TDN_INPUT_FILE_DEFAULT_SETTINGS_TOKEN
• TdnInputImageComponent → TDN_INPUT_IMAGE_DEFAULT_SETTINGS_TOKEN
• TdnInputPinComponent → TDN_PIN_INPUT_DEFAULT_SETTINGS
• TdnInputTagComponent → TDN_TAG_INPUT_DEFAULT_SETTINGS
• TdnInputTimeComponent → TDN_TIME_INPUT_DEFAULT_SETTINGS

Consulta la documentación de cada componente para detalles sobre las opciones de configuración disponibles.

Librerías Recomendadas

ngx-mask - Manejo de Máscaras

Para cualquier necesidad de máscaras de entrada (números de teléfono, documentos, tarjetas de crédito, etc.), recomendamos usar ngx-mask.

Esta librería de terceros proporciona:

• ✅ Máscaras dinámicas y personalizables
• ✅ Validación integrada
• ✅ Soporte para Angular Reactive Forms
• ✅ Amplia documentación y casos de uso

Instalación:

npm install ngx-mask

Uso básico:

import { provideEnvironmentNgxMask } from 'ngx-mask';

bootstrapApplication(AppComponent, {
  providers: [
    provideEnvironmentNgxMask()
  ]
});

<input mask="(000) 000-0000" [formControl]="phoneControl" />

Consulta la documentación oficial para ver todos los tipos de máscaras disponibles y configuraciones avanzadas.

Leaflet - Mapas Interactivos

Para implementar mapas interactivos, recomendamos Leaflet directamente sin wrappers adicionales.

Instalación:

npm install leaflet @types/leaflet

Uso básico:

import { Component, ElementRef, viewChild, AfterViewInit } from '@angular/core';
import * as L from 'leaflet';

@Component({
  template: `<div #mapContainer style="height: 400px;"></div>`
})
export class MapComponent implements AfterViewInit {
  mapContainer = viewChild.required<ElementRef<HTMLDivElement>>('mapContainer');
  private map?: L.Map;

  ngAfterViewInit() {
    this.map = L.map(this.mapContainer().nativeElement).setView([4.711, -74.0721], 13);
    
    L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
      attribution: '© OpenStreetMap contributors'
    }).addTo(this.map);
    
    // Integración con Angular - Eventos
    this.map.on('click', (e) => {
      console.log('Clicked at:', e.latlng);
    });
  }
}

Consulta la documentación de Leaflet para más detalles.

Chart.js - Gráficos de Alto Rendimiento

Para visualización de datos con gráficos de ultra performance via canvas, recomendamos Chart.js directamente sin wrappers adicionales.

Instalación:

npm install chart.js

Uso básico:

import { Component, ElementRef, viewChild, AfterViewInit } from '@angular/core';
import { Chart, ChartConfiguration } from 'chart.js/auto';

@Component({
  template: `<canvas #chartCanvas></canvas>`
})
export class ChartComponent implements AfterViewInit {
  chartCanvas = viewChild.required<ElementRef<HTMLCanvasElement>>('chartCanvas');
  private chart?: Chart;

  ngAfterViewInit() {
    const config: ChartConfiguration = {
      type: 'line',
      data: {
        labels: ['Ene', 'Feb', 'Mar', 'Abr', 'May'],
        datasets: [{
          label: 'Ventas',
          data: [65, 59, 80, 81, 56],
          borderColor: '#00D47E',
          backgroundColor: 'rgba(0, 212, 126, 0.1)'
        }]
      },
      options: {
        responsive: true,
        onClick: (event, elements) => {
          // Integración con Angular - Eventos
          if (elements.length > 0) {
            console.log('Clicked element:', elements[0]);
          }
        }
      }
    };

    this.chart = new Chart(this.chartCanvas().nativeElement, config);
  }
}

Consulta la documentación de Chart.js para ver todos los tipos de gráficos disponibles.

Quill - Editor de Texto Enriquecido

Para edición de texto enriquecido, recomendamos Quill junto con su wrapper para Angular.

Instalación:

npm install quill ngx-quill

Uso básico:

import { QuillModule } from 'ngx-quill';

@Component({
  imports: [QuillModule, ReactiveFormsModule],
  template: `
    <quill-editor 
      [formControl]="contentControl"
      [modules]="modules">
    </quill-editor>
  `
})
export class EditorComponent {
  contentControl = new FormControl('');
  
  modules = {
    toolbar: [
      ['bold', 'italic', 'underline'],
      [{ 'list': 'ordered'}, { 'list': 'bullet' }],
      ['link', 'image']
    ]
  };
}

Consulta la documentación de Quill y ngx-quill para personalización avanzada.