valtech-components 2.0.653 → 2.0.655

package/README.md

@@ -1,257 +1,293 @@
 <img style="margin-bottom: 20px;" src="https://myvaltech.s3.us-east-2.amazonaws.com/logo-terminal-rounded.png" width="60px" />
 
-# [Valtech Components](https://ui.myvaltech.com/)
+# Valtech Components
 
-[Valtech Components](https://ui.myvaltech.com/) is a reusable component library for building modern web and hybrid applications with Angular, Ionic, and Capacitor. It provides a set of UI components, utilities, and styles to accelerate and standardize the development of scalable applications.
+[![npm version](https://img.shields.io/npm/v/valtech-components.svg)](https://www.npmjs.com/package/valtech-components)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**[Documentation](https://ui.myvaltech.com)** | **[npm](https://www.npmjs.com/package/valtech-components)**
+
+A comprehensive component library for building modern web and hybrid applications with Angular, Ionic, and Capacitor. Includes **134 UI components** and **23+ specialized services** for authentication, Firebase integration, internationalization, and more.
 
 ## Features
 
-- **Reusable UI Components:** Atoms, molecules, organisms, and templates ready to use and customize.
-- **Ionic & Angular Integration:** Built on top of Angular and Ionic for seamless hybrid and web experiences.
-- **Capacitor Support:** Utilities and helpers for native functionality in hybrid apps.
-- **Consistent Design:** Shared styles, themes, and assets for a unified look and feel.
-- **Extensible Architecture:** Easily extend or customize components to fit your needs.
+- **134 UI Components** — Atoms, molecules, organisms, and templates ready to use
+- **Authentication System** — Complete auth with OAuth (Google, Apple), session management, and token handling
+- **Firebase Integration** — Analytics, Firestore, Cloud Messaging, and Storage services
+- **i18n with Signals** — Modern internationalization using Angular Signals for reactive translations
+- **Remote App Configuration** — Feature flags and remote config management
+- **Google Ad Manager** — Built-in ad slot integration
+- **User Feedback System** — Collect and manage user feedback
+- **Storybook Documentation** — Interactive component documentation
 
 ## Technologies
 
 - Angular 18+
 - Ionic 8+
 - Capacitor 6+
-- RxJS
+- Firebase 10+
+- RxJS 7.8+
 
 ## Installation
 
-Add the library to your Angular/Ionic project:
-
-```sh
+```bash
 npm install valtech-components
 ```
 
-> Make sure you have the required peer dependencies installed: `@angular/core`, `@ionic/angular`, `ionicons`, `rxjs`.
-
-## Development
-
-### Prerequisites
-
-- Node.js 18+
-- npm 9+
-
-### Setup
+### Peer Dependencies
 
 ```bash
-# Install dependencies
-npm install
+npm install @angular/core @angular/common @ionic/angular ionicons rxjs
 ```
 
-### Available Scripts
-
-| Command | Description |
-|---------|-------------|
-| `npm run build` | Build the library (production) |
-| `npm run build:prod` | Build with production config |
-| `npm run storybook` | Start Storybook dev server (port 6006) |
-| `npm run build-storybook` | Build static Storybook |
-| `npm run test` | Run unit tests |
-| `npm run prettier` | Format source files |
-
-### Storybook
-
-Storybook is included for component development and documentation:
+Optional peer dependencies for additional features:
 
 ```bash
-# Start Storybook development server
-npm run storybook
+# Firebase services
+npm install @angular/fire firebase
 
-# Open http://localhost:6006
-```
+# QR code generation
+npm install qr-code-styling
 
-### Project Structure
+# Code highlighting
+npm install prismjs
 
+# Carousel support
+npm install swiper
 ```
-valtech-components/
-├── .storybook/          # Storybook configuration
-├── src/
-│   ├── lib/
-│   │   ├── components/  # UI components (atoms, molecules, organisms, templates)
-│   │   ├── services/    # Angular services
-│   │   ├── shared/      # Utilities, pipes, constants
-│   │   └── assets/      # Fonts and static resources
-│   ├── stories/         # Storybook documentation
-│   └── public-api.ts    # Library exports
-├── styles/              # Global SCSS styles
-├── angular.json         # Angular CLI config
-├── ng-package.json      # ng-packagr config
-└── package.json         # Dependencies and scripts
-```
-
-### Building the Library
 
-```bash
-# Development build
-npm run build
+## Components
 
-# Production build (optimized)
-npm run build:prod
+| Category | Count | Description |
+|----------|-------|-------------|
+| **Atoms** | 19 | Basic UI elements: avatar, button, icon, text, image, skeleton, progress-bar, qr-code, etc. |
+| **Molecules** | 81 | Compound components: inputs (text, email, phone, pin, date), cards, searchbar, tabs, accordion, pagination, etc. |
+| **Organisms** | 24 | Complex components: forms, data-table, menu, toolbar, login, comment-section, infinite-list, etc. |
+| **Templates** | 10 | Page layouts: page-wrapper, page-content, docs-shell, auth-background, maintenance-page, etc. |
 
-# Output: ./dist/valtech-components/
-```
+> **[View full component catalog](https://ui.myvaltech.com)**
 
-### Publishing
+## Services
 
-The built library can be published to npm or used locally via `npm link`.
+### Basic Services
+| Service | Description |
+|---------|-------------|
+| `ThemeService` | Theme management (light/dark mode) |
+| `ToastService` | Toast notifications |
+| `NavigationService` | Routing utilities |
+| `DownloadService` | File download helpers |
+| `IconsService` | Ionicons management |
+| `LocaleService` | Simple locale management with localStorage |
+| `LocalStorageService` | localStorage abstraction |
+| `LinkProcessorService` | Automatic URL and markdown link processing |
+| `InAppBrowserService` | Capacitor in-app browser |
+
+### Authentication Services
+| Service | Description |
+|---------|-------------|
+| `AuthService` | Main authentication service |
+| `OAuthService` | OAuth providers (Google, Apple) |
+| `SessionService` | Session management |
+| `TokenService` | JWT token handling |
+| `AuthStateService` | Authentication state management |
+| `DeviceService` | Device information |
+
+### Firebase Services
+| Service | Description |
+|---------|-------------|
+| `FirebaseService` | Firebase initialization |
+| `AnalyticsService` | Firebase Analytics with custom events |
+| `FirestoreService` | Firestore database operations |
+| `MessagingService` | Cloud Messaging (push notifications) |
+| `NotificationsService` | Notification management |
+| `FirebaseStorageService` | Firebase Storage operations |
+
+### Other Services
+| Service | Description |
+|---------|-------------|
+| `I18nService` | Internationalization with Angular Signals |
+| `AppConfigService` | Remote configuration and feature flags |
+| `FeedbackService` | User feedback collection |
+| `ModalService` | Modal dialog management |
+| `ConfirmationDialogService` | Confirmation dialogs |
+| `QrGeneratorService` | QR code generation |
+| `PresetService` | Reusable configuration presets |
+| `PaginationService` | Pagination state management |
+| `SkeletonService` | Skeleton loading states |
 
-## Usage
+## Quick Start
 
-Import the desired standalone components in your Angular modules or components:
+### Basic Component Usage
 
 ```typescript
-import { inject } from '@angular/core';
-import { TextComponent, ButtonComponent } from 'valtech-components';
+import { Component } from '@angular/core';
+import { TextComponent, ButtonComponent, CardComponent } from 'valtech-components';
 
 @Component({
-  selector: 'your-component',
+  selector: 'app-example',
   standalone: true,
-  imports: [
-    TextComponent,
-    ButtonComponent
-  ],
+  imports: [TextComponent, ButtonComponent, CardComponent],
   template: `
-    <!-- Static text -->
-    <val-text
-      [props]="{
-        content: 'This is a body text.',
-        color: 'primary',
-        bold: false,
-        size: 'small'
-      }"
-    />
-
-    <!-- Button -->
-    <val-button
-      [props]="{
-        text: 'Cancel',
-        color: 'secondary',
-        type: 'button'
-      }"
-      (onClick)="handleCancel()"
-    />
+    <val-card [props]="{ title: 'Welcome' }">
+      <val-text [props]="{ content: 'Hello, World!', size: 'medium' }" />
+      <val-button
+        [props]="{ text: 'Get Started', color: 'primary' }"
+        (onClick)="handleClick()"
+      />
+    </val-card>
   `
 })
-export class YourComponent {
-  handleCancel() {
-    console.log('Cancel clicked');
+export class ExampleComponent {
+  handleClick() {
+    console.log('Button clicked');
   }
 }
 ```
 
-## 🌍 Locale Management
-
-The library includes a simple locale management service using localStorage:
+### i18n with Signals
 
 ```typescript
-import { inject } from '@angular/core';
-import { LocaleService, LanguageSelectorComponent } from 'valtech-components';
+import { Component, inject, computed } from '@angular/core';
+import { I18nService, TextComponent } from 'valtech-components';
 
 @Component({
+  selector: 'app-i18n-example',
+  standalone: true,
+  imports: [TextComponent],
   template: `
-    <val-language-selector
-      [props]="{ showFlags: true, showLabel: true }"
-      (languageChange)="onLanguageChange($event)"
-    ></val-language-selector>
+    <val-text [props]="{ content: welcomeText() }" />
   `
 })
-export class MyComponent {
-  localeService = inject(LocaleService);
+export class I18nExampleComponent {
+  private i18n = inject(I18nService);
 
-  // Get current locale
-  currentLocale = this.localeService.getLocale(); // 'es', 'en', etc.
+  // Use computed() for reactive translations
+  welcomeText = computed(() => this.i18n.t('home.welcome'));
+}
+```
+
+### Authentication
 
-  onLanguageChange(locale: string) {
-    // Changes locale and reloads the page
-    this.localeService.setLocale(locale);
+```typescript
+import { Component, inject } from '@angular/core';
+import { AuthService } from 'valtech-components';
+
+@Component({
+  selector: 'app-auth-example',
+  template: `...`
+})
+export class AuthExampleComponent {
+  private auth = inject(AuthService);
+
+  async loginWithGoogle() {
+    await this.auth.loginWithGoogle();
+  }
+
+  async logout() {
+    await this.auth.logout();
+  }
+
+  get isAuthenticated() {
+    return this.auth.isAuthenticated();
   }
 }
 ```
 
-## 🔗 Automatic Link Processing
-
-The library now includes automatic link detection and processing capabilities. Convert URLs and internal routes in text content into clickable links automatically:
+### Firebase Analytics
 
 ```typescript
-// Basic usage with direct URLs
-<val-text [props]="{
-  content: 'Visit https://angular.io or go to /dashboard',
-  processLinks: true,
-  linkConfig: {
-    openExternalInNewTab: true,
-    openInternalInNewTab: false
-  }
-}"></val-text>
-
-// Markdown-style links [text](url)
-<val-text [props]="{
-  content: 'Check [the documentation](https://angular.io/docs) for details',
-  processLinks: true,
-  linkConfig: {
-    processMarkdownLinks: true,
-    openExternalInNewTab: true
+import { Component, inject } from '@angular/core';
+import { AnalyticsService } from 'valtech-components';
+
+@Component({
+  selector: 'app-analytics-example',
+  template: `...`
+})
+export class AnalyticsExampleComponent {
+  private analytics = inject(AnalyticsService);
+
+  trackEvent() {
+    this.analytics.logEvent('button_click', {
+      button_name: 'signup',
+      page: 'home'
+    });
   }
-}"></val-text>
+}
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js 18+
+- npm 9+
+
+### Setup
 
-// Mixed formats in the same text
-<val-text [props]="{
-  content: 'Read [the guide](https://angular.io/guide), check https://github.com/angular, or go to /examples',
-  processLinks: true
-}"></val-text>
+```bash
+# Install dependencies
+npm install
+
+# Start Storybook
+npm run storybook
+# Open http://localhost:6006
 ```
 
-### Features
+### Available Scripts
 
-- **Automatic Detection**: Identifies external URLs (http/https), internal routes (starting with /), and Markdown-style links `[text](url)`
-- **Improved Regex**: Excludes punctuation marks (`,`, `;`, `.`, `!`, `?`, `()`) from URLs to prevent broken links
-- **Configurable Behavior**: Control whether links open in new tabs
-- **Custom Styling**: Apply custom CSS classes to links
-- **Secure Processing**: Uses Angular's DomSanitizer for safe HTML generation
-- **Standalone Pipe**: Use `ProcessLinksPipe` independently in any template
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Build the library |
+| `npm run build:prod` | Production build (optimized) |
+| `npm run storybook` | Start Storybook dev server (port 6006) |
+| `npm run build-storybook` | Build static Storybook |
+| `npm run test` | Run unit tests |
+| `npm run prettier` | Format source files |
+| `npm run publish:patch` | Build and publish patch version to npm |
+| `npm run update-apps` | Update dependent apps |
 
-### Using the Service Directly
+### Publishing
 
-```typescript
-import { LinkProcessorService } from 'valtech-components';
-
-constructor(private linkProcessor: LinkProcessorService) {}
-
-processText(text: string) {
-  // Convert links automatically
-  const processed = this.linkProcessor.processLinks(text);
-  
-  // Check if text contains links
-  const hasLinks = this.linkProcessor.hasLinks(text);
-  
-  // Extract all links with their types and text
-  const links = this.linkProcessor.extractLinks(text);
-  // Returns: [{ url: '...', type: 'external|internal', text: '...' }]
-}
+```bash
+# Publish a new patch version (e.g., 2.0.654 → 2.0.655)
+npm run publish:patch
 ```
 
 ## Project Structure
 
-- `src/lib/components/atoms/` – Basic UI elements (e.g., button, icon, text)
-- `src/lib/components/molecules/` – Compound components (e.g., input groups, cards)
-- `src/lib/components/organisms/` – Complex components (e.g., forms, toolbars)
-- `src/lib/components/templates/` – Page templates and layouts
-- `src/lib/components/styles/` – Shared SCSS variables, mixins, and utilities
-- `src/lib/services/` – Core services:
-  - `locale.service.ts` – Simple locale management with localStorage
-  - `theme.service.ts` – Theme management
-  - `navigation.service.ts` – Routing utilities
-  - `download.service.ts` – File download helpers
-  - `icons.service.ts` – Icon management
-  - `toast.service.ts` – Toast notifications
-- `src/lib/shared/` – Shared utilities:
-  - `pipes/process-links.pipe.ts` – Automatic link processing
-  - `constants/` – Shared constants
+```
+valtech-components/
+├── .storybook/              # Storybook configuration
+├── src/
+│   ├── lib/
+│   │   ├── components/      # UI components
+│   │   │   ├── atoms/       # Basic elements (19)
+│   │   │   ├── molecules/   # Compound components (81)
+│   │   │   ├── organisms/   # Complex components (24)
+│   │   │   └── templates/   # Page layouts (10)
+│   │   ├── services/        # Angular services (23+)
+│   │   │   ├── auth/        # Authentication
+│   │   │   ├── firebase/    # Firebase integration
+│   │   │   ├── i18n/        # Internationalization
+│   │   │   ├── feedback/    # User feedback
+│   │   │   ├── app-config/  # Remote configuration
+│   │   │   └── ...
+│   │   ├── shared/          # Utilities, pipes, constants
+│   │   └── config/          # Shared configuration
+│   ├── stories/             # Storybook stories
+│   └── public-api.ts        # Library exports
+├── styles/                  # Global SCSS styles
+├── angular.json             # Angular CLI config
+├── ng-package.json          # ng-packagr config
+└── package.json             # Dependencies and scripts
+```
+
+## Documentation
+
+For complete documentation, examples, and API reference, visit:
+
+**[https://ui.myvaltech.com](https://ui.myvaltech.com)**
 
 ## License
 
-[MIT](https://opensource.org/license/mit)
+[MIT](https://opensource.org/licenses/MIT)