valtech-components 2.0.787 → 2.0.795

package/src/lib/services/link-processor.service.ts

@@ -0,0 +1,311 @@
+import { Injectable } from '@angular/core';
+import { DomSanitizer, SafeHtml } from '@angular/platform-browser';
+
+export interface LinkProcessorConfig {
+  /** Whether to open external links in new tab (default: true) */
+  openExternalInNewTab?: boolean;
+  /** Whether to open internal links in new tab (default: false) */
+  openInternalInNewTab?: boolean;
+  /** Custom CSS classes for links */
+  linkClass?: string;
+  /** Custom CSS classes for external links */
+  externalLinkClass?: string;
+  /** Custom CSS classes for internal links */
+  internalLinkClass?: string;
+  /** Whether to process Markdown-style links [text](url) (default: true) */
+  processMarkdownLinks?: boolean;
+}
+
+/**
+ * LinkProcessorService - Service for processing text content to convert URLs and internal routes into clickable links.
+ *
+ * This service automatically detects external URLs (http/https), internal routes (starting with /),
+ * and Markdown-style links [text](url) and converts them into HTML anchor elements with appropriate attributes.
+ *
+ * @example Basic usage:
+ * ```typescript
+ * constructor(private linkProcessor: LinkProcessorService) {}
+ *
+ * processText() {
+ *   const text = 'Visit https://example.com, go to /profile, or [check docs](https://docs.example.com)';
+ *   const processed = this.linkProcessor.processLinks(text);
+ *   // Returns SafeHtml with clickable links
+ * }
+ * ```
+ */
+@Injectable({
+  providedIn: 'root',
+})
+export class LinkProcessorService {
+  // Regex para detectar URLs completas (http/https) - captura toda la URL y luego limpiamos puntuación
+  private readonly urlRegex = /(https?:\/\/[^\s]+)/g;
+
+  // Regex para detectar rutas internas - captura toda la ruta y luego limpiamos puntuación
+  private readonly internalRouteRegex = /(\s|^)(\/[^\s]*)/g;
+
+  // Regex para detectar enlaces estilo Markdown [texto](url)
+  private readonly markdownLinkRegex = /\[([^\]]+)\]\(([^)]+)\)/g;
+
+  constructor(private sanitizer: DomSanitizer) {}
+
+  /**
+   * Limpia la puntuación del final de una URL.
+   * Mantiene caracteres válidos de URL pero remueve signos de puntuación comunes al final.
+   * Preserva parámetros de consulta, fragmentos y caracteres válidos en URLs.
+   */
+  private cleanUrlPunctuation(url: string): string {
+    // Caracteres que consideramos puntuación al final de oración, pero NO parte de URLs
+    // No incluimos & o = que son parte de query params, ni # que es parte de fragmentos
+    const trailingPunctuation = /[.,;!?)]+$/;
+
+    // Casos especiales: si la URL termina con paréntesis pero no tiene paréntesis de apertura
+    // probablemente el paréntesis no es parte de la URL
+    const hasOpeningParen = url.includes('(');
+    const endsWithClosingParen = url.endsWith(')');
+
+    if (endsWithClosingParen && !hasOpeningParen) {
+      // Remover el paréntesis de cierre si no hay uno de apertura
+      url = url.replace(/\)$/, '');
+    }
+
+    return url.replace(trailingPunctuation, '');
+  }
+
+  /**
+   * Procesa texto para convertir enlaces en elementos <a> clickeables.
+   * Detecta automáticamente URLs externas, rutas internas y enlaces estilo Markdown.
+   *
+   * @param text - Texto a procesar
+   * @param config - Configuración del procesamiento
+   * @returns SafeHtml con enlaces procesados o string original
+   *
+   * @example
+   * ```typescript
+   * const result = this.linkProcessor.processLinks(
+   *   'Visit https://example.com, go to /profile, or [check docs](https://docs.example.com)',
+   *   {
+   *     openExternalInNewTab: true,
+   *     openInternalInNewTab: false,
+   *     processMarkdownLinks: true,
+   *     linkClass: 'custom-link'
+   *   }
+   * );
+   * ```
+   */
+  processLinks(text: string, config: LinkProcessorConfig = {}): SafeHtml | string {
+    if (!text) return '';
+
+    const {
+      openExternalInNewTab = true,
+      openInternalInNewTab = false,
+      linkClass = 'processed-link',
+      externalLinkClass = 'external-link',
+      internalLinkClass = 'internal-link',
+      processMarkdownLinks = true,
+    } = config;
+
+    let hasLinks = false;
+    let processedText = text;
+
+    // 1. Procesar enlaces estilo Markdown [texto](url) primero
+    if (processMarkdownLinks) {
+      // Usar exec en bucle (compatible con ES2018)
+      const markdownMatches: RegExpExecArray[] = [];
+      this.markdownLinkRegex.lastIndex = 0;
+      let mdMatch: RegExpExecArray | null;
+      while ((mdMatch = this.markdownLinkRegex.exec(processedText)) !== null) {
+        markdownMatches.push(mdMatch);
+      }
+
+      // Procesar de atrás hacia adelante para mantener las posiciones
+      for (let i = markdownMatches.length - 1; i >= 0; i--) {
+        const match = markdownMatches[i];
+        const [fullMatch, linkText, url] = match;
+        const startIndex = match.index!;
+        const endIndex = startIndex + fullMatch.length;
+
+        hasLinks = true;
+        const isExternal = /^https?:\/\//.test(url);
+        const target = (isExternal ? openExternalInNewTab : openInternalInNewTab)
+          ? isExternal
+            ? ' target="_blank" rel="noopener noreferrer"'
+            : ' target="_blank"'
+          : '';
+        const typeClass = isExternal ? externalLinkClass : internalLinkClass;
+        const classes = `${linkClass} ${typeClass}`.trim();
+        const linkHtml = `<a href="${url}"${target} class="${classes}">${linkText}</a>`;
+
+        processedText =
+          processedText.substring(0, startIndex) + linkHtml + processedText.substring(endIndex);
+      }
+    }
+
+    // 2. Procesar URLs externas directas
+    // Usar exec en bucle (compatible con ES2018)
+    const urlMatches: RegExpExecArray[] = [];
+    this.urlRegex.lastIndex = 0;
+    let urlMatch: RegExpExecArray | null;
+    while ((urlMatch = this.urlRegex.exec(processedText)) !== null) {
+      urlMatches.push(urlMatch);
+    }
+
+    // Procesar de atrás hacia adelante para mantener las posiciones
+    for (let i = urlMatches.length - 1; i >= 0; i--) {
+      const match = urlMatches[i];
+      const [fullMatch, url] = match;
+      const startIndex = match.index!;
+      const endIndex = startIndex + fullMatch.length;
+
+      // Verificar que no esté ya dentro de un enlace HTML existente
+      const textBefore = processedText.substring(0, startIndex);
+      const lastOpenTag = textBefore.lastIndexOf('<a ');
+      const lastCloseTag = textBefore.lastIndexOf('</a>');
+
+      // Si hay un tag <a abierto sin cerrar, no procesamos
+      if (lastOpenTag > lastCloseTag) {
+        continue;
+      }
+
+      // Limpiar puntuación del final de la URL
+      const cleanUrl = this.cleanUrlPunctuation(url);
+      const punctuationRemoved = url !== cleanUrl;
+      const punctuation = punctuationRemoved ? url.substring(cleanUrl.length) : '';
+
+      hasLinks = true;
+      const target = openExternalInNewTab ? ' target="_blank" rel="noopener noreferrer"' : '';
+      const classes = `${linkClass} ${externalLinkClass}`.trim();
+      const linkHtml = `<a href="${cleanUrl}"${target} class="${classes}">${cleanUrl}</a>`;
+
+      // Reemplazar el URL original con el enlace + puntuación si existía
+      const replacement = punctuationRemoved ? linkHtml + punctuation : linkHtml;
+      processedText =
+        processedText.substring(0, startIndex) + replacement + processedText.substring(endIndex);
+    }
+
+    // 3. Procesar rutas internas
+    // Usar exec en bucle (compatible con ES2018)
+    const internalMatches: RegExpExecArray[] = [];
+    this.internalRouteRegex.lastIndex = 0;
+    let internalMatch: RegExpExecArray | null;
+    while ((internalMatch = this.internalRouteRegex.exec(processedText)) !== null) {
+      internalMatches.push(internalMatch);
+    }
+
+    // Procesar de atrás hacia adelante para mantener las posiciones
+    for (let i = internalMatches.length - 1; i >= 0; i--) {
+      const match = internalMatches[i];
+      const [fullMatch, prefix, route] = match;
+      const startIndex = match.index!;
+      const endIndex = startIndex + fullMatch.length;
+
+      // Verificar que no esté ya dentro de un enlace HTML existente
+      const textBefore = processedText.substring(0, startIndex);
+      const lastOpenTag = textBefore.lastIndexOf('<a ');
+      const lastCloseTag = textBefore.lastIndexOf('</a>');
+
+      // Si hay un tag <a abierto sin cerrar, no procesamos
+      if (lastOpenTag > lastCloseTag) {
+        continue;
+      }
+
+      hasLinks = true;
+      const target = openInternalInNewTab ? ' target="_blank"' : '';
+      const classes = `${linkClass} ${internalLinkClass}`.trim();
+      const linkHtml = `<a href="${route}"${target} class="${classes}">${route}</a>`;
+
+      const replacement = `${prefix}${linkHtml}`;
+      processedText =
+        processedText.substring(0, startIndex) + replacement + processedText.substring(endIndex);
+    }
+
+    // Si hay enlaces, sanitizar el HTML
+    if (hasLinks) {
+      return this.sanitizer.bypassSecurityTrustHtml(processedText);
+    }
+
+    return text;
+  }
+
+  /**
+   * Detecta si un texto contiene enlaces (URLs, rutas internas o enlaces Markdown).
+   *
+   * @param text - Texto a analizar
+   * @returns true si contiene enlaces
+   *
+   * @example
+   * ```typescript
+   * const hasLinks = this.linkProcessor.hasLinks('Visit https://example.com or [docs](https://docs.com)');
+   * // Returns: true
+   * ```
+   */
+  hasLinks(text: string): boolean {
+    if (!text) return false;
+
+    // Reset regex indices
+    this.urlRegex.lastIndex = 0;
+    this.internalRouteRegex.lastIndex = 0;
+    this.markdownLinkRegex.lastIndex = 0;
+
+    return (
+      this.urlRegex.test(text) ||
+      this.internalRouteRegex.test(text) ||
+      this.markdownLinkRegex.test(text)
+    );
+  }
+
+  /**
+   * Extrae todos los enlaces de un texto.
+   *
+   * @param text - Texto a analizar
+   * @returns Array de enlaces encontrados con su tipo y texto (si es Markdown)
+   *
+   * @example
+   * ```typescript
+   * const links = this.linkProcessor.extractLinks('Visit https://example.com, /profile, or [docs](https://docs.com)');
+   * // Returns: [
+   * //   { url: 'https://example.com', type: 'external', text: 'https://example.com' },
+   * //   { url: '/profile', type: 'internal', text: '/profile' },
+   * //   { url: 'https://docs.com', type: 'external', text: 'docs' }
+   * // ]
+   * ```
+   */
+  extractLinks(text: string): Array<{ url: string; type: 'external' | 'internal'; text: string }> {
+    if (!text) return [];
+
+    const links: Array<{ url: string; type: 'external' | 'internal'; text: string }> = [];
+
+    // Reset regex indices
+    this.urlRegex.lastIndex = 0;
+    this.internalRouteRegex.lastIndex = 0;
+    this.markdownLinkRegex.lastIndex = 0;
+
+    // Extraer enlaces Markdown primero
+    let match;
+    while ((match = this.markdownLinkRegex.exec(text)) !== null) {
+      const url = match[2];
+      const linkText = match[1];
+      const type = /^https?:\/\//.test(url) ? 'external' : 'internal';
+      links.push({ url, type, text: linkText });
+    }
+
+    // Extraer URLs externas directas
+    while ((match = this.urlRegex.exec(text)) !== null) {
+      const url = match[1];
+      // Verificar que no esté ya capturado como Markdown link
+      if (!links.some(link => link.url === url)) {
+        links.push({ url, type: 'external', text: url });
+      }
+    }
+
+    // Extraer rutas internas directas
+    while ((match = this.internalRouteRegex.exec(text)) !== null) {
+      const url = match[2];
+      // Verificar que no esté ya capturado como Markdown link
+      if (!links.some(link => link.url === url)) {
+        links.push({ url, type: 'internal', text: url });
+      }
+    }
+
+    return links;
+  }
+}

