valtech-components 2.0.794 → 2.0.795

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

@@ -0,0 +1,243 @@
+import { Injectable, signal, computed, Signal } from '@angular/core';
+import { firstValueFrom, isObservable } from 'rxjs';
+import {
+  PaginationConfig,
+  PaginationController,
+  PaginationLoadParams,
+  PaginationLoadResult,
+  PaginationState,
+  createInitialPaginationState,
+} from './types';
+
+/**
+ * Implementacion del controlador de paginacion.
+ */
+class PaginationControllerImpl<T> implements PaginationController<T> {
+  private readonly _state = signal<PaginationState<T>>(
+    createInitialPaginationState(this.config.pageSize ?? 20, this.config.initialItems)
+  );
+
+  readonly state = this._state.asReadonly();
+  readonly items = computed(() => this._state().items);
+  readonly isLoading = computed(() => this._state().isLoading);
+  readonly hasMore = computed(() => this._state().hasMore);
+  readonly error = computed(() => this._state().error ?? null);
+  readonly currentPage = computed(() => this._state().page);
+  readonly total = computed(() => this._state().total);
+
+  constructor(private readonly config: PaginationConfig<T>) {}
+
+  async loadNext(): Promise<void> {
+    const currentState = this._state();
+    if (currentState.isLoading || !currentState.hasMore) return;
+
+    this._state.update((s) => ({ ...s, isLoading: true, error: undefined }));
+
+    try {
+      const params: PaginationLoadParams = {
+        strategy: this.config.strategy,
+        page: currentState.page,
+        pageSize: currentState.pageSize,
+        cursor: currentState.nextCursor,
+        direction: 'forward',
+      };
+
+      const result = await this.executeLoad(params);
+
+      this._state.update((s) => ({
+        ...s,
+        items: [...s.items, ...result.items],
+        page: s.page + 1,
+        hasMore: result.hasMore,
+        total: result.total ?? s.total,
+        nextCursor: result.nextCursor,
+        prevCursor: result.prevCursor ?? s.prevCursor,
+        isLoading: false,
+      }));
+    } catch (err) {
+      this._state.update((s) => ({
+        ...s,
+        isLoading: false,
+        error: err as Error,
+      }));
+    }
+  }
+
+  async loadPrevious(): Promise<void> {
+    const currentState = this._state();
+    if (currentState.isLoading || currentState.page <= 0) return;
+
+    this._state.update((s) => ({ ...s, isLoading: true, error: undefined }));
+
+    try {
+      const params: PaginationLoadParams = {
+        strategy: this.config.strategy,
+        page: currentState.page - 1,
+        pageSize: currentState.pageSize,
+        cursor: currentState.prevCursor,
+        direction: 'backward',
+      };
+
+      const result = await this.executeLoad(params);
+
+      this._state.update((s) => ({
+        ...s,
+        items: [...result.items, ...s.items],
+        page: s.page - 1,
+        prevCursor: result.prevCursor,
+        isLoading: false,
+      }));
+    } catch (err) {
+      this._state.update((s) => ({
+        ...s,
+        isLoading: false,
+        error: err as Error,
+      }));
+    }
+  }
+
+  async refresh(): Promise<void> {
+    this._state.update((s) => ({
+      ...s,
+      items: [],
+      page: 0,
+      hasMore: true,
+      nextCursor: undefined,
+      prevCursor: undefined,
+      isLoading: true,
+      error: undefined,
+    }));
+
+    try {
+      const params: PaginationLoadParams = {
+        strategy: this.config.strategy,
+        page: 0,
+        pageSize: this._state().pageSize,
+        direction: 'forward',
+      };
+
+      const result = await this.executeLoad(params);
+
+      this._state.update((s) => ({
+        ...s,
+        items: result.items,
+        page: 1,
+        hasMore: result.hasMore,
+        total: result.total,
+        nextCursor: result.nextCursor,
+        isLoading: false,
+      }));
+    } catch (err) {
+      this._state.update((s) => ({
+        ...s,
+        isLoading: false,
+        error: err as Error,
+      }));
+    }
+  }
+
+  reset(): void {
+    this._state.set(
+      createInitialPaginationState(this.config.pageSize ?? 20, this.config.initialItems)
+    );
+  }
+
+  updateItem(predicate: (item: T) => boolean, updates: Partial<T>): void {
+    this._state.update((s) => ({
+      ...s,
+      items: s.items.map((item) => (predicate(item) ? { ...item, ...updates } : item)),
+    }));
+  }
+
+  removeItem(predicate: (item: T) => boolean): void {
+    this._state.update((s) => ({
+      ...s,
+      items: s.items.filter((item) => !predicate(item)),
+    }));
+  }
+
+  prependItems(items: T[]): void {
+    this._state.update((s) => ({
+      ...s,
+      items: [...items, ...s.items],
+    }));
+  }
+
+  appendItems(items: T[]): void {
+    this._state.update((s) => ({
+      ...s,
+      items: [...s.items, ...items],
+    }));
+  }
+
+  private async executeLoad(params: PaginationLoadParams): Promise<PaginationLoadResult<T>> {
+    const result = this.config.loadFn(params);
+
+    if (isObservable(result)) {
+      return await firstValueFrom(result);
+    }
+    return await result;
+  }
+}
+
+/**
+ * Servicio para crear controladores de paginacion reutilizables.
+ *
+ * @example
+ * // En un componente
+ * pagination = inject(PaginationService);
+ *
+ * usersController = this.pagination.createController<User>({
+ *   strategy: 'offset',
+ *   pageSize: 20,
+ *   loadFn: (params) => this.userService.getUsers(params.page, params.pageSize)
+ * });
+ *
+ * // En el template
+ * @for (user of usersController.items(); track user.id) {
+ *   <app-user-card [user]="user"></app-user-card>
+ * }
+ *
+ * @if (usersController.hasMore()) {
+ *   <ion-button (click)="usersController.loadNext()">Cargar mas</ion-button>
+ * }
+ */
+@Injectable({ providedIn: 'root' })
+export class PaginationService {
+  /**
+   * Crea un controlador de paginacion para una fuente de datos.
+   *
+   * @param config Configuracion del controlador
+   * @returns Controlador de paginacion
+   */
+  createController<T>(config: PaginationConfig<T>): PaginationController<T> {
+    return new PaginationControllerImpl<T>(config);
+  }
+
+  /**
+   * Crea un controlador simple para arrays estaticos con paginacion local.
+   *
+   * @param items Array completo de items
+   * @param pageSize Tamano de pagina
+   * @returns Controlador de paginacion
+   */
+  createLocalController<T>(items: T[], pageSize = 20): PaginationController<T> {
+    let currentIndex = 0;
+
+    return this.createController<T>({
+      strategy: 'offset',
+      pageSize,
+      loadFn: async (params) => {
+        const start = params.page * params.pageSize;
+        const end = start + params.pageSize;
+        const pageItems = items.slice(start, end);
+
+        return {
+          items: pageItems,
+          hasMore: end < items.length,
+          total: items.length,
+        };
+      },
+    });
+  }
+}

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

