valtech-components 2.0.687 → 2.0.689

package/src/lib/components/molecules/docs-nav-links/docs-nav-links.component.ts

@@ -0,0 +1,216 @@
+import { CommonModule } from '@angular/common';
+import { Component, Input, Output, EventEmitter, inject, computed } from '@angular/core';
+import { IonIcon } from '@ionic/angular/standalone';
+import { addIcons } from 'ionicons';
+import { arrowBackOutline, arrowForwardOutline } from 'ionicons/icons';
+import { DocsNavLinksMetadata } from './types';
+import { DocsNavigationService } from '../../../services/docs/docs-navigation.service';
+import { I18nService } from '../../../services/i18n';
+
+addIcons({ arrowBackOutline, arrowForwardOutline });
+
+/**
+ * val-docs-nav-links
+ *
+ * Navigation links for previous/next page navigation in documentation.
+ *
+ * @example
+ * ```html
+ * <val-docs-nav-links
+ *   [props]="{
+ *     previous: { label: 'Previous', title: 'Getting Started', route: ['/docs', 'getting-started'] },
+ *     next: { label: 'Next', title: 'Components', route: ['/docs', 'components'] }
+ *   }"
+ * ></val-docs-nav-links>
+ * ```
+ */
+@Component({
+  selector: 'val-docs-nav-links',
+  standalone: true,
+  imports: [CommonModule, IonIcon],
+  template: `
+    <nav class="docs-nav-links" [class]="props.cssClass" aria-label="Page navigation">
+      <!-- Previous -->
+      <div
+        class="docs-nav-links__item docs-nav-links__item--prev"
+        [class.docs-nav-links__item--empty]="!props.previous"
+      >
+        @if (props.previous) {
+          <a
+            class="docs-nav-links__link"
+            [href]="getHref(props.previous.route)"
+            (click)="onNavigate($event, props.previous.route)"
+          >
+            <ion-icon name="arrow-back-outline" class="docs-nav-links__icon"></ion-icon>
+            <div class="docs-nav-links__text">
+              <span class="docs-nav-links__label">{{ props.previous.label || previousLabel() }}</span>
+              <span class="docs-nav-links__title">{{ props.previous.title }}</span>
+            </div>
+          </a>
+        }
+      </div>
+
+      <!-- Next -->
+      <div
+        class="docs-nav-links__item docs-nav-links__item--next"
+        [class.docs-nav-links__item--empty]="!props.next"
+      >
+        @if (props.next) {
+          <a
+            class="docs-nav-links__link"
+            [href]="getHref(props.next.route)"
+            (click)="onNavigate($event, props.next.route)"
+          >
+            <div class="docs-nav-links__text">
+              <span class="docs-nav-links__label">{{ props.next.label || nextLabel() }}</span>
+              <span class="docs-nav-links__title">{{ props.next.title }}</span>
+            </div>
+            <ion-icon name="arrow-forward-outline" class="docs-nav-links__icon"></ion-icon>
+          </a>
+        }
+      </div>
+    </nav>
+  `,
+  styles: [`
+    .docs-nav-links {
+      display: flex;
+      gap: 1rem;
+      margin-top: 3rem;
+      padding-top: 2rem;
+      border-top: 1px solid var(--ion-border-color, #e0e0e0);
+    }
+
+    .docs-nav-links__item {
+      flex: 1;
+      min-width: 0;
+    }
+
+    .docs-nav-links__item--empty {
+      visibility: hidden;
+    }
+
+    .docs-nav-links__item--next {
+      text-align: right;
+    }
+
+    .docs-nav-links__item--next .docs-nav-links__link {
+      justify-content: flex-end;
+    }
+
+    .docs-nav-links__item--next .docs-nav-links__text {
+      align-items: flex-end;
+    }
+
+    .docs-nav-links__link {
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+      padding: 1rem;
+      border-radius: 8px;
+      text-decoration: none;
+      color: inherit;
+      transition: all 0.2s ease;
+      border: 1px solid var(--ion-border-color, #e0e0e0);
+    }
+
+    .docs-nav-links__link:hover {
+      background: rgba(0, 0, 0, 0.03);
+      border-color: #1a1a1a;
+    }
+
+    .docs-nav-links__link:hover .docs-nav-links__title {
+      color: #1a1a1a;
+    }
+
+    .docs-nav-links__link:hover .docs-nav-links__icon {
+      color: #1a1a1a;
+    }
+
+    .docs-nav-links__icon {
+      font-size: 1.25rem;
+      color: var(--ion-color-medium, #666);
+      flex-shrink: 0;
+    }
+
+    .docs-nav-links__text {
+      display: flex;
+      flex-direction: column;
+      gap: 0.25rem;
+    }
+
+    .docs-nav-links__label {
+      font-size: 0.75rem;
+      font-weight: 500;
+      text-transform: uppercase;
+      letter-spacing: 0.5px;
+      color: var(--ion-color-medium, #666);
+    }
+
+    .docs-nav-links__title {
+      font-size: 1rem;
+      font-weight: 600;
+      color: var(--ion-text-color, #1a1a1a);
+      transition: color 0.2s ease;
+    }
+
+    /* Mobile responsive */
+    @media (max-width: 600px) {
+      .docs-nav-links {
+        flex-direction: column;
+      }
+
+      .docs-nav-links__item--next {
+        text-align: left;
+      }
+
+      .docs-nav-links__item--next .docs-nav-links__link {
+        justify-content: flex-start;
+        flex-direction: row-reverse;
+      }
+
+      .docs-nav-links__item--next .docs-nav-links__text {
+        align-items: flex-start;
+      }
+    }
+
+    /* Dark mode */
+    :host-context(.dark) .docs-nav-links__link,
+    :host-context([color-scheme='dark']) .docs-nav-links__link {
+      border-color: #3a3a3a;
+    }
+
+    :host-context(.dark) .docs-nav-links__link:hover,
+    :host-context([color-scheme='dark']) .docs-nav-links__link:hover {
+      background: rgba(255, 255, 255, 0.05);
+    }
+
+    :host-context(.dark) .docs-nav-links__title,
+    :host-context([color-scheme='dark']) .docs-nav-links__title {
+      color: #f4f5f8;
+    }
+  `],
+})
+export class DocsNavLinksComponent {
+  @Input() props: DocsNavLinksMetadata = {};
+
+  @Output() navigate = new EventEmitter<string[]>();
+
+  private docsNav = inject(DocsNavigationService);
+  private i18n = inject(I18nService);
+
+  // i18n labels - uses _global namespace from valtech-components defaults
+  previousLabel = computed(() => this.i18n.t('previous') || 'Previous');
+  nextLabel = computed(() => this.i18n.t('next') || 'Next');
+
+  getHref(route: string[]): string {
+    // Handle routes that already start with '/'
+    const path = route.join('/');
+    return path.startsWith('/') ? path : '/' + path;
+  }
+
+  onNavigate(event: Event, route: string[]): void {
+    event.preventDefault();
+    this.navigate.emit(route);
+    this.docsNav.navigateAndScroll(route);
+  }
+}

