valtech-components 2.0.821 → 2.0.824

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

@@ -0,0 +1,113 @@
+import { Signal } from '@angular/core';
+import { Observable } from 'rxjs';
+/**
+ * Estrategia de paginacion.
+ */
+export type PaginationStrategy = 'offset' | 'cursor' | 'page';
+/**
+ * Estado de paginacion.
+ */
+export interface PaginationState<T> {
+    /** Items actuales */
+    items: T[];
+    /** Pagina actual (para estrategia offset/page) */
+    page: number;
+    /** Tamano de pagina */
+    pageSize: number;
+    /** Conteo total (si se conoce) */
+    total?: number;
+    /** Cursor para siguiente pagina (para estrategia cursor) */
+    nextCursor?: unknown;
+    /** Cursor para pagina anterior */
+    prevCursor?: unknown;
+    /** Si existen mas items */
+    hasMore: boolean;
+    /** Estado de carga */
+    isLoading: boolean;
+    /** Estado de error */
+    error?: Error;
+}
+/**
+ * Parametros para funcion de carga.
+ */
+export interface PaginationLoadParams {
+    /** Estrategia de paginacion */
+    strategy: PaginationStrategy;
+    /** Numero de pagina */
+    page: number;
+    /** Tamano de pagina */
+    pageSize: number;
+    /** Cursor (para estrategia cursor) */
+    cursor?: unknown;
+    /** Direccion de carga */
+    direction: 'forward' | 'backward';
+}
+/**
+ * Resultado de funcion de carga.
+ */
+export interface PaginationLoadResult<T> {
+    /** Items cargados */
+    items: T[];
+    /** Si hay mas items */
+    hasMore: boolean;
+    /** Total de items (opcional) */
+    total?: number;
+    /** Cursor para siguiente pagina */
+    nextCursor?: unknown;
+    /** Cursor para pagina anterior */
+    prevCursor?: unknown;
+}
+/**
+ * Configuracion para crear un controlador de paginacion.
+ */
+export interface PaginationConfig<T> {
+    /** Estrategia de paginacion */
+    strategy: PaginationStrategy;
+    /** Tamano de pagina */
+    pageSize?: number;
+    /** Items iniciales (opcional) */
+    initialItems?: T[];
+    /** Funcion de carga */
+    loadFn: (params: PaginationLoadParams) => Observable<PaginationLoadResult<T>> | Promise<PaginationLoadResult<T>>;
+    /** Funcion de tracking para items */
+    trackBy?: (item: T) => unknown;
+}
+/**
+ * Interface del controlador de paginacion.
+ */
+export interface PaginationController<T> {
+    /** Estado reactivo como signal */
+    state: Signal<PaginationState<T>>;
+    /** Signal de items (accessor de conveniencia) */
+    items: Signal<T[]>;
+    /** Signal de carga */
+    isLoading: Signal<boolean>;
+    /** Signal de mas items */
+    hasMore: Signal<boolean>;
+    /** Signal de error */
+    error: Signal<Error | null>;
+    /** Signal de pagina actual */
+    currentPage: Signal<number>;
+    /** Signal de total */
+    total: Signal<number | undefined>;
+    /** Cargar siguiente pagina */
+    loadNext(): Promise<void>;
+    /** Cargar pagina anterior (si soportado) */
+    loadPrevious(): Promise<void>;
+    /** Refresh (recargar desde inicio) */
+    refresh(): Promise<void>;
+    /** Reset a estado inicial */
+    reset(): void;
+    /** Actualizar un item */
+    updateItem(predicate: (item: T) => boolean, updates: Partial<T>): void;
+    /** Remover un item */
+    removeItem(predicate: (item: T) => boolean): void;
+    /** Agregar items al inicio */
+    prependItems(items: T[]): void;
+    /** Agregar items al final */
+    appendItems(items: T[]): void;
+}
+/**
+ * Estado inicial para controladores de paginacion.
+ */
+export declare function createInitialPaginationState<T>(pageSize: number, initialItems?: T[]): PaginationState<T>;

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

@@ -0,0 +1,2 @@
+export * from './preferences.service';
+export * from './preferences.types';

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

