valtech-components 2.0.687 → 2.0.689

package/src/lib/components/templates/docs-shell/docs-shell.component.ts

@@ -0,0 +1,494 @@
+import { Component, Input, Output, EventEmitter, inject, signal, computed } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { RouterModule } from '@angular/router';
+import {
+  IonSplitPane,
+  IonMenu,
+  IonHeader,
+  IonToolbar,
+  IonContent,
+  IonIcon,
+  IonMenuButton,
+  IonButtons,
+  MenuController,
+} from '@ionic/angular/standalone';
+import { addIcons } from 'ionicons';
+import {
+  chevronDownOutline,
+  chevronForwardOutline,
+  closeOutline,
+} from 'ionicons/icons';
+import { DocsSearchComponent } from '../../molecules/docs-search/docs-search.component';
+import { DocsSearchMetadata, DocsSearchSection } from '../../molecules/docs-search/types';
+import { CompanyFooterComponent } from '../../organisms/company-footer/company-footer.component';
+import { DocsNavigationService } from '../../../services/docs/docs-navigation.service';
+import { DocsShellMetadata, DocsShellSection } from './types';
+
+addIcons({
+  chevronDownOutline,
+  chevronForwardOutline,
+  closeOutline,
+});
+
+/**
+ * val-docs-shell
+ *
+ * A complete documentation shell with sidebar navigation, search, and content area.
+ * Use this component as the root layout for documentation pages.
+ *
+ * @example
+ * ```html
+ * <val-docs-shell [props]="shellConfig">
+ *   <router-outlet></router-outlet>
+ * </val-docs-shell>
+ * ```
+ */
+@Component({
+  selector: 'val-docs-shell',
+  standalone: true,
+  imports: [
+    CommonModule,
+    RouterModule,
+    IonSplitPane,
+    IonMenu,
+    IonHeader,
+    IonToolbar,
+    IonContent,
+    IonIcon,
+    IonMenuButton,
+    IonButtons,
+    DocsSearchComponent,
+    CompanyFooterComponent,
+  ],
+  template: `
+    <ion-split-pane contentId="docs-content" when="lg">
+      <ion-menu contentId="docs-content" type="overlay" menuId="docs-menu">
+        <ion-header class="ion-no-border">
+          <ion-toolbar>
+            <div class="sidebar-header">
+              <a [routerLink]="props.logo.route || ['/']" class="logo-link" [attr.aria-label]="props.logo.alt">
+                @if (props.logo.cssVariable) {
+                  <span
+                    class="sidebar-logo sidebar-logo--css-var"
+                    role="img"
+                    [attr.aria-label]="props.logo.alt"
+                    [style.--logo-var]="'var(' + props.logo.cssVariable + ')'"
+                    [style.width]="props.logo.width || '10rem'"
+                    [style.height]="props.logo.height || '3rem'"
+                  ></span>
+                } @else if (props.logo.src) {
+                  <img
+                    [src]="props.logo.src"
+                    [alt]="props.logo.alt"
+                    class="sidebar-logo sidebar-logo--img"
+                    [style.width]="props.logo.width || '10rem'"
+                    [style.height]="props.logo.height || '3rem'"
+                  />
+                }
+              </a>
+              <button
+                type="button"
+                class="sidebar-close"
+                (click)="closeMenu()"
+                aria-label="Close menu"
+              >
+                <ion-icon name="close-outline"></ion-icon>
+              </button>
+            </div>
+          </ion-toolbar>
+        </ion-header>
+
+        <ion-content>
+          <!-- Search -->
+          @if (props.search) {
+            <div class="search-wrapper">
+              <val-docs-search
+                [props]="searchProps()"
+                (navigate)="onNavigate($event)"
+              ></val-docs-search>
+            </div>
+          }
+
+          <nav class="sidebar-nav">
+            @for (section of sectionsState(); track section.key) {
+              <div class="nav-section">
+                <button
+                  type="button"
+                  class="nav-section__header"
+                  (click)="toggleSection(section)"
+                >
+                  @if (section.icon) {
+                    <ion-icon [name]="section.icon"></ion-icon>
+                  }
+                  <span>{{ section.title }}</span>
+                  <ion-icon
+                    [name]="section.expanded ? 'chevron-down-outline' : 'chevron-forward-outline'"
+                    class="nav-chevron"
+                  ></ion-icon>
+                </button>
+
+                @if (section.expanded) {
+                  <ul class="nav-links">
+                    @for (link of section.children; track link.label) {
+                      <li>
+                        <a
+                          [routerLink]="link.route"
+                          routerLinkActive="active"
+                          (click)="closeMenu()"
+                        >
+                          {{ link.label }}
+                          @if (link.badge) {
+                            <span
+                              class="nav-badge"
+                              [class.nav-badge--success]="link.badgeColor === 'success'"
+                            >{{ link.badge }}</span>
+                          }
+                        </a>
+                      </li>
+                    }
+                  </ul>
+                }
+              </div>
+            }
+          </nav>
+        </ion-content>
+      </ion-menu>
+
+      <div class="ion-page" id="docs-content">
+        <ion-header class="ion-no-border mobile-header">
+          <ion-toolbar>
+            <ion-buttons slot="start">
+              <a [routerLink]="props.logo.route || ['/']" class="mobile-logo" [attr.aria-label]="props.logo.alt">
+                @if (props.mobileLogo?.cssVariable) {
+                  <span
+                    class="mobile-logo__icon mobile-logo__icon--css-var"
+                    role="img"
+                    [style.--logo-var]="'var(' + props.mobileLogo.cssVariable + ')'"
+                    [style.width]="props.mobileLogo.width || '32px'"
+                    [style.height]="props.mobileLogo.height || '32px'"
+                  ></span>
+                } @else if (props.mobileLogo?.src) {
+                  <img
+                    [src]="props.mobileLogo.src"
+                    [alt]="props.logo.alt"
+                    class="mobile-logo__icon mobile-logo__icon--img"
+                    [style.width]="props.mobileLogo.width || '32px'"
+                    [style.height]="props.mobileLogo.height || '32px'"
+                  />
+                }
+              </a>
+            </ion-buttons>
+            <ion-buttons slot="end">
+              <ion-menu-button menu="docs-menu" color="dark"></ion-menu-button>
+            </ion-buttons>
+          </ion-toolbar>
+        </ion-header>
+
+        <main class="docs-main-scroll">
+          <ng-content></ng-content>
+          @if (props.footer) {
+            <val-company-footer [props]="props.footer"></val-company-footer>
+          }
+        </main>
+      </div>
+    </ion-split-pane>
+  `,
+  styles: [`
+    :host {
+      display: block;
+      height: 100%;
+    }
+
+    ion-split-pane {
+      height: 100%;
+      --side-width: var(--docs-sidebar-width, 260px);
+      --side-min-width: var(--docs-sidebar-width, 260px);
+      --side-max-width: var(--docs-sidebar-width, 260px);
+    }
+
+    .sidebar-header {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 0rem 1rem;
+    }
+
+    .logo-link {
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+      text-decoration: none;
+      transition: opacity 0.2s ease;
+    }
+
+    .logo-link:hover {
+      opacity: 0.8;
+    }
+
+    .sidebar-logo--css-var {
+      display: block;
+      background-image: var(--logo-var);
+      background-size: contain;
+      background-repeat: no-repeat;
+      background-position: left center;
+    }
+
+    .sidebar-logo--img {
+      display: block;
+      object-fit: contain;
+    }
+
+    .sidebar-close {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: 2.5rem;
+      height: 2.5rem;
+      border: none;
+      background: transparent;
+      border-radius: 50%;
+      cursor: pointer;
+      color: var(--ion-text-color, #333);
+      transition: background 0.2s ease;
+    }
+
+    .sidebar-close:hover {
+      background: rgba(0, 0, 0, 0.05);
+    }
+
+    .sidebar-close ion-icon {
+      font-size: 1.5rem;
+    }
+
+    @media (min-width: 992px) {
+      .sidebar-close {
+        display: none;
+      }
+    }
+
+    .search-wrapper {
+      padding: 0.75rem 1rem;
+      border-bottom: 1px solid var(--ion-border-color, #e0e0e0);
+    }
+
+    .sidebar-nav {
+      padding: 0.5rem 0;
+    }
+
+    .nav-section__header {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      width: 100%;
+      padding: 0.75rem 1rem;
+      border: none;
+      background: transparent;
+      font-size: 0.75rem;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+      color: #666;
+      cursor: pointer;
+    }
+
+    .nav-section__header:hover {
+      color: var(--ion-text-color);
+    }
+
+    .nav-section__header span {
+      flex: 1;
+      text-align: left;
+    }
+
+    .nav-chevron {
+      font-size: 0.875rem;
+    }
+
+    .nav-links {
+      list-style: none;
+      margin: 0;
+      padding: 0;
+    }
+
+    .nav-links a {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      padding: 0.5rem 1rem 0.5rem 2.5rem;
+      font-size: 0.875rem;
+      color: #555;
+      text-decoration: none;
+      border-left: 2px solid transparent;
+    }
+
+    .nav-links a:hover {
+      color: var(--ion-text-color);
+      background: rgba(0, 0, 0, 0.03);
+    }
+
+    .nav-links a.active {
+      color: var(--ion-text-color);
+      font-weight: 500;
+      background: rgba(0, 0, 0, 0.05);
+      border-left-color: var(--ion-color-primary);
+    }
+
+    .nav-badge {
+      font-size: 0.625rem;
+      font-weight: 500;
+      text-transform: uppercase;
+      padding: 0.125rem 0.375rem;
+      border-radius: 4px;
+      background: rgba(0, 0, 0, 0.04);
+      color: #888;
+    }
+
+    .nav-badge--success {
+      background: #e8f5e9;
+      color: #2e7d32;
+    }
+
+    .docs-main-scroll {
+      flex: 1;
+      overflow-y: auto;
+      background: var(--ion-background-color);
+    }
+
+    ion-menu {
+      --width: 100%;
+      --max-width: 100%;
+      --background: var(--ion-background-color);
+      border-right: 1px solid var(--ion-border-color, #e0e0e0);
+    }
+
+    /* Mobile logo styles */
+    .mobile-logo {
+      display: flex;
+      align-items: center;
+      padding: 0 0.5rem;
+      text-decoration: none;
+    }
+
+    .mobile-logo__icon {
+      display: block;
+    }
+
+    .mobile-logo__icon--css-var {
+      background-image: var(--logo-var);
+      background-size: contain;
+      background-repeat: no-repeat;
+      background-position: center;
+    }
+
+    .mobile-logo__icon--img {
+      object-fit: contain;
+    }
+
+    @media (min-width: 992px) {
+      ion-menu {
+        --width: var(--docs-sidebar-width, 260px);
+        --max-width: var(--docs-sidebar-width, 260px);
+      }
+
+      .mobile-header {
+        display: none;
+      }
+    }
+
+    #docs-content {
+      display: flex;
+      flex-direction: column;
+    }
+
+    /* Dark mode */
+    :host-context(.dark) .nav-badge,
+    :host-context([color-scheme="dark"]) .nav-badge {
+      background: rgba(255, 255, 255, 0.06);
+      color: #999;
+    }
+
+    :host-context(.dark) .nav-badge--success,
+    :host-context([color-scheme="dark"]) .nav-badge--success {
+      background: rgba(46, 125, 50, 0.2);
+      color: #81c784;
+    }
+
+    :host-context(.dark) .sidebar-close:hover,
+    :host-context([color-scheme="dark"]) .sidebar-close:hover {
+      background: rgba(255, 255, 255, 0.1);
+    }
+  `],
+})
+export class DocsShellComponent {
+  private menuCtrl = inject(MenuController);
+  private docsNav = inject(DocsNavigationService);
+
+  @Input() props: DocsShellMetadata = {
+    logo: { alt: 'Logo' },
+    sections: [],
+  };
+
+  @Output() navigate = new EventEmitter<string[]>();
+
+  // Internal state for expanded sections
+  private _sectionsState = signal<DocsShellSection[]>([]);
+
+  sectionsState = computed(() => {
+    // Initialize from props if empty
+    if (this._sectionsState().length === 0 && this.props.sections.length > 0) {
+      return this.props.sections.map(s => ({
+        ...s,
+        expanded: s.expanded ?? true,
+      }));
+    }
+    return this._sectionsState().length > 0 ? this._sectionsState() : this.props.sections;
+  });
+
+  searchProps = computed<DocsSearchMetadata>(() => ({
+    placeholder: this.props.search?.placeholder || 'Search...',
+    showShortcut: this.props.search?.showShortcut ?? true,
+    sections: this.buildSearchSections(),
+  }));
+
+  ngOnChanges(): void {
+    // Update sections state when props change
+    if (this.props.sections.length > 0) {
+      this._sectionsState.set(
+        this.props.sections.map(s => ({
+          ...s,
+          expanded: s.expanded ?? true,
+        }))
+      );
+    }
+  }
+
+  toggleSection(section: DocsShellSection): void {
+    this._sectionsState.update(sections =>
+      sections.map(s =>
+        s.key === section.key ? { ...s, expanded: !s.expanded } : s
+      )
+    );
+  }
+
+  async closeMenu(): Promise<void> {
+    await this.menuCtrl.close('docs-menu');
+    this.docsNav.scrollToTop();
+  }
+
+  onNavigate(route: string[]): void {
+    this.navigate.emit(route);
+    this.docsNav.navigateAndScroll(route);
+    this.menuCtrl.close('docs-menu');
+  }
+
+  private buildSearchSections(): DocsSearchSection[] {
+    return this.props.sections.map(section => ({
+      title: section.title,
+      items: section.children.map(child => ({
+        label: child.label,
+        route: child.route,
+        description: `${section.title} > ${child.label}`,
+      })),
+    }));
+  }
+}

