valtech-components 2.0.821 → 2.0.823

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/donation/config.d.ts

@@ -0,0 +1,33 @@
+import { EnvironmentProviders, InjectionToken } from '@angular/core';
+import { ValtechDonationConfig } from './types';
+/**
+ * Token de inyección para la configuración de Donation/Support.
+ */
+export declare const VALTECH_DONATION_CONFIG: InjectionToken<ValtechDonationConfig>;
+/** Configuración por defecto — sin métodos habilitados. */
+export declare const DEFAULT_DONATION_CONFIG: Partial<ValtechDonationConfig>;
+/**
+ * Provee el feature de aportes (Support) a la aplicación Angular.
+ *
+ * Cada app del factory declara qué métodos habilita. La vista de Support
+ * (heredada o local) renderiza solo los métodos configurados.
+ *
+ * @example
+ * ```typescript
+ * // main.ts
+ * provideValtechDonations({
+ *   appId: 'showcase',
+ *   methods: ['coffee', 'bank', 'ads'],
+ *   coffee: { provider: 'buymeacoffee', url: 'https://buymeacoffee.com/valtech' },
+ *   bank: {
+ *     accounts: [{
+ *       country: 'CL', bank: 'Banco X', accountType: 'Cuenta Corriente',
+ *       number: '000000000', taxId: '11.111.111-1', holder: 'Valtech SpA',
+ *       email: 'aportes@valtech.com', currency: 'CLP',
+ *     }],
+ *   },
+ *   ads: { provider: 'admob', rewardedUnitId: 'ca-app-pub-xxx' },
+ * }),
+ * ```
+ */
+export declare function provideValtechDonations(config: ValtechDonationConfig): EnvironmentProviders;

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

