valtech-components 4.0.7 → 4.0.10

package/README.md

@@ -1,13 +1,13 @@
 <img style="margin-bottom: 20px;" src="https://myvaltech.s3.us-east-2.amazonaws.com/logo-terminal-rounded.png" width="60px" />
 
-# Valtech Components
+# valtech-components
 
 [![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)
 
-Component library for Angular + Ionic + Capacitor apps. **145 components** and **23+ services** for auth, Firebase, i18n, and more.
+Component library for Angular 18 + Ionic 8 apps. 145+ components and 23+ services covering auth, Firebase, i18n, theming, and more.
 
-**[Full documentation → ui.myvaltech.com](https://ui.myvaltech.com)**
+**[Full docs → ui.myvaltech.com](https://ui.myvaltech.com)**
 
 ---
 
@@ -23,11 +23,11 @@ npm install valtech-components
 npm install @angular/common @angular/core @ionic/angular ionicons rxjs
 ```
 
-**Optional — only if you use these features:**
+**Optional — only install if you use these features:**
 
 ```bash
 npm install @angular/fire firebase          # Firebase services
-npm install @capacitor/app @capacitor/clipboard  # Native features
+npm install @capacitor/app @capacitor/clipboard  # Native (Capacitor) features
 npm install qr-code-styling                 # QR code component
 npm install prismjs                         # Code highlighting
 npm install swiper                          # Carousel component
@@ -35,11 +35,11 @@ npm install swiper                          # Carousel component
 
 ---
 
-## Usage
+## Quick start
 
-### UI only (no backend needed)
+### UI only (no backend required)
 
-144 of 145 components work standalone — no Firebase, no backend:
+144 of 145 components work standalone:
 
 ```typescript
 import { ButtonComponent, CardComponent, TextComponent } from 'valtech-components';
@@ -50,7 +50,7 @@ import { ButtonComponent, CardComponent, TextComponent } from 'valtech-component
   template: `
     <val-card [props]="{ title: 'My Card' }">
       <val-text [props]="{ content: 'Hello World' }" />
-      <val-button [props]="{ text: 'Click me', color: 'primary' }" />
+      <val-button preset="primary-round" [props]="{ text: 'Click me' }" />
     </val-card>
   `
 })
@@ -59,49 +59,156 @@ export class MyComponent {}
 
 ### Full integration (auth + Firebase + i18n)
 
-Add providers in `main.ts`:
+Wire providers in `main.ts`:
 
 ```typescript
 import {
   provideValtechFirebase,
   provideValtechAuth,
   provideValtechI18n,
-  createFirebaseConfig,
+  provideValtechErrorHandling,
+  provideValtechSkeleton,
+  provideValtechPresets,
+  HandoffService,
 } from 'valtech-components';
-import firebaseConfig from './config/firebase.config.json';
+import { APP_INITIALIZER } from '@angular/core';
 
 bootstrapApplication(AppComponent, {
   providers: [
-    provideValtechFirebase(createFirebaseConfig(firebaseConfig)),
-    provideValtechAuth({ apiUrl: 'https://api.yourapp.com' }),
-    provideValtechI18n({ defaultLang: 'en', supportedLangs: ['en', 'es', 'pt'] }),
+    provideValtechFirebase(environment.valtechFirebase),
+
+    // Auth must come before provideValtechErrorHandling
+    provideValtechAuth({
+      apiUrl: environment.apiUrl,
+      appId: 'my-app',
+      loginRoute: '/login',
+      homeRoute: '/app',
+      enableFirebaseIntegration: true,
+      enableTabSync: true,
+    }),
+
+    // HTTP error observability — always after provideValtechAuth
+    provideValtechErrorHandling(),
+
+    // Cross-app session handoff — always after provideValtechAuth
+    {
+      provide: APP_INITIALIZER,
+      multi: true,
+      deps: [HandoffService],
+      useFactory: (h: HandoffService) => () => h.detectAndExchangeHandoff(),
+    },
+
+    provideValtechI18n({
+      defaultLanguage: 'es',
+      supportedLanguages: ['es', 'en'],
+      content: APP_I18N_CONTENT,
+    }),
+
+    provideValtechPresets(APP_PRESETS),
+    provideValtechSkeleton({ animated: true }),
   ],
 });
 ```
 
+**Provider order matters:**
+
+```
+provideHttpClient
+  ↓
+provideValtechFirebase   (initializes Firebase app)
+  ↓
+provideValtechAuth       (registers auth HTTP interceptor)
+  ↓
+provideValtechErrorHandling  (registers error interceptor — composes with auth)
+  ↓
+APP_INITIALIZER handoff  (depends on AuthService being configured)
+```
+
 ---
 
 ## Components
 
 | Category | Count | Includes |
 |----------|------:|---------|
-| Atoms | 24 | avatar, button, icon, text, image, skeleton, progress-bar, qr-code… |
-| Molecules | 81 | inputs (text, email, phone, pin, date), cards, tabs, accordion, pagination… |
-| Organisms | 31 | forms, data-table, menu, toolbar, login, comment-section, infinite-list… |
-| Templates | 9 | page-wrapper, page-content, docs-shell, auth-background, maintenance-page… |
-| **Total** | **145** | |
+| Atoms | ~24 | `val-button`, `val-text`, `val-icon`, `val-avatar`, `val-image`, `val-badge`, `val-skeleton`, `val-progress-bar`, `val-qr-code`, `val-page-waves` |
+| Molecules | ~81 | `val-card`, `val-input`, `val-select`, `val-date-picker`, `val-tabs`, `val-accordion`, `val-searchbar`, `val-empty-state`, `val-ticket-card`, `val-field-list`, `val-stats-bar`, `val-article-card` |
+| Organisms | ~31 | `val-form`, `val-data-table`, `val-bottom-nav`, `val-toolbar`, `val-menu`, `val-login`, `val-comment-section`, `val-qr-scanner`, `val-search-header`, `val-share-profile-modal`, `val-fun-modal` |
+| Templates | ~9 | `val-page-wrapper`, `val-page-content`, `val-auth-background`, `val-maintenance-page`, `val-docs-shell` |
+
+Components requiring a backend API: `val-login`, `val-content-reaction`.
+
+### Buttons — presets, not factories
+
+```html
+<!-- Declarative (preferred) -->
+<val-button preset="primary-round" [props]="{ text: 'Save' }" />
+<val-button preset="secondary" [props]="{ text: 'Cancel' }" />
+<val-button preset="danger-round" [props]="{ text: 'Delete' }" />
+```
+
+Built-in presets: `primary`, `primary-round`, `primary-block`, `primary-full`, `secondary`, `secondary-round`, `solid`, `solid-round`, `solid-block`, `outline`, `outline-round`, `clear`, `clear-round`, `danger`, `danger-round`.
+
+### Date picker
+
+Use `val-date-picker` instead of `val-date-input` or `ion-datetime` (ion-datetime has a known bug with empty day grids in modals):
+
+```html
+<val-date-picker
+  [props]="{
+    control: myControl,
+    label: 'Date',
+    placeholder: 'Select date',
+    locale: 'es-CL',
+    firstWeekday: 1
+  }"
+  (valueChange)="onDate($event)"
+/>
+```
+
+Value format: `YYYY-MM-DD` (local date string, no timezone shift). If the backend returns ISO timestamps, slice to 10 chars: `value.slice(0, 10)`.
+
+### Field list (editable repeating items)
+
+```html
+<val-field-list
+  [props]="{
+    fields: [
+      { name: 'name', label: 'Prize name', maxlength: 200 },
+      { name: 'description', label: 'Description', maxlength: 300 }
+    ],
+    items: seedSignal(),
+    itemLabel: 'Prize {n}',
+    addLabel: 'Add prize'
+  }"
+  (itemsChange)="onItemsChange($event)"
+/>
+```
+
+Pass a **separate seed signal** for `items` — do not bind the editing signal directly (it re-seeds on every change).
+
+### Empty / error state
 
-Components requiring a backend API: `LoginComponent`, `ContentReactionComponent`.
+```html
+@if (page.loading()) {
+  <val-skeleton-layout [props]="{ preset: 'list', rows: 4 }" />
+} @else if (page.errorState(); as e) {
+  <val-empty-state [props]="e" />
+} @else if (items().length === 0) {
+  <val-empty-state [props]="{ variant: 'empty', title: t('emptyTitle') }" />
+} @else {
+  <!-- content -->
+}
+```
 
 ---
 
 ## Services
 
 **No setup required:**
-`ThemeService` · `ToastService` · `NavigationService` · `DownloadService` · `IconsService` · `LocaleService` · `LocalStorageService` · `ModalService` · `ConfirmationDialogService` · `QrGeneratorService` · `PaginationService` · `SkeletonService`
+`ThemeService` · `ToastService` · `NavigationService` · `DownloadService` · `IconService` · `LocaleService` · `LocalStorageService` · `ModalService` · `ConfirmationDialogService` · `QrGeneratorService` · `PaginationService` · `SkeletonService`
 
 **Requires `provideValtechAuth`:**
-`AuthService` · `OAuthService` · `SessionService` · `TokenService` · `AuthStateService` · `DeviceService`
+`AuthService` · `OAuthService` · `SessionService` · `TokenService` · `AuthStateService` · `DeviceService` · `HandoffService` · `OrgSwitchService`
 
 **Requires `provideValtechFirebase`:**
 `FirebaseService` · `AnalyticsService` · `FirestoreService` · `MessagingService` · `NotificationsService` · `FirebaseStorageService`
@@ -109,23 +216,147 @@ Components requiring a backend API: `LoginComponent`, `ContentReactionComponent`
 **Requires `provideValtechI18n`:**
 `I18nService`
 
+**Requires `provideValtechErrorHandling`:**
+`ValtechErrorService`
+
 ---
 
-## Technologies
+## Common patterns
 
-Angular 18+ · Ionic 8+ · Capacitor 6+ · Firebase 10+ · RxJS 7.8+
+### Page loading state — `createPageState`
+
+Replaces ~15 lines of boilerplate (loading signal + error signal + try/catch + computed error state):
+
+```typescript
+import { createPageState, connectPageRefresh } from 'valtech-components';
+
+export class MyPage {
+  private svc = inject(MyService);
+  private i18n = inject(I18nService);
+  readonly items = signal<Item[]>([]);
+
+  readonly page = createPageState(this.i18n, async () => {
+    const res = await firstValueFrom(this.svc.getItems());
+    this.items.set(res.items);
+  });
+
+  constructor() {
+    connectPageRefresh(() => this.page.reload());
+  }
+}
+```
+
+`page.loading()` · `page.errorState()` · `page.reload()` — all signals/promises, ready to bind.
+
+### Pull-to-refresh
+
+Every page that displays remote data must register a refresh handler. Use `connectPageRefresh` in the constructor — it registers and auto-cleans via `DestroyRef`:
+
+```typescript
+import { connectPageRefresh, createRefreshableStream } from 'valtech-components';
+
+export class MyPage {
+  private data = createRefreshableStream(() => this.svc.getItems());
+  readonly items = this.data.data;
+  readonly loading = this.data.loading;
+
+  constructor() {
+    connectPageRefresh(() => this.data.reload());
+  }
+}
+```
+
+### Error handling in catch blocks
+
+```typescript
+import { ValtechErrorService } from 'valtech-components';
+
+export class MyPage {
+  private errors = inject(ValtechErrorService);
+
+  async save() {
+    try {
+      await firstValueFrom(this.api.updateX(...));
+    } catch (err) {
+      this.errors.handle(err, {
+        context: 'mypage.save',
+        i18nMap: { BACKEND_CODE: 'i18nKey' },
+        fallbackKey: 'saveError',
+        i18nNamespace: 'MyNamespace',
+      });
+    }
+  }
+}
+```
+
+### Cross-app session handoff
+
+Seamlessly transfer a logged-in session from one factory app to another:
+
+```typescript
+// App A — create handoff and redirect
+const { url } = await handoff.createHandoff({ app: 'sigify', route: '/docs/123' });
+window.location.href = url;
+
+// App B — auto-handled in bootstrap via APP_INITIALIZER (see Full integration above)
+```
+
+### OAuth callback route
+
+Add this route to `app.routes.ts` if your app uses social login:
+
+```typescript
+import { OAuthCallbackComponent } from 'valtech-components';
+
+{ path: 'auth/oauth/callback', component: OAuthCallbackComponent }
+```
+
+Without this route, post-login redirects to a 404.
+
+### Toasts — always `color: 'dark'`
+
+```typescript
+// All toasts use color: 'dark' regardless of message type
+this.toast.show({ message: 'Saved', color: 'dark', duration: 2000 });
+this.toast.show({ message: 'Error: ...', color: 'dark', duration: 3000 });
+```
+
+### Content reactions (feedback widget)
+
+```html
+<val-content-reaction [props]="{
+  entityRef: { entityType: 'blog', entityId: post.slug },
+  question: 'Was this article helpful?',
+  emojis: ['👎', '👍'],
+  commentOnValues: ['negative'],
+  allowAnonymous: true
+}" />
+```
+
+Requires `provideValtechFeedback({ apiUrl, appId })` in `main.ts`.
 
 ---
 
-## Development
+## Styles
 
-```bash
-npm install
-npm run storybook     # http://localhost:6006
-npm run build         # build library
-npm run test          # unit tests
+Import fonts and base styles in your app's `variables.scss`:
+
+```scss
+@import "valtech-components/styles/fonts.scss";  // Nunito Sans (default) + Khula (Bingo brand)
+
+:root {
+  --ion-font-family: "Nunito Sans", Arial, sans-serif;
+}
 ```
 
+All `font-size` values in the lib use `rem` to respect the user's font size preference (`FontSizeService` scales the root `html` element).
+
+---
+
+## Technologies
+
+Angular 18+ · Ionic 8+ · Capacitor 6+ · Firebase 10+ · RxJS 7.8+
+
 ---
 
 ## License