package/src/lib/components/templates/docs-shell/types.ts

@@ -0,0 +1,176 @@
+import { CompanyFooterMetadata } from '../../organisms/company-footer/types';
+import { LanguageSelectorMetadata } from '../../molecules/language-selector/types';
+
+/**
+ * Configuration for the docs-shell component.
+ */
+export interface DocsShellMetadata {
+  /**
+   * Logo configuration for the sidebar header.
+   */
+  logo: DocsShellLogo;
+
+  /**
+   * Navigation sections for the sidebar.
+   */
+  sections: DocsShellSection[];
+
+  /**
+   * Search configuration.
+   */
+  search?: {
+    /** Placeholder text for the search input */
+    placeholder?: string;
+    /** Show keyboard shortcut hint */
+    showShortcut?: boolean;
+  };
+
+  /**
+   * Mobile logo configuration.
+   * Used in the mobile header toolbar.
+   */
+  mobileLogo?: {
+    /**
+     * CSS variable for the logo (recommended for dark mode support).
+     * @example '--main-logo-mini'
+     */
+    cssVariable?: string;
+    /**
+     * Logo image source (alternative to cssVariable).
+     */
+    src?: string;
+    /**
+     * Logo width.
+     * @default '32px'
+     */
+    width?: string;
+    /**
+     * Logo height.
+     * @default '32px'
+     */
+    height?: string;
+  };
+
+  /**
+   * Footer configuration.
+   */
+  footer?: CompanyFooterMetadata;
+
+  /**
+   * Sidebar width in desktop mode.
+   * @default '260px'
+   */
+  sidebarWidth?: string;
+
+  /**
+   * Language selector configuration for the footer.
+   */
+  languageSelector?: LanguageSelectorMetadata;
+
+  /**
+   * Custom CSS class for the shell.
+   */
+  cssClass?: string;
+}
+
+/**
+ * Logo configuration for the docs shell.
+ */
+export interface DocsShellLogo {
+  /**
+   * Use CSS variable for the logo (recommended for dark mode support).
+   * When set, uses background-image with this CSS variable.
+   * @example '--main-logo'
+   */
+  cssVariable?: string;
+
+  /**
+   * Logo image source (alternative to cssVariable).
+   */
+  src?: string;
+
+  /**
+   * Dark mode logo source (used with src).
+   */
+  srcDark?: string;
+
+  /**
+   * Alt text for accessibility.
+   */
+  alt: string;
+
+  /**
+   * Route to navigate when clicking the logo.
+   * @default ['/']
+   */
+  route?: string[];
+
+  /**
+   * Logo width.
+   * @default '10rem'
+   */
+  width?: string;
+
+  /**
+   * Logo height.
+   * @default '3rem'
+   */
+  height?: string;
+}
+
+/**
+ * A navigation section in the sidebar.
+ */
+export interface DocsShellSection {
+  /**
+   * Unique key for the section.
+   */
+  key: string;
+
+  /**
+   * Display title for the section header.
+   */
+  title: string;
+
+  /**
+   * Icon name (ionicons).
+   */
+  icon?: string;
+
+  /**
+   * Whether the section is expanded by default.
+   * @default true
+   */
+  expanded?: boolean;
+
+  /**
+   * Child navigation links.
+   */
+  children: DocsShellLink[];
+}
+
+/**
+ * A navigation link in the sidebar.
+ */
+export interface DocsShellLink {
+  /**
+   * Display label for the link.
+   */
+  label: string;
+
+  /**
+   * Route array for navigation.
+   */
+  route: string[];
+
+  /**
+   * Optional badge text (e.g., "New", "Updated").
+   */
+  badge?: string;
+
+  /**
+   * Badge color variant.
+   * @default 'default'
+   */
+  badgeColor?: 'default' | 'success';
+}

