valtech-components 2.0.687 → 2.0.689

package/src/lib/components/templates/page-template/page-template.component.ts

@@ -0,0 +1,164 @@
+import { CommonModule } from '@angular/common';
+import { Component, computed, EventEmitter, inject, Input, Output } from '@angular/core';
+import { NavController } from '@ionic/angular';
+import { IonCol, IonGrid, IonHeader, IonRow, IonTitle, IonToolbar } from '@ionic/angular/standalone';
+import { ExpandableTextComponent } from '../../molecules/expandable-text/expandable-text.component';
+import { ButtonComponent } from '../../atoms/button/button.component';
+import { PageTemplateMetadata } from './types';
+import { I18nService } from '../../../services/i18n';
+
+/**
+ * val-page-template
+ *
+ * A page template component with title, expandable description,
+ * content projection, and optional back navigation button.
+ *
+ * @example
+ * <val-page-template
+ *   [props]="{
+ *     pageTitle: 'Getting Started',
+ *     pageDescription: 'Learn how to use our components...',
+ *     showBackButton: true
+ *   }"
+ * >
+ *   <div extra-description>
+ *     <p>Additional info here</p>
+ *   </div>
+ *
+ *   <!-- Main content -->
+ *   <my-content></my-content>
+ *
+ *   <div extra-footer>
+ *     <p>Footer content</p>
+ *   </div>
+ * </val-page-template>
+ *
+ * @input props - Page template configuration
+ * @output onBack - Emits when back button is clicked
+ */
+@Component({
+  selector: 'val-page-template',
+  standalone: true,
+  imports: [
+    CommonModule,
+    IonHeader,
+    IonToolbar,
+    IonTitle,
+    ExpandableTextComponent,
+    IonGrid,
+    IonRow,
+    IonCol,
+    ButtonComponent,
+  ],
+  template: `
+    @if (props.pageTitle) {
+      <ion-header [class.ion-no-border]="true">
+        <ion-toolbar style="--background: transparent; --padding-start: 0; --padding-end: 0;">
+          <ion-title class="page-title" size="large" style="--padding-start: 0; --padding-end: 0; padding: 0;">{{ props.pageTitle }}</ion-title>
+        </ion-toolbar>
+      </ion-header>
+    }
+    <ion-grid>
+      <ion-row class="ion-justify-content-center description-row">
+        <ion-col size="12" size-md="10" size-lg="8">
+          @if (props.pageDescription) {
+            <div class="description-container">
+              <val-expandable-text
+                [props]="{
+                  limit: props.descriptionLimit || 180,
+                  content: props.pageDescription,
+                  color: props.descriptionColor || 'dark',
+                }"
+              />
+            </div>
+          }
+          <ng-content select="[extra-description]"></ng-content>
+        </ion-col>
+      </ion-row>
+      <ng-content></ng-content>
+      <ng-content select="[extra-footer]"></ng-content>
+      @if (props.showBackButton) {
+        <ion-row class="ion-justify-content-center back-row">
+          <ion-col size="12" size-md="10" size-lg="8">
+            <val-button
+              class="back-button"
+              [props]="{
+                text: backButtonText(),
+                color: 'dark',
+                size: 'small',
+                type: 'button',
+                state: 'ENABLED',
+                fill: 'outline',
+                shape: 'round',
+                icon: {
+                  name: 'arrow-back-outline',
+                  slot: 'start'
+                }
+              }"
+              (onClick)="handleBack()"
+            />
+          </ion-col>
+        </ion-row>
+      }
+    </ion-grid>
+  `,
+  styles: `
+    .page-title {
+      font-size: 1.6rem;
+      font-weight: 800;
+    }
+
+    @media (min-width: 768px) {
+      .page-title {
+        font-size: 2rem;
+      }
+    }
+
+    .description-row {
+      margin-bottom: 16px;
+    }
+
+    .description-container {
+      margin-top: 1rem;
+    }
+
+    .back-row {
+      margin-bottom: 16px;
+    }
+
+    .back-button {
+      display: block;
+      margin: 1rem 0;
+    }
+  `,
+})
+export class PageTemplateComponent {
+  private nav = inject(NavController);
+  private i18n = inject(I18nService);
+
+  /**
+   * Page template configuration.
+   */
+  @Input() props: PageTemplateMetadata = {};
+
+  /**
+   * Emits when the back button is clicked.
+   */
+  @Output() onBack = new EventEmitter<void>();
+
+  /**
+   * Back button text - reactive to language changes.
+   */
+  backButtonText = computed(() => {
+    this.i18n.lang(); // Track language changes
+    return this.props.backButtonText || this.i18n.t('back');
+  });
+
+  /**
+   * Handles back navigation.
+   */
+  handleBack(): void {
+    this.onBack.emit();
+    this.nav.back();
+  }
+}