@@ -0,0 +1,133 @@
+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 function createInitialPaginationState<T>(
+  pageSize: number,
+  initialItems: T[] = []
+): PaginationState<T> {
+  return {
+    items: initialItems,
+    page: 0,
+    pageSize,
+    hasMore: true,
+    isLoading: false,
+    error: undefined,
+  };
+}

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

@@ -0,0 +1,179 @@
+import { DestroyRef, Inject, Injectable, Optional, effect, inject, signal } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { Subscription, firstValueFrom } from 'rxjs';
+
+import { AuthService } from '../auth/auth.service';
+import { VALTECH_AUTH_CONFIG } from '../auth/config';
+import { ValtechAuthConfig } from '../auth/types';
+import { FirestoreService } from '../firebase/firestore.service';
+import { I18nLang } from '../i18n/types';
+import { I18nService } from '../i18n/i18n.service';
+import { ThemeOption, ThemeService } from '../theme.service';
+import {
+  PreferencesDocument,
+  PreferencesLanguage,
+  PreferencesTheme,
+  PreferencesUpdate,
+  PreferencesUpdateResponse,
+} from './preferences.types';
+
+/**
+ * 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.
+ */
+@Injectable({ providedIn: 'root' })
+export class PreferencesService {
+  private readonly _theme = signal<PreferencesTheme>('auto');
+  private readonly _language = signal<PreferencesLanguage>('es');
+  // Default `false` (opt-in). El user debe activar explícitamente las notificaciones;
+  // no asumimos consentimiento implícito. Backend debe coincidir.
+  private readonly _notificationsMaster = signal<boolean>(false);
+  /** `true` después del primer snapshot Firestore. Antes, defaults sin side-effects. */
+  private readonly _synced = signal<boolean>(false);
+
+  readonly theme = this._theme.asReadonly();
+  readonly language = this._language.asReadonly();
+  readonly notificationsMaster = this._notificationsMaster.asReadonly();
+  readonly synced = this._synced.asReadonly();
+
+  private subscription?: Subscription;
+  private currentUserId?: string;
+
+  constructor(
+    @Inject(VALTECH_AUTH_CONFIG) private config: ValtechAuthConfig,
+    private firestore: FirestoreService,
+    private auth: AuthService,
+    private http: HttpClient,
+    @Optional() private themeService: ThemeService | null,
+    @Optional() private i18n: I18nService | null
+  ) {
+    const destroyRef = inject(DestroyRef);
+    destroyRef.onDestroy(() => this.unbind());
+
+    // Auto-bind al user actual. effect() corre en injection context (constructor OK).
+    // allowSignalWrites: bindToUser/unbind escriben `_synced` (señal interna sin
+    // dependencias del propio effect) → seguro y necesario.
+    effect(
+      () => {
+        const user = this.auth.user();
+        if (user?.userId) {
+          this.bindToUser(user.userId);
+        } else {
+          this.unbind();
+        }
+      },
+      { allowSignalWrites: true }
+    );
+
+    // Side-effect: aplicar theme local cuando llega snapshot real.
+    // OJO: usar `toggleUserPreference()` y NO el setter `Theme =`. El setter
+    // solo persiste localStorage + emite el BehaviorSubject; no aplica las
+    // clases `body.dark`/`body.light` que el palette `dark.class.css` de
+    // Ionic necesita para conmutar el tema visible.
+    effect(() => {
+      if (!this._synced()) return;
+      const t = this._theme();
+      if (this.themeService) {
+        this.themeService.toggleUserPreference(t as ThemeOption);
+      }
+    });
+
+    // Side-effect: aplicar language local cuando llega snapshot real.
+    effect(() => {
+      if (!this._synced()) return;
+      const l = this._language();
+      if (this.i18n && this.i18n.lang() !== l) {
+        this.i18n.setLanguage(l as I18nLang);
+      }
+    });
+  }
+
+  /** Actualiza preferencias via backend. Optimistic UI: aplica local, revierte si falla. */
+  async update(partial: PreferencesUpdate): Promise<PreferencesUpdateResponse> {
+    const url = `${this.config.apiUrl}/v2/auth/preferences`;
+
+    const prev = {
+      theme: this._theme(),
+      language: this._language(),
+      master: this._notificationsMaster(),
+    };
+
+    if (partial.theme) this._theme.set(partial.theme);
+    if (partial.language) this._language.set(partial.language);
+    if (partial.notifications && typeof partial.notifications.master === 'boolean') {
+      this._notificationsMaster.set(partial.notifications.master);
+    }
+
+    try {
+      const res = await firstValueFrom(this.http.put<PreferencesUpdateResponse>(url, partial));
+      // El listener Firestore es la fuente final, pero alinear ya con la
+      // respuesta del backend acelera UX (especialmente si el listener
+      // tarda en propagar).
+      if (res.theme) this._theme.set(res.theme as PreferencesTheme);
+      if (res.language) this._language.set(res.language as PreferencesLanguage);
+      if (typeof res.notifications?.master === 'boolean') {
+        this._notificationsMaster.set(res.notifications.master);
+      }
+      return res;
+    } catch (err) {
+      // Revert optimistic.
+      this._theme.set(prev.theme);
+      this._language.set(prev.language);
+      this._notificationsMaster.set(prev.master);
+      throw err;
+    }
+  }
+
+  setTheme(theme: PreferencesTheme): Promise<PreferencesUpdateResponse> {
+    return this.update({ theme });
+  }
+
+  setLanguage(language: PreferencesLanguage): Promise<PreferencesUpdateResponse> {
+    return this.update({ language });
+  }
+
+  setNotificationsMaster(enabled: boolean): Promise<PreferencesUpdateResponse> {
+    return this.update({ notifications: { master: enabled } });
+  }
+
+  private bindToUser(userId: string): void {
+    if (this.currentUserId === userId && this.subscription) return;
+    this.unbind();
+    this.currentUserId = userId;
+    // FirestoreService.docChanges prefija automáticamente `apps/{appId}/`
+    // cuando `config.appId` está seteado en ValtechAuthConfig.
+    this.subscription = this.firestore
+      .docChanges<PreferencesDocument & { id?: string }>(`users/${userId}/preferences`, 'main')
+      .subscribe(doc => {
+        if (!doc) {
+          // Doc no existe aún (user nuevo, sin primer sync). Mantenemos
+          // defaults locales pero NO marcamos synced — los side-effects no
+          // pisan el theme/lang locales con valores arbitrarios.
+          return;
+        }
+        if (doc.theme) this._theme.set(doc.theme);
+        if (doc.language) this._language.set(doc.language);
+        if (doc.notifications && typeof doc.notifications.master === 'boolean') {
+          this._notificationsMaster.set(doc.notifications.master);
+        }
+        this._synced.set(true);
+      });
+  }
+
+  private unbind(): void {
+    this.subscription?.unsubscribe();
+    this.subscription = undefined;
+    this.currentUserId = undefined;
+    this._synced.set(false);
+  }
+}

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

@@ -0,0 +1,37 @@
+/**
+ * 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/src/lib/services/presets/config.ts

@@ -0,0 +1,51 @@
+import {
+  EnvironmentProviders,
+  makeEnvironmentProviders,
+  APP_INITIALIZER,
+} from '@angular/core';
+import { PresetConfig } from './types';
+import { PresetService } from './preset.service';
+
+/**
+ * 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 function provideValtechPresets(presets: PresetConfig): EnvironmentProviders {
+  return makeEnvironmentProviders([
+    {
+      provide: APP_INITIALIZER,
+      useFactory: (presetService: PresetService) => {
+        return () => {
+          presetService.registerPresets(presets);
+        };
+      },
+      deps: [PresetService],
+      multi: true,
+    },
+  ]);
+}

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

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