valtech-components 2.0.787 → 2.0.795

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

@@ -0,0 +1,566 @@
+/**
+ * PAGE COMPOSITION GUIDE
+ * ----------------------
+ * This file is a visual reference for developers building full pages with valtech-components.
+ *
+ * Instead of looking at isolated atoms/molecules, here you can see how the top-level
+ * building blocks (header, menu, footer, auth-background) are assembled into real
+ * application layouts.
+ *
+ * Three canonical layouts are covered:
+ *
+ *  - AppShell       → The main authenticated app shell: header + side menu + routed content + footer.
+ *                     Use this as the outer wrapper of your entire app (app.component.html).
+ *
+ *  - MinimalPage    → A lightweight public-facing layout: header + content + footer, no side menu.
+ *                     Use this for marketing/informational pages or secondary app sections.
+ *
+ *  - AuthPage       → A full-screen auth layout with animated background.
+ *                     Use this for login, sign-up, forgot-password and similar pages.
+ */
+
+import type { Meta, StoryObj } from '@storybook/angular';
+import { applicationConfig, moduleMetadata } from '@storybook/angular';
+import { CommonModule } from '@angular/common';
+import { provideRouter } from '@angular/router';
+import {
+  IonAccordion,
+  IonAccordionGroup,
+  IonButton,
+  IonButtons,
+  IonContent,
+  IonHeader,
+  IonIcon,
+  IonItem,
+  IonLabel,
+  IonList,
+  IonMenu,
+  IonMenuToggle,
+  IonToolbar,
+} from '@ionic/angular/standalone';
+
+import { PageWrapperComponent } from './page-wrapper.component';
+import { HeaderComponent } from '../../organisms/header/header.component';
+import { MenuComponent } from '../../organisms/menu/menu.component';
+import { CompanyFooterComponent } from '../../organisms/company-footer/company-footer.component';
+import { LinksAccordionComponent } from '../../molecules/links-accordion/links-accordion.component';
+import { AuthBackgroundComponent } from '../auth-background/auth-background.component';
+
+// ---------------------------------------------------------------------------
+// Shared fixture data used across stories
+// ---------------------------------------------------------------------------
+
+const FOOTER_PROPS = {
+  links: {
+    leftLinks: {
+      title: 'Company',
+      size: 'medium' as const,
+      links: [
+        {
+          text: 'About',
+          url: '/about',
+          token: 'about',
+          color: 'dark' as const,
+          download: false,
+          hoverable: true,
+        },
+        {
+          text: 'Privacy',
+          url: '/privacy',
+          token: 'privacy',
+          color: 'dark' as const,
+          download: false,
+          hoverable: true,
+        },
+        {
+          text: 'Terms',
+          url: '/terms',
+          token: 'terms',
+          color: 'dark' as const,
+          download: false,
+          hoverable: true,
+        },
+      ],
+    },
+    rightLinks: {
+      title: 'Support',
+      size: 'medium' as const,
+      links: [
+        {
+          text: 'Help Center',
+          url: '/help',
+          token: 'help',
+          color: 'dark' as const,
+          download: false,
+          hoverable: true,
+        },
+        {
+          text: 'FAQ',
+          url: '/faq',
+          token: 'faq',
+          color: 'dark' as const,
+          download: false,
+          hoverable: true,
+        },
+        {
+          text: 'Contact Us',
+          url: '/contact',
+          token: 'contact',
+          color: 'dark' as const,
+          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,
+  withBackground: true,
+};
+
+const MENU_SECTIONS = {
+  sections: [
+    { title: 'Dashboard', route: ['/dashboard'] },
+    {
+      title: 'Products',
+      links: [
+        { text: 'All Products', route: ['/products'] },
+        { text: 'New Arrivals', route: ['/products', 'new'] },
+        { text: 'Categories', route: ['/products', 'categories'] },
+      ],
+    },
+    {
+      title: 'Orders',
+      links: [
+        { text: 'My Orders', route: ['/orders'] },
+        { text: 'Returns', route: ['/orders', 'returns'] },
+      ],
+    },
+    { title: 'Profile', route: ['/profile'] },
+    { title: 'Settings', route: ['/settings'] },
+  ],
+  closeMenuOnClick: true,
+  closeAccordionOnClick: true,
+};
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta: Meta = {
+  title: 'Templates/PageComposition',
+  decorators: [
+    applicationConfig({
+      // provideRouter([]) satisfies any RouterOutlet or Router injection
+      // inside child components without requiring real routes.
+      providers: [provideRouter([])],
+    }),
+    moduleMetadata({
+      imports: [
+        CommonModule,
+        PageWrapperComponent,
+        HeaderComponent,
+        MenuComponent,
+        CompanyFooterComponent,
+        LinksAccordionComponent,
+        AuthBackgroundComponent,
+        // Ionic standalone components needed by menu/header
+        IonMenu,
+        IonButtons,
+        IonMenuToggle,
+        IonButton,
+        IonIcon,
+        IonHeader,
+        IonToolbar,
+        IonContent,
+        IonItem,
+        IonLabel,
+        IonList,
+        IonAccordionGroup,
+        IonAccordion,
+      ],
+    }),
+  ],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: `
+## Page Composition Guide
+
+This section shows developers how to assemble complete page layouts using
+\`valtech-components\` building blocks.
+
+### When to use each layout
+
+| Layout | Use case |
+|--------|----------|
+| **AppShell** | Authenticated area — wraps the whole app with header, side menu and footer |
+| **MinimalPage** | Public/marketing pages or lightweight secondary sections — no side menu |
+| **AuthPage** | Login, sign-up, forgot-password — full-screen animated background |
+
+### Storybook limitations
+
+- \`<router-outlet>\` is active but renders nothing since no routes are registered.
+  In a real app the main page content would appear inside it.
+- The Ionic side menu requires the full Ionic app context to slide open/close.
+  In real usage, open it with \`MenuController.open('main-menu')\` or \`IonMenuButton\`.
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+// ---------------------------------------------------------------------------
+// Story 1 — AppShell
+// Use this as the outer wrapper in your app.component.html.
+// val-page-wrapper already bundles the header and footer; val-menu sits alongside it.
+// ---------------------------------------------------------------------------
+
+export const AppShell: Story = {
+  name: 'AppShell — Full authenticated layout',
+  parameters: {
+    docs: {
+      description: {
+        story: `
+**When to use:** This is the main application shell for authenticated users.
+Place it in \`app.component.html\`. The router outlet renders individual pages
+inside the content area.
+
+\`\`\`html
+<!-- app.component.html -->
+<val-menu
+  [props]="{ id: 'main-menu', contentId: 'page-wrapper', side: 'start', type: 'overlay', swipe: true, showCloseButton: true }"
+>
+  <val-links-accordion [props]="menuSections" (navigate)="onNavigate($event)" />
+</val-menu>
+
+<val-page-wrapper
+  [props]="pageWrapperProps"
+  (onHeaderClick)="handleHeaderAction($event)"
+/>
+\`\`\`
+        `,
+      },
+    },
+  },
+  render: () => ({
+    props: {
+      menuProps: {
+        id: 'main-menu',
+        contentId: 'page-wrapper',
+        side: 'start',
+        type: 'overlay',
+        swipe: true,
+        showCloseButton: true,
+        closeButtonText: 'Close Menu',
+      },
+      menuSections: MENU_SECTIONS,
+      pageWrapperProps: {
+        homeRoute: '/',
+        scrollToTopOnNavigate: true,
+        footer: FOOTER_PROPS,
+      },
+    },
+    template: `
+      <!--
+        AppShell layout:
+        val-menu + val-page-wrapper sit as siblings.
+        The menu's contentId must match val-page-wrapper's default contentId ("page-wrapper").
+      -->
+      <div style="position: relative; min-height: 100vh; display: flex; flex-direction: column;">
+
+        <!-- Side navigation menu -->
+        <val-menu [props]="menuProps">
+          <val-links-accordion [props]="menuSections"></val-links-accordion>
+        </val-menu>
+
+        <!-- Main page shell: header → router-outlet → footer -->
+        <val-page-wrapper [props]="pageWrapperProps">
+        </val-page-wrapper>
+
+        <!-- Simulated page content (replaces what router-outlet would render) -->
+        <div style="
+          padding: 32px 24px;
+          max-width: 900px;
+          margin: 0 auto;
+          width: 100%;
+          font-family: system-ui, sans-serif;
+        ">
+          <h2 style="margin: 0 0 8px; font-size: 1.5rem; color: var(--ion-color-dark, #1a1a2e);">
+            Dashboard
+          </h2>
+          <p style="color: var(--ion-color-medium, #666); margin: 0 0 24px;">
+            This area is rendered by your routed page component via
+            <code>&lt;router-outlet&gt;</code>.
+          </p>
+
+          <div style="display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 16px;">
+            <div style="background: var(--ion-color-light, #f4f5f8); border-radius: 12px; padding: 20px;">
+              <div style="font-size: 2rem; font-weight: 700; color: var(--ion-color-primary, #3880ff);">142</div>
+              <div style="color: var(--ion-color-medium, #666); font-size: .875rem; margin-top: 4px;">Total Orders</div>
+            </div>
+            <div style="background: var(--ion-color-light, #f4f5f8); border-radius: 12px; padding: 20px;">
+              <div style="font-size: 2rem; font-weight: 700; color: var(--ion-color-success, #2dd36f);">$8,430</div>
+              <div style="color: var(--ion-color-medium, #666); font-size: .875rem; margin-top: 4px;">Revenue</div>
+            </div>
+            <div style="background: var(--ion-color-light, #f4f5f8); border-radius: 12px; padding: 20px;">
+              <div style="font-size: 2rem; font-weight: 700; color: var(--ion-color-warning, #ffc409);">7</div>
+              <div style="color: var(--ion-color-medium, #666); font-size: .875rem; margin-top: 4px;">Pending</div>
+            </div>
+          </div>
+        </div>
+
+      </div>
+    `,
+  }),
+};
+
+// ---------------------------------------------------------------------------
+// Story 2 — MinimalPage
+// Header + content + footer only. No side menu. Good for public pages.
+// ---------------------------------------------------------------------------
+
+export const MinimalPage: Story = {
+  name: 'MinimalPage — Header + content + footer',
+  parameters: {
+    docs: {
+      description: {
+        story: `
+**When to use:** Public-facing pages, marketing sections, or any page where a side
+menu is unnecessary. Uses \`val-page-wrapper\` without configuring a menu.
+
+\`\`\`html
+<!-- No val-menu sibling needed -->
+<val-page-wrapper
+  [props]="{
+    homeRoute: '/',
+    header: { bordered: true, translucent: false, toolbar: { title: 'MyApp', withBack: false, withActions: false, actions: [] } },
+    footer: footerProps
+  }"
+/>
+\`\`\`
+        `,
+      },
+    },
+  },
+  render: () => ({
+    props: {
+      pageWrapperProps: {
+        homeRoute: '/',
+        scrollToTopOnNavigate: false,
+        header: {
+          bordered: true,
+          translucent: false,
+          toolbar: {
+            title: 'MyApp',
+            withBack: false,
+            withActions: false,
+            withMenu: false,
+            actions: [],
+          },
+        },
+        footer: FOOTER_PROPS,
+      },
+    },
+    template: `
+      <!--
+        MinimalPage layout:
+        Just val-page-wrapper — no menu. Ideal for public/marketing pages.
+      -->
+      <div style="min-height: 100vh; display: flex; flex-direction: column; font-family: system-ui, sans-serif;">
+
+        <val-page-wrapper [props]="pageWrapperProps">
+        </val-page-wrapper>
+
+        <!-- Simulated page content -->
+        <div style="flex: 1; padding: 64px 24px; max-width: 760px; margin: 0 auto; width: 100%; text-align: center;">
+          <h1 style="font-size: 2.25rem; font-weight: 700; margin: 0 0 16px; color: var(--ion-color-dark, #1a1a2e);">
+            Welcome to MyApp
+          </h1>
+          <p style="font-size: 1.125rem; color: var(--ion-color-medium, #666); line-height: 1.7; margin: 0 0 32px;">
+            A minimal public-facing page with header and footer only.
+            No side menu clutters the experience for anonymous visitors.
+          </p>
+          <div style="display: inline-block; background: var(--ion-color-primary, #3880ff); color: white; border-radius: 8px; padding: 12px 28px; font-weight: 600; font-size: 1rem; cursor: pointer;">
+            Get Started
+          </div>
+        </div>
+
+      </div>
+    `,
+  }),
+};
+
+// ---------------------------------------------------------------------------
+// Story 3 — AuthPage
+// Full-screen animated background for login/sign-up pages.
+// No header or footer — auth pages are self-contained.
+// ---------------------------------------------------------------------------
+
+export const AuthPage: Story = {
+  name: 'AuthPage — Login / Sign-up layout',
+  parameters: {
+    docs: {
+      description: {
+        story: `
+**When to use:** Login, sign-up, forgot-password, or any full-screen authentication
+flow. Uses \`val-auth-background\` which provides animated waves, grain texture and
+glassmorphism. Place your form component inside it via content projection.
+
+\`\`\`html
+<!-- login.page.html -->
+<val-auth-background [props]="{ waveCount: 35, showGrain: true, showGlass: true }">
+  <div class="auth-card">
+    <val-login [props]="loginProps" (onSubmit)="handleLogin($event)" />
+  </div>
+</val-auth-background>
+\`\`\`
+
+> No \`val-header\` or \`val-company-footer\` here — auth pages are intentionally
+> distraction-free. Add back/close navigation inside your card component if needed.
+        `,
+      },
+    },
+  },
+  render: () => ({
+    props: {
+      authBgProps: {
+        waveCount: 35,
+        showGrain: true,
+        showGlass: true,
+        minHeight: '100vh',
+      },
+    },
+    template: `
+      <!--
+        AuthPage layout:
+        val-auth-background wraps the entire viewport.
+        Project your login/sign-up card as content.
+        No header or footer — auth flows are self-contained.
+      -->
+      <val-auth-background [props]="authBgProps">
+
+        <div style="
+          width: 100%;
+          min-height: 100vh;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          padding: 24px;
+          box-sizing: border-box;
+        ">
+
+          <!-- Auth card — replace with your val-login / val-register component -->
+          <div style="
+            background: rgba(255, 255, 255, 0.85);
+            backdrop-filter: blur(16px);
+            -webkit-backdrop-filter: blur(16px);
+            border: 1px solid rgba(255, 255, 255, 0.6);
+            border-radius: 20px;
+            padding: 40px 36px;
+            width: 100%;
+            max-width: 400px;
+            box-shadow: 0 8px 32px rgba(0, 0, 0, 0.08);
+            font-family: system-ui, sans-serif;
+          ">
+            <!-- Logo placeholder -->
+            <div style="text-align: center; margin-bottom: 28px;">
+              <div style="
+                display: inline-flex;
+                align-items: center;
+                justify-content: center;
+                width: 56px;
+                height: 56px;
+                background: var(--ion-color-primary, #3880ff);
+                border-radius: 14px;
+                margin-bottom: 16px;
+              ">
+                <span style="color: white; font-size: 1.5rem; font-weight: 700;">M</span>
+              </div>
+              <h2 style="margin: 0; font-size: 1.375rem; font-weight: 700; color: #1a1a2e;">
+                Sign in to MyApp
+              </h2>
+              <p style="margin: 6px 0 0; font-size: .875rem; color: #666;">
+                Enter your credentials to continue
+              </p>
+            </div>
+
+            <!-- Form fields (simulated) -->
+            <div style="margin-bottom: 16px;">
+              <label style="display: block; font-size: .8125rem; font-weight: 600; color: #444; margin-bottom: 6px;">
+                Email
+              </label>
+              <input
+                type="email"
+                placeholder="you@example.com"
+                style="
+                  width: 100%;
+                  padding: 10px 14px;
+                  border: 1.5px solid #e0e0e0;
+                  border-radius: 8px;
+                  font-size: .9375rem;
+                  outline: none;
+                  box-sizing: border-box;
+                  background: rgba(255,255,255,0.9);
+                "
+              />
+            </div>
+
+            <div style="margin-bottom: 24px;">
+              <label style="display: block; font-size: .8125rem; font-weight: 600; color: #444; margin-bottom: 6px;">
+                Password
+              </label>
+              <input
+                type="password"
+                placeholder="••••••••"
+                style="
+                  width: 100%;
+                  padding: 10px 14px;
+                  border: 1.5px solid #e0e0e0;
+                  border-radius: 8px;
+                  font-size: .9375rem;
+                  outline: none;
+                  box-sizing: border-box;
+                  background: rgba(255,255,255,0.9);
+                "
+              />
+            </div>
+
+            <button style="
+              width: 100%;
+              padding: 12px;
+              background: var(--ion-color-primary, #3880ff);
+              color: white;
+              border: none;
+              border-radius: 10px;
+              font-size: 1rem;
+              font-weight: 600;
+              cursor: pointer;
+              margin-bottom: 16px;
+            ">
+              Sign In
+            </button>
+
+            <p style="text-align: center; font-size: .8125rem; color: #888; margin: 0;">
+              Don't have an account?
+              <a href="#" style="color: var(--ion-color-primary, #3880ff); font-weight: 600; text-decoration: none;">
+                Sign up
+              </a>
+            </p>
+          </div>
+
+        </div>
+
+      </val-auth-background>
+    `,
+  }),
+};