valtech-components 2.0.691 → 2.0.692

package/lib/services/confirmation-dialog/confirmation-dialog.service.d.ts

@@ -0,0 +1,71 @@
+import { ConfirmationDialogMetadata, ConfirmationResult, ConfirmationButton } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Service for displaying confirmation dialogs.
+ *
+ * @example Basic usage
+ * const result = await confirmationService.confirm({
+ *   title: 'Delete Item',
+ *   message: 'Are you sure you want to delete this item?',
+ * });
+ *
+ * if (result.confirmed) {
+ *   // User confirmed
+ * }
+ *
+ * @example Custom buttons
+ * const result = await confirmationService.confirm({
+ *   title: 'Save Changes',
+ *   message: 'Do you want to save your changes before leaving?',
+ *   confirmButton: { text: 'Save', color: 'success' },
+ *   cancelButton: { text: 'Discard', color: 'danger' },
+ *   extraButtons: [{ text: 'Cancel', role: 'cancel' }]
+ * });
+ *
+ * @example Destructive action
+ * const result = await confirmationService.confirmDestructive({
+ *   title: 'Delete Account',
+ *   message: 'This action cannot be undone. Are you sure?',
+ * });
+ */
+export declare class ConfirmationDialogService {
+    private alertController;
+    /**
+     * Shows a confirmation dialog and returns the result.
+     * @param options - Configuration for the dialog
+     * @returns Promise resolving to the confirmation result
+     */
+    confirm(options: ConfirmationDialogMetadata): Promise<ConfirmationResult>;
+    /**
+     * Shows a simple confirmation dialog with default buttons.
+     * @param title - Dialog title
+     * @param message - Dialog message
+     * @returns Promise resolving to true if confirmed, false otherwise
+     */
+    confirmSimple(title: string, message: string): Promise<boolean>;
+    /**
+     * Shows a destructive action confirmation with red confirm button.
+     * @param options - Configuration for the dialog
+     * @returns Promise resolving to the confirmation result
+     */
+    confirmDestructive(options: Omit<ConfirmationDialogMetadata, 'confirmButton'> & {
+        confirmButton?: Partial<ConfirmationButton>;
+    }): Promise<ConfirmationResult>;
+    /**
+     * Shows an info alert with just an OK button.
+     * @param title - Alert title
+     * @param message - Alert message
+     */
+    alert(title: string, message: string): Promise<void>;
+    /**
+     * Shows a three-option dialog (Save, Discard, Cancel).
+     * Common for unsaved changes scenarios.
+     * @param title - Dialog title
+     * @param message - Dialog message
+     * @returns Promise resolving to 'save' | 'discard' | 'cancel'
+     */
+    confirmSaveDiscard(title: string, message: string): Promise<'save' | 'discard' | 'cancel'>;
+    private buildButtons;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ConfirmationDialogService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ConfirmationDialogService>;
+}

package/lib/services/confirmation-dialog/types.d.ts