@@ -0,0 +1,61 @@
+import { HttpClient } from '@angular/common/http';
+import { AuthService } from '../auth/auth.service';
+import { ValtechAuthConfig } from '../auth/types';
+import { FirestoreService } from '../firebase/firestore.service';
+import { I18nService } from '../i18n/i18n.service';
+import { ThemeService } from '../theme.service';
+import { PreferencesLanguage, PreferencesTheme, PreferencesUpdate, PreferencesUpdateResponse } from './preferences.types';
+import * as i0 from "@angular/core";
+/**
+ * PreferencesService — preferencias del user en el doc canónico Firestore
+ * `/apps/{appId}/users/{uid}/preferences/main`.
+ *
+ * Read reactivo (signals) via listener Firestore.
+ * Write via `PUT /v2/auth/preferences` (cliente NUNCA escribe Firestore directo —
+ * ver memoria `feedback_no_direct_firestore_writes`).
+ *
+ * Side-effects automáticos:
+ * - Cuando `theme()` cambia → `ThemeService.Theme = ...`
+ * - Cuando `language()` cambia → `I18nService.setLanguage(...)`
+ *
+ * Auto-bind al user actual via `AuthService.user()`. Sin user (logout) → unbind.
+ */
+export declare class PreferencesService {
+    private config;
+    private firestore;
+    private auth;
+    private http;
+    private themeService;
+    private i18n;
+    private readonly _theme;
+    private readonly _language;
+    private readonly _notificationsMaster;
+    /** `true` después del primer snapshot Firestore. Antes, defaults sin side-effects. */
+    private readonly _synced;
+    readonly theme: import("@angular/core").Signal<PreferencesTheme>;
+    readonly language: import("@angular/core").Signal<PreferencesLanguage>;
+    readonly notificationsMaster: import("@angular/core").Signal<boolean>;
+    readonly synced: import("@angular/core").Signal<boolean>;
+    private subscription?;
+    private currentUserId?;
+    /**
+     * `true` mientras un `update()` está en vuelo (PUT al backend).
+     *
+     * El listener Firestore (`bindToUser`) es real-time y puede emitir un snapshot
+     * *stale* — anterior al sync del backend — que pisaría el valor optimista de
+     * `_notificationsMaster` y revertiría el toggle. Mientras este flag esté `true`
+     * el listener ignora las emisiones; el `update()` ya alinea las señales con la
+     * respuesta del backend al terminar.
+     */
+    private _updateInFlight;
+    constructor(config: ValtechAuthConfig, firestore: FirestoreService, auth: AuthService, http: HttpClient, themeService: ThemeService | null, i18n: I18nService | null);
+    /** Actualiza preferencias via backend. Optimistic UI: aplica local, revierte si falla. */
+    update(partial: PreferencesUpdate): Promise<PreferencesUpdateResponse>;
+    setTheme(theme: PreferencesTheme): Promise<PreferencesUpdateResponse>;
+    setLanguage(language: PreferencesLanguage): Promise<PreferencesUpdateResponse>;
+    setNotificationsMaster(enabled: boolean): Promise<PreferencesUpdateResponse>;
+    private bindToUser;
+    private unbind;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PreferencesService, [null, null, null, null, { optional: true; }, { optional: true; }]>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PreferencesService>;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Preferences types — Fase 1 schema simple (theme + language + notifications.master).
+ * Doc canónico: /apps/{appId}/users/{uid}/preferences/main
+ * Cliente NUNCA escribe directo — todas las mutaciones via PUT /v2/auth/preferences.
+ */
+export type PreferencesTheme = 'light' | 'dark' | 'auto';
+export type PreferencesLanguage = 'es' | 'en' | 'pt';
+/** Forma del doc tal como lo escribe el backend (Admin SDK). */
+export interface PreferencesDocument {
+    theme?: PreferencesTheme;
+    language?: PreferencesLanguage;
+    notifications?: {
+        master?: boolean;
+    };
+    /** serverTimestamp escrito por el backend en cada sync. */
+    syncedAt?: unknown;
+}
+/** Payload aceptado por `PUT /v2/auth/preferences` — partial update. */
+export interface PreferencesUpdate {
+    theme?: PreferencesTheme;
+    language?: PreferencesLanguage;
+    notifications?: {
+        master?: boolean;
+    };
+}
+/** Response del backend tras el PUT. */
+export interface PreferencesUpdateResponse {
+    operationId: string;
+    theme: PreferencesTheme | '';
+    language: PreferencesLanguage | '';
+    notifications: {
+        master?: boolean;
+    };
+    updated: boolean;
+}

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

@@ -0,0 +1,32 @@
+import { EnvironmentProviders } from '@angular/core';
+import { PresetConfig } from './types';
+/**
+ * Configura el sistema de presets de Valtech Components.
+ *
+ * @param presets Configuración de presets por componente
+ * @returns Providers para agregar en app.config.ts
+ *
+ * @example
+ * // app.config.ts
+ * import { provideValtechPresets } from 'valtech-components';
+ *
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideValtechPresets({
+ *       button: {
+ *         'primary-action': { size: 'large', color: 'primary', fill: 'solid' },
+ *         'secondary': { size: 'medium', color: 'secondary', fill: 'outline' },
+ *         'danger': { size: 'medium', color: 'danger', fill: 'solid' },
+ *       },
+ *       card: {
+ *         'feature': { variant: 'elevated', padding: 'large' },
+ *         'compact': { variant: 'flat', padding: 'small' },
+ *       },
+ *       input: {
+ *         'form-field': { size: 'medium', fill: 'outline', labelPosition: 'floating' },
+ *       }
+ *     }),
+ *   ]
+ * };
+ */
+export declare function provideValtechPresets(presets: PresetConfig): EnvironmentProviders;

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

@@ -0,0 +1,3 @@
+export { PresetConfig, ComponentPresets, PresetsOptions } from './types';
+export { PresetService } from './preset.service';
+export { provideValtechPresets } from './config';

package/lib/services/presets/preset.service.d.ts

@@ -0,0 +1,69 @@
+import { PresetConfig, ComponentPresets } from './types';
+import * as i0 from "@angular/core";
+/**
+ * Servicio para gestionar presets de componentes.
+ *
+ * Los presets permiten definir configuraciones reutilizables
+ * de componentes (tamaño, color, variante, etc.) que se pueden
+ * aplicar con un nombre semántico.
+ *
+ * @example
+ * // En un componente
+ * presets = inject(PresetService);
+ *
+ * // Obtener preset
+ * const buttonProps = this.presets.get<ButtonMetadata>('button', 'primary-action');
+ * // { size: 'large', color: 'primary', fill: 'solid' }
+ */
+export declare class PresetService {
+    private readonly _presets;
+    /**
+     * Obtiene un preset específico para un componente
+     *
+     * @param component Tipo de componente (ej: 'button', 'card', 'input')
+     * @param presetName Nombre del preset (ej: 'primary-action', 'compact')
+     * @returns Propiedades del preset o objeto vacío si no existe
+     *
+     * @example
+     * // Obtener preset de botón
+     * const props = presets.get<ButtonMetadata>('button', 'primary-action');
+     *
+     * // Usar en componente
+     * <val-button [props]="props"></val-button>
+     */
+    get<T extends Record<string, unknown>>(component: string, presetName: string): Partial<T>;
+    /**
+     * Verifica si existe un preset
+     */
+    has(component: string, presetName: string): boolean;
+    /**
+     * Registra presets de la aplicación
+     *
+     * @param presets Configuración de presets
+     *
+     * @example
+     * presets.registerPresets({
+     *   button: {
+     *     'primary-action': { size: 'large', color: 'primary' },
+     *   },
+     *   card: {
+     *     'feature': { variant: 'elevated' },
+     *   }
+     * });
+     */
+    registerPresets(presets: PresetConfig): void;
+    /**
+     * Agrega presets para un componente específico (merge con existentes)
+     */
+    registerComponentPresets(component: string, presets: ComponentPresets): void;
+    /**
+     * Obtiene todos los nombres de presets para un componente
+     */
+    getPresetNames(component: string): string[];
+    /**
+     * Obtiene todos los componentes con presets registrados
+     */
+    getRegisteredComponents(): string[];
+    static ɵfac: i0.ɵɵFactoryDeclaration<PresetService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PresetService>;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Presets para un tipo de componente
+ *
+ * @example
+ * const buttonPresets: ComponentPresets = {
+ *   'primary-action': { size: 'large', color: 'primary', fill: 'solid' },
+ *   'secondary': { size: 'medium', color: 'secondary', fill: 'outline' },
+ *   'danger': { size: 'medium', color: 'danger', fill: 'solid' },
+ * };
+ */
+export type ComponentPresets = Record<string, Record<string, unknown>>;
+/**
+ * Configuración completa de presets por componente
+ *
+ * @example
+ * const appPresets: PresetConfig = {
+ *   button: {
+ *     'primary-action': { size: 'large', color: 'primary', fill: 'solid' },
+ *     'secondary': { size: 'medium', color: 'secondary', fill: 'outline' },
+ *   },
+ *   card: {
+ *     'feature': { variant: 'elevated', padding: 'large' },
+ *     'compact': { variant: 'flat', padding: 'small' },
+ *   },
+ *   input: {
+ *     'form-field': { size: 'medium', fill: 'outline', labelPosition: 'floating' },
+ *   }
+ * };
+ */
+export type PresetConfig = Record<string, ComponentPresets>;
+/**
+ * Opciones para provideValtechPresets()
+ */
+export interface PresetsOptions {
+    /**
+     * Presets iniciales de la aplicación
+     */
+    presets: PresetConfig;
+}

package/lib/services/qr-generator/qr-generator.service.d.ts

@@ -0,0 +1,115 @@
+import { QrConfig, QrResult, QrDownloadOptions, QrShareOptions, QR_PRESETS } from './types';
+import * as i0 from "@angular/core";
+/**
+ * QrGeneratorService
+ *
+ * A comprehensive service for generating, customizing, and manipulating QR codes.
+ * Uses qr-code-styling library for high-quality, customizable QR code generation.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const qr = await this.qrService.generate({ data: 'https://example.com' });
+ * console.log(qr.dataUrl); // base64 image
+ * ```
+ *
+ * @example With customization
+ * ```typescript
+ * const qr = await this.qrService.generate({
+ *   data: 'https://example.com',
+ *   width: 400,
+ *   dotsStyle: 'rounded',
+ *   dotsColor: '#3880ff',
+ *   logo: { src: 'logo.png', width: 60 }
+ * });
+ * ```
+ *
+ * @example Using presets
+ * ```typescript
+ * const qr = await this.qrService.generateFromPreset('modern', 'https://example.com');
+ * ```
+ */
+export declare class QrGeneratorService {
+    /**
+     * Generate a QR code with the given configuration.
+     *
+     * @param config - QR code configuration
+     * @returns Promise<QrResult> - Generated QR code result
+     *
+     * @example
+     * ```typescript
+     * const qr = await this.qrService.generate({
+     *   data: 'https://myapp.com/product/123',
+     *   width: 300,
+     *   dotsStyle: 'rounded',
+     *   dotsColor: '#000000',
+     *   backgroundColor: '#ffffff'
+     * });
+     * ```
+     */
+    generate(config: QrConfig): Promise<QrResult>;
+    /**
+     * Generate a QR code using a preset configuration.
+     *
+     * @param preset - Preset name ('default', 'rounded', 'dots', 'classy', 'modern')
+     * @param data - Data to encode
+     * @param overrides - Optional configuration overrides
+     * @returns Promise<QrResult>
+     */
+    generateFromPreset(preset: keyof typeof QR_PRESETS | string, data: string, overrides?: Partial<QrConfig>): Promise<QrResult>;
+    /**
+     * Download the QR code as a file.
+     *
+     * @param qr - QR result to download
+     * @param options - Download options
+     */
+    download(qr: QrResult, options?: QrDownloadOptions): Promise<void>;
+    /**
+     * Copy the QR code to clipboard as an image.
+     *
+     * @param qr - QR result to copy
+     * @returns Promise<boolean> - Whether copy was successful
+     */
+    copyToClipboard(qr: QrResult): Promise<boolean>;
+    /**
+     * Share the QR code using Web Share API.
+     *
+     * @param qr - QR result to share
+     * @param options - Share options
+     * @returns Promise<boolean> - Whether share was successful
+     */
+    share(qr: QrResult, options?: QrShareOptions): Promise<boolean>;
+    /**
+     * Get the QR code as a base64 string (without data URL prefix).
+     *
+     * @param qr - QR result
+     * @returns Base64 string
+     */
+    toBase64(qr: QrResult): string;
+    /**
+     * Get the QR code as a data URL.
+     *
+     * @param qr - QR result
+     * @returns Data URL string
+     */
+    toDataUrl(qr: QrResult): string;
+    /**
+     * Get the QR code as a Blob.
+     *
+     * @param qr - QR result
+     * @returns Blob
+     */
+    toBlob(qr: QrResult): Blob;
+    /**
+     * Check if Web Share API is available.
+     */
+    canShare(): boolean;
+    /**
+     * Check if Clipboard API is available for images.
+     */
+    canCopyToClipboard(): boolean;
+    private buildColorOptions;
+    private getMimeType;
+    private blobToDataUrl;
+    static ɵfac: i0.ɵɵFactoryDeclaration<QrGeneratorService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<QrGeneratorService>;
+}

package/lib/services/qr-generator/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Style options for QR code dots (data modules).
+ */
+export type QrDotsStyle = 'square' | 'dots' | 'rounded' | 'extra-rounded' | 'classy' | 'classy-rounded';
+/**
+ * Style options for QR code corner squares.
+ */
+export type QrCornersSquareStyle = 'square' | 'dot' | 'extra-rounded';
+/**
+ * Style options for QR code corner dots.
+ */
+export type QrCornersDotStyle = 'square' | 'dot';
+/**
+ * Output format for the generated QR code.
+ */
+export type QrOutputFormat = 'svg' | 'png' | 'jpeg' | 'webp';
+/**
+ * Error correction level for QR codes.
+ * Higher levels allow more damage tolerance but reduce data capacity.
+ */
+export type QrErrorCorrectionLevel = 'L' | 'M' | 'Q' | 'H';
+/**
+ * Logo/image configuration for the QR code center.
+ */
+export interface QrLogoConfig {
+    /** Image source URL or base64 */
+    src: string;
+    /** Logo width (default: 25% of QR size) */
+    width?: number;
+    /** Logo height (default: same as width) */
+    height?: number;
+    /** Margin around the logo */
+    margin?: number;
+    /** Border radius for rounded corners */
+    borderRadius?: number;
+    /** Whether to hide dots behind the logo */
+    hideBackgroundDots?: boolean;
+}
+/**
+ * Gradient configuration for QR elements.
+ */
+export interface QrGradient {
+    /** Gradient type */
+    type: 'linear' | 'radial';
+    /** Rotation angle in degrees (for linear) */
+    rotation?: number;
+    /** Color stops */
+    colorStops: Array<{
+        offset: number;
+        color: string;
+    }>;
+}
+/**
+ * Color configuration - can be solid color or gradient.
+ */
+export type QrColorConfig = string | QrGradient;
+/**
+ * Complete configuration for QR code generation.
+ */
+export interface QrConfig {
+    /** The data to encode (URL, text, etc.) */
+    data: string;
+    /** QR code width in pixels (default: 300) */
+    width?: number;
+    /** QR code height in pixels (default: same as width) */
+    height?: number;
+    /** Quiet zone margin in modules (default: 0) */
+    margin?: number;
+    /** Color/gradient for data dots */
+    dotsColor?: QrColorConfig;
+    /** Background color (default: white) */
+    backgroundColor?: QrColorConfig;
+    /** Color for corner squares */
+    cornersSquareColor?: QrColorConfig;
+    /** Color for corner dots */
+    cornersDotColor?: QrColorConfig;
+    /** Style of data dots (default: 'square') */
+    dotsStyle?: QrDotsStyle;
+    /** Style of corner squares (default: 'square') */
+    cornersSquareStyle?: QrCornersSquareStyle;
+    /** Style of corner dots (default: 'square') */
+    cornersDotStyle?: QrCornersDotStyle;
+    /** Logo/image configuration */
+    logo?: QrLogoConfig;
+    /** Error correction level (default: 'M') */
+    errorCorrectionLevel?: QrErrorCorrectionLevel;
+    /** Output format (default: 'png') */
+    format?: QrOutputFormat;
+    /** Quality for jpeg/webp (0-1, default: 1) */
+    quality?: number;
+}
+/**
+ * Result from QR code generation.
+ */
+export interface QrResult {
+    /** Original configuration used */
+    config: QrConfig;
+    /** Generated data as base64 data URL */
+    dataUrl: string;
+    /** Generated data as Blob */
+    blob: Blob;
+    /** SVG string (only when format is 'svg') */
+    svg?: string;
+    /** MIME type of the generated image */
+    mimeType: string;
+    /** File extension */
+    extension: string;
+    /** Timestamp of generation */
+    generatedAt: Date;
+}
+/**
+ * Options for downloading the QR code.
+ */
+export interface QrDownloadOptions {
+    /** Custom filename (without extension) */
+    filename?: string;
+    /** Override format for download */
+    format?: QrOutputFormat;
+}
+/**
+ * Options for sharing the QR code.
+ */
+export interface QrShareOptions {
+    /** Share title */
+    title?: string;
+    /** Share text/description */
+    text?: string;
+    /** Custom filename for the shared file */
+    filename?: string;
+}
+/**
+ * Preset configurations for common use cases.
+ */
+export interface QrPreset {
+    name: string;
+    config: Partial<QrConfig>;
+}
+/**
+ * Default presets for quick styling.
+ */
+export declare const QR_PRESETS: Record<string, Partial<QrConfig>>;

package/lib/services/refreshable-stream/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Refreshable Stream
+ *
+ * Helper `createRefreshableStream` para vistas con datos Firestore.
+ * Soporta modo one-shot y real-time, con gate de `firebaseAuthReady`.
+ */
+export { createRefreshableStream, type RefreshableStream, type RefreshableStreamOptions, } from './refreshable-stream';