valtech-components 2.0.687 → 2.0.689

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

@@ -0,0 +1,91 @@
+import { Injectable, inject } from '@angular/core';
+import { Router } from '@angular/router';
+
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+@Injectable({
+  providedIn: 'root',
+})
+export class DocsNavigationService {
+  private router = inject(Router);
+
+  /**
+   * Default scroll container selector.
+   * Can be overridden per-call or globally.
+   */
+  private defaultScrollSelector = '.docs-main-scroll';
+
+  /**
+   * Navigate to a route and scroll to top.
+   * @param route - Route segments to navigate to
+   * @param scrollSelector - Optional custom scroll container selector
+   */
+  async navigateAndScroll(route: string[], scrollSelector?: string): Promise<boolean> {
+    const result = await this.router.navigate(route);
+    if (result) {
+      this.scrollToTop(scrollSelector);
+    }
+    return result;
+  }
+
+  /**
+   * Scroll to top of the documentation content.
+   * Tries multiple scroll containers for compatibility.
+   * @param scrollSelector - Optional custom scroll container selector
+   */
+  scrollToTop(scrollSelector?: string): void {
+    const selector = scrollSelector || this.defaultScrollSelector;
+
+    // 1. Try ion-content first (Ionic)
+    const ionContent = document.querySelector('ion-content');
+    if (ionContent && typeof (ionContent as any).scrollToTop === 'function') {
+      (ionContent as any).scrollToTop(0);
+    }
+
+    // 2. Try the main scrollable element
+    const mainScroll = document.querySelector(selector);
+    if (mainScroll) {
+      mainScroll.scrollTop = 0;
+    }
+
+    // 3. Fallback to window/document scroll
+    window.scrollTo({ top: 0, behavior: 'instant' });
+    document.documentElement.scrollTop = 0;
+    document.body.scrollTop = 0;
+  }
+
+  /**
+   * 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 {
+    const element = document.getElementById(elementId);
+    if (element) {
+      element.scrollIntoView({ behavior: 'smooth', block: 'start' });
+    }
+  }
+
+  /**
+   * Set the default scroll container selector.
+   * @param selector - CSS selector for the scroll container
+   */
+  setDefaultScrollSelector(selector: string): void {
+    this.defaultScrollSelector = selector;
+  }
+}

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

@@ -0,0 +1,75 @@
+/**
+ * Service for downloading files and opening links in new tabs.
+ * Provides utility methods for browser-based file downloads and extracting file names from URLs.
+ */
+import { Injectable } from '@angular/core';
+
+@Injectable({
+  providedIn: 'root',
+})
+export class DownloadService {
+  /**
+   * Extracts the file name from a given URL.
+   * @param url The file URL
+   * @returns The file name
+   */
+  getFileNameFromUrl(url: string): string {
+    try {
+      const pathSegments = url.split('/');
+      const lastSegment = pathSegments[pathSegments.length - 1];
+      const fileName = decodeURIComponent(lastSegment);
+      return fileName;
+    } catch (error) {
+      console.error('Error al obtener nombre de archivo: ', JSON.stringify(error));
+      return 'filename';
+    }
+  }
+
+  /**
+   * Opens a given URL in a new browser tab and triggers download if possible.
+   * @param url The file URL
+   */
+  openNewTab(url: string): void {
+    if (url) {
+      const fileName = this.getFileNameFromUrl(url);
+      const link = document.createElement('a');
+      link.href = url;
+      link.download = fileName;
+      link.target = '_blank';
+      document.body.appendChild(link);
+      link.click();
+      document.body.removeChild(link);
+    } else {
+      console.error('La URL no está definida');
+    }
+  }
+
+  /**
+   * Downloads a file from the browser using fetch and triggers a download dialog.
+   * @param url The file URL
+   */
+  downloadLinkFromBrowser(url: string): void {
+    console.log('trying to download file from url');
+    if (url) {
+      fetch(url)
+        .then(response => response.blob())
+        .then(blob => {
+          const url = window.URL.createObjectURL(blob);
+          const link = document.createElement('a');
+          link.href = url;
+
+          const fileName = this.getFileNameFromUrl(url);
+          link.download = `${+new Date()}-${fileName}`;
+          link.target = '_self';
+          link.click();
+
+          window.URL.revokeObjectURL(url);
+        })
+        .catch(error => {
+          console.error('Error al descargar el archivo:', JSON.stringify(error));
+        });
+    } else {
+      console.error('La URL no está definida');
+    }
+  }
+}

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

