valtech-components 2.0.787 → 2.0.795

package/src/stories/Introduction.mdx

@@ -0,0 +1,649 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Introduction" />
+
+<div className="sb-container">
+
+# Valtech Components
+
+**valtech-components** is a UI component library for **Angular 18+ / Ionic 8+** designed to accelerate the development of mobile and web applications. It follows the **Atomic Design** pattern and uses an **Object-First Configuration** approach for a consistent and scalable API.
+
+<div className="sb-highlight">
+  <strong>Ideal for:</strong> Hybrid mobile apps, PWAs, e-commerce platforms, management systems, and applications with complex forms.
+</div>
+
+<div className="sb-section">
+
+## Key Features
+
+<div className="sb-features">
+
+- **91 components** organized in Atoms, Molecules, Organisms and Templates
+- **Object-First Pattern** - All components use a single `props` input for configuration
+- **Locale Support** - Simple locale management with `LocaleService`
+- **Dark/Light Themes** - Full dark mode support via CSS variables
+- **Standalone Components** - No modules required, import only what you need
+- **Accessibility** - Accessible components following WCAG 2.1
+- **11 services** - Toast, Modal, QR Generator, Theme, Navigation and more
+- **Reactive Forms** - Native integration with Angular Reactive Forms
+
+</div>
+
+</div>
+
+<div className="sb-section">
+
+## Atomic Design Architecture
+
+The library follows the Atomic Design pattern to organize components by complexity levels:
+
+<div className="sb-grid">
+
+<div className="sb-card atom">
+  <h3>Atoms</h3>
+  <p><strong>17 components</strong></p>
+  <p>Basic, indivisible elements: button, text, icon, image, avatar, title, divider, progress-bar, skeleton, countdown, price-tag, qr-code, fab...</p>
+</div>
+
+<div className="sb-card molecule">
+  <h3>Molecules</h3>
+  <p><strong>61 components</strong></p>
+  <p>Functional combinations: form inputs (text, email, phone, currency, date-range), cards, alerts, accordion, tabs, pagination, rating, timeline, ticket-grid, share-buttons...</p>
+</div>
+
+<div className="sb-card organism">
+  <h3>Organisms</h3>
+  <p><strong>11 components</strong></p>
+  <p>Complex UI sections: form, header, footer, toolbar, wizard, data-table, comment-section, banner, article...</p>
+</div>
+
+<div className="sb-card template">
+  <h3>Templates</h3>
+  <p><strong>2 components</strong></p>
+  <p>Page layouts: layout (with header/footer), simple (basic content)</p>
+</div>
+
+</div>
+
+</div>
+
+<div className="sb-section">
+
+## Included Services
+
+<div className="sb-services-list">
+  <div className="sb-service-item">
+    <code>LocaleService</code>
+    <span>Simple locale management with localStorage</span>
+  </div>
+  <div className="sb-service-item">
+    <code>ModalService</code>
+    <span>Open modals and sheets with full configuration</span>
+  </div>
+  <div className="sb-service-item">
+    <code>ToastService</code>
+    <span>Toast notifications with colors and positions</span>
+  </div>
+  <div className="sb-service-item">
+    <code>ConfirmationDialogService</code>
+    <span>Confirmation dialogs for critical actions</span>
+  </div>
+  <div className="sb-service-item">
+    <code>QrGeneratorService</code>
+    <span>QR code generation in multiple formats</span>
+  </div>
+  <div className="sb-service-item">
+    <code>ThemeService</code>
+    <span>Light/dark theme control</span>
+  </div>
+  <div className="sb-service-item">
+    <code>NavigationService</code>
+    <span>Programmatic navigation with history</span>
+  </div>
+  <div className="sb-service-item">
+    <code>DownloadService</code>
+    <span>File and blob downloads</span>
+  </div>
+  <div className="sb-service-item">
+    <code>LocalStorageService</code>
+    <span>Typed localStorage persistence</span>
+  </div>
+  <div className="sb-service-item">
+    <code>InAppBrowserService</code>
+    <span>Open URLs in internal browser</span>
+  </div>
+  <div className="sb-service-item">
+    <code>LinkProcessorService</code>
+    <span>Link processing in text</span>
+  </div>
+  <div className="sb-service-item">
+    <code>IconsService</code>
+    <span>Custom icon registration</span>
+  </div>
+</div>
+
+</div>
+
+<div className="sb-section">
+
+## Object-First Configuration Pattern
+
+All components follow the **object-first** pattern where configuration is passed through a single `@Input() props`:
+
+```html
+<!-- Traditional Pattern (multiple inputs) -->
+<my-button
+  [text]="'Save'"
+  [color]="'primary'"
+  [disabled]="false"
+  [loading]="isLoading"
+  [icon]="'save'"
+></my-button>
+
+<!-- Object-First Pattern (single input) -->
+<val-button
+  [props]="{
+    text: 'Save',
+    color: 'primary',
+    state: isLoading ? 'WORKING' : 'ENABLED',
+    icon: { name: 'save-outline', slot: 'start' }
+  }"
+  (onClick)="save()"
+></val-button>
+```
+
+### Advantages
+
+- **Scalability** - Add properties without breaking the existing API
+- **Strong typing** - TypeScript interfaces (`ButtonMetadata`, `CardMetadata`, etc.)
+- **Factories** - Helper functions to create common configurations
+- **Consistency** - Same structure across all 91 components
+- **Serializable** - Configurations that can come from a backend/CMS
+
+</div>
+
+<div className="sb-section">
+
+## Raffle Platform Components
+
+The library includes specialized components for building raffle and lottery platforms:
+
+<div className="sb-raffle-grid">
+
+<div className="sb-raffle-card">
+  <h4>val-ticket-grid</h4>
+  <p>Visual grid for ticket selection with states (available, sold, reserved, selected)</p>
+</div>
+
+<div className="sb-raffle-card">
+  <h4>val-countdown</h4>
+  <p>Configurable countdown with multiple formats (full, compact, minimal, digital)</p>
+</div>
+
+<div className="sb-raffle-card">
+  <h4>val-price-tag</h4>
+  <p>Price tag with support for 9 currencies and discounts</p>
+</div>
+
+<div className="sb-raffle-card">
+  <h4>val-number-stepper</h4>
+  <p>Quantity selector with presets and total price calculation</p>
+</div>
+
+<div className="sb-raffle-card">
+  <h4>val-winner-display</h4>
+  <p>Winner presentation with animations (confetti, spotlight, zoom)</p>
+</div>
+
+<div className="sb-raffle-card">
+  <h4>val-raffle-status-card</h4>
+  <p>Raffle status card with progress, countdown and actions</p>
+</div>
+
+<div className="sb-raffle-card">
+  <h4>val-participant-card</h4>
+  <p>Participant card with tickets, payment status and admin actions</p>
+</div>
+
+<div className="sb-raffle-card">
+  <h4>val-share-buttons</h4>
+  <p>Share buttons for WhatsApp, Facebook, Twitter, etc.</p>
+</div>
+
+<div className="sb-raffle-card">
+  <h4>val-data-table</h4>
+  <p>Data table with sorting, pagination and multi-selection</p>
+</div>
+
+</div>
+
+</div>
+
+<div className="sb-section">
+
+## Quick Start
+
+```typescript
+// 1. Import standalone components
+import {
+  ButtonComponent,
+  TextComponent,
+  CardComponent,
+  TextInputComponent,
+  ComponentStates
+} from 'valtech-components';
+
+@Component({
+  standalone: true,
+  imports: [ButtonComponent, TextComponent, CardComponent, TextInputComponent],
+  template: `
+    <val-card [props]="{ variant: 'outlined', padding: 'medium' }">
+      <val-text [props]="{ content: 'Contact Form', size: 'lg', weight: 'bold' }"></val-text>
+
+      <val-text-input
+        [props]="{
+          control: nameControl,
+          label: 'Name',
+          placeholder: 'Your full name',
+          state: states.ENABLED
+        }"
+      ></val-text-input>
+
+      <val-button
+        [props]="{ text: 'Submit', color: 'primary', expand: 'block' }"
+        (onClick)="submit()"
+      ></val-button>
+    </val-card>
+  `
+})
+export class ContactFormComponent {
+  states = ComponentStates;
+  nameControl = new FormControl('');
+
+  submit() {
+    console.log('Submitting:', this.nameControl.value);
+  }
+}
+```
+
+</div>
+
+<div className="sb-section">
+
+## Component States
+
+Interactive components support four states through `ComponentStates`:
+
+<div className="sb-states-list">
+  <div className="sb-state-item">
+    <span className="sb-state-name">Enabled</span>
+    <code>ENABLED</code>
+    <span className="sb-state-desc">Normal, interactive state</span>
+  </div>
+  <div className="sb-state-item">
+    <span className="sb-state-name">Disabled</span>
+    <code>DISABLED</code>
+    <span className="sb-state-desc">Does not allow interaction</span>
+  </div>
+  <div className="sb-state-item">
+    <span className="sb-state-name">Working</span>
+    <code>WORKING</code>
+    <span className="sb-state-desc">Operation in progress</span>
+  </div>
+  <div className="sb-state-item">
+    <span className="sb-state-name">Error</span>
+    <code>ERROR</code>
+    <span className="sb-state-desc">Indicates a problem</span>
+  </div>
+</div>
+
+```typescript
+import { ComponentStates } from 'valtech-components';
+
+// In your component
+buttonState = ComponentStates.ENABLED;
+
+async save() {
+  this.buttonState = ComponentStates.WORKING;
+  try {
+    await this.api.save();
+    this.buttonState = ComponentStates.ENABLED;
+  } catch {
+    this.buttonState = ComponentStates.ERROR;
+  }
+}
+```
+
+</div>
+
+<div className="sb-section">
+
+## Locale Management
+
+The library uses a simple locale management approach with `LocaleService`:
+
+```typescript
+// In your component
+import { LocaleService } from 'valtech-components';
+
+@Component({
+  template: `
+    <val-language-selector
+      [props]="{ showFlags: true, showLabel: true }"
+      (languageChange)="onLanguageChange($event)"
+    ></val-language-selector>
+  `
+})
+export class MyComponent {
+  localeService = inject(LocaleService);
+
+  // Get current locale
+  currentLocale = this.localeService.getLocale(); // 'es', 'en', etc.
+
+  onLanguageChange(locale: string) {
+    // Changes locale and reloads the page
+    this.localeService.setLocale(locale);
+  }
+}
+```
+
+</div>
+
+<div className="sb-section">
+
+## Storybook Navigation
+
+Use the sidebar to explore components organized by category:
+
+- **Atoms** - Basic elements (button, text, icon, image, avatar...)
+- **Molecules** - Compound components (inputs, cards, alerts, modals...)
+- **Organisms** - UI sections (form, header, wizard, data-table...)
+- **Templates** - Page layouts
+
+Each component includes:
+- **Documentation** - Description and use cases
+- **Playground** - Interactive controls to test props
+- **Examples** - Implementation code
+
+</div>
+
+</div>
+
+<style>
+  {`
+    .sb-container {
+      font-family: 'Nunito Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      max-width: 960px;
+      margin: 0 auto;
+      line-height: 1.6;
+      color: #333;
+    }
+
+    .sb-container h1 {
+      color: #1a1a2e;
+      font-size: 2.5rem;
+      margin-bottom: 1rem;
+    }
+
+    .sb-container > p:first-of-type {
+      font-size: 1.1rem;
+      color: #4a4a4a;
+    }
+
+    .sb-highlight {
+      background: linear-gradient(135deg, #6366f1 0%, #8b5cf6 100%);
+      color: #fff;
+      padding: 18px 24px;
+      border-radius: 10px;
+      margin: 24px 0;
+      font-size: 15px;
+      box-shadow: 0 4px 15px rgba(99, 102, 241, 0.3);
+    }
+
+    .sb-highlight strong {
+      color: #fff;
+    }
+
+    .sb-section {
+      margin-bottom: 64px;
+      padding-bottom: 48px;
+      border-bottom: 1px solid #e5e7eb;
+    }
+
+    .sb-section:last-child {
+      border-bottom: none;
+      margin-bottom: 32px;
+    }
+
+    .sb-section h2 {
+      color: #1a1a2e;
+      margin-bottom: 20px;
+      font-size: 1.5rem;
+    }
+
+    .sb-section h3 {
+      color: #374151;
+      font-size: 1.1rem;
+      margin-top: 24px;
+    }
+
+    .sb-features {
+      background: #f8fafc;
+      padding: 24px 28px;
+      border-radius: 10px;
+      margin-top: 16px;
+      border: 1px solid #e2e8f0;
+    }
+
+    .sb-features li {
+      margin-bottom: 12px;
+      font-size: 15px;
+      color: #475569;
+    }
+
+    .sb-features li strong {
+      color: #1e293b;
+    }
+
+    .sb-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+      gap: 16px;
+      margin-top: 20px;
+    }
+
+    .sb-card {
+      background: #fff;
+      border: 2px solid #e5e7eb;
+      border-radius: 12px;
+      padding: 20px;
+      transition: all 0.2s ease;
+    }
+
+    .sb-card:hover {
+      transform: translateY(-2px);
+      box-shadow: 0 8px 24px rgba(0,0,0,0.08);
+    }
+
+    .sb-card.atom {
+      border-left: 4px solid #3b82f6;
+      background: linear-gradient(135deg, #fff 0%, #eff6ff 100%);
+    }
+    .sb-card.molecule {
+      border-left: 4px solid #22c55e;
+      background: linear-gradient(135deg, #fff 0%, #f0fdf4 100%);
+    }
+    .sb-card.organism {
+      border-left: 4px solid #f97316;
+      background: linear-gradient(135deg, #fff 0%, #fff7ed 100%);
+    }
+    .sb-card.template {
+      border-left: 4px solid #a855f7;
+      background: linear-gradient(135deg, #fff 0%, #faf5ff 100%);
+    }
+
+    .sb-card h3 {
+      margin: 0 0 10px 0;
+      font-size: 1.1rem;
+      color: #1e293b;
+    }
+
+    .sb-card.atom h3 { color: #1d4ed8; }
+    .sb-card.molecule h3 { color: #16a34a; }
+    .sb-card.organism h3 { color: #ea580c; }
+    .sb-card.template h3 { color: #9333ea; }
+
+    .sb-card p {
+      margin: 6px 0;
+      color: #64748b;
+      font-size: 14px;
+      line-height: 1.5;
+    }
+
+    .sb-card p strong {
+      color: #334155;
+    }
+
+    /* Services List */
+    .sb-services-list {
+      display: flex;
+      flex-direction: column;
+      gap: 12px;
+      margin-top: 16px;
+    }
+
+    .sb-service-item {
+      display: flex;
+      align-items: center;
+      gap: 16px;
+      padding: 14px 18px;
+      background: #f8fafc;
+      border-radius: 8px;
+      border: 1px solid #e2e8f0;
+      transition: all 0.15s ease;
+    }
+
+    .sb-service-item:hover {
+      background: #f1f5f9;
+      border-color: #cbd5e1;
+    }
+
+    .sb-service-item code {
+      background: #1e293b;
+      color: #e2e8f0;
+      padding: 6px 12px;
+      border-radius: 6px;
+      font-size: 13px;
+      font-weight: 600;
+      font-family: 'JetBrains Mono', 'Fira Code', 'Monaco', monospace;
+      min-width: 200px;
+      text-align: center;
+    }
+
+    .sb-service-item span {
+      color: #475569;
+      font-size: 14px;
+    }
+
+    /* States List */
+    .sb-states-list {
+      display: flex;
+      flex-direction: column;
+      gap: 10px;
+      margin-top: 16px;
+      margin-bottom: 24px;
+    }
+
+    .sb-state-item {
+      display: flex;
+      align-items: center;
+      gap: 16px;
+      padding: 12px 16px;
+      background: #f8fafc;
+      border-radius: 8px;
+      border: 1px solid #e2e8f0;
+    }
+
+    .sb-state-item .sb-state-name {
+      font-weight: 600;
+      color: #1e293b;
+      min-width: 80px;
+    }
+
+    .sb-state-item code {
+      background: #ecfdf5;
+      color: #059669;
+      padding: 4px 10px;
+      border-radius: 4px;
+      font-size: 13px;
+      font-weight: 600;
+      font-family: 'JetBrains Mono', 'Fira Code', 'Monaco', monospace;
+      min-width: 100px;
+      text-align: center;
+    }
+
+    .sb-state-item .sb-state-desc {
+      color: #64748b;
+      font-size: 14px;
+    }
+
+    .sb-raffle-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+      gap: 14px;
+      margin-top: 16px;
+    }
+
+    .sb-raffle-card {
+      background: linear-gradient(135deg, #fef3c7 0%, #fde68a 100%);
+      border-radius: 10px;
+      padding: 18px;
+      border: 1px solid #fcd34d;
+    }
+
+    .sb-raffle-card h4 {
+      margin: 0 0 10px 0;
+      font-size: 15px;
+      color: #92400e;
+      font-weight: 700;
+    }
+
+    .sb-raffle-card p {
+      margin: 0;
+      font-size: 13px;
+      color: #78350f;
+      line-height: 1.5;
+    }
+
+    /* Light theme code blocks */
+    pre {
+      background: #f8fafc !important;
+      border-radius: 10px;
+      padding: 20px !important;
+      overflow-x: auto;
+      border: 1px solid #e2e8f0;
+      margin-top: 16px;
+    }
+
+    pre code {
+      font-family: 'JetBrains Mono', 'Fira Code', 'Monaco', monospace;
+      font-size: 13px;
+      line-height: 1.6;
+      color: #334155;
+      background: transparent !important;
+    }
+
+    code {
+      font-family: 'JetBrains Mono', 'Fira Code', 'Monaco', monospace;
+    }
+
+    /* Inline code */
+    p code, li code {
+      background: #f1f5f9;
+      color: #0f172a;
+      padding: 2px 6px;
+      border-radius: 4px;
+      font-size: 0.9em;
+    }
+  `}
+</style>