@@ -0,0 +1,54 @@
+import { BankAccount, DonationActionResult, DonationMethod } from './types';
+import * as i0 from "@angular/core";
+/**
+ * `DonationService`
+ *
+ * Servicio cross-app para el feature de aportes voluntarios (Support).
+ * Patrón factory: cada app llama `provideValtechDonations(...)` y este
+ * servicio expone solo los métodos habilitados.
+ *
+ * **Fase 0 (placeholder)** — abre links externos + expone datos de config.
+ * Sin backend. Fases futuras: rewarded ads reales, webhook de café,
+ * registro de intents para una página de transparencia.
+ *
+ * @example
+ * ```typescript
+ * private donations = inject(DonationService);
+ *
+ * methods = this.donations.enabledMethods();  // ['coffee', 'bank']
+ * onCoffee() { this.donations.openCoffee(); }
+ * accounts = this.donations.bankAccounts();
+ * ```
+ */
+export declare class DonationService {
+    private readonly config;
+    /** Último intent registrado — útil para tests / debugging / UI feedback. */
+    private readonly _lastIntent;
+    readonly lastIntent: import("@angular/core").Signal<DonationMethod>;
+    /** Métodos habilitados por la app, en orden de config. */
+    readonly enabledMethods: import("@angular/core").Signal<DonationMethod[]>;
+    /** `true` si el método está habilitado en la config de la app. */
+    isEnabled(method: DonationMethod): boolean;
+    /** Cuentas bancarias configuradas (vacío si `bank` no está habilitado). */
+    bankAccounts(): BankAccount[];
+    /** Cuentas filtradas por país ISO — para apps multi-mercado. */
+    bankAccountsByCountry(country: string): BankAccount[];
+    /**
+     * Abre el checkout de "café" (Buy Me a Coffee / Ko-fi) en una pestaña nueva.
+     * El proveedor es el merchant of record — Valtech no procesa el pago.
+     */
+    openCoffee(): DonationActionResult;
+    /**
+     * Muestra un anuncio rewarded (opt-in). **Fase 0: no implementado** —
+     * placeholder hasta integrar el plugin de ads (AdMob/AdSense) + la
+     * categoría de consentimiento. Retorna `not-supported`.
+     */
+    showRewardedAd(): Promise<DonationActionResult>;
+    /**
+     * Registra la intención de aporte. **Fase 0: solo estado local.**
+     * Fase 4 — POST a un endpoint para una página de transparencia.
+     */
+    recordIntent(method: DonationMethod): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<DonationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<DonationService>;
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Valtech Donation / Support Service
+ *
+ * Feature cross-app de aportes voluntarios. Patrón factory: cada app llama
+ * `provideValtechDonations(...)` y habilita los métodos que quiera
+ * (`ads` · `coffee` · `bank`).
+ *
+ * Importante (legal): el dinero recibido por una entidad con fines de lucro
+ * es ingreso afecto a impuesto, NO una donación deducible. La UI debe usar
+ * lenguaje de "aporte voluntario / apoyo", nunca "donación".
+ *
+ * @example
+ * ```typescript
+ * // main.ts
+ * provideValtechDonations({
+ *   appId: 'showcase',
+ *   methods: ['coffee', 'bank'],
+ *   coffee: { provider: 'buymeacoffee', url: 'https://buymeacoffee.com/valtech' },
+ *   bank: { accounts: [ ... ] },
+ * }),
+ * ```
+ */
+export { VALTECH_DONATION_CONFIG, provideValtechDonations, DEFAULT_DONATION_CONFIG, } from './config';
+export { DonationService } from './donation.service';
+export { DonationMethod, CoffeeProvider, AdsProvider, BankAccount, CoffeeConfig, AdsConfig, ValtechDonationConfig, DonationActionResult, } from './types';

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

@@ -0,0 +1,85 @@
+/**
+ * Valtech Donation / Support — tipos.
+ *
+ * Nota legal importante: el dinero recibido por una entidad con fines de lucro
+ * NO es una "donación" deducible de impuestos — es ingreso afecto. Por eso la
+ * UI debe usar lenguaje de "aporte voluntario / apoyo", nunca "donación" en su
+ * sentido jurídico. Ver `docs/` (pendiente) y la vista Support del consumer.
+ */
+/**
+ * Métodos de aporte soportados.
+ * - `ads`    — el usuario ve publicidad rewarded (opt-in) para apoyar.
+ * - `coffee` — pago único vía proveedor externo (Buy Me a Coffee / Ko-fi).
+ * - `bank`   — transferencia bancaria directa (se muestran los datos).
+ */
+export type DonationMethod = 'ads' | 'coffee' | 'bank';
+/** Proveedor del método "café". El merchant of record es el proveedor. */
+export type CoffeeProvider = 'buymeacoffee' | 'kofi' | 'custom';
+/** Proveedor de publicidad rewarded. */
+export type AdsProvider = 'admob' | 'adsense' | 'custom';
+/**
+ * Datos de una cuenta bancaria para transferencia. Pensado para ser
+ * por-país (el modelo factory es 1 producto = 1 dominio, con datos
+ * fiscales/bancarios distintos por mercado).
+ */
+export interface BankAccount {
+    /** ISO country code — ej. 'CL', 'AR', 'MX'. */
+    country: string;
+    /** Nombre del banco. */
+    bank: string;
+    /** Tipo de cuenta — ej. 'Cuenta Corriente', 'Vista', 'Checking'. */
+    accountType: string;
+    /** Número de cuenta / IBAN / CBU. */
+    number: string;
+    /** Identificador fiscal del titular — RUT, CUIT, RFC, etc. */
+    taxId: string;
+    /** Nombre del titular de la cuenta. */
+    holder: string;
+    /** Email para enviar comprobante de transferencia. */
+    email?: string;
+    /** Moneda — ej. 'CLP', 'USD'. */
+    currency?: string;
+}
+/** Config del método "café". */
+export interface CoffeeConfig {
+    provider: CoffeeProvider;
+    /** URL pública del perfil (BMC/Ko-fi) o checkout custom. */
+    url: string;
+}
+/** Config del método "ads" (rewarded, opt-in). */
+export interface AdsConfig {
+    provider: AdsProvider;
+    /** ID de la unidad de anuncio rewarded. */
+    rewardedUnitId?: string;
+}
+/**
+ * Configuración del feature Donation/Support.
+ *
+ * Cada app del factory declara qué métodos habilita. Una vista heredada
+ * (`val-*` page) renderiza solo los métodos en `methods`.
+ */
+export interface ValtechDonationConfig {
+    /** AppID — para tracking de intents (ej. analytics). */
+    appId?: string;
+    /** Métodos habilitados, en orden de aparición en la UI. */
+    methods: DonationMethod[];
+    /** Config del método café — requerido si `methods` incluye `'coffee'`. */
+    coffee?: CoffeeConfig;
+    /** Cuentas bancarias — requerido si `methods` incluye `'bank'`. */
+    bank?: {
+        accounts: BankAccount[];
+    };
+    /** Config de ads — requerido si `methods` incluye `'ads'`. */
+    ads?: AdsConfig;
+}
+/**
+ * Resultado de un intento de aporte. Devuelto por los métodos del servicio
+ * de forma descriptiva (no se lanzan excepciones para flujos esperables).
+ */
+export interface DonationActionResult {
+    method: DonationMethod;
+    /** `true` si la acción se inició correctamente. */
+    ok: boolean;
+    /** Motivo cuando `ok` es `false` — ej. 'not-configured', 'not-supported'. */
+    reason?: string;
+}

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;