valtech-components 2.0.687 → 2.0.689

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

@@ -0,0 +1,534 @@
+import { Component, Input, computed, signal, AfterViewInit, OnDestroy, ElementRef, inject } from '@angular/core';
+import { CommonModule } from '@angular/common';
+import { Router } from '@angular/router';
+import { DocsBreadcrumbComponent } from '../../molecules/docs-breadcrumb/docs-breadcrumb.component';
+import { DocsBreadcrumbMetadata } from '../../molecules/docs-breadcrumb/types';
+import { DocsNavLinksComponent } from '../../molecules/docs-nav-links/docs-nav-links.component';
+import { DocsNavLinksMetadata } from '../../molecules/docs-nav-links/types';
+import { DocsTocComponent } from '../../organisms/docs-toc/docs-toc.component';
+import { DocsTocMetadata } from '../../organisms/docs-toc/types';
+import { ContentReactionComponent } from '../../molecules/content-reaction/content-reaction.component';
+import { ContentReactionMetadata } from '../../molecules/content-reaction/types';
+import { DocsPageMetadata } from './types';
+
+/**
+ * val-docs-page
+ *
+ * A complete documentation page template that eliminates boilerplate.
+ * Provides automatic TOC generation, navigation links, and consistent styling.
+ *
+ * @example Basic usage
+ * ```html
+ * <val-docs-page [props]="{
+ *   title: 'Button',
+ *   lead: 'A clickable element for user interactions.',
+ *   previousPage: { title: 'Quick Start', route: ['/docs', 'quick-start'] },
+ *   nextPage: { title: 'Card', route: ['/docs', 'components', 'card'] }
+ * }">
+ *   <val-docs-section [props]="{ id: 'basic-usage', title: 'Basic Usage' }">
+ *     <p>Content here...</p>
+ *   </val-docs-section>
+ *
+ *   <val-docs-section [props]="{ id: 'variants', title: 'Variants' }">
+ *     <p>More content...</p>
+ *   </val-docs-section>
+ * </val-docs-page>
+ * ```
+ *
+ * @example With badge
+ * ```html
+ * <val-docs-page [props]="{
+ *   title: 'New Component',
+ *   badge: 'New',
+ *   badgeColor: 'success'
+ * }">
+ *   ...
+ * </val-docs-page>
+ * ```
+ */
+@Component({
+  selector: 'val-docs-page',
+  standalone: true,
+  imports: [CommonModule, DocsBreadcrumbComponent, DocsNavLinksComponent, DocsTocComponent, ContentReactionComponent],
+  template: `
+    <div class="docs-page" [class]="props.cssClass">
+      <div class="docs-page__content" #content>
+        @if (breadcrumbProps()) {
+          <val-docs-breadcrumb [props]="breadcrumbProps()!"></val-docs-breadcrumb>
+        }
+        <header class="docs-page__header">
+          <div class="docs-page__title-row">
+            <h1 class="docs-page__title">{{ props.title }}</h1>
+            @if (props.badge) {
+              <span
+                class="docs-page__badge"
+                [class.docs-page__badge--success]="props.badgeColor === 'success'"
+                [class.docs-page__badge--warning]="props.badgeColor === 'warning'"
+                [class.docs-page__badge--danger]="props.badgeColor === 'danger'"
+              >
+                {{ props.badge }}
+              </span>
+            }
+          </div>
+          @if (props.lead) {
+            <p class="docs-page__lead">{{ props.lead }}</p>
+          }
+        </header>
+
+        <div class="docs-page__sections">
+          <ng-content></ng-content>
+        </div>
+
+        @if (props.feedback?.enabled) {
+          <div class="docs-page__feedback">
+            <val-content-reaction [props]="feedbackProps()"></val-content-reaction>
+          </div>
+        }
+
+        @if (showNavLinks()) {
+          <val-docs-nav-links [props]="navLinksProps()"></val-docs-nav-links>
+        }
+      </div>
+
+      @if (!props.toc?.hide) {
+        <aside class="docs-page__toc">
+          <val-docs-toc [props]="tocProps()"></val-docs-toc>
+        </aside>
+      }
+    </div>
+  `,
+  styles: [`
+    /* Main layout */
+    .docs-page {
+      display: grid;
+      grid-template-columns: 1fr;
+      gap: 2rem;
+      max-width: 1400px;
+      margin: 0 auto;
+      padding: 2rem 1.5rem;
+    }
+
+    @media (min-width: 1200px) {
+      .docs-page {
+        grid-template-columns: 1fr 220px;
+        padding: 2rem;
+      }
+    }
+
+    .docs-page__content {
+      min-width: 0;
+      max-width: 900px;
+    }
+
+    val-docs-breadcrumb {
+      display: block;
+      margin-bottom: 1rem;
+    }
+
+    .docs-page__header {
+      margin-bottom: 2rem;
+    }
+
+    .docs-page__title-row {
+      display: flex;
+      align-items: center;
+      gap: 0.75rem;
+      flex-wrap: wrap;
+    }
+
+    .docs-page__title {
+      margin: 0;
+      font-size: 2rem;
+      font-weight: 700;
+      color: var(--ion-text-color, #1a1a1a);
+      line-height: 1.2;
+    }
+
+    @media (min-width: 768px) {
+      .docs-page__title {
+        font-size: 2.5rem;
+      }
+    }
+
+    .docs-page__badge {
+      display: inline-flex;
+      align-items: center;
+      padding: 0.25rem 0.5rem;
+      font-size: 0.6875rem;
+      font-weight: 500;
+      text-transform: uppercase;
+      letter-spacing: 0.03em;
+      border-radius: 4px;
+      background: rgba(0, 0, 0, 0.04);
+      color: #888;
+    }
+
+    .docs-page__badge--success {
+      background: rgba(0, 0, 0, 0.04);
+      color: #888;
+    }
+
+    .docs-page__badge--warning {
+      background: var(--ion-color-warning-tint, #fff3e0);
+      color: var(--ion-color-warning-shade, #e65100);
+    }
+
+    .docs-page__badge--danger {
+      background: var(--ion-color-danger-tint, #ffebee);
+      color: var(--ion-color-danger-shade, #c62828);
+    }
+
+    .docs-page__lead {
+      margin: 1rem 0 0;
+      font-size: 1.125rem;
+      line-height: 1.7;
+      color: var(--ion-color-medium, #666);
+    }
+
+    .docs-page__sections > *:last-child {
+      margin-bottom: 0;
+    }
+
+    /* Feedback section */
+    .docs-page__feedback {
+      margin-top: 3rem;
+      padding-top: 2rem;
+      border-top: 1px solid rgba(0, 0, 0, 0.08);
+      display: flex;
+      justify-content: center;
+    }
+
+    /* TOC - Hidden on mobile, visible on desktop */
+    .docs-page__toc {
+      display: none;
+    }
+
+    @media (min-width: 1200px) {
+      .docs-page__toc {
+        display: block;
+        position: sticky;
+        top: 2rem;
+        height: fit-content;
+        max-height: calc(100vh - 4rem);
+        overflow-y: auto;
+      }
+    }
+
+    /* Content typography styles */
+    .docs-page__sections h2 {
+      font-size: 1.5rem;
+      font-weight: 600;
+      margin: 0 0 1rem 0;
+      color: var(--ion-text-color, #1a1a1a);
+      scroll-margin-top: 2rem;
+    }
+
+    .docs-page__sections h3 {
+      font-size: 1.125rem;
+      font-weight: 600;
+      margin: 1.5rem 0 1rem 0;
+      color: var(--ion-text-color, #1a1a1a);
+    }
+
+    .docs-page__sections h4 {
+      font-size: 1rem;
+      font-weight: 600;
+      margin: 1.25rem 0 0.75rem 0;
+      color: var(--ion-text-color, #1a1a1a);
+    }
+
+    .docs-page__sections p {
+      line-height: 1.7;
+      color: var(--ion-text-color, #1a1a1a);
+      margin: 0 0 1rem 0;
+    }
+
+    .docs-page__sections ul,
+    .docs-page__sections ol {
+      padding-left: 1.5rem;
+      margin: 0 0 1rem 0;
+    }
+
+    .docs-page__sections li {
+      margin-bottom: 0.5rem;
+      line-height: 1.6;
+      color: var(--ion-text-color, #1a1a1a);
+    }
+
+    .docs-page__sections a {
+      color: var(--ion-color-primary, #3880ff);
+      text-decoration: none;
+    }
+
+    .docs-page__sections a:hover {
+      text-decoration: underline;
+    }
+
+    .docs-page__sections code:not([class*='language-']) {
+      background: rgba(0, 0, 0, 0.06);
+      padding: 0.125rem 0.375rem;
+      border-radius: 4px;
+      font-family: 'SF Mono', 'Fira Code', Consolas, monospace;
+      font-size: 0.875em;
+    }
+
+    .docs-page__sections pre:not([class*='language-']) {
+      background: rgba(0, 0, 0, 0.04);
+      padding: 1rem;
+      border-radius: 8px;
+      overflow-x: auto;
+      margin: 0 0 1rem 0;
+    }
+
+    .docs-page__sections pre:not([class*='language-']) code {
+      background: none;
+      padding: 0;
+    }
+
+    .docs-page__sections table {
+      width: 100%;
+      border-collapse: collapse;
+      margin: 0 0 1rem 0;
+      font-size: 0.875rem;
+    }
+
+    .docs-page__sections th,
+    .docs-page__sections td {
+      padding: 0.75rem;
+      text-align: left;
+      border-bottom: 1px solid rgba(0, 0, 0, 0.1);
+    }
+
+    .docs-page__sections th {
+      font-weight: 600;
+      background: rgba(0, 0, 0, 0.02);
+    }
+
+    .docs-page__sections blockquote {
+      margin: 0 0 1rem 0;
+      padding: 1rem 1.5rem;
+      border-left: 4px solid var(--ion-color-primary, #3880ff);
+      background: rgba(0, 0, 0, 0.02);
+      border-radius: 0 8px 8px 0;
+    }
+
+    .docs-page__sections blockquote p:last-child {
+      margin-bottom: 0;
+    }
+
+    .docs-page__sections img {
+      max-width: 100%;
+      height: auto;
+      border-radius: 8px;
+    }
+
+    .docs-page__sections hr {
+      border: none;
+      border-top: 1px solid rgba(0, 0, 0, 0.1);
+      margin: 2rem 0;
+    }
+
+    .docs-page__sections strong {
+      font-weight: 600;
+    }
+
+    .docs-page__sections section {
+      margin-bottom: 2rem;
+    }
+
+    /* Dark mode */
+    :host-context(.dark) .docs-page__badge,
+    :host-context([color-scheme="dark"]) .docs-page__badge {
+      background: rgba(255, 255, 255, 0.06);
+      color: #999;
+    }
+
+    :host-context(.dark) .docs-page__badge--success,
+    :host-context([color-scheme="dark"]) .docs-page__badge--success {
+      background: rgba(255, 255, 255, 0.06);
+      color: #999;
+    }
+
+    :host-context(.dark) .docs-page__badge--warning,
+    :host-context([color-scheme="dark"]) .docs-page__badge--warning {
+      background: rgba(230, 81, 0, 0.2);
+      color: #ffb74d;
+    }
+
+    :host-context(.dark) .docs-page__badge--danger,
+    :host-context([color-scheme="dark"]) .docs-page__badge--danger {
+      background: rgba(198, 40, 40, 0.2);
+      color: #e57373;
+    }
+
+    :host-context(.dark) .docs-page__sections code:not([class*='language-']),
+    :host-context([color-scheme="dark"]) .docs-page__sections code:not([class*='language-']) {
+      background: rgba(255, 255, 255, 0.1);
+    }
+
+    :host-context(.dark) .docs-page__sections pre:not([class*='language-']),
+    :host-context([color-scheme="dark"]) .docs-page__sections pre:not([class*='language-']) {
+      background: rgba(255, 255, 255, 0.06);
+    }
+
+    :host-context(.dark) .docs-page__sections th,
+    :host-context([color-scheme="dark"]) .docs-page__sections th {
+      background: rgba(255, 255, 255, 0.04);
+    }
+
+    :host-context(.dark) .docs-page__sections th,
+    :host-context(.dark) .docs-page__sections td,
+    :host-context([color-scheme="dark"]) .docs-page__sections th,
+    :host-context([color-scheme="dark"]) .docs-page__sections td {
+      border-color: rgba(255, 255, 255, 0.1);
+    }
+
+    :host-context(.dark) .docs-page__sections blockquote,
+    :host-context([color-scheme="dark"]) .docs-page__sections blockquote {
+      background: rgba(255, 255, 255, 0.04);
+    }
+
+    :host-context(.dark) .docs-page__sections hr,
+    :host-context([color-scheme="dark"]) .docs-page__sections hr {
+      border-color: rgba(255, 255, 255, 0.1);
+    }
+
+    :host-context(.dark) .docs-page__feedback,
+    :host-context([color-scheme="dark"]) .docs-page__feedback {
+      border-color: rgba(255, 255, 255, 0.1);
+    }
+
+    /* Responsive feedback */
+    @media (max-width: 768px) {
+      .docs-page__feedback {
+        margin-top: 2rem;
+        padding-top: 1.5rem;
+      }
+    }
+  `],
+})
+export class DocsPageComponent implements AfterViewInit, OnDestroy {
+  private elementRef = inject(ElementRef);
+  private router = inject(Router);
+
+  // Use signal internally so computed properties react to changes
+  private _props = signal<DocsPageMetadata>({ title: '' });
+
+  @Input()
+  set props(value: DocsPageMetadata) {
+    this._props.set(value);
+  }
+  get props(): DocsPageMetadata {
+    return this._props();
+  }
+
+  private tocItems = signal<{ id: string; label: string; level: number }[]>([]);
+  private observer: MutationObserver | null = null;
+
+  ngAfterViewInit(): void {
+    // Initial scan
+    this.scanForSections();
+
+    // Watch for dynamic content changes
+    this.observer = new MutationObserver(() => {
+      this.scanForSections();
+    });
+
+    const contentEl = this.elementRef.nativeElement.querySelector('.docs-page__sections');
+    if (contentEl) {
+      this.observer.observe(contentEl, { childList: true, subtree: true });
+    }
+  }
+
+  ngOnDestroy(): void {
+    this.observer?.disconnect();
+  }
+
+  private scanForSections(): void {
+    const contentEl = this.elementRef.nativeElement.querySelector('.docs-page__sections');
+    if (!contentEl) return;
+
+    const headings = contentEl.querySelectorAll('h2[id], h3[id], section[id] > h2, section[id] > h3');
+    const items: { id: string; label: string; level: number }[] = [];
+
+    headings.forEach((heading: Element) => {
+      // Get ID from heading or parent section
+      let id = heading.id;
+      if (!id && heading.parentElement?.tagName === 'SECTION') {
+        id = heading.parentElement.id;
+      }
+
+      if (id) {
+        const level = heading.tagName === 'H2' ? 2 : 3;
+        items.push({ id, label: heading.textContent?.trim() || '', level });
+      }
+    });
+
+    this.tocItems.set(items);
+  }
+
+  tocProps = computed<DocsTocMetadata>(() => {
+    const props = this._props();
+    return {
+      title: props.toc?.title ?? 'On this page',
+      items: this.tocItems(),
+    };
+  });
+
+  navLinksProps = computed<DocsNavLinksMetadata>(() => {
+    const props = this._props();
+    return {
+      previous: props.previousPage
+        ? {
+            // Don't pass label - let DocsNavLinksComponent use its internal i18n-reactive labels
+            title: props.previousPage.title,
+            route: props.previousPage.route,
+          }
+        : undefined,
+      next: props.nextPage
+        ? {
+            // Don't pass label - let DocsNavLinksComponent use its internal i18n-reactive labels
+            title: props.nextPage.title,
+            route: props.nextPage.route,
+          }
+        : undefined,
+    };
+  });
+
+  showNavLinks = computed(() => {
+    const props = this._props();
+    return !!props.previousPage || !!props.nextPage;
+  });
+
+  breadcrumbProps = computed<DocsBreadcrumbMetadata | null>(() => {
+    const props = this._props();
+    if (!props.breadcrumb?.items?.length) {
+      return null;
+    }
+    return {
+      items: props.breadcrumb.items,
+      showHome: props.breadcrumb.showHome ?? true,
+      homeRoute: props.breadcrumb.homeRoute ?? ['/'],
+    };
+  });
+
+  feedbackProps = computed<ContentReactionMetadata>(() => {
+    const props = this._props();
+    const feedback = props.feedback;
+
+    // Derive entityId from route if not provided
+    const entityId =
+      feedback?.entityId || this.router.url.replace(/^\//, '').replace(/\//g, '-') || 'unknown';
+
+    return {
+      entityRef: {
+        entityType: feedback?.entityType || 'docs-page',
+        entityId: entityId,
+      },
+      question: feedback?.question,
+      showComment: feedback?.showComment ?? true,
+      allowAnonymous: feedback?.allowAnonymous ?? true,
+      showThankYou: true,
+    };
+  });
+}

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

@@ -0,0 +1,141 @@
+import { DocsBreadcrumbItem } from '../../molecules/docs-breadcrumb/types';
+
+/**
+ * Configuration for the docs-page component.
+ */
+export interface DocsPageMetadata {
+  /**
+   * Page title displayed as h1.
+   */
+  title: string;
+
+  /**
+   * Breadcrumb navigation items.
+   * When provided, shows breadcrumb above the title.
+   */
+  breadcrumb?: {
+    /** Breadcrumb items (last item is current page) */
+    items: DocsBreadcrumbItem[];
+    /** Show home icon at start @default true */
+    showHome?: boolean;
+    /** Custom home route @default ['/'] */
+    homeRoute?: string[];
+  };
+
+  /**
+   * Lead paragraph below the title.
+   */
+  lead?: string;
+
+  /**
+   * Optional badge displayed next to title (e.g., "New", "Updated", "Beta").
+   */
+  badge?: string;
+
+  /**
+   * Badge color variant.
+   * @default 'default'
+   */
+  badgeColor?: 'default' | 'success' | 'warning' | 'danger';
+
+  /**
+   * Previous page for navigation.
+   */
+  previousPage?: DocsPageLink;
+
+  /**
+   * Next page for navigation.
+   */
+  nextPage?: DocsPageLink;
+
+  /**
+   * i18n labels for navigation.
+   */
+  navLabels?: {
+    previous?: string;
+    next?: string;
+  };
+
+  /**
+   * TOC configuration.
+   */
+  toc?: {
+    /**
+     * TOC title.
+     * @default 'On this page'
+     */
+    title?: string;
+
+    /**
+     * Hide the TOC.
+     * @default false
+     */
+    hide?: boolean;
+  };
+
+  /**
+   * Custom CSS class.
+   */
+  cssClass?: string;
+
+  /**
+   * Feedback/reaction widget configuration.
+   * When enabled, shows a "Was this page helpful?" reaction widget.
+   */
+  feedback?: DocsPageFeedbackConfig;
+}
+
+/**
+ * Configuration for the feedback reaction widget.
+ */
+export interface DocsPageFeedbackConfig {
+  /**
+   * Enable the feedback widget.
+   */
+  enabled: boolean;
+
+  /**
+   * Entity type for categorizing feedback.
+   * @default 'docs-page'
+   */
+  entityType?: string;
+
+  /**
+   * Entity ID for this page. If not provided, derives from current route.
+   * @example 'components-button', 'guides-theming'
+   */
+  entityId?: string;
+
+  /**
+   * Custom question text. If not provided, uses i18n default.
+   * @example '¿Te resultó útil esta página?'
+   */
+  question?: string;
+
+  /**
+   * Allow anonymous (unauthenticated) feedback.
+   * @default true
+   */
+  allowAnonymous?: boolean;
+
+  /**
+   * Show optional comment field after reaction.
+   * @default true
+   */
+  showComment?: boolean;
+}
+
+/**
+ * Link to another documentation page.
+ */
+export interface DocsPageLink {
+  /**
+   * Display title for the link.
+   */
+  title: string;
+
+  /**
+   * Route array for navigation.
+   */
+  route: string[];
+}