package/src/lib/components/templates/layout/layout.component.scss

@@ -0,0 +1,25 @@
+@import '../../styles/mixins.scss';
+
+.layout-container {
+  margin: 0 auto;
+  padding: 0;
+  width: 100%;
+  box-sizing: border-box;
+  margin-bottom: pxToRem(16);
+  padding-top: pxToRem(8);
+
+  @include max-media-medium {
+    max-width: 100%;
+  }
+
+  @include media-medium {
+    margin: 0 auto;
+    max-width: pxToRem($container-max-small);
+    margin-bottom: pxToRem(24);
+  }
+
+  @include media-xlarge {
+    margin: 0 auto;
+    max-width: pxToRem($container-max-medium);
+  }
+}

package/src/lib/components/templates/layout/layout.component.ts

@@ -0,0 +1,14 @@
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'val-layout',
+  standalone: true,
+  imports: [],
+  template: `
+    <div class="layout-container">
+      <ng-content></ng-content>
+    </div>
+  `,
+  styleUrl: './layout.component.scss',
+})
+export class LayoutComponent {}

package/src/lib/components/templates/maintenance-page/index.ts

@@ -0,0 +1,2 @@
+export { MaintenancePageComponent } from './maintenance-page.component';
+export { MaintenancePageMetadata } from './types';