@@ -0,0 +1,61 @@
+import {
+  EnvironmentProviders,
+  InjectionToken,
+  makeEnvironmentProviders,
+} from '@angular/core';
+import { ValtechFeedbackConfig } from './types';
+
+/**
+ * Token de inyección para la configuración de Feedback.
+ */
+export const VALTECH_FEEDBACK_CONFIG = new InjectionToken<ValtechFeedbackConfig>(
+  'ValtechFeedbackConfig'
+);
+
+/**
+ * Configuración por defecto.
+ */
+export const DEFAULT_FEEDBACK_CONFIG: Partial<ValtechFeedbackConfig> = {
+  feedbackPrefix: '/v1/feedback',
+  maxAttachments: 5,
+  maxFileSize: 10 * 1024 * 1024, // 10MB
+  allowedFileTypes: ['image/*', 'video/*', 'application/pdf'],
+  storagePath: 'feedback',
+};
+
+/**
+ * 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 function provideValtechFeedback(
+  config: ValtechFeedbackConfig
+): EnvironmentProviders {
+  const mergedConfig: ValtechFeedbackConfig = {
+    ...DEFAULT_FEEDBACK_CONFIG,
+    ...config,
+  };
+
+  return makeEnvironmentProviders([
+    { provide: VALTECH_FEEDBACK_CONFIG, useValue: mergedConfig },
+  ]);
+}

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

@@ -0,0 +1,348 @@
+import { Injectable, inject } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { Observable, firstValueFrom } from 'rxjs';
+import { VALTECH_FEEDBACK_CONFIG } from './config';
+import {
+  CreateFeedbackRequest,
+  CreateFeedbackResponse,
+  GetFeedbackResponse,
+  CheckFeedbackResponse,
+  DeviceContext,
+  FeedbackType,
+  ContentRef,
+  EntityRef,
+  ReactionValue,
+  FeedbackFirestoreDoc,
+} from './types';
+import { FirestoreService } from '../firebase/firestore.service';
+import { AuthService } from '../auth/auth.service';
+
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+@Injectable({ providedIn: 'root' })
+export class FeedbackService {
+  private config = inject(VALTECH_FEEDBACK_CONFIG);
+  private http = inject(HttpClient);
+  private firestore = inject(FirestoreService, { optional: true });
+  private auth = inject(AuthService, { optional: true });
+
+  /**
+   * URL base para endpoints de feedback.
+   */
+  private get baseUrl(): string {
+    return `${this.config.apiUrl}${this.config.feedbackPrefix}`;
+  }
+
+  /**
+   * Captura el contexto del dispositivo automáticamente.
+   */
+  captureDeviceContext(): DeviceContext {
+    const ua = navigator.userAgent;
+    return {
+      browser: this.detectBrowser(ua),
+      os: this.detectOS(ua),
+      viewport: `${window.innerWidth}x${window.innerHeight}`,
+      language: navigator.language,
+      userAgent: ua,
+      pageUrl: window.location.href,
+    };
+  }
+
+  /**
+   * 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> {
+    const request: CreateFeedbackRequest = {
+      type,
+      title,
+      description,
+      attachments,
+      contentRef,
+      deviceContext: this.captureDeviceContext(),
+      appId: this.config.appId,
+    };
+
+    return this.http.post<CreateFeedbackResponse>(this.baseUrl, request);
+  }
+
+  /**
+   * Crea un nuevo feedback (versión async/await).
+   */
+  async createAsync(
+    type: FeedbackType,
+    title: string,
+    description: string,
+    attachments: string[] = [],
+    contentRef?: ContentRef
+  ): Promise<CreateFeedbackResponse> {
+    return firstValueFrom(
+      this.create(type, title, description, attachments, contentRef)
+    );
+  }
+
+  /**
+   * Obtiene un feedback por ID (solo el propietario).
+   *
+   * @param feedbackId - ID del feedback
+   * @returns Observable con la respuesta
+   */
+  getById(feedbackId: string): Observable<GetFeedbackResponse> {
+    return this.http.get<GetFeedbackResponse>(`${this.baseUrl}/${feedbackId}`);
+  }
+
+  /**
+   * Obtiene un feedback por ID (versión async/await).
+   */
+  async getByIdAsync(feedbackId: string): Promise<GetFeedbackResponse> {
+    return firstValueFrom(this.getById(feedbackId));
+  }
+
+  /**
+   * Valida si un archivo cumple con las restricciones.
+   */
+  validateFile(file: File): { valid: boolean; error?: string } {
+    // Verificar tamaño
+    if (file.size > this.config.maxFileSize!) {
+      const maxSizeMB = Math.round(this.config.maxFileSize! / (1024 * 1024));
+      return {
+        valid: false,
+        error: `El archivo excede el tamaño máximo de ${maxSizeMB}MB`,
+      };
+    }
+
+    // Verificar tipo
+    const allowedTypes = this.config.allowedFileTypes || [];
+    const isAllowed = allowedTypes.some((pattern) => {
+      if (pattern.endsWith('/*')) {
+        const baseType = pattern.replace('/*', '');
+        return file.type.startsWith(baseType);
+      }
+      return file.type === pattern;
+    });
+
+    if (!isAllowed) {
+      return {
+        valid: false,
+        error: 'Tipo de archivo no permitido',
+      };
+    }
+
+    return { valid: true };
+  }
+
+  /**
+   * Obtiene la configuración actual del servicio.
+   */
+  getConfig(): Readonly<typeof this.config> {
+    return this.config;
+  }
+
+  // =========================================================================
+  // Reaction Methods (Content feedback with emojis)
+  // =========================================================================
+
+  /**
+   * 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);
+   * }
+   * ```
+   */
+  async checkFeedback(
+    entityType: string,
+    entityId: string
+  ): Promise<CheckFeedbackResponse> {
+    // Si no hay usuario autenticado, no puede haber feedback previo
+    // Retornar inmediatamente sin llamar al API (evita 401 y redirect a login)
+    const userId = this.auth?.user()?.userId;
+    if (!userId) {
+      return { operationId: '', hasFeedback: false };
+    }
+
+    // 1. Intentar Firebase primero (si está disponible)
+    if (this.firestore) {
+      try {
+        // Path: feedback/{entityType}/{entityId}/{userId}
+        // FirestoreService agrega automáticamente el prefijo apps/{appId}/
+        const collectionPath = `feedback/${entityType}/${entityId}`;
+        const doc = await this.firestore.getDoc<FeedbackFirestoreDoc>(
+          collectionPath,
+          userId
+        );
+
+        if (doc) {
+          return {
+            operationId: '',
+            hasFeedback: true,
+            feedbackId: doc.feedbackId,
+            type: doc.type as FeedbackType,
+            reactionValue: doc.reactionValue as ReactionValue,
+            createdAt: doc.createdAt?.toISOString(),
+          };
+        }
+
+        // Doc no existe = no hay feedback
+        return { operationId: '', hasFeedback: false };
+      } catch (error) {
+        console.warn('[FeedbackService] Firebase check failed, falling back to API:', error);
+        // Fallback a API
+      }
+    }
+
+    // 2. Fallback: llamar API (solo si hay usuario autenticado)
+    const params = new URLSearchParams({
+      appId: this.config.appId,
+      entityType,
+      entityId,
+    });
+
+    return firstValueFrom(
+      this.http.get<CheckFeedbackResponse>(`${this.baseUrl}/check?${params}`)
+    );
+  }
+
+  /**
+   * 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!'
+   * );
+   * ```
+   */
+  async createReaction(
+    entityRef: EntityRef,
+    value: ReactionValue,
+    comment?: string
+  ): Promise<CreateFeedbackResponse> {
+    const request: CreateFeedbackRequest = {
+      type: 'reaction',
+      entityRef,
+      reactionValue: value,
+      description: comment || '',
+      deviceContext: this.captureDeviceContext(),
+      appId: this.config.appId,
+    };
+
+    return firstValueFrom(
+      this.http.post<CreateFeedbackResponse>(this.baseUrl, request)
+    );
+  }
+
+  /**
+   * 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'
+   * );
+   * ```
+   */
+  async createAnonymousReaction(
+    entityRef: EntityRef,
+    value: ReactionValue,
+    comment?: string
+  ): Promise<CreateFeedbackResponse> {
+    const request = {
+      type: 'reaction' as const,
+      entityRef,
+      reactionValue: value,
+      description: comment || '',
+      deviceContext: this.captureDeviceContext(),
+      appId: this.config.appId,
+    };
+
+    return firstValueFrom(
+      this.http.post<CreateFeedbackResponse>(`${this.baseUrl}/anonymous`, request)
+    );
+  }
+
+  // =========================================================================
+  // Helpers privados para detección de browser/OS
+  // =========================================================================
+
+  private detectBrowser(ua: string): string {
+    if (ua.includes('Edg/')) return 'Edge';
+    if (ua.includes('Chrome/')) return 'Chrome';
+    if (ua.includes('Firefox/')) return 'Firefox';
+    if (ua.includes('Safari/') && !ua.includes('Chrome')) return 'Safari';
+    if (ua.includes('Opera') || ua.includes('OPR/')) return 'Opera';
+    return 'Unknown';
+  }
+
+  private detectOS(ua: string): string {
+    if (ua.includes('Windows NT 10')) return 'Windows 10';
+    if (ua.includes('Windows NT 11')) return 'Windows 11';
+    if (ua.includes('Windows')) return 'Windows';
+    if (ua.includes('Mac OS X')) {
+      const match = ua.match(/Mac OS X (\d+[._]\d+)/);
+      if (match) {
+        return `macOS ${match[1].replace('_', '.')}`;
+      }
+      return 'macOS';
+    }
+    if (ua.includes('Android')) return 'Android';
+    if (ua.includes('iPhone') || ua.includes('iPad')) return 'iOS';
+    if (ua.includes('Linux')) return 'Linux';
+    return 'Unknown';
+  }
+}

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

@@ -0,0 +1,59 @@
+/**
+ * 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...'
+ *     );
+ *   }
+ * }
+ * ```
+ */
+
+// Configuration
+export { VALTECH_FEEDBACK_CONFIG, provideValtechFeedback, DEFAULT_FEEDBACK_CONFIG } from './config';
+
+// Service
+export { FeedbackService } from './feedback.service';
+
+// Types
+export {
+  ValtechFeedbackConfig,
+  FeedbackType,
+  FeedbackStatus,
+  ContentType,
+  ContentRef,
+  DeviceContext,
+  Feedback,
+  CreateFeedbackRequest,
+  CreateFeedbackResponse,
+  GetFeedbackResponse,
+  FeedbackTypeOption,
+  DEFAULT_FEEDBACK_TYPE_OPTIONS,
+} from './types';