@@ -0,0 +1,61 @@
+import { Color } from '@ionic/core';
+/**
+ * Button configuration for confirmation dialog.
+ */
+export interface ConfirmationButton {
+    /** Button text */
+    text: string;
+    /** Button role */
+    role?: 'cancel' | 'destructive' | 'confirm';
+    /** Button color (Ionic color) */
+    color?: Color;
+    /** CSS class for the button */
+    cssClass?: string;
+    /** Handler function called when button is clicked */
+    handler?: () => void | Promise<void> | boolean | Promise<boolean>;
+}
+/**
+ * Metadata for the confirmation dialog.
+ */
+export interface ConfirmationDialogMetadata {
+    /** Dialog title */
+    title: string;
+    /** Dialog message/content */
+    message: string;
+    /** Confirm button configuration */
+    confirmButton?: ConfirmationButton;
+    /** Cancel button configuration */
+    cancelButton?: ConfirmationButton;
+    /** Additional buttons (between cancel and confirm) */
+    extraButtons?: ConfirmationButton[];
+    /** Allow dismissing by clicking backdrop */
+    backdropDismiss?: boolean;
+    /** CSS class for the alert */
+    cssClass?: string;
+    /** Alert mode */
+    mode?: 'ios' | 'md';
+    /** Unique token identifier */
+    token?: string;
+    /** Translucent backdrop */
+    translucent?: boolean;
+    /** Animated transitions */
+    animated?: boolean;
+    /** Header subtitle */
+    subHeader?: string;
+}
+/**
+ * Result from confirmation dialog.
+ */
+export interface ConfirmationResult {
+    /** Whether the dialog was confirmed */
+    confirmed: boolean;
+    /** The role of the button clicked */
+    role?: string;
+    /** Any data returned */
+    data?: any;
+}
+/**
+ * Default confirmation dialog options.
+ */
+export declare const DEFAULT_CONFIRM_BUTTON: ConfirmationButton;
+export declare const DEFAULT_CANCEL_BUTTON: ConfirmationButton;

package/lib/services/docs/docs-navigation.service.d.ts