package/src/lib/components/templates/page-template/page-template.stories.ts

@@ -0,0 +1,174 @@
+import type { Meta, StoryObj } from '@storybook/angular';
+import { moduleMetadata } from '@storybook/angular';
+import { CommonModule } from '@angular/common';
+import { PageTemplateComponent } from './page-template.component';
+import { ExpandableTextComponent } from '../../molecules/expandable-text/expandable-text.component';
+import { ButtonComponent } from '../../atoms/button/button.component';
+import { IonCol, IonGrid, IonHeader, IonRow, IonTitle, IonToolbar } from '@ionic/angular/standalone';
+
+const meta: Meta<PageTemplateComponent> = {
+  title: 'Templates/PageTemplate',
+  component: PageTemplateComponent,
+  decorators: [
+    moduleMetadata({
+      imports: [
+        CommonModule,
+        PageTemplateComponent,
+        ExpandableTextComponent,
+        ButtonComponent,
+        IonGrid,
+        IonRow,
+        IonCol,
+        IonHeader,
+        IonToolbar,
+        IonTitle,
+      ],
+    }),
+  ],
+  tags: ['autodocs'],
+  argTypes: {
+    props: {
+      description: 'Page template configuration object',
+      control: 'object',
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component: `
+## val-page-template
+
+A page template component with title, description, and navigation.
+
+### Problem it solves
+
+Many pages in an application share common structure:
+- Large page title
+- Expandable description
+- Centered content grid
+- Optional back button
+- Slots for extra content
+
+This template provides that structure out of the box.
+
+### Usage
+
+\`\`\`html
+<val-page-template
+  [props]="{
+    pageTitle: 'Getting Started',
+    pageDescription: 'Learn how to use our component library...',
+    showBackButton: true,
+    backButtonText: 'Go Back'
+  }"
+>
+  <div extra-description>
+    <p>Additional context here</p>
+  </div>
+
+  <!-- Main content (default slot) -->
+  <ion-row>
+    <ion-col>Your content here</ion-col>
+  </ion-row>
+
+  <div extra-footer>
+    <p>Footer content</p>
+  </div>
+</val-page-template>
+\`\`\`
+
+### Content Slots
+
+- **Default slot**: Main page content
+- **[extra-description]**: Additional content after description
+- **[extra-footer]**: Content before the back button
+
+### Features
+
+- Large collapsible title
+- Expandable description text
+- Responsive grid layout (centered on larger screens)
+- Optional back navigation button
+- Content projection slots
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<PageTemplateComponent>;
+
+export const Default: Story = {
+  args: {
+    props: {
+      pageTitle: 'Getting Started',
+      pageDescription:
+        'Welcome to our component library! This guide will help you understand how to use our components effectively. You can explore atoms, molecules, and organisms to build your interfaces quickly.',
+    },
+  },
+};
+
+export const WithBackButton: Story = {
+  args: {
+    props: {
+      pageTitle: 'Component Details',
+      pageDescription:
+        'This page shows detailed information about a specific component. You can navigate back to the main list using the button below.',
+      showBackButton: true,
+      backButtonText: 'Back to List',
+    },
+  },
+};
+
+export const LongDescription: Story = {
+  args: {
+    props: {
+      pageTitle: 'Documentation',
+      pageDescription:
+        'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.',
+      descriptionLimit: 150,
+    },
+  },
+};
+
+export const TitleOnly: Story = {
+  args: {
+    props: {
+      pageTitle: 'Dashboard',
+    },
+  },
+};
+
+export const WithContent: Story = {
+  render: () => ({
+    props: {
+      templateProps: {
+        pageTitle: 'Products',
+        pageDescription: 'Browse our product catalog',
+        showBackButton: true,
+      },
+    },
+    template: `
+      <val-page-template [props]="templateProps">
+        <ion-row>
+          <ion-col size="12" size-md="6" size-lg="4">
+            <div style="padding: 16px; background: var(--ion-color-light); border-radius: 8px;">
+              Product Card 1
+            </div>
+          </ion-col>
+          <ion-col size="12" size-md="6" size-lg="4">
+            <div style="padding: 16px; background: var(--ion-color-light); border-radius: 8px;">
+              Product Card 2
+            </div>
+          </ion-col>
+          <ion-col size="12" size-md="6" size-lg="4">
+            <div style="padding: 16px; background: var(--ion-color-light); border-radius: 8px;">
+              Product Card 3
+            </div>
+          </ion-col>
+        </ion-row>
+      </val-page-template>
+    `,
+  }),
+};

package/src/lib/components/templates/page-template/types.ts

@@ -0,0 +1,17 @@
+/**
+ * Configuration for the page template component.
+ */
+export interface PageTemplateMetadata {
+  /** Page title displayed in large header style */
+  pageTitle?: string;
+  /** Page description (expandable text) */
+  pageDescription?: string;
+  /** Show a back button at the bottom */
+  showBackButton?: boolean;
+  /** Custom text for the back button (default: 'Back') */
+  backButtonText?: string;
+  /** Character limit for description before expand (default: 180) */
+  descriptionLimit?: number;
+  /** Text color for the description (default: 'dark') */
+  descriptionColor?: string;
+}

package/src/lib/components/templates/page-wrapper/page-wrapper.component.ts

@@ -0,0 +1,183 @@
+import { CommonModule } from '@angular/common';
+import { Component, computed, EventEmitter, inject, input, OnDestroy, OnInit, Output } from '@angular/core';
+import { NavigationEnd, Router, RouterOutlet } from '@angular/router';
+import { IonContent, ViewWillEnter, ViewWillLeave } from '@ionic/angular/standalone';
+import { filter, Subscription } from 'rxjs';
+import { HeaderComponent } from '../../organisms/header/header.component';
+import { CompanyFooterComponent } from '../../organisms/company-footer/company-footer.component';
+import { ThemeService } from '../../../services/theme.service';
+import { NavigationService } from '../../../services/navigation';
+import { PageWrapperMetadata } from './types';
+import { resolveColor } from '../../../shared/utils/styles';
+
+/**
+ * val-page-wrapper
+ *
+ * A complete page wrapper template with header, router outlet, footer,
+ * and automatic scroll-to-top on navigation.
+ *
+ * @example
+ * <val-page-wrapper
+ *   [props]="{
+ *     homeRoute: '/',
+ *     scrollToTopOnNavigate: true,
+ *     footer: {
+ *       links: { ... },
+ *       rights: { companyName: 'Acme' }
+ *     }
+ *   }"
+ * ></val-page-wrapper>
+ *
+ * @input props - Page wrapper configuration
+ * @output onHeaderClick - Emits when a header action is clicked
+ */
+@Component({
+  selector: 'val-page-wrapper',
+  standalone: true,
+  imports: [CommonModule, HeaderComponent, CompanyFooterComponent, RouterOutlet, IonContent],
+  template: `
+    <div class="ion-page">
+      <val-header
+        [props]="headerProps()"
+        (onClick)="onHeaderClickHandler($event)"
+      />
+      <ion-content
+        [id]="contentId()"
+        [fullscreen]="true"
+        [ngStyle]="{
+          '--background': background()
+        }"
+      >
+        <main>
+          <router-outlet></router-outlet>
+        </main>
+        @if (propsFooter()) {
+          <val-company-footer [props]="propsFooter()" />
+        }
+      </ion-content>
+    </div>
+  `,
+  styles: `
+    main {
+      min-height: 60vh;
+      padding-bottom: var(--val-bottom-nav-height, 0);
+    }
+  `,
+})
+export class PageWrapperComponent implements ViewWillEnter, ViewWillLeave, OnInit, OnDestroy {
+  private theme = inject(ThemeService);
+  private nav = inject(NavigationService);
+  private router = inject(Router);
+  private routerSubscription?: Subscription;
+
+  /**
+   * Page wrapper configuration.
+   * Signal-based input for full reactivity with computed().
+   */
+  readonly props = input<PageWrapperMetadata>({
+    scrollToTopOnNavigate: true,
+  });
+
+  /**
+   * Emits when a header action is clicked.
+   */
+  @Output() onHeaderClick = new EventEmitter<string>();
+
+  /**
+   * Default header configuration (cached to avoid infinite change detection).
+   */
+  private readonly defaultHeader = {
+    bordered: true,
+    translucent: true,
+    toolbar: {
+      withBack: false,
+      withActions: true,
+      textColor: 'dark' as const,
+      withMenu: true,
+      title: '',
+      actions: [
+        {
+          token: 'header-logo',
+          description: '',
+          position: 'left' as const,
+          type: 'IMAGE' as const,
+          image: {
+            width: 10,
+            src: '--main-logo',
+            alt: 'header logo',
+            mode: 'box' as const,
+            shaded: false,
+            bordered: false,
+            size: 'small' as const,
+            limited: false,
+            flex: true,
+          },
+        },
+      ],
+    },
+  };
+
+  // Computed helpers for template bindings
+  headerProps = computed(() => this.props()?.header || this.defaultHeader);
+  contentId = computed(() => this.props()?.contentId || 'page-wrapper');
+  propsFooter = computed(() => this.props()?.footer);
+  background = computed(() => {
+    if (this.theme.IsDark) {
+      return 'var(--ion-background-color)';
+    }
+    const bg = this.props()?.background;
+    if (!bg) {
+      return 'var(--ion-background-color)';
+    }
+    return resolveColor(bg);
+  });
+
+  ngOnInit(): void {
+    if (this.props()?.scrollToTopOnNavigate !== false) {
+      this.routerSubscription = this.router.events
+        .pipe(filter((event) => event instanceof NavigationEnd))
+        .subscribe(() => {
+          this.scrollToTop();
+        });
+    }
+  }
+
+  ngOnDestroy(): void {
+    if (this.routerSubscription) {
+      this.routerSubscription.unsubscribe();
+    }
+  }
+
+  ionViewWillLeave(): void {
+    // Optional: can add logic on view leave
+  }
+
+  ionViewWillEnter(): void {
+    this.scrollToTop();
+  }
+
+  /**
+   * Scrolls the content to the top.
+   */
+  private scrollToTop(): void {
+    const id = this.props()?.contentId || 'page-wrapper';
+    const ionContent = document.querySelector(`#${id}`) as any;
+    if (ionContent && ionContent.scrollToTop) {
+      ionContent.scrollToTop(300);
+    } else {
+      window.scrollTo({ top: 0, behavior: 'smooth' });
+    }
+  }
+
+  /**
+   * Handles header action clicks.
+   */
+  onHeaderClickHandler(token: string): void {
+    this.onHeaderClick.emit(token);
+
+    const homeRoute = this.props()?.homeRoute;
+    if (token === 'header-logo' && homeRoute) {
+      this.nav.navigateByUrl(homeRoute);
+    }
+  }
+}