package/src/lib/components/molecules/docs-nav-links/types.ts

@@ -0,0 +1,36 @@
+/**
+ * Configuration for the docs-nav-links component.
+ */
+export interface DocsNavLinksMetadata {
+  /**
+   * Previous page link.
+   */
+  previous?: DocsNavLink;
+
+  /**
+   * Next page link.
+   */
+  next?: DocsNavLink;
+
+  /**
+   * Custom CSS class.
+   */
+  cssClass?: string;
+}
+
+export interface DocsNavLink {
+  /**
+   * Label (small text, e.g., "Previous", "Next").
+   */
+  label?: string;
+
+  /**
+   * Title (main text, page name).
+   */
+  title: string;
+
+  /**
+   * Route to navigate to.
+   */
+  route: string[];
+}

package/src/lib/components/molecules/docs-search/docs-search.component.scss

@@ -0,0 +1,195 @@
+.docs-search {
+  --search-bg: var(--ion-background-color, #fff);
+  --search-border: var(--ion-border-color, #e0e0e0);
+  --search-text: var(--ion-text-color, #1a1a1a);
+  --search-placeholder: var(--ion-color-medium, #666);
+  --search-hover-bg: rgba(0, 0, 0, 0.03);
+  --search-active-bg: rgba(0, 0, 0, 0.05);
+
+  position: relative;
+  font-family: var(--ion-font-family, system-ui, sans-serif);
+
+  // ==========================================================================
+  // Input wrapper
+  // ==========================================================================
+  &__input-wrapper {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.5rem 0.75rem;
+    background: var(--search-bg);
+    border: 1px solid var(--search-border);
+    border-radius: 8px;
+    transition: all 0.15s ease;
+
+    &:focus-within {
+      border-color: #1a1a1a;
+      box-shadow: 0 0 0 3px rgba(0, 0, 0, 0.05);
+    }
+  }
+
+  &__icon {
+    font-size: 1rem;
+    color: var(--search-placeholder);
+    flex-shrink: 0;
+  }
+
+  &__input {
+    flex: 1;
+    border: none;
+    outline: none;
+    background: transparent;
+    font-size: 0.875rem;
+    color: var(--search-text);
+    min-width: 0;
+
+    &::placeholder {
+      color: var(--search-placeholder);
+    }
+  }
+
+  &__clear {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0.25rem;
+    border: none;
+    background: transparent;
+    color: var(--search-placeholder);
+    cursor: pointer;
+    border-radius: 4px;
+    transition: all 0.15s ease;
+
+    &:hover {
+      background: var(--search-hover-bg);
+      color: var(--search-text);
+    }
+
+    &:focus-visible {
+      outline: 2px solid #1a1a1a;
+      outline-offset: 2px;
+    }
+
+    ion-icon {
+      font-size: 0.875rem;
+    }
+  }
+
+  &__shortcut {
+    font-size: 0.6875rem;
+    font-weight: 500;
+    color: var(--search-placeholder);
+    background: var(--search-hover-bg);
+    padding: 0.125rem 0.375rem;
+    border-radius: 4px;
+    white-space: nowrap;
+  }
+
+  // ==========================================================================
+  // Results dropdown
+  // ==========================================================================
+  &__results {
+    position: absolute;
+    top: calc(100% + 4px);
+    left: 0;
+    right: 0;
+    max-height: 400px;
+    overflow-y: auto;
+    background: var(--search-bg);
+    border: 1px solid var(--search-border);
+    border-radius: 8px;
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.1);
+    z-index: 100;
+  }
+
+  &__result {
+    display: flex;
+    flex-direction: column;
+    gap: 0.125rem;
+    width: 100%;
+    padding: 0.75rem 1rem;
+    border: none;
+    background: transparent;
+    text-align: left;
+    cursor: pointer;
+    transition: background 0.15s ease;
+    border-bottom: 1px solid var(--search-border);
+
+    &:last-child {
+      border-bottom: none;
+    }
+
+    &:hover,
+    &--active {
+      background: var(--search-hover-bg);
+    }
+
+    &:focus-visible {
+      outline: 2px solid #1a1a1a;
+      outline-offset: -2px;
+    }
+  }
+
+  &__result-section {
+    font-size: 0.625rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.5px;
+    color: var(--search-placeholder);
+  }
+
+  &__result-label {
+    font-size: 0.875rem;
+    font-weight: 500;
+    color: var(--search-text);
+  }
+
+  &__result-description {
+    font-size: 0.75rem;
+    color: var(--search-placeholder);
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__no-results {
+    padding: 1.5rem 1rem;
+    text-align: center;
+    font-size: 0.875rem;
+    color: var(--search-placeholder);
+    background: var(--search-bg);
+    border: 1px solid var(--search-border);
+    border-radius: 8px;
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.1);
+    position: absolute;
+    top: calc(100% + 4px);
+    left: 0;
+    right: 0;
+    z-index: 100;
+  }
+}
+
+// ==========================================================================
+// Dark Mode Support
+// ==========================================================================
+:host-context(.dark),
+:host-context([color-scheme='dark']) {
+  .docs-search {
+    --search-bg: #1e1e1e;
+    --search-border: #3a3a3a;
+    --search-text: #f4f5f8;
+    --search-placeholder: #a0a0a0;
+    --search-hover-bg: rgba(255, 255, 255, 0.05);
+    --search-active-bg: rgba(255, 255, 255, 0.08);
+
+    &__input-wrapper:focus-within {
+      border-color: #f4f5f8;
+      box-shadow: 0 0 0 3px rgba(255, 255, 255, 0.05);
+    }
+
+    &__results,
+    &__no-results {
+      box-shadow: 0 4px 16px rgba(0, 0, 0, 0.3);
+    }
+  }
+}

package/src/lib/components/molecules/docs-search/docs-search.component.ts

@@ -0,0 +1,228 @@
+import { CommonModule } from '@angular/common';
+import {
+  Component,
+  Input,
+  Output,
+  EventEmitter,
+  HostListener,
+  signal,
+  computed,
+  ElementRef,
+  ViewChild,
+  OnDestroy,
+} from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { Router } from '@angular/router';
+import { IonIcon } from '@ionic/angular/standalone';
+import { addIcons } from 'ionicons';
+import { searchOutline, closeOutline } from 'ionicons/icons';
+import { Subject } from 'rxjs';
+import { debounceTime, takeUntil } from 'rxjs/operators';
+import { DocsSearchMetadata, DocsSearchResult, DocsSearchItem, DocsSearchSection } from './types';
+
+addIcons({ searchOutline, closeOutline });
+
+/**
+ * val-docs-search
+ *
+ * A search component for documentation with keyboard navigation support.
+ * Supports Cmd+K / Ctrl+K shortcut to open.
+ *
+ * @example
+ * ```html
+ * <val-docs-search
+ *   [props]="{
+ *     placeholder: 'Search docs...',
+ *     sections: sidebarSections,
+ *     showShortcut: true
+ *   }"
+ *   (navigate)="onNavigate($event)"
+ * ></val-docs-search>
+ * ```
+ */
+@Component({
+  selector: 'val-docs-search',
+  standalone: true,
+  imports: [CommonModule, FormsModule, IonIcon],
+  template: `
+    <div class="docs-search" [class]="props.cssClass">
+      <div class="docs-search__input-wrapper">
+        <ion-icon name="search-outline" class="docs-search__icon"></ion-icon>
+        <input
+          #searchInput
+          type="text"
+          class="docs-search__input"
+          [placeholder]="props.placeholder || 'Search...'"
+          [(ngModel)]="searchQuery"
+          (ngModelChange)="onQueryChange($event)"
+          (keydown)="onInputKeydown($event)"
+          (focus)="onFocus()"
+          (blur)="onBlur()"
+          aria-label="Search documentation"
+          autocomplete="off"
+        />
+        @if (searchQuery()) {
+          <button
+            type="button"
+            class="docs-search__clear"
+            (click)="clearSearch()"
+            aria-label="Clear search"
+          >
+            <ion-icon name="close-outline"></ion-icon>
+          </button>
+        } @else if (props.showShortcut) {
+          <span class="docs-search__shortcut">{{ isMac ? '⌘' : 'Ctrl' }}+K</span>
+        }
+      </div>
+
+      @if (showResults() && results().length > 0) {
+        <div class="docs-search__results" role="listbox">
+          @for (result of results(); track result.item.label; let i = $index) {
+            <button
+              type="button"
+              class="docs-search__result"
+              [class.docs-search__result--active]="selectedIndex() === i"
+              role="option"
+              [attr.aria-selected]="selectedIndex() === i"
+              (click)="selectResult(result)"
+              (mouseenter)="selectedIndex.set(i)"
+            >
+              <span class="docs-search__result-section">{{ result.section }}</span>
+              <span class="docs-search__result-label">{{ result.item.label }}</span>
+              @if (result.item.description) {
+                <span class="docs-search__result-description">{{ result.item.description }}</span>
+              }
+            </button>
+          }
+        </div>
+      }
+
+      @if (showResults() && searchQuery() && results().length === 0) {
+        <div class="docs-search__no-results">
+          No results found for "{{ searchQuery() }}"
+        </div>
+      }
+    </div>
+  `,
+  styleUrls: ['./docs-search.component.scss'],
+})
+export class DocsSearchComponent implements OnDestroy {
+  @Input() props: DocsSearchMetadata = {};
+
+  @Output() navigate = new EventEmitter<string[]>();
+  @Output() search = new EventEmitter<string>();
+
+  @ViewChild('searchInput') searchInputEl?: ElementRef<HTMLInputElement>;
+
+  protected searchQuery = signal('');
+  protected showResults = signal(false);
+  protected selectedIndex = signal(0);
+
+  private searchSubject = new Subject<string>();
+  private destroy$ = new Subject<void>();
+
+  readonly isMac = typeof navigator !== 'undefined' && navigator.platform.toLowerCase().includes('mac');
+
+  protected results = computed(() => {
+    const query = this.searchQuery().toLowerCase().trim();
+    if (!query || !this.props.sections) return [];
+
+    const results: DocsSearchResult[] = [];
+
+    this.props.sections.forEach((section: DocsSearchSection) => {
+      section.items.forEach((item: DocsSearchItem) => {
+        // Match label
+        if (item.label.toLowerCase().includes(query)) {
+          results.push({ section: section.title, item, matchType: 'label' });
+          return;
+        }
+        // Match description
+        if (item.description?.toLowerCase().includes(query)) {
+          results.push({ section: section.title, item, matchType: 'description' });
+          return;
+        }
+        // Match keywords
+        if (item.keywords?.some((kw: string) => kw.toLowerCase().includes(query))) {
+          results.push({ section: section.title, item, matchType: 'keyword' });
+        }
+      });
+    });
+
+    return results.slice(0, 10); // Limit results
+  });
+
+  constructor(private router: Router) {
+    this.searchSubject
+      .pipe(debounceTime(this.props.debounceMs || 150), takeUntil(this.destroy$))
+      .subscribe((query) => {
+        this.search.emit(query);
+      });
+  }
+
+  ngOnDestroy(): void {
+    this.destroy$.next();
+    this.destroy$.complete();
+  }
+
+  @HostListener('document:keydown', ['$event'])
+  onGlobalKeydown(event: KeyboardEvent): void {
+    // Cmd+K or Ctrl+K to focus search
+    if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
+      event.preventDefault();
+      this.searchInputEl?.nativeElement.focus();
+    }
+  }
+
+  onQueryChange(query: string): void {
+    this.searchQuery.set(query);
+    this.selectedIndex.set(0);
+    this.searchSubject.next(query);
+  }
+
+  onFocus(): void {
+    this.showResults.set(true);
+  }
+
+  onBlur(): void {
+    // Delay to allow click on results
+    setTimeout(() => this.showResults.set(false), 200);
+  }
+
+  onInputKeydown(event: KeyboardEvent): void {
+    const resultsArray = this.results();
+
+    switch (event.key) {
+      case 'ArrowDown':
+        event.preventDefault();
+        this.selectedIndex.update((i) => Math.min(i + 1, resultsArray.length - 1));
+        break;
+      case 'ArrowUp':
+        event.preventDefault();
+        this.selectedIndex.update((i) => Math.max(i - 1, 0));
+        break;
+      case 'Enter':
+        event.preventDefault();
+        if (resultsArray[this.selectedIndex()]) {
+          this.selectResult(resultsArray[this.selectedIndex()]);
+        }
+        break;
+      case 'Escape':
+        event.preventDefault();
+        this.clearSearch();
+        this.searchInputEl?.nativeElement.blur();
+        break;
+    }
+  }
+
+  selectResult(result: DocsSearchResult): void {
+    this.navigate.emit(result.item.route);
+    this.router.navigate(result.item.route);
+    this.clearSearch();
+  }
+
+  clearSearch(): void {
+    this.searchQuery.set('');
+    this.selectedIndex.set(0);
+    this.showResults.set(false);
+  }
+}

package/src/lib/components/molecules/docs-search/types.ts

@@ -0,0 +1,30 @@
+export interface DocsSearchMetadata {
+  /** Placeholder text for the search input */
+  placeholder?: string;
+  /** Sections to search through */
+  sections?: DocsSearchSection[];
+  /** Debounce time in milliseconds */
+  debounceMs?: number;
+  /** Show keyboard shortcut hint (Cmd+K / Ctrl+K) */
+  showShortcut?: boolean;
+  /** Custom CSS class */
+  cssClass?: string;
+}
+
+export interface DocsSearchSection {
+  title: string;
+  items: DocsSearchItem[];
+}
+
+export interface DocsSearchItem {
+  label: string;
+  route: string[];
+  description?: string;
+  keywords?: string[];
+}
+
+export interface DocsSearchResult {
+  section: string;
+  item: DocsSearchItem;
+  matchType: 'label' | 'description' | 'keyword';
+}