@@ -0,0 +1,51 @@
+import * as i0 from "@angular/core";
+/**
+ * Service for handling documentation navigation with scroll management.
+ *
+ * @example
+ * ```typescript
+ * import { DocsNavigationService } from 'valtech-components';
+ *
+ * @Component({...})
+ * export class MyComponent {
+ *   private docsNav = inject(DocsNavigationService);
+ *
+ *   onLinkClick(route: string[]) {
+ *     this.docsNav.navigateAndScroll(route);
+ *   }
+ * }
+ * ```
+ */
+export declare class DocsNavigationService {
+    private router;
+    /**
+     * Default scroll container selector.
+     * Can be overridden per-call or globally.
+     */
+    private defaultScrollSelector;
+    /**
+     * Navigate to a route and scroll to top.
+     * @param route - Route segments to navigate to
+     * @param scrollSelector - Optional custom scroll container selector
+     */
+    navigateAndScroll(route: string[], scrollSelector?: string): Promise<boolean>;
+    /**
+     * Scroll to top of the documentation content.
+     * Tries multiple scroll containers for compatibility.
+     * @param scrollSelector - Optional custom scroll container selector
+     */
+    scrollToTop(scrollSelector?: string): void;
+    /**
+     * Scroll to a specific element by ID.
+     * @param elementId - The ID of the element to scroll to
+     * @param scrollSelector - Optional custom scroll container selector
+     */
+    scrollToElement(elementId: string, scrollSelector?: string): void;
+    /**
+     * Set the default scroll container selector.
+     * @param selector - CSS selector for the scroll container
+     */
+    setDefaultScrollSelector(selector: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DocsNavigationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DocsNavigationService>;
+}

package/lib/services/download.service.d.ts

@@ -0,0 +1,21 @@
+import * as i0 from "@angular/core";
+export declare class DownloadService {
+    /**
+     * Extracts the file name from a given URL.
+     * @param url The file URL
+     * @returns The file name
+     */
+    getFileNameFromUrl(url: string): string;
+    /**
+     * Opens a given URL in a new browser tab and triggers download if possible.
+     * @param url The file URL
+     */
+    openNewTab(url: string): void;
+    /**
+     * Downloads a file from the browser using fetch and triggers a download dialog.
+     * @param url The file URL
+     */
+    downloadLinkFromBrowser(url: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DownloadService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DownloadService>;
+}

package/lib/services/feedback/config.d.ts

@@ -0,0 +1,35 @@
+import { EnvironmentProviders, InjectionToken } from '@angular/core';
+import { ValtechFeedbackConfig } from './types';
+/**
+ * Token de inyección para la configuración de Feedback.
+ */
+export declare const VALTECH_FEEDBACK_CONFIG: InjectionToken<ValtechFeedbackConfig>;
+/**
+ * Configuración por defecto.
+ */
+export declare const DEFAULT_FEEDBACK_CONFIG: Partial<ValtechFeedbackConfig>;
+/**
+ * Provee el servicio de feedback a la aplicación Angular.
+ *
+ * @param config - Configuración de feedback
+ * @returns EnvironmentProviders para usar en bootstrapApplication
+ *
+ * @example
+ * ```typescript
+ * // main.ts
+ * import { bootstrapApplication } from '@angular/platform-browser';
+ * import { provideValtechFeedback } from 'valtech-components';
+ * import { environment } from './environments/environment';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideValtechAuth({ apiUrl: environment.apiUrl }),
+ *     provideValtechFeedback({
+ *       apiUrl: environment.apiUrl,
+ *       appId: 'my-app-name',
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export declare function provideValtechFeedback(config: ValtechFeedbackConfig): EnvironmentProviders;

package/lib/services/feedback/feedback.service.d.ts

@@ -0,0 +1,134 @@
+import { Observable } from 'rxjs';
+import { CreateFeedbackResponse, GetFeedbackResponse, CheckFeedbackResponse, DeviceContext, FeedbackType, ContentRef, EntityRef, ReactionValue } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Servicio para gestionar feedback de usuarios.
+ *
+ * @example
+ * ```typescript
+ * @Component({...})
+ * export class MyComponent {
+ *   private feedbackService = inject(FeedbackService);
+ *
+ *   async submitFeedback() {
+ *     const response = await this.feedbackService.createAsync(
+ *       'feedback',
+ *       'Mi comentario',
+ *       'Descripción detallada...'
+ *     );
+ *     console.log('Feedback enviado:', response.feedbackId);
+ *   }
+ * }
+ * ```
+ */
+export declare class FeedbackService {
+    private config;
+    private http;
+    private firestore;
+    private auth;
+    /**
+     * URL base para endpoints de feedback.
+     */
+    private get baseUrl();
+    /**
+     * Captura el contexto del dispositivo automáticamente.
+     */
+    captureDeviceContext(): DeviceContext;
+    /**
+     * Crea un nuevo feedback.
+     *
+     * @param type - Tipo de feedback
+     * @param title - Título del feedback
+     * @param description - Descripción detallada
+     * @param attachments - URLs de archivos adjuntos (opcional)
+     * @param contentRef - Referencia a contenido específico (opcional)
+     * @returns Observable con la respuesta
+     */
+    create(type: FeedbackType, title: string, description: string, attachments?: string[], contentRef?: ContentRef): Observable<CreateFeedbackResponse>;
+    /**
+     * Crea un nuevo feedback (versión async/await).
+     */
+    createAsync(type: FeedbackType, title: string, description: string, attachments?: string[], contentRef?: ContentRef): Promise<CreateFeedbackResponse>;
+    /**
+     * Obtiene un feedback por ID (solo el propietario).
+     *
+     * @param feedbackId - ID del feedback
+     * @returns Observable con la respuesta
+     */
+    getById(feedbackId: string): Observable<GetFeedbackResponse>;
+    /**
+     * Obtiene un feedback por ID (versión async/await).
+     */
+    getByIdAsync(feedbackId: string): Promise<GetFeedbackResponse>;
+    /**
+     * Valida si un archivo cumple con las restricciones.
+     */
+    validateFile(file: File): {
+        valid: boolean;
+        error?: string;
+    };
+    /**
+     * Obtiene la configuración actual del servicio.
+     */
+    getConfig(): Readonly<typeof this.config>;
+    /**
+     * Verifica si el usuario ya dio feedback para una entidad específica.
+     *
+     * Primero intenta leer de Firebase (rápido, sin latencia de red al backend).
+     * Si Firebase no está disponible o falla, hace fallback a la API.
+     *
+     * @param entityType - Tipo de entidad (article, docs, feature, etc.)
+     * @param entityId - ID de la entidad
+     * @returns Promise con la respuesta de verificación
+     *
+     * @example
+     * ```typescript
+     * const check = await this.feedbackService.checkFeedback('article', 'art-123');
+     * if (check.hasFeedback) {
+     *   console.log('Ya dio feedback:', check.reactionValue);
+     * }
+     * ```
+     */
+    checkFeedback(entityType: string, entityId: string): Promise<CheckFeedbackResponse>;
+    /**
+     * Crea o actualiza una reacción (feedback con emoji).
+     *
+     * @param entityRef - Referencia a la entidad
+     * @param value - Valor de la reacción (negative, neutral, positive)
+     * @param comment - Comentario opcional (máx 500 caracteres)
+     * @returns Promise con la respuesta
+     *
+     * @example
+     * ```typescript
+     * const response = await this.feedbackService.createReaction(
+     *   { entityType: 'article', entityId: 'art-123' },
+     *   'positive',
+     *   'Muy útil!'
+     * );
+     * ```
+     */
+    createReaction(entityRef: EntityRef, value: ReactionValue, comment?: string): Promise<CreateFeedbackResponse>;
+    /**
+     * Crea feedback anónimo (sin autenticación requerida).
+     * Usado para blogs, FAQs y contenido público.
+     *
+     * @param entityRef - Referencia a la entidad
+     * @param value - Valor de la reacción (negative, neutral, positive)
+     * @param comment - Comentario opcional (máx 500 caracteres)
+     * @returns Promise con la respuesta
+     *
+     * @example
+     * ```typescript
+     * // En un blog público
+     * const response = await this.feedbackService.createAnonymousReaction(
+     *   { entityType: 'blog', entityId: 'my-post-slug' },
+     *   'positive'
+     * );
+     * ```
+     */
+    createAnonymousReaction(entityRef: EntityRef, value: ReactionValue, comment?: string): Promise<CreateFeedbackResponse>;
+    private detectBrowser;
+    private detectOS;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FeedbackService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<FeedbackService>;
+}

package/lib/services/feedback/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Valtech Feedback Service
+ *
+ * Servicio para gestionar feedback de usuarios a nivel de plataforma.
+ *
+ * @example
+ * ```typescript
+ * // main.ts - Configuración
+ * import { provideValtechFeedback } from 'valtech-components';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideValtechAuth({ apiUrl: environment.apiUrl }),
+ *     provideValtechFeedback({
+ *       apiUrl: environment.apiUrl,
+ *       appId: 'my-app-name',
+ *     }),
+ *   ],
+ * });
+ *
+ * // component.ts - Uso
+ * import { FeedbackService } from 'valtech-components';
+ *
+ * @Component({...})
+ * export class MyComponent {
+ *   private feedbackService = inject(FeedbackService);
+ *
+ *   async submitFeedback() {
+ *     const response = await this.feedbackService.createAsync(
+ *       'feedback',
+ *       'Título',
+ *       'Descripción...'
+ *     );
+ *   }
+ * }
+ * ```
+ */
+export { VALTECH_FEEDBACK_CONFIG, provideValtechFeedback, DEFAULT_FEEDBACK_CONFIG } from './config';
+export { FeedbackService } from './feedback.service';
+export { ValtechFeedbackConfig, FeedbackType, FeedbackStatus, ContentType, ContentRef, DeviceContext, Feedback, CreateFeedbackRequest, CreateFeedbackResponse, GetFeedbackResponse, FeedbackTypeOption, DEFAULT_FEEDBACK_TYPE_OPTIONS, } from './types';

package/lib/services/feedback/types.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Configuración del servicio de Feedback.
+ */
+export interface ValtechFeedbackConfig {
+    /** URL base de la API */
+    apiUrl: string;
+    /** ID de la aplicación (ej: 'my-valtech-app') */
+    appId: string;
+    /** Prefijo para endpoints (default: '/v1/feedback') */
+    feedbackPrefix?: string;
+    /** Número máximo de adjuntos (default: 5) */
+    maxAttachments?: number;
+    /** Tamaño máximo por archivo en bytes (default: 10MB) */
+    maxFileSize?: number;
+    /** Tipos de archivo permitidos (default: ['image/*', 'video/*', 'application/pdf']) */
+    allowedFileTypes?: string[];
+    /** Ruta en Firebase Storage para adjuntos (default: 'feedback') */
+    storagePath?: string;
+}
+/**
+ * Tipos de feedback disponibles.
+ */
+export type FeedbackType = 'issue' | 'poor-content' | 'feedback' | 'suggestion' | 'reaction';
+/**
+ * Valor de reacción (para feedback tipo emoji).
+ */
+export type ReactionValue = 'negative' | 'neutral' | 'positive';
+/**
+ * Estado de un feedback.
+ */
+export type FeedbackStatus = 'new' | 'reviewed' | 'resolved';
+/**
+ * Tipos de contenido para referencia.
+ */
+export type ContentType = 'article' | 'faq' | 'news' | 'page' | 'product' | 'event' | 'other';
+/**
+ * Referencia a contenido específico.
+ */
+export interface ContentRef {
+    contentId: string;
+    contentType: ContentType;
+}
+/**
+ * Referencia a entidad (para reactions y feedback de contenido).
+ */
+export interface EntityRef {
+    /** Tipo de entidad: 'article', 'docs', 'feature', 'bug', etc. */
+    entityType: string;
+    /** ID de la entidad */
+    entityId: string;
+}
+/**
+ * Contexto del dispositivo del usuario.
+ */
+export interface DeviceContext {
+    browser: string;
+    os: string;
+    viewport: string;
+    language: string;
+    userAgent: string;
+    pageUrl: string;
+}
+/**
+ * Entrada de feedback completa.
+ */
+export interface Feedback {
+    feedbackId: string;
+    appId: string;
+    userId: string;
+    type: FeedbackType;
+    title: string;
+    description: string;
+    attachments: string[];
+    contentRef?: ContentRef;
+    entityRef?: EntityRef;
+    reactionValue?: ReactionValue;
+    deviceContext: DeviceContext;
+    status: FeedbackStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Request para crear feedback.
+ */
+export interface CreateFeedbackRequest {
+    type: FeedbackType;
+    title?: string;
+    description?: string;
+    attachments?: string[];
+    contentRef?: ContentRef;
+    entityRef?: EntityRef;
+    reactionValue?: ReactionValue;
+    deviceContext: DeviceContext;
+    appId: string;
+}
+/**
+ * Response al crear feedback.
+ */
+export interface CreateFeedbackResponse {
+    operationId: string;
+    feedbackId: string;
+    status: FeedbackStatus;
+    createdAt: string;
+}
+/**
+ * Response al obtener feedback.
+ */
+export interface GetFeedbackResponse {
+    operationId: string;
+    feedback: Feedback;
+}
+/**
+ * Opciones de tipo de feedback para UI.
+ */
+export interface FeedbackTypeOption {
+    value: FeedbackType;
+    label: string;
+    description?: string;
+    icon?: string;
+}
+/**
+ * Configuración por defecto de tipos de feedback.
+ */
+export declare const DEFAULT_FEEDBACK_TYPE_OPTIONS: FeedbackTypeOption[];
+/**
+ * Response al verificar si existe feedback para una entidad.
+ */
+export interface CheckFeedbackResponse {
+    operationId: string;
+    hasFeedback: boolean;
+    feedbackId?: string;
+    type?: FeedbackType;
+    reactionValue?: ReactionValue;
+    createdAt?: string;
+}
+/**
+ * Request para listar feedback (admin).
+ */
+export interface ListFeedbackRequest {
+    appId?: string;
+    type?: FeedbackType;
+    status?: FeedbackStatus;
+    entityType?: string;
+    entityId?: string;
+    userId?: string;
+    dateFrom?: string;
+    dateTo?: string;
+    limit?: number;
+    nextToken?: string;
+}
+/**
+ * Response al listar feedback.
+ */
+export interface ListFeedbackResponse {
+    operationId: string;
+    feedbacks: Feedback[];
+    nextToken?: string;
+    count: number;
+}
+/**
+ * Documento de feedback en Firestore.
+ * Usado para lectura rápida del estado de feedback del usuario.
+ *
+ * Path: apps/{appId}/feedback/{entityType}/{entityId}/{userId}
+ */
+export interface FeedbackFirestoreDoc {
+    id?: string;
+    feedbackId: string;
+    type: string;
+    reactionValue: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}

package/lib/services/firebase/analytics-error-handler.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Analytics Error Handler
+ *
+ * ErrorHandler personalizado que envía errores no capturados a Firebase Analytics.
+ * Se activa si enableErrorTracking=true en analyticsConfig.
+ */
+import { ErrorHandler } from '@angular/core';
+import * as i0 from "@angular/core";
+/**
+ * ErrorHandler que trackea errores en Firebase Analytics.
+ *
+ * Captura errores no manejados de la aplicación y los envía a GA4
+ * como eventos 'error_occurred'. También delega al ErrorHandler
+ * default para mantener el comportamiento de console.error.
+ *
+ * @example
+ * ```typescript
+ * // Se activa automáticamente si enableErrorTracking=true
+ * provideValtechFirebase({
+ *   firebase: environment.firebase,
+ *   enableAnalytics: true,
+ *   analyticsConfig: {
+ *     enableErrorTracking: true,
+ *   },
+ * });
+ * ```
+ */
+export declare class AnalyticsErrorHandler implements ErrorHandler {
+    private readonly analytics;
+    private readonly defaultHandler;
+    /**
+     * Maneja un error no capturado.
+     * Envía el error a Analytics y luego al handler default.
+     */
+    handleError(error: unknown): void;
+    /**
+     * Trackea el error en Analytics
+     */
+    private trackError;
+    /**
+     * Extrae información útil del error
+     */
+    private extractErrorInfo;
+    /**
+     * Verifica si es un PromiseRejectionEvent
+     */
+    private isPromiseRejection;
+    /**
+     * Obtiene la URL actual de forma segura
+     */
+    private getCurrentUrl;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AnalyticsErrorHandler, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AnalyticsErrorHandler>;
+}

package/lib/services/firebase/analytics-router-tracker.d.ts

@@ -0,0 +1,51 @@
+import { ValtechFirebaseConfig } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Tracker automático de page views via Router.
+ *
+ * Este servicio escucha eventos de navegación del Router y registra
+ * page views automáticamente en Firebase Analytics.
+ *
+ * Se excluyen rutas configuradas en `analyticsConfig.excludeRoutes`.
+ *
+ * @example
+ * ```typescript
+ * // Se activa automáticamente si enablePageViewTracking=true
+ * provideValtechFirebase({
+ *   firebase: environment.firebase,
+ *   enableAnalytics: true,
+ *   analyticsConfig: {
+ *     enablePageViewTracking: true,
+ *     excludeRoutes: ['/admin/*', '/debug/*'],
+ *   },
+ * });
+ * ```
+ */
+export declare class AnalyticsRouterTracker {
+    private config;
+    private readonly analytics;
+    private readonly router;
+    private readonly destroyRef;
+    private readonly excludePatterns;
+    private readonly enabled;
+    constructor(config: ValtechFirebaseConfig);
+    /**
+     * Inicia el tracking de navegación
+     */
+    private startTracking;
+    /**
+     * Compila patrones de exclusión a RegExp
+     */
+    private compileExcludePatterns;
+    /**
+     * Verifica si una URL debe ser excluida del tracking
+     */
+    private isExcluded;
+    /**
+     * Registra un page view manualmente.
+     * Útil para casos donde necesitas trackear manualmente.
+     */
+    trackPageView(path: string, title?: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AnalyticsRouterTracker, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AnalyticsRouterTracker>;
+}