valtech-components 2.0.795 → 2.0.797

package/lib/services/content/transformer.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Content Transformer
+ *
+ * Transforms ContentDocument instances into ArticleMetadata
+ * for rendering with the val-article component.
+ */
+import { ArticleMetadata } from '../../components/organisms/article/types';
+import { ContentDocument } from './types';
+/**
+ * ContentTransformer converts ContentDocument objects into ArticleMetadata
+ * that can be rendered by the val-article component.
+ *
+ * @example
+ * ```typescript
+ * const doc: BlogPost = { ... };
+ * const article = ContentTransformer.toArticle(doc);
+ * // Use article with <val-article [props]="article">
+ * ```
+ */
+export declare class ContentTransformer {
+    /**
+     * Transforms a ContentDocument into ArticleMetadata
+     *
+     * @param doc - The content document to transform
+     * @returns ArticleMetadata ready for val-article component
+     */
+    static toArticle(doc: ContentDocument): ArticleMetadata;
+    /**
+     * Adds header elements based on document type and metadata
+     */
+    private static addHeader;
+    /**
+     * Adds footer elements based on document type
+     */
+    private static addFooter;
+    /**
+     * Adds author information block
+     */
+    private static addAuthorBlock;
+    /**
+     * Transforms a single content block and adds it to the builder
+     */
+    private static addBlock;
+    /**
+     * Adds a heading block
+     */
+    private static addHeading;
+    /**
+     * Adds a paragraph block
+     */
+    private static addParagraph;
+    /**
+     * Adds a quote block
+     */
+    private static addQuote;
+    /**
+     * Adds a code block
+     */
+    private static addCode;
+    /**
+     * Adds a list block
+     */
+    private static addList;
+    /**
+     * Adds an image block
+     */
+    private static addImage;
+    /**
+     * Adds a callout/note block
+     */
+    private static addCallout;
+    /**
+     * Adds a divider/separator block
+     */
+    private static addDivider;
+    /**
+     * Adds a button block
+     */
+    private static addButton;
+    /**
+     * Adds a command/terminal block
+     */
+    private static addCommand;
+}
+/**
+ * Convenience function to transform a ContentDocument to ArticleMetadata
+ *
+ * @param doc - The content document to transform
+ * @returns ArticleMetadata ready for val-article component
+ *
+ * @example
+ * ```typescript
+ * const article = toArticle(myBlogPost);
+ * ```
+ */
+export declare function toArticle(doc: ContentDocument): ArticleMetadata;

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