package/src/lib/components/templates/page-wrapper/page-wrapper.stories.ts

@@ -0,0 +1,149 @@
+import type { Meta, StoryObj } from '@storybook/angular';
+import { moduleMetadata } from '@storybook/angular';
+import { CommonModule } from '@angular/common';
+import { PageWrapperComponent } from './page-wrapper.component';
+import { HeaderComponent } from '../../organisms/header/header.component';
+import { CompanyFooterComponent } from '../../organisms/company-footer/company-footer.component';
+import { RouterOutlet } from '@angular/router';
+import { IonContent } from '@ionic/angular/standalone';
+
+const meta: Meta<PageWrapperComponent> = {
+  title: 'Templates/PageWrapper',
+  component: PageWrapperComponent,
+  decorators: [
+    moduleMetadata({
+      imports: [CommonModule, PageWrapperComponent, HeaderComponent, CompanyFooterComponent, RouterOutlet, IonContent],
+    }),
+  ],
+  tags: ['autodocs'],
+  argTypes: {
+    props: {
+      description: 'Page wrapper configuration object',
+      control: 'object',
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component: `
+## val-page-wrapper
+
+A complete page wrapper template with router outlet and navigation.
+
+### Problem it solves
+
+Single-page applications need a consistent wrapper that:
+- Contains the router outlet for all pages
+- Provides consistent header and footer
+- Handles scroll-to-top on navigation
+- Supports dark mode backgrounds
+- Integrates with Ionic lifecycle hooks
+
+### Usage
+
+In your app.component or main layout:
+
+\`\`\`html
+<val-page-wrapper
+  [props]="{
+    homeRoute: '/',
+    scrollToTopOnNavigate: true,
+    footer: {
+      links: {
+        leftLinks: { title: 'Company', size: 'medium', links: [...] },
+        rightLinks: { title: 'Support', size: 'medium', links: [...] },
+        socialLinks: [...]
+      },
+      rights: { companyName: 'Acme Inc' }
+    }
+  }"
+  (onHeaderClick)="handleHeaderAction($event)"
+></val-page-wrapper>
+\`\`\`
+
+### Features
+
+- Router outlet integration
+- Automatic scroll-to-top on route changes
+- Corporate header with menu toggle
+- Configurable company footer
+- Dark mode background handling
+- Ionic ViewWillEnter/Leave support
+
+### Note
+
+This component requires Angular Router to be configured.
+In Storybook, the router outlet won't display routed content.
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<PageWrapperComponent>;
+
+export const Default: Story = {
+  args: {
+    props: {
+      homeRoute: '/',
+      scrollToTopOnNavigate: true,
+    },
+  },
+};
+
+export const WithFooter: Story = {
+  args: {
+    props: {
+      homeRoute: '/',
+      scrollToTopOnNavigate: true,
+      footer: {
+        links: {
+          leftLinks: {
+            title: 'Company',
+            size: 'medium',
+            links: [
+              { text: 'About', url: '/about', token: 'about', color: 'dark', download: false, hoverable: true },
+              { text: 'Privacy', url: '/privacy', token: 'privacy', color: 'dark', download: false, hoverable: true },
+              { text: 'Terms', url: '/terms', token: 'terms', color: 'dark', download: false, hoverable: true },
+            ],
+          },
+          rightLinks: {
+            title: 'Support',
+            size: 'medium',
+            links: [
+              { text: 'Help', url: '/help', token: 'help', color: 'dark', download: false, hoverable: true },
+              { text: 'FAQ', url: '/faq', token: 'faq', color: 'dark', download: false, hoverable: true },
+              { text: 'Contact', url: '/contact', token: 'contact', color: 'dark', download: false, hoverable: true },
+            ],
+          },
+          socialLinks: [
+            { icon: 'logo-facebook', url: 'https://facebook.com', name: 'Facebook' },
+            { icon: 'logo-twitter', url: 'https://twitter.com', name: 'Twitter' },
+            { icon: 'logo-linkedin', url: 'https://linkedin.com', name: 'LinkedIn' },
+          ],
+        },
+        rights: { companyName: 'Acme Corporation' },
+        withPadding: true,
+      },
+    },
+  },
+};
+
+export const CustomBackground: Story = {
+  args: {
+    props: {
+      homeRoute: '/',
+      background: '#f5f5f5',
+      scrollToTopOnNavigate: true,
+    },
+  },
+};
+
+export const MinimalConfiguration: Story = {
+  args: {
+    props: {
+      homeRoute: '/',
+    },
+  },
+};

package/src/lib/components/templates/page-wrapper/types.ts

@@ -0,0 +1,20 @@
+import { HeaderMetadata } from '../../organisms/header/types';
+import { CompanyFooterMetadata } from '../../organisms/company-footer/types';
+
+/**
+ * Configuration for the page wrapper component.
+ */
+export interface PageWrapperMetadata {
+  /** Header configuration */
+  header?: HeaderMetadata;
+  /** Footer configuration */
+  footer?: CompanyFooterMetadata;
+  /** Background color or CSS variable */
+  background?: string;
+  /** Route to navigate to when header logo is clicked */
+  homeRoute?: string;
+  /** Content ID for scroll handling */
+  contentId?: string;
+  /** Enable scroll-to-top on route change */
+  scrollToTopOnNavigate?: boolean;
+}