valtech-components 2.0.687 → 2.0.689

package/src/lib/components/organisms/docs-sidebar/types.ts

@@ -0,0 +1,112 @@
+/**
+ * Configuration for the docs-sidebar component.
+ */
+export interface DocsSidebarMetadata {
+  /**
+   * Navigation sections to display.
+   */
+  sections: DocsSidebarSection[];
+
+  /**
+   * Currently active route for highlighting.
+   */
+  activeRoute?: string[];
+
+  /**
+   * Logo configuration for the sidebar header.
+   */
+  logo?: DocsSidebarLogo;
+
+  /**
+   * Custom CSS class.
+   */
+  cssClass?: string;
+
+  /**
+   * Background color override.
+   */
+  backgroundColor?: string;
+}
+
+export interface DocsSidebarLogo {
+  /**
+   * Logo image source.
+   */
+  src: string;
+
+  /**
+   * Alt text for accessibility.
+   */
+  alt: string;
+
+  /**
+   * Optional title/text next to logo.
+   */
+  title?: string;
+
+  /**
+   * Route to navigate when logo is clicked.
+   */
+  route?: string[];
+
+  /**
+   * Logo height (width auto-calculated).
+   * @default '32px'
+   */
+  height?: string;
+}
+
+export interface DocsSidebarSection {
+  /**
+   * Section title displayed in the sidebar.
+   */
+  title: string;
+
+  /**
+   * Route for direct navigation (if no children).
+   */
+  route?: string[];
+
+  /**
+   * Child links under this section.
+   */
+  children?: DocsSidebarLink[];
+
+  /**
+   * Whether the section is expanded by default.
+   * @default false
+   */
+  expanded?: boolean;
+
+  /**
+   * Optional icon name (Ionicons).
+   */
+  icon?: string;
+
+  /**
+   * Badge text (e.g., "New", "Beta").
+   */
+  badge?: string;
+}
+
+export interface DocsSidebarLink {
+  /**
+   * Link display text.
+   */
+  label: string;
+
+  /**
+   * Route to navigate to.
+   */
+  route: string[];
+
+  /**
+   * Badge text (e.g., "New", "Deprecated").
+   */
+  badge?: string;
+
+  /**
+   * Badge color variant.
+   */
+  badgeColor?: 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
+}

package/src/lib/components/organisms/docs-toc/docs-toc.component.scss