@@ -0,0 +1,220 @@
+/**
+ * Content Types System
+ *
+ * This module provides a content abstraction layer that transforms
+ * structured content documents (blog posts, documentation, news articles)
+ * into ArticleMetadata for rendering with val-article component.
+ */
+/**
+ * Author information for content documents
+ */
+export interface ContentAuthor {
+    /** Author's display name */
+    name: string;
+    /** URL to author's avatar image */
+    avatar?: string;
+    /** Author's role or title */
+    role?: string;
+    /** Link to author's profile */
+    profileUrl?: string;
+}
+/**
+ * Common metadata for all content documents
+ */
+export interface ContentMeta {
+    /** Unique identifier */
+    id?: string;
+    /** URL-friendly slug */
+    slug?: string;
+    /** Creation date */
+    createdAt?: Date | string;
+    /** Last update date */
+    updatedAt?: Date | string;
+    /** Publication date */
+    publishedAt?: Date | string;
+    /** Content author */
+    author?: ContentAuthor;
+    /** Tags for categorization */
+    tags?: string[];
+    /** Primary category */
+    category?: string;
+    /** Content locale (e.g., 'es', 'en') */
+    locale?: string;
+}
+/**
+ * Heading block - renders as title or subtitle
+ */
+export interface HeadingBlock {
+    type: 'heading';
+    /** Heading level: 1 = title, 2-3 = subtitle */
+    level: 1 | 2 | 3;
+    /** Heading text */
+    text: string;
+}
+/**
+ * Paragraph block - renders as text
+ */
+export interface ParagraphBlock {
+    type: 'paragraph';
+    /** Paragraph text content */
+    text: string;
+    /** Apply emphasis styling */
+    emphasis?: boolean;
+}
+/**
+ * Quote block - renders as blockquote
+ */
+export interface QuoteBlock {
+    type: 'quote';
+    /** Quote text */
+    text: string;
+    /** Quote author name */
+    author?: string;
+    /** Quote source */
+    source?: string;
+}
+/**
+ * Code block - renders as syntax-highlighted code
+ */
+export interface CodeBlock {
+    type: 'code';
+    /** Code content */
+    code: string;
+    /** Programming language for syntax highlighting */
+    language?: string;
+    /** Code block title/filename */
+    title?: string;
+}
+/**
+ * List block - renders as ordered, unordered, or checklist
+ */
+export interface ListBlock {
+    type: 'list';
+    /** List items (simple strings) */
+    items: string[];
+    /** Render as numbered list */
+    ordered?: boolean;
+    /** Render as checklist with checkmarks */
+    checklist?: boolean;
+}
+/**
+ * Image block - renders as image with optional caption
+ */
+export interface ImageBlock {
+    type: 'image';
+    /** Image source URL */
+    src: string;
+    /** Alt text for accessibility */
+    alt: string;
+    /** Image caption */
+    caption?: string;
+    /** Image alignment */
+    alignment?: 'left' | 'center' | 'right';
+}
+/**
+ * Callout block - renders as highlighted note/warning
+ */
+export interface CalloutBlock {
+    type: 'callout';
+    /** Callout text content */
+    text: string;
+    /** Callout variant determines styling */
+    variant: 'info' | 'warning' | 'success' | 'error';
+    /** Optional title/prefix */
+    title?: string;
+}
+/**
+ * Divider block - renders as separator line
+ */
+export interface DividerBlock {
+    type: 'divider';
+    /** Divider style */
+    style?: 'line' | 'dots' | 'space';
+}
+/**
+ * Button block - renders as call-to-action button
+ */
+export interface ButtonBlock {
+    type: 'button';
+    /** Button text */
+    text: string;
+    /** Link URL (for navigation) */
+    href?: string;
+    /** Action identifier (for event handling) */
+    action?: string;
+    /** Button color */
+    color?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
+    /** Button alignment */
+    alignment?: 'left' | 'center' | 'right';
+}
+/**
+ * Command block - renders as terminal/CLI command
+ */
+export interface CommandBlock {
+    type: 'command';
+    /** Command to display */
+    command: string;
+    /** Show copy button */
+    copyable?: boolean;
+}
+/**
+ * Union type of all content blocks
+ */
+export type ContentBlock = HeadingBlock | ParagraphBlock | QuoteBlock | CodeBlock | ListBlock | ImageBlock | CalloutBlock | DividerBlock | ButtonBlock | CommandBlock;
+/**
+ * Configuration options for content rendering
+ */
+export interface ContentConfig {
+    /** Article theme */
+    theme?: 'light' | 'dark' | 'auto';
+    /** Maximum width of the content container */
+    maxWidth?: string;
+    /** Show metadata (author, date, etc.) */
+    showMeta?: boolean;
+    /** Show table of contents */
+    showTableOfContents?: boolean;
+    /** Center the content container */
+    centered?: boolean;
+}
+/**
+ * Base interface for all content documents.
+ * Generic type T represents the document type discriminator.
+ *
+ * @example
+ * ```typescript
+ * interface BlogPost extends ContentDocument<'blog'> {
+ *   title: string;
+ *   excerpt: string;
+ * }
+ * ```
+ */
+export interface ContentDocument<T extends string = string> {
+    /** Document type discriminator */
+    type: T;
+    /** Document metadata */
+    meta: ContentMeta;
+    /** Array of content blocks */
+    content: ContentBlock[];
+    /** Rendering configuration */
+    config?: ContentConfig;
+}
+/**
+ * Type guard to check if a block is a heading
+ */
+export declare function isHeadingBlock(block: ContentBlock): block is HeadingBlock;
+/**
+ * Type guard to check if a block is a paragraph
+ */
+export declare function isParagraphBlock(block: ContentBlock): block is ParagraphBlock;
+/**
+ * Type guard to check if a block is a code block
+ */
+export declare function isCodeBlock(block: ContentBlock): block is CodeBlock;
+/**
+ * Type guard to check if a block is a list
+ */
+export declare function isListBlock(block: ContentBlock): block is ListBlock;
+/**
+ * Type guard to check if a block is a callout
+ */
+export declare function isCalloutBlock(block: ContentBlock): block is CalloutBlock;

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';