package/src/lib/services/local-storage.service.ts

@@ -0,0 +1,39 @@
+/**
+ * Utility service for interacting with browser localStorage in a type-safe way.
+ * Provides static methods for setting, getting, removing, and clearing items.
+ */
+export class LocalStorageService {
+  /**
+   * Stores a value in localStorage under the given reference key.
+   * @param reference The key to store the value under
+   * @param value The value to store
+   */
+  static set<T>(reference: string, value: T): void {
+    localStorage.setItem(reference, JSON.stringify(value));
+  }
+
+  /**
+   * Retrieves a value from localStorage by key.
+   * @param reference The key to retrieve
+   * @returns The parsed value
+   */
+  static get<T>(reference: string): T {
+    const value = localStorage.getItem(reference);
+    return JSON.parse(value) as T;
+  }
+
+  /**
+   * Removes an item from localStorage by key.
+   * @param reference The key to remove
+   */
+  static remove(reference: string): void {
+    localStorage.removeItem(reference);
+  }
+
+  /**
+   * Clears all items from localStorage.
+   */
+  static clear() {
+    localStorage.clear();
+  }
+}

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

@@ -0,0 +1,86 @@
+import { Injectable } from '@angular/core';
+
+/**
+ * Tipos de idioma soportados
+ */
+export type SupportedLang = 'es' | 'en';
+
+/**
+ * Clave para persistir el idioma en localStorage
+ */
+const LANG_STORAGE_KEY = 'app_lang';
+
+/**
+ * Idioma por defecto
+ */
+const DEFAULT_LANG: SupportedLang = 'es';
+
+/**
+ * Servicio mínimo de localización.
+ *
+ * - Lee el idioma desde localStorage al iniciar
+ * - Proporciona método para cambiar idioma (recarga la página)
+ * - Sin observables ni subscripciones
+ *
+ * @example
+ * // En un componente
+ * locale = inject(LocaleService);
+ *
+ * // Obtener idioma actual
+ * console.log(this.locale.lang); // 'es' o 'en'
+ *
+ * // Cambiar idioma (recarga la página)
+ * this.locale.setLang('en');
+ */
+@Injectable({ providedIn: 'root' })
+export class LocaleService {
+  /**
+   * Idioma actual de la aplicación.
+   * Se lee una vez al iniciar desde localStorage.
+   */
+  readonly lang: SupportedLang;
+
+  constructor() {
+    this.lang = this.getStoredLang();
+  }
+
+  /**
+   * Cambia el idioma de la aplicación.
+   * Guarda en localStorage y recarga la página para aplicar el cambio.
+   *
+   * @param lang Nuevo idioma ('es' o 'en')
+   */
+  setLang(lang: SupportedLang): void {
+    if (lang === this.lang) {
+      return;
+    }
+    localStorage.setItem(LANG_STORAGE_KEY, lang);
+    window.location.reload();
+  }
+
+  /**
+   * Obtiene el idioma almacenado en localStorage.
+   * Si no existe o no es válido, retorna el idioma por defecto.
+   */
+  private getStoredLang(): SupportedLang {
+    const stored = localStorage.getItem(LANG_STORAGE_KEY);
+    if (stored === 'es' || stored === 'en') {
+      return stored;
+    }
+    return DEFAULT_LANG;
+  }
+
+  /**
+   * Verifica si el idioma actual es español
+   */
+  get isSpanish(): boolean {
+    return this.lang === 'es';
+  }
+
+  /**
+   * Verifica si el idioma actual es inglés
+   */
+  get isEnglish(): boolean {
+    return this.lang === 'en';
+  }
+}