@@ -0,0 +1,119 @@
+.docs-toc {
+  --toc-text-color: var(--ion-color-medium, #666);
+  --toc-active-color: #1a1a1a;
+  --toc-hover-color: var(--ion-text-color, #1a1a1a);
+  --toc-border-color: var(--ion-border-color, #e0e0e0);
+
+  font-family: var(--ion-font-family, system-ui, sans-serif);
+
+  // ==========================================================================
+  // Title
+  // ==========================================================================
+  &__title {
+    font-size: 0.6875rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 1px;
+    color: var(--toc-text-color);
+    margin: 0 0 1rem 0;
+  }
+
+  // ==========================================================================
+  // List
+  // ==========================================================================
+  &__list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    border-left: 1px solid var(--toc-border-color);
+  }
+
+  // ==========================================================================
+  // Item
+  // ==========================================================================
+  &__item {
+    position: relative;
+    margin: 0;
+
+    // Active indicator
+    &::before {
+      content: '';
+      position: absolute;
+      left: -1px;
+      top: 0;
+      bottom: 0;
+      width: 2px;
+      background: transparent;
+      transition: background 0.2s ease;
+    }
+
+    &--active {
+      &::before {
+        background: var(--toc-active-color);
+      }
+
+      .docs-toc__link {
+        color: var(--toc-active-color);
+        font-weight: 500;
+      }
+    }
+
+    // Indentation levels
+    &--level-1 {
+      .docs-toc__link {
+        padding-left: 0.75rem;
+      }
+    }
+
+    &--level-2 {
+      .docs-toc__link {
+        padding-left: 1.5rem;
+        font-size: 0.75rem;
+      }
+    }
+
+    &--level-3 {
+      .docs-toc__link {
+        padding-left: 2.25rem;
+        font-size: 0.6875rem;
+      }
+    }
+  }
+
+  // ==========================================================================
+  // Link
+  // ==========================================================================
+  &__link {
+    display: block;
+    padding: 0.375rem 0.75rem;
+    font-size: 0.8125rem;
+    line-height: 1.4;
+    color: var(--toc-text-color);
+    text-decoration: none;
+    transition: color 0.15s ease;
+    word-break: break-word;
+    border-radius: 4px;
+
+    &:hover {
+      color: var(--toc-hover-color);
+    }
+
+    &:focus-visible {
+      outline: 2px solid var(--toc-active-color);
+      outline-offset: 2px;
+    }
+  }
+}
+
+// ==========================================================================
+// Dark Mode Support
+// ==========================================================================
+:host-context(.dark),
+:host-context([color-scheme='dark']) {
+  .docs-toc {
+    --toc-text-color: #a0a0a0;
+    --toc-active-color: #f4f5f8;
+    --toc-hover-color: #f4f5f8;
+    --toc-border-color: #3a3a3a;
+  }
+}

package/src/lib/components/organisms/docs-toc/docs-toc.component.ts

@@ -0,0 +1,320 @@
+import { CommonModule } from '@angular/common';
+import {
+  Component,
+  Input,
+  Output,
+  EventEmitter,
+  OnInit,
+  OnDestroy,
+  OnChanges,
+  SimpleChanges,
+  AfterViewInit,
+  NgZone,
+  signal,
+} from '@angular/core';
+import { DocsTocMetadata, DocsTocItem } from './types';
+
+/**
+ * val-docs-toc
+ *
+ * A table of contents component with scroll spy functionality.
+ * Automatically highlights the current section based on scroll position.
+ *
+ * @example Manual items
+ * ```html
+ * <val-docs-toc
+ *   [props]="{
+ *     title: 'On this page',
+ *     items: [
+ *       { id: 'overview', label: 'Overview', level: 1 },
+ *       { id: 'installation', label: 'Installation', level: 1 },
+ *       { id: 'npm', label: 'Using npm', level: 2 },
+ *       { id: 'yarn', label: 'Using yarn', level: 2 }
+ *     ]
+ *   }"
+ * ></val-docs-toc>
+ * ```
+ *
+ * @example Auto-generated from headings
+ * ```html
+ * <val-docs-toc
+ *   [props]="{
+ *     autoGenerate: true,
+ *     containerSelector: '.article-content',
+ *     headingLevels: [2, 3]
+ *   }"
+ * ></val-docs-toc>
+ * ```
+ */
+@Component({
+  selector: 'val-docs-toc',
+  standalone: true,
+  imports: [CommonModule],
+  template: `
+    <nav
+      class="docs-toc"
+      [class]="props.cssClass"
+      role="navigation"
+      aria-label="Table of contents"
+    >
+      @if (!props.hideTitle) {
+        <h4 class="docs-toc__title">{{ props.title || 'Contents' }}</h4>
+      }
+
+      <ul class="docs-toc__list">
+        @for (item of flatItems(); track item.id) {
+          <li
+            class="docs-toc__item"
+            [class.docs-toc__item--level-1]="item.level === 1"
+            [class.docs-toc__item--level-2]="item.level === 2"
+            [class.docs-toc__item--level-3]="item.level === 3"
+            [class.docs-toc__item--active]="activeId() === item.id"
+          >
+            <a
+              class="docs-toc__link"
+              [href]="'#' + item.id"
+              [attr.aria-current]="activeId() === item.id ? 'location' : null"
+              (click)="scrollToSection($event, item.id)"
+            >
+              {{ item.label }}
+            </a>
+          </li>
+        }
+      </ul>
+    </nav>
+  `,
+  styleUrls: ['./docs-toc.component.scss'],
+})
+export class DocsTocComponent implements OnInit, OnDestroy, OnChanges, AfterViewInit {
+  @Input() props: DocsTocMetadata = {};
+
+  @Output() sectionChange = new EventEmitter<string>();
+
+  // Reactive state
+  protected activeId = signal<string>('');
+  protected flatItems = signal<DocsTocItem[]>([]);
+
+  private headingElements: HTMLElement[] = [];
+  private scrollHandler: (() => void) | null = null;
+  private rafId: number | null = null;
+
+  constructor(private ngZone: NgZone) {}
+
+  ngOnInit(): void {
+    this.updateFlatItems();
+  }
+
+  ngAfterViewInit(): void {
+    // Delay to ensure DOM is ready
+    setTimeout(() => {
+      if (this.props.autoGenerate) {
+        this.generateTocFromHeadings();
+      }
+      this.setupScrollSpy();
+    }, 100);
+  }
+
+  ngOnChanges(changes: SimpleChanges): void {
+    if (changes['props']) {
+      this.updateFlatItems();
+      if (this.props.autoGenerate) {
+        setTimeout(() => this.generateTocFromHeadings(), 100);
+      }
+    }
+  }
+
+  ngOnDestroy(): void {
+    this.destroyScrollSpy();
+  }
+
+  private updateFlatItems(): void {
+    if (this.props.items) {
+      this.flatItems.set(this.flattenItems(this.props.items));
+    }
+  }
+
+  private flattenItems(items: DocsTocItem[]): DocsTocItem[] {
+    const result: DocsTocItem[] = [];
+    const flatten = (itemList: DocsTocItem[]) => {
+      itemList.forEach(item => {
+        result.push(item);
+        if (item.children?.length) {
+          flatten(item.children);
+        }
+      });
+    };
+    flatten(items);
+    return result;
+  }
+
+  private generateTocFromHeadings(): void {
+    const selector = this.props.containerSelector || '.docs-layout__content';
+    const container = document.querySelector(selector);
+
+    if (!container) {
+      console.warn(`[docs-toc] Container not found: ${selector}`);
+      return;
+    }
+
+    const levels = this.props.headingLevels || [2, 3];
+    const headingSelector = levels.map(l => `h${l}`).join(', ');
+    const headings = container.querySelectorAll(headingSelector);
+
+    const items: DocsTocItem[] = [];
+    headings.forEach((heading: Element) => {
+      const el = heading as HTMLElement;
+      // Generate ID if not present
+      if (!el.id) {
+        el.id = this.generateId(el.textContent || '');
+      }
+
+      const level = parseInt(el.tagName[1], 10);
+      items.push({
+        id: el.id,
+        label: el.textContent?.trim() || '',
+        level: level - 1, // h2 = level 1, h3 = level 2
+      });
+    });
+
+    this.flatItems.set(items);
+    // Re-setup scroll spy with new items
+    this.setupScrollSpy();
+  }
+
+  private generateId(text: string): string {
+    return text
+      .toLowerCase()
+      .trim()
+      .replace(/[^\w\s-]/g, '')
+      .replace(/\s+/g, '-')
+      .substring(0, 50);
+  }
+
+  private scrollContainer: HTMLElement | Window | null = null;
+
+  private setupScrollSpy(): void {
+    this.destroyScrollSpy();
+
+    const items = this.flatItems();
+    if (items.length === 0) return;
+
+    // Collect heading elements
+    this.headingElements = items
+      .map(item => document.getElementById(item.id))
+      .filter((el): el is HTMLElement => el !== null);
+
+    if (this.headingElements.length === 0) {
+      console.warn('[docs-toc] No heading elements found for IDs:', items.map(i => i.id));
+      return;
+    }
+
+    // Find the scroll container - check for ion-content first, then use window
+    this.scrollContainer = this.findScrollContainer();
+
+    // Set initial active item
+    this.updateActiveHeading();
+
+    // Use scroll event with requestAnimationFrame for performance
+    this.ngZone.runOutsideAngular(() => {
+      this.scrollHandler = () => {
+        if (this.rafId) {
+          cancelAnimationFrame(this.rafId);
+        }
+        this.rafId = requestAnimationFrame(() => {
+          this.updateActiveHeading();
+        });
+      };
+
+      // Listen on both window and the scroll container for maximum compatibility
+      window.addEventListener('scroll', this.scrollHandler, { passive: true });
+      document.addEventListener('scroll', this.scrollHandler, { passive: true, capture: true });
+
+      // Also listen on ion-content if present
+      const ionContent = document.querySelector('ion-content');
+      if (ionContent) {
+        ionContent.addEventListener('ionScroll', this.scrollHandler as EventListener, { passive: true });
+      }
+    });
+  }
+
+  private findScrollContainer(): HTMLElement | Window {
+    // Check for ion-content's scroll element
+    const ionContent = document.querySelector('ion-content');
+    if (ionContent) {
+      // ion-content has a shadow DOM with the actual scrollable element
+      const scrollEl = (ionContent as any).shadowRoot?.querySelector('.inner-scroll');
+      if (scrollEl) return scrollEl;
+    }
+    return window;
+  }
+
+  private updateActiveHeading(): void {
+    const offsetTop = this.props.offsetTop ?? 100;
+
+    // Find the heading closest to or above the trigger point (offset from top of viewport)
+    // Using getBoundingClientRect().top which is relative to viewport - works regardless of scroll container
+    let activeHeading: HTMLElement | null = null;
+
+    for (const heading of this.headingElements) {
+      const rect = heading.getBoundingClientRect();
+
+      // If heading's top is at or above the trigger point (offset pixels from viewport top)
+      if (rect.top <= offsetTop + 10) {
+        activeHeading = heading;
+      } else {
+        // Since headings are in DOM order, stop once we find one below the trigger
+        break;
+      }
+    }
+
+    // If no heading is above the trigger point, use the first one
+    if (!activeHeading && this.headingElements.length > 0) {
+      activeHeading = this.headingElements[0];
+    }
+
+    if (activeHeading && activeHeading.id !== this.activeId()) {
+      this.ngZone.run(() => {
+        this.activeId.set(activeHeading!.id);
+        this.sectionChange.emit(activeHeading!.id);
+      });
+    }
+  }
+
+  private destroyScrollSpy(): void {
+    if (this.scrollHandler) {
+      window.removeEventListener('scroll', this.scrollHandler);
+      document.removeEventListener('scroll', this.scrollHandler, { capture: true } as EventListenerOptions);
+
+      const ionContent = document.querySelector('ion-content');
+      if (ionContent) {
+        ionContent.removeEventListener('ionScroll', this.scrollHandler as EventListener);
+      }
+
+      this.scrollHandler = null;
+    }
+    if (this.rafId) {
+      cancelAnimationFrame(this.rafId);
+      this.rafId = null;
+    }
+    this.headingElements = [];
+    this.scrollContainer = null;
+  }
+
+  scrollToSection(event: Event, id: string): void {
+    event.preventDefault();
+
+    const element = document.getElementById(id);
+    if (!element) return;
+
+    // Use native scrollIntoView - most reliable across all containers
+    // Requires CSS scroll-margin-top on target elements for offset
+    element.scrollIntoView({ behavior: 'smooth', block: 'start' });
+
+    // Update active immediately for better UX
+    this.activeId.set(id);
+
+    // Update URL hash while preserving current path
+    const currentPath = window.location.pathname + window.location.search;
+    history.pushState(null, '', `${currentPath}#${id}`);
+  }
+}

package/src/lib/components/organisms/docs-toc/types.ts

@@ -0,0 +1,73 @@
+/**
+ * Configuration for the docs-toc component.
+ */
+export interface DocsTocMetadata {
+  /**
+   * Manual TOC items (used when autoGenerate is false).
+   */
+  items?: DocsTocItem[];
+
+  /**
+   * Automatically generate TOC from headings in the content.
+   * @default false
+   */
+  autoGenerate?: boolean;
+
+  /**
+   * CSS selector for the content container to scan for headings.
+   * Required when autoGenerate is true.
+   * @default '.docs-layout__content'
+   */
+  containerSelector?: string;
+
+  /**
+   * Heading levels to include in auto-generated TOC.
+   * @default [2, 3]
+   */
+  headingLevels?: number[];
+
+  /**
+   * Title displayed above the TOC.
+   * @default 'Contents'
+   */
+  title?: string;
+
+  /**
+   * Offset from top for scroll spy calculations (e.g., for sticky headers).
+   * @default 100
+   */
+  offsetTop?: number;
+
+  /**
+   * Custom CSS class.
+   */
+  cssClass?: string;
+
+  /**
+   * Hide the title.
+   * @default false
+   */
+  hideTitle?: boolean;
+}
+
+export interface DocsTocItem {
+  /**
+   * ID of the DOM element (without #).
+   */
+  id: string;
+
+  /**
+   * Label to display in the TOC.
+   */
+  label: string;
+
+  /**
+   * Heading level for indentation (1, 2, 3).
+   */
+  level: number;
+
+  /**
+   * Nested children items.
+   */
+  children?: DocsTocItem[];
+}

package/src/lib/components/organisms/footer/footer.component.scss

@@ -0,0 +1,3 @@
+.background {
+  background: var(--ion-background-color);
+}

package/src/lib/components/organisms/footer/footer.component.ts

@@ -0,0 +1,65 @@
+import { CommonModule } from '@angular/common';
+import { Component, EventEmitter, Input, OnInit, Output } from '@angular/core';
+import { IonFooter } from '@ionic/angular/standalone';
+import { ToolbarComponent } from '../toolbar/toolbar.component';
+import { FooterMetadata } from './types';
+
+/**
+ * FooterComponent
+ *
+ * Componente de pie de página reutilizable para aplicaciones Ionic/Angular.
+ * Permite mostrar una barra de herramientas (toolbar) y contenido adicional.
+ *
+ * @example
+ * <val-footer [props]="footerProps" (onClick)="handleFooterAction($event)">
+ *   <div extra>Contenido extra</div>
+ * </val-footer>
+ *
+ * @input props {FooterMetadata} - Metadatos del pie de página y su toolbar.
+ * @output onClick - Emite el token de la acción clicada en la toolbar.
+ */
+@Component({
+  selector: 'val-footer',
+  standalone: true,
+  imports: [CommonModule, IonFooter, ToolbarComponent],
+  template: `
+    <ion-footer
+      [class.ion-no-border]="!props.bordered"
+      [translucent]="props.translucent"
+      [class.background]="props.toolbar.color === 'background'"
+    >
+      <val-toolbar
+        *ngIf="props.toolbar.title || props.toolbar.withActions || props.toolbar.withBack"
+        [props]="props.toolbar"
+        (onClick)="clickHandler($event)"
+      ></val-toolbar>
+      <ng-content select="[extra]"></ng-content>
+    </ion-footer>
+  `,
+  styleUrls: ['./footer.component.scss'],
+})
+export class FooterComponent implements OnInit {
+  /**
+   * Metadatos del pie de página y su toolbar.
+   */
+  @Input()
+  props: FooterMetadata;
+
+  /**
+   * Evento emitido al hacer click en una acción de la toolbar.
+   */
+  @Output()
+  onClick = new EventEmitter<string>();
+
+  constructor() {}
+
+  ngOnInit() {}
+
+  /**
+   * Emite el token de la acción clicada en la toolbar.
+   * @param token Token de la acción
+   */
+  clickHandler(token?: string) {
+    this.onClick.emit(token);
+  }
+}