package/src/lib/services/markdown-article/legal-content.service.ts

@@ -0,0 +1,152 @@
+import { HttpClient } from '@angular/common/http';
+import { InjectionToken, Injectable, Provider, inject } from '@angular/core';
+import { Observable, catchError, from, map, of, shareReplay, switchMap, throwError } from 'rxjs';
+import { ArticleMetadata } from '../../components/organisms/article/types';
+import { MarkdownArticleParserService } from './markdown-article-parser.service';
+
+export type LegalSlug = 'terms' | 'privacy' | 'cookies' | 'data-usage' | 'legal-notice' | string;
+
+/**
+ * Factory that returns a Record<slug, ArticleMetadata> for a given locale.
+ * Use a dynamic `import()` so each locale module is code-split by the bundler.
+ */
+export type LegalContentFactory = () => Promise<Record<string, ArticleMetadata>>;
+
+export interface LegalContentConfig {
+  /** Pre-generated content factories keyed by locale (e.g. `{ es: () => import('./generated/legal-content.es') ... }`). */
+  factories?: Record<string, LegalContentFactory>;
+  /** Override default `/assets/legal` base path used when no factory matches. */
+  basePath?: string;
+  /** Fallback locale (default `es`). Set null to disable. */
+  fallbackLocale?: string | null;
+}
+
+export const LEGAL_CONTENT_CONFIG = new InjectionToken<LegalContentConfig>('LEGAL_CONTENT_CONFIG');
+
+export interface LegalLoadOptions {
+  /** Two-letter locale code (es, en, pt). */
+  locale?: string;
+  /** Override base path for runtime mode (default `/assets/legal`). */
+  basePath?: string;
+  /** Fallback locale tried when the requested one is missing. Set null to disable. */
+  fallbackLocale?: string | null;
+}
+
+/**
+ * Loads legal articles via one of two modes:
+ *
+ * 1. **Build-time** (preferred): when the app provides `LEGAL_CONTENT_CONFIG.factories`
+ *    via `provideLegalContent()`, the service dynamically imports the matching
+ *    locale module and returns the pre-parsed `ArticleMetadata` synchronously
+ *    (wrapped in an Observable). Each locale is code-split.
+ *
+ * 2. **Runtime**: when no factory matches, falls back to fetching
+ *    `/assets/legal/{locale}/{slug}.md` and parsing on the fly.
+ *
+ * Both modes cache by `locale:slug` so concurrent loads share one promise/HTTP request.
+ */
+@Injectable({ providedIn: 'root' })
+export class LegalContentService {
+  private readonly http = inject(HttpClient);
+  private readonly parser = inject(MarkdownArticleParserService);
+  private readonly config = inject(LEGAL_CONTENT_CONFIG, { optional: true }) ?? {};
+
+  private readonly DEFAULT_BASE = '/assets/legal';
+  private readonly cache = new Map<string, Observable<ArticleMetadata>>();
+  private readonly factoryCache = new Map<string, Promise<Record<string, ArticleMetadata>>>();
+
+  load(slug: LegalSlug, options: LegalLoadOptions = {}): Observable<ArticleMetadata> {
+    const locale = (options.locale ?? 'es').toLowerCase();
+    const fallback =
+      options.fallbackLocale === undefined
+        ? (this.config.fallbackLocale ?? 'es')
+        : options.fallbackLocale;
+
+    const key = `${locale}|${slug}`;
+    const cached = this.cache.get(key);
+    if (cached) return cached;
+
+    const primary = this.loadOne(slug, locale, options.basePath);
+    const stream =
+      fallback && fallback !== locale
+        ? primary.pipe(catchError(() => this.loadOne(slug, fallback, options.basePath)))
+        : primary;
+
+    const shared = stream.pipe(shareReplay({ bufferSize: 1, refCount: false }));
+    this.cache.set(key, shared);
+    return shared;
+  }
+
+  /** Raw Markdown — only available in runtime mode (HTTP). */
+  raw(slug: LegalSlug, options: LegalLoadOptions = {}): Observable<string> {
+    const locale = (options.locale ?? 'es').toLowerCase();
+    const base = options.basePath ?? this.config.basePath ?? this.DEFAULT_BASE;
+    return this.http.get(`${base}/${locale}/${slug}.md`, { responseType: 'text' });
+  }
+
+  /** Clears in-memory caches. Call on runtime locale change. */
+  invalidate(): void {
+    this.cache.clear();
+    this.factoryCache.clear();
+  }
+
+  private loadOne(
+    slug: string,
+    locale: string,
+    basePathOverride?: string
+  ): Observable<ArticleMetadata> {
+    const factory = this.config.factories?.[locale];
+    if (factory) {
+      return from(this.runFactory(locale, factory)).pipe(
+        switchMap(content => {
+          const article = content[slug];
+          return article
+            ? of(article)
+            : throwError(() => new Error(`Legal doc not found: ${locale}/${slug}`));
+        })
+      );
+    }
+    const base = basePathOverride ?? this.config.basePath ?? this.DEFAULT_BASE;
+    return this.fetchAndParse(`${base}/${locale}/${slug}.md`);
+  }
+
+  private runFactory(
+    locale: string,
+    factory: LegalContentFactory
+  ): Promise<Record<string, ArticleMetadata>> {
+    const cached = this.factoryCache.get(locale);
+    if (cached) return cached;
+    const promise = factory();
+    this.factoryCache.set(locale, promise);
+    return promise;
+  }
+
+  private fetchAndParse(url: string): Observable<ArticleMetadata> {
+    return this.http.get(url, { responseType: 'text' }).pipe(
+      switchMap(md =>
+        md && md.trim().length > 0
+          ? of(this.parser.parse(md))
+          : throwError(() => new Error(`Empty legal doc: ${url}`))
+      ),
+      map(parsed => parsed)
+    );
+  }
+}
+
+/**
+ * Wires pre-generated legal content into `LegalContentService`. Call from `main.ts`
+ * (or any `providers: []` array). The factories use dynamic `import()` so each
+ * locale is code-split — only the active locale's bundle is loaded.
+ *
+ * @example
+ * provideLegalContent({
+ *   factories: {
+ *     es: () => import('./app/generated/legal-content.es').then((m) => m.LEGAL_CONTENT_ES),
+ *     en: () => import('./app/generated/legal-content.en').then((m) => m.LEGAL_CONTENT_EN),
+ *     pt: () => import('./app/generated/legal-content.pt').then((m) => m.LEGAL_CONTENT_PT),
+ *   },
+ * })
+ */
+export function provideLegalContent(config: LegalContentConfig): Provider {
+  return { provide: LEGAL_CONTENT_CONFIG, useValue: config };
+}

package/src/lib/services/markdown-article/markdown-article-parser.service.ts

@@ -0,0 +1,15 @@
+import { Injectable } from '@angular/core';
+import { ArticleMetadata } from '../../components/organisms/article/types';
+import { parseMarkdownArticle } from './markdown-article-parser';
+
+/**
+ * Angular service wrapper for the pure {@link parseMarkdownArticle} function.
+ * Provided in root so it can be injected anywhere. The actual parsing logic lives in
+ * `markdown-article-parser.ts` and is also usable from Node scripts (build-time generation).
+ */
+@Injectable({ providedIn: 'root' })
+export class MarkdownArticleParserService {
+  parse(markdown: string, config?: Partial<ArticleMetadata>): ArticleMetadata {
+    return parseMarkdownArticle(markdown, config